wickchart 0.3.0

package/types/core.d.ts

@@ -0,0 +1,572 @@
+export type Bar = {
+    time: number;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume?: number;
+};
+export type IndicatorLine = {
+    name?: string;
+    values: Array<number | null>;
+    /**
+     * #hex / rgb() / CSS name / palette key
+     */
+    color?: string;
+};
+export type IndicatorDef = {
+    /**
+     * overlay on the price pane, or a stacked sub-pane
+     */
+    kind?: 'overlay' | 'pane';
+    /**
+     * defaults; set via `name:p1/p2` tokens
+     */
+    params?: Record<string, number>;
+    compute: (bars: Bar[], params: Record<string, number>) => (Array<number | null> | {
+        lines?: IndicatorLine[];
+        histogram?: Array<number | null>;
+    });
+    /**
+     * pane only: dashed horizontal levels
+     */
+    guides?: number[];
+    /**
+     * pane only: fixed scale (else autoscale)
+     */
+    range?: [number, number];
+    /**
+     * legend/axis number format
+     */
+    fmt?: 'price' | 'fixed1';
+    color?: string;
+};
+export type Position = {
+    id: string;
+    side: 'long' | 'short';
+    entry: number;
+    stop: number | null;
+    target: number | null;
+    qty: number | null;
+};
+export type Alert = {
+    id: string;
+    price: number;
+    direction: 'above' | 'below' | 'cross';
+    once: boolean;
+};
+export type ChartState = {
+    type?: 'candles' | 'line' | 'area' | 'bars' | 'hollow' | 'heikin';
+    theme?: 'dark' | 'light';
+    log?: boolean;
+    stats?: boolean;
+    /**
+     * volume profile overlay (POC + value area)
+     */
+    profile?: boolean;
+    /**
+     * smart annotations (spikes/gaps/pivots/divergences)
+     */
+    annotations?: boolean;
+    label?: string;
+    indicators?: string;
+    /**
+     * visible time window (ms)
+     */
+    view?: {
+        from: number;
+        to: number;
+    };
+    /**
+     * partial positions to add
+     */
+    positions?: Array<Position & {
+        id?: string;
+        stop?: number;
+        target?: number;
+        qty?: number;
+    }>;
+    /**
+     * partial alerts to add
+     */
+    alerts?: Array<Alert & {
+        id?: string;
+        once?: boolean;
+    }>;
+};
+export type IndicatorEntry = {
+    name: string;
+    def: IndicatorDef;
+    params: Record<string, number>;
+    color: string | null;
+    key: string;
+};
+/**
+ * A single OHLCV bar. `time` is milliseconds (second-based input is
+ * auto-detected and converted).
+ * @typedef {object} Bar
+ * @property {number} time
+ * @property {number} open
+ * @property {number} high
+ * @property {number} low
+ * @property {number} close
+ * @property {number} [volume]
+ */
+/**
+ * One plotted line of an indicator result.
+ * @typedef {object} IndicatorLine
+ * @property {string} [name]
+ * @property {Array<number|null>} values
+ * @property {string} [color] #hex / rgb() / CSS name / palette key
+ */
+/**
+ * An indicator definition for {@link registerIndicator}.
+ * @typedef {object} IndicatorDef
+ * @property {'overlay'|'pane'} [kind] overlay on the price pane, or a stacked sub-pane
+ * @property {Record<string, number>} [params] defaults; set via `name:p1/p2` tokens
+ * @property {(bars: Bar[], params: Record<string, number>) => (Array<number|null>|{lines?: IndicatorLine[], histogram?: Array<number|null>})} compute
+ * @property {number[]} [guides] pane only: dashed horizontal levels
+ * @property {[number, number]} [range] pane only: fixed scale (else autoscale)
+ * @property {'price'|'fixed1'} [fmt] legend/axis number format
+ * @property {string} [color]
+ */
+/**
+ * A position/order visualization.
+ * @typedef {object} Position
+ * @property {string} id
+ * @property {'long'|'short'} side
+ * @property {number} entry
+ * @property {number|null} stop
+ * @property {number|null} target
+ * @property {number|null} qty
+ */
+/**
+ * A price alert (edge-triggered on streamed crossings).
+ * @typedef {object} Alert
+ * @property {string} id
+ * @property {number} price
+ * @property {'above'|'below'|'cross'} direction
+ * @property {boolean} once
+ */
+/**
+ * Serializable chart snapshot (see `getState()` / `setState()`).
+ * @typedef {object} ChartState
+ * @property {'candles'|'line'|'area'|'bars'|'hollow'|'heikin'} [type]
+ * @property {'dark'|'light'} [theme]
+ * @property {boolean} [log]
+ * @property {boolean} [stats]
+ * @property {boolean} [profile] volume profile overlay (POC + value area)
+ * @property {boolean} [annotations] smart annotations (spikes/gaps/pivots/divergences)
+ * @property {string} [label]
+ * @property {string} [indicators]
+ * @property {{from: number, to: number}} [view] visible time window (ms)
+ * @property {Array<Position & {id?: string, stop?: number, target?: number, qty?: number}>} [positions] partial positions to add
+ * @property {Array<Alert & {id?: string, once?: boolean}>} [alerts] partial alerts to add
+ */
+/**
+ * A parsed indicator entry (internal token → def binding).
+ * @typedef {object} IndicatorEntry
+ * @property {string} name
+ * @property {IndicatorDef} def
+ * @property {Record<string, number>} params
+ * @property {string|null} color
+ * @property {string} key
+ */
+export declare const clamp: (v: any, lo: any, hi: any) => any;
+export declare const isNum: (v: any) => boolean;
+export declare const pad2: (n: any) => string;
+export declare function numberFmt(p: any): any;
+export declare function fmtCompact(v: any): any;
+export declare function autoPrecision(v: any): 2 | 3 | 5 | 8;
+/** Nice round step (1, 2, 5 × 10^n) covering `range` in ~`target` steps. */
+export declare function niceStep(range: any, target: any): number;
+export declare function hexToRgba(color: any, alpha: any): any;
+export declare function safeColor(s: any): string;
+export declare const FONT_STACK = "ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif";
+export declare const axisFont: (w?: number) => string;
+export declare const pillFont: () => string;
+export declare function roundRectPath(ctx: any, x: any, y: any, w: any, h: any, r: any): void;
+export declare const SEC = 1000;
+export declare const MIN: number;
+export declare const HOUR: number;
+export declare const DAY: number;
+export declare const TIME_STEPS: {
+    ms: number;
+    label: string;
+}[];
+export declare const hhmm: (t: any) => string;
+export declare const fmtDay: (t: any) => any;
+export declare const fmtMonth: (t: any, withYear: any) => any;
+export declare const fmtYear: (t: any) => any;
+export declare const fmtFull: (t: any) => string;
+export declare const THEMES: {
+    dark: {
+        bg: string;
+        text: string;
+        textStrong: string;
+        grid: string;
+        border: string;
+        up: string;
+        down: string;
+        accent: string;
+        crosshair: string;
+        crosshairBg: string;
+        crosshairText: string;
+        pillText: string;
+        rsi: string;
+        guide: string;
+        volAlpha: number;
+        overlay: string[];
+    };
+    light: {
+        bg: string;
+        text: string;
+        textStrong: string;
+        grid: string;
+        border: string;
+        up: string;
+        down: string;
+        accent: string;
+        crosshair: string;
+        crosshairBg: string;
+        crosshairText: string;
+        pillText: string;
+        rsi: string;
+        guide: string;
+        volAlpha: number;
+        overlay: string[];
+    };
+};
+/**
+ * @param {number[]} values
+ * @param {number} period
+ * @returns {Array<number|null>}
+ */
+export declare function calcSMA(values: number[], period: number): Array<number | null>;
+/**
+ * @param {number[]} values
+ * @param {number} period
+ * @returns {Array<number|null>}
+ */
+export declare function calcEMA(values: number[], period: number): Array<number | null>;
+/** EMA over a series that may contain leading nulls (e.g. MACD line).
+ * @param {Array<number|null>} values
+ * @param {number} period
+ * @returns {Array<number|null>}
+ */
+export declare function calcEMASparse(values: Array<number | null>, period: number): Array<number | null>;
+/**
+ * @param {number[]} closes
+ * @param {number} period
+ * @returns {Array<number|null>}
+ */
+export declare function calcRSI(closes: number[], period: number): Array<number | null>;
+/** Rolling standard deviation (population) over `period`, aligned like SMA. */
+export declare function calcStdDev(values: any, period: any): any[];
+/**
+ * Bollinger Bands.
+ * @param {number[]} closes
+ * @param {number} period
+ * @param {number} [mult]
+ * @returns {{mid:Array<number|null>, upper:Array<number|null>, lower:Array<number|null>}}
+ */
+export declare function calcBollinger(closes: number[], period: number, mult?: number): {
+    mid: Array<number | null>;
+    upper: Array<number | null>;
+    lower: Array<number | null>;
+};
+/**
+ * MACD.
+ * @param {number[]} closes
+ * @param {number} [fast]
+ * @param {number} [slow]
+ * @param {number} [signal]
+ * @returns {{macd:Array<number|null>, signal:Array<number|null>, hist:Array<number|null>}}
+ */
+export declare function calcMACD(closes: number[], fast?: number, slow?: number, signal?: number): {
+    macd: Array<number | null>;
+    signal: Array<number | null>;
+    hist: Array<number | null>;
+};
+/**
+ * Merge older (backfilled) bars in front of `existing`.
+ * Dedupes by time (existing bars win); only strictly older bars are prepended.
+ * @param {Bar[]} existing
+ * @param {Bar[]} older
+ * @returns {{bars: Bar[], added: number}} merged array and count prepended.
+ */
+export declare function mergeOlderData(existing: Bar[], older: Bar[]): {
+    bars: Bar[];
+    added: number;
+};
+/**
+ * Indices of visible bars whose time jump from the previous bar exceeds
+ * `threshold × dt` (sessions breaks, weekends, missing data).
+ * @param {Bar[]} bars
+ * @param {number} i0
+ * @param {number} i1
+ * @param {number} dtMs
+ * @param {number} [threshold]
+ * @returns {number[]}
+ */
+export declare function detectGaps(bars: Bar[], i0: number, i1: number, dtMs: number, threshold?: number): number[];
+/**
+ * Aggregate a visible bar range into ~1px-wide columns for deep zoom-outs.
+ * `xOf(i)` must be non-decreasing in i (index-space x mapping guarantees it).
+ * Each column keeps first open / max high / min low / last close / volume sum.
+ * @param {Bar[]} bars
+ * @param {number} i0
+ * @param {number} i1
+ * @param {(i: number) => number} xOf
+ * @param {number} plotRight plot width in px (column count)
+ * @returns {Array<{x: number, i0: number, i1: number, open: number, high: number, low: number, close: number, volume: number}>}
+ */
+export declare function buildColumns(bars: Bar[], i0: number, i1: number, xOf: (i: number) => number, plotRight: number): Array<{
+    x: number;
+    i0: number;
+    i1: number;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume: number;
+}>;
+/**
+ * Detect notable events over a visible bar window.
+ * Volume spikes (> volMult × SMA(volume)), price gaps beyond the previous
+ * bar's range (> gapMult × average range), pivot highs/lows (± pivot bars),
+ * and RSI divergences (later higher high with weaker RSI, and symmetric lows).
+ *
+ * @param {Bar[]} bars full dataset (raw)
+ * @param {number} i0 first visible index
+ * @param {number} i1 last visible index
+ * @param {Array<number|null>|null} rsi precomputed RSI series (or null to skip divergences)
+ * @param {{pivot?: number, volMult?: number, gapMult?: number, divDist?: number}} [opts]
+ * @returns {Array<{type: string, side: 'high'|'low', i: number, note: string}>}
+ */
+export declare function detectAnnotations(bars: Bar[], i0: number, i1: number, rsi: Array<number | null> | null, opts?: {
+    pivot?: number;
+    volMult?: number;
+    gapMult?: number;
+    divDist?: number;
+}): Array<{
+    type: string;
+    side: 'high' | 'low';
+    i: number;
+    note: string;
+}>;
+/**
+ * Map a price to a sonification frequency over the visible scale.
+ * Logarithmic scales map through log-space; result clamped to [lo, hi] Hz.
+ * @param {number} price
+ * @param {{min: number, max: number, useLog?: boolean}} scale
+ * @param {number} [freqLo=180]
+ * @param {number} [freqHi=880]
+ * @returns {number} frequency in Hz
+ */
+export declare function priceToFreq(price: number, scale: {
+    min: number;
+    max: number;
+    useLog?: boolean;
+}, freqLo?: number, freqHi?: number): number;
+/**
+ * Volume profile over a visible bar range: volume distributed into price
+ * rows, with POC and the value area (greedy expansion around the POC).
+ * @param {Bar[]} bars
+ * @param {number} i0
+ * @param {number} i1
+ * @param {{rows?: number, valueAreaPct?: number}} [opts]
+ * @returns {null|{
+ *   rows: Array<{v: number, up: number, dn: number}>, maxV: number, total: number,
+ *   rowH: number, priceMin: number, priceMax: number,
+ *   pocIndex: number, valIndex: number, vahIndex: number,
+ *   poc: number, val: number, vah: number
+ * }}
+ */
+export declare function computeVolumeProfile(bars: Bar[], i0: number, i1: number, opts?: {
+    rows?: number;
+    valueAreaPct?: number;
+}): null | {
+    rows: Array<{
+        v: number;
+        up: number;
+        dn: number;
+    }>;
+    maxV: number;
+    total: number;
+    rowH: number;
+    priceMin: number;
+    priceMax: number;
+    pocIndex: number;
+    valIndex: number;
+    vahIndex: number;
+    poc: number;
+    val: number;
+    vah: number;
+};
+/** Supported values for the `type` attribute. */
+export declare const SERIES_TYPES: string[];
+/**
+ * Heikin-Ashi transform (smoothed candles; time/volume pass through).
+ * @param {Bar[]} bars
+ * @returns {Bar[]}
+ */
+export declare function calcHeikinAshi(bars: Bar[]): Bar[];
+/**
+ * Normalize an indicator compute() result to
+ * `{ lines: [{name, values, color?}], histogram: number[] | null }`.
+ */
+export declare function normalizeIndicatorResult(res: any): {
+    lines: any;
+    histogram: any;
+};
+/** Built-in indicator definitions (name → def). */
+export declare const BUILTIN_INDICATORS: Map<string, {
+    kind: string;
+    params: {
+        period: number;
+        mult?: undefined;
+        fast?: undefined;
+        slow?: undefined;
+        signal?: undefined;
+    };
+    compute: (bars: any, p: any) => number[];
+    range?: undefined;
+    color?: undefined;
+    guides?: undefined;
+    fmt?: undefined;
+} | {
+    kind: string;
+    params: {
+        period: number;
+        mult?: undefined;
+        fast?: undefined;
+        slow?: undefined;
+        signal?: undefined;
+    };
+    compute: (bars: any, p: any) => number[];
+    range?: undefined;
+    color?: undefined;
+    guides?: undefined;
+    fmt?: undefined;
+} | {
+    kind: string;
+    params: {
+        period: number;
+        mult: number;
+        fast?: undefined;
+        slow?: undefined;
+        signal?: undefined;
+    };
+    compute: (bars: any, p: any) => {
+        lines: {
+            name: string;
+            values: number[];
+        }[];
+    };
+    range?: undefined;
+    color?: undefined;
+    guides?: undefined;
+    fmt?: undefined;
+} | {
+    kind: string;
+    params: {
+        mult?: undefined;
+        period: number;
+        fast?: undefined;
+        slow?: undefined;
+        signal?: undefined;
+    };
+    guides: number[];
+    range: number[];
+    fmt: string;
+    color: string;
+    compute: (bars: any, p: any) => number[];
+} | {
+    range?: undefined;
+    color?: undefined;
+    kind: string;
+    params: {
+        mult?: undefined;
+        period?: undefined;
+        fast: number;
+        slow: number;
+        signal: number;
+    };
+    guides: number[];
+    fmt: string;
+    compute: (bars: any, p: any) => {
+        lines: {
+            name: string;
+            values: number[];
+        }[];
+        histogram: number[];
+    };
+}>;
+/**
+ * Parse an `indicators` attribute string against a registry.
+ * Token: `name[:param[/param…]][@color]`, plus the `volume` keyword.
+ * @param {string|null|undefined} str
+ * @param {Map<string, IndicatorDef>} registry
+ * @returns {{overlays: IndicatorEntry[], panes: IndicatorEntry[], volume: boolean, unknown: string[]}}
+ */
+export declare function parseIndicators(str: string | null | undefined, registry: Map<string, IndicatorDef>): {
+    overlays: IndicatorEntry[];
+    panes: IndicatorEntry[];
+    volume: boolean;
+    unknown: string[];
+};
+/**
+ * Unrealized P&L of a position at `price`.
+ * @param {{side?: 'long'|'short', entry: number, qty?: number}} pos
+ * @param {number} price
+ * @returns {number}
+ */
+export declare function positionPnl(pos: {
+    side?: 'long' | 'short';
+    entry: number;
+    qty?: number;
+}, price: number): number;
+/**
+ * Edge-triggered alert crossing test between two consecutive prices.
+ * @param {{price: number, direction?: 'above'|'below'|'cross'}} alert
+ * @param {number} prevPrice
+ * @param {number} price
+ * @returns {boolean}
+ */
+export declare function checkAlertCross(alert: {
+    price: number;
+    direction?: 'above' | 'below' | 'cross';
+}, prevPrice: number, price: number): boolean;
+/**
+ * Statistics over a visible slice of bars.
+ * @param {Bar[]} bars
+ * @param {number} i0
+ * @param {number} i1
+ * @param {number} dtMs
+ * @returns {null|{n:number, changePct:number, min:number, max:number, maxDDPct:number, annVolPct:number, up:number, dn:number, avgVolume:number}}
+ */
+export declare function computeStats(bars: Bar[], i0: number, i1: number, dtMs: number): null | {
+    n: number;
+    changePct: number;
+    min: number;
+    max: number;
+    maxDDPct: number;
+    annVolPct: number;
+    up: number;
+    dn: number;
+    avgVolume: number;
+};
+/**
+ * Encode a chart state (from getState()) as a compact query string.
+ * View times are encoded in whole seconds.
+ * @param {ChartState|null} state
+ * @returns {string}
+ */
+export declare function encodeStateQuery(state: ChartState | null): string;
+/**
+ * Decode a query string (from encodeStateQuery) back into a partial state.
+ * @param {string} str
+ * @returns {ChartState}
+ */
+export declare function decodeStateQuery(str: string): ChartState;

package/types/feeds.d.ts

@@ -0,0 +1,58 @@
+export declare const TF_SECONDS: {
+    '1m': number;
+    '3m': number;
+    '5m': number;
+    '15m': number;
+    '30m': number;
+    '1h': number;
+    '2h': number;
+    '4h': number;
+    '6h': number;
+    '12h': number;
+    '1d': number;
+    '3d': number;
+    '1w': number;
+};
+/** Seconds for a timeframe id ('15m', '1h', '1D'…); defaults to 1h. */
+export declare function tfToSeconds(tf: any): any;
+export declare const BASE_PRICES: {
+    BTC: number;
+    ETH: number;
+    SOL: number;
+    DEMO: number;
+};
+export declare function mulberry32(seed: any): () => number;
+export declare function gauss(rnd: any): number;
+export declare function hashStr(s: any): number;
+/**
+ * Deterministic synthetic OHLCV history (random walk with volatility regimes
+ * and mild mean reversion). Same key → same series.
+ * @param {string} key seed key (symbol, symbol+tf, …)
+ * @param {number} sec timeframe in seconds
+ * @param {number} n bar count
+ * @param {number} [base=100] starting/base price
+ */
+export declare function genSynthetic(key: string, sec: number, n: number, base?: number): any[];
+/**
+ * Stateful synthetic live stream: mutates the current bar each tick and
+ * rolls over on timeframe boundaries. Bridges from `startPrice` when given.
+ * @param {number} sec timeframe in seconds
+ * @param {number} [startPrice] bridge continuity from the last known price
+ */
+export declare function makeSynthStream(sec: number, startPrice?: number): () => any;
+/**
+ * Fetch klines from Binance's public REST API.
+ * @param {string} symbol e.g. 'BTCUSDT'
+ * @param {string} tfId interval id ('15m','1h','1d'…)
+ * @param {number} [limit=500]
+ * @param {number} [endTime] fetch bars older than this (ms) — for backfill
+ */
+export declare function fetchBinanceKlines(symbol: string, tfId: string, limit?: number, endTime?: number): Promise<any>;
+/**
+ * Open a Binance kline WebSocket. `onDown(err)` fires on error/close/timeout
+ * (after which the socket is dead and the caller should fall back).
+ * @returns {{close(): void}}
+ */
+export declare function openBinanceSocket(symbol: any, tfId: any, onBar: any, onDown: any, timeoutMs?: number): {
+    close(): void;
+};