@microsoft/webui-framework 0.0.25 → 0.0.26

package/dist/streaming-coordinator.js

@@ -2,10 +2,11 @@ import { abortStreamingGate, markBoundaryCommitted, markBoundaryPending, } from
 import { activateRootsBetween, } from './streaming-activation.js';
 import { applyBoundaryBootstrap } from './streaming-bootstrap.js';
 import { abandonDeferredDocumentRoots, abandonDeferredRange, } from './streaming-cleanup.js';
-import { abandonPendingWaiters, configureStreamingFailureHandler, elementHasPendingStateForTests, pendingTagWaiterCountForTests, pendingUndefinedRootCountForTests, resetDeferredActivationForTests, } from './streaming-deferred.js';
-import { findBoundaryScript, findEndMarkerByPrefix, findStartMarkerByPrefix, removeBoundaryScaffolding, resolveBoundaryRange, streamingErrorMessage, } from './streaming-dom.js';
-import { parseBoundaryEnvelope, RECORD_KIND_STATE_UPDATE, RECORD_KIND_TERMINAL, RECORD_KIND_UPDATABLE_CHECKPOINT, } from './streaming-protocol.js';
+import { abandonPendingWaiters, configureStreamingFailureHandler, elementHasPendingStateForTests, pendingBarrierRootCountForTests, pendingTagWaiterCountForTests, pendingUndefinedRootCountForTests, resetDeferredActivationForTests, } from './streaming-deferred.js';
+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 { abandonOpenSpans, completeSpan, hasOpenSpans, openSpanCountForTests, prepareSpanCompletion, registerEnclosingSpans, spanHostFor, } from './streaming-spans.js';
 const MAX_QUEUED_BOUNDARIES = 512;
 const MAX_UPDATABLE_BOUNDARIES = 128;
 const MAX_RETAINED_UPDATE_ROOTS = 50_000;
@@ -13,6 +14,7 @@ const BOUNDARY_HYDRATED_EVENT = 'webui:boundary-hydrated';
 const BOUNDARY_MARK_PREFIX = 'webui:boundary:';
 const UPDATE_MARK_SUFFIX = ':update';
 const TERMINAL_MARK = 'webui:streaming:terminal';
+const SPAN_MARK_PREFIX = 'webui:span:';
 const perf = globalThis.performance;
 const queue = [];
 let queueHead = 0;
@@ -20,7 +22,7 @@ let pumpScheduled = false;
 let slicedDrainActive = false;
 let halted = false;
 let nextExpectedRecordSequence = 0;
-let nextExpectedBoundaryId = 0;
+let nextExpectedBoundaryInstanceId = 0;
 let terminalCommitted = false;
 let pendingTerminalSequence = null;
 let terminalValidationScheduled = false;
@@ -106,6 +108,7 @@ function fail(reason) {
     console.error(`[WebUI] streaming hydration halted: ${reason}.`);
     abortStreamingGate();
     abandonPendingWaiters();
+    abandonOpenSpans();
     clearUpdatableBoundaries();
     settlePendingTerminal(false);
     for (let i = queueHead; i < queue.length; i++) {
@@ -124,9 +127,9 @@ function discardRejectedBoundary(sentinel) {
     let endMarker = null;
     let startMarker = null;
     if (scriptEl) {
-        endMarker = findEndMarkerByPrefix(scriptEl);
+        endMarker = findRangeEndMarkerByPrefix(scriptEl);
         if (endMarker)
-            startMarker = findStartMarkerByPrefix(endMarker);
+            startMarker = findRangeStartMarkerByPrefix(endMarker);
     }
     if (startMarker && endMarker) {
         abandonDeferredRange(startMarker, endMarker);
@@ -153,7 +156,22 @@ function processSentinel(sentinel) {
         failBoundary(sentinel, `expected streaming record sequence ${nextExpectedRecordSequence}, received ${sequence}`);
         return;
     }
-    if (kind === RECORD_KIND_STATE_UPDATE) {
+    if (kind === RECORD_KIND_STATE_UPDATE || kind === RECORD_KIND_TERMINAL) {
+        const terminal = kind === RECORD_KIND_TERMINAL;
+        const violation = markerlessRecordViolation(scriptEl, terminal ? 'terminal' : 'state update');
+        if (violation) {
+            failBoundary(sentinel, violation);
+            return;
+        }
+        if (terminal) {
+            if (hasOpenSpans()) {
+                failBoundary(sentinel, 'terminal record arrived before every component span completed');
+                return;
+            }
+            nextExpectedRecordSequence++;
+            commitTerminal(sequence, sentinel, scriptEl);
+            return;
+        }
         const boundary = updatableBoundaries.get(target);
         if (!boundary) {
             failBoundary(sentinel, `state update targets boundary ${target}, which is not committed as updatable`);
@@ -163,71 +181,105 @@ function processSentinel(sentinel) {
         commitStateUpdate(boundary, payload, target, sequence, sentinel, scriptEl);
         return;
     }
-    if (kind === RECORD_KIND_TERMINAL) {
-        const resolved = resolveBoundaryRange(scriptEl, 0, true);
+    if (kind === RECORD_KIND_SPAN_COMPLETION) {
+        const resolved = resolveSpanRange(scriptEl, target);
         if (!resolved.ok) {
-            failBoundary(sentinel, resolved.reason);
+            failRangeResolution(sentinel, scriptEl, resolved);
             return;
         }
         nextExpectedRecordSequence++;
-        commitTerminal(sequence, sentinel, scriptEl);
+        commitRecord(true, payload, resolved.range, sequence, target, false, sentinel, scriptEl);
         return;
     }
-    if (target !== nextExpectedBoundaryId) {
-        failBoundary(sentinel, `expected boundary ID ${nextExpectedBoundaryId}, received ${target}`);
+    if (kind !== RECORD_KIND_FINAL_CHECKPOINT &&
+        kind !== RECORD_KIND_UPDATABLE_CHECKPOINT) {
+        failBoundary(sentinel, `unsupported streaming record kind ${kind}`);
         return;
     }
-    const resolved = resolveBoundaryRange(scriptEl, target, false);
+    if (target !== nextExpectedBoundaryInstanceId) {
+        failBoundary(sentinel, `expected boundary instance ${nextExpectedBoundaryInstanceId}, received ${target}`);
+        return;
+    }
+    const resolved = resolveBoundaryRange(scriptEl, target);
     if (!resolved.ok) {
-        if (resolved.truncated) {
-            if (resolved.start) {
-                abandonDeferredRange(resolved.start, scriptEl);
-            }
-            removeBoundaryScaffolding(sentinel, scriptEl, resolved.start, null);
-            fail(resolved.reason);
-        }
-        else {
-            failBoundary(sentinel, resolved.reason);
-        }
+        failRangeResolution(sentinel, scriptEl, resolved);
         return;
     }
     nextExpectedRecordSequence++;
-    nextExpectedBoundaryId++;
-    commitCheckpoint(payload, resolved.range, sequence, target, kind === RECORD_KIND_UPDATABLE_CHECKPOINT, sentinel, scriptEl);
+    nextExpectedBoundaryInstanceId++;
+    commitRecord(false, payload, resolved.range, sequence, target, kind === RECORD_KIND_UPDATABLE_CHECKPOINT, sentinel, scriptEl);
 }
-function commitCheckpoint(bootstrap, range, sequence, target, updatable, sentinel, scriptEl) {
+function commitRecord(span, payload, range, sequence, target, updatable, sentinel, scriptEl) {
     markBoundaryPending();
     let committed = false;
     try {
-        applyBoundaryBootstrap(bootstrap);
-        if (range.start && range.end) {
-            const boundary = updatable
-                ? { roots: [], retained: 0, pendingRoots: 0 }
-                : undefined;
-            activateRootsBetween(range.start, range.end, bootstrap.state, boundary);
-            if (boundary)
-                retainUpdatableBoundary(target, boundary);
+        if (span) {
+            hydrateSpanCompletion(payload, range, target);
         }
-        else if (updatable) {
-            retainUpdatableBoundary(target, {
-                roots: [],
-                retained: 0,
-                pendingRoots: 0,
-            });
+        else {
+            hydrateCheckpoint(payload, range, target, updatable);
         }
         committed = true;
     }
     catch (error) {
-        fail(`error committing boundary ${sequence}: ${streamingErrorMessage(error)}`);
+        const detail = streamingErrorMessage(error);
+        fail(span
+            ? `error completing span ${target}: ${detail}`
+            : `error committing boundary ${sequence}: ${detail}`);
     }
     finally {
         removeBoundaryScaffolding(sentinel, scriptEl, range.start, range.end);
         if (committed) {
-            notifyCommit(`${BOUNDARY_MARK_PREFIX}${target}`, sequence, 'checkpoint');
+            notifyCommit(`${span ? SPAN_MARK_PREFIX : BOUNDARY_MARK_PREFIX}${target}`, sequence, span ? 'span' : 'checkpoint');
         }
         markBoundaryCommitted(false);
     }
 }
+function hydrateCheckpoint(bootstrap, range, target, updatable) {
+    let bypass;
+    const enclosing = bootstrap.enclosingSpanInstanceId;
+    if (enclosing !== undefined && range.start?.parentNode) {
+        const invalid = registerEnclosingSpans(range.start.parentNode, enclosing);
+        if (invalid)
+            throw new Error(invalid);
+        const host = spanHostFor(enclosing);
+        if (host)
+            bypass = { id: String(enclosing), host };
+    }
+    applyBoundaryBootstrap(bootstrap);
+    if (range.start && range.end) {
+        const boundary = updatable
+            ? newUpdatableBoundary()
+            : undefined;
+        activateRootsBetween(range.start, range.end, bootstrap.state, boundary, bypass);
+        if (boundary)
+            retainUpdatableBoundary(target, boundary);
+    }
+    else if (updatable) {
+        retainUpdatableBoundary(target, newUpdatableBoundary());
+    }
+}
+function newUpdatableBoundary() {
+    return { roots: [], active: true, retained: 0, pendingRoots: 0 };
+}
+function hydrateSpanCompletion(payload, range, target) {
+    const invalid = prepareSpanCompletion(target, range);
+    if (invalid)
+        throw new Error(invalid);
+    applyBoundaryBootstrap(payload);
+    activateRootsBetween(range.start, range.end, payload.state);
+    completeSpan(target);
+}
+function failRangeResolution(sentinel, scriptEl, resolved) {
+    if (!resolved.truncated) {
+        failBoundary(sentinel, resolved.reason);
+        return;
+    }
+    if (resolved.start)
+        abandonDeferredRange(resolved.start, scriptEl);
+    removeBoundaryScaffolding(sentinel, scriptEl, resolved.start, null);
+    fail(resolved.reason);
+}
 function retainUpdatableBoundary(target, boundary) {
     if (updatableBoundaries.size >= MAX_UPDATABLE_BOUNDARIES) {
         throw new Error(`updatable boundary count exceeds ${MAX_UPDATABLE_BOUNDARIES}`);
@@ -269,10 +321,17 @@ function commitTerminal(sequence, sentinel, scriptEl) {
     removeBoundaryScaffolding(sentinel, scriptEl, null, null);
     terminalCommitted = true;
     pendingTerminalSequence = sequence;
-    clearUpdatableBoundaries();
+    clearUpdatableBoundaries(true);
     scheduleTerminalValidation();
 }
-function clearUpdatableBoundaries() {
+function clearUpdatableBoundaries(preservePendingPatches = false) {
+    for (const boundary of updatableBoundaries.values()) {
+        boundary.active = false;
+        boundary.roots.length = 0;
+        if (!preservePendingPatches || boundary.pendingRoots === 0) {
+            boundary.patch = undefined;
+        }
+    }
     updatableBoundaries.clear();
     retainedUpdateRoots = 0;
 }
@@ -341,6 +400,7 @@ function onDomContentLoaded(generation) {
 }
 export function resetStreamingCoordinatorStateForTests() {
     resetDeferredActivationForTests();
+    abandonOpenSpans();
     settlePendingTerminal(false);
     clearUpdatableBoundaries();
     coordinatorGeneration++;
@@ -350,7 +410,7 @@ export function resetStreamingCoordinatorStateForTests() {
     slicedDrainActive = false;
     halted = false;
     nextExpectedRecordSequence = 0;
-    nextExpectedBoundaryId = 0;
+    nextExpectedBoundaryInstanceId = 0;
     terminalCommitted = false;
     pendingTerminalSequence = null;
     terminalValidationScheduled = false;
@@ -361,4 +421,4 @@ export function isStreamingHaltedForTests() {
 export function streamingRetentionStateForTests() {
     return [updatableBoundaries.size, retainedUpdateRoots];
 }
-export { elementHasPendingStateForTests, pendingTagWaiterCountForTests, pendingUndefinedRootCountForTests, };
+export { elementHasPendingStateForTests, openSpanCountForTests, pendingBarrierRootCountForTests, pendingTagWaiterCountForTests, pendingUndefinedRootCountForTests, };

package/dist/streaming-deferred.d.ts

@@ -1,16 +1,25 @@
-export declare const ACTIVATION_MISSING_TEMPLATE = 3;
-export declare const ELEMENT_IGNORED = 0;
-export declare const ELEMENT_DEFERRED = 4;
-export declare const ELEMENT_LIMIT_FAILURE = 5;
+export declare const ELEMENT_IGNORED = 10;
+export declare const ELEMENT_DEFERRED = 11;
+export declare const ELEMENT_LIMIT_FAILURE = 12;
+export declare const ELEMENT_ACTIVATED_FROM_PENDING = 13;
+export declare const ELEMENT_BARRIER_LIMIT_FAILURE = 14;
+export declare const ELEMENT_INVALID_OUTCOME = 15;
 export declare const MAX_PENDING_UNDEFINED_ROOTS = 50000;
+export declare const MAX_PENDING_BARRIER_ROOTS = 50000;
+export interface SpanBypass {
+    readonly id: string;
+    readonly host: Element;
+}
 export interface PendingBoundaryUpdates {
     readonly roots: Element[];
+    active: boolean;
     retained: number;
     pendingRoots: number;
     patch?: Record<string, unknown>;
 }
 export interface DeferredActivationOptions {
     updates?: PendingBoundaryUpdates;
+    bypass?: SpanBypass;
     countRetention?: boolean;
 }
 export declare function configureStreamingFailureHandler(handler: (reason: string) => void): void;
@@ -19,4 +28,5 @@ export declare function abandonPendingWaiters(): void;
 export declare function resetDeferredActivationForTests(): void;
 export declare function pendingTagWaiterCountForTests(): number;
 export declare function pendingUndefinedRootCountForTests(): number;
+export declare function pendingBarrierRootCountForTests(): number;
 export declare function elementHasPendingStateForTests(el: Element): boolean;