@haruhimemoe/ui 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -6,6 +6,34 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-10-03
+
+### Added
+
+- `@haruhimemoe/ui/mdx`: `mdxComponents` (the `a`/`h2`/`h3`/`pre`/`table`/`blockquote` element overrides for `@next/mdx` and `react-markdown`), `CodeBlock` (a fenced code block, Shiki-highlighted when registered), `Callout` (a note/tip/warning aside, also reached through a GitHub-style `> [!NOTE]` blockquote), `parseCodeMeta` and `slugify`.
+- `@haruhimemoe/ui/remark`: `remarkHaruhime` (default export, for Turbopack's module-name-only `remarkPlugins`) plus the named `remarkCodeMeta`, `remarkCallouts` and `remarkHeadingIds`, and `createSlugger`.
+- `@haruhimemoe/ui/shiki`: an opt-in side-effect import (`shiki` is now an optional peer dependency) that registers Shiki's core highlighter for `CodeBlock`. An app that skips it, or doesn't install `shiki`, gets plain code blocks instead of a build failure.
+- `theme.css`: `--shiki-foreground`, `--shiki-background` and the `--shiki-token-*` variables Shiki's CSS-variables theme reads, derived from `--hue` like the rest of the palette.
+
+### Changed
+
+- `Prose` styles a `pre` at any depth, excluding `CodeBlock`'s own (`role="group"`), so a plain `pre` nested inside `li` or `blockquote` keeps its fence look while `CodeBlock` (as `mdxComponents`' `pre` override renders it) keeps its own. `Prose` also styles `blockquote`.
+- `CodeBlock` accepts every native `<div>` prop (`id`, `data-*`, `aria-*`, …) except `code`, `lang`, `title` and `highlight`, spread onto its wrapper.
+
+## [0.8.0] - 2026-10-03
+
+### Added
+
+- `CommandPalette`: a mod+k command palette in a native `<dialog>`. Fuzzy search over commands with group headings and marked matches, nested pages (Backspace or Escape go back), async providers that search as you type (debounced, aborted when superseded), argument prompts (text, number, choice) before a command runs, a Recent group from localStorage, and a calculator row (`2*21` → `= 42`, Enter copies). Command shortcuts (`mod+shift+c`, chords like `g p`) work while the palette is closed. `openCommandPalette(page?)` opens it from anywhere; `CommandPaletteButton` is the header button with the platform hint. Built as a combobox over a listbox, with an `h1` edge on the active row, a focus cue on the input row, status errors and a polite result count.
+- `siteCommands(options)`: the defaults every tool gets: Go to each nav page, Open each other haruhime tool, Copy page URL, Go back, Scroll to top, Reload, Open on GitHub, Sign in / My account / Sign out, Keyboard shortcuts, Report a bug.
+- `fuzzyScore` and `evaluate` / `formatResult` are public, so an app can rank its provider rows the same way and reuse the calculator.
+- `playground/`: a Next.js app in the repo that renders the components from `src/` (`bun run play`), and `bun run play:axe`, which builds it and runs axe-core in Chromium over the palette's states. Not published.
+
+### Changed
+
+- `Checkbox` and `RadioGroup` boxes are 24px (WCAG 2.2 target size; they were the browser's 13px), centered on the first line of their label. `Disclosure` and `HeaderMenu` buttons are at least 24px tall.
+- The consumer check runs axe-core in headless Chromium over the fixture page with color contrast and target-size checks on, at 1280 and 390 wide, after `next build`. CI installs Chromium for it.
+
 ## [0.7.0] - 2026-10-03
 
 ### Changed
@@ -110,7 +138,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - `className` on every component, and the extras passed to `buttonClasses` and `fieldClasses`, merge with tailwind-merge: a caller's class replaces a built-in one that sets the same property (`fieldClasses("w-auto")` drops `w-full`).
 - Shell: `SiteHeader` (brand slot, nav links as data with `aria-current`, actions slot), `NavLinks`, `SiteFooter` (link columns as data, fine print, the haruhime.moe wordmark and a GitHub link) and `PageShell` (skip link, header, main, footer).
 
-[unreleased]: https://github.com/haruhimemoe/ui/compare/v0.7.0...HEAD
+[unreleased]: https://github.com/haruhimemoe/ui/compare/v0.9.0...HEAD
+[0.9.0]: https://github.com/haruhimemoe/ui/compare/v0.8.0...v0.9.0
+[0.8.0]: https://github.com/haruhimemoe/ui/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/haruhimemoe/ui/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/haruhimemoe/ui/compare/v0.5.1...v0.6.0
 [0.5.1]: https://github.com/haruhimemoe/ui/compare/v0.5.0...v0.5.1

package/README.md

@@ -2,11 +2,11 @@
 
 # @haruhimemoe/ui
 
-React components for the haruhime.moe osu! tools on Next.js. It ships the osu!-web-style palette as a Tailwind 4 theme, plus buttons, links, badges, form fields and confirms, filter controls (toggle and choice chips, a two-thumb range slider, a filter panel), tables, osu! beatmap display pieces and the site header, footer, tabs, account menu and page frame. Most components are Server Components. The few that need the browser carry `"use client"` in their own files, so you import everything from one place.
+React components for the haruhime.moe osu! tools on Next.js. It ships the osu!-web-style palette as a Tailwind 4 theme, plus buttons, links, badges, form fields and confirms, filter controls (toggle and choice chips, a two-thumb range slider, a filter panel), tables, osu! beatmap display pieces, a command palette (mod+k, with the defaults every tool shares) and the site header, footer, tabs, account menu and page frame. Most components are Server Components. The few that need the browser carry `"use client"` in their own files, so you import everything from one place.
 
 See every component in its states at [haruhime.moe/ui](https://www.haruhime.moe/ui). The page names the version it runs.
 
-This README describes version 0.7.0. Anything marked "since 0.7.0" is not in 0.6.0, anything marked "since 0.6.0" is not in 0.5.0, anything marked "since 0.5.0" is not in 0.4.0, anything marked "since 0.4.0" is not in 0.3.0, anything marked "since 0.3.0" is not in 0.2.0, and anything marked "since 0.2.0" is not in 0.1.0. [CHANGELOG.md](./CHANGELOG.md) lists what changed in each version.
+This README describes version 0.9.0. Anything marked "since 0.9.0" is not in 0.8.0, anything marked "since 0.8.0" is not in 0.7.0, anything marked "since 0.7.0" is not in 0.6.0, anything marked "since 0.6.0" is not in 0.5.0, anything marked "since 0.5.0" is not in 0.4.0, anything marked "since 0.4.0" is not in 0.3.0, anything marked "since 0.3.0" is not in 0.2.0, and anything marked "since 0.2.0" is not in 0.1.0. [CHANGELOG.md](./CHANGELOG.md) lists what changed in each version.
 
 ## Requirements
 
@@ -153,7 +153,7 @@ export default function Home() {
 
 Import every component from `@haruhimemoe/ui`, in Server and Client Components alike.
 
-- **Client components:** `CopyButton`, `Chip`, `ChipGroup`, `RangeSlider` and `FilterPanel`, and since 0.4.0 `AsyncButton`, `InlineConfirm`, `Disclosure`, `ChoiceChips`, `RadioGroup`, `TypeToConfirm` and `HeaderMenu`, and since 0.5.0 `Tabs`, `VisibilitySelect` and `ReportDisclosure`. Each file starts with `"use client"`. They merge their classes with tailwind-merge in the browser, so a page that renders any of them loads tailwind-merge (about 9 KB gzipped), however its header renders.
+- **Client components:** `CopyButton`, `Chip`, `ChipGroup`, `RangeSlider` and `FilterPanel`, and since 0.4.0 `AsyncButton`, `InlineConfirm`, `Disclosure`, `ChoiceChips`, `RadioGroup`, `TypeToConfirm` and `HeaderMenu`, and since 0.5.0 `Tabs`, `VisibilitySelect` and `ReportDisclosure`, and since 0.8.0 `CommandPalette` and `CommandPaletteButton`. Each file starts with `"use client"`. They merge their classes with tailwind-merge in the browser, so a page that renders any of them loads tailwind-merge (about 9 KB gzipped), however its header renders.
 - **`SiteHeader` and `NavLinks`** are Server Components with a small client part (since 0.2.0; in 0.1.0 `NavLinks` is a client component). When a nav link can be the current page (a path such as `/packs`), a client list reads the path to set `aria-current`. With only external or text-only links, the nav renders on the server alone and nothing in it hydrates. Relative hrefs (`#main`) skip the client list too, but they render `next/link`, which hydrates.
 - **Everything else is server-safe:** no state, no effects, no browser APIs.
 
@@ -255,7 +255,7 @@ Later sections keep their heading margin, which spaces them apart.
 
 #### `Disclosure` (client)
 
-Since 0.4.0. A button that shows and hides a panel below it, with `aria-expanded` and `aria-controls` and a ▾ / ▴ arrow. The closed panel stays in the page, hidden, so fields inside keep their values. Every native `<div>` prop except `children`, for the wrapper.
+Since 0.4.0. A button (at least 24px tall) that shows and hides a panel below it, with `aria-expanded` and `aria-controls` and a ▾ / ▴ arrow. The closed panel stays in the page, hidden, so fields inside keep their values. Every native `<div>` prop except `children`, for the wrapper.
 
 | Prop | Type | Default | What it does |
 | --- | --- | --- | --- |
@@ -345,11 +345,11 @@ Every native `<select>` prop, plus the field props. Pass `<option>` elements as
 
 #### `Checkbox`
 
-Every native `<input>` prop except `type` (`checked`, `defaultChecked`, `onChange`, `name`, `disabled`...), plus the field props. The label is bold `text-c1` and the hint follows it inline after a dot. Clicking anywhere on the row toggles it. The label alone is the accessible name; the hint is the description. An `aria-labelledby` you pass is added after the label (since 0.4.0; 0.3.0 dropped it).
+Every native `<input>` prop except `type` (`checked`, `defaultChecked`, `onChange`, `name`, `disabled`...), plus the field props. The box is 24px (since 0.8.0; it was the browser's 13px), the label is bold `text-c1` and the hint follows it inline after a dot. Clicking anywhere on the row toggles it. The label alone is the accessible name; the hint is the description. An `aria-labelledby` you pass is added after the label (since 0.4.0; 0.3.0 dropped it).
 
 #### `RadioGroup` (client)
 
-Since 0.4.0. A native radio group on the `Checkbox` look: a `<fieldset>` named by its `<legend>`, one radio per option with a bold label and an inline hint, then the group's hint and error. Each option's label is its accessible name and its hint its description. Arrow keys move and pick, as native radios do. Every native `<fieldset>` prop except `onChange`, `children` and `defaultValue`; `disabled` turns off every radio. Types: `RadioOption`.
+Since 0.4.0. A native radio group on the `Checkbox` look: a `<fieldset>` named by its `<legend>`, one 24px radio per option with a bold label and an inline hint, then the group's hint and error. Each option's label is its accessible name and its hint its description. Arrow keys move and pick, as native radios do. Every native `<fieldset>` prop except `onChange`, `children` and `defaultValue`; `disabled` turns off every radio. Types: `RadioOption`.
 
 | Prop | Type | Default | What it does |
 | --- | --- | --- | --- |
@@ -788,7 +788,7 @@ Since 0.4.0. A row of link tabs (Pools / Maps, All / Hidden): a named `<nav>` wi
 
 #### `HeaderMenu` (client)
 
-Since 0.4.0. The header's account menu: a button (an avatar and a name, say) that shows a small panel of links and extra controls such as a sign-out button. It is a disclosure, not an ARIA menu: the button has `aria-expanded` and `aria-controls`, and Tab moves through the panel. Escape closes it and puts focus back on the button; a click outside it, a click on one of its links, or focus leaving it closes it too. Every native `<div>` prop except `children`, for the wrapper. Type: `HeaderMenuItem`.
+Since 0.4.0. The header's account menu: a button (an avatar and a name, say; at least 24px tall) that shows a small panel of links and extra controls such as a sign-out button. It is a disclosure, not an ARIA menu: the button has `aria-expanded` and `aria-controls`, and Tab moves through the panel. Escape closes it and puts focus back on the button; a click outside it, a click on one of its links, or focus leaving it closes it too. Every native `<div>` prop except `children`, for the wrapper. Type: `HeaderMenuItem`.
 
 | Prop | Type | Default | What it does |
 | --- | --- | --- | --- |
@@ -845,6 +845,240 @@ A mod pool slot's pill (`NM1`, `HD2`, `TB`), colored by the first two letters: N
 | --- | --- | --- | --- |
 | `mod` | `string` | required | The mod or slot label. |
 
+### MDX (server)
+
+Since 0.9.0. Three subpaths, so an app that never renders Markdown loads none of this: `@haruhimemoe/ui/mdx` (the React pieces: `mdxComponents`, `CodeBlock`, `Callout`), `@haruhimemoe/ui/remark` (plain functions, no React, for `@next/mdx` and `react-markdown`'s `remarkPlugins`), and `@haruhimemoe/ui/shiki` (opt-in code highlighting). The root `@haruhimemoe/ui` export is unchanged.
+
+**With `@next/mdx`:**
+
+```ts
+// next.config.ts
+import createMDX from "@next/mdx";
+
+const withMDX = createMDX({
+  extension: /\.mdx?$/,
+  // Turbopack only takes MDX plugins as module names, not imported functions.
+  options: { remarkPlugins: ["remark-gfm", "@haruhimemoe/ui/remark"] },
+});
+
+export default withMDX({ pageExtensions: ["ts", "tsx", "md", "mdx"] });
+```
+
+```tsx
+// mdx-components.tsx
+import { mdxComponents } from "@haruhimemoe/ui/mdx";
+import "@haruhimemoe/ui/shiki"; // optional: see "Code highlighting" below
+
+export function useMDXComponents(components) {
+  return { ...mdxComponents, ...components };
+}
+```
+
+`remark-gfm` isn't ui's dependency (pin it yourself); without it `@next/mdx` has no pipe tables, and a table with no GFM stays a paragraph.
+
+**With `react-markdown`:**
+
+```tsx
+import { mdxComponents } from "@haruhimemoe/ui/mdx";
+import remarkHaruhime from "@haruhimemoe/ui/remark";
+import remarkGfm from "remark-gfm";
+import Markdown from "react-markdown";
+
+<Markdown components={mdxComponents} remarkPlugins={[remarkGfm, remarkHaruhime]}>
+  {body}
+</Markdown>;
+```
+
+`mdxComponents` must render in a Server Component: `CodeBlock` (its `pre` override hands off to) is async, and a client component can't render an async one. A client-side renderer, like a live editor preview, can't use `pre` from this map; pass your own synchronous override for that case.
+
+If you sanitize the output (`rehype-sanitize` or your own schema), allow `className` on `code` matching `/^language-/`, `dataMeta` on `code`, `dataCallout` on `blockquote`, and `id` on `h2`/`h3`: the remark plugin writes these, and `mdxComponents` reads them back. rehype-sanitize's default `clobberPrefix` renames those heading ids to `user-content-…`; pass `clobberPrefix: ""` (what haruhime.moe uses) to keep the plain id, or live with the prefix and update any hand-written anchor links to match.
+
+#### `mdxComponents`
+
+The element overrides apps pass to `@next/mdx`'s `useMDXComponents` or `react-markdown`'s `components`: `{ a, blockquote, h2, h3, pre, table }`. Spread it and add your own (`{ ...mdxComponents, Example: LiveExample }`).
+
+| Element | Renders |
+| --- | --- |
+| `a` | `https://` opens in a new tab (`rel="noopener noreferrer"`); a same-page `#hash` is a plain anchor; everything else goes through `AutoLink` (`next/link`, or a plain `<a>` off-site). |
+| `h2`, `h3` | The heading with its id (from the remark plugin, or a `slugify` of its own text) and, beside it, a `#` anchor link (`aria-label="Link to section: …"`, always visible in `c4`, turning `h1` on hover, never only on hover). |
+| `pre` | Reads its single `code` child (text, `language-x` class, the fence's meta) and renders `CodeBlock`. Anything else (a `pre` with no single `code` child) renders as a plain, focusable `<pre>`. |
+| `table` | The table wrapped in a focusable, named scroll region: `<div role="group" tabIndex={0} aria-label="…">`, labelled by the table's `<caption>` text, or `"Table"` without one. |
+| `blockquote` | A blockquote the remark plugin marked `data-callout` renders as `Callout` of that type; any other blockquote renders plainly. |
+
+#### `CodeBlock`
+
+An async Server Component: a header bar (the fence's `title`, or the language name, or `"Code"`) with a copy button, over a `<pre role="group" tabIndex={0}>` of lines. Every native `<div>` prop goes on the wrapper except `code`, `lang`, `title` and `highlight`.
+
+| Prop | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `code` | `string` | required | The text. Any line endings (`\r\n`, a trailing newline) are normalized; a lone trailing newline doesn't add a phantom last line. |
+| `lang` | `string` | none | A Shiki language id or alias (`ts`, `tsx`, `js`, `json`, `bash`/`sh`/`shell`, `css`, `html`, `md`/`markdown`, `diff`, `yaml`/`yml`). Unknown languages render plain. |
+| `title` | `string` | none | Shown in the header instead of the language; also names the `<pre>` and the copy button ("Copy x.ts"). |
+| `highlight` | `readonly number[]` | `[]` | 1-based line numbers to mark: an `h1` left border and a `b4` tint (`forced-colors:border-[Highlight]` keeps the mark visible under Windows high contrast). |
+
+In MDX, pass these through the fence's meta string instead of writing `CodeBlock` by hand: ` ```ts title="pool.ts" {2,4-5}`. `parseCodeMeta` reads `title="…"` or `title='…'` and `{1,3-5}` ranges (anything else is ignored, and it never throws); the language comes from the fence's own tag.
+
+#### Code highlighting
+
+`shiki` is an optional peer dependency: apps that never render code don't install it, and ui's only runtime dependency stays `tailwind-merge`. An app that renders code:
+
+```sh
+bun add shiki
+```
+
+```ts
+// in the module that renders code: mdx-components.tsx, or next to your react-markdown call
+import "@haruhimemoe/ui/shiki";
+```
+
+That import is a side effect: it registers a Shiki core highlighter (`shiki/core` with the no-WASM JS regex engine, loaded through dynamic `import()`) under `@haruhimemoe/ui/mdx`'s `CodeBlock`. The registration lives on `globalThis` for the whole process, not per module graph, but it only exists once the import has actually run: put it in the module that renders code (`mdx-components.tsx`, which reaches every MDX page, or directly beside your `react-markdown` renderer) so it runs before `CodeBlock` does. `package.json`'s `sideEffects` lists `./dist/shiki.js`, so bundlers don't drop the bare import; Turbopack resolves even a dynamic `import("shiki/core")` at build time, which is why highlighting is a separate subpath instead of `CodeBlock` importing it unconditionally.
+
+Without the import, `CodeBlock` renders plain, unstyled lines, and in development it logs one `console.warn` per process ("code blocks aren't highlighted…"). A highlighter that fails to load (a missing package, a broken build) falls back the same way, warned once.
+
+Tokens render as `<span style={{ color: "var(--shiki-token-…)" }}>`, no injected Shiki HTML, through `--shiki-*` custom properties in `theme.css` (see "Setup" above for loading it). They follow `--hue` like the rest of the palette: `--shiki-foreground` and `--shiki-background` are `c2`/`b6`; `-punctuation` is `c3` and `-comment` is `c4`, the palette tokens as-is; `-keyword` and `-link` are `hsl(var(--hue) 100% 78%)`, the palette's own hue with no offset; `-string`, `-string-expression`, `-constant`, `-function` and `-parameter` are each `calc(var(--hue) + N)`, a hue-offset HSL value. Every one stays at or above 4.5:1 against both `b6` (the block's background) and `b4` (a highlighted line's tint) at every integer hue. `keyword` and `link` get their own fixed lightness instead of reusing `h1`: `h1`'s default (76%) drops to 4.33:1 against `b4` at hue 240, and a `--h1-l` override written for other text shouldn't silently recolor code too.
+
+#### `Callout`
+
+A labelled aside: a left-border panel (`role="note"`) with an icon and a bold label, usable directly in MDX or rendered by `mdxComponents`' `blockquote` override.
+
+| Prop | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `type` | `"note" \| "tip" \| "warning"` | `"note"` | The border color, icon and default label (`h1` / `c2` / `h2` border; "Note" / "Tip" / "Warning"). The type is in the text, never color alone. |
+| `title` | `ReactNode` | the type's label | Replaces the default label. |
+| `children` | `ReactNode` | required | The body. |
+
+GitHub-style callout syntax works through the remark plugin: a blockquote whose first paragraph starts with `[!NOTE]`, `[!TIP]`, `[!WARNING]` (case-insensitive; GitHub's `[!IMPORTANT]` maps to `tip`, `[!CAUTION]` to `warning`) becomes a `Callout` of that type, the marker stripped:
+
+```md
+> [!NOTE]
+> Packs are deleted after 90 days of no edits.
+```
+
+Or write `<Callout type="tip">` directly in an `.mdx` file.
+
+#### `@haruhimemoe/ui/remark`
+
+Plain functions (no React), for `remarkPlugins`. Default export `remarkHaruhime(options?)` runs all three transforms below in order and is what Turbopack needs by module name: `remarkPlugins: ["@haruhimemoe/ui/remark"]`. Named exports `remarkCodeMeta`, `remarkCallouts` and `remarkHeadingIds` run one each, for `react-markdown`'s array form or a custom pipeline.
+
+| Option (all default `true`) | Turns off |
+| --- | --- |
+| `codeMeta` | Copying a fenced code block's meta string onto `data-meta`, which `CodeBlock`'s fence syntax (`title=`, `{…}`) reads. |
+| `callouts` | The `[!NOTE]` / `[!TIP]` / `[!WARNING]` blockquote markers. |
+| `headingIds` | Slugged, deduplicated ids on `h2`/`h3` (a heading that already has one keeps it). |
+
+`slugify(text)` and `createSlugger()` are also exported: lowercase, Unicode-aware (letters, marks, digits and underscores from any script survive; everything else but whitespace and hyphens is dropped), spaces to hyphens, repeats suffixed `-1`, `-2` like GitHub's own heading anchors. `@haruhimemoe/ui/mdx` re-exports `slugify` for apps that build their own heading links.
+
+#### Accessibility
+
+- The `<pre>` `CodeBlock` renders and the `<div>` `mdxComponents`' `table` wraps a table in are both `role="group"` with `tabIndex={0}` and an `aria-label` (`pre` may not be named on its own): keyboard users can reach a sideways scroll that a mouse would otherwise require. Do the same for any `pre` you render yourself inside `Prose`.
+- Heading anchor links are always visible (`c4`, turning `h1` on hover), never hover-only, and at least 24px; their `aria-label` ("Link to section: …") keeps the heading's own accessible name as its own text.
+- `CodeCopyButton` reports "Copied" or "Copy failed" through a live region mounted before use, like `CopyButton`.
+- `Callout` is `role="note"` with the type in text, not color alone; highlighted code lines keep a `forced-colors` border so Windows high contrast mode still shows them.
+
+`Prose` (in "Basics" above) styles a direct-child `pre` with its own fence look, so `CodeBlock` (which isn't a direct child; `mdxComponents`' `pre` override renders it) is untouched when both are in play. `Prose` also styles `blockquote`.
+
+### Palette (client)
+
+Since 0.8.0. A command palette: press Ctrl K (⌘K on a Mac) anywhere on the page and a dialog opens with a search box over everything the app can do. It is one component for every haruhime tool: `CommandPalette` is the engine, `siteCommands` the defaults every site shares, and each app plugs in its own commands, pages and search providers through the same `Command` and `Provider` types. No new dependency.
+
+Mount it once, from a client file, since commands carry functions. The button goes in `SiteHeader`'s `actions`:
+
+```tsx
+// src/components/Palette.tsx
+"use client";
+
+import { type Command, CommandPalette, siteCommands } from "@haruhimemoe/ui";
+import { HEADER_LINKS } from "@/constants/nav";
+
+const COMMANDS: Command[] = [
+  ...siteCommands({ pages: HEADER_LINKS, tools: "packs", repo: "https://github.com/haruhimemoe/packs.haruhime.moe" }),
+  { id: "pack.new", title: "New pack", group: "Packs", shortcut: "g n", run: (ctx) => ctx.navigate("/new") },
+];
+
+export function Palette() {
+  return <CommandPalette storageKey="packs" commands={COMMANDS} />;
+}
+```
+
+```tsx
+// app/layout.tsx
+<SiteHeader brand={...} links={HEADER_LINKS} actions={<CommandPaletteButton>Search</CommandPaletteButton>} />
+<Palette />
+```
+
+#### `CommandPalette`
+
+The dialog. Renders nothing until opened, then a native `<dialog>` (modal, backdrop, scroll locked) with a combobox over a listbox. Mount one per app.
+
+| Prop | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `commands` | `readonly Command[]` | required | The root rows. Read on every open, so a command's `when` and titles can change. |
+| `providers` | `readonly Provider[]` | none | Searched at the root as you type, once the query reaches each one's `minLength`. |
+| `storageKey` | `string` | `"default"` | Namespaces the recents in `localStorage` (`haruhime:palette:<key>`). |
+| `hotkey` | `string` | `"mod+k"` | The toggle, in shortcut syntax. `mod` is ⌘ on a Mac and Ctrl elsewhere. |
+| `placeholder` | `string` | `"Search commands…"` | The root input's placeholder. |
+| `label` | `string` | `"Command palette"` | The dialog's and the input's accessible name. |
+| `calculator` | `boolean` | `true` | A `= 42` row for a query that computes (`2*21`), first in the list; Enter copies the result. |
+| `recents` | `boolean` | `true` | A Recent group of the last five commands run, and a ranking boost by how often each ran. |
+| `className` | `string` | none | Classes for the panel. |
+
+Keys: ↑ ↓ move (wrapping), Home and End jump, Enter runs the active row, Escape goes back a level and then closes, Backspace on an empty input goes back a level, Tab stays put (focus never leaves the input), and the hotkey (a combo, not a chord) toggles the palette from anywhere, a field included, without typing into it. A click on the backdrop closes it, and so does the browser (a back gesture on Android). Focus returns to whatever had it. The footer reads the result count, or the copy outcome until the query changes.
+
+Typing filters the rows with a fuzzy match: a letter or digit must start a word or follow the previous match ("cpu" finds "Copy page URL", "go" doesn't find "Sign out"), except in scripts without case or spaces (kanji, kana), which match anywhere; the title weighs most, then `keywords`, `subtitle` and `group`. Matched letters are marked. With an empty query every command is listed under its group, in order, after the Recent group.
+
+#### `Command`
+
+| Field | Type | What it does |
+| --- | --- | --- |
+| `id` | `string` | Unique in the app. Recents are stored by it, so keep it stable when a title changes. |
+| `title` | `string` | The row. |
+| `subtitle?` | `string` | A smaller second line. |
+| `icon?` | `ReactNode` | A 20px slot before the title. |
+| `keywords?` | `string[]` | Matched at a lower weight than the title. |
+| `group?` | `string` | The heading the row sits under. Default `"Commands"`. |
+| `shortcut?` | `string` | Shown as keys on the row, and active while the palette is mounted and closed: a combo (`"mod+shift+c"`, `"?"`) or a chord of two bare keys (`"g p"`, within 800 ms). Never fires from a field. |
+| `when?` | `(ctx) => boolean` | Hidden when false. Read on every render of the list. |
+| `run?` | `(ctx, args) => void \| Promise<void>` | What it does. A rejection is logged; the palette stays usable. |
+| `page?` | `Page` | Instead of `run`: Enter pushes this page (its `commands` and `providers`), with the page's title as a crumb. |
+| `args?` | `ArgSpec[]` | Prompts collected before `run`, one at a time: `{ name, label, type: "text" \| "number" \| "choice", choices?, validate? }`. A `choice` lists its `choices` as rows (fuzzy-filtered); `text` and `number` take the input on Enter; `validate` returns a message to block it. `run` gets them as `args[name]`. |
+| `closeOnRun?` | `boolean` | Default `true`. |
+
+`PaletteContext` (the `ctx` a command runs with): `navigate(href)` (`router.push`), `close()`, `push(page)` (opens the palette first when closed), `copy(text)` (clipboard, announcing "Copied" or the failure), `pathname`, and `commands` (every root command, so a page can list them).
+
+#### `Provider`
+
+`{ id, group?, minLength? = 2, debounceMs? = 200, search(query, signal) }`. `search` returns `Command[]` for the query and must honor the `AbortSignal`: a newer query aborts the older search, and a late result is dropped. Its rows sit under `group` (default "Results") after the static matches; while it runs the list is `aria-busy`, says "Searching…" and keeps the last rows in place, so nothing flashes per keystroke; an error says "Couldn't search, try again". `fuzzyScore(query, text)` is exported so a provider can rank its rows the way the palette does.
+
+#### `openCommandPalette(page?)`
+
+Opens the mounted palette from anywhere (a button, a tour), onto `page` when given. It dispatches a `window` event, so it works from a Server Component's client child without a ref.
+
+#### `CommandPaletteButton` (client)
+
+A ghost `Button` with a magnifier, your `children` beside it and the hotkey hint (`Ctrl K`, or `⌘K` once a Mac is detected after mount; decorative, so it isn't part of the name). With `children`, that text is the button's name; without, `label` is (default "Open command palette"). Every `Button` prop except `onClick`.
+
+#### `siteCommands(options)`
+
+The defaults every tool gets, in order: Navigate, Page, Account, Help. Pass only what the app has.
+
+| Option | Type | What it builds |
+| --- | --- | --- |
+| `pages` | `SiteLinkItem[]` | "Go to <label>" per linked nav item (`site.go.<slug>`). |
+| `tools` | `HaruhimeToolId \| false` | "Open <tool>" for every other tool in `HARUHIME_TOOLS` plus "Open haruhime.moe" (`site.tool.<id>`, `site.tool.home`). `false` leaves them out. |
+| `repo` | `string` | "Open on GitHub" (`site.github`) and "Report a bug" (`site.report`, the repo's new-issue page). |
+| `account` | `{ signedIn, signInHref, accountHref?, signOutHref? }` | "Sign in" (`site.sign-in`) while signed out; "My account" (`site.account`) and "Sign out" (`site.sign-out`, navigated, as next-kit's route expects) while signed in. |
+| `include` | `("navigate" \| "page" \| "account" \| "help")[]` | Which groups. Default all. |
+
+Always there: "Copy page URL" (`site.copy-url`, mod+shift+c), "Go back" (`site.back`), "Scroll to top" (`site.top`, instant under reduced motion), "Reload page" (`site.reload`) and "Keyboard shortcuts" (`site.shortcuts`, `?`), a page listing every command that has a shortcut, the app's included.
+
+#### Calculator
+
+`evaluate(expression)` and `formatResult(value)` are exported. The grammar: `+ - * / % ^`, unary minus, parentheses, `k` and `m` suffixes (`1.5k`), `pi` and `e`, and `sqrt`, `abs`, `round`, `floor`, `ceil`, `min` and `max`. Anything else, and a result that isn't finite, is `null`. In the palette a bare number or word is a search, not a sum.
+
+#### Accessibility
+
+The input is a `combobox` over a `listbox`; the active row is named by `aria-activedescendant`, so focus never leaves the input. The active row shows an `h1` left edge as well as a tint, the input row's bottom border turns `h1` while it has focus, hint rows ("Searching…", "No matching commands") are disabled options, an argument's error is an always-mounted `role="status"`, group headings aren't uppercase, rows are 36px, and the footer's `<output>` reads the result count and the copy outcome. `bun run play:axe` runs axe-core in Chromium over the open palette's states with contrast on.
+
 ### Tables
 
 Since 0.4.0. `Table`, `THead`, `TBody`, `Th` and `Td` give a data table the apps' look: full width, small left-aligned text, muted capitals in the head and a rule above each body row. They are Server Components, and each takes its element's native props, `className` (merged last) and `ref`. Use plain `<tr>` for rows.
@@ -889,21 +1123,22 @@ Since 0.4.0. `cx(...classes: ClassValue[]): string` is the class merger every co
 The target is WCAG 2.2 AA. House rules, which every component follows and your own code around them should too:
 
 - **Focus is always visible, and always the same.** The theme draws a 2px `h1` outline, offset 2px, on `:focus-visible`. Fields keep it (since 0.7.0; before, they swapped it for a 1px border change) and add an `h1` border. `RangeSlider` thumbs show a solid `h1` ring instead and keep a transparent outline, so Windows high contrast mode (forced colors) still paints one. Never `outline: none`.
-- **Targets are 24px or more** (WCAG 2.2 2.5.8): buttons are `h-9`, chips and tabs 24px tall, slider thumbs 24px (since 0.7.0).
+- **Targets are 24px or more** (WCAG 2.2 2.5.8): buttons are `h-9`, chips and tabs 24px tall, slider thumbs 24px (since 0.7.0), checkboxes and radios 24px and the `Disclosure` and `HeaderMenu` buttons at least 24px tall (since 0.8.0).
 - **Contrast is computed, not eyeballed.** The test suite checks `c1` on `h2`, `h1` on `b4` and `b5`, and the hue overrides under Setup; `StarRating` picks its text color by contrast. Text is never dimmed with `opacity` (a `text-c4` line at 70% opacity drops under 4.5:1): use a lighter palette step instead.
 - **Color never carries meaning alone.** Accent links are underlined, a pressed `Chip` is `aria-pressed`, the current nav link is `aria-current`, `CharCounter` says "over the limit" in words, errors are text.
 - **Live regions exist before they speak.** `CopyButton`, `AsyncButton`, `CharCounter live`, `FilterPanel`'s count and `ReportDisclosure`'s outcome render their `<output>` or `role="status"` node up front, empty, and swap the text in. Field errors are `role="status"` (polite); `Notice live tone="error"` is the one `role="alert"`.
 - **Focus never falls to the body.** When the control you pressed goes away, focus moves somewhere sensible: `FilterPanel` to its heading, `Pagination` to "Page X of Y", `InlineConfirm` back to its trigger, `ReportDisclosure` to its outcome line. Pending buttons use `aria-disabled`, not `disabled`, so focus stays.
+- **The palette is a combobox.** `CommandPalette` keeps focus on its input and names the active row with `aria-activedescendant`; the row shows its state with an `h1` edge, the input row shows focus, and `bun run play:axe` checks its open states in a real browser (since 0.8.0).
 - **Landmarks are few and named.** `PageShell` gives a skip link and `<main>`; `SiteHeader` one `<nav>` (`navLabel`, default "Main"); `SiteFooter` one `<nav>` (`navLabel`, default "Footer") with a headed `<section>` per column; `Pagination` and `LinkTabs` are labelled `<nav>`s. Give two of a kind different labels.
 - **Scrollable regions take focus.** `Table`'s wrapper is a focusable named section. Do the same for a `pre` inside `Prose`.
 - **Native first.** Fields are native inputs, selects and textareas; radios and checkboxes are native with a visible label; `RangeSlider`'s thumbs are native range inputs with `aria-valuetext` ("10+" reads as it shows); `Disclosure` and `HeaderMenu` are buttons with `aria-expanded` and `aria-controls`; `Tabs` follows the ARIA tabs pattern (one tab in the Tab order, arrows, Home and End, `aria-controls`). ARIA only where HTML has no element.
 - **Groups are named.** `ChipGroup`, `RangeSlider`, `RadioGroup` and `FilterRow` are fieldsets named by their label. Inside a `FilterRow`, `hideLabel` leaves the naming to the row, so each row is announced once.
 - **Icons are decorative; links and buttons have names.** `DiscordIcon` and `GitHubIcon` are hidden from screen readers; give the link around each one an `aria-label`, as `SiteFooter` does. Give icon-only buttons an `aria-label`, and keep `label` props meaningful. `BeatmapStats` reads "Circle size" where it shows "CS".
-- **Tested.** Every component is checked with axe-core's WCAG 2.0, 2.1 and 2.2 A and AA rules in the test suite (color contrast excepted: that needs a real browser, and the sites run a Playwright axe pass with it on). Interactive ones also have keyboard tests.
+- **Tested.** Every component is checked with axe-core's WCAG 2.0, 2.1 and 2.2 A and AA rules in the test suite (color contrast excepted: that needs a real browser). The consumer check then renders every component in a real Next.js app and runs axe in headless Chromium with contrast and target-size checks on, at a desktop and a phone width; the sites run the same pass over their pages. Interactive ones also have keyboard tests.
 
 ## Compatibility
 
-| | Supported |
+| Requirement | Supported |
 | --- | --- |
 | Next.js | 16 (app router). Components use `next/link` and `next/navigation`. |
 | React | 19 |
@@ -914,7 +1149,7 @@ The target is WCAG 2.2 AA. House rules, which every component follows and your o
 
 ## Changelog and contributing
 
-See [CHANGELOG.md](./CHANGELOG.md) for what changed in each version and [CONTRIBUTING.md](./CONTRIBUTING.md) to work on the package. Report security issues as described in [SECURITY.md](./SECURITY.md). Bring questions and feedback to the haruhime.moe [Discord server](https://discord.gg/bKy9kjMV4y).
+See [CHANGELOG.md](./CHANGELOG.md) for what changed in each version and [CONTRIBUTING.md](./CONTRIBUTING.md) to work on the package. `bun run play` serves `playground/`, a small Next.js app in the repo that renders the components straight from `src/`, for trying a change by hand. Report security issues as described in [SECURITY.md](./SECURITY.md). Bring questions and feedback to the haruhime.moe [Discord server](https://discord.gg/bKy9kjMV4y).
 
 ## License
 

package/dist/components/basics/Disclosure.d.ts

@@ -5,7 +5,7 @@
  *       so its form fields keep their values. Uncontrolled by default, or controlled with `open`.
  * @author David @dvhsh (https://dvh.sh)
  * @created Mon Sep 28, 2026
- * @modified Mon Sep 28, 2026
+ * @modified Sat Oct 3, 2026
  */
 import { type ComponentProps, type ReactNode } from "react";
 /** Every native `<div>` prop for the wrapper, plus the button's text and the panel. */

package/dist/components/basics/Disclosure.js

@@ -5,7 +5,7 @@
  *       so its form fields keep their values. Uncontrolled by default, or controlled with `open`.
  * @author David @dvhsh (https://dvh.sh)
  * @created Mon Sep 28, 2026
- * @modified Mon Sep 28, 2026
+ * @modified Sat Oct 3, 2026
  */
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
@@ -26,5 +26,5 @@ export function Disclosure({ summary, children, defaultOpen = false, open, onOpe
             setInner(!isOpen);
         onOpenChange?.(!isOpen);
     };
-    return (_jsxs("div", { className: cx("flex flex-col gap-2", className), ...props, children: [_jsxs("button", { type: "button", "aria-expanded": isOpen, "aria-controls": panelId, onClick: toggle, className: cx("inline-flex items-center gap-1 self-start font-bold text-c2 text-sm transition-colors hover:text-c1", buttonClassName), children: [summary, _jsx("span", { "aria-hidden": "true", children: isOpen ? "▴" : "▾" })] }), _jsx("div", { id: panelId, hidden: !isOpen, className: panelClassName, children: children })] }));
+    return (_jsxs("div", { className: cx("flex flex-col gap-2", className), ...props, children: [_jsxs("button", { type: "button", "aria-expanded": isOpen, "aria-controls": panelId, onClick: toggle, className: cx("inline-flex min-h-6 items-center gap-1 self-start font-bold text-c2 text-sm transition-colors hover:text-c1", buttonClassName), children: [summary, _jsx("span", { "aria-hidden": "true", children: isOpen ? "▴" : "▾" })] }), _jsx("div", { id: panelId, hidden: !isOpen, className: panelClassName, children: children })] }));
 }

package/dist/components/basics/Prose.d.ts

@@ -1,11 +1,14 @@
 /**
  * @file src/components/basics/Prose.tsx
  * @desc Long-form typography for MDX, docs and legal text, styled with the osu!-web tokens.
- *       Styles the plain elements inside it (headings, links, lists, code, tables). The element
- *       that opens the block gets no top margin, so a leading heading sits flush.
+ *       Styles the plain elements inside it (headings, links, lists, code, tables, blockquotes).
+ *       The element that opens the block gets no top margin, so a leading heading sits flush. Any
+ *       `pre` at any depth (including one nested inside `li` or `blockquote`) gets Prose's fence
+ *       styles, except CodeBlock's own `pre` (`role="group"`, the `./mdx` subpath's fenced code
+ *       renderer), which keeps its own look untouched.
  * @author David @dvhsh (https://dvh.sh)
  * @created Wed Sep 23, 2026
- * @modified Thu Sep 24, 2026
+ * @modified Sat Oct 3, 2026
  */
 import type { ComponentProps } from "react";
 /** Every native `<div>` prop (including `ref`). */
@@ -13,8 +16,8 @@ export type ProseProps = ComponentProps<"div">;
 /**
  * @function Prose
  * @param props {ProseProps} native div props; children are the rendered Markdown or MDX
- * @returns {JSX.Element} a max-w-3xl `<div>` that styles the headings, links, lists, code and
- *          tables inside it. Its first child's top margin is zeroed (`[&>:first-child]:mt-0`),
- *          which outranks the h2 and h3 margins by specificity.
+ * @returns {JSX.Element} a max-w-3xl `<div>` that styles the headings, links, lists, code,
+ *          tables and blockquotes inside it. Its first child's top margin is zeroed
+ *          (`[&>:first-child]:mt-0`), which outranks the h2 and h3 margins by specificity.
  */
 export declare function Prose({ className, ...props }: ProseProps): import("react").JSX.Element;

package/dist/components/basics/Prose.js

@@ -3,10 +3,10 @@ import { cx } from "../../utils/cx.js";
 /**
  * @function Prose
  * @param props {ProseProps} native div props; children are the rendered Markdown or MDX
- * @returns {JSX.Element} a max-w-3xl `<div>` that styles the headings, links, lists, code and
- *          tables inside it. Its first child's top margin is zeroed (`[&>:first-child]:mt-0`),
- *          which outranks the h2 and h3 margins by specificity.
+ * @returns {JSX.Element} a max-w-3xl `<div>` that styles the headings, links, lists, code,
+ *          tables and blockquotes inside it. Its first child's top margin is zeroed
+ *          (`[&>:first-child]:mt-0`), which outranks the h2 and h3 margins by specificity.
  */
 export function Prose({ className, ...props }) {
-    return (_jsx("div", { className: cx("max-w-3xl text-c2 leading-relaxed [&>:first-child]:mt-0 [&_a:hover]:text-c1 [&_a]:text-h1 [&_a]:underline [&_code]:rounded [&_code]:bg-b4 [&_code]:px-1.5 [&_code]:py-0.5 [&_code]:text-[0.9em] [&_h2]:mt-10 [&_h2]:mb-3 [&_h2]:font-bold [&_h2]:text-2xl [&_h2]:text-c1 [&_h3]:mt-6 [&_h3]:mb-2 [&_h3]:font-bold [&_h3]:text-c1 [&_h3]:text-lg [&_hr]:my-8 [&_hr]:border-b3 [&_li]:mt-1 [&_ol]:list-decimal [&_ol]:pl-6 [&_p]:mt-3 [&_pre]:mt-3 [&_pre]:overflow-x-auto [&_pre]:rounded-md [&_pre]:bg-b6 [&_pre]:p-3 [&_pre]:text-sm [&_pre_code]:bg-transparent [&_pre_code]:p-0 [&_strong]:text-c1 [&_table]:mt-4 [&_table]:w-full [&_table]:text-sm [&_td]:border-b3 [&_td]:border-b [&_td]:px-2 [&_td]:py-1.5 [&_th]:border-b3 [&_th]:border-b [&_th]:px-2 [&_th]:py-1.5 [&_th]:text-left [&_th]:text-c1 [&_ul]:mt-3 [&_ul]:list-disc [&_ul]:pl-6", className), ...props }));
+    return (_jsx("div", { className: cx("max-w-3xl text-c2 leading-relaxed [&>:first-child]:mt-0 [&_a:hover]:text-c1 [&_a]:text-h1 [&_a]:underline [&_blockquote]:mt-3 [&_blockquote]:border-b2 [&_blockquote]:border-l-2 [&_blockquote]:pl-4 [&_blockquote]:text-c3 [&_code]:rounded [&_code]:bg-b4 [&_code]:px-1.5 [&_code]:py-0.5 [&_code]:text-[0.9em] [&_h2]:mt-10 [&_h2]:mb-3 [&_h2]:font-bold [&_h2]:text-2xl [&_h2]:text-c1 [&_h3]:mt-6 [&_h3]:mb-2 [&_h3]:font-bold [&_h3]:text-c1 [&_h3]:text-lg [&_hr]:my-8 [&_hr]:border-b3 [&_li]:mt-1 [&_ol]:list-decimal [&_ol]:pl-6 [&_p]:mt-3 [&_pre:not([role=group])]:mt-3 [&_pre:not([role=group])]:overflow-x-auto [&_pre:not([role=group])]:rounded-md [&_pre:not([role=group])]:bg-b6 [&_pre:not([role=group])]:p-3 [&_pre:not([role=group])]:text-sm [&_pre_code]:bg-transparent [&_pre_code]:p-0 [&_strong]:text-c1 [&_table]:mt-4 [&_table]:w-full [&_table]:text-sm [&_td]:border-b3 [&_td]:border-b [&_td]:px-2 [&_td]:py-1.5 [&_th]:border-b3 [&_th]:border-b [&_th]:px-2 [&_th]:py-1.5 [&_th]:text-left [&_th]:text-c1 [&_ul]:mt-3 [&_ul]:list-disc [&_ul]:pl-6", className), ...props }));
 }

package/dist/components/forms/Checkbox.d.ts

@@ -6,7 +6,7 @@
  *       hint and error.
  * @author David @dvhsh (https://dvh.sh)
  * @created Wed Sep 23, 2026
- * @modified Mon Sep 28, 2026
+ * @modified Sat Oct 3, 2026
  */
 import type { ComponentProps } from "react";
 import { type FieldProps } from "./FieldFrame.js";

package/dist/components/forms/Checkbox.js

@@ -9,5 +9,7 @@ import { FieldError, fieldControlProps, hintId } from "./FieldFrame.js";
  */
 export function Checkbox({ id, label, hint, error, wrapperClassName, className, "aria-describedby": describedBy, "aria-invalid": invalid, "aria-labelledby": labelledBy, ...props }) {
     const labelId = `${id}-label`;
-    return (_jsxs("div", { className: cx("flex flex-col gap-1", wrapperClassName), children: [_jsxs("label", { htmlFor: id, className: "flex items-start gap-2 text-sm", children: [_jsx("input", { ...props, type: "checkbox", ...fieldControlProps({ id, hint, error, describedBy, invalid }), "aria-labelledby": labelledBy ? `${labelId} ${labelledBy}` : labelId, className: cx("mt-1 accent-h1", className) }), _jsxs("span", { children: [_jsx("span", { id: labelId, className: "font-bold text-c1", children: label }), hint ? (_jsxs("span", { className: "text-c3", children: [" · ", _jsx("span", { id: hintId(id), children: hint })] })) : null] })] }), _jsx(FieldError, { id: id, error: error })] }));
+    return (_jsxs("div", { className: cx("flex flex-col gap-1", wrapperClassName), children: [_jsxs("label", { htmlFor: id, className: "flex items-start gap-2 text-sm", children: [_jsx("input", { ...props, type: "checkbox", ...fieldControlProps({ id, hint, error, describedBy, invalid }), "aria-labelledby": labelledBy ? `${labelId} ${labelledBy}` : labelId, 
+                        // 24px, the WCAG 2.2 target size; -mt-0.5 centers it on the first text-sm line.
+                        className: cx("-mt-0.5 size-6 shrink-0 accent-h1", className) }), _jsxs("span", { children: [_jsx("span", { id: labelId, className: "font-bold text-c1", children: label }), hint ? (_jsxs("span", { className: "text-c3", children: [" · ", _jsx("span", { id: hintId(id), children: hint })] })) : null] })] }), _jsx(FieldError, { id: id, error: error })] }));
 }

package/dist/components/forms/RadioGroup.js

@@ -27,6 +27,8 @@ export function RadioGroup({ label, options, name, value, defaultValue, onChange
                 const optionId = `${id}-${i}`;
                 return (_jsxs("label", { className: "flex items-start gap-2 text-sm", children: [_jsx("input", { type: "radio", id: optionId, name: name ?? id, value: option.value, ...(value === undefined
                                 ? { defaultChecked: option.value === defaultValue }
-                                : { checked: option.value === value }), disabled: option.disabled, required: required, "aria-labelledby": `${optionId}-label`, "aria-describedby": option.hint ? hintId(optionId) : undefined, onChange: () => onChange?.(option.value), className: "mt-1 accent-h1" }), _jsxs("span", { children: [_jsx("span", { id: `${optionId}-label`, className: "font-bold text-c1", children: option.label }), option.hint ? (_jsxs("span", { className: "text-c3", children: [" · ", _jsx("span", { id: hintId(optionId), children: option.hint })] })) : null] })] }, option.value));
+                                : { checked: option.value === value }), disabled: option.disabled, required: required, "aria-labelledby": `${optionId}-label`, "aria-describedby": option.hint ? hintId(optionId) : undefined, onChange: () => onChange?.(option.value), 
+                            // 24px, the WCAG 2.2 target size; -mt-0.5 centers it on the first text-sm line.
+                            className: "-mt-0.5 size-6 shrink-0 accent-h1" }), _jsxs("span", { children: [_jsx("span", { id: `${optionId}-label`, className: "font-bold text-c1", children: option.label }), option.hint ? (_jsxs("span", { className: "text-c3", children: [" · ", _jsx("span", { id: hintId(optionId), children: option.hint })] })) : null] })] }, option.value));
             }), hint ? (_jsx("div", { id: hintId(id), className: "text-c4 text-xs", children: hint })) : null, _jsx(FieldError, { id: id, error: error })] }));
 }

package/dist/components/mdx/Callout.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @file src/components/mdx/Callout.tsx
+ * @desc A labelled aside for MDX prose (note, tip, warning): a left-border panel with an icon and
+ *       a bold label, rendered by MdxBlockquote for a GitHub-style `> [!NOTE]` blockquote, or
+ *       usable directly in hand-written MDX.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import type { ComponentProps, ReactNode } from "react";
+import type { CalloutType } from "../../remark/callouts.js";
+export type { CalloutType };
+/** Every native `<div>` prop except `title` (replaced by the callout's own label slot). */
+export type CalloutProps = Omit<ComponentProps<"div">, "title"> & {
+    type?: CalloutType | undefined;
+    title?: ReactNode;
+};
+/**
+ * @function Callout
+ * @param props {CalloutProps} the callout type (default "note"), an optional title replacing
+ *        the type's default label, native div props and children
+ * @returns {JSX.Element} a bordered, labelled panel announced as a note
+ */
+export declare function Callout({ type, title, className, children, ...props }: CalloutProps): import("react").JSX.Element;

package/dist/components/mdx/Callout.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from "../../utils/cx.js";
+const LABEL = { note: "Note", tip: "Tip", warning: "Warning" };
+const BORDER = {
+    note: "border-h1",
+    tip: "border-c2",
+    warning: "border-h2",
+};
+const ICON = {
+    note: "M12 2a10 10 0 1 0 0 20 10 10 0 0 0 0-20Zm1 15h-2v-6h2Zm0-8h-2V7h2Z",
+    tip: "M9 21h6v-2H9Zm3-19a7 7 0 0 0-4 12.7V17h8v-2.3A7 7 0 0 0 12 2Z",
+    warning: "M1 21h22L12 2Zm12-3h-2v-2h2Zm0-4h-2v-4h2Z",
+};
+/**
+ * @function Callout
+ * @param props {CalloutProps} the callout type (default "note"), an optional title replacing
+ *        the type's default label, native div props and children
+ * @returns {JSX.Element} a bordered, labelled panel announced as a note
+ */
+export function Callout({ type = "note", title, className, children, ...props }) {
+    return (_jsxs("div", { role: "note", className: cx("mt-4 rounded-md border-l-4 bg-b5 px-4 py-3 text-c2", BORDER[type], className), ...props, children: [_jsxs("p", { className: "mt-0! flex items-center gap-2 font-bold text-c1", children: [_jsx("svg", { "aria-hidden": "true", viewBox: "0 0 24 24", className: "size-4 shrink-0 fill-current", children: _jsx("path", { d: ICON[type] }) }), title ?? LABEL[type]] }), _jsx("div", { className: "[&>:first-child]:mt-1", children: children })] }));
+}

package/dist/components/mdx/CodeBlock.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @file src/components/mdx/CodeBlock.tsx
+ * @desc A fenced code block rendered with Shiki highlighting when the app registered it (by
+ *       importing `@haruhimemoe/ui/shiki`) and the language is one of the bundled set, plain text
+ *       otherwise. Async so it can await the lazily-loaded highlighter from highlighter.ts.
+ *       Server-safe: the only client piece is the copy button (CodeCopyButton).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import type { ComponentProps } from "react";
+/** The code (any line endings, trailing newline optional), language, title, highlighted lines
+ *  and every other native `<div>` prop (spread onto the wrapper). */
+export type CodeBlockProps = Omit<ComponentProps<"div">, "title" | "children"> & {
+    code: string;
+    lang?: string | undefined;
+    title?: string | undefined;
+    highlight?: readonly number[] | undefined;
+};
+/**
+ * @function CodeBlock
+ * @param props {CodeBlockProps} the code, optional language, title, highlighted line numbers and
+ *        wrapper class
+ * @returns {Promise<JSX.Element>} a header (name and copy button) over a highlighted `<pre>`
+ */
+export declare function CodeBlock({ code, lang, title, highlight, className, ...rest }: CodeBlockProps): Promise<import("react").JSX.Element>;