@363045841yyt/klinechart-core 0.8.11-alpha.0 → 0.8.12

package/src/components/orderBookHeatmap/__tests__/controller.test.ts

@@ -0,0 +1,237 @@
+import { describe, it, expect } from 'vitest'
+
+import { createHeatmapController } from '../createHeatmapController'
+import { createOrderBookState } from '../createOrderBookState'
+import type { BookSnapshot, OrderBookDelta } from '../types'
+
+function bid(ts: number, price: number, size: number): OrderBookDelta {
+    return { side: 'bid', price, size, timestamp: ts }
+}
+function ask(ts: number, price: number, size: number): OrderBookDelta {
+    return { side: 'ask', price, size, timestamp: ts }
+}
+
+function findBidSize(snap: BookSnapshot, price: number): number {
+    for (const [p, s] of snap.bids) if (p === price) return s
+    return 0
+}
+
+describe('createHeatmapController', () => {
+    it('auto-generates snapshots at the configured interval driven by delta timestamps', () => {
+        const ctrl = createHeatmapController({
+            tickSize: 0.01,
+            snapshotIntervalMs: 100,
+            snapshotRingCapacity: 10,
+            deltaArchiveMaxSize: 1000,
+            logColorRange: { sizeMin: 1, sizeMax: 1000 },
+        })
+        // Send 5 deltas spanning 0 → 450ms — 4 interval crossings.
+        ctrl.ingestDelta(bid(0, 100, 1))
+        ctrl.ingestDelta(bid(150, 100, 2)) // crosses 100ms
+        ctrl.ingestDelta(bid(220, 100, 3)) // crosses 200ms
+        ctrl.ingestDelta(bid(330, 100, 4)) // crosses 300ms
+        ctrl.ingestDelta(bid(450, 100, 5)) // crosses 400ms
+        const st = ctrl.state.peek()
+        // Each crossing produces one snapshot.
+        expect(st.snapshotCount).toBe(4)
+        expect(st.deltaCount).toBe(5)
+        ctrl.dispose()
+    })
+
+    it('records flash orders in the archive even when they vanish before the next snapshot', () => {
+        const ctrl = createHeatmapController({
+            tickSize: 0.01,
+            snapshotIntervalMs: 100,
+            snapshotRingCapacity: 10,
+            deltaArchiveMaxSize: 1000,
+            logColorRange: { sizeMin: 1, sizeMax: 1000 },
+        })
+        // First delta anchors snapshot clock at t=0.
+        ctrl.ingestDelta(bid(0, 100, 1))
+        // Place + cancel inside the [0, 100) window.
+        ctrl.ingestDelta(bid(10, 99.5, 500)) // flash place
+        ctrl.ingestDelta(bid(20, 99.5, 0)) // flash cancel
+        // Now cross the interval to fire a snapshot.
+        ctrl.ingestDelta(bid(150, 100, 2))
+        const st = ctrl.state.peek()
+        expect(st.snapshotCount).toBe(1)
+        // The forced snapshot should NOT show the flash level (it was cancelled).
+        ctrl.forceSnapshot()
+        const latest = ctrl.state.peek().latestSnapshot
+        expect(latest).not.toBeNull()
+        expect(findBidSize(latest as BookSnapshot, 99.5)).toBe(0)
+        // But replay across the flash window MUST show it.
+        const series = ctrl.replay(5, 25, 5)
+        const flashOn = series.find((s) => findBidSize(s, 99.5) === 500)
+        const flashOff = series.find(
+            (s) => s.timestamp >= 20 && findBidSize(s, 99.5) === 0,
+        )
+        expect(flashOn).toBeDefined()
+        expect(flashOff).toBeDefined()
+        ctrl.dispose()
+    })
+
+    it('forceSnapshot() pushes the current book state immediately', () => {
+        const ctrl = createHeatmapController({
+            tickSize: 0.01,
+            snapshotIntervalMs: 1000,
+            snapshotRingCapacity: 10,
+            deltaArchiveMaxSize: 1000,
+            logColorRange: { sizeMin: 1, sizeMax: 1000 },
+        })
+        ctrl.ingestDelta(bid(0, 100, 5))
+        ctrl.ingestDelta(ask(0, 101, 7))
+        expect(ctrl.state.peek().snapshotCount).toBe(0)
+        ctrl.forceSnapshot()
+        const st = ctrl.state.peek()
+        expect(st.snapshotCount).toBe(1)
+        expect(st.latestSnapshot?.bids).toEqual([[100, 5]])
+        expect(st.latestSnapshot?.asks).toEqual([[101, 7]])
+        ctrl.dispose()
+    })
+
+    it('replay(t1,t2) reconstructs the book equivalent to fold-left of deltas', () => {
+        // Property-test equivalent: build a fixed delta stream, replay through
+        // the controller, and assert the replayed snapshot at every grid
+        // timestamp equals the snapshot computed by applying deltas
+        // up-to-and-including that timestamp to a fresh order book.
+        const ctrl = createHeatmapController({
+            tickSize: 0.01,
+            snapshotIntervalMs: 50,
+            snapshotRingCapacity: 100,
+            deltaArchiveMaxSize: 10_000,
+            logColorRange: { sizeMin: 1, sizeMax: 1000 },
+        })
+        const deltas: OrderBookDelta[] = [
+            bid(0, 100, 5),
+            ask(0, 101, 5),
+            bid(40, 99.5, 10),
+            ask(60, 101.5, 3),
+            bid(75, 100, 0), // remove
+            ask(110, 102, 4),
+            bid(140, 99.5, 25),
+            ask(170, 101, 0),
+            bid(190, 99, 1),
+        ]
+        for (const d of deltas) ctrl.ingestDelta(d)
+
+        const replayed = ctrl.replay(0, 200, 25)
+
+        for (const snap of replayed) {
+            const oracle = createOrderBookState({ tickSize: 0.01 })
+            for (const d of deltas) {
+                if (d.timestamp <= snap.timestamp) oracle.applyDelta(d)
+            }
+            const expected = oracle.snapshot()
+            expect(snap.bids).toEqual(expected.bids)
+            expect(snap.asks).toEqual(expected.asks)
+        }
+        ctrl.dispose()
+    })
+
+    it('replay across midpoint matches live-state snapshot at that point', () => {
+        // Hand-coded equivalence: a known midpoint timestamp must yield the
+        // same book state whether reached via live ingest or via replay.
+        const cfg = {
+            tickSize: 0.01,
+            snapshotIntervalMs: 100,
+            snapshotRingCapacity: 64,
+            deltaArchiveMaxSize: 10_000,
+            logColorRange: { sizeMin: 1, sizeMax: 1000 },
+        }
+        const live = createHeatmapController(cfg)
+        const deltas: OrderBookDelta[] = [
+            bid(0, 100, 1),
+            ask(0, 101, 1),
+            bid(50, 99.5, 2),
+            bid(120, 100, 0),
+            ask(160, 101.5, 4),
+        ]
+        for (const d of deltas) live.ingestDelta(d)
+
+        // Live midpoint reference: replay BOOK alone, no controller, up to t=80.
+        const reference = createOrderBookState({ tickSize: 0.01 })
+        for (const d of deltas) if (d.timestamp <= 80) reference.applyDelta(d)
+        const refSnap = reference.snapshot()
+
+        // Controller-produced replay snapshot at exactly t=80.
+        const series = live.replay(80, 80, 1)
+        expect(series).toHaveLength(1)
+        expect(series[0].bids).toEqual(refSnap.bids)
+        expect(series[0].asks).toEqual(refSnap.asks)
+        live.dispose()
+    })
+
+    it('dispose() silences subsequent mutator calls', () => {
+        const ctrl = createHeatmapController({
+            tickSize: 0.01,
+            snapshotIntervalMs: 100,
+            snapshotRingCapacity: 10,
+            deltaArchiveMaxSize: 1000,
+            logColorRange: { sizeMin: 1, sizeMax: 1000 },
+        })
+        ctrl.ingestDelta(bid(0, 100, 1))
+        const before = ctrl.state.peek().deltaCount
+        ctrl.dispose()
+        ctrl.ingestDelta(bid(100, 100, 2))
+        ctrl.forceSnapshot()
+        ctrl.setConfig({ snapshotIntervalMs: 50 })
+        expect(ctrl.state.peek().deltaCount).toBe(before)
+        // replay() on disposed controller returns empty.
+        expect(ctrl.replay(0, 100, 10)).toEqual([])
+        // dispose() is idempotent.
+        ctrl.dispose()
+    })
+
+    it('setConfig() rebuilds book + ring + archive cap when tick/capacity/maxSize change', () => {
+        const ctrl = createHeatmapController({
+            tickSize: 0.01,
+            snapshotIntervalMs: 100,
+            snapshotRingCapacity: 4,
+            deltaArchiveMaxSize: 1000,
+            logColorRange: { sizeMin: 1, sizeMax: 1000 },
+        })
+        // Three distinct fine prices that all fall inside a single coarse
+        // bucket once we re-quantize.
+        ctrl.ingestDelta(bid(0, 100.10, 1))
+        ctrl.ingestDelta(bid(150, 100.20, 2))
+        ctrl.ingestDelta(bid(300, 100.30, 3))
+        // Coarser tick: 0.10/0.20/0.30 → ticks 1/2/3 at 0.01, but at 1.0
+        // they all round to 100.0.
+        ctrl.setConfig({ tickSize: 1.0 })
+        ctrl.forceSnapshot()
+        const snap = ctrl.state.peek().latestSnapshot as BookSnapshot
+        const buckets = new Set(snap.bids.map((b) => b[0]))
+        expect(buckets.size).toBe(1)
+        expect(snap.bids[0][0]).toBe(100)
+        ctrl.dispose()
+    })
+
+    it('rejects invalid replay configuration', () => {
+        const ctrl = createHeatmapController()
+        expect(() => ctrl.replay(0, 100, 0)).toThrow()
+        expect(() => ctrl.replay(0, 100, -1)).toThrow()
+        // from > to returns empty (not throw).
+        expect(ctrl.replay(100, 0, 10)).toEqual([])
+        ctrl.dispose()
+    })
+
+    it('emits a state notification on every ingestDelta', () => {
+        const ctrl = createHeatmapController({
+            tickSize: 0.01,
+            snapshotIntervalMs: 1_000,
+            snapshotRingCapacity: 10,
+            deltaArchiveMaxSize: 1000,
+            logColorRange: { sizeMin: 1, sizeMax: 1000 },
+        })
+        let calls = 0
+        const off = ctrl.state.subscribe(() => calls++)
+        ctrl.ingestDelta(bid(0, 100, 1))
+        ctrl.ingestDelta(bid(1, 100, 2))
+        ctrl.ingestDelta(bid(2, 100, 3))
+        // 3 deltas → 3 notifications.
+        expect(calls).toBe(3)
+        off()
+        ctrl.dispose()
+    })
+})

package/src/components/orderBookHeatmap/__tests__/deltaArchive.test.ts

@@ -0,0 +1,88 @@
+import { describe, it, expect } from 'vitest'
+
+import { createDeltaArchive } from '../deltaArchive'
+import type { OrderBookDelta } from '../types'
+
+function delta(ts: number, price = 100, size = 1): OrderBookDelta {
+    return { side: 'bid', price, size, timestamp: ts }
+}
+
+describe('createDeltaArchive', () => {
+    it('appends + ranges across the inserted window', () => {
+        const a = createDeltaArchive()
+        for (let i = 0; i < 10; i++) a.append(delta(i))
+        const r = a.range(2, 5)
+        expect(r.map((d) => d.timestamp)).toEqual([2, 3, 4, 5])
+    })
+
+    it('range bounds are inclusive on both ends', () => {
+        const a = createDeltaArchive()
+        a.append(delta(10))
+        a.append(delta(20))
+        a.append(delta(30))
+        expect(a.range(10, 30).map((d) => d.timestamp)).toEqual([10, 20, 30])
+        expect(a.range(11, 29).map((d) => d.timestamp)).toEqual([20])
+    })
+
+    it('trim drops the oldest entries until size ≤ target', () => {
+        const a = createDeltaArchive()
+        for (let i = 0; i < 100; i++) a.append(delta(i))
+        a.trim(30)
+        expect(a.size()).toBe(30)
+        // The 30 newest should remain.
+        const all = a.range(0, 999)
+        expect(all[0].timestamp).toBe(70)
+        expect(all[all.length - 1].timestamp).toBe(99)
+    })
+
+    it('reports accurate size after append, trim, and clear', () => {
+        const a = createDeltaArchive()
+        expect(a.size()).toBe(0)
+        for (let i = 0; i < 5; i++) a.append(delta(i))
+        expect(a.size()).toBe(5)
+        a.trim(2)
+        expect(a.size()).toBe(2)
+        a.clear()
+        expect(a.size()).toBe(0)
+    })
+
+    it('chunked storage does not break range queries across chunks', () => {
+        // CHUNK_SIZE is 10_000 in the impl. Push more than that to force at
+        // least one chunk boundary and ensure ordering still holds.
+        const a = createDeltaArchive()
+        const N = 25_000
+        for (let i = 0; i < N; i++) a.append(delta(i))
+        // Window straddles two chunk boundaries.
+        const r = a.range(9_998, 10_002)
+        expect(r.map((d) => d.timestamp)).toEqual([9_998, 9_999, 10_000, 10_001, 10_002])
+        // Full range returns every delta exactly once.
+        const all = a.range(Number.NEGATIVE_INFINITY, Number.POSITIVE_INFINITY)
+        expect(all.length).toBe(N)
+        expect(all[0].timestamp).toBe(0)
+        expect(all[N - 1].timestamp).toBe(N - 1)
+    })
+
+    it('respects maxSize at construction by auto-trimming on append', () => {
+        const a = createDeltaArchive({ maxSize: 5 })
+        for (let i = 0; i < 12; i++) a.append(delta(i))
+        expect(a.size()).toBe(5)
+        const all = a.range(Number.NEGATIVE_INFINITY, Number.POSITIVE_INFINITY)
+        expect(all.map((d) => d.timestamp)).toEqual([7, 8, 9, 10, 11])
+    })
+
+    it('returns empty array when from > to', () => {
+        const a = createDeltaArchive()
+        for (let i = 0; i < 5; i++) a.append(delta(i))
+        expect(a.range(3, 1)).toEqual([])
+    })
+
+    it('clear() resets the archive without breaking subsequent appends', () => {
+        const a = createDeltaArchive()
+        for (let i = 0; i < 5; i++) a.append(delta(i))
+        a.clear()
+        expect(a.size()).toBe(0)
+        a.append(delta(99))
+        expect(a.size()).toBe(1)
+        expect(a.range(0, 1000).map((d) => d.timestamp)).toEqual([99])
+    })
+})

package/src/components/orderBookHeatmap/__tests__/logColorScale.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect } from 'vitest'
+
+import { createLogColorScale } from '../logColorScale'
+
+describe('createLogColorScale', () => {
+    it('maps size = 0 to intensity 0', () => {
+        const scale = createLogColorScale(1, 1000)
+        expect(scale.intensity(0)).toBe(0)
+        expect(scale.intensity(-5)).toBe(0)
+    })
+
+    it('maps size below sizeMin to 0', () => {
+        const scale = createLogColorScale(10, 1000)
+        expect(scale.intensity(1)).toBe(0)
+        expect(scale.intensity(10)).toBe(0)
+    })
+
+    it('maps size above sizeMax to 1', () => {
+        const scale = createLogColorScale(1, 100)
+        expect(scale.intensity(100)).toBe(1)
+        expect(scale.intensity(1_000_000)).toBe(1)
+    })
+
+    it('mid-range is monotonically increasing in log size', () => {
+        const scale = createLogColorScale(1, 10_000)
+        const a = scale.intensity(2)
+        const b = scale.intensity(20)
+        const c = scale.intensity(200)
+        const d = scale.intensity(2_000)
+        expect(a).toBeGreaterThan(0)
+        expect(a).toBeLessThan(b)
+        expect(b).toBeLessThan(c)
+        expect(c).toBeLessThan(d)
+        expect(d).toBeLessThan(1)
+    })
+
+    it('matches the exact log-ratio formula for a known interior point', () => {
+        // sizeMin = 1, sizeMax = 100 → log range = ln(100). At size = 10
+        // intensity should be ln(10) / ln(100) = 0.5.
+        const scale = createLogColorScale(1, 100)
+        expect(scale.intensity(10)).toBeCloseTo(0.5, 10)
+    })
+
+    it('degenerate range (sizeMin === sizeMax) returns 0.5 for any positive size', () => {
+        const scale = createLogColorScale(5, 5)
+        expect(scale.intensity(1)).toBe(0.5)
+        expect(scale.intensity(5)).toBe(0.5)
+        expect(scale.intensity(1_000_000)).toBe(0.5)
+        // Non-positive sizes still map to 0.
+        expect(scale.intensity(0)).toBe(0)
+    })
+
+    it('setRange swaps the range without rebuilding the scale', () => {
+        const scale = createLogColorScale(1, 100)
+        expect(scale.intensity(10)).toBeCloseTo(0.5, 10)
+        scale.setRange(1, 1_000_000)
+        // Now ln(10) / ln(1e6) = 1 / 6.
+        expect(scale.intensity(10)).toBeCloseTo(1 / 6, 6)
+        expect(scale.range()).toEqual({ sizeMin: 1, sizeMax: 1_000_000 })
+    })
+
+    it('rejects invalid ranges at construction', () => {
+        expect(() => createLogColorScale(0, 1)).toThrow()
+        expect(() => createLogColorScale(1, 0)).toThrow()
+        expect(() => createLogColorScale(-1, 1)).toThrow()
+        expect(() => createLogColorScale(10, 1)).toThrow()
+        expect(() => createLogColorScale(Infinity, 1)).toThrow()
+    })
+})

package/src/components/orderBookHeatmap/__tests__/orderBookState.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect } from 'vitest'
+
+import { createOrderBookState } from '../createOrderBookState'
+
+describe('createOrderBookState', () => {
+    it('applies a bid delta and reflects it in the next snapshot', () => {
+        const book = createOrderBookState({ tickSize: 0.01 })
+        book.applyDelta({ side: 'bid', price: 100.0, size: 5, timestamp: 1 })
+        const snap = book.snapshot()
+        expect(snap.bids).toEqual([[100.0, 5]])
+        expect(snap.asks).toEqual([])
+        expect(snap.timestamp).toBe(1)
+    })
+
+    it('treats size=0 as a removal of the level', () => {
+        const book = createOrderBookState({ tickSize: 0.01 })
+        book.applyDelta({ side: 'bid', price: 100.0, size: 5, timestamp: 1 })
+        book.applyDelta({ side: 'bid', price: 100.0, size: 0, timestamp: 2 })
+        const snap = book.snapshot()
+        expect(snap.bids).toEqual([])
+        expect(snap.timestamp).toBe(2)
+    })
+
+    it('quantizes input prices to ticks (67000.123 with tick 0.01 → 67000.12)', () => {
+        const book = createOrderBookState({ tickSize: 0.01 })
+        book.applyDelta({ side: 'ask', price: 67000.123, size: 1, timestamp: 1 })
+        const snap = book.snapshot()
+        expect(snap.asks).toHaveLength(1)
+        expect(snap.asks[0][0]).toBeCloseTo(67000.12, 6)
+        expect(snap.asks[0][1]).toBe(1)
+    })
+
+    it('returns dequantized prices (consumer never sees the tick index)', () => {
+        const book = createOrderBookState({ tickSize: 0.5 })
+        // 100.7 → tick 201 → 100.5
+        book.applyDelta({ side: 'bid', price: 100.7, size: 3, timestamp: 1 })
+        // 101.3 → tick 203 → 101.5
+        book.applyDelta({ side: 'ask', price: 101.3, size: 4, timestamp: 1 })
+        const snap = book.snapshot()
+        expect(snap.bids).toEqual([[100.5, 3]])
+        expect(snap.asks).toEqual([[101.5, 4]])
+    })
+
+    it('clear() resets both sides and the last timestamp', () => {
+        const book = createOrderBookState({ tickSize: 0.01 })
+        book.applyDelta({ side: 'bid', price: 100, size: 1, timestamp: 5 })
+        book.applyDelta({ side: 'ask', price: 101, size: 2, timestamp: 6 })
+        book.clear()
+        const snap = book.snapshot()
+        expect(snap.bids).toEqual([])
+        expect(snap.asks).toEqual([])
+        expect(snap.timestamp).toBe(0)
+        expect(book.lastTimestamp()).toBe(0)
+    })
+
+    it('last update wins for the same price (multiple updates collapse)', () => {
+        const book = createOrderBookState({ tickSize: 0.01 })
+        book.applyDelta({ side: 'bid', price: 100, size: 1, timestamp: 1 })
+        book.applyDelta({ side: 'bid', price: 100, size: 2, timestamp: 2 })
+        book.applyDelta({ side: 'bid', price: 100, size: 9, timestamp: 3 })
+        const snap = book.snapshot()
+        expect(snap.bids).toEqual([[100.0, 9]])
+        expect(snap.timestamp).toBe(3)
+    })
+
+    it('maintains bid and ask side independence', () => {
+        const book = createOrderBookState({ tickSize: 0.01 })
+        book.applyDelta({ side: 'bid', price: 100, size: 5, timestamp: 1 })
+        book.applyDelta({ side: 'ask', price: 100, size: 7, timestamp: 2 })
+        // Removing bid at 100 must not remove ask at 100.
+        book.applyDelta({ side: 'bid', price: 100, size: 0, timestamp: 3 })
+        const snap = book.snapshot()
+        expect(snap.bids).toEqual([])
+        expect(snap.asks).toEqual([[100, 7]])
+    })
+
+    it('sorts bids descending and asks ascending', () => {
+        const book = createOrderBookState({ tickSize: 0.01 })
+        book.applyDelta({ side: 'bid', price: 99.5, size: 1, timestamp: 1 })
+        book.applyDelta({ side: 'bid', price: 100.0, size: 1, timestamp: 1 })
+        book.applyDelta({ side: 'bid', price: 99.8, size: 1, timestamp: 1 })
+        book.applyDelta({ side: 'ask', price: 101.0, size: 1, timestamp: 1 })
+        book.applyDelta({ side: 'ask', price: 100.2, size: 1, timestamp: 1 })
+        book.applyDelta({ side: 'ask', price: 100.5, size: 1, timestamp: 1 })
+        const snap = book.snapshot()
+        expect(snap.bids.map((b) => b[0])).toEqual([100.0, 99.8, 99.5])
+        expect(snap.asks.map((a) => a[0])).toEqual([100.2, 100.5, 101.0])
+    })
+
+    it('respects maxLevels by truncating to top-of-book first', () => {
+        const book = createOrderBookState({ tickSize: 0.01, maxLevels: 2 })
+        book.applyDelta({ side: 'bid', price: 99.5, size: 1, timestamp: 1 })
+        book.applyDelta({ side: 'bid', price: 100.0, size: 1, timestamp: 1 })
+        book.applyDelta({ side: 'bid', price: 99.8, size: 1, timestamp: 1 })
+        const snap = book.snapshot()
+        expect(snap.bids.map((b) => b[0])).toEqual([100.0, 99.8])
+    })
+
+    it('rejects non-positive tickSize at construction', () => {
+        expect(() => createOrderBookState({ tickSize: 0 })).toThrow()
+        expect(() => createOrderBookState({ tickSize: -1 })).toThrow()
+        expect(() => createOrderBookState({ tickSize: Infinity })).toThrow()
+    })
+
+    it('ignores NaN / Infinity deltas without corrupting state', () => {
+        const book = createOrderBookState({ tickSize: 0.01 })
+        book.applyDelta({ side: 'bid', price: NaN, size: 1, timestamp: 1 })
+        book.applyDelta({ side: 'bid', price: 100, size: NaN, timestamp: 2 })
+        book.applyDelta({ side: 'bid', price: 100, size: 1, timestamp: 3 })
+        const snap = book.snapshot()
+        expect(snap.bids).toEqual([[100, 1]])
+    })
+})

package/src/components/orderBookHeatmap/__tests__/snapshotRing.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect } from 'vitest'
+
+import { createSnapshotRing } from '../snapshotRing'
+import type { BookSnapshot } from '../types'
+
+function makeSnap(ts: number): BookSnapshot {
+    return { bids: [], asks: [], timestamp: ts }
+}
+
+describe('createSnapshotRing', () => {
+    it('respects the declared capacity and reports size accurately', () => {
+        const ring = createSnapshotRing(3)
+        expect(ring.capacity).toBe(3)
+        expect(ring.size()).toBe(0)
+        ring.push(makeSnap(1))
+        ring.push(makeSnap(2))
+        expect(ring.size()).toBe(2)
+    })
+
+    it('drops the oldest entry when pushed past capacity', () => {
+        const ring = createSnapshotRing(3)
+        ring.push(makeSnap(1))
+        ring.push(makeSnap(2))
+        ring.push(makeSnap(3))
+        ring.push(makeSnap(4))
+        const out = ring.toArray()
+        expect(out.map((s) => s.timestamp)).toEqual([2, 3, 4])
+    })
+
+    it('toArray returns snapshots oldest → newest, even after wrap-around', () => {
+        const ring = createSnapshotRing(4)
+        for (let i = 1; i <= 10; i++) ring.push(makeSnap(i))
+        const out = ring.toArray()
+        expect(out.map((s) => s.timestamp)).toEqual([7, 8, 9, 10])
+    })
+
+    it('clear() empties the buffer without affecting capacity', () => {
+        const ring = createSnapshotRing(2)
+        ring.push(makeSnap(1))
+        ring.push(makeSnap(2))
+        ring.clear()
+        expect(ring.size()).toBe(0)
+        expect(ring.toArray()).toEqual([])
+        ring.push(makeSnap(3))
+        expect(ring.toArray().map((s) => s.timestamp)).toEqual([3])
+    })
+
+    it('rejects non-positive capacity', () => {
+        expect(() => createSnapshotRing(0)).toThrow()
+        expect(() => createSnapshotRing(-5)).toThrow()
+        expect(() => createSnapshotRing(1.5)).toThrow()
+    })
+})

package/src/components/orderBookHeatmap/computeShader.wgsl.md

@@ -0,0 +1,130 @@
+# Order Book Heatmap — WGSL Render Path Spec
+
+This document specifies the GPU side of the heatmap. **No `.wgsl` source ships
+with this commit** — the JS controller in this module produces the snapshot
+ring; the renderer (P1 deliverable) will translate the spec below into a real
+pipeline once the WebGPU surface lands. The spec is authoritative for that
+work.
+
+## Inputs
+
+### `snapshotRing` — storage buffer (read-only in shaders)
+
+Logically a 2-D grid `intensity[col][row]` where:
+
+- `col`  ∈ `[0, snapshotRingCapacity)` — time axis (oldest → newest)
+- `row`  ∈ `[0, priceRowCount)` — price axis (low → high)
+
+CPU-side layout (one upload per render frame for simplicity in v0):
+
+```
+struct SnapshotCell {
+  intensity: f32,   // log-mapped, already in [0, 1]
+};
+@group(0) @binding(0) var<storage, read> ring: array<SnapshotCell>;
+```
+
+Index conversion: `cellIdx = col * priceRowCount + row`.
+
+Empty levels (no resting size at that price/time) are written as `0.0`. The
+fragment shader treats `0.0` as fully transparent.
+
+### `viridisLUT` — 256-entry uniform color table
+
+```
+@group(0) @binding(1) var<uniform> viridisLUT: array<vec4<f32>, 256>;
+```
+
+`viridis` is the perceptually-uniform colormap from `d3-scale-chromatic`. Each
+entry is `vec4<f32>(r, g, b, 1.0)` with channels in `[0, 1]` and gamma already
+applied. The CPU sends it once at controller init and on theme change.
+
+### `params` — uniform block
+
+```
+struct HeatmapParams {
+  priceRowCount:        u32,
+  snapshotColumnCount:  u32,
+  // Scroll offset: when the ring buffer wraps, this is the col where the
+  // oldest sample lives. The fragment shader rotates around this.
+  ringHead:             u32,
+  // Range used by the CPU when log-mapping; replicated here so the shader
+  // can re-map should we move log mapping onto the GPU later (see §4).
+  sizeMinLog:           f32,
+  sizeMaxLog:           f32,
+  _pad:                 f32,
+};
+@group(0) @binding(2) var<uniform> params: HeatmapParams;
+```
+
+## Fragment shader
+
+```
+@fragment
+fn fs_main(@location(0) uv: vec2<f32>) -> @location(0) vec4<f32> {
+  // uv.x: 0 (left, oldest) → 1 (right, newest)
+  // uv.y: 0 (bottom, lowest price) → 1 (top, highest price)
+  let col = u32(floor(uv.x * f32(params.snapshotColumnCount)));
+  let row = u32(floor(uv.y * f32(params.priceRowCount)));
+  let rotated = (col + params.ringHead) % params.snapshotColumnCount;
+  let idx = rotated * params.priceRowCount + row;
+  let i = ring[idx].intensity;
+  if (i <= 0.0) {
+    return vec4<f32>(0.0, 0.0, 0.0, 0.0);
+  }
+  let lutIdx = u32(clamp(i * 255.0, 0.0, 255.0));
+  return viridisLUT[lutIdx];
+}
+```
+
+## Trade-off — full re-upload vs scrolling write
+
+There are two reasonable upload strategies. The CPU controller currently
+produces the data shape for **either**; the renderer picks at integration time.
+
+### Option A — full re-upload every frame
+
+Each render frame the CPU calls `snapshotRing.toArray()` and writes the whole
+buffer. Simple, no GPU-side state, fast on small rings.
+
+- Cost: `O(N · R · sizeof(SnapshotCell))` per frame
+  (N = ring capacity, R = price rows). For N = 600, R = 400, 4 B per cell
+  that's ~960 KB per frame — fine at 60 fps on any GPU we target.
+- Pros: stateless, robust to seeking/replay, code is short.
+- Cons: redundant uploads for the columns that didn't change.
+
+### Option B — scrolling buffer with single-column write
+
+Treat the storage buffer as a true ring. On each new snapshot:
+
+1. CPU writes one column at offset `ringHead * R` (only the new data).
+2. CPU bumps `params.ringHead = (ringHead + 1) % N`.
+
+- Cost: `O(R · sizeof(SnapshotCell))` per snapshot.
+- Pros: minimal bandwidth, scales to N >> 600.
+- Cons: needs careful synchronization with frame timing; the fragment shader
+  already accounts for `ringHead` rotation (see snippet above).
+
+**Recommendation**: start with A in v0 (correct + easy to validate); migrate
+to B once the renderer is on WebGPU and we want to drive much wider time
+windows.
+
+## Why CPU-side log mapping (today) and not GPU?
+
+We do the log transform on CPU inside `logColorScale` because:
+
+- The mapping is cheap (one `log` per cell, ~tens of µs per snapshot).
+- Having the intensity already in `[0, 1]` keeps the fragment shader trivial
+  and avoids passing raw size ranges through every uniform.
+
+Once we move to Option B and want to scrub a long history with dynamic range
+recalibration, we can move log mapping onto the GPU using `sizeMinLog` /
+`sizeMaxLog` from `HeatmapParams`. The shader code path is one extra `log`
+call and a divide — no change to the buffer shape is required.
+
+## Composition with depth chart / order book ladder
+
+The same `ring` storage buffer is consumed by §3.4's depth chart, which only
+needs the *current* column (`ringHead - 1 mod N`) and a different fragment
+shader that does a cumulative-sum sweep. We deliberately avoid duplicating
+state for the two visualizations.