@luxalgo/vela 0.6.21 → 0.7.0

package/dist/{chunk-T5Z5YUCF.js → chunk-CZRNTHD6.js}

@@ -525,7 +525,7 @@ function intersectRects(a, b) {
   return { left, top, right, bottom, width: right - left, height: bottom - top };
 }
 function placePopover(a) {
-  let left = a.align === "end" ? a.trigger.right - a.pop.width : a.trigger.left;
+  let left = a.align === "end" ? a.trigger.right - a.pop.width : a.align === "center" ? a.trigger.left + a.trigger.width / 2 - a.pop.width / 2 : a.trigger.left;
   const below = a.trigger.bottom + a.gap;
   const above = a.trigger.top - a.pop.height - a.gap;
   const fitsBelow = below + a.pop.height <= a.clamp.bottom;
@@ -597,6 +597,8 @@ var Popover = class {
     this.onKey = null;
     this.onReflow = null;
     this.shown = false;
+    /** The pending removal of a fading-out shell; a show() that reuses the shell cancels it. */
+    this.leaveTimer = null;
     const doc = opts.trigger.ownerDocument;
     injectStyles(POPOVER_STYLE_ID, POPOVER_CSS, doc);
     this.trigger = opts.trigger;
@@ -604,6 +606,7 @@ var Popover = class {
     this.ctrl = popoverController(opts);
     this.boundary = opts.boundary ?? "viewport";
     this.theme = opts.theme;
+    this.fadeMs = Math.max(0, opts.fadeMs ?? 0);
     this.el = doc.createElement("div");
     this.el.className = "vela-popover vela-ui-layer" + (opts.className ? ` ${opts.className}` : "");
     this.el.dataset.position = this.ctrl.position;
@@ -627,11 +630,21 @@ var Popover = class {
       return;
     }
     if (open && open !== this) open.hide();
+    if (this.leaveTimer !== null) {
+      clearTimeout(this.leaveTimer);
+      this.leaveTimer = null;
+    }
     ensureUIHost(this.el, this.theme);
+    if (this.fadeMs > 0) {
+      this.el.style.transition = `opacity ${this.fadeMs}ms ease`;
+      this.el.style.opacity = "0";
+      this.el.style.pointerEvents = "";
+    }
     this.host.appendChild(this.el);
     this.shown = true;
     open = this;
     this.place();
+    if (this.fadeMs > 0) this.el.style.opacity = "1";
     const onOutside = (ev) => {
       const t = ev.target;
       if (this.el.contains(t) || this.trigger.contains(t)) return;
@@ -664,7 +677,16 @@ var Popover = class {
     this.onOutside = null;
     this.onKey = null;
     this.onReflow = null;
-    this.el.remove();
+    if (this.fadeMs > 0) {
+      this.el.style.opacity = "0";
+      this.el.style.pointerEvents = "none";
+      this.leaveTimer = setTimeout(() => {
+        this.leaveTimer = null;
+        this.el.remove();
+      }, this.fadeMs);
+    } else {
+      this.el.remove();
+    }
     this.shown = false;
     if (open === this) open = null;
     this.ctrl.onClose?.();

package/dist/{chunk-XCBJU674.js → chunk-UHXG5J7C.js}

@@ -1,4 +1,4 @@
-import { normalizeProps, nextUid, runMachine, spreadProps } from './chunk-T5Z5YUCF.js';
+import { normalizeProps, nextUid, runMachine, spreadProps } from './chunk-CZRNTHD6.js';
 import { injectStyles } from './chunk-CAFCLMPF.js';
 import * as tooltip from '@zag-js/tooltip';
 import * as dialog from '@zag-js/dialog';

package/dist/{contributions-D8HdlKmp.d.cts → contributions-BjQ7hyIx.d.ts}

@@ -1,5 +1,5 @@
-import { u as Millis, aj as InputSchema, ah as IndicatorMeta, P as PriceStyle, O as OHLCV, I as InputValue, l as IndicatorModel, k as MoveTarget, av as PaneAxis, aI as SeriesSpec, af as Fill, B as Background, aA as PriceLine, a2 as DrawingLine, _ as DrawingBox, a1 as DrawingLabel, a6 as DrawingPolyline, a3 as DrawingLinefill, ab as DrawingTable, h as IndicatorStatus, a as VisibleRange, c as VelaTheme, S as SerializedDrawing, w as DrawingTypeKey, v as SnapMode, a4 as DrawingMode, e as IChartRenderer, R as RendererCapabilities, o as LegendActionView, p as LegendCalloutView, U as Unsubscribe, C as CrosshairEvent, A as AxisLongPressEvent, s as DataWindowReadout, n as SymbolPickerFn, aX as PaneInfo, ae as DrawingsOption, a8 as DrawingSeriesGateway, D as Drawing, b as VelaOptions, y as AddIndicatorOptions, au as MarketSwitch, at as MarketSnapshot, V as VisibleRangePreset, T as ThemeName } from './options-BCRmYALw.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-UtWw2CgJ.cjs';
+import { x as Millis, an as InputSchema, al as IndicatorMeta, P as PriceStyle, O as OHLCV, I as InputValue, l as IndicatorModel, k as MoveTarget, aH as PaneAxis, aV as SeriesSpec, aj as Fill, G as Background, aM as PriceLine, a6 as DrawingLine, a2 as DrawingBox, a5 as DrawingLabel, aa as DrawingPolyline, a7 as DrawingLinefill, af as DrawingTable, h as IndicatorStatus, a as VisibleRange, c as VelaTheme, S as SerializedDrawing, z as DrawingTypeKey, y as SnapMode, a8 as DrawingMode, u as MarkClickEvent, e as IChartRenderer, R as RendererCapabilities, o as LegendActionView, p as LegendCalloutView, U as Unsubscribe, C as CrosshairEvent, A as AxisLongPressEvent, v as DataWindowReadout, n as SymbolPickerFn, W as WallClock, b8 as PaneInfo, ai as DrawingsOption, ac as DrawingSeriesGateway, D as Drawing, s as TimelineMark, t as MarkGroup, b as VelaOptions, E as AddIndicatorOptions, aG as MarketSwitch, aF as MarketSnapshot, V as VisibleRangePreset, T as ThemeName } from './options-ex2_gtKp.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-Bu9E5Zh5.js';
 
 /**
  * A strategy's broker state at ONE bar — the flat summary a host reads while a script
@@ -503,6 +503,15 @@ interface NativeIndicatorDescriptor {
     readonly reactsToViewport?: boolean;
     /** Marks the type as beta — surfaced in the catalog so a host "add indicator" UI can badge it. */
     readonly beta?: boolean;
+    /**
+     * Whether instances get in-chart chrome. Absent ⇒ a legend row like any indicator.
+     * `false` ⇒ the output paints, but there is NO legend row (no title chip, no eye/gear/✕,
+     * uncounted by the fold chip) and `panes.list()` does not report it — for host-owned
+     * overlays (trade markers, event flags) whose on/off lives in the host's own UI. Distinct
+     * from hidden: a legend-less indicator still computes and paints; the host controls it
+     * through its handle.
+     */
+    readonly legend?: boolean;
     /**
      * Allow several instances of this type on one chart — every add creates a new one (a study
      * like a moving average is typically stacked at different lengths). Absent ⇒ SINGLE instance
@@ -772,6 +781,9 @@ interface VelaEventMap extends Record<string, unknown> {
     "drawing:settings": {
         id: string;
     };
+    /** A timeline-mark glyph was clicked — `ids` lists every mark under it (a cluster). Fires
+     *  before the popup opens; a mark without content opens none, so this is the host's hook. */
+    "mark:click": MarkClickEvent;
     /**
      * A SCRIPT computed — the first run over the history, a live tick, a new bar, an input
      * edit, a viewport move, a market switch. The payload carries the run itself (title,
@@ -1030,6 +1042,13 @@ declare class RendererControl {
      *  `'mobile'` switches its dialogs/toolbars to the touch-first presentation.
      *  Silent no-op on a renderer without adaptive chrome. */
     setLayoutMode(mode: 'mobile' | 'desktop'): this;
+    /**
+     * Drive the renderer's time-of-day chrome (the countdown-to-bar-close chip) from the
+     * host's own second pulse, so it ticks in step with a host clock display instead of
+     * on a separate timer that can read a different second. `null` hands the pulse back
+     * to the renderer. Silent no-op on a renderer without time-of-day chrome.
+     */
+    setWallClock(clock: WallClock | null): this;
 }
 
 /** Callback surface `PanesControl` uses to drive the orchestrator. */
@@ -1315,6 +1334,82 @@ declare class DrawingsControl {
     private ok;
 }
 
+/**
+ * Renderer-agnostic owner of the timeline-mark model (backs `chart.marks`). Holds the
+ * marks + group definitions (the source of truth), pushes snapshots to the renderer
+ * through its optional `setTimelineMarks` seam, and re-emits the renderer's glyph
+ * clicks as `mark:click`. Inert on a renderer without the `timelineMarks` capability —
+ * the model still fills, so `all()` and a later host UI see it.
+ */
+declare class MarksController {
+    private readonly renderer;
+    /** Insertion-ordered — the order a cluster falls back to for equal times. */
+    private readonly marks;
+    private readonly groups;
+    private readonly enabled;
+    private readonly subs;
+    constructor(renderer: IChartRenderer, events: TypedEventBus<VelaEventMap>);
+    /** Whether the active renderer paints timeline marks. */
+    get supported(): boolean;
+    /** Add (or replace, by id) one mark. */
+    add(mark: TimelineMark): void;
+    /** Replace the whole set — a market switch. */
+    set(marks: readonly TimelineMark[]): void;
+    remove(id: string): boolean;
+    clear(): void;
+    /** Every mark, in insertion order (shallow copies — mutating one changes nothing). */
+    all(): TimelineMark[];
+    /** Define (or replace) a group's presentation — its settings label and default visibility. */
+    defineGroup(group: MarkGroup): void;
+    /** The defined groups, in definition order. */
+    groupDefinitions(): MarkGroup[];
+    /**
+     * Show or hide one group's marks. The choice lives in the renderer's cosmetic config
+     * (the `marks` feature) — what the settings dialog's Events checkboxes edit and what
+     * a persisted chart restores — so it warns + no-ops on a renderer without it.
+     */
+    setGroupVisible(id: string, visible: boolean): void;
+    /** A group's effective visibility: the user's (persisted) choice, else the group's declared default, else visible. */
+    isGroupVisible(id: string): boolean;
+    destroy(): void;
+    private sync;
+}
+
+/**
+ * The chart's timeline-marks control surface (`chart.marks`) — sibling of
+ * `chart.drawings` / `chart.panes`. Marks are DATA, not user state: the chart never
+ * persists them; re-supply them when the market changes (`market:changed`). The model
+ * is core-owned, so every method works on any renderer; on one without the
+ * `timelineMarks` capability nothing paints (`supported` reports it) and the group
+ * visibility setter warns + no-ops.
+ */
+declare class MarksControl {
+    private readonly ctrl;
+    constructor(ctrl: MarksController);
+    /** Whether the active renderer paints timeline marks. */
+    get supported(): boolean;
+    /** Add one mark; an existing id is replaced in place. */
+    add(mark: TimelineMark): this;
+    /** Replace the whole set (a market switch). */
+    set(marks: readonly TimelineMark[]): this;
+    remove(id: string): this;
+    clear(): this;
+    /** Every mark, in insertion order. */
+    all(): TimelineMark[];
+    /**
+     * Define a visibility group's presentation: the label of its checkbox in chart
+     * settings (the Events tab) and its default visibility. Marks may name a group
+     * that was never defined — it then shows its capitalized id.
+     */
+    defineGroup(group: MarkGroup): this;
+    /** The defined groups, in definition order. */
+    groups(): MarkGroup[];
+    /** Show or hide one group's marks — the same switch as the settings checkbox, persisted with the chart's config. */
+    setGroupVisible(id: string, visible?: boolean): this;
+    /** A group's effective visibility (the user's choice, else the group's declared default). */
+    isGroupVisible(id: string): boolean;
+}
+
 /** Outcome of {@link Vela.runIndicator}: success carries the live handle, failure the error. */
 interface RunIndicatorResult {
     ok: boolean;
@@ -1348,6 +1443,7 @@ declare class Vela {
     private readonly panesControl;
     private readonly dataControl;
     private readonly drawingsControl;
+    private readonly marksControl;
     constructor(container: HTMLElement | string, options?: VelaOptions, deps?: VelaDeps);
     /**
      * Register a scripting engine so `addIndicator({ language })` can run that
@@ -1474,6 +1570,15 @@ declare class Vela {
      * `new Vela(el, { drawings: true })` or `chart.drawings.showToolbar()`.
      */
     get drawings(): DrawingsControl;
+    /**
+     * The chart's timeline-marks control surface: host events pinned to a bar and shown
+     * as glyphs on a lane above the time axis, each opening a popup on click —
+     * `chart.marks.add({ id, time, glyph, title, content })`, `chart.marks.set(list)`,
+     * `chart.marks.defineGroup({ id, label })`. Marks are data, not user state: re-supply
+     * them on `market:changed`. On a renderer without the `timelineMarks` capability the
+     * model still fills but nothing paints (`chart.marks.supported`).
+     */
+    get marks(): MarksControl;
     on<K extends keyof VelaEventMap>(event: K, handler: (payload: VelaEventMap[K]) => void): () => void;
     /** The current visible time range (`from`/`to` in epoch-ms), or null before data loads. */
     getVisibleRange(): VisibleRange | null;
@@ -1886,4 +1991,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 { TypedEventBus as $, type RunIndicatorResult as A, type BarsChangeReason as B, type CellStateContext as C, type DrawingsDocument as D, type ExternalIndicatorEntry as E, type FetchSeries as F, type SceneInspection as G, type ScriptRunCause as H, type IndicatorHandle as I, type ScriptRunResult as J, type SidePanelButton as K, type LegendActionDescriptor as L, type SidePanelDescriptor as M, type NativeIndicator as N, OVERRIDABLE_TOPBAR_IDS as O, type ParsedSymbol as P, type SidePanelHandle as Q, type Resolved as R, type ScriptingEngine as S, type SidePanelHeader as T, type StatePersistenceHandler as U, Vela as V, type WidgetContext as W, type StrategyFill as X, type StrategyState as Y, type StrategyTrade as Z, type SymbolRankingHook as _, type ScriptRun as a, type VelaDeps as a0, type VelaEventMap as a1, type VisibleBarRange as a2, type WidgetActionDescriptor as a3, type WidgetActionTarget as a4, type WidgetAttachment as a5, getNativeIndicator as a6, legendActions as a7, legendCallouts as a8, nativeIndicatorDescriptors as a9, nativeIndicatorTypes as aa, registerDefaultEngine as ab, registerLegendAction as ac, registerLegendCallout as ad, registerNativeIndicator as ae, registerSidePanel as af, registerStatePersistence as ag, registerSymbolRanking as ah, registerWidgetAction as ai, registerWidgetAttachment as aj, resolveEngines as ak, sidePanels as al, statePersistenceHandlers as am, symbolRanking as an, topbarActionOverride as ao, unregisterDefaultEngine as ap, unregisterLegendAction as aq, unregisterLegendCallout as ar, unregisterNativeIndicator as as, unregisterSidePanel as at, unregisterStatePersistence as au, unregisterWidgetAction as av, unregisterWidgetAttachment as aw, widgetActions as ax, widgetAttachments as ay, DEFAULT_PANEL_ORDER as az, 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 LegendCalloutContent as p, type LegendCalloutDescriptor as q, type LegendCalloutItem as r, type LegendCalloutSpec as s, type LegendIndicatorInfo as t, type NativeIndicatorContext as u, type NativeIndicatorDescriptor as v, type NativeIndicatorInfo as w, type NativeIndicatorOutput as x, type PreparedScript as y, RendererControl as z };
+export { type SymbolRankingHook as $, type RunIndicatorResult as A, type BarsChangeReason as B, type CellStateContext as C, type DrawingsDocument as D, type ExternalIndicatorEntry as E, type FetchSeries as F, type SceneInspection as G, type ScriptRunCause as H, type IndicatorHandle as I, type ScriptRunResult as J, type SidePanelButton as K, type LegendActionDescriptor as L, MarksControl as M, type NativeIndicator as N, OVERRIDABLE_TOPBAR_IDS as O, type ParsedSymbol as P, type SidePanelDescriptor as Q, type Resolved as R, type ScriptingEngine as S, type SidePanelHandle as T, type SidePanelHeader as U, Vela as V, type WidgetContext as W, type StatePersistenceHandler as X, type StrategyFill as Y, type StrategyState as Z, type StrategyTrade as _, type ScriptRun as a, TypedEventBus as a0, type VelaDeps as a1, type VelaEventMap as a2, type VisibleBarRange as a3, type WidgetActionDescriptor as a4, type WidgetActionTarget as a5, type WidgetAttachment as a6, getNativeIndicator as a7, legendActions as a8, legendCallouts as a9, DEFAULT_PANEL_ORDER as aA, nativeIndicatorDescriptors as aa, nativeIndicatorTypes as ab, registerDefaultEngine as ac, registerLegendAction as ad, registerLegendCallout as ae, registerNativeIndicator as af, registerSidePanel as ag, registerStatePersistence as ah, registerSymbolRanking as ai, registerWidgetAction as aj, registerWidgetAttachment as ak, resolveEngines as al, sidePanels as am, statePersistenceHandlers as an, symbolRanking as ao, topbarActionOverride as ap, unregisterDefaultEngine as aq, unregisterLegendAction as ar, unregisterLegendCallout as as, unregisterNativeIndicator as at, unregisterSidePanel as au, unregisterStatePersistence as av, unregisterWidgetAction as aw, unregisterWidgetAttachment as ax, widgetActions as ay, widgetAttachments as az, 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 LegendCalloutContent as p, type LegendCalloutDescriptor as q, type LegendCalloutItem as r, type LegendCalloutSpec as s, type LegendIndicatorInfo as t, type NativeIndicatorContext as u, type NativeIndicatorDescriptor as v, type NativeIndicatorInfo as w, type NativeIndicatorOutput as x, type PreparedScript as y, RendererControl as z };

package/dist/{contributions-FqIWhN4p.d.ts → contributions-Cv2Mutvn.d.cts}

@@ -1,5 +1,5 @@
-import { u as Millis, aj as InputSchema, ah as IndicatorMeta, P as PriceStyle, O as OHLCV, I as InputValue, l as IndicatorModel, k as MoveTarget, av as PaneAxis, aI as SeriesSpec, af as Fill, B as Background, aA as PriceLine, a2 as DrawingLine, _ as DrawingBox, a1 as DrawingLabel, a6 as DrawingPolyline, a3 as DrawingLinefill, ab as DrawingTable, h as IndicatorStatus, a as VisibleRange, c as VelaTheme, S as SerializedDrawing, w as DrawingTypeKey, v as SnapMode, a4 as DrawingMode, e as IChartRenderer, R as RendererCapabilities, o as LegendActionView, p as LegendCalloutView, U as Unsubscribe, C as CrosshairEvent, A as AxisLongPressEvent, s as DataWindowReadout, n as SymbolPickerFn, aX as PaneInfo, ae as DrawingsOption, a8 as DrawingSeriesGateway, D as Drawing, b as VelaOptions, y as AddIndicatorOptions, au as MarketSwitch, at as MarketSnapshot, V as VisibleRangePreset, T as ThemeName } from './options-BCRmYALw.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-Cb-2lC5O.js';
+import { x as Millis, an as InputSchema, al as IndicatorMeta, P as PriceStyle, O as OHLCV, I as InputValue, l as IndicatorModel, k as MoveTarget, aH as PaneAxis, aV as SeriesSpec, aj as Fill, G as Background, aM as PriceLine, a6 as DrawingLine, a2 as DrawingBox, a5 as DrawingLabel, aa as DrawingPolyline, a7 as DrawingLinefill, af as DrawingTable, h as IndicatorStatus, a as VisibleRange, c as VelaTheme, S as SerializedDrawing, z as DrawingTypeKey, y as SnapMode, a8 as DrawingMode, u as MarkClickEvent, e as IChartRenderer, R as RendererCapabilities, o as LegendActionView, p as LegendCalloutView, U as Unsubscribe, C as CrosshairEvent, A as AxisLongPressEvent, v as DataWindowReadout, n as SymbolPickerFn, W as WallClock, b8 as PaneInfo, ai as DrawingsOption, ac as DrawingSeriesGateway, D as Drawing, s as TimelineMark, t as MarkGroup, b as VelaOptions, E as AddIndicatorOptions, aG as MarketSwitch, aF as MarketSnapshot, V as VisibleRangePreset, T as ThemeName } from './options-ex2_gtKp.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-Ck2qyS_9.cjs';
 
 /**
  * A strategy's broker state at ONE bar — the flat summary a host reads while a script
@@ -503,6 +503,15 @@ interface NativeIndicatorDescriptor {
     readonly reactsToViewport?: boolean;
     /** Marks the type as beta — surfaced in the catalog so a host "add indicator" UI can badge it. */
     readonly beta?: boolean;
+    /**
+     * Whether instances get in-chart chrome. Absent ⇒ a legend row like any indicator.
+     * `false` ⇒ the output paints, but there is NO legend row (no title chip, no eye/gear/✕,
+     * uncounted by the fold chip) and `panes.list()` does not report it — for host-owned
+     * overlays (trade markers, event flags) whose on/off lives in the host's own UI. Distinct
+     * from hidden: a legend-less indicator still computes and paints; the host controls it
+     * through its handle.
+     */
+    readonly legend?: boolean;
     /**
      * Allow several instances of this type on one chart — every add creates a new one (a study
      * like a moving average is typically stacked at different lengths). Absent ⇒ SINGLE instance
@@ -772,6 +781,9 @@ interface VelaEventMap extends Record<string, unknown> {
     "drawing:settings": {
         id: string;
     };
+    /** A timeline-mark glyph was clicked — `ids` lists every mark under it (a cluster). Fires
+     *  before the popup opens; a mark without content opens none, so this is the host's hook. */
+    "mark:click": MarkClickEvent;
     /**
      * A SCRIPT computed — the first run over the history, a live tick, a new bar, an input
      * edit, a viewport move, a market switch. The payload carries the run itself (title,
@@ -1030,6 +1042,13 @@ declare class RendererControl {
      *  `'mobile'` switches its dialogs/toolbars to the touch-first presentation.
      *  Silent no-op on a renderer without adaptive chrome. */
     setLayoutMode(mode: 'mobile' | 'desktop'): this;
+    /**
+     * Drive the renderer's time-of-day chrome (the countdown-to-bar-close chip) from the
+     * host's own second pulse, so it ticks in step with a host clock display instead of
+     * on a separate timer that can read a different second. `null` hands the pulse back
+     * to the renderer. Silent no-op on a renderer without time-of-day chrome.
+     */
+    setWallClock(clock: WallClock | null): this;
 }
 
 /** Callback surface `PanesControl` uses to drive the orchestrator. */
@@ -1315,6 +1334,82 @@ declare class DrawingsControl {
     private ok;
 }
 
+/**
+ * Renderer-agnostic owner of the timeline-mark model (backs `chart.marks`). Holds the
+ * marks + group definitions (the source of truth), pushes snapshots to the renderer
+ * through its optional `setTimelineMarks` seam, and re-emits the renderer's glyph
+ * clicks as `mark:click`. Inert on a renderer without the `timelineMarks` capability —
+ * the model still fills, so `all()` and a later host UI see it.
+ */
+declare class MarksController {
+    private readonly renderer;
+    /** Insertion-ordered — the order a cluster falls back to for equal times. */
+    private readonly marks;
+    private readonly groups;
+    private readonly enabled;
+    private readonly subs;
+    constructor(renderer: IChartRenderer, events: TypedEventBus<VelaEventMap>);
+    /** Whether the active renderer paints timeline marks. */
+    get supported(): boolean;
+    /** Add (or replace, by id) one mark. */
+    add(mark: TimelineMark): void;
+    /** Replace the whole set — a market switch. */
+    set(marks: readonly TimelineMark[]): void;
+    remove(id: string): boolean;
+    clear(): void;
+    /** Every mark, in insertion order (shallow copies — mutating one changes nothing). */
+    all(): TimelineMark[];
+    /** Define (or replace) a group's presentation — its settings label and default visibility. */
+    defineGroup(group: MarkGroup): void;
+    /** The defined groups, in definition order. */
+    groupDefinitions(): MarkGroup[];
+    /**
+     * Show or hide one group's marks. The choice lives in the renderer's cosmetic config
+     * (the `marks` feature) — what the settings dialog's Events checkboxes edit and what
+     * a persisted chart restores — so it warns + no-ops on a renderer without it.
+     */
+    setGroupVisible(id: string, visible: boolean): void;
+    /** A group's effective visibility: the user's (persisted) choice, else the group's declared default, else visible. */
+    isGroupVisible(id: string): boolean;
+    destroy(): void;
+    private sync;
+}
+
+/**
+ * The chart's timeline-marks control surface (`chart.marks`) — sibling of
+ * `chart.drawings` / `chart.panes`. Marks are DATA, not user state: the chart never
+ * persists them; re-supply them when the market changes (`market:changed`). The model
+ * is core-owned, so every method works on any renderer; on one without the
+ * `timelineMarks` capability nothing paints (`supported` reports it) and the group
+ * visibility setter warns + no-ops.
+ */
+declare class MarksControl {
+    private readonly ctrl;
+    constructor(ctrl: MarksController);
+    /** Whether the active renderer paints timeline marks. */
+    get supported(): boolean;
+    /** Add one mark; an existing id is replaced in place. */
+    add(mark: TimelineMark): this;
+    /** Replace the whole set (a market switch). */
+    set(marks: readonly TimelineMark[]): this;
+    remove(id: string): this;
+    clear(): this;
+    /** Every mark, in insertion order. */
+    all(): TimelineMark[];
+    /**
+     * Define a visibility group's presentation: the label of its checkbox in chart
+     * settings (the Events tab) and its default visibility. Marks may name a group
+     * that was never defined — it then shows its capitalized id.
+     */
+    defineGroup(group: MarkGroup): this;
+    /** The defined groups, in definition order. */
+    groups(): MarkGroup[];
+    /** Show or hide one group's marks — the same switch as the settings checkbox, persisted with the chart's config. */
+    setGroupVisible(id: string, visible?: boolean): this;
+    /** A group's effective visibility (the user's choice, else the group's declared default). */
+    isGroupVisible(id: string): boolean;
+}
+
 /** Outcome of {@link Vela.runIndicator}: success carries the live handle, failure the error. */
 interface RunIndicatorResult {
     ok: boolean;
@@ -1348,6 +1443,7 @@ declare class Vela {
     private readonly panesControl;
     private readonly dataControl;
     private readonly drawingsControl;
+    private readonly marksControl;
     constructor(container: HTMLElement | string, options?: VelaOptions, deps?: VelaDeps);
     /**
      * Register a scripting engine so `addIndicator({ language })` can run that
@@ -1474,6 +1570,15 @@ declare class Vela {
      * `new Vela(el, { drawings: true })` or `chart.drawings.showToolbar()`.
      */
     get drawings(): DrawingsControl;
+    /**
+     * The chart's timeline-marks control surface: host events pinned to a bar and shown
+     * as glyphs on a lane above the time axis, each opening a popup on click —
+     * `chart.marks.add({ id, time, glyph, title, content })`, `chart.marks.set(list)`,
+     * `chart.marks.defineGroup({ id, label })`. Marks are data, not user state: re-supply
+     * them on `market:changed`. On a renderer without the `timelineMarks` capability the
+     * model still fills but nothing paints (`chart.marks.supported`).
+     */
+    get marks(): MarksControl;
     on<K extends keyof VelaEventMap>(event: K, handler: (payload: VelaEventMap[K]) => void): () => void;
     /** The current visible time range (`from`/`to` in epoch-ms), or null before data loads. */
     getVisibleRange(): VisibleRange | null;
@@ -1886,4 +1991,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 { TypedEventBus as $, type RunIndicatorResult as A, type BarsChangeReason as B, type CellStateContext as C, type DrawingsDocument as D, type ExternalIndicatorEntry as E, type FetchSeries as F, type SceneInspection as G, type ScriptRunCause as H, type IndicatorHandle as I, type ScriptRunResult as J, type SidePanelButton as K, type LegendActionDescriptor as L, type SidePanelDescriptor as M, type NativeIndicator as N, OVERRIDABLE_TOPBAR_IDS as O, type ParsedSymbol as P, type SidePanelHandle as Q, type Resolved as R, type ScriptingEngine as S, type SidePanelHeader as T, type StatePersistenceHandler as U, Vela as V, type WidgetContext as W, type StrategyFill as X, type StrategyState as Y, type StrategyTrade as Z, type SymbolRankingHook as _, type ScriptRun as a, type VelaDeps as a0, type VelaEventMap as a1, type VisibleBarRange as a2, type WidgetActionDescriptor as a3, type WidgetActionTarget as a4, type WidgetAttachment as a5, getNativeIndicator as a6, legendActions as a7, legendCallouts as a8, nativeIndicatorDescriptors as a9, nativeIndicatorTypes as aa, registerDefaultEngine as ab, registerLegendAction as ac, registerLegendCallout as ad, registerNativeIndicator as ae, registerSidePanel as af, registerStatePersistence as ag, registerSymbolRanking as ah, registerWidgetAction as ai, registerWidgetAttachment as aj, resolveEngines as ak, sidePanels as al, statePersistenceHandlers as am, symbolRanking as an, topbarActionOverride as ao, unregisterDefaultEngine as ap, unregisterLegendAction as aq, unregisterLegendCallout as ar, unregisterNativeIndicator as as, unregisterSidePanel as at, unregisterStatePersistence as au, unregisterWidgetAction as av, unregisterWidgetAttachment as aw, widgetActions as ax, widgetAttachments as ay, DEFAULT_PANEL_ORDER as az, 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 LegendCalloutContent as p, type LegendCalloutDescriptor as q, type LegendCalloutItem as r, type LegendCalloutSpec as s, type LegendIndicatorInfo as t, type NativeIndicatorContext as u, type NativeIndicatorDescriptor as v, type NativeIndicatorInfo as w, type NativeIndicatorOutput as x, type PreparedScript as y, RendererControl as z };
+export { type SymbolRankingHook as $, type RunIndicatorResult as A, type BarsChangeReason as B, type CellStateContext as C, type DrawingsDocument as D, type ExternalIndicatorEntry as E, type FetchSeries as F, type SceneInspection as G, type ScriptRunCause as H, type IndicatorHandle as I, type ScriptRunResult as J, type SidePanelButton as K, type LegendActionDescriptor as L, MarksControl as M, type NativeIndicator as N, OVERRIDABLE_TOPBAR_IDS as O, type ParsedSymbol as P, type SidePanelDescriptor as Q, type Resolved as R, type ScriptingEngine as S, type SidePanelHandle as T, type SidePanelHeader as U, Vela as V, type WidgetContext as W, type StatePersistenceHandler as X, type StrategyFill as Y, type StrategyState as Z, type StrategyTrade as _, type ScriptRun as a, TypedEventBus as a0, type VelaDeps as a1, type VelaEventMap as a2, type VisibleBarRange as a3, type WidgetActionDescriptor as a4, type WidgetActionTarget as a5, type WidgetAttachment as a6, getNativeIndicator as a7, legendActions as a8, legendCallouts as a9, DEFAULT_PANEL_ORDER as aA, nativeIndicatorDescriptors as aa, nativeIndicatorTypes as ab, registerDefaultEngine as ac, registerLegendAction as ad, registerLegendCallout as ae, registerNativeIndicator as af, registerSidePanel as ag, registerStatePersistence as ah, registerSymbolRanking as ai, registerWidgetAction as aj, registerWidgetAttachment as ak, resolveEngines as al, sidePanels as am, statePersistenceHandlers as an, symbolRanking as ao, topbarActionOverride as ap, unregisterDefaultEngine as aq, unregisterLegendAction as ar, unregisterLegendCallout as as, unregisterNativeIndicator as at, unregisterSidePanel as au, unregisterStatePersistence as av, unregisterWidgetAction as aw, unregisterWidgetAttachment as ax, widgetActions as ay, widgetAttachments as az, 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 LegendCalloutContent as p, type LegendCalloutDescriptor as q, type LegendCalloutItem as r, type LegendCalloutSpec as s, type LegendIndicatorInfo as t, type NativeIndicatorContext as u, type NativeIndicatorDescriptor as v, type NativeIndicatorInfo as w, type NativeIndicatorOutput as x, type PreparedScript as y, RendererControl as z };