From 3e27f1f77d56d1e3d1fdc3581ae9b5c22b771292 Mon Sep 17 00:00:00 2001
From: Mohamed Mansour <hello@mohamedmansour.com>
Date: Fri, 27 Mar 2026 14:21:28 -0700
Subject: [PATCH 1/4] feat: add todo-webui app

---
 examples/app/todo-fast/package.json           |   1 +
 examples/app/todo-webui/README.md             |  31 ++
 examples/app/todo-webui/data/state.json       |  23 +
 examples/app/todo-webui/package.json          |  21 +
 examples/app/todo-webui/playwright.config.ts  |  18 +
 examples/app/todo-webui/src/index.html        |  77 ++++
 examples/app/todo-webui/src/index.ts          |  39 ++
 .../app/todo-webui/src/todo-app/todo-app.css  |  64 +++
 .../app/todo-webui/src/todo-app/todo-app.html |  30 ++
 .../app/todo-webui/src/todo-app/todo-app.ts   |  59 +++
 .../todo-webui/src/todo-item/todo-item.css    |  69 +++
 .../todo-webui/src/todo-item/todo-item.html   |  13 +
 .../app/todo-webui/src/todo-item/todo-item.ts |  24 +
 .../app/todo-webui/tests/todo-webui.spec.ts   | 417 ++++++++++++++++++
 examples/app/todo-webui/tsconfig.json         |  16 +
 15 files changed, 902 insertions(+)
 create mode 100644 examples/app/todo-webui/README.md
 create mode 100644 examples/app/todo-webui/data/state.json
 create mode 100644 examples/app/todo-webui/package.json
 create mode 100644 examples/app/todo-webui/playwright.config.ts
 create mode 100644 examples/app/todo-webui/src/index.html
 create mode 100644 examples/app/todo-webui/src/index.ts
 create mode 100644 examples/app/todo-webui/src/todo-app/todo-app.css
 create mode 100644 examples/app/todo-webui/src/todo-app/todo-app.html
 create mode 100644 examples/app/todo-webui/src/todo-app/todo-app.ts
 create mode 100644 examples/app/todo-webui/src/todo-item/todo-item.css
 create mode 100644 examples/app/todo-webui/src/todo-item/todo-item.html
 create mode 100644 examples/app/todo-webui/src/todo-item/todo-item.ts
 create mode 100644 examples/app/todo-webui/tests/todo-webui.spec.ts
 create mode 100644 examples/app/todo-webui/tsconfig.json

diff --git a/examples/app/todo-fast/package.json b/examples/app/todo-fast/package.json
index b5ab7fa1..b9ba01ae 100644
--- a/examples/app/todo-fast/package.json
+++ b/examples/app/todo-fast/package.json
@@ -4,6 +4,7 @@
   "type": "module",
   "private": true,
   "scripts": {
+    "build": "esbuild src/index.ts --bundle --outfile=dist/index.js --format=esm --metafile=dist/meta.json",
     "start:client": "esbuild src/index.ts --bundle --outfile=dist/index.js --format=esm --sourcemap --watch",
     "start:server": "cargo run -p microsoft-webui-cli -- serve ./src --state ./data/state.json --plugin=fast --servedir ./dist --port 3001 --watch",
     "start": "cargo xtask dev todo-fast"
diff --git a/examples/app/todo-webui/README.md b/examples/app/todo-webui/README.md
new file mode 100644
index 00000000..a9a9811d
--- /dev/null
+++ b/examples/app/todo-webui/README.md
@@ -0,0 +1,31 @@
+
+### todo-webui (WebUI Framework hydration)
+
+```bash
+# Install JS dependencies (esbuild, @microsoft/webui-framework)
+pnpm install
+
+# Build the protocol with WebUI parser plugin
+cargo run -p microsoft-webui-cli -- build examples/app/todo-webui/src --out examples/app/todo-webui/dist --plugin=webui
+
+# Or use the dev server with live rendering
+cd examples/app/todo-webui
+cargo run -p microsoft-webui-cli -- serve ./src --state ./data/state.json --plugin=webui --servedir ./dist --port 3006
+```
+
+### Using `--plugin=webui`
+
+The `--plugin=webui` flag enables:
+
+1. **Parser plugin (`WebUIParserPlugin`)** — During `webui build`:
+   - Skips WebUI Framework runtime attributes (`@click`, `w-ref`, etc.)
+   - Counts dynamic attribute bindings per element and emits `Plugin` protocol fragments
+   - Tracks components and generates `<w-template name="...">` client template strings
+
+2. **Handler plugin (`WebUIHydrationPlugin`)** — During rendering:
+   - Wraps signals, for-loops, and if-conditions in `<!--w-b:start:INDEX:NAME-->` comment markers
+   - Wraps for-loop items in `<!--w-r:start:INDEX-->` comment markers
+   - Emits `data-w-b-*` / `data-w-c-*` attributes for element bindings
+   - Manages per-component/per-item scope counters for binding indices
+
+These markers enable `@microsoft/webui-framework`'s client-side hydration.
\ No newline at end of file
diff --git a/examples/app/todo-webui/data/state.json b/examples/app/todo-webui/data/state.json
new file mode 100644
index 00000000..deb2f003
--- /dev/null
+++ b/examples/app/todo-webui/data/state.json
@@ -0,0 +1,23 @@
+{
+    "textdirection": "ltr",
+    "language": "en",
+    "title": "Todo List",
+    "remainingCount": 2,
+    "items": [
+        {
+            "id": "1",
+            "title": "Buy groceries",
+            "state": "done"
+        },
+        {
+            "id": "2",
+            "title": "Write documentation",
+            "state": "pending"
+        },
+        {
+            "id": "3",
+            "title": "Ship feature",
+            "state": "pending"
+        }
+    ]
+}
diff --git a/examples/app/todo-webui/package.json b/examples/app/todo-webui/package.json
new file mode 100644
index 00000000..aa7316a5
--- /dev/null
+++ b/examples/app/todo-webui/package.json
@@ -0,0 +1,21 @@
+{
+  "name": "todo-webui-example",
+  "version": "1.0.0",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --outfile=dist/index.js --format=esm --metafile=dist/meta.json --minify",
+    "start:client": "esbuild src/index.ts --bundle --outfile=dist/index.js --format=esm --sourcemap --watch",
+    "start:server": "cargo run -p microsoft-webui-cli -- serve ./src --state ./data/state.json --plugin=webui --servedir ./dist --port 3006 --watch",
+    "start": "cargo xtask dev todo-webui",
+    "test": "playwright test",
+    "test:update-snapshots": "playwright test --update-snapshots"
+  },
+  "devDependencies": {
+    "@microsoft/webui-framework": "workspace:*",
+    "@playwright/test": "catalog:",
+    "esbuild": "catalog:",
+    "tslib": "catalog:",
+    "typescript": "catalog:"
+  }
+}
diff --git a/examples/app/todo-webui/playwright.config.ts b/examples/app/todo-webui/playwright.config.ts
new file mode 100644
index 00000000..929889a6
--- /dev/null
+++ b/examples/app/todo-webui/playwright.config.ts
@@ -0,0 +1,18 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests',
+  snapshotPathTemplate:
+    '{snapshotDir}/{testFileDir}/{testFileName}-snapshots/{arg}-{projectName}{ext}',
+  timeout: 30_000,
+  use: {
+    baseURL: 'http://127.0.0.1:3006',
+    screenshot: 'only-on-failure',
+  },
+  projects: [
+    { name: 'chromium', use: { browserName: 'chromium' } },
+  ],
+});
diff --git a/examples/app/todo-webui/src/index.html b/examples/app/todo-webui/src/index.html
new file mode 100644
index 00000000..ff540433
--- /dev/null
+++ b/examples/app/todo-webui/src/index.html
@@ -0,0 +1,77 @@
+<!DOCTYPE html>
+<html dir="{{textdirection}}" lang="{{language}}">
+
+<head>
+  <meta charset="utf-8">
+  <title>{{title}}</title>
+  <style>
+    :root {
+      /* Brand */
+      --color-brand-primary: #0078d4;
+      --color-brand-primary-hover: #106ebe;
+
+      /* Neutral */
+      --color-neutral-800: #1a1a1a;
+      --color-neutral-500: #666;
+      --color-neutral-400: #999;
+      --color-neutral-300: #ccc;
+      --color-neutral-200: #eee;
+      --color-neutral-100: #f5f5f5;
+      --color-white: #fff;
+
+      /* Semantic */
+      --color-success: #4caf50;
+      --color-success-light: #e8f5e9;
+      --color-danger: #e53935;
+      --color-danger-light: #ffebee;
+
+      /* Spacing */
+      --spacing-s: 8px;
+      --spacing-m: 10px;
+      --spacing-ml: 12px;
+      --spacing-l: 14px;
+      --spacing-xl: 16px;
+      --spacing-xxl: 20px;
+      --spacing-xxxl: 24px;
+
+      /* Border Radius */
+      --border-radius-s: 4px;
+      --border-radius-m: 6px;
+      --border-radius-l: 8px;
+      --border-radius-round: 50%;
+
+      /* Shadows */
+      --shadow-s: 0 1px 3px rgba(0, 0, 0, 0.12);
+      --shadow-focus-ring: 0 0 0 2px rgba(0, 120, 212, 0.2);
+
+      /* Typography */
+      --font-family-base: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
+      --font-size-m: 14px;
+      --font-size-ml: 15px;
+      --font-size-xxl: 28px;
+    }
+
+    * {
+      box-sizing: border-box;
+      margin: 0;
+      padding: 0;
+    }
+
+    body {
+      font-family: var(--font-family-base);
+      max-width: 640px;
+      margin: 0 auto;
+      padding: var(--spacing-xxxl);
+      background: var(--color-neutral-100);
+      color: var(--color-neutral-800);
+    }
+  </style>
+</head>
+
+<body>
+  <todo-app title="{{title}}"></todo-app>
+
+  <script type="module" src="/index.js"></script>
+</body>
+
+</html>
diff --git a/examples/app/todo-webui/src/index.ts b/examples/app/todo-webui/src/index.ts
new file mode 100644
index 00000000..b60e19ef
--- /dev/null
+++ b/examples/app/todo-webui/src/index.ts
@@ -0,0 +1,39 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+/**
+ * Todo-webui entry point — bootstraps WebUI Framework hydration.
+ *
+ * The server pre-renders HTML with hydration markers via `webui build --plugin=webui`.
+ * Compiled templates are registered automatically by `<script>` blocks emitted
+ * by the handler — no WTemplateElement needed.
+ *
+ * This script registers custom elements so they upgrade and hydrate.
+ * The framework fires `webui:hydration-complete` on `window` once all
+ * components have finished hydrating.
+ */
+
+// Listen for the framework's global hydration-complete event.
+// NOTE: ES module imports are hoisted, so hydration may complete before
+// this listener is registered. Check for the performance mark as a fallback.
+window.addEventListener('webui:hydration-complete', logHydrationTiming);
+
+function logHydrationTiming(): void {
+  const total = performance.getEntriesByName('webui:hydrate:total', 'measure')[0];
+  console.log(`Hydration complete in ${total?.duration.toFixed(1)}ms`);
+
+  for (const entry of performance.getEntriesByType('measure')) {
+    if (entry.name.startsWith('webui:hydrate:') && entry.name !== 'webui:hydrate:total') {
+      console.log(`  ${entry.name}: ${entry.duration.toFixed(1)}ms`);
+    }
+  }
+}
+
+// Side-effect imports — register custom elements and trigger hydration
+import './todo-app/todo-app.js';
+import './todo-item/todo-item.js';
+
+// Fallback: if hydration already completed before the listener, log now
+if (performance.getEntriesByName('webui:hydrate:total', 'measure').length > 0) {
+  logHydrationTiming();
+}
diff --git a/examples/app/todo-webui/src/todo-app/todo-app.css b/examples/app/todo-webui/src/todo-app/todo-app.css
new file mode 100644
index 00000000..44c047ab
--- /dev/null
+++ b/examples/app/todo-webui/src/todo-app/todo-app.css
@@ -0,0 +1,64 @@
+/* Copyright (c) Microsoft Corporation. */
+/* Licensed under the MIT license. */
+
+:host {
+  display: block;
+}
+
+h1 {
+  font-size: var(--font-size-xxl);
+  font-weight: 600;
+  margin-bottom: var(--spacing-xxl);
+  color: var(--color-brand-primary);
+}
+
+.add-form {
+  display: flex;
+  gap: var(--spacing-s);
+  margin-bottom: var(--spacing-xl);
+}
+
+.add-input {
+  flex: 1;
+  padding: var(--spacing-m) var(--spacing-l);
+  font-size: var(--font-size-ml);
+  border: 1px solid var(--color-neutral-300);
+  border-radius: var(--border-radius-m);
+  outline: none;
+  font-family: inherit;
+}
+
+.add-input:focus {
+  border-color: var(--color-brand-primary);
+  box-shadow: var(--shadow-focus-ring);
+}
+
+.add-button {
+  padding: var(--spacing-m) var(--spacing-xxl);
+  font-size: var(--font-size-ml);
+  font-family: inherit;
+  background: var(--color-brand-primary);
+  color: var(--color-white);
+  border: none;
+  border-radius: var(--border-radius-m);
+  cursor: pointer;
+}
+
+.add-button:hover {
+  background: var(--color-brand-primary-hover);
+}
+
+.todo-list {
+  background: var(--color-white);
+  border-radius: var(--border-radius-l);
+  box-shadow: var(--shadow-s);
+  overflow: hidden;
+}
+
+.footer {
+  margin-top: var(--spacing-xl);
+  padding: var(--spacing-ml);
+  text-align: center;
+  font-size: var(--font-size-m);
+  color: var(--color-neutral-500);
+}
diff --git a/examples/app/todo-webui/src/todo-app/todo-app.html b/examples/app/todo-webui/src/todo-app/todo-app.html
new file mode 100644
index 00000000..fd7467be
--- /dev/null
+++ b/examples/app/todo-webui/src/todo-app/todo-app.html
@@ -0,0 +1,30 @@
+<template shadowrootmode="open"
+  @toggle-item="{onToggleItem(e)}"
+  @delete-item="{onDeleteItem(e)}"
+>
+  <h1>{{title}}</h1>
+
+  <div class="add-form">
+    <input
+      class="add-input"
+      placeholder="What needs to be done?"
+      w-ref="addInput"
+      @keydown="{onAddKeydown(e)}"
+    />
+    <button class="add-button" @click="{onAddClick()}">Add</button>
+  </div>
+
+  <div class="todo-list">
+    <for each="item in items">
+      <todo-item
+        id="{{item.id}}"
+        title="{{item.title}}"
+        state="{{item.state}}"
+      ></todo-item>
+    </for>
+  </div>
+
+  <div class="footer">
+    <span>{{remainingCount}} items remaining</span>
+  </div>
+</template>
diff --git a/examples/app/todo-webui/src/todo-app/todo-app.ts b/examples/app/todo-webui/src/todo-app/todo-app.ts
new file mode 100644
index 00000000..bbf6904c
--- /dev/null
+++ b/examples/app/todo-webui/src/todo-app/todo-app.ts
@@ -0,0 +1,59 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { WebUIElement, attr, observable, volatile } from '@microsoft/webui-framework';
+
+interface TodoItemData {
+  id: string;
+  title: string;
+  state: string;
+}
+
+export class TodoApp extends WebUIElement {
+  @attr title = '';
+  @observable items: TodoItemData[] = [];
+
+  @volatile get remainingCount(): number {
+    return (this.items ?? []).filter(i => i.state !== 'done').length;
+  }
+
+  addInput!: HTMLInputElement;
+  private nextId = 100;
+
+  onToggleItem(e: CustomEvent<{ id: string }>): void {
+    const item = (this.items ?? []).find(i => i.id === e.detail.id);
+    if (item) {
+      item.state = item.state === 'done' ? 'pending' : 'done';
+      this.items = [...this.items];
+    }
+  }
+
+  onDeleteItem(e: CustomEvent<{ id: string }>): void {
+    this.items = (this.items ?? []).filter(item => item.id !== e.detail.id);
+  }
+
+  onAddKeydown(e: KeyboardEvent): void {
+    if (e.key === 'Enter') this.addTodo();
+  }
+
+  onAddClick(): void {
+    this.addTodo();
+  }
+
+  private addTodo(): void {
+    const input = this.addInput;
+    if (!input) return;
+
+    const text = input.value.trim();
+    if (!text) return;
+
+    this.items = [
+      ...this.items,
+      { id: String(this.nextId++), title: text, state: 'pending' },
+    ];
+    input.value = '';
+    input.focus();
+  }
+}
+
+TodoApp.define('todo-app');
diff --git a/examples/app/todo-webui/src/todo-item/todo-item.css b/examples/app/todo-webui/src/todo-item/todo-item.css
new file mode 100644
index 00000000..923db88c
--- /dev/null
+++ b/examples/app/todo-webui/src/todo-item/todo-item.css
@@ -0,0 +1,69 @@
+/* Copyright (c) Microsoft Corporation. */
+/* Licensed under the MIT license. */
+
+:host {
+  display: block;
+}
+
+:host([state="done"]) .title {
+  text-decoration: line-through;
+  color: var(--color-neutral-400);
+}
+
+.item {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-m);
+  padding: var(--spacing-ml) var(--spacing-l);
+  border-bottom: 1px solid var(--color-neutral-200);
+}
+
+.toggle {
+  width: 28px;
+  height: 28px;
+  border-radius: var(--border-radius-round);
+  border: 2px solid var(--color-neutral-300);
+  background: transparent;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  font-size: var(--font-size-m);
+  color: var(--color-success);
+}
+
+:host([state="done"]) .toggle {
+  border-color: var(--color-success);
+  background: var(--color-success-light);
+}
+
+.title {
+  flex: 1;
+  font-size: var(--font-size-ml);
+}
+
+.delete {
+  width: 28px;
+  height: 28px;
+  border: none;
+  background: transparent;
+  cursor: pointer;
+  font-size: 20px;
+  color: var(--color-neutral-300);
+  border-radius: var(--border-radius-s);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  opacity: 0;
+  transition: opacity 0.15s;
+}
+
+.item:hover .delete {
+  opacity: 1;
+}
+
+.delete:hover {
+  color: var(--color-danger);
+  background: var(--color-danger-light);
+}
diff --git a/examples/app/todo-webui/src/todo-item/todo-item.html b/examples/app/todo-webui/src/todo-item/todo-item.html
new file mode 100644
index 00000000..b75b2058
--- /dev/null
+++ b/examples/app/todo-webui/src/todo-item/todo-item.html
@@ -0,0 +1,13 @@
+<template shadowrootmode="open"
+  @click="{onClick(e)}"
+>
+  <div class="item">
+    <button class="toggle" data-action="toggle" title="Toggle complete">
+      <if condition="state == 'done'">
+        <span class="check">&#10003;</span>
+      </if>
+    </button>
+    <span class="title">{{title}}</span>
+    <button class="delete" data-action="delete" title="Delete">&times;</button>
+  </div>
+</template>
diff --git a/examples/app/todo-webui/src/todo-item/todo-item.ts b/examples/app/todo-webui/src/todo-item/todo-item.ts
new file mode 100644
index 00000000..d129a8a6
--- /dev/null
+++ b/examples/app/todo-webui/src/todo-item/todo-item.ts
@@ -0,0 +1,24 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { WebUIElement, attr } from '@microsoft/webui-framework';
+
+export class TodoItem extends WebUIElement {
+  @attr id = '';
+  @attr title = '';
+  @attr state = '';
+
+  onClick(e: MouseEvent): void {
+    const target = e.composedPath()[0] as HTMLElement;
+    const action = target.closest('[data-action]')?.getAttribute('data-action');
+    if (!action) return;
+
+    if (action === 'toggle') {
+      this.$emit('toggle-item', { id: this.id });
+    } else if (action === 'delete') {
+      this.$emit('delete-item', { id: this.id });
+    }
+  }
+}
+
+TodoItem.define('todo-item');
diff --git a/examples/app/todo-webui/tests/todo-webui.spec.ts b/examples/app/todo-webui/tests/todo-webui.spec.ts
new file mode 100644
index 00000000..746abb98
--- /dev/null
+++ b/examples/app/todo-webui/tests/todo-webui.spec.ts
@@ -0,0 +1,417 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { test, expect } from '@playwright/test';
+
+test.describe('SSR rendering', () => {
+  test('renders heading and initial state', async ({ page }) => {
+    await page.goto('/');
+    await expect(page.locator('h1')).toContainText('Todo List');
+    await expect(page.getByText('Buy groceries')).toBeVisible();
+    await expect(page.getByText('Write documentation')).toBeVisible();
+    await expect(page.getByText('Ship feature')).toBeVisible();
+    await expect(page.getByText('2 items remaining')).toBeVisible();
+  });
+
+  test('renders completed item with strikethrough', async ({ page }) => {
+    await page.goto('/');
+    // "Buy groceries" has state="done" — its todo-item host should have that attribute
+    const doneItem = page.locator('todo-item[state="done"]');
+    await expect(doneItem).toBeVisible();
+    await expect(doneItem).toContainText('Buy groceries');
+  });
+
+  test('compiled templates registered in global registry', async ({ page }) => {
+    await page.goto('/');
+    const templateNames = await page.evaluate(
+      () => Object.keys(window.__webui_templates ?? {}),
+    );
+    expect(templateNames).toContain('todo-app');
+    expect(templateNames).toContain('todo-item');
+  });
+
+  test('compiled template is a metadata object', async ({ page }) => {
+    await page.goto('/');
+    const meta = await page.evaluate(() => {
+      const template = window.__webui_templates?.['todo-app'];
+      const textPaths = Array.isArray(template?.tx)
+        ? template.tx
+          .flatMap(([, parts]) => parts)
+          .filter((part) => Array.isArray(part))
+          .map(([path]) => path)
+        : [];
+
+      return {
+        h: template?.h ?? '',
+        textPaths,
+        repeat: template?.r?.[0] ?? null,
+        hasRepeatSlots: Array.isArray(template?.rl),
+        eventCount: template?.e?.length ?? 0,
+        hasEventTargets: Array.isArray(template?.el),
+      };
+    });
+
+    // h: marker-free static HTML with only static attributes left in place
+    expect(meta.h).toContain('w-ref');
+    expect(meta.h).not.toContain('<!--t:');
+    expect(meta.h).not.toContain('<!--c:');
+    expect(meta.h).not.toContain('<!--r:');
+    expect(meta.h).not.toContain('data-w-');
+    expect(meta.h).not.toContain('data-ev');
+    expect(meta.h).not.toContain('{{');
+    expect(meta.h).not.toContain('<for');
+    expect(meta.h).not.toContain('<if');
+    expect(meta.h).not.toContain('shadowrootmode');
+
+    // tx: locator-driven text runs
+    expect(meta.textPaths).toContain('title');
+    expect(meta.textPaths).toContain('remainingCount');
+
+    // r/rl: repeat bindings plus anchor slots
+    expect(meta.repeat).not.toBeNull();
+    expect(meta.repeat[0]).toBe('items'); // collection
+    expect(meta.repeat[1]).toBe('item');  // item var
+    expect(meta.hasRepeatSlots).toBe(true);
+
+    // e/el: events plus target locators
+    expect(meta.eventCount).toBeGreaterThan(0);
+    expect(meta.hasEventTargets).toBe(true);
+  });
+
+  test('no console errors on page load', async ({ page }) => {
+    const errors: string[] = [];
+    page.on('pageerror', (err) => errors.push(err.message));
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') errors.push(msg.text());
+    });
+    await page.goto('/');
+    await page.waitForTimeout(500);
+    expect(errors).toEqual([]);
+  });
+
+  test('fires webui:hydration-complete event with performance marks', async ({ page }) => {
+    await page.goto('/');
+    // Wait for the hydration-complete event to have fired
+    const result = await page.evaluate(() =>
+      new Promise<Record<string, unknown>>((resolve) => {
+        // If already complete, read immediately
+        const total = performance.getEntriesByName('webui:hydrate:total', 'measure');
+        if (total.length > 0) {
+          const perComponent = performance.getEntriesByType('measure')
+            .filter(e => e.name.startsWith('webui:hydrate:') && e.name !== 'webui:hydrate:total')
+            .map(e => e.name);
+          return resolve({
+            totalDuration: total[0].duration,
+            components: perComponent,
+          });
+        }
+        // Otherwise wait
+        window.addEventListener('webui:hydration-complete', () => {
+          const t = performance.getEntriesByName('webui:hydrate:total', 'measure');
+          const perComp = performance.getEntriesByType('measure')
+            .filter(e => e.name.startsWith('webui:hydrate:') && e.name !== 'webui:hydrate:total')
+            .map(e => e.name);
+          resolve({ totalDuration: t[0]?.duration, components: perComp });
+        });
+      }),
+    );
+
+    expect(result.totalDuration).toBeGreaterThanOrEqual(0);
+    const components = result.components as string[];
+    // Should have hydrated todo-app and at least 3 todo-items
+    expect(components.some(c => c.includes('todo-app'))).toBe(true);
+    expect(components.some(c => c.includes('todo-item'))).toBe(true);
+    expect(components.length).toBeGreaterThanOrEqual(4);
+  });
+
+  test('one-shot hydration markers removed while repeat anchors stay available', async ({ page }) => {
+    await page.goto('/');
+    const result = await page.evaluate(() => {
+      const app = document.querySelector('todo-app');
+      const sr = app?.shadowRoot;
+      if (!sr) return { error: 'no shadow root' };
+
+      // Check for any remaining hydration comments
+      const walker = document.createTreeWalker(sr, NodeFilter.SHOW_COMMENT);
+      const bindingComments: string[] = [];
+      const repeatComments: string[] = [];
+      let c: Comment | null;
+      while ((c = walker.nextNode() as Comment | null)) {
+        if (!(c.data.startsWith('w-b:') || c.data.startsWith('w-r:'))) {
+          continue;
+        }
+
+        if (c.data.includes(':for-') || c.data.startsWith('w-r:')) {
+          repeatComments.push(c.data);
+        } else {
+          bindingComments.push(c.data);
+        }
+      }
+
+      // Check for any data-w-* attributes
+      const dataWAttrs: string[] = [];
+      for (const el of sr.querySelectorAll('*')) {
+        for (const attr of el.attributes) {
+          if (attr.name.startsWith('data-w-')) {
+            dataWAttrs.push(`${el.tagName}:${attr.name}`);
+          }
+        }
+      }
+
+      return { bindingComments, repeatComments, dataWAttrs };
+    });
+
+    expect(result.bindingComments).toEqual([]);
+    expect(result.repeatComments.length).toBeGreaterThan(0);
+    expect(result.dataWAttrs).toEqual([]);
+  });
+
+  test('reactive text bindings still work after one-shot markers are removed', async ({ page }) => {
+    await page.goto('/');
+
+    // Verify text/conditional hydration markers are gone even though repeat
+    // anchors can remain for reconciliation.
+    const markersGone = await page.evaluate(() => {
+      const sr = document.querySelector('todo-app')?.shadowRoot;
+      const walker = document.createTreeWalker(sr!, NodeFilter.SHOW_COMMENT);
+      let c;
+      while ((c = walker.nextNode())) {
+        const data = (c as Comment).data;
+        if ((data.startsWith('w-b:') || data.startsWith('w-r:')) && !data.includes(':for-')) {
+          return false;
+        }
+      }
+      return true;
+    });
+    expect(markersGone).toBe(true);
+
+    // Now trigger a reactive update — add a todo item
+    await page.evaluate(() => {
+      const app = document.querySelector('todo-app')!;
+      (app as any).addInput.value = 'After marker removal';
+      (app as any).addInput.dispatchEvent(new Event('input', { bubbles: true }));
+    });
+    await page.evaluate(() => {
+      document.querySelector('todo-app')!.shadowRoot!
+        .querySelector<HTMLButtonElement>('.add-button')!.click();
+    });
+
+    // The new item should appear (repeat reconciliation works)
+    await expect(page.locator('todo-item[title="After marker removal"]')).toBeAttached();
+
+    // Remaining count should have updated reactively (text binding works)
+    const remaining = await page.evaluate(() => {
+      const app = document.querySelector('todo-app');
+      return (app as any).remainingCount;
+    });
+    expect(remaining).toBe(3); // 2 original pending + 1 new
+  });
+});
+
+test.describe('interactivity', () => {
+  test('add a new todo item', async ({ page }) => {
+    await page.goto('/');
+    await page.waitForFunction(
+      () => document.querySelector('todo-app')?.addInput instanceof HTMLInputElement,
+    );
+
+    // Fill and click inside shadow DOM
+    await page.evaluate(() => {
+      const app = document.querySelector('todo-app')!;
+      app.addInput.value = 'Write Playwright tests';
+      app.addInput.dispatchEvent(new Event('input', { bubbles: true }));
+    });
+    await page.evaluate(() => {
+      document.querySelector('todo-app')!.shadowRoot!.querySelector<HTMLButtonElement>('.add-button')!.click();
+    });
+
+    // The new item appears with pending state and no checkmark
+    const newItem = page.locator('todo-item[title="Write Playwright tests"]');
+    await expect(newItem).toBeAttached();
+    await expect(newItem).toHaveAttribute('state', 'pending');
+
+    const hasCheck = await page.evaluate(() => {
+      const el = document.querySelector('todo-app')!.shadowRoot!
+        .querySelector('todo-item[title="Write Playwright tests"]');
+      return !!el?.shadowRoot?.querySelector('.check');
+    });
+    expect(hasCheck).toBe(false);
+  });
+
+  test('new dynamically-created item shows checkmark when toggled to done', async ({ page }) => {
+    await page.goto('/');
+    await page.waitForFunction(
+      () => document.querySelector('todo-app')?.addInput instanceof HTMLInputElement,
+    );
+
+    // Add a new item
+    await page.evaluate(() => {
+      const app = document.querySelector('todo-app')!;
+      (app as any).addInput.value = 'Dynamic toggle test';
+      (app as any).addInput.dispatchEvent(new Event('input', { bubbles: true }));
+      app.shadowRoot!.querySelector<HTMLButtonElement>('.add-button')!.click();
+    });
+    await expect(page.locator('todo-item[title="Dynamic toggle test"]')).toBeAttached();
+
+    // Toggle it to done via custom event (simulating click → $emit flow)
+    await page.evaluate(() => {
+      const app = document.querySelector('todo-app')!;
+      const item = app.shadowRoot!.querySelector('todo-item[title="Dynamic toggle test"]')!;
+      item.dispatchEvent(new CustomEvent('toggle-item', {
+        bubbles: true, composed: true,
+        detail: { id: item.getAttribute('id') },
+      }));
+    });
+
+    // Checkmark should appear
+    const hasCheck = await page.evaluate(() => {
+      const item = document.querySelector('todo-app')!.shadowRoot!
+        .querySelector('todo-item[title="Dynamic toggle test"]');
+      return !!item?.shadowRoot?.querySelector('.check');
+    });
+    expect(hasCheck).toBe(true);
+  });
+
+  test('add a todo via Enter key', async ({ page }) => {
+    await page.goto('/');
+    await page.waitForFunction(
+      () => document.querySelector('todo-app')?.addInput instanceof HTMLInputElement,
+    );
+
+    await page.evaluate(() => {
+      const app = document.querySelector('todo-app')!;
+      app.addInput.value = 'Press Enter todo';
+      app.addInput.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }));
+    });
+
+    await expect(page.locator('todo-item[title="Press Enter todo"]')).toBeAttached();
+  });
+
+  test('toggle a todo item done', async ({ page }) => {
+    await page.goto('/');
+    await page.waitForFunction(() => customElements.get('todo-item') !== undefined);
+
+    const writeDocItem = page.locator('todo-item[title="Write documentation"]');
+    await expect(writeDocItem).toHaveAttribute('state', 'pending');
+
+    const toggleBtn = writeDocItem.locator('button.toggle');
+    await toggleBtn.click();
+
+    await expect(writeDocItem).toHaveAttribute('state', 'done');
+  });
+
+  test('if-block checkmark appears when toggled to done', async ({ page }) => {
+    await page.goto('/');
+    await page.waitForFunction(() => customElements.get('todo-item') !== undefined);
+
+    // "Write documentation" starts pending — no checkmark
+    const hasCheckBefore = await page.evaluate(() => {
+      const item = document.querySelector('todo-app')!.shadowRoot!
+        .querySelector('todo-item[title="Write documentation"]');
+      return !!item?.shadowRoot?.querySelector('.check');
+    });
+    expect(hasCheckBefore).toBe(false);
+
+    // Toggle to done — checkmark should appear reactively
+    await page.evaluate(() => {
+      const item = document.querySelector('todo-app')!.shadowRoot!
+        .querySelector('todo-item[title="Write documentation"]');
+      item?.shadowRoot?.querySelector<HTMLButtonElement>('.toggle')?.click();
+    });
+
+    const hasCheckAfter = await page.evaluate(() => {
+      const item = document.querySelector('todo-app')!.shadowRoot!
+        .querySelector('todo-item[title="Write documentation"]');
+      return !!item?.shadowRoot?.querySelector('.check');
+    });
+    expect(hasCheckAfter).toBe(true);
+  });
+
+  test('if-block checkmark disappears when toggled back to pending', async ({ page }) => {
+    await page.goto('/');
+    await page.waitForFunction(() => customElements.get('todo-item') !== undefined);
+
+    // "Buy groceries" starts done — has checkmark
+    const hasCheckBefore = await page.evaluate(() => {
+      const item = document.querySelector('todo-app')!.shadowRoot!
+        .querySelector('todo-item[title="Buy groceries"]');
+      return !!item?.shadowRoot?.querySelector('.check');
+    });
+    expect(hasCheckBefore).toBe(true);
+
+    // Toggle to pending — checkmark should disappear reactively
+    await page.evaluate(() => {
+      const item = document.querySelector('todo-app')!.shadowRoot!
+        .querySelector('todo-item[title="Buy groceries"]');
+      item?.shadowRoot?.querySelector<HTMLButtonElement>('.toggle')?.click();
+    });
+
+    const hasCheckAfter = await page.evaluate(() => {
+      const item = document.querySelector('todo-app')!.shadowRoot!
+        .querySelector('todo-item[title="Buy groceries"]');
+      return !!item?.shadowRoot?.querySelector('.check');
+    });
+    expect(hasCheckAfter).toBe(false);
+  });
+
+  test('delete a todo item', async ({ page }) => {
+    await page.goto('/');
+    await page.waitForFunction(() => customElements.get('todo-item') !== undefined);
+
+    await expect(page.getByText('Ship feature')).toBeVisible();
+
+    const shipItem = page.locator('todo-item[title="Ship feature"]');
+    await shipItem.hover();
+    const deleteBtn = shipItem.locator('button.delete');
+    await deleteBtn.click();
+
+    await expect(page.getByText('Ship feature')).not.toBeVisible();
+  });
+
+  test('new dynamically-created item renders title text inside shadow DOM', async ({ page }) => {
+    await page.goto('/');
+    await page.waitForFunction(
+      () => document.querySelector('todo-app')?.addInput instanceof HTMLInputElement,
+    );
+
+    // Add a new item
+    await page.evaluate(() => {
+      const app = document.querySelector('todo-app')!;
+      (app as any).addInput.value = 'Visible title test';
+      (app as any).addInput.dispatchEvent(new Event('input', { bubbles: true }));
+      app.shadowRoot!.querySelector<HTMLButtonElement>('.add-button')!.click();
+    });
+
+    // Verify the title text is actually rendered inside the shadow DOM
+    // (regression test: previously blank until a toggle/re-render)
+    const titleText = await page.evaluate(() => {
+      const item = document.querySelector('todo-app')!.shadowRoot!
+        .querySelector('todo-item[title="Visible title test"]');
+      return item?.shadowRoot?.querySelector('.title')?.textContent;
+    });
+    expect(titleText).toBe('Visible title test');
+  });
+
+  test('deleting all items leaves empty list', async ({ page }) => {
+    await page.goto('/');
+    await page.waitForFunction(() => customElements.get('todo-item') !== undefined);
+
+    // Delete all 3 items one by one
+    for (const title of ['Buy groceries', 'Write documentation', 'Ship feature']) {
+      const item = page.locator(`todo-item[title="${title}"]`);
+      await item.hover();
+      await item.locator('button.delete').click();
+      await expect(item).not.toBeAttached();
+    }
+
+    // No todo-items should remain
+    const count = await page.evaluate(() => {
+      return document.querySelector('todo-app')!.shadowRoot!
+        .querySelectorAll('todo-item').length;
+    });
+    expect(count).toBe(0);
+
+    // Remaining count should be 0
+    await expect(page.getByText('0 items remaining')).toBeVisible();
+  });
+});
diff --git a/examples/app/todo-webui/tsconfig.json b/examples/app/todo-webui/tsconfig.json
new file mode 100644
index 00000000..117664c2
--- /dev/null
+++ b/examples/app/todo-webui/tsconfig.json
@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "target": "ESNext",
+    "strict": true,
+    "experimentalDecorators": true,
+    "useDefineForClassFields": false,
+    "skipLibCheck": true,
+    "sourceMap": true,
+    "incremental": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}

From 585b0842b10826fd9505de024ef72080fd3e554a Mon Sep 17 00:00:00 2001
From: Mohamed Mansour <hello@mohamedmansour.com>
Date: Fri, 27 Mar 2026 14:29:08 -0700
Subject: [PATCH 2/4] Publish pnpm

---
 pnpm-lock.yaml | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 3051e7c0..f664016b 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -259,6 +259,24 @@ importers:
         specifier: 'catalog:'
         version: 5.9.3
 
+  examples/app/todo-webui:
+    devDependencies:
+      '@microsoft/webui-framework':
+        specifier: workspace:*
+        version: link:../../../packages/webui-framework
+      '@playwright/test':
+        specifier: 'catalog:'
+        version: 1.58.2
+      esbuild:
+        specifier: 'catalog:'
+        version: 0.27.3
+      tslib:
+        specifier: 'catalog:'
+        version: 2.8.1
+      typescript:
+        specifier: 'catalog:'
+        version: 5.9.3
+
   examples/integration/electron:
     dependencies:
       '@microsoft/webui':

From 6f7dd50b24680055388702c5014d7c0ff70c101a Mon Sep 17 00:00:00 2001
From: Mohamed Mansour <hello@mohamedmansour.com>
Date: Fri, 27 Mar 2026 14:50:58 -0700
Subject: [PATCH 3/4] fix regression on template element

---
 packages/webui-framework/src/element.ts       | 10 +++--
 .../tests/fixtures/root-event/element.ts      | 39 +++++++++++++++++
 .../tests/fixtures/root-event/fixture.html    | 17 ++++++++
 .../fixtures/root-event/root-event.spec.ts    | 42 +++++++++++++++++++
 4 files changed, 104 insertions(+), 4 deletions(-)
 create mode 100644 packages/webui-framework/tests/fixtures/root-event/element.ts
 create mode 100644 packages/webui-framework/tests/fixtures/root-event/fixture.html
 create mode 100644 packages/webui-framework/tests/fixtures/root-event/root-event.spec.ts

diff --git a/packages/webui-framework/src/element.ts b/packages/webui-framework/src/element.ts
index 518908eb..fc3fd717 100644
--- a/packages/webui-framework/src/element.ts
+++ b/packages/webui-framework/src/element.ts
@@ -1394,10 +1394,10 @@ export class WebUIElement extends HTMLElement {
     const method = (this as unknown as Record<string, Function>)[handler];
     if (typeof method !== 'function') return;
 
-    // Root-level events (target === this) use a direct listener
-    if (target instanceof Element) {
-      target.setAttribute(`data-eh-${eventName}`, needsEvent ? `${handler}:e` : handler);
-    } else {
+    // Root-level events (target === this) use a direct listener on the host.
+    // The host element lives outside the shadow DOM so it cannot be reached
+    // by the delegated-listener parentElement walk inside the shadow root.
+    if (target === this || !(target instanceof Element)) {
       target.addEventListener(eventName, (e: Event) => {
         if (needsEvent) method.call(this, e);
         else method.call(this);
@@ -1405,6 +1405,8 @@ export class WebUIElement extends HTMLElement {
       return;
     }
 
+    target.setAttribute(`data-eh-${eventName}`, needsEvent ? `${handler}:e` : handler);
+
     // Install one delegated listener per event type on the shadow root
     if (!this.$delegatedEvents) {
       this.$delegatedEvents = new Map();
diff --git a/packages/webui-framework/tests/fixtures/root-event/element.ts b/packages/webui-framework/tests/fixtures/root-event/element.ts
new file mode 100644
index 00000000..1504248e
--- /dev/null
+++ b/packages/webui-framework/tests/fixtures/root-event/element.ts
@@ -0,0 +1,39 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { WebUIElement, observable } from '../../../src/index.js';
+import {
+  bindEvent,
+  bindText,
+  dynamic,
+  nodePath,
+  registerCompiledTemplate,
+  slot,
+} from '@microsoft/webui-test-support';
+
+registerCompiledTemplate('test-root-event', {
+  h: '<span class="total"></span><button class="action" data-action="ping">Ping</button><button class="other" data-action="pong">Pong</button>',
+  text: [
+    bindText(slot({ parent: nodePath(0), before: 0 }), dynamic('totalClicks')),
+  ],
+  rootEvents: [
+    bindEvent('click', 'onRootClick', true),
+  ],
+});
+
+export class TestRootEvent extends WebUIElement {
+  @observable totalClicks = 0;
+
+  lastAction = '';
+
+  onRootClick(e: MouseEvent): void {
+    this.totalClicks += 1;
+    const target = e.composedPath()[0] as HTMLElement;
+    const actionEl = target?.closest?.('[data-action]') as HTMLElement | null;
+    if (actionEl) {
+      this.lastAction = actionEl.dataset.action ?? '';
+    }
+  }
+}
+
+TestRootEvent.define('test-root-event');
diff --git a/packages/webui-framework/tests/fixtures/root-event/fixture.html b/packages/webui-framework/tests/fixtures/root-event/fixture.html
new file mode 100644
index 00000000..f5556ce9
--- /dev/null
+++ b/packages/webui-framework/tests/fixtures/root-event/fixture.html
@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Root Event Fixture</title>
+</head>
+<body>
+  <test-root-event>
+    <template shadowrootmode="open">
+      <span class="total"><!--w-b:start:0:totalClicks-->0<!--w-b:end:0:totalClicks--></span>
+      <button class="action" data-action="ping">Ping</button>
+      <button class="other" data-action="pong">Pong</button>
+    </template>
+  </test-root-event>
+  <script src="/dist/root-event/element.js"></script>
+</body>
+</html>
diff --git a/packages/webui-framework/tests/fixtures/root-event/root-event.spec.ts b/packages/webui-framework/tests/fixtures/root-event/root-event.spec.ts
new file mode 100644
index 00000000..e5eda5ad
--- /dev/null
+++ b/packages/webui-framework/tests/fixtures/root-event/root-event.spec.ts
@@ -0,0 +1,42 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { expect, test } from '@playwright/test';
+
+test.describe('root-event fixture', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/root-event/fixture.html');
+    await page.waitForSelector('test-root-event');
+  });
+
+  test('root @click fires when clicking a child button', async ({ page }) => {
+    await page.locator('test-root-event .action').click();
+    await expect(page.locator('test-root-event .total')).toHaveText('1');
+  });
+
+  test('root @click fires for different child elements', async ({ page }) => {
+    await page.locator('test-root-event .action').click();
+    await page.locator('test-root-event .other').click();
+    await expect(page.locator('test-root-event .total')).toHaveText('2');
+  });
+
+  test('root handler receives the event object with composedPath', async ({ page }) => {
+    await page.locator('test-root-event .action').click();
+
+    const action = await page.evaluate(() => {
+      const el = document.querySelector('test-root-event') as any;
+      return el?.lastAction;
+    });
+    expect(action).toBe('ping');
+  });
+
+  test('root handler distinguishes data-action from composedPath', async ({ page }) => {
+    await page.locator('test-root-event .other').click();
+
+    const action = await page.evaluate(() => {
+      const el = document.querySelector('test-root-event') as any;
+      return el?.lastAction;
+    });
+    expect(action).toBe('pong');
+  });
+});

From e8c0c19ed726db67f441d9100104663826958712 Mon Sep 17 00:00:00 2001
From: Mohamed Mansour <hello@mohamedmansour.com>
Date: Fri, 27 Mar 2026 14:54:06 -0700
Subject: [PATCH 4/4] fix comment

---
 packages/webui-framework/src/element.ts | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/packages/webui-framework/src/element.ts b/packages/webui-framework/src/element.ts
index fc3fd717..550fedec 100644
--- a/packages/webui-framework/src/element.ts
+++ b/packages/webui-framework/src/element.ts
@@ -1394,9 +1394,12 @@ export class WebUIElement extends HTMLElement {
     const method = (this as unknown as Record<string, Function>)[handler];
     if (typeof method !== 'function') return;
 
-    // Root-level events (target === this) use a direct listener on the host.
-    // The host element lives outside the shadow DOM so it cannot be reached
-    // by the delegated-listener parentElement walk inside the shadow root.
+    // Root-level events (target === this) and non-Element targets use a
+    // direct listener. The host element lives outside the shadow DOM so it
+    // cannot be reached by the delegated parentElement walk. When a component
+    // has both root and inner handlers for the same event type, both fire —
+    // the inner via delegation, the root via this direct listener — matching
+    // standard DOM bubbling semantics.
     if (target === this || !(target instanceof Element)) {
       target.addEventListener(eventName, (e: Event) => {
         if (needsEvent) method.call(this, e);