@zakkster/lite-signal 1.2.1 → 1.2.2

package/Signal.d.ts

@@ -1,10 +1,10 @@
 /**
- * @zakkster/lite-signal — zero-GC reactive graph.
+ * @zakkster/lite-signal -- zero-GC reactive graph.
  *
  * Public type surface for the JavaScript implementation in `Signal.js`.
  */
 
-// ─── Options ──────────────────────────────────────────────────────────────────
+// --- Options ------------------------------------------------------------------
 
 /** Equality predicate. Returning `true` halts propagation. */
 export type EqualsFn<T> = (a: T, b: T) => boolean;
@@ -45,7 +45,7 @@ export type Dispose = () => void;
  */
 export type Disposable<T = unknown> = Signal<T> | Computed<T> | Dispose;
 
-// ─── Reactive primitive shapes ────────────────────────────────────────────────
+// --- Reactive primitive shapes ------------------------------------------------
 
 /** Reactive source of truth. */
 export interface Signal<T> {
@@ -71,7 +71,7 @@ export interface Computed<T> {
     subscribe(fn: (value: T) => void): Dispose;
 }
 
-// ─── Diagnostics ──────────────────────────────────────────────────────────────
+// --- Diagnostics --------------------------------------------------------------
 
 export interface RegistryStats {
     /** Number of signals created in this registry's lifetime. */
@@ -92,7 +92,7 @@ export interface RegistryStats {
     activeNodes: number;
 }
 
-// ─── Observer-lifecycle introspection (1.1.4) ─────────────────────────────────
+// --- Observer-lifecycle introspection (1.1.4) ---------------------------------
 
 /** Whether a described node is a signal, a computed, or an effect. */
 export type NodeKind = "signal" | "computed" | "effect";
@@ -109,9 +109,9 @@ export interface NodeDescriptor {
 
 /** Transition callbacks for {@link Registry.observeObservers}. */
 export interface ObserveObserversHooks {
-    /** Fired on the 0→1 observer transition (after registration). */
+    /** Fired on the 0->1 observer transition (after registration). */
     onConnect?: () => void;
-    /** Fired on the 1→0 observer transition. */
+    /** Fired on the 1->0 observer transition. */
     onDisconnect?: () => void;
 }
 
@@ -121,25 +121,25 @@ export type Unobserve = () => void;
 /** Anything carrying a node identity that the introspection surface can read. */
 export type ReactiveHandle = Signal<any> | Computed<any>;
 
-// ─── Graph-mutation hook (1.2.1) ──────────────────────────────────────────────
+// --- Graph-mutation hook (1.2.1) ----------------------------------------------
 
 /**
  * Opcode passed as the first argument to a {@link GraphMutationListener}.
  *
  *  - `1` node create.    `(intA, intB) = (node.id, node.flags)`.
- *  - `2` node dispose.   `(intA, intB) = (node.id, node.flags)` — fires for every node
+ *  - `2` node dispose.   `(intA, intB) = (node.id, node.flags)` -- fires for every node
  *                        disposed, including cascaded owner-tree children.
  *  - `3` link add.       `(intA, intB) = (source.id, target.id)`.
- *  - `4` link remove.    `(intA, intB) = (source.id, target.id)` — `-1` if the link
+ *  - `4` link remove.    `(intA, intB) = (source.id, target.id)` -- `-1` if the link
  *                        was already nulled (defensive, rare).
- *  - `5` recompute.      `(intA, intB) = (node.id, 0)` — fires just before an effect
+ *  - `5` recompute.      `(intA, intB) = (node.id, 0)` -- fires just before an effect
  *                        re-run or a computed re-eval.
  */
 export type GraphMutationOpcode = 1 | 2 | 3 | 4 | 5;
 
 /**
  * Listener registered with {@link Registry.onGraphMutation}. Called synchronously
- * inside each mutation point with three integers — no objects allocated.
+ * inside each mutation point with three integers -- no objects allocated.
  *
  * **Contract: observe only.** Listeners MUST NOT throw and MUST NOT mutate the
  * graph from inside the callback. Both will corrupt the engine's state. Wrap any
@@ -150,7 +150,7 @@ export type GraphMutationListener = (opcode: GraphMutationOpcode, intA: number,
 /** Idempotent unsubscriber returned by {@link Registry.onGraphMutation}. */
 export type GraphMutationUnsubscribe = () => void;
 
-// ─── Errors ───────────────────────────────────────────────────────────────────
+// --- Errors -------------------------------------------------------------------
 
 /** Thrown when a pool ceiling is hit. */
 export class CapacityError extends Error {
@@ -160,7 +160,7 @@ export class CapacityError extends Error {
     constructor(kind: "nodes" | "links", capacity: number);
 }
 
-// ─── Registry ─────────────────────────────────────────────────────────────────
+// --- Registry -----------------------------------------------------------------
 
 export interface RegistryConfig {
     /** Initial node-pool capacity. Default: 1024. */
@@ -197,8 +197,8 @@ export interface Registry {
     isTracking(): boolean;
     /** O(1): does this source have at least one live observer right now? A `peek` does not count. */
     hasObservers(handle: ReactiveHandle): boolean;
-    /** Auto-pause hook: fires `onConnect` on the 0→1 observer transition and `onDisconnect`
-     *  on 1→0, after registration (transition-only — no immediate fire if already observed).
+    /** Auto-pause hook: fires `onConnect` on the 0->1 observer transition and `onDisconnect`
+     *  on 1->0, after registration (transition-only -- no immediate fire if already observed).
      *  Re-tracking a persistently-read source does not churn. Returns an idempotent unobserve.
      *  @throws TypeError if `handle` is not a reactive handle. */
     observeObservers(handle: ReactiveHandle, hooks?: ObserveObserversHooks): Unobserve;
@@ -251,12 +251,12 @@ export function createRegistry(config?: RegistryConfig): Registry;
 /** Replace the default registry backing the top-level helpers. */
 export function setDefaultRegistry(registry: Registry): void;
 
-// ─── Top-level helpers (delegate to default registry) ────────────────────────
+// --- Top-level helpers (delegate to default registry) ------------------------
 
 export function signal<T>(initial: T, opts?: SignalOptions<T>): Signal<T>;
 export function computed<T>(fn: () => T, opts?: ComputedOptions<T>): Computed<T>;
 export function effect(fn: () => void, opts?: EffectOptions): Dispose;
-/** Universal disposal — see {@link Registry.dispose}. */
+/** Universal disposal -- see {@link Registry.dispose}. */
 export function dispose(api: Disposable): void;
 export function batch<T>(fn: () => T): T;
 export function untrack<T>(fn: () => T): T;
@@ -296,7 +296,7 @@ export interface WatchOptions {
 
 /**
  * Track a reactive source and run a callback whenever its projected value
- * changes. The callback receives `(newValue, oldValue, stop)` — the third
+ * changes. The callback receives `(newValue, oldValue, stop)` -- the third
  * argument is a dispose function that can be called from inside the callback
  * to terminate the watcher.
  *
@@ -336,10 +336,10 @@ export function when(
  * Promise-returning variant of {@link when}. The returned promise resolves
  * when `predicate` first returns a truthy value.
  *
- * ⚠️ **HOT-PATH WARNING — DO NOT USE PER FRAME.** This function calls
+ * ! **HOT-PATH WARNING -- DO NOT USE PER FRAME.** This function calls
  * `new Promise(...)`, which is a heap allocation (one Promise object plus
  * executor closure plus internal infrastructure per call). Promises require
- * heap allocation by the language spec — this cost is unavoidable.
+ * heap allocation by the language spec -- this cost is unavoidable.
  *
  * **Use for:** high-level scene/UI orchestration, boot sequences, awaiting
  * user input or network state, level transitions. Anything that runs once

package/Signal.js

@@ -1,26 +1,23 @@
 /**
- * @zakkster/lite-signal v1.2.1
+ * @zakkster/lite-signal v1.2.2
  * --------------------
- * Hybrid Doubly-Linked-List Reactive Graph Engine — decoupled (Signal1_3) base
+ * Hybrid Doubly-Linked-List Reactive Graph Engine -- decoupled (Signal1_3) base
  * with the two 1.1.3 performance fixes ported in:
- *   1. pullComputed clean short-circuit (markEpoch) — kills the dynamic-graph
+ *   1. pullComputed clean short-circuit (markEpoch) -- kills the dynamic-graph
  *      regression: "large web app" 4900ms -> 665ms, "wide dense" 4472 -> 952.
- *   2. allocateLink: O(1) tailSub dedup replaces the O(N) prefix scan — divergent
+ *   2. allocateLink: O(1) tailSub dedup replaces the O(N) prefix scan -- divergent
  *      re-tracking is O(N) not O(N^2) (600-dep flip micro: 1373ms -> 62ms).
  * Ownership tree + L1/L2/L3 layering + observer/owner split are UNCHANGED; they
  * were never the regression. Same EDGE NOTE as 1.1.3 applies to fix (2): a nested
  * re-read of the same source can retain one bounded, dispose-reclaimed link.
  *
- * Original header:
- * v1.3.2: Hybrid Doubly-Linked-List Reactive Graph Engine.
- *
  * Performance model:
  * - ReactiveLink DLL object pool guarantees O(1) graph edge allocation.
  * - Inlined O(1) cursor fast-path for stable steady-state reads.
  * - Divergence triggers immediate tail-severing to bound worst-case complexity.
  * - O(1) Owner Context Tree ensures automatic teardown of nested observers.
  *
- * ── ARCHITECTURE: three layers + a public API, with a strict dependency direction ──
+ * -- ARCHITECTURE: three layers + a public API, with a strict dependency direction --
  *
  *   L1  GRAPH TOPOLOGY      allocateLink, freeLink, severTail
  *       Owns the ReactiveLink pool and the dep/sub doubly-linked lists.
@@ -29,7 +26,7 @@
  *   L2  OWNERSHIP / LIFECYCLE   createNode, disposeNode, runCleanup
  *       Owns the owner tree and node death + user cleanup.
  *       INVARIANT: never touches the `activeObserverCurrentDep` cursor.
- *       Sanctioned downward edge → L1: disposeNode walks a dying node's own
+ *       Sanctioned downward edge -> L1: disposeNode walks a dying node's own
  *       dep/sub lists and calls freeLink to extract it from the graph.
  *
  *   L3  PROPAGATION / EXECUTION   markDownstream, flushEffects, executeEffect, pullComputed
@@ -37,18 +34,18 @@
  *       (a pure propagation primitive). executeEffect/pullComputed are the
  *       ORCHESTRATORS: they drive the cursor + severTail (L1) AND, before a
  *       re-run, call runCleanup (L2) to cascade-dispose owned children.
- *       Sanctioned upward call → L2: executeEffect/pullComputed → runCleanup.
+ *       Sanctioned upward call -> L2: executeEffect/pullComputed -> runCleanup.
  *
  *   API  signal, computed, effect, dispose, batch, untrack, onCleanup, stats, destroy
  *
- *   The only cross-layer edges are L3→runCleanup and L2→freeLink. The graph of
+ *   The only cross-layer edges are L3->runCleanup and L2->freeLink. The graph of
  *   dependencies is acyclic; nothing in L1 reaches up, nothing in L2 touches
  *   the cursor, and the engine is the single place the two subsystems meet.
  *
- * ── OWNER vs OBSERVER ──
+ * -- OWNER vs OBSERVER --
  *   `currentObserver` = the node whose READS establish dependencies (tracking).
  *   `currentOwner`    = the node that OWNS anything created right now (lifecycle).
- *   Today they move together, so behaviour is unchanged — but they are distinct
+ *   Today they move together, so behaviour is unchanged -- but they are distinct
  *   pointers so future runWithOwner/createRoot can attach ownership without
  *   establishing reactive dependencies (and untrack can suppress tracking
  *   without orphaning created nodes). createNode and onCleanup key off the
@@ -115,7 +112,7 @@ class ReactiveNode {
         this.headSub = null;
         this.tailSub = null;
 
-        // Owner Context Tree (Auto-Disposal of Nested Observers) — 1.2.0.
+        // Owner Context Tree (Auto-Disposal of Nested Observers) -- 1.2.0.
         // An effect/computed created inside another effect/computed is "owned"
         // by it. When the owner re-runs or is disposed, owned children are
         // cascade-disposed before the new run. Plain signals are NOT adopted
@@ -173,7 +170,7 @@ export class CapacityError extends Error {
  *
  * Use this when you need multiple independent reactive graphs (e.g. one per
  * Twitch Extension viewer, one per worker, one per test). The top-level
- * helpers ({@link signal}, {@link effect}, …) delegate to a single shared
+ * helpers ({@link signal}, {@link effect}, ...) delegate to a single shared
  * default registry; call {@link setDefaultRegistry} to swap that for your own.
  *
  * @param {object} [config]
@@ -228,7 +225,7 @@ export function createRegistry(config) {
     let batchDepth = 0;
     let isTrackingDeps = false;
 
-    // ── Node identity + observer-lifecycle introspection (ported from 1.1.5) ──
+    // -- Node identity + observer-lifecycle introspection (ported from 1.1.5) --
     let nodeSeq = 1 | 0;
     let lifecycleCount = 0 | 0;
     const lifecycleMap = new WeakMap();
@@ -251,19 +248,19 @@ export function createRegistry(config) {
     const flushErrorBuffer = [];
     let flushErrorCount = 0;
 
-    // ═══ L1 · GRAPH TOPOLOGY ══════════════════════════════════════
+    // === L1 * GRAPH TOPOLOGY ======================================
     // Owns the ReactiveLink pool and the dep/sub lists. Pure edge mechanics:
-    // INVARIANT — must never touch node.owner / firstOwned.
+    // INVARIANT -- must never touch node.owner / firstOwned.
 
-    // ─── HYBRID ALLOCATOR ─────────────────────────────────────────
+    // --- HYBRID ALLOCATOR -----------------------------------------
 
     /**
-     * Establish (or reuse) a dependency link from `source` → `target`.
+     * Establish (or reuse) a dependency link from `source` -> `target`.
      *
-     * Fast path: cursor match (re-tracking same dep at same position) — O(1), no allocation.
-     * Mid path: O(1) tailSub dedup (1.1.4 rewrite) — divergent retracking stays O(N) overall,
-     *           not O(N²).
-     * Cold path: pool exhausted → grow or throw per policy.
+     * Fast path: cursor match (re-tracking same dep at same position) -- O(1), no allocation.
+     * Mid path: O(1) tailSub dedup (1.1.4 rewrite) -- divergent retracking stays O(N) overall,
+     *           not O(N^2).
+     * Cold path: pool exhausted -> grow or throw per policy.
      *
      * SEVER-FIRST: on a cursor-miss divergence the unmatched dep tail is freed
      * BEFORE any new link is allocated, so peak link usage never exceeds steady
@@ -277,12 +274,12 @@ export function createRegistry(config) {
      *
      * @private
      */
-    // --- Graph-mutation hook (1.2.1 keystone prototype) ---------------------
-    // Single nullable listener; every fire point is `if (mutationHook !== null)`
-    // -- branch-predicted free when absent, allocation-free when present
-    // (opcode + two int args). Enables push-based devtools (watchGraph) and the
-    // recompute profiler. Opcodes: 1 node-create, 2 node-dispose, 3 link-add,
-    // 4 link-remove, 5 recompute.
+        // --- Graph-mutation hook (1.2.1 keystone prototype) ---------------------
+        // Single nullable listener; every fire point is `if (mutationHook !== null)`
+        // -- branch-predicted free when absent, allocation-free when present
+        // (opcode + two int args). Enables push-based devtools (watchGraph) and the
+        // recompute profiler. Opcodes: 1 node-create, 2 node-dispose, 3 link-add,
+        // 4 link-remove, 5 recompute.
     let mutationHook = null;
     function onGraphMutation(fn) {
         if (fn !== null && typeof fn !== "function") throw new TypeError("onGraphMutation: listener must be a function or null");
@@ -294,7 +291,7 @@ export function createRegistry(config) {
     function allocateLink(source, target) {
         // Eligibility gate (restored from 1.1.5): an observer disposed mid-run (self-dispose, or
         // an outer observer torn down while suspended) has flags cleared to 0. Linking would splice
-        // a dead, pool-bound node back into source's subscriber list — a phantom edge. Cold path only.
+        // a dead, pool-bound node back into source's subscriber list -- a phantom edge. Cold path only.
         if (target.flags === 0) return null;
         let expected = activeObserverCurrentDep;
 
@@ -345,7 +342,7 @@ export function createRegistry(config) {
 
         link.nextSub = null;
         link.prevSub = source.tailSub;
-        const _was0 = lifecycleCount !== 0 && source.headSub === null;   // 0→1 detect (pre-link)
+        const _was0 = lifecycleCount !== 0 && source.headSub === null;   // 0->1 detect (pre-link)
         if (source.tailSub !== null) source.tailSub.nextSub = link;
         else source.headSub = link;
         source.tailSub = link;
@@ -367,7 +364,7 @@ export function createRegistry(config) {
         const nSub = link.nextSub;
         if (pSub !== null) pSub.nextSub = nSub; else source.headSub = nSub;
         if (nSub !== null) nSub.prevSub = pSub; else source.tailSub = pSub;
-        if (lifecycleCount !== 0 && source.headSub === null) fireDisconnect(source);   // 1→0
+        if (lifecycleCount !== 0 && source.headSub === null) fireDisconnect(source);   // 1->0
 
         link.source = null;
         link.target = null;
@@ -403,13 +400,13 @@ export function createRegistry(config) {
         }
     }
 
-    // ═══ L2 · OWNERSHIP / LIFECYCLE ═══════════════════════════════
+    // === L2 * OWNERSHIP / LIFECYCLE ===============================
     // Owns the owner tree, node death, and user cleanup.
-    // INVARIANT — must never touch the activeObserverCurrentDep cursor.
-    // Sanctioned downward edge → L1: disposeNode calls freeLink to extract a
+    // INVARIANT -- must never touch the activeObserverCurrentDep cursor.
+    // Sanctioned downward edge -> L1: disposeNode calls freeLink to extract a
     // dying node from the graph.
 
-    // ─── LIFECYCLE & OWNERSHIP ───────────────────────────────────────
+    // --- LIFECYCLE & OWNERSHIP ---------------------------------------
 
     function disposeNode(node) {
         if (mutationHook !== null) mutationHook(2, node.id, node.flags | 0);
@@ -417,7 +414,7 @@ export function createRegistry(config) {
 
         // RACE WITH ACTIVE TRACKING: an effect/computed may call dispose on
         // itself from inside its own body (#141). Once we tear the node down
-        // its dep-list, FLAG_COMPUTING, and cursor become stale immediately —
+        // its dep-list, FLAG_COMPUTING, and cursor become stale immediately --
         // any read() that runs in the REST of the body would otherwise try to
         // hang a fresh link off a freed slot. Null the tracking state now so
         // subsequent reads in this call stack become no-ops, and let
@@ -455,7 +452,7 @@ export function createRegistry(config) {
 
         runCleanup(node);
 
-        // CROSS-EDGE L2→L1: extract this node's own edges from the graph.
+        // CROSS-EDGE L2->L1: extract this node's own edges from the graph.
         let dLink = node.headDep;
         while (dLink !== null) {
             const next = dLink.nextDep;
@@ -511,7 +508,7 @@ export function createRegistry(config) {
      * Claim a node from the free pool, reinitialise, and return it.
      * Grows pool per `policy` if exhausted (or throws CapacityError under "throw").
      * Adopts the new node into `currentOwner` if there is one AND the new node is
-     * an observer (computed/effect) — plain signals are not adopted (see ReactiveNode
+     * an observer (computed/effect) -- plain signals are not adopted (see ReactiveNode
      * comment on the owner tree).
      * @private
      */
@@ -539,43 +536,53 @@ export function createRegistry(config) {
         node.nextFree = null;
         activeNodes = (activeNodes + 1) | 0;
 
+        // 1.2.2: Clean free-list invariant (Andrii's recommendation).
+        //
+        // Every node leaving the pool is guaranteed-clean for the seven fields
+        // {headDep, tailDep, headSub, tailSub, revertEpoch, preBatchValue,
+        // preBatchVersion}: dispose() clears them on the recycle path, and the
+        // ReactiveNode constructor initializes them to the same values on the
+        // fresh-allocation path (pool growth at lines above). Re-writing them
+        // here was defense against a state that cannot exist.
+        //
+        // What stays: fields that define the new lifetime (value, flags, id,
+        // firstOwned, conditional owner-tree wiring) AND fields dispose does
+        // not touch (version, evalVersion, markEpoch -- used by the propagation
+        // and pull machinery, must be reset for the new lifetime).
         node.value = value;
         node.flags = flags | 0;
-        node.headDep = null;
-        node.tailDep = null;
-        node.headSub = null;
-        node.tailSub = null;
         node.version = 0;
         node.evalVersion = 0;
         node.markEpoch = 0;
-        node.revertEpoch = 0;
-        node.preBatchValue = undefined;
-        node.preBatchVersion = 0;
         node.id = nodeSeq; nodeSeq = (nodeSeq + 1) | 0;   // fresh identity per allocation (ported from 1.1.5)
 
-        // Wire into Owner Context (lifecycle, not tracking — keyed off currentOwner).
+        // Wire into Owner Context (lifecycle, not tracking -- keyed off currentOwner).
         // ONLY observers (computed/effect) are adopted: a re-running owner disposes
         // its nested observers (which would otherwise leak dep links), but plain
         // signals have no deps to leak, and disposing them breaks lazy-allocation
         // libraries (lite-store allocates a key's signal on first read, INSIDE the
-        // reading computed — adopting it meant that computed's next run wiped the
+        // reading computed -- adopting it meant that computed's next run wiped the
         // store key). Signals are therefore never owner-adopted.
-        // firstOwned is reset unconditionally (reuse-safety: a recycled former-owner
-        // must not carry stale children into runCleanup). prevOwned/nextOwned are
-        // written only on the adoption path -- an unadopted node is in no owner's
-        // firstOwned chain, so its prevOwned/nextOwned are never traversed and may
-        // stay stale. Saves two writes per signal and per top-level computed/effect.
-        node.firstOwned = null;
+        //
+        // 1.2.2 clean free-list invariant (extended to the owner tree):
+        // owner / prevOwned / firstOwned are all guaranteed-null on every node
+        // leaving the pool. Both teardown paths null them -- disposeNode (lines
+        // ~451-453) on direct dispose, runCleanup (lines ~609-615) on parent
+        // cascade -- and the ReactiveNode constructor inits them to null on the
+        // fresh-allocation path. The three former null-writes here (firstOwned,
+        // the adoption-path prevOwned, and the else-branch owner) were defense
+        // against a state that cannot exist. Only the writes that establish the
+        // NEW lifetime remain: owner + nextOwned + the parent's chain splice on
+        // the adoption path. nextOwned is written unconditionally on adoption
+        // (it takes the prior firstOwned, which may be non-null), so it is a
+        // real lifetime write, not a redundant clear.
         if (currentOwner !== null && (flags & (FLAG_COMPUTED | FLAG_EFFECT)) !== 0) {
             node.owner = currentOwner;
-            node.prevOwned = null;
             node.nextOwned = currentOwner.firstOwned;
             if (currentOwner.firstOwned !== null) {
                 currentOwner.firstOwned.prevOwned = node;
             }
             currentOwner.firstOwned = node;
-        } else {
-            node.owner = null;
         }
 
         if (mutationHook !== null) mutationHook(1, node.id, node.flags | 0);
@@ -585,12 +592,12 @@ export function createRegistry(config) {
     /**
      * Cascade-dispose owned children inside-out (deepest first), then invoke this
      * node's own cleanup if any. Cascade order is the v1.2 conformance fix for
-     * #238 / #241 / #243 — nested cleanups must fire grandchild → child → outer
+     * #238 / #241 / #243 -- nested cleanups must fire grandchild -> child -> outer
      * so that a parent's cleanup still sees its own state intact.
      * @private
      */
     function runCleanup(node) {
-        // Cascade children FIRST — deepest cleanups fire before shallowest.
+        // Cascade children FIRST -- deepest cleanups fire before shallowest.
         // This matches the universal invariant in the upstream conformance suite
         // (#238 / #241 / #243): nested cleanups run inside-out on owner-tree
         // disposal, mirroring the parent-knows-best assumption shared with
@@ -629,19 +636,19 @@ export function createRegistry(config) {
         }
     }
 
-    // ═══ L3 · PROPAGATION / EXECUTION ═════════════════════════════
+    // === L3 * PROPAGATION / EXECUTION =============================
     // markDownstream is owner-free AND cursor-free (a pure propagation
     // primitive). executeEffect/pullComputed are the orchestrators: they drive
     // the cursor + severTail (L1) and, before a re-run, call runCleanup (L2) to
-    // cascade-dispose owned children. Sanctioned upward call → L2: runCleanup.
+    // cascade-dispose owned children. Sanctioned upward call -> L2: runCleanup.
 
-    // ─── EXECUTION ENGINE ─────────────────────────────────────────
+    // --- EXECUTION ENGINE -----------------------------------------
 
     /**
      * Mark all transitive subscribers of `startNode` dirty.
      * Iterative DFS via the markStack to avoid call-stack growth.
      * Effects are enqueued for the flush phase; computeds are merely marked
-     * (their re-evaluation is lazy — triggered by the next read).
+     * (their re-evaluation is lazy -- triggered by the next read).
      * @private
      */
     function markDownstream(startNode) {
@@ -677,7 +684,7 @@ export function createRegistry(config) {
      * effects scheduled mid-flush land in the next pass. Individual effect throws
      * are caught and buffered; at end-of-flush a single throw is rethrown directly,
      * multiple throws are aggregated into an `AggregateError` (1.2.0). Exceeds
-     * `maxFlushPasses` (default 100) → Error prefixed `"CycleError:"`.
+     * `maxFlushPasses` (default 100) -> Error prefixed `"CycleError:"`.
      * @private
      */
     function flushEffects() {
@@ -737,7 +744,7 @@ export function createRegistry(config) {
      * Run an effect's compute body, re-tracking dependencies.
      * Short-circuits if no dependency has bumped its version since last eval.
      * If the body self-disposes (node.gen advances during the body), skips the
-     * post-body bookkeeping (severTail, flag clear, evalVersion bump) — that
+     * post-body bookkeeping (severTail, flag clear, evalVersion bump) -- that
      * gen-snapshot guard is the v1.2 conformance fix for #141.
      * @private
      */
@@ -767,7 +774,7 @@ export function createRegistry(config) {
         }
 
         node.flags = (node.flags & ~FLAG_QUEUED) | FLAG_COMPUTING;
-        runCleanup(node);   // CROSS-EDGE L3→L2: dispose owned children before re-run
+        runCleanup(node);   // CROSS-EDGE L3->L2: dispose owned children before re-run
         if ((node.flags & FLAG_EFFECT) === 0) return;
 
         const prevObserver = currentObserver;
@@ -783,7 +790,7 @@ export function createRegistry(config) {
         // SELF-DISPOSE DETECTION: snapshot the gen. disposeNode bumps gen,
         // so if it advanced during the body the node was disposed (and may
         // already have been recycled into a different role). Skip the
-        // dep-list / flag / version mutations in that case — they would
+        // dep-list / flag / version mutations in that case -- they would
         // either crash on the freed link list or corrupt the new resident.
         const savedGen = node.gen;
         if (mutationHook !== null) mutationHook(5, node.id, 0);
@@ -812,7 +819,7 @@ export function createRegistry(config) {
      * Errors thrown by computeFn are captured in `node.value` with FLAG_HAS_ERROR;
      * subsequent reads re-throw until a dependency change re-runs computeFn.
      *
-     * Same gen-snapshot self-dispose guard as executeEffect — see #141 fix.
+     * Same gen-snapshot self-dispose guard as executeEffect -- see #141 fix.
      *
      * @private
      */
@@ -849,7 +856,7 @@ export function createRegistry(config) {
         if (shouldRun) {
             if ((node.flags & FLAG_COMPUTING) !== 0) throw new Error("CycleError: Circular dependency detected.");
             node.flags |= FLAG_COMPUTING;
-            runCleanup(node);   // CROSS-EDGE L3→L2: dispose owned children before recompute
+            runCleanup(node);   // CROSS-EDGE L3->L2: dispose owned children before recompute
 
             const prevObserver = currentObserver;
             const prevOwner = currentOwner;
@@ -861,7 +868,7 @@ export function createRegistry(config) {
             activeObserverCurrentDep = node.headDep;
             isTrackingDeps = true;
 
-            // Same self-dispose detection as executeEffect — see comment there.
+            // Same self-dispose detection as executeEffect -- see comment there.
             const savedGen = node.gen;
             if (mutationHook !== null) mutationHook(5, node.id, 0);
             try {
@@ -879,7 +886,7 @@ export function createRegistry(config) {
                     node.version = globalVersion;
                 } else {
                     // The body disposed `node` and then threw. The error has
-                    // nowhere to land — the caller of the read that triggered
+                    // nowhere to land -- the caller of the read that triggered
                     // this pull has already had its tracking state torn down.
                     // Swallow rather than corrupt a recycled slot. The
                     // canonical thrown-computed test (#168 / cached error)
@@ -904,9 +911,9 @@ export function createRegistry(config) {
         return node.value;
     }
 
-    // ─── PUBLIC API ──────────────────────────────────────────────────
+    // --- PUBLIC API --------------------------------------------------
 
-    // ─── shared accessor methods (one set per registry, not per primitive) ───────
+    // --- shared accessor methods (one set per registry, not per primitive) -------
     // update/subscribe are method-invoked (s.update(fn), s.subscribe(fn)), so `this`
     // is the read function and this[NODE_PTR] is the node. set() and peek() stay
     // closures: set() is the hot write path (a closure over `node` beats the
@@ -1085,7 +1092,7 @@ export function createRegistry(config) {
             const gen = node.gen | 0;
             // Cache the gen-bound thunk so re-schedules reuse the same closure.
             // The inline guard preserves ABA correctness across dispose+recycle
-            // (gen bumps on disposeNode → stale thunk no-ops).
+            // (gen bumps on disposeNode -> stale thunk no-ops).
             node.schedulerThunk = () => {
                 if (node.gen === gen && (node.flags & FLAG_EFFECT) !== 0) executeEffect(node);
             };
@@ -1140,7 +1147,7 @@ export function createRegistry(config) {
 
     /**
      * Coalesce multiple synchronous writes into a single effect-flush pass.
-     * Nested batches are merged — only the outermost close triggers the flush.
+     * Nested batches are merged -- only the outermost close triggers the flush.
      *
      * Pre-batch revert (1.2.0): if a signal is set, then set back to its
      * pre-batch value (under its `equals`) before the outer close, the version
@@ -1219,7 +1226,7 @@ export function createRegistry(config) {
     }
 
     /**
-     * Snapshot of registry counters. Useful for diagnostics and tests —
+     * Snapshot of registry counters. Useful for diagnostics and tests --
      * e.g. asserting that `activeNodes` returns to a baseline after teardown.
      * @returns {RegistryStats}
      */
@@ -1339,7 +1346,7 @@ export function createRegistry(config) {
         const kind = (fl & FLAG_EFFECT) !== 0 ? "effect" : (fl & FLAG_COMPUTED) !== 0 ? "computed" : "signal";
         // Plain property assignment, not Object.defineProperty.
         // Object.keys() never includes symbol-keyed properties regardless of
-        // descriptor — enumerable: false was defending nothing. Confirmed
+        // descriptor -- enumerable: false was defending nothing. Confirmed
         // empirically: `o[Symbol()] = x; Object.keys(o)` returns only
         // string-keyed enumerable props.
         const d = {id: node.id, kind, value: node.value};
@@ -1399,9 +1406,9 @@ export function createRegistry(config) {
     return {signal, computed, effect, dispose, batch, untrack, onCleanup, stats, destroy, isTracking, hasObservers, observeObservers, forEachObserver, forEachSource, forEachOwned, ownerOf, nodeId, describe, onGraphMutation};
 }
 
-// ─────────────────────────────────────────────────────────────────
+// -----------------------------------------------------------------
 // GLOBAL BINDINGS
-// ─────────────────────────────────────────────────────────────────
+// -----------------------------------------------------------------
 
 let defaultRegistry = createRegistry();