@ape-egg/vibe 2.1.4 → 2.1.7

package/compiler/src/compiler/reassignment_analyzer.rs

@@ -0,0 +1,456 @@
+//! Reassignment analysis: decide which global `$` state keys are compile-time
+//! constants (safe to value-stamp into pre-rendered HTML) versus runtime-dynamic
+//! (must be left as live `@[...]` bindings for the runtime to fill).
+//!
+//! Soundness rule: a wrong "constant" bakes stale content into production HTML
+//! (a correctness bug), while a wrong "dynamic" merely forgoes the optimization
+//! (a brief FOUC, same as today). So every uncertain case resolves to **dynamic**.
+//!
+//! A key is reported constant only when ALL of these hold:
+//!   1. Its initial value is a primitive (string / number / bool / null). Objects
+//!      and arrays are never constant — their contents can be mutated through a
+//!      value alias (`const a = $.items; a.push(x)`) that a `$.key` scan cannot
+//!      see, so they are conservatively excluded.
+//!   2. No write to `$.key` anywhere across the scanned sources — assignment,
+//!      compound assignment, `++`/`--`, `delete`, or a nested `$.key.x = …`.
+//!
+//! Any of these "escape" signals discards the whole optimization (every key is
+//! treated dynamic), because they could write a key we cannot pin down:
+//!   - aliasing `$` itself (`const x = $` / `x = $`),
+//!   - reflective writes (`Object.assign($, …)` / `Object.defineProperty($, …)`),
+//!   - a source that fails to parse (we cannot prove it is write-free).
+//!
+//! The `$` access split mirrors Vibe's own convention: `$.key` and `$['key']`
+//! (string literal) address GLOBAL state, while `$[expr]` with a non-literal key
+//! is the component-state-by-id pattern (`const id = component(s); $[id].x = …`)
+//! whose key is a generated component id, never a global key — so a non-literal
+//! computed write is ignored, not a bail.
+//!
+//! Passing `$` as a plain argument (`derive($, …)`) is treated as a read, not an
+//! escape — the vibe convention is to write state through direct `$.key = …`
+//! member assignments, and bailing on every `f($)` would disable the optimization
+//! for any real app.
+
+use swc_common::{sync::Lrc, FileName, SourceMap};
+use swc_ecma_ast::*;
+use swc_ecma_parser::{EsSyntax, Parser, StringInput, Syntax};
+use swc_ecma_visit::{Visit, VisitWith};
+
+use serde_json::{Map, Value};
+use std::collections::HashSet;
+
+/// Classify which `initial_state` keys are safe to treat as compile-time
+/// constants, given every JS source in the app (module files, inline `<script>`
+/// bodies, and HTML `on*` handler bodies). See module docs for the rules.
+pub fn classify_constant_keys(
+    initial_state: &Map<String, Value>,
+    sources: &[String],
+) -> HashSet<String> {
+    let mut written: HashSet<String> = HashSet::new();
+
+    for src in sources {
+        let module = match parse(src) {
+            Some(m) => m,
+            // Cannot prove a source is write-free → forfeit the whole optimization.
+            None => return HashSet::new(),
+        };
+        let mut visitor = WriteVisitor::default();
+        module.visit_with(&mut visitor);
+        if visitor.bail {
+            return HashSet::new();
+        }
+        written.extend(visitor.written);
+    }
+
+    initial_state
+        .iter()
+        .filter(|(key, value)| is_primitive(value) && !written.contains(key.as_str()))
+        .map(|(key, _)| key.clone())
+        .collect()
+}
+
+/// True if `src` parses as JavaScript. Used to drop heuristically-extracted
+/// HTML attribute values that aren't actually event-handler code, so that genuine
+/// unparseable JS sources can still trigger the conservative bail.
+pub fn parses_as_js(src: &str) -> bool {
+    parse(src).is_some()
+}
+
+fn is_primitive(value: &Value) -> bool {
+    matches!(
+        value,
+        Value::String(_) | Value::Number(_) | Value::Bool(_) | Value::Null
+    )
+}
+
+/// Parse a source as a module. Handler bodies can contain top-level `return`
+/// (`onclick="if (x) return; f()"`), which is illegal at module top level, so a
+/// failed parse is retried wrapped in a function before giving up — writes are
+/// still found inside the wrapper, while genuinely broken sources fall through.
+fn parse(src: &str) -> Option<Module> {
+    parse_module(src).or_else(|| parse_module(&format!("function __vibe_wrap__(){{\n{}\n}}", src)))
+}
+
+fn parse_module(code: &str) -> Option<Module> {
+    let cm: Lrc<SourceMap> = Default::default();
+    let fm = cm.new_source_file(Lrc::new(FileName::Anon), code.to_string());
+    let syntax = Syntax::Es(EsSyntax {
+        jsx: false,
+        decorators: true,
+        ..Default::default()
+    });
+    let input = StringInput::new(&fm.src, fm.start_pos, fm.end_pos);
+    let mut parser = Parser::new(syntax, input, None);
+    parser.parse_module().ok()
+}
+
+fn is_dollar(expr: &Expr) -> bool {
+    matches!(expr, Expr::Ident(id) if id.sym.to_string() == "$")
+}
+
+/// What a write target rooted at `$` resolves to.
+enum DollarTarget {
+    /// `$.key`, `$.key.x…`, or `$['key']` — the top-level GLOBAL state key touched.
+    Key(String),
+    /// `$[expr]` with a non-literal key — Vibe's component-state-by-id access,
+    /// never a global key, so irrelevant to global-constant analysis.
+    ComponentState,
+    /// Not rooted at `$`.
+    None,
+}
+
+/// Walk a member chain to its base. If the base is the `$` identifier, return
+/// the FIRST property after it (the top-level state key). `$.a.b.c` → `a`.
+fn dollar_target(member: &MemberExpr) -> DollarTarget {
+    match &*member.obj {
+        Expr::Ident(id) if id.sym.to_string() == "$" => match &member.prop {
+            MemberProp::Ident(name) => DollarTarget::Key(name.sym.to_string()),
+            MemberProp::Computed(c) => match &*c.expr {
+                Expr::Lit(Lit::Str(s)) => DollarTarget::Key(s.value.to_string()),
+                _ => DollarTarget::ComponentState,
+            },
+            MemberProp::PrivateName(_) => DollarTarget::None,
+        },
+        Expr::Member(inner) => dollar_target(inner),
+        Expr::Paren(p) => match &*p.expr {
+            Expr::Member(inner) => dollar_target(inner),
+            _ => DollarTarget::None,
+        },
+        _ => DollarTarget::None,
+    }
+}
+
+#[derive(Default)]
+struct WriteVisitor {
+    written: HashSet<String>,
+    bail: bool,
+}
+
+impl WriteVisitor {
+    /// Record a write whose target is (or descends from) `$`.
+    fn record_member_write(&mut self, member: &MemberExpr) {
+        match dollar_target(member) {
+            DollarTarget::Key(k) => {
+                self.written.insert(k);
+            }
+            // Component-state-by-id write — irrelevant to global keys.
+            DollarTarget::ComponentState => {}
+            DollarTarget::None => {}
+        }
+    }
+}
+
+/// Detects any use of the bare `$` identifier within a subtree.
+#[derive(Default)]
+struct DollarUseFinder {
+    found: bool,
+}
+impl Visit for DollarUseFinder {
+    fn visit_ident(&mut self, id: &Ident) {
+        if id.sym.to_string() == "$" {
+            self.found = true;
+        }
+    }
+}
+
+impl Visit for WriteVisitor {
+    fn visit_assign_expr(&mut self, n: &AssignExpr) {
+        match &n.left {
+            AssignTarget::Simple(SimpleAssignTarget::Member(m)) => self.record_member_write(m),
+            // `($.k) = …`
+            AssignTarget::Simple(SimpleAssignTarget::Paren(p)) => {
+                if let Expr::Member(m) = &*p.expr {
+                    self.record_member_write(m);
+                }
+            }
+            // Reassigning `$` itself (`$ = …`) replaces the whole state object.
+            AssignTarget::Simple(SimpleAssignTarget::Ident(id)) => {
+                if id.id.sym.to_string() == "$" {
+                    self.bail = true;
+                }
+            }
+            // Destructuring assignment that writes through `$` (`[$.k] = …`).
+            AssignTarget::Pat(pat) => {
+                let mut finder = DollarUseFinder::default();
+                pat.visit_with(&mut finder);
+                if finder.found {
+                    self.bail = true;
+                }
+            }
+            _ => {}
+        }
+        // Aliasing: `x = $` lets later `x.key = …` writes escape our scan.
+        if is_dollar(&n.right) {
+            self.bail = true;
+        }
+        n.visit_children_with(self);
+    }
+
+    fn visit_var_declarator(&mut self, n: &VarDeclarator) {
+        // `const x = $` — same aliasing escape as `x = $`.
+        if let Some(init) = &n.init {
+            if is_dollar(init) {
+                self.bail = true;
+            }
+        }
+        n.visit_children_with(self);
+    }
+
+    fn visit_update_expr(&mut self, n: &UpdateExpr) {
+        // `$.key++`, `--$.key`
+        if let Expr::Member(m) = &*n.arg {
+            self.record_member_write(m);
+        }
+        n.visit_children_with(self);
+    }
+
+    fn visit_unary_expr(&mut self, n: &UnaryExpr) {
+        // `delete $.key`
+        if matches!(n.op, UnaryOp::Delete) {
+            if let Expr::Member(m) = &*n.arg {
+                self.record_member_write(m);
+            }
+        }
+        n.visit_children_with(self);
+    }
+
+    fn visit_call_expr(&mut self, n: &CallExpr) {
+        // Reflective writes: Object.assign($, …) / Object.defineProperty($, …) /
+        // Reflect.set($, …) and friends could write any key.
+        if let Callee::Expr(callee) = &n.callee {
+            if let Expr::Member(m) = &**callee {
+                if let Expr::Ident(obj) = &*m.obj {
+                    let obj = obj.sym.to_string();
+                    if let MemberProp::Ident(method) = &m.prop {
+                        let method = method.sym.to_string();
+                        let reflective_write = matches!(
+                            (obj.as_str(), method.as_str()),
+                            ("Object", "assign")
+                                | ("Object", "defineProperty")
+                                | ("Object", "defineProperties")
+                                | ("Object", "setPrototypeOf")
+                                | ("Reflect", "set")
+                                | ("Reflect", "defineProperty")
+                                | ("Reflect", "deleteProperty")
+                                | ("Reflect", "setPrototypeOf")
+                        );
+                        if reflective_write {
+                            if let Some(first) = n.args.first() {
+                                if is_dollar(&first.expr) {
+                                    self.bail = true;
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        n.visit_children_with(self);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    fn state(pairs: &[(&str, Value)]) -> Map<String, Value> {
+        pairs.iter().map(|(k, v)| (k.to_string(), v.clone())).collect()
+    }
+
+    #[test]
+    fn primitive_never_written_is_constant() {
+        let s = state(&[("version", json!("0.1.5"))]);
+        let got = classify_constant_keys(&s, &["console.log($.version);".to_string()]);
+        assert!(got.contains("version"));
+    }
+
+    #[test]
+    fn direct_reassignment_is_dynamic() {
+        let s = state(&[("coins", json!(400)), ("version", json!("0.1.5"))]);
+        let got = classify_constant_keys(&s, &["$.coins = 500;".to_string()]);
+        assert!(!got.contains("coins"));
+        assert!(got.contains("version"));
+    }
+
+    #[test]
+    fn compound_and_update_are_dynamic() {
+        let s = state(&[("a", json!(1)), ("b", json!(1)), ("c", json!(1))]);
+        let got = classify_constant_keys(&s, &["$.a += 1; $.b++; --$.c;".to_string()]);
+        assert!(got.is_empty());
+    }
+
+    #[test]
+    fn computed_string_literal_write_is_dynamic() {
+        let s = state(&[("coins", json!(400)), ("version", json!("v"))]);
+        let got = classify_constant_keys(&s, &["$['coins'] = 1;".to_string()]);
+        assert!(!got.contains("coins"));
+        assert!(got.contains("version"));
+    }
+
+    #[test]
+    fn delete_is_dynamic() {
+        let s = state(&[("x", json!(1))]);
+        let got = classify_constant_keys(&s, &["delete $.x;".to_string()]);
+        assert!(!got.contains("x"));
+    }
+
+    #[test]
+    fn nested_property_write_marks_top_key_dynamic() {
+        let s = state(&[("settings", json!({ "a": 1 })), ("version", json!("v"))]);
+        let got = classify_constant_keys(&s, &["$.settings.theme = 'dark';".to_string()]);
+        assert!(!got.contains("settings"));
+        assert!(got.contains("version"));
+    }
+
+    #[test]
+    fn objects_and_arrays_are_never_constant() {
+        let s = state(&[
+            ("characters", json!([])),
+            ("clock", json!({ "now": 0 })),
+            ("version", json!("v")),
+        ]);
+        let got = classify_constant_keys(&s, &["// no writes".to_string()]);
+        assert!(!got.contains("characters"));
+        assert!(!got.contains("clock"));
+        assert!(got.contains("version"));
+    }
+
+    #[test]
+    fn aliasing_dollar_bails_everything() {
+        let s = state(&[("version", json!("v")), ("coins", json!(1))]);
+        let got = classify_constant_keys(&s, &["const x = $; x.coins = 5;".to_string()]);
+        assert!(got.is_empty());
+    }
+
+    #[test]
+    fn reassigning_dollar_bails_everything() {
+        let s = state(&[("version", json!("v"))]);
+        let got = classify_constant_keys(&s, &["let y; y = $;".to_string()]);
+        assert!(got.is_empty());
+    }
+
+    #[test]
+    fn computed_component_state_write_is_ignored() {
+        // `$[id]` / `$[id].x = …` is Vibe's component-state-by-id pattern (id is a
+        // generated component id, never a global key), so it must not bail.
+        let s = state(&[("version", json!("v"))]);
+        let got = classify_constant_keys(
+            &s,
+            &["const id = component({ open: false }); $[id].open = true;".to_string()],
+        );
+        assert!(got.contains("version"));
+    }
+
+    #[test]
+    fn computed_string_literal_global_write_is_dynamic() {
+        // A *literal* computed key IS a global-key write and must mark it dynamic.
+        let s = state(&[("coins", json!(1)), ("version", json!("v"))]);
+        let got = classify_constant_keys(&s, &["$['coins'] = 5;".to_string()]);
+        assert!(!got.contains("coins"));
+        assert!(got.contains("version"));
+    }
+
+    #[test]
+    fn object_assign_on_dollar_bails_everything() {
+        let s = state(&[("version", json!("v"))]);
+        let got = classify_constant_keys(&s, &["Object.assign($, { coins: 5 });".to_string()]);
+        assert!(got.is_empty());
+    }
+
+    #[test]
+    fn write_in_nested_scope_is_detected() {
+        let s = state(&[("token", json!(null)), ("version", json!("v"))]);
+        let src = "function f(){ if (true) { $.token = undefined; } } const g = () => $.version;";
+        let got = classify_constant_keys(&s, &[src.to_string()]);
+        assert!(!got.contains("token"));
+        assert!(got.contains("version"));
+    }
+
+    #[test]
+    fn write_across_multiple_sources() {
+        let s = state(&[("a", json!(1)), ("b", json!(2))]);
+        let srcs = ["$.a = 1;".to_string(), "console.log($.b);".to_string()];
+        let got = classify_constant_keys(&s, &srcs);
+        assert!(!got.contains("a"));
+        assert!(got.contains("b"));
+    }
+
+    #[test]
+    fn reads_do_not_mark_dynamic() {
+        let s = state(&[("version", json!("v"))]);
+        let src = "const x = $.version; if ($.version === 'v') foo($.version);";
+        let got = classify_constant_keys(&s, &[src.to_string()]);
+        assert!(got.contains("version"));
+    }
+
+    #[test]
+    fn passing_dollar_as_argument_does_not_bail() {
+        let s = state(&[("version", json!("v"))]);
+        let src = "dataInspectorState($, paths); render($);";
+        let got = classify_constant_keys(&s, &[src.to_string()]);
+        assert!(got.contains("version"));
+    }
+
+    #[test]
+    fn unparseable_source_bails_everything() {
+        let s = state(&[("version", json!("v"))]);
+        let got = classify_constant_keys(&s, &["this is (((not valid @@@".to_string()]);
+        assert!(got.is_empty());
+    }
+
+    #[test]
+    fn handler_body_write_is_detected() {
+        let s = state(&[("overlay", json!({})), ("version", json!("v"))]);
+        let got = classify_constant_keys(
+            &s,
+            &["event.preventDefault(); $.overlay = { name: 'x' };".to_string()],
+        );
+        assert!(got.contains("version"));
+        assert!(!got.contains("overlay"));
+    }
+
+    #[test]
+    fn realistic_app_state_subset() {
+        // Mirrors the battle-brawlers global state: only `version` survives.
+        let s = state(&[
+            ("version", json!("0.1.5")),
+            ("coins", json!(400)),
+            ("characters", json!([])),
+            ("token", json!(null)),
+            ("settings", json!({ "darkMode": false })),
+        ]);
+        let srcs = [
+            "if (email) $.email = email; $.canTest = false;".to_string(),
+            "if (gameState.characters) $.characters = gameState.characters;".to_string(),
+            "if (gameState.coins !== undefined) $.coins = gameState.coins;".to_string(),
+            "$.token = undefined; const v = $.version;".to_string(),
+        ];
+        let got = classify_constant_keys(&s, &srcs);
+        assert!(got.contains("version"));
+        assert!(!got.contains("coins"));
+        assert!(!got.contains("characters"));
+        assert!(!got.contains("token"));
+        assert!(!got.contains("settings"));
+    }
+}

package/compiler/src/compiler/value_stamper.rs

@@ -1,7 +1,20 @@
 use regex::{Regex, Captures};
-use serde_json::Value;
+use serde_json::{Map, Value};
 use rquickjs::{Context, Runtime};
-use std::collections::HashSet;
+use std::collections::{HashMap, HashSet};
+
+/// Render a primitive state value the way an evaluated `@[expr]` would print it:
+/// strings/numbers/bools as their text, null as empty. Mirrors `eval_with_state`.
+fn primitive_to_text(value: &Value) -> String {
+    match value {
+        Value::String(s) => s.clone(),
+        Value::Number(n) => n.to_string(),
+        Value::Bool(b) => b.to_string(),
+        Value::Null => String::new(),
+        // Constants are primitive-only (see reassignment_analyzer); fall back safely.
+        other => other.to_string(),
+    }
+}
 
 // Elements that should not have reactive bindings processed
 // Matches runtime/constants.js NON_REACTIVE_ELEMENTS
@@ -53,10 +66,23 @@ pub struct ValueStamper<'a> {
     _runtime: Runtime, // Must be kept alive for context to work
     context: Context,
     components_as_is: bool,
+    /// Global state keys proven constant by reassignment analysis, mapped to the
+    /// text they stamp to. Only an `@[key]` binding whose expression is EXACTLY
+    /// one of these keys is stamped from here — never a compound expression — so
+    /// there is no risk of a dynamic operand leaking into the value.
+    constant_texts: HashMap<String, String>,
 }
 
 impl<'a> ValueStamper<'a> {
     pub fn new(state: &'a Value, components_as_is: bool) -> Result<Self, String> {
+        Self::with_constants(state, components_as_is, &Map::new())
+    }
+
+    pub fn with_constants(
+        state: &'a Value,
+        components_as_is: bool,
+        constants: &Map<String, Value>,
+    ) -> Result<Self, String> {
         let runtime = Runtime::new().map_err(|e| format!("Failed to create QuickJS runtime: {:?}", e))?;
         let context = Context::full(&runtime).map_err(|e| format!("Failed to create QuickJS context: {:?}", e))?;
 
@@ -76,12 +102,18 @@ impl<'a> ValueStamper<'a> {
             Ok(())
         })?;
 
+        let constant_texts = constants
+            .iter()
+            .map(|(key, value)| (key.clone(), primitive_to_text(value)))
+            .collect();
+
         Ok(Self {
             state,
             binding_regex: Regex::new(r"@\[((?:[^\[\]]|\[[^\]]*\])+)\]").unwrap(),
             _runtime: runtime,
             context,
             components_as_is,
+            constant_texts,
         })
     }
 
@@ -164,9 +196,17 @@ impl<'a> ValueStamper<'a> {
                 // Stamp the binding
                 let caps = self.binding_regex.captures(binding_match.as_str()).unwrap();
                 let expr = &caps[1];
-                let stamped = self.eval_expression(expr)
-                    .unwrap_or_else(|| binding_match.as_str().to_string());
-                result.push_str(&stamped);
+                // A bare reference to a proven-constant global key (`@[version]`)
+                // stamps its build-time value. Any compound expression falls
+                // through to normal evaluation, where dynamic globals stay absent
+                // and the binding is left live for the runtime.
+                if let Some(text) = self.constant_texts.get(expr.trim()) {
+                    result.push_str(text);
+                } else {
+                    let stamped = self.eval_expression(expr)
+                        .unwrap_or_else(|| binding_match.as_str().to_string());
+                    result.push_str(&stamped);
+                }
             }
 
             last_pos = match_end;
@@ -226,7 +266,11 @@ impl<'a> ValueStamper<'a> {
     }
 
     fn render_iterations_recursive(&self, html: String) -> Result<String, String> {
-        let each_start = Regex::new(r"<!--\s*each\s+(\w+(?:\.\w+)*)\s+as\s+(\w+)(?:\s*,\s*(\w+))?\s*-->").unwrap();
+        // Matches every `<!-- each PATH as ITEM[, INDEX][ (KEY)] -->` form: the
+        // array PATH may be any expression (a call like `filter(...)`, not just a
+        // dotted path) and the optional `(KEY)` keyed-iteration suffix is captured
+        // so it can be preserved on the rebuilt marker.
+        let each_start = Regex::new(r"<!--\s*each\s+(.+?)\s+as\s+(\w+)(?:\s*,\s*(\w+))?(?:\s*\(([^)]*)\))?\s*-->").unwrap();
 
         let mut result = html.clone();
         let mut search_pos = 0;
@@ -241,20 +285,19 @@ impl<'a> ValueStamper<'a> {
             let item_alias = captures.get(2).unwrap().as_str().to_string();
             let index_alias = captures.get(3).map(|m| m.as_str().to_string()).unwrap_or_else(|| "index".to_string());
             let has_index = captures.get(3).is_some();
+            let key_part = captures.get(4).map(|m| format!(" ({})", m.as_str())).unwrap_or_default();
 
             // Find matching <!-- /each --> using depth counting
             if let Some((end_pos, end_after)) = self.find_matching_end(&result, template_start) {
                 let template = result[template_start..end_pos].to_string();
 
-                // Get array from state using QuickJS
-                let array = match self.eval_array_path(&array_path) {
-                    Some(arr) => arr,
-                    None => {
-                        // Array not found, skip this iteration
-                        search_pos = end_after;
-                        continue;
-                    }
-                };
+                // Resolve the array from the stamp state. An array we can't resolve
+                // (a dynamic global like `notifications`, empty at compile time) is
+                // treated as empty: render zero items so the raw `@[item.x]`
+                // template body is dropped from the painted DOM. The runtime
+                // restores the template from the manifest (built pre-stamp) and
+                // fills it in when the live array gets data.
+                let array = self.eval_array_path(&array_path).unwrap_or_default();
 
                 // Render each item
                 let mut rendered_items = Vec::new();
@@ -298,10 +341,11 @@ impl<'a> ValueStamper<'a> {
                 };
 
                 let replacement = format!(
-                    "<!-- each {} as {}{} -->{}<!-- /each -->",
+                    "<!-- each {} as {}{}{} -->{}<!-- /each -->",
                     array_path,
                     item_alias,
                     index_part,
+                    key_part,
                     rendered_items.join("")
                 );
 
@@ -767,6 +811,38 @@ mod tests {
         assert_eq!(result, r#"<!-- each items as item, idx --><span>[0] a</span><span>[1] b</span><span>[2] c</span><!-- /each -->"#);
     }
 
+    #[test]
+    fn unresolvable_iteration_body_is_stripped() {
+        // `notifications` is a dynamic global, absent from the stamp state. The
+        // each renders empty so no raw `@[notification.title]` paints, while the
+        // keyed marker is preserved for runtime restoration from the manifest.
+        let state = json!({});
+        let stamper = ValueStamper::new(&state, false).unwrap();
+        let html = String::from(
+            "<toasts><!-- each notifications as notification (notification.id) --><toast>@[notification.title]</toast><!-- /each --></toasts>",
+        );
+        let result = stamper.stamp_html(html).unwrap();
+        assert!(!result.contains("@["), "raw binding left behind: {result}");
+        assert!(
+            result.contains("<!-- each notifications as notification (notification.id) -->"),
+            "keyed marker dropped: {result}"
+        );
+        assert!(result.contains("<!-- /each -->"));
+    }
+
+    #[test]
+    fn unresolvable_complex_path_iteration_is_stripped() {
+        // The array path is a function call, not a dotted path — still handled.
+        let state = json!({});
+        let stamper = ValueStamper::new(&state, false).unwrap();
+        let html = String::from(
+            "<!-- each dataInspectorState($, x).rows as row (row.path) --><r>@[row.label]</r><!-- /each -->",
+        );
+        let result = stamper.stamp_html(html).unwrap();
+        assert!(!result.contains("@["), "raw binding left behind: {result}");
+        assert!(result.contains("<!-- each dataInspectorState($, x).rows as row (row.path) -->"));
+    }
+
     #[test]
     fn cleanup_boolean_attributes_false() {
         let state = json!({ "buttonDisabled": false });
@@ -806,4 +882,40 @@ mod tests {
         // disabled and required should be removed, readonly should be present with empty value
         assert_eq!(result, r#"<input readonly="">"#);
     }
+
+    fn constants(pairs: &[(&str, Value)]) -> Map<String, Value> {
+        pairs.iter().map(|(k, v)| (k.to_string(), v.clone())).collect()
+    }
+
+    #[test]
+    fn constant_key_binding_is_stamped() {
+        let state = json!({});
+        let consts = constants(&[("version", json!("0.1.5"))]);
+        let stamper = ValueStamper::with_constants(&state, false, &consts).unwrap();
+        let result = stamper
+            .stamp_html("<version-tag>BETA v@[version]</version-tag>".to_string())
+            .unwrap();
+        assert_eq!(result, "<version-tag>BETA v0.1.5</version-tag>");
+    }
+
+    #[test]
+    fn non_constant_binding_stays_raw() {
+        let state = json!({});
+        let consts = constants(&[("version", json!("0.1.5"))]);
+        let stamper = ValueStamper::with_constants(&state, false, &consts).unwrap();
+        // `coins` is dynamic (not a constant, not in stamp state) → left for runtime.
+        let result = stamper.stamp_html("<coin-stack>@[coins]</coin-stack>".to_string()).unwrap();
+        assert_eq!(result, "<coin-stack>@[coins]</coin-stack>");
+    }
+
+    #[test]
+    fn constant_never_leaks_into_compound_expression() {
+        // Only the EXACT `@[version]` binding stamps; `@[version + …]` must not
+        // pull the constant in (no `0.1.5…` garbage), guarding mixed expressions.
+        let state = json!({});
+        let consts = constants(&[("version", json!("0.1.5"))]);
+        let stamper = ValueStamper::with_constants(&state, false, &consts).unwrap();
+        let result = stamper.stamp_html("<x>@[version + suffix]</x>".to_string()).unwrap();
+        assert!(!result.contains("0.1.5"), "constant leaked into compound: {result}");
+    }
 }