wickchart 1.6.0 → 2.0.0

package/types/core.d.ts

@@ -190,6 +190,30 @@ export declare const SEC = 1000;
 export declare const MIN: number;
 export declare const HOUR: number;
 export declare const DAY: number;
+/**
+ * Interpret a timestamp as milliseconds. Numbers may be seconds or ms, so
+ * some threshold is unavoidable; pass a `Date` for anything before 1973,
+ * which is unambiguous. Single source of truth — everything that reads a
+ * caller-supplied time goes through here.
+ * @param {number|Date} t
+ * @returns {number} milliseconds
+ */
+export declare const toMs: (t: number | Date) => number;
+/** Warn once per distinct message (used by the 2.0 moved-method stubs in
+ *  wick-chart.js — deleted with them in 3.0). */
+export declare function warnDeprecatedAlias(message: any): void;
+/**
+ * Milliseconds east of UTC in `zone` at the instant `at`.
+ *   'utc'            → 0
+ *   'local' / null   → the browser's zone (DST-correct via Date)
+ *   number           → a fixed offset in ms (exchange sessions)
+ *   IANA name        → DST-correct via Intl
+ * Never throws: an unusable zone reads as UTC.
+ * @param {number} at epoch ms
+ * @param {string|number|null} [zone]
+ * @returns {number} offset in ms
+ */
+export declare function zoneOffset(at: number, zone?: string | number | null): number;
 export declare const TIME_STEPS: {
     ms: number;
     label: string;
@@ -308,12 +332,22 @@ export declare function calcTrueRange(bars: Bar[]): Array<number | null>;
  */
 export declare function calcATR(bars: Bar[], period?: number): Array<number | null>;
 /**
- * Volume-weighted average price over the hlc3 typical price, anchored to
- * each UTC day (resets at the session boundary).
+ * Volume-weighted average price over the hlc3 typical price, resetting at
+ * each session boundary.
+ *
+ * The anchor defaults to the UTC day — the crypto convention, and what this
+ * has always done. Equities, futures and FX rarely open at UTC midnight, so
+ * pass the session's zone (or a fixed offset) to move the reset. Note this is
+ * deliberately independent of the chart's `timezone`, which only governs how
+ * times are displayed: changing the axis to Stockholm should not silently
+ * re-anchor a BTC chart's VWAP.
+ *
  * @param {Bar[]} bars
+ * @param {string|number} [anchor='utc'] 'utc' | 'local' | IANA zone | fixed
+ *   offset in ms — see zoneOffset()
  * @returns {Array<number|null>}
  */
-export declare function calcVWAP(bars: Bar[]): Array<number | null>;
+export declare function calcVWAP(bars: Bar[], anchor?: string | number): Array<number | null>;
 /**
  * On-balance volume: cumulative volume signed by close-to-close direction.
  * @param {Bar[]} bars
@@ -446,20 +480,6 @@ export declare function detectAnnotations(bars: Bar[], i0: number, i1: number, r
     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).
@@ -523,10 +543,10 @@ export declare const BUILTIN_INDICATORS: Map<string, {
         smooth?: undefined;
     };
     compute: (bars: any, p: any) => number[];
-    color?: undefined;
     guides?: undefined;
     range?: undefined;
     fmt?: undefined;
+    color?: undefined;
 } | {
     kind: string;
     params: {
@@ -538,10 +558,10 @@ export declare const BUILTIN_INDICATORS: Map<string, {
         smooth?: undefined;
     };
     compute: (bars: any, p: any) => number[];
-    color?: undefined;
     guides?: undefined;
     range?: undefined;
     fmt?: undefined;
+    color?: undefined;
 } | {
     kind: string;
     params: {
@@ -552,11 +572,11 @@ export declare const BUILTIN_INDICATORS: Map<string, {
         smooth?: undefined;
         period?: undefined;
     };
-    compute: (bars: any) => number[];
-    color?: undefined;
+    compute: (bars: any, p: any) => number[];
     guides?: undefined;
     range?: undefined;
     fmt?: undefined;
+    color?: undefined;
 } | {
     kind: string;
     params: {
@@ -568,10 +588,10 @@ export declare const BUILTIN_INDICATORS: Map<string, {
         smooth?: undefined;
     };
     compute: (bars: any, p: any) => number[];
-    color?: undefined;
     guides?: undefined;
     range?: undefined;
     fmt?: undefined;
+    color?: undefined;
 } | {
     kind: string;
     params: {
@@ -588,10 +608,10 @@ export declare const BUILTIN_INDICATORS: Map<string, {
             values: number[];
         }[];
     };
-    color?: undefined;
     guides?: undefined;
     range?: undefined;
     fmt?: undefined;
+    color?: undefined;
 } | {
     kind: string;
     params: {
@@ -608,10 +628,10 @@ export declare const BUILTIN_INDICATORS: Map<string, {
             values: number[];
         }[];
     };
-    color?: undefined;
     guides?: undefined;
     range?: undefined;
     fmt?: undefined;
+    color?: undefined;
 } | {
     kind: string;
     params: {
@@ -628,10 +648,10 @@ export declare const BUILTIN_INDICATORS: Map<string, {
             values: number[];
         }[];
     };
-    color?: undefined;
     guides?: undefined;
     range?: undefined;
     fmt?: undefined;
+    color?: undefined;
 } | {
     kind: string;
     params: {
@@ -648,7 +668,6 @@ export declare const BUILTIN_INDICATORS: Map<string, {
     color: string;
     compute: (bars: any, p: any) => number[];
 } | {
-    color?: undefined;
     kind: string;
     params: {
         mult?: undefined;
@@ -668,8 +687,8 @@ export declare const BUILTIN_INDICATORS: Map<string, {
         histogram: number[];
     };
     range?: undefined;
-} | {
     color?: undefined;
+} | {
     kind: string;
     params: {
         mult?: undefined;
@@ -683,8 +702,8 @@ export declare const BUILTIN_INDICATORS: Map<string, {
     compute: (bars: any, p: any) => number[];
     guides?: undefined;
     range?: undefined;
-} | {
     color?: undefined;
+} | {
     kind: string;
     params: {
         mult?: undefined;
@@ -703,8 +722,8 @@ export declare const BUILTIN_INDICATORS: Map<string, {
             values: number[];
         }[];
     };
-} | {
     color?: undefined;
+} | {
     kind: string;
     params: {
         mult?: undefined;
@@ -718,8 +737,8 @@ export declare const BUILTIN_INDICATORS: Map<string, {
     compute: (bars: any) => number[];
     guides?: undefined;
     range?: undefined;
-} | {
     color?: undefined;
+} | {
     kind: string;
     params: {
         mult?: undefined;
@@ -733,8 +752,8 @@ export declare const BUILTIN_INDICATORS: Map<string, {
     fmt: string;
     compute: (bars: any, p: any) => number[];
     range?: undefined;
-} | {
     color?: undefined;
+} | {
     kind: string;
     params: {
         mult?: undefined;
@@ -748,6 +767,7 @@ export declare const BUILTIN_INDICATORS: Map<string, {
     range: number[];
     fmt: string;
     compute: (bars: any, p: any) => number[];
+    color?: undefined;
 }>;
 /**
  * Parse an `indicators` attribute string against a registry.
@@ -795,7 +815,7 @@ export declare function evalScript(compiled: {
 /**
  * Build an indicator definition from a WickScript expression — used inline by
  * `indicators="expr:{…}"` / `pexpr:{…}"`, or register it under a name:
- * `HabChart.registerIndicator('myspread', scriptIndicator('close - ema(close,21)'))`.
+ * `WickChart.registerIndicator('myspread', scriptIndicator('close - ema(close,21)'))`.
  * @param {string} src
  * @param {{pane?: boolean}} [opts]
  * @returns {IndicatorDef}
@@ -814,6 +834,18 @@ export declare function positionPnl(pos: {
     entry: number;
     qty?: number;
 }, price: number): number;
+/**
+ * Percent return of a position at `price` — the move per unit, so it does
+ * NOT scale with `qty` the way positionPnl() does. Deriving this by dividing
+ * positionPnl() by the entry price reports qty × the true return.
+ * @param {{side?: 'long'|'short', entry: number}} pos
+ * @param {number} price
+ * @returns {number} percent (10 means +10%)
+ */
+export declare function positionPnlPct(pos: {
+    side?: 'long' | 'short';
+    entry: number;
+}, price: number): number;
 /**
  * Edge-triggered alert crossing test between two consecutive prices.
  * @param {{price: number, direction?: 'above'|'below'|'cross'}} alert
@@ -944,24 +976,6 @@ export declare function normalizeOverlays(list: any): object[];
  * @returns {string} a concrete CSS color
  */
 export declare function resolveOverlayColor(raw: any, pal: object): string;
-/**
- * σ-cone projection from realized per-bar volatility: price bands widening
- * with √h (GBM-style, exp(±z·σ·√h)) over `horizon` future bars.
- * @param {number} lastClose anchor price (bar 0)
- * @param {number} volPerBar per-bar stddev of log returns (from calcRealizedVol)
- * @param {number} horizon future bars (clamped 1–500, default 48)
- * @param {number[]} [levels] σ multipliers, e.g. [1, 2] (each clamped to 0–5)
- * @returns {{horizon: number, levels: number[], bands: Record<string, {up: number[], down: number[]}>}}
- *          bands[z].up/.down are arrays indexed by h = 0…horizon ([0] === lastClose)
- */
-export declare function calcVolCone(lastClose: number, volPerBar: number, horizon: number, levels?: number[]): {
-    horizon: number;
-    levels: number[];
-    bands: Record<string, {
-        up: number[];
-        down: number[];
-    }>;
-};
 /**
  * Validate a scenario spec: a ghost path of future prices (bars or API data)
  * plus optional cone settings. Invalid entries are dropped, never thrown.
@@ -1018,34 +1032,6 @@ export declare function normalizeRiskPlan(spec: any): null | {
     maxK: number;
     label: string;
 };
-/**
- * Turn a bar window into an ordered story: the annotation events (pivot
- * highs/lows, volume spikes, gaps, RSI divergences) plus derived **legs** —
- * the move between consecutive opposite pivots ("+12.4% over 38 bars").
- * The timeline drives the bar-walk player and any caption UI.
- *
- * @param {Bar[]} bars full dataset
- * @param {number} i0 first index of the window
- * @param {number} i1 last index of the window
- * @param {{pivot?: number, volMult?: number, gapMult?: number, rsiPeriod?: number}} [opts]
- *        pivot window defaults to 8 (denser than the annotations overlay's 20)
- * @returns {{i: number, time: number, type: string, side: string, note: string,
- *            legPct?: number, legBars?: number}[]} sorted by index, capped at 60
- */
-export declare function narrateWindow(bars: Bar[], i0: number, i1: number, opts?: {
-    pivot?: number;
-    volMult?: number;
-    gapMult?: number;
-    rsiPeriod?: number;
-}): {
-    i: number;
-    time: number;
-    type: string;
-    side: string;
-    note: string;
-    legPct?: number;
-    legBars?: number;
-}[];
 /**
  * Stats for a brushed bar range: net move (open of the first bar → close
  * of the last), extremes, and summed volume. Powers the brush-selection
@@ -1077,72 +1063,6 @@ export declare function brushStats(bars: Bar[], i0: number, i1: number): null |
     low: number;
     volume: number;
 };
-/** Smoothest cheap easing for viewport pans: slow in, slow out. */
-export declare function easeInOutCubic(t: any): number;
-/**
- * Validate one story scene. Every field is optional except that a scene
- * must be an object; omitted fields simply don't change that aspect of
- * the chart when played. `scenario`/`riskPlan` use a 'clear' sentinel for
- * explicit "remove it" (null input means clear too when the KEY is present).
- *
- *   { title: 'The breakout', note: 'What happened…',
- *     range: { from, to },          // times (s or ms) — the camera pans there
- *     indicators: 'sma:20 rsi:14',  // optional indicator string
- *     type: 'candles',              // optional series type
- *     overlays: [...],              // optional zones/levels (normalizeOverlays)
- *     scenario: {...} | null,       // set / clear a scenario
- *     riskPlan: {...} | null,       // set / clear a risk plan
- *     dwell: 2200 }                 // ms to hold after the pan (500–30000)
- *
- * @returns {object|null} normalized scene, or null for non-objects
- */
-export declare function normalizeScene(scene: any): object | null;
-/**
- * Validate a whole story: normalize each scene, drop junk, cap at 20.
- * @returns {object[]} possibly empty
- */
-export declare function sceneList(story: any): object[];
-/**
- * Tracks other charts viewing the same room: last-sighting timestamps per
- * peer plus the viewport each one is looking at. Pure bookkeeping — the
- * transport (BroadcastChannel, WebSocket, …) lives in the component/app.
- *
- * Peers expire `ttl` ms after their last sighting, so a closed tab fades
- * out of the room without an explicit goodbye.
- */
-export declare class PresenceTracker {
-    ttl: number;
-    /** @type {Map<string, {id: string, name: string|null, range: {from:number,to:number}|null, at: number}>} */
-    peers: Map<string, {
-        id: string;
-        name: string | null;
-        range: {
-            from: number;
-            to: number;
-        } | null;
-        at: number;
-    }>;
-    /** @param {number} [ttl=12000] ms a peer survives without a sighting */
-    constructor(ttl?: number);
-    /**
-     * Record a sighting. `patch.range` ({from,to} times) is validated and
-     * normalized; a sighting without a range keeps the previous one.
-     * @returns {boolean} true when this sighting is a join (new peer)
-     */
-    track(id: any, patch?: {}, now?: number): boolean;
-    /** @returns {object|null} the removed peer entry, or null when unknown */
-    drop(id: any): object | null;
-    /** Expire peers not seen within the ttl.
-     *  @returns {object[]} the peer entries that left */
-    sweep(now?: number): object[];
-    /** @returns {{id: string, name: string|null, range: object|null, at: number}[]} copies, oldest sighting first */
-    list(): {
-        id: string;
-        name: string | null;
-        range: object | null;
-        at: number;
-    }[];
-}
 export declare const tfLabelOf: (dtMs: any) => string;
 /**
  * Compact, LLM-friendly summary of a bar window: structured fields plus a
@@ -1172,110 +1092,3 @@ export declare function encodeStateQuery(state: ChartState | null): string;
  * @returns {ChartState}
  */
 export declare function decodeStateQuery(str: string): ChartState;
-/**
- * Tool manifest for LLM/agent control of a chart. Tools map 1:1 onto the
- * public element API; every op through applyChartOps is validated before it
- * touches the chart (LLM output is untrusted input).
- */
-export declare const AI_TOOLS: ({
-    tool: string;
-    description: string;
-    args: {
-        indicators?: undefined;
-        overlays?: undefined;
-        from?: undefined;
-        to?: undefined;
-        type?: undefined;
-        enabled?: undefined;
-        low?: undefined;
-        high?: undefined;
-    };
-} | {
-    tool: string;
-    description: string;
-    args: {
-        indicators: string;
-        overlays?: undefined;
-        from?: undefined;
-        to?: undefined;
-        type?: undefined;
-        enabled?: undefined;
-        low?: undefined;
-        high?: undefined;
-    };
-} | {
-    tool: string;
-    description: string;
-    args: {
-        indicators?: undefined;
-        overlays: string;
-        from?: undefined;
-        to?: undefined;
-        type?: undefined;
-        enabled?: undefined;
-        low?: undefined;
-        high?: undefined;
-    };
-} | {
-    tool: string;
-    description: string;
-    args: {
-        indicators?: undefined;
-        overlays?: undefined;
-        from: string;
-        to: string;
-        type?: undefined;
-        enabled?: undefined;
-        low?: undefined;
-        high?: undefined;
-    };
-} | {
-    tool: string;
-    description: string;
-    args: {
-        indicators?: undefined;
-        overlays?: undefined;
-        from?: undefined;
-        to?: undefined;
-        type: string;
-        enabled?: undefined;
-        low?: undefined;
-        high?: undefined;
-    };
-} | {
-    tool: string;
-    description: string;
-    args: {
-        indicators?: undefined;
-        overlays?: undefined;
-        from?: undefined;
-        to?: undefined;
-        type?: undefined;
-        enabled: string;
-        low: string;
-        high: string;
-    };
-})[];
-/**
- * Compact system prompt for agent control: paste into any LLM alongside the
- * tool manifest. The model answers with a JSON array of {tool, args} ops.
- * @returns {string}
- */
-export declare function aiPromptText(): string;
-/**
- * Validate + apply a list of {tool, args} ops (typically LLM output) to a
- * chart-like target. Ops are whitelisted and their args validated — an op
- * never throws; it returns {ok: false, error} instead so the agent can
- * self-correct. Target contract: getDataWindow(), setAttribute(k, v),
- * setOverlays(list), clearOverlays(), addAlert(a), setVisibleRange(r),
- * fit(), and (static) _registry() for indicator name checks.
- * @param {object} target chart element (or test double)
- * @param {any} ops
- * @returns {Array<{ok: boolean, tool?: string, result?: any, error?: string}>}
- */
-export declare function applyChartOps(target: object, ops: any): Array<{
-    ok: boolean;
-    tool?: string;
-    result?: any;
-    error?: string;
-}>;

package/types/feeds.d.ts

@@ -40,6 +40,131 @@ export declare function genSynthetic(key: string, sec: number, n: number, base?:
  * @param {number} [startPrice] bridge continuity from the last known price
  */
 export declare function makeSynthStream(sec: number, startPrice?: number): () => any;
+/** Default thresholds per kind. They are per-instrument — there is no
+ *  universal "one bar" size, treat these as starting points to tune. */
+export declare const AGG_DEFAULTS: {
+    tick: number;
+    volume: number;
+    dollar: number;
+};
+/**
+ * Parse an `aggregate` spec — `tick`, `volume:50`, `dollar:25000` (case and
+ * whitespace tolerant; the value is the bar size in trades / base units /
+ * quote units respectively).
+ * @param {string} spec attribute value
+ * @returns {{kind: 'tick'|'volume'|'dollar', threshold: number}|null} null when invalid
+ */
+export declare function parseAggregate(spec: string): {
+    kind: 'tick' | 'volume' | 'dollar';
+    threshold: number;
+} | null;
+/**
+ * Streaming aggregator: feed it trades, get bars back. `add()` returns a
+ * bar the moment the threshold is crossed ({@link current} keeps exposing
+ * the forming bar meanwhile). The completing trade belongs entirely to the
+ * closing bar — a whale print is never split across two bars.
+ */
+export declare class TickBarAggregator {
+    kind: string;
+    threshold: any;
+    _bar: {
+        time: number;
+        open: number;
+        high: number;
+        low: number;
+        close: number;
+        volume: number;
+        n: number;
+        notional: number;
+    };
+    /**
+     * @param {'tick'|'volume'|'dollar'} kind what the threshold counts
+     * @param {number} threshold bar size (trades / base units / quote units)
+     */
+    constructor(kind?: 'tick' | 'volume' | 'dollar', threshold?: number);
+    /**
+     * Feed one trade `{ time, price, size }` (seconds auto-upgraded to ms,
+     * same heuristic as the chart). Returns the completed bar —
+     * `{ time, open, high, low, close, volume, closed: true }` — when the
+     * threshold is reached, else null.
+     * @returns {object|null}
+     */
+    add(trade: any): object | null;
+    /** The forming bar as plain chart-bar fields (no internals), or null. */
+    current(): {
+        time: number;
+        open: number;
+        high: number;
+        low: number;
+        close: number;
+        volume: number;
+    };
+    /** Close the forming bar as-is (end of tape / teardown), or null. */
+    flush(): {
+        time: number;
+        open: number;
+        high: number;
+        low: number;
+        close: number;
+        volume: number;
+        closed: boolean;
+    };
+}
+/**
+ * One-pass batch aggregation of a trade history. Returns the closed bars,
+ * the still-forming remainder, and the live aggregator positioned at the end
+ * of the tape so streaming can continue without a seam.
+ * @param {Array<object>} trades `{ time, price, size }` prints
+ * @param {'tick'|'volume'|'dollar'} kind
+ * @param {number} threshold
+ */
+export declare function aggregateTrades(trades: Array<object>, kind: 'tick' | 'volume' | 'dollar', threshold: number): {
+    bars: any[];
+    pending: {
+        time: number;
+        open: number;
+        high: number;
+        low: number;
+        close: number;
+        volume: number;
+    };
+    aggregator: TickBarAggregator;
+};
+/**
+ * Coerce a generic JSON trades array into plain `{ time, price, size }`
+ * (ms, seconds auto-upgraded; `size` also read from `qty`/`amount`).
+ * Invalid entries are dropped, never thrown — same contract as the chart's
+ * other normalizers. Output is sorted by time.
+ */
+export declare function normalizeTrades(list: any): any[];
+/**
+ * Deterministic synthetic trade prints (random-walk price with volatility
+ * regimes, heavy-tailed sizes). Same key → same tape.
+ * @param {string} key seed key
+ * @param {number} [n=24000] print count
+ * @param {number} [base=100] starting price
+ */
+export declare function genSyntheticTrades(key: string, n?: number, base?: number): any[];
+/**
+ * Stateful synthetic live tape: one print per call, bridging from
+ * `startPrice` (e.g. the last price of a seeded history).
+ * @param {number} [startPrice=100]
+ */
+export declare function makeSynthTradeStream(startPrice?: number): () => {
+    time: number;
+    price: number;
+    size: number;
+};
+/**
+ * Expected synthetic prints per bar — used to size the offline seed so a
+ * demo chart starts with roughly the requested bar count.
+ * @param {{kind: string, threshold: number}} agg
+ * @param {number} [base=100]
+ */
+export declare function synthTradesPerBar(agg: {
+    kind: string;
+    threshold: number;
+}, base?: number): number;
 /**
  * Fetch klines from Binance's public REST API.
  * @param {string} symbol e.g. 'BTCUSDT'
@@ -56,3 +181,43 @@ export declare function fetchBinanceKlines(symbol: string, tfId: string, limit?:
 export declare function openBinanceSocket(symbol: any, tfId: any, onBar: any, onDown: any, timeoutMs?: number): {
     close(): void;
 };
+/**
+ * Fetch Binance aggTrades, paging backwards from the newest prints (or from
+ * below `beforeId`) until `minTrades` prints / `maxPages` requests / the
+ * start of the symbol's history. Returns `{ trades, oldestId }` ascending by
+ * time; each print carries its Binance id so live streams can resume without
+ * overlaps.
+ * @param {string} symbol e.g. 'BTCUSDT'
+ * @param {number} [minTrades=1000] stop once at least this many prints are held
+ * @param {number} [maxPages=25] hard request cap (1000 prints per page)
+ * @param {number} [beforeId] only fetch prints with an id lower than this
+ */
+export declare function fetchBinanceAggTrades(symbol: string, minTrades?: number, maxPages?: number, beforeId?: number): Promise<{
+    trades: any[];
+    oldestId: number;
+}>;
+/**
+ * One forward window of aggTrades starting at `fromId` — the catch-up call
+ * for REST polling after a trade socket drops. Returns `{ trades, latestId }`.
+ * @param {string} symbol
+ * @param {number} fromId first print id to fetch (use lastSeenId + 1)
+ */
+export declare function fetchBinanceAggTradesSince(symbol: string, fromId: number): Promise<{
+    trades: {
+        id: any;
+        time: any;
+        price: number;
+        size: number;
+    }[];
+    latestId: any;
+}>;
+/**
+ * Open a Binance aggTrade WebSocket — raw prints for information-based bar
+ * aggregation. Same lifecycle contract as openBinanceSocket: `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 openBinanceTradeSocket(symbol: any, onTrade: any, onDown: any, timeoutMs?: number): {
+    close(): void;
+};