@trdrs/quickcharts 1.3.0 → 2.0.1

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
@@ -982,7 +984,7 @@ delete, and there is no custom-timeframe composer. The viewer's saved chips show
 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
+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.
@@ -1052,7 +1054,7 @@ picture or as data.
 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:
+drawing toolbar keeps its own groups and sections:
 
 ```ts
 import { createChart, type ChartDatafeed } from '@trdrs/quickcharts'
@@ -1068,14 +1070,14 @@ 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.
+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
@@ -1095,7 +1097,7 @@ that names no tool and a repeated type are setup errors that `createChart` throw
 
 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:
+`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'
@@ -1105,16 +1107,16 @@ 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.
+// 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 browser: not among the built-ins, not
+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 browser, the keyboard or your own control) answers `denied`,
+`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 studies without it. The
+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,
@@ -1154,7 +1156,7 @@ A preset you leave out has no `chart.range.<key>` command, so no menu, shortcut
 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
+`{ 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.
 
@@ -1270,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'
@@ -1320,11 +1322,11 @@ createChart({
 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
+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 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.
+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
@@ -1344,11 +1346,11 @@ without them. An indicator whose definition `access.indicator` refuses, once on
 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.
+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
 
@@ -1379,7 +1381,7 @@ Every surface that reads the policy reads it again at once: the top and bottom b
 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
+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
@@ -1430,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'
@@ -1456,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 {
@@ -1492,10 +1495,10 @@ const indicatorPicker: IndicatorPickerSource = {
 }
 ```
 
-The source receives the collection, query and the shipped definition ids the browser lists (only
+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 and any
-service limits; the browser does not promise an unlimited catalog or implement paging for you.
+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.
@@ -1504,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.
 
@@ -1520,7 +1523,7 @@ 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 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
+  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
@@ -1555,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
@@ -1694,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
@@ -1745,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`, `mountSymbolSearch`, `openTimeframePicker` and
-`mountTimeframePicker` take the same `icons` for a menu, search or picker 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'
@@ -1791,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
@@ -1889,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
 
@@ -1912,19 +1916,22 @@ same values:
 | `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.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. |
 
-A modal dialog, such as the symbol search or chart settings, opens with its backdrop fading in over
+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.
+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
@@ -1949,23 +1956,23 @@ 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 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:
+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
 
@@ -1977,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 |
 
@@ -2011,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:
 
@@ -2023,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
@@ -2035,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'
@@ -2067,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'
@@ -2183,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
@@ -2211,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
@@ -2371,9 +2379,9 @@ 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.
+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
@@ -2390,7 +2398,7 @@ do not serve is left out, and the composer does not offer one. `theme`, `locale`
 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
+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.
@@ -2398,13 +2406,13 @@ it) and moves as every menu does.
 ```ts
 import { mountTimeframePicker, openTimeframePicker } from '@trdrs/quickcharts'
 
-declare const intervalField: HTMLButtonElement
-declare const intervalBox: HTMLElement
+declare const timeframeField: HTMLButtonElement
+declare const timeframeBox: HTMLElement
 declare const backtest: { timeframe: string; setTimeframe(timeframe: string): void }
 
-intervalField.addEventListener('click', () => {
+timeframeField.addEventListener('click', () => {
   const picker = openTimeframePicker({
-    anchor: intervalField,
+    anchor: timeframeField,
     timeframe: backtest.timeframe,
     resolutions: ['1m', '5m', '15m', '1h', '4h', '1d'], // what the feed serves
     theme: { mode: 'light' },
@@ -2414,18 +2422,18 @@ intervalField.addEventListener('click', () => {
 })
 
 const card = mountTimeframePicker({
-  container: intervalBox,
+  container: timeframeBox,
   timeframes: ['5m', '15m', '1h', '4h', '1d'],
   timeframe: '1h',
   onPick: (timeframe) => backtest.setTimeframe(timeframe),
-  onClose: () => intervalBox.remove(),
+  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
@@ -2441,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'
@@ -2488,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
@@ -2565,9 +2573,9 @@ 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,
@@ -2596,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.
@@ -2605,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
@@ -2644,14 +2652,14 @@ Everything about drawings a host builds its own UI from is one subpath. A host t
 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}`)
 }
 
@@ -2661,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.
 
@@ -2672,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'
@@ -2707,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
@@ -2730,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.
 
@@ -2790,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
@@ -2807,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
@@ -2842,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.
@@ -2870,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
@@ -2882,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.