@luxalgo/vela 0.6.4 → 0.6.6

package/dist/workspace.d.cts

@@ -1,9 +1,9 @@
-import { O as OHLCV, V as VisibleRangePreset, a as VisibleRange, b as VelaOptions, c as VelaTheme, N as NativeBackend, d as MarketSession } from './options-YdiaaVjt.cjs';
-import { S as SyncSetting, V as VelaStorage, C as CellState, W as WidgetHistory, R as ResolvedIndicator, a as RangePreset, T as TrackSizes, b as VelaShellOptions, c as SyncOptions, d as SyncKind, e as WorkspaceState } from './history-BmyjaVir.cjs';
-export { f as ChartState, P as PanelsState, g as decodeState, h as encodeState, s as sanitizeState } from './history-BmyjaVir.cjs';
+import { O as OHLCV, V as VisibleRangePreset, a as VisibleRange, b as VelaOptions, c as VelaTheme, N as NativeBackend, d as MarketSession } from './options-BaVTMXaO.cjs';
+import { S as SyncSetting, V as VelaStorage, C as CellState, W as WidgetHistory, R as ResolvedIndicator, a as RangePreset, T as TrackSizes, b as VelaShellOptions, c as SyncOptions, d as SyncKind, e as WorkspaceState } from './bottombar-DeDXbF_K.cjs';
+export { f as ChartState, P as PanelsState, g as decodeState, h as encodeState, s as sanitizeState } from './bottombar-DeDXbF_K.cjs';
 import { K as KeymapManager } from './keymap-CGOz5F5f.cjs';
-import { I as IndicatorHandle, S as ScriptingEngine, W as WidgetContext, V as Vela, a as ScriptRun } from './contributions-2bEmCF9S.cjs';
-import { M as MarketDataFeed } from './DataProvider-DrN7ZIou.cjs';
+import { I as IndicatorHandle, S as ScriptingEngine, W as WidgetContext, V as Vela, E as ExternalIndicatorEntry, a as ScriptRun } from './contributions-DNMqrAuw.cjs';
+import { M as MarketDataFeed } from './DataProvider-DDUYw2qP.cjs';
 
 /** The cells that follow `originId` under `setting` — PURE (never includes the origin). */
 declare function syncTargets(originId: string, setting: SyncSetting | undefined, cellIds: readonly string[]): string[];
@@ -53,7 +53,7 @@ type CellBoot = PooledCellState & Pick<CellSeed, 'data' | 'visibleRange'>;
  *  `nativeBackend` (the WebGL budget policy, explicit value resolved upstream), the
  *  market/view seeds (those flow through {@link CellSeed}), and `drawings`' toolbar
  *  sub-key (see {@link cellDrawings}). */
-type CellChartDefaults = Pick<VelaOptions, 'renderer' | 'defaultLanguage' | 'currentPriceLine' | 'logScale' | 'animations' | 'glow' | 'upColor' | 'downColor' | 'drawings'>;
+type CellChartDefaults = Pick<VelaOptions, 'renderer' | 'defaultLanguage' | 'currentPriceLine' | 'logScale' | 'animations' | 'glow' | 'upColor' | 'downColor' | 'drawings' | 'settings'>;
 /** One entry of the shared indicator picker's native catalog, per cell. */
 interface CellNativeInfo {
     type: string;
@@ -102,6 +102,8 @@ interface CellDeps {
     /** Persistable per-cell state changed outside the market/indicator channels
      *  (bars budget, watermark/titles toggles) — the workspace debounces a save. */
     onStateDirty(): void;
+    /** The shell's toast surface (unresolved-symbol notices land there). */
+    toast(message: string, kind: 'info' | 'success' | 'error', durationMs?: number): void;
 }
 declare class ChartCell {
     readonly id: string;
@@ -110,10 +112,15 @@ declare class ChartCell {
     readonly host: HTMLElement;
     /** This cell's unified app+drawings undo timeline (the shared Ctrl+Z routes here). */
     readonly history: WidgetHistory;
-    /** Live manifest-indicator instances on this cell (the SAME entry may repeat). */
+    /** Live manifest-indicator instances on this cell (the SAME entry may repeat).
+     *  `external` marks instances added through the public seam (`ctx.addIndicator`)
+     *  rather than the shell manifest — they share the undo/redo and picker plumbing
+     *  but stay OUT of the persisted ledger (their names would never resolve against
+     *  the manifest); persisting them is their plugin's job (`registerStatePersistence`). */
     readonly instances: Array<{
         entry: ResolvedIndicator;
         handle: IndicatorHandle | null;
+        external?: boolean;
     }>;
     /** The native-indicator catalog with this cell's live supported/present flags. */
     nativeCatalog: CellNativeInfo[];
@@ -146,13 +153,22 @@ declare class ChartCell {
     /** The volume auto-add rides the cell's first candles (`load:end`); until then the
      *  registry can't show it and the dehydrated ledger reports the INTENT instead. */
     private volumeMayBePending;
-    /** Volume intent: the seed's ledger, else the workspace `volume` option. */
-    private readonly volumeIntent;
+    /** Volume intent: the seed's ledger, else the workspace `volume` option — a
+     *  rehydrated ledger overwrites it (see {@link applyIndicatorLedger}). */
+    private volumeIntent;
     /** Sync mirror of the chart's present native types — the removal handler diffs
      *  against it to identify (and record) whichever type was just removed. */
     private presentNatives;
     private rangeBars;
     private pendingRange;
+    /** Last symbol we toasted "no provider serves this" for — once per symbol (the
+     *  core re-reports on every provider-index settle). */
+    private unresolvedToasted;
+    /** The cell's third-party state bag (`ext` of the persisted per-chart state) —
+     *  seeded from the boot/restored document, refreshed by handler `serialize` calls at
+     *  dehydrate time. Entries with no registered handler this session ride along
+     *  verbatim, so a document never loses a plugin's state in the plugin's absence. */
+    private extState;
     private watermarkOn;
     /** Indicator titles (this cell's in-chart legend rows) shown. */
     private indicatorTitlesOn;
@@ -232,6 +248,14 @@ declare class ChartCell {
      * entries (fresh cells only).
      */
     setManifest(list: readonly ResolvedIndicator[], seedEnabled: boolean): void;
+    /**
+     * Replace the indicator ledger: natives converge to the listed set (volume
+     * included — removing it sticks, the core's auto-add respects the opt-out), and
+     * manifest instances are re-created by name, held until the shared manifest
+     * resolves. Convergence is state application, not user edits — nothing enters the
+     * undo timeline.
+     */
+    private applyIndicatorLedger;
     /** The picker's library rows: supported natives first, then the manifest. */
     libraryRows(): Array<{
         name: string;
@@ -252,9 +276,18 @@ declare class ChartCell {
     addFromLibrary(index: number): void;
     /** Remove by picker ON-CHART index (present natives precede instances). */
     removeFromChart(index: number): void;
+    /**
+     * Add a script indicator through the PUBLIC seam (`ctx.addIndicator`) — same undo/
+     * redo and picker plumbing as a manifest entry, but flagged `external` so the
+     * persisted ledger never records a name the manifest can't resolve (the plugin owns
+     * persistence via `registerStatePersistence`). Recording follows the ambient mute:
+     * a persistence handler's `restore` runs silently, a user-driven call records.
+     */
+    addExternalIndicator(entry: ExternalIndicatorEntry): void;
     /** Add ONE instance of a manifest entry (repeatable — duplicates are legitimate). */
     addManifestInstance(entry: ResolvedIndicator, opts?: {
         record?: boolean;
+        external?: boolean;
     }): void;
     private removeInstance;
     private dropInstance;
@@ -267,6 +300,33 @@ declare class ChartCell {
     /** Refresh the native catalog (supported/present flags) for this cell's market. */
     refreshNativeCatalog(): void;
     private addToChart;
+    /** The cell-bound surface persistence handlers work against (built per call — the
+     *  widget-context rule; nothing here may be cached by a handler). Its add methods
+     *  are ALWAYS muted — a `restore` that fetches before adding escapes the sync mute
+     *  of {@link restorePersistedExt}, and a state application must never enter the
+     *  undo timeline, however late its continuation lands. */
+    private stateContext;
+    /**
+     * Run the registered cell-scope `restore` handlers against the cell's restored
+     * `ext` bag — the workspace calls this AFTER the core state is in place (chart
+     * alive and wired, indicator ledger converged). Muted: nothing a restore does
+     * enters the undo timeline. Handlers only see keys the document carries; a failing
+     * handler is contained (one broken plugin must not take the cell down).
+     */
+    restorePersistedExt(): void;
+    /** Assemble the cell's `ext` bag: fresh handler snapshots merged OVER the preserved
+     *  entries — a key with no handler this session rides along verbatim; a registered
+     *  handler returning `undefined` withdraws its entry. */
+    private dehydrateExt;
+    /**
+     * Apply a restored cell state IN PLACE — the chart instance survives (the market
+     * switches via `setMarket`) while cosmetics, renderer config, drawings, and the
+     * indicator ledger converge to the document. The workspace takes this path when a
+     * state document lands on a grid of the same shape (async-storage boot, host
+     * `applyState`), so chart references, indicator handles, event subscriptions, and
+     * the cell host all stay valid.
+     */
+    rehydrate(cs: CellState): void;
     /** Snapshot everything the pool needs to restore this slot later. The market fields
      *  come from the LIVE config (`chart.market`) — the requested identity — so a switch
      *  still loading when the snapshot is taken (persist-on-close) is not lost. */
@@ -369,8 +429,15 @@ declare function activeAfterLayout(current: string | null, cellIds: readonly str
  */
 interface VelaWorkspaceOptions extends Omit<VelaOptions, 'height'>, VelaShellOptions {
     /** Initial layout — a registered id (`'1'`, `'2h'`, `'2v'`, `'4'`, `'8'`, or a
-     *  plugin-registered one) or an inline definition. Default `'4'`. */
-    layout?: string | LayoutDefinition;
+     *  plugin-registered one) or an inline definition. Default `'4'`.
+     *
+     *  `false` = SINGLE-CHART mode: the grid is pinned to the one-cell layout, the
+     *  layout picker disappears from the topbar and the mobile drawer (the sync
+     *  switches with it — meaningless with one cell), `setLayout` becomes a no-op,
+     *  and a restored document keeps only its first chart live (the rest stays
+     *  dormant in the pool). No `cells` entry is needed — the top-level chart
+     *  options seed the single chart. */
+    layout?: string | LayoutDefinition | false;
     /** Per-cell overrides of the top-level chart defaults, keyed by a FREE-FORM cell
      *  name — the name is the cell's durable IDENTITY (persistence, `sync` groups,
      *  `ws.cell(name)`), never its position: DECLARATION ORDER fills the layout's
@@ -396,6 +463,8 @@ interface VelaWorkspaceOptions extends Omit<VelaOptions, 'height'>, VelaShellOpt
      *  the browser's WebGL-context budget; glow is unavailable there). Default 8; an
      *  explicit `nativeBackend` other than `'auto'` wins over this policy. */
     maxWebglCells?: number;
+    /** How many alerts the topbar bell keeps (the oldest drop beyond it). Default 50. */
+    alertCap?: number;
 }
 /** A cell's {@link ScriptRun}, tagged with the cell it ran in. */
 type WorkspaceScriptRun = ScriptRun & {
@@ -447,6 +516,14 @@ declare class VelaWorkspace {
     private order;
     private activeId;
     private cellBackend;
+    /** `layout: false` — the grid is pinned to the one-cell layout, the layout picker
+     *  and sync switches never render, and `setLayout` no-ops. */
+    private readonly monoLayout;
+    /** `drawings: false` — the whole user-drawings surface is gone: no shared bar, no
+     *  mobile drawings stop, no pill (the headless `chart.drawings` API stays). */
+    private readonly drawingsEnabled;
+    /** The shared bar's content — `drawings: { tools | groups }` picks it. */
+    private readonly toolbarDef;
     private destroyed;
     private readonly topbar;
     private readonly bottombar;
@@ -459,7 +536,7 @@ declare class VelaWorkspace {
     private readonly indicatorPicker;
     private readonly tfQuick;
     private shortcutsHelp;
-    private readonly toast;
+    private readonly toastHost;
     private readonly glider;
     private readonly drawToolbar;
     /** The GLOBAL armed tool/magnet/stay (workspace policy) — re-applied to whichever cell
@@ -499,6 +576,8 @@ declare class VelaWorkspace {
     private timezone;
     private openDialogs;
     private alerts;
+    /** Bell retention — `alertCap` option, default {@link ALERT_CAP}. */
+    private readonly alertCap;
     private alertsMenu;
     /** Writes `data-layout` on the root and pushes mode flips into every cell's renderer. */
     private layoutCtl;
@@ -512,6 +591,10 @@ declare class VelaWorkspace {
     /** Plot-local y of the last price-axis long-press (targets the pane under the finger). */
     private priceScalePressY;
     private readonly attachmentDisposers;
+    /** The document-level third-party state bag (`state.ext`) — seeded from the restored
+     *  document, refreshed by global-scope handler `serialize` calls at snapshot time.
+     *  Entries with no registered handler this session ride along verbatim. */
+    private extState;
     /** The single grid-wide attribution mark — re-inked on a live theme swap. */
     private attributionMark;
     private readonly onRootKeydown;
@@ -555,11 +638,21 @@ declare class VelaWorkspace {
     getState(): WorkspaceState;
     /**
      * Restore a state document produced by {@link getState} (untrusted-safe: malformed
-     * fields are dropped). Replaces the WHOLE workspace state: prefs, sync links,
-     * layout, and every slot — current cells are rebuilt from the document. A layout id
-     * that is not registered keeps the current grid (register custom layouts first).
+     * fields are dropped). When the document matches the live grid one-to-one — same
+     * layout, same ordered slot identities — it is applied IN PLACE: every chart
+     * instance survives (markets switch via `setMarket`), so chart references,
+     * indicator handles, and event subscriptions stay valid. Any structural difference
+     * (layout, slot count, renamed ids) falls back to the full rebuild: prefs, sync
+     * links, layout, and every slot are replaced, current cells rebuilt from the
+     * document. A layout id that is not registered keeps the current grid (register
+     * custom layouts first).
      */
     applyState(state: unknown): void;
+    /** Run the registered global-scope `restore` handlers against the document-level
+     *  `ext` bag — keys present in the document only; a failing handler is contained.
+     *  Handlers whose restore touches chart content should be `scope: 'cell'` instead
+     *  (those run inside the cell's history-mute). */
+    private restoreGlobalExt;
     /** Set the workspace-global display timezone — applied to EVERY cell. */
     setTimezone(zone: string): void;
     /**
@@ -579,6 +672,9 @@ declare class VelaWorkspace {
      */
     setLayout(layout: string | LayoutDefinition): void;
     resize(): void;
+    /** Show a toast over the grid — the same surface the shell's own notices use
+     *  (alerts, script errors) and the one contributions reach via `ctx.toast`. */
+    toast(message: string, kind?: 'info' | 'success' | 'error', durationMs?: number): void;
     destroy(): void;
     /** Re-project the shared chrome from the ACTIVE cell. The chrome holds no state of
      *  its own — this is a pure read of the cell, safe to call redundantly. */

package/dist/workspace.d.ts

@@ -1,9 +1,9 @@
-import { O as OHLCV, V as VisibleRangePreset, a as VisibleRange, b as VelaOptions, c as VelaTheme, N as NativeBackend, d as MarketSession } from './options-YdiaaVjt.js';
-import { S as SyncSetting, V as VelaStorage, C as CellState, W as WidgetHistory, R as ResolvedIndicator, a as RangePreset, T as TrackSizes, b as VelaShellOptions, c as SyncOptions, d as SyncKind, e as WorkspaceState } from './history-CvOtsjT5.js';
-export { f as ChartState, P as PanelsState, g as decodeState, h as encodeState, s as sanitizeState } from './history-CvOtsjT5.js';
+import { O as OHLCV, V as VisibleRangePreset, a as VisibleRange, b as VelaOptions, c as VelaTheme, N as NativeBackend, d as MarketSession } from './options-BaVTMXaO.js';
+import { S as SyncSetting, V as VelaStorage, C as CellState, W as WidgetHistory, R as ResolvedIndicator, a as RangePreset, T as TrackSizes, b as VelaShellOptions, c as SyncOptions, d as SyncKind, e as WorkspaceState } from './bottombar-COnL2Sk4.js';
+export { f as ChartState, P as PanelsState, g as decodeState, h as encodeState, s as sanitizeState } from './bottombar-COnL2Sk4.js';
 import { K as KeymapManager } from './keymap-CGOz5F5f.js';
-import { I as IndicatorHandle, S as ScriptingEngine, W as WidgetContext, V as Vela, a as ScriptRun } from './contributions-DatoAzMx.js';
-import { M as MarketDataFeed } from './DataProvider-BmHkcwvJ.js';
+import { I as IndicatorHandle, S as ScriptingEngine, W as WidgetContext, V as Vela, E as ExternalIndicatorEntry, a as ScriptRun } from './contributions-BqCIsbaP.js';
+import { M as MarketDataFeed } from './DataProvider-JJq7M2it.js';
 
 /** The cells that follow `originId` under `setting` — PURE (never includes the origin). */
 declare function syncTargets(originId: string, setting: SyncSetting | undefined, cellIds: readonly string[]): string[];
@@ -53,7 +53,7 @@ type CellBoot = PooledCellState & Pick<CellSeed, 'data' | 'visibleRange'>;
  *  `nativeBackend` (the WebGL budget policy, explicit value resolved upstream), the
  *  market/view seeds (those flow through {@link CellSeed}), and `drawings`' toolbar
  *  sub-key (see {@link cellDrawings}). */
-type CellChartDefaults = Pick<VelaOptions, 'renderer' | 'defaultLanguage' | 'currentPriceLine' | 'logScale' | 'animations' | 'glow' | 'upColor' | 'downColor' | 'drawings'>;
+type CellChartDefaults = Pick<VelaOptions, 'renderer' | 'defaultLanguage' | 'currentPriceLine' | 'logScale' | 'animations' | 'glow' | 'upColor' | 'downColor' | 'drawings' | 'settings'>;
 /** One entry of the shared indicator picker's native catalog, per cell. */
 interface CellNativeInfo {
     type: string;
@@ -102,6 +102,8 @@ interface CellDeps {
     /** Persistable per-cell state changed outside the market/indicator channels
      *  (bars budget, watermark/titles toggles) — the workspace debounces a save. */
     onStateDirty(): void;
+    /** The shell's toast surface (unresolved-symbol notices land there). */
+    toast(message: string, kind: 'info' | 'success' | 'error', durationMs?: number): void;
 }
 declare class ChartCell {
     readonly id: string;
@@ -110,10 +112,15 @@ declare class ChartCell {
     readonly host: HTMLElement;
     /** This cell's unified app+drawings undo timeline (the shared Ctrl+Z routes here). */
     readonly history: WidgetHistory;
-    /** Live manifest-indicator instances on this cell (the SAME entry may repeat). */
+    /** Live manifest-indicator instances on this cell (the SAME entry may repeat).
+     *  `external` marks instances added through the public seam (`ctx.addIndicator`)
+     *  rather than the shell manifest — they share the undo/redo and picker plumbing
+     *  but stay OUT of the persisted ledger (their names would never resolve against
+     *  the manifest); persisting them is their plugin's job (`registerStatePersistence`). */
     readonly instances: Array<{
         entry: ResolvedIndicator;
         handle: IndicatorHandle | null;
+        external?: boolean;
     }>;
     /** The native-indicator catalog with this cell's live supported/present flags. */
     nativeCatalog: CellNativeInfo[];
@@ -146,13 +153,22 @@ declare class ChartCell {
     /** The volume auto-add rides the cell's first candles (`load:end`); until then the
      *  registry can't show it and the dehydrated ledger reports the INTENT instead. */
     private volumeMayBePending;
-    /** Volume intent: the seed's ledger, else the workspace `volume` option. */
-    private readonly volumeIntent;
+    /** Volume intent: the seed's ledger, else the workspace `volume` option — a
+     *  rehydrated ledger overwrites it (see {@link applyIndicatorLedger}). */
+    private volumeIntent;
     /** Sync mirror of the chart's present native types — the removal handler diffs
      *  against it to identify (and record) whichever type was just removed. */
     private presentNatives;
     private rangeBars;
     private pendingRange;
+    /** Last symbol we toasted "no provider serves this" for — once per symbol (the
+     *  core re-reports on every provider-index settle). */
+    private unresolvedToasted;
+    /** The cell's third-party state bag (`ext` of the persisted per-chart state) —
+     *  seeded from the boot/restored document, refreshed by handler `serialize` calls at
+     *  dehydrate time. Entries with no registered handler this session ride along
+     *  verbatim, so a document never loses a plugin's state in the plugin's absence. */
+    private extState;
     private watermarkOn;
     /** Indicator titles (this cell's in-chart legend rows) shown. */
     private indicatorTitlesOn;
@@ -232,6 +248,14 @@ declare class ChartCell {
      * entries (fresh cells only).
      */
     setManifest(list: readonly ResolvedIndicator[], seedEnabled: boolean): void;
+    /**
+     * Replace the indicator ledger: natives converge to the listed set (volume
+     * included — removing it sticks, the core's auto-add respects the opt-out), and
+     * manifest instances are re-created by name, held until the shared manifest
+     * resolves. Convergence is state application, not user edits — nothing enters the
+     * undo timeline.
+     */
+    private applyIndicatorLedger;
     /** The picker's library rows: supported natives first, then the manifest. */
     libraryRows(): Array<{
         name: string;
@@ -252,9 +276,18 @@ declare class ChartCell {
     addFromLibrary(index: number): void;
     /** Remove by picker ON-CHART index (present natives precede instances). */
     removeFromChart(index: number): void;
+    /**
+     * Add a script indicator through the PUBLIC seam (`ctx.addIndicator`) — same undo/
+     * redo and picker plumbing as a manifest entry, but flagged `external` so the
+     * persisted ledger never records a name the manifest can't resolve (the plugin owns
+     * persistence via `registerStatePersistence`). Recording follows the ambient mute:
+     * a persistence handler's `restore` runs silently, a user-driven call records.
+     */
+    addExternalIndicator(entry: ExternalIndicatorEntry): void;
     /** Add ONE instance of a manifest entry (repeatable — duplicates are legitimate). */
     addManifestInstance(entry: ResolvedIndicator, opts?: {
         record?: boolean;
+        external?: boolean;
     }): void;
     private removeInstance;
     private dropInstance;
@@ -267,6 +300,33 @@ declare class ChartCell {
     /** Refresh the native catalog (supported/present flags) for this cell's market. */
     refreshNativeCatalog(): void;
     private addToChart;
+    /** The cell-bound surface persistence handlers work against (built per call — the
+     *  widget-context rule; nothing here may be cached by a handler). Its add methods
+     *  are ALWAYS muted — a `restore` that fetches before adding escapes the sync mute
+     *  of {@link restorePersistedExt}, and a state application must never enter the
+     *  undo timeline, however late its continuation lands. */
+    private stateContext;
+    /**
+     * Run the registered cell-scope `restore` handlers against the cell's restored
+     * `ext` bag — the workspace calls this AFTER the core state is in place (chart
+     * alive and wired, indicator ledger converged). Muted: nothing a restore does
+     * enters the undo timeline. Handlers only see keys the document carries; a failing
+     * handler is contained (one broken plugin must not take the cell down).
+     */
+    restorePersistedExt(): void;
+    /** Assemble the cell's `ext` bag: fresh handler snapshots merged OVER the preserved
+     *  entries — a key with no handler this session rides along verbatim; a registered
+     *  handler returning `undefined` withdraws its entry. */
+    private dehydrateExt;
+    /**
+     * Apply a restored cell state IN PLACE — the chart instance survives (the market
+     * switches via `setMarket`) while cosmetics, renderer config, drawings, and the
+     * indicator ledger converge to the document. The workspace takes this path when a
+     * state document lands on a grid of the same shape (async-storage boot, host
+     * `applyState`), so chart references, indicator handles, event subscriptions, and
+     * the cell host all stay valid.
+     */
+    rehydrate(cs: CellState): void;
     /** Snapshot everything the pool needs to restore this slot later. The market fields
      *  come from the LIVE config (`chart.market`) — the requested identity — so a switch
      *  still loading when the snapshot is taken (persist-on-close) is not lost. */
@@ -369,8 +429,15 @@ declare function activeAfterLayout(current: string | null, cellIds: readonly str
  */
 interface VelaWorkspaceOptions extends Omit<VelaOptions, 'height'>, VelaShellOptions {
     /** Initial layout — a registered id (`'1'`, `'2h'`, `'2v'`, `'4'`, `'8'`, or a
-     *  plugin-registered one) or an inline definition. Default `'4'`. */
-    layout?: string | LayoutDefinition;
+     *  plugin-registered one) or an inline definition. Default `'4'`.
+     *
+     *  `false` = SINGLE-CHART mode: the grid is pinned to the one-cell layout, the
+     *  layout picker disappears from the topbar and the mobile drawer (the sync
+     *  switches with it — meaningless with one cell), `setLayout` becomes a no-op,
+     *  and a restored document keeps only its first chart live (the rest stays
+     *  dormant in the pool). No `cells` entry is needed — the top-level chart
+     *  options seed the single chart. */
+    layout?: string | LayoutDefinition | false;
     /** Per-cell overrides of the top-level chart defaults, keyed by a FREE-FORM cell
      *  name — the name is the cell's durable IDENTITY (persistence, `sync` groups,
      *  `ws.cell(name)`), never its position: DECLARATION ORDER fills the layout's
@@ -396,6 +463,8 @@ interface VelaWorkspaceOptions extends Omit<VelaOptions, 'height'>, VelaShellOpt
      *  the browser's WebGL-context budget; glow is unavailable there). Default 8; an
      *  explicit `nativeBackend` other than `'auto'` wins over this policy. */
     maxWebglCells?: number;
+    /** How many alerts the topbar bell keeps (the oldest drop beyond it). Default 50. */
+    alertCap?: number;
 }
 /** A cell's {@link ScriptRun}, tagged with the cell it ran in. */
 type WorkspaceScriptRun = ScriptRun & {
@@ -447,6 +516,14 @@ declare class VelaWorkspace {
     private order;
     private activeId;
     private cellBackend;
+    /** `layout: false` — the grid is pinned to the one-cell layout, the layout picker
+     *  and sync switches never render, and `setLayout` no-ops. */
+    private readonly monoLayout;
+    /** `drawings: false` — the whole user-drawings surface is gone: no shared bar, no
+     *  mobile drawings stop, no pill (the headless `chart.drawings` API stays). */
+    private readonly drawingsEnabled;
+    /** The shared bar's content — `drawings: { tools | groups }` picks it. */
+    private readonly toolbarDef;
     private destroyed;
     private readonly topbar;
     private readonly bottombar;
@@ -459,7 +536,7 @@ declare class VelaWorkspace {
     private readonly indicatorPicker;
     private readonly tfQuick;
     private shortcutsHelp;
-    private readonly toast;
+    private readonly toastHost;
     private readonly glider;
     private readonly drawToolbar;
     /** The GLOBAL armed tool/magnet/stay (workspace policy) — re-applied to whichever cell
@@ -499,6 +576,8 @@ declare class VelaWorkspace {
     private timezone;
     private openDialogs;
     private alerts;
+    /** Bell retention — `alertCap` option, default {@link ALERT_CAP}. */
+    private readonly alertCap;
     private alertsMenu;
     /** Writes `data-layout` on the root and pushes mode flips into every cell's renderer. */
     private layoutCtl;
@@ -512,6 +591,10 @@ declare class VelaWorkspace {
     /** Plot-local y of the last price-axis long-press (targets the pane under the finger). */
     private priceScalePressY;
     private readonly attachmentDisposers;
+    /** The document-level third-party state bag (`state.ext`) — seeded from the restored
+     *  document, refreshed by global-scope handler `serialize` calls at snapshot time.
+     *  Entries with no registered handler this session ride along verbatim. */
+    private extState;
     /** The single grid-wide attribution mark — re-inked on a live theme swap. */
     private attributionMark;
     private readonly onRootKeydown;
@@ -555,11 +638,21 @@ declare class VelaWorkspace {
     getState(): WorkspaceState;
     /**
      * Restore a state document produced by {@link getState} (untrusted-safe: malformed
-     * fields are dropped). Replaces the WHOLE workspace state: prefs, sync links,
-     * layout, and every slot — current cells are rebuilt from the document. A layout id
-     * that is not registered keeps the current grid (register custom layouts first).
+     * fields are dropped). When the document matches the live grid one-to-one — same
+     * layout, same ordered slot identities — it is applied IN PLACE: every chart
+     * instance survives (markets switch via `setMarket`), so chart references,
+     * indicator handles, and event subscriptions stay valid. Any structural difference
+     * (layout, slot count, renamed ids) falls back to the full rebuild: prefs, sync
+     * links, layout, and every slot are replaced, current cells rebuilt from the
+     * document. A layout id that is not registered keeps the current grid (register
+     * custom layouts first).
      */
     applyState(state: unknown): void;
+    /** Run the registered global-scope `restore` handlers against the document-level
+     *  `ext` bag — keys present in the document only; a failing handler is contained.
+     *  Handlers whose restore touches chart content should be `scope: 'cell'` instead
+     *  (those run inside the cell's history-mute). */
+    private restoreGlobalExt;
     /** Set the workspace-global display timezone — applied to EVERY cell. */
     setTimezone(zone: string): void;
     /**
@@ -579,6 +672,9 @@ declare class VelaWorkspace {
      */
     setLayout(layout: string | LayoutDefinition): void;
     resize(): void;
+    /** Show a toast over the grid — the same surface the shell's own notices use
+     *  (alerts, script errors) and the one contributions reach via `ctx.toast`. */
+    toast(message: string, kind?: 'info' | 'success' | 'error', durationMs?: number): void;
     destroy(): void;
     /** Re-project the shared chrome from the ACTIVE cell. The chrome holds no state of
      *  its own — this is a pure read of the cell, safe to call redundantly. */