emberwick 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -3,6 +3,83 @@
 All notable changes to Emberwick are documented here.
 This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] — 2026-09-19
+
+Correctness release. Thirteen defects, most of them able to put wrong data on
+screen without raising anything. Minor rather than patch because two fixes
+change observable behaviour: markers outside the loaded range are now hidden,
+and `priceScale.marginBottom` finally does what it has always documented.
+
+### Fixed
+
+- **An out-of-order tick no longer destroys the newest bar.** `append()` routed
+  any bar at or before the last one into an in-place overwrite, so a late tick
+  deleted the newest candle and left a duplicate timestamp — breaking the
+  ascending-by-time invariant that marker resolution's binary search relies on.
+  Equal timestamps still replace (that is an idempotent re-send of the forming
+  candle); older ones are dropped.
+- **Timeframe is inferred from the median gap, not the first pair.** Any
+  exchange with a trading session puts a large gap at each day boundary; on NSE
+  minute data `bars[1] - bars[0]` across an overnight break reads as 17.75
+  hours. That number drove axis label density and Replay's future-marker
+  cut-off, so a bad inference could leak a future trade into playback.
+- **A null OHLC value no longer collapses the price scale.** `isFinite(null)`
+  is `true`, so a null low passed the guard and dragged the minimum to zero,
+  flattening every candle into the top of the plot.
+- **Log mode no longer collapses on a non-positive price.** A single zero tick
+  clamped to `1e-9` and turned the axis into a ~20-decade range.
+- **A throwing frame no longer freezes the chart permanently.** `Loop` swapped
+  the dirty set out before calling the frame, so one exception lost the pending
+  layers and left nothing to reschedule. The set is now restored and retried;
+  after ten consecutive failures the loop stops with a clear message rather
+  than spinning at 60fps.
+- **State-event dedupe is per listener.** `visibleRange` and `replay` shared a
+  single key, so a late subscriber recorded the current state as "already
+  sent" and every existing listener silently missed that update.
+- **A transient history error no longer disables paging for good.** One failed
+  page used to latch `_exhausted` permanently; it now retries and gives up
+  only after three consecutive failures.
+- **`Replay.seek()` ignores non-finite input.** `clamp()` compares with `<` and
+  `>`, both false against NaN, so `seek(NaN)` passed through and
+  `slice(0, NaN)` blanked the chart.
+- **A replaced replay controller can no longer drive the chart.** Calling
+  `startReplay()` twice left the first controller live in the caller's hands,
+  still able to swap bars into a chart that had moved on. Controllers are now
+  detached by `startReplay()`, `stopReplay()`, `setData()` and `destroy()`.
+- **Markers outside the loaded range are hidden rather than clamped.**
+  `nearestIndex()` clamps, so a trade from long before the window pinned itself
+  to bar 0 and read as an event at the left edge. Tolerance is one timeframe.
+- **`setData()` invalidates the marker index cache**, like every other bar-array
+  mutator already did.
+- **Generated marker ids no longer collide.** They were keyed off the array
+  index, so a remove-then-add could hand the newcomer an id a survivor owned,
+  and `removeMarker(id)` would take the wrong one.
+- **`priceTicks()` cannot hang.** A non-finite bound made the step fall back to
+  1 and the cursor start at `-Infinity`, where `v += step` never advances — an
+  infinite loop inside a frame.
+- **`priceScale.marginBottom` is read.** It was documented, typed and stored,
+  but both bounds were padded from `marginTop`. With the default settings
+  (0.12 / 0.12) nothing changes; only charts that set them differently move.
+
+### Added
+
+- `test/chart-correctness.test.mjs` — 18 cases; 17 fail against 0.4.2.
+- `inferTimeframe(bars, fallback)` exported from `core/Chart.js` for testing.
+- `Replay#detach()`.
+
+## [0.4.2] — 2026-09-19
+
+Metadata only. The code is identical to 0.4.1; nothing needs re-testing.
+
+### Added
+
+- `repository`, `homepage`, `bugs` and `author` in the published manifest, so
+  the npm package page links back to the source, the demo and the issue
+  tracker, and carries a publisher byline. These
+  belong in `package.lib.json` — the root `package.json` is private and never
+  reaches the registry — and 0.4.1 shipped without them. npm versions are
+  immutable, hence a new patch rather than a corrected republish.
+
 ## [0.4.1] — 2026-09-19
 
 Bug-fix release. Three feed-lifecycle races could put wrong prices on screen,

package/README.md

@@ -114,8 +114,15 @@ One contract, used everywhere:
 }
 ```
 
-Bars must be **ascending by time** and **de-duplicated**. The chart infers the
-timeframe from the gap between the first two bars (or from `feed.timeframe`).
+Bars must be **ascending by time** and **de-duplicated**. A bar older than the
+newest one is dropped rather than applied — an out-of-order tick would
+otherwise overwrite the newest candle and leave a duplicate timestamp behind.
+
+The chart infers the timeframe from the **median** gap between consecutive
+bars, sampled across the dataset (or takes it from `feed.timeframe`). The
+median rather than the first pair, because any exchange with a trading session
+puts a large gap at each day boundary — on NSE minute data, `bars[1] - bars[0]`
+across an overnight break reads as 17.75 hours.
 
 ---
 
@@ -423,6 +430,11 @@ A marker is pinned to a **timestamp**, not a bar index, and resolves to the
 nearest bar. Load an older page of history and every marker re-resolves, so
 nothing drifts off its candle.
 
+A marker more than one timeframe outside the loaded range is **hidden**, not
+clamped to the end bar. A trade from six months before the loaded window is
+not an event that happened at the left edge of the chart, and drawing it there
+is worse than not drawing it at all. Page that history in and it appears.
+
 | Field | Default | Notes |
 |---|---|---|
 | `time` | *required* | ms since epoch, snapped to the closest bar |

package/index.d.ts

@@ -351,6 +351,12 @@ export declare class Replay {
   /** Clamped to 0.25–500. */
   setSpeed(speed: number): this
   setLoop(on: boolean): this
+  /**
+   * Stop this controller from ever touching the chart again. Called for you
+   * by startReplay(), stopReplay(), setData() and destroy(); a controller you
+   * are still holding after any of those is inert. Idempotent.
+   */
+  detach(): this
   /** Move the cursor. Out-of-range values clamp. */
   seek(index: number): this
   step(n?: number): this

package/index.js

@@ -63,9 +63,11 @@ class Layers {
     this.ctx = {};
   }
 }
+const MAX_FRAME_ERRORS = 10;
 class Loop {
   constructor(onFrame) {
     this.onFrame = onFrame;
+    this._frameErrors = 0;
     this.fps = 0;
     this._raf = 0;
     this._dirty = /* @__PURE__ */ new Set();
@@ -112,7 +114,18 @@ class Loop {
     let wantMore = false;
     try {
       wantMore = this.onFrame(dirty, dt, now) === true;
+      this._frameErrors = 0;
     } catch (e) {
+      for (const l of dirty) this._dirty.add(l);
+      if (++this._frameErrors >= MAX_FRAME_ERRORS) {
+        console.error(
+          `[Emberwick] frame error — stopping after ${MAX_FRAME_ERRORS} consecutive failures`,
+          e
+        );
+        this._dirty.clear();
+        this.stop();
+        return;
+      }
       console.error("[Emberwick] frame error", e);
     }
     if (wantMore || this._dirty.size) this._schedule();
@@ -322,28 +335,43 @@ class PriceScale {
     const t = 1 - (y - this.top) / this.height;
     return this._inv(a + t * (b - a));
   }
+  /**
+   * Is this a price this scale can actually plot?
+   *
+   * `isFinite(null)` is TRUE — null numifies to 0 — so a bar carrying a null
+   * low used to sail through the old isFinite() guard and drag the minimum to
+   * zero, flattening every candle into the top of the plot. Log mode has the
+   * same problem from the other end: log(0) is -Infinity, and the clamp to
+   * 1e-9 turns one zero tick into a ~20-decade range.
+   */
+  _plottable(v) {
+    return typeof v === "number" && isFinite(v) && (this.mode !== "log" || v > 0);
+  }
   /** Fit visible bars. `extra` lets the forming candle influence the range. */
   fit(bars, from, to, extra) {
     if (!this.auto || !bars.length) return;
     let min = Infinity;
     let max = -Infinity;
+    const consider = (lo, hi) => {
+      if (this._plottable(lo) && lo < min) min = lo;
+      if (this._plottable(hi) && hi > max) max = hi;
+    };
     for (let i = from; i <= to; i++) {
       const b2 = bars[i];
       if (!b2) continue;
-      if (b2.low < min) min = b2.low;
-      if (b2.high > max) max = b2.high;
-    }
-    if (extra) {
-      if (extra.low < min) min = extra.low;
-      if (extra.high > max) max = extra.high;
+      consider(b2.low, b2.high);
     }
+    if (extra) consider(extra.low, extra.high);
     if (!isFinite(min) || !isFinite(max)) return;
     let a = this._fwd(min);
     let b = this._fwd(max);
-    let pad = (b - a) * this.marginTop;
-    if (!(pad > 0)) pad = Math.abs(b) * 0.01 || 1;
-    a -= pad;
-    b += (b - a) * 0 + pad;
+    const span = b - a;
+    let padTop = span * this.marginTop;
+    let padBottom = span * this.marginBottom;
+    if (!(padTop > 0)) padTop = Math.abs(b) * 0.01 || 1;
+    if (!(padBottom > 0)) padBottom = Math.abs(a) * 0.01 || 1;
+    a -= padBottom;
+    b += padTop;
     this._lo.set(a);
     this._hi.set(b);
     if (!this._primed) {
@@ -518,6 +546,7 @@ class Replay {
     this._acc = 0;
     this._markerKey = "";
     this._markerView = null;
+    this._detached = false;
     this.minIndex = Math.min(1, this.lastIndex);
     const from = +options.from;
     this.index = clamp(
@@ -567,8 +596,14 @@ class Replay {
     };
   }
   // ------------------------------------------------------------- transport --
+  /** Stop this controller from ever touching the chart again. Idempotent. */
+  detach() {
+    this._detached = true;
+    this.playing = false;
+    return this;
+  }
   play() {
-    if (this.playing || this.length < 2) return this;
+    if (this._detached || this.playing || this.length < 2) return this;
     if (this.atEnd) {
       this.index = this.minIndex;
       this._apply("seek");
@@ -604,8 +639,10 @@ class Replay {
   }
   /** 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;
+    const n = Math.round(+index);
+    if (!Number.isFinite(n)) return this;
+    const next = clamp(n, this.minIndex, this.lastIndex);
+    if (this._detached || next === this.index) return this;
     this.index = next;
     this._acc = 0;
     this._apply("seek");
@@ -626,7 +663,7 @@ class Replay {
    * true while playback is in flight, which is what keeps the loop awake.
    */
   tick(dt) {
-    if (!this.playing || this.length < 2) return false;
+    if (this._detached || !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;
@@ -684,6 +721,7 @@ class Replay {
    * animates; anything else swaps the prefix and re-anchors without easing.
    */
   _apply(mode) {
+    if (this._detached) return;
     const chart = this.chart;
     if (mode === "step" && chart.bars.length === this.index) {
       chart.append(this.source[this.index]);
@@ -694,6 +732,7 @@ class Replay {
   }
   /** Any state change needs a frame: that frame is what emits 'replay'. */
   _changed() {
+    if (this._detached) return;
     this.chart.loop.invalidate("main");
   }
 }
@@ -705,11 +744,17 @@ function niceStep(span, count) {
   const s = n < 1.5 ? 1 : n < 3 ? 2 : n < 7 ? 5 : 10;
   return s * mag;
 }
+const MAX_TICKS = 1e3;
 function priceTicks(lo, hi, count) {
   const step = niceStep(hi - lo, count);
-  const ticks = [];
+  if (!isFinite(lo) || !isFinite(hi) || hi < lo) return { ticks: [], step };
   const start = Math.ceil(lo / step) * step;
-  for (let v = start; v <= hi + step * 1e-9; v += step) ticks.push(v);
+  const ticks = [];
+  for (let i = 0; i < MAX_TICKS; i++) {
+    const v = start + i * step;
+    if (v > hi + step * 1e-9) break;
+    ticks.push(v);
+  }
   return { ticks, step };
 }
 function decimalsFor(step) {
@@ -950,6 +995,7 @@ const MARKER_SHAPES = [
   "label"
 ];
 const SHAPE_SET = new Set(MARKER_SHAPES);
+let autoId = 0;
 const DEFAULT_POSITION = {
   arrowUp: "belowBar",
   triangleUp: "belowBar",
@@ -962,7 +1008,7 @@ function normalizeMarker(raw, i) {
   const shape = SHAPE_SET.has(raw.shape) ? raw.shape : "circle";
   const position = POSITIONS.has(raw.position) ? raw.position : DEFAULT_POSITION[shape] || "aboveBar";
   return {
-    id: raw.id != null ? String(raw.id) : `mk${i}`,
+    id: raw.id != null ? String(raw.id) : `mk${++autoId}`,
     time: +raw.time,
     price: isFinite(raw.price) ? +raw.price : null,
     shape,
@@ -980,7 +1026,7 @@ function normalizeMarkers(list) {
   if (!Array.isArray(list)) return [];
   const out = [];
   for (let i = 0; i < list.length; i++) {
-    const m = normalizeMarker(list[i], i);
+    const m = normalizeMarker(list[i]);
     if (m) out.push(m);
   }
   out.sort((a, b) => a.time - b.time);
@@ -1004,9 +1050,14 @@ function nearestIndex(bars, time) {
   const b = Math.min(n - 1, lo);
   return Math.abs(bars[a].time - time) <= Math.abs(bars[b].time - time) ? a : b;
 }
-function resolveMarkers(markers, bars) {
+function resolveMarkers(markers, bars, toleranceMs) {
+  const n = bars.length;
+  const tol = isFinite(toleranceMs) && toleranceMs > 0 ? toleranceMs : Infinity;
+  const first = n ? bars[0].time - tol : 0;
+  const last = n ? bars[n - 1].time + tol : 0;
   for (let i = 0; i < markers.length; i++) {
-    markers[i].index = nearestIndex(bars, markers[i].time);
+    const t = markers[i].time;
+    markers[i].index = !n || t < first || t > last ? -1 : nearestIndex(bars, t);
   }
   return markers;
 }
@@ -1275,6 +1326,21 @@ const inactiveReplay = () => ({
   bar: null,
   atEnd: false
 });
+const TF_SAMPLES = 200;
+const MAX_HISTORY_ERRORS = 3;
+function inferTimeframe(bars, fallback = 6e4) {
+  const n = bars.length;
+  if (n < 2) return fallback;
+  const stride = Math.max(1, Math.floor(n / TF_SAMPLES));
+  const gaps = [];
+  for (let i = 1; i < n; i += stride) {
+    const d = bars[i].time - bars[i - 1].time;
+    if (d > 0) gaps.push(d);
+  }
+  if (!gaps.length) return fallback;
+  gaps.sort((a, b) => a - b);
+  return gaps[gaps.length >> 1];
+}
 class Chart {
   constructor(container, options = {}) {
     if (!container) throw new Error("Chart: container element is required");
@@ -1291,6 +1357,7 @@ class Chart {
     this._unsub = null;
     this._loadingHistory = false;
     this._exhausted = false;
+    this._historyErrors = 0;
     this._replay = null;
     this._feedGen = 0;
     this._destroyed = false;
@@ -1308,6 +1375,7 @@ class Chart {
     this._markerHits = [];
     this._hoverMarkerId = null;
     this._resolveKey = "";
+    this._stateKeys = { visibleRange: /* @__PURE__ */ new Map(), replay: /* @__PURE__ */ new Map() };
     this.layers = new Layers(container, ["base", "main", "overlay"]);
     this.ts = new TimeScale(options.timeScale);
     this.ps = new PriceScale(options.priceScale);
@@ -1336,11 +1404,16 @@ class Chart {
   }
   // ------------------------------------------------------------------ data --
   setData(bars) {
-    if (this._replay) this._replay = null;
+    if (this._replay) {
+      this._replay.detach();
+      this._replay = null;
+    }
     this.bars = Array.isArray(bars) ? bars.slice() : [];
     this._exhausted = false;
+    this._historyErrors = 0;
+    this._resolveKey = "";
     if (this.bars.length > 1) {
-      this.ts.timeframeMs = this.bars[1].time - this.bars[0].time;
+      this.ts.timeframeMs = inferTimeframe(this.bars, this.ts.timeframeMs);
     }
     this.ts.setBarCount(this.bars.length);
     this.ts.snapToRealtime();
@@ -1358,7 +1431,7 @@ class Chart {
   _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.timeframeMs = inferTimeframe(this.bars, this.ts.timeframeMs);
     }
     this.ts.setBarCount(this.bars.length);
     this.live.reset();
@@ -1378,11 +1451,21 @@ class Chart {
     this.live.setTarget(bar);
     this.loop.invalidate("main");
   }
-  /** Open a new candle; the previous one is now closed. */
+  /**
+   * Open a new candle; the previous one is now closed.
+   *
+   * A bar OLDER than the newest one is dropped rather than applied. It used
+   * to overwrite the last element — so a late tick silently deleted the
+   * newest candle and left a duplicate timestamp behind, which breaks the
+   * ascending-by-time invariant that marker resolution's binary search
+   * depends on. Feeds are documented as ascending and de-duplicated
+   * (data/DataFeed.js); this is the guard for the ones that are not.
+   */
   append(bar) {
     if (!bar) return;
     const n = this.bars.length;
-    if (n && bar.time <= this.bars[n - 1].time) {
+    if (n && bar.time < this.bars[n - 1].time) return;
+    if (n && bar.time === this.bars[n - 1].time) {
       this.bars[n - 1] = bar;
     } else {
       this.bars.push(bar);
@@ -1424,6 +1507,7 @@ class Chart {
   detachFeed() {
     this._feedGen++;
     this._loadingHistory = false;
+    this._historyErrors = 0;
     if (this._unsub) this._unsub();
     this._unsub = null;
     this.feed = null;
@@ -1455,13 +1539,14 @@ class Chart {
         this._exhausted = true;
         return;
       }
+      this._historyErrors = 0;
       this.bars = added.concat(this.bars);
       this.ts.barCount = this.bars.length;
       this.ts._right.jump(this.ts._right.value + added.length);
       this.loop.invalidate("all");
     } catch (err) {
       if (gen !== this._feedGen || this._destroyed) return;
-      this._exhausted = true;
+      if (++this._historyErrors >= MAX_HISTORY_ERRORS) this._exhausted = true;
       this._emitError(err, "loadHistory");
     } finally {
       if (gen === this._feedGen) this._loadingHistory = false;
@@ -1663,15 +1748,19 @@ class Chart {
     set.add(fn);
     if (event === "visibleRange") {
       const payload = this.visibleRange();
-      this._rangeKey = this._rangeIdentity(payload);
+      this._stateKeys.visibleRange.set(fn, this._rangeIdentity(payload));
       fn(payload);
     }
     if (event === "replay") {
       const payload = this.replayState();
-      this._replayKey = this._replayIdentity(payload);
+      this._stateKeys.replay.set(fn, this._replayIdentity(payload));
       fn(payload);
     }
-    return () => set.delete(fn);
+    return () => {
+      set.delete(fn);
+      const keys = this._stateKeys[event];
+      if (keys) keys.delete(fn);
+    };
   }
   // ------------------------------------------------------------------ range --
   /**
@@ -1709,13 +1798,23 @@ class Chart {
    *   work until the view stops moving would wait forever.
    */
   _emitVisibleRange(from, to) {
-    const set = this._listeners.visibleRange;
+    this._emitState("visibleRange", this._rangePayload(from, to), this._rangeIdentity);
+  }
+  /**
+   * Deliver a state event to every listener that has not already seen this
+   * exact state. Keys are per-listener, so one subscriber can never suppress
+   * another's update, and a brand-new listener (no key yet) always gets one.
+   */
+  _emitState(event, payload, identity) {
+    const set = this._listeners[event];
     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);
+    const key = identity.call(this, payload);
+    const keys = this._stateKeys[event];
+    for (const fn of set) {
+      if (keys.get(fn) === key) continue;
+      keys.set(fn, key);
+      fn(payload);
+    }
   }
   // ----------------------------------------------------------------- replay --
   /**
@@ -1742,6 +1841,7 @@ class Chart {
     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();
+    if (this._replay) this._replay.detach();
     this._replay = new Replay(this, { ...options, bars: dataset });
     return this._replay;
   }
@@ -1749,6 +1849,7 @@ class Chart {
   stopReplay() {
     if (!this._replay) return;
     const full = this._replay.source;
+    this._replay.detach();
     this._replay = null;
     this.setData(full);
   }
@@ -1769,13 +1870,7 @@ class Chart {
    * 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);
+    this._emitState("replay", this.replayState(), this._replayIdentity);
   }
   // ----------------------------------------------------------- annotations --
   /** Replace every marker. Each `time` is resolved to its nearest bar. */
@@ -1848,7 +1943,7 @@ class Chart {
     if (markers.length) {
       const key = markers.length + ":" + this.bars.length + ":" + (this.bars.length ? this.bars[0].time : 0);
       if (key !== this._resolveKey) {
-        resolveMarkers(markers, this.bars);
+        resolveMarkers(markers, this.bars, this.ts.timeframeMs);
         this._resolveKey = key;
       }
     }
@@ -1917,6 +2012,8 @@ class Chart {
     this.loop.stop();
     this.layers.destroy();
     for (const set of Object.values(this._listeners)) set.clear();
+    for (const keys of Object.values(this._stateKeys)) keys.clear();
+    if (this._replay) this._replay.detach();
     this._replay = null;
     this._markers = [];
     this._markerHits = [];
@@ -2100,7 +2197,7 @@ class RandomFeed extends DataFeed {
 function createChart(container, options) {
   return new Chart(container, options);
 }
-const version = "0.4.1";
+const version = "0.5.0";
 export {
   Chart,
   DataFeed,