@microsoft/webui-framework 0.0.19 → 0.0.20

package/README.md

@@ -126,6 +126,36 @@ The plugin alone preserves full server state. To emit exact `@observable` and
 `--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
 
 Property bindings use the `:` prefix to pass values directly to child DOM properties:
@@ -145,18 +175,26 @@ 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).
 
-`super.connectedCallback()` is the synchronous hydration boundary for an
-authored component. When it returns, bindings, events, and `w-ref` references
-are wired. Use a parser-inserted, non-async ES module script or a classic
-`defer` script. A blocking classic script must follow every SSR instance it may
-upgrade. Descendants must not structurally mutate a containing component's SSR
-subtree before it hydrates, because hydration relies on stable compiled paths.
+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`)
 
@@ -186,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.) |
@@ -360,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
@@ -424,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
 
@@ -490,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
@@ -511,6 +553,7 @@ sequenceDiagram
     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.
 ```
 
@@ -535,6 +578,7 @@ sequenceDiagram
     FW->>FW: $wireEvents() + $wireRefs()
     FW->>FW: $buildPathIndex(), $ready = true
     FW->>FW: $update() — flush initial property values
+    FW->>CE: hydratedCallback() (once)
 ```
 
 ---
@@ -734,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`)
 

package/dist/element.d.ts

@@ -8,14 +8,10 @@ export declare class WebUIElement extends TemplateElement {
     $emit(name: string, detail?: unknown): boolean;
     protected $finalize(instance: TemplateInstance, root: Node, meta: TemplateBlockMeta, resolver: (root: Node, path: TemplateNodePath) => Node | null, scope?: ScopeFrame): void;
     private $wireEvents;
-    private $resolveDelegatedEvents;
     private $wireRoot;
-    private $addDelegatedEvent;
-    private $dispatchDelegatedEvent;
     private $addEvent;
     private $addCleanup;
     private $callEventHandler;
-    private $callEventHandlerWithCurrentTarget;
     private $resolveEventArgs;
     private $resolveEventArg;
     private $wireRefs;

package/dist/element.js

@@ -29,32 +29,16 @@ export class WebUIElement extends TemplateElement {
         const groups = meta.eg;
         if (!groups)
             return;
-        const delegateTarget = this.shadowRoot ?? this;
         for (let i = 0; i < groups.length; i++) {
             const [eventName, bindings] = groups[i];
-            const bucket = this.$resolveDelegatedEvents(root, bindings, resolver, scope);
-            this.$addDelegatedEvent(instance, delegateTarget, eventName, bucket);
-        }
-    }
-    $resolveDelegatedEvents(root, bindings, resolver, scope) {
-        const entries = [];
-        for (let i = 0; i < bindings.length; i++) {
-            const [handlerName, args, target, usesEvent] = bindings[i];
-            const el = resolver(root, target);
-            if (!el || el.nodeType !== 1)
-                continue;
-            const method = this[handlerName];
-            if (typeof method !== 'function')
-                continue;
-            entries.push({
-                target: el,
-                method: method,
-                args,
-                usesEvent: usesEvent === 1,
-                scope,
-            });
+            for (let j = 0; j < bindings.length; j++) {
+                const [handlerName, args, target] = bindings[j];
+                const el = resolver(root, target);
+                if (el && el.nodeType === 1) {
+                    this.$addEvent(instance, el, eventName, handlerName, args, scope);
+                }
+            }
         }
-        return entries;
     }
     $wireRoot(instance, re) {
         const target = this.shadowRoot ?? this;
@@ -62,27 +46,6 @@ export class WebUIElement extends TemplateElement {
             this.$addEvent(instance, target, re[i][0], re[i][1], re[i][2], undefined);
         }
     }
-    $addDelegatedEvent(instance, target, eventName, entries) {
-        if (entries.length === 0)
-            return;
-        const listener = (event) => {
-            this.$dispatchDelegatedEvent(entries, event);
-        };
-        target.addEventListener(eventName, listener);
-        this.$addCleanup(instance, () => target.removeEventListener(eventName, listener));
-    }
-    $dispatchDelegatedEvent(entries, event) {
-        let current = event.target;
-        while (current) {
-            for (let i = 0; i < entries.length; i++) {
-                const entry = entries[i];
-                if (entry.target === current) {
-                    this.$callEventHandler(entry.method, entry.args, event, entry.scope, entry.target, entry.usesEvent);
-                }
-            }
-            current = current.parentNode;
-        }
-    }
     $addEvent(instance, target, eventName, handlerName, args, scope) {
         const method = this[handlerName];
         if (typeof method !== 'function')
@@ -94,11 +57,7 @@ export class WebUIElement extends TemplateElement {
     $addCleanup(instance, cleanup) {
         (instance.cleanups ??= []).push(cleanup);
     }
-    $callEventHandler(method, args, event, scope, currentTarget, usesEvent = false) {
-        if (currentTarget && usesEvent) {
-            this.$callEventHandlerWithCurrentTarget(method, args, event, scope, currentTarget);
-            return;
-        }
+    $callEventHandler(method, args, event, scope) {
         switch (args.length) {
             case 0:
                 method.call(this);
@@ -119,24 +78,6 @@ export class WebUIElement extends TemplateElement {
                 method.apply(this, this.$resolveEventArgs(args, event, scope));
         }
     }
-    $callEventHandlerWithCurrentTarget(method, args, event, scope, currentTarget) {
-        const descriptor = Object.getOwnPropertyDescriptor(event, 'currentTarget');
-        Object.defineProperty(event, 'currentTarget', {
-            configurable: true,
-            value: currentTarget,
-        });
-        try {
-            this.$callEventHandler(method, args, event, scope);
-        }
-        finally {
-            if (descriptor) {
-                Object.defineProperty(event, 'currentTarget', descriptor);
-            }
-            else {
-                delete event.currentTarget;
-            }
-        }
-    }
     $resolveEventArgs(args, event, scope) {
         const resolved = [];
         for (let i = 0; i < args.length; i++) {

package/dist/lifecycle.d.ts

@@ -1,2 +1,19 @@
 export declare function hydrationStart(): void;
 export declare function hydrationEnd(): void;
+export declare function beginStreamingGate(): void;
+export declare function abortStreamingGate(): void;
+export declare function markBoundaryPending(): void;
+export declare function markBoundaryCommitted(terminal: boolean): void;
+export declare function markLateActivationPending(): void;
+export declare function settleLateActivation(): void;
+export declare function __getLifecycleStateForTests(): {
+    pendingCount: number;
+    started: boolean;
+    completed: boolean;
+    streamingGateActive: boolean;
+    streamingGateAborted: boolean;
+    terminalReached: boolean;
+    pendingBoundaries: number;
+    pendingLateActivations: number;
+};
+export declare function __resetLifecycleForTests(): void;

package/dist/lifecycle.js

@@ -1,6 +1,11 @@
 let pendingCount = 0;
 let started = false;
 let completed = false;
+let streamingGateActive = false;
+let terminalReached = false;
+let streamingGateAborted = false;
+let pendingBoundaries = 0;
+let pendingLateActivations = 0;
 export function hydrationStart() {
     if (!started) {
         performance.mark('webui:hydrate:total:start');
@@ -9,11 +14,69 @@ export function hydrationStart() {
     pendingCount++;
 }
 export function hydrationEnd() {
+    if (pendingCount === 0)
+        return;
     pendingCount--;
-    if (pendingCount <= 0 && !completed) {
-        completed = true;
+    tryComplete();
+}
+export function beginStreamingGate() {
+    streamingGateActive = true;
+}
+export function abortStreamingGate() {
+    streamingGateAborted = true;
+}
+export function markBoundaryPending() {
+    pendingBoundaries++;
+}
+export function markBoundaryCommitted(terminal) {
+    if (pendingBoundaries === 0)
+        return;
+    pendingBoundaries--;
+    if (terminal)
+        terminalReached = true;
+    tryComplete();
+}
+export function markLateActivationPending() {
+    pendingLateActivations++;
+}
+export function settleLateActivation() {
+    if (pendingLateActivations === 0)
+        return;
+    pendingLateActivations--;
+    tryComplete();
+}
+function tryComplete() {
+    if (completed || streamingGateAborted || pendingCount !== 0)
+        return;
+    if (streamingGateActive &&
+        (!terminalReached || pendingBoundaries !== 0 || pendingLateActivations !== 0))
+        return;
+    completed = true;
+    if (started) {
         performance.mark('webui:hydrate:total:end');
         performance.measure('webui:hydrate:total', 'webui:hydrate:total:start', 'webui:hydrate:total:end');
-        window.dispatchEvent(new Event('webui:hydration-complete'));
     }
+    window.dispatchEvent(new Event('webui:hydration-complete'));
+}
+export function __getLifecycleStateForTests() {
+    return {
+        pendingCount,
+        started,
+        completed,
+        streamingGateActive,
+        streamingGateAborted,
+        terminalReached,
+        pendingBoundaries,
+        pendingLateActivations,
+    };
+}
+export function __resetLifecycleForTests() {
+    pendingCount = 0;
+    started = false;
+    completed = false;
+    streamingGateActive = false;
+    streamingGateAborted = false;
+    terminalReached = false;
+    pendingBoundaries = 0;
+    pendingLateActivations = 0;
 }

package/dist/static-host.js

@@ -22,6 +22,9 @@ function defineTemplateHost(tag, meta) {
         $shouldApplySSRBootstrapState() {
             return false;
         }
+        $shouldActivateOnBoundaryCommit() {
+            return false;
+        }
     }
     StaticTemplateHost.define(tag);
 }
@@ -58,9 +61,8 @@ export function installTemplateElementRuntime() {
             return;
         defineTemplateHosts(detail.templates);
     });
+    defineTemplateHosts();
     if (document.readyState === 'loading') {
         document.addEventListener('DOMContentLoaded', () => defineTemplateHosts(), { once: true });
-        return;
     }
-    defineTemplateHosts();
 }

package/dist/streaming-activation.d.ts

@@ -0,0 +1,2 @@
+import type { PendingBoundaryUpdates } from './streaming-deferred.js';
+export declare function activateRootsBetween(startMarker: Comment, endMarker: Comment, state: Record<string, unknown> | undefined, updates?: PendingBoundaryUpdates): void;

package/dist/streaming-activation.js

@@ -0,0 +1,13 @@
+import { abandonDeferredRange, } from './streaming-cleanup.js';
+import { activateDeferredTree, } from './streaming-deferred.js';
+export function activateRootsBetween(startMarker, endMarker, state, updates) {
+    const root = startMarker.parentNode;
+    if (!root) {
+        throw new Error('boundary start marker was detached before activation');
+    }
+    const failure = activateDeferredTree(startMarker.nextSibling, root, endMarker, state, updates ? { updates, retainedRoots: updates.roots } : undefined);
+    if (!failure)
+        return;
+    abandonDeferredRange(startMarker, endMarker);
+    throw new Error(failure);
+}

package/dist/streaming-bootstrap.d.ts

@@ -0,0 +1,2 @@
+import type { BoundaryBootstrap } from './streaming-protocol.js';
+export declare function applyBoundaryBootstrap(bootstrap: BoundaryBootstrap): void;

package/dist/streaming-bootstrap.js

@@ -0,0 +1,48 @@
+import { registerTemplateData } from './template.js';
+export function applyBoundaryBootstrap(bootstrap) {
+    if (bootstrap.templates)
+        registerTemplateData(bootstrap.templates);
+    const w = window;
+    if (!w.__webui)
+        w.__webui = {};
+    const keys = Object.keys(bootstrap);
+    for (let i = 0; i < keys.length; i++) {
+        const key = keys[i];
+        if (key === 'templates' || key === 'state')
+            continue;
+        if (key === 'inventory') {
+            w.__webui.inventory = mergeInventory(w.__webui.inventory, bootstrap.inventory);
+            continue;
+        }
+        if (key === 'css' || key === 'styles') {
+            appendUniqueStrings(w.__webui, key, bootstrap[key]);
+            continue;
+        }
+        w.__webui[key] = bootstrap[key];
+    }
+}
+function mergeInventory(existing, delta) {
+    const current = typeof existing === 'string' ? existing : '';
+    const next = delta ?? '';
+    const length = Math.max(current.length, next.length);
+    let merged = '';
+    for (let i = 0; i < length; i++) {
+        const a = i < current.length ? parseInt(current[i], 16) : 0;
+        const b = i < next.length ? parseInt(next[i], 16) : 0;
+        merged += (a | b).toString(16);
+    }
+    return merged;
+}
+function appendUniqueStrings(target, key, delta) {
+    if (!delta)
+        return;
+    const existing = target[key];
+    const cumulative = Array.isArray(existing) ? existing : [];
+    for (let i = 0; i < delta.length; i++) {
+        if (cumulative.indexOf(delta[i]) === -1) {
+            cumulative.push(delta[i]);
+        }
+    }
+    if (cumulative !== existing)
+        target[key] = cumulative;
+}

package/dist/streaming-cleanup.d.ts

@@ -0,0 +1,4 @@
+export declare function abandonDeferredElement(el: Element): void;
+export declare function abandonDeferredDescendants(root: Element): void;
+export declare function abandonDeferredRange(startMarker: Comment, endMarker: Node): void;
+export declare function abandonDeferredDocumentRoots(): void;

package/dist/streaming-cleanup.js

@@ -0,0 +1,66 @@
+import { firstNodeWithin, MAX_MARKER_SCAN_NODES, nextWithinRoot, safeRemoveAttribute, streamingErrorMessage, } from './streaming-dom.js';
+import { STREAMED_HOST_ATTR } from './streaming-mode.js';
+const STREAMING_BOUNDARY_ABANDON = Symbol.for('microsoft.webui.boundaryAbandon');
+export function abandonDeferredElement(el) {
+    try {
+        if (!el.hasAttribute(STREAMED_HOST_ATTR))
+            return;
+    }
+    catch {
+        safeRemoveAttribute(el, STREAMED_HOST_ATTR);
+        return;
+    }
+    try {
+        const hook = el[STREAMING_BOUNDARY_ABANDON];
+        if (typeof hook === 'function')
+            hook.call(el);
+    }
+    catch (error) {
+        console.error(`[WebUI] streaming: abandon failed for <${el.tagName?.toLowerCase?.() ?? '?'}>: ${streamingErrorMessage(error)}`);
+    }
+    finally {
+        safeRemoveAttribute(el, STREAMED_HOST_ATTR);
+    }
+}
+export function abandonDeferredDescendants(root) {
+    abandonDeferredNodes(firstNodeWithin(root), root, null);
+}
+export function abandonDeferredRange(startMarker, endMarker) {
+    const root = startMarker.parentNode;
+    if (root) {
+        abandonDeferredNodes(startMarker.nextSibling, root, endMarker);
+    }
+}
+function abandonDeferredNodes(first, root, end) {
+    let node = first;
+    let visited = 0;
+    while (node && node !== end && visited < MAX_MARKER_SCAN_NODES) {
+        visited++;
+        if (node.nodeType === 1) {
+            abandonDeferredElement(node);
+        }
+        node = nextWithinRoot(node, root);
+    }
+}
+export function abandonDeferredDocumentRoots() {
+    if (typeof document === 'undefined' ||
+        typeof document.getElementsByTagName !== 'function') {
+        return;
+    }
+    const elements = document.getElementsByTagName('*');
+    let visited = 0;
+    for (let i = 0; i < elements.length && visited < MAX_MARKER_SCAN_NODES; i++) {
+        const el = elements[i];
+        visited++;
+        abandonDeferredElement(el);
+        const shadowRoot = el.shadowRoot;
+        let node = shadowRoot?.firstChild ?? null;
+        while (node && visited < MAX_MARKER_SCAN_NODES) {
+            visited++;
+            if (node.nodeType === 1) {
+                abandonDeferredElement(node);
+            }
+            node = nextWithinRoot(node, shadowRoot);
+        }
+    }
+}

package/dist/streaming-coordinator.d.ts

@@ -0,0 +1,7 @@
+import { elementHasPendingStateForTests, pendingTagWaiterCountForTests, pendingUndefinedRootCountForTests } from './streaming-deferred.js';
+export declare function enqueueStreamingSentinel(sentinel: Element): void;
+export declare function installStreamingTruncationGuard(): void;
+export declare function resetStreamingCoordinatorStateForTests(): void;
+export declare function isStreamingHaltedForTests(): boolean;
+export declare function streamingRetentionStateForTests(): readonly [number, number];
+export { elementHasPendingStateForTests, pendingTagWaiterCountForTests, pendingUndefinedRootCountForTests, };