@microsoft/webui-framework 0.0.19 → 0.0.20

package/dist/streaming-dom.js

@@ -0,0 +1,148 @@
+export const BOUNDARY_SCRIPT_ATTR = 'data-webui-boundary';
+export const MAX_ELEMENTS_PER_BOUNDARY = 10_000;
+export const MAX_MARKER_SCAN_NODES = 50_000;
+export const MAX_BOUNDARY_SCRIPT_SCAN = 8;
+export function streamingErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+const BOUNDARY_START_PREFIX = 'wb:';
+const BOUNDARY_END_PREFIX = '/wb:';
+const MARKERLESS_RANGE = { start: null, end: null };
+export function resolveBoundaryRange(scriptEl, sequence, terminal) {
+    const end = findEndMarker(scriptEl, sequence);
+    if (end) {
+        if (terminal) {
+            return {
+                ok: false,
+                reason: `terminal boundary ${sequence} must be markerless`,
+                truncated: false,
+            };
+        }
+        const start = findStartMarkerBefore(end, sequence);
+        if (!start) {
+            return {
+                ok: false,
+                reason: `missing start marker for boundary ${sequence}`,
+                truncated: false,
+            };
+        }
+        return { ok: true, range: { start, end } };
+    }
+    if (terminal)
+        return { ok: true, range: MARKERLESS_RANGE };
+    return {
+        ok: false,
+        reason: `missing end marker for boundary ${sequence}`,
+        truncated: true,
+        start: findStartMarkerBefore(scriptEl, sequence),
+    };
+}
+export function findBoundaryScript(sentinel) {
+    let node = sentinel.previousElementSibling;
+    for (let hops = 0; node && hops < MAX_BOUNDARY_SCRIPT_SCAN; hops++) {
+        if (node.tagName === 'SCRIPT' &&
+            node.hasAttribute(BOUNDARY_SCRIPT_ATTR)) {
+            return node;
+        }
+        node = node.previousElementSibling;
+    }
+    return null;
+}
+function findEndMarker(scriptEl, sequence) {
+    const marker = previousComment(scriptEl);
+    return marker?.data === `${BOUNDARY_END_PREFIX}${sequence}`
+        ? marker
+        : null;
+}
+function findStartMarkerBefore(nodeBefore, sequence) {
+    return findCommentBefore(nodeBefore, `${BOUNDARY_START_PREFIX}${sequence}`);
+}
+export function findEndMarkerByPrefix(scriptEl) {
+    const marker = previousComment(scriptEl);
+    return marker?.data.startsWith(BOUNDARY_END_PREFIX) ? marker : null;
+}
+export function findStartMarkerByPrefix(endMarker) {
+    return findCommentBefore(endMarker, `${BOUNDARY_START_PREFIX}${endMarker.data.slice(BOUNDARY_END_PREFIX.length)}`);
+}
+function previousComment(node) {
+    const previous = node.previousSibling;
+    return previous?.nodeType === 8
+        ? previous
+        : null;
+}
+function findCommentBefore(nodeBefore, target) {
+    let node = nodeBefore.previousSibling;
+    for (let hops = 0; node && hops < MAX_MARKER_SCAN_NODES; hops++) {
+        if (node.nodeType === 8 &&
+            node.data === target) {
+            return node;
+        }
+        node = node.previousSibling;
+    }
+    return null;
+}
+export function safeRemove(node) {
+    try {
+        node?.remove?.();
+    }
+    catch {
+    }
+}
+export function safeRemoveAttribute(el, name) {
+    try {
+        el.removeAttribute?.(name);
+    }
+    catch {
+    }
+}
+export function removeBoundaryScaffolding(sentinel, scriptEl, startMarker, endMarker) {
+    if (!scriptEl) {
+        safeRemove(sentinel);
+        safeRemove(endMarker);
+        safeRemove(startMarker);
+        return;
+    }
+    let node = sentinel.previousElementSibling;
+    safeRemove(sentinel);
+    for (let hops = 0; node && hops <= MAX_BOUNDARY_SCRIPT_SCAN; hops++) {
+        const previous = node.previousElementSibling;
+        const wasBoundaryScript = node === scriptEl;
+        safeRemove(node);
+        if (wasBoundaryScript)
+            break;
+        node = previous;
+    }
+    safeRemove(endMarker);
+    safeRemove(startMarker);
+}
+export function firstNodeWithin(root) {
+    return root.shadowRoot?.firstChild ?? root.firstChild;
+}
+export function nextWithinRoot(node, root) {
+    if (node.nodeType === 1) {
+        const shadowRoot = node.shadowRoot;
+        if (shadowRoot?.firstChild)
+            return shadowRoot.firstChild;
+    }
+    if (node.firstChild)
+        return node.firstChild;
+    return nextAfterSubtreeWithin(node, root);
+}
+export function nextAfterSubtreeWithin(node, root) {
+    let current = node;
+    while (current && current !== root) {
+        if (current.nodeType === 11) {
+            const host = current.host ?? null;
+            if (host) {
+                if (host.firstChild)
+                    return host.firstChild;
+                current = host;
+                continue;
+            }
+        }
+        if (current.nextSibling)
+            return current.nextSibling;
+        current = current.parentNode;
+    }
+    return null;
+}

package/dist/streaming-entry.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/streaming-entry.js

@@ -0,0 +1,2 @@
+import { installStreamingCoordinator } from './streaming.js';
+installStreamingCoordinator();

package/dist/streaming-install.d.ts

@@ -0,0 +1,2 @@
+export declare function installStreamingCoordinator(): void;
+export declare function resetStreamingInstallForTests(): void;

package/dist/streaming-install.js

@@ -0,0 +1,25 @@
+import { beginStreamingGate } from './lifecycle.js';
+import { installTemplateElementRuntime } from './static-host.js';
+import { enqueueStreamingSentinel, installStreamingTruncationGuard, } from './streaming-coordinator.js';
+import { isStreamingHydrationMode } from './streaming-mode.js';
+const SENTINEL_TAG = 'webui-hydrate';
+let installed = false;
+class WebUiHydrateSentinel extends HTMLElement {
+    connectedCallback() {
+        enqueueStreamingSentinel(this);
+    }
+}
+export function installStreamingCoordinator() {
+    if (installed || !isStreamingHydrationMode())
+        return;
+    installed = true;
+    if (!customElements.get(SENTINEL_TAG)) {
+        customElements.define(SENTINEL_TAG, WebUiHydrateSentinel);
+    }
+    beginStreamingGate();
+    installStreamingTruncationGuard();
+    installTemplateElementRuntime();
+}
+export function resetStreamingInstallForTests() {
+    installed = false;
+}

package/dist/streaming-mode.d.ts

@@ -0,0 +1,5 @@
+export declare const STREAMING_BOUNDARY_ACTIVATE: unique symbol;
+export declare const PENDING_ROOT_CONNECTED: unique symbol;
+export declare const STREAMED_HOST_ATTR = "data-ws";
+export declare function isStreamingHydrationMode(): boolean;
+export declare function resetStreamingModeForTests(): void;

package/dist/streaming-mode.js

@@ -0,0 +1,14 @@
+let cached;
+export const STREAMING_BOUNDARY_ACTIVATE = Symbol.for('microsoft.webui.boundaryActivate');
+export const PENDING_ROOT_CONNECTED = Symbol.for('microsoft.webui.pendingRootConnected');
+export const STREAMED_HOST_ATTR = 'data-ws';
+export function isStreamingHydrationMode() {
+    if (cached !== undefined)
+        return cached;
+    cached = typeof document !== 'undefined' &&
+        !!document.querySelector('meta[name="webui-streaming"][content="1"]');
+    return cached;
+}
+export function resetStreamingModeForTests() {
+    cached = undefined;
+}

package/dist/streaming-protocol.d.ts

@@ -0,0 +1,32 @@
+import type { TemplateMeta } from './template.js';
+export interface BoundaryBootstrap {
+    state?: Record<string, unknown>;
+    templates?: Record<string, TemplateMeta>;
+    inventory?: string;
+    nonce?: string;
+    chain?: unknown[];
+    css?: string[];
+    styles?: string[];
+    [key: string]: unknown;
+}
+export declare const RECORD_KIND_FINAL_CHECKPOINT = 0;
+export declare const RECORD_KIND_UPDATABLE_CHECKPOINT = 1;
+export declare const RECORD_KIND_STATE_UPDATE = 2;
+export declare const RECORD_KIND_TERMINAL = 3;
+export type BoundaryRecordKind = typeof RECORD_KIND_FINAL_CHECKPOINT | typeof RECORD_KIND_UPDATABLE_CHECKPOINT | typeof RECORD_KIND_STATE_UPDATE | typeof RECORD_KIND_TERMINAL;
+export type BoundaryRecordPayload = BoundaryBootstrap | Record<string, unknown>;
+export type BoundaryEnvelope = readonly [
+    version: number,
+    recordSequence: number,
+    kind: BoundaryRecordKind,
+    target: number,
+    payload: BoundaryRecordPayload
+];
+export type ParseBoundaryEnvelopeResult = {
+    readonly ok: true;
+    readonly envelope: BoundaryEnvelope;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+export declare function parseBoundaryEnvelope(text: string): ParseBoundaryEnvelopeResult;

package/dist/streaming-protocol.js

@@ -0,0 +1,27 @@
+const SUPPORTED_VERSION = 1;
+export const RECORD_KIND_FINAL_CHECKPOINT = 0;
+export const RECORD_KIND_UPDATABLE_CHECKPOINT = 1;
+export const RECORD_KIND_STATE_UPDATE = 2;
+export const RECORD_KIND_TERMINAL = 3;
+function invalid(reason) {
+    return { ok: false, reason };
+}
+export function parseBoundaryEnvelope(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(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] !== SUPPORTED_VERSION) {
+        return invalid(`unsupported boundary envelope version ${JSON.stringify(parsed[0])}`);
+    }
+    return {
+        ok: true,
+        envelope: parsed,
+    };
+}

package/dist/streaming.d.ts

@@ -0,0 +1,5 @@
+export { enqueueStreamingSentinel as __enqueueSentinelForTests, elementHasPendingStateForTests as __elementHasPendingStateForTests, installStreamingTruncationGuard as __installTruncationGuardForTests, isStreamingHaltedForTests as __isHaltedForTests, pendingTagWaiterCountForTests as __pendingTagWaiterCountForTests, pendingUndefinedRootCountForTests as __pendingUndefinedRootCountForTests, streamingRetentionStateForTests as __streamingRetentionStateForTests, } from './streaming-coordinator.js';
+export { installStreamingCoordinator } from './streaming-install.js';
+export { parseBoundaryEnvelope } from './streaming-protocol.js';
+export type { BoundaryBootstrap, BoundaryEnvelope, ParseBoundaryEnvelopeResult, } from './streaming-protocol.js';
+export declare function __resetStreamingCoordinatorForTests(): void;

package/dist/streaming.js

@@ -0,0 +1,9 @@
+import { resetStreamingCoordinatorStateForTests, } from './streaming-coordinator.js';
+import { resetStreamingInstallForTests } from './streaming-install.js';
+export { enqueueStreamingSentinel as __enqueueSentinelForTests, elementHasPendingStateForTests as __elementHasPendingStateForTests, installStreamingTruncationGuard as __installTruncationGuardForTests, isStreamingHaltedForTests as __isHaltedForTests, pendingTagWaiterCountForTests as __pendingTagWaiterCountForTests, pendingUndefinedRootCountForTests as __pendingUndefinedRootCountForTests, streamingRetentionStateForTests as __streamingRetentionStateForTests, } from './streaming-coordinator.js';
+export { installStreamingCoordinator } from './streaming-install.js';
+export { parseBoundaryEnvelope } from './streaming-protocol.js';
+export function __resetStreamingCoordinatorForTests() {
+    resetStreamingCoordinatorStateForTests();
+    resetStreamingInstallForTests();
+}

package/dist/template-element.d.ts

@@ -1,11 +1,14 @@
 import type { TemplateBlockMeta, TemplateNodePath } from './template.js';
+import { STREAMING_BOUNDARY_ACTIVATE } from './streaming-mode.js';
 import type { ScopeFrame, TemplateInstance } from './element/types.js';
 declare const WEBUI_SET_STATE_KEY: unique symbol;
+declare const STREAMING_BOUNDARY_ABANDON: unique symbol;
 export declare class TemplateElement extends HTMLElement {
     private $root;
     private $meta?;
     private $ready;
     private $hydrated;
+    private $hydratedCallbackCalled;
     private $deferredSSR;
     private $activatingDeferredSSR;
     private $hasUnknownScopes;
@@ -17,6 +20,8 @@ export declare class TemplateElement extends HTMLElement {
     private $pathIndex?;
     private $wildcardBindings?;
     [WEBUI_SET_STATE_KEY](key: string, value: unknown): boolean;
+    [STREAMING_BOUNDARY_ACTIVATE](state?: Record<string, unknown>): number;
+    [STREAMING_BOUNDARY_ABANDON](): void;
     static define(tagName: string): void;
     connectedCallback(): void;
     private $mount;
@@ -30,10 +35,13 @@ export declare class TemplateElement extends HTMLElement {
     protected $beforeExternalStateWrite(): void;
     protected $afterExternalStateWrite(_applied: boolean): void;
     protected $shouldDeferSSRHydration(): boolean;
-    protected $activateDeferredSSR(): void;
+    protected $shouldActivateOnBoundaryCommit(): boolean;
+    protected $activateDeferredSSR(state?: Record<string, unknown>): void;
     protected $shouldApplySSRBootstrapState(): boolean;
     protected $shouldApplySSRState(_key: string): boolean;
     protected $syncAuthoredAttributes(): void;
+    protected hydratedCallback(): void;
+    private $notifyHydrated;
     protected $shouldApplyTemplateStateFromSSR(_key: string): boolean;
     protected $setTemplateState(key: string, value: unknown): boolean;
     private $writeTemplateState;

package/dist/template-element.js

@@ -1,5 +1,6 @@
-import { getTemplate } from './template.js';
+import { deferTemplateDefinition, getTemplate } from './template.js';
 import { hydrationStart, hydrationEnd } from './lifecycle.js';
+import { isStreamingHydrationMode, PENDING_ROOT_CONNECTED, STREAMED_HOST_ATTR, STREAMING_BOUNDARY_ACTIVATE, } from './streaming-mode.js';
 import { createRepeatKeyState, seedHydratedRepeatKeys, syncRepeat, dotWalk, } from './element/diff.js';
 import { collectItemMarkers, nextElement, findByOrdinal, MARKER_COND_START, MARKER_COND_END, MARKER_REPEAT_START, } from './element/markers.js';
 import { injectModuleStyle, } from './element/styles.js';
@@ -35,6 +36,10 @@ function getTplOrdinals(tplNode) {
 const EMPTY_ARR = [];
 const EMPTY_SET = Object.freeze(new Set());
 const WEBUI_SET_STATE_KEY = Symbol.for('microsoft.webui.setStateKey');
+const STREAMING_BOUNDARY_ABANDON = Symbol.for('microsoft.webui.boundaryAbandon');
+const ACTIVATION_ACTIVATED = 1;
+const ACTIVATION_STATIC_HOST_OPT_OUT = 2;
+const ACTIVATION_MISSING_TEMPLATE = 3;
 const templateMetaByCtor = new WeakMap();
 function childNodesArray(parent) {
     const children = parent.childNodes;
@@ -53,8 +58,7 @@ function getTemplateDom(meta) {
     templateDOMCache.set(meta, div);
     return div;
 }
-function installTemplateObservedAttributes(ctor, tagName) {
-    const meta = getTemplate(tagName);
+function installTemplateObservedAttributes(ctor, tagName, meta = getTemplate(tagName)) {
     if (!meta)
         return;
     templateMetaByCtor.set(ctor, meta);
@@ -90,6 +94,10 @@ function installTemplateObservedAttributes(ctor, tagName) {
         configurable: true,
     });
 }
+function defineTemplateConstructor(ctor, tagName, meta) {
+    installTemplateObservedAttributes(ctor, tagName, meta);
+    customElements.define(tagName, ctor);
+}
 function hasAuthoredMember(instance, key) {
     if (Object.prototype.hasOwnProperty.call(instance, key))
         return true;
@@ -107,6 +115,7 @@ export class TemplateElement extends HTMLElement {
         this.$root = null;
         this.$ready = false;
         this.$hydrated = false;
+        this.$hydratedCallbackCalled = false;
         this.$deferredSSR = false;
         this.$activatingDeferredSSR = false;
         this.$hasUnknownScopes = false;
@@ -125,9 +134,39 @@ export class TemplateElement extends HTMLElement {
             this.$update(key);
         return owned;
     }
+    [STREAMING_BOUNDARY_ACTIVATE](state) {
+        if (!this.$deferredSSR && this.hasAttribute(STREAMED_HOST_ATTR)) {
+            this.$deferredSSR = true;
+            this.$ready = true;
+        }
+        if (!this.$deferredSSR)
+            return ACTIVATION_ACTIVATED;
+        const meta = this.$templateMeta();
+        if (!meta) {
+            return ACTIVATION_MISSING_TEMPLATE;
+        }
+        this.$meta = meta;
+        if (!this.$shouldActivateOnBoundaryCommit())
+            return ACTIVATION_STATIC_HOST_OPT_OUT;
+        this.$activateDeferredSSR(state);
+        return ACTIVATION_ACTIVATED;
+    }
+    [STREAMING_BOUNDARY_ABANDON]() {
+        this.$deferredSSR = false;
+        this.$activatingDeferredSSR = false;
+        this.$ready = false;
+        this.$preReadyWrites = null;
+    }
     static define(tagName) {
-        installTemplateObservedAttributes(this, tagName);
-        customElements.define(tagName, this);
+        const ctor = this;
+        const meta = getTemplate(tagName);
+        if (!meta && isStreamingHydrationMode()) {
+            deferTemplateDefinition(tagName, ctor, () => {
+                defineTemplateConstructor(ctor, tagName, getTemplate(tagName));
+            });
+            return;
+        }
+        defineTemplateConstructor(ctor, tagName, meta);
     }
     connectedCallback() {
         const tag = this.tagName.toLowerCase();
@@ -137,12 +176,24 @@ export class TemplateElement extends HTMLElement {
         }
         if (this.$hydrated && this.$root) {
             hydrationStart();
+            try {
+                this.$ready = true;
+                this.$update();
+            }
+            finally {
+                hydrationEnd();
+            }
+            return;
+        }
+        if (isStreamingHydrationMode() && this.hasAttribute(STREAMED_HOST_ATTR)) {
+            this.$deferredSSR = true;
             this.$ready = true;
-            this.$update();
-            hydrationEnd();
+            const resume = this[PENDING_ROOT_CONNECTED];
+            if (typeof resume === 'function')
+                resume.call(this);
             return;
         }
-        const meta = getTemplate(tag);
+        const meta = this.$templateMeta();
         if (!meta) {
             console.warn(`[WebUI] Template metadata for <${tag}> not found. ` +
                 `Ensure the component is included in the SSR output or registered via __webui.templates.`);
@@ -151,7 +202,7 @@ export class TemplateElement extends HTMLElement {
         this.$meta = meta;
         this.$mount(meta, false);
     }
-    $mount(meta, forceSSR) {
+    $mount(meta, forceSSR, ssrState) {
         if (this.$hydrated)
             return;
         const hasShadow = !!this.shadowRoot;
@@ -182,35 +233,41 @@ export class TemplateElement extends HTMLElement {
             return;
         }
         hydrationStart();
-        if (meta.sa)
-            injectModuleStyle(meta.sa, this.shadowRoot);
-        if (isSSR) {
-            if (this.$shouldApplySSRBootstrapState())
-                this.$applySSRState();
-            this.$root = this.$hydrate(root, meta, getTemplateDom(meta));
-        }
-        else {
-            clientRoot = this.$createStagingRoot(meta);
-            this.$root = this.$wire(clientRoot, meta);
-        }
-        this.$meta = meta;
-        this.$hydrated = true;
-        this.$ready = true;
-        this.$syncAuthoredAttributes();
-        if (isSSR && DEV)
-            this.$checkHydrationMismatch();
-        else
-            this.$preReadyWrites = null;
-        if (!isSSR && clientRoot) {
-            this.$updateInstance(this.$root);
-            if (this.$root.repeats.length !== 0 || this.$root.conds.length !== 0) {
-                this.$root.nodes = childNodesArray(clientRoot);
-                this.$replaceInstanceContainer(this.$root, clientRoot, root);
+        try {
+            if (meta.sa)
+                injectModuleStyle(meta.sa, this.shadowRoot);
+            if (isSSR) {
+                if (this.$shouldApplySSRBootstrapState()) {
+                    this.$applySSRState(forceSSR ? ssrState : window.__webui?.state);
+                }
+                this.$root = this.$hydrate(root, meta, getTemplateDom(meta));
+            }
+            else {
+                clientRoot = this.$createStagingRoot(meta);
+                this.$root = this.$wire(clientRoot, meta);
+            }
+            this.$meta = meta;
+            this.$hydrated = true;
+            this.$ready = true;
+            this.$syncAuthoredAttributes();
+            if (isSSR && DEV)
+                this.$checkHydrationMismatch();
+            else
+                this.$preReadyWrites = null;
+            if (!isSSR && clientRoot) {
+                this.$updateInstance(this.$root);
+                if (this.$root.repeats.length !== 0 || this.$root.conds.length !== 0) {
+                    this.$root.nodes = childNodesArray(clientRoot);
+                    this.$replaceInstanceContainer(this.$root, clientRoot, root);
+                }
+                this.$appendStagedChildren(root, clientRoot);
+                this.$root.container = root;
             }
-            this.$appendStagedChildren(root, clientRoot);
-            this.$root.container = root;
+            this.$notifyHydrated();
+        }
+        finally {
+            hydrationEnd();
         }
-        hydrationEnd();
     }
     disconnectedCallback() {
         if (this.$root) {
@@ -299,15 +356,21 @@ export class TemplateElement extends HTMLElement {
     $shouldDeferSSRHydration() {
         return false;
     }
-    $activateDeferredSSR() {
-        if (!this.$deferredSSR || !this.$meta)
+    $shouldActivateOnBoundaryCommit() {
+        return true;
+    }
+    $activateDeferredSSR(state) {
+        if (!this.$deferredSSR)
+            return;
+        const meta = this.$meta;
+        if (!meta)
             return;
         this.$deferredSSR = false;
         this.$ready = false;
         this.$preReadyWrites = null;
         this.$activatingDeferredSSR = true;
         try {
-            this.$mount(this.$meta, true);
+            this.$mount(meta, true, state);
         }
         finally {
             this.$activatingDeferredSSR = false;
@@ -321,6 +384,14 @@ export class TemplateElement extends HTMLElement {
     }
     $syncAuthoredAttributes() {
     }
+    hydratedCallback() {
+    }
+    $notifyHydrated() {
+        if (this.$hydratedCallbackCalled)
+            return;
+        this.$hydratedCallbackCalled = true;
+        this.hydratedCallback();
+    }
     $shouldApplyTemplateStateFromSSR(_key) {
         return true;
     }
@@ -368,8 +439,7 @@ export class TemplateElement extends HTMLElement {
         }
         return false;
     }
-    $applySSRState() {
-        const state = window.__webui?.state;
+    $applySSRState(state) {
         if (!state || typeof state !== 'object')
             return;
         const observableNames = this.$observableNames();
@@ -783,7 +853,6 @@ export class TemplateElement extends HTMLElement {
                     const insertRef = ssrParent.childNodes[Math.min(beforeIndex ?? staticCount, ssrParent.childNodes.length)] ?? null;
                     ssrParent.insertBefore(anchor, insertRef);
                 }
-                lastRepMarker = anchor;
                 const repeatInsts = [];
                 const hasCollectionState = this.$hasStateRoot(collection, scope);
                 const itemsArr = this.$resolveValue(collection, scope);
@@ -791,6 +860,7 @@ export class TemplateElement extends HTMLElement {
                 const { items: itemMarkers, end: endMarker } = marker
                     ? collectItemMarkers(anchor)
                     : { items: [], end: null };
+                lastRepMarker = endMarker ?? anchor;
                 if (blockMeta && blockTplDom && anchor.parentNode && itemMarkers.length > 0) {
                     if (!this.$activatingDeferredSSR
                         && hasCollectionState

package/dist/template.d.ts

@@ -14,3 +14,4 @@ declare global {
 export declare function getTemplate(name: string): TemplateMeta | undefined;
 export declare function getTemplateRegistry(): Record<string, TemplateMeta> | undefined;
 export declare function registerTemplateData(templates: Record<string, TemplateMeta>, templateFns?: Record<string, CompiledConditionFn[]>): void;
+export declare function deferTemplateDefinition(tagName: string, ctor: Function, define: () => void): void;

package/dist/template.js

@@ -1,22 +1,9 @@
-import { dispatchTemplatesRegistered } from './template-events.js';
+import { dispatchTemplatesRegistered, templateRegistrationDetail, TEMPLATES_REGISTERED_EVENT, } from './template-events.js';
 const WEBUI_DATA_ID = 'webui-data';
 const normalizedTemplates = new WeakSet();
 let webuiDataLoaded = false;
-export function getTemplate(name) {
-    let meta = window.__webui?.templates?.[name];
-    if (!meta) {
-        loadWebUIDataBlock();
-        meta = window.__webui?.templates?.[name];
-    }
-    if (meta)
-        normalizeTemplate(name, meta);
-    return meta;
-}
-export function getTemplateRegistry() {
-    loadWebUIDataBlock();
-    return window.__webui?.templates;
-}
-export function registerTemplateData(templates, templateFns) {
+const pendingTemplateDefinitions = new Map();
+function acceptTemplateData(templates, templateFns) {
     const w = window;
     if (!w.__webui)
         w.__webui = {};
@@ -32,16 +19,56 @@ export function registerTemplateData(templates, templateFns) {
         }
     }
     const names = Object.keys(templates);
-    let hasTemplates = false;
     for (let i = 0; i < names.length; i++) {
         const tag = names[i];
         const meta = templates[tag];
         w.__webui.templates[tag] = meta;
         normalizeTemplate(tag, meta);
-        hasTemplates = true;
     }
-    if (hasTemplates)
+    for (let i = 0; i < names.length; i++) {
+        const pending = pendingTemplateDefinitions.get(names[i]);
+        if (!pending)
+            continue;
+        pendingTemplateDefinitions.delete(names[i]);
+        pending.define();
+    }
+    return names.length > 0;
+}
+if (typeof window !== 'undefined' && typeof window.addEventListener === 'function') {
+    window.addEventListener(TEMPLATES_REGISTERED_EVENT, (event) => {
+        const templates = templateRegistrationDetail(event)?.templates;
+        if (templates)
+            acceptTemplateData(templates);
+    });
+}
+export function getTemplate(name) {
+    let meta = window.__webui?.templates?.[name];
+    if (!meta) {
+        loadWebUIDataBlock();
+        meta = window.__webui?.templates?.[name];
+    }
+    if (meta)
+        normalizeTemplate(name, meta);
+    return meta;
+}
+export function getTemplateRegistry() {
+    loadWebUIDataBlock();
+    return window.__webui?.templates;
+}
+export function registerTemplateData(templates, templateFns) {
+    if (acceptTemplateData(templates, templateFns)) {
         dispatchTemplatesRegistered(templates);
+    }
+}
+export function deferTemplateDefinition(tagName, ctor, define) {
+    const pending = pendingTemplateDefinitions.get(tagName);
+    if (pending) {
+        if (pending.ctor === ctor) {
+            throw new Error(`[WebUI] <${tagName}> is already pending definition.`);
+        }
+        throw new Error(`[WebUI] <${tagName}> already has a pending authored definition.`);
+    }
+    pendingTemplateDefinitions.set(tagName, { ctor, define });
 }
 function loadWebUIDataBlock() {
     if (webuiDataLoaded || window.__webui?.state !== undefined || typeof document === 'undefined')