@microsoft/webui-framework 0.0.29 → 3.0.0

package/README.md

@@ -12,7 +12,7 @@ This package is the browser-side runtime used by `webui build --plugin=webui`. I
 
 If you are building WebUI apps in this repo, this is the component model used by examples like `examples/app/todo-webui`, `examples/app/commerce`, and `examples/app/contact-book-manager`.
 
-> 📖 **Full documentation at [microsoft.github.io/webui](https://microsoft.github.io/webui)**, see the [Interactivity Guide](https://microsoft.github.io/webui/guide/concepts/interactivity) for component authoring patterns. For framework internals (hydration, path resolution, reactive update model), see [RENDERING.md](./RENDERING.md).
+> 📖 **Full documentation at [microsoft.github.io/webui](https://microsoft.github.io/webui)**, see the [Interactivity Guide](https://microsoft.github.io/webui/guide/concepts/interactivity) for component authoring patterns. For framework internals (hydration, path resolution, reactive update model), see [the hydration contract](https://github.com/microsoft/webui/blob/main/specs/hydration.md).
 
 ## Install
 
@@ -328,7 +328,7 @@ 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 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
+`__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).
 
@@ -396,36 +396,40 @@ In most components you do not call `$update()` directly. Property changes throug
 
 ### Static component assets
 
-`webui build --plugin=webui --emit-component-assets settings-dialog` emits
-`settings-dialog.webui.js` next to `protocol.bin`. Load the ESM asset before
-creating the component when you are not using `@microsoft/webui-router`:
+Generate stable ESM inputs separately from deployable output:
 
-```ts
-import { settingsAssets } from './lazy-assets.js';
-
-settingsAssets.preload('settings-dialog');
-panelSlot.replaceChildren(await settingsAssets.create('settings-dialog'));
+```bash
+webui build ./src --out ./dist --plugin=webui \
+  --emit-component-assets settings-dialog \
+  --component-assets-out ./.webui
 ```
 
-```ts
-// lazy-assets.ts
-import { defineComponentAssets } from '@microsoft/webui-framework/component-asset.js';
-
-export const settingsAssets = defineComponentAssets({
-  'settings-dialog': {
-    asset: '/settings-dialog.webui.js',
-    module: () => import('./settings-dialog/settings-dialog.js'),
-    data: async () => await (await fetch('/settings-dialog-data.json')).json(),
-  },
-});
+```typescript
+import {
+  defineComponentAsset,
+  preloadComponentAssetStyles,
+} from '@microsoft/webui-framework/component-asset-runtime.js';
+
+const loadSettings = () => {
+  preloadComponentAssetStyles('settings-dialog');
+  return import('../../.webui/settings-dialog.webui.js')
+    .then(module => defineComponentAsset(module.default));
+};
+
+void loadSettings().then(asset => asset.preload()).catch(() => {});
+panelSlot.replaceChildren(await (await loadSettings()).create());
 ```
 
-The asset graph keeps entry-owned templates external, leaves single-root
-dependencies inline, and emits dependencies shared by multiple roots once as
-flat dynamic chunks. Component assets cannot be combined with `<route>`. Load
-the normal entry bundle first so external prerequisites are registered.
-Current assets require version 3 and an atomically validated
-`componentStyles` catalog; any other version is rejected as unsupported.
+WebUI emits one module per asset-owned component and a thin root entry with
+static imports for its closure. The application bundler owns final splitting,
+sharing, hashes, public paths, and caching. Entry-owned templates remain
+external prerequisites, so load the normal application entry first. Component
+assets cannot be combined with `<route>`. Current generated assets use version
+4 on the root. Imported component payloads contain template and style data,
+not repeated root manifests. Compiler-proven coverage is checked at build time;
+registration checks external entry templates and live style conflicts before
+mutating the registries. The manifest-driven loader additionally validates
+untrusted graphs.
 
 The compiler records final Link stylesheet filenames in the protocol. For
 Shadow builds, the handler emits that finite manifest as inert JSON in the
@@ -437,25 +441,23 @@ WebUI handler or `Protocol`, which emits `#webui-component-assets`. A shell that
 uses build artifacts without rendering the protocol still mounts safely through
 the native stylesheet guard, but it does not receive the earlier
 compiler-owned style preload.
-Shared chunk and content-hashed stylesheet filenames are generated and must not
-be copied into authored code. Each root asset carries its own dynamic imports;
-`--metafile` remains available for analysis and build tooling.
-
-In Shadow builds, `preload(tag)` reads the compiler-owned style metadata and
-starts Link styles beside the authored root asset, component module, and
-optional data request. Only the stable root asset URL remains in application
-code; shared chunks and content-hashed CSS stay compiler-owned.
-
-Bundler-generated loaders can use `asset: () => import('./settings-dialog.webui.js')`
-instead of a URL. This keeps chunk naming and public-path rewriting inside the
-bundler while preserving the same `preload(tag)` and `create(tag)` lifecycle.
-Concurrent roots share in-flight chunk and stylesheet work. `create(tag)`
-creates the element after template/module work is ready and does not block on
-optional data by default. Use
-`create(tag, { awaitData: true, dataTimeoutMs: 150 })` only when a component
-must wait briefly for state before mounting. A rejected root asset or authored
-module is evicted from the registry so a later `preload(tag)` or `create(tag)`
-retries it.
+Only stable generated root input paths belong in authored imports. Final
+JavaScript filenames are application-bundler outputs, while content-hashed
+stylesheet filenames remain compiler-owned. `--metafile` exposes the static
+input graph for analysis and build tooling.
+
+Generated roots export semantic payloads only. Application-owned code loads
+component behavior and data directly, so it also owns caching and recovery policy.
+The runtime returns one facade per imported payload. Native ESM failures may stay
+cached for the document lifetime: resetting an application promise does not
+guarantee a new network request. Handle real open failures with visible errors
+and bundler-owned recovery or an explicit page reload. Consume speculative
+preload rejections without automatically reloading.
+In Shadow builds, applications can import the small runtime eagerly, call
+`preloadComponentAssetStyles(root)` before the dynamic import, and wrap the
+default generated payload with `defineComponentAsset()`. This keeps templates
+lazy while starting CSS and JavaScript in parallel. Concurrent roots share
+in-flight registration and stylesheet work.
 
 ### `@observable`
 

package/dist/component-asset/asset.d.ts

@@ -1,24 +1,18 @@
 import type { CompiledConditionFn, TemplateMeta } from '../template.js';
 import { type ComponentStyles } from '../element/styles.js';
-export interface ComponentAssetImport {
-    components: string[];
-    href: string;
-    load: () => Promise<unknown>;
+export interface ComponentAssetPayload {
+    componentStyles: ComponentStyles;
+    templates: Record<string, TemplateMeta>;
+    templateFunctions?: Record<string, CompiledConditionFn[]>;
 }
 export interface ComponentAsset {
     type: 'webui-component-asset';
-    version: 3;
-    kind: 'root' | 'chunk';
-    root?: string;
-    components: string[];
-    requiredComponents: string[];
+    version: 4;
+    root: string;
     externalComponents: string[];
-    imports: ComponentAssetImport[];
+    imports: ComponentAssetPayload[];
     componentStyles: ComponentStyles;
-    templates: Record<string, TemplateMeta>;
-    templateFunctions?: Record<string, CompiledConditionFn[]>;
 }
 export declare function prepareAssetComponentStyles(value: unknown): ComponentStyles;
 export declare function readComponentAssetModule(module: unknown): unknown;
-export declare function validateAsset(value: unknown, expectedKind: ComponentAsset['kind']): asserts value is ComponentAsset;
-export declare function sameComponents(left: readonly string[], right: readonly string[]): boolean;
+export declare function validateAsset(value: unknown): asserts value is ComponentAsset;

package/dist/component-asset/asset.js

@@ -1,9 +1,7 @@
 import { requireComponentStyles, } from '../element/styles.js';
-const ASSET_TYPE = 'webui-component-asset';
-const COMPONENT_STYLES_ASSET_VERSION = 3;
 const preparedAssetStyles = new WeakMap();
 export function prepareAssetComponentStyles(value) {
-    if (typeof value === 'object' && value !== null) {
+    if (isObject(value)) {
         const cached = preparedAssetStyles.get(value);
         if (cached)
             return cached;
@@ -19,169 +17,74 @@ export function readComponentAssetModule(module) {
     }
     return module.default;
 }
-export function validateAsset(value, expectedKind) {
+export function validateAsset(value) {
     if (!isObject(value)) {
         throw new Error('[WebUI] Component asset default export must be an object.');
     }
-    const asset = value;
-    if (asset.type !== ASSET_TYPE) {
-        throw new Error(`[WebUI] Invalid component asset type: ${String(asset.type)}`);
+    if (value.type !== 'webui-component-asset') {
+        throw new Error(`[WebUI] Invalid component asset type: ${String(value.type)}`);
     }
-    if (asset.version !== COMPONENT_STYLES_ASSET_VERSION) {
-        throw new Error(`[WebUI] Unsupported component asset version: ${String(asset.version)}`);
+    if (value.version !== 4) {
+        throw new Error(`[WebUI] Unsupported component asset version: ${String(value.version)}`);
     }
-    if (asset.componentStyles === undefined) {
-        throw new Error('[WebUI] Version 3 component assets require componentStyles.');
+    if (typeof value.root !== 'string' || value.root.length === 0) {
+        throw new Error('[WebUI] Component asset root must name its root component.');
     }
-    if (asset.kind !== expectedKind) {
-        throw new Error(`[WebUI] Expected component asset kind "${expectedKind}", received "${String(asset.kind)}".`);
+    if (value.componentStyles === undefined) {
+        throw new Error('[WebUI] Version 4 component assets require componentStyles.');
     }
-    validateUniqueStringArray(asset.components, 'components');
-    validateUniqueStringArray(asset.requiredComponents, 'requiredComponents');
-    validateUniqueStringArray(asset.externalComponents, 'externalComponents');
-    if (!Array.isArray(asset.imports)) {
+    prepareAssetComponentStyles(value.componentStyles);
+    validateExternalComponents(value.externalComponents);
+    if (!Array.isArray(value.imports)) {
         throw new Error('[WebUI] Component asset imports must be an array.');
     }
-    prepareAssetComponentStyles(asset.componentStyles);
-    if (!isObject(asset.templates)) {
-        throw new Error('[WebUI] Component asset templates must be an object.');
-    }
-    let root;
-    if (expectedKind === 'root') {
-        if (typeof asset.root !== 'string' || asset.root.length === 0) {
-            throw new Error('[WebUI] Component asset root must name its root component.');
+    const providers = new Set(value.externalComponents);
+    for (let i = 0; i < value.imports.length; i++) {
+        const tag = validatePayload(value.imports[i]);
+        if (providers.has(tag)) {
+            throw new Error(`[WebUI] Component asset assigns template <${tag}> to more than one import or external prerequisite.`);
         }
-        root = asset.root;
-    }
-    else {
-        validateChunkShape(asset.root, asset.imports, asset.externalComponents);
+        providers.add(tag);
     }
-    for (let i = 0; i < asset.imports.length; i++) {
-        validateAssetImport(asset.imports[i]);
-    }
-    validateAssetPayload(asset.components, asset.templates, asset.templateFunctions);
-    validateAssetCoverage(root, asset.components, asset.requiredComponents, asset.externalComponents, asset.imports);
-}
-export function sameComponents(left, right) {
-    if (left.length !== right.length)
-        return false;
-    for (let i = 0; i < left.length; i++) {
-        if (left[i] !== right[i])
-            return false;
+    if (!providers.has(value.root)) {
+        throw new Error(`[WebUI] Component asset root <${value.root}> has no imported payload or external prerequisite.`);
     }
-    return true;
 }
 function isObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-function validateChunkShape(root, imports, externalComponents) {
-    if (root !== undefined) {
-        throw new Error('[WebUI] Shared component asset chunks cannot declare a root.');
-    }
-    if (imports.length !== 0) {
-        throw new Error('[WebUI] Shared component asset chunks cannot import other chunks.');
-    }
-    if (externalComponents.length !== 0) {
-        throw new Error('[WebUI] Shared component asset chunks cannot declare external components.');
-    }
-}
-function validateAssetImport(value) {
-    if (!isObject(value)) {
-        throw new Error('[WebUI] Component asset import must be an object.');
-    }
-    const assetImport = value;
-    validateUniqueStringArray(assetImport.components, 'import components');
-    if (assetImport.components.length === 0) {
-        throw new Error('[WebUI] Component asset imports must provide at least one component.');
-    }
-    if (typeof assetImport.href !== 'string' || assetImport.href.length === 0) {
-        throw new Error('[WebUI] Component asset import href must be a non-empty string.');
-    }
-    if (typeof assetImport.load !== 'function') {
-        throw new Error('[WebUI] Component asset import load must be a function.');
-    }
-}
-function validateUniqueStringArray(value, field) {
-    validateStringArray(value, field);
-    const seen = new Set();
-    for (let i = 0; i < value.length; i++) {
-        if (seen.has(value[i])) {
-            throw new Error(`[WebUI] Component asset ${field} cannot contain duplicate <${value[i]}> entries.`);
-        }
-        seen.add(value[i]);
-    }
-}
-function validateStringArray(value, field) {
+function validateExternalComponents(value) {
     if (!Array.isArray(value)) {
-        throw new Error(`[WebUI] Component asset ${field} must be an array.`);
+        throw new Error('[WebUI] Component asset externalComponents must be an array.');
     }
+    const seen = new Set();
     for (let i = 0; i < value.length; i++) {
-        if (typeof value[i] !== 'string' || value[i].length === 0) {
-            throw new Error(`[WebUI] Component asset ${field} must contain non-empty strings.`);
-        }
-    }
-}
-function validateAssetCoverage(root, components, requiredComponents, externalComponents, imports) {
-    const required = new Set(requiredComponents);
-    if (root && !required.has(root)) {
-        throw new Error(`[WebUI] Component asset root <${root}> must include itself in requiredComponents.`);
-    }
-    const providers = new Set();
-    const addProvider = (component) => {
-        if (!required.has(component)) {
-            throw new Error(`[WebUI] Component asset provides undeclared template <${component}>. Add it to requiredComponents.`);
-        }
-        if (providers.has(component)) {
-            throw new Error(`[WebUI] Component asset assigns required template <${component}> to more than one payload, import, or external prerequisite.`);
-        }
-        providers.add(component);
-    };
-    for (let i = 0; i < components.length; i++)
-        addProvider(components[i]);
-    for (let i = 0; i < externalComponents.length; i++)
-        addProvider(externalComponents[i]);
-    for (let i = 0; i < imports.length; i++) {
-        const imported = imports[i].components;
-        for (let j = 0; j < imported.length; j++)
-            addProvider(imported[j]);
-    }
-    for (let i = 0; i < requiredComponents.length; i++) {
-        const component = requiredComponents[i];
-        if (!providers.has(component)) {
-            throw new Error(`[WebUI] Component asset required template <${component}> has no payload, import, or external prerequisite.`);
+        const tag = value[i];
+        if (typeof tag !== 'string' || tag.length === 0 || seen.has(tag)) {
+            throw new Error('[WebUI] Component asset externalComponents must contain unique non-empty strings.');
         }
+        seen.add(tag);
     }
 }
-function validateAssetPayload(components, templates, templateFunctions) {
-    const declared = new Set(components);
-    const templateNames = Object.keys(templates);
-    for (let i = 0; i < templateNames.length; i++) {
-        const template = templateNames[i];
-        if (!declared.has(template)) {
-            throw new Error(`[WebUI] Component asset templates contain undeclared payload <${template}>.`);
-        }
-    }
-    for (let i = 0; i < components.length; i++) {
-        const component = components[i];
-        if (!Object.prototype.hasOwnProperty.call(templates, component)) {
-            throw new Error(`[WebUI] Component asset payload <${component}> is missing its template metadata.`);
-        }
-    }
-    if (templateFunctions === undefined)
-        return;
-    if (!isObject(templateFunctions)) {
-        throw new Error('[WebUI] Component asset templateFunctions must be an object.');
-    }
-    const functionNames = Object.keys(templateFunctions);
-    for (let i = 0; i < functionNames.length; i++) {
-        const component = functionNames[i];
-        if (!declared.has(component)) {
-            throw new Error(`[WebUI] Component asset templateFunctions contains undeclared payload <${component}>.`);
+function validatePayload(value) {
+    if (!isObject(value) || !isObject(value.templates)) {
+        throw new Error('[WebUI] Component asset payload must contain its template metadata.');
+    }
+    const tags = Object.keys(value.templates);
+    if (tags.length !== 1 || tags[0].length === 0) {
+        throw new Error('[WebUI] Component asset payload must contain exactly one template.');
+    }
+    const tag = tags[0];
+    prepareAssetComponentStyles(value.componentStyles);
+    const functions = value.templateFunctions;
+    if (functions !== undefined) {
+        if (!isObject(functions) || Object.keys(functions).some(name => name !== tag)) {
+            throw new Error(`[WebUI] Component asset templateFunctions contains undeclared payload for <${tag}>.`);
         }
-        const functions = templateFunctions[component];
-        if (!Array.isArray(functions) ||
-            functions.some(candidate => typeof candidate !== 'function')) {
-            throw new Error(`[WebUI] Component asset templateFunctions for <${component}> must contain only functions.`);
+        const closures = functions[tag];
+        if (!Array.isArray(closures) || closures.some(candidate => typeof candidate !== 'function')) {
+            throw new Error(`[WebUI] Component asset templateFunctions for <${tag}> must contain only functions.`);
         }
     }
+    return tag;
 }

package/dist/component-asset/loader.d.ts

@@ -1,2 +1,4 @@
+import { type ComponentAsset } from './asset.js';
 import type { ComponentAssetSource } from './manifest.js';
 export declare function loadComponentAsset(tag: string, source: ComponentAssetSource): Promise<void>;
+export declare function registerComponentAsset(asset: ComponentAsset): Promise<void>;

package/dist/component-asset/loader.js

@@ -1,7 +1,6 @@
-import { getTemplate, prepareAssetTemplateData, registerTemplateData, } from '../template.js';
-import { prepareAssetComponentStyles, readComponentAssetModule, sameComponents, validateAsset, } from './asset.js';
-import { hasRegisteredComponentStyleResource, registerPreparedComponentStyles, sameComponentStyleClosure, sameComponentStyleResource, validateComponentStylesRegistration, } from '../element/styles.js';
-import { prepareComponentStyleLinks, prepareRegisteredLinkStyles, } from '../element/link-styles.js';
+import { prepareAssetComponentStyles, readComponentAssetModule, validateAsset, } from './asset.js';
+import { registerComponentAssetGraph } from './registration.js';
+import { validateComponentAssetGraph } from './validate-graph.js';
 const assetModulePromises = new Map();
 export function loadComponentAsset(tag, source) {
     if (typeof source === 'function') {
@@ -16,34 +15,11 @@ export function loadComponentAsset(tag, source) {
 }
 async function registerRootAsset(expectedRoot, href, imported) {
     const asset = readComponentAssetModule(imported);
-    validateAsset(asset, 'root');
+    validateAsset(asset);
     if (asset.root !== expectedRoot) {
         throw new Error(`[WebUI] Component asset manifest expected <${expectedRoot}> but ${href} exports <${String(asset.root)}>.`);
     }
-    validateExternalComponents(asset);
-    const root = prepareComponentPayload(asset);
-    const chunks = await prepareAssetImports(asset.imports);
-    const graph = [...chunks, root];
-    validatePreparedGraph(graph);
-    for (let i = 0; i < chunks.length; i++) {
-        registerComponentResources(chunks[i]);
-    }
-    registerComponentResources(root);
-    let pendingStyles;
-    for (let i = 0; i < chunks.length; i++) {
-        const ready = chunks[i].linkStyles;
-        if (!ready)
-            continue;
-        (pendingStyles ??= []).push(ready);
-    }
-    if (root.linkStyles)
-        (pendingStyles ??= []).push(root.linkStyles);
-    if (pendingStyles)
-        await Promise.all(pendingStyles);
-    for (let i = 0; i < chunks.length; i++) {
-        registerComponentTemplates(chunks[i]);
-    }
-    registerComponentTemplates(root);
+    await registerComponentAssetGraph(asset, prepareAssetComponentStyles, validateComponentAssetGraph);
 }
 function loadAssetModule(href, load) {
     let promise = assetModulePromises.get(href);
@@ -57,124 +33,6 @@ function loadAssetModule(href, load) {
     assetModulePromises.set(href, promise);
     return promise;
 }
-async function prepareAssetImports(imports) {
-    const pending = [];
-    for (let i = 0; i < imports.length; i++) {
-        const assetImport = imports[i];
-        if (componentsAlreadyRegistered(assetImport.components))
-            continue;
-        pending.push(importAndPrepareChunk(assetImport));
-    }
-    return Promise.all(pending);
-}
-function importAndPrepareChunk(assetImport) {
-    const href = new URL(assetImport.href, document.baseURI).href;
-    return loadAssetModule(href, assetImport.load)
-        .then(imported => {
-        const chunk = readComponentAssetModule(imported);
-        validateAsset(chunk, 'chunk');
-        if (!sameComponents(chunk.components, assetImport.components)) {
-            throw new Error(`[WebUI] Shared component asset ${href} does not provide the components declared by its root import.`);
-        }
-        return prepareComponentPayload(chunk);
-    });
-}
-function prepareComponentPayload(asset) {
-    const componentStyles = prepareAssetComponentStyles(asset.componentStyles);
-    prepareAssetTemplateData(asset.templates, asset.templateFunctions);
-    const templateLinkStyles = prepareRegisteredLinkStyles(asset.templates);
-    const componentStyleLinks = prepareComponentStyleLinks(componentStyles);
-    let linkStyles = templateLinkStyles;
-    if (templateLinkStyles && componentStyleLinks) {
-        linkStyles = Promise.all([templateLinkStyles, componentStyleLinks]).then(() => { });
-    }
-    else {
-        linkStyles = templateLinkStyles ?? componentStyleLinks;
-    }
-    return {
-        asset,
-        componentStyles,
-        linkStyles,
-    };
-}
-function registerComponentResources(prepared) {
-    registerPreparedComponentStyles(prepared.componentStyles);
-}
-function registerComponentTemplates(prepared) {
-    const { asset } = prepared;
-    if (componentsAlreadyRegistered(asset.components))
-        return;
-    registerTemplateData(asset.templates, asset.templateFunctions);
-}
-function validatePreparedGraph(graph) {
-    const resources = new Map();
-    const closures = new Map();
-    const provided = new Set();
-    for (let i = 0; i < graph.length; i++) {
-        const prepared = graph[i];
-        validateComponentStylesRegistration(prepared.componentStyles);
-        for (const component of prepared.asset.components)
-            provided.add(component);
-        const styles = prepared.componentStyles;
-        for (const id of Object.keys(styles.resources)) {
-            const resource = styles.resources[id];
-            const current = resources.get(id);
-            if (current && !sameComponentStyleResource(current, resource)) {
-                throw new Error(`[WebUI] Conflicting component style resource "${id}".`);
-            }
-            resources.set(id, resource);
-        }
-        for (const root of Object.keys(styles.closures)) {
-            const closure = styles.closures[root];
-            const current = closures.get(root);
-            if (current && !sameComponentStyleClosure(current, closure)) {
-                throw new Error(`[WebUI] Conflicting component style closure "${root}".`);
-            }
-            closures.set(root, closure);
-        }
-    }
-    for (let i = 0; i < graph.length; i++) {
-        const styles = graph[i].componentStyles;
-        for (const root of Object.keys(styles.closures)) {
-            for (const id of styles.closures[root]) {
-                if (!resources.has(id) &&
-                    !hasRegisteredComponentStyleResource(id)) {
-                    throw new Error(`[WebUI] Component style closure "${root}" references missing resource "${id}".`);
-                }
-            }
-        }
-    }
-    const missing = [];
-    for (let i = 0; i < graph.length; i++) {
-        const asset = graph[i].asset;
-        for (const required of asset.requiredComponents) {
-            if (provided.has(required) || getTemplate(required))
-                continue;
-            if (missing.indexOf(required) < 0)
-                missing.push(required);
-        }
-    }
-    if (missing.length === 0)
-        return;
-    throw new Error(`[WebUI] Component asset is missing required templ${missing.length === 1 ? 'ate' : 'ates'} ${missing.map(tag => `<${tag}>`).join(', ')}. Load the application entry bundle and protocol before deferred component assets.`);
-}
-function componentsAlreadyRegistered(components) {
-    if (components.length === 0)
-        return false;
-    for (let i = 0; i < components.length; i++) {
-        if (!getTemplate(components[i]))
-            return false;
-    }
-    return true;
-}
-function validateExternalComponents(asset) {
-    const missing = [];
-    for (let i = 0; i < asset.externalComponents.length; i++) {
-        const component = asset.externalComponents[i];
-        if (!getTemplate(component))
-            missing.push(component);
-    }
-    if (missing.length === 0)
-        return;
-    throw new Error(`[WebUI] Component asset requires entr${missing.length === 1 ? 'y template' : 'y templates'} ${missing.map(tag => `<${tag}>`).join(', ')}. Load the application entry bundle and protocol before deferred component assets.`);
+export function registerComponentAsset(asset) {
+    return registerRootAsset(typeof asset.root === 'string' ? asset.root : '', 'generated component asset', { default: asset });
 }

package/dist/component-asset/registration.d.ts

@@ -0,0 +1,11 @@
+import { type ComponentStyles } from '../element/styles.js';
+import type { ComponentAsset, ComponentAssetPayload } from './asset.js';
+export interface PreparedComponentAsset {
+    tag: string;
+    payload?: ComponentAssetPayload;
+    componentStyles: ComponentStyles;
+}
+type PrepareStyles = (value: unknown) => ComponentStyles;
+export type ValidateComponentAssetGraph = (graph: readonly PreparedComponentAsset[]) => void;
+export declare function registerComponentAssetGraph(asset: ComponentAsset, prepareStyles?: PrepareStyles, validateGraph?: ValidateComponentAssetGraph): Promise<void>;
+export {};

package/dist/component-asset/registration.js

@@ -0,0 +1,63 @@
+import { getTemplate, prepareAssetTemplateData, registerTemplateData, } from '../template.js';
+import { registerPreparedComponentStyles, validateComponentStylesRegistration, } from '../element/styles.js';
+import { prepareComponentStyleLinks, prepareRegisteredLinkStyles, } from '../element/link-styles.js';
+export async function registerComponentAssetGraph(asset, prepareStyles = trustedComponentStyles, validateGraph) {
+    const graph = [];
+    for (let i = 0; i < asset.imports.length; i++) {
+        const payload = asset.imports[i];
+        const styles = prepareStyles(payload.componentStyles);
+        validateComponentStylesRegistration(styles);
+        graph.push({
+            tag: Object.keys(payload.templates)[0],
+            payload,
+            componentStyles: styles,
+        });
+    }
+    const rootStyles = prepareStyles(asset.componentStyles);
+    validateComponentStylesRegistration(rootStyles);
+    graph.push({ tag: asset.root, componentStyles: rootStyles });
+    validateGraph?.(graph);
+    validateExternalTemplates(asset.externalComponents);
+    for (let i = 0; i < graph.length; i++) {
+        const prepared = graph[i];
+        const payload = prepared.payload;
+        if (payload && !getTemplate(prepared.tag)) {
+            prepareAssetTemplateData(payload.templates, payload.templateFunctions);
+        }
+    }
+    const pendingStyles = [];
+    for (let i = 0; i < graph.length; i++) {
+        const prepared = graph[i];
+        const payload = prepared.payload;
+        const templateLinks = payload && prepareRegisteredLinkStyles(payload.templates);
+        const componentLinks = prepareComponentStyleLinks(prepared.componentStyles);
+        if (templateLinks)
+            pendingStyles.push(templateLinks);
+        if (componentLinks)
+            pendingStyles.push(componentLinks);
+    }
+    for (let i = 0; i < graph.length; i++) {
+        registerPreparedComponentStyles(graph[i].componentStyles);
+    }
+    if (pendingStyles.length > 0)
+        await Promise.all(pendingStyles);
+    for (let i = 0; i < graph.length; i++) {
+        const payload = graph[i].payload;
+        if (payload && !getTemplate(graph[i].tag)) {
+            registerTemplateData(payload.templates, payload.templateFunctions);
+        }
+    }
+}
+function validateExternalTemplates(external) {
+    const missing = [];
+    for (let i = 0; i < external.length; i++) {
+        if (!getTemplate(external[i]))
+            missing.push(external[i]);
+    }
+    if (missing.length > 0) {
+        throw new Error(`[WebUI] Component asset requires entr${missing.length === 1 ? 'y template' : 'y templates'} ${missing.map(tag => `<${tag}>`).join(', ')}. Load the application entry bundle and protocol before deferred component assets.`);
+    }
+}
+function trustedComponentStyles(value) {
+    return value;
+}

package/dist/component-asset/validate-graph.d.ts

@@ -0,0 +1,2 @@
+import type { PreparedComponentAsset } from './registration.js';
+export declare function validateComponentAssetGraph(graph: readonly PreparedComponentAsset[]): void;

package/dist/component-asset/validate-graph.js

@@ -0,0 +1,42 @@
+import { hasRegisteredComponentStyleResource, sameComponentStyleClosure, sameComponentStyleResource, } from '../element/styles.js';
+export function validateComponentAssetGraph(graph) {
+    const resources = new Map();
+    const closures = new Map();
+    for (let i = 0; i < graph.length; i++) {
+        const styles = graph[i].componentStyles;
+        const resourceIds = Object.keys(styles.resources);
+        for (let j = 0; j < resourceIds.length; j++) {
+            const id = resourceIds[j];
+            const resource = styles.resources[id];
+            const current = resources.get(id);
+            if (current && !sameComponentStyleResource(current, resource)) {
+                throw new Error(`[WebUI] Conflicting component style resource "${id}".`);
+            }
+            resources.set(id, resource);
+        }
+        const roots = Object.keys(styles.closures);
+        for (let j = 0; j < roots.length; j++) {
+            const root = roots[j];
+            const closure = styles.closures[root];
+            const current = closures.get(root);
+            if (current && !sameComponentStyleClosure(current, closure)) {
+                throw new Error(`[WebUI] Conflicting component style closure "${root}".`);
+            }
+            closures.set(root, closure);
+        }
+    }
+    for (let i = 0; i < graph.length; i++) {
+        const styles = graph[i].componentStyles;
+        const roots = Object.keys(styles.closures);
+        for (let j = 0; j < roots.length; j++) {
+            const root = roots[j];
+            const closure = styles.closures[root];
+            for (let k = 0; k < closure.length; k++) {
+                const id = closure[k];
+                if (!resources.has(id) && !hasRegisteredComponentStyleResource(id)) {
+                    throw new Error(`[WebUI] Component style closure "${root}" references missing resource "${id}".`);
+                }
+            }
+        }
+    }
+}

package/dist/component-asset-runtime.d.ts

@@ -0,0 +1,7 @@
+import type { ComponentAsset } from './component-asset/asset.js';
+export interface GeneratedComponentAsset {
+    preload(): Promise<void>;
+    create(): Promise<HTMLElement>;
+}
+export declare function preloadComponentAssetStyles(root: string): void;
+export declare function defineComponentAsset(asset: ComponentAsset): GeneratedComponentAsset;

package/dist/component-asset-runtime.js

@@ -0,0 +1,38 @@
+import { registerComponentAssetGraph } from './component-asset/registration.js';
+import { takeGeneratedComponentAssetStyles } from './component-asset/generated-manifest.js';
+import { preloadComponentAssetStyles as preloadComponentAssetStylesInternal } from './element/link-styles.js';
+const facades = new WeakMap();
+export function preloadComponentAssetStyles(root) {
+    const styles = takeGeneratedComponentAssetStyles(root);
+    if (styles)
+        preloadComponentAssetStylesInternal(styles);
+}
+export function defineComponentAsset(asset) {
+    if (asset.type !== 'webui-component-asset' || asset.version !== 4) {
+        throw new Error('[WebUI] Expected a version 4 component asset root. Rebuild generated inputs with a compatible compiler.');
+    }
+    const existing = facades.get(asset);
+    if (existing)
+        return existing;
+    const root = asset.root;
+    let pending;
+    const preload = () => {
+        if (pending)
+            return pending;
+        preloadComponentAssetStyles(root);
+        const next = registerComponentAssetGraph(asset).catch((error) => {
+            if (pending === next)
+                pending = undefined;
+            throw error;
+        });
+        pending = next;
+        return next;
+    };
+    const create = async () => {
+        await preload();
+        return document.createElement(root);
+    };
+    const facade = { preload, create };
+    facades.set(asset, facade);
+    return facade;
+}

package/dist/component-asset.d.ts

@@ -1,4 +1,4 @@
 import type { ComponentAssetManifest, ComponentAssetRegistry } from './component-asset/manifest.js';
-export type { ComponentAsset, ComponentAssetImport, } from './component-asset/asset.js';
+export type { ComponentAsset, ComponentAssetPayload, } from './component-asset/asset.js';
 export type { ComponentAssetCreateOptions, ComponentAssetManifest, ComponentAssetManifestEntry, ComponentAssetPreload, ComponentAssetRegistry, ComponentAssetSource, ComponentAssetState, } from './component-asset/manifest.js';
 export declare function defineComponentAssets(manifest: ComponentAssetManifest): ComponentAssetRegistry;

package/dist/decorators.js

@@ -162,6 +162,12 @@ function createReactiveProperty(proto, name, attrDefinition) {
             return this[backingKey];
         },
         set(newValue) {
+            const captured = this['$preUpgradeProperties'];
+            if (captured?.has(name) && this.matches(':defined')) {
+                captured.delete(name);
+                if (captured.size === 0)
+                    this['$preUpgradeProperties'] = undefined;
+            }
             const oldValue = this[backingKey];
             if (Object.is(oldValue, newValue)) {
                 if (this['$deferredSSR'] === true) {
@@ -172,12 +178,33 @@ function createReactiveProperty(proto, name, attrDefinition) {
                 return;
             }
             this[backingKey] = newValue;
-            if (attrDefinition && this['$ready'] === true) {
-                reflectPropertyToAttribute(this, attrDefinition, newValue);
+            let canReflect = false;
+            if (attrDefinition) {
+                const checkReflection = this['$canRunAuthoredEffects'];
+                if (typeof checkReflection === 'function' &&
+                    checkReflection.call(this)) {
+                    reflectPropertyToAttribute(this, attrDefinition, newValue);
+                    canReflect = true;
+                }
             }
-            const cb = this[changedKey];
-            if (typeof cb === 'function') {
-                cb.call(this, oldValue, newValue);
+            const callback = this[changedKey];
+            if (typeof callback === 'function') {
+                if (this['$authoredPhase'] === 1 &&
+                    (attrDefinition ? canReflect : this.isConnected)) {
+                    callback
+                        .call(this, oldValue, newValue);
+                }
+                else {
+                    const record = this['$recordPropertyChange'];
+                    if (typeof record === 'function') {
+                        record
+                            .call(this, name, oldValue);
+                    }
+                    else {
+                        callback
+                            .call(this, oldValue, newValue);
+                    }
+                }
             }
             if (this.isConnected ||
                 this['$deferredSSR'] === true) {
@@ -234,9 +261,16 @@ function applyAttr(target, name, options) {
             const definition = attrDefinitionFor(this.constructor, attribute);
             if (definition !== undefined &&
                 this[reflectingAttribute] !== attribute) {
-                this[definition.property] = definition.boolean
-                    ? newVal !== null
-                    : newVal;
+                const captured = this['$preUpgradeProperties'];
+                if (captured)
+                    this['$preUpgradeProperties'] = undefined;
+                try {
+                    this[definition.property] = definition.boolean ? newVal !== null : newVal;
+                }
+                finally {
+                    if (captured)
+                        this['$preUpgradeProperties'] = captured;
+                }
             }
             if (origACB) {
                 origACB.call(this, attribute, oldVal, newVal);

package/dist/element.d.ts

@@ -4,6 +4,18 @@ import type { TemplateBlockMeta, TemplateMeta, TemplateNodeIndex } from './templ
 import type { ScopeFrame, TemplateInstance } from './element/types.js';
 export declare class WebUIElement extends TemplateElement {
     private $lazyHydrationMode;
+    private $authoredPhase;
+    private $pendingPropertyChanges;
+    private $preUpgradeProperties;
+    constructor();
+    connectedCallback(): void;
+    $destroy(): void;
+    $recordPropertyChange(name: string, oldValue: unknown): void;
+    protected $reconcileAuthoredState(): boolean;
+    $flushUpdates(): void;
+    private $flushAuthoredChanges;
+    private $invokePropertyChange;
+    private $releasePropertyChanges;
     protected $shouldDeferSSRHydration(meta?: TemplateMeta): boolean;
     protected $didDeferSSRHydration(): void;
     protected $didDeferStreamedSSRHydration(state: Record<string, unknown> | undefined): void;

package/dist/element.js

@@ -7,6 +7,9 @@ const RENDER_ATTR = 'w-render';
 const HYDRATE_EAGER = 'eager';
 const INTERACTION_HYDRATION = 3;
 const LAZY_RENDER_INTERACTION = 4;
+const AUTHORED_LIVE = 1;
+const AUTHORED_PENDING = 2;
+const AUTHORED_FLUSHING = 4;
 const DEV = typeof __WEBUI_DEV__ === 'undefined' || __WEBUI_DEV__;
 let warnedMissingLazyHydrationEntry = false;
 function warnMissingLazyHydrationEntry(tag, policy) {
@@ -22,6 +25,121 @@ function warnMissingLazyHydrationEntry(tag, policy) {
         'your component definitions to enable visibility-deferred hydration.');
 }
 export class WebUIElement extends TemplateElement {
+    constructor() {
+        super();
+        const names = getObservableNames(this.constructor);
+        for (const name of names) {
+            if (!Object.prototype.hasOwnProperty.call(this, name))
+                continue;
+            (this.$preUpgradeProperties ??= new Map()).set(name, this[name]);
+            delete this[name];
+        }
+    }
+    connectedCallback() {
+        const properties = this.$preUpgradeProperties;
+        if (properties) {
+            this.$preUpgradeProperties = undefined;
+            for (const [name, value] of properties) {
+                this[name] = value;
+            }
+        }
+        super.connectedCallback();
+    }
+    $destroy() {
+        if (this.$authoredPhase !== undefined)
+            this.$authoredPhase &= ~AUTHORED_LIVE;
+        super.$destroy();
+    }
+    $recordPropertyChange(name, oldValue) {
+        if (this.$authoredPhase === undefined)
+            return;
+        const changes = this.$pendingPropertyChanges;
+        if ((this.$authoredPhase & AUTHORED_LIVE) && this.$canRunAuthoredEffects()) {
+            if (changes?.has(name)) {
+                oldValue = changes.get(name);
+                changes.delete(name);
+            }
+            try {
+                this.$invokePropertyChange(name, oldValue);
+            }
+            finally {
+                this.$releasePropertyChanges();
+            }
+        }
+        else {
+            const queued = changes ?? (this.$pendingPropertyChanges = new Map());
+            if (!queued.has(name))
+                queued.set(name, oldValue);
+            this.$authoredPhase |= AUTHORED_PENDING;
+        }
+    }
+    $reconcileAuthoredState() {
+        if (!this.$canRunAuthoredEffects())
+            return !this.$pendingPropertyChanges;
+        if (this.$authoredPhase === undefined) {
+            const names = getObservableNames(this.constructor);
+            for (const name of names) {
+                if (typeof this[`${name}Changed`] !== 'function')
+                    continue;
+                this.$authoredPhase = AUTHORED_LIVE;
+                if (Object.prototype.hasOwnProperty.call(this, `_${name}`)) {
+                    (this.$pendingPropertyChanges ??= new Map()).set(name, undefined);
+                }
+            }
+        }
+        if (this.$authoredPhase === undefined)
+            return true;
+        this.$authoredPhase |= AUTHORED_LIVE;
+        if (this.$authoredPhase & AUTHORED_FLUSHING)
+            return false;
+        if (this.$pendingPropertyChanges) {
+            this.$authoredPhase |= AUTHORED_PENDING;
+            this.$flushAuthoredChanges();
+        }
+        return !this.$pendingPropertyChanges;
+    }
+    $flushUpdates() {
+        if (this.$pendingPropertyChanges)
+            this.$notifyHydrated();
+        super.$flushUpdates();
+    }
+    $flushAuthoredChanges() {
+        const changes = this.$pendingPropertyChanges;
+        if (!changes || !this.$canRunAuthoredEffects())
+            return;
+        this.$authoredPhase = AUTHORED_LIVE | AUTHORED_PENDING | AUTHORED_FLUSHING;
+        try {
+            for (const [name, oldValue] of changes) {
+                if (!this.$canRunAuthoredEffects()) {
+                    this.$authoredPhase &= ~AUTHORED_LIVE;
+                    break;
+                }
+                changes.delete(name);
+                this.$invokePropertyChange(name, oldValue);
+            }
+        }
+        finally {
+            this.$authoredPhase &= ~AUTHORED_FLUSHING;
+            this.$releasePropertyChanges();
+        }
+    }
+    $invokePropertyChange(name, oldValue) {
+        const value = this[name];
+        if (Object.is(oldValue, value))
+            return;
+        const callback = this[`${name}Changed`];
+        if (typeof callback === 'function') {
+            callback.call(this, oldValue, value);
+        }
+    }
+    $releasePropertyChanges() {
+        const phase = this.$authoredPhase;
+        if (phase !== undefined && this.$pendingPropertyChanges?.size === 0 &&
+            !(phase & AUTHORED_FLUSHING)) {
+            this.$pendingPropertyChanges = undefined;
+            this.$authoredPhase = phase & ~AUTHORED_PENDING;
+        }
+    }
     $shouldDeferSSRHydration(meta) {
         this.$lazyHydrationMode = this.$resolveLazyHydrationMode(meta);
         return this.$lazyHydrationMode !== undefined;
@@ -90,6 +208,8 @@ export class WebUIElement extends TemplateElement {
         this.$activateDeferredSSR(state);
     }
     disconnectedCallback() {
+        if (this.$authoredPhase !== undefined)
+            this.$authoredPhase &= ~AUTHORED_LIVE;
         if (this.$lazyHydrationMode !== undefined) {
             disconnectLazyHydration(this);
         }
@@ -103,7 +223,8 @@ export class WebUIElement extends TemplateElement {
         return attribute === undefined || !this.hasAttribute(attribute);
     }
     $syncAuthoredAttributes() {
-        syncAttrProperties(this, this.constructor);
+        if (this.isConnected)
+            syncAttrProperties(this, this.constructor);
     }
     $emit(name, detail) {
         return this.dispatchEvent(new CustomEvent(name, {

package/dist/template-content.d.ts

@@ -12,7 +12,7 @@ export interface TemplateStylesheetDescriptor {
     readonly title: string;
     readonly type: string;
 }
-export declare function cloneTemplateContent(meta: TemplateBlockMeta): DocumentFragment;
+export declare function cloneTemplateContent(meta: TemplateBlockMeta, ownerDocument: Document): DocumentFragment;
 export declare function getTemplateFragment(meta: TemplateBlockMeta): DocumentFragment;
 export declare function getTemplateStylesheets(meta: TemplateBlockMeta): readonly TemplateStylesheetDescriptor[] | undefined;
 export declare function templateHtmlMayContainLink(html: string): boolean;

package/dist/template-content.js

@@ -2,8 +2,8 @@ import { setTemplateContent } from './trusted-types-policy.js';
 const EMPTY_STYLESHEETS = Object.freeze([]);
 const NO_LINK_STYLESHEETS = Object.freeze([]);
 const templateContentCache = new WeakMap();
-export function cloneTemplateContent(meta) {
-    return getTemplateFragment(meta).cloneNode(true);
+export function cloneTemplateContent(meta, ownerDocument) {
+    return ownerDocument.importNode(getTemplateFragment(meta), true);
 }
 export function getTemplateFragment(meta) {
     return getTemplateContent(meta).fragment;

package/dist/template-element.d.ts

@@ -19,7 +19,7 @@ export declare class TemplateElement extends HTMLElement {
     private $hydrated;
     private $deferredClientMount;
     private $resetClientShadow;
-    private $hasMounted;
+    private $mountPhase;
     private $deferredSSR;
     private $activatingDeferredSSR;
     private $deferredAncestor;
@@ -78,7 +78,7 @@ export declare class TemplateElement extends HTMLElement {
     protected $shouldApplySSRState(_key: string): boolean;
     protected $syncAuthoredAttributes(): void;
     protected hydratedCallback(): void;
-    private $notifyHydrated;
+    protected $notifyHydrated(): void;
     private $finishHydration;
     protected $shouldApplyTemplateStateFromSSR(_key: string): boolean;
     protected $setTemplateState(key: string, value: unknown): boolean;
@@ -93,6 +93,8 @@ export declare class TemplateElement extends HTMLElement {
     private $recordDeferredWrite;
     private $replayDeferredWrites;
     $flushUpdates(): void;
+    protected $reconcileAuthoredState(): boolean;
+    protected $canRunAuthoredEffects(): boolean;
     private $flush;
     private $recordPreReadyWrite;
     private $checkHydrationMismatch;

package/dist/template-element.js

@@ -204,6 +204,8 @@ function hasAuthoredMember(instance, key) {
     }
     return false;
 }
+const MOUNTED = 1;
+const HYDRATION_NOTIFIED = 2;
 export class TemplateElement extends HTMLElement {
     constructor() {
         super(...arguments);
@@ -212,7 +214,7 @@ export class TemplateElement extends HTMLElement {
         this.$hydrated = false;
         this.$deferredClientMount = false;
         this.$resetClientShadow = false;
-        this.$hasMounted = false;
+        this.$mountPhase = 0;
         this.$deferredSSR = false;
         this.$activatingDeferredSSR = false;
         this.$hasUnknownScopes = false;
@@ -322,6 +324,8 @@ export class TemplateElement extends HTMLElement {
             hydrationStart();
             try {
                 this.$ready = true;
+                this.$syncAuthoredAttributes();
+                this.$notifyHydrated();
                 this.$update();
             }
             finally {
@@ -329,7 +333,7 @@ export class TemplateElement extends HTMLElement {
             }
             return;
         }
-        if (!this.$hasMounted &&
+        if (!this.$mountPhase &&
             isStreamingHydrationMode() &&
             this.hasAttribute(STREAMED_HOST_ATTR)) {
             this.$deferredSSR = true;
@@ -346,7 +350,7 @@ export class TemplateElement extends HTMLElement {
             return;
         }
         this.$meta = meta;
-        if (this.$hasMounted) {
+        if (this.$mountPhase) {
             this.$remount(meta);
         }
         else {
@@ -856,10 +860,14 @@ export class TemplateElement extends HTMLElement {
     hydratedCallback() {
     }
     $notifyHydrated() {
-        if (this.$hasMounted)
+        if (!this.$mountPhase)
+            this.$mountPhase = MOUNTED;
+        if (!this.$reconcileAuthoredState())
             return;
-        this.$hasMounted = true;
-        this.hydratedCallback();
+        if (this.$mountPhase === MOUNTED) {
+            this.$mountPhase = HYDRATION_NOTIFIED;
+            this.hydratedCallback();
+        }
     }
     $finishHydration() {
         let callbackFailed = false;
@@ -1031,9 +1039,18 @@ export class TemplateElement extends HTMLElement {
         this.$flush(true);
     }
     $flushUpdates() {
+        if (this.$mountPhase === MOUNTED)
+            this.$notifyHydrated();
         if (this.$pendingFlush)
             this.$flush();
     }
+    $reconcileAuthoredState() {
+        return true;
+    }
+    $canRunAuthoredEffects() {
+        return this.$hydrated && this.$root !== null && this.$ready &&
+            !this.$deferredClientMount && this.isConnected;
+    }
     $flush(requireKnownState = this.$guardUnknownState === true) {
         if (!this.$ready || !this.$root) {
             this.$dirtyPaths = null;
@@ -1108,10 +1125,10 @@ export class TemplateElement extends HTMLElement {
         void import('./hydration-mismatch.js').then((m) => m.reportHydrationMismatch(tag, writes, index, ctx));
     }
     $parseTemplate(meta) {
-        return cloneTemplateContent(meta);
+        return cloneTemplateContent(meta, this.ownerDocument);
     }
     $createStagingRoot(meta) {
-        const wrapper = document.createElement('div');
+        const wrapper = this.ownerDocument.createElement('div');
         const fragment = this.$parseTemplate(meta);
         wrapper.appendChild(fragment);
         customElements.upgrade(wrapper);
@@ -1125,7 +1142,7 @@ export class TemplateElement extends HTMLElement {
             root.appendChild(first);
             return;
         }
-        const fragment = document.createDocumentFragment();
+        const fragment = this.ownerDocument.createDocumentFragment();
         while (stagingRoot.firstChild) {
             fragment.appendChild(stagingRoot.firstChild);
         }
@@ -1157,6 +1174,7 @@ export class TemplateElement extends HTMLElement {
         }
     }
     $wire(root, meta, scope) {
+        const ownerDocument = this.ownerDocument;
         const instance = {
             scope, container: root, nodes: childNodesArray(root),
             texts: bindingArray(meta.tx?.length ?? 0),
@@ -1181,8 +1199,8 @@ export class TemplateElement extends HTMLElement {
                 let node;
                 let end;
                 if (raw) {
-                    const start = document.createComment(rawMarker(rawIndex));
-                    end = document.createComment(rawMarker(rawIndex, true));
+                    const start = ownerDocument.createComment(rawMarker(rawIndex));
+                    end = ownerDocument.createComment(rawMarker(rawIndex, true));
                     rawIndex++;
                     instance.texts.push({
                         node: start,
@@ -1195,7 +1213,7 @@ export class TemplateElement extends HTMLElement {
                     node = start;
                 }
                 else {
-                    const textNode = document.createTextNode('');
+                    const textNode = ownerDocument.createTextNode('');
                     instance.texts.push({ node: textNode, parts, scope });
                     node = textNode;
                 }
@@ -1217,7 +1235,7 @@ export class TemplateElement extends HTMLElement {
                 const parent = elements[parentIndex];
                 if (!parent || (parent.nodeType !== 1 && parent.nodeType !== 11))
                     continue;
-                const anchor = document.createComment('');
+                const anchor = ownerDocument.createComment('');
                 instance.conds.push({
                     condition: condition,
                     blockIndex,
@@ -1243,7 +1261,7 @@ export class TemplateElement extends HTMLElement {
                 const parent = elements[parentIndex];
                 if (!parent || (parent.nodeType !== 1 && parent.nodeType !== 11))
                     continue;
-                const anchor = document.createComment('');
+                const anchor = ownerDocument.createComment('');
                 const binding = {
                     markerId: i, collection, itemVar, blockIndex,
                     container: parent, start: anchor, end: null,
@@ -1271,6 +1289,7 @@ export class TemplateElement extends HTMLElement {
         return instance;
     }
     $hydrate(ssrRoot, meta, tplDom, scope, pathStart = 0) {
+        const ownerDocument = this.ownerDocument;
         const instance = {
             scope,
             container: (pathStart > 0 ? ssrRoot.parentNode : ssrRoot),
@@ -1334,7 +1353,7 @@ export class TemplateElement extends HTMLElement {
                     }
                     let textNode = previous?.nodeType === 3 ? previous : null;
                     if (textNode === null) {
-                        textNode = document.createTextNode('');
+                        textNode = ownerDocument.createTextNode('');
                         ssrParent.insertBefore(textNode, insertRef);
                     }
                     instance.texts.push({ node: textNode, parts, scope });
@@ -1356,7 +1375,7 @@ export class TemplateElement extends HTMLElement {
                     condAnchor = marker;
                 }
                 else {
-                    condAnchor = document.createComment('');
+                    condAnchor = ownerDocument.createComment('');
                     const [, beforeIndex] = slotMeta;
                     const insertRef = ssrParent.childNodes[beforeIndex ?? ssrParent.childNodes.length] ?? null;
                     ssrParent.insertBefore(condAnchor, insertRef);
@@ -1405,7 +1424,7 @@ export class TemplateElement extends HTMLElement {
                     anchor = marker;
                 }
                 else {
-                    anchor = document.createComment('');
+                    anchor = ownerDocument.createComment('');
                     const [, beforeIndex] = slotMeta;
                     const tplParent = tplElements[parentIndex];
                     const staticCount = tplParent ? tplParent.childNodes.length : 0;
@@ -1447,7 +1466,7 @@ export class TemplateElement extends HTMLElement {
                         else {
                             const itemParent = itemMarkers[j].parentNode;
                             const nextBound = j + 1 < itemMarkers.length ? itemMarkers[j + 1] : endMarker;
-                            const wrapper = document.createElement('div');
+                            const wrapper = ownerDocument.createElement('div');
                             let cursor = itemMarkers[j].nextSibling;
                             while (cursor && cursor !== nextBound) {
                                 const next = cursor.nextSibling;
@@ -1553,7 +1572,7 @@ export class TemplateElement extends HTMLElement {
         const condNodes = this.$collectConditionalRange(condAnchor);
         if (condNodes.length === 0)
             return null;
-        const wrapper = document.createElement('div');
+        const wrapper = this.ownerDocument.createElement('div');
         for (let cn = 0; cn < condNodes.length; cn++)
             wrapper.appendChild(condNodes[cn]);
         const inst = this.$hydrate(wrapper, blockMeta, tplDom, scope);
@@ -2006,7 +2025,7 @@ export class TemplateElement extends HTMLElement {
             const first = instance.nodes[0] ?? null;
             const container = first?.parentNode;
             if (first && container) {
-                const anchor = document.createComment('');
+                const anchor = this.ownerDocument.createComment('');
                 container.insertBefore(anchor, first);
                 this.$swapOwnedRange(c.owner, instance.nodes, anchor);
                 c.anchor = anchor;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/webui-framework",
-  "version": "0.0.29",
+  "version": "3.0.0",
   "publishConfig": {
     "tag": "latest"
   },
@@ -20,6 +20,12 @@
         "default": "./dist/component-asset.js"
       }
     },
+    "./component-asset-runtime.js": {
+      "import": {
+        "types": "./dist/component-asset-runtime.d.ts",
+        "default": "./dist/component-asset-runtime.js"
+      }
+    },
     "./streaming.js": {
       "import": {
         "types": "./dist/streaming-entry.d.ts",
@@ -43,7 +49,7 @@
     "dist/"
   ],
   "devDependencies": {
-    "@microsoft/webui-test-support": "0.0.29",
+    "@microsoft/webui-test-support": "3.0.0",
     "@playwright/test": "^1.63.0",
     "@types/node": "^26.5.1",
     "typescript": "7.0.2"