efficient-shell 4.127.0 → 4.131.0

package/README.md

@@ -373,7 +373,7 @@ All exports are named — `import { Modal, ... } from 'efficient-shell'`.
 |---|---|
 | `<ShellAuthProvider value={{ hasAnyPerm }}>` | Permission-filter nav items. |
 | `<ShellPrefsProvider value={{ prefs, save }}>` | Where the shell reads/writes user prefs (theme, taskbar pos, sticky notes, …). Use `useLocalStoragePrefs(key)` for a backend-less default. Since 4.92.0 it is also how `<EntityList>` / `<ResizableTable>` column config and sort persist: with no provider mounted, `useShellPrefs()` reads empty and drops saves, so both silently degrade to localStorage-only and never reach the user's profile. Session restore reads `session_windows` once, at mount: hand the provider prefs that are already loaded by then (an adapter whose prefs arrive later misses that load's replay, though the saved set is kept). |
-| `<ShellStringsProvider value={{ … }}>` | Translates the shell's own strings — window controls, taskbar hints, the logout cover, About/What's New, picker and table defaults, the help viewer. English works with NO provider; the override is a typed partial merged per section, so an incomplete catalog falls back rather than breaking. Prop-level text (`emptyText`, placeholders) always wins over the catalog. |
+| `<ShellStringsProvider value={{ … }} locale?>` | Translates every word the shell and the kit draw on their own account — window controls, taskbar hints, dialogs, pickers, pagers, list footers, upload zones, charts, timelines. English works with NO provider; the override is a typed partial merged per section, so an incomplete catalog falls back rather than breaking. Prop-level text (`emptyText`, placeholders) always wins over the catalog. `locale` (a BCP 47 tag) writes dates and numbers that locale's way; without one nothing moves. See [Languages, dates and numbers](#languages-dates-and-numbers--shellstringsprovider) for the full catalog. |
 | `<ShellEntityFetcherProvider value={(endpoint, id) => …}>` | How the modal stack fetches entity data. |
 | `<BugReportConfigProvider value={{ submit, list?, resolve? }}>` | Wire the bug-report flow to your backend. |
 | `<DesktopHostProvider value={{ stickyResolver?, saveShortcuts?, … }}>` | Sticky-note ref resolver + persistence callbacks. |
@@ -403,6 +403,7 @@ All exports are named — `import { Modal, ... } from 'efficient-shell'`.
 | `useUndoCanEdit(canEdit)` | A form's own word on whether the record may be edited right now — `useUndoCanEdit(!isLocked)`. While false the stack records nothing, ⌘Z is left alone and the footer shows no controls. A nested `<UndoProvider canEdit={false}>` in the form's JSX says the same thing: it shadows the stack for its children AND forwards the read-only claim to the window's stack, which is where the form's own `useUndoableState` calls (made above it in the tree) register. Either form of the claim makes the whole window read-only. The positive claim, `useUndoCanEdit(true)`, is how a window that edits in place outside Edit mode — a detail with inline cells behind a permission — asks the footer for the pair. |
 | `useMultiModal()` | Manages multi-window stacking + activate/blur. |
 | `useShellAuth() / useShellPrefs() / useShellEntityFetcher() / useBugReport() / useDesktopHost()` | Context readers — the shell uses these internally; consumers may also call them. |
+| `useShellStrings() / useShellLocale()` | The active catalog, and the provider's `locale` (`undefined` without one) — for a host cell that should write a date or a number the way the kit does. |
 
 ### Apps barrel — `efficient-shell/apps`
 
@@ -491,8 +492,20 @@ What you get: every form control, the display and layout primitives
 `HelpCenter`, `EditableGrid`, `SearchableSelect`, `PopupMenu`), the charts, all
 nine page templates, the pageless data primitives (`Pagination`, `Kanban`,
 `ListFooter`, `ListLoadError`), `toast`, and the theming hooks (`useTheme`,
-`resolveTheme`, `applyThemePrefs`) — you need those last ones to reach dark mode
-or an accent at all, since both work by stamping `data-theme`.
+`resolveTheme`, `applyThemePrefs`) — the way to an accent theme, which works by
+stamping `data-theme`. Dark mode answers to either `<html data-theme="dark">`
+(what `useTheme` stamps) or `<html class="dark">` (next-themes, shadcn/ui,
+Tailwind's class strategy), so an app whose own theme switcher already sets the
+class gets the kit's dark mode with nothing more to wire.
+
+**An app with its own design system** can keep the kit off its markup. Three
+rules in `ui.css` style bare elements rather than the kit's components: dark
+form controls (every `input`, `select` and `textarea`), the 16px font-size that
+stops iOS zooming on focus (narrow or coarse-pointer screens), and dark
+scrollbars. In a portal built on the kit that is what you want; in an app that
+draws its own controls it restyles them. `<html class="rosh-host-elements">`
+turns those three off. The kit's own controls stay dark through their
+remapped utility classes.
 
 What you do not get: `Modal` and the window manager, `Layout`, `Desktop`,
 `StartMenu`, `GlobalSearch`, the settings panels, the bundled apps, and the
@@ -510,6 +523,914 @@ layers without preflight.
 `efficient-shell` (the root entry) is unchanged and remains a superset: same
 components, same bindings, plus the shell.
 
+### Server rendering (Next.js App Router)
+
+Every React entry — the root, `ui`, `apps`, `markdown`, `file-intake`,
+`page-tabs`, `map` — starts with `"use client"`, so a **server component can
+import and render kit components**: they are server-rendered as client
+components and hydrated in the browser.
+
+```tsx
+// app/bookings/page.tsx — a server component
+import { Card, PageHeader, DataTable } from 'efficient-shell/ui';
+```
+
+- **Kit functions and constants are client references.** `toast`, `confirm`,
+  `formatDate`, `inputClasses`, `resolveTheme`, `CMD_K`, `Z_LAYERS`… arrive in a
+  server component as references, not values: call them from client code (a
+  `'use client'` file, an event handler, an effect). From a server component,
+  render components and pass them serialisable props.
+- **`markup` is server-safe.** It has no directive and imports no React, so its
+  functions are plain functions you can call from server code.
+- **The first render is the server's.** What only a browser knows renders as
+  the server would, and switches one render after hydration: the ⌘ forms of the
+  shortcut constants (render them through `<Kbd keys={CMD_K} />`, which handles
+  the switch; `isMac` is `false` on a server), a `SidebarLayout`'s saved width,
+  `useLocalStoragePrefs`, the OS dark-mode setting in `useTheme`, reduced motion,
+  and *today* — `Calendar` marks it after hydration, and a `Calendar` with
+  nothing to open on (no `value`, `month` or `defaultMonth`) draws an empty frame
+  until then, so pass `defaultMonth` if the server knows the month. Popups and
+  portals open after hydration. A root that was never server-rendered sees none
+  of this: it reads the browser on its first render, as before.
+- `formatDate` writes the default format on a server. A page that also lets
+  readers choose a format (`user_date_format`) should format those dates in the
+  browser after mount.
+
+### Theming the kit from a host app
+
+An app with its own design system — its own neutrals, its own primary, square
+corners, one focus treatment for the whole app — can put the kit under its look
+without forking a component. Every colour, radius, typeface and focus ring the
+kit draws comes from a token, and the knobs below are all of them. (A colour
+written as a literal in a kit module fails the build:
+`tests/kitColourLiterals.test.ts`.)
+
+Write light classes in your own markup and never `dark:` variants. The kit's
+dark mode remaps utility classes under `<html data-theme="dark">` or
+`<html class="dark">` — so a next-themes or shadcn/ui host already has it, and
+points it at its own palette through the neutral roles below — and its accent
+themes under `data-theme="pink" | "green" | "grey" | "blue"`, which only a host
+that stamps one gets. `rosh-host-elements` on `<html>` keeps the three rules
+that style bare `input`/`select`/`textarea` and scrollbars off your own markup.
+
+Your `@theme` wins whichever side of the import it is on (the kit's is
+`@theme default`). Your `:root` and dark overrides of the kit's TOKENS are plain
+declarations, where source order decides, so import the kit first:
+
+```css
+@import "tailwindcss";
+@import "efficient-shell/ui.css";
+/* your @theme and :root blocks after this line */
+```
+
+**Palette.** Kit components paint with Tailwind palette utilities, which
+compile to `var(--color-<family>-<step>)`, so `@theme` reaches them. The
+families the kit uses: **gray** (nearly all chrome: surfaces, borders, text),
+**blue** (the accent: primary buttons, links, selection, the chosen tab),
+**red** (danger and invalid), **green** (success), **amber** and **yellow**
+(warning), one **emerald** and one **neutral** (a template's sparkline,
+BrandMark's dark plate), plus `white` and `black`. Status badges and charts read
+their own tokens (`--status-*`, `--viz-*`, `--rosh-donut-*`) rather than the palette.
+
+```css
+@theme {
+  /* a neutral gray ramp, and a near-black primary */
+  --color-gray-50: oklch(98.5% 0 0);   /* … through --color-gray-950 */
+  --color-blue-600: oklch(20.5% 0 0);  /* the primary Button's fill */
+  --color-blue-700: oklch(14.5% 0 0);  /* its hover */
+}
+```
+
+**Accent, picked at runtime.** `applyThemePrefs({ accent_color })` (or
+`useTheme`) stamps `data-custom-accent` on `<html>` and the `--accent-50` …
+`--accent-700` scale inline; `themes.css` then remaps the blue accent utilities
+to that scale, and the timeline, `SidebarLayout`'s resize handle and the accent
+focus ring follow it. A host can stamp the same attribute and scale itself. For
+a fixed brand colour, `@theme` above is simpler.
+
+**The neutral roles.** Twelve tokens, declared for light on `:root` and for dark
+under `:is([data-theme="dark"], .dark)`: `--surface`, `--surface-sunken`, `--surface-raised`,
+`--line-subtle`, `--line`, `--line-strong`, `--ink-faintest`, `--ink-faint`,
+`--ink-muted`, `--ink`, `--ink-strong`, `--ink-strongest`. Dark mode's remaps,
+the timeline card and the frosted glass read them.
+
+```css
+:root { --surface: #ffffff; --line: oklch(92.2% 0 0); --ink-strongest: oklch(14.5% 0 0); }
+:is([data-theme="dark"], .dark) { --surface: oklch(14.5% 0 0); --line: oklch(26.9% 0 0); }
+```
+
+**Focus.** Kit controls ring on `:focus-visible`, so a button does not ring
+when it is clicked and a text field does (it takes typing, so the browser shows
+where the caret went). The ring colours are tokens; each default is the
+Tailwind colour the kit always drew:
+
+| Token | Default | Where |
+|---|---|---|
+| `--rosh-focus-ring` | blue-400 at 30% | fields, outlined and quiet buttons, Checkbox, Radio |
+| `--rosh-focus-ring-strong` | blue-400 at 40% | primary Button, Switch, TileButton, a badge's close |
+| `--rosh-focus-ring-solid` | blue-400 | edgeless controls: a dialog's close, calendar days, table rows, crumbs, steps |
+| `--rosh-focus-ring-deep` | blue-500 | charts (plot, legend), a chip's remove, the date-range field |
+| `--rosh-focus-ring-accent` | blue-500, follows the accent | HelpCenter's search, the prompt dialog's field |
+| `--rosh-focus-ring-zone` | `rgba(59,130,246,.45)` | upload zones and thumbnails |
+| `--rosh-focus-ring-invalid` | red-400 at 30% | an invalid field, `ghost-danger` |
+| `--rosh-focus-ring-invalid-strong` | red-400 at 40% | the `danger` Button |
+| `--rosh-focus-ring-invalid-solid` | red-400 | `FormErrorSummary` |
+
+To give the whole app **one** focus treatment, hand focus to the host: put
+`rosh-host-focus` on `<html>` (or on any ancestor of the kit). The kit then
+draws no ring and no outline of its own and removes nothing, so your rule is
+what every kit control shows — including one in `@layer base`, which the kit
+outranks otherwise:
+
+```html
+<html class="rosh-host-focus">
+```
+
+```css
+@layer base {
+  :where(a, button, input, select, textarea, summary, [role="button"], [role="tab"],
+    [tabindex]:not([tabindex="-1"])):focus-visible {
+    outline: 2px solid var(--ring);
+    outline-offset: 2px;
+  }
+}
+```
+
+A class rather than a token, because no token value can give an outline back:
+the kit takes the browser's outline off its controls while it draws a ring, and
+only a selector that stops matching can stop that. A focused text field still
+changes its border colour (`focus:border-blue-400`): that is the field's edge,
+so the palette above governs it.
+
+**Radius and type.** `ui.css` declares `--radius-sm` … `--radius-2xl`,
+`--font-sans` and `--font-mono` as `@theme default`; declare your own anywhere. Bare
+`rounded` and `rounded-full` (pills, switches, avatars, badges) compile to fixed
+values unless you name `--radius` and `--radius-full` too. A few kit component
+classes in `ui.css` (the timeline card's) carry pixel radii of their own.
+
+```css
+@theme {
+  --radius: 0; --radius-sm: 0; --radius-md: 0; --radius-lg: 0; --radius-xl: 0; --radius-2xl: 0;
+  --font-sans: "Inter", ui-sans-serif, system-ui, sans-serif;
+}
+```
+
+**Glass.** Menus, popups, listboxes and tooltips are frosted glass
+(`glassStyle()`). `--menu-opacity` (0–1, default `0.95`) sets how much shows
+through. `rosh-reduce-transparency` on `<html>` makes every popup one solid
+`--rosh-glass-surface` (default: `--surface`) with no blur — and strips
+`backdrop-filter` from everything else on the page too, since it is the user's
+"Reduce transparency" preference. The frosted look itself is
+`--rosh-glass-surface`, `--rosh-glass-surface-mid`, `--rosh-glass-border` and
+`--rosh-glass-shadow`; the solid one adds `--rosh-glass-solid-border` and
+`--rosh-glass-solid-shadow`. All have light and dark values.
+
+```css
+:root { --rosh-glass-surface: var(--popover); --rosh-glass-solid-shadow: 0 4px 12px rgb(0 0 0 / 0.08); }
+```
+
+**Everything else** a kit component paints, each defaulting to the literal it
+replaced: `--rosh-media-scrim` and `--rosh-media-scrim-button` (the dark wash
+under text and buttons on an upload thumbnail), `--rosh-drop-ring` (the halo
+while a file is dragged over a gallery), `--rosh-mark-plate-shadow` and
+`--rosh-mark-plate-shadow-strong` (`BrandMark`'s plates), `--rosh-resize-handle`
+(`SidebarLayout`'s handle without a custom accent), and `--rosh-donut-1` …
+`--rosh-donut-8` with `--rosh-donut-track` (`DonutChart`'s default palette —
+point them at `--viz-series-*` for one palette across every chart). The chart
+palette (`--viz-*`), the status tiers (`--status-*`) and the timeline
+(`--tl-*`) are documented where `ui.css` declares them.
+
+### Languages, dates and numbers — `ShellStringsProvider`
+
+Every word the kit draws on its own account — a dialog's "Close", a pager's
+"Previous page", a chart's tooltip rows, a calendar's "Next month", an upload
+zone's refusal — comes from one typed catalog. With no provider the catalog is
+American English and the markup is exactly what it has always been. Mount the
+provider once, near the top of the app, with whatever you translate:
+
+```tsx
+import { ShellStringsProvider, type ShellStringsOverride } from 'efficient-shell/ui';
+
+// Your own catalog, your own plural rules — the kit asks for nothing else.
+function kitStrings(t: (key: string, values?: object) => string): ShellStringsOverride {
+  return {
+    dialog: {
+      close: t('kit.close'), cancel: t('kit.cancel'), ok: t('kit.ok'),
+      // Word order is the translation's: the kit draws the <kbd> wherever
+      // the sentence puts the word.
+      typeToConfirm: word => t('kit.typeToConfirm', { word }),
+    },
+    pagination: { previous: t('kit.previousPage'), next: t('kit.nextPage') },
+    // A sentence with a value in it is a function. Counts arrive as numbers,
+    // so a plural rule can choose the words: "1 запись", "5 записей".
+    list: {
+      allLoaded: (total, label) => t('kit.allLoaded', { total, label }),
+      loadedOf: (loaded, total, label) => t('kit.loadedOf', { loaded, total, label }),
+    },
+  };
+}
+
+<ShellStringsProvider value={kitStrings(t)} locale="de-DE">
+  <App />
+</ShellStringsProvider>
+```
+
+**How the catalog merges.** `value` is a partial: per section, keys you leave
+out keep their English default, so a catalog that falls behind a release still
+works. A prop on the component (`emptyText`, `placeholder`, `label`,
+`emptyLabel`, a chart's `formatValue`) always wins over the catalog — the
+catalog replaces the kit's defaults, never your words. A nested provider's
+`value` merges onto the English defaults, not onto its parent's.
+
+**Sentences are functions, deliberately not templates.** The catalog is not an
+i18n library: no message syntax, no plural rules. An entry that carries a value
+is a plain function, and you write it with whatever you already use. Two rules
+make the arguments predictable:
+
+- a **count** arrives as a `number`, unformatted, because the words depend on it
+  — format it yourself (the English defaults format it in the provider's
+  `locale`);
+- a **value the kit has already written** — a date, a file size, the output of
+  your own `formatValue` — arrives as the `string` that will be printed.
+
+Three older entries are halves the kit concatenates (`select.remove` before a
+chip's label, `pageTabs.close` before a tab's title, a count before
+`pageTabs.discardMany`). They still work; each now has an optional
+whole-sentence function beside it (`select.removeItem`, `pageTabs.closeTab`,
+`pageTabs.discardCount`) that wins when you supply it, for a language whose
+word order a concatenation cannot express.
+
+**`locale` — how dates and numbers are written.** A BCP 47 tag. With one:
+
+- `Calendar`, `DatePicker` and `DateRangePicker` take month and weekday names —
+  and the full date each day is announced as — from `Intl.DateTimeFormat` in
+  that locale (`Oktober`, `Mo.`, `2026年10月2日`). The calendar is always
+  Gregorian, whatever the locale's default.
+- `DatePicker native`, `DateTimePicker` and `TimePicker` are drawn by the
+  browser, so they get the locale the one way they can: a `lang` attribute.
+- `formatDate`, and the timelines' dates, are written by `Intl` in the locale
+  (`dateStyle: 'medium'` by default). The stored `user_date_format` is not read
+  — a locale is the host saying how dates read for everyone it serves.
+- Numbers the kit formats itself use `Intl.NumberFormat` in the locale: list
+  footers, page numbers, `Statistic`, `CountBadge`, chart axes, tooltips,
+  percentages and the meters (`1.234,5`, `37,5 %`).
+
+With no `locale` — no provider, or a provider that only translates strings —
+nothing changes: the same English month names, `DD/MM/YYYY` from the stored
+setting, `toLocaleString()` with no argument, `String(v)`. Mounting the provider
+for its strings alone moves no digit. A nested provider without a `locale`
+keeps its parent's; a malformed tag (`en_US`) is reported once on the console
+and ignored rather than thrown in render. Which day a week starts on is still
+`weekStartsOn`, not the locale's to change. `InputNumber` keeps a `.` decimal in
+the field, because what is typed there is parsed back.
+
+`useShellLocale()` reads the tag for your own cells — pass it on as
+`formatDate(value, { locale, style })` or `fmtSliderDate(ms, locale)`, or hand it
+to `Intl` directly — so a host's dates and numbers read like the kit's.
+
+**What is not in the catalog, on purpose:** month and weekday names (the
+`locale` supplies them); file-format names in `BrandAssetEditor`'s default
+`acceptHint` and the `20ft`/`40ft` container codes (notation, not language); the
+`Kbd` shortcut constants (key symbols); `STAGES` labels (data a consumer's own
+tables read); the sample content of the starter templates (`DashboardTemplate`,
+`AuthScreen` and the rest are demos to copy, not components to configure); and
+console warnings, which are for developers.
+
+**The full catalog** — 39 sections, 359 keys. A function's default is shown
+with sample arguments.
+
+<details><summary><code>window</code> — 17 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `minimize` | `string` | `Minimize` |
+| `restore` | `string` | `Restore` |
+| `maximize` | `string` | `Maximize` |
+| `windowed` | `string` | `Windowed` |
+| `pinOnTop` | `string` | `Pin on top` |
+| `unpin` | `string` | `Unpin from top` |
+| `close` | `string` | `Close` |
+| `windowSuffix` | `string` | `window` |
+| `prev` | `string` | `Prev` |
+| `next` | `string` | `Next` |
+| `snapLayouts` | `string` | `Snap layouts` |
+| `snapLeft` | `string` | `Snap left half` |
+| `snapRight` | `string` | `Snap right half` |
+| `snapTopLeft` | `string` | `Snap top-left quarter` |
+| `snapTopRight` | `string` | `Snap top-right quarter` |
+| `snapBottomLeft` | `string` | `Snap bottom-left quarter` |
+| `snapBottomRight` | `string` | `Snap bottom-right quarter` |
+
+</details>
+
+<details><summary><code>taskbar</code> — 9 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `closeWindow` | `string` | `Close window` |
+| `offscreenHint` | `string` | `This window is off screen — click to bring it back` |
+| `offscreenDot` | `string` | `Off screen — click to bring this window back` |
+| `expose` | `string` | `Exposé — show all open windows as thumbnails` |
+| `addToDesktop` | `string` | `Add to desktop` |
+| `removeFromDesktop` | `string` | `Remove from desktop` |
+| `minimizeAllWindows` | `string` | `Minimize all` |
+| `restoreAllWindows` | `string` | `Restore all` |
+| `closeAllWindows` | `string` | `Close all` |
+
+</details>
+
+<details><summary><code>logout</code> — 2 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `goodbye` | `string` | `Goodbye` |
+| `seeYou` | `string` | `See you next time` |
+
+</details>
+
+<details><summary><code>about</code> — 5 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `aboutPrefix` | `string` | `About` |
+| `thisApp` | `string` | `this app` |
+| `openSourceLicenses` | `string` | `Open Source Licenses` |
+| `whatsNew` | `string` | `What's New` |
+| `noChangelog` | `string` | `No changelog available.` |
+
+</details>
+
+<details><summary><code>table</code> — 4 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `empty` | `string` | `Nothing to show` |
+| `loading` | `string` | `Loading` |
+| `selectAll` | `string` | `Select all rows` |
+| `selectRow` | `string` | `Select row` |
+
+</details>
+
+<details><summary><code>select</code> — 6 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `none` | `string` | `— None —` |
+| `noMatches` | `string` | `No matches` |
+| `allSelected` | `string` | `All options selected` |
+| `clear` | `string` | `Clear selection` |
+| `remove` | `string` | `Remove` |
+| `removeItem?` | `(label: string) => string` | *(none — the older halves are concatenated)* |
+
+</details>
+
+<details><summary><code>notifications</code> — 9 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `title` | `string` | `Notifications` |
+| `markAllRead` | `string` | `Mark all read` |
+| `dnd` | `string` | `Do not disturb` |
+| `dndOn` | `string` | `Do not disturb is on` |
+| `caughtUp` | `string` | `All caught up` |
+| `empty` | `string` | `No notifications yet` |
+| `viewAll` | `string` | `View all notifications` |
+| `cardLabel` | `string` | `Notification` |
+| `dismiss` | `string` | `Dismiss notification` |
+
+</details>
+
+<details><summary><code>form</code> — 1 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `errorSummaryTitle` | `string` | `There is a problem` |
+
+</details>
+
+<details><summary><code>help</code> — 10 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `title` | `string` | `Help` |
+| `searchPlaceholder` | `string` | `Search help…` |
+| `empty` | `string` | `No help articles yet.` |
+| `noResults` | `string` | `No articles match your search.` |
+| `loading` | `string` | `Loading…` |
+| `pickArticle` | `string` | `Pick a help article from the left.` |
+| `noBody` | `string` | `This article has no body yet.` |
+| `draft` | `string` | `Draft` |
+| `newArticle` | `string` | `+ New` |
+| `edit` | `string` | `Edit` |
+
+</details>
+
+<details><summary><code>update</code> — 2 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `available` | `string` | `A new version is available.` |
+| `refreshNow` | `string` | `Refresh now` |
+
+</details>
+
+<details><summary><code>pageTabs</code> — 13 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `label` | `string` | `Open pages` |
+| `close` | `string` | `Close` |
+| `closeTab?` | `(title: string) => string` | *(none — the older halves are concatenated)* |
+| `closeOthers` | `string` | `Close other tabs` |
+| `closeRight` | `string` | `Close tabs to the right` |
+| `closeAll` | `string` | `Close all tabs` |
+| `unsaved` | `string` | `Unsaved changes` |
+| `discardTitle` | `string` | `Discard unsaved changes?` |
+| `discardOne` | `string` | `This page has changes that have not been saved. Close it anyway?` |
+| `discardMany` | `string` | `pages have changes that have not been saved. Close them anyway?` |
+| `discardCount?` | `(count: number) => string` | *(none — the older halves are concatenated)* |
+| `discardConfirm` | `string` | `Discard and close` |
+| `keepEditing` | `string` | `Keep editing` |
+
+</details>
+
+<details><summary><code>dialog</code> — 9 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `close` | `string` | `Close` |
+| `cancel` | `string` | `Cancel` |
+| `ok` | `string` | `OK` |
+| `confirmTitle` | `string` | `Confirm` |
+| `destructiveTitle` | `string` | `Confirm Action` |
+| `destructiveCancel` | `string` | `Dismiss` |
+| `destructiveConfirm` | `string` | `Delete` |
+| `typeToConfirm` | `(word: string) => string` | `Type {word} to confirm:` |
+| `promptTitle` | `string` | `Enter a value` |
+
+</details>
+
+<details><summary><code>calendar</code> — 10 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `previousMonth` | `string` | `Previous month` |
+| `nextMonth` | `string` | `Next month` |
+| `previousYear` | `string` | `Previous year` |
+| `nextYear` | `string` | `Next year` |
+| `previousYears` | `string` | `Previous years` |
+| `nextYears` | `string` | `Next years` |
+| `monthPanel` | `string` | `Choose a month` |
+| `yearPanel` | `string` | `Choose a year` |
+| `chooseMonth` | `(month: string) => string` | `Choose a month, currently {month}` |
+| `chooseYear` | `(year: number) => string` | `Choose a year, currently 2026` |
+
+</details>
+
+<details><summary><code>datePicker</code> — 4 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `placeholder` | `string` | `Select a date` |
+| `dialog` | `string` | `Choose a date` |
+| `clear` | `string` | `Clear` |
+| `today` | `string` | `Today` |
+
+</details>
+
+<details><summary><code>dateRange</code> — 18 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `placeholder` | `string` | `Date Range` |
+| `clearRange` | `string` | `Clear date range` |
+| `dialog` | `string` | `Date range` |
+| `from` | `string` | `From` |
+| `to` | `string` | `To` |
+| `start` | `string` | `Start` |
+| `end` | `string` | `End` |
+| `fromOnly` | `(date: string) => string` | `From {date}` |
+| `toOnly` | `(date: string) => string` | `To {date}` |
+| `last2Weeks` | `string` | `Last 2 Weeks` |
+| `lastMonth` | `string` | `Last Month` |
+| `last3Months` | `string` | `Last 3 Months` |
+| `last6Months` | `string` | `Last 6 Months` |
+| `last12Months` | `string` | `Last 12 Months` |
+| `custom` | `string` | `Custom` |
+| `clear` | `string` | `Clear` |
+| `cancel` | `string` | `Cancel` |
+| `apply` | `string` | `Apply` |
+
+</details>
+
+<details><summary><code>pagination</code> — 5 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `label` | `string` | `Pagination` |
+| `first` | `string` | `First page` |
+| `previous` | `string` | `Previous page` |
+| `next` | `string` | `Next page` |
+| `last` | `string` | `Last page` |
+
+</details>
+
+<details><summary><code>list</code> — 8 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `selected` | `(count: number) => string` | `3 selected` |
+| `allLoaded` | `(total: number, label: string) => string` | `All 3 {label} loaded` |
+| `count` | `(total: number, label: string) => string` | `3 {label}` |
+| `loadedOf` | `(loaded: number, total: number, label: string) => string` | `3 of 3 {label}` |
+| `loadingMore` | `string` | `Loading more...` |
+| `loadError` | `string` | `Couldn't load this list` |
+| `loadErrorMessage` | `string` | `Something went wrong fetching these records. Check your connection and try again.` |
+| `retry` | `string` | `Try again` |
+
+</details>
+
+<details><summary><code>kanban</code> — 4 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `loading` | `string` | `Loading…` |
+| `empty` | `string` | `No items.` |
+| `dropHere` | `string` | `Drop here` |
+| `addItem` | `string` | `Add item` |
+
+</details>
+
+<details><summary><code>files</code> — 13 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `attach` | `string` | `Attach files` |
+| `drop` | `string` | `Drop files to attach` |
+| `remove` | `(name: string) => string` | `Remove {name}` |
+| `chooseMany` | `string` | `Choose files` |
+| `chooseOne` | `string` | `Choose a file` |
+| `dragMany` | `string` | `or drag them here` |
+| `dragOne` | `string` | `or drag it here` |
+| `notAccepted` | `(name: string, hint: string) => string` | `{name} is not an accepted file type ({hint})` |
+| `tooLarge` | `(name: string, size: string, limit: string) => string` | `{name} is {size} — the limit is {limit}` |
+| `tooMany` | `(name: string, max: number) => string` | `{name} was not added — 3 files is the limit` |
+| `bytes` | `(value: number) => string` | `3 B` |
+| `kilobytes` | `(value: number) => string` | `3 KB` |
+| `megabytes` | `(value: number) => string` | `3.0 MB` |
+
+</details>
+
+<details><summary><code>media</code> — 14 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `uploadImage` | `string` | `Upload an image` |
+| `uploadVideo` | `string` | `Upload a video` |
+| `uploadFile` | `string` | `Upload a file` |
+| `upload` | `string` | `Upload media` |
+| `cta` | `string` | `Choose from library or upload` |
+| `replace` | `string` | `Replace` |
+| `remove` | `string` | `Remove` |
+| `uploading` | `string` | `Uploading…` |
+| `cover` | `string` | `Cover` |
+| `add` | `string` | `Add` |
+| `addMedia` | `string` | `Add media` |
+| `empty` | `string` | `No media.` |
+| `removeItem` | `(name: string) => string` | `Remove {name}` |
+| `reorder` | `(name: string, position: number, total: number) => string` | `{name}, item 2 of 3. Use arrow keys to reorder.` |
+
+</details>
+
+<details><summary><code>brandAsset</code> — 10 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `save` | `(noun: string, assetName: string) => string` | `Save {noun}` |
+| `remove` | `(noun: string, assetName: string) => string` | `Remove {noun}` |
+| `discard` | `string` | `Discard change` |
+| `saveFailed` | `(noun: string, assetName: string) => string` | `Could not save {noun}.` |
+| `removeFailed` | `(noun: string, assetName: string) => string` | `Could not remove {noun}.` |
+| `region` | `(assetName: string, subjectName: string) => string` | `{assetName} for {subjectName}` |
+| `usedFor` | `(subjectName: string) => string` | `Used for {subjectName}.` |
+| `previews` | `(assetName: string) => string` | `{assetName} previews` |
+| `preview` | `string` | `Preview` |
+| `alt` | `(subjectName: string, assetName: string) => string` | `{subjectName} {assetName}` |
+
+</details>
+
+<details><summary><code>copy</code> — 5 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `copy` | `string` | `Copy` |
+| `copyLabel` | `(label: string) => string` | `Copy {label}` |
+| `copied` | `string` | `Copied` |
+| `copiedLabel` | `(label: string) => string` | `{label} copied` |
+| `failed` | `string` | `Could not copy to the clipboard` |
+
+</details>
+
+<details><summary><code>keypad</code> — 2 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `backspace` | `string` | `Backspace` |
+| `enter` | `string` | `Enter` |
+
+</details>
+
+<details><summary><code>banner</code> — 1 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `dismiss` | `string` | `Dismiss` |
+
+</details>
+
+<details><summary><code>badge</code> — 2 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `remove` | `string` | `Remove` |
+| `removeItem` | `(label: string) => string` | `Remove {label}` |
+
+</details>
+
+<details><summary><code>breadcrumbs</code> — 2 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `label` | `string` | `Breadcrumb` |
+| `hidden` | `string` | `Hidden crumbs` |
+
+</details>
+
+<details><summary><code>emptyState</code> — 1 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `message` | `string` | `Nothing here yet.` |
+
+</details>
+
+<details><summary><code>errors</code> — 9 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `notFound` | `string` | `Page not found` |
+| `notFoundBody` | `string` | `The page you're looking for doesn't exist or was moved.` |
+| `forbidden` | `string` | `Access denied` |
+| `forbiddenBody` | `string` | `You don't have permission to view this page.` |
+| `noAccess` | `string` | `You don't have access to this` |
+| `serverError` | `string` | `Something went wrong` |
+| `serverErrorBody` | `string` | `An unexpected error occurred. Please try again.` |
+| `retry` | `string` | `Try again` |
+| `details` | `string` | `Error details` |
+
+</details>
+
+<details><summary><code>search</code> — 10 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `placeholder` | `string` | `Search...` |
+| `escBadge` | `string` | `ESC` |
+| `searching` | `string` | `Searching...` |
+| `noResults` | `string` | `No results found.` |
+| `minChars` | `(min: number) => string` | `Type at least 3 characters to search...` |
+| `navigate` | `string` | `navigate` |
+| `open` | `string` | `open` |
+| `close` | `string` | `close` |
+| `enterKey` | `string` | `Enter` |
+| `escKey` | `string` | `Esc` |
+
+</details>
+
+<details><summary><code>grid</code> — 9 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `selectAll` | `string` | `Select all` |
+| `insertRowAbove` | `string` | `Insert row above` |
+| `insertRowBelow` | `string` | `Insert row below` |
+| `deleteRow` | `(row: number) => string` | `Delete row 4` |
+| `insertColumnLeft` | `string` | `Insert column left` |
+| `insertColumnRight` | `string` | `Insert column right` |
+| `deleteColumn` | `(column: string) => string` | `Delete column {column}` |
+| `resize` | `string` | `Drag to resize · double-click to auto-fit` |
+| `fill` | `string` | `Drag to fill` |
+
+</details>
+
+<details><summary><code>sidebar</code> — 1 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `resize` | `string` | `Drag to resize · double-click to reset` |
+
+</details>
+
+<details><summary><code>markdown</code> — 1 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `screenshot` | `string` | `Screenshot` |
+
+</details>
+
+<details><summary><code>severity</code> — 4 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `success` | `string` | `ok` |
+| `warning` | `string` | `warning` |
+| `danger` | `string` | `critical` |
+| `unrecognised` | `(token: string) => string` | `unrecognised severity {token}` |
+
+</details>
+
+<details><summary><code>meter</code> — 10 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `noData` | `string` | `no data` |
+| `warningAt` | `(bound: number) => string` | `warning ≥ 3` |
+| `criticalAt` | `(bound: number) => string` | `critical ≥ 3` |
+| `noReading` | `string` | `no reading` |
+| `noBudget` | `string` | `no budget` |
+| `ofBudget` | `(value: string) => string` | `{value} of budget` |
+| `budget` | `string` | `budget` |
+| `hoursMinutes` | `(hours: number, minutes: number) => string` | `3h 3m` |
+| `minutesSeconds` | `(minutes: number, seconds: number) => string` | `3m 3s` |
+| `seconds` | `(seconds: number) => string` | `3s` |
+
+</details>
+
+<details><summary><code>charts</code> — 81 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `showTable` | `string` | `Show the data as a table` |
+| `loading` | `string` | `Loading chart data` |
+| `noData` | `string` | `No data in this window.` |
+| `windowStart` | `string` | `Window start` |
+| `windowEnd` | `string` | `Window end` |
+| `window` | `(from: string, to: string, count: number) => string` | `Time window — showing {from} to {to} of 3 intervals` |
+| `overIntervals` | `(series: string[], count: number) => string` | `{series1}, {series2} over 3 intervals` |
+| `acrossCategories` | `(series: string[], count: number) => string` | `{series1}, {series2} across 3 categories` |
+| `acrossMeasures` | `(series: string[], count: number) => string` | `{series1}, {series2} across 3 measures` |
+| `breakdown` | `(total: string, segments: number) => string` | `Breakdown of {total} across 3 segments` |
+| `funnel` | `(stages: number, first: string, last: string) => string` | `Funnel of 3 stages, {first} down to {last}` |
+| `radialTrack` | `(count: number) => string` | `3 categories, as concentric proportions` |
+| `radialCycle` | `(count: number) => string` | `3 categories, around a cycle` |
+| `tableFrom` | `string` | `From` |
+| `tableTo` | `string` | `To` |
+| `tableItem` | `string` | `Item` |
+| `tableLevel` | `string` | `Level` |
+| `tableSeries` | `string` | `Series` |
+| `inBucket` | `(total: string) => string` | `{total} in this bucket` |
+| `inCategory` | `(total: string) => string` | `{total} in this category` |
+| `value` | `string` | `Value` |
+| `share` | `string` | `Share` |
+| `count` | `string` | `Count` |
+| `flow` | `string` | `Flow` |
+| `totalFlow` | `string` | `Total flow` |
+| `throughput` | `string` | `Throughput` |
+| `open` | `string` | `Open` |
+| `high` | `string` | `High` |
+| `low` | `string` | `Low` |
+| `close` | `string` | `Close` |
+| `maximum` | `string` | `Maximum` |
+| `q3` | `string` | `Q3` |
+| `median` | `string` | `Median` |
+| `q1` | `string` | `Q1` |
+| `minimum` | `string` | `Minimum` |
+| `distribution` | `string` | `Distribution` |
+| `fiveNumber` | `(label: string, count: number) => string` | `{label}: five-number summary for 3 categories` |
+| `outliers` | `(count: number) => string` | `3 outliers beyond the whiskers` |
+| `price` | `string` | `Price` |
+| `ohlc` | `(label: string, count: number) => string` | `{label}: open, high, low and close across 3 periods` |
+| `closedAbove` | `string` | `Closed above its open` |
+| `closedBelow` | `string` | `Closed below its open` |
+| `noFlows` | `string` | `No flows to chart.` |
+| `chord` | `(count: number) => string` | `Flows between 3 participants` |
+| `noStages` | `string` | `No stages to chart.` |
+| `ofFirstStage` | `string` | `Of first stage` |
+| `droppedHere` | `string` | `Dropped here` |
+| `intensity` | `string` | `Intensity` |
+| `noActivity` | `string` | `No activity in this window.` |
+| `heatmap` | `(label: string, rows: number, columns: number) => string` | `{label} across 4 rows and 3 columns` |
+| `countAxis` | `string` | `count` |
+| `histogram` | `(label: string, bins: number, observations: number) => string` | `{label}: 3 bins over 3 observations` |
+| `observations` | `string` | `Observations` |
+| `notEnough` | `string` | `Not enough eligible requests to judge.` |
+| `objectiveMet` | `(objective: string) => string` | `objective {objective} met` |
+| `objectiveMissed` | `(objective: string) => string` | `objective {objective} missed` |
+| `nothingToPlot` | `string` | `Nothing to plot.` |
+| `nothingToCompare` | `string` | `Nothing to compare.` |
+| `other` | `string` | `Other` |
+| `nothingToBreakDown` | `string` | `Nothing to break down.` |
+| `range` | `string` | `Range` |
+| `rangeLabel` | `(label: string, count: number) => string` | `{label}: low and high across 3 categories` |
+| `nothingToRank` | `string` | `Nothing to rank in this window.` |
+| `emphasised` | `string` | `(emphasised)` |
+| `sankey` | `(nodes: number, links: number) => string` | `Flow between 3 nodes over 3 links` |
+| `noObservations` | `string` | `No observations in this window.` |
+| `xAxis` | `string` | `x` |
+| `yAxis` | `string` | `y` |
+| `size` | `string` | `Size` |
+| `scatter` | `(series: string[], yLabel: string, xLabel: string) => string` | `{series1}, {series2}: {yLabel} against {xLabel}` |
+| `outsideRange` | `(count: number) => string` | `3 points outside the shown range` |
+| `waterfall` | `(steps: number, from: string, to: string) => string` | `Waterfall of 3 steps from {from} to {to}` |
+| `balance` | `string` | `Balance` |
+| `increase` | `string` | `Increase` |
+| `decrease` | `string` | `Decrease` |
+| `runningTotal` | `string` | `Running total` |
+| `sunburst` | `(total: string, depth: number) => string` | `Hierarchy of {total} across 3 levels` |
+| `treemap` | `(count: number) => string` | `Treemap of 3 items` |
+| `trendUp` | `string` | `up` |
+| `trendDown` | `string` | `down` |
+| `trendFlat` | `string` | `flat` |
+
+</details>
+
+<details><summary><code>timeline</code> — 17 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `days` | `(count: number) => string` | `3 days` |
+| `daysToToday` | `(count: number) => string` | `3 days to today` |
+| `notReached` | `string` | `Not yet reached` |
+| `next` | `string` | `Next` |
+| `more` | `(count: number) => string` | `+3 more` |
+| `today` | `string` | `Today` |
+| `todayTitle` | `(date: string) => string` | `Today — {date}` |
+| `open` | `(name: string) => string` | `Open {name}` |
+| `openButton` | `string` | `Open` |
+| `scrub` | `string` | `Scrub the timeline` |
+| `alsoToCome` | `(names: string[]) => string` | `Also to come: {names1}, {names2}` |
+| `start` | `(date: string) => string` | `Start · {date}` |
+| `events` | `(count: number, names: string[]) => string` | `3 events · {names1}, {names2}` |
+| `started` | `(date: string) => string` | `started {date}` |
+| `duration` | `(days: number) => string` | `3 days` |
+| `reached` | `(dated: number, total: number) => string` | `3 of 3 milestones` |
+| `milestones` | `(title: string) => string` | `{title} milestones` |
+
+</details>
+
+<details><summary><code>production</code> — 20 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `heading` | `string` | `Production progress` |
+| `start` | `string` | `Start` |
+| `estimated` | `string` | `Estimated` |
+| `estimatedCompletion` | `string` | `Estimated completion` |
+| `estDone` | `string` | `Est. done` |
+| `play` | `string` | `Play` |
+| `pause` | `string` | `Pause` |
+| `playTitle` | `string` | `Play the timeline, report by report` |
+| `backTo` | `(report: string) => string` | `Back to {report}` |
+| `showing` | `(report: string) => string` | `Showing {report}` |
+| `overall` | `(percent: number) => string` | `3% overall` |
+| `inStock` | `(pieces: number) => string` | `3 pc in stock` |
+| `noReport` | `string` | `No production report filed yet` |
+| `leadTime` | `(days: number) => string` | `3 days lead time` |
+| `report` | `string` | `Production report` |
+| `shipment` | `string` | `Shipment` |
+| `inspection` | `string` | `Inspection` |
+| `invoice` | `string` | `Invoice` |
+| `scrub` | `string` | `Scrub the production timeline` |
+| `label` | `(from: string, to: string) => string` | `Production reports and events, {from} to {to}` |
+
+</details>
+
+<details><summary><code>containers</code> — 10 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `items` | `(count: number) => string` | `3 items` |
+| `pieces` | `(count: number) => string` | `3 pcs` |
+| `split` | `(instructed: number, loaded: number) => string` | `(3 instr / 3 loaded)` |
+| `added` | `(count: number, pieces: number) => string` | `3 new (3 pcs)` |
+| `fill` | `(volume: number, capacity: number) => string` | `3.0 / 3 m³` |
+| `total` | `string` | `Total:` |
+| `instructed` | `(volume: number) => string` | `3.00 m³ instruction` |
+| `loaded` | `(volume: number) => string` | `3.00 m³ loaded` |
+| `volume` | `(volume: number) => string` | `3.00 m³` |
+| `noVolume` | `string` | `Volume: N/A (no volume data for these part numbers)` |
+
+</details>
+
+<details><summary><code>toast</code> — 1 keys</summary>
+
+| Key | Type | English default |
+|---|---|---|
+| `notification` | `string` | `Notification` |
+
+</details>
+
 ### Brand surfaces — `efficient-shell/brand.css`
 
 For output that is not a portal window — a report, a published artifact, a
@@ -753,7 +1674,7 @@ copying both from `node_modules/maplibre-gl/dist`). Tiles come from
 
 | Export | Notes |
 |---|---|
-| `EntityMap` | The map. `pins` (`MapPin`: glyph or `icon` paths, `badge`, `tone` classes, `approximate`, `faded`), `selectedKey` + `onSelect`, `focus` to fly to a pin, `routes` (`MapRoute`, dashed when an estimate), `fitTo`, `attribution`. Follows `data-theme="dark"` on `<html>`; resizes with its box (a shell window sends no window resize). Without WebGL it says so and its children still draw. |
+| `EntityMap` | The map. `pins` (`MapPin`: glyph or `icon` paths, `badge`, `tone` classes, `approximate`, `faded`), `selectedKey` + `onSelect`, `focus` to fly to a pin, `routes` (`MapRoute`, dashed when an estimate), `fitTo`, `attribution`. Follows `data-theme="dark"` or a `dark` class on `<html>`; resizes with its box (a shell window sends no window resize). Without WebGL it says so and its children still draw. |
 | `LocationsMap` | A record's compact map over an endpoint: legend, "Locating N addresses…", a note per record with no pin, the chosen pin's card. `palette` names the categories the portal's way; `numbers` gives each pin the number the page's own list shows. |
 | `MapLegend`, `SelectedCard` | The overlays, for a map that lays out its own list (the admin portal's list-wide Map view). |
 | `useMapPoints(queryKey, queryFn)` | react-query, re-asked every few seconds while `pending > 0`; `mapPointsRefetchInterval` is the same rule for a hand-written query. |
@@ -769,7 +1690,7 @@ copying both from `node_modules/maplibre-gl/dist`). Tiles come from
 | `isPageEntry`, `isEntityEntry` | Type guards for `WindowRegistryEntry`. |
 | `glassStyle()` | Returns the theme-aware frosted-glass `style` object. |
 | `reportBug(submit)` | Captures a screenshot via `getDisplayMedia`, opens the dialog, hands the payload to your `submit`. |
-| `formatDate(iso)` | Locale-aware date formatter. |
+| `formatDate(iso, { locale?, style? })` | A `YYYY-MM-DD` (or the date part of a timestamp) in the user's stored date format — or, given a `locale`, written by `Intl` in it (`style` defaults to `{ dateStyle: 'medium' }`). Returns `—` for nothing. |
 | `installStaleChunkReload(options?)` | Call once before the app mounts. A deploy replaces every lazy chunk; a tab opened before it crashes on the first lazy window it opens ("Failed to fetch dynamically imported module", or a `ChunkLoadError`) and no remount can fix it. This reloads the page instead — once per 30 s cooldown, kept in `sessionStorage`, so a chunk still missing after the reload (a broken deploy) crashes visibly instead of looping. It hears Vite's `vite:preloadError` (whose throw it swallows) and, for Next.js (Turbopack) and webpack, a chunk under `chunkPathPrefix` (default `NEXT_CHUNK_PATH_PREFIX`, `/_next/static/`; a path from this origin or a full URL for a CDN `assetPrefix`; `null` for Vite only) that fails as a `<script>`, a stylesheet or a script/style/module preload — or that came back as HTML and threw a `SyntaxError`, which is how a missing chunk surfaces without `X-Content-Type-Options: nosniff`. Prefetches, fonts and images are ignored. Before a chunk reload it asks the server (`HEAD`, `no-store`) whether the file is really gone — a 404/410, or the SPA fallback's HTML — so a dropped connection is left to the loader's own retry and an offline tab is never reloaded onto the browser's error page. Both signals share one cooldown. Returns the uninstaller. |
 | `isStaleChunkError(error)` | True for the three engines' "module the server did not return" messages, Vite's CSS-preload line, and any Error named `ChunkLoadError` (Turbopack, webpack) — what `WindowCrashedFallback` uses to offer "Reload page" instead of "Reload window". |
 | `budgetState(elapsed, budget)` | `no-reading` \| `no-budget` \| `within` \| `over` — the verdict `BudgetBar` draws by, exported so a run list sorts and filters by the same rule rather than re-deriving "late" a second time. |