@microsoft/webui-framework 0.0.27 → 0.0.28

package/README.md

@@ -269,8 +269,8 @@ activation. The coordinator does not publish that state to
 scaffolding after commit. Updates apply state to retained roots and never insert
 markup or rerun hydration.
 
-The browser reads version-2
-`[2, sequence, kind, target, payload]` records for final checkpoints,
+The browser reads the single unversioned
+`[sequence, kind, target, payload]` contract for final checkpoints,
 updatable checkpoints, updates, span completions, and terminal. Every commit
 also emits a `performance.mark()` - `webui:boundary:<id>`,
 `webui:boundary:<id>:update`, `webui:span:<id>`, or
@@ -278,6 +278,12 @@ also emits a `performance.mark()` - `webui:boundary:<id>`,
 Set `window.__WEBUI_STREAMING_DEBUG__ = true` only when tooling needs the live
 `webui:boundary-hydrated` event as well.
 
+A range record can reuse the exact preceding range state with `stateRef` and
+carry only a top-level `stateDelta`. References are backward-only and resolved
+before activation; missing, stale, forward, or malformed references halt and
+clean up the stream. The reference base is released on terminal, cancellation,
+failure, or coordinator reset.
+
 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

package/dist/streaming-bootstrap.js

@@ -12,6 +12,8 @@ export function applyBoundaryBootstrap(bootstrap) {
         const key = keys[i];
         if (key === 'templates' ||
             key === 'state' ||
+            key === 'stateRef' ||
+            key === 'stateDelta' ||
             key === 'componentStyles' ||
             key === 'declarationId' ||
             key === 'enclosingSpanInstanceId')

package/dist/streaming-coordinator.js

@@ -6,6 +6,7 @@ import { abandonPendingWaiters, configureStreamingFailureHandler, elementHasPend
 import { findBoundaryScript, findRangeEndMarkerByPrefix, findRangeStartMarkerByPrefix, markerlessRecordViolation, removeBoundaryScaffolding, resolveBoundaryRange, resolveSpanRange, streamingErrorMessage, } from './streaming-dom.js';
 import { parseBoundaryEnvelope, RECORD_KIND_FINAL_CHECKPOINT, RECORD_KIND_SPAN_COMPLETION, RECORD_KIND_STATE_UPDATE, RECORD_KIND_TERMINAL, RECORD_KIND_UPDATABLE_CHECKPOINT, } from './streaming-protocol.js';
 import { applyStateUpdate } from './streaming-state.js';
+import { clearRangeState, resolveRangeState, } from './streaming-record-state.js';
 import { abandonOpenSpans, completeSpan, hasOpenSpans, openSpanCountForTests, prepareSpanCompletion, registerEnclosingSpans, spanHostFor, } from './streaming-spans.js';
 const MAX_QUEUED_BOUNDARIES = 512;
 const MAX_UPDATABLE_BOUNDARIES = 128;
@@ -110,6 +111,7 @@ function fail(reason) {
     abandonPendingWaiters();
     abandonOpenSpans();
     clearUpdatableBoundaries();
+    clearRangeState();
     settlePendingTerminal(false);
     for (let i = queueHead; i < queue.length; i++) {
         discardRejectedBoundary(queue[i]);
@@ -151,7 +153,7 @@ function processSentinel(sentinel) {
         failBoundary(sentinel, parsed.reason);
         return;
     }
-    const [, sequence, kind, target, payload] = parsed.envelope;
+    const [sequence, kind, target, payload] = parsed.envelope;
     if (sequence !== nextExpectedRecordSequence) {
         failBoundary(sentinel, `expected streaming record sequence ${nextExpectedRecordSequence}, received ${sequence}`);
         return;
@@ -213,11 +215,12 @@ function commitRecord(span, payload, range, sequence, target, updatable, sentine
     markBoundaryPending();
     let committed = false;
     try {
+        const state = resolveRangeState(payload, sequence);
         if (span) {
-            hydrateSpanCompletion(payload, range, target);
+            hydrateSpanCompletion(payload, state, range, target);
         }
         else {
-            hydrateCheckpoint(payload, range, target, updatable);
+            hydrateCheckpoint(payload, state, range, target, updatable);
         }
         committed = true;
     }
@@ -235,7 +238,7 @@ function commitRecord(span, payload, range, sequence, target, updatable, sentine
         markBoundaryCommitted(false);
     }
 }
-function hydrateCheckpoint(bootstrap, range, target, updatable) {
+function hydrateCheckpoint(bootstrap, state, range, target, updatable) {
     let bypass;
     const enclosing = bootstrap.enclosingSpanInstanceId;
     if (enclosing !== undefined && range.start?.parentNode) {
@@ -251,7 +254,7 @@ function hydrateCheckpoint(bootstrap, range, target, updatable) {
         const boundary = updatable
             ? newUpdatableBoundary()
             : undefined;
-        activateRootsBetween(range.start, range.end, bootstrap.state, boundary, bypass);
+        activateRootsBetween(range.start, range.end, state, boundary, bypass);
         if (boundary)
             retainUpdatableBoundary(target, boundary);
     }
@@ -262,12 +265,12 @@ function hydrateCheckpoint(bootstrap, range, target, updatable) {
 function newUpdatableBoundary() {
     return { roots: [], active: true, retained: 0, pendingRoots: 0 };
 }
-function hydrateSpanCompletion(payload, range, target) {
+function hydrateSpanCompletion(payload, state, range, target) {
     const invalid = prepareSpanCompletion(target, range);
     if (invalid)
         throw new Error(invalid);
     applyBoundaryBootstrap(payload);
-    activateRootsBetween(range.start, range.end, payload.state);
+    activateRootsBetween(range.start, range.end, state);
     completeSpan(target);
 }
 function failRangeResolution(sentinel, scriptEl, resolved) {
@@ -321,6 +324,7 @@ function commitTerminal(sequence, sentinel, scriptEl) {
     removeBoundaryScaffolding(sentinel, scriptEl, null, null);
     terminalCommitted = true;
     pendingTerminalSequence = sequence;
+    clearRangeState();
     clearUpdatableBoundaries(true);
     scheduleTerminalValidation();
 }
@@ -403,6 +407,7 @@ export function resetStreamingCoordinatorStateForTests() {
     abandonOpenSpans();
     settlePendingTerminal(false);
     clearUpdatableBoundaries();
+    clearRangeState();
     coordinatorGeneration++;
     queue.length = 0;
     queueHead = 0;

package/dist/streaming-protocol.d.ts

@@ -1,10 +1,11 @@
 import type { TemplateMeta } from './template.js';
 import type { ComponentStyles } from './element/styles.js';
-export declare const STREAMING_PROTOCOL_VERSION = 2;
 export interface BoundaryBootstrap {
     declarationId: number;
     enclosingSpanInstanceId?: number;
     state?: Record<string, unknown>;
+    stateRef?: number;
+    stateDelta?: Record<string, unknown>;
     templates?: Record<string, TemplateMeta>;
     inventory?: string;
     nonce?: string;
@@ -22,6 +23,8 @@ export declare const RECORD_KIND_TERMINAL = 4;
 export type BoundaryRecordKind = typeof RECORD_KIND_FINAL_CHECKPOINT | typeof RECORD_KIND_UPDATABLE_CHECKPOINT | typeof RECORD_KIND_STATE_UPDATE | typeof RECORD_KIND_SPAN_COMPLETION | typeof RECORD_KIND_TERMINAL;
 export interface SpanCompletionPayload {
     state?: Record<string, unknown>;
+    stateRef?: number;
+    stateDelta?: Record<string, unknown>;
     templates?: Record<string, TemplateMeta>;
     inventory?: string;
     nonce?: string;
@@ -32,7 +35,6 @@ export interface SpanCompletionPayload {
 }
 export type BoundaryRecordPayload = BoundaryBootstrap | SpanCompletionPayload | Record<string, unknown>;
 export type BoundaryEnvelope = readonly [
-    version: number,
     recordSequence: number,
     kind: BoundaryRecordKind,
     target: number,

package/dist/streaming-protocol.js

@@ -1,4 +1,3 @@
-export const STREAMING_PROTOCOL_VERSION = 2;
 export const RECORD_KIND_FINAL_CHECKPOINT = 0;
 export const RECORD_KIND_UPDATABLE_CHECKPOINT = 1;
 export const RECORD_KIND_STATE_UPDATE = 2;
@@ -15,11 +14,8 @@ export function parseBoundaryEnvelope(text) {
     catch {
         return invalid('boundary payload is not valid JSON');
     }
-    if (!Array.isArray(parsed) || parsed.length !== 5) {
-        return invalid('boundary envelope must be a 5-element [version, recordSequence, kind, target, payload] array');
-    }
-    if (parsed[0] !== STREAMING_PROTOCOL_VERSION) {
-        return invalid(`unsupported boundary envelope version ${JSON.stringify(parsed[0])}`);
+    if (!Array.isArray(parsed) || parsed.length !== 4) {
+        return invalid('boundary envelope must be a 4-element [recordSequence, kind, target, payload] array');
     }
     return {
         ok: true,

package/dist/streaming-record-state.d.ts

@@ -0,0 +1,6 @@
+import type { BoundaryBootstrap, SpanCompletionPayload } from './streaming-protocol.js';
+type RangePayload = BoundaryBootstrap | SpanCompletionPayload;
+type StreamedState = Record<string, unknown> | undefined;
+export declare function resolveRangeState(payload: RangePayload, sequence: number): StreamedState;
+export declare function clearRangeState(): void;
+export {};

package/dist/streaming-record-state.js

@@ -0,0 +1,54 @@
+let lastRangeSequence;
+let lastRangeState;
+export function resolveRangeState(payload, sequence) {
+    const reference = payload.stateRef;
+    if (reference === undefined) {
+        if (payload.stateDelta !== undefined) {
+            throw new Error('streaming state delta is missing its stateRef');
+        }
+        const state = payload.state;
+        if (state !== undefined && !isStateObject(state)) {
+            throw new Error('streaming range state must be an object');
+        }
+        lastRangeSequence = sequence;
+        lastRangeState = cloneState(state);
+        return state;
+    }
+    if (!Number.isSafeInteger(reference) ||
+        reference < 0 ||
+        reference >= sequence) {
+        throw new Error(`invalid streaming state reference ${String(reference)}`);
+    }
+    if (payload.state !== undefined) {
+        throw new Error('referenced streaming state must not include complete state');
+    }
+    if (lastRangeSequence === undefined || reference !== lastRangeSequence) {
+        throw new Error(`streaming state reference ${reference} does not match prior range record ${lastRangeSequence === undefined ? 'none' : lastRangeSequence}`);
+    }
+    const delta = payload.stateDelta;
+    if (delta !== undefined && !isStateObject(delta)) {
+        throw new Error('streaming state delta must be an object');
+    }
+    const state = mergeStateDelta(lastRangeState, delta);
+    lastRangeSequence = sequence;
+    lastRangeState = state;
+    return cloneState(state);
+}
+export function clearRangeState() {
+    lastRangeSequence = undefined;
+    lastRangeState = undefined;
+}
+function isStateObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function mergeStateDelta(base, delta) {
+    if (delta === undefined || Object.keys(delta).length === 0)
+        return base;
+    if (base === undefined) {
+        throw new Error('streaming state delta references missing base state');
+    }
+    return { ...base, ...delta };
+}
+function cloneState(state) {
+    return state === undefined ? undefined : structuredClone(state);
+}

package/package.json

@@ -1,6 +1,9 @@
 {
   "name": "@microsoft/webui-framework",
-  "version": "0.0.27",
+  "version": "0.0.28",
+  "publishConfig": {
+    "tag": "latest"
+  },
   "type": "module",
   "description": "WebUI Framework Next — Preact-inspired lightweight Web Component runtime with SSR hydration and compiled-template path mapping.",
   "license": "MIT",
@@ -43,7 +46,7 @@
     "@playwright/test": "^1.61.1",
     "@types/node": "^26.1.0",
     "typescript": "7.0.2",
-    "@microsoft/webui-test-support": "0.0.27"
+    "@microsoft/webui-test-support": "0.0.28"
   },
   "scripts": {
     "build": "tsc",