emberwick 0.2.0 → 0.4.0

package/index.js

@@ -169,7 +169,7 @@ class Tween {
     return true;
   }
 }
-const clamp$1 = (v, a, b) => v < a ? a : v > b ? b : v;
+const clamp$2 = (v, a, b) => v < a ? a : v > b ? b : v;
 class TimeScale {
   constructor({ spacing = 9, minSpacing = 0.8, maxSpacing = 160, rightOffset = 12 } = {}) {
     this.minSpacing = minSpacing;
@@ -216,14 +216,14 @@ class TimeScale {
     const first = Math.floor(this.index(0)) - 1;
     const last = Math.ceil(this.index(this.width)) + 1;
     return {
-      from: clamp$1(first, 0, Math.max(0, this.barCount - 1)),
-      to: clamp$1(last, 0, Math.max(0, this.barCount - 1))
+      from: clamp$2(first, 0, Math.max(0, this.barCount - 1)),
+      to: clamp$2(last, 0, Math.max(0, this.barCount - 1))
     };
   }
   _clampRight(v) {
     const max = this.barCount - 1 + this.rightOffset + this.width / this._spacing.target;
     const min = Math.min(4, this.barCount - 1 + this.rightOffset);
-    return clamp$1(v, min, max);
+    return clamp$2(v, min, max);
   }
   /** Immediate pan, in pixels. Positive dx drags content right (back in time). */
   panBy(dxPx) {
@@ -236,7 +236,7 @@ class TimeScale {
   /** Zoom by `factor`, keeping the bar under `x` pinned. */
   zoomAt(x, factor) {
     const s0 = this._spacing.target;
-    const s1 = clamp$1(s0 * factor, this.minSpacing, this.maxSpacing);
+    const s1 = clamp$2(s0 * factor, this.minSpacing, this.maxSpacing);
     if (Math.abs(s1 - s0) < 1e-9) return false;
     const anchorX = this.follow ? this.width : x;
     const r0 = this._right.target;
@@ -250,6 +250,15 @@ class TimeScale {
     this.follow = true;
     this._right.set(this.barCount - 1 + this.rightOffset);
   }
+  /**
+   * Same anchor, no easing. Scrubbing re-targets the right edge many times a
+   * second; easing each one reads as the chart lagging the scrubber, which is
+   * the same reason a drag uses jump().
+   */
+  jumpToRealtime() {
+    this.follow = true;
+    this._right.jump(this.barCount - 1 + this.rightOffset);
+  }
   reset() {
     this._spacing.set(this._initial);
     this.snapToRealtime();
@@ -264,7 +273,7 @@ class TimeScale {
     return this._spacing.settled && this._right.settled;
   }
 }
-const clamp = (v, a, b) => v < a ? a : v > b ? b : v;
+const clamp$1 = (v, a, b) => v < a ? a : v > b ? b : v;
 class PriceScale {
   constructor({ mode = "linear", tau = 120, marginTop = 0.12, marginBottom = 0.12 } = {}) {
     this.mode = mode;
@@ -349,7 +358,7 @@ class PriceScale {
     const a = this._lo.target;
     const b = this._hi.target;
     const mid = (a + b) / 2;
-    const half = (b - a) / 2 * clamp(factor, 0.2, 5);
+    const half = (b - a) / 2 * clamp$1(factor, 0.2, 5);
     this._lo.set(mid - half);
     this._hi.set(mid + half);
   }
@@ -492,6 +501,202 @@ class Inertia {
     return dx;
   }
 }
+const clamp = (v, a, b) => v < a ? a : v > b ? b : v;
+const MIN_SPEED = 0.25;
+const MAX_SPEED = 500;
+const MAX_STEPS_PER_FRAME = 240;
+class Replay {
+  constructor(chart, options = {}) {
+    const src = Array.isArray(options.bars) ? options.bars : [];
+    this.chart = chart;
+    this.source = src.slice();
+    this.baseInterval = Math.max(16, +options.baseInterval || 1e3);
+    this.speed = clamp(+options.speed || 1, MIN_SPEED, MAX_SPEED);
+    this.looping = options.loop === true;
+    this.follow = options.follow !== false;
+    this.playing = false;
+    this._acc = 0;
+    this._markerKey = "";
+    this._markerView = null;
+    this.minIndex = Math.min(1, this.lastIndex);
+    const from = +options.from;
+    this.index = clamp(
+      Number.isFinite(from) ? Math.round(from) : Math.floor(this.lastIndex / 2),
+      this.minIndex,
+      this.lastIndex
+    );
+    this._apply("seek");
+  }
+  // ----------------------------------------------------------------- state --
+  get length() {
+    return this.source.length;
+  }
+  get lastIndex() {
+    return Math.max(0, this.source.length - 1);
+  }
+  get atEnd() {
+    return this.index >= this.lastIndex;
+  }
+  get bar() {
+    return this.source[this.index] || null;
+  }
+  get time() {
+    return this.bar ? this.bar.time : null;
+  }
+  /** 0 at the first playable bar, 1 at the last. */
+  get progress() {
+    const span = this.lastIndex - this.minIndex;
+    return span > 0 ? (this.index - this.minIndex) / span : 1;
+  }
+  /** Real ms between bars at the current speed. */
+  get interval() {
+    return this.baseInterval / this.speed;
+  }
+  /** Snapshot handed to `subscribe('replay', fn)`. */
+  state() {
+    return {
+      active: true,
+      playing: this.playing,
+      index: this.index,
+      length: this.length,
+      progress: this.progress,
+      speed: this.speed,
+      time: this.time,
+      bar: this.bar,
+      atEnd: this.atEnd
+    };
+  }
+  // ------------------------------------------------------------- transport --
+  play() {
+    if (this.playing || this.length < 2) return this;
+    if (this.atEnd) {
+      this.index = this.minIndex;
+      this._apply("seek");
+    }
+    this.playing = true;
+    this._acc = 0;
+    this._changed();
+    return this;
+  }
+  pause() {
+    if (!this.playing) return this;
+    this.playing = false;
+    this._acc = 0;
+    this._changed();
+    return this;
+  }
+  toggle() {
+    return this.playing ? this.pause() : this.play();
+  }
+  /** Multiplier on `baseInterval`. Clamped to 0.25×–500×. */
+  setSpeed(speed) {
+    const s = clamp(+speed || 1, MIN_SPEED, MAX_SPEED);
+    if (s === this.speed) return this;
+    this.speed = s;
+    this._acc = 0;
+    this._changed();
+    return this;
+  }
+  setLoop(on) {
+    this.looping = !!on;
+    this._changed();
+    return this;
+  }
+  /** Move the cursor. Out-of-range values clamp; playback keeps running. */
+  seek(index) {
+    const next = clamp(Math.round(+index), this.minIndex, this.lastIndex);
+    if (next === this.index) return this;
+    this.index = next;
+    this._acc = 0;
+    this._apply("seek");
+    this._changed();
+    return this;
+  }
+  step(n = 1) {
+    return this.seek(this.index + (n || 0));
+  }
+  toStart() {
+    return this.seek(this.minIndex);
+  }
+  toEnd() {
+    return this.seek(this.lastIndex);
+  }
+  /**
+   * Advance with wall-clock time. Called once per frame by the chart; returns
+   * true while playback is in flight, which is what keeps the loop awake.
+   */
+  tick(dt) {
+    if (!this.playing || this.length < 2) return false;
+    this._acc += dt * this.speed;
+    const steps = Math.floor(this._acc / this.baseInterval);
+    if (steps <= 0) return true;
+    this._acc -= steps * this.baseInterval;
+    const last = this.lastIndex;
+    let next = this.index + Math.min(steps, MAX_STEPS_PER_FRAME);
+    if (next > last) {
+      if (this.looping) {
+        this.index = this.minIndex;
+        this._apply("seek");
+        this._changed();
+        return true;
+      }
+      next = last;
+    }
+    const single = next === this.index + 1;
+    this.index = next;
+    this._apply(single ? "step" : "seek");
+    if (this.atEnd && !this.looping) {
+      this.playing = false;
+      this._acc = 0;
+    }
+    this._changed();
+    return this.playing;
+  }
+  // --------------------------------------------------------------- markers --
+  /**
+   * Markers after the cursor are future information: hidden, not clamped.
+   * Without this they would all pin to the newest revealed bar, because
+   * time→index resolution snaps to the NEAREST bar.
+   *
+   * Cached on the cursor, so a paused chart allocates nothing per frame.
+   */
+  markerFilter(markers) {
+    const t = this.time;
+    if (t == null) return markers;
+    const key = this.index + ":" + markers.length;
+    if (key !== this._markerKey || !this._markerView) {
+      const cut = t + (this.chart.ts.timeframeMs || 0) / 2;
+      this._markerView = markers.filter((m) => m.time <= cut);
+      this._markerKey = key;
+    }
+    return this._markerView;
+  }
+  /** Drop the cached slice — the marker set itself changed. */
+  invalidateMarkers() {
+    this._markerKey = "";
+    this._markerView = null;
+  }
+  // ---------------------------------------------------------------- private --
+  /**
+   * Push the revealed prefix into the chart.
+   *
+   * 'step' (exactly one bar forward) takes the live path so the new candle
+   * animates; anything else swaps the prefix and re-anchors without easing.
+   */
+  _apply(mode) {
+    const chart = this.chart;
+    if (mode === "step" && chart.bars.length === this.index) {
+      chart.append(this.source[this.index]);
+      return;
+    }
+    chart._swapBars(this.source.slice(0, this.index + 1));
+    if (this.follow) chart.ts.jumpToRealtime();
+  }
+  /** Any state change needs a frame: that frame is what emits 'replay'. */
+  _changed() {
+    this.chart.loop.invalidate("main");
+  }
+}
 function niceStep(span, count) {
   const raw = span / Math.max(1, count);
   if (!(raw > 0) || !isFinite(raw)) return 1;
@@ -1059,6 +1264,17 @@ function drawMarkers(ctx, s, placed, hoverId) {
   ctx.restore();
   return hits;
 }
+const inactiveReplay = () => ({
+  active: false,
+  playing: false,
+  index: -1,
+  length: 0,
+  progress: 0,
+  speed: 1,
+  time: null,
+  bar: null,
+  atEnd: false
+});
 class Chart {
   constructor(container, options = {}) {
     if (!container) throw new Error("Chart: container element is required");
@@ -1075,11 +1291,13 @@ class Chart {
     this._unsub = null;
     this._loadingHistory = false;
     this._exhausted = false;
+    this._replay = null;
     this._listeners = {
       crosshair: /* @__PURE__ */ new Set(),
       visibleRange: /* @__PURE__ */ new Set(),
       markerClick: /* @__PURE__ */ new Set(),
-      markerHover: /* @__PURE__ */ new Set()
+      markerHover: /* @__PURE__ */ new Set(),
+      replay: /* @__PURE__ */ new Set()
     };
     this._markers = normalizeMarkers(options.markers);
     this.priceLines = Array.isArray(options.priceLines) ? options.priceLines.slice() : [];
@@ -1115,6 +1333,7 @@ class Chart {
   }
   // ------------------------------------------------------------------ data --
   setData(bars) {
+    if (this._replay) this._replay = null;
     this.bars = Array.isArray(bars) ? bars.slice() : [];
     this._exhausted = false;
     if (this.bars.length > 1) {
@@ -1126,6 +1345,23 @@ class Chart {
     this.ps._primed = false;
     this.loop.invalidate("all");
   }
+  /**
+   * Replace the bar array WITHOUT re-anchoring the view — the deliberate
+   * difference from setData(), which snaps to the right edge and re-primes
+   * the price scale. Replay swaps its revealed prefix through here on every
+   * scrub, so a snap would fight the user's zoom and the price scale would
+   * pop instead of easing between windows.
+   */
+  _swapBars(bars) {
+    this.bars = Array.isArray(bars) ? bars : [];
+    if (this.bars.length > 1) {
+      this.ts.timeframeMs = this.bars[1].time - this.bars[0].time;
+    }
+    this.ts.setBarCount(this.bars.length);
+    this.live.reset();
+    this._resolveKey = "";
+    this.loop.invalidate("all");
+  }
   /** Merge a tick into the forming candle (animated). */
   update(bar) {
     if (!bar) return;
@@ -1167,6 +1403,7 @@ class Chart {
     if (typeof feed.prime === "function") feed.prime(bars[bars.length - 1]);
     this._unsub = feed.subscribe((msg) => {
       if (!msg || !msg.bar) return;
+      if (this._replay) return;
       if (msg.type === "append") this.append(msg.bar);
       else this.update(msg.bar);
     });
@@ -1177,6 +1414,7 @@ class Chart {
     this.feed = null;
   }
   async _maybeLoadHistory() {
+    if (this._replay) return;
     if (this._loadingHistory || this._exhausted || !this.feed) return;
     const { from } = this.ts.visibleRange();
     if (from > 80 || !this.bars.length) return;
@@ -1394,13 +1632,128 @@ class Chart {
     const set = this._listeners[event];
     if (!set) throw new Error(`Chart: unknown event "${event}"`);
     set.add(fn);
+    if (event === "visibleRange") {
+      const payload = this.visibleRange();
+      this._rangeKey = this._rangeIdentity(payload);
+      fn(payload);
+    }
+    if (event === "replay") {
+      const payload = this.replayState();
+      this._replayKey = this._replayIdentity(payload);
+      fn(payload);
+    }
     return () => set.delete(fn);
   }
+  // ------------------------------------------------------------------ range --
+  /**
+   * The window currently on screen. Cheap enough to poll, though
+   * subscribe('visibleRange', fn) is the better way to track it.
+   */
+  visibleRange() {
+    const { from, to } = this.ts.visibleRange();
+    return this._rangePayload(from, to);
+  }
+  _rangePayload(from, to) {
+    const n = this.bars.length;
+    return {
+      from,
+      to,
+      fromTime: n ? this.bars[from].time : null,
+      toTime: n ? this.bars[to].time : null,
+      barCount: n,
+      spacing: this.ts.spacing,
+      settled: this.ts.settled
+    };
+  }
+  _rangeIdentity(p) {
+    return `${p.from}:${p.to}:${p.fromTime}:${p.toTime}:${p.settled ? 1 : 0}`;
+  }
+  /**
+   * Fires only when the window actually changed, so a consumer can hang a
+   * fetch off it without debouncing. Two deliberate choices:
+   *
+   * - `spacing` is NOT part of the identity. It is a float that moves on every
+   *   frame of an eased zoom, so keying on it would make this a 60/sec
+   *   firehose. It is still reported, for level-of-detail decisions.
+   * - `settled` IS part of the identity, so the final event of a gesture
+   *   always arrives with settled:true. Without it, code that defers expensive
+   *   work until the view stops moving would wait forever.
+   */
+  _emitVisibleRange(from, to) {
+    const set = this._listeners.visibleRange;
+    if (!set.size) return;
+    const payload = this._rangePayload(from, to);
+    const key = this._rangeIdentity(payload);
+    if (key === this._rangeKey) return;
+    this._rangeKey = key;
+    for (const fn of set) fn(payload);
+  }
+  // ----------------------------------------------------------------- replay --
+  /**
+   * Start bar-by-bar playback over a fixed dataset.
+   *
+   * With no `bars`, the chart's CURRENT data becomes the dataset — the usual
+   * case: load history, then replay it. The chart is not switched into a
+   * special mode; it is simply handed the revealed prefix, so scales,
+   * annotations, the crosshair and visibleRange all keep behaving normally.
+   *
+   *   chart.startReplay({ from: 200, speed: 4 })
+   *   chart.replay.play()
+   *
+   * @param {object} [options]
+   * @param {Bar[]} [options.bars]          dataset (defaults to current bars)
+   * @param {number} [options.from]         starting index (default: midpoint)
+   * @param {number} [options.speed]        rate multiplier, 0.25–500
+   * @param {number} [options.baseInterval] real ms per bar at 1× (default 1000)
+   * @param {boolean} [options.loop]        restart at the end
+   * @param {boolean} [options.follow]      re-anchor the right edge on scrub
+   * @returns {Replay|null} null if there are fewer than two bars to replay
+   */
+  startReplay(options = {}) {
+    const source = Array.isArray(options.bars) && options.bars.length ? options.bars : this._replay ? this._replay.source : this.bars;
+    if (!source || source.length < 2) return null;
+    const dataset = source.slice();
+    this._replay = new Replay(this, { ...options, bars: dataset });
+    return this._replay;
+  }
+  /** Leave replay and reveal the whole dataset again. */
+  stopReplay() {
+    if (!this._replay) return;
+    const full = this._replay.source;
+    this._replay = null;
+    this.setData(full);
+  }
+  /** The active controller, or null. */
+  get replay() {
+    return this._replay;
+  }
+  /** Current playback state; `{ active: false, ... }` when not replaying. */
+  replayState() {
+    return this._replay ? this._replay.state() : inactiveReplay();
+  }
+  _replayIdentity(p) {
+    return `${p.active ? 1 : 0}:${p.playing ? 1 : 0}:${p.index}:${p.length}:${p.speed}`;
+  }
+  /**
+   * Emitted from the frame, like visibleRange, so a handler can safely touch
+   * the chart. Keyed on cursor + transport, not on the payload object, so a
+   * paused replay emits nothing at all.
+   */
+  _emitReplay() {
+    const set = this._listeners.replay;
+    if (!set.size) return;
+    const payload = this.replayState();
+    const key = this._replayIdentity(payload);
+    if (key === this._replayKey) return;
+    this._replayKey = key;
+    for (const fn of set) fn(payload);
+  }
   // ----------------------------------------------------------- annotations --
   /** Replace every marker. Each `time` is resolved to its nearest bar. */
   setMarkers(markers) {
     this._markers = normalizeMarkers(markers);
     this._resolveKey = "";
+    if (this._replay) this._replay.invalidateMarkers();
     this.loop.invalidate("main");
   }
   /** The current markers, normalised, each with its resolved bar index. */
@@ -1430,6 +1783,7 @@ class Chart {
   // ----------------------------------------------------------------- frame --
   _frame(dirty, dt) {
     let animating = false;
+    if (this._replay && this._replay.tick(dt)) animating = true;
     if (this.ts.tick(dt)) animating = true;
     const dx = this.inertia.tick(dt);
     if (dx) {
@@ -1460,10 +1814,12 @@ class Chart {
       priceLines: this.priceLines,
       zones: this.zones
     };
-    if (this._markers.length) {
-      const key = this.bars.length + ":" + (this.bars.length ? this.bars[0].time : 0);
+    let markers = this._markers;
+    if (this._replay && markers.length) markers = this._replay.markerFilter(markers);
+    if (markers.length) {
+      const key = markers.length + ":" + this.bars.length + ":" + (this.bars.length ? this.bars[0].time : 0);
       if (key !== this._resolveKey) {
-        resolveMarkers(this._markers, this.bars);
+        resolveMarkers(markers, this.bars);
         this._resolveKey = key;
       }
     }
@@ -1475,13 +1831,15 @@ class Chart {
       this._markerHits = drawMarkers(
         this.layers.ctx.main,
         state,
-        layoutMarkers(this._markers, state),
+        layoutMarkers(markers, state),
         this._hoverMarkerId
       );
     }
     if (redrawAll || dirty.has("overlay")) {
       drawCrosshair(this.layers.ctx.overlay, state);
     }
+    this._emitVisibleRange(from, to);
+    this._emitReplay();
     return animating;
   }
   // ------------------------------------------------------------------- api --
@@ -1528,6 +1886,7 @@ class Chart {
     this.loop.stop();
     this.layers.destroy();
     for (const set of Object.values(this._listeners)) set.clear();
+    this._replay = null;
     this._markers = [];
     this._markerHits = [];
     this.priceLines = [];
@@ -1710,14 +2069,17 @@ class RandomFeed extends DataFeed {
 function createChart(container, options) {
   return new Chart(container, options);
 }
-const version = "0.2.0";
+const version = "0.4.0";
 export {
   Chart,
   DataFeed,
   Inertia,
   LiveCandle,
+  MAX_SPEED,
+  MIN_SPEED,
   PriceScale,
   RandomFeed,
+  Replay,
   Smoothed,
   TimeScale,
   Tween,