wickchart 1.6.0 → 2.0.0

package/README.md

@@ -1,5 +1,7 @@
 # WickChart
 
+[![npm](https://img.shields.io/npm/v/wickchart)](https://www.npmjs.com/package/wickchart)
+
 **`<wick-chart>` — a modern, simpler, more useful charting web component.**
 
 A TradingView-style financial chart as a single framework-agnostic Web Component.
@@ -62,6 +64,7 @@ with **zero JavaScript written**:
 | `tf`        | timeframe: `1m 3m 5m 15m 30m 1h 2h 4h 6h 12h 1d 3d 1w`                  |
 | `limit`     | initial bars (default 500)                                               |
 | `live`      | `live="false"` loads history without streaming                           |
+| `aggregate` | information-based bars from a trade stream (see below)                   |
 
 The element reflects its state in the `status` attribute (`loading`, `live`,
 `polling`, `fallback`, `loaded`, `waiting`, `idle`) and emits
@@ -70,6 +73,78 @@ The element reflects its state in the `status` attribute (`loading`, `live`,
 synthetic stream bridged from the last real price, so the chart never goes
 blank. It also wires `chart.onloadmore` for infinite backfill automatically.
 
+### Information-based bars (advanced bars)
+
+Add `aggregate` to any feed and bars close on *information*, not the clock:
+
+```html
+<wick-feed for="c" binance="BTCUSDT" aggregate="dollar:50000"></wick-feed>
+<wick-chart id="c" indicators="volume"></wick-chart>
+```
+
+`tick:200` closes a bar every 200 prints, `volume:50` every 50 base units,
+`dollar:50000` every $50k traded — the quant-grade alternative to time
+candles, built client-side from the raw trade tape (Binance aggTrade
+WebSocket + paginated REST backfill; offline synthetic prints with `demo=`;
+your own JSON trades endpoint with `url=` + `poll=`). The value you pass *is*
+the bar size — tune it per instrument. The machinery is exported too:
+`import { TickBarAggregator, aggregateTrades } from 'wickchart/feed'` to pipe
+any trade stream through the same aggregator.
+
+## Web Worker compute path (1M-bar histories)
+
+One extra import, one attribute — and the built-in indicators compute in a
+Web Worker, built for million-bar histories:
+
+```js
+import 'wickchart/worker';   // once — wires a shared worker pool into the chart
+
+<wick-chart worker indicators="sma:20 bb:20 rsi:14"></wick-chart>
+```
+
+The dataset crosses once per bulk load as six transferable `Float64Array`s
+(~25 ms per million bars; a structured clone of bar objects would cost ~1 s),
+and indicator tasks reference it worker-side. First paint of every indicator
+line happens off the main thread; `wick:worker` fires as results land.
+Engages at 50k+ bars with built-in indicators (custom/scripted defs are
+closures and stay sync, as does everything below the threshold); results are
+cached per data epoch, so streamed ticks stop recomputing the full series per
+bar. No worker available? Everything silently stays synchronous — the
+attribute is an optimization, never a dependency. Live demo with freeze
+numbers: **[demo/worker.html](./demo/worker.html)**.
+
+**Incremental tick updates** (automatic, worker or not): a streamed tick —
+appending a bar or replacing the forming one — patches every online-capable
+series by recomputing a bounded tail with the *same* batch definition
+(O(warm-up) ≈ 0.1 ms, not O(full history)) and only writing the last
+`period` values, so history is never degraded by tail warm-up error. This
+works on worker-computed bases too: the forming bar's indicator value stays
+fresh instead of waiting for the next bulk load. Cumulative indicators
+(`obv`, `vwap`) and the stateful `supertrend` are excluded and keep the
+full-recompute behavior.
+
+## Report export (branded snapshots)
+
+One shareable PNG — chart, visible-range stats, watermark — composed from
+public surfaces only, as an opt-in entry:
+
+```js
+import { exportReport, downloadReport } from 'wickchart/report';
+
+const url = await exportReport(chart);   // PNG data URL
+const blob = await exportReport(chart, { as: 'blob' });
+await downloadReport(chart, 'btc-1h.png', { source: 'binance: BTCUSDT' });
+```
+
+The header carries the title (the chart's `label` by default), the visible
+range and the brand; the chart keeps its full DPR resolution with a corner
+watermark; the stats grid covers the visible window (return, annualized
+vol, max drawdown, bars, up/down, average volume, high, low); the footer
+credits your `source` and a timestamp. Theme follows the chart's own
+`--wick-*` CSS variables (or `theme: 'dark' | 'light'`), scale 1–4.
+`reportModel(chart, opts)` is exported too — plain data, if you want your
+own layout.
+
 ---
 
 ## Why another chart library?
@@ -78,7 +153,8 @@ TradingView's charting library is powerful but heavy and enterprise-licensed;
 most wrappers add build steps and framework lock-in. WickChart takes the opposite
 bet:
 
-- **Zero dependencies, single file** (~40 KB unminified, no build step required)
+- **Zero dependencies, no build step required** (~67 KB gzipped for the whole
+  component — `core.js` + `wick-chart.js`, held to a 68 KB CI budget)
 - **One tag, sane defaults** — drop it in and it renders; everything optional
 - **Built-in usefulness** — crosshair + OHLC legend, last-price line, wheel zoom,
   drag pan, pinch, keyboard navigation, live streaming, PNG export
@@ -97,7 +173,10 @@ chart, the full interactive demo, the zero-JavaScript declarative page, and a
 [benyblack.github.io/wickchart/docs.html](./docs.html)** — every attribute,
 method, event, the WickScript reference, overlays (with a live JSON
 playground), feeds, theming and framework bindings, each with runnable
-examples. This README covers the same ground in plain markdown.
+examples. The **[Plugins hub](./plugins.html)** documents every opt-in
+package — draw, sessions, replay, compare, navigator, alerts+, layouts,
+signals, tape, grid, paper — each with its own live playground. This README covers
+the same ground in plain markdown.
 
 ## Run the demo locally
 
@@ -886,7 +965,7 @@ npm install wickchart wickchart-signals   // signals is a separate opt-in packag
 
 import { attachSignals } from 'wickchart-signals';
 const signals = attachSignals(chart);
-signals.setKinds(['engulfing', 'pinbar']); // subset (default: all three)
+signals.setKinds(['engulfing', 'pinbar']); // subset (default: all three; [] = off)
 signals.setLabels(false);                  // hover explanations off
 chart.addEventListener('wick:signals', (e) => status.textContent = e.detail?.label || '');
 ```
@@ -894,6 +973,30 @@ chart.addEventListener('wick:signals', (e) => status.textContent = e.detail?.lab
 Detection is O(n), cached per dataset and kind subset — pan/zoom are pure
 repaints. Peer dependency: wickchart ≥ 1.4.
 
+### Tape — the `wickchart-tape` plugin
+
+Time & sales (~4.6 KB gz, own CI budget): a live trade-print strip docked at
+the bottom of the canvas through the `insetBottom` hook — `time · price ·
+size` rows colored by side with proportional size bars, oversized prints
+highlighted. Display-only: it never claims a pointer gesture. Prints carry
+an optional side; without one the plugin applies the classic **tick rule**
+(uptick → buy, downtick → sell), carried continuously across pushes. The
+same stream drives the chart: `chart.setData(tape.toBars(60000))`.
+
+```js
+npm install wickchart wickchart-tape   // tape is a separate opt-in package
+
+import { attachTape } from 'wickchart-tape';
+const tape = attachTape(chart, { rows: 7, bigSize: 50 });
+socket.onmessage = (m) => tape.push(m.trades); // single print or batch
+tape.setRows(4); tape.hide(); tape.detach();   // rows 3–8; hide frees the dock
+chart.addEventListener('wick:tape', (e) => status.textContent = e.detail.total + ' prints');
+```
+
+Keeps the newest 500 prints. Peer dependency: wickchart ≥ 1.6 (the dock
+hook); shares the bottom strip with wickchart-navigator, so attach one or
+the other.
+
 ## Methods
 
 | Method                          | Description                                      |
@@ -947,6 +1050,9 @@ chart.addEventListener('wick:alert', (e) => {
 // scripted alerts — any WickScript predicate, fired on its false→true edge
 chart.addAlert({ when: 'crossup(rsi(close,14), 30)' });
 chart.addAlert({ when: 'volume > sma(volume,20) * 3', once: false }); // re-arms
+
+// evaluate only on final candles, so the signal cannot repaint
+chart.addAlert({ when: 'crossup(rsi(close,14), 30)', evaluate: 'close' });
 ```
 
 The P&L chip recalculates on every streamed bar. Alerts are edge-triggered
@@ -955,6 +1061,43 @@ Scripted alerts are evaluated locally on every streamed bar — the event
 carries the triggering close as `price` plus the `when` source; an invalid
 predicate is rejected (`addAlert` returns `null`), never thrown.
 
+**Live vs closed-candle evaluation.** Alerts evaluate on every update by
+default, the still-forming candle included — so a technical signal can
+repaint (RSI crosses 30 mid-candle, price reverses, the candle closes back
+above 30). Pass `evaluate: 'close'` to fire only on final candles, or set
+`<wick-chart alert-evaluate="close">` as the chart-wide default (per-alert
+`evaluate` still wins). A candle is final once a newer bar arrives, or as
+soon as the feed says so via `closed: true` on `update()` — `<wick-feed>`
+forwards Binance's `k.x` flag, so the signal lands at the close rather than
+one candle later. Historical corrections and backfilled candles never fire
+live alerts in either mode.
+
+### Timezone & VWAP sessions
+
+Axis labels and the crosshair readout use the viewer's timezone by default.
+Pin them with `timezone` — `local`, `utc`, or any IANA zone, DST included:
+
+```html
+<wick-chart timezone="Europe/Stockholm"></wick-chart>
+<wick-chart timezone="America/New_York"></wick-chart>
+```
+
+Day dividers and month/year ticks follow the chosen zone, so a "1 Feb" tick
+is 1 February *there*. An unrecognised zone falls back to UTC and warns once.
+
+VWAP's session boundary is deliberately **separate** from the display zone —
+changing the axis to Stockholm shouldn't silently re-anchor a BTC chart. It
+defaults to the UTC day (the crypto convention) and moves only when asked:
+
+```html
+<wick-chart indicators="vwap" vwap-anchor="America/New_York"></wick-chart>
+```
+
+`vwap-anchor` takes `utc` (default), `local`, an IANA zone, or a fixed offset
+in milliseconds. Equities, futures and FX rarely open at UTC midnight, so the
+default is right for crypto and wrong for most other markets — set it
+deliberately. `calcVWAP(bars, anchor)` takes the same values directly.
+
 ### Stats & measure
 
 `<wick-chart stats>` shows live statistics of the visible range — return %,
@@ -1022,7 +1165,9 @@ wick-chart {
 | Trackpad horizontal scroll | Pan                                 |
 | Drag                       | Pan (auto-follow re-arms at the right edge) |
 | Pinch (touch)              | Zoom                                |
-| Double-click               | Reset view                          |
+| Long press (touch)         | Open the crosshair, then drag to scrub across bars |
+| Vertical swipe (touch)     | Scrolls the page, not the chart     |
+| Double-click / double-tap  | Reset view                          |
 | `←` `→` (`+Shift` ×10)     | Move crosshair                      |
 | `+` / `−`                  | Zoom in / out                       |
 | `Home` / `End`             | Jump to oldest / newest             |
@@ -1059,13 +1204,55 @@ column, and an offscreen layer so hover only repaints the crosshair.
 ## Architecture notes
 
 - Single ES module, Custom Element + Shadow DOM, Canvas 2D with
-  devicePixelRatio scaling and rAF-batched invalidation
+  devicePixelRatio scaling and rAF-batched invalidation. The ratio is watched
+  with a `resolution` media query, so moving a window between monitors
+  re-renders at the new resolution rather than staying soft
 - Only visible bars are drawn; indicator series are computed lazily and cached
   per data version (prefix-sum SMA, Wilder RSI)
 - Time axis picks tick steps from bar interval (minutes → months) and labels
   day/month boundaries like a pro terminal
 - No dependencies, no build step required — but it bundles/tree-shakes fine
 
+## Tests
+
+Two suites, and they answer different questions.
+
+```bash
+npm test          # Node: pure functions, indicator maths, parsing, plugins
+npm run test:e2e  # Playwright: the chart in a real browser
+```
+
+`npm test` is the fast one and covers the bulk of the library. What it cannot
+reach is anything that only exists once a browser is involved: custom-element
+upgrade, a real canvas, wheel/pointer/touch input, `devicePixelRatio`,
+`ResizeObserver`, and React re-renders against a live DOM node. Bugs have
+shipped in exactly that gap — a React parent re-render used to silently reset
+the user's zoom, and a chart moved to a monitor with a different pixel ratio
+kept rendering at the old resolution. Both are covered in `e2e/` now.
+
+The browser suite serves the repository over a small dependency-free static
+server (`e2e/server.mjs`) and loads the library from source, so it tests the
+files that ship rather than a build artifact. The React fixture pulls React
+from esm.sh, the same way `demo/react.html` does.
+
+**Running it locally.** `npm run test:e2e` downloads Playwright's bundled
+Chromium the first time. If that CDN is blocked on your machine, point the
+suite at a browser you already have:
+
+```bash
+WICK_E2E_CHANNEL=chrome npm run test:e2e     # or msedge
+```
+
+**Visual regression** is opt-in. Canvas output is not pixel-identical across
+operating systems, so a committed baseline from one machine red-lights
+everyone else; the rest of the suite compares the chart against *itself*
+instead (repaint X, assert only what should have moved did). To gate on real
+screenshots, generate baselines on the platform that will run them:
+
+```bash
+WICK_E2E_VISUAL=1 npm run test:e2e -- --update-snapshots
+```
+
 ## Roadmap ideas
 
 - More overlays (Bollinger, VWAP), MACD pane, drawing tools
@@ -1073,26 +1260,54 @@ column, and an offscreen layer so hover only repaints the crosshair.
 - Incremental (O(1)) indicator updates for high-frequency streaming
 - Min/max downsampling and/or an offscreen hover layer if profiling ever demands
 
-## Migrating from 0.x (HabView)
+## Migrating from 1.x to 2.x
+
+2.0 removes the deprecated 0.x `hab-*` aliases (they warn once per surface
+from **1.7.1**) and moves the six optional feature families out of the core
+entry into their own packages — the core drops back under ~65 KB gz. The
+full plan and delivery sequence: [ROADMAP-V2.md](./ROADMAP-V2.md).
 
-1.0 renames the public surface to the WickChart brand. The 0.x names keep
-working as **deprecated aliases** (removed in 2.0), so upgrading is safe to
-do lazily:
+**Aliases removed.** Renaming is mechanical; each warns in 1.7.1 already:
 
-| 0.x (deprecated alias) | 1.0 canonical |
+| removed in 2.0 | use instead |
 |---|---|
 | `<hab-chart>` / `<hab-feed>` | `<wick-chart>` / `<wick-feed>` |
-| `hab:range`, `hab:select`, `hab:alert`, `hab:crosshair`, `hab:measure`, `hab:annotations` | `wick:*` of the same name (both fire during 1.x) |
-| `hab-feed:status` / `hab-feed:fallback` | `wick-feed:status` / `wick-feed:fallback` (both fire during 1.x) |
-| `--hab-bg`, `--hab-up`, … | `--wick-*` of the same name (`--wick-*` wins; `--hab-*` is the fallback) |
-| `HabChart` / `HabFeed` classes | `WickChart` / `WickFeed` (also as named exports) |
-| HabScript (the `expr:{…}` language) | WickScript — syntax unchanged |
-| `import … from 'wickchart/src/hab-chart.js'` | use the package entry points (`wickchart`, `wickchart/core`, `wickchart/feed`) — module files are renamed |
-
-Two behavioral notes: custom indicators registered via
-`WickChart.registerIndicator()` are shared with the legacy `<hab-chart>`
-alias (one registry), and cross-tab co-view channels are now prefixed
-`wick-co-view:` (a 0.x tab and a 1.x tab won't pair — refresh both).
+| `hab:*` events (every chart event fired twice in 1.x) | `wick:*` of the same name |
+| `hab-feed:*` events | `wick-feed:*` |
+| `--hab-bg`, `--hab-up`, … (runtime **and** stylesheet fallbacks) | `--wick-*` of the same name |
+
+Still on 0.x? Upgrade through 1.x first — the 1.x releases carry the
+aliases with warnings, so the rename can be done lazily there.
+
+**Features moved to packages.** Calls keep their shape: each
+`attachX(chart)` installs the familiar methods *on the instance*, so
+existing call sites survive with one added import line. Without the
+package, the core methods become warn-once stubs naming it:
+
+| 1.x (in core) | 2.0 package |
+|---|---|
+| `narrate()` · `walk()` / `stopWalk()` · `playRange()` · the `sonify` attribute · `captureScene()` / `getStory()` / `playStory()` / `stopStory()` | `wickchart-narrator` |
+| the `co-view` / `co-view-name` attributes · `getPeers()` | `wickchart-coview` |
+| `setScenario()` / `clearScenario()` · `setRiskPlan()` / `clearRiskPlan()` | `wickchart-scenario` |
+| `aiTools()` · `aiPrompt()` · `aiContext()` · `applyAI()` · `ask()` | `wickchart-ai` |
+
+```js
+import { attachNarrator } from 'wickchart-narrator';
+attachNarrator(chart);        // chart.narrate() / walk() / playStory() … work as before
+```
+
+**Unaffected:** `getDataWindow()` stays in core (a data API, not an LLM
+API), `getState()` / `setState()` serialize none of the moved features, and
+all four packages are already published and documented on the
+[plugins hub](https://benyblack.github.io/wickchart/plugins.html) — you can
+adopt them today, on 1.x (attaching simply shadows the core's identical
+methods).
+
+## Releases
+
+Versioned per [semver](./CHANGELOG.md#how-this-project-versions); every
+release is a tagged GitHub Release with the changelog — see
+**[CHANGELOG.md](./CHANGELOG.md)**.
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "wickchart",
-  "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.",
+  "version": "2.0.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> (incl. tick/volume/dollar bars), a worker compute path for 1M-bar histories, report export, theming.",
   "type": "module",
   "main": "src/wick-chart.js",
   "module": "src/wick-chart.js",
@@ -22,6 +22,14 @@
     "./react": {
       "types": "./types/react.d.ts",
       "default": "./src/react.js"
+    },
+    "./worker": {
+      "types": "./types/worker.d.ts",
+      "default": "./src/worker.js"
+    },
+    "./report": {
+      "types": "./types/report.d.ts",
+      "default": "./src/report.js"
     }
   },
   "files": [
@@ -42,10 +50,11 @@
   },
   "scripts": {
     "dev": "npx --yes serve . -l 5173",
-    "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\"",
+    "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\" \"plugins/tape/tests/*.test.mjs\" \"plugins/grid/tests/*.test.mjs\" \"plugins/paper/tests/*.test.mjs\" \"plugins/narrator/tests/*.test.mjs\" \"plugins/coview/tests/*.test.mjs\" \"plugins/scenario/tests/*.test.mjs\" \"plugins/ai/tests/*.test.mjs\"",
+    "test:e2e": "playwright test",
     "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 && 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"
+    "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 src/worker.js && node --check src/worker-core.js && node --check src/report.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 && node --check plugins/tape/core.mjs && node --check plugins/tape/tape.mjs && node --check plugins/grid/core.mjs && node --check plugins/grid/grid.mjs && node --check plugins/paper/core.mjs && node --check plugins/paper/paper.mjs && node --check plugins/narrator/core.mjs && node --check plugins/narrator/narrator.mjs && node --check plugins/coview/core.mjs && node --check plugins/coview/coview.mjs && node --check plugins/scenario/core.mjs && node --check plugins/scenario/scenario.mjs && node --check plugins/ai/core.mjs && node --check plugins/ai/ai.mjs"
   },
   "keywords": [
     "chart",
@@ -56,6 +65,9 @@
     "web-component",
     "custom-element",
     "canvas",
+    "paper-trading",
+    "equity-curve",
+    "web-worker",
     "zero-dependency",
     "tradingview",
     "vwap",
@@ -72,10 +84,12 @@
     "url": "git+https://github.com/benyblack/wickchart.git"
   },
   "devDependencies": {
+    "@playwright/test": "^1.63.0",
     "@types/react": "^19.1.0",
     "jsdom": "^26.1.0",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
-    "typescript": "^7.0.2"
+    "typescript": "^7.0.2",
+    "wickchart": "file:."
   }
 }