@microsoft/webui-framework 0.0.17 → 0.0.19

package/README.md

@@ -6,9 +6,9 @@ This package is the browser-side runtime used by `webui build --plugin=webui`. I
 
 - `WebUIElement` for SSR hydration and client-created elements
 - `@observable`, `@attr`, and `@volatile` decorators
-- compiled template path mapping for direct DOM binding resolution
+- direct DOM binding updates
 - light DOM or shadow DOM rendering (`--dom=light|shadow` flag)
-- SSR state seeding from `window.__webui.state` (like Preact's props)
+- SSR state seeding
 
 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`.
 
@@ -87,13 +87,44 @@ Build with `--dom=shadow` (default) to wrap in a declarative shadow root, or `--
 <counter-card label="Taps"></counter-card>
 ```
 
+### HTML-only dormant components
+
+If a component has no event handlers, custom lifecycle code, or client-only
+methods, it can ship only `component.html` and optional `component.css`.
+
+The sibling `.ts` or `.js` file is the authored behavior boundary. With
+manifest-enabled projection, only `@observable` and `@attr` fields opt into
+initial state hydration; template-only roots stay in the trusted SSR DOM.
+Without a module, template bindings render on the server and the component
+contributes no projected keys. Without projection metadata, the server
+preserves full state. The compiler still emits template metadata for scriptless
+components. When the framework is loaded, it can activate that template when
+browser state or client-side creation needs it.
+If that first write omits a repeat collection, the host preserves the existing
+SSR items until the collection is explicitly supplied.
+
+Create a custom element only for an Interactive Island: event handlers, custom
+lifecycle code, imperative methods, or state that TypeScript code reads or
+mutates. `@observable` and `@attr` are optional; add them when JavaScript needs
+to access the value or when the value is part of the component's public API.
+
 ### Build with the WebUI plugin
 
 ```bash
 cargo run -p microsoft-webui-cli -- build ./src --out ./dist --plugin=webui
 ```
 
-The compiler/plugin generates the template metadata and condition closure arrays consumed by the runtime. In normal app code, you should not need to hand-author `window.__webui.templates` or `window.__webui.templateFns`.
+The WebUI plugin prepares component templates for the browser. Bundle your
+source browser entry directly. Import `@microsoft/webui-framework` from authored
+component modules. An app that stays static after SSR needs no framework
+browser import. Import the framework once when HTML-only components must accept
+browser state or participate in soft navigation.
+
+The plugin alone preserves full server state. To emit exact `@observable` and
+`@attr` state surfaces, run the application's bundler first with
+`@microsoft/webui/projection.js`, then pass its manifest to `webui build` with
+`--projection-manifest`. The manifest tooling is build-only; this runtime
+package does not depend on esbuild or TypeScript.
 
 ### Property binding lifecycle
 
@@ -103,7 +134,29 @@ Property bindings use the `:` prefix to pass values directly to child DOM proper
 <profile-card :config="{{settings}}"></profile-card>
 ```
 
-For client-created component trees, the runtime upgrades the cloned child elements while they are still detached, wires bindings, and applies the first binding pass before appending them to the connected DOM. A child can read an initial parent-provided property in `connectedCallback`. If the parent value is not set, the child may initialize its own fallback there, and later parent updates still flow through the live binding.
+For client-created component trees, WebUI applies initial property bindings
+before child `connectedCallback` methods run. A child can read an initial
+parent-provided property in `connectedCallback`. If the parent value is not set,
+the child may initialize its own fallback there, and later parent updates still
+flow through the live binding.
+
+During SSR hydration the framework trusts the server-rendered DOM and does not
+re-render it. An `@observable` written before hydration finishes — in a field
+initializer, the `constructor`, or before `super.connectedCallback()` — cannot
+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 after `super.connectedCallback()`. 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
+`false`). See the
+[Interactivity Guide](https://microsoft.github.io/webui/guide/concepts/interactivity#setting-observable-state-during-setup).
+
+`super.connectedCallback()` is the synchronous hydration boundary for an
+authored component. When it returns, bindings, events, and `w-ref` references
+are wired. Use a parser-inserted, non-async ES module script or a classic
+`defer` script. A blocking classic script must follow every SSR instance it may
+upgrade. Descendants must not structurally mutate a containing component's SSR
+subtree before it hydrates, because hydration relies on stable compiled paths.
 
 ### DOM strategy (`--dom`)
 
@@ -135,15 +188,50 @@ Base class for framework components.
 | `static define(tagName)` | Register the class as a custom element |
 | `$emit(name, detail?)` | Dispatch a bubbling, composed `CustomEvent` |
 | `$update()` | Force a reactive update (normally called automatically) |
-| `setState(state)` | Populate `@observable` properties from router/server state |
 | `disconnectedCallback()` | Override for cleanup (global listeners, etc.) |
 
 In most components you do not call `$update()` directly. Property changes through `@observable` and `@attr` trigger updates for you.
 
+### 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`:
+
+```ts
+import { settingsAssets } from './lazy-assets.js';
+
+settingsAssets.preload('settings-dialog');
+panelSlot.replaceChildren(await settingsAssets.create('settings-dialog'));
+```
+
+```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(),
+  },
+});
+```
+
+The asset module carries the component's template and style payload. Use
+`preload(tag)` to start template, module, and optional data work early, then
+`create(tag)` to create the element after template/module work is ready.
+Concurrent asset requests share one in-flight load and CSS module styles are
+deduped. `create(tag)` 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.
+
 ### `@observable`
 
-Marks a property as reactive.  When the value changes, the framework
-re-evaluates the compiled bindings that reference it.
+Marks a property as reactive. When the value changes, the framework
+updates template bindings that reference it. Use it for state that TypeScript
+code reads or mutates. Values used only by the template do not need an
+`@observable` class field.
 
 ```ts
 class SearchPanel extends WebUIElement {
@@ -170,7 +258,8 @@ Notes:
 
 - default attribute names use kebab-case
 - attribute values arrive as strings
-- use `@observable` for richer client-only state
+- during SSR hydration, an existing host attribute wins over projected state
+- use `@observable` for state that client code reads or mutates
 
 ### `@volatile`
 
@@ -189,7 +278,7 @@ class CartSummary extends WebUIElement {
 
 ## Template Features
 
-The WebUI plugin compiles these template features into runtime metadata:
+The WebUI plugin supports these template features:
 
 - text bindings: `{{title}}`
 - attribute bindings: `href="{{item.href}}"`
@@ -198,6 +287,10 @@ The WebUI plugin compiles these template features into runtime metadata:
 - conditionals: `<if condition="...">`
 - repeats: `<for each="item in items">`
 
+Components that use `@event` must have authored `.ts` or `.js` code that
+defines a `WebUIElement` for the tag. HTML-only components do not provide
+application event handlers.
+
 Example from `examples/app/todo-webui`:
 
 ```html
@@ -222,11 +315,17 @@ Root-level events (e.g. `@toggle-item="{onToggleItem(e)}"`) can be declared on t
 
 ## Recommended Patterns
 
-- Treat decorated properties as the source of truth.
+- Treat decorated properties as the source of truth for state used by
+  TypeScript code.
 - Update state with property assignments such as `this.open = !this.open`.
 - Use `$emit()` for child-to-parent communication.
 - Use `w-ref` for true DOM-only concerns like focus or reading input values.
-- Prefer `@observable someValue!: T;` when a value is expected to be seeded externally after construction.
+- Omit `@observable` for values that are only read by the template and seeded
+  externally after construction.
+- Omit the TypeScript class when compiled template behavior is sufficient,
+  including browser-applied state, route updates, and client-created instances.
+  Add a same-named module only for authored events, lifecycle, decorators, or
+  imperative APIs.
 
 Avoid imperative DOM mutation for application state that can be represented by reactive properties.
 
@@ -360,7 +459,7 @@ flowchart LR
 graph TD
     EL["element.ts (~850 lines)<br/><i>Orchestrator</i><br/>$mount, $wire, $hydrate,<br/>$resolveSSR, $applySSRState,<br/>$update, events, cleanup"]
 
-    DIFF["element/diff.ts (~130 lines)<br/><i>List Reconciliation</i><br/>keyed/sequential diffing<br/>for @for repeat blocks"]
+    DIFF["element/diff.ts<br/><i>List Reconciliation</i><br/>positional + explicit-key diffing<br/>for &lt;for&gt; repeat blocks"]
 
     COND["element/conditions.ts<br/><i>Condition Evaluation</i><br/>evaluateCondition (iterative),<br/>conditionUsesPath"]
 
@@ -407,7 +506,7 @@ sequenceDiagram
     CE->>CE: attributeChangedCallback (pre-existing attrs)
     CE->>FW: connectedCallback() → $mount()
     FW->>FW: SSR DOM detected (shadow root or children exist)
-    FW->>FW: $applySSRState() — seed observables from __webui.state
+    FW->>FW: $applySSRState() — seed decorated state
     FW->>FW: $hydrate() — template-parallel path resolution
     FW->>FW: $resolveSSR() — match SSR nodes via ordinal traversal
     FW->>FW: $wireEvents() + $wireRefs()
@@ -454,15 +553,15 @@ interface TemplateMeta {
   tx?: [slot, parts][];                // Text run locators
   a?: CompiledAttrMeta[];              // Attribute bindings
   ag?: [path, start, count][];         // Attribute target groups
-  c?: [conditionAST, blockIndex][];    // Conditional blocks
-  cl?: SlotPath[];                     // Conditional anchor slots
-  r?: [collection, itemVar, blockIdx][];// Repeat blocks
-  rl?: SlotPath[];                     // Repeat anchor slots
-  e?: [event, handler, argSpecs, targetPath][]; // Events
+  c?: [conditionAST, blockIndex, slot][]; // Conditional blocks
+  r?: [collection, itemVar, blockIdx, slot][]; // Repeat blocks
+  eg?: [event, [[handler, argSpecs, targetPath, usesEvent?]]][]; // Events
   b?: TemplateBlockMeta[];             // Nested block metadata
   sa?: string;                         // Adopted stylesheet specifier
   sd?: boolean;                        // Shadow DOM flag for client-created
   re?: [event, handler, argSpecs][];    // Root-level events
+  tr?: string[];                       // Template state roots
+  ta?: string[];                       // Host attributes aligned with tr
 }
 ```
 
@@ -482,7 +581,7 @@ Compiled metadata:
     [[[0], 0], [["title"]]],           // slot in <h1>, dynamic "title"
     [[[1], 1], ["Count: ", ["count"]]]  // slot in <button>, static + dynamic
   ],
-  e: [["click", "increment", [], [1]]] // click -> increment, no event args
+  eg: [["click", [["increment", [], [1]]]]] // click -> increment, no event args
 }
 ```
 
@@ -523,15 +622,16 @@ sequenceDiagram
 ### Why Updates Are O(affected)
 
 After hydration, every dynamic value in the template is connected to a direct
-DOM node reference stored in a binding array.  A per-path index maps each
-`@observable` property name to the subset of bindings that reference it.
+DOM node reference stored in a binding array. A per-path index maps each
+decorated property or compiled template root to the subset of bindings that
+reference it.
 
 When `this.count = 5` fires, the `@observable` setter calls `$update('count')`,
 which looks up `'count'` in the index and only patches the bindings that
 actually depend on `count` — not every binding in the component.
 
-Computed/volatile getters (paths not in the `@observable` set) are stored
-under a wildcard key and always included in targeted updates.
+Computed/volatile getters and other paths that are not known state roots are
+stored under a wildcard key and always included in targeted updates.
 
 ```typescript
 // Targeted update (simplified):
@@ -553,64 +653,58 @@ path index ensures only affected pointers are visited.
 
 ## SSR State Seeding
 
-When the server renders `<span>42</span>` for `@observable count = 0`, the
-browser sees `42` in the DOM but the JavaScript property `this.count` is still
-`0` (the class default).  Without seeding, the first `$update()` would
-overwrite the SSR content with the wrong value.
+When the server renders `<span>42</span>` for a template binding, the browser
+sees `42` in the DOM before the component's JavaScript state exists. Without
+seeding, the first `$update()` would overwrite the SSR content with the wrong
+value.
 
-State seeding uses `window.__webui.state` — a JSON object loaded from the
-server-emitted `#webui-data` block.  Like Preact's props, this delivers the
-same data used for SSR rendering to the client.  During `$mount()`,
-`$applySSRState()` writes matching keys directly to observable backing fields
-before any bindings are wired:
+State seeding uses `window.__webui.state` loaded from the server-emitted
+`#webui-data` block. When the protocol contains projection metadata, only
+`@observable` and `@attr` keys from reachable authored components select
+initial state; HTML-only dormant components and authored template-only roots
+contribute no startup keys. Without projection metadata, the server preserves
+full state. During `$mount()`, `$applySSRState()` writes matching decorated keys
+directly to observable backing fields before any bindings are wired:
 
 ```mermaid
 flowchart LR
-    SCRIPT["&lt;script type='application/json' id='webui-data'&gt;<br/>{ state: { count: 42, title: 'Hello' } }"] --> APPLY["$applySSRState()"]
-    APPLY --> SEED["Write to backing fields:<br/>this._count = 42<br/>this._title = 'Hello'"]
+    SCRIPT["&lt;script type='application/json' id='webui-data'&gt;<br/>{ state: { count: 42 } }"] --> APPLY["$applySSRState()"]
+    APPLY --> SEED["Write decorated backing fields"]
     SEED --> HYDRATE["$hydrate() — bindings match<br/>server-rendered DOM"]
 ```
 
-`$applySSRState()` only sets properties that exist in the component's
-`@observable` set — unknown keys are ignored.  Writes go to the backing
-field (`_prop`) directly, avoiding reactive updates before bindings are wired.
+Decorated writes go to the backing field (`_prop`) directly, avoiding reactive
+updates before bindings are wired. For `@attr`, an existing SSR host attribute
+takes precedence and the projected value is skipped. Template-only values
+remain represented by the SSR DOM until browser state explicitly changes them.
+Later `setState()` calls, including router partials, accept both decorated
+properties and compiled template roots; undecorated roots are stored in hidden
+framework state. The first write to a dormant HTML-only host replays only the
+roots present in that write, preserving omitted SSR text, attributes,
+conditions, and repeats.
 
 ---
 
 ## Repeat Reconciliation
 
-`@for(item of items)` blocks support two reconciliation strategies,
-implemented in `element/diff.ts` (~130 lines):
-
-### Keyed Reconciliation
-
-When the repeat block's root element has attribute bindings (e.g.
-`<todo-item id="{{item.id}}">`), the framework uses the first attribute as a
-key.  This preserves DOM nodes across reorders:
-
-```mermaid
-flowchart TD
-    subgraph Before ["Before: items = [A, B, C]"]
-        A1["&lt;todo-item&gt; key=A"]
-        B1["&lt;todo-item&gt; key=B"]
-        C1["&lt;todo-item&gt; key=C"]
-    end
-
-    subgraph After ["After: items = [C, A]"]
-        C2["&lt;todo-item&gt; key=C ← reused"]
-        A2["&lt;todo-item&gt; key=A ← reused"]
-        B2["key=B ← removed"]
-    end
-
-    A1 -.->|"moved"| A2
-    C1 -.->|"moved"| C2
-    B1 -.->|"destroyed"| B2
-```
-
-### Sequential Reconciliation
-
-When no keying attributes exist, items are matched by position.  Excess items
-are removed; new items are appended.
+`<for>` blocks reconcile by array position by default. The existing block at
+index `i` receives the current item at index `i`; only a new or removed tail
+creates or removes blocks.
+
+Duplicate values and attributes are safe because dynamic attributes never act
+as hidden keys. Reordering rebinds existing blocks in place, so local
+browser-owned or component state remains associated with positions rather than
+logical items.
+
+For reorderable or stateful lists, author `key="{{item.id}}"` on the first
+child inside `<for>` to move existing blocks with their logical items.
+`key="{{item}}"` supports arrays of unique string or finite-number primitives.
+`key` is compiler-only metadata and is removed from SSR and client HTML;
+`data-key` remains an ordinary attribute with no identity semantics. Key paths
+are compiler-validated and stored only for explicitly keyed repeats, so
+unkeyed bindings carry no key state or map allocation. Duplicate or invalid
+runtime keys warn once, clear identity, and use positional reconciliation until
+valid identity is re-established.
 
 ### SSR State Reading
 
@@ -684,7 +778,7 @@ This template-parallel traversal eliminates the need for any marker comments,
 | Initial hydration | O(bindings) | Single pass over compiled path mappings |
 | Reactive update | O(affected) | Per-path index skips unrelated bindings |
 | Conditional toggle | O(block size) | Create/destroy a block instance |
-| Repeat reconciliation | O(items) | Keyed map lookup or sequential scan |
+| Repeat reconciliation | O(items) | Positional scan; explicit keys use a reusable map only when order changes |
 | Event wiring | O(events) | One-time during hydration |
 
 ### What the framework does NOT do

package/dist/component-asset.d.ts

@@ -0,0 +1,30 @@
+import { type CompiledConditionFn, type TemplateMeta } from './template.js';
+export interface ComponentAsset {
+    type?: 'webui-component-asset';
+    version?: number;
+    components?: string[];
+    templateStyles?: string[];
+    templates?: Record<string, TemplateMeta>;
+    templateFunctions?: Record<string, CompiledConditionFn[]>;
+}
+export type ComponentAssetState = Record<string, unknown>;
+export interface ComponentAssetManifestEntry<Data extends ComponentAssetState = ComponentAssetState> {
+    asset: string | URL;
+    module?: () => Promise<unknown>;
+    data?: () => Promise<Data>;
+}
+export type ComponentAssetManifest = Record<string, ComponentAssetManifestEntry>;
+export interface ComponentAssetPreload<Data extends ComponentAssetState = ComponentAssetState> {
+    asset: Promise<void>;
+    module?: Promise<unknown>;
+    data?: Promise<Data>;
+}
+export interface ComponentAssetCreateOptions {
+    awaitData?: boolean;
+    dataTimeoutMs?: number;
+}
+export interface ComponentAssetRegistry {
+    preload<Data extends ComponentAssetState = ComponentAssetState>(tag: string): ComponentAssetPreload<Data>;
+    create(tag: string, options?: ComponentAssetCreateOptions): Promise<HTMLElement>;
+}
+export declare function defineComponentAssets(manifest: ComponentAssetManifest): ComponentAssetRegistry;

package/dist/component-asset.js

@@ -0,0 +1,213 @@
+import { getTemplate, registerTemplateData, } from './template.js';
+const ASSET_TYPE = 'webui-component-asset';
+const ASSET_VERSION = 1;
+const injectedAssetStyles = new Set();
+const assetLoadPromises = new Map();
+let assetStylesSeeded = false;
+function assetGlobal() {
+    return window.__webui;
+}
+export function defineComponentAssets(manifest) {
+    const preloads = new Map();
+    function preload(tag) {
+        const existing = preloads.get(tag);
+        if (existing)
+            return existing;
+        const entry = manifest[tag];
+        if (!entry) {
+            throw new Error(`[WebUI] No component asset manifest entry for <${tag}>.`);
+        }
+        const next = {
+            asset: loadComponentAsset(tag, entry.asset),
+        };
+        if (entry.module) {
+            next.module = entry.module();
+        }
+        if (entry.data) {
+            next.data = entry.data();
+        }
+        next.asset.catch(() => { });
+        next.module?.catch(() => { });
+        next.data?.catch(() => { });
+        preloads.set(tag, next);
+        return next;
+    }
+    async function create(tag, options = {}) {
+        const pending = preload(tag);
+        await waitForElementResources(pending);
+        const element = document.createElement(tag);
+        if (pending.data) {
+            if (options.awaitData) {
+                const state = options.dataTimeoutMs === undefined
+                    ? await pending.data
+                    : await dataWithTimeout(pending.data, options.dataTimeoutMs);
+                if (state) {
+                    applyState(element, state);
+                }
+                else {
+                    applyDataWhenReady(element, pending.data);
+                }
+            }
+            else {
+                applyDataWhenReady(element, pending.data);
+            }
+        }
+        return element;
+    }
+    return { preload, create };
+}
+async function waitForElementResources(pending) {
+    await pending.asset;
+    if (pending.module)
+        await pending.module;
+}
+function applyState(element, state) {
+    const setState = element.setState;
+    if (typeof setState === 'function') {
+        setState.call(element, state);
+    }
+}
+function applyDataWhenReady(element, data) {
+    const elementRef = new WeakRef(element);
+    void data.then(state => {
+        const liveElement = elementRef.deref();
+        if (liveElement)
+            applyState(liveElement, state);
+    }).catch(() => { });
+}
+function dataWithTimeout(data, timeoutMs) {
+    if (timeoutMs < 0)
+        return data;
+    return Promise.race([
+        data,
+        new Promise(resolve => {
+            setTimeout(() => resolve(undefined), timeoutMs);
+        }),
+    ]);
+}
+function loadComponentAsset(tag, url) {
+    if (getTemplate(tag))
+        return Promise.resolve();
+    const assetUrl = new URL(url, document.baseURI);
+    const href = assetUrl.href;
+    let promise = assetLoadPromises.get(href);
+    if (promise)
+        return promise;
+    promise = importAndRegisterComponentAsset(assetUrl)
+        .finally(() => {
+        assetLoadPromises.delete(href);
+    });
+    assetLoadPromises.set(href, promise);
+    return promise;
+}
+function registerComponentAsset(asset) {
+    validateAsset(asset);
+    if (asset.templates && templatesAlreadyRegistered(asset.templates))
+        return;
+    registerAssetStyles(asset.templateStyles, readNonce());
+    if (asset.templates) {
+        registerTemplateData(asset.templates, asset.templateFunctions);
+    }
+}
+async function importAndRegisterComponentAsset(assetUrl) {
+    const imported = await import(assetUrl.href);
+    registerComponentAsset(readComponentAssetModule(imported));
+}
+function readComponentAssetModule(module) {
+    if (!isObject(module) || !isObject(module.default)) {
+        throw new Error('[WebUI] Component asset module must default-export an asset object.');
+    }
+    return module.default;
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null;
+}
+function validateAsset(asset) {
+    if (asset.type !== ASSET_TYPE) {
+        throw new Error(`[WebUI] Invalid component asset type: ${String(asset.type)}`);
+    }
+    if (asset.version !== ASSET_VERSION) {
+        throw new Error(`[WebUI] Unsupported component asset version: ${String(asset.version)}`);
+    }
+}
+function templatesAlreadyRegistered(templates) {
+    const tags = Object.keys(templates);
+    if (tags.length === 0)
+        return false;
+    for (let i = 0; i < tags.length; i++) {
+        if (!getTemplate(tags[i]))
+            return false;
+    }
+    return true;
+}
+function readNonce() {
+    const nonce = assetGlobal()?.nonce;
+    if (nonce)
+        return nonce;
+    const meta = document.querySelector('meta[name="webui-nonce"]');
+    return meta?.content ?? '';
+}
+function seedAssetStyleSet() {
+    if (assetStylesSeeded)
+        return;
+    assetStylesSeeded = true;
+    const styles = assetGlobal()?.styles;
+    if (!styles)
+        return;
+    for (let i = 0; i < styles.length; i++) {
+        injectedAssetStyles.add(styles[i]);
+    }
+}
+function registerAssetStyles(templateStyles, nonce) {
+    if (!templateStyles || templateStyles.length === 0)
+        return;
+    seedAssetStyleSet();
+    for (let i = 0; i < templateStyles.length; i++) {
+        const imports = parseImportMap(templateStyles[i]);
+        const nextImports = {};
+        let hasNewImport = false;
+        const specifiers = Object.keys(imports);
+        for (let j = 0; j < specifiers.length; j++) {
+            const specifier = specifiers[j];
+            if (injectedAssetStyles.has(specifier))
+                continue;
+            injectedAssetStyles.add(specifier);
+            nextImports[specifier] = imports[specifier];
+            hasNewImport = true;
+        }
+        if (!hasNewImport)
+            continue;
+        const script = document.createElement('script');
+        script.type = 'importmap';
+        if (nonce)
+            script.nonce = nonce;
+        script.textContent = JSON.stringify({ imports: nextImports });
+        document.head.appendChild(script);
+    }
+}
+function parseImportMap(scriptMarkup) {
+    const trimmed = scriptMarkup.trim();
+    if (!trimmed.startsWith('<script')) {
+        throw new Error('[WebUI] Component asset templateStyles entry must be a <script type="importmap"> tag.');
+    }
+    const openTagEnd = trimmed.indexOf('>');
+    const closeTagStart = trimmed.lastIndexOf('</script>');
+    if (openTagEnd < 0 || closeTagStart <= openTagEnd) {
+        throw new Error('[WebUI] Component asset importmap tag is malformed.');
+    }
+    const parsed = JSON.parse(trimmed.substring(openTagEnd + 1, closeTagStart));
+    if (!parsed.imports || typeof parsed.imports !== 'object') {
+        throw new Error('[WebUI] Component asset importmap is missing an imports object.');
+    }
+    const imports = {};
+    const specifiers = Object.keys(parsed.imports);
+    for (let i = 0; i < specifiers.length; i++) {
+        const specifier = specifiers[i];
+        const uri = parsed.imports[specifier];
+        if (typeof uri !== 'string' || !uri.startsWith('data:text/css,')) {
+            throw new Error(`[WebUI] Component asset importmap entry "${specifier}" must be a data:text/css URI.`);
+        }
+        imports[specifier] = uri;
+    }
+    return imports;
+}