wickchart 1.0.0 → 1.3.0

package/types/wick-chart.d.ts

@@ -1,3 +1,4 @@
+import { PresenceTracker } from './core.js';
 declare const HTMLElementBase: {
     new (): {};
 };
@@ -108,6 +109,10 @@ declare class WickChart extends HTMLElementBase {
         at: number;
     };
     _ghostTimer: number;
+    _coviewLabel: any;
+    _presence: PresenceTracker;
+    _coviewBeat: number;
+    _coviewViewLast: number;
     _sonify: boolean;
     _actx: any;
     _lastToneIdx: number;
@@ -120,6 +125,36 @@ declare class WickChart extends HTMLElementBase {
         done: boolean;
     };
     _measuring: boolean;
+    _walkTimer: number;
+    _storyToken: number;
+    _story: object[];
+    _brush: boolean;
+    _brushSel: {
+        i0: number;
+        i1: number;
+        stats: {
+            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;
+        };
+    };
+    _brushDrag: {
+        i0: any;
+        i1: any;
+    };
     _ind: {
         overlays: any[];
         panes: any[];
@@ -142,6 +177,30 @@ 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;
+    };
+    _riskPlan: {
+        entry: number;
+        stop: number;
+        risk: number;
+        direction: 'long' | 'short';
+        levels: {
+            k: number;
+            price: number;
+        }[];
+        maxK: number;
+        label: string;
+    };
     _onResize: () => void;
     _onPointerDown: (e: any) => void;
     _onPointerMove: (e: any) => void;
@@ -349,23 +408,148 @@ 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;
+    /**
+     * Risk plan: an R-multiple grid anchored at entry/stop. 1R = |entry −
+     * stop| (the risk unit); reward lines are drawn at kR beyond the entry
+     * with the risk/reward zones shaded, so sizing and take-profit choices
+     * read directly off the chart.
+     *
+     *   chart.setRiskPlan({ entry: 64500, stop: 63800, multiples: [1, 2, 3] });
+     *   chart.setRiskPlan({ entry: 64500, stop: 63800, targets: [65900, 67300] });
+     *
+     * Direction is derived (stop below entry ⇒ long). Targets convert to
+     * their R multiple; `multiples` win when both are given. Invalid specs
+     * clear the plan (replace semantics, like setScenario); excluded from
+     * getState/setState — it is app state, not chart state.
+     * @param {object} spec
+     * @returns {object|null} the normalized plan, or null when invalid
+     */
+    setRiskPlan(spec: object): object | null;
+    clearRiskPlan(): void;
+    /** @returns {object|null} a copy of the active risk plan */
+    get riskPlan(): 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;
@@ -465,11 +649,126 @@ declare class WickChart extends HTMLElementBase {
     _emitCrosshair(hover: any): void;
     /** Join/leave the co-view channel named by the `co-view` attribute. */
     _setupCoView(): void;
+    /** Broadcast our visible range for presence; throttled unless forced. */
+    _coviewSendView(force: any): void;
     _coviewSend(msg: any): void;
     _onCoMessage(m: any): void;
     /** Dispatch `wick:name` (canonical) plus the deprecated `hab:name` alias,
      *  so 0.x listeners keep working until 2.0. */
     _fire(name: any, detail: any): void;
+    /**
+     * Live co-view peers: who else is in the room and the time window each
+     * one is looking at — [{ id, name, range: {from, to}, at }], oldest
+     * sighting first. Peers fade out ~12 s after their last sighting.
+     * @returns {object[]}
+     */
+    getPeers(): object[];
+    /**
+     * Narrated timeline for a window (default: the visible range) — pivot
+     * highs/lows, volume spikes, gaps, RSI divergences plus derived legs
+     * ("+12.4% over 38 bars"), sorted by index. Pure data, perfect for
+     * caption UIs or the walk player.
+     *   chart.narrate();                        // visible range
+     *   chart.narrate({ from, to });            // times in ms (s accepted)
+     * @param {{from?: number, to?: number}} [range]
+     * @returns {{i: number, time: number, type: string, side: string, note: string,
+     *            legPct?: number, legBars?: number}[]}
+     */
+    narrate(range?: {
+        from?: number;
+        to?: number;
+    }): {
+        i: number;
+        time: number;
+        type: string;
+        side: string;
+        note: string;
+        legPct?: number;
+        legBars?: number;
+    }[];
+    /**
+     * Walk the chart through history like a story: the viewport slides
+     * from `from` to `to` while `wick:walk` events announce every step and
+     * the narrator's events (spikes, gaps, pivots, legs) as they're crossed.
+     * Any user interaction — pointer, wheel, keys, double-click — stops it.
+     *   chart.walk({ from: 0, to: 500, speed: 120, step: 10 });
+     *   chart.addEventListener('wick:walk', (e) => showCaption(e.detail));
+     *   // detail: { phase: 'step'|'end'|'stop', index, events: [...], from, to }
+     * @param {{from?: number, to?: number, speed?: number, step?: number}} [opts]
+     *        from/to are bar indices (default: last ~500 bars → the end)
+     * @returns {boolean} true when the walk started
+     */
+    walk(opts?: {
+        from?: number;
+        to?: number;
+        speed?: number;
+        step?: number;
+    }): boolean;
+    /**
+     * Stop the running walk (if any). Fires a final `wick:walk`
+     * { phase: 'stop' } unless called internally.
+     */
+    stopWalk(silent: any): void;
+    /**
+     * Commit a brush selection over [i0, i1]: stores it (draws the band
+     * and delta chip) and fires `wick:brush` with the range statistics.
+     * @param {number} i0 first index
+     * @param {number} i1 last index
+     */
+    _brushFinish(i0: number, i1: number): void;
+    /** Clear the committed brush selection (if any). Escape does the same. */
+    clearBrush(): void;
+    /** @returns {object|null} the committed selection { i0, i1, stats } */
+    get brushSelection(): object | null;
+    /**
+     * Capture the current chart state as a story scene: view, series type,
+     * indicators, overlays, scenario and risk plan, plus a title/note.
+     * Build guided tours by capturing several and playing them back.
+     *   const story = [
+     *     chart.captureScene('Overview', 'The full picture'),
+     *     { title: 'The breakout', range: { from, to }, indicators: 'sma:20' },
+     *   ];
+     *   chart.playStory(story);
+     * @param {string} [title]
+     * @param {string} [note]
+     * @returns {object} scene (plain data — snapshot of the moment)
+     */
+    captureScene(title?: string, note?: string): object;
+    /** @returns {object[]|null} a copy of the last played story */
+    getStory(): object[] | null;
+    /**
+     * Play a story: each scene applies its state (type / indicators /
+     * overlays / scenario / risk plan — set or clear), the camera eases
+     * to its range, then holds for its dwell. `wick:story` events narrate:
+     *   { phase: 'scene' | 'end' | 'stop', index, total, scene, title, note }
+     * Any user interaction — pointer, wheel, keys, double-click — stops it.
+     * @param {object[]} story scenes (invalid entries dropped, max 20)
+     * @param {{dwell?: number, panMs?: number, loop?: boolean}} [opts]
+     *        panMs clamps 100–5000 (default 900); loop replays forever
+     * @returns {boolean} true when playback started
+     */
+    playStory(story: object[], opts?: {
+        dwell?: number;
+        panMs?: number;
+        loop?: boolean;
+    }): boolean;
+    /**
+     * Stop story playback (if running). Fires a final `wick:story`
+     * { phase: 'stop' } unless called internally.
+     */
+    stopStory(silent: any): void;
+    /** Apply a scene's state (only the fields it carries). */
+    _applyScene(sc: any): void;
+    /** Map a scene's time range to bar indices (null when not applicable). */
+    _sceneTarget(sc: any): {
+        i0: number;
+        i1: number;
+    };
+    /** Ease the viewport to { i0, i1 } over `ms`; resolves early if the
+     *  token changes (superseded or stopped). rAF when available. */
+    _storyTween(target: any, ms: any, token: any): Promise<any>;
+    /** Interrupt narrated playback (walk / story) on user input. */
+    _stopPlayback(): void;
     _emitRange(): void;
 }
 export default WickChart;