wickchart 1.4.0 → 1.6.0

package/README.md

@@ -6,6 +6,9 @@ A TradingView-style financial chart as a single framework-agnostic Web Component
 One file, zero dependencies, one HTML tag. Canvas-rendered, fast, themeable, and
 streaming-ready.
 
+<img width="759" height="390" alt="image" src="https://github.com/user-attachments/assets/f335cecc-d5b3-4d27-a982-600b6bc72d6f" />
+
+
 ## Install
 
 ```bash
@@ -226,7 +229,7 @@ chart.setData([
 | ------------- | ---------- | ------------------------------------------------------------------ |
 | `theme`       | `dark`     | `dark` or `light`                                                   |
 | `type`        | `candles`  | `candles`, `line`, `area`, `bars` (OHLC), `hollow` (hollow up-candles), `heikin` (Heikin-Ashi) |
-| `indicators`  | `volume`*  | Space/comma-separated: `sma:20`, `ema:50`, `bb:20`, `rsi:14`, `macd:12/26/9`, `volume`, or any registered indicator |
+| `indicators`  | `volume`*  | Space/comma-separated: `sma:20`, `ema:50`, `bb:20`, `vwap`, `supertrend:10/3`, `donchian:20`, `keltner:20/2`, `rsi:14`, `macd:12/26/9`, `stoch:14/3`, `atr:14`, `obv`, `cci:20`, `wr:14`, `volume`, or any registered indicator |
 | `label`       | –          | Text shown in the legend (e.g. `"BTC · 1h"`)                        |
 | `log`         | off        | Logarithmic price scale                                             |
 | `auto`        | on         | Keep the right edge pinned to the latest bar while streaming        |
@@ -247,8 +250,17 @@ chart.setData([
 | `sma` | overlay | `period` (20) | |
 | `ema` | overlay | `period` (50) | |
 | `bb` | overlay | `period`, `mult` (20, 2) | Bollinger bands (3 lines) |
+| `vwap` | overlay | – | hlc3 VWAP, resets each UTC day |
+| `supertrend` | overlay | `period`, `mult` (10, 3) | ATR trend line, breaks at flips |
+| `donchian` | overlay | `period` (20) | high/low channel + mid |
+| `keltner` | overlay | `period`, `mult` (20, 2) | EMA ± mult×ATR channel |
 | `rsi` | pane | `period` (14) | fixed 0–100 scale, 30/70 guides |
 | `macd` | pane | `fast/slow/signal` (12/26/9) | 2 lines + histogram |
+| `stoch` | pane | `period`, `smooth` (14, 3) | %K + %D, fixed 0–100, 20/80 guides |
+| `atr` | pane | `period` (14) | Wilder ATR |
+| `obv` | pane | – | on-balance volume |
+| `cci` | pane | `period` (20) | ±100 guides |
+| `wr` | pane | `period` (14) | Williams %R, fixed −100–0, −80/−20 guides |
 | `volume` | overlay | – | histogram at the bottom of the price pane |
 
 ### Custom indicators
@@ -257,9 +269,9 @@ Register your own — anything from a one-liner moving average to a multi-line
 pane:
 
 ```js
-WickChart.registerIndicator('vwap', {
+WickChart.registerIndicator('cvwap', {   // cumulative VWAP over the whole dataset
   kind: 'overlay',               // or 'pane'
-  params: { period: 20 },        // defaults; set via indicators="vwap:30"
+  params: { period: 20 },        // defaults; set via indicators="cvwap:30"
   compute(bars, params) {        // bars: normalized {time,open,high,low,close,volume}
     const out = new Array(bars.length).fill(null);
     let pv = 0, vv = 0;
@@ -270,9 +282,9 @@ WickChart.registerIndicator('vwap', {
     }
     return out;                  // single series — or { lines:[{name,values}], histogram }
   },
-  // pane-only extras: guides:[30,70], range:[0,100], fmt:'price'|'fixed1'
+  // pane-only extras: guides:[30,70], range:[0,100], fmt:'price'|'fixed1'|'compact'
 });
-chart.indicators = 'vwap:20';
+chart.indicators = 'cvwap';
 ```
 
 `import WickChart from 'wickchart'` gives you the class for
@@ -306,6 +318,7 @@ shareable URLs.
 | `prev(x[,k])` `change(x)` | shifted series / bar-to-bar delta |
 | `abs(x)` `sqrt(x)` `log(x)` `min(a,b)` `max(a,b)` | element-wise math |
 | `crossup(a,b)` `crossdown(a,b)` | 1 on a strict cross, else 0 |
+| `vwap()` `obv()` `atr(n)` | bar-level series — callable anywhere, e.g. `crossup(close, vwap())` in alerts |
 
 Operators are `+ - * / %` with usual precedence, unary `-`, and parentheses.
 Values before a window fills are `NaN` (not drawn), division by zero yields
@@ -661,7 +674,7 @@ chart.removeLayer('flags'); // detach by handle or id
 A claimed gesture delivers `move`/`up` (and `cancel` on Escape) to the layer
 while the chart suppresses pan/brush/measure. Markers, watermarks, signal
 badges — or a whole drawing toolkit — plug in without the core growing a
-single tool. The main entry is covered by a CI gzip budget (64 KB) so it
+single tool. The main entry is covered by a CI gzip budget (68 KB) so it
 stays that way.
 
 ### Drawings — the `wickchart-draw` plugin
@@ -673,19 +686,213 @@ data that rides zoom & pan, survives reloads, extrapolates into future
 space, and serializes to JSON. Anchors magnet-snap to bar times and OHLC.
 
 ```js
+npm install wickchart wickchart-draw   // drawings are a separate opt-in package
+
 import { attachDrawings } from 'wickchart-draw';
 
 const draw = attachDrawings(chart);
 draw.setTool('trendline'); // drag to draw; setTool(null) = select/move mode
 draw.getDrawings();        // → JSON array (save it); setDrawings(saved)
 draw.undo(); draw.clear();
+draw.setShare(true);       // shared drawings: draw on one tab, appears on all
 chart.addEventListener('wick:drawings', (e) => save(e.detail.drawings));
 ```
 
 Select mode: click a drawing to select it, drag to move, drag the square
 handles to re-anchor, `Delete` removes, `Esc` cancels a gesture; clicks on
-empty space fall through to the chart. Peer dependency: wickchart ≥ 1.4.
-See the live playground in the docs (Drawings section).
+empty space fall through to the chart. Placing a note opens an inline editor
+(type + `Enter`); click a selected note again to re-edit. `setShare(true)`
+reuses the chart's `co-view` room (or pass an explicit room name) — last
+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
 
@@ -701,7 +908,7 @@ See the live playground in the docs (Drawings section).
 | `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.4.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",
@@ -57,7 +57,14 @@
     "custom-element",
     "canvas",
     "zero-dependency",
-    "tradingview"
+    "tradingview",
+    "vwap",
+    "supertrend",
+    "bollinger-bands",
+    "macd",
+    "rsi",
+    "stochastic",
+    "technical-analysis"
   ],
   "license": "MIT",
   "repository": {