@microsoft/webui-framework 0.0.13 → 0.0.15

package/README.md

@@ -95,6 +95,16 @@ 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`.
 
+### 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`)
 
 The `--dom` flag controls how the server renders component content:
@@ -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.
 
 ---
@@ -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,8 +482,7 @@ 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
 }
 ```
 
@@ -624,7 +633,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/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
     // ═══════════════════════════════════════════════════════════════
@@ -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 });
                 }
@@ -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/template-types.d.ts

@@ -30,7 +30,9 @@ export type CompiledCondition = [
 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 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

@@ -10,14 +10,13 @@
  * - `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
+ * - `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';
+export type { CompiledAttrGroupMeta, CompiledAttrMeta, CompiledAttrPart, CompiledCondition, CompiledConditionalMeta, CompiledEventArg, CompiledEventArgs, CompiledTextRunMeta, TemplateBlockMeta, TemplateMeta, TemplateNodePath, TemplateSlotPath, } from './template-types.js';
 import type { TemplateMeta } from './template-types.js';
 declare global {
     interface Window {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/webui-framework",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "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.13"
+    "@microsoft/webui-test-support": "0.0.15"
   },
   "scripts": {
     "build": "tsc",