@luxalgo/vela 0.5.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,28 @@
+Vela
+Copyright (c) 2026 LuxAlgo
+https://luxalgo.com/vela
+
+This product includes the Vela charting library, developed by LuxAlgo.
+
+ATTRIBUTION REQUIREMENT
+
+Any product, website, or application that displays charts rendered by this
+software must show a visible attribution to the Vela project on every page or
+screen where such a chart is displayed.
+
+The library satisfies this requirement automatically: it renders an attribution
+mark (the project logomark linking to the Vela project page) on the chart
+itself, enabled by default. You may restyle or reposition this mark to fit your
+design.
+
+You may disable the built-in mark (renderer feature `attribution`) ONLY if you
+display an equivalent visible attribution — the name "Vela" together with a
+link to the project page above — elsewhere on the same page or screen, in a
+place available to your users.
+
+Removing, hiding, or obscuring the attribution without providing the
+equivalent notice described above is not permitted.
+
+This file constitutes the NOTICE file described in Section 4(d) of the Apache
+License, Version 2.0: redistributions of this software, in source or binary
+form, must include a readable copy of these attribution notices.

package/README.md

@@ -0,0 +1,135 @@
+# Vela
+
+A fast, extensible financial charting library with its own native canvas renderer, a
+headless core, a batteries-included widget, and a plugin SDK for custom chart types and
+renderer layers.
+
+- **`vela`** — the headless chart: data model, engines, drawings, providers, native renderer.
+- **`vela/widget`** — the full chart app: topbar (symbol / timeframe / style / indicators),
+  status line, watermark, bottom bar (ranges, clock, timezone), object tree, keyboard-first UX.
+- **`vela/ui`** — the component kit the widget is built on (design tokens + headless
+  [Zag.js](https://zagjs.com) machines + vanilla views) and the `KeymapManager`.
+- **`vela/plugin`** — the extension SDK: chart types, renderer layers, native indicators.
+- **`vela/workspace`** — the multi-chart shell: a grid of full charts under one shared
+  topbar, with named cells, sync groups and one persisted state document.
+- **`vela/providers/*`** — data providers (Binance, Coinbase, Hyperliquid).
+
+## Quick start
+
+```ts
+import { VelaWidget } from 'vela/widget';
+import { BinanceProvider } from 'vela/providers/binance';
+
+const widget = new VelaWidget('#chart', {
+    symbol: 'BTCUSDT', // bare = first declared provider listing it; 'binance:BTCUSDT' pins the venue
+    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
+    urlState: true,  // ?symbol=…&interval=… shareable links
+});
+```
+
+Prefer full control? Use the headless core directly:
+
+```ts
+import { Vela } from 'vela';
+import { BinanceProvider } from 'vela/providers/binance';
+
+const chart = new Vela('#chart', { symbol: 'binance:BTCUSDT', timeframe: '60', live: true });
+chart.data.registerProvider('binance', new BinanceProvider());
+await chart.ready();
+```
+
+## Indicators
+
+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:
+
+```ts
+import { PineEngine } from '@luxalgo/vela-pinets';
+
+chart.registerEngine('pine', new PineEngine());
+chart.addIndicator(`//@version=5
+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
+[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 widget takes an **indicator manifest** — inline JSON, a URL returning it, or an async
+loader (`() => Promise<manifest>`):
+
+```ts
+new VelaWidget('#chart', {
+    // …
+    engines: { pine: () => new PineEngine() },
+    indicators: '/indicators.json', // or an inline [{ name, script | url, language?, enabled? }]
+});
+```
+
+## 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
+(`widget.keymap.register({...})`) — plugins register theirs the same way.
+
+## Extending (plugin SDK)
+
+```ts
+import { registerChartType, registerRendererLayer } from 'vela/plugin';
+
+// A new price style: bar transform + optional per-bar data engine + ticker modifier.
+registerChartType({
+    id: 'renko-like',
+    label: 'Renko-like',
+    barTransform: { full: (bars) => transformAll(bars), next: (bar) => transformOne(bar) },
+});
+
+// A custom canvas layer, painted every frame with the chart (its id = its data channel).
+registerRendererLayer({
+    id: 'renko-like',
+    placement: 'above-data',
+    create: () => ({ mount(canvas) {/* keep it */}, render({ bars, data, coords, scale, bounds }) {/* paint */} }),
+});
+```
+
+A registered chart type automatically appears in the widget's style dropdown; 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),
+[the widget](docs/user/widget.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).
+
+## Development
+
+```bash
+npm install
+npm run playground   # vite playground on http://localhost:5190
+npm test             # vitest
+npm run build        # tsup → dist/
+```
+
+## License
+
+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.
+
+No scripting engine ships with this package; the Pine Script addon
+(`@luxalgo/vela-pinets`) is AGPL-3.0 and licensed separately (see *Indicators*).

package/dist/DataProvider-DKNDHpNv.d.cts

@@ -0,0 +1,134 @@
+import { M as MarketConfig, O as OHLCV, U as Unsubscribe } from './options-Q-576hIi.cjs';
+
+/**
+ * Symbol metadata an engine may need (e.g. Pine `syminfo.*`). Free-form beyond
+ * `ticker` — engines read the keys they understand and synthesize a fallback for
+ * the rest.
+ */
+interface SymbolInfo {
+    ticker: string;
+    [key: string]: unknown;
+}
+/**
+ * The market-data abstraction. Vela OWNS the candles: it loads history and
+ * streams live ticks through this port, holds the one canonical bar array, and
+ * hands it to whichever engine executes. Decoupled from scripting so every
+ * registered engine shares the same dataset (no per-engine re-fetch).
+ *
+ * Swappable: the default is `MultiProviderFeed` (a registry of `DataProvider`s); tests
+ * inject a fake; a host app can supply its own backend.
+ */
+/** A bounded fetch window (epoch ms). `from`/`to` inclusive-ish; `limit` caps the count. */
+interface BarRange {
+    /** Oldest bar open-time to fetch from (inclusive). */
+    from?: number;
+    /** Newest bar open-time to fetch to (defaults to "now" when omitted). */
+    to?: number;
+    /** Max bars. */
+    limit?: number;
+}
+interface MarketDataFeed {
+    /** Load the initial history (from a provider or the offline `data` array). */
+    load(cfg: MarketConfig): Promise<OHLCV[]>;
+    /** Subscribe to live forming-candle ticks. Returns an unsubscribe fn. */
+    subscribe(cfg: MarketConfig, onBar: (bar: OHLCV) => void): Unsubscribe;
+    /** Optional symbol metadata for engines that need it; absent/undefined ≡ engine synthesizes. */
+    symbolInfo?(cfg: MarketConfig): SymbolInfo | undefined;
+    /**
+     * Fetch a bounded range. Used by the cache to pull ONLY the uncached tail
+     * (newly-closed + forming bars) instead of re-downloading the whole window.
+     * Absent ≡ no ranged support; the cache falls back to a full `load`.
+     */
+    loadRange?(cfg: MarketConfig, range: BarRange): Promise<OHLCV[]>;
+    /**
+     * Report that a symbol cannot be served by anything registered — the load is PARKED
+     * (it resumes if a capable provider registers later). Hosts surface this instead of
+     * leaving a silently blank chart. Absent ≡ the feed never parks.
+     */
+    onUnresolved?(cb: (info: {
+        symbol: string;
+        providers: string[];
+    }) => void): Unsubscribe;
+    /** Release feed-owned resources (parked waits, timers). Absent ≡ nothing to release. */
+    destroy?(): void;
+}
+
+/**
+ * A descriptor for one symbol a provider serves. Powers the eager index built at
+ * registration (for bare-symbol resolution) and symbol autocomplete.
+ */
+interface SymbolDescriptor {
+    /** The ticker exactly as the provider expects it (e.g. `BTCUSDT`, `BTCUSDT.P`). */
+    ticker: string;
+    /** Human-readable label (e.g. `Bitcoin / TetherUS`). */
+    description?: string;
+    /** Instrument class, free-form (e.g. `crypto`, `futures`, `stock`). */
+    type?: string;
+    /** Owning provider name — annotated by the registry aggregation (badges in pickers). */
+    provider?: string;
+}
+/** What a provider can do — lets the registry/UI reason without provider-specific checks. */
+interface ProviderCapabilities {
+    /** Implements `listSymbols()` (enumeration → eager index + autocomplete). */
+    enumerate: boolean;
+    /** Implements `subscribe()` (true streaming; otherwise the feed polls `getBars`). */
+    stream: boolean;
+    /** Implements `getSymbolInfo()` (per-symbol metadata for engine `syminfo.*`). */
+    symbolInfo: boolean;
+}
+/** Provider metadata, surfaced via `chart.data.providers()`. */
+interface ProviderInfo {
+    /** Stable id (the registration name, lower-cased). */
+    name: string;
+    /** Display label (e.g. `Binance`). */
+    displayName?: string;
+    /** Whether the provider needs `configure()` before use. */
+    requiresApiKey?: boolean;
+    /** Timeframes the provider serves (canonical strings); informational. */
+    supportedTimeframes?: readonly string[];
+    capabilities: ProviderCapabilities;
+}
+/**
+ * A market-data source for ONE venue, neutral to Vela (no scripting-engine types). Register
+ * one with `chart.data.registerProvider(name, provider)`; the registry routes any
+ * `name:SYMBOL` (or bare `SYMBOL` it indexes) to it.
+ *
+ * Only `getBars` is required. Everything else is a progressive capability the
+ * registry uses when present and degrades around when absent — the same
+ * philosophy as the {@link MarketDataFeed} port.
+ */
+interface DataProvider {
+    /**
+     * Fetch bars for `ticker`/`timeframe`. `ticker` is exactly what the user typed
+     * minus any `provider:` prefix; any `.ext` suffix is KEPT (the provider owns its
+     * meaning — e.g. Binance `.P` = perpetual). The newest bar is treated as the
+     * forming candle. Bars: `{ time (open, epoch ms), open, high, low, close, volume? }`,
+     * sorted + de-duplicated by open-time.
+     */
+    getBars(ticker: string, timeframe: string, range: BarRange): Promise<OHLCV[]>;
+    /** Provider metadata. Absent ⇒ the registry synthesizes a record from the methods present. */
+    info?(): ProviderInfo;
+    /**
+     * Enumerate the symbols this provider serves — drives the eager index built when
+     * the provider registers. Absent ⇒ no index: the provider can only be reached by
+     * an explicit `name:SYMBOL` prefix, never by resolving a bare symbol.
+     */
+    listSymbols?(): Promise<SymbolDescriptor[]>;
+    /** Per-symbol metadata for engine `syminfo.*`. Absent ⇒ the engine synthesizes a fallback. */
+    getSymbolInfo?(ticker: string): Promise<SymbolInfo | undefined>;
+    /**
+     * Open a true live stream for `ticker`/`timeframe`. Each call to `onBar` delivers
+     * the forming candle (or a freshly-closed one). Returns an unsubscribe fn. Absent
+     * ⇒ the feed polls `getBars` for ticks instead.
+     */
+    subscribe?(ticker: string, timeframe: string, onBar: (bar: OHLCV) => void): Unsubscribe;
+    /** Apply runtime config (e.g. API keys). Absent ⇒ no configuration needed. */
+    configure?(config: unknown): void;
+    /**
+     * Capabilities for ONE ticker, when they vary by instrument class within the venue.
+     * Absent ⇒ {@link ProviderInfo.capabilities} applies uniformly to every symbol.
+     */
+    capabilitiesFor?(ticker: string): ProviderCapabilities;
+}
+
+export type { BarRange as B, DataProvider as D, MarketDataFeed as M, ProviderInfo as P, SymbolInfo as S, SymbolDescriptor as a, ProviderCapabilities as b };

package/dist/DataProvider-Dzd-Erlk.d.ts

@@ -0,0 +1,134 @@
+import { M as MarketConfig, O as OHLCV, U as Unsubscribe } from './options-Q-576hIi.js';
+
+/**
+ * Symbol metadata an engine may need (e.g. Pine `syminfo.*`). Free-form beyond
+ * `ticker` — engines read the keys they understand and synthesize a fallback for
+ * the rest.
+ */
+interface SymbolInfo {
+    ticker: string;
+    [key: string]: unknown;
+}
+/**
+ * The market-data abstraction. Vela OWNS the candles: it loads history and
+ * streams live ticks through this port, holds the one canonical bar array, and
+ * hands it to whichever engine executes. Decoupled from scripting so every
+ * registered engine shares the same dataset (no per-engine re-fetch).
+ *
+ * Swappable: the default is `MultiProviderFeed` (a registry of `DataProvider`s); tests
+ * inject a fake; a host app can supply its own backend.
+ */
+/** A bounded fetch window (epoch ms). `from`/`to` inclusive-ish; `limit` caps the count. */
+interface BarRange {
+    /** Oldest bar open-time to fetch from (inclusive). */
+    from?: number;
+    /** Newest bar open-time to fetch to (defaults to "now" when omitted). */
+    to?: number;
+    /** Max bars. */
+    limit?: number;
+}
+interface MarketDataFeed {
+    /** Load the initial history (from a provider or the offline `data` array). */
+    load(cfg: MarketConfig): Promise<OHLCV[]>;
+    /** Subscribe to live forming-candle ticks. Returns an unsubscribe fn. */
+    subscribe(cfg: MarketConfig, onBar: (bar: OHLCV) => void): Unsubscribe;
+    /** Optional symbol metadata for engines that need it; absent/undefined ≡ engine synthesizes. */
+    symbolInfo?(cfg: MarketConfig): SymbolInfo | undefined;
+    /**
+     * Fetch a bounded range. Used by the cache to pull ONLY the uncached tail
+     * (newly-closed + forming bars) instead of re-downloading the whole window.
+     * Absent ≡ no ranged support; the cache falls back to a full `load`.
+     */
+    loadRange?(cfg: MarketConfig, range: BarRange): Promise<OHLCV[]>;
+    /**
+     * Report that a symbol cannot be served by anything registered — the load is PARKED
+     * (it resumes if a capable provider registers later). Hosts surface this instead of
+     * leaving a silently blank chart. Absent ≡ the feed never parks.
+     */
+    onUnresolved?(cb: (info: {
+        symbol: string;
+        providers: string[];
+    }) => void): Unsubscribe;
+    /** Release feed-owned resources (parked waits, timers). Absent ≡ nothing to release. */
+    destroy?(): void;
+}
+
+/**
+ * A descriptor for one symbol a provider serves. Powers the eager index built at
+ * registration (for bare-symbol resolution) and symbol autocomplete.
+ */
+interface SymbolDescriptor {
+    /** The ticker exactly as the provider expects it (e.g. `BTCUSDT`, `BTCUSDT.P`). */
+    ticker: string;
+    /** Human-readable label (e.g. `Bitcoin / TetherUS`). */
+    description?: string;
+    /** Instrument class, free-form (e.g. `crypto`, `futures`, `stock`). */
+    type?: string;
+    /** Owning provider name — annotated by the registry aggregation (badges in pickers). */
+    provider?: string;
+}
+/** What a provider can do — lets the registry/UI reason without provider-specific checks. */
+interface ProviderCapabilities {
+    /** Implements `listSymbols()` (enumeration → eager index + autocomplete). */
+    enumerate: boolean;
+    /** Implements `subscribe()` (true streaming; otherwise the feed polls `getBars`). */
+    stream: boolean;
+    /** Implements `getSymbolInfo()` (per-symbol metadata for engine `syminfo.*`). */
+    symbolInfo: boolean;
+}
+/** Provider metadata, surfaced via `chart.data.providers()`. */
+interface ProviderInfo {
+    /** Stable id (the registration name, lower-cased). */
+    name: string;
+    /** Display label (e.g. `Binance`). */
+    displayName?: string;
+    /** Whether the provider needs `configure()` before use. */
+    requiresApiKey?: boolean;
+    /** Timeframes the provider serves (canonical strings); informational. */
+    supportedTimeframes?: readonly string[];
+    capabilities: ProviderCapabilities;
+}
+/**
+ * A market-data source for ONE venue, neutral to Vela (no scripting-engine types). Register
+ * one with `chart.data.registerProvider(name, provider)`; the registry routes any
+ * `name:SYMBOL` (or bare `SYMBOL` it indexes) to it.
+ *
+ * Only `getBars` is required. Everything else is a progressive capability the
+ * registry uses when present and degrades around when absent — the same
+ * philosophy as the {@link MarketDataFeed} port.
+ */
+interface DataProvider {
+    /**
+     * Fetch bars for `ticker`/`timeframe`. `ticker` is exactly what the user typed
+     * minus any `provider:` prefix; any `.ext` suffix is KEPT (the provider owns its
+     * meaning — e.g. Binance `.P` = perpetual). The newest bar is treated as the
+     * forming candle. Bars: `{ time (open, epoch ms), open, high, low, close, volume? }`,
+     * sorted + de-duplicated by open-time.
+     */
+    getBars(ticker: string, timeframe: string, range: BarRange): Promise<OHLCV[]>;
+    /** Provider metadata. Absent ⇒ the registry synthesizes a record from the methods present. */
+    info?(): ProviderInfo;
+    /**
+     * Enumerate the symbols this provider serves — drives the eager index built when
+     * the provider registers. Absent ⇒ no index: the provider can only be reached by
+     * an explicit `name:SYMBOL` prefix, never by resolving a bare symbol.
+     */
+    listSymbols?(): Promise<SymbolDescriptor[]>;
+    /** Per-symbol metadata for engine `syminfo.*`. Absent ⇒ the engine synthesizes a fallback. */
+    getSymbolInfo?(ticker: string): Promise<SymbolInfo | undefined>;
+    /**
+     * Open a true live stream for `ticker`/`timeframe`. Each call to `onBar` delivers
+     * the forming candle (or a freshly-closed one). Returns an unsubscribe fn. Absent
+     * ⇒ the feed polls `getBars` for ticks instead.
+     */
+    subscribe?(ticker: string, timeframe: string, onBar: (bar: OHLCV) => void): Unsubscribe;
+    /** Apply runtime config (e.g. API keys). Absent ⇒ no configuration needed. */
+    configure?(config: unknown): void;
+    /**
+     * Capabilities for ONE ticker, when they vary by instrument class within the venue.
+     * Absent ⇒ {@link ProviderInfo.capabilities} applies uniformly to every symbol.
+     */
+    capabilitiesFor?(ticker: string): ProviderCapabilities;
+}
+
+export type { BarRange as B, DataProvider as D, MarketDataFeed as M, ProviderInfo as P, SymbolInfo as S, SymbolDescriptor as a, ProviderCapabilities as b };