@trdrs/quickcharts 1.2.0 → 2.0.0

package/README.md

@@ -1,9 +1,8 @@
 # @trdrs/quickcharts
 
-Quick Charts is a charting library that draws over the datafeed and the storage you supply. The chart
-consumes the `ChartDatafeed` interface and never a concrete backend, so your feed drives it without a
-change to the chart. It does not include market data, trading, accounts, execution, community, news
-or hosting: the host supplies data and storage, and the chart draws.
+Quick Charts is a datafeed-driven charting library with drawings, indicators, layouts and replay.
+It draws over the datafeed and the storage you supply: the chart consumes the `ChartDatafeed`
+interface, so your feed drives it without a change to the chart.
 
 ## Install
 
@@ -21,8 +20,8 @@ runtime. Use default peer resolution; do not suppress peer checks.
 Quick Charts is licensed under the Apache License 2.0: see `LICENSE` and `NOTICE`. Because the
 renderer is *your* dependency, its own Apache-2.0 NOTICE
 obligations attach to **your** bundle: `THIRD-PARTY-NOTICES.md` in this package spells out exactly
-what to carry and how. The chart includes no trading, accounts or executions; an application that
-trades composes those outside the chart, through the extension seam below.
+what to carry and how. An application composes its own features on the chart through the extension
+seam below.
 
 Quickstart, the smallest working chart (see [The widget](#the-widget) for the full options). The
 stylesheet import is not optional: it carries the chart's layout as well as its look, and without it
@@ -44,9 +43,8 @@ await widget.ready()
 Implement `ChartDatafeed` (see `datafeed.ts`). Required methods: `search`, `resolve`, `history`,
 `subscribeBars`. Optional: `serverTime` (countdown skew correction) and `config` (a feed-level
 capability declaration, described [below](#capability-declaration-config-optional)). The datafeed serves
-symbol metadata, bars and bar updates and nothing else: a quote board (last, change, volume) or a
-top-of-book is not a chart concern, and your host fans quotes to its own consumers from its own
-source.
+symbol metadata, bars and bar updates; your host serves quotes (last, change, volume, the top of
+book) to its own consumers from its own source.
 
 When `appearance.countdown` is enabled, a live streaming time bar replaces the native last-value
 label with one price-and-time label. The price uses the resolved symbol formatter. Replay, stale,
@@ -176,8 +174,8 @@ export const feed: ChartDatafeed = {
 ```
 
 Declare only what is **true**. Absent method / absent field / empty list = unconstrained, so a feed that
-serves any interval must not declare a finite `resolutions` list, because the widget then enforces it.
-The UDF adapter declares automatically from the server's own `/config` (and only ever declares
+serves any timeframe must not declare a finite `resolutions` list, because the widget then enforces
+it. The UDF adapter declares automatically from the server's own `/config` (and only ever declares
 timeframes it would actually serve).
 
 ## The UDF on-ramp
@@ -213,10 +211,11 @@ What the adapter honors of the protocol:
 
 Symbology is the set of display facts that decide how a market's prices are written. Your datafeed
 owns them (`resolve` answers with `SymbolInfo`), and one package formatter uses them everywhere a
-price appears: the price scale, the crosshair and last-price labels, the legend, the level menu,
-every drawing label, study scales, and the extension seam. Precision comes from the symbol, never
-from the size of the price, so the same market reads at the same width on every surface. A study
-that declares its own precision keeps it; every other value writes through the symbol formatter.
+price appears: the price scale, the crosshair and last-price labels, the legend, the context menu,
+every drawing label, indicator scales, and the extension seam. Precision comes from the symbol,
+never from the size of the price, so the same market reads at the same width on every surface. An
+indicator that declares its own precision keeps it; every other value writes through the symbol
+formatter.
 
 `PriceFormat` expresses every supported form in five facts:
 
@@ -303,8 +302,8 @@ symbolNames({ symbol: 'NASDAQ:AAPL', name: 'Apple Inc', exchange: 'NASDAQ', type
 symbolNames('HYPERLIQUID:ETH').mark // 'ETH', before the symbol resolves
 ```
 
-Symbology is display truth, not trading truth. It carries no order quantity, price step, lot size,
-or pip value. Your broker integration owns those, and a broker's execution grid can differ from a
+Symbology is display truth: how the chart writes a market's prices. Execution facts, such as lot
+size and pip value, stay with your trading integration, and its execution grid can differ from the
 chart's display grid.
 
 If your data comes from a UDF server, map its `/symbols` answer without collapsing the facts:
@@ -322,14 +321,14 @@ info?.dataStatus // 'streaming'
 
 Quick Charts persists two different kinds of thing, and the difference decides where each one lives.
 
-Saved charts, layouts, drawing documents and templates are **entities**: a user names them, opens
+Saved charts, layouts, drawing documents and templates are **entities**: a viewer names them, opens
 them in two tabs, and can lose them. They have identity and versions, and they live on the
 save/load adapter you supply. Viewer preferences (the last symbol and timeframe, the scale mode, the
 replay speed) are **flat settings**: they need no identity, and they live on the small `ChartStorage`
 port beside it.
 
 The chart never writes on its own. It tells you when a save would be worth making, through the
-`saveNeeded` event, and it runs a write only when a user asks for one through the built-in UI or
+`saveNeeded` event, and it runs a write only when a viewer asks for one through the built-in UI or
 when you call a save method yourself.
 
 ### What a saved entity carries
@@ -367,7 +366,7 @@ changes, and a menu with Save, an Autosave switch, Make a copy, Rename, Download
 new layout, the layouts used most recently, and Open layout: the Layouts dialog, with search, a sort
 by name or by date modified, a star that keeps a layout at the top, and delete behind a
 confirmation. The sort and the stars are the viewer's, kept in the widget's `ChartStorage`. Each
-saved layout is listed by the market and interval its active chart showed when
+saved layout is listed by the market and timeframe its active chart showed when
 it was saved, or by its age where the store kept neither.
 
 Every row runs a command (`widget.layout.save`, `rename`, `load`, `open`, `delete`, `create`, `autosave`,
@@ -417,7 +416,7 @@ const adapter = memorySaveLoadAdapter()
 const controller = new AbortController()
 
 await adapter.layouts.list(controller.signal)
-await adapter.templates('study').list()
+await adapter.templates('indicator').list()
 const context = { version: 1, kind: 'symbol-global', symbol: 'ESZ2026' } as const
 await adapter.drawings(context).create(emptyDrawingDocument(context))
 
@@ -428,8 +427,9 @@ outcome.kind // 'not-found'
 
 An aborted call rejects with an error named `AbortError` and changes nothing.
 
-`memorySaveLoadAdapter` persists nothing. Use it for tests, server rendering and an intentionally
-ephemeral embed, and implement the same contract over your own backend for durable storage.
+`memorySaveLoadAdapter` keeps everything in memory for the life of the page. Use it for tests,
+server rendering and an intentionally ephemeral embed, and implement the same contract over your
+own backend for durable storage.
 
 ### The REST adapter and its wire contract
 
@@ -447,10 +447,11 @@ const restSaves = createRestSaveLoadAdapter({
 await restSaves.layouts.list()
 ```
 
-You supply two values and nothing else. `baseUrl` is where you mounted the routes, and `request` is
-how a request is made. Authorization, cookies, CORS, retries, timeouts and tenancy stay in your
-request function, because their consequences are yours: the adapter holds no credential, no token
-store, no header policy and no default origin, and it makes no request until you call a verb.
+You supply two values. `baseUrl` is where you mounted the routes, and `request` is how a request is
+made. Authorization, cookies, CORS, retries, timeouts and tenancy stay in your request function,
+because their consequences are yours: the adapter builds each request from `baseUrl` and hands it to
+your function, which adds the credentials and headers your service needs, and it makes a request
+only when you call a verb.
 
 Your service serves four collections under that base URL. Every path below is relative to it.
 
@@ -532,8 +533,8 @@ remain in step while the menu is open; transient tile maximize does not change t
 names.
 
 Growing a layout keeps every existing chart instance and initializes each new tile from pane 0's
-safe presentation: symbol, timeframe, style, studies and comparisons. Mutable study configuration
-is copied per tile; replay, session state and saved-chart identity are not copied.
+safe presentation: symbol, timeframe, style, indicators and comparisons. Mutable indicator
+configuration is copied per tile; replay, session state and saved-chart identity are not copied.
 
 `load` answers rather than rejecting. Five kinds, told apart without reading a message:
 
@@ -587,13 +588,13 @@ switch (opened.kind) {
 A load that a later load supersedes is `cancelled`, with no signal of your own involved, and only
 the later load binds. This includes a later load begun synchronously by a chart callback during
 application. A widget disposed while the store is still answering answers the same way. That is
-what keeps a slow answer for the chart a user has left from landing on the chart they are looking
+what keeps a slow answer for the chart a viewer has left from landing on the chart they are looking
 at.
 
 Where a body fails after part of it has been applied, the chart puts back the content it held. If
 that fails too the chart is holding neither, and it stops saving: `saveLoad.notSaving()` reports it,
 `save` answers `not-saving` and writes nothing, the built-in layouts menu says so on the toolbar and
-stands its Save and its autosave down, and the sentence for the trader arrives on `saveConflict`.
+stands its Save and its autosave down, and the sentence for the viewer arrives on `saveConflict`.
 
 Saving starts again when a load lands, and only then: a whole content out of the store, applied in
 full, under the resource it came from. `save(name, { asNew: true })` stays available throughout, and
@@ -623,7 +624,7 @@ Complete recovery requires every typed appearance leaf with a valid concrete col
 in combined mode, a drawings array. Separate-mode chart content does not need that array.
 
 Hydration and rollback do not emit `saveNeeded` for their own storage writes. An event already
-queued by a user edit is preserved. A late save result does not replace a newer load's binding;
+queued by a viewer's edit is preserved. A late save result does not replace a newer load's binding;
 the built-in commands announce a saved layout only while that result is still current.
 
 ### Drawings: combined or separate
@@ -676,18 +677,18 @@ tile.
 
 ### Templates
 
-`adapter.templates(kind)` is a store per kind: `'study'` for indicator settings, `'drawing'` for a
-drawing tool's look, and `'palette'` for chart appearance. A drawing template carries the `tool` it
-belongs to, because a trend-line template means nothing on a rectangle. Their content is opaque,
+`adapter.templates(kind)` is a store per kind: `'indicator'` for indicator settings, `'drawing'` for
+a drawing tool's look, and `'palette'` for chart appearance. A drawing template carries the `tool`
+it belongs to, because a trend-line template means nothing on a rectangle. Their content is opaque,
 like a chart's.
 
-### User settings
+### Viewer settings
 
 The widget keeps the viewer's flat preferences in a `ChartStorage`. Every key is an opaque string in
 the `quickcharts.` namespace, and every value is an opaque string; a store routes or scopes them and
-reads neither. The default is an in-memory store that lasts the page; supply your own to keep them
-per device or per account. A browser store is a few lines you write; it is not part of the package,
-because a device-local default is not a persistence architecture:
+treats both as opaque. The default is an in-memory store that lasts the page; supply your own to
+keep them per device or per viewer. A browser store is a few lines you write and own, so where
+preferences live stays your decision:
 
 ```ts
 import { memoryChartStorage, type ChartStorage } from '@trdrs/quickcharts'
@@ -710,7 +711,7 @@ live on the saved-resource adapter above, never here.
 A conflict means someone else wrote the same entity after the copy on screen was read. The chart
 never resolves that by overwriting. It reports the case with a sentence from its own catalog and the
 ref that stands now, and leaves the decision to you: reload and lose the local edit, save a copy
-under a new name, or show the user both.
+under a new name, or show the viewer both.
 
 Reach the report in two places. A verb you called answers a typed `conflict` outcome. A write the
 widget made for the viewer, through the built-in UI or its own drawing sync, arrives on the
@@ -863,7 +864,7 @@ widget.dispose() // teardown; every handle and subscription is inert afterwards
 The widget paints the main series and volume, applies live updates by the bar rules above, pages
 older history in as the viewer scrolls left (stopping at the feed's `noData`), persists the viewer's
 preferences through `ChartStorage`, runs configured indicator instances through the manifest
-pipeline, and mounts the drawing layer, the legend and the level menu.
+pipeline, and mounts the drawing layer, the legend and the context menu.
 
 When older main or comparison history extends the renderer's shared timeline, the chart retains
 the latest fractional logical window, spacing and permitted off-data padding. Its compensating
@@ -875,7 +876,7 @@ the maintenance span or either endpoint. Public range methods and built-in navig
 enter that same epoch, so every supported navigation door has the same precedence.
 
 `toolbarContainer` optionally supplies a separate element for the top toolbar, such as a space
-between a host's navigation and account controls. The widget appends one package-owned, themed
+between a host's navigation and its other controls. The widget appends one package-owned, themed
 child there; it never clears or styles the supplied element. The toolbar follows the widget's
 theme, language and active chart, and its child is removed at disposal. The toolbar's menus and
 dialogs open in the widget's layer on the document body, at viewport coordinates, so each menu
@@ -885,12 +886,13 @@ toolbar available in fullscreen. Without `toolbarContainer`, the toolbar sits ab
 part of the default composition. When horizontal space is limited, the toolbar scrolls without
 dropping controls from the keyboard order.
 
-`drawingToolbarContainer` supplies separate host space for a single drawing rail. The package
+`drawingToolbarContainer` supplies separate host space for a single drawing toolbar. The package
 fills that space's height with its own themed child, follows the active chart when a layout
-changes, and removes the child on disposal. An external rail leaves the full chart width for the
-canvas; without the option, each chart keeps its internal rail and reserved leading column.
-Drawing flyouts stay beside the external rail within the widget's bounds regardless of the active
-pane. Switching charts closes an open flyout before the rail targets the newly active chart.
+changes, and removes the child on disposal. An external drawing toolbar leaves the full chart width
+for the canvas; without the option, each chart keeps its internal drawing toolbar and reserved
+leading column. Drawing flyouts stay beside the external drawing toolbar within the widget's bounds
+regardless of the active pane. Switching charts closes an open flyout before the drawing toolbar
+targets the newly active chart.
 Include this container in the custom fullscreen target alongside the chart and top toolbar.
 
 ### Widget and chart
@@ -918,14 +920,277 @@ function drive(widget: ChartWidget): void {
 }
 ```
 
-### The seven chart styles
+### Chart styles
 
-`candles`, `hollow`, `bars`, `line`, `area`, `baseline`, `stepline`, listed in picker order as
-`CHART_STYLES`. A style switch is presentation: nothing refetches, and the loaded bars, indicators,
-drawings, comparisons, scale and visible range all survive it. Four of the seven are value-shaped
+`candles`, `hollow`, `bars`, `line`, `area`, `baseline`, `stepline`, listed as `CHART_STYLES`. A
+style switch is presentation: nothing refetches, and the loaded bars, indicators, drawings,
+comparisons, scale and visible range all survive it. Four of the seven are value-shaped
 (`valueShaped(style)`), which is the one predicate a host branches on when it renders open, high and
 low values of its own.
 
+By default a chart offers all seven styles, and the style picker groups them by family. `styles`
+names the styles you offer, in the order the picker lists them, and `style` must be one of them:
+
+```ts
+import { createChart, type ChartDatafeed } from '@trdrs/quickcharts'
+
+declare const datafeed: ChartDatafeed
+
+// Candles, line and area, in this order, opening on the line.
+createChart({ container, datafeed, styles: ['candles', 'line', 'area'], style: 'line' })
+
+// Every style and no picker: a control of your own runs the chart.style.<id> commands.
+createChart({ container, datafeed, ui: { topBar: { styles: false } } })
+
+// Candles and line, with no picker.
+createChart({ container, datafeed, styles: ['candles', 'line'], ui: { topBar: { styles: false } } })
+```
+
+A style you leave out has no `chart.style.<id>` command, so no menu, shortcut or host control
+reaches it, and `setStyle` ignores it. With one style offered the picker is not shown, since there
+is nothing to choose. `ui.topBar.styles: false` hides the picker on its own terms, so you can
+restrict the set, hide the picker, do both, or do neither. A saved layout, saved chart or stored
+preference that names a style you left out opens on the first style in `styles`, and the rest of it
+restores. An empty list, an id outside `CHART_STYLES`, a repeated id and a `style` outside the list
+are setup errors that `createChart` throws.
+
+### Offered timeframes
+
+By default a chart offers the 26 presets (`TIMEFRAME_PRESETS`) and lets the viewer compose custom
+timeframes. `timeframes` names the timeframe tokens you offer, presets or any other token the
+grammar reads, and `timeframe` must be one of them. The order you give does not matter: the picker
+lists each unit's group smallest first. `customTimeframes: false` keeps the presets and removes
+custom timeframes:
+
+```ts
+import { createChart, type ChartDatafeed } from '@trdrs/quickcharts'
+
+declare const datafeed: ChartDatafeed
+
+// Four timeframes, one of them beyond the presets, opening on five minutes.
+createChart({ container, datafeed, timeframes: ['2m', '5m', '1h', '1d'], timeframe: '5m' })
+
+// Every preset and no custom timeframes.
+createChart({ container, datafeed, customTimeframes: false })
+
+// Two timeframes and no picker: a control of your own runs the chart.timeframe.<token> commands.
+createChart({ container, datafeed, timeframes: ['1m', '5m'], ui: { topBar: { timeframes: false } } })
+```
+
+A preset you leave out has no `chart.timeframe.<token>` command, and `chart.timeframe.set` and
+`setTimeframe` ignore any token you leave out. The picker shows only what you list: a group with
+no listed token is not drawn, a listed token beyond the presets sits in its unit's group without a
+delete, and there is no custom-timeframe composer. The viewer's saved chips show where you list
+them. When you list none of them, the chips are your five smallest timeframes, and the viewer's
+stored chips stay stored for a chart that offers them. With one timeframe offered the picker is not
+shown. `ui.topBar.timeframes: false` hides the picker on its own terms. A range preset whose
+timeframe you leave out reads its span at your nearest coarser timeframe, or at your largest when
+none is coarser. Within what you offer, the feed's `resolutions` and the symbol's
+`supportedResolutions` still apply: a chip the feed or the symbol does not serve is disabled, and
+the picker's list leaves its row out.
+
+A saved layout, saved chart or stored preference that names a timeframe you left out opens on your
+smallest timeframe, and the rest of it restores. With `customTimeframes: false` a stored custom
+token opens on `1m`. An empty list, a token the grammar cannot read, a repeated token, a
+`timeframe` or `layout.charts[].timeframe` outside what you offer, and `customTimeframes: true`
+beside a list are setup errors that `createChart` throws. `customTimeframes` is the switch, and
+`preferences.customTimeframes` is the list of custom tokens a first-run viewer starts with.
+
+### Offered layouts
+
+By default a chart offers all 55 arrangements (`ARRANGEMENTS`) and lets the viewer change every
+sync switch. `layouts` names the arrangement codes you offer, and the layout opens on
+`layout.arrangement` or else on the first code you list. `layoutSync` names the sync switches the
+viewer may change:
+
+```ts
+import { createChart, type ChartDatafeed, type ChartSaveLoadAdapter } from '@trdrs/quickcharts'
+
+declare const datafeed: ChartDatafeed
+declare const saveLoad: ChartSaveLoadAdapter
+
+// A single chart: no layout setup menu, and no re-tile from any door.
+createChart({ container, datafeed, layouts: ['s'] })
+
+// One chart, two side by side or a 2x2 grid, with the crosshair always synced and symbol sync the
+// only switch the viewer changes.
+createChart({ container, datafeed, layouts: ['s', '2h', '4'], layoutSync: ['symbol'], layout: { sync: { crosshair: true } } })
+
+// Every arrangement, with the layout setup menu kept and the saved-layouts menu hidden.
+createChart({ container, datafeed, saveLoad, ui: { topBar: { savedLayouts: false } } })
+```
+
+The layout setup menu shows only the arrangements you list, in its own rows by chart count, and
+leaves out a row with none of them. An arrangement you leave out has no tile, and
+`widget.layout.setArrangement` and its command ignore it. With one arrangement offered there is
+nothing to choose, so the menu is not shown, unless that arrangement holds several charts and a
+sync switch is offered, in which case the menu holds the switches alone. A switch you leave out holds
+the value `layout.sync` gives it, or off: the menu does not show it, `widget.layout.setSync` and its
+command leave it as it is, and a saved layout cannot change it. An empty `layoutSync` fixes every
+switch.
+
+A saved layout whose arrangement you left out opens on the offered arrangement with the most charts
+not above the saved count, the first one listed winning a tie. When every offered arrangement holds
+more charts, it opens on the one with the fewest, and the extra panes clone the first chart as a
+re-tile does. The saved charts past the ones shown are not dropped. The layout carries them with the
+saved arrangement and its divider positions, and a save writes them back unchanged beside the shown
+charts as they are now: a host offering only `['s']` opens a saved 4-chart layout as one chart, and
+after it saves, a host offering every arrangement still opens all four. A re-tile is a new
+arrangement and ends the carry, as it tears down the charts it has no pane for. A saved active chart
+among the hidden ones leaves the first chart active, and the sync switches restore as saved, apart
+from those `layoutSync` leaves out. An empty `layouts`, an unknown or repeated code, a
+`layout.arrangement` outside the list, and an unknown or repeated sync switch are setup errors that
+`createChart` throws.
+
+`ui.topBar.layouts: false` hides the layout setup menu and the saved-layouts menu together;
+`ui.topBar.layoutSetup: false` and `ui.topBar.savedLayouts: false` hide one of them, and neither
+shows a menu `layouts: false` hid. The saved-layouts menu saves, opens and lists layouts, so it is
+shown only with a layouts store (`saveLoad.layouts`). Without one, its Download chart data row joins
+the image menu beside Download image and Copy image, the way an export menu offers a chart as a
+picture or as data.
+
+### Offered drawing tools
+
+By default a chart offers every drawing tool. `drawingTools` names the tools you offer, by the type
+`access.drawingTool` and the `tool.<type>` icon ids use: a type `drawingTools.all()` lists (from
+`@trdrs/quickcharts/drawings`), `zoom` or `eraser`. The order you give does not matter, because the
+drawing toolbar keeps its own groups and sections:
+
+```ts
+import { createChart, type ChartDatafeed } from '@trdrs/quickcharts'
+
+declare const datafeed: ChartDatafeed
+
+// Lines, levels and a ruler: no shapes, patterns, notes or glyphs.
+createChart({ container, datafeed, drawingTools: ['trend_line', 'horizontal_line', 'fib_retracement', 'measure'] })
+
+// A chart whose viewers keep and remove the drawings on it and make nothing new.
+createChart({ container, datafeed, drawingTools: ['eraser'] })
+```
+
+A tool you leave out is not drawn anywhere a tool is chosen: not in its group's flyout, not as a
+group's face, which wears the first tool the group offers, not on the favorites bar, and not on the
+drawing toolbar for `measure` and `zoom`. A section or group it empties goes with it. The glyph
+picker's kinds are the `emoji`, `sticker` and `icon` tools, so a kind you leave out has no tab, and
+leaving out all three removes the glyph group. Every door that would arm it refuses:
+`chart.drawings.arm` answers `denied`, and `armTool`, `placeImage` and an image pasted over the
+chart place nothing. A copy is a new drawing, so a drawing of a tool you leave out is not copied
+into another: `chart.drawings.clone` and `chart.drawings.paste` are unavailable for it, `clone` and
+`paste` make nothing, and a Control- or Command-drag moves the drawing instead of duplicating it.
+Copying it to the clipboard is not refused, so it pastes on a chart that offers its tool.
+
+Drawings of a tool you leave out that are already on the chart, from a saved chart or layout, a
+drawings document or another host, render and stay fully editable. They select, restyle through the
+selection's settings bar and the settings dialog, lock, hide and delete exactly as any drawing does:
+from the settings bar, the eraser, the remove menu and the Delete key. The eraser is always offered,
+listed or not, because it removes drawings rather than making them, which is why `['eraser']` is the
+way to offer no tool that creates one.
+
+The list composes with your access policy: a tool is offered when you list it and the policy permits
+it, and a listed tool the policy refuses is drawn as `access.refused` says (see Refused controls).
+Nothing stored is rewritten: a starred tool you leave out keeps its star and returns to the favorites
+bar on a chart that offers it, and a group's remembered face is kept the same way.
+`features.drawings: false` removes drawing altogether, whatever the list says. An empty list, a type
+that names no tool and a repeated type are setup errors that `createChart` throws.
+
+### Offered indicators
+
+By default a chart offers every built-in indicator. `builtInIndicators` names the built-ins you
+offer, by the definition id `access.indicator` receives: an id `BUILT_IN_INDICATORS` lists, such as
+`sma`. The order you give does not matter, because the indicator picker keeps its own:
+
+```ts
+import { BUILT_IN_INDICATORS, createChart, type ChartDatafeed } from '@trdrs/quickcharts'
+
+declare const datafeed: ChartDatafeed
+
+// Moving averages and RSI only.
+createChart({ container, datafeed, builtInIndicators: ['sma', 'ema', 'rsi'] })
+
+// A chart that opens with an indicator it offers.
+const sma = BUILT_IN_INDICATORS.find((definition) => definition.id === 'sma')!
+createChart({ container, datafeed, builtInIndicators: ['sma'], indicators: [{ id: 'sma-1', definition: sma }] })
+```
+
+A built-in you leave out is not listed in the indicator picker: not among the built-ins, not
+among the favorites, and not in search results. Every door that would add one refuses:
+`chart.indicators.add` (from the picker, the keyboard or your own control) answers `denied`,
+`indicators.add` adds nothing, `indicators.set` leaves out an instance of it the chart does not
+already hold, and a new pane that a re-tile adds copies the first chart's indicators without it. The
+chart has no verb that duplicates an indicator, so a second instance is an add like any other.
+
+Instances of a built-in you leave out that are already on the chart, from a saved chart or layout,
+an undo step or another host sharing the store, render and stay fully editable and removable. The
+settings dialog, `chart.indicators.update`, the legend's eye and remove control, remove all and
+`indicators.remove` work on them exactly as on any instance, and an edit that would move one onto
+another built-in you leave out keeps it as it stands. Nothing saved is rewritten because of the
+list: a starred built-in you leave out keeps its star and returns to the favorites on a chart that
+offers it.
+
+The list filters the built-ins alone. A definition of your own, whose `manifest.id` names no
+built-in, is never filtered, and neither is what your `indicatorPicker` source lists: its
+collections and rows are your content. The source is handed only the offered ids as `builtInIds`.
+The list composes with your access policy: a built-in is offered when you list it and the policy
+permits it, and a listed one the policy refuses is drawn as `access.refused` says (see Refused
+controls). A non-list, an empty list, an id that names no built-in, a repeated id and an
+`indicators` instance whose built-in you do not list are setup errors that `createChart` throws.
+
+### Offered ranges
+
+By default the bottom bar offers every range preset in `RANGE_PRESETS`, from `1D` to `All`.
+`ranges` names the presets you offer by their keys, in the order the bottom bar draws them:
+
+```ts
+import { createChart, type ChartDatafeed } from '@trdrs/quickcharts'
+
+declare const datafeed: ChartDatafeed
+
+// A day, a week's worth of sessions and a year, in this order.
+createChart({ container, datafeed, ranges: ['1D', '5D', '1Y'] })
+
+// No range buttons: the bottom bar keeps its clock, timezone picker and session view.
+createChart({ container, datafeed, ranges: [] })
+```
+
+A preset you leave out has no `chart.range.<key>` command, so no menu, shortcut or host control
+reaches it, `chart.range.set` ignores its key, and the bottom bar draws no button for it. An empty
+list offers none, which is how you keep the rest of the bottom bar without range buttons;
+`ui.bottomBar: false` removes the whole bar. `chart.range.set` still takes an explicit
+`{ from, to }` window either way. A preset whose timeframe your `timeframes` leave out reads its
+span at your nearest coarser timeframe, as it does without a list. A non-list, a key that names no
+preset and a repeated key are setup errors that `createChart` throws.
+
+### Offered timezones
+
+By default the timezone picker offers every zone in `TIMEZONES` and the exchange choice.
+`timezones` names the choices you offer: zone ids, and `exchange` (`EXCHANGE_TIMEZONE`) for the
+charted symbol's own zone. The picker keeps its own order (UTC, the exchange choice, then every
+zone by its current offset); the order you give decides only which choice comes first:
+
+```ts
+import { createChart, EXCHANGE_TIMEZONE, type ChartDatafeed } from '@trdrs/quickcharts'
+
+declare const datafeed: ChartDatafeed
+
+// The exchange's own time, New York or London, opening on the exchange's time for a first-run viewer.
+createChart({ container, datafeed, timezones: [EXCHANGE_TIMEZONE, 'America/New_York', 'Europe/London'] })
+
+// Always Tokyo time: no picker, and the clock reads Tokyo.
+createChart({ container, datafeed, timezones: ['Asia/Tokyo'] })
+```
+
+A choice you leave out has no `chart.timezone.<id>` command (`chart.timezone.exchange` for the
+exchange choice), `chart.timezone.set` and `setTimezone` ignore it, and the picker lists no row for
+it. With one choice offered the picker is not shown, since there is nothing to choose, and the
+bottom bar's clock still reads the time in that zone.
+
+A chart opens on the viewer's stored choice, else on `preferences.timezone`, when you list it, and
+otherwise on the first choice you list. A stored choice you leave out is not rewritten: it stays
+stored until the viewer picks another zone, so a chart that offers it again opens on it. The
+exported registry is not filtered: `TIMEZONES`, `isTimezoneChoice` and `timezoneListing` answer
+the full set for code of your own. A non-list, an empty list, an id that names no zone and a
+repeated id are setup errors that `createChart` throws.
+
 ### Events
 
 Typed maps, one per scope. Every subscription returns its unsubscribe and is inert after
@@ -981,7 +1246,9 @@ function toolbar(widget: ChartWidget): void {
 
 A command whose one id spans many subjects declares `refuses(arg)` beside `available()`: an
 argument your access policy turns away answers `denied` before availability is asked, which is how
-`chart.drawings.arm` refuses a tool. A refusal is a value, never a throw: `ok`, `unavailable`,
+`chart.drawings.arm` refuses a tool. `onChange` fires when the registered set or a shortcut changes,
+and when `widget.refreshAccess()` says your policy may answer differently. A refusal is a value,
+never a throw: `ok`, `unavailable`,
 `denied`, `unknown`, or `failed` with the
 error. Your own commands register through the same door: a chart extension's `contributeCommands`
 puts them in this list with `scope: 'chart'` and its own label text.
@@ -1005,10 +1272,10 @@ over it is absent. A control you hide in `ui` is the only thing that changes. Th
 Two presentation flags also close the one command whose only job is opening their dialog.
 `ui.symbolSearch: false` removes the search dialog and `chart.symbol.search`, while
 `chart.symbol.set` still changes the symbol. `ui.indicatorPicker: false` removes the indicator
-browser and `chart.indicators.open`, while `chart.indicators.add` still adds an indicator.
+picker and `chart.indicators.open`, while `chart.indicators.add` still adds an indicator.
 
-Neither plane is authorization. A hidden control's command still answers to `access`, and no flag
-supplies a capability the datafeed lacks: a feed with no search keeps every search door closed.
+Authorization belongs to `access`: a hidden control's command still answers to it, and a flag
+reaches only what the datafeed can do, so a feed with no search keeps every search door closed.
 
 ```ts
 import { createChart, createUdfDatafeed } from '@trdrs/quickcharts'
@@ -1028,6 +1295,99 @@ The library reads `features` and `ui` once, when the widget is created. A key or
 plane does not take throws a `TypeError` naming its path before anything mounts. The package's
 `dist/feature-manifest.json` lists every flag in its `features` and `ui` blocks.
 
+### Refused controls
+
+By default the chart's own controls draw what your access policy refuses disabled, which suits an
+offer the viewer can unlock. `access.refused: 'hide'` leaves it out instead, for a chart that simply
+does not offer it:
+
+```ts
+import { createChart, type ChartDatafeed } from '@trdrs/quickcharts'
+
+declare const datafeed: ChartDatafeed
+declare const session: { may(feature: string): boolean }
+
+createChart({
+  container,
+  datafeed,
+  access: {
+    refused: 'hide',
+    command: (id) => id !== 'chart.replay.start' || session.may('replay'),
+    drawingTool: (tool) => tool !== 'brush' && tool !== 'highlighter',
+    indicator: (id) => id !== 'vwap',
+  },
+})
+```
+
+With `'hide'`, a refused drawing tool is not in its group's flyout, on the favorites bar or in the
+glyph picker; a section, a group or a favorites bar it leaves empty goes with it, and a group's face
+that would wear a refused tool wears the first one the group still offers. A refused indicator is
+not in the indicator picker. A control or menu row whose command the policy refuses is not drawn
+(top bar, bottom bar, menus, the drawing toolbar and the selection's bar, the navigation cluster,
+the replay transport, legend row controls and the context menu), and a rule left with nothing beside
+it goes too. A picker always keeps its current choice: the chosen style, timeframe, timezone or
+scale is listed even when its command is refused.
+
+Only a refusal hides. A permitted command that cannot run now (nothing to undo, no bars loaded,
+nothing selected) is drawn disabled as before. The policy is asked whenever the chrome syncs (a
+change on the active chart, a change to the command registry) and whenever a menu or flyout opens,
+and `widget.refreshAccess()` asks it again at any moment (see A policy that changes), so a policy
+that follows your session moves the controls with it. Nothing stored is rewritten: a
+viewer's favorite keeps its star and returns to the favorites bar once you permit the tool again,
+and drawings and indicators already on the chart render exactly as they do under a refusal by
+default. The keyboard, `widget.commands` and the chart handles refuse exactly as they do with
+`'disable'`. A value other than `'disable'` or `'hide'` is a setup error that `createChart` throws.
+
+Under either value the policy refuses creating content, never what is already on the chart or in
+saved content: it refuses adding, never restoring. A saved chart, a layout load, an undo or a redo,
+a drawings document and shared drawing storage put back every indicator and drawing they carry,
+those the policy refuses included, so a load followed by a save never rewrites a viewer's content
+without them. An indicator whose definition `access.indicator` refuses, once on the chart (added
+before the policy changed, or put back by a restore), renders and stays fully editable and
+removable:
+`indicators.set`, `chart.indicators.update` and the settings dialog edit it, an edit of any other
+indicator keeps it, and an edit that would move it, or another indicator, onto a refused definition
+leaves that indicator as it stands. A new instance of a refused definition is still left out by
+every door. A drawing whose tool `access.drawingTool` refuses selects, restyles, locks, hides and
+deletes as any drawing does; a copy is a new drawing, so it is not cloned, pasted or duplicated by a
+Control- or Command-drag, while copying it to the clipboard is not refused.
+
+### A policy that changes
+
+The predicates are asked live: every door that runs a command, arms a tool or adds an indicator asks
+at that moment, so a refusal holds from the instant your policy answers it. The chart's own controls
+read the policy when they sync and when a menu opens. When its answers change and nothing on the
+chart does (a viewer's plan changed mid-session), call `widget.refreshAccess()`:
+
+```ts
+import { createChart, type ChartDatafeed } from '@trdrs/quickcharts'
+
+declare const datafeed: ChartDatafeed
+declare const session: { may(feature: string): boolean; onChange(listener: () => void): void }
+
+const widget = createChart({
+  container,
+  datafeed,
+  access: {
+    refused: 'hide',
+    command: (id) => id !== 'chart.replay.start' || session.may('replay'),
+    indicator: (id) => id !== 'vwap' || session.may('vwap'),
+  },
+})
+session.onChange(() => widget.refreshAccess())
+```
+
+Every surface that reads the policy reads it again at once: the top and bottom bars and their
+controls, the drawing toolbar's tools and groups, the favorites bar, the selection's bar, the
+navigation cluster, the replay transport and the legend's row controls, shown or left out as
+`access.refused` says and enabled or disabled. A menu, flyout or dialog that is open reads it too:
+the bars' menus, the context menu, the indicator picker and the saved layouts dialog rebuild their
+rows in place, and a drawing toolbar flyout (the glyph picker among them) or a selection bar panel
+opens again from its control, or closes when that control is now left out or disabled. Listeners of `widget.commands.onChange`
+hear it as well, so a control of your own can read `commands.available` again. Nothing stored
+changes, nothing on the chart changes, and no `saveNeeded` is raised: a refresh is a reading, never
+a write.
+
 ### Your own interface
 
 The widget supports three ways to present a chart, over the same behavior and the same commands.
@@ -1072,14 +1432,15 @@ The chart's own dialogs still open from their commands while its bars are hidden
 them in the widget's layer on the document, and `widget.layout.save` asks a layout that was never
 saved for its name. Hide a dialog in `ui` when your interface provides its own.
 
-The library does not export its internal components, replace its renderer, or take markup for its
-controls. The class names under the widget's root are private, apart from the styling hooks listed
+The library draws its own controls over its own renderer and keeps its internal components to
+itself. The class names under the widget's root are private, apart from the styling hooks listed
 under Theme.
 
 ### Fullscreen and image
 
-Chart-root fullscreen fills the screen with the widget's own element. It never takes over your
-application shell, which is a different thing from a fit-to-container layout your CSS owns.
+Chart-root fullscreen fills the screen with the widget's own element, or with the
+`fullscreen.target` you name; your application shell and any fit-to-container layout stay in your
+CSS.
 
 ```ts
 import { type ChartWidget } from '@trdrs/quickcharts'
@@ -1098,24 +1459,24 @@ async function shareable(widget: ChartWidget): Promise<void> {
 identity and the attribution you configured through `image`. Nothing is uploaded, shared or stored:
 you receive a blob and decide.
 
-### Indicator browser content
+### Indicator picker content
 
-The Indicators button and `commands.execute('chart.indicators.open')` open the same browser.
+The Indicators button and `commands.execute('chart.indicators.open')` open the same picker.
 Pass `{ collection: 'saved' }` as the command argument to open a declared host collection directly.
-An unknown collection falls back to the shipped catalog. Reopening an already open browser keeps its current selection and query.
+An unknown collection falls back to the shipped catalog. Reopening an already open picker keeps its current selection and query.
 It lists the 23 shipped definitions, with search and Favorites. Add creates a new instance on the
-currently active chart and keeps the browser open. Favorites use your `ChartStorage` port.
+currently active chart and keeps the picker open. Favorites use your `ChartStorage` port.
 
 Supply `ChartWidgetOptions.indicatorPicker` to include additional localized collections and rows
-in that browser. You supply data and opaque actions, not DOM, indicator definitions, or a renderer.
+in that picker. You supply data and opaque actions, not DOM, indicator definitions, or a renderer.
 Built-in annotations can add favorite state, counts and actions; they cannot replace a definition,
-its name, or Add. Without a source, the browser has only shipped built-ins and Favorites.
+its name, or Add. Without a source, the picker has only shipped built-ins and Favorites.
 
 ```ts
 import type { IndicatorPickerSource } from '@trdrs/quickcharts'
 
 const indicatorPicker: IndicatorPickerSource = {
-  collections: [{ id: 'saved', label: 'Saved studies' }],
+  collections: [{ id: 'saved', label: 'Saved indicators' }],
   async list({ collection, query, builtInIds }, signal) {
     if (signal.aborted) return { kind: 'unavailable', message: 'Content unavailable.' }
     return {
@@ -1134,8 +1495,10 @@ const indicatorPicker: IndicatorPickerSource = {
 }
 ```
 
-The source receives the collection, query and shipped definition ids. It owns filtering and any
-service limits; the browser does not promise an unlimited catalog or implement paging for you.
+The source receives the collection, query and the shipped definition ids the picker lists (only
+those `builtInIndicators` offers, when you name a list). Its own collections and rows are never
+filtered by that list. It owns filtering, paging and any
+service limits; the picker lists what it answers.
 Collection ids `builtin` and `favorites`, and action ids `add` and `favorite`, are reserved.
 Item ids cannot collide with shipped definition ids or these reserved ids. Duplicate ids,
 malformed rows and missing primary actions refuse the response; the shipped catalog remains usable.
@@ -1144,7 +1507,7 @@ name a localized navigation group and use `layout: 'list'` for name/secondary-ac
 An absent count stays blank. Omit `favorite` to omit that action on a contributed item.
 
 A favorite action receives the requested next boolean. Successful actions refresh the current
-collection unless they return `close: true`. Refusals and exceptions keep the browser open with
+collection unless they return `close: true`. Refusals and exceptions keep the picker open with
 plain text, never rendered markup. Icons reuse `ChartExtensionIcon`; invalid icons draw no glyph.
 The host localizes contributed labels and messages; the chart localizes its own controls.
 
@@ -1159,8 +1522,9 @@ chrome is painted from it and renders nothing without it.
 
 - **The top bar.** The symbol pill opens the symbol search for the active chart; the compare door
   opens it in compare mode. The timeframe picker shows the saved timeframes as chips and a list of
-  the 26 presets in five groups, each row savable as a chip, with a composer for a custom interval
-  under the unit's ceiling. The style picker lists the seven styles. Indicators opens the picker
+  the timeframes the chart offers (by default the 26 presets in five groups), each row savable as a
+  chip, with a composer for a custom timeframe under the unit's ceiling while custom timeframes are
+  offered. The style picker lists the styles the chart offers. Indicators opens the picker
   over the 23 built-in definitions, and the legend's gear opens the settings dialog for an instance
   (inputs, style, visibility). Bar replay enters and leaves replay for the active chart; entering
   asks where to begin rather than choosing a starting bar. Its starting-point menu answers with a
@@ -1168,19 +1532,20 @@ chrome is painted from it and renders nothing without it.
   date runs `chart.replay.startFirst`: the chart pages the feed's history back to its oldest bar,
   within the 20,000 bars one session holds, and starts there. Undo and
   redo step back and forward through the active chart's own content, and each names the change it
-  would move. Layout setup offers the 55
-  arrangements and the five sync switches; the saved-layouts menu saves, copies, renames, opens and
-  deletes layouts through `saveLoad.layouts` and marks unsaved changes, with an autosave switch.
+  would move. Layout setup offers the arrangements and sync switches the chart offers (by default
+  the 55 arrangements and the five sync switches); the saved-layouts menu, shown with a layouts
+  store, saves, copies, renames, opens and deletes layouts through `saveLoad.layouts` and marks
+  unsaved changes, with an autosave switch and Download chart data.
   Chart settings edits appearance, grid and session shading, the price-scale mode and the theme
   mode, and its Reset defaults row runs `chart.appearance.reset`, which drops the viewer's own
   appearance edits and returns the price scale to normal so the chart reads as the theme and your
   constructor options paint it. `ui: { topBar: { settings: { theme: false } } }` removes its Theme
   section and leaves the rest of the menu, for a host that offers the theme choice in its own
-  settings; the widget's theme API and theme commands are untouched. Fullscreen and the image menu (Download image, and Copy image where the browser can) close
-  the bar.
-- **The bottom bar.** The range presets, the clock in the display zone with the timezone list
-  (UTC and the exchange choice first), and the session view for a symbol that trades outside
-  regular hours.
+  settings; the widget's theme API and theme commands are untouched. Fullscreen and the image menu (Download image, Copy image where the browser can, and
+  Download chart data when there is no layouts store) close the bar.
+- **The bottom bar.** The range presets the chart offers, the clock in the display zone with the
+  list of the timezones it offers (UTC and the exchange choice first), and the session view for a
+  symbol that trades outside regular hours.
 - **Around the charts.** A navigation cluster (zoom, scroll, reset) sits at the bottom of each
   pane, and past one tile it carries a sixth control that fills the layout with the active tile or
   gives the layout back, over `widget.layout.toggleMaximize`, the same verb the Alt press on a tile
@@ -1193,7 +1558,7 @@ chrome is painted from it and renders nothing without it.
   replay entry can claim the row. Chart notices report a feed that cannot serve the symbol, an
   image that could not be copied, or a save the store refused.
 
-Undo and redo step through the chart's own content: the symbol, the interval, the style, the price
+Undo and redo step through the chart's own content: the symbol, the timeframe, the style, the price
 scale and whether it frames itself, the appearance a viewer authored, the comparisons, the
 indicators and the drawings. A step is one reading of that content, so a step back puts the whole
 reading back rather than reversing a single verb, and the two controls name the change they would
@@ -1273,7 +1638,8 @@ null when `ui: { topBar: false }` removes the bar, which is what to check before
 you would have nowhere to put.
 
 Every control acts through the command registry and reflects `commands.available`, so a command
-your access policy refuses renders disabled and does nothing. The saved-layouts menu runs the
+your access policy refuses renders disabled and does nothing, or is not drawn with
+`access.refused: 'hide'`. The saved-layouts menu runs the
 layout verbs `widget.layout.save`, `rename`, `load`, `open`, `delete`, `create` and `autosave`; what a
 verb did reports through the `layout` event and what it refused through `saveConflict`. Copy image
 reports through the `image` event (a refused copy falls back to a download). Each control has a flag
@@ -1298,7 +1664,9 @@ trimmed.on('saveNeeded', () => note('the layout has unsaved changes'))
 ```
 
 The search dialog's class chips come from your datafeed's `config().classes`, named through
-`search.classNames`; a class you do not name wears its token. `search.scope` names what your
+`search.classNames`; a class you do not name wears its token. `search.spreads`,
+`search.allClasses` and `search.classSelection` choose how the classes and the spread operators are
+offered, as "Classes and spread operators" under Search describes. `search.scope` names what your
 search is limited to at the far edge of that strip, with the mark its `mark` paints; your datafeed
 decides what is found. The range presets read your
 datafeed's optional `earliestBar(symbol)`: a preset deeper than the history you serve is disabled.
@@ -1329,8 +1697,8 @@ is a factory that returns a fresh `<svg>` element. An id you leave out keeps the
 as a `TypeError` when the widget is created.
 
 An id names what a glyph means, not one control. `settings` is the top bar's settings button, a
-study's gear in the legend and the drawing settings bar's gear, so one drawing stands in all three.
-Drawing tools take `tool.<type>`, chart styles `style.<style>` and layout arrangements
+indicator's gear in the legend and the drawing settings bar's gear, so one drawing stands in all
+three. Drawing tools take `tool.<type>`, chart styles `style.<style>` and layout arrangements
 `layout.<code>`, from the registries the rest of the API uses.
 
 ```ts
@@ -1380,15 +1748,16 @@ before costs that one glyph its artwork. The control draws the chart's own glyph
 
 `icons` covers the chart's own controls. The emoji, sticker and icon glyphs a drawing places come
 through the asset port, and a chart extension draws its rows and layers from the
-`ChartExtensionIcon` descriptors it contributes. The product's mark in the plot's corner is not an
-icon. `mountContextMenu`, `openSymbolSearch` and `mountSymbolSearch` take the same `icons` for a menu
-or search you mount without a widget.
+`ChartExtensionIcon` descriptors it contributes. The product's mark in the plot's corner is the
+chart's own artwork, outside `icons`. `mountContextMenu`, `openSymbolSearch`, `mountSymbolSearch`,
+`openTimeframePicker` and `mountTimeframePicker` take the same `icons` for a menu, search or picker
+you mount without a widget.
 
 ### Neutral marks
 
 Serve `marks` and `timescaleMarks` from your datafeed and the chart draws them. A mark is a note
 about a moment: its color is a semantic theme role rather than a literal, its words are yours, and
-the chart neither interprets nor acts on it.
+the chart draws it as given.
 
 ```ts
 import { type BarMark, type ChartDatafeed } from '@trdrs/quickcharts'
@@ -1426,13 +1795,13 @@ void withMarks
   display name, venue, timeframe, OHLC and change against the previous painted close. Prices use
   the symbol's formatter. Hover selects a bar; leaving restores the latest painted reading. Replay
   does not expose bars beyond its cursor. Missing metadata leaves the supplied symbol unchanged.
-  Legend and search use a decorative monogram; they do not fetch symbol logos or infer a provider.
-  Study and separate-pane comparison rows follow their renderer panes. Stable row controls retain
-  focus during value updates. Study values read the first plot, using declared precision or the
-  symbol formatter; Volume reads bar volume using resolved volume precision. The row-list toggle,
-  study eye and pane collapse are independent controls. Pane restore remembers study identity
-  across pane removal. The status control opens session details, retains an unknown-session state
-  and is hidden during replay. Price-scale chips use the same commands as `setScaleMode`.
+  Legend and search rows wear your `symbolMark`, or a decorative monogram without one.
+  Indicator and separate-pane comparison rows follow their renderer panes. Stable row controls
+  retain focus during value updates. Indicator values read the first plot, using declared precision
+  or the symbol formatter; Volume reads bar volume using resolved volume precision. The row-list
+  toggle, indicator eye and pane collapse are independent controls. Pane restore remembers indicator
+  identity across pane removal. The status control opens session details, retains an unknown-session
+  state and is hidden during replay. Price-scale chips use the same commands as `setScaleMode`.
 - **An interface language** (`locale`, English by default), one of the 21 the package ships.
   `BUILT_IN_LOCALES` lists them for a picker: each carries its stable code, its canonical BCP 47
   `tag`, its reading direction (`ar` and `he_IL` are `rtl`), and its endonym. The chart's own chrome
@@ -1524,9 +1893,9 @@ theme.resetCustom()
 stop()
 ```
 
-Switching modes keeps the symbol, timeframe, visible range, drawings and studies the chart already
-has. A palette you supply is a tint rather than a replacement: a role you do not name keeps its
-built-in value for that mode.
+Switching modes keeps the symbol, timeframe, visible range, drawings and indicators the chart
+already has. A palette you supply is a tint rather than a replacement: a role you do not name keeps
+its built-in value for that mode.
 
 ### Roles
 
@@ -1535,26 +1904,75 @@ inventory, and the built-in palettes and the generated stylesheet are built from
 property names are private, so a color, a size or a radius is always set through a role. The
 class names inside the stylesheet are private too, except the supported hooks below.
 
+### Motion
+
+Every duration, timing function and motion scale the chart uses is a role in the `motion` family,
+so you retune the chart's motion the way you retune its colors. Both built-in palettes carry the
+same values:
+
+| Role | Default | What it times |
+|---|---|---|
+| `motion.durationFast` | `90ms` | A state change under the pointer, such as a hover fill. |
+| `motion.durationBase` | `150ms` | A modal dialog and its backdrop opening and closing, and the replay row entering and leaving. |
+| `motion.durationModerate` | `250ms` | A control moving to its new state, such as a switch knob sliding. |
+| `motion.durationSlow` | `350ms` | A small mark settling, such as a disclosure caret turning or a checkbox filling. |
+| `motion.durationSlower` | `500ms` | A larger mark turning, such as the drawing toolbar's chevron. |
+| `motion.easingStandard` | `ease` | A modal dialog box, the replay row, a caret dip, a checkbox fill. |
+| `motion.easingOut` | `ease-out` | A modal backdrop fading, a switch knob sliding. |
+| `motion.easingLinear` | `linear` | A color or opacity change under the pointer. |
+| `motion.easingSpring` | `cubic-bezier(0.175, 0.885, 0.32, 1.275)` | A caret or chevron turning with a slight overshoot. |
+| `motion.scaleEnter` | `0.97` | The scale a modal dialog box grows from as it opens. |
+
+Every modal dialog the chart opens (the symbol search, chart settings, the indicator browser and
+indicator settings, the saved-layouts browser, the name and confirm prompts, go to date, and the
+drawing settings, image picker and template prompts) opens with its backdrop fading in over
+`motion.durationBase` on `motion.easingOut`, and its box fading in and growing from
+`motion.scaleEnter` to full size over `motion.durationBase` on `motion.easingStandard`. It closes
+with the same motion reversed. A closing dialog stops taking input and returns focus at once, and the
+chart removes it when the same `motion.durationBase` has elapsed, so a duration you set times both
+the transition and the removal. A dialog opened over another moves on its own and closes first, and
+a dialog the chart replaces or tears down goes at once.
+
+A duration takes a CSS duration such as `200ms` or `0.2s`; an easing takes any CSS timing function,
+such as `ease-in-out`, `steps(4)` or `cubic-bezier(0.2, 0, 0, 1)`; a scale takes a unitless factor
+such as `0.95`.
+
+```ts
+import { createThemeController, type CustomThemes } from '@trdrs/quickcharts'
+
+const calm: CustomThemes = {
+  light: { 'motion.durationBase': '200ms', 'motion.scaleEnter': '0.95' },
+  dark: { 'motion.durationBase': '200ms', 'motion.scaleEnter': '0.95' },
+}
+const theme = createThemeController({ mode: 'dark', custom: calm })
+note(theme.get()['motion.durationBase'])
+```
+
+When the reader's system asks for reduced motion (`prefers-reduced-motion: reduce`), the
+stylesheet resolves every duration role to `0ms` and marks those declarations `!important`, so a
+palette you supply cannot bring motion back: dialogs, menus and the replay row open and close at
+once.
+
 ### Cascade layers
 
 The stylesheet declares two cascade layers and puts everything it contains in them: the built-in
-palettes in `trdrs.tokens`, every recipe in `trdrs.chart`. Nothing in it is unlayered. It marks a
-declaration `!important` only where a later layer must not undo it: an element's `hidden`
-attribute, the shortened motion under a reduced-motion preference, and the missing focus ring of a
-search field, which shows its focus by its caret. Your first stylesheet must declare the complete
-order before any product stylesheet loads, because a layer's position is fixed by the first
-statement that names it:
+palettes in `quickcharts.tokens`, every recipe in `quickcharts.chart`. Nothing in it is unlayered.
+It marks a declaration `!important` only where a later layer or an inline palette must not undo it:
+an element's `hidden` attribute, the zero motion durations under a reduced-motion preference, and
+the missing focus ring of a search field, which shows its focus by its caret. Your first stylesheet
+must declare the complete order before any product stylesheet loads, because a layer's position is
+fixed by the first statement that names it:
 
 ```css
-@layer reset, trdrs.tokens, trdrs.chart, trdrs.platform, host;
+@layer reset, quickcharts.tokens, quickcharts.chart, host;
 ```
 
 Put your reset in `reset`. A reset left unlayered outranks every layered rule and strips the
 chart's controls of their borders and grounds. Put an intentional override of a supported hook in
-`host`, or leave it unlayered; either wins over the chart's recipe. A chart-only host declares only
-`reset`, the two chart layers and `host`; `trdrs.platform` is the layer a later product declares
-for itself. Inline styles the chart writes for measured geometry outrank any stylesheet rule, and
-a rule marked `!important` reverses layer order, so neither is a way to restyle the chart.
+`host`, or leave it unlayered; either wins over the chart's recipe. Layers of your own product go
+between `quickcharts.chart` and `host`. Inline styles the chart writes for measured geometry
+outrank any stylesheet rule, and a rule marked `!important` reverses layer order, so neither is a
+way to restyle the chart.
 
 ### Supported styling hooks
 
@@ -1566,9 +1984,9 @@ applying in any release. Removing a hook, a state or a customization is a breaki
 | Hook | Purpose | States | Customization |
 |---|---|---|---|
 | `.qc-topbar` | The top toolbar: symbol search, timeframe, chart style, indicators, layouts, replay and the widget menus. | | background-color, border, padding, gap, box-shadow |
-| `.qc-drawing-toolbar` | The drawing rail beside the plot. | `aria-orientation`: vertical beside the plot, horizontal in a host row. | background-color, border, padding, gap, box-shadow |
+| `.qc-drawing-toolbar` | The drawing toolbar beside the plot. | `aria-orientation`: vertical beside the plot, horizontal in a host row. | background-color, border, padding, gap, box-shadow |
 | `.qc-bottombar` | The bottom bar: range shortcuts, the session clock and the timezone. | | background-color, border, padding, gap, box-shadow |
-| `.qc-legend` | The legend over the plot: the symbol, its reading and each study row. | | background-color, border, border-radius, padding, box-shadow, inset |
+| `.qc-legend` | The legend over the plot: the symbol, its reading and each indicator row. | | background-color, border, border-radius, padding, box-shadow, inset |
 | `.qc-menu-panel` | A floating menu opened from a toolbar control. | `hidden`: present while the menu is closed. | background-color, border, border-radius, padding, box-shadow |
 | `.qc-dialog` | A modal dialog: settings, search, layouts and the drawing editors. | `data-role`: which dialog this is, in the chart's own vocabulary. | background-color, border, border-radius, padding, box-shadow, max-width |
 
@@ -1600,8 +2018,8 @@ problem. Configuration errors never reach a render.
 ### Theme and appearance are two ladders
 
 The theme palette is the broad brand surface. Chart appearance is the specific one: series colors,
-candle anatomy, grid visibility and study visuals in `ChartOverrides.appearance`. Where both could
-affect the same pixel, appearance wins.
+candle anatomy, grid visibility and indicator visuals in `ChartOverrides.appearance`. Where both
+could affect the same pixel, appearance wins.
 
 Theme palette precedence, lowest first:
 
@@ -1612,7 +2030,7 @@ Chart appearance precedence, lowest first:
 
 1. the built-in appearance for the selected mode;
 2. the constructor's `appearance` partial;
-3. restored user appearance;
+3. restored viewer appearance;
 4. runtime `chart.applyAppearance` patches.
 
 Resetting custom palettes returns the chart to the built-in mode and leaves saved chart appearance
@@ -1624,23 +2042,24 @@ opens in those colors on any theme.
 
 ## Compare
 
-Every chart can draw OTHER symbols beside its own. A compare is study-like: legend-managed, three
-placements, persisted in the chart content blob. `same-percent` shares the
-main price scale and flips it to percent while any such compare lives (the prior scale mode comes
-back when the last one leaves); `new-scale` binds the LEFT scale with absolute prices (the left
-axis exists only while such a compare does); `new-pane` takes a pane of its own. Compared bars
-clip to the main series window, so a compare never extends the time axis. `features.compareSymbols` supplies
-a curated quick-add list for the compare dialog; `compare.symbols()` reads it back.
+Compare draws OTHER symbols beside a chart's own. Each comparison is managed like an indicator:
+from the legend, at one of three placements, persisted in the chart content blob. `same-percent`
+shares the main price scale and flips it to percent while any such comparison lives (the prior
+scale mode comes back when the last one leaves); `new-scale` binds the LEFT scale with absolute
+prices (the left axis exists only while such a comparison does); `new-pane` takes a pane of its
+own. Compared bars clip to the main series window, so a comparison never extends the time axis.
+`features.compareSymbols` supplies a curated quick-add list for the compare dialog;
+`compare.symbols()` reads it back.
 
 The widget's standard Compare door lives in the top bar, and `ui: { topBar: { compare: false } }`
 hides it. The legend header does not duplicate that door. Commands and comparison-row actions remain
-available when the top-bar door is hidden, and `features: { compare: false }` removes comparing
-altogether. The built-in dialog's search rows add at any of the three placements, curated `compareSymbols` rows sit
-above results, and the ADDED section removes. Each compare takes a legend row whose title reopens
-the dialog in change-symbol mode (the pick re-keys the compare in place), with an eye and a remove
-beside the value (% under `same-percent`, the last close otherwise). In a layout, compares belong to
-each chart of their own (`widget.activeChart().compare`) and ride the layout blob with the rest of
-that chart's content.
+available when the top-bar door is hidden, and `features: { compare: false }` removes compare
+altogether. The built-in dialog's search rows add at any of the three placements, curated
+`compareSymbols` rows sit above results, and the ADDED section removes. Each comparison takes a
+legend row whose title reopens the dialog in change-symbol mode (the pick re-keys the comparison in
+place), with an eye and a remove beside the value (% under `same-percent`, the last close
+otherwise). In a layout, each chart holds its own comparisons (`widget.activeChart().compare`), and
+they ride the layout blob with the rest of that chart's content.
 
 ```ts
 import { createChart, createUdfDatafeed } from '@trdrs/quickcharts'
@@ -1656,15 +2075,15 @@ compare.add('CL', { placement: 'new-pane' })
 compare.setVisible('CL', false)
 const active = compare.list() // [{ symbol, placement, color, visible }]
 note(`NQ last: ${compare.latest('NQ') ?? '-'}`)
-compare.remove('NQ') // the scale mode the trader held comes back
+compare.remove('NQ') // the scale mode the viewer held comes back
 ```
 
 ## Timeframes
 
-A timeframe token names a bar interval: a count and a unit, `1m`, `4h`, `1d`, `3mo`, `500t`. The
-units are ticks (`t`), seconds (`s`), minutes (`m`), hours (`h`), days (`d`), weeks (`w`) and
-months (`mo`), and each unit has a ceiling (`TIMEFRAME_MAX`). A token outside the grammar parses
-as null, and the chart never asks a feed for it.
+A timeframe token names how much one bar spans: a count and a unit, `1m`, `4h`, `1d`, `3mo`, `500t`.
+The units are ticks (`t`), seconds (`s`), minutes (`m`), hours (`h`), days (`d`), weeks (`w`) and
+months (`mo`), and each unit has a ceiling (`TIMEFRAME_MAX`). A token outside the grammar parses as
+null, and the chart never asks a feed for it.
 
 ```ts
 import { formatTimeframe, isIntradayTimeframe, parseTimeframe, timeframeSeconds } from '@trdrs/quickcharts'
@@ -1772,7 +2191,7 @@ if (equity) {
 
 ## Ranges
 
-`RANGE_PRESETS` lists the nine range presets, each a visible span and the interval it reads best
+`RANGE_PRESETS` lists the nine range presets, each a visible span and the timeframe it reads best
 at: `1D` over one-minute bars through `All` over monthly bars. `rangeAvailable` withholds a preset
 deeper than the history a symbol has, and `frameRange` sets a pane's visible window for a span,
 anchored on the last real bar so a future whitespace horizon never frames as empty space. The
@@ -1800,7 +2219,7 @@ host's own search surface subscribes to the same state.
 The widget prefetches the default catalog and reuses completed pages across search, compare and
 change-symbol dialogs. Each opening owns its query, class filter and pending work. Closing it
 discards late results without clearing completed pages. Locale changes and widget disposal clear
-the widget cache. A replacement widget never inherits a previous provider's cache.
+the widget cache. A replacement widget starts with a cache of its own.
 
 Completed reuse holds at most 32 queries and 5,000 rows, evicting least-recent entries. Retained
 multi-page results reopen without a first-page refetch. Eviction does not truncate an active
@@ -1838,6 +2257,87 @@ isSymbolPair('BTC/USD') // true
 spreadExpression(' es - nq ') // 'ES-NQ'
 ```
 
+### Classes and spread operators
+
+The dialog offers your datafeed's `config().classes` as a strip of chips, an All chip first, one
+class selected at a time and sent to your feed as `cls`. Its field offers six spread operators
+behind a toggle, and a query that reads as an expression leads the list with the expression row.
+Three `search` options change that, and a chart that sets none of them searches exactly as above.
+
+- `spreads`: `false` offers no operator toggle, no operator and no expression row, and your feed
+  receives the query exactly as typed. `{ operators }` keeps spreads on and offers only the listed
+  operators (`SpreadOperatorId`: `division`, `subtraction`, `addition`, `multiplication`,
+  `exponentiation`, `reciprocal`), in the listed order. Default `true`. The compare dialog never
+  offers the operators.
+- `allClasses`: `false` offers no All chip. With one class at a time, the first class you declare
+  starts selected; with several, no selection means every class. `{ label }` writes the All chip
+  with your label. Default: the chip, with the catalog's label.
+- `classSelection`: `'multiple'` makes every chip a toggle, and the All chip clears the selection.
+  Your feed receives `classes` with every selected class in declared order, and `cls` too while
+  exactly one is selected, so a feed that reads only `cls` still narrows a single chip. Default
+  `'single'`.
+
+A `classes` entry is a class token, or a `SearchClassNode`, `{ id, children }`, whose children are
+narrower classes. Selecting such a class opens a second row of chips beneath the strip: its own
+all chip, written like the All chip, and one chip per child, named through `search.classNames`.
+Your feed always receives the most specific class selected: the child when one is picked, the
+class when none is. The dialog renders two levels; a child's own `children` are not offered, and
+the child narrows by its `id`. The second row is a labelled group of pressed buttons, reached by
+Tab after the strip, as the strip is.
+
+```ts
+import { createChart, type ChartDatafeed, type DatafeedConfig } from '@trdrs/quickcharts'
+
+declare const cryptoBase: ChartDatafeed
+
+// Spot markets by quote currency, beside perpetuals.
+const cryptoFeed: ChartDatafeed = {
+  ...cryptoBase,
+  async config(): Promise<DatafeedConfig> {
+    return { classes: [{ id: 'spot', children: ['usdc', 'usdt'] }, 'perp'] }
+  },
+  // `cls` is 'spot' while the whole class is selected, and 'usdc' once USDC is picked under it.
+  search: (query, options) => cryptoBase.search(query, options),
+}
+
+const crypto = createChart({
+  container,
+  datafeed: cryptoFeed,
+  search: {
+    classNames: { spot: 'Spot', usdc: 'USDC', usdt: 'USDT', perp: 'Perpetuals' },
+    allClasses: { label: 'Every market' },
+    spreads: { operators: ['division', 'subtraction'] },
+  },
+})
+void crypto
+```
+
+With several classes at once, read `classes` and fall back to `cls`:
+
+```ts
+import { createChart, type ChartDatafeed } from '@trdrs/quickcharts'
+
+declare const catalogFeed: ChartDatafeed
+
+const multiFeed: ChartDatafeed = {
+  ...catalogFeed,
+  async search(query, options = {}) {
+    // ['future', 'option'] with two chips selected; absent with none, which is every class.
+    const classes = options.classes ?? (options.cls ? [options.cls] : [])
+    return myBackend.search(query, classes, options.limit, options.offset)
+  },
+}
+
+const multi = createChart({
+  container,
+  datafeed: multiFeed,
+  search: { classSelection: 'multiple', allClasses: false, spreads: false },
+})
+void multi
+```
+
+`openSymbolSearch` and `mountSymbolSearch` take the same three options beside their `classes`.
+
 ### The picker, away from a chart
 
 A page that picks a market where no chart is mounted opens the same dialog the chart's symbol pill
@@ -1877,9 +2377,63 @@ card.dispose()
 catalog.dispose()
 ```
 
+### The timeframe picker, away from a chart
+
+A page that asks for a timeframe where no chart is mounted (a backtest's timeframe, an alert's
+timeframe) opens the list the chart's timeframe caret drops: the same unit groups, rows, labels and
+custom composer, built by the same code, so a timeframe reads there exactly as it reads on a chart.
+`openTimeframePicker` drops it from a control you own, which gets `aria-expanded` while it is open
+and focus back when it closes; `mountTimeframePicker` builds it bare into a box you own and
+position, as a card on a phone. Picking a row, or composing a custom timeframe, hands the token to
+`onPick`, because there is no chart here to set. The drop-down then closes; the card calls
+`onClose`, your cue to close its box.
+
+It takes what you already give a chart. `timeframe` is the value it opens on, checked and focused,
+and a custom value sits in its unit's group. `timeframes` and `customTimeframes` offer exactly what
+they offer a chart (see Offered timeframes), with the same setup errors, thrown before anything
+mounts, plus one for a `timeframe` the grammar cannot read. `resolutions` and
+`supportedResolutions` say what your feed and the symbol serve: as in the chart's list, a row they
+do not serve is left out, and the composer does not offer one. `theme`, `locale` (or a prepared
+`i18n`) and `icons` paint it as they paint a chart, on a theme root of its own, so the stylesheet
+reaches it outside any chart in either mode.
+
+It carries no saved chips and no stars, and keeps nothing: the chips are a chart's quick-select row,
+stored with the chart's preferences, and a field that asks for one timeframe has no row to put them
+in. A composed timeframe is handed back and not added to any list. The drop-down takes the keyboard
+as the chart's does (arrow keys, Home and End rove the rows; Escape and a press outside close
+it) and moves as every menu does.
+
+```ts
+import { mountTimeframePicker, openTimeframePicker } from '@trdrs/quickcharts'
+
+declare const timeframeField: HTMLButtonElement
+declare const timeframeBox: HTMLElement
+declare const backtest: { timeframe: string; setTimeframe(timeframe: string): void }
+
+timeframeField.addEventListener('click', () => {
+  const picker = openTimeframePicker({
+    anchor: timeframeField,
+    timeframe: backtest.timeframe,
+    resolutions: ['1m', '5m', '15m', '1h', '4h', '1d'], // what the feed serves
+    theme: { mode: 'light' },
+    onPick: (timeframe) => backtest.setTimeframe(timeframe),
+  })
+  void picker // picker.close() closes it from outside; Escape and a press outside close it too
+})
+
+const card = mountTimeframePicker({
+  container: timeframeBox,
+  timeframes: ['5m', '15m', '1h', '4h', '1d'],
+  timeframe: '1h',
+  onPick: (timeframe) => backtest.setTimeframe(timeframe),
+  onClose: () => timeframeBox.remove(),
+})
+card.focus()
+```
+
 ### The legend
 
-Every chart carries its own legend over its plot: an identity row naming the market, the interval
+Every chart carries its own legend over its plot: an identity row naming the market, the timeframe
 and the venue, and a values row carrying the hovered bar's O H L C and its move against the previous
 close. The numbers are written through that chart's own formatter, so a level in the legend is the
 level its price axis writes, and they follow the pointer while the crosshair is on the plot and the
@@ -1895,10 +2449,10 @@ The `size` is the chart's, not a suggestion: the box is already laid out, and pa
 you were given is what lines the marks up down a list. The chart ships no artwork and fetches none,
 so without this every mark is the neutral monogram it draws itself.
 
-`venueMark` and `providerMark` paint the source at the end of every symbol search and compare row
-the same way: the venue a market lists on, or the data provider where a row names no venue. Each
-receives the name the row writes (`exchange` or `provider`), the element and the size, and returns
-a disposer. Without them a source wears its initial on a neutral disc.
+`venueMark` and `dataSourceMark` paint the source at the end of every symbol search and compare
+row the same way: the venue a market lists on, or the data source where a row names no venue. Each
+receives the name the row writes (`exchange` or `dataSource`), the element and the size, and
+returns a disposer. Without them a source wears its initial on a neutral disc.
 
 ```ts
 import { createChart, createUdfDatafeed } from '@trdrs/quickcharts'
@@ -1942,7 +2496,7 @@ re-tile, a restore. Pointing your own surface at a chart moves no chart's symbol
 concepts stay separate: each chart keeps charting what it charts, and one of them is the one you are
 looking at.
 
-Five sync toggles fan changes across the charts: `symbol`, `interval` and `dateRange` replay a
+Five sync toggles fan changes across the charts: `symbol`, `timeframe` and `dateRange` replay a
 change onto every chart, `crosshair` mirrors continuously by time, and `time` centers every chart on
 a clicked moment. The whole layout serializes as ONE opaque content blob (arrangement, sync flags,
 durable chart-entity identities, active chart, every chart's own content), so a saved multi-chart
@@ -2019,19 +2573,21 @@ const saved = drawings?.export() // the persistence wire format (SerializedDrawi
 note(`${selected?.type ?? 'nothing'} selected, ${saved?.length ?? 0} drawings`)
 ```
 
-### The toolbar
+### The drawing toolbar
 
-The toolbar is the rail down the chart's leading edge. Its buttons are the cursor with its three
+The drawing toolbar runs down the chart's leading edge. Its buttons are the cursor with its three
 pointer modes and the eraser; seven tool groups, each opening a flyout of the group's sections
 with a star on every row that lands the tool on the favorites bar; Measure and Zoom; the magnet
 with its weak and strong strengths; stay in drawing mode; lock all; the eye that hides drawings,
 indicators, or both; drawing sync, shown only in a layout of more than one chart; the remove menu,
 which names what each row takes and carries the locked-item policy; and the favorites star. Each
 group button wears the tool it last armed, and every action is a `chart.drawings.*` command
-through the registry: a control renders disabled, never hidden, while the registry would not run
-its command (a tool or verb your access policy refuses, a selection verb with nothing selected,
-the Image tool without an asset port), and a command the policy refuses answers `denied` from the
-toolbar as from anywhere else, including `chart.drawings.arm` for a refused tool. An image is
+through the registry: a control renders disabled while the registry would not run its command (a
+tool or verb your access policy refuses, a selection verb with nothing selected, the Image tool
+without an asset port), and with `access.refused: 'hide'` a tool or verb the policy refuses is left
+out instead (see Refused controls), and a command the policy refuses answers `denied` from the
+toolbar as from anywhere else, including `chart.drawings.arm` for a refused tool. A tool your
+`drawingTools` list leaves out is not on the toolbar at all (see Offered drawing tools). An image is
 placed through `chart.drawings.placeImage`, from the picker or a system-clipboard paste over the
 chart. Every flyout, palette and dialog a surface opens sits inside the chart root and closes with
 it, and the eye and lock all announce their state through a live region. Lock all also makes Paste
@@ -2048,7 +2604,7 @@ chosen.
 Selecting a drawing shows the settings bar: templates, the stroke color with its opacity, the
 background for tools that have one, the text color and font size for text tools, thickness and
 line style, the settings gear, lock, delete, and a More menu with the stacking moves, the
-per-interval visibility presets, clone, copy and hide. Every edit persists at once and becomes the
+per-timeframe visibility presets, clone, copy and hide. Every edit persists at once and becomes the
 tool's default for the next drawing of that type. The settings dialog opens from the gear with
 Inputs, Style, Text, Table, Coordinates and Visibility pages as the tool has them; its edits apply
 live, Cancel restores the drawing, and Ok commits the session as one edit.
@@ -2057,7 +2613,7 @@ Text-bearing tools open an inline editor where the text sits, in the drawing's o
 placement committed empty is removed; an existing note committed empty is blanked. Ctrl or Cmd
 with Enter commits, Escape cancels, and a press on the chart commits.
 
-Templates are named setups a trader saves from either surface and applies on demand. They and
+Templates are named setups a viewer saves from either surface and applies on demand. They and
 the remembered defaults ride `ChartSaveLoadAdapter.templates('drawing')`, so a host that keeps
 saved charts on a server keeps these there too. Same-tool default changes are written in issue
 order, and a delayed read or failed write does not replace the newest local choice. Store work is
@@ -2085,20 +2641,25 @@ layer.armTool('rectangle')
 layer.destroy()
 ```
 
+A layer you mount yourself arms whatever you arm. Its `copies` option answers whether a new drawing
+may be made as a copy of a drawing of a type: return false for a tool you do not offer, and clone,
+paste and a Control- or Command-drag duplicate make nothing for its drawings, `canPaste` answers
+false, and the drag moves the drawing itself.
+
 ### `@trdrs/quickcharts/drawings`
 
 Everything about drawings a host builds its own UI from is one subpath. A host that never draws
 never imports any of it.
 
 ```ts
-import { buildRailGroups, drawingTools, parseDrawingsStore, restoreDrawings, serializeDrawingsStore } from '@trdrs/quickcharts/drawings'
+import { buildDrawingToolbarGroups, drawingTools, parseDrawingsStore, restoreDrawings, serializeDrawingsStore } from '@trdrs/quickcharts/drawings'
 
 // The catalog: 90 tools in 14 categories, read-only.
 const trendLine = drawingTools.get('trend_line')
 const fibs = drawingTools.byCategory('fibonacci')
 
-// The rail's own structure, as data: seven groups, their sections, and a catalog key per heading.
-for (const group of buildRailGroups()) {
+// The drawing toolbar as data: seven groups, their sections, and a catalog key per heading.
+for (const group of buildDrawingToolbarGroups()) {
   for (const section of group.sections) note(`${group.id}/${section.label}: ${section.tools.length}`)
 }
 
@@ -2108,10 +2669,10 @@ const drawings = restoreDrawings(store['ES'] ?? [])
 localStorage.setItem('acme.chart.drawings', serializeDrawingsStore(store))
 ```
 
-The subpath carries the workflow models too: what the rail's eye blanks (`HideMode`, which reaches
-chart-owned drawings and indicators and nothing else), the cursor modes and the two transient
-tools, the magnet policy over `magnetSnap`, the remove menu, favorites over a `FavoritesPort`, the
-standing preference record, and per-tool defaults and named templates over
+The subpath carries the workflow models too: what the drawing toolbar's eye blanks (`HideMode`,
+which reaches chart-owned drawings and indicators and nothing else), the cursor modes and the two
+transient tools, the magnet policy over `magnetSnap`, the remove menu, favorites over a
+`FavoritesPort`, the standing preference record, and per-tool defaults and named templates over
 `ChartSaveLoadAdapter.templates('drawing')`. Each is a pure function or a plain record, so a host
 builds its own controls without reimplementing the decisions behind them.
 
@@ -2119,7 +2680,7 @@ What a lock refuses is the library's own. A host locks and unlocks through the d
 reads what they answer: `chart.drawings.lock` holds one drawing where it stands,
 `chart.drawings.lockAll` suspends the whole chart, and every editing command answers `ok` or
 `unavailable` for the state the chart is actually in, so a control built on those outcomes says
-exactly what the chart will accept. The gesture list below is what a trader meets.
+exactly what the chart will accept. The gesture list below is what a viewer meets.
 
 ```ts
 import { blanks, chooseHideMode, DEFAULT_HIDE_STATE, DrawingTemplates } from '@trdrs/quickcharts/drawings'
@@ -2154,9 +2715,9 @@ note(IMAGE_ACCEPT)
 
 What to know:
 
-- **The subpath is a subset, not a re-export.** The drawing classes, the model store and the
-  mutable registry stay inside the library. There is no door for a host-authored tool: tool
-  contribution belongs to the access-policy plane, not to a bare registration call.
+- **The subpath is a deliberate subset.** The drawing classes, the model store and the
+  mutable registry stay inside the library. A host chooses among the catalog's tools through
+  `drawingTools` and the access policy.
 - **Every tool places.** Fixed-anchor tools place by press-drag-release or click then click; an
   instant tool (the position tools) lands whole from one press; a multipoint tool adds a point per
   click until a double-click ends the run; a freehand tool captures the drag as a stroke; a
@@ -2177,13 +2738,13 @@ What to know:
   so anchors never drift apart); grab an anchor handle to reshape; hold Shift to constrain a
   two-point placement or an anchor drag to 45 degree rays; Ctrl-drag duplicates; the magnet pulls
   a placed or dragged anchor onto the bar's own open, high, low or close; a locked drawing
-  selects, takes the Delete and Clone a trader asks for by name, and refuses a move, a resize, a
+  selects, takes the Delete and Clone a viewer asks for by name, and refuses a move, a resize, a
   text edit, the eraser and a Ctrl-drag copy; lock all suspends every edit, Delete and Clone
   included, until it is released.
 
 ## Extensions
 
-An extension is host code that draws on the chart, adds rows to its level menu, offers commands,
+An extension is host code that draws on the chart, adds rows to its context menu, offers commands,
 and stores viewer state in the chart's own save blob. The chart attaches it at mount, pushes its
 changes at it, and takes it down at teardown, along with everything it drew.
 
@@ -2237,9 +2798,9 @@ What to know:
   layer on the document body, painted with the widget's theme: a menu or an editor mounted there at
   viewport coordinates stands over every pane and over whatever the page stacks around the widget,
   which the pane's own overlay cannot promise. `ctx.symbolTitle()` is the name symbology gives the
-  charted market, the name the legend and the level menu print; `ctx.chart.symbol()` stays the
+  charted market, the name the legend and the context menu print; `ctx.chart.symbol()` stays the
   ticker an action is sent for. `ctx.painters` carries the mark painters you supplied as `.symbol`,
-  `.venue` and `.provider`, so a surface that names a market paints it with the same mark the
+  `.venue` and `.dataSource`, so a surface that names a market paints it with the same mark the
   legend and the search rows wear rather than shipping artwork of its own; a painter you did not
   supply is `null`, and the surface writes the name alone.
 - **A contributed row may bring its own glyph.** `ChartExtensionMenuItem.icon` is a
@@ -2254,19 +2815,20 @@ What to know:
   default), an action on the price the pointer landed on, placed under Copy price and Paste; or
   `view`, a switch over what the chart shows, placed under the remove rows. Rows keep the order
   they were contributed in within their group.
-- **A drawn layer can join the rail's eye.** `ctx.contributeHideLayer({ id, label, icon, apply })`
-  lists the layer in the eye's menu after the chart's own drawings and indicators and before
-  "Hide all", which blanks it with them. `label` carries the row's wording in both states, `icon`
-  the two marks the eye wears while the layer is its subject, and `apply(hidden)` is called with
-  the current state at contribution and on every change. The handle reads `hidden()`, flips
-  `setHidden()` through the same eye the rail drives, and `remove()` withdraws the layer.
+- **A drawn layer can join the drawing toolbar's eye.**
+  `ctx.contributeHideLayer({ id, label, icon, apply })` lists the layer in the eye's menu after the
+  chart's own drawings and indicators and before "Hide all", which blanks it with them. `label`
+  carries the row's wording in both states, `icon` the two marks the eye wears while the layer is
+  its subject, and `apply(hidden)` is called with the current state at contribution and on every
+  change. The handle reads `hidden()`, flips `setHidden()` through the same eye the drawing toolbar
+  drives, and `remove()` withdraws the layer.
 - **A printed chord is a real binding.** `ChartExtensionMenuItem.shortcut` prints on the row and
   answers to the key. The chart's dispatcher offers a press no built-in verb claims to the rows your
-  provider contributes for the level under the pointer and runs that row's own `run`, the same call
-  the click makes. The press acts on the tile the pointer is inside, active or not; outside every
-  tile, on a point with no readable level, while the viewer is typing, or while a modal holds the
-  keyboard, the key is left to your page. A row your provider withholds claims no key, and a row
-  carries one chord.
+  `contributeContextMenu` callback returns for the level under the pointer and runs that row's own
+  `run`, the same call the click makes. The press acts on the tile the pointer is inside, active or
+  not; outside every tile, on a point with no readable level, while the viewer is typing, or while
+  a modal holds the keyboard, the key is left to your page. A row your callback withholds claims no
+  key, and a row carries one chord.
 - **A glyph is bounded, and a refusal is free.** Up to 8 shapes, each up to 2048 characters of path
   data with every number in it finite, and an `outline` stroke width above 0 and up to 8. A shape
   outside that is dropped and the rest of the glyph still draws; a descriptor outside it draws
@@ -2289,7 +2851,7 @@ What to know:
   re-attaches it on every switch, so a market-scoped overlay cannot carry one market's drawing onto
   another's bars.
 - **A failing extension is its own problem.** A throw in `attach` drops that extension and the
-  chart still mounts; a throw in a subscriber, a menu provider, a command or a teardown is
+  chart still mounts; a throw in a subscriber, a menu builder, a command or a teardown is
   contained.
 - **Layouts attach per chart.** A widget hands its shared options to every chart it tiles, so each
   chart gets its own attachment, its own context and its own state slot.
@@ -2317,7 +2879,7 @@ Every claim in this document maps to a test or a generated artifact in the packa
   and the tarball, and the third-party notices are held by the boundary tests and
   `THIRD-PARTY-NOTICES.md`.
 
-## Versioning & deprecation
+## Versioning
 
 - **SemVer, enforced at the gate.** The public surface is pinned by an API-surface test (every
   exported name and its runtime kind), the shipped type declarations are compiled against by a
@@ -2329,8 +2891,8 @@ Every claim in this document maps to a test or a generated artifact in the packa
   and fields (`config` and `serverTime` are the pattern): an existing
   implementation keeps compiling, and the widget treats absence as "unconstrained / not supported".
   Your integration never breaks by standing still within a major.
-- **Deprecation runs a full major.** A deprecated export keeps working for the remainder of the
-  current major, is marked `@deprecated` in the types with its replacement named in the note (your
-  editor flags every call site), and is removed only in the next major, never silently.
+- **A major version may rename or remove public names.** Its upgrading guide in
+  [CHANGELOG.md](CHANGELOG.md) lists each one, old to new, with how saved state carries over: what
+  the previous major saved still opens, and the next save writes the current names.
 - **The wire timeframe grammar is stable vocabulary.** `<N><unit>` with units `t s m h d w mo`.
   Extensions may add units; an existing token never changes meaning.