wickchart 1.0.0 → 1.3.0

package/README.md

@@ -17,6 +17,7 @@ npm install wickchart
 import 'wickchart';                       // registers <wick-chart>
 import WickChart from 'wickchart';         // for WickChart.registerIndicator(...)
 import { encodeStateQuery } from 'wickchart/core';  // pure helpers
+import { WickChart } from 'wickchart/react';        // React bindings (optional)
 ```
 
 Or straight from a CDN — no install, no build:
@@ -86,7 +87,14 @@ bet:
 
 The demo site is deployed to GitHub Pages:
 **https://benyblack.github.io/wickchart/** — a landing page with a live hero
-chart, the full interactive demo, and the zero-JavaScript declarative page.
+chart, the full interactive demo, the zero-JavaScript declarative page, and a
+[React demo](./demo/react.html) driven entirely by React state.
+
+**Full documentation lives at
+[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.
 
 ## Run the demo locally
 
@@ -105,6 +113,101 @@ with graceful fallback to synthetic data if it isn't.
 
 ---
 
+## Frameworks
+
+`<wick-chart>` is framework-agnostic — attributes, one `data` property,
+standard DOM events. The one opinionated wrapper ships as `wickchart/react`,
+which turns that contract into idiomatic React with proper event
+subscription/cleanup. `react` is an **optional** peer dependency: nothing
+changes if you never import `wickchart/react`.
+
+### React
+
+```bash
+npm install wickchart react
+```
+
+```jsx
+import { WickChart, useWickChart } from 'wickchart/react';
+
+// drop-in component — props map 1:1 onto the element
+export function PriceChart({ bars, onRange }) {
+  return (
+    <WickChart
+      type="candles"
+      indicators="sma:20 ema:50 volume"
+      volshading
+      label="BTC · 1h"
+      data={bars}                 // bars are assigned as a property
+      onRange={onRange}           // subscribes to wick:range
+      onAlert={(e) => toast(`crossed ${e.detail.price}`)}
+      style={{ height: 420 }}
+    />
+  );
+}
+
+// or the hook, when you need the imperative API
+function PracticeChart({ bars }) {
+  const { ref, chart } = useWickChart({ data: bars, indicators: 'sma:20' });
+  // chart.getDataWindow(), chart.addAlert(...), chart.getState() … after mount
+  return <wick-chart ref={ref} style={{ height: 420 }} />;
+}
+```
+
+Rules of thumb:
+
+- **Pass a fresh array** to `data` when the bars change — the binding compares
+  by reference, and reassignment is what triggers a redraw (don't mutate).
+  The same rule applies to `overlays` (see
+  [Server-side overlays](#server-side-overlays-zones--levels)).
+- **String/number/boolean props become attributes** (`type`, `indicators`,
+  `volshading`, …); `className`/`style`/`id` reach React as usual.
+- **`onXxx` subscribes to `wick:xxx`** with cleanup on unmount; an
+  `events={{ range: fn }}` object works too.
+- Works the same on React 16.8 → 19 — no custom-element event caveats.
+
+No build step? The [React demo](./demo/react.html) runs straight off a CDN
+import map — `react` and `react-dom` from esm.sh, the bindings from the
+package source.
+
+### Vue 3
+
+```vue
+<script setup>
+import { ref, onMounted } from 'vue';
+import 'wickchart';
+const chart = ref(null);
+const bars = ref([]);
+onMounted(async () => {
+  bars.value = await loadBars();
+  chart.value.data = bars.value;
+  chart.value.addEventListener('wick:range', (e) => console.log(e.detail));
+});
+</script>
+
+<template>
+  <wick-chart ref="chart" type="candles" indicators="sma:20"
+              style="height: 420px"></wick-chart>
+</template>
+```
+
+### Svelte
+
+```svelte
+<script>
+  import 'wickchart';
+  let el;
+  let bars = [];
+  $: if (el && bars.length) el.data = bars;
+</script>
+
+<wick-chart bind:this={el} type="candles" indicators="sma:20"
+            on:wick:alert={(e) => console.log(e.detail)}
+            style="height: 420px"></wick-chart>
+```
+
+---
+
 ## Data format
 
 Bars are plain objects; `time` accepts **milliseconds or seconds** (auto-detected).
@@ -132,6 +235,7 @@ chart.setData([
 | `profile`     | off        | Volume profile overlay (POC + 70% value area)       |
 | `annotations` | off        | Smart annotations (volume spikes, gaps, pivots, RSI divergences) |
 | `volshading`  | off        | Volatility-regime background shading (see below)    |
+| `overlays`    | –          | JSON array of server-side zones & levels (see below) |
 
 \* `indicators=""` disables everything, including volume. Token syntax:
 `name[:param[/param…]][@color]` — e.g. `sma:20@#ff0000`, `macd:12/26/9`.
@@ -249,6 +353,151 @@ classifies everything as normal. The pieces are exported from
 `wickchart/core` (`calcRealizedVol`, `volRegimeBands`, `percentileOfSorted`)
 if you want to build on them.
 
+### Server-side overlays (zones & levels)
+
+Draw analysis from your own API straight onto the chart: supply/demand
+**zones** (time × price rectangles) and horizontal **levels**, rendered
+behind the candles. Zones without a `to` extend into future space past the
+last bar, like TradingView drawings.
+
+```js
+const res = await fetch('https://api.example.com/analysis?symbol=BTC');
+chart.setOverlays(await res.json());
+```
+
+```js
+[
+  // zone: from/to are timestamps (ms or s); null → chart edge
+  { type: 'zone', from: 1753920000000, priceFrom: 33000, priceTo: 35600,
+    color: '#ef5350', alpha: 0.25, label: 'demand' },
+  { type: 'zone', from: 1753920000000,                    // no `to` → extends
+    priceFrom: 37700, priceTo: 40900, color: '#26a69a' }, // to the right edge
+  // level: horizontal price line, full width by default
+  { type: 'level', price: 28700, color: '#3f51b5', label: 'S1' },
+  { type: 'level', price: 22800, color: '#3f51b5', dash: true },
+]
+```
+
+- `addOverlay(o)` upserts one (by `id`), `removeOverlay(id)`,
+  `clearOverlays()`, and `chart.overlays` reads them back.
+- Colors accept hex / `rgb()` / CSS names plus the palette keys
+  `up` | `down` | `accent`; `alpha` clamps to 0.02–0.8 (default 0.22).
+- Timestamps snap to bars (before the first bar clamps left, after the last
+  clamps right); invalid entries are dropped, never thrown — it's API data.
+- Fully declarative, too — the same JSON as an attribute:
+
+```html
+<wick-chart overlays='[{"type":"level","price":28700,"color":"#3f51b5","label":"S1"}]'></wick-chart>
+```
+
+The React binding takes `overlays` as a prop (fresh array → re-apply), and
+`normalizeOverlays` / `barIndexForTime` / `resolveOverlayColor` are exported
+from `wickchart/core`.
+
+### Scenario mode — ghost paths & volatility cones
+
+Project what-if into future space: a ghost path of hypothetical prices plus
+a volatility cone (±1σ/±2σ bands widening with √h from realized vol).
+
+```js
+chart.setScenario({
+  path: [64000, 65500, 66800, 68000], // prices for future bars 1..N
+  cone: true,                         // σ-bands from realized vol (default)
+  label: 'bull case',
+  color: 'up',                        // up | down | accent or safe colors
+});
+chart.setScenario({ horizon: 48 });   // cone-only projection
+chart.clearScenario();
+```
+
+Setting a scenario reserves future space on the right so the cone stays
+visible; the horizon defaults to the path length (1–500) and `levels` are σ
+multipliers (default `[1, 2]`). Like overlays, scenarios are analysis data —
+excluded from shareable state, and the same shape a server-side model could
+push. `calcVolCone` / `normalizeScenario` are exported from `wickchart/core`.
+
+### Risk planner — R-multiple grid
+
+Plan the trade on the chart: entry + stop define **1R** (the risk unit) and
+reward lines are drawn at kR beyond the entry, with the risk/reward zones
+shaded. Direction is derived from the stop side.
+
+```js
+chart.setRiskPlan({ entry: 64500, stop: 63800, multiples: [1, 2, 3] });
+chart.setRiskPlan({ entry: 64500, stop: 63800, targets: [65900, 67300] }); // prices → kR
+chart.clearRiskPlan();
+chart.riskPlan; // { entry, stop, risk, direction, levels: [{ k, price }], maxK, label }
+```
+
+Explicit `targets` convert to their R multiple (wrong-side prices drop);
+`multiples` win when both are given. At most 8 levels, each ≤ 20R; invalid
+specs clear the plan, never throw. `normalizeRiskPlan` is exported from
+`wickchart/core`.
+
+### Bar-walk narrator — history as a story
+
+`narrate()` builds the timeline of a window (pivot highs/lows, volume
+spikes, gaps, RSI divergences, plus derived legs — the move between
+opposite pivots); `walk()` replays the chart through it while `wick:walk`
+events announce each step, so a caption bar can narrate the replay.
+
+```js
+chart.narrate();                 // [{ i, time, type, note, legPct?, legBars? }]
+chart.walk({ from: 0, to: 500, speed: 120, step: 10 });
+chart.addEventListener('wick:walk', (e) => {
+  // { phase: 'step' | 'end' | 'stop', index, events: [...], from, to }
+});
+chart.stopWalk();                // any pointer/wheel/key input stops it too
+```
+
+`narrateWindow` (the analyzer) is exported from `wickchart/core`.
+
+### Delta brush — drag-select with stats
+
+`<wick-chart brush>` makes a plain drag **select bars** instead of panning:
+a live band follows the pointer with a delta chip (Δ% · bars · high · low ·
+Σvol); on release the selection commits and fires `wick:brush` with the
+range statistics. Esc (or `clearBrush()`) clears it.
+
+```html
+<wick-chart brush></wick-chart>
+```
+
+```js
+chart.addEventListener('wick:brush', (e) => {
+  // { bars, from: {index, time}, to: {index, time}, delta, deltaPct,
+  //   firstOpen, lastClose, high, low, volume }
+});
+chart.brushSelection; // { i0, i1, stats } | null
+chart.clearBrush();
+```
+
+Brush mode replaces plain-drag panning (shift-drag still measures);
+replacing the dataset clears a committed selection. `brushStats` is
+exported from `wickchart/core`.
+
+### Story mode — guided tours of chart state
+
+A **story** is an array of **scenes** (view range, type, indicators,
+overlays, scenario, risk plan + title/note). `playStory()` applies each
+scene, eases the camera to its range, holds for `dwell`, and narrates
+through `wick:story`. Record scenes with `captureScene()` while you
+arrange the chart, or generate them from an analysis.
+
+```js
+const story = [chart.captureScene('Overview', 'the full picture')];
+story.push({ title: 'The breakout', range: { from, to }, indicators: 'sma:20' });
+chart.playStory(story, { dwell: 2200, panMs: 900, loop: false });
+chart.addEventListener('wick:story', (e) => {
+  // { phase: 'scene' | 'end' | 'stop', index, total, scene, title, note }
+});
+chart.stopStory(); chart.getStory();
+```
+
+Any user interaction stops the tour. Scenes are plain data — serialize
+or share them. `normalizeScene` / `sceneList` / `easeInOutCubic` are
+exported from `wickchart/core`.
+
 ### AI-ready data window — `getDataWindow()`
 
 One call turns whatever is on screen into a compact, LLM-pasteable summary.
@@ -266,6 +515,31 @@ s.volPctile; // 84 → hot regime relative to the window itself
 s.patterns;  // [{ time, note }] — most recent first
 ```
 
+### AI agent interface — the chart as a tool surface
+
+The chart can publish its own **tool manifest** and accept validated
+tool-calls, so any LLM can operate it with zero glue code — the chart never
+touches the network; you supply the model call.
+
+```js
+chart.aiTools();    // manifest: get_data_window, set_indicators, set_overlays, add_alert, …
+chart.aiPrompt();   // system prompt demanding JSON [{tool, args}] ops
+chart.aiContext();  // grounding: current state + visible-window summary
+chart.applyAI(ops); // validated dispatcher — per-op {ok, result} / {ok:false, error}
+
+const { results } = await chart.ask(
+  'add RSI, mark the demand zone, and alert me on volume spikes',
+  { run: async (payload) => (await callMyLLM(payload)).ops }
+);
+```
+
+Every op is whitelisted and its args validated (indicator names checked
+against the registry, overlays through the sanitizer, enums enforced) — LLM
+output is treated as untrusted input, and a bad op returns an error the
+model can self-correct from instead of throwing. The
+[docs page](./docs.html) has a live playground driving `applyAI()` with an
+offline demo agent (no network, no keys).
+
 `text` renders like:
 
 ```
@@ -291,13 +565,13 @@ range as a ~4-second pitch sequence, riding the crosshair along for sighted
 users. Audio starts lazily within the enabling user gesture (autoplay-policy
 safe).
 
-### Cross-tab co-view
+### Cross-tab co-view & presence
 
 Tag charts with the same channel and they share pointers — across browser
 tabs, or between multiple charts on one page:
 
 ```html
-<wick-chart co-view="btc-room"></wick-chart>
+<wick-chart co-view="btc-room" co-view-name="ben"></wick-chart>
 ```
 
 Hovering in one tab draws a ghost crosshair (accent, dotted, with the time
@@ -306,6 +580,20 @@ different history depths still line up. Ghosts fade ~2.5 s after the peer
 stops moving. Same-origin only (BroadcastChannel); the connection follows the
 `co-view` attribute and closes with the element.
 
+Peers also see **where everyone is looking**: each peer's viewport renders
+as a colored band (with name) along the top of the plot, updated live as
+they pan or zoom and swept away ~12 s after they go quiet.
+
+```js
+chart.getPeers(); // [{ id, name, range: { from, to }, at }]
+chart.addEventListener('wick:peers', (e) => {
+  // { peers, joined, left } — membership changes only
+});
+```
+
+`PresenceTracker` (the TTL bookkeeping) is exported from `wickchart/core`
+for apps that sync presence over their own transport instead.
+
 ### Smart annotations
 
 `<wick-chart annotations>` marks notable events on the visible range — volume
@@ -390,10 +678,17 @@ chart.addAlert({ price: 65000, direction: 'above' }); // 'above' | 'below' | 'cr
 chart.addEventListener('wick:alert', (e) => {
   console.log('crossed!', e.detail.id, e.detail.price);
 });
+
+// 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
 ```
 
 The P&L chip recalculates on every streamed bar. Alerts are edge-triggered
 (fire once per crossing) and one-shot by default (`once: false` to re-arm).
+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.
 
 ### Stats & measure
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wickchart",
-  "version": "1.0.0",
+  "version": "1.3.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",
@@ -18,6 +18,10 @@
     "./feed": {
       "types": "./types/wick-feed.d.ts",
       "default": "./src/wick-feed.js"
+    },
+    "./react": {
+      "types": "./types/react.d.ts",
+      "default": "./src/react.js"
     }
   },
   "files": [
@@ -25,14 +29,23 @@
     "types"
   ],
   "sideEffects": [
-    "src/wick-chart.js"
+    "src/wick-chart.js",
+    "src/react.js"
   ],
+  "peerDependencies": {
+    "react": ">=16.8"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
   "scripts": {
     "dev": "npx --yes serve . -l 5173",
     "test": "node --test \"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 demo/app.js"
+    "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"
   },
   "keywords": [
     "chart",
@@ -52,6 +65,10 @@
     "url": "git+https://github.com/benyblack/wickchart.git"
   },
   "devDependencies": {
+    "@types/react": "^19.1.0",
+    "jsdom": "^26.1.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
     "typescript": "^7.0.2"
   }
 }