@ape-egg/vibe 1.9.6 → 1.9.8

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## [1.9.8] - 2026-06-01
+
+### Added
+
+- **Raw-HTML rendering via `$.unsafe(expr)`** (`runtime/raw-html.js` (new), `runtime/hydrate.js`, `runtime/index.js`, `runtime/utils.js`, `compiler/src/compiler/value_stamper.rs`) — a binding that renders a trusted string as real markup instead of escaping it; Vibe's equivalent of Svelte `{@html}` / Vue `v-html` / React `dangerouslySetInnerHTML`. `$.unsafe(str)` wraps a string in a `RawHtml` marker. When the binding is the **sole content of its element** (`<p>@[$.unsafe(desc)]</p>`), the runtime sets `innerHTML` from the string and marks the injected subtree opaque (`managedNodes`) so the MutationObserver never re-walks it — injected markup is **inert**, matching Svelte. Mixed into surrounding text it falls back to escaped literal text (via the marker's `toString()`). Reactive in every scope (top-level, iterations, conditionals, components). Compiled mode paints the markup raw at stamp time (`value_stamper.rs` defines `$.unsafe` in the QuickJS context) while the manifest preserves the `@[$.unsafe(...)]` marker for runtime re-hydration. **Trusted input only — no sanitizing.**
+  - Test: `tests/unit/raw-html.test.js`, `tests/e2e/unsafe-html.spec.js` (pure render, escaped-text fallback, reactivity, in-iteration, in-conditional, inert injected markup), and `$.unsafe` stamping in `tests/compiler/runtime`.
+
+### Fixed
+
+- **`$` inside expressions must read from the per-cycle state, not the live root** (`runtime/utils.js`) — surfaced while wiring `$.unsafe`. The reactivity engine detects change by evaluating each expression against an old snapshot and a new snapshot and comparing; binding `$` to the live root proxy made both reads identical, silently defeating change detection for any expression reading through `$` or `this.` (which compiles to `$['id']…`) — e.g. a computed iteration array or conditional gated on component state would stop re-rendering. `evalInScope` now resolves `$` to the same state object the diff cycle is evaluating, and reaches the root's non-enumerable helper methods (`unsafe`, `on`, `reconcile`) via a thin per-state fallback proxy so `$.unsafe` stays callable from plain snapshots on the update path. State reads stay on the snapshot (diffable); only missing method names fall through to root. Scoped states already delegate to root, so the hot path is unaffected.
+  - Test: `tests/unit/dollar-binding-scope.test.js` (a `$`-expression yields different values for two snapshots → diffable; `$.unsafe` resolves from a plain snapshot lacking it)
+
+---
+
+## [1.9.7] - 2026-06-01
+
+### Fixed
+
+- **Conditional inside an iteration row didn't react to global-state changes** (`runtime/affected.js`, `runtime/hydrate.js`) — a `<!-- if … -->` (or `<!-- if … --><!-- else --><!-- /if -->`) living inside an `<!-- each -->` row, whose expression depended on a global rather than the loop item, stayed frozen on the branch active at mount time when the global later changed and the row's `item` was unchanged. Two compounding gaps, fixed at the right layer in two steps:
+  - **Branch swap re-evaluated against the wrong scope** (`affected.js`, `hydrate.js`) — `affected` correctly detected the change against the row's merged state, but the affected entry it pushed carried only the node. `hydrate` then called `updateConditional` with the cycle's top-level state, which had no `item`, so the branch eval evaluated `selected.includes(item.id)` etc. against `item === undefined`. Rows mounted on the *if* branch happened to flip to *else* (often correct by coincidence); rows mounted on the *else* branch stayed stuck. `affected.js` now attaches the same `state`/`newState` pair the change was detected against as `scopedState`/`oldScopedState` on the conditional entry — merged row state inside an iteration, the cycle's top-level state outside — and `hydrate.js`'s conditional handler uses them when present.
+  - **Inlined per-row components were invisible to the iteration recursion** (`affected.js`) — a `<component src>` mounted per iteration row has its parsed tree stashed on the post-process wrapper as `_vibeIterTree`, not as a child of `instance.tree`. `hydrateInlinedIterationComponents` already re-hydrates those trees, but it only runs from `updateInstance`, which only fires when the iteration's array changes. On a pure global-state change the array is unchanged, so the inlined component trees were never visited — a row-internal `<!-- if -->` *without* an else, gated on a global and living inside a per-row component (the Battle Brawlers `<brawler-menu>`/`<brawler-activity>` shape), wouldn't tear down. `affected.js`'s iteration recursion now also descends into every `_vibeIterTree` reachable from each instance's cloned nodes with the same merged scoped state, so the conditional flows through the normal affected → hydrate → `updateConditional` path and the existing `branches.else === null` handling triggers `unmountBranch`. Same path covers any other binding/conditional living inside a per-row component, so they all now react to global state changes too.
+  - Test: `tests/e2e/conditional-in-iteration-global.spec.js` (7 tests: swap of `selected.includes(item.id)` in both directions; dynamic property lookup; compound gate with both halves; `if`-without-else direct shape; compound `if`-without-else; nested-property gate `combat.duration !== 0 && busyMap[item.id]`; and the per-row-component repro toggling `$.showMenu` through a mount→teardown→re-mount cycle)
+
+- **Loop-scoped `on*` handler inside a row-internal `<!-- if -->` resolved the previous item after the row updated** (`runtime/loop-scope.js`) — a `<!-- if -->` inside an iteration mounts its branch content separately from the row's `clonedNodes` and stamps `__vibeScope` once at mount time. When the row was later updated in place (its DOM reused for a new item), the iteration refreshed its own root stamp but the branch root kept the stale mount-time stamp, and `resolveScope` hit that first on the walk up — so a handler inside the conditional resolved the previous item. `stampInstanceScopes` now walks the instance's parsed tree and re-stamps every active conditional-branch root with the same fresh scope. Nested loops are skipped — each iteration node already manages its own instances' scopes.
+  - Test: `tests/e2e/loop-scoped-handlers.spec.js` (+ unit coverage in `tests/unit/loop-scope.test.js`)
+
+- **Treeless (batch-rendered) iteration was rebuilt on every unrelated state change** (`runtime/iterate.js`) — `affected.js` conservatively flags a treeless iteration on any state change (it can't walk per-row trees to know what they depend on), and `updateIteration` responded with an unconditional `bulkReplace`. A background tick (e.g. a 250 ms client clock) therefore recreated every row on every flush, dropping imperatively-attached listeners (tooltip mouseleave) and any in-progress drag. `renderBatch` now remembers the rendered HTML on the iteration's runtime; before tearing down, `updateIteration` re-runs the batch — if the output is byte-identical to the previous one, the rows don't depend on what changed, and the existing DOM nodes are kept. Skipped when the template has DOM-property writes (`value`/`checked`/`selected`), which aren't reflected in the HTML string.
+  - Test: `tests/e2e/iteration-treeless-unrelated-update.spec.js`
+
+- **Inlined component's literal-wrap `<!-- each [prop] as alias -->` froze on the original snapshot** (`runtime/iterate.js`) — when an inlined component received an object prop and wrapped it in a literal-array iteration to render its fields, the inner iteration's `forceRegistryBackedIterationUpdates` calls `updateIteration` with `oldState === newState`, but the old/new array eval produces fresh arrays containing the just-rewritten registry value, so the diff saw identical contents and emitted no UPDATE. `updateIteration` now treats `oldState === newState` as a "trust the rendered snapshot" signal — the previously rendered items on iteration instances are the only honest "old" when the registry side-effect is the only mutation — and correctly emits per-row updates.
+
+### Added
+
+- **`<component src>` callsite receives its componentId** (`runtime/component.js`) — `processSingle` now returns the resolved `componentId` so `const id = component(state)` inside a `<script type="module">` block of a src-fetched component resolves to a non-undefined id. Matches the public component.js contract; without it, downstream `$[id]` was silently undefined for src-fetched components.
+
+---
+
 ## [1.9.6] - 2026-05-25
 
 ### Fixed

package/README.md

@@ -1,6 +1,6 @@
 # Vibe
 
-**Version 1.9.2 (Beta)** — A runtime-first reactive framework with optional compilation.
+**Version 1.9.8 (Beta)** — A runtime-first reactive framework with optional compilation.
 
 No virtual DOM. No build step required. Just modern JavaScript. When you need production optimizations, add the optional Rust-based compiler.
 
@@ -105,6 +105,26 @@ Vibe supports bindings in three positions:
 <!-- /each -->
 ```
 
+The "array" position accepts any JS expression evaluated in scope, not just a state path:
+
+```html
+<!-- each items.filter(i => i.active) as item -->...<!-- /each -->
+<!-- each Array.from({ length: count }) as n, index -->...<!-- /each -->
+```
+
+**Keyed iteration** — give each row a stable identity with `(keyExpr)` so survivors keep their DOM (and listeners / animation state) when the list reorders or items are removed. The key comes before the optional index. Without a key, Vibe falls back to an index-coupled hash and bulk-re-renders the tail on reorder.
+
+```html
+<!-- each rows as row (row.id) -->
+<li>@[row.label]</li>
+<!-- /each -->
+
+<!-- key + index -->
+<!-- each rows as row (row.id), index -->
+<li>@[index]: @[row.label]</li>
+<!-- /each -->
+```
+
 Nested iteration with dot paths:
 
 ```html
@@ -218,6 +238,19 @@ Skip reactive processing for an element:
 <code vibe-dehydrate>@[this] displays literally</code>
 ```
 
+### Raw HTML (`$.unsafe`)
+
+`@[expr]` escapes its output (`textContent`) — safe by default. To render **trusted** markup instead, wrap the value in `$.unsafe(...)`; the binding sets `innerHTML`. This is Vibe's equivalent of Svelte `{@html}` / Vue `v-html` / React `dangerouslySetInnerHTML`.
+
+```html
+<p>@[$.unsafe(description)]</p>
+```
+
+- The binding **must be the sole content of its element** (innerHTML semantics). Mixed into surrounding text, it falls back to escaped literal text.
+- Injected markup is **inert** — `@[...]` / `<!-- if -->` / `<!-- each -->` inside it are not processed (matches Svelte `{@html}`); the subtree is opaque to the MutationObserver.
+- Fully **reactive** — re-renders on value change; works in iterations, conditionals, and components. Compiled mode paints the markup at stamp time and re-hydrates at runtime.
+- **Trusted input only** — no sanitizing. Don't pass user-supplied strings.
+
 ### Internal Names (don't collide)
 
 These are used by the runtime — don't repurpose them in your code:

package/compiler/src/compiler/value_stamper.rs

@@ -64,7 +64,14 @@ impl<'a> ValueStamper<'a> {
         context.with(|ctx| -> Result<(), String> {
             let state_str = serde_json::to_string(state)
                 .map_err(|e| format!("Failed to serialize state: {}", e))?;
-            ctx.eval::<(), _>(format!("const $ = {}; Object.assign(globalThis, $)", state_str))
+            // Expose state both as bare globals (via Object.assign) and as a
+            // persistent `$` global carrying the runtime `unsafe` helper, so a
+            // `@[$.unsafe(expr)]` binding stamps its trusted string raw at build
+            // time — mirroring the runtime, where `$.unsafe` marks raw HTML.
+            ctx.eval::<(), _>(format!(
+                "const $ = {}; Object.assign(globalThis, $); $.unsafe = (s) => s; globalThis.$ = $",
+                state_str
+            ))
                 .map_err(|e| format!("Failed to set up state in QuickJS: {:?}", e))?;
             Ok(())
         })?;
@@ -714,6 +721,25 @@ mod tests {
         assert_eq!(result, "<div>Hello @[missing]</div>");
     }
 
+    #[test]
+    fn stamp_unsafe_emits_raw_html() {
+        let state = json!({ "desc": "Gain <span data-green>+3%</span>." });
+        let stamper = ValueStamper::new(&state, false).unwrap();
+        let html = String::from("<p>@[$.unsafe(desc)]</p>");
+        let result = stamper.stamp_html(html).unwrap();
+        // Raw markup is painted directly — not escaped, not left as a marker.
+        assert_eq!(result, "<p>Gain <span data-green>+3%</span>.</p>");
+    }
+
+    #[test]
+    fn stamp_unsafe_nested_path() {
+        let state = json!({ "tooltip": { "props": { "description": "<em>x</em>" } } });
+        let stamper = ValueStamper::new(&state, false).unwrap();
+        let html = String::from("<p>@[$.unsafe(tooltip.props.description)]</p>");
+        let result = stamper.stamp_html(html).unwrap();
+        assert_eq!(result, "<p><em>x</em></p>");
+    }
+
     #[test]
     fn stamp_attribute_binding() {
         let state = json!({ "firstName": "John" });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ape-egg/vibe",
-  "version": "1.9.6",
+  "version": "1.9.8",
   "type": "module",
   "description": "Runtime-first reactivity with optional compiler",
   "main": "index.js",

package/runtime/affected.js

@@ -38,6 +38,63 @@ const matchesKey = (matchStr, key) => {
   return false;
 };
 
+// Identifier-followed-by-`(` — i.e. an attempted function or method call.
+// Used to flag conditional expressions whose result can't be trusted to the
+// snapshot-equality short-circuit because the called function may read live
+// `$` (or other state-holding globals) via closure rather than the state
+// snapshot affected.js passes in. False positives are acceptable: when the
+// expression contains a call, we fall back to "if any state key changed,
+// re-evaluate"; mountBranch's branchChanged guard suppresses the no-op DOM
+// churn when the value didn't actually flip.
+const CALL_EXPR_REGEX = /\b[A-Za-z_$][\w$]*\s*\(/;
+
+// Resolve a clone-list entry to its live counterpart. processComponent swaps
+// the original `<component src>` for a post-process `<component>` wrapper and
+// records the new node on the original via `_vibeReplacedBy`. Mirrors
+// `liveCloneNode` in iterate.js — kept inline to avoid a circular import.
+const liveCloneNode = (node) => {
+  let cur = node;
+  while (cur && cur._vibeReplacedBy) cur = cur._vibeReplacedBy;
+  return cur;
+};
+
+// Descend into any inlined `<component>` parsed trees attached to an
+// iteration row. `_vibeIterTree` is stamped on the post-process wrapper by
+// index.js (mutation-observer path) and on nested inlined components reached
+// via `[data-vibe-iter-prop]`. The trees retain the original `@[…]` binding
+// text so this affected walk can flag changes the same way it would on the
+// row's own tree.
+const walkInlinedComponentTrees = (
+  clonedNodes,
+  state,
+  newState,
+  affected,
+  depth,
+) => {
+  for (let n = 0; n < clonedNodes.length; n++) {
+    const node = liveCloneNode(clonedNodes[n]);
+    if (!node || node.nodeType !== 1) continue;
+    const wrappers = [];
+    if (node._vibeIterTree) wrappers.push(node);
+    const found = node.querySelectorAll?.('[data-vibe-iter-prop]');
+    if (found) {
+      for (let i = 0; i < found.length; i++) {
+        if (found[i]._vibeIterTree) wrappers.push(found[i]);
+      }
+    }
+    for (let w = 0; w < wrappers.length; w++) {
+      recursive(
+        wrappers[w]._vibeIterTree,
+        state,
+        newState,
+        affected,
+        newState,
+        depth,
+      );
+    }
+  }
+};
+
 const recursive = (
   tree,
   state,
@@ -129,6 +186,26 @@ const recursive = (
             mergedNewState,
             depth + 1,
           );
+
+          // Components mounted as `<component src>` *inside* an iteration row
+          // are not children of `instance.tree` — their parsed tree lives on
+          // the post-process wrapper as `_vibeIterTree`. Without descending
+          // into it, conditionals / bindings inside the inlined component are
+          // invisible to this walk, so a global state change that should tear
+          // down a row-internal `<!-- if -->` (or flip a binding) inside the
+          // component is missed. `updateInstance` re-hydrates these trees via
+          // `hydrateInlinedIterationComponents`, but only when the iteration
+          // itself is flagged affected (array change). For pure global-state
+          // updates the array is unchanged, so we descend here instead.
+          if (instance.clonedNodes) {
+            walkInlinedComponentTrees(
+              instance.clonedNodes,
+              mergedOldState,
+              mergedNewState,
+              affected,
+              depth + 1,
+            );
+          }
         }
       }
     }
@@ -151,14 +228,46 @@ const recursive = (
 
     // Check if condition result changed
     if (oldValue !== newValue) {
+      // Carry the state pair the condition was evaluated against. Inside an
+      // iteration row this is the merged state (loop alias + current globals),
+      // outside it is the cycle's top-level state. hydrate hands these to
+      // updateConditional so the branch swap re-evaluates the expression in
+      // the same scope — without them, a row-internal `if` is re-evaluated
+      // against a state with no `item`, which always reads falsy and leaves
+      // rows that were initially on the else branch stuck there.
       affected.push({
         type: "conditional",
         node: tree,
         changeType: "expression",
+        scopedState: newState,
+        oldScopedState: state,
       });
       return affected;
     }
 
+    // Function-call short-circuit: when the expression contains a `(`-style
+    // call, the snapshot eval can be blind — the called helper may read live
+    // `$` via closure rather than the passed state, so `oldValue` and
+    // `newValue` both run against the *current* values and the equality check
+    // never fires. Flag as affected whenever any state key actually changed
+    // this cycle so updateConditional re-runs against live state; if the
+    // result hasn't really flipped, mountBranch's branchChanged guard absorbs
+    // the call cheaply. Skip during initial hydration (state === newState).
+    if (state !== newState && CALL_EXPR_REGEX.test(tree.meta.expression)) {
+      const stateKeys = Object.keys(state);
+      const anyChanged = stateKeys.some((k) => state[k] !== newState[k]);
+      if (anyChanged) {
+        affected.push({
+          type: "conditional",
+          node: tree,
+          changeType: "expression-fn-call",
+          scopedState: newState,
+          oldScopedState: state,
+        });
+        return affected;
+      }
+    }
+
     // Condition didn't change, check for affected elements inside active branch
     if (tree.runtime.activeInstance && tree.runtime.activeInstance.parsedTree) {
       return recursive(

package/runtime/hydrate.js

@@ -1,7 +1,8 @@
 import { updateIteration } from './iterate.js';
-import { updateConditional } from './conditionals.js';
+import { updateConditional, managedNodes } from './conditionals.js';
 import { VALUE_ATTRS, DOM_PROPERTIES, BINDING_REGEX, PURE_BINDING_REGEX } from './constants.js';
 import { evalInScope, resolveCaseInsensitivePath } from './utils.js';
+import { RawHtml } from './raw-html.js';
 
 export default (affected, state, manifest = {}, oldState = {}) => {
   affected.forEach((aff) => {
@@ -14,9 +15,15 @@ export default (affected, state, manifest = {}, oldState = {}) => {
       return;
     }
 
-    // Handle conditional updates
+    // Handle conditional updates. Use the scoped pair affected attached when
+    // the conditional sits inside an iteration row — that pair has the row's
+    // loop alias overlaid on current globals, so the branch eval re-runs in
+    // the same scope the change was detected against. Top-level conditionals
+    // pass through with the cycle's state (affected attaches it verbatim there).
     if (aff.type === 'conditional') {
-      updateConditional(aff.node, state, oldState, manifest);
+      const condNewState = aff.scopedState || state;
+      const condOldState = aff.oldScopedState || oldState;
+      updateConditional(aff.node, condNewState, condOldState, manifest);
       return;
     }
 
@@ -125,6 +132,27 @@ export default (affected, state, manifest = {}, oldState = {}) => {
       // Evaluate the expression with state as context
       const evaluated = evalInScope(matchInner, effectiveState, element);
 
+      // Raw-HTML render: `$.unsafe(str)` returns a RawHtml marker. When the
+      // binding is the sole content of its element (`<p>@[$.unsafe(x)]</p>`),
+      // set innerHTML from the trusted string instead of escaping via
+      // textContent. The injected subtree is marked opaque (managedNodes) so
+      // the MutationObserver never re-walks or hydrates it — raw HTML is inert,
+      // matching Svelte {@html}. Any non-pure use (marker spliced into
+      // surrounding text, or an element with other children) falls through to
+      // the normal path, where RawHtml.toString() degrades to escaped text.
+      const isPureBinding = input.trim() === matchOuter;
+      if (evaluated instanceof RawHtml && isPureBinding &&
+          (element._vibeRawHtml || element.childNodes.length === 1)) {
+        const html = evaluated.html;
+        if (element._vibeRawHtmlValue !== html) {
+          element.innerHTML = html;
+          for (const child of element.children) managedNodes.add(child);
+          element._vibeRawHtmlValue = html;
+        }
+        element._vibeRawHtml = true;
+        return;
+      }
+
       const toReplace = input.replaceAll(matchOuter, evaluated).trim();
 
       affected.forEach((innerAff) => {

package/runtime/index.js

@@ -3,7 +3,8 @@ import parse from './parse.js';
 import createManifest from './manifest.js';
 import hydrate from './hydrate.js';
 import affected from './affected.js';
-import { deepMerge, hash } from './utils.js';
+import { deepMerge, hash, setRootState } from './utils.js';
+import { unsafe } from './raw-html.js';
 import { renderAllIterations, setRenderAllConditionals, releaseOrphanedIterationProps } from './iterate.js';
 import { renderAllConditionals, branchNodeRegistry, managedNodes } from './conditionals.js';
 import { installScopeResolver } from './loop-scope.js';
@@ -655,6 +656,16 @@ const main = (s, config = {}, stringSelector = '') => {
     enumerable: false,
   });
 
+  // Mark a trusted string as raw HTML. A binding that is the sole content of
+  // its element — `<p>@[$.unsafe(desc)]</p>` — sets innerHTML from the string
+  // instead of escaping it via textContent. Trusted input only (no sanitizing,
+  // like Svelte {@html}). Non-enumerable so it never leaks into state snapshots.
+  Object.defineProperty($, 'unsafe', {
+    value: unsafe,
+    enumerable: false,
+    configurable: true,
+  });
+
   // Pure-render path for surgical component HMR. Given raw component template
   // HTML, callsite props, slot HTML, and existing componentIds, returns the
   // processed HTML string the plugin's HMR handler can hand to $.reconcile.
@@ -672,6 +683,21 @@ const main = (s, config = {}, stringSelector = '') => {
   // manifest's node-path entry iteration.
   Object.defineProperty(manifest, '__live', { value: $, enumerable: false, configurable: true });
 
+  // Bind `$` inside every expression to this live root proxy (see setRootState
+  // in utils.js). Done before the first hydration pass so `$.unsafe` and the
+  // other reserved methods are reachable from the initial render onward.
+  setRootState($);
+
+  // Publish the real proxy on `window.$` BEFORE the first hydration pass.
+  // boot.js sets `window.$ = main(...)`, but until main returns it's the
+  // pre-boot placeholder (vibeInstance with no state keys). User helpers
+  // defined on `window` that close over `$` — e.g. a global `brawlerActivity`
+  // function reading `$.combat?.duration` — would then read the placeholder
+  // during initial render and treat the whole world as empty. Assigning the
+  // live proxy here lets those closures see the right `$` from the very
+  // first conditional/binding eval.
+  if (typeof window !== 'undefined') window.$ = $;
+
   // Initial hydration - pass plain values so iteration can do reference comparison
   const initialState = extractPlainValue($);
   const affectedElements = affected(parsedTree, initialState, initialState);

package/runtime/iterate.js

@@ -996,19 +996,32 @@ export const updateIteration = (iterationNode, newState, oldState, manifest, par
   const newArray = evalInScope(resolvedExpr, newState, startComment.parentElement) ?? resolvePath(newState, resolvedExpr) ?? [];
 
   // Use instances (what's actually rendered) as ground truth for old array
-  // when oldState disagrees with the rendered count, OR when stateOldArray
-  // and newArray are the same reference. The latter happens for
-  // registry-backed iterations: when the iteration's arrayPath resolves to
-  // `window.__vibeIterProps._pN`, refreshIterationComponentProps updates the
-  // slot in place, so both reads return the same NEW array. Without this
-  // fallback the diff would compare the new array against itself and report
-  // no changes — leaving the inlined iteration frozen on previously rendered
-  // items.
+  // whenever the only signal of change is a registry side-effect, or when
+  // the rendered count doesn't match the freshly evaluated state. Three
+  // cases collapse to "trust the rendered snapshot":
+  //   1. oldState === newState — forceRegistryBackedIterationUpdates calls
+  //      updateIteration with the same state on both sides because the only
+  //      mutation was a registry slot rewrite. The previously rendered
+  //      items are the only honest record of what was there before.
+  //   2. stateOldArray === newArray — the iteration's arrayPath resolves
+  //      directly to a registry slot (`window.__vibeIterProps._pN`); the
+  //      slot was swapped in place, so both reads return the same NEW
+  //      array.
+  //   3. length mismatch — oldState predates the current render.
+  // Otherwise the freshly evaluated state is a trustworthy "old".
+  //
+  // Literal-wrap expressions like `[s]` would otherwise slip through this
+  // net: they build different array refs each eval but both contain the
+  // just-rewritten registry value, so a naive diff sees no change. Case 1
+  // catches them.
   const instances = iterationNode.runtime.instances;
-  const oldArray =
-    stateOldArray !== newArray && instances.length === stateOldArray.length
-      ? stateOldArray
-      : instances.map((inst) => inst.item);
+  const useInstancesAsOld =
+    oldState === newState ||
+    stateOldArray === newArray ||
+    instances.length !== stateOldArray.length;
+  const oldArray = useInstancesAsOld
+    ? instances.map((inst) => inst.item)
+    : stateOldArray;
 
   // Compiled path: Use pre-compiled batch function when available
   if (compiled.canUseCompiled(iterationNode)) {

package/runtime/loop-scope.js

@@ -128,6 +128,35 @@ export const resolveScope = (el, name) => {
   return undefined;
 };
 
+// Re-stamp the instance scope onto conditional-branch roots mounted inside a
+// row. A `<!-- if -->` within a loop mounts its branch content separately from
+// the iteration's own clonedNodes and stamps it once, at mount time
+// (conditionals.js). When the row later updates in place — its DOM node reused
+// for a new item — the iteration refreshes its own root stamp, but the branch
+// root keeps the stale mount-time stamp, and `resolveScope` hits that first on
+// the walk up (so a handler inside the conditional resolves the previous item).
+// Walking the instance's parsed tree and re-stamping every active conditional
+// branch root with the same fresh `scope` object closes that gap. Nested loops
+// are skipped: each iteration node manages its own instances' scopes.
+const restampConditionalBranches = (tree, scope) => {
+  if (!tree || typeof tree !== 'object') return;
+  if (tree.type === 'iteration') return;
+  if (tree.type === 'conditional') {
+    const active = tree.runtime?.activeInstance;
+    if (active?.nodes) {
+      for (let i = 0; i < active.nodes.length; i++) {
+        const node = active.nodes[i];
+        if (node && node.nodeType === 1) node.__vibeScope = scope;
+      }
+    }
+    if (active?.parsedTree) restampConditionalBranches(active.parsedTree, scope);
+    return;
+  }
+  if (tree.children) {
+    for (const key in tree.children) restampConditionalBranches(tree.children[key], scope);
+  }
+};
+
 // Stamp the in-scope loop vars onto every iteration instance's root element
 // node(s). The stamp accumulates the enclosing loop vars (`parentScope`) plus
 // this loop's item/index, so a single innermost stamp resolves every alias in
@@ -151,6 +180,10 @@ export const stampInstanceScopes = (iterationNode, parentScope = {}) => {
       const node = roots[r];
       if (node && node.nodeType === 1) node.__vibeScope = scope;
     }
+    // Conditional branches inside the row carry their own stamp from mount time;
+    // refresh them with the same fresh scope so in-place row updates don't leave
+    // a handler inside an `<!-- if -->` resolving the previous item.
+    if (inst.tree) restampConditionalBranches(inst.tree, scope);
   }
 };
 

package/runtime/raw-html.js

@@ -0,0 +1,15 @@
+// Marker for trusted raw-HTML output. `$.unsafe(str)` wraps a string so the
+// hydrate path knows to set innerHTML instead of escaping via textContent.
+// toString() returns the raw string so any non-pure use (the marker spliced
+// into surrounding text) degrades to escaped literal text automatically — the
+// browser escapes it when it lands in a text node.
+export class RawHtml {
+  constructor(html) {
+    this.html = html == null ? '' : String(html);
+  }
+  toString() {
+    return this.html;
+  }
+}
+
+export const unsafe = (html) => new RawHtml(html);

package/runtime/utils.js

@@ -4,6 +4,40 @@ import { THIS_PROP_REGEX } from './constants.js';
 let hashCounter = 0;
 export const hash = () => `_${hashCounter++}`;
 
+// The live root reactive proxy, wired once at boot by index.js. Used ONLY to
+// reach the root's non-enumerable helper methods (`$.unsafe`, `$.on`, …) — NOT
+// for state reads.
+let rootProxy = null;
+export const setRootState = (proxy) => { rootProxy = proxy; };
+
+// Resolve the `$` identifier for an expression. `$` must read from the SAME
+// state object the diff cycle is evaluating — affected.js / iterate.js compare
+// an expression's value against an old snapshot and a new snapshot, so binding
+// `$` to the live root instead would make both reads identical and defeat
+// change detection (the whole reactivity engine). So state reads stay on the
+// passed `state`.
+//
+// The catch: the root's reserved methods (`unsafe`, `on`, `reconcile`, …) are
+// non-enumerable and don't survive the plain `{...state}` snapshots, so a
+// plain snapshot can't reach `$.unsafe`. Wrap such a state in a thin proxy that
+// serves its own keys (snapshot reads, fully diffable) and falls back to the
+// live root only for keys it lacks (the helper methods). Scoped states already
+// delegate to the live root (their target is `$`), so they need no wrapper.
+const dollarCache = new WeakMap();
+const RESERVED_PROBE = 'unsafe'; // reserved method present on root-backed states, absent on plain snapshots
+const dollarFor = (state) => {
+  if (!rootProxy || state === rootProxy || RESERVED_PROBE in state) return state;
+  let wrapped = dollarCache.get(state);
+  if (!wrapped) {
+    wrapped = new Proxy(state, {
+      get: (t, k) => (k in t ? t[k] : rootProxy[k]),
+      has: (t, k) => k in t || k in rootProxy,
+    });
+    dollarCache.set(state, wrapped);
+  }
+  return wrapped;
+};
+
 // Function compilation cache: avoids creating new Function() for repeated expressions
 // Key: normalized expression + '\0' + state keys joined by '\0'
 const fnCache = new Map();
@@ -113,10 +147,13 @@ export const evalInScope = (expr, state, element = null) => {
       fnCache.set(cacheKey, fn);
     }
 
-    // Build values array matching the cached function's parameter order
+    // Build values array matching the cached function's parameter order. Bare
+    // identifiers resolve from the passed (possibly scoped) state; the `$`
+    // identifier resolves via dollarFor — the same state for reads (so old/new
+    // diffing works), with helper-method fallback to the live root.
     const values = new Array(keyCount + 1);
     for (let i = 0; i < keyCount; i++) values[i] = state[stateKeys[i]];
-    values[keyCount] = state;
+    values[keyCount] = dollarFor(state);
 
     const result = fn(...values);