@ape-egg/vibe 2.3.0 → 3.0.0

package/runtime/conditionals.js

@@ -1,9 +1,13 @@
 import parse from './parse.js';
-import affected from './affected.js';
+import affected, { nodeSubscriberOf } from './affected.js';
 import hydrate from './hydrate.js';
+import { beginTracking, endTracking, pruneDisconnected } from './tracking.js';
+import { overlayKeysOf } from './utils.js';
+import { setManifestEntry, manifestPathOf } from './manifest.js';
 import { createScopedState, renderAllIterations, initializeBlock, resolveIterationComponentProps } from './iterate.js';
 import { evalInScope } from './utils.js';
 import { collectComponentIds, releaseOrphanedComponentState, executeCompiledComponentScriptsIn } from './component.js';
+import { isOutgoing } from './staging.js';
 
 // Registry of DOM nodes owned by conditional branches.
 // Maps a DOM node to { nodes: array_ref, index: number } so that
@@ -17,22 +21,19 @@ export const branchNodeRegistry = new WeakMap();
 export const managedNodes = new WeakSet();
 
 // Find the dot path of a conditional node in the manifest.
-// Searches for the parent element, then appends the conditional's key.
+// Resolves the parent element through the reverse index, then appends the
+// conditional's key.
 const findConditionalPath = (node, manifest) => {
-  const parent = node.meta.startComment.parentNode;
-  const parentEntry = Object.entries(manifest).find(([_, el]) => el === parent);
-  if (!parentEntry) return null;
+  const parentPath = manifestPathOf(manifest, node.meta.startComment.parentNode);
+  if (parentPath === null) return null;
 
-  // Find which key this conditional has in the parent's children
-  // by matching the startComment reference
-  const [parentPath] = parentEntry;
   return `${parentPath}.${node._key}`;
 };
 
 // Register branch tree nodes in the manifest (recursive)
 const addBranchToManifest = (tree, manifest, basePath) => {
   if (tree.element) {
-    manifest[basePath] = tree.element;
+    setManifestEntry(manifest, basePath, tree.element);
   }
   if (tree.children) {
     for (const key in tree.children) {
@@ -71,6 +72,7 @@ export const extractDependencies = (expression) => {
   return [...new Set(matches)]; // Unique values
 };
 
+
 // Render all conditionals in the parsed tree
 export const renderAllConditionals = (tree, state, manifest, parentScope = {}) => {
   let count = 0;
@@ -81,8 +83,9 @@ export const renderAllConditionals = (tree, state, manifest, parentScope = {}) =
     return 1;
   }
 
-  // Recursively render conditionals in child nodes
-  if (tree.children) {
+  // Recursively render conditionals in child nodes — except under an
+  // outgoing wrapper, whose content the pending swap will replace wholesale.
+  if (tree.children && !(tree.element && isOutgoing(tree.element))) {
     Object.keys(tree.children).forEach((key) => {
       const child = tree.children[key];
       if (typeof child === 'object' && child !== null) {
@@ -94,6 +97,42 @@ export const renderAllConditionals = (tree, state, manifest, parentScope = {}) =
   return count;
 };
 
+// Re-settle every ALREADY-RENDERED conditional against the current world.
+// The boot's initial pass can run before module scripts have evaluated
+// (compiled shell: boot.js rides the vibe-module chain), so a gate on a
+// module-provided global — `<!-- if window.isDev -->` — first evaluates
+// against the pre-module world and carries no reactive dependency that would
+// ever re-check it. Walks like renderAllConditionals but routes through
+// updateConditional: value-unchanged branches are a no-op, changed ones
+// mount/unmount through the normal branch machinery.
+export const settleConditionals = (tree, state, manifest, parentScope = {}) => {
+  if (tree.type === 'conditional') {
+    updateConditional(tree, state, state, manifest, parentScope);
+    // A COMPILED pre-rendered conditional keeps its live content in
+    // `children` (never mountBranch'd) — nested conditionals there need
+    // settling too. Connected-root check skips a runtime conditional's
+    // detached template nodes.
+    if (tree.children) {
+      Object.keys(tree.children).forEach((key) => {
+        const child = tree.children[key];
+        if (!child || typeof child !== 'object') return;
+        const root = child.element ?? child.textNode;
+        if (!root || !root.isConnected) return;
+        settleConditionals(child, state, manifest, parentScope);
+      });
+    }
+    return;
+  }
+  if (tree.children && !(tree.element && isOutgoing(tree.element))) {
+    Object.keys(tree.children).forEach((key) => {
+      const child = tree.children[key];
+      if (typeof child === 'object' && child !== null) {
+        settleConditionals(child, state, manifest, parentScope);
+      }
+    });
+  }
+};
+
 // Initial render of a conditional block
 export const renderConditional = (node, state, manifest, parentScope = {}) => {
   const { expression, startComment, endComment, branches } = node.meta;
@@ -141,8 +180,13 @@ export const renderConditional = (node, state, manifest, parentScope = {}) => {
   // @ts-ignore - adding custom property to comment node
   startComment.__vibeRendered = true;
 
-  // Evaluate condition with current state
+  // Evaluate condition with current state — inside a tracking window, so the
+  // conditional subscribes to what its expression read from first render on.
+  const trackSub = nodeSubscriberOf(node, 'conditional');
+  trackSub.lastScope = state;
+  beginTracking(trackSub, overlayKeysOf(state));
   const conditionResult = evaluateCondition(expression, state, startComment.parentElement);
+  endTracking();
 
   // Determine which branch to mount
   const branchToMount = conditionResult ? branches.if : branches.else;
@@ -243,7 +287,7 @@ const mountBranch = (node, branchData, state, manifest, parentScope) => {
   // mounts (or re-mounts after unmount) must run its own scripts here to
   // re-register component-local state. Must happen BEFORE rendering nested
   // iterations/conditionals so `<!-- each _cN.x -->` sees the registered state.
-  executeCompiledComponentScriptsIn(clonedNodes);
+  const scriptsPending = executeCompiledComponentScriptsIn(clonedNodes);
 
   // Recursively render any nested iterations and conditionals
   if (branchTree) {
@@ -257,6 +301,31 @@ const mountBranch = (node, branchData, state, manifest, parentScope) => {
     nodes: clonedNodes,
     parsedTree: branchTree,
   };
+
+  // Import-bearing branch scripts run async through the script chain, so the
+  // eager render above may evaluate expressions before the window helpers those
+  // scripts define exist — and defining a global is not a state write, so no
+  // flush ever re-dispatches them (the fetch path never has this gap: it mounts
+  // DOM only after its scripts ran). Finish the mount when the chain settles:
+  // re-render this branch's directives against the fully-scripted world.
+  // Idempotent — rendered iterations early-return, value-unchanged conditionals
+  // are a no-op — and skipped when a remount superseded this instance.
+  //
+  // The settle evaluates CURRENT state (the live `$`), never the mount-time
+  // snapshot: state that legitimately changed while the imports were pending
+  // (a nested gate flipping true off a socket flush) already dispatched and
+  // mounted — settling against the stale snapshot would unmount it again.
+  // Loop-scoped branches keep their mount scope (the row's aliases aren't
+  // reachable from the root proxy); a row update supersedes activeInstance
+  // and the guard skips the settle entirely.
+  if (scriptsPending && branchTree) {
+    scriptsPending.then(() => {
+      if (node.runtime.activeInstance?.nodes !== clonedNodes) return;
+      const healState = node.meta.scopeAliases?.length ? scopedState : (window.$ ?? scopedState);
+      renderAllIterations(branchTree, healState, manifest, parentScope);
+      settleConditionals(branchTree, healState, manifest, parentScope);
+    });
+  }
 };
 
 // Unmount currently active branch
@@ -299,11 +368,34 @@ const unmountBranch = (node, manifest) => {
 
   // CLEANUP OF CURRENT STATE
   releaseOrphanedComponentState(ids);
+  // The swept range's binding subscribers are dead — their anchors just left
+  // the document. (The conditional's own subscriber survives: its anchor is
+  // the start comment, which stays.)
+  pruneDisconnected();
 
   // Clear active instance
   node.runtime.activeInstance = null;
 };
 
+// Subscription dispatch: flip the branch if the expression's value moved,
+// nothing else. Branch CONTENT updates arrive through the content's own
+// subscribers — re-walking the branch here (updateConditional's else path)
+// would reintroduce a partial walk per dirty conditional. A mounting branch
+// registers its fresh subscribers through initializeBlock's hydrate pass.
+export const dispatchConditional = (node, newState, manifest, parentScope = {}) => {
+  if (!node.runtime.templateRemoved) return;
+  const sub = nodeSubscriberOf(node, 'conditional');
+  sub.lastScope = newState;
+  beginTracking(sub, overlayKeysOf(newState));
+  const result = evaluateCondition(node.meta.expression, newState, node.meta.startComment?.parentElement);
+  endTracking();
+  const newBranchData = result ? node.meta.branches.if : node.meta.branches.else;
+  if (node.runtime.activeBranch !== newBranchData) {
+    mountBranch(node, newBranchData, newState, manifest, parentScope);
+    node.runtime.activeBranch = newBranchData;
+  }
+};
+
 // Update conditional when dependencies change
 export const updateConditional = (node, newState, oldState, manifest, parentScope = {}) => {
   const { expression, branches, startComment } = node.meta;
@@ -313,8 +405,13 @@ export const updateConditional = (node, newState, oldState, manifest, parentScop
     return;
   }
 
-  // Evaluate expression with new state
+  // Evaluate expression with new state — re-records the subscription every
+  // update, so branch-dependent reads self-heal.
+  const trackSub = nodeSubscriberOf(node, 'conditional');
+  trackSub.lastScope = newState;
+  beginTracking(trackSub, overlayKeysOf(newState));
   const newConditionResult = evaluateCondition(expression, newState, startComment?.parentElement);
+  endTracking();
   const newBranchData = newConditionResult ? branches.if : branches.else;
 
   // Check if branch changed (compare references)

package/runtime/debug.js

@@ -1,5 +1,29 @@
 import { DEBUGGER_NAME } from './constants.js';
 
+// Loud-in-debug evaluation failures. A typo'd binding must not fail silently
+// while developing — "let it crash in development" — while production keeps
+// the silent-undefined contract (a broken binding renders nothing, the page
+// survives). Once per expression: a broken binding re-evaluates every flush
+// and would otherwise firehose the console.
+// The affected-walk deliberately evaluates expressions in speculative
+// contexts (row templates against global state, conservative "can't prove
+// unaffected" probes) where throwing is expected and self-recovering. Those
+// are engine business — only RENDER-path failures are author business.
+let speculativeDepth = 0;
+export const beginSpeculative = () => {
+  speculativeDepth++;
+};
+export const endSpeculative = () => {
+  speculativeDepth--;
+};
+
+const reportedEvalErrors = new Set();
+export const reportEvalError = (expression, element, error) => {
+  if (!globalThis.__vibe?.debug || speculativeDepth > 0 || reportedEvalErrors.has(expression)) return;
+  reportedEvalErrors.add(expression);
+  console.error(`[vibe] Binding evaluation failed: @[${expression}]`, error, element ?? '');
+};
+
 // Phase colors - synced with index.css debug phase colors
 // Muted palette based on comment green (#6a9955)
 const PHASE_COLORS = {

package/runtime/dispatch.js

@@ -0,0 +1,172 @@
+// Subscription dispatch — subscribe mode's flush (phase 2 of auto-tracked
+// subscriptions). Where the walk answers "what changed?" by evaluating the
+// world, dispatch already knows: the flush's changed keys select their
+// subscribers from the reverse index, each re-evaluates in document order
+// through the SAME patch machinery the walk uses (hydrate's entry
+// dispatcher, mountBranch, updateIteration) and re-records its dependencies
+// while doing so. The walk itself retires to mount duty — first hydration,
+// processMutations, branch mounts — where it keeps registering fresh
+// subscribers.
+import hydrate from './hydrate.js';
+import { updateIteration } from './iterate.js';
+import { dispatchConditional } from './conditionals.js';
+import { beginTracking, endTracking, unsubscribe } from './tracking.js';
+import { activeOutgoingRoots, outgoingRootOf, isRemountTrigger } from './staging.js';
+import {
+  scopedOverlayOf,
+  rememberOverlay,
+  overlayKeysOf,
+  evalInScope,
+  resolveThisPath,
+} from './utils.js';
+import { resolvePath } from './iteration-utils.js';
+
+// Rebuild a row subscriber's evaluation scope against the CURRENT globals.
+// The scope it last evaluated in is a per-flush merged snapshot (stale
+// globals); only its alias overlay is durable — item/index identity is owned
+// by the iteration's diff, which rebuilds rows whenever it changes.
+export const scopeFor = (sub, base) => {
+  const overlay = sub.lastScope ? scopedOverlayOf(sub.lastScope) : null;
+  if (!overlay) return base;
+  const merged = { ...base, ...overlay };
+  rememberOverlay(merged, overlay);
+  return merged;
+};
+
+// The plan's iteration shallow-compare, generalized from the walk's
+// CALL_EXPR fresh-ref fix: same length + same item refs as the rendered
+// instances ⇒ the rows are already right (outer-state bindings inside rows
+// are their own subscribers). Ref inequality — including a reassigned array
+// after in-place mutation — falls through to the full diff.
+export const rowsShallowEqual = (instances, newArray) =>
+  instances.length === newArray.length &&
+  instances.every((inst, i) => inst.item === newArray[i]);
+
+// A text node's interpolation group renders all-or-nothing (hydrate
+// re-interpolates the whole span), so one dirty binding expands to entries
+// for every binding in its group.
+export const entriesForText = (sub, scope) => {
+  const e = sub.entry;
+  const group = e.binding?._group ?? [e.binding];
+  return group.map((m) => ({
+    matchOuter: m.outer,
+    matchInner: m.inner,
+    input: m.input,
+    element: e.element,
+    textNode: e.textNode,
+    scopedState: scope,
+    binding: m,
+  }));
+};
+
+// Document-order sort over subscriber anchors — the walk is document-ordered
+// and the corpus expects that stability. Bit 4 = FOLLOWING, 2 = PRECEDING.
+const docOrder = (a, b) => {
+  const x = a.anchor;
+  const y = b.anchor;
+  if (x === y || !x?.compareDocumentPosition || !y) return 0;
+  const pos = x.compareDocumentPosition(y);
+  if (pos & 4) return -1;
+  if (pos & 2) return 1;
+  return 0;
+};
+
+const dispatchIteration = (sub, currentState, previousState, manifest) => {
+  const node = sub.node;
+  // Not yet rendered — the mount path owns first render.
+  if (!node.runtime.instances || !node.runtime.templateRemoved) return;
+  const scope = scopeFor(sub, currentState);
+  const parentEl = node.meta.startComment?.parentElement;
+  const resolvedExpr = resolveThisPath(node.meta.arrayPath, parentEl);
+  beginTracking(sub, overlayKeysOf(scope));
+  const newArray =
+    evalInScope(resolvedExpr, scope, parentEl) ?? resolvePath(scope, resolvedExpr);
+  endTracking();
+  const instances = node.runtime.instances;
+  const treeless = instances.length > 0 && !instances[0].tree;
+  // Treeless (batch/compiled) rows skip the shallow guard — their HTML may
+  // read non-array state; updateIteration's identical-HTML check absorbs
+  // no-ops there.
+  if (!treeless && Array.isArray(newArray) && rowsShallowEqual(instances, newArray)) return;
+  updateIteration(node, scope, scopeFor(sub, previousState), manifest);
+};
+
+// The subscribe-mode flush: document-ordered dirty set → patch. Binding
+// entries batch through single hydrate calls between structural ops so
+// relative order is preserved (and hydrate's same-element input chaining
+// keeps working).
+export default (dirty, currentState, previousState, manifest) => {
+  const subs = [...dirty].sort(docOrder);
+  // Remount triggers (a wrapper's own src/key binding) hydrate FLUSH-WIDE
+  // FIRST: they register the outgoing roots every later entry's freeze-skip
+  // and parking depend on. The walk got this ordering from hydrate's
+  // per-call two-pass; dispatch splits into multiple hydrate calls at
+  // structural boundaries, so the hoist must span the whole flush.
+  const triggers = [];
+  const rest = [];
+  for (const sub of subs) {
+    if (sub.anchor && !sub.anchor.isConnected) {
+      unsubscribe(sub);
+      continue;
+    }
+    // Already-frozen subtree (a staging window spanning flushes): skip.
+    if (activeOutgoingRoots.size && outgoingRootOf(sub.anchor)) continue;
+    (sub.entry && isRemountTrigger(sub.entry) ? triggers : rest).push(sub);
+  }
+  if (triggers.length > 0) {
+    hydrate(
+      triggers.map((s) => ({ ...s.entry, scopedState: scopeFor(s, currentState) })),
+      currentState,
+      manifest,
+      previousState,
+    );
+  }
+  const seenGroups = new Set();
+  let batch = [];
+  const flushBatch = () => {
+    if (batch.length > 0) {
+      hydrate(batch, currentState, manifest, previousState);
+      batch = [];
+    }
+  };
+  for (const sub of rest) {
+    // Died mid-flush: an earlier structural op (iteration diff, branch flip)
+    // tore this subscriber's DOM down after beginFlush selected it. The lazy
+    // self-prune, at dispatch time.
+    if (sub.anchor && !sub.anchor.isConnected) {
+      unsubscribe(sub);
+      continue;
+    }
+    // Frozen mid-flush: a trigger above marked this subscriber's page
+    // outgoing — its DOM is replaced wholesale at the commit, so rendering
+    // it against post-navigation state is the mid-navigation collapse the
+    // freeze exists to prevent. Subscriptions stay; the swap's removal
+    // prunes them lazily via isConnected. (Ancestor styling bindings park
+    // inside hydrate — same seam the walk uses.)
+    if (activeOutgoingRoots.size && outgoingRootOf(sub.anchor)) continue;
+    if (sub.kind === 'conditional') {
+      flushBatch();
+      dispatchConditional(sub.node, scopeFor(sub, currentState), manifest);
+      continue;
+    }
+    if (sub.kind === 'iteration') {
+      flushBatch();
+      dispatchIteration(sub, currentState, previousState, manifest);
+      continue;
+    }
+    const e = sub.entry;
+    if (!e) continue;
+    const scope = scopeFor(sub, currentState);
+    if (e.type === 'attribute' || e.type === 'nameBinding') {
+      batch.push({ ...e, scopedState: scope });
+    } else {
+      const group = e.binding?._group;
+      if (group) {
+        if (seenGroups.has(group)) continue;
+        seenGroups.add(group);
+      }
+      batch.push(...entriesForText(sub, scope));
+    }
+  }
+  flushBatch();
+};