wickchart 1.5.0 → 1.7.0

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;
+};

package/types/report.d.ts

@@ -0,0 +1,114 @@
+/** Decimals worth showing for a price of this magnitude. */
+export declare function decimalsFor(price: any): 2 | 3 | 6;
+/** 1234 → '1.2k', 1234567 → '1.23M', 12 → '12'. */
+export declare function compact(v: any): string;
+export declare function pct(v: any, digits?: number): string;
+/** Greatest index whose time is <= t (binary search; bars are ascending). */
+export declare function indexForTime(bars: any, t: any): number;
+/** Resolve the report colors: theme palettes, overridden by the chart's own
+ *  --wick-* variables when readable (browser) and theme is 'auto'. */
+export declare function reportColors(chart: any, theme?: string): {
+    bg: string;
+    panel: string;
+    text: string;
+    muted: string;
+    up: string;
+    down: string;
+    accent: string;
+} | {
+    bg: string;
+    panel: string;
+    text: string;
+    muted: string;
+    up: string;
+    down: string;
+    accent: string;
+};
+/** Relative luminance of a #hex / rgb() string (0..1, best effort). */
+export declare function luminance(color: any): number;
+/**
+ * Build the whole report as data: sizes, bands, stat rows, colors, labels.
+ * @param {object} chart a <wick-chart> (public API only: data,
+ *   getVisibleRange, exportPNG, clientWidth/Height, getAttribute)
+ * @param {{title?: string, source?: string, brand?: string, theme?: string,
+ *   scale?: number, precision?: number}} [opts]
+ */
+export declare function reportModel(chart: object, opts?: {
+    title?: string;
+    source?: string;
+    brand?: string;
+    theme?: string;
+    scale?: number;
+    precision?: number;
+}): {
+    scale: number;
+    width: number;
+    height: number;
+    bands: {
+        header: number;
+        stats: number;
+        footer: number;
+        chart: number;
+    };
+    grid: {
+        cols: number;
+    };
+    title: any;
+    brand: string;
+    source: string;
+    range: {
+        from: any;
+        to: any;
+    };
+    last: any;
+    precision: number;
+    rows: ({
+        label: string;
+        value: string;
+        color: string;
+    } | {
+        color?: undefined;
+        label: string;
+        value: string;
+    })[];
+    generatedAt: number;
+    colors: {
+        bg: string;
+        panel: string;
+        text: string;
+        muted: string;
+        up: string;
+        down: string;
+        accent: string;
+    } | {
+        bg: string;
+        panel: string;
+        text: string;
+        muted: string;
+        up: string;
+        down: string;
+        accent: string;
+    };
+    stats: {
+        n: number;
+        changePct: number;
+        min: number;
+        max: number;
+        maxDDPct: number;
+        annVolPct: number;
+        up: number;
+        dn: number;
+        avgVolume: number;
+    };
+};
+/**
+ * Compose the branded report and return it as a PNG data URL (default), a
+ * Blob, or the canvas itself.
+ * @returns {Promise<string|Blob|HTMLCanvasElement>}
+ */
+export declare function exportReport(chart: any, opts?: {}): Promise<string | Blob | HTMLCanvasElement>;
+/**
+ * Compose and trigger a download (browser only).
+ * @returns {Promise<void>}
+ */
+export declare function downloadReport(chart: any, filename?: string, opts?: {}): Promise<void>;

package/types/wick-chart.d.ts

@@ -21,7 +21,7 @@ declare class WickChart extends HTMLElementBase {
     _hover: {
         index: any;
         x: number;
-        y: number;
+        y: any;
     } | {
         index: number;
         x: number;
@@ -46,6 +46,10 @@ declare class WickChart extends HTMLElementBase {
             y1: number;
             h: number;
         }[];
+        dock: {
+            y0: number;
+            h: number;
+        };
     };
     _cache: {
         v: number;
@@ -160,6 +164,19 @@ declare class WickChart extends HTMLElementBase {
         panes: any[];
         volume: boolean;
     };
+    _workerOn: boolean;
+    _epoch: number;
+    _workerCache: {
+        epoch: number;
+        map: {};
+        pending: {};
+        sent: number;
+    };
+    _sid: number;
+    _onlineSeries: {
+        epoch: number;
+        map: {};
+    };
     _pointers: Map<any, any>;
     _pan: {
         x: number;
@@ -172,6 +189,13 @@ declare class WickChart extends HTMLElementBase {
         idxAtMid: number;
         midX: number;
     };
+    _scrub: boolean;
+    _pressTimer: number;
+    _pressOrigin: {
+        pointerId: any;
+        x: any;
+        y: any;
+    };
     _layers: any[];
     _layerClaim: {
         layer: any;
@@ -183,6 +207,10 @@ declare class WickChart extends HTMLElementBase {
     _positions: any[];
     _alerts: any[];
     _seq: number;
+    _alertEval: string;
+    _lastClosedIdx: number;
+    _tz: string;
+    _vwapAnchor: string;
     _overlays: any[];
     _scenario: {
         path: {
@@ -215,8 +243,11 @@ declare class WickChart extends HTMLElementBase {
     _onWheel: (e: any) => void;
     _onDbl: () => void;
     _onKey: (e: any) => void;
+    _onTouchMove: (e: any) => void;
+    _onDprChange: () => void;
     tabIndex: number;
     _ro: any;
+    _dprMq: MediaQueryList;
     _posVersion: any;
     _pendingRange: {
         from: number;
@@ -233,9 +264,18 @@ declare class WickChart extends HTMLElementBase {
         rawHi: number;
     };
     static get observedAttributes(): string[];
+    /**
+     * Shared ChartWorkerPool for the worker compute path (set by importing
+     * 'wickchart/worker'; null — everything sync — until then).
+     * @type {object|null}
+     */
+    static _workerPool: object | null;
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
+    /** (Re)arm the devicePixelRatio watcher for the current ratio. */
+    _watchDpr(): void;
+    _unwatchDpr(): void;
     attributeChangedCallback(name: any, _old: any, val: any): void;
     /** Indicator registry (module scope — shared with the legacy alias tag). */
     static _registry(): Map<string, {
@@ -278,7 +318,7 @@ declare class WickChart extends HTMLElementBase {
             smooth?: undefined;
             period?: undefined;
         };
-        compute: (bars: any) => number[];
+        compute: (bars: any, p: any) => number[];
         color?: undefined;
         guides?: undefined;
         range?: undefined;
@@ -493,7 +533,8 @@ declare class WickChart extends HTMLElementBase {
      */
     /** @param {import('./core.js').IndicatorDef} def */
     static registerIndicator(name: any, def: import('./core.js').IndicatorDef): void;
-    /** The custom element class (also exported implicitly for users). */
+    /** The tag this class registers as. (<hab-chart> is a deprecated alias
+     *  registered from the HabChart subclass, not this name.) */
     static get elementName(): string;
     get data(): any[];
     /**
@@ -708,6 +749,24 @@ declare class WickChart extends HTMLElementBase {
     /** Check alerts against an incoming bar (prev close → new close).
      *  Scripted (`when`) alerts evaluate their predicate series, cached per
      *  data version, and fire on the false→true edge. */
+    /**
+     * Index of the newest bar known to be final: any bar with a newer bar
+     * behind it, plus the front bar when the feed flagged it `closed: true`
+     * (Binance's `k.x`). -1 when nothing has closed yet.
+     */
+    _lastClosedIndex(): number;
+    /** Re-baseline the closed-bar cursor without firing anything. */
+    _syncClosedIdx(): void;
+    /**
+     * Resolve an alert's evaluation mode: an explicit 'close' / 'live' on the
+     * alert wins, otherwise the chart-level `alert-evaluate` default (itself
+     * 'live', so 1.x behaviour is unchanged unless asked for).
+     * @param {string|undefined} v
+     * @returns {'live'|'close'}
+     */
+    _evalMode(v: string | undefined): 'live' | 'close';
+    /** Dispatch one alert, retiring it when it was a `once` alert. */
+    _fireAlert(alert: any, detail: any): void;
     _checkAlerts(prevClose: any, bar: any): void;
     /** Cached boolean series for a scripted alert's predicate (per data version). */
     _predicateCache(alert: any): any;
@@ -720,14 +779,18 @@ declare class WickChart extends HTMLElementBase {
     get indicators(): any;
     set indicators(v: any);
     static _MAX_SP: number;
+    /** Hold this long on a touchscreen to open the crosshair (ms). */
+    static _PRESS_MS: number;
+    /** Finger travel that cancels the press and makes it a pan (px). */
+    static _PRESS_SLOP: number;
     /**
      * Lowest allowed px/bar: either 0.35, or whatever fits the entire
      * dataset on screen — so any history can be zoomed out fully.
      */
     _minSpacing(): number;
-    static _timeToMs(t: any): any;
+    static _timeToMs(t: any): number;
     static _normBar(b: any): {
-        time: any;
+        time: number;
         open: any;
         high: any;
         low: any;
@@ -755,6 +818,33 @@ declare class WickChart extends HTMLElementBase {
     _volShadeCache(): any;
     /** Compute (and cache per data version) an indicator entry's series. */
     _indicatorSeries(entry: any): any;
+    /**
+     * After a live stream tick (append or forming-bar replace), patch every
+     * online-capable series by recomputing a bounded tail with the same
+     * batch definition — O(warm-up) instead of a full-history recompute per
+     * indicator per tick. Bases are seeded by the sync or worker path; bulk
+     * loads (epoch changes) reseed automatically.
+     */
+    _onlineTick(): void;
+    /** Recompute the last K bars of one series in place (K = max(400,
+     *  10×period), clamped to the data). False when the series and data
+     *  lengths can't line up — the caller drops the base and reseeds. */
+    _patchSeriesTail(res: any, entry: any, d: any): boolean;
+    /** Remember a fresh series as the base for incremental tick updates
+     *  (online-capable builtins only). */
+    _seedOnline(k: any, entry: any, res: any): void;
+    /** Bar count from which the worker path engages (below it, sync wins). */
+    _workerCols(): {
+        time: Float64Array<ArrayBuffer>;
+        open: Float64Array<ArrayBuffer>;
+        high: Float64Array<ArrayBuffer>;
+        low: Float64Array<ArrayBuffer>;
+        close: Float64Array<ArrayBuffer>;
+        volume: Float64Array<ArrayBuffer>;
+    };
+    /** Kick an off-thread compute for one indicator (idempotent per epoch). */
+    _workerCompute(pool: any, entry: any, k: any): void;
+    _workerArrived(k: any, epoch: any, res: any, entry: any): void;
     /** Resolve a line color: #hex / rgb() / CSS name / palette key ('rsi', 'up', …) / cycle.
      *  Untrusted values (URL/attribute-sourced) are validated — never interpolated raw. */
     _lineColor(entry: any, line: any, pal: any, cycleIdx: any): any;
@@ -778,6 +868,8 @@ declare class WickChart extends HTMLElementBase {
      * the walk to those bars — used at deep zoom where bars are aggregated
      * into pixel columns (keeps this O(screen) instead of O(visible bars)).
      */
+    /** An instant shifted into the chart's display zone, for the formatters. */
+    _zt(t: any): any;
     _timeTicks(i0: any, i1: any, sampleIdx: any): any[];
     _render(): void;
     _pill(x: any, y: any, text: any, bg: any, fg: any, align: string, widthOverride: any): void;
@@ -791,7 +883,13 @@ declare class WickChart extends HTMLElementBase {
      * layer then receives that pointer's move/up/cancel events (plus a
      * 'cancel' on Escape) and the chart suppresses its own pan/measure/brush
      * for the duration.
-     * @param {{id?: string, draw: Function, onPointer?: Function}} layer
+     *
+     * A layer may also declare `insetBottom` (px, 0..160): the largest
+     * declared inset reserves a docked strip at the very bottom of the
+     * canvas — all chart content (panes + time axis) shrinks above it and
+     * the strip is handed to layers as `api.layout.dock = { y0, h }`
+     * (used by the wickchart-navigator plugin).
+     * @param {{id?: string, draw: Function, onPointer?: Function, insetBottom?: number}} layer
      * @returns {object|null} the normalized layer handle (with `id`), or null
      *   if the layer was rejected (no draw fn, or 16 layers already added)
      */
@@ -799,6 +897,7 @@ declare class WickChart extends HTMLElementBase {
         id?: string;
         draw: Function;
         onPointer?: Function;
+        insetBottom?: number;
     }): object | null;
     /**
      * Remove a layer added via addLayer (pass the returned handle or its id).
@@ -810,6 +909,11 @@ declare class WickChart extends HTMLElementBase {
     requestDraw(): void;
     /** Paint every registered layer. Called from _render with live state. */
     _drawLayers(ctx: any, pal: any, ly: any, d: any): void;
+    /**
+     * Bottom space reserved by plugin layers: the largest declared
+     * `insetBottom` (px, clamped 0..160 at addLayer time), or 0.
+     */
+    _dockInset(): number;
     /** Ask layers, in order, whether one claims this pointerdown. */
     _layerHit(e: any, pt: any): any;
     /** Deliver a pointer event to a claiming layer; never throws outward. */
@@ -857,6 +961,21 @@ declare class WickChart extends HTMLElementBase {
         x: number;
         y: number;
     };
+    /**
+     * Put the crosshair on the bar under a point and announce it. Shared by
+     * mouse hover, keyboard walking and the touch scrub gesture.
+     */
+    _hoverAt(pt: any): void;
+    /**
+     * Start the long-press timer for a touch. A touchscreen has no hover, so
+     * without this there is no way to read a bar's values on a phone: a tap
+     * selects, a drag pans, and the legend never leaves the last candle.
+     * Holding still opens the crosshair; moving first cancels and pans.
+     */
+    _armPress(pointerId: any, pt: any): void;
+    _disarmPress(): void;
+    /** Leave scrub mode and put the crosshair away. */
+    _endScrub(): void;
     _pointerDown(e: any): void;
     _pointerMove(e: any): void;
     _pointerUp(e: any): void;

package/types/wick-feed.d.ts

@@ -25,7 +25,26 @@ declare class WickFeed extends HTMLElementBase {
     _binance(gen: any, chart: any, sym: any, tfId: any, limit: any, live: any): Promise<void>;
     _pollBinance(gen: any, chart: any, sym: any, tfId: any): void;
     _degrade(gen: any, chart: any, sym: any, tfId: any, limit: any, live: any, err: any): void;
+    /**
+     * Wrap chart.update for aggregated bars: the chart keys bars by timestamp,
+     * and two groups can close inside the same millisecond, so emitted times
+     * are nudged +1ms to stay strictly increasing (keeps the one-bar-per-
+     * timestamp integrity invariant; display-only, values are untouched).
+     */
+    _aggEmit(gen: any, chart: any): (bar: any) => void;
+    /** Seed + stream one aggregator onto the chart (shared by all sources). */
+    _aggAttach(gen: any, chart: any, res: any, bars: any, limit: any, status: any): {
+        emit: (bar: any) => void;
+        aggregator: any;
+        /** Push one print through; emits the closed bar, then the forming one. */
+        push(t: any): void;
+    };
+    _syntheticTrades(gen: any, chart: any, key: any, agg: any, limit: any, live: any, status?: string): void;
+    _binanceTrades(gen: any, chart: any, sym: any, agg: any, limit: any, live: any): Promise<void>;
+    _pollBinanceTrades(gen: any, chart: any, sym: any, handle: any, fromId: any, agg: any, limit: any, live: any): void;
+    _restTrades(gen: any, chart: any, url: any, agg: any, limit: any, live: any): Promise<void>;
     _rest(gen: any, chart: any, url: any, limit: any, live: any): Promise<void>;
 }
 export default WickFeed;
 export { WickFeed };
+export { parseAggregate, TickBarAggregator, aggregateTrades, normalizeTrades, genSyntheticTrades, makeSynthTradeStream, } from './feeds.js';

package/types/worker-core.d.ts

@@ -0,0 +1,11 @@
+/** Rebuild the bar-object tape from a columnar snapshot (worker-side only —
+ *  this cost never touches the main thread). */
+export declare function barsFromCols(cols: any): any[];
+/**
+ * Create a worker-core state + dispatcher.
+ * @returns {{sessions: Map, handle(message: object): object}} the reply object
+ */
+export declare function createWorkerCore(): {
+    sessions: Map<any, any>;
+    handle(message: object): object;
+};

package/types/worker.d.ts

@@ -0,0 +1,36 @@
+import { WickChart } from './wick-chart.js';
+export { WickChart };
+/**
+ * A single-Worker task runner. The factory is injectable so tests can drive
+ * the protocol with a fake Worker; the default spawns the module worker
+ * sitting next to this file.
+ */
+export declare class ChartWorkerPool {
+    _factory: () => Worker;
+    available: boolean;
+    _worker: Worker;
+    _seq: number;
+    _pending: Map<any, any>;
+    /** @param {() => Worker} [factory] */
+    constructor(factory?: () => Worker);
+    /**
+     * Post a task; resolves with the reply's `res`, rejects on failure or
+     * worker death (a `stale` rejection means: resend the epoch data first).
+     * @param {object} msg task message without the id
+     * @returns {Promise<any>}
+     */
+    run(msg: object): Promise<any>;
+    _spawn(): void;
+    /** Reject everything in flight and drop the worker; the next run() respawns
+     *  — a transient worker crash must not permanently kill the mode. */
+    _die(): void;
+    /** Shut the pool down for good (in-flight tasks reject). */
+    terminate(): void;
+}
+/** The page-wide pool (created on first use). */
+export declare function getSharedPool(): any;
+/**
+ * Point the chart class at a pool (or null to disable the worker path).
+ * @param {ChartWorkerPool|null} pool
+ */
+export declare function setChartWorkerPool(pool: ChartWorkerPool | null): ChartWorkerPool;