@ape-egg/vibe 2.3.0 → 3.0.0

package/runtime/parse.js

@@ -1,8 +1,14 @@
-import { findEndComment, findConditionalEnd, parseIterationHeader } from './iteration-utils.js';
+import {
+  findEndComment,
+  findEndCommentIndex,
+  findConditionalEnd,
+  parseIterationHeader,
+} from './iteration-utils.js';
 import {
   NON_REACTIVE_ELEMENTS,
   BINDING_REGEX,
   CONDITIONAL_REGEX,
+  ITERATION_START_REGEX,
   DOM_ELEMENT_PROPERTIES,
   DEHYDRATE_CLASS_OR_ATTR,
   THIS_PROP_REGEX,
@@ -18,6 +24,18 @@ const findComponentIdForElement = (element) => {
   return wrapper ? wrapper.getAttribute('data-vibe-component-id') : null;
 };
 
+// `key` is reserved on fetched-component wrappers and remounts on CHANGE — a
+// literal key can never change, so it can never fire. Warn once per value
+// instead of dying silently (reparses would otherwise spam).
+const warnedStaticKeys = new Set();
+const warnStaticKey = (key) => {
+  if (warnedStaticKeys.has(key)) return;
+  warnedStaticKeys.add(key);
+  console.warn(
+    `[vibe] <component key="${key}"> is static — key remounts on CHANGE, so a literal never fires. Bind it (key="@[expr]") or remove it.`,
+  );
+};
+
 // Single source of truth for reading attribute/name bindings off an element.
 // Called from both the root handler and recursive() so they can't drift. Any
 // element classified as a fetched component (`<component src>` or
@@ -44,6 +62,7 @@ const captureAttributeBindings = (element, aliasSet) => {
     if (BINDING_REGEX.test(src)) attributes.src = src;
     BINDING_REGEX.lastIndex = 0;
     if (key && BINDING_REGEX.test(key)) attributes.key = key;
+    else if (key) warnStaticKey(key);
     return {
       attributes: Object.keys(attributes).length ? attributes : null,
       nameBindings: null,
@@ -169,7 +188,39 @@ const recursive = (children, rootKey = undefined, skipIndices = new Set(), stats
 
     // Handle iteration comments
     if (nodeName === '#comment') {
-      const iterationMatch = parseIterationHeader(textContent.trim());
+      const trimmedComment = textContent.trim();
+      const iterationMatch = parseIterationHeader(trimmedComment);
+
+      // An each-shaped comment that fails the grammar, WITH a matching /each,
+      // is an authored directive with a syntax error — code, not prose. It
+      // used to render its body once, silently: the framework's worst
+      // footgun. Directives scream like a SyntaxError in every mode. (A
+      // prose comment merely starting with "each", no /each below, stays an
+      // inert comment.)
+      if (
+        !iterationMatch &&
+        ITERATION_START_REGEX.test(trimmedComment) &&
+        findEndCommentIndex(children, i + 1) !== -1
+      ) {
+        console.error(
+          `[vibe] Malformed each directive: <!-- ${trimmedComment} -->\n` +
+            'Expected <!-- each items as item -->, with optional ", index" and "(key)" in either order — e.g. <!-- each items as item (item.id), i -->',
+        );
+      }
+
+      // A bare <!-- if --> / <!-- else if --> (no expression) with a
+      // matching /if ahead is the same class of authored error.
+      if (/^if$/.test(trimmedComment) || /^else\s+if$/.test(trimmedComment)) {
+        try {
+          findConditionalEnd(children, i + 1);
+          console.error(
+            `[vibe] Malformed ${trimmedComment.startsWith('else') ? 'else if' : 'if'} directive: <!-- ${trimmedComment} --> has no expression.\n` +
+              'Expected <!-- if condition --> ... <!-- else if condition --> ... <!-- /if -->',
+          );
+        } catch {
+          // No /if below — an inert comment.
+        }
+      }
 
       if (iterationMatch) {
         const { arrayPath, itemAlias, keyExpr, indexAlias } = iterationMatch;
@@ -269,8 +320,8 @@ const recursive = (children, rootKey = undefined, skipIndices = new Set(), stats
         const [_, expression] = conditionalMatch;
 
         try {
-          // Find matching end comment and optional else
-          const { elseIndex, endIndex } = findConditionalEnd(children, i + 1);
+          // Find matching end comment and optional else / else-if boundary
+          const { elseIndex, endIndex, elseText } = findConditionalEnd(children, i + 1);
 
           // Extract true branch nodes (between if and else/endif)
           const trueBranchEnd = elseIndex !== null ? elseIndex : endIndex;
@@ -286,15 +337,28 @@ const recursive = (children, rootKey = undefined, skipIndices = new Set(), stats
           // inside a conditional nested within an iteration).
           const trueBranchParsed = recursive([...trueBranchContainer.childNodes], undefined, new Set(), stats, aliasSet);
 
-          // Extract false branch nodes if else exists
+          // Extract false branch nodes if else exists. An `else if` boundary
+          // DESUGARS: the false branch becomes a synthesized nested
+          // conditional (`<!-- if rest -->…<!-- /if -->` wrapping the chain
+          // tail), so every mount/patch/manifest path only ever sees binary
+          // conditionals — else-if is grammar, not machinery. The chain tail
+          // may itself contain further else-if boundaries; the recursion
+          // desugars them the same way.
           let falseBranchParsed = null;
           let falseBranchContainer = null;
           if (elseIndex !== null) {
             const falseBranchNodes = Array.from(children).slice(elseIndex + 1, endIndex);
             falseBranchContainer = document.createElement('div');
+            const chained = elseText !== 'else';
+            if (chained) {
+              falseBranchContainer.appendChild(
+                document.createComment(` ${elseText.replace(/^else\s+/, '')} `),
+              );
+            }
             falseBranchNodes.forEach((node) => {
               falseBranchContainer.appendChild(node.cloneNode(true));
             });
+            if (chained) falseBranchContainer.appendChild(document.createComment(' /if '));
             falseBranchParsed = recursive([...falseBranchContainer.childNodes], undefined, new Set(), stats, aliasSet);
           }
 

package/runtime/pre-compiled-iterations.js

@@ -125,6 +125,7 @@ export const renderCompiled = (iterationNode, array, state, compiledMeta, parent
 
     parent.insertBefore(frag, endComment);
     iterationNode.runtime.instances = instances;
+    iterationNode.runtime.lastCompiledHtml = html;
     stampInstanceScopes(iterationNode);
     return true;
   }
@@ -137,9 +138,22 @@ export const renderCompiled = (iterationNode, array, state, compiledMeta, parent
  */
 export const updateCompiled = (iterationNode, newArray, state, compiledMeta, startComment, endComment) => {
   const parent = startComment.parentNode;
+  const rt = iterationNode.runtime;
+
+  const html = newArray.length === 0 ? '' : callCompiled(iterationNode, newArray, state, compiledMeta);
+  if (html === null) return false;
+
+  // Keep-DOM guard, same contract as the runtime batch renderer: compiled
+  // iterations sit in the always-dirty bucket, so every flush of ANY key
+  // lands here — identical output must keep the existing rows (imperative
+  // listeners, focus, markers die with deleteContents), not rebuild them.
+  if (html === rt.lastCompiledHtml && rt.instances.length === newArray.length) {
+    for (let i = 0; i < newArray.length; i++) rt.instances[i].item = newArray[i];
+    return true;
+  }
 
   // Clear existing instances
-  if (iterationNode.runtime.instances.length > 0) {
+  if (rt.instances.length > 0) {
     const range = document.createRange();
     range.setStartAfter(startComment);
     range.setEndBefore(endComment);
@@ -147,13 +161,11 @@ export const updateCompiled = (iterationNode, newArray, state, compiledMeta, sta
   }
 
   if (newArray.length === 0) {
-    iterationNode.runtime.instances = [];
+    rt.instances = [];
+    rt.lastCompiledHtml = '';
     return true;
   }
 
-  const html = callCompiled(iterationNode, newArray, state, compiledMeta);
-  if (html === null) return false;
-
   // Parse and insert
   if (parseTemplate) {
     parseTemplate.innerHTML = html;
@@ -168,7 +180,8 @@ export const updateCompiled = (iterationNode, newArray, state, compiledMeta, sta
     }
 
     parent.insertBefore(frag, endComment);
-    iterationNode.runtime.instances = instances;
+    rt.instances = instances;
+    rt.lastCompiledHtml = html;
     stampInstanceScopes(iterationNode);
     return true;
   }

package/runtime/pre-compiled-manifest.js

@@ -252,13 +252,22 @@ const detectHyperspeed = async () => {
   const skipNetwork = !!document.querySelector("[vibe-fouc], .vibe-fouc");
 
   try {
+    // window.__MANIFEST__ is an explicit manifest URL stamped into the page by
+    // the build/dev server. The compiled SPA shell needs it: the shell is
+    // served for EVERY route, so pathname-derived candidates point at manifests
+    // that don't exist (deep links probed 404s and never found the shell's own
+    // manifest). When present it is the single, authoritative candidate.
+    //
     // window.__ROUTE__ is the page's route template (e.g. "/brawlers/:index"),
     // injected by the compiler/dev server for dynamic pages. It lets us resolve
     // the tokenized `$` manifest directly instead of probing literal 404s.
-    const possiblePaths = buildManifestCandidatePaths(
-      window.location.pathname,
-      typeof window !== "undefined" ? window.__ROUTE__ : null,
-    );
+    const hinted = typeof window !== "undefined" ? window.__MANIFEST__ : null;
+    const possiblePaths = hinted
+      ? [hinted]
+      : buildManifestCandidatePaths(
+          window.location.pathname,
+          typeof window !== "undefined" ? window.__ROUTE__ : null,
+        );
 
     if (possiblePaths.length === 0) return null;
 

package/runtime/staging.js

@@ -0,0 +1,153 @@
+// Navigation staging — the one-paint commit machinery behind reactive-src /
+// keyed remounts, owned in one place. A remount marks the mounted wrapper
+// OUTGOING: it keeps the screen — visible, styled, frozen — while the
+// incoming wrapper hydrates as a display:none sibling ([vibe-staged]). The
+// commit swaps the two and replays parked ancestor bindings in one
+// synchronous step: navigation paints exactly once, never an unstyled or
+// blank frame between.
+//
+// Every consumer answers its question through THIS module:
+//   isOutgoing(el)      tree walks — skip collecting under a frozen wrapper
+//   outgoingRootOf(n)   dispatch — is this subscriber inside a frozen page?
+//   parkRootFor(el)     hydrate — is a frozen page inside this element? then
+//                       park the binding (it is the styling context AROUND
+//                       the outlet — flipping it mid-stage un-styles the
+//                       visible page) and let the commit replay it
+//   stage/commit/abandon  component.js's mount finalize drives transitions
+
+// The mount pipeline replaces wrappers (finalize's replaceWith), leaving a
+// `_vibeReplacedBy` link behind. Trees and clone lists keep ORIGINAL nodes —
+// follow the chain to the live one, compressing so intermediate detached
+// wrappers stay collectable.
+export const liveNode = (node) => {
+  let live = node;
+  while (live && live._vibeReplacedBy) live = live._vibeReplacedBy;
+  if (live !== node && node) node._vibeReplacedBy = live;
+  return live;
+};
+
+// Wrappers whose mounted content is outgoing — a remount is in flight.
+export const activeOutgoingRoots = new Set();
+
+export const isOutgoing = (element) => !!(element && liveNode(element)._vibeOutgoing);
+
+export const markOutgoing = (el) => {
+  el._vibeOutgoing = true;
+  activeOutgoingRoots.add(el);
+};
+
+export const releaseOutgoing = (el) => {
+  el._vibeOutgoing = false;
+  activeOutgoingRoots.delete(el);
+};
+
+// The outgoing root STRICTLY containing `node`, or null. The root's own
+// src/key/prop bindings stay live (a rapid next navigation must re-trigger);
+// everything beneath it is replaced wholesale at the swap, so re-rendering
+// it against post-navigation state is pure waste — and was the visible
+// mid-navigation collapse.
+export const outgoingRootOf = (node) => {
+  if (!activeOutgoingRoots.size || !node) return null;
+  for (const root of activeOutgoingRoots) {
+    if (root !== node && root.contains?.(node)) return root;
+  }
+  return null;
+};
+
+// The outgoing root strictly INSIDE `element`, or null — the park direction:
+// `element` is the styling context around the outlet (the game's
+// `<page @[page.name]>`). Zero cost when nothing is staging.
+export const parkRootFor = (element) => {
+  if (!activeOutgoingRoots.size || !element) return null;
+  for (const root of activeOutgoingRoots) {
+    if (root !== element && element.contains?.(root)) return root;
+  }
+  return null;
+};
+
+// Parked updates live on the outgoing wrapper (Map<element, Map<key, apply>>)
+// keyed by element + binding so rapid flushes during staging keep only the
+// latest value; the commit replays them in its synchronous swap step.
+export const parkBinding = (root, element, key, apply) => {
+  const parked = (root._vibeParkedBindings ??= new Map());
+  let perElement = parked.get(element);
+  if (!perElement) parked.set(element, (perElement = new Map()));
+  perElement.set(key, apply);
+};
+
+const replayParked = (old) => {
+  const parked = old._vibeParkedBindings;
+  if (!parked) return;
+  for (const perElement of parked.values()) {
+    for (const apply of perElement.values()) apply();
+  }
+  old._vibeParkedBindings = null;
+};
+
+// A fetched-component host: `<component>` or `<div class="component">`.
+export const isComponentWrapper = (el) =>
+  el.nodeName === 'COMPONENT' ||
+  (el.nodeName === 'DIV' && el.classList?.contains('component'));
+
+// A flush entry that (re)mounts: the wrapper's own src/key binding. These
+// process FLUSH-WIDE FIRST — they register the outgoing roots every other
+// entry's freeze-skip and parking decisions depend on. (Tree-walk order gave
+// the walk this for free within one pass; dispatch batches must hoist.)
+export const isRemountTrigger = (entry) =>
+  entry.type === 'attribute' &&
+  (entry.attrName === 'src' || entry.attrName === 'key') &&
+  !!entry.element &&
+  isComponentWrapper(entry.element);
+
+// ————— staged swap transitions (driven by component.js finalize) —————
+
+// Mount landed for an outgoing wrapper: stage the incoming wrapper, don't
+// swap. A superseded staged wrapper (rapid re-navigation) was never visible:
+// drop it immediately and inherit the ORIGINAL visible page as this mount's
+// commit target.
+export const stageIncoming = (el, newWrapper) => {
+  if (el.hasAttribute('vibe-staged')) {
+    newWrapper._vibeCommitOld = el._vibeCommitOld;
+    activeOutgoingRoots.delete(el);
+    newWrapper.setAttribute('vibe-staged', '');
+    el.replaceWith(newWrapper);
+  } else {
+    newWrapper._vibeCommitOld = el;
+    newWrapper.setAttribute('vibe-staged', '');
+    // The outgoing wrapper is no longer a mount request — with the src
+    // attribute still on it, every processComponent rescan would treat it as
+    // unresolved and mount a second copy while it holds the screen.
+    el.removeAttribute('src');
+    el.after(newWrapper);
+  }
+};
+
+// Atomic visual commit: old page out, parked styling-context bindings
+// applied, new page revealed — one synchronous block, one paint.
+export const commitStaged = (newWrapper) => {
+  const old = newWrapper._vibeCommitOld;
+  if (old) {
+    old.remove();
+    activeOutgoingRoots.delete(old);
+    replayParked(old);
+    newWrapper._vibeCommitOld = null;
+  }
+  newWrapper.removeAttribute('vibe-staged');
+};
+
+// Incoming wrapper died before its commit (unmounted mid-hydration, or
+// removed by something outside the staging machinery — $.reconcile on an
+// ancestor, app code pruning the container): no swap is coming. Release the
+// frozen old page — connected, it must resume updating; detached, the Set
+// entry would pin the subtree forever — and reverse the replaced-by link so
+// chains compressed onto the dead staged wrapper resolve back to the page
+// that stayed (its src binding must act on IT again, or no later navigation
+// can ever remount).
+export const abandonStaged = (newWrapper) => {
+  const old = newWrapper._vibeCommitOld;
+  if (!old) return;
+  newWrapper._vibeCommitOld = null;
+  releaseOutgoing(old);
+  old._vibeReplacedBy = null;
+  newWrapper._vibeReplacedBy = old;
+};

package/runtime/state.js

@@ -1,3 +1,5 @@
+import { recordRead } from './tracking.js';
+
 // Track which objects are already proxied to avoid double-wrapping
 const proxyCache = new WeakMap();
 
@@ -15,6 +17,29 @@ const RAW = Symbol('vibeRaw');
 const unwrap = (value) =>
   value !== null && typeof value === 'object' && value[RAW] !== undefined ? value[RAW] : value;
 
+// Write a property onto the proxy's raw target without waking the reactive
+// pipeline — no changedProps, no flush. For writes that reactivity can prove
+// irrelevant: a freshly generated component id has no live bindings yet (its
+// subtree hydrates later in the same batch by reading state directly), so
+// flushing on registration re-walks the whole live tree for nothing. Reads
+// through the proxy see the value immediately; later writes through the
+// proxy flush normally.
+export const silentSet = (proxy, prop, value) => {
+  const raw = proxy !== null && typeof proxy === 'object' ? (proxy[RAW] ?? proxy) : proxy;
+  raw[prop] = unwrap(value);
+};
+
+// Mark a batch of already-written keys changed and schedule one flush — the
+// commit half of silentSet. A mount registers N component states silently as
+// its scripts settle (staggered by module fetches), then notifies ONCE, so
+// whole-`$` observers (`@[Object.keys($)...]`) still see every fresh key
+// with a single tree walk instead of N.
+export const notifyChanged = (props) => {
+  if (!props || props.length === 0) return;
+  for (const prop of props) changedProps.add(prop);
+  scheduleFlush();
+};
+
 // Batching: collect mutations and flush once per microtask
 let pendingFlush = false;
 let flushCallback = null;
@@ -95,6 +120,12 @@ const createDeepProxy = (target, rerender, rootState = null, rootProp = null) =>
       // recover the unproxied object from any of our proxies.
       if (prop === RAW) return target;
 
+      // Subscription tracking: a read inside an open tracking window records
+      // the ROOT key it descended from. This is what makes helper bodies
+      // truthful dependencies — `isPremium()` reading `$.premiumUntil` via
+      // closure lands here mid-evaluation. One null check when inactive.
+      recordRead(rootProp === null ? prop : rootProp);
+
       const value = Reflect.get(target, prop);
 
       // Don't proxy non-objects, functions, null, or Promises.

package/runtime/tracking.js

@@ -0,0 +1,173 @@
+// Auto-tracked reactive subscriptions — the knowledge half of the update
+// engine. Each reactive obligation (a text-binding span, an attribute or name
+// binding, a conditional, an iteration) is a SUBSCRIBER; during its
+// evaluation a tracking window is open and every genuine state read that
+// happens inside it — proxy get traps, evalInScope's state-first parameter
+// resolution, `$.key` reads on snapshots, scoped-state global fallthrough —
+// records the ROOT state key into the window. Closing the window commits the
+// read set to a reverse index (rootKey → Set<subscriber>), replacing the
+// subscriber's previous deps wholesale so conditional branches self-heal
+// (`a ? $.x : $.y` re-subscribes as it flips). A write then answers "who
+// cares?" from the index instead of walking the world.
+//
+// Granularity is deliberately root-key only — the same granularity as
+// state.js's changedProps. Recording is active ONLY inside a window: app
+// code (handlers, boot scripts, intervals) never tracks, and the inactive
+// path is a single null check.
+
+// Stack of open windows — nesting is tolerated (a subscriber's eval that
+// transitively evaluates another registers each read against the window that
+// was open when it happened), though engine call sites keep windows tight
+// around single evaluations.
+let windows = [];
+let active = null;
+
+// rootKey → Set<subscriber>
+const keyIndex = new Map();
+// Conservative bucket: subscribers whose evaluation read NO tracked key at
+// all (module-level caches, Date.now(), Object.keys($) enumeration). Can't
+// prove what they depend on, so they re-evaluate on every flush — the same
+// contract the walk's "no known state key ⇒ affected" check gives today.
+const alwaysSubs = new Set();
+// subscriber → its committed dep Set (empty Set = scope-only, owned by its
+// iteration's diff; absent = never tracked/unsubscribed)
+const subDeps = new Map();
+
+// Open a window for `sub`. `skipKeys` names the scope-alias keys of the
+// evaluation state (loop `item`/`index` overlays) — reads of those are the
+// row's own scope, owned by the iteration's diff lifecycle, so they mark the
+// window scope-touched instead of subscribing.
+export const beginTracking = (sub, skipKeys = null) => {
+  active = { sub, skipKeys, reads: new Set(), absent: new Set(), sawScope: false };
+  windows.push(active);
+};
+
+export const endTracking = () => {
+  const w = windows.pop();
+  active = windows.length ? windows[windows.length - 1] : null;
+  if (w) commit(w);
+};
+
+const dropFromBuckets = (sub, deps) => {
+  for (const key of deps) {
+    const bucket = keyIndex.get(key);
+    if (bucket) {
+      bucket.delete(sub);
+      if (bucket.size === 0) keyIndex.delete(key);
+    }
+  }
+};
+
+const commit = ({ sub, reads, absent, sawScope }) => {
+  const prev = subDeps.get(sub);
+  if (prev) dropFromBuckets(sub, prev);
+  alwaysSubs.delete(sub);
+
+  // Only LIVE reads count toward "this subscriber has provable deps" — an
+  // eval that read no present state key keeps the walk's re-evaluate-on-any-
+  // flush contract even when absent identifiers were seen (they may be plain
+  // globals forever). Scope-only evals stay out of the always-bucket: the
+  // row's iteration is subscribed and owns the row.
+  if (reads.size === 0 && !sawScope) alwaysSubs.add(sub);
+
+  // Absent identifiers still index: if the key is ever CREATED, that flush
+  // must select this subscriber — the walk got this by token-matching against
+  // the NEW state's key set every cycle. Same for delete-then-recreate: the
+  // post-delete re-eval keeps the key as an absent dep.
+  const deps = absent.size === 0 ? reads : new Set([...reads, ...absent]);
+  for (const key of deps) {
+    let bucket = keyIndex.get(key);
+    if (!bucket) keyIndex.set(key, (bucket = new Set()));
+    bucket.add(sub);
+  }
+  subDeps.set(sub, deps);
+};
+
+// The single recording entry point — called from state.js's get trap,
+// evalInScope's parameter resolution, dollarFor's snapshot wrapper, and
+// createScopedState's global fallthrough. One null check when inactive.
+export const recordRead = (key) => {
+  if (active === null || typeof key !== 'string') return;
+  if (active.skipKeys !== null && active.skipKeys.has(key)) {
+    active.sawScope = true;
+    return;
+  }
+  active.reads.add(key);
+};
+
+// A read that MISSED the state (identifier absent at evaluation time —
+// evalInScope's global fallback, dollarFor's non-key miss). Indexed so the
+// key's later creation dispatches this subscriber, but not counted as a live
+// dep — see commit.
+export const recordAbsentRead = (key) => {
+  if (active === null || typeof key !== 'string') return;
+  if (active.skipKeys !== null && active.skipKeys.has(key)) {
+    active.sawScope = true;
+    return;
+  }
+  active.absent.add(key);
+};
+
+// Union of subscribers for a set of changed root keys, plus the conservative
+// always-bucket. Callers filter liveness (anchor.isConnected) at use time.
+export const subscribersOf = (keys) => {
+  const out = new Set(alwaysSubs);
+  for (const key of keys) {
+    const bucket = keyIndex.get(key);
+    if (bucket) for (const sub of bucket) out.add(sub);
+  }
+  return out;
+};
+
+export const depsOf = (sub) => subDeps.get(sub);
+
+// Force a subscriber into the conservative always-bucket. Batch/compiled
+// iterations use this: their row HTML is produced by a compiled function
+// closing over every state key, so "re-evaluate on any change" is exactly
+// the walk's contract for them (the identical-HTML guard absorbs no-ops).
+export const markAlways = (sub) => {
+  const prev = subDeps.get(sub);
+  if (prev) dropFromBuckets(sub, prev);
+  alwaysSubs.add(sub);
+  subDeps.set(sub, new Set());
+};
+
+export const unsubscribe = (sub) => {
+  const prev = subDeps.get(sub);
+  if (prev) dropFromBuckets(sub, prev);
+  alwaysSubs.delete(sub);
+  subDeps.delete(sub);
+};
+
+// Drop every subscriber whose anchor node has left the document. Called on
+// teardown batches (mutation removals, iteration row release, branch
+// unmount) — O(subscribers), same cost class as the manifest sweep.
+export const pruneDisconnected = () => {
+  for (const sub of subDeps.keys()) {
+    if (sub.anchor && !sub.anchor.isConnected) unsubscribe(sub);
+  }
+};
+
+// Called at the top of a state flush with the changed root keys. Returns the
+// dirty set — every live subscriber of those keys plus the conservative
+// always-bucket. Dead subscribers found here unsubscribe on the spot (the
+// lazy self-prune).
+export const beginFlush = (changedKeys) => {
+  const dirty = new Set();
+  for (const sub of subscribersOf(changedKeys)) {
+    if (sub.anchor && sub.anchor.isConnected === false) {
+      unsubscribe(sub);
+      continue;
+    }
+    dirty.add(sub);
+  }
+  return dirty;
+};
+
+export const resetTracking = () => {
+  windows = [];
+  active = null;
+  keyIndex.clear();
+  alwaysSubs.clear();
+  subDeps.clear();
+};