@microsoft/webui-framework 0.0.10 → 0.0.11

package/README.md

@@ -8,11 +8,11 @@ This package is the browser-side runtime used by `webui build --plugin=webui`. I
 - `@observable`, `@attr`, and `@volatile` decorators
 - compiled template path mapping for direct DOM binding resolution
 - light DOM or shadow DOM rendering (`--dom=light|shadow` flag)
-- SSR state seeding from `window.__webui_state` (like Preact's props)
+- SSR state seeding from `window.__webui.state` (like Preact's props)
 
 If you are building WebUI apps in this repo, this is the component model used by examples like `examples/app/todo-webui`, `examples/app/commerce`, and `examples/app/contact-book-manager`.
 
-> 📖 **Full documentation at [microsoft.github.io/webui](https://microsoft.github.io/webui)** — see the [Interactivity Guide](https://microsoft.github.io/webui/guide/concepts/interactivity) for component authoring patterns.
+> 📖 **Full documentation at [microsoft.github.io/webui](https://microsoft.github.io/webui)**, see the [Interactivity Guide](https://microsoft.github.io/webui/guide/concepts/interactivity) for component authoring patterns. For framework internals (hydration, path resolution, reactive update model), see [RENDERING.md](./RENDERING.md).
 
 ## Install
 
@@ -93,7 +93,7 @@ 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 consumed by the runtime. In normal app code, you should not need to hand-author `window.__webui.templates`.
 
 ### DOM strategy (`--dom`)
 
@@ -107,7 +107,7 @@ The `--dom` flag controls how the server renders component content:
 The runtime auto-detects which mode was used at hydration time:
 - If a `shadowRoot` already exists → shadow DOM SSR path
 - If `childNodes` exist but no shadow root → light DOM SSR path
-- If neither → client-created path (uses `meta.sd` or `window.__webui_shadow` to decide)
+- If neither → client-created path (uses `meta.sd` to decide)
 
 Light DOM is useful for simpler styling (CSS inheritance works naturally) and
 better search-engine indexing.  Shadow DOM provides style encapsulation.
@@ -125,7 +125,7 @@ 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) |
-| `setInitialState(state, params?)` | Populate `@observable` properties from router state |
+| `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.
@@ -300,7 +300,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.state JSON  │
 │                      │     │                       │      │                      │
 │  Outputs:            │     │  Renders:             │      │  Hydrates:           │
 │  • TemplateMeta      │     │  • Full HTML page     │      │  • Path-based DOM    │
@@ -329,7 +329,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/>+ TemplateMeta &lt;script&gt;<br/>+ __webui.state &lt;script&gt;"]
     end
 
     subgraph Browser ["Browser"]
@@ -377,7 +377,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 a `window.__webui.state`
 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,13 +390,13 @@ 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/>+ __webui.state JSON
     Browser->>Browser: Parse HTML → DOM exists
     Browser->>CE: Custom element upgrade
     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 observables from __webui.state
     FW->>FW: $hydrate() — template-parallel path resolution
     FW->>FW: $resolveSSR() — match SSR nodes via ordinal traversal
     FW->>FW: $wireEvents() + $wireRefs()
@@ -552,7 +552,7 @@ 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
+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
 same data used for SSR rendering to the client.  During `$mount()`,
 `$applySSRState()` writes matching keys directly to observable backing fields
@@ -560,7 +560,7 @@ 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&gt;<br/>window.__webui.state = {<br/>  count: 42,<br/>  title: 'Hello'<br/>}"] --> 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"]
 ```
@@ -611,7 +611,7 @@ are removed; new items are appended.
 On initial hydration, the repeat system walks existing SSR children and
 reconstructs collection instances by matching them against the compiled
 template via `$resolveSSR` path traversal.  State is already seeded from
-`window.__webui_state`, so repeat items reflect the server-rendered list
+`window.__webui.state`, so repeat items reflect the server-rendered list
 without parsing marker comments.
 
 ---

package/dist/element.d.ts

@@ -17,23 +17,31 @@ export declare class WebUIElement extends HTMLElement {
     /** Mount the component after children are available. */
     private $mount;
     disconnectedCallback(): void;
+    /**
+     * Permanently destroy this component's own bindings and DOM references.
+     * Each component is responsible for its own cleanup — child WebUI
+     * elements handle theirs via their own `disconnectedCallback`.
+     */
+    $destroy(): void;
+    /** Break all DOM references held by a binding instance and its nested blocks. */
+    private $teardown;
     /** Dispatch a bubbling custom event. Uses composed:true when in shadow DOM. */
     $emit(name: string, detail?: unknown): boolean;
-    /** Populate @observable properties from router state.
+    /** Populate @observable properties from server or router state.
      *
      * Each property is set through its reactive setter, which coalesces
      * updates into a single pending microtask. We then synchronously
      * flush those pending path updates so the DOM is current before any
      * view-transition snapshot captures it.
      */
-    setInitialState(state: Record<string, unknown>): void;
+    setState(state: Record<string, unknown>): void;
     /**
-     * Apply SSR state from the global `window.__webui_state` object.
+     * Apply SSR state from `window.__webui.state`.
      *
-     * Passing the same props to both server render and client
-     * hydrate, this ensures component observables match the server-rendered
-     * DOM. The handler emits the state as a `<script>` tag at the end of
-     * the page. Only observable properties are set — unknown keys are ignored.
+     * The handler emits all SSR metadata in a single consolidated
+     * `window.__webui` script block. State lives at `.state` — the same
+     * props passed to the server render so observables match the DOM.
+     * Only observable properties are set — unknown keys are ignored.
      *
      * Writes directly to the backing field (`_prop`) to avoid triggering
      * reactive updates before bindings are wired.

package/dist/element.js

@@ -50,6 +50,8 @@ import { ATTR_KIND_BOOLEAN, ATTR_KIND_COMPLEX, ATTR_KIND_TEMPLATE, } from './ele
 const templateCache = new WeakMap();
 /** Parsed template DOM for SSR path mapping, keyed by TemplateBlockMeta. */
 const templateDOMCache = new WeakMap();
+/** Cached root tag name extracted from meta.h before it's released. */
+const rootTagCache = new WeakMap();
 /** Pre-computed ordinals for template nodes: childIndex → [nodeType, ordinal].
  *  Avoids re-counting element/text siblings on every $resolveSSR call. */
 const tplOrdinalCache = new WeakMap();
@@ -126,7 +128,7 @@ export class WebUIElement extends HTMLElement {
         const meta = getTemplate(tag);
         if (!meta) {
             console.warn(`[WebUI] Template metadata for <${tag}> not found. ` +
-                `Ensure the component is included in the SSR output or registered via __webui_templates.`);
+                `Ensure the component is included in the SSR output or registered via __webui.templates.`);
             return;
         }
         this.$meta = meta;
@@ -152,7 +154,7 @@ export class WebUIElement extends HTMLElement {
         hydrationStart();
         // Auto-detect shadow vs light DOM
         const hasShadow = !!this.shadowRoot;
-        const wantShadow = hasShadow || !!meta.sd || !!window.__webui_shadow;
+        const wantShadow = hasShadow || !!meta.sd;
         let root;
         let isSSR;
         if (hasShadow) {
@@ -209,10 +211,51 @@ export class WebUIElement extends HTMLElement {
         hydrationEnd();
     }
     disconnectedCallback() {
-        // Note: event listeners wired by $addEvent target child nodes owned by
-        // this component — they will be GC'd together with the component.
-        // We intentionally do NOT remove them here because connectedCallback
-        // does not re-wire events when a hydrated component is reattached.
+        // Schedule teardown on microtask — if the element is re-connected
+        // before then (e.g. repeat reconciliation), skip the cleanup.
+        if (this.$root) {
+            queueMicrotask(() => {
+                if (!this.isConnected)
+                    this.$destroy();
+            });
+        }
+    }
+    /**
+     * Permanently destroy this component's own bindings and DOM references.
+     * Each component is responsible for its own cleanup — child WebUI
+     * elements handle theirs via their own `disconnectedCallback`.
+     */
+    $destroy() {
+        if (!this.$root)
+            return;
+        this.$teardown(this.$root);
+        this.$root = null;
+        this.$pathIndex = undefined;
+        this.$wildcardBindings = undefined;
+        this.$dirtyPaths = null;
+        this.$pendingFlush = false;
+        this.$ready = false;
+    }
+    /** Break all DOM references held by a binding instance and its nested blocks. */
+    $teardown(instance) {
+        for (const c of instance.conds) {
+            if (c.instance)
+                this.$teardown(c.instance);
+            c.instance = null;
+        }
+        for (const r of instance.repeats) {
+            for (const item of r.instances)
+                this.$teardown(item.instance);
+            r.instances.length = 0;
+            r.container = null;
+            r.start = null;
+            r.end = null;
+        }
+        instance.nodes.length = 0;
+        instance.texts.length = 0;
+        instance.attrs.length = 0;
+        instance.conds.length = 0;
+        instance.repeats.length = 0;
     }
     /** Dispatch a bubbling custom event. Uses composed:true when in shadow DOM. */
     $emit(name, detail) {
@@ -223,16 +266,18 @@ export class WebUIElement extends HTMLElement {
             detail,
         }));
     }
-    /** Populate @observable properties from router state.
+    /** Populate @observable properties from server or router state.
      *
      * Each property is set through its reactive setter, which coalesces
      * updates into a single pending microtask. We then synchronously
      * flush those pending path updates so the DOM is current before any
      * view-transition snapshot captures it.
      */
-    setInitialState(state) {
+    setState(state) {
         const names = getObservableNames(this.constructor);
-        for (const key of Object.keys(state)) {
+        const keys = Object.keys(state);
+        for (let i = 0; i < keys.length; i++) {
+            const key = keys[i];
             if (names.has(key)) {
                 this[key] = state[key];
             }
@@ -240,18 +285,18 @@ export class WebUIElement extends HTMLElement {
         this.$flushUpdates();
     }
     /**
-     * Apply SSR state from the global `window.__webui_state` object.
+     * Apply SSR state from `window.__webui.state`.
      *
-     * Passing the same props to both server render and client
-     * hydrate, this ensures component observables match the server-rendered
-     * DOM. The handler emits the state as a `<script>` tag at the end of
-     * the page. Only observable properties are set — unknown keys are ignored.
+     * The handler emits all SSR metadata in a single consolidated
+     * `window.__webui` script block. State lives at `.state` — the same
+     * props passed to the server render so observables match the DOM.
+     * Only observable properties are set — unknown keys are ignored.
      *
      * Writes directly to the backing field (`_prop`) to avoid triggering
      * reactive updates before bindings are wired.
      */
     $applySSRState() {
-        const state = window.__webui_state;
+        const state = window.__webui?.state;
         if (!state || typeof state !== 'object')
             return;
         const names = getObservableNames(this.constructor);
@@ -856,9 +901,14 @@ export class WebUIElement extends HTMLElement {
     }
     /** Extract root tag name from block metadata. */
     $rootTag(meta) {
+        let cached = rootTagCache.get(meta);
+        if (cached !== undefined)
+            return cached;
         const h = meta.h;
-        if (!h || h.charCodeAt(0) !== 60)
+        if (!h || h.charCodeAt(0) !== 60) {
+            rootTagCache.set(meta, null);
             return null;
+        }
         let end = 1;
         while (end < h.length) {
             const c = h.charCodeAt(end);
@@ -866,7 +916,9 @@ export class WebUIElement extends HTMLElement {
                 break;
             end++;
         }
-        return h.slice(1, end).toLowerCase();
+        const tag = h.slice(1, end).toLowerCase();
+        rootTagCache.set(meta, tag);
+        return tag;
     }
     // ═══════════════════════════════════════════════════════════════
     //  Shared: binding wiring, event wiring, refs
@@ -914,14 +966,11 @@ export class WebUIElement extends HTMLElement {
         }
     }
     /** Attach a single event listener. */
-    $addEvent(target, eventName, handlerName, needsEvent) {
+    $addEvent(target, eventName, handlerName, _needsEvent) {
         const method = this[handlerName];
         if (typeof method !== 'function')
             return;
-        const self = this;
-        target.addEventListener(eventName, needsEvent
-            ? (e) => method.call(self, e)
-            : () => method.call(self));
+        target.addEventListener(eventName, method.bind(this));
     }
     /** Find w-ref attributes and assign to component properties. */
     $wireRefs(root) {

package/dist/template.d.ts

@@ -21,10 +21,12 @@ export type { CompiledAttrGroupMeta, CompiledAttrMeta, CompiledAttrPart, Compile
 import type { TemplateMeta } from './template-types.js';
 declare global {
     interface Window {
-        __webui_templates?: Record<string, TemplateMeta>;
-        __webui_state?: Record<string, unknown>;
-        /** When true, all client-created components use shadow DOM. */
-        __webui_shadow?: boolean;
+        /** Consolidated SSR bootstrap object — single script block. */
+        __webui?: {
+            state?: Record<string, unknown>;
+            templates?: Record<string, TemplateMeta>;
+            [key: string]: unknown;
+        };
     }
 }
 export declare function getTemplate(name: string): TemplateMeta | undefined;

package/dist/template.js

@@ -1,5 +1,5 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
 export function getTemplate(name) {
-    return window.__webui_templates?.[name];
+    return window.__webui?.templates?.[name];
 }

package/package.json

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