@luxalgo/vela 0.5.0

package/dist/widget.js

@@ -0,0 +1,1060 @@
+import { Glider, WidgetHistory, localStorageAdapter, decodeState, prefixedSymbol, SymbolPicker, IndicatorPicker, TimeframeQuick, Topbar, PanelDock, ObjectTree, DataWindow, ChartContextMenu, Toast, Watermark, Statusline, Bottombar, ZOOM_IN, ZOOM_OUT, PAN_FAST, ShortcutsHelp, indicatorLedger, sanitizeState, legacyWidgetState, parsePersisted, statuslineInkOf, toolShortcutHints, resolveIndicators, encodeState } from './chunk-OVQKKXLZ.js';
+export { Bottombar, ChartContextMenu, DataWindow, IndicatorPicker, ObjectTree, PanelDock, RANGE_PRESETS, ShortcutsHelp, Statusline, SymbolPicker, TimeframeQuick, Topbar, Watermark, dataWindowSections, decimalsFor, decodeState, encodeState, filterSymbols, fmtChange, fmtPrice, legacyWidgetState, loadPersisted, localStorageAdapter, parsePersisted, parseTimeframe, priceStyleLabel, resolveIndicators, sanitizeState, savePersisted, timeframeLabel, timeframeMs } from './chunk-OVQKKXLZ.js';
+import { registerBuiltinChartTypes, resolveTheme, parseSymbol, Vela, normalizeTimezone } from './chunk-KCCZNKH7.js';
+export { TIMEZONES, normalizeTimezone, tzButtonLabel, tzMenuLabel, tzOffset } from './chunk-KCCZNKH7.js';
+import { widgetAttachments, legendActionsProviderFor, resolveEngines } from './chunk-7UFX5ZIG.js';
+export { DEFAULT_PANEL_MAX_WIDTH, DEFAULT_PANEL_MIN_WIDTH, DEFAULT_PANEL_ORDER, DEFAULT_PANEL_WIDTH, SidePanel, clampPanelWidth, registerSidePanel, registerWidgetAction, registerWidgetAttachment, sidePanels, unregisterSidePanel, unregisterWidgetAction, unregisterWidgetAttachment, widgetActions, widgetAttachments } from './chunk-7UFX5ZIG.js';
+import { ensureUIHost, KeymapManager, Menu, applyPlotOverlayTokens, isEditableTarget } from './chunk-RHIDOUFL.js';
+import './chunk-KM6LHB3Y.js';
+import { injectStyles } from './chunk-GYD2THPV.js';
+
+// src/widget/url-state.ts
+var PARAMS = [
+  ["symbol", "symbol"],
+  ["timeframe", "interval"],
+  ["priceStyle", "style"],
+  ["timezone", "tz"],
+  ["bars", "bars"]
+];
+function readUrlState(search) {
+  const out = {};
+  try {
+    const q = new URLSearchParams(search);
+    for (const [key, param] of PARAMS) {
+      const v = q.get(param);
+      if (v) out[key] = v;
+    }
+  } catch {
+  }
+  return out;
+}
+function writeUrlState(state) {
+  if (typeof history === "undefined" || typeof location === "undefined") return;
+  try {
+    const q = new URLSearchParams(location.search);
+    for (const [key, param] of PARAMS) {
+      const v = state[key];
+      if (v) q.set(param, v);
+      else q.delete(param);
+    }
+    const qs = q.toString();
+    history.replaceState(null, "", `${location.pathname}${qs ? `?${qs}` : ""}${location.hash}`);
+  } catch {
+  }
+}
+
+// src/widget/VelaWidget.ts
+var DEFAULT_TIMEFRAMES = ["1", "5", "15", "60", "240", "D", "W"];
+var WIDGET_STYLE_ID = "vela-widget";
+var WIDGET_CSS = `
+.vela-widget { display: flex; flex-direction: column; width: 100%; height: 100%; background: var(--vela-bg); }
+.vela-widget-main { display: flex; flex-direction: row; flex: 1 1 auto; min-height: 0; }
+.vela-widget-chart { position: relative; flex: 1 1 auto; min-width: 0; }
+`;
+var VelaWidget = class {
+  constructor(container, opts) {
+    this.shortcutsHelp = null;
+    this.inner = null;
+    /** The manifest library (loaded once). */
+    this.manifest = [];
+    /** Live instances — the SAME entry may be added several times. */
+    this.instances = [];
+    /** Native-indicator catalog of the CURRENT chart (refreshed per rebuild/change). */
+    this.nativeCatalog = [];
+    /** Present native types, mirrored SYNC from the chart (see syncPresentNatives). */
+    this.presentNatives = [];
+    this.openDialogs = 0;
+    this.onRootKeydown = (ev) => this.routeTyping(ev);
+    /** Indicator titles (the in-chart legend rows) shown — reapplied across rebuilds. */
+    this.indicatorTitlesOn = true;
+    this.pendingRange = null;
+    /** Symbol already reported as unservable (the core re-reports on every index settle). */
+    this.unresolvedToasted = null;
+    /** Extra fetch depth the ACTIVE range chip needs — a view concern, kept apart from the
+     *  user's own `bars` setting so a preset never overwrites their preference. */
+    this.rangeBars = 0;
+    this.toast = null;
+    this.alerts = [];
+    this.alertsMenu = null;
+    this.glider = new Glider(() => this.inner);
+    /** Unified app+drawings undo timeline (Ctrl+Z / Ctrl+Y). Late-resolves the CURRENT
+     *  inner chart so steps recorded before a rebuild never act on a destroyed instance. */
+    this.history = new WidgetHistory(() => this.inner);
+    this.lastCrossPrice = null;
+    this.lastCrossTime = null;
+    /** Renderer cosmetic template carried across rebuilds (and persisted when enabled). */
+    this.savedConfig = null;
+    /** User-drawings document carried across rebuilds (and persisted when enabled). */
+    this.savedDrawings = null;
+    /** A restored indicator ledger waiting for the manifest to resolve. */
+    this.pendingIndicators = null;
+    /** Volume presence decided by a RESTORED ledger (null = follow the option). */
+    this.ledgerVolume = null;
+    /** The manifest can no longer change the instance set: it resolved, or no `indicators`
+     *  option exists so nothing will ever resolve. Gates the ledger's pending fallback —
+     *  once settled, a live empty set means "the user removed everything" and persists so. */
+    this.manifestSettled = false;
+    /** The volume auto-add rides the first candles (`load:end`); until then the registry
+     *  can't show it and the persisted ledger reports the INTENT instead. */
+    this.volumeMayBePending = true;
+    /** True when the boot state came from the LEGACY three-key layout — the first
+     *  unified save then drops the old `:config`/`:drawings` sub-keys. */
+    this.legacyKeys = false;
+    this.stateTimer = null;
+    this.stateListeners = /* @__PURE__ */ new Set();
+    /** Favorite drawing-tool types — mirrored from chart events, reapplied on rebuilds. */
+    this.favs = [];
+    /** Mounted attachment disposers (by id), torn down at destroy. */
+    this.attachmentDisposers = /* @__PURE__ */ new Map();
+    this.onUnload = () => this.persistNow();
+    this.indicatorsPromise = null;
+    this.destroyed = false;
+    this.buildSeq = 0;
+    const hostEl = typeof container === "string" ? document.querySelector(container) : container;
+    if (!hostEl) throw new Error(`VelaWidget: container not found: ${String(container)}`);
+    registerBuiltinChartTypes();
+    this.opts = opts;
+    this.storageKey = opts.persist === void 0 || opts.persist === false ? null : opts.persist === true ? "vela-widget" : opts.persist;
+    this.storage = opts.storage ?? localStorageAdapter();
+    let boot = null;
+    if (this.storageKey !== null) {
+      const raw = this.storage.get(this.storageKey);
+      if (raw instanceof Promise) void this.bootAsync(raw);
+      else {
+        boot = raw != null ? decodeState(raw) : null;
+        if (!boot) boot = this.bootLegacySync(raw);
+      }
+      window.addEventListener("beforeunload", this.onUnload);
+    }
+    const bootCell = boot ? boot.charts.find((c) => c.id === "c1") ?? boot.charts[0] : void 0;
+    const fromUrl = opts.urlState ? readUrlState(typeof location !== "undefined" ? location.search : "") : {};
+    this.symbol = fromUrl.symbol ?? prefixedSymbol(bootCell) ?? opts.symbol ?? "";
+    this.timeframe = fromUrl.timeframe ?? bootCell?.timeframe ?? opts.timeframe ?? "60";
+    this.priceStyle = fromUrl.priceStyle ?? bootCell?.priceStyle ?? opts.priceStyle ?? "candles";
+    this.timezone = fromUrl.timezone ?? boot?.timezone ?? opts.timezone ?? "Etc/UTC";
+    this.bars = Number(fromUrl.bars ?? bootCell?.bars ?? opts.bars ?? 1e3);
+    this.watermarkOn = bootCell?.watermark !== void 0 ? bootCell.watermark : opts.watermark !== false;
+    this.indicatorTitlesOn = bootCell?.indicatorTitles ?? true;
+    this.favs = boot?.favorites ? [...boot.favorites] : [];
+    this.savedConfig = bootCell?.rendererConfig ?? null;
+    this.savedDrawings = bootCell?.drawings ?? null;
+    this.pendingIndicators = bootCell?.indicators ?? null;
+    this.ledgerVolume = bootCell?.indicators ? bootCell.indicators.natives.includes("volume") : null;
+    this.manifestSettled = opts.indicators === void 0;
+    const doc = hostEl.ownerDocument;
+    injectStyles(WIDGET_STYLE_ID, WIDGET_CSS, doc);
+    this.root = doc.createElement("div");
+    this.root.className = "vela-widget";
+    ensureUIHost(this.root, resolveTheme(opts.theme));
+    this.symbolPicker = new SymbolPicker({
+      host: this.root,
+      onSelect: (symbol) => this.setSymbol(symbol),
+      onOpenChange: (open) => {
+        if (open) this.inner?.renderer.closeDialogs();
+        this.trackDialog(open);
+      }
+    });
+    this.indicatorPicker = new IndicatorPicker({
+      host: this.root,
+      library: () => [
+        ...this.nativeCatalog.filter((n) => n.supported).map((n) => ({ name: n.title, category: "Vela", native: true, nativeType: n.type, beta: n.beta })),
+        ...this.manifest.map((e) => ({ name: e.name, language: e.language, category: e.category }))
+      ],
+      onChart: () => [
+        ...this.nativeCatalog.filter((n) => n.present).map((n) => ({ name: n.title, native: true, nativeType: n.type })),
+        ...this.instances.map((it) => ({ name: it.entry.name, language: it.entry.language }))
+      ],
+      onAdd: (i) => {
+        const natives = this.nativeCatalog.filter((n) => n.supported);
+        if (i < natives.length) this.addNative(natives[i].type);
+        else this.addInstance(i - natives.length);
+      },
+      onRemove: (i) => {
+        const present = this.nativeCatalog.filter((n) => n.present);
+        if (i < present.length) this.removeNative(present[i].type);
+        else this.removeInstance(i - present.length);
+      },
+      onOpenChange: (open) => this.trackDialog(open)
+    });
+    this.tfQuick = new TimeframeQuick({
+      host: this.root,
+      onApply: (tf) => this.setTimeframe(tf),
+      onOpenChange: (open) => this.trackDialog(open)
+    });
+    this.topbar = new Topbar(this.root, {
+      symbol: this.symbol,
+      onSymbolClick: () => this.symbolPicker.open(),
+      onIndicatorsClick: () => this.indicatorPicker.open(),
+      onUndoClick: () => this.history.undo(),
+      onRedoClick: () => this.history.redo(),
+      onScreenshotClick: () => this.downloadScreenshot(),
+      onAlertsClick: (anchor) => this.openAlertsMenu(anchor),
+      timeframe: this.timeframe,
+      timeframes: opts.timeframes ?? DEFAULT_TIMEFRAMES,
+      priceStyle: this.priceStyle,
+      onTimeframe: (tf) => this.setTimeframe(tf),
+      onPriceStyle: (style) => this.setPriceStyle(style),
+      getContext: () => this.context()
+    });
+    this.history.onChange(() => this.topbar.setHistoryState(this.history.canUndo, this.history.canRedo));
+    const main = doc.createElement("div");
+    main.className = "vela-widget-main";
+    this.chartHost = doc.createElement("div");
+    this.chartHost.className = "vela-widget-chart";
+    main.appendChild(this.chartHost);
+    this.dock = new PanelDock(main, {
+      chrome: this.topbar,
+      context: () => this.context(),
+      changed: () => this.markStateDirty()
+    });
+    this.objectTree = new ObjectTree(main);
+    this.dataWindow = new DataWindow(main);
+    this.dock.addBuiltIn({ id: "dataWindow", title: "Data window", icon: "datawindow", order: 10, panel: this.dataWindow, onChart: (c) => this.dataWindow.onChart(c) });
+    this.dock.addBuiltIn({ id: "objects", title: "Object tree", icon: "objects", order: 20, panel: this.objectTree, onChart: (c) => this.objectTree.onChart(c) });
+    this.dock.refresh();
+    this.root.appendChild(main);
+    this.contextMenu = new ChartContextMenu(this.chartHost, {
+      resetView: () => {
+        this.inner?.renderer.set("autoScale", true);
+        this.inner?.setVisibleRangePreset("ALL");
+      },
+      timezone: () => this.timezone,
+      setTimezone: (zone) => this.setTimezone(zone),
+      getContext: () => this.context()
+    });
+    this.toast = new Toast(this.chartHost);
+    this.watermark = opts.watermark !== false ? new Watermark(this.chartHost, this.symbol, this.timeframe) : null;
+    this.watermark?.setVisible(this.watermarkOn);
+    this.statusline = opts.statusline !== false ? new Statusline(this.chartHost, this.symbol) : null;
+    this.statusline?.setMeta(this.timeframe, parseSymbol(this.symbol).provider ?? "");
+    this.bottombar = opts.bottombar !== false ? new Bottombar(this.root, {
+      timezone: this.timezone,
+      onRange: (preset) => this.applyRange(preset),
+      onTimezone: (zone) => this.setTimezone(zone),
+      onSettingsClick: () => this.inner?.renderer.openSettings()
+    }) : null;
+    hostEl.appendChild(this.root);
+    this.keymap = new KeymapManager();
+    this.keymap.attach(this.root);
+    this.keymap.register({
+      id: "chart.screenshot",
+      keys: "mod+alt+s",
+      label: "Download a chart screenshot",
+      category: "Chart",
+      run: () => this.downloadScreenshot()
+    });
+    this.keymap.register({ id: "chart.reset-view", keys: "alt+r", label: "Reset view (all history)", category: "Chart", run: () => this.inner?.setVisibleRangePreset("ALL") });
+    this.keymap.register({ id: "chart.toggle-log", keys: "alt+l", label: "Toggle logarithmic scale", category: "Chart", run: () => this.inner?.renderer.set("logScale", !this.inner.renderer.get("logScale")) });
+    this.keymap.register({
+      id: "chart.toggle-percent",
+      keys: "alt+p",
+      label: "Toggle percent scale",
+      category: "Chart",
+      run: () => {
+        const mode = this.inner?.renderer.get("scaleMode");
+        this.inner?.renderer.set("scaleMode", mode === "percent" ? "price" : "percent");
+      }
+    });
+    this.keymap.register({ id: "drawings.trendline", keys: "alt+t", label: "Arm the trend line tool", category: "Drawings", run: () => this.inner?.drawings.setTool("trendline") });
+    this.keymap.register({
+      id: "drawings.hline-cursor",
+      keys: "alt+h",
+      label: "Horizontal line at the cursor price",
+      category: "Drawings",
+      run: () => {
+        if (this.lastCrossPrice != null && this.lastCrossTime != null)
+          this.inner?.drawings.add("hline", { anchors: [{ time: this.lastCrossTime, price: this.lastCrossPrice }] });
+      }
+    });
+    this.keymap.register({
+      id: "drawings.vline-cursor",
+      keys: "alt+v",
+      label: "Vertical line at the cursor time",
+      category: "Drawings",
+      run: () => {
+        if (this.lastCrossTime != null && this.lastCrossPrice != null)
+          this.inner?.drawings.add("vline", { anchors: [{ time: this.lastCrossTime, price: this.lastCrossPrice }] });
+      }
+    });
+    this.keymap.register({ id: "history.undo", keys: ["mod+z"], label: "Undo", category: "Edit", run: () => this.history.undo() });
+    this.keymap.register({ id: "history.redo", keys: ["mod+y", "mod+shift+z"], label: "Redo", category: "Edit", run: () => this.history.redo() });
+    this.keymap.register({ id: "view.zoom-in", keys: "mod+arrowup", label: "Zoom in", category: "Chart", run: () => this.glider.zoom(ZOOM_IN) });
+    this.keymap.register({ id: "view.zoom-out", keys: "mod+arrowdown", label: "Zoom out", category: "Chart", run: () => this.glider.zoom(ZOOM_OUT) });
+    this.keymap.register({ id: "view.pan-left", keys: "mod+arrowleft", label: "Pan toward history", category: "Chart", run: () => this.inner?.panBy(-PAN_FAST) });
+    this.keymap.register({ id: "view.pan-right", keys: "mod+arrowright", label: "Pan toward now", category: "Chart", run: () => this.inner?.panBy(PAN_FAST) });
+    this.keymap.register({ id: "indicators.open", keys: "/", label: "Open the indicator picker", category: "Indicators", run: () => this.indicatorPicker.open() });
+    this.keymap.register({
+      id: "help.shortcuts",
+      keys: "?",
+      label: "Show this shortcuts panel",
+      category: "Help",
+      run: () => {
+        this.shortcutsHelp ?? (this.shortcutsHelp = new ShortcutsHelp(this.keymap, this.root, (open) => this.trackDialog(open)));
+        this.shortcutsHelp.open();
+      }
+    });
+    this.root.addEventListener("keydown", this.onRootKeydown);
+    this.root.tabIndex = -1;
+    this.rebuild();
+    this.mountAttachments();
+    if (opts.autofocus) this.inner?.renderer.focus();
+  }
+  /** Mount registered attachments not yet mounted on this widget (idempotent per id). */
+  mountAttachments() {
+    for (const att of widgetAttachments()) {
+      if (this.attachmentDisposers.has(att.id)) continue;
+      try {
+        this.attachmentDisposers.set(att.id, att.mount(this.context()));
+      } catch (err) {
+        console.warn(`[vela] widget attachment "${att.id}" failed to mount:`, err);
+      }
+    }
+  }
+  /** The context handed to contributed actions (see `registerWidgetAction`). */
+  context() {
+    const self = this;
+    return {
+      get chart() {
+        return self.chart;
+      },
+      symbol: this.symbol,
+      timeframe: this.timeframe,
+      priceStyle: this.priceStyle,
+      setSymbol: (symbol) => this.setSymbol(symbol),
+      setTimeframe: (tf) => this.setTimeframe(tf),
+      setPriceStyle: (style) => this.setPriceStyle(style),
+      openSymbolSearch: (query) => this.symbolPicker.open(query ?? ""),
+      togglePanel: (id, open) => this.dock.toggle(id, open),
+      host: this.root,
+      toast: (message, kind) => this.toast?.show(message, kind)
+    };
+  }
+  /** The recent engine alerts (topbar bell). */
+  openAlertsMenu(anchor) {
+    this.alertsMenu?.destroy();
+    const items = this.alerts.length ? this.alerts.map((a, i) => ({
+      id: String(i),
+      label: `${new Date(a.time).toLocaleTimeString()} \xB7 ${a.title}: ${a.message}`.slice(0, 70)
+    })) : [{ id: "none", label: "No alerts yet", disabled: true }];
+    this.alertsMenu = new Menu({ host: this.root, items, onSelect: () => {
+    } });
+    const r = anchor.getBoundingClientRect();
+    this.alertsMenu.openAt(r.left, r.bottom + 4);
+  }
+  /** Re-project contributed topbar actions and side panels (after late registrations). */
+  refreshActions() {
+    this.mountAttachments();
+    this.topbar.renderActions();
+    this.dock.refresh();
+    if (this.inner) this.inner.renderer.setLegendActions(legendActionsProviderFor(this.inner, () => this.context()));
+  }
+  /** The inner headless chart of the CURRENT build — becomes a new instance after a
+   *  symbol/timeframe change; don't cache it across awaits. */
+  get chart() {
+    if (!this.inner) throw new Error("VelaWidget is destroyed");
+    return this.inner;
+  }
+  /** Chrome that must follow the timeframe wherever it changes from (menu, quick entry,
+   *  range chip, API). Keeping it in one place is what stopped the status line from
+   *  drifting out of sync with the topbar. */
+  syncTimeframeChrome(tf) {
+    this.timeframe = tf;
+    this.topbar.setTimeframe(tf);
+    this.watermark?.update(this.symbol, tf);
+    this.statusline?.setMeta(tf, this.providerLabel());
+  }
+  /**
+   * The provider name to show: the one that RESOLVED the symbol, not the one configured.
+   * They differ whenever the `provider` option is just a default (or names something that
+   * isn't registered) — the status line must not claim a venue that served nothing.
+   */
+  providerLabel() {
+    const resolved = this.inner?.data.resolve(this.symbol)?.provider;
+    return resolved ?? parseSymbol(this.symbol).provider ?? "";
+  }
+  setTimeframe(tf) {
+    if (tf === this.timeframe || this.destroyed) return;
+    this.bottombar?.setActiveRange(null);
+    this.rangeBars = 0;
+    this.syncTimeframeChrome(tf);
+    this.markStateDirty();
+    void this.inner?.setMarket({ timeframe: tf, bars: this.bars });
+  }
+  /**
+   * Switch the chart symbol in place. An `EXCHANGE:` prefix pins the venue (the
+   * symbol picker composes one from the row the user pointed at) — a bare ticker
+   * resolves against the registered providers in declaration order.
+   */
+  setSymbol(symbol) {
+    if (this.destroyed) return;
+    if (symbol === this.symbol) return;
+    this.unresolvedToasted = null;
+    this.symbol = symbol;
+    this.topbar.setSymbol(symbol);
+    this.statusline?.setSymbol(symbol);
+    this.objectTree.setSymbol(symbol);
+    this.watermark?.update(symbol, this.timeframe);
+    this.markStateDirty();
+    void this.inner?.setMarket({ symbol });
+    this.statusline?.setMeta(this.timeframe, this.providerLabel());
+  }
+  // ── state surface (same triplet as the workspace: getState / applyState / state:changed) ──
+  /**
+   * Snapshot the COMPLETE widget state as the unified shell document — the SAME
+   * format `VelaWorkspace.getState()` returns, with a single `c1` cell: market,
+   * display prefs, the renderer config document, the user-drawings document, and
+   * the indicator ledger. This is what `persist` writes; hosts build custom flows
+   * on it (server snapshots, share links, templates) — and a saved widget state
+   * drops into a workspace slot as-is.
+   */
+  getState() {
+    const cell = {};
+    const live = this.inner?.market;
+    const symbol = live?.symbol ?? this.symbol;
+    if (symbol) cell.symbol = symbol;
+    const provider = parseSymbol(symbol ?? "").provider ?? void 0;
+    if (provider) cell.provider = provider;
+    cell.timeframe = live?.timeframe ?? this.timeframe;
+    cell.priceStyle = this.priceStyle;
+    if (this.bars > 0) cell.bars = this.bars;
+    cell.watermark = this.watermarkOn;
+    cell.indicatorTitles = this.indicatorTitlesOn;
+    if (this.inner) {
+      cell.rendererConfig = this.inner.renderer.getConfig();
+      cell.drawings = this.inner.drawings.toJSON();
+    } else {
+      if (this.savedConfig != null) cell.rendererConfig = this.savedConfig;
+      if (this.savedDrawings != null) cell.drawings = this.savedDrawings;
+    }
+    cell.indicators = indicatorLedger({
+      present: this.inner ? this.inner.presentNativeIndicators() : this.pendingIndicators?.natives ?? [],
+      instanceNames: this.instances.map((it) => it.entry.name),
+      pendingManifest: this.pendingIndicators?.manifest ?? null,
+      manifestSettled: this.manifestSettled,
+      volumePending: this.volumeMayBePending && (this.ledgerVolume ?? this.opts.volume !== false)
+    });
+    const state = { version: 1, layout: "1", activeCellId: "c1", timezone: this.timezone, charts: [{ id: "c1", ...cell }] };
+    if (this.favs.length > 0) state.favorites = [...this.favs];
+    const panels = this.dock.getState();
+    if (panels) state.panels = panels;
+    return state;
+  }
+  /**
+   * Restore a state document produced by {@link getState} — or by a WORKSPACE (the
+   * first cell of a multi-cell document applies). Untrusted-safe: malformed fields
+   * are dropped. Applied IN PLACE: the chart instance survives (market switches via
+   * `setMarket`), config/drawings/indicators are replaced. With `urlState` enabled,
+   * URL params still win over the document's market/prefs fields.
+   */
+  applyState(state) {
+    if (this.destroyed) return;
+    const st = sanitizeState(state);
+    if (!st) return;
+    const cell = st.charts.find((c) => c.id === "c1") ?? st.charts[0];
+    const fromUrl = this.opts.urlState ? readUrlState(typeof location !== "undefined" ? location.search : "") : {};
+    const tz = fromUrl.timezone ?? st.timezone;
+    if (tz && tz !== this.timezone) this.setTimezone(tz);
+    if (st.favorites) {
+      this.favs = [...st.favorites];
+      this.inner?.drawings.setFavorites(this.favs);
+    }
+    this.dock.applyState(st.panels);
+    if (cell) {
+      const style = fromUrl.priceStyle ?? cell.priceStyle;
+      if (style && style !== this.priceStyle) this.setPriceStyle(style);
+      if (cell.watermark !== void 0 && cell.watermark !== this.watermarkOn) this.setWatermarkVisible(cell.watermark);
+      if (cell.indicatorTitles !== void 0 && cell.indicatorTitles !== this.indicatorTitlesOn) this.setIndicatorTitlesVisible(cell.indicatorTitles);
+      if (cell.rendererConfig != null) {
+        this.savedConfig = cell.rendererConfig;
+        this.inner?.renderer.applyConfig(cell.rendererConfig);
+      }
+      if (cell.drawings != null) {
+        this.savedDrawings = cell.drawings;
+        this.inner?.drawings.fromJSON(cell.drawings);
+      }
+      if (cell.indicators) this.applyIndicatorLedger(cell.indicators);
+      const symbol = fromUrl.symbol ?? prefixedSymbol(cell);
+      const timeframe = fromUrl.timeframe ?? cell.timeframe;
+      const bars = Number(fromUrl.bars ?? cell.bars ?? 0);
+      const next = {};
+      if (symbol && symbol !== this.symbol) next.symbol = symbol;
+      if (timeframe && timeframe !== this.timeframe) next.timeframe = timeframe;
+      if (bars > 0 && bars !== this.bars) {
+        this.bars = bars;
+        next.bars = Math.max(bars, this.rangeBars);
+      }
+      if (Object.keys(next).length > 0) void this.inner?.setMarket(next);
+    }
+    this.markStateDirty();
+  }
+  /** Subscribe to `state:changed` — the persistable state changed (debounced ~500ms);
+   *  re-pull {@link getState}. Returns an unsubscribe function. */
+  on(event, handler) {
+    if (event !== "state:changed") return () => void 0;
+    this.stateListeners.add(handler);
+    return () => this.stateListeners.delete(handler);
+  }
+  /** Replace the indicator ledger: natives converge to the listed set (volume
+   *  included — removing it sticks, the core's auto-add respects the opt-out),
+   *  manifest instances are re-created by name — held until the manifest resolves. */
+  applyIndicatorLedger(led) {
+    const chart = this.inner;
+    if (!chart) return;
+    this.ledgerVolume = led.natives.includes("volume");
+    this.history.silently(() => {
+      for (const type of led.natives) {
+        if (!this.nativeCatalog.some((n) => n.type === type && n.present)) chart.addNativeIndicator(type);
+      }
+      for (const n of this.nativeCatalog) {
+        if (n.present && !led.natives.includes(n.type)) chart.addNativeIndicator(n.type).remove();
+      }
+      for (const it of [...this.instances]) this.dropInstance(it);
+    });
+    if (this.manifest.length > 0) {
+      for (const name of led.manifest) {
+        const entry = this.manifest.find((e) => e.name === name);
+        if (entry) this.instances.push({ entry, handle: this.addToChart(chart, entry) });
+      }
+      this.pendingIndicators = null;
+    } else if (!this.manifestSettled) {
+      this.pendingIndicators = led;
+    } else {
+      this.pendingIndicators = null;
+    }
+    this.refreshNativeCatalog();
+    this.syncIndicatorCount();
+  }
+  /** SYNC boot fallback: a LEGACY three-key payload read at construction. */
+  bootLegacySync(rawMain) {
+    if (this.storageKey === null) return null;
+    const cfg = this.storage.get(`${this.storageKey}:config`);
+    const drw = this.storage.get(`${this.storageKey}:drawings`);
+    if (cfg instanceof Promise || drw instanceof Promise) return null;
+    const doc = sanitizeState(legacyWidgetState(parsePersisted(rawMain), cfg, drw));
+    if (doc) this.legacyKeys = true;
+    return doc;
+  }
+  /** ASYNC boot: resolve the unified document (or migrate a legacy payload), then
+   *  late-apply it — the widget built with option defaults in the meantime. */
+  async bootAsync(rawMain) {
+    let doc = null;
+    try {
+      const raw = await rawMain;
+      doc = raw != null ? decodeState(raw) : null;
+      if (!doc && this.storageKey !== null) {
+        const [cfg, drw] = await Promise.all([
+          Promise.resolve(this.storage.get(`${this.storageKey}:config`)),
+          Promise.resolve(this.storage.get(`${this.storageKey}:drawings`))
+        ]);
+        doc = sanitizeState(legacyWidgetState(parsePersisted(raw), cfg, drw));
+        if (doc) this.legacyKeys = true;
+      }
+    } catch {
+      doc = null;
+    }
+    if (doc && !this.destroyed) this.applyState(doc);
+  }
+  /** Show/hide the symbol watermark behind the chart (persisted). */
+  setWatermarkVisible(visible) {
+    this.watermarkOn = visible;
+    this.watermark?.setVisible(visible);
+    this.markStateDirty();
+  }
+  /** Show/hide the indicator titles — the in-chart legend rows (persisted). */
+  setIndicatorTitlesVisible(visible) {
+    this.indicatorTitlesOn = visible;
+    this.inner?.renderer.set("indicatorTitles", visible);
+    this.markStateDirty();
+  }
+  /** Applied LIVE (renderer feature) — no rebuild; persists across rebuilds. */
+  setPriceStyle(style) {
+    this.priceStyle = style;
+    this.topbar.setPriceStyle(style);
+    this.inner?.renderer.set("priceStyle", style);
+    this.syncStatuslineColors();
+    this.markStateDirty();
+  }
+  /** OHLC/change ink in the status line follows the ACTIVE price style's configured
+   *  colors and direction rule (candle bodies by close-vs-open, baseline by position
+   *  against the live baseline price, …) instead of the fixed theme tokens. */
+  syncStatuslineColors() {
+    if (!this.statusline || !this.inner) return;
+    this.statusline.setDirectionColors(...statuslineInkOf(this.inner.renderer, this.priceStyle));
+  }
+  /** The widget shell (topbar, panels) keeps the app theme; the chart host's tokens
+   *  re-derive from the LIVE plot surface (see {@link applyPlotOverlayTokens}). */
+  syncPlotOverlayTokens() {
+    applyPlotOverlayTokens(this.chartHost, resolveTheme(this.opts.theme), this.inner?.renderer.getConfig() ?? null);
+  }
+  /**
+   * Swap the widget theme at runtime — `'dark'`, `'light'`, or a full custom theme.
+   * Applied LIVE: the inner chart re-skins through `Vela.setTheme` and its
+   * `theme:changed` event re-tokens the widget chrome (topbar, menus, panels) in
+   * place; the choice also persists into rebuilds. Same switch the user reaches from
+   * chart settings → Canvas → Theme.
+   */
+  setTheme(theme) {
+    if (this.destroyed) return;
+    this.opts.theme = theme;
+    this.inner?.setTheme(theme);
+  }
+  /** Applied LIVE (renderer feature) — no rebuild; persists across rebuilds. */
+  setTimezone(zone) {
+    this.timezone = zone;
+    this.bottombar?.setTimezone(zone);
+    this.inner?.renderer.set("timezone", zone);
+    this.markStateDirty();
+  }
+  /**
+   * Range chip: switch to the preset's timeframe, fetch enough history for its window,
+   * and frame it once ready. The in-place `setMarket` loads the depth, so it also runs
+   * when only the DEPTH grows (same timeframe, deeper window).
+   */
+  applyRange(preset) {
+    if (this.destroyed) return;
+    this.pendingRange = preset;
+    const tfChanged = preset.tf !== this.timeframe;
+    const deeper = preset.bars > Math.max(this.bars, this.rangeBars);
+    this.rangeBars = preset.bars;
+    if (tfChanged) this.syncTimeframeChrome(preset.tf);
+    if (tfChanged || deeper) {
+      void this.inner?.setMarket({ timeframe: preset.tf, bars: Math.max(this.bars, this.rangeBars), visibleRange: preset.preset }).then(() => {
+        if (!this.destroyed && this.pendingRange === preset) {
+          this.inner?.setVisibleRangePreset(preset.preset);
+          this.pendingRange = null;
+        }
+      });
+    } else {
+      this.inner?.setVisibleRangePreset(preset.preset);
+      this.pendingRange = null;
+    }
+  }
+  destroy() {
+    this.destroyed = true;
+    this.persistNow();
+    this.inner?.destroy();
+    this.inner = null;
+    for (const dispose of this.attachmentDisposers.values()) {
+      try {
+        dispose();
+      } catch {
+      }
+    }
+    this.attachmentDisposers.clear();
+    window.removeEventListener("beforeunload", this.onUnload);
+    this.root.removeEventListener("keydown", this.onRootKeydown);
+    this.topbar.destroy();
+    this.dock.destroy();
+    this.objectTree.destroy();
+    this.dataWindow.destroy();
+    this.shortcutsHelp?.destroy();
+    this.contextMenu.destroy();
+    this.symbolPicker.destroy();
+    this.indicatorPicker.destroy();
+    this.tfQuick.destroy();
+    this.statusline?.destroy();
+    this.watermark?.destroy();
+    this.bottombar?.destroy();
+    this.toast?.destroy();
+    this.alertsMenu?.destroy();
+    this.glider.stop();
+    this.history.destroy();
+    this.keymap.destroy();
+    this.root.remove();
+  }
+  /** Destroy + recreate the inner chart with the current symbol/timeframe, then
+   *  re-register providers/engines, rebind chrome, and re-add manifest indicators. */
+  rebuild() {
+    const seq = ++this.buildSeq;
+    if (this.inner) {
+      this.savedConfig = this.inner.renderer.getConfig();
+      this.savedDrawings = this.inner.drawings.toJSON();
+    }
+    this.inner?.destroy();
+    const {
+      providers,
+      engines,
+      indicators,
+      timeframes: _timeframes,
+      priceStyle: _priceStyle,
+      timezone: _timezone,
+      statusline: _statusline,
+      watermark: _watermark,
+      bottombar: _bottombar,
+      ...chartOpts
+    } = this.opts;
+    const chart = new Vela(this.chartHost, {
+      ...chartOpts,
+      symbol: this.symbol,
+      timeframe: this.timeframe,
+      bars: Math.max(this.bars, this.rangeBars),
+      volume: this.ledgerVolume ?? chartOpts.volume,
+      // A pending range chip frames the FIRST paint (no preview flash, no re-frame).
+      ...this.pendingRange ? { visibleRange: this.pendingRange.preset } : {}
+    });
+    for (const [name, make] of Object.entries(providers ?? {})) chart.data.registerProvider(name, make());
+    for (const [language, make] of Object.entries(resolveEngines(engines))) chart.registerEngine(language, make());
+    this.inner = chart;
+    this.symbolPicker.setSource(() => chart.data.symbols());
+    this.objectTree.setSymbol(this.symbol);
+    chart.renderer.setLegendActions(legendActionsProviderFor(chart, () => this.context()));
+    if (chart.renderer.supports("historyChords")) chart.renderer.set("historyChords", false);
+    this.dock.onChart(chart);
+    this.contextMenu.onChart(chart);
+    this.refreshNativeCatalog();
+    chart.on("indicator:added", () => {
+      this.syncPresentNatives();
+      this.refreshNativeCatalog();
+      this.markStateDirty();
+    });
+    chart.on("indicator:removed", ({ id }) => {
+      const idx = this.instances.findIndex((it) => it.handle?.id === id);
+      if (idx >= 0) {
+        const snapshot = this.instances[idx];
+        this.instances.splice(idx, 1);
+        this.syncIndicatorCount();
+        this.history.push({
+          undo: () => {
+            snapshot.handle = this.inner ? this.addToChart(this.inner, snapshot.entry) : null;
+            this.instances.push(snapshot);
+            this.syncIndicatorCount();
+          },
+          redo: () => this.dropInstance(snapshot)
+        });
+      } else {
+        const now = this.inner?.presentNativeIndicators() ?? [];
+        for (const type of this.presentNatives.filter((t) => !now.includes(t))) {
+          this.history.push({
+            undo: () => {
+              this.inner?.addNativeIndicator(type);
+              this.refreshNativeCatalog();
+            },
+            redo: () => {
+              this.inner?.addNativeIndicator(type).remove();
+              this.refreshNativeCatalog();
+            }
+          });
+        }
+      }
+      this.syncPresentNatives();
+      this.refreshNativeCatalog();
+      this.markStateDirty();
+    });
+    if (this.pendingIndicators) {
+      for (const type of this.pendingIndicators.natives) chart.addNativeIndicator(type);
+      if (this.manifestSettled) this.pendingIndicators = null;
+    }
+    this.syncPresentNatives();
+    chart.on("load:end", () => {
+      this.volumeMayBePending = false;
+    });
+    chart.on("theme:changed", (t) => {
+      this.opts.theme = t;
+      ensureUIHost(this.root, t);
+      this.syncPlotOverlayTokens();
+    });
+    chart.on("market:changed", ({ symbol, timeframe }) => {
+      this.refreshNativeCatalog();
+      if (this.statusline) this.statusline.onChart(chart);
+      if (symbol !== this.symbol) {
+        this.symbol = symbol;
+        this.topbar.setSymbol(symbol);
+        this.statusline?.setSymbol(symbol);
+        this.objectTree.setSymbol(symbol);
+        this.watermark?.update(symbol, this.timeframe);
+      }
+      if (timeframe !== this.timeframe) this.syncTimeframeChrome(timeframe);
+    });
+    this.history.onChart(chart);
+    chart.on("alert", (alert) => {
+      this.alerts.unshift({ title: alert.title ?? "Alert", message: alert.message, time: alert.time });
+      if (this.alerts.length > 20) this.alerts.pop();
+      this.toast?.show(`${alert.title ? alert.title + " \u2014 " : ""}${alert.message}`, "info", 4e3);
+      this.topbar.setAlertCount(this.alerts.length);
+    });
+    chart.on("indicator:error", ({ error }) => this.toast?.show(error.message, "error", 5e3));
+    chart.on("data:unresolved", ({ symbol, providers: providers2 }) => {
+      if (this.unresolvedToasted === symbol) return;
+      this.unresolvedToasted = symbol;
+      const list = providers2.length > 0 ? providers2.join(", ") : "none";
+      this.toast?.show(`No registered provider serves "${symbol}" (registered: ${list})`, "error", 6e3);
+    });
+    if (this.favs.length > 0) chart.drawings.setFavorites(this.favs);
+    chart.on("drawing:favorites", ({ favorites }) => {
+      this.favs = favorites;
+      this.markStateDirty();
+    });
+    if (chart.drawings.supported) chart.drawings.setToolShortcuts(toolShortcutHints(this.keymap));
+    chart.on("drawing:created", () => this.markStateDirty());
+    chart.on("drawing:edited", () => this.markStateDirty());
+    chart.on("drawing:removed", () => this.markStateDirty());
+    chart.renderer.onCrosshairMove((e) => {
+      this.lastCrossPrice = e.price;
+      this.lastCrossTime = e.time;
+    });
+    this.topbar.renderActions();
+    if (this.savedConfig != null) chart.renderer.applyConfig(this.savedConfig);
+    if (this.savedDrawings != null) chart.drawings.fromJSON(this.savedDrawings);
+    if (this.priceStyle !== "candles") chart.renderer.set("priceStyle", this.priceStyle);
+    if (this.timezone !== "Etc/UTC") chart.renderer.set("timezone", this.timezone);
+    if (!this.indicatorTitlesOn) chart.renderer.set("indicatorTitles", false);
+    chart.renderer.onConfigChanged(() => {
+      const zone = chart.renderer.get("timezone");
+      if (typeof zone === "string" && normalizeTimezone(zone) !== normalizeTimezone(this.timezone)) {
+        this.setTimezone(normalizeTimezone(zone));
+      }
+      this.syncStatuslineColors();
+      this.syncPlotOverlayTokens();
+    });
+    this.syncPlotOverlayTokens();
+    this.statusline?.onChart(chart);
+    this.syncStatuslineColors();
+    const advanced = {
+      title: "Advanced",
+      placement: "end",
+      rows: [
+        {
+          kind: "select",
+          label: "Bars to fetch",
+          options: ["500", "1000", "2000", "5000", "10000", "20000"],
+          get: () => String(this.bars),
+          set: (v) => {
+            this.bars = Number(v);
+            this.markStateDirty();
+            void this.inner?.setMarket({ bars: Math.max(this.bars, this.rangeBars) });
+          }
+        }
+      ]
+    };
+    const watermarkSection = {
+      title: "Watermark",
+      placement: "symbol",
+      rows: [
+        {
+          kind: "toggle",
+          label: "Symbol watermark",
+          get: () => this.watermarkOn,
+          set: (v) => this.setWatermarkVisible(v)
+        }
+      ]
+    };
+    if (this.statusline) {
+      const sl = this.statusline;
+      chart.renderer.setSettingsSections([
+        {
+          title: "Status line",
+          rows: [
+            { kind: "heading", label: "Status line" },
+            { kind: "toggle", label: "Symbol name", get: () => sl.partVisible("name"), set: (v) => sl.setPartVisible("name", v) },
+            { kind: "toggle", label: "Market status", get: () => sl.partVisible("market"), set: (v) => sl.setPartVisible("market", v) },
+            { kind: "toggle", label: "OHLC values", get: () => sl.partVisible("ohlc"), set: (v) => sl.setPartVisible("ohlc", v) },
+            { kind: "toggle", label: "Bar change values", get: () => sl.partVisible("change"), set: (v) => sl.setPartVisible("change", v) },
+            { kind: "heading", label: "Indicators" },
+            {
+              kind: "toggle",
+              label: "Titles",
+              get: () => this.indicatorTitlesOn,
+              set: (v) => this.setIndicatorTitlesVisible(v)
+            }
+          ]
+        },
+        advanced,
+        watermarkSection
+      ]);
+    } else {
+      chart.renderer.setSettingsSections([advanced, watermarkSection]);
+    }
+    void chart.ready().then(() => {
+      if (this.buildSeq !== seq || this.destroyed) return;
+      if (this.pendingRange) {
+        chart.setVisibleRangePreset(this.pendingRange.preset);
+        this.pendingRange = null;
+      }
+      this.statusline?.setMeta(this.timeframe, this.providerLabel());
+    });
+    if (this.manifest.length || this.instances.length) {
+      for (const it of this.instances) it.handle = this.addToChart(chart, it.entry);
+      this.syncIndicatorCount();
+    } else if (indicators !== void 0) {
+      this.indicatorsPromise ?? (this.indicatorsPromise = resolveIndicators(indicators).then((list) => {
+        this.manifest = list;
+        const pending = this.pendingIndicators;
+        this.instances = pending ? pending.manifest.map((name) => list.find((e) => e.name === name)).filter((e) => e != null).map((entry) => ({ entry, handle: null })) : list.filter((e) => e.enabled).map((entry) => ({ entry, handle: null }));
+        if (pending) this.pendingIndicators = null;
+        this.manifestSettled = true;
+        return list;
+      }));
+      void this.indicatorsPromise.then(() => {
+        if (this.buildSeq !== seq || this.destroyed) return;
+        for (const it of this.instances) {
+          it.handle = this.addToChart(chart, it.entry);
+        }
+        this.syncIndicatorCount();
+      });
+    }
+  }
+  /** Refresh the native catalog (supported/present flags) for the current chart. */
+  refreshNativeCatalog() {
+    const chart = this.inner;
+    if (!chart) return;
+    void chart.availableNativeIndicators().then((list) => {
+      if (this.inner !== chart || this.destroyed) return;
+      this.nativeCatalog = list.map((n) => ({ type: n.type, title: n.title, supported: n.supported, present: n.present, beta: n.beta }));
+      this.syncIndicatorCount();
+      this.indicatorPicker.sync();
+    });
+  }
+  /** Add a native indicator (single-instance per type — the core dedupes). */
+  addNative(type) {
+    this.inner?.addNativeIndicator(type);
+    this.syncPresentNatives();
+    this.refreshNativeCatalog();
+    this.history.push({
+      undo: () => {
+        this.inner?.addNativeIndicator(type).remove();
+        this.refreshNativeCatalog();
+      },
+      redo: () => {
+        this.inner?.addNativeIndicator(type);
+        this.refreshNativeCatalog();
+      }
+    });
+  }
+  removeNative(type) {
+    this.inner?.addNativeIndicator(type).remove();
+    this.refreshNativeCatalog();
+  }
+  /** Sync mirror of the chart's present native types — the removal handler diffs
+   *  against it to identify (and record) whichever type was just removed. */
+  syncPresentNatives() {
+    this.presentNatives = this.inner?.presentNativeIndicators() ?? [];
+  }
+  /** Add ONE instance of a manifest entry (repeatable — duplicates are legitimate). */
+  addInstance(libraryIndex) {
+    const entry = this.manifest[libraryIndex];
+    if (!entry || this.destroyed) return;
+    const it = { entry, handle: this.inner ? this.addToChart(this.inner, entry) : null };
+    this.instances.push(it);
+    this.syncIndicatorCount();
+    const snapshot = it;
+    this.history.push({
+      undo: () => this.dropInstance(snapshot),
+      redo: () => {
+        snapshot.handle = this.inner ? this.addToChart(this.inner, snapshot.entry) : null;
+        this.instances.push(snapshot);
+        this.syncIndicatorCount();
+      }
+    });
+  }
+  /** Remove one live instance (picker trash). */
+  removeInstance(instanceIndex) {
+    const it = this.instances[instanceIndex];
+    if (!it || this.destroyed) return;
+    this.dropInstance(it);
+    const snapshot = it;
+    this.history.push({
+      undo: () => {
+        snapshot.handle = this.inner ? this.addToChart(this.inner, snapshot.entry) : null;
+        this.instances.push(snapshot);
+        this.syncIndicatorCount();
+      },
+      redo: () => this.dropInstance(snapshot)
+    });
+  }
+  dropInstance(it) {
+    const idx = this.instances.indexOf(it);
+    if (idx >= 0) this.instances.splice(idx, 1);
+    try {
+      it.handle?.remove();
+    } catch {
+    }
+    it.handle = null;
+    this.syncIndicatorCount();
+  }
+  syncIndicatorCount() {
+    this.topbar.setIndicatorCount(this.instances.length + this.nativeCatalog.filter((n) => n.present).length);
+  }
+  addToChart(chart, ind) {
+    try {
+      return chart.addIndicator(ind.script, ind.language !== void 0 ? { language: ind.language } : void 0);
+    } catch (err) {
+      console.warn(`[vela] indicator "${ind.name}" failed to add:`, err);
+      return null;
+    }
+  }
+  /** Bare-typing router: letters → symbol search (seeded), digits → timeframe entry. */
+  routeTyping(ev) {
+    if (this.destroyed || this.openDialogs > 0) return;
+    if (ev.ctrlKey || ev.metaKey || ev.altKey) return;
+    if (isEditableTarget(ev)) return;
+    const key = ev.key;
+    if (/^[a-zA-Z]$/.test(key)) {
+      ev.preventDefault();
+      this.symbolPicker.open(key.toUpperCase());
+    } else if (/^[0-9]$/.test(key)) {
+      ev.preventDefault();
+      this.tfQuick.open(key);
+    }
+  }
+  trackDialog(open) {
+    this.openDialogs = Math.max(0, this.openDialogs + (open ? 1 : -1));
+    if (open) this.keymap.pushScope("dialog");
+    else this.keymap.popScope("dialog");
+  }
+  downloadScreenshot() {
+    const url = this.inner?.renderer.screenshot();
+    if (!url) return;
+    const a = this.root.ownerDocument.createElement("a");
+    a.href = url;
+    a.download = `${this.symbol || "chart"}-${this.timeframe}.png`;
+    a.click();
+  }
+  /** The persistable state changed: debounce (~500ms), then notify `state:changed`
+   *  listeners and flush — the same cadence as the workspace. */
+  markStateDirty() {
+    if (this.destroyed) return;
+    if (this.stateTimer != null) clearTimeout(this.stateTimer);
+    this.stateTimer = setTimeout(() => {
+      this.stateTimer = null;
+      for (const listener of [...this.stateListeners]) listener();
+      this.persistNow();
+    }, 500);
+  }
+  /** Write the unified state document through the adapter (persist mode only) — also
+   *  the unload/destroy flush. The first save after a LEGACY boot rewrites the main
+   *  key in the unified format and drops the old `:config`/`:drawings` sub-keys. */
+  persistNow() {
+    if (this.stateTimer != null) {
+      clearTimeout(this.stateTimer);
+      this.stateTimer = null;
+    }
+    const state = this.getState();
+    if (this.storageKey !== null) {
+      try {
+        void this.storage.set(this.storageKey, encodeState(state));
+      } catch {
+      }
+      if (this.legacyKeys) {
+        this.legacyKeys = false;
+        try {
+          void this.storage.remove?.(`${this.storageKey}:config`);
+          void this.storage.remove?.(`${this.storageKey}:drawings`);
+        } catch {
+        }
+      }
+    }
+    if (this.opts.urlState) {
+      writeUrlState({
+        symbol: this.symbol,
+        timeframe: this.timeframe,
+        priceStyle: this.priceStyle,
+        timezone: this.timezone,
+        bars: String(this.bars),
+        watermark: this.watermarkOn ? "1" : "0",
+        favorites: this.favs.join(",")
+      });
+    }
+  }
+};
+
+export { VelaWidget, readUrlState, writeUrlState };