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

package/dist/renderer-tier/selectBackend.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Renderer backend selector — bridges the tier-detection layer
+ * ({@link detectRendererTier}) to the actual backend factory the
+ * `Renderer` interface will instantiate.
+ *
+ * Why this exists separately from {@link detectRendererTier}:
+ *
+ *   - Detection answers "what's *possible*?".
+ *   - Selection answers "what's *registered* and matches what's possible?".
+ *
+ * In practice the answers diverge. A consumer can:
+ *
+ *   (a) Choose to omit a backend they don't want to ship (e.g. drop the
+ *       WebGPU backend to save bundle size; the selector then falls
+ *       through to WebGL2 even when the host supports WebGPU).
+ *   (b) Override a backend for a specific tier (e.g. inject a Canvas2D
+ *       backend stub during tests, so the chart still renders headless).
+ *
+ * Both shapes need a *structural* fallback chain, not just "give me the
+ * factory for the detected tier". This module formalises that chain so
+ * the wiring is consistent across React, Vue, Angular, and any future
+ * adapter.
+ *
+ * Pure data: no DOM, no async, no side effects. The returned factory is
+ * just the function the caller registered.
+ */
+import { type DetectRendererTierOptions, type RendererTier, type RendererTierResult } from './types';
+/**
+ * Opaque factory shape. We don't constrain the Renderer construction here —
+ * the consumer's backend implementation knows its own signature. The
+ * selector is purely about *which* factory to hand back.
+ */
+export type BackendFactory<T = unknown> = () => T;
+/**
+ * Map of tier → registered factory. Tiers that are absent or `null` are
+ * treated as "not registered" and skipped during selection.
+ *
+ * `'none'` is intentionally absent from the type. A `'none'` tier is the
+ * absence of any rendering capability; there is nothing to register.
+ */
+export type BackendRegistry<T = unknown> = Partial<Record<Exclude<RendererTier, 'none'>, BackendFactory<T> | null>>;
+/**
+ * Selection result. `tier` is the effective tier the chosen factory
+ * targets — which is at most the detected tier. `fallbackChain`
+ * enumerates the tiers the selector traversed (high → low). When no
+ * backend is registered for any tier ≤ the detected tier, returns
+ * `tier: 'none'` and `factory: null`.
+ */
+export interface BackendSelection<T = unknown> {
+    readonly tier: RendererTier;
+    readonly factory: BackendFactory<T> | null;
+    readonly fallbackChain: ReadonlyArray<RendererTier>;
+    readonly reason: string;
+    /**
+     * The original tier-detection result. Useful for telemetry — when
+     * `tier < detection.tier` the consumer knows the host could have
+     * done better but the registry was the binding constraint.
+     */
+    readonly detection: RendererTierResult;
+}
+export interface SelectBackendOptions<T = unknown> {
+    readonly registry: BackendRegistry<T>;
+    /**
+     * Tier-detection probes pass-through for tests. Same shape as
+     * {@link DetectRendererTierOptions}.
+     */
+    readonly detect?: DetectRendererTierOptions;
+    /**
+     * Optional pre-computed detection result. When provided, the selector
+     * skips `detectRendererTier()` and uses this directly. Useful when
+     * the caller cached the detection at app startup.
+     */
+    readonly detection?: RendererTierResult;
+    /**
+     * Optional floor — refuse to select a backend below this tier even
+     * if a lower-tier factory is registered. Used by features that need
+     * GPU compute (`minimum: 'webgl2'`). When the floor can't be met,
+     * the result has `tier: 'none'` and `factory: null`.
+     */
+    readonly minimum?: RendererTier;
+}
+/**
+ * Pick the highest registered backend at or below the detected tier
+ * (and at or above the optional minimum). Pure-data.
+ *
+ *   const sel = selectBackend({
+ *     registry: { webgpu: makeGpu, webgl2: makeGl2, canvas2d: makeC2d },
+ *   })
+ *   if (sel.factory === null) throw new Error('no renderer')
+ *   const renderer = sel.factory()
+ *
+ * Telemetry pattern:
+ *
+ *   if (sel.tier !== sel.detection.tier) {
+ *     log('renderer downgrade', sel.detection.tier, '→', sel.tier, sel.reason)
+ *   }
+ */
+export declare function selectBackend<T = unknown>(opts: SelectBackendOptions<T>): BackendSelection<T>;
+/**
+ * Strict variant: throws `KLineChartError('INVALID_STATE')` if no factory
+ * could be selected. Use when a renderable backend is mandatory.
+ */
+export declare function selectBackendOrThrow<T = unknown>(opts: SelectBackendOptions<T>): BackendSelection<T> & {
+    factory: BackendFactory<T>;
+};
+//# sourceMappingURL=selectBackend.d.ts.map

package/dist/renderer-tier/selectBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectBackend.d.ts","sourceRoot":"","sources":["../../src/renderer-tier/selectBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,EAEH,KAAK,yBAAyB,EAC9B,KAAK,YAAY,EACjB,KAAK,kBAAkB,EAC1B,MAAM,SAAS,CAAA;AAOhB;;;;GAIG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,GAAG,OAAO,IAAI,MAAM,CAAC,CAAA;AAEjD;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,GAAG,OAAO,IAAI,OAAO,CAC9C,MAAM,CAAC,OAAO,CAAC,YAAY,EAAE,MAAM,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAClE,CAAA;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,OAAO;IACzC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;IAC3B,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI,CAAA;IAC1C,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC,YAAY,CAAC,CAAA;IACnD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAA;CACzC;AAED,MAAM,WAAW,oBAAoB,CAAC,CAAC,GAAG,OAAO;IAC7C,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC,CAAA;IACrC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,yBAAyB,CAAA;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,kBAAkB,CAAA;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAA;CAClC;AAYD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,CAAC,GAAG,OAAO,EACrC,IAAI,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC9B,gBAAgB,CAAC,CAAC,CAAC,CAuDrB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,GAAG,OAAO,EAC5C,IAAI,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC9B,gBAAgB,CAAC,CAAC,CAAC,GAAG;IAAE,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,CAAA;CAAE,CAStD"}

package/dist/renderer-tier/selectBackend.js

@@ -0,0 +1,113 @@
+/**
+ * Renderer backend selector — bridges the tier-detection layer
+ * ({@link detectRendererTier}) to the actual backend factory the
+ * `Renderer` interface will instantiate.
+ *
+ * Why this exists separately from {@link detectRendererTier}:
+ *
+ *   - Detection answers "what's *possible*?".
+ *   - Selection answers "what's *registered* and matches what's possible?".
+ *
+ * In practice the answers diverge. A consumer can:
+ *
+ *   (a) Choose to omit a backend they don't want to ship (e.g. drop the
+ *       WebGPU backend to save bundle size; the selector then falls
+ *       through to WebGL2 even when the host supports WebGPU).
+ *   (b) Override a backend for a specific tier (e.g. inject a Canvas2D
+ *       backend stub during tests, so the chart still renders headless).
+ *
+ * Both shapes need a *structural* fallback chain, not just "give me the
+ * factory for the detected tier". This module formalises that chain so
+ * the wiring is consistent across React, Vue, Angular, and any future
+ * adapter.
+ *
+ * Pure data: no DOM, no async, no side effects. The returned factory is
+ * just the function the caller registered.
+ */
+import { KLineChartError } from '../errors';
+import { RENDERER_TIER_RANK, } from './types';
+import { detectRendererTier, isTierAtLeast } from './detectRendererTier';
+// ---------------------------------------------------------------------------
+// Selection
+// ---------------------------------------------------------------------------
+const SEARCH_ORDER = [
+    'webgpu',
+    'webgl2',
+    'canvas2d',
+];
+/**
+ * Pick the highest registered backend at or below the detected tier
+ * (and at or above the optional minimum). Pure-data.
+ *
+ *   const sel = selectBackend({
+ *     registry: { webgpu: makeGpu, webgl2: makeGl2, canvas2d: makeC2d },
+ *   })
+ *   if (sel.factory === null) throw new Error('no renderer')
+ *   const renderer = sel.factory()
+ *
+ * Telemetry pattern:
+ *
+ *   if (sel.tier !== sel.detection.tier) {
+ *     log('renderer downgrade', sel.detection.tier, '→', sel.tier, sel.reason)
+ *   }
+ */
+export function selectBackend(opts) {
+    const detection = opts.detection ?? detectRendererTier(opts.detect);
+    const detectedTier = detection.tier;
+    const minimum = opts.minimum ?? 'none';
+    // Validate the minimum is a known tier; reject 'none' as a minimum
+    // because a 'none' floor is meaningless — nothing can be below it.
+    if (!(minimum in RENDERER_TIER_RANK)) {
+        throw new KLineChartError('INVALID_PARAM', `selectBackend: minimum must be a RendererTier, got ${JSON.stringify(minimum)}`);
+    }
+    const chain = [];
+    // Search from the detected tier downwards through SEARCH_ORDER.
+    for (const candidate of SEARCH_ORDER) {
+        // Skip tiers above the detected ceiling.
+        if (RENDERER_TIER_RANK[candidate] > RENDERER_TIER_RANK[detectedTier]) {
+            continue;
+        }
+        chain.push(candidate);
+        // Skip below the configured minimum.
+        if (!isTierAtLeast(candidate, minimum)) {
+            // No further candidate will satisfy the minimum.
+            break;
+        }
+        const factory = opts.registry[candidate] ?? null;
+        if (factory !== null) {
+            return {
+                tier: candidate,
+                factory,
+                fallbackChain: chain,
+                reason: candidate === detectedTier
+                    ? `direct match: detected ${candidate} and ${candidate} backend is registered`
+                    : `downgrade: detected ${detectedTier}, but only ${candidate} backend is registered`,
+                detection,
+            };
+        }
+    }
+    return {
+        tier: 'none',
+        factory: null,
+        fallbackChain: chain,
+        reason: detectedTier === 'none'
+            ? `host has no renderable tier`
+            : `no registered backend at or below detected ${detectedTier}` +
+                (opts.minimum !== undefined && opts.minimum !== 'none'
+                    ? ` (minimum=${opts.minimum})`
+                    : ''),
+        detection,
+    };
+}
+/**
+ * Strict variant: throws `KLineChartError('INVALID_STATE')` if no factory
+ * could be selected. Use when a renderable backend is mandatory.
+ */
+export function selectBackendOrThrow(opts) {
+    const sel = selectBackend(opts);
+    if (sel.factory === null) {
+        throw new KLineChartError('INVALID_STATE', `selectBackendOrThrow: ${sel.reason}`);
+    }
+    return sel;
+}
+//# sourceMappingURL=selectBackend.js.map

package/dist/renderer-tier/selectBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectBackend.js","sourceRoot":"","sources":["../../src/renderer-tier/selectBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAC3C,OAAO,EACH,kBAAkB,GAIrB,MAAM,SAAS,CAAA;AAChB,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAkExE,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,MAAM,YAAY,GAAiD;IAC/D,QAAQ;IACR,QAAQ;IACR,UAAU;CACb,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,aAAa,CACzB,IAA6B;IAE7B,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IACnE,MAAM,YAAY,GAAG,SAAS,CAAC,IAAI,CAAA;IACnC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,MAAM,CAAA;IAEtC,mEAAmE;IACnE,mEAAmE;IACnE,IAAI,CAAC,CAAC,OAAO,IAAI,kBAAkB,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,eAAe,CACrB,eAAe,EACf,sDAAsD,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAClF,CAAA;IACL,CAAC;IAED,MAAM,KAAK,GAAmB,EAAE,CAAA;IAChC,gEAAgE;IAChE,KAAK,MAAM,SAAS,IAAI,YAAY,EAAE,CAAC;QACnC,yCAAyC;QACzC,IAAI,kBAAkB,CAAC,SAAS,CAAC,GAAG,kBAAkB,CAAC,YAAY,CAAC,EAAE,CAAC;YACnE,SAAQ;QACZ,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;QACrB,qCAAqC;QACrC,IAAI,CAAC,aAAa,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,CAAC;YACrC,iDAAiD;YACjD,MAAK;QACT,CAAC;QACD,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,IAAI,CAAA;QAChD,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACnB,OAAO;gBACH,IAAI,EAAE,SAAS;gBACf,OAAO;gBACP,aAAa,EAAE,KAAK;gBACpB,MAAM,EACF,SAAS,KAAK,YAAY;oBACtB,CAAC,CAAC,0BAA0B,SAAS,QAAQ,SAAS,wBAAwB;oBAC9E,CAAC,CAAC,uBAAuB,YAAY,cAAc,SAAS,wBAAwB;gBAC5F,SAAS;aACZ,CAAA;QACL,CAAC;IACL,CAAC;IAED,OAAO;QACH,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,IAAI;QACb,aAAa,EAAE,KAAK;QACpB,MAAM,EACF,YAAY,KAAK,MAAM;YACnB,CAAC,CAAC,6BAA6B;YAC/B,CAAC,CAAC,8CAA8C,YAAY,EAAE;gBAC5D,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,IAAI,IAAI,CAAC,OAAO,KAAK,MAAM;oBAClD,CAAC,CAAC,aAAa,IAAI,CAAC,OAAO,GAAG;oBAC9B,CAAC,CAAC,EAAE,CAAC;QACnB,SAAS;KACZ,CAAA;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAChC,IAA6B;IAE7B,MAAM,GAAG,GAAG,aAAa,CAAC,IAAI,CAAC,CAAA;IAC/B,IAAI,GAAG,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;QACvB,MAAM,IAAI,eAAe,CACrB,eAAe,EACf,yBAAyB,GAAG,CAAC,MAAM,EAAE,CACxC,CAAA;IACL,CAAC;IACD,OAAO,GAA2D,CAAA;AACtE,CAAC"}

package/dist/renderer-tier/types.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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 declare const RENDERER_TIER_RANK: Readonly<Record<RendererTier, number>>;
+/**
+ * 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;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/renderer-tier/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/renderer-tier/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAA;AAEpE;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAKrE,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IAC/B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,YAAY,CAAC,CAAA;CAC9C;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,OAAO,CAAA;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,OAAO,CAAA;IAC/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAA;CACpC;AAED,MAAM,WAAW,yBAAyB;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,kBAAkB,CAAA;CACvC"}

package/dist/renderer-tier/types.js

@@ -0,0 +1,24 @@
+/**
+ * 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.
+ */
+/**
+ * Numeric rank used for `compareRendererTier`. Higher = better.
+ * Exposed so consumers can write their own "at least X" guards.
+ */
+export const RENDERER_TIER_RANK = {
+    webgpu: 3,
+    webgl2: 2,
+    canvas2d: 1,
+    none: 0,
+};
+//# sourceMappingURL=types.js.map

package/dist/renderer-tier/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/renderer-tier/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAA2C;IACtE,MAAM,EAAE,CAAC;IACT,MAAM,EAAE,CAAC;IACT,QAAQ,EAAE,CAAC;IACX,IAAI,EAAE,CAAC;CACV,CAAA"}

package/dist/replay/createReplayController.d.ts

@@ -0,0 +1,3 @@
+import type { ReplayController, ReplayControllerInit } from './types';
+export declare function createReplayController(init?: ReplayControllerInit): ReplayController;
+//# sourceMappingURL=createReplayController.d.ts.map

package/dist/replay/createReplayController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createReplayController.d.ts","sourceRoot":"","sources":["../../src/replay/createReplayController.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EACR,gBAAgB,EAChB,oBAAoB,EAIvB,MAAM,SAAS,CAAA;AAwDhB,wBAAgB,sBAAsB,CAClC,IAAI,CAAC,EAAE,oBAAoB,GAC5B,gBAAgB,CAoNlB"}

package/dist/replay/createReplayController.js

@@ -0,0 +1,251 @@
+import { KLineChartError } from '../errors';
+/**
+ * createReplayController — framework-agnostic Bar Replay state machine.
+ *
+ * Owns: position, mode, pacing, speed, [start, end] range.
+ * Doesn't own: the data series, the calendar, the frame loop. Those are
+ * supplied by the surrounding chart adapter.
+ *
+ * Why we expose it via a single `state` signal (rather than five separate
+ * signals): every replay mutation is a transaction over the playhead — the
+ * mode flip on auto-pause, the clamp on `setRange`, etc. Emitting a single
+ * snapshot keeps subscribers (React/Vue) from rendering intermediate states.
+ *
+ * Open design question (deferred from v1):
+ *   Should "reverse play" (speed < 0) be supported in v2?
+ *   The cleanest extension is to drop the `speed <= 0` guard, accept negative
+ *   multipliers in `tick()` math (already symmetric), and add an
+ *   `autoStartReached` clamp that mirrors `autoEndReached`. The on-disk
+ *   contract (the `ReplayState` shape) does not need to change. We defer it
+ *   because reverse playback is meaningless for live-data sessions and the
+ *   indicator runtime currently assumes monotonic time — flipping that
+ *   assumption is a larger cross-package change than this PR.
+ */
+import { createSignal } from '../reactivity/signal';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Default bar interval used by wall-clock pacing when the host did not
+ *  supply one via `init.barIntervalMs`. Picked to match the most common
+ *  intraday chart (1-minute bars). */
+const DEFAULT_BAR_INTERVAL_MS = 60_000;
+/** For `tick` pacing, this is the nominal wall-time spent on one bar at
+ *  speed=1. 100ms means a 60-bar tick replay takes 6 seconds at 1x — fast
+ *  enough to feel like "tick playback", slow enough to follow visually. */
+const TICK_PACING_MS_PER_BAR = 100;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function clamp(value, lo, hi) {
+    if (value < lo)
+        return lo;
+    if (value > hi)
+        return hi;
+    return value;
+}
+function assertValidRange(start, end) {
+    if (!Number.isFinite(start) || !Number.isFinite(end)) {
+        throw new KLineChartError('REPLAY_CONFIG_INVALID', `Replay range must be finite numbers: got start=${String(start)}, end=${String(end)}`);
+    }
+    if (end < start) {
+        throw new KLineChartError('REPLAY_CONFIG_INVALID', `Replay range end (${end}) must be >= start (${start})`);
+    }
+}
+function assertValidSpeed(speed) {
+    if (!Number.isFinite(speed) || speed <= 0) {
+        // Reverse playback (negative speed) is deliberately rejected in v1.
+        // See the header comment for the extension path.
+        throw new KLineChartError('REPLAY_CONFIG_INVALID', `Replay speed must be a positive finite number; got ${String(speed)}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+export function createReplayController(init) {
+    // -------------------------------------------------------------------
+    // Initial state — validate eagerly so misconfiguration surfaces at
+    // construction rather than on first tick.
+    // -------------------------------------------------------------------
+    const start = init?.start ?? 0;
+    const end = init?.end ?? 0;
+    assertValidRange(start, end);
+    const pacing = init?.pacing ?? 'bar';
+    const speed = init?.speed ?? 1;
+    assertValidSpeed(speed);
+    let barIntervalMs = init?.barIntervalMs ?? DEFAULT_BAR_INTERVAL_MS;
+    if (!Number.isFinite(barIntervalMs) || barIntervalMs <= 0) {
+        throw new KLineChartError('REPLAY_CONFIG_INVALID', `barIntervalMs must be a positive finite number; got ${String(barIntervalMs)}`);
+    }
+    const state = createSignal({
+        position: start,
+        start,
+        end,
+        mode: 'paused',
+        pacing,
+        speed,
+    });
+    // -------------------------------------------------------------------
+    // Internal commit helper. All mutations funnel through here so the
+    // immutability invariant and auto-pause check live in one place.
+    // -------------------------------------------------------------------
+    function commit(patch) {
+        const prev = state.peek();
+        const next = { ...prev, ...patch };
+        // Re-clamp position whenever it or the range changed.
+        if (patch.position !== undefined ||
+            patch.start !== undefined ||
+            patch.end !== undefined) {
+            next.position = clamp(next.position, next.start, next.end);
+        }
+        // Auto-pause when the playhead arrives at the right edge while
+        // playing. This is the natural end-of-tape transition; without it,
+        // the frame loop would happily tick forever against a clamped
+        // value and waste battery.
+        if (next.mode === 'playing' && next.position >= next.end) {
+            next.position = next.end;
+            next.mode = 'paused';
+        }
+        // Object.is short-circuits identical structural snapshots so a
+        // no-op commit (e.g. seekTo(currentPosition)) doesn't notify.
+        if (prev.position === next.position &&
+            prev.start === next.start &&
+            prev.end === next.end &&
+            prev.mode === next.mode &&
+            prev.pacing === next.pacing &&
+            prev.speed === next.speed) {
+            return;
+        }
+        state.set(next);
+    }
+    // -------------------------------------------------------------------
+    // Public mutators
+    // -------------------------------------------------------------------
+    function setRange(nextStart, nextEnd) {
+        assertValidRange(nextStart, nextEnd);
+        commit({ start: nextStart, end: nextEnd });
+    }
+    function seekTo(position) {
+        if (!Number.isFinite(position))
+            return;
+        commit({ position });
+    }
+    function seekBy(delta) {
+        if (!Number.isFinite(delta))
+            return;
+        const cur = state.peek().position;
+        commit({ position: cur + delta });
+    }
+    function stepForward() {
+        seekBy(1);
+    }
+    function stepBackward() {
+        seekBy(-1);
+    }
+    function play() {
+        const cur = state.peek();
+        // If we're already at the end, calling play() should not flip to
+        // 'playing' only to immediately auto-pause — that would be a
+        // confusing observable transition for subscribers. Stay paused.
+        if (cur.position >= cur.end)
+            return;
+        commit({ mode: 'playing' });
+    }
+    function pause() {
+        commit({ mode: 'paused' });
+    }
+    function toggle() {
+        const cur = state.peek();
+        if (cur.mode === 'playing') {
+            pause();
+        }
+        else {
+            play();
+        }
+    }
+    function setPacing(p) {
+        commit({ pacing: p });
+    }
+    function setSpeed(s) {
+        assertValidSpeed(s);
+        commit({ speed: s });
+    }
+    // -------------------------------------------------------------------
+    // Frame-loop driver
+    //
+    // `tick()` is deliberately stateless w.r.t. internal clock
+    // accumulation: each call applies the full advance derived from
+    // `deltaMs` directly to `position`. We DO carry fractional position
+    // values forward through the signal itself, so sub-bar progress is
+    // visible to subscribers (useful for smooth scrubbing animations and
+    // for sub-bar interpolation in the renderer).
+    //
+    // Rationale: a stateful internal accumulator would hide state from
+    // the signal, defeating the "fully observable" property that
+    // distinguishes us from TradingView. Anyone driving the controller
+    // can save/restore the entire replay session by snapshotting the
+    // state signal — no hidden bookkeeping.
+    // -------------------------------------------------------------------
+    function tick(deltaMs) {
+        if (!Number.isFinite(deltaMs) || deltaMs <= 0)
+            return false;
+        const cur = state.peek();
+        if (cur.mode !== 'playing')
+            return false;
+        let advance = 0;
+        switch (cur.pacing) {
+            case 'bar':
+                // Bar pacing is keyboard-driven: tick() never auto-advances.
+                return false;
+            case 'wallclock':
+                advance = (deltaMs / barIntervalMs) * cur.speed;
+                break;
+            case 'tick':
+                advance = (deltaMs / TICK_PACING_MS_PER_BAR) * cur.speed;
+                break;
+        }
+        if (advance === 0)
+            return false;
+        const prevPosition = cur.position;
+        commit({ position: cur.position + advance });
+        // commit() may have clamped or auto-paused; the only way position
+        // genuinely did not change is if we were already at end and the
+        // clamp swallowed the advance.
+        return state.peek().position !== prevPosition;
+    }
+    // -------------------------------------------------------------------
+    // Disposal — same guard pattern as createIndicatorSelectorController.
+    // -------------------------------------------------------------------
+    let disposed = false;
+    function dispose() {
+        if (disposed)
+            return;
+        disposed = true;
+    }
+    function guard(fn) {
+        return (...args) => {
+            if (disposed)
+                return undefined;
+            return fn(...args);
+        };
+    }
+    return {
+        state,
+        setRange: guard(setRange),
+        seekTo: guard(seekTo),
+        seekBy: guard(seekBy),
+        stepForward: guard(stepForward),
+        stepBackward: guard(stepBackward),
+        play: guard(play),
+        pause: guard(pause),
+        toggle: guard(toggle),
+        setPacing: guard(setPacing),
+        setSpeed: guard(setSpeed),
+        tick: ((deltaMs) => {
+            if (disposed)
+                return false;
+            return tick(deltaMs);
+        }),
+        dispose,
+    };
+}
+//# sourceMappingURL=createReplayController.js.map

package/dist/replay/createReplayController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createReplayController.js","sourceRoot":"","sources":["../../src/replay/createReplayController.ts"],"names":[],"mappings":"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"}

package/dist/replay/index.d.ts

@@ -0,0 +1,5 @@
+export type { ReplayMode, ReplayPacing, ReplayState, ReplayController, ReplayControllerInit, CreateReplayController, } from './types';
+export { createReplayController } from './createReplayController';
+export { barIndexToTimestamp, timestampToBarIndex, inferBarIntervalMs, } from './timeline';
+export type { BarCalendar } from './timeline';
+//# sourceMappingURL=index.d.ts.map

package/dist/replay/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/replay/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACR,UAAU,EACV,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,oBAAoB,EACpB,sBAAsB,GACzB,MAAM,SAAS,CAAA;AAChB,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAA;AACjE,OAAO,EACH,mBAAmB,EACnB,mBAAmB,EACnB,kBAAkB,GACrB,MAAM,YAAY,CAAA;AACnB,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA"}

package/dist/replay/index.js

@@ -0,0 +1,3 @@
+export { createReplayController } from './createReplayController';
+export { barIndexToTimestamp, timestampToBarIndex, inferBarIntervalMs, } from './timeline';
+//# sourceMappingURL=index.js.map

package/dist/replay/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/replay/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAA;AACjE,OAAO,EACH,mBAAmB,EACnB,mBAAmB,EACnB,kBAAkB,GACrB,MAAM,YAAY,CAAA"}

package/dist/replay/timeline.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Timeline — bar-index ↔ timestamp navigation.
+ *
+ * A `BarCalendar` is the authoritative list of bar open-times in
+ * milliseconds. Real markets aren't uniformly spaced: there are weekend
+ * gaps, half-day holiday closes, exchange maintenance windows, etc. The
+ * timeline functions must honor those gaps exactly — bar N and bar N+1 can
+ * be 60 seconds apart on a Tuesday and three days apart Friday→Monday.
+ *
+ * Both functions are pure and total: out-of-range inputs return `null`
+ * instead of throwing. Callers (e.g. the replay controller, the crosshair
+ * tooltip) should treat `null` as "no data at that position".
+ */
+/** A monotonically-increasing list of bar open timestamps (ms since epoch).
+ *  By convention `calendar[i]` is the open time of bar `i`. */
+export type BarCalendar = ReadonlyArray<number>;
+/**
+ * Look up the timestamp for an integer bar index.
+ *
+ * Fractional `barIndex` is floored — the timestamp returned is the
+ * open-time of the containing bar. (Callers that want intra-bar
+ * interpolation should do it themselves.)
+ *
+ * Returns `null` if the calendar is empty or the index is out of range.
+ */
+export declare function barIndexToTimestamp(calendar: BarCalendar, barIndex: number): number | null;
+/**
+ * Look up the bar index that contains a given timestamp.
+ *
+ * Uses binary search; cost is O(log n). The returned index is the bar
+ * whose open-time is the largest value `<= ts`. This means a timestamp
+ * that falls inside a non-trading gap (e.g. Saturday) resolves to the
+ * last bar before the gap (Friday's close), which is the intuitive
+ * behavior for "scrub to this wall-clock time".
+ *
+ * Returns `null` if the calendar is empty or `ts` precedes the first bar.
+ */
+export declare function timestampToBarIndex(calendar: BarCalendar, ts: number): number | null;
+/**
+ * Compute the dominant bar interval (in ms) from a calendar.
+ *
+ * Uses the median delta between successive bars, which is robust to
+ * weekend and holiday gaps that would skew a simple mean. Returns
+ * `null` if the calendar has fewer than two bars.
+ *
+ * The replay controller uses this when `barIntervalMs` is not configured
+ * but a calendar is available, so wall-clock pacing self-calibrates.
+ */
+export declare function inferBarIntervalMs(calendar: BarCalendar): number | null;
+//# sourceMappingURL=timeline.d.ts.map

package/dist/replay/timeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline.d.ts","sourceRoot":"","sources":["../../src/replay/timeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;+DAC+D;AAC/D,MAAM,MAAM,WAAW,GAAG,aAAa,CAAC,MAAM,CAAC,CAAA;AAE/C;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAC/B,QAAQ,EAAE,WAAW,EACrB,QAAQ,EAAE,MAAM,GACjB,MAAM,GAAG,IAAI,CAOf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAC/B,QAAQ,EAAE,WAAW,EACrB,EAAE,EAAE,MAAM,GACX,MAAM,GAAG,IAAI,CAsBf;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI,CAkBvE"}