wickchart 1.5.0 → 1.6.0

package/README.md

@@ -707,6 +707,193 @@ writer wins, remote updates never touch the local undo stack. Peer
 dependency: wickchart ≥ 1.4. See the live playground in the docs (Drawings
 section — it shares a room, so open it twice and draw on either chart).
 
+### Sessions — the `wickchart-sessions` plugin
+
+Market session shading as opt-in bytes (~6 KB gz, own CI budget): Asia /
+London / New York and other sessions drawn as translucent bands, with labels,
+closed-weekend shading for equities/futures, and crosshair hover events.
+Presets for crypto & forex use the common UTC convention; equity/futures
+presets use IANA timezones, so 09:30 is the real 09:30 across DST changes.
+Custom defs (`{ name, start, end, tz?, days?, color?, alpha? }`) cover
+midnight-crossing sessions and weekday filters.
+
+```js
+npm install wickchart wickchart-sessions   // sessions are a separate opt-in package
+
+import { attachSessions } from 'wickchart-sessions';
+
+const sessions = attachSessions(chart, { preset: 'crypto' });
+sessions.setPreset('nyse');   // 'crypto' | 'forex' | 'nyse' | 'cme' | null
+sessions.setSessions([...]);  // custom defs (validated; getSessions() → JSON)
+sessions.setWeekends(true);   // shade closed Sat+Sun (default for nyse/cme)
+chart.addEventListener('wick:sessions', (e) => status.textContent = e.detail.hover || '');
+```
+
+The hover bridge listens to the chart's own crosshair events, so shading
+never claims a pointer gesture — pan/zoom/measure work untouched. Peer
+dependency: wickchart ≥ 1.4.
+
+### Replay — the `wickchart-replay` plugin
+
+Bar replay as opt-in bytes (~3 KB gz, own CI budget): play history forward
+bar-by-bar or at speed while the future stays hidden. The whole engine runs
+on the public data API — a `setData` slice hides the future, `update()`
+appends one bar per step — so the core stays replay-free. A badge layer shows
+the mode and position at a glance.
+
+```js
+npm install wickchart wickchart-replay   // replay is a separate opt-in package
+
+import { attachReplay } from 'wickchart-replay';
+
+const replay = attachReplay(chart);
+replay.start();               // head at ~70% of the data (or pass a time/index)
+replay.play();                // 4 bars/sec — play(15) for faster, pause() stops
+replay.step();                // reveal one bar
+replay.seek('2026-03-06');    // jump the head
+replay.setLoop(true);         // wrap to the anchor at the end
+replay.stop();                // exit — the full dataset is restored
+chart.addEventListener('wick:replay', (e) => progress.textContent =
+  e.detail.active ? `${e.detail.index + 1}/${e.detail.total}` : '');
+```
+
+Anchors accept bar indices, timestamps (ms/s) or date strings; every change
+fires `wick:replay` with the full state. Pause live feeds while replaying —
+an external `update()`/`setData()` aborts replay instead of corrupting the
+chart (the demo pauses its feed automatically). Paper trading and an equity
+curve are the planned 0.2 follow-up. Peer dependency: wickchart ≥ 1.4.
+
+### Compare — the `wickchart-compare` plugin
+
+Normalized multi-asset overlays as opt-in bytes (~4 KB gz, own CI budget):
+percent-rebased compare lines (ETH against BTC, TradingView-style) plus
+derived **ratio** and **diff** lines (`BTC/ETH`, `BTC−ETH`), drawn over the
+main pane against their own invisible scale so the price axis is untouched.
+A legend chip row shows each series with its live value.
+
+```js
+npm install wickchart wickchart-compare   // compare is a separate opt-in package
+
+import { attachCompare } from 'wickchart-compare';
+
+const cmp = attachCompare(chart);
+cmp.setSeries([
+  { label: 'ETH', data: ethBars },                            // OHLC or {time, value}
+  { label: 'BTC/ETH', op: 'ratio', a: btcBars, b: ethBars },  // derived
+]);
+cmp.setRebase('visible');   // 0% at the window edge, re-normalized while
+                            // panning; 'first' or an epoch anchor also work
+cmp.clear(); cmp.detach();
+```
+
+Series are sampled onto the main chart's bar times, so timeframes can mix
+and gaps break the line instead of bridging. Rebased values share one
+invisible scale inset 8% from the pane edges; the price scale is never
+distorted. Validated, capped at 6 series, invalid entries dropped. Peer
+dependency: wickchart ≥ 1.4.
+
+### Navigator — the `wickchart-navigator` plugin
+
+The most-missed TradingView affordance: a silhouette of the whole dataset
+docked below the chart with a draggable viewport window (~3 KB gz, own CI
+budget). Drag the window to pan, grab an edge to resize, click outside it to
+jump — pan/zoom and the window stay in sync live, both directions.
+
+```js
+npm install wickchart wickchart-navigator   // navigator is a separate opt-in package
+
+import { attachNavigator } from 'wickchart-navigator';
+const nav = attachNavigator(chart, { height: 46 }); // strip height, 24..120
+nav.detach();                                       // remove the strip again
+```
+
+The strip needs bottom space, so this plugin pairs with a small core hook:
+a layer may declare `insetBottom` (px) — the largest declared inset reserves
+a docked strip at the bottom of the canvas, panes and the time axis shrink
+above it, and layers draw it as `api.layout.dock`. On charts without the
+hook the navigator degrades silently. The silhouette is O(n) once per
+(dataset, width) and cached. Peer dependency: wickchart ≥ 1.6.
+
+### Alerts+ — the `wickchart-alerts-plus` plugin
+
+The "pro" alert tier (~3 KB gz, own CI budget). Core alerts are runtime-only
+by design; this adds what a trading tool actually needs, without the core
+growing any of it: **persistence** (the alert list mirrors into
+localStorage and re-arms on reload), **desktop notifications + a WebAudio
+beep** while the tab is hidden, and an optional **webhook** that receives
+every fire as `POST { id, price, when, time, bar, key }`.
+
+```js
+npm install wickchart wickchart-alerts-plus   // alerts-plus is a separate opt-in package
+
+import { attachAlertsPlus } from 'wickchart-alerts-plus';
+const ap = attachAlertsPlus(chart, {
+  key: 'BTC:1h',                       // one storage key per symbol+timeframe
+  notify: true, sound: true,           // hidden-tab surfacing
+  webhook: 'https://example.com/hook', // optional
+});
+await ap.requestNotify();              // ask for the notification permission
+ap.add({ price: 100, direction: 'above' });  // persisted, re-armed on reload
+ap.add({ when: 'rsi(close,14) < 30' });      // scripted alerts persist too
+ap.list(); ap.remove(id); ap.clear(); ap.sync(); ap.detach();
+```
+
+Once-fired alerts drop out of storage automatically; alerts added directly
+on the chart are captured at the next save point; storage/fetch are
+injectable and every storage failure degrades to memory-only, never
+throwing. Peer dependency: wickchart ≥ 1.4.
+
+### Layouts — the `wickchart-layouts` plugin
+
+Named workspace persistence (~3 KB gz, own CI budget): save and restore
+whole chart setups by name — type, theme, log scale, toggles, indicators,
+view range, positions, alerts — plus the drawing list when wickchart-draw
+is attached. Everything rides the core's public `getState()`/`setState()`.
+
+```js
+npm install wickchart wickchart-layouts   // layouts is a separate opt-in package
+
+import { attachLayouts } from 'wickchart-layouts';
+const layouts = attachLayouts(chart, {
+  key: 'my-desk',      // storage key (default 'wickchart-layouts')
+  drawings: draw,      // optional wickchart-draw handle — include drawings
+});
+layouts.save('swing');    // capture the current setup under a name
+layouts.load('swing');    // apply it back
+layouts.list();           // → [{ name, at, drawingCount }] newest first
+layouts.export();         // → JSON string — share it, store it anywhere
+layouts.import(json);     // merge layouts back (replaces same names)
+chart.addEventListener('wick:layouts', (e) => console.log(e.detail.action, e.detail.name));
+```
+
+Entries are capped (oldest evicted), `storage` is injectable, storage
+failures degrade to an in-memory store for the session and never throw.
+Pair a `load` with `wickchart-alerts-plus`'s `sync()` if you also persist
+alerts, since a layout load replaces the chart's alert list. Peer
+dependency: wickchart ≥ 1.4.
+
+### Signals — the `wickchart-signals` plugin
+
+Candlestick pattern badges (~4 KB gz, own CI budget): bullish/bearish
+**engulfing**, **pin bars** (hammer / shooting star) and **inside bars**
+drawn as direction-colored letter chips above/below the bar. Hover a badged
+bar and the plugin draws the explanation ("Bullish engulfing") and fires
+`wick:signals` — the same passive crosshair bridge as wickchart-sessions,
+so badges never claim a pointer gesture.
+
+```js
+npm install wickchart wickchart-signals   // signals is a separate opt-in package
+
+import { attachSignals } from 'wickchart-signals';
+const signals = attachSignals(chart);
+signals.setKinds(['engulfing', 'pinbar']); // subset (default: all three)
+signals.setLabels(false);                  // hover explanations off
+chart.addEventListener('wick:signals', (e) => status.textContent = e.detail?.label || '');
+```
+
+Detection is O(n), cached per dataset and kind subset — pan/zoom are pure
+repaints. Peer dependency: wickchart ≥ 1.4.
+
 ## Methods
 
 | Method                          | Description                                      |
@@ -721,7 +908,7 @@ section — it shares a room, so open it twice and draw on either chart).
 | `getDataWindow()`               | → AI-ready summary of the visible window (see below) |
 | `getState()`                    | → serializable snapshot (type, indicators, view, positions, alerts) |
 | `setState(state)`               | Apply a snapshot; a pending view applies after the next `setData()` |
-| `addLayer(layer)` / `removeLayer(idOrHandle)` | Register/detach a plugin layer (draw hook + optional pointer claim) |
+| `addLayer(layer)` / `removeLayer(idOrHandle)` | Register/detach a plugin layer (draw hook + optional pointer claim + optional `insetBottom` dock strip) |
 | `requestDraw()`                 | Repaint on the next frame (interactive layers)     |
 | `timeToX(t)` / `xToTime(x)`     | Bar time ⇄ x-pixel; extrapolates into future space |
 | `priceToY(p)` / `yToPrice(y)`   | Price ⇄ y-pixel in the main pane (log-aware)       |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wickchart",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "<wick-chart> — a modern, dependency-free financial charting web component. Candles, line & area charts, crosshair, zoom/pan, indicators (incl. a safe expression mini-language), live streaming via <wick-feed>, theming.",
   "type": "module",
   "main": "src/wick-chart.js",
@@ -42,10 +42,10 @@
   },
   "scripts": {
     "dev": "npx --yes serve . -l 5173",
-    "test": "node --test \"tests/*.test.mjs\" \"plugins/draw/tests/*.test.mjs\"",
+    "test": "node --test \"tests/*.test.mjs\" \"plugins/draw/tests/*.test.mjs\" \"plugins/sessions/tests/*.test.mjs\" \"plugins/replay/tests/*.test.mjs\" \"plugins/compare/tests/*.test.mjs\" \"plugins/navigator/tests/*.test.mjs\" \"plugins/alerts-plus/tests/*.test.mjs\" \"plugins/layouts/tests/*.test.mjs\" \"plugins/signals/tests/*.test.mjs\"",
     "build:types": "node -e \"require('fs').rmSync('types', { recursive: true, force: true });\" && tsc -p tsconfig.json",
     "prepack": "npm run build:types",
-    "ci": "npm run build:types && npm test && node --check src/wick-chart.js && node --check src/wick-feed.js && node --check src/core.js && node --check src/react.js && node --check src/react-core.js && node --check demo/app.js && node --check plugins/draw/core.mjs && node --check plugins/draw/draw.mjs"
+    "ci": "npm run build:types && npm test && node --check src/wick-chart.js && node --check src/wick-feed.js && node --check src/core.js && node --check src/react.js && node --check src/react-core.js && node --check demo/app.js && node --check plugins/draw/core.mjs && node --check plugins/draw/draw.mjs && node --check plugins/sessions/core.mjs && node --check plugins/sessions/sessions.mjs && node --check plugins/replay/replay.mjs && node --check plugins/compare/core.mjs && node --check plugins/compare/compare.mjs && node --check plugins/navigator/core.mjs && node --check plugins/navigator/navigator.mjs && node --check plugins/alerts-plus/alerts-plus.mjs && node --check plugins/layouts/layouts.mjs && node --check plugins/signals/core.mjs && node --check plugins/signals/signals.mjs"
   },
   "keywords": [
     "chart",

package/src/wick-chart.js

@@ -1598,8 +1598,9 @@ class WickChart extends HTMLElementBase {
         );
       }
       const timeH = 26;
+      const dock = this._dockInset();
       const plotRight = Math.max(30, W - priceW);
-      const plotBottom = H - timeH;
+      const plotBottom = H - timeH - dock;
       const paneList = this._ind.panes;
       const paneArea = paneList.length
         ? Math.min(
@@ -1622,6 +1623,7 @@ class WickChart extends HTMLElementBase {
         plotBottom,
         main: { y0: 0, y1: mainH, h: mainH },
         panes,
+        dock: dock > 0 ? { y0: H - dock, h: dock } : null,
       });
 
       /* background */
@@ -2942,7 +2944,13 @@ class WickChart extends HTMLElementBase {
      * layer then receives that pointer's move/up/cancel events (plus a
      * 'cancel' on Escape) and the chart suppresses its own pan/measure/brush
      * for the duration.
-     * @param {{id?: string, draw: Function, onPointer?: Function}} layer
+     *
+     * A layer may also declare `insetBottom` (px, 0..160): the largest
+     * declared inset reserves a docked strip at the very bottom of the
+     * canvas — all chart content (panes + time axis) shrinks above it and
+     * the strip is handed to layers as `api.layout.dock = { y0, h }`
+     * (used by the wickchart-navigator plugin).
+     * @param {{id?: string, draw: Function, onPointer?: Function, insetBottom?: number}} layer
      * @returns {object|null} the normalized layer handle (with `id`), or null
      *   if the layer was rejected (no draw fn, or 16 layers already added)
      */
@@ -2956,6 +2964,10 @@ class WickChart extends HTMLElementBase {
       const entry = {
         id,
         draw: layer.draw,
+        insetBottom:
+          typeof layer.insetBottom === 'number' && Number.isFinite(layer.insetBottom)
+            ? Math.max(0, Math.min(160, Math.round(layer.insetBottom)))
+            : 0,
         onPointer: typeof layer.onPointer === 'function' ? layer.onPointer : null,
       };
       const at = this._layers.findIndex((l) => l.id === id);
@@ -3007,6 +3019,18 @@ class WickChart extends HTMLElementBase {
       }
     }
 
+    /**
+     * Bottom space reserved by plugin layers: the largest declared
+     * `insetBottom` (px, clamped 0..160 at addLayer time), or 0.
+     */
+    _dockInset() {
+      let dock = 0;
+      for (const l of this._layers) {
+        if (l.insetBottom > dock) dock = l.insetBottom;
+      }
+      return dock;
+    }
+
     /** Ask layers, in order, whether one claims this pointerdown. */
     _layerHit(e, pt) {
       for (const layer of this._layers) {

package/types/wick-chart.d.ts

@@ -46,6 +46,10 @@ declare class WickChart extends HTMLElementBase {
             y1: number;
             h: number;
         }[];
+        dock: {
+            y0: number;
+            h: number;
+        };
     };
     _cache: {
         v: number;
@@ -791,7 +795,13 @@ declare class WickChart extends HTMLElementBase {
      * layer then receives that pointer's move/up/cancel events (plus a
      * 'cancel' on Escape) and the chart suppresses its own pan/measure/brush
      * for the duration.
-     * @param {{id?: string, draw: Function, onPointer?: Function}} layer
+     *
+     * A layer may also declare `insetBottom` (px, 0..160): the largest
+     * declared inset reserves a docked strip at the very bottom of the
+     * canvas — all chart content (panes + time axis) shrinks above it and
+     * the strip is handed to layers as `api.layout.dock = { y0, h }`
+     * (used by the wickchart-navigator plugin).
+     * @param {{id?: string, draw: Function, onPointer?: Function, insetBottom?: number}} layer
      * @returns {object|null} the normalized layer handle (with `id`), or null
      *   if the layer was rejected (no draw fn, or 16 layers already added)
      */
@@ -799,6 +809,7 @@ declare class WickChart extends HTMLElementBase {
         id?: string;
         draw: Function;
         onPointer?: Function;
+        insetBottom?: number;
     }): object | null;
     /**
      * Remove a layer added via addLayer (pass the returned handle or its id).
@@ -810,6 +821,11 @@ declare class WickChart extends HTMLElementBase {
     requestDraw(): void;
     /** Paint every registered layer. Called from _render with live state. */
     _drawLayers(ctx: any, pal: any, ly: any, d: any): void;
+    /**
+     * Bottom space reserved by plugin layers: the largest declared
+     * `insetBottom` (px, clamped 0..160 at addLayer time), or 0.
+     */
+    _dockInset(): number;
     /** Ask layers, in order, whether one claims this pointerdown. */
     _layerHit(e: any, pt: any): any;
     /** Deliver a pointer event to a claiming layer; never throws outward. */