wickchart 1.0.0 → 1.2.0

package/src/core.js

@@ -1043,6 +1043,17 @@ function tokenizeScript(src) {
       i += m[0].length;
       continue;
     }
+    const two = src.slice(i, i + 2);
+    if (two === '>=' || two === '<=' || two === '==' || two === '!=') {
+      toks.push({ t: 'op', v: two });
+      i += 2;
+      continue;
+    }
+    if (c === '>' || c === '<') {
+      toks.push({ t: 'op', v: c });
+      i++;
+      continue;
+    }
     if (c === '+' || c === '-' || c === '*' || c === '/' || c === '%') {
       toks.push({ t: 'op', v: c });
       i++;
@@ -1066,6 +1077,17 @@ function parseScript(src) {
   let p = 0;
   const peek = () => toks[p];
 
+  const CMP_OPS = ['>', '<', '>=', '<=', '==', '!='];
+
+  /** Comparisons bind loosest (a > b + 1); chains associate left, each 1/0. */
+  function parseCmp(depth) {
+    let l = parseAdd(depth);
+    while (peek() && peek().t === 'op' && CMP_OPS.includes(peek().v)) {
+      const op = toks[p++].v;
+      l = { type: 'bin', op, l, r: parseAdd(depth) };
+    }
+    return l;
+  }
   function parseAdd(depth) {
     let l = parseMul(depth);
     while (peek() && peek().t === 'op' && (peek().v === '+' || peek().v === '-')) {
@@ -1103,10 +1125,10 @@ function parseScript(src) {
         p++;
         const args = [];
         if (peek() && peek().t !== ')') {
-          args.push(parseAdd(depth));
+          args.push(parseCmp(depth));
           while (peek() && peek().t === ',') {
             p++;
-            args.push(parseAdd(depth));
+            args.push(parseCmp(depth));
           }
         }
         const close = toks[p++];
@@ -1117,7 +1139,7 @@ function parseScript(src) {
       return { type: 'var', name };
     }
     if (t.t === '(') {
-      const e = parseAdd(depth);
+      const e = parseCmp(depth);
       const close = toks[p++];
       if (!close || close.t !== ')') throw scriptErr('missing ")"');
       return e;
@@ -1125,7 +1147,7 @@ function parseScript(src) {
     throw scriptErr(`unexpected token "${t.t === 'op' ? t.v : t.t}"`);
   }
 
-  const ast = parseAdd(0);
+  const ast = parseCmp(0);
   if (p < toks.length) throw scriptErr('unexpected trailing input');
   validateScriptNode(ast);
   return ast;
@@ -1179,6 +1201,20 @@ function binOp(op, a, b) {
     case '*': return a * b;
     case '/': return a / b;
     case '%': return a % b;
+    // comparisons yield 1/0; NaN operands stay NaN so warm-up gaps survive
+    case '>':
+    case '<':
+    case '>=':
+    case '<=':
+    case '==':
+    case '!=':
+      if (!Number.isFinite(a) || !Number.isFinite(b)) return NaN;
+      if (op === '>') return a > b ? 1 : 0;
+      if (op === '<') return a < b ? 1 : 0;
+      if (op === '>=') return a >= b ? 1 : 0;
+      if (op === '<=') return a <= b ? 1 : 0;
+      if (op === '==') return a === b ? 1 : 0;
+      return a !== b ? 1 : 0;
   }
   return NaN;
 }
@@ -1354,6 +1390,34 @@ export function checkAlertCross(alert, prevPrice, price) {
   return (prevPrice <= p && price > p) || (prevPrice >= p && price < p);
 }
 
+/**
+ * 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 function predicateTrueSeries(compiled, bars) {
+  const vals = evalScript(compiled, bars);
+  return vals.map((v) => Number.isFinite(v) && v !== 0);
+}
+
+/**
+ * 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 function scriptAlertStep(armed, curTrue) {
+  if (curTrue && armed) return { fire: true, armed: false };
+  if (!curTrue && !armed) return { fire: false, armed: true };
+  return { fire: false, armed };
+}
+
 /* ------------------------------------------------------------------ *
  * Visible-range statistics
  * ------------------------------------------------------------------ */
@@ -1528,10 +1592,221 @@ export function parseVolShading(val) {
   let p1 = isNum(parts[0]) ? clamp(parts[0], 0, 98) : 30;
   const p2 = isNum(parts[1]) ? clamp(parts[1], 2, 100) : 70;
   p1 = clamp(p1, 0, p2 - 2);
-  const period = isNum(parts[2]) ? Math.round(clamp(parts[2], 2, 500)) : 20;
+  const period = isNum(parts[2]) ? clamp(parts[2], 2, 500) : 20;
   return { p1, p2, period };
 }
 
+/* ------------------------------------------------------------------ *
+ * Server-side overlays (zones & levels)
+ * ------------------------------------------------------------------ */
+
+/** Normalize a timestamp to milliseconds (bar times and query times both
+ *  auto-detect seconds — anything below 1e12 is treated as seconds). */
+const normMs = (t) => (t < 1e12 ? t * 1000 : t);
+
+/**
+ * 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 function barIndexForTime(bars, t) {
+  if (!Array.isArray(bars) || !bars.length || !isNum(t)) return null;
+  const scale = normMs(bars[bars.length - 1].time) / bars[bars.length - 1].time;
+  const target = normMs(t);
+  let lo = 0;
+  let hi = bars.length - 1;
+  if (target <= bars[0].time * scale) return 0;
+  if (target >= bars[hi].time * scale) return hi;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    if (bars[mid].time * scale <= target) lo = mid;
+    else hi = mid - 1;
+  }
+  return lo;
+}
+
+/**
+ * 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 function normalizeOverlays(list) {
+  if (!Array.isArray(list)) return [];
+  const out = [];
+  let n = 0;
+  for (const raw of list) {
+    if (!raw || typeof raw !== 'object') continue;
+    let type = null;
+    if (raw.type === 'zone') type = 'zone';
+    else if (raw.type === 'level') type = 'level';
+    if (!type) continue;
+    const id = raw.id != null ? String(raw.id).slice(0, 64) : 'ov-' + ++n;
+    const label = raw.label != null ? String(raw.label).slice(0, 40) : '';
+    // palette keys first ('up' is 2 letters and would fail the generic name check)
+    const rawColor = raw.color != null ? String(raw.color).trim() : '';
+    const color = /^(up|down|accent)$/i.test(rawColor)
+      ? rawColor.toLowerCase()
+      : safeColor(rawColor) || null;
+    const from = isNum(raw.from) ? raw.from : null;
+    const to = isNum(raw.to) ? raw.to : null;
+    if (type === 'zone') {
+      if (!isNum(raw.priceFrom) || !isNum(raw.priceTo)) continue;
+      out.push({
+        id,
+        type,
+        from,
+        to,
+        priceFrom: Math.min(raw.priceFrom, raw.priceTo),
+        priceTo: Math.max(raw.priceFrom, raw.priceTo),
+        color,
+        alpha: isNum(raw.alpha) ? clamp(raw.alpha, 0.02, 0.8) : 0.22,
+        border: raw.border !== false,
+        label,
+      });
+    } else {
+      if (!isNum(raw.price)) continue;
+      out.push({
+        id,
+        type,
+        from,
+        to,
+        price: raw.price,
+        color,
+        width: isNum(raw.width) ? clamp(raw.width, 1, 4) : 1,
+        dash: raw.dash === true,
+        label,
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * 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 function resolveOverlayColor(raw, pal) {
+  if (typeof raw === 'string') {
+    const key = raw.trim().toLowerCase();
+    if (key === 'up' || key === 'down' || key === 'accent') return pal[key];
+    const c = safeColor(raw);
+    if (c) return c;
+  }
+  return pal.accent;
+}
+
+/* ------------------------------------------------------------------ *
+ * Scenario mode — ghost paths + volatility cones
+ * ------------------------------------------------------------------ */
+
+/**
+ * σ-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 function calcVolCone(lastClose, volPerBar, horizon, levels) {
+  const zs = (Array.isArray(levels) && levels.length ? levels : [1, 2])
+    .map((z) => +z)
+    .filter((z) => Number.isFinite(z) && z > 0 && z <= 5)
+    .sort((a, b) => a - b);
+  const lv = zs.length ? zs : [1];
+  const H = Math.max(1, Math.min(500, Math.round(+horizon || 48)));
+  const c = +lastClose;
+  const v = +volPerBar;
+  const bands = {};
+  const flat = !Number.isFinite(c) || c <= 0 || !Number.isFinite(v) || v < 0;
+  for (const z of lv) {
+    const up = new Array(H + 1);
+    const down = new Array(H + 1);
+    for (let h = 0; h <= H; h++) {
+      if (flat) {
+        up[h] = c || 0;
+        down[h] = c || 0;
+      } else {
+        const k = Math.exp(z * v * Math.sqrt(h));
+        up[h] = c * k;
+        down[h] = c / k;
+      }
+    }
+    bands[z] = { up, down };
+  }
+  return { horizon: H, levels: lv, bands };
+}
+
+/**
+ * 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 function normalizeScenario(spec) {
+  if (!spec || typeof spec !== 'object') return null;
+  const rawPath = Array.isArray(spec.path) ? spec.path : null;
+  const path = [];
+  if (rawPath) {
+    for (let i = 0; i < rawPath.length && path.length < 250; i++) {
+      const p = rawPath[i];
+      const price = p && typeof p === 'object' ? +p.price : +p;
+      if (Number.isFinite(price) && price > 0) path.push({ h: path.length + 1, price });
+    }
+  }
+  const hasHorizon = isNum(spec.horizon) && spec.horizon > 0;
+  if (!path.length && !hasHorizon) return null;
+  const horizon = Math.round(
+    clamp(path.length ? (hasHorizon ? Math.max(path.length, spec.horizon) : path.length) : spec.horizon, 1, 500)
+  );
+  let levels = [1, 2];
+  if (Array.isArray(spec.levels)) {
+    const zs = spec.levels
+      .map((z) => +z)
+      .filter((z) => Number.isFinite(z) && z > 0 && z <= 5)
+      .sort((a, b) => a - b);
+    if (zs.length) levels = zs;
+  }
+  const rawColor = spec.color != null ? String(spec.color).trim() : '';
+  const color = /^(up|down|accent)$/i.test(rawColor)
+    ? rawColor.toLowerCase()
+    : safeColor(rawColor) || null;
+  return {
+    path,
+    horizon,
+    cone: spec.cone !== false,
+    levels,
+    color,
+    label: spec.label != null ? String(spec.label).slice(0, 40) : '',
+  };
+}
+
 /* ------------------------------------------------------------------ *
  * AI-ready window summary
  * ------------------------------------------------------------------ */
@@ -1780,3 +2055,166 @@ export function decodeStateQuery(str) {
   }
   return state;
 }
+
+/* ------------------------------------------------------------------ *
+ * AI agent interface — the chart as a tool surface
+ * ------------------------------------------------------------------ */
+
+/**
+ * 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 const AI_TOOLS = [
+  {
+    tool: 'get_data_window',
+    description:
+      'Read the visible chart window: OHLC stats, trend (slope + fit), volatility percentile, indicator snapshots, detected patterns. Returns structured fields plus a markdown summary.',
+    args: {},
+  },
+  {
+    tool: 'set_indicators',
+    description:
+      'Replace the indicators. Tokens: sma:20 ema:50 bb:20 vwap rsi:14 macd:12/26/9 volume, @hexcolor suffixes, or WickScript expressions like expr:{close - sma(close,20)} / pexpr:{rsi(close,14)}. Empty string clears all.',
+    args: { indicators: 'string — space/comma-separated tokens' },
+  },
+  {
+    tool: 'set_overlays',
+    description:
+      'Draw zones & levels behind the candles (support/resistance, supply/demand). Zone: {type:"zone", from?, to?, priceFrom, priceTo, color?, alpha?, label?} — omit `to` (or pass null) to extend into future space past the last bar. Level: {type:"level", price, color?, dash?, label?}. Invalid entries are dropped.',
+    args: { overlays: 'array of overlay objects' },
+  },
+  { tool: 'clear_overlays', description: 'Remove all overlays.', args: {} },
+  {
+    tool: 'add_alert',
+    description:
+      'Price alert {price, direction:"above"|"below"|"cross"} or scripted predicate {when:"<WickScript>"} — e.g. when:"crossup(rsi(close,14), 30)" or when:"volume > sma(volume,20) * 3". Fires wick:alert.',
+    args: {},
+  },
+  {
+    tool: 'set_view',
+    description: 'Set the visible time range (unix seconds or ms).',
+    args: { from: 'timestamp', to: 'timestamp' },
+  },
+  { tool: 'reset_view', description: 'Fit all loaded data.', args: {} },
+  {
+    tool: 'set_type',
+    description: 'Change the series type.',
+    args: { type: '"candles" | "line" | "area" | "bars" | "hollow" | "heikin"' },
+  },
+  {
+    tool: 'set_volshading',
+    description: 'Volatility-regime background shading (calm/normal/hot percentiles).',
+    args: { enabled: 'boolean', low: 'percentile 0–98 (default 30)', high: 'percentile (default 70)' },
+  },
+];
+
+/**
+ * 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 function aiPromptText() {
+  const lines = AI_TOOLS.map(
+    (t) => `- ${t.tool}${Object.keys(t.args).length ? '(' + Object.keys(t.args).join(', ') + ')' : '()'}: ${t.description}`
+  );
+  return [
+    'You are controlling a WickChart financial charting element through tool calls.',
+    'Reply with ONLY a JSON array of operations to apply, each {"tool": name, "args": {...}}.',
+    'Use get_data_window first when you need to see the chart before deciding.',
+    'Available tools:',
+    ...lines,
+  ].join('\n');
+}
+
+const AI_CHART_TYPES = SERIES_TYPES;
+
+/**
+ * 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 function applyChartOps(target, ops) {
+  if (!target) return [{ ok: false, error: 'no target' }];
+  if (!Array.isArray(ops)) return [{ ok: false, error: 'ops must be an array of {tool, args} objects' }];
+  return ops.map((op) => {
+    if (!op || typeof op !== 'object' || Array.isArray(op)) {
+      return { ok: false, error: 'each op must be an object: {tool, args}' };
+    }
+    const tool = String(op.tool || '');
+    const args = op.args && typeof op.args === 'object' && !Array.isArray(op.args) ? op.args : {};
+    const fail = (error) => ({ ok: false, tool, error });
+    try {
+      switch (tool) {
+        case 'get_data_window':
+          return { ok: true, tool, result: target.getDataWindow() };
+        case 'set_indicators': {
+          if (typeof args.indicators !== 'string') return fail('args.indicators must be a string');
+          const reg = target.constructor && target.constructor._registry ? target.constructor._registry() : null;
+          const parsed = parseIndicators(args.indicators, reg);
+          if (parsed.unknown.length) {
+            return fail(`unknown indicators: ${parsed.unknown.join(', ')}`);
+          }
+          target.setAttribute('indicators', args.indicators);
+          return { ok: true, tool, result: { applied: args.indicators || '(cleared)' } };
+        }
+        case 'set_overlays': {
+          if (!Array.isArray(args.overlays)) return fail('args.overlays must be an array');
+          const norm = normalizeOverlays(args.overlays);
+          if (!norm.length) return fail('no valid overlays in args.overlays');
+          const ids = target.setOverlays(args.overlays);
+          return { ok: true, tool, result: { applied: ids.length, dropped: args.overlays.length - ids.length } };
+        }
+        case 'clear_overlays':
+          target.clearOverlays();
+          return { ok: true, tool, result: { cleared: true } };
+        case 'add_alert': {
+          if (!isNum(args.price) && typeof args.when !== 'string') {
+            return fail('args needs either price (number) or when (WickScript string)');
+          }
+          const id = target.addAlert(args);
+          return id ? { ok: true, tool, result: { id } } : fail('invalid alert (bad predicate?)');
+        }
+        case 'set_view': {
+          const r = {};
+          if (isNum(args.from)) r.from = normMs(args.from);
+          if (isNum(args.to)) r.to = normMs(args.to);
+          if (!('from' in r) && !('to' in r)) return fail('args needs from and/or to timestamps');
+          target.setVisibleRange(r);
+          return { ok: true, tool, result: r };
+        }
+        case 'reset_view':
+          target.fit();
+          return { ok: true, tool, result: { reset: true } };
+        case 'set_type': {
+          if (!AI_CHART_TYPES.includes(args.type)) {
+            return fail(`args.type must be one of ${AI_CHART_TYPES.join(' | ')}`);
+          }
+          target.setAttribute('type', args.type);
+          return { ok: true, tool, result: { type: args.type } };
+        }
+        case 'set_volshading': {
+          if (args.enabled === false) {
+            target.setAttribute('volshading', 'false');
+            return { ok: true, tool, result: { enabled: false } };
+          }
+          const p = parseVolShading(
+            isNum(args.low) && isNum(args.high) ? `${args.low}/${args.high}` : ''
+          );
+          target.setAttribute('volshading', `${p.p1}/${p.p2}`);
+          return { ok: true, tool, result: { enabled: true, low: p.p1, high: p.p2 } };
+        }
+        default:
+          return fail(`unknown tool "${tool}"`);
+      }
+    } catch (err) {
+      return fail(err && err.message ? err.message : String(err));
+    }
+  });
+}