wickchart 1.0.0 → 1.3.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,541 @@ 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) : '',
+  };
+}
+
+/* ------------------------------------------------------------------ *
+ * Risk planner — R-multiple grid
+ * ------------------------------------------------------------------ */
+
+/**
+ * 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 function normalizeRiskPlan(spec) {
+  if (!spec || typeof spec !== 'object') return null;
+  const entry = +spec.entry;
+  const stop = +spec.stop;
+  if (
+    !Number.isFinite(entry) || !Number.isFinite(stop) ||
+    entry <= 0 || stop <= 0 || entry === stop
+  ) return null;
+  const risk = Math.abs(entry - stop);
+  const sign = stop < entry ? 1 : -1;
+  let ks = null;
+  if (Array.isArray(spec.multiples)) {
+    ks = spec.multiples.map((k) => +k).filter((k) => Number.isFinite(k) && k > 0 && k <= 20);
+  } else if (Array.isArray(spec.targets)) {
+    ks = [];
+    for (const t of spec.targets) {
+      const p = +t;
+      if (!Number.isFinite(p) || p <= 0) continue;
+      const k = ((p - entry) / risk) * sign;
+      if (k > 0.005) ks.push(Math.round(k * 100) / 100);
+    }
+  }
+  if (!ks || !ks.length) ks = [1, 2, 3];
+  const levels = [...new Set(ks)]
+    .sort((a, b) => a - b)
+    .slice(0, 8)
+    .map((k) => ({ k, price: entry + sign * k * risk }));
+  return {
+    entry,
+    stop,
+    risk,
+    direction: sign > 0 ? 'long' : 'short',
+    levels,
+    maxK: levels.length ? levels[levels.length - 1].k : 0,
+    label: spec.label != null ? String(spec.label).slice(0, 40) : '',
+  };
+}
+
+/* ------------------------------------------------------------------ *
+ * Bar-walk narrator — a timeline of what happened
+ * ------------------------------------------------------------------ */
+
+/**
+ * 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 function narrateWindow(bars, i0, i1, opts = {}) {
+  if (!bars.length || i0 < 0 || i1 < i0 || i1 >= bars.length) return [];
+  const rsi = calcRSI(bars.map((b) => b.close), Math.min(50, Math.max(2, +opts.rsiPeriod || 14)));
+  const ann = detectAnnotations(bars, i0, i1, rsi, {
+    pivot: opts.pivot ?? 8,
+    volMult: opts.volMult,
+    gapMult: opts.gapMult,
+  });
+  // legs: the move between consecutive opposite pivots, stamped at the
+  // ending pivot so a walk player can speak it as it arrives
+  const pivots = ann
+    .filter((a) => a.type === 'pivothigh' || a.type === 'pivotlow')
+    .sort((a, b) => a.i - b.i);
+  const legs = [];
+  for (let k = 1; k < pivots.length; k++) {
+    const a = pivots[k - 1];
+    const b = pivots[k];
+    if (a.type === b.type) continue;
+    const pa = a.type === 'pivothigh' ? bars[a.i].high : bars[a.i].low;
+    const pb = b.type === 'pivothigh' ? bars[b.i].high : bars[b.i].low;
+    if (!(pa > 0) || !Number.isFinite(pb)) continue;
+    const pct = ((pb - pa) / pa) * 100;
+    legs.push({
+      type: 'leg',
+      side: pct >= 0 ? 'high' : 'low',
+      i: b.i,
+      note: `${pct >= 0 ? '+' : ''}${pct.toFixed(1)}% over ${b.i - a.i} bars`,
+      legPct: Math.round(pct * 100) / 100,
+      legBars: b.i - a.i,
+    });
+  }
+  return [...ann, ...legs]
+    .sort((a, b) => a.i - b.i)
+    .slice(0, 60)
+    .map((e) => ({ ...e, time: bars[e.i].time }));
+}
+
+/* ------------------------------------------------------------------ *
+ * Delta brush — selection statistics
+ * ------------------------------------------------------------------ */
+
+/**
+ * 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 function brushStats(bars, i0, i1) {
+  if (!bars.length || i0 < 0 || i1 < i0 || i1 >= bars.length) return null;
+  const first = bars[i0];
+  const last = bars[i1];
+  let high = -Infinity;
+  let low = Infinity;
+  let vol = 0;
+  for (let i = i0; i <= i1; i++) {
+    const b = bars[i];
+    if (b.high > high) high = b.high;
+    if (b.low < low) low = b.low;
+    vol += b.volume || 0;
+  }
+  const delta = last.close - first.open;
+  return {
+    bars: i1 - i0 + 1,
+    from: { index: i0, time: first.time },
+    to: { index: i1, time: last.time },
+    firstOpen: first.open,
+    lastClose: last.close,
+    delta,
+    deltaPct: first.open ? (delta / first.open) * 100 : 0,
+    high,
+    low,
+    volume: vol,
+  };
+}
+
+/* ------------------------------------------------------------------ *
+ * Story mode — guided tours of chart state
+ * ------------------------------------------------------------------ */
+
+/** Smoothest cheap easing for viewport pans: slow in, slow out. */
+export function easeInOutCubic(t) {
+  const x = clamp(+t || 0, 0, 1);
+  return x < 0.5 ? 4 * x * x * x : 1 - Math.pow(-2 * x + 2, 3) / 2;
+}
+
+/**
+ * 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 function normalizeScene(scene) {
+  if (!scene || typeof scene !== 'object') return null;
+  const out = {
+    title: scene.title != null ? String(scene.title).slice(0, 60) : '',
+    note: scene.note != null ? String(scene.note).slice(0, 200) : '',
+    dwell: clamp(Math.round(+scene.dwell || 2200), 500, 30000),
+  };
+  if (scene.range && Number.isFinite(+scene.range.from) && Number.isFinite(+scene.range.to)) {
+    out.range = { from: +scene.range.from, to: +scene.range.to };
+  }
+  if (scene.indicators != null) {
+    const s = String(scene.indicators).trim();
+    if (s) out.indicators = s.slice(0, 200);
+  }
+  if (scene.type != null && SERIES_TYPES.includes(scene.type)) out.type = scene.type;
+  if (scene.overlays != null) {
+    const ovs = normalizeOverlays(scene.overlays);
+    if (ovs.length) out.overlays = ovs;
+  }
+  if ('scenario' in scene) {
+    if (scene.scenario == null) out.scenario = 'clear';
+    else {
+      const sc = normalizeScenario(scene.scenario);
+      if (sc) out.scenario = sc;
+    }
+  }
+  if ('riskPlan' in scene) {
+    if (scene.riskPlan == null) out.riskPlan = 'clear';
+    else {
+      const rp = normalizeRiskPlan(scene.riskPlan);
+      if (rp) out.riskPlan = rp;
+    }
+  }
+  return out;
+}
+
+/**
+ * Validate a whole story: normalize each scene, drop junk, cap at 20.
+ * @returns {object[]} possibly empty
+ */
+export function sceneList(story) {
+  if (!Array.isArray(story)) return [];
+  const out = [];
+  for (const s of story) {
+    const n = normalizeScene(s);
+    if (n) out.push(n);
+    if (out.length >= 20) break;
+  }
+  return out;
+}
+
+/* ------------------------------------------------------------------ *
+ * Co-view presence — peer viewport tracking with TTL expiry
+ * ------------------------------------------------------------------ */
+
+/**
+ * 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 class PresenceTracker {
+  /** @param {number} [ttl=12000] ms a peer survives without a sighting */
+  constructor(ttl = 12000) {
+    this.ttl = Math.max(1000, +ttl || 12000);
+    /** @type {Map<string, {id: string, name: string|null, range: {from:number,to:number}|null, at: number}>} */
+    this.peers = new Map();
+  }
+
+  /**
+   * 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, patch = {}, now = Date.now()) {
+    if (!id || typeof id !== 'string') return false;
+    const existing = this.peers.get(id);
+    if (existing) {
+      if (patch && patch.range) {
+        const f = +patch.range.from;
+        const t = +patch.range.to;
+        if (Number.isFinite(f) && Number.isFinite(t)) {
+          existing.range = { from: Math.min(f, t), to: Math.max(f, t) };
+        }
+      }
+      if (patch && patch.name != null) existing.name = String(patch.name).slice(0, 24) || null;
+      existing.at = now;
+      return false;
+    }
+    const f = patch && patch.range ? +patch.range.from : NaN;
+    const t = patch && patch.range ? +patch.range.to : NaN;
+    this.peers.set(id, {
+      id,
+      name: patch && patch.name != null ? (String(patch.name).slice(0, 24) || null) : null,
+      range: Number.isFinite(f) && Number.isFinite(t)
+        ? { from: Math.min(f, t), to: Math.max(f, t) }
+        : null,
+      at: now,
+    });
+    return true;
+  }
+
+  /** @returns {object|null} the removed peer entry, or null when unknown */
+  drop(id) {
+    const p = this.peers.get(id);
+    this.peers.delete(id);
+    return p || null;
+  }
+
+  /** Expire peers not seen within the ttl.
+   *  @returns {object[]} the peer entries that left */
+  sweep(now = Date.now()) {
+    const left = [];
+    for (const [id, p] of this.peers) {
+      if (now - p.at > this.ttl) {
+        this.peers.delete(id);
+        left.push(p);
+      }
+    }
+    return left;
+  }
+
+  /** @returns {{id: string, name: string|null, range: object|null, at: number}[]} copies, oldest sighting first */
+  list() {
+    return [...this.peers.values()]
+      .sort((a, b) => a.at - b.at)
+      .map((p) => ({ ...p, range: p.range ? { ...p.range } : null }));
+  }
+}
+
 /* ------------------------------------------------------------------ *
  * AI-ready window summary
  * ------------------------------------------------------------------ */
@@ -1780,3 +2375,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));
+    }
+  });
+}