@trdrs/quickcharts 1.2.0 → 1.3.0

package/README.md

@@ -918,14 +918,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
+interval 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
+rail 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
+rail 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 browser 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 a study 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 browser: 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 browser, 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 studies 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 interval 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 +1244,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.
@@ -1028,6 +1293,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 browser. 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 level 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
+study keeps it, and an edit that would move it, or another study, onto a refused definition leaves
+that study 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 level menu, the indicator browser 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.
@@ -1134,7 +1492,9 @@ const indicatorPicker: IndicatorPickerSource = {
 }
 ```
 
-The source receives the collection, query and shipped definition ids. It owns filtering and any
+The source receives the collection, query and the shipped definition ids the browser lists (only
+those `builtInIndicators` offers, when you name a list). Its own collections and rows are never
+filtered by that list. It owns filtering and any
 service limits; the browser does not promise an unlimited catalog or implement paging for you.
 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,
@@ -1159,8 +1519,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 interval 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 +1529,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
@@ -1273,7 +1635,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 +1661,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.
@@ -1381,8 +1746,8 @@ 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.
+icon. `mountContextMenu`, `openSymbolSearch`, `mountSymbolSearch`, `openTimeframePicker` and
+`mountTimeframePicker` take the same `icons` for a menu, search or picker you mount without a widget.
 
 ### Neutral marks
 
@@ -1535,15 +1900,61 @@ 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 rail'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. |
+
+A modal dialog, such as the symbol search or chart settings, 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 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:
+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;
@@ -1838,6 +2249,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,6 +2369,60 @@ card.dispose()
 catalog.dispose()
 ```
 
+### The timeframe picker, away from a chart
+
+A page that asks for an interval where no chart is mounted (a backtest's timeframe, an alert's
+interval) opens the list the chart's timeframe caret drops: the same unit groups, rows, labels and
+custom composer, built by the same code, so an interval 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 interval 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 intervalField: HTMLButtonElement
+declare const intervalBox: HTMLElement
+declare const backtest: { timeframe: string; setTimeframe(timeframe: string): void }
+
+intervalField.addEventListener('click', () => {
+  const picker = openTimeframePicker({
+    anchor: intervalField,
+    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: intervalBox,
+  timeframes: ['5m', '15m', '1h', '4h', '1d'],
+  timeframe: '1h',
+  onPick: (timeframe) => backtest.setTimeframe(timeframe),
+  onClose: () => intervalBox.remove(),
+})
+card.focus()
+```
+
 ### The legend
 
 Every chart carries its own legend over its plot: an identity row naming the market, the interval
@@ -2028,10 +2574,12 @@ with its weak and strong strengths; stay in drawing mode; lock all; the eye that
 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
@@ -2085,6 +2633,11 @@ 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