@zakkster/lite-signal 1.2.2 → 1.3.0-rc

package/CHANGELOG.md

@@ -4,7 +4,108 @@ All notable changes to `@zakkster/lite-signal` are documented here.
 Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 This project follows [Semantic Versioning](https://semver.org/).
 
-## [1.2.2] -- 2026-06-16
+## [1.3.0] -- 2026-06-XX
+
+The pool minor: the node and link pools become **growable and incrementally
+populated**, the propagation mark phase moves to an **intrusive linked-list
+stack**, and a small **registry config surface** (`prealloc`,
+`onCapacityExceeded`, `maxFlushPasses`) is exposed. Drop-in over 1.2.2 -- the
+hot paths and public callable API are byte-identical; everything here is pool
+mechanics, construction-time behavior, and new opt-in config. Steady-state
+zero-GC is unchanged: after warm-up the pools recycle exactly as before.
+
+**Default behavior: `prealloc: "eager"`.** The pools are preallocated up front
+by default, preserving 1.2.x's deterministic-latency profile (no allocation
+inside a hot loop or render frame -- the contract that matters for the 16ms /
+120fps Twitch-overlay and canvas use cases this engine targets). Lazy population
+is available as an opt-in (`prealloc: "lazy"`) for footprint-sensitive or
+fast-cold-start consumers. See the tradeoff note under *Added -- registry config*.
+
+### Added -- growable pools (`onCapacityExceeded: "grow"`)
+
+The node and link pools can now grow past their initial capacity instead of
+only throwing. Growth is **chunked and incremental**, not a single doubling
+burst:
+
+- **Link pool** refills in contiguous runs of up to **1024** links per
+  free-list miss; **node pool** in runs of up to **256**. This bounds any
+  single growth pause to roughly `chunk x ~0.5us` and keeps the freshly
+  constructed slots contiguous in memory (better locality than scattered
+  one-at-a-time `new`).
+- `onCapacityExceeded` (default `"throw"`) selects the policy: `"throw"` fails
+  fast with a `CapacityError` when a pool is full (the 1.2.x behavior, now
+  named); `"grow"` extends the pool on demand. Link growth is bounded by a hard
+  ceiling of `maxLinks * 16`.
+- The growth path **no longer length-extends the effect queues or mark stack**.
+  Previously `arr.length = newCap` permanently converted those arrays from
+  PACKED to HOLEY elements-kind -- a silent flush-path tax. They now grow by
+  sequential `arr[len++] = x` appends, which keep them packed.
+
+### Added -- registry config surface
+
+`createRegistry(config)` accepts three new options. All are additive and
+non-breaking; omitting `config` reproduces 1.2.x behavior with the eager
+default.
+
+- **`prealloc`** (`"eager"` default | `"lazy"`). `"eager"` constructs the full
+  `maxNodes` / `maxLinks` pools up front -- deterministic latency, zero
+  allocation inside any subsequent hot path, at the cost of a larger resident
+  heap that every major GC must trace. `"lazy"` treats `maxNodes` / `maxLinks`
+  as capacity *ledgers*, constructs nodes/links on first demand, and recycles
+  through the free lists thereafter -- smaller heap, faster cold start, lighter
+  GC marking, identical zero-GC steady state after warm-up. **Choose eager for
+  hard-real-time (render loops, game ticks, extension frame budgets); choose
+  lazy for footprint-sensitive or short-lived registries.**
+- **`onCapacityExceeded`** (`"throw"` default | `"grow"`) -- see above.
+- **`maxFlushPasses`** (default `100`) -- cycle-protection ceiling: the maximum
+  number of effect-queue drain passes before the flush throws an `Error`
+  prefixed `"CycleError:"`. Exposes what was a fixed internal bound so
+  pathological-but-legitimate deep-cascade graphs can raise it.
+
+### Changed -- intrusive mark stack in `markDownstream`
+
+The propagation mark phase now walks an **iterative DFS backed by an intrusive
+linked-list stack** (a `nextMark` field on each node) instead of a separate
+`markStack` container array. Because `nextMark` sits adjacent to the
+`markEpoch` field that the same sweep reads, the stack write lands in an
+already-hot cache line. Behaviorally identical -- same nodes marked in the same
+order, same glitch-free guarantee -- and it removes the container array's growth
+and HOLEY-conversion concerns entirely. The mark stack never grows the JS call
+stack regardless of graph depth (the iterative property from 1.2.4 is retained).
+
+### Added -- `ReactiveNode.nextMark`
+
+One field added to the node shape to back the intrusive mark stack. Initialized
+to `null` on construction, cleared on pop during a sweep and defensively on
+dispose, so the chain stays clean for reuse. This is the only node-shape change
+in 1.3.0.
+
+### Verified
+
+- **Full suite green** against the 1.3.0 engine: 424 tests, 414 pass, 0 fail,
+  10 skip. The 10 skips are the 9 `{skip:true}` `signalBox` tests in
+  `24-signalbox` (those primitives land in 1.5.0) plus 1 architecturally-N/A
+  SSR case in `17-reactivity`. The eager-default flip changed no test outcome.
+  Four new tests in `03-pool` cover the 1.3.0 paths: lazy on-demand construction
+  reaching the same steady state as eager, a never-allocated lazy registry
+  surviving `destroy()`, `"grow"` extending both pool ledgers, and the
+  `maxLinks * 16` link ceiling.
+- **Coverage** (c8@11, Node 22): `Signal.js` 100% statements / 98.26% branches /
+  100% functions / 100% lines; `Watch.js` 100% across all four. The lazy-pool
+  `destroy()` paths added in 1.3.0 are covered by the new `03-pool` tests.
+- **Behavior-preservation difftest**: 20,000 direct + 10,000 batched writes
+  against the published 1.1.5 reference, 0 disagreements. Pool growth, chunked
+  refill, and the intrusive mark stack do not alter observable propagation.
+- **Zero-GC steady state holds**: after warm-up, writing through a built graph
+  allocates nothing and the pool does not grow (eager) / does not grow further
+  (lazy, post warm-up). Confirmed across deep-chain, wide fan-out, and batched
+  scenarios.
+- **`stats()` shape unchanged from 1.2.x** (8 keys). The cumulative allocation
+  counters (`totalAllocations` / `totalDisposals` / `poolGrowths`) remain
+  reserved for 1.4.0 and are still absent here -- the introspection-contract
+  test continues to pin their absence.
+
+
 
 A code-deletion ship: a `createNode` audit removes ten redundant field-writes
 that defended against a state the engine cannot produce on a clean free-list.

package/README.md

@@ -444,10 +444,11 @@ The effect dispose handle (`const dispose = effect(...)`) is still a plain funct
 
 ```ts
 const r = createRegistry({
-  maxNodes:          1024,       // default
-  maxLinks:          4 * 1024,   // default = maxNodes * 4
-  maxFlushPasses:    100,        // default
-  onCapacityExceeded: "throw"    // default. Other: "grow"
+  maxNodes:           1024,       // default (ledger)
+  maxLinks:           4 * 1024,   // default = maxNodes * 4 (ledger)
+  prealloc:           "eager",    // default. Other: "lazy"
+  maxFlushPasses:     100,        // default
+  onCapacityExceeded: "throw"     // default. Other: "grow"
 });
 
 const s = r.signal(0);
@@ -466,29 +467,34 @@ r.destroy();                     // reset all pools, invalidate generations
 <details>
 <summary>Pool sizing, the grow policy, and why there is a 16× link ceiling.</summary>
 
-The engine has two pool sizes: **nodes** and **links**. Both are fixed at registry creation but can be configured to grow.
+The engine has two pools: **nodes** and **links**. Their capacities are set at registry creation. As of **1.3.0** you also choose *when* the pools are populated (`prealloc`) and *what happens* when a capacity is hit (`onCapacityExceeded`).
+
+**`prealloc` (1.3.0)** -- `"eager"` (default) constructs the full `maxNodes` / `maxLinks` pools up front: deterministic latency, zero allocation inside any subsequent hot path (the contract that matters for 16ms render frames and 120fps canvas loops), at the cost of a larger resident heap. `"lazy"` treats the capacities as *ledgers*, constructs nodes/links on first demand, and recycles through the free lists thereafter: smaller heap, faster cold start, lighter GC marking, **identical zero-GC steady state after warm-up**. Choose eager for hard-real-time, lazy for footprint-sensitive or short-lived registries (per-viewer sandboxes, tests).
+
+**`onCapacityExceeded`** -- `"throw"` (default) fails fast with a `CapacityError`. `"grow"` extends the pool on demand. Growth is **chunked and incremental** -- contiguous runs of up to **1024 links / 256 nodes** per free-list miss, not a single doubling burst -- so any one growth pause stays bounded (~chunk x ~0.5us) and freshly constructed slots stay contiguous in memory. The capacity *ledger* still doubles, so `stats()` semantics are unchanged.
 
 ```mermaid
 flowchart LR
-  A[allocator hits empty pool] --> B{policy?}
+  A[allocator hits empty free-list] --> B{policy?}
   B -- "throw" --> C[CapacityError]
-  B -- "grow" --> D[double pool size]
-  D --> E{new size > 16× original?}
+  B -- "grow" --> D[construct a chunked run<br/>up to 1024 links / 256 nodes<br/>ledger doubles]
+  D --> E{ledger > 16x original links?}
   E -- yes --> F[CapacityError<br/>link ceiling]
   E -- no --> G[allocate, continue]
 ```
 
-Why a ceiling? Unbounded growth hides leaks. If your app reaches 16× its starting link capacity, something is wrong and you want to know -- `CapacityError` is louder than a slow OOM crash four hours later.
+Why a ceiling? Unbounded growth hides leaks. If your app reaches 16x its starting link capacity, something is wrong and you want to know -- `CapacityError` is louder than a slow OOM crash four hours later.
 
 Default sizing for a Twitch-extension-style budget:
 
-| Workload                            | maxNodes | maxLinks | policy   |
-| ----------------------------------- | -------- | -------- | -------- |
-| Tiny widget (<=50 reactive cells)    | 256      | 1024     | `"throw"` |
-| Standard overlay (~500 cells)       | 1024     | 4096     | `"throw"` |
-| Heavy dashboard (variable scale)    | 2048     | 16384    | `"grow"`  |
+| Workload                            | maxNodes | maxLinks | prealloc | policy   |
+| ----------------------------------- | -------- | -------- | -------- | -------- |
+| Tiny widget (<=50 reactive cells)    | 256      | 1024     | `"eager"` | `"throw"` |
+| Standard overlay (~500 cells)       | 1024     | 4096     | `"eager"` | `"throw"` |
+| Heavy dashboard (variable scale)    | 2048     | 16384    | `"eager"` | `"grow"`  |
+| Per-viewer sandbox / short-lived    | 512      | 2048     | `"lazy"`  | `"throw"` |
 
-`stats()` reports `signals`, `computeds`, `effects`, `activeLinks`, `pooledLinks`, `linkPoolCapacity`. Drop it on screen for live observability.
+`stats()` reports `signals`, `computeds`, `effects`, `activeNodes`, `activeLinks`, `pooledLinks`, `nodePoolCapacity`, `linkPoolCapacity` (8 keys; the capacity keys are ledgers under `"lazy"`). Drop it on screen for live observability.
 
 </details>
 
@@ -500,9 +506,9 @@ Default sizing for a Twitch-extension-style budget:
 
 | API | Use case | Lifecycle | Hot-path safe? |
 |---|---|---|---|
-| `watch(source, cb)` | observe value changes over time | manual `stop()` | ✅ zero-GC per fire |
-| `watch(source, (v, p, stop) => ...)` | observe until a condition | self-dispose via callback arg | ✅ zero-GC per fire |
-| `when(predicate, cb)` | one-shot trigger when condition first true | auto-dispose | ✅ zero-GC per check |
+| `watch(source, cb)` | observe value changes over time | manual `stop()` | yes -- zero-GC per fire |
+| `watch(source, (v, p, stop) => ...)` | observe until a condition | self-dispose via callback arg | yes -- zero-GC per fire |
+| `when(predicate, cb)` | one-shot trigger when condition first true | auto-dispose | yes -- zero-GC per check |
 | `whenAsync(predicate)` | await a condition | auto-dispose | ! allocates Promise -- see below |
 
 ### `watch(source, callback, options?)`
@@ -699,7 +705,7 @@ Three tiers, all reproducible.
 
 - **`01-core_test.mjs`** -- signal/computed/effect basics, equality semantics, NaN/+/-0, subscribe/peek/update, untrack, batch, cleanup ordering, first-run error recovery, nested object reference-identity gotchas.
 - **`02-topology_test.mjs`** -- diamond glitch-freedom, 256-deep and 1024-deep computed chains, wide fan-out (1000 effects from one signal), dynamic dependency switching, conditional fan-out, nested effects, cycle detection (`CycleError`).
-- **`03-pool_test.mjs`** -- `CapacityError` under both `"throw"` and `"grow"` policies, the 16× link ceiling, stable pool reuse across thousands of create/dispose cycles, registry isolation.
+- **`03-pool_test.mjs`** -- `CapacityError` under both `"throw"` and `"grow"` policies, the 16× link ceiling, stable pool reuse across thousands of create/dispose cycles, registry isolation, and (1.3.0) the lazy-prealloc paths: on-demand construction reaching the same steady state as eager, a never-allocated lazy registry surviving `destroy()`, and `"grow"` extending both pool ledgers past their initial capacity.
 - **`05-scheduler_test.mjs`** -- scheduler-deferred effects, dispose-during-schedule races, microtask integration, 32-bit version wrap (simulated), `setDefaultRegistry`, `onCleanup` inside computeds.
 - **`06-nested-objects_test.mjs`** -- array mutation patterns (push/splice/spread), deep nested paths, Map/Set/Date inside signals, custom structural equality, computed memoisation cutoffs over object slices, signal-of-signals composition, high-frequency object updates, batched immutable updates.
 - **`07-dispose_test.mjs`** -- unified `dispose(api)` across signals, computeds and effect handles, idempotency, cross-registry isolation (per-registry Symbol prevents pool corruption), foreign-value safety, top-level helper routing, 500-cycle balanced churn leaving pool and stats stable.
@@ -719,8 +725,8 @@ Three tiers, all reproducible.
 - **`21-perf-pins_test.mjs`** -- v1.2.1 construction-shape pins (6 tests). Locks the canonical handle shapes (`signal` 6 own props: peek/set/update/subscribe + NODE_PTR/NODE_GEN; `computed` 4: peek/subscribe + NODE_PTR/NODE_GEN) so a future "let's unify them" change has to be explicit. Locks the 1.2.1 ABA guards: detached `const {set} = signal()` keeps working on a LIVE signal; `read()` returns `undefined` and skips dep-tracking on a stale handle (no phantom subscription to the recycled slot); `set()` on a stale handle is a no-op across three corruption tiers (disposed slot, recycled slot, downstream propagation); `peek()` returns `undefined` for stale signal and computed handles.
 - **`22-mutation-hook_test.mjs`** -- 1.2.1 `onGraphMutation` semantics (12 tests across 2 suites). Registration: unsubscribe returns a function; `null` argument clears and the unsub restores the prior listener; non-function/non-null throws `TypeError`; multiple registrations stack LIFO; registries are isolated (no cross-talk). Opcode emission: `1` node-create fires with `(id, flags)` for signal (32) / computed (1) / effect (2); `2` node-dispose fires for cascade-disposed owned children; `3` link-add fires with `(source.id, target.id)` on dependency record; `4` link-remove fires when a dep-set flip severs the tail; `5` recompute fires on initial eval AND re-eval; the hook fires synchronously inside the mutation (listener sees its own event before the caller returns); payload is always three plain numbers -- no objects, no closures.
 - **`23-owner-introspection_test.mjs`** -- 1.2.1 owner-tree introspection + effect-disposer regression (22 tests across 4 suites). `ownerOf`: undefined for top-level / garbage input / stale handle; returns the enclosing effect's descriptor for a child created inside an effect body. `forEachOwned`: no-op for handles with no owned children / garbage input / stale handle; iterates owned children as `{id, kind, value}` descriptors. Gen-guarded introspection (ABA fix): `nodeId` / `describe` / `hasObservers` return undefined / false for stale handles; `observeObservers` throws `TypeError`; `forEachObserver` / `forEachSource` are no-ops; descriptors returned by `describeNode` are themselves gen-stamped so a descriptor obtained pre-recycle correctly walks as a no-op post-recycle (the "descriptors are re-walkable handles" contract survives the guard). Plus the 1.2.1 effect-dispose-handle fix: passing the effect's disposer directly to `describe` / `nodeId` / `forEachSource` / `forEachOwned` / `ownerOf` / `hasObservers` works as a first-class introspection handle (pre-fix it was a bare closure and returned `undefined` for a *live* effect); after `fx()` dispose the same handle correctly goes stale on every entry point; the disposer's `NODE_GEN` mirrors the effect node's birthGen exactly.
-- **`24-signalbox_test.mjs`** -- staged for v1.5.0; all 9 tests `{skip: true}` on 1.2.x. The `signalBox` / `computedBox` allocation-light handle API lands in 1.5.0; the suite is committed early so the surface is pinned and the skips are visible in the test count (the 10 skips on 1.2.2 are these 9 plus 1 architecturally-N/A SSR case in `17-reactivity`).
-- **`25-devtools-real-boot_test.mjs`** -- Devtools/Studio contract (10 tests). Boots the actual `Devtools.js` against the 1.2.2 engine and exercises all 19 Devtools exports plus the 10 symbols Studio imports from Devtools. Pins the ghost contract: heavy introspection (graph walk, owner-tree, observer descriptors) adds **zero** nodes to the live graph. Catches the real-rig failure mode where importing the package by its own name from a repo whose `package.json` declares `name: "@zakkster/lite-signal"` resolves to the published build instead of the local engine.
+- **`24-signalbox_test.mjs`** -- staged for v1.5.0; all 9 tests `{skip: true}` on 1.3.x. The `signalBox` / `computedBox` allocation-light handle API lands in 1.5.0; the suite is committed early so the surface is pinned and the skips are visible in the test count (the 10 skips on 1.3.0 are these 9 plus 1 architecturally-N/A SSR case in `17-reactivity`).
+- **`25-devtools-real-boot_test.mjs`** -- Devtools/Studio contract (10 tests). Boots the actual `Devtools.js` against the 1.3.0 engine and exercises all 19 Devtools exports plus the 10 symbols Studio imports from Devtools. Pins the ghost contract: heavy introspection (graph walk, owner-tree, observer descriptors) adds **zero** nodes to the live graph. Catches the real-rig failure mode where importing the package by its own name from a repo whose `package.json` declares `name: "@zakkster/lite-signal"` resolves to the published build instead of the local engine.
 - **`26-free-list-invariant_test.mjs`** -- the 1.2.2 audit's cleanliness pins (3 invariant tests + 1 targeted coverage test). Asserts directly -- by inspecting freshly-allocated nodes through the documented `describe()` -> `NODE_PTR` introspection protocol -- that the `ReactiveNode` constructor and the fresh-pool-growth path initialize the ten fields the audit removed from `createNode` to identical values, so the deleted writes were defending against a state the engine cannot produce on a clean free list. The 4th test covers the swallow-on-self-dispose-then-throw branch in `pullComputed` (the path that lifted branch coverage from 98.07% to 98.43%).
 
 ```bash
@@ -824,7 +830,8 @@ The cross-framework reactivity suite agrees independently, re-run on **1.2.2** (
 ### Roadmap
 - **1.1.5** -- additions in service of `lite-devtools` (node identity/traversability on the introspection walkers, for full auto-discovered graph rendering). *Shipped.*
 - **1.2.0** -- the **ownership hybrid**: an owner tree so nested effects/computeds auto-dispose with their parent (closes conformance #209 / #210, matching Solid's `createRoot` ergonomics). Plus three additive features built on the same internal split: pre-batch revert (`batch(() => { a.set(99); a.set(10); })` doesn't re-fire), multi-throw `AggregateError`, and scheduler-thunk caching with an ABA gen guard. *Shipped.*
-- **1.3** -- next engine work after the owner-tree validation. The pull-mode recursion depth limit (~5,000 chained computeds) is the main outstanding architectural item.
+- **1.3.0** -- the **pool minor**: node and link pools become growable and incrementally populated. New `prealloc` config (`"eager"` default | `"lazy"`) chooses up-front vs on-demand construction; `onCapacityExceeded: "grow"` extends pools via chunked refill (runs of up to 1024 links / 256 nodes, ledger doubles) bounded by the 16x link ceiling; `maxFlushPasses` is now a public config. Internally the propagation mark phase moved to an intrusive linked-list stack (a `nextMark` field) -- the only node-shape change. The hot paths and public callable API are byte-identical to 1.2.2; steady-state zero-GC is unchanged. *Shipped.*
+- **1.4** -- next engine work. The pull-mode recursion depth limit (~5,000 chained computeds) is the main outstanding architectural item; cumulative allocation counters (`totalAllocations` / `totalDisposals` / `poolGrowths`) are reserved for the `stats()` surface here.
 
 > Note: the retracking rewrite that closes the dynamic-topology gap shipped in **1.1.4**, not a future release. The earlier roadmap that listed it under "v1.2" is superseded.
 
@@ -873,14 +880,14 @@ Pure ES2020 + `Object.is` + `Int32 | 0`. Runs anywhere that runs modern JavaScri
 
 | Target                            | Supported |
 | --------------------------------- | --------- |
-| Chrome / Edge (last 2 majors)     | ✓         |
-| Firefox (last 2 majors)           | ✓         |
-| Safari 14+                        | ✓         |
-| Node.js 18+                       | ✓         |
-| Bun                               | ✓         |
-| Twitch Extensions (1MB / 3s)      | ✓         |
-| Cloudflare Workers                | ✓         |
-| Deno                              | ✓         |
+| Chrome / Edge (last 2 majors)     | yes         |
+| Firefox (last 2 majors)           | yes         |
+| Safari 14+                        | yes         |
+| Node.js 18+                       | yes         |
+| Bun                               | yes         |
+| Twitch Extensions (1MB / 3s)      | yes         |
+| Cloudflare Workers                | yes         |
+| Deno                              | yes         |
 
 ESM-only. No CommonJS build -- modern bundlers handle this; legacy consumers can use a wrapper.
 

package/Signal.d.ts

@@ -82,11 +82,13 @@ export interface RegistryStats {
     effects: number;
     /** Number of dependency links currently in use. */
     activeLinks: number;
-    /** Number of dependency links available in the pool. */
+    /** Dependency links available in the pool (ledger-based: `linkPoolCapacity - activeLinks`). */
     pooledLinks: number;
-    /** Total link-pool capacity (grows under `"grow"` policy). */
+    /** Link-pool capacity ledger. Doubles under the `"grow"` policy; under `"lazy"`
+     *  prealloc it may exceed the count of physically constructed links. */
     linkPoolCapacity: number;
-    /** Total node-pool capacity (grows under `"grow"` policy). */
+    /** Node-pool capacity ledger. Doubles under the `"grow"` policy; under `"lazy"`
+     *  prealloc it may exceed the count of physically constructed nodes. */
     nodePoolCapacity: number;
     /** Number of nodes currently allocated (signals + computeds + alive effects). */
     activeNodes: number;
@@ -163,14 +165,31 @@ export class CapacityError extends Error {
 // --- Registry -----------------------------------------------------------------
 
 export interface RegistryConfig {
-    /** Initial node-pool capacity. Default: 1024. */
+    /** Initial node-pool capacity (a ledger under `prealloc: "lazy"`). Default: 1024. */
     maxNodes?: number;
-    /** Initial link-pool capacity. Default: `maxNodes * 4`. */
+    /** Initial link-pool capacity (a ledger under `prealloc: "lazy"`). Default: `maxNodes * 4`. */
     maxLinks?: number;
     /**
-     * Behaviour when a pool is exhausted:
-     *  - `"throw"` (default): throw {@link CapacityError} immediately.
-     *  - `"grow"`: double the pool. Links are bounded by `maxLinks * 16`.
+     * Pool population strategy. Default: `"eager"`.
+     *  - `"eager"`: construct the full `maxNodes` / `maxLinks` pools up front.
+     *    Deterministic latency -- zero allocation inside any subsequent hot path
+     *    (the contract for render loops, game ticks, and extension frame budgets),
+     *    at the cost of a larger resident heap that every major GC traces.
+     *  - `"lazy"`: treat `maxNodes` / `maxLinks` as capacity ledgers and construct
+     *    nodes/links on first demand, recycling through the free lists thereafter.
+     *    Smaller heap, faster cold start, lighter GC marking; identical zero-GC
+     *    steady state after warm-up. Prefer for footprint-sensitive or short-lived
+     *    registries.
+     */
+    prealloc?: "eager" | "lazy";
+    /**
+     * Behaviour when a pool is exhausted. Default: `"throw"`.
+     *  - `"throw"`: throw {@link CapacityError} immediately when the pool is full.
+     *  - `"grow"`: extend the pool on demand. Growth is chunked and incremental
+     *    (contiguous runs of up to 1024 links / 256 nodes per free-list miss),
+     *    not a single doubling burst, so any one growth pause stays bounded. The
+     *    capacity ledger still doubles, keeping {@link RegistryStats} semantics
+     *    unchanged. Link growth is bounded by a hard ceiling of `maxLinks * 16`.
      */
     onCapacityExceeded?: "throw" | "grow";
     /** Max effect-queue drain passes before a flush-cycle `Error` (message prefixed `"CycleError:"`) is thrown. Default: 100. */
@@ -282,7 +301,7 @@ export function describe(handle: ReactiveHandle): NodeDescriptor | undefined;
 export function onGraphMutation(fn: GraphMutationListener | null): GraphMutationUnsubscribe;
 export function onCleanup(fn: () => void): void;
 export function stats(): RegistryStats;
-export declare function destroy(): void;
+export function destroy(): void;
 
 /**
  * Configuration options for the watch utility.

package/Signal.js

@@ -1,5 +1,5 @@
 /**
- * @zakkster/lite-signal v1.2.2
+ * @zakkster/lite-signal v1.3.0
  * --------------------
  * Hybrid Doubly-Linked-List Reactive Graph Engine -- decoupled (Signal1_3) base
  * with the two 1.1.3 performance fixes ported in:
@@ -11,6 +11,9 @@
  * 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:
+ * 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.
@@ -124,6 +127,11 @@ class ReactiveNode {
 
         // Pool free-list pointer.
         this.nextFree = null;
+        // 1.3.0: Intrusive mark-stack pointer. markDownstream chains visited
+        // nodes through this field instead of an external array, eliminating the
+        // separate cache line + bounds-check on each push/pop. Always null
+        // outside an active markDownstream sweep; cleared on pop and on dispose.
+        this.nextMark = null;
     }
 }
 
@@ -174,11 +182,25 @@ export class CapacityError extends Error {
  * default registry; call {@link setDefaultRegistry} to swap that for your own.
  *
  * @param {object} [config]
- * @param {number} [config.maxNodes=1024]            Initial node-pool capacity.
- * @param {number} [config.maxLinks=maxNodes*4]      Initial link-pool capacity.
+ * @param {number} [config.maxNodes=1024]            Initial node-pool capacity (ledger).
+ * @param {number} [config.maxLinks=maxNodes*4]      Initial link-pool capacity (ledger).
+ * @param {"eager"|"lazy"} [config.prealloc="eager"]
+ *        Pool population strategy. `"eager"` constructs the full `maxNodes` /
+ *        `maxLinks` pools up front -- deterministic latency, zero allocation
+ *        inside any subsequent hot path (the contract for render loops, game
+ *        ticks, and extension frame budgets), at the cost of a larger resident
+ *        heap that every major GC traces. `"lazy"` treats the capacities as
+ *        ledgers and constructs nodes/links on first demand, recycling through
+ *        the free lists thereafter -- smaller heap, faster cold start, lighter
+ *        GC marking, identical zero-GC steady state after warm-up. Choose eager
+ *        for hard-real-time, lazy for footprint-sensitive or short-lived registries.
  * @param {"throw"|"grow"} [config.onCapacityExceeded="throw"]
- *        `"throw"` fails fast when pools are full.
- *        `"grow"` doubles the pool (bounded by `maxLinks * 16` for links).
+ *        `"throw"` fails fast with a {@link CapacityError} when a pool is full.
+ *        `"grow"` extends the pool on a free-list miss. Growth is chunked and
+ *        incremental -- contiguous runs of up to 1024 links / 256 nodes per
+ *        miss, not a single doubling burst -- so any one growth pause stays
+ *        bounded; the capacity ledger still doubles (`stats()` semantics
+ *        unchanged). Link growth is bounded by a hard ceiling of `maxLinks * 16`.
  * @param {number} [config.maxFlushPasses=100]       Cycle-protection: max effect-queue
  *                                                   drain passes before throwing an
  *                                                   Error prefixed `"CycleError:"`.
@@ -194,15 +216,24 @@ export function createRegistry(config) {
     const maxFlushPasses = (config !== undefined && config.maxFlushPasses !== undefined) ? config.maxFlushPasses : 100;
     const maxLinkLimit = currentLinkCapacity * 16;
 
+    // Lazy pool population (P1): maxNodes / maxLinks are capacity ledgers,
+    // not eager construction counts. Nodes/links are constructed on first
+    // demand and recycled through the free lists thereafter -- the zero-GC
+    // steady state is identical after warm-up, but the heap no longer carries
+    // never-used live objects for every major GC to mark.
+    const prealloc = (config !== undefined && config.prealloc !== undefined) ? config.prealloc : "eager";
     const nodePool = [];
-    for (let i = 0; i < currentNodesCapacity; i++) nodePool[i] = new ReactiveNode();
-    let freeNodeHead = nodePool[0];
-    for (let i = 0; i < currentNodesCapacity - 1; i++) nodePool[i].nextFree = nodePool[i + 1];
-
+    let freeNodeHead = null;
     const linkPool = [];
-    for (let i = 0; i < currentLinkCapacity; i++) linkPool[i] = new ReactiveLink();
-    let freeLinkHead = linkPool[0];
-    for (let i = 0; i < currentLinkCapacity - 1; i++) linkPool[i].nextFree = linkPool[i + 1];
+    let freeLinkHead = null;
+    if (prealloc === "eager") {
+        for (let i = 0; i < currentNodesCapacity; i++) nodePool[i] = new ReactiveNode();
+        freeNodeHead = nodePool[0];
+        for (let i = 0; i < currentNodesCapacity - 1; i++) nodePool[i].nextFree = nodePool[i + 1];
+        for (let i = 0; i < currentLinkCapacity; i++) linkPool[i] = new ReactiveLink();
+        freeLinkHead = linkPool[0];
+        for (let i = 0; i < currentLinkCapacity - 1; i++) linkPool[i].nextFree = linkPool[i + 1];
+    }
 
     let activeNodes = 0;
     let activeLinks = 0;
@@ -212,7 +243,6 @@ export function createRegistry(config) {
 
     const effectQueueA = [];
     const effectQueueB = [];
-    const markStack = [];
     let activeQueue = effectQueueA;
     let activeQueueLen = 0;
     let isQueueA = true;
@@ -229,20 +259,35 @@ export function createRegistry(config) {
     let nodeSeq = 1 | 0;
     let lifecycleCount = 0 | 0;
     const lifecycleMap = new WeakMap();
+
     function fireConnect(node) {
         const e = lifecycleMap.get(node);
         if (e === undefined || e.onConnect === undefined) return;
         const po = currentObserver, pt = isTrackingDeps;
-        currentObserver = null; isTrackingDeps = false;
-        try { e.onConnect(); } finally { currentObserver = po; isTrackingDeps = pt; }
+        currentObserver = null;
+        isTrackingDeps = false;
+        try {
+            e.onConnect();
+        } finally {
+            currentObserver = po;
+            isTrackingDeps = pt;
+        }
     }
+
     function fireDisconnect(node) {
         const e = lifecycleMap.get(node);
         if (e === undefined || e.onDisconnect === undefined) return;
         const po = currentObserver, pt = isTrackingDeps;
-        currentObserver = null; isTrackingDeps = false;
-        try { e.onDisconnect(); } finally { currentObserver = po; isTrackingDeps = pt; }
+        currentObserver = null;
+        isTrackingDeps = false;
+        try {
+            e.onDisconnect();
+        } finally {
+            currentObserver = po;
+            isTrackingDeps = pt;
+        }
     }
+
     let isFlushing = false;
 
     const flushErrorBuffer = [];
@@ -281,11 +326,14 @@ export function createRegistry(config) {
         // 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");
         const prev = mutationHook;
         mutationHook = fn;
-        return () => { if (mutationHook === fn) mutationHook = prev; };
+        return () => {
+            if (mutationHook === fn) mutationHook = prev;
+        };
     }
 
     function allocateLink(source, target) {
@@ -317,24 +365,38 @@ export function createRegistry(config) {
 
         let link;
         if (freeLinkHead === null) {
-            if (policy === "throw") throw new CapacityError("links", currentLinkCapacity);
-            const newCap = currentLinkCapacity * 2;
-            if (newCap > maxLinkLimit) throw new CapacityError("links", maxLinkLimit);
-
-            const newLinks = new Array(newCap - currentLinkCapacity);
-            for (let i = 0; i < newLinks.length; i++) newLinks[i] = new ReactiveLink();
-            for (let i = 0; i < newLinks.length - 1; i++) newLinks[i].nextFree = newLinks[i + 1];
-
-            const startIdx = linkPool.length;
-            linkPool.length = newCap;
-            for (let i = 0; i < newLinks.length; i++) linkPool[startIdx + i] = newLinks[i];
-            freeLinkHead = newLinks[0];
-            currentLinkCapacity = newCap;
+            if (policy === "throw" && linkPool.length >= currentLinkCapacity) throw new CapacityError("links", currentLinkCapacity);
+            // Incremental growth (P0): construct links on a free-list miss instead
+            // of doubling with an eager construction burst. The capacity LEDGER
+            // still doubles (stats() / ceiling semantics are unchanged) -- only the
+            // physical allocation is amortized. Eliminates multi-ms pauses in hot loops.
+            if (linkPool.length >= maxLinkLimit) throw new CapacityError("links", maxLinkLimit);
+            // Chunked refill (P1 rev2): construct a CONTIGUOUS run of links on a
+            // miss. Restores eager-pool heap locality for traversal-heavy graphs
+            // (lazy one-at-a-time construction interleaves pool objects with
+            // user allocations and costs 10-25% on dynamic/large-graph shapes)
+            // while keeping pauses bounded (~chunk x ~0.5us) and startup lazy.
+            let limit = (policy === "throw") ? currentLinkCapacity : maxLinkLimit;
+            let chunk = limit - linkPool.length;
+            if (chunk > 1024) chunk = 1024;
+            link = new ReactiveLink();
+            linkPool.push(link);
+            for (let i = 1; i < chunk; i++) {
+                const l = new ReactiveLink();
+                linkPool.push(l);
+                l.nextFree = freeLinkHead;
+                freeLinkHead = l;
+            }
+            if (linkPool.length > currentLinkCapacity) {
+                let doubled = currentLinkCapacity;
+                while (doubled < linkPool.length) doubled *= 2;
+                currentLinkCapacity = doubled > maxLinkLimit ? maxLinkLimit : doubled;
+            }
+        } else {
+            link = freeLinkHead;
+            freeLinkHead = link.nextFree;
+            link.nextFree = null;
         }
-
-        link = freeLinkHead;
-        freeLinkHead = link.nextFree;
-        link.nextFree = null;
         activeLinks = (activeLinks + 1) | 0;
 
         link.source = source;
@@ -497,6 +559,7 @@ export function createRegistry(config) {
         node.revertEpoch = 0;
         node.preBatchValue = undefined;
         node.preBatchVersion = 0;
+        node.nextMark = null;   // 1.3.0: defensive -- disposal during a sweep shouldn't happen, but ensures clean state
 
         node.gen = (node.gen + 1) | 0;
         node.nextFree = freeNodeHead;
@@ -513,36 +576,44 @@ export function createRegistry(config) {
      * @private
      */
     function createNode(value, flags) {
+        let node;
         if (freeNodeHead === null) {
-            if (policy === "throw") throw new CapacityError("nodes", currentNodesCapacity);
-            const newCap = currentNodesCapacity * 2;
-            const newNodes = new Array(newCap - currentNodesCapacity);
-            for (let i = 0; i < newNodes.length; i++) newNodes[i] = new ReactiveNode();
-            for (let i = 0; i < newNodes.length - 1; i++) newNodes[i].nextFree = newNodes[i + 1];
-
-            const startIdx = nodePool.length;
-            nodePool.length = newCap;
-            for (let i = 0; i < newNodes.length; i++) nodePool[startIdx + i] = newNodes[i];
-            freeNodeHead = newNodes[0];
-
-            effectQueueA.length = newCap;
-            effectQueueB.length = newCap;
-            markStack.length = newCap;
-            currentNodesCapacity = newCap;
+            if (policy === "throw" && nodePool.length >= currentNodesCapacity) throw new CapacityError("nodes", currentNodesCapacity);
+            // Incremental growth (P0): chunked construction on a free-list miss;
+            // ledger doubles for stats() continuity. The effect queues are no
+            // longer length-extended here: `arr.length = n` converts a PACKED
+            // array to HOLEY permanently (a hidden flush-path tax); sequential
+            // `arr[len++] = x` appends keep them packed and auto-grow. (markStack
+            // is gone entirely as of 1.3.0's intrusive mark stack.)
+            let chunk = (policy === "throw") ? (currentNodesCapacity - nodePool.length) : 256;
+            if (chunk > 256) chunk = 256;
+            node = new ReactiveNode();
+            nodePool.push(node);
+            for (let i = 1; i < chunk; i++) {
+                const n = new ReactiveNode();
+                nodePool.push(n);
+                n.nextFree = freeNodeHead;
+                freeNodeHead = n;
+            }
+            if (nodePool.length > currentNodesCapacity) {
+                let doubled = currentNodesCapacity;
+                while (doubled < nodePool.length) doubled *= 2;
+                currentNodesCapacity = doubled;
+            }
+        } else {
+            node = freeNodeHead;
+            freeNodeHead = node.nextFree;
+            node.nextFree = null;
         }
-
-        const node = freeNodeHead;
-        freeNodeHead = node.nextFree;
-        node.nextFree = null;
         activeNodes = (activeNodes + 1) | 0;
 
-        // 1.2.2: Clean free-list invariant (Andrii's recommendation).
+        // 1.2.3: 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
+        // fresh-allocation path (chunked refill above). Re-writing them
         // here was defense against a state that cannot exist.
         //
         // What stays: fields that define the new lifetime (value, flags, id,
@@ -554,7 +625,8 @@ export function createRegistry(config) {
         node.version = 0;
         node.evalVersion = 0;
         node.markEpoch = 0;
-        node.id = nodeSeq; nodeSeq = (nodeSeq + 1) | 0;   // fresh identity per allocation (ported from 1.1.5)
+        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).
         // ONLY observers (computed/effect) are adopted: a re-running owner disposes
@@ -564,7 +636,7 @@ export function createRegistry(config) {
         // reading computed -- adopting it meant that computed's next run wiped the
         // store key). Signals are therefore never owner-adopted.
         //
-        // 1.2.2 clean free-list invariant (extended to the owner tree):
+        // 1.2.3 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
@@ -646,23 +718,30 @@ export function createRegistry(config) {
 
     /**
      * Mark all transitive subscribers of `startNode` dirty.
-     * Iterative DFS via the markStack to avoid call-stack growth.
+     * 1.3.0: Iterative DFS backed by an intrusive linked-list stack (`nextMark`)
+     * instead of an external array (the iterative property itself is retained
+     * from 1.2.4) -- eliminates array bounds checks and consolidates the touched
+     * memory to the node's own cache line (we already loaded `t` to check
+     * t.markEpoch, so writing t.nextMark is in-cache).
      * Effects are enqueued for the flush phase; computeds are merely marked
      * (their re-evaluation is lazy -- triggered by the next read).
      * @private
      */
     function markDownstream(startNode) {
-        let stackLen = 0;
-        markStack[stackLen++] = startNode;
+        const gv = globalVersion;   // hoist invariant module-scope read into a local
+        let markHead = startNode;
+        startNode.nextMark = null;
 
-        while (stackLen !== 0) {
-            const n = markStack[--stackLen];
-            let link = n.headSub;
+        while (markHead !== null) {
+            const n = markHead;
+            markHead = n.nextMark;
+            n.nextMark = null;       // clear on pop; chain stays clean for future sweeps
 
+            let link = n.headSub;
             while (link !== null) {
                 const t = link.target;
-                if (t.markEpoch !== globalVersion) {
-                    t.markEpoch = globalVersion;
+                if (t.markEpoch !== gv) {
+                    t.markEpoch = gv;
                     const flags = t.flags;
 
                     if ((flags & FLAG_EFFECT) !== 0) {
@@ -671,7 +750,9 @@ export function createRegistry(config) {
                             activeQueue[activeQueueLen++] = t;
                         }
                     } else {
-                        markStack[stackLen++] = t;
+                        // Intrusive push: t.nextMark holds the prior head
+                        t.nextMark = markHead;
+                        markHead = t;
                     }
                 }
                 link = link.nextSub;
@@ -919,7 +1000,10 @@ export function createRegistry(config) {
     // closures: set() is the hot write path (a closure over `node` beats the
     // this[NODE_PTR] load and keeps `const {set} = signal()` working), and peek()'s
     // body is too cheap to absorb the node recovery.
-    function sharedUpdate(fn) { return this.set(fn(this[NODE_PTR].value)); }
+    function sharedUpdate(fn) {
+        return this.set(fn(this[NODE_PTR].value));
+    }
+
     function sharedSubscribe(fn) {
         const read = this;
         return effect(() => {
@@ -933,6 +1017,7 @@ export function createRegistry(config) {
             }
         });
     }
+
     // Shared peeks (one per registry, not per primitive). Save one closure
     // allocation per signal/computed creation versus the previous per-instance
     // arrows. Method-invoked, so `this` is the read function and this[NODE_PTR]
@@ -943,6 +1028,7 @@ export function createRegistry(config) {
         if (this[NODE_GEN] !== node.gen) return undefined;   // stale handle: slot recycled (ABA guard, matches read())
         return node.value;
     }
+
     function sharedComputedPeek() {
         const node = this[NODE_PTR];
         if (this[NODE_GEN] !== node.gen) return undefined;
@@ -1249,7 +1335,8 @@ export function createRegistry(config) {
      * no-ops (every node's `gen` bump invalidates any outstanding handle).
      */
     function destroy() {
-        for (let i = 0; i < currentNodesCapacity; i++) {
+        const nodeCount = nodePool.length;
+        for (let i = 0; i < nodeCount; i++) {
             const n = nodePool[i];
             n.value = undefined;
             n.computeFn = undefined;
@@ -1272,19 +1359,23 @@ export function createRegistry(config) {
             n.prevOwned = null;
             n.nextOwned = null;
             n.firstOwned = null;
+            n.nextMark = null;
 
             n.gen = (n.gen + 1) | 0;
 
-            effectQueueA[i] = null;
-            effectQueueB[i] = null;
-            markStack[i] = null;
-
-            if (i < currentNodesCapacity - 1) n.nextFree = nodePool[i + 1];
+            if (i < nodeCount - 1) n.nextFree = nodePool[i + 1];
         }
-        nodePool[currentNodesCapacity - 1].nextFree = null;
-        freeNodeHead = nodePool[0];
+        if (nodeCount > 0) {
+            nodePool[nodeCount - 1].nextFree = null;
+            freeNodeHead = nodePool[0];
+        } else {
+            freeNodeHead = null;
+        }
+        effectQueueA.length = 0;
+        effectQueueB.length = 0;
 
-        for (let i = 0; i < currentLinkCapacity; i++) {
+        const linkCount = linkPool.length;
+        for (let i = 0; i < linkCount; i++) {
             const l = linkPool[i];
             l.source = null;
             l.target = null;
@@ -1292,10 +1383,14 @@ export function createRegistry(config) {
             l.nextDep = null;
             l.prevSub = null;
             l.nextSub = null;
-            if (i < currentLinkCapacity - 1) l.nextFree = linkPool[i + 1];
+            if (i < linkCount - 1) l.nextFree = linkPool[i + 1];
+        }
+        if (linkCount > 0) {
+            linkPool[linkCount - 1].nextFree = null;
+            freeLinkHead = linkPool[0];
+        } else {
+            freeLinkHead = null;
         }
-        linkPool[currentLinkCapacity - 1].nextFree = null;
-        freeLinkHead = linkPool[0];
 
         activeNodes = 0;
         activeLinks = 0;
@@ -1321,6 +1416,7 @@ export function createRegistry(config) {
         const node = liveNode(handle);
         return node !== undefined && node.headSub !== null;
     }
+
     function observeObservers(handle, opts) {
         const node = liveNode(handle);
         if (node === undefined) throw new TypeError("observeObservers: argument is not a reactive handle");
@@ -1341,6 +1437,7 @@ export function createRegistry(config) {
             if (lifecycleMap.delete(node)) lifecycleCount = (lifecycleCount - 1) | 0;
         };
     }
+
     function describeNode(node) {
         const fl = node.flags;
         const kind = (fl & FLAG_EFFECT) !== 0 ? "effect" : (fl & FLAG_COMPUTED) !== 0 ? "computed" : "signal";
@@ -1354,6 +1451,7 @@ export function createRegistry(config) {
         d[NODE_GEN] = node.gen;   // descriptors are re-walkable handles; stamp gen so the ABA guard holds for them too
         return d;
     }
+
     // Gen-guarded handle resolution (1.2.1): with the v1.2 owner tree, the
     // ENGINE recycles slots autonomously (owner re-run cascade-disposes owned
     // children), so stale handles are a normal occurrence -- introspecting the
@@ -1367,20 +1465,28 @@ export function createRegistry(config) {
         if (handle[NODE_GEN] !== node.gen) return undefined;   // stale: slot recycled
         return node;
     }
+
     function nodeId(handle) {
         const node = liveNode(handle);
         return node !== undefined ? node.id : undefined;
     }
+
     function describe(handle) {
         const node = liveNode(handle);
         return node !== undefined ? describeNode(node) : undefined;
     }
+
     function forEachObserver(handle, fn) {
         const node = liveNode(handle);
         if (node === undefined) return;
         let l = node.headSub;
-        while (l !== null) { const nx = l.nextSub; fn(describeNode(l.target)); l = nx; }
+        while (l !== null) {
+            const nx = l.nextSub;
+            fn(describeNode(l.target));
+            l = nx;
+        }
     }
+
     /** Iterate this node's OWNED children (v1.2 owner tree). Additive 1.3 API
      *  prototype: lets devtools/studio walk + render the ownership hierarchy
      *  (cascade-disposal domains), which is invisible through dep/sub edges. */
@@ -1388,22 +1494,52 @@ export function createRegistry(config) {
         const node = liveNode(handle);
         if (node === undefined) return;
         let c = node.firstOwned;
-        while (c !== null) { const nx = c.nextOwned; fn(describeNode(c)); c = nx; }
+        while (c !== null) {
+            const nx = c.nextOwned;
+            fn(describeNode(c));
+            c = nx;
+        }
     }
+
     /** Descriptor of this node's owner, or undefined (top-level / stale handle). */
     function ownerOf(handle) {
         const node = liveNode(handle);
         if (node === undefined || node.owner === null) return undefined;
         return describeNode(node.owner);
     }
+
     function forEachSource(handle, fn) {
         const node = liveNode(handle);
         if (node === undefined) return;
         let l = node.headDep;
-        while (l !== null) { const nx = l.nextDep; fn(describeNode(l.source)); l = nx; }
+        while (l !== null) {
+            const nx = l.nextDep;
+            fn(describeNode(l.source));
+            l = nx;
+        }
     }
 
-    return {signal, computed, effect, dispose, batch, untrack, onCleanup, stats, destroy, isTracking, hasObservers, observeObservers, forEachObserver, forEachSource, forEachOwned, ownerOf, nodeId, describe, onGraphMutation};
+    return {
+        signal,
+        computed,
+        effect,
+        dispose,
+        batch,
+        untrack,
+        onCleanup,
+        stats,
+        destroy,
+        isTracking,
+        hasObservers,
+        observeObservers,
+        forEachObserver,
+        forEachSource,
+        forEachOwned,
+        ownerOf,
+        nodeId,
+        describe,
+        onGraphMutation
+    };
 }
 
 // -----------------------------------------------------------------
@@ -1463,27 +1599,35 @@ export function destroy() {
 export function hasObservers(handle) {
     return defaultRegistry.hasObservers(handle);
 }
+
 export function observeObservers(handle, opts) {
     return defaultRegistry.observeObservers(handle, opts);
 }
+
 export function forEachObserver(handle, fn) {
     return defaultRegistry.forEachObserver(handle, fn);
 }
+
 export function forEachSource(handle, fn) {
     return defaultRegistry.forEachSource(handle, fn);
 }
+
 export function onGraphMutation(fn) {
     return defaultRegistry.onGraphMutation(fn);
 }
+
 export function forEachOwned(handle, fn) {
     return defaultRegistry.forEachOwned(handle, fn);
 }
+
 export function ownerOf(handle) {
     return defaultRegistry.ownerOf(handle);
 }
+
 export function nodeId(handle) {
     return defaultRegistry.nodeId(handle);
 }
+
 export function describe(handle) {
     return defaultRegistry.describe(handle);
 }

package/Watch.js

@@ -2,7 +2,7 @@ import { effect, untrack } from "./Signal.js";
 
 /**
  * Sentinel for "first run" in `watch`. Distinguishes a legitimate `undefined`
- * source value from the uninitialized state — necessary because a naive
+ * source value from the uninitialized state -- necessary because a naive
  * `oldValue === undefined` check would conflate them.
  * @private
  */
@@ -10,7 +10,7 @@ const UNINITIALIZED = Symbol("watch.uninitialized");
 
 /**
  * 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 (matching MobX's `reaction` ergonomics).
  *
@@ -22,13 +22,13 @@ const UNINITIALIZED = Symbol("watch.uninitialized");
  * fires the effect but the projected value is unchanged (e.g.,
  * `watch(() => health() <= 0, ...)` where many `health` changes produce the
  * same boolean). Wrapping the source in a `computed` would achieve the same
- * via the computed's own equality check — the guard makes that wrapping
+ * via the computed's own equality check -- the guard makes that wrapping
  * optional.
  *
  * @example
  *   const count = signal(0);
- *   const stop = watch(count, (next, prev) => console.log(prev, "→", next));
- *   count.set(1);  // logs: 0 → 1
+ *   const stop = watch(count, (next, prev) => console.log(prev, "->", next));
+ *   count.set(1);  // logs: 0 -> 1
  *   stop();
  *
  * @example  // Self-disposing on a condition
@@ -65,7 +65,7 @@ export function watch(source, callback, options) {
     // ZERO-GC HOT PATH: the untrack body is hoisted into a closure allocated
     // ONCE at registration time. If this were declared inline as
     // `untrack(() => { ... })` inside the effect body, V8 would allocate a
-    // fresh closure on every fire — at 120fps that's 7,200 allocations per
+    // fresh closure on every fire -- at 120fps that's 7,200 allocations per
     // minute per watcher. The shared `currentNewValue` variable is the price
     // for keeping the per-fire cost at exactly zero allocations.
     const untrackedFire = () => {
@@ -123,7 +123,7 @@ export function when(predicate, callback) {
         // Defense-in-depth: even if dispose timing lets one more evaluation
         // through (e.g., during sync propagation), don't fire twice. In practice
         // stop() disposes this effect before any re-entry, so the early return is
-        // unreachable under the engine's self-cycle no-re-run guard — hence ignored.
+        // unreachable under the engine's self-cycle no-re-run guard -- hence ignored.
         /* c8 ignore next -- unreachable defensive guard; see comment above */
         if (fired) return;
         if (predicate()) {
@@ -142,10 +142,10 @@ export function when(predicate, callback) {
  * when `predicate` first returns a truthy value. Composes with `await` for
  * declarative async control flow against reactive state.
  *
- * ⚠️ **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. Every call allocates a
  * Promise object plus its executor closure plus internal Promise infrastructure
- * (resolve function, microtask state). This is unavoidable — Promises require
+ * (resolve function, microtask state). This is unavoidable -- Promises require
  * heap allocation by the language spec.
  *
  * **Use `whenAsync` for:** high-level scene/UI orchestration, boot sequences,
@@ -164,21 +164,21 @@ export function when(predicate, callback) {
  * Note: this promise never rejects. If the predicate never becomes truthy,
  * the promise never settles. Wrap in `Promise.race` for timeout semantics.
  *
- * @example  // ✅ OK — high-level orchestration
+ * @example  // OK -- high-level orchestration
  *   await whenAsync(() => user.isAuthenticated);
  *   navigate("/dashboard");
  *
- * @example  // ✅ OK — boot sequence
+ * @example  // OK -- boot sequence
  *   await whenAsync(() => assets.loaded);
  *   startGame();
  *
- * @example  // ❌ NOT OK — per-frame, allocates a Promise every frame
+ * @example  // NOT OK -- per-frame, allocates a Promise every frame
  *   function animate() {
  *       whenAsync(() => physics.settled).then(render);  // GC pressure!
  *       requestAnimationFrame(animate);
  *   }
  *
- * @example  // ✅ Same use case, zero-GC
+ * @example  // Same use case, zero-GC
  *   when(() => physics.settled, render);  // no Promise, no GC pressure
  *
  * @example  // With timeout

package/llms.txt

@@ -22,7 +22,7 @@ triggering write -- no `queueMicrotask`, no promises, no scheduler ticks.
 - **isTracking**: `isTracking()` returns true iff a read right now would record a dependency on this registry (for wrappers that lazily allocate signals).
 - **onCleanup**: registers teardown for the current computation; fires before each re-run and once on dispose. Works in effects and computeds.
 - **Observer-lifecycle introspection** (1.1.4; top-level + per-registry): `hasObservers(handle)` returns true iff a signal/computed has >=1 live observer right now (O(1); a `peek` does not count). `observeObservers(handle, { onConnect?, onDisconnect? })` fires on the 0->1 and 1->0 observer transitions (after registration; transition-only) and returns an idempotent unobserve -- the auto-pause hook for tickers (lite-time/lite-raf start a source only while it's watched). `forEachObserver(handle, fn)` / `forEachSource(handle, fn)` walk the live graph in either direction, passing a `{ kind, value }` descriptor (`kind` is `"signal" | "computed" | "effect"`) -- for inspection (lite-devtools). The surface is gated by an internal counter: zero steady-state cost when nothing is observed. `hasObservers`/`forEach*` no-op on a non-handle; `observeObservers` throws `TypeError`. **Node identity (1.1.5):** `nodeId(handle)` returns the node's stable per-allocation id, `describe(handle)` returns the handle's own `{ id, kind, value }` descriptor, and `forEach*` descriptors now carry `id` too; a descriptor is **re-walkable** (pass it back into `forEachObserver`/`forEachSource`) -- the recursion primitive lite-devtools uses to walk the full DAG. **Owner-tree introspection (1.2.1):** `forEachOwned(handle, fn)` walks a node's owned children (lifetime-binding edges from the 1.2 owner tree -- invisible through dep/sub); `ownerOf(handle)` returns the owner's descriptor or `undefined` for top-level / stale handles. **Stale-handle guard (1.2.1):** the entire introspection surface plus `peek()`/`read()`/`set()` is now generation-checked. A handle held across the 1.2 owner-cascade auto-dispose used to resolve `NODE_PTR` ungated and silently report the recycled slot's NEW resident; 1.2.1 surfaces stale handles as `undefined` (or `TypeError`, for `observeObservers`) -- same ABA discipline `dispose()` always had. Descriptors are gen-stamped so the re-walkable contract survives the guard. **Push-based mutation hook (1.2.1):** `onGraphMutation(fn)` registers a single nullable listener invoked synchronously at every mutation point with three integers `(opcode, intA, intB)` -- opcodes `1` node-create / `2` node-dispose / `3` link-add / `4` link-remove / `5` recompute. Zero-cost gate when no listener is registered (one branch-predicted null check); allocation-free dispatch when registered. The connection point for push-based devtools/studio. Contract: observe only -- never throw, never mutate.
-- **Registry**: `createRegistry({ maxNodes, maxLinks, onCapacityExceeded, maxFlushPasses })` creates an isolated reactive world with its own pools. Useful for tests, plugins, multi-tenant sandboxes. Top-level helpers use a default registry created at module load.
+- **Registry**: `createRegistry({ maxNodes, maxLinks, prealloc, onCapacityExceeded, maxFlushPasses })` creates an isolated reactive world with its own pools. Useful for tests, plugins, multi-tenant sandboxes. Top-level helpers use a default registry created at module load. `prealloc` (1.3.0; `"eager"` default | `"lazy"`) chooses up-front vs on-demand pool construction; `onCapacityExceeded` (`"throw"` default | `"grow"`) chooses fail-fast vs chunked-incremental growth bounded by the 16x link ceiling.
 - **CapacityError**: thrown when a fixed-size pool is exhausted under the `"throw"` policy, or when a `"grow"` policy hits the 16× starting-capacity ceiling on links.
 
 ## Architecture invariants
@@ -50,7 +50,48 @@ triggering write -- no `queueMicrotask`, no promises, no scheduler ticks.
 
 ## Version notes
 
-- **1.2.2** (current): `createNode` clean-free-list invariant audit. Removes
+- **1.3.0** (current): the **pool minor**. Node and link pools become growable
+  and incrementally populated; the propagation mark phase moves to an intrusive
+  linked-list stack; a small registry config surface is exposed. **The hot paths
+  and public callable API are byte-identical to 1.2.2** -- everything here is
+  pool mechanics, construction-time behavior, and new opt-in config. Steady-state
+  zero-GC is unchanged: after warm-up the pools recycle exactly as before.
+  **`prealloc` (`"eager"` default | `"lazy"`):** `"eager"` constructs the full
+  `maxNodes` / `maxLinks` pools up front -- deterministic latency, zero allocation
+  inside any subsequent hot path (the 16ms / 120fps render-frame contract), at the
+  cost of a larger resident heap every major GC traces. `"lazy"` treats the
+  capacities as ledgers, constructs nodes/links on first demand, recycles through
+  the free lists thereafter -- smaller heap, faster cold start, lighter GC marking,
+  identical zero-GC steady state after warm-up. **Growable pools
+  (`onCapacityExceeded: "grow"`):** pools extend past their initial capacity via
+  chunked refill -- contiguous runs of up to 1024 links / 256 nodes per free-list
+  miss, not a single doubling burst, so any one growth pause stays bounded
+  (~chunk x ~0.5us). The growth path no longer length-extends the effect queues
+  or mark stack (which permanently converted them PACKED->HOLEY). Link growth is
+  bounded by the hard `maxLinks * 16` ceiling; `"throw"` (default, now backed by a
+  named `CapacityError`) preserves the 1.2.x fail-fast behavior.
+  **`maxFlushPasses`** (default 100) is now a public config -- the cycle-protection
+  ceiling that throws an `Error` prefixed `"CycleError:"`. **Intrusive mark stack:**
+  `markDownstream` walks an iterative DFS backed by a `nextMark` field on each node
+  instead of an external `markStack` array; behaviorally identical (same nodes, same
+  order, same glitch-free guarantee), and the write lands in the cache line already
+  hot from reading `markEpoch`. `nextMark` is the only node-shape change in 1.3.0.
+  **`stats()` shape unchanged** (8 keys: `signals`, `computeds`, `effects`,
+  `activeNodes`, `activeLinks`, `pooledLinks`, `nodePoolCapacity`,
+  `linkPoolCapacity`); the capacity keys are ledgers under `"lazy"`. Cumulative
+  allocation counters (`totalAllocations` / `totalDisposals` / `poolGrowths`) remain
+  reserved for 1.4.0 and are still absent. **Tests:** 424 total, 414 pass, 0 fail,
+  10 skip (the 10 skips are 9 signalBox-staged-for-1.5.0 in
+  `test/24-signalbox_test.mjs` plus 1 architecturally-N/A SSR case in
+  `17-reactivity`); 4 new pool tests in `test/03-pool_test.mjs` cover the lazy
+  on-demand / never-allocated-destroy / grow-extends-ledger / link-ceiling paths.
+  **Coverage** (c8@11, Node 22): `Signal.js` 100% statements / 98.26% branches /
+  100% functions / 100% lines; `Watch.js` 100% across all four. Behavior-
+  preservation difftest: 20,000 direct + 10,000 batched writes vs the published
+  1.1.5 reference, 0 disagreements -- pool growth, chunked refill, and the intrusive
+  mark stack do not alter observable propagation. Drop-in over 1.2.2.
+
+- **1.2.2**: `createNode` clean-free-list invariant audit. Removes
   ten redundant field-writes that defended against a state the engine cannot
   produce on a clean free-list: seven graph/batch fields (`headDep`, `tailDep`,
   `headSub`, `tailSub`, `revertEpoch`, `preBatchValue`, `preBatchVersion`) and
@@ -270,10 +311,11 @@ interface NodeDescriptor {           // yielded by forEachObserver / forEachSour
 }
 
 interface RegistryConfig {
-  maxNodes?: number;                 // default 1024
-  maxLinks?: number;                 // default maxNodes * 4
+  maxNodes?: number;                 // default 1024 (ledger under "lazy")
+  maxLinks?: number;                 // default maxNodes * 4 (ledger under "lazy")
+  prealloc?: "eager" | "lazy";       // default "eager" (1.3.0): up-front vs on-demand pool construction
   maxFlushPasses?: number;           // default 100
-  onCapacityExceeded?: "throw" | "grow";  // default "throw"
+  onCapacityExceeded?: "throw" | "grow";  // default "throw"; "grow" = chunked refill, ledger doubles, 16x link ceiling
 }
 
 interface RegistryStats {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zakkster/lite-signal",
-  "version": "1.2.2",
+  "version": "1.3.0-rc",
   "description": "Zero-GC reactive graph. Monomorphic object pool, versioned push-pull propagation, 32-bit modular versioning. Built for hot paths and long-running processes.",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
   "license": "MIT",