diff --git a/DESIGN.md b/DESIGN.md
index 86bbd7e61..894980f79 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -165,8 +165,22 @@ 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 `"),
+ ],
+ },
+ );
+ let protocol = WebUIProtocol::new(fragments);
+ let state = test_json!({"tokens": "--accent:red"});
+ let output = render_with_webui_plugin(&protocol, &state);
+
+ assert!(output.contains(""));
+ assert!(!output.contains(""));
+ assert!(!output.contains(""));
}
}
diff --git a/crates/webui-parser/src/lib.rs b/crates/webui-parser/src/lib.rs
index 40fa6ecff..c5dd69e18 100644
--- a/crates/webui-parser/src/lib.rs
+++ b/crates/webui-parser/src/lib.rs
@@ -160,6 +160,29 @@ 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.
+ // ` inert content` and "component host content" are
+ // intentionally excluded: both parse normal (escaped) child content.
+ matches!(
+ scope,
+ Some(
+ "<![CDATA[ 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"
+ )
+ )
+}
+
/// 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 +2426,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 +2473,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 +5643,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 +5721,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 +8285,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 +8316,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 +8343,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 +8451,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. `>` → `>`). 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..02aa1d6a2 100644
--- a/crates/webui-protocol/src/lib.rs
+++ b/crates/webui-protocol/src/lib.rs
@@ -167,6 +167,36 @@ 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>`.
+ ///
+ /// `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. `&`) 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 {
+ value: value.into(),
+ raw,
+ raw_text_context: true,
})),
}
}
@@ -819,7 +849,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..23fa260f4 100644
--- a/docs/guide/concepts/plugins/index.md
+++ b/docs/guide/concepts/plugins/index.md
@@ -148,9 +148,20 @@ pub trait HandlerPlugin: Send {
/// Leave the current scope.
fn pop_scope(&mut self);
- /// Called before/after a 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 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<()>;
+ fn on_binding_end(
+ &mut self,
+ name: &str,
+ raw: bool,
+ writer: &mut dyn ResponseWriter,
+ ) -> Result<()>;
/// Called before/after for-loop and if-condition blocks.
fn on_for_start(&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"
+}
]]>