wickchart 1.0.0 → 1.3.0

package/types/core.d.ts

@@ -585,6 +585,28 @@ export declare function checkAlertCross(alert: {
     price: number;
     direction?: 'above' | 'below' | 'cross';
 }, prevPrice: number, price: number): boolean;
+/**
+ * Boolean truth series for a WickScript predicate: any numeric expression
+ * where nonzero & finite counts as true (NaN / 0 / ±Infinity → false).
+ * Powers scripted alerts — `addAlert({ when: 'crossup(close, sma(close,50))' })`.
+ * @param {object|string} compiled compiled predicate (or raw source)
+ * @param {Bar[]} bars
+ * @returns {boolean[]}
+ */
+export declare function predicateTrueSeries(compiled: object | string, bars: Bar[]): boolean[];
+/**
+ * Edge-triggered step for a scripted alert. `armed` starts true; a rising
+ * edge (false → true) fires once and disarms; a true → false transition
+ * re-arms, so `once: false` alerts can fire again on the next edge while
+ * `once: true` alerts are removed after their first fire.
+ * @param {boolean} armed
+ * @param {boolean} curTrue
+ * @returns {{ fire: boolean, armed: boolean }}
+ */
+export declare function scriptAlertStep(armed: boolean, curTrue: boolean): {
+    fire: boolean;
+    armed: boolean;
+};
 /**
  * Statistics over a visible slice of bars.
  * @param {Bar[]} bars
@@ -648,6 +670,239 @@ export declare function parseVolShading(val: string | null | undefined): {
     p2: number;
     period: number;
 };
+/**
+ * Index of the last bar whose time is <= `t` (binary search). Clamps to
+ * [0, n-1]: a time before the first bar → 0, past the last bar → n-1.
+ * Empty bars or a non-numeric time → null.
+ * @param {object[]} bars normalized bar objects
+ * @param {number} t timestamp in ms or s
+ * @returns {number|null}
+ */
+export declare function barIndexForTime(bars: object[], t: number): number | null;
+/**
+ * Validate & normalize server-side overlay definitions. Overlays are data
+ * from an API, so invalid entries are silently dropped — never thrown.
+ *
+ * zone:  { type:'zone', from?: time|null, to?: time|null, priceFrom, priceTo,
+ *          color?, alpha?, border?, label?, id? } — a time×price rectangle.
+ *          `from`/`to` omitted (or null) anchor to the left/right chart edge;
+ *          a zone with no `to` extends into future space past the last bar.
+ * level: { type:'level', price, from?, to?, color?, width?, dash?, label?, id? }
+ *          — a horizontal price line, full width by default.
+ *
+ * Colors go through safeColor(); `alpha` clamps to [0.02, 0.8] (default 0.22).
+ * @param {any} list
+ * @returns {object[]} normalized overlays (possibly empty)
+ */
+export declare function normalizeOverlays(list: any): object[];
+/**
+ * Resolve an overlay color against the active palette: 'up'/'down'/'accent'
+ * map to theme colors, anything else passes through safeColor(), and invalid
+ * or missing values fall back to the accent color.
+ * @param {any} raw
+ * @param {object} pal active theme palette
+ * @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.
+ *
+ *   { path: [64000, 65500, {price: 68000}],  // future bars 1..N
+ *     horizon: 48,          // alternative/additional: cone-only projection
+ *     cone: true,           // σ-bands from realized vol (default true)
+ *     levels: [1, 2],       // σ multipliers (default [1, 2])
+ *     color?, label? }      // palette keys up|down|accent or safe CSS colors
+ *
+ * @param {any} spec
+ * @returns {null|{path: {h:number, price:number}[], horizon: number,
+ *            cone: boolean, levels: number[], color: string|null, label: string}}
+ */
+export declare function normalizeScenario(spec: any): null | {
+    path: {
+        h: number;
+        price: number;
+    }[];
+    horizon: number;
+    cone: boolean;
+    levels: number[];
+    color: string | null;
+    label: string;
+};
+/**
+ * Validate a risk plan: entry + stop define 1R (the risk unit per trade);
+ * reward levels are drawn at R multiples beyond the entry. Invalid input
+ * is dropped, never thrown — same contract as setOverlays/setScenario.
+ *
+ *   { entry: 64500, stop: 63800,        // stop < entry ⇒ long; else short
+ *     multiples: [1, 2, 3],             // R-multiple levels (default [1,2,3])
+ *     targets: [65900, 67300],          // alternative: explicit prices → kR
+ *     label: 'breakout plan' }          // ≤ 40 chars
+ *
+ * Explicit `targets` are converted to their (signed) R multiple; levels on
+ * the wrong side of the entry (negative or ~zero R) are dropped. `multiples`
+ * win when both are given. At most 8 levels, each ≤ 20R.
+ *
+ * @param {any} spec
+ * @returns {null|{entry: number, stop: number, risk: number,
+ *            direction: 'long'|'short', levels: {k: number, price: number}[],
+ *            maxK: number, label: string}}
+ */
+export declare function normalizeRiskPlan(spec: any): null | {
+    entry: number;
+    stop: number;
+    risk: number;
+    direction: 'long' | 'short';
+    levels: {
+        k: number;
+        price: number;
+    }[];
+    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
+ * overlay and its `wick:brush` event.
+ *
+ * @param {Bar[]} bars full dataset
+ * @param {number} i0 first selected index
+ * @param {number} i1 last selected index
+ * @returns {null|{bars: number, from: {index: number, time: number},
+ *          to: {index: number, time: number}, firstOpen: number,
+ *          lastClose: number, delta: number, deltaPct: number,
+ *          high: number, low: number, volume: number}}
+ */
+export declare function brushStats(bars: Bar[], i0: number, i1: number): null | {
+    bars: number;
+    from: {
+        index: number;
+        time: number;
+    };
+    to: {
+        index: number;
+        time: number;
+    };
+    firstOpen: number;
+    lastClose: number;
+    delta: number;
+    deltaPct: number;
+    high: number;
+    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
@@ -677,3 +932,110 @@ 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/react-core.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Map an event shorthand to the dispatched event name.
+ * "range" / "wick:range" → "wick:range" (the 0.x "hab:" prefix is no longer emitted).
+ * @param {string} name
+ * @returns {string}
+ */
+export declare const toWickEventName: (name: string) => string;
+/**
+ * camelCase prop name → kebab-case attribute name ("volShading" → "vol-shading").
+ * @param {string} key
+ * @returns {string}
+ */
+export declare const toAttrName: (key: string) => string;
+/**
+ * Split React props into chart attrs / event handlers / DOM passthrough /
+ * the data array / the overlays array.
+ * @param {object} props
+ * @returns {{ attrs: object, events: Record<string, Function>, dom: object, data: any, overlays: any }}
+ */
+export declare function splitChartProps(props: object): {
+    attrs: object;
+    events: Record<string, Function>;
+    dom: object;
+    data: any;
+    overlays: any;
+};
+/**
+ * Apply split props to a chart element. Every write is guarded so re-running
+ * with identical values is a no-op (attributes compared as strings, `data`
+ * and `overlays` compared by identity — passing a fresh array is what
+ * triggers a redraw).
+ * @param {HTMLElement} el
+ * @param {{ attrs?: object, data?: any, overlays?: any }} split
+ */
+export declare function applyChartProps(el: HTMLElement, split: {
+    attrs?: object;
+    data?: any;
+    overlays?: any;
+}): void;
+/**
+ * Full control hook: renders nothing — attach the returned ref to your own
+ * <wick-chart> element and pass the same options you would give the component.
+ *
+ *   const { ref, chart } = useWickChart({ data: bars, indicators: 'sma:20', onRange });
+ *   return <wick-chart ref={ref} style={{ height: 420 }} />;
+ *   // chart.getDataWindow() etc. once mounted
+ *
+ * @param {object} [options] any <wick-chart> attribute, plus `data`, `events`
+ *   and `onXxx`-style handlers (see splitChartProps).
+ * @returns {{ ref: (node: any) => void, chart: any }} `chart` is the element
+ *   instance (or null before mount) for the imperative API.
+ */
+export declare function useWickChart(options?: object): {
+    ref: (node: any) => void;
+    chart: any;
+};
+/**
+ * Drop-in React component for <wick-chart>. Attributes ride through
+ * createElement (so they exist at first paint and in SSR output) while the
+ * hook keeps them in sync on updates; `data` and event handlers never touch
+ * React's prop pipeline. Works the same on React 16.8 → 19.
+ */
+export declare const WickChart: import("react").ForwardRefExoticComponent<import("react").RefAttributes<any>>;
+export default WickChart;

package/types/react.d.ts

@@ -0,0 +1,3 @@
+import './wick-chart.js';
+export { WickChart, useWickChart, splitChartProps, applyChartProps, toWickEventName, toAttrName, } from './react-core.js';
+export { default } from './react-core.js';