wickchart 1.5.0 → 1.7.0

package/src/wick-chart.js

@@ -21,10 +21,10 @@
 import {
   clamp, isNum, numberFmt, fmtCompact, autoPrecision, niceStep, hexToRgba,
   FONT_STACK, axisFont, pillFont, roundRectPath,
-  TIME_STEPS, HOUR, DAY, hhmm, fmtDay, fmtMonth, fmtYear, fmtFull,
+  TIME_STEPS, HOUR, DAY, toMs, zoneOffset, hhmm, fmtDay, fmtMonth, fmtYear, fmtFull,
   THEMES, mergeOlderData, detectGaps,
   parseIndicators, normalizeIndicatorResult, BUILTIN_INDICATORS,
-  positionPnl, checkAlertCross, computeStats, safeColor,
+  positionPnl, positionPnlPct, checkAlertCross, computeStats, safeColor,
   SERIES_TYPES, calcHeikinAshi, buildColumns, computeVolumeProfile,
   calcRSI, detectAnnotations, priceToFreq,
   calcRealizedVol, volRegimeBands, percentileOfSorted, parseVolShading,
@@ -44,15 +44,42 @@ import {
  *  <wick-chart> and the deprecated <hab-chart> alias element. */
 const REGISTRY = new Map(BUILTIN_INDICATORS);
 
+/** Bars from which the worker compute path engages — below it, sync wins
+ *  (posting the epoch snapshot costs more than the compute it saves). */
+const WORKER_MIN_BARS = 50000;
+/** Returned while an off-thread compute is in flight: no lines yet, and —
+ *  like a failed compute — every renderer draws nothing. */
+const PENDING_SERIES = { lines: [], histogram: null };
+/**
+ * Built-ins a streamed tick can update by recomputing a bounded tail with
+ * the SAME batch definition (window indicators exactly, recursive ones
+ * converge geometrically). Excluded: obv/vwap are cumulative over all
+ * history, supertrend is a path-dependent state machine — no tail can
+ * patch those; they keep the full-recompute behavior.
+ */
+const ONLINE_SKIP = new Set(['obv', 'vwap', 'supertrend']);
+/** Tail warm-up bars per tick: past the recursion decay of any realistic
+ *  period (~10×), and still ~0.1 ms of work per indicator. */
+const ONLINE_WARMUP = 400;
+/** Per-chart worker session ids (see _workerCompute / src/worker-core.js). */
+let CHART_SID = 0;
+
   /* SSR safety: importing this module under Node (Next.js/Nuxt server render)
  * must not throw — the element simply registers only in browsers. */
 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', 'co-view-name', 'brush', 'sonify'];
+      return ['theme', 'type', 'log', 'auto', 'indicators', 'precision', 'label', 'stats', 'profile', 'annotations', 'volshading', 'overlays', 'co-view', 'co-view-name', 'brush', 'sonify', 'alert-evaluate', 'timezone', 'vwap-anchor', 'worker'];
     }
 
+    /**
+     * Shared ChartWorkerPool for the worker compute path (set by importing
+     * 'wickchart/worker'; null — everything sync — until then).
+     * @type {object|null}
+     */
+    static _workerPool = null;
+
     constructor() {
       super();
       const root = this.attachShadow({ mode: 'open' });
@@ -65,6 +92,9 @@ class WickChart extends HTMLElementBase {
             height: 100%;
             min-height: 220px;
             contain: content;
+            /* the overlays lay themselves out against the chart's own width
+               (see the @container rule at the end of this sheet) */
+            container-type: inline-size;
           }
           :host(:focus-visible) {
             outline: 2px solid var(--wick-accent, var(--hab-accent, #4c8dff));
@@ -75,10 +105,17 @@ class WickChart extends HTMLElementBase {
             position: absolute; inset: 0;
             width: 100%; height: 100%;
             display: block;
-            touch-action: none;
+            /* pan-y, not none: a vertical swipe belongs to the page, or a
+               chart embedded in a phone article becomes a dead zone the
+               reader cannot scroll past. Horizontal drags and pinches still
+               arrive as pointer events; _onTouchMove takes the gesture back
+               (preventDefault) once the chart owns it. */
+            touch-action: pan-y;
             cursor: crosshair;
             user-select: none;
             -webkit-user-select: none;
+            /* long-press is the scrub gesture — suppress the iOS callout */
+            -webkit-touch-callout: none;
           }
           canvas.grabbing { cursor: grabbing; }
           .legend {
@@ -150,6 +187,32 @@ class WickChart extends HTMLElementBase {
           .hud .v { color: var(--wick-text-strong, var(--hab-text-strong, #e6edf3)); font-variant-numeric: tabular-nums; }
           .hud .up { color: var(--wick-up, var(--hab-up, #16c784)); }
           .hud .dn { color: var(--wick-down, var(--hab-down, #ea3943)); }
+
+          /* Narrow charts: the legend (top-left) and the HUD (top-right) are
+             both pinned to the top, so on a phone they land on top of each
+             other — a label plus a few indicators wraps the legend to three
+             rows and the stats row draws straight through it. Below 560px
+             they stack instead.
+
+             A container query, not a media query: what matters is how wide
+             the chart is, not the screen. A narrow chart in a sidebar on a
+             desktop has exactly the same problem.
+
+             They become position:relative rather than static so they stay in
+             flow *and* keep their stacking context — an unpositioned box would
+             paint underneath the absolutely positioned canvas. The canvas is
+             out of flow either way, so the flex column never moves it. */
+          @container (max-width: 560px) {
+            .wrap { display: flex; flex-direction: column; align-items: flex-start; }
+            .legend, .hud {
+              position: relative;
+              left: auto; right: auto; top: auto;
+              max-width: calc(100% - 20px);
+            }
+            .legend { margin: 8px 10px 0; }
+            .hud { margin: 4px 10px 0; align-items: flex-start; }
+            .hud .pos, .hud .statsrow { white-space: normal; }
+          }
         </style>
         <div class="wrap" part="wrap">
           <canvas part="canvas" role="img"></canvas>
@@ -231,9 +294,27 @@ class WickChart extends HTMLElementBase {
       this._brushDrag = null; // { i0, i1 } — while the pointer is down
       this._ind = { overlays: [], panes: [], volume: true };
 
+      // worker compute path (see _indicatorSeries): built-in indicators over
+      // big histories compute off the main thread. Results are cached per
+      // data *epoch* (bulk loads: setData/clearData/backfill) — streamed
+      // ticks bump _version, not _epoch, so they stop recomputing the full
+      // series per bar; the forming bar's value catches up on the next load.
+      this._workerOn = false;
+      this._epoch = 0;
+      this._workerCache = { epoch: -1, map: {}, pending: {}, sent: -1 };
+      this._sid = ++CHART_SID;
+      // incremental tick updates: { epoch, map: key → { v, res } } — the
+      // freshest series per key, patched in place by _onlineTick
+      this._onlineSeries = { epoch: -1, map: {} };
+
       this._pointers = new Map();
       this._pan = null;
       this._pinch = null;
+      // long-press scrub: touch has no hover, so reading a bar needs a
+      // gesture of its own (see _armPress)
+      this._scrub = false;
+      this._pressTimer = 0;
+      this._pressOrigin = null;
 
       // plugin layers: external draw hooks + pointer claims (see addLayer)
       this._layers = [];
@@ -248,6 +329,12 @@ class WickChart extends HTMLElementBase {
       this._positions = [];
       this._alerts = [];
       this._seq = 0;
+      // Default evaluation mode for alerts that don't pick one, and the last
+      // bar index known to be final — see _lastClosedIndex().
+      this._alertEval = 'live';
+      this._lastClosedIdx = -1;
+      this._tz = 'local';
+      this._vwapAnchor = 'utc';
 
       // server-side overlays (zones & levels)
       this._overlays = [];
@@ -274,6 +361,32 @@ class WickChart extends HTMLElementBase {
         this.fit();
       };
       this._onKey = (e) => this._keydown(e);
+      // The canvas leaves vertical scrolling to the page (touch-action:
+      // pan-y). Once a chart gesture owns the touch — a pinch, a scrub, a
+      // layer drag, or a pan that has committed to a direction — the
+      // gesture is taken back, or the browser would hand it to the scroller
+      // halfway through. Must be non-passive to be allowed to.
+      this._onTouchMove = (e) => {
+        if (
+          this._scrub ||
+          this._pointers.size >= 2 ||
+          this._layerClaim ||
+          (this._pan && this._pan.moved)
+        ) {
+          e.preventDefault();
+        }
+      };
+      // devicePixelRatio changes without the CSS box changing size — dragging
+      // the window to a monitor with a different ratio, or a browser zoom
+      // that lands on the same layout width. ResizeObserver stays silent for
+      // those, so the canvas would keep its old backing store and render
+      // soft until something else forced a resize. A `resolution` media
+      // query is the only event for it; it only ever matches the ratio it
+      // was created with, so each change re-arms a fresh one.
+      this._onDprChange = () => {
+        this._watchDpr();
+        this._invalidate();
+      };
     }
 
     connectedCallback() {
@@ -294,6 +407,7 @@ class WickChart extends HTMLElementBase {
       cv.addEventListener('pointercancel', this._onPointerUp);
       cv.addEventListener('pointerleave', this._onPointerLeave);
       cv.addEventListener('wheel', this._onWheel, { passive: false });
+      cv.addEventListener('touchmove', this._onTouchMove, { passive: false });
       cv.addEventListener('dblclick', this._onDbl);
       this.addEventListener('keydown', this._onKey);
 
@@ -301,6 +415,7 @@ class WickChart extends HTMLElementBase {
         document.fonts.ready.then(() => this._invalidate()).catch(() => {});
       }
       if (this._coviewName) this._setupCoView();
+      this._watchDpr();
       this._invalidate();
     }
 
@@ -325,6 +440,7 @@ class WickChart extends HTMLElementBase {
       }
       clearTimeout(this._ghostTimer);
       if (this._ro) this._ro.disconnect();
+      this._unwatchDpr();
       const cv = this._canvas;
       cv.removeEventListener('pointerdown', this._onPointerDown);
       cv.removeEventListener('pointermove', this._onPointerMove);
@@ -332,11 +448,29 @@ class WickChart extends HTMLElementBase {
       cv.removeEventListener('pointercancel', this._onPointerUp);
       cv.removeEventListener('pointerleave', this._onPointerLeave);
       cv.removeEventListener('wheel', this._onWheel);
+      cv.removeEventListener('touchmove', this._onTouchMove);
       cv.removeEventListener('dblclick', this._onDbl);
       this.removeEventListener('keydown', this._onKey);
+      this._disarmPress();
+      this._scrub = false;
       if (this._raf) cancelAnimationFrame(this._raf), (this._raf = 0);
     }
 
+    /** (Re)arm the devicePixelRatio watcher for the current ratio. */
+    _watchDpr() {
+      this._unwatchDpr();
+      if (typeof matchMedia !== 'function') return;
+      const dpr = window.devicePixelRatio || 1;
+      this._dprMq = matchMedia(`(resolution: ${dpr}dppx)`);
+      this._dprMq.addEventListener('change', this._onDprChange);
+    }
+
+    _unwatchDpr() {
+      if (!this._dprMq) return;
+      this._dprMq.removeEventListener('change', this._onDprChange);
+      this._dprMq = null;
+    }
+
     attributeChangedCallback(name, _old, val) {
       switch (name) {
         case 'theme':
@@ -360,6 +494,10 @@ class WickChart extends HTMLElementBase {
         case 'indicators':
           this._ind = parseIndicators(val, WickChart._registry());
           break;
+        case 'worker':
+          this._workerOn = val != null && val !== 'false';
+          this._invalidate();
+          break;
         case 'stats':
           this._stats = val != null && val !== 'false';
           this._statsKey = '';
@@ -406,6 +544,26 @@ class WickChart extends HTMLElementBase {
           this._sonify = val != null && val !== 'false';
           this._lastToneIdx = -1;
           break;
+        // Default evaluation mode for alerts added without one. Anything
+        // other than "close" means live, so a typo cannot silently mute
+        // signals — it degrades to today's behaviour.
+        case 'alert-evaluate':
+          this._alertEval = val === 'close' ? 'close' : 'live';
+          break;
+        // Display zone for axis labels and the crosshair readout: 'local'
+        // (default), 'utc', or an IANA name. Deliberately does NOT re-anchor
+        // VWAP — the trading session is a separate question from how times
+        // are shown; see calcVWAP's `anchor`.
+        case 'timezone':
+          this._tz = val || 'local';
+          break;
+        // Session anchor for VWAP: 'utc' (default), 'local', an IANA zone, or
+        // a fixed offset in ms. Bumping the version drops the per-version
+        // indicator cache so the series recomputes on the next frame.
+        case 'vwap-anchor':
+          this._vwapAnchor = val || 'utc';
+          this._version++;
+          break;
       }
       this._invalidate();
     }
@@ -449,9 +607,10 @@ class WickChart extends HTMLElementBase {
       });
     }
 
-    /** The custom element class (also exported implicitly for users). */
+    /** The tag this class registers as. (<hab-chart> is a deprecated alias
+     *  registered from the HabChart subclass, not this name.) */
     static get elementName() {
-      return 'hab-chart';
+      return 'wick-chart';
     }
 
     /* ------------------------------------------------------------ *
@@ -487,9 +646,23 @@ class WickChart extends HTMLElementBase {
         }
       }
       if (!sorted) norm.sort((a, b) => a.time - b.time);
+      // One bar per timestamp. A REST history fetch and the websocket that
+      // takes over from it overlap, so the same final candle routinely
+      // arrives twice; the later copy is the corrected one and wins. In
+      // place and allocation-free when the data is already unique.
+      let dst = 0;
+      for (let i = 0; i < norm.length; i++) {
+        if (dst > 0 && norm[i].time === norm[dst - 1].time) norm[dst - 1] = norm[i];
+        else norm[dst++] = norm[i];
+      }
+      norm.length = dst;
       this._data = norm;
       this._version++;
+      this._epoch++;
       this._computeDt();
+      // history is not a live signal: re-baseline so close-mode alerts only
+      // fire on candles that close from here on
+      this._syncClosedIdx();
       this._needsFit = true;
       this._auto = this._autoAttr();
       this._hover = null;
@@ -508,21 +681,37 @@ class WickChart extends HTMLElementBase {
       if (!b) return;
       const d = this._data;
       const last = d[d.length - 1];
-      this._checkAlerts(last ? last.close : NaN, b);
+      const prevClose = last ? last.close : NaN;
+      // Only the front of the series is a live signal. A historical
+      // correction or a backfilled candle must never be compared against the
+      // latest price — that would fire an alert on a stale bar.
+      let live = true;
       if (!last || b.time > last.time) {
         d.push(b);
         if (d.length > 1) this._computeDt();
       } else if (b.time === last.time) {
         d[d.length - 1] = b;
       } else {
-        // out-of-order / backfill: replace matching or insert
-        let i = d.length - 1;
-        while (i >= 0 && d[i].time > b.time) i--;
-        if (i >= 0 && d[i].time === b.time) d[i] = b;
-        else d.splice(i + 1, 0, b);
+        // out-of-order / backfill: replace matching or insert. Binary search
+        // for the slot — a backward scan is O(n) per bar, which turns a
+        // backfill of old candles into O(n·m) over a long history.
+        live = false;
+        const i = WickChart._indexForTime(d, b.time);
+        if (d[i] && d[i].time === b.time) d[i] = b;
+        else d.splice(i, 0, b);
         this._computeDt();
       }
       this._version++;
+      // a live tick (append / forming-bar replace) patches every
+      // online-capable series in O(warm-up) before the next render
+      if (live) this._onlineTick();
+      // Alerts run after the dataset AND the version are updated, so scripted
+      // predicates evaluate over the bar that just arrived rather than
+      // re-reading the previous version's memoized series.
+      // A historical insert shifts indices without closing anything, so the
+      // cursor moves with the data rather than reading as a fresh close.
+      if (live) this._checkAlerts(prevClose, b);
+      else this._syncClosedIdx();
       if (this._hover && this._hover.index >= d.length) this._hover = null;
       this._updateAria();
       this._invalidate();
@@ -531,6 +720,8 @@ class WickChart extends HTMLElementBase {
     clearData() {
       this._data = [];
       this._version++;
+      this._epoch++;
+      this._syncClosedIdx();
       this._hover = null;
       this._needsFit = true;
       this._noMore = false;
@@ -574,9 +765,11 @@ class WickChart extends HTMLElementBase {
           }
           this._data = merged;
           this._version++;
+          this._epoch++;
           this._computeDt();
           // keep the exact same bars on screen: every index shifts by `added`
           this._view.rightIndex += added;
+          this._syncClosedIdx(); // backfill shifts indices, it closes nothing
           if (this._hover) this._hover.index = Math.min(this._hover.index + added, this._data.length - 1);
           this._clampView();
           this._invalidate();
@@ -701,8 +894,8 @@ class WickChart extends HTMLElementBase {
           .filter((a) => !a.fired)
           .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 }
+              ? { id: a.id, when: a.when, once: a.once, evaluate: a.evaluate }
+              : { id: a.id, price: a.price, direction: a.direction, once: a.once, evaluate: a.evaluate }
           ),
       };
     }
@@ -750,6 +943,7 @@ class WickChart extends HTMLElementBase {
                   when: a.when.trim(),
                   compiled: compileScript(a.when),
                   once: a.once !== false,
+                  evaluate: this._evalMode(a.evaluate),
                   fired: false,
                   armed: true,
                 };
@@ -762,6 +956,7 @@ class WickChart extends HTMLElementBase {
               price: a.price,
               direction: a.direction || 'cross',
               once: a.once !== false,
+              evaluate: this._evalMode(a.evaluate),
               fired: false,
             };
           })
@@ -845,6 +1040,7 @@ class WickChart extends HTMLElementBase {
           when: alert.when.trim(),
           compiled,
           once: alert.once !== false,
+          evaluate: this._evalMode(alert.evaluate),
           fired: false,
           armed: true,
         };
@@ -855,6 +1051,7 @@ class WickChart extends HTMLElementBase {
           price: alert.price,
           direction: alert.direction || 'cross',
           once: alert.once !== false,
+          evaluate: this._evalMode(alert.evaluate),
           fired: false,
         };
       }
@@ -1081,27 +1278,78 @@ class WickChart extends HTMLElementBase {
     /** 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. */
+    /**
+     * Index of the newest bar known to be final: any bar with a newer bar
+     * behind it, plus the front bar when the feed flagged it `closed: true`
+     * (Binance's `k.x`). -1 when nothing has closed yet.
+     */
+    _lastClosedIndex() {
+      const d = this._data;
+      if (!d.length) return -1;
+      const last = d.length - 1;
+      return d[last] && d[last].closed === true ? last : last - 1;
+    }
+
+    /** Re-baseline the closed-bar cursor without firing anything. */
+    _syncClosedIdx() {
+      this._lastClosedIdx = this._lastClosedIndex();
+    }
+
+    /**
+     * Resolve an alert's evaluation mode: an explicit 'close' / 'live' on the
+     * alert wins, otherwise the chart-level `alert-evaluate` default (itself
+     * 'live', so 1.x behaviour is unchanged unless asked for).
+     * @param {string|undefined} v
+     * @returns {'live'|'close'}
+     */
+    _evalMode(v) {
+      if (v === 'close' || v === 'live') return v;
+      return this._alertEval === 'close' ? 'close' : 'live';
+    }
+
+    /** Dispatch one alert, retiring it when it was a `once` alert. */
+    _fireAlert(alert, detail) {
+      if (alert.once) alert.fired = true;
+      this._fire('alert', { id: alert.id, ...detail });
+      if (alert.once) this._alerts = this._alerts.filter((x) => x !== alert);
+    }
+
     _checkAlerts(prevClose, bar) {
+      const closedIdx = this._lastClosedIndex();
+      // A bar closing is an edge, not a level: close-mode alerts evaluate
+      // only on the update that finalizes a candle, so a candle that ticks
+      // through a threshold and back never produces a signal.
+      const justClosed = closedIdx > this._lastClosedIdx;
+      if (justClosed) this._lastClosedIdx = closedIdx;
       if (!this._alerts.length) return;
+      const d = this._data;
       for (const a of [...this._alerts]) {
+        // `fired` means "spent forever" — it is only ever set on `once`
+        // alerts. Repeating (once:false) alerts re-fire on every edge:
+        // price alerts are edge-triggered by checkAlertCross(), scripted
+        // ones by the armed/scriptAlertStep() latch.
         if (a.fired) continue;
+
+        // Close mode reads the newest final candle; live mode reads the
+        // front of the series, forming or not.
+        const onClose = a.evaluate === 'close';
+        if (onClose && (!justClosed || closedIdx < 0)) continue;
+        const idx = onClose ? closedIdx : d.length - 1;
+        const cur = onClose ? d[idx] : bar;
+        if (!cur) 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);
+          // predicates are causal, so the value at `idx` is the same whether
+          // it was computed over the whole series or just the prefix
+          const step = scriptAlertStep(a.armed, this._predicateCache(a)[idx] === true);
           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);
-          }
+          if (step.fire) this._fireAlert(a, { price: cur.close, when: a.when, bar: cur });
           continue;
         }
-        if (!isNum(prevClose)) continue;
-        if (checkAlertCross(a, prevClose, bar.close)) {
-          a.fired = true;
-          this._fire('alert', { id: a.id, price: a.price, bar });
-          if (a.once) this._alerts = this._alerts.filter((x) => x !== a);
+        const prev = onClose ? (d[idx - 1] ? d[idx - 1].close : NaN) : prevClose;
+        if (!isNum(prev)) continue;
+        if (checkAlertCross(a, prev, cur.close)) {
+          this._fireAlert(a, { price: a.price, bar: cur });
         }
       }
     }
@@ -1136,6 +1384,11 @@ class WickChart extends HTMLElementBase {
 
     static _MAX_SP = 90;
 
+    /** Hold this long on a touchscreen to open the crosshair (ms). */
+    static _PRESS_MS = 350;
+    /** Finger travel that cancels the press and makes it a pan (px). */
+    static _PRESS_SLOP = 10;
+
     /**
      * Lowest allowed px/bar: either 0.35, or whatever fits the entire
      * dataset on screen — so any history can be zoomed out fully.
@@ -1147,18 +1400,19 @@ class WickChart extends HTMLElementBase {
     }
 
     static _timeToMs(t) {
-      return isNum(t) ? (t < 1e12 ? t * 1000 : t) : Date.now();
+      if (t instanceof Date) return t.getTime();
+      return isNum(t) ? toMs(t) : Date.now();
     }
 
     static _normBar(b) {
       if (!b) return null;
       const t = b.time != null ? b.time : b.t;
-      if (!isNum(t)) return null;
+      if (!isNum(t) && !(t instanceof Date)) return null;
       const time = WickChart._timeToMs(t);
       const close = isNum(b.close) ? b.close : isNum(b.value) ? b.value : NaN;
       if (!isNum(close)) return null;
       const open = isNum(b.open) ? b.open : close;
-      return {
+      const nb = {
         time,
         open,
         high: isNum(b.high) ? b.high : Math.max(open, close),
@@ -1166,6 +1420,10 @@ class WickChart extends HTMLElementBase {
         close,
         volume: isNum(b.volume) ? b.volume : isNum(b.v) ? b.v : 0,
       };
+      // Only carried when the feed actually says the candle is final
+      // (Binance `k.x`), so the bar shape is unchanged for everyone else.
+      if (b.closed === true) nb.closed = true;
+      return nb;
     }
 
     static _indexForTime(d, time) {
@@ -1303,22 +1561,188 @@ class WickChart extends HTMLElementBase {
 
     /** Compute (and cache per data version) an indicator entry's series. */
     _indicatorSeries(entry) {
+      {
+        // incremental path first: a series patched for this exact version
+        // by _onlineTick is the freshest thing there is
+        const on = this._onlineSeries;
+        const cur = on.epoch === this._epoch ? on.map['ind:' + entry.key] : null;
+        if (cur && cur.v === this._version) return cur.res;
+      }
       if (this._cache.v !== this._version) {
         this._cache = { v: this._version, map: {} };
       }
       const k = 'ind:' + entry.key;
       if (!this._cache.map[k]) {
+        // Worker compute path: built-in indicators over big histories run
+        // off the main thread. The dataset crosses once per data epoch as
+        // six transferable Float64Arrays (~25 ms/M bars — cloning objects
+        // would cost ~1 s). Closures (custom/scripted defs) can't cross;
+        // neither can anything below WORKER_MIN_BARS — both stay sync.
+        const pool = WickChart._workerPool;
+        if (pool && pool.available && this._workerOn && this._data.length >= WORKER_MIN_BARS &&
+            BUILTIN_INDICATORS.get(entry.name) === entry.def) {
+          const wc = this._workerCache;
+          if (wc.epoch === this._epoch && wc.map[k]) return wc.map[k];
+          this._workerCompute(pool, entry, k);
+          return PENDING_SERIES; // the line lands when the result arrives
+        }
         let res;
         try {
-          res = entry.def.compute(this._data, entry.params);
+          // the session anchor rides along for indicators that observe one
+          // (vwap); the rest ignore the extra key
+          res = entry.def.compute(this._data, { ...entry.params, anchor: this._vwapAnchor });
         } catch (err) {
           res = null;
         }
         this._cache.map[k] = normalizeIndicatorResult(res);
+        this._seedOnline(k, entry, this._cache.map[k]);
       }
       return this._cache.map[k];
     }
 
+    /**
+     * After a live stream tick (append or forming-bar replace), patch every
+     * online-capable series by recomputing a bounded tail with the same
+     * batch definition — O(warm-up) instead of a full-history recompute per
+     * indicator per tick. Bases are seeded by the sync or worker path; bulk
+     * loads (epoch changes) reseed automatically.
+     */
+    _onlineTick() {
+      const d = this._data;
+      const on = this._onlineSeries;
+      if (!d.length || on.epoch !== this._epoch) return;
+      for (const entry of this._ind.overlays.concat(this._ind.panes)) {
+        const k = 'ind:' + entry.key;
+        const cur = on.map[k];
+        if (!cur || ONLINE_SKIP.has(entry.name) || BUILTIN_INDICATORS.get(entry.name) !== entry.def) {
+          continue;
+        }
+        if (this._patchSeriesTail(cur.res, entry, d)) cur.v = this._version;
+        else delete on.map[k]; // length mismatch etc. — reseed on the next compute
+      }
+    }
+
+    /** Recompute the last K bars of one series in place (K = max(400,
+     *  10×period), clamped to the data). False when the series and data
+     *  lengths can't line up — the caller drops the base and reseeds. */
+    _patchSeriesTail(res, entry, d) {
+      let p = 0;
+      for (const v of Object.values(entry.params || {})) {
+        if (Number.isFinite(+v) && +v > p) p = +v;
+      }
+      const K = Math.min(d.length - 1, Math.max(ONLINE_WARMUP, p * 10));
+      if (K < 2 || !res.lines.length) return false;
+      let tail;
+      try {
+        tail = normalizeIndicatorResult(
+          entry.def.compute(d.slice(d.length - 1 - K), { ...entry.params, anchor: this._vwapAnchor })
+        );
+      } catch (_) {
+        return false;
+      }
+      const want = d.length;
+      const base = want - 1 - K; // data index of tail[0]
+      // Only the last `p` values can have changed (window indicators depend
+      // on the trailing window alone; recursive ones only move the new bar).
+      // Writing deeper would replace good full-history values with the
+      // tail's own warm-up error.
+      const from = Math.max(base, want - 1 - p);
+      const patch = (dst, src) => {
+        if (!Array.isArray(src) || src.length !== K + 1) return false;
+        if (dst.length === want - 1) dst.push(src[src.length - 1]); // a bar was appended
+        else if (dst.length !== want) return false;
+        for (let di = from; di < want; di++) {
+          const v = src[di - base];
+          if (v != null || dst[di] == null) dst[di] = v; // warm-up null never clobbers
+        }
+        return true;
+      };
+      for (let i = 0; i < res.lines.length; i++) {
+        const t = tail.lines[i];
+        if (!t || !patch(res.lines[i].values, t.values)) return false;
+      }
+      if (Array.isArray(res.histogram) && !patch(res.histogram, tail.histogram)) return false;
+      return true;
+    }
+
+    /** Remember a fresh series as the base for incremental tick updates
+     *  (online-capable builtins only). */
+    _seedOnline(k, entry, res) {
+      if (ONLINE_SKIP.has(entry.name) || BUILTIN_INDICATORS.get(entry.name) !== entry.def) return;
+      const on = this._onlineSeries;
+      if (on.epoch !== this._epoch) {
+        on.epoch = this._epoch;
+        on.map = {};
+      }
+      on.map[k] = { v: this._version, res };
+    }
+
+    /** Bar count from which the worker path engages (below it, sync wins). */
+    _workerCols() {
+      const d = this._data;
+      const n = d.length;
+      const cols = {
+        time: new Float64Array(n), open: new Float64Array(n), high: new Float64Array(n),
+        low: new Float64Array(n), close: new Float64Array(n), volume: new Float64Array(n),
+      };
+      for (let i = 0; i < n; i++) {
+        const b = d[i];
+        cols.time[i] = b.time;
+        cols.open[i] = b.open;
+        cols.high[i] = b.high;
+        cols.low[i] = b.low;
+        cols.close[i] = b.close;
+        cols.volume[i] = b.volume || 0;
+      }
+      return cols;
+    }
+
+    /** Kick an off-thread compute for one indicator (idempotent per epoch). */
+    _workerCompute(pool, entry, k) {
+      const wc = this._workerCache;
+      wc.epoch = this._epoch;
+      if (wc.sent !== this._epoch) {
+        wc.sent = this._epoch;
+        wc.pending = {};
+        pool
+          .run({ type: 'epoch', sid: this._sid, epoch: this._epoch, cols: this._workerCols() })
+          .catch(() => {
+            if (wc.sent === this._epoch) wc.sent = -1; // resend on the next kick
+          });
+      }
+      if (wc.pending[k] === this._epoch) return; // already in flight
+      wc.pending[k] = this._epoch;
+      const epoch = this._epoch; // captured at kick time — a bulk load that
+      // lands while the compute is in flight must not adopt its result
+      pool
+        .run({
+          type: 'indicator', sid: this._sid, epoch,
+          name: entry.name, params: { ...entry.params, anchor: this._vwapAnchor },
+        })
+        .then((res) => this._workerArrived(k, epoch, res, entry))
+        .catch((err) => {
+          delete wc.pending[k];
+          if (err && err.stale && wc.sent === this._epoch) {
+            wc.sent = -1; // the worker no longer holds this epoch's data — resend
+          } else if (wc.epoch === epoch) {
+            wc.map[k] = { lines: [], histogram: null }; // negative cache: draw nothing this epoch
+          }
+        });
+    }
+
+    _workerArrived(k, epoch, res, entry) {
+      const wc = this._workerCache;
+      delete wc.pending[k];
+      if (wc.epoch !== epoch) return; // a newer bulk load won — drop the stale line
+      const norm = normalizeIndicatorResult(res);
+      wc.map[k] = norm;
+      // the worker base doubles as the seed for incremental tick updates,
+      // so streamed ticks stay fresh instead of waiting for the next load
+      if (entry) this._seedOnline(k, entry, norm);
+      this._fire('worker', { key: k, epoch });
+      this._invalidate();
+    }
+
     /** Resolve a line color: #hex / rgb() / CSS name / palette key ('rsi', 'up', …) / cycle.
      *  Untrusted values (URL/attribute-sourced) are validated — never interpolated raw. */
     _lineColor(entry, line, pal, cycleIdx) {
@@ -1492,6 +1916,11 @@ class WickChart extends HTMLElementBase {
      * the walk to those bars — used at deep zoom where bars are aggregated
      * into pixel columns (keeps this O(screen) instead of O(visible bars)).
      */
+    /** An instant shifted into the chart's display zone, for the formatters. */
+    _zt(t) {
+      return t + zoneOffset(t, this._tz);
+    }
+
     _timeTicks(i0, i1, sampleIdx) {
       const d = this._data;
       const sp = this._view.spacing;
@@ -1519,7 +1948,6 @@ class WickChart extends HTMLElementBase {
         }
       }
 
-      const tz = (t) => -new Date(t).getTimezoneOffset() * 60000;
       const ticks = [];
       let prevKey = null;
       // Labels are built lazily — only for bars that actually start a new step.
@@ -1527,30 +1955,32 @@ class WickChart extends HTMLElementBase {
       const visit = (i) => {
         if (i < 0 || i >= d.length) return;
         const t = d[i].time;
+        // shifted into the display zone once, then read with UTC getters
+        const zt = this._zt(t);
         let key;
         let label = null;
         if (stepMs != null) {
-          key = Math.floor((t + tz(t)) / stepMs);
+          key = Math.floor(zt / stepMs);
           if (prevKey !== null && key !== prevKey) {
             if (stepLabel === 'time') {
               const prevT = d[i - 1] ? d[i - 1].time : t;
-              const dayKey = Math.floor((t + tz(t)) / DAY);
-              const prevDay = Math.floor((prevT + tz(prevT)) / DAY);
-              label = dayKey !== prevDay ? fmtDay(t) : hhmm(t);
+              const dayKey = Math.floor(zt / DAY);
+              const prevDay = Math.floor(this._zt(prevT) / DAY);
+              label = dayKey !== prevDay ? fmtDay(zt) : hhmm(zt);
             } else {
-              const dt_ = new Date(t);
-              label = dt_.getDate() === 1 ? fmtMonth(t, dt_.getMonth() === 0) : fmtDay(t);
+              const dt_ = new Date(zt);
+              label = dt_.getUTCDate() === 1 ? fmtMonth(zt, dt_.getUTCMonth() === 0) : fmtDay(zt);
             }
           }
         } else if (monthStep) {
-          const dt_ = new Date(t);
-          key = Math.floor((dt_.getFullYear() * 12 + dt_.getMonth()) / monthStep);
+          const dt_ = new Date(zt);
+          key = Math.floor((dt_.getUTCFullYear() * 12 + dt_.getUTCMonth()) / monthStep);
           if (prevKey !== null && key !== prevKey) {
-            label = fmtMonth(t, dt_.getMonth() === 0 || monthStep > 1);
+            label = fmtMonth(zt, dt_.getUTCMonth() === 0 || monthStep > 1);
           }
         } else {
-          key = new Date(t).getFullYear();
-          if (prevKey !== null && key !== prevKey) label = fmtYear(t);
+          key = new Date(zt).getUTCFullYear();
+          if (prevKey !== null && key !== prevKey) label = fmtYear(zt);
         }
         if (label !== null) ticks.push({ x: this._xFor(i), label });
         prevKey = key;
@@ -1598,8 +2028,9 @@ class WickChart extends HTMLElementBase {
         );
       }
       const timeH = 26;
+      const dock = this._dockInset();
       const plotRight = Math.max(30, W - priceW);
-      const plotBottom = H - timeH;
+      const plotBottom = H - timeH - dock;
       const paneList = this._ind.panes;
       const paneArea = paneList.length
         ? Math.min(
@@ -1622,6 +2053,7 @@ class WickChart extends HTMLElementBase {
         plotBottom,
         main: { y0: 0, y1: mainH, h: mainH },
         panes,
+        dock: dock > 0 ? { y0: H - dock, h: dock } : null,
       });
 
       /* background */
@@ -2602,7 +3034,7 @@ class WickChart extends HTMLElementBase {
         }
 
         // time pill
-        const tLabel = fmtFull(d[h.index].time);
+        const tLabel = fmtFull(this._zt(d[h.index].time));
         ctx.font = pillFont();
         const tw = ctx.measureText(tLabel).width + 12;
         this._pill(
@@ -2673,7 +3105,7 @@ class WickChart extends HTMLElementBase {
         ctx.stroke();
         ctx.restore();
         if (gxVisible && this._data[g.index]) {
-          const tLabel = fmtFull(this._data[g.index].time);
+          const tLabel = fmtFull(this._zt(this._data[g.index].time));
           ctx.font = pillFont();
           const tw = ctx.measureText(tLabel).width + 12;
           this._pill(
@@ -2919,7 +3351,7 @@ class WickChart extends HTMLElementBase {
       let html = '';
       for (const p of this._positions) {
         const pnl = positionPnl(p, price);
-        const pct = p.entry ? (pnl / p.entry) * 100 : 0;
+        const pct = positionPnlPct(p, price);
         const cls = pnl >= 0 ? 'up' : 'dn';
         const qtyStr = p.qty != null ? ' ' + p.qty : '';
         html +=
@@ -2942,7 +3374,13 @@ class WickChart extends HTMLElementBase {
      * layer then receives that pointer's move/up/cancel events (plus a
      * 'cancel' on Escape) and the chart suppresses its own pan/measure/brush
      * for the duration.
-     * @param {{id?: string, draw: Function, onPointer?: Function}} layer
+     *
+     * A layer may also declare `insetBottom` (px, 0..160): the largest
+     * declared inset reserves a docked strip at the very bottom of the
+     * canvas — all chart content (panes + time axis) shrinks above it and
+     * the strip is handed to layers as `api.layout.dock = { y0, h }`
+     * (used by the wickchart-navigator plugin).
+     * @param {{id?: string, draw: Function, onPointer?: Function, insetBottom?: number}} layer
      * @returns {object|null} the normalized layer handle (with `id`), or null
      *   if the layer was rejected (no draw fn, or 16 layers already added)
      */
@@ -2956,6 +3394,10 @@ class WickChart extends HTMLElementBase {
       const entry = {
         id,
         draw: layer.draw,
+        insetBottom:
+          typeof layer.insetBottom === 'number' && Number.isFinite(layer.insetBottom)
+            ? Math.max(0, Math.min(160, Math.round(layer.insetBottom)))
+            : 0,
         onPointer: typeof layer.onPointer === 'function' ? layer.onPointer : null,
       };
       const at = this._layers.findIndex((l) => l.id === id);
@@ -3007,6 +3449,18 @@ class WickChart extends HTMLElementBase {
       }
     }
 
+    /**
+     * Bottom space reserved by plugin layers: the largest declared
+     * `insetBottom` (px, clamped 0..160 at addLayer time), or 0.
+     */
+    _dockInset() {
+      let dock = 0;
+      for (const l of this._layers) {
+        if (l.insetBottom > dock) dock = l.insetBottom;
+      }
+      return dock;
+    }
+
     /** Ask layers, in order, whether one claims this pointerdown. */
     _layerHit(e, pt) {
       for (const layer of this._layers) {
@@ -3069,7 +3523,7 @@ class WickChart extends HTMLElementBase {
       const ly = this._ly;
       const d = this._data;
       if (!ly || !d.length || !isNum(time)) return null;
-      const t = time < 1e12 ? time * 1000 : time;
+      const t = toMs(time);
       const last = d.length - 1;
       if (t >= d[last].time) {
         return this._xFor(last + (t - d[last].time) / (this._dt || HOUR));
@@ -3141,6 +3595,59 @@ class WickChart extends HTMLElementBase {
       return { x: e.clientX - r.left, y: e.clientY - r.top };
     }
 
+    /**
+     * Put the crosshair on the bar under a point and announce it. Shared by
+     * mouse hover, keyboard walking and the touch scrub gesture.
+     */
+    _hoverAt(pt) {
+      if (!this._ly || !this._data.length) return;
+      const idx = clamp(Math.round(this._indexForX(pt.x)), 0, this._data.length - 1);
+      this._hover = { index: idx, x: this._xFor(idx), y: pt.y };
+      this._maybeSonify(idx);
+      this._emitCrosshair(this._hover);
+      this._invalidate();
+    }
+
+    /**
+     * Start the long-press timer for a touch. A touchscreen has no hover, so
+     * without this there is no way to read a bar's values on a phone: a tap
+     * selects, a drag pans, and the legend never leaves the last candle.
+     * Holding still opens the crosshair; moving first cancels and pans.
+     */
+    _armPress(pointerId, pt) {
+      this._disarmPress();
+      this._pressOrigin = { pointerId, x: pt.x, y: pt.y };
+      this._pressTimer = setTimeout(() => {
+        this._pressTimer = 0;
+        const origin = this._pressOrigin;
+        // Still one finger, still down, nothing else has claimed the gesture.
+        if (!origin || this._pointers.size !== 1 || this._layerClaim) return;
+        if (!this._pointers.has(origin.pointerId)) return;
+        this._scrub = true;
+        this._pan = null;
+        this._measuring = false;
+        this._canvas.classList.remove('grabbing');
+        this._hoverAt(origin);
+      }, WickChart._PRESS_MS);
+    }
+
+    _disarmPress() {
+      if (this._pressTimer) clearTimeout(this._pressTimer);
+      this._pressTimer = 0;
+      this._pressOrigin = null;
+    }
+
+    /** Leave scrub mode and put the crosshair away. */
+    _endScrub() {
+      if (!this._scrub) return;
+      this._scrub = false;
+      if (this._hover) {
+        this._hover = null;
+        this._emitCrosshair(null);
+        this._invalidate();
+      }
+    }
+
     _pointerDown(e) {
       if (e.button !== 0) return;
       this._stopPlayback(); // any touch interrupts the story
@@ -3161,6 +3668,9 @@ class WickChart extends HTMLElementBase {
         }
       }
       if (this._pointers.size === 2) {
+        // a second finger is a pinch, never a press or a scrub
+        this._disarmPress();
+        this._endScrub();
         const [a, b] = [...this._pointers.values()];
         const mid = { x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 };
         this._pinch = {
@@ -3196,6 +3706,7 @@ class WickChart extends HTMLElementBase {
       } else {
         this._pan = { x: pt.x, rightIndex: this._view.rightIndex, moved: false };
         this._canvas.classList.add('grabbing');
+        if (e.pointerType === 'touch') this._armPress(e.pointerId, pt);
       }
     }
 
@@ -3210,6 +3721,20 @@ class WickChart extends HTMLElementBase {
       if (this._pointers.has(e.pointerId)) this._pointers.set(e.pointerId, pt);
       const ly = this._ly;
 
+      // A finger that wanders before the press lands wanted to pan.
+      const origin = this._pressOrigin;
+      if (this._pressTimer && origin && origin.pointerId === e.pointerId) {
+        if (Math.hypot(pt.x - origin.x, pt.y - origin.y) > WickChart._PRESS_SLOP) {
+          this._disarmPress();
+        }
+      }
+
+      // Scrub: the finger walks the crosshair, the viewport stays put.
+      if (this._scrub && this._pointers.has(e.pointerId)) {
+        this._hoverAt(pt);
+        return;
+      }
+
       if (this._pinch && this._pointers.size >= 2 && ly) {
         const [a, b] = [...this._pointers.values()];
         const dist = Math.hypot(a.x - b.x, a.y - b.y) || 1;
@@ -3257,11 +3782,7 @@ class WickChart extends HTMLElementBase {
 
       if (!ly) return;
       // hover / crosshair
-      const idx = clamp(Math.round(this._indexForX(pt.x)), 0, this._data.length - 1);
-      this._hover = { index: idx, x: this._xFor(idx), y: pt.y };
-      this._maybeSonify(idx);
-      this._emitCrosshair(this._hover);
-      this._invalidate();
+      this._hoverAt(pt);
     }
 
     _pointerUp(e) {
@@ -3275,8 +3796,12 @@ class WickChart extends HTMLElementBase {
       }
       const had = this._pointers.delete(e.pointerId);
       if (this._pointers.size < 2) this._pinch = null;
+      if (this._pressOrigin && this._pressOrigin.pointerId === e.pointerId) this._disarmPress();
       if (this._pointers.size === 0) {
         this._canvas.classList.remove('grabbing');
+        // Lifting ends the scrub — the crosshair is not left stranded on a
+        // touchscreen, where nothing else would ever clear it.
+        this._endScrub();
         if (this._brushDrag && had) {
           const b = this._brushDrag;
           this._brushDrag = null;