wickchart 0.4.0 → 1.2.0

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

@@ -1,16 +1,19 @@
 /* ==========================================================================
- * <hab-chart> — a modern, dependency-free financial charting web component.
+ * <wick-chart> — a modern, dependency-free financial charting web component.
  *
- *   <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);        // streaming update / append
  *   </script>
  *
  * Zero dependencies. Canvas-rendered. Framework-agnostic (works in React,
- * Vue, Svelte, plain HTML). Themeable with --hab-* CSS custom properties.
+ * Vue, plain HTML). Themeable with --wick-* CSS custom properties.
+ *
+ * The 0.x names (<hab-chart>, --hab-*, hab:* events) still work as
+ * deprecated aliases — see the README migration notes.
  *
  * MIT License.
  * ========================================================================== */
@@ -25,20 +28,27 @@ import {
   SERIES_TYPES, calcHeikinAshi, buildColumns, computeVolumeProfile,
   calcRSI, detectAnnotations, priceToFreq,
   calcRealizedVol, volRegimeBands, percentileOfSorted, parseVolShading,
-  windowSummary,
+  windowSummary, normalizeOverlays, barIndexForTime, resolveOverlayColor,
+  compileScript, predicateTrueSeries, scriptAlertStep,
+  AI_TOOLS, aiPromptText, applyChartOps,
+  calcVolCone, normalizeScenario,
 } from './core.js';
 
 /* ------------------------------------------------------------------ *
- * <hab-chart>
+ * <wick-chart>
  * ------------------------------------------------------------------ */
 
+/** Indicator registry — module scope so registrations are shared by
+ *  <wick-chart> and the deprecated <hab-chart> alias element. */
+const REGISTRY = new Map(BUILTIN_INDICATORS);
+
   /* SSR safety: importing this module under Node (Next.js/Nuxt server render)
  * must not throw — the element simply registers only in browsers. */
 const HTMLElementBase = typeof HTMLElement !== 'undefined' ? HTMLElement : class {};
 
-class HabChart extends HTMLElementBase {
+class WickChart extends HTMLElementBase {
     static get observedAttributes() {
-      return ['theme', 'type', 'log', 'auto', 'indicators', 'precision', 'label', 'stats', 'profile', 'annotations', 'volshading', 'co-view', 'sonify'];
+      return ['theme', 'type', 'log', 'auto', 'indicators', 'precision', 'label', 'stats', 'profile', 'annotations', 'volshading', 'overlays', 'co-view', 'sonify'];
     }
 
     constructor() {
@@ -55,7 +65,7 @@ class HabChart extends HTMLElementBase {
             contain: content;
           }
           :host(:focus-visible) {
-            outline: 2px solid var(--hab-accent, #4c8dff);
+            outline: 2px solid var(--wick-accent, var(--hab-accent, #4c8dff));
             outline-offset: -2px;
           }
           .wrap { position: absolute; inset: 0; overflow: hidden; }
@@ -78,26 +88,26 @@ class HabChart extends HTMLElementBase {
           }
           .legend .row { display: flex; align-items: baseline; gap: 12px; flex-wrap: wrap; }
           .legend .sym {
-            color: var(--hab-text-strong, #e6edf3);
+            color: var(--wick-text-strong, var(--hab-text-strong, #e6edf3));
             font-weight: 700;
             font-size: 13px;
             letter-spacing: 0.02em;
           }
           .legend .kv { display: inline-flex; gap: 5px; align-items: baseline; white-space: nowrap; }
-          .legend .k { color: var(--hab-text, #8b949e); font-size: 11px; }
-          .legend .v { color: var(--hab-text-strong, #e6edf3); font-weight: 600; font-variant-numeric: tabular-nums; white-space: nowrap; }
+          .legend .k { color: var(--wick-text, var(--hab-text, #8b949e)); font-size: 11px; }
+          .legend .v { color: var(--wick-text-strong, var(--hab-text-strong, #e6edf3)); font-weight: 600; font-variant-numeric: tabular-nums; white-space: nowrap; }
           .legend .pct { font-weight: 600; font-variant-numeric: tabular-nums; white-space: nowrap; }
-          .legend .up { color: var(--hab-up, #16c784); }
-          .legend .dn { color: var(--hab-down, #ea3943); }
+          .legend .up { color: var(--wick-up, var(--hab-up, #16c784)); }
+          .legend .dn { color: var(--wick-down, var(--hab-down, #ea3943)); }
           .legend .ind {
             display: inline-flex; align-items: center; gap: 6px;
-            color: var(--hab-text, #8b949e); font-size: 11.5px; white-space: nowrap;
+            color: var(--wick-text, var(--hab-text, #8b949e)); font-size: 11.5px; white-space: nowrap;
           }
           .legend .ind i { width: 8px; height: 2.5px; border-radius: 2px; display: inline-block; }
           .legend .ind .v { font-size: 12px; }
           .legend .insight {
-            color: var(--hab-accent, #4c8dff);
-            background: var(--hab-chip, rgba(127, 137, 153, 0.12));
+            color: var(--wick-accent, var(--hab-accent, #4c8dff));
+            background: var(--wick-chip, var(--hab-chip, rgba(127, 137, 153, 0.12)));
             border-radius: 6px;
             padding: 1px 8px;
             font-size: 11.5px;
@@ -106,7 +116,7 @@ class HabChart extends HTMLElementBase {
           .nodata {
             position: absolute; inset: 0;
             display: flex; align-items: center; justify-content: center;
-            color: var(--hab-text, #8b949e);
+            color: var(--wick-text, var(--hab-text, #8b949e));
             font: 500 13px ${FONT_STACK};
             pointer-events: none;
           }
@@ -119,25 +129,25 @@ class HabChart extends HTMLElementBase {
           }
           .hud .pos {
             display: inline-flex; gap: 9px; align-items: baseline; white-space: nowrap;
-            background: var(--hab-chip, rgba(127, 137, 153, 0.12));
-            border: 1px solid var(--hab-border, rgba(148, 163, 184, 0.2));
+            background: var(--wick-chip, var(--hab-chip, rgba(127, 137, 153, 0.12)));
+            border: 1px solid var(--wick-border, var(--hab-border, rgba(148, 163, 184, 0.2)));
             border-radius: 7px;
             padding: 3px 9px;
           }
           .hud .statsrow {
             display: inline-flex; gap: 12px; white-space: nowrap;
-            background: var(--hab-chip, rgba(127, 137, 153, 0.12));
-            border: 1px solid var(--hab-border, rgba(148, 163, 184, 0.2));
+            background: var(--wick-chip, var(--hab-chip, rgba(127, 137, 153, 0.12)));
+            border: 1px solid var(--wick-border, var(--hab-border, rgba(148, 163, 184, 0.2)));
             border-radius: 7px;
             padding: 3px 10px;
-            color: var(--hab-text, #8b949e);
+            color: var(--wick-text, var(--hab-text, #8b949e));
             font-variant-numeric: tabular-nums;
           }
-          .hud .statsrow b { color: var(--hab-text-strong, #e6edf3); font-weight: 600; }
-          .hud .k { color: var(--hab-text, #8b949e); font-weight: 500; }
-          .hud .v { color: var(--hab-text-strong, #e6edf3); font-variant-numeric: tabular-nums; }
-          .hud .up { color: var(--hab-up, #16c784); }
-          .hud .dn { color: var(--hab-down, #ea3943); }
+          .hud .statsrow b { color: var(--wick-text-strong, var(--hab-text-strong, #e6edf3)); font-weight: 600; }
+          .hud .k { color: var(--wick-text, var(--hab-text, #8b949e)); font-weight: 500; }
+          .hud .v { color: var(--wick-text-strong, var(--hab-text-strong, #e6edf3)); font-variant-numeric: tabular-nums; }
+          .hud .up { color: var(--wick-up, var(--hab-up, #16c784)); }
+          .hud .dn { color: var(--wick-down, var(--hab-down, #ea3943)); }
         </style>
         <div class="wrap" part="wrap">
           <canvas part="canvas" role="img"></canvas>
@@ -218,6 +228,12 @@ class HabChart extends HTMLElementBase {
       this._alerts = [];
       this._seq = 0;
 
+      // server-side overlays (zones & levels)
+      this._overlays = [];
+
+      // scenario projection (ghost path + vol cone)
+      this._scenario = null;
+
       this._onResize = () => this._invalidate();
       this._onPointerDown = (e) => this._pointerDown(e);
       this._onPointerMove = (e) => this._pointerMove(e);
@@ -305,7 +321,7 @@ class HabChart extends HTMLElementBase {
           this._label = val || '';
           break;
         case 'indicators':
-          this._ind = parseIndicators(val, HabChart._registry());
+          this._ind = parseIndicators(val, WickChart._registry());
           break;
         case 'stats':
           this._stats = val != null && val !== 'false';
@@ -323,6 +339,18 @@ class HabChart extends HTMLElementBase {
           this._volshade = val != null && val !== 'false' ? parseVolShading(val) : null;
           this._legendKey = '';
           break;
+        case 'overlays': {
+          let ovs = [];
+          if (val != null && val !== '') {
+            try {
+              ovs = normalizeOverlays(JSON.parse(val));
+            } catch (err) {
+              ovs = [];
+            }
+          }
+          this._overlays = ovs;
+          break;
+        }
         case 'co-view':
           this._coviewName = val || null;
           this._setupCoView();
@@ -339,20 +367,15 @@ class HabChart extends HTMLElementBase {
      * Indicator registry
      * ------------------------------------------------------------ */
 
-    static _registryMap = null;
-
-    /** Lazily-built registry, seeded with the built-in indicators. */
+    /** Indicator registry (module scope — shared with the legacy alias tag). */
     static _registry() {
-      if (!HabChart._registryMap) {
-        HabChart._registryMap = new Map(BUILTIN_INDICATORS);
-      }
-      return HabChart._registryMap;
+      return REGISTRY;
     }
 
     /**
      * 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}
@@ -373,7 +396,7 @@ class HabChart extends HTMLElementBase {
       if (!def || typeof def.compute !== 'function') {
         throw new Error('registerIndicator: def.compute must be a function');
       }
-      HabChart._registry().set(name.toLowerCase(), {
+      REGISTRY.set(name.toLowerCase(), {
         kind: def.kind === 'pane' ? 'pane' : 'overlay',
         ...def,
       });
@@ -403,7 +426,7 @@ class HabChart extends HTMLElementBase {
       }
       const norm = [];
       for (const b of bars) {
-        const nb = HabChart._normBar(b);
+        const nb = WickChart._normBar(b);
         if (nb) norm.push(nb);
       }
       // skip the O(n log n) sort when already ascending (typical for feeds)
@@ -432,7 +455,7 @@ class HabChart extends HTMLElementBase {
      * @param {import('./core.js').Bar} bar
      */
     update(bar) {
-      const b = HabChart._normBar(bar);
+      const b = WickChart._normBar(bar);
       if (!b) return;
       const d = this._data;
       const last = d[d.length - 1];
@@ -492,7 +515,7 @@ class HabChart extends HTMLElementBase {
           }
           const older = [];
           for (const b of bars) {
-            const nb = HabChart._normBar(b);
+            const nb = WickChart._normBar(b);
             if (nb) older.push(nb);
           }
           const { bars: merged, added } = mergeOlderData(this._data, older);
@@ -540,14 +563,14 @@ class HabChart extends HTMLElementBase {
     setVisibleRange(range) {
       const d = this._data;
       if (!d.length || !range || !this._ly) return;
-      const from = HabChart._timeToMs(range.from);
-      const to = HabChart._timeToMs(range.to);
-      let i0 = HabChart._indexForTime(d, from);
-      let i1 = HabChart._indexForTime(d, to);
+      const from = WickChart._timeToMs(range.from);
+      const to = WickChart._timeToMs(range.to);
+      let i0 = WickChart._indexForTime(d, from);
+      let i1 = WickChart._indexForTime(d, to);
       if (i0 > i1) [i0, i1] = [i1, i0];
       if (i1 - i0 < 2) return;
       const { plotRight } = this._ly;
-      this._view.spacing = clamp(plotRight / (i1 - i0), this._minSpacing(), HabChart._MAX_SP);
+      this._view.spacing = clamp(plotRight / (i1 - i0), this._minSpacing(), WickChart._MAX_SP);
       this._view.rightIndex = i1;
       this._auto = false;
       this._clampView();
@@ -627,7 +650,11 @@ class HabChart extends HTMLElementBase {
         })),
         alerts: this._alerts
           .filter((a) => !a.fired)
-          .map((a) => ({ id: a.id, price: a.price, direction: a.direction, once: a.once })),
+          .map((a) =>
+            a.when != null
+              ? { id: a.id, when: a.when, once: a.once }
+              : { id: a.id, price: a.price, direction: a.direction, once: a.once }
+          ),
       };
     }
 
@@ -665,14 +692,31 @@ class HabChart extends HTMLElementBase {
       }
       if (Array.isArray(state.alerts)) {
         this._alerts = state.alerts
-          .filter((a) => a && isNum(a.price))
-          .map((a) => ({
-            id: a.id != null ? String(a.id) : 'alert-' + ++this._seq,
-            price: a.price,
-            direction: a.direction || 'cross',
-            once: a.once !== false,
-            fired: false,
-          }));
+          .filter((a) => a && (isNum(a.price) || typeof a.when === 'string'))
+          .map((a) => {
+            if (typeof a.when === 'string' && a.when.trim()) {
+              try {
+                return {
+                  id: a.id != null ? String(a.id) : 'alert-' + ++this._seq,
+                  when: a.when.trim(),
+                  compiled: compileScript(a.when),
+                  once: a.once !== false,
+                  fired: false,
+                  armed: true,
+                };
+              } catch (err) {
+                return null;
+              }
+            }
+            return {
+              id: a.id != null ? String(a.id) : 'alert-' + ++this._seq,
+              price: a.price,
+              direction: a.direction || 'cross',
+              once: a.once !== false,
+              fired: false,
+            };
+          })
+          .filter(Boolean);
       }
       if (state.view && state.view.from != null && state.view.to != null) {
         if (this._ly && this._data.length > 1) {
@@ -725,21 +769,46 @@ class HabChart extends HTMLElementBase {
     }
 
     /**
-     * Price alert. Fires `hab:alert` ({id, price, bar}) on an edge crossing
-     * during streaming updates.
-     * @param {{id?: string, price: number, direction?: 'above'|'below'|'cross',
-     *          once?: boolean}} alert
-     * @returns {string|null} the alert id
+     * Price or scripted alert. Price alerts fire `wick:alert`
+     * ({id, price, bar}) on an edge crossing; scripted alerts evaluate a
+     * WickScript predicate (`when`) on every streamed bar and fire on its
+     * false→true edge — e.g. `when: 'crossup(rsi(close,14), 30)'` or
+     * `when: 'volume > sma(volume,20) * 3'`. Scripted events carry the
+     * triggering close as `price` plus the `when` source (deprecated
+     * `hab:alert` alias still dispatched).
+     * @param {{id?: string, price?: number, direction?: 'above'|'below'|'cross',
+     *          when?: string, once?: boolean}} alert
+     * @returns {string|null} the alert id (null when no valid price/when,
+     *          or the predicate fails to compile)
      */
     addAlert(alert) {
-      if (!alert || !isNum(alert.price)) return null;
-      const a = {
-        id: alert.id != null ? String(alert.id) : 'alert-' + ++this._seq,
-        price: alert.price,
-        direction: alert.direction || 'cross',
-        once: alert.once !== false,
-        fired: false,
-      };
+      if (!alert) return null;
+      let a;
+      if (typeof alert.when === 'string' && alert.when.trim()) {
+        let compiled;
+        try {
+          compiled = compileScript(alert.when);
+        } catch (err) {
+          return null;
+        }
+        a = {
+          id: alert.id != null ? String(alert.id) : 'alert-' + ++this._seq,
+          when: alert.when.trim(),
+          compiled,
+          once: alert.once !== false,
+          fired: false,
+          armed: true,
+        };
+      } else {
+        if (!isNum(alert.price)) return null;
+        a = {
+          id: alert.id != null ? String(alert.id) : 'alert-' + ++this._seq,
+          price: alert.price,
+          direction: alert.direction || 'cross',
+          once: alert.once !== false,
+          fired: false,
+        };
+      }
       const i = this._alerts.findIndex((x) => x.id === a.id);
       if (i >= 0) this._alerts[i] = a;
       else this._alerts.push(a);
@@ -757,21 +826,214 @@ class HabChart extends HTMLElementBase {
       this._invalidate();
     }
 
-    /** Check alerts against an incoming bar (prev close → new close). */
+    /**
+     * Server-side overlays: zones & levels anchored in time × price — e.g.
+     * supply/demand zones from an analysis API. Zones with no `to` extend
+     * into future space past the last bar, like TradingView drawings.
+     *
+     *   zone:  { type:'zone', from?:ms, to?:ms|null, priceFrom, priceTo,
+     *            color?, alpha?, border?, label?, id? }
+     *   level: { type:'level', price, from?, to?, color?, width?, dash?,
+     *            label?, id? }
+     *
+     * Invalid entries are dropped, never thrown. Colors accept hex/rgb()/CSS
+     * names plus the palette keys 'up' | 'down' | 'accent'.
+     * @param {object[]} list
+     * @returns {string[]} applied overlay ids
+     */
+    setOverlays(list) {
+      this._overlays = normalizeOverlays(list);
+      this._invalidate();
+      return this._overlays.map((o) => o.id);
+    }
+
+    /** @returns {object[]} a copy of the current overlays */
+    get overlays() {
+      return this._overlays.map((o) => ({ ...o }));
+    }
+
+    /**
+     * Add or replace (upsert, by id) a single overlay.
+     * @returns {string|null} the overlay id, or null if invalid
+     */
+    addOverlay(ov) {
+      const norm = normalizeOverlays([ov]);
+      if (!norm.length) return null;
+      const one = norm[0];
+      const i = this._overlays.findIndex((x) => x.id === one.id);
+      if (i >= 0) this._overlays[i] = one;
+      else this._overlays.push(one);
+      this._invalidate();
+      return one.id;
+    }
+
+    removeOverlay(id) {
+      this._overlays = this._overlays.filter((o) => o.id !== String(id));
+      this._invalidate();
+    }
+
+    clearOverlays() {
+      this._overlays = [];
+      this._invalidate();
+    }
+
+    /**
+     * Scenario projection into future space: a ghost path of future prices
+     * plus optional σ-bands (vol cone) from realized volatility.
+     *
+     *   chart.setScenario({ path: [64000, 65500, 68000], label: 'bull case' });
+     *   chart.setScenario({ horizon: 48, cone: true });   // cone-only
+     *
+     * The path is an array of prices (or {price} objects) for future bars
+     * 1..N; horizon defaults to the path length (1–500). `cone` (default
+     * true) draws ±levels·σ bands widening with √h from the current realized
+     * vol; `color` accepts up|down|accent or safe CSS colors. Setting a
+     * scenario reserves future space on the right; analysis data — excluded
+     * from getState/setState.
+     * @param {object} spec
+     * @returns {object|null} the normalized scenario, or null when invalid
+     */
+    setScenario(spec) {
+      this._scenario = normalizeScenario(spec);
+      this._invalidate();
+      return this._scenario;
+    }
+
+    clearScenario() {
+      this._scenario = null;
+      this._invalidate();
+    }
+
+    /** @returns {object|null} a copy of the active scenario */
+    get scenario() {
+      if (!this._scenario) return null;
+      return { ...this._scenario, path: this._scenario.path.map((p) => ({ ...p })) };
+    }
+
+    /** σ-cone for the active scenario, cached per data version. */
+    _scenarioConeCache() {
+      if (!this._scenario || !this._data.length) return null;
+      if (this._cache.v !== this._version) {
+        this._cache = { v: this._version, map: {} };
+      }
+      if (!this._cache.map.__scenario) {
+        const d = this._data;
+        const vol = calcRealizedVol(d.map((b) => b.close), 20);
+        let v = NaN;
+        for (let i = vol.length - 1; i >= 0; i--) {
+          if (Number.isFinite(vol[i])) { v = vol[i]; break; }
+        }
+        this._cache.map.__scenario = calcVolCone(
+          d[d.length - 1].close,
+          v,
+          this._scenario.horizon,
+          this._scenario.levels
+        );
+      }
+      return this._cache.map.__scenario;
+    }
+
+    /* ------------------------------------------------------------ *
+     * AI agent interface — the chart as a tool surface
+     * ------------------------------------------------------------ */
+
+    /** Tool manifest for LLM control — JSON-safe copy of AI_TOOLS. */
+    aiTools() {
+      return JSON.parse(JSON.stringify(AI_TOOLS));
+    }
+
+    /** System prompt for agent control — paste into any LLM alongside aiTools(). */
+    aiPrompt() {
+      return aiPromptText();
+    }
+
+    /** Grounding context for a model: current state + visible-window summary. */
+    aiContext() {
+      return { state: this.getState(), window: this.getDataWindow() };
+    }
+
+    /**
+     * Apply a list of {tool, args} ops (typically LLM output) through the
+     * validated dispatcher in core. Never throws — each op resolves
+     * {ok, tool, result} or {ok: false, tool, error} so an agent can
+     * self-correct.
+     * @param {any} ops
+     * @returns {Array<object>}
+     */
+    applyAI(ops) {
+      return applyChartOps(this, ops);
+    }
+
+    /**
+     * Ask an AI to operate the chart. Builds the payload {system,
+     * instruction, chart, tools}; with a `run` async function (your model
+     * call — the chart itself never touches the network), applies the
+     * returned ops and resolves {payload, ops, results}. Without `run`,
+     * returns the payload for manual wiring — send it anywhere, then call
+     * chart.applyAI(ops) with the model's answer.
+     *
+     *   const { results } = await chart.ask('add RSI and mark the demand zone', {
+     *     run: async (payload) => (await callMyLLM(payload)).ops,
+     *   });
+     *
+     * @param {string} instruction natural-language request
+     * @param {{run?: (payload: object) => Promise<any>}} [opts]
+     */
+    async ask(instruction, opts = {}) {
+      const payload = {
+        system: aiPromptText(),
+        instruction: String(instruction == null ? '' : instruction),
+        chart: this.aiContext(),
+        tools: this.aiTools(),
+      };
+      if (typeof opts.run !== 'function') {
+        return { payload, ops: null, results: null };
+      }
+      const ops = await opts.run(payload);
+      const results = this.applyAI(ops);
+      return { payload, ops, results };
+    }
+
+    /** Check alerts against an incoming bar (prev close → new close).
+     *  Scripted (`when`) alerts evaluate their predicate series, cached per
+     *  data version, and fire on the false→true edge. */
     _checkAlerts(prevClose, bar) {
-      if (!this._alerts.length || !isNum(prevClose)) return;
+      if (!this._alerts.length) return;
       for (const a of [...this._alerts]) {
         if (a.fired) continue;
+        if (a.when != null) {
+          const series = this._predicateCache(a);
+          const curTrue = series.length ? series[series.length - 1] : false;
+          const step = scriptAlertStep(a.armed, curTrue);
+          a.armed = step.armed;
+          if (step.fire) {
+            a.fired = true;
+            this._fire('alert', { id: a.id, price: bar.close, when: a.when, bar });
+            if (a.once) this._alerts = this._alerts.filter((x) => x !== a);
+          }
+          continue;
+        }
+        if (!isNum(prevClose)) continue;
         if (checkAlertCross(a, prevClose, bar.close)) {
           a.fired = true;
-          this.dispatchEvent(
-            new CustomEvent('hab:alert', { detail: { id: a.id, price: a.price, bar } })
-          );
+          this._fire('alert', { id: a.id, price: a.price, bar });
           if (a.once) this._alerts = this._alerts.filter((x) => x !== a);
         }
       }
     }
 
+    /** Cached boolean series for a scripted alert's predicate (per data version). */
+    _predicateCache(alert) {
+      if (this._cache.v !== this._version) {
+        this._cache = { v: this._version, map: {} };
+      }
+      const k = 'pred:' + alert.when;
+      if (!this._cache.map[k]) {
+        this._cache.map[k] = predicateTrueSeries(alert.compiled, this._data);
+      }
+      return this._cache.map[k];
+    }
+
     /* reflected properties */
     get theme() { return this._theme; }
     set theme(v) { this.setAttribute('theme', v); }
@@ -808,7 +1070,7 @@ class HabChart extends HTMLElementBase {
       if (!b) return null;
       const t = b.time != null ? b.time : b.t;
       if (!isNum(t)) return null;
-      const time = HabChart._timeToMs(t);
+      const time = WickChart._timeToMs(t);
       const close = isNum(b.close) ? b.close : isNum(b.value) ? b.value : NaN;
       if (!isNum(close)) return null;
       const open = isNum(b.open) ? b.open : close;
@@ -887,8 +1149,9 @@ class HabChart extends HTMLElementBase {
       if (this._pal && this._palKey === this._theme) return this._pal;
       const base = THEMES[this._theme] || THEMES.dark;
       const cs = getComputedStyle(this);
+      // --wick-* is canonical; --hab-* still honored as the 0.x fallback
       const get = (name, fallback) => {
-        const v = cs.getPropertyValue('--hab-' + name).trim();
+        const v = cs.getPropertyValue('--wick-' + name).trim() || cs.getPropertyValue('--hab-' + name).trim();
         return v || fallback;
       };
       const pal = {};
@@ -899,7 +1162,8 @@ class HabChart extends HTMLElementBase {
             o.push(get('overlay-' + i, base.overlay[i]));
           }
           // allow single overlay color
-          const single = cs.getPropertyValue('--hab-overlay').trim();
+          const single =
+            cs.getPropertyValue('--wick-overlay').trim() || cs.getPropertyValue('--hab-overlay').trim();
           pal.overlay = single ? base.overlay.map(() => single) : o;
         } else {
           pal[k] = get(k.replace(/[A-Z]/g, (m) => '-' + m.toLowerCase()), base[k]);
@@ -1010,7 +1274,9 @@ class HabChart extends HTMLElementBase {
     _rightMargin() {
       const ly = this._ly;
       const w = ly ? ly.plotRight : 600;
-      return Math.max(3, (w / this._view.spacing) * 0.06);
+      const base = Math.max(3, (w / this._view.spacing) * 0.06);
+      // a scenario projection reserves future space so the cone stays visible
+      return this._scenario ? Math.max(base, this._scenario.horizon + 3) : base;
     }
 
     _applyFit() {
@@ -1018,7 +1284,7 @@ class HabChart extends HTMLElementBase {
       if (!d.length || !this._ly) return;
       const { plotRight } = this._ly;
       const target = Math.min(d.length, 150);
-      this._view.spacing = clamp(plotRight / target, this._minSpacing(), HabChart._MAX_SP);
+      this._view.spacing = clamp(plotRight / target, this._minSpacing(), WickChart._MAX_SP);
       this._view.rightIndex = d.length - 1 + this._rightMargin();
     }
 
@@ -1027,7 +1293,7 @@ class HabChart extends HTMLElementBase {
       const ly = this._ly;
       if (!d.length || !ly) return;
       const v = this._view;
-      v.spacing = clamp(v.spacing, this._minSpacing(), HabChart._MAX_SP);
+      v.spacing = clamp(v.spacing, this._minSpacing(), WickChart._MAX_SP);
       const visible = ly.plotRight / v.spacing;
       const maxRight = d.length - 1 + Math.max(6, visible * 0.5);
       const minRight = Math.min(2, d.length - 1);
@@ -1378,6 +1644,146 @@ class HabChart extends HTMLElementBase {
         }
       }
 
+      /* server-side overlays: zones & levels (above regime shading, under series).
+       * Zones with `to == null` extend into future space past the last bar. */
+      if (this._overlays.length) {
+        const d = this._data;
+        const idxFor = (t, fallback) => (t == null ? fallback : barIndexForTime(d, t));
+        for (const ov of this._overlays) {
+          const col = resolveOverlayColor(ov.color, pal);
+          if (ov.type === 'zone') {
+            const iA = Math.max(0, idxFor(ov.from, 0));
+            const iB = ov.to == null ? null : Math.max(0, idxFor(ov.to, d.length - 1));
+            const zx0 = clamp(this._xFor(iA) - sp * 0.5, 0, plotRight);
+            const zx1 = iB == null ? plotRight : clamp(this._xFor(iB) + sp * 0.5, 0, plotRight);
+            const zyT = clamp(yOf(ov.priceTo), main.y0, main.y1);
+            const zyB = clamp(yOf(ov.priceFrom), main.y0, main.y1);
+            if (zx1 - zx0 < 1 || zyB - zyT < 1) continue;
+            ctx.save();
+            ctx.globalAlpha = ov.alpha;
+            ctx.fillStyle = col;
+            ctx.fillRect(zx0, zyT, zx1 - zx0, zyB - zyT);
+            if (ov.border) {
+              ctx.globalAlpha = Math.min(1, ov.alpha + 0.4);
+              ctx.lineWidth = 1;
+              ctx.strokeStyle = col;
+              ctx.strokeRect(
+                Math.round(zx0) + 0.5, Math.round(zyT) + 0.5,
+                Math.max(2, Math.round(zx1 - zx0) - 1), Math.max(2, Math.round(zyB - zyT) - 1)
+              );
+            }
+            if (ov.label) {
+              ctx.globalAlpha = 0.95;
+              ctx.font = pillFont();
+              ctx.fillStyle = col;
+              ctx.textAlign = 'left';
+              ctx.textBaseline = 'top';
+              ctx.fillText(ov.label, zx0 + 6, Math.max(main.y0, zyT) + 4);
+            }
+            ctx.restore();
+          } else {
+            const lx0 = clamp(this._xFor(Math.max(0, idxFor(ov.from, 0))) - sp * 0.5, 0, plotRight);
+            const lx1 =
+              ov.to == null
+                ? plotRight
+                : clamp(this._xFor(Math.max(0, idxFor(ov.to, d.length - 1))) + sp * 0.5, 0, plotRight);
+            const ly = Math.round(yOf(ov.price)) + 0.5;
+            if (lx1 - lx0 < 1 || ly < main.y0 || ly > main.y1) continue;
+            ctx.save();
+            ctx.strokeStyle = col;
+            ctx.lineWidth = ov.width;
+            if (ov.dash) ctx.setLineDash([5, 4]);
+            ctx.beginPath();
+            ctx.moveTo(lx0, ly);
+            ctx.lineTo(lx1, ly);
+            ctx.stroke();
+            if (ov.label) {
+              ctx.font = pillFont();
+              ctx.fillStyle = col;
+              ctx.textAlign = 'right';
+              ctx.textBaseline = 'bottom';
+              ctx.fillText(ov.label, Math.min(lx1, plotRight) - 6, ly - 2);
+            }
+            ctx.restore();
+          }
+        }
+      }
+
+      /* scenario projection: ghost path + σ-cone in future space (clipped to
+       * the main plot so out-of-range bands never bleed into the axis) */
+      if (this._scenario && d.length) {
+        const sc = this._scenario;
+        const col = resolveOverlayColor(sc.color, pal);
+        const baseIdx = d.length - 1;
+        const xAt = (h) => this._xFor(baseIdx + h);
+        ctx.save();
+        ctx.beginPath();
+        ctx.rect(0, main.y0, plotRight, main.h);
+        ctx.clip();
+        if (sc.cone) {
+          const cone = this._scenarioConeCache();
+          if (cone) {
+            for (let li = cone.levels.length - 1; li >= 0; li--) {
+              const b = cone.bands[cone.levels[li]];
+              ctx.globalAlpha = li === 0 ? 0.1 : 0.05;
+              ctx.fillStyle = col;
+              ctx.beginPath();
+              ctx.moveTo(xAt(0), yOf(b.up[0]));
+              for (let h = 1; h <= cone.horizon; h++) ctx.lineTo(xAt(h), yOf(b.up[h]));
+              for (let h = cone.horizon; h >= 0; h--) ctx.lineTo(xAt(h), yOf(b.down[h]));
+              ctx.closePath();
+              ctx.fill();
+            }
+            const inner = cone.bands[cone.levels[0]];
+            ctx.globalAlpha = 0.4;
+            ctx.strokeStyle = col;
+            ctx.lineWidth = 1;
+            ctx.setLineDash([4, 4]);
+            for (const arr of [inner.up, inner.down]) {
+              ctx.beginPath();
+              ctx.moveTo(xAt(0), yOf(arr[0]));
+              for (let h = 1; h <= cone.horizon; h++) ctx.lineTo(xAt(h), yOf(arr[h]));
+              ctx.stroke();
+            }
+            ctx.setLineDash([]);
+          }
+        }
+        if (sc.path.length) {
+          ctx.globalAlpha = 0.9;
+          ctx.strokeStyle = col;
+          ctx.lineWidth = 1.5;
+          ctx.setLineDash([6, 4]);
+          ctx.beginPath();
+          ctx.moveTo(xAt(0), yOf(d[baseIdx].close));
+          for (const p of sc.path) ctx.lineTo(xAt(p.h), yOf(p.price));
+          ctx.stroke();
+          ctx.setLineDash([]);
+          ctx.fillStyle = col;
+          for (const p of sc.path) {
+            const y = yOf(p.price);
+            if (y >= main.y0 && y <= main.y1) {
+              ctx.beginPath();
+              ctx.arc(xAt(p.h), y, 2.5, 0, Math.PI * 2);
+              ctx.fill();
+            }
+          }
+          if (sc.label) {
+            const p = sc.path[sc.path.length - 1];
+            ctx.font = pillFont();
+            ctx.globalAlpha = 0.95;
+            ctx.fillStyle = col;
+            ctx.textAlign = 'left';
+            ctx.textBaseline = 'middle';
+            ctx.fillText(
+              sc.label,
+              Math.min(xAt(p.h) + 8, plotRight - 4),
+              clamp(yOf(p.price), main.y0 + 8, main.y1 - 8)
+            );
+          }
+        }
+        ctx.restore();
+      }
+
       /* position zones (under series) */
       for (const pos of this._positions) {
         const yE = clamp(yOf(pos.entry), main.y0, main.y1);
@@ -1457,9 +1863,7 @@ class HabChart extends HTMLElementBase {
           this._annoList = detectAnnotations(this._data, i0, i1, this._cachedRSI14());
           this._annoKey = akey;
           this._legendKey = ''; // legend may now show insights at the hovered bar
-          this.dispatchEvent(
-            new CustomEvent('hab:annotations', { detail: { annotations: this._annoList } })
-          );
+          this._fire('annotations', { annotations: this._annoList });
         }
         const A = this._annoList;
         if (A.length) {
@@ -1723,7 +2127,7 @@ class HabChart extends HTMLElementBase {
         ctx.setLineDash([5, 4]);
         ctx.strokeStyle = pal.overlay[0];
         for (const a of this._alerts) {
-          if (a.fired) continue;
+          if (a.fired || !isNum(a.price)) continue; // scripted alerts have no line
           const y = yOf(a.price);
           if (y < main.y0 || y > main.y1) continue;
           ctx.globalAlpha = 0.8;
@@ -2353,7 +2757,7 @@ class HabChart extends HTMLElementBase {
         const s = clamp(
           (this._pinch.spacing * dist) / this._pinch.dist,
           this._minSpacing(),
-          HabChart._MAX_SP
+          WickChart._MAX_SP
         );
         this._view.spacing = s;
         this._view.rightIndex = this._pinch.idxAtMid + (ly.plotRight - mid.x) / s;
@@ -2406,15 +2810,11 @@ class HabChart extends HTMLElementBase {
             const d = this._data;
             const barA = d[clamp(m.iA, 0, d.length - 1)];
             const barB = d[clamp(m.iB, 0, d.length - 1)];
-            this.dispatchEvent(
-              new CustomEvent('hab:measure', {
-                detail: {
-                  from: { index: m.iA, time: barA.time, price: m.pA },
-                  to: { index: m.iB, time: barB.time, price: m.pB },
-                  bars: Math.abs(m.iB - m.iA),
-                },
-              })
-            );
+            this._fire('measure', {
+              from: { index: m.iA, time: barA.time, price: m.pA },
+              to: { index: m.iB, time: barB.time, price: m.pB },
+              bars: Math.abs(m.iB - m.iA),
+            });
           }
         } else if (this._pan && had && !this._pan.moved && this._data.length) {
           if (this._measure) {
@@ -2426,11 +2826,7 @@ class HabChart extends HTMLElementBase {
             const pt = this._localPoint(e);
             const idx = clamp(Math.round(this._indexForX(pt.x)), 0, this._data.length - 1);
             const price = this._yToPrice(pt.y);
-            this.dispatchEvent(
-              new CustomEvent('hab:select', {
-                detail: { index: idx, bar: this._data[idx], price },
-              })
-            );
+            this._fire('select', { index: idx, bar: this._data[idx], price });
           }
         }
         this._pan = null;
@@ -2456,8 +2852,10 @@ class HabChart extends HTMLElementBase {
       const dy = e.deltaY * (e.deltaMode === 1 ? 33 : 1);
 
       if (Math.abs(dx) > Math.abs(dy) && !e.ctrlKey) {
-        // trackpad horizontal scroll → pan
-        this._view.rightIndex -= dx / this._view.spacing;
+        // trackpad horizontal scroll → pan. Wheel deltas are viewport-relative:
+        // deltaX>0 means "scroll right", i.e. reveal newer bars. On natural-scroll
+        // trackpads this makes the content follow the fingers, matching drag.
+        this._view.rightIndex += dx / this._view.spacing;
         this._auto = this._atRight();
         this._clampView();
         this._invalidate();
@@ -2467,7 +2865,7 @@ class HabChart extends HTMLElementBase {
 
       const factor = Math.exp(-dy * (e.ctrlKey ? 0.008 : 0.0016));
       const oldSp = this._view.spacing;
-      const newSp = clamp(oldSp * factor, this._minSpacing(), HabChart._MAX_SP);
+      const newSp = clamp(oldSp * factor, this._minSpacing(), WickChart._MAX_SP);
       if (newSp === oldSp) return;
       const idxAtCursor = this._indexForX(pt.x);
       this._view.spacing = newSp;
@@ -2504,12 +2902,12 @@ class HabChart extends HTMLElementBase {
         this._invalidate();
         this._emitRange();
       } else if (key === '+' || key === '=') {
-        this._view.spacing = clamp(this._view.spacing * 1.25, this._minSpacing(), HabChart._MAX_SP);
+        this._view.spacing = clamp(this._view.spacing * 1.25, this._minSpacing(), WickChart._MAX_SP);
         this._clampView();
         this._invalidate();
         this._emitRange();
       } else if (key === '-' || key === '_') {
-        this._view.spacing = clamp(this._view.spacing / 1.25, this._minSpacing(), HabChart._MAX_SP);
+        this._view.spacing = clamp(this._view.spacing / 1.25, this._minSpacing(), WickChart._MAX_SP);
         this._clampView();
         this._invalidate();
         this._emitRange();
@@ -2636,7 +3034,7 @@ class HabChart extends HTMLElementBase {
           price: this._yToPrice(hover.y),
         };
       }
-      this.dispatchEvent(new CustomEvent('hab:crosshair', { detail }));
+      this._fire('crosshair', detail);
 
       // co-view: share the pointer with peer charts (leave events bypass throttle)
       if (this._coviewCh) {
@@ -2678,7 +3076,7 @@ class HabChart extends HTMLElementBase {
       if (!name || !this._connected || typeof BroadcastChannel === 'undefined') return;
       if (!this._coviewPeer) this._coviewPeer = 'p' + Math.random().toString(36).slice(2, 8);
       try {
-        const ch = new BroadcastChannel('hab-co-view:' + name);
+        const ch = new BroadcastChannel('wick-co-view:' + name);
         ch.onmessage = (ev) => this._onCoMessage(ev.data);
         this._coviewCh = ch;
       } catch (_) {}
@@ -2703,7 +3101,7 @@ class HabChart extends HTMLElementBase {
       }
       if (!isNum(m.time) || !this._data.length) return;
       this._ghost = {
-        index: HabChart._indexForTime(this._data, m.time),
+        index: WickChart._indexForTime(this._data, m.time),
         yFrac: isNum(m.yFrac) ? clamp(m.yFrac, 0, 1) : null,
         at: Date.now(),
       };
@@ -2715,15 +3113,31 @@ class HabChart extends HTMLElementBase {
       this._invalidate();
     }
 
+    /** Dispatch `wick:name` (canonical) plus the deprecated `hab:name` alias,
+     *  so 0.x listeners keep working until 2.0. */
+    _fire(name, detail) {
+      this.dispatchEvent(new CustomEvent('wick:' + name, { detail }));
+      this.dispatchEvent(new CustomEvent('hab:' + name, { detail }));
+    }
+
     _emitRange() {
       const r = this.getVisibleRange();
       if (!r) return;
-      this.dispatchEvent(new CustomEvent('hab:range', { detail: r }));
+      this._fire('range', r);
     }
   }
 
-if (typeof customElements !== 'undefined' && !customElements.get('hab-chart')) {
-  customElements.define('hab-chart', HabChart);
+if (typeof customElements !== 'undefined') {
+  if (!customElements.get('wick-chart')) {
+    customElements.define('wick-chart', WickChart);
+  }
+  // 0.x alias: same element under its old tag name (deprecated, removed in 2.0)
+  if (!customElements.get('hab-chart')) {
+    /** @deprecated use <wick-chart> */
+    class HabChart extends WickChart {}
+    customElements.define('hab-chart', HabChart);
+  }
 }
 
-export default HabChart;
+export default WickChart;
+export { WickChart };