wickchart 0.3.0 → 0.4.0

package/README.md

@@ -125,6 +125,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`.
@@ -168,6 +169,112 @@ chart.indicators = 'vwap:20';
 `HabChart.registerIndicator(...)` (the element is registered as a side effect
 of importing the package).
 
+### HabScript — 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
+<hab-chart indicators="sma:20 expr:{(close - sma(close,20)) / sma(close,20) * 100}@ff6a00"></hab-chart>
+
+<!-- oscillator in its own pane -->
+<hab-chart indicators="pexpr:{rsi(close,14)} pexpr:{change(close) / close * 100}"></hab-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';
+
+HabChart.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
+
+`<hab-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
+<hab-chart volshading></hab-chart>                 <!-- defaults 30/70, 20 bars -->
+<hab-chart volshading="20/85"></hab-chart>         <!-- custom cutoffs -->
+<hab-chart volshading="20/85/50"></hab-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
@@ -243,6 +350,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()` |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wickchart",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "<hab-chart> — a modern, dependency-free financial charting web component. Candles, line & area charts, crosshair, zoom/pan, indicators, live streaming, theming.",
   "type": "module",
   "main": "src/hab-chart.js",

package/src/core.js

@@ -410,6 +410,23 @@ export function calcStdDev(values, period) {
   return out;
 }
 
+/** Linear-weighted moving average (most recent bar weighs `period`), aligned like SMA.
+ * @param {number[]} values
+ * @param {number} period
+ * @returns {Array<number|null>}
+ */
+export function calcWMA(values, period) {
+  const out = new Array(values.length).fill(null);
+  if (period < 1 || values.length < period) return out;
+  const denom = (period * (period + 1)) / 2;
+  for (let i = period - 1; i < values.length; i++) {
+    let sum = 0;
+    for (let j = 0; j < period; j++) sum += values[i - j] * (period - j);
+    out[i] = sum / denom;
+  }
+  return out;
+}
+
 /**
  * Bollinger Bands.
  * @param {number[]} closes
@@ -849,7 +866,8 @@ export const BUILTIN_INDICATORS = new Map(
 
 /**
  * Parse an `indicators` attribute string against a registry.
- * Token: `name[:param[/param…]][@color]`, plus the `volume` keyword.
+ * Token: `name[:param[/param…]][@color]`, the `volume` keyword, and
+ * HabScript blobs `expr:{…}` (overlay) / `pexpr:{…}` (separate pane).
  * @param {string|null|undefined} str
  * @param {Map<string, IndicatorDef>} registry
  * @returns {{overlays: IndicatorEntry[], panes: IndicatorEntry[], volume: boolean, unknown: string[]}}
@@ -858,8 +876,32 @@ export function parseIndicators(str, registry) {
   const out = { overlays: [], panes: [], volume: false, unknown: [] };
   if (str == null || str === '') return out;
   const seen = new Set();
-  for (const raw of String(str).split(/[\s,;]+/)) {
-    if (!raw) continue;
+  for (const raw of splitIndicatorTokens(str)) {
+    const em = raw.match(/^(p?expr):\{([^{}]*)\}(@\S*)?$/i);
+    if (em) {
+      const pane = em[1].toLowerCase() === 'pexpr';
+      const src = em[2].trim();
+      let def;
+      try {
+        def = scriptIndicator(src, { pane });
+      } catch (err) {
+        out.unknown.push(em[1] + ':{' + src + '}');
+        continue;
+      }
+      const key = (pane ? 'pexpr' : 'expr') + ':{' + src.toLowerCase() + '}';
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const entry = {
+        name: pane ? 'pexpr' : 'expr',
+        def,
+        params: {},
+        color: em[3] ? em[3].slice(1) : null,
+        key,
+      };
+      if (pane) out.panes.push(entry);
+      else out.overlays.push(entry);
+      continue;
+    }
     const m = raw.match(/^([A-Za-z][A-Za-z0-9_]*)(?::([^@]*))?(@.+)?$/);
     if (!m) continue;
     const [, name, paramStr, colorStr] = m;
@@ -897,6 +939,386 @@ export function parseIndicators(str, registry) {
   return out;
 }
 
+/* ------------------------------------------------------------------ *
+ * HabScript — safe expression mini-language for custom indicators
+ *
+ * `expr:{(close - sma(close,20)) / sma(close,20)}` compiles through a
+ * hand-written tokenizer + recursive-descent parser (no eval / Function)
+ * and evaluates element-wise over the bar series.
+ * ------------------------------------------------------------------ */
+
+const SCRIPT_MAX_LEN = 512;
+const SCRIPT_MAX_TOKENS = 128;
+const SCRIPT_MAX_DEPTH = 24;
+
+/** Series variables available inside expressions. */
+const SCRIPT_VARS = ['open', 'high', 'low', 'close', 'volume', 'hl2', 'hlc3', 'ohlc4'];
+
+/**
+ * Functions available inside expressions. `scalar` lists argument indexes
+ * that must be plain whole-number literals (periods / shifts).
+ */
+const SCRIPT_FUNCS = {
+  sma: { min: 2, max: 2, scalar: [1] },
+  ema: { min: 2, max: 2, scalar: [1] },
+  wma: { min: 2, max: 2, scalar: [1] },
+  stddev: { min: 2, max: 2, scalar: [1] },
+  rsi: { min: 2, max: 2, scalar: [1] },
+  hh: { min: 2, max: 2, scalar: [1] },
+  ll: { min: 2, max: 2, scalar: [1] },
+  prev: { min: 1, max: 2, scalar: [1] },
+  change: { min: 1, max: 1 },
+  abs: { min: 1, max: 1 },
+  sqrt: { min: 1, max: 1 },
+  log: { min: 1, max: 1 },
+  min: { min: 2, max: 2 },
+  max: { min: 2, max: 2 },
+  crossup: { min: 2, max: 2 },
+  crossdown: { min: 2, max: 2 },
+};
+
+const scriptErr = (msg) => new Error('script: ' + msg);
+
+/**
+ * Split an indicators string into tokens, keeping `expr:{…}` / `pexpr:{…}`
+ * blobs atomic — spaces and commas inside the braces are preserved, and an
+ * optional `@color` suffix directly after `}` stays attached.
+ * Separators are whitespace, `,` and `;`.
+ * @param {string|null|undefined} str
+ * @returns {string[]}
+ */
+export function splitIndicatorTokens(str) {
+  const out = [];
+  const s = String(str == null ? '' : str);
+  let i = 0;
+  while (i < s.length) {
+    while (i < s.length && /[\s,;]/.test(s[i])) i++;
+    if (i >= s.length) break;
+    let j = i;
+    if (/^(p?expr):\{/i.test(s.slice(i))) {
+      const end = s.indexOf('}', i);
+      if (end === -1) {
+        out.push(s.slice(i)); // unterminated → caller rejects the token
+        break;
+      }
+      j = end + 1;
+      if (s[j] === '@') {
+        j++;
+        while (j < s.length && !/[\s,;]/.test(s[j])) j++;
+      }
+    } else {
+      while (j < s.length && !/[\s,;]/.test(s[j])) j++;
+    }
+    out.push(s.slice(i, j));
+    i = j;
+  }
+  return out.filter(Boolean);
+}
+
+/** Tokenize an expression (numbers, identifiers, operators, `( ) ,`). */
+function tokenizeScript(src) {
+  if (typeof src !== 'string' || !src.trim()) throw scriptErr('empty expression');
+  if (src.length > SCRIPT_MAX_LEN) throw scriptErr(`expression longer than ${SCRIPT_MAX_LEN} chars`);
+  const toks = [];
+  let i = 0;
+  while (i < src.length) {
+    const c = src[i];
+    if (c === ' ' || c === '\t' || c === '\n' || c === '\r') {
+      i++;
+      continue;
+    }
+    const isDigit = c >= '0' && c <= '9';
+    if (isDigit || (c === '.' && src[i + 1] >= '0' && src[i + 1] <= '9')) {
+      const m = src.slice(i).match(/^\d*\.?\d+/);
+      toks.push({ t: 'num', v: parseFloat(m[0]) });
+      i += m[0].length;
+      continue;
+    }
+    const isAlpha = (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || c === '_';
+    if (isAlpha) {
+      const m = src.slice(i).match(/^[A-Za-z_][A-Za-z0-9_]*/);
+      toks.push({ t: 'id', v: m[0] });
+      i += m[0].length;
+      continue;
+    }
+    if (c === '+' || c === '-' || c === '*' || c === '/' || c === '%') {
+      toks.push({ t: 'op', v: c });
+      i++;
+      continue;
+    }
+    if (c === '(' || c === ')' || c === ',') {
+      toks.push({ t: c });
+      i++;
+      continue;
+    }
+    throw scriptErr(`unexpected character "${c}"`);
+  }
+  if (!toks.length) throw scriptErr('empty expression');
+  if (toks.length > SCRIPT_MAX_TOKENS) throw scriptErr(`more than ${SCRIPT_MAX_TOKENS} tokens`);
+  return toks;
+}
+
+/** Recursive-descent parse into a small AST; validates identifiers, calls and arities. */
+function parseScript(src) {
+  const toks = tokenizeScript(src);
+  let p = 0;
+  const peek = () => toks[p];
+
+  function parseAdd(depth) {
+    let l = parseMul(depth);
+    while (peek() && peek().t === 'op' && (peek().v === '+' || peek().v === '-')) {
+      const op = toks[p++].v;
+      l = { type: 'bin', op, l, r: parseMul(depth) };
+    }
+    return l;
+  }
+  function parseMul(depth) {
+    let l = parseUnary(depth);
+    while (peek() && peek().t === 'op' && (peek().v === '*' || peek().v === '/' || peek().v === '%')) {
+      const op = toks[p++].v;
+      l = { type: 'bin', op, l, r: parseUnary(depth) };
+    }
+    return l;
+  }
+  function parseUnary(depth) {
+    if (depth > SCRIPT_MAX_DEPTH) throw scriptErr('expression too deeply nested');
+    const t = peek();
+    if (t && t.t === 'op' && (t.v === '-' || t.v === '+')) {
+      p++;
+      const e = parseUnary(depth + 1);
+      return t.v === '-' ? { type: 'neg', e } : e;
+    }
+    return parseAtom(depth + 1);
+  }
+  function parseAtom(depth) {
+    if (depth > SCRIPT_MAX_DEPTH) throw scriptErr('expression too deeply nested');
+    const t = toks[p++];
+    if (!t) throw scriptErr('unexpected end of expression');
+    if (t.t === 'num') return { type: 'num', v: t.v };
+    if (t.t === 'id') {
+      const name = t.v.toLowerCase();
+      if (peek() && peek().t === '(') {
+        p++;
+        const args = [];
+        if (peek() && peek().t !== ')') {
+          args.push(parseAdd(depth));
+          while (peek() && peek().t === ',') {
+            p++;
+            args.push(parseAdd(depth));
+          }
+        }
+        const close = toks[p++];
+        if (!close || close.t !== ')') throw scriptErr(`missing ")" after ${name}(`);
+        return { type: 'call', name, args };
+      }
+      if (!SCRIPT_VARS.includes(name)) throw scriptErr(`unknown identifier "${t.v}"`);
+      return { type: 'var', name };
+    }
+    if (t.t === '(') {
+      const e = parseAdd(depth);
+      const close = toks[p++];
+      if (!close || close.t !== ')') throw scriptErr('missing ")"');
+      return e;
+    }
+    throw scriptErr(`unexpected token "${t.t === 'op' ? t.v : t.t}"`);
+  }
+
+  const ast = parseAdd(0);
+  if (p < toks.length) throw scriptErr('unexpected trailing input');
+  validateScriptNode(ast);
+  return ast;
+}
+
+function validateScriptNode(n) {
+  if (!n || n.type === 'num' || n.type === 'var') return;
+  if (n.type === 'neg') return validateScriptNode(n.e);
+  if (n.type === 'bin') {
+    validateScriptNode(n.l);
+    validateScriptNode(n.r);
+    return;
+  }
+  if (n.type === 'call') {
+    const spec = SCRIPT_FUNCS[n.name];
+    if (!spec) throw scriptErr(`unknown function "${n.name}"`);
+    if (n.args.length < spec.min || n.args.length > spec.max) {
+      const want = spec.min === spec.max ? String(spec.min) : `${spec.min}–${spec.max}`;
+      throw scriptErr(`${n.name}() takes ${want} argument${spec.max === 1 ? '' : 's'} (got ${n.args.length})`);
+    }
+    n.args.forEach((a, i) => {
+      if (spec.scalar && spec.scalar.includes(i)) {
+        if (a.type !== 'num' || !Number.isInteger(a.v) || a.v < 1) {
+          throw scriptErr(`${n.name}() argument ${i + 1} must be a whole number ≥ 1`);
+        }
+      }
+      validateScriptNode(a);
+    });
+  }
+}
+
+/**
+ * Compile a HabScript expression. Throws a descriptive error on any syntax
+ * or semantic problem — never evaluates strings at runtime.
+ * @param {string} src
+ * @returns {{src: string, ast: object}}
+ */
+export function compileScript(src) {
+  const s = String(src == null ? '' : src).trim();
+  return { src: s, ast: parseScript(s) };
+}
+
+/** null → NaN so sparse calc helpers compose safely inside expressions. */
+const scriptNum = (x) => (x == null || Number.isFinite(x) ? x : NaN);
+
+function binOp(op, a, b) {
+  if (a == null || b == null) return NaN;
+  switch (op) {
+    case '+': return a + b;
+    case '-': return a - b;
+    case '*': return a * b;
+    case '/': return a / b;
+    case '%': return a % b;
+  }
+  return NaN;
+}
+
+function evalScriptNode(node, vars, n) {
+  switch (node.type) {
+    case 'num':
+      return node.v;
+    case 'var':
+      return vars[node.name];
+    case 'neg': {
+      const e = evalScriptNode(node.e, vars, n);
+      if (!Array.isArray(e)) return -e;
+      return e.map((x) => (x == null ? NaN : -x));
+    }
+    case 'bin': {
+      const l = evalScriptNode(node.l, vars, n);
+      const r = evalScriptNode(node.r, vars, n);
+      if (!Array.isArray(l) && !Array.isArray(r)) return binOp(node.op, l, r);
+      const a = Array.isArray(l) ? l : new Array(n).fill(l);
+      const b = Array.isArray(r) ? r : new Array(n).fill(r);
+      const out = new Array(n);
+      for (let i = 0; i < n; i++) out[i] = binOp(node.op, a[i], b[i]);
+      return out;
+    }
+    case 'call':
+      return evalScriptCall(node, vars, n);
+  }
+  return NaN;
+}
+
+function evalScriptCall(node, vars, n) {
+  const { name, args } = node;
+  const s0 = evalScriptNode(args[0], vars, n);
+  const a = Array.isArray(s0) ? s0 : new Array(n).fill(s0);
+  // window functions must not read leading nulls as 0 — NaN them so results stay honest
+  const clean = a.map((x) => (x == null ? NaN : x));
+  const p = args.length > 1 && args[1].type === 'num' ? args[1].v : 1;
+
+  switch (name) {
+    case 'sma': return calcSMA(clean, p);
+    case 'ema': return calcEMA(clean, p);
+    case 'wma': return calcWMA(clean, p);
+    case 'stddev': return calcStdDev(clean, p);
+    case 'rsi': return calcRSI(clean, p);
+    case 'hh':
+    case 'll': {
+      const out = new Array(n).fill(null);
+      for (let i = p - 1; i < n; i++) {
+        let v = clean[i];
+        for (let j = i - p + 1; j <= i; j++) {
+          v = name === 'hh' ? Math.max(v, clean[j]) : Math.min(v, clean[j]);
+        }
+        out[i] = v;
+      }
+      return out;
+    }
+    case 'prev': {
+      const out = new Array(n).fill(null);
+      for (let i = p; i < n; i++) out[i] = a[i - p];
+      return out;
+    }
+    case 'change': {
+      const out = new Array(n).fill(null);
+      for (let i = 1; i < n; i++) out[i] = scriptNum(a[i]) - scriptNum(a[i - 1]);
+      return out;
+    }
+    case 'abs': return clean.map((x) => Math.abs(x));
+    case 'sqrt': return clean.map((x) => (x < 0 ? NaN : Math.sqrt(x)));
+    case 'log': return clean.map((x) => (x <= 0 ? NaN : Math.log(x)));
+    case 'min':
+    case 'max': {
+      const b0 = evalScriptNode(args[1], vars, n);
+      const b = Array.isArray(b0) ? b0 : new Array(n).fill(b0);
+      return a.map((x, i) => (name === 'min' ? Math.min(scriptNum(x), scriptNum(b[i])) : Math.max(scriptNum(x), scriptNum(b[i]))));
+    }
+    case 'crossup':
+    case 'crossdown': {
+      const b0 = evalScriptNode(args[1], vars, n);
+      const b = Array.isArray(b0) ? b0 : new Array(n).fill(b0);
+      const out = new Array(n).fill(0);
+      for (let i = 1; i < n; i++) {
+        const x0 = scriptNum(a[i - 1]);
+        const x1 = scriptNum(a[i]);
+        const y0 = scriptNum(b[i - 1]);
+        const y1 = scriptNum(b[i]);
+        if (Number.isNaN(x0) || Number.isNaN(x1) || Number.isNaN(y0) || Number.isNaN(y1)) continue;
+        out[i] = name === 'crossup' ? (x0 <= y0 && x1 > y1 ? 1 : 0) : (x0 >= y0 && x1 < y1 ? 1 : 0);
+      }
+      return out;
+    }
+  }
+  return new Array(n).fill(NaN);
+}
+
+/**
+ * Evaluate a compiled script (or a raw expression string) over bars.
+ * @param {{src:string, ast:object}|string} compiled
+ * @param {Bar[]} bars
+ * @returns {number[]} length `bars.length`; non-finite values become NaN
+ */
+export function evalScript(compiled, bars) {
+  const c = typeof compiled === 'string' ? compileScript(compiled) : compiled;
+  const n = bars.length;
+  const out = new Array(n).fill(NaN);
+  if (!n) return out;
+  const vars = {
+    open: bars.map((b) => b.open),
+    high: bars.map((b) => b.high),
+    low: bars.map((b) => b.low),
+    close: bars.map((b) => b.close),
+    volume: bars.map((b) => b.volume),
+    hl2: bars.map((b) => (b.high + b.low) / 2),
+    hlc3: bars.map((b) => (b.high + b.low + b.close) / 3),
+    ohlc4: bars.map((b) => (b.open + b.high + b.low + b.close) / 4),
+  };
+  const res = evalScriptNode(c.ast, vars, n);
+  const arr = Array.isArray(res) ? res : new Array(n).fill(res);
+  for (let i = 0; i < n; i++) {
+    const v = arr[i];
+    out[i] = v != null && Number.isFinite(v) ? v : NaN;
+  }
+  return out;
+}
+
+/**
+ * Build an indicator definition from a HabScript expression — used inline by
+ * `indicators="expr:{…}"` / `pexpr:{…}"`, or register it under a name:
+ * `HabChart.registerIndicator('myspread', scriptIndicator('close - ema(close,21)'))`.
+ * @param {string} src
+ * @param {{pane?: boolean}} [opts]
+ * @returns {IndicatorDef}
+ */
+export function scriptIndicator(src, opts = {}) {
+  const compiled = compileScript(src);
+  const label = compiled.src.length > 24 ? compiled.src.slice(0, 23) + '…' : compiled.src;
+  return {
+    kind: opts.pane ? 'pane' : 'overlay',
+    compute: (bars) => ({ lines: [{ name: label, values: evalScript(compiled, bars) }] }),
+  };
+}
+
 /* ------------------------------------------------------------------ *
  * Trading overlays
  * ------------------------------------------------------------------ */
@@ -998,6 +1420,304 @@ export function computeStats(bars, i0, i1, dtMs) {
   };
 }
 
+/* ------------------------------------------------------------------ *
+ * Volatility-regime shading
+ * ------------------------------------------------------------------ */
+
+/**
+ * Rolling realized volatility: population stddev of log returns over the
+ * last `period` bars (per-bar value, aligned like SMA — null until the
+ * window fills).
+ * @param {number[]} closes
+ * @param {number} [period=20]
+ * @returns {Array<number|null>}
+ */
+export function calcRealizedVol(closes, period = 20) {
+  const n = closes.length;
+  const out = new Array(n).fill(null);
+  if (period < 2 || n < 2) return out;
+  const rets = new Array(n).fill(0);
+  let sum = 0;
+  let sumSq = 0;
+  let cnt = 0;
+  for (let i = 1; i < n; i++) {
+    const r = closes[i - 1] > 0 && closes[i] > 0 ? Math.log(closes[i] / closes[i - 1]) : NaN;
+    rets[i] = r;
+    if (Number.isFinite(r)) {
+      sum += r;
+      sumSq += r * r;
+      cnt++;
+    }
+    const j = i - period; // return that falls out of the window
+    if (j >= 1 && Number.isFinite(rets[j])) {
+      sum -= rets[j];
+      sumSq -= rets[j] * rets[j];
+      cnt--;
+    }
+    if (i >= period && cnt === period) {
+      const mean = sum / period;
+      out[i] = Math.sqrt(Math.max(0, sumSq / period - mean * mean));
+    }
+  }
+  return out;
+}
+
+/**
+ * Classify a realized-vol series into regimes by empirical percentile over
+ * the whole series: 0 = calm (≤ qLow), 1 = normal, 2 = hot (≥ qHigh),
+ * -1 = unknown (null input). A degenerate spread (qHigh ≤ qLow, e.g. a
+ * flat series) classifies everything as normal.
+ * @param {Array<number|null>} vol
+ * @param {number} [qLow=30]
+ * @param {number} [qHigh=70]
+ * @returns {{regimes:number[], sorted:number[], q1:number, q2:number}}
+ */
+export function volRegimeBands(vol, qLow = 30, qHigh = 70) {
+  const n = vol.length;
+  const regimes = new Array(n).fill(-1);
+  const sorted = [];
+  for (let i = 0; i < n; i++) if (isNum(vol[i])) sorted.push(vol[i]);
+  sorted.sort((a, b) => a - b);
+  const q = (p) => {
+    if (!sorted.length) return NaN;
+    const pos = clamp((p / 100) * (sorted.length - 1), 0, sorted.length - 1);
+    const lo = Math.floor(pos);
+    const hi = Math.ceil(pos);
+    return lo === hi ? sorted[lo] : sorted[lo] + (sorted[hi] - sorted[lo]) * (pos - lo);
+  };
+  const q1 = q(Math.min(qLow, qHigh));
+  const q2 = q(Math.max(qLow, qHigh));
+  const degenerate = !(q2 > q1);
+  for (let i = 0; i < n; i++) {
+    if (!isNum(vol[i])) continue;
+    regimes[i] = degenerate ? 1 : vol[i] <= q1 ? 0 : vol[i] >= q2 ? 2 : 1;
+  }
+  return { regimes, sorted, q1, q2 };
+}
+
+/**
+ * Percentile (0–100) of `v` within an ascending `sorted` array.
+ * @param {number[]} sorted
+ * @param {number} v
+ * @returns {number}
+ */
+export function percentileOfSorted(sorted, v) {
+  if (!sorted.length || !isNum(v)) return NaN;
+  let lo = 0;
+  let hi = sorted.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (sorted[mid] < v) lo = mid + 1;
+    else hi = mid;
+  }
+  if (sorted.length === 1) return sorted[0] === v ? 50 : sorted[0] < v ? 100 : 0;
+  return clamp((lo / (sorted.length - 1)) * 100, 0, 100);
+}
+
+/**
+ * Parse a `volshading` attribute value: `""` / `"true"` → defaults (30/70,
+ * period 20); `"30/70"` custom cutoffs; `"30/70/14"` cutoffs + period.
+ * Inputs are clamped so qLow always stays at least 2 points below qHigh.
+ * @param {string|null|undefined} val
+ * @returns {{p1:number, p2:number, period:number}}
+ */
+export function parseVolShading(val) {
+  const parts = String(val == null ? '' : val).split('/').map((s) => parseFloat(s));
+  let p1 = isNum(parts[0]) ? clamp(parts[0], 0, 98) : 30;
+  const p2 = isNum(parts[1]) ? clamp(parts[1], 2, 100) : 70;
+  p1 = clamp(p1, 0, p2 - 2);
+  const period = isNum(parts[2]) ? Math.round(clamp(parts[2], 2, 500)) : 20;
+  return { p1, p2, period };
+}
+
+/* ------------------------------------------------------------------ *
+ * AI-ready window summary
+ * ------------------------------------------------------------------ */
+
+/** Least-squares trend of a value sequence: slope per bar + goodness of fit. */
+function lsTrend(vals) {
+  const n = vals.length;
+  let sx = 0;
+  let sy = 0;
+  let sxx = 0;
+  let sxy = 0;
+  for (let i = 0; i < n; i++) {
+    sx += i;
+    sy += vals[i];
+    sxx += i * i;
+    sxy += i * vals[i];
+  }
+  const denom = n * sxx - sx * sx;
+  if (!denom) return { slope: 0, r2: 0 };
+  const slope = (n * sxy - sx * sy) / denom;
+  const intercept = (sy - slope * sx) / n;
+  const meanY = sy / n;
+  let ssTot = 0;
+  let ssRes = 0;
+  for (let i = 0; i < n; i++) {
+    ssTot += (vals[i] - meanY) * (vals[i] - meanY);
+    ssRes += (vals[i] - (intercept + slope * i)) * (vals[i] - (intercept + slope * i));
+  }
+  return { slope, r2: ssTot ? Math.max(0, 1 - ssRes / ssTot) : 0 };
+}
+
+export const tfLabelOf = (dtMs) => {
+  if (!isNum(dtMs) || dtMs <= 0) return '';
+  const s = Math.round(dtMs / 1000);
+  if (s < 60) return s + 's';
+  const m = Math.round(s / 60);
+  if (m < 60) return m + 'm';
+  const h = Math.round(m / 60);
+  if (h < 24) return h + 'h';
+  const d = Math.round(h / 24);
+  if (d < 7) return d + 'd';
+  return Math.round(d / 7) + 'w';
+};
+
+/**
+ * Compact, LLM-friendly summary of a bar window: structured fields plus a
+ * ready-to-paste markdown rendering (`text`). Built entirely from local
+ * data — nothing leaves the page until the user pastes it somewhere.
+ *
+ * @param {Bar[]} bars full dataset
+ * @param {number} i0 first index of the window
+ * @param {number} i1 last index of the window
+ * @param {{dtMs?: number, label?: string}} [opts] bar spacing (ms) + chart label
+ * @returns {object|null} null when the window is empty or out of range
+ */
+export function windowSummary(bars, i0, i1, opts = {}) {
+  const n = i1 - i0 + 1;
+  if (!bars.length || n < 2 || i0 < 0 || i1 >= bars.length) return null;
+  const closes = bars.map((b) => b.close);
+  const stats = computeStats(bars, i0, i1, opts.dtMs || 0);
+
+  let hi = -Infinity;
+  let lo = Infinity;
+  let hiI = i0;
+  let loI = i0;
+  let vMax = -Infinity;
+  let vMaxI = i0;
+  for (let i = i0; i <= i1; i++) {
+    if (bars[i].high > hi) {
+      hi = bars[i].high;
+      hiI = i;
+    }
+    if (bars[i].low < lo) {
+      lo = bars[i].low;
+      loI = i;
+    }
+    if (isNum(bars[i].volume) && bars[i].volume > vMax) {
+      vMax = bars[i].volume;
+      vMaxI = i;
+    }
+  }
+
+  // trend over the window: % drift per bar + fit quality
+  const win = closes.slice(i0, i1 + 1);
+  const t = lsTrend(win);
+  const meanY = win.reduce((a, b) => a + b, 0) / n;
+  const slopePct = meanY ? (t.slope / meanY) * 100 : 0;
+  let trendLabel;
+  if (t.r2 < 0.25) trendLabel = 'range-bound';
+  else if (slopePct >= 0.15) trendLabel = 'strong uptrend';
+  else if (slopePct <= -0.15) trendLabel = 'strong downtrend';
+  else if (slopePct >= 0.05) trendLabel = 'uptrend';
+  else if (slopePct <= -0.05) trendLabel = 'downtrend';
+  else trendLabel = 'mild drift ' + (slopePct >= 0 ? 'up' : 'down');
+
+  // realized-vol percentile of the latest bar within the window itself
+  let volPctile = null;
+  const wvol = calcRealizedVol(win, Math.min(20, Math.max(2, Math.floor(n / 3))));
+  let lastVol = null;
+  for (let i = wvol.length - 1; i >= 0; i--) {
+    if (isNum(wvol[i])) {
+      lastVol = wvol[i];
+      break;
+    }
+  }
+  if (lastVol != null) {
+    const sorted = wvol.filter((x) => isNum(x)).sort((a, b) => a - b);
+    volPctile = Math.round(percentileOfSorted(sorted, lastVol));
+  }
+
+  const sma20 = n >= 20 ? calcSMA(win, 20)[n - 1] : null;
+  const rsi14 = n > 15 ? calcRSI(win, 14)[n - 1] : null;
+
+  // notable events (most recent first, capped)
+  const ann = detectAnnotations(bars, i0, i1, calcRSI(closes, 14))
+    .sort((a, b) => b.i - a.i)
+    .slice(0, 8)
+    .map((a) => ({ time: bars[a.i].time, note: a.note }));
+
+  const f = numberFmt(autoPrecision(closes[i1]));
+  const day = (ms) => new Date(ms).toISOString().slice(0, 10);
+  const from = bars[i0].time;
+  const to = bars[i1].time;
+  const label = opts.label || 'Chart';
+  const tf = tfLabelOf(opts.dtMs);
+  const showTf = tf && !label.includes(tf) ? ` · ${tf}` : '';
+
+  const out = {
+    label,
+    bars: n,
+    from,
+    to,
+    timeframe: tf,
+    open: closes[i0],
+    close: closes[i1],
+    changePct: stats.changePct,
+    high: hi,
+    highTime: bars[hiI].time,
+    low: lo,
+    lowTime: bars[loI].time,
+    maxDDPct: stats.maxDDPct,
+    upBars: stats.up,
+    downBars: stats.dn,
+    avgVolume: stats.avgVolume,
+    maxVolume: vMax,
+    maxVolumeTime: bars[vMaxI].time,
+    annVolPct: stats.annVolPct,
+    volPctile,
+    trend: { slopePctPerBar: slopePct, r2: t.r2, label: trendLabel },
+    sma20: isNum(sma20) ? { value: sma20, priceAbove: closes[i1] >= sma20 } : null,
+    rsi14: isNum(rsi14) ? rsi14 : null,
+    patterns: ann,
+  };
+
+  const lines = [];
+  lines.push(
+    `CHART SUMMARY — ${label}${showTf} · ${n} bars · ${day(from)} → ${day(to)}`
+  );
+  lines.push(
+    `- Close ${f.format(out.close)} (${out.changePct >= 0 ? '+' : ''}${out.changePct.toFixed(2)}% over window). ` +
+      `High ${f.format(hi)} on ${day(out.highTime)}, low ${f.format(lo)} on ${day(out.lowTime)}. ` +
+      `Max drawdown ${out.maxDDPct.toFixed(1)}%.`
+  );
+  lines.push(
+    `- Trend: ${trendLabel} (drift ${slopePct >= 0 ? '+' : ''}${slopePct.toFixed(3)}%/bar, fit r² ${t.r2.toFixed(2)}).` +
+      (out.sma20 ? ` Price ${out.sma20.priceAbove ? 'above' : 'below'} SMA20 (${f.format(out.sma20.value)}).` : '') +
+      (out.rsi14 != null ? ` RSI(14) ${out.rsi14.toFixed(1)}.` : '')
+  );
+  lines.push(
+    `- Volatility: annualized ${out.annVolPct.toFixed(0)}%` +
+      (volPctile != null
+        ? `; latest realized vol at the ${volPctile}th percentile of the window ` +
+          `(${volPctile >= 70 ? 'hot' : volPctile <= 30 ? 'calm' : 'normal'} regime).`
+        : '.')
+  );
+  lines.push(
+    `- Bars: ${out.upBars} up / ${out.downBars} down. Volume avg ${fmtCompact(out.avgVolume)}/bar, ` +
+      `peak ${fmtCompact(vMax)} on ${day(out.maxVolumeTime)}.`
+  );
+  lines.push(
+    out.patterns.length
+      ? `- Notable: ${out.patterns.map((a) => `${a.note} (${day(a.time)})`).join('; ')}.`
+      : '- Notable: no gaps, volume spikes or pivots flagged.'
+  );
+  out.text = lines.join('\n');
+  return out;
+}
+
 /* ------------------------------------------------------------------ *
  * State serialization (shareable URLs)
  * ------------------------------------------------------------------ */
@@ -1017,7 +1737,9 @@ export function encodeStateQuery(state) {
   if (state.stats) p.set('stats', '1');
   if (state.profile) p.set('profile', '1');
   if (state.annotations) p.set('ann', '1');
-  if (state.indicators) p.set('ind', state.indicators.trim().replace(/\s+/g, ','));
+  if (state.volshading === true) p.set('vsh', '1');
+  else if (typeof state.volshading === 'string' && state.volshading) p.set('vsh', state.volshading);
+  if (state.indicators) p.set('ind', splitIndicatorTokens(state.indicators).join(','));
   if (state.view) {
     if (isNum(state.view.from)) p.set('from', String(Math.floor(state.view.from / 1000)));
     if (isNum(state.view.to)) p.set('to', String(Math.floor(state.view.to / 1000)));
@@ -1041,8 +1763,11 @@ export function decodeStateQuery(str) {
   if (p.get('stats') === '1') state.stats = true;
   if (p.get('profile') === '1') state.profile = true;
   if (p.get('ann') === '1') state.annotations = true;
+  const vsh = p.get('vsh');
+  if (vsh === '1') state.volshading = true;
+  else if (vsh) state.volshading = vsh;
   const ind = p.get('ind');
-  if (ind) state.indicators = ind.split(',').map((s) => s.trim()).filter(Boolean).join(' ');
+  if (ind) state.indicators = splitIndicatorTokens(ind).join(' ');
   const from = p.get('from');
   const to = p.get('to');
   if (from != null || to != null) {

package/src/hab-chart.js

@@ -24,6 +24,8 @@ import {
   positionPnl, checkAlertCross, computeStats, safeColor,
   SERIES_TYPES, calcHeikinAshi, buildColumns, computeVolumeProfile,
   calcRSI, detectAnnotations, priceToFreq,
+  calcRealizedVol, volRegimeBands, percentileOfSorted, parseVolShading,
+  windowSummary,
 } from './core.js';
 
 /* ------------------------------------------------------------------ *
@@ -36,7 +38,7 @@ const HTMLElementBase = typeof HTMLElement !== 'undefined' ? HTMLElement : class
 
 class HabChart extends HTMLElementBase {
     static get observedAttributes() {
-      return ['theme', 'type', 'log', 'auto', 'indicators', 'precision', 'label', 'stats', 'profile', 'annotations', 'co-view', 'sonify'];
+      return ['theme', 'type', 'log', 'auto', 'indicators', 'precision', 'label', 'stats', 'profile', 'annotations', 'volshading', 'co-view', 'sonify'];
     }
 
     constructor() {
@@ -184,6 +186,7 @@ class HabChart extends HTMLElementBase {
       this._annotations = false;
       this._annoKey = '';
       this._annoList = null;
+      this._volshade = null;
 
       // cross-tab co-view state
       this._coviewName = null;
@@ -316,6 +319,10 @@ class HabChart extends HTMLElementBase {
           this._annotations = val != null && val !== 'false';
           this._annoKey = '';
           break;
+        case 'volshading':
+          this._volshade = val != null && val !== 'false' ? parseVolShading(val) : null;
+          this._legendKey = '';
+          break;
         case 'co-view':
           this._coviewName = val || null;
           this._setupCoView();
@@ -553,6 +560,41 @@ class HabChart extends HTMLElementBase {
       return this._canvas.toDataURL('image/png');
     }
 
+    /**
+     * AI-ready summary of the visible window: structured fields plus a
+     * ready-to-paste markdown rendering (`text`). Computed locally —
+     * nothing leaves the page until the user copies it somewhere.
+     * @returns {object|null}
+     */
+    getDataWindow() {
+      const d = this._data;
+      if (!d.length || !this._ly) return null;
+      const { plotRight } = this._ly;
+      const { rightIndex, spacing } = this._view;
+      const i0 = Math.max(0, Math.round(rightIndex - plotRight / spacing));
+      const i1 = clamp(Math.round(rightIndex), 0, d.length - 1);
+      const s = windowSummary(d, i0, i1, { dtMs: this._dt, label: this._label });
+      if (!s) return null;
+      // snapshot active indicator values at the right edge (scripts show their expression)
+      const f = numberFmt(this._prec(d[i1].close));
+      const snap = [];
+      for (const entry of this._ind.overlays.concat(this._ind.panes)) {
+        if (entry.name === 'volume') continue;
+        const res = this._indicatorSeries(entry);
+        for (const ln of res.lines) {
+          const v = ln.values[i1];
+          if (!isNum(v)) continue;
+          const isScript = entry.name === 'expr' || entry.name === 'pexpr';
+          const name = isScript
+            ? ln.name || entry.name
+            : entry.name + (Object.keys(entry.params).length ? ':' + Object.values(entry.params).join('/') : '');
+          snap.push(`${name} = ${f.format(v)}`);
+        }
+      }
+      if (snap.length) s.text += `\n- Indicators: ${snap.join('; ')}.`;
+      return s;
+    }
+
     /* ------------------------------------------------------------ *
      * State serialization
      * ------------------------------------------------------------ */
@@ -575,6 +617,9 @@ class HabChart extends HTMLElementBase {
         stats: this._stats,
         profile: this._profile,
         annotations: this._annotations,
+        volshading: this._volshade
+          ? `${this._volshade.p1}/${this._volshade.p2}`
+          : false,
         indicators: ind.join(' '),
         view: range ? { from: range.from, to: range.to } : null,
         positions: this._positions.map((p) => ({
@@ -599,6 +644,8 @@ class HabChart extends HTMLElementBase {
       if (typeof state.stats === 'boolean') this.setAttribute('stats', String(state.stats));
       if (typeof state.profile === 'boolean') this.setAttribute('profile', String(state.profile));
       if (typeof state.annotations === 'boolean') this.setAttribute('annotations', String(state.annotations));
+      if (state.volshading === true) this.setAttribute('volshading', 'true');
+      else if (typeof state.volshading === 'string' && state.volshading) this.setAttribute('volshading', state.volshading);
       if (typeof state.label === 'string') this.setAttribute('label', state.label);
       if (typeof state.indicators === 'string') {
         this.setAttribute('indicators', state.indicators);
@@ -889,6 +936,23 @@ class HabChart extends HTMLElementBase {
       return this._cache.map.__rsi14;
     }
 
+    /** Volatility-regime data (realized vol + percentile bands), cached per data version. */
+    _volShadeCache() {
+      if (!this._volshade) return null;
+      if (this._cache.v !== this._version) {
+        this._cache = { v: this._version, map: {} };
+      }
+      if (!this._cache.map.__volshade) {
+        const closes = this._data.map((b) => b.close);
+        const vol = calcRealizedVol(closes, this._volshade.period);
+        this._cache.map.__volshade = {
+          vol,
+          ...volRegimeBands(vol, this._volshade.p1, this._volshade.p2),
+        };
+      }
+      return this._cache.map.__volshade;
+    }
+
     /** Compute (and cache per data version) an indicator entry's series. */
     _indicatorSeries(entry) {
       if (this._cache.v !== this._version) {
@@ -1288,6 +1352,32 @@ class HabChart extends HTMLElementBase {
       }
       ctx.stroke();
 
+      /* volatility-regime shading (behind everything but the grid) */
+      if (this._volshade) {
+        const vs = this._volShadeCache();
+        if (vs) {
+          const flushRun = (val, a, b) => {
+            if (val !== 0 && val !== 2) return;
+            const xa = clamp(this._xFor(a) - sp * 0.5, 0, plotRight);
+            const xb = clamp(this._xFor(b) + sp * 0.5, 0, plotRight);
+            if (xb <= xa) return;
+            ctx.fillStyle = val === 0 ? hexToRgba(pal.accent, 0.05) : hexToRgba(pal.down, 0.07);
+            ctx.fillRect(xa, main.y0, xb - xa, main.h);
+          };
+          let runVal = -2;
+          let runA = i0;
+          for (let i = i0; i <= i1; i++) {
+            const rv = vs.regimes[i] == null ? -1 : vs.regimes[i];
+            if (rv !== runVal) {
+              flushRun(runVal, runA, i - 1);
+              runVal = rv;
+              runA = i;
+            }
+          }
+          flushRun(runVal, runA, i1);
+        }
+      }
+
       /* position zones (under series) */
       for (const pos of this._positions) {
         const yE = clamp(yOf(pos.entry), main.y0, main.y1);
@@ -1825,21 +1915,21 @@ class HabChart extends HTMLElementBase {
           ctx.fillText(fmtV(g), W - 6, pyOf(g));
         }
 
-        // pane label + live values
+        // pane label + live values (script panes show their expression label)
         const hi = this._hover ? clamp(this._hover.index, 0, d.length - 1) : d.length - 1;
         const vals = res.lines
           .map((ln) => (isNum(ln.values[hi]) ? fmtV(ln.values[hi]) : '—'))
           .join('  ');
+        const paneLabel =
+          (entry.name === 'expr' || entry.name === 'pexpr') && res.lines[0] && res.lines[0].name
+            ? res.lines[0].name
+            : `${entry.name.toUpperCase()} ${Object.values(entry.params).join(' ')}`;
         ctx.font = axisFont(600);
         ctx.fillStyle = pal.text;
         ctx.textAlign = 'left';
         ctx.textBaseline = 'top';
         ctx.globalAlpha = 0.9;
-        ctx.fillText(
-          `${entry.name.toUpperCase()} ${Object.values(entry.params).join(' ')}${vals ? '   ' + vals : ''}`,
-          8,
-          pr.y0 + 5
-        );
+        ctx.fillText(`${paneLabel}${vals ? '   ' + vals : ''}`, 8, pr.y0 + 5);
         ctx.globalAlpha = 1;
       }
 
@@ -2103,7 +2193,8 @@ class HabChart extends HTMLElementBase {
       const idx = clamp(hoverIdx, 0, d.length - 1);
       const key = [
         idx, this._version, this._type, this._label, this._theme,
-        this.getAttribute('indicators'), this._positions.length, this._posVersion || 0,
+        this.getAttribute('indicators'), this.getAttribute('volshading'),
+        this._positions.length, this._posVersion || 0,
       ].join('|');
       if (key === this._legendKey) return;
       this._legendKey = key;
@@ -2143,12 +2234,29 @@ class HabChart extends HTMLElementBase {
         const vals = res.lines
           .map((ln) => (isNum(ln.values[idx]) ? f.format(ln.values[idx]) : '—'))
           .join('  ');
-        html +=
-          `<div class="row"><span class="ind">` +
-          `<i style="background:${dotColor}"></i>${entry.name.toUpperCase()} ${Object.values(entry.params).join(' ')}` +
-          `</span><span class="v">${vals}</span></div>`;
+        // script indicators carry their expression in the line name; built-ins show name+params
+        const label =
+          (entry.name === 'expr' || entry.name === 'pexpr') && res.lines[0].name
+            ? esc(res.lines[0].name)
+            : `${entry.name.toUpperCase()} ${Object.values(entry.params).join(' ')}`;
+        html += `<div class="row"><span class="ind"><i style="background:${dotColor}"></i>${label}</span><span class="v">${vals}</span></div>`;
       });
 
+      if (this._volshade) {
+        const vs = this._volShadeCache();
+        const rv = vs ? vs.regimes[idx] : -1;
+        if (vs && rv >= 0) {
+          const pct = percentileOfSorted(vs.sorted, vs.vol[idx]);
+          const name = rv === 0 ? 'calm' : rv === 2 ? 'hot' : 'normal';
+          const dot = rv === 0 ? palNow.accent : rv === 2 ? palNow.down : palNow.text;
+          html +=
+            `<div class="row"><span class="ind">` +
+            `<i style="background:${dot}"></i>VOL ${this._volshade.p1}/${this._volshade.p2} · ${name}` +
+            `${isNum(pct) ? ` · ${pct.toFixed(0)}%ile` : ''}` +
+            `</span></div>`;
+        }
+      }
+
       if (this._annotations && this._annoList) {
         const notes = this._annoList.filter((a) => a.i === idx).map((a) => a.note);
         if (notes.length) {

package/types/core.d.ts

@@ -263,6 +263,12 @@ export declare function calcEMASparse(values: Array<number | null>, period: numb
 export declare function calcRSI(closes: number[], period: number): Array<number | null>;
 /** Rolling standard deviation (population) over `period`, aligned like SMA. */
 export declare function calcStdDev(values: any, period: any): any[];
+/** Linear-weighted moving average (most recent bar weighs `period`), aligned like SMA.
+ * @param {number[]} values
+ * @param {number} period
+ * @returns {Array<number|null>}
+ */
+export declare function calcWMA(values: number[], period: number): Array<number | null>;
 /**
  * Bollinger Bands.
  * @param {number[]} closes
@@ -505,7 +511,8 @@ export declare const BUILTIN_INDICATORS: Map<string, {
 }>;
 /**
  * Parse an `indicators` attribute string against a registry.
- * Token: `name[:param[/param…]][@color]`, plus the `volume` keyword.
+ * Token: `name[:param[/param…]][@color]`, the `volume` keyword, and
+ * HabScript blobs `expr:{…}` (overlay) / `pexpr:{…}` (separate pane).
  * @param {string|null|undefined} str
  * @param {Map<string, IndicatorDef>} registry
  * @returns {{overlays: IndicatorEntry[], panes: IndicatorEntry[], volume: boolean, unknown: string[]}}
@@ -516,6 +523,46 @@ export declare function parseIndicators(str: string | null | undefined, registry
     volume: boolean;
     unknown: string[];
 };
+/**
+ * Split an indicators string into tokens, keeping `expr:{…}` / `pexpr:{…}`
+ * blobs atomic — spaces and commas inside the braces are preserved, and an
+ * optional `@color` suffix directly after `}` stays attached.
+ * Separators are whitespace, `,` and `;`.
+ * @param {string|null|undefined} str
+ * @returns {string[]}
+ */
+export declare function splitIndicatorTokens(str: string | null | undefined): string[];
+/**
+ * Compile a HabScript expression. Throws a descriptive error on any syntax
+ * or semantic problem — never evaluates strings at runtime.
+ * @param {string} src
+ * @returns {{src: string, ast: object}}
+ */
+export declare function compileScript(src: string): {
+    src: string;
+    ast: object;
+};
+/**
+ * Evaluate a compiled script (or a raw expression string) over bars.
+ * @param {{src:string, ast:object}|string} compiled
+ * @param {Bar[]} bars
+ * @returns {number[]} length `bars.length`; non-finite values become NaN
+ */
+export declare function evalScript(compiled: {
+    src: string;
+    ast: object;
+} | string, bars: Bar[]): number[];
+/**
+ * Build an indicator definition from a HabScript expression — used inline by
+ * `indicators="expr:{…}"` / `pexpr:{…}"`, or register it under a name:
+ * `HabChart.registerIndicator('myspread', scriptIndicator('close - ema(close,21)'))`.
+ * @param {string} src
+ * @param {{pane?: boolean}} [opts]
+ * @returns {IndicatorDef}
+ */
+export declare function scriptIndicator(src: string, opts?: {
+    pane?: boolean;
+}): IndicatorDef;
 /**
  * Unrealized P&L of a position at `price`.
  * @param {{side?: 'long'|'short', entry: number, qty?: number}} pos
@@ -557,6 +604,66 @@ export declare function computeStats(bars: Bar[], i0: number, i1: number, dtMs:
     dn: number;
     avgVolume: number;
 };
+/**
+ * Rolling realized volatility: population stddev of log returns over the
+ * last `period` bars (per-bar value, aligned like SMA — null until the
+ * window fills).
+ * @param {number[]} closes
+ * @param {number} [period=20]
+ * @returns {Array<number|null>}
+ */
+export declare function calcRealizedVol(closes: number[], period?: number): Array<number | null>;
+/**
+ * Classify a realized-vol series into regimes by empirical percentile over
+ * the whole series: 0 = calm (≤ qLow), 1 = normal, 2 = hot (≥ qHigh),
+ * -1 = unknown (null input). A degenerate spread (qHigh ≤ qLow, e.g. a
+ * flat series) classifies everything as normal.
+ * @param {Array<number|null>} vol
+ * @param {number} [qLow=30]
+ * @param {number} [qHigh=70]
+ * @returns {{regimes:number[], sorted:number[], q1:number, q2:number}}
+ */
+export declare function volRegimeBands(vol: Array<number | null>, qLow?: number, qHigh?: number): {
+    regimes: number[];
+    sorted: number[];
+    q1: number;
+    q2: number;
+};
+/**
+ * Percentile (0–100) of `v` within an ascending `sorted` array.
+ * @param {number[]} sorted
+ * @param {number} v
+ * @returns {number}
+ */
+export declare function percentileOfSorted(sorted: number[], v: number): number;
+/**
+ * Parse a `volshading` attribute value: `""` / `"true"` → defaults (30/70,
+ * period 20); `"30/70"` custom cutoffs; `"30/70/14"` cutoffs + period.
+ * Inputs are clamped so qLow always stays at least 2 points below qHigh.
+ * @param {string|null|undefined} val
+ * @returns {{p1:number, p2:number, period:number}}
+ */
+export declare function parseVolShading(val: string | null | undefined): {
+    p1: number;
+    p2: number;
+    period: number;
+};
+export declare const tfLabelOf: (dtMs: any) => string;
+/**
+ * Compact, LLM-friendly summary of a bar window: structured fields plus a
+ * ready-to-paste markdown rendering (`text`). Built entirely from local
+ * data — nothing leaves the page until the user pastes it somewhere.
+ *
+ * @param {Bar[]} bars full dataset
+ * @param {number} i0 first index of the window
+ * @param {number} i1 last index of the window
+ * @param {{dtMs?: number, label?: string}} [opts] bar spacing (ms) + chart label
+ * @returns {object|null} null when the window is empty or out of range
+ */
+export declare function windowSummary(bars: Bar[], i0: number, i1: number, opts?: {
+    dtMs?: number;
+    label?: string;
+}): object | null;
 /**
  * Encode a chart state (from getState()) as a compact query string.
  * View times are encoded in whole seconds.

package/types/hab-chart.d.ts

@@ -93,6 +93,11 @@ declare class HabChart extends HTMLElementBase {
         i: number;
         note: string;
     }[];
+    _volshade: {
+        p1: number;
+        p2: number;
+        period: number;
+    };
     _coviewName: any;
     _coviewCh: BroadcastChannel;
     _coviewPeer: string;
@@ -228,6 +233,13 @@ declare class HabChart extends HTMLElementBase {
     }): void;
     /** Current canvas as a PNG data URL. */
     exportPNG(): any;
+    /**
+     * AI-ready summary of the visible window: structured fields plus a
+     * ready-to-paste markdown rendering (`text`). Computed locally —
+     * nothing leaves the page until the user copies it somewhere.
+     * @returns {object|null}
+     */
+    getDataWindow(): object | null;
     /**
      * Serializable snapshot of the chart's configuration and view.
      * Feed it to setState() (or encodeStateQuery for shareable URLs).
@@ -313,6 +325,8 @@ declare class HabChart extends HTMLElementBase {
     _renderBars(): any;
     /** RSI(14) over raw closes, cached per data version (annotation input). */
     _cachedRSI14(): any;
+    /** Volatility-regime data (realized vol + percentile bands), cached per data version. */
+    _volShadeCache(): any;
     /** Compute (and cache per data version) an indicator entry's series. */
     _indicatorSeries(entry: any): any;
     /** Resolve a line color: #hex / rgb() / CSS name / palette key ('rsi', 'up', …) / cycle.