From 953192ad663f2ae9dafdcf9107dc03027cb398cc Mon Sep 17 00:00:00 2001
From: Mohamed Mansour <hello@mohamedmansour.com>
Date: Fri, 19 Jun 2026 10:50:26 -0700
Subject: [PATCH] fix: preserve plugin template root attributes

Preserve authored root <template> attributes for plugin/client component templates while keeping SSR output clean.

Append CSS module adopted stylesheet attributes centrally when missing and add todo-fast E2E coverage for delegated root events.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 DESIGN.md                                     |   6 +-
 crates/webui-parser/src/error.rs              |  17 -
 crates/webui-parser/src/lib.rs                | 383 +++++++++++++-----
 crates/webui-parser/src/plugin/mod.rs         |   9 +-
 crates/webui-parser/src/plugin/webui.rs       |   6 +-
 docs/ai.md                                    |   5 +
 docs/guide/cli/index.md                       |   2 +-
 docs/guide/concepts/plugins/index.md          |   3 +-
 examples/app/todo-fast/package.json           |   5 +-
 examples/app/todo-fast/playwright.config.ts   |  18 +
 .../app/todo-fast/tests/todo-fast.spec.ts     | 204 ++++++++++
 pnpm-lock.yaml                                |   3 +
 xtask/src/e2e.rs                              |  10 +
 13 files changed, 536 insertions(+), 135 deletions(-)
 create mode 100644 examples/app/todo-fast/playwright.config.ts
 create mode 100644 examples/app/todo-fast/tests/todo-fast.spec.ts

diff --git a/DESIGN.md b/DESIGN.md
index dd5495a9..c223eee5 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -966,7 +966,7 @@ pub enum CssStrategy {
 
 - **Link** (default): Emits `<link>` tags referencing external `.css` files only for components whose discovery/registration data included CSS. Used by the CLI for production builds where CSS files are served separately. Output filenames are configurable with a naming template (`[name]`, `[hash]`, `[ext]`), defaulting to `[name].[ext]`. `[hash]` is SHA-256 truncated to 8 hex chars. An optional public base prefix can be applied so protocol `css_href` values point to CDN URLs. The resolved href is used consistently for handler-emitted head links and parser/plugin-generated component template stylesheet links.
 - **Style**: Embeds the full CSS content in `<style>` tags inside the shadow DOM template. Used when all files are needed in-memory.
-- **Module**: Registers each component's CSS as a CSS Module via an [Import Map](https://html.spec.whatwg.org/multipage/webappapis.html#import-maps) entry whose value is a `data:text/css,...` URI. During SSR, the handler emits a `<script type="importmap">{"imports":{"component-name":"data:text/css,..."}}</script>` in each component's light DOM on first render (e.g., `<my-comp><script type="importmap">...</script><template ...>`) and adds `shadowrootadoptedstylesheets="component-name"` to each shadow root `<template>`. When the developer supplies their own `<template>` wrapper (e.g., to attach `@event` handlers), they MUST declare `shadowrootadoptedstylesheets="component-name"` on it — the parser returns `ParserError::MissingAdoptedStylesheets` at build time if the attribute is absent, so adoption can never silently fail. Multi-specifier values (`shadowrootadoptedstylesheets="component-name other-sheet"`) are honored verbatim. Components inside false `<if>` blocks or empty `<for>` loops that were not rendered during SSR get their importmap definitions emitted at `body_end`, so client-side activation can adopt them. CSS bytes are percent-encoded as needed to survive the `data:` URI parser (`%`, `#`, `"`, whitespace, and non-ASCII / control bytes); the importmap JSON object is built via `serde_json` so the specifier and URI value are correctly JSON-escaped. **Requires browser support for [Multiple Import Maps](https://github.com/WICG/import-maps/blob/main/proposals/multiple-import-maps.md) (Chrome 133+)** so each component's importmap can be emitted independently and merged into the document-level resolution table by the browser. When a CSP nonce is configured (via `RenderOptions::with_nonce` / `webui_handler_set_nonce`), the SSR-emitted `<script type="importmap">` tags include `nonce="VALUE"` (in `type`, `nonce` order) so strict `script-src 'nonce-...'` policies allow them, matching the existing nonce treatment of inline `<script>` tags. The browser registers the CSS module globally and shares a single `CSSStyleSheet` across all shadow roots that adopt it. No external CSS files are produced. During SPA partial navigation, definitions for newly needed components are sent in the `templateStyles` array as `<script type="importmap">{"imports":{...}}</script>` strings (without a `nonce` attribute - the router materializes each tag client-side and applies the per-request nonce when appending to `<head>` before installing component template closure arrays). WebUI Framework compiled metadata carries the adopted stylesheet specifier (`sa`) so client-created components can adopt the registered stylesheet on their shadow root.
+- **Module**: Registers each component's CSS as a CSS Module via an [Import Map](https://html.spec.whatwg.org/multipage/webappapis.html#import-maps) entry whose value is a `data:text/css,...` URI. During SSR, the handler emits a `<script type="importmap">{"imports":{"component-name":"data:text/css,..."}}</script>` in each component's light DOM on first render (e.g., `<my-comp><script type="importmap">...</script><template ...>`) and adds `shadowrootadoptedstylesheets="component-name"` to each shadow root `<template>`. When the developer supplies their own `<template>` wrapper (e.g., to attach `@event` handlers), the parser preserves the wrapper attributes and appends `shadowrootadoptedstylesheets="component-name"` when it is missing. Multi-specifier values already authored by the developer (`shadowrootadoptedstylesheets="component-name other-sheet"`) are honored verbatim. Components inside false `<if>` blocks or empty `<for>` loops that were not rendered during SSR get their importmap definitions emitted at `body_end`, so client-side activation can adopt them. CSS bytes are percent-encoded as needed to survive the `data:` URI parser (`%`, `#`, `"`, whitespace, and non-ASCII / control bytes); the importmap JSON object is built via `serde_json` so the specifier and URI value are correctly JSON-escaped. **Requires browser support for [Multiple Import Maps](https://github.com/WICG/import-maps/blob/main/proposals/multiple-import-maps.md) (Chrome 133+)** so each component's importmap can be emitted independently and merged into the document-level resolution table by the browser. When a CSP nonce is configured (via `RenderOptions::with_nonce` / `webui_handler_set_nonce`), the SSR-emitted `<script type="importmap">` tags include `nonce="VALUE"` (in `type`, `nonce` order) so strict `script-src 'nonce-...'` policies allow them, matching the existing nonce treatment of inline `<script>` tags. The browser registers the CSS module globally and shares a single `CSSStyleSheet` across all shadow roots that adopt it. No external CSS files are produced. During SPA partial navigation, definitions for newly needed components are sent in the `templateStyles` array as `<script type="importmap">{"imports":{...}}</script>` strings (without a `nonce` attribute - the router materializes each tag client-side and applies the per-request nonce when appending to `<head>` before installing component template closure arrays). WebUI Framework compiled metadata carries the adopted stylesheet specifier (`sa`) so client-created components can adopt the registered stylesheet on their shadow root.
 
 Set at construction time with
 `HtmlParser::with_options(ParserOptions::try_new(css, dom, css_file_name_template, css_public_base, legal_comments))`.
@@ -1021,7 +1021,7 @@ pub trait ParserPlugin {
 - **Fragment start**: `start_fragment` runs before each `HtmlParser::parse(...)` call so plugins can reset fragment-local counters
 - **Attribute loop**: `classify_attribute` decides whether framework-owned attrs are kept, skipped, or skipped-and-counted as bindings
 - **Element completion**: `finish_element` runs with the final binding count after all attrs are processed; returned bytes are emitted as a `Plugin` fragment
-- **Component registration**: `register_component_template` receives the final processed component template HTML after HTML/CSS comment stripping
+- **Component registration**: `register_component_template` receives the plugin-facing component template HTML after HTML/CSS comment stripping. Authored root `<template>` attributes are preserved for plugins; the SSR/internal parse view may strip runtime-only attributes so rendered HTML stays clean.
 - **Artifact extraction**: `into_artifacts` returns post-parse outputs such as client component templates without `Any` downcasts. It is **fallible**: template-authoring mistakes found while compiling component templates (an invalid `@event` handler or a non-braced `w-ref`) surface as `ParserError::Template` instead of panicking, so every host (CLI, Node, FFI, WASM) can handle them.
 
 **Selecting parser plugins**
@@ -1373,7 +1373,7 @@ The Rust compiler (`generate_compiled_template` in `webui-parser/src/plugin/webu
 | `w-ref="{name}"`                     | *(stays)*              | *(unchanged)*                     |
 | `<outlet />`                         | *(stays)*              | `<outlet></outlet>`               |
 
-**Authoring validation.** Build-time authoring mistakes are returned as a structured `ParserError::Template(Box<Diagnostic>)`, never panicked. This covers invalid `@event` handlers (e.g. `@click="e.preventDefault()"`, or a bare `@click="{closeMenu}"`), non-braced `w-ref` (`w-ref="name"` instead of `w-ref="{name}"`), core-parser mistakes — an invalid `<for each>` expression, a missing/invalid `<if condition>`, an unknown component tag, a recursive template reference — malformed CSS in a `<style>` block, and structural HTML well-formedness errors (unclosed/malformed tags, unterminated comments/declarations, unexpected closing tags, excessive nesting), so every build error renders identically. The `Diagnostic` is plain, actionable data — a **stable machine-readable `code`** (e.g. `invalid-for-each`; see `diagnostic::codes`), title, source location (rendered rustc-style as `--> owner:line:column` when the offending byte offset is known, otherwise `in component <c> · element <e>`), offending snippet, and a `help:` fix — and carries **no color**: `webui-cli` styles it with `console`, while Node/FFI/WASM forward the plain `Display` text through their native error channel. Where a fix is likely a typo, the `help:` offers a **"did you mean …?" suggestion** via an iterative Levenshtein match (`suggest::closest_match`): a misspelled directive attribute (`eahc` → `each`), or an unregistered custom-element tag that closely matches a registered component **in the same namespace** (`<mp-buton>` → `<mp-button>`; cross-namespace tags like `<md-button>` still pass through as genuine custom elements). This mirrors `ParserError::MissingAdoptedStylesheets`: authoring errors are returned so consumers can recover instead of aborting (`panic = "abort"` in release would otherwise kill the process).
+**Authoring validation.** Build-time authoring mistakes are returned as a structured `ParserError::Template(Box<Diagnostic>)`, never panicked. This covers invalid `@event` handlers (e.g. `@click="e.preventDefault()"`, or a bare `@click="{closeMenu}"`), non-braced `w-ref` (`w-ref="name"` instead of `w-ref="{name}"`), core-parser mistakes — an invalid `<for each>` expression, a missing/invalid `<if condition>`, an unknown component tag, a recursive template reference — malformed CSS in a `<style>` block, and structural HTML well-formedness errors (unclosed/malformed tags, unterminated comments/declarations, unexpected closing tags, excessive nesting), so every build error renders identically. The `Diagnostic` is plain, actionable data — a **stable machine-readable `code`** (e.g. `invalid-for-each`; see `diagnostic::codes`), title, source location (rendered rustc-style as `--> owner:line:column` when the offending byte offset is known, otherwise `in component <c> · element <e>`), offending snippet, and a `help:` fix — and carries **no color**: `webui-cli` styles it with `console`, while Node/FFI/WASM forward the plain `Display` text through their native error channel. Where a fix is likely a typo, the `help:` offers a **"did you mean …?" suggestion** via an iterative Levenshtein match (`suggest::closest_match`): a misspelled directive attribute (`eahc` → `each`), or an unregistered custom-element tag that closely matches a registered component **in the same namespace** (`<mp-buton>` → `<mp-button>`; cross-namespace tags like `<md-button>` still pass through as genuine custom elements).
 
 **Machine-readable diagnostics.** `webui-cli` accepts a global `--format <human|json>` flag. In `json` mode the colorized terminal output is suppressed and each error is emitted as a single JSON object on **stdout** (`{severity, code, message, file, line, column, snippet, help, chain}`), so editors, CI, and AI assistants consume diagnostics without scraping ANSI text. The process exit code follows BSD `sysexits.h` so callers can branch on the cause: `65` (`EX_DATAERR`) for a template/authoring error, `66` (`EX_NOINPUT`) for a missing app folder / state file / serve dir / entry, `69` (`EX_UNAVAILABLE`) for an occupied port, `74` (`EX_IOERR`) for other I/O failures, `2` for argument/usage errors (clap), and `1` otherwise.
 
diff --git a/crates/webui-parser/src/error.rs b/crates/webui-parser/src/error.rs
index 48a4eb49..2c2b6229 100644
--- a/crates/webui-parser/src/error.rs
+++ b/crates/webui-parser/src/error.rs
@@ -34,23 +34,6 @@ pub enum ParserError {
     #[error("Component error: {0}")]
     Component(String),
 
-    /// A component supplied its own `<template>` wrapper under
-    /// `CssStrategy::Module` but did not declare a
-    /// `shadowrootadoptedstylesheets` attribute. The framework cannot
-    /// silently inject the attribute without overriding developer intent
-    /// on the wrapper, so authoring help is surfaced at build time.
-    #[error(
-        "Component <{tag}> supplies its own <template> wrapper under --css=module but is \
-         missing the `shadowrootadoptedstylesheets` attribute, which is required to wire \
-         the component's CSS module into its shadow root. Add \
-         `shadowrootadoptedstylesheets=\"{tag}\"` to the <template> tag, or remove the \
-         <template> wrapper to let the framework manage it automatically."
-    )]
-    MissingAdoptedStylesheets {
-        /// The component tag name (e.g. `mp-app`).
-        tag: String,
-    },
-
     /// CSS error.
     #[error("CSS error: {0}")]
     Css(String),
diff --git a/crates/webui-parser/src/lib.rs b/crates/webui-parser/src/lib.rs
index fe4f7e04..01f6c306 100644
--- a/crates/webui-parser/src/lib.rs
+++ b/crates/webui-parser/src/lib.rs
@@ -376,6 +376,17 @@ pub struct HtmlParser {
     current_fragment_id: String,
 }
 
+struct BuiltComponentTemplate {
+    ssr: String,
+    artifact: Option<String>,
+}
+
+impl BuiltComponentTemplate {
+    fn artifact(&self) -> &str {
+        self.artifact.as_deref().unwrap_or(&self.ssr)
+    }
+}
+
 impl HtmlParser {
     /// Create a new directive parser with default parser options.
     #[must_use]
@@ -1284,17 +1295,18 @@ impl HtmlParser {
                     .help(self.unknown_component_help(element.name()))
                 })?
                 .clone();
-            let processed = self.build_component_template(
+            let built = self.build_component_templates(
                 element.name(),
                 &html_content,
                 css_content.as_deref(),
+                self.plugin.is_some(),
             )?;
 
             if let Some(ref mut p) = self.plugin {
-                p.register_component_template(element.name(), &component_data, &processed)?;
+                p.register_component_template(element.name(), &component_data, built.artifact())?;
             }
 
-            self.parse(element.name(), &processed)?;
+            self.parse(element.name(), &built.ssr)?;
         }
 
         fragments.push(WebUIFragment::component(element.name().to_string()));
@@ -2017,18 +2029,19 @@ impl HtmlParser {
         self.token_store
             .extend(component_data.css_tokens.iter().cloned());
 
-        let processed = self.build_component_template(
+        let built = self.build_component_templates(
             component,
             &component_data.html_content,
             component_data.css_content.as_deref(),
+            self.plugin.is_some(),
         )?;
 
         if let Some(ref mut p) = self.plugin {
-            p.register_component_template(component, &component_data, &processed)?;
+            p.register_component_template(component, &component_data, built.artifact())?;
         }
 
         let saved_buffer = std::mem::take(&mut self.raw_buffer);
-        self.parse(component, &processed)?;
+        self.parse(component, &built.ssr)?;
         self.raw_buffer = saved_buffer;
 
         Ok(())
@@ -2038,6 +2051,7 @@ impl HtmlParser {
     const SKIPPED_ATTRIBUTES: &[&str] = &["class", "style", "role"];
     /// Skipped attribute prefixes for components.
     const SKIPPED_ATTRIBUTE_PREFIXES: &[&str] = &["data-", "aria-"];
+    const ADOPTED_STYLESHEETS_ATTR: &str = "shadowrootadoptedstylesheets";
 
     fn is_skipped_attribute(name: &str) -> bool {
         Self::SKIPPED_ATTRIBUTES.contains(&name)
@@ -2052,18 +2066,16 @@ impl HtmlParser {
         matches!(name, "innerHTML" | "outerHTML" | "srcdoc" | "content") || name.starts_with("on")
     }
 
-    /// Process component template HTML: wrap in shadow DOM template if needed,
-    /// inject CSS snippet (link or inline style), and strip runtime-only attributes.
-    /// When `adopted_specifier` is `Some`, it is stored in template metadata
-    /// for the client runtime to handle document-level CSS adoption.
-    fn build_component_template(
+    /// Build both SSR-facing and plugin-facing component template views.
+    fn build_component_templates(
         &mut self,
         tag_name: &str,
         html: &str,
         css_content: Option<&str>,
-    ) -> Result<String> {
+        artifact_needed: bool,
+    ) -> Result<BuiltComponentTemplate> {
         let adopted_specifier = match self.options.css_strategy {
-            CssStrategy::Module if css_content.is_some() => Some(tag_name.to_string()),
+            CssStrategy::Module if css_content.is_some() => Some(tag_name),
             _ => None,
         };
         let css_injection = match self.options.css_strategy {
@@ -2092,11 +2104,20 @@ impl HtmlParser {
             CssStrategy::Module => None,
         };
 
-        self.process_component_template(
-            html,
-            css_injection.as_deref(),
-            adopted_specifier.as_deref(),
-        )
+        let artifact_differs = artifact_needed && Self::template_has_stripped_runtime_attrs(html);
+        let ssr =
+            self.process_component_template(html, css_injection.as_deref(), adopted_specifier)?;
+        let artifact = if artifact_differs {
+            Some(self.process_component_artifact_template(
+                html,
+                css_injection.as_deref(),
+                adopted_specifier,
+            )?)
+        } else {
+            None
+        };
+
+        Ok(BuiltComponentTemplate { ssr, artifact })
     }
 
     /// Process component template HTML for SSR output.
@@ -2105,16 +2126,13 @@ impl HtmlParser {
     ///
     /// - **Dev supplied `<template ...>`:** preserved verbatim — including
     ///   `shadowrootmode`, `shadowrootadoptedstylesheets`, signal fragments,
-    ///   and any other custom attributes. The only modification is stripping
-    ///   runtime-only attributes (`@event`, `:bind`, `?cond`) from the
-    ///   opening tag, since those are protocol metadata and never appear
-    ///   in HTML output. If a CSS snippet is supplied, it is injected
+    ///   and any other custom attributes. SSR strips runtime-only attributes
+    ///   (`@event`, `:bind`, `?cond`) from the opening tag, since those are
+    ///   protocol metadata and never appear in HTML output. Plugin-facing
+    ///   artifacts preserve them. If a CSS snippet is supplied, it is injected
     ///   immediately inside the opening tag (before the dev's children) so
-    ///   styles still apply. For `CssStrategy::Module` the dev MUST author
-    ///   a `shadowrootadoptedstylesheets="<tag>"` attribute on the wrapper
-    ///   — failure to do so returns
-    ///   [`ParserError::MissingAdoptedStylesheets`] at build time so the
-    ///   broken CSS adoption never reaches a browser.
+    ///   styles still apply. For `CssStrategy::Module`, the parser appends
+    ///   `shadowrootadoptedstylesheets="<tag>"` when it is missing.
     ///
     /// - **Dev omitted `<template>`:**
     ///   - `DomStrategy::Shadow` wraps the content in a framework-controlled
@@ -2131,47 +2149,37 @@ impl HtmlParser {
         html: &str,
         css_snippet: Option<&str>,
         adopted_specifier: Option<&str>,
+    ) -> Result<String> {
+        self.process_component_template_with_mode(html, css_snippet, adopted_specifier, false)
+    }
+
+    fn process_component_artifact_template(
+        &mut self,
+        html: &str,
+        css_snippet: Option<&str>,
+        adopted_specifier: Option<&str>,
+    ) -> Result<String> {
+        self.process_component_template_with_mode(html, css_snippet, adopted_specifier, true)
+    }
+
+    fn process_component_template_with_mode(
+        &mut self,
+        html: &str,
+        css_snippet: Option<&str>,
+        adopted_specifier: Option<&str>,
+        preserve_runtime_attrs: bool,
     ) -> Result<String> {
         let trimmed = html.trim();
         let snippet = css_snippet.unwrap_or_default();
 
         let processed = if trimmed.starts_with("<template") {
-            let stripped = self.strip_runtime_attrs_from_template(trimmed);
-
-            // For `CssStrategy::Module`, the dev must declare
-            // `shadowrootadoptedstylesheets` themselves on their wrapper.
-            // Validate at build time so adoption can never silently fail.
-            if let Some(tag) = adopted_specifier {
-                let opening = match html::find_tag_close(&stripped) {
-                    Some(end) => &stripped[..=end],
-                    None => stripped.as_str(),
-                };
-                if !opening.contains("shadowrootadoptedstylesheets=") {
-                    return Err(ParserError::MissingAdoptedStylesheets {
-                        tag: tag.to_string(),
-                    });
-                }
-            }
-
-            if snippet.is_empty() {
-                stripped
+            let base = if preserve_runtime_attrs {
+                trimmed.to_string()
             } else {
-                // Splice the CSS snippet right after the opening `<template …>` tag.
-                // The quote-aware scanner avoids matching a `>` inside an attribute value
-                // (e.g., `data-x="a>b"`).
-                match html::find_tag_close(&stripped) {
-                    Some(open_end) => {
-                        let mut result = String::with_capacity(stripped.len() + snippet.len());
-                        result.push_str(&stripped[..=open_end]);
-                        result.push_str(snippet);
-                        result.push_str(&stripped[open_end + 1..]);
-                        result
-                    }
-                    // Malformed opening tag (no closing `>`): emit as-is rather
-                    // than panic. The downstream parser surfaces the error.
-                    None => stripped,
-                }
-            }
+                self.strip_runtime_attrs_from_template(trimmed)
+            };
+            let with_adopted = Self::append_adopted_attr_if_missing(base, adopted_specifier);
+            Self::inject_css_snippet_into_template(with_adopted, snippet)
         } else {
             match self.options.dom_strategy {
                 DomStrategy::Shadow => {
@@ -2179,15 +2187,13 @@ impl HtmlParser {
                     let adopted_extra = if adopted.is_empty() {
                         0
                     } else {
-                        33 + adopted.len()
+                        Self::adopted_attr_len(adopted)
                     };
                     let mut result =
                         String::with_capacity(45 + adopted_extra + snippet.len() + trimmed.len());
                     result.push_str("<template shadowrootmode=\"open\"");
                     if !adopted.is_empty() {
-                        result.push_str(" shadowrootadoptedstylesheets=\"");
-                        result.push_str(adopted);
-                        result.push('"');
+                        Self::push_adopted_attr(&mut result, adopted);
                     }
                     result.push('>');
                     result.push_str(snippet);
@@ -2211,6 +2217,68 @@ impl HtmlParser {
         self.strip_template_comments(processed)
     }
 
+    fn inject_css_snippet_into_template(html: String, snippet: &str) -> String {
+        if snippet.is_empty() {
+            return html;
+        }
+
+        match html::find_tag_close(&html) {
+            Some(open_end) => {
+                let mut result = String::with_capacity(html.len() + snippet.len());
+                result.push_str(&html[..=open_end]);
+                result.push_str(snippet);
+                result.push_str(&html[open_end + 1..]);
+                result
+            }
+            // Malformed opening tag (no closing `>`): emit as-is rather than
+            // panic. The downstream parser surfaces the error.
+            None => html,
+        }
+    }
+
+    fn append_adopted_attr_if_missing(html: String, adopted_specifier: Option<&str>) -> String {
+        let Some(adopted) = adopted_specifier else {
+            return html;
+        };
+        let Some(tag) = html::parse_tag(&html) else {
+            return html;
+        };
+        if tag.name != "template" || tag.closing || tag.has_attr(Self::ADOPTED_STYLESHEETS_ATTR) {
+            return html;
+        }
+
+        let mut result = String::with_capacity(html.len() + Self::adopted_attr_len(adopted));
+        result.push_str(&html[..tag.close]);
+        Self::push_adopted_attr(&mut result, adopted);
+        result.push_str(&html[tag.close..]);
+        result
+    }
+
+    fn push_adopted_attr(out: &mut String, adopted: &str) {
+        out.push(' ');
+        out.push_str(Self::ADOPTED_STYLESHEETS_ATTR);
+        out.push_str("=\"");
+        out.push_str(adopted);
+        out.push('"');
+    }
+
+    fn adopted_attr_len(adopted: &str) -> usize {
+        4 + Self::ADOPTED_STYLESHEETS_ATTR.len() + adopted.len()
+    }
+
+    fn template_has_stripped_runtime_attrs(html: &str) -> bool {
+        let trimmed = html.trim_start();
+        let Some(tag) = html::parse_tag(trimmed) else {
+            return false;
+        };
+        if tag.name != "template" || tag.closing {
+            return false;
+        }
+        tag.attrs().any(|attr| {
+            attr.name.starts_with('@') || attr.name.starts_with(':') || attr.name.starts_with('?')
+        })
+    }
+
     fn strip_template_comments(&mut self, html: String) -> Result<String> {
         let mut ranges = Vec::new();
         let mut style_ranges = Vec::new();
@@ -4451,56 +4519,26 @@ mod tests {
     // `shadowrootadoptedstylesheets` attribute is the only wire between
     // the framework-emitted importmap/module-script and the shadow root.
     // When the developer supplies their own `<template>` wrapper (e.g.
-    // to attach `@event` handlers, as commerce's `mp-app` does), the
-    // framework cannot silently inject the attribute without overriding
-    // developer intent. Instead we surface a parse-time error so adoption
-    // can never silently fail. See the search-page visual regression that
-    // surfaced this bug for the symptom of getting it wrong.
+    // to attach `@event` handlers), the framework preserves that wrapper
+    // and appends the CSS-module adoption attribute when it is missing.
 
     #[test]
-    fn dev_template_module_strategy_errors_when_attr_missing() {
+    fn dev_template_module_strategy_appends_adopted_attr_when_missing() {
         let mut parser = HtmlParser::with_options(DomStrategy::Shadow);
-        let err = parser
+        let processed = parser
             .process_component_template(
                 r#"<template shadowrootmode="open"><div>hi</div></template>"#,
                 None,
                 Some("my-comp"),
             )
-            .expect_err("expected ParserError::MissingAdoptedStylesheets");
-        match err {
-            ParserError::MissingAdoptedStylesheets { tag } => {
-                assert_eq!(tag, "my-comp");
-            }
-            other => panic!("expected MissingAdoptedStylesheets, got: {other:?}"),
-        }
-    }
-
-    #[test]
-    fn dev_template_module_strategy_error_message_is_actionable() {
-        let mut parser = HtmlParser::with_options(DomStrategy::Shadow);
-        let err = parser
-            .process_component_template(
-                r#"<template shadowrootmode="open"><div>hi</div></template>"#,
-                None,
-                Some("mp-app"),
-            )
-            .expect_err("expected ParserError::MissingAdoptedStylesheets");
-        let msg = err.to_string();
-        // Actionable per the framework's error guidance: tell the dev
-        // which component, exactly what attribute to add, and how to opt
-        // out (drop the wrapper).
-        assert!(msg.contains("<mp-app>"), "missing tag name: {msg}");
-        assert!(
-            msg.contains(r#"shadowrootadoptedstylesheets="mp-app""#),
-            "missing copy-pasteable fix: {msg}"
-        );
+            .expect("process failed");
         assert!(
-            msg.contains("--css=module"),
-            "missing strategy context: {msg}"
+            processed.contains(r#"shadowrootmode="open""#),
+            "dev-authored shadowrootmode must be preserved, got: {processed}"
         );
         assert!(
-            msg.contains("remove the <template> wrapper"),
-            "missing opt-out hint: {msg}"
+            processed.contains(r#"shadowrootadoptedstylesheets="my-comp""#),
+            "module CSS should append adopted stylesheets, got: {processed}"
         );
     }
 
@@ -4525,6 +4563,48 @@ mod tests {
         );
     }
 
+    #[test]
+    fn dev_template_module_strategy_appends_adopted_attr_and_preserves_root_attrs() {
+        for dom_strategy in [DomStrategy::Shadow, DomStrategy::Light] {
+            let mut parser = HtmlParser::with_options((CssStrategy::Module, dom_strategy));
+            let built = match parser.build_component_templates(
+                "my-comp",
+                r#"<template shadowrootmode="open" @click="{onClick()}">Hello</template>"#,
+                Some(":host { color: red; }"),
+                true,
+            ) {
+                Ok(built) => built,
+                Err(err) => panic!(
+                    "dev-authored <template> should be accepted under {dom_strategy:?} with module CSS, got: {err}"
+                ),
+            };
+            let artifact = built.artifact();
+
+            assert!(
+                artifact.contains(r#"shadowrootmode="open""#),
+                "dev-authored shadowrootmode must be preserved under {dom_strategy:?}, got: {artifact}"
+            );
+            assert!(
+                artifact.contains(r#"@click="{onClick()}""#),
+                "dev-authored root event must be preserved under {dom_strategy:?}, got: {artifact}"
+            );
+            assert!(
+                artifact.contains(r#"shadowrootadoptedstylesheets="my-comp""#),
+                "module CSS should append adopted stylesheets under {dom_strategy:?}, got: {artifact}"
+            );
+            assert_eq!(
+                artifact.matches("shadowrootadoptedstylesheets").count(),
+                1,
+                "module CSS should append adopted stylesheets once under {dom_strategy:?}, got: {artifact}"
+            );
+            assert!(
+                !built.ssr.contains("@click"),
+                "SSR template must still strip runtime attrs, got: {}",
+                built.ssr
+            );
+        }
+    }
+
     #[test]
     fn dev_template_module_strategy_ok_with_multi_specifier_attr() {
         // Multi-specifier scenarios: the dev wants to adopt extra sheets
@@ -4783,6 +4863,99 @@ mod tests {
         }
     }
 
+    struct TemplateCapturePlugin {
+        template: Option<String>,
+    }
+
+    impl TemplateCapturePlugin {
+        fn new() -> Self {
+            Self { template: None }
+        }
+    }
+
+    impl crate::plugin::ParserPlugin for TemplateCapturePlugin {
+        fn register_component_template(
+            &mut self,
+            _tag_name: &str,
+            _component: &Component,
+            processed_template: &str,
+        ) -> Result<()> {
+            self.template = Some(processed_template.to_string());
+            Ok(())
+        }
+
+        fn classify_attribute(&mut self, attr_name: &str) -> AttributeAction {
+            if attr_name.starts_with('@') || attr_name == "f-ref" {
+                AttributeAction::SkipAndCountBinding
+            } else {
+                AttributeAction::Keep
+            }
+        }
+
+        fn finish_element(&mut self, _binding_attribute_count: u32) -> Option<Vec<u8>> {
+            None
+        }
+
+        fn into_artifacts(self: Box<Self>) -> Result<ParserPluginArtifacts> {
+            match self.template {
+                Some(template) => Ok(ParserPluginArtifacts::ComponentTemplates(vec![
+                    crate::plugin::ComponentTemplateArtifact::template(
+                        "todo-app".to_string(),
+                        template,
+                    ),
+                ])),
+                None => Ok(ParserPluginArtifacts::None),
+            }
+        }
+    }
+
+    #[test]
+    fn parser_passes_user_template_root_attrs_to_plugin_without_css_modules() {
+        let mut parser = HtmlParser::with_plugin_options(
+            Box::new(TemplateCapturePlugin::new()),
+            CssStrategy::Link,
+        );
+        parser
+            .component_registry_mut()
+            .register_component(
+                "todo-app",
+                r#"<template shadowrootmode="open" @toggle-item="{onToggleItem($e)}" @delete-item="{onDeleteItem($e)}" f-ref="{root}"><div>items</div></template>"#,
+                Some(":host { display: block; }"),
+            )
+            .expect("register todo-app");
+
+        parser
+            .parse("index.html", "<todo-app></todo-app>")
+            .expect("parse failed");
+
+        let artifacts = parser.take_plugin_artifacts().expect("artifacts");
+        let ParserPluginArtifacts::ComponentTemplates(templates) = artifacts else {
+            panic!("expected captured component template");
+        };
+        let template = &templates[0].template;
+
+        assert!(
+            template.contains(r#"shadowrootmode="open""#),
+            "parser must pass dev-authored root template attrs to plugins, got: {template}"
+        );
+        assert!(
+            template.contains(r#"@toggle-item="{onToggleItem($e)}""#),
+            "parser must pass dev-authored root event attrs to plugins, got: {template}"
+        );
+        assert!(
+            template.contains(r#"@delete-item="{onDeleteItem($e)}""#),
+            "parser must pass dev-authored root event attrs to plugins, got: {template}"
+        );
+        assert!(
+            template.contains(r#"f-ref="{root}""#),
+            "parser must pass dev-authored root FAST attrs to plugins, got: {template}"
+        );
+        assert!(
+            !template.contains("shadowrootadoptedstylesheets"),
+            "link CSS must not add CSS module adoption attrs, got: {template}"
+        );
+    }
+
     #[test]
     fn test_component_static_attrs_not_counted_as_bindings() {
         let mut parser = HtmlParser::with_plugin(Box::new(BindingCountPlugin::new()));
diff --git a/crates/webui-parser/src/plugin/mod.rs b/crates/webui-parser/src/plugin/mod.rs
index 6bcbaeb5..4f2fd5ef 100644
--- a/crates/webui-parser/src/plugin/mod.rs
+++ b/crates/webui-parser/src/plugin/mod.rs
@@ -4,7 +4,7 @@
 //! Parser plugin trait and built-in plugin implementations.
 //!
 //! The plugin system is framework-aware but phase-local — parser plugins
-//! classify framework-owned attributes, capture processed component templates,
+//! classify framework-owned attributes, capture plugin-facing component templates,
 //! and emit per-element hydration metadata for the handler.
 
 pub mod fast;
@@ -76,7 +76,7 @@ impl ComponentTemplateArtifact {
 ///
 /// Plugins receive callbacks at key points during HTML parsing:
 /// - **Fragment lifecycle**: `start_fragment` before a fragment parse begins
-/// - **Component registration**: `register_component_template` when a component template is finalized
+/// - **Component registration**: `register_component_template` when a plugin-facing component template is finalized
 /// - **Attribute classification**: `classify_attribute` for framework-specific attrs
 /// - **Element completion**: `finish_element` after attributes are processed
 ///
@@ -91,8 +91,9 @@ pub trait ParserPlugin {
     /// Called when parser output options change.
     fn configure(&mut self, _options: &ParserOptions) {}
 
-    /// Called when a component template has been fully processed for the active
-    /// CSS strategy and wrapped for shadow DOM rendering.
+    /// Called with the plugin-facing component template for the active CSS/DOM
+    /// strategies. Authored root `<template>` attributes are preserved here;
+    /// the SSR/internal parse view may strip runtime-only attributes.
     fn register_component_template(
         &mut self,
         tag_name: &str,
diff --git a/crates/webui-parser/src/plugin/webui.rs b/crates/webui-parser/src/plugin/webui.rs
index 59bfb11c..b112c3c5 100644
--- a/crates/webui-parser/src/plugin/webui.rs
+++ b/crates/webui-parser/src/plugin/webui.rs
@@ -55,8 +55,8 @@
 //!    counts them per-element, and keeps them out of the parsed protocol.
 //! 2. **`finish_element`** — encodes the accumulated event count
 //!    plus attribute binding count into 12 bytes.
-//! 3. **`register_component_template`** — caches the component's final template
-//!    HTML for later compilation (deduplicates by tag name).
+//! 3. **`register_component_template`** — caches the component's plugin-facing
+//!    template HTML for later compilation (deduplicates by tag name).
 //! 4. **`take_component_templates`** — called after parsing is complete;
 //!    compiles each tracked component into JSON metadata plus condition closures.
 
@@ -70,7 +70,7 @@ use std::cell::Cell;
 use std::fmt::Write;
 use webui_protocol::{condition_expr, ConditionExpr, WebUIElementData};
 
-/// A component whose final template HTML has been captured for compilation.
+/// A component whose plugin-facing template HTML has been captured for compilation.
 /// Repeated tracking for the same tag updates the stored template so the plugin
 /// can prefer processed HTML over raw component source.
 struct TrackedComponent {
diff --git a/docs/ai.md b/docs/ai.md
index 197d19b8..4d0b1da2 100644
--- a/docs/ai.md
+++ b/docs/ai.md
@@ -526,6 +526,11 @@ webui build ./src --out ./dist --plugin=webui
 | `--legal-comments <MODE>` | `inline` | `inline` preserves legal CSS comments, `none` strips all comments |
 | `--format <FORMAT>` | `human` | `human` (colorized) or `json` (machine-readable diagnostics on stdout) |
 
+With `--css module`, WebUI appends
+`shadowrootadoptedstylesheets="<component-name>"` to component `<template>`
+wrappers when needed. If you author the wrapper yourself for root events, keep
+your attributes there; WebUI preserves them for client/plugin templates.
+
 For CDN/browser caching in `link` mode, prefer:
 
 ```bash
diff --git a/docs/guide/cli/index.md b/docs/guide/cli/index.md
index a78df7e4..2067d746 100644
--- a/docs/guide/cli/index.md
+++ b/docs/guide/cli/index.md
@@ -59,7 +59,7 @@ Path inputs for `APP`, `--state`, and `--servedir` support absolute paths, relat
 |------|----------|
 | `link` | Emits `<link>` tags referencing external `.css` files. CSS files are copied to the output folder. |
 | `style` | Embeds CSS content directly in `<style>` tags inside shadow DOM templates. No separate CSS files are written. |
-| `module` | Emits `<script type="importmap">{"imports":{"component":"data:text/css,..."}}</script>` tags that register each component's CSS under a data URI, and adds `shadowrootadoptedstylesheets` to `<template>` tags. The browser shares a single `CSSStyleSheet` across all shadow roots that adopt it. No separate CSS files are written. Based on the [Import Maps](https://html.spec.whatwg.org/multipage/webappapis.html#import-maps) and [CSS Module Scripts](https://github.com/whatwg/html/issues/9572) proposals. **Note:** if a component supplies its own `<template>` wrapper (e.g. to attach `@event` handlers), the wrapper must include `shadowrootadoptedstylesheets="component-name"` — the build fails fast otherwise so adoption can never silently break. |
+| `module` | Emits `<script type="importmap">{"imports":{"component":"data:text/css,..."}}</script>` tags that register each component's CSS under a data URI, and adds `shadowrootadoptedstylesheets` to `<template>` tags. The browser shares a single `CSSStyleSheet` across all shadow roots that adopt it. No separate CSS files are written. Based on the [Import Maps](https://html.spec.whatwg.org/multipage/webappapis.html#import-maps) and [CSS Module Scripts](https://github.com/whatwg/html/issues/9572) proposals. If a component supplies its own `<template>` wrapper (e.g. to attach `@event` handlers), WebUI preserves the wrapper attributes and appends `shadowrootadoptedstylesheets="component-name"` when it is missing. |
 
 For long-lived CDN/browser caching in `link` mode, include `[hash]` in the CSS
 filename template. `[hash]` is the component CSS file's SHA-256 content hash
diff --git a/docs/guide/concepts/plugins/index.md b/docs/guide/concepts/plugins/index.md
index 0e8b4834..663c13ce 100644
--- a/docs/guide/concepts/plugins/index.md
+++ b/docs/guide/concepts/plugins/index.md
@@ -95,7 +95,8 @@ pub trait ParserPlugin {
     /// Called before parsing begins for a fragment.
     fn start_fragment(&mut self, fragment_id: &str) {}
 
-    /// Called when a component template has been fully processed.
+    /// Called with the plugin-facing component template. Authored root
+    /// `<template>` attributes are preserved for plugins.
     fn register_component_template(
         &mut self,
         tag_name: &str,
diff --git a/examples/app/todo-fast/package.json b/examples/app/todo-fast/package.json
index 34f60577..2964248a 100644
--- a/examples/app/todo-fast/package.json
+++ b/examples/app/todo-fast/package.json
@@ -9,11 +9,14 @@
     "build:client": "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 --theme=@microsoft/webui-examples-theme --plugin=fast-v3 --servedir ./dist --port 3001 --watch",
-    "start": "cargo xtask dev todo-fast"
+    "start": "cargo xtask dev todo-fast",
+    "test": "playwright test",
+    "test:update-snapshots": "playwright test --update-snapshots"
   },
   "devDependencies": {
     "@microsoft/webui-examples-theme": "workspace:*",
     "@microsoft/fast-element": "catalog:",
+    "@playwright/test": "catalog:",
     "esbuild": "catalog:",
     "tslib": "catalog:",
     "typescript": "catalog:"
diff --git a/examples/app/todo-fast/playwright.config.ts b/examples/app/todo-fast/playwright.config.ts
new file mode 100644
index 00000000..f869404e
--- /dev/null
+++ b/examples/app/todo-fast/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:3001',
+    screenshot: 'only-on-failure',
+  },
+  projects: [
+    { name: 'chromium', use: { browserName: 'chromium' } },
+  ],
+});
diff --git a/examples/app/todo-fast/tests/todo-fast.spec.ts b/examples/app/todo-fast/tests/todo-fast.spec.ts
new file mode 100644
index 00000000..d04dadba
--- /dev/null
+++ b/examples/app/todo-fast/tests/todo-fast.spec.ts
@@ -0,0 +1,204 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { expect, type Page, test } from '@playwright/test';
+
+async function gotoAndWaitForFastHydration(page: Page): Promise<void> {
+  await page.goto('/');
+  await page.waitForFunction(() => {
+    const app = document.querySelector('todo-app');
+    return Boolean(
+      customElements.get('todo-app')
+      && customElements.get('todo-item')
+      && app?.shadowRoot?.querySelector('input.add-input'),
+    );
+  });
+}
+
+async function readInitialHtml(page: Page): Promise<string> {
+  const response = await page.goto('/');
+  expect(response).not.toBeNull();
+  return response?.text() ?? '';
+}
+
+function fastTemplate(html: string, name: string): string {
+  const start = html.indexOf(`<f-template name="${name}">`);
+  expect(start, `expected ${name} f-template`).toBeGreaterThanOrEqual(0);
+  const end = html.indexOf('</f-template>', start);
+  expect(end, `expected ${name} closing f-template`).toBeGreaterThan(start);
+  return html.slice(start, end);
+}
+
+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 state attribute', async ({ page }) => {
+    await page.goto('/');
+    const doneItem = page.locator('todo-item[state="done"]');
+    await expect(doneItem).toBeVisible();
+    await expect(doneItem).toContainText('Buy groceries');
+  });
+
+  test('emits FAST templates with root runtime attrs without CSS modules', async ({ page }) => {
+    const html = await readInitialHtml(page);
+    const appTemplate = fastTemplate(html, 'todo-app');
+    const itemTemplate = fastTemplate(html, 'todo-item');
+
+    expect(html).not.toContain('shadowrootadoptedstylesheets');
+    expect(appTemplate).toContain('@toggle-item="{onToggleItem($e)}"');
+    expect(appTemplate).toContain('@delete-item="{onDeleteItem($e)}"');
+    expect(itemTemplate).toContain('@click="{onClick($e)}"');
+  });
+
+  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);
+    const real = errors.filter(e => !e.includes('favicon'));
+    expect(real).toEqual([]);
+  });
+
+  test('fires FAST hydration completion measure', async ({ page }) => {
+    await gotoAndWaitForFastHydration(page);
+    await page.waitForFunction(() =>
+      performance.getEntriesByName('todo-hydration-completed', 'measure').length > 0
+    );
+
+    const totalDuration = await page.evaluate(() => {
+      const total = performance.getEntriesByName('todo-hydration-completed', 'measure');
+      return total[0]?.duration ?? -1;
+    });
+
+    expect(totalDuration).toBeGreaterThanOrEqual(0);
+  });
+});
+
+test.describe('interactivity', () => {
+  test('add a new todo item via Add button', async ({ page }) => {
+    await gotoAndWaitForFastHydration(page);
+
+    await page.locator('input.add-input').fill('Write Playwright tests');
+    await page.locator('button.add-button').click();
+
+    const newItem = page.locator('todo-item[title="Write Playwright tests"]');
+    await expect(newItem).toBeAttached();
+    await expect(newItem).toHaveAttribute('state', 'pending');
+    await expect(newItem.locator('.check')).not.toBeAttached();
+  });
+
+  test('add a todo via Enter key', async ({ page }) => {
+    await gotoAndWaitForFastHydration(page);
+
+    await page.locator('input.add-input').fill('Press Enter todo');
+    await page.locator('input.add-input').press('Enter');
+
+    await expect(page.locator('todo-item[title="Press Enter todo"]')).toBeAttached();
+  });
+
+  test('toggle a todo item done', async ({ page }) => {
+    await gotoAndWaitForFastHydration(page);
+
+    const item = page.locator('todo-item[title="Write documentation"]');
+    await expect(item).toHaveAttribute('state', 'pending');
+
+    await item.locator('button.toggle').click();
+
+    await expect(item).toHaveAttribute('state', 'done');
+  });
+
+  test('if-block checkmark appears when toggled to done', async ({ page }) => {
+    await gotoAndWaitForFastHydration(page);
+
+    const item = page.locator('todo-item[title="Write documentation"]');
+    await expect(item.locator('.check')).not.toBeAttached();
+
+    await item.locator('button.toggle').click();
+
+    await expect(item.locator('.check')).toBeAttached();
+  });
+
+  test('if-block checkmark disappears when toggled back to pending', async ({ page }) => {
+    await gotoAndWaitForFastHydration(page);
+
+    const item = page.locator('todo-item[title="Buy groceries"]');
+    await expect(item.locator('.check')).toBeAttached();
+
+    await item.locator('button.toggle').click();
+
+    await expect(item.locator('.check')).not.toBeAttached();
+  });
+
+  test('delete a todo item', async ({ page }) => {
+    await gotoAndWaitForFastHydration(page);
+
+    const shipItem = page.locator('todo-item[title="Ship feature"]');
+    await expect(shipItem).toBeVisible();
+    await shipItem.hover();
+    await shipItem.locator('button.delete').click();
+    await expect(shipItem).not.toBeAttached();
+  });
+
+  test('new item renders title text', async ({ page }) => {
+    await gotoAndWaitForFastHydration(page);
+
+    await page.locator('input.add-input').fill('Visible title test');
+    await page.locator('button.add-button').click();
+
+    const titleText = await page.locator(
+      'todo-item[title="Visible title test"] .title',
+    ).textContent();
+    expect(titleText).toBe('Visible title test');
+  });
+
+  test('deleting all items leaves empty list', async ({ page }) => {
+    await gotoAndWaitForFastHydration(page);
+
+    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();
+    }
+
+    await expect(page.locator('todo-item')).toHaveCount(0);
+    await expect(page.getByText('0 items remaining')).toBeVisible();
+  });
+
+  test('remaining count updates reactively', async ({ page }) => {
+    await gotoAndWaitForFastHydration(page);
+
+    await expect(page.getByText('2 items remaining')).toBeVisible();
+
+    await page.locator('input.add-input').fill('Count test');
+    await page.locator('button.add-button').click();
+
+    await expect(page.getByText('3 items remaining')).toBeVisible();
+  });
+
+  test('dynamically-created item shows checkmark when toggled', async ({ page }) => {
+    await gotoAndWaitForFastHydration(page);
+
+    await page.locator('input.add-input').fill('Dynamic toggle');
+    await page.locator('button.add-button').click();
+
+    const item = page.locator('todo-item[title="Dynamic toggle"]');
+    await expect(item).toBeAttached();
+
+    await item.locator('button.toggle').click();
+    await expect(item.locator('.check')).toBeAttached();
+
+    await item.locator('button.toggle').click();
+    await expect(item.locator('.check')).not.toBeAttached();
+  });
+});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 016aa556..7656bba4 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -256,6 +256,9 @@ importers:
       '@microsoft/webui-examples-theme':
         specifier: workspace:*
         version: link:../../../packages/webui-examples-theme
+      '@playwright/test':
+        specifier: 'catalog:'
+        version: 1.58.2
       esbuild:
         specifier: 'catalog:'
         version: 0.28.1
diff --git a/xtask/src/e2e.rs b/xtask/src/e2e.rs
index 67a1fc64..e535f625 100644
--- a/xtask/src/e2e.rs
+++ b/xtask/src/e2e.rs
@@ -102,6 +102,16 @@ const SUITES: &[PlaywrightSuite] = &[
         test_script: "test",
         update_snapshots_script: "test:update-snapshots",
     },
+    PlaywrightSuite {
+        name: "todo-fast",
+        dir: "examples/app/todo-fast",
+        ports: &[3001],
+        scripts: &["start:server"],
+        build_client: true,
+        pre_script: None,
+        test_script: "test",
+        update_snapshots_script: "test:update-snapshots",
+    },
     PlaywrightSuite {
         name: "todo-webui",
         dir: "examples/app/todo-webui",