# Configuration precedence (/vela-pro/persistence/precedence)



Constructor options set the initial defaults for a new workspace. Once `persist` is enabled and a state document has been saved, Vela Pro restores the user's saved state over most constructor options on reload. This page documents the precedence order between constructor options, saved state documents, per-symbol drawing storage, and runtime API calls.

## Saved state vs. workspace options [#saved-state-vs-workspace-options]

When `persist` is enabled, `VelaWorkspace` restores the saved state document during initialization, treating most constructor options as fallback defaults for new users without saved state.

| Constructor option                                                                   | Behavior when a saved state document exists                                                                                                                 |
| ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `layout`                                                                             | Restores the saved `layout` if its ID is registered. Exception: passing `layout: false` forces a single-chart workspace regardless of the saved document.   |
| `symbol`, `timeframe`, `priceStyle`, `bars`, `session`, and `cells` overrides        | Charts present in the saved document restore completely from the document. Constructor options seed only newly added chart slots missing from the document. |
| `visibleRange`                                                                       | Applied only to charts initialized from constructor options; ignored on restored charts.                                                                    |
| `upColor`, `downColor`, `logScale`, `currentPriceLine`, and other appearance options | Applied first at construction, then overridden by each chart's saved `rendererConfig`.                                                                      |
| `timezone`                                                                           | Uses the saved `timezone` from the document.                                                                                                                |
| `sync`                                                                               | Uses the saved `sync` links when present in the document.                                                                                                   |
| `indicators` (manifest)                                                              | Manifest entries with `enabled: true` mount only on charts that have no saved indicators; restored charts load their saved indicator set.                   |
| `volume`                                                                             | Restored charts mount the volume study only if `"volume"` is listed in their saved indicators.                                                              |
| `theme`, locale options, `providers`, `engines`, `live`, `topbar`, `sidebar`         | Excluded from the state document; constructor options always govern these settings.                                                                         |

With an asynchronous `storage` adapter, initialization runs in two phases: the workspace first mounts using your constructor options, then applies the saved state document once `storage.get()` resolves.

## Module settings vs. enabler options [#module-settings-vs-enabler-options]

Domain modules and Vela Pro features accept initial options in `enableVelaPro()` while persisting user adjustments in the workspace state document or dedicated stores. Whether changing a default option affects returning users depends on whether that setting is stored as a delta or saved in full:

| Feature or module setting                             | Precedence rule                                                                                                                                                                                         |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Trading `display`                                     | Delta-tracked. Only display toggles explicitly changed by the user are written to `ext['velapro.trading']`. Untouched display fields always inherit your latest option value, even for returning users. |
| Trading `safety`, `presets`, and order size           | Saved in full inside the state document. Once saved, stored values take precedence over enabler options.                                                                                                |
| Order book `settings`                                 | Saved in full. Keys present in `ext['velapro.orderbook']` override enabler options.                                                                                                                     |
| Calendar `settings` and `minImpact`                   | Saved in full. Stored values in `ext['velapro.calendar']` override enabler options.                                                                                                                     |
| Watchlist `defaultSymbols`                            | Seeds the initial watchlist only when `WatchlistStorage` returns empty state.                                                                                                                           |
| Paper broker `initialBalance`, `currency`, and `name` | Used only when creating the initial paper account; existing persisted accounts keep their stored attributes.                                                                                            |
| Code editor `initialSource`                           | Used only when no editor draft exists in storage.                                                                                                                                                       |

Settings marked "saved in full" write every field into the state document on each save regardless of whether the user modified it. Consequently, changing those option values in code affects only new users without saved state, whereas changes to Trading `display` options roll out automatically for any toggle a user has not overridden.

## Applying a state document [#applying-a-state-document]

Calling `workspace.applyState(doc)` replaces active workspace state rather than merging incrementally:

* Each chart's symbol, timeframe, chart type, `rendererConfig`, drawings, and persisted indicators update to match `doc`. Tracked indicators absent from `doc` are removed from the chart.
* Cross-chart `sync` links and splitter `trackSizes` adopt the document's values. Applying a document that omits those fields disables sync links and resets splitter proportions.
* Workspace-level `favorites`, `timeframeFavorites`, and `drawingTools` are replaced only when those keys exist on `doc`.
* Extension entries under `ext` restore only for keys present in `doc`. Modules whose keys are absent retain their current in-memory settings.

Always pass complete documents produced by `workspace.getState()`. See [Layouts and chart state](/vela-pro/persistence/layouts#in-place-updates-vs-full-rebuilds) for details on when `applyState()` updates charts in place versus rebuilding cells.

## State documents vs. per-symbol drawings [#state-documents-vs-per-symbol-drawings]

When per-symbol drawing storage is enabled, a chart's drawings for its active symbol can originate from either an applied state document or `SymbolDrawingsStorage`:

1. A state document applied to a chart takes precedence when its `drawings` payload contains at least one drawing, replacing active drawings and updating the per-symbol store for that symbol.
2. A state document with zero drawings never erases `SymbolDrawingsStorage`; the chart loads existing drawings for that symbol from the per-symbol store instead.
3. Only explicit removal (user deletion in the UI or `chart.drawings.clear()` in code) clears a symbol's stored drawings.
4. Applying multiple layout documents on the same workspace under a static `chartKey` causes non-empty layout drawings to overwrite one another under rule 1. Return a layout-specific prefix from `chartKey` when supporting tabs or saved layouts.

See [Drawing persistence](/vela-pro/persistence/stores/drawings#precedence-rules) for full details and `chartKey` examples.

## Host overrides vs. Vela Pro defaults [#host-overrides-vs-vela-pro-defaults]

`enableVelaPro()` registers shell, renderer, and engine defaults that per-workspace or per-chart options can override:

| Vela Pro default                 | Host override with higher precedence                                                                                                                                                                                                                                                                                                                |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Corner attribution (`watermark`) | `enableVelaPro({ watermark })` configures the default read once by workspaces and charts constructed afterward. Calling `chart.renderer.set('attribution', ...)` overrides it on that individual chart. Attribution is excluded from the state document, so saved state never alters it. See [Theming and branding](/vela-pro/customization/theme). |
| Side rail                        | Passing an explicit `sidebar` option (including `sidebar: false`) to `new VelaWorkspace(...)`.                                                                                                                                                                                                                                                      |
| Default Pine Script® engine      | Passing an explicit `'pine'` entry in the workspace `engines` option.                                                                                                                                                                                                                                                                               |

## Repeated `enableVelaPro()` calls [#repeated-enablevelapro-calls]

The first `enableVelaPro()` call on a page takes precedence for every feature and module it installs. Because each enabler registers once per page lifecycle, calling `enableVelaPro()` a second time cannot reconfigure an already-installed feature or disable it; a subsequent call can only enable features that were set to `false` in the first call and update `watermark` for workspaces constructed afterward.

This behavior directly affects persistence configuration: passing a custom `storage` adapter in a second `enableVelaPro()` call is ignored without throwing a warning. If drawings, templates, or module state continue writing to `localStorage` despite passing custom storage adapters, verify that no earlier module called `enableVelaPro()` during application bootstrap.

## Resetting saved state [#resetting-saved-state]

| State to reset                                                 | Procedure                                                                                                                                                      |
| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Single workspace back to constructor options                   | Delete the stored record under its `persist` key before constructing `VelaWorkspace` (with default storage, call `localStorage.removeItem('vela-workspace')`). |
| All users' workspaces after shipping new defaults              | Change the `persist` key string passed to `VelaWorkspace` so previously saved documents are ignored.                                                           |
| Single module's layout preferences                             | Remove that module's key (such as `velapro.trading`) from the state document's `ext` object before applying or returning it from `storage.get()`.              |
| Drawings for one symbol on a chart                             | Call `chart.drawings.clear()` while that symbol is active on the chart, which writes `null` to `SymbolDrawingsStorage.save()`.                                 |
| Indicator templates, favorites, watchlists, alerts, or journal | Delete the corresponding backend record or the `localStorage` key listed in [Overview](/vela-pro/persistence/overview#independent-stores).                     |

`VelaWorkspace` never invokes `storage.remove()` and exposes no method to wipe persisted documents. Implement deletions and document schema migrations in your application code or inside your storage adapter's `get()` method.

## Related [#related]

* [Layouts and chart state](/vela-pro/persistence/layouts)
* [Server-side storage](/vela-pro/persistence/backend)
