wickchart 0.4.0 → 1.2.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

@@ -512,7 +512,7 @@ export declare const BUILTIN_INDICATORS: Map<string, {
 /**
  * Parse an `indicators` attribute string against a registry.
  * Token: `name[:param[/param…]][@color]`, the `volume` keyword, and
- * HabScript blobs `expr:{…}` (overlay) / `pexpr:{…}` (separate pane).
+ * 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[]}}
@@ -533,7 +533,7 @@ export declare function parseIndicators(str: string | null | undefined, registry
  */
 export declare function splitIndicatorTokens(str: string | null | undefined): string[];
 /**
- * Compile a HabScript expression. Throws a descriptive error on any syntax
+ * 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}}
@@ -553,7 +553,7 @@ export declare function evalScript(compiled: {
     ast: object;
 } | string, bars: Bar[]): number[];
 /**
- * Build an indicator definition from a HabScript expression — used inline by
+ * 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
@@ -585,6 +585,28 @@ export declare function checkAlertCross(alert: {
     price: number;
     direction?: 'above' | 'below' | 'cross';
 }, prevPrice: number, price: number): boolean;
+/**
+ * Boolean truth series for a WickScript predicate: any numeric expression
+ * where nonzero & finite counts as true (NaN / 0 / ±Infinity → false).
+ * Powers scripted alerts — `addAlert({ when: 'crossup(close, sma(close,50))' })`.
+ * @param {object|string} compiled compiled predicate (or raw source)
+ * @param {Bar[]} bars
+ * @returns {boolean[]}
+ */
+export declare function predicateTrueSeries(compiled: object | string, bars: Bar[]): boolean[];
+/**
+ * Edge-triggered step for a scripted alert. `armed` starts true; a rising
+ * edge (false → true) fires once and disarms; a true → false transition
+ * re-arms, so `once: false` alerts can fire again on the next edge while
+ * `once: true` alerts are removed after their first fire.
+ * @param {boolean} armed
+ * @param {boolean} curTrue
+ * @returns {{ fire: boolean, armed: boolean }}
+ */
+export declare function scriptAlertStep(armed: boolean, curTrue: boolean): {
+    fire: boolean;
+    armed: boolean;
+};
 /**
  * Statistics over a visible slice of bars.
  * @param {Bar[]} bars
@@ -648,6 +670,83 @@ export declare function parseVolShading(val: string | null | undefined): {
     p2: number;
     period: number;
 };
+/**
+ * Index of the last bar whose time is <= `t` (binary search). Clamps to
+ * [0, n-1]: a time before the first bar → 0, past the last bar → n-1.
+ * Empty bars or a non-numeric time → null.
+ * @param {object[]} bars normalized bar objects
+ * @param {number} t timestamp in ms or s
+ * @returns {number|null}
+ */
+export declare function barIndexForTime(bars: object[], t: number): number | null;
+/**
+ * Validate & normalize server-side overlay definitions. Overlays are data
+ * from an API, so invalid entries are silently dropped — never thrown.
+ *
+ * zone:  { type:'zone', from?: time|null, to?: time|null, priceFrom, priceTo,
+ *          color?, alpha?, border?, label?, id? } — a time×price rectangle.
+ *          `from`/`to` omitted (or null) anchor to the left/right chart edge;
+ *          a zone with no `to` extends into future space past the last bar.
+ * level: { type:'level', price, from?, to?, color?, width?, dash?, label?, id? }
+ *          — a horizontal price line, full width by default.
+ *
+ * Colors go through safeColor(); `alpha` clamps to [0.02, 0.8] (default 0.22).
+ * @param {any} list
+ * @returns {object[]} normalized overlays (possibly empty)
+ */
+export declare function normalizeOverlays(list: any): object[];
+/**
+ * Resolve an overlay color against the active palette: 'up'/'down'/'accent'
+ * map to theme colors, anything else passes through safeColor(), and invalid
+ * or missing values fall back to the accent color.
+ * @param {any} raw
+ * @param {object} pal active theme palette
+ * @returns {string} a concrete CSS color
+ */
+export declare function resolveOverlayColor(raw: any, pal: object): string;
+/**
+ * σ-cone projection from realized per-bar volatility: price bands widening
+ * with √h (GBM-style, exp(±z·σ·√h)) over `horizon` future bars.
+ * @param {number} lastClose anchor price (bar 0)
+ * @param {number} volPerBar per-bar stddev of log returns (from calcRealizedVol)
+ * @param {number} horizon future bars (clamped 1–500, default 48)
+ * @param {number[]} [levels] σ multipliers, e.g. [1, 2] (each clamped to 0–5)
+ * @returns {{horizon: number, levels: number[], bands: Record<string, {up: number[], down: number[]}>}}
+ *          bands[z].up/.down are arrays indexed by h = 0…horizon ([0] === lastClose)
+ */
+export declare function calcVolCone(lastClose: number, volPerBar: number, horizon: number, levels?: number[]): {
+    horizon: number;
+    levels: number[];
+    bands: Record<string, {
+        up: number[];
+        down: number[];
+    }>;
+};
+/**
+ * Validate a scenario spec: a ghost path of future prices (bars or API data)
+ * plus optional cone settings. Invalid entries are dropped, never thrown.
+ *
+ *   { path: [64000, 65500, {price: 68000}],  // future bars 1..N
+ *     horizon: 48,          // alternative/additional: cone-only projection
+ *     cone: true,           // σ-bands from realized vol (default true)
+ *     levels: [1, 2],       // σ multipliers (default [1, 2])
+ *     color?, label? }      // palette keys up|down|accent or safe CSS colors
+ *
+ * @param {any} spec
+ * @returns {null|{path: {h:number, price:number}[], horizon: number,
+ *            cone: boolean, levels: number[], color: string|null, label: string}}
+ */
+export declare function normalizeScenario(spec: any): null | {
+    path: {
+        h: number;
+        price: number;
+    }[];
+    horizon: number;
+    cone: boolean;
+    levels: number[];
+    color: string | null;
+    label: string;
+};
 export declare const tfLabelOf: (dtMs: any) => string;
 /**
  * Compact, LLM-friendly summary of a bar window: structured fields plus a
@@ -677,3 +776,110 @@ export declare function encodeStateQuery(state: ChartState | null): string;
  * @returns {ChartState}
  */
 export declare function decodeStateQuery(str: string): ChartState;
+/**
+ * Tool manifest for LLM/agent control of a chart. Tools map 1:1 onto the
+ * public element API; every op through applyChartOps is validated before it
+ * touches the chart (LLM output is untrusted input).
+ */
+export declare const AI_TOOLS: ({
+    tool: string;
+    description: string;
+    args: {
+        indicators?: undefined;
+        overlays?: undefined;
+        from?: undefined;
+        to?: undefined;
+        type?: undefined;
+        enabled?: undefined;
+        low?: undefined;
+        high?: undefined;
+    };
+} | {
+    tool: string;
+    description: string;
+    args: {
+        indicators: string;
+        overlays?: undefined;
+        from?: undefined;
+        to?: undefined;
+        type?: undefined;
+        enabled?: undefined;
+        low?: undefined;
+        high?: undefined;
+    };
+} | {
+    tool: string;
+    description: string;
+    args: {
+        indicators?: undefined;
+        overlays: string;
+        from?: undefined;
+        to?: undefined;
+        type?: undefined;
+        enabled?: undefined;
+        low?: undefined;
+        high?: undefined;
+    };
+} | {
+    tool: string;
+    description: string;
+    args: {
+        indicators?: undefined;
+        overlays?: undefined;
+        from: string;
+        to: string;
+        type?: undefined;
+        enabled?: undefined;
+        low?: undefined;
+        high?: undefined;
+    };
+} | {
+    tool: string;
+    description: string;
+    args: {
+        indicators?: undefined;
+        overlays?: undefined;
+        from?: undefined;
+        to?: undefined;
+        type: string;
+        enabled?: undefined;
+        low?: undefined;
+        high?: undefined;
+    };
+} | {
+    tool: string;
+    description: string;
+    args: {
+        indicators?: undefined;
+        overlays?: undefined;
+        from?: undefined;
+        to?: undefined;
+        type?: undefined;
+        enabled: string;
+        low: string;
+        high: string;
+    };
+})[];
+/**
+ * Compact system prompt for agent control: paste into any LLM alongside the
+ * tool manifest. The model answers with a JSON array of {tool, args} ops.
+ * @returns {string}
+ */
+export declare function aiPromptText(): string;
+/**
+ * Validate + apply a list of {tool, args} ops (typically LLM output) to a
+ * chart-like target. Ops are whitelisted and their args validated — an op
+ * never throws; it returns {ok: false, error} instead so the agent can
+ * self-correct. Target contract: getDataWindow(), setAttribute(k, v),
+ * setOverlays(list), clearOverlays(), addAlert(a), setVisibleRange(r),
+ * fit(), and (static) _registry() for indicator name checks.
+ * @param {object} target chart element (or test double)
+ * @param {any} ops
+ * @returns {Array<{ok: boolean, tool?: string, result?: any, error?: string}>}
+ */
+export declare function applyChartOps(target: object, ops: any): Array<{
+    ok: boolean;
+    tool?: string;
+    result?: any;
+    error?: string;
+}>;

package/types/react-core.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Map an event shorthand to the dispatched event name.
+ * "range" / "wick:range" → "wick:range" (the 0.x "hab:" prefix is no longer emitted).
+ * @param {string} name
+ * @returns {string}
+ */
+export declare const toWickEventName: (name: string) => string;
+/**
+ * camelCase prop name → kebab-case attribute name ("volShading" → "vol-shading").
+ * @param {string} key
+ * @returns {string}
+ */
+export declare const toAttrName: (key: string) => string;
+/**
+ * Split React props into chart attrs / event handlers / DOM passthrough /
+ * the data array / the overlays array.
+ * @param {object} props
+ * @returns {{ attrs: object, events: Record<string, Function>, dom: object, data: any, overlays: any }}
+ */
+export declare function splitChartProps(props: object): {
+    attrs: object;
+    events: Record<string, Function>;
+    dom: object;
+    data: any;
+    overlays: any;
+};
+/**
+ * Apply split props to a chart element. Every write is guarded so re-running
+ * with identical values is a no-op (attributes compared as strings, `data`
+ * and `overlays` compared by identity — passing a fresh array is what
+ * triggers a redraw).
+ * @param {HTMLElement} el
+ * @param {{ attrs?: object, data?: any, overlays?: any }} split
+ */
+export declare function applyChartProps(el: HTMLElement, split: {
+    attrs?: object;
+    data?: any;
+    overlays?: any;
+}): void;
+/**
+ * Full control hook: renders nothing — attach the returned ref to your own
+ * <wick-chart> element and pass the same options you would give the component.
+ *
+ *   const { ref, chart } = useWickChart({ data: bars, indicators: 'sma:20', onRange });
+ *   return <wick-chart ref={ref} style={{ height: 420 }} />;
+ *   // chart.getDataWindow() etc. once mounted
+ *
+ * @param {object} [options] any <wick-chart> attribute, plus `data`, `events`
+ *   and `onXxx`-style handlers (see splitChartProps).
+ * @returns {{ ref: (node: any) => void, chart: any }} `chart` is the element
+ *   instance (or null before mount) for the imperative API.
+ */
+export declare function useWickChart(options?: object): {
+    ref: (node: any) => void;
+    chart: any;
+};
+/**
+ * Drop-in React component for <wick-chart>. Attributes ride through
+ * createElement (so they exist at first paint and in SSR output) while the
+ * hook keeps them in sync on updates; `data` and event handlers never touch
+ * React's prop pipeline. Works the same on React 16.8 → 19.
+ */
+export declare const WickChart: import("react").ForwardRefExoticComponent<import("react").RefAttributes<any>>;
+export default WickChart;

package/types/react.d.ts

@@ -0,0 +1,3 @@
+import './wick-chart.js';
+export { WickChart, useWickChart, splitChartProps, applyChartProps, toWickEventName, toAttrName, } from './react-core.js';
+export { default } from './react-core.js';