wickchart 1.2.0 → 1.3.0

package/src/wick-chart.js

@@ -31,7 +31,9 @@ import {
   windowSummary, normalizeOverlays, barIndexForTime, resolveOverlayColor,
   compileScript, predicateTrueSeries, scriptAlertStep,
   AI_TOOLS, aiPromptText, applyChartOps,
-  calcVolCone, normalizeScenario,
+  calcVolCone, normalizeScenario, normalizeRiskPlan, PresenceTracker,
+  narrateWindow, brushStats,
+  easeInOutCubic, sceneList,
 } from './core.js';
 
 /* ------------------------------------------------------------------ *
@@ -48,7 +50,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', 'overlays', 'co-view', 'sonify'];
+      return ['theme', 'type', 'log', 'auto', 'indicators', 'precision', 'label', 'stats', 'profile', 'annotations', 'volshading', 'overlays', 'co-view', 'co-view-name', 'brush', 'sonify'];
     }
 
     constructor() {
@@ -205,6 +207,11 @@ class WickChart extends HTMLElementBase {
       this._coviewLast = 0;
       this._ghost = null;
       this._ghostTimer = 0;
+      // presence: peer viewports (who is looking where)
+      this._coviewLabel = null; // display name from the co-view-name attribute
+      this._presence = new PresenceTracker();
+      this._coviewBeat = 0;
+      this._coviewViewLast = 0;
 
       // sonification state
       this._sonify = false;
@@ -213,6 +220,15 @@ class WickChart extends HTMLElementBase {
       this._playToken = 0;
       this._measure = null; // { iA, pA, iB, pB, done }
       this._measuring = false;
+      // bar-walk narrator state
+      this._walkTimer = 0;
+      // story mode state: token cancels stale async runs
+      this._storyToken = 0;
+      this._story = null;
+      // delta brush state: mode flag + current/finished selection
+      this._brush = false;
+      this._brushSel = null; // { i0, i1, stats } — the committed selection
+      this._brushDrag = null; // { i0, i1 } — while the pointer is down
       this._ind = { overlays: [], panes: [], volume: true };
 
       this._pointers = new Map();
@@ -233,6 +249,8 @@ class WickChart extends HTMLElementBase {
 
       // scenario projection (ghost path + vol cone)
       this._scenario = null;
+      // risk plan (R-multiple grid)
+      this._riskPlan = null;
 
       this._onResize = () => this._invalidate();
       this._onPointerDown = (e) => this._pointerDown(e);
@@ -246,7 +264,10 @@ class WickChart extends HTMLElementBase {
         }
       };
       this._onWheel = (e) => this._wheel(e);
-      this._onDbl = () => this.fit();
+      this._onDbl = () => {
+        this._stopPlayback();
+        this.fit();
+      };
       this._onKey = (e) => this._keydown(e);
     }
 
@@ -280,12 +301,22 @@ class WickChart extends HTMLElementBase {
 
     disconnectedCallback() {
       this._connected = false;
+      this.stopWalk(true);
+      this.stopStory(true);
       if (this._coviewCh) {
+        this._coviewSend({ type: 'bye' });
         try {
           this._coviewCh.close();
         } catch (_) {}
         this._coviewCh = null;
       }
+      clearInterval(this._coviewBeat);
+      this._coviewBeat = 0;
+      if (this._presence && this._presence.peers.size) {
+        const left = this._presence.list();
+        this._presence = new PresenceTracker();
+        this._fire('peers', { peers: [], joined: [], left });
+      }
       clearTimeout(this._ghostTimer);
       if (this._ro) this._ro.disconnect();
       const cv = this._canvas;
@@ -355,6 +386,16 @@ class WickChart extends HTMLElementBase {
           this._coviewName = val || null;
           this._setupCoView();
           break;
+        case 'co-view-name':
+          // display name travels with every presence message; no re-render
+          this._coviewLabel = val || null;
+          break;
+        case 'brush':
+          this._brush = val != null && val !== 'false';
+          this._brushSel = null;
+          this._brushDrag = null;
+          this._invalidate();
+          break;
         case 'sonify':
           this._sonify = val != null && val !== 'false';
           this._lastToneIdx = -1;
@@ -424,6 +465,8 @@ class WickChart extends HTMLElementBase {
         this.clearData();
         return;
       }
+      // selection indices are data-bound; a replacement invalidates them
+      if (this._brushSel || this._brushDrag) this.clearBrush();
       const norm = [];
       for (const b of bars) {
         const nb = WickChart._normBar(b);
@@ -910,6 +953,41 @@ class WickChart extends HTMLElementBase {
       return { ...this._scenario, path: this._scenario.path.map((p) => ({ ...p })) };
     }
 
+    /**
+     * Risk plan: an R-multiple grid anchored at entry/stop. 1R = |entry −
+     * stop| (the risk unit); reward lines are drawn at kR beyond the entry
+     * with the risk/reward zones shaded, so sizing and take-profit choices
+     * read directly off the chart.
+     *
+     *   chart.setRiskPlan({ entry: 64500, stop: 63800, multiples: [1, 2, 3] });
+     *   chart.setRiskPlan({ entry: 64500, stop: 63800, targets: [65900, 67300] });
+     *
+     * Direction is derived (stop below entry ⇒ long). Targets convert to
+     * their R multiple; `multiples` win when both are given. Invalid specs
+     * clear the plan (replace semantics, like setScenario); excluded from
+     * getState/setState — it is app state, not chart state.
+     * @param {object} spec
+     * @returns {object|null} the normalized plan, or null when invalid
+     */
+    setRiskPlan(spec) {
+      this._riskPlan = normalizeRiskPlan(spec);
+      this._invalidate();
+      return this._riskPlan;
+    }
+
+    clearRiskPlan() {
+      if (this._riskPlan) {
+        this._riskPlan = null;
+        this._invalidate();
+      }
+    }
+
+    /** @returns {object|null} a copy of the active risk plan */
+    get riskPlan() {
+      if (!this._riskPlan) return null;
+      return { ...this._riskPlan, levels: this._riskPlan.levels.map((l) => ({ ...l })) };
+    }
+
     /** σ-cone for the active scenario, cached per data version. */
     _scenarioConeCache() {
       if (!this._scenario || !this._data.length) return null;
@@ -1799,6 +1877,67 @@ class WickChart extends HTMLElementBase {
         }
       }
 
+      /* risk plan: R-multiple grid — risk/reward shading + kR lines */
+      if (this._riskPlan && d.length) {
+        const rp = this._riskPlan;
+        const fP = numberFmt(this._prec(scale.rawHi || 1));
+        const yE = yOf(rp.entry);
+        const yS = yOf(rp.stop);
+        ctx.fillStyle = hexToRgba(pal.down, 0.06);
+        ctx.fillRect(0, Math.min(yE, yS), plotRight, Math.abs(yS - yE));
+        const yTop = yOf(rp.levels[rp.levels.length - 1].price);
+        ctx.fillStyle = hexToRgba(pal.up, 0.05);
+        ctx.fillRect(0, Math.min(yE, yTop), plotRight, Math.abs(yTop - yE));
+        const line = (p, col, dash) => {
+          const y = yOf(p);
+          if (y < main.y0 || y > main.y1) return null;
+          ctx.strokeStyle = col;
+          ctx.lineWidth = 1.5;
+          if (dash) ctx.setLineDash([5, 4]);
+          ctx.beginPath();
+          ctx.moveTo(0, Math.round(y) + 0.5);
+          ctx.lineTo(plotRight, Math.round(y) + 0.5);
+          ctx.stroke();
+          ctx.setLineDash([]);
+          ctx.lineWidth = 1;
+          return y;
+        };
+        const pills = [];
+        for (let i = rp.levels.length - 1; i >= 0; i--) {
+          const lv = rp.levels[i];
+          const y = line(lv.price, pal.up, true);
+          if (y != null) {
+            const kk = lv.k % 1 === 0 ? lv.k : +lv.k.toFixed(2);
+            pills.push({ y, text: `${kk}R ${fP.format(lv.price)}`, bg: pal.up });
+          }
+        }
+        const yStop = line(rp.stop, pal.down, false);
+        if (yStop != null) pills.push({ y: yStop, text: `STOP ${fP.format(rp.stop)}`, bg: pal.down });
+        const yEnt = line(rp.entry, pal.accent, false);
+        if (yEnt != null) {
+          pills.push({ y: yEnt, text: `${rp.direction === 'long' ? 'LONG' : 'SHORT'} ${fP.format(rp.entry)}`, bg: pal.accent });
+        }
+        // stack right-edge pills instead of letting close lines overlap
+        pills.sort((a, b) => a.y - b.y);
+        let lastY = -Infinity;
+        for (const p of pills) {
+          const y = Math.max(p.y, lastY + 20);
+          lastY = y;
+          ctx.font = pillFont();
+          const tw = ctx.measureText(p.text).width + 12;
+          this._pill(plotRight - tw - 8, y, p.text, p.bg, pal.pillText, 'left', tw);
+        }
+        if (rp.label) {
+          ctx.font = pillFont();
+          ctx.fillStyle = pal.accent;
+          ctx.globalAlpha = 0.9;
+          ctx.textAlign = 'left';
+          ctx.textBaseline = 'bottom';
+          ctx.fillText(rp.label, 8, clamp(yE, main.y0 + 14, main.y1) - 3);
+          ctx.globalAlpha = 1;
+        }
+      }
+
       /* volume profile (behind the series) */
       if (this._profile) {
         const pkey = `${i0}:${i1}:${this._version}`;
@@ -2458,6 +2597,34 @@ class WickChart extends HTMLElementBase {
         );
       }
 
+      /* co-view presence: peer viewport bands along the top of the plot */
+      if (this._presence && this._presence.peers.size && d.length) {
+        const peers = this._presence.list().slice(0, 4);
+        ctx.save();
+        ctx.font = pillFont();
+        for (let row = 0; row < peers.length; row++) {
+          const p = peers[row];
+          if (!p.range) continue;
+          const cols = pal.overlay || [];
+          const col = cols[(row + 1) % Math.max(cols.length, 1)] || pal.accent;
+          const i0 = WickChart._indexForTime(this._data, p.range.from);
+          const i1 = WickChart._indexForTime(this._data, p.range.to);
+          const x0 = clamp(this._xFor(i0), 0, plotRight);
+          const x1 = clamp(this._xFor(i1), 0, plotRight);
+          const y = main.y0 + 2 + row * 5;
+          ctx.globalAlpha = 0.8;
+          ctx.fillStyle = col;
+          ctx.fillRect(x0, y, Math.max(x1 - x0, 3), 3);
+          if (x1 - x0 > 44) {
+            ctx.globalAlpha = 0.95;
+            ctx.textAlign = 'left';
+            ctx.textBaseline = 'top';
+            ctx.fillText(p.name || p.id, x0 + 3, y + 4);
+          }
+        }
+        ctx.restore();
+      }
+
       /* co-view ghost crosshair (peer pointer from another tab/chart) */
       if (this._ghost) {
         const g = this._ghost;
@@ -2544,6 +2711,50 @@ class WickChart extends HTMLElementBase {
         );
       }
 
+      /* delta brush selection: band + live delta chip */
+      {
+        const sel = this._brushDrag || this._brushSel;
+        if (sel && d.length) {
+          const bi0 = Math.min(sel.i0, sel.i1);
+          const bi1 = Math.max(sel.i0, sel.i1);
+          const xa = this._xFor(bi0) - this._view.spacing / 2;
+          const xb = this._xFor(bi1) + this._view.spacing / 2;
+          const bx0 = clamp(Math.min(xa, xb), 0, plotRight);
+          const bx1 = clamp(Math.max(xa, xb), 0, plotRight);
+          if (bx1 - bx0 > 1) {
+            const live = this._brushDrag ? brushStats(this._data, bi0, bi1) : sel.stats;
+            ctx.save();
+            ctx.fillStyle = hexToRgba(pal.accent, this._brushDrag ? 0.13 : 0.08);
+            ctx.fillRect(bx0, main.y0, bx1 - bx0, main.h);
+            ctx.globalAlpha = 0.55;
+            ctx.strokeStyle = pal.accent;
+            ctx.lineWidth = 1;
+            if (!this._brushDrag) ctx.setLineDash([4, 3]);
+            ctx.strokeRect(bx0 + 0.5, main.y0 + 0.5, bx1 - bx0 - 1, main.h - 1);
+            ctx.setLineDash([]);
+            ctx.restore();
+            if (live) {
+              const fP = numberFmt(this._prec(Math.abs(live.lastClose) || 1));
+              const sign = live.delta >= 0 ? '+' : '';
+              const txt =
+                `${sign}${live.deltaPct.toFixed(2)}% · ${live.bars} bars · ` +
+                `H ${fP.format(live.high)} · L ${fP.format(live.low)} · Σvol ${fmtCompact(live.volume)}`;
+              ctx.font = pillFont();
+              const tw = ctx.measureText(txt).width + 12;
+              this._pill(
+                clamp((bx0 + bx1) / 2 - tw / 2, 2, plotRight - tw - 2),
+                main.y0 + 11,
+                txt,
+                live.delta >= 0 ? pal.up : pal.down,
+                pal.pillText,
+                'left',
+                tw
+              );
+            }
+          }
+        }
+      }
+
       /* visible-range stats chip */
       if (this._stats) {
         const st = computeStats(d, i0, i1, this._dt);
@@ -2712,6 +2923,7 @@ class WickChart extends HTMLElementBase {
 
     _pointerDown(e) {
       if (e.button !== 0) return;
+      this._stopPlayback(); // any touch interrupts the story
       this._canvas.setPointerCapture(e.pointerId);
       const pt = this._localPoint(e);
       this._pointers.set(e.pointerId, pt);
@@ -2726,6 +2938,15 @@ class WickChart extends HTMLElementBase {
         };
         this._pan = null;
         this._measuring = false;
+        this._brushDrag = null;
+      } else if (this._brush && !e.shiftKey && this._data.length) {
+        // brush mode: plain drag selects a bar range (shift still measures)
+        const idx = clamp(Math.round(this._indexForX(pt.x)), 0, this._data.length - 1);
+        this._brushDrag = { i0: idx, i1: idx };
+        this._brushSel = null;
+        this._measuring = false;
+        this._pan = null;
+        this._invalidate();
       } else if (e.shiftKey && this._data.length) {
         // shift+drag → measure tool
         this._measuring = true;
@@ -2777,6 +2998,13 @@ class WickChart extends HTMLElementBase {
         return;
       }
 
+      if (this._brushDrag && this._pointers.has(e.pointerId) && this._data.length) {
+        const idx = clamp(Math.round(this._indexForX(pt.x)), 0, this._data.length - 1);
+        this._brushDrag.i1 = idx;
+        this._invalidate();
+        return;
+      }
+
       if (this._pan && this._pointers.has(e.pointerId) && ly) {
         const dx = pt.x - this._pan.x;
         if (Math.abs(dx) > 3) this._pan.moved = true;
@@ -2802,7 +3030,11 @@ class WickChart extends HTMLElementBase {
       if (this._pointers.size < 2) this._pinch = null;
       if (this._pointers.size === 0) {
         this._canvas.classList.remove('grabbing');
-        if (this._measuring) {
+        if (this._brushDrag && had) {
+          const b = this._brushDrag;
+          this._brushDrag = null;
+          this._brushFinish(Math.min(b.i0, b.i1), Math.max(b.i0, b.i1));
+        } else if (this._measuring) {
           this._measuring = false;
           if (this._measure) {
             this._measure.done = true;
@@ -2846,6 +3078,7 @@ class WickChart extends HTMLElementBase {
     _wheel(e) {
       const ly = this._ly;
       if (!ly || !this._data.length) return;
+      this._stopPlayback();
       e.preventDefault();
       const pt = this._localPoint(e);
       const dx = e.deltaX;
@@ -2879,6 +3112,11 @@ class WickChart extends HTMLElementBase {
     _keydown(e) {
       const ly = this._ly;
       if (!ly || !this._data.length) return;
+      this._stopPlayback();
+      if (e.key === 'Escape' && (this._brushSel || this._brushDrag)) {
+        this.clearBrush();
+        return;
+      }
       const d = this._data;
       const key = e.key;
       const step = e.shiftKey ? 10 : 1;
@@ -3067,11 +3305,18 @@ class WickChart extends HTMLElementBase {
         } catch (_) {}
         this._coviewCh = null;
       }
+      clearInterval(this._coviewBeat);
+      this._coviewBeat = 0;
       clearTimeout(this._ghostTimer);
       if (this._ghost) {
         this._ghost = null;
         this._invalidate();
       }
+      if (this._presence && this._presence.peers.size) {
+        const left = this._presence.list();
+        this._presence = new PresenceTracker();
+        this._fire('peers', { peers: [], joined: [], left });
+      }
       const name = this._coviewName;
       if (!name || !this._connected || typeof BroadcastChannel === 'undefined') return;
       if (!this._coviewPeer) this._coviewPeer = 'p' + Math.random().toString(36).slice(2, 8);
@@ -3080,6 +3325,33 @@ class WickChart extends HTMLElementBase {
         ch.onmessage = (ev) => this._onCoMessage(ev.data);
         this._coviewCh = ch;
       } catch (_) {}
+      // presence: announce immediately, then heartbeat so idle peers stay
+      // warm (and stale ones sweep) without waiting for a pan/zoom
+      this._coviewSendView(true);
+      this._coviewBeat = setInterval(() => {
+        this._coviewSendView(true);
+        const left = this._presence.sweep();
+        if (left.length) {
+          this._fire('peers', { peers: this._presence.list(), joined: [], left });
+          this._invalidate();
+        }
+      }, 4000);
+    }
+
+    /** Broadcast our visible range for presence; throttled unless forced. */
+    _coviewSendView(force) {
+      if (!this._coviewCh) return;
+      const r = this.getVisibleRange();
+      if (!r) return;
+      const now = performance.now();
+      if (!force && now - this._coviewViewLast < 120) return;
+      this._coviewViewLast = now;
+      this._coviewSend({
+        type: 'view',
+        from: r.from,
+        to: r.to,
+        name: this._coviewLabel || null,
+      });
     }
 
     _coviewSend(msg) {
@@ -3090,7 +3362,30 @@ class WickChart extends HTMLElementBase {
     }
 
     _onCoMessage(m) {
-      if (!m || m.v !== 1 || m.peer === this._coviewPeer || m.type !== 'cross') return;
+      if (!m || m.v !== 1 || m.peer === this._coviewPeer) return;
+      if (m.type === 'view') {
+        const joined = this._presence.track(m.peer, {
+          range: { from: m.from, to: m.to },
+          name: m.name,
+        });
+        this._invalidate();
+        if (joined) {
+          const p = this._presence.peers.get(m.peer);
+          this._fire('peers', {
+            peers: this._presence.list(),
+            joined: [p ? { ...p, range: p.range && { ...p.range } } : { id: m.peer }],
+            left: [],
+          });
+        }
+        return;
+      }
+      if (m.type === 'bye') {
+        const left = this._presence.drop(m.peer);
+        if (left) this._fire('peers', { peers: this._presence.list(), joined: [], left: [left] });
+        this._invalidate();
+        return;
+      }
+      if (m.type !== 'cross') return;
       if (m.time == null) {
         if (this._ghost) {
           this._ghost = null;
@@ -3120,10 +3415,297 @@ class WickChart extends HTMLElementBase {
       this.dispatchEvent(new CustomEvent('hab:' + name, { detail }));
     }
 
+    /**
+     * Live co-view peers: who else is in the room and the time window each
+     * one is looking at — [{ id, name, range: {from, to}, at }], oldest
+     * sighting first. Peers fade out ~12 s after their last sighting.
+     * @returns {object[]}
+     */
+    getPeers() {
+      return this._presence ? this._presence.list() : [];
+    }
+
+    /**
+     * Narrated timeline for a window (default: the visible range) — pivot
+     * highs/lows, volume spikes, gaps, RSI divergences plus derived legs
+     * ("+12.4% over 38 bars"), sorted by index. Pure data, perfect for
+     * caption UIs or the walk player.
+     *   chart.narrate();                        // visible range
+     *   chart.narrate({ from, to });            // times in ms (s accepted)
+     * @param {{from?: number, to?: number}} [range]
+     * @returns {{i: number, time: number, type: string, side: string, note: string,
+     *            legPct?: number, legBars?: number}[]}
+     */
+    narrate(range) {
+      const d = this._data;
+      if (!d.length) return [];
+      let i0 = 0;
+      let i1 = d.length - 1;
+      if (range && isNum(range.from) && isNum(range.to)) {
+        i0 = WickChart._indexForTime(d, WickChart._timeToMs(range.from));
+        i1 = WickChart._indexForTime(d, WickChart._timeToMs(range.to));
+        if (i0 > i1) [i0, i1] = [i1, i0];
+      }
+      return narrateWindow(d, i0, i1);
+    }
+
+    /**
+     * Walk the chart through history like a story: the viewport slides
+     * from `from` to `to` while `wick:walk` events announce every step and
+     * the narrator's events (spikes, gaps, pivots, legs) as they're crossed.
+     * Any user interaction — pointer, wheel, keys, double-click — stops it.
+     *   chart.walk({ from: 0, to: 500, speed: 120, step: 10 });
+     *   chart.addEventListener('wick:walk', (e) => showCaption(e.detail));
+     *   // detail: { phase: 'step'|'end'|'stop', index, events: [...], from, to }
+     * @param {{from?: number, to?: number, speed?: number, step?: number}} [opts]
+     *        from/to are bar indices (default: last ~500 bars → the end)
+     * @returns {boolean} true when the walk started
+     */
+    walk(opts = {}) {
+      this.stopWalk(true);
+      const d = this._data;
+      if (!d.length || !this._connected) return false;
+      const to = clamp(Math.round(+opts.to || d.length - 1), 0, d.length - 1);
+      const from = clamp(Math.round(opts.from != null ? +opts.from : Math.max(0, to - 500)), 0, to);
+      const span = to - from + 1;
+      // window width: the current viewport, but never more than ~⅓ of the
+      // span (a fully zoomed-out chart would otherwise start at `to`)
+      const widthBars = clamp(
+        Math.min(
+          this._ly ? Math.round(this._ly.plotRight / this._view.spacing) : 120,
+          Math.max(10, Math.ceil(span / 3))
+        ),
+        10,
+        span
+      );
+      const events = narrateWindow(d, from, to, { pivot: 8 });
+      const speed = clamp(Math.round(+opts.speed || 120), 16, 2000);
+      const step = clamp(Math.round(+opts.step || Math.max(1, Math.round(widthBars / 12))), 1, 500);
+      let cursor = Math.min(from + widthBars - 1, to);
+      let ev = 0;
+      let ended = false;
+      const tick = () => {
+        if (ended) return;
+        this._auto = false;
+        this._view.rightIndex = cursor;
+        this._clampView();
+        this._invalidate();
+        this._emitRange();
+        const hits = [];
+        while (ev < events.length && events[ev].i <= cursor) hits.push(events[ev++]);
+        this._fire('walk', { phase: 'step', index: cursor, events: hits, from, to });
+        if (cursor >= to) {
+          ended = true;
+          clearInterval(this._walkTimer);
+          this._walkTimer = 0;
+          this._fire('walk', { phase: 'end', index: cursor, events: [], from, to });
+        } else {
+          cursor = Math.min(cursor + step, to);
+        }
+      };
+      this._walkTimer = setInterval(tick, speed);
+      tick(); // first step lands immediately
+      return true;
+    }
+
+    /**
+     * Stop the running walk (if any). Fires a final `wick:walk`
+     * { phase: 'stop' } unless called internally.
+     */
+    stopWalk(silent) {
+      if (!this._walkTimer) return;
+      clearInterval(this._walkTimer);
+      this._walkTimer = 0;
+      if (!silent) this._fire('walk', { phase: 'stop' });
+    }
+
+    /**
+     * Commit a brush selection over [i0, i1]: stores it (draws the band
+     * and delta chip) and fires `wick:brush` with the range statistics.
+     * @param {number} i0 first index
+     * @param {number} i1 last index
+     */
+    _brushFinish(i0, i1) {
+      if (!this._data.length) return;
+      const stats = brushStats(this._data, i0, i1);
+      if (!stats) {
+        this._brushSel = null;
+        this._invalidate();
+        return;
+      }
+      this._brushSel = { i0, i1, stats };
+      this._invalidate();
+      this._fire('brush', stats);
+    }
+
+    /** Clear the committed brush selection (if any). Escape does the same. */
+    clearBrush() {
+      if (this._brushSel || this._brushDrag) {
+        this._brushSel = null;
+        this._brushDrag = null;
+        this._invalidate();
+      }
+    }
+
+    /** @returns {object|null} the committed selection { i0, i1, stats } */
+    get brushSelection() {
+      if (!this._brushSel) return null;
+      const { i0, i1, stats } = this._brushSel;
+      return { i0, i1, stats: { ...stats, from: { ...stats.from }, to: { ...stats.to } } };
+    }
+
+    /**
+     * Capture the current chart state as a story scene: view, series type,
+     * indicators, overlays, scenario and risk plan, plus a title/note.
+     * Build guided tours by capturing several and playing them back.
+     *   const story = [
+     *     chart.captureScene('Overview', 'The full picture'),
+     *     { title: 'The breakout', range: { from, to }, indicators: 'sma:20' },
+     *   ];
+     *   chart.playStory(story);
+     * @param {string} [title]
+     * @param {string} [note]
+     * @returns {object} scene (plain data — snapshot of the moment)
+     */
+    captureScene(title, note) {
+      const scene = {
+        title: title != null ? String(title).slice(0, 60) : '',
+        note: note != null ? String(note).slice(0, 200) : '',
+        range: this.getVisibleRange() || undefined,
+        type: this.getAttribute('type') || 'candles',
+        indicators: this.getAttribute('indicators') || null,
+      };
+      const ovs = this.overlays;
+      if (ovs.length) scene.overlays = ovs;
+      const sc = this.scenario;
+      if (sc) scene.scenario = sc;
+      const rp = this.riskPlan;
+      if (rp) scene.riskPlan = rp;
+      return scene;
+    }
+
+    /** @returns {object[]|null} a copy of the last played story */
+    getStory() {
+      return this._story ? this._story.map((s) => ({ ...s })) : null;
+    }
+
+    /**
+     * Play a story: each scene applies its state (type / indicators /
+     * overlays / scenario / risk plan — set or clear), the camera eases
+     * to its range, then holds for its dwell. `wick:story` events narrate:
+     *   { phase: 'scene' | 'end' | 'stop', index, total, scene, title, note }
+     * Any user interaction — pointer, wheel, keys, double-click — stops it.
+     * @param {object[]} story scenes (invalid entries dropped, max 20)
+     * @param {{dwell?: number, panMs?: number, loop?: boolean}} [opts]
+     *        panMs clamps 100–5000 (default 900); loop replays forever
+     * @returns {boolean} true when playback started
+     */
+    playStory(story, opts = {}) {
+      this.stopStory(true);
+      const scenes = sceneList(story);
+      if (!scenes.length || !this._data.length || !this._connected) return false;
+      const token = ++this._storyToken;
+      this._story = scenes;
+      const panMs = clamp(Math.round(+opts.panMs || 900), 100, 5000);
+      const loop = opts.loop === true;
+      const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+      const run = async () => {
+        let idx = 0;
+        while (token === this._storyToken) {
+          const sc = scenes[idx];
+          this._fire('story', {
+            phase: 'scene', index: idx, total: scenes.length,
+            scene: sc, title: sc.title, note: sc.note,
+          });
+          this._applyScene(sc);
+          const target = this._sceneTarget(sc);
+          if (target) await this._storyTween(target, panMs, token);
+          if (token !== this._storyToken) return;
+          await wait(sc.dwell);
+          if (token !== this._storyToken) return;
+          idx++;
+          if (idx >= scenes.length) {
+            if (loop) idx = 0;
+            else {
+              this._fire('story', { phase: 'end', index: idx - 1, total: scenes.length });
+              return;
+            }
+          }
+        }
+      };
+      run();
+      return true;
+    }
+
+    /**
+     * Stop story playback (if running). Fires a final `wick:story`
+     * { phase: 'stop' } unless called internally.
+     */
+    stopStory(silent) {
+      if (!this._storyToken) return;
+      this._storyToken = 0;
+      if (!silent) this._fire('story', { phase: 'stop' });
+    }
+
+    /** Apply a scene's state (only the fields it carries). */
+    _applyScene(sc) {
+      if (sc.type) this.setAttribute('type', sc.type);
+      if (sc.indicators != null) this.setAttribute('indicators', sc.indicators);
+      if (sc.overlays) this.setOverlays(sc.overlays);
+      if (sc.scenario === 'clear') this.clearScenario();
+      else if (sc.scenario) this.setScenario(sc.scenario);
+      if (sc.riskPlan === 'clear') this.clearRiskPlan();
+      else if (sc.riskPlan) this.setRiskPlan(sc.riskPlan);
+    }
+
+    /** Map a scene's time range to bar indices (null when not applicable). */
+    _sceneTarget(sc) {
+      if (!sc.range || !this._data.length) return null;
+      let i0 = WickChart._indexForTime(this._data, WickChart._timeToMs(sc.range.from));
+      let i1 = WickChart._indexForTime(this._data, WickChart._timeToMs(sc.range.to));
+      if (i0 > i1) [i0, i1] = [i1, i0];
+      return i1 - i0 >= 2 ? { i0, i1 } : null;
+    }
+
+    /** Ease the viewport to { i0, i1 } over `ms`; resolves early if the
+     *  token changes (superseded or stopped). rAF when available. */
+    _storyTween(target, ms, token) {
+      const ly = this._ly;
+      const d = this._data;
+      if (!ly || !d.length) return Promise.resolve();
+      const sp1 = clamp(ly.plotRight / (target.i1 - target.i0), this._minSpacing(), WickChart._MAX_SP);
+      const from = { right: this._view.rightIndex, sp: this._view.spacing };
+      const to = { right: target.i1, sp: sp1 };
+      const t0 = performance.now();
+      this._auto = false;
+      return new Promise((resolve) => {
+        const step = () => {
+          if (token !== this._storyToken) return resolve();
+          const e = easeInOutCubic(Math.min(1, (performance.now() - t0) / ms));
+          this._view.rightIndex = from.right + (to.right - from.right) * e;
+          this._view.spacing = from.sp + (to.sp - from.sp) * e;
+          this._clampView();
+          this._invalidate();
+          this._emitRange();
+          if (e >= 1) resolve();
+          else if (typeof requestAnimationFrame === 'function') requestAnimationFrame(step);
+          else setTimeout(step, 16);
+        };
+        step();
+      });
+    }
+
+    /** Interrupt narrated playback (walk / story) on user input. */
+    _stopPlayback() {
+      if (this._walkTimer) this.stopWalk();
+      if (this._storyToken) this.stopStory();
+    }
+
     _emitRange() {
       const r = this.getVisibleRange();
       if (!r) return;
       this._fire('range', r);
+      if (this._coviewCh) this._coviewSendView();
     }
   }