emberwick 0.2.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 |
@@ -240,16 +244,132 @@ 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'` | **Accepted but never emitted.** See *Known gaps* |
+| `'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.
 
+### Tracking the visible range
+
+`'visibleRange'` is a **state** event rather than a notification, which makes it
+usable without any debouncing of your own:
+
+- A new subscriber is called **immediately** with the current window, so it
+  never has to wait for the user to pan before it knows what is on screen.
+- It then fires **only when the window actually changes**. Indices are
+  integers, so a slow pan at 9px/bar produces roughly one event every nine
+  frames, not one per frame.
+- `spacing` is reported but is deliberately *not* part of the change test — it
+  is a float that moves every frame of an eased zoom, and keying on it would
+  turn this into a 60/sec firehose. Use it for level-of-detail decisions.
+- `settled` *is* part of the change test, so the final event of a gesture
+  always arrives with `settled: true`. That makes "wait until the view stops
+  moving, then do the expensive thing" a safe pattern.
+
+```js
+const off = chart.subscribe('visibleRange', async (r) => {
+  // paginate backwards when the user approaches the left edge
+  if (r.from < 50 && r.settled && r.fromTime) {
+    const older = await myApi.bars({ to: r.fromTime, limit: 500 })
+    chart.setData(older.concat(chart.bars))
+  }
+})
+```
+
+Syncing a second chart is the other common use — feed `fromTime`/`toTime`
+straight into the other instance. And `chart.visibleRange()` returns the same
+payload on demand if you would rather poll than subscribe.
+
+> The chart also paginates backwards **on its own** through
+> `feed.getBars({ to })` whenever you have attached a feed. This event is for
+> when you want to drive that yourself, or to drive something other than data.
+
+---
+
+## 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
@@ -529,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,
@@ -607,8 +728,6 @@ src/App.jsx, src/styles.css  the playground (not published)
 
 Honest list of what isn't there yet:
 
-- **`subscribe('visibleRange', fn)` never fires.** The event is accepted and
-  the handler is stored, but nothing emits it. Use `'crosshair'` for now.
 - **No OHLCV legend in the package.** `subscribe('crosshair', fn)` gives you
   the hovered bar; rendering the readout is still yours to do.
 - **Markers are not draggable.** They are hit-tested for hover and click, but

package/index.d.ts

@@ -179,6 +179,28 @@ export interface CrosshairPayload {
   price: number
 }
 
+/** Payload of the 'visibleRange' event, and the return of chart.visibleRange(). */
+export interface VisibleRangePayload {
+  /** First visible bar index, clamped to the loaded data. */
+  from: number
+  /** Last visible bar index, clamped to the loaded data. */
+  to: number
+  /** `bars[from].time`, or null when no bars are loaded. */
+  fromTime: number | null
+  /** `bars[to].time`, or null when no bars are loaded. */
+  toTime: number | null
+  /** Total bars currently loaded. */
+  barCount: number
+  /** Current pixels per bar — useful for level-of-detail decisions. */
+  spacing: number
+  /**
+   * False while the view is still easing. The last event of a gesture always
+   * arrives with `settled: true`, so it is safe to defer expensive work
+   * (a fetch, a re-aggregation) until you see it.
+   */
+  settled: boolean
+}
+
 /* ------------------------------------------------------------------ feed -- */
 
 export interface GetBarsRequest {
@@ -267,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 {
@@ -295,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
@@ -306,14 +417,21 @@ export declare class Chart {
   /** Rolling frames-per-second of the render loop. */
   readonly fps: number
 
+  /** The window currently on screen. Cheap enough to poll. */
+  visibleRange(): VisibleRangePayload
+
   /**
    * Subscribe to a chart event. Returns an unsubscribe function.
-   * NOTE: 'visibleRange' is accepted but is not currently emitted.
+   *
+   * 'visibleRange' is a state event rather than a notification: a new
+   * subscriber is called immediately with the current window, and then only
+   * when that window actually changes — so no debouncing is required.
    */
   subscribe(event: 'crosshair', fn: (payload: CrosshairPayload | null) => void): () => void
   subscribe(event: 'markerClick', fn: (marker: ResolvedMarker) => void): () => void
   subscribe(event: 'markerHover', fn: (marker: ResolvedMarker | null) => void): () => void
-  subscribe(event: 'visibleRange', fn: (range: { from: number; to: number }) => 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