@luxalgo/vela 0.6.11 → 0.6.13

package/README.md

@@ -1,56 +1,105 @@
-# Vela
-
-A fast, extensible financial charting library with its own native canvas renderer, a
-headless core, a batteries-included shell, and a plugin SDK for custom chart types and
-renderer layers.
-
-- **`vela`** — the headless chart: data model, engines, drawings, providers, native renderer.
-- **`vela/workspace`** — the full chart app: one chart (`layout: false`) or a grid of
-  them under one shared topbar (symbol / timeframe / style / indicators), status line,
-  watermark, bottom bar (ranges, clock, timezone), object tree, keyboard-first UX,
-  named cells, sync groups and one persisted state document.
-- **`vela/ui`** — the component kit the shell is built on: design tokens, overlay chrome
-  ([Zag.js](https://zagjs.com) menu/dialog/drawer/tooltip), form primitives (switch, select,
-  number, text, color, popover), and the `KeymapManager`.
-- **`vela/plugin`** — the extension SDK: chart types, renderer layers, native indicators.
-- **`vela/providers/*`** — data providers (Binance, Coinbase, Hyperliquid).
+<!-- markdownlint-disable no-inline-html first-line-h1 -->
+
+<div align="center">
+
+  <img src=".github/banner.png" alt="Vela™ — fast, extensible financial charts for the web" width="100%">
+
+  <p><strong>Fast, extensible financial charts for the web.</strong><br>
+  Headless core · native WebGL2 renderer · batteries-included workspace · plugin SDK</p>
+
+  [![npm version][npm-version-img]][npm-link]
+  [![Downloads][npm-downloads-img]][npm-link]
+  [![License][license-img]][license-link]
+
+  <p>
+    <a href="https://luxalgo.com/vela">Homepage</a> ·
+    <a href="#quick-start">Quick start</a> ·
+    <a href="docs/index.md">Documentation</a> ·
+    <a href="#extending-plugin-sdk">Plugin SDK</a> ·
+    <a href="CHANGELOG.md">Changelog</a> ·
+    <a href="#license-and-attribution">License</a>
+  </p>
+
+</div>
+
+<!-- markdownlint-enable no-inline-html -->
+
+Vela™ renders interactive financial charts with its own native renderer (WebGL2, with a
+canvas2d fallback) and keeps the chart itself headless: drive it entirely from code, or
+drop in the workspace for a complete chart app in one call. Every layer (data providers,
+scripting engines, renderers) plugs in behind a public port and can be swapped without
+touching the rest.
+
+## What's in the box
+
+- **`@luxalgo/vela`**: the headless chart. Data model, engines, drawings, providers,
+  native renderer.
+- **`@luxalgo/vela/workspace`**: the full chart app. One chart or a grid of them under
+  one shared topbar (symbol / timeframe / style / indicators), status line, symbol
+  watermark, bottom bar (ranges, clock, timezone), object tree, keyboard-first UX
+  (type a letter for symbol search, a digit for timeframe entry, `?` for the shortcuts
+  panel), named cells, sync groups, and one persisted state document.
+- **`@luxalgo/vela/ui`**: the component kit the app is built on. Design tokens, overlay
+  chrome ([Zag.js](https://zagjs.com) menu/dialog/drawer/tooltip), form primitives, and
+  the `KeymapManager`.
+- **`@luxalgo/vela/plugin`**: the extension SDK. Chart types, renderer layers, native
+  indicators.
+- **`@luxalgo/vela/providers/*`**: data providers (Binance, Coinbase, Hyperliquid),
+  ready to register. Or supply your own bars and stay fully offline.
+
+## Installing
+
+```bash
+npm install @luxalgo/vela
+```
 
 ## Quick start
 
+The fastest path is the workspace, a complete chart app in one call:
+
 ```ts
-import { VelaWorkspace } from 'vela/workspace';
-import { BinanceProvider } from 'vela/providers/binance';
+import { VelaWorkspace } from '@luxalgo/vela/workspace';
+import { BinanceProvider } from '@luxalgo/vela/providers/binance';
 
 const chart = new VelaWorkspace('#chart', {
     layout: false, // one chart; '2h' | '4' | '8' | … for a multi-chart grid
-    symbol: 'BTCUSDT', // bare = first declared provider listing it; 'binance:BTCUSDT' pins the venue
+    symbol: 'BTCUSDT',
     timeframe: '60',
     live: true,
     theme: 'dark',
     providers: { binance: () => new BinanceProvider() },
-    persist: true, // restore the full state document — market, style, timezone, renderer
-                   // config, drawings and indicators — from localStorage
+    persist: true, // restore market, style, timezone, drawings and indicators from localStorage
 });
 ```
 
 Prefer full control? Use the headless core directly:
 
 ```ts
-import { Vela } from 'vela';
-import { BinanceProvider } from 'vela/providers/binance';
+import { Vela } from '@luxalgo/vela';
+import { BinanceProvider } from '@luxalgo/vela/providers/binance';
 
 const chart = new Vela('#chart', { symbol: 'binance:BTCUSDT', timeframe: '60', live: true });
 chart.data.registerProvider('binance', new BinanceProvider());
 await chart.ready();
 ```
 
+No provider, no network? Pass your own bars via the `data` option. See the
+[quickstart](docs/user/quickstart.md).
+
+### Browser bundle
+
+The package also ships self-contained browser builds for script-tag usage:
+`dist/vela.global.js` (readable, development) and `dist/vela.global.min.js` (minified,
+production). Either file attaches the library's public API, including the bundled
+providers, to `window.Vela`.
+
 ## Indicators
 
-Vela runs indicator scripts through pluggable engines and **ships none** — install the
+Vela™ runs indicator scripts through pluggable engines and **ships none**. Install the
 addon for the language you want, or write one against the public `ScriptingEngine` port.
 Pine Script lives in [`@luxalgo/vela-pinets`](https://github.com/LuxAlgo/Vela-pinets)
 (`npm i @luxalgo/vela-pinets pinets`), which is **AGPL-3.0** because the PineTS runtime it
-executes is — Vela itself stays Apache-2.0 and carries no Pine code:
+executes is. Vela™ itself stays Apache-2.0 and carries no Pine code:
 
 ```ts
 import { PineEngine } from '@luxalgo/vela-pinets';
@@ -61,14 +110,14 @@ indicator("EMA 20", overlay=true)
 plot(ta.ema(close, 20), color=color.orange, linewidth=2)`);
 ```
 
-Host tooling can execute-and-inject safely (`chart.runIndicator(source)` — structured
-errors, no dead legend rows) and read a running script's state — including its **return
-value** — via `handle.context()` (read-only snapshots, worker-safe). See the
+Host tooling can execute-and-inject safely with `chart.runIndicator(source)` (structured
+errors, no dead legend rows) and read a running script's state, including its **return
+value**, via `handle.context()` (read-only snapshots, worker-safe). See the
 [API reference](docs/user/api-reference.md#reading-a-scripts-execution-context), and
 [Scripting engines](docs/user/scripting-engines.md) for the addon and for writing your own.
 
-The shell takes an **indicator manifest** — inline JSON, a URL returning it, or an async
-loader (`() => Promise<manifest>`):
+The workspace takes an **indicator manifest**: inline JSON, a URL returning it, or an
+async loader (`() => Promise<manifest>`):
 
 ```ts
 new VelaWorkspace('#chart', {
@@ -78,16 +127,12 @@ new VelaWorkspace('#chart', {
 });
 ```
 
-## Keyboard
-
-Type a **letter** → symbol search. Type a **digit** → timeframe entry (`15`, `4h`, `D`, `3M`…).
-`mod+alt+S` (Ctrl+Alt+S, ⌥⌘S on macOS) → screenshot. `?` → the shortcuts panel. Bindings are declarative
-(`chart.keymap.register({...})`) — plugins register theirs the same way.
-
 ## Extending (plugin SDK)
 
+Custom chart types and canvas layers register through the public SDK, no fork needed:
+
 ```ts
-import { registerChartType, registerRendererLayer } from 'vela/plugin';
+import { registerChartType, registerRendererLayer } from '@luxalgo/vela/plugin';
 
 // A new price style: bar transform + optional per-bar data engine + ticker modifier.
 registerChartType({
@@ -104,13 +149,13 @@ registerRendererLayer({
 });
 ```
 
-A registered chart type automatically appears in the shell's style dropdown; a chart
-type's `dataEngine` pushes to its layer's channel with zero extra wiring. See
+A registered chart type automatically appears in the workspace's style dropdown, and a
+chart type's `dataEngine` pushes to its layer's channel with zero extra wiring. See
 [docs/contributing/plugin-sdk.md](docs/contributing/plugin-sdk.md).
 
 ## Documentation
 
-Full documentation lives in [docs/](docs/index.md) — user guides ([quickstart](docs/user/quickstart.md),
+Full documentation lives in [docs/](docs/index.md): user guides ([quickstart](docs/user/quickstart.md),
 [the workspace](docs/user/workspace.md), [options](docs/user/options.md), [API reference](docs/user/api-reference.md)),
 [architecture](docs/architecture/overview.md), and [contributing](docs/contributing/setup.md) guides
 including the [plugin SDK](docs/contributing/plugin-sdk.md).
@@ -124,13 +169,32 @@ npm test             # vitest
 npm run build        # tsup → dist/
 ```
 
-## License
+## License and attribution
+
+Vela™ is licensed under the **Apache License, Version 2.0** (see [LICENSE](LICENSE)).
+The [NOTICE](NOTICE) file adds an **attribution requirement**, and redistributions must
+include it per Apache-2.0 §4(d):
+
+- Every chart renders a small **Vela™ attribution watermark** — the project logomark,
+  linking to the [project page][homepage] — enabled by default. You may restyle or
+  reposition it to fit your design.
+- You may turn the watermark off (`chart.renderer.set('attribution', false)`) **only if**
+  an equivalent visible attribution is shown elsewhere on the same page or screen, where
+  your users can see it: the name "Vela™" linking to the project page.
+- Removing, hiding, or obscuring the attribution without providing that equivalent
+  notice is not permitted.
 
-Apache-2.0 **with a mandatory attribution notice** (see [NOTICE](NOTICE)): charts render
-a small Vela attribution mark by default; it may be disabled
-(`chart.renderer.set('attribution', false)`) only if an equivalent visible attribution —
-"Vela" linking to the project page — is shown elsewhere on the same page. This is the
-same licensing model as other popular charting libraries.
+This is the same licensing model used by other popular charting libraries, and we're
+grateful when the watermark stays in a visible spot.
 
 No scripting engine ships with this package; the Pine Script addon
 (`@luxalgo/vela-pinets`) is AGPL-3.0 and licensed separately (see *Indicators*).
+
+[homepage]: https://luxalgo.com/vela
+
+[npm-version-img]: https://img.shields.io/npm/v/%40luxalgo%2Fvela.svg
+[npm-downloads-img]: https://img.shields.io/npm/dm/%40luxalgo%2Fvela.svg
+[npm-link]: https://www.npmjs.com/package/@luxalgo/vela
+
+[license-img]: https://img.shields.io/badge/license-Apache--2.0-blue.svg
+[license-link]: LICENSE

package/dist/{DataProvider-BBf-jc6W.d.ts → DataProvider-DhzstpQb.d.ts}

@@ -1,4 +1,4 @@
-import { M as MarketConfig, O as OHLCV, U as Unsubscribe } from './options-yp7sA96q.js';
+import { M as MarketConfig, O as OHLCV, U as Unsubscribe } from './options-CYS5Wmlx.js';
 
 /**
  * Symbol metadata an engine may need (e.g. Pine `syminfo.*`). Free-form beyond

package/dist/{DataProvider-p0TEyhlX.d.cts → DataProvider-DlMtrwqM.d.cts}

@@ -1,4 +1,4 @@
-import { M as MarketConfig, O as OHLCV, U as Unsubscribe } from './options-yp7sA96q.cjs';
+import { M as MarketConfig, O as OHLCV, U as Unsubscribe } from './options-CYS5Wmlx.cjs';
 
 /**
  * Symbol metadata an engine may need (e.g. Pine `syminfo.*`). Free-form beyond

package/dist/{chunk-MTLJKZDZ.js → chunk-F4M24ANM.js}

@@ -4969,6 +4969,111 @@ function roundFloat(n) {
   return Math.round(n * 1e8) / 1e8;
 }
 
+// src/core/drawings/types/Magnifier.ts
+var MAGNIFIER_TIMEFRAME_OPTIONS = [
+  { value: "auto", label: "Auto", ms: 0 },
+  { value: "1", label: "1m", ms: 6e4 },
+  { value: "5", label: "5m", ms: 3e5 },
+  { value: "15", label: "15m", ms: 9e5 },
+  { value: "30", label: "30m", ms: 18e5 },
+  { value: "60", label: "1h", ms: 36e5 },
+  { value: "240", label: "4h", ms: 144e5 },
+  { value: "D", label: "1D", ms: 864e5 }
+];
+function magnifierTimeframeLabel(value) {
+  const opt = MAGNIFIER_TIMEFRAME_OPTIONS.find((o) => o.value === value);
+  if (opt) return opt.label;
+  const n = Number(value);
+  if (Number.isFinite(n) && n > 0) {
+    if (n % 1440 === 0) return `${n / 1440}D`;
+    if (n % 60 === 0) return `${n / 60}h`;
+    return `${n}m`;
+  }
+  return value;
+}
+function defaultMagnifierStyle() {
+  return { timeframe: "auto", upColor: "", downColor: "" };
+}
+var Magnifier = class extends Drawing {
+  constructor(init) {
+    super(init);
+    this.type = "magnifier";
+    /** Pixel rect of the timeframe chip as painted last frame, caret included — the chip is
+     *  an interactive dropdown trigger, so the interaction layer needs the exact rect the
+     *  painter measured. Renderer-transient: never serialized, null while unpainted. */
+    this.chipRect = null;
+    if (!this.magnifier) this.magnifier = defaultMagnifierStyle();
+  }
+  anchorSchema() {
+    return { min: 2, max: 2, slots: [{ role: "c1", free: "both" }, { role: "c2", free: "both" }] };
+  }
+  placementMode() {
+    return "drag";
+  }
+  /** The pixel rectangle between the two corner anchors (painter + hit-test share it). */
+  rect(proj) {
+    const a = this.anchors[0];
+    const b = this.anchors[1];
+    if (!a || !b) return null;
+    const ya = proj.yOf(a.price, this.paneId);
+    const yb = proj.yOf(b.price, this.paneId);
+    if (ya == null || yb == null) return null;
+    return { x1: proj.xOf(a.time), y1: ya, x2: proj.xOf(b.time), y2: yb };
+  }
+  hitTest(px, py, proj, tol) {
+    const r = this.rect(proj);
+    if (!r) return false;
+    if (pointInBox(px, py, r.x1, r.y1, r.x2, r.y2)) return true;
+    const edges = [
+      [r.x1, r.y1, r.x2, r.y1],
+      [r.x2, r.y1, r.x2, r.y2],
+      [r.x2, r.y2, r.x1, r.y2],
+      [r.x1, r.y2, r.x1, r.y1]
+    ];
+    return edges.some((e) => distToSegment(px, py, e[0], e[1], e[2], e[3]) <= tol);
+  }
+  handlePoints(proj) {
+    const r = this.rect(proj);
+    return r ? [[r.x1, r.y1], [r.x2, r.y2]] : [];
+  }
+  hitHandle(px, py, proj, tol) {
+    return handleAt(px, py, this.handlePoints(proj), tol + 3);
+  }
+  bounds(proj) {
+    const r = this.rect(proj);
+    if (!r) return null;
+    return { x: Math.min(r.x1, r.x2), y: Math.min(r.y1, r.y2), w: Math.abs(r.x2 - r.x1), h: Math.abs(r.y2 - r.y1) };
+  }
+  priceRange() {
+    const a = this.anchors[0];
+    const b = this.anchors[1];
+    if (!a || !b) return null;
+    return { min: Math.min(a.price, b.price), max: Math.max(a.price, b.price) };
+  }
+  schema() {
+    return {
+      fields: [
+        {
+          path: "magnifier.timeframe",
+          label: "Timeframe",
+          kind: "select",
+          options: MAGNIFIER_TIMEFRAME_OPTIONS,
+          group: "behavior"
+        },
+        ...LINE_FIELDS.map((f) => ({ ...f, label: f.label.replace("Line", "Border") })),
+        { path: "magnifier.upColor", label: "Up candles", kind: "color", group: "fill" },
+        { path: "magnifier.downColor", label: "Down candles", kind: "color", group: "fill" }
+      ]
+    };
+  }
+  writeProps() {
+    return { ...this.magnifier };
+  }
+  readProps(props) {
+    this.magnifier = { ...defaultMagnifierStyle(), ...props };
+  }
+};
+
 // src/core/drawings/registry.ts
 var REGISTRY2 = /* @__PURE__ */ new Map();
 function registerDrawingType(meta) {
@@ -5628,6 +5733,22 @@ registerDrawingType({
   defaultStyle: { lineColor: DEFAULT_DRAWING_COLOR, lineWidth: 1, lineStyle: "solid" },
   create: (init) => new PositionTool(init)
 });
+var MAGNIFIER_ICON = svg24(
+  '<circle cx="10.5" cy="10.5" r="6.5"/><path d="m15.3 15.3 5.2 5.2"/><path d="M8 12.5v-3M10.5 13.5v-5.5M13 12v-2"/>'
+);
+registerDrawingType({
+  type: "magnifier",
+  group: "measure",
+  label: "Magnifier",
+  icon: MAGNIFIER_ICON,
+  // An empty border color means the THEME's contrast ink (white on dark, black on
+  // light), resolved at paint time so it follows theme switches; a user pick wins.
+  defaultStyle: { lineColor: "", lineWidth: 1, lineStyle: "solid" },
+  coversSeries: true,
+  // the inset's backdrop must sit over the base candles it replaces
+  placementHint: "Drag an area on the chart to view it at a lower timeframe",
+  create: (init) => new Magnifier(init)
+});
 var VWAP_ICON = svg24('<line x1="5" y1="3" x2="5" y2="21"/><path d="M5 16c4 0 5-9 8-9s3 5 8 3"/>');
 registerDrawingType({
   type: "anchoredvwap",
@@ -6168,4 +6289,4 @@ var SidePanel = class {
   }
 };
 
-export { AnchoredVwap, ArrowMark, Callout, CalloutBase, Comment, DEDEKIND_CURVATURE_OPTIONS, DEFAULT_DRAWING_COLOR, DEFAULT_PANEL_MAX_WIDTH, DEFAULT_PANEL_MIN_WIDTH, DEFAULT_PANEL_ORDER, DEFAULT_PANEL_WIDTH, DIRECTION_OPTIONS, DedekindTessellation, Drawing, FibRatios, FibSpiral, FixedRangeVolumeProfile, GANN_SQUARE_ARCS, GLYPH_OPTIONS, GannSquare, GlyphStamp, LINE_STYLE_OPTIONS, MACH_NUMBER_OPTIONS, MACH_WAVE_COUNT_OPTIONS, MachFigure, MeasureBox, Note, OVERRIDABLE_TOPBAR_IDS, PatternDrawing, PositionTool, PriceLabel, PriceNote, RadialFib, RegressionChannel, STAMP_SIZE_OPTIONS, SegmentDrawing, SidePanel, Signpost, TEXT_SIZE_OPTIONS, TOPBAR_BUILTIN_IDS, TOPBAR_DEFAULT_LEFT, TOPBAR_DEFAULT_RIGHT, TextLabel, chartType, chartTypes, clampPanelWidth, createDrawing, deserializeDrawing, drawingTypes, foldBaseModulation, formatDuration, getDrawingType, getNativeIndicator, inputDeltas, inputVisible, legendActions, legendActionsProviderFor, legendCallouts, legendCalloutsProviderFor, lineSegmentIntersection, nativeIndicatorDescriptors, nativeIndicatorTypes, normalizeSettingsRow, pinnedTopbarActionIds, registerChartType, registerDefaultEngine, registerDrawingType, registerLegendAction, registerLegendCallout, registerNativeIndicator, registerRendererDefaults, registerRendererLayer, registerSidePanel, registerStatePersistence, registerSymbolRanking, registerWidgetAction, registerWidgetAttachment, rendererDefaults, rendererLayers, resetDrawingSettings, resolveEngines, resolveTopbarComposition, settingsRowValueKeys, settingsRowVisible, sidePanels, statePersistenceHandlers, symbolRanking, tickerModifierIds, topbarActionOverride, topbarHas, unregisterChartType, unregisterDefaultEngine, unregisterLegendAction, unregisterLegendCallout, unregisterNativeIndicator, unregisterRendererDefaults, unregisterRendererLayer, unregisterSidePanel, unregisterStatePersistence, unregisterWidgetAction, unregisterWidgetAttachment, widgetActions, widgetAttachments };
+export { AnchoredVwap, ArrowMark, Callout, CalloutBase, Comment, DEDEKIND_CURVATURE_OPTIONS, DEFAULT_DRAWING_COLOR, DEFAULT_PANEL_MAX_WIDTH, DEFAULT_PANEL_MIN_WIDTH, DEFAULT_PANEL_ORDER, DEFAULT_PANEL_WIDTH, DIRECTION_OPTIONS, DedekindTessellation, Drawing, FibRatios, FibSpiral, FixedRangeVolumeProfile, GANN_SQUARE_ARCS, GLYPH_OPTIONS, GannSquare, GlyphStamp, LINE_STYLE_OPTIONS, MACH_NUMBER_OPTIONS, MACH_WAVE_COUNT_OPTIONS, MAGNIFIER_TIMEFRAME_OPTIONS, MachFigure, Magnifier, MeasureBox, Note, OVERRIDABLE_TOPBAR_IDS, PatternDrawing, PositionTool, PriceLabel, PriceNote, RadialFib, RegressionChannel, STAMP_SIZE_OPTIONS, SegmentDrawing, SidePanel, Signpost, TEXT_SIZE_OPTIONS, TOPBAR_BUILTIN_IDS, TOPBAR_DEFAULT_LEFT, TOPBAR_DEFAULT_RIGHT, TextLabel, chartType, chartTypes, clampPanelWidth, createDrawing, deserializeDrawing, drawingTypes, foldBaseModulation, formatDuration, getDrawingType, getNativeIndicator, inputDeltas, inputVisible, legendActions, legendActionsProviderFor, legendCallouts, legendCalloutsProviderFor, lineSegmentIntersection, magnifierTimeframeLabel, nativeIndicatorDescriptors, nativeIndicatorTypes, normalizeSettingsRow, pinnedTopbarActionIds, registerChartType, registerDefaultEngine, registerDrawingType, registerLegendAction, registerLegendCallout, registerNativeIndicator, registerRendererDefaults, registerRendererLayer, registerSidePanel, registerStatePersistence, registerSymbolRanking, registerWidgetAction, registerWidgetAttachment, rendererDefaults, rendererLayers, resetDrawingSettings, resolveEngines, resolveTopbarComposition, settingsRowValueKeys, settingsRowVisible, sidePanels, statePersistenceHandlers, symbolRanking, tickerModifierIds, topbarActionOverride, topbarHas, unregisterChartType, unregisterDefaultEngine, unregisterLegendAction, unregisterLegendCallout, unregisterNativeIndicator, unregisterRendererDefaults, unregisterRendererLayer, unregisterSidePanel, unregisterStatePersistence, unregisterWidgetAction, unregisterWidgetAttachment, widgetActions, widgetAttachments };