wickchart 0.3.0 → 1.0.0

package/README.md

@@ -1,6 +1,6 @@
-# HabView
+# WickChart
 
-**`<hab-chart>` — a modern, simpler, more useful charting web component.**
+**`<wick-chart>` — a modern, simpler, more useful charting web component.**
 
 A TradingView-style financial chart as a single framework-agnostic Web Component.
 One file, zero dependencies, one HTML tag. Canvas-rendered, fast, themeable, and
@@ -14,8 +14,8 @@ npm install wickchart
 
 ```js
 // any bundler / framework — TypeScript types included
-import 'wickchart';                       // registers <hab-chart>
-import HabChart from 'wickchart';         // for HabChart.registerIndicator(...)
+import 'wickchart';                       // registers <wick-chart>
+import WickChart from 'wickchart';         // for WickChart.registerIndicator(...)
 import { encodeStateQuery } from 'wickchart/core';  // pure helpers
 ```
 
@@ -24,10 +24,10 @@ Or straight from a CDN — no install, no build:
 ```html
 <script type="module" src="https://unpkg.com/wickchart"></script>
 
-<hab-chart label="BTC · 1h" type="candles" indicators="sma:20 volume"></hab-chart>
+<wick-chart label="BTC · 1h" type="candles" indicators="sma:20 volume"></wick-chart>
 
 <script type="module">
-  const chart = document.querySelector('hab-chart');
+  const chart = document.querySelector('wick-chart');
   chart.setData(bars);   // [{ time, open, high, low, close, volume }]
   chart.update(bar);     // stream live updates
 </script>
@@ -37,7 +37,7 @@ Works in plain HTML, React, Vue, Svelte, Angular — anywhere a `<div>` works.
 TypeScript declarations ship inside the package (generated at pack time from
 the JSDoc-annotated source — the repo itself stays 100% dependency-free JS).
 
-## Declarative live charts with `<hab-feed>`
+## Declarative live charts with `<wick-feed>`
 
 One more script tag and your chart is fully live — data, backfill, streaming —
 with **zero JavaScript written**:
@@ -45,13 +45,13 @@ with **zero JavaScript written**:
 ```html
 <script type="module" src="https://unpkg.com/wickchart/feed"></script>
 
-<hab-feed for="chart" binance="BTCUSDT" tf="1h"></hab-feed>
-<hab-chart id="chart" indicators="sma:20 volume" profile></hab-chart>
+<wick-feed for="chart" binance="BTCUSDT" tf="1h"></wick-feed>
+<wick-chart id="chart" indicators="sma:20 volume" profile></wick-chart>
 ```
 
 | Attribute   | Meaning                                                                 |
 | ----------- | ----------------------------------------------------------------------- |
-| `for`       | target `<hab-chart>` id (auto-pairs with the first chart when omitted)   |
+| `for`       | target `<wick-chart>` id (auto-pairs with the first chart when omitted)   |
 | `binance`   | Binance symbol (`BTCUSDT`) — REST load + WebSocket live + backfill       |
 | `demo`      | deterministic offline synthetic feed (`demo="ETH"` picks a base price)   |
 | `url`       | generic REST endpoint returning a JSON array of bars (+ `poll="10"` sec) |
@@ -61,7 +61,7 @@ with **zero JavaScript written**:
 
 The element reflects its state in the `status` attribute (`loading`, `live`,
 `polling`, `fallback`, `loaded`, `waiting`, `idle`) and emits
-`hab-feed:status` / `hab-feed:fallback` events. When Binance is unreachable
+`wick-feed:status` / `wick-feed:fallback` events. When Binance is unreachable
 (geo-blocked, offline), it degrades gracefully: WebSocket → REST polling → a
 synthetic stream bridged from the last real price, so the chart never goes
 blank. It also wires `chart.onloadmore` for infinite backfill automatically.
@@ -71,7 +71,7 @@ blank. It also wires `chart.onloadmore` for infinite backfill automatically.
 ## Why another chart library?
 
 TradingView's charting library is powerful but heavy and enterprise-licensed;
-most wrappers add build steps and framework lock-in. HabView takes the opposite
+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)
@@ -82,7 +82,13 @@ bet:
   outside the component (Shadow DOM friendly)
 - **Accessible** — focusable, arrow-key crosshair, ARIA summary of the data
 
-## Run the demo
+## Try it online
+
+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.
+
+## Run the demo locally
 
 ```bash
 npm run dev        # serves on http://localhost:5173
@@ -125,6 +131,7 @@ chart.setData([
 | `stats`       | off        | Live statistics chip for the visible range          |
 | `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)    |
 
 \* `indicators=""` disables everything, including volume. Token syntax:
 `name[:param[/param…]][@color]` — e.g. `sma:20@#ff0000`, `macd:12/26/9`.
@@ -146,7 +153,7 @@ Register your own — anything from a one-liner moving average to a multi-line
 pane:
 
 ```js
-HabChart.registerIndicator('vwap', {
+WickChart.registerIndicator('vwap', {
   kind: 'overlay',               // or 'pane'
   params: { period: 20 },        // defaults; set via indicators="vwap:30"
   compute(bars, params) {        // bars: normalized {time,open,high,low,close,volume}
@@ -164,13 +171,119 @@ HabChart.registerIndicator('vwap', {
 chart.indicators = 'vwap:20';
 ```
 
-`import HabChart from 'wickchart'` gives you the class for
-`HabChart.registerIndicator(...)` (the element is registered as a side effect
+`import WickChart from 'wickchart'` gives you the class for
+`WickChart.registerIndicator(...)` (the element is registered as a side effect
 of importing the package).
 
+### WickScript — custom indicators as expressions
+
+No build step, no JS: write an indicator inline in the attribute. `expr:{…}`
+draws on the price chart; `pexpr:{…}` gets its own pane. Add an optional
+`@color`, mix freely with named indicators, and it all round-trips through
+shareable URLs.
+
+```html
+<wick-chart indicators="sma:20 expr:{(close - sma(close,20)) / sma(close,20) * 100}@ff6a00"></wick-chart>
+
+<!-- oscillator in its own pane -->
+<wick-chart indicators="pexpr:{rsi(close,14)} pexpr:{change(close) / close * 100}"></wick-chart>
+```
+
+| Series variables | |
+|---|---|
+| `open` `high` `low` `close` `volume` | raw bar fields |
+| `hl2` `hlc3` `ohlc4` | classic derived prices |
+
+| Functions | |
+|---|---|
+| `sma(x,n)` `ema(x,n)` `wma(x,n)` `stddev(x,n)` | moving stats (window `n` must be a whole number ≥ 1) |
+| `rsi(x,n)` | RSI of any series |
+| `hh(x,n)` `ll(x,n)` | rolling highest / lowest |
+| `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 |
+
+Operators are `+ - * / %` with usual precedence, unary `-`, and parentheses.
+Values before a window fills are `NaN` (not drawn), division by zero yields
+`NaN`, and identifiers are case-insensitive.
+
+The expression is compiled by a hand-written tokenizer + recursive-descent
+parser in `wickchart/core` — **no `eval`, no `new Function`** — with caps on
+length (512), tokens (128) and nesting (24). Invalid scripts are reported via
+the parse result's `unknown` list and simply not drawn; they can never execute
+anything.
+
+Programmatically, compile once and reuse, or register it under a name for the
+attribute syntax:
+
+```js
+import { scriptIndicator } from 'wickchart/core';
+
+WickChart.registerIndicator('spread', scriptIndicator('close - ema(close,21)'));
+chart.indicators = 'spread';   // now usable like any built-in
+```
+
+The demo has a live input for it (type an expression, optionally tick *pane*,
+press **+ Expr** — invalid expressions show the compiler's error inline).
+
+### Volatility-regime shading
+
+`<wick-chart volshading>` tints the price pane background by realized
+volatility — the rolling stddev of log returns (20 bars by default),
+classified against its own full-history percentiles: **calm** (≤ 30th
+percentile, subtle blue), **normal** (untinted), **hot** (≥ 70th percentile,
+subtle red). Market state at a glance: quiet ranges and violent expansions
+read instantly, and the legend shows the hovered bar's regime and
+percentile (`VOL 30/70 · hot · 94%ile`).
+
+```html
+<wick-chart volshading></wick-chart>                 <!-- defaults 30/70, 20 bars -->
+<wick-chart volshading="20/85"></wick-chart>         <!-- custom cutoffs -->
+<wick-chart volshading="20/85/50"></wick-chart>      <!-- + 50-bar vol window -->
+```
+
+Cutoffs are clamped so the low percentile always stays at least 2 points
+below the high one; the toggle and custom cutoffs round-trip through
+shareable URLs (`vsh=1` / `vsh=20/85`). A degenerate history (flat series)
+classifies everything as normal. The pieces are exported from
+`wickchart/core` (`calcRealizedVol`, `volRegimeBands`, `percentileOfSorted`)
+if you want to build on them.
+
+### AI-ready data window — `getDataWindow()`
+
+One call turns whatever is on screen into a compact, LLM-pasteable summary.
+Everything is computed locally from the visible bars — trend (least-squares
+drift + fit), realized-vol percentile, SMA/RSI snapshot, up/down bar mix,
+volume profile notes, and the same pattern detection that powers smart
+annotations (gaps, spikes, pivots, divergences). Nothing leaves the page
+until you copy it somewhere.
+
+```js
+const s = chart.getDataWindow();
+s.text;      // markdown — ready to paste into any AI chat
+s.trend;     // { label: 'strong uptrend', slopePctPerBar: 0.77, r2: 0.94 }
+s.volPctile; // 84 → hot regime relative to the window itself
+s.patterns;  // [{ time, note }] — most recent first
+```
+
+`text` renders like:
+
+```
+CHART SUMMARY — BTC · 1h · 214 bars · 2026-08-21 → 2026-09-07
+- Close 97.03 (−1.20% over window). High 104.20 on 2026-08-28, low 91.40 on 2026-09-01. Max drawdown 8.1%.
+- Trend: downtrend (drift −0.061%/bar, fit r² 0.58). Price below SMA20 (99.10). RSI(14) 41.3.
+- Volatility: annualized 48%; latest realized vol at the 84th percentile of the window (hot regime).
+- Bars: 96 up / 117 down. Volume avg 1.2K/bar, peak 8.9K on 2026-09-01.
+- Notable: Gapped down −1.42% (2026-09-01); Volume 4.1× average (2026-09-03).
+```
+
+The demo's **Explain** button shows this in a panel with a one-click copy.
+The pure function behind it (`windowSummary(bars, i0, i1, opts)`) is exported
+from `wickchart/core` for server-side use.
+
 ### Sonification — the chart by ear
 
-`<hab-chart sonify>` maps price to pitch (180–880 Hz across the visible
+`<wick-chart sonify>` maps price to pitch (180–880 Hz across the visible
 scale, log-aware): moving the crosshair with the mouse or **arrow keys** plays
 a short tone per bar, so trend and shape are audible — a rare accessibility
 win for screen-reader users. `chart.playRange()` sweeps the whole visible
@@ -184,7 +297,7 @@ Tag charts with the same channel and they share pointers — across browser
 tabs, or between multiple charts on one page:
 
 ```html
-<hab-chart co-view="btc-room"></hab-chart>
+<wick-chart co-view="btc-room"></wick-chart>
 ```
 
 Hovering in one tab draws a ghost crosshair (accent, dotted, with the time
@@ -195,12 +308,12 @@ stops moving. Same-origin only (BroadcastChannel); the connection follows the
 
 ### Smart annotations
 
-`<hab-chart annotations>` marks notable events on the visible range — volume
+`<wick-chart annotations>` marks notable events on the visible range — volume
 spikes (>3× average), price gaps, 41-bar pivot highs/lows, and RSI
 divergences — with lettered badges (V/G/H/L/D). Hover a badged bar and the
 legend shows a one-line insight ("Volume 4.2× average", "Bearish RSI
 divergence"). The current set is emitted on every recompute via the
-`hab:annotations` event, so hosts can build their own UI from it. Badges are
+`wick:annotations` event, so hosts can build their own UI from it. Badges are
 hidden at extreme zoom-out, where bars collapse into columns.
 
 ### Example: VWAP via the registry
@@ -209,9 +322,9 @@ VWAP ships in the demo but *not* as a builtin — it's the reference for writing
 your own (session-anchored, resets each trading day):
 
 ```js
-import HabChart from 'wickchart';
+import WickChart from 'wickchart';
 
-HabChart.registerIndicator('vwap', {
+WickChart.registerIndicator('vwap', {
   kind: 'overlay',
   params: {},
   compute(bars) {
@@ -243,6 +356,7 @@ chart.indicators = 'vwap';
 | `getVisibleRange()`             | → `{ from, to }` (ms timestamps)                  |
 | `setVisibleRange({from, to})`   | Jump to a time window                             |
 | `exportPNG()`                   | → PNG data URL of the current canvas              |
+| `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()` |
 
@@ -273,7 +387,7 @@ chart.addPosition({ id: 'x1', side: 'short', entry: 66000, qty: 1 });
 chart.removePosition('x1');
 
 chart.addAlert({ price: 65000, direction: 'above' }); // 'above' | 'below' | 'cross'
-chart.addEventListener('hab:alert', (e) => {
+chart.addEventListener('wick:alert', (e) => {
   console.log('crossed!', e.detail.id, e.detail.price);
 });
 ```
@@ -283,12 +397,12 @@ The P&L chip recalculates on every streamed bar. Alerts are edge-triggered
 
 ### Stats & measure
 
-`<hab-chart stats>` shows live statistics of the visible range — return %,
+`<wick-chart stats>` shows live statistics of the visible range — return %,
 max drawdown, annualized volatility, up/down bar counts, average volume —
 recalculated as you pan and zoom.
 
 Hold **Shift and drag** across the chart to measure a move: an overlay shows
-Δprice, Δ%, bar count and elapsed time, and a `hab:measure` event fires on
+Δprice, Δ%, bar count and elapsed time, and a `wick:measure` event fires on
 release (`detail.from` / `detail.to` carry index, time and price). Click or
 press `Esc` to clear.
 
@@ -315,9 +429,9 @@ Reflected properties (`chart.type = 'line'`) work for `theme`, `type`, `label`,
 
 | Event           | Detail                                                     |
 | --------------- | ---------------------------------------------------------- |
-| `hab:crosshair` | `{ index, bar, x, y, price }` on hover / arrows, `null` on leave |
-| `hab:range`     | `{ from, to }` after zoom / pan / jump                      |
-| `hab:select`    | `{ index, bar, price }` on click/tap (e.g. open an order form at that price) |
+| `wick:crosshair` | `{ index, bar, x, y, price }` on hover / arrows, `null` on leave |
+| `wick:range`     | `{ from, to }` after zoom / pan / jump                      |
+| `wick:select`    | `{ index, bar, price }` on click/tap (e.g. open an order form at that price) |
 
 ## Theming
 
@@ -325,18 +439,18 @@ All colors are CSS custom properties settable on the element (they pierce the
 Shadow DOM):
 
 ```css
-hab-chart {
-  --hab-bg: #0d1117;          /* transparent works too */
-  --hab-up: #16c784;
-  --hab-down: #ea3943;
-  --hab-accent: #4c8dff;      /* line & area color */
-  --hab-text: #8b949e;        /* axis text */
-  --hab-text-strong: #e6edf3; /* legend values */
-  --hab-grid: rgba(230,237,243,.05);
-  --hab-border: rgba(230,237,243,.09);
-  --hab-crosshair: rgba(230,237,243,.42);
-  --hab-rsi: #a78bfa;
-  --hab-overlay-0: #f0b429;   /* SMA color, …-1, -2, … for more overlays */
+wick-chart {
+  --wick-bg: #0d1117;          /* transparent works too */
+  --wick-up: #16c784;
+  --wick-down: #ea3943;
+  --wick-accent: #4c8dff;      /* line & area color */
+  --wick-text: #8b949e;        /* axis text */
+  --wick-text-strong: #e6edf3; /* legend values */
+  --wick-grid: rgba(230,237,243,.05);
+  --wick-border: rgba(230,237,243,.09);
+  --wick-crosshair: rgba(230,237,243,.42);
+  --wick-rsi: #a78bfa;
+  --wick-overlay-0: #f0b429;   /* SMA color, …-1, -2, … for more overlays */
 }
 ```
 
@@ -399,6 +513,27 @@ 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)
+
+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:
+
+| 0.x (deprecated alias) | 1.0 canonical |
+|---|---|
+| `<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).
+
 ## License
 
 MIT

package/package.json

@@ -1,23 +1,23 @@
 {
   "name": "wickchart",
-  "version": "0.3.0",
-  "description": "<hab-chart> — a modern, dependency-free financial charting web component. Candles, line & area charts, crosshair, zoom/pan, indicators, live streaming, theming.",
+  "version": "1.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>, theming.",
   "type": "module",
-  "main": "src/hab-chart.js",
-  "module": "src/hab-chart.js",
-  "types": "types/hab-chart.d.ts",
+  "main": "src/wick-chart.js",
+  "module": "src/wick-chart.js",
+  "types": "types/wick-chart.d.ts",
   "exports": {
     ".": {
-      "types": "./types/hab-chart.d.ts",
-      "default": "./src/hab-chart.js"
+      "types": "./types/wick-chart.d.ts",
+      "default": "./src/wick-chart.js"
     },
     "./core": {
       "types": "./types/core.d.ts",
       "default": "./src/core.js"
     },
     "./feed": {
-      "types": "./types/hab-feed.d.ts",
-      "default": "./src/hab-feed.js"
+      "types": "./types/wick-feed.d.ts",
+      "default": "./src/wick-feed.js"
     }
   },
   "files": [
@@ -25,14 +25,14 @@
     "types"
   ],
   "sideEffects": [
-    "src/hab-chart.js"
+    "src/wick-chart.js"
   ],
   "scripts": {
     "dev": "npx --yes serve . -l 5173",
     "test": "node --test \"tests/*.test.mjs\"",
-    "build:types": "tsc -p tsconfig.json",
+    "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/hab-chart.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 demo/app.js"
   },
   "keywords": [
     "chart",