wickchart 1.2.0 → 1.4.0

package/types/core.d.ts

@@ -747,6 +747,162 @@ export declare function normalizeScenario(spec: any): null | {
     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

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[];
@@ -137,6 +172,12 @@ declare class WickChart extends HTMLElementBase {
         idxAtMid: number;
         midX: number;
     };
+    _layers: any[];
+    _layerClaim: {
+        layer: any;
+        pointerId: any;
+    };
+    _layerSeq: number;
     _loadingMore: boolean;
     _noMore: boolean;
     _positions: any[];
@@ -154,6 +195,18 @@ declare class WickChart extends HTMLElementBase {
         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;
@@ -427,6 +480,26 @@ declare class WickChart extends HTMLElementBase {
     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. */
@@ -556,6 +629,75 @@ declare class WickChart extends HTMLElementBase {
     _updateLegend(): void;
     /** Position P&L chips (top-right HTML overlay). */
     _updateHud(): void;
+    /**
+     * Register a plugin layer. `layer.draw(api)` runs on every render, above
+     * chart content and under the crosshair; `layer.onPointer(pev)` is asked
+     * first on pointerdown and claims the gesture by returning true — the
+     * 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
+     * @returns {object|null} the normalized layer handle (with `id`), or null
+     *   if the layer was rejected (no draw fn, or 16 layers already added)
+     */
+    addLayer(layer: {
+        id?: string;
+        draw: Function;
+        onPointer?: Function;
+    }): object | null;
+    /**
+     * Remove a layer added via addLayer (pass the returned handle or its id).
+     * @param {object|string} idOrLayer
+     * @returns {boolean} true if a layer was removed
+     */
+    removeLayer(idOrLayer: object | string): boolean;
+    /** Ask for a repaint on the next frame (interactive layers call this). */
+    requestDraw(): void;
+    /** Paint every registered layer. Called from _render with live state. */
+    _drawLayers(ctx: any, pal: any, ly: any, d: any): void;
+    /** 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. */
+    _routeLayer(layer: any, e: any, pt: any, type: any): void;
+    _layerPointerEvent(e: any, pt: any, type: any): {
+        type: any;
+        x: any;
+        y: any;
+        pointerId: any;
+        button: any;
+        shiftKey: boolean;
+        ctrlKey: boolean;
+        altKey: boolean;
+        metaKey: boolean;
+    };
+    /**
+     * x-pixel for a bar time (ms or s, auto-detected). Extrapolates past the
+     * last bar into future space using the median bar interval, so layers can
+     * anchor trendlines to tomorrow, not just to history.
+     * @param {number} time
+     * @returns {number|null}
+     */
+    timeToX(time: number): number | null;
+    /**
+     * Bar time (ms) at an x-pixel — the inverse of timeToX, interpolating
+     * between bars and extrapolating beyond both data edges.
+     * @param {number} x
+     * @returns {number|null}
+     */
+    xToTime(x: number): number | null;
+    /**
+     * y-pixel for a price in the main pane (current scale; log-aware).
+     * Unclamped — values off-screen still map, layers decide how to clip.
+     * @param {number} price
+     * @returns {number|null}
+     */
+    priceToY(price: number): number | null;
+    /**
+     * Price at a y-pixel in the main pane — the inverse of priceToY.
+     * @param {number} y
+     * @returns {number|null}
+     */
+    yToPrice(y: number): number | null;
     _localPoint(e: any): {
         x: number;
         y: number;
@@ -582,11 +724,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;