feat: support component-local streaming boundaries

[Mohamed Mansour (mohamedmansour)]

Why

Applications should be able to keep component ownership intact while still choosing meaningful SSR readiness points. A page such as <ntp-page> can remain the single entry shell for CSR, while an internal SearchBox becomes interactive as soon as its complete HTML is available instead of waiting for the entire page component and response tail.

A boundary must also map to a real transport write. Committing SearchBox should return SearchBox and its checkpoint only; following parent or tail markup must not be bundled into that host write or require an artificial sibling boundary.

Streaming model

<boundary> is a compile-time directive authored in an entry or reusable component template. It emits no application DOM wrapper.

A boundary-owning subtree may be reached through normal server-rendered selection:

• a true <if> branch produces its occurrence; a false branch produces none
• an active route or outlet path produces its occurrences; inactive routes produce none
• a <for> body cannot directly or transitively reach a boundary

A complete finite <for> may be wrapped by one outer boundary and rendered as one atomic region. Boundaries before and after a repeat are also valid. This avoids retaining repeat iterators across host calls and keeps occurrence identity finite and predictable.

At runtime, rendering discovers boundary occurrences in document order. Each occurrence has:

{ instanceId, declarationId, owner, name, key }

• owner and name identify the declaration.
• instanceId identifies one occurrence in one response.
• key distinguishes a component-owned declaration reached from multiple static callsites.

Host flow

Every host uses the same pull-style state machine:

start(state) -> StreamStep
resume(instanceId, state, mode) -> StreamStep
advance() -> StreamStep
update(instanceId, patch) -> bytes

A StreamStep contains emitted bytes, a done flag, and the next optional descriptor:

Step state	Required action
boundary present, done == false	Call resume for that occurrence
no boundary, done == false	The boundary was committed; write its bytes, then call advance
done == true	Write the final bytes; the document and terminal are complete

start renders the parent prefix and stops before the first boundary. resume renders only the pending boundary through its checkpoint and returns immediately. advance renders the following parent/shell bytes until the next boundary or terminal.

This guarantees:

start()             -> pre-SearchBox shell write
resume(searchBox)   -> SearchBox-only checkpoint write
advance()           -> following parent/tail write or next boundary

No sibling boundary is needed merely to force SearchBox into its own response write. An updatable occurrence may receive update after resume and before advance while the response remains open.

Rust, Node, npm, WASM, Python, C FFI, .NET, and the CLI control stream expose this same logical contract. The CLI automatically writes the boundary step and advance step separately while keeping backend controls at start, resume, and update.

Component-local hydration

When rendering suspends inside a reusable component, WebUI generates a temporary component span around the unfinished parent. A compiler-marked child boundary may hydrate through exactly that parent barrier while unrelated descendants remain deferred.

When the parent closes, a span-completion record hydrates the parent and remaining descendants exactly once. An already active child is not rehydrated and newer boundary updates are not overwritten. The same ownership rules apply in light DOM and declarative shadow DOM.

Parent continuation state is projected and frozen once. Boundary resume state overlays only newly resolved values, with resolution order:

1. lexical locals
2. resume state
3. frozen parent state

Updatable occurrences retain only their successfully activated roots. update applies a projected shallow state patch and never inserts markup or reruns hydration.

Previous model vs current model

Previous model	Current model
Boundaries existed only in the entry template	Reusable components may own their readiness boundary
The complete boundary list and IDs were fixed before rendering	Occurrence IDs are discovered from the selected render path in document order
A reusable page component streamed as one atomic region	A complete internal child can hydrate before its parent tail
A boundary write could include following parent/tail bytes	resume is boundary-only; advance owns following bytes
Hosts resolved names, then called shell, ordered boundary writes, and finish	Hosts consume explicit prefix, boundary, continuation, and update steps

Authored boundaries cannot nest directly or transitively, and repeat bodies cannot reach them. Generated component spans are the only supported ancestor mechanism.

Performance and bounds

The continuation VM uses integer fragment slots, lock-free per-entry plans, persistent projection scratch, one frozen state snapshot per response, and no resumable repeat iterator. Valid browser commits use root-local marker ranges and never scan the document.

Measured release-mode server costs are:

Boundaries	Render time
1	2.57 us
3	4.58 us
10	11.05 us
100	98.3 us

The always-shipped framework entry is 60,528 bytes minified / 18,993 bytes gzip. Opting into streaming adds 16,652 bytes minified / 5,928 bytes gzip. Absolute ordinary and incremental bundle gates retain 4.2-4.7% headroom.

Continuation depth, occurrence count, static keys, open spans, retained roots, marker scans, records, and cleanup work are explicitly bounded. Malformed or truncated streams fail closed and release discoverable deferred state.

Validation

• cargo xtask check
• Parser, protocol, handler, and host state-machine suites
• Framework unit tests: 272 passed
• Streaming Playwright: 18 passed
• Real Node HTTP test proving boundary and continuation bytes are written separately
• Browser hydration, heap, update, and bundle matrices
• Node, WASM, npm, Python, C FFI, and .NET streaming suites
• Criterion server benchmarks across 1, 3, 10, and 100 boundaries

[Copilot]

Pull request overview

Adds runtime-discovered, component-local streaming boundaries across the WebUI stack so hosts can flush and hydrate meaningful readiness points (including inside reusable components) without requiring sibling boundaries, via a unified start / resume / advance / update step machine.

Changes:

• Replaces compile-time boundary name tables with runtime-discovered boundary descriptors and a pull-style streaming step API across Node/WASM/Python/.NET/FFI/docs/examples.
• Introduces component span completion + ancestor-barrier bypass support in the framework streaming coordinator to enable child hydration ahead of unfinished parent tails.
• Evolves the protocol schema to inline boundary declarations (start/end tape) and adds build-time contains_boundary to avoid render-time graph walking.

Reviewed changes

Copilot reviewed 58 out of 132 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
packages/webui/src/index.ts	Node host API: StreamingSession now returns StreamStep with optional BoundaryDescriptor.
packages/webui/README.md	Updates Node API documentation to the new step machine.
packages/webui-framework/src/template-element.ts	Adds ancestor-barrier activation status + bypass support for component spans.
packages/webui-framework/src/streaming-protocol.ts	Bumps browser streaming protocol to v2; adds span completion record + new bootstrap fields.
packages/webui-framework/src/streaming-dom.ts	Adds span marker support + shared marker resolution helpers.
packages/webui-framework/src/streaming-cleanup.ts	Extends failure cleanup to remove span markers/scaffolding and strip all streaming attrs.
examples/app/streaming/*	Refactors the demo to component-owned boundaries (<streaming-page>) and updates tests/docs.
examples/app/service-worker/*	Migrates WASM handler usage from callback streaming to host-driven streamResponse() steps.
dotnet/test/Microsoft.WebUI.Tests/*	Updates streaming fixtures/tests and enables multitargeting net8/net9.
crates/webui-protocol/proto/webui.proto	Schema update: inline boundaries + contains_boundary; removes name tables.
crates/webui-parser/src/plugin/webui.rs	Strips <boundary> directive tags from component metadata templates.
crates/webui-handler/*	Implements runtime-discovered streaming, component spans, and host-owned step APIs.
docs/guide/*	Syncs integration + CLI + concept docs to the new streaming contract.

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.