wickchart 1.0.0 → 1.2.0

package/src/wick-chart.js

@@ -28,7 +28,10 @@ import {
   SERIES_TYPES, calcHeikinAshi, buildColumns, computeVolumeProfile,
   calcRSI, detectAnnotations, priceToFreq,
   calcRealizedVol, volRegimeBands, percentileOfSorted, parseVolShading,
-  windowSummary,
+  windowSummary, normalizeOverlays, barIndexForTime, resolveOverlayColor,
+  compileScript, predicateTrueSeries, scriptAlertStep,
+  AI_TOOLS, aiPromptText, applyChartOps,
+  calcVolCone, normalizeScenario,
 } from './core.js';
 
 /* ------------------------------------------------------------------ *
@@ -45,7 +48,7 @@ const HTMLElementBase = typeof HTMLElement !== 'undefined' ? HTMLElement : class
 
 class WickChart extends HTMLElementBase {
     static get observedAttributes() {
-      return ['theme', 'type', 'log', 'auto', 'indicators', 'precision', 'label', 'stats', 'profile', 'annotations', 'volshading', 'co-view', 'sonify'];
+      return ['theme', 'type', 'log', 'auto', 'indicators', 'precision', 'label', 'stats', 'profile', 'annotations', 'volshading', 'overlays', 'co-view', 'sonify'];
     }
 
     constructor() {
@@ -225,6 +228,12 @@ class WickChart extends HTMLElementBase {
       this._alerts = [];
       this._seq = 0;
 
+      // server-side overlays (zones & levels)
+      this._overlays = [];
+
+      // scenario projection (ghost path + vol cone)
+      this._scenario = null;
+
       this._onResize = () => this._invalidate();
       this._onPointerDown = (e) => this._pointerDown(e);
       this._onPointerMove = (e) => this._pointerMove(e);
@@ -330,6 +339,18 @@ class WickChart extends HTMLElementBase {
           this._volshade = val != null && val !== 'false' ? parseVolShading(val) : null;
           this._legendKey = '';
           break;
+        case 'overlays': {
+          let ovs = [];
+          if (val != null && val !== '') {
+            try {
+              ovs = normalizeOverlays(JSON.parse(val));
+            } catch (err) {
+              ovs = [];
+            }
+          }
+          this._overlays = ovs;
+          break;
+        }
         case 'co-view':
           this._coviewName = val || null;
           this._setupCoView();
@@ -629,7 +650,11 @@ class WickChart extends HTMLElementBase {
         })),
         alerts: this._alerts
           .filter((a) => !a.fired)
-          .map((a) => ({ id: a.id, price: a.price, direction: a.direction, once: a.once })),
+          .map((a) =>
+            a.when != null
+              ? { id: a.id, when: a.when, once: a.once }
+              : { id: a.id, price: a.price, direction: a.direction, once: a.once }
+          ),
       };
     }
 
@@ -667,14 +692,31 @@ class WickChart extends HTMLElementBase {
       }
       if (Array.isArray(state.alerts)) {
         this._alerts = state.alerts
-          .filter((a) => a && isNum(a.price))
-          .map((a) => ({
-            id: a.id != null ? String(a.id) : 'alert-' + ++this._seq,
-            price: a.price,
-            direction: a.direction || 'cross',
-            once: a.once !== false,
-            fired: false,
-          }));
+          .filter((a) => a && (isNum(a.price) || typeof a.when === 'string'))
+          .map((a) => {
+            if (typeof a.when === 'string' && a.when.trim()) {
+              try {
+                return {
+                  id: a.id != null ? String(a.id) : 'alert-' + ++this._seq,
+                  when: a.when.trim(),
+                  compiled: compileScript(a.when),
+                  once: a.once !== false,
+                  fired: false,
+                  armed: true,
+                };
+              } catch (err) {
+                return null;
+              }
+            }
+            return {
+              id: a.id != null ? String(a.id) : 'alert-' + ++this._seq,
+              price: a.price,
+              direction: a.direction || 'cross',
+              once: a.once !== false,
+              fired: false,
+            };
+          })
+          .filter(Boolean);
       }
       if (state.view && state.view.from != null && state.view.to != null) {
         if (this._ly && this._data.length > 1) {
@@ -727,22 +769,46 @@ class WickChart extends HTMLElementBase {
     }
 
     /**
-     * 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) {
-      if (!alert || !isNum(alert.price)) return null;
-      const a = {
-        id: alert.id != null ? String(alert.id) : 'alert-' + ++this._seq,
-        price: alert.price,
-        direction: alert.direction || 'cross',
-        once: alert.once !== false,
-        fired: false,
-      };
+      if (!alert) return null;
+      let a;
+      if (typeof alert.when === 'string' && alert.when.trim()) {
+        let compiled;
+        try {
+          compiled = compileScript(alert.when);
+        } catch (err) {
+          return null;
+        }
+        a = {
+          id: alert.id != null ? String(alert.id) : 'alert-' + ++this._seq,
+          when: alert.when.trim(),
+          compiled,
+          once: alert.once !== false,
+          fired: false,
+          armed: true,
+        };
+      } else {
+        if (!isNum(alert.price)) return null;
+        a = {
+          id: alert.id != null ? String(alert.id) : 'alert-' + ++this._seq,
+          price: alert.price,
+          direction: alert.direction || 'cross',
+          once: alert.once !== false,
+          fired: false,
+        };
+      }
       const i = this._alerts.findIndex((x) => x.id === a.id);
       if (i >= 0) this._alerts[i] = a;
       else this._alerts.push(a);
@@ -760,11 +826,194 @@ class WickChart extends HTMLElementBase {
       this._invalidate();
     }
 
-    /** 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) {
+      this._overlays = normalizeOverlays(list);
+      this._invalidate();
+      return this._overlays.map((o) => o.id);
+    }
+
+    /** @returns {object[]} a copy of the current overlays */
+    get overlays() {
+      return this._overlays.map((o) => ({ ...o }));
+    }
+
+    /**
+     * Add or replace (upsert, by id) a single overlay.
+     * @returns {string|null} the overlay id, or null if invalid
+     */
+    addOverlay(ov) {
+      const norm = normalizeOverlays([ov]);
+      if (!norm.length) return null;
+      const one = norm[0];
+      const i = this._overlays.findIndex((x) => x.id === one.id);
+      if (i >= 0) this._overlays[i] = one;
+      else this._overlays.push(one);
+      this._invalidate();
+      return one.id;
+    }
+
+    removeOverlay(id) {
+      this._overlays = this._overlays.filter((o) => o.id !== String(id));
+      this._invalidate();
+    }
+
+    clearOverlays() {
+      this._overlays = [];
+      this._invalidate();
+    }
+
+    /**
+     * 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) {
+      this._scenario = normalizeScenario(spec);
+      this._invalidate();
+      return this._scenario;
+    }
+
+    clearScenario() {
+      this._scenario = null;
+      this._invalidate();
+    }
+
+    /** @returns {object|null} a copy of the active scenario */
+    get scenario() {
+      if (!this._scenario) return null;
+      return { ...this._scenario, path: this._scenario.path.map((p) => ({ ...p })) };
+    }
+
+    /** σ-cone for the active scenario, cached per data version. */
+    _scenarioConeCache() {
+      if (!this._scenario || !this._data.length) return null;
+      if (this._cache.v !== this._version) {
+        this._cache = { v: this._version, map: {} };
+      }
+      if (!this._cache.map.__scenario) {
+        const d = this._data;
+        const vol = calcRealizedVol(d.map((b) => b.close), 20);
+        let v = NaN;
+        for (let i = vol.length - 1; i >= 0; i--) {
+          if (Number.isFinite(vol[i])) { v = vol[i]; break; }
+        }
+        this._cache.map.__scenario = calcVolCone(
+          d[d.length - 1].close,
+          v,
+          this._scenario.horizon,
+          this._scenario.levels
+        );
+      }
+      return this._cache.map.__scenario;
+    }
+
+    /* ------------------------------------------------------------ *
+     * AI agent interface — the chart as a tool surface
+     * ------------------------------------------------------------ */
+
+    /** Tool manifest for LLM control — JSON-safe copy of AI_TOOLS. */
+    aiTools() {
+      return JSON.parse(JSON.stringify(AI_TOOLS));
+    }
+
+    /** System prompt for agent control — paste into any LLM alongside aiTools(). */
+    aiPrompt() {
+      return aiPromptText();
+    }
+
+    /** Grounding context for a model: current state + visible-window summary. */
+    aiContext() {
+      return { state: this.getState(), window: this.getDataWindow() };
+    }
+
+    /**
+     * 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) {
+      return applyChartOps(this, ops);
+    }
+
+    /**
+     * 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]
+     */
+    async ask(instruction, opts = {}) {
+      const payload = {
+        system: aiPromptText(),
+        instruction: String(instruction == null ? '' : instruction),
+        chart: this.aiContext(),
+        tools: this.aiTools(),
+      };
+      if (typeof opts.run !== 'function') {
+        return { payload, ops: null, results: null };
+      }
+      const ops = await opts.run(payload);
+      const results = this.applyAI(ops);
+      return { payload, ops, results };
+    }
+
+    /** 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, bar) {
-      if (!this._alerts.length || !isNum(prevClose)) return;
+      if (!this._alerts.length) return;
       for (const a of [...this._alerts]) {
         if (a.fired) continue;
+        if (a.when != null) {
+          const series = this._predicateCache(a);
+          const curTrue = series.length ? series[series.length - 1] : false;
+          const step = scriptAlertStep(a.armed, curTrue);
+          a.armed = step.armed;
+          if (step.fire) {
+            a.fired = true;
+            this._fire('alert', { id: a.id, price: bar.close, when: a.when, bar });
+            if (a.once) this._alerts = this._alerts.filter((x) => x !== a);
+          }
+          continue;
+        }
+        if (!isNum(prevClose)) continue;
         if (checkAlertCross(a, prevClose, bar.close)) {
           a.fired = true;
           this._fire('alert', { id: a.id, price: a.price, bar });
@@ -773,6 +1022,18 @@ class WickChart extends HTMLElementBase {
       }
     }
 
+    /** Cached boolean series for a scripted alert's predicate (per data version). */
+    _predicateCache(alert) {
+      if (this._cache.v !== this._version) {
+        this._cache = { v: this._version, map: {} };
+      }
+      const k = 'pred:' + alert.when;
+      if (!this._cache.map[k]) {
+        this._cache.map[k] = predicateTrueSeries(alert.compiled, this._data);
+      }
+      return this._cache.map[k];
+    }
+
     /* reflected properties */
     get theme() { return this._theme; }
     set theme(v) { this.setAttribute('theme', v); }
@@ -1013,7 +1274,9 @@ class WickChart extends HTMLElementBase {
     _rightMargin() {
       const ly = this._ly;
       const w = ly ? ly.plotRight : 600;
-      return Math.max(3, (w / this._view.spacing) * 0.06);
+      const base = Math.max(3, (w / this._view.spacing) * 0.06);
+      // a scenario projection reserves future space so the cone stays visible
+      return this._scenario ? Math.max(base, this._scenario.horizon + 3) : base;
     }
 
     _applyFit() {
@@ -1381,6 +1644,146 @@ class WickChart extends HTMLElementBase {
         }
       }
 
+      /* server-side overlays: zones & levels (above regime shading, under series).
+       * Zones with `to == null` extend into future space past the last bar. */
+      if (this._overlays.length) {
+        const d = this._data;
+        const idxFor = (t, fallback) => (t == null ? fallback : barIndexForTime(d, t));
+        for (const ov of this._overlays) {
+          const col = resolveOverlayColor(ov.color, pal);
+          if (ov.type === 'zone') {
+            const iA = Math.max(0, idxFor(ov.from, 0));
+            const iB = ov.to == null ? null : Math.max(0, idxFor(ov.to, d.length - 1));
+            const zx0 = clamp(this._xFor(iA) - sp * 0.5, 0, plotRight);
+            const zx1 = iB == null ? plotRight : clamp(this._xFor(iB) + sp * 0.5, 0, plotRight);
+            const zyT = clamp(yOf(ov.priceTo), main.y0, main.y1);
+            const zyB = clamp(yOf(ov.priceFrom), main.y0, main.y1);
+            if (zx1 - zx0 < 1 || zyB - zyT < 1) continue;
+            ctx.save();
+            ctx.globalAlpha = ov.alpha;
+            ctx.fillStyle = col;
+            ctx.fillRect(zx0, zyT, zx1 - zx0, zyB - zyT);
+            if (ov.border) {
+              ctx.globalAlpha = Math.min(1, ov.alpha + 0.4);
+              ctx.lineWidth = 1;
+              ctx.strokeStyle = col;
+              ctx.strokeRect(
+                Math.round(zx0) + 0.5, Math.round(zyT) + 0.5,
+                Math.max(2, Math.round(zx1 - zx0) - 1), Math.max(2, Math.round(zyB - zyT) - 1)
+              );
+            }
+            if (ov.label) {
+              ctx.globalAlpha = 0.95;
+              ctx.font = pillFont();
+              ctx.fillStyle = col;
+              ctx.textAlign = 'left';
+              ctx.textBaseline = 'top';
+              ctx.fillText(ov.label, zx0 + 6, Math.max(main.y0, zyT) + 4);
+            }
+            ctx.restore();
+          } else {
+            const lx0 = clamp(this._xFor(Math.max(0, idxFor(ov.from, 0))) - sp * 0.5, 0, plotRight);
+            const lx1 =
+              ov.to == null
+                ? plotRight
+                : clamp(this._xFor(Math.max(0, idxFor(ov.to, d.length - 1))) + sp * 0.5, 0, plotRight);
+            const ly = Math.round(yOf(ov.price)) + 0.5;
+            if (lx1 - lx0 < 1 || ly < main.y0 || ly > main.y1) continue;
+            ctx.save();
+            ctx.strokeStyle = col;
+            ctx.lineWidth = ov.width;
+            if (ov.dash) ctx.setLineDash([5, 4]);
+            ctx.beginPath();
+            ctx.moveTo(lx0, ly);
+            ctx.lineTo(lx1, ly);
+            ctx.stroke();
+            if (ov.label) {
+              ctx.font = pillFont();
+              ctx.fillStyle = col;
+              ctx.textAlign = 'right';
+              ctx.textBaseline = 'bottom';
+              ctx.fillText(ov.label, Math.min(lx1, plotRight) - 6, ly - 2);
+            }
+            ctx.restore();
+          }
+        }
+      }
+
+      /* scenario projection: ghost path + σ-cone in future space (clipped to
+       * the main plot so out-of-range bands never bleed into the axis) */
+      if (this._scenario && d.length) {
+        const sc = this._scenario;
+        const col = resolveOverlayColor(sc.color, pal);
+        const baseIdx = d.length - 1;
+        const xAt = (h) => this._xFor(baseIdx + h);
+        ctx.save();
+        ctx.beginPath();
+        ctx.rect(0, main.y0, plotRight, main.h);
+        ctx.clip();
+        if (sc.cone) {
+          const cone = this._scenarioConeCache();
+          if (cone) {
+            for (let li = cone.levels.length - 1; li >= 0; li--) {
+              const b = cone.bands[cone.levels[li]];
+              ctx.globalAlpha = li === 0 ? 0.1 : 0.05;
+              ctx.fillStyle = col;
+              ctx.beginPath();
+              ctx.moveTo(xAt(0), yOf(b.up[0]));
+              for (let h = 1; h <= cone.horizon; h++) ctx.lineTo(xAt(h), yOf(b.up[h]));
+              for (let h = cone.horizon; h >= 0; h--) ctx.lineTo(xAt(h), yOf(b.down[h]));
+              ctx.closePath();
+              ctx.fill();
+            }
+            const inner = cone.bands[cone.levels[0]];
+            ctx.globalAlpha = 0.4;
+            ctx.strokeStyle = col;
+            ctx.lineWidth = 1;
+            ctx.setLineDash([4, 4]);
+            for (const arr of [inner.up, inner.down]) {
+              ctx.beginPath();
+              ctx.moveTo(xAt(0), yOf(arr[0]));
+              for (let h = 1; h <= cone.horizon; h++) ctx.lineTo(xAt(h), yOf(arr[h]));
+              ctx.stroke();
+            }
+            ctx.setLineDash([]);
+          }
+        }
+        if (sc.path.length) {
+          ctx.globalAlpha = 0.9;
+          ctx.strokeStyle = col;
+          ctx.lineWidth = 1.5;
+          ctx.setLineDash([6, 4]);
+          ctx.beginPath();
+          ctx.moveTo(xAt(0), yOf(d[baseIdx].close));
+          for (const p of sc.path) ctx.lineTo(xAt(p.h), yOf(p.price));
+          ctx.stroke();
+          ctx.setLineDash([]);
+          ctx.fillStyle = col;
+          for (const p of sc.path) {
+            const y = yOf(p.price);
+            if (y >= main.y0 && y <= main.y1) {
+              ctx.beginPath();
+              ctx.arc(xAt(p.h), y, 2.5, 0, Math.PI * 2);
+              ctx.fill();
+            }
+          }
+          if (sc.label) {
+            const p = sc.path[sc.path.length - 1];
+            ctx.font = pillFont();
+            ctx.globalAlpha = 0.95;
+            ctx.fillStyle = col;
+            ctx.textAlign = 'left';
+            ctx.textBaseline = 'middle';
+            ctx.fillText(
+              sc.label,
+              Math.min(xAt(p.h) + 8, plotRight - 4),
+              clamp(yOf(p.price), main.y0 + 8, main.y1 - 8)
+            );
+          }
+        }
+        ctx.restore();
+      }
+
       /* position zones (under series) */
       for (const pos of this._positions) {
         const yE = clamp(yOf(pos.entry), main.y0, main.y1);
@@ -1724,7 +2127,7 @@ class WickChart extends HTMLElementBase {
         ctx.setLineDash([5, 4]);
         ctx.strokeStyle = pal.overlay[0];
         for (const a of this._alerts) {
-          if (a.fired) continue;
+          if (a.fired || !isNum(a.price)) continue; // scripted alerts have no line
           const y = yOf(a.price);
           if (y < main.y0 || y > main.y1) continue;
           ctx.globalAlpha = 0.8;
@@ -2449,8 +2852,10 @@ class WickChart extends HTMLElementBase {
       const dy = e.deltaY * (e.deltaMode === 1 ? 33 : 1);
 
       if (Math.abs(dx) > Math.abs(dy) && !e.ctrlKey) {
-        // trackpad horizontal scroll → pan
-        this._view.rightIndex -= dx / this._view.spacing;
+        // trackpad horizontal scroll → pan. Wheel deltas are viewport-relative:
+        // deltaX>0 means "scroll right", i.e. reveal newer bars. On natural-scroll
+        // trackpads this makes the content follow the fingers, matching drag.
+        this._view.rightIndex += dx / this._view.spacing;
         this._auto = this._atRight();
         this._clampView();
         this._invalidate();