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

package/src/renderer-tier/types.ts

@@ -0,0 +1,59 @@
+/**
+ * Renderer tier types.
+ *
+ * `RendererTier` is a totally-ordered enum (`'webgpu' > 'webgl2' >
+ * 'canvas2d' > 'none'`). Consumers pick the highest tier the host
+ * environment supports and configure the {@link Renderer} accordingly.
+ *
+ * Why a string union (not a numeric enum):
+ *   - Logs and analytics stay human-readable.
+ *   - Tree-shakable; no runtime enum object.
+ *   - Cross-package safe — string equality survives serialization
+ *     and avoids the "two enum copies don't compare" footgun.
+ */
+
+export type RendererTier = 'webgpu' | 'webgl2' | 'canvas2d' | 'none'
+
+/**
+ * Numeric rank used for `compareRendererTier`. Higher = better.
+ * Exposed so consumers can write their own "at least X" guards.
+ */
+export const RENDERER_TIER_RANK: Readonly<Record<RendererTier, number>> = {
+    webgpu: 3,
+    webgl2: 2,
+    canvas2d: 1,
+    none: 0,
+}
+
+/**
+ * Detection result. `tier` is the picked tier; `reason` is a one-line
+ * human-readable explanation (intended for diagnostics, not for
+ * branching — branch on `tier`).
+ *
+ * `tried` enumerates the tiers probed in order — useful when reporting
+ * "we wanted WebGPU but it threw" telemetry.
+ */
+export interface RendererTierResult {
+    readonly tier: RendererTier
+    readonly reason: string
+    readonly tried: ReadonlyArray<RendererTier>
+}
+
+/**
+ * Probe injection — the unit tests use this to simulate every tier
+ * combination without poking globals. Production code passes nothing
+ * and the real `globalThis` probes run.
+ *
+ * Each probe returns `true` when the tier is detected, `false` when
+ * it is conclusively unavailable. Throwing is treated as "unavailable"
+ * with the message folded into `reason`.
+ */
+export interface RendererTierProbes {
+    readonly webgpu?: () => boolean
+    readonly webgl2?: () => boolean
+    readonly canvas2d?: () => boolean
+}
+
+export interface DetectRendererTierOptions {
+    readonly probes?: RendererTierProbes
+}

package/src/replay/__tests__/controller.test.ts

@@ -0,0 +1,309 @@
+import { describe, it, expect, vi } from 'vitest'
+import { createReplayController } from '../createReplayController'
+import type { ReplayState } from '../types'
+
+// A 1-minute bar interval so wall-clock math is easy to reason about:
+//   1000ms of wall-clock at speed=1 advances 1000/60000 = 0.01666... bars.
+//   At speed=60, 1000ms advances 1 full bar.
+const ONE_MINUTE_MS = 60_000
+
+function build(initOverride: Partial<Parameters<typeof createReplayController>[0]> = {}) {
+    return createReplayController({
+        start: 0,
+        end: 99,
+        pacing: 'bar',
+        speed: 1,
+        barIntervalMs: ONE_MINUTE_MS,
+        ...initOverride,
+    })
+}
+
+describe('createReplayController', () => {
+    it('initialises position at start with mode=paused', () => {
+        const ctrl = build()
+        const s = ctrl.state.peek()
+        expect(s.position).toBe(0)
+        expect(s.start).toBe(0)
+        expect(s.end).toBe(99)
+        expect(s.mode).toBe('paused')
+        expect(s.pacing).toBe('bar')
+        expect(s.speed).toBe(1)
+        ctrl.dispose()
+    })
+
+    it('throws on construction when end < start', () => {
+        expect(() => build({ start: 10, end: 5 })).toThrow(/end.*start/i)
+    })
+
+    it('throws on construction when speed <= 0', () => {
+        expect(() => build({ speed: 0 })).toThrow(/speed/i)
+        expect(() => build({ speed: -1 })).toThrow(/speed/i)
+    })
+
+    it('seekTo within range updates state and notifies subscribers', () => {
+        const ctrl = build()
+        const fn = vi.fn()
+        const unsub = ctrl.state.subscribe(fn)
+        ctrl.seekTo(42)
+        expect(ctrl.state.peek().position).toBe(42)
+        expect(fn).toHaveBeenCalledTimes(1)
+        unsub()
+        ctrl.dispose()
+    })
+
+    it('seekTo above end clamps to end', () => {
+        const ctrl = build()
+        ctrl.seekTo(1_000_000)
+        expect(ctrl.state.peek().position).toBe(99)
+        ctrl.dispose()
+    })
+
+    it('seekTo below start clamps to start', () => {
+        const ctrl = build()
+        ctrl.seekTo(-50)
+        expect(ctrl.state.peek().position).toBe(0)
+        ctrl.dispose()
+    })
+
+    it('stepForward + stepBackward returns to the same position', () => {
+        const ctrl = build()
+        ctrl.seekTo(20)
+        ctrl.stepForward()
+        expect(ctrl.state.peek().position).toBe(21)
+        ctrl.stepBackward()
+        expect(ctrl.state.peek().position).toBe(20)
+        ctrl.dispose()
+    })
+
+    it('consecutive stepForward past end clamps to end and auto-pauses if playing', () => {
+        const ctrl = build({ end: 3 })
+        ctrl.seekTo(2)
+        ctrl.play()
+        expect(ctrl.state.peek().mode).toBe('playing')
+        ctrl.stepForward() // -> 3, hits end while playing => auto-paused
+        const s = ctrl.state.peek()
+        expect(s.position).toBe(3)
+        expect(s.mode).toBe('paused')
+        // Further forwards stay clamped.
+        ctrl.stepForward()
+        expect(ctrl.state.peek().position).toBe(3)
+        ctrl.dispose()
+    })
+
+    it('play() then pause() toggles mode and emits both transitions', () => {
+        const ctrl = build()
+        ctrl.seekTo(10)
+        const fn = vi.fn()
+        const unsub = ctrl.state.subscribe(fn)
+        ctrl.play()
+        expect(ctrl.state.peek().mode).toBe('playing')
+        ctrl.pause()
+        expect(ctrl.state.peek().mode).toBe('paused')
+        expect(fn).toHaveBeenCalledTimes(2)
+        unsub()
+        ctrl.dispose()
+    })
+
+    it('toggle() flips between paused and playing', () => {
+        const ctrl = build()
+        ctrl.seekTo(10)
+        expect(ctrl.state.peek().mode).toBe('paused')
+        ctrl.toggle()
+        expect(ctrl.state.peek().mode).toBe('playing')
+        ctrl.toggle()
+        expect(ctrl.state.peek().mode).toBe('paused')
+        ctrl.dispose()
+    })
+
+    it('play() at end stays paused (no observable mode flip)', () => {
+        const ctrl = build({ end: 5 })
+        ctrl.seekTo(5)
+        const fn = vi.fn()
+        const unsub = ctrl.state.subscribe(fn)
+        ctrl.play()
+        expect(ctrl.state.peek().mode).toBe('paused')
+        expect(fn).not.toHaveBeenCalled()
+        unsub()
+        ctrl.dispose()
+    })
+
+    it('tick() in bar mode is a no-op when playing', () => {
+        const ctrl = build({ pacing: 'bar' })
+        ctrl.play()
+        const before = ctrl.state.peek().position
+        const changed = ctrl.tick(1000)
+        expect(changed).toBe(false)
+        expect(ctrl.state.peek().position).toBe(before)
+        ctrl.dispose()
+    })
+
+    it('tick() in wallclock mode advances proportional to deltaMs * speed', () => {
+        const ctrl = build({ pacing: 'wallclock', speed: 1 })
+        ctrl.play()
+        // 1000ms at speed=1 with 60_000ms/bar → 1/60 of a bar.
+        const changed = ctrl.tick(1000)
+        expect(changed).toBe(true)
+        expect(ctrl.state.peek().position).toBeCloseTo(1 / 60, 10)
+
+        // Bump speed to 60 → 1000ms advances exactly 1 bar.
+        ctrl.setSpeed(60)
+        const before = ctrl.state.peek().position
+        ctrl.tick(1000)
+        expect(ctrl.state.peek().position).toBeCloseTo(before + 1, 10)
+        ctrl.dispose()
+    })
+
+    it('tick() in tick mode advances faster than wallclock at the same speed', () => {
+        const wallCtrl = build({ pacing: 'wallclock', speed: 1 })
+        const tickCtrl = build({ pacing: 'tick', speed: 1 })
+        wallCtrl.play()
+        tickCtrl.play()
+        wallCtrl.tick(1000)
+        tickCtrl.tick(1000)
+        const wallAdvance = wallCtrl.state.peek().position
+        const tickAdvance = tickCtrl.state.peek().position
+        expect(tickAdvance).toBeGreaterThan(wallAdvance)
+        // 1000ms / 100ms-per-bar * speed=1 = 10 bars
+        expect(tickAdvance).toBeCloseTo(10, 10)
+        wallCtrl.dispose()
+        tickCtrl.dispose()
+    })
+
+    it('reaching end via tick() auto-pauses and clamps to end', () => {
+        const ctrl = build({ pacing: 'wallclock', speed: 60, end: 5 })
+        ctrl.play()
+        // 10 bars worth of advance — far past the end (5).
+        ctrl.tick(10_000)
+        const s = ctrl.state.peek()
+        expect(s.position).toBe(5)
+        expect(s.mode).toBe('paused')
+        ctrl.dispose()
+    })
+
+    it('setPacing mid-play keeps mode=playing and switches tick math', () => {
+        const ctrl = build({ pacing: 'wallclock', speed: 1 })
+        ctrl.play()
+        ctrl.tick(1000)
+        const afterWall = ctrl.state.peek().position
+        expect(ctrl.state.peek().mode).toBe('playing')
+
+        ctrl.setPacing('bar')
+        // Still playing, but bar pacing means tick() no longer advances.
+        expect(ctrl.state.peek().mode).toBe('playing')
+        const changed = ctrl.tick(1000)
+        expect(changed).toBe(false)
+        expect(ctrl.state.peek().position).toBe(afterWall)
+        ctrl.dispose()
+    })
+
+    it('setSpeed(<=0) throws and does not mutate state', () => {
+        const ctrl = build()
+        const before = ctrl.state.peek()
+        expect(() => ctrl.setSpeed(0)).toThrow(/speed/i)
+        expect(() => ctrl.setSpeed(-2)).toThrow(/speed/i)
+        expect(ctrl.state.peek()).toBe(before) // same object reference
+        ctrl.dispose()
+    })
+
+    it('setRange clamps current position into the new range', () => {
+        const ctrl = build({ end: 100 })
+        ctrl.seekTo(80)
+        ctrl.setRange(0, 50)
+        const s = ctrl.state.peek()
+        expect(s.start).toBe(0)
+        expect(s.end).toBe(50)
+        expect(s.position).toBe(50)
+        ctrl.dispose()
+    })
+
+    it('setRange throws when end < start and leaves state untouched', () => {
+        const ctrl = build()
+        const before = ctrl.state.peek()
+        expect(() => ctrl.setRange(20, 10)).toThrow(/end.*start/i)
+        expect(ctrl.state.peek()).toBe(before)
+        ctrl.dispose()
+    })
+
+    it('tick() returns true only when position changed', () => {
+        const ctrl = build({ pacing: 'wallclock', speed: 60, end: 10 })
+        ctrl.play()
+        expect(ctrl.tick(1000)).toBe(true) // advanced ~1 bar
+        // Seek to the end manually so playback is at the right edge.
+        ctrl.seekTo(10)
+        // After clamping at end, the controller has auto-paused already, so
+        // tick() should refuse to advance (mode != 'playing').
+        expect(ctrl.tick(1000)).toBe(false)
+
+        // Negative or zero delta is ignored regardless of mode.
+        const fresh = build({ pacing: 'wallclock' })
+        fresh.play()
+        expect(fresh.tick(0)).toBe(false)
+        expect(fresh.tick(-100)).toBe(false)
+        ctrl.dispose()
+        fresh.dispose()
+    })
+
+    it('dispose silences subsequent mutators (no further emissions)', () => {
+        const ctrl = build()
+        ctrl.seekTo(10)
+        const fn = vi.fn()
+        const unsub = ctrl.state.subscribe(fn)
+        ctrl.dispose()
+        ctrl.seekTo(20)
+        ctrl.play()
+        ctrl.stepForward()
+        ctrl.setPacing('wallclock')
+        // Tick after dispose returns false and emits nothing.
+        expect(ctrl.tick(1000)).toBe(false)
+        expect(fn).not.toHaveBeenCalled()
+        // State observably unchanged from pre-dispose.
+        expect(ctrl.state.peek().position).toBe(10)
+        unsub()
+    })
+
+    it('seekBy clamps and notifies on net change', () => {
+        const ctrl = build()
+        ctrl.seekTo(50)
+        const fn = vi.fn()
+        const unsub = ctrl.state.subscribe(fn)
+        ctrl.seekBy(10)
+        expect(ctrl.state.peek().position).toBe(60)
+        ctrl.seekBy(1_000_000)
+        expect(ctrl.state.peek().position).toBe(99)
+        ctrl.seekBy(-1_000_000)
+        expect(ctrl.state.peek().position).toBe(0)
+        expect(fn).toHaveBeenCalledTimes(3)
+        unsub()
+        ctrl.dispose()
+    })
+
+    it('state is a single transactional snapshot — one notification per mutation', () => {
+        // Verifies the "single signal" design: setRange changes multiple
+        // fields but subscribers see one emission.
+        const ctrl = build()
+        ctrl.seekTo(80)
+        const captured: ReplayState[] = []
+        const unsub = ctrl.state.subscribe(() => {
+            captured.push(ctrl.state.peek())
+        })
+        ctrl.setRange(10, 50)
+        expect(captured).toHaveLength(1)
+        const snap = captured[0] as ReplayState
+        expect(snap.start).toBe(10)
+        expect(snap.end).toBe(50)
+        expect(snap.position).toBe(50) // clamped from 80
+        unsub()
+        ctrl.dispose()
+    })
+
+    it('no-op seekTo to current position does not notify', () => {
+        const ctrl = build()
+        ctrl.seekTo(25)
+        const fn = vi.fn()
+        const unsub = ctrl.state.subscribe(fn)
+        ctrl.seekTo(25)
+        expect(fn).not.toHaveBeenCalled()
+        unsub()
+        ctrl.dispose()
+    })
+})

package/src/replay/__tests__/timeline.test.ts

@@ -0,0 +1,99 @@
+import { describe, it, expect } from 'vitest'
+import {
+    barIndexToTimestamp,
+    timestampToBarIndex,
+    inferBarIntervalMs,
+    type BarCalendar,
+} from '../timeline'
+
+// 1-minute bars covering 10 bars starting at an arbitrary epoch.
+const MINUTE_MS = 60_000
+const T0 = 1_700_000_000_000
+function uniformCalendar(n: number, intervalMs = MINUTE_MS): BarCalendar {
+    const out: number[] = []
+    for (let i = 0; i < n; i++) out.push(T0 + i * intervalMs)
+    return out
+}
+
+describe('timeline', () => {
+    describe('barIndexToTimestamp + timestampToBarIndex', () => {
+        it('round-trips on a uniform calendar', () => {
+            const cal = uniformCalendar(10)
+            for (let i = 0; i < cal.length; i++) {
+                const ts = barIndexToTimestamp(cal, i)
+                expect(ts).not.toBeNull()
+                const back = timestampToBarIndex(cal, ts as number)
+                expect(back).toBe(i)
+            }
+        })
+
+        it('returns null for out-of-range bar indices', () => {
+            const cal = uniformCalendar(5)
+            expect(barIndexToTimestamp(cal, -1)).toBeNull()
+            expect(barIndexToTimestamp(cal, 5)).toBeNull()
+            expect(barIndexToTimestamp(cal, 999)).toBeNull()
+            expect(barIndexToTimestamp(cal, Number.NaN)).toBeNull()
+        })
+
+        it('returns null for empty calendars on both directions', () => {
+            const empty: BarCalendar = []
+            expect(barIndexToTimestamp(empty, 0)).toBeNull()
+            expect(timestampToBarIndex(empty, T0)).toBeNull()
+        })
+
+        it('honors non-uniform gaps (e.g. weekend close)', () => {
+            // Friday 16:00 close, then Monday 09:30 open — a ~65h gap.
+            // bars 0..3 are 1-minute Friday afternoon; bar 4 is Monday open.
+            const friday = T0
+            const cal: BarCalendar = [
+                friday + 0 * MINUTE_MS,
+                friday + 1 * MINUTE_MS,
+                friday + 2 * MINUTE_MS,
+                friday + 3 * MINUTE_MS,
+                friday + (65 * 60 + 30) * MINUTE_MS, // ~65.5h later
+            ]
+
+            // Sanity: bar 4 timestamp matches what we put in.
+            expect(barIndexToTimestamp(cal, 4)).toBe(cal[4])
+            // A timestamp inside the weekend gap resolves to the last
+            // pre-gap bar (Friday's close), not the Monday open.
+            const insideGap = (cal[3] as number) + 12 * 60 * MINUTE_MS // Saturday noon
+            expect(timestampToBarIndex(cal, insideGap)).toBe(3)
+            // A timestamp at or after the Monday open resolves to bar 4.
+            expect(timestampToBarIndex(cal, cal[4] as number)).toBe(4)
+            expect(timestampToBarIndex(cal, (cal[4] as number) + MINUTE_MS)).toBe(4)
+        })
+
+        it('clamps timestamps below the first bar to null and above the last bar to the final index', () => {
+            const cal = uniformCalendar(5)
+            expect(timestampToBarIndex(cal, (cal[0] as number) - 1)).toBeNull()
+            expect(timestampToBarIndex(cal, (cal[4] as number) + 999_999)).toBe(4)
+        })
+    })
+
+    describe('inferBarIntervalMs', () => {
+        it('returns the dominant interval on a uniform calendar', () => {
+            expect(inferBarIntervalMs(uniformCalendar(10))).toBe(MINUTE_MS)
+        })
+
+        it('uses the median so outlier gaps do not skew the estimate', () => {
+            // Mostly 1-minute, with one massive weekend gap.
+            const cal: BarCalendar = [
+                0,
+                MINUTE_MS,
+                2 * MINUTE_MS,
+                3 * MINUTE_MS,
+                // 3-day gap
+                3 * MINUTE_MS + 3 * 24 * 60 * MINUTE_MS,
+                3 * MINUTE_MS + 3 * 24 * 60 * MINUTE_MS + MINUTE_MS,
+                3 * MINUTE_MS + 3 * 24 * 60 * MINUTE_MS + 2 * MINUTE_MS,
+            ]
+            expect(inferBarIntervalMs(cal)).toBe(MINUTE_MS)
+        })
+
+        it('returns null when the calendar has fewer than two bars', () => {
+            expect(inferBarIntervalMs([])).toBeNull()
+            expect(inferBarIntervalMs([T0])).toBeNull()
+        })
+    })
+})