wickchart 1.0.0 → 1.2.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,83 @@ 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;
+};
 export declare const tfLabelOf: (dtMs: any) => string;
 /**
  * Compact, LLM-friendly summary of a bar window: structured fields plus a
@@ -677,3 +776,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';

package/types/wick-chart.d.ts

@@ -142,6 +142,18 @@ declare class WickChart extends HTMLElementBase {
     _positions: any[];
     _alerts: any[];
     _seq: number;
+    _overlays: any[];
+    _scenario: {
+        path: {
+            h: number;
+            price: number;
+        }[];
+        horizon: number;
+        cone: boolean;
+        levels: number[];
+        color: string | null;
+        label: string;
+    };
     _onResize: () => void;
     _onPointerDown: (e: any) => void;
     _onPointerMove: (e: any) => void;
@@ -349,23 +361,128 @@ declare class WickChart extends HTMLElementBase {
     removePosition(id: any): void;
     clearPositions(): void;
     /**
-     * Price alert. Fires `wick:alert` ({id, price, bar}) on an edge crossing
-     * (plus the deprecated `hab:alert` alias)
-     * during streaming updates.
-     * @param {{id?: string, price: number, direction?: 'above'|'below'|'cross',
-     *          once?: boolean}} alert
-     * @returns {string|null} the alert id
+     * Price or scripted alert. Price alerts fire `wick:alert`
+     * ({id, price, bar}) on an edge crossing; scripted alerts evaluate a
+     * WickScript predicate (`when`) on every streamed bar and fire on its
+     * false→true edge — e.g. `when: 'crossup(rsi(close,14), 30)'` or
+     * `when: 'volume > sma(volume,20) * 3'`. Scripted events carry the
+     * triggering close as `price` plus the `when` source (deprecated
+     * `hab:alert` alias still dispatched).
+     * @param {{id?: string, price?: number, direction?: 'above'|'below'|'cross',
+     *          when?: string, once?: boolean}} alert
+     * @returns {string|null} the alert id (null when no valid price/when,
+     *          or the predicate fails to compile)
      */
     addAlert(alert: {
         id?: string;
-        price: number;
+        price?: number;
         direction?: 'above' | 'below' | 'cross';
+        when?: string;
         once?: boolean;
     }): string | null;
     removeAlert(id: any): void;
     clearAlerts(): void;
-    /** Check alerts against an incoming bar (prev close → new close). */
+    /**
+     * Server-side overlays: zones & levels anchored in time × price — e.g.
+     * supply/demand zones from an analysis API. Zones with no `to` extend
+     * into future space past the last bar, like TradingView drawings.
+     *
+     *   zone:  { type:'zone', from?:ms, to?:ms|null, priceFrom, priceTo,
+     *            color?, alpha?, border?, label?, id? }
+     *   level: { type:'level', price, from?, to?, color?, width?, dash?,
+     *            label?, id? }
+     *
+     * Invalid entries are dropped, never thrown. Colors accept hex/rgb()/CSS
+     * names plus the palette keys 'up' | 'down' | 'accent'.
+     * @param {object[]} list
+     * @returns {string[]} applied overlay ids
+     */
+    setOverlays(list: object[]): string[];
+    /** @returns {object[]} a copy of the current overlays */
+    get overlays(): object[];
+    /**
+     * Add or replace (upsert, by id) a single overlay.
+     * @returns {string|null} the overlay id, or null if invalid
+     */
+    addOverlay(ov: any): string | null;
+    removeOverlay(id: any): void;
+    clearOverlays(): void;
+    /**
+     * Scenario projection into future space: a ghost path of future prices
+     * plus optional σ-bands (vol cone) from realized volatility.
+     *
+     *   chart.setScenario({ path: [64000, 65500, 68000], label: 'bull case' });
+     *   chart.setScenario({ horizon: 48, cone: true });   // cone-only
+     *
+     * The path is an array of prices (or {price} objects) for future bars
+     * 1..N; horizon defaults to the path length (1–500). `cone` (default
+     * true) draws ±levels·σ bands widening with √h from the current realized
+     * vol; `color` accepts up|down|accent or safe CSS colors. Setting a
+     * scenario reserves future space on the right; analysis data — excluded
+     * from getState/setState.
+     * @param {object} spec
+     * @returns {object|null} the normalized scenario, or null when invalid
+     */
+    setScenario(spec: object): object | null;
+    clearScenario(): void;
+    /** @returns {object|null} a copy of the active scenario */
+    get scenario(): object | null;
+    /** σ-cone for the active scenario, cached per data version. */
+    _scenarioConeCache(): any;
+    /** Tool manifest for LLM control — JSON-safe copy of AI_TOOLS. */
+    aiTools(): any;
+    /** System prompt for agent control — paste into any LLM alongside aiTools(). */
+    aiPrompt(): string;
+    /** Grounding context for a model: current state + visible-window summary. */
+    aiContext(): {
+        state: import("./core.js").ChartState;
+        window: object;
+    };
+    /**
+     * Apply a list of {tool, args} ops (typically LLM output) through the
+     * validated dispatcher in core. Never throws — each op resolves
+     * {ok, tool, result} or {ok: false, tool, error} so an agent can
+     * self-correct.
+     * @param {any} ops
+     * @returns {Array<object>}
+     */
+    applyAI(ops: any): Array<object>;
+    /**
+     * Ask an AI to operate the chart. Builds the payload {system,
+     * instruction, chart, tools}; with a `run` async function (your model
+     * call — the chart itself never touches the network), applies the
+     * returned ops and resolves {payload, ops, results}. Without `run`,
+     * returns the payload for manual wiring — send it anywhere, then call
+     * chart.applyAI(ops) with the model's answer.
+     *
+     *   const { results } = await chart.ask('add RSI and mark the demand zone', {
+     *     run: async (payload) => (await callMyLLM(payload)).ops,
+     *   });
+     *
+     * @param {string} instruction natural-language request
+     * @param {{run?: (payload: object) => Promise<any>}} [opts]
+     */
+    ask(instruction: string, opts?: {
+        run?: (payload: object) => Promise<any>;
+    }): Promise<{
+        payload: {
+            system: string;
+            instruction: string;
+            chart: {
+                state: import("./core.js").ChartState;
+                window: object;
+            };
+            tools: any;
+        };
+        ops: any;
+        results: object[];
+    }>;
+    /** 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. */
     _checkAlerts(prevClose: any, bar: any): void;
+    /** Cached boolean series for a scripted alert's predicate (per data version). */
+    _predicateCache(alert: any): any;
     get theme(): string;
     set theme(v: string);
     get type(): string;