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

package/dist/replay/timeline.js

@@ -0,0 +1,104 @@
+/**
+ * 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".
+ */
+/**
+ * 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 function barIndexToTimestamp(calendar, barIndex) {
+    if (calendar.length === 0)
+        return null;
+    if (!Number.isFinite(barIndex))
+        return null;
+    const idx = Math.floor(barIndex);
+    if (idx < 0 || idx >= calendar.length)
+        return null;
+    // We've bounds-checked the index, so this access is safe.
+    return calendar[idx];
+}
+/**
+ * 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 function timestampToBarIndex(calendar, ts) {
+    if (calendar.length === 0)
+        return null;
+    if (!Number.isFinite(ts))
+        return null;
+    const first = calendar[0];
+    if (ts < first)
+        return null;
+    const last = calendar[calendar.length - 1];
+    if (ts >= last)
+        return calendar.length - 1;
+    // Binary search for the largest index `i` such that calendar[i] <= ts.
+    let lo = 0;
+    let hi = calendar.length - 1;
+    while (lo < hi) {
+        // Bias the midpoint up so `lo` converges to the upper bound.
+        const mid = (lo + hi + 1) >>> 1;
+        const v = calendar[mid];
+        if (v <= ts) {
+            lo = mid;
+        }
+        else {
+            hi = mid - 1;
+        }
+    }
+    return lo;
+}
+/**
+ * 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 function inferBarIntervalMs(calendar) {
+    if (calendar.length < 2)
+        return null;
+    const deltas = [];
+    for (let i = 1; i < calendar.length; i++) {
+        const a = calendar[i - 1];
+        const b = calendar[i];
+        const d = b - a;
+        if (d > 0)
+            deltas.push(d);
+    }
+    if (deltas.length === 0)
+        return null;
+    deltas.sort((a, b) => a - b);
+    const mid = deltas.length >>> 1;
+    if (deltas.length % 2 === 1) {
+        return deltas[mid];
+    }
+    const lo = deltas[mid - 1];
+    const hi = deltas[mid];
+    return (lo + hi) / 2;
+}
+//# sourceMappingURL=timeline.js.map

package/dist/replay/timeline.js.map

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

package/dist/replay/types.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Bar Replay — public types.
+ *
+ * The replay subsystem models a playhead that scrubs through a finite bar
+ * series. Three pacing strategies are supported:
+ *
+ *   - `bar`       step-by-bar; `tick()` is a no-op, callers drive position
+ *                 via `stepForward` / `stepBackward` (keyboard-driven).
+ *   - `wallclock` real-time playback; `tick(deltaMs)` advances by
+ *                 `(deltaMs / msPerBar) * speed` bars. `speed` is a
+ *                 multiplier (1 = realtime, 10 = 10x).
+ *   - `tick`      synthetic tick replay; `tick(deltaMs)` advances by
+ *                 `(deltaMs / 100) * speed` bars (100ms per nominal step).
+ *
+ * Why this matters: TradingView's Bar Replay is wall-clock only and hides its
+ * state. Ours is observable via the `state` signal — any backtest engine,
+ * recording session, or sibling controller can subscribe and react to
+ * playhead changes deterministically.
+ */
+import type { Signal } from '../reactivity/signal';
+export type ReplayMode = 'paused' | 'playing';
+export type ReplayPacing = 'bar' | 'wallclock' | 'tick';
+export interface ReplayState {
+    /** Position in the full data series; fractional values are allowed and
+     *  represent sub-bar progress for wall-clock / tick pacing. Callers that
+     *  need an integer bar index should `Math.floor(position)`. */
+    position: number;
+    /** Inclusive lower bound of the playhead (clamp floor). */
+    start: number;
+    /** Inclusive upper bound of the playhead (clamp ceiling). Typically
+     *  `totalBars - 1`. */
+    end: number;
+    mode: ReplayMode;
+    pacing: ReplayPacing;
+    /** Pacing-dependent rate:
+     *  - `wallclock`: multiplier (1.0 = realtime).
+     *  - `bar`:       reserved; ignored by `tick()`.
+     *  - `tick`:      multiplier (1.0 = 1 bar per 100ms). */
+    speed: number;
+}
+export interface ReplayControllerInit {
+    start?: number;
+    end?: number;
+    pacing?: ReplayPacing;
+    speed?: number;
+    /** Bar interval in milliseconds. Used by wall-clock pacing to compute
+     *  how many bars one wall-second represents. Defaults to 60_000 (1m). */
+    barIntervalMs?: number;
+}
+export interface ReplayController {
+    /** Reactive view of the entire replay state. Subscribers fire after any
+     *  mutation that changes the state object (Object.is equality). */
+    readonly state: Signal<ReplayState>;
+    /** Set the inclusive `[start, end]` range. The current position is
+     *  re-clamped into the new range. Throws if `end < start`. */
+    setRange(start: number, end: number): void;
+    /** Seek the playhead to an absolute position; clamped to `[start, end]`. */
+    seekTo(position: number): void;
+    /** Seek by a relative delta; clamped to `[start, end]`. */
+    seekBy(delta: number): void;
+    /** Advance exactly one bar (`position += 1`), clamped to `end`. If the
+     *  step lands on `end`, mode transitions to `paused`. */
+    stepForward(): void;
+    /** Retreat exactly one bar (`position -= 1`), clamped to `start`. */
+    stepBackward(): void;
+    /** Begin playback from the current position using the configured
+     *  pacing/speed. If already at `end`, this is a no-op. */
+    play(): void;
+    pause(): void;
+    /** Toggle between `playing` and `paused`. */
+    toggle(): void;
+    setPacing(p: ReplayPacing): void;
+    /** Set the speed multiplier. Throws on `speed <= 0` (reverse play not
+     *  supported in v1 — see Open Question in the controller header). */
+    setSpeed(s: number): void;
+    /** Frame-loop hook. The chart's render loop calls this with the elapsed
+     *  wall-clock time since the last frame; the controller decides whether
+     *  to advance `position` based on `mode`, `pacing`, and `speed`.
+     *
+     *  Returns `true` if `position` (and therefore `state`) changed, so the
+     *  caller can request a re-render. Returns `false` for no-op frames
+     *  (paused, bar-pacing, or sub-bar accumulation that didn't cross a
+     *  whole-bar boundary — though in this v1 we keep `tick()` stateless and
+     *  always commit the fractional advance, so any non-zero advance returns
+     *  `true`). */
+    tick(deltaMs: number): boolean;
+    /** Tear down. After `dispose()`, all mutators become silent no-ops and
+     *  the `state` signal stops emitting. */
+    dispose(): void;
+}
+/** Factory shape — matches the exported function. Re-stated here so callers
+ *  importing only the types file can type-check controller construction. */
+export type CreateReplayController = (init?: ReplayControllerInit) => ReplayController;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/replay/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAA;AAElD,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAA;AAC7C,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,WAAW,GAAG,MAAM,CAAA;AAEvD,MAAM,WAAW,WAAW;IACxB;;mEAE+D;IAC/D,QAAQ,EAAE,MAAM,CAAA;IAChB,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAA;IACb;2BACuB;IACvB,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,UAAU,CAAA;IAChB,MAAM,EAAE,YAAY,CAAA;IACpB;;;6DAGyD;IACzD,KAAK,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,oBAAoB;IACjC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,YAAY,CAAA;IACrB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;6EACyE;IACzE,aAAa,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC7B;uEACmE;IACnE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,WAAW,CAAC,CAAA;IAEnC;kEAC8D;IAC9D,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAE1C,4EAA4E;IAC5E,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,2DAA2D;IAC3D,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B;6DACyD;IACzD,WAAW,IAAI,IAAI,CAAA;IACnB,qEAAqE;IACrE,YAAY,IAAI,IAAI,CAAA;IAEpB;8DAC0D;IAC1D,IAAI,IAAI,IAAI,CAAA;IACZ,KAAK,IAAI,IAAI,CAAA;IACb,6CAA6C;IAC7C,MAAM,IAAI,IAAI,CAAA;IAEd,SAAS,CAAC,CAAC,EAAE,YAAY,GAAG,IAAI,CAAA;IAChC;yEACqE;IACrE,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAEzB;;;;;;;;;mBASe;IACf,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAA;IAE9B;6CACyC;IACzC,OAAO,IAAI,IAAI,CAAA;CAClB;AAED;4EAC4E;AAC5E,MAAM,MAAM,sBAAsB,GAAG,CACjC,IAAI,CAAC,EAAE,oBAAoB,KAC1B,gBAAgB,CAAA"}

package/dist/replay/types.js

@@ -0,0 +1,21 @@
+/**
+ * Bar Replay — public types.
+ *
+ * The replay subsystem models a playhead that scrubs through a finite bar
+ * series. Three pacing strategies are supported:
+ *
+ *   - `bar`       step-by-bar; `tick()` is a no-op, callers drive position
+ *                 via `stepForward` / `stepBackward` (keyboard-driven).
+ *   - `wallclock` real-time playback; `tick(deltaMs)` advances by
+ *                 `(deltaMs / msPerBar) * speed` bars. `speed` is a
+ *                 multiplier (1 = realtime, 10 = 10x).
+ *   - `tick`      synthetic tick replay; `tick(deltaMs)` advances by
+ *                 `(deltaMs / 100) * speed` bars (100ms per nominal step).
+ *
+ * Why this matters: TradingView's Bar Replay is wall-clock only and hides its
+ * state. Ours is observable via the `state` signal — any backtest engine,
+ * recording session, or sibling controller can subscribe and react to
+ * playhead changes deterministically.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/replay/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/replay/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG"}

package/dist/scale/anchoredZoom.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Anchored zoom — ROADMAP §1.3.
+ *
+ * Why this exists in its own file: the "data point under the mouse stays under
+ * the mouse" guarantee is the single most-felt detail of chart UX. Getting it
+ * mathematically right (so the screen-pixel offset survives sequential zooms
+ * within sub-pixel error) is the only path to a feel that matches TradingView.
+ *
+ * Forward equation, before zoom:
+ *
+ *     mouseX = (i_anchor - firstVisibleIndex) * barWidth + leftPadding
+ *
+ * Solve for `i_anchor` first (this is the bar index the user is pointing at):
+ *
+ *     i_anchor = (mouseX - leftPadding) / barWidth + firstVisibleIndex
+ *
+ * Then pick the new bar width and solve the same equation for the new first
+ * visible index so that `mouseX` still maps to `i_anchor`:
+ *
+ *     barWidth'         = clamp(barWidth * zoomFactor, minBarWidth, maxBarWidth)
+ *     firstVisibleIndex' = i_anchor - (mouseX - leftPadding) / barWidth'
+ *
+ * Two non-obvious cases worth flagging:
+ *
+ *  1. **zoomFactor === 1** is a true no-op; we short-circuit so floating-point
+ *     round-trips don't sneak a sub-ULP drift into the state on every mouse-move.
+ *
+ *  2. **barWidth' got clamped** (user keeps wheeling at the min/max). Once the
+ *     clamp engages we re-derive `firstVisibleIndex` from the clamped width.
+ *     The anchor is preserved at the clamped width, which means the visible
+ *     anchor point will *drift in screen X by the same amount the wheel tried
+ *     to push the bar width past the clamp*. This is the expected behavior —
+ *     it's how the user feels "the chart can't zoom any further" rather than
+ *     watching the wheel become a silent dead-zone.
+ */
+export interface AnchoredZoomOptions {
+    /** Screen X (logical px) where the wheel event fired. */
+    mouseX: number;
+    /** Logical px on the left edge before bar 0. */
+    leftPadding: number;
+    /** Current `firstVisibleIndex` (fractional). */
+    firstVisibleIndex: number;
+    /** Current `barWidth` in logical px. */
+    barWidth: number;
+    /** > 1 zoom in (wheel up), < 1 zoom out, === 1 no-op. */
+    zoomFactor: number;
+    /** Lower clamp for the resulting bar width. Default 0.5 logical px. */
+    minBarWidth?: number;
+    /** Upper clamp for the resulting bar width. Default 200 logical px. */
+    maxBarWidth?: number;
+}
+export interface AnchoredZoomResult {
+    firstVisibleIndex: number;
+    barWidth: number;
+}
+/**
+ * @internal — building block used by `createTimeScale / interaction handlers`. Reachable today
+ *   via the top-level `@klinechart-quant/core` barrel but **NOT
+ *   part of the supported public API**. typedoc / api-extractor
+ *   hide it from generated docs. Prefer the controller factory
+ *   for stable user code. Closes API audit BLOCKER-002.
+ */
+export declare function computeAnchoredZoom(opts: AnchoredZoomOptions): AnchoredZoomResult;
+//# sourceMappingURL=anchoredZoom.d.ts.map

package/dist/scale/anchoredZoom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchoredZoom.d.ts","sourceRoot":"","sources":["../../src/scale/anchoredZoom.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,MAAM,WAAW,mBAAmB;IAChC,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAA;IACd,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAA;IACnB,gDAAgD;IAChD,iBAAiB,EAAE,MAAM,CAAA;IACzB,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAA;IAChB,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAA;IAClB,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,kBAAkB;IAC/B,iBAAiB,EAAE,MAAM,CAAA;IACzB,QAAQ,EAAE,MAAM,CAAA;CACnB;AAKD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,mBAAmB,GAAG,kBAAkB,CAmCjF"}

package/dist/scale/anchoredZoom.js

@@ -0,0 +1,67 @@
+/**
+ * Anchored zoom — ROADMAP §1.3.
+ *
+ * Why this exists in its own file: the "data point under the mouse stays under
+ * the mouse" guarantee is the single most-felt detail of chart UX. Getting it
+ * mathematically right (so the screen-pixel offset survives sequential zooms
+ * within sub-pixel error) is the only path to a feel that matches TradingView.
+ *
+ * Forward equation, before zoom:
+ *
+ *     mouseX = (i_anchor - firstVisibleIndex) * barWidth + leftPadding
+ *
+ * Solve for `i_anchor` first (this is the bar index the user is pointing at):
+ *
+ *     i_anchor = (mouseX - leftPadding) / barWidth + firstVisibleIndex
+ *
+ * Then pick the new bar width and solve the same equation for the new first
+ * visible index so that `mouseX` still maps to `i_anchor`:
+ *
+ *     barWidth'         = clamp(barWidth * zoomFactor, minBarWidth, maxBarWidth)
+ *     firstVisibleIndex' = i_anchor - (mouseX - leftPadding) / barWidth'
+ *
+ * Two non-obvious cases worth flagging:
+ *
+ *  1. **zoomFactor === 1** is a true no-op; we short-circuit so floating-point
+ *     round-trips don't sneak a sub-ULP drift into the state on every mouse-move.
+ *
+ *  2. **barWidth' got clamped** (user keeps wheeling at the min/max). Once the
+ *     clamp engages we re-derive `firstVisibleIndex` from the clamped width.
+ *     The anchor is preserved at the clamped width, which means the visible
+ *     anchor point will *drift in screen X by the same amount the wheel tried
+ *     to push the bar width past the clamp*. This is the expected behavior —
+ *     it's how the user feels "the chart can't zoom any further" rather than
+ *     watching the wheel become a silent dead-zone.
+ */
+const DEFAULT_MIN_BAR_WIDTH = 0.5;
+const DEFAULT_MAX_BAR_WIDTH = 200;
+/**
+ * @internal — building block used by `createTimeScale / interaction handlers`. Reachable today
+ *   via the top-level `@klinechart-quant/core` barrel but **NOT
+ *   part of the supported public API**. typedoc / api-extractor
+ *   hide it from generated docs. Prefer the controller factory
+ *   for stable user code. Closes API audit BLOCKER-002.
+ */
+export function computeAnchoredZoom(opts) {
+    const { mouseX, leftPadding, firstVisibleIndex, barWidth, zoomFactor, minBarWidth = DEFAULT_MIN_BAR_WIDTH, maxBarWidth = DEFAULT_MAX_BAR_WIDTH, } = opts;
+    // No-op short-circuit — avoid round-trip rounding when not zooming.
+    if (zoomFactor === 1) {
+        return { firstVisibleIndex, barWidth };
+    }
+    // Defensive: a non-positive or non-finite current barWidth would blow up the
+    // inverse formula. The TimeScale itself never lets barWidth reach 0, but we
+    // belt-and-brace it here so the function is total.
+    if (!Number.isFinite(barWidth) || barWidth <= 0) {
+        return { firstVisibleIndex, barWidth };
+    }
+    const dx = mouseX - leftPadding;
+    const iAnchor = dx / barWidth + firstVisibleIndex;
+    const rawNewBarWidth = barWidth * zoomFactor;
+    const newBarWidth = Math.min(Math.max(rawNewBarWidth, minBarWidth), maxBarWidth);
+    const newFirstVisibleIndex = iAnchor - dx / newBarWidth;
+    return {
+        firstVisibleIndex: newFirstVisibleIndex,
+        barWidth: newBarWidth,
+    };
+}
+//# sourceMappingURL=anchoredZoom.js.map

package/dist/scale/anchoredZoom.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchoredZoom.js","sourceRoot":"","sources":["../../src/scale/anchoredZoom.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAwBH,MAAM,qBAAqB,GAAG,GAAG,CAAA;AACjC,MAAM,qBAAqB,GAAG,GAAG,CAAA;AAEjC;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAyB;IACzD,MAAM,EACF,MAAM,EACN,WAAW,EACX,iBAAiB,EACjB,QAAQ,EACR,UAAU,EACV,WAAW,GAAG,qBAAqB,EACnC,WAAW,GAAG,qBAAqB,GACtC,GAAG,IAAI,CAAA;IAER,oEAAoE;IACpE,IAAI,UAAU,KAAK,CAAC,EAAE,CAAC;QACnB,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,CAAA;IAC1C,CAAC;IAED,6EAA6E;IAC7E,4EAA4E;IAC5E,mDAAmD;IACnD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;QAC9C,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,CAAA;IAC1C,CAAC;IAED,MAAM,EAAE,GAAG,MAAM,GAAG,WAAW,CAAA;IAC/B,MAAM,OAAO,GAAG,EAAE,GAAG,QAAQ,GAAG,iBAAiB,CAAA;IAEjD,MAAM,cAAc,GAAG,QAAQ,GAAG,UAAU,CAAA;IAC5C,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,cAAc,EAAE,WAAW,CAAC,EAAE,WAAW,CAAC,CAAA;IAEhF,MAAM,oBAAoB,GAAG,OAAO,GAAG,EAAE,GAAG,WAAW,CAAA;IAEvD,OAAO;QACH,iBAAiB,EAAE,oBAAoB;QACvC,QAAQ,EAAE,WAAW;KACxB,CAAA;AACL,CAAC"}

package/dist/scale/createPriceScale.d.ts

@@ -0,0 +1,49 @@
+/**
+ * PriceScale factory — price ↔ screen Y (ROADMAP §1.2) + origin-shift policy
+ * (ROADMAP §2.5).
+ *
+ * Linear mapping (top-origin, Y grows downward):
+ *
+ *     t        = (p        - visibleMin)        / (visibleMax - visibleMin)
+ *     y        = height - t * height
+ *     inverse: p = visibleMin + (1 - y / height) * (visibleMax - visibleMin)
+ *
+ * Log mapping (only valid for strictly positive ranges):
+ *
+ *     t        = (ln(p)    - ln(visibleMin))    / (ln(visibleMax) - ln(visibleMin))
+ *     y        = height - t * height
+ *     inverse: p = exp(ln(visibleMin) + (1 - y / height) * (ln(visibleMax) - ln(visibleMin)))
+ *
+ * Origin-shift policy: lives inside this scale and is consulted on every
+ * `setVisibleRange`. It is intentionally in **linear-price space**, applied
+ * *before* the log transform — that matches the existing engine and keeps the
+ * "shift is just a translation" mental model clean. (Log-space shift is also
+ * mathematically valid; it would compose better with sub-cent log-axis zoom on
+ * astronomically high prices, but we have no such use case and this keeps
+ * parity with the legacy renderer.)
+ *
+ * Degenerate range handling: when `visibleMin === visibleMax`, `priceToY` and
+ * `yToPrice` would divide by zero. We pin the output to `height / 2` (the
+ * geometric center) and document that the caller should treat this as
+ * "everything at the same price"; this is preferred over throwing because
+ * mid-frame `setVisibleRange(p, p)` is reachable from external data feeds and
+ * we don't want one bad row to crash the chart.
+ */
+import type { PriceScale, ScaleMode } from './types';
+export interface PriceScaleConfig {
+    /** Initial mode. Default `'linear'`. */
+    initialMode?: ScaleMode;
+    /** Initial visibleMin. Default 0. (Must be > 0 if initialMode === 'log'.) */
+    initialVisibleMin?: number;
+    /** Initial visibleMax. Default 100. */
+    initialVisibleMax?: number;
+    /** Initial canvas height in logical px. Default 480. */
+    initialHeight?: number;
+    /**
+     * Threshold for the origin-shift rebaseline policy. Default 0.01 (1% of
+     * visible range). See `originShift.ts` for the rationale.
+     */
+    originShiftThreshold?: number;
+}
+export declare function createPriceScale(config?: PriceScaleConfig): PriceScale;
+//# sourceMappingURL=createPriceScale.d.ts.map

package/dist/scale/createPriceScale.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createPriceScale.d.ts","sourceRoot":"","sources":["../../src/scale/createPriceScale.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAEpD,MAAM,WAAW,gBAAgB;IAC7B,wCAAwC;IACxC,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB,6EAA6E;IAC7E,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,uCAAuC;IACvC,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,wDAAwD;IACxD,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAA;CAChC;AAED,wBAAgB,gBAAgB,CAAC,MAAM,GAAE,gBAAqB,GAAG,UAAU,CA2K1E"}

package/dist/scale/createPriceScale.js

@@ -0,0 +1,175 @@
+/**
+ * PriceScale factory — price ↔ screen Y (ROADMAP §1.2) + origin-shift policy
+ * (ROADMAP §2.5).
+ *
+ * Linear mapping (top-origin, Y grows downward):
+ *
+ *     t        = (p        - visibleMin)        / (visibleMax - visibleMin)
+ *     y        = height - t * height
+ *     inverse: p = visibleMin + (1 - y / height) * (visibleMax - visibleMin)
+ *
+ * Log mapping (only valid for strictly positive ranges):
+ *
+ *     t        = (ln(p)    - ln(visibleMin))    / (ln(visibleMax) - ln(visibleMin))
+ *     y        = height - t * height
+ *     inverse: p = exp(ln(visibleMin) + (1 - y / height) * (ln(visibleMax) - ln(visibleMin)))
+ *
+ * Origin-shift policy: lives inside this scale and is consulted on every
+ * `setVisibleRange`. It is intentionally in **linear-price space**, applied
+ * *before* the log transform — that matches the existing engine and keeps the
+ * "shift is just a translation" mental model clean. (Log-space shift is also
+ * mathematically valid; it would compose better with sub-cent log-axis zoom on
+ * astronomically high prices, but we have no such use case and this keeps
+ * parity with the legacy renderer.)
+ *
+ * Degenerate range handling: when `visibleMin === visibleMax`, `priceToY` and
+ * `yToPrice` would divide by zero. We pin the output to `height / 2` (the
+ * geometric center) and document that the caller should treat this as
+ * "everything at the same price"; this is preferred over throwing because
+ * mid-frame `setVisibleRange(p, p)` is reachable from external data feeds and
+ * we don't want one bad row to crash the chart.
+ */
+import { createSignal } from '../reactivity/signal';
+import { KLineChartError } from '../errors';
+import { createOriginShiftPolicy } from './originShift';
+export function createPriceScale(config = {}) {
+    const initialMode = config.initialMode ?? 'linear';
+    const initialVisibleMin = config.initialVisibleMin ?? 0;
+    const initialVisibleMax = config.initialVisibleMax ?? 100;
+    const initialHeight = config.initialHeight ?? 480;
+    if (!(initialVisibleMax >= initialVisibleMin)) {
+        throw new KLineChartError('SCALE_RANGE_INVALID', `createPriceScale: initialVisibleMax (${initialVisibleMax}) must be >= initialVisibleMin (${initialVisibleMin})`);
+    }
+    if (initialMode === 'log' && !(initialVisibleMin > 0)) {
+        throw new KLineChartError('SCALE_LOG_REQUIRES_POSITIVE', `createPriceScale: log mode requires visibleMin > 0, got ${initialVisibleMin}`);
+    }
+    if (!(initialHeight > 0)) {
+        throw new KLineChartError('SCALE_HEIGHT_INVALID', `createPriceScale: initialHeight must be > 0, got ${initialHeight}`);
+    }
+    const mode = createSignal(initialMode);
+    const visibleMin = createSignal(initialVisibleMin);
+    const visibleMax = createSignal(initialVisibleMax);
+    const height = createSignal(initialHeight);
+    const initialRef = (initialVisibleMin + initialVisibleMax) / 2;
+    const policy = createOriginShiftPolicy(initialRef, config.originShiftThreshold);
+    const originShiftRef = createSignal(policy.ref);
+    let disposed = false;
+    /**
+     * Post-dispose: mutator calls become silent no-ops. See createTimeScale.ts
+     * for the rationale + API audit BLOCKER-004 reference. Returns `true` when
+     * the operation should proceed.
+     */
+    const guard = () => !disposed;
+    /**
+     * Run `policy.maybeRebaseline` with the latest visible range and, if it
+     * rebased, mirror the new value into the reactive `originShiftRef` signal
+     * so subscribers (uniform updaters, GPU buffer uploaders) can pick it up.
+     */
+    const syncOriginShift = () => {
+        const min = visibleMin.peek();
+        const max = visibleMax.peek();
+        const range = max - min;
+        const mid = (min + max) / 2;
+        if (policy.maybeRebaseline(mid, range)) {
+            originShiftRef.set(policy.ref);
+        }
+    };
+    const priceToYLinear = (p) => {
+        const min = visibleMin.peek();
+        const max = visibleMax.peek();
+        const h = height.peek();
+        const span = max - min;
+        if (span <= 0)
+            return h / 2;
+        const t = (p - min) / span;
+        return h - t * h;
+    };
+    const priceToYLog = (p) => {
+        const min = visibleMin.peek();
+        const max = visibleMax.peek();
+        const h = height.peek();
+        // Defensive — setMode('log') already rejects bad ranges, but we keep
+        // priceToY total so a stray p<=0 doesn't NaN out the whole chart.
+        if (p <= 0 || min <= 0 || max <= 0 || max <= min)
+            return h / 2;
+        const t = (Math.log(p) - Math.log(min)) / (Math.log(max) - Math.log(min));
+        return h - t * h;
+    };
+    const yToPriceLinear = (y) => {
+        const min = visibleMin.peek();
+        const max = visibleMax.peek();
+        const h = height.peek();
+        const span = max - min;
+        if (span <= 0)
+            return min;
+        return min + (1 - y / h) * span;
+    };
+    const yToPriceLog = (y) => {
+        const min = visibleMin.peek();
+        const max = visibleMax.peek();
+        const h = height.peek();
+        if (min <= 0 || max <= 0 || max <= min)
+            return min;
+        const lmin = Math.log(min);
+        const lmax = Math.log(max);
+        const ly = lmin + (1 - y / h) * (lmax - lmin);
+        return Math.exp(ly);
+    };
+    const scale = {
+        mode,
+        visibleMin,
+        visibleMax,
+        height,
+        originShiftRef: originShiftRef,
+        priceToY(p) {
+            return mode.peek() === 'log' ? priceToYLog(p) : priceToYLinear(p);
+        },
+        yToPrice(y) {
+            return mode.peek() === 'log' ? yToPriceLog(y) : yToPriceLinear(y);
+        },
+        setMode(next) {
+            if (!guard())
+                return;
+            if (next === 'log') {
+                const min = visibleMin.peek();
+                const max = visibleMax.peek();
+                if (!(min > 0) || !(max > 0)) {
+                    throw new KLineChartError('SCALE_LOG_REQUIRES_POSITIVE', `PriceScale.setMode('log'): requires visibleMin > 0 and visibleMax > 0, got min=${min}, max=${max}`);
+                }
+            }
+            mode.set(next);
+        },
+        setVisibleRange(min, max) {
+            if (!guard())
+                return;
+            if (!Number.isFinite(min) || !Number.isFinite(max)) {
+                throw new KLineChartError('SCALE_RANGE_INVALID', `PriceScale.setVisibleRange: both bounds must be finite, got min=${min}, max=${max}`);
+            }
+            if (max < min) {
+                throw new KLineChartError('SCALE_RANGE_INVALID', `PriceScale.setVisibleRange: max (${max}) must be >= min (${min})`);
+            }
+            if (mode.peek() === 'log' && !(min > 0)) {
+                throw new KLineChartError('SCALE_LOG_REQUIRES_POSITIVE', `PriceScale.setVisibleRange: log mode requires min > 0, got ${min}`);
+            }
+            visibleMin.set(min);
+            visibleMax.set(max);
+            syncOriginShift();
+        },
+        setHeight(h) {
+            if (!guard())
+                return;
+            if (!(h > 0)) {
+                throw new KLineChartError('SCALE_HEIGHT_INVALID', `PriceScale.setHeight: height must be > 0, got ${h}`);
+            }
+            height.set(h);
+        },
+        toShiftedFp32(p) {
+            return policy.shift(p);
+        },
+        dispose() {
+            disposed = true;
+        },
+    };
+    return scale;
+}
+//# sourceMappingURL=createPriceScale.js.map

package/dist/scale/createPriceScale.js.map

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

package/dist/scale/createTimeScale.d.ts

@@ -0,0 +1,27 @@
+/**
+ * TimeScale factory — discrete bar-index ↔ screen X mapping (ROADMAP §1.1).
+ *
+ * The math is one-line in each direction; the value of this factory is the
+ * reactive plumbing (signals so adapters can subscribe) and the optional
+ * wall-clock calendar that maps bar indices ↔ timestamps.
+ *
+ *     forward:  x(i) = (i - firstVisibleIndex) * barWidth + leftPadding
+ *     inverse:  i(x) = (x - leftPadding) / barWidth + firstVisibleIndex
+ *
+ * Calendar semantics: when the user attaches a `barTimestamps` array, we treat
+ * bar index `i` as the array index. Integer indices map directly; fractional
+ * indices linearly interpolate between neighboring timestamps. Anything
+ * outside `[0, N-1]` returns `null` — the caller decides whether to clamp,
+ * extrapolate, or display a "—" label.
+ */
+import type { TimeScale } from './types';
+export interface TimeScaleConfig {
+    /** Default firstVisibleIndex. Fractional/negative allowed. Default 0. */
+    initialFirstVisibleIndex?: number;
+    /** Default barWidth in logical px. Must be > 0. Default 8. */
+    initialBarWidth?: number;
+    /** Default leftPadding in logical px. Default 0. */
+    initialLeftPadding?: number;
+}
+export declare function createTimeScale(config?: TimeScaleConfig): TimeScale;
+//# sourceMappingURL=createTimeScale.d.ts.map

package/dist/scale/createTimeScale.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createTimeScale.d.ts","sourceRoot":"","sources":["../../src/scale/createTimeScale.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAExC,MAAM,WAAW,eAAe;IAC5B,yEAAyE;IACzE,wBAAwB,CAAC,EAAE,MAAM,CAAA;IACjC,8DAA8D;IAC9D,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,oDAAoD;IACpD,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED,wBAAgB,eAAe,CAAC,MAAM,GAAE,eAAoB,GAAG,SAAS,CAuHvE"}