@trdrs/quickcharts 2.4.0 → 4.0.0

package/README.md

@@ -1627,7 +1627,13 @@ chrome is painted from it and renders nothing without it.
   asks where to begin rather than choosing a starting bar. Its starting-point menu answers with a
   bar picked on the plot, a date, the first available date, or a random bar. The first available
   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
+  within the 20,000 bars one session holds, and starts there. A date opens Select date over the
+  undimmed chart, carried by its title: a date field, on an intraday chart a time field whose clock
+  lists the day in quarter hours, a calendar of the loaded window whose heading turns to the months
+  and the years, and a chip that moves the choice to the first available day. Picking moves the
+  choice and the dialog stays up; Select starts replay at the first bar at or after the date and
+  time, in UTC, and Cancel leaves replay asking where to start. The arrows walk the days, Page Up
+  and Page Down turn the month, Enter picks and Escape closes. 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 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
@@ -1743,9 +1749,9 @@ reports through the `image` event (a refused copy falls back to a download). Eac
 in `ui`; hiding one removes the control and leaves its commands.
 
 ```ts
-import { createChart, createUdfDatafeed } from '@trdrs/quickcharts'
+import { createChart, createUdfDatafeed, type ChartDatafeed } from '@trdrs/quickcharts'
 
-declare const portfolio: { name: string } | null
+declare const portfolio: { name: string; search: ChartDatafeed['search'] } | null
 
 const trimmed = createChart({
   container,
@@ -1753,7 +1759,7 @@ const trimmed = createChart({
   ui: { navigation: false, topBar: { layouts: false, image: false } },
   search: {
     classNames: { future: 'Futures', crypto: 'Crypto' },
-    scope: () => (portfolio ? { label: portfolio.name } : null),
+    scope: () => (portfolio ? { label: portfolio.name, search: portfolio.search } : null),
   },
   preferences: { savedTimeframes: ['1m', '15m', '1h', '1d'], layoutAutosave: true },
 })
@@ -1763,9 +1769,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.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
+offered, as "Classes and spread operators" under Search describes. `search.scope` offers a part of
+the catalog the viewer can limit the search to, as a chip at the far edge of that strip, as "A
+search scope" under Search describes. The range presets read your
 datafeed's optional `earliestBar(symbol)`: a preset deeper than the history you serve is disabled.
 
 ```ts
@@ -2019,6 +2025,60 @@ 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.
 
+### The built-in palettes
+
+The two built-in palettes paint every dialog, menu and popover the chart opens from these roles,
+among the others `THEME_ROLES` lists:
+
+| Role | Light | Dark | What it paints |
+|---|---|---|---|
+| `overlay.surface` | `#ffffff` | `#1f1f1f` | The ground of a dialog, menu or popover. |
+| `overlay.separator` | `#ebebeb` | `#4a4a4a` | The rule under a dialog header and over its footer, and between menu groups. |
+| `overlay.scrim` | `rgba(156, 156, 156, 0.5)` | `rgba(0, 0, 0, 0.5)` | The veil behind a modal dialog. |
+| `text.primary` | `#0f0f0f` | `#dbdbdb` | The ink of rows, labels and values. |
+| `text.muted` | `#6a6a6a` | `#9b9b9b` | A section title, a hint, a placeholder. |
+| `chrome.caret` | `#707070` | `#8c8c8c` | The chevron of a select and the arrow that opens a flyout. |
+| `text.link` | `#2962ff` | `#5b9cf6` | A text link. |
+| `state.hover` | `#f2f2f2` | `#2e2e2e` | The fill under the pointer. |
+| `state.pressed` | `#ebebeb` | `#3d3d3d` | The fill while the pointer is down. |
+| `control.outline` | `#2e2e2e` | `#ffffff` | The edge and the words of an outlined button at rest, such as a dialog's Cancel. |
+| `control.onInk` | `#ffffff` | `#000000` | A mark cut from the emphasis fill: a chosen thickness, line style or line end. |
+| `control.neutral` | `#f2f2f2` | `#2e2e2e` | The quiet fill: a dialog's shortcut chip, the band over a calendar's columns, a chosen month or year. |
+| `control.neutralHover` | `#ebebeb` | `#3d3d3d` | The quiet fill under the pointer. |
+| `control.neutralPressed` | `#dbdbdb` | `#4a4a4a` | The quiet fill while the pointer is down. |
+| `control.neutralInk` | `#000000` | `#ffffff` | The words on the quiet fill, and what a quiet control's words and mark brighten to under the pointer, such as a calendar's day. |
+| `status.positive` | `#078671` | `#089981` | A gain or a success. |
+| `status.negative` | `#df323f` | `#f34452` | A loss or a failure. |
+| `status.warning` | `#ac6600` | `#ff9800` | A condition to notice before acting. |
+
+Every ink is held to the WCAG 2.2 AA ratio on each ground it is drawn over, so the light status
+inks are the darkest steps of their hues that still read at 4.5 to 1 on white, the dark red reads at
+4.5 to 1 on the dialog ground, and the muted ink reads at 4.5 to 1 over the hover and selected fills
+of a menu row and over the quiet fill. `drawing.line` is `#2962ff` in both modes; `drawing.selected`,
+the ring of a selected drawing's handles, is `#2962ff` light and `#1e53e5` dark, around a center of
+`drawing.handle`, the chart's own ground.
+
+### Fields
+
+Every text field, select, number field and color well the chart draws in its dialogs and settings
+is one box: 34px tall, a 1px edge with an 8px corner around a clear ground, and its words at 14 on
+18, 8px in from the edge. A select ends in an 18px chevron in `chrome.caret`. Five roles in the
+`control` family paint the box, and the focus ring is `state.focusRing`:
+
+| Role | Light | Dark | What it paints |
+|---|---|---|---|
+| `control.fieldEdge` | `#dbdbdb` | `#575757` | The edge of a field at rest. |
+| `control.fieldEdgeHover` | `#a8a8a8` | `#707070` | The edge of a field under the pointer. |
+| `control.selectEdgeHover` | `#a8a8a8` | `#808080` | The edge of a list button under the pointer, such as a select on a drawing's settings page. |
+| `control.fieldInvalid` | `#f23645` | `#f23645` | The edge and the focus ring of a field holding a value it refuses. |
+| `control.fieldFill` | `#f2f2f2` | `#2e2e2e` | The ground of a field that is read-only or disabled. |
+
+Focus draws a 2px ring over the edge, the edge itself and the pixel inside it, so the ring follows
+the corner and a dialog that scrolls never clips it. Only a value the chart refuses turns the edge
+`control.fieldInvalid`; a number past its bounds or off its step is clamped or rounded, so its
+field never turns red. The symbol search field draws its own outline in
+`chrome.fieldBorder`.
+
 ### Motion
 
 Every duration, timing function and motion scale the chart uses is a role in the `motion` family,
@@ -2032,21 +2092,25 @@ same values:
 | `motion.durationModerate` | `250ms` | A control moving to its new state, such as a switch knob sliding. |
 | `motion.durationSlow` | `350ms` | A small mark settling, such as a disclosure caret turning or a checkbox filling. |
 | `motion.durationSlower` | `500ms` | A larger mark turning, such as the drawing toolbar's chevron. |
+| `motion.durationGlide` | `100ms` | A mark gliding to a new place, such as a dialog's tab bar or an opacity knob. |
 | `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.easingInOut` | `ease-in-out` | A dialog's tab bar sliding to the page shown. |
 | `motion.scaleEnter` | `0.97` | The scale a modal dialog box grows from as it opens. |
 
 Every modal dialog the chart opens (the symbol search, chart settings, the indicator browser and
-indicator settings, the saved-layouts browser, the name and confirm prompts, go to date, and the
-drawing settings, image picker and template prompts) opens with its backdrop fading in over
+indicator settings, the saved-layouts browser, the name and confirm prompts, and the drawing image
+picker and template prompts) opens with its backdrop fading in over
 `motion.durationBase` on `motion.easingOut`, and its box fading in and growing from
 `motion.scaleEnter` to full size over `motion.durationBase` on `motion.easingStandard`. It closes
 with the same motion reversed. A closing dialog stops taking input and returns focus at once, and the
 chart removes it when the same `motion.durationBase` has elapsed, so a duration you set times both
 the transition and the removal. A dialog opened over another moves on its own and closes first, and
-a dialog the chart replaces or tears down goes at once.
+a dialog the chart replaces or tears down goes at once. The drawing settings dialog and the replay
+date picker work on the chart they stand over, so they open in place: they appear and leave at once,
+and their backdrop dims nothing while still taking the press that closes them.
 
 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
@@ -2074,7 +2138,8 @@ The stylesheet declares two cascade layers and puts everything it contains in th
 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
+the focus outline a field leaves off, because a field shows its focus on its own box: the ring over
+its edge, or the caret in a search field. 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:
 
@@ -2453,6 +2518,75 @@ void multi
 
 `openSymbolSearch` and `mountSymbolSearch` take the same three options beside their `classes`.
 
+### A search scope
+
+`search.scope` offers a part of the catalog the viewer can limit the search to: a portfolio, a
+watchlist, or any other set of symbols you can search within. The symbol search shows it as a chip
+at the far edge of the class strip, wearing the scope's mark and label, and the chip is on each time
+the dialog opens unless the scope says `on: false`. `scope` is read each time the dialog opens, so
+it follows what your page has selected; null offers no chip.
+
+While the chip is on, the dialog searches with the scope's `search`, which the chart's search
+controller asks exactly as it asks your datafeed's: the query after the debounce, the selected
+classes as `cls` or `classes`, a page at a time through `limit` and `offset`, and a newer question
+retiring an older one's answer. Answer with a page, as your datafeed does. A dialog that opens with
+the chip on asks the scope at once, and the scope's completed pages are reused while the dialog is
+open and go when it closes: the widget's catalog cache holds your datafeed's pages alone. The list
+leads with the scope's `recents`, or with none when the scope keeps none. While the chip is off,
+the dialog searches your datafeed and leads with the chart's recents.
+
+Pressing the chip asks the other source the query and classes the dialog holds, and an answer that
+arrives for the state the viewer left is dropped. A pick is recorded in `search.recents` either way,
+and in the scope's `recents` too while the chip is on. The compare dialog, adding a comparison or
+changing one, offers no scope and searches your datafeed.
+
+| Field | What it is |
+|---|---|
+| `label` | The scope's name, written on the chip. |
+| `mark` | Paints the scope's mark into the chart's 18px box at the chip's leading edge, and returns what takes it down. Absent, the chip wears the label's initial. |
+| `search` | Searches within the scope, called as your datafeed's `search` is. Required. |
+| `recents` | The recent picks the list leads with while the chip is on, and where a pick made then is recorded too. Absent, the list leads with none. |
+| `on` | Whether the chip is on when the dialog opens. Default `true`. |
+
+The chip is a toggle button in the strip's tab order, after the class chips. `aria-pressed` says
+whether the search is limited, and its accessible name says what a press does: "Limit search to"
+and the scope's label, in the viewer's language.
+
+```ts
+import { createChart, createUdfDatafeed, memoryRecents, type SearchScope } from '@trdrs/quickcharts'
+
+declare const watchlist: { id: string; name: string; logo: string } | null
+
+const watchlistRecents = memoryRecents()
+
+const scoped = createChart({
+  container,
+  datafeed: createUdfDatafeed({ baseUrl: 'https://feed.example.com/udf' }),
+  search: {
+    scope: (): SearchScope | null => {
+      if (!watchlist) return null
+      const { id, name, logo } = watchlist
+      return {
+        label: name,
+        mark: ({ host, size }) => {
+          const image = document.createElement('img')
+          image.src = logo
+          image.alt = ''
+          image.width = size
+          image.height = size
+          host.append(image)
+          return () => image.remove()
+        },
+        // Asked as your datafeed is: the query, `cls` or `classes`, `limit` and `offset`.
+        search: (query, options) => myBackend.searchWatchlist(id, query, options),
+        recents: watchlistRecents,
+      }
+    },
+  },
+})
+void scoped
+```
+
 ### 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
@@ -2682,7 +2816,7 @@ re-tile opens in the current one.
 
 ## Drawings
 
-The widget ships with a complete drawing product, on by default: every one of the 90 tools places
+The widget ships with a complete drawing product, on by default: every one of the 89 tools places
 from the toolbar, the selected drawing gets a floating settings bar and a settings dialog, tool
 defaults and named templates ride the adapter's template family, and a symbol's drawings persist
 through the adapter's drawings family. Turn the whole layer off with `features.drawings: false`,
@@ -2757,11 +2891,164 @@ line style, the settings gear, lock, delete, and a More menu with the stacking m
 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.
-
-Text-bearing tools open an inline editor where the text sits, in the drawing's own type. A fresh
-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.
+live, Cancel restores the drawing, and Ok commits the session as one edit. Its header carries the
+drawing's name, the tool's own until the viewer renames it with the pencil beside it; the name is
+`DrawingOptions.name`, saved with the drawing, and Cancel restores it with the rest. A page shown
+puts the keyboard in its first field, and the dialog keeps its top edge where it opened as pages of
+other sizes come and go. Its lists hang under the controls that open them, past the dialog's edge
+where they need to. The Template menu saves the current setup under a name, applies a saved one,
+or applies the tool's defaults: its own look and setup, put on the drawing at once, with its words
+kept.
+
+A color in the dialog opens its popover under the button that holds it: the offered colors, the
+colors the viewer added with the plus after them, and the opacity, and for a stroke its thickness
+and line style. Every choice applies at once and the popover stays up for the next one; Escape
+returns to the button. The plus opens a custom color editor that takes a hex of three or six digits
+or a pick on its saturation and brightness area and hue strip. A color added there joins the
+viewer's own, newest first, kept with the drawing preferences in `ChartStorage`, and the settings
+bar's palette offers them too.
+
+The line tools' Style page carries the stroke with its two ends, the extensions, the middle point,
+the price labels and, under Info, the stats a line reads (price range, percent change, the change
+counted in the symbol's smallest price move, bars, date and time range, angle), where they stand
+(left, center, right, or auto, which keeps them inside the pane), and whether they show always or
+only while the line is selected. A horizontal line offers its price label, a vertical line its time
+label, a cross line both. A rectangle offers its extensions, its border, a middle line with a stroke
+of its own and its background; every other shape its border and background; a curve its stroke and
+ends, its extensions along the tangents it ends on, and its background. A background switched off
+keeps its color and opacity for when it is switched back on. The Text page sets the words' color,
+size, weight and slant on one line over the words, and where the tool places them, where they stand:
+above, on or below a line, above, inside or below a box, along it from left to right, and for a
+vertical line whether they read across it or run up it. `NO_COORDINATES_TAB` names the tools whose
+points are drawn rather than typed, and `PRICE_ONLY_COORDS` the levels that span every bar.
+
+A retracement, a trend-based extension and a fib channel lay their levels out two to a line, each
+level its switch, its value and its color, under the thickness and style every level line is drawn
+in. The one color recolors every level at once, and shows the color the levels share or a split
+well while they differ. The bands between levels fill at `backgroundOpacity` while
+`fillBackground` holds them; `coeffsAsPercents` reads a level's ratio as a percent, and
+`labelsHAlign` and `labelsVAlign` stand the labels before, at the middle of or after the levels,
+above, on or below each line. A retracement and an extension draw their trend line through the
+swing points in a stroke of its own (`trendLine`, `trendLineColor`, `trendLineWidth`,
+`trendLineStyle`), stand each level's own words where `showText`, `textHAlign` and
+`textVAlign` put them, and with `levelsOnLogScale` divide the swing by log price while the price
+scale is logarithmic, which `Viewport.logScale` reports.
+
+A time zone, a trend-based time, fib circles, speed resistance arcs, a fib wedge and a pitchfan
+stand their levels one to a line, each level its switch, its value and its own stroke: a level's
+`width` and `style` draw it apart from the drawing's own. A time zone and a trend-based time label
+their lines where `labelsHAlign` and `labelsVAlign` put them along and across the pane; a circle
+fib reads its ratios as percents with `coeffsAsPercents`; an arc fib closes its arcs into circles
+with `fullCircles`; the trend-based time, the circles, the arcs and the wedge draw a trend line in a
+stroke of its own, and a pitchfan its median (`medianColor`, `medianWidth`, `medianStyle`). A
+speed resistance fan and a gann box divide their box on `priceLevels` across it and `timeLevels`
+down it, each side's labels switched on their own; a fan draws a grid at the divisions in a stroke
+of its own, and a gann box shades its price and time bands on their own switches and draws its
+angles corner to corner in `anglesColor`. `reverse` counts a box's divisions from the other
+corner.
+
+A pitchfork stands its line pairs one to a line the same way, each pair its switch, its value and
+its own stroke, under its median's stroke (`medianColor`, `medianWidth`, `medianStyle`) and over
+the bands between pairs, each in its outer pair's color at `backgroundOpacity` while
+`fillBackground` is on. `extendLines` runs every line back past the fork's start, and `variant`
+switches its construction in place: `original`, `schiff`, `modified_schiff` or `inside`.
+A fib spiral winds clockwise out from its first point, and `counterclockwise` winds it the other
+way.
+
+A gann square and a gann square fixed draw a grid of six lines at their fifths (`levels`), fan
+lines from the corner they count from out to their far sides (`fans`) and arcs about that corner
+(`arcs`), each line its switch, its color and its width, a fan line or an arc at its ratio of the
+square's unit, `x` along the time side for `y` along the price side. Their pages set each set
+under its section, two to a line; the bands between arcs follow `fillBackground` and
+`backgroundOpacity`, and `reverse` counts from the other corner. A gann square holds its second
+corner at `scaleRatio` price for every bar between its corners, a ratio it takes from the pane
+when it is first drawn so it opens square, and typing a Price/bar ratio moves the corner to it; with
+`showLabels` it reads its price and bar ranges and their ratio under it. A square fixed stays
+square on the pane whatever its scale. A gann fan draws its rays at their price-to-time ratios, 1/8
+to 8/1, each in its own stroke, with the bands between them and each ray's ratio at its end.
+
+A regression trend fits its line through the `source` of the bars between its points: a bar's
+open, high, low, close or volume, or one of the averages `hl2`, `hlc3`, `ohlc4` and `hlcc4`
+(`BAR_PRICE_SOURCES`). Its bands stand `upperDeviation` and `lowerDeviation` standard deviations
+from it, the lower counted down, each shown by `useUpper` and `useLower`; the line and each band
+switch and stroke on their own (`baseLine`, `upLine`, `downLine` with their colors, widths and
+styles), `extendLines` runs them to the pane's edges, and `showPearsons` reads the correlation
+under them.
+
+A parallel channel draws its levels at ratios of its width, 0 its baseline and 1 the parallel through
+its third point, each level its switch, its value and its own stroke, over its body between 0 and 1.
+A flat top/bottom and a disjoint channel end their sides as `leftEnd` and `rightEnd` set and read
+each side's prices at its ends with `showPrices`, in `pricesColor`, `pricesFontSize`,
+`pricesBold` and `pricesItalic`. A channel's `fillBackground` switches its body, and its words
+stand above it, inside it or below it with `textVAlign`, at its start, middle or end with
+`textHAlign`. A parallel channel's Coordinates page writes its third point as the price its
+parallel stands from the baseline.
+
+A sector shades the two halves of its slice, parted by the ray through its arc's middle, in `color1`
+and `color2` while `fillBackground` is on. A bars pattern paints its captured bars as `mode` says:
+`hl` their high-low ranges, `oc` their open-close ranges, or a line through each bar's close, open,
+high, low or `hl2`. A ghost feed's average candle span is held as a price and written on its page in
+the symbol's minimum ticks.
+
+An anchored VWAP weighs the `source` of every bar since its point by the bar's volume, and stands
+its bands off the average by `bandMultipliers` standard deviations or, with `bandsMode`
+`percent`, percents of it, each band calculated while its `bandsOn` switch is on. A volume profile
+reads its rows' volumes beside them with `showValues` and its point of control and shown value
+area bounds on the price scale with `showLabelsOnPriceScale`. A range meter reads the stats its
+switches choose in a label of its own color, size and background.
+
+A text's box switches its background (`fillBackground`) and its border (`drawBorder`, in the
+drawing's stroke color) on their own, and with `wordWrap` its words wrap at `wordWrapWidth` pixels;
+a callout's words wrap the same way inside a border at the drawing's width. A note ties a label to
+the point it notes: its first point is that point, its second the label's, with a line between them
+in the drawing's stroke color and the label's border in `borderColor`; a pin's words stand in a box
+of the same kind under its marker. A price note runs a line from its price to a tag that reads it,
+the tag in a text style and colors of its own (`labelTextColor`, `labelFontSize`, `labelBold`,
+`labelItalic`, `labelBackgroundColor`, `labelBorderColor`), its words along the line where
+`textVAlign` and `textHAlign` stand them. A signpost stands on its bar's high, or its low for a
+plate below the bar, its plate `position` percent of the pane's height away, so the plate keeps its
+height over the bar as the price scale moves; with `showImage` the plate leads with its `emoji`,
+and its words read in white or black, whichever reads on the plate. A table stands its cells' words
+at their left, middle or right with `textHAlign`, its border and grid in the drawing's stroke color.
+
+A brush fills the area its stroke closes back to its start while `fillBackground` is on, and a brush
+and a path head their ends with arrows as `leftEnd` and `rightEnd` say, a path with an arrow at its
+last point at first. A highlighter's width is in pixels, 8 to 96 on its page. The emoji and the
+sticker have no settings beyond their visibility: a glyph's size is set by its grips on the chart. An
+icon's page sets its tint, and an image's page chooses its picture from a
+box that names the formats and the size the intake takes, and sets how see-through it is drawn.
+
+The pattern tools are read by their letters and carry no words of their own: their Style page sets
+the letters' color, size, weight and slant on a Label row, then the border and, for the patterns
+that shade their legs, the background, which `fillBackground` switches off and on keeping its
+color. A three drives pattern stands on seven points, its reversal after the third drive the last.
+
+An Elliott wave count writes its labels in its wave's color, as its `degree` writes them: the
+fifteen degrees from `supermillennium` to `minuscule` (`ELLIOTT_DEGREES`) stand in five threes,
+each three ringed, in parentheses and bare, in roman numerals or figures and in capitals or small
+letters. `showWave` switches the wave through its pivots, and the labels stand without it.
+
+The text, the comment, the note, the signpost, the callout and the pin type their words on the
+chart. The drawing paints the words as they are typed, with their caret, selection and
+placeholder, while a field nobody sees, laid exactly over them in their own type and line height,
+takes the keys: the session's `inline` (`TextInlineEdit`) says where the words stand
+(`TextEditFrame`) and hears what the field holds (`TextDraft`). Enter and Shift with Enter break
+the line; Escape, Ctrl or Cmd with Enter, and a press elsewhere commit the words exactly as typed,
+the drawing still selected after Escape. A click on the words of the selected drawing types again,
+and a double-click opens its settings. A text, a comment, a note or a signpost left without words
+stays while it is selected and goes once it is not; a callout left without words goes as its edit
+ends; a pin keeps its place without words. `AttachDrawingsOptions.placeholder` names the words an
+empty drawing shows and `AttachDrawingsOptions.inks` the chart's own inks (`DrawingInks`).
+
+A table types into the cell a click on the selected table lands in, Tab moving on to the next cell
+and from the last to the first. Its floating bar and the chart's menu over it add a column right of
+the cell last typed in and a row below it, or at the table's ends where no cell is, and the menu
+removes that cell's row and column (`chart.drawings.tableRemoveRow`,
+`chart.drawings.tableRemoveColumn`). A hovered grid line resizes its column or row, and the corners
+scale the table. The price label, the price note, the arrow marks, the arrow marker and the flag
+open no editor: their words, where they have any, are set in their settings, which a double-click
+opens. Any other text-bearing tool types in a box of its own: Ctrl or Cmd with Enter commits,
+Escape cancels, and a press on the chart commits.
 
 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
@@ -2776,7 +3063,9 @@ adapter they last the page.
 
 The image and glyph tools reach your host through `ChartWidgetOptions.assets`. `intakeImage`
 turns a picked file into a payload within the caps and answers a refusal as a code the chart
-resolves through its own catalog; `glyphSource` answers the artwork URL an emoji or sticker draws
+resolves through its own catalog. The payload's `dataUrl` is always a PNG or a JPEG, whatever the
+picked file was, so a saved chart opens everywhere: decode a WEBP and re-encode it on a canvas, as a
+PNG where it has transparency and a JPEG otherwise; `glyphSource` answers the artwork URL an emoji or sticker draws
 with, or null to draw the glyph as text. Emoji artwork from Twemoji is bundled and works without
 an asset port or external requests. Omit `glyphSource` to use it. It is a chunk of its own, which
 the chart imports the first time it draws an emoji, so a chart that never shows one never loads
@@ -2793,6 +3082,8 @@ layer.armTool('rectangle')
 layer.destroy()
 ```
 
+A layer you mount yourself is told the symbol's grid, formatter and currency through `setTick`,
+`setPriceFormatter` and `setCurrency`; a position offers its risk as an amount in that currency.
 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
@@ -2806,7 +3097,7 @@ never imports any of it.
 ```ts
 import { buildDrawingToolbarGroups, drawingTools, parseDrawingsStore, restoreDrawings, serializeDrawingsStore } from '@trdrs/quickcharts/drawings'
 
-// The catalog: 90 tools in 14 categories, read-only.
+// The catalog: 89 tools in 14 categories, read-only.
 const trendLine = drawingTools.get('trend_line')
 const fibs = drawingTools.byCategory('fibonacci')
 
@@ -2846,8 +3137,9 @@ const preset = await templates.defaultFor('trend_line')
 ```
 
 Image-backed and glyph tools reach the host through one explicit asset port. The library owns the
-rules (JPG or PNG, 2 MB, a 2000 px longest edge, downscaled rather than refused) and names each
-refusal with a code that resolves through the chart's own catalog; the host owns the bytes.
+rules (a JPG, a PNG or a WEBP, stored as a PNG or a JPEG, 2 MB, a 2000 px longest edge, downscaled
+rather than refused) and names each refusal with a code that resolves through the chart's own
+catalog; the host owns the bytes.
 
 ```ts
 import { checkImageFile, fittedSize, IMAGE_ACCEPT, type DrawingAssetPort } from '@trdrs/quickcharts/drawings'
@@ -2857,7 +3149,8 @@ const assets: DrawingAssetPort = {
     const bad = checkImageFile(file)
     if (bad) return { ok: false, ...bad }
     const { width, height } = fittedSize(1200, 900)
-    return { ok: true, asset: { dataUrl: await myBackend.read(file), width, height, downscaled: false } }
+    // A PNG or a JPEG whatever the picked file was: a WEBP is re-encoded before it is stored.
+    return { ok: true, asset: { dataUrl: await myBackend.pngOrJpeg(file), width, height, downscaled: false } }
   },
   // Optional: glyphSource replaces the bundled emoji artwork.
   // glyphSource: (glyph) => myBackend.emojiUrl(glyph),
@@ -2873,14 +3166,21 @@ What to know:
 - **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
-  text-bearing tool opens the inline editor as it lands. `armTool` **throws** only for a name the
-  catalog does not know, and `placeableByWidget(type)` answers in advance.
+  text-bearing tool opens the inline editor as it lands; a right-click while a drawing is half
+  placed takes it back and puts the tool down. `armTool` **throws** only for a name the catalog does
+  not know, and `placeableByWidget(type)` answers in advance.
 - **Persistence speaks a shared codec.** The store document (`{ [symbol]: SerializedDrawing[] }`,
   via `parseDrawingsStore`/`serializeDrawingsStore`) is the SAME document every host of the codec
   reads and writes, so drawings survive moving between hosts. A drawing bound to one chart (sync
   off) lives in the adapter's chart-bound scope for the symbol; a shared drawing lives in the
   symbol's scope, and a refused write merges the stored document over the layer's own before it
   writes again.
+- **A save keeps its look.** A drawing saves at `v: 3`. A save at `v: 2` restores with the look it
+  was saved with: its tool writes the values that paint it so and saves at `v: 3` with them, the
+  looks the tool's pages do not set riding in the props `INERT_PROPS` lists. A gann square, a gann
+  square fixed, a speed resistance fan, a pitchfan, the text and annotation tools, the marks and a
+  table saved at `v: 2` paint as they were saved (`savedLook`) until their settings change. A host
+  that writes drawings itself writes `v: 3`.
 - **Keys run through the registry.** Delete and Backspace remove the selection, Escape cancels a
   placement, disarms, or closes the inline editor, and Ctrl (or Cmd) with C and V copy and paste a
   drawing. Each resolves to a `chart.drawings.*` command, so your access policy gates the keyboard
@@ -2892,7 +3192,8 @@ What to know:
   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 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.
+  included, until it is released. A right-click selects the drawing it lands on, so the menu that
+  follows acts on it, and the handle under a mouse stands out.
 
 ## Extensions
 

package/dist/adapters/rest.d.ts

@@ -1,4 +1,4 @@
-import { C as ChartSaveLoadAdapter } from '../resources-C0cYryO9.js';
+import { C as ChartSaveLoadAdapter } from '../resources-Le6flcEn.js';
 
 /** The three template collections. */
 type RestTemplateKind = 'indicator' | 'drawing' | 'palette';