wickchart 1.0.0 → 1.3.0

package/src/wick-chart.js

@@ -28,7 +28,12 @@ import {
   SERIES_TYPES, calcHeikinAshi, buildColumns, computeVolumeProfile,
   calcRSI, detectAnnotations, priceToFreq,
   calcRealizedVol, volRegimeBands, percentileOfSorted, parseVolShading,
-  windowSummary,
+  windowSummary, normalizeOverlays, barIndexForTime, resolveOverlayColor,
+  compileScript, predicateTrueSeries, scriptAlertStep,
+  AI_TOOLS, aiPromptText, applyChartOps,
+  calcVolCone, normalizeScenario, normalizeRiskPlan, PresenceTracker,
+  narrateWindow, brushStats,
+  easeInOutCubic, sceneList,
 } from './core.js';
 
 /* ------------------------------------------------------------------ *
@@ -45,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', 'co-view', 'sonify'];
+      return ['theme', 'type', 'log', 'auto', 'indicators', 'precision', 'label', 'stats', 'profile', 'annotations', 'volshading', 'overlays', 'co-view', 'co-view-name', 'brush', 'sonify'];
     }
 
     constructor() {
@@ -202,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;
@@ -210,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();
@@ -225,6 +244,14 @@ class WickChart extends HTMLElementBase {
       this._alerts = [];
       this._seq = 0;
 
+      // server-side overlays (zones & levels)
+      this._overlays = [];
+
+      // scenario projection (ghost path + vol cone)
+      this._scenario = null;
+      // risk plan (R-multiple grid)
+      this._riskPlan = null;
+
       this._onResize = () => this._invalidate();
       this._onPointerDown = (e) => this._pointerDown(e);
       this._onPointerMove = (e) => this._pointerMove(e);
@@ -237,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);
     }
 
@@ -271,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;
@@ -330,10 +370,32 @@ class WickChart extends HTMLElementBase {
           this._volshade = val != null && val !== 'false' ? parseVolShading(val) : null;
           this._legendKey = '';
           break;
+        case 'overlays': {
+          let ovs = [];
+          if (val != null && val !== '') {
+            try {
+              ovs = normalizeOverlays(JSON.parse(val));
+            } catch (err) {
+              ovs = [];
+            }
+          }
+          this._overlays = ovs;
+          break;
+        }
         case 'co-view':
           this._coviewName = val || null;
           this._setupCoView();
           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;
@@ -403,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);
@@ -629,7 +693,11 @@ class WickChart extends HTMLElementBase {
         })),
         alerts: this._alerts
           .filter((a) => !a.fired)
-          .map((a) => ({ id: a.id, price: a.price, direction: a.direction, once: a.once })),
+          .map((a) =>
+            a.when != null
+              ? { id: a.id, when: a.when, once: a.once }
+              : { id: a.id, price: a.price, direction: a.direction, once: a.once }
+          ),
       };
     }
 
@@ -667,14 +735,31 @@ class WickChart extends HTMLElementBase {
       }
       if (Array.isArray(state.alerts)) {
         this._alerts = state.alerts
-          .filter((a) => a && isNum(a.price))
-          .map((a) => ({
-            id: a.id != null ? String(a.id) : 'alert-' + ++this._seq,
-            price: a.price,
-            direction: a.direction || 'cross',
-            once: a.once !== false,
-            fired: false,
-          }));
+          .filter((a) => a && (isNum(a.price) || typeof a.when === 'string'))
+          .map((a) => {
+            if (typeof a.when === 'string' && a.when.trim()) {
+              try {
+                return {
+                  id: a.id != null ? String(a.id) : 'alert-' + ++this._seq,
+                  when: a.when.trim(),
+                  compiled: compileScript(a.when),
+                  once: a.once !== false,
+                  fired: false,
+                  armed: true,
+                };
+              } catch (err) {
+                return null;
+              }
+            }
+            return {
+              id: a.id != null ? String(a.id) : 'alert-' + ++this._seq,
+              price: a.price,
+              direction: a.direction || 'cross',
+              once: a.once !== false,
+              fired: false,
+            };
+          })
+          .filter(Boolean);
       }
       if (state.view && state.view.from != null && state.view.to != null) {
         if (this._ly && this._data.length > 1) {
@@ -727,22 +812,46 @@ class WickChart extends HTMLElementBase {
     }
 
     /**
-     * Price alert. Fires `wick:alert` ({id, price, bar}) on an edge crossing
-     * (plus the deprecated `hab:alert` alias)
-     * during streaming updates.
-     * @param {{id?: string, price: number, direction?: 'above'|'below'|'cross',
-     *          once?: boolean}} alert
-     * @returns {string|null} the alert id
+     * Price or scripted alert. Price alerts fire `wick:alert`
+     * ({id, price, bar}) on an edge crossing; scripted alerts evaluate a
+     * WickScript predicate (`when`) on every streamed bar and fire on its
+     * false→true edge — e.g. `when: 'crossup(rsi(close,14), 30)'` or
+     * `when: 'volume > sma(volume,20) * 3'`. Scripted events carry the
+     * triggering close as `price` plus the `when` source (deprecated
+     * `hab:alert` alias still dispatched).
+     * @param {{id?: string, price?: number, direction?: 'above'|'below'|'cross',
+     *          when?: string, once?: boolean}} alert
+     * @returns {string|null} the alert id (null when no valid price/when,
+     *          or the predicate fails to compile)
      */
     addAlert(alert) {
-      if (!alert || !isNum(alert.price)) return null;
-      const a = {
-        id: alert.id != null ? String(alert.id) : 'alert-' + ++this._seq,
-        price: alert.price,
-        direction: alert.direction || 'cross',
-        once: alert.once !== false,
-        fired: false,
-      };
+      if (!alert) return null;
+      let a;
+      if (typeof alert.when === 'string' && alert.when.trim()) {
+        let compiled;
+        try {
+          compiled = compileScript(alert.when);
+        } catch (err) {
+          return null;
+        }
+        a = {
+          id: alert.id != null ? String(alert.id) : 'alert-' + ++this._seq,
+          when: alert.when.trim(),
+          compiled,
+          once: alert.once !== false,
+          fired: false,
+          armed: true,
+        };
+      } else {
+        if (!isNum(alert.price)) return null;
+        a = {
+          id: alert.id != null ? String(alert.id) : 'alert-' + ++this._seq,
+          price: alert.price,
+          direction: alert.direction || 'cross',
+          once: alert.once !== false,
+          fired: false,
+        };
+      }
       const i = this._alerts.findIndex((x) => x.id === a.id);
       if (i >= 0) this._alerts[i] = a;
       else this._alerts.push(a);
@@ -760,11 +869,229 @@ class WickChart extends HTMLElementBase {
       this._invalidate();
     }
 
-    /** Check alerts against an incoming bar (prev close → new close). */
+    /**
+     * Server-side overlays: zones & levels anchored in time × price — e.g.
+     * supply/demand zones from an analysis API. Zones with no `to` extend
+     * into future space past the last bar, like TradingView drawings.
+     *
+     *   zone:  { type:'zone', from?:ms, to?:ms|null, priceFrom, priceTo,
+     *            color?, alpha?, border?, label?, id? }
+     *   level: { type:'level', price, from?, to?, color?, width?, dash?,
+     *            label?, id? }
+     *
+     * Invalid entries are dropped, never thrown. Colors accept hex/rgb()/CSS
+     * names plus the palette keys 'up' | 'down' | 'accent'.
+     * @param {object[]} list
+     * @returns {string[]} applied overlay ids
+     */
+    setOverlays(list) {
+      this._overlays = normalizeOverlays(list);
+      this._invalidate();
+      return this._overlays.map((o) => o.id);
+    }
+
+    /** @returns {object[]} a copy of the current overlays */
+    get overlays() {
+      return this._overlays.map((o) => ({ ...o }));
+    }
+
+    /**
+     * Add or replace (upsert, by id) a single overlay.
+     * @returns {string|null} the overlay id, or null if invalid
+     */
+    addOverlay(ov) {
+      const norm = normalizeOverlays([ov]);
+      if (!norm.length) return null;
+      const one = norm[0];
+      const i = this._overlays.findIndex((x) => x.id === one.id);
+      if (i >= 0) this._overlays[i] = one;
+      else this._overlays.push(one);
+      this._invalidate();
+      return one.id;
+    }
+
+    removeOverlay(id) {
+      this._overlays = this._overlays.filter((o) => o.id !== String(id));
+      this._invalidate();
+    }
+
+    clearOverlays() {
+      this._overlays = [];
+      this._invalidate();
+    }
+
+    /**
+     * Scenario projection into future space: a ghost path of future prices
+     * plus optional σ-bands (vol cone) from realized volatility.
+     *
+     *   chart.setScenario({ path: [64000, 65500, 68000], label: 'bull case' });
+     *   chart.setScenario({ horizon: 48, cone: true });   // cone-only
+     *
+     * The path is an array of prices (or {price} objects) for future bars
+     * 1..N; horizon defaults to the path length (1–500). `cone` (default
+     * true) draws ±levels·σ bands widening with √h from the current realized
+     * vol; `color` accepts up|down|accent or safe CSS colors. Setting a
+     * scenario reserves future space on the right; analysis data — excluded
+     * from getState/setState.
+     * @param {object} spec
+     * @returns {object|null} the normalized scenario, or null when invalid
+     */
+    setScenario(spec) {
+      this._scenario = normalizeScenario(spec);
+      this._invalidate();
+      return this._scenario;
+    }
+
+    clearScenario() {
+      this._scenario = null;
+      this._invalidate();
+    }
+
+    /** @returns {object|null} a copy of the active scenario */
+    get scenario() {
+      if (!this._scenario) return null;
+      return { ...this._scenario, path: this._scenario.path.map((p) => ({ ...p })) };
+    }
+
+    /**
+     * 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;
+      if (this._cache.v !== this._version) {
+        this._cache = { v: this._version, map: {} };
+      }
+      if (!this._cache.map.__scenario) {
+        const d = this._data;
+        const vol = calcRealizedVol(d.map((b) => b.close), 20);
+        let v = NaN;
+        for (let i = vol.length - 1; i >= 0; i--) {
+          if (Number.isFinite(vol[i])) { v = vol[i]; break; }
+        }
+        this._cache.map.__scenario = calcVolCone(
+          d[d.length - 1].close,
+          v,
+          this._scenario.horizon,
+          this._scenario.levels
+        );
+      }
+      return this._cache.map.__scenario;
+    }
+
+    /* ------------------------------------------------------------ *
+     * AI agent interface — the chart as a tool surface
+     * ------------------------------------------------------------ */
+
+    /** Tool manifest for LLM control — JSON-safe copy of AI_TOOLS. */
+    aiTools() {
+      return JSON.parse(JSON.stringify(AI_TOOLS));
+    }
+
+    /** System prompt for agent control — paste into any LLM alongside aiTools(). */
+    aiPrompt() {
+      return aiPromptText();
+    }
+
+    /** Grounding context for a model: current state + visible-window summary. */
+    aiContext() {
+      return { state: this.getState(), window: this.getDataWindow() };
+    }
+
+    /**
+     * Apply a list of {tool, args} ops (typically LLM output) through the
+     * validated dispatcher in core. Never throws — each op resolves
+     * {ok, tool, result} or {ok: false, tool, error} so an agent can
+     * self-correct.
+     * @param {any} ops
+     * @returns {Array<object>}
+     */
+    applyAI(ops) {
+      return applyChartOps(this, ops);
+    }
+
+    /**
+     * Ask an AI to operate the chart. Builds the payload {system,
+     * instruction, chart, tools}; with a `run` async function (your model
+     * call — the chart itself never touches the network), applies the
+     * returned ops and resolves {payload, ops, results}. Without `run`,
+     * returns the payload for manual wiring — send it anywhere, then call
+     * chart.applyAI(ops) with the model's answer.
+     *
+     *   const { results } = await chart.ask('add RSI and mark the demand zone', {
+     *     run: async (payload) => (await callMyLLM(payload)).ops,
+     *   });
+     *
+     * @param {string} instruction natural-language request
+     * @param {{run?: (payload: object) => Promise<any>}} [opts]
+     */
+    async ask(instruction, opts = {}) {
+      const payload = {
+        system: aiPromptText(),
+        instruction: String(instruction == null ? '' : instruction),
+        chart: this.aiContext(),
+        tools: this.aiTools(),
+      };
+      if (typeof opts.run !== 'function') {
+        return { payload, ops: null, results: null };
+      }
+      const ops = await opts.run(payload);
+      const results = this.applyAI(ops);
+      return { payload, ops, results };
+    }
+
+    /** Check alerts against an incoming bar (prev close → new close).
+     *  Scripted (`when`) alerts evaluate their predicate series, cached per
+     *  data version, and fire on the false→true edge. */
     _checkAlerts(prevClose, bar) {
-      if (!this._alerts.length || !isNum(prevClose)) return;
+      if (!this._alerts.length) return;
       for (const a of [...this._alerts]) {
         if (a.fired) continue;
+        if (a.when != null) {
+          const series = this._predicateCache(a);
+          const curTrue = series.length ? series[series.length - 1] : false;
+          const step = scriptAlertStep(a.armed, curTrue);
+          a.armed = step.armed;
+          if (step.fire) {
+            a.fired = true;
+            this._fire('alert', { id: a.id, price: bar.close, when: a.when, bar });
+            if (a.once) this._alerts = this._alerts.filter((x) => x !== a);
+          }
+          continue;
+        }
+        if (!isNum(prevClose)) continue;
         if (checkAlertCross(a, prevClose, bar.close)) {
           a.fired = true;
           this._fire('alert', { id: a.id, price: a.price, bar });
@@ -773,6 +1100,18 @@ class WickChart extends HTMLElementBase {
       }
     }
 
+    /** Cached boolean series for a scripted alert's predicate (per data version). */
+    _predicateCache(alert) {
+      if (this._cache.v !== this._version) {
+        this._cache = { v: this._version, map: {} };
+      }
+      const k = 'pred:' + alert.when;
+      if (!this._cache.map[k]) {
+        this._cache.map[k] = predicateTrueSeries(alert.compiled, this._data);
+      }
+      return this._cache.map[k];
+    }
+
     /* reflected properties */
     get theme() { return this._theme; }
     set theme(v) { this.setAttribute('theme', v); }
@@ -1013,7 +1352,9 @@ class WickChart extends HTMLElementBase {
     _rightMargin() {
       const ly = this._ly;
       const w = ly ? ly.plotRight : 600;
-      return Math.max(3, (w / this._view.spacing) * 0.06);
+      const base = Math.max(3, (w / this._view.spacing) * 0.06);
+      // a scenario projection reserves future space so the cone stays visible
+      return this._scenario ? Math.max(base, this._scenario.horizon + 3) : base;
     }
 
     _applyFit() {
@@ -1381,6 +1722,146 @@ class WickChart extends HTMLElementBase {
         }
       }
 
+      /* server-side overlays: zones & levels (above regime shading, under series).
+       * Zones with `to == null` extend into future space past the last bar. */
+      if (this._overlays.length) {
+        const d = this._data;
+        const idxFor = (t, fallback) => (t == null ? fallback : barIndexForTime(d, t));
+        for (const ov of this._overlays) {
+          const col = resolveOverlayColor(ov.color, pal);
+          if (ov.type === 'zone') {
+            const iA = Math.max(0, idxFor(ov.from, 0));
+            const iB = ov.to == null ? null : Math.max(0, idxFor(ov.to, d.length - 1));
+            const zx0 = clamp(this._xFor(iA) - sp * 0.5, 0, plotRight);
+            const zx1 = iB == null ? plotRight : clamp(this._xFor(iB) + sp * 0.5, 0, plotRight);
+            const zyT = clamp(yOf(ov.priceTo), main.y0, main.y1);
+            const zyB = clamp(yOf(ov.priceFrom), main.y0, main.y1);
+            if (zx1 - zx0 < 1 || zyB - zyT < 1) continue;
+            ctx.save();
+            ctx.globalAlpha = ov.alpha;
+            ctx.fillStyle = col;
+            ctx.fillRect(zx0, zyT, zx1 - zx0, zyB - zyT);
+            if (ov.border) {
+              ctx.globalAlpha = Math.min(1, ov.alpha + 0.4);
+              ctx.lineWidth = 1;
+              ctx.strokeStyle = col;
+              ctx.strokeRect(
+                Math.round(zx0) + 0.5, Math.round(zyT) + 0.5,
+                Math.max(2, Math.round(zx1 - zx0) - 1), Math.max(2, Math.round(zyB - zyT) - 1)
+              );
+            }
+            if (ov.label) {
+              ctx.globalAlpha = 0.95;
+              ctx.font = pillFont();
+              ctx.fillStyle = col;
+              ctx.textAlign = 'left';
+              ctx.textBaseline = 'top';
+              ctx.fillText(ov.label, zx0 + 6, Math.max(main.y0, zyT) + 4);
+            }
+            ctx.restore();
+          } else {
+            const lx0 = clamp(this._xFor(Math.max(0, idxFor(ov.from, 0))) - sp * 0.5, 0, plotRight);
+            const lx1 =
+              ov.to == null
+                ? plotRight
+                : clamp(this._xFor(Math.max(0, idxFor(ov.to, d.length - 1))) + sp * 0.5, 0, plotRight);
+            const ly = Math.round(yOf(ov.price)) + 0.5;
+            if (lx1 - lx0 < 1 || ly < main.y0 || ly > main.y1) continue;
+            ctx.save();
+            ctx.strokeStyle = col;
+            ctx.lineWidth = ov.width;
+            if (ov.dash) ctx.setLineDash([5, 4]);
+            ctx.beginPath();
+            ctx.moveTo(lx0, ly);
+            ctx.lineTo(lx1, ly);
+            ctx.stroke();
+            if (ov.label) {
+              ctx.font = pillFont();
+              ctx.fillStyle = col;
+              ctx.textAlign = 'right';
+              ctx.textBaseline = 'bottom';
+              ctx.fillText(ov.label, Math.min(lx1, plotRight) - 6, ly - 2);
+            }
+            ctx.restore();
+          }
+        }
+      }
+
+      /* scenario projection: ghost path + σ-cone in future space (clipped to
+       * the main plot so out-of-range bands never bleed into the axis) */
+      if (this._scenario && d.length) {
+        const sc = this._scenario;
+        const col = resolveOverlayColor(sc.color, pal);
+        const baseIdx = d.length - 1;
+        const xAt = (h) => this._xFor(baseIdx + h);
+        ctx.save();
+        ctx.beginPath();
+        ctx.rect(0, main.y0, plotRight, main.h);
+        ctx.clip();
+        if (sc.cone) {
+          const cone = this._scenarioConeCache();
+          if (cone) {
+            for (let li = cone.levels.length - 1; li >= 0; li--) {
+              const b = cone.bands[cone.levels[li]];
+              ctx.globalAlpha = li === 0 ? 0.1 : 0.05;
+              ctx.fillStyle = col;
+              ctx.beginPath();
+              ctx.moveTo(xAt(0), yOf(b.up[0]));
+              for (let h = 1; h <= cone.horizon; h++) ctx.lineTo(xAt(h), yOf(b.up[h]));
+              for (let h = cone.horizon; h >= 0; h--) ctx.lineTo(xAt(h), yOf(b.down[h]));
+              ctx.closePath();
+              ctx.fill();
+            }
+            const inner = cone.bands[cone.levels[0]];
+            ctx.globalAlpha = 0.4;
+            ctx.strokeStyle = col;
+            ctx.lineWidth = 1;
+            ctx.setLineDash([4, 4]);
+            for (const arr of [inner.up, inner.down]) {
+              ctx.beginPath();
+              ctx.moveTo(xAt(0), yOf(arr[0]));
+              for (let h = 1; h <= cone.horizon; h++) ctx.lineTo(xAt(h), yOf(arr[h]));
+              ctx.stroke();
+            }
+            ctx.setLineDash([]);
+          }
+        }
+        if (sc.path.length) {
+          ctx.globalAlpha = 0.9;
+          ctx.strokeStyle = col;
+          ctx.lineWidth = 1.5;
+          ctx.setLineDash([6, 4]);
+          ctx.beginPath();
+          ctx.moveTo(xAt(0), yOf(d[baseIdx].close));
+          for (const p of sc.path) ctx.lineTo(xAt(p.h), yOf(p.price));
+          ctx.stroke();
+          ctx.setLineDash([]);
+          ctx.fillStyle = col;
+          for (const p of sc.path) {
+            const y = yOf(p.price);
+            if (y >= main.y0 && y <= main.y1) {
+              ctx.beginPath();
+              ctx.arc(xAt(p.h), y, 2.5, 0, Math.PI * 2);
+              ctx.fill();
+            }
+          }
+          if (sc.label) {
+            const p = sc.path[sc.path.length - 1];
+            ctx.font = pillFont();
+            ctx.globalAlpha = 0.95;
+            ctx.fillStyle = col;
+            ctx.textAlign = 'left';
+            ctx.textBaseline = 'middle';
+            ctx.fillText(
+              sc.label,
+              Math.min(xAt(p.h) + 8, plotRight - 4),
+              clamp(yOf(p.price), main.y0 + 8, main.y1 - 8)
+            );
+          }
+        }
+        ctx.restore();
+      }
+
       /* position zones (under series) */
       for (const pos of this._positions) {
         const yE = clamp(yOf(pos.entry), main.y0, main.y1);
@@ -1396,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}`;
@@ -1724,7 +2266,7 @@ class WickChart extends HTMLElementBase {
         ctx.setLineDash([5, 4]);
         ctx.strokeStyle = pal.overlay[0];
         for (const a of this._alerts) {
-          if (a.fired) continue;
+          if (a.fired || !isNum(a.price)) continue; // scripted alerts have no line
           const y = yOf(a.price);
           if (y < main.y0 || y > main.y1) continue;
           ctx.globalAlpha = 0.8;
@@ -2055,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;
@@ -2141,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);
@@ -2309,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);
@@ -2323,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;
@@ -2374,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;
@@ -2399,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;
@@ -2443,14 +3078,17 @@ 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;
       const dy = e.deltaY * (e.deltaMode === 1 ? 33 : 1);
 
       if (Math.abs(dx) > Math.abs(dy) && !e.ctrlKey) {
-        // trackpad horizontal scroll → pan
-        this._view.rightIndex -= dx / this._view.spacing;
+        // trackpad horizontal scroll → pan. Wheel deltas are viewport-relative:
+        // deltaX>0 means "scroll right", i.e. reveal newer bars. On natural-scroll
+        // trackpads this makes the content follow the fingers, matching drag.
+        this._view.rightIndex += dx / this._view.spacing;
         this._auto = this._atRight();
         this._clampView();
         this._invalidate();
@@ -2474,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;
@@ -2662,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);
@@ -2675,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) {
@@ -2685,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;
@@ -2715,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();
     }
   }