@luxalgo/vela 0.6.5 → 0.6.7

package/dist/{contributions-DatoAzMx.d.ts → contributions-Hv4_cOJo.d.cts}

@@ -1,5 +1,5 @@
-import { t as Millis, ae as InputSchema, ac as IndicatorMeta, P as PriceStyle, O as OHLCV, m as InputValue, k as IndicatorModel, j as MoveTarget, aB as SeriesSpec, aa as Fill, B as Background, at as PriceLine, a0 as DrawingLine, Y as DrawingBox, $ as DrawingLabel, a4 as DrawingPolyline, a1 as DrawingLinefill, a6 as DrawingTable, g as IndicatorStatus, a as VisibleRange, c as VelaTheme, S as SerializedDrawing, v as DrawingTypeKey, u as SnapMode, a2 as DrawingMode, I as IChartRenderer, R as RendererCapabilities, o as LegendActionView, U as Unsubscribe, C as CrosshairEvent, A as AxisLongPressEvent, r as DataWindowReadout, n as SymbolPickerFn, aO as PaneInfo, a9 as DrawingsOption, D as Drawing, b as VelaOptions, x as AddIndicatorOptions, ap as MarketSwitch, ao as MarketSnapshot, V as VisibleRangePreset, T as ThemeName } from './options-YdiaaVjt.js';
-import { S as SymbolInfo, B as BarRange, M as MarketDataFeed, D as DataProvider, P as ProviderInfo, a as SymbolDescriptor, b as ProviderCapabilities } from './DataProvider-BmHkcwvJ.js';
+import { t as Millis, ae as InputSchema, ac as IndicatorMeta, P as PriceStyle, O as OHLCV, m as InputValue, k as IndicatorModel, j as MoveTarget, aq as PaneAxis, aD as SeriesSpec, aa as Fill, B as Background, av as PriceLine, a0 as DrawingLine, Y as DrawingBox, $ as DrawingLabel, a4 as DrawingPolyline, a1 as DrawingLinefill, a6 as DrawingTable, g as IndicatorStatus, a as VisibleRange, c as VelaTheme, S as SerializedDrawing, v as DrawingTypeKey, u as SnapMode, a2 as DrawingMode, I as IChartRenderer, R as RendererCapabilities, o as LegendActionView, U as Unsubscribe, C as CrosshairEvent, A as AxisLongPressEvent, r as DataWindowReadout, n as SymbolPickerFn, aR as PaneInfo, a9 as DrawingsOption, D as Drawing, b as VelaOptions, x as AddIndicatorOptions, ap as MarketSwitch, ao as MarketSnapshot, V as VisibleRangePreset, T as ThemeName } from './options-BaVTMXaO.cjs';
+import { S as SymbolInfo, B as BarRange, M as MarketDataFeed, D as DataProvider, P as ProviderInfo, a as SymbolDescriptor, b as ProviderCapabilities } from './DataProvider-BsQM2WNH.cjs';
 
 /**
  * A strategy's broker state at ONE bar — the flat summary a host reads while a script
@@ -361,6 +361,10 @@ declare class DataControl {
     providerInstance(name: string): DataProvider | undefined;
     /** Indexed symbols for one provider (or all) — for autocomplete. */
     symbols(provider?: string): SymbolDescriptor[];
+    /** The icon URL for `symbol` — its owning provider's `resolveSymbolIcon`, routed
+     *  through resolution. Undefined while unresolvable, when the provider declares no
+     *  resolver, or on a custom `deps.dataFeed` — the shells then show initials. */
+    symbolIcon(symbol: string): string | undefined;
     /** Per-symbol metadata (Pine `syminfo.*`), resolved through the owning provider. */
     symbolInfo(symbol: string): Promise<SymbolInfo | undefined>;
     /**
@@ -382,6 +386,13 @@ declare class DataControl {
  * columns — instead pushes its payload through the dedicated renderer seam, `pushData`.)
  */
 interface NativeIndicatorOutput {
+    /**
+     * Value-axis override for the pane this native OWNS (see `IndicatorModel.paneAxis`):
+     * `'none'` for content that is not value-mapped, or band labels for a categorical
+     * axis. Emitted per compute, so it can follow the inputs (e.g. row toggles relabel
+     * the axis). Absent ⇒ the pane derives a scale from its content as usual.
+     */
+    paneAxis?: PaneAxis;
     series?: SeriesSpec[];
     fills?: Fill[];
     backgrounds?: Background[];
@@ -753,7 +764,11 @@ interface VelaEventMap extends Record<string, unknown> {
         oldestTime: number;
         barsLoaded: number;
     };
-    alert: EngineAlert;
+    /** An indicator's script raised an alert. `indicator` names the source — the
+     *  indicator's display title (what its legend row shows). */
+    alert: EngineAlert & {
+        indicator?: string;
+    };
     warning: EngineWarning;
 }
 
@@ -928,7 +943,23 @@ declare class RendererControl {
     setSettingsSections(sections: ReadonlyArray<{
         title: string;
         rows: readonly unknown[];
+        id?: string;
     }>): this;
+    /**
+     * Set the settings-dialog visibility policy: `hidden` lists setting ids to hide —
+     * a tab (`'canvas'`), a group (`'canvas.grid'`), or a single row
+     * (`'canvas.grid.vertical'`); an id hides its whole subtree, and a tab with nothing
+     * left disappears from the rail. Presentation-only: hidden values keep being stored
+     * and applied (e.g. hide `'advanced'` while forcing the widget's `bars` option).
+     * Seeded from `VelaOptions.settings`; silent no-op without a settings dialog.
+     */
+    setSettingsVisibility(policy: {
+        hidden?: readonly string[];
+    }): this;
+    /** Every addressable setting id of this chart (built-in tabs/groups/rows, chart-type
+     *  sections, host sections) — enumerate these to build a `hidden` list instead of
+     *  reading contributor source. Empty on a renderer without a settings dialog. */
+    listSettingsIds(): string[];
     /** Tell the renderer's own chrome which size class the host shell is in —
      *  `'mobile'` switches its dialogs/toolbars to the touch-first presentation.
      *  Silent no-op on a renderer without adaptive chrome. */
@@ -1425,6 +1456,28 @@ interface WidgetContext {
     host: HTMLElement;
     /** The widget's feedback pill (bottom-center, auto-hides). */
     toast(message: string, kind?: 'info' | 'success' | 'error'): void;
+    /** Add a SCRIPT indicator to the active chart THROUGH THE SHELL — unlike the raw
+     *  `chart.addIndicator`, the addition enters the unified undo/redo timeline, the
+     *  topbar indicator count, and the shell's bookkeeping. The entry's source rides the
+     *  recorded action, so redo re-adds it even after the original handle died. The
+     *  shell does NOT persist these across reloads (they are not manifest entries) —
+     *  a plugin that wants them back owns that via {@link registerStatePersistence}. */
+    addIndicator(entry: ExternalIndicatorEntry): void;
+    /** Add a native (core-computed) indicator to the active chart through the shell —
+     *  recorded in the undo/redo timeline, unlike the raw `chart.addNativeIndicator`. */
+    addNativeIndicator(type: string): void;
+    /** Tell the shell some PERSISTABLE third-party state changed (a debounced
+     *  `state:changed` + storage write follows). Only needed for state with no shell
+     *  event of its own — indicator adds/removals already trigger the save cycle. */
+    stateChanged(): void;
+}
+/** What {@link WidgetContext.addIndicator} takes: a named script, ready to run. */
+interface ExternalIndicatorEntry {
+    name: string;
+    /** The script source (the recorded undo/redo action re-adds from it). */
+    script: string;
+    /** Engine language (default: the chart's default engine). */
+    language?: string;
 }
 /** Where an action is projected. */
 type WidgetActionTarget = 'topbar' | 'context:body' | 'context:price-axis' | 'context:time-axis';
@@ -1528,7 +1581,24 @@ declare function registerSidePanel(desc: SidePanelDescriptor): () => void;
 declare function unregisterSidePanel(id: string): void;
 /** Every registered side panel, `order`-sorted (registration order breaks ties). */
 declare function sidePanels(): SidePanelDescriptor[];
-/** Register (or replace) a widget action. Widgets read the registry live. */
+/** The built-in topbar slots a contributed action may TAKE OVER by registering under
+ *  their id — the "simple button" slots. The composites (symbol, timeframes, style,
+ *  layout, undo-redo, alerts, panels) are stateful controls the shell pushes state
+ *  into; a plain `{label, icon, run}` descriptor cannot stand in for them. */
+declare const OVERRIDABLE_TOPBAR_IDS: readonly ["indicators", "screenshot"];
+/**
+ * The action OVERRIDING a built-in topbar slot, if one is registered — an action whose
+ * `id` IS the built-in id. An override takes the slot's WHOLE surface: the desktop
+ * button (at the slot's position), the mobile counterpart, and the keyboard chord all
+ * route to `run`, and the native machinery behind the slot (the built-in indicator
+ * picker) is not constructed. Shells resolve this at construction — register at import
+ * time, like every contribution.
+ */
+declare function topbarActionOverride(id: string): WidgetActionDescriptor | undefined;
+/** Register (or replace) a widget action. Widgets read the registry live.
+ *  Registering under a RESERVED built-in topbar id (`'indicators'`, `'screenshot'`)
+ *  OVERRIDES that slot — see {@link topbarActionOverride}. Built-in ids that are
+ *  stateful composites cannot be overridden and the registration is refused. */
 declare function registerWidgetAction(desc: WidgetActionDescriptor): () => void;
 declare function unregisterWidgetAction(id: string): void;
 /** Actions for one target, `order`-sorted, `when`-filtered when a context is given. */
@@ -1565,6 +1635,83 @@ declare function registerLegendAction(desc: LegendActionDescriptor): () => void;
 declare function unregisterLegendAction(id: string): void;
 /** Every registered legend action, `order`-sorted (registration order breaks ties). */
 declare function legendActions(): LegendActionDescriptor[];
+/**
+ * The surface a `scope: 'cell'` persistence handler works against — bound to ONE cell
+ * (never the active one by proxy), because serialize/restore run per cell, including
+ * cells that are not active. `addIndicator`/`addNativeIndicator` target THIS cell and
+ * are ALWAYS muted — unlike their {@link WidgetContext} namesakes they never enter the
+ * undo timeline, even from an async `restore` continuation (fetch, then add): applying
+ * a document is state application, not a user edit.
+ */
+interface CellStateContext {
+    /** The cell's durable identity (`'c1'`, a declared name). */
+    cellId: string;
+    /** The cell's LIVE chart. */
+    chart: Vela;
+    /** Add a script indicator to THIS cell through the shell (see {@link WidgetContext.addIndicator}). */
+    addIndicator(entry: ExternalIndicatorEntry): void;
+    /** Add a native indicator to THIS cell through the shell. */
+    addNativeIndicator(type: string): void;
+}
+/**
+ * A third-party STATE PERSISTENCE handler — how a plugin puts its own state into the
+ * shell's persisted document (the `ext` bag of `WorkspaceState` / per-chart state)
+ * instead of running a parallel store. `key` is namespaced (`'vendor.feature'`) and
+ * flat — one entry per handler. `serialize` runs on every shell snapshot (`getState`,
+ * the persist write) and returns a JSON-serializable payload, or `undefined` for "no
+ * entry". `restore` runs when a document carrying the key is applied (boot restore,
+ * `applyState`) — AFTER the core state (chart alive, engines registered, indicator
+ * ledger converged) and, for cell scope, inside the cell's history-mute, so nothing it
+ * does enters undo/redo. The payload is UNTRUSTED (the codec passes `ext` through
+ * opaquely): validate it. `restore` is only called for keys present in the document.
+ *
+ * Register at import time, before shells are constructed — the rule every contribution
+ * registry shares. A key with no registered handler still round-trips verbatim, so a
+ * session without the plugin never loses its state.
+ */
+type StatePersistenceHandler = {
+    /** Namespaced entry key (`'velapro.indicators'`) — re-registering a key replaces it. */
+    key: string;
+    /** Where the entry lives: per chart (`charts[i].ext`) — follows the cell through pool/layout moves. */
+    scope: 'cell';
+    serialize(ctx: CellStateContext): unknown;
+    restore(payload: unknown, ctx: CellStateContext): void;
+} | {
+    key: string;
+    /** Document root (`state.ext`) — one entry per document, whatever the grid. */
+    scope: 'global';
+    serialize(ctx: WidgetContext): unknown;
+    restore(payload: unknown, ctx: WidgetContext): void;
+};
+/** Register (or replace) a state-persistence handler. Returns an unregister disposer. */
+declare function registerStatePersistence(handler: StatePersistenceHandler): () => void;
+declare function unregisterStatePersistence(key: string): void;
+/** The registered handlers of one scope (registration order). */
+declare function statePersistenceHandlers<S extends StatePersistenceHandler['scope']>(scope: S): Array<Extract<StatePersistenceHandler, {
+    scope: S;
+}>>;
+/**
+ * Reorder the symbol picker's AGGREGATED pool — every source combined, exactly what
+ * the search dialog displays. Called when the pool changes (a provider's index lands
+ * or refreshes), NOT per keystroke: the picker caches the result. May be async (a
+ * server-fetched top list) — the picker shows the current order and refreshes when
+ * the promise resolves.
+ *
+ * The returned list may INJECT descriptors absent from the pool (they must carry
+ * their `provider` and be genuinely servable, or selecting them parks the load) and
+ * may OMIT entries (hiding them). The picker dedupes by venue+ticker, FIRST
+ * occurrence winning — injecting at the head fixes both position and display data.
+ *
+ * While a ranking is registered, the picker's built-in empty-query pin (the hardcoded
+ * majors) stands down: the head of YOUR list is the dialog's opening screen. Under a
+ * typed query the relevance tiers still lead — the ranking orders within each tier.
+ */
+type SymbolRankingHook = (pool: SymbolDescriptor[]) => SymbolDescriptor[] | Promise<SymbolDescriptor[]>;
+/** Register (or replace — ONE ranking at a time, last wins) the symbol ranking.
+ *  Returns an unregister disposer. Register at import time, like every contribution. */
+declare function registerSymbolRanking(hook: SymbolRankingHook): () => void;
+/** The registered ranking, if any — what the shells' symbol picker consults. */
+declare function symbolRanking(): SymbolRankingHook | undefined;
 /** Makes ONE engine instance for ONE chart — engines hold per-chart sessions (and
  *  possibly a worker), so the shell calls the factory per chart build, never shares. */
 type EngineFactory = () => ScriptingEngine;
@@ -1582,4 +1729,4 @@ declare function unregisterDefaultEngine(language: string): void;
  *  language. The shell layers (widget, workspace cell) register exactly this result. */
 declare function resolveEngines(overrides?: Record<string, EngineFactory>): Record<string, EngineFactory>;
 
-export { nativeIndicatorDescriptors as $, type SidePanelHandle as A, type BarsChangeReason as B, type ContextSelect as C, type DrawingsDocument as D, type EngineAlert as E, type FetchSeries as F, type SidePanelHeader as G, type StrategyFill as H, type IndicatorHandle as I, type StrategyState as J, type StrategyTrade as K, type LegendActionDescriptor as L, type VelaDeps as M, type NativeIndicator as N, type VelaEventMap as O, type ParsedSymbol as P, type VisibleBarRange as Q, type Resolved as R, type ScriptingEngine as S, TypedEventBus as T, type WidgetActionDescriptor as U, Vela as V, type WidgetContext as W, type WidgetActionTarget as X, type WidgetAttachment as Y, getNativeIndicator as Z, legendActions as _, type ScriptRun as a, nativeIndicatorTypes as a0, registerDefaultEngine as a1, registerLegendAction as a2, registerNativeIndicator as a3, registerSidePanel as a4, registerWidgetAction as a5, registerWidgetAttachment as a6, resolveEngines as a7, sidePanels as a8, unregisterDefaultEngine as a9, unregisterLegendAction as aa, unregisterNativeIndicator as ab, unregisterSidePanel as ac, unregisterWidgetAction as ad, unregisterWidgetAttachment as ae, widgetActions as af, widgetAttachments as ag, DEFAULT_PANEL_ORDER as ah, DataControl as b, DrawingsControl as c, type EngineCapabilities as d, type EngineContextSnapshot as e, type EngineFactory as f, type EngineWarning as g, type ExecutionHandlers as h, type ExecutionMarket as i, type ExecutionRequest as j, type ExecutionSession as k, type IndicatorEventMap as l, type IndicatorSummary as m, type LegendIndicatorInfo as n, type NativeIndicatorContext as o, type NativeIndicatorDescriptor as p, type NativeIndicatorInfo as q, type NativeIndicatorOutput as r, type PreparedScript as s, RendererControl as t, type RunIndicatorResult as u, type SceneInspection as v, type ScriptRunCause as w, type ScriptRunResult as x, type SidePanelButton as y, type SidePanelDescriptor as z };
+export { type WidgetActionDescriptor as $, type SidePanelButton as A, type BarsChangeReason as B, type CellStateContext as C, type DrawingsDocument as D, type ExternalIndicatorEntry as E, type FetchSeries as F, type SidePanelDescriptor as G, type SidePanelHandle as H, type IndicatorHandle as I, type SidePanelHeader as J, type StatePersistenceHandler as K, type LegendActionDescriptor as L, type StrategyFill as M, type NativeIndicator as N, OVERRIDABLE_TOPBAR_IDS as O, type ParsedSymbol as P, type StrategyState as Q, type Resolved as R, type ScriptingEngine as S, type StrategyTrade as T, type SymbolRankingHook as U, Vela as V, type WidgetContext as W, TypedEventBus as X, type VelaDeps as Y, type VelaEventMap as Z, type VisibleBarRange as _, type ScriptRun as a, type WidgetActionTarget as a0, type WidgetAttachment as a1, getNativeIndicator as a2, legendActions as a3, nativeIndicatorDescriptors as a4, nativeIndicatorTypes as a5, registerDefaultEngine as a6, registerLegendAction as a7, registerNativeIndicator as a8, registerSidePanel as a9, registerStatePersistence as aa, registerSymbolRanking as ab, registerWidgetAction as ac, registerWidgetAttachment as ad, resolveEngines as ae, sidePanels as af, statePersistenceHandlers as ag, symbolRanking as ah, topbarActionOverride as ai, unregisterDefaultEngine as aj, unregisterLegendAction as ak, unregisterNativeIndicator as al, unregisterSidePanel as am, unregisterStatePersistence as an, unregisterWidgetAction as ao, unregisterWidgetAttachment as ap, widgetActions as aq, widgetAttachments as ar, DEFAULT_PANEL_ORDER as as, type ContextSelect as b, DataControl as c, DrawingsControl as d, type EngineAlert as e, type EngineCapabilities as f, type EngineContextSnapshot as g, type EngineFactory as h, type EngineWarning as i, type ExecutionHandlers as j, type ExecutionMarket as k, type ExecutionRequest as l, type ExecutionSession as m, type IndicatorEventMap as n, type IndicatorSummary as o, type LegendIndicatorInfo as p, type NativeIndicatorContext as q, type NativeIndicatorDescriptor as r, type NativeIndicatorInfo as s, type NativeIndicatorOutput as t, type PreparedScript as u, RendererControl as v, type RunIndicatorResult as w, type SceneInspection as x, type ScriptRunCause as y, type ScriptRunResult as z };

package/dist/{contributions-2bEmCF9S.d.cts → contributions-Z12BrWCy.d.ts}

@@ -1,5 +1,5 @@
-import { t as Millis, ae as InputSchema, ac as IndicatorMeta, P as PriceStyle, O as OHLCV, m as InputValue, k as IndicatorModel, j as MoveTarget, aB as SeriesSpec, aa as Fill, B as Background, at as PriceLine, a0 as DrawingLine, Y as DrawingBox, $ as DrawingLabel, a4 as DrawingPolyline, a1 as DrawingLinefill, a6 as DrawingTable, g as IndicatorStatus, a as VisibleRange, c as VelaTheme, S as SerializedDrawing, v as DrawingTypeKey, u as SnapMode, a2 as DrawingMode, I as IChartRenderer, R as RendererCapabilities, o as LegendActionView, U as Unsubscribe, C as CrosshairEvent, A as AxisLongPressEvent, r as DataWindowReadout, n as SymbolPickerFn, aO as PaneInfo, a9 as DrawingsOption, D as Drawing, b as VelaOptions, x as AddIndicatorOptions, ap as MarketSwitch, ao as MarketSnapshot, V as VisibleRangePreset, T as ThemeName } from './options-YdiaaVjt.cjs';
-import { S as SymbolInfo, B as BarRange, M as MarketDataFeed, D as DataProvider, P as ProviderInfo, a as SymbolDescriptor, b as ProviderCapabilities } from './DataProvider-DrN7ZIou.cjs';
+import { t as Millis, ae as InputSchema, ac as IndicatorMeta, P as PriceStyle, O as OHLCV, m as InputValue, k as IndicatorModel, j as MoveTarget, aq as PaneAxis, aD as SeriesSpec, aa as Fill, B as Background, av as PriceLine, a0 as DrawingLine, Y as DrawingBox, $ as DrawingLabel, a4 as DrawingPolyline, a1 as DrawingLinefill, a6 as DrawingTable, g as IndicatorStatus, a as VisibleRange, c as VelaTheme, S as SerializedDrawing, v as DrawingTypeKey, u as SnapMode, a2 as DrawingMode, I as IChartRenderer, R as RendererCapabilities, o as LegendActionView, U as Unsubscribe, C as CrosshairEvent, A as AxisLongPressEvent, r as DataWindowReadout, n as SymbolPickerFn, aR as PaneInfo, a9 as DrawingsOption, D as Drawing, b as VelaOptions, x as AddIndicatorOptions, ap as MarketSwitch, ao as MarketSnapshot, V as VisibleRangePreset, T as ThemeName } from './options-BaVTMXaO.js';
+import { S as SymbolInfo, B as BarRange, M as MarketDataFeed, D as DataProvider, P as ProviderInfo, a as SymbolDescriptor, b as ProviderCapabilities } from './DataProvider-BSLlBpB9.js';
 
 /**
  * A strategy's broker state at ONE bar — the flat summary a host reads while a script
@@ -361,6 +361,10 @@ declare class DataControl {
     providerInstance(name: string): DataProvider | undefined;
     /** Indexed symbols for one provider (or all) — for autocomplete. */
     symbols(provider?: string): SymbolDescriptor[];
+    /** The icon URL for `symbol` — its owning provider's `resolveSymbolIcon`, routed
+     *  through resolution. Undefined while unresolvable, when the provider declares no
+     *  resolver, or on a custom `deps.dataFeed` — the shells then show initials. */
+    symbolIcon(symbol: string): string | undefined;
     /** Per-symbol metadata (Pine `syminfo.*`), resolved through the owning provider. */
     symbolInfo(symbol: string): Promise<SymbolInfo | undefined>;
     /**
@@ -382,6 +386,13 @@ declare class DataControl {
  * columns — instead pushes its payload through the dedicated renderer seam, `pushData`.)
  */
 interface NativeIndicatorOutput {
+    /**
+     * Value-axis override for the pane this native OWNS (see `IndicatorModel.paneAxis`):
+     * `'none'` for content that is not value-mapped, or band labels for a categorical
+     * axis. Emitted per compute, so it can follow the inputs (e.g. row toggles relabel
+     * the axis). Absent ⇒ the pane derives a scale from its content as usual.
+     */
+    paneAxis?: PaneAxis;
     series?: SeriesSpec[];
     fills?: Fill[];
     backgrounds?: Background[];
@@ -753,7 +764,11 @@ interface VelaEventMap extends Record<string, unknown> {
         oldestTime: number;
         barsLoaded: number;
     };
-    alert: EngineAlert;
+    /** An indicator's script raised an alert. `indicator` names the source — the
+     *  indicator's display title (what its legend row shows). */
+    alert: EngineAlert & {
+        indicator?: string;
+    };
     warning: EngineWarning;
 }
 
@@ -928,7 +943,23 @@ declare class RendererControl {
     setSettingsSections(sections: ReadonlyArray<{
         title: string;
         rows: readonly unknown[];
+        id?: string;
     }>): this;
+    /**
+     * Set the settings-dialog visibility policy: `hidden` lists setting ids to hide —
+     * a tab (`'canvas'`), a group (`'canvas.grid'`), or a single row
+     * (`'canvas.grid.vertical'`); an id hides its whole subtree, and a tab with nothing
+     * left disappears from the rail. Presentation-only: hidden values keep being stored
+     * and applied (e.g. hide `'advanced'` while forcing the widget's `bars` option).
+     * Seeded from `VelaOptions.settings`; silent no-op without a settings dialog.
+     */
+    setSettingsVisibility(policy: {
+        hidden?: readonly string[];
+    }): this;
+    /** Every addressable setting id of this chart (built-in tabs/groups/rows, chart-type
+     *  sections, host sections) — enumerate these to build a `hidden` list instead of
+     *  reading contributor source. Empty on a renderer without a settings dialog. */
+    listSettingsIds(): string[];
     /** Tell the renderer's own chrome which size class the host shell is in —
      *  `'mobile'` switches its dialogs/toolbars to the touch-first presentation.
      *  Silent no-op on a renderer without adaptive chrome. */
@@ -1425,6 +1456,28 @@ interface WidgetContext {
     host: HTMLElement;
     /** The widget's feedback pill (bottom-center, auto-hides). */
     toast(message: string, kind?: 'info' | 'success' | 'error'): void;
+    /** Add a SCRIPT indicator to the active chart THROUGH THE SHELL — unlike the raw
+     *  `chart.addIndicator`, the addition enters the unified undo/redo timeline, the
+     *  topbar indicator count, and the shell's bookkeeping. The entry's source rides the
+     *  recorded action, so redo re-adds it even after the original handle died. The
+     *  shell does NOT persist these across reloads (they are not manifest entries) —
+     *  a plugin that wants them back owns that via {@link registerStatePersistence}. */
+    addIndicator(entry: ExternalIndicatorEntry): void;
+    /** Add a native (core-computed) indicator to the active chart through the shell —
+     *  recorded in the undo/redo timeline, unlike the raw `chart.addNativeIndicator`. */
+    addNativeIndicator(type: string): void;
+    /** Tell the shell some PERSISTABLE third-party state changed (a debounced
+     *  `state:changed` + storage write follows). Only needed for state with no shell
+     *  event of its own — indicator adds/removals already trigger the save cycle. */
+    stateChanged(): void;
+}
+/** What {@link WidgetContext.addIndicator} takes: a named script, ready to run. */
+interface ExternalIndicatorEntry {
+    name: string;
+    /** The script source (the recorded undo/redo action re-adds from it). */
+    script: string;
+    /** Engine language (default: the chart's default engine). */
+    language?: string;
 }
 /** Where an action is projected. */
 type WidgetActionTarget = 'topbar' | 'context:body' | 'context:price-axis' | 'context:time-axis';
@@ -1528,7 +1581,24 @@ declare function registerSidePanel(desc: SidePanelDescriptor): () => void;
 declare function unregisterSidePanel(id: string): void;
 /** Every registered side panel, `order`-sorted (registration order breaks ties). */
 declare function sidePanels(): SidePanelDescriptor[];
-/** Register (or replace) a widget action. Widgets read the registry live. */
+/** The built-in topbar slots a contributed action may TAKE OVER by registering under
+ *  their id — the "simple button" slots. The composites (symbol, timeframes, style,
+ *  layout, undo-redo, alerts, panels) are stateful controls the shell pushes state
+ *  into; a plain `{label, icon, run}` descriptor cannot stand in for them. */
+declare const OVERRIDABLE_TOPBAR_IDS: readonly ["indicators", "screenshot"];
+/**
+ * The action OVERRIDING a built-in topbar slot, if one is registered — an action whose
+ * `id` IS the built-in id. An override takes the slot's WHOLE surface: the desktop
+ * button (at the slot's position), the mobile counterpart, and the keyboard chord all
+ * route to `run`, and the native machinery behind the slot (the built-in indicator
+ * picker) is not constructed. Shells resolve this at construction — register at import
+ * time, like every contribution.
+ */
+declare function topbarActionOverride(id: string): WidgetActionDescriptor | undefined;
+/** Register (or replace) a widget action. Widgets read the registry live.
+ *  Registering under a RESERVED built-in topbar id (`'indicators'`, `'screenshot'`)
+ *  OVERRIDES that slot — see {@link topbarActionOverride}. Built-in ids that are
+ *  stateful composites cannot be overridden and the registration is refused. */
 declare function registerWidgetAction(desc: WidgetActionDescriptor): () => void;
 declare function unregisterWidgetAction(id: string): void;
 /** Actions for one target, `order`-sorted, `when`-filtered when a context is given. */
@@ -1565,6 +1635,83 @@ declare function registerLegendAction(desc: LegendActionDescriptor): () => void;
 declare function unregisterLegendAction(id: string): void;
 /** Every registered legend action, `order`-sorted (registration order breaks ties). */
 declare function legendActions(): LegendActionDescriptor[];
+/**
+ * The surface a `scope: 'cell'` persistence handler works against — bound to ONE cell
+ * (never the active one by proxy), because serialize/restore run per cell, including
+ * cells that are not active. `addIndicator`/`addNativeIndicator` target THIS cell and
+ * are ALWAYS muted — unlike their {@link WidgetContext} namesakes they never enter the
+ * undo timeline, even from an async `restore` continuation (fetch, then add): applying
+ * a document is state application, not a user edit.
+ */
+interface CellStateContext {
+    /** The cell's durable identity (`'c1'`, a declared name). */
+    cellId: string;
+    /** The cell's LIVE chart. */
+    chart: Vela;
+    /** Add a script indicator to THIS cell through the shell (see {@link WidgetContext.addIndicator}). */
+    addIndicator(entry: ExternalIndicatorEntry): void;
+    /** Add a native indicator to THIS cell through the shell. */
+    addNativeIndicator(type: string): void;
+}
+/**
+ * A third-party STATE PERSISTENCE handler — how a plugin puts its own state into the
+ * shell's persisted document (the `ext` bag of `WorkspaceState` / per-chart state)
+ * instead of running a parallel store. `key` is namespaced (`'vendor.feature'`) and
+ * flat — one entry per handler. `serialize` runs on every shell snapshot (`getState`,
+ * the persist write) and returns a JSON-serializable payload, or `undefined` for "no
+ * entry". `restore` runs when a document carrying the key is applied (boot restore,
+ * `applyState`) — AFTER the core state (chart alive, engines registered, indicator
+ * ledger converged) and, for cell scope, inside the cell's history-mute, so nothing it
+ * does enters undo/redo. The payload is UNTRUSTED (the codec passes `ext` through
+ * opaquely): validate it. `restore` is only called for keys present in the document.
+ *
+ * Register at import time, before shells are constructed — the rule every contribution
+ * registry shares. A key with no registered handler still round-trips verbatim, so a
+ * session without the plugin never loses its state.
+ */
+type StatePersistenceHandler = {
+    /** Namespaced entry key (`'velapro.indicators'`) — re-registering a key replaces it. */
+    key: string;
+    /** Where the entry lives: per chart (`charts[i].ext`) — follows the cell through pool/layout moves. */
+    scope: 'cell';
+    serialize(ctx: CellStateContext): unknown;
+    restore(payload: unknown, ctx: CellStateContext): void;
+} | {
+    key: string;
+    /** Document root (`state.ext`) — one entry per document, whatever the grid. */
+    scope: 'global';
+    serialize(ctx: WidgetContext): unknown;
+    restore(payload: unknown, ctx: WidgetContext): void;
+};
+/** Register (or replace) a state-persistence handler. Returns an unregister disposer. */
+declare function registerStatePersistence(handler: StatePersistenceHandler): () => void;
+declare function unregisterStatePersistence(key: string): void;
+/** The registered handlers of one scope (registration order). */
+declare function statePersistenceHandlers<S extends StatePersistenceHandler['scope']>(scope: S): Array<Extract<StatePersistenceHandler, {
+    scope: S;
+}>>;
+/**
+ * Reorder the symbol picker's AGGREGATED pool — every source combined, exactly what
+ * the search dialog displays. Called when the pool changes (a provider's index lands
+ * or refreshes), NOT per keystroke: the picker caches the result. May be async (a
+ * server-fetched top list) — the picker shows the current order and refreshes when
+ * the promise resolves.
+ *
+ * The returned list may INJECT descriptors absent from the pool (they must carry
+ * their `provider` and be genuinely servable, or selecting them parks the load) and
+ * may OMIT entries (hiding them). The picker dedupes by venue+ticker, FIRST
+ * occurrence winning — injecting at the head fixes both position and display data.
+ *
+ * While a ranking is registered, the picker's built-in empty-query pin (the hardcoded
+ * majors) stands down: the head of YOUR list is the dialog's opening screen. Under a
+ * typed query the relevance tiers still lead — the ranking orders within each tier.
+ */
+type SymbolRankingHook = (pool: SymbolDescriptor[]) => SymbolDescriptor[] | Promise<SymbolDescriptor[]>;
+/** Register (or replace — ONE ranking at a time, last wins) the symbol ranking.
+ *  Returns an unregister disposer. Register at import time, like every contribution. */
+declare function registerSymbolRanking(hook: SymbolRankingHook): () => void;
+/** The registered ranking, if any — what the shells' symbol picker consults. */
+declare function symbolRanking(): SymbolRankingHook | undefined;
 /** Makes ONE engine instance for ONE chart — engines hold per-chart sessions (and
  *  possibly a worker), so the shell calls the factory per chart build, never shares. */
 type EngineFactory = () => ScriptingEngine;
@@ -1582,4 +1729,4 @@ declare function unregisterDefaultEngine(language: string): void;
  *  language. The shell layers (widget, workspace cell) register exactly this result. */
 declare function resolveEngines(overrides?: Record<string, EngineFactory>): Record<string, EngineFactory>;
 
-export { nativeIndicatorDescriptors as $, type SidePanelHandle as A, type BarsChangeReason as B, type ContextSelect as C, type DrawingsDocument as D, type EngineAlert as E, type FetchSeries as F, type SidePanelHeader as G, type StrategyFill as H, type IndicatorHandle as I, type StrategyState as J, type StrategyTrade as K, type LegendActionDescriptor as L, type VelaDeps as M, type NativeIndicator as N, type VelaEventMap as O, type ParsedSymbol as P, type VisibleBarRange as Q, type Resolved as R, type ScriptingEngine as S, TypedEventBus as T, type WidgetActionDescriptor as U, Vela as V, type WidgetContext as W, type WidgetActionTarget as X, type WidgetAttachment as Y, getNativeIndicator as Z, legendActions as _, type ScriptRun as a, nativeIndicatorTypes as a0, registerDefaultEngine as a1, registerLegendAction as a2, registerNativeIndicator as a3, registerSidePanel as a4, registerWidgetAction as a5, registerWidgetAttachment as a6, resolveEngines as a7, sidePanels as a8, unregisterDefaultEngine as a9, unregisterLegendAction as aa, unregisterNativeIndicator as ab, unregisterSidePanel as ac, unregisterWidgetAction as ad, unregisterWidgetAttachment as ae, widgetActions as af, widgetAttachments as ag, DEFAULT_PANEL_ORDER as ah, DataControl as b, DrawingsControl as c, type EngineCapabilities as d, type EngineContextSnapshot as e, type EngineFactory as f, type EngineWarning as g, type ExecutionHandlers as h, type ExecutionMarket as i, type ExecutionRequest as j, type ExecutionSession as k, type IndicatorEventMap as l, type IndicatorSummary as m, type LegendIndicatorInfo as n, type NativeIndicatorContext as o, type NativeIndicatorDescriptor as p, type NativeIndicatorInfo as q, type NativeIndicatorOutput as r, type PreparedScript as s, RendererControl as t, type RunIndicatorResult as u, type SceneInspection as v, type ScriptRunCause as w, type ScriptRunResult as x, type SidePanelButton as y, type SidePanelDescriptor as z };
+export { type WidgetActionDescriptor as $, type SidePanelButton as A, type BarsChangeReason as B, type CellStateContext as C, type DrawingsDocument as D, type ExternalIndicatorEntry as E, type FetchSeries as F, type SidePanelDescriptor as G, type SidePanelHandle as H, type IndicatorHandle as I, type SidePanelHeader as J, type StatePersistenceHandler as K, type LegendActionDescriptor as L, type StrategyFill as M, type NativeIndicator as N, OVERRIDABLE_TOPBAR_IDS as O, type ParsedSymbol as P, type StrategyState as Q, type Resolved as R, type ScriptingEngine as S, type StrategyTrade as T, type SymbolRankingHook as U, Vela as V, type WidgetContext as W, TypedEventBus as X, type VelaDeps as Y, type VelaEventMap as Z, type VisibleBarRange as _, type ScriptRun as a, type WidgetActionTarget as a0, type WidgetAttachment as a1, getNativeIndicator as a2, legendActions as a3, nativeIndicatorDescriptors as a4, nativeIndicatorTypes as a5, registerDefaultEngine as a6, registerLegendAction as a7, registerNativeIndicator as a8, registerSidePanel as a9, registerStatePersistence as aa, registerSymbolRanking as ab, registerWidgetAction as ac, registerWidgetAttachment as ad, resolveEngines as ae, sidePanels as af, statePersistenceHandlers as ag, symbolRanking as ah, topbarActionOverride as ai, unregisterDefaultEngine as aj, unregisterLegendAction as ak, unregisterNativeIndicator as al, unregisterSidePanel as am, unregisterStatePersistence as an, unregisterWidgetAction as ao, unregisterWidgetAttachment as ap, widgetActions as aq, widgetAttachments as ar, DEFAULT_PANEL_ORDER as as, type ContextSelect as b, DataControl as c, DrawingsControl as d, type EngineAlert as e, type EngineCapabilities as f, type EngineContextSnapshot as g, type EngineFactory as h, type EngineWarning as i, type ExecutionHandlers as j, type ExecutionMarket as k, type ExecutionRequest as l, type ExecutionSession as m, type IndicatorEventMap as n, type IndicatorSummary as o, type LegendIndicatorInfo as p, type NativeIndicatorContext as q, type NativeIndicatorDescriptor as r, type NativeIndicatorInfo as s, type NativeIndicatorOutput as t, type PreparedScript as u, RendererControl as v, type RunIndicatorResult as w, type SceneInspection as x, type ScriptRunCause as y, type ScriptRunResult as z };