@pyreon/core 0.22.0 → 0.24.0

package/src/context.ts

@@ -73,12 +73,62 @@ export function pushContext(values: Map<symbol, unknown>) {
   getStack().push(values)
 }
 
+/**
+ * Pop the LAST frame from the context stack.
+ *
+ * NOTE: position-based pop. Safe ONLY when the caller can guarantee that the
+ * top of the stack is the frame they want to remove (the strict LIFO contract).
+ * The `provide()` helper does NOT use this — it uses identity-based removal
+ * via `removeContextFrame` because reactive boundaries can push snapshot
+ * frames between a component's `provide(ctx, value)` and its eventual
+ * unmount, making the top-of-stack unsafe to assume.
+ */
 export function popContext() {
   const stack = getStack()
   if (stack.length === 0) return
   stack.pop()
 }
 
+/**
+ * Read the current live stack length WITHOUT allocating a snapshot.
+ *
+ * SSR cleanup uses this as a position marker: capture the live length
+ * before a component renders, pop the live stack back to that length
+ * after. Previously these sites called `captureContextStack().length`,
+ * which allocated a full snapshot array (potentially 40k+ entries
+ * under deeply-nested reactive boundaries — the same allocation the
+ * `captureContextStack` dedup work is designed to shrink) just to
+ * read its length. This helper avoids the allocation entirely AND
+ * decouples SSR cleanup from `captureContextStack`'s snapshot shape,
+ * so dedup at capture time can never silently break SSR length
+ * bookkeeping.
+ */
+export function getContextStackLength(): number {
+  return getStack().length
+}
+
+/**
+ * Remove a SPECIFIC frame from the context stack by reference identity.
+ *
+ * Internal — used by `provide()` and `withContext()` to safely clean up
+ * their pushed frame on unmount even when other frames have been pushed
+ * between push and pop (e.g. a reactive boundary's `restoreContextStack`
+ * pushing snapshot frames during the descendant's lifecycle). The
+ * symmetric position-based `popContext()` would pop the wrong frame in
+ * that case and orphan the descendant's provider frame on the live stack
+ * — the root cause of the 321k-entry context-stack leak under repeated
+ * reactive remounts.
+ *
+ * Uses `lastIndexOf` (LIFO match) — picks the most-recently-pushed frame
+ * with that exact reference, so `provide(ctx, a); provide(ctx, b)` followed
+ * by two unmounts removes them in reverse order.
+ */
+export function removeContextFrame(frame: Map<symbol, unknown>): void {
+  const stack = getStack()
+  const idx = stack.lastIndexOf(frame)
+  if (idx !== -1) stack.splice(idx, 1)
+}
+
 /**
  * Read the nearest provided value for a context.
  * Falls back to `context.defaultValue` if none found.
@@ -111,8 +161,17 @@ export function useContext<T>(context: Context<T>): T {
  * }
  */
 export function provide<T>(context: Context<T>, value: T): void {
-  pushContext(new Map<symbol, unknown>([[context.id, value]]))
-  onUnmount(() => popContext())
+  const frame = new Map<symbol, unknown>([[context.id, value]])
+  pushContext(frame)
+  // Identity-based removal — the top of the stack is NOT guaranteed to be
+  // this frame at unmount time. Reactive boundaries (`mountReactive`'s
+  // effect snapshot-restore + the inner `restoreContextStack` call) push
+  // additional snapshot frames during a descendant's lifecycle. A
+  // position-based `popContext()` would pop the snapshot frame instead
+  // of this provider's frame and orphan the provider on the live stack.
+  // See `.claude/rules/anti-patterns.md` "Context-stack frame identity"
+  // for the full bug class.
+  onUnmount(() => removeContextFrame(frame))
 }
 
 /**
@@ -125,7 +184,11 @@ export function withContext<T>(context: Context<T>, value: T, fn: () => void) {
   try {
     fn()
   } finally {
-    popContext()
+    // Same identity-based-removal rationale as `provide()` — `fn()` may
+    // synchronously trigger a `mountReactive` re-run whose snapshot-restore
+    // window leaves the top-of-stack pointing at a snapshot push, not our
+    // frame.
+    removeContextFrame(frame)
   }
 }
 
@@ -134,17 +197,92 @@ export function withContext<T>(context: Context<T>, value: T, fn: () => void) {
 export type ContextSnapshot = Map<symbol, unknown>[]
 
 /**
- * Capture a snapshot of the current context stack.
+ * Capture a snapshot of the current context stack, **deduplicated** so
+ * only the topmost frame for each context-id is retained.
  *
  * Used by `mountReactive` to preserve the context that was active when a
  * reactive boundary (e.g. `<Show>`, `<For>`) was set up. When the boundary
  * later mounts new children inside an effect, the snapshot is restored so
  * those children can see ancestor providers via `useContext()`.
+ *
+ * **Why dedup is semantically equivalent to a full snapshot:**
+ * `useContext()` walks the stack in reverse and returns the first frame
+ * matching the requested context-id (`for (let i = stack.length - 1; i >= 0; i--)`
+ * — see implementation below in this file). Any frame deeper in the
+ * stack that ALSO provides the same id is unreachable by definition —
+ * the reverse walk stops at the first match. Those shadowed frames are
+ * dead weight in the snapshot: they carry no observable value, they
+ * cost memory, and they can NEVER affect program behavior.
+ *
+ * The dedup walks frames from top to bottom keeping a `seen` set of
+ * already-resolved context ids. A frame is kept iff at least one of
+ * its keys is NOT in `seen` (i.e. it's the topmost provider for at
+ * least one id). All of a frame's keys are added to `seen` regardless
+ * of whether the frame is kept — `seen` represents "ids that are
+ * already provided by a more-recent frame".
+ *
+ * **Why this is safe for `restoreContextStack`:**
+ * `restoreContextStack` pushes the snapshot's frames onto the live
+ * stack, runs `fn()`, then removes those frames by **reference
+ * identity** (`stack.lastIndexOf(frame)`) — NOT by position or count
+ * of the snapshot. A deduped snapshot pushes fewer frames; the same
+ * reference-identity cleanup removes exactly those frames. No
+ * bookkeeping invariant breaks.
+ *
+ * **Why this is safe for the live stack length invariant:**
+ * SSR cleanup uses `getContextStackLength()` (a sibling helper) for
+ * position-marker bookkeeping. That helper reads the LIVE stack
+ * length, NOT the snapshot length, so dedup at capture time has zero
+ * effect on SSR cleanup behavior.
+ *
+ * **Why this is needed:**
+ * Under deeply-nested reactive boundaries (a `<Show>` inside a `<For>`
+ * inside a `<Suspense>`, each effect capturing its own snapshot at
+ * setup time), the live stack temporarily holds the same context-id
+ * pushed multiple times during nested `restoreContextStack` windows.
+ * The pre-dedup `[...getStack()]` snapshot baked those duplicates in
+ * permanently — each effect's closure retained an O(stack-depth)
+ * array for its lifetime. Reported heap snapshots from 0.21.x showed
+ * 1.22 MB / 321k-entry arrays from this pattern. The 0.23.0
+ * restoreContextStack reference-identity fix cleaned the LIVE stack
+ * but left the residual snapshot-amplification — observable as 20
+ * arrays at 157 KB each (40k entries) retained by effect closures.
+ * This dedup collapses each captured snapshot to ~N entries, where
+ * N is the number of DISTINCT context ids in scope (typically 2-10
+ * in real apps).
  */
 export function captureContextStack(): ContextSnapshot {
-  // Shallow copy — each frame (Map) is shared by reference, which is
-  // correct because providers don't mutate frames after creation.
-  return [...getStack()]
+  const stack = getStack()
+  // Fast path: empty stack or single frame is the common case for
+  // top-level mounts and zero-context apps. Skip the dedup machinery.
+  if (stack.length <= 1) return stack.slice()
+
+  // Walk top-to-bottom, keeping the topmost frame for each context-id.
+  // Each frame is a Map<symbol, unknown>; `seen` tracks ids already
+  // provided by a more-recent frame.
+  const seen = new Set<symbol>()
+  const reversed: Map<symbol, unknown>[] = []
+  for (let i = stack.length - 1; i >= 0; i--) {
+    const frame = stack[i]
+    if (!frame) continue
+    // A frame is unique if it provides at least one not-yet-seen id.
+    // Iterate ALL keys to accumulate them into `seen` (so deeper
+    // frames sharing any one of them are correctly shadowed even if
+    // they also have other unique keys).
+    let unique = false
+    for (const id of frame.keys()) {
+      if (!seen.has(id)) {
+        seen.add(id)
+        unique = true
+      }
+    }
+    if (unique) reversed.push(frame)
+  }
+  // We walked top-to-bottom; the result is in reverse stack order.
+  // Reverse back so the snapshot is in bottom-to-top order, matching
+  // the order `restoreContextStack` pushes them.
+  reversed.reverse()
+  return reversed
 }
 
 /**
@@ -162,7 +300,6 @@ export function captureContextStack(): ContextSnapshot {
  */
 export function restoreContextStack<T>(snapshot: ContextSnapshot, fn: () => T): T {
   const stack = getStack()
-  const insertIndex = stack.length
 
   // Push captured snapshot frames at the END of the current stack.
   for (const frame of snapshot) {
@@ -172,15 +309,27 @@ export function restoreContextStack<T>(snapshot: ContextSnapshot, fn: () => T):
   try {
     return fn()
   } finally {
-    // Splice out exactly the snapshot frames we pushed (they sit at
-    // [insertIndex, insertIndex + snapshot.length)). Any frames `fn()`
-    // pushed AFTER our snapshot (provider frames) get shifted down by
-    // `snapshot.length` positions but remain on the stack. Their owning
-    // components' `onUnmount(popContext)` handlers will pop them in
-    // LIFO order on subtree teardown — splice preserves that ordering
-    // because it doesn't touch frames at indices >= insertIndex +
-    // snapshot.length until the splice operation itself.
-    stack.splice(insertIndex, snapshot.length)
+    // Remove our pushed snapshot frames by REFERENCE IDENTITY (not by
+    // position). `fn()` may legitimately remove frames at indices BEFORE
+    // our push window — most commonly via `provide()` registering
+    // `onUnmount(removeContextFrame(frame))` and a descendant unmount
+    // firing inside this restore window. A position-based `splice` would
+    // either pull the wrong frames or no-op when the live stack has
+    // shrunk below the original `insertIndex + snapshot.length` —
+    // orphaning the snapshot pushes on the live stack and producing the
+    // 321k-frame leak reported under repeated reactive remounts.
+    //
+    // Iterate in reverse so multi-occurrence frames (the same Map ref
+    // pushed by multiple nested restores) are removed in LIFO push order.
+    // `lastIndexOf` is O(N); N is small in practice (single-digit nesting),
+    // and the alternative `findLastIndex(f => f === frame)` is the same
+    // cost.
+    for (let i = snapshot.length - 1; i >= 0; i--) {
+      const frame = snapshot[i]
+      if (!frame) continue
+      const idx = stack.lastIndexOf(frame)
+      if (idx !== -1) stack.splice(idx, 1)
+    }
   }
 }
 

package/src/error-boundary.ts

@@ -68,7 +68,13 @@ export function ErrorBoundary(props: {
 
   // Push synchronously — before children are mounted — so child errors see this boundary
   pushErrorBoundary(handler)
-  onUnmount(() => popErrorBoundary())
+  // Identity-based pop: pass our own handler reference. Sibling boundaries
+  // can unmount in any order driven by the renderer (keyed `<For>` removal
+  // of a non-last item, `<Show>` flipping on the FIRST of N siblings, route
+  // nav, etc.) — without passing the handler reference, the position-based
+  // `pop()` would remove the WRONG boundary's handler. Same bug class as
+  // #725 (`popContext()` orphaning provider frames under reactive remount).
+  onUnmount(() => popErrorBoundary(handler))
 
   return (): VNodeChildAtom => {
     const err = error()

package/src/index.ts

@@ -8,9 +8,11 @@ export {
   captureContextStack,
   createContext,
   createReactiveContext,
+  getContextStackLength,
   popContext,
   provide,
   pushContext,
+  removeContextFrame,
   restoreContextStack,
   setContextStackProvider,
   useContext,

package/src/tests/context.test.ts

@@ -1,13 +1,17 @@
 import { runWithHooks } from '../component'
 import {
+  captureContextStack,
   createContext,
+  getContextStackLength,
   popContext,
   provide,
   pushContext,
+  restoreContextStack,
   setContextStackProvider,
   useContext,
   withContext,
 } from '../context'
+import type { ContextSnapshot } from '../context'
 import type { ComponentFn, Props } from '../types'
 
 describe('createContext', () => {
@@ -259,3 +263,367 @@ describe('setContextStackProvider', () => {
     setContextStackProvider(() => freshStack)
   })
 })
+
+// ─── captureContextStack — dedup semantics ───────────────────────────────────
+//
+// The capture step deduplicates: only the topmost frame per context-id is
+// retained in the snapshot. This is a HEAP-LEAK fix: under deeply-nested
+// reactive boundaries, each effect's setup-time snapshot used to grow with
+// the live stack's transient duplicates (40k+ entries reported in 0.21.x;
+// see context.ts JSDoc for the full story). Dedup collapses the captured
+// size to ~N entries where N is the number of distinct context ids in
+// scope (typically 2-10 in real apps).
+//
+// Safety property: `useContext` walks the stack in reverse and stops at
+// the first matching frame; any shadowed frame is unreachable. The dedup
+// preserves the topmost frame per id, so `useContext` returns the same
+// value before and after.
+
+describe('captureContextStack — dedup', () => {
+  const restoreStack: Map<symbol, unknown>[][] = []
+  let testStack: Map<symbol, unknown>[]
+
+  beforeEach(() => {
+    testStack = []
+    setContextStackProvider(() => testStack)
+  })
+
+  afterEach(() => {
+    while (restoreStack.length > 0) restoreStack.pop()
+    const freshStack: Map<symbol, unknown>[] = []
+    setContextStackProvider(() => freshStack)
+  })
+
+  test('empty stack snapshot is empty', () => {
+    expect(captureContextStack()).toEqual([])
+  })
+
+  test('single frame snapshot is identical', () => {
+    const ctx = createContext('default')
+    pushContext(new Map([[ctx.id, 'A']]))
+    const snap = captureContextStack()
+    expect(snap).toHaveLength(1)
+    expect(snap[0]).toBe(testStack[0]) // same reference
+    popContext()
+  })
+
+  test('stack with no duplicate ids snapshots verbatim', () => {
+    const a = createContext('a-default')
+    const b = createContext('b-default')
+    const c = createContext('c-default')
+    pushContext(new Map([[a.id, 'A']]))
+    pushContext(new Map([[b.id, 'B']]))
+    pushContext(new Map([[c.id, 'C']]))
+    const snap = captureContextStack()
+    expect(snap).toHaveLength(3)
+    expect(snap.map((f) => Array.from(f.values()))).toEqual([['A'], ['B'], ['C']])
+    popContext()
+    popContext()
+    popContext()
+  })
+
+  test('duplicate ids collapse to topmost', () => {
+    // Same context-id pushed 3 times — typical of nested restoreContextStack
+    // windows. Only the topmost should appear in the snapshot.
+    const ctx = createContext('default')
+    pushContext(new Map([[ctx.id, 'A']]))
+    pushContext(new Map([[ctx.id, 'B']]))
+    pushContext(new Map([[ctx.id, 'C']]))
+    const snap = captureContextStack()
+    expect(snap).toHaveLength(1)
+    expect(snap[0]!.get(ctx.id)).toBe('C') // topmost wins
+    popContext()
+    popContext()
+    popContext()
+  })
+
+  test('mixed: deep stack with mostly duplicates collapses', () => {
+    // Simulates the bug shape: same context pushed 40 times via nested
+    // restore windows + one unique frame at the top.
+    const repeated = createContext('default')
+    const unique = createContext('default')
+    for (let i = 0; i < 40; i++) {
+      pushContext(new Map([[repeated.id, `dup-${i}`]]))
+    }
+    pushContext(new Map([[unique.id, 'unique']]))
+    expect(testStack).toHaveLength(41)
+
+    const snap = captureContextStack()
+    // Result: topmost `repeated` frame + the `unique` frame = 2 entries.
+    // Pre-fix this snapshot would have all 41 frames — the leak.
+    expect(snap).toHaveLength(2)
+    // Ordering must match push order (bottom-to-top in the array).
+    expect(snap[0]!.get(repeated.id)).toBe('dup-39')
+    expect(snap[1]!.get(unique.id)).toBe('unique')
+
+    for (let i = 0; i < 41; i++) popContext()
+  })
+
+  test('multi-key frame: kept if it provides ANY un-shadowed id', () => {
+    // Frame with two contexts; only one is shadowed by a deeper push.
+    const a = createContext('a')
+    const b = createContext('b')
+    pushContext(new Map<symbol, unknown>([[a.id, 'a1'], [b.id, 'b1']]))
+    pushContext(new Map([[a.id, 'a2']])) // shadows `a`, NOT `b`
+
+    const snap = captureContextStack()
+    // Both frames should remain: the upper provides `a`, the lower
+    // still provides un-shadowed `b`.
+    expect(snap).toHaveLength(2)
+
+    // Verify useContext semantics survive: a→a2, b→b1
+    setContextStackProvider(() => snap)
+    expect(useContext(a)).toBe('a2')
+    expect(useContext(b)).toBe('b1')
+    setContextStackProvider(() => testStack)
+
+    popContext()
+    popContext()
+  })
+
+  test('multi-key frame: dropped if ALL its ids are shadowed', () => {
+    const a = createContext('a')
+    const b = createContext('b')
+    pushContext(new Map<symbol, unknown>([[a.id, 'a1'], [b.id, 'b1']]))
+    pushContext(new Map<symbol, unknown>([[a.id, 'a2'], [b.id, 'b2']]))
+
+    const snap = captureContextStack()
+    expect(snap).toHaveLength(1)
+    expect(snap[0]!.get(a.id)).toBe('a2')
+    expect(snap[0]!.get(b.id)).toBe('b2')
+
+    popContext()
+    popContext()
+  })
+
+  test('useContext returns same value pre/post dedup for arbitrary read patterns', () => {
+    // Cross-check: build a complex stack, capture, then verify useContext
+    // returns the same value when reading from the original stack vs the
+    // deduped snapshot. This is the load-bearing semantic-equivalence
+    // assertion for the safety argument.
+    const a = createContext('a-default')
+    const b = createContext('b-default')
+    const c = createContext('c-default')
+    pushContext(new Map([[a.id, 'a1']]))
+    pushContext(new Map<symbol, unknown>([[a.id, 'a2'], [b.id, 'b1']]))
+    pushContext(new Map([[c.id, 'c1']]))
+    pushContext(new Map([[a.id, 'a3']]))
+    pushContext(new Map([[b.id, 'b2']]))
+
+    // Read against original stack
+    const beforeA = useContext(a)
+    const beforeB = useContext(b)
+    const beforeC = useContext(c)
+
+    // Capture (dedup happens) and read against the snapshot
+    const snap = captureContextStack()
+    setContextStackProvider(() => snap)
+    const afterA = useContext(a)
+    const afterB = useContext(b)
+    const afterC = useContext(c)
+
+    expect(afterA).toBe(beforeA) // 'a3' from the topmost frame
+    expect(afterB).toBe(beforeB) // 'b2' from the topmost frame
+    expect(afterC).toBe(beforeC) // 'c1' (still the only c-provider)
+
+    // Clean up
+    setContextStackProvider(() => testStack)
+    for (let i = 0; i < 5; i++) popContext()
+  })
+})
+
+// ─── restoreContextStack — works against deduped snapshots ───────────────────
+
+describe('restoreContextStack — with deduped snapshots', () => {
+  let testStack: Map<symbol, unknown>[]
+
+  beforeEach(() => {
+    testStack = []
+    setContextStackProvider(() => testStack)
+  })
+
+  afterEach(() => {
+    const freshStack: Map<symbol, unknown>[] = []
+    setContextStackProvider(() => freshStack)
+  })
+
+  test('restores deduped snapshot — fn() sees correct context, stack cleans up', () => {
+    const ctx = createContext('default')
+    pushContext(new Map([[ctx.id, 'A']]))
+    pushContext(new Map([[ctx.id, 'B']]))
+    pushContext(new Map([[ctx.id, 'C']]))
+
+    const snap = captureContextStack()
+    expect(snap).toHaveLength(1) // dedup collapsed to topmost
+
+    // Now empty the stack to simulate post-mount state
+    popContext()
+    popContext()
+    popContext()
+    expect(testStack).toHaveLength(0)
+
+    // Restore the deduped snapshot
+    const observed = restoreContextStack(snap, () => {
+      // Inside fn(): stack has the deduped frame
+      expect(testStack).toHaveLength(1)
+      return useContext(ctx)
+    })
+
+    // fn() saw the topmost-frame value, NOT 'default' — semantic equivalence
+    expect(observed).toBe('C')
+    // After restore, the snapshot's frames are removed by reference identity
+    expect(testStack).toHaveLength(0)
+  })
+
+  test('restoring 40-duplicate stack only pushes/pops 1 frame post-dedup', () => {
+    // This is the bug-shape regression test. Pre-dedup, this snapshot was
+    // 40 entries; restore pushed 40 then removed 40. Post-dedup, both
+    // operations move 1 frame.
+    const ctx = createContext('default')
+    for (let i = 0; i < 40; i++) {
+      pushContext(new Map([[ctx.id, `dup-${i}`]]))
+    }
+    const snap = captureContextStack()
+    expect(snap).toHaveLength(1)
+
+    // Empty the live stack so the restore is observable in isolation.
+    while (testStack.length > 0) popContext()
+
+    let observedLenInside = -1
+    restoreContextStack(snap, () => {
+      observedLenInside = testStack.length
+    })
+
+    // 1 push during fn, 1 splice after = stack stays balanced.
+    expect(observedLenInside).toBe(1)
+    expect(testStack).toHaveLength(0)
+  })
+})
+
+// ─── Leak audit: snapshot allocations stay bounded under deep stacks ─────────
+//
+// This is the regression lock for the heap-snapshot finding that motivated
+// the dedup. Reported in 0.21.x: 1.22 MB / 321k-entry arrays retained by
+// effect closures under deeply-nested reactive boundaries. The 0.23.0
+// restoreContextStack fix cleaned the live stack but residual snapshot
+// amplification persisted (~3 MB / 20×40k-entry arrays). This dedup
+// closes that. The test below makes the bug-shape impossible to
+// re-introduce silently: it builds the deep-stack scenario, captures
+// N snapshots that previously would each have held the stack-depth, and
+// asserts the TOTAL frame count across all snapshots scales with the
+// number of DISTINCT context ids in scope, NOT with the stack depth.
+
+describe('captureContextStack — leak audit (regression lock)', () => {
+  let testStack: Map<symbol, unknown>[]
+
+  beforeEach(() => {
+    testStack = []
+    setContextStackProvider(() => testStack)
+  })
+
+  afterEach(() => {
+    const freshStack: Map<symbol, unknown>[] = []
+    setContextStackProvider(() => freshStack)
+  })
+
+  test('1000 snapshots of a deep duplicate-heavy stack retain bounded total frames', () => {
+    // Build a stack of 100 frames, all pushing the same context (simulates
+    // nested restoreContextStack windows). Then capture 1000 snapshots —
+    // one per effect setup, as happens in a large component tree.
+    const ctx = createContext('default')
+    for (let i = 0; i < 100; i++) {
+      pushContext(new Map([[ctx.id, `dup-${i}`]]))
+    }
+
+    const snapshots: ContextSnapshot[] = []
+    for (let i = 0; i < 1000; i++) {
+      snapshots.push(captureContextStack())
+    }
+
+    // Pre-dedup: 1000 snapshots × 100 frames = 100,000 frame references.
+    // Post-dedup: 1000 snapshots × 1 frame (topmost) = 1,000 frame references.
+    // The assertion bounds total retention at the dedup-correct ceiling.
+    const totalFrames = snapshots.reduce((sum, s) => sum + s.length, 0)
+    expect(totalFrames).toBe(1000) // 1000 snapshots × 1 unique id
+
+    // Clean up
+    for (let i = 0; i < 100; i++) popContext()
+  })
+
+  test('mixed deep stack: total frames bounded by distinct id count, not depth', () => {
+    // 50 unique contexts pushed into a stack of 500 frames (10 duplicates
+    // per context). Capture 100 snapshots.
+    const ctxs = Array.from({ length: 50 }, () => createContext('default'))
+    for (let depth = 0; depth < 10; depth++) {
+      for (const ctx of ctxs) {
+        pushContext(new Map([[ctx.id, `d${depth}`]]))
+      }
+    }
+    expect(testStack).toHaveLength(500)
+
+    const snapshots: ContextSnapshot[] = []
+    for (let i = 0; i < 100; i++) {
+      snapshots.push(captureContextStack())
+    }
+
+    // Pre-dedup: 100 × 500 = 50,000 frame references.
+    // Post-dedup: 100 × 50 (topmost per distinct id) = 5,000 frame
+    // references. 10× reduction matches the empirical bug-shape.
+    const totalFrames = snapshots.reduce((sum, s) => sum + s.length, 0)
+    expect(totalFrames).toBe(100 * 50)
+
+    // Clean up
+    for (let i = 0; i < 500; i++) popContext()
+  })
+})
+
+// ─── getContextStackLength ──────────────────────────────────────────────────
+
+describe('getContextStackLength', () => {
+  let testStack: Map<symbol, unknown>[]
+
+  beforeEach(() => {
+    testStack = []
+    setContextStackProvider(() => testStack)
+  })
+
+  afterEach(() => {
+    const freshStack: Map<symbol, unknown>[] = []
+    setContextStackProvider(() => freshStack)
+  })
+
+  test('returns the LIVE stack length, not the deduped snapshot length', () => {
+    // This is the load-bearing distinction: SSR cleanup uses
+    // `getContextStackLength()` as a position marker, and it must reflect
+    // the live (un-deduped) stack length so subsequent `popContext` calls
+    // pop the right number of frames.
+    const ctx = createContext('default')
+    pushContext(new Map([[ctx.id, 'A']]))
+    pushContext(new Map([[ctx.id, 'B']]))
+    pushContext(new Map([[ctx.id, 'C']]))
+
+    expect(getContextStackLength()).toBe(3) // live length
+    expect(captureContextStack()).toHaveLength(1) // deduped snapshot length
+
+    popContext()
+    popContext()
+    popContext()
+  })
+
+  test('zero on empty stack', () => {
+    expect(getContextStackLength()).toBe(0)
+  })
+
+  test('matches stack array length after push/pop cycles', () => {
+    const ctx = createContext('default')
+    expect(getContextStackLength()).toBe(0)
+    pushContext(new Map([[ctx.id, 'A']]))
+    expect(getContextStackLength()).toBe(1)
+    pushContext(new Map([[ctx.id, 'B']]))
+    expect(getContextStackLength()).toBe(2)
+    popContext()
+    expect(getContextStackLength()).toBe(1)
+    popContext()
+    expect(getContextStackLength()).toBe(0)
+  })
+})