efficient-shell 5.6.1 → 7.7.0

package/README.md

@@ -16,7 +16,7 @@ A backend-less playground hosted on GitHub Pages. Wallpapers, themes, sticky not
 
 **Shell:** `<Layout>`, `<StartMenu>`, `<Desktop>` (with sticky notes + folders), `<WindowManager>`, `<Modal>` (standard / compact / widget styles), `<PopupMenu>`, `<ConfirmDialog>`, `<GlobalSearch>` (Cmd-K), `<ShortcutHelp>`, `<NotificationBell>`, `<StatusBadge>`, `<SearchableSelect>`, frosted-glass theming.
 
-**UI primitives:** `<Button>`, `<Input>`, `<Textarea>`, `<Select>`, `<Checkbox>`, `<Radio>` / `<RadioGroup>`, `<FormField>`, `<Label>`, `<Snippet>`, `<Kbd>`, `<Card>` / `<StatCard>`, `<Avatar>` / `<AvatarGroup>`, `<Banner>`, `<Tabs>`, `<Accordion>`, `<Tooltip>`, `<Pagination>`, `<MetricBar>`, `<BudgetBar>`, `<SettingRow>`, and dependency-free `<Sparkline>` / `<LineChart>` / `<BarChart>` / `<DonutChart>` charts.
+**UI primitives:** `<Button>`, `<Input>`, `<Textarea>`, `<Select>`, `<Checkbox>`, `<Radio>` / `<RadioGroup>`, `<FormField>`, `<Label>`, `<Snippet>`, `<Kbd>`, `<Card>` / `<StatCard>`, `<Avatar>` / `<AvatarGroup>`, `<Banner>`, `<Tabs>`, `<Accordion>`, `<Tooltip>`, `<Pagination>`, `<MetricBar>`, `<BudgetBar>`, `<SettingRow>`, and the dependency-free chart family (`<Sparkline>` for a tile, and `<ColumnChart>`, `<TimeSeriesChart>`, `<PieChart>` and the rest for charts that are read).
 
 **Page templates:** ready-made screens composed from the primitives — `<DashboardTemplate>`, `<DataTablePage>`, `<FormLayoutPage>`, `<CheckoutTemplate>`, `<EmailTemplate>`, `<ChatTemplate>`, `<GalleryTemplate>`, `<AuthScreen>`, `<ErrorPage>`. `<ErrorBoundary>` catches a render crash and shows the 500 page in place of a blank screen.
 
@@ -54,9 +54,12 @@ Peer deps you should already have in a typical React + Tailwind v4 app:
 
 ```bash
 npm i react react-dom react-router-dom @tanstack/react-query react-hook-form \
-      tailwindcss @headlessui/react @heroicons/react
+      tailwindcss @headlessui/react
 ```
 
+No icon package: the shell draws every icon from its own set
+(`efficient-shell/icons/efficient`).
+
 All of those except `react` / `react-dom` are declared **optional** peers. The
 shell's components need them — a portal that drops one gets a module-not-found at
 build — but a consumer taking only `efficient-shell/markup` needs none of them, and
@@ -922,10 +925,28 @@ End go to `min`/`max`, and Enter or a double-click resets to `defaultWidth`. A
 drag starts after 3px, so a click never nudges it. `storageKey` restores the
 width after mount and keeps it once a drag settles. Its hint is a `Tooltip`.
 
+For the seam between two stacked panes, such as a message box under a thread,
+pass `orientation="horizontal"` and `side="top"` or `side="bottom"` (where the
+pane sits). The word and its values are `Divider`'s and `IconRail`'s, and they
+name the line: a grip between stacked panes is a horizontal line. It drags up
+and down, its cursor is `row-resize`, it is a separator with
+`aria-orientation="horizontal"`, and ArrowUp/ArrowDown move it. Home, End,
+Enter, the double-click and `storageKey` work as above. `width`, `min`, `max`
+and `defaultWidth` are then the pane's height. The default is
+`orientation="vertical"`, and its markup is unchanged.
+
+```tsx
+<section className="relative" style={{ height }}>
+  <ResizeHandle orientation="horizontal" side="bottom" width={height} onResize={setHeight} min={108} max={520} defaultWidth={220} storageKey="chat.composer" />
+  …
+</section>
+```
+
 **`WidthsBar`** sets how a row's columns share its width: a bar split into
-the columns, a handle between each pair, and a typed % box for each column.
-The last column fills itself. It came from the campaign designer's "Column
-widths" field (efficient-admin-portal), which is deleted once this ships.
+the columns, with a handle between each pair. Each segment of the bar is
+where its % is typed; there are no number boxes under it. It came from the
+campaign designer's "Column widths" field (efficient-admin-portal), which is
+deleted once this ships.
 
 ```tsx
 <InputNumber aria-label="Columns" value={count} onChange={n => n && setCount(n)} min={1} max={4} />
@@ -934,8 +955,41 @@ widths" field (efficient-admin-portal), which is deleted once this ships.
 
 The value is `ColumnShares`: the first `count - 1` shares, whole percentages.
 The last column is what the others leave, so the widths always add up. No
-column goes under `COLUMN_SHARE_MIN` (10%): raising a box squeezes the columns
-after it, and a handle trades width with its neighbour and stops at the floor.
+column goes under `COLUMN_SHARE_MIN` (10%).
+
+Each segment's "34%" is a field that looks like a label until it is focused.
+Focused, it shows a focus ring and the bare number, selected. Enter or leaving
+the field commits; Escape puts back the value from when the field was
+entered. ArrowUp/ArrowDown step 1, Shift 10. Every column can be typed in, the
+last one too. A typed column takes its room from the next column (the last
+column from the one before it); when that one is at the floor, the room comes
+from the column after it, then from the other side. A focused field in a
+narrow segment grows to at least 40px, over the handles and inside the bar.
+A segment narrower than 36px shows "10" rather than "10%". Each field is a
+`spinbutton` named "Column 1", "Column 2", … (`strings.widths.column`), valued
+in percent and described by the hint. Tab goes column 1, the handle after it,
+column 2, …, the last column, then "Reset to equal".
+
+A handle trades width with its neighbour and stops at the floor. Its line is
+2px at rest and 4px on hover, keyboard focus and while dragged; the grab area
+is 12px either way. Under 264px of its own width (a container query, not the
+window), the bar puts "Reset to equal" under the hint, at the right end.
+
+A host that draws its own reset and hint passes `footer={false}`: for
+example a settings field with a reset in its heading row (shown only when
+the value has changed) and a hint that folds away. The bar then draws
+nothing under itself, not even a gap. The hint is still there for screen
+readers, as visually hidden text that the group and every field are
+described by. The host's reset calls `onChange(undefined)`, as the bar's own
+does.
+
+```tsx
+<WidthsBar label="Widths" count={count} value={row.columnShares} onChange={save} footer={false} />
+```
+
+While a field in a narrow segment is focused and grown, a neighbour's label
+that it covers even in part is hidden whole, so only whole numbers are ever
+seen.
 A row that chose nothing shows equal widths and stores nothing; "Reset to
 equal" calls `onChange(undefined)` and never stores 34/33, because no value
 renders as the exact `33.34% / 33.33% / 33.33%` strings saved rows carry.
@@ -957,13 +1011,33 @@ equal strings and the equal panel figures.
 each face in itself. The `label` still names, filters and fills the field.
 `Select` takes the same, and `renderValue(chosen)` draws its closed field.
 
+**A server search that is running, or has failed.** A `SearchableSelect` fed
+by `onSearchChange` can say both. `loading` puts "Searching..." on a line
+above the options, in place of "No matches". `error` puts the caller's words
+there instead ("Couldn't search your catalog."), and `onRetry` adds a "Try
+again" button to that line; its press keeps focus in the field and the list
+open. Options still listed (the last answer, or a search that half failed)
+stay under the line and stay pickable. `loading` wins over `error`. Without
+them the list is what it was.
+
+**A typed value only when it is picked.** `SearchableSelect`'s
+`allowFreeText` saves the typed text on Enter, Tab, blur and a press outside.
+For a field where typing is mostly searching — a PO number, a shipment —
+`` freeTextOption={text => `Use “${text}” as manual PO#`} `` instead draws the
+typed text as one more row at the end of the list, in those words, and saves
+it only when that row is pressed or reached with the arrow keys and taken with
+Enter. Every other way out drops it. The row is not drawn while nothing is
+typed or while the text is exactly an option's label. It turns free text on by
+itself, and with `multiple` it adds the text and keeps the list open.
+
 **Gaps the editors found in the form kit** (efficient-easel#199, harness UI-24),
 now in the kit itself:
 
-- **`Segmented`**: the chosen chip has a 1px `--ink-faint` ring, 3:1 or more
-  against its track in light and dark, so a strip of icons shows which option
-  is chosen (WCAG 1.4.11). An option's `title` is shown in the kit's `Tooltip`,
-  not the native attribute. A radio option also gets it as its description.
+- **`Segmented`**: the chosen option is the solid blue chip pill `Tabs` draw
+  (owner, 2026-10-12), 4.8:1 against the light track and 3.1:1 against the
+  dark one, so a strip of icons shows which option is chosen (WCAG 1.4.11).
+  An option's `title` is shown in the kit's `Tooltip`, not the native
+  attribute. A radio option also gets it as its description.
 - **`Input`, `Textarea`**: `readOnly` draws the read-only ground (`bg-gray-50`,
   `--surface-sunken` in dark). The border and focus ring do not change.
   `inputClasses({ readOnly: true })` gives the same look to anything else.
@@ -1017,6 +1091,25 @@ Round 4:
   option checked), `disabled` options (greyed, skipped by the arrows, inert to
   a press), and `clearable={false}` to drop the "×". Groups, flattening and the
   check are shared with `Select`.
+- **`SearchableSelect` as a list filter, and with several values** (admin
+  list pages). `filter` marks a field that filters a list ("All Suppliers").
+  While it holds a value it is "on": the accent border and a light accent fill,
+  as a set `FilterBar` chip, in light and dark. Empty or disabled, it is a
+  plain field. With `filter` or `multiple`:
+  - the open list may be **wider than the field** — at least the field's
+    width, growing to fit its options up to the kit's popup width, inside the
+    owning window (UI-11) — so long names are not cut;
+  - **open, the field still shows what is chosen** (in the field's ink) until
+    the person types.
+
+  With `multiple`, a **"Clear all"** row tops the open list while anything is
+  chosen (not with `clearable={false}`). Closed, the field shows **the labels
+  that fit, then "+N"** for the rest ("AA, AC, MF +3"), never a bare "…"; a
+  field too narrow for one label and a count says "6 selected". Hovering a
+  shortened field shows every chosen label in a `Tooltip`. A single-pick field
+  without `filter` is unchanged. New strings: `select.clearAll`,
+  `select.selectedCount(count)`. `Tooltip` shows no bubble while its `content`
+  is empty.
 - **`IconButton`**: `pressed` wears the pressed look without `aria-pressed`,
   for a menu button that is open (`aria-expanded`), a radio, or a window's
   button.
@@ -1033,6 +1126,9 @@ Round 4:
 - **`Tabs`**: a `TabItem` takes `tooltip`, a shell `Tooltip` that opens on
   hover and on focus, so the arrow keys show each tab's word in turn. Keep the
   word in `label` (visually hidden) for an icon-only tab.
+  `variant="pill"` is the same strip `Segmented` draws: the active tab is solid
+  blue with white text on the grey track, 32px tall. The tablist roles, the
+  arrow keys and `idPrefix` stay the tabs' own.
 - **`registerModalEscapeInterceptor`** is on `efficient-shell/ui`. A window or
   panel a host draws itself registers there, with the element it closes, so
   Escape reaches it before the window around it and a `Tooltip` outside it
@@ -1082,25 +1178,25 @@ All exports are named — `import { Modal, ... } from 'efficient-shell'`.
 | `ProductionTimeline` | The scrubbable production bar, drawn on `TimelineTrack` inside the shared timeline card: a sentence-case heading with the PO as its subject, the window and the lead time as meta, a Play **pill** on the right whose glyph follows its state, and a footer carrying the status line and legend chips drawn with the track's own glyphs — a shipment is a diamond with a truck in it and an inspection a disc with a flask, on the rail and in the chip alike, because every kind is painted in the one accent and the glyph is the only thing left to tell them apart. The thumb only ever rests on a date a report was filed on — drag it and it snaps report to report, arrow it and it steps one report at a time — so the bar never shows an estimate dressed as a fact. Press Play and it **travels** between them: a fresh press rewinds to the first report, the thumb reads each snapshot for 700 ms and then glides to the next with the date chip counting the days it crosses, and the status line under the bar changes on arrival rather than while it is on its way. Pausing freezes it mid-glide and pressing Play again carries on from exactly there; touching the thumb ends the playback and hands it back. The walk keeps time by the clock rather than by the frame rate, so an idle or throttled pane does not stretch it. `onScrubProgress` forwards the track's in-flight fraction — `{ fromKey, toKey, t, ms }` keyed by report id, `null` at a stop — which is how a consumer's items table moves WITH the thumb instead of jumping a whole report's worth of quantities when it lands; it is optional and undefined by default, so a caller that only reads the snapshot needs no change. `onPickReport` selects a report; the optional `onOpenReport` / `onOpenMarker` make the label above the thumb a real button that opens the document behind it. `reportLabel` names a report wherever the bar states its identity — the caption over the thumb, the popover header, each dot's accessible name, the slider's value text and the status line — and defaults to its own `progress_number`, while `resetLabel` replaces the whole of the `Back to …` button: together they are what lets a portal that must not print an internal document number run the same card. A report carries an optional `preview` for its hover/focus popover — the stage row it filed, the note attached to it — and `renderReportPreview` builds one for the reports that carry none, the convenience for a caller whose list arrives straight off an API; the report's own preview wins where both exist, and the popover prints the report number and the date itself. `useProductionTimeline(opts)` owns the slider state and the derived snapshot so the caller's items table and the bar read the same state; `STAGES` / `calcOverall` / `calcReportOverall` are the stage maths it shares with that table. **`variant="rail"`** is the bar alone, for a window whose own header already says what the order is: no card, no heading, no lead-time line, no label under the active report — every report, shipment, inspection and **invoice** (kind `invoice`, a disc with a receipt) is a dot with a popover — the thumb with its date chip, `Start` and `Est. done` flanking the rail, the estimated completion as a hollow mark on the right edge while it is still ahead, and under the rail one row: Play, the return button when the thumb has been moved, and the `<report> · date · N% overall · N pc in stock` line. The rail spreads the reports (the track's `spread` axis) rather than folding two a week apart into a `×2`. `onPlayStart` fires before the thumb moves, on a fresh run and on a resume, so a window that keeps the bar in view while its table shows something else can switch the table first. |
 | `MilestoneTimeline` | The static sibling, on the same `TimelineTrack` and in the same card: one dot per milestone on a date axis, no scrubber. `heading` and `subject` split the title from the record it is about (`Mould development` · **001F/1813**), and the meta line states when it started, how long it has run and how many milestones are dated. The axis **cuts** rather than squeezes: a stretch holding more than 30% of the window's time becomes a fixed notch with a break glyph saying how many days it hides, and every stretch that still keeps time gets at least 48 px. Labels are packed into **two lanes** by their **measured** width, and a run of same-kind revisions folds into one `DFM ×4` pill whose members keep their dots on the rail: hovering it magnifies that stretch until each member can carry its own label, a click pins the popover listing them, Escape closes it. A milestone carries an optional `glyph` (a `default` one that names `doc` is drawn as the signed drawing it is), a `preview` for the popover, and an `onOpen` that the popover's "Open" button fires — `onClick` selects the dot on the bar, `onOpen` opens the drawing behind it, and a card that declares only the first keeps its Open button because the footer falls back to it. Label and date are printed by the popover above the preview, so a consumer supplies neither. A milestone with **no date gets no position**, because the only position available would be a date the record does not have: it is listed beside the bar under "Not yet reached" (two rows, then a real `+N more` button) and takes no part in the range, the fill or a phase bracket. `phase` groups of 2+ get a bracket marking parallel work, the fill never runs past today, and today gets its dashed rule and tag even when it IS the right edge — the commonest case, because a programme with no finish date ends at today. **`variant="rail"`** is the bar alone, for a window whose stepper already names the stages: no card, no heading, no label under any dot — every milestone is a dot with a popover, a revision carries a two-character `caption` over its dot (`v3`; captions that would overprint collapse to `v1–v4`), `edgeCaptions` flank the rail on its own row (`{ start: 'Start', end: 'Ready' }`), nothing is cut (the `spread` axis: every stretch at least 48 px, the idle ones drawn short rather than notched), and what has not happened is one dashed **cap** at the end of a dashed tail — a real button announced as the last undated milestone, naming the rest in its popover. The stepper and the rail then point at each other: `highlightKeys` lights one soft band from the leftmost named milestone to the rightmost and every dot inside it (a single key rings one dot; the cap answers to the pending milestone's key), and `onHoverChange` reports the milestone under the pointer or the focus, `null` on leave. A `provisional` milestone — a sample ORDERED, drawn where the shipment will be — is hollow, never "where we are", and outside the fill. |
 | `SettingRow` | One setting in a settings card: the name with its explanation stacked under it on the left, the control or value on the right (it never shrinks), and an optional body (`children`) that opens beneath behind its own line. Each row draws its own top line (`divider`) and padding, so rows stack in a card. One prop per slot: `label` (the name) and `value` (a control or a read-only fact). `size="compact"` is the editor-panel row. Handles a value that is a control (`controlId` labels it), a read-only fact, a value nobody knows (an em dash in the faint ink, never an empty cell), and a `quiet` row nothing can write yet. A name over a field (children, no value) draws nothing on the right. `DescriptionList` is the record-detail neighbour and stays that. |
-| `Button`, `Input`, `Textarea`, `Select`, `Checkbox`, `Radio`, `Switch`, `FormField`, `Label` | Form controls — controlled (`value`/`onChange`); `Input`/`Textarea` forward native props for react-hook-form. `Button` and `Switch` take `disabledReason`: persistent text beside the control wired with `aria-describedby`, never a `title` — a tooltip needs a hover a disabled control does not reliably get. `Switch` also takes `disabledReasonId`, so a panel whose controls are all dead for one reason states it once and points every control at it. A `Select` option carries an optional `description`, rendered as a second muted line **in the open list only** — the closed trigger stays one line, so one explained option cannot change the height of every field in the row. `NativeSelect` (and so `Select` on touch) ignores it: an `<option>` holds text and nothing else. An option also takes `lang` (a BCP 47 tag) when its label is written in another language than the page's — a language picker naming each language in its own words: it goes on the option in the open list, on the native `<option>` and on the closed trigger's label while chosen, so a screen reader and the font fallback treat each name as its own language (WCAG 3.1.2). On the desktop listbox, `title` joins `aria-label` / `aria-labelledby` / `aria-describedby` on the VISIBLE trigger button — it used to ride the native spread onto the `sr-only` `<select>`, where a tooltip has no pointer that can reach it and a fallback name sits on an `aria-hidden` element. `name`, `required` and the forwarded ref stay on the native control, which is what it is for. A `Checkbox` or `Radio` with both a `label` and a `description` is NAMED by the label and DESCRIBED by the description (`aria-labelledby` / `aria-describedby`); the whole row is still its `<label>`, so its words still tick it. `FormField` points its one child at the hint or error on screen with `aria-describedby`, and marks it `aria-invalid` while `error` is set. A child that already has its own `aria-describedby` (a react-hook-form binding often does) keeps it: the ids are merged, the child's own first, and each id is said once — a repeated id is a message a screen reader reads twice. |
+| `Button`, `Input`, `Textarea`, `Select`, `Checkbox`, `Radio`, `Switch`, `FormField`, `Label` | Form controls — controlled (`value`/`onChange`); `Button`'s `variant` is `primary` (the default), `secondary` (outlined), `secondary-danger` (outlined in red: a destructive action in a footer of outlined buttons, e.g. Delete beside Archive — the same size and shape as `secondary`, red border and text, a light red wash on hover), `ghost`, `ghost-danger` (red text, no box: a destructive action among quiet `ghost` buttons), `danger` (solid red: the one action a confirm dialog asks for) or `link`; `Button` takes `pressed` (or follows `aria-pressed`) for a toggle that is on, with `IconButton`'s accent wash and ink on `ghost` and `secondary` (`secondary` keeps its border, tinted, so it does not move; `buttonClasses({ pressed })` gives a link the same); `Input`/`Textarea` forward native props for react-hook-form. `Button` and `Switch` take `disabledReason`: persistent text beside the control wired with `aria-describedby`, never a `title` — a tooltip needs a hover a disabled control does not reliably get. `Switch` also takes `disabledReasonId`, so a panel whose controls are all dead for one reason states it once and points every control at it. A `Select` option carries an optional `description`, rendered as a second muted line **in the open list only** — the closed trigger stays one line, so one explained option cannot change the height of every field in the row. `NativeSelect` (and so `Select` on touch) ignores it: an `<option>` holds text and nothing else. An option also takes `lang` (a BCP 47 tag) when its label is written in another language than the page's — a language picker naming each language in its own words: it goes on the option in the open list, on the native `<option>` and on the closed trigger's label while chosen, so a screen reader and the font fallback treat each name as its own language (WCAG 3.1.2). On the desktop listbox, `title` joins `aria-label` / `aria-labelledby` / `aria-describedby` on the VISIBLE trigger button — it used to ride the native spread onto the `sr-only` `<select>`, where a tooltip has no pointer that can reach it and a fallback name sits on an `aria-hidden` element. `name`, `required` and the forwarded ref stay on the native control, which is what it is for. A `Checkbox` or `Radio` with both a `label` and a `description` is NAMED by the label and DESCRIBED by the description (`aria-labelledby` / `aria-describedby`); the whole row is still its `<label>`, so its words still tick it. `FormField` points its one child at the hint or error on screen with `aria-describedby`, and marks it `aria-invalid` while `error` is set. A child that already has its own `aria-describedby` (a react-hook-form binding often does) keeps it: the ids are merged, the child's own first, and each id is said once — a repeated id is a message a screen reader reads twice. |
 | `buttonClasses`, `iconButtonClasses` | `Button`'s and `IconButton`'s look as a class string, for something that must navigate and so cannot be a `<button>`: `<Link href="/organisations/new" className={buttonClasses({ variant: 'secondary' })}>Add a business</Link>`. Same options and defaults as the component (`variant`, `size`, `block`, `className`), and the components render through these functions, so the two cannot drift. What the string cannot give an `<a>`: a disabled state (`disabled:` never matches an anchor — drop the `href`, add `role="link"` and `aria-disabled="true"`, or render a disabled `Button`), and the cursor (an `<a href>` gets the browser's pointer, a `<button>` the host's preflight; set it once for both). Keep its `inline-flex` — ask for `block` rather than passing a display utility. An icon-only link still needs the `aria-label` `IconButton` would have required. Client references, like every kit function: call them in a `'use client'` file. |
 | `labelClasses` | `Label`'s look as a class string, for a `<label>` a host lays out itself — beside a check box, in a row with its control, `sr-only`: `<label htmlFor="x" className={labelClasses({ inline: true, className: 'flex gap-2' })}>`. `inline: true` drops `Label`'s block layout (`mb-1 block`) and keeps its size, weight and ink; without it the string is exactly what `Label` renders. A client reference: call it in a `'use client'` file. |
-| `Segmented` | A row of mutually exclusive options, all visible: a button group, or with `name` a real radio group that submits. Named by `label`, or by an element already on the page (`aria-labelledby`, a list row's own heading) and described by another (`aria-describedby`); an option's `title` says on hover what choosing it means. |
+| `Segmented` | A row of mutually exclusive options, all visible: a button group, or with `name` a real radio group that submits. It looks exactly like `Tabs variant="pill"`: the chosen option is solid blue with white text on the grey track, the others grey text. Both draw through one shared strip, so they cannot drift apart; only the roles differ (a value here, a tab panel there). `size` is `sm` / `md` / `lg` (24 / 32 / 40, the control-height ladder) or `touch` (56, as `Button size="touch"`). Icon-only: give the option its `icon` and its word as a visually hidden label (`sr-only`); the word names it and the icon is hidden from screen readers. Named by `label`, or by an element already on the page (`aria-labelledby`, a list row's own heading) and described by another (`aria-describedby`); an option's `title` says on hover what choosing it means. |
 | `DisplayChips` | Which parts of a section are shown, one chip per part ("Breadcrumb", "Stats", "Intro text"): blue with an eye while shown, grey with a crossed eye while hidden, and a press flips it. The chips wrap, so a long list takes a few short lines instead of one switch row per part. Controlled: `items` (`{ id, label, shown, disabled?, disabledReason? }`) and `onChange(id, shown)`. The group is named by `label` or `aria-labelledby`. Each chip is a real toggle button (`aria-pressed`), named by its part and described by its state in words (`displayChips.shown` / `hidden`), with a hover label that says what a press does; Space and Enter are the button's own. A chip with `disabledReason` stays focusable, its press does nothing and the reason is said, as on `Button`. Not `Segmented` (one choice of several) and not `TagInput` (typing values in). |
 | `RadioGroup` | One choice from a short visible list, with the group chrome each panel used to rebuild: a `role="radiogroup"` named by its own label (`aria-labelledby`, because `<label for>` cannot name a div), the `hint`/`error`/`required` wiring borrowed from `FormField`, and `orientation` for a row that wraps rather than compresses. The options are real native radios sharing one `name`, which is what gives the group its arrow keys, its disabled-skipping and its single tab stop — all from the user agent, none of it hand-rolled. `value: null` is "nothing chosen yet", not a silent first option. |
 | `Snippet` | A value the user copies rather than reads — an endpoint, a tenant id, a shell command. Monospace, truncated with the whole value on its `title` (`multiline` wraps instead), and a copy button that flips to a check for two seconds and says "Copied" through an `aria-live` region. `value` is what reaches the clipboard and `children` is what is shown, so a masked key displays masked and copies whole. `symbol` prints a leading glyph that is never copied and has **no default** — a URL has no `$` in front of it. A refused clipboard toasts rather than looking like it worked. Not a read-only `Input`: a value that can only be copied is not a control and should not take a tab stop or invite an edit. `id` and `aria-describedby` land on the COPY BUTTON — the only focusable thing in the row, and a labelable one — so a wrapping `FormField` really does label it and its hint is really announced; with `hideCopyButton` they fall back to the box, because an id that resolves to nothing is not wiring. |
-| `Kbd` | The badge the shortcut constants (`CMD_ENTER`, `ALT_SHIFT_E`, …) are shown in — a real `<kbd>`, two rungs, `className` layered on so a portal can tint it. It renders the string it is handed; which symbol a platform uses is what the constants already decide. |
+| `Kbd` | The badge the shortcut constants (`CMD_ENTER`, `ALT_SHIFT_E`, …) are shown in — a real `<kbd>`, two rungs, `className` layered on so a portal can tint it. `tone` says what it sits on: `neutral` (default, grey), `accent` (inside a primary or submit button: the `kbd-submit` chip, with no colour utility of its own) or `warning` (an amber button). It renders the string it is handed; which symbol a platform uses is what the constants already decide. |
 | `FormErrorSummary` | The error list at the top of a failed form (WCAG 3.3.1, the GOV.UK pattern): takes focus when errors appear, each message is a link that focuses the offending control by its `FormField` id. `fieldId` is optional: an error with no control behind it — a server's `_general` / `non_field_errors`, or a field the form does not draw — is listed as plain text, not a link that goes nowhere. Renders nothing while `errors` is empty. |
-| `TagInput` | Multi-value field — chosen values as removable chips, typing filters the option list in the same dropdown SearchableSelect uses. `allowFreeText` admits unlisted entries; Backspace in the empty input removes the last chip. The value array stays duplicate-free by construction. |
+| `TagInput` | Multi-value field — chosen values as removable chips, typing filters the option list in the same dropdown SearchableSelect uses. `allowFreeText` admits unlisted entries; Backspace in the empty input removes the last chip. The value array stays duplicate-free by construction. Opt-in, per chip: `tone(value)` gives a chip `'danger'` (the status red, for a value that is chosen but wrong here) or the default `'accent'`, and `tooltip(value)` gives it the kit's `Tooltip`, shown on hover and when its × has focus. An option's `sublabel` is drawn greyed beside its label in the list (a procedure's name beside its code), and typing it finds the option. `split` (a RegExp, such as `/[\s,/]+/`) takes typed or pasted "AA, AC" as two chips: each finished piece is a chip at once, a piece that names an option (label or value, any case) takes it, and any other piece needs `allowFreeText`. |
 | `DatePicker`, `TimePicker`, `DateTimePicker`, `DateRangePicker` | Date/time fields, all careful to speak LOCAL dates and wall-clock times (never `toISOString`). `TimePicker` and `DateTimePicker` wrap the platform's own inputs in the kit's field styling; `TimePicker` hands back an `HH:MM` string — a time of day names no calendar day, so it never invents a Date. **`DatePicker`** opens the kit's `Calendar` in a popover (`native` swaps in the platform's date input). Its value posts from a hidden input that takes `name` and `form`; `required` adds "Required" to the trigger's description (`datePicker.required`; a button may not carry `aria-required`) and drops Clear from the footer (`clearable` overrides either way); `invalid` paints the field, and the reader hears the error message the host links through `aria-describedby` (`FormField` does) — the trigger carries no `aria-invalid`, which a button may not either; Today is offered only when `min`/`max` allow today; `aria-*`, `data-*`, `title`, `tabIndex`, `autoFocus`, `onFocus` and `onBlur` reach the trigger, while what only a text box can use (`readOnly`, `pattern`, `autoComplete`…) applies with `native` alone. Named by a `<label htmlFor={id}>` or `aria-labelledby`, the trigger is described by the date spelled out. A browser never validates a hidden input, so `required` cannot block a submit in the popover. **`DateRangePicker`** is a from/to calendar with presets in one popover: side by side on a desktop; where that does not fit the room the box allows (a phone, a narrow shell window — measured, not a media query), the panel takes the full width between the margins and stacks, the presets a wrapping row of chips above the calendar and From/To one line each. `fullWidth` fills a filter-grid cell instead of shrink-wrapping its label. `id` (on the trigger button, for `<label htmlFor>`), `aria-labelledby` and `aria-label` name the trigger, and the chosen range is then its description ("Period, button, 1 August 2026 to 3 October 2026"). `name={{ from, to }}` posts the applied range as two hidden `YYYY-MM-DD` inputs (`''` when unset), so a GET form or a server action reads it as it read two date inputs. `required` adds "Required" to the trigger's description (`dateRange.required`) and, unless `clearable` is given, removes Clear. `min` / `max` (`YYYY-MM-DD`) bound it as they bound `DatePicker`: days outside are disabled, a preset whose range reaches outside is not offered (none at all on a range that starts today — time off, a booking — and then no Custom either), and with nothing chosen the panel opens on the first month that has a day to pick. `disabled` makes the whole control inert: a disabled trigger with the kit's disabled look, no panel, no Clear ×, and the hidden inputs disabled so the range is not posted (an open panel closes). `allowOpenEnd` lets Apply commit ONE end on its own — "from 1 August", "up to 30 June" — and turns the panel's From and To boxes into buttons that choose which end the next day sets (the start first, as before); the open end comes back as `''`. Without it Apply needs both ends, as it always has. Both pickers take `weekStartsOn` (0 Sunday, 1 Monday); without it the week starts where the provider's `locale` says. |
-| `Card`, `StatCard` | Surface panel (optional header/footer; `description` puts one sentence under the title, outside the heading) + dashboard metric tile. |
+| `Card`, `StatCard` | Surface panel (optional header/footer; `description` puts one sentence under the title, outside the heading; `headingLevel` makes the title a heading and the card a region named by it, and an `aria-label` names the region instead when the title is not the name, such as a count; `tone="warning"` draws the border amber for a card that needs attention, and the card's words still say why; `tone="current"` marks the current card in a list with a light-blue header band, a blue title and `aria-current`) + dashboard metric tile. |
 | `Avatar`, `AvatarGroup` | User avatar with initials fallback + status dot; overlapping stack with +N overflow. |
 | `Banner` | Static in-flow alert (`tone`: info / success / warning / danger / neutral). `neutral` is a note that is none of the other four ("Prices exclude GST"): grey in the kit's neutral, the same wash and ink as a neutral `StatusBadge` (`--status-neutral-soft` / `--status-neutral-soft-ink`, `--status-neutral-solid` when `emphasis="solid"`), with the info glyph. `action` renders a control at the right edge — after the text, so a screen reader reaches the problem before the remedy, and before the dismiss ×, so "Update card" is never past "close this". Vertically centred against the words and `shrink-0`, so a message that wraps does not drag the button down or squeeze it — and on a narrow banner (a phone, a narrow column: the words keep at least 12rem) it drops UNDER the words rather than leave them a column one word wide. A banner that names a condition and leaves the fix three menus away is the usual shape of a notice nobody acts on. |
-| `Tabs`, `Accordion`, `Tooltip` | Controlled tab strip, collapsible sections, frosted hover/focus tooltip. A tooltip's `side` is a preference: near an edge the bubble slides along that side to stay 8 px clear of it, and flips to the opposite side when its own has no room, keeping inside the screen and inside the shell window that owns its trigger (UI-11). It never leaves that box: a bubble wider than the room wraps, and one taller than the room is cut off at it. The bubble is drawn on `<body>`, in a `fixed` layer laid over its trigger, so a scrolling pane or an `overflow-hidden` box around the trigger cannot cut it off; it follows the trigger when that moves and closes once the trigger has scrolled out of sight. A small arrow on the edge facing the trigger points at the trigger's centre wherever the bubble ended up, kept clear of the bubble's corners; it is the bubble's own surface (`.rosh-tooltip-arrow` in `ui.css`), solid and seamless under `rosh-reduce-transparency`, and hidden from assistive technology. |
+| `Tabs`, `Accordion`, `Tooltip` | Controlled tab strip, collapsible sections, solid hover/focus tooltip. `Tabs variant="pill"` draws the same strip as `Segmented` (the active tab solid blue on the grey track); use it when each choice shows its own panel, and `Segmented` when the choice is a value. A tooltip's `side` is a preference: near an edge the bubble slides along that side to stay 8 px clear of it, and flips to the opposite side when its own has no room, keeping inside the screen and inside the shell window that owns its trigger (UI-11). It never leaves that box: a bubble wider than the room wraps, and one taller than the room is cut off at it. The bubble is drawn on `<body>`, in a `fixed` layer laid over its trigger, so a scrolling pane or an `overflow-hidden` box around the trigger cannot cut it off; it follows the trigger when that moves and closes once the trigger has scrolled out of sight. A small arrow on the edge facing the trigger points at the trigger's centre wherever the bubble ended up, kept clear of the bubble's corners; it is the bubble's own surface (`.rosh-tooltip-arrow` in `ui.css`), seamless, and hidden from assistive technology. The bubble is SOLID, not glass, in every setting: the kit's solid popup surface (`--rosh-glass-surface`, `--rosh-glass-solid-border`, `--rosh-glass-solid-shadow`), so words behind a small bubble never mix with its own. |
 | `Stepper` | A linear wizard's progress strip — numbered circles, connectors, `aria-current="step"`. Controlled like Tabs; completed steps are clickable to go back (when `onChange` is wired), upcoming steps never are — moving forward belongs to the wizard's own Continue button, behind its validation. |
 | `DataTable` | Read-only table for server-driven lists: it renders and reports, and never sorts or pages its own `data`. Controlled sort and pager, row selection, column groups, pinned columns, windowed rendering. `onRow` gives a row `onClick`, a `className`, any `data-*` attributes for its `<tr>` — a test's or a stylesheet's hook (`data-testid`, `data-state`) — the pointer and the keyboard coming in and out (`onMouseEnter` … `onBlur`) and `current`. `rowHref` makes each row one real link (`onRowPress` a button) with its controls still pressable — see [DataTable rows that are links](#datatable-rows-that-are-links). `stackOnNarrow` turns each row into a labelled card on a narrow container — see [DataTable on a narrow screen](#datatable-on-a-narrow-screen). |
 | `Pagination` | Numbered page control (pairs with tables; complements `ListFooter`). |
-| `Sparkline`, `LineChart`, `BarChart`, `DonutChart`, `ScatterChart` | Dependency-free inline-SVG charts (`currentColor`-themed). `LineChart` is the multi-series trend with optional scale, legend, dots and area fill. `ScatterChart` takes `xDomain` / `yDomain` to override the derived axis, and `xScale` / `yScale` of `'log'` for a long tail; a point outside a supplied domain is dropped and counted in the accessible label. |
+| `Sparkline`, `ScatterChart` | Dependency-free inline-SVG charts. `Sparkline` is the decorative trend for a tile (`currentColor`-themed). For bars use `ColumnChart`, for a trend over time `TimeSeriesChart`, for a donut `PieChart variant="ring"`. `ScatterChart` takes `xDomain` / `yDomain` to override the derived axis, and `xScale` / `yScale` of `'log'` for a long tail; a point outside a supplied domain is dropped and counted in the accessible label. |
 | `BulkImportGrid` | Paste-or-upload bulk entry with column mapping, duplicate review and optional sum-merge. Hands resolved rows to `onImport`; owns no persistence. The whole panel takes a dropped CSV; the Upload CSV button opens the same dialog. Its words are the strings catalog's `bulkImport` section (a `description` prop wins), and its totals are written in the provider's `locale`. |
 | `UndoProvider`, `UndoControls` | One undo stack per form window, covering its fields, line items and bulk imports. Register state with `useUndoable` and the shell shows the Undo/Redo pair itself, leftmost in the window footer, as soon as the form has state and the window is editing (a draft, a duplicate, Edit mode) or the form has said `useUndoCanEdit(true)` — a view that merely holds state gets nothing — it joins a footer that is there for other reasons and never creates one, and the mobile chrome (footer hidden) gets nothing. A form mounts `UndoControls` by hand only for a place the footer is not (a plain overlay, a section header); a hand mount claims the stack and the shell then mounts nothing for it, so a form shows one pair wherever it chose to put it. Binds ⌘Z / ⇧⌘Z (and Ctrl+Y) except while the caret is in a field, where the browser's own undo wins. `WindowManager` already mounts one per window, scoped with `windowId` so a keypress reaches only the frontmost window; pass `windowId` yourself for any provider you mount outside a `<Modal>`, or two open windows will step back together. Offered to anyone who may edit the record — gate with `canEdit` and/or `perms`; a reader sees no controls and records no history. The shell-level provider cannot know the record's permissions, so a read-only form nests its own `<UndoProvider canEdit={false}>` to shadow it. A provider nested inside a window puts its own pair in the footer on the same footer terms — it joins a footer that is there for other reasons, never creates one or holds it open, and shows nothing on the mobile chrome — but its `canEdit` takes the place of the editing check: the form that nested it has already said whether the record may be edited, so pass `canEdit={isEditing}` (or the lock) rather than leaving the default. |
 | `Calendar` | Month grid with full keyboard navigation (arrows, Home/End, PageUp/Down) and `role="grid"` semantics. Single or range. Days of the months either side are quieter than the month's own but keep AA contrast: they are dates a person can press. The shared grid behind `DatePicker` and `DateRangePicker`. `weekStartsOn` defaults to the provider locale's first day of the week (`firstDayOfWeek`), Sunday without one. |
@@ -1274,8 +1370,8 @@ import 'efficient-shell/ui.css';
 ```
 
 **It reaches nothing but `react` and `react-dom`.** None of the optional peers —
-no `react-router-dom`, `@tanstack/react-query`, `axios`, `@headlessui/react` or
-`@heroicons/react` — which matters because they are declared *optional*, so a
+no `react-router-dom`, `@tanstack/react-query`, `axios` or `@headlessui/react`
+— which matters because they are declared *optional*, so a
 consumer who has not installed them gets an unresolvable import rather than a
 degraded style. CI asserts it against the built artifact
 (`scripts/verify-dist.mjs`), not just the source, because leakage can arrive
@@ -1506,7 +1602,7 @@ families the kit uses: **gray** (nearly all chrome: surfaces, borders, text),
 **red** (danger and invalid), **green** (success), **amber** and **yellow**
 (warning), one **emerald** and one **neutral** (a template's sparkline,
 BrandMark's dark plate), plus `white` and `black`. Status badges and charts read
-their own tokens (`--status-*`, `--viz-*`, `--rosh-donut-*`) rather than the palette.
+their own tokens (`--status-*`, `--viz-*`) rather than the palette.
 
 ```css
 @theme {
@@ -1552,7 +1648,14 @@ maps `--color-blue-*` sets these as well:
 
 Give the chip `kbd-submit` and no colour utility of its own. The dark and
 accent themes remap palette utilities as `!important`, so one written beside
-the class (`Kbd`'s gray ones included) wins over it there:
+the class (`Kbd`'s gray ones included) wins over it there. `<Kbd tone="accent">`
+is that chip, so write it in React; a bare `<kbd>` is the same chip in HTML:
+
+```tsx
+<button className="btn-submit rounded-lg px-4 py-2 text-sm font-medium">
+  Save <Kbd keys={CMD_ENTER} tone="accent" />
+</button>
+```
 
 ```html
 <button class="btn-submit rounded-lg px-4 py-2 text-sm font-medium">
@@ -1584,7 +1687,7 @@ Tailwind colour the kit always drew:
 | `--rosh-focus-ring-deep` | blue-500 | charts (plot, legend), a chip's remove, the date-range field |
 | `--rosh-focus-ring-accent` | blue-500, follows the accent | HelpCenter's search, the prompt dialog's field |
 | `--rosh-focus-ring-zone` | `rgba(59,130,246,.45)` | upload zones and thumbnails |
-| `--rosh-focus-ring-invalid` | red-400 at 30% | an invalid field, `ghost-danger` |
+| `--rosh-focus-ring-invalid` | red-400 at 30% | an invalid field, `ghost-danger`, `secondary-danger` |
 | `--rosh-focus-ring-invalid-strong` | red-400 at 40% | the `danger` Button |
 | `--rosh-focus-ring-invalid-solid` | red-400 | `FormErrorSummary` |
 
@@ -1696,8 +1799,8 @@ rows take their height from `--control-height-sm` / `-md` / `-lg` (24 / 32 /
 `efficient-shell/ui`: `SPACING_SCALE`, `SPACING_ROLES`, `CONTROL_HEIGHTS`, and
 `isSpacingStep('2.5')` for a Tailwind step.
 
-**Glass.** Menus, popups, listboxes and tooltips are frosted glass
-(`glassStyle()`). `--menu-opacity` (0–1, default `0.95`) sets how much shows
+**Glass.** Menus, popups and listboxes are frosted glass
+(`glassStyle()`); a `Tooltip` bubble is always solid (`solidSurfaceStyle()`). `--menu-opacity` (0–1, default `0.95`) sets how much shows
 through. `rosh-reduce-transparency` on `<html>` makes every popup one solid
 `--rosh-glass-surface` (default: `--surface`) with no blur — and strips
 `backdrop-filter` from everything else on the page too, since it is the user's
@@ -1724,12 +1827,11 @@ grid (`--viz-grid`) is `--line-strong`, the same as the axis.
 replaced: `--rosh-media-scrim` and `--rosh-media-scrim-button` (the dark wash
 under text and buttons on an upload thumbnail), `--rosh-drop-ring` (the halo
 while a file is dragged over a gallery), `--rosh-mark-plate-shadow` and
-`--rosh-mark-plate-shadow-strong` (`BrandMark`'s plates), `--rosh-resize-handle`
-(`SidebarLayout`'s handle without a custom accent), and `--rosh-donut-1` …
-`--rosh-donut-8` with `--rosh-donut-track` (`DonutChart`'s default palette —
-point them at `--viz-series-*` for one palette across every chart). The chart
-palette (`--viz-*`), the status tiers (`--status-*`) and the timeline
-(`--tl-*`) are documented where `ui.css` declares them.
+`--rosh-mark-plate-shadow-strong` (`BrandMark`'s plates), and
+`--rosh-resize-handle` (`SidebarLayout`'s handle without a custom accent).
+Every chart paints with one palette, `--viz-series-*`. The chart palette
+(`--viz-*`), the status tiers (`--status-*`) and the timeline (`--tl-*`) are
+documented where `ui.css` declares them.
 
 ### Languages, dates and numbers — `ShellStringsProvider`
 
@@ -3295,27 +3397,57 @@ that checks them, live in the EFFICIENT harness (`52-brand-surface.md`).
 
 ### Editorial markup — `efficient-shell/markup`
 
-One grammar for copy a human types into a plain text box, so a toolbar button and
-a parser can never disagree about what a delimiter means: `**bold**`, `_italic_`,
-`~~strike~~`, `==highlight==` (the brand accent, applied to a selection).
+The ONE grammar for copy a human types into a plain text box — in both editors,
+on the published page and in the campaign email — so a toolbar button and a
+parser can never disagree about what a delimiter means. It moved here from
+efficient-easel (`src/markup`, 6d31d5d) on 2026-10-12 (Lewis, D1) and replaced
+the smaller grammar this subpath held before.
 
 **Its own subpath because it imports nothing** — no React, no JSX, no DOM, none
 of this package's peers. A public site can take the rule without inheriting a 3D
 viewer and a PDF renderer; `dist/markup/index.js` is a standalone file with zero
-import statements.
+import statements, and the `./markup` export carries a `default` condition so a
+build script running under `tsx` resolves it too.
 
 What is shared is the RULE, not the rendering. A web renderer paints with
 theme-token classes and an email renderer must inline every style, so each host
-keeps its own renderer and walks the same token list.
+keeps its own renderer and walks the same tree or token list.
+
+| Mark | Means | Written by a button |
+|---|---|---|
+| `**x**` | **Strong** (bold) | yes, ⌘B |
+| `_x_` | italic, only at a word edge | yes, ⌘I |
+| `~~x~~` | strikethrough | yes |
+| `==x==` | **Emphasis** (the brand accent) | `applyMark` writes it; a copy field no longer offers it (`RETIRED_MARKS`) |
+| `^^x^^` | **Quiet** | `applyMark` writes it; a copy field no longer offers it (`RETIRED_MARKS`) |
+| `[words](href)` | a link — `http`, `https`, `mailto`, `tel` or no scheme only | yes, ⌘K |
+| `- ` at the start of a line | a bullet line, one level | yes |
+| `1. ` at the start of a line | a numbered line, one level: 1-3 digits, `. `, words; the number is kept as typed | yes |
+| `[x]{underline}`, `[x]{sup}`, `[x]{sub}` | underline, superscript, subscript (tree only) | `applyMark` / `toggleMark` |
+| `[x]{color=name}` / `[x]{color=#rrggbb}` | a theme colour by name (`isColorName`), or any colour as exactly six hex digits (`isColorValue`; saved lowercase) (tree only) | `applyColor` / `colorOver` |
+| `@@x@@`, `++x++` | Emphasis, Strong (the storefront's old word styles). `++` opens only at a word start, so `A++ rated tyres, A++ service` is plain text | no — read only |
+| `*x*`, `#x#`, `[x]` | legacy accent, bold, italic (per product set) | no — read only |
+
+The three names a merchant sees are in `MARK_NAMES`. A run never crosses a line
+break, and runs, spans and links nest up to four levels
+(`[**_[x]{sup}_**]{color=accent}`); a fifth stays as typed. Any block after `]`
+that is not exactly one of the four (`[x]{foo}`, `[x]{color=#f00}`,
+`[x]{{first_name}}`) is plain text. The spans and the numbered line are read by
+`parseMarkup` only: `tokenizeInline` keeps them as text, so a renderer that has
+not learned them prints the delimiters.
 
 | Export | Notes |
 |---|---|
-| `applyMark(text, start, end, style)` | Pure writer behind a toolbar button — returns the new text plus where the selection should sit. Pressing the same button again unwraps. |
-| `MARKUP_TOOLS`, `COPY_FIELD_TOOLS`, `markupTools(styles)` | Button descriptors, and the four a copy field offers (bold / italic / strike / highlight). A host renders its own buttons; only the rule is shared. |
-| `tokenizeInline(value, rules)` | Parses to `InlineToken[]`. Tokens ALTERNATE, starting and ending with a `text` token that may be empty — a renderer that wraps every segment depends on the empty ones to keep its markup stable. |
-| `stripInline(value, rules)` | The plain words — the only correct source for an `alt`, an `aria-label` or a structured-data field. Deleting delimiter characters by hand breaks the moment the grammar grows a marker. |
-| `STANDARD_MARKUP` | The four marks above. |
-| `STOREFRONT_MARKUP`, `CAMPAIGN_MARKUP` | Standard plus a host's own LEGACY runs, so already-published copy keeps rendering as it does today. Designed to be deleted once stored content has been converted. |
+| `parseMarkup(value, rules)` → `MarkupLine[]` | The whole grammar as a tree. Each run keeps the delimiters that were saved. |
+| `serializeMarkup(lines)` | The inverse: `serializeMarkup(parseMarkup(s, rules)) === s`, for every string. Pinned by `tests/markupRoundTrip.test.ts`; `tests/markupSameAnswers.test.ts` holds 1,609 strings from the repos' own code and tests whose answers were recorded once from easel's copy. |
+| `isSafeLinkHref(href)` | The link rule. Call it before writing any `href`. |
+| `tokenizeInline(value, rules)`, `stripInline(value, rules)` | The flat reading older renderers use: runs only, no links, no nesting. Tokens ALTERNATE, starting and ending with a `text` token that may be empty. `stripInline` is the only correct source for an `alt`, an `aria-label` or a structured-data field. |
+| `applyMark(text, start, end, style, rules?, placeholders?)`, `markedAt`, `MARKUP_TOOLS`, `markupTools`, `COPY_FIELD_TOOLS`, `MARK_PLACEHOLDERS` | The writer behind a toolbar button (pressing the same button again unwraps), whether a button is pressed, and the button descriptors. A copy field offers bold, italic and strike. |
+| `applyColor(text, start, end, name)`, `isColorName`, `isColorValue`, `spanFor` | A colour carries a value, so it has its own writer: it writes, changes and (`null`) takes off `[x]{color=name}`, and changes nothing for a value `isColorValue` refuses (`#f00`, `rgb()`, a typo). |
+| `findLink`, `writeLink`, `removeLink` | The link window's reading and writing, with the parser's own link rule. |
+| `markedLines`, `writeMarkedLines`, `sameMarks` | The saved string as characters, each carrying its runs, and back byte for byte — what an editor that hides the delimiters edits. |
+| `toggleMark`, `marksIn`, `linkOver`, `unlinkAt`, `colorOver`, `colorIn`, `setList`, `listIn`, `clearMarks`, `clearStyle` | Writers that act on the WORDS whichever runs they sit in, splitting a run rather than crossing a delimiter, and the readers a toolbar draws its pressed state from. |
+| `STANDARD_MARKUP`, `STOREFRONT_MARKUP`, `CAMPAIGN_MARKUP`, `RETIRED_MARKS` | The rule sets. The last two add each product's LEGACY runs, designed to be deleted once stored content has been converted. |
 
 Two delimiter choices worth knowing. Italic is `_phrase_`, not `*phrase*`,
 because a single asterisk already means the accent color in the products that
@@ -3414,6 +3546,58 @@ so an app importing from both has one hook.
 | `FileIntakeAlert` | The rejection list as `role="alert"`, styled with Tailwind utilities (`text-xs text-red-600`). A page whose Tailwind does not scan this package renders `rejections` itself, as above — keep the `role="alert"`. |
 | `FileIntakeOptions`, `FileIntakeLimits`, `FileRejection`, `FileRejectionReason` | Types. |
 
+### Web vitals and errors — `startClientTelemetry` (`efficient-shell/telemetry`)
+
+Field performance and client errors from a portal, sent to the backend's
+first-party intake (`POST /api/client-telemetry/web-batches/`, efficient-backend
+docs/adr/0057). Call it once, after sign-in is known; the host decides whether
+it runs, what the app is called and what a route is.
+
+```ts
+import { startClientTelemetry } from 'efficient-shell'; // or 'efficient-shell/telemetry'
+
+const telemetry = startClientTelemetry({
+  app: 'admin-portal',                   // the intake's web app code
+  release: APP_VERSION,                  // this build's version
+  getAccessToken: () => getAccessToken(),// in-memory bearer token; null = send nothing
+  routeKey: () => currentRouteTemplate(),// '/sales-orders/:id' or a window key, never the URL
+  enabled: true,                         // the host's switch
+  vitalsSampleRate: 1,                   // share of page loads whose vitals are collected
+});
+// telemetry.flush(), telemetry.reportError(error), telemetry.stop()
+```
+
+What it collects:
+
+- **Web vitals** — LCP, INP, CLS, FCP and TTFB through `web-vitals` 6.2.3,
+  bundled (the host installs nothing). LCP, FCP and TTFB are filed under the
+  route the page loaded on; INP and CLS under the route when they are reported.
+  The device class (`desktop`, `tablet`, `mobile`) comes from the viewport and
+  the pointer.
+- **Errors** — window `error`, `unhandledrejection`, and the render errors both
+  `ErrorBoundary` and `WindowErrorBoundary` catch (a consumer's own `onError`
+  still runs beside it). Each error is the class, a redacted message (no
+  emails, tokens, URLs, UUIDs or record numbers; 160 characters) and the top
+  five frames as `path:line:column`, unsymbolicated. The same error is sent once
+  a page load with a count, and at most 20 distinct errors a page load.
+
+How it sends: queued, then posted every minute and when the page is hidden or
+left, in batches of at most 50 events and 30 KB, with
+`fetch(…, { keepalive: true })` and the bearer token. Not `sendBeacon`, which
+cannot carry an `Authorization` header. A failed send is dropped and never
+retried. No user, URL or query string ever leaves the page; a raw path the host
+passes as a route is cleaned (query gone, ids made `:id`).
+
+**The subpath reaches no package at all**, so dealer and POS, which take only
+`efficient-shell/ui`, can report too. `web-vitals` is a pinned devDependency
+bundled into it (`tests/telemetryEntryBundlesWebVitals.test.ts`); its licence
+is in `THIRD_PARTY_NOTICES.md`.
+
+| Export | Notes |
+|---|---|
+| `startClientTelemetry(config)` | Starts collecting; a second call replaces the first. Returns `{ flush, reportError, stop }`. `enabled: false`, a missing `window` or an `app`/`release` that is not version-like starts nothing. |
+| `ClientTelemetryConfig`, `ClientTelemetry` | Types. The subpath also exports the wire types (`TelemetryBatch`, `TelemetryEvent`, `WebVitalEvent`, `ClientErrorEvent`, `ErrorSource`, `DeviceClass`). |
+
 ### Open pages as tabs — `efficient-shell/page-tabs`
 
 For a routed app — a sidebar, a header, one page at a time — that wants what
@@ -3558,7 +3742,7 @@ read a stored focus on a server.
 | `severityOf(value, warn?, crit?)` | The `SeverityTone` (`success` \| `warning` \| `danger`) a reading earns against **inclusive** bounds; `null` when there's no reading or no usable bounds — the shell hardcodes no threshold. Backs `MetricBar`; use it to roll a `SidebarNavItem severity` up. |
 | `isSeverityTone(value)` | Type guard for the three tones. Validate a backend rollup with it at the fetch boundary, where a bad token can still be reported against its payload, rather than letting it surface as a wrong pixel. |
 | `toast.success / .error / .info` | Toast notifications — auto-mounts container. Each plays the user's chime; `toast.configure({ sound: false })` keeps them quiet for a host whose screen makes sounds of its own (an alarm, a till's beep), and `{ sound: true }` on one toast still asks for it. |
-| `Z_LAYERS` | The shell's z-index scale: `window` 50 (+ `windowStep` 10 per window above), `menu` 400, `pinnedWindow` 999, `overlay` 9999 (the palette, `Dialog`, `Drawer`, the shortcut sheet), `popup` 10000 (portalled listboxes, calendars, the server-status card). Popups sit above overlays so one opened inside a dialog is not drawn behind it. Apply as inline `zIndex` — an interpolated `z-[…]` class is invisible to Tailwind's scan. |
+| `Z_LAYERS` | The shell's z-index scale, in hundreds (owner ruling, 2026-10-12), bottom to top: `raised` / `sticky` / `inBox` 10 / 20 / 30 (inside one box only), `snapPreview` 900, `window` 1000 (+ `windowStep` 2 per window above), `peek` 1999, `pinnedWindow` 2000, `desktopWidget` 2100, `taskbar` 2200, `sidebar` 2300, `taskbarPreview` 2350, `startMenu` 2400, `restoreTab` 2500, `expose` 2600, `overlay` 2700 (the palette, `Dialog`, `Drawer`, the shortcut sheet, startup and logout), `toast` 2800 (toasts, the notification card, the update banner), `popup` = `menu` 2900 (context menus, portalled listboxes, calendars, the server-status card) and `hint` 3000 (tooltips). Menus and popups sit above overlays and toasts, so one opened inside a dialog is never drawn behind it; a pinned window stays under the taskbar and every menu. Apply as inline `zIndex`, or in markup as `z-(--z-<layer>)` from the matching `--z-*` custom property in `ui.css` — an interpolated `z-[…]` class is invisible to Tailwind's scan. Never write a stack order above 30 as a number: name the layer, and add a new one between two hundreds. |
 | `dismissPopups()`, `OVERLAY_OPEN_EVENT` | An overlay calls `dismissPopups()` as it opens; every open kit popup (`Select`, `SearchableSelect`, `TagInput`, `DatePicker`, `DateRangePicker`, `PopupMenu` via its `onClose`, `ServerStatusIndicator`) closes rather than floating over the overlay. The kit's own overlays already call it. A consumer's own popup listens for `OVERLAY_OPEN_EVENT` on `window` while open. |
 | `Kbd` constants — `MOD`, `ALT`, `SHIFT`, `ENTER`, `ALT_SHIFT_E`, `CMD_K`, … | Symbol constants for rendering keyboard shortcuts. |
 
@@ -3590,7 +3774,7 @@ root entry. They import React and nothing else.
 icon in every repository (2026-10-10). `<Icon name>` is typed to it, so a
 misspelt meaning does not compile.
 
-**One set.** `efficient` is the company's one icon set (Lewis 2026-10-12). Lewis
+**The default set.** `efficient` is the company's default icon set (Lewis 2026-10-12). Lewis
 picked the drawing of every meaning himself: the heroicons outline drawing where
 heroicons has the meaning, and our own drawing in the heroicons style (24 grid,
 1.5 line, round ends) where it has not. One meaning, one drawing: a name that
@@ -3606,19 +3790,40 @@ look="pencil-square" />`). The looks are a subpath of their own, so a host that
 draws only the default does not bundle them. A meaning without the look asked
 for draws its default.
 
+**A part a host can fill: the `swatch`.** In every look of `text-color`, the
+letter A itself is the swatch: one closed path (the letter and its counter)
+marked `data-part="swatch"`. A host paints the chosen colour into it with CSS
+(`.my-color-button [data-part="swatch"] { fill: var(--chosen) }`). The outline
+look keeps its ink line round the fill, so a light colour still shows on a
+light toolbar; with no such rule it draws a hollow A, so "no colour" is told
+apart from black.
+
 | Import | Set | Draws | Needs |
 |---|---|---|---|
 | `efficient-shell/icons/efficient` | `efficient` | every meaning, default look | nothing |
 | `efficient-shell/icons/efficient-looks` | `efficient` (its other looks) | `solid`, `mini` and the kept looks | nothing |
-| `efficient-shell/icons/heroicons` | `heroicons` | **deprecated**: the 197 meanings it drew | `@heroicons/react` |
-| `efficient-shell/icons/lucide` | `lucide` | **deprecated**: the 197 meanings it drew | `lucide-react` (0.577 or later) |
 
-The heroicons and lucide sets go in the next major release; register `efficient`.
-Heroicons drawings are copied under the MIT licence: see `THIRD_PARTY_NOTICES.md`.
+No icon package is behind it: the shell imports none, and no host needs
+`@heroicons/react` or `lucide-react` for it. Heroicons
+drawings are copied under the MIT licence: see `THIRD_PARTY_NOTICES.md`.
+
+**More sets: added beside the default.** `efficient` is the default set (Lewis
+2026-10-12: the set he picked is the default, and we add other sets later). A
+new set is one module that exports an `IconSet` (its `name`, `label` and the
+meanings it draws, with `looks` if it has them), registered after the default:
+
+```tsx
+registerIconSet(efficient);              // the default: every meaning
+registerIconSet(sketch);                 // { name: 'sketch', label: 'Sketch', icons: { trash: SketchTrash, … } }
+```
 
-The first set registered is the default (`setDefaultIconSet(name)` changes
-that). A meaning the chosen set does not draw falls back to the default set, so
-a partial set never leaves a hole.
+A set need not draw every meaning. Whatever the chosen set does not draw falls
+back to the default set's drawing, so a new set can start with a handful of
+icons and never leaves a blank. The first set registered is the default
+(`setDefaultIconSet(name)` changes that); after the chosen set and the default,
+every other registered set is asked, which is how a product's own glyphs are
+found. With a `look`, each set is asked for that look and then for its own
+default drawing, so a chosen set keeps its style.
 
 **Part of the theme.** The `icon_set` preference sits beside the colour theme
 and the corners: `useTheme` and `applyThemePrefs({ icon_set })` choose the set
@@ -3633,16 +3838,16 @@ drawn in the set that is active. It appears only when a host has registered
 more than one set, since one set is nothing to choose between.
 
 **The shell's own icons follow the set too.** A window's close button, the
-sidebar's chevrons, a banner's tone, a number box's steppers: 199 of the icons
-the shell draws itself are `<Icon name>`, so the chosen set draws them. Each
-hands `<Icon>` the drawing it had before as its `fallback`
-(`src/icons/fallbacks.tsx`, not a public entry), which is what a host that
-registered no set still sees: nothing changes there. Size, colour and stroke
-width stay with the place, so an icon takes the same box whichever set draws
-it. What is left inline is not an icon by meaning: charts, spinners,
+sidebar's chevrons, a banner's tone, a number box's steppers: every icon the
+shell draws itself is `<Icon name>` (with a `look` where it is filled), so the
+chosen set draws them. A host that registered no set still sees them: `<Icon>`
+falls back to `src/icons/kit.tsx` (not a public entry), which the generator
+writes from the default set's source with exactly the meanings and looks the
+shell's parts name, so the kit does not bundle the whole set. Size, colour and stroke width stay with the
+place. What is left inline is not an icon by meaning: charts, spinners,
 illustrations, an app's tool palette, a path a host supplies.
 `tests/shellIconFallbacks.test.tsx` holds each file to its count; a new icon in
-the shell is `<Icon name="…" fallback={…} />`.
+the shell is `<Icon name="…" />`, and `npm run icons` adds it to the kit.
 
 **A product's own glyphs.** An editor's block types and settings rows are not
 in the catalogue. Register them and draw them by `glyph`, with no icon package
@@ -3661,15 +3866,14 @@ whatever the theme.
 **Adding or changing a drawing.** `src/icons/efficient.json` is the source: per
 name its meaning, where the drawing came from, the default SVG (24 by 24
 viewBox, 1.5 stroke on `currentColor`, round ends, transparent background) and
-its looks, or the name it is an alias of. Add the meaning to
-`src/icons/catalogue.json` too, run `npm run icons`, and commit the lot. Look
+its looks, or the name it is an alias of. Run `npm run icons` and commit the
+lot. Look
 before you keep a drawing: `node scripts/icons/glyph-sheet.mjs <new>
 <neighbours…>` draws it at 16px beside the glyphs it could be mistaken for, and
 `tests/efficientSet.test.tsx` fails it if it looks like another meaning.
 
-With no set registered, `<Icon>` draws nothing and warns once per meaning. The
-kit's own components (a window's close button, a filter chip) keep drawing
-through a built-in fallback, so a host that registers nothing sees no change.
+With no set registered, `<Icon>` draws nothing for a meaning the shell's own
+parts do not use, and warns once per meaning. Register `efficient` at startup.
 
 ### The UI kit check — `efficient-shell-ui-check`
 
@@ -3715,6 +3919,8 @@ itself where the kit has an answer:
 | `icon` | an import of an icon package (`@heroicons`, `lucide-react`, `@tabler/icons`, …) | `<Icon name>` from `efficient-shell/icons` |
 | `svg` | an `<svg>` element written in JSX: an icon drawn in place (one per element, however many shapes it holds; a component named `Svg` and the word in a string are not counted) | `<Icon name>` from `efficient-shell/icons`. A chart, an illustration or a mark a host supplies stays on the baseline |
 | `kit-dep` | one of those packages declared in `package.json` (not `devDependencies`, and not one the shell needs from an entry the repository imports: `@headlessui/react` and `@heroicons/react` for the root entry, an icon set's own package) | remove it |
+| `chart` | an import of a second chart library: `recharts`, `chart.js`, `react-chartjs-2`, `d3` and every `d3-*` module (one imported only for its maths too), `@nivo/*`, `victory` and `victory-*`, `echarts`, `echarts-for-react`, `apexcharts`, `react-apexcharts`, `@visx/*`, `highcharts`, `highcharts-react-official`, `plotly.js`, `plotly.js-dist`, `react-plotly.js`, `lightweight-charts`, `@antv/g2`, `@antv/g2plot`, `chartist`, `billboard.js`, `c3`, `uplot`. A name counts with its subpaths (`chart.js/auto`); a name that only contains one (`react-d3-tree`) does not. Read after `kit` and `icon`, so `@mui/x-charts` stays a `kit` | a chart from `efficient-shell/ui`: `ChartFrame`, `TimeSeriesChart`, `ColumnChart`, `RankedBars`, `PieChart`, `FunnelChart`, `ScatterChart`, …; the one chart system (harness FT-3) |
+| `chart-dep` | one of those chart libraries declared in `package.json`, whether or not anything imports it (not `devDependencies`) | remove it |
 
 Known gaps: `rgb()` / `hsl()` colours, colours in `.ts` maps, and
 `createElement('button')` are not counted.