nexus-shared 3.2.0 → 4.1.0

package/README.md

@@ -1,1123 +1,1911 @@
-# nexus-shared
-
-Lightweight React components, helpers, and design tokens for Nexus apps. No runtime dependencies besides
-React and `nexus-icons`.
-
-```
-npm install nexus-shared nexus-icons
-```
-
-```tsx
-// Once, in the root layout
-import "nexus-shared/styles.css";
-
-import { Button } from "nexus-shared";
-import { InlineIcon, iconPlus } from "nexus-icons";
-
-<Button variant="primary" icon={<InlineIcon icon={iconPlus} />}>New booking</Button>
-```
-
-## Entry points
-
-| Import | Contains |
-|---|---|
-| `nexus-shared` | Components and helpers that work in server and client components |
-| `nexus-shared/client` | Client components and browser services |
-| `nexus-shared/server` | Server-only code |
-| `nexus-shared/styles.css` | Tokens, base styles, and component styles |
-
-## Themes
-
-Seven themes, each with a light and a dark palette that meets WCAG AA contrast:
-**Nexus** (default), **GitHub**, **Nord**, **Dracula**, **Solarized**, **Catppuccin**, and **Rosé Pine**.
-The mode is Light, Dark, or System (follows the operating system).
-
-```tsx
-// app/layout.tsx
-import "nexus-shared/styles.css";
-import { ThemeScript } from "nexus-shared";
-import { ThemeSwitcher } from "nexus-shared/client";
-
-export default function RootLayout({ children }) {
-  return (
-    <html lang="en" suppressHydrationWarning>
-      <head>
-        <ThemeScript />
-      </head>
-      <body>
-        <header>… <ThemeSwitcher /></header>
-        {children}
-      </body>
-    </html>
-  );
-}
-```
-
-- `ThemeScript` applies the saved choices before the page paints, so there is no flash of the defaults. Options:
-  `defaultTheme`, `defaultMode`, `defaultDensity`, `defaultAnimations`, `grid`, `themes`, `nonce`. It sets
-  attributes on `<html>`, hence `suppressHydrationWarning`.
-- `ThemeSwitcher` is a palette button with a popover; `ThemePicker` is the same picker placed in a page. Besides the
-  mode and the theme it offers **Density** (Compact, Cozy), **Animations** (On, Off, System) and, in a development
-  build only, the **Scale grid** (Off, px, mm); `showMode`, `showDensity`, `showAnimations`, `showGrid` turn them off.
-- `useTheme()` returns `{ theme, mode, resolvedMode, density, animations, motion, grid }` and a setter for each.
-- The choices are saved in `localStorage` (`nx-theme`, `nx-mode`, `nx-density`, `nx-animations`, `nx-grid`) and
-  shared by open tabs.
-
-Without JavaScript, set the attributes yourself: `<html data-nx-theme="nord" data-nx-mode="dark">`.
-Without `data-nx-mode`, the system setting applies. `data-nx-theme` also works on any element, which then
-draws in that theme (the picker's previews use this).
-
-**Density** is `data-nx-density="cozy"` on `<html>`: every control 4px taller (`--nx-control-sm/md/lg` 32/38/44) and
-every list row 6px (`--nx-row` 38), so buttons, fields, table rows and headers, menus, dropdown options and the table's
-footer follow at once. Compact, the default, is the sizes the package always had.
-
-**Animations** come from one attribute too. `ThemeScript` works out `data-nx-motion` (`reduce` or `full`) from the
-visitor's choice and the system's `prefers-reduced-motion`, and keeps it current when the system setting changes;
-every stylesheet reads that attribute, never the media query. So **On** animates on a machine whose operating system
-has animations turned off, **Off** never animates, and **System** (the default) does what the system says. Popups fade
-in and out, and every popover panel (menus, the table's panels, pickers) fades briefly; nothing waits for a fade.
-
-**Scroll bars** have one look everywhere, the design lab's: thin and quiet, with a thumb of the text colour at 22% on
-no track (`Nexus.Base.css` sets `scrollbar-width` and `scrollbar-color` on every element). On Windows, Chrome and Edge
-draw the bar 10px wide and Firefox 8px. Safari has no `scrollbar-color`, so it draws its own thin bar. A component
-that needs another look sets the two properties on its own scroller: the time picker's columns hide the thumb until
-the pointer or the keys are in them. An app overrides the bar the same way, from outside the layers. With forced
-colours on, the system's colours come back.
-
-### How it works
-
-- `Nexus.Themes.css` gives each theme its colors once, as `light-dark(light, dark)`; the page's `color-scheme` picks the side.
-- `Nexus.Tokens.css` holds sizes, spacing, and type, and derives hover colors, soft backgrounds, and the focus ring from the palette.
-- Components use only `--nx-*` variables, so every component follows the theme with no extra code.
-- `npm run check:themes` checks every theme in both modes against WCAG contrast. Run it after changing a color.
-
-### Custom themes
-
-A theme is one CSS block. List it for the script and the picker:
-
-```css
-[data-nx-theme="brand"] {
-  --nx-primary: light-dark(#0f766e, #2dd4bf);        /* the accent as text and lines */
-  --nx-primary-solid: light-dark(#0f766e, #0d7a70);  /* the accent as a fill behind white text: buttons, checks */
-  --nx-primary-text: light-dark(#ffffff, #ffffff);
-  /* …any other --nx-* color: bg, surface, surface-2, surface-hover, border, border-strong,
-     text, text-muted, text-subtle, danger, danger-solid, danger-text, success, warning, info */
-}
-```
-
-```tsx
-const themes = [...NEXUS_THEMES, { id: "brand", name: "Brand", description: "Our colors" }];
-<ThemeScript themes={themes} defaultTheme="brand" />
-<ThemeSwitcher themes={themes} />
-```
-
-All styles sit in `@layer nexus.*`, so an app's own CSS overrides any token or component style without `!important`.
-
-### Quick preferences
-
-Under the theme, the `ThemeSwitcher` panel holds the person's own settings (`PreferencesPicker`, or
-`<ThemeSwitcher preferences={false} />` for the theme alone). Each applies at once to everything on the page, is saved
-on this device, and reaches other open tabs:
-
-| Section | Setting | Saved as | Read by |
-|---|---|---|---|
-| Language and region | Interface language: English, नेपाली | `nx-language` | `useUserPreferences().language` |
-| | Calendar: AD, BS | `nx-date-calendar` | every date component (`useDatePreferences`) |
-| Dates and times | Date picker language: English, नेपाली | `nx-date-script` | every date component |
-| | Clock: 12-hour, 24-hour | `nx-time-format` | every time component |
-| | Display date format | `nx-date-format` | every date component |
-| Numbers | Number scale (the core's `ENumberScales`): International 1,234,567, South Asian 12,34,567 | `nx-number-scale` | `useNumberLocale()` |
-| | Thousands separator: 1,200, 1.200 (decimal comma), 1 200, 1200 | `nx-thousands` | `useNumberLocale()` |
-| Tables | Default page size | `nx-page-size` | every `DataTable` and `Crud` |
-| | A row click opens the record | `nx-row-click` | every `DataTable` and `Crud` |
-
-- **Numbers:** `useNumberLocale()` turns the two number settings into a locale (`numberLocale(scale, separator)`):
-  `en-US` and `en-IN` as they are, any other pair a key such as `"en-IN|.|,"` that `formatNumber`, `parseNumber` and
-  `getNumberSymbols` read. A `NumberBox`, a `Slider` and a table's number cells without a `locale` of their own use it;
-  a number box rewrites what it shows when the setting changes, so a typed value is never read in the wrong marks.
-- **Tables:** once chosen, the page size and the row click go over what a table names itself (`pageSize`,
-  `openOnClick`); a page size picked in a table with a `stateKey` still wins there, and a size the table does not offer
-  is not forced on it. Until chosen (`null`), each table keeps its own.
-- **Interface language** is stored and read through `useUserPreferences()`; the package's own words are English for
-  now, and it does not set `lang` on `<html>` until they are translated (a screen reader would read English in a Nepali
-  voice).
-- `setUserPreferences({ … })` and `readUserPreferences()` (`nexus-shared/client`) change and read them from code, as
-  `setDatePreferences` does the date settings.
-
-## Components
-
-| Component | Import | Notes |
-|---|---|---|
-| `Button` | `nexus-shared` | Variants `primary`, `secondary`, `ghost`, `danger`; sizes `sm`, `md`, `lg`; `icon`, `iconEnd`, `loading`, `block`; `hoverTone` |
-| `TabButtons` | `nexus-shared/client` | Pick one option; sliding indicator; sizes, `tone="primary"`, `labels="selected"` (icons, label on the selected option), `block`, disabled options; `design="list"` for a vertical list with descriptions and badges; `multiple` to pick several, wrapping onto more rows |
-| `SplitButton` | `nexus-shared/client` | A main action with a menu of alternatives; the pick becomes the main button, and `storageKey` remembers it for the next visit |
-| `Menu`, `ContextMenu` | `nexus-shared/client` | A dropdown menu under a button, and a right-click menu: icons, shortcuts, descriptions, `tone="danger"`, links, `kind="radio"` or `"checkbox"` |
-| `Toaster`, `toast` | `nexus-shared/client` | Toast messages from anywhere: `toast.success(title, message)`, `toast.promise`, `toast.loading`, actions, positions; one `<Toaster />` in the layout |
-| `Popup` | `nexus-shared/client` | A modal window on the native dialog, with the buttons of a desktop window: minimize (a bar at the bottom right, content kept), maximize, close; moved by its title bar inside the window; title, description, scrolling body, footer, sizes `xs` to `full`, close reasons |
-| `PopupHost`, `openPopup` | `nexus-shared/client` | Popups opened from code with a handle (`close`, `update`, `minimize`, `maximize`, `restore`, `windowState`, `closed`), one per `key` (replaced or restored); one `<PopupHost />` in the layout, which also shows the minimized popups |
-| `definePopupRules` | `nexus-shared/client` | Rules for popups by key or `prefix-*` pattern, set once: `reopen` (replace or restore), `minimizable`, `maximizable`, `movable`, how it closes, `size`, `defaultWindowState` |
-| `useDraggable`, `makeDraggable`, `startDrag`, `moveWithin`, `clampToBounds` | `nexus-shared/client` | Move any element with the pointer (or the keyboard), kept inside bounds: the window, the parent, an element, or a box; by a handle, along one axis, partly outside; Esc puts it back |
-| `messageBox` | `nexus-shared/client` | `alert`, `confirm`, `prompt`, and `show` with any buttons, each returning a promise |
-| `TextBox` | `nexus-shared/client` | Text input: label designs `standard`, `outlined`, `inbox`; sizes; icons; `prefix`, `suffix`; `clearable`; show password; `showCount`; validation |
-| `TextArea` | `nexus-shared/client` | Multi-line text with the same field features; `autoResize` between `rows` and `maxRows` |
-| `CheckBox`, `Switch` | `nexus-shared/client` | One checkbox or on/off switch: `label`, `description`, `required` (must be checked), `indeterminate`, `readOnly`, `labelPosition` |
-| `CheckBoxGroup` | `nexus-shared/client` | Many choices from `options`: `min`, `max` (disables the rest at the limit), `selectAll`, `columns`, `design="cards"` |
-| `RadioGroup` | `nexus-shared/client` | One choice from `options`: arrow keys, `orientation`, `columns`, `design="cards"` |
-| `Dropdown` | `nexus-shared/client` | One value, or several with `multiple`, from `options` or server pages (`loadOptions`: search, infinite scroll, loaders, Retry); rows as `columns` like a data table (avatar, image, icon, code); saved values the list no longer offers (`selectedOptions`, `resolveOptions`, inactive items) show and cannot be picked again |
-| `Slider`, `RangeSlider` | `nexus-shared/client` | Pick a number or a range: `min`, `max`, `step`, number format with `prefix`/`suffix`, `marks`, `tooltip`, `minDistance`, `onValueCommit` |
-| `NumberBox` | `nexus-shared/client` | Numbers only: `min`, `max`, `decimals`, `fixedDecimals`, `grouping` by `locale`, `prefix`, `suffix`, `stepper`, `clamp`; the same field shell |
-| `DatePicker` | `nexus-shared/client` | Type or pick a date in the English (AD) or Nepali (BS) calendar from the user's settings; `min`, `max`, `isDateDisabled`; the value is always a Gregorian ISO date |
-| `DateRangePicker` | `nexus-shared/client` | A start and an end in one box, picked in a two-month calendar or typed; `startName` and `endName` send two fields; `minDistance`, `maxDistance` in days; booked nights cannot be included |
-| `TimePicker` | `nexus-shared/client` | Type or pick a time on a 12- or 24-hour clock from the user's settings: columns of hours and minutes or `view="list"` slots; `min`, `max` (past midnight too), `step` in seconds, `isTimeDisabled`; the value is always an ISO time |
-| `DateTimePicker` | `nexus-shared/client` | Type or pick a day and a time: each user sees their own local time in their date and time settings, and the value is always the UTC moment; `timeZone` for a place's zone, `min`, `max`, `minTime`, `maxTime`, `step`, `isDateDisabled`, `isTimeDisabled` |
-| `Calendar` | `nexus-shared/client` | The month grid on its own: single or `mode="range"`, `months={2}` side by side, month and year menus, arrow keys, `renderDay` for event markers, `weekStart` |
-| `useDatePreferences`, `setDatePreferences` | `nexus-shared/client` | The user's calendar, format, script, and time format, saved in local storage and followed by every date and time component |
-| `Form` | `nexus-shared/client` | A list of input params (`InputParams[]`) on a 12-column grid (`span`), with the values in a store outside React; `onFieldChange` for derived values, `validate` for rules across inputs, `draftKey` for unsaved changes that survive a reload, `loading` (the inputs disabled until the values land) |
-| `SubmitForm` | `nexus-shared/client` | A `Form` that checks every value on Save and focuses the first problem, then runs `onSubmit` once at a time; a status line with links to what needs attention; Save, Cancel (asks first), Reset; Ctrl+S |
-| `ApiForm` | `nexus-shared/client` | A `SubmitForm` that sends to an API (an endpoint such as `ROOMS.update`, `{ url, method }`, or the app's own client), loads the record first (`loadValue`), and shows the server's messages on their inputs: Nexus responses and ASP.NET Core problem details |
-| `FormButtons` | `nexus-shared/client` | A form's status line and buttons on their own, such as in a popup's footer |
-| `useForm`, `useFormValue`, `useFormValues`, `useFormStatus` | `nexus-shared/client` | A store for the page to hold, and hooks that render again when a value, any value, or the status changes |
-| `FormStore` | `nexus-shared` | The store and the form's handle: `getValue`, `getChanges`, `set`, `load` (with `keepChanged`), `reset`, `validate`, `setErrors`, `focus`, `submit` |
-| `DataTable`, `useTable` | `nexus-shared/client` | Rows with a search (rows per page inside it), sorting by column, pages, a selection with one split button of actions over the headings, icon buttons and a menu per row, columns the user orders, resizes, pins, and hides, a band of headings over the columns that belong together (`group`), an options menu (filters from `filterInputs`, CSV, print, import), and loading, empty, and failed states; rows given, loaded once, or a page per query from a server; page size, sort, and the columns remembered with `stateKey` |
-| `TableStore` | `nexus-shared` | The table's state and handle, outside React: `reload`, `upsert`, `patch`, `remove`, `select`, `getSelected`, `setSearch`, `setFilters`, `setSort`, `setPage` |
-| `Crud` | `nexus-shared/client` | A module's records in one component: a controller's endpoints, the table's columns, and the form's input params in; the lists (all, flagged, trash, deleted) and actions the user may use, the records the user pinned above the list, Add and Edit popups on `ApiForm`, details, actions on one record or many, and a cache of lists while the page is open |
-| `Permissions`, `NexusPermissions`, `definePermissions`, `canCall` | `nexus-shared` | May the user call this endpoint? The app registers its rules once; `NexusPermissions` reads the Nexus backend's access actions. Everything is allowed until then |
-| `CrudBackend`, `NexusCrudBackend`, `defineCrudBackend` | `nexus-shared` | How a CRUD talks to a backend beyond its endpoints: page requests and answers, mass action bodies, flag and pin marks. Nexus's by default |
-| `configureCrud`, `getCrudSettings` | `nexus-shared` | What every CRUD in the app follows: how many records a user may pin (100 by default) |
-| `queryRows`, `filterRequest`, `formatCellText`, `sortRows`, `pageButtons`, `CrudCache`, `crudRowActions` | `nexus-shared` | Pure helpers behind the table and the CRUD: search, filter, sort, and page rows as the table does, the filters in a server's names, a value as its cell writes it, the page buttons, the cache, and which actions a list offers |
-| `readApiResponse`, `readErrorMessages`, `sendApiRequest`, `matchFieldErrors`, `matchInputName`, `formErrorsFromResult` | `nexus-shared` | Pure helpers behind the API form: read an answer as success or failure, every problem it carries as one list, send a URL as it is, match server field names to inputs, and turn a failed answer into what a form shows |
-| `api`, `apiOptionsLoader`, `configureApi` | `nexus-shared/client` | API calls from the browser, through the app's proxy or straight to a module: toasts worded by the message builder, `api.confirm` to ask first, one request for the same GET at once; a dropdown's `loadOptions` from a pagination endpoint |
-| `serverApi`, `configureServerApi`, `createApiProxy` | `nexus-shared/server` | API calls from the server, straight to each module's root, with the user's token and Next.js caching; the proxy route the browser calls |
-| `ApiModules`, `NexusApiModules`, `defineApiModules`, `ApiRegister` | `nexus-shared` | An app's API modules: its own module enum (named once in `ApiRegister`, so endpoints take only those), where each root is, and the proxy on or off. Extend `ApiModules` for another backend |
-| `apiController`, `apiEndpoint`, `unwrapApiResult` | `nexus-shared` | Endpoints defined once by module: a controller's standard actions (`NormalListing`, `Detail/{id}`, `Create`, `Update`, `Delete/{id}`, each list's `lists.trash` and `pages.trash`, …); an answer's result, or an `ApiError` |
-| `messages`, `buildMessage`, `configureMessages` | `nexus-shared` | Every success, failure, reason, loading, question, and button text from one table: "3 rooms deleted.", "You do not have permission to delete Room 204."; reworded all at once |
-| `createApiClient` | `nexus-shared` | The engine behind `api` and `serverApi`, for an API of another shape |
-| `Field` | `nexus-shared` | The frame of every input (label, box, icons, hint or error), for building custom inputs |
-| `validateText`, `TEXT_PATTERNS` | `nexus-shared` | Pure text validation and common patterns with their messages |
-| `validateCheck`, `validateSelection` | `nexus-shared` | Pure checks for a checkbox and for chosen values (`required`, `min`, `max`) |
-| `validateNumber`, `formatNumber`, `parseNumber` | `nexus-shared` | Pure number validation, and number text in any locale (`roundDecimal`, `stepNumber` too) |
-| `formatDate`, `parseDateText`, `toIsoDate`, `validateDate` | `nexus-shared` | Pure date helpers: ISO dates in and out, either calendar, any format, Devanagari digits; `toCalendar` and `fromCalendar` convert AD and BS |
-| `formatDateRange`, `parseDateRangeText`, `toDateRange`, `validateDateRange` | `nexus-shared` | The same for a range: "2026-09-17 – 2026-09-24" in and out, typed with a dash, an arrow, or "to"; rules on both ends and on the days between |
-| `filterItems`, `matchesSearch`, `indexItems`, `optionKey`, `initials` | `nexus-shared` | Pure helpers behind the dropdown: search every word with or without accents, index items by value, compare ids from APIs and forms, and initials for avatars |
-| `formatTime`, `parseTimeText`, `toIsoTime`, `validateTime` | `nexus-shared` | Pure time helpers: ISO times in and out, 12- or 24-hour formats, Devanagari digits, typed text on either clock; `addMinutes`, `isTimeInRange`, `listTimeSlots` |
-| `toUtcDateTime`, `toLocalDateTime`, `fromLocalDateTime`, `formatDateTime`, `parseDateTimeText`, `validateDateTime` | `nexus-shared` | Pure date-time helpers: UTC values in and out, the date and time a moment shows in any IANA zone (daylight saving included), typed text in both calendars; `describeTimeZone`, `getBrowserTimeZone` |
-| `ThemeScript` | `nexus-shared` | Applies the saved theme, mode, density and animations (and the scale grid in development) before paint; goes in `<head>` |
-| `ThemeSwitcher` | `nexus-shared/client` | Palette button with the theme picker in a popover: mode, theme, density, animations, and the scale grid in development |
-| `ThemePicker` | `nexus-shared/client` | Mode control and theme cards with live previews |
-
-### Tab buttons
-
-```tsx
-import { TabButtons } from "nexus-shared/client";
-
-<TabButtons
-  aria-label="View"
-  value={view}
-  onChange={setView}
-  options={[
-    { value: "grid", label: "Grid", icon: <InlineIcon icon={iconLayoutGrid} /> },
-    { value: "list", label: "List", icon: <InlineIcon icon={iconList} /> },
-  ]}
-/>
-```
-
-- An indicator slides to the selected option. In light mode the track is a soft tint with no frame and the indicator
-  is lifted by a shadow; in dark mode the indicator is lighter than the track, with a visible edge. The selected icon
-  takes the primary color, so the choice is clear in every theme.
-- `size` (`sm`, `md`, `lg`), `tone="primary"` for a solid primary indicator, `block` to fill the width, `disabled` per option.
-- `labels="selected"`: icons only, and the selected option grows to show its label. Every option needs an icon;
-  hidden labels are still read by screen readers and shown as tooltips.
-- `design="list"`: the options stacked as full-width rows, for settings pages and side panels. Each row takes an
-  `icon`, a `description` on a second line, and a `badge` (a count) at the end. The selected row is tinted, marked
-  by a bar at its start, and its label turns bold; `tone="primary"` tints it with the primary color. ↑ and ↓ move
-  the selection. The nav design is the old project's `nav-tabs`, this one its `list-tabs`.
-- `multiple`: several at once. `value` is an array and `onChange` hands back the chosen values in option order.
-  Each chosen option is raised as the one choice's indicator is, the options wrap onto more rows when they do not
-  fit (never narrower than tall, so single letters line up), and on a touch screen each grows to a medium control's
-  height. They are checkboxes: Tab moves between them and Space toggles one.
-- Native radio buttons: arrow keys move the selection, and `name` makes it part of a form. Needs `aria-label` or `aria-labelledby`.
-  `form` sets the form the choice belongs to, as in HTML; an id that matches no form keeps a switch that is not a
-  value (the Markdown editor's views) out of the form around it.
-- For choosing a value. For switching page panels, use tabs with panels (planned).
-
-### Split button
-
-```tsx
-import { SplitButton } from "nexus-shared/client";
-
-<SplitButton storageKey="pull-request" onAction={value => create(value)} options={[
-  { value: "create", label: "Create pull request", description: "Open a pull request that is ready for review" },
-  { value: "draft", label: "Create draft pull request", description: "Cannot be merged until marked ready for review" },
-]} />
-```
-
-- The main button runs the chosen action; the arrow opens the alternatives as a radio menu. Picking one makes it the
-  main button, and with `storageKey` the browser remembers it (`localStorage`, `nx-split:<key>`), so the next visit
-  starts with it. `runOnSelect` also runs the pick at once, for Save / Save and close.
-- `variant`, `size`, `loading`, `disabled`, `block` as `Button`; `type="submit"` with `name` submits a form and sends
-  the chosen value; `value` and `onValueChange` for a controlled choice; `align` and `menuLabel` for the menu.
-
-### Menus
-
-```tsx
-import { ContextMenu, Menu } from "nexus-shared/client";
-
-<Menu items={[
-  { value: "edit", label: "Edit", icon: <InlineIcon icon={iconPencil} />, shortcut: "Ctrl+E" },
-  { separator: true },
-  { value: "delete", label: "Delete", icon: <InlineIcon icon={iconTrash} />, tone: "danger" },
-]} onSelect={value => run(value)}>
-  <Button iconEnd={<InlineIcon icon={iconChevronDown} />}>Actions</Button>
-</Menu>
-
-<ContextMenu items={rowItems} onSelect={value => run(value, row)}>
-  <table>…</table>
-</ContextMenu>
-```
-
-- **Native popovers.** The list is a `[popover]` element: it sits above everything, closes with Esc or a click
-  outside, and needs no library. It opens under its button (above it when there is no room), lined up with the
-  button's `align="start"` or `"end"` edge, and follows the page as it scrolls.
-- **Items are params:** `{ value, label, description?, icon?, shortcut?, tone?: "danger", disabled?, href?, target?, checked?, title? }`,
-  plus `{ separator: true }` and `{ heading }`. An item with `href` is a link. The trigger is any element that
-  renders a button and passes its props on, such as `Button`.
-- `kind="radio"` or `"checkbox"` adds a check column and `aria-checked`; `closeOnSelect={false}` keeps a checkbox
-  menu open while options are toggled.
-- **Keys:** arrows move between items (wrapping, skipping disabled ones), Home and End jump, a letter jumps to the
-  next item starting with it, Enter or Space chooses, Esc closes and returns focus to the button, Tab closes and
-  moves on. Focus follows a moving pointer, so the keys carry on from the hovered item.
-- `ContextMenu` opens at the pointer on right-click, or under the focused element on Shift+F10. Its wrapper takes no
-  space (`display: contents`), so wrap a table once and note the clicked row in the row's own `onContextMenu`.
-- A menu opens below its button, or above it when it fits only there, or on the side with more room when it fits on
-  neither, and is never taller than that room: its items scroll inside it, the scroll bar against the panel's right
-  wall. It opens scrolled to the top, and a hovered item never scrolls the list.
-- `placeUnderAnchor`, `placeAtPoint`, and `followAnchor` (`nexus-shared/client`) place custom popovers the same way, and
-  `showPanel` opens one with its scroller at the top. A panel (`.nx-popover`) that marks its scrolling part
-  `.nx-popover__scroll` is capped to the room it was placed in and gets the scroll bar on its wall; set its padding with
-  `--nx-popover-pad`. `usePopoverPanel` is a panel a menu item opens under a button, as the table's Filters and Columns
-  open.
-
-### Toast messages
-
-```tsx
-import { Toaster, toast } from "nexus-shared/client";
-
-// Once, in the root layout
-<Toaster position="top-right" />
-
-// Anywhere: components, services, fetch helpers
-toast.success("Booking confirmed", "Room 204, 3 nights");
-toast.error("Could not save", { message: error.message, action: { label: "Retry", onClick: save } });
-toast.promise(saveBooking(), { loading: "Saving…", success: "Saved", error: e => `Not saved: ${e.message}` });
-```
-
-- `toast(title, options?)`, `toast.info`, `.success`, `.warning`, `.error`, `.loading` (spinner, no timer), and
-  `.promise`. Options: `message`, `duration` (default 5000 ms, 0 keeps it; pauses while hovered or focused), `action`,
-  `closable`, `icon`, `position`, `onClose`, and `id` to update a toast in place. `toast.dismiss(id?)` closes one or all.
-- Each toast is a native popover of its own, so it sits above open dialogs; the newest is nearest the edge, and at
-  most `max` (default 5) show per position. Warnings and errors use `role="alert"`, the rest `role="status"`.
-
-### Popup
-
-```tsx
-import { Popup, definePopupRules, openPopup } from "nexus-shared/client";
-
-<Popup open={open} onClose={() => setOpen(false)} title="Edit booking" description="NX-2048 · Room 204"
-  footer={<><Button onClick={() => setOpen(false)}>Cancel</Button><Button type="submit" form="booking" variant="primary">Save</Button></>}>
-  <form id="booking" onSubmit={save}>…</form>
-</Popup>
-
-// From code, with a handle; needs <PopupHost /> in the layout. Never two popups with one key: opening the key again
-// replaces its popup (a fresh one), or with reopen: "restore" brings it back as it was.
-const popup = openPopup({ key: "room-edit-204", reopen: "restore", title: "Room 204", content: <RoomDetails id={204} />, footer: p => <Button onClick={() => p.close()}>Close</Button> });
-popup.minimize(); popup.restore(); popup.maximize();
-await popup.closed;
-
-// Rules by key, once, in a client module; options given to openPopup win over them
-definePopupRules({
-  "room-new": { reopen: "replace" },                  // Add: a fresh form every time (the default)
-  "room-edit-*": { reopen: "restore" },               // Edit: back as it was, with what was typed
-  "night-report": { minimizable: false, maximizable: false, movable: false },
-});
-
-// The page in charge of the window state
-<Popup open={open} windowState={state} onWindowStateChange={setState} … />
-```
-
-- Built on the native `<dialog>` shown modally: above everything, the page behind dimmed and locked (without a layout
-  shift), Tab kept inside, focus returned on close. `onClose(reason)` says whether the close button, Esc, the
-  backdrop, or code asked; the page decides by setting `open`. `closable`, `closeOnEscape`, `closeOnBackdrop` turn
-  those off for a popup that must be answered.
-- `size`: `xs` 360, `sm` 440, `md` 560, `lg` 720, `xl` 960, `full`. The body scrolls while the title and footer
-  stay; `flush` removes the body padding for tables. `initialFocus` picks the first focused element (default: the
-  first control in the body or footer). The content mounts only while open, so forms start fresh.
-- Popups open other popups and message boxes above themselves; Esc closes the top one.
-- A **title bar** like a desktop window's: 32px high (40px on touch screens), the icon, the title, and the description
-  on one line (cut with …), and the window buttons filling its top right corner, 46 x 32 each: **minimize**,
-  **maximize** (restore down when maximized), **close** (red on hover). `variant="dialog"` gives the larger heading
-  instead (the icon in a circle, the description under the title), which message boxes use. `minimizable` (default: when `closable`, so a popup that must be answered cannot be put aside),
-  `maximizable` and `movable` (default true); message boxes have only close.
-- **Minimized**, the dialog closes so the page can be used, and a bar waits at the bottom right with the popup's icon and
-  title; its content stays mounted, so typed text, scroll, and the focused field are there when the bar brings it back
-  (maximized again if it was). Several stack behind the newest with a count that opens the whole list (Esc or a press
-  elsewhere closes it). An open popup's backdrop covers the dock. `<PopupHost />` renders the dock; without a host
-  there is no minimize button. Bottom-right toasts stack above it (`--nx-dock-space`).
-- **Maximized**, it fills the window edge to edge; a double-click on the title bar does the same, and restore down puts
-  it back where it was.
-- **Moved** by its title bar (not its buttons), kept inside the window, pulled back in when the window shrinks; Esc
-  during a drag puts it back; dragging a maximized popup restores it under the pointer, as desktop windows do. Each
-  opening starts centered in `defaultWindowState`.
-- **Opened again** while it is still open or minimized, a popup never doubles up. `openPopup` with a `key` whose popup
-  is there closes that popup (`onClose` and `closed` say `replaced`) and opens a fresh one: `reopen: "replace"`, the
-  default, right for an Add form, so Add, minimize, Add again cannot pile up popups. `reopen: "restore"` brings the
-  old one back as it was and returns its handle, right for editing one record. A page popup opens again through the
-  button that opened it, with the same `reopen` choice. Popups without a key are separate every time.
-- **Asking before a close**: `openPopup({ beforeClose })` runs when the user closes the popup (its close button, Esc,
-  the backdrop, or its bar on the dock); return `false`, or a promise of it, to keep it open, such as after
-  `confirmDiscard(form)` asked "Discard your changes?". Closing from code does not ask.
-- **Rules by key**: `definePopupRules({ "booking-new": {…}, "booking-edit-*": {…} })` sets `reopen`, `minimizable`,
-  `maximizable`, `movable`, `closable`, `closeOnEscape`, `closeOnBackdrop`, `size`, and `defaultWindowState` for every
-  `openPopup` with that key. A name ending in `*` matches keys that start with the rest (`*` alone, every key); all
-  matching rules apply, an exact key over a pattern and a longer pattern over a shorter one; options given to
-  `openPopup` win. It returns a function that removes the rules; `popupRuleFor(key)` shows what a key gets.
-- With motion, minimize flies to the dock and maximize grows from the old box; with reduced motion, both happen in the
-  same frame.
-
-### Drag helpers
-
-```tsx
-import { clampToBounds, makeDraggable, moveWithin, useDraggable, viewportBounds } from "nexus-shared/client";
-
-useDraggable(cardRef, { bounds: "parent" }); // the card moves, kept inside its positioned parent
-useDraggable(barRef, { target: () => cardRef.current, bounds: "parent", axis: "x", keepVisible: 40 });
-const stop = makeDraggable(titleBar, { target: panel, bounds: document.querySelector(".board") }); // without React
-moveWithin(card, { x: 10, y: 0 }, { bounds: "parent" }); // the keyboard way
-clampToBounds({ left: -20, top: 40, width: 300, height: 200 }, viewportBounds()); // { x: 0, y: 40 }
-```
-
-- The popup's title bar is built on these; any component can use them. `bounds`: `viewport` (default), `parent`,
-  an element (inside its borders), a box, a function, or `null`. `margin`, `keepVisible` (how much must stay
-  inside when it may partly leave), `axis`, `threshold` (default 3 px, so clicks stay clicks), `cancel` (controls in
-  the handle that do not drag).
-- The position is an offset from the element's place in the layout, written to CSS `translate` by default, or to CSS
-  variables (`cssVariablePosition`), or anywhere through `position: { get, set }`, so a move never shifts the layout.
-- `onStart` may cancel or change the target first; `onEnd` says whether Esc cancelled. A drag selects no text, and
-  the click that ends it does not reach what lies under the pointer. The handle needs `touch-action: none`
-  (`makeDraggable` and `useDraggable` set it).
-
-### Message box
-
-```tsx
-import { messageBox } from "nexus-shared/client";
-
-if (await messageBox.confirm({ title: "Delete booking NX-2048?", message: "This cannot be undone.", tone: "danger", confirmLabel: "Delete" })) …
-await messageBox.alert({ title: "Saved", tone: "success" });
-const name = await messageBox.prompt({ title: "Rename the room", label: "Name", defaultValue: room.name });
-const choice = await messageBox.show({ title: "Unsaved changes", tone: "warning", buttons: [{ value: "discard", label: "Don't save" }, { value: "save", label: "Save" }] });
-```
-
-- Small popups through `<PopupHost />`, the tone in the icon: `info` (alert default), `question` (confirm default),
-  `success`, `warning`, `danger`, or `neutral` for none. A danger box makes the last button red and focuses the first
-  one, so Enter cannot delete by accident.
-- `confirm` resolves `false` and `show` resolves `null` when the box is dismissed with Esc, the close button, or a
-  click outside; `prompt` resolves `null` when cancelled and refuses an empty answer while `required` (the default).
-
-### Button hover tones
-
-`hoverTone` keeps a `secondary` or `ghost` button neutral until it is hovered or focused from the keyboard, then
-colors its border, a light background, and its text. Tones: `primary`, `danger`, `success`, `warning`, `info`.
-Good for rows of actions, where full-color buttons would be too loud:
-
-```tsx
-<Button hoverTone="danger" icon={<InlineIcon icon={iconTrash} />}>Delete</Button>
-<Button variant="ghost" size="sm" hoverTone="primary" aria-label="Edit" icon={<InlineIcon icon={iconPencil} />} />
-```
-
-Every tone meets WCAG AA contrast on its light background in all themes.
-
-### Text box
-
-```tsx
-import { TEXT_PATTERNS } from "nexus-shared";
-import { TextBox, TextArea } from "nexus-shared/client";
-
-<form onSubmit={save}>
-  <TextBox name="email" type="email" label="Email" required pattern={TEXT_PATTERNS.email} icon={<InlineIcon icon={iconMail} />} />
-  <TextBox name="password" type="password" label="Password" required minLength={8} />
-  <TextArea name="notes" label="Notes" maxLength={500} showCount autoResize />
-  <Button type="submit" variant="primary">Save</Button>
-</form>
-```
-
-- **Uncontrolled by default**, so typing re-renders nothing. `onValueChange(value)` reports each change; `value` makes it controlled.
-- **Validation:** `required`, `minLength`, `maxLength`, `pattern` (a `TEXT_PATTERNS` entry carries its own message), and
-  `validate(value)` for custom rules. Messages show after a field is left with text in it (`validateOn`: `blur`, `change`,
-  `submit`). Inside a `<form>`, an invalid field blocks submit, every message shows, and the first invalid field takes focus.
-  `error` shows a message from outside, such as the server.
-- **Read-only says why.** Every input with `readOnly` shows a lock, and a short note for 2.5 seconds when someone tries
-  to change it anyway, so a click that does nothing does not look like a bug. The value is still sent with a form, and
-  selecting and copying text work as usual. Esc, leaving the field, or the timeout hide the note; `readOnlyMessage`
-  changes its text.
-
-  | Input | Lock | Tries that show the note | Default note |
-  |---|---|---|---|
-  | `TextBox`, `TextArea` | End of the box | A click, typing, Backspace, Delete, Ctrl+V, Ctrl+X (and Enter in a text area) | Read-only: this field cannot be changed. |
-  | `NumberBox` | In place of the − and + buttons | The same, and ↑ ↓ Page Up Page Down | Read-only: this number cannot be changed. |
-  | `DatePicker`, `DateRangePicker` | In place of the calendar button | The same as a text box, and ↓ | Read-only: this date (these dates) cannot be changed. |
-  | `TimePicker` | In place of the clock button | The same as a text box, and ↓ | Read-only: this time cannot be changed. |
-  | `DateTimePicker` | In place of the calendar and clock button | The same as a text box, and ↓ | Read-only: this date and time cannot be changed. |
-  | `Dropdown` | In place of the list button; chips lose their remove buttons | A click on the box or a chip, a typed key, ↓ or ↑ | Read-only: this choice (these choices) cannot be changed. |
-  | `CheckBox`, `Switch` | After the label | A click or Space | Read-only: this option (this setting) cannot be changed. |
-  | `CheckBoxGroup`, `RadioGroup` | After the group label | A click, Space, or an arrow key, under that option | Read-only: these options (this choice) cannot be changed. |
-  | `Slider`, `RangeSlider` | After the label | A press on the track or a mark, the arrow keys, Page Up/Down, Home, End | Read-only: this value (this range) cannot be changed. |
-
-  Nothing renders until an attempt, and an attempt re-renders only the note, so read-only forms of any size cost
-  nothing extra. `useReadOnlyNotice` gives a custom control the same lock and note.
-- **Props are params:** plain, named like HTML attributes, and serializable, so forms and CRUD pages can describe
-  fields as objects. Design notes for inputs, forms, and CRUD: [src/Components/Inputs/README.md](src/Components/Inputs/README.md).
-
-### Number box
-
-```tsx
-import { NumberBox } from "nexus-shared/client";
-
-<NumberBox name="nights" label="Nights" stepper="split" required min={1} max={30} defaultValue={1} />
-<NumberBox name="rate" label="Rate per night" prefix="Rs" required min={500} decimals={2} fixedDecimals grouping locale="en-IN" />
-<NumberBox name="discount" label="Discount" suffix="%" stepper min={0} max={50} step={5} />
-```
-
-- **Only a number gets in.** Typing accepts digits, one decimal separator, and a minus sign when `min` is below 0 (or
-  not set). `decimals` stops typing after that many decimals; pasted text such as "Rs 1,250.50" keeps its number, and
-  text with no single clear number is ignored rather than guessed at.
-- **Formats by locale:** `grouping` shows 12,50,000.00 (`en-IN`) or 1.250.000,00 (`de-DE`) while the box is not
-  being edited; separators come off on focus. Without a `locale`, the box follows the person's Number scale and
-  Thousands separator (`useNumberLocale`, see Quick preferences), which is `en-US` until they choose, so the server
-  renders that and the browser takes the saved choice right after hydration.
-  Inside a `<form>`, a grouped box sends the plain number through a hidden input with its `name`.
-- **Steps:** ↑ and ↓ (Shift or Page Up/Down for ten), and `stepper` buttons that repeat while held. Values move along
-  the grid of `step` from `min` and stay within the limits.
-- **Values:** `onValueChange(value)` gets a `number`, or `null` when empty; `validate(value)` too. `clamp` moves an
-  out-of-range value to the nearest limit on blur instead of showing a message.
-- `npm run test:numbers` checks the number helpers (formatting, parsing, paste, rounding, stepping, messages).
-
-### Checkbox and radio
-
-```tsx
-import { CheckBox, CheckBoxGroup, RadioGroup, Switch } from "nexus-shared/client";
-
-<RadioGroup name="roomType" label="Room type" required design="cards" columns={3} options={roomTypes} />
-<CheckBoxGroup name="amenityIds" label="Amenities" columns={3} selectAll options={amenities.map(a => ({ value: a.id, label: a.name }))} />
-<Switch name="breakfast" label="Breakfast included" labelPosition="start" />
-<CheckBox name="terms" label="I accept the booking terms" required />
-```
-
-- **Native inputs, drawn with CSS.** Each option is one `<input>`, so forms, arrow keys (radios), and screen readers
-  work as usual. Box edges use the subtle text color, which meets 3:1 contrast on panels in every theme.
-- **Options are params:** `{ value, label, description?, icon?, disabled? }`. Values can be strings or numbers and
-  come back from `onValueChange` with their type.
-- **Limits:** `required`, `min`, `max`, `validate`. At `max` a checkbox group disables the other options and shows a
-  count. Messages follow the text box: after leaving a changed group, or on submit, where the first invalid option takes focus.
-- **Fast:** uncontrolled by default, so clicking re-renders nothing; 10,000 checkboxes mount in 0.5 to 0.7 s
-  in the development build.
-
-### Slider
-
-```tsx
-import { RangeSlider, Slider } from "nexus-shared/client";
-
-<Slider name="discount" label="Discount" max={50} suffix="%" defaultValue={10} />
-<RangeSlider name="price" label="Price per night" min={1000} max={30000} step={500} minDistance={1000}
-  prefix="Rs " grouping locale="en-IN" onValueCommit={([from, to]) => loadRooms(from, to)} />
-```
-
-- **Native range inputs** under a drawn track, so arrow keys, Page Up/Down, Home/End, touch, and screen readers work.
-  Each thumb announces its formatted value (`aria-valuetext`).
-- **Values read like a number box:** `prefix`, `suffix`, `decimals`, `grouping`, `locale`, or a `format` function.
-- **`onValueChange`** follows every step; **`onValueCommit`** fires once when a thumb is released or a key step ends,
-  the moment to call an API from a filter.
-- **Range:** two thumbs that never cross and keep `minDistance` apart; a click on the track moves the nearer thumb.
-  A form receives two values under the name.
-- **Marks** label points under the track and move the thumb when clicked; **`tooltip`** shows the value above the thumb.
-- Dragging writes the fill and the text straight to the DOM, so nothing re-renders.
-
-### Date picker and date range picker
-
-```tsx
-import { todayIsoDate } from "nexus-shared";
-import { Calendar, DatePicker, DateRangePicker, setDatePreferences } from "nexus-shared/client";
-
-<DatePicker name="checkIn" label="Check-in" required min={todayIsoDate()} onValueChange={iso => …} />
-<DatePicker name="fiscalYearStart" label="Fiscal year start" calendar="bs" format="YYYY/MM/DD" />
-<DateRangePicker startName="checkIn" endName="checkOut" label="Stay" required min={todayIsoDate()} minDistance={1} maxDistance={30} />
-<Calendar mode="range" months={2} range={range} onRangeChange={setRange} min={todayIsoDate()} />
-
-// A settings page
-setDatePreferences({ calendar: "bs", format: "D MMMM YYYY", script: "devanagari" });
-```
-
-- **The value is a day, not a time.** An ISO date `"2026-09-17"` in the Gregorian calendar, whatever calendar is
-  shown: what a form sends (through a hidden input with the field's `name`), what an API stores (`DateOnly`), and
-  what means the same day in every time zone. `toIsoDate` reads a `Date` in local time and an ISO date-time with a
-  zone as the local day of that instant; `isoDateToDate(iso)` gives UTC midnight, `isoDateToDate(iso, "local")` local midnight.
-- **English or Nepali from the user's settings.** `useDatePreferences` reads `nx-date-calendar` (`ad` or `bs`),
-  `nx-date-format`, and `nx-date-script` (`latin` or `devanagari`) from local storage, with the English calendar in
-  `YYYY-MM-DD` as the default; `setDatePreferences` changes every date component on the page, and other tabs follow.
-  A box can fix its own `calendar`, `format`, or `script`.
-- **Formats** use the tokens `YYYY` `YY` `MMMM` `MMM` `MM` `M` `DD` `D` `dddd` `ddd`. Typing follows the format's
-  order and is lenient: `17/9/2026`, `Sep 17, 2026`, `1 asoj 2083`, `२०८३-०६-०१`; a four-digit number is the year wherever it stands.
-- **Bikram Sambat** covers BS 1975 to 2100 (AD 1918 to 2044), as the majority of five published tables
-  (`NepaliCalendar.ts`), converted through day numbers with no `Date` objects. `npm run test:dates` checks known
-  dates and round-trips every day.
-- **DateRangePicker** holds a start and an end in one box, written as "2026-09-17 – 2026-09-24" in the user's
-  format. Pick the start and then the end in a calendar of two months (one when the window is narrow), with the
-  days between lit as the pointer moves, or type both dates around a dash, an arrow, or "to". The values are two
-  ISO dates: `onValueChange` gives `[start, end]` (`null` for an end not chosen yet), and a form sends `startName`
-  and `endName` as two fields, or both under `name`. Rules: `required`, `min`, `max`, `minDistance` and
-  `maxDistance` (days from start to end, the nights of a stay), and `isDateDisabled`, which also refuses a range
-  that includes such a day (a booked night). `validateDateRange` is the pure check behind it.
-- **Read-only** boxes have no calendar: a lock sits where the calendar button was, and a click, a typed key, or ↓
-  shows a note under the box, as in every read-only input (see [Text box](#text-box)).
-- **Calendar** is the pickers' panel and a component of its own: month and year menus, arrow keys (Page Up and Page
-  Down for months, with Shift for years), `min`, `max`, `isDateDisabled`, `weekStart`, `weekendDays` (Saturday is
-  red in the Nepali calendar), `mode="range"` with a live preview, `months={2}` side by side (a page passes 1 on
-  a phone; the calendar does not measure), `month` and `onMonthChange` to load a month's events, and `renderDay`
-  to draw markers in a cell.
-
-### Time picker
-
-```tsx
-import { TimePicker, setDatePreferences } from "nexus-shared/client";
-
-<TimePicker name="arrival" label="Arrival" required min="14:00" max="22:00" step={1800} view="list" onValueChange={iso => …} />
-<TimePicker name="shiftStart" label="Shift start" min="22:00" max="06:00" format="HH:mm" />
-<TimePicker name="spa" label="Spa slot" view="list" step={1800} isTimeDisabled={iso => booked.has(iso)} />
-
-// A settings page
-setDatePreferences({ timeFormat: "HH:mm" });
-```
-
-- **The value is a time of day, not an instant.** An ISO time on a 24-hour clock, `"14:30"` (`"14:30:15"` when
-  `step` has seconds), with no date and no zone: what a form sends through a hidden input with the field's `name`,
-  and what a .NET `TimeOnly` stores. `toIsoTime` reads `"9:05"`, `"14:30:00.000"`, a `Date` (its local time), and an
-  ISO date-time (with a zone, the local time of that instant; without one, its time part).
-- **12 or 24 hours from the user's settings.** `nx-time-format` in local storage, next to the date settings, holds
-  a format of tokens `HH` `H` `hh` `h` `mm` `m` `ss` `s` `A` `a`; the default is `hh:mm A` (02:30 PM).
-  `useDatePreferences` returns it as `timeFormat`, and `setDatePreferences({ timeFormat })` changes every time picker
-  on the page. Nepali dates in Devanagari bring Nepali digits and पूर्वाह्न/अपराह्न. A box can fix its own `format` or `script`.
-- **Typing** works on either clock: `2:30 pm`, `2.30p`, `230pm`, `14:30`, `1430`, `9`, `१४:३०`. Without AM or PM the
-  hours are read on a 24-hour clock. Leaving the box writes the time in the format.
-- **Columns** (the default) show hours, minutes, seconds when the step needs them, and AM/PM; the chosen items line
-  up on the middle row, a pick in any column changes the time at once, and ↑ ↓ ← → Home End Page Up/Down move through
-  them. **`view="list"`** shows one slot per `step` (every 30 minutes for steps under 5 minutes); a click or Enter
-  picks and closes.
-- **Rules:** `required`, `min` and `max` (with `max` earlier than `min` the range runs past midnight, 22:00 to 06:00),
-  `step` in seconds counted from midnight as in HTML, `isTimeDisabled` for booked slots, and `validate`. Items outside
-  the rules are dimmed in the panel; a typed time outside them gets a message such as "Arrival must be in steps of 30
-  minutes, like 02:00 PM or 02:30 PM." `validateTime` is the pure check behind it. `npm run test:times` checks the helpers.
-- **Read-only** boxes have no panel: a lock sits where the clock button was, as in every read-only input.
-
-### Date and time picker
-
-```tsx
-import { DateTimePicker } from "nexus-shared/client";
-
-<DateTimePicker name="pickupAt" label="Airport pickup" required min={new Date()} step={900} minTime="05:00" maxTime="23:00" />
-<DateTimePicker name="checkInAt" label="Check-in" timeZone="Asia/Kathmandu" defaultTime="14:00" />
-<DateTimePicker name="spaAt" label="Spa slot" view="list" step={1800} isTimeDisabled={(time, date) => booked.has(`${date} ${time}`)} />
-```
-
-- **The value is a moment, in UTC.** `"2026-09-17T08:45:00.000Z"`, the shape `toISOString` writes, is what the hidden
-  input sends and `onValueChange` gives, whatever the user sees; the same moment is 02:30 PM in Kathmandu and 04:45 AM
-  in New York, so no time zone can move a saved value. Store it as UTC: a .NET `DateTimeOffset`, or a `DateTime` of
-  kind `Utc`. For a day with no time use `DatePicker`; for a time of day with no date, `TimePicker`.
-- **Values in** (`toUtcDateTime`): an ISO date-time with `Z` or an offset is that moment; one **without a zone is read
-  as UTC**, the way a UTC `DateTime` loaded from a database often arrives without its `Z`; a date alone is the first
-  moment of that day where the user is; a `Date` or milliseconds are that moment. .NET's seven digits of fractions are read.
-- **Shown in the user's zone and settings.** The browser's time zone, and the date (`nx-date-calendar`,
-  `nx-date-format`, `nx-date-script`) and time (`nx-time-format`) settings of the other pickers: "2026-09-17 02:30 PM",
-  or "२०८३-०६-०१ ०२:३० अपराह्न". The panel names the zone ("Kathmandu · UTC+05:45"). `timeZone` fixes a zone, such as a
-  hotel's, and writes its city in the box. The server does not know the user's zone, so a box shows its text right
-  after hydration rather than another zone's time for a moment; the hidden input holds the value from the start.
-- **No data loss.** A value changes only when the user changes what it shows: seconds and milliseconds the box does not
-  show stay as they came (a stamp from the server is sent back exactly), and retyping or re-picking what it shows keeps
-  the moment. Where clocks go back, one hour happens twice: a box holds whichever it was given, an edit inside that hour
-  keeps its offset, and a new pick is the first of the two. Where clocks go forward, a skipped time moves on (02:30
-  becomes 03:30), as `Date` and Temporal do.
-- **Typing:** a date in the user's format, then a time on either clock: `2026-09-17 2:30 pm`, `17/09/2026 14:30`,
-  `Sep 17, 2026 at 2:30 PM`, `2026-09-17T14:30`, `२०८३-०६-०१ १४:३०`. A date alone takes `defaultTime` (default
-  `minTime`, or midnight). Leaving the box writes it in the settings.
-- **The panel** is the calendar and the time columns (or `view="list"` slots) side by side, as tall as each other, with
-  Now, the zone, and Done. A picked day keeps the time; ↓ opens it on the chosen day, Enter on a day moves on to the
-  hours, and Tab runs through the calendar, the columns, and the buttons. On a phone the time goes under the calendar,
-  and a panel taller than the room scrolls, moving to the time once a day is picked.
-- **Rules:** `required`; `min` and `max` as moments (days outside are dimmed, and times outside on the first and last
-  day); `minTime` and `maxTime` as opening hours on every day (past midnight when `maxTime` is earlier); `step` in
-  seconds from each midnight; `isDateDisabled(date)` and `isTimeDisabled(time, date)` with ISO dates and times where the
-  user is; `validate`. Messages read like the box: "Airport pickup must be between 05:00 AM and 11:00 PM."
-  `validateDateTime(value, rules, fieldName, options)` is the pure check. `npm run test:datetimes` checks the helpers
-  against `Date` in eight zones, including half-hour daylight saving and a skipped day.
-- **Read-only** boxes have no panel: a lock sits where the button was, as in every read-only input.
-
-### Dropdown
-
-```tsx
-import { Dropdown } from "nexus-shared/client";
-
-<Dropdown name="roomType" label="Room type" required options={roomTypes} />
-<Dropdown name="amenities" label="Amenities" multiple max={6} options={amenities} />   // { value, label, icon: "wifi" }
-
-// Rows like a data table
-<Dropdown name="assignee" label="Assign to" options={staff} valueKey="id" labelKey="fullName"
-  columns={[{ key: "photo", type: "avatar" }, { key: "username", header: "Username" }, { key: "fullName", header: "Full name" }]} />
-<Dropdown name="country" label="Country" options={countries} valueKey="code" labelKey="name"
-  columns={[{ key: "flag", type: "image" }, { key: "code", header: "Code", type: "code" }, { key: "name", header: "Country" }]} />
-
-// A server list, editing a saved value
-<Dropdown name="guestId" label="Guest" valueKey="id" labelKey="fullName" defaultValue={booking.guestId} selectedOptions={[booking.guest]}
-  loadOptions={({ search, skip, pageSize, signal }) => api.guests({ search, skip, take: pageSize }, signal)} />  // { items, total }
-```
-
-- **Options are any objects.** `{ value, label, description, icon, disabled }` by default (a `ChoiceOption`), or API rows
-  read through `valueKey`, `labelKey`, `descriptionKey`, and `iconKey`. Values keep their type; a number and its text
-  are the same value, so id 7 from an API matches "7" from a form. A form gets hidden inputs named `name`, one per value.
-- **Columns** turn rows into cells that line up down the list (one grid with subgrid rows), with headings that stay on top.
-  Types: `text`, `muted`, `code`, `avatar` (a photo URL, or initials of the label on a soft tone), `image` (4:3: flags,
-  logos), and `icon` (a Tabler name); `width`, `align`, and `render` for the rest. The first picture leads the value in
-  the box and in chips.
-- **Search** matches every typed word in any order, with or without Latin accents, in the label, description, value, and
-  text columns (`searchKeys` to change). It is on with `loadOptions` or more than 8 options; without it, letters jump to
-  an option as in a native select. A local list renders 100 rows and adds more while it scrolls: 10,000 options open in
-  about 30 ms.
-- **Server pages:** `loadOptions({ search, page, pageSize, skip, signal })` returns `{ items, total?, hasMore? }`. The first
-  page loads when the list opens (placeholder rows, a spinner in the box), the next near the end ("Loading more…"), a new
-  search 250 ms after typing stops, aborting the request before it. A failure shows Retry. `loadKey` drops the loaded
-  pages, for a list that depends on another field. `loading` shows the same loaders when the page fetches `options` itself.
-- **Saved values the list can no longer offer** always show, and are never offered again once removed:
-  - on a server page not loaded: `selectedOptions` gives their items (a record usually carries the name), or
-    `resolveOptions(values)` looks them up (a placeholder shows until it answers);
-  - inactive items (`inactive: true` or `isActive: false`, or `isOptionInactive`): never in the list, shown only as a value;
-  - values missing from `options`: tagged **Unavailable**, or **Not found** when nothing is known but the value.
-
-  In the list they sit on top under **Selected** with their tag; in the box they carry the tag, or show as dashed chips.
-  A value only on another server page has no tag: a search finds it as a normal option.
-- **Rules:** `required`, `min` and `max` for several (at `max` the other options are disabled), and `validate`, through
-  `validateSelection`. A pick follows the same message timing as typing. `npm run test:dropdown` checks the helpers.
-- **Keys:** ↓ ↑ Page Up/Down Home End move past rows that cannot be picked, Enter picks, Space picks without search,
-  Backspace in an empty box removes the last value, Esc closes (then clears the search), Tab closes and moves on.
-- **Read-only** boxes have no list: a lock sits where the list button was, chips lose their remove buttons, and a click or
-  a key shows the note, as in every read-only input.
-
-### Markdown editor
-
-```tsx
-import { MarkdownView } from "nexus-shared";
-import { MarkdownEditor } from "nexus-shared/client";
-
-<MarkdownEditor name="description" label="Room description" defaultValue={room.description} defaultMode="split"
-  height={320} heightKey="room-description" maxLength={5000} required />
-
-// Wherever the text is shown, also in a server component
-<MarkdownView value={room.description} />
-```
-
-- **Write, split, and preview.** `defaultMode` (or `mode` with `onModeChange`) picks the view, and `modes` the views
-  offered. The switch is small tab buttons with `labels="selected"`: icons, and the label of the selected view. Split puts the preview beside the text and keeps the two scrolled together; under 560 px wide it stacks
-  them. The preview renders as a React transition, so typing stays within a frame in a 2,000-line document.
-- **Toolbar and shortcuts:** heading, bold (Ctrl+B), italic (Ctrl+I), strikethrough (Ctrl+Shift+X), quote
-  (Ctrl+Shift+.), code (Ctrl+E), code block, link (Ctrl+K), image, bulleted, numbered, and task lists (Ctrl+Shift+8,
-  7, L), table, and horizontal line. Marks wrap the selection or the word at the caret and come off when applied
-  again. Edits go through the browser's own editing, so Ctrl+Z undoes them. `toolbar` picks and orders the buttons.
-- **While typing:** Enter continues a list (the next number, an empty task box) and ends it on an empty item; a URL
-  pasted over selected text links it; a task ticked in the preview is ticked in the text.
-- **Height handle:** the status bar under the editor drags the height between `minHeight` and `maxHeight`, showing
-  the height as it changes; its grip takes ↑ ↓ (Shift for more), Page Up/Down, Home, and End; a double-click goes back
-  to `height`. `heightKey` remembers the user's height in local storage. Dragging writes straight to the DOM.
-- **Full screen** (`fullscreen`, on by default) lifts the editor into the top layer over a dimmed page, without
-  moving it in the DOM, so undo history and the form stay. Tab stays inside, and Esc closes it.
-- **A form field like `TextArea`:** `name`, `required`, `minLength`, `maxLength`, `pattern`, `validate`, the status bar's
-  word and character count, and read-only (a lock in the bar and a note under it). An invalid submit while the preview
-  shows brings the text back and focuses it. The view switch belongs to no form (`TabButtons` `form`), so it is never sent.
-- **Safe to show anyone's text.** `parseMarkdown` (GitHub-flavored: tables, tasks, strikethrough, autolinks) never
-  renders raw HTML, and `safeUrl` keeps only http, https, mailto, tel, and relative addresses for links, and raster
-  data URLs for images. Links to other sites get `rel="nofollow noopener noreferrer"`.
-- **Helpers:** `markdownToPlainText` for excerpts and search, and the editing commands `applyMarkdownTool`,
-  `continueMarkdownList`, `toggleMarkdownTask`, and `linkPastedUrl` for a custom editor. `npm run test:markdown`
-  checks the parser and every command.
-
-### Forms
-
-```tsx
-import { TEXT_PATTERNS, type InputParams } from "nexus-shared";
-import { ApiForm, SubmitForm } from "nexus-shared/client";
-
-const ROOM_INPUTS: InputParams[] = [
-  { type: "text", name: "number", label: "Room number", required: true, pattern: TEXT_PATTERNS.digits, span: 4 },
-  { type: "number", name: "floor", label: "Floor", required: true, min: 0, span: 4 },
-  { type: "dropdown", name: "type", label: "Type", required: true, options: ROOM_TYPES, span: 4 },
-  { type: "tabular", name: "beds", label: "Beds", itemLabel: "Bed", inputs: BED_INPUTS },   // a list is an input too
-];
-
-<ApiForm
-  inputs={ROOM_INPUTS}
-  loadValue={signal => api.get(ROOMS.details, { params: { id }, signal, toast: false }).then(unwrapApiResult)}
-  api={ROOMS.update}   // or in place: { module: NexusModule.Reservation, path: "Room/Update", method: "PUT" }
-  draftKey={`hotel-3:user-8:room:${id}`}
-  onSuccess={room => table.updateRow(room)}
-  onCancel={close}
-/>
-```
-
-- **Params in, values out.** Every input is an entry of `inputs`, so a page, a CRUD component, or a server can describe a
-  form with plain objects. Values come in as each input reports them (a date-time from an API becomes a date, "12.5"
-  becomes 12.5), and fields the record came with (an `id`) stay in the values.
-- **Fast at any size.** The values live in a `FormStore` outside React. Typing renders only the input typed in; an input
-  renders again only when a message it shows changes, or code sets its value. A keystroke costs about 5 µs in the store
-  for a form of 200 inputs, and a list of 10,000 rows is not checked again on each keystroke (it checks itself).
-- **Checks on Save.** Each input's own rules (they also catch text that is not a date yet), the form's `validate` across
-  inputs, and rows not on the page. Every message shows, the first problem takes focus (a table scrolls to its row), and
-  the status line lists what needs attention, each name a link to its input. A rule message on an input shows once the
-  input was left, and on Save.
-- **One save at a time.** Save waits with a spinner; another click, Enter, or Ctrl+S does nothing until it ends. A save
-  makes the values the form's own ("Unsaved changes" clears; values typed meanwhile stay changes). `onSubmit` returns
-  `{ ok: false, errors, message }` to say why not, and a thrown error shows its message.
-- **Server messages.** The server's own words are what the user reads. `ApiForm` shows **every** message a refusal
-  carried - a Nexus answer's `errorMessages` (a list, or one message object, or one message and its codes at the top
-  level) and ASP.NET Core problem details (`errors` by field) - each on the input its `inputName` names, matched without
-  case and by the first part of a path (`Addresses[1].City`). Names that match no input of this form, messages that name
-  none, and failures without fields show beside the buttons; nothing is swallowed and nothing is shown twice. A sentence
-  of ours by HTTP status ("Someone else changed this record…") is the fallback for an answer that explained nothing.
-  `messageCode` and `errorCode` ride along in `answer.errorMessages` for the log and for `onError` to react to, and are
-  never shown as the sentence. An input's message clears when its value changes.
-- **Nothing lost.** `draftKey` keeps unsaved changes in IndexedDB (after a 600 ms pause, and at once when the page hides
-  or the form leaves) and brings them back with a note and Discard; drafts changed on the server since are named. Cancel
-  asks before it drops changes, and the page asks before it closes with some (`confirmLeave`, on without a draft).
-  `form.load(values, { keepChanged: true })` refreshes a record without touching what the user changed.
-- `npm run test:forms` checks the store and the API helpers; `scripts/browser-checks/forms.cjs` in the template checks the
-  three demo pages.
-
-### API calls
-
-```ts
-// api-modules.ts: the app's modules and where each one's root is (shared by the browser and the server)
-import { defineApiModules, NexusApiModules, NexusModule } from "nexus-shared";
-
-export const MODULES = defineApiModules(new NexusApiModules({ useProxy: process.env.NEXT_PUBLIC_API_PROXY !== "false" }));
-export const ROOMS = MODULES.controller(NexusModule.Reservation, "Room", "room");
-
-// In the browser
-import { api } from "nexus-shared/client";
-const rooms = await api.get<Room[]>(ROOMS.listing);                    // GET /api/app/reservation/Room/NormalListing
-await api.put(ROOMS.update, values, { subject: "Room 204" });          // toast: "Room 204 saved." or what failed and why
-await api.confirm(ROOMS.delete, { params: { id }, subject: "Room 204" });   // asks "Delete Room 204?" first
-
-// On the server (a server component, a route handler, a server action)
-import { serverApi } from "nexus-shared/server";
-const list = await serverApi.get<Room[]>(ROOMS.listing, { revalidate: 60, tags: ["rooms"] });   // straight to API_RESERVATION
-
-// app/api/app/[module]/[...path]/route.ts: the browser's way to every module
-export const { GET, HEAD, POST, PUT, PATCH, DELETE } = createApiProxy({ token: readAccessToken });
-```
-
-- **Modules are the app's.** `ApiModules<TModule>` is an abstract class over the app's own module enum: implement
-  `modules` (each module's value, its key in proxy URLs, its label for messages, where its root comes from) and
-  `serverRoot(module)` (from the environment, a settings service, anything; may be async). Register it once with
-  `defineApiModules`, and define endpoints through it (`MODULES.controller`, `MODULES.endpoint`), so a file that calls
-  an endpoint has registered the modules on either side. `NexusApiModules` is the Nexus set (roots from `API_<MODULE>`,
-  as in the previous project; `NexusModule.None` for the app's own `/api` routes) and runs when nothing is registered.
-  The list is checked: keys and values must be unique, and keys fit in a URL.
-- **`NexusModule`'s numbers are the backend's `EModules` flags**, and a permission is a bitmask of them, so a value
-  that disagrees with the backend by one bit grants or denies the wrong module in silence. They changed after
-  2.0.0: `Chat` took bit 6 and `Accounting` through `Portfolio` each moved up one. Code that uses the names needs
-  nothing; anything holding a stored or hard-coded **number** does. [CHANGELOG.md](CHANGELOG.md) has the table.
-- **Module types from one place.** An app names its enum once, next to `defineApiModules`:
-  `declare module "nexus-shared" { interface ApiRegister { module: HrModule } }`. Every endpoint, call, `ApiForm`,
-  and CRUD then takes only those modules (`AppModule`), so `{ module: NexusModule.Reservation, … }` in an HR app is a
-  type error. Without it, the modules are `NexusModule`.
-- **The proxy, on or off.** With `useProxy` (the default), the browser calls `/api/app/<module>/<path>` and the proxy
-  route sends it on to the module's root with the user's token, which never reaches the browser. Off, the browser
-  calls each module's `browserRoot` (public) and the proxy serves none. `proxies(module)` mixes the two, such as
-  uploads straight to the Drive module and the rest through the proxy.
-- **The proxy hides the backend.** To the browser the app is the backend, and nothing in an answer names the real one:
-  - **No redirect reaches the browser.** One that stays inside the module (the root's origin, or its host moved to
-    https by the backend's HTTPS redirection, under the root's path in any casing) is followed on the server as
-    `fetch` follows it: 307 and 308 keep the method and body, a 303 and a POST's 301 or 302 become a GET, up to
-    `maxRedirects` (3). Any other answers 502 `BACKEND_REDIRECT_REFUSED`: following it would carry the token elsewhere.
-  - **Response headers by an allowlist**, `DEFAULT_PROXY_RESPONSE_HEADERS` (Content-Type, Content-Disposition,
-    Content-Language, Content-Range, Accept-Ranges, Cache-Control, Expires, ETag, Last-Modified, Vary, Retry-After),
-    the Nexus backend's `X-Nexus-*`, and the names in `responseHeaders`. Server, X-Powered-By, X-AspNet-*,
-    X-SourceFiles, Via, Alt-Svc, Strict-Transport-Security, Report-To, NEL, CORS, Location, Link and WWW-Authenticate
-    never pass, even named; Set-Cookie only with `passCookies`. Every answer gets `X-Content-Type-Options: nosniff`,
-    and `Cache-Control: private, no-store` unless the backend said how to cache it.
-  - **Error pages replaced.** An error answer that is not JSON (an HTML or text page, a stack trace), JSON that is a
-    stack trace or repeats the user's token, or one over 1 MB, becomes the failure envelope with the backend's status
-    and plain words (`BACKEND_ERROR_PAGE`). JSON refusals (the Nexus envelope, problem details) and empty ones pass as
-    they came, so the backend's own words still reach the form.
-  - **The request.** The browser's own `X-Forwarded-*`, `Forwarded`, `X-Real-IP` and the like never go on, nor its
-    cookies, a method or path override (`X-HTTP-Method-Override`, `X-Original-URL`) or Next.js's own headers. The
-    proxy writes X-Forwarded-For (the last address the app received, which Next.js or the app's reverse proxy wrote;
-    `clientAddress` reads it elsewhere; an IPv4 or IPv6 address or nothing, never other text) and X-Forwarded-Host
-    and -Proto (the app's configured origin, else the request's). A module whose root is a path on the app (a pretend
-    backend) is called at this server's own host and port, over http: the request URL's, which Next.js builds from
-    where it listens. Never at the configured origin, so an app whose `origin` reads the Host header cannot let a client
-    choose another port on the machine; `serverApi`, which has no request, uses that `origin`, so build it from
-    configuration, or take the Host only when it names this server's own port. A body over `maxBodySize` (100 MB) is
-    refused with 413 before the backend sees it, and a page of another site cannot call through the proxy
-    (`Sec-Fetch-Site: cross-site`, other than a link followed) unless `allowCrossSite`.
-  - **A server call can say who the client is too.** `lastForwardedAddress` and `readIpAddress` (`nexus-shared/server`)
-    read the client's address as the proxy does, from anything with a `get` (Next.js's `headers()` included). The
-    template's `api-setup.ts` gives Identity calls, and only them, `X-Forwarded-For` and the browser's `User-Agent`
-    through `configureServerApi({ headers })`: sign-in leaves from the server, and Identity's rate limit counts per
-    address. Only Identity's, because reading the request makes a page render per request.
-  - **Refusals** are the Nexus envelope, `{ isSuccess: false, code, message, messageCode, errorCode, errorMessages }`
-    (`failure` builds another backend's; `PROXY_REFUSALS` lists the codes), and the real cause goes to the server's
-    log (`onProblem`, default `console.error`), never with the token or a query string.
-  - **Two things the proxy cannot do for an app.** Node.js does not trust a development certificate (ASP.NET Core's)
-    unless it starts with `NODE_USE_SYSTEM_CA=1`, so a module whose http root redirects to such an https port answers
-    502 until then, and the log says so. And Next.js keeps an X-Forwarded-For a client sent when nothing stands in
-    front of the app, so only behind a reverse proxy of its own is the client's address certain.
-- **One engine, two clients.** `api` and `serverApi` are two settings of `createApiClient`: it fills `{id}` in the path
-  from `params` or the body, adds the query, headers, and token, waits up to `timeout` (60 s), tries a failed GET once
-  more (a save never twice), and reads every answer as an `ApiResult` (`ok`, `status`, `result`, `message`,
-  `errorMessages`, `errors`, `messageCode`, `errorCode`, `network`, `timeout`, `aborted`). A failed call is an answer,
-  never a throw; an aborted one shows nothing. Next.js's own signals (`headers()` while prerendering, `redirect()`) pass
-  through untouched.
-- **What the server said wins.** A refusal is shown in the backend's own words whenever it sent any:
-  `{ isSuccess, code, errorMessages: [{ message, messageCode, errorCode, inputName }] }` becomes
-  `result.errorMessages` in that order (one message object instead of a list, a single `errorMessage`, and an older
-  answer's one message at the top level all read into the same list), `result.errors` holds the ones that name an input,
-  and `result.message` is all of them joined for a toast. `messageCode` and `errorCode` are for the log and for a page to
-  react to - never the sentence a user reads. The messages built from the HTTP status are the fallback for an answer that
-  explained nothing.
-- **Answers of another shape.** Nexus answers and ASP.NET Core problem
-  details are read out of the box. A backend that answers its own envelope registers one reader for the whole app:
-
-  ```ts
-  // Reads { success, message, data, error: { code, message, fields } } — the answer becomes ok, result, message, errors
-  const read: ApiResponseReader = (body, status) => {
-    const answer = body as BackendAnswer | null;
-    if (answer?.success) return { ok: true, status, result: answer.data, message: answer.message };
-    const fields = Object.entries(answer?.error?.fields ?? {}).map(([name, list]) => [name, list.join(" ")]);
-    return { ok: false, status, message: answer?.error?.message, messageCode: answer?.error?.code, errors: Object.fromEntries(fields) };
-  };
-  configureApi({ read });          // the browser
-  configureServerApi({ read });    // and the server, so both sides read one envelope
-  ```
-
-  It is the fallback of every call that does not bring a `read` of its own, which is what the components that call
-  inside themselves need: a `Crud`'s lists and actions and an `ApiForm`'s save have no place to pass one. A call's own
-  `read`, and an `ApiForm`'s `readResponse`, still win.
-- **Toasts in the browser.** Errors always, successes for POST, PUT, PATCH, and DELETE; the same failure twice at once
-  shows once; `toast: false`, `true`, or `{ success, error, loading }` per call; `configureApi({ toast, headers, read,
-  onSignedOut })` for the app. The server shows nothing and logs network failures, timeouts, and 5xx.
-- **One message builder.** `buildMessage(kind, { action, subject, count, status })` words every message, and
-  `messages.success`, `.failure`, `.reason`, `.loading`, `.confirm`, `.label`, and `.forResult` are short ways to call
-  it: "3 rooms deleted.", "Could not move Room 204 to the trash.", "You do not have permission to delete Room 204.". The
-  texts and action words are one table: `configureMessages` rewords or translates all of them at once, and an action
-  of the app's own is its words (`{ verb: "check in", done: "checked in", doing: "Checking in", object: "the guest" }`).
-- **A controller's lists.** `apiController` names the lists as the Nexus backend does: `listing` and `pagination` are the
-  active records' (`NormalListing`, `NormalPagination`), and `lists.flag`, `lists.trash`, `pages.trash`, … the others
-  (`FlagListing`, `TrashListing`, `TrashPagination`, …), for the CRUD component.
-- `npm run test:api` checks the builder, routes, modules (another app's enum, the proxy on and off), the engine, the
-  server client, and the proxy's routing; `npm run test:proxy` checks how the proxy hides the backend (redirects,
-  headers, error pages, forwarded headers, paths, the body limit, other sites, the log) against a fake backend;
-  `scripts/browser-checks/api-calls.cjs` in the template checks `/demo/api`.
-
-### Data table
-
-```tsx
-import type { TableColumn } from "nexus-shared";
-import { DataTable, useTable } from "nexus-shared/client";
-
-const COLUMNS: TableColumn<Booking>[] = [
-  { key: "no", label: "Booking", width: "7rem", movable: false, pinnable: false },   // stays first, and stays put
-  { key: "guest.name", label: "Guest" },                                   // a path into the row
-  { key: "amount", label: "Amount", format: "money", prefix: "Rs. ", group: "Amount details" },   // number, money, percent, date, …
-  { key: "due", label: "Due", format: "money", prefix: "Rs. ", group: "Amount details" },   // one heading over both: the header is two rows
-  { key: "status", label: "Status", options: [{ value: 1, label: "Confirmed", tone: "success" }] },   // a tag
-  { key: "paid", label: "Paid", format: "boolean", resizable: false },     // keeps its width
-  { key: "created", label: "Booked", format: "date-time", hidden: true },  // shown from the Columns menu
-];
-
-const table = useTable<Booking>();
-<DataTable table={table} aria-label="Bookings" columns={COLUMNS} rows={bookings} selectable massActions={MASS} rowActions={row => ACTIONS(row)} stateKey="bookings" />
-<DataTable columns={COLUMNS} paging="server" load={(query, signal) => fetchPage(query, signal)} />   // { search, sort, page, pageSize, filters }
-<DataTable columns={COLUMNS} rows={bookings} onImport={askForFile} moreActions={[{ id: "report", label: "Monthly report", onSelect: open }]} />
-
-table.upsert(saved); table.patch(7, { paid: true }, { flash: true }); table.remove([7, 8]); await table.reload();
-```
-
-- **Columns are params**, one plain object each, as inputs are: `key` (a field or a path), `label`, `group`, `format`,
-  `decimals`, `prefix`, `suffix`, `options` (labels for an enum's values; a `tone` draws a tag with a dot of its color),
-  `value`, `render`, `text`, `width`, `minWidth`, `align`, `wrap`, `sortable`, `sortKey`, `searchable`, `hidden`,
-  `hideable`, `movable`, `resizable`, `pinnable`, `pinned`. Numbers line up at the end in tabular figures; dates and
-  times follow the user's settings; moments show in the user's zone once the page has hydrated; long text ends in … at
-  the column's width.
-- **Columns in bands.** `group` is the heading above a column (`{ key: "amount", label: "Total", group: "Amount
-  details" }`); the columns next to each other that name the same one share it, and the header reads in two rows, the
-  bands on top and the columns' own headings under them. A column with no group keeps one heading as tall as both rows,
-  and so do the numbers and checkbox column and the actions. A band is a heading and nothing more: it sorts nothing, has
-  no menu and no edge to drag, and the columns stay one flat list, so hiding, ordering, widths, pins and the export are
-  as they were. The bands are read off the order on screen: a column dragged out of its run takes its band's heading
-  with it, and the run it left draws that heading again. With no group anywhere the header is one row.
-- **Rows three ways.** Given (`rows`) or loaded once (`load`), the table searches, sorts, and pages them itself: every word
-  must match, in any column, with or without accents, and 10,000 rows search in about 0.5 ms a keystroke. A page at a time
-  (`load` with `paging="server"`), each search (after 300 ms without typing, or Enter), sort, and page is one request; a
-  newer query stops the one before, so a late answer never shows. A loader may answer without a promise (a cache), and
-  the rows then paint with the table. `loadKey` starts over for another list behind the same table.
-- **What it shows while it waits.** Placeholders in the shape of the rows for the first rows; afterwards the rows stay,
-  with a thin bar under the headings, and dim only if a load takes a moment. A failed load says why, with Retry; an empty
-  list has its own message and action; a search or filters that find nothing offer Clear search or Clear filters.
-- **The columns are the user's.** Drag a heading to another place, drag its right edge for its width (double-click the
-  edge, or "Fit to content", to fit it, never under the column's `minWidth`), and use the caret on the heading to sort,
-  pin it left or right, move it, or hide it; the Columns menu shows and hides them. A column opts out with
-  `movable`, `resizable`, or `pinnable: false`, and `pinned` starts it on a side. The table itself can refuse all three
-  (`reorderable`, `resizable`, `pinnable`). Once a width is set the columns are laid out from those widths, so one edge
-  moves alone; "Reset columns" in the options menu puts everything back.
-- **The bar** is one line on a wide table: the Add section (`add`, then the page's `actions`) and the lists
-  (`toolbar`) on the left; Reload, the options menu (⋮) and the search, rows per page inside it, on the right. A
-  narrower table moves whole parts, never a lone button, by its own width (a container query, so a table in a narrow
-  panel does the same): under 670px the search takes the top line (with nothing on the left, it leads the buttons'
-  line instead), under 375px Reload moves into ⋮, and under 325px, beside lists, the Add section takes the last line,
-  its buttons sharing it. On the admin shell, whose menu leaves the screen at 900px, those are windows of 695, 400 and
-  350px. A bar wider than those widths expect (a long Add label, the page's own buttons, cozy density) takes the next
-  step as soon as a line would break (`data-squeeze`). A `Crud`'s lists name every tab from 900px and only the chosen
-  one below.
-- **One options menu (⋮)**: **Filters** (`filterInputs`, input params as a form takes them, each named after the
-  column it filters: a small form under ⋮, applied as it changes; a server gets them flat by name, see `filterRequest`),
-  the columns shown as a CSV (`exportable`, named by `exportName` or the table's label), a
-  print view of the same in a frame of its own (`printable`), Import (`onImport`), any `moreActions` of the page, and
-  Reload, last, on a table too narrow for its button. A client table writes every row the search left; a server table
-  writes the page it has, and says so.
-- **Selection.** The first column counts the rows (`numbered`, on by default when `selectable`) and turns into the row's
-  checkbox under the pointer; once anything is selected every row shows its checkbox and the heading shows the box that
-  selects the page (partly checked when some are). Shift+click selects a range, up to `maxSelection` (500). While rows
-  are selected, a bar with the count, one split button holding every `massAction`, and Clear covers the headings, so
-  nothing moves: the menu makes the action picked the button, and the next click runs it, with a spinner while it does.
-- **Row actions**: `inline` ones as icon buttons, the rest in the row's menu; while one runs (a promise), the row is busy.
-  `onRowOpen` for a double-click. A row added or saved is highlighted for a moment (steadily, with reduced motion).
-- **A pinned section.** `pinnedRows` puts rows in a band above the page with a button that folds them open and shut
-  (`pinnedLabel`, `pinnedMax` beside the count, `pinnedLoading` while they come); with a `stateKey` the choice is
-  remembered on the device. They are the same records as in the list below, and each wears a pin where the rows of the
-  page show their number.
-- **Wide tables** scroll inside their frame, with the numbers and checkbox column on the left, the actions on the right,
-  any pinned columns beside them, and the headings on top staying in place, and a soft shadow where columns scroll under
-  them. Under the table: "Showing 41–50 of 234" (and how many the search and filters left out) on the left, "Page 5 of
-  24" and the pager on the right; rows per page sits inside the search box. At 520px and less the page buttons go.
-- `npm run test:table` checks the helpers, the store, and the CRUD rules; `scripts/browser-checks/data-table.cjs` in the
-  template checks `/demo/data-table`.
-
-### CRUD
-
-```tsx
-import { Crud } from "nexus-shared/client";
-
-export const GUESTS = MODULES.controller(NexusModule.Reservation, "Guest", "guest");   // every list and action
-
-<Crud<Guest>
-  api={GUESTS}
-  columns={GUEST_COLUMNS}                                 // as a DataTable takes them
-  inputs={GUEST_INPUTS}                                   // or { create, edit }, or (action, row) => inputs
-  paging="server"                                         // default "client": each list loaded once
-  form={{ load: "details", newValues: { country: "Nepal" } }}
-  details={{ columns: GUEST_DETAILS }}
-  onChange={({ action, rows, mode }) => audit(action, rows)}
-/>
-```
-
-- **Lists.** All (`NormalListing` or `NormalPagination`), Flagged, Trash, and Deleted, as tabs after Add: every one
-  named on a table 900px wide or more, icons with the chosen one named below. A list shows when it is in `modes`, has
-  its endpoint, and the user may call it.
-- **Pinned records.** `PinListing` answers the records the user pinned: they sit in a section above the active list that
-  folds open and shut, and in the list and its pages as well. One limit holds for every CRUD in the app
-  (`configureCrud({ maxPins: 100 })`, 100 by default). Pinning a selection bigger than the room left pins as many as fit,
-  in the order they were picked, and says so; lowering the limit never unpins anything, so a user over it can still
-  unpin and can pin again once they are under it.
-- **Actions.** On a record in the lists of active records: View details, Edit (an icon on the row), Flag, Pin,
-  Move to trash; in the trash: Recover, Delete permanently; in the deleted list: Move back to trash. On selected records: the same, plus a new Description for all of them. Each shows only when it is in
-  `actions`, has its endpoint, and is allowed. A controller without a trash (no endpoint, or left out of `actions`) offers
-  Delete where Move to trash would be; a trash the user may not use never becomes Delete.
-- **Questions and messages.** Move to trash and Delete ask first ("Move 3 guests to the trash?", "This cannot be
-  undone."); Flag, Pin, and Recover are undone by a click and do not ask. Toasts come from the message
-  builder ("Sita Sharma moved to the trash.", "3 guests unpinned.").
-- **Rows from the answers.** A record that moves to another list leaves the one in view (and the pinned section); flags,
-  pins, and saved values change in place; a new record goes first; a server page loads again in the background to fill up. When a mass
-  answer lists the records it changed, only those change.
-- **Add and Edit** open popups built on `ApiForm`, with the Save bar in the footer and the server's messages on their
-  inputs. Keys keep them one each: pressing Add again brings back an Add form with changes (minimized or not), or opens a
-  fresh one; Edit of a record already open brings that popup back as it was. Closing a form with changes (its close
-  button, Esc, the dock) asks "Discard your changes?". Edit opens with the row, the `details` endpoint's record
-  (`form.load: "details"`, for fields a list leaves out), or a loader of your own.
-- **Details** (View, or a double-click) shows every column, hidden ones too, and the full record once `details` answers,
-  with Edit in its footer.
-- **Cache.** Lists are kept for 5 minutes while the page is open (`cache={{ lifetime }}`, or `false`): going back to a
-  list paints it at once. After a change, the list in view keeps its rows and the others load again when shown; Reload
-  and the handle's `reload()` go past the cache. The cache goes when the page does.
-- **Permissions** come from the app's rules: `definePermissions(new NexusPermissions())` once, then `setActions(accessActions)`
-  after sign-in. While the rules load, the table shows placeholders; a user with no list sees a message. Rules for
-  another backend extend `Permissions` (`can(endpoint)`), and its page and mass shapes extend `CrudBackend`.
-- `ref` gives `table`, `mode`, `setMode`, `reload`, `create(values)`, `edit(row)`, and `view(row)`.
-- `scripts/browser-checks/crud.cjs` in the template checks `/demo/crud`: every list and action, the popups, the roles, the
-  cache, a phone, and contrast in every theme.
-
-### Excel import and export
-
-A model's records in and out of a spreadsheet, against the backend's Excel controller bases
-(`NexusExcelController<TContract>` and `NexusExcelExportController<TContract>`): `Excel/Settings`, `Excel/Template`,
-`Excel/Verify`, `Excel/Import`, and the model's own export action.
-
-```tsx
-export const CITIES = MODULES.controller(NexusModule.Configuration, "City", "city");
-export const CITY_SHEET = excelEndpoints(CITIES, { subject: "city" });        // the four, and Excel/Export
-
-openExcelImport({ endpoints: CITY_SHEET, subject: "city", onImported: reload });   // the panel as a window
-<ExcelImport endpoints={CITY_SHEET} subject="city" onImported={reload} />          // or in the page
-openExcelImport({ endpoints: REGION_SHEET, subject: "region", mode: "bulk", onImported: reload }); // rows typed in
-
-await downloadExcelTemplate(CITY_SHEET);
-await exportExcel(CITY_SHEET, { subject: "city", rows: table.matches, query: { search, sort: "cityName", direction: "asc", filters } });
-```
-
-- **The template** is the backend's file, downloaded under the name its `Content-Disposition` gives it. Every list in it
-  is a dropdown and the ids beside a choice fill themselves, so the person types no code and pastes no id.
-- **A verify writes nothing.** The file goes up as form data, and the answer is the rows, judged: what would be added,
-  what is already a record, and what is waiting on a fix.
-- **The review is two editors** over those rows - **New rows** (which includes the rows to fix, since a row with a
-  problem is not yet a record) and **Already there**, which folds away - built from the sheet's columns with the rules
-  the sheet told the person about, so a fix made here is checked the way the file was. What the server found wrong is
-  listed under the rows, each entry naming the cell as a spreadsheet does (`B7 - City name`) and taking the caret to it.
-  Rows can be added to the new rows (Add, Insert, Duplicate); one added and left empty is not sent, and an added row is
-  numbered after every row of the file, so no two rows share a number. A sheet with a required list takes no added
-  rows: a list's key is picked in the spreadsheet, and a row added here could never have one.
-- **A bulk insert is an import with no file** (`mode: "bulk"`): the new rows' editor opens with one empty row, the
-  person types the rows, and they go to the same `Excel/Import` with the same checks - a problem then names its row
-  (`Row 3 - Region name`). A sheet with a required list cannot be typed in, and the panel says so.
-- **Nothing typed is lost unasked**: closing the window or Start over asks first, and the entry picked again while its
-  window is minimized brings that window back. An import that wrote nothing keeps the rows, and lists under them what
-  the backend refused and why.
-- **The import sends rows, never the file again**, or every fix made on screen would be lost; every check runs again on
-  the way in. **A duplicate is never updated**: one left alone is not sent at all, and editing one sends it as a new
-  record. An import writes what it can and names the rest; only one that wrote nothing at all is a failure.
-- **A choice travels as its key**, out and back. The plain id in the sheet is for the person to read and is never read
-  back, so nothing copied out of a file or out of an answer can be posted to an endpoint as an id.
-- **The export is the server's file**, written from the search, the sort and the filters on screen - not a CSV of the
-  rows this browser holds. The row limit is the backend's (`Excel/Settings`, 5,000 by default, kept for the page's life);
-  over it the person is asked first, and the answer's own headers say what was written and what was left out.
-- **Generic, like the rest.** `ExcelBackend` is the class an app on another backend registers
-  (`defineExcelBackend(new MyExcelBackend())`): the request shapes, how the answers read, the upload field, and the names
-  of a download's headers. `NexusExcelBackend` is the default. `readExcelResponse` reads a refusal's `errorMessages`, so
-  "no city could be written" reaches the person in the backend's own words.
-- **A column draws its own input**: text, note, whole number, decimal, amount, date, time, Yes/No, and a choice shown
-  read-only with the words the person picked. A **date and time** is a text box, not a picker: the sheet's moment is a
-  zone-less wall clock while a picker's value is a UTC moment, so a picker would shift every value by the reader's offset.
-- `scripts/test-excel.mts` checks the endpoints, the answers, the inputs and the round trip; the template's
-  `scripts/browser-checks/excel.cjs` checks `/demo/excel`: every state, the two rules about the wire, both downloads, the
-  warning before a capped export, a phone, and contrast in every theme.
-
-In a table, `excel={{ endpoints: CITY_SHEET, subject: "city" }}` is the whole of it: the options menu (⋮) then offers
-**Download template**, **Import from a spreadsheet** (the panel as a window, after which the table reads its rows
-again), **Bulk insert** (the same with no file, beside an Add only; `bulk: false` leaves it out) and **Export to
-Excel**, which sends the table's own search, filters and sort with the page's `filters()`. A `Crud` passes it through
-as `table={{ excel }}` and drops the lists it had kept once an import has written. It replaces `onImport`, which stays
-for a page that imports its own way.
-
-Planned, following the previous Nexus project: a page status layout, and in the CRUD, audit logs in the details view.
+# nexus-shared
+
+Lightweight React components, helpers, and design tokens for Nexus apps. No runtime dependencies besides
+React and `nexus-icons`.
+
+```
+npm install nexus-shared nexus-icons
+```
+
+```tsx
+// Once, in the root layout
+import "nexus-shared/styles.css";
+
+import { Button } from "nexus-shared";
+import { InlineIcon, iconPlus } from "nexus-icons";
+
+<Button variant="primary" icon={<InlineIcon icon={iconPlus} />}>New booking</Button>
+```
+
+## Entry points
+
+| Import | Contains |
+|---|---|
+| `nexus-shared` | Components and helpers that work in server and client components |
+| `nexus-shared/client` | Client components and browser services |
+| `nexus-shared/server` | Server-only code |
+| `nexus-shared/styles.css` | Tokens, base styles, and component styles |
+
+## Themes
+
+Seven themes, each with a light and a dark palette that meets WCAG AA contrast:
+**Nexus** (default), **GitHub**, **Nord**, **Dracula**, **Solarized**, **Catppuccin**, and **Rosé Pine**.
+The mode is Light, Dark, or System (follows the operating system).
+
+```tsx
+// app/layout.tsx
+import "nexus-shared/styles.css";
+import { ThemeScript } from "nexus-shared";
+import { ThemeSwitcher } from "nexus-shared/client";
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <ThemeScript />
+      </head>
+      <body>
+        <header>… <ThemeSwitcher /></header>
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+- `ThemeScript` applies the saved choices before the page paints, so there is no flash of the defaults. Options:
+  `defaultTheme`, `defaultMode`, `defaultDensity`, `defaultAnimations`, `grid`, `themes`, `nonce`. It sets
+  attributes on `<html>`, hence `suppressHydrationWarning`.
+- `ThemeSwitcher` is a palette button with a popover; `ThemePicker` is the same picker placed in a page. Besides the
+  mode and the theme it offers **Density** (Compact, Cozy), **Animations** (On, Off, System) and, in a development
+  build only, the **Scale grid** (Off, px, mm); `showMode`, `showDensity`, `showAnimations`, `showGrid` turn them off.
+- `useTheme()` returns `{ theme, mode, resolvedMode, density, animations, motion, grid }` and a setter for each.
+- The choices are saved in `localStorage` (`nx-theme`, `nx-mode`, `nx-density`, `nx-animations`, `nx-grid`) and
+  shared by open tabs.
+
+Without JavaScript, set the attributes yourself: `<html data-nx-theme="nord" data-nx-mode="dark">`.
+Without `data-nx-mode`, the system setting applies. `data-nx-theme` also works on any element, which then
+draws in that theme (the picker's previews use this).
+
+**Density** is `data-nx-density="cozy"` on `<html>`: every control 4px taller (`--nx-control-sm/md/lg` 32/38/44) and
+every list row 6px (`--nx-row` 38), so buttons, fields, table rows and headers, menus, dropdown options and the table's
+footer follow at once. Compact, the default, is the sizes the package always had.
+
+**Animations** come from one attribute too. `ThemeScript` works out `data-nx-motion` (`reduce` or `full`) from the
+visitor's choice and the system's `prefers-reduced-motion`, and keeps it current when the system setting changes;
+every stylesheet reads that attribute, never the media query. So **On** animates on a machine whose operating system
+has animations turned off, **Off** never animates, and **System** (the default) does what the system says. Popups fade
+in and out, and every popover panel (menus, the table's panels, pickers) fades briefly; nothing waits for a fade.
+
+**Scroll bars** have one look everywhere, the design lab's: thin and quiet, with a thumb of the text colour at 22% on
+no track (`Nexus.Base.css` sets `scrollbar-width` and `scrollbar-color` on every element). On Windows, Chrome and Edge
+draw the bar 10px wide and Firefox 8px. Safari has no `scrollbar-color`, so it draws its own thin bar. A component
+that needs another look sets the two properties on its own scroller: the time picker's columns hide the thumb until
+the pointer or the keys are in them. An app overrides the bar the same way, from outside the layers. With forced
+colours on, the system's colours come back.
+
+### How it works
+
+- `Nexus.Themes.css` gives each theme its colors once, as `light-dark(light, dark)`; the page's `color-scheme` picks the side.
+- `Nexus.Tokens.css` holds sizes, spacing, and type, and derives hover colors, soft backgrounds, and the focus ring from the palette.
+  A solid fill under the pointer is the fill with 12% black mixed in, in light and dark mode alike, so a light label on
+  it only gains contrast: a `--nx-primary-solid` or `--nx-danger-solid` whose label reads at rest reads hovered and
+  pressed too. `--nx-primary-text` and `--nx-danger-text` are therefore white (or near it) in both modes; a fill that
+  needs a dark label is too light to be a solid fill. In a dark theme the darker step moves the fill toward the panel,
+  so a fill keeps 2:1 on `--nx-surface` under the pointer as it does at rest.
+- Components use only `--nx-*` variables, so every component follows the theme with no extra code.
+- `npm run check:themes` checks every theme in both modes against WCAG contrast. Run it after changing a color.
+
+### Custom themes
+
+A theme is one CSS block. List it for the script and the picker:
+
+```css
+[data-nx-theme="brand"] {
+  --nx-primary: light-dark(#0f766e, #2dd4bf);        /* the accent as text and lines */
+  --nx-primary-solid: light-dark(#0f766e, #0d7a70);  /* the accent as a fill behind white text: buttons, checks */
+  --nx-primary-text: light-dark(#ffffff, #ffffff);   /* light in both modes: hover and pressed darken the fill */
+  /* …any other --nx-* color: bg, surface, surface-2, surface-hover, border, border-strong,
+     text, text-muted, text-subtle, danger, danger-solid, danger-text, success, warning, info */
+}
+```
+
+Give a solid fill a light label at 4.6:1 or more in both modes, and keep it 2:1 off `--nx-surface` once 12% black is
+mixed in (the pointer's step). A dark label on a light fill reads at rest and loses contrast under the pointer. The
+example's dark fill, `#0d7a70`, holds white at 5.2:1 at rest and 6.8:1 hovered. `npm run check:themes` checks this
+package's own themes, not an app's.
+
+```tsx
+const themes = [...NEXUS_THEMES, { id: "brand", name: "Brand", description: "Our colors" }];
+<ThemeScript themes={themes} defaultTheme="brand" />
+<ThemeSwitcher themes={themes} />
+```
+
+All styles sit in `@layer nexus.*`, so an app's own CSS overrides any token or component style without `!important`.
+
+### Quick preferences
+
+Under the theme, the `ThemeSwitcher` panel holds the person's own settings (`PreferencesPicker`, or
+`<ThemeSwitcher preferences={false} />` for the theme alone). Each applies at once to everything on the page, is saved
+on this device, and reaches other open tabs:
+
+| Section | Setting | Saved as | Read by |
+|---|---|---|---|
+| Language and region | Interface language: English, नेपाली | `nx-language` | `useUserPreferences().language` |
+| | Calendar: AD, BS | `nx-date-calendar` | every date component (`useDatePreferences`) |
+| Dates and times | Date picker language: English, नेपाली | `nx-date-script` | every date component |
+| | Clock: 12-hour, 24-hour | `nx-time-format` | every time component |
+| | Display date format | `nx-date-format` | every date component |
+| Numbers | Number scale (the core's `ENumberScales`): International 1,234,567, South Asian 12,34,567 | `nx-number-scale` | `useNumberLocale()` |
+| | Thousands separator: 1,200, 1.200 (decimal comma), 1 200, 1200 | `nx-thousands` | `useNumberLocale()` |
+| Tables | Default page size | `nx-page-size` | every `DataTable` and `Crud` |
+| | A row click opens the record | `nx-row-click` | every `DataTable` and `Crud` |
+
+- **Numbers:** `useNumberLocale()` turns the two number settings into a locale (`numberLocale(scale, separator)`):
+  `en-US` and `en-IN` as they are, any other pair a key such as `"en-IN|.|,"` that `formatNumber`, `parseNumber` and
+  `getNumberSymbols` read. A `NumberBox`, a `Slider` and a table's number cells without a `locale` of their own use it;
+  a number box rewrites what it shows when the setting changes, so a typed value is never read in the wrong marks.
+- **Tables:** once chosen, the page size and the row click go over what a table names itself (`pageSize`,
+  `openOnClick`); a page size picked in a table with a `stateKey` still wins there, and a size the table does not offer
+  is not forced on it. Until chosen (`null`), each table keeps its own.
+- **Interface language** is stored and read through `useUserPreferences()`; the package's own words are English for
+  now, and it does not set `lang` on `<html>` until they are translated (a screen reader would read English in a Nepali
+  voice).
+- `setUserPreferences({ … })` and `readUserPreferences()` (`nexus-shared/client`) change and read them from code, as
+  `setDatePreferences` does the date settings.
+
+## Components
+
+| Component | Import | Notes |
+|---|---|---|
+| `Button` | `nexus-shared` | Variants `primary`, `secondary`, `ghost`, `danger`; sizes `sm`, `md`, `lg`; `icon`, `iconEnd`, `loading`, `block`; `hoverTone` |
+| `TabButtons` | `nexus-shared/client` | Pick one option; sliding indicator; sizes, `tone="primary"`, `labels="selected"` (icons, label on the selected option), `block`, disabled options; `design="list"` for a vertical list with descriptions and badges; `multiple` to pick several, wrapping onto more rows |
+| `Tabs`, `TabPanel` | `nexus-shared/client` | Tabs that switch panels: a `tablist` in the look of `TabButtons` (`design` `list`, `nav`, or `auto`: the list, a strip in a container under 720px), the chosen tab the only one in the Tab order, arrows, Home and End; `TabPanel` joins the panel to its tab |
+| `SplitButton` | `nexus-shared/client` | A main action with a menu of alternatives; the pick becomes the main button, and `storageKey` remembers it for the next visit |
+| `Menu`, `ContextMenu` | `nexus-shared/client` | A dropdown menu under a button, and a right-click menu: icons, shortcuts, descriptions, `tone="danger"`, links, `kind="radio"` or `"checkbox"` |
+| `Toaster`, `toast` | `nexus-shared/client` | Toast messages from anywhere: `toast.success(title, message)`, `toast.promise`, `toast.loading`, actions, positions; one `<Toaster />` in the layout |
+| `Popup` | `nexus-shared/client` | A modal window on the native dialog, with the buttons of a desktop window: maximize, close, and minimize (a bar at the bottom right, content kept) only when it asks (`minimizable`: a CRUD page's Add, Edit and row forms do); moved by its title bar inside the window; title, description, scrolling body, footer, sizes `xs` to `full`, close reasons |
+| `PopupHost`, `openPopup` | `nexus-shared/client` | Popups opened from code with a handle (`close`, `update`, `minimize`, `maximize`, `restore`, `windowState`, `closed`), one per `key` (replaced or restored); one `<PopupHost />` in the layout, which also shows the minimized popups |
+| `definePopupRules` | `nexus-shared/client` | Rules for popups by key or `prefix-*` pattern, set once: `reopen` (replace or restore), `minimizable`, `maximizable`, `movable`, how it closes, `size`, `defaultWindowState` |
+| `useDraggable`, `makeDraggable`, `startDrag`, `moveWithin`, `clampToBounds` | `nexus-shared/client` | Move any element with the pointer (or the keyboard), kept inside bounds: the window, the parent, an element, or a box; by a handle, along one axis, partly outside; Esc puts it back |
+| `messageBox` | `nexus-shared/client` | `alert`, `confirm`, `prompt`, and `show` with any buttons, each returning a promise |
+| `TextBox` | `nexus-shared/client` | Text input: label designs `standard`, `outlined`, `inbox`; sizes; icons; `prefix`, `suffix`; `clearable`; show password; `showCount`; validation |
+| `TextArea` | `nexus-shared/client` | Multi-line text with the same field features; `autoResize` between `rows` and `maxRows` |
+| `CheckBox`, `Switch` | `nexus-shared/client` | One checkbox or on/off switch: `label`, `description`, `required` (must be checked), `indeterminate`, `readOnly`, `labelPosition` |
+| `CheckBoxGroup` | `nexus-shared/client` | Many choices from `options`: `min`, `max` (disables the rest at the limit), `selectAll`, `columns`, `design="cards"` |
+| `RadioGroup` | `nexus-shared/client` | One choice from `options`: arrow keys, `orientation`, `columns`, `design="cards"`, `design="tabs"` (nav-style tabs, descriptions as tooltips) |
+| `Dropdown` | `nexus-shared/client` | One value, or several with `multiple`, from `options` or server pages (`loadOptions`: search, infinite scroll, loaders, Retry); rows as `columns` like a data table (avatar, image, icon, code, money); saved values the list no longer offers (`selectedOptions`, `resolveOptions`, inactive items) show and cannot be picked again |
+| `Slider`, `RangeSlider` | `nexus-shared/client` | Pick a number or a range: `min`, `max`, `step`, number format with `prefix`/`suffix`, `marks`, `tooltip`, `minDistance`, `onValueCommit` |
+| `NumberBox` | `nexus-shared/client` | Numbers only: `min`, `max`, `decimals`, `fixedDecimals`, `grouping` by `locale`, `prefix`, `suffix`, `stepper`, `clamp`; the same field shell |
+| `DatePicker` | `nexus-shared/client` | Type or pick a date in the English (AD) or Nepali (BS) calendar from the user's settings; `min`, `max`, `isDateDisabled`; the value is always a Gregorian ISO date |
+| `DateRangePicker` | `nexus-shared/client` | A start and an end in one box, picked in a two-month calendar or typed; `startName` and `endName` send two fields; `minDistance`, `maxDistance` in days; booked nights cannot be included |
+| `TimePicker` | `nexus-shared/client` | Type or pick a time on a 12- or 24-hour clock from the user's settings: columns of hours and minutes or `view="list"` slots; `min`, `max` (past midnight too), `step` in seconds, `isTimeDisabled`; the value is always an ISO time |
+| `DateTimePicker` | `nexus-shared/client` | Type or pick a day and a time: each user sees their own local time in their date and time settings, and the value is always the UTC moment; `timeZone` for a place's zone, `min`, `max`, `minTime`, `maxTime`, `step`, `isDateDisabled`, `isTimeDisabled` |
+| `Calendar` | `nexus-shared/client` | The month grid on its own: single or `mode="range"`, `months={2}` side by side, month and year menus, arrow keys, `renderDay` for event markers, `weekStart` |
+| `useDatePreferences`, `setDatePreferences` | `nexus-shared/client` | The user's calendar, format, script, and time format, saved in local storage and followed by every date and time component |
+| `Form` | `nexus-shared/client` | A list of input params (`InputParams[]`) on a 12-column grid (`span`), with the values in a store outside React; `onFieldChange` for derived values, `validate` for rules across inputs, `draftKey` for unsaved changes that survive a reload, `loading` (the inputs disabled until the values land) |
+| `SubmitForm` | `nexus-shared/client` | A `Form` that checks every value on Save and focuses the first problem, then runs `onSubmit` once at a time; a status line with links to what needs attention; Save, Cancel (asks first), Reset; Ctrl+S |
+| `ApiForm` | `nexus-shared/client` | A `SubmitForm` that sends to an API (an endpoint such as `ROOMS.update`, `{ url, method }`, or the app's own client), loads the record first (`loadValue`), and shows the server's messages on their inputs: Nexus responses and ASP.NET Core problem details |
+| `FormButtons` | `nexus-shared/client` | A form's status line and buttons on their own, such as in a popup's footer; `submitTone="danger"` for a save that removes something |
+| `downloadText` | `nexus-shared/client` | Hands the user a file made from text in the browser (a CSV, recovery codes as a `.txt`), read as UTF-8 by Excel and Windows editors |
+| `useForm`, `useFormValue`, `useFormValues`, `useFormStatus` | `nexus-shared/client` | A store for the page to hold, and hooks that render again when a value, any value, or the status changes |
+| `FormStore` | `nexus-shared` | The store and the form's handle: `getValue`, `getChanges`, `set`, `load` (with `keepChanged`), `reset`, `validate`, `setErrors`, `focus`, `submit` |
+| `DataTable`, `useTable` | `nexus-shared/client` | Rows with a search (rows per page inside it), sorting by column, pages, a selection with one split button of actions over the headings, icon buttons and a menu per row, columns the user orders, resizes, pins, and hides, a band of headings over the columns that belong together (`group`), an options menu (filters from `filterInputs`, CSV, print, import), and loading, empty, and failed states; rows given, loaded once, or a page per query from a server; page size, sort, and the columns remembered with `stateKey`; a picked row (`onPick`) for a list beside it, and a `caption` |
+| `TableStore` | `nexus-shared` | The table's state and handle, outside React: `reload`, `upsert`, `patch`, `remove`, `select`, `getSelected`, `pick`, `setSearch`, `setFilters`, `setSort`, `setPage` |
+| `Crud` | `nexus-shared/client` | A module's records in one component: a controller's endpoints, the table's columns, and the form's input params in; the lists (all, flagged, trash, deleted) and actions the user may use, the records the user pinned above the list, Add and Edit popups on `ApiForm`, details, actions on one record or many, and a cache of lists while the page is open; a list narrowed to the record picked in another (`narrow`); a list widened to other endpoints by a switch in its toolbar (`scopes`); row actions that open a form of their own for the record (`rowForms`) |
+| `CrudTree` | `nexus-shared/client` | A controller's records as a lazy tree, with the `Crud`'s own Add and Edit forms and its trash, recover and delete calls: icons on each row, a toolbar Add New, and the picked record's fields and buttons for a panel the page draws; every change written into the tree and its kept pages, nothing read again |
+| `CrudTabFooter` | `nexus-shared/client` | The footer of a tab in a record's workspace: its words and Save in one bar that stays at the bottom of the tab while a long form scrolls, and sits in its place at the end; a plain bar elsewhere |
+| `RecordCards` | `nexus-shared/client` | One record that is not a list (a profile, my company) as a hero and cards of fields, of items with icon actions on the right, and of the page's own; every change in a popup (a form, steps such as a code sent then typed, a confirm), its answer drawn at once, and no Save on the page; loading held, a failed read per card with Try again, read-only, an ended session |
+| `MailThread`, `MailPeople`, `mailInboxColumns`, `mailRowUnread` | `nexus-shared/client` | A mail thread: its subject and people (From, To, Cc, Bcc as the backend shows them, folded to three names and "+2"), the record it is about, and the chat's own lines and reply box; a notification as an event line; the note a blind copy reads before replying; an inbox's columns and its strong unread row ([Mail thread](#mail-thread)) |
+| `MessageSource`, `apiMessageSource`, `localMessageSource`, `MessageBackend`, `NexusMessageBackend`, `defineMessageBackend` | `nexus-shared` (`apiMessageSource`: `/client`) | Where a mailbox's data comes from: the app's API through its backend (the Nexus Message module's `Mail` controller by default), or a mailbox in memory that keeps a backend's rules, for demos and tests |
+| `DomainCard`, `DomainCardFrame`, `DomainLine`, `useDomainCard` | `nexus-shared/client` | A record a message is about, as a card read live from its module: the kind an app gave a `card` on its `defineChatDomains` row (`domainCard({ load, view })`), drawn from params (title, code, state, fields, figures, lines, link) in every state - a placeholder that keeps its height, refused for 403 and 404, failed with Try again, read again when the record changes ([A record's card in a message](#a-records-card-in-a-message)) |
+| `MessageBell`, `useMessageUnread` | `nexus-shared/client` | The unread count on a top bar's button, one size whatever the count ("99+"), and the newest unread a click away; every bell of a page on one mailbox shares one read a minute, none while the tab is hidden ([Message bell](#message-bell)) |
+| `MessageUnreadPoller`, `messageUnreadPoller`, `refreshMessageUnread`, `mailUnreadWords` | `nexus-shared` | The page's one poller per mailbox, outside React, and the words a bell says |
+| `domainCardReads`, `refreshDomainCards`, `DomainCardRun`, `formatDays` | `nexus-shared` | One read of a record at a time, kept 30 seconds per reader; every card of a record read again when the page changed it; a card's read outside React; days written "1 day", "2.5 days" |
+| `pagedPicker`, `holdPickerItems`, `mailPeoplePicker`, `mailComposeDefaults` | `nexus-shared` | A dropdown over a server's search, paged, that names every value it holds (seen, handed over, looked up, or found in the first pages): people to send to; a new message's defaults for a CRUD's `form.createDefaults` |
+| `Permissions`, `NexusPermissions`, `definePermissions`, `canCall` | `nexus-shared` | May the user call this endpoint? The app registers its rules once; `NexusPermissions` reads the Nexus backend's access actions. Everything is allowed until then |
+| `CrudBackend`, `NexusCrudBackend`, `defineCrudBackend` | `nexus-shared` | How a CRUD talks to a backend beyond its endpoints: page requests and answers, mass action bodies, flag and pin marks. Nexus's by default |
+| `configureCrud`, `getCrudSettings` | `nexus-shared` | What every CRUD in the app follows: how many records a user may pin (100 by default) |
+| `queryRows`, `filterRequest`, `formatCellText`, `sortRows`, `pageButtons`, `CrudCache`, `crudRowActions` | `nexus-shared` | Pure helpers behind the table and the CRUD: search, filter, sort, and page rows as the table does, the filters in a server's names, a value as its cell writes it, the page buttons, the cache, and which actions a list offers |
+| `readApiResponse`, `readErrorMessages`, `sendApiRequest`, `matchFieldErrors`, `matchInputName`, `formErrorsFromResult` | `nexus-shared` | Pure helpers behind the API form: read an answer as success or failure, every problem it carries as one list, send a URL as it is, match server field names to inputs, and turn a failed answer into what a form shows |
+| `api`, `apiOptionsLoader`, `configureApi` | `nexus-shared/client` | API calls from the browser, through the app's proxy or straight to a module: toasts worded by the message builder, `api.confirm` to ask first, one request for the same GET at once; a dropdown's `loadOptions` from a pagination endpoint |
+| `serverApi`, `configureServerApi`, `createApiProxy` | `nexus-shared/server` | API calls from the server, straight to each module's root, with the user's token and Next.js caching; the proxy route the browser calls |
+| `ApiModules`, `NexusApiModules`, `defineApiModules`, `ApiRegister` | `nexus-shared` | An app's API modules: its own module enum (named once in `ApiRegister`, so endpoints take only those), where each root is, and the proxy on or off. Extend `ApiModules` for another backend |
+| `apiController`, `apiEndpoint`, `unwrapApiResult` | `nexus-shared` | Endpoints defined once by module: a controller's standard actions (`NormalListing`, `Detail/{id}`, `Create`, `Update`, `Delete/{id}`, each list's `lists.trash` and `pages.trash`, …); an answer's result, or an `ApiError` |
+| `messages`, `buildMessage`, `configureMessages` | `nexus-shared` | Every success, failure, reason, loading, question, and button text from one table: "3 rooms deleted.", "You do not have permission to delete Room 204."; reworded all at once |
+| `createApiClient` | `nexus-shared` | The engine behind `api` and `serverApi`, for an API of another shape |
+| `Field` | `nexus-shared` | The frame of every input (label, box, icons, hint or error), for building custom inputs |
+| `QrCodeImage` | `nexus-shared` | Any text as a QR code a phone can scan: one SVG path, black on white in every theme, 9rem wide (`nx-qr`); a server component can render it |
+| `PrintDocument` | `nexus-shared` | A receipt, bill or statement by params (head, stamp, facts, lines, totals, footer) on A5 or an 80 mm roll; printed alone, black on white (`nx-print`) |
+| `DocumentFrame` | `nexus-shared/client` | A whole HTML page a server wrote (a print layout's preview) in a sandboxed `<iframe srcdoc>` where no script runs: a bar with its status line and the page's buttons, slow and failed reads over the last page, `print()` through its handle (`nx-document-frame`) |
+| `encodeQr`, `qrPath` | `nexus-shared` | The encoder behind it, written by hand (byte mode, versions 1 to 40, levels L, M, Q and H), and its modules as one SVG path |
+| `validateText`, `TEXT_PATTERNS` | `nexus-shared` | Pure text validation and common patterns with their messages |
+| `validateCheck`, `validateSelection` | `nexus-shared` | Pure checks for a checkbox and for chosen values (`required`, `min`, `max`) |
+| `validateNumber`, `formatNumber`, `parseNumber` | `nexus-shared` | Pure number validation, and number text in any locale (`roundDecimal`, `stepNumber` too) |
+| `formatDate`, `parseDateText`, `toIsoDate`, `validateDate` | `nexus-shared` | Pure date helpers: ISO dates in and out, either calendar, any format, Devanagari digits; `toCalendar` and `fromCalendar` convert AD and BS |
+| `formatDateRange`, `parseDateRangeText`, `toDateRange`, `validateDateRange` | `nexus-shared` | The same for a range: "2026-09-17 – 2026-09-24" in and out, typed with a dash, an arrow, or "to"; rules on both ends and on the days between |
+| `filterItems`, `matchesSearch`, `indexItems`, `optionKey`, `initials` | `nexus-shared` | Pure helpers behind the dropdown: search every word with or without accents, index items by value, compare ids from APIs and forms, and initials for avatars |
+| `formatTime`, `parseTimeText`, `toIsoTime`, `validateTime` | `nexus-shared` | Pure time helpers: ISO times in and out, 12- or 24-hour formats, Devanagari digits, typed text on either clock; `addMinutes`, `isTimeInRange`, `listTimeSlots` |
+| `toUtcDateTime`, `toLocalDateTime`, `fromLocalDateTime`, `formatDateTime`, `parseDateTimeText`, `validateDateTime` | `nexus-shared` | Pure date-time helpers: UTC values in and out, the date and time a moment shows in any IANA zone (daylight saving included), typed text in both calendars; `describeTimeZone`, `getBrowserTimeZone` |
+| `ThemeScript` | `nexus-shared` | Applies the saved theme, mode, density and animations (and the scale grid in development) before paint; goes in `<head>` |
+| `ThemeSwitcher` | `nexus-shared/client` | Palette button with the theme picker in a popover: mode, theme, density, animations, and the scale grid in development |
+| `ThemePicker` | `nexus-shared/client` | Mode control and theme cards with live previews |
+
+### Tab buttons
+
+```tsx
+import { TabButtons } from "nexus-shared/client";
+
+<TabButtons
+  aria-label="View"
+  value={view}
+  onChange={setView}
+  options={[
+    { value: "grid", label: "Grid", icon: <InlineIcon icon={iconLayoutGrid} /> },
+    { value: "list", label: "List", icon: <InlineIcon icon={iconList} /> },
+  ]}
+/>
+```
+
+- An indicator slides to the selected option. In light mode the track is a soft tint with no frame and the indicator
+  is lifted by a shadow; in dark mode the indicator is lighter than the track, with a visible edge. The selected icon
+  takes the primary color, so the choice is clear in every theme.
+- `size` (`sm`, `md`, `lg`), `tone="primary"` for a solid primary indicator, `block` to fill the width, `disabled` per option.
+- `labels="selected"`: icons only, and the selected option grows to show its label. Every option needs an icon;
+  hidden labels are still read by screen readers and shown as tooltips.
+- `design="list"`: the options stacked as full-width rows, for settings pages and side panels. Each row takes an
+  `icon`, a `description` on a second line, and a `badge` (a count) at the end. The selected row is tinted, marked
+  by a bar at its start, and its label turns bold; `tone="primary"` tints it with the primary color. ↑ and ↓ move
+  the selection. The nav design is the old project's `nav-tabs`, this one its `list-tabs`.
+- `multiple`: several at once. `value` is an array and `onChange` hands back the chosen values in option order.
+  Each chosen option is raised as the one choice's indicator is, the options wrap onto more rows when they do not
+  fit (never narrower than tall, so single letters line up), and on a touch screen each grows to a medium control's
+  height. They are checkboxes: Tab moves between them and Space toggles one.
+- Native radio buttons: arrow keys move the selection, and `name` makes it part of a form. Needs `aria-label` or `aria-labelledby`.
+  `form` sets the form the choice belongs to, as in HTML; an id that matches no form keeps a switch that is not a
+  value (the Markdown editor's views) out of the form around it.
+- For choosing a value. For switching page panels, use tabs with panels (planned).
+
+### Split button
+
+```tsx
+import { SplitButton } from "nexus-shared/client";
+
+<SplitButton storageKey="pull-request" onAction={value => create(value)} options={[
+  { value: "create", label: "Create pull request", description: "Open a pull request that is ready for review" },
+  { value: "draft", label: "Create draft pull request", description: "Cannot be merged until marked ready for review" },
+]} />
+```
+
+- The main button runs the chosen action; the arrow opens the alternatives as a radio menu. Picking one makes it the
+  main button, and with `storageKey` the browser remembers it (`localStorage`, `nx-split:<key>`), so the next visit
+  starts with it. `runOnSelect` also runs the pick at once, for Save / Save and close.
+- `variant`, `size`, `loading`, `disabled`, `block` as `Button`; `type="submit"` with `name` submits a form and sends
+  the chosen value; `value` and `onValueChange` for a controlled choice; `align` and `menuLabel` for the menu.
+
+### Menus
+
+```tsx
+import { ContextMenu, Menu } from "nexus-shared/client";
+
+<Menu items={[
+  { value: "edit", label: "Edit", icon: <InlineIcon icon={iconPencil} />, shortcut: "Ctrl+E" },
+  { separator: true },
+  { value: "delete", label: "Delete", icon: <InlineIcon icon={iconTrash} />, tone: "danger" },
+]} onSelect={value => run(value)}>
+  <Button iconEnd={<InlineIcon icon={iconChevronDown} />}>Actions</Button>
+</Menu>
+
+<ContextMenu items={rowItems} onSelect={value => run(value, row)}>
+  <table>…</table>
+</ContextMenu>
+```
+
+- **Native popovers.** The list is a `[popover]` element: it sits above everything, closes with Esc or a click
+  outside, and needs no library. It opens under its button (above it when there is no room), lined up with the
+  button's `align="start"` or `"end"` edge, and follows the page as it scrolls.
+- **Items are params:** `{ value, label, description?, icon?, shortcut?, tone?: "danger", disabled?, href?, target?, checked?, title? }`,
+  plus `{ separator: true }` and `{ heading }`. An item with `href` is a link. The trigger is any element that
+  renders a button and passes its props on, such as `Button`.
+- `kind="radio"` or `"checkbox"` adds a check column and `aria-checked`; `closeOnSelect={false}` keeps a checkbox
+  menu open while options are toggled.
+- A `disabled` item fades its icon and label, not its `description`: give a switched-off item the reason it is off
+  there, and it is read at full strength. Descriptions wrap, even in a menu opened from a cell that does not.
+- **A held item** - `disabled` with a `description` - says that reason when it is pressed (a click, Enter or Space),
+  in the note a read-only field and a table's held Add show (`.nx-field-notice`, a `status`), beside the item, and the
+  menu stays open; the arrow keys reach it, so the keyboard can press it too. The note goes with the menu. A CRUD's
+  locked actions (`rowLock`, `rowActionLock`, a row form's `lock`) are held items.
+- **Keys:** arrows move between items (wrapping, skipping disabled ones without a reason), Home and End jump, a letter jumps to the
+  next item starting with it, Enter or Space chooses, Esc closes and returns focus to the button, Tab closes and
+  moves on. Focus follows a moving pointer, so the keys carry on from the hovered item.
+- `ContextMenu` opens at the pointer on right-click, or under the focused element on Shift+F10. Its wrapper takes no
+  space (`display: contents`), so wrap a table once and note the clicked row in the row's own `onContextMenu`.
+- A menu opens below its button, or above it when it fits only there, or on the side with more room when it fits on
+  neither, and is never taller than that room: its items scroll inside it, the scroll bar against the panel's right
+  wall. It opens scrolled to the top, and a hovered item never scrolls the list.
+- `placeUnderAnchor`, `placeAtPoint`, and `followAnchor` (`nexus-shared/client`) place custom popovers the same way, and
+  `showPanel` opens one with its scroller at the top. A panel (`.nx-popover`) that marks its scrolling part
+  `.nx-popover__scroll` is capped to the room it was placed in and gets the scroll bar on its wall; set its padding with
+  `--nx-popover-pad`. `usePopoverPanel` is a panel a menu item opens under a button, as the table's Filters and Columns
+  open.
+
+### Toast messages
+
+```tsx
+import { Toaster, toast } from "nexus-shared/client";
+
+// Once, in the root layout
+<Toaster position="top-right" />
+
+// Anywhere: components, services, fetch helpers
+toast.success("Booking confirmed", "Room 204, 3 nights");
+toast.error("Could not save", { message: error.message, action: { label: "Retry", onClick: save } });
+toast.promise(saveBooking(), { loading: "Saving…", success: "Saved", error: e => `Not saved: ${e.message}` });
+```
+
+- `toast(title, options?)`, `toast.info`, `.success`, `.warning`, `.error`, `.loading` (spinner, no timer), and
+  `.promise`. Options: `message`, `duration` (default 5000 ms, 0 keeps it; pauses while hovered or focused), `action`,
+  `closable`, `icon`, `position`, `onClose`, and `id` to update a toast in place. `toast.dismiss(id?)` closes one or all.
+- Each toast is a native popover of its own, so it sits above open dialogs; the newest is nearest the edge, and at
+  most `max` (default 5) show per position. Warnings and errors use `role="alert"`, the rest `role="status"`.
+
+### Popup
+
+```tsx
+import { Popup, definePopupRules, openPopup } from "nexus-shared/client";
+
+<Popup open={open} onClose={() => setOpen(false)} title="Edit booking" description="NX-2048 · Room 204"
+  footer={<><Button onClick={() => setOpen(false)}>Cancel</Button><Button type="submit" form="booking" variant="primary">Save</Button></>}>
+  <form id="booking" onSubmit={save}>…</form>
+</Popup>
+
+// From code, with a handle; needs <PopupHost /> in the layout. Never two popups with one key: opening the key again
+// replaces its popup (a fresh one), or with reopen: "restore" brings it back as it was.
+const popup = openPopup({ key: "room-edit-204", reopen: "restore", title: "Room 204", content: <RoomDetails id={204} />, footer: p => <Button onClick={() => p.close()}>Close</Button> });
+popup.minimize(); popup.restore(); popup.maximize();
+await popup.closed;
+
+// Rules by key, once, in a client module; options given to openPopup win over them
+definePopupRules({
+  "room-new": { reopen: "replace" },                  // Add: a fresh form every time (the default)
+  "room-edit-*": { reopen: "restore" },               // Edit: back as it was, with what was typed
+  "night-report": { minimizable: false, maximizable: false, movable: false },
+});
+
+// The page in charge of the window state
+<Popup open={open} windowState={state} onWindowStateChange={setState} … />
+```
+
+- Built on the native `<dialog>` shown modally: above everything, the page behind dimmed and locked (without a layout
+  shift), Tab kept inside, focus returned on close. `onClose(reason)` says whether the close button, Esc, the
+  backdrop, or code asked; the page decides by setting `open`. `closable`, `closeOnEscape`, `closeOnBackdrop` turn
+  those off for a popup that must be answered.
+- `size`: `xs` 360, `sm` 440, `md` 560, `lg` 720, `xl` 960, `full`. The body scrolls while the title and footer
+  stay; `flush` removes the body padding for tables. `initialFocus` picks the first focused element (default: an
+  element of the body or footer marked `data-nx-focus` - a mail thread marks its subject, so a long read opens at its
+  top - else the first control there). The content mounts only while open, so forms start fresh.
+- Popups open other popups and message boxes above themselves; Esc closes the top one.
+- A **title bar** like a desktop window's: 32px high (40px on touch screens), the icon, the title, and the description
+  on one line (cut with …), and the window buttons filling its top right corner, 46 x 32 each: **minimize** (only when it asks),
+  **maximize** (restore down when maximized), **close** (red on hover). `variant="dialog"` gives the larger heading
+  instead (the icon in a circle, the description under the title), which message boxes use. `minimizable` (default false: a popup has no minimize button unless it asks; a CRUD page's Add and Edit forms and its row forms ask, and a page's rule for their key may still say no; message boxes, viewers, galleries, histories, imports, record cards and the rest do not),
+  `maximizable` and `movable` (default true); message boxes have only close.
+- **Minimized**, the dialog closes so the page can be used, and a bar waits at the bottom right with the popup's icon and
+  title; its content stays mounted, so typed text, scroll, and the focused field are there when the bar brings it back
+  (maximized again if it was). Several stack behind the newest with a count that opens the whole list (Esc or a press
+  elsewhere closes it). An open popup's backdrop covers the dock. `<PopupHost />` renders the dock; without a host
+  there is no minimize button. Bottom-right toasts stack above it (`--nx-dock-space`).
+- **Maximized**, it fills the window edge to edge; a double-click on the title bar does the same, and restore down puts
+  it back where it was.
+- **Moved** by its title bar (not its buttons), kept inside the window, pulled back in when the window shrinks; Esc
+  during a drag puts it back; dragging a maximized popup restores it under the pointer, as desktop windows do. Each
+  opening starts centered in `defaultWindowState`.
+- **Opened again** while it is still open or minimized, a popup never doubles up. `openPopup` with a `key` whose popup
+  is there closes that popup (`onClose` and `closed` say `replaced`) and opens a fresh one: `reopen: "replace"`, the
+  default, right for an Add form, so Add, minimize, Add again cannot pile up popups. `reopen: "restore"` brings the
+  old one back as it was and returns its handle, right for editing one record. A page popup opens again through the
+  button that opened it, with the same `reopen` choice. Popups without a key are separate every time.
+- **Asking before a close**: `openPopup({ beforeClose })` runs when the user closes the popup (its close button, Esc,
+  the backdrop, or its bar on the dock); return `false`, or a promise of it, to keep it open, such as after
+  `confirmDiscard(form)` asked "Discard your changes?". Closing from code does not ask.
+- **Rules by key**: `definePopupRules({ "booking-new": {…}, "booking-edit-*": {…} })` sets `reopen`, `minimizable`,
+  `maximizable`, `movable`, `closable`, `closeOnEscape`, `closeOnBackdrop`, `size`, and `defaultWindowState` for every
+  `openPopup` with that key. A name ending in `*` matches keys that start with the rest (`*` alone, every key); all
+  matching rules apply, an exact key over a pattern and a longer pattern over a shorter one; options given to
+  `openPopup` win. It returns a function that removes the rules; `popupRuleFor(key)` shows what a key gets.
+- With motion, minimize flies to the dock and maximize grows from the old box; with reduced motion, both happen in the
+  same frame.
+
+### Drag helpers
+
+```tsx
+import { clampToBounds, makeDraggable, moveWithin, useDraggable, viewportBounds } from "nexus-shared/client";
+
+useDraggable(cardRef, { bounds: "parent" }); // the card moves, kept inside its positioned parent
+useDraggable(barRef, { target: () => cardRef.current, bounds: "parent", axis: "x", keepVisible: 40 });
+const stop = makeDraggable(titleBar, { target: panel, bounds: document.querySelector(".board") }); // without React
+moveWithin(card, { x: 10, y: 0 }, { bounds: "parent" }); // the keyboard way
+clampToBounds({ left: -20, top: 40, width: 300, height: 200 }, viewportBounds()); // { x: 0, y: 40 }
+```
+
+- The popup's title bar is built on these; any component can use them. `bounds`: `viewport` (default), `parent`,
+  an element (inside its borders), a box, a function, or `null`. `margin`, `keepVisible` (how much must stay
+  inside when it may partly leave), `axis`, `threshold` (default 3 px, so clicks stay clicks), `cancel` (controls in
+  the handle that do not drag).
+- The position is an offset from the element's place in the layout, written to CSS `translate` by default, or to CSS
+  variables (`cssVariablePosition`), or anywhere through `position: { get, set }`, so a move never shifts the layout.
+- `onStart` may cancel or change the target first; `onEnd` says whether Esc cancelled. A drag selects no text, and
+  the click that ends it does not reach what lies under the pointer. The handle needs `touch-action: none`
+  (`makeDraggable` and `useDraggable` set it).
+
+### Message box
+
+```tsx
+import { messageBox } from "nexus-shared/client";
+
+if (await messageBox.confirm({ title: "Delete booking NX-2048?", message: "This cannot be undone.", tone: "danger", confirmLabel: "Delete" })) …
+await messageBox.alert({ title: "Saved", tone: "success" });
+const name = await messageBox.prompt({ title: "Rename the room", label: "Name", defaultValue: room.name });
+const choice = await messageBox.show({ title: "Unsaved changes", tone: "warning", buttons: [{ value: "discard", label: "Don't save" }, { value: "save", label: "Save" }] });
+```
+
+- Small popups through `<PopupHost />`, the tone in the icon: `info` (alert default), `question` (confirm default),
+  `success`, `warning`, `danger`, or `neutral` for none. A danger box makes the last button red and focuses the first
+  one, so Enter cannot delete by accident.
+- `confirm` resolves `false` and `show` resolves `null` when the box is dismissed with Esc, the close button, or a
+  click outside; `prompt` resolves `null` when cancelled and refuses an empty answer while `required` (the default).
+- `details` puts what the question is about after the message, in the normal text colour (the message is muted), and
+  scrolls with the body while the buttons stay: `details: <CrudDetails row={order} columns={ORDER_COLUMNS} />` with a
+  `size` of `lg` or `xl`. `closeOnBackdrop: false` keeps a box with much to read open through a stray click (Esc and ×
+  still dismiss it, and the focus stays where it was); `signal` dismisses it when the page or form that asked goes.
+- The message and the details describe the box to a screen reader (`aria-describedby`), so they are read with the
+  title as the focus enters. A held Enter, or one within 300 ms of the Enter before it (the one that opened the box,
+  pressed twice), never answers a box; the next deliberate Enter does.
+
+### Button hover tones
+
+`hoverTone` keeps a `secondary` or `ghost` button neutral until it is hovered or focused from the keyboard, then
+colors its border, a light background, and its text. Tones: `primary`, `danger`, `success`, `warning`, `info`.
+Good for rows of actions, where full-color buttons would be too loud:
+
+```tsx
+<Button hoverTone="danger" icon={<InlineIcon icon={iconTrash} />}>Delete</Button>
+<Button variant="ghost" size="sm" hoverTone="primary" aria-label="Edit" icon={<InlineIcon icon={iconPencil} />} />
+```
+
+Every tone meets WCAG AA contrast on its light background in all themes.
+
+### Text box
+
+```tsx
+import { TEXT_PATTERNS } from "nexus-shared";
+import { TextBox, TextArea } from "nexus-shared/client";
+
+<form onSubmit={save}>
+  <TextBox name="email" type="email" label="Email" required pattern={TEXT_PATTERNS.email} icon={<InlineIcon icon={iconMail} />} />
+  <TextBox name="password" type="password" label="Password" required minLength={8} />
+  <TextArea name="notes" label="Notes" maxLength={500} showCount autoResize />
+  <TextArea name="html" label="Layout HTML" rows={18} code />
+  <Button type="submit" variant="primary">Save</Button>
+</form>
+```
+
+- **Uncontrolled by default**, so typing re-renders nothing. `onValueChange(value)` reports each change; `value` makes it controlled.
+- **Code text: `TextArea code`** (in a form's inputs, `{ type: EInputTypes.TextArea, code: true }`). HTML or JSON in the
+  monospace font, lines kept as typed (`wrap="off"`: a long line scrolls sideways inside the box), a tab two spaces
+  wide, and no spellcheck, capitals, corrections, suggestions or translation. Tab still leaves the box, so a keyboard
+  is never trapped in it; read-only and disabled code keep the look.
+- **Validation:** `required`, `minLength`, `maxLength`, `pattern` (a `TEXT_PATTERNS` entry carries its own message), and
+  `validate(value)` for custom rules. Messages show after a field is left with text in it (`validateOn`: `blur`, `change`,
+  `submit`). Inside a `<form>`, an invalid field blocks submit, every message shows, and the first invalid field takes focus.
+  `error` shows a message from outside, such as the server. `invalid` (on `Field` and `Dropdown`) draws the invalid look
+  with no message line, for a field the page says why about elsewhere: point its `aria-describedby` at those words.
+- **Read-only says why.** Every input with `readOnly` shows a lock, and a short note for 2.5 seconds when someone tries
+  to change it anyway, so a click that does nothing does not look like a bug. The value is still sent with a form, and
+  selecting and copying text work as usual. Esc, leaving the field, or the timeout hide the note; `readOnlyMessage`
+  changes its text.
+
+  | Input | Lock | Tries that show the note | Default note |
+  |---|---|---|---|
+  | `TextBox`, `TextArea` | End of the box | A click, typing, Backspace, Delete, Ctrl+V, Ctrl+X (and Enter in a text area) | Read-only: this field cannot be changed. |
+  | `NumberBox` | In place of the − and + buttons | The same, and ↑ ↓ Page Up Page Down | Read-only: this number cannot be changed. |
+  | `DatePicker`, `DateRangePicker` | In place of the calendar button | The same as a text box, and ↓ | Read-only: this date (these dates) cannot be changed. |
+  | `TimePicker` | In place of the clock button | The same as a text box, and ↓ | Read-only: this time cannot be changed. |
+  | `DateTimePicker` | In place of the calendar and clock button | The same as a text box, and ↓ | Read-only: this date and time cannot be changed. |
+  | `Dropdown` | In place of the list button; chips lose their remove buttons | A click on the box or a chip, a typed key, ↓ or ↑ | Read-only: this choice (these choices) cannot be changed. |
+  | `CheckBox`, `Switch` | After the label | A click or Space | Read-only: this option (this setting) cannot be changed. |
+  | `CheckBoxGroup`, `RadioGroup` | After the group label | A click, Space, or an arrow key, under that option | Read-only: these options (this choice) cannot be changed. |
+  | `Slider`, `RangeSlider` | After the label | A press on the track or a mark, the arrow keys, Page Up/Down, Home, End | Read-only: this value (this range) cannot be changed. |
+
+  Nothing renders until an attempt, and an attempt re-renders only the note, so read-only forms of any size cost
+  nothing extra. `useReadOnlyNotice` gives a custom control the same lock and note.
+- **Props are params:** plain, named like HTML attributes, and serializable, so forms and CRUD pages can describe
+  fields as objects. Design notes for inputs, forms, and CRUD: [src/Components/Inputs/README.md](src/Components/Inputs/README.md).
+
+### Number box
+
+```tsx
+import { NumberBox } from "nexus-shared/client";
+
+<NumberBox name="nights" label="Nights" stepper="split" required min={1} max={30} defaultValue={1} />
+<NumberBox name="rate" label="Rate per night" prefix="Rs" required min={500} decimals={2} fixedDecimals grouping locale="en-IN" />
+<NumberBox name="discount" label="Discount" suffix="%" stepper min={0} max={50} step={5} />
+```
+
+- **Only a number gets in.** Typing accepts digits, one decimal separator, and a minus sign when `min` is below 0 (or
+  not set). `decimals` stops typing after that many decimals; pasted text such as "Rs 1,250.50" keeps its number, and
+  text with no single clear number is ignored rather than guessed at.
+- **Formats by locale:** `grouping` shows 12,50,000.00 (`en-IN`) or 1.250.000,00 (`de-DE`) while the box is not
+  being edited; separators come off on focus. Without a `locale`, the box follows the person's Number scale and
+  Thousands separator (`useNumberLocale`, see Quick preferences), which is `en-US` until they choose, so the server
+  renders that and the browser takes the saved choice right after hydration.
+  Inside a `<form>`, a grouped box sends the plain number through a hidden input with its `name`.
+- **Steps:** ↑ and ↓ (Shift or Page Up/Down for ten), and `stepper` buttons that repeat while held. Values move along
+  the grid of `step` from `min` and stay within the limits.
+- **Values:** `onValueChange(value)` gets a `number`, or `null` when empty; `validate(value)` too. `clamp` moves an
+  out-of-range value to the nearest limit on blur instead of showing a message.
+- `npm run test:numbers` checks the number helpers (formatting, parsing, paste, rounding, stepping, messages).
+
+### Checkbox and radio
+
+```tsx
+import { CheckBox, CheckBoxGroup, RadioGroup, Switch } from "nexus-shared/client";
+
+<RadioGroup name="roomType" label="Room type" required design="cards" columns={3} options={roomTypes} />
+<CheckBoxGroup name="amenityIds" label="Amenities" columns={3} selectAll options={amenities.map(a => ({ value: a.id, label: a.name }))} />
+<Switch name="breakfast" label="Breakfast included" labelPosition="start" />
+<CheckBox name="terms" label="I accept the booking terms" required />
+```
+
+- **Native inputs, drawn with CSS.** Each option is one `<input>`, so forms, arrow keys (radios), and screen readers
+  work as usual. Box edges use the subtle text color, which meets 3:1 contrast on panels in every theme.
+- **Options are params:** `{ value, label, description?, icon?, disabled? }`. Values can be strings or numbers and
+  come back from `onValueChange` with their type.
+- **Limits:** `required`, `min`, `max`, `validate`. At `max` a checkbox group disables the other options and shows a
+  count. Messages follow the text box: after leaving a changed group, or on submit, where the first invalid option takes focus.
+- **Fast:** uncontrolled by default, so clicking re-renders nothing; 10,000 checkboxes mount in 0.5 to 0.7 s
+  in the development build.
+
+**A choice drawn as tabs.** `<RadioGroup design="tabs" />` (or `design: "tabs"` in its params) draws the options as
+nav-style tabs on one `TabButtons` track - still a radio group: arrow keys, `required`, read-only and disabled work as
+in the other designs, and the tabs wrap on a phone. Each option's `description` is its tooltip and what a screen reader
+hears with it; the chosen one's shows under the track.
+
+```tsx
+{ type: EInputTypes.RadioGroup, name: "counterType", label: "What is it?", required: true, design: "tabs", options: [
+  { value: 0, label: "Payment", description: "Renew: the dates move, the money is taken now." },
+  { value: 1, label: "Activate", description: "Switch the service on for a time, with no money." },
+] }
+```
+
+### Slider
+
+```tsx
+import { RangeSlider, Slider } from "nexus-shared/client";
+
+<Slider name="discount" label="Discount" max={50} suffix="%" defaultValue={10} />
+<RangeSlider name="price" label="Price per night" min={1000} max={30000} step={500} minDistance={1000}
+  prefix="Rs " grouping locale="en-IN" onValueCommit={([from, to]) => loadRooms(from, to)} />
+```
+
+- **Native range inputs** under a drawn track, so arrow keys, Page Up/Down, Home/End, touch, and screen readers work.
+  Each thumb announces its formatted value (`aria-valuetext`).
+- **Values read like a number box:** `prefix`, `suffix`, `decimals`, `grouping`, `locale`, or a `format` function.
+- **`onValueChange`** follows every step; **`onValueCommit`** fires once when a thumb is released or a key step ends,
+  the moment to call an API from a filter.
+- **Range:** two thumbs that never cross and keep `minDistance` apart; a click on the track moves the nearer thumb.
+  A form receives two values under the name.
+- **Marks** label points under the track and move the thumb when clicked; **`tooltip`** shows the value above the thumb.
+- Dragging writes the fill and the text straight to the DOM, so nothing re-renders.
+
+### Date picker and date range picker
+
+```tsx
+import { todayIsoDate } from "nexus-shared";
+import { Calendar, DatePicker, DateRangePicker, setDatePreferences } from "nexus-shared/client";
+
+<DatePicker name="checkIn" label="Check-in" required min={todayIsoDate()} onValueChange={iso => …} />
+<DatePicker name="fiscalYearStart" label="Fiscal year start" calendar="bs" format="YYYY/MM/DD" />
+<DateRangePicker startName="checkIn" endName="checkOut" label="Stay" required min={todayIsoDate()} minDistance={1} maxDistance={30} />
+<Calendar mode="range" months={2} range={range} onRangeChange={setRange} min={todayIsoDate()} />
+
+// A settings page
+setDatePreferences({ calendar: "bs", format: "D MMMM YYYY", script: "devanagari" });
+```
+
+- **The value is a day, not a time.** An ISO date `"2026-09-17"` in the Gregorian calendar, whatever calendar is
+  shown: what a form sends (through a hidden input with the field's `name`), what an API stores (`DateOnly`), and
+  what means the same day in every time zone. `toIsoDate` reads a `Date` in local time and an ISO date-time with a
+  zone as the local day of that instant; `isoDateToDate(iso)` gives UTC midnight, `isoDateToDate(iso, "local")` local midnight.
+- **English or Nepali from the user's settings.** `useDatePreferences` reads `nx-date-calendar` (`ad` or `bs`),
+  `nx-date-format`, and `nx-date-script` (`latin` or `devanagari`) from local storage, with the English calendar in
+  `YYYY-MM-DD` as the default; `setDatePreferences` changes every date component on the page, and other tabs follow.
+  A box can fix its own `calendar`, `format`, or `script`.
+- **Formats** use the tokens `YYYY` `YY` `MMMM` `MMM` `MM` `M` `DD` `D` `dddd` `ddd`. Typing follows the format's
+  order and is lenient: `17/9/2026`, `Sep 17, 2026`, `1 asoj 2083`, `२०८३-०६-०१`; a four-digit number is the year wherever it stands.
+- **Bikram Sambat** covers BS 1975 to 2100 (AD 1918 to 2044), as the majority of five published tables
+  (`NepaliCalendar.ts`), converted through day numbers with no `Date` objects. `npm run test:dates` checks known
+  dates and round-trips every day.
+- **DateRangePicker** holds a start and an end in one box, written as "2026-09-17 – 2026-09-24" in the user's
+  format. Pick the start and then the end in a calendar of two months (one when the window is narrow), with the
+  days between lit as the pointer moves, or type both dates around a dash, an arrow, or "to". The values are two
+  ISO dates: `onValueChange` gives `[start, end]` (`null` for an end not chosen yet), and a form sends `startName`
+  and `endName` as two fields, or both under `name`. Rules: `required`, `min`, `max`, `minDistance` and
+  `maxDistance` (days from start to end, the nights of a stay), and `isDateDisabled`, which also refuses a range
+  that includes such a day (a booked night). `validateDateRange` is the pure check behind it.
+- **Read-only** boxes have no calendar: a lock sits where the calendar button was, and a click, a typed key, or ↓
+  shows a note under the box, as in every read-only input (see [Text box](#text-box)).
+- **Calendar** is the pickers' panel and a component of its own: month and year menus, arrow keys (Page Up and Page
+  Down for months, with Shift for years), `min`, `max`, `isDateDisabled`, `weekStart`, `weekendDays` (Saturday is
+  red in the Nepali calendar), `mode="range"` with a live preview, `months={2}` side by side (a page passes 1 on
+  a phone; the calendar does not measure), `month` and `onMonthChange` to load a month's events, and `renderDay`
+  to draw markers in a cell.
+
+### Time picker
+
+```tsx
+import { TimePicker, setDatePreferences } from "nexus-shared/client";
+
+<TimePicker name="arrival" label="Arrival" required min="14:00" max="22:00" step={1800} view="list" onValueChange={iso => …} />
+<TimePicker name="shiftStart" label="Shift start" min="22:00" max="06:00" format="HH:mm" />
+<TimePicker name="spa" label="Spa slot" view="list" step={1800} isTimeDisabled={iso => booked.has(iso)} />
+
+// A settings page
+setDatePreferences({ timeFormat: "HH:mm" });
+```
+
+- **The value is a time of day, not an instant.** An ISO time on a 24-hour clock, `"14:30"` (`"14:30:15"` when
+  `step` has seconds), with no date and no zone: what a form sends through a hidden input with the field's `name`,
+  and what a .NET `TimeOnly` stores. `toIsoTime` reads `"9:05"`, `"14:30:00.000"`, a `Date` (its local time), and an
+  ISO date-time (with a zone, the local time of that instant; without one, its time part).
+- **12 or 24 hours from the user's settings.** `nx-time-format` in local storage, next to the date settings, holds
+  a format of tokens `HH` `H` `hh` `h` `mm` `m` `ss` `s` `A` `a`; the default is `hh:mm A` (02:30 PM).
+  `useDatePreferences` returns it as `timeFormat`, and `setDatePreferences({ timeFormat })` changes every time picker
+  on the page. Nepali dates in Devanagari bring Nepali digits and पूर्वाह्न/अपराह्न. A box can fix its own `format` or `script`.
+- **Typing** works on either clock: `2:30 pm`, `2.30p`, `230pm`, `14:30`, `1430`, `9`, `१४:३०`. Without AM or PM the
+  hours are read on a 24-hour clock. Leaving the box writes the time in the format.
+- **Columns** (the default) show hours, minutes, seconds when the step needs them, and AM/PM; the chosen items line
+  up on the middle row, a pick in any column changes the time at once, and ↑ ↓ ← → Home End Page Up/Down move through
+  them. **`view="list"`** shows one slot per `step` (every 30 minutes for steps under 5 minutes); a click or Enter
+  picks and closes.
+- **Rules:** `required`, `min` and `max` (with `max` earlier than `min` the range runs past midnight, 22:00 to 06:00),
+  `step` in seconds counted from midnight as in HTML, `isTimeDisabled` for booked slots, and `validate`. Items outside
+  the rules are dimmed in the panel; a typed time outside them gets a message such as "Arrival must be in steps of 30
+  minutes, like 02:00 PM or 02:30 PM." `validateTime` is the pure check behind it. `npm run test:times` checks the helpers.
+- **Read-only** boxes have no panel: a lock sits where the clock button was, as in every read-only input.
+
+### Date and time picker
+
+```tsx
+import { DateTimePicker } from "nexus-shared/client";
+
+<DateTimePicker name="pickupAt" label="Airport pickup" required min={new Date()} step={900} minTime="05:00" maxTime="23:00" />
+<DateTimePicker name="checkInAt" label="Check-in" timeZone="Asia/Kathmandu" defaultTime="14:00" />
+<DateTimePicker name="spaAt" label="Spa slot" view="list" step={1800} isTimeDisabled={(time, date) => booked.has(`${date} ${time}`)} />
+```
+
+- **The value is a moment, in UTC.** `"2026-09-17T08:45:00.000Z"`, the shape `toISOString` writes, is what the hidden
+  input sends and `onValueChange` gives, whatever the user sees; the same moment is 02:30 PM in Kathmandu and 04:45 AM
+  in New York, so no time zone can move a saved value. Store it as UTC: a .NET `DateTimeOffset`, or a `DateTime` of
+  kind `Utc`. For a day with no time use `DatePicker`; for a time of day with no date, `TimePicker`.
+- **Values in** (`toUtcDateTime`): an ISO date-time with `Z` or an offset is that moment; one **without a zone is read
+  as UTC**, the way a UTC `DateTime` loaded from a database often arrives without its `Z`; a date alone is the first
+  moment of that day where the user is; a `Date` or milliseconds are that moment. .NET's seven digits of fractions are read.
+- **Shown in the user's zone and settings.** The browser's time zone, and the date (`nx-date-calendar`,
+  `nx-date-format`, `nx-date-script`) and time (`nx-time-format`) settings of the other pickers: "2026-09-17 02:30 PM",
+  or "२०८३-०६-०१ ०२:३० अपराह्न". The panel names the zone ("Kathmandu · UTC+05:45"). `timeZone` fixes a zone, such as a
+  hotel's, and writes its city in the box. The server does not know the user's zone, so a box shows its text right
+  after hydration rather than another zone's time for a moment; the hidden input holds the value from the start.
+- **No data loss.** A value changes only when the user changes what it shows: seconds and milliseconds the box does not
+  show stay as they came (a stamp from the server is sent back exactly), and retyping or re-picking what it shows keeps
+  the moment. Where clocks go back, one hour happens twice: a box holds whichever it was given, an edit inside that hour
+  keeps its offset, and a new pick is the first of the two. Where clocks go forward, a skipped time moves on (02:30
+  becomes 03:30), as `Date` and Temporal do.
+- **Typing:** a date in the user's format, then a time on either clock: `2026-09-17 2:30 pm`, `17/09/2026 14:30`,
+  `Sep 17, 2026 at 2:30 PM`, `2026-09-17T14:30`, `२०८३-०६-०१ १४:३०`. A date alone takes `defaultTime` (default
+  `minTime`, or midnight). Leaving the box writes it in the settings.
+- **The panel** is the calendar and the time columns (or `view="list"` slots) side by side, as tall as each other, with
+  Now, the zone, and Done. A picked day keeps the time; ↓ opens it on the chosen day, Enter on a day moves on to the
+  hours, and Tab runs through the calendar, the columns, and the buttons. On a phone the time goes under the calendar,
+  and a panel taller than the room scrolls, moving to the time once a day is picked.
+- **Rules:** `required`; `min` and `max` as moments (days outside are dimmed, and times outside on the first and last
+  day); `minTime` and `maxTime` as opening hours on every day (past midnight when `maxTime` is earlier); `step` in
+  seconds from each midnight; `isDateDisabled(date)` and `isTimeDisabled(time, date)` with ISO dates and times where the
+  user is; `validate`. Messages read like the box: "Airport pickup must be between 05:00 AM and 11:00 PM."
+  `validateDateTime(value, rules, fieldName, options)` is the pure check. `npm run test:datetimes` checks the helpers
+  against `Date` in eight zones, including half-hour daylight saving and a skipped day.
+- **Read-only** boxes have no panel: a lock sits where the button was, as in every read-only input.
+
+### Dropdown
+
+```tsx
+import { Dropdown } from "nexus-shared/client";
+
+<Dropdown name="roomType" label="Room type" required options={roomTypes} />
+<Dropdown name="amenities" label="Amenities" multiple max={6} options={amenities} />   // { value, label, icon: "wifi" }
+
+// Rows like a data table
+<Dropdown name="assignee" label="Assign to" options={staff} valueKey="id" labelKey="fullName"
+  columns={[{ key: "photo", type: "avatar" }, { key: "username", header: "Username" }, { key: "fullName", header: "Full name" }]} />
+<Dropdown name="country" label="Country" options={countries} valueKey="code" labelKey="name"
+  columns={[{ key: "flag", type: "image" }, { key: "code", header: "Code", type: "code" }, { key: "name", header: "Country" }]} />
+
+// A server list, editing a saved value
+<Dropdown name="guestId" label="Guest" valueKey="id" labelKey="fullName" defaultValue={booking.guestId} selectedOptions={[booking.guest]}
+  loadOptions={({ search, skip, pageSize, signal }) => api.guests({ search, skip, take: pageSize }, signal)} />  // { items, total }
+```
+
+- **Options are any objects.** `{ value, label, description, icon, disabled }` by default (a `ChoiceOption`), or API rows
+  read through `valueKey`, `labelKey`, `descriptionKey`, and `iconKey`. Values keep their type; a number and its text
+  are the same value, so id 7 from an API matches "7" from a form. A form gets hidden inputs named `name`, one per value.
+- **Columns** turn rows into cells that line up down the list (one grid with subgrid rows), with headings that stay on top.
+  Types: `text`, `muted`, `code`, `avatar` (a photo URL, or initials of the label on a soft tone), `image` (4:3: flags,
+  logos), `icon` (a Tabler name), and `money` (a figure with 2 places in the person's number format, at the end of its
+  column in even digits: a fee's price beside its name); `width`, `align`, and `render` for the rest. The first
+  picture leads the value in the box and in chips.
+- **Search** matches every typed word in any order, with or without Latin accents, in the label, description, value, and
+  text columns (`searchKeys` to change). It is on with `loadOptions` or more than 8 options; without it, letters jump to
+  an option as in a native select. A local list renders 100 rows and adds more while it scrolls: 10,000 options open in
+  about 30 ms.
+- **Server pages:** `loadOptions({ search, page, pageSize, skip, signal })` returns `{ items, total?, hasMore? }`. The first
+  page loads when the list opens (placeholder rows, a spinner in the box), the next near the end ("Loading more…"), a new
+  search 250 ms after typing stops, aborting the request before it. A failure shows Retry. `loadKey` drops the loaded
+  pages, for a list that depends on another field. `loading` shows the same loaders when the page fetches `options` itself.
+- **Saved values the list can no longer offer** always show, and are never offered again once removed:
+  - on a server page not loaded: `selectedOptions` gives their items (a record usually carries the name),
+    `peekOption(key)` gives one the page already holds while it is fresh (no call; `crudPicker` gives it), or
+    `resolveOptions(values)` looks them up (a placeholder shows until it answers) - one the page marked old too;
+  - inactive items (`inactive: true` or `isActive: false`, or `isOptionInactive`): never in the list, shown only as a value;
+  - values missing from `options`: tagged **Unavailable**, or **Not found** when nothing is known but the value.
+
+  In the list they sit on top under **Selected** with their tag; in the box they carry the tag, or show as dashed chips.
+  A value only on another server page has no tag: a search finds it as a normal option.
+- **Rules:** `required`, `min` and `max` for several (at `max` the other options are disabled), and `validate`, through
+  `validateSelection`. A pick follows the same message timing as typing. `npm run test:dropdown` checks the helpers.
+- **Keys:** ↓ ↑ Page Up/Down Home End move past rows that cannot be picked, Enter picks, Space picks without search,
+  Backspace in an empty box removes the last value, Esc closes (then clears the search), Tab closes and moves on.
+- **Read-only** boxes have no list: a lock sits where the list button was, chips lose their remove buttons, and a click or
+  a key shows the note, as in every read-only input.
+
+### Markdown editor
+
+```tsx
+import { MarkdownView } from "nexus-shared";
+import { MarkdownEditor } from "nexus-shared/client";
+
+<MarkdownEditor name="description" label="Room description" defaultValue={room.description} defaultMode="split"
+  height={320} heightKey="room-description" maxLength={5000} required />
+
+// Wherever the text is shown, also in a server component
+<MarkdownView value={room.description} />
+```
+
+- **Write, split, and preview.** `defaultMode` (or `mode` with `onModeChange`) picks the view, and `modes` the views
+  offered. The switch is small tab buttons with `labels="selected"`: icons, and the label of the selected view. Split puts the preview beside the text and keeps the two scrolled together; under 560 px wide it stacks
+  them. The preview renders as a React transition, so typing stays within a frame in a 2,000-line document.
+- **Toolbar and shortcuts:** heading, bold (Ctrl+B), italic (Ctrl+I), strikethrough (Ctrl+Shift+X), quote
+  (Ctrl+Shift+.), code (Ctrl+E), code block, link (Ctrl+K), image, bulleted, numbered, and task lists (Ctrl+Shift+8,
+  7, L), table, and horizontal line. Marks wrap the selection or the word at the caret and come off when applied
+  again. Edits go through the browser's own editing, so Ctrl+Z undoes them. `toolbar` picks and orders the buttons.
+  Under 560 px they take a row of their own; `toolbarOverflow="menu"` keeps one row at any width instead, the buttons
+  that do not fit in a "More formatting" menu at its end (`fitToolbar` works out which) - a chat's reply box does, so a
+  phone keeps its room for the lines.
+- **While typing:** Enter continues a list (the next number, an empty task box) and ends it on an empty item; a URL
+  pasted over selected text links it; a task ticked in the preview is ticked in the text.
+- **Height handle:** the status bar under the editor drags the height between `minHeight` and `maxHeight`, showing
+  the height as it changes; its grip takes ↑ ↓ (Shift for more), Page Up/Down, Home, and End; a double-click goes back
+  to `height`. `heightKey` remembers the user's height in local storage. Dragging writes straight to the DOM.
+- **Full screen** (`fullscreen`, on by default) lifts the editor into the top layer over a dimmed page, without
+  moving it in the DOM, so undo history and the form stay. Tab stays inside, and Esc closes it.
+- **A form field like `TextArea`:** `name`, `required`, `minLength`, `maxLength`, `pattern`, `validate`, the status bar's
+  word and character count, and read-only (a lock in the bar and a note under it). An invalid submit while the preview
+  shows brings the text back and focuses it. The view switch belongs to no form (`TabButtons` `form`), so it is never sent.
+- **Safe to show anyone's text.** `parseMarkdown` (GitHub-flavored: tables, tasks, strikethrough, autolinks) never
+  renders raw HTML, and `safeUrl` keeps only http, https, mailto, tel, and relative addresses for links, and raster
+  data URLs for images. Links to other sites get `rel="nofollow noopener noreferrer"`.
+- **Helpers:** `markdownToPlainText` for excerpts and search, and the editing commands `applyMarkdownTool`,
+  `continueMarkdownList`, `toggleMarkdownTask`, and `linkPastedUrl` for a custom editor. `npm run test:markdown`
+  checks the parser and every command.
+
+### QR code
+
+```tsx
+import { encodeQr, qrPath, QrCodeImage } from "nexus-shared";
+
+<QrCodeImage value={setup.otpauthUri} label="QR code to add your account to an authenticator app" />
+const { version, size, mask } = encodeQr("https://nexus.example", "H");
+```
+
+- **What a camera reads:** black modules on a white square that holds the quiet zone, in every theme and in forced
+  colours. `nx-qr` makes it 9rem wide with a control's corners; the page's own class places it.
+- **The encoder** is QR Code Model 2, written by hand: the text as UTF-8 in byte mode, the smallest of versions 1 to 40
+  that holds it at the level asked (L, M, Q, H restore about 7%, 15%, 25%, 30%), Reed-Solomon, and the eight masks scored
+  by the four penalty rules. A text past version 40 throws, saying how much the level holds (2,331 bytes at M).
+- `npm run test:qr` checks its shape; `Project-Skills/Checks/qr-code-check.mjs` reads every code back with an independent
+  decoder (jsQR, installed outside the repository).
+
+### Printable document
+
+```tsx
+import { formatMoney, PRINT_PAPERS, PrintDocument, type PrintPaper } from "nexus-shared";
+
+<TabButtons<PrintPaper> aria-label="Paper" options={PRINT_PAPERS} value={paper} onChange={setPaper} size="sm" />
+<Button variant="primary" size="sm" onClick={() => window.print()}>Print</Button>
+<PrintDocument
+  paper={paper}   // "a5" (default) or "thermal", an 80 mm roll
+  logo={billLogo ? { src: billLogo.url, alt: company.name } : undefined}   // or any node; logoOnThermal={false} leaves it off a roll
+  aria-label={`Receipt ${receipt.number}`}
+  title={company.name}
+  subtitles={[branch.name]}
+  kind={onCredit ? "Bill on credit" : "Receipt"}
+  stamp={voided ? `Voided: ${reason}` : undefined}
+  blocks={[
+    { facts: [{ label: "Receipt no.", value: receipt.number }, phone && { label: "Phone", value: phone }] },
+    { columns: [{ label: "For" }, { label: "Amount" }], lines: [{ cells: [item, money(amount)], note: `Paid up to ${day}` }], totals: [{ label: "Total paid", value: formatMoney(net, { currency, locale }) }] },
+  ]}
+  footer={settings.receiptFooter}
+/>
+```
+
+- **Params, not markup.** A head (`title`, `subtitles`, `kind`), a `stamp` across it, `blocks` in order - facts (a
+  label and a value per line, the labels in one column) and lines (a table, the last column lined up at the end, a
+  `note` under a line's first cell, `totals` under a rule) - and a `footer` whose line breaks are kept. A falsy entry,
+  or one with `hidden: true`, is left out.
+- **Printed alone.** On screen it reads in the theme's colours at its paper's width (A5: 128 mm of text; the roll: 72
+  mm). `window.print()` prints only the document, black on white, at the paper's edge, on the paper picked: the
+  component writes the page's `@page` rule while it is on the page. Any other page prints as it is. No PDF library.
+- **A logo** (`logo`: `{ src, alt }`, or any node). On A5 it sits beside the title lines in a 24 mm column (at most 16
+  mm tall), the lines still centred, so the head grows no taller and a one-page receipt stays one page; on a roll, or
+  an A5 document shown narrower than 100 mm, it sits small and centred above them (at most 36 x 10 mm on a roll).
+  `logoOnThermal={false}` leaves it off a roll. Printed in black and white. An image must have loaded before printing.
+
+### Document frame
+
+```tsx
+import { DocumentFrame, type DocumentFrameHandle } from "nexus-shared/client";
+
+const frame = useRef<DocumentFrameHandle>(null);
+<DocumentFrame
+  ref={frame}
+  title="Voucher preview"                  // the frame's title, its name to a screen reader
+  html={preview}                           // the server's whole page, <!DOCTYPE html> to </html>; null while none
+  loading={reading}
+  loadingMessage="Loading the preview…"    // default "Loading…"
+  error={problem}                          // why it could not be shown
+  emptyMessage="Pick a layout."            // default "Nothing to show yet."
+  printable                                // print() may open the dialog
+  actions={<Button onClick={() => frame.current?.print()}>Print</Button>}
+/>
+```
+
+- **A page that is not this page's.** A server's whole document (its own `@page` sheet, screen style and CSP) goes
+  into an `<iframe srcdoc>`, never into this page's DOM or styles. **No script ever runs in it**: the sandbox is `""`
+  (an opaque origin; not even this page can reach in), or with `printable` `"allow-same-origin allow-modals"` - the
+  parent may call the frame's `print()`, and `print()` may open its dialog (Chrome ignores it without `allow-modals`).
+  Never `allow-scripts`, forms, popups or top navigation. A frame that becomes printable is made again, as a new
+  sandbox counts only from the frame's next page.
+- **Its height is its container's**: it grows in a flex column (or stretches in a grid row) and is never under 22rem.
+  The page scrolls inside the frame; an A4 sheet wider than the frame scrolls sideways there, never the page.
+- **A bar over the page**, the form's bar: the status line, and `actions` at its end, which wrap under the line on a
+  phone. It shows only with actions or something to say; out of sight it stays a live region.
+- **States.** `loading` makes the page area `aria-busy` at once; a read that lasts 0.4s dims the page and says
+  `loadingMessage` (a quick one says nothing, held 0.3s once shown, as a CRUD's details footer). `error` is a line with
+  `role="alert"` over the last page, which stays in view. While loading or failed, an `html` of null keeps the last page.
+  A printable page read again keeps its scroll while the `title` stays the same.
+- **`print()`** answers `false` when it cannot: not printable, no page yet, or the frame not loaded.
+
+### Forms
+
+```tsx
+import { EInputTypes, TEXT_PATTERNS, type InputParams } from "nexus-shared";
+import { ApiForm, SubmitForm } from "nexus-shared/client";
+
+const ROOM_INPUTS: InputParams[] = [
+  { type: EInputTypes.Text, name: "number", label: "Room number", required: true, pattern: TEXT_PATTERNS.digits, span: 4 },
+  { type: EInputTypes.Number, name: "floor", label: "Floor", required: true, min: 0, span: 4 },
+  { type: EInputTypes.Dropdown, name: "type", label: "Type", required: true, options: ROOM_TYPES, span: 4 },
+  { type: EInputTypes.Tabular, name: "beds", label: "Beds", itemLabel: "Bed", inputs: BED_INPUTS },   // a list is an input too
+];
+
+<ApiForm
+  inputs={ROOM_INPUTS}
+  loadValue={signal => api.get(ROOMS.details, { params: { id }, signal, toast: false }).then(unwrapApiResult)}
+  api={ROOMS.update}   // or in place: { module: NexusModule.Reservation, path: "Room/Update", method: "PUT" }
+  draftKey={`hotel-3:user-8:room:${id}`}
+  onSuccess={room => table.updateRow(room)}
+  onCancel={close}
+/>
+```
+
+- **An input's `type` is a number**, a member of `EInputTypes` (since 4.0.0; a string is refused): text boxes 1–19
+  (`Text` 1, `Email` 2, `Password` 3, `Search` 4, `Tel` 5, `Url` 6, `TextArea` 7, `Code` 8), choices 20–39 (`CheckBox`
+  20, `Switch` 21, `Radio` 22, `CheckBoxGroup` 23, `RadioGroup` 24, `Dropdown` 25, one item or many by `multiple`),
+  dates and times 40–59 (`Date` 40, `DateRange` 41, `Time` 42, `DateTime` 43), numbers and sliders 60–79 (`Number` 60,
+  `Slider` 61, `RangeSlider` 62), editors 80–99 (`Markdown` 80, `RichText` 81) and structures 100–119 (`Tree` 100,
+  `Tabular` 101, `Group` 102, `Picture` 103). 0 is never a kind, and a number is never reused, so a database or a C# enum can hold it.
+- **Params in, values out.** Every input is an entry of `inputs`, so a page, a CRUD component, or a server can describe a
+  form with plain objects. Values come in as each input reports them (a date-time from an API becomes a date, "12.5"
+  becomes 12.5), and fields the record came with (an `id`) stay in the values.
+- **Fast at any size.** The values live in a `FormStore` outside React. Typing renders only the input typed in; an input
+  renders again only when a message it shows changes, or code sets its value. A keystroke costs about 5 µs in the store
+  for a form of 200 inputs, and a list of 10,000 rows is not checked again on each keystroke (it checks itself).
+- **Checks on Save.** Each input's own rules (they also catch text that is not a date yet), the form's `validate` across
+  inputs, and rows not on the page. Every message shows, the first problem takes focus (a table scrolls to its row), and
+  the status line lists what needs attention, each name a link to its input. A rule message on an input shows once the
+  input was left, and on Save.
+- **An input shown by another's value** (`showWhen`, Form only): `{ name: "counterType", in: [0, 1] }`, `notIn`, or
+  `filled: true | false`, or a list that must all hold (`[{ name: "counterType", in: [2] }, { name: "feeId", filled:
+  false }]`). The input comes and goes as the other changes, keeps what was typed, and is not checked while hidden; no
+  getter, no state in the page. `dependsOn` remains for anything else a getter reads (a `label`, `options`, a `max`).
+- **An input read-only by another's value** (`readOnlyWhen`, Form only): the same conditions. A CRUD's Edit form holds
+  the record's key (`rowKey`, default `id`) and its Add form does not, so a field picked on Add and fixed once saved is
+  `readOnlyWhen: { name: "id", filled: true }`, with `readOnlyMessage` saying why. It shows its value (a dropdown its
+  saved label) with the lock and the note, sends it with the rest, and is not checked while read-only.
+- **A label that follows another input** (`labelWhen`, Form only): `{ name: "registrationType", labels: { 1: "PAN
+  number", 2: "VAT number" }, otherwise: "PAN/VAT number", placeholders: { 1: "9 digits" } }`. The label (and the
+  placeholder, where listed) is the one for the other input's value as it is now, compared as text, else `otherwise`,
+  else its own; its messages name it the same way; the field draws again with no remount, keeping what was typed.
+- **A width that follows a value** (`spanWhen: { when, span }`, Form only): `span` columns while every condition of
+  `when` holds (`showWhen`'s conditions; the input's own name follows its own typing), else its own `span`. A Bill date
+  that is the whole row until a date is put, then half with the switch that counts from it beside it, so nothing after
+  it moves: `span: 6, spanWhen: { when: { name: "billDate", filled: false }, span: 12 }`. The cell takes the new width
+  on the key that makes or unmakes the value, with no remount: the text, the caret, the focus and an open calendar
+  stay. A narrow form still gives every input the whole row.
+- **An input worked out from others** (`compute: { from, value }`, Form only): shown, never typed - a price's
+  Calculated amount after Price, Discount and VAT. It is worked out when the form opens and whenever an input in `from`
+  changes (typed, set from code, loaded, reset), and is no form value: never sent, never checked, never a change,
+  never remembered or kept in a draft. Its box is an `<output>` on the read-only tint, in the person's number format,
+  with no lock, no steppers and no Tab stop; blank for null, "" or NaN, and while the values load. The form's
+  **`computeWith`** (state or a `useMemo` value, compared by identity) is what the page knows beside the values, such
+  as a server's preview: `compute: { from: [], value: (_values, line) => line?.netAmount }`.
+  - **The money presets**: `crudInputs.netAmount()` is that box ("Calculated amount", span 3, blank while the price
+    is empty); `...crudColumns.amounts()` gives a list Price, Discount, VAT and Calculated amount under "Amount
+    details"; `crudColumns.priceLadder(row, { locale })` gives a record's details a receipt's lines (Rate, Amount,
+    "Discount (5%)", "VAT (13%)", Calculated amount; a zero line left out). `PriceKeys` names other fields.
+  - **`priceAmounts({ price, quantity, discountPercentage, vatPercentage })`** is the Nexus server's money rule in the
+    browser: the amount, the discount off it, the VAT on the rest, each rounded half away from zero on exact decimals,
+    so a page's figure equals the server's to the paisa. `priceLadder(row, { locale })` gives the ladder as lines.
+- **An input that remembers** (`remember: { key, viewer, preferred, per, when }`, a Form's input or a row input):
+  when the form's values leave it empty (a new record), it opens on the company's `preferred` value (a setting the page
+  reads), else on the person's last saved choice, kept in this browser under `nx-input:{key}:{viewer}` each time a form
+  holding it saves; each only while the input still offers it (a disabled or inactive option, or one gone, is dropped
+  without a word and a kept one forgotten), else its own `defaultValue`. It is the value the form opened with, not a
+  change; a form reset after a save opens on the new choice. No `viewer`, nothing kept.
+  `{ type: EInputTypes.RadioGroup, name: "paidBy", ..., remember: { key: "counter-paid-by", viewer: `${userId}|${companyId}`, preferred: settings.defaultPaymentMode } }`.
+  - **A picker** (`...crudPicker(...)`, options from `loadOptions`) confirms a kept value by its key before it opens -
+    found, not inactive, inside its `narrowedBy` narrowing - with its spinner meanwhile (the box `aria-busy`, described
+    "Loading"; a person in the box keeps the focus when the value opens); never over the person's own pick. A picker
+    that cannot name a record by its key is looked through page by page in its own `pageSize`: a value not met in 20
+    pages, on a list that goes on, is kept for later but not opened - only the list's end makes it gone.
+  - **`per: "subscriptionGroupId"`** keeps one value per value of that input (`nx-input:{key}-{group}:{viewer}`): a
+    package per group. **`when: { name: "id", filled: false }`** remembers on a CRUD's Add only (Edit holds the key).
+  - **In rows** (a tabular or group form): a new row's input opens on the kept value (give its first choice as the
+    input's `defaultValue`, not in `newRow`, which wins), and a save keeps the value of the last row added.
+- **Ask before saving** (`confirm`: SubmitForm, ApiForm, and a CRUD's `form.confirm`): after every value has passed its
+  checks, a question with what will be saved in full - `{ title: "Place this order?", message, details: (values, body) =>
+  ({ row: body, columns, currency }), confirmLabel: "Place order", size: "xl", when }`. `body` is what is sent: an
+  ApiForm's `transform` runs once, before the question, and that very body is sent after Confirm. The details are drawn
+  as a record's (`CrudDetails`), a section under a heading for each run of columns with one `group`, and are read out
+  with the title. Confirm has the focus, so a deliberate Enter saves (the Enter that asked, held or pressed twice,
+  does not); Back to the form, Esc and × send nothing and leave the form as it was, the focus back where it
+  was; a click outside leaves it open. While it asks nothing else submits and nothing says "Saving…"; a throw while it
+  is prepared shows under the form and asks nothing. `when` limits it to some saves.
+- **One save at a time.** Save waits with a spinner; another click, Enter, or Ctrl+S does nothing until it ends. A save
+  makes the values the form's own ("Unsaved changes" clears; values typed meanwhile stay changes). `onSubmit` returns
+  `{ ok: false, errors, message }` to say why not, and a thrown error shows its message.
+- **Server messages.** The server's own words are what the user reads. `ApiForm` shows **every** message a refusal
+  carried - a Nexus answer's `errorMessages` (a list, or one message object, or one message and its codes at the top
+  level) and ASP.NET Core problem details (`errors` by field) - each on the input its `inputName` names, matched without
+  case and by the first part of a path (`Addresses[1].City`). Names that match no input of this form, messages that name
+  none, and failures without fields show beside the buttons; nothing is swallowed and nothing is shown twice. A sentence
+  of ours by HTTP status ("Someone else changed this record…") is the fallback for an answer that explained nothing.
+  `messageCode` and `errorCode` ride along in `answer.errorMessages` for the log and for `onError` to react to, and are
+  never shown as the sentence. An input's message clears when its value changes.
+- **Nothing lost.** `draftKey` keeps unsaved changes in IndexedDB (after a 600 ms pause, and at once when the page hides
+  or the form leaves) and brings them back with a note and Discard; drafts changed on the server since are named. Cancel
+  asks before it drops changes, and the page asks before it closes with some (`confirmLeave`, on without a draft).
+  The same form on the page also asks "Discard your changes?" before a navigation inside the app takes it away: every
+  same-origin link (next/link or a plain `<a>`: a side menu, the brand, a trail, a menu's link row) is held in the
+  capture phase while one has changes, and followed once Discard is chosen; Keep editing stays. A navigation of the
+  app's own asks through `confirmPageLeave()` (`if (await confirmPageLeave()) router.push(href)`), as nexus-admin's
+  module and account menus do; a move to the page in view asks nothing (`keepsPage(href)`), nor does a link inside text
+  being edited. A form in a `PopupHost` popup is left out: the popup stays open through a navigation, and keeps its own
+  close question. A confirmed navigation is not asked about again by the browser's close question. A move that loads a
+  whole page (a sign-out, `location.assign`) asks with `confirmPageLeave({ unload: true })`: about every form, the
+  popups' too, and once confirmed nothing asks again until the page goes (`endPageLeave()` if it did not).
+  `form.load(values, { keepChanged: true })` refreshes a record without touching what the user changed.
+- **A save that removes something** (remove an app, turn a setting off, replace codes) says so on its button:
+  `submitTone="danger"` fills it with the danger colour, as every solid danger fill is. `aria-describedby` on the form
+  points at the line that says what goes, so a screen reader hears it when the focus lands straight in the password box.
+- `npm run test:forms` checks the store and the API helpers; `scripts/browser-checks/forms.cjs` in the template checks the
+  three demo pages.
+
+
+**A preview the server works out as the person types** (`useServerPreview`, `nexus-shared/client`): a counter's
+amount and dates, a layout's printed page. `request(values)` on each change asks a moment after the last one (`delay`,
+300 ms); an older question is aborted and its late answer never shown; `result` (and the `question` it answers) stays
+while a newer one runs and after one fails (`error`, the thrown message); `waiting` during the pause and `loading`
+while it is with the server; `cancel()` drops what waits or runs, `clear()` the answer too; leaving the page stops it.
+`ServerPreviewStore` is the same outside React.
+
+```tsx
+const preview = useServerPreview(async (body: CounterBody, signal) => {
+  const answer = await api.send<CounterPreview>(COUNTER_PREVIEW, { body, signal, toast: false });
+  if (!answer.ok || !answer.result) throw new Error(answer.message ?? "This cannot be worked out just now.");
+  return answer.result;
+});
+<Form inputs={inputs} onValueChange={values => (missingFor(values) ? preview.cancel() : preview.request(counterBody(values)))} />
+<DocumentFrame html={preview.result} loading={preview.loading} error={preview.error} />   // a layout editor's page
+```
+
+### API calls
+
+```ts
+// api-modules.ts: the app's modules and where each one's root is (shared by the browser and the server)
+import { defineApiModules, NexusApiModules, NexusModule } from "nexus-shared";
+
+export const MODULES = defineApiModules(new NexusApiModules({ useProxy: process.env.NEXT_PUBLIC_API_PROXY !== "false" }));
+export const ROOMS = MODULES.controller(NexusModule.Reservation, "Room", "room");
+
+// In the browser
+import { api } from "nexus-shared/client";
+const rooms = await api.get<Room[]>(ROOMS.listing);                    // GET /api/app/reservation/Room/NormalListing
+await api.put(ROOMS.update, values, { subject: "Room 204" });          // toast: "Room 204 saved." or what failed and why
+await api.confirm(ROOMS.delete, { params: { id }, subject: "Room 204" });   // asks "Delete Room 204?" first
+
+// On the server (a server component, a route handler, a server action)
+import { serverApi } from "nexus-shared/server";
+const list = await serverApi.get<Room[]>(ROOMS.listing, { revalidate: 60, tags: ["rooms"] });   // straight to API_RESERVATION
+
+// app/api/app/[module]/[...path]/route.ts: the browser's way to every module
+export const { GET, HEAD, POST, PUT, PATCH, DELETE } = createApiProxy({ token: readAccessToken });
+```
+
+- **Modules are the app's.** `ApiModules<TModule>` is an abstract class over the app's own module enum: implement
+  `modules` (each module's value, its key in proxy URLs, its label for messages, where its root comes from) and
+  `serverRoot(module)` (from the environment, a settings service, anything; may be async). Register it once with
+  `defineApiModules`, and define endpoints through it (`MODULES.controller`, `MODULES.endpoint`), so a file that calls
+  an endpoint has registered the modules on either side. `NexusApiModules` is the Nexus set (roots from `API_<MODULE>`,
+  as in the previous project; `NexusModule.None` for the app's own `/api` routes) and runs when nothing is registered.
+  The list is checked: keys and values must be unique, and keys fit in a URL.
+- **`NexusModule`'s numbers are the backend's `EModules` flags**, and a permission is a bitmask of them, so a value
+  that disagrees with the backend by one bit grants or denies the wrong module in silence. They changed after
+  2.0.0: `Chat` took bit 6 and `Accounting` through `Portfolio` each moved up one. Code that uses the names needs
+  nothing; anything holding a stored or hard-coded **number** does. [CHANGELOG.md](CHANGELOG.md) has the table.
+  `Inventory` (`API_INVENTORY`) was added at bit 17 in 4.0.0, after `Portfolio`, and moved nothing: a new module takes
+  the next bit at the end.
+- **Module types from one place.** An app names its enum once, next to `defineApiModules`:
+  `declare module "nexus-shared" { interface ApiRegister { module: HrModule } }`. Every endpoint, call, `ApiForm`,
+  and CRUD then takes only those modules (`AppModule`), so `{ module: NexusModule.Reservation, … }` in an HR app is a
+  type error. Without it, the modules are `NexusModule`.
+- **The proxy, on or off.** With `useProxy` (the default), the browser calls `/api/app/<module>/<path>` and the proxy
+  route sends it on to the module's root with the user's token, which never reaches the browser. Off, the browser
+  calls each module's `browserRoot` (public) and the proxy serves none. `proxies(module)` mixes the two, such as
+  uploads straight to the Drive module and the rest through the proxy.
+- **The proxy hides the backend.** To the browser the app is the backend, and nothing in an answer names the real one:
+  - **No redirect reaches the browser.** One that stays inside the module (the root's origin, or its host moved to
+    https by the backend's HTTPS redirection, under the root's path in any casing) is followed on the server as
+    `fetch` follows it: 307 and 308 keep the method and body, a 303 and a POST's 301 or 302 become a GET, up to
+    `maxRedirects` (3). Any other answers 502 `BACKEND_REDIRECT_REFUSED`: following it would carry the token elsewhere.
+  - **Response headers by an allowlist**, `DEFAULT_PROXY_RESPONSE_HEADERS` (Content-Type, Content-Disposition,
+    Content-Language, Content-Range, Accept-Ranges, Cache-Control, Expires, ETag, Last-Modified, Vary, Retry-After),
+    the Nexus backend's `X-Nexus-*`, and the names in `responseHeaders`. Server, X-Powered-By, X-AspNet-*,
+    X-SourceFiles, Via, Alt-Svc, Strict-Transport-Security, Report-To, NEL, CORS, Location, Link and WWW-Authenticate
+    never pass, even named; Set-Cookie only with `passCookies`. Every answer gets `X-Content-Type-Options: nosniff`,
+    and `Cache-Control: private, no-store` unless the backend said how to cache it.
+  - **Error pages replaced.** An error answer that is not JSON (an HTML or text page, a stack trace), JSON that is a
+    stack trace or repeats the user's token, or one over 1 MB, becomes the failure envelope with the backend's status
+    and plain words (`BACKEND_ERROR_PAGE`). JSON refusals (the Nexus envelope, problem details) and empty ones pass as
+    they came, so the backend's own words still reach the form.
+  - **The request.** The browser's own `X-Forwarded-*`, `Forwarded`, `X-Real-IP` and the like never go on, nor its
+    cookies, a method or path override (`X-HTTP-Method-Override`, `X-Original-URL`) or Next.js's own headers. The
+    proxy writes X-Forwarded-For (the last address the app received, which Next.js or the app's reverse proxy wrote;
+    `clientAddress` reads it elsewhere; an IPv4 or IPv6 address or nothing, never other text) and X-Forwarded-Host
+    and -Proto (the app's configured origin, else the request's). A module whose root is a path on the app (a pretend
+    backend) is called at this server's own host and port, over http: the request URL's, which Next.js builds from
+    where it listens. Never at the configured origin, so an app whose `origin` reads the Host header cannot let a client
+    choose another port on the machine; `serverApi`, which has no request, uses that `origin`, so build it from
+    configuration, or take the Host only when it names this server's own port. A body over `maxBodySize` (100 MB) is
+    refused with 413 before the backend sees it, and a page of another site cannot call through the proxy
+    (`Sec-Fetch-Site: cross-site`, other than a link followed) unless `allowCrossSite`.
+  - **A server call can say who the client is too.** `lastForwardedAddress` and `readIpAddress` (`nexus-shared/server`)
+    read the client's address as the proxy does, from anything with a `get` (Next.js's `headers()` included). The
+    template's `api-setup.ts` gives Identity calls, and only them, `X-Forwarded-For` and the browser's `User-Agent`
+    through `configureServerApi({ headers })`: sign-in leaves from the server, and Identity's rate limit counts per
+    address. Only Identity's, because reading the request makes a page render per request.
+  - **Refusals** are the Nexus envelope, `{ isSuccess: false, code, message, messageCode, errorCode, errorMessages }`
+    (`failure` builds another backend's; `PROXY_REFUSALS` lists the codes), and the real cause goes to the server's
+    log (`onProblem`, default `console.error`), never with the token or a query string.
+  - **Two things the proxy cannot do for an app.** Node.js does not trust a development certificate (ASP.NET Core's)
+    unless it starts with `NODE_USE_SYSTEM_CA=1`, so a module whose http root redirects to such an https port answers
+    502 until then, and the log says so. And Next.js keeps an X-Forwarded-For a client sent when nothing stands in
+    front of the app, so only behind a reverse proxy of its own is the client's address certain.
+- **One engine, two clients.** `api` and `serverApi` are two settings of `createApiClient`: it fills `{id}` in the path
+  from `params` or the body, adds the query, headers, and token, waits up to `timeout` (60 s), tries a failed GET once
+  more (a save never twice), and reads every answer as an `ApiResult` (`ok`, `status`, `result`, `message`,
+  `errorMessages`, `errors`, `messageCode`, `errorCode`, `network`, `timeout`, `aborted`). A failed call is an answer,
+  never a throw; an aborted one shows nothing. Next.js's own signals (`headers()` while prerendering, `redirect()`) pass
+  through untouched.
+- **What the server said wins.** A refusal is shown in the backend's own words whenever it sent any:
+  `{ isSuccess, code, errorMessages: [{ message, messageCode, errorCode, inputName }] }` becomes
+  `result.errorMessages` in that order (one message object instead of a list, a single `errorMessage`, and an older
+  answer's one message at the top level all read into the same list), `result.errors` holds the ones that name an input,
+  and `result.message` is all of them joined for a toast. `messageCode` and `errorCode` are for the log and for a page to
+  react to - never the sentence a user reads. The messages built from the HTTP status are the fallback for an answer that
+  explained nothing.
+- **Answers of another shape.** Nexus answers and ASP.NET Core problem
+  details are read out of the box. A backend that answers its own envelope registers one reader for the whole app:
+
+  ```ts
+  // Reads { success, message, data, error: { code, message, fields } } — the answer becomes ok, result, message, errors
+  const read: ApiResponseReader = (body, status) => {
+    const answer = body as BackendAnswer | null;
+    if (answer?.success) return { ok: true, status, result: answer.data, message: answer.message };
+    const fields = Object.entries(answer?.error?.fields ?? {}).map(([name, list]) => [name, list.join(" ")]);
+    return { ok: false, status, message: answer?.error?.message, messageCode: answer?.error?.code, errors: Object.fromEntries(fields) };
+  };
+  configureApi({ read });          // the browser
+  configureServerApi({ read });    // and the server, so both sides read one envelope
+  ```
+
+  It is the fallback of every call that does not bring a `read` of its own, which is what the components that call
+  inside themselves need: a `Crud`'s lists and actions and an `ApiForm`'s save have no place to pass one. A call's own
+  `read`, and an `ApiForm`'s `readResponse`, still win.
+- **Toasts in the browser.** Errors always, successes for POST, PUT, PATCH, and DELETE; the same failure twice at once
+  shows once; `toast: false`, `true`, or `{ success, error, loading }` per call; `configureApi({ toast, headers, read,
+  onSignedOut })` for the app. The server shows nothing and logs network failures, timeouts, and 5xx.
+- **One message builder.** `buildMessage(kind, { action, subject, count, status })` words every message, and
+  `messages.success`, `.failure`, `.reason`, `.loading`, `.confirm`, `.label`, and `.forResult` are short ways to call
+  it: "3 rooms deleted.", "Could not move Room 204 to the trash.", "You do not have permission to delete Room 204.". The
+  texts and action words are one table: `configureMessages` rewords or translates all of them at once, and an action
+  of the app's own is its words (`{ verb: "check in", done: "checked in", doing: "Checking in", object: "the guest" }`).
+- **A controller's lists.** `apiController` names the lists as the Nexus backend does: `listing` and `pagination` are the
+  active records' (`NormalListing`, `NormalPagination`), and `lists.flag`, `lists.trash`, `pages.trash`, … the others
+  (`FlagListing`, `TrashListing`, `TrashPagination`, …), for the CRUD component.
+- `npm run test:api` checks the builder, routes, modules (another app's enum, the proxy on and off), the engine, the
+  server client, and the proxy's routing; `npm run test:proxy` checks how the proxy hides the backend (redirects,
+  headers, error pages, forwarded headers, paths, the body limit, other sites, the log) against a fake backend;
+  `scripts/browser-checks/api-calls.cjs` in the template checks `/demo/api`.
+
+### Data table
+
+```tsx
+import type { TableColumn } from "nexus-shared";
+import { DataTable, useTable } from "nexus-shared/client";
+
+const COLUMNS: TableColumn<Booking>[] = [
+  { key: "no", label: "Booking", width: "7rem", movable: false, pinnable: false },   // stays first, and stays put
+  { key: "guest.name", label: "Guest" },                                   // a path into the row
+  { key: "amount", label: "Amount", format: "money", prefix: "Rs. ", group: "Amount details" },   // number, money, percent, date, …
+  { key: "due", label: "Due", format: "money", prefix: "Rs. ", group: "Amount details" },   // one heading over both: the header is two rows
+  { key: "status", label: "Status", options: [{ value: 1, label: "Confirmed", tone: "success" }] },   // a tag
+  { key: "paid", label: "Paid", format: "boolean", resizable: false },     // keeps its width
+  { key: "created", label: "Booked", format: "date-time", hidden: true },  // shown from the Columns menu
+];
+
+const table = useTable<Booking>();
+<DataTable table={table} aria-label="Bookings" columns={COLUMNS} rows={bookings} selectable massActions={MASS} rowActions={row => ACTIONS(row)} stateKey="bookings" />
+<DataTable columns={COLUMNS} paging="server" load={(query, signal) => fetchPage(query, signal)} />   // { search, sort, page, pageSize, filters }
+<DataTable columns={COLUMNS} rows={bookings} onImport={askForFile} moreActions={[{ id: "report", label: "Monthly report", onSelect: open }]} />
+
+table.upsert(saved); table.patch(7, { paid: true }, { flash: true }); table.remove([7, 8]); await table.reload();
+```
+
+- **Columns are params**, one plain object each, as inputs are: `key` (a field or a path), `label`, `group`, `format`,
+  `decimals`, `prefix`, `suffix`, `currency`, `options` (labels for an enum's values; a `tone` draws a tag with a dot of its color),
+  `value`, `render`, `text`, `width`, `minWidth`, `align`, `wrap`, `sortable`, `sortKey`, `searchable`, `hidden`,
+  `hideable`, `movable`, `resizable`, `pinnable`, `pinned`. Numbers line up at the end in tabular figures; dates and
+  times follow the user's settings; moments show in the user's zone once the page has hydrated; long text ends in … at
+  the column's width. `table` (sub-columns) marks a list of rows: a record's details draw it as a small table across the line
+  (numbered rows, an option's tone as its tag, a yes or no in words, "None" for an empty list), the table its count.
+- **Money in the company's currency.** `<DataTable currency="Rs." />` (a `Crud`'s `table.currency`) writes every
+  `money` column "Rs. 1,250.00" - in the cells, the details, the CSV and the print - with no `render` of the page's; a
+  column's own `currency` (a text, or `row => row.currencyText`) wins. `formatMoney(value, { currency, locale })` writes
+  the same anywhere else, a dashboard's figure or a receipt's total.
+- **Columns in bands.** `group` is the heading above a column (`{ key: "amount", label: "Total", group: "Amount
+  details" }`); the columns next to each other that name the same one share it, and the header reads in two rows, the
+  bands on top and the columns' own headings under them. A column with no group keeps one heading as tall as both rows,
+  and so do the numbers and checkbox column and the actions. A band is a heading and nothing more: it sorts nothing, has
+  no menu and no edge to drag, and the columns stay one flat list, so hiding, ordering, widths, pins and the export are
+  as they were. The bands are read off the order on screen: a column dragged out of its run takes its band's heading
+  with it, and the run it left draws that heading again. With no group anywhere the header is one row.
+- **Rows three ways.** Given (`rows`) or loaded once (`load`), the table searches, sorts, and pages them itself: every word
+  must match, in any column, with or without accents, and 10,000 rows search in about 0.5 ms a keystroke. A page at a time
+  (`load` with `paging="server"`), each search (after 300 ms without typing, or Enter), sort, and page is one request; a
+  newer query stops the one before, so a late answer never shows. A loader may answer without a promise (a cache), and
+  the rows then paint with the table. `loadKey` starts over for another list behind the same table.
+- **What it shows while it waits.** Placeholders in the shape of the rows for the first rows; afterwards the rows stay,
+  with a thin bar under the headings, and dim only if a load takes a moment. A failed load says why, with Retry; an empty
+  list has its own message and action; a search or filters that find nothing offer Clear search or Clear filters.
+- **The columns are the user's.** Drag a heading to another place, drag its right edge for its width (double-click the
+  edge, or "Fit to content", to fit it, never under the column's `minWidth`), and use the caret on the heading to sort,
+  pin it left or right, move it, or hide it; the Columns menu shows and hides them. A column opts out with
+  `movable`, `resizable`, or `pinnable: false`, and `pinned` starts it on a side. The table itself can refuse all three
+  (`reorderable`, `resizable`, `pinnable`). Once a width is set the columns are laid out from those widths, so one edge
+  moves alone; "Reset columns" in the options menu puts everything back.
+- **The bar** is one line on a wide table: the Add section (`add`, then the page's `actions`) and the lists
+  (`toolbar`) on the left; Reload, the options menu (⋮) and the search, rows per page inside it, on the right. A
+  narrower table moves whole parts, never a lone button, by its own width (a container query, so a table in a narrow
+  panel does the same): under 670px the search takes the top line (with nothing on the left, it leads the buttons'
+  line instead), under 375px Reload moves into ⋮, and under 325px, beside lists, the Add section takes the last line,
+  its buttons sharing it. On the admin shell, whose menu leaves the screen at 900px, those are windows of 695, 400 and
+  350px. A bar wider than those widths expect (a long Add label, the page's own buttons, cozy density) takes the next
+  step as soon as a line would break (`data-squeeze`). Each item of the Add section keeps its own width on a shared
+  line (a switch's label never breaks between its words, nothing runs into the lists); on the line the section takes
+  of its own its items share it, and one that would not fit its share takes a line of its own, whole. A `Crud`'s lists
+  name every tab from 900px and only the chosen one below.
+- **One options menu (⋮)**: **Filters** (`filterInputs`, input params as a form takes them, each named after the
+  column it filters: a small form under ⋮, applied as it changes; a server gets them flat by name, see `filterRequest`),
+  the columns shown as a CSV (`exportable`, named by `exportName` or the table's label), a
+  print view of the same in a frame of its own (`printable`), Import (`onImport`), any `moreActions` of the page, and
+  Reload, last, on a table too narrow for its button. A client table writes every row the search left; a server table
+  writes the page it has, and says so.
+- **Selection.** The first column counts the rows (`numbered`, on by default when `selectable`) and turns into the row's
+  checkbox under the pointer; once anything is selected every row shows its checkbox and the heading shows the box that
+  selects the page (partly checked when some are). Shift+click selects a range, up to `maxSelection` (500). While rows
+  are selected, a bar with the count, one split button holding every `massAction`, and Clear covers the headings, so
+  nothing moves: the menu makes the action picked the button, and the next click runs it, with a spinner while it does.
+- **Row actions**: `inline` ones as icon buttons, the rest in the row's menu; while one runs (a promise), the row is busy.
+  `onRowOpen` for a double-click. A row added or saved is highlighted for a moment (steadily, with reduced motion).
+- **A picked row** (`onPick`), for a page that shows the picked one's records beside the table. A click picks a row, and
+  a double-click still opens it. The keyboard reaches the rows through a radio button each, out of sight in the first
+  column and named with the row: Tab to the picked one, and the arrow keys move the pick.
+  - The picked row wears a selected row's tint, and a ring round it while its radio has the focus.
+  - The pick is the store's (`TableState.picked`, `table.pick(row)`) and follows the record: it is kept through a search
+    or another page, handed over anew after an edit, and let go once the record leaves the rows.
+- **`caption`**: a line inside the frame, over the bar, saying what the rows are. **An Add that waits**:
+  `add.disabled` with a `description` stays in the Tab order, and a press shows why in a note under it, unless
+  `add.onDisabledPress` answers it first (returns true): a CRUD's narrowing box takes the cursor instead.
+- **A pinned section.** `pinnedRows` puts rows in a band above the page with a button that folds them open and shut
+  (`pinnedLabel`, `pinnedMax` beside the count, `pinnedLoading` while they come); with a `stateKey` the choice is
+  remembered on the device. They are the same records as in the list below, and each wears a pin where the rows of the
+  page show their number.
+- **A `stateKey` that changes** (a `Crud` scope's list) reads that key's settings as the first draw does - its page
+  size, sort, hidden columns, order, widths and pins, each column's own default where nothing is kept - and the
+  settings on screen are never written under the new key.
+- **Wide tables** scroll inside their frame, with the numbers and checkbox column on the left, the actions on the right,
+  any pinned columns beside them, and the headings on top staying in place, and a soft shadow where columns scroll under
+  them. On a narrow table the pinned columns give way: the columns that stay take at most 60% of the width on screen
+  (`PINNED_SHARE`), pins kept from the outer edge in, and the others scroll with the rest - keeping their side and their
+  menu's Unpin - until there is room again. Under the table: "Showing 41–50 of 234" (and how many the search and filters left out) on the left, "Page 5 of
+  24" and the pager on the right; rows per page sits inside the search box. At 520px and less the page buttons go.
+- **Where the paging lives** (`pager`). `"bar"` (the default) is the above. `"footer"` puts rows per page beside the
+  pager, so a table with nothing else on top (no search, no ⋮, no lists) draws no bar. `"none"` is for a short list
+  read whole, such as a record's notes (at most 50): every row on one page, no pager, no rows per page, and no footer
+  unless a search or the filters leave rows out; the count is still read to a screen reader. With `searchable={false}`,
+  `columnsMenu={false}`, `exportable={false}` and `printable={false}` such a table is its rows alone, in its frame. A
+  server's pages cannot all be shown, so `paging="server"` takes `"none"` as `"footer"`. A `Crud` passes it as
+  `table: { pager }`.
+
+  ```tsx
+  <DataTable aria-label="Notes" columns={NOTE_COLUMNS} rows={notes} pager="none" searchable={false} columnsMenu={false} exportable={false} printable={false} />
+  ```
+
+- `npm run test:table` checks the helpers, the store, and the CRUD rules; `scripts/browser-checks/data-table.cjs` in the
+  template checks `/demo/data-table`.
+
+### CRUD
+
+```tsx
+import { Crud } from "nexus-shared/client";
+
+export const GUESTS = MODULES.controller(NexusModule.Reservation, "Guest", "guest");   // every list and action
+
+<Crud<Guest>
+  api={GUESTS}
+  columns={GUEST_COLUMNS}                                 // as a DataTable takes them
+  inputs={GUEST_INPUTS}                                   // or { create, edit }, or (action, row) => inputs
+  paging="server"                                         // default "client": each list loaded once
+  form={{ load: "details", newValues: { country: "Nepal" } }}
+  details={{ columns: GUEST_DETAILS }}
+  onChange={({ action, rows, mode }) => audit(action, rows)}
+/>
+```
+
+- **Lists.** All (`NormalListing` or `NormalPagination`), Flagged, Trash, and Deleted, as tabs after Add: every one
+  named on a table 900px wide or more, icons with the chosen one named below. A list shows when it is in `modes`, has
+  its endpoint, and the user may call it.
+- **Pinned records.** `PinListing` answers the records the user pinned: they sit in a section above the active list that
+  folds open and shut, and in the list and its pages as well. One limit holds for every CRUD in the app
+  (`configureCrud({ maxPins: 100 })`, 100 by default). Pinning a selection bigger than the room left pins as many as fit,
+  in the order they were picked, and says so; lowering the limit never unpins anything, so a user over it can still
+  unpin and can pin again once they are under it.
+- **Actions.** On a record in the lists of active records: View details, Edit (an icon on the row), Flag, Pin,
+  Move to trash; in the trash: Recover, Delete permanently; in the deleted list: Move back to trash. On selected records: the same, plus a new Description for all of them. Each shows only when it is in
+  `actions`, has its endpoint, and is allowed. A controller without a trash (no endpoint, or left out of `actions`) offers
+  Delete where Move to trash would be; a trash the user may not use never becomes Delete.
+- **Questions and messages.** Move to trash and Delete ask first ("Move 3 guests to the trash?", "This cannot be
+  undone."); Flag, Pin, and Recover are undone by a click and do not ask. Toasts come from the message
+  builder ("Sita Sharma moved to the trash.", "3 guests unpinned.").
+- **Rows from the answers.** A record that moves to another list leaves the one in view (and the pinned section); flags,
+  pins, and saved values change in place; a new record goes first; a server page loads again in the background to fill up. When a mass
+  answer lists the records it changed, only those change.
+- **A save is never read back** (Nexus: an Add is one Create, an Edit one Update). The row is what was sent under what the
+  answer said (`crudSavedRecord`): the body `transform` made over the form's values, so a field sent as null is empty on
+  the row; and a value `showWhen` hid at the save shows only as the answer (a record) or else the body gives it, never
+  the hidden box's own copy. The fields only the server keeps are written by `CrudBackend.savedRow` (Nexus: Active, no marks, added
+  now; an edit keeps them and was changed now), and the names the database joins written again by `crudJoinedNames` for
+  each `crudColumns.dbJoin` column given `from` (the key's field): from the record the user picked in the form, one the
+  page holds (`peekOption`), or the name the row had when the key did not change. An edit takes the status, the marks
+  and, with `trees`, the child count from the row the page holds now, over its form's older copies; the parents' own rows
+  on the table count their children too. Read back once (`details`), and only then: a record of a backend whose save
+  says no status, or one with a joined name nothing names (`crudJoinsMissing`) - a `dbJoin` column without `from`, or a
+  new key no picked or held record names.
+- **Add and Edit** open popups built on `ApiForm`, with the Save bar in the footer and the server's messages on their
+  inputs. Keys keep them one each: pressing Add again brings back an Add form with changes (minimized or not), or opens a
+  fresh one in place of every untouched one; a record has one Edit popup, brought back as it was when Edit is pressed
+  again - from a table or a tree. Closing a form with changes (its close
+  button, Esc, the dock) asks "Discard your changes?". Edit opens with the row, the `details` endpoint's record
+  (`form.load: "details"`, for fields a list leaves out), or a loader of your own.
+- **Details** (View, or a double-click) shows every column, hidden ones too, and the full record once `details` answers,
+  with Edit in its footer. Each field is a label and its value in a box, two pairs to a line where the details are
+  wide and one where they are not. Columns that name a `group` (a table's band) are drawn in sections under a numbered
+  heading, "01. Contact", "02. Account" (`CrudDetails`, `crudDetailsRuns`); with no group anywhere the list is one
+  grid. In a workspace (below) this footer is the Details tab's alone: every other tab runs to the popup's foot. A
+  section may change on its own: `details.sections: [{ group: "KYC details", edit: "edit" }, { group: "Contacts", edit:
+  "contacts" }]` (the Edit form, or a `rowForms` id) puts an Edit at the end of its heading; once saved the record is
+  read again and the focus comes back to the button.
+- **A record's workspace** (`details.profile`, `details.tabs`, `details.remember`): View, and a click on a row under
+  `table.openOnClick`, open the record as a wide popup (`full` unless `size` says otherwise) - who it is and its tabs in
+  a 20rem column on the left, the chosen tab on the right, scrolling inside itself. A page passes it in a few lines:
+
+  ```tsx
+  details={{
+    profile: row => ({
+      picture: { ...GUEST_PICTURE, ownerId: String(row.id) },   // the picture column's params: a click opens the pictures
+      title: row.fullName,
+      subtitle: row.email,
+      tags: [{ label: "Gold", tone: "warning" }],
+    }),
+    tabs: [
+      // `details` (the fields, with `aside` under them) comes first unless listed: { id: "details" } moves it.
+      { id: "stays", label: "Stays", icon: <InlineIcon icon={iconCalendar} />, endpoint: STAYS.create,
+        render: ({ row, refresh }) => <StayForm guest={row} onSaved={refresh} /> },
+      { id: "bills", label: "Bills", icon: <InlineIcon icon={iconReceipt} />, badge: row => row.openBills,
+        render: ({ row }) => <Bills guestId={row.id} /> },
+      { id: "gold", label: "Gold desk", hidden: row => row.vipLevel !== 2, render: context => <GoldDesk {...context} /> },
+    ],
+    remember: { key: "guest-tab", viewer },   // the last tab, in this browser, for this viewer
+  }}
+  ```
+
+  - A tab that names an `endpoint` shows only to a person who may call it; `hidden(row)` hides it for a record. Only
+    the chosen tab is drawn, and a switch never changes the popup's size.
+  - `profile.fields` puts a few of the record's fields under the tags, a label and a value each, drawn as the table
+    draws them (the person's date format, an option's tone, the column's `tag` after the value). A field is a column
+    given whole or a key of the details' `columns`; one with no value for the record is left out. A field the list's
+    row does not carry keeps its line while the record is read (held) and says "Not loaded" if that read fails; it is
+    left out only once read and empty. The Details tab leaves out every key named there, so no field shows twice. Beside the tabs they are a small grid in the 20rem column; on a
+    phone they follow the tags as one wrapped line.
+
+    ```tsx
+    profile: row => ({ title: row.fullName, tags: [{ label: "Due", tone: "warning" }], fields: [EXPIRY_COLUMN, "inactiveDate"] }),
+    ```
+  - `render` is handed `row` (as the list has it now), `form` (the record: the row, then the `details` endpoint's, then
+    each refresh's), `popup`, `tab`, `select(tabId)` and `refresh()`. Call `refresh()` after a tab changed the record on
+    the server (a stay recorded): it reads the record again and writes it into the table, the pinned band, every list
+    kept and every tree, so the row's visits and dates change with one request and no list read again - in place on
+    every page kept, also for a record opened from the pinned band, and also when the popup closed before it landed.
+  - A `SubmitForm` or `ApiForm` in a tab joins the workspace by itself: while it has changes, choosing another tab or
+    closing the popup (Close, Edit, its X, Esc, its bar on the dock) asks "Discard your changes?" first.
+  - A tab's form longer than the window puts its line and Save last, in a **`CrudTabFooter`**: it stays at the bottom
+    of the tab while the form scrolls and sits in its place at the end, across the tab's whole width under a hairline;
+    a field the keyboard moves to is scrolled clear of it, and on a phone its words and buttons wrap as whole groups.
+
+    ```tsx
+    function StayTab({ refresh }: CrudDetailsTabContext<Guest>) {   // { id: "stay", render: context => <StayTab {...context} /> }
+      const form = useForm<Stay>();
+      const stay = useFormValues(form);
+      return (
+        <>
+          <ApiForm form={form} buttons={false} api={STAYS.create} inputs={STAY_INPUTS} onSuccess={() => void refresh()} />
+          <CrudTabFooter>
+            <p role="status" aria-live="polite">{stay.nights} nights · To pay Rs. {formatNumber(price(stay), { decimals: 2 })}</p>
+            <FormButtons form={form} submitLabel="Save" />
+          </CrudTabFooter>
+        </>
+      );
+    }
+    ```
+  - The built-in `details` tab: list `{ id: "details", label: "Profile" }` to move or rename it, add
+    `hidden: () => true` to leave it out, or a `render` to replace it. Without a second tab for the person, there is no
+    tab list: the profile and the details.
+  - Its `aside` (a subscriber's notes) goes **under** the fields, each across the whole width, the panel as tall as it
+    needs and scrolled with the fields (`details.asidePlace`, `"below"` by default in a workspace); `asidePlace:
+    "beside"` puts it beside them from 1000px, as a plain details popup does by default.
+  - Below 720px of popup width (a phone) the profile is one row and the tabs one strip above the tab. The tabs are a
+    `Tabs` tablist: the focus opens on the chosen tab, the arrow keys, Home and End move and open, Tab goes into the tab.
+- **A list beside the record picked in another** - a person's places beside the people. The page holds the picked record
+  and passes it on; every behaviour is the `Crud`'s:
+
+  ```tsx
+  const [person, setPerson] = useState<CompanyUser | null>(null);
+  <AdminSplit>
+    <Crud<CompanyUser> api={COMPANY_USERS} columns={PEOPLE} inputs={PEOPLE_INPUTS} onPick={setPerson} />
+    <Crud<BranchUser> api={BRANCH_USERS} columns={PLACES} inputs={PLACE_INPUTS} narrow={{ picked: person, key: "userId", labelKey: "fullname" }} />
+  </AdminSplit>
+  ```
+
+  - The narrowed list shows the records whose `key` field holds the picked record's value (its `valueKey` field, `key`
+    by default), under a caption naming it ("Places of: Ram Thapa"). With nothing picked it says so and asks for nothing.
+  - Paged in the browser, it keeps the whole list and reads each pick's rows from it, with no request. Paged on the
+    server, it sends the value as a filter named `key`.
+  - Add New fixes the value in the new record, in a form titled for whom it adds. It waits, saying why, while nothing
+    is picked or the picked record may take nothing: `addLock`, by default the backend's rule, so a Nexus record that is
+    pending, trashed or deleted takes no new records.
+  - A save lands in the list of the record it names, and in no other, even when another record is picked by then.
+- **Pickers of another controller's records** (`crudPicker(STAFF, { labelKey, valueKey, find })`): the active list read
+  once and searched in the browser, and a saved value it does not offer looked up by key through `findListing`. A
+  `valueKey` other than `id` - a person's account rather than their row's key - is looked up through `find`, an endpoint
+  of its own that takes those values. Without it such a value is never looked up, since `findListing` takes keys.
+  **`list`** reads another listing in place of `activeListing` - a controller with none, such as a pay run's CRUD
+  endpoints (`crudPicker(PAY_RUNS, { list: PAY_RUNS.lists.normal, ... })`; with no `findListing`, nothing is looked
+  up) - **`usable`** says which records count as usable in place of the backend's rule (under 30): `run =>
+  run.recordStatus < NEXUS_TRASH_STATUS` offers a draft run (31); and **`option`** makes each record's option, keeping its
+  fields (`run => ({ ...run, label: run.monthName + " · " + run.runCode, state: STATES[run.payRunState] })`). A CRUD's
+  change on the controller marks the list old, as it does the active one.
+- **A record nobody may change here** (`rowLock={row => row.isLocked ? row.lockReason : null}`): its Edit, Flag, Move to
+  trash, Recover and the deletes are listed switched off with that sentence under each, its details have no Edit, the
+  handle's `edit` opens its details, and a selection holding it has those mass actions switched off. View, History, Pin
+  and Favourite stay. The page's own `rowActions` are its own to switch off; the backend still decides.
+- **One action locked on a record** (`rowActionLock={row => row.isHeadOffice ? { trash: "The head office stays open." } : null}`):
+  only the actions named are listed switched off, each with its sentence, and switched off in a selection that holds
+  the record; a locked `edit` opens the details instead. The rest still run.
+- **A list narrowed by a box of its own** (`narrowPicker={{ picker: crudPicker(GROUPS, { labelKey: "groupName" }), label: "Group", key: "subscriptionGroupId", labelKey: "groupName", remember: { key: "subscribers-group", viewer }, onPick }}`):
+  the CRUD draws the box in its toolbar and narrows by the pick as `narrow` does. `remember` keeps the pick in this
+  browser per viewer (pass a short hash of the person and the company, so a shared PC never opens on another's pick)
+  and opens it again while the box still offers it; only the record's key is stored, and nothing without a `viewer`.
+  `onPick` tells the page, for inputs that follow it. The empty list, Add and the Add form's fixed field name the box
+  ("Pick a group in the Group box to see its subscribers."); `emptyMessage`, `addMessage` and `fixedMessage` replace them.
+  While nothing is picked the box asks for a pick: as the page opens it settles (a spinner in it, the list waiting) on
+  the remembered pick, or else on the one record it offers, picked by itself and remembered as a person's pick is; with
+  neither it is required and drawn with a field's invalid edge (`Dropdown` / `Field` `invalid`), the list's words read
+  with it, and it takes the cursor - unless the person is already at work on the page, a popup is open, the box is
+  below the fold, or the screen is touch-only (a cursor would raise the keyboard over the list). The empty list has a
+  button to the box ("↑ Pick a group"), and Add pressed with nothing picked sends the cursor there and nudges the box
+  (still, with reduced motion) while a screen reader hears Add's reason instead of a note under Add.
+- **A list that can be widened** (`scopes={{ options: [{ id: "all", label: "All branches", description: "Every branch's people", api: ALL_BRANCH_USERS, columns, inputs, form: { newValues }, "aria-label" }], remember: { key: "branch-users-scope", viewer }, onChange }}`):
+  the CRUD's own props are its own list (one branch's places); each scope is another list of the same records on
+  endpoints of its own, with its own `columns`, `inputs`, `form` (over the CRUD's, field by field), `table` settings and
+  name where they differ. One scope is a switch after Add, its `description` the tooltip; two or more are tabs, the
+  CRUD's own list first (`label`, `description` for its tab). A scope is offered only to a person who may call one of
+  its lists and passes its `when` (the page's own rule), again whenever their rights change. Switching reads the new
+  list on its endpoints with the CRUD left in place (the switch keeps the focus, popups stay open); each scope keeps
+  its lists while the page is open, so going back shows them at once, and a change made on one drops the others' (only
+  the server knows which hold the record). Each scope keeps its own table settings (`{stateKey}:{id}`, or its own
+  `table.stateKey`). `remember` keeps the choice in this browser per viewer (`nx-crud-scope:{key}:{viewer}`), read after
+  the first draw and before any list is asked for; a kept scope not offered now opens the CRUD's own list and stays kept.
+  An answer that lands after a switch writes nothing into the list on screen, which is read again; it still marks the
+  lookups of both lists' endpoints old and drops a tree's kept pages. A form belongs to the scope it was opened on: an
+  Edit pressed in details opened on another scope is that scope's form on its endpoints, and each scope keeps its own
+  Add and its draft. The handle's `scope` and `setScope(id | null)` read and set it; `onChange` hears every change of
+  the list shown.
+- **A row's own form** (`rowForms={[{ id: "permissions", label: "Permissions", icon, inline: true, modes: ["normal"], size: "lg", load: SETS.details, submit: SETS.update, inputs: (row, loaded) => setInputs(loaded), transform: (values, row) => ({ branchUserId: row.id, ...values }), writes: ["assignedPermissionCount"], lock, when, target, title, submitLabel, onSaved }]}`):
+  a row action (an icon beside Edit with `inline`, else a line of the row's menu) that opens a form of its own for the
+  record in a popup - one per record, brought back if open - after the built-in actions and before `rowActions`. It is
+  offered on the lists that offer Edit unless `modes` says otherwise, to a person who may call `submit` and, when it is
+  an endpoint, `load`, and by the page's `when`; `lock` lists it switched off with its sentence. `load` reads the values
+  (an endpoint called with `{id}`, the record's key or `target`, or a function that must reject on a failure), and the
+  inputs may be made from what was read; until it is, Save waits, and a read that fails - an answer that is not ok, or
+  no record - shows "Could not load the values" with Retry and **no Save**, so an empty form is never saved over the
+  record. `writes` names the answer's fields that change the record (or is a function of the answer): only those, merged
+  over the record as the CRUD holds it when the answer lands (an Edit made while the popup was minimized stays), written
+  into the table, every list kept and the pinned sections with no list read again. The handle's `openRowForm(id, row)`
+  opens one. **`confirm`** asks before the save, as a form's `confirm` does - the details in full, Confirm focused, read
+  out, a hasty Enter held - its params or a function of the record and what was read (`confirm: run => ({ title:
+  "Lock " + run.runCode + "?", details: () => ({ row: run, columns: TOTALS }) })`). **A row form with no `inputs` is its
+  question alone** (a pay run's Lock): no popup, the question (`confirm`, else "{label} {name}?", buttons the action's
+  word and "Cancel"), then the record as the list has it - or what `load` read - sent through `transform`; the API's
+  toasts say it was done or why not, and a refusal writes nothing.
+- **A record's history** (`api.audit`, so every row offers History; or `AuditHistory`/`openAuditHistory` on a page):
+  each entry says what was done, when and by whom - "by Sita Rai" when the answer carries `creatorName`, else the start
+  of the person's token ("User 3fA9b2…"), which still tells two people apart - and the columns it changed. An app whose
+  backend sends no names sets `setAuditActorNames(async (tokens, signal) => ({ [token]: "Sita Rai (sita.rai)" }))` once:
+  the history asks it once per page shown, for the tokens it has not had an answer for, and keeps the answers.
+- **Options narrowed by another input** (`narrowedBy: { name: "subscriptionGroupId" }` on an input, in a Form and its rows): a
+  Package list only of the Group picked. Static `options` are filtered by the records' `key` field (default the other
+  input's name); `loadOptions` is asked with `request.narrow`, which `crudPicker` answers from its kept list, or from
+  the server with `crudPicker(PACKAGES, { labelKey, narrowQuery: "subscriptionGroupId" })`. While the other input is
+  empty nothing is offered ("Pick a group first"), and a person changing it clears the value picked here.
+  **Or by a fixed value** the page knows when the form opens (`narrowedBy: { key: "subscriptionGroupId", value:
+  subscriber.subscriptionGroupId }`): nothing is followed or cleared, and a `null` value offers nothing. `orUnset: true`
+  (both forms) also offers the options whose field is empty: the Fee list of the group, and the fees of every group.
+  **Several at once, and in rows**: `narrowedBy: [{ name: "storeId", from: "form" }, { name: "itemId" }]` on a line
+  table's Tags offers the units of the line's Item in the form's Store - the first empty one asked for, a loader told
+  every value (`request.narrows`), and `crudPicker({}, { list: UNITS, valueKey: "tagNumber", labelKey: "tagNumber" })`
+  over `StockBalance/Units/{storeId}/{itemId}` reads each pair once, the values in its path. A person's new Item clears
+  that line's tags, a new Store every line's; a saved document loading keeps them. `dependsOn: ["quantity"]` on a row
+  input redraws its row as the quantity changes, so `cellParams` can cap the picks (`{ max: row.quantity }`).
+- **Cache.** Lists are kept for 5 minutes while the page is open (`cache={{ lifetime }}`, or `false`): going back to a
+  list paints it at once. After a change, the list in view keeps its rows and the others load again when shown; Reload
+  and the handle's `reload()` go past the cache. The cache goes when the page does.
+- **Permissions** come from the app's rules: `definePermissions(new NexusPermissions())` once, then `setActions(accessActions)`
+  after sign-in. While the rules load, the table shows placeholders; a user with no list sees a message. Rules for
+  another backend extend `Permissions` (`can(endpoint)`), and its page and mass shapes extend `CrudBackend`.
+- `ref` gives `table`, `mode`, `setMode`, `reload`, `create(values)`, `edit(row)`, and `view(row)`.
+- `scripts/browser-checks/crud.cjs` in the template checks `/demo/crud`: every list and action, the popups, the roles, the
+  cache, a phone, and contrast in every theme.
+
+### CRUD in a tree
+
+```tsx
+import { CrudTree } from "nexus-shared/client";
+
+// Where the records sit in the tree: one definition for the tree page and for a Crud whose changes it must follow.
+export const REGION_TREE: CrudTreePlacement<Region, RegionItem> = {
+  cacheKey: "regions-tree",
+  rules: { valueKey: "key", hasChildrenKey: "childCount", compare: bySortOrderThenName },
+  itemOf: region => ({ key: `r${region.id}`, label: region.name, childCount: region.childCount ?? 0, region }),
+  parentOf: region => `r${region.parentId}`,
+  recordOf: item => (item.region ? { ...item.region, childCount: item.childCount } : null),  // the count goes back
+  childValues: parent => ({ parentId: parent.region?.id }),
+  placeKeys: ["parentId"],  // where a record sits: fixed in the tree's forms, moved only on the data table page
+};
+
+<CrudTree<Region, RegionItem>
+  api={REGIONS} inputs={REGION_INPUTS} columns={REGION_COLUMNS} form={REGION_FORM} place={REGION_TREE}
+  tree={{ loadChildren, fill: true, "aria-label": "Regions" }}
+  details={({ row, body, actions }) => <AdminPanel title={row?.name ?? "Details"} action={actions}>{body}</AdminPanel>}
+/>
+<Crud<Region> api={REGIONS} columns={REGION_COLUMNS} inputs={REGION_INPUTS} trees={[REGION_TREE]} />  // the data table page
+```
+
+- **Actions.** Add New under any row (Insert), Edit (F2) and Move to trash (Delete) on a record's row, all three in its
+  context menu, Add New in the toolbar; the picked record's panel offers what its list offers - Recover and Delete
+  permanently once it is in the trash. The forms, questions and calls are the `Crud`'s own.
+- **The selected row.** A click or Enter on a row selects it (`TreeView` `selectedValue`): tinted, and staying so while
+  focus, the arrow keys and the chevrons move on. A record's row shows the record in the panel; a row that is no record
+  (a country) empties the panel and opens.
+- **A fixed place** (`placeKeys`). Every Add goes inside a row - the toolbar's inside the selected row, the one the panel
+  shows; with none (or one in the trash) a press says why - and the fields that say where a record sits show read-only in
+  the Add and Edit forms, with the lock and a note on any try: from the row added inside (`childValues`; a field it
+  leaves out is fixed empty), or the record's own. A record moves only where those fields are offered, such as the data
+  table's form. An Add started inside one row is a popup of its own, titled with its place ("Inside Bagmati", on the dock
+  too): it never comes back inside another row. A record's Edit stays one popup: asked for from the other page with
+  changes in it, it comes back as it is and says why, so an older form never undoes a newer save.
+- **Nothing read again.** A change is written into the tree and the pages it keeps (`writeTreeChanges`): an added record
+  goes where `compare` puts it among its loaded siblings and is shown there - or, under a parent never opened, into its
+  count, the parent left closed, since opening it would read its page - an edit is written in place or moved, a trashed
+  one leaves, and each parent's count and chevron follow. A save is not read back either: the record is built as `Crud`
+  builds it, its joined names from the form, the page, or the parent the tree holds.
+- **Another page's changes.** A `Crud` given the same placement in `trees` writes its changes into the tree's kept pages,
+  so the tree opened next shows them without a call.
+
+### Excel import and export
+
+A model's records in and out of a spreadsheet, against the backend's Excel controller bases
+(`NexusExcelController<TContract>` and `NexusExcelExportController<TContract>`): `Excel/Settings`, `Excel/Template`,
+`Excel/Verify`, `Excel/Import`, and the model's own export action.
+
+```tsx
+export const CITIES = MODULES.controller(NexusModule.Configuration, "City", "city");
+export const CITY_SHEET = excelEndpoints(CITIES, { subject: "city" });        // the four, and Excel/Export
+
+openExcelImport({ endpoints: CITY_SHEET, subject: "city", onImported: reload });   // the panel as a window
+<ExcelImport endpoints={CITY_SHEET} subject="city" onImported={reload} />          // or in the page
+openExcelImport({ endpoints: REGION_SHEET, subject: "region", mode: "bulk", onImported: reload }); // rows typed in
+
+await downloadExcelTemplate(CITY_SHEET);
+await exportExcel(CITY_SHEET, { subject: "city", rows: table.matches, query: { search, sort: "cityName", direction: "asc", filters } });
+```
+
+- **The template** is the backend's file, downloaded under the name its `Content-Disposition` gives it. Every list in it
+  is a dropdown and the ids beside a choice fill themselves, so the person types no code and pastes no id.
+- **A verify writes nothing.** The file goes up as form data, and the answer is the rows, judged: what would be added,
+  what is already a record, and what is waiting on a fix.
+- **The review is two editors** over those rows - **New rows** (which includes the rows to fix, since a row with a
+  problem is not yet a record) and **Already there**, which folds away - built from the sheet's columns with the rules
+  the sheet told the person about, so a fix made here is checked the way the file was. What the server found wrong is
+  listed under the rows, each entry naming the cell as a spreadsheet does (`B7 - City name`) and taking the caret to it.
+  Rows can be added to the new rows (Add, Insert, Duplicate); one added and left empty is not sent, and an added row is
+  numbered after every row of the file, so no two rows share a number. A sheet with a required list takes no added
+  rows: a list's key is picked in the spreadsheet, and a row added here could never have one.
+- **A bulk insert is an import with no file** (`mode: "bulk"`): the new rows' editor opens with one empty row, the
+  person types the rows, and they go to the same `Excel/Import` with the same checks - a problem then names its row
+  (`Row 3 - Region name`). A sheet with a required list cannot be typed in, and the panel says so.
+- **Nothing typed is lost unasked**: closing the window or Start over asks first, and the entry picked again while its
+  window is minimized (by a page's rule or from code: the window has no minimize button of its own) brings that window back. An import that wrote nothing keeps the rows, and lists under them what
+  the backend refused and why.
+- **The import sends rows, never the file again**, or every fix made on screen would be lost; every check runs again on
+  the way in. **A duplicate is never updated**: one left alone is not sent at all, and editing one sends it as a new
+  record. An import writes what it can and names the rest; only one that wrote nothing at all is a failure.
+- **A choice travels as its key**, out and back. The plain id in the sheet is for the person to read and is never read
+  back, so nothing copied out of a file or out of an answer can be posted to an endpoint as an id.
+- **The export is the server's file**, written from the search, the sort and the filters on screen - not a CSV of the
+  rows this browser holds. The row limit is the backend's (`Excel/Settings`, 5,000 by default, kept for the page's life);
+  over it the person is asked first, and the answer's own headers say what was written and what was left out.
+- **Generic, like the rest.** `ExcelBackend` is the class an app on another backend registers
+  (`defineExcelBackend(new MyExcelBackend())`): the request shapes, how the answers read, the upload field, and the names
+  of a download's headers. `NexusExcelBackend` is the default. `readExcelResponse` reads a refusal's `errorMessages`, so
+  "no city could be written" reaches the person in the backend's own words.
+- **A column draws its own input**: text, note, whole number, decimal, amount, date, time, Yes/No, and a choice shown
+  read-only with the words the person picked. A **date and time** is a text box, not a picker: the sheet's moment is a
+  zone-less wall clock while a picker's value is a UTC moment, so a picker would shift every value by the reader's offset.
+- `scripts/test-excel.mts` checks the endpoints, the answers, the inputs and the round trip; the template's
+  `scripts/browser-checks/excel.cjs` checks `/demo/excel`: every state, the two rules about the wire, both downloads, the
+  warning before a capped export, a phone, and contrast in every theme.
+
+In a table, `excel={{ endpoints: CITY_SHEET, subject: "city" }}` is the whole of it: the options menu (⋮) then offers
+**Download template**, **Import from a spreadsheet** (the panel as a window, after which the table reads its rows
+again), **Bulk insert** (the same with no file, beside an Add only; `bulk: false` leaves it out) and **Export to
+Excel**, which sends the table's own search, filters and sort with the page's `filters()`. A `Crud` passes it through
+as `table={{ excel }}` and drops the lists it had kept once an import has written. It replaces `onImport`, which stays
+for a page that imports its own way. Each item asks the app's permissions (`canCall`) for every endpoint it needs, the
+settings included - the template and the export their own, the import and the bulk insert Verify and Import - so a
+person the backend would refuse is not offered it. A download whose settings call fails stops there: one toast.
+
+Planned, following the previous Nexus project: a page status layout, and in the CRUD, audit logs in the details view.
+
+### Pictures and documents
+
+A record's pictures and documents are the files of an **owner** (a row of a module) in a **category** (what they are
+for: the kinds it takes, the size, how many an owner keeps, the thumbnail's size). A page declares them by params - the
+owner's `module`, the `category`, the `ownerId`, and for a picture its `aspect`, `shape`, `maxWidth`/`maxHeight`,
+`type` and `quality` - and every piece runs on the app's `FileAdapter`:
+
+| Piece | From | What it is |
+|---|---|---|
+| `EInputTypes.Picture` (`PictureInput`) | `nexus-shared` / `/client` | In a form: the owner's main picture, Upload, Edit, Remove, All pictures (a click on the picture opens them too); in a category that keeps one file, Replace and Delete. Changed at once: the form keeps no field for it (`holdsValue`), so a save sends nothing under its name, and it takes no `required`. `ownerId` null: "Save the record first". |
+| `PictureGallery`, `openPictureGallery` | `nexus-shared/client` | An owner's pictures in two panes: the main picture large with Upload and Remove and the count, then a grid of rounded squares, each with View, Make main, Edit and Delete inside it (on hover, on a keyboard's focus, always by touch; neither Make main nor Delete on the main one). Upload several, up to the category's count; edits are saved as new pictures. Under 560px the main picture sits small over the grid |
+| `DocumentList` | `nexus-shared/client` | The same as a list, for a category that takes PDF (the gallery picks it itself): kind, size, date, open, rename, delete; `changes` for a record whose files are only added to |
+| `pictureColumn` | `nexus-shared/client` | A table column with each row's picture: the page's rows in one call (`primaryPictures`), a click opens the row's gallery |
+| `OwnerPicture`, `usePrimaryPicture`, `useOwnerFiles` | `nexus-shared/client` | The small picture, the kept main picture, and the files with every change, for a page's own layout |
+| `loadImageEditor`, `preloadImageEditor` | `nexus-shared/client` | The image editor, downloaded from the file backend the first time it is needed; never in the bundle |
+| `FileAdapter`, `NexusDriveAdapter`, `defineFileAdapter` | `nexus-shared` / `/client` | Where files are kept: the Nexus Drive by default, any other backend by one class |
+
+```tsx
+import { EInputTypes, NexusModule } from "nexus-shared";
+import { openPictureGallery, pictureColumn } from "nexus-shared/client";
+
+const LOGO = { module: NexusModule.Enterprise, category: "company-logo", aspect: 1 };
+inputs: (action, row) => [{ type: EInputTypes.Picture, name: "logo", label: "Logo", ...LOGO, ownerId: row?.id, subject: "company" }, ...];
+columns: [pictureColumn({ ...LOGO, rowTitle: row => row.companyName }), ...];
+```
+
+- **Every picture goes through the editor before it is stored**: the picture input's Upload and Edit, and the gallery's
+  Upload one picture at a time ("Picture 2 of 5" in its title; Cancel skips one and asks "Go on with the next file?" -
+  Next file or Stop here). Documents (a PDF) are sent as they are. **The browser makes what is stored, within the
+  category's picture limits**, which Drive's `File/List` answers from its settings (`pictureMaxSide`, `pictureQuality`,
+  `pictureMaxBytes`; `pictureLimits` gives `PICTURE_LIMITS`, 1920 px, 80% and 300 KB, when a backend says none): the
+  editor crops to the shape, brings the long edge down to `pictureMaxSide` (less when the params say), starts the
+  quality at most at `pictureQuality` (its slider's top), and writes the file under `pictureMaxBytes` - a PNG with
+  nothing see-through as a JPEG, one with see-through parts as a WebP where the browser writes it (else a smaller PNG),
+  then a lower quality step by step, then a smaller picture - showing the real size in its Save panel and saying when it
+  had to shrink; the toast says so too. It writes only kinds the category takes (`types`): where it takes neither JPEG
+  nor WebP, a PNG too large is made smaller. A picture the browser could not type (a phone's share, a name with no
+  extension) is typed from its bytes (`typedFile`) and goes through the editor too. When the editor cannot be
+  downloaded, the picture input and the gallery say why under their buttons until a try opens it. It makes the thumbnail at the category's size. A kind the category refuses is
+  said before anything is made; a picture's size is checked against `pictureMaxBytes`, a document's against the
+  category's own (`fileRefusal`). The gallery's line says both. The backend checks the bytes again.
+- **A gallery opened without `view`** takes its title and icon from the category once it is read: "Documents" for one
+  that takes PDF. A page's rows whose read is refused or fails show no picture for 30 s (`retryAfter`), not one call
+  per redraw.
+- **With Nexus** (`NexusDriveAdapter`), the owner's module decides who may change the files: the adapter asks it for a
+  write ticket (`{module}/Files/Ticket/{category}/{ownerId}`, `me` for a person's own), keeps it until a minute before
+  it runs out and asks again once when Drive says it ran out (`DRV_X011`); a person refused a write ticket sees the
+  files read only through a read ticket (`Files/Owners/{category}`), which also reads a page's rows at once. The bytes
+  are Drive's `File/View/{id}/{Original|Thumbnail}` through the app's proxy.
+- **The editor** is served by the backend at a versioned address (Drive: `Assets/File/nexus-image-editor.txt` names the
+  current `nexus-image-editor.<hash>.js`), imported with the bundler told to leave it alone, once per page
+  (`importModule`, built without the import-extension rewrite so `dist` keeps a plain `import(url)` that webpack,
+  Turbopack and Vite leave to the browser; `test-dist-loader` guards it). When it cannot load (the network, a 404, a
+  bundler), the person gets a toast in plain words and the console the cause.
+- **Read only, and why.** `lockReason: "The branch is closed."` makes the files read only with that sentence under
+  them; a person the backend lets only look is told the backend's words (`OwnerFiles.readOnlyReason`), and the files
+  of an owner not in use (trashed, ended) say so (`OWNER_NOT_IN_USE_REASON`).
+- **Only some changes.** `changes: receipt.isPosted ? ["add"] : undefined` with `changesReason: "Posted: a document can
+  be added; none is removed."` keeps Upload and offers no Rename, Delete, Make main or Remove (nor a Replace or an Edit
+  that deletes or marks) for a record whose files may only be added to; the reason is said under the files. The changes
+  are `FileChange` words, the core's `EFileChanges` one for one. A refusal that says so - the Nexus `API_X084`, read by
+  `FileAdapter.changesLeft` - narrows them the same way for that owner under the server's words, so a page read before
+  the record was posted stops offering what the server refuses. `ownerFileActions` is the rule, for a page's own buttons.
+- **Initials.** `pictureColumn({ ..., nameKey: "fullname" })` (or `OwnerPicture name`) shows an owner with no picture
+  as the name's initials, on the shared `Avatar`'s tone for that name.
+- **The keyboard's focus stays.** While a change saves, the buttons stay focusable (`aria-disabled`, the press ignored:
+  `busyProps`), and when the focused one goes with the change (Remove, a star, a deleted file's) the focus moves to the
+  first control left in its tile, else in the input (`useFocusThroughChange`), never to the page.
+- **Another backend**: `defineFileAdapter(new MyFiles())`, a class with `list`, `primaries`, `upload`, `setPrimary`,
+  `rename`, `remove`, `fileUrl` and `editorModuleUrl`, answering `ApiResult`s; nothing else changes.
+
+### A record's page of cards
+
+`RecordCards` draws one record that is not a list - a person's profile, my company, a subscriber's details - as a hero
+across the top and cards under it, from params alone. **The page never saves**: a card's Edit, a list's Add and an
+item's icon actions open popups, and each answer is written into the card at once (every card on the same source
+follows, the hero too, with nothing read again).
+
+```tsx
+<RecordCards
+  name="profile"
+  sources={{ profile: { read: ACCOUNT_API.profile, held: { fullName: user.fullName } }, emails: ACCOUNT_API.emails }}
+  hero={{ source: "profile", title: p => p.fullName, lines: p => [`@${p.username}`], picture: p => ({ ...OWN_PICTURE, ownerId: p.id }) }}
+  signedOut={{ onSignIn: () => window.location.assign(signInHref("profile")) }}
+  cards={[
+    fieldsCard<Profile>({ id: "personal", source: "profile", title: "Personal details", fields: [FULL_NAME, DATE_OF_BIRTH, GENDER], edit: { submit: ACCOUNT_API.saveProfile } }),
+    itemsCard<ContactList, Contact>({
+      id: "emails", source: "emails", title: "Emails", items: "items", itemKey: "id", limit: "maxCount",
+      item: e => ({ title: e.address, marks: e.isPrimary ? [{ label: "Primary", tone: "primary" }] : [] }),
+      add: { title: "Add an email", inputs: [EMAIL], submit: ACCOUNT_API.addEmail },
+      itemActions: [{ id: "remove", label: "Remove", icon: <InlineIcon icon={iconTrash} />, tone: "danger",
+        held: e => (e.isPrimary ? "The primary email cannot be removed." : null),
+        confirm: { title: ({ item }) => `Remove ${item!.address}?`, submit: ACCOUNT_API.removeEmail, transform: ({ item }) => ({ id: item!.id }) } }],
+    }),
+  ]}
+/>
+```
+
+- **Sources** are read once each (GET through `api`, or a function answering an `ApiResult`); `held` is drawn while a
+  read runs. A card names its `source` (default the first).
+- **Fields cards** draw each value by the `InputParams` that edit it: a choice by its label, a date in the person's
+  format, Yes or No, chips (`look: "chips"`, a multiple choice), long text on its lines, "Not said" (`empty`) when empty.
+  `edit` opens a popup of those inputs on the record; the values are sent merged over the record as held now, so an
+  endpoint that takes the whole record works.
+- **Items cards** list rows with icon actions on the right, each named as a tooltip and to a screen reader with its
+  item, hidden (`hidden`), or held with its reason (`held`: aria-disabled, said in a note when pressed). `add` sits in
+  the heading, held at the `limit` ("5 of 5").
+- **Popups** are one step or `steps` (`start`, `next`): a sentence (`lead`), inputs, `submit`, `transform`, `writes`, a
+  button that calls and stays (`also`, held while the server says to wait), and `done` to run another action next
+  (`run("verify", added)`). A form opens only on the plain values its inputs name (and a rows input on its rows).
+  `confirm` asks, then calls.
+- **A step's form**: each step is handed its `form`, and `inputs` as a function gets it, so a label or `hidden` can
+  follow another input as typed (`inputs: ({ form }) => addressInputs(form)`, getters with `dependsOn`). `validate`
+  is the step's own rule over its values; `fresh: true` (or `goTo(id, { fresh: true })`) shows a step reached again
+  with nothing of before (an old code, a password). A password or a code typed is never asked about before it goes.
+- **Heading buttons** are named with their card ("Edit: Personal details"), held ("Still being read.") until the data is
+  read - their `hidden` and `held` are asked only then, `loading: "hidden"` draws one only then - and go under the
+  title where the card is narrow. `heldRows`, `heldRowLines` and a field's `heldLines` hold what the data usually
+  takes, so nothing under a card moves when it comes.
+- **`writes`**: the answer merged over the data (default), the values, one item replaced or added (`"item"`), the item
+  removed (`"remove"`), a read again, named fields, or a function.
+- **States** are the piece's: the cards held as they will be while they load, a failed read in each of its cards with
+  Try again, `readOnly` with no button anywhere, and `signedOut` - an answer that ended the session closes the popups
+  and leaves the page's words and its way back in.
+
+### Mail thread
+
+Mail inside the app: a **thread** with a subject, a sender and the people it went to (To, Cc, Bcc), whose first line is
+the mail and the rest are replies, drawn by the chat's own thread and reply box. A thread can be about a record (a
+leave request), and an app can write into it when something happens - a **notification**, drawn as a quiet event line
+among the replies. Everything comes through one interface, `MessageSource`, so a page passes params and the package
+does the rest.
+
+```tsx
+const mail = apiMessageSource(); // the app's MessageBackend: Nexus's Message module, Mail controller, by default
+const people = mailPeoplePicker(mail); // To, Cc and Bcc boxes that page the server and name what they hold
+
+<Crud<MailInboxRow>
+  api={{ pages: { normal: INBOX }, create: MAIL_CREATE }}
+  paging="server"
+  actions={["create", "view"]}
+  columns={mailInboxColumnList()}
+  inputs={[
+    { type: EInputTypes.Dropdown, name: "to", label: "To", multiple: true, required: true, ...people },
+    { type: EInputTypes.Dropdown, name: "cc", label: "Cc", multiple: true, ...people },
+    { type: EInputTypes.Dropdown, name: "bcc", label: "Bcc", multiple: true, ...people },
+    { type: EInputTypes.Text, name: "subject", label: "Subject", required: true, maxLength: 100 },
+    { type: EInputTypes.Markdown, name: "body", label: "Message", required: true, maxLength: 4000 },
+  ]}
+  form={{ newValues: () => ({ clientId: newMailClientId() }), createDefaults: mailComposeDefaults(mail, people) }}
+  details={{ size: "xl", render: row => <MailThread source={mail} threadId={row.id} userId={me.id} /> }}
+  table={{ rowStrong: mailRowUnread, openOnClick: true }}
+/>
+```
+
+- **The head** is a band at the top of the thread, scrolling with its lines (`ChatThread` `lead`), never in a box of
+  its own; the thread opens at its top. It holds the subject, the time, From, To and Cc, and Bcc **only as the source gives
+  it** (the sender sees every person copied unseen; a person copied unseen sees their own row; nobody else sees any).
+  Lists of people fold to three names and "+2", a button that opens the rest in place. A record the thread is about
+  is drawn as its card ([below](#a-records-card-in-a-message)) when its kind has one, read again when a notification
+  arrives, and folded to its title and figures while the thread is narrower than 480px (its real width, followed as
+  it changes, until the reader folds or unfolds it); otherwise as its kind (named by `defineChatDomains`) and its words.
+  `renderDomain` draws it instead.
+- **The lines** are a `ChatStore` on `source.threadSource(id)`: paging up, a reply on screen at once, Retry, read marks
+  (reading to the bottom marks the thread read; `onSummary` hands the page the new counts), polling.
+  `ChatMessage.kind` says what a line is: `chat`, `mail`, or `notification` (an event line with who acted, no bubble).
+- **A person copied unseen** reads "You were sent a blind copy. Replying shows you to everyone." over the reply box
+  (`mailBccNote`), and the reply box is described by it; once they reply the head is read again and shows them as a Cc.
+- **When someone else writes**, the head is read again (the people may have changed) and `onChanged` tells the page;
+  `reason: "notification"` means the record may have changed, and the record's slot is told too (`revision`).
+- **States**: the head held by bones while it loads, a failure with Try again in the head and in the thread, "This
+  message is not available to you." for a thread the reader is not on (403 or 404), a closed thread that is read and not
+  answered (`canSend: false`).
+- **`MessageBackend`** maps each action to an endpoint and reads each answer; `NexusMessageBackend` is the Message
+  module's `Mail` controller (POST `Inbox`, `History`, `Create`, `Reply`, `People`; GET `Thread/{id}`, `Unread`,
+  `Defaults`; PUT `Read`, `Archive`, `Unarchive`), reading a role (1 From, 2 To, 3 Cc, 4 Bcc) and a line's type (0 chat,
+  1 mail, 2 notification) as this package's words. Override `module` or any reader for another backend.
+- **`localMessageSource({ userId, people, threads })`** keeps a mailbox in memory with a backend's rules - who sees
+  whom, a blind copy's reply, archive and unread per person, a retried send written once - for a demo or a test;
+  `as(userId)` reads it as somebody else and `post` writes a module's notification.
+- **Three params any page can use**: `pagedPicker` (a dropdown over any server search, naming the values it holds),
+  `Crud` `form.createDefaults` (an Add form's values read as it opens; a failed read opens it on `newValues`), and
+  `DataTable` `rowStrong` (a row read strong while a field says so).
+
+### A record's card in a message
+
+A message about a record - a leave request, a requisition - shows that record as a **card**, read live from the module
+that owns it each time it is drawn, never a copy kept in the message. The package knows no module and no record kind:
+an app gives each kind it names with `defineChatDomains` a `card` - how to read the record and what to show of it - and
+every thread about that kind draws it at its head. Every kind looks alike, because a card is params.
+
+```tsx
+defineChatDomains([
+  {
+    domain: EDomainTypes.LeaveRequest,
+    key: "leave-request",
+    label: "Leave request",
+    card: domainCard({
+      // The owning module's card door, which checks the reader. 403 and 404 read "You cannot open this leave request."
+      load: (id, signal) => api.get<LeaveRequestCard>(REQUEST_CARD.leave, { params: { id }, signal, toast: false }).then(unwrapApiResult),
+      // `view` is typed by what `load` answers.
+      view: leave => ({
+        title: `${leave.leaveTypeName} · ${formatDays(leave.days)}`,
+        code: leave.requestCode,
+        state: { label: "In approval", tone: "info" },
+        fields: [
+          { label: "From", value: leave.startDate, kind: "date" },
+          { label: "To", value: leave.endDate, kind: "date", note: "half day" },
+        ],
+        figures: [
+          { label: "Available", value: leave.balance.availableDays, kind: "days" },
+          { label: "Held", value: leave.balance.heldDays, kind: "days", tone: "warning" },
+        ],
+        link: { href: "/admin/requisition/my-approvals", label: "Open My approvals" },
+      }),
+      held: { subtitle: true, fields: 2, figures: 2 }, // what its placeholder holds the first time
+    }),
+  },
+]);
+
+<DomainCard domain={EDomainTypes.LeaveRequest} id={token} label="LR2082-0007 · Puja Shrestha" viewer={me.id} />
+```
+
+- **The card** (`DomainCardParams`): the kind as a tag and the title; a quiet line under it with the code, a subtitle and
+  the link at its end; the state as a tag in its tone; figures first (large values in a row, two to a row on a phone,
+  a tone mark beside each, a hint under one keeping two lines); then its details: fields (a label over each value, as
+  many to a row as fit) and lines (a short table, numbers and
+  money at the end, the first column one line cut with "..."; "and 3 more"). Values are written by their kind with the
+  reader's settings: `date`, `datetime` (their zone), `days` (`formatDays`: "1 day", "2.5 days"), `money` (the card's
+  `currency`, `formatMoney`), `number`, `person`, `text`. A field with no value is left out unless it names `empty`.
+  `extra(data)` adds one more piece of this package's parts after the lines. A band, never a box: a mail thread's head
+  draws a line above it.
+  The fold button folds the details and keeps the figures (folded, a leave's card is its title, code and balance);
+  `collapsed` with `onCollapsedChange` lets a page hold the fold, `defaultCollapsed` starts it.
+- **Every state**: a placeholder of the card's own parts, in the shape of the kind's last card (or its `held`), so the
+  record lands without moving what is under it, at any width; the card; "You cannot open this leave request." for 403
+  and 404 alike (a stranger learns nothing from the difference); "Could not load this leave request." with Try again
+  for anything else; the kind and the record's words alone for a kind with no card or a message with no id. `view`
+  throwing on an answer is a failure too, never a broken thread.
+- **Read again**: when `revision` grows (a mail thread's notification), `ref.reload()`, or `refreshDomainCards(kind,
+  id)` (the page changed the record itself). The card stays while it is read, says "Updated 2:45 PM" when the record
+  turned out different, and "Not up to date" with Try again when the read failed; a refusal on a read again drops it.
+  A screen reader is told each.
+- **Reads** (`DomainCardReads`, `domainCardReads`): one read of a record at a time however many cards draw it, an
+  answer kept 30 seconds per reader (`lifetime`), a failure never kept, a read nobody waits for aborted, a read again
+  taking only a read started after the change and forgetting what other readers kept. `useDomainCard` and
+  `DomainCardRun` give a page the same read for a look of its own; `DomainCardFrame` draws a card from params a page
+  already holds, with no read.
+
+### Message bell
+
+How much internal mail waits, on a top bar's button: the count over its corner in the chat's badge (one size whatever
+the count, "99+" from 100 on) and the newest unread threads a click away, each a link into the inbox.
+
+```tsx
+const mail = apiMessageSource(); // one object for the page: every bell on it shares one poller
+
+<AdminLayout
+  utilities={[{ code: "notifications", label: "Messages", icon: "bell" }]}
+  renderUtility={item => (item.code === "notifications" ? <MessageBell source={mail} href="/admin/message/inbox" label={item.label} /> : undefined)}
+/>
+```
+
+- **One read however many bells.** `useMessageUnread(source)` joins the page's poller for that source: it reads when
+  the first bell appears, then every minute while the page is in front, at once when the window takes the focus or the
+  tab comes back, and never while the tab is hidden. A failure keeps the count read before. Call
+  `refreshMessageUnread(source)` after the page reads or archives threads, and every bell on it reads at once - or
+  right after the read on its way, which may have counted before the change (one more read, however many are asked).
+- **The menu**: the newest unread (subject; who wrote last, the record, when), a row opening `href?thread=<id>` (or
+  `threadHref(row)`), "Open inbox", and Try again after a failure. Opening it reads the count again.
+- **A screen reader** hears the button's name ("Messages: 3 unread messages") and, when the count goes up, the new
+  count once from one bell of the page - never on every read, never as the page loads.
+- **`Button` `badge`** is the piece underneath: a count over any button's corner that leaves its size alone.