@microsoft/webui-framework 0.0.18 → 0.0.20

package/README.md

@@ -87,16 +87,21 @@ Build with `--dom=shadow` (default) to wrap in a declarative shadow root, or `--
 <counter-card label="Taps"></counter-card>
 ```
 
-### HTML-only components
+### HTML-only dormant components
 
 If a component has no event handlers, custom lifecycle code, or client-only
 methods, it can ship only `component.html` and optional `component.css`.
 
-When HTML-only components receive server or route state, import
-`@microsoft/webui-framework` somewhere in the browser entry. The framework root
-installs the static host runtime, which only claims compiler-owned HTML-only
-components whose templates need hidden state or observed host attributes. Fully
-static HTML-only components stay as plain SSR DOM.
+The sibling `.ts` or `.js` file is the authored behavior boundary. With
+manifest-enabled projection, only `@observable` and `@attr` fields opt into
+initial state hydration; template-only roots stay in the trusted SSR DOM.
+Without a module, template bindings render on the server and the component
+contributes no projected keys. Without projection metadata, the server
+preserves full state. The compiler still emits template metadata for scriptless
+components. When the framework is loaded, it can activate that template when
+browser state or client-side creation needs it.
+If that first write omits a repeat collection, the host preserves the existing
+SSR items until the collection is explicitly supplied.
 
 Create a custom element only for an Interactive Island: event handlers, custom
 lifecycle code, imperative methods, or state that TypeScript code reads or
@@ -111,9 +116,45 @@ cargo run -p microsoft-webui-cli -- build ./src --out ./dist --plugin=webui
 
 The WebUI plugin prepares component templates for the browser. Bundle your
 source browser entry directly. Import `@microsoft/webui-framework` from authored
-component modules, or once from the browser entry when the app has no authored
-components but still uses HTML-only components that receive server or route
-state.
+component modules. An app that stays static after SSR needs no framework
+browser import. Import the framework once when HTML-only components must accept
+browser state or participate in soft navigation.
+
+The plugin alone preserves full server state. To emit exact `@observable` and
+`@attr` state surfaces, run the application's bundler first with
+`@microsoft/webui/projection.js`, then pass its manifest to `webui build` with
+`--projection-manifest`. The manifest tooling is build-only; this runtime
+package does not depend on esbuild or TypeScript.
+
+### Progressive streaming hydration
+
+Streaming applications opt into a separate side-effect entry:
+
+```ts
+import '@microsoft/webui-framework/streaming.js';
+import './counter-card.js';
+```
+
+Import it before component registration modules and load the application entry
+early with `<script type="module" async>` in `<head>`. The server must render
+authored `<boundary>` directives through
+`WebUIHandler::render_streaming`. The default
+`@microsoft/webui-framework` entry has no dependency on the coordinator, so
+normal applications pay no streaming bundle or initialization cost.
+
+Each committed boundary receives its own ephemeral state object directly during
+activation. The coordinator does not publish that state to
+`window.__webui.state`, and it removes generated checkpoint scaffolding after
+commit. Every commit also emits a `performance.mark()` — `webui:boundary:<id>`,
+`webui:boundary:<id>:update`, or `webui:streaming:terminal` — which needs no
+flag and no listener, so tooling that loads after hydration can still read it.
+Set `window.__WEBUI_STREAMING_DEBUG__ = true` only when tooling needs the live
+`webui:boundary-hydrated` event as well.
+
+Set `window.__WEBUI_STREAMING_SLICE_MS__` to a positive millisecond budget to
+make the coordinator yield between boundaries instead of draining its queue in
+one pass. That is for pages where an intermediary coalesces the response into a
+single chunk; it costs total hydration time, so leave it unset otherwise.
 
 ### Property binding lifecycle
 
@@ -134,12 +175,27 @@ re-render it. An `@observable` written before hydration finishes — in a field
 initializer, the `constructor`, or before `super.connectedCallback()` — cannot
 update that DOM, so the write is dropped and the runtime logs a
 `[WebUI] Hydration mismatch` warning naming the properties. Seed such values in
-the SSR state, or assign them after `super.connectedCallback()`. The warning is
+the SSR state, or assign them from `hydratedCallback()`. The warning is
 development-only and is dead-code-eliminated from production bundles via the
 `__WEBUI_DEV__` compile-time flag (on by default; `webui-press build` sets it to
 `false`). See the
 [Interactivity Guide](https://microsoft.github.io/webui/guide/concepts/interactivity#setting-observable-state-during-setup).
 
+Override the protected `hydratedCallback()` hook for work that requires the
+component's bindings, events, and `w-ref` references to be ready. It runs
+synchronously exactly once after the first successful ordinary SSR hydration,
+client-created mount, deferred streamed activation, or dormant static-host wake.
+Its once-latch is set before author code runs, so a thrown callback is not
+retried on reconnect.
+
+`connectedCallback()` remains a native per-connection lifecycle. On ordinary
+SSR and client-created mounts, `super.connectedCallback()` hydrates
+synchronously, but a streamed `data-ws` root returns while still deferred and
+hydrates only when its boundary commits. Therefore `connectedCallback()` cannot
+be used as a universal post-hydration signal. Descendants must not structurally
+mutate a containing component's SSR subtree before it hydrates, because
+hydration relies on stable compiled paths.
+
 ### DOM strategy (`--dom`)
 
 The `--dom` flag controls how the server renders component content:
@@ -168,6 +224,7 @@ Base class for framework components.
 | Member | Purpose |
 |--------|---------|
 | `static define(tagName)` | Register the class as a custom element |
+| `protected hydratedCallback()` | Run once after the first successful hydration or client mount |
 | `$emit(name, detail?)` | Dispatch a bubbling, composed `CustomEvent` |
 | `$update()` | Force a reactive update (normally called automatically) |
 | `disconnectedCallback()` | Override for cleanup (global listeners, etc.) |
@@ -240,6 +297,7 @@ Notes:
 
 - default attribute names use kebab-case
 - attribute values arrive as strings
+- during SSR hydration, an existing host attribute wins over projected state
 - use `@observable` for state that client code reads or mutates
 
 ### `@volatile`
@@ -269,7 +327,8 @@ The WebUI plugin supports these template features:
 - repeats: `<for each="item in items">`
 
 Components that use `@event` must have authored `.ts` or `.js` code that
-defines a `WebUIElement` for the tag; HTML-only components are declarative only.
+defines a `WebUIElement` for the tag. HTML-only components do not provide
+application event handlers.
 
 Example from `examples/app/todo-webui`:
 
@@ -302,8 +361,10 @@ Root-level events (e.g. `@toggle-item="{onToggleItem(e)}"`) can be declared on t
 - Use `w-ref` for true DOM-only concerns like focus or reading input values.
 - Omit `@observable` for values that are only read by the template and seeded
   externally after construction.
-- Omit the TypeScript class for HTML-only components that only need template
-  bindings and router/server state.
+- Omit the TypeScript class when compiled template behavior is sufficient,
+  including browser-applied state, route updates, and client-created instances.
+  Add a same-named module only for authored events, lifecycle, decorators, or
+  imperative APIs.
 
 Avoid imperative DOM mutation for application state that can be represented by reactive properties.
 
@@ -338,9 +399,9 @@ resource-constrained devices.
 
 5. **Single-pass hydration via path mapping.**
    SSR DOM is matched to compiled template bindings through
-   template-parallel traversal (`$resolveSSR`).  No marker comments, no
-   data attributes — just path-based node resolution.  The hydration walk
-   touches each DOM node exactly once.
+   template-parallel traversal (`$resolveSSR`). Ordinary buffered hydration
+   needs no marker comments or data attributes for binding resolution. The
+   hydration walk touches each DOM node exactly once.
 
 6. **Keep the framework out of the GC's way.**
    Fewer JS objects = fewer GC pauses.  Binding arrays are pre-built at
@@ -402,7 +463,10 @@ Angular all require a JavaScript runtime on the server.  This framework's SSR
 is driven by data (template metadata + state values), not code.  Any language
 that can read the compiled metadata and produce HTML can serve as the SSR
 backend.  No comment markers or data attributes are needed — the runtime
-resolves SSR DOM nodes via template-parallel path traversal.
+resolves ordinary buffered SSR nodes via template-parallel path traversal.
+Progressive streaming uses temporary checkpoint scaffolding only to delay
+activation until a complete region arrives; it removes that scaffolding after
+commit.
 
 ### Build → Serve → Hydrate → Update
 
@@ -437,7 +501,7 @@ flowchart LR
 graph TD
     EL["element.ts (~850 lines)<br/><i>Orchestrator</i><br/>$mount, $wire, $hydrate,<br/>$resolveSSR, $applySSRState,<br/>$update, events, cleanup"]
 
-    DIFF["element/diff.ts (~130 lines)<br/><i>List Reconciliation</i><br/>keyed/sequential diffing<br/>for @for repeat blocks"]
+    DIFF["element/diff.ts<br/><i>List Reconciliation</i><br/>positional + explicit-key diffing<br/>for &lt;for&gt; repeat blocks"]
 
     COND["element/conditions.ts<br/><i>Condition Evaluation</i><br/>evaluateCondition (iterative),<br/>conditionUsesPath"]
 
@@ -468,8 +532,8 @@ When the server renders a component, it emits HTML content (as a declarative
 shadow root or as light DOM children) along with an inert `#webui-data`
 JSON payload.  The browser parses this DOM before any JavaScript runs.
 When the component's JS loads and `connectedCallback` fires, the framework
-uses compiled template paths to resolve SSR DOM nodes without any marker
-comments or data attributes:
+uses compiled template paths to resolve ordinary buffered SSR DOM nodes without
+binding markers:
 
 ```mermaid
 sequenceDiagram
@@ -484,11 +548,12 @@ sequenceDiagram
     CE->>CE: attributeChangedCallback (pre-existing attrs)
     CE->>FW: connectedCallback() → $mount()
     FW->>FW: SSR DOM detected (shadow root or children exist)
-    FW->>FW: $applySSRState() — seed decorated + template state
+    FW->>FW: $applySSRState() — seed decorated state
     FW->>FW: $hydrate() — template-parallel path resolution
     FW->>FW: $resolveSSR() — match SSR nodes via ordinal traversal
     FW->>FW: $wireEvents() + $wireRefs()
     FW->>FW: $buildPathIndex(), $ready = true
+    FW->>CE: hydratedCallback() (once)
     Note over FW: DOM is already correct from SSR.<br/>No $update() call needed.
 ```
 
@@ -513,6 +578,7 @@ sequenceDiagram
     FW->>FW: $wireEvents() + $wireRefs()
     FW->>FW: $buildPathIndex(), $ready = true
     FW->>FW: $update() — flush initial property values
+    FW->>CE: hydratedCallback() (once)
 ```
 
 ---
@@ -538,7 +604,8 @@ interface TemplateMeta {
   sa?: string;                         // Adopted stylesheet specifier
   sd?: boolean;                        // Shadow DOM flag for client-created
   re?: [event, handler, argSpecs][];    // Root-level events
-  th?: 1;                               // Compiler-owned static host
+  tr?: string[];                       // Template state roots
+  ta?: string[];                       // Host attributes aligned with tr
 }
 ```
 
@@ -635,61 +702,53 @@ sees `42` in the DOM before the component's JavaScript state exists. Without
 seeding, the first `$update()` would overwrite the SSR content with the wrong
 value.
 
-State seeding uses `window.__webui.state` — a JSON object loaded from the
-server-emitted `#webui-data` block.  Like Preact's props, this delivers the
-same data used for SSR rendering to the client. During `$mount()`,
-`$applySSRState()` writes matching decorated keys directly to observable backing
-fields and stores undecorated template roots in hidden framework state before
-any bindings are wired:
+State seeding uses `window.__webui.state` loaded from the server-emitted
+`#webui-data` block. When the protocol contains projection metadata, only
+`@observable` and `@attr` keys from reachable authored components select
+initial state; HTML-only dormant components and authored template-only roots
+contribute no startup keys. Without projection metadata, the server preserves
+full state. During `$mount()`, `$applySSRState()` writes matching decorated keys
+directly to observable backing fields before any bindings are wired:
 
 ```mermaid
 flowchart LR
-    SCRIPT["&lt;script type='application/json' id='webui-data'&gt;<br/>{ state: { count: 42, title: 'Hello' } }"] --> APPLY["$applySSRState()"]
-    APPLY --> SEED["Write decorated fields + hidden template state"]
+    SCRIPT["&lt;script type='application/json' id='webui-data'&gt;<br/>{ state: { count: 42 } }"] --> APPLY["$applySSRState()"]
+    APPLY --> SEED["Write decorated backing fields"]
     SEED --> HYDRATE["$hydrate() — bindings match<br/>server-rendered DOM"]
 ```
 
-`$applySSRState()` only accepts keys that are decorated properties or compiled
-template roots. Unknown keys are ignored. Decorated writes go to the backing
-field (`_prop`) directly, and undecorated template roots stay internal, avoiding
-reactive updates before bindings are wired.
+Decorated writes go to the backing field (`_prop`) directly, avoiding reactive
+updates before bindings are wired. For `@attr`, an existing SSR host attribute
+takes precedence and the projected value is skipped. Template-only values
+remain represented by the SSR DOM until browser state explicitly changes them.
+Later `setState()` calls, including router partials, accept both decorated
+properties and compiled template roots; undecorated roots are stored in hidden
+framework state. The first write to a dormant HTML-only host replays only the
+roots present in that write, preserving omitted SSR text, attributes,
+conditions, and repeats.
 
 ---
 
 ## Repeat Reconciliation
 
-`@for(item of items)` blocks support two reconciliation strategies,
-implemented in `element/diff.ts` (~130 lines):
-
-### Keyed Reconciliation
-
-When the repeat block's root element has attribute bindings (e.g.
-`<todo-item id="{{item.id}}">`), the framework uses the first attribute as a
-key.  This preserves DOM nodes across reorders:
-
-```mermaid
-flowchart TD
-    subgraph Before ["Before: items = [A, B, C]"]
-        A1["&lt;todo-item&gt; key=A"]
-        B1["&lt;todo-item&gt; key=B"]
-        C1["&lt;todo-item&gt; key=C"]
-    end
-
-    subgraph After ["After: items = [C, A]"]
-        C2["&lt;todo-item&gt; key=C ← reused"]
-        A2["&lt;todo-item&gt; key=A ← reused"]
-        B2["key=B ← removed"]
-    end
-
-    A1 -.->|"moved"| A2
-    C1 -.->|"moved"| C2
-    B1 -.->|"destroyed"| B2
-```
-
-### Sequential Reconciliation
-
-When no keying attributes exist, items are matched by position.  Excess items
-are removed; new items are appended.
+`<for>` blocks reconcile by array position by default. The existing block at
+index `i` receives the current item at index `i`; only a new or removed tail
+creates or removes blocks.
+
+Duplicate values and attributes are safe because dynamic attributes never act
+as hidden keys. Reordering rebinds existing blocks in place, so local
+browser-owned or component state remains associated with positions rather than
+logical items.
+
+For reorderable or stateful lists, author `key="{{item.id}}"` on the first
+child inside `<for>` to move existing blocks with their logical items.
+`key="{{item}}"` supports arrays of unique string or finite-number primitives.
+`key` is compiler-only metadata and is removed from SSR and client HTML;
+`data-key` remains an ordinary attribute with no identity semantics. Key paths
+are compiler-validated and stored only for explicitly keyed repeats, so
+unkeyed bindings carry no key state or map allocation. Duplicate or invalid
+runtime keys warn once, clear identity, and use positional reconciliation until
+valid identity is re-established.
 
 ### SSR State Reading
 
@@ -719,10 +778,11 @@ stylesheet specifier for a component.
 
 ## Path-Based Binding Resolution
 
-Unlike frameworks that use comment markers or data attributes to locate
-dynamic content, this framework uses **compiled template paths** — arrays of
+Unlike frameworks that use comment markers or data attributes to locate each
+dynamic binding, this framework uses **compiled template paths** — arrays of
 child-node indices that describe exactly where each binding lives in the DOM
-tree.
+tree. Progressive streaming's temporary boundary markers locate complete
+activation regions, not individual bindings.
 
 ### Client-created resolution (`$resolve`)
 
@@ -763,7 +823,7 @@ This template-parallel traversal eliminates the need for any marker comments,
 | Initial hydration | O(bindings) | Single pass over compiled path mappings |
 | Reactive update | O(affected) | Per-path index skips unrelated bindings |
 | Conditional toggle | O(block size) | Create/destroy a block instance |
-| Repeat reconciliation | O(items) | Keyed map lookup or sequential scan |
+| Repeat reconciliation | O(items) | Positional scan; explicit keys use a reusable map only when order changes |
 | Event wiring | O(events) | One-time during hydration |
 
 ### What the framework does NOT do

package/dist/decorators.d.ts

@@ -1,6 +1,7 @@
 export declare function toKebabCase(str: string): string;
 export declare function getObservableNames(ctor: Function): Set<string>;
 export declare function isAttributeProperty(ctor: Function, property: string): boolean;
+export declare function attributeNameForProperty(ctor: Function, property: string): string | undefined;
 export declare function syncAttrProperties(instance: object, ctor: Function): void;
 export declare function observable(target: object, name: string): void;
 export interface AttrOptions {

package/dist/decorators.js

@@ -94,6 +94,9 @@ function attrPropertyMapFor(ctor) {
 export function isAttributeProperty(ctor, property) {
     return attrPropertyMapFor(ctor)?.has(property) === true;
 }
+export function attributeNameForProperty(ctor, property) {
+    return attrPropertyMapFor(ctor)?.get(property)?.attribute;
+}
 function setReflectingAttribute(instance, attrName) {
     instance[reflectingAttribute] = attrName;
 }

package/dist/element/diff.d.ts

@@ -1,3 +1,5 @@
-import type { RepeatBinding, RepeatHost } from './types.js';
+import type { RepeatBinding, RepeatHost, RepeatKeyState } from './types.js';
 export declare function dotWalk(cursor: unknown, path: string, from: number): unknown;
+export declare function createRepeatKeyState(path: string): RepeatKeyState;
+export declare function seedHydratedRepeatKeys(rep: RepeatBinding, items: unknown[]): void;
 export declare function syncRepeat(host: RepeatHost, rep: RepeatBinding): void;