@microsoft/webui-framework 0.0.30 → 3.0.0

package/README.md

@@ -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/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.js

@@ -1125,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);
@@ -1142,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);
         }
@@ -1174,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),
@@ -1198,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,
@@ -1212,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;
                 }
@@ -1234,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,
@@ -1260,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,
@@ -1288,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),
@@ -1351,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 });
@@ -1373,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);
@@ -1422,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;
@@ -1464,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;
@@ -1570,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);
@@ -2023,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.30",
+  "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.30",
+    "@microsoft/webui-test-support": "3.0.0",
     "@playwright/test": "^1.63.0",
     "@types/node": "^26.5.1",
     "typescript": "7.0.2"