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

package/src/scale/createPriceScale.ts

@@ -0,0 +1,226 @@
+/**
+ * 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 type { Signal } from '../reactivity/signal'
+import { createOriginShiftPolicy, type OriginShiftPolicy } from './originShift'
+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 function createPriceScale(config: PriceScaleConfig = {}): PriceScale {
+    const initialMode: ScaleMode = 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<ScaleMode>(initialMode)
+    const visibleMin = createSignal(initialVisibleMin)
+    const visibleMax = createSignal(initialVisibleMax)
+    const height = createSignal(initialHeight)
+
+    const initialRef = (initialVisibleMin + initialVisibleMax) / 2
+    const policy: OriginShiftPolicy = 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 = (): boolean => !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 = (): void => {
+        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: number): number => {
+        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: number): number => {
+        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: number): number => {
+        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: number): number => {
+        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: PriceScale = {
+        mode,
+        visibleMin,
+        visibleMax,
+        height,
+        originShiftRef: originShiftRef as Signal<number>,
+
+        priceToY(p: number): number {
+            return mode.peek() === 'log' ? priceToYLog(p) : priceToYLinear(p)
+        },
+
+        yToPrice(y: number): number {
+            return mode.peek() === 'log' ? yToPriceLog(y) : yToPriceLinear(y)
+        },
+
+        setMode(next: ScaleMode): void {
+            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: number, max: number): void {
+            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: number): void {
+            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: number): number {
+            return policy.shift(p)
+        },
+
+        dispose(): void {
+            disposed = true
+        },
+    }
+
+    return scale
+}

package/src/scale/createTimeScale.ts

@@ -0,0 +1,150 @@
+/**
+ * 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 { createSignal } from '../reactivity/signal'
+import { KLineChartError } from '../errors'
+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 function createTimeScale(config: TimeScaleConfig = {}): TimeScale {
+    const initialFirstVisibleIndex = config.initialFirstVisibleIndex ?? 0
+    const initialBarWidth = config.initialBarWidth ?? 8
+    const initialLeftPadding = config.initialLeftPadding ?? 0
+
+    if (!(initialBarWidth > 0)) {
+        throw new KLineChartError('SCALE_BAR_WIDTH_INVALID', `createTimeScale: initialBarWidth must be > 0, got ${initialBarWidth}`)
+    }
+
+    const firstVisibleIndex = createSignal(initialFirstVisibleIndex)
+    const barWidth = createSignal(initialBarWidth)
+    const leftPadding = createSignal(initialLeftPadding)
+
+    let calendar: { barTimestamps: ReadonlyArray<number> } | null = null
+    let disposed = false
+
+    /**
+     * Post-dispose: mutator calls become silent no-ops. This matches the
+     * convention used by every other controller in @klinechart-quant/core
+     * (IndicatorSelector, Toolbar, Drawing, Alerts, Replay, VolumeProfile,
+     * Footprint, OrderBookHeatmap, AnchoredVwap, MtfOverlay). Throwing on
+     * stale references — as the original implementation did — was the API
+     * audit BLOCKER-004 (docs/audit/API_REVIEW.md) divergence; harmonized
+     * to silent-no-op here.
+     *
+     * Returns `true` when the operation should proceed (controller live),
+     * `false` when it should be skipped (post-dispose).
+     */
+    const guard = (): boolean => !disposed
+
+    const scale: TimeScale = {
+        firstVisibleIndex,
+        barWidth,
+        leftPadding,
+
+        xToBarIndex(x: number): number {
+            // We deliberately read with `.peek()` here — these methods are pure
+            // queries, they must not register the caller as a reactive subscriber.
+            const lp = leftPadding.peek()
+            const bw = barWidth.peek()
+            const fvi = firstVisibleIndex.peek()
+            return (x - lp) / bw + fvi
+        },
+
+        barIndexToX(i: number): number {
+            const lp = leftPadding.peek()
+            const bw = barWidth.peek()
+            const fvi = firstVisibleIndex.peek()
+            return (i - fvi) * bw + lp
+        },
+
+        setFirstVisibleIndex(i: number): void {
+            if (!guard()) return
+            firstVisibleIndex.set(i)
+        },
+
+        setBarWidth(w: number): void {
+            if (!guard()) return
+            if (!(w > 0)) {
+                throw new KLineChartError('SCALE_BAR_WIDTH_INVALID', `TimeScale.setBarWidth: barWidth must be > 0, got ${w}`)
+            }
+            barWidth.set(w)
+        },
+
+        setLeftPadding(p: number): void {
+            if (!guard()) return
+            leftPadding.set(p)
+        },
+
+        setCalendar(c) {
+            if (!guard()) return
+            calendar = c
+        },
+
+        timeToBarIndex(timestamp: number): number | null {
+            if (calendar === null) return null
+            const ts = calendar.barTimestamps
+            const n = ts.length
+            if (n === 0) return null
+            // Binary search for the upper bound of `timestamp` in `ts`.
+            // Returns the fractional index that interpolates linearly between
+            // bracketing bars. Outside the calendar → null.
+            if (timestamp < ts[0] || timestamp > ts[n - 1]) return null
+            if (timestamp === ts[n - 1]) return n - 1
+            let lo = 0
+            let hi = n - 1
+            while (hi - lo > 1) {
+                const mid = (lo + hi) >>> 1
+                if (ts[mid] <= timestamp) lo = mid
+                else hi = mid
+            }
+            const span = ts[hi] - ts[lo]
+            if (span <= 0) return lo
+            return lo + (timestamp - ts[lo]) / span
+        },
+
+        barIndexToTime(i: number): number | null {
+            if (calendar === null) return null
+            const ts = calendar.barTimestamps
+            const n = ts.length
+            if (n === 0) return null
+            if (i < 0 || i > n - 1) return null
+            const lo = Math.floor(i)
+            const hi = Math.min(lo + 1, n - 1)
+            if (lo === hi) return ts[lo]
+            const frac = i - lo
+            return ts[lo] + (ts[hi] - ts[lo]) * frac
+        },
+
+        dispose(): void {
+            // Signals don't allocate listeners we own; we just mark the
+            // instance as dead so writes throw and tests can assert dispose
+            // semantics. Reads remain functional as pure math.
+            disposed = true
+            calendar = null
+        },
+    }
+
+    return scale
+}

package/src/scale/index.ts

@@ -0,0 +1,9 @@
+export type { ScaleMode, TimeScale, PriceScale } from './types'
+export { createTimeScale, type TimeScaleConfig } from './createTimeScale'
+export { createPriceScale, type PriceScaleConfig } from './createPriceScale'
+export {
+    computeAnchoredZoom,
+    type AnchoredZoomOptions,
+    type AnchoredZoomResult,
+} from './anchoredZoom'
+export { createOriginShiftPolicy, type OriginShiftPolicy } from './originShift'

package/src/scale/originShift.ts

@@ -0,0 +1,111 @@
+import { KLineChartError } from '../errors'
+/**
+ * Origin-shift policy — ROADMAP §2.5, refined per the upstream PR feedback
+ * about *rebaseline drift*.
+ *
+ * Background.  GPUs run fp32 (~7 decimal digits of precision). At BTC-tier
+ * prices (~67,000) and tick sizes (~0.01) the absolute price burns most of
+ * the mantissa, and a subtraction like `(p - pMin)` inside a zoomed-in
+ * sub-dollar range produces catastrophic cancellation. The cheap fix is to
+ * subtract a "reference value" `ref` on the CPU (which is fp64 and can spare
+ * it) before uploading, so the GPU only ever sees relative deltas in the
+ * 0.1-or-so range.
+ *
+ * Why this is its own policy object, and why **threshold-based**:
+ *
+ *   The naive implementation — "every frame, set `ref = midpoint of current
+ *   visible range`" — looks right but is actively harmful on pan. Every time
+ *   the user drags one logical pixel, `ref` changes by one logical-pixel-of-
+ *   price, and *all* prices get re-quantized to a slightly different fp32
+ *   rounding. The result is a continuous, sub-pixel **shimmer** of the entire
+ *   chart that the eye perceives as soft jitter even when no actual data has
+ *   changed. (This is the bug I flagged on the upstream PR.)
+ *
+ *   The fix is to keep `ref` *stable* until the visible-range center has
+ *   drifted far enough that the fp32 budget is at risk of being exhausted —
+ *   then rebaseline once, deliberately. The visible artifact becomes a single
+ *   imperceptible discrete snap, instead of a continuous wobble.
+ *
+ *   In practice 1% of the visible range works well: at a 100-dollar range you
+ *   tolerate `ref` being 1 dollar off-center before re-snapping, which is
+ *   nowhere near the fp32 cliff but cuts rebaselines from "every frame" to
+ *   a handful per pan gesture.
+ *
+ * Edge cases worth documenting:
+ *
+ *  - `threshold === 0` forces a rebaseline on *every* call where the midpoint
+ *    differs from `ref` at all — this is the legacy "naive" behaviour, kept
+ *    for parity tests against the bug we're avoiding.
+ *
+ *  - `threshold >= 1` effectively disables rebaselining, useful when an
+ *    adapter wants to manage `ref` externally.
+ *
+ *  - A `currentRange` of zero (degenerate, visibleMin === visibleMax) is
+ *    treated as "no signal" — we don't rebaseline because we cannot compute a
+ *    meaningful normalized drift. The caller is responsible for handling the
+ *    degenerate range elsewhere.
+ */
+
+export interface OriginShiftPolicy {
+    /** Current reference value. Subtract this from any price before upload. */
+    readonly ref: number
+    /** Subtract `ref` from `value`. The fp32-safe number to upload. */
+    shift(value: number): number
+    /**
+     * Maybe rebaseline. Returns `true` iff `ref` was updated.
+     *
+     * Policy: rebaseline only when
+     *   `|currentMid - ref| / currentRange > threshold`.
+     * On rebaseline, `ref` becomes `currentMid`.
+     */
+    maybeRebaseline(currentMid: number, currentRange: number): boolean
+}
+
+const DEFAULT_THRESHOLD = 0.01
+
+/**
+ * @internal — building block used by `createPriceScale`. 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 createOriginShiftPolicy(
+    initialRef: number,
+    threshold: number = DEFAULT_THRESHOLD,
+): OriginShiftPolicy {
+    if (!Number.isFinite(initialRef)) {
+        throw new KLineChartError('INVALID_PARAM', `createOriginShiftPolicy: initialRef must be finite, got ${initialRef}`)
+    }
+    if (!Number.isFinite(threshold) || threshold < 0) {
+        throw new KLineChartError('INVALID_PARAM', `createOriginShiftPolicy: threshold must be >= 0, got ${threshold}`)
+    }
+
+    let ref = initialRef
+
+    const policy: OriginShiftPolicy = {
+        get ref() {
+            return ref
+        },
+        shift(value: number): number {
+            return value - ref
+        },
+        maybeRebaseline(currentMid: number, currentRange: number): boolean {
+            // Degenerate range — refuse to rebaseline. Caller handles this elsewhere.
+            if (!Number.isFinite(currentMid) || !Number.isFinite(currentRange) || currentRange <= 0) {
+                return false
+            }
+
+            const drift = Math.abs(currentMid - ref)
+            const normalized = drift / currentRange
+
+            if (normalized > threshold) {
+                ref = currentMid
+                return true
+            }
+            return false
+        },
+    }
+
+    return policy
+}

package/src/scale/types.ts

@@ -0,0 +1,100 @@
+/**
+ * Coordinate-system interfaces for the headless core.
+ *
+ * The `TimeScale` maps **bar index** (a discrete-but-fractional sequence number)
+ * to a screen X position, per ROADMAP §1.1. Wall-clock time is a secondary
+ * label, available only when a calendar is attached.
+ *
+ * The `PriceScale` maps a (possibly very narrow) price range to screen Y per
+ * ROADMAP §1.2 — and additionally exposes an origin-shift policy so adapters
+ * can keep GPU uploads in safe fp32 territory (ROADMAP §2.5).
+ *
+ * Both scales are **reactive**: their core state is exposed as signals so the
+ * React/Vue/Angular adapter layer can subscribe without re-implementing the
+ * change-detection plumbing.
+ */
+
+import type { Signal } from '../reactivity/signal'
+
+/** Linear (arithmetic) or logarithmic Y mapping. */
+export type ScaleMode = 'linear' | 'log'
+
+/**
+ * Discrete bar-index ↔ screen X mapping (ROADMAP §1.1).
+ *
+ * Forward equation (the only equation a renderer needs to know):
+ *
+ *     x(i) = (i - firstVisibleIndex) * barWidth + leftPadding
+ *
+ * Inverse, used by anchored zoom and hit-testing:
+ *
+ *     i(x) = (x - leftPadding) / barWidth + firstVisibleIndex
+ *
+ * `firstVisibleIndex` is allowed to be **fractional, negative, or > N**;
+ * this is what lets the user pan to "half a bar" or scroll into the future.
+ */
+export interface TimeScale {
+    /** Inverse: screen X (logical px) → fractional bar index. */
+    xToBarIndex(x: number): number
+    /** Forward: fractional bar index → screen X (logical px). */
+    barIndexToX(i: number): number
+
+    /** Fractional, may be negative or > N. */
+    readonly firstVisibleIndex: Signal<number>
+    /** Logical pixels per bar. Clamped by the caller (e.g. zoom) not the scale. */
+    readonly barWidth: Signal<number>
+    /** Logical pixels added on the left edge before bar 0. */
+    readonly leftPadding: Signal<number>
+
+    setFirstVisibleIndex(i: number): void
+    setBarWidth(w: number): void
+    setLeftPadding(p: number): void
+
+    /**
+     * Attach (or detach with `null`) a wall-clock calendar so the scale can
+     * answer `timeToBarIndex` / `barIndexToTime`. Bar indices not covered by
+     * the calendar return `null` — *time is a label, not a coordinate*.
+     */
+    setCalendar(c: { barTimestamps: ReadonlyArray<number> } | null): void
+
+    /** wall-clock ms → fractional bar index; `null` if no calendar / out of range. */
+    timeToBarIndex(timestamp: number): number | null
+    /** fractional bar index → wall-clock ms; `null` if no calendar / out of range. */
+    barIndexToTime(i: number): number | null
+
+    /** Detach signal subscribers and release any internal listeners. */
+    dispose(): void
+}
+
+/**
+ * Price → screen Y mapping (ROADMAP §1.2) plus an origin-shift policy
+ * (ROADMAP §2.5) so adapters can upload fp32-safe values to the GPU.
+ *
+ * Coordinate convention: top-origin, Y increases downward (DOM standard).
+ * A price ≥ `visibleMax` maps to y = 0, a price ≤ `visibleMin` maps to
+ * y = `height`.
+ */
+export interface PriceScale {
+    /** Forward: price → screen Y (top-origin, increases downward). */
+    priceToY(p: number): number
+    /** Inverse: screen Y → price. */
+    yToPrice(y: number): number
+
+    readonly mode: Signal<ScaleMode>
+    readonly visibleMin: Signal<number>
+    readonly visibleMax: Signal<number>
+    readonly height: Signal<number>
+
+    /** Set `'linear'` or `'log'`; throws on `'log'` if `visibleMin <= 0`. */
+    setMode(mode: ScaleMode): void
+    /** Update visible range. Triggers the origin-shift rebaseline check. */
+    setVisibleRange(min: number, max: number): void
+    setHeight(h: number): void
+
+    /** Origin-shift reference; managed automatically but exposed for tests. */
+    readonly originShiftRef: Signal<number>
+    /** Returns `p - originShiftRef.peek()` — what to upload to the GPU as fp32. */
+    toShiftedFp32(p: number): number
+
+    dispose(): void
+}