@ultimat3/ui 22.15.0 → 24.0.0

package/CATALOG.md

@@ -103,13 +103,14 @@ Small status label. Tone maps straight onto the status colour roles so the same
 
 ### BarChart
 
-A bar chart of one series — clicks per day, signups per week — as static SVG. No charting library: the framework's own docs use a sparkline pulling one in as the cautionary example, and a route's JS budget counts raw minified bytes. `<rect>` bars cost nothing to hydrate, so the server-rendered shell IS the chart. Geometry lives in `bar-chart-view.ts`.
+A bar chart of one series — clicks per day, signups per week — or two stacked (done, and failed on top), as static SVG. No charting library: the framework's own docs use a sparkline pulling one in as the cautionary example, and a route's JS budget counts raw minified bytes. `<rect>` bars cost nothing to hydrate, so the server-rendered shell IS the chart. Geometry lives in `bar-chart-view.ts`.
 
 | Prop | Type | Required | Notes |
 |---|---|---|---|
 | `label` | `string` | yes | The accessible name for the whole chart, already translated. |
 | `points` | `readonly ChartPoint[]` | yes | Oldest first. Every bar comes from exactly this array — the caller zero-fills gaps. |
 | `highlightLast` | `boolean` | — | Draw the last bar at full strength — the eye lands where the live number is. Default on. |
+| `seriesLabels` | `{ readonly primary: string; readonly secondary: string }` | — | Names of the two series, already translated, read by each rect's `<title>`. Give them when a point carries `secondary`: a stacked bar with no name for its top is two numbers and no key. |
 | `class` | `string` | — |  |
 
 ### Breadcrumb
@@ -170,6 +171,7 @@ Native checkbox with a token-drawn indicator. The label element wraps the input,
 | `id` | `string` | — |  |
 | `name` | `string` | — |  |
 | `value` | `string` | — |  |
+| `form` | `string` | — | The id of the `<form>` this box submits with, when it cannot sit inside it — a row checkbox in a table whose page already holds another form. The platform's own association, no script. |
 | `checked` | `boolean` | — |  |
 | `indeterminate` | `boolean` | — | Tri-state for "some children selected". The ONLY thing mirrored to `aria-checked`. |
 | `disabled` | `boolean` | — |  |
@@ -258,7 +260,6 @@ Data-driven table: sortable headers, cursor pagination, and the four states a re
 | `rows` | `readonly Row[]` | yes |  |
 | `rowKey` | `(row: Row) => string` | yes |  |
 | `sort` | `SortState` | — |  |
-| `onSortChange` | `(sort: SortState \| undefined) => void` | — |  |
 | `loading` | `boolean` | — |  |
 | `error` | `unknown` | — | An UltimateError (or anything shaped like one) from the query. |
 | `onRetry` | `(() => void)` | — |  |
@@ -266,11 +267,14 @@ Data-driven table: sortable headers, cursor pagination, and the four states a re
 | `emptyDescription` | `string` | — |  |
 | `nextCursor` | `string` | — | Opaque cursors from the query result; absent means no further page. |
 | `prevCursor` | `string` | — |  |
-| `onCursor` | `((cursor: string, direction: 'next' \| 'prev') => void)` | — |  |
 | `stickyHeader` | `boolean` | — |  |
 | `density` | `'comfortable' \| 'compact'` | — |  |
 | `skeletonRows` | `number` | — | Placeholder row count while loading. Match the usual page size. |
 | `class` | `string` | — |  |
+| `onCursor` | `((cursor: string, direction: 'next' \| 'prev') => void)` | — | Callback paging. Never beside `hrefFor` — the type refuses the pair. |
+| `onSortChange` | `((sort: SortState \| undefined) => void)` | — | Callback sorting. Never beside `sortHrefFor` — the type refuses the pair. |
+| `hrefFor` | `(cursor: string, direction: 'next' \| 'prev') => string` | — | Link paging: the URL of the page a cursor names, handed to `<Pagination hrefFor>`. |
+| `sortHrefFor` | `((sort: SortState \| undefined) => string)` | — | Link sorting: the URL of the list under the NEXT sort state of a header's cycle (`undefined` is "unsorted"). Absent, a sortable header is plain text — never a button with no handler. |
 
 ### DateTime
 
@@ -546,7 +550,7 @@ A keyboard key or chord as the user reads it — "⌘K", "Esc", "/". A native `<
 
 ### Link
 
-Anchor primitive. External links get `rel` hardening and a translated "opens in a new tab" hint automatically — never a bare `target="_blank"`.
+Anchor primitive. External links get `rel` hardening and a translated "opens in a new tab" hint automatically — never a bare `target="_blank"`. `appearance="button"` is Button's look on the same anchor: a control that navigates is a link.
 
 | Prop | Type | Required | Notes |
 |---|---|---|---|
@@ -554,12 +558,19 @@ Anchor primitive. External links get `rel` hardening and a translated "opens in
 | `children` | `JSX.Element` | yes |  |
 | `external` | `boolean` | — |  |
 | `externalHint` | `string` | — | Announced suffix for external links; supply via `t()` at the call site. |
-| `underline` | `'always' \| 'hover' \| 'none'` | — |  |
-| `tone` | `'accent' \| 'inherit'` | — |  |
+| `rel` | `'next' \| 'prev'` | — | A pager's direction. Joins the hardening an external link always carries, never replaces it. |
 | `id` | `string` | — |  |
 | `class` | `string` | — |  |
 | `aria-current` | `'page' \| 'step' \| 'true' \| false` | — |  |
 | `onClick` | `JSX.EventHandlerUnion<HTMLAnchorElement, MouseEvent>` | — |  |
+| `appearance` | `'link' \| 'button'` | — | `button` wears Button's classes on the same `<a>`; the two looks take different props. |
+| `underline` | `'always' \| 'hover' \| 'none'` | — |  |
+| `tone` | `'accent' \| 'inherit' \| Tone` | — | A text link: `accent` or `inherit`. A button-link: any `Tone`. |
+| `variant` | `ButtonVariant` | — | `appearance="button"` only. |
+| `size` | `Size` | — | `appearance="button"` only. |
+| `fullWidth` | `boolean` | — | `appearance="button"` only. |
+| `iconStart` | `JSX.Element` | — | `appearance="button"` only. |
+| `iconEnd` | `JSX.Element` | — | `appearance="button"` only. |
 
 ### LocaleSwitcher
 
@@ -631,29 +642,30 @@ The top of a screen: breadcrumbs, the page's one heading, a description, and the
 
 ### Pagination
 
-Cursor-first pagination — the only shape a Postgres-backed list should use. Numbered mode exists for prerendered archives where the total is known.
+Cursor-first pagination — the only shape a Postgres-backed list should use. Numbered mode exists for prerendered archives where the total is known. One mode per use: callbacks (`onCursor` / `onPage`) for an island, or `hrefFor` for a server-rendered list — anchors the browser follows, with no script on the page.
 
 | Prop | Type | Required | Notes |
 |---|---|---|---|
 | `nextCursor` | `string` | — | Opaque cursor for the following page; absent disables "next". |
 | `prevCursor` | `string` | — |  |
-| `onCursor` | `((cursor: string, direction: 'next' \| 'prev') => void)` | — |  |
-| `page` | `number` | — | Numbered mode: 1-based page and total. Ignored when cursors are present. |
-| `totalPages` | `number` | — |  |
-| `onPage` | `((page: number) => void)` | — |  |
 | `labelPrevious` | `string` | — | Already-translated; falls back to the ui.* catalog keys. |
 | `labelNext` | `string` | — |  |
 | `class` | `string` | — |  |
+| `onCursor` | `((cursor: string, direction: 'next' \| 'prev') => void)` | — | Callback mode. Never beside `hrefFor` — the type refuses the pair. |
+| `page` | `number` | — | Numbered mode: 1-based page and total. Ignored when cursors are present. |
+| `totalPages` | `number` | — |  |
+| `onPage` | `((page: number) => void)` | — |  |
+| `hrefFor` | `(cursor: string, direction: 'next' \| 'prev') => string` | — | Link mode: the URL of the page a cursor names. Renders `<a rel="next\|prev">` and attaches no handler, so it needs no island. Cursor paging only — never beside `onCursor`, `onPage`, `page` or `totalPages`. |
 
 ### Popover
 
-Non-modal anchored panel. Positioning is CSS-only (a relatively positioned anchor plus logical insets), so there is no measure/reflow loop and the panel flips sides automatically under `dir="rtl"`.
+Non-modal anchored panel. Positioning is CSS-only (a relatively positioned anchor plus logical insets and auto-margin centring), so there is no measure/reflow loop and the panel mirrors under `dir="rtl"` — `rtl-sheets.test.ts` holds that.
 
 | Prop | Type | Required | Notes |
 |---|---|---|---|
 | `open` | `boolean` | yes |  |
 | `onOpenChange` | `(open: boolean) => void` | yes |  |
-| `trigger` | `(control: { id: string; 'aria-expanded': boolean; 'aria-controls': string; }) => JSX.Element` | yes | The anchor. Wire its onClick to `onOpenChange` in the caller. |
+| `trigger` | `(control: { id: string; 'aria-expanded': boolean; 'aria-controls': string \| undefined; }) => JSX.Element` | yes | The anchor. Wire its onClick to `onOpenChange` in the caller. `aria-controls` is present only while the panel is mounted: an IDREF to an element not in the document names nothing. |
 | `children` | `JSX.Element` | yes |  |
 | `label` | `string` | yes | Already-translated accessible name for the panel. |
 | `placement` | `Placement` | — |  |
@@ -1014,6 +1026,14 @@ charts and email.
 | `pill` | `999px` |
 | `full` | `50%` |
 
+### Stroke — `--stroke-*`
+
+| Token | Value |
+|---|---|
+| `hairline` | `1px` |
+| `thick` | `2px` |
+| `heavy` | `3px` |
+
 ### Font size — `--text-*`
 
 | Token | Value |
@@ -1078,7 +1098,7 @@ charts and email.
 | `toast` | `700` |
 | `skip-nav` | `800` |
 
-### Breakpoints — `@include t.respond-to(<name>)`
+### Breakpoints — `respond-to` · `respond-down` · `respond-between`
 
 | Token | Value |
 |---|---|
@@ -1087,3 +1107,14 @@ charts and email.
 | `lg` | `1024px` |
 | `xl` | `1280px` |
 | `2xl` | `1536px` |
+
+`@include t.respond-to(md)` is `md` and wider, `t.respond-down(md)` is narrower than `md`, and
+`t.respond-between(md, lg)` is `md` up to `lg`. A max-width arm stops 0.02px under its rung, so
+no width matches two of them.
+
+### Computed lengths
+
+| Function | Answers |
+|---|---|
+| `t.rem(24px)` | `1.5rem` — px, rem or a unitless px count in, rem out |
+| `t.fluid(1rem, 2rem, 20rem, 80rem)` | one `clamp()`: the first size at a 20rem viewport, the second at 80rem, linear between |

package/CLAUDE.md

@@ -12,76 +12,38 @@ Tier 4. Imports `@ultimat3/core`, `i18n`, `money`, `time` — **not `schema`**,
 
 - **SCSS modules only.** `Foo.tsx` + `Foo.module.scss`, always paired. No Tailwind, no CSS-in-JS, no inline `style` except CSS custom properties.
 - **No raw colours.** Only `t.role('<role>')` / `var(--color-*)`. Canonical roles live in `src/tokens/_colors.scss`; `tokens.ts` mirrors them and `tokens.test.ts` fails on drift.
+- **No raw length, breakpoint, z-index, shadow or duration** in any sheet here: `t.space()` / `t.stroke()` / `t.rem()`, `respond-*`, `t.z()`, `t.shadow()`, `t.duration()`. Held by `packages/cli/src/templates/scaffold-guards-style.test.ts`, which runs the guards `x new` ships over this package.
 - **Logical properties only.** `margin-inline`, `inset-inline-start`, `text-align: start`. A `left`/`right` in a stylesheet is a bug.
 - **solid-js is a type-only import.** All reactive access goes through `src/theme/solid-adapter.ts`. Never `import { createSignal } from 'solid-js'`.
 - **The runtime SLOT is `src/theme/runtime-slot.ts`; the RULE is `solid-adapter.ts`, and the split is a byte measurement.** `solid-adapter.ts` reaches `../errors` and so core's error registry; the slot imports nothing, so an island that only calls `setSolidRuntime` pays 72 B, not 5,719. `barrel-bytes.test.ts` holds the ceiling at 1 kB.
 - **The barrel is the ONE import path; component subpath exports are refused on measurement** (issue #275). A barrel import and a deep path emit the same modules and bytes, so `@ultimat3/ui/button` would be a second idiom for zero bytes. The two subpaths that exist are not exceptions: `./icons/*` is 1,767 data modules no bundler can split, and `./jsx-probe` is test-only. `barrel-bytes.test.ts` compares the two paths and names `schema-error-codes.ts` (Bun 1.4.0's load-correlated shake, issues #273 #276) rather than allowing bytes for it.
-- **`useUi()`'s server branch is a SLOT, and the module that fills it is browser-mapped** (issue #490). `context.ts` imports no value from `@ultimat3/i18n` or `@ultimat3/time` (the i18n barrel installs the framework catalog at import: 16.1 kB per island). `src/theme/ambient.ts` registers `ambientUiContext` into `ambient-slot.ts` at import; `index.ts` imports it BARE above every re-export, and `package.json`'s `browser` field maps it to `ambient.browser.ts` (bundlers only — `bun test` and SSR get the server's). A test reaching components by module path must `import './ambient'` itself, as `inert-render.test.ts` does. `fallbackTranslator` is held member-for-member against `createTranslator({})` by `context.test.ts`. `errors.ts` is pure: `registerErrorCodes()` is `src/error-registry.ts`, imported bare. `barrel-bytes.test.ts` pins the theme island's retained-module list.
+- **`useUi()`'s server branch is a SLOT, and the module that fills it is browser-mapped** (issue #490). `context.ts` imports no value from `@ultimat3/i18n` or `@ultimat3/time`. `src/theme/ambient.ts` registers into `ambient-slot.ts` at import; `index.ts` imports it BARE above every re-export; `package.json`'s `browser` field maps it to `ambient.browser.ts`. A test reaching components by module path must `import './ambient'` itself. `errors.ts` is pure: `registerErrorCodes()` is `src/error-registry.ts`, imported bare.
 - **`solid()` always answers off-DOM.** No registered runtime and no DOM is a *server render*, and it gets `INERT_SOLID_RUNTIME` (`src/theme/inert-runtime.ts`) — signals hold, memos recompute on read, effects never run, `useContext` returns the default. No DOM means no reactivity to lose; a **DOM** with no runtime is still `X_UI_RUNTIME_MISSING`, because that one is the theme toggle that does nothing. Never widen this to "no runtime, never throw": that is the silent degradation the split exists to prevent.
 - **`useUi()` reads the request on the server**, via `ambientUiContext()` — `currentLocale()`, `currentTimeZone()`, `useI18n()`, which read **core's own `Ctx.locale` / `Ctx.tz`** (written once per request by `@ultimat3/http`'s `locale` stage). Never add a second ambient store here or in `i18n`/`time`. `theme`/`currency` have no ambient source at all.
 - **Every locale-sensitive call takes the locale as an ARGUMENT, `toLocaleUpperCase` included.** `initialsOf(name, locale)` reads `useUi().locale`; a bare `toLocaleUpperCase()` reads the runtime's default (Turkish dotted `i` → `İ`).
 - **`UiProvider` is client-only and throws on the server** (`providerNeedsRuntimeError`, the same `X_UI_RUNTIME_MISSING`). A Provider in an inert tree reaches no descendant — the tree is built before the renderer walks it, so consumers are walked outside every owner and read the context default even with a real Solid runtime registered. Rendering the children anyway would drop its locale, zone, currency and translator silently. Making it work needs the *renderer* to scope a context around the walk; until then it refuses.
 - **A component may call `solid()` freely.** Its effects must stay DOM-only work — they simply never run on the server.
 - **No `{...rest}` prop spreading.** Splitting props reactively needs solid's `splitProps` (a value import), so components declare explicit props and read `props.x` inside JSX.
+- **One mode per use is a UNION of interfaces** (`LinkProps`, `PaginationProps`, `DataTableProps` — where the mode covers the pager AND the sort headers: `hrefFor` + `sortHrefFor`, or `onCursor` + `onSortChange`; a linked table never renders a button with no handler): a mode forbids the other's props with `x?: undefined`, and `catalog/parse-component.ts` merges the modes.
 - **No hardcoded strings.** Label props, or `useUi().t(UI_KEYS.x)`. New built-in strings go in `src/i18n-keys.ts`.
 - **Page layout is four composites**: `AppShell` (frame + skip link + landmarks), `PageHeader`, `Section`, `Toolbar`. A screen that hand-rolls a header grid is the bug they exist to prevent. `AppShell` holds no state — off-canvas is `Drawer`.
 - **Restyling goes through `defineTheme()`**, never a forked stylesheet and never an SCSS `with ()` override. Its values are validated, not escaped: the output lands in a `<style>` element.
 - **`@include t.tone-classes`** emits the `.tone-*` custom-property blocks. Never hand-write a seventh copy; `$tones` in `_colors.scss` mirrors `TONES` and `variants.test.ts` gates it.
 - **Icons are generated, never authored.** `src/icons/glyphs/*.ts` is one module per Lucide icon, written by `bun run icons` from `lucide-static@LUCIDE_VERSION`. Never hand-edit a glyph, never add a hand-drawn one, never introduce a second icon source. An upstream fix is a version bump plus a re-run. `lucide` itself is NOT a dependency — the data is committed, so the package still installs, typechecks and renders offline with zero runtime deps.
 - **One icon, one module.** The `Icon` component takes a `glyph`, not a name: a `name → glyph` map would be one module holding 1767 icons, and no bundler can split that. Per-icon imports are the whole point (1 icon = 104 B minified, 50 = 8.9 kB).
-- **No client runtime exists yet.** A new interactive component must be correct server-rendered and usable with scripting off — `<details>` for disclosure, `<input list>`+`<datalist>` for suggestions, a real `rel="next"` link for paging — with listeners and observers as additive extras. A component that renders nothing until JS runs does not ship.
+- **Server-rendered first, an island second.** Components run in islands (`examples/dummy`'s settings and feed islands render them), but every one must still be correct server-rendered and usable with scripting off — `<details>` for disclosure, `<input list>`+`<datalist>` for suggestions, a real `rel="next"` link for paging — with listeners and observers as additive extras. A component that renders nothing until JS runs does not ship. In an island the body runs ONCE: a branch decided there (an early `return <ErrorState>`) is decided for the island's life, so branches live inside the returned JSX (`AsyncRegion`, `DataTable`). A server-only spelling is gated on `typeof document` (`Textarea`'s parser newline). Ids minted in an island carry a per-copy scope (`a11y.ts`), because each island bundles its own counter.
 - **`inert-render.test.ts` must not assume which factory its `.tsx` compiled to.** `@ultimat3/render` installs a process-global `.tsx` `onLoad` plugin at import, so in one `bun test` process a component may compile to render's `h`. The walker recognises both (`Symbol.for('ultimate.render.jsx')`), and the first test asserts a recognised node — otherwise the file renders `"[object Object]"` and passes by shard packing.
 - **Components are not unit-tested through a renderer.** `.tsx` compiles to `@ultimat3/render`'s `h`, which this package may not import, so every rule lives in a pure module beside the component (`icon-glyph.ts`, `accordion-view.ts`, `combobox-filter.ts`, `infinite-scroll-view.ts`) and *that* is what the tests assert.
 - Formatting logic lives in a pure `*-view.ts` next to the component (`money-view.ts`, `date-time-view.ts`) so it is testable with no renderer. Every other renderer-free core follows the same rule under its own name (`sort-state.ts`, `image-source.ts`) — the `.tsx` holds markup, never a rule.
-- **The rule being pure is not enough — the WIRING has to be tested too.** `createRovingTabindex` was correct and `Menu` handed it `[role="menuitem"]`, so a disabled item made every item after it unreachable and every assertion in the package still passed. `src/jsx-probe.ts` reads the props an element actually carries (a `tabindex`, an `aria-live`, an `onKeyDown`, a `ref`) and `src/fake-dom.ts` gives it a DOM where a disabled control REFUSES focus, exactly as the real one does. Both are test-only and neither is in `index.ts`. `jsx-probe`'s `probe`/`unprobe` are the one exception, reachable at the subpath `@ultimat3/ui/jsx-probe` and still absent from the barrel: `globalThis.React` is ONE property, so its install/restore counter has to be ONE counter — `@ultimat3/admin` (tier 5) kept a second pair, and interleaved installs restored the two harnesses in the wrong order, leaving the global holding a harness the run had already torn down. `components/interaction.test.ts` is where a keyboard or form-participation claim gets proven; asserting the pure helper alone is how these shipped.
+- **The rule being pure is not enough — the WIRING is tested too.** `src/jsx-probe.ts` reads the props an element carries and `src/fake-dom.ts` is a DOM where a disabled control refuses focus; both TEST-ONLY, neither in `index.ts`. `probe`/`unprobe` are the framework's ONE owner of `globalThis.React`, reachable at `@ultimat3/ui/jsx-probe` (admin imports them). A keyboard or form-participation claim is proven in `components/interaction.test.ts`.
 - **A roving group excludes disabled items from both answers** — the set arrows walk and the one item holding the tab stop (`src/roving.ts`). `focus()` on a disabled control is a no-op, so a disabled item left in the list pins the reducer on its index forever. And a control that answers arrows itself (`handlesOwnArrowKeys`) keeps them: a `Toolbar` exists to hold a search field.
 - **A single-winner state attribute is decided by POSITION, never by a missing prop.** `Breadcrumb` gives `aria-current="page"` to the last item and to nothing else; an href-less ancestor renders as plain text with no `aria-current` at all. Reading "no href" as "is the current page" put two of them in one `<nav>`. `Tabs.tsx` is the same rule for `tabindex`, and `Breadcrumb.test.ts` proves it through `jsx-probe` rather than through the pure helper.
-- **One async region, four branches, and `empty` is unreachable while `pending`.** `asyncBranch`
-  (`src/components/async-branch.ts`) is the ONLY place the `(pending, failed, empty, data)` decision
-  is made — `AsyncRegion` renders it and `DataTable` calls it, so a table and a card list cannot
-  disagree about what "loading with stale rows" looks like. The property is structural: an
-  `AsyncState` (declared in `@ultimat3/core` since 21.0.0 — imported here, never re-exported, so
-  it has one import path) in `pending` carries no data, so nothing can be found empty in it, and "No results"
-  for one frame before the first page arrives is unconstructible rather than discouraged.
-  `<AsyncRegion>`'s `empty` and `ready` are REQUIRED props, so forgetting the empty state is a type
-  error. `refreshing` CARRIES the previous data — a refetch dims what is on screen (`aria-busy`) and
-  never tears it down, which is what makes a search box feel fast; the empty branch is reachable
-  only from a completed result that returned zero. `reserve` feeds the placeholder AND the
-  `min-block-size` of every branch, so the skeleton and the loaded content cannot be written into
-  different boxes.
-- **A toast dwell stops for THREE independent reasons, and one of them is `document.hidden`.**
-  Hover and focus-within are the two everybody implements; a backgrounded tab spends the whole dwell
-  and the corner is empty when the user comes back. `ToastHold` is a set, never a boolean: a pointer
-  leaving a toast a keyboard user is still inside must not restart the countdown, which one flag
-  cannot express. Duration is a TOKEN (`TOAST_DWELL_MS`), never a per-call number of milliseconds.
-  The queue's rules are pure (`src/toast/toast-state.ts`) and the clock is injected (`ToastEnv`), so
-  a server render gets `INERT_TOAST_ENV` — nothing scheduled — and `ToastRegion` still emits its
-  empty live region, which is what the document has to carry BEFORE the first message.
-- **`announce()` writes into a region `AppShell` already rendered.** A live region created and
-  filled in the same frame is not announced by most screen readers, so `announce()`'s own
-  create-if-absent branch could only ever be right from its second call. `liveRegionAttrs` is the
-  one derivation both halves read. It is for a state change with no surface of its own ("12
-  results", "sorted by name"); a notification is a `Toast`, and two announcement paths for one
-  message is how a screen reader reads it twice.
-- **`loading` never sets the native `disabled` attribute** (`Button`), and that WILL read as a
-  mistake. A control that disables itself mid-flow drops focus to `<body>`, is exempt from the
-  contrast minimum, announces no reason, and still does not prevent the double submit — that race is
-  on the server. `aria-disabled` + a refused click keeps it focusable and readable; `Button.module.scss`
-  restores full opacity under `[aria-busy='true']` because `t.disabled` dims to 0.55. `<Form busy>`
-  refuses the submit again, because Enter in a text field touches no button at all.
-- **A failed submit focuses the first invalid CONTROL, and the summary only when there is none.**
-  GOV.UK's summary-with-links shape is not available here: `Field` mints its control ids internally,
-  and inverting that ownership is the drift `Field` exists to prevent. `firstInvalidField` answers in
-  DECLARATION order, never issue order — a server may report the last field first. `fieldSelector`
-  is the allowlist between a caller's string and a selector; a name the grammar refuses reaches no
-  `querySelector`.
-- **`defineTheme()` refuses a palette that fails WCAG 2.2 AA** (`X_UI_CONTRAST_INSUFFICIENT`),
-  measured against `CONTRAST_PAIRS` — the same table `contrast.test.ts` holds the shipped palette to,
-  in SOURCE rather than in a test, so an app cannot ship a brand the design system would have failed
-  its own suite over. Only pairings the brand can have CHANGED are measured, on the resolved palette
-  (shipped channels + overrides): a new `accent` against the shipped `accent-fg` is the commonest way
-  a brand goes unreadable. AA, never APCA — APCA is not a standard, and AA is the operative legal
-  benchmark.
+- **One async region, four branches, and `empty` is unreachable while `pending`.** `asyncBranch` (`src/components/async-branch.ts`) is the ONLY place the decision is made — `AsyncRegion` renders it, `DataTable` calls it. `AsyncState` is core's (imported, never re-exported). `empty` and `ready` are REQUIRED props; `refreshing` carries the previous data and dims it (`aria-busy`), never tears it down; `reserve` feeds the placeholder AND every branch's `min-block-size`.
+- **A toast dwell stops for THREE independent reasons** — hover, focus-within, `document.hidden` — so `ToastHold` is a set, never a boolean. Duration is a TOKEN (`TOAST_DWELL_MS`). Rules are pure (`src/toast/toast-state.ts`), the clock injected (`ToastEnv`); a server render gets `INERT_TOAST_ENV` and `ToastRegion` still emits its empty live region.
+- **`announce()` writes into a region `AppShell` already rendered** (`liveRegionAttrs` is the one derivation). For a state change with no surface of its own; a notification is a `Toast` — never both for one message.
+- **`loading` never sets the native `disabled` attribute** (`Button`): `aria-disabled` + a refused click keeps it focusable and readable; `Button.module.scss` restores full opacity under `[aria-busy='true']`. `<Form busy>` refuses the submit again.
+- **A failed submit focuses the first invalid CONTROL, and the summary only when there is none.** `firstInvalidField` answers in DECLARATION order; `fieldSelector` is the allowlist between a caller's string and a selector.
+- **`defineTheme()` refuses a palette that fails WCAG 2.2 AA** (`X_UI_CONTRAST_INSUFFICIENT`), measured against `CONTRAST_PAIRS` on the RESOLVED palette, only for pairings the brand changed. AA, never APCA.
 - **Live semantics belong to the container that outlives the message.** `ToastRegion`'s `<ol>` carries `aria-live`; a `Toast` is a plain `<li>`. A region created with its content already inside it is not announced, and a `role="status"` on the `<li>` also strips its `listitem` semantics.
 - **`aria-checked` never mirrors a native `checked`.** ARIA outranks host state in the accessibility tree, and on the no-JS path this package supports there is nothing to rewrite the attribute after the user ticks the box. `Checkbox` writes only `'mixed'` (an IDL property with no attribute form, so ARIA is the only server-side lever); `Switch` writes none at all, over a `biome-ignore` that says why.
 - **A form binds to an action; it never decides for one.** `useForm` (`src/form/`) is a binding over an existing `action`, not a ninth primitive and not a component — `submit` is REQUIRED and is the only producer of a `succeeded` state, and the client-side parse's **value** is discarded so that only its issues are read. A binding that submitted the locally-parsed value would let a browser choose what the server was asked to store; `FormSchema` has no output type for that reason.
@@ -96,17 +58,16 @@ Tier 4. Imports `@ultimat3/core`, `i18n`, `money`, `time` — **not `schema`**,
 
 | Path | Responsibility |
 |---|---|
-| `src/tokens/*.scss` | canonical token maps + `_mixins.scss` authoring helpers |
+| `src/tokens/*.scss` | canonical token maps + `_mixins.scss` authoring helpers (`respond-to`/`-down`/`-between`) + `_units.scss` (`rem()`, `fluid()`). Every `@error` is `string.unquote('X_CODE: … fix: …')` with a REGISTERED code — `mixins.test.ts` |
 | `src/tokens/theme.scss` | the only stylesheet that emits global custom properties |
 | `src/tokens/reset.scss` | the reset, ZERO specificity: every rule a component may restyle sits in `:where(…)` whole, pseudo-class inside (`:where(a:hover)`, never `:where(a):hover`). `a:hover` (0,1,1) beat `.primary` and hid a button link's text until 22.3.2. `reset.test.ts` computes it |
 | `src/theme/runtime-slot.ts` | the module-scope slot holding the app's Solid runtime — and nothing else, so registering one costs an island 72 B |
 | `src/theme/solid-adapter.ts` | the runtime's SHAPE, and the one rule that decides which runtime a render gets |
 | `src/theme/inert-runtime.ts` | `INERT_SOLID_RUNTIME` — what a server render IS, not a stub of what it lacks |
-| `src/theme/theme.ts` | resolution: stored choice → OS; all side effects via injected `ThemeEnv` |
+| `src/theme/theme.ts` | resolution: stored choice → the theme the boot stamped on `<html>` (`ThemeEnv.current()`) → the app default (`data-theme-default`, `ThemeEnv.appDefault()`) → OS; clearing and the OS listener answer the app default too; all side effects via injected `ThemeEnv` |
 | `src/theme/ambient-slot.ts` | the module-scope slot holding the reader `useUi()` falls back to on the server — imports nothing, so a browser chunk pays nothing for it |
 | `src/theme/ambient.ts` | the server's reader (`ambientUiContext`: request locale, zone, direction, translator), registered at import; `index.ts` imports it bare, and the `browser` field maps it to `ambient.browser.ts`, which answers the defaults and registers nothing |
 | `src/error-registry.ts` | the `registerErrorCodes()` call, alone, so `errors.ts` is pure and the barrel's re-export of it costs a chunk nothing |
-| `src/theme/inline-script.ts` | anti-flash `<head>` snippet + its CSP sha256 |
 | `src/components/` | 62 components, `PascalCase.tsx` (component convention overrides the repo's kebab-case) |
 | `src/icons/glyphs/` | GENERATED: 1767 per-icon modules, `@ultimat3/ui/icons/<name>` → `icon<Name>` |
 | `src/icons/build-icons.ts` | the generator + the pinned `LUCIDE_VERSION`; `LICENSE.lucide` is upstream's ISC text |
@@ -127,6 +88,8 @@ Tier 4. Imports `@ultimat3/core`, `i18n`, `money`, `time` — **not `schema`**,
 | `src/form/use-form.ts` | the Solid shell: the same binding with its state in a signal |
 | `src/form/form-values.ts` | `FormData` → the nested object the action's input schema declares |
 | `src/form/field-binding.test.ts` | the WIRING, end to end: a rejection reaching `aria-invalid` and `aria-describedby` on the control it named |
+| `src/sass-probe.ts` | TEST-ONLY: what Sass EMITS. `sass` is resolved from `packages/render`'s directory — never an import of render, never a second copy |
+| `src/components/button-classes.ts` | the keys of a button's look, asked by `Button` AND `<Link appearance="button">` (`link-classes.ts`). `Button` gets no `href` |
 | `src/fake-dom.ts` | TEST-ONLY: a DOM where a disabled control refuses focus. Never exported from `index.ts` |
 | `src/jsx-probe.ts` | TEST-ONLY: a component's node tree, so a test can assert the props and call the handlers an element carries. `probe`/`unprobe` are the framework's ONE owner of `globalThis.React`, reached from `@ultimat3/admin` at `@ultimat3/ui/jsx-probe`; the walkers stay internal |
 | `src/barrel-bytes.test.ts` | the build error behind the three claims above: the setter's byte ceiling, barrel-vs-deep-path parity, and the theme-toggle island's retained-module list — the last two read off the `minify: false` banners, never a byte allowance |
@@ -143,6 +106,7 @@ bun test                                  # from the repo root
 bun run --filter @ultimat3/ui typecheck
 bun run --filter @ultimat3/ui catalog     # after any prop change — CATALOG.md is gated
 bun run --filter @ultimat3/ui icons       # regenerate the glyph set (network; dev-only)
+bun run --filter @ultimat3/ui icons --bump  # move LUCIDE_VERSION to the latest lucide-static, then regenerate
 ```
 
 ## Deep import

package/README.md

@@ -21,10 +21,22 @@ channels** so `rgb(var(--color-accent) / 0.12)` gives a tint with no extra token
 | `accent` / `accent-strong` / `accent-fg` | primary action, its hover, text on it |
 | `success` / `warning` / `danger` / `info` | status solid, each with a `-soft` tint and a `-fg` text-on-solid |
 
-Scales: `--space-*` (4px base), `--text-*` (fluid `clamp()`), `--radius-*`,
+Scales: `--space-*` (4px base), `--stroke-*` (line weights: `hairline thick heavy`), `--text-*` (fluid `clamp()`), `--radius-*`,
 `--shadow-*` (themed — dark gets deeper, higher-alpha shadows), `--duration-*`,
 `--easing-*`, `--z-*` (named ladder, no magic numbers).
 
+Authoring helpers, from the same `@use '@ultimat3/ui/tokens' as t` — an app writes no mixin of its own for any of them:
+
+| Helper | Emits |
+|---|---|
+| `@include t.respond-to(md)` | `@media (min-width: 768px)` — the rung and wider |
+| `@include t.respond-down(md)` | `@media (max-width: 767.98px)` — narrower than the rung; 0.02px under it, so no width matches both arms |
+| `@include t.respond-between(md, lg)` | `@media (min-width: 768px) and (max-width: 1023.98px)` |
+| `t.rem(24px)` | `1.5rem` — px, rem or a unitless px count in; `t.rem(20px, 10px)` states another root |
+| `t.fluid(1rem, 2rem, 20rem, 80rem)` | `clamp(1rem, 0.6666666667rem + 1.6666666667vw, 2rem)` — the first size at a 20rem viewport, the second at 80rem (the default range), linear between. Takes px too; a size that shrinks is legal |
+
+A rung is `sm md lg xl 2xl`, quoted or bare. Prefer a container query (`t.container` + `t.container-query`) to all three breakpoint mixins.
+
 ## The law
 
 | Rule | Enforcement |
@@ -32,7 +44,7 @@ Scales: `--space-*` (4px base), `--text-*` (fluid `clamp()`), `--radius-*`,
 | No raw colours | a hex or `rgb()` literal in a component stylesheet fails review; `tokens.test.ts` asserts the shared SCSS is hex-free |
 | No Tailwind | not a dependency, not a config, not an escape hatch |
 | No CSS-in-JS | styles are `Foo.module.scss` next to `Foo.tsx`, compiled at build |
-| No physical directions | `margin-inline`, `inset-inline-start`, `text-align: start` — RTL needs no second stylesheet |
+| No physical directions | `margin-inline`, `inset-inline-start`, `text-align: start` — RTL needs no second stylesheet. Centring is `inset-inline` + `margin-inline: auto`, never a 50% logical inset beside a physical −50% translate, and an edge shadow's physical x offset gets a `[dir='rtl']` mirror (`components/rtl-sheets.test.ts`) |
 | No hardcoded strings | labels are props, or `t()` through `UI_KEYS` |
 | One token source | `src/tokens/*.scss` is canonical; `tokens.ts` mirrors it and `x verify` fails on drift |
 | AA contrast, both themes | `contrast.test.ts` measures every pairing a component renders — text, status fills, soft tints, focus rings, borders |
@@ -193,7 +205,7 @@ commit the diff. There is no hand-edited icon in the package.
 
 ## Works without JavaScript
 
-Three components are interactive without a client runtime, because the platform already
+These components are interactive without a client runtime, because the platform already
 has the behaviour. Each is correct server-rendered, and the script layer only adds.
 
 | Component | Platform base | The enhancement |
@@ -201,6 +213,8 @@ has the behaviour. Each is correct server-rendered, and the script layer only ad
 | `Accordion` | `<details>` / `<summary>`; `exclusive` is the native `name` group | `onToggle` notification, after the browser has applied it |
 | `Combobox` | `<input list>` + `<datalist>` — typing, filtering, keyboard, mobile | `onFilter`, debounced, for a live/server-side query |
 | `InfiniteScroll` | a real `rel="next"` link to the next page | an `IntersectionObserver` sentinel that calls `onLoadMore` and intercepts the click |
+| `Pagination` with `hrefFor` | `<a rel="next">` / `<a rel="prev">`, one per cursor | none — link mode attaches no handler |
+| `Link appearance="button"` | an `<a href>` wearing Button's classes | none |
 
 ```tsx
 <Accordion level={3} exclusive items={[{ id: 'ship', title: t('faq.ship'), panel: <p>…</p> }]} />
@@ -217,6 +231,47 @@ scripting off the control is a link, and a link needs somewhere to go. `Combobox
 what it is given by `value` (`filterOptions` — case- and accent-insensitive, prefix first),
 so the list is right on the first paint and after a form round-trip, not only once JS runs.
 
+### A pager and a button that navigate
+
+```tsx
+import { Link, Pagination } from '@ultimat3/ui';
+import type { JSX } from 'solid-js';
+
+interface PostsFooterProps {
+  prevCursor?: string | undefined;
+  nextCursor?: string | undefined;
+  /** Already translated: `t('posts.new')` at the call site. */
+  newLabel: string;
+}
+
+export function PostsFooter(props: PostsFooterProps): JSX.Element {
+  return (
+    <footer>
+      <Link appearance="button" variant="secondary" size="sm" href="/posts/new">
+        {props.newLabel}
+      </Link>
+      <Pagination
+        prevCursor={props.prevCursor}
+        nextCursor={props.nextCursor}
+        hrefFor={(cursor, direction) =>
+          `/posts?${direction === 'next' ? 'after' : 'before'}=${cursor}`
+        }
+      />
+    </footer>
+  );
+}
+```
+
+| Rule | Held by |
+|---|---|
+| `Pagination` is one mode per use: `hrefFor`, or `onCursor` / `onPage` / `page` / `totalPages` — never both | the type: `PaginationProps` is `PaginationLinkProps \| PaginationCallbackProps`, and each forbids the other's props |
+| `DataTable` takes the same pair — `hrefFor` or `onCursor` — and hands it to its pager | the type: `DataTableProps<Row>` is `DataTableLinkProps<Row> \| DataTableCallbackProps<Row>` |
+| a `DataTable` sort header follows the table's mode: an anchor at `sortHrefFor(next)` in link mode, a button calling `onSortChange` in callback mode; a linked table with no `sortHrefFor` renders the header as text | the same union — `sortHrefFor` lives on `DataTableLinkProps`, `onSortChange` on `DataTableCallbackProps` — and `DataTable.test.ts` |
+| link mode pages by cursor only; a side with no cursor is a disabled button, never an anchor with nowhere to go | `Pagination.test.ts` |
+| a control that navigates is a `Link`; `Button` has no `href` | `ButtonProps` |
+| a button-link takes `variant` / `tone` / `size` / `fullWidth` / `iconStart` / `iconEnd`; a text link takes `underline` and `tone: 'accent' \| 'inherit'` | the type: `LinkProps` is `TextLinkProps \| ButtonLinkProps` |
+| both elements wear ONE set of classes | `buttonClassKeys` (`button-classes.ts`), asked by `Button` and `Link` |
+
 `debounce(fn, ms)` is exported on its own: trailing edge, `cancel()`, `flush()`, `pending()`.
 Components cancel theirs on cleanup, so a filter never fires into a tree that is gone.
 
@@ -441,14 +496,15 @@ one politeness — `politeness="assertive"` for a region that carries errors alo
 
 ## Theme resolution
 
-`explicit choice in localStorage` → `OS preference`. `setTheme()` persists,
-`clearTheme()` forgets and follows the OS again, and the OS listener only applies
-while nothing is stored. `themeInlineScriptTag()` goes in `<head>` and applies the
-result before first paint, so there is no flash and screenshots are deterministic:
-
-```
-Content-Security-Policy: script-src 'self' 'sha256-…'   # themeInlineScriptCspSource()
-```
+`explicit choice in localStorage` → `the theme already on <html>` → `defaultTheme(env)`: the
+app's `theme.defaultMode` (`data-theme-default`), and the OS only when that is `'system'` or
+absent. The framework's boot inlines `themeScript({ fallback })` from
+`@ultimat3/render` and stamps `data-theme` before first paint, and `resolveTheme()` reads it back
+through `ThemeEnv.current()` — so with `defaultMode: 'dark'` on a light-OS machine the first toggle
+flips to light rather than writing the dark already on screen. `setTheme()` persists,
+`clearTheme()` forgets and returns to the app default (`data-theme-default`, which the boot stamps
+from `theme.defaultMode`; the OS for `'system'`), and the OS listener applies only while nothing is
+stored and that default is `'system'`.
 
 ## Forms bound to an action's input schema
 
@@ -539,13 +595,13 @@ of truth for the one thing the server decides.
 
 | Code | When |
 |---|---|
-| `X_TOKEN_UNKNOWN` | a token role the SCSS source does not define — including a `defineTheme()` override of a role, radius or font slot that is not in the scale |
+| `X_TOKEN_UNKNOWN` | a token role the SCSS source does not define — including a `defineTheme()` override of a role, radius or font slot that is not in the scale, and a breakpoint rung `respond-to` / `respond-down` / `respond-between` was handed that is not in `$breakpoints` (a Sass `@error`: the stylesheet does not compile) |
 | `X_THEME_INVALID` | a theme other than `light` / `dark` |
 | `X_UI_RUNTIME_MISSING` | a DOM render with no registered Solid runtime, `<UiProvider>` on the server, or `browserThemeEnv()` off-DOM. A server render with no runtime is **not** one of them — it gets `INERT_SOLID_RUNTIME` |
 | `X_UI_FORM_PATH_INVALID` | a form field or control name the path grammar cannot read (`items.0.price`, `items[]`, `__proto__`), or two control names describing different shapes for one path (`user` beside `user.name`) |
 | `X_UI_CONTRAST_INSUFFICIENT` | a `defineTheme()` palette whose resolved channels put a pairing in `CONTRAST_PAIRS` below WCAG 2.2 AA — 4.5:1 for text, 3:1 for the focus ring. Only pairings the brand changed are measured; the cause names the measured ratio and the required one |
 | `X_UI_QR_CAPACITY` | a `<QrCode>` value over version 3's 42-byte ceiling (byte mode, error-correction level M). The encoder draws versions 1–3 only; the cause names the byte count and the ceiling |
-| `X_UI_INVALID_VALUE` | `<Money>` given a float, `<DateTime>` given an unparseable instant, `<Image>` given mixed `w`/`x` descriptors, one dimension without the other, or no reserved box at all, a heading level off 1–6, a `defineTheme()` value that is not a token value, an `<Icon>` glyph with a tag/attribute/colour outside `ICON_TAGS`, two `Accordion` items sharing an id, `InfiniteScroll` with `hasMore` and no `nextHref`, a negative `debounce` window, or (`As of 2026-08`) upstream icon data `bun run icons` refuses (not an object, no renderable nodes, an attribute value that is not glyph geometry) |
+| `X_UI_INVALID_VALUE` | `<Money>` given a float, `<DateTime>` given an unparseable instant, `<Image>` given mixed `w`/`x` descriptors, one dimension without the other, or no reserved box at all, a heading level off 1–6, a `defineTheme()` value that is not a token value, an `<Icon>` glyph with a tag/attribute/colour outside `ICON_TAGS`, two `Accordion` items sharing an id, `InfiniteScroll` with `hasMore` and no `nextHref`, a negative `debounce` window, or (`As of 2026-08`) upstream icon data `bun run icons` refuses (not an object, no renderable nodes, an attribute value that is not glyph geometry), or — as a Sass `@error` — `t.rem()` / `t.fluid()` given a unit other than px or rem, `t.fluid()` given a viewport range that is empty or reversed, `respond-between` given `$from` at or above `$to` |
 
 ### Error classes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/ui",
-  "version": "22.15.0",
+  "version": "24.0.0",
   "description": "SolidJS design system: semantic design tokens, dark/RTL-ready SCSS modules, a11y primitives",
   "license": "MIT",
   "type": "module",
@@ -33,6 +33,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*-fixture.ts",
     "CATALOG.md",
     "CLAUDE.md",
     "README.md",
@@ -48,10 +49,10 @@
     "icons": "bun run src/icons/build-icons.ts"
   },
   "dependencies": {
-    "@ultimat3/core": "22.15.0",
-    "@ultimat3/i18n": "22.15.0",
-    "@ultimat3/money": "22.15.0",
-    "@ultimat3/time": "22.15.0"
+    "@ultimat3/core": "24.0.0",
+    "@ultimat3/i18n": "24.0.0",
+    "@ultimat3/money": "24.0.0",
+    "@ultimat3/time": "24.0.0"
   },
   "peerDependencies": {
     "solid-js": "^1.9.0"

package/src/a11y.ts

@@ -20,27 +20,41 @@ export const FOCUSABLE_SELECTOR = [
 ].join(',');
 
 let idCounter = 0;
+let islandScope: string | undefined;
 
 /**
- * Unique id for label/description wiring, from a PROCESS-wide counter. Prefixed so a mismatch is
- * obvious in the DOM rather than silent.
+ * The part of an id that tells two copies of this module apart. Each island is its own bundle by
+ * default (`islands.sharedChunks` off — measured: every island chunk inlines this counter; with it
+ * on, one shared chunk holds it), so each island counts from zero and two of them both minted
+ * `field-1`. In a browser every copy draws its own scope once; a server render has one copy and no
+ * scope, so a document's ids carry no random part.
+ */
+function scope(): string {
+  if (typeof document === 'undefined') return '';
+  if (islandScope === undefined) {
+    const [draw = 0] = crypto.getRandomValues(new Uint32Array(1));
+    islandScope = draw.toString(36);
+  }
+  return `${islandScope}-`;
+}
+
+/**
+ * Unique id for label/description wiring. Prefixed so a mismatch is obvious in the DOM.
  *
- * Correct for the only render path that exists: a server render walks a tree once, so every id in
- * one document is distinct, which is all `for`/`aria-describedby` need. It is NOT stable across two
- * renders of the same tree — a second process, or a client re-render, starts its own count — so it
- * cannot survive hydration. That is latent rather than broken: this package has no client runtime
- * (see CLAUDE.md), so nothing re-renders a server tree yet. Making it survive needs a
- * RENDER-SCOPED counter, which means a seam in `@ultimat3/render` (or a `SolidRuntime` member);
- * resetting this one per request would only move the collision. Do not paper over it here.
+ * On the server it comes from a PROCESS-wide counter: every id in one document is distinct, which
+ * is all `for`/`aria-describedby` need, but two renders of one page mint different numbers — a
+ * render-scoped counter needs a seam in `@ultimat3/render`. An island never reuses a server id: it
+ * replaces its shell rather than hydrating it, and its own ids carry its scope (above).
  */
 export function useId(prefix = 'u'): string {
   idCounter += 1;
-  return `${prefix}-${idCounter.toString(36)}`;
+  return `${prefix}-${scope()}${idCounter.toString(36)}`;
 }
 
 /** Test-only: make id assertions deterministic. */
 export function resetIdCounter(): void {
   idCounter = 0;
+  islandScope = undefined;
 }
 
 /**