@ape-egg/vibe 1.9.7 → 1.9.8

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 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

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.7",
+  "version": "1.9.8",
   "type": "module",
   "description": "Runtime-first reactivity with optional compiler",
   "main": "index.js",

package/runtime/affected.js

@@ -38,6 +38,16 @@ 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
@@ -235,6 +245,29 @@ const recursive = (
       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) => {
@@ -131,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/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);