@microsoft/webui-framework 0.0.14 → 0.0.16

package/README.md

@@ -32,7 +32,7 @@ Outside the workspace:
 pnpm add @microsoft/webui-framework
 ```
 
-TypeScript must use legacy decorators:
+TypeScript must enable decorator emit:
 
 ```json
 {
@@ -93,7 +93,17 @@ Build with `--dom=shadow` (default) to wrap in a declarative shadow root, or `--
 cargo run -p microsoft-webui-cli -- build ./src --out ./dist --plugin=webui
 ```
 
-The compiler/plugin generates the template metadata consumed by the runtime. In normal app code, you should not need to hand-author `window.__webui.templates`.
+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`.
+
+### Property binding lifecycle
+
+Property bindings use the `:` prefix to pass values directly to child DOM properties:
+
+```html
+<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.
 
 ### DOM strategy (`--dom`)
 
@@ -183,7 +193,7 @@ The WebUI plugin compiles these template features into runtime metadata:
 
 - text bindings: `{{title}}`
 - attribute bindings: `href="{{item.href}}"`
-- event handlers: `@click="{onClick()}"`
+- event handlers: `@click="{onClick()}"`, `@click="{onSelect(item.id, e)}"`
 - refs: `w-ref="addInput"`
 - conditionals: `<if condition="...">`
 - repeats: `<for each="item in items">`
@@ -244,10 +254,10 @@ resource-constrained devices.
    and cached as a `DocumentFragment`.  Every subsequent instance uses
    `cloneNode(true)` — DOM cloning is significantly faster than HTML parsing.
 
-4. **Delegate events, don't multiply listeners.**
-   Event bindings use delegation: one listener per event type on the
-   component root, with handler names resolved from compiled paths.  200
-   items × 5 events = 1 delegated listener, not 1000 closures.
+4. **Resolve event targets once.**
+   Event bindings store their target path in compiled metadata.  Hydration
+   resolves each target once, installs the listener directly, and captures the
+   active repeat scope so handler arguments like `item.id` are read at dispatch.
 
 5. **Single-pass hydration via path mapping.**
    SSR DOM is matched to compiled template bindings through
@@ -285,7 +295,8 @@ When contributing to the runtime, avoid these patterns:
   pre-resolved at hydration time via compiled path mapping.
 - **Don't use recursion in hot paths.** Condition evaluation and DOM walks
   use iterative stacks.
-- **Don't create closures per binding.** Use delegation or shared handlers.
+- **Don't allocate on the update path for events.** Event listeners are created
+  once during hydration and should not trigger extra DOM lookup work later.
 - **Don't re-parse template HTML.** Always clone from the cached fragment.
 
 ---
@@ -300,7 +311,7 @@ When contributing to the runtime, avoid these patterns:
 │                      │     │   (Rust/Go/C#/…)      │      │                      │
 │  HTML template       │     │                       │      │  SSR HTML (light or  │
 │  + expressions       │────▶│  TemplateMeta (JSON)  │────▶│  shadow DOM) +       │
-│  + @if / @for        │     │  + state data         │      │  __webui.state JSON  │
+│  + @if / @for        │     │  + state data         │      │  webui-data JSON     │
 │                      │     │                       │      │                      │
 │  Outputs:            │     │  Renders:             │      │  Hydrates:           │
 │  • TemplateMeta      │     │  • Full HTML page     │      │  • Path-based DOM    │
@@ -329,7 +340,7 @@ flowchart LR
     subgraph Serve ["Server (Any Language)"]
         M --> R[Route Handler]
         S[State Data] --> R
-        R --> HTML["Full SSR HTML<br/>(shadow or light DOM)<br/>+ TemplateMeta &lt;script&gt;<br/>+ __webui.state &lt;script&gt;"]
+        R --> HTML["Full SSR HTML<br/>(shadow or light DOM)<br/>+ inert #webui-data"]
     end
 
     subgraph Browser ["Browser"]
@@ -355,7 +366,7 @@ graph TD
 
     TYPES["element/types.ts<br/><i>Shared Types</i><br/>TemplateInstance, TextBinding,<br/>AttrBinding, CondBinding,<br/>RepeatBinding, ScopeFrame,<br/>RepeatHost"]
 
-    TMPL["template.ts<br/><i>Metadata Types + Registry</i><br/>TemplateMeta, getTemplate"]
+    TMPL["template.ts<br/><i>Metadata Types + Registry</i><br/>TemplateMeta, getTemplate,<br/>registerTemplateData"]
 
     DEC["decorators.ts<br/><i>Reactive Properties</i><br/>@observable, @attr, @volatile"]
 
@@ -377,7 +388,7 @@ graph TD
 ### SSR Hydration Path
 
 When the server renders a component, it emits HTML content (as a declarative
-shadow root or as light DOM children) along with a `window.__webui.state`
+shadow root or as light DOM children) along with an inert `#webui-data`
 JSON payload.  The browser parses this DOM before any JavaScript runs.
 When the component's JS loads and `connectedCallback` fires, the framework
 uses compiled template paths to resolve SSR DOM nodes without any marker
@@ -390,7 +401,7 @@ sequenceDiagram
     participant CE as Custom Element
     participant FW as Framework
 
-    Server->>Browser: HTML (shadow or light DOM)<br/>+ __webui.state JSON
+    Server->>Browser: HTML (shadow or light DOM)<br/>+ inert #webui-data JSON
     Browser->>Browser: Parse HTML → DOM exists
     Browser->>CE: Custom element upgrade
     CE->>CE: attributeChangedCallback (pre-existing attrs)
@@ -447,12 +458,11 @@ interface TemplateMeta {
   cl?: SlotPath[];                     // Conditional anchor slots
   r?: [collection, itemVar, blockIdx][];// Repeat blocks
   rl?: SlotPath[];                     // Repeat anchor slots
-  e?: [event, handler, needsEvent][];  // Events
-  el?: NodePath[];                     // Event target paths
+  e?: [event, handler, argSpecs, targetPath][]; // Events
   b?: TemplateBlockMeta[];             // Nested block metadata
   sa?: string;                         // Adopted stylesheet specifier
   sd?: boolean;                        // Shadow DOM flag for client-created
-  re?: [event, handler, needsEvent][];  // Root-level events
+  re?: [event, handler, argSpecs][];    // Root-level events
 }
 ```
 
@@ -461,7 +471,7 @@ interface TemplateMeta {
 Template:
 ```html
 <h1>{{title}}</h1>
-<button @click="increment">Count: {{count}}</button>
+<button @click="{increment()}">Count: {{count}}</button>
 ```
 
 Compiled metadata:
@@ -472,24 +482,20 @@ Compiled metadata:
     [[[0], 0], [["title"]]],           // slot in <h1>, dynamic "title"
     [[[1], 1], ["Count: ", ["count"]]]  // slot in <button>, static + dynamic
   ],
-  e: [["click", "increment", 0]],      // click → increment, no event arg
-  el: [[1]]                            // event target is child[1] (button)
+  e: [["click", "increment", [], [1]]] // click -> increment, no event args
 }
 ```
 
-### Condition AST
-
-Conditions are emitted as compact tuples:
+### Condition references
 
-| Tuple | Meaning | Example |
-|-------|---------|---------|
-| `[0, path]` | Identifier (truthy check) | `@if(visible)` |
-| `[1, left, op, right]` | Comparison predicate | `@if(count > 0)` |
-| `[2, inner]` | Logical NOT | `@if(!visible)` |
-| `[3, left, op, right]` | Compound AND/OR | `@if(a && b)` |
+Conditions are emitted as `[functionIndex, paths]` references. The index points
+to a component-local closure in `window.__webui.templateFns[tagName]`, while
+`paths` lets the runtime build targeted reactive indexes without parsing
+function source.
 
-The runtime evaluates these iteratively (stack-based, no recursion) to avoid
-call-stack depth in hot update paths.
+The runtime normalizes each condition reference into `[fn, paths]` once before
+hydration or client-created wiring, so hot update paths call the closure
+directly.
 
 ---
 
@@ -552,15 +558,15 @@ 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.
 
-State seeding uses `window.__webui.state` — a JSON object emitted by the
-server handler as a `<script>` tag.  Like Preact's props, this delivers the
+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:
 
 ```mermaid
 flowchart LR
-    SCRIPT["&lt;script&gt;<br/>window.__webui.state = {<br/>  count: 42,<br/>  title: 'Hello'<br/>}"] --> APPLY["$applySSRState()"]
+    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'"]
     SEED --> HYDRATE["$hydrate() — bindings match<br/>server-rendered DOM"]
 ```
@@ -624,7 +630,7 @@ The framework supports three CSS delivery strategies:
 |----------|-------------|
 | **Link** | `<link>` tag baked into `meta.h` — loaded by the browser naturally |
 | **Inline** | `<style>` tag baked into `meta.h` — no external request |
-| **Module** | `<style type="module" specifier="tag-name">` in the HTML payload, parsed into a `CSSStyleSheet` and applied via `adoptedStyleSheets` for shadow DOM isolation |
+| **Module** | `<script type="importmap">{"imports":{"tag-name":"data:text/css,..."}}</script>` in the HTML payload registers the CSS as a module under `tag-name`. The framework imports it via `import(tag, { with: { type: 'css' } })` and applies the resulting `CSSStyleSheet` via `adoptedStyleSheets` for shadow DOM isolation |
 
 CSS module stylesheets are cached so each component instance adopts the same
 parsed sheet without re-parsing CSS.  The `meta.sa` field specifies the

package/dist/decorators.js

@@ -3,8 +3,8 @@
 /**
  * Reactive decorators for WebUIElement properties.
  *
- * Uses legacy/experimental TypeScript decorators (`experimentalDecorators: true`)
- * for compatibility with the FAST ecosystem conventions.
+ * Uses TypeScript's `experimentalDecorators` emit, matching the FAST ecosystem
+ * conventions.
  */
 // ---------------------------------------------------------------------------
 // Internal helpers

package/dist/element/diff.js

@@ -101,12 +101,11 @@ export function syncRepeat(host, rep) {
             host.$removeInstance(oldInstances[i].instance);
         }
         rep.instances = next;
-        // Reorder + update
         let cursor = rep.start;
         for (let i = 0; i < next.length; i += 1) {
             cursor = host.$insertInstanceAfter(cursor, container, next[i].instance);
         }
-        for (let i = 0; i < next.length; i += 1) {
+        for (let i = 0; i < reuseCount; i += 1) {
             host.$updateInstance(next[i].instance);
         }
         return;
@@ -148,13 +147,16 @@ export function syncRepeat(host, rep) {
     }
     rep.instances = next;
     // ── Reorder DOM (forward pass) ──────────────────────────────────
-    // Walk forward, skip nodes already in position.
+    // Newly-created instances were patched while detached. Reused instances
+    // update after moving so nested structural nodes stay with the item.
     let cursor = rep.start;
     for (let i = 0; i < next.length; i += 1) {
         cursor = host.$insertInstanceAfter(cursor, container, next[i].instance);
     }
-    // ── Update bindings ─────────────────────────────────────────────
-    for (let i = 0; i < next.length; i += 1) {
-        host.$updateInstance(next[i].instance);
+    for (let i = 0; i < oldInstances.length; i += 1) {
+        const entry = oldInstances[i];
+        const k = entry.key;
+        if (k != null && !oldByKey.has(k))
+            host.$updateInstance(entry.instance);
     }
 }

package/dist/element/styles.js

@@ -10,17 +10,17 @@
  *
  * - **Style**: Inline `<style>` tags inside each shadow template.
  *
- * - **Module**: Uses the Declarative CSS Module Scripts proposal. During SSR,
- *   `<style type="module" specifier="...">` definitions are emitted inline in
- *   each rendered component's light DOM. The browser registers these globally
- *   and automatically adopts them via `shadowrootadoptedstylesheets` on
- *   declarative shadow roots.
+ * - **Module**: Uses CSS Modules registered via Import Maps. During SSR, the
+ *   handler emits a `<script type="importmap">{"imports":{"<tag>":"data:text/css,..."}}</script>`
+ *   in each rendered component's light DOM. The browser registers the
+ *   stylesheet globally under `<tag>` and automatically adopts it via
+ *   `shadowrootadoptedstylesheets` on declarative shadow roots.
  *
- *   During SPA navigation, the router appends new `<style type="module">`
- *   definitions to `<head>` via `templateStyles[]`. The framework uses
+ *   During SPA navigation, the router appends new importmap script tags to
+ *   `<head>` via `templateStyles[]`. The framework uses
  *   `import(specifier, { with: { type: "css" } })` to retrieve the browser's
  *   registered CSSStyleSheet and adopts it onto the shadow root. This is a
- *   direct hash-map lookup in the browser's module registry — no DOM queries,
+ *   direct hash-map lookup in the browser's module registry - no DOM queries,
  *   no manual CSSStyleSheet construction.
  *
  * For light DOM components (no shadow root), Module mode injects a `<style>`
@@ -48,9 +48,10 @@ export function injectModuleStyle(specifier, shadowRoot) {
         if (shadowRoot.adoptedStyleSheets.length > 0)
             return;
         // SPA path: import the CSS module from the browser's registry.
-        // The <style type="module" specifier="X"> definition was either
-        // emitted inline during SSR or appended to <head> by the router.
-        // The import resolves to the same CSSStyleSheet the browser registered.
+        // The specifier was registered via a `<script type="importmap">` tag
+        // (either inlined at SSR time or appended to <head> by the router during
+        // partial navigation). The import resolves to the same CSSStyleSheet the
+        // browser registered.
         import(specifier, { with: { type: 'css' } }).then((mod) => {
             shadowRoot.adoptedStyleSheets = [
                 ...shadowRoot.adoptedStyleSheets,

package/dist/element/types.d.ts

@@ -98,6 +98,7 @@ export interface RepeatItemInstance {
  */
 export interface RepeatHost {
     $resolveValue(path: string, scope?: ScopeFrame): unknown;
+    /** Create, wire, and perform the first binding pass while detached. */
     $createBlockInstance(blockIndex: number, scope?: ScopeFrame): TemplateInstance | null;
     $updateInstance(instance: TemplateInstance): void;
     $removeInstance(instance: TemplateInstance): void;

package/dist/element.d.ts

@@ -57,6 +57,9 @@ export declare class WebUIElement extends HTMLElement {
     private $resolve;
     private $resolveSSR;
     private $parseTemplate;
+    private $createStagingRoot;
+    private $appendStagedChildren;
+    private $releaseStagingRepeatContainers;
     private $wire;
     /**
      * Hydrate SSR-rendered DOM against compiled template metadata.
@@ -98,6 +101,8 @@ export declare class WebUIElement extends HTMLElement {
      * `<!--wr-->...<!--/wr-->` ranges to keep text ordinals aligned.
      */
     private $findSSRText;
+    /** Find the SSR insertion reference for an empty text slot. */
+    private $findSSRSlotRef;
     /** Extract root tag name from block metadata. */
     private $rootTag;
     /** Wire attribute bindings using a resolver (shared by $wire and $hydrate). */
@@ -110,6 +115,8 @@ export declare class WebUIElement extends HTMLElement {
     private $wireRoot;
     /** Attach a single event listener. */
     private $addEvent;
+    private $resolveEventArgs;
+    private $resolveEventArg;
     /** Find w-ref attributes and assign to component properties. */
     private $wireRefs;
     /** Create an AttrBinding from compiled metadata. */

package/dist/element.js

@@ -157,6 +157,7 @@ export class WebUIElement extends HTMLElement {
         const wantShadow = hasShadow || !!meta.sd;
         let root;
         let isSSR;
+        let clientRoot = null;
         if (hasShadow) {
             // Shadow DOM SSR — declarative shadow root already has content
             root = this.shadowRoot;
@@ -175,14 +176,10 @@ export class WebUIElement extends HTMLElement {
             // Existing children are slot content — they stay in light DOM
             // and project through the template's <slot>.
             root = this.attachShadow({ mode: 'open' });
-            const fragment = this.$parseTemplate(meta);
-            root.appendChild(fragment);
             isSSR = false;
         }
         else {
             // Light DOM client-created — populate from template (no shadow = no link issue)
-            const fragment = this.$parseTemplate(meta);
-            this.appendChild(fragment);
             root = this;
             isSSR = false;
         }
@@ -196,7 +193,8 @@ export class WebUIElement extends HTMLElement {
             this.$root = this.$hydrate(root, meta, getTemplateDom(meta));
         }
         else {
-            this.$root = this.$wire(root, meta);
+            clientRoot = this.$createStagingRoot(meta);
+            this.$root = this.$wire(clientRoot, meta);
         }
         this.$meta = meta;
         this.$hydrated = true;
@@ -206,8 +204,13 @@ export class WebUIElement extends HTMLElement {
         // into the freshly-wired template DOM. Call $updateInstance directly
         // to avoid the $update() path-index build — it will be lazy-built
         // on the first reactive change instead.
-        if (!isSSR) {
+        if (!isSSR && clientRoot) {
             this.$updateInstance(this.$root);
+            if (this.$root.repeats.length !== 0 || this.$root.conds.length !== 0) {
+                this.$root.nodes = childNodesArray(clientRoot);
+                this.$releaseStagingRepeatContainers(this.$root, clientRoot);
+            }
+            this.$appendStagedChildren(root, clientRoot);
         }
         hydrationEnd();
     }
@@ -458,6 +461,52 @@ export class WebUIElement extends HTMLElement {
         templateCache.set(meta, tpl.content);
         return tpl.content.cloneNode(true);
     }
+    $createStagingRoot(meta) {
+        const wrapper = document.createElement('div');
+        const fragment = this.$parseTemplate(meta);
+        wrapper.appendChild(fragment);
+        customElements.upgrade(wrapper);
+        return wrapper;
+    }
+    $appendStagedChildren(root, stagingRoot) {
+        const first = stagingRoot.firstChild;
+        if (!first)
+            return;
+        if (!first.nextSibling) {
+            root.appendChild(first);
+            return;
+        }
+        const fragment = document.createDocumentFragment();
+        while (stagingRoot.firstChild) {
+            fragment.appendChild(stagingRoot.firstChild);
+        }
+        root.appendChild(fragment);
+    }
+    $releaseStagingRepeatContainers(instance, stagingRoot) {
+        if (!instance || !stagingRoot)
+            return;
+        if (instance.repeats.length === 0 && instance.conds.length === 0)
+            return;
+        const stack = [instance];
+        while (stack.length > 0) {
+            const current = stack.pop();
+            if (!current)
+                continue;
+            for (let i = 0; i < current.repeats.length; i++) {
+                const repeat = current.repeats[i];
+                if (repeat.container === stagingRoot)
+                    repeat.container = null;
+                for (let j = 0; j < repeat.instances.length; j++) {
+                    stack.push(repeat.instances[j].instance);
+                }
+            }
+            for (let i = 0; i < current.conds.length; i++) {
+                const child = current.conds[i].instance;
+                if (child)
+                    stack.push(child);
+            }
+        }
+    }
     // ═══════════════════════════════════════════════════════════════
     //  Client-created wiring — exact childNode index resolution
     // ═══════════════════════════════════════════════════════════════
@@ -491,7 +540,7 @@ export class WebUIElement extends HTMLElement {
                 const parent = parentPath.length > 0 ? this.$resolve(root, parentPath) : root;
                 if (!parent || (parent.nodeType !== 1 && parent.nodeType !== 11))
                     continue;
-                condRefs.push({ parent, ref: parent.childNodes[beforeIndex] || null, condition, blockIndex });
+                condRefs.push({ parent, ref: parent.childNodes[beforeIndex] || null, condition: condition, blockIndex });
             }
         }
         const repRefs = [];
@@ -510,7 +559,7 @@ export class WebUIElement extends HTMLElement {
         // Events + refs — resolve BEFORE anchors shift childNode indices.
         // Events target element nodes (not text/comment positions), but anchor
         // insertions still shift childNode indices for sibling elements.
-        this.$finalize(root, meta, (r, p) => this.$resolve(r, p));
+        this.$finalize(root, meta, (r, p) => this.$resolve(r, p), scope);
         // Now insert anchors using pre-resolved references
         // Text bindings
         for (const t of textRefs) {
@@ -602,7 +651,12 @@ export class WebUIElement extends HTMLElement {
                     instance.texts.push({ node: textNode, parts, scope, raw: true, rawParent });
                 }
                 else {
-                    const textNode = this.$findSSRText(ssrParent, tplParent, beforeIndex);
+                    let textNode = this.$findSSRText(ssrParent, tplParent, beforeIndex);
+                    if (!textNode) {
+                        textNode = document.createTextNode('');
+                        const insertRef = this.$findSSRSlotRef(ssrParent, tplParent, beforeIndex);
+                        ssrParent.insertBefore(textNode, insertRef);
+                    }
                     if (textNode)
                         instance.texts.push({ node: textNode, parts, scope });
                 }
@@ -665,7 +719,7 @@ export class WebUIElement extends HTMLElement {
                     }
                 }
                 instance.conds.push({
-                    condition, blockIndex,
+                    condition: condition, blockIndex,
                     anchor: condAnchor,
                     scope, instance: condInstance,
                 });
@@ -686,7 +740,11 @@ export class WebUIElement extends HTMLElement {
                 }
                 const blockMeta = this.$block(blockIndex);
                 const { attrMap, rootBindings } = this.$repeatMaps(blockIndex, itemVar);
-                const rootTag = blockMeta ? this.$rootTag(blockMeta) : null;
+                const blockTplDom = blockMeta ? getTemplateDom(blockMeta) : null;
+                const rootTag = blockMeta && blockTplDom?.childNodes.length === 1 && blockTplDom.children.length === 1
+                    ? this.$rootTag(blockMeta)
+                    : null;
+                const keyPath = Object.values(attrMap)[0];
                 // Find the next <!--wr--> marker in ssrParent (after any previously found one)
                 const marker = this.$findMarker(ssrParent, MARKER_REPEAT_START, lastRepMarker);
                 let anchor;
@@ -710,12 +768,11 @@ export class WebUIElement extends HTMLElement {
                 const { items: itemMarkers, end: endMarker } = marker
                     ? collectItemMarkers(anchor)
                     : { items: [], end: null };
-                if (blockMeta && items.length > 0 && anchor.parentNode && itemMarkers.length > 0) {
+                if (blockMeta && blockTplDom && items.length > 0 && anchor.parentNode && itemMarkers.length > 0) {
                     if (itemMarkers.length !== items.length) {
                         console.warn(`[webui] hydration: repeat marker count (${itemMarkers.length}) ≠ data length (${items.length}) for "${collection}"`);
                     }
                     const firstKey = Object.keys(attrMap)[0];
-                    const blockTplDom = getTemplateDom(blockMeta);
                     const limit = Math.min(itemMarkers.length, items.length);
                     for (let j = 0; j < limit; j++) {
                         const itemValue = items[j];
@@ -731,62 +788,25 @@ export class WebUIElement extends HTMLElement {
                             }
                         }
                         else {
-                            // Text-only repeat item — wire nested conditionals from markers
-                            const inst = {
-                                scope: itemScope, nodes: [],
-                                texts: EMPTY_ARR,
-                                attrs: EMPTY_ARR,
-                                conds: [],
-                                repeats: EMPTY_ARR,
-                            };
-                            if (blockMeta.c) {
-                                // Walk between this <!--wi--> and the next boundary to find <!--wc--> markers
-                                let cursor = itemMarkers[j].nextSibling;
-                                const nextBound = j + 1 < itemMarkers.length ? itemMarkers[j + 1] : endMarker;
-                                const itemParent = itemMarkers[j].parentNode;
-                                for (let ci = 0; ci < blockMeta.c.length; ci++) {
-                                    const [condCond, condBlockIndex] = blockMeta.c[ci];
-                                    // Find <!--wc--> within this item's range
-                                    let condAnchor = null;
-                                    while (cursor && cursor !== nextBound) {
-                                        if (cursor.nodeType === 8 && cursor.data === MARKER_COND_START) {
-                                            condAnchor = cursor;
-                                            cursor = cursor.nextSibling;
-                                            break;
-                                        }
-                                        cursor = cursor.nextSibling;
-                                    }
-                                    if (!condAnchor) {
-                                        condAnchor = document.createComment('');
-                                        if (itemParent)
-                                            itemParent.insertBefore(condAnchor, cursor ?? null);
-                                    }
-                                    const condMet = condCond[0](this.$resolver, itemScope);
-                                    let condInstance = null;
-                                    if (condMet) {
-                                        const condBlockMeta = this.$block(condBlockIndex);
-                                        if (condBlockMeta) {
-                                            condInstance = this.$hydrateCondContent(condAnchor, condBlockMeta, itemScope);
-                                        }
-                                    }
-                                    // Remove <!--/wc--> end marker and advance cursor past it
-                                    const lastNode = condInstance ? condInstance.nodes[condInstance.nodes.length - 1] : condAnchor;
-                                    const endM = lastNode?.nextSibling;
-                                    if (endM && endM.nodeType === 8 && endM.data === MARKER_COND_END) {
-                                        cursor = endM.nextSibling;
-                                        endM.parentNode?.removeChild(endM);
-                                    }
-                                    else {
-                                        cursor = lastNode?.nextSibling ?? null;
-                                    }
-                                    inst.conds.push({
-                                        condition: condCond, blockIndex: condBlockIndex,
-                                        anchor: condAnchor, scope: itemScope,
-                                        instance: condInstance,
-                                    });
-                                }
+                            const itemParent = itemMarkers[j].parentNode;
+                            const nextBound = j + 1 < itemMarkers.length ? itemMarkers[j + 1] : endMarker;
+                            const wrapper = document.createElement('div');
+                            let cursor = itemMarkers[j].nextSibling;
+                            while (cursor && cursor !== nextBound) {
+                                const next = cursor.nextSibling;
+                                wrapper.appendChild(cursor);
+                                cursor = next;
                             }
-                            repeatInsts.push({ key: String(j), value: itemValue, instance: inst });
+                            const inst = this.$hydrate(wrapper, blockMeta, blockTplDom, itemScope);
+                            inst.nodes = childNodesArray(wrapper);
+                            let afterNode = itemMarkers[j];
+                            for (let nodeIndex = 0; nodeIndex < inst.nodes.length; nodeIndex++) {
+                                const node = inst.nodes[nodeIndex];
+                                itemParent?.insertBefore(node, afterNode.nextSibling);
+                                afterNode = node;
+                            }
+                            const key = keyPath ? String(dotWalk(itemValue, keyPath, 0) ?? '') : null;
+                            repeatInsts.push({ key, value: itemValue, instance: inst });
                         }
                     }
                     // Defer <!--wi--> item marker removal (anchor <!--wr--> stays
@@ -808,7 +828,7 @@ export class WebUIElement extends HTMLElement {
             }
         }
         // Events + refs — this is the last phase that uses $resolveSSR.
-        this.$finalize(ssrRoot, meta, (r, p) => this.$resolveSSR(r, tplDom, p, pathStart));
+        this.$finalize(ssrRoot, meta, (r, p) => this.$resolveSSR(r, tplDom, p, pathStart), scope);
         // All path-based resolution is complete. Remove the SSR markers that
         // were kept alive for structural-block skipping.  Start markers
         // (<!--wc-->, <!--wr-->) are intentionally NOT collected — they
@@ -931,6 +951,18 @@ export class WebUIElement extends HTMLElement {
         }
         return null;
     }
+    /** Find the SSR insertion reference for an empty text slot. */
+    $findSSRSlotRef(ssrParent, tplParent, beforeIndex) {
+        const ordinals = getTplOrdinals(tplParent);
+        const children = tplParent.childNodes;
+        for (let i = beforeIndex; i < children.length; i++) {
+            const entry = ordinals.get(i);
+            if (!entry)
+                continue;
+            return findByOrdinal(ssrParent, entry[0], entry[1]);
+        }
+        return null;
+    }
     /** Extract root tag name from block metadata. */
     $rootTag(meta) {
         let cached = rootTagCache.get(meta);
@@ -972,37 +1004,68 @@ export class WebUIElement extends HTMLElement {
         }
     }
     /** Wire events + root events + refs (shared by $wire and $hydrate). */
-    $finalize(root, meta, resolver) {
-        this.$wireEvents(root, meta, resolver);
+    $finalize(root, meta, resolver, scope) {
+        this.$wireEvents(root, meta, resolver, scope);
         if (meta.re)
             this.$wireRoot(meta.re);
         this.$wireRefs(root);
     }
     /** Wire events using a resolver function (works for both client and SSR). */
-    $wireEvents(root, meta, resolver) {
+    $wireEvents(root, meta, resolver, scope) {
         if (!meta.e)
             return;
         for (let i = 0; i < meta.e.length; i++) {
-            const [eventName, handlerName, needsEvent, target] = meta.e[i];
+            const [eventName, handlerName, args, target] = meta.e[i];
             const el = resolver(root, target);
             if (!el || el.nodeType !== 1)
                 continue;
-            this.$addEvent(el, eventName, handlerName, needsEvent);
+            this.$addEvent(el, eventName, handlerName, args, scope);
         }
     }
     /** Wire root-level events on the host element (or shadow root when present). */
     $wireRoot(re) {
         const target = this.shadowRoot ?? this;
         for (let i = 0; i < re.length; i++) {
-            this.$addEvent(target, re[i][0], re[i][1], re[i][2]);
+            this.$addEvent(target, re[i][0], re[i][1], re[i][2], undefined);
         }
     }
     /** Attach a single event listener. */
-    $addEvent(target, eventName, handlerName, _needsEvent) {
+    $addEvent(target, eventName, handlerName, args, scope) {
         const method = this[handlerName];
         if (typeof method !== 'function')
             return;
-        target.addEventListener(eventName, method.bind(this));
+        if (args.length === 0) {
+            target.addEventListener(eventName, () => {
+                method.call(this);
+            });
+            return;
+        }
+        if (args.length === 1 && args[0][0] === 'e') {
+            target.addEventListener(eventName, (event) => {
+                method.call(this, event);
+            });
+            return;
+        }
+        target.addEventListener(eventName, (event) => {
+            method.apply(this, this.$resolveEventArgs(args, event, scope));
+        });
+    }
+    $resolveEventArgs(args, event, scope) {
+        const resolved = [];
+        for (let i = 0; i < args.length; i++) {
+            resolved.push(this.$resolveEventArg(args[i], event, scope));
+        }
+        return resolved;
+    }
+    $resolveEventArg(arg, event, scope) {
+        switch (arg[0]) {
+            case 'e': return event;
+            case 'p': return this.$resolveValue(arg[1], scope);
+            case 's': return arg[1];
+            case 'n': return arg[1];
+            case 'b': return !!arg[1];
+            case 'z': return null;
+        }
     }
     /** Find w-ref attributes and assign to component properties. */
     $wireRefs(root) {
@@ -1253,8 +1316,9 @@ export class WebUIElement extends HTMLElement {
                     c.anchor.parentNode?.insertBefore(frag, c.anchor.nextSibling);
                 }
             }
-            if (c.instance)
+            else {
                 this.$updateInstance(c.instance);
+            }
         }
         else if (c.instance) {
             this.$removeInstance(c.instance);
@@ -1300,11 +1364,14 @@ export class WebUIElement extends HTMLElement {
         const bm = this.$block(blockIndex);
         if (!bm)
             return null;
-        const frag = this.$parseTemplate(bm);
-        const wrapper = document.createElement('div');
-        wrapper.appendChild(frag);
+        const wrapper = this.$createStagingRoot(bm);
         const inst = this.$wire(wrapper, bm, scope);
         inst.nodes = childNodesArray(wrapper);
+        this.$updateInstance(inst);
+        if (inst.repeats.length !== 0 || inst.conds.length !== 0) {
+            inst.nodes = childNodesArray(wrapper);
+            this.$releaseStagingRepeatContainers(inst, wrapper);
+        }
         return inst;
     }
     $removeInstance(instance) {

package/dist/index.d.ts

@@ -19,6 +19,6 @@
  */
 export { WebUIElement } from './element.js';
 export { observable, attr } from './decorators.js';
-export { getTemplate } from './template.js';
+export { getTemplate, registerTemplateData } from './template.js';
 export type { TemplateMeta } from './template.js';
 export { hydrationStart, hydrationEnd } from './lifecycle.js';

package/dist/index.js

@@ -21,5 +21,5 @@
  */
 export { WebUIElement } from './element.js';
 export { observable, attr } from './decorators.js';
-export { getTemplate } from './template.js';
+export { getTemplate, registerTemplateData } from './template.js';
 export { hydrationStart, hydrationEnd } from './lifecycle.js';

package/dist/template-types.d.ts

@@ -16,21 +16,23 @@ export type CompiledAttrGroupMeta = [
     count: number
 ];
 /**
- * Compiled condition — a pre-compiled JS function plus the paths it references.
- * The Rust compiler emits the function body at build time so the runtime
- * doesn't need a condition AST interpreter.
+ * Compiled condition — JSON metadata carries a function index plus the paths it
+ * references. The Rust compiler emits the actual function bodies in a separate
+ * closure array, and the runtime normalizes indexes to functions once.
  *
- * - `[0]` — evaluator function: `(resolve, scope) => boolean`
+ * - `[0]` — evaluator function or component-local function index
  * - `[1]` — referenced paths for the reactive path index
  */
-export type CompiledCondition = [
-    fn: (v: (path: string, s?: unknown) => unknown, s?: unknown) => boolean,
-    paths: string[]
-];
-export type CompiledConditionalMeta = [condition: CompiledCondition, blockIndex: number, slot: TemplateSlotPath];
-export type CompiledAttrMeta = [name: string, kind: 0, value: string] | [name: string, kind: 1, value: string] | [name: string, kind: 2, condition: CompiledCondition] | [name: string, kind: 3, parts: CompiledAttrPart[]];
+export type CompiledConditionFn = (v: (path: string, s?: unknown) => unknown, s?: unknown) => boolean;
+export type CompiledCondition = [fn: CompiledConditionFn, paths: string[]];
+export type SerializedCompiledCondition = [fnIndex: number, paths: string[]];
+export type TemplateCondition = CompiledCondition | SerializedCompiledCondition;
+export type CompiledConditionalMeta = [condition: TemplateCondition, blockIndex: number, slot: TemplateSlotPath];
+export type CompiledAttrMeta = [name: string, kind: 0, value: string] | [name: string, kind: 1, value: string] | [name: string, kind: 2, condition: TemplateCondition] | [name: string, kind: 3, parts: CompiledAttrPart[]];
 export type CompiledRepeatMeta = [collection: string, itemVar: string, blockIndex: number, slot: TemplateSlotPath];
-export type CompiledEventMeta = [name: string, handler: string, needsEvent: number, target: TemplateNodePath];
+export type CompiledEventArg = ['e'] | ['p', string] | ['s', string] | ['n', number] | ['b', number] | ['z'];
+export type CompiledEventArgs = CompiledEventArg[];
+export type CompiledEventMeta = [name: string, handler: string, args: CompiledEventArgs, target: TemplateNodePath];
 export interface TemplateBlockMeta {
     h: string;
     tx?: CompiledTextRunMeta[];
@@ -43,7 +45,7 @@ export interface TemplateBlockMeta {
 export interface TemplateMeta extends TemplateBlockMeta {
     b?: TemplateBlockMeta[];
     sa?: string;
-    re?: [string, string, number][];
+    re?: [string, string, CompiledEventArgs][];
     /** Shadow DOM flag — when true, client-created components use shadow root. */
     sd?: boolean;
 }

package/dist/template.d.ts

@@ -6,27 +6,26 @@
  * - `tx` — text runs `[slot, parts]` for text binding positions
  * - `a`  — attribute binding metadata
  * - `ag` — attribute target groups `[path, startIndex, count]`
- * - `c`  — conditional blocks `[conditionAst, blockIndex]`
- * - `cl` — conditional anchor slots
- * - `r`  — repeat/for blocks `[collection, itemVar, blockIndex]`
- * - `rl` — repeat anchor slots
- * - `e`  — element events `[eventName, handlerName, needsEvent]`
- * - `el` — event target element paths
+ * - `c`  — conditional blocks `[conditionRef, blockIndex, slot]`
+ * - `r`  — repeat/for blocks `[collection, itemVar, blockIndex, slot]`
+ * - `e`  — element events `[eventName, handlerName, argSpecs, targetPath]`
  * - `b`  — nested compiled block metadata
  * - `sa` — adopted stylesheet specifier for CSS module strategy
  * - `sd` — shadow DOM flag for client-created components
  * - `re` — root events on the host element
  */
-export type { CompiledAttrGroupMeta, CompiledAttrMeta, CompiledAttrPart, CompiledCondition, CompiledConditionalMeta, CompiledTextRunMeta, TemplateBlockMeta, TemplateMeta, TemplateNodePath, TemplateSlotPath, } from './template-types.js';
-import type { TemplateMeta } from './template-types.js';
+export type { CompiledAttrGroupMeta, CompiledAttrMeta, CompiledAttrPart, CompiledCondition, CompiledConditionFn, CompiledConditionalMeta, CompiledEventArg, CompiledEventArgs, SerializedCompiledCondition, TemplateCondition, CompiledTextRunMeta, TemplateBlockMeta, TemplateMeta, TemplateNodePath, TemplateSlotPath, } from './template-types.js';
+import type { CompiledConditionFn, TemplateMeta } from './template-types.js';
 declare global {
     interface Window {
-        /** Consolidated SSR bootstrap object — single script block. */
+        /** Consolidated SSR metadata loaded from `#webui-data` or partial responses. */
         __webui?: {
             state?: Record<string, unknown>;
             templates?: Record<string, TemplateMeta>;
+            templateFns?: Record<string, CompiledConditionFn[]>;
             [key: string]: unknown;
         };
     }
 }
 export declare function getTemplate(name: string): TemplateMeta | undefined;
+export declare function registerTemplateData(templates: Record<string, TemplateMeta>, templateFns?: Record<string, CompiledConditionFn[]>): void;

package/dist/template.js

@@ -1,5 +1,96 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
+const WEBUI_DATA_ID = 'webui-data';
+const normalizedTemplates = new WeakSet();
+let webuiDataLoaded = false;
 export function getTemplate(name) {
-    return window.__webui?.templates?.[name];
+    let meta = window.__webui?.templates?.[name];
+    if (!meta) {
+        loadWebUIDataBlock();
+        meta = window.__webui?.templates?.[name];
+    }
+    if (meta)
+        normalizeTemplate(name, meta);
+    return meta;
+}
+export function registerTemplateData(templates, templateFns) {
+    const w = window;
+    if (!w.__webui)
+        w.__webui = {};
+    if (!w.__webui.templates)
+        w.__webui.templates = {};
+    if (templateFns) {
+        if (!w.__webui.templateFns)
+            w.__webui.templateFns = {};
+        const fnNames = Object.keys(templateFns);
+        for (let i = 0; i < fnNames.length; i++) {
+            const tag = fnNames[i];
+            w.__webui.templateFns[tag] = templateFns[tag];
+        }
+    }
+    const names = Object.keys(templates);
+    for (let i = 0; i < names.length; i++) {
+        const tag = names[i];
+        const meta = templates[tag];
+        w.__webui.templates[tag] = meta;
+        normalizeTemplate(tag, meta);
+    }
+}
+function loadWebUIDataBlock() {
+    if (webuiDataLoaded || window.__webui?.state !== undefined || typeof document === 'undefined')
+        return;
+    const el = document.getElementById(WEBUI_DATA_ID);
+    if (!el) {
+        webuiDataLoaded = true;
+        return;
+    }
+    const text = el.textContent;
+    if (text) {
+        const templateFns = window.__webui?.templateFns;
+        const parsed = JSON.parse(text);
+        if (templateFns)
+            parsed.templateFns = templateFns;
+        window.__webui = parsed;
+    }
+    el.remove();
+    webuiDataLoaded = true;
+}
+function normalizeTemplate(name, meta) {
+    if (normalizedTemplates.has(meta))
+        return;
+    const fns = window.__webui?.templateFns?.[name] ?? [];
+    const stack = [meta];
+    while (stack.length > 0) {
+        const block = stack.pop();
+        if (!block)
+            continue;
+        if (block.a) {
+            for (let i = 0; i < block.a.length; i++) {
+                const attr = block.a[i];
+                if (attr[1] === 2)
+                    normalizeCondition(name, attr[2], fns);
+            }
+        }
+        if (block.c) {
+            for (let i = 0; i < block.c.length; i++) {
+                normalizeCondition(name, block.c[i][0], fns);
+            }
+        }
+        const children = block.b;
+        if (children) {
+            for (let i = 0; i < children.length; i++)
+                stack.push(children[i]);
+        }
+    }
+    normalizedTemplates.add(meta);
+}
+function normalizeCondition(tagName, condition, fns) {
+    const first = condition[0];
+    if (typeof first === 'function')
+        return;
+    const fn = fns[first];
+    if (typeof fn !== 'function') {
+        throw new Error(`[WebUI] Missing condition closure ${first} for <${tagName}>.`);
+    }
+    condition[0] = fn;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/webui-framework",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "type": "module",
   "description": "WebUI Framework Next — Preact-inspired lightweight Web Component runtime with SSR hydration. 15KB minified, compiled-template path mapping, no hydration markers.",
   "license": "MIT",
@@ -19,7 +19,7 @@
     "@playwright/test": "^1.58.2",
     "@types/node": "^25.3.5",
     "typescript": "^5.9.3",
-    "@microsoft/webui-test-support": "0.0.14"
+    "@microsoft/webui-test-support": "0.0.16"
   },
   "scripts": {
     "build": "tsc",