From 84bb5ae4c019e1b2b732df612fd87bb5844a78d6 Mon Sep 17 00:00:00 2001
From: Mohamed Mansour <mmansour@microsoft.com>
Date: Fri, 21 Aug 2026 23:50:29 -0700
Subject: [PATCH 1/4] fix: preserve siblings around raw HTML updates

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 0807f5af-f9d9-45ad-b7d2-907084c53ea0
---
 DESIGN.md                                     |  48 ++-
 crates/webui-handler/src/lib.rs               |  17 +-
 crates/webui-handler/src/plugin/mod.rs        |  54 ++-
 crates/webui-handler/src/plugin/webui.rs      | 103 ++++-
 crates/webui-parser/src/lib.rs                |  69 +++-
 crates/webui-parser/src/plugin/webui.rs       |  48 ++-
 crates/webui-protocol/proto/webui.proto       |   3 +
 crates/webui-protocol/src/gen_webui.rs        |   4 +
 crates/webui-protocol/src/lib.rs              |  33 +-
 crates/webui-test-utils/src/lib.rs            |  28 +-
 docs/guide/concepts/plugins/index.md          |  19 +-
 packages/webui-framework/README.md            |  32 +-
 .../src/element/markers.test.ts               |  29 ++
 .../webui-framework/src/element/markers.ts    |  63 ++-
 packages/webui-framework/src/element/types.ts |  17 +-
 .../src/hydration-mismatch.test.ts            |   6 +-
 .../webui-framework/src/template-element.ts   | 288 ++++++++++---
 .../fixtures/raw-html-conditional/element.ts  |  45 ++
 .../raw-html-conditional.spec.ts              | 386 +++++++++++++++++-
 .../raw-html-conditional/src/index.html       |   1 +
 .../test-raw-html-keyed-repeat.html           |   7 +
 .../src/test-raw-html/test-raw-html.html      |  23 +-
 .../fixtures/raw-html-conditional/state.json  |  28 +-
 .../tests/fixtures/raw-html-light/element.ts  |  12 +
 .../raw-html-light/raw-html-light.spec.ts     | 119 ++++++
 .../fixtures/raw-html-light/src/index.html    |  10 +
 .../test-raw-html-light.html                  |  15 +
 .../tests/fixtures/raw-html-light/state.json  |   5 +
 .../fixtures/raw-html-light/webui.config.json |   3 +
 29 files changed, 1389 insertions(+), 126 deletions(-)
 create mode 100644 packages/webui-framework/tests/fixtures/raw-html-conditional/src/test-raw-html-keyed-repeat/test-raw-html-keyed-repeat.html
 create mode 100644 packages/webui-framework/tests/fixtures/raw-html-light/element.ts
 create mode 100644 packages/webui-framework/tests/fixtures/raw-html-light/raw-html-light.spec.ts
 create mode 100644 packages/webui-framework/tests/fixtures/raw-html-light/src/index.html
 create mode 100644 packages/webui-framework/tests/fixtures/raw-html-light/src/test-raw-html-light/test-raw-html-light.html
 create mode 100644 packages/webui-framework/tests/fixtures/raw-html-light/state.json
 create mode 100644 packages/webui-framework/tests/fixtures/raw-html-light/webui.config.json

diff --git a/DESIGN.md b/DESIGN.md
index 86bbd7e61..4d8fe04c1 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -165,6 +165,9 @@ pub struct WebUIFragmentSignal {
     pub value: String,
     /// Determines if the value should be rendered as raw content.
     pub raw: bool,
+    /// Whether the signal is inside an HTML raw-text context such as `<style>`.
+    /// Raw-text signals never own replaceable sibling ranges.
+    pub raw_text_context: bool,
 }
 ```
 #### Conditional Fragment
@@ -1050,8 +1053,30 @@ completion work such as rendered-component template emission stays in handler co
 pub trait HandlerPlugin: Send {
     fn push_scope(&mut self);
     fn pop_scope(&mut self);
-    fn on_binding_start(&mut self, name: &str, writer: &mut dyn ResponseWriter) -> Result<()>;
-    fn on_binding_end(&mut self, name: &str, writer: &mut dyn ResponseWriter) -> Result<()>;
+    fn on_binding_start(
+        &mut self,
+        name: &str,
+        writer: &mut dyn ResponseWriter,
+    ) -> Result<()>;
+    fn on_binding_end(
+        &mut self,
+        name: &str,
+        writer: &mut dyn ResponseWriter,
+    ) -> Result<()>;
+    fn on_raw_binding_start(
+        &mut self,
+        name: &str,
+        writer: &mut dyn ResponseWriter,
+    ) -> Result<()> {
+        self.on_binding_start(name, writer)
+    }
+    fn on_raw_binding_end(
+        &mut self,
+        name: &str,
+        writer: &mut dyn ResponseWriter,
+    ) -> Result<()> {
+        self.on_binding_end(name, writer)
+    }
     fn on_repeat_item_start(&mut self, index: usize, writer: &mut dyn ResponseWriter) -> Result<()>;
     fn on_repeat_item_end(&mut self, index: usize, writer: &mut dyn ResponseWriter) -> Result<()>;
     fn on_element_data(&mut self, data: &[u8], writer: &mut dyn ResponseWriter) -> Result<()>;
@@ -1080,7 +1105,10 @@ retain thread-affine state such as `Rc`; use owned state, `Arc`, or another
 sendable handle instead.
 
 **Hook invocation points:**
-- **Signal**: `on_binding_start` before, `on_binding_end` after (same scope)
+- **Signal**: escaped and raw-text signals call `on_binding_start` before and
+  `on_binding_end` after; authored raw HTML range signals call
+  `on_raw_binding_start` / `on_raw_binding_end`. The raw hooks default to the
+  escaped hooks, preserving existing plugin behavior and source compatibility.
 - **For loop**: `on_binding_start/end` around entire loop; `on_repeat_item_start/end` + `push_scope/pop_scope` per item
 - **If condition**: `on_binding_start/end` around condition; `push_scope/pop_scope` if condition is true
 - **Component**: `push_scope/pop_scope` around component body
@@ -1757,7 +1785,7 @@ update hot paths still call the function directly.
 | Field | Type                              | Description                                        |
 |-------|-----------------------------------|----------------------------------------------------|
 | `h`   | `string`                          | Marker-free static HTML for client-created DOM, including baked-in `<link>` / `<style>` nodes for link/style CSS strategies |
-| `tx`  | `[slot, parts][]`                 | Client text runs inserted at precompiled slots     |
+| `tx`  | `[slot, parts, raw?][]`           | Client text runs inserted at precompiled slots; `raw = 1` identifies unescaped HTML ranges |
 | `a`   | `CompiledAttrMeta[]`              | Attribute binding metadata                         |
 | `ag`  | `[elementIndex, start, count][]`  | Attribute-target groups for `a[]`                  |
 | `c`   | `[ConditionRef, blockIndex, slot][]` | Conditional blocks                              |
@@ -4045,7 +4073,7 @@ strict missing-fragment failure.
 
 **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.
 
-`tx[]` stores text runs as `[slot, parts]`, where `parts` reuse the compact attribute-part encoding (`string` for static text, `[path]` for dynamic text). Client-created DOM inserts one runtime `Text` node per run instead of scanning compiled marker comments.
+`tx[]` stores text runs as `[slot, parts, raw?]`, where `parts` reuse the compact attribute-part encoding (`string` for static text, `[path]` for dynamic text). Escaped text omits `raw` and client-created DOM inserts one runtime `Text` node per run. Triple-brace bindings set `raw` to `1` and own the sibling-safe DOM range between paired `<!--wN-->` and `<!--/wN-->` markers.
 
 **Element addressing.** Every locator - the `slot` in `tx` / `c` / `r`, the target in `ag`, and the event target in `eg` - names an element by its **pre-order index** within its own compiled section: `0` is the section root and elements are numbered `1..N` in the order a depth-first walk of `h` meets them. The root template and each `<if>` / `<for>` block number independently, matching the `b[]` split. A `slot` is `[parentIndex, beforeIndex, order?]`, where `beforeIndex` remains a child offset within that parent. Both runtime paths rebuild the same numbering in one walk - client-created DOM by walking the cloned `h`, SSR by walking the server output while skipping structural block ranges - so a binding resolves by array index rather than by descending a chain of child offsets.
 
@@ -4079,8 +4107,10 @@ WebUI SSR marker formats are:
 | Repeat item | `<!--wi-->` | Marks each iteration boundary inside a repeat |
 | Conditional start | `<!--wc-->` | Opens an `<if>` block |
 | Conditional end | `<!--/wc-->` | Closes the `<if>` block |
+| Raw HTML start | `<!--wN-->` | Opens raw range `N` owned by a triple-brace binding |
+| Raw HTML end | `<!--/wN-->` | Closes the same raw range `N` |
 
-The WebUI handler plugin emits only these five comment markers. Text bindings, attribute bindings, and event handlers are resolved from compiled pre-order element indices at hydration time - no DOM attribute markers are needed. The handler only emits markers in active child scopes; the root page scope remains marker-free. During hydration the framework keeps `<!--wr-->` and `<!--wc-->` as runtime anchors and removes `<!--/wr-->`, `<!--/wc-->`, and `<!--wi-->` markers.
+The WebUI handler plugin emits these seven comment marker roles. Escaped text bindings, attribute bindings, and event handlers are resolved from compiled pre-order element indices at hydration time - no DOM attribute markers are needed. Raw HTML is the exception because its rendered value can contain any number of top-level nodes and therefore needs explicit ownership boundaries. Raw markers carry a decimal pair identifier so adjacent bindings cannot claim each other's ranges. Exact `<!--wN-->` / `<!--/wN-->` comments are framework-reserved and trusted raw HTML must not emit a marker matching its surrounding range. During hydration the framework keeps `<!--wr-->`, `<!--wc-->`, `<!--wN-->`, and `<!--/wN-->` as runtime anchors and removes `<!--/wr-->`, `<!--/wc-->`, and `<!--wi-->` markers.
 
 WebUI Framework hydration assumes the SSR DOM, hydration markers, and compiled metadata were generated by the same trusted WebUI compiler/handler version. Hand-authored or partially modified marker streams are unsupported; missing structural closing markers are invalid input, not a recoverable runtime condition.
 
@@ -4088,7 +4118,11 @@ WebUI Framework hydration assumes the SSR DOM, hydration markers, and compiled m
 
 `@microsoft/webui-framework` consumes the metadata object above plus the SSR markers emitted by `WebUIHydrationPlugin`. This follows an Islands Architecture approach: the server delivers fully-rendered HTML, authored Web Components hydrate on startup or explicitly opt into visibility-driven activation, and compiler-owned scriptless hosts remain dormant until browser code actually writes state.
 
-- SSR hydration performs one pre-order walk per component that pairs each template element with the server-rendered element it hydrates and collects `<!--wc-->` / `<!--wr-->` markers in document order. Because the compiler emits `c` / `r` in source order and the server renders in source order, the two line up by index, so each block's anchor is unambiguous. Bindings then resolve by lookup rather than by rescanning, keeping hydration linear in subtree size instead of proportional to bindings times sibling count. The walk skips whole `<!--wc-->` / `<!--wr-->` ranges — that content belongs to the block's own metadata — and stops at child components, which contribute no children to the parent's `h`. `<!--wi-->` item markers and SSR-only closing markers are removed afterwards.
+- SSR hydration performs one pre-order walk per component that pairs each template element with the server-rendered element it hydrates and collects structural markers and raw HTML ranges in document order. Because compiler metadata and server output share source order, each block and raw range is unambiguous. Bindings then resolve by lookup rather than by rescanning, keeping hydration linear in subtree size instead of proportional to bindings times sibling count. The walk skips complete conditional, repeat, and raw HTML ranges - their rendered elements are not static children owned by the enclosing section - and stops at child components, which contribute no children to the parent's `h`. `<!--wi-->` item markers and structural closing markers are removed afterwards; raw HTML boundaries remain for targeted updates.
+- Reactive triple-brace updates delete only the nodes between the binding's retained
+  `<!--wN-->` / `<!--/wN-->` anchors, parse the new trusted HTML in the parent
+  element's context, and insert the resulting fragment before the end anchor.
+  Static, conditional, and repeated siblings outside that range are preserved.
 - Authored browser entries execute only after every SSR instance they may
   upgrade has complete markup. Parser-inserted, non-async ES module scripts and
   classic `defer` scripts satisfy this automatically; blocking classic scripts
diff --git a/crates/webui-handler/src/lib.rs b/crates/webui-handler/src/lib.rs
index f046b82d8..217299ab9 100644
--- a/crates/webui-handler/src/lib.rs
+++ b/crates/webui-handler/src/lib.rs
@@ -1639,7 +1639,7 @@ impl WebUIHandler {
         if signal.raw {
             self.process_raw_signal(signal, context)
         } else {
-            self.process_state_signal(signal, context)
+            self.process_state_signal(signal, false, context)
         }
     }
 
@@ -1650,7 +1650,7 @@ impl WebUIHandler {
         context: &mut WebUIProcessContext<'data, '_, '_>,
     ) -> Result<()> {
         let Some(structural_value) = structural_signal_value(signal) else {
-            return self.process_state_signal(signal, context);
+            return self.process_state_signal(signal, !signal.raw_text_context, context);
         };
 
         if context.streaming.is_some()
@@ -1953,10 +1953,15 @@ impl WebUIHandler {
     fn process_state_signal(
         &self,
         signal: &webui_protocol::WebUIFragmentSignal,
+        owns_html_range: bool,
         context: &mut WebUIProcessContext,
     ) -> Result<()> {
         if let Some(p) = &mut context.plugin {
-            p.on_binding_start(&signal.value, context.writer)?;
+            if owns_html_range {
+                p.on_raw_binding_start(&signal.value, context.writer)?;
+            } else {
+                p.on_binding_start(&signal.value, context.writer)?;
+            }
         }
 
         if let Some(value) = self.resolve_value(&signal.value, context) {
@@ -1964,7 +1969,11 @@ impl WebUIHandler {
         }
 
         if let Some(p) = &mut context.plugin {
-            p.on_binding_end(&signal.value, context.writer)?;
+            if owns_html_range {
+                p.on_raw_binding_end(&signal.value, context.writer)?;
+            } else {
+                p.on_binding_end(&signal.value, context.writer)?;
+            }
         }
         Ok(())
     }
diff --git a/crates/webui-handler/src/plugin/mod.rs b/crates/webui-handler/src/plugin/mod.rs
index 73548178b..4d474bb77 100644
--- a/crates/webui-handler/src/plugin/mod.rs
+++ b/crates/webui-handler/src/plugin/mod.rs
@@ -41,7 +41,7 @@ pub struct BootstrapExtensionContext<'a> {
 ///
 /// Plugins receive callbacks at key points in the rendering lifecycle:
 /// - **Scope management**: `push_scope` / `pop_scope` for component and loop boundaries
-/// - **Binding lifecycle**: `on_binding_start` / `on_binding_end` around signals
+/// - **Binding lifecycle**: binding hooks around escaped and raw signals
 /// - **For-loop lifecycle**: `on_for_start` / `on_for_end` around for-loop blocks
 /// - **If-condition lifecycle**: `on_if_start` / `on_if_end` around if-condition blocks
 /// - **Repeat items**: `on_repeat_item_start` / `on_repeat_item_end` per for-loop item
@@ -73,12 +73,28 @@ pub trait HandlerPlugin: Send {
     /// Exit the current scope, restoring the parent scope state.
     fn pop_scope(&mut self);
 
-    /// Called before rendering a signal binding.
+    /// Called before rendering an escaped signal binding.
     fn on_binding_start(&mut self, name: &str, writer: &mut dyn ResponseWriter) -> Result<()>;
 
-    /// Called after rendering a signal binding.
+    /// Called after rendering an escaped signal binding.
     fn on_binding_end(&mut self, name: &str, writer: &mut dyn ResponseWriter) -> Result<()>;
 
+    /// Called before rendering a signal that owns a raw HTML range.
+    ///
+    /// Defaults to the ordinary binding hook so existing plugins remain source
+    /// compatible and keep their established marker behavior.
+    fn on_raw_binding_start(&mut self, name: &str, writer: &mut dyn ResponseWriter) -> Result<()> {
+        self.on_binding_start(name, writer)
+    }
+
+    /// Called after rendering a signal that owns a raw HTML range.
+    ///
+    /// Defaults to the ordinary binding hook so existing plugins remain source
+    /// compatible and keep their established marker behavior.
+    fn on_raw_binding_end(&mut self, name: &str, writer: &mut dyn ResponseWriter) -> Result<()> {
+        self.on_binding_end(name, writer)
+    }
+
     /// Called before rendering a for-loop block.
     /// Defaults to [`on_binding_start`](HandlerPlugin::on_binding_start).
     fn on_for_start(&mut self, name: &str, writer: &mut dyn ResponseWriter) -> Result<()> {
@@ -264,6 +280,19 @@ mod tests {
     #[derive(Default)]
     struct SendOnlyPlugin {
         scope_depth: Cell<usize>,
+        binding_calls: Cell<usize>,
+    }
+
+    struct TestWriter;
+
+    impl ResponseWriter for TestWriter {
+        fn write(&mut self, _content: &str) -> Result<()> {
+            Ok(())
+        }
+
+        fn end(&mut self) -> Result<()> {
+            Ok(())
+        }
     }
 
     impl HandlerPlugin for SendOnlyPlugin {
@@ -282,10 +311,14 @@ mod tests {
             _name: &str,
             _writer: &mut dyn ResponseWriter,
         ) -> Result<()> {
+            self.binding_calls
+                .set(self.binding_calls.get().saturating_add(1));
             Ok(())
         }
 
         fn on_binding_end(&mut self, _name: &str, _writer: &mut dyn ResponseWriter) -> Result<()> {
+            self.binding_calls
+                .set(self.binding_calls.get().saturating_add(1));
             Ok(())
         }
 
@@ -322,4 +355,19 @@ mod tests {
         assert_send::<dyn HandlerPlugin>();
         assert_plugin::<SendOnlyPlugin>();
     }
+
+    #[test]
+    fn raw_hooks_default_to_existing_binding_hooks() {
+        let mut plugin = SendOnlyPlugin::default();
+        let mut writer = TestWriter;
+
+        plugin
+            .on_raw_binding_start("trusted_html", &mut writer)
+            .unwrap();
+        plugin
+            .on_raw_binding_end("trusted_html", &mut writer)
+            .unwrap();
+
+        assert_eq!(plugin.binding_calls.get(), 2);
+    }
 }
diff --git a/crates/webui-handler/src/plugin/webui.rs b/crates/webui-handler/src/plugin/webui.rs
index 0afa26c68..b742b628a 100644
--- a/crates/webui-handler/src/plugin/webui.rs
+++ b/crates/webui-handler/src/plugin/webui.rs
@@ -4,8 +4,9 @@
 //! WebUI handler plugin that emits lightweight hydration markers.
 //!
 //! Emits comment markers around for-loop blocks (`<!--wr-->` / `<!--/wr-->`),
-//! before each repeat item (`<!--wi-->`), and around if-condition blocks
-//! (`<!--wc-->` / `<!--/wc-->`). These markers enable zero-DOM-mutation
+//! before each repeat item (`<!--wi-->`), around if-condition blocks
+//! (`<!--wc-->` / `<!--/wc-->`), and around raw HTML bindings
+//! (`<!--wN-->` / `<!--/wN-->`). These markers enable zero-DOM-mutation
 //! in-place hydration on the client: the framework reuses the SSR comment
 //! nodes as runtime anchors instead of creating temporary wrappers.
 
@@ -19,22 +20,65 @@ const REPEAT_END: &str = "<!--/wr-->";
 const REPEAT_ITEM: &str = "<!--wi-->";
 const COND_START: &str = "<!--wc-->";
 const COND_END: &str = "<!--/wc-->";
+const RAW_START_PREFIX: &str = "<!--w";
+const RAW_END_PREFIX: &str = "<!--/w";
+const MARKER_SUFFIX: &str = "-->";
 
 /// WebUI handler plugin that emits hydration markers.
 ///
 /// Emits lightweight HTML comment markers around structural boundaries
 /// (for-loops and if-conditions) so the client can hydrate in-place
 /// without reparenting DOM nodes.
-pub struct WebUIHydrationPlugin;
+pub struct WebUIHydrationPlugin {
+    raw_index: usize,
+    raw_marker: String,
+}
 
 impl WebUIHydrationPlugin {
     /// Create a new WebUI handler plugin.
     #[must_use]
     pub fn new() -> Self {
-        Self
+        Self {
+            raw_index: 0,
+            raw_marker: String::new(),
+        }
     }
 }
 
+fn write_raw_marker(
+    marker: &mut String,
+    writer: &mut dyn ResponseWriter,
+    index: usize,
+    closing: bool,
+) -> Result<()> {
+    let mut reversed_digits = [0_u8; 20];
+    let mut digit_count = 0;
+    let mut remaining = index;
+    loop {
+        reversed_digits[digit_count] = b"0123456789"[remaining % 10];
+        digit_count += 1;
+        remaining /= 10;
+        if remaining == 0 {
+            break;
+        }
+    }
+
+    marker.clear();
+    if marker.capacity() == 0 {
+        marker.reserve(32);
+    }
+    marker.push_str(if closing {
+        RAW_END_PREFIX
+    } else {
+        RAW_START_PREFIX
+    });
+    for index in (0..digit_count).rev() {
+        marker.push(char::from(reversed_digits[index]));
+    }
+    marker.push_str(MARKER_SUFFIX);
+    writer.write(marker)
+}
+
 impl Default for WebUIHydrationPlugin {
     fn default() -> Self {
         Self::new()
@@ -54,6 +98,16 @@ impl HandlerPlugin for WebUIHydrationPlugin {
         Ok(())
     }
 
+    fn on_raw_binding_start(&mut self, _name: &str, writer: &mut dyn ResponseWriter) -> Result<()> {
+        write_raw_marker(&mut self.raw_marker, writer, self.raw_index, false)
+    }
+
+    fn on_raw_binding_end(&mut self, _name: &str, writer: &mut dyn ResponseWriter) -> Result<()> {
+        write_raw_marker(&mut self.raw_marker, writer, self.raw_index, true)?;
+        self.raw_index += 1;
+        Ok(())
+    }
+
     fn on_for_start(&mut self, _name: &str, writer: &mut dyn ResponseWriter) -> Result<()> {
         writer.write(REPEAT_START)
     }
@@ -295,7 +349,7 @@ mod tests {
 
     #[test]
     fn test_default_creates_instance() {
-        let _plugin = WebUIHydrationPlugin;
+        let _plugin = WebUIHydrationPlugin::default();
     }
 
     #[test]
@@ -310,6 +364,16 @@ mod tests {
         );
     }
 
+    #[test]
+    fn test_raw_signal_binding_emits_range_markers() {
+        let mut plugin = WebUIHydrationPlugin::new();
+        let mut writer = TestWriter::new();
+        plugin.on_raw_binding_start("html", &mut writer).unwrap();
+        writer.write("<b>trusted</b>").unwrap();
+        plugin.on_raw_binding_end("html", &mut writer).unwrap();
+        assert_eq!(writer.output, "<!--w0--><b>trusted</b><!--/w0-->");
+    }
+
     #[test]
     fn test_for_loop_emits_repeat_markers() {
         let mut plugin = WebUIHydrationPlugin::new();
@@ -622,6 +686,7 @@ mod tests {
                 fragments: vec![
                     WebUIFragment::for_loop("item", "items", "for-body"),
                     WebUIFragment::if_cond(ConditionExpr::identifier("show"), "if-body"),
+                    WebUIFragment::signal("html", true),
                 ],
             },
         );
@@ -638,7 +703,7 @@ mod tests {
             },
         );
         let protocol = WebUIProtocol::new(fragments);
-        let state = test_json!({"items": ["a", "b"], "show": true});
+        let state = test_json!({"items": ["a", "b"], "show": true, "html": "<i>raw</i>"});
         let output = render_with_webui_plugin(&protocol, &state);
 
         // For-loop markers
@@ -684,5 +749,31 @@ mod tests {
             output.contains("<span>yes</span>"),
             "Expected if-condition body, got: {output}"
         );
+        assert!(
+            output.contains("<!--w0--><i>raw</i><!--/w0-->"),
+            "Expected bounded raw HTML markers, got: {output}"
+        );
+    }
+
+    #[test]
+    fn test_handler_keeps_raw_text_signal_marker_free() {
+        let mut fragments = HashMap::new();
+        fragments.insert(
+            "index.html".to_string(),
+            FragmentList {
+                fragments: vec![
+                    WebUIFragment::raw("<style>:root{"),
+                    WebUIFragment::raw_text_signal("tokens", true),
+                    WebUIFragment::raw("}</style>"),
+                ],
+            },
+        );
+        let protocol = WebUIProtocol::new(fragments);
+        let state = test_json!({"tokens": "--accent:red"});
+        let output = render_with_webui_plugin(&protocol, &state);
+
+        assert!(output.contains("<style>:root{--accent:red}</style>"));
+        assert!(!output.contains("<!--w0-->"));
+        assert!(!output.contains("<!--/w0-->"));
     }
 }
diff --git a/crates/webui-parser/src/lib.rs b/crates/webui-parser/src/lib.rs
index 40fa6ecff..96469d93e 100644
--- a/crates/webui-parser/src/lib.rs
+++ b/crates/webui-parser/src/lib.rs
@@ -160,6 +160,14 @@ fn boundary_parent_scope(name: &str) -> Option<&'static str> {
     }
 }
 
+#[inline]
+fn is_html_text_only_scope(scope: Option<&str>) -> bool {
+    matches!(
+        scope,
+        Some(value) if value != "component host content" && value != "<template> inert content"
+    )
+}
+
 /// Strategy for how component CSS is delivered in rendered output.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
 #[cfg_attr(feature = "cli", derive(clap::ValueEnum))]
@@ -2403,6 +2411,15 @@ impl HtmlParser {
                 if Self::should_emit_text_content(&raw.value) {
                     self.add_raw_fragment(&raw.value);
                 }
+            } else if let Some(Fragment::Signal(signal)) = fragment.fragment.as_ref() {
+                if signal.raw && is_html_text_only_scope(self.boundary_parent_scope) {
+                    self.add_fragment(
+                        WebUIFragment::raw_text_signal(signal.value.as_str(), true),
+                        fragments,
+                    );
+                } else {
+                    self.add_fragment(fragment, fragments);
+                }
             } else {
                 self.add_fragment(fragment, fragments);
             }
@@ -2441,7 +2458,7 @@ impl HtmlParser {
 
     fn css_signal_comment_fragment(&self, comment: &str) -> Option<WebUIFragment> {
         let signal = comment_policy::parse_css_signal_comment(comment)?;
-        Some(WebUIFragment::signal(signal.path, signal.raw))
+        Some(WebUIFragment::raw_text_signal(signal.path, signal.raw))
     }
 
     /// Check if an attribute value is a pure handlebars expression (e.g., "{{name}}" or
@@ -5611,6 +5628,45 @@ mod tests {
         );
     }
 
+    #[test]
+    fn raw_bindings_in_html_text_contexts_do_not_own_html_ranges() {
+        for element in ["title", "textarea", "script", "xmp"] {
+            let html = format!("<{element}>{{{{{{value}}}}}}</{element}>");
+            let (fragments, _) = parse_and_get_fragments(&html);
+            let signal = fragments
+                .iter()
+                .find_map(|fragment| match fragment.fragment.as_ref() {
+                    Some(Fragment::Signal(signal)) if signal.value == "value" => Some(signal),
+                    _ => None,
+                });
+            let signal = signal
+                .unwrap_or_else(|| panic!("expected raw signal inside <{element}>: {fragments:?}"));
+            assert!(
+                signal.raw,
+                "<{element}> should preserve raw brace semantics"
+            );
+            assert!(
+                signal.raw_text_context,
+                "<{element}> should suppress HTML ownership markers"
+            );
+        }
+    }
+
+    #[test]
+    fn raw_bindings_in_template_content_own_html_ranges() {
+        let (fragments, _) = parse_and_get_fragments("<template>{{{value}}}</template>");
+        let signal = fragments
+            .iter()
+            .find_map(|fragment| match fragment.fragment.as_ref() {
+                Some(Fragment::Signal(signal)) if signal.value == "value" => Some(signal),
+                _ => None,
+            });
+        let signal =
+            signal.unwrap_or_else(|| panic!("expected raw signal inside template: {fragments:?}"));
+        assert!(signal.raw);
+        assert!(!signal.raw_text_context);
+    }
+
     #[test]
     fn test_css_strategy_external_emits_link_tag() {
         let mut parser = HtmlParser::new();
@@ -5650,7 +5706,8 @@ mod tests {
         assert!(
             fragments.iter().any(|f| matches!(
                 f.fragment.as_ref(),
-                Some(Fragment::Signal(s)) if s.value == "tokens" && !s.raw
+                Some(Fragment::Signal(s))
+                    if s.value == "tokens" && !s.raw && s.raw_text_context
             )),
             "uppercase <STYLE> should be CSS-processed, got: {:?}",
             fragments
@@ -8213,7 +8270,7 @@ mod tests {
                 raw("<html><head>"),
                 structural_matcher("head_start"),
                 raw("<style>\n:root {\n    "),
-                signal_raw("tokens.light"),
+                raw_text_signal("tokens.light", true),
                 raw("\n}\n</style>"),
                 structural_matcher("head_end"),
                 raw("</head><body>"),
@@ -8244,7 +8301,7 @@ mod tests {
                 raw("<html><head>"),
                 structural_matcher("head_start"),
                 raw("<style>\n:root {\n    "),
-                signal_raw("tokens.light"),
+                raw_text_signal("tokens.light", true),
                 raw("\n}\n</style>"),
                 structural_matcher("head_end"),
                 raw("</head><body>"),
@@ -8271,7 +8328,7 @@ mod tests {
                 raw("<html><head>"),
                 structural_matcher("head_start"),
                 raw("<style>"),
-                signal("themeCss"),
+                raw_text_signal("themeCss", false),
                 raw("</style>"),
                 structural_matcher("head_end"),
                 raw("</head><body>"),
@@ -8379,7 +8436,7 @@ mod tests {
                 raw("<html><head>"),
                 structural_matcher("head_start"),
                 raw("<style>\n  .a { color: red; }\n  "),
-                signal("themeCss"),
+                raw_text_signal("themeCss", false),
                 raw("\n  .b { color: blue; }\n</style>"),
                 structural_matcher("head_end"),
                 raw("</head><body>"),
diff --git a/crates/webui-parser/src/plugin/webui.rs b/crates/webui-parser/src/plugin/webui.rs
index 1be8e15cc..a0a5b31a5 100644
--- a/crates/webui-parser/src/plugin/webui.rs
+++ b/crates/webui-parser/src/plugin/webui.rs
@@ -1580,7 +1580,7 @@ fn compile_style_content(input: &str, meta: &mut TemplateSectionMeta) {
 fn compile_css_signal_comment(comment: &str, meta: &mut TemplateSectionMeta) -> bool {
     if let Some(signal) = comment_policy::parse_css_signal_comment(comment) {
         let idx = meta.text_bindings.len();
-        meta.text_bindings.push((signal.path, signal.raw));
+        meta.text_bindings.push((signal.path, false));
         emit_text_marker(meta, idx);
         return true;
     }
@@ -1682,7 +1682,11 @@ fn process_fragment_children(
         if let Some((parts, consumed, has_dynamic, is_raw)) =
             collect_text_run(&nodes[index..], text_bindings)
         {
-            if has_dynamic {
+            let adjacent_to_raw = !has_dynamic
+                && ((index > 0 && is_raw_text_marker(&nodes[index - 1], text_bindings))
+                    || (index + consumed < nodes.len()
+                        && is_raw_text_marker(&nodes[index + consumed], text_bindings)));
+            if has_dynamic || adjacent_to_raw {
                 // Decode HTML entities in static parts so that runtime
                 // textContent assignment renders decoded characters
                 // (e.g. `&gt;` → `>`).  Static-only text runs are
@@ -1885,10 +1889,15 @@ fn collect_text_run(
             FragmentNode::Comment(_) => break,
             FragmentNode::TextMarker(index) => {
                 if let Some((path, raw)) = text_bindings.get(*index) {
+                    if *raw && consumed != 0 {
+                        break;
+                    }
                     parts.push(CompiledAttrPart::Dynamic(path.clone()));
                     has_dynamic = true;
                     if *raw {
                         is_raw = true;
+                        consumed += 1;
+                        break;
                     }
                     consumed += 1;
                 } else {
@@ -1906,6 +1915,13 @@ fn collect_text_run(
     Some((parts, consumed, has_dynamic, is_raw))
 }
 
+fn is_raw_text_marker(node: &FragmentNode, text_bindings: &[(String, bool)]) -> bool {
+    let FragmentNode::TextMarker(index) = node else {
+        return false;
+    };
+    text_bindings.get(*index).is_some_and(|(_, raw)| *raw)
+}
+
 fn collect_static_text(parts: &[CompiledAttrPart]) -> String {
     let mut text = String::new();
     for part in parts {
@@ -3499,7 +3515,10 @@ mod tests {
         );
 
         assert_no_client_markers(&result);
-        assert!(result.contains(r#"["tokens.light"]"#));
+        assert!(
+            result.contains(r#","tx":[[[1,0],[":root{",["tokens.light"],"}"]]]"#),
+            "raw CSS stays an ordinary text binding: {result}"
+        );
         assert!(!result.contains("/*"));
         assert!(!result.contains("*/"));
     }
@@ -4650,6 +4669,29 @@ mod tests {
         );
     }
 
+    #[test]
+    fn raw_binding_is_split_from_adjacent_text_and_escaped_binding() {
+        let result =
+            generate_compiled_template("my-comp", r#"<div>Before {{{html}}} After {{name}}</div>"#);
+
+        assert!(
+            result.contains(
+                r#","tx":[[[1,0],["Before "]],[[1,0,1],[["html"]],1],[[1,0,2],[" After ",["name"]]]]"#,
+            ),
+            "raw HTML must own only its signal while adjacent text remains separate: {result}"
+        );
+    }
+
+    #[test]
+    fn adjacent_raw_bindings_compile_to_distinct_ranges() {
+        let result = generate_compiled_template("my-comp", r#"<div>{{{first}}}{{{second}}}</div>"#);
+
+        assert!(
+            result.contains(r#","tx":[[[1,0],[["first"]],1],[[1,0,1],[["second"]],1]]"#,),
+            "each raw binding needs one metadata entry and one marker range: {result}"
+        );
+    }
+
     #[test]
     fn test_for_with_complex_body() {
         let result = generate_compiled_template(
diff --git a/crates/webui-protocol/proto/webui.proto b/crates/webui-protocol/proto/webui.proto
index 49ec2ddbd..d32d02662 100644
--- a/crates/webui-protocol/proto/webui.proto
+++ b/crates/webui-protocol/proto/webui.proto
@@ -225,6 +225,9 @@ message WebUIFragmentFor {
 message WebUIFragmentSignal {
   string value = 1;
   bool raw = 2;
+  // True inside an HTML raw-text context such as <style>. Raw-text signals do
+  // not own replaceable HTML sibling ranges because comments parse as text.
+  bool raw_text_context = 3;
 }
 
 // Conditional rendering fragment.
diff --git a/crates/webui-protocol/src/gen_webui.rs b/crates/webui-protocol/src/gen_webui.rs
index 1e84389b9..52fddc7fe 100644
--- a/crates/webui-protocol/src/gen_webui.rs
+++ b/crates/webui-protocol/src/gen_webui.rs
@@ -275,6 +275,10 @@ pub struct WebUiFragmentSignal {
     pub value: ::prost::alloc::string::String,
     #[prost(bool, tag = "2")]
     pub raw: bool,
+    /// True inside an HTML raw-text context such as <style>. Raw-text signals do
+    /// not own replaceable HTML sibling ranges because comments parse as text.
+    #[prost(bool, tag = "3")]
+    pub raw_text_context: bool,
 }
 /// Conditional rendering fragment.
 #[derive(serde::Serialize, serde::Deserialize)]
diff --git a/crates/webui-protocol/src/lib.rs b/crates/webui-protocol/src/lib.rs
index dc46f173b..3ed6a06d2 100644
--- a/crates/webui-protocol/src/lib.rs
+++ b/crates/webui-protocol/src/lib.rs
@@ -167,6 +167,22 @@ impl WebUiFragment {
             fragment: Some(web_ui_fragment::Fragment::Signal(WebUiFragmentSignal {
                 value: value.into(),
                 raw,
+                raw_text_context: false,
+            })),
+        }
+    }
+
+    /// Create a signal inside an HTML raw-text context such as `<style>`.
+    ///
+    /// The rendered value follows `raw` escaping semantics but never owns an
+    /// HTML sibling range because comment markers are plain text in raw-text
+    /// elements.
+    pub fn raw_text_signal(value: impl Into<String>, raw: bool) -> Self {
+        Self {
+            fragment: Some(web_ui_fragment::Fragment::Signal(WebUiFragmentSignal {
+                value: value.into(),
+                raw,
+                raw_text_context: true,
             })),
         }
     }
@@ -819,7 +835,22 @@ mod tests {
         let decoded = WebUIProtocol::from_protobuf(&bytes).unwrap();
         let frag = &decoded.fragments["main"].fragments[0];
         match frag.fragment.as_ref() {
-            Some(web_ui_fragment::Fragment::Signal(s)) => assert!(!s.raw),
+            Some(web_ui_fragment::Fragment::Signal(s)) => {
+                assert!(!s.raw);
+                assert!(!s.raw_text_context);
+            }
+            _ => panic!("expected signal"),
+        }
+    }
+
+    #[test]
+    fn raw_text_signal_does_not_own_html_range() {
+        let fragment = WebUIFragment::raw_text_signal("tokens.light", true);
+        match fragment.fragment.as_ref() {
+            Some(web_ui_fragment::Fragment::Signal(signal)) => {
+                assert!(signal.raw);
+                assert!(signal.raw_text_context);
+            }
             _ => panic!("expected signal"),
         }
     }
diff --git a/crates/webui-test-utils/src/lib.rs b/crates/webui-test-utils/src/lib.rs
index 208b1289c..9d36eb2bd 100644
--- a/crates/webui-test-utils/src/lib.rs
+++ b/crates/webui-test-utils/src/lib.rs
@@ -66,6 +66,7 @@ pub enum FragmentMatcher {
     Signal {
         value: String,
         raw: bool,
+        raw_text_context: bool,
     },
     Attribute(AttrMatcher),
     Component(String),
@@ -108,6 +109,7 @@ pub fn signal(value: &str) -> FragmentMatcher {
     FragmentMatcher::Signal {
         value: value.to_string(),
         raw: false,
+        raw_text_context: false,
     }
 }
 
@@ -116,6 +118,16 @@ pub fn signal_raw(value: &str) -> FragmentMatcher {
     FragmentMatcher::Signal {
         value: value.to_string(),
         raw: true,
+        raw_text_context: false,
+    }
+}
+
+/// Match a signal rendered in an HTML raw-text context.
+pub fn raw_text_signal(value: &str, raw: bool) -> FragmentMatcher {
+    FragmentMatcher::Signal {
+        value: value.to_string(),
+        raw,
+        raw_text_context: true,
     }
 }
 
@@ -301,9 +313,20 @@ pub fn assert_fragment_list(
             (Some(Fragment::Raw(r)), FragmentMatcher::Raw(expected)) => {
                 assert_eq!(r.value, *expected, "Fragment[{}]: raw value mismatch", i);
             }
-            (Some(Fragment::Signal(s)), FragmentMatcher::Signal { value, raw }) => {
+            (
+                Some(Fragment::Signal(s)),
+                FragmentMatcher::Signal {
+                    value,
+                    raw,
+                    raw_text_context,
+                },
+            ) => {
                 assert_eq!(s.value, *value, "Fragment[{}]: signal value mismatch", i);
                 assert_eq!(s.raw, *raw, "Fragment[{}]: signal raw flag mismatch", i);
+                assert_eq!(
+                    s.raw_text_context, *raw_text_context,
+                    "Fragment[{i}]: signal raw-text context mismatch"
+                );
             }
             (Some(Fragment::Attribute(a)), FragmentMatcher::Attribute(m)) => {
                 assert_eq!(a.name, m.name, "Fragment[{}]: attr name mismatch", i);
@@ -455,6 +478,9 @@ fn format_fragment(frag: &webui_protocol::WebUIFragment) -> String {
     use webui_protocol::web_ui_fragment::Fragment;
     match frag.fragment.as_ref() {
         Some(Fragment::Raw(r)) => format!("raw({:?})", r.value),
+        Some(Fragment::Signal(s)) if s.raw_text_context => {
+            format!("raw_text_signal({:?}, raw={})", s.value, s.raw)
+        }
         Some(Fragment::Signal(s)) => format!("signal({:?}, raw={})", s.value, s.raw),
         Some(Fragment::Attribute(a)) => format!(
             "attr({:?}, value={:?}, template={:?}, complex={}, start={}, skip={}, raw_value={})",
diff --git a/docs/guide/concepts/plugins/index.md b/docs/guide/concepts/plugins/index.md
index a643e2d00..f76f5e121 100644
--- a/docs/guide/concepts/plugins/index.md
+++ b/docs/guide/concepts/plugins/index.md
@@ -148,10 +148,27 @@ pub trait HandlerPlugin: Send {
     /// Leave the current scope.
     fn pop_scope(&mut self);
 
-    /// Called before/after a signal binding.
+    /// Called before/after an escaped or raw-text signal binding.
     fn on_binding_start(&mut self, name: &str, writer: &mut dyn ResponseWriter) -> Result<()>;
     fn on_binding_end(&mut self, name: &str, writer: &mut dyn ResponseWriter) -> Result<()>;
 
+    /// Called before/after an owned raw HTML range. The default methods
+    /// delegate to on_binding_start/end for source compatibility.
+    fn on_raw_binding_start(
+        &mut self,
+        name: &str,
+        writer: &mut dyn ResponseWriter,
+    ) -> Result<()> {
+        self.on_binding_start(name, writer)
+    }
+    fn on_raw_binding_end(
+        &mut self,
+        name: &str,
+        writer: &mut dyn ResponseWriter,
+    ) -> Result<()> {
+        self.on_binding_end(name, writer)
+    }
+
     /// Called before/after for-loop and if-condition blocks.
     fn on_for_start(&mut self, name: &str, writer: &mut dyn ResponseWriter) -> Result<()>;
     fn on_for_end(&mut self, name: &str, writer: &mut dyn ResponseWriter) -> Result<()>;
diff --git a/packages/webui-framework/README.md b/packages/webui-framework/README.md
index 18cd2575b..8853d2f4c 100644
--- a/packages/webui-framework/README.md
+++ b/packages/webui-framework/README.md
@@ -471,10 +471,11 @@ resource-constrained devices.
    `$update(path)` only visits bindings that reference the changed property.
    Everything else is skipped via a per-path index built once at hydration time.
 
-2. **Zero allocations during updates.**
+2. **Zero framework allocations during ordinary updates.**
    Targeted updates are a single `Map.get()` → direct array iteration.
    No intermediate arrays, no object creation, no spread operators on the
-   update path.
+   update path. A changed raw HTML binding necessarily parses and creates its
+   replacement DOM nodes inside its pre-resolved ownership range.
 
 3. **Parse once, clone forever.**
    Compiled template HTML is parsed via `innerHTML` once per component tag
@@ -928,24 +929,28 @@ const target = elements[index];
 ### SSR resolution (`buildSSRIndex`)
 
 SSR DOM differs from the compiled template: the renderer strips inter-element
-whitespace, and `<if>` / `<for>` bodies are rendered inline between markers.
+whitespace, `<if>` / `<for>` bodies are rendered inline between structural
+markers, and raw HTML values can contribute arbitrary element runs.
 `buildSSRIndex` walks the SSR DOM and the compiled template DOM **in lockstep**,
 skipping whole marker ranges, and numbers the result the same way:
 
 ```typescript
 // Elements are paired positionally and numbered in pre-order.
-// Structural ranges are skipped whole — that content belongs to
-// the block's own metadata.
+// Structural and raw HTML ranges are skipped whole - that content
+// is not part of the enclosing section's static element numbering.
 // Text is the exception: whitespace stripping means text nodes do
-// not line up, so text slots still resolve by ordinal.
+// not line up, so each text slot resolves from its compiled
+// right-hand static or marker boundary.
 ```
 
-This eliminates all *per-binding* annotation: no `data-w-*` attributes, no
-comment per text run, no DOM markers around individual bindings.  What the SSR
-server does emit is the five structural comments documented above
-(`<!--wr-->`, `<!--wi-->`, `<!--/wr-->`, `<!--wc-->`, `<!--/wc-->`), which
-delimit `<if>` / `<for>` bodies and are what the walk skips over and anchors
-blocks on.  They are removed once hydration completes.
+This eliminates annotations for ordinary bindings: no `data-w-*` attributes and
+no comments around escaped text. The SSR server emits five structural comments
+for `<if>` / `<for>` bodies plus paired `<!--wN-->` / `<!--/wN-->` markers around each raw HTML
+binding. Structural closing/item markers are removed after hydration. Raw HTML
+anchors remain so updates can replace zero or multiple direct sibling nodes
+without touching content outside the binding's range. These exact marker
+comments are framework-reserved and must not appear in the trusted raw value
+inside that range.
 
 ---
 
@@ -963,7 +968,8 @@ blocks on.  They are removed once hydration completes.
 
 - **No virtual DOM** — no tree copy, no diff algorithm
 - **No runtime template parsing** — the Rust compiler handles all syntax
-- **No `innerHTML` on updates** — only `textContent` and `setAttribute`
+- **No parent-wide `innerHTML` on updates** — raw HTML parses into its bounded
+  contextual range; escaped text and attributes patch direct node references
 - **No `querySelector` on updates** — all nodes are pre-resolved references
 - **No recursion in hot paths** — conditions use iterative stack evaluation
 
diff --git a/packages/webui-framework/src/element/markers.test.ts b/packages/webui-framework/src/element/markers.test.ts
index 740b05ecd..2e3392ec8 100644
--- a/packages/webui-framework/src/element/markers.test.ts
+++ b/packages/webui-framework/src/element/markers.test.ts
@@ -525,6 +525,35 @@ describe('buildSSRIndex', () => {
     assert.deepStrictEqual(index.conds, [markerA, markerC, markerB]);
   });
 
+  test('collects raw ranges and excludes their elements from static pairing', () => {
+    const tplStatic = el('SPAN');
+    const tpl = el('ROOT', tplStatic);
+    const rawStart = cmt('w0');
+    const rawEnd = cmt('/w0');
+    const ssrStatic = el('SPAN');
+    const ssr = el('ROOT', rawStart, el('B'), el('I'), rawEnd, ssrStatic);
+
+    const index = build(tpl, ssr);
+
+    assert.deepStrictEqual(index.raws, [[rawStart, rawEnd]]);
+    assert.strictEqual(index.elements[1], ssrStatic);
+  });
+
+  test('ignores legacy-looking comments inside an indexed raw range', () => {
+    const tplStatic = el('SPAN');
+    const tpl = el('ROOT', tplStatic);
+    const rawStart = cmt('w0');
+    const contentComment = cmt('/wh');
+    const rawEnd = cmt('/w0');
+    const ssrStatic = el('SPAN');
+    const ssr = el('ROOT', rawStart, el('B'), contentComment, el('I'), rawEnd, ssrStatic);
+
+    const index = build(tpl, ssr);
+
+    assert.deepStrictEqual(index.raws, [[rawStart, rawEnd]]);
+    assert.strictEqual(index.elements[1], ssrStatic);
+  });
+
   test('does not pair elements inside a structural range', () => {
     // The <p> rendered inside the conditional belongs to the block's own
     // metadata, so the template's first element must pair with <div>.
diff --git a/packages/webui-framework/src/element/markers.ts b/packages/webui-framework/src/element/markers.ts
index 38daf44b9..322a179d4 100644
--- a/packages/webui-framework/src/element/markers.ts
+++ b/packages/webui-framework/src/element/markers.ts
@@ -15,6 +15,8 @@
  *   <!--wi-->   repeat item boundary
  *   <!--wc-->   conditional block start
  *   <!--/wc-->  conditional block end
+ *   <!--wN-->   raw HTML binding start
+ *   <!--/wN-->  raw HTML binding end
  */
 
 // Marker data constants matching the handler plugin output.
@@ -22,9 +24,25 @@ export const MARKER_REPEAT_START = 'wr';
 export const MARKER_REPEAT_END = '/wr';
 export const MARKER_COND_START = 'wc';
 export const MARKER_COND_END = '/wc';
+export const MARKER_RAW_START = 'w';
+export const MARKER_RAW_END = '/w';
 
 const MARKER_REPEAT_ITEM = 'wi';
 
+/** Build the paired marker data for a client-created raw binding. */
+export function rawMarker(index: number, closing = false): string {
+  return `${closing ? MARKER_RAW_END : MARKER_RAW_START}${index}`;
+}
+
+function isRawStartMarker(data: string): boolean {
+  if (data.length < 2 || data.charCodeAt(0) !== 119 /* w */) return false;
+  for (let i = 1; i < data.length; i++) {
+    const code = data.charCodeAt(i);
+    if (code < 48 /* 0 */ || code > 57 /* 9 */) return false;
+  }
+  return true;
+}
+
 /**
  * Collect the item markers (<!--wi-->) within a repeat range.
  *
@@ -66,6 +84,10 @@ export function nextElement(marker: Comment): Element | null {
     if (node.nodeType === 1 /* ELEMENT_NODE */) return node as Element;
     if (node.nodeType === 8 /* COMMENT_NODE */) {
       const data = (node as Comment).data;
+      if (isRawStartMarker(data)) {
+        node = skipBlockRange(node as Comment, data);
+        continue;
+      }
       if (data === MARKER_REPEAT_END || data === MARKER_REPEAT_ITEM || data === MARKER_COND_END) return null;
     }
     node = node.nextSibling;
@@ -76,13 +98,17 @@ export function nextElement(marker: Comment): Element | null {
 /**
  * Skip a complete structural block range and return the node that follows it.
  *
- * `start` must be a `<!--wc-->` or `<!--wr-->` comment.  Walks forward with
+ * `start` must be a `<!--wc-->`, `<!--wr-->`, or `<!--wN-->` comment. Walks forward with
  * depth tracking over same-type markers so nested blocks of the same kind are
  * consumed as part of the range, and returns the sibling after the matching
  * closing marker (or `null` when the range is unterminated).
  */
 export function skipBlockRange(start: Comment, data: string): ChildNode | null {
-  const endTag = data === MARKER_COND_START ? MARKER_COND_END : MARKER_REPEAT_END;
+  const endTag = data === MARKER_COND_START
+    ? MARKER_COND_END
+    : isRawStartMarker(data)
+      ? `/${data}`
+      : MARKER_REPEAT_END;
   let depth = 1;
   let node: ChildNode | null = start.nextSibling;
   while (node && depth > 0) {
@@ -132,13 +158,14 @@ export function collectTemplateElements(root: Node): Array<Node | undefined> {
  * A resolved view of one SSR subtree, built in a single pre-order pass.
  *
  * `elements` holds the server-rendered element for each compiled pre-order
- * index, and `conds` / `repeats` list the structural markers in document order.
+ * index. Block markers and raw HTML ranges are listed in document order.
  */
 export interface SSRIndex {
   /** Server-rendered elements by pre-order index; `0` is the section root. */
   elements: Array<Node | undefined>;
   conds: Comment[];
   repeats: Comment[];
+  raws: Array<[Comment, Comment]>;
 }
 
 /**
@@ -183,6 +210,7 @@ export function buildSSRIndex(
   const elements: Array<Node | undefined> = [ssrIsSectionChild ? undefined : ssrRoot];
   const conds: Comment[] = [];
   const repeats: Comment[] = [];
+  const raws: Array<[Comment, Comment]> = [];
   // `solo` bounds a frame to the single element it was entered on.  In-place
   // block hydration starts inside the block's own `<!--wc-->` range, so an
   // unbounded frame would run past the closing marker once the template ran
@@ -216,6 +244,27 @@ export function buildSSRIndex(
           s = skipBlockRange(s as Comment, data);
           continue;
         }
+        if (isRawStartMarker(data)) {
+          const start = s as Comment;
+          let end: ChildNode | null = start.nextSibling;
+          let depth = 1;
+          const endMarker = `/${data}`;
+          while (end && depth > 0) {
+            if (end.nodeType === 8 /* COMMENT_NODE */) {
+              const marker = (end as Comment).data;
+              if (marker === data) depth++;
+              else if (marker === endMarker) depth--;
+            }
+            if (depth > 0) end = end.nextSibling;
+          }
+          if (end) {
+            raws.push([start, end as Comment]);
+            s = end.nextSibling;
+          } else {
+            s = null;
+          }
+          continue;
+        }
       } else if (type === 1 /* ELEMENT_NODE */) {
         break;
       }
@@ -255,7 +304,7 @@ export function buildSSRIndex(
     }
   }
 
-  return { elements, conds, repeats };
+  return { elements, conds, repeats, raws };
 }
 
 
@@ -286,7 +335,11 @@ export function findByOrdinal(parent: Node, nodeType: number, ordinal: number):
     // Detect a structural block opening marker and skip the entire range.
     if (child.nodeType === 8 /* COMMENT_NODE */) {
       const data = (child as Comment).data;
-      if (data === MARKER_COND_START || data === MARKER_REPEAT_START) {
+      if (
+        data === MARKER_COND_START
+        || data === MARKER_REPEAT_START
+        || isRawStartMarker(data)
+      ) {
         child = skipBlockRange(child as Comment, data);
         continue;
       }
diff --git a/packages/webui-framework/src/element/types.ts b/packages/webui-framework/src/element/types.ts
index 2afc1824f..d494281fe 100644
--- a/packages/webui-framework/src/element/types.ts
+++ b/packages/webui-framework/src/element/types.ts
@@ -25,18 +25,21 @@ import type {
   CompiledCondition,
 } from '../template.js';
 
-/** Direct reference to a text node bound to a property path. */
+/** Direct reference to character data bound to a property path. */
 export interface TextBinding {
-  node: Text;
+  node: CharacterData;
   path?: string;
   parts?: CompiledAttrPart[];
   scope?: ScopeFrame;
-  /** When true, the binding renders unescaped HTML via innerHTML on the
-   *  parent element instead of setting Text.data. Corresponds to the
-   *  triple-brace `{{{expr}}}` template syntax. */
+  /** When true, the binding renders unescaped HTML between comment anchors.
+   *  Corresponds to the triple-brace `{{{expr}}}` template syntax. */
   raw?: boolean;
-  /** The parent element for raw bindings — innerHTML is set here. */
-  rawParent?: Element;
+  /** Closing ownership anchor for a raw HTML binding. */
+  rawEnd?: Comment;
+  /** Last client-patched value, used to avoid repeat HTML parsing. */
+  rawValue?: string;
+  /** Owning instance when the raw range is part of its top-level node list. */
+  rawOwner?: TemplateInstance;
 }
 
 /** Attribute binding kind constants (matches compiled metadata). */
diff --git a/packages/webui-framework/src/hydration-mismatch.test.ts b/packages/webui-framework/src/hydration-mismatch.test.ts
index b3a8dddd9..b87f9bc58 100644
--- a/packages/webui-framework/src/hydration-mismatch.test.ts
+++ b/packages/webui-framework/src/hydration-mismatch.test.ts
@@ -86,12 +86,12 @@ describe('textDiffersFromDom', () => {
     assert.equal(textDiffersFromDom(b, makeCtx({}, 'a-c')), true);
   });
 
-  test('raw bindings are skipped (innerHTML re-serialization is unreliable)', () => {
+  test('raw bindings are skipped because their owned range is not text data', () => {
     const b = {
-      node: { data: 'stale' } as unknown as Text,
+      node: { data: 'wh' } as unknown as Comment,
       path: 'html',
       raw: true,
-      rawParent: fakeEl({}, '<b>x</b>'),
+      rawEnd: { data: '/wh' } as unknown as Comment,
     } as TextBinding;
     // Even with a divergent value, raw bindings never report a mismatch.
     assert.equal(textDiffersFromDom(b, makeCtx({ html: '<b>y</b>' })), false);
diff --git a/packages/webui-framework/src/template-element.ts b/packages/webui-framework/src/template-element.ts
index deb1c4918..6abbf973f 100644
--- a/packages/webui-framework/src/template-element.ts
+++ b/packages/webui-framework/src/template-element.ts
@@ -21,11 +21,13 @@
  *   - `<!--wr-->` / `<!--/wr-->` — repeat (for-loop) block boundaries
  *   - `<!--wi-->` — repeat item boundary (one per item)
  *   - `<!--wc-->` / `<!--/wc-->` — conditional (if) block boundaries
+ *   - `<!--wN-->` / `<!--/wN-->` — raw HTML ownership boundaries
  *
  * During hydration these markers are consumed: `<!--wi-->`, `<!--/wr-->`,
- * and `<!--/wc-->` are removed from the DOM.  The `<!--wr-->` start
+ * and `<!--/wc-->` are removed from the DOM. The `<!--wr-->` start
  * marker is kept as the runtime repeat anchor, and `<!--wc-->` is kept
- * as the runtime condition anchor.
+ * as the runtime condition anchor. Raw HTML markers remain as the minimum
+ * stable range required for sibling-safe reactive replacement.
  *
  * **Marker removal is deferred** until after all path-based resolution
  * (`buildSSRIndex`, `$findSSRText`, `$finalize`) is complete.  This is
@@ -55,6 +57,7 @@ import type {
   CompiledAttrPart,
   CompiledCondition,
   TemplateNodeIndex,
+  TemplateSlot,
 } from './template.js';
 import { hydrationStart, hydrationEnd } from './lifecycle.js';
 import {
@@ -77,6 +80,8 @@ import {
   collectTemplateElements,
   MARKER_COND_START,
   MARKER_COND_END,
+  rawMarker,
+  type SSRIndex,
 } from './element/markers.js';
 import {
   injectModuleStyle,
@@ -144,6 +149,10 @@ const templateDOMCache = new WeakMap<TemplateBlockMeta, Element>();
 /** Pre-computed ordinals for template nodes: childIndex → [nodeType, ordinal].
  *  Avoids re-counting siblings on every text-slot resolution. */
 const tplOrdinalCache = new WeakMap<Node, Map<number, [nodeType: number, ordinal: number]>>();
+/** Encoded next marker boundary per text slot, built once per template. */
+const textMarkerBoundaryCache = new WeakMap<TemplateBlockMeta, Int32Array>();
+const NO_TEXT_MARKER_BOUNDARIES = new Int32Array(0);
+const RAW_MARKER_BOUNDARY_BASE = 0x40000000;
 
 /**
  * Pre-order element table for a parsed template, keyed by its root.
@@ -168,16 +177,67 @@ function getTplOrdinals(tplNode: Node): Map<number, [number, number]> {
   map = new Map();
   let elemOrd = 0;
   let textOrd = 0;
+  let commentOrd = 0;
   const children = tplNode.childNodes;
   for (let k = 0; k < children.length; k++) {
     const type = children[k].nodeType;
     if (type === 1) { map.set(k, [1, elemOrd]); elemOrd++; }
     else if (type === 3) { map.set(k, [3, textOrd]); textOrd++; }
+    else if (type === 8) { map.set(k, [8, commentOrd]); commentOrd++; }
   }
   tplOrdinalCache.set(tplNode, map);
   return map;
 }
 
+function slotKey(slot: TemplateSlot, orderOffset = 0): string {
+  return `${slot[0]},${slot[1]},${(slot[2] ?? 0) + orderOffset}`;
+}
+
+/**
+ * Resolve the dynamic marker immediately after each text slot.
+ *
+ * Positive values encode `meta.c` indexes plus one; negative values encode
+ * `meta.r` indexes plus one; large positive values encode raw-range indexes.
+ * The compiler assigns gapless order values within each static slot.
+ */
+function getTextMarkerBoundaries(meta: TemplateBlockMeta): Int32Array {
+  const cached = textMarkerBoundaryCache.get(meta);
+  if (cached) return cached;
+  const texts = meta.tx;
+  if (!texts) {
+    textMarkerBoundaryCache.set(meta, NO_TEXT_MARKER_BOUNDARIES);
+    return NO_TEXT_MARKER_BOUNDARIES;
+  }
+
+  const markers = new Map<string, number>();
+  if (meta.c) {
+    for (let i = 0; i < meta.c.length; i++) {
+      markers.set(slotKey(meta.c[i][2]), i + 1);
+    }
+  }
+  if (meta.r) {
+    for (let i = 0; i < meta.r.length; i++) {
+      markers.set(slotKey(meta.r[i][3]), -(i + 1));
+    }
+  }
+  let rawIndex = 0;
+  for (let i = 0; i < texts.length; i++) {
+    if (texts[i][2] !== 1) continue;
+    markers.set(
+      slotKey(texts[i][0]),
+      RAW_MARKER_BOUNDARY_BASE + rawIndex + 1,
+    );
+    rawIndex++;
+  }
+
+  const boundaries = new Int32Array(texts.length);
+  for (let i = 0; i < texts.length; i++) {
+    boundaries[i] = markers.get(slotKey(texts[i][0], 1)) ?? 0;
+  }
+  textMarkerBoundaryCache.set(meta, boundaries);
+  return boundaries;
+}
+
 // ── Sentinels ───────────────────────────────────────────────────
 
 const EMPTY_ARR: readonly never[] = [];
@@ -702,6 +762,7 @@ export class TemplateElement extends HTMLElement {
         // Retained DOM is client-owned after the first mount. Reconcile roots
         // that are still available while preserving trusted values for any
         // template-only state the client never received.
+        this.$invalidateRawValues(this.$root);
         this.$updateBindings(
           this.$root.texts,
           this.$root.attrs,
@@ -1671,16 +1732,23 @@ export class TemplateElement extends HTMLElement {
     // Now insert anchors using pre-resolved references
 
     // Text bindings
+    let rawIndex = 0;
     for (let i = 0; i < textRefCount; i++) {
       const t = textRefs[i];
-      const anchor = document.createComment('');
+      const anchor = document.createComment(t.raw ? rawMarker(rawIndex, true) : '');
       t.parent.insertBefore(anchor, t.ref);
       if (t.raw) {
-        // Raw binding: create a container span for innerHTML updates
-        const container = document.createElement('span');
-        t.parent.insertBefore(container, anchor);
-        const textNode = document.createTextNode('');
-        instance.texts.push({ node: textNode, parts: t.parts, scope, raw: true, rawParent: container });
+        const start = document.createComment(rawMarker(rawIndex));
+        rawIndex++;
+        t.parent.insertBefore(start, anchor);
+        instance.texts.push({
+          node: start,
+          parts: t.parts,
+          scope,
+          raw: true,
+          rawEnd: anchor,
+          rawOwner: instance,
+        });
       } else {
         const textNode = document.createTextNode('');
         t.parent.insertBefore(textNode, anchor);
@@ -1774,38 +1842,76 @@ export class TemplateElement extends HTMLElement {
     // Built before any mutation: the phases below insert text nodes and
     // anchors, but never add or permanently remove elements outside a block
     // range, so the element pairing stays valid for the whole pass.
+    let rawTextCount = 0;
+    if (meta.tx) {
+      for (let i = 0; i < meta.tx.length; i++) {
+        if (meta.tx[i][2] === 1) rawTextCount++;
+      }
+    }
     const ssrIndex = buildSSRIndex(
       tplDom,
       ssrRoot,
-      meta.c !== undefined || meta.r !== undefined,
+      meta.c !== undefined || meta.r !== undefined || rawTextCount !== 0,
       pathStart > 0,
     );
     const ssrElements = ssrIndex.elements;
     const tplElements = getTemplateElements(tplDom);
+    const textMarkerBoundaries = getTextMarkerBoundaries(meta);
 
     // Text bindings — find existing text nodes rendered by the server
     if (meta.tx) {
+      const rawRanges = ssrIndex.raws.length === rawTextCount ? ssrIndex.raws : null;
+      let rawIndex = 0;
       for (let i = 0; i < meta.tx.length; i++) {
         const entry = meta.tx[i];
         const [slot, parts] = entry;
         const raw = entry[2] === 1;
-        const [parentIndex, beforeIndex] = slot;
+        const [parentIndex] = slot;
         const ssrParent = ssrElements[parentIndex];
         if (!ssrParent) continue;
         const tplParent = tplElements[parentIndex];
         if (!tplParent) continue;
         if (raw) {
-          const rawParent = ssrParent as Element;
-          const textNode = document.createTextNode('');
-          instance.texts.push({ node: textNode, parts, scope, raw: true, rawParent });
+          const rawRange = rawRanges?.[rawIndex++];
+          if (!rawRange) continue;
+          const binding: TextBinding = {
+            node: rawRange[0],
+            parts,
+            scope,
+            raw: true,
+            rawEnd: rawRange[1],
+            rawOwner: instance,
+          };
+          if (
+            (!scope || this.$scopeIsKnown(scope))
+            && this.$textStateIsKnown(binding)
+          ) {
+            binding.rawValue = this.$resolveParts(parts, scope);
+          }
+          instance.texts.push(binding);
         } else {
-          let textNode = this.$findSSRText(ssrParent, tplParent, beforeIndex);
-          if (!textNode) {
+          const insertRef = this.$findSSRSlotRef(
+            ssrParent,
+            tplParent,
+            meta,
+            ssrIndex,
+            slot,
+            textMarkerBoundaries[i] ?? 0,
+          );
+          let previous = insertRef ? insertRef.previousSibling : ssrParent.lastChild;
+          if (
+            previous?.nodeType === 8
+            && (previous as Comment).data === ''
+            && previous.previousSibling?.nodeType === 3
+          ) {
+            previous = previous.previousSibling;
+          }
+          let textNode = previous?.nodeType === 3 ? previous as Text : null;
+          if (textNode === null) {
             textNode = document.createTextNode('');
-            const insertRef = this.$findSSRSlotRef(ssrParent, tplParent, beforeIndex);
             ssrParent.insertBefore(textNode, insertRef);
           }
-          if (textNode) instance.texts.push({ node: textNode, parts, scope });
+          instance.texts.push({ node: textNode, parts, scope });
         }
       }
     }
@@ -1851,7 +1957,7 @@ export class TemplateElement extends HTMLElement {
         // than claiming the first static sibling after <!--/wc-->.
         if (marker && blockMeta) {
           condInstance = this.$hydrateCondContent(condAnchor, blockMeta, scope);
-          if (condInstance) condInstance.parent = instance;
+          if (condInstance) this.$setInstanceParent(condInstance, instance);
         }
 
         // Collect the <!--/wc--> end marker for deferred removal.  Do NOT remove
@@ -1886,7 +1992,10 @@ export class TemplateElement extends HTMLElement {
         const ssrParent = (marker ? marker.parentNode : ssrElements[parentIndex]) ?? ssrRoot;
         const blockMeta = this.$block(blockIndex);
         const blockTplDom = blockMeta ? getTemplateDom(blockMeta) : null;
-        const rootTag = blockMeta && blockTplDom?.childNodes.length === 1 && blockTplDom.children.length === 1
+        const rootTag = blockMeta
+          && blockTplDom?.childNodes.length === 1
+          && blockTplDom.children.length === 1
+          && !this.$hasRootStructuralSlot(blockMeta)
           ? this.$rootTag(blockMeta)
           : null;
 
@@ -1937,7 +2046,7 @@ export class TemplateElement extends HTMLElement {
               const itemEl = nextElement(itemMarkers[j]);
               if (itemEl) {
                 const childInstance = this.$hydrate(itemEl, blockMeta, blockTplDom, itemScope, 1);
-                childInstance.parent = instance;
+                this.$setInstanceParent(childInstance, instance);
                 repeatInsts.push(childInstance);
               }
             } else {
@@ -1951,7 +2060,6 @@ export class TemplateElement extends HTMLElement {
                 cursor = next;
               }
               const inst = this.$hydrate(wrapper, blockMeta, blockTplDom, itemScope);
-              inst.parent = instance;
               inst.nodes = childNodesArray(wrapper);
               let afterNode: Node = itemMarkers[j];
               for (let nodeIndex = 0; nodeIndex < inst.nodes.length; nodeIndex++) {
@@ -1966,6 +2074,7 @@ export class TemplateElement extends HTMLElement {
                   itemParent as ParentNode & Node,
                 );
               }
+              this.$setInstanceParent(inst, instance);
               repeatInsts.push(inst);
             }
           }
@@ -2049,6 +2158,11 @@ export class TemplateElement extends HTMLElement {
         if (meta.r[i][3][0] === 0) return true;
       }
     }
+    if (meta.tx) {
+      for (let i = 0; i < meta.tx.length; i++) {
+        if (meta.tx[i][2] === 1 && meta.tx[i][0][0] === 0) return true;
+      }
+    }
     return false;
   }
 
@@ -2094,43 +2208,35 @@ export class TemplateElement extends HTMLElement {
     return inst;
   }
 
-  /**
-   * Find existing SSR text node by mapping template text-node ordinal.
-   *
-   * Elements are numbered in pre-order, but text cannot be: the renderer
-   * strips inter-element whitespace that `meta.h` keeps.  Text slots therefore
-   * resolve by ordinal, and the SSR DOM may contain extra text nodes
-   * inside structural blocks (`<if>`/`<for>`) that are not in the
-   * compiled template.  We skip `<!--wc-->...<!--/wc-->` and
-   * `<!--wr-->...<!--/wr-->` ranges to keep text ordinals aligned.
-   */
-  private $findSSRText(ssrParent: Node, tplParent: Node, beforeIndex: number): Text | null {
-    // Count how many text nodes precede `beforeIndex` in the template
-    const ordinals = getTplOrdinals(tplParent);
-    let textOrd = 0;
-    for (let k = 0; k < beforeIndex; k++) {
-      const entry = ordinals.get(k);
-      if (entry && entry[0] === 3) textOrd++;
-    }
-
-    // Find the matching text node in SSR DOM, skipping structural block
-    // content - see findByOrdinal for the skipping algorithm.
-    const found = findByOrdinal(ssrParent, 3 /* TEXT_NODE */, textOrd);
-    if (found) return found as Text;
-
-    // Fallback: any text node with content
-    let child = ssrParent.firstChild;
-    while (child) {
-      if (child.nodeType === 3 && (child as Text).data && (child as Text).data.trim()) {
-        return child as Text;
-      }
-      child = child.nextSibling;
+  /** Find the SSR right-hand boundary for an escaped text slot. */
+  private $findSSRSlotRef(
+    ssrParent: Node,
+    tplParent: Node,
+    meta: TemplateBlockMeta,
+    ssrIndex: SSRIndex,
+    slot: TemplateSlot,
+    markerBoundary: number,
+  ): Node | null {
+    const [, beforeIndex] = slot;
+    let marker: Comment | null = null;
+    if (markerBoundary >= RAW_MARKER_BOUNDARY_BASE) {
+      marker =
+        ssrIndex.raws[markerBoundary - RAW_MARKER_BOUNDARY_BASE - 1]?.[0] ?? null;
+    } else if (
+      markerBoundary > 0
+      && meta.c
+      && ssrIndex.conds.length === meta.c.length
+    ) {
+      marker = ssrIndex.conds[markerBoundary - 1];
+    } else if (
+      markerBoundary < 0
+      && meta.r
+      && ssrIndex.repeats.length === meta.r.length
+    ) {
+      marker = ssrIndex.repeats[-markerBoundary - 1];
     }
-    return null;
-  }
+    if (marker?.parentNode === ssrParent) return marker;
 
-  /** Find the SSR insertion reference for an empty text slot. */
-  private $findSSRSlotRef(ssrParent: Node, tplParent: Node, beforeIndex: number): Node | null {
     const ordinals = getTplOrdinals(tplParent);
     const children = tplParent.childNodes;
     for (let i = beforeIndex; i < children.length; i++) {
@@ -2407,6 +2513,26 @@ export class TemplateElement extends HTMLElement {
     return !binding.path || this.$hasStateRoot(binding.path, binding.scope);
   }
 
+  private $invalidateRawValues(root: TemplateInstance): void {
+    const stack: TemplateInstance[] = [root];
+    while (stack.length > 0) {
+      const instance = stack.pop();
+      if (!instance) continue;
+      for (let i = 0; i < instance.texts.length; i++) {
+        const binding = instance.texts[i];
+        if (binding.raw) binding.rawValue = undefined;
+      }
+      for (let i = 0; i < instance.conds.length; i++) {
+        const child = instance.conds[i].instance;
+        if (child) stack.push(child);
+      }
+      for (let i = 0; i < instance.repeats.length; i++) {
+        const children = instance.repeats[i].instances;
+        for (let j = 0; j < children.length; j++) stack.push(children[j]);
+      }
+    }
+  }
+
   private $attrStateIsKnown(binding: AttrBinding): boolean {
     if (binding.path && !this.$hasStateRoot(binding.path, binding.scope)) return false;
     if (binding.parts && !this.$partsAreKnown(binding.parts, binding.scope)) return false;
@@ -2458,9 +2584,37 @@ export class TemplateElement extends HTMLElement {
     } else {
       return;
     }
-    if (b.raw && b.rawParent) {
-      // Raw binding: render unescaped HTML via innerHTML
-      if (b.rawParent.innerHTML !== val) b.rawParent.innerHTML = val;
+    if (b.raw && b.rawEnd) {
+      if (b.rawValue === val) return;
+      const range = document.createRange();
+      range.setStartAfter(b.node);
+      range.setEndBefore(b.rawEnd);
+      range.deleteContents();
+      let rawNodes: Node[] | undefined;
+      const rawOwner = b.rawOwner;
+      if (val !== '') {
+        const fragment = range.createContextualFragment(val);
+        if (rawOwner && b.node.parentNode === rawOwner.container) {
+          rawNodes = childNodesArray(fragment);
+        }
+        range.insertNode(fragment);
+      } else if (rawOwner && b.node.parentNode === rawOwner.container) {
+        rawNodes = [];
+      }
+      if (rawNodes && rawOwner) {
+        const container = b.node.parentNode;
+        let owner: TemplateInstance | undefined = rawOwner;
+        while (owner && owner.container === container) {
+          const ownerNodes = owner.nodes;
+          const startIndex = ownerNodes.indexOf(b.node);
+          const endIndex = ownerNodes.indexOf(b.rawEnd, startIndex + 1);
+          if (startIndex >= 0 && endIndex > startIndex) {
+            ownerNodes.splice(startIndex + 1, endIndex - startIndex - 1, ...rawNodes);
+          }
+          owner = owner.parent;
+        }
+      }
+      b.rawValue = val;
     } else {
       if (b.node.data !== val) b.node.data = val;
     }
@@ -2603,6 +2757,13 @@ export class TemplateElement extends HTMLElement {
 
   // ── Block instance management ─────────────────────────────────
 
+  private $setInstanceParent(
+    instance: TemplateInstance,
+    parent: TemplateInstance | undefined,
+  ): void {
+    instance.parent = parent;
+  }
+
   $block(blockIndex: number): TemplateBlockMeta | undefined {
     return this.$meta?.b?.[blockIndex];
   }
@@ -2617,7 +2778,6 @@ export class TemplateElement extends HTMLElement {
     if (!bm) return null;
     const wrapper = this.$createStagingRoot(bm);
     const inst = this.$wire(wrapper, bm, scope);
-    inst.parent = parent;
     inst.nodes = childNodesArray(wrapper);
     this.$updateInstance(inst);
     if (inst.repeats.length !== 0 || inst.conds.length !== 0) {
@@ -2626,6 +2786,7 @@ export class TemplateElement extends HTMLElement {
     } else if (container) {
       inst.container = container;
     }
+    this.$setInstanceParent(inst, parent);
     return inst;
   }
 
@@ -2644,7 +2805,7 @@ export class TemplateElement extends HTMLElement {
         cleanups.length = 0;
       }
       if (removeNodes) {
-        for (const node of instance.nodes) node.parentNode?.removeChild(node);
+        this.$removeInstanceNodes(instance);
       }
       for (const binding of instance.conds) {
         if (binding.instance) stack.push(binding.instance);
@@ -2658,6 +2819,11 @@ export class TemplateElement extends HTMLElement {
     }
   }
 
+  private $removeInstanceNodes(instance: TemplateInstance): void {
+    const nodes = instance.nodes;
+    for (let i = 0; i < nodes.length; i++) nodes[i].parentNode?.removeChild(nodes[i]);
+  }
+
   private $compactNodeArray(instance: TemplateInstance): void {
     const container = instance.container;
     if (!container) return;
diff --git a/packages/webui-framework/tests/fixtures/raw-html-conditional/element.ts b/packages/webui-framework/tests/fixtures/raw-html-conditional/element.ts
index 74521d130..5c58a1f2c 100644
--- a/packages/webui-framework/tests/fixtures/raw-html-conditional/element.ts
+++ b/packages/webui-framework/tests/fixtures/raw-html-conditional/element.ts
@@ -3,10 +3,55 @@
 
 import { WebUIElement, observable } from '../../../src/index.js';
 
+interface KeyedRawItem {
+  id: string;
+  label: string;
+  rawHtml: string;
+  showRaw: boolean;
+}
+
 export class TestRawHtml extends WebUIElement {
   @observable expanded = true;
+  @observable firstRawHtml = '';
+  @observable inlineName = '';
+  @observable inlineRawHtml = '';
   @observable name = '';
   @observable rawHtml = '';
+  @observable rowsHtml = '';
+  @observable secondRawHtml = '';
+  @observable styleRule = '';
+}
+
+export class TestRawHtmlKeyedRepeat extends WebUIElement {
+  @observable items: KeyedRawItem[] = [];
+
+  reverseItems(): void {
+    this.items = this.items.map((item) => ({ ...item })).reverse();
+  }
+
+  updateItemRaw(id: string): void {
+    this.items = this.items.map((item) => (
+      item.id === id
+        ? {
+            ...item,
+            rawHtml:
+              `<strong class="raw-node raw-first" data-owner="${id}">${id} updated 1</strong>`
+              + `<u class="raw-node raw-second" data-owner="${id}">${id} updated 2</u>`,
+          }
+        : item
+    ));
+  }
+
+  updateItemRawHtml(id: string, rawHtml: string): void {
+    this.items = this.items.map((item) => (
+      item.id === id ? { ...item, rawHtml } : { ...item }
+    ));
+  }
+
+  removeItem(id: string): void {
+    this.items = this.items.filter((item) => item.id !== id);
+  }
 }
 
 TestRawHtml.define('test-raw-html');
+TestRawHtmlKeyedRepeat.define('test-raw-html-keyed-repeat');
diff --git a/packages/webui-framework/tests/fixtures/raw-html-conditional/raw-html-conditional.spec.ts b/packages/webui-framework/tests/fixtures/raw-html-conditional/raw-html-conditional.spec.ts
index eeb5a0175..4323eac4e 100644
--- a/packages/webui-framework/tests/fixtures/raw-html-conditional/raw-html-conditional.spec.ts
+++ b/packages/webui-framework/tests/fixtures/raw-html-conditional/raw-html-conditional.spec.ts
@@ -19,13 +19,393 @@ test.describe('raw HTML inside conditional', () => {
     await expect(page.locator('test-raw-html .header .name')).toHaveText('Alice');
   });
 
-  test('raw HTML body renders in its own container', async ({ page }) => {
-    const bodyHtml = await page.locator('test-raw-html .body').innerHTML();
-    expect(bodyHtml).toContain('<p>Hello</p>');
+  test('reactive raw HTML updates preserve and order sibling ranges', async ({ page }) => {
+    const body = page.locator('test-raw-html .body');
+    await expect(body.locator(':scope > .raw-initial')).toHaveText('Hello');
+
+    await page.evaluate(() => {
+      const host = document.querySelector('test-raw-html') as HTMLElement & {
+        rawHtml: string;
+      };
+      host.rawHtml = '<b class="raw-first">One</b><!--/wh--><i class="raw-second">Two</i>';
+    });
+
+    await expect(body.locator(':scope > .before')).toHaveText('Before');
+    await expect(body.locator(':scope > .raw-first')).toHaveText('One');
+    await expect(body.locator(':scope > .raw-second')).toHaveText('Two');
+    await expect(body.locator(':scope > .conditional')).toHaveText('Conditional');
+    await expect(body.locator(':scope > .after')).toHaveText('After');
+    await expect(body.locator(':scope > *')).toHaveClass([
+      'before',
+      'raw-first',
+      'raw-second',
+      'conditional',
+      'after',
+    ]);
+
+    await page.evaluate(() => {
+      const host = document.querySelector('test-raw-html') as HTMLElement & {
+        rawHtml: string;
+      };
+      host.rawHtml = '';
+    });
+    await expect(body.locator(':scope > *')).toHaveClass([
+      'before',
+      'conditional',
+      'after',
+    ]);
+
+    await page.evaluate(() => {
+      const host = document.querySelector('test-raw-html') as HTMLElement & {
+        rawHtml: string;
+      };
+      host.rawHtml = '<mark class="raw-only">Only</mark>';
+    });
+    await expect(body.locator(':scope > *')).toHaveClass([
+      'before',
+      'raw-only',
+      'conditional',
+      'after',
+    ]);
+
+    await page.evaluate(() => {
+      const host = document.querySelector('test-raw-html') as HTMLElement & {
+        rawHtml: string;
+      };
+      host.rawHtml = '<b class="raw-first">One</b><i class="raw-second">Two</i>';
+    });
+    await expect(body.locator(':scope > *')).toHaveClass([
+      'before',
+      'raw-first',
+      'raw-second',
+      'conditional',
+      'after',
+    ]);
+
+    await page.evaluate(() => {
+      const host = document.querySelector('test-raw-html') as HTMLElement & {
+        expanded: boolean;
+      };
+      host.expanded = false;
+    });
+    await expect(page.locator('test-raw-html .body')).toHaveCount(0);
+
+    await page.evaluate(() => {
+      const host = document.querySelector('test-raw-html') as HTMLElement & {
+        expanded: boolean;
+      };
+      host.expanded = true;
+    });
+    await expect(body.locator(':scope > *')).toHaveClass([
+      'before',
+      'raw-first',
+      'raw-second',
+      'conditional',
+      'after',
+    ]);
+
+    await page.evaluate(async () => {
+      const host = document.querySelector('test-raw-html') as HTMLElement & {
+        rawHtml: string;
+      };
+      host.remove();
+      await Promise.resolve();
+      host.rawHtml = '<u class="raw-reconnected">Reconnected</u>';
+      document.body.appendChild(host);
+    });
+    await expect(body.locator(':scope > *')).toHaveClass([
+      'before',
+      'raw-reconnected',
+      'conditional',
+      'after',
+    ]);
+  });
+
+  test('parses reactive raw table rows in the tbody context', async ({ page }) => {
+    const rows = page.locator('test-raw-html .rows');
+    await expect(rows.locator(':scope > tr')).toHaveClass([
+      'before-row',
+      'raw-row raw-row-initial',
+      'conditional-row',
+      'after-row',
+    ]);
+
+    await page.evaluate(() => {
+      const host = document.querySelector('test-raw-html') as HTMLElement & {
+        rowsHtml: string;
+      };
+      host.rowsHtml = [
+        '<tr class="raw-row raw-row-first"><td>First</td></tr>',
+        '<tr class="raw-row raw-row-second"><td>Second</td></tr>',
+      ].join('');
+    });
+
+    await expect(rows.locator(':scope > tr')).toHaveClass([
+      'before-row',
+      'raw-row raw-row-first',
+      'raw-row raw-row-second',
+      'conditional-row',
+      'after-row',
+    ]);
+    await expect(rows.locator(':scope > .raw-row > td')).toHaveText(['First', 'Second']);
+    expect(await rows.locator(':scope > .raw-row').evaluateAll((elements) => (
+      elements.every((element) => (
+        element instanceof HTMLTableRowElement
+        && element.firstElementChild instanceof HTMLTableCellElement
+      ))
+    ))).toBe(true);
   });
 
   test('header does not contain raw HTML body content', async ({ page }) => {
     const headerHtml = await page.locator('test-raw-html .header').innerHTML();
     expect(headerHtml).not.toContain('Hello');
   });
+
+  test('escaped text bindings stay aligned around an inline raw range', async ({ page }) => {
+    const line = page.locator('test-raw-html .inline-text');
+    await expect(line).toHaveText('Before raw After Alice');
+    await expect(line.locator(':scope > .inline-raw')).toHaveText('raw');
+
+    await page.evaluate(() => {
+      const host = document.querySelector('test-raw-html') as HTMLElement & {
+        inlineName: string;
+        inlineRawHtml: string;
+      };
+      host.inlineName = 'Bob';
+      host.inlineRawHtml = '<i class="inline-raw">updated</i>';
+    });
+
+    await expect(line).toHaveText('Before updated After Bob');
+    await expect(line.locator(':scope > .inline-raw')).toHaveText('updated');
+  });
+
+  test('updates adjacent raw ranges independently', async ({ page }) => {
+    const container = page.locator('test-raw-html .adjacent-raw');
+    await expect(container.locator(':scope > *')).toHaveClass([
+      'adjacent-first',
+      'adjacent-second',
+    ]);
+
+    await page.evaluate(() => {
+      const host = document.querySelector('test-raw-html') as HTMLElement & {
+        firstRawHtml: string;
+      };
+      host.firstRawHtml =
+        '<strong class="adjacent-first-a">First A</strong>'
+        + '<em class="adjacent-first-b">First B</em>';
+    });
+    await expect(container.locator(':scope > *')).toHaveClass([
+      'adjacent-first-a',
+      'adjacent-first-b',
+      'adjacent-second',
+    ]);
+
+    await page.evaluate(() => {
+      const host = document.querySelector('test-raw-html') as HTMLElement & {
+        secondRawHtml: string;
+      };
+      host.secondRawHtml = '';
+    });
+    await expect(container.locator(':scope > *')).toHaveClass([
+      'adjacent-first-a',
+      'adjacent-first-b',
+    ]);
+  });
+
+  test('hydrates raw CSS signals as marker-free text', async ({ page }) => {
+    const target = page.locator('test-raw-html .raw-context-target');
+    await expect(target).toHaveCSS('color', 'rgb(1, 2, 3)');
+
+    await page.evaluate(() => {
+      const host = document.querySelector('test-raw-html') as HTMLElement & {
+        styleRule: string;
+      };
+      host.styleRule = 'color: rgb(4, 5, 6);';
+    });
+    await expect(target).toHaveCSS('color', 'rgb(4, 5, 6)');
+
+    const markerText = await page.locator('test-raw-html style').textContent();
+    expect(markerText).not.toContain('<!--w');
+  });
+
+  test('client-created raw HTML uses the same sibling structure', async ({ page }) => {
+    await page.evaluate(() => {
+      const host = document.createElement('test-raw-html') as HTMLElement & {
+        expanded: boolean;
+        name: string;
+        rawHtml: string;
+      };
+      host.id = 'client-raw-html';
+      document.body.appendChild(host);
+      host.name = 'Client';
+      host.rawHtml = '<b class="raw-first">One</b><i class="raw-second">Two</i>';
+    });
+
+    const body = page.locator('#client-raw-html .body');
+    await expect(body.locator(':scope > *')).toHaveClass([
+      'before',
+      'raw-first',
+      'raw-second',
+      'conditional',
+      'after',
+    ]);
+
+    await page.evaluate(() => {
+      const host = document.querySelector('#client-raw-html') as HTMLElement & {
+        expanded: boolean;
+      };
+      host.expanded = false;
+    });
+    await expect(page.locator('#client-raw-html .body')).toHaveCount(0);
+  });
+
+  test('keyed repeat moves raw ranges by identity and removes them without ghosts', async ({
+    page,
+  }) => {
+    await page.waitForFunction(() => {
+      const element = document.querySelector('test-raw-html-keyed-repeat');
+      return element && (element as unknown as { $ready?: boolean }).$ready === true;
+    });
+
+    const host = page.locator('test-raw-html-keyed-repeat');
+    const items = host.locator('.keyed-raw-item');
+    await expect(items).toHaveCount(3);
+
+    await page.evaluate(() => {
+      const host = document.querySelector('test-raw-html-keyed-repeat') as HTMLElement & {
+        updateItemRaw(id: string): void;
+      };
+      host.updateItemRaw('b');
+    });
+    await expect(host.locator('[data-owner="b"]')).toHaveText([
+      'b updated 1',
+      'b updated 2',
+    ]);
+
+    await page.evaluate(() => {
+      const host = document.querySelector('test-raw-html-keyed-repeat') as HTMLElement & {
+        updateItemRawHtml(id: string, rawHtml: string): void;
+      };
+      host.updateItemRawHtml(
+        'b',
+        '<strong class="raw-node" data-owner="b">B updated 1</strong>'
+          + '<em class="raw-node" data-owner="b">B updated 2</em>',
+      );
+    });
+    await expect(host.locator('[data-owner="b"]')).toHaveText(['B updated 1', 'B updated 2']);
+
+    await page.evaluate(() => {
+      const host = document.querySelector('test-raw-html-keyed-repeat') as HTMLElement & {
+        reverseItems(): void;
+      };
+      const root = host.shadowRoot ?? host;
+      const snapshots = new Map<string, Node[]>();
+      root.querySelectorAll('.keyed-raw-item').forEach((item) => {
+        const owned: Node[] = [];
+        let node = item.nextSibling;
+        while (node) {
+          const data = node.nodeType === Node.COMMENT_NODE ? (node as Comment).data : '';
+          const markerDigit = data.charCodeAt(1);
+          if (data.charCodeAt(0) === 119 && markerDigit >= 48 && markerDigit <= 57) {
+            owned.push(node);
+            const endMarker = `/${data}`;
+            node = node.nextSibling;
+            while (node) {
+              owned.push(node);
+              if (node.nodeType === Node.COMMENT_NODE
+                && (node as Comment).data === endMarker) break;
+              node = node.nextSibling;
+            }
+            break;
+          }
+          node = node.nextSibling;
+        }
+        snapshots.set(item.getAttribute('data-id') ?? '', [item, ...owned]);
+      });
+      (window as unknown as { __keyedRawSnapshots?: Map<string, Node[]> })
+        .__keyedRawSnapshots = snapshots;
+      host.reverseItems();
+    });
+
+    const reorderedIds = await items.evaluateAll((elements) => (
+      elements.map((element) => element.getAttribute('data-id'))
+    ));
+    expect(reorderedIds).toEqual(['c', 'b', 'a']);
+
+    const identityById = await page.evaluate(() => {
+      const host = document.querySelector('test-raw-html-keyed-repeat');
+      const root = host?.shadowRoot ?? host;
+      const snapshots = (window as unknown as {
+        __keyedRawSnapshots?: Map<string, Node[]>;
+      }).__keyedRawSnapshots;
+      if (!root || !snapshots) return [];
+
+      return Array.from(root.querySelectorAll('.keyed-raw-item')).map((item) => {
+        const id = item.getAttribute('data-id') ?? '';
+        const original = snapshots.get(id);
+        const owned: Node[] = [];
+        let node = item.nextSibling;
+        while (node) {
+          const data = node.nodeType === Node.COMMENT_NODE ? (node as Comment).data : '';
+          const markerDigit = data.charCodeAt(1);
+          if (data.charCodeAt(0) === 119 && markerDigit >= 48 && markerDigit <= 57) {
+            owned.push(node);
+            const endMarker = `/${data}`;
+            node = node.nextSibling;
+            while (node) {
+              owned.push(node);
+              if (node.nodeType === Node.COMMENT_NODE
+                && (node as Comment).data === endMarker) break;
+              node = node.nextSibling;
+            }
+            break;
+          }
+          node = node.nextSibling;
+        }
+        return {
+          id,
+          root: original?.[0] === item,
+          owned: owned.map((node, index) => original?.[index + 1] === node),
+        };
+      });
+    });
+    expect(identityById).toEqual([
+      { id: 'c', root: true, owned: [true, true, true, true] },
+      { id: 'b', root: true, owned: [true, true, true, true] },
+      { id: 'a', root: true, owned: [true, true, true, true] },
+    ]);
+
+    await page.evaluate(() => {
+      const host = document.querySelector('test-raw-html-keyed-repeat') as HTMLElement & {
+        removeItem(id: string): void;
+      };
+      host.removeItem('b');
+    });
+
+    await expect(items).toHaveCount(2);
+    expect(await items.evaluateAll((elements) => (
+      elements.map((element) => element.getAttribute('data-id'))
+    ))).toEqual(['c', 'a']);
+    await expect(host.locator('[data-owner="b"]')).toHaveCount(0);
+    await expect(host.locator('.raw-node')).toHaveCount(4);
+
+    const markerCounts = await page.evaluate(() => {
+      const host = document.querySelector('test-raw-html-keyed-repeat');
+      const root = host?.shadowRoot ?? host;
+      if (!root) return { starts: -1, ends: -1 };
+      const walker = document.createTreeWalker(root, NodeFilter.SHOW_COMMENT);
+      let starts = 0;
+      let ends = 0;
+      while (walker.nextNode()) {
+        const data = (walker.currentNode as Comment).data;
+        const startDigit = data.charCodeAt(1);
+        const endDigit = data.charCodeAt(2);
+        if (data.charCodeAt(0) === 119 && startDigit >= 48 && startDigit <= 57) starts += 1;
+        if (data.charCodeAt(0) === 47 && data.charCodeAt(1) === 119
+          && endDigit >= 48 && endDigit <= 57) ends += 1;
+      }
+      return { starts, ends };
+    });
+    expect(markerCounts).toEqual({ starts: 2, ends: 2 });
+  });
 });
diff --git a/packages/webui-framework/tests/fixtures/raw-html-conditional/src/index.html b/packages/webui-framework/tests/fixtures/raw-html-conditional/src/index.html
index 0dfe8b4d0..87eb42113 100644
--- a/packages/webui-framework/tests/fixtures/raw-html-conditional/src/index.html
+++ b/packages/webui-framework/tests/fixtures/raw-html-conditional/src/index.html
@@ -6,5 +6,6 @@
 </head>
 <body>
   <test-raw-html></test-raw-html>
+  <test-raw-html-keyed-repeat></test-raw-html-keyed-repeat>
 </body>
 </html>
diff --git a/packages/webui-framework/tests/fixtures/raw-html-conditional/src/test-raw-html-keyed-repeat/test-raw-html-keyed-repeat.html b/packages/webui-framework/tests/fixtures/raw-html-conditional/src/test-raw-html-keyed-repeat/test-raw-html-keyed-repeat.html
new file mode 100644
index 000000000..96157191c
--- /dev/null
+++ b/packages/webui-framework/tests/fixtures/raw-html-conditional/src/test-raw-html-keyed-repeat/test-raw-html-keyed-repeat.html
@@ -0,0 +1,7 @@
+<for each="item in items">
+  <article class="keyed-raw-item" key="{{item.id}}" data-id="{{item.id}}">
+    <span class="item-before">{{item.label}} before</span>
+    <span class="item-after">after</span>
+  </article>
+  <if condition="item.showRaw">{{{item.rawHtml}}}</if>
+</for>
diff --git a/packages/webui-framework/tests/fixtures/raw-html-conditional/src/test-raw-html/test-raw-html.html b/packages/webui-framework/tests/fixtures/raw-html-conditional/src/test-raw-html/test-raw-html.html
index 426d5c9c0..4e13a609b 100644
--- a/packages/webui-framework/tests/fixtures/raw-html-conditional/src/test-raw-html/test-raw-html.html
+++ b/packages/webui-framework/tests/fixtures/raw-html-conditional/src/test-raw-html/test-raw-html.html
@@ -1,4 +1,25 @@
 <if condition="expanded">
+  <style>.raw-context-target { /*{{{styleRule}}}*/ }</style>
   <div class="header"><strong class="name">{{name}}</strong></div>
-  <div class="body">{{{rawHtml}}}</div>
+  <span class="raw-context-target">Styled</span>
+  <div class="body">
+    <span class="before">Before</span>
+    {{{rawHtml}}}
+    <if condition="expanded">
+      <span class="conditional">Conditional</span>
+    </if>
+    <span class="after">After</span>
+  </div>
+  <p class="inline-text">Before {{{inlineRawHtml}}} After {{inlineName}}</p>
+  <div class="adjacent-raw">{{{firstRawHtml}}}{{{secondRawHtml}}}</div>
+  <table>
+    <tbody class="rows">
+      <tr class="before-row"><td>Before row</td></tr>
+      {{{rowsHtml}}}
+      <if condition="expanded">
+        <tr class="conditional-row"><td>Conditional row</td></tr>
+      </if>
+      <tr class="after-row"><td>After row</td></tr>
+    </tbody>
+  </table>
 </if>
diff --git a/packages/webui-framework/tests/fixtures/raw-html-conditional/state.json b/packages/webui-framework/tests/fixtures/raw-html-conditional/state.json
index 87381f380..6cd26319d 100644
--- a/packages/webui-framework/tests/fixtures/raw-html-conditional/state.json
+++ b/packages/webui-framework/tests/fixtures/raw-html-conditional/state.json
@@ -1,5 +1,31 @@
 {
   "expanded": true,
+  "firstRawHtml": "<b class=\"adjacent-first\">First</b>",
+  "inlineName": "Alice",
+  "inlineRawHtml": "<b class=\"inline-raw\">raw</b>",
   "name": "Alice",
-  "rawHtml": "<p>Hello</p>"
+  "rawHtml": "<p class=\"raw-initial\">Hello</p>",
+  "rowsHtml": "<tr class=\"raw-row raw-row-initial\"><td>Initial row</td></tr>",
+  "secondRawHtml": "<i class=\"adjacent-second\">Second</i>",
+  "styleRule": "color: rgb(1, 2, 3);",
+  "items": [
+    {
+      "id": "a",
+      "label": "A",
+      "rawHtml": "<b class=\"raw-node raw-first\" data-owner=\"a\">A1</b><i class=\"raw-node raw-second\" data-owner=\"a\">A2</i>",
+      "showRaw": true
+    },
+    {
+      "id": "b",
+      "label": "B",
+      "rawHtml": "<b class=\"raw-node raw-first\" data-owner=\"b\">B1</b><i class=\"raw-node raw-second\" data-owner=\"b\">B2</i>",
+      "showRaw": true
+    },
+    {
+      "id": "c",
+      "label": "C",
+      "rawHtml": "<b class=\"raw-node raw-first\" data-owner=\"c\">C1</b><i class=\"raw-node raw-second\" data-owner=\"c\">C2</i>",
+      "showRaw": true
+    }
+  ]
 }
diff --git a/packages/webui-framework/tests/fixtures/raw-html-light/element.ts b/packages/webui-framework/tests/fixtures/raw-html-light/element.ts
new file mode 100644
index 000000000..9fbeea314
--- /dev/null
+++ b/packages/webui-framework/tests/fixtures/raw-html-light/element.ts
@@ -0,0 +1,12 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { WebUIElement, observable } from '../../../src/index.js';
+
+export class TestRawHtmlLight extends WebUIElement {
+  @observable rawHtml = '';
+  @observable rowsHtml = '';
+  @observable showConditional = true;
+}
+
+TestRawHtmlLight.define('test-raw-html-light');
diff --git a/packages/webui-framework/tests/fixtures/raw-html-light/raw-html-light.spec.ts b/packages/webui-framework/tests/fixtures/raw-html-light/raw-html-light.spec.ts
new file mode 100644
index 000000000..03d1db139
--- /dev/null
+++ b/packages/webui-framework/tests/fixtures/raw-html-light/raw-html-light.spec.ts
@@ -0,0 +1,119 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { expect, test } from '@playwright/test';
+
+test('light DOM raw updates preserve static and conditional siblings', async ({ page }) => {
+  await page.goto('/raw-html-light/fixture.html');
+  await page.waitForFunction(() => {
+    const element = document.querySelector('test-raw-html-light');
+    return element && (element as unknown as { $ready?: boolean }).$ready === true;
+  });
+
+  const host = page.locator('test-raw-html-light');
+  expect(await host.evaluate((element) => element.shadowRoot === null)).toBe(true);
+
+  const body = host.locator('.body');
+  await expect(body.locator(':scope > *')).toHaveClass([
+    'before',
+    'raw-initial',
+    'conditional',
+    'after',
+  ]);
+
+  await page.evaluate(() => {
+    const host = document.querySelector('test-raw-html-light') as HTMLElement & {
+      rawHtml: string;
+    };
+    host.rawHtml = '<b class="raw-first">One</b><i class="raw-second">Two</i>';
+  });
+  await expect(body.locator(':scope > *')).toHaveClass([
+    'before',
+    'raw-first',
+    'raw-second',
+    'conditional',
+    'after',
+  ]);
+
+  await page.evaluate(() => {
+    const host = document.querySelector('test-raw-html-light') as HTMLElement & {
+      rawHtml: string;
+    };
+    host.rawHtml = '';
+  });
+  await expect(body.locator(':scope > *')).toHaveClass([
+    'before',
+    'conditional',
+    'after',
+  ]);
+
+  await page.evaluate(() => {
+    const host = document.querySelector('test-raw-html-light') as HTMLElement & {
+      rawHtml: string;
+    };
+    host.rawHtml = '<strong class="raw-restored">Restored</strong>';
+  });
+  await expect(body.locator(':scope > *')).toHaveClass([
+    'before',
+    'raw-restored',
+    'conditional',
+    'after',
+  ]);
+
+  await page.evaluate(() => {
+    const host = document.querySelector('test-raw-html-light') as HTMLElement & {
+      showConditional: boolean;
+    };
+    host.showConditional = false;
+  });
+  await expect(body.locator(':scope > *')).toHaveClass([
+    'before',
+    'raw-restored',
+    'after',
+  ]);
+
+  await page.evaluate(() => {
+    const host = document.querySelector('test-raw-html-light') as HTMLElement & {
+      showConditional: boolean;
+    };
+    host.showConditional = true;
+  });
+  await expect(body.locator(':scope > *')).toHaveClass([
+    'before',
+    'raw-restored',
+    'conditional',
+    'after',
+  ]);
+});
+
+test('raw HTML parses in the live table context', async ({ page }) => {
+  await page.goto('/raw-html-light/fixture.html');
+  await page.waitForFunction(() => {
+    const element = document.querySelector('test-raw-html-light');
+    return element && (element as unknown as { $ready?: boolean }).$ready === true;
+  });
+
+  const rows = page.locator('test-raw-html-light .rows');
+  await expect(rows.locator(':scope > tr')).toHaveClass([
+    'row-before',
+    'raw-row-initial',
+    'row-after',
+  ]);
+
+  await page.evaluate(() => {
+    const host = document.querySelector('test-raw-html-light') as HTMLElement & {
+      rowsHtml: string;
+    };
+    host.rowsHtml =
+      '<tr class="raw-row-a"><td>A</td></tr><tr class="raw-row-b"><td>B</td></tr>';
+  });
+
+  await expect(rows.locator(':scope > tr')).toHaveClass([
+    'row-before',
+    'raw-row-a',
+    'raw-row-b',
+    'row-after',
+  ]);
+  await expect(rows.locator(':scope > tr').nth(1).locator('td')).toHaveText('A');
+  await expect(rows.locator(':scope > tr').nth(2).locator('td')).toHaveText('B');
+});
diff --git a/packages/webui-framework/tests/fixtures/raw-html-light/src/index.html b/packages/webui-framework/tests/fixtures/raw-html-light/src/index.html
new file mode 100644
index 000000000..fdf500882
--- /dev/null
+++ b/packages/webui-framework/tests/fixtures/raw-html-light/src/index.html
@@ -0,0 +1,10 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Raw HTML Light DOM Fixture</title>
+</head>
+<body>
+  <test-raw-html-light></test-raw-html-light>
+</body>
+</html>
diff --git a/packages/webui-framework/tests/fixtures/raw-html-light/src/test-raw-html-light/test-raw-html-light.html b/packages/webui-framework/tests/fixtures/raw-html-light/src/test-raw-html-light/test-raw-html-light.html
new file mode 100644
index 000000000..791c0110c
--- /dev/null
+++ b/packages/webui-framework/tests/fixtures/raw-html-light/src/test-raw-html-light/test-raw-html-light.html
@@ -0,0 +1,15 @@
+<div class="body">
+  <span class="before">Before</span>
+  {{{rawHtml}}}
+  <if condition="showConditional">
+    <span class="conditional">Conditional</span>
+  </if>
+  <span class="after">After</span>
+</div>
+<table>
+  <tbody class="rows">
+    <tr class="row-before"><td>Before row</td></tr>
+    {{{rowsHtml}}}
+    <tr class="row-after"><td>After row</td></tr>
+  </tbody>
+</table>
diff --git a/packages/webui-framework/tests/fixtures/raw-html-light/state.json b/packages/webui-framework/tests/fixtures/raw-html-light/state.json
new file mode 100644
index 000000000..62a807813
--- /dev/null
+++ b/packages/webui-framework/tests/fixtures/raw-html-light/state.json
@@ -0,0 +1,5 @@
+{
+  "rawHtml": "<em class=\"raw-initial\">Initial</em>",
+  "rowsHtml": "<tr class=\"raw-row-initial\"><td>Initial row</td></tr>",
+  "showConditional": true
+}
diff --git a/packages/webui-framework/tests/fixtures/raw-html-light/webui.config.json b/packages/webui-framework/tests/fixtures/raw-html-light/webui.config.json
new file mode 100644
index 000000000..b5b9610e2
--- /dev/null
+++ b/packages/webui-framework/tests/fixtures/raw-html-light/webui.config.json
@@ -0,0 +1,3 @@
+{
+  "dom": "light"
+}

From 7cb5f295f8134a977916f138761c102b31dc2716 Mon Sep 17 00:00:00 2001
From: Mohamed Mansour <mmansour@microsoft.com>
Date: Sat, 22 Aug 2026 08:08:48 -0700
Subject: [PATCH 2/4] fix: pass raw state through binding hooks

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 0807f5af-f9d9-45ad-b7d2-907084c53ea0
---
 DESIGN.md                                  | 23 ++-----
 crates/webui-handler/src/lib.rs            | 12 +---
 crates/webui-handler/src/plugin/fast.rs    |  4 +-
 crates/webui-handler/src/plugin/fast_v2.rs | 34 +++++++---
 crates/webui-handler/src/plugin/fast_v3.rs | 76 ++++++++++++++--------
 crates/webui-handler/src/plugin/mod.rs     | 66 +++++++++++--------
 crates/webui-handler/src/plugin/webui.rs   | 46 +++++++------
 docs/guide/concepts/plugins/index.md       | 22 +++----
 8 files changed, 158 insertions(+), 125 deletions(-)

diff --git a/DESIGN.md b/DESIGN.md
index 4d8fe04c1..d2993fd35 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -1056,27 +1056,15 @@ pub trait HandlerPlugin: Send {
     fn on_binding_start(
         &mut self,
         name: &str,
+        raw: bool,
         writer: &mut dyn ResponseWriter,
     ) -> Result<()>;
     fn on_binding_end(
         &mut self,
         name: &str,
+        raw: bool,
         writer: &mut dyn ResponseWriter,
     ) -> Result<()>;
-    fn on_raw_binding_start(
-        &mut self,
-        name: &str,
-        writer: &mut dyn ResponseWriter,
-    ) -> Result<()> {
-        self.on_binding_start(name, writer)
-    }
-    fn on_raw_binding_end(
-        &mut self,
-        name: &str,
-        writer: &mut dyn ResponseWriter,
-    ) -> Result<()> {
-        self.on_binding_end(name, writer)
-    }
     fn on_repeat_item_start(&mut self, index: usize, writer: &mut dyn ResponseWriter) -> Result<()>;
     fn on_repeat_item_end(&mut self, index: usize, writer: &mut dyn ResponseWriter) -> Result<()>;
     fn on_element_data(&mut self, data: &[u8], writer: &mut dyn ResponseWriter) -> Result<()>;
@@ -1105,10 +1093,9 @@ retain thread-affine state such as `Rc`; use owned state, `Arc`, or another
 sendable handle instead.
 
 **Hook invocation points:**
-- **Signal**: escaped and raw-text signals call `on_binding_start` before and
-  `on_binding_end` after; authored raw HTML range signals call
-  `on_raw_binding_start` / `on_raw_binding_end`. The raw hooks default to the
-  escaped hooks, preserving existing plugin behavior and source compatibility.
+- **Signal**: every signal calls `on_binding_start/end`. The `raw` argument is
+  `true` only for authored raw HTML signals that own replaceable sibling ranges;
+  escaped signals and marker-free signals in HTML raw-text contexts pass `false`.
 - **For loop**: `on_binding_start/end` around entire loop; `on_repeat_item_start/end` + `push_scope/pop_scope` per item
 - **If condition**: `on_binding_start/end` around condition; `push_scope/pop_scope` if condition is true
 - **Component**: `push_scope/pop_scope` around component body
diff --git a/crates/webui-handler/src/lib.rs b/crates/webui-handler/src/lib.rs
index 217299ab9..8da36d2b5 100644
--- a/crates/webui-handler/src/lib.rs
+++ b/crates/webui-handler/src/lib.rs
@@ -1957,11 +1957,7 @@ impl WebUIHandler {
         context: &mut WebUIProcessContext,
     ) -> Result<()> {
         if let Some(p) = &mut context.plugin {
-            if owns_html_range {
-                p.on_raw_binding_start(&signal.value, context.writer)?;
-            } else {
-                p.on_binding_start(&signal.value, context.writer)?;
-            }
+            p.on_binding_start(&signal.value, owns_html_range, context.writer)?;
         }
 
         if let Some(value) = self.resolve_value(&signal.value, context) {
@@ -1969,11 +1965,7 @@ impl WebUIHandler {
         }
 
         if let Some(p) = &mut context.plugin {
-            if owns_html_range {
-                p.on_raw_binding_end(&signal.value, context.writer)?;
-            } else {
-                p.on_binding_end(&signal.value, context.writer)?;
-            }
+            p.on_binding_end(&signal.value, owns_html_range, context.writer)?;
         }
         Ok(())
     }
diff --git a/crates/webui-handler/src/plugin/fast.rs b/crates/webui-handler/src/plugin/fast.rs
index 9122205f4..25463b9e3 100644
--- a/crates/webui-handler/src/plugin/fast.rs
+++ b/crates/webui-handler/src/plugin/fast.rs
@@ -89,7 +89,9 @@ mod tests {
         let mut plugin = FastHydrationPlugin::new();
         plugin.push_scope();
         let mut writer = TestWriter::new();
-        assert!(plugin.on_binding_start("userName", &mut writer).is_ok());
+        assert!(plugin
+            .on_binding_start("userName", false, &mut writer)
+            .is_ok());
         assert_eq!(writer.output, "<!--fe-b$$start$$0$$userName$$fe-b-->");
     }
 
diff --git a/crates/webui-handler/src/plugin/fast_v2.rs b/crates/webui-handler/src/plugin/fast_v2.rs
index d4269c369..aa6303281 100644
--- a/crates/webui-handler/src/plugin/fast_v2.rs
+++ b/crates/webui-handler/src/plugin/fast_v2.rs
@@ -132,7 +132,12 @@ impl HandlerPlugin for FastV2HydrationPlugin {
         self.scopes.pop();
     }
 
-    fn on_binding_start(&mut self, name: &str, writer: &mut dyn ResponseWriter) -> Result<()> {
+    fn on_binding_start(
+        &mut self,
+        name: &str,
+        _raw: bool,
+        writer: &mut dyn ResponseWriter,
+    ) -> Result<()> {
         if !self.is_active() {
             return Ok(());
         }
@@ -142,7 +147,12 @@ impl HandlerPlugin for FastV2HydrationPlugin {
         writer.write(&self.buffer)
     }
 
-    fn on_binding_end(&mut self, name: &str, writer: &mut dyn ResponseWriter) -> Result<()> {
+    fn on_binding_end(
+        &mut self,
+        name: &str,
+        _raw: bool,
+        writer: &mut dyn ResponseWriter,
+    ) -> Result<()> {
         if !self.is_active() {
             return Ok(());
         }
@@ -232,8 +242,12 @@ mod tests {
         let mut plugin = FastV2HydrationPlugin::new();
         plugin.push_scope();
         let mut writer = TestWriter::new();
-        plugin.on_binding_start("userName", &mut writer).unwrap();
-        plugin.on_binding_end("userName", &mut writer).unwrap();
+        plugin
+            .on_binding_start("userName", false, &mut writer)
+            .unwrap();
+        plugin
+            .on_binding_end("userName", false, &mut writer)
+            .unwrap();
         assert_eq!(
             writer.output,
             "<!--fe-b$$start$$0$$userName$$fe-b--><!--fe-b$$end$$0$$userName$$fe-b-->"
@@ -245,10 +259,10 @@ mod tests {
         let mut plugin = FastV2HydrationPlugin::new();
         plugin.push_scope();
         let mut writer = TestWriter::new();
-        plugin.on_binding_start("a", &mut writer).unwrap();
-        plugin.on_binding_end("a", &mut writer).unwrap();
+        plugin.on_binding_start("a", false, &mut writer).unwrap();
+        plugin.on_binding_end("a", false, &mut writer).unwrap();
         writer.output.clear();
-        plugin.on_binding_start("b", &mut writer).unwrap();
+        plugin.on_binding_start("b", false, &mut writer).unwrap();
         assert_eq!(writer.output, "<!--fe-b$$start$$1$$b$$fe-b-->");
     }
 
@@ -291,7 +305,7 @@ mod tests {
         plugin.on_element_data(&three, &mut writer).unwrap();
 
         writer.output.clear();
-        plugin.on_binding_start("next", &mut writer).unwrap();
+        plugin.on_binding_start("next", false, &mut writer).unwrap();
         assert_eq!(writer.output, "<!--fe-b$$start$$3$$next$$fe-b-->");
     }
 
@@ -299,8 +313,8 @@ mod tests {
     fn test_fast_v2_root_scope_disabled() {
         let mut plugin = FastV2HydrationPlugin::new();
         let mut writer = TestWriter::new();
-        plugin.on_binding_start("x", &mut writer).unwrap();
-        plugin.on_binding_end("x", &mut writer).unwrap();
+        plugin.on_binding_start("x", false, &mut writer).unwrap();
+        plugin.on_binding_end("x", false, &mut writer).unwrap();
         plugin.on_repeat_item_start(0, &mut writer).unwrap();
         plugin.on_repeat_item_end(0, &mut writer).unwrap();
         let data = 3u32.to_le_bytes();
diff --git a/crates/webui-handler/src/plugin/fast_v3.rs b/crates/webui-handler/src/plugin/fast_v3.rs
index ee5df30a9..d34b29d3c 100644
--- a/crates/webui-handler/src/plugin/fast_v3.rs
+++ b/crates/webui-handler/src/plugin/fast_v3.rs
@@ -107,7 +107,12 @@ impl HandlerPlugin for FastV3HydrationPlugin {
         self.scopes.pop();
     }
 
-    fn on_binding_start(&mut self, _name: &str, writer: &mut dyn ResponseWriter) -> Result<()> {
+    fn on_binding_start(
+        &mut self,
+        _name: &str,
+        _raw: bool,
+        writer: &mut dyn ResponseWriter,
+    ) -> Result<()> {
         if !self.is_active() {
             return Ok(());
         }
@@ -115,7 +120,12 @@ impl HandlerPlugin for FastV3HydrationPlugin {
         writer.write(BINDING_START_MARKER)
     }
 
-    fn on_binding_end(&mut self, _name: &str, writer: &mut dyn ResponseWriter) -> Result<()> {
+    fn on_binding_end(
+        &mut self,
+        _name: &str,
+        _raw: bool,
+        writer: &mut dyn ResponseWriter,
+    ) -> Result<()> {
         if !self.is_active() {
             return Ok(());
         }
@@ -201,8 +211,8 @@ mod tests {
         let mut plugin = FastV3HydrationPlugin::new();
         let mut writer = TestWriter::new();
         // Root scope should not emit markers
-        plugin.on_binding_start("x", &mut writer).unwrap();
-        plugin.on_binding_end("x", &mut writer).unwrap();
+        plugin.on_binding_start("x", false, &mut writer).unwrap();
+        plugin.on_binding_end("x", false, &mut writer).unwrap();
         plugin.on_repeat_item_start(0, &mut writer).unwrap();
         plugin.on_repeat_item_end(0, &mut writer).unwrap();
         let data = 3u32.to_le_bytes();
@@ -215,7 +225,9 @@ mod tests {
         let mut plugin = FastV3HydrationPlugin::new();
         plugin.push_scope();
         let mut writer = TestWriter::new();
-        plugin.on_binding_start("userName", &mut writer).unwrap();
+        plugin
+            .on_binding_start("userName", false, &mut writer)
+            .unwrap();
         assert_eq!(writer.output, "<!--fe:b-->");
     }
 
@@ -224,9 +236,13 @@ mod tests {
         let mut plugin = FastV3HydrationPlugin::new();
         plugin.push_scope();
         let mut writer = TestWriter::new();
-        plugin.on_binding_start("userName", &mut writer).unwrap();
+        plugin
+            .on_binding_start("userName", false, &mut writer)
+            .unwrap();
         writer.output.clear();
-        plugin.on_binding_end("userName", &mut writer).unwrap();
+        plugin
+            .on_binding_end("userName", false, &mut writer)
+            .unwrap();
         assert_eq!(writer.output, "<!--fe:/b-->");
     }
 
@@ -235,10 +251,10 @@ mod tests {
         let mut plugin = FastV3HydrationPlugin::new();
         plugin.push_scope();
         let mut writer = TestWriter::new();
-        plugin.on_binding_start("a", &mut writer).unwrap();
-        plugin.on_binding_end("a", &mut writer).unwrap();
+        plugin.on_binding_start("a", false, &mut writer).unwrap();
+        plugin.on_binding_end("a", false, &mut writer).unwrap();
         writer.output.clear();
-        plugin.on_binding_start("b", &mut writer).unwrap();
+        plugin.on_binding_start("b", false, &mut writer).unwrap();
         assert_eq!(writer.output, "<!--fe:b-->");
     }
 
@@ -249,18 +265,18 @@ mod tests {
         // Push first active scope (root is disabled)
         plugin.push_scope();
         // Active scope emits compact markers.
-        plugin.on_binding_start("a", &mut writer).unwrap();
-        plugin.on_binding_end("a", &mut writer).unwrap();
+        plugin.on_binding_start("a", false, &mut writer).unwrap();
+        plugin.on_binding_end("a", false, &mut writer).unwrap();
         // Push child scope: markers are still emitted.
         plugin.push_scope();
         writer.output.clear();
-        plugin.on_binding_start("b", &mut writer).unwrap();
+        plugin.on_binding_start("b", false, &mut writer).unwrap();
         assert_eq!(writer.output, "<!--fe:b-->");
-        plugin.on_binding_end("b", &mut writer).unwrap();
+        plugin.on_binding_end("b", false, &mut writer).unwrap();
         // Pop child scope: parent remains active.
         plugin.pop_scope();
         writer.output.clear();
-        plugin.on_binding_start("c", &mut writer).unwrap();
+        plugin.on_binding_start("c", false, &mut writer).unwrap();
         assert_eq!(writer.output, "<!--fe:b-->");
     }
 
@@ -317,7 +333,7 @@ mod tests {
 
         // Next binding still emits the compact sequential marker.
         writer.output.clear();
-        plugin.on_binding_start("x", &mut writer).unwrap();
+        plugin.on_binding_start("x", false, &mut writer).unwrap();
         assert_eq!(writer.output, "<!--fe:b-->");
     }
 
@@ -328,26 +344,32 @@ mod tests {
         // Push first active scope (root is disabled)
         plugin.push_scope();
         // Active scope emits binding markers.
-        plugin.on_binding_start("root", &mut writer).unwrap();
-        plugin.on_binding_end("root", &mut writer).unwrap();
+        plugin.on_binding_start("root", false, &mut writer).unwrap();
+        plugin.on_binding_end("root", false, &mut writer).unwrap();
         // Component scope
         plugin.push_scope();
         // For-loop binding in component emits compact markers.
         writer.output.clear();
-        plugin.on_binding_start("for-1", &mut writer).unwrap();
+        plugin
+            .on_binding_start("for-1", false, &mut writer)
+            .unwrap();
         assert_eq!(writer.output, "<!--fe:b-->");
         // For-loop item scope
         plugin.push_scope();
         writer.output.clear();
-        plugin.on_binding_start("signal", &mut writer).unwrap();
+        plugin
+            .on_binding_start("signal", false, &mut writer)
+            .unwrap();
         assert_eq!(writer.output, "<!--fe:b-->");
-        plugin.on_binding_end("signal", &mut writer).unwrap();
+        plugin.on_binding_end("signal", false, &mut writer).unwrap();
         plugin.pop_scope();
-        plugin.on_binding_end("for-1", &mut writer).unwrap();
+        plugin.on_binding_end("for-1", false, &mut writer).unwrap();
         plugin.pop_scope();
         // Back to first active scope: compact markers are still emitted.
         writer.output.clear();
-        plugin.on_binding_start("root2", &mut writer).unwrap();
+        plugin
+            .on_binding_start("root2", false, &mut writer)
+            .unwrap();
         assert_eq!(writer.output, "<!--fe:b-->");
     }
 
@@ -977,10 +999,10 @@ mod tests {
             plugin_bind.push_scope();
             let mut writer_bind = TestWriter::new();
             plugin_bind
-                .on_binding_start("items", &mut writer_bind)
+                .on_binding_start("items", false, &mut writer_bind)
                 .unwrap();
             plugin_bind
-                .on_binding_end("items", &mut writer_bind)
+                .on_binding_end("items", false, &mut writer_bind)
                 .unwrap();
 
             assert_eq!(
@@ -1002,10 +1024,10 @@ mod tests {
             plugin_bind.push_scope();
             let mut writer_bind = TestWriter::new();
             plugin_bind
-                .on_binding_start("visible", &mut writer_bind)
+                .on_binding_start("visible", false, &mut writer_bind)
                 .unwrap();
             plugin_bind
-                .on_binding_end("visible", &mut writer_bind)
+                .on_binding_end("visible", false, &mut writer_bind)
                 .unwrap();
 
             assert_eq!(
diff --git a/crates/webui-handler/src/plugin/mod.rs b/crates/webui-handler/src/plugin/mod.rs
index 4d474bb77..e3d73b5da 100644
--- a/crates/webui-handler/src/plugin/mod.rs
+++ b/crates/webui-handler/src/plugin/mod.rs
@@ -73,50 +73,48 @@ pub trait HandlerPlugin: Send {
     /// Exit the current scope, restoring the parent scope state.
     fn pop_scope(&mut self);
 
-    /// Called before rendering an escaped signal binding.
-    fn on_binding_start(&mut self, name: &str, writer: &mut dyn ResponseWriter) -> Result<()>;
-
-    /// Called after rendering an escaped signal binding.
-    fn on_binding_end(&mut self, name: &str, writer: &mut dyn ResponseWriter) -> Result<()>;
-
-    /// Called before rendering a signal that owns a raw HTML range.
+    /// Called before rendering a signal binding.
     ///
-    /// Defaults to the ordinary binding hook so existing plugins remain source
-    /// compatible and keep their established marker behavior.
-    fn on_raw_binding_start(&mut self, name: &str, writer: &mut dyn ResponseWriter) -> Result<()> {
-        self.on_binding_start(name, writer)
-    }
+    /// `raw` is true when the signal owns a replaceable HTML sibling range.
+    fn on_binding_start(
+        &mut self,
+        name: &str,
+        raw: bool,
+        writer: &mut dyn ResponseWriter,
+    ) -> Result<()>;
 
-    /// Called after rendering a signal that owns a raw HTML range.
+    /// Called after rendering a signal binding.
     ///
-    /// Defaults to the ordinary binding hook so existing plugins remain source
-    /// compatible and keep their established marker behavior.
-    fn on_raw_binding_end(&mut self, name: &str, writer: &mut dyn ResponseWriter) -> Result<()> {
-        self.on_binding_end(name, writer)
-    }
+    /// `raw` is true when the signal owns a replaceable HTML sibling range.
+    fn on_binding_end(
+        &mut self,
+        name: &str,
+        raw: bool,
+        writer: &mut dyn ResponseWriter,
+    ) -> Result<()>;
 
     /// Called before rendering a for-loop block.
     /// Defaults to [`on_binding_start`](HandlerPlugin::on_binding_start).
     fn on_for_start(&mut self, name: &str, writer: &mut dyn ResponseWriter) -> Result<()> {
-        self.on_binding_start(name, writer)
+        self.on_binding_start(name, false, writer)
     }
 
     /// Called after rendering a for-loop block.
     /// Defaults to [`on_binding_end`](HandlerPlugin::on_binding_end).
     fn on_for_end(&mut self, name: &str, writer: &mut dyn ResponseWriter) -> Result<()> {
-        self.on_binding_end(name, writer)
+        self.on_binding_end(name, false, writer)
     }
 
     /// Called before rendering an if-condition block.
     /// Defaults to [`on_binding_start`](HandlerPlugin::on_binding_start).
     fn on_if_start(&mut self, name: &str, writer: &mut dyn ResponseWriter) -> Result<()> {
-        self.on_binding_start(name, writer)
+        self.on_binding_start(name, false, writer)
     }
 
     /// Called after rendering an if-condition block.
     /// Defaults to [`on_binding_end`](HandlerPlugin::on_binding_end).
     fn on_if_end(&mut self, name: &str, writer: &mut dyn ResponseWriter) -> Result<()> {
-        self.on_binding_end(name, writer)
+        self.on_binding_end(name, false, writer)
     }
 
     /// Called before rendering a repeat item in a for loop.
@@ -281,6 +279,7 @@ mod tests {
     struct SendOnlyPlugin {
         scope_depth: Cell<usize>,
         binding_calls: Cell<usize>,
+        raw_binding_calls: Cell<usize>,
     }
 
     struct TestWriter;
@@ -309,16 +308,30 @@ mod tests {
         fn on_binding_start(
             &mut self,
             _name: &str,
+            raw: bool,
             _writer: &mut dyn ResponseWriter,
         ) -> Result<()> {
             self.binding_calls
                 .set(self.binding_calls.get().saturating_add(1));
+            if raw {
+                self.raw_binding_calls
+                    .set(self.raw_binding_calls.get().saturating_add(1));
+            }
             Ok(())
         }
 
-        fn on_binding_end(&mut self, _name: &str, _writer: &mut dyn ResponseWriter) -> Result<()> {
+        fn on_binding_end(
+            &mut self,
+            _name: &str,
+            raw: bool,
+            _writer: &mut dyn ResponseWriter,
+        ) -> Result<()> {
             self.binding_calls
                 .set(self.binding_calls.get().saturating_add(1));
+            if raw {
+                self.raw_binding_calls
+                    .set(self.raw_binding_calls.get().saturating_add(1));
+            }
             Ok(())
         }
 
@@ -357,17 +370,18 @@ mod tests {
     }
 
     #[test]
-    fn raw_hooks_default_to_existing_binding_hooks() {
+    fn binding_hooks_receive_raw_range_flag() {
         let mut plugin = SendOnlyPlugin::default();
         let mut writer = TestWriter;
 
         plugin
-            .on_raw_binding_start("trusted_html", &mut writer)
+            .on_binding_start("trusted_html", true, &mut writer)
             .unwrap();
         plugin
-            .on_raw_binding_end("trusted_html", &mut writer)
+            .on_binding_end("trusted_html", true, &mut writer)
             .unwrap();
 
         assert_eq!(plugin.binding_calls.get(), 2);
+        assert_eq!(plugin.raw_binding_calls.get(), 2);
     }
 }
diff --git a/crates/webui-handler/src/plugin/webui.rs b/crates/webui-handler/src/plugin/webui.rs
index b742b628a..6da90d6c2 100644
--- a/crates/webui-handler/src/plugin/webui.rs
+++ b/crates/webui-handler/src/plugin/webui.rs
@@ -90,21 +90,29 @@ impl HandlerPlugin for WebUIHydrationPlugin {
 
     fn pop_scope(&mut self) {}
 
-    fn on_binding_start(&mut self, _name: &str, _writer: &mut dyn ResponseWriter) -> Result<()> {
-        Ok(())
-    }
-
-    fn on_binding_end(&mut self, _name: &str, _writer: &mut dyn ResponseWriter) -> Result<()> {
-        Ok(())
-    }
-
-    fn on_raw_binding_start(&mut self, _name: &str, writer: &mut dyn ResponseWriter) -> Result<()> {
-        write_raw_marker(&mut self.raw_marker, writer, self.raw_index, false)
+    fn on_binding_start(
+        &mut self,
+        _name: &str,
+        raw: bool,
+        writer: &mut dyn ResponseWriter,
+    ) -> Result<()> {
+        if raw {
+            write_raw_marker(&mut self.raw_marker, writer, self.raw_index, false)
+        } else {
+            Ok(())
+        }
     }
 
-    fn on_raw_binding_end(&mut self, _name: &str, writer: &mut dyn ResponseWriter) -> Result<()> {
-        write_raw_marker(&mut self.raw_marker, writer, self.raw_index, true)?;
-        self.raw_index += 1;
+    fn on_binding_end(
+        &mut self,
+        _name: &str,
+        raw: bool,
+        writer: &mut dyn ResponseWriter,
+    ) -> Result<()> {
+        if raw {
+            write_raw_marker(&mut self.raw_marker, writer, self.raw_index, true)?;
+            self.raw_index += 1;
+        }
         Ok(())
     }
 
@@ -356,8 +364,8 @@ mod tests {
     fn test_signal_binding_emits_no_output() {
         let mut plugin = WebUIHydrationPlugin::new();
         let mut writer = TestWriter::new();
-        plugin.on_binding_start("x", &mut writer).unwrap();
-        plugin.on_binding_end("x", &mut writer).unwrap();
+        plugin.on_binding_start("x", false, &mut writer).unwrap();
+        plugin.on_binding_end("x", false, &mut writer).unwrap();
         assert_eq!(
             writer.output, "",
             "signal binding hooks must not emit output"
@@ -368,9 +376,9 @@ mod tests {
     fn test_raw_signal_binding_emits_range_markers() {
         let mut plugin = WebUIHydrationPlugin::new();
         let mut writer = TestWriter::new();
-        plugin.on_raw_binding_start("html", &mut writer).unwrap();
+        plugin.on_binding_start("html", true, &mut writer).unwrap();
         writer.write("<b>trusted</b>").unwrap();
-        plugin.on_raw_binding_end("html", &mut writer).unwrap();
+        plugin.on_binding_end("html", true, &mut writer).unwrap();
         assert_eq!(writer.output, "<!--w0--><b>trusted</b><!--/w0-->");
     }
 
@@ -493,9 +501,9 @@ mod tests {
         // Simulate a component with a signal, repeat, and conditional.
         plugin.push_scope();
         // Signal binding — no markers
-        plugin.on_binding_start("a", &mut writer).unwrap();
+        plugin.on_binding_start("a", false, &mut writer).unwrap();
         writer.write("hello").unwrap();
-        plugin.on_binding_end("a", &mut writer).unwrap();
+        plugin.on_binding_end("a", false, &mut writer).unwrap();
         // For-loop — markers
         plugin.on_for_start("list", &mut writer).unwrap();
         plugin.on_repeat_item_start(0, &mut writer).unwrap();
diff --git a/docs/guide/concepts/plugins/index.md b/docs/guide/concepts/plugins/index.md
index f76f5e121..23fa260f4 100644
--- a/docs/guide/concepts/plugins/index.md
+++ b/docs/guide/concepts/plugins/index.md
@@ -148,26 +148,20 @@ pub trait HandlerPlugin: Send {
     /// Leave the current scope.
     fn pop_scope(&mut self);
 
-    /// Called before/after an escaped or raw-text signal binding.
-    fn on_binding_start(&mut self, name: &str, writer: &mut dyn ResponseWriter) -> Result<()>;
-    fn on_binding_end(&mut self, name: &str, writer: &mut dyn ResponseWriter) -> Result<()>;
-
-    /// Called before/after an owned raw HTML range. The default methods
-    /// delegate to on_binding_start/end for source compatibility.
-    fn on_raw_binding_start(
+    /// Called before/after a signal binding. `raw` is true only when the
+    /// binding owns a replaceable HTML sibling range.
+    fn on_binding_start(
         &mut self,
         name: &str,
+        raw: bool,
         writer: &mut dyn ResponseWriter,
-    ) -> Result<()> {
-        self.on_binding_start(name, writer)
-    }
-    fn on_raw_binding_end(
+    ) -> Result<()>;
+    fn on_binding_end(
         &mut self,
         name: &str,
+        raw: bool,
         writer: &mut dyn ResponseWriter,
-    ) -> Result<()> {
-        self.on_binding_end(name, writer)
-    }
+    ) -> Result<()>;
 
     /// Called before/after for-loop and if-condition blocks.
     fn on_for_start(&mut self, name: &str, writer: &mut dyn ResponseWriter) -> Result<()>;

From a76faf7a452a69ad195cf0ec629b0566eb8ed96c Mon Sep 17 00:00:00 2001
From: Mohamed Mansour <mmansour@microsoft.com>
Date: Sat, 22 Aug 2026 11:42:25 -0700
Subject: [PATCH 3/4] Use explicit allowlist for is_html_text_only_scope

Replace the deny-list check with an explicit match over the known
raw-text/RCDATA scope strings returned by boundary_parent_scope, so a
future scope value must be deliberately classified instead of
silently defaulting to text-only.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 0807f5af-f9d9-45ad-b7d2-907084c53ea0
---
 crates/webui-parser/src/lib.rs | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/crates/webui-parser/src/lib.rs b/crates/webui-parser/src/lib.rs
index 96469d93e..c5dd69e18 100644
--- a/crates/webui-parser/src/lib.rs
+++ b/crates/webui-parser/src/lib.rs
@@ -162,9 +162,24 @@ fn boundary_parent_scope(name: &str) -> Option<&'static str> {
 
 #[inline]
 fn is_html_text_only_scope(scope: Option<&str>) -> bool {
+    // Explicit allowlist of the raw-text/RCDATA scopes returned by
+    // `boundary_parent_scope`, so a new scope value must be deliberately
+    // added here to become text-only rather than silently defaulting to it.
+    // `<template> inert content` and "component host content" are
+    // intentionally excluded: both parse normal (escaped) child content.
     matches!(
         scope,
-        Some(value) if value != "component host content" && value != "<template> inert content"
+        Some(
+            "<xmp> raw-text content"
+                | "<title> text content"
+                | "<iframe> raw-text content"
+                | "<script> raw-text content"
+                | "<noembed> raw-text content"
+                | "<textarea> text content"
+                | "<noframes> raw-text content"
+                | "<noscript> inert content"
+                | "<plaintext> text content"
+        )
     )
 }
 

From 0a1031ec6e3adde854423492b38f67e49d1a03a3 Mon Sep 17 00:00:00 2001
From: Mohamed Mansour <mmansour@microsoft.com>
Date: Sat, 22 Aug 2026 11:49:28 -0700
Subject: [PATCH 4/4] docs: clarify raw_text_context vs raw escaping policy

Document that raw_text_context only governs HTML sibling-marker
ownership and never changes escaping. signal.raw keeps its usual
meaning (HTML-encode vs. verbatim) uniformly across contexts,
including inside HTML raw-text elements (<script>, <style>, <xmp>)
which never decode character references, unlike RCDATA elements
(<title>, <textarea>) which do. Callers binding values that may
contain HTML-significant characters inside raw-text elements must
use the raw ({{{value}}}) form.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 0807f5af-f9d9-45ad-b7d2-907084c53ea0
---
 DESIGN.md                        | 18 ++++++++++++++++++
 crates/webui-handler/src/lib.rs  | 17 +++++++++++++++++
 crates/webui-protocol/src/lib.rs | 20 +++++++++++++++++---
 3 files changed, 52 insertions(+), 3 deletions(-)

diff --git a/DESIGN.md b/DESIGN.md
index d2993fd35..894980f79 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -170,6 +170,17 @@ pub struct WebUIFragmentSignal {
     pub raw_text_context: bool,
 }
 ```
+`raw_text_context` governs marker ownership only; it does not change escaping.
+`raw` keeps its usual meaning (`false` HTML-encodes, `true` writes verbatim) in
+every context, including inside `<script>`/`<style>`/`<xmp>` (HTML raw-text,
+never decodes character references) and `<title>`/`<textarea>` (RCDATA, does
+decode them). An escaped (`{{value}}`) binding inside a raw-text element is
+therefore an authoring footgun: an HTML-encoded value such as `&amp;` is
+emitted as literal text and is never decoded back by the browser, which can
+corrupt CSS/JS. Authors binding values that may contain `&`, `<`, `>`, or
+quotes inside `<script>`/`<style>`/`<xmp>` must use the raw (`{{{value}}}`)
+form. The parser does not currently reject an escaped binding in these
+contexts.
 #### Conditional Fragment
 ```rust
 pub struct WebUIFragmentIf {
@@ -1669,6 +1680,13 @@ trimmed body is exactly one handlebars expression:
 
 Bare handlebars expressions in CSS are raw text. Dynamic CSS fragments must use
 the comment wrapper so the CSS parser can distinguish them from invalid CSS.
+`<style>` is an HTML raw-text element, so the browser never decodes character
+references in it: an escaped (`raw: false`) CSS signal whose value contains
+`&`, `<`, `>`, or quotes is HTML-encoded (e.g. `&amp;`) exactly like any other
+escaped signal, and that encoded text is emitted verbatim into the stylesheet
+rather than decoded back — corrupting the CSS for those values. Prefer
+`/*{{{tokens.light}}}*/` (raw) for CSS custom-property/token values, which are
+expected to be plain CSS syntax rather than pre-escaped text.
 
 ### Design Token Resolution (`webui-tokens`)
 
diff --git a/crates/webui-handler/src/lib.rs b/crates/webui-handler/src/lib.rs
index 8da36d2b5..b10c96182 100644
--- a/crates/webui-handler/src/lib.rs
+++ b/crates/webui-handler/src/lib.rs
@@ -1949,6 +1949,17 @@ impl WebUIHandler {
         Ok(())
     }
 
+    /// Process a plain (non-structural) signal by resolving its value and
+    /// writing it to the response, HTML-encoded unless `signal.raw` is set.
+    ///
+    /// `owns_html_range` only controls whether the active plugin emits
+    /// replaceable sibling markers around the value (`on_binding_start/end`);
+    /// it never affects escaping. In particular, `signal.raw_text_context`
+    /// (marker ownership inside `<style>`/`<script>`/etc.) is independent of
+    /// `signal.raw` (escaping): a signal can be marker-free *and* HTML-encoded
+    /// at the same time. See `WebUIFragment::raw_text_signal` for why an
+    /// escaped binding inside an HTML raw-text element is an authoring
+    /// footgun rather than something this function can safely correct.
     #[inline]
     fn process_state_signal(
         &self,
@@ -1972,6 +1983,12 @@ impl WebUIHandler {
 
     /// Write a signal value directly to the writer, avoiding intermediate String allocation.
     /// For HTML-escaped output, writes the Cow from `encode_safe` directly.
+    ///
+    /// `raw` here is purely the authored escaping choice (`{{value}}` vs.
+    /// `{{{value}}}`) and is applied uniformly regardless of surrounding HTML
+    /// context: it does not know whether it is writing into a raw-text
+    /// element (`<script>`, `<style>`, `<xmp>`, which never decode character
+    /// references) or an RCDATA element (`<title>`, `<textarea>`, which do).
     fn write_signal_value(
         &self,
         value: &Value,
diff --git a/crates/webui-protocol/src/lib.rs b/crates/webui-protocol/src/lib.rs
index 3ed6a06d2..02aa1d6a2 100644
--- a/crates/webui-protocol/src/lib.rs
+++ b/crates/webui-protocol/src/lib.rs
@@ -174,9 +174,23 @@ impl WebUiFragment {
 
     /// Create a signal inside an HTML raw-text context such as `<style>`.
     ///
-    /// The rendered value follows `raw` escaping semantics but never owns an
-    /// HTML sibling range because comment markers are plain text in raw-text
-    /// elements.
+    /// `raw_text_context` is scoped to **marker ownership only**: it tells the
+    /// handler that comment/text sibling markers cannot be inserted around this
+    /// signal because they would be inert plain text in a raw-text/RCDATA
+    /// element (`<script>`, `<style>`, `<xmp>`, `<title>`, `<textarea>`, ...).
+    /// It does **not** change escaping. The rendered value still follows plain
+    /// `raw` semantics: `raw = false` (`{{value}}`) HTML-encodes the value via
+    /// `encode_safe`, `raw = true` (`{{{value}}}`) writes it verbatim.
+    ///
+    /// This distinction matters because HTML raw-text elements (`<script>`,
+    /// `<style>`, `<xmp>`, `<iframe>`, `<noembed>`, `<noframes>`) never decode
+    /// character references, unlike RCDATA elements (`<title>`, `<textarea>`)
+    /// which do. Authors who bind a value that may contain `&`, `<`, `>`, or
+    /// quotes inside a raw-text element must use the raw (`{{{value}}}`) form;
+    /// otherwise the HTML-encoded entities (e.g. `&amp;`) are emitted as literal
+    /// text and are never decoded back by the browser, corrupting the CSS/JS.
+    /// The parser does not currently reject an escaped binding in these
+    /// contexts — this is a known authoring footgun, not a parser bug.
     pub fn raw_text_signal(value: impl Into<String>, raw: bool) -> Self {
         Self {
             fragment: Some(web_ui_fragment::Fragment::Signal(WebUiFragmentSignal {