wickchart 1.2.0 → 1.3.0

package/README.md

@@ -416,6 +416,88 @@ multipliers (default `[1, 2]`). Like overlays, scenarios are analysis data —
 excluded from shareable state, and the same shape a server-side model could
 push. `calcVolCone` / `normalizeScenario` are exported from `wickchart/core`.
 
+### Risk planner — R-multiple grid
+
+Plan the trade on the chart: entry + stop define **1R** (the risk unit) and
+reward lines are drawn at kR beyond the entry, with the risk/reward zones
+shaded. Direction is derived from the stop side.
+
+```js
+chart.setRiskPlan({ entry: 64500, stop: 63800, multiples: [1, 2, 3] });
+chart.setRiskPlan({ entry: 64500, stop: 63800, targets: [65900, 67300] }); // prices → kR
+chart.clearRiskPlan();
+chart.riskPlan; // { entry, stop, risk, direction, levels: [{ k, price }], maxK, label }
+```
+
+Explicit `targets` convert to their R multiple (wrong-side prices drop);
+`multiples` win when both are given. At most 8 levels, each ≤ 20R; invalid
+specs clear the plan, never throw. `normalizeRiskPlan` is exported from
+`wickchart/core`.
+
+### Bar-walk narrator — history as a story
+
+`narrate()` builds the timeline of a window (pivot highs/lows, volume
+spikes, gaps, RSI divergences, plus derived legs — the move between
+opposite pivots); `walk()` replays the chart through it while `wick:walk`
+events announce each step, so a caption bar can narrate the replay.
+
+```js
+chart.narrate();                 // [{ i, time, type, note, legPct?, legBars? }]
+chart.walk({ from: 0, to: 500, speed: 120, step: 10 });
+chart.addEventListener('wick:walk', (e) => {
+  // { phase: 'step' | 'end' | 'stop', index, events: [...], from, to }
+});
+chart.stopWalk();                // any pointer/wheel/key input stops it too
+```
+
+`narrateWindow` (the analyzer) is exported from `wickchart/core`.
+
+### Delta brush — drag-select with stats
+
+`<wick-chart brush>` makes a plain drag **select bars** instead of panning:
+a live band follows the pointer with a delta chip (Δ% · bars · high · low ·
+Σvol); on release the selection commits and fires `wick:brush` with the
+range statistics. Esc (or `clearBrush()`) clears it.
+
+```html
+<wick-chart brush></wick-chart>
+```
+
+```js
+chart.addEventListener('wick:brush', (e) => {
+  // { bars, from: {index, time}, to: {index, time}, delta, deltaPct,
+  //   firstOpen, lastClose, high, low, volume }
+});
+chart.brushSelection; // { i0, i1, stats } | null
+chart.clearBrush();
+```
+
+Brush mode replaces plain-drag panning (shift-drag still measures);
+replacing the dataset clears a committed selection. `brushStats` is
+exported from `wickchart/core`.
+
+### Story mode — guided tours of chart state
+
+A **story** is an array of **scenes** (view range, type, indicators,
+overlays, scenario, risk plan + title/note). `playStory()` applies each
+scene, eases the camera to its range, holds for `dwell`, and narrates
+through `wick:story`. Record scenes with `captureScene()` while you
+arrange the chart, or generate them from an analysis.
+
+```js
+const story = [chart.captureScene('Overview', 'the full picture')];
+story.push({ title: 'The breakout', range: { from, to }, indicators: 'sma:20' });
+chart.playStory(story, { dwell: 2200, panMs: 900, loop: false });
+chart.addEventListener('wick:story', (e) => {
+  // { phase: 'scene' | 'end' | 'stop', index, total, scene, title, note }
+});
+chart.stopStory(); chart.getStory();
+```
+
+Any user interaction stops the tour. Scenes are plain data — serialize
+or share them. `normalizeScene` / `sceneList` / `easeInOutCubic` are
+exported from `wickchart/core`.
+
 ### AI-ready data window — `getDataWindow()`
 
 One call turns whatever is on screen into a compact, LLM-pasteable summary.
@@ -483,13 +565,13 @@ range as a ~4-second pitch sequence, riding the crosshair along for sighted
 users. Audio starts lazily within the enabling user gesture (autoplay-policy
 safe).
 
-### Cross-tab co-view
+### Cross-tab co-view & presence
 
 Tag charts with the same channel and they share pointers — across browser
 tabs, or between multiple charts on one page:
 
 ```html
-<wick-chart co-view="btc-room"></wick-chart>
+<wick-chart co-view="btc-room" co-view-name="ben"></wick-chart>
 ```
 
 Hovering in one tab draws a ghost crosshair (accent, dotted, with the time
@@ -498,6 +580,20 @@ different history depths still line up. Ghosts fade ~2.5 s after the peer
 stops moving. Same-origin only (BroadcastChannel); the connection follows the
 `co-view` attribute and closes with the element.
 
+Peers also see **where everyone is looking**: each peer's viewport renders
+as a colored band (with name) along the top of the plot, updated live as
+they pan or zoom and swept away ~12 s after they go quiet.
+
+```js
+chart.getPeers(); // [{ id, name, range: { from, to }, at }]
+chart.addEventListener('wick:peers', (e) => {
+  // { peers, joined, left } — membership changes only
+});
+```
+
+`PresenceTracker` (the TTL bookkeeping) is exported from `wickchart/core`
+for apps that sync presence over their own transport instead.
+
 ### Smart annotations
 
 `<wick-chart annotations>` marks notable events on the visible range — volume

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wickchart",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "<wick-chart> — a modern, dependency-free financial charting web component. Candles, line & area charts, crosshair, zoom/pan, indicators (incl. a safe expression mini-language), live streaming via <wick-feed>, theming.",
   "type": "module",
   "main": "src/wick-chart.js",

package/src/core.js

@@ -1807,6 +1807,326 @@ export function normalizeScenario(spec) {
   };
 }
 
+/* ------------------------------------------------------------------ *
+ * 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
  * ------------------------------------------------------------------ */