emberwick 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+All notable changes to Emberwick are documented here.
+This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.4.1] — 2026-09-19
+
+Bug-fix release. Three feed-lifecycle races could put wrong prices on screen,
+so this supersedes 0.4.0 for anyone attaching a `DataFeed`.
+
+### Fixed
+
+- **A slow `setFeed()` no longer overwrites a newer one.** `setFeed()` awaited
+  `getBars()` without recording which call was current, so switching symbols
+  faster than the network could resolve let the *earlier* request win: it
+  replaced the new symbol's bars, overwrote `_unsub` — leaving the newer
+  subscription permanently unreachable — and, because both feeds wrote to the
+  bar slot keyed on the last bar's time, made the forming candle alternate
+  between two instruments with no error raised. Every async feed read is now
+  stamped with a generation that `setFeed()`, `detachFeed()` and `destroy()`
+  invalidate.
+- **Lazy history pages are bound to the feed that requested them.** A page in
+  flight during a symbol switch could prepend one instrument's bars onto
+  another's, and a stale empty page could latch `_exhausted` on the *new*
+  symbol, permanently disabling paging for an instrument with history left.
+  The page boundary is also re-read after the await, so a late page can no
+  longer splice into the middle of the array and break the ascending-by-time
+  invariant that marker resolution's binary search depends on.
+- **Prepending history shifts the viewport exactly once.** `Smoothed.jump()`
+  writes both `value` and `target`, so the follow-up `set(target + n)` added
+  the page size a second time. The view eased past the newest bar, and because
+  that pushed the visible range beyond the 80-bar trigger, lazy paging stopped
+  firing for the rest of the session — one page load could permanently disable
+  the feature.
+- **`destroy()` is idempotent.** A second call threw from `Layers.destroy()`,
+  which React 18 StrictMode's double-unmount could reach.
+
+### Added
+
+- **`'error'` event.** `subscribe('error', fn)` receives the thrown value from
+  a failed `getBars()`, in both `setFeed()` and history paging. Previously
+  `setFeed()` had no error path at all: a rejection escaped as an unhandled
+  rejection and left a permanently blank chart that a consumer could not even
+  detect. With no subscriber the error is logged rather than swallowed.
+- **First test suite.** `npm test` runs `test/chart-feed-race.test.mjs` on
+  plain Node — no jsdom, no browser. Eight of its nine cases fail against
+  0.4.0. `npm run release` now runs it before building.
+
+### Docs
+
+- Documented the `'error'` event and feed-failure handling.
+- Removed a duplicated header row in the events table.
+
+## [0.4.0] — 2026-09-16
+
+### Added
+
+- Bar-by-bar `Replay` with transport, scrubbing, speed control and looping.
+- Annotations: nine marker shapes, price lines and shaded zones, with
+  collision-aware stacking and hover/click hit-testing.
+- `'visibleRange'` state event and `chart.visibleRange()`.
+
+## [0.1.0] — 2026-09-16
+
+First public release: canvas candlestick core, `DataFeed` seam, `RandomFeed`,
+React adapter, web component, UMD build.

package/README.md

@@ -225,6 +225,10 @@ const chart = createChart(el, {
 | `setAnimate(bool)` | Toggle live-candle easing |
 | `setMagnet(bool)` | Toggle crosshair OHLC snapping |
 | `snapToRealtime()` | Jump back to the newest bar and re-enable autoscale |
+| `startReplay(options?)` | Begin bar-by-bar playback. Returns the `Replay`, or `null` if there is nothing to replay |
+| `stopReplay()` | Leave replay and reveal the whole dataset again |
+| `replayState()` | Current playback state. `{ active: false, ... }` when not replaying |
+| `chart.replay` | Getter — the active `Replay` controller, or `null` |
 | `toImage()` | PNG data URL of the composited layers |
 | `destroy()` | Remove listeners, stop the loop, drop canvases |
 | `chart.fps` | Getter — measured frames per second |
@@ -240,18 +244,39 @@ const off = chart.subscribe('crosshair', (payload) => {
 off()  // unsubscribe
 ```
 
-| Event | Payload |
-|---|---|
 | Event | Payload |
 |---|---|
 | `'crosshair'` | `{ index, bar, price }`, or `null` when the pointer leaves the plot |
 | `'markerHover'` | The marker under the pointer, or `null` when none is |
 | `'markerClick'` | The clicked marker. Only fires on a hit, never with `null` |
 | `'visibleRange'` | `{ from, to, fromTime, toTime, barCount, spacing, settled }` |
+| `'replay'` | `{ active, playing, index, length, progress, speed, time, bar, atEnd }` |
+| `'error'` | The thrown value from a failed feed read. See below |
 
 A drag that happens to end on top of a marker does not fire `'markerClick'` —
 panning and clicking stay distinct.
 
+### Feed errors
+
+`getBars()` is your code, so it can reject — a 502, an expired token, an
+aborted request. Both paths that call it (`setFeed()` and the lazy history
+paging) route a rejection to `'error'` rather than letting it escape as an
+unhandled rejection:
+
+```js
+chart.subscribe('error', (err) => {
+  toast('Could not load market data')
+  console.error(err)
+})
+```
+
+With no `'error'` subscriber the failure is logged to the console instead of
+vanishing. `setFeed()` itself never rejects, so `await chart.setFeed(feed)`
+is safe to leave unguarded; subscribe to `'error'` to react to the failure.
+
+A failed history page sets the same "stop asking" latch an empty page does, so
+the chart will not retry that boundary on every pan.
+
 ### Tracking the visible range
 
 `'visibleRange'` is a **state** event rather than a notification, which makes it
@@ -289,6 +314,84 @@ payload on demand if you would rather poll than subscribe.
 
 ---
 
+## Replay
+
+Play a fixed dataset back bar by bar — backtesting playback, a market-open
+recap, a training drill.
+
+```js
+chart.setData(bars)
+
+const replay = chart.startReplay({ from: 200, speed: 4 })
+replay.play()
+
+chart.subscribe('replay', (s) => {
+  scrubber.value = s.index
+  clock.textContent = new Date(s.time).toLocaleTimeString()
+  if (s.atEnd) playBtn.textContent = 'Restart'
+})
+```
+
+The chart is never put into a special mode. The controller keeps the dataset
+aside and hands the chart only the **revealed prefix**, so scales, crosshair,
+annotations and `'visibleRange'` behave exactly as they do on live data that
+happens to end at the cursor.
+
+Revealing the next bar goes through the same path a feed tick takes, so the
+candle grows in and the axis glides. Scrubbing swaps the prefix and jumps —
+easing a scrub would read as lag, the same rule the pan gesture follows.
+
+### `chart.startReplay(options?)`
+
+| Option | Default | Notes |
+|---|---|---|
+| `bars` | the chart's current bars | The dataset to replay. Never mutated |
+| `from` | midpoint | Starting cursor index |
+| `speed` | `1` | Multiplier, clamped to `0.25`–`500` |
+| `baseInterval` | `1000` | Real ms one bar takes at 1× |
+| `loop` | `false` | Restart at the end instead of stopping |
+| `follow` | `true` | Re-anchor the right edge on the cursor when scrubbing |
+
+Returns the `Replay`, or `null` when there are fewer than two bars. While a
+replay is active an attached feed is ignored, so live ticks cannot fight the
+cursor; `stopReplay()` restores the full dataset and resumes normal service.
+
+### Transport
+
+Every method returns the controller, so calls chain.
+
+| Method | Description |
+|---|---|
+| `play()` / `pause()` / `toggle()` | Pressing play at the end restarts from the beginning |
+| `seek(index)` | Move the cursor. Out-of-range values clamp |
+| `step(n = 1)` | Relative move; `step(-1)` goes back a bar |
+| `toStart()` / `toEnd()` | Jump to either end |
+| `setSpeed(x)` | Clamped to `0.25`–`500`. Never bursts bars on a rate change |
+| `setLoop(bool)` | Toggle looping |
+
+Readable state: `index`, `length`, `progress` (0–1), `speed`, `time`, `bar`,
+`atEnd`, `playing`, and `interval` (real ms between bars at the current
+speed).
+
+### The `'replay'` event
+
+`{ active, playing, index, length, progress, speed, time, bar, atEnd }`.
+
+Like `'visibleRange'` it is a **state** event: a new subscriber is called
+immediately, and after `stopReplay()` it fires once with `active: false` so a
+UI can reset itself without special-casing teardown. `chart.replayState()`
+returns the same payload on demand.
+
+**Markers after the cursor are hidden, not clamped.** Time→index resolution
+snaps to the nearest bar, so without that filter every future trade would pile
+onto the newest revealed candle — and a replay that shows you tomorrow's
+entries is worse than no replay at all.
+
+The cursor never goes below index 1: the scales infer the timeframe from the
+first pair of bars.
+
+---
+
 ## Annotations
 
 Three independent collections, each replaced wholesale. Zones paint behind the
@@ -566,6 +669,7 @@ import {
   TimeScale, PriceScale,        // scales (advanced)
   Smoothed, Tween, Inertia,     // motion primitives
   LiveCandle,
+  Replay, MIN_SPEED, MAX_SPEED, // bar-by-bar playback
   easeOutCubic, easeInOutCubic,
   mulberry32,                   // seeded PRNG
   version,

package/index.d.ts

@@ -289,6 +289,80 @@ export declare class PriceScale {
   readonly hi: number
 }
 
+/* ---------------------------------------------------------------- replay -- */
+
+export interface ReplayOptions {
+  /** Dataset to replay. Defaults to the chart's current bars. */
+  bars?: Bar[]
+  /** Starting cursor index. Default: the midpoint of the dataset. */
+  from?: number
+  /** Rate multiplier, clamped to 0.25–500. Default 1. */
+  speed?: number
+  /** Real milliseconds one bar takes at 1×. Default 1000. */
+  baseInterval?: number
+  /** Restart from the beginning instead of stopping at the end. Default false. */
+  loop?: boolean
+  /** Re-anchor the right edge on the cursor when scrubbing. Default true. */
+  follow?: boolean
+}
+
+/** Payload of the 'replay' event, and the return of chart.replayState(). */
+export interface ReplayState {
+  /** False when the chart is not replaying; every other field is then inert. */
+  active: boolean
+  playing: boolean
+  /** Cursor: index of the newest revealed bar. -1 when inactive. */
+  index: number
+  /** Size of the dataset being replayed. */
+  length: number
+  /** 0 at the first playable bar, 1 at the last. */
+  progress: number
+  speed: number
+  /** `time` of the bar at the cursor. */
+  time: number | null
+  bar: Bar | null
+  atEnd: boolean
+}
+
+/**
+ * Bar-by-bar playback over a fixed dataset. Obtained from
+ * `chart.startReplay()` or `chart.replay`; not constructed directly.
+ */
+export declare class Replay {
+  readonly source: Bar[]
+  readonly length: number
+  readonly lastIndex: number
+  readonly atEnd: boolean
+  readonly bar: Bar | null
+  readonly time: number | null
+  readonly progress: number
+  /** Real ms between bars at the current speed. */
+  readonly interval: number
+  index: number
+  speed: number
+  playing: boolean
+  looping: boolean
+  follow: boolean
+  baseInterval: number
+
+  play(): this
+  pause(): this
+  toggle(): this
+  /** Clamped to 0.25–500. */
+  setSpeed(speed: number): this
+  setLoop(on: boolean): this
+  /** Move the cursor. Out-of-range values clamp. */
+  seek(index: number): this
+  step(n?: number): this
+  toStart(): this
+  toEnd(): this
+  state(): ReplayState
+}
+
+/** Speed bounds accepted by `setSpeed`. */
+export declare const MIN_SPEED: number
+export declare const MAX_SPEED: number
+
 /* ----------------------------------------------------------------- chart -- */
 
 export declare class Chart {
@@ -317,6 +391,21 @@ export declare class Chart {
   /** Topmost marker under a plot-relative point, else null. */
   markerAt(x: number, y: number): ResolvedMarker | null
 
+  /**
+   * Start bar-by-bar playback. With no `bars`, the chart's current data is
+   * the dataset. Returns null if there are fewer than two bars to replay.
+   *
+   *   chart.startReplay({ from: 200, speed: 4 })
+   *   chart.replay.play()
+   */
+  startReplay(options?: ReplayOptions): Replay | null
+  /** Leave replay and reveal the whole dataset again. */
+  stopReplay(): void
+  /** The active controller, or null. */
+  readonly replay: Replay | null
+  /** Current playback state; `{ active: false, ... }` when not replaying. */
+  replayState(): ReplayState
+
   setTheme(theme: Partial<Theme>): void
   setPriceMode(mode: PriceMode): void
   setAnimate(on: boolean): void
@@ -342,6 +431,12 @@ export declare class Chart {
   subscribe(event: 'markerClick', fn: (marker: ResolvedMarker) => void): () => void
   subscribe(event: 'markerHover', fn: (marker: ResolvedMarker | null) => void): () => void
   subscribe(event: 'visibleRange', fn: (range: VisibleRangePayload) => void): () => void
+  subscribe(event: 'replay', fn: (state: ReplayState) => void): () => void
+  /**
+   * Feed failures: a rejected `getBars()` from either `setFeed()` or lazy
+   * history paging. With no subscriber the error is logged instead.
+   */
+  subscribe(event: 'error', fn: (error: unknown) => void): () => void
 
   /** Removes listeners, canvases and the render loop. */
   destroy(): void