@ape-egg/vibe 2.1.22 → 3.0.0

package/runtime/utils.js

@@ -1,4 +1,6 @@
 import { THIS_PROP_REGEX } from './constants.js';
+import { recordRead, recordAbsentRead } from './tracking.js';
+import { reportEvalError } from './debug.js';
 
 // Fast incrementing counter instead of expensive random hash
 let hashCounter = 0;
@@ -25,6 +27,29 @@ export const rememberScopedKeys = (state, keys, overlay) => {
 export const ownKeysOf = (state) => scopedKeys.get(state) || Object.keys(state);
 export const scopedOverlayOf = (state) => scopedOverlay.get(state);
 
+// Register just the overlay for a merged PLAIN row snapshot (affected's
+// iteration descent builds those without going through createScopedState).
+// Tracking uses it to tell alias reads from global reads.
+export const rememberOverlay = (state, overlay) => {
+  if (overlay) scopedOverlay.set(state, overlay);
+  return state;
+};
+
+// The overlay's key set, cached per state object — the skipKeys a tracking
+// window needs so loop-alias reads don't subscribe.
+const overlayKeySets = new WeakMap();
+export const overlayKeysOf = (state) => {
+  if (state === null || typeof state !== 'object') return null;
+  const overlay = scopedOverlay.get(state);
+  if (!overlay) return null;
+  let set = overlayKeySets.get(state);
+  if (!set) {
+    set = new Set(Object.keys(overlay));
+    overlayKeySets.set(state, set);
+  }
+  return set;
+};
+
 // 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.
@@ -61,7 +86,12 @@ const dollarFor = (state) => {
   let wrapped = dollarCache.get(state);
   if (!wrapped) {
     wrapped = new Proxy(state, {
-      get: (t, k) => (k in t ? t[k] : rootHelper(k) ? rootProxy[k] : undefined),
+      // A `$.key` read on a plain snapshot never touches the live proxy, so
+      // the tracking trap can't see it — record it here. The helper fallback
+      // isn't a state read; a genuine miss records absent-tier so the key's
+      // later creation dispatches this subscriber.
+      get: (t, k) =>
+        k in t ? (recordRead(k), t[k]) : rootHelper(k) ? rootProxy[k] : (recordAbsentRead(k), undefined),
       has: (t, k) => k in t || rootHelper(k),
     });
     dollarCache.set(state, wrapped);
@@ -69,9 +99,81 @@ const dollarFor = (state) => {
   return wrapped;
 };
 
-// Function compilation cache: avoids creating new Function() for repeated expressions
-// Key: normalized expression + '\0' + state keys joined by '\0'
+// Function compilation cache: avoids creating new Function() for repeated
+// expressions. Keyed by the CANONICALIZED expression alone — params derive
+// from the expression's own free identifiers (state-first, live global
+// fallback at call time), and per-mount component ids (`_cN`) canonicalize
+// into parameters — so the cache is bounded by the app's distinct template
+// expressions, not by state shape or mount count. The previous key included
+// the full state-key signature: every SPA navigation mints fresh `_cN` keys,
+// so each navigation recompiled every expression and left the dead entries
+// cached forever (~1,300 per navigation cycle in the game).
 const fnCache = new Map();
+export const evalCacheSize = () => fnCache.size;
+
+// Canonicalize + compile one normalized expression. One regex pass: skips
+// string literals and object-literal keys, folds `$['_cN']` and bare `_cN`
+// references into `$[__vibeCidK]` parameters, and collects every remaining
+// free identifier (minus locals declared by arrow params, reserved words,
+// and known globals) as a parameter of the compiled function.
+const compileExpression = (normalized) => {
+  // Arrow-function parameters are locally bound — never parameters of ours.
+  const locals = new Set();
+  normalized.replace(/\(([^()]*)\)\s*=>/g, (_, paramList) => {
+    for (const p of paramList.split(',')) {
+      const name = p.trim().split('=')[0].trim();
+      if (/^[a-zA-Z_$][\w$]*$/.test(name)) locals.add(name);
+    }
+    return '';
+  });
+  const singleParamRe = /(?:^|[^\w$.])([a-zA-Z_$][\w$]*)\s*=>/g;
+  let paramMatch;
+  while ((paramMatch = singleParamRe.exec(normalized)) !== null) {
+    locals.add(paramMatch[1]);
+  }
+
+  const params = [];
+  const paramSet = new Set();
+  const cids = [];
+  const cidParams = new Map();
+  const cidParamFor = (id) => {
+    let p = cidParams.get(id);
+    if (!p) {
+      p = `__vibeCid${cids.length}`;
+      cidParams.set(id, p);
+      cids.push(id);
+    }
+    return p;
+  };
+
+  const canonical = normalized.replace(
+    /('(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*")|\$\['(_c\d+)'\]|((?<=[{,]\s*)[a-zA-Z_$][\w$]*(?=\s*:))|(?<![.\w$'"])[a-zA-Z_$][\w$]*/g,
+    (match, strLit, bracketCid, objKey) => {
+      if (strLit !== undefined || objKey !== undefined) return match;
+      if (bracketCid !== undefined) return `$[${cidParamFor(bracketCid)}]`;
+      if (/^_c\d+$/.test(match)) return `$[${cidParamFor(match)}]`;
+      if (match === '$' || locals.has(match) || EVAL_IDENT_EXCLUDE.has(match)) return match;
+      if (!paramSet.has(match)) {
+        paramSet.add(match);
+        params.push(match);
+      }
+      return match;
+    },
+  );
+
+  let entry = fnCache.get(canonical);
+  if (!entry) {
+    entry = {
+      fn: new Function(...params, ...cidParams.values(), '$', `'use strict'; return (${canonical})`),
+      params,
+    };
+    fnCache.set(canonical, entry);
+  }
+  // Params/cids are derived deterministically from the expression text, so a
+  // cache hit from a DIFFERENT original spelling (another mount's `_cN`)
+  // reuses the compiled fn with THIS call's ids.
+  return { fn: entry.fn, params: entry.params, cids };
+};
 
 // Built-ins and reserved words that must NEVER be pre-declared as `var`
 // inside a compiled expression — they're either real globals we want to
@@ -79,12 +181,14 @@ const fnCache = new Map();
 const EVAL_IDENT_EXCLUDE = new Set([
   // Primitive literals / special identifiers
   'true', 'false', 'null', 'undefined', 'NaN', 'Infinity', 'this',
-  // JS reserved words (shadowing any of these is a SyntaxError)
+  // JS reserved words (shadowing any of these is a SyntaxError) — plus
+  // `arguments`/`eval`, which are legal identifiers but illegal PARAMETER
+  // names in strict mode.
   'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger',
   'default', 'delete', 'do', 'else', 'export', 'extends', 'finally',
   'for', 'function', 'if', 'import', 'in', 'instanceof', 'let', 'new',
   'of', 'return', 'super', 'switch', 'throw', 'try', 'typeof', 'var',
-  'void', 'while', 'with', 'yield', 'async', 'await',
+  'void', 'while', 'with', 'yield', 'async', 'await', 'arguments', 'eval',
   // Common runtime globals authors reach for
   'Math', 'Array', 'Object', 'String', 'Number', 'Boolean', 'Date',
   'JSON', 'RegExp', 'Error', 'Map', 'Set', 'WeakMap', 'WeakSet',
@@ -98,6 +202,23 @@ const EVAL_IDENT_EXCLUDE = new Set([
 // a quote (inside a string literal).
 const FREE_IDENT_REGEX = /(?<![.\w$'"])[a-zA-Z_$][\w$]*/g;
 
+// Resolve a global identifier through the SCOPE CHAIN, not the globalThis
+// object — top-level let/const/class helpers in classic scripts live in the
+// global declarative record, which `globalThis[p]` can't see. A cached
+// per-identifier probe compiled at global scope reaches both records with
+// the typeof-guard the compiled expressions themselves used pre-3.0.0.
+// `p` is always a regex-validated non-reserved identifier (compileExpression
+// filters keywords via EVAL_IDENT_EXCLUDE), so the probe source is inert.
+const globalProbeCache = new Map();
+const readGlobal = (p) => {
+  let probe = globalProbeCache.get(p);
+  if (!probe) {
+    probe = new Function(`return typeof ${p} === 'undefined' ? undefined : ${p};`);
+    globalProbeCache.set(p, probe);
+  }
+  return probe();
+};
+
 // Evaluate expression in the context of state
 // Handles @[this.property] for component state and @[property] for global state
 export const evalInScope = (expr, state, element = null) => {
@@ -114,79 +235,34 @@ export const evalInScope = (expr, state, element = null) => {
       }
     }
 
-    // Get state keys once. ownKeysOf reads the scoped-state proxy's precomputed
-    // key list instead of Object.keys() — the latter fires getOwnPropertyDescriptor
-    // for every key, a per-eval combat hot spot.
-    const stateKeys = ownKeysOf(state);
-    const keyCount = stateKeys.length;
-
-    // Cache lookup: expression + key signature → compiled function
-    // All iteration instances share the same state shape, so this hits cache 999/1000 times
-    const cacheKey = normalized + '\0' + stateKeys.join('\0');
-    let fn = fnCache.get(cacheKey);
-    if (!fn) {
-      const allKeys = new Array(keyCount + 1);
-      for (let i = 0; i < keyCount; i++) allKeys[i] = stateKeys[i];
-      allKeys[keyCount] = '$';
-
-      // Rewrite free identifiers that are neither state keys nor known
-      // globals/reserved words so they resolve to `undefined` instead of
-      // throwing ReferenceError. `typeof x` is the only operator that can
-      // probe a name without reading it, so we guard each such reference:
-      //
-      //   missingProp  →  (typeof missingProp==='undefined'?void 0:missingProp)
-      //
-      // This keeps author intuition working for absent state (`!undef` is
-      // `true`, `undef?.x` is `undefined`) while leaving real globals —
-      // functions the app exposes on `window` — reachable via normal
-      // identifier lookup. The previous approach (`var undef;` hoist) also
-      // shadowed those globals to `undefined`, so a template call like
-      // `getLevelByExperience(exp)` threw TypeError and silently rendered
-      // "undefined".
-      const known = new Set(allKeys);
-      for (const ex of EVAL_IDENT_EXCLUDE) known.add(ex);
-
-      // Arrow function parameters are bound locally — rewriting them breaks
-      // the arrow's parameter list syntax (e.g. `f =>` must stay a bare ident).
-      // Collect both `(a, b) =>` and `x =>` forms, strip defaults, and treat
-      // them as known so the main pass leaves them untouched.
-      normalized.replace(/\(([^()]*)\)\s*=>/g, (_, paramList) => {
-        for (const p of paramList.split(',')) {
-          const name = p.trim().split('=')[0].trim();
-          if (/^[a-zA-Z_$][\w$]*$/.test(name)) known.add(name);
-        }
-        return '';
-      });
-      const singleParamRe = /(?:^|[^\w$.])([a-zA-Z_$][\w$]*)\s*=>/g;
-      let paramMatch;
-      while ((paramMatch = singleParamRe.exec(normalized)) !== null) {
-        known.add(paramMatch[1]);
-      }
-
-      // Match string literals first so hyphens inside them (e.g. 'the-arena')
-      // don't cause the trailing word to be rewritten as a free identifier.
-      // Also capture object-literal keys (`{foo: ...}` / `, foo: ...`) as a
-      // second alternative — they're property names, not references, so
-      // rewriting them produces invalid JS (computed key without brackets).
-      const source = normalized.replace(
-        /('(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*")|((?<=[{,]\s*)[a-zA-Z_$][\w$]*(?=\s*:))|(?<![.\w$'"])[a-zA-Z_$][\w$]*/g,
-        (match, strLit, objKey) => {
-          if (strLit !== undefined) return match;
-          if (objKey !== undefined) return match;
-          return known.has(match) ? match : `(typeof ${match}==='undefined'?void 0:${match})`;
-        },
-      );
-      fn = new Function(...allKeys, `'use strict'; return (${source})`);
-      fnCache.set(cacheKey, fn);
+    const { fn, params, cids } = compileExpression(normalized);
+
+    // Build values matching the compiled parameter order: the expression's
+    // free identifiers, the canonicalized component-id strings, and `$` via
+    // dollarFor — the same state for reads (so old/new diffing works), with
+    // helper-method fallback to the live root. An identifier resolves state-
+    // first by ENUMERABLE OWN KEY presence — ownKeysOf, the exact reach the
+    // old key-signature params had: snapshots and scoped states expose their
+    // keys there (a key holding undefined still shadows a global), while the
+    // root's non-enumerable helpers ($.on, $.unsafe) stay invisible — a state
+    // key named `on` must never resolve the hook method. `in` would see
+    // those helpers and the prototype chain; ownKeysOf is computed per call,
+    // so a live root proxy mutated between evals stays accurate. Everything
+    // else resolves through the scope-chain probe (readGlobal) and records
+    // an absent-tier read, so the key's later creation re-renders this
+    // binding instead of being silently missed.
+    const stateObj = state == null ? {} : state;
+    const values = new Array(params.length + cids.length + 1);
+    const keys = params.length ? ownKeysOf(stateObj) : null;
+    let v = 0;
+    for (let i = 0; i < params.length; i++) {
+      const p = params[i];
+      // State-first resolution IS a root-key read — record it for the open
+      // tracking window (snapshot evals never reach the proxy trap).
+      values[v++] = keys.includes(p) ? (recordRead(p), stateObj[p]) : (recordAbsentRead(p), readGlobal(p));
     }
-
-    // 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] = dollarFor(state);
+    for (let i = 0; i < cids.length; i++) values[v++] = cids[i];
+    values[v] = dollarFor(stateObj);
 
     const result = fn(...values);
 
@@ -209,6 +285,7 @@ export const evalInScope = (expr, state, element = null) => {
 
     return result;
   } catch (e) {
+    reportEvalError(expr, element, e);
     return undefined;
   }
 };
@@ -236,7 +313,7 @@ export const resolveCaseInsensitivePath = (state, path) => {
   // Resolve the root against the SAME scope evalInScope reaches, in its order:
   // the diff state (including scoped loop aliases — see ownKeysOf below), then
   // globals. A name-binding inside an iteration reads its props from a global
-  // stash — `window.__vibeiterprops._p0.statusKey` — so a state-only walk can
+  // stash — `window.__vibe.iterProps._p0.statusKey` — so a state-only walk can
   // never reach it, and the camelCase leaf the parser lowercased stays lost
   // (the status-chip gray-icon parity bug: resolved in compiled, not runtime).
   const root = segments[0];

package/spa.js

@@ -0,0 +1,206 @@
+// @ape-egg/vibe/spa
+//
+// Standalone SPA router — the tier between a handrolled router and compiler
+// SPA mode. Maintains one contract: $.page = { path, route, params, src,
+// name }, which a reactive component src (<component src="@[page.src]">)
+// turns into a route outlet.
+//
+// SOFT DEPENDENCY: nothing in Vibe's runtime imports this, and deleting it
+// leaves a working framework. Its one import is the standalone template cache
+// (itself dependency-free), so navigation prefetches ride the same in-flight
+// promise the outlet's mount consumes — one request per fragment. The default
+// onNavigate writes to the runtime global window.$ at call time; pass a
+// custom onNavigate and the module stays a pure router (parse/claim/history)
+// over that cache.
+//
+// Route grammar (shared with the compiler's route table and route scanners):
+//   /static/path        literal segments
+//   /brawlers/:index    :param captures one segment
+//   /docs/:rest*        trailing :name* captures zero or more segments
+//   *                   declared no-match fallback — deep links and popstate
+//                       only, never claims a click
+// Tables are pre-sorted most-specific-first; first match wins.
+
+import { fetchComponentTemplate } from './runtime/component-cache.js';
+
+// Captured params arrive percent-encoded from the URL bar; hand authors the
+// decoded value. A malformed escape (user-typed %zz) keeps the raw segment —
+// URLs are external input, not authored code.
+const decode = (segment) => {
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return segment;
+  }
+};
+
+// Match one pathname against one route template. Returns the params object
+// (possibly empty) on match, null otherwise. Empty segments are dropped, so
+// trailing slashes resolve to the same route.
+const matchRoute = (path, route) => {
+  const routeSegments = route.split('/').filter(Boolean);
+  const pathSegments = path.split('/').filter(Boolean);
+  const params = {};
+  for (let i = 0; i < routeSegments.length; i++) {
+    const segment = routeSegments[i];
+    if (segment.startsWith(':') && segment.endsWith('*')) {
+      params[segment.slice(1, -1)] = pathSegments.slice(i).map(decode).join('/');
+      return params;
+    }
+    if (pathSegments[i] === undefined) return null;
+    if (segment.startsWith(':')) params[segment.slice(1)] = decode(pathSegments[i]);
+    else if (segment !== pathSegments[i]) return null;
+  }
+  return pathSegments.length === routeSegments.length ? params : null;
+};
+
+// Route slug: segments joined with dashes, params flattened to their bare
+// name — '/' → 'home', '/pve/:id' → 'pve-id', '/docs/:rest*' → 'docs-rest'.
+// Stable across param values, so markup hangs page-scoped attributes and
+// active checks on it: <page @[page.name]>, page.name.startsWith('pve').
+const routeName = (route) =>
+  route
+    .replace(/^\/+|\/+$/g, '')
+    .replace(/:(\w+)\*?/g, '$1')
+    .replace(/\//g, '-') || 'home';
+
+// Resolve a location (anything with a .pathname, or a bare path string)
+// against a route table → { path, route, params, src, name, title? } | null.
+// Pure: the compiled shell seeds initial $.page with it, unit tests drive it
+// directly. '*' is skipped during matching and applied only when nothing
+// real matched — it is a declared fallback, not a positional route.
+export const resolve = (location, routes) => {
+  const path = location.pathname ?? location;
+  for (const entry of routes) {
+    if (entry.route === '*') continue;
+    const params = matchRoute(path, entry.route);
+    if (params)
+      return {
+        path,
+        route: entry.route,
+        params,
+        src: entry.src,
+        name: routeName(entry.route),
+        title: entry.title,
+      };
+  }
+  const fallback = routes.find((entry) => entry.route === '*');
+  // 'not-found', not '*': the slug feeds name bindings (<page @[page.name]>)
+  // and setAttribute('*') throws — the fallback must be attribute-safe.
+  return fallback
+    ? { path, route: '*', params: {}, src: fallback.src, name: 'not-found', title: fallback.title }
+    : null;
+};
+
+// Programmatic navigation without holding the setupSpa return value: app code
+// imports this and calls it like a link click. With no router active (MPA
+// output, or before setupSpa runs) it falls back to a native load, so the same
+// call site works in both output modes.
+let activeRouter = null;
+export const navigate = (path) =>
+  activeRouter ? activeRouter.navigate(path) : location.assign(new URL(path, location.origin));
+
+// Wire the router: one document-level click listener + popstate. Claiming
+// rule: same-origin, unmodified, untargeted clicks whose pathname matches a
+// REAL route — '*' never claims, so unrouted paths navigate natively (which
+// is what makes mixed MPA/SPA output work). Returns { navigate, dispose }.
+export const setupSpa = ({ routes, onNavigate }) => {
+  // Default Vibe binding: one fresh-object assignment so bindings diff
+  // cleanly, reading window.$ at call time (page scripts boot vibe before
+  // setupSpa runs). A route-supplied title swaps document.title.
+  const apply = onNavigate ?? (({ path, route, params, src, name, title }) => {
+    window.$.page = { path, route, params, src, name };
+    if (title) document.title = title;
+  });
+
+  const claim = (target) => {
+    const resolved = resolve(target, routes);
+    return resolved && resolved.route !== '*' ? resolved : null;
+  };
+
+  // Two-phase commit: the URL flips at interaction time, but route state —
+  // and with it every binding the outgoing page still renders — flips only
+  // once the incoming fragment's template is in hand. The old view never
+  // re-renders against the new route, and the prefetch IS the mount's fetch
+  // (same cache entry), so a navigation still costs one request. A failed
+  // prefetch resolves anyway: the flip proceeds and the mount path owns the
+  // error, exactly as before. The token makes rapid navigations last-wins —
+  // a superseded prefetch never applies a stale flip.
+  let navigationToken = 0;
+  const commit = (resolved, { scroll, hash }) => {
+    const token = ++navigationToken;
+    const prefetch = resolved.src
+      ? fetchComponentTemplate(resolved.src).catch(() => {})
+      : Promise.resolve();
+    prefetch.then(() => {
+      if (token !== navigationToken) return;
+      apply(resolved);
+      // A cross-page hash link scrolls to its anchor once the fragment's
+      // mount settles — late ready fires exactly then. Hashless navigations
+      // start at the top. getElementById + decode, not querySelector: a URL
+      // fragment is an element id, not a CSS selector — digit-leading ids
+      // are valid HTML but invalid selectors, and fragments arrive
+      // percent-encoded.
+      if (hash)
+        window.$?.on?.('ready', () =>
+          document.getElementById(decodeURIComponent(hash.slice(1)))?.scrollIntoView(),
+        );
+      else if (scroll) scrollTo(0, 0);
+    });
+  };
+
+  const push = (url, resolved, hash) => {
+    history.pushState({}, '', url);
+    commit(resolved, { scroll: true, hash });
+  };
+
+  const onClick = (event) => {
+    const anchor = event.target.closest('a[href]');
+    if (!anchor || anchor.origin !== location.origin) return;
+    if (anchor.target || anchor.hasAttribute('download')) return;
+    if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey || event.button) return;
+    if (event.defaultPrevented) return;
+    // Same-page hash links keep the native anchor jump.
+    if (anchor.hash && anchor.pathname === location.pathname) return;
+    const resolved = claim(anchor);
+    if (!resolved) return;
+    event.preventDefault();
+    // Same-URL click: claimed (no reload), but no duplicate history entry —
+    // Back must keep meaning "the previous page". The WHOLE url: a link to
+    // the same pathname with a different query string is a real navigation.
+    if (anchor.href === location.href) return;
+    push(anchor.href, resolved, anchor.hash || null);
+  };
+
+  // History traversal re-resolves WITH the '*' fallback — symmetric with
+  // deep-link entry, whose URL may itself be a '*' page. No scroll: the
+  // browser restores scroll position on popstate. Same two-phase commit:
+  // going back re-renders the old view only when the target is ready.
+  const onPopstate = () => {
+    const resolved = resolve(location, routes);
+    if (resolved) commit(resolved, { scroll: false });
+  };
+
+  // Programmatic navigation, claiming like a link click: real route match →
+  // SPA navigation, anything else → native load (the server rewrite serves
+  // the shell, whose deep-link resolution may then mount '*').
+  const navigate = (path) => {
+    const url = new URL(path, location.origin);
+    const resolved = claim(url);
+    if (resolved) push(url, resolved);
+    else location.assign(url);
+  };
+
+  document.addEventListener('click', onClick);
+  addEventListener('popstate', onPopstate);
+
+  const dispose = () => {
+    document.removeEventListener('click', onClick);
+    removeEventListener('popstate', onPopstate);
+    if (activeRouter === api) activeRouter = null;
+  };
+
+  const api = { navigate, dispose };
+  activeRouter = api;
+  return api;
+};

package/vibe.css

@@ -1,12 +1,16 @@
-/* Vibe Framework - Hydration Styles
- * Elements with [vibe] attribute are hidden until framework removes it after hydration.
- * This prevents flash of unprocessed content and disables transitions during init.
- */
 [vibe-fouc],
 .vibe-fouc {
   visibility: hidden;
 }
 
+/* A route/key remount stages the incoming wrapper as a hidden sibling of the
+ * outgoing page (which keeps its place, visible and styled) until the commit
+ * swaps them in one paint. display: none keeps the staged content out of
+ * layout so the two never occupy the document together. */
+[vibe-staged] {
+  display: none;
+}
+
 [vibe-fouc] *,
 .vibe-fouc * {
   transition: none !important;