@luxalgo/vela 0.5.0 → 0.5.2

package/dist/{options-Q-576hIi.d.cts → options-XTBpbx0s.d.cts}

@@ -420,7 +420,13 @@ type PaneHint = 'price' | 'new';
 interface IndicatorModel {
     /** Per-instance id (stable). */
     id: string;
+    /** Full display name (settings dialog, object tree, inspect). */
     title: string;
+    /**
+     * Compact legend label when the full {@link title} is too long for the chip.
+     * Absent ⇒ the legend uses {@link title}. Mirrors Pine `indicator(..., shorttitle=)`.
+     */
+    shorttitle?: string;
     overlay: boolean;
     paneHint: PaneHint;
     /**
@@ -885,6 +891,15 @@ type DrawingMode = 'measure' | 'eraser' | null;
 type DrawingIntent = {
     kind: 'arm';
     type: DrawingTypeKey | null;
+}
+/** Placement in progress: the ghost's current shape after every anchor click and
+ *  cursor move; `null` when placement ends (finalized OR cancelled). No store
+ *  mutation — the core only re-emits it (`drawing:draft`) so a multi-chart host
+ *  can mirror the ghost live. Optional — a renderer that never emits it simply
+ *  syncs at completion. */
+ | {
+    kind: 'draft';
+    doc: SerializedDrawing | null;
 } | {
     kind: 'create';
     doc: SerializedDrawing;
@@ -978,6 +993,11 @@ interface IDrawingsRendererPort {
     setMode?(mode: DrawingMode): void;
     /** Open a drawing's settings popup (selecting it too) — the programmatic twin of a click on it. */
     openSettings(id: string): void;
+    /** Display another chart's in-progress placement as a GHOST at reduced opacity
+     *  (`null` clears it) — the drawings-sync twin of `setExternalCrosshair`. Never a
+     *  store drawing: no selection, no hit-testing, no persistence. Optional — a
+     *  renderer without it simply never previews remote placements. */
+    setExternalGhost?(doc: SerializedDrawing | null): void;
     /**
      * The pane's SERIES stack in z terms, for renderers whose drawings share one draw-order
      * space with the series (`drawingDepth`): the extremes ("bring to front" beats `front`,
@@ -1057,7 +1077,14 @@ interface CrosshairOHLC {
 }
 interface CrosshairEvent {
     time: Millis | null;
+    /** Value at the cursor on ITS pane's scale — a price on the price pane, an
+     *  indicator value on a study pane (which one: see {@link paneKind}). */
     price: number | null;
+    /** The kind of pane the cursor (and thus `price`) is on — how a consumer tells a
+     *  real price from a study-pane value (e.g. crosshair sync only mirrors the
+     *  horizontal level from the price pane). Optional and additive: a renderer that
+     *  doesn't track panes omits it. */
+    paneKind?: 'price' | 'study' | null;
     /** Value at the crosshair per series, keyed by stable series id. */
     values: ReadonlyMap<string, number>;
     /** The hovered price bar's OHLCV (null when the cursor is off any bar). */
@@ -1067,6 +1094,13 @@ interface ClickEvent {
     time: Millis | null;
     price: number | null;
 }
+/** A touch long-press on an axis strip — the mobile substitute for a right-click menu. */
+interface AxisLongPressEvent {
+    axis: 'price' | 'time';
+    /** Plot-local pixel of the press (y maps a multi-pane price scale to its pane). */
+    x: number;
+    y: number;
+}
 /** One indicator plot's readout line in the data window. */
 interface DataWindowRow {
     label: string;
@@ -1238,6 +1272,22 @@ interface IChartRenderer {
      * renderer without it simply never shows contributed legend actions.
      */
     setLegendActions?(provider: ((indicatorId: string) => LegendActionView[]) | null): void;
+    /**
+     * Replace the indicator legend's fold toggle with a HOST action (or restore it with
+     * null): the chip stays — a list glyph plus the indicator count — but pressing it
+     * runs the action instead of unfolding the rows, which stay hidden while the
+     * override is in force. Multi-chart shells route it to their indicator overview
+     * (e.g. an object-tree panel), where per-indicator controls live instead. Optional —
+     * a renderer without a foldable legend omits it.
+     */
+    setLegendOverviewAction?(action: (() => void) | null): void;
+    /**
+     * Open the settings dialog of one mounted indicator — the programmatic twin of the
+     * legend row's gear button, for host chrome that reaches indicators outside the
+     * legend (an object tree's action menu). Silent no-op for an unknown id. Optional —
+     * a renderer without per-indicator settings UI omits it.
+     */
+    openIndicatorSettings?(indicatorId: string): void;
     /**
      * Hide (`false`) or show (`true`) a mounted indicator's visuals while keeping its legend row
      * (marked hidden). Optional — a renderer that can't suppress an indicator omits it (and the
@@ -1261,6 +1311,9 @@ interface IChartRenderer {
     onToggleIndicatorVisible?(cb: (id: string, visible: boolean) => void): Unsubscribe;
     onCrosshairMove(cb: (e: CrosshairEvent) => void): Unsubscribe;
     onClick(cb: (e: ClickEvent) => void): Unsubscribe;
+    /** Touch long-press on a price or time axis strip. Optional — a renderer without
+     *  touch axis gestures omits it; host chrome (timezone / price-scale sheets) keys off it. */
+    onAxisLongPress?(cb: (e: AxisLongPressEvent) => void): Unsubscribe;
     /**
      * Display an EXTERNAL crosshair at a data-space position — a ghost marker driven by
      * another chart (multi-chart crosshair sync), not by this chart's own pointer.
@@ -1348,6 +1401,13 @@ interface IChartRenderer {
         title: string;
         rows: readonly unknown[];
     }>): void;
+    /**
+     * The host shell's chrome size class. `'mobile'` asks the renderer's own chrome
+     * (dialogs, toolbars, buttons) for its touch-first presentation — fullscreen
+     * dialogs, no hover-gated affordances; `'desktop'` (the default) keeps the
+     * pointer-first one. Optional — a renderer without adaptive chrome omits it.
+     */
+    setLayoutMode?(mode: 'mobile' | 'desktop'): void;
     /**
      * Interactive user-drawings surface. Present iff `capabilities.userDrawings`.
      * The core `DrawingController` drives it (commands down) and listens for
@@ -1542,4 +1602,4 @@ interface AddIndicatorOptions {
     title?: string;
 }
 
-export { type DrawingLinefill as $, type AddIndicatorOptions as A, type Background as B, type CrosshairEvent as C, Drawing as D, type CandleBarColor as E, type CandleSeries as F, type CandleStyle as G, type DataWindowGroup as H, type IChartRenderer as I, type DataWindowOHLC as J, type DataWindowRow as K, type LineStyle as L, type MarketConfig as M, type NativeBackend as N, type OHLCV as O, type PriceStyle as P, type DirtyRange as Q, type RendererCapabilities as R, type SerializedDrawing as S, type ThemeName as T, type Unsubscribe as U, type VisibleRangePreset as V, type DrawingBox as W, type DrawingExtend as X, type DrawingIntent as Y, type DrawingLabel as Z, type DrawingLine as _, type VisibleRange as a, type DrawingMode as a0, type DrawingPoint as a1, type DrawingPolyline as a2, type DrawingStyle as a3, type DrawingTable as a4, type DrawingText as a5, type DrawingXLoc as a6, type DrawingsOption as a7, type Fill as a8, type FillGradientStop as a9, type SettingsSchema as aA, type TableCell as aB, type TableMerge as aC, type TablePosition as aD, type ToolbarGroupConfig as aE, type TradeExecution as aF, type ValuePatch as aG, buildToolbar as aH, defaultToolbar as aI, type PaneInfo as aJ, type IndicatorMeta as aa, type InputSchema as ab, type InputType as ac, type LabelStyle as ad, type LabelYLoc as ae, type LineLikeKind as af, type LineLikeSeries as ag, type LineLikeStyle as ah, type MarkerPoint as ai, type MarkerSeries as aj, type MarketSnapshot as ak, type MarketSwitch as al, type PaneHint as am, type PaneKind as an, type PolylinePoint as ao, type PriceLine as ap, type Projector as aq, type ProviderName as ar, type RendererConstructor as as, type Scene as at, type SchemaPatch as au, type SeriesKind as av, type SeriesPoint as aw, type SeriesSpec as ax, type SeriesValueDelta as ay, type SettingsField as az, type VelaOptions as b, type VelaTheme as c, type RendererDisplayOptions as d, type IndicatorRenderHandle as e, type IndicatorStatus as f, type Pane as g, type PaneAction as h, type MoveTarget as i, type IndicatorModel as j, type ScenePatch as k, type InputValue as l, type SymbolPickerFn as m, type LegendActionView as n, type InputChangeEvent as o, type ClickEvent as p, type DataWindowReadout as q, type IDrawingsRendererPort as r, type Millis as s, type SnapMode as t, type DrawingTypeKey as u, type ToolbarDefinition as v, type BoxFontFamily as w, type BoxHAlign as x, type BoxTextSize as y, type BoxVAlign as z };
+export { type DrawingLine as $, type AxisLongPressEvent as A, type Background as B, type CrosshairEvent as C, Drawing as D, type BoxVAlign as E, type CandleBarColor as F, type CandleSeries as G, type CandleStyle as H, type IChartRenderer as I, type DataWindowGroup as J, type DataWindowOHLC as K, type LineStyle as L, type MarketConfig as M, type NativeBackend as N, type OHLCV as O, type PriceStyle as P, type DataWindowRow as Q, type RendererCapabilities as R, type SerializedDrawing as S, type ThemeName as T, type Unsubscribe as U, type VisibleRangePreset as V, type DirtyRange as W, type DrawingBox as X, type DrawingExtend as Y, type DrawingIntent as Z, type DrawingLabel as _, type VisibleRange as a, type DrawingLinefill as a0, type DrawingMode as a1, type DrawingPoint as a2, type DrawingPolyline as a3, type DrawingStyle as a4, type DrawingTable as a5, type DrawingText as a6, type DrawingXLoc as a7, type DrawingsOption as a8, type Fill as a9, type SettingsField as aA, type SettingsSchema as aB, type TableCell as aC, type TableMerge as aD, type TablePosition as aE, type ToolbarGroupConfig as aF, type TradeExecution as aG, type ValuePatch as aH, buildToolbar as aI, defaultToolbar as aJ, type PaneInfo as aK, type FillGradientStop as aa, type IndicatorMeta as ab, type InputSchema as ac, type InputType as ad, type LabelStyle as ae, type LabelYLoc as af, type LineLikeKind as ag, type LineLikeSeries as ah, type LineLikeStyle as ai, type MarkerPoint as aj, type MarkerSeries as ak, type MarketSnapshot as al, type MarketSwitch as am, type PaneHint as an, type PaneKind as ao, type PolylinePoint as ap, type PriceLine as aq, type Projector as ar, type ProviderName as as, type RendererConstructor as at, type Scene as au, type SchemaPatch as av, type SeriesKind as aw, type SeriesPoint as ax, type SeriesSpec as ay, type SeriesValueDelta as az, type VelaOptions as b, type VelaTheme as c, type RendererDisplayOptions as d, type IndicatorRenderHandle as e, type IndicatorStatus as f, type Pane as g, type PaneAction as h, type MoveTarget as i, type IndicatorModel as j, type ScenePatch as k, type InputValue as l, type SymbolPickerFn as m, type LegendActionView as n, type InputChangeEvent as o, type ClickEvent as p, type DataWindowReadout as q, type IDrawingsRendererPort as r, type Millis as s, type SnapMode as t, type DrawingTypeKey as u, type ToolbarDefinition as v, type AddIndicatorOptions as w, type BoxFontFamily as x, type BoxHAlign as y, type BoxTextSize as z };

package/dist/{options-Q-576hIi.d.ts → options-XTBpbx0s.d.ts}

@@ -420,7 +420,13 @@ type PaneHint = 'price' | 'new';
 interface IndicatorModel {
     /** Per-instance id (stable). */
     id: string;
+    /** Full display name (settings dialog, object tree, inspect). */
     title: string;
+    /**
+     * Compact legend label when the full {@link title} is too long for the chip.
+     * Absent ⇒ the legend uses {@link title}. Mirrors Pine `indicator(..., shorttitle=)`.
+     */
+    shorttitle?: string;
     overlay: boolean;
     paneHint: PaneHint;
     /**
@@ -885,6 +891,15 @@ type DrawingMode = 'measure' | 'eraser' | null;
 type DrawingIntent = {
     kind: 'arm';
     type: DrawingTypeKey | null;
+}
+/** Placement in progress: the ghost's current shape after every anchor click and
+ *  cursor move; `null` when placement ends (finalized OR cancelled). No store
+ *  mutation — the core only re-emits it (`drawing:draft`) so a multi-chart host
+ *  can mirror the ghost live. Optional — a renderer that never emits it simply
+ *  syncs at completion. */
+ | {
+    kind: 'draft';
+    doc: SerializedDrawing | null;
 } | {
     kind: 'create';
     doc: SerializedDrawing;
@@ -978,6 +993,11 @@ interface IDrawingsRendererPort {
     setMode?(mode: DrawingMode): void;
     /** Open a drawing's settings popup (selecting it too) — the programmatic twin of a click on it. */
     openSettings(id: string): void;
+    /** Display another chart's in-progress placement as a GHOST at reduced opacity
+     *  (`null` clears it) — the drawings-sync twin of `setExternalCrosshair`. Never a
+     *  store drawing: no selection, no hit-testing, no persistence. Optional — a
+     *  renderer without it simply never previews remote placements. */
+    setExternalGhost?(doc: SerializedDrawing | null): void;
     /**
      * The pane's SERIES stack in z terms, for renderers whose drawings share one draw-order
      * space with the series (`drawingDepth`): the extremes ("bring to front" beats `front`,
@@ -1057,7 +1077,14 @@ interface CrosshairOHLC {
 }
 interface CrosshairEvent {
     time: Millis | null;
+    /** Value at the cursor on ITS pane's scale — a price on the price pane, an
+     *  indicator value on a study pane (which one: see {@link paneKind}). */
     price: number | null;
+    /** The kind of pane the cursor (and thus `price`) is on — how a consumer tells a
+     *  real price from a study-pane value (e.g. crosshair sync only mirrors the
+     *  horizontal level from the price pane). Optional and additive: a renderer that
+     *  doesn't track panes omits it. */
+    paneKind?: 'price' | 'study' | null;
     /** Value at the crosshair per series, keyed by stable series id. */
     values: ReadonlyMap<string, number>;
     /** The hovered price bar's OHLCV (null when the cursor is off any bar). */
@@ -1067,6 +1094,13 @@ interface ClickEvent {
     time: Millis | null;
     price: number | null;
 }
+/** A touch long-press on an axis strip — the mobile substitute for a right-click menu. */
+interface AxisLongPressEvent {
+    axis: 'price' | 'time';
+    /** Plot-local pixel of the press (y maps a multi-pane price scale to its pane). */
+    x: number;
+    y: number;
+}
 /** One indicator plot's readout line in the data window. */
 interface DataWindowRow {
     label: string;
@@ -1238,6 +1272,22 @@ interface IChartRenderer {
      * renderer without it simply never shows contributed legend actions.
      */
     setLegendActions?(provider: ((indicatorId: string) => LegendActionView[]) | null): void;
+    /**
+     * Replace the indicator legend's fold toggle with a HOST action (or restore it with
+     * null): the chip stays — a list glyph plus the indicator count — but pressing it
+     * runs the action instead of unfolding the rows, which stay hidden while the
+     * override is in force. Multi-chart shells route it to their indicator overview
+     * (e.g. an object-tree panel), where per-indicator controls live instead. Optional —
+     * a renderer without a foldable legend omits it.
+     */
+    setLegendOverviewAction?(action: (() => void) | null): void;
+    /**
+     * Open the settings dialog of one mounted indicator — the programmatic twin of the
+     * legend row's gear button, for host chrome that reaches indicators outside the
+     * legend (an object tree's action menu). Silent no-op for an unknown id. Optional —
+     * a renderer without per-indicator settings UI omits it.
+     */
+    openIndicatorSettings?(indicatorId: string): void;
     /**
      * Hide (`false`) or show (`true`) a mounted indicator's visuals while keeping its legend row
      * (marked hidden). Optional — a renderer that can't suppress an indicator omits it (and the
@@ -1261,6 +1311,9 @@ interface IChartRenderer {
     onToggleIndicatorVisible?(cb: (id: string, visible: boolean) => void): Unsubscribe;
     onCrosshairMove(cb: (e: CrosshairEvent) => void): Unsubscribe;
     onClick(cb: (e: ClickEvent) => void): Unsubscribe;
+    /** Touch long-press on a price or time axis strip. Optional — a renderer without
+     *  touch axis gestures omits it; host chrome (timezone / price-scale sheets) keys off it. */
+    onAxisLongPress?(cb: (e: AxisLongPressEvent) => void): Unsubscribe;
     /**
      * Display an EXTERNAL crosshair at a data-space position — a ghost marker driven by
      * another chart (multi-chart crosshair sync), not by this chart's own pointer.
@@ -1348,6 +1401,13 @@ interface IChartRenderer {
         title: string;
         rows: readonly unknown[];
     }>): void;
+    /**
+     * The host shell's chrome size class. `'mobile'` asks the renderer's own chrome
+     * (dialogs, toolbars, buttons) for its touch-first presentation — fullscreen
+     * dialogs, no hover-gated affordances; `'desktop'` (the default) keeps the
+     * pointer-first one. Optional — a renderer without adaptive chrome omits it.
+     */
+    setLayoutMode?(mode: 'mobile' | 'desktop'): void;
     /**
      * Interactive user-drawings surface. Present iff `capabilities.userDrawings`.
      * The core `DrawingController` drives it (commands down) and listens for
@@ -1542,4 +1602,4 @@ interface AddIndicatorOptions {
     title?: string;
 }
 
-export { type DrawingLinefill as $, type AddIndicatorOptions as A, type Background as B, type CrosshairEvent as C, Drawing as D, type CandleBarColor as E, type CandleSeries as F, type CandleStyle as G, type DataWindowGroup as H, type IChartRenderer as I, type DataWindowOHLC as J, type DataWindowRow as K, type LineStyle as L, type MarketConfig as M, type NativeBackend as N, type OHLCV as O, type PriceStyle as P, type DirtyRange as Q, type RendererCapabilities as R, type SerializedDrawing as S, type ThemeName as T, type Unsubscribe as U, type VisibleRangePreset as V, type DrawingBox as W, type DrawingExtend as X, type DrawingIntent as Y, type DrawingLabel as Z, type DrawingLine as _, type VisibleRange as a, type DrawingMode as a0, type DrawingPoint as a1, type DrawingPolyline as a2, type DrawingStyle as a3, type DrawingTable as a4, type DrawingText as a5, type DrawingXLoc as a6, type DrawingsOption as a7, type Fill as a8, type FillGradientStop as a9, type SettingsSchema as aA, type TableCell as aB, type TableMerge as aC, type TablePosition as aD, type ToolbarGroupConfig as aE, type TradeExecution as aF, type ValuePatch as aG, buildToolbar as aH, defaultToolbar as aI, type PaneInfo as aJ, type IndicatorMeta as aa, type InputSchema as ab, type InputType as ac, type LabelStyle as ad, type LabelYLoc as ae, type LineLikeKind as af, type LineLikeSeries as ag, type LineLikeStyle as ah, type MarkerPoint as ai, type MarkerSeries as aj, type MarketSnapshot as ak, type MarketSwitch as al, type PaneHint as am, type PaneKind as an, type PolylinePoint as ao, type PriceLine as ap, type Projector as aq, type ProviderName as ar, type RendererConstructor as as, type Scene as at, type SchemaPatch as au, type SeriesKind as av, type SeriesPoint as aw, type SeriesSpec as ax, type SeriesValueDelta as ay, type SettingsField as az, type VelaOptions as b, type VelaTheme as c, type RendererDisplayOptions as d, type IndicatorRenderHandle as e, type IndicatorStatus as f, type Pane as g, type PaneAction as h, type MoveTarget as i, type IndicatorModel as j, type ScenePatch as k, type InputValue as l, type SymbolPickerFn as m, type LegendActionView as n, type InputChangeEvent as o, type ClickEvent as p, type DataWindowReadout as q, type IDrawingsRendererPort as r, type Millis as s, type SnapMode as t, type DrawingTypeKey as u, type ToolbarDefinition as v, type BoxFontFamily as w, type BoxHAlign as x, type BoxTextSize as y, type BoxVAlign as z };
+export { type DrawingLine as $, type AxisLongPressEvent as A, type Background as B, type CrosshairEvent as C, Drawing as D, type BoxVAlign as E, type CandleBarColor as F, type CandleSeries as G, type CandleStyle as H, type IChartRenderer as I, type DataWindowGroup as J, type DataWindowOHLC as K, type LineStyle as L, type MarketConfig as M, type NativeBackend as N, type OHLCV as O, type PriceStyle as P, type DataWindowRow as Q, type RendererCapabilities as R, type SerializedDrawing as S, type ThemeName as T, type Unsubscribe as U, type VisibleRangePreset as V, type DirtyRange as W, type DrawingBox as X, type DrawingExtend as Y, type DrawingIntent as Z, type DrawingLabel as _, type VisibleRange as a, type DrawingLinefill as a0, type DrawingMode as a1, type DrawingPoint as a2, type DrawingPolyline as a3, type DrawingStyle as a4, type DrawingTable as a5, type DrawingText as a6, type DrawingXLoc as a7, type DrawingsOption as a8, type Fill as a9, type SettingsField as aA, type SettingsSchema as aB, type TableCell as aC, type TableMerge as aD, type TablePosition as aE, type ToolbarGroupConfig as aF, type TradeExecution as aG, type ValuePatch as aH, buildToolbar as aI, defaultToolbar as aJ, type PaneInfo as aK, type FillGradientStop as aa, type IndicatorMeta as ab, type InputSchema as ac, type InputType as ad, type LabelStyle as ae, type LabelYLoc as af, type LineLikeKind as ag, type LineLikeSeries as ah, type LineLikeStyle as ai, type MarkerPoint as aj, type MarkerSeries as ak, type MarketSnapshot as al, type MarketSwitch as am, type PaneHint as an, type PaneKind as ao, type PolylinePoint as ap, type PriceLine as aq, type Projector as ar, type ProviderName as as, type RendererConstructor as at, type Scene as au, type SchemaPatch as av, type SeriesKind as aw, type SeriesPoint as ax, type SeriesSpec as ay, type SeriesValueDelta as az, type VelaOptions as b, type VelaTheme as c, type RendererDisplayOptions as d, type IndicatorRenderHandle as e, type IndicatorStatus as f, type Pane as g, type PaneAction as h, type MoveTarget as i, type IndicatorModel as j, type ScenePatch as k, type InputValue as l, type SymbolPickerFn as m, type LegendActionView as n, type InputChangeEvent as o, type ClickEvent as p, type DataWindowReadout as q, type IDrawingsRendererPort as r, type Millis as s, type SnapMode as t, type DrawingTypeKey as u, type ToolbarDefinition as v, type AddIndicatorOptions as w, type BoxFontFamily as x, type BoxHAlign as y, type BoxTextSize as z };

package/dist/{plugin-aGUD1epn.d.ts → plugin-CnNd7cuF.d.ts}

@@ -1,9 +1,9 @@
-import { u as DrawingTypeKey, a3 as DrawingStyle, S as SerializedDrawing, D as Drawing, av as SeriesKind, O as OHLCV, c as VelaTheme } from './options-Q-576hIi.js';
-import { b as DataControl } from './contributions-hX3EUyjG.js';
+import { u as DrawingTypeKey, a4 as DrawingStyle, S as SerializedDrawing, D as Drawing, aw as SeriesKind, O as OHLCV, c as VelaTheme } from './options-XTBpbx0s.js';
+import { b as DataControl } from './contributions-b6AVrqqG.js';
 import './side-panel-CT9ZwIGz.js';
 import './icons-BZYbJXSV.js';
 import './keymap-CGOz5F5f.js';
-import './DataProvider-Dzd-Erlk.js';
+import './DataProvider-DTOEXKTI.js';
 
 /** What a drawing type contributes to the toolbar + factory (renderer-neutral). */
 interface DrawingTypeMeta {
@@ -208,7 +208,11 @@ interface SeriesDataEngine {
         from: number;
         to: number;
     }): void;
-    /** New settings values from the chart-settings dialog (the type's SDK section). */
+    /** New settings values from the chart-settings dialog (the type's SDK section).
+     *  Also delivered once just BEFORE `start()` whenever stored values exist (a
+     *  persisted config, a market switch recreating the engine) — an engine must
+     *  accept a pre-start call as pure configuration, so it never fetches on
+     *  schema defaults the user has edited away. */
     onSettings?(values: Record<string, unknown>): void;
 }
 /** One registered chart type. */
@@ -242,12 +246,175 @@ interface ChartTypeDefinition {
      */
     basePainting?: 'candles' | 'none';
 }
-/** One declarative settings row. To add a NEW kind, see docs/architecture/settings-rows.md. */
+/**
+ * A declarative visibility condition on another row's CURRENT value (stored value,
+ * or that row's `defval` while unset). Pure data — the dialog evaluates it live as
+ * the user edits, so dependent rows appear/disappear without a rebuild.
+ * `anyOf` wins over `equals` when both are given.
+ */
+interface SettingsRowCondition {
+    key: string;
+    equals?: boolean | string | number;
+    anyOf?: readonly (boolean | string | number)[];
+}
+/** A row's visibility gate: one condition, or several AND-ed together. */
+type SettingsRowWhen = SettingsRowCondition | readonly SettingsRowCondition[];
+/**
+ * An inline color swatch on a toggle row — the color(s) the toggle governs, edited
+ * right on the toggle's row (dimmed while the toggle is off) instead of a
+ * conditionally revealed row below. Each swatch stores under its own bag key.
+ */
+interface SettingsRowSwatch {
+    key: string;
+    /** Names the color for the swatch's tooltip (`'Highlight color'`). */
+    label: string;
+    defval: string;
+    /**
+     * Optional visibility gate, evaluated live against the values bag exactly like a
+     * row's own `when` — lets one toggle row swap its swatch set as another value
+     * changes (a mode's two colors while it is on, its one alternative while off).
+     * A gated swatch is EXEMPT from the toggle-off dim: its gate already says when
+     * it matters, and it may exist specifically for the off state.
+     */
+    when?: SettingsRowWhen;
+}
+/**
+ * An inline LINE-WIDTH dropdown on a toggle row — sits beside the row's color
+ * swatches (dimmed with them while the toggle is off) and stores a px number under
+ * its own bag key. The control offers the classic drawing-bar weights (1–5 px),
+ * each option previewed as a line at that weight.
+ */
+interface SettingsRowWidth {
+    key: string;
+    /** Names the control for its tooltip (`'Line width'`). */
+    label: string;
+    defval: number;
+}
+/**
+ * An inline NUMBER input on a toggle row — sits AHEAD of the row's color swatches
+ * (dimmed with them while the toggle is off) and stores a number under its own bag
+ * key. For the one value the toggle governs (a percent, a count) — the declarative
+ * alternative to a separate `number` row gated on the toggle.
+ */
+interface SettingsRowInlineNumber {
+    key: string;
+    /** Names the input for its tooltip (`'Value area (%)'`). */
+    label: string;
+    defval: number;
+    min?: number;
+    max?: number;
+    step?: number;
+}
+/**
+ * A select option: a bare string (value = label) or a `[value, label]` pair when the
+ * stored id differs from the human-readable text (`['bidAskProfile', 'Bid × Ask Profile']`).
+ */
+type SettingsSelectOption = string | readonly [value: string, label: string];
+/**
+ * One INLINE CONTROL on a composite `row` — the composable unit every value row is
+ * made of. Each keyed control stores under its own bag key; `label` names it for the
+ * control's tooltip. A control may carry its own `when` gate (same shape as a row's),
+ * evaluated live against the values bag: a gated control appears/disappears as other
+ * values change, and is EXEMPT from the row's toggle-off dim — its gate already says
+ * when it matters, and it may exist specifically for the off state.
+ *
+ * - `number` — a compact number input. With `placeholder`, an input at the default
+ *   value renders EMPTY showing it, and clearing the input stores the default back —
+ *   the placeholder names the "unset" state (`'Off'` for a 0-disables bound).
+ * - `color` — a color swatch opening the shared color picker.
+ * - `width` — a line-width dropdown (the classic drawing-bar 1–5 px weights, each
+ *   option previewed as a line at that weight), storing a px number.
+ * - `select` — a dropdown over {@link SettingsSelectOption}s.
+ * - `hint` — display-only dimmed text between controls (the `–` of a min–max pair,
+ *   a unit); stores nothing.
+ */
+type SettingsInlineControl = {
+    kind: 'number';
+    key: string;
+    label: string;
+    defval: number;
+    min?: number;
+    max?: number;
+    step?: number;
+    placeholder?: string;
+    when?: SettingsRowWhen;
+} | {
+    kind: 'color';
+    key: string;
+    label: string;
+    defval: string;
+    when?: SettingsRowWhen;
+} | {
+    kind: 'width';
+    key: string;
+    label: string;
+    defval: number;
+    when?: SettingsRowWhen;
+} | {
+    kind: 'select';
+    key: string;
+    label: string;
+    options: readonly SettingsSelectOption[];
+    defval: string;
+    when?: SettingsRowWhen;
+} | {
+    kind: 'hint';
+    text: string;
+};
+/**
+ * One declarative settings row. To add a NEW inline control kind, see
+ * docs/architecture/settings-rows.md.
+ *
+ * `heading` titles a GROUP of rows: the heading plus everything after it up to the next
+ * heading. In a flat `rows` section headings render as inline group titles; inside
+ * `instances`/`subsections` (or a `layout: 'grouped'` section) they become entries of
+ * the pane's group TOC (see {@link ChartTypeSettingsSection}).
+ *
+ * `header` is an in-pane subgroup title: same visual as a flat heading, but inside a
+ * structured pane it stays in the rows column (does NOT become a TOC entry). Use it to
+ * cluster rows inside a TOC group (e.g. Colors / Values under Display).
+ *
+ * `row` is the COMPOSITE form every value row reduces to: a label, an optional leading
+ * `toggle` (a checkbox storing a boolean under `toggle.key`; while off, the row's
+ * controls dim and ignore input), and an ordered list of {@link SettingsInlineControl}s
+ * in the control column. Any mix of control kinds in any order — no per-combination
+ * SDK surface.
+ *
+ * The remaining kinds are SUGAR over `row` (see {@link normalizeSettingsRow}):
+ * - `toggle` — a checkbox row; optional inline `number`, color `colors`, and `width`
+ *   attachments render in that order.
+ * - `number` / `color` / `select` — one control on its own row.
+ * - `range` — a min–max pair (two number inputs under `minKey`/`maxKey`, both seeded
+ *   from the shared `defval`, with `placeholder` naming the unset state).
+ *
+ * Any row may carry `when` — it is shown only while the condition holds.
+ */
 type SettingsRowDescriptor = {
+    kind: 'heading';
+    label: string;
+    when?: SettingsRowWhen;
+} | {
+    kind: 'header';
+    label: string;
+    when?: SettingsRowWhen;
+} | {
+    kind: 'row';
+    label: string;
+    toggle?: {
+        key: string;
+        defval: boolean;
+    };
+    controls: readonly SettingsInlineControl[];
+    when?: SettingsRowWhen;
+} | {
     kind: 'toggle';
     key: string;
     label: string;
     defval: boolean;
+    number?: SettingsRowInlineNumber;
+    colors?: readonly SettingsRowSwatch[];
+    width?: SettingsRowWidth;
+    when?: SettingsRowWhen;
 } | {
     kind: 'number';
     key: string;
@@ -256,25 +423,127 @@ type SettingsRowDescriptor = {
     min?: number;
     max?: number;
     step?: number;
+    when?: SettingsRowWhen;
 } | {
     kind: 'color';
     key: string;
     label: string;
     defval: string;
+    when?: SettingsRowWhen;
 } | {
     kind: 'select';
     key: string;
     label: string;
-    options: readonly string[];
+    options: readonly SettingsSelectOption[];
     defval: string;
+    when?: SettingsRowWhen;
+} | {
+    kind: 'range';
+    label: string;
+    minKey: string;
+    maxKey: string;
+    defval: number;
+    min?: number;
+    max?: number;
+    step?: number;
+    placeholder?: string;
+    when?: SettingsRowWhen;
 };
+/** A value-carrying row (everything except the key-less `heading`/`header` titles). */
+type SettingsValueRow = Exclude<SettingsRowDescriptor, {
+    kind: 'heading' | 'header';
+}>;
+/** The canonical row shape every {@link SettingsValueRow} reduces to (the `row` kind's fields). */
+interface NormalizedSettingsRow {
+    label: string;
+    toggle?: {
+        key: string;
+        defval: boolean;
+    };
+    controls: readonly SettingsInlineControl[];
+    when?: SettingsRowWhen;
+}
+/**
+ * Reduce a value row to the canonical composite shape — the ONE contract view layers
+ * render and the persistence layer enumerates. The sugar kinds map exactly onto their
+ * historical rendering: `toggle` attachments in number → colors → width order, `range`
+ * as two number controls around a `–` hint (placeholder semantics preserved).
+ */
+declare function normalizeSettingsRow(r: SettingsValueRow): NormalizedSettingsRow;
+/** One value a settings row stores: its bag key, runtime type, and registry default. */
+interface SettingsRowValueKey {
+    key: string;
+    type: 'boolean' | 'number' | 'string';
+    defval: boolean | number | string;
+}
+/**
+ * EVERY key a row stores (toggle key + each keyed inline control), with its expected
+ * type and default — the single enumeration the dialog seeds from and the factory
+ * reset restores, so no key can fall through a kind-specific walk.
+ */
+declare function settingsRowValueKeys(r: SettingsRowDescriptor): SettingsRowValueKey[];
+/**
+ * One tab of a section's INSTANCE STRIP — a repeated block of settings (e.g. one of
+ * several overlays a style can paint). The dialog shows a tab per PRESENT instance,
+ * a dashed `+` that turns on the next absent one, and an `×` on the active removable
+ * tab that turns it off. Presence is the boolean at `enableKey` (stored in the same
+ * per-type bag as every other value); an instance without `enableKey` is always
+ * present and not removable — the base instance.
+ */
+interface ChartTypeSettingsInstance {
+    label: string;
+    /** Boolean bag key controlling presence; omitted = always present, not removable. */
+    enableKey?: string;
+    rows: readonly SettingsRowDescriptor[];
+}
+/** An indented sub-entry under the section's rail tab, with its own pane of rows. */
+interface ChartTypeSettingsSubsection {
+    title: string;
+    rows: readonly SettingsRowDescriptor[];
+    /**
+     * Boolean bag key that masters this pane. While it is false, every row EXCEPT the
+     * one whose `key` matches stays visible but grayed out (not hidden) — so users can
+     * still browse and preview settings with the feature off. The matching toggle is
+     * typically the first row of the Display group.
+     */
+    enableKey?: string;
+}
+/**
+ * A chart type's settings tab. Two forms:
+ *
+ * - **Flat**: `rows` only — rendered as one scrollable pane, `heading` rows as inline
+ *   group titles (the historical form). `layout: 'grouped'` upgrades the same rows to
+ *   the GROUP TOC presentation (below) without declaring an instance strip.
+ * - **Structured**: `instances` (and optionally `subsections`) — the pane opens with an
+ *   instance TAB STRIP, and each instance's rows are organized by a GROUP TOC on the
+ *   left of the pane (right of the dialog's tab rail) built from its `heading` rows
+ *   (rows before the first heading always show above the groups; selecting a TOC entry
+ *   shows only that group's rows). `subsections` add indented rail entries under the
+ *   section's tab, each a pane with the same TOC treatment. A TOC entry hides itself
+ *   while every row of its group is hidden by `when` gates.
+ *
+ * All values — every instance and subsection included — live in the ONE per-type bag
+ * (`config.chartTypes[<id>]`), so consumers keep receiving a single flat object.
+ */
 interface ChartTypeSettingsSection {
     /** Section heading in the settings dialog. */
     title: string;
-    rows: readonly SettingsRowDescriptor[];
+    /** Flat form. Ignored when `instances` is declared. */
+    rows?: readonly SettingsRowDescriptor[];
+    /** How `rows` are presented: `'flat'` (default) renders headings as inline group
+     *  titles; `'grouped'` promotes them to a group TOC beside the rows (the structured
+     *  pane's presentation, without an instance strip). Ignored with `instances`. */
+    layout?: 'flat' | 'grouped';
+    /** Structured form: the pane's instance tab strip. */
+    instances?: readonly ChartTypeSettingsInstance[];
+    /** Indented sub-entries under this section's rail tab. */
+    subsections?: readonly ChartTypeSettingsSubsection[];
     /** `'active'` (default): shown only while this chart type is the active price style;
      *  `'always'`: shown whenever the type is registered. */
     visibility?: 'always' | 'active';
+    /** Rail position: `'end'` (default, after the built-in tabs) or `'after-symbol'`
+     *  (directly under the Symbol tab). Subsections follow their parent. */
+    placement?: 'after-symbol' | 'end';
 }
 /** Register (or replace) a chart type. */
 declare function registerChartType(def: ChartTypeDefinition): void;
@@ -323,6 +592,23 @@ interface RendererLayerArgs {
     priceStyle: string;
     /** Frame clock (ms) for pulses/fades; monotonic within a session. */
     nowMs: number;
+    /** Plot-relative pointer position, or null when the pointer is off the plot. Layers
+     *  that hover-test set `repaintOnCursor` on their definition so pointer moves repaint
+     *  them (only data-tier frames repaint layers otherwise). */
+    cursor: {
+        x: number;
+        y: number;
+    } | null;
+}
+/** How the active style's layer dims/slims the BASE painting under it (see
+ *  {@link RendererLayerInstance.modulateBase}). Omitted fields keep their defaults. */
+interface BasePaintingModulation {
+    /** Candle body width multiplier, (0..1] (1 = full width). */
+    candleBodyScale?: number;
+    /** Candle body-fill opacity, [0..1] (wick + border keep their own opacity). */
+    candleBodyAlpha?: number;
+    /** Gridline opacity, [0..1] (fade the grid as a reveal-under layer opens). */
+    gridAlpha?: number;
 }
 /** One live layer instance (per mounted renderer). */
 interface RendererLayerInstance {
@@ -332,6 +618,14 @@ interface RendererLayerInstance {
     render(args: RendererLayerArgs): void;
     /** Return true while the layer needs CONTINUOUS frames (a pulse/fade) — keeps the animator alive. */
     animating?(): boolean;
+    /**
+     * How the base painting (candles, grid) should be dimmed/slimmed under this layer for
+     * the CURRENT frame — a gradual counterpart of the chart type's all-or-nothing
+     * `basePainting: 'none'`. Called after `render`, only for the layer whose id matches
+     * the active price style; returning null (or omitting the method) leaves the base
+     * painting untouched. Values are clamped by the renderer.
+     */
+    modulateBase?(args: RendererLayerArgs): BasePaintingModulation | null;
     /** The renderer unmounted — release everything (the canvas itself is removed by the renderer). */
     destroy?(): void;
 }
@@ -342,6 +636,9 @@ interface RendererLayerDefinition {
     /** Stacking: `'below-data'` = behind the candles (reveal-under styles); `'above-data'` =
      *  over the candles, under the chrome/axes. Default `'above-data'`. */
     placement?: 'below-data' | 'above-data';
+    /** Repaint this layer when the pointer moves (hover hit-testing UIs). Off by default:
+     *  pointer moves normally repaint only the crosshair overlay, not the layers. */
+    repaintOnCursor?: boolean;
     /** Instance factory — called once per mounted renderer. */
     create(): RendererLayerInstance;
 }
@@ -402,4 +699,4 @@ declare const CATEGORICAL: readonly string[];
 /** Pick a stable categorical color for a string key (same key ⇒ same color). */
 declare function categoricalColor(key: string): string;
 
-export { ACCENT as A, BEARISH as B, CATEGORICAL as C, type DrawingTypeMeta as D, getDrawingType as E, registerChartType as F, registerDrawingType as G, HIGHLIGHT as H, INFO as I, registerRendererDefaults as J, registerRendererLayer as K, rendererDefaults as L, MARKER as M, NEUTRAL as N, rendererLayers as O, stableSeriesId as P, tickerModifierIds as Q, type RendererLayerArgs as R, SERIES_LINE as S, TRADE_EXIT as T, unregisterChartType as U, VALID as V, WARNING as W, unregisterRendererDefaults as X, unregisterRendererLayer as Y, ACCENT_BRIGHT as a, BULLISH as b, type BarTransform as c, CROSSHAIR as d, type ChartTypeDefinition as e, type ChartTypeSettingsSection as f, INVALID as g, type IdentifiableKind as h, type RendererLayerDefinition as i, type RendererLayerInstance as j, SESSION_OFF as k, SESSION_POST as l, SESSION_PRE as m, SLATE as n, SLATE_DEEP as o, type SeriesDataEngine as p, type SeriesDataEngineHost as q, type SettingsRowDescriptor as r, TRADE_LONG as s, TRADE_SHORT as t, categoricalColor as u, chartType as v, chartTypes as w, createDrawing as x, deserializeDrawing as y, drawingTypes as z };
+export { normalizeSettingsRow as $, ACCENT as A, BEARISH as B, CATEGORICAL as C, type DrawingTypeMeta as D, type SettingsRowValueKey as E, type SettingsRowWhen as F, type SettingsRowWidth as G, HIGHLIGHT as H, INFO as I, type SettingsSelectOption as J, type SettingsValueRow as K, TRADE_LONG as L, MARKER as M, NEUTRAL as N, TRADE_SHORT as O, categoricalColor as P, chartType as Q, type RendererLayerArgs as R, SERIES_LINE as S, TRADE_EXIT as T, chartTypes as U, VALID as V, WARNING as W, createDrawing as X, deserializeDrawing as Y, drawingTypes as Z, getDrawingType as _, ACCENT_BRIGHT as a, registerChartType as a0, registerDrawingType as a1, registerRendererDefaults as a2, registerRendererLayer as a3, rendererDefaults as a4, rendererLayers as a5, settingsRowValueKeys as a6, stableSeriesId as a7, tickerModifierIds as a8, unregisterChartType as a9, unregisterRendererDefaults as aa, unregisterRendererLayer as ab, BULLISH as b, type BarTransform as c, type BasePaintingModulation as d, CROSSHAIR as e, type ChartTypeDefinition as f, type ChartTypeSettingsInstance as g, type ChartTypeSettingsSection as h, type ChartTypeSettingsSubsection as i, INVALID as j, type IdentifiableKind as k, type NormalizedSettingsRow as l, type RendererLayerDefinition as m, type RendererLayerInstance as n, SESSION_OFF as o, SESSION_POST as p, SESSION_PRE as q, SLATE as r, SLATE_DEEP as s, type SeriesDataEngine as t, type SeriesDataEngineHost as u, type SettingsInlineControl as v, type SettingsRowCondition as w, type SettingsRowDescriptor as x, type SettingsRowInlineNumber as y, type SettingsRowSwatch as z };