wickchart 0.3.0 → 1.0.0

package/src/{hab-feed.js → wick-feed.js}

@@ -1,10 +1,10 @@
 /* ==========================================================================
- * <hab-feed> — declarative data feeds for <hab-chart>.
+ * <wick-feed> — declarative data feeds for <wick-chart>.
  *
- *   <script type="module" src="https://unpkg.com/hab-view/feed"></script>
+ *   <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"></hab-chart>
+ *   <wick-feed for="chart" binance="BTCUSDT" tf="1h"></wick-feed>
+ *   <wick-chart id="chart" indicators="sma:20 volume"></wick-chart>
  *
  * A fully live chart with zero JavaScript written. Sources:
  *   binance="SYMBOL"  live via WebSocket (REST klines + backfill; falls back
@@ -17,11 +17,12 @@
  * Attributes: for (chart id; auto-pairs with the first chart otherwise),
  *   tf (1m…1w), limit (initial bars, default 500), live="false" to disable
  *   streaming. Status is reflected in the `status` attribute and via
- *   `hab-feed:status` events (loading / live / polling / fallback / loaded /
- *   waiting / idle). `hab-feed:fallback` fires when a live source degrades.
+ *   `wick-feed:status` events (loading / live / polling / fallback / loaded /
+ *   waiting / idle). `wick-feed:fallback` fires when a live source degrades.
+ *   (The 0.x event names `hab-feed:*` still fire as deprecated aliases.)
  * ========================================================================== */
 
-import './hab-chart.js';
+import './wick-chart.js';
 import {
   genSynthetic,
   makeSynthStream,
@@ -35,7 +36,7 @@ const LIVE_TICK_MS = 650;
 
 const HTMLElementBase = typeof HTMLElement !== 'undefined' ? HTMLElement : class {};
 
-class HabFeed extends HTMLElementBase {
+class WickFeed extends HTMLElementBase {
   static get observedAttributes() {
     return ['for', 'binance', 'demo', 'url', 'tf', 'limit', 'poll', 'live'];
   }
@@ -86,17 +87,24 @@ class HabFeed extends HTMLElementBase {
   _setStatus(status, detail) {
     if (!this.isConnected) return;
     this.setAttribute('status', status);
-    this.dispatchEvent(new CustomEvent('hab-feed:status', { detail: { status, ...detail } }));
+    this._fire('status', { status, ...detail });
   }
 
-  /** Resolve the target chart (by `for` id, else the first <hab-chart>). */
+  /** Dispatch `wick-feed:name` plus the deprecated `hab-feed:name` alias. */
+  _fire(name, detail) {
+    this.dispatchEvent(new CustomEvent('wick-feed:' + name, { detail }));
+    this.dispatchEvent(new CustomEvent('hab-feed:' + name, { detail }));
+  }
+
+  /** Resolve the target chart (by `for` id, else the first chart element —
+   *  <wick-chart> or the deprecated <hab-chart>). */
   _resolveChart() {
     const id = this.getAttribute('for');
     if (id) {
       const el = document.getElementById(id);
-      return el && el.tagName === 'HAB-CHART' ? el : null;
+      return el && (el.tagName === 'WICK-CHART' || el.tagName === 'HAB-CHART') ? el : null;
     }
-    return document.querySelector('hab-chart');
+    return document.querySelector('wick-chart') || document.querySelector('hab-chart');
   }
 
   _restart() {
@@ -105,7 +113,7 @@ class HabFeed extends HTMLElementBase {
     if (!chart || typeof chart.setData !== 'function') {
       // chart not in the DOM yet (or not upgraded) — watch for it
       this._setStatus('waiting');
-      customElements.whenDefined('hab-chart').then(() => {
+      customElements.whenDefined('wick-chart').then(() => {
         if (!this.isConnected) return;
         this._observer = this._observer || new MutationObserver(() => {
           const c = this._resolveChart();
@@ -208,9 +216,7 @@ class HabFeed extends HTMLElementBase {
   }
 
   _degrade(gen, chart, sym, tfId, limit, live, err) {
-    this.dispatchEvent(
-      new CustomEvent('hab-feed:fallback', { detail: { reason: err && err.message } })
-    );
+    this._fire('fallback', { reason: err && err.message });
     this._synthetic(gen, chart, sym, tfId, limit, live, 'fallback');
   }
 
@@ -248,8 +254,17 @@ class HabFeed extends HTMLElementBase {
   }
 }
 
-if (typeof customElements !== 'undefined' && !customElements.get('hab-feed')) {
-  customElements.define('hab-feed', HabFeed);
+if (typeof customElements !== 'undefined') {
+  if (!customElements.get('wick-feed')) {
+    customElements.define('wick-feed', WickFeed);
+  }
+  // 0.x alias: same element under its old tag name (deprecated, removed in 2.0)
+  if (!customElements.get('hab-feed')) {
+    /** @deprecated use <wick-feed> */
+    class HabFeed extends WickFeed {}
+    customElements.define('hab-feed', HabFeed);
+  }
 }
 
-export default HabFeed;
+export default WickFeed;
+export { WickFeed };

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
+ * WickScript 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 WickScript 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 WickScript 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 → wick-chart.d.ts}

@@ -1,7 +1,7 @@
 declare const HTMLElementBase: {
     new (): {};
 };
-declare class HabChart extends HTMLElementBase {
+declare class WickChart extends HTMLElementBase {
     _canvas: any;
     _ctx: any;
     _legend: any;
@@ -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;
@@ -167,13 +172,93 @@ declare class HabChart extends HTMLElementBase {
     connectedCallback(): void;
     disconnectedCallback(): void;
     attributeChangedCallback(name: any, _old: any, val: any): void;
-    static _registryMap: any;
-    /** Lazily-built registry, seeded with the built-in indicators. */
-    static _registry(): any;
+    /** Indicator registry (module scope — shared with the legacy alias tag). */
+    static _registry(): Map<string, {
+        kind: string;
+        params: {
+            period: number;
+            mult?: undefined;
+            fast?: undefined;
+            slow?: undefined;
+            signal?: undefined;
+        };
+        compute: (bars: any, p: any) => number[];
+        range?: undefined;
+        color?: undefined;
+        guides?: undefined;
+        fmt?: undefined;
+    } | {
+        kind: string;
+        params: {
+            period: number;
+            mult?: undefined;
+            fast?: undefined;
+            slow?: undefined;
+            signal?: undefined;
+        };
+        compute: (bars: any, p: any) => number[];
+        range?: undefined;
+        color?: undefined;
+        guides?: undefined;
+        fmt?: undefined;
+    } | {
+        kind: string;
+        params: {
+            period: number;
+            mult: number;
+            fast?: undefined;
+            slow?: undefined;
+            signal?: undefined;
+        };
+        compute: (bars: any, p: any) => {
+            lines: {
+                name: string;
+                values: number[];
+            }[];
+        };
+        range?: undefined;
+        color?: undefined;
+        guides?: undefined;
+        fmt?: undefined;
+    } | {
+        kind: string;
+        params: {
+            mult?: undefined;
+            period: number;
+            fast?: undefined;
+            slow?: undefined;
+            signal?: undefined;
+        };
+        guides: number[];
+        range: number[];
+        fmt: string;
+        color: string;
+        compute: (bars: any, p: any) => number[];
+    } | {
+        range?: undefined;
+        color?: undefined;
+        kind: string;
+        params: {
+            mult?: undefined;
+            period?: undefined;
+            fast: number;
+            slow: number;
+            signal: number;
+        };
+        guides: number[];
+        fmt: string;
+        compute: (bars: any, p: any) => {
+            lines: {
+                name: string;
+                values: number[];
+            }[];
+            histogram: number[];
+        };
+    }>;
     /**
      * Register a custom indicator.
      *
-     *   HabChart.registerIndicator('vwap', {
+     *   WickChart.registerIndicator('vwap', {
      *     kind: 'overlay',                    // or 'pane'
      *     params: { period: 20 },             // defaults; settable via name:period
      *     compute(bars, params) {             // bars: normalized {time,o,h,l,c,v}
@@ -228,6 +313,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).
@@ -257,7 +349,8 @@ declare class HabChart extends HTMLElementBase {
     removePosition(id: any): void;
     clearPositions(): void;
     /**
-     * Price alert. Fires `hab:alert` ({id, price, bar}) on an edge crossing
+     * Price alert. Fires `wick:alert` ({id, price, bar}) on an edge crossing
+     * (plus the deprecated `hab:alert` alias)
      * during streaming updates.
      * @param {{id?: string, price: number, direction?: 'above'|'below'|'cross',
      *          once?: boolean}} alert
@@ -313,6 +406,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.
@@ -372,6 +467,10 @@ declare class HabChart extends HTMLElementBase {
     _setupCoView(): void;
     _coviewSend(msg: any): void;
     _onCoMessage(m: any): void;
+    /** Dispatch `wick:name` (canonical) plus the deprecated `hab:name` alias,
+     *  so 0.x listeners keep working until 2.0. */
+    _fire(name: any, detail: any): void;
     _emitRange(): void;
 }
-export default HabChart;
+export default WickChart;
+export { WickChart };

package/types/{hab-feed.d.ts → wick-feed.d.ts}

@@ -1,8 +1,8 @@
-import './hab-chart.js';
+import './wick-chart.js';
 declare const HTMLElementBase: {
     new (): {};
 };
-declare class HabFeed extends HTMLElementBase {
+declare class WickFeed extends HTMLElementBase {
     _gen: number;
     _closers: any[];
     _timer: number;
@@ -15,7 +15,10 @@ declare class HabFeed extends HTMLElementBase {
     _scheduleRestart(): void;
     _teardown(): void;
     _setStatus(status: any, detail: any): void;
-    /** Resolve the target chart (by `for` id, else the first <hab-chart>). */
+    /** Dispatch `wick-feed:name` plus the deprecated `hab-feed:name` alias. */
+    _fire(name: any, detail: any): void;
+    /** Resolve the target chart (by `for` id, else the first chart element —
+     *  <wick-chart> or the deprecated <hab-chart>). */
     _resolveChart(): Element;
     _restart(): void;
     _synthetic(gen: any, chart: any, key: any, tfId: any, limit: any, live: any, status?: string): void;
@@ -24,4 +27,5 @@ declare class HabFeed extends HTMLElementBase {
     _degrade(gen: any, chart: any, sym: any, tfId: any, limit: any, live: any, err: any): void;
     _rest(gen: any, chart: any, url: any, limit: any, live: any): Promise<void>;
 }
-export default HabFeed;
+export default WickFeed;
+export { WickFeed };