hyperprop-charting-library 0.1.142 → 0.1.144

package/docs/API.md

@@ -593,7 +593,7 @@ an up measurement, red for down.
 - `updateIndicator(id: string, patch: Partial<IndicatorInstanceOptions>): void`
 - `removeIndicator(id: string): void`
 - `setIndicators(indicators: IndicatorInstanceOptions[]): void`
-- `saveState(): ChartSavedState` — one JSON-serializable snapshot of the full user-visible setup: `{ version: 1, chartType, viewport, drawings, indicators, magnetMode, priceScale, drawingDefaults }`. Chart *data* is not included; keep feeding bars through `setData`/`upsertBar`.
+- `saveState(): ChartSavedState` — one JSON-serializable snapshot of the full user-visible setup: `{ version: 1, chartType, viewport, drawings, indicators, magnetMode, priceScale, drawingDefaults, alerts, timezone, timeFormat }`. Chart *data* is not included; keep feeding bars through `setData`/`upsertBar`.
 - `loadState(state: Partial<ChartSavedState>): void` — restore a `saveState()` blob. Tolerant of partial blobs (missing sections are left untouched), so it doubles as a bulk setter. Register custom script indicator plugins with `registerIndicator` *before* calling it so their instances resolve. Viewport is applied last so pane changes don't clobber the restore.
 - `takeScreenshot(options?: { type?: "image/png" | "image/jpeg"; quality?: number }): string` — returns a data URL of the current frame (default PNG) at the chart's device pixel ratio. Everything on the canvas is included: series, indicators, panes, drawings, legends.
 
@@ -609,11 +609,239 @@ link.download = "chart.png";
 link.click();
 ```
 
+### Time zone and sessions
+
+- `setTimezone(timezone: ChartTimezone): void` / `getTimezone(): ChartTimezone` — an IANA id, `"utc"`, or `"local"` (default). Unknown ids fall back to local instead of throwing.
+- `setTimeFormat(format: "24h" | "12h"): void` / `getTimeFormat()`.
+- `setSession(session: SessionOptions | SessionSpec | SessionPresetName | null): void` / `getSession(): SessionOptions`.
+
+### Undo / redo
+
+- `undo(): boolean` / `redo(): boolean` — return false when the stack is empty.
+- `canUndo(): boolean` / `canRedo(): boolean` / `getUndoRedoState(): UndoRedoState`.
+- `onUndoRedoStateChange(handler)` / `clearHistory(): void`.
+
+### Bar replay
+
+- `startReplay(options?: ReplayStartOptions): void` / `stopReplay(): void`
+- `replayStep(bars?: number): void` — negative rewinds.
+- `replayPlay(speed?: number): void` / `replayPause(): void` / `setReplaySpeed(speed: number): void`
+- `getReplayState(): ReplayState` / `onReplayStateChange(handler)`
+
+### Price alerts
+
+- `setAlerts(alerts: AlertOptions[]): void` / `addAlert(alert): string` / `updateAlert(id, patch)` / `removeAlert(id)` / `getAlerts()`
+- `onAlertTrigger(handler)` / `onAlertAction(handler)`
+
+### Marks
+
+- `setBarMarks(marks: BarMarkOptions[]): void` / `getBarMarks()`
+- `setTimescaleMarks(marks: TimescaleMarkOptions[]): void` / `getTimescaleMarks()`
+- `onMarkClick(handler)` / `onMarkHover(handler)`
+
 - `resize(width?: number, height?: number): void`
 - `destroy(): void`
 
 ---
 
+## Time zones and trading sessions
+
+Timestamps are rendered in whatever zone you choose, and the chart can be told
+the instrument's actual trading hours. Both matter most for futures: a CME day
+opens at 18:00 ET the *previous* calendar evening, so calendar-day boundaries
+draw separators in the wrong places.
+
+```ts
+const chart = createChart(el, {
+  timezone: "America/New_York", // IANA id, "utc", or "local" (default)
+  timeFormat: "24h",            // or "12h"
+  session: {
+    spec: "cme-futures",        // preset name, your own SessionSpec, or null
+    separators: true,           // vertical rule at each session open
+    highlightOutOfSession: true // tint overnight/extended-hours bars
+  }
+});
+
+chart.setTimezone("Asia/Tokyo");
+chart.setSession({ spec: "cme-rth" }); // 09:30–16:00 ET
+```
+
+Presets (`SESSION_PRESETS`): `cme-futures` (Sun–Thu 18:00 → 17:00 ET, including
+the daily maintenance break), `cme-rth`, `us-equities`,
+`us-equities-extended`, `24x7`. A custom spec is three fields:
+
+```ts
+chart.setSession({
+  spec: {
+    timezone: "America/New_York",
+    // Days the session OPENS. For a window that runs past midnight this is the
+    // evening side, so Sun–Thu means Friday evening is closed for the weekend.
+    days: [0, 1, 2, 3, 4],
+    segments: [{ start: "18:00", end: "17:00" }]
+  },
+  highlightOutOfSession: true
+});
+```
+
+Session separators only apply to intraday series (on daily bars every bar is
+its own day). Zone conversion is offset-cached per UTC hour, so DST transitions
+are exact and per-bar lookups stay arithmetic rather than `Intl` calls.
+
+---
+
+## Undo / redo
+
+Covers the drawing document: create, move, restyle, delete, clear. A whole drag
+collapses into one step, and `Ctrl/Cmd+Z` (redo: `Ctrl/Cmd+Shift+Z` or
+`Ctrl+Y`) works whenever the chart canvas has focus.
+
+```ts
+chart.onUndoRedoStateChange((state) => {
+  undoButton.disabled = !state.canUndo;
+  undoButton.title = state.undoLabel ?? "";   // e.g. "Move trendline"
+});
+chart.undo();
+```
+
+Deliberately **not** recorded: viewport changes (panning is navigation, not an
+edit — TradingView made the same call in v30) and bulk `setDrawings` syncs, so a
+host that echoes `onDrawingsChange` straight back never fills the stack with its
+own round-trips. Indicators are excluded too: hosts usually own that state, and
+undoing it here would be overwritten on the next sync. `loadState()` clears the
+history, since a restored layout is a starting point rather than a step.
+
+---
+
+## Bar replay
+
+Hide everything after a chosen bar and step forward through it — the same
+practice loop TradingView's replay gives you, which the Advanced Charts package
+itself does not ship. Indicators, drawings and autoscale all see only the
+revealed bars, so there is no lookahead.
+
+```ts
+chart.startReplay({ fromTimeMs: Date.parse("2026-07-14T13:30:00Z"), speed: 4 });
+chart.replayPlay();          // 4 bars per second
+chart.replayStep(1);         // or step by hand
+chart.replayStep(-1);        // rewind
+chart.onReplayStateChange((s) => {
+  label.textContent = `${s.index + 1}/${s.total}${s.atEnd ? " (end)" : ""}`;
+});
+chart.stopReplay();          // restores the full series
+```
+
+Live bars arriving during replay are buffered rather than shown, and are all
+present when replay stops. Without `fromIndex`/`fromTimeMs` replay starts 70%
+of the way through the series.
+
+---
+
+## Price alerts
+
+Watch levels drawn as a dashed line plus a bell tag on the price axis. The
+chart renders them, lets the user drag them and remove them, and tells you when
+price satisfies the condition; delivery (push, sound, email) stays with the
+host.
+
+```ts
+chart.addAlert({ price: 5120.25, condition: "crossing-up", label: "breakout" });
+
+chart.onAlertTrigger(({ alert, price, timeMs }) => {
+  notify(`${alert.label} hit ${price}`);
+});
+chart.onAlertAction(({ alert, action, price, dragging }) => {
+  if (action === "move" && !dragging) persist(alert.id, price);
+  if (action === "remove") forget(alert.id);
+});
+```
+
+Conditions: `crossing` (either direction), `crossing-up`, `crossing-down`,
+`greater`, `less`. Crossings compare against the last price the alert saw, so an
+alert armed mid-bar fires on the tick that crosses it instead of waiting for a
+close. `once` (default true) disarms after firing; the line stays visible but
+dimmed until you re-arm it with `updateAlert(id, { triggered: false })`.
+Dragging a level re-arms it against the current market.
+
+---
+
+## Marks (events on bars and on the time axis)
+
+```ts
+chart.setBarMarks([
+  { id: "cpi", time: "2026-07-15T12:30:00Z", label: "C", text: "CPI 0.2% m/m", color: "#f7a600" }
+]);
+chart.setTimescaleMarks([
+  { id: "fomc", time: "2026-07-29T18:00:00Z", label: "F", text: "FOMC statement", shape: "diamond" }
+]);
+chart.onMarkClick(({ mark, clientX, clientY }) => openPopover(mark, clientX, clientY));
+chart.onMarkHover((event) => (event ? showTooltip(event) : hideTooltip()));
+```
+
+Bar marks pin under (or above) the bar their timestamp falls on, or at an exact
+`price`. Time-axis marks sit at the foot of the plot. Both accept
+`circle | square | diamond | flag`, expose hover and click, and are host data —
+they are not part of `saveState()`.
+
+---
+
+## In-chart data line
+
+The symbol/OHLC line TradingView draws in the top-left of the plot. Hosts have
+been building this in DOM and re-rendering it on every crosshair move; drawn
+in-canvas it just follows the frame, inherits the theme's colors, and costs
+nothing per pointer move.
+
+```ts
+createChart(el, {
+  dataLine: {
+    visible: true,
+    symbol: "NQU6",
+    interval: "1h",
+    exchange: "CME",
+    showVolume: true,
+    statusColor: marketOpen ? "#22c55e" : "#ef4444",
+    details: [
+      { label: "Session", value: "RTH" },
+      { value: "Closed", color: "#fff", background: "rgba(242,54,69,0.85)" },
+    ],
+  },
+});
+```
+
+Values track the hovered bar and fall back to the latest one, the change is
+colored by direction, and the indicator legend moves down to sit under it.
+Detail chips are dropped rather than clipped when the row runs out of width.
+Off by default so hosts with their own overlay don't suddenly render two.
+
+## Viewport transitions
+
+The discrete jumps — `resetViewport()`, `fitContent()`,
+`setFollowingLatest(true)` and the `Home`/`End`/`R` shortcuts — ease into place
+over `animation.durationMs` (default 260) instead of teleporting, so it stays
+obvious which way the chart moved. Zoom interpolates geometrically, so each
+frame changes scale by the same ratio rather than appearing to accelerate.
+
+Continuous gestures (drag, wheel, pinch) are never animated — they already
+track the input — and any pointer interaction cancels a transition in flight.
+The whole thing is skipped when the OS asks for reduced motion, or with
+`animation: { viewportTransitions: false }`.
+
+## Indicator recomputation
+
+Indicator series are memoised per (indicator, inputs, series fingerprint). A
+live tick changes the fingerprint, which used to mean every indicator
+recomputed its whole series on every animation frame — measured at 50k bars
+with 10 indicators, that was ~11ms of the frame budget and dropped the chart to
+51fps.
+
+While *only the forming bar* is ticking, recomputation is now throttled to
+`indicatorUpdate.liveThrottleMs` (default 80ms). The values are always exact —
+this changes how often the live bar's output refreshes, never how it is
+computed — and anything structural (a bar closing, history prepending, inputs
+or length changing) recomputes immediately, so closed bars are never stale.
+Same benchmark after: 8.4ms and 118fps. Set `liveThrottleMs: 0` to recompute on
+every frame.
+
 ## Themes
 
 A theme is the chart's whole palette as one object, so hosts stop setting a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyperprop-charting-library",
-  "version": "0.1.142",
+  "version": "0.1.144",
   "description": "Lightweight TypeScript charting core",
   "type": "module",
   "main": "./dist/hyperprop-charting-library.cjs",
@@ -21,7 +21,8 @@
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts --clean && cp \"./dist/index.js\" \"./dist/hyperprop-charting-library.js\" && cp \"./dist/index.cjs\" \"./dist/hyperprop-charting-library.cjs\" && cp \"./dist/index.d.ts\" \"./dist/hyperprop-charting-library.d.ts\"",
     "dev": "tsup src/index.ts --format esm,cjs --dts --watch --onSuccess \"cp ./dist/index.js ./dist/hyperprop-charting-library.js && cp ./dist/index.cjs ./dist/hyperprop-charting-library.cjs && cp ./dist/index.d.ts ./dist/hyperprop-charting-library.d.ts\"",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npx tsx src/time.test.mjs"
   },
   "devDependencies": {
     "tsup": "^8.5.0"