emberwick 0.3.0 → 0.4.0

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 |
@@ -248,6 +252,7 @@ off()  // unsubscribe
 | `'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 }` |
 
 A drag that happens to end on top of a marker does not fire `'markerClick'` —
 panning and clicking stay distinct.
@@ -289,6 +294,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 +649,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,7 @@ 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
 
   /** Removes listeners, canvases and the render loop. */
   destroy(): void