From 7277b95aa05002101b62f81eeae121125ede4abf Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 09:06:47 -0700
Subject: [PATCH 01/31] =?UTF-8?q?docs:=20spec=20for=20components=20SP1=20?=
 =?UTF-8?q?=E2=80=94=20the=20contract,=20and=20Button=20/=20IconButton?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Opens the component-kit program: every control in the grid rebuilt on a
pre-built, accessible, styleable kit a consumer can also replace per
component type. Four sub-projects by component type; this spec is the first
and settles the contract the rest inherit — placement in @pretable/react,
one `components` slot per type with a `role` in the props, the house styling
channel (attributes + tokens + className passthrough), and context as the
plumbing because popovers are portalled.

Proven against the grid's twelve plain push-buttons, which keep their
existing data attributes so nothing that identifies a button today stops
identifying it. Menu items, checkboxes, tabs and the twisty are roles that
happen to use <button>, and wait for their own components.

Also records the decision that the Excel theme stays light-only.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 ...2026-09-04-components-sp1-button-design.md | 240 ++++++++++++++++++
 1 file changed, 240 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-09-04-components-sp1-button-design.md

diff --git a/docs/superpowers/specs/2026-09-04-components-sp1-button-design.md b/docs/superpowers/specs/2026-09-04-components-sp1-button-design.md
new file mode 100644
index 00000000..cd307851
--- /dev/null
+++ b/docs/superpowers/specs/2026-09-04-components-sp1-button-design.md
@@ -0,0 +1,240 @@
+# Components SP1: the contract, and Button / IconButton
+
+Date: 2026-09-04
+Status: approved, ready for planning
+
+## Purpose
+
+pretable renders 40 `<button>` elements, 15 `<input>`s, 9 native `<select>`s and
+a `<textarea>` with no shared component behind them. The selects wear native
+chrome inside an otherwise designed surface; the buttons carry their looks as
+per-site CSS. The program this spec opens replaces all of them with a
+pre-built, accessible, styleable component kit that a consumer can also replace
+per component type with their own.
+
+This is the first of four sub-projects. It settles the contract every later
+component inherits — where components live, how a consumer replaces one, how a
+consumer styles one, what a component guarantees — and proves it with the
+simplest component, against the grid's own push-buttons.
+
+The kit is the product; replacement is the escape hatch. Design effort goes to
+what the components look like and how they behave, and the override contract
+follows what those components need.
+
+## Decisions (each confirmed with the user)
+
+1. **Pretable UI kit first.** A designed, accessible set most consumers ship
+   as-is. Not primarily an integration seam, not a standalone library.
+2. **End state: every control in the grid rebuilt on the kit.** Reached in
+   four sub-projects, by component type:
+   - SP1 (this spec): the contract + Button / IconButton.
+   - SP2: Select, and the Listbox/Popover primitive it needs — the nine native
+     selects.
+   - SP3: TextInput / Textarea / Checkbox — the remaining inputs.
+   - SP4: docs, theming page, accessibility sweep.
+3. **Override shape: one slot per component type, props carry a role.**
+   `components={{ Button: MyButton }}` replaces every button in the grid. Ours
+   passes a `role` among the props, so a consumer who wants one site treated
+   differently branches on it in their own component. No per-site public
+   names.
+4. **Styling: attributes + tokens, `className`/`style` passthrough.** The house
+   pattern `PretableBadge` already follows. No `classNames` map, no unstyled
+   build, no variant-as-styling-channel.
+5. **SP1's Button covers plain push-buttons only.** Menu items, checkboxes,
+   the tab, the twisty and header cells are roles that happen to use the
+   `<button>` element; each waits for its own component.
+6. **Plumbing: context, resolved once at the surface.** pretable portals its
+   popovers into `document.body`; context crosses portals, props do not, and
+   the popovers are where overrides matter most.
+7. **Excel theme is light-only, and stays so for now.** Recorded here because
+   it came out of the same conversation; not SP1 work.
+
+## Placement
+
+Components live in `packages/react/src/components/`, one file per component,
+exported from `@pretable/react`'s public API alongside `PretableBadge`,
+`PretableDelta`, `PretableEntity` and `PretableStatus`. Same package, same
+api-extractor gate, same `Pretable*` naming. No new package: a second build,
+report and version to keep in step buys nothing while the grid is the only
+consumer.
+
+## The components
+
+Two components, one contract.
+
+```ts
+export type PretableButtonVariant = "outline" | "link";
+
+/** The twelve sites SP1 migrates — each name is the site's existing attribute suffix. */
+export type PretableBuiltInButtonRole =
+  | "filter-add"
+  | "add-group"
+  | "expand-all"
+  | "collapse-all"
+  | "filter-clear"
+  | "tool-reset"
+  | "filter-funnel"
+  | "column-menu-button"
+  | "tool-row-menu-button"
+  | "chip-remove"
+  | "filter-row-remove"
+  | "tool-group-remove";
+
+/** Built-in role names, open to strings the grid does not know yet. */
+export type PretableButtonRole = PretableBuiltInButtonRole | (string & {});
+
+export interface PretableButtonProps extends Omit<
+  ButtonHTMLAttributes<HTMLButtonElement>,
+  "type"
+> {
+  /** The two labelled looks the grid uses today. Default: "outline". */
+  variant?: PretableButtonVariant;
+  /** Where in the grid this button is. Lands as data-pretable-role. */
+  role?: PretableButtonRole;
+}
+
+export interface PretableIconButtonProps extends Omit<
+  ButtonHTMLAttributes<HTMLButtonElement>,
+  "type" | "aria-label"
+> {
+  /** REQUIRED. An icon-only button has no other accessible name. */
+  "aria-label": string;
+  role?: PretableButtonRole;
+}
+
+export const PretableButton: ForwardRefExoticComponent<
+  PretableButtonProps & RefAttributes<HTMLButtonElement>
+>;
+export const PretableIconButton: ForwardRefExoticComponent<
+  PretableIconButtonProps & RefAttributes<HTMLButtonElement>
+>;
+```
+
+Guarantees, for both:
+
+- Renders `<button type="button">`, always. Every grid button is `type="button"`
+  today, and a stray submit inside a consumer's `<form>` is a real bug class,
+  so `type` is not a prop.
+- `className` and `style` pass through and **merge** with ours; they never
+  replace the component's own attributes.
+- `disabled` gets the standard treatment established in #573:
+  `--pretable-text-dim`, `cursor: default`, and every hover rule guarded with
+  `:not(:disabled)`. Under forced colours, `GrayText`.
+- The DOM carries `data-pretable-button` or `data-pretable-icon-button`,
+  `data-pretable-variant` (Button only), and `data-pretable-role` when a role
+  is given. This is the styling channel: those attributes and the
+  `--pretable-*` tokens, nothing new.
+- `forwardRef` reaches the `<button>` node. The tool panel already needs
+  button nodes for focus return; a component that hid them would break it.
+- Focus ring is the shared `outline: 2px solid var(--pretable-focus-ring)` at
+  `-2px`, as every ring in `grid.css` is.
+
+IconButton makes the accessible name a **type error** to omit. That converts a
+WCAG failure the grid can currently ship into a compile failure, and is the one
+place SP1 makes something impossible rather than merely wrong.
+
+Not props: `size`, `tone`, `loading`, `icon` slots. None of the twelve sites
+needs them; each is added when a site does.
+
+## The override contract
+
+```ts
+export interface PretableComponents {
+  Button?: ComponentType<PretableButtonProps>;
+  IconButton?: ComponentType<PretableIconButtonProps>;
+}
+
+// on PretableSurfaceProps (and through it, PretableProps):
+components?: PretableComponents;
+```
+
+- A replacement receives **exactly what ours receives** — the same props,
+  `role` included — so a consumer's component is a drop-in, and can branch on
+  `role` to treat one site differently.
+- `PretableButtonRole` is the union of built-in names plus `(string & {})`,
+  the same shape as `PretableToolPanelSectionId`: autocomplete for ours, no
+  type error when the grid gains a role.
+- The **props** are stable public API. The **set of roles** is documented but
+  additive: a new grid button may introduce a new role without a major bump.
+- pretable never depends on a replacement's DOM shape. Anything the grid needs
+  from a button node — focus return, popover anchoring — goes through the
+  `ref`, which a replacement must forward. This is the one obligation on the
+  consumer, and the docs say so.
+
+### Plumbing
+
+`PretableSurface` merges `components` over the built-in defaults, memoises the
+result keyed on the identity of each value (so an inline object literal does
+not re-render every button per keystroke), and publishes it on a React
+context. Call sites read `const { Button } = usePretableComponents()` — an
+internal hook, not exported. The default context value is the built-in map, so
+a component rendered outside any surface still works.
+
+## Migration of the call sites
+
+Twelve sites become kit components; two stay out on purpose.
+
+| becomes                    | sites                                                                                                                  |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `Button variant="outline"` | `filter-add` (×2), `add-group`, `expand-all`, `collapse-all`                                                           |
+| `Button variant="link"`    | `filter-clear`, `tool-reset`                                                                                           |
+| `IconButton`               | `filter-funnel`, `column-menu-button`, `tool-row-menu-button`, `chip-remove`, `filter-row-remove`, `tool-group-remove` |
+| **stays**                  | `filter-join` (a pressed-state toggle, not a push-button), `pane-resize` (a separator handle)                          |
+
+Each site **keeps its existing `data-pretable-*` attribute**, passed through as
+a prop. Every selector in `grid.css`, every e2e locator and every consumer
+stylesheet keyed on `[data-pretable-filter-clear]` keeps working unchanged.
+That is what makes the migration safe to land in one PR: nothing that
+identifies a button today stops identifying it. The role name for each site is
+its existing attribute suffix (`filter-clear`, `tool-reset`, …), so there is
+one vocabulary, not two.
+
+What moves is the **shared look**. The four bordered actions carry a
+five-selector rule list in `grid.css` for the same border, radius, padding and
+hover; it collapses onto `[data-pretable-button][data-pretable-variant="outline"]`
+and the site rules shrink to what is genuinely site-specific. The icon
+buttons' shared 18px box collapses the same way onto
+`[data-pretable-icon-button]`. `grid.css` gets smaller.
+
+The pixel must not move. Before touching a site, its computed box, colours,
+hover and focus are recorded; after, they are re-measured. Any difference is a
+finding, not an acceptable drift.
+
+## Testing
+
+- **Component tests** (jsdom, `packages/react/src/__tests__/`): `type="button"`
+  always; attributes and `data-pretable-role` land; `className`/`style` merge
+  rather than replace; the ref reaches the node; `disabled` is reflected.
+- **Type tests** (`type-tests/`): omitting `aria-label` on IconButton fails to
+  compile; `type` is not accepted on either; `role` accepts an unknown string.
+- **Override tests**: `components={{ Button }}` on the surface renders the
+  replacement at a known site with the right `role`; a stable map yields a
+  stable context value (re-rendering with the same map does not remount
+  buttons); a replacement inside a **portalled** menu renders — the test that
+  proves the context-over-props decision.
+- **CSS guards** (`css-cascade.test.ts`): the variant rules exist and carry
+  `:hover:not(:disabled)`; the disabled treatment covers the new attributes;
+  the collapsed site rules do not come back. Mutation-tested, like the rest of
+  that file.
+- **Browser**: a `/fixtures/components` page with an override, asserted in the
+  website e2e; the hero re-measured for all three looks; **and
+  `pnpm bench:e2e`** — leaving the bench suite out is what broke #577.
+- **Accessibility**: every migrated site keeps its accessible name, asserted by
+  `getByRole("button", { name })`.
+
+## Docs and API surface
+
+- A "Components" docs page covering Button and IconButton, leading with a live
+  example per the examples-first standard.
+- The `components` prop on the surface reference page.
+- Both tables registered with the api-surface guard, which fails closed on an
+  unregistered table.
+- `pnpm build` then `pnpm api`; a **minor** changeset for `@pretable/react`
+  (new public API) and a patch for `@pretable/ui`.
+
+## Out of scope
+
+Menu items, checkboxes, tabs, the twisty, header cells, Select and every
+input — each waits for its own component and sub-project. No `size`, `tone`,
+`loading` or icon-slot props. No `classNames` map, no unstyled build, no
+per-site override names. No change to the Excel theme.

From 211343b48e4fd6cd8a5d1bd471bb115aef1e71e6 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 09:48:24 -0700
Subject: [PATCH 02/31] =?UTF-8?q?docs(spec):=20components=20SP1=20?=
 =?UTF-8?q?=E2=80=94=20ghost/link=20variants,=20and=20`site`=20not=20`role?=
 =?UTF-8?q?`?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two corrections from reading the code the plan has to match. The four
labelled actions are `border: 0; background: transparent` with a hover tint —
a ghost button, not an outlined one; the earlier survey read `border: 0` as
a border. And `role` cannot be the prop: it is the ARIA attribute on every
button, so a replacement spreading `role="filter-clear"` onto a <button>
would emit invalid ARIA. The prop is `site`, which is what the spec already
defined it to mean.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 ...2026-09-04-components-sp1-button-design.md | 64 +++++++++++--------
 1 file changed, 36 insertions(+), 28 deletions(-)

diff --git a/docs/superpowers/specs/2026-09-04-components-sp1-button-design.md b/docs/superpowers/specs/2026-09-04-components-sp1-button-design.md
index cd307851..dc748ae5 100644
--- a/docs/superpowers/specs/2026-09-04-components-sp1-button-design.md
+++ b/docs/superpowers/specs/2026-09-04-components-sp1-button-design.md
@@ -1,7 +1,8 @@
 # Components SP1: the contract, and Button / IconButton
 
 Date: 2026-09-04
-Status: approved, ready for planning
+Status: approved, ready for planning (variant names and the `site` prop
+corrected during planning — see the plan's header)
 
 ## Purpose
 
@@ -32,9 +33,9 @@ follows what those components need.
      selects.
    - SP3: TextInput / Textarea / Checkbox — the remaining inputs.
    - SP4: docs, theming page, accessibility sweep.
-3. **Override shape: one slot per component type, props carry a role.**
+3. **Override shape: one slot per component type, props carry the site.**
    `components={{ Button: MyButton }}` replaces every button in the grid. Ours
-   passes a `role` among the props, so a consumer who wants one site treated
+   passes a `site` among the props, so a consumer who wants one place treated
    differently branches on it in their own component. No per-site public
    names.
 4. **Styling: attributes + tokens, `className`/`style` passthrough.** The house
@@ -63,10 +64,10 @@ consumer.
 Two components, one contract.
 
 ```ts
-export type PretableButtonVariant = "outline" | "link";
+export type PretableButtonVariant = "ghost" | "link";
 
 /** The twelve sites SP1 migrates — each name is the site's existing attribute suffix. */
-export type PretableBuiltInButtonRole =
+export type PretableBuiltInButtonSite =
   | "filter-add"
   | "add-group"
   | "expand-all"
@@ -80,17 +81,22 @@ export type PretableBuiltInButtonRole =
   | "filter-row-remove"
   | "tool-group-remove";
 
-/** Built-in role names, open to strings the grid does not know yet. */
-export type PretableButtonRole = PretableBuiltInButtonRole | (string & {});
+/** Built-in site names, open to strings the grid does not know yet. */
+export type PretableButtonSite = PretableBuiltInButtonSite | (string & {});
 
 export interface PretableButtonProps extends Omit<
   ButtonHTMLAttributes<HTMLButtonElement>,
   "type"
 > {
-  /** The two labelled looks the grid uses today. Default: "outline". */
+  /** The two labelled looks the grid uses today. Default: "ghost". */
   variant?: PretableButtonVariant;
-  /** Where in the grid this button is. Lands as data-pretable-role. */
-  role?: PretableButtonRole;
+  /**
+   * Where in the grid this button is. Lands as data-pretable-site. Named
+   * `site`, not `role`: `role` is the ARIA attribute on every button, and a
+   * replacement that spread `role="filter-clear"` onto a <button> would emit
+   * invalid ARIA.
+   */
+  site?: PretableButtonSite;
 }
 
 export interface PretableIconButtonProps extends Omit<
@@ -99,7 +105,7 @@ export interface PretableIconButtonProps extends Omit<
 > {
   /** REQUIRED. An icon-only button has no other accessible name. */
   "aria-label": string;
-  role?: PretableButtonRole;
+  site?: PretableButtonSite;
 }
 
 export const PretableButton: ForwardRefExoticComponent<
@@ -121,7 +127,7 @@ Guarantees, for both:
   `--pretable-text-dim`, `cursor: default`, and every hover rule guarded with
   `:not(:disabled)`. Under forced colours, `GrayText`.
 - The DOM carries `data-pretable-button` or `data-pretable-icon-button`,
-  `data-pretable-variant` (Button only), and `data-pretable-role` when a role
+  `data-pretable-variant` (Button only), and `data-pretable-site` when a site
   is given. This is the styling channel: those attributes and the
   `--pretable-*` tokens, nothing new.
 - `forwardRef` reaches the `<button>` node. The tool panel already needs
@@ -149,13 +155,13 @@ components?: PretableComponents;
 ```
 
 - A replacement receives **exactly what ours receives** — the same props,
-  `role` included — so a consumer's component is a drop-in, and can branch on
-  `role` to treat one site differently.
-- `PretableButtonRole` is the union of built-in names plus `(string & {})`,
+  `site` included — so a consumer's component is a drop-in, and can branch on
+  `site` to treat one place differently.
+- `PretableButtonSite` is the union of built-in names plus `(string & {})`,
   the same shape as `PretableToolPanelSectionId`: autocomplete for ours, no
-  type error when the grid gains a role.
-- The **props** are stable public API. The **set of roles** is documented but
-  additive: a new grid button may introduce a new role without a major bump.
+  type error when the grid gains a site.
+- The **props** are stable public API. The **set of sites** is documented but
+  additive: a new grid button may introduce a new site without a major bump.
 - pretable never depends on a replacement's DOM shape. Anything the grid needs
   from a button node — focus return, popover anchoring — goes through the
   `ref`, which a replacement must forward. This is the one obligation on the
@@ -185,16 +191,18 @@ Each site **keeps its existing `data-pretable-*` attribute**, passed through as
 a prop. Every selector in `grid.css`, every e2e locator and every consumer
 stylesheet keyed on `[data-pretable-filter-clear]` keeps working unchanged.
 That is what makes the migration safe to land in one PR: nothing that
-identifies a button today stops identifying it. The role name for each site is
+identifies a button today stops identifying it. The site name for each is
 its existing attribute suffix (`filter-clear`, `tool-reset`, …), so there is
 one vocabulary, not two.
 
-What moves is the **shared look**. The four bordered actions carry a
-five-selector rule list in `grid.css` for the same border, radius, padding and
-hover; it collapses onto `[data-pretable-button][data-pretable-variant="outline"]`
-and the site rules shrink to what is genuinely site-specific. The icon
-buttons' shared 18px box collapses the same way onto
-`[data-pretable-icon-button]`. `grid.css` gets smaller.
+What moves is the **shared look**. The four ghost actions carry a
+four-selector rule list in `grid.css` for the same 24px box, radius, padding,
+accent ink and hover tint; it collapses onto
+`[data-pretable-button][data-pretable-variant="ghost"]` and the site rules
+shrink to what is genuinely site-specific. The icon buttons share everything
+but their size — 14px, 18px and 24px boxes exist — so the shared
+`[data-pretable-icon-button]` rule carries the box minus its dimensions and
+each site keeps its size, its hover and its reveal. `grid.css` gets smaller.
 
 The pixel must not move. Before touching a site, its computed box, colours,
 hover and focus are recorded; after, they are re-measured. Any difference is a
@@ -203,12 +211,12 @@ finding, not an acceptable drift.
 ## Testing
 
 - **Component tests** (jsdom, `packages/react/src/__tests__/`): `type="button"`
-  always; attributes and `data-pretable-role` land; `className`/`style` merge
+  always; attributes and `data-pretable-site` land; `className`/`style` merge
   rather than replace; the ref reaches the node; `disabled` is reflected.
 - **Type tests** (`type-tests/`): omitting `aria-label` on IconButton fails to
-  compile; `type` is not accepted on either; `role` accepts an unknown string.
+  compile; `type` is not accepted on either; `site` accepts an unknown string.
 - **Override tests**: `components={{ Button }}` on the surface renders the
-  replacement at a known site with the right `role`; a stable map yields a
+  replacement at a known site with the right `site`; a stable map yields a
   stable context value (re-rendering with the same map does not remount
   buttons); a replacement inside a **portalled** menu renders — the test that
   proves the context-over-props decision.

From cf68a5bbed9ddf5ab69474de4ecfa82e10757e12 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 09:54:52 -0700
Subject: [PATCH 03/31] docs: implementation plan for components SP1

Fifteen tasks, TDD throughout: the pixel baseline first, the two components,
the type contract, the context, the surface wiring with the override tests
landing red, the component rules and a site-rule guard that stays red until
the twelve sites migrate and their CSS collapses, the public API, the pixel
re-measure, docs with registered tables, the browser proof through the
portalled dialog, and a verification step that runs the bench suite.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../plans/2026-09-04-components-sp1-button.md | 2416 +++++++++++++++++
 1 file changed, 2416 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-09-04-components-sp1-button.md

diff --git a/docs/superpowers/plans/2026-09-04-components-sp1-button.md b/docs/superpowers/plans/2026-09-04-components-sp1-button.md
new file mode 100644
index 00000000..4442495b
--- /dev/null
+++ b/docs/superpowers/plans/2026-09-04-components-sp1-button.md
@@ -0,0 +1,2416 @@
+# Components SP1: Button / IconButton Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Ship `PretableButton` and `PretableIconButton`, the `components` override slot that lets a consumer replace either everywhere, and rebuild the grid's twelve plain push-buttons on them — with no pixel moving.
+
+**Architecture:** Two `forwardRef` components in `packages/react/src/components/`, styled by `grid.css` through `data-pretable-button` / `data-pretable-icon-button` / `data-pretable-variant` / `data-pretable-site`. `PretableSurface` takes `components`, resolves it over the defaults once (memoised on value identity), and publishes it on a React context; call sites read `usePretableComponents()`. Context, not props, because the popovers are portalled to `document.body`. Each migrated site keeps its existing `data-pretable-*` attribute, so every selector, locator and consumer stylesheet keyed on it keeps working; the shared look moves out of the site rules into the component rules.
+
+**Tech Stack:** React 18/19 (`forwardRef` — React 18 has no ref-as-prop), TypeScript, vitest + testing-library (jsdom), Playwright (website e2e + bench), api-extractor, changesets. Vanilla CSS only in `packages/*`.
+
+**Spec:** `docs/superpowers/specs/2026-09-04-components-sp1-button-design.md`. Two names differ from the spec's first draft, corrected before this plan: the variants are `ghost` | `link` (the labelled actions are `border: 0` + hover tint, not outlined), and the placement prop is `site`, not `role` (`role` is the ARIA attribute on every button).
+
+**Repo rules that bite here** (from memory and this thread):
+
+- Run every verification from the **repo root**; a shell left in `apps/website` runs that app's scripts and reports green for the wrong thing.
+- `pnpm bench:e2e` is a separate Playwright project from the website e2e. Run both.
+- `pnpm build` **before** `pnpm api` — a stale `dist/` silently strips exports.
+- The docs api-surface guard fails closed on an unregistered member table.
+- Never `git stash`; never touch `~/repos/pretable` (the main checkout).
+- Commit attribution line: `Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>`.
+
+---
+
+## File structure
+
+**Create**
+
+| file | responsibility |
+| --- | --- |
+| `packages/react/src/components/button.tsx` | `PretableButton`, `PretableIconButton`, their props and the `site` / variant types |
+| `packages/react/src/components/context.ts` | `PretableComponents`, the resolved map, the context, `usePretableComponents`, `useResolvedComponents` |
+| `packages/react/src/__tests__/components-button.test.tsx` | component behaviour in jsdom |
+| `packages/react/src/__tests__/components-override.test.tsx` | the `components` prop through the surface, incl. the portalled case |
+| `type-tests/react/components-button.types.tsx` | the compile-time contract |
+| `apps/website/content/docs/grid/components.mdx` | the docs page |
+| `apps/website/content/examples/components-button/{example.ts,demo.tsx,ComponentsGrid.tsx,BrandButton.tsx,data.ts}` | the live example |
+| `apps/website/app/fixtures/components/page.tsx` | the e2e fixture with both slots replaced |
+| `apps/website/e2e/components.spec.ts` | browser proof: replacement lands in a portalled dialog |
+| `.changeset/components-sp1-button.md` | minor `@pretable/react`, patch `@pretable/ui` |
+
+**Modify**
+
+| file | change |
+| --- | --- |
+| `packages/react/src/public_api.ts` | export the components and types |
+| `packages/react/src/pretable-surface.tsx` | `components` prop; resolve; provide on both return paths |
+| `packages/react/src/pretable.tsx` | forward `components` on `PretableBaseProps` |
+| `packages/react/src/tool-panel/filters/FiltersSection.tsx` | 2× `filter-add` → `Button` |
+| `packages/react/src/tool-panel/grouping/GroupingSection.tsx` | `add-group`, `expand-all`, `collapse-all` → `Button`; `tool-group-remove` → `IconButton` |
+| `packages/react/src/filter-menu/FilterMenu.tsx` | `filter-clear` → `Button variant="link"` |
+| `packages/react/src/tool-panel/ColumnsSection.tsx` | `tool-reset` → `Button variant="link"`; `tool-row-menu-button` → `IconButton` |
+| `packages/react/src/filter-menu/FunnelButton.tsx` | → `IconButton` |
+| `packages/react/src/column-menu/MenuButton.tsx` | → `IconButton` |
+| `packages/react/src/group-panel/GroupPanel.tsx` | `chip-remove` → `IconButton` |
+| `packages/react/src/tool-panel/filters/FilterRow.tsx` | `filter-row-remove` → `IconButton` |
+| `packages/ui/grid.css` | component rules; collapse the site rules they replace |
+| `packages/ui/src/__tests__/css-cascade.test.ts` | guards for the above |
+| `apps/website/app/docs/_nav.ts` | nav entry |
+| `apps/website/lib/docs/__tests__/docs-api-surface.test.ts` | register the page's tables |
+| `packages/react/react.api.md` | regenerated by `pnpm api` |
+
+---
+
+### Task 1: Record the pixels before anything moves
+
+The spec's definition of done is "the pixel must not move". That needs a baseline taken **before** Task 2.
+
+**Files:**
+
+- Create (scratch, not committed): `<scratchpad>/measure-buttons.mjs`
+- Output: `<scratchpad>/buttons-before.json`
+
+- [ ] **Step 1: Build and serve the current tree**
+
+Run from the repo root:
+
+```bash
+pnpm build && (cd apps/website && pnpm exec next start -p 3117 > /tmp/pt-server.log 2>&1 &) && sleep 6 && curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3117/
+```
+
+Expected: `BUILD` succeeds and the last line is `200`.
+
+- [ ] **Step 2: Write the measurement script**
+
+It records, for every one of the twelve sites, the computed longhands that define its look at rest and under focus. Hover is not scripted — `page.hover` on a button whose site rule reveals it on header-row hover is timing-sensitive; the hover declarations are guarded in CSS instead (Task 7).
+
+```js
+// <scratchpad>/measure-buttons.mjs — run from apps/website so @playwright/test resolves
+import { chromium } from "@playwright/test";
+import fs from "node:fs";
+
+const OUT = process.argv[2];
+const PROPS = [
+  "display", "alignItems", "justifyContent", "gap", "width", "height",
+  "paddingTop", "paddingRight", "paddingBottom", "paddingLeft",
+  "borderTopWidth", "borderRadius", "backgroundColor", "backgroundImage",
+  "color", "fontSize", "fontFamily", "lineHeight", "cursor", "opacity",
+  "position", "flex", "alignSelf",
+];
+
+const browser = await chromium.launch();
+const page = await browser.newPage({ viewport: { width: 1280, height: 900 } });
+
+const read = (selector) =>
+  page.evaluate(({ selector, PROPS }) => {
+    const el = document.querySelector(selector);
+    if (!el) return null;
+    const at = (s) => Object.fromEntries(PROPS.map((p) => [p, s[p]]));
+    const rest = at(getComputedStyle(el));
+    el.focus();
+    const f = getComputedStyle(el);
+    const focus = { outline: f.outline, outlineOffset: f.outlineOffset };
+    el.blur();
+    const r = el.getBoundingClientRect();
+    return { rest, focus, box: { w: Math.round(r.width), h: Math.round(r.height) } };
+  }, { selector, PROPS });
+
+const result = {};
+
+// Hero: header buttons, the tool panel's three sections, the filter dialog.
+await page.goto("http://localhost:3117/", { waitUntil: "networkidle" });
+await page.waitForSelector('[data-pretable-hydrated="true"]');
+const calm = page.getByRole("button", { name: /calm/i });
+if (await calm.count()) await calm.first().click();
+await page.hover("[data-pretable-header-cell]");
+result["filter-funnel"] = await read("[data-pretable-filter-funnel]");
+result["column-menu-button"] = await read("[data-pretable-column-menu-button]");
+
+await page.locator("[data-pretable-filter-funnel]").first().click();
+result["filter-clear"] = await read("[data-pretable-filter-clear]");
+await page.keyboard.press("Escape");
+
+await page.locator("[data-pretable-tool-tab]").nth(0).click(); // columns
+result["tool-reset"] = await read("[data-pretable-tool-reset]");
+result["tool-row-menu-button"] = await read("[data-pretable-tool-row-menu-button]");
+await page.locator("[data-pretable-tool-tab]").nth(1).click(); // filters
+await page.locator("[data-pretable-filter-add]").first().click();
+result["filter-add"] = await read("[data-pretable-filter-add]");
+result["filter-row-remove"] = await read("[data-pretable-filter-row-remove]");
+await page.locator("[data-pretable-tool-tab]").nth(2).click(); // grouping
+result["add-group"] = await read("[data-pretable-add-group]");
+result["expand-all"] = await read("[data-pretable-expand-all]");
+result["collapse-all"] = await read("[data-pretable-collapse-all]");
+
+// Grouped fixture: a chip to remove, a group row to remove.
+await page.goto("http://localhost:3117/fixtures/grouping", { waitUntil: "networkidle" });
+await page.waitForSelector('[data-pretable-hydrated="true"]');
+result["chip-remove"] = await read("[data-pretable-chip-remove]");
+await page.locator("[data-pretable-tool-tab]").nth(2).click();
+result["tool-group-remove"] = await read("[data-pretable-tool-group-remove]");
+
+fs.writeFileSync(OUT, JSON.stringify(result, null, 1));
+const missing = Object.entries(result).filter(([, v]) => v === null).map(([k]) => k);
+console.log(missing.length ? `MISSING: ${missing.join(", ")}` : "all 12 sites measured");
+await browser.close();
+```
+
+- [ ] **Step 3: Take the baseline**
+
+```bash
+cp <scratchpad>/measure-buttons.mjs apps/website/measure.tmp.mjs && (cd apps/website && node measure.tmp.mjs <scratchpad>/buttons-before.json); rm -f apps/website/measure.tmp.mjs
+```
+
+Expected: `all 12 sites measured`. If any site prints as MISSING, fix the selector or the navigation in the script before continuing — a baseline with holes cannot prove anything later.
+
+- [ ] **Step 4: Stop the server**
+
+```bash
+pkill -f "next start -p 3117"
+```
+
+No commit — nothing in the repo changed.
+
+---
+
+### Task 2: The two components
+
+**Files:**
+
+- Create: `packages/react/src/components/button.tsx`
+- Test: `packages/react/src/__tests__/components-button.test.tsx`
+
+- [ ] **Step 1: Write the failing tests**
+
+```tsx
+// packages/react/src/__tests__/components-button.test.tsx
+import "@testing-library/jest-dom/vitest";
+import { cleanup, render } from "@testing-library/react";
+import { createRef } from "react";
+import { afterEach, describe, expect, test } from "vitest";
+
+import { PretableButton, PretableIconButton } from "../components/button";
+
+afterEach(() => {
+  cleanup();
+});
+
+describe("PretableButton", () => {
+  test("is always type=button, and carries its attributes", () => {
+    // Every grid button is type="button" today; a stray submit inside a
+    // consumer's <form> is a real bug class, so `type` is not a prop at all.
+    const { container } = render(
+      <PretableButton site="filter-clear">Clear</PretableButton>,
+    );
+    const button = container.querySelector("button")!;
+    expect(button).toHaveAttribute("type", "button");
+    expect(button).toHaveAttribute("data-pretable-button", "");
+    expect(button).toHaveAttribute("data-pretable-variant", "ghost");
+    expect(button).toHaveAttribute("data-pretable-site", "filter-clear");
+    expect(button).toHaveTextContent("Clear");
+  });
+
+  test("takes the link variant, and leaves the site attribute off when none is given", () => {
+    const { container } = render(
+      <PretableButton variant="link">Reset</PretableButton>,
+    );
+    const button = container.querySelector("button")!;
+    expect(button).toHaveAttribute("data-pretable-variant", "link");
+    expect(button).not.toHaveAttribute("data-pretable-site");
+  });
+
+  test("passes className, style and any other button attribute through", () => {
+    // The styling channel is the attributes plus the consumer's own class —
+    // a component that dropped className would have no styling channel.
+    const { container } = render(
+      <PretableButton
+        className="mine"
+        style={{ marginLeft: 4 }}
+        disabled
+        data-pretable-tool-reset=""
+        aria-describedby="why"
+      >
+        x
+      </PretableButton>,
+    );
+    const button = container.querySelector("button")!;
+    expect(button).toHaveClass("mine");
+    expect(button.style.marginLeft).toBe("4px");
+    expect(button).toBeDisabled();
+    expect(button).toHaveAttribute("data-pretable-tool-reset", "");
+    expect(button).toHaveAttribute("aria-describedby", "why");
+  });
+
+  test("forwards its ref to the button node", () => {
+    // The tool panel returns focus to button nodes and anchors menus on
+    // them; a component that hid the node would break both.
+    const ref = createRef<HTMLButtonElement>();
+    render(<PretableButton ref={ref}>x</PretableButton>);
+    expect(ref.current).toBeInstanceOf(HTMLButtonElement);
+  });
+
+  test("a consumer cannot override the contract attributes by spreading", () => {
+    // The data attributes follow the spread on purpose: they are the
+    // component's contract with grid.css, not inputs.
+    const { container } = render(
+      // @ts-expect-error — proving the runtime order, not the types
+      <PretableButton data-pretable-button="no" type="submit">
+        x
+      </PretableButton>,
+    );
+    const button = container.querySelector("button")!;
+    expect(button).toHaveAttribute("data-pretable-button", "");
+    expect(button).toHaveAttribute("type", "button");
+  });
+});
+
+describe("PretableIconButton", () => {
+  test("carries the icon-button attributes and its required name", () => {
+    const { container } = render(
+      <PretableIconButton aria-label="Remove Alpha" site="chip-remove">
+        <svg />
+      </PretableIconButton>,
+    );
+    const button = container.querySelector("button")!;
+    expect(button).toHaveAttribute("type", "button");
+    expect(button).toHaveAttribute("data-pretable-icon-button", "");
+    expect(button).toHaveAttribute("data-pretable-site", "chip-remove");
+    expect(button).not.toHaveAttribute("data-pretable-variant");
+    expect(button).toHaveAccessibleName("Remove Alpha");
+  });
+
+  test("forwards its ref and passes attributes through", () => {
+    const ref = createRef<HTMLButtonElement>();
+    const { container } = render(
+      <PretableIconButton
+        ref={ref}
+        aria-label="Filter Title"
+        tabIndex={-1}
+        aria-expanded={false}
+        data-pretable-filter-funnel=""
+      />,
+    );
+    expect(ref.current).toBe(container.querySelector("button"));
+    expect(ref.current).toHaveAttribute("tabindex", "-1");
+    expect(ref.current).toHaveAttribute("aria-expanded", "false");
+    expect(ref.current).toHaveAttribute("data-pretable-filter-funnel", "");
+  });
+});
+```
+
+- [ ] **Step 2: Run them to see them fail**
+
+```bash
+cd packages/react && pnpm exec vitest run --environment jsdom src/__tests__/components-button.test.tsx; cd ../..
+```
+
+Expected: FAIL — `Cannot find module '../components/button'`.
+
+- [ ] **Step 3: Write the components**
+
+```tsx
+// packages/react/src/components/button.tsx
+/**
+ * The kit's push-buttons — the first two components of a collection the grid
+ * renders its own chrome from and a consumer can replace per type through
+ * `components` on the surface (see `./context.ts`).
+ *
+ * Both render `<button type="button">`, always: every grid button is
+ * `type="button"`, and a stray submit inside a consumer's `<form>` is a real
+ * bug class, so `type` is not a prop. `className` and `style` pass through
+ * and merge — the component sets neither, so the consumer's IS the merge —
+ * and the contract attributes follow the spread so no prop can displace them.
+ *
+ * Styled by `@pretable/ui`'s grid.css through the attributes written here.
+ * That is the whole styling channel: `data-pretable-button` /
+ * `data-pretable-icon-button` for the shared box, `data-pretable-variant` for
+ * the two labelled looks, `data-pretable-site` for where in the grid the
+ * button sits. A site's own attribute (`data-pretable-filter-clear`) still
+ * arrives through the spread, so nothing that identified a button before
+ * these existed stops identifying it.
+ */
+import {
+  createElement,
+  forwardRef,
+  type ButtonHTMLAttributes,
+  type ReactElement,
+} from "react";
+
+/**
+ * The two labelled looks the grid uses: `ghost` (a 24px box with a hover
+ * tint — `+ filter`, `Expand all`) and `link` (plain accent text — `Clear`,
+ * `Reset columns`).
+ *
+ * @public
+ */
+export type PretableButtonVariant = "ghost" | "link";
+
+/**
+ * Where in the grid a built-in button sits. Each name is the site's own
+ * `data-pretable-*` attribute suffix, so there is one vocabulary, not two.
+ *
+ * @public
+ */
+export type PretableBuiltInButtonSite =
+  | "filter-add"
+  | "add-group"
+  | "expand-all"
+  | "collapse-all"
+  | "filter-clear"
+  | "tool-reset"
+  | "filter-funnel"
+  | "column-menu-button"
+  | "tool-row-menu-button"
+  | "chip-remove"
+  | "filter-row-remove"
+  | "tool-group-remove";
+
+/**
+ * A built-in site, or any string: autocomplete for the grid's own, no type
+ * error when a consumer names one of theirs. Same shape as
+ * `PretableToolPanelSectionId`.
+ *
+ * @public
+ */
+export type PretableButtonSite = PretableBuiltInButtonSite | (string & {});
+
+/**
+ * Props for {@link PretableButton}.
+ *
+ * @public
+ */
+export interface PretableButtonProps extends Omit<
+  ButtonHTMLAttributes<HTMLButtonElement>,
+  "type"
+> {
+  /** The labelled look. Default: `"ghost"`. */
+  variant?: PretableButtonVariant;
+  /**
+   * Where in the grid this button is; lands as `data-pretable-site`. A
+   * replacement passed through `components` receives it and can branch on it.
+   * Named `site`, not `role`: `role` is the ARIA attribute on every button.
+   */
+  site?: PretableButtonSite;
+}
+
+/**
+ * Props for {@link PretableIconButton}.
+ *
+ * @public
+ */
+export interface PretableIconButtonProps extends Omit<
+  ButtonHTMLAttributes<HTMLButtonElement>,
+  "type" | "aria-label"
+> {
+  /**
+   * Required. An icon-only button has no other accessible name, so omitting
+   * it is a compile error rather than a WCAG failure discovered later.
+   */
+  "aria-label": string;
+  /** Where in the grid this button is; lands as `data-pretable-site`. */
+  site?: PretableButtonSite;
+}
+
+/**
+ * A labelled push-button in one of the grid's two looks.
+ *
+ * ```tsx
+ * <PretableButton variant="link" site="filter-clear" onClick={clear}>
+ *   Clear
+ * </PretableButton>
+ * ```
+ *
+ * @public
+ */
+export const PretableButton = forwardRef<HTMLButtonElement, PretableButtonProps>(
+  function PretableButton(
+    { variant = "ghost", site, ...buttonProps },
+    ref,
+  ): ReactElement {
+    return (
+      <button
+        {...buttonProps}
+        ref={ref}
+        type="button"
+        data-pretable-button=""
+        data-pretable-variant={variant}
+        data-pretable-site={site}
+      />
+    );
+  },
+);
+
+/**
+ * An icon-only push-button. The accessible name is required.
+ *
+ * ```tsx
+ * <PretableIconButton aria-label={`Remove ${label}`} site="chip-remove">
+ *   <CloseIcon />
+ * </PretableIconButton>
+ * ```
+ *
+ * @public
+ */
+export const PretableIconButton = forwardRef<
+  HTMLButtonElement,
+  PretableIconButtonProps
+>(function PretableIconButton({ site, ...buttonProps }, ref): ReactElement {
+  return (
+    <button
+      {...buttonProps}
+      ref={ref}
+      type="button"
+      data-pretable-icon-button=""
+      data-pretable-site={site}
+    />
+  );
+});
+```
+
+- [ ] **Step 4: Run the tests to see them pass**
+
+```bash
+cd packages/react && pnpm exec vitest run --environment jsdom src/__tests__/components-button.test.tsx; cd ../..
+```
+
+Expected: `Tests  7 passed (7)`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/react/src/components/button.tsx packages/react/src/__tests__/components-button.test.tsx
+git commit -m "feat(react): PretableButton and PretableIconButton
+
+The kit's first two components. Always type=\"button\"; className and style
+pass through; the contract attributes follow the spread so no prop displaces
+them; IconButton's accessible name is a required prop.
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 3: The type contract
+
+**Files:**
+
+- Create: `type-tests/react/components-button.types.tsx`
+
+These are compiled by `pnpm typecheck:public` (`tsconfig.react.json` includes `react/**/*.tsx`). The components are not yet exported from `@pretable/react` — this task imports from the source path so it can run now; Task 11 switches the import to the package.
+
+- [ ] **Step 1: Write the type test**
+
+```tsx
+// type-tests/react/components-button.types.tsx
+import {
+  PretableButton,
+  PretableIconButton,
+  type PretableButtonProps,
+  type PretableButtonSite,
+  type PretableIconButtonProps,
+} from "../../packages/react/src/components/button";
+import type { Equal, Expect } from "../shared/assert";
+
+// An icon-only button has no accessible name but the one it is given, so
+// omitting it is a compile error — a WCAG failure the grid could otherwise
+// ship becomes one the compiler refuses.
+// @ts-expect-error — aria-label is required on an icon button
+<PretableIconButton onClick={() => {}} />;
+<PretableIconButton aria-label="Remove" />;
+
+// The element is always type="button"; the prop does not exist.
+// @ts-expect-error — `type` is not a prop
+<PretableButton type="submit">x</PretableButton>;
+// @ts-expect-error — `type` is not a prop on the icon button either
+<PretableIconButton aria-label="x" type="submit" />;
+
+// A site is a built-in name or any string, never a type error.
+<PretableButton site="filter-clear">x</PretableButton>;
+<PretableButton site="my-app-export">x</PretableButton>;
+export type SiteIsOpen = Expect<
+  Equal<Extract<PretableButtonSite, "filter-clear">, "filter-clear">
+>;
+
+// The variant is closed.
+<PretableButton variant="link">x</PretableButton>;
+// @ts-expect-error — only the two shipped looks exist
+<PretableButton variant="solid">x</PretableButton>;
+
+// Every native button attribute flows through, refs included.
+const ref = { current: null as HTMLButtonElement | null };
+<PretableButton ref={ref} aria-describedby="why" disabled tabIndex={-1}>
+  x
+</PretableButton>;
+<PretableIconButton ref={ref} aria-label="x" aria-expanded={false} />;
+
+// The props types are what a replacement is written against.
+export type ButtonHasSite = Expect<
+  Equal<PretableButtonProps["site"], PretableButtonSite | undefined>
+>;
+export type IconHasName = Expect<
+  Equal<PretableIconButtonProps["aria-label"], string>
+>;
+```
+
+- [ ] **Step 2: Run the type tests**
+
+```bash
+pnpm exec tsc -p type-tests/tsconfig.react.json --noEmit
+```
+
+Expected: no output (exit 0). If an `@ts-expect-error` is reported as unused, the prop it guards is not actually rejected — fix the component, not the test.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add type-tests/react/components-button.types.tsx
+git commit -m "test(react): pin the Button/IconButton type contract
+
+aria-label required on IconButton, no \`type\` prop, an open \`site\`, a closed
+variant, and native attributes flowing through with the ref.
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 4: The components context
+
+**Files:**
+
+- Create: `packages/react/src/components/context.ts`
+- Test: add a `describe("components context")` block to `packages/react/src/__tests__/components-button.test.tsx`
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `components-button.test.tsx`:
+
+```tsx
+import { renderHook } from "@testing-library/react";
+import {
+  DEFAULT_COMPONENTS,
+  PretableComponentsProvider,
+  usePretableComponents,
+  useResolvedComponents,
+} from "../components/context";
+
+describe("components context", () => {
+  test("outside any provider, the hook returns the built-in components", () => {
+    const { result } = renderHook(() => usePretableComponents());
+    expect(result.current).toBe(DEFAULT_COMPONENTS);
+    expect(result.current.Button).toBe(PretableButton);
+    expect(result.current.IconButton).toBe(PretableIconButton);
+  });
+
+  test("resolving nothing yields the default map, by identity", () => {
+    // Identity matters: the provider's value is what every button re-renders
+    // on, so an unchanged input must produce an unchanged output.
+    const { result, rerender } = renderHook(
+      ({ components }) => useResolvedComponents(components),
+      { initialProps: { components: undefined as undefined | { Button?: typeof PretableButton } } },
+    );
+    expect(result.current).toBe(DEFAULT_COMPONENTS);
+    rerender({ components: {} });
+    expect(result.current).toBe(DEFAULT_COMPONENTS);
+  });
+
+  test("a replacement is merged over the defaults, and a stable input is a stable output", () => {
+    const MyButton = (props: React.ComponentProps<typeof PretableButton>) => (
+      <button {...props} data-mine="" />
+    );
+    const { result, rerender } = renderHook(
+      ({ components }) => useResolvedComponents(components),
+      { initialProps: { components: { Button: MyButton } } },
+    );
+    const first = result.current;
+    expect(first.Button).toBe(MyButton);
+    expect(first.IconButton).toBe(PretableIconButton);
+    // A NEW object literal with the SAME values — what an inline
+    // `components={{ Button: MyButton }}` produces on every render.
+    rerender({ components: { Button: MyButton } });
+    expect(result.current).toBe(first);
+  });
+
+  test("the provider's value is what the hook reads", () => {
+    const MyIcon = (props: React.ComponentProps<typeof PretableIconButton>) => (
+      <button {...props} data-mine="" />
+    );
+    const value = { Button: PretableButton, IconButton: MyIcon };
+    const { result } = renderHook(() => usePretableComponents(), {
+      wrapper: ({ children }) => (
+        <PretableComponentsProvider value={value}>{children}</PretableComponentsProvider>
+      ),
+    });
+    expect(result.current.IconButton).toBe(MyIcon);
+  });
+});
+```
+
+Add `import * as React from "react";` at the top of the file if `React.ComponentProps` is not otherwise in scope.
+
+- [ ] **Step 2: Run to see them fail**
+
+```bash
+cd packages/react && pnpm exec vitest run --environment jsdom src/__tests__/components-button.test.tsx; cd ../..
+```
+
+Expected: FAIL — `Cannot find module '../components/context'`.
+
+- [ ] **Step 3: Write the context**
+
+```ts
+// packages/react/src/components/context.ts
+/**
+ * How a consumer's replacement reaches every place the grid renders a kit
+ * component, and how the grid reads it.
+ *
+ * ONE slot per component type. `components={{ Button: MyButton }}` on the
+ * surface replaces every button the grid draws; the props ours passes —
+ * `site` included — are exactly what the replacement receives, so it can
+ * branch on `site` to treat one place differently. No per-site public names:
+ * the API does not grow a name for every control the grid gains.
+ *
+ * CONTEXT, not props. pretable portals its popovers — the filter dialog, the
+ * column menus — into document.body. Context crosses a portal; props do not,
+ * and the popovers are exactly where an override matters most. The value is
+ * resolved once at the surface and memoised on the identity of each slot, so
+ * an inline `{{ Button: MyButton }}` literal does not re-render every button
+ * on every keystroke.
+ *
+ * The default context value is the built-in map, so a kit component rendered
+ * outside any surface still resolves.
+ */
+import {
+  createContext,
+  useContext,
+  useMemo,
+  type ComponentType,
+  type RefAttributes,
+} from "react";
+
+import {
+  PretableButton,
+  PretableIconButton,
+  type PretableButtonProps,
+  type PretableIconButtonProps,
+} from "./button";
+
+/**
+ * The component a `components.Button` replacement must be: it receives
+ * {@link PretableButtonProps} and forwards its `ref` to the button node —
+ * the one obligation on a replacement, since the grid anchors menus on and
+ * returns focus to that node.
+ *
+ * @public
+ */
+export type PretableButtonComponent = ComponentType<
+  PretableButtonProps & RefAttributes<HTMLButtonElement>
+>;
+
+/**
+ * The component a `components.IconButton` replacement must be.
+ *
+ * @public
+ */
+export type PretableIconButtonComponent = ComponentType<
+  PretableIconButtonProps & RefAttributes<HTMLButtonElement>
+>;
+
+/**
+ * The kit components a consumer can replace, one slot per type. Every slot is
+ * optional; an absent one is the built-in.
+ *
+ * @public
+ */
+export interface PretableComponents {
+  readonly Button?: PretableButtonComponent;
+  readonly IconButton?: PretableIconButtonComponent;
+}
+
+/** The map after resolution: every slot filled. Internal. */
+export interface ResolvedPretableComponents {
+  readonly Button: PretableButtonComponent;
+  readonly IconButton: PretableIconButtonComponent;
+}
+
+/** The built-ins, frozen: also the identity a no-op resolution returns. */
+export const DEFAULT_COMPONENTS: ResolvedPretableComponents = Object.freeze({
+  Button: PretableButton,
+  IconButton: PretableIconButton,
+});
+
+const PretableComponentsContext =
+  createContext<ResolvedPretableComponents>(DEFAULT_COMPONENTS);
+
+/** Wraps the surface's tree. Internal — the public entry is the surface prop. */
+export const PretableComponentsProvider = PretableComponentsContext.Provider;
+
+/** What a call site renders its button from. Internal. */
+export function usePretableComponents(): ResolvedPretableComponents {
+  return useContext(PretableComponentsContext);
+}
+
+/**
+ * Merge a consumer's map over the defaults, memoised on the identity of each
+ * slot's VALUE rather than of the map, so a fresh object literal carrying the
+ * same components resolves to the same object — and the defaults, when
+ * nothing is replaced, to the frozen `DEFAULT_COMPONENTS` itself.
+ */
+export function useResolvedComponents(
+  components: PretableComponents | undefined,
+): ResolvedPretableComponents {
+  const Button = components?.Button ?? DEFAULT_COMPONENTS.Button;
+  const IconButton = components?.IconButton ?? DEFAULT_COMPONENTS.IconButton;
+  return useMemo(
+    () =>
+      Button === DEFAULT_COMPONENTS.Button &&
+      IconButton === DEFAULT_COMPONENTS.IconButton
+        ? DEFAULT_COMPONENTS
+        : { Button, IconButton },
+    [Button, IconButton],
+  );
+}
+```
+
+- [ ] **Step 4: Run the tests to see them pass**
+
+```bash
+cd packages/react && pnpm exec vitest run --environment jsdom src/__tests__/components-button.test.tsx; cd ../..
+```
+
+Expected: `Tests  11 passed (11)`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/react/src/components/context.ts packages/react/src/__tests__/components-button.test.tsx
+git commit -m "feat(react): the components context
+
+One slot per type, resolved over the defaults and memoised on each slot's
+identity; context rather than props because the popovers are portalled.
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 5: Wire `components` through the surface and the preset
+
+**Files:**
+
+- Modify: `packages/react/src/pretable-surface.tsx` (the shared-props interface near the `messages?` prop at ~L1412; the props destructuring at ~L1899; after the `effectiveMessages` memo ending ~L2265; the two return statements at ~L7955 and ~L7966)
+- Modify: `packages/react/src/pretable.tsx` (`PretableBaseProps`, after `messages?` at ~L120)
+- Test: `packages/react/src/__tests__/components-override.test.tsx`
+
+- [ ] **Step 1: Write the failing tests**
+
+```tsx
+// packages/react/src/__tests__/components-override.test.tsx
+// @vitest-environment jsdom
+import "@testing-library/jest-dom/vitest";
+import { cleanup, fireEvent, render, waitFor } from "@testing-library/react";
+import { forwardRef, type ComponentProps } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { Pretable } from "../pretable";
+import { PretableSurface } from "../pretable-surface";
+import type { PretableColumn } from "../types";
+import type { PretableButtonComponent, PretableIconButtonComponent } from "../components/context";
+
+afterEach(() => {
+  cleanup();
+});
+
+type Row = { id: string; name: string; qty: number };
+const columns: PretableColumn<Row>[] = [
+  { id: "name", header: "Name", widthPx: 160, type: "text" },
+  { id: "qty", header: "Qty", widthPx: 100, type: "number" },
+];
+const rows: Row[] = [
+  { id: "a", name: "Alpha", qty: 1 },
+  { id: "b", name: "Bravo", qty: 2 },
+];
+
+/** A replacement that marks itself and records what site it was asked for. */
+const MyButton: PretableButtonComponent = forwardRef(function MyButton(
+  { site, variant, ...props },
+  ref,
+) {
+  return <button {...props} ref={ref} type="button" data-mine={site ?? ""} data-mine-variant={variant} />;
+});
+const MyIconButton: PretableIconButtonComponent = forwardRef(function MyIconButton(
+  { site, ...props },
+  ref,
+) {
+  return <button {...props} ref={ref} type="button" data-mine-icon={site ?? ""} />;
+});
+
+function renderSurface(components?: ComponentProps<typeof PretableSurface>["components"]) {
+  return render(
+    <PretableSurface<Row>
+      ariaLabel="override-grid"
+      columns={columns}
+      components={components}
+      getRowId={(row) => row.id}
+      rows={rows}
+      toolPanel={{ defaultActiveSection: "columns" }}
+      viewportHeight={240}
+    />,
+  );
+}
+
+describe("components on the surface", () => {
+  it("without the prop, the grid draws the kit's own buttons", () => {
+    const view = renderSurface();
+    const reset = view.getByRole("button", { name: "Reset columns" });
+    expect(reset).toHaveAttribute("data-pretable-button", "");
+    expect(reset).toHaveAttribute("data-pretable-site", "tool-reset");
+    expect(reset).toHaveAttribute("data-pretable-tool-reset", "");
+  });
+
+  it("replaces every Button, passing the site through, and keeps the site's own attribute", () => {
+    const view = renderSurface({ Button: MyButton });
+    const reset = view.getByRole("button", { name: "Reset columns" });
+    expect(reset).toHaveAttribute("data-mine", "tool-reset");
+    expect(reset).toHaveAttribute("data-mine-variant", "link");
+    // Nothing that identified this button before stops identifying it.
+    expect(reset).toHaveAttribute("data-pretable-tool-reset", "");
+    expect(reset).not.toHaveAttribute("data-pretable-button");
+    // The other slot is untouched.
+    expect(view.container.querySelector("[data-pretable-icon-button]")).not.toBeNull();
+  });
+
+  it("replaces every IconButton, including one in the header", () => {
+    const view = renderSurface({ IconButton: MyIconButton });
+    const funnel = view.getByRole("button", { name: "Filter Name" });
+    expect(funnel).toHaveAttribute("data-mine-icon", "filter-funnel");
+    expect(funnel).toHaveAttribute("data-pretable-filter-funnel", "");
+    expect(funnel).toHaveAttribute("tabindex", "-1");
+  });
+
+  it("reaches a button inside a PORTALLED popover — the reason this is context, not props", async () => {
+    const view = renderSurface({ Button: MyButton });
+    const funnel = view.getByRole("button", { name: "Filter Name" });
+    fireEvent.pointerDown(funnel);
+    fireEvent.click(funnel);
+    // The filter dialog renders through OverlayPortal into document.body.
+    const dialog = await waitFor(() => {
+      const el = document.querySelector("[data-pretable-filter-menu]");
+      if (!el) throw new Error("dialog not open");
+      return el;
+    });
+    expect(dialog.parentElement).toBe(document.body);
+    const clear = dialog.querySelector("[data-pretable-filter-clear]")!;
+    expect(clear).toHaveAttribute("data-mine", "filter-clear");
+  });
+
+  it("a fresh object literal with the same components does not remount the buttons", () => {
+    // Inline `components={{ Button: MyButton }}` is the common way to write
+    // it, and it produces a new object every render. The resolved map is
+    // memoised on the slot VALUES, so the node survives a re-render.
+    const view = renderSurface({ Button: MyButton });
+    const before = view.getByRole("button", { name: "Reset columns" });
+    view.rerender(
+      <PretableSurface<Row>
+        ariaLabel="override-grid"
+        columns={columns}
+        components={{ Button: MyButton }}
+        getRowId={(row) => row.id}
+        rows={rows}
+        toolPanel={{ defaultActiveSection: "columns" }}
+        viewportHeight={240}
+      />,
+    );
+    expect(view.getByRole("button", { name: "Reset columns" })).toBe(before);
+  });
+
+  it("the replacement still receives the ref the grid anchors on", () => {
+    // The kebab menu anchors on its button's node through a ref callback. A
+    // replacement that forwards its ref keeps that working.
+    const view = renderSurface({ IconButton: MyIconButton });
+    const kebab = view.container.querySelector("[data-pretable-tool-row-menu-button]")!;
+    fireEvent.pointerDown(kebab);
+    fireEvent.click(kebab);
+    expect(document.querySelector("[data-pretable-column-menu]")).not.toBeNull();
+  });
+});
+
+describe("components on the <Pretable> preset", () => {
+  it("forwards the prop", () => {
+    const view = render(
+      <Pretable<Row>
+        ariaLabel="preset-grid"
+        columns={columns}
+        components={{ Button: MyButton }}
+        rows={rows}
+      />,
+    );
+    // The preset ships the tool panel on by default; open the columns tab.
+    const tab = view.container.querySelector("[data-pretable-tool-tab]")!;
+    fireEvent.click(tab);
+    expect(view.getByRole("button", { name: "Reset columns" })).toHaveAttribute("data-mine", "tool-reset");
+  });
+});
+```
+
+Note: the funnel's accessible name is `Filter ${label}` (from `FunnelButton.tsx`), and the reset button's label is `messages.toolPanelResetColumnsLabel()` — `"Reset columns"` in the defaults. If either string differs when you run this, read it from `packages/react/src/messages.ts` and correct the test, not the component.
+
+- [ ] **Step 2: Run to see them fail**
+
+```bash
+cd packages/react && pnpm exec vitest run --environment jsdom src/__tests__/components-override.test.tsx; cd ../..
+```
+
+Expected: FAIL. The first test fails because `Reset columns` is a bare `<button>` with no `data-pretable-button` (sites are migrated in Tasks 8–10); the others fail because `components` is not yet a prop. That is the right order: this task makes the prop exist and flow; the site tests go green as each site migrates.
+
+- [ ] **Step 3: Add the prop to the shared props interface**
+
+In `packages/react/src/pretable-surface.tsx`, directly after the `messages?: PretableSurfaceMessages;` member (~L1412), add:
+
+```ts
+  /**
+   * Replace the kit components the grid renders its own chrome from — one
+   * slot per component type, applied everywhere that type appears. A
+   * replacement receives exactly the props the built-in does, `site`
+   * included, so it can branch on where in the grid it is; it must forward
+   * its `ref` to the button node, which the grid anchors menus on and returns
+   * focus to. Absent slots are the built-ins.
+   */
+  components?: PretableComponents;
+```
+
+and add the import near the other `./` imports at the top of the file:
+
+```ts
+import {
+  PretableComponentsProvider,
+  useResolvedComponents,
+  type PretableComponents,
+} from "./components/context";
+```
+
+- [ ] **Step 4: Destructure and resolve it**
+
+In the surface's props destructuring where `messages,` appears (~L1899), add `components,` on the next line.
+
+Directly after the `effectiveMessages` `useMemo` closes (the `}, [messages]);` line, ~L2265), add:
+
+```ts
+  const resolvedComponents = useResolvedComponents(components);
+```
+
+- [ ] **Step 5: Provide it on both return paths**
+
+The surface returns from two places. Replace the early return (~L7955):
+
+```tsx
+  if (!toolPanelEnabled || toolPanelSections.length === 0) {
+    return verticalStack;
+  }
+```
+
+with
+
+```tsx
+  if (!toolPanelEnabled || toolPanelSections.length === 0) {
+    return (
+      <PretableComponentsProvider value={resolvedComponents}>
+        {verticalStack}
+      </PretableComponentsProvider>
+    );
+  }
+```
+
+and wrap the tool-layout return (~L7966) the same way — the existing `<div data-pretable-tool-layout="" …>…</div>` becomes the provider's only child:
+
+```tsx
+  return (
+    <PretableComponentsProvider value={resolvedComponents}>
+      <div
+        data-pretable-tool-layout=""
+        ref={observeToolLayout}
+        style={getToolPanelLayoutStyle()}
+      >
+        {/* …unchanged… */}
+      </div>
+    </PretableComponentsProvider>
+  );
+```
+
+The provider is outside every portal's React parent, so the popovers inherit it.
+
+- [ ] **Step 6: Forward it on the preset**
+
+In `packages/react/src/pretable.tsx`, in `PretableBaseProps`, directly after the `messages?:` member:
+
+```ts
+  components?: PretableSurfaceSharedProps<TRow, TRowId, TColumns>["components"];
+```
+
+The preset spreads its props into the surface (`const surfaceProps = { ...props, … }`), so no runtime change is needed.
+
+- [ ] **Step 7: Run the override tests**
+
+```bash
+cd packages/react && pnpm exec vitest run --environment jsdom src/__tests__/components-override.test.tsx; cd ../..
+```
+
+Expected: still FAIL on every site assertion — the sites are not migrated yet — but with **no** failure about `components` being an unknown prop, and `pnpm typecheck` clean:
+
+```bash
+pnpm typecheck
+```
+
+Expected: exit 0.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add packages/react/src/pretable-surface.tsx packages/react/src/pretable.tsx packages/react/src/__tests__/components-override.test.tsx
+git commit -m "feat(react): the components prop on the surface and the preset
+
+Resolved once, memoised on slot identity, provided on both of the surface's
+return paths so the portalled popovers inherit it. The override tests land
+red on the site assertions, which the migrations turn green.
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 6: The component rules in grid.css
+
+**Files:**
+
+- Modify: `packages/ui/grid.css` — new section inserted **before** the first site rule (anchor: the `/* Multi-sort priority badge` comment that follows the pinned-header-cell rule near L102), so every site rule that follows can still win at equal specificity by source order
+- Modify: the `@media (forced-colors: active)` block's disabled rule
+- Test: `packages/ui/src/__tests__/css-cascade.test.ts`
+
+- [ ] **Step 1: Write the failing guard**
+
+Add to `css-cascade.test.ts`, before the `a focused cell draws its ring…` test:
+
+```ts
+  test("the kit buttons carry the shared look, the standard ring and the disabled treatment", () => {
+    const css = strippedCss();
+    const rules = rulesSelecting(
+      css,
+      (selector) =>
+        selector.includes("data-pretable-button]") ||
+        selector.includes("data-pretable-icon-button]"),
+    );
+    expect(rules.length, "no kit button rules").toBeGreaterThan(0);
+    const bodies = rules.map((m) => m[2]).join("\n");
+
+    // The shared box every push-button had per site: no border, transparent,
+    // the control radius, the pointer, and the surrounding font.
+    expect(bodies).toMatch(/border:\s*0/);
+    expect(bodies).toMatch(/background:\s*transparent/);
+    expect(bodies).toMatch(/border-radius:\s*var\(--pretable-radius-control\)/);
+    expect(bodies).toMatch(/font:\s*inherit/);
+
+    // The two labelled looks.
+    const ghost = rulesSelecting(css, (s) => s.includes('data-pretable-variant="ghost"]'));
+    expect(ghost.map((m) => m[2]).join("")).toMatch(/block-size:\s*24px/);
+    const link = rulesSelecting(css, (s) => s.includes('data-pretable-variant="link"]'));
+    expect(link.map((m) => m[2]).join("")).toMatch(/padding:\s*2px 4px/);
+
+    // Hover never paints on a disabled control (#573).
+    for (const [, selector] of rules) {
+      if (selector.includes(":hover")) {
+        expect(selector, `"${selector.trim()}" hovers a disabled button`).toContain(":not(:disabled)");
+      }
+    }
+    // The standard ring, and the standard disabled ink.
+    const ring = rules.filter(([, s]) => s.includes(":focus-visible")).map((m) => m[2]).join("");
+    expect(ring).toMatch(/outline:\s*2px solid var\(--pretable-focus-ring\)/);
+    const disabled = rules.filter(([, s]) => s.includes(":disabled") && !s.includes(":hover")).map((m) => m[2]).join("");
+    expect(disabled).toMatch(/color:\s*var\(--pretable-text-dim\)/);
+    expect(disabled).toMatch(/cursor:\s*default/);
+
+    // And under forced colours, the system's own disabled ink.
+    const forced = css.slice(css.indexOf("@media (forced-colors: active)"));
+    const forcedDisabled = rulesSelecting(forced, (s) => s.includes("data-pretable-button]:disabled"));
+    expect(forcedDisabled.map((m) => m[2]).join("")).toMatch(/color:\s*GrayText/);
+  });
+```
+
+- [ ] **Step 2: Run to see it fail**
+
+```bash
+cd packages/ui && pnpm exec vitest run src/__tests__/css-cascade.test.ts; cd ../..
+```
+
+Expected: FAIL — `no kit button rules`.
+
+- [ ] **Step 3: Add the rules**
+
+Insert into `packages/ui/grid.css` immediately before the `/* Multi-sort priority badge` comment:
+
+```css
+  /* ---- Kit components: push-buttons ------------------------------------
+     The shared look every plain push-button in the grid used to carry per
+     site — twelve rule lists for one box — now lives on the component's own
+     attributes, and each site keeps only what is genuinely its own: a size,
+     a reveal, an alignment. These rules come FIRST in the file so a site
+     rule can still win at equal specificity by source order. The site
+     attribute (`data-pretable-filter-clear`) still arrives on the element,
+     so every selector keyed on it keeps working. */
+  :where([data-pretable-button], [data-pretable-icon-button]) {
+    box-sizing: border-box;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    border: 0;
+    border-radius: var(--pretable-radius-control);
+    background: transparent;
+    color: var(--pretable-text-dim);
+    font: inherit;
+    cursor: pointer;
+  }
+  /* A labelled button speaks in the accent; an icon button in the dim ink
+     its site may lift on hover or reveal. */
+  :where([data-pretable-button]) {
+    color: var(--pretable-accent);
+  }
+  /* `ghost`: the 24px action row box — `+ filter`, `Expand all` — with a
+     hover tint painted as a background-IMAGE layer so a site's own surface
+     colour underneath survives. */
+  :where([data-pretable-button][data-pretable-variant="ghost"]) {
+    gap: 4px;
+    block-size: 24px;
+    padding-inline: 6px;
+  }
+  :where(
+    [data-pretable-button][data-pretable-variant="ghost"]:hover:not(:disabled)
+  ) {
+    background-image: linear-gradient(
+      var(--pretable-bg-hover),
+      var(--pretable-bg-hover)
+    );
+  }
+  /* `link`: plain accent text — `Clear`, `Reset columns`. No hover tint;
+     the two sites that use it never had one. */
+  :where([data-pretable-button][data-pretable-variant="link"]) {
+    padding: 2px 4px;
+  }
+  /* An icon button is a fixed box its site sizes (14, 18 and 24px boxes all
+     exist); `position: relative` is for the sites that enlarge the hit area
+     with a ::after. */
+  :where([data-pretable-icon-button]) {
+    flex: none;
+    padding: 0;
+    position: relative;
+  }
+  :where(
+    [data-pretable-button]:focus-visible,
+    [data-pretable-icon-button]:focus-visible
+  ) {
+    outline: 2px solid var(--pretable-focus-ring);
+    outline-offset: -2px;
+  }
+  /* The standard disabled treatment (#573): dim by token, drop the pointer. */
+  :where([data-pretable-button]:disabled, [data-pretable-icon-button]:disabled) {
+    color: var(--pretable-text-dim);
+    cursor: default;
+  }
+
+```
+
+Then in the `@media (forced-colors: active)` block, change the disabled rule from
+
+```css
+    :where([data-pretable-menu-item]:disabled) {
+      color: GrayText;
+    }
+```
+
+to
+
+```css
+    :where(
+      [data-pretable-menu-item]:disabled,
+      [data-pretable-button]:disabled,
+      [data-pretable-icon-button]:disabled
+    ) {
+      color: GrayText;
+    }
+```
+
+- [ ] **Step 4: Run the guard and the whole ui suite**
+
+```bash
+cd packages/ui && pnpm exec vitest run; cd ../..
+```
+
+Expected: all pass. (The `unresolved var` contract test still passes — every token used is a theme token.)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/ui/grid.css packages/ui/src/__tests__/css-cascade.test.ts
+git commit -m "feat(ui): the kit button rules
+
+The shared push-button box on the component attributes, first in the file
+so site rules still win by order; ghost and link looks; the standard ring,
+disabled treatment and forced-colours ink.
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 7: Guard that the site rules give up what the component owns
+
+This guard is written before the sites migrate (Tasks 8–10) and fails until Task 10 collapses the CSS. It is what makes "grid.css gets smaller" a checked claim rather than a hope.
+
+**Files:**
+
+- Modify: `packages/ui/src/__tests__/css-cascade.test.ts`
+
+- [ ] **Step 1: Write the failing guard**
+
+```ts
+  test("a push-button site rule declares only what is its own", () => {
+    // The component rules own the box: border, background, radius, cursor,
+    // font, the ring, the disabled ink. A site that redeclares any of them
+    // is the old per-site copy coming back — twelve of which is how the
+    // buttons drifted apart in the first place.
+    const css = strippedCss();
+    const OWNED = [
+      /(?:^|[;{\s])border:\s*0/,
+      /(?:^|[;{\s])background:\s*transparent/,
+      /border-radius:\s*var\(--pretable-radius-control\)/,
+      /(?:^|[;{\s])cursor:\s*pointer/,
+      /(?:^|[;{\s])font:\s*inherit/,
+    ];
+    const sites = [
+      "filter-add", "add-group", "expand-all", "collapse-all",
+      "filter-clear", "tool-reset",
+      "filter-funnel", "column-menu-button", "tool-row-menu-button",
+      "chip-remove", "filter-row-remove", "tool-group-remove",
+    ];
+    for (const site of sites) {
+      const rules = rulesSelecting(
+        css,
+        (selector) =>
+          selector.includes(`data-pretable-${site}]`) &&
+          !selector.includes("::") &&
+          !selector.includes(":hover") &&
+          !selector.includes(":focus") &&
+          !selector.includes(":disabled"),
+      );
+      for (const [, selector, body] of rules) {
+        for (const owned of OWNED) {
+          expect(
+            body,
+            `"${selector.trim()}" redeclares ${owned} — the kit button rule owns it`,
+          ).not.toMatch(owned);
+        }
+      }
+      // The ring and the disabled ink are the component's too.
+      const ring = rulesSelecting(css, (s) => s.includes(`data-pretable-${site}]:focus-visible`));
+      expect(ring.length, `${site} still carries its own focus ring`).toBe(0);
+      const dis = rulesSelecting(css, (s) => s.includes(`data-pretable-${site}]:disabled`));
+      expect(dis.length, `${site} still carries its own disabled rule`).toBe(0);
+    }
+  });
+```
+
+- [ ] **Step 2: Run to see it fail**
+
+```bash
+cd packages/ui && pnpm exec vitest run src/__tests__/css-cascade.test.ts; cd ../..
+```
+
+Expected: FAIL, naming `[data-pretable-filter-funnel]` (or another site) as redeclaring `border: 0`. Leave it red; Task 10 turns it green.
+
+- [ ] **Step 3: Commit the red guard**
+
+```bash
+git add packages/ui/src/__tests__/css-cascade.test.ts
+git commit -m "test(ui): a push-button site rule declares only what is its own
+
+Red until the site rules collapse onto the component rules (Task 10).
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 8: Migrate the ghost buttons (5 sites)
+
+**Files:**
+
+- Modify: `packages/react/src/tool-panel/filters/FiltersSection.tsx` (~L693–L735)
+- Modify: `packages/react/src/tool-panel/grouping/GroupingSection.tsx` (~L443–L462 and ~L480–L496)
+
+- [ ] **Step 1: FiltersSection — both `+ filter` / `+ group` buttons**
+
+Add the import:
+
+```ts
+import { usePretableComponents } from "../../components/context";
+```
+
+Inside the component that renders them (the function containing `const refuse = …`), before its `return`, add:
+
+```ts
+    const { Button } = usePretableComponents();
+```
+
+Replace the first button:
+
+```tsx
+        <button
+          type="button"
+          data-pretable-filter-add=""
+          {...refuse(filterReason)}
+          onClick={() => {
+```
+
+with
+
+```tsx
+        <Button
+          site="filter-add"
+          data-pretable-filter-add=""
+          {...refuse(filterReason)}
+          onClick={() => {
+```
+
+and its closing `</button>` (the one right after `{messages.toolPanelAddFilterLabel()}`) with `</Button>`. Do the same for the second: `<button type="button" data-pretable-filter-add="" {...refuse(groupReason)}` → `<Button site="filter-add" data-pretable-filter-add="" {...refuse(groupReason)}`, and its closing tag after `{messages.toolPanelAddGroupLabel()}` → `</Button>`.
+
+`variant` is omitted: `ghost` is the default. `type="button"` is dropped: the component sets it and the prop does not exist.
+
+- [ ] **Step 2: GroupingSection — `add-group`, `expand-all`, `collapse-all`**
+
+Add the import:
+
+```ts
+import { usePretableComponents } from "../../components/context";
+```
+
+In the section component, before the `return` that renders the add-group button, add `const { Button } = usePretableComponents();` (if the file has more than one component rendering these, add it in each).
+
+Replace
+
+```tsx
+        <button
+          aria-expanded={menu !== null}
+          aria-haspopup="menu"
+          data-pretable-add-group=""
+          disabled={ungrouped.length === 0}
+          ref={addButtonRef}
+```
+
+with
+
+```tsx
+        <Button
+          site="add-group"
+          aria-expanded={menu !== null}
+          aria-haspopup="menu"
+          data-pretable-add-group=""
+          disabled={ungrouped.length === 0}
+          ref={addButtonRef}
+```
+
+remove its `type="button"` line, and change its closing `</button>` (after `{messages.toolPanelAddRowGroupLabel()}`) to `</Button>`.
+
+Replace the two expansion buttons:
+
+```tsx
+        <button
+          data-pretable-expand-all=""
+          disabled={groupedIds.length === 0}
+          onClick={() => rowModel.expandAll()}
+          type="button"
+        >
+          {messages.toolPanelExpandAllLabel()}
+        </button>
+        <button
+          data-pretable-collapse-all=""
+          disabled={groupedIds.length === 0}
+          onClick={() => rowModel.collapseAll()}
+          type="button"
+        >
+          {messages.toolPanelCollapseAllLabel()}
+        </button>
+```
+
+with
+
+```tsx
+        <Button
+          site="expand-all"
+          data-pretable-expand-all=""
+          disabled={groupedIds.length === 0}
+          onClick={() => rowModel.expandAll()}
+        >
+          {messages.toolPanelExpandAllLabel()}
+        </Button>
+        <Button
+          site="collapse-all"
+          data-pretable-collapse-all=""
+          disabled={groupedIds.length === 0}
+          onClick={() => rowModel.collapseAll()}
+        >
+          {messages.toolPanelCollapseAllLabel()}
+        </Button>
+```
+
+- [ ] **Step 3: Run the suites that touch these sections**
+
+```bash
+cd packages/react && pnpm exec vitest run --environment jsdom src/__tests__/filter-builder.test.tsx src/__tests__/tool-panel.test.tsx src/__tests__/grouping-options.test.tsx src/__tests__/components-override.test.tsx; cd ../..
+```
+
+Expected: `filter-builder`, `tool-panel`, `grouping-options` pass unchanged (every locator keys on the site attribute, which is still there). `components-override` still has failures for `tool-reset` and the icon sites — expected until Tasks 9–10.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add packages/react/src/tool-panel/filters/FiltersSection.tsx packages/react/src/tool-panel/grouping/GroupingSection.tsx
+git commit -m "refactor(react): the five ghost actions render the kit Button
+
++ filter, + group, Add group, Expand all, Collapse all. Each keeps its site
+attribute, so nothing that identified it stops identifying it.
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 9: Migrate the link buttons (2 sites)
+
+**Files:**
+
+- Modify: `packages/react/src/filter-menu/FilterMenu.tsx` (~L396)
+- Modify: `packages/react/src/tool-panel/ColumnsSection.tsx` (~L586)
+
+- [ ] **Step 1: FilterMenu — `Clear`**
+
+Add the import `import { usePretableComponents } from "../components/context";`. In the `FilterMenu` component body, before its `return`, add `const { Button } = usePretableComponents();`. Replace
+
+```tsx
+        <button type="button" data-pretable-filter-clear="" onClick={onClear}>
+          Clear
+        </button>
+```
+
+with
+
+```tsx
+        <Button variant="link" site="filter-clear" data-pretable-filter-clear="" onClick={onClear}>
+          Clear
+        </Button>
+```
+
+- [ ] **Step 2: ColumnsSection — `Reset columns`**
+
+Add the import `import { usePretableComponents } from "../components/context";`. In the component that renders the reset button, before its `return`, add `const { Button } = usePretableComponents();` (this file also hosts the kebab migrated in Task 10 — one `const { Button, IconButton } = usePretableComponents();` serves both if they are in the same component). Replace
+
+```tsx
+      <button data-pretable-tool-reset="" onClick={reset} type="button">
+        {messages.toolPanelResetColumnsLabel()}
+      </button>
+```
+
+with
+
+```tsx
+      <Button variant="link" site="tool-reset" data-pretable-tool-reset="" onClick={reset}>
+        {messages.toolPanelResetColumnsLabel()}
+      </Button>
+```
+
+- [ ] **Step 3: Run the suites**
+
+```bash
+cd packages/react && pnpm exec vitest run --environment jsdom src/__tests__/filter-menu.test.tsx src/__tests__/filter-menu-surface.test.tsx src/__tests__/tool-panel.test.tsx src/__tests__/components-override.test.tsx; cd ../..
+```
+
+Expected: the first three pass unchanged. In `components-override`, the `tool-reset` and portalled `filter-clear` tests now pass; the icon-button tests still fail.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add packages/react/src/filter-menu/FilterMenu.tsx packages/react/src/tool-panel/ColumnsSection.tsx
+git commit -m "refactor(react): Clear and Reset columns render the kit Button, link variant
+
+The Clear button is inside the portalled filter dialog, which is the case
+the components context exists for.
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 10: Migrate the icon buttons (6 sites) and collapse the CSS
+
+**Files:**
+
+- Modify: `packages/react/src/filter-menu/FunnelButton.tsx`
+- Modify: `packages/react/src/column-menu/MenuButton.tsx`
+- Modify: `packages/react/src/tool-panel/ColumnsSection.tsx` (~L505–L530, the kebab)
+- Modify: `packages/react/src/group-panel/GroupPanel.tsx` (~L467–L486)
+- Modify: `packages/react/src/tool-panel/filters/FilterRow.tsx` (~L408–L420)
+- Modify: `packages/react/src/tool-panel/grouping/GroupingSection.tsx` (~L420–L430)
+- Modify: `packages/ui/grid.css` — collapse every site rule the component now owns
+
+- [ ] **Step 1: FunnelButton**
+
+Replace the file's body so the button is the kit's:
+
+```tsx
+// packages/react/src/filter-menu/FunnelButton.tsx
+import { createElement, type CSSProperties } from "react";
+import { usePretableComponents } from "../components/context";
+import { FunnelIcon } from "../icons";
+
+export function FunnelButton({
+  columnId,
+  label,
+  active,
+  open,
+  style,
+  onToggle,
+}: {
+  columnId: string;
+  label: string;
+  active: boolean;
+  open: boolean;
+  style?: CSSProperties;
+  onToggle: (columnId: string, anchor: HTMLElement) => void;
+}) {
+  const { IconButton } = usePretableComponents();
+  return (
+    <IconButton
+      site="filter-funnel"
+      data-pretable-filter-funnel=""
+      data-pretable-column-id={columnId}
+      data-pretable-filter-active={active ? "true" : "false"}
+      aria-haspopup="dialog"
+      aria-expanded={open}
+      aria-label={`Filter ${label}`}
+      style={style}
+      // (keep the existing tabIndex and pointerdown comments verbatim)
+      tabIndex={-1}
+      onPointerDown={(e) => e.stopPropagation()}
+      onClick={(e) => {
+        e.stopPropagation();
+        onToggle(columnId, e.currentTarget);
+      }}
+    >
+      <FunnelIcon />
+    </IconButton>
+  );
+}
+```
+
+Keep the two long comments that were on `tabIndex` and `onPointerDown` — copy them across unchanged; only the element and the two new lines (`import`, `site`) change.
+
+- [ ] **Step 2: MenuButton**
+
+Same shape: import `usePretableComponents` from `"../components/context"`, add `const { IconButton } = usePretableComponents();`, and replace `<button type="button" data-pretable-column-menu-button="" …>` with `<IconButton site="column-menu-button" data-pretable-column-menu-button="" …>` and its `</button>` with `</IconButton>`. The `ref={(node) => onNodeChange?.(columnId, node)}` callback stays exactly as it is — the component forwards it. Keep every comment.
+
+- [ ] **Step 3: ColumnsSection kebab**
+
+With `const { Button, IconButton } = usePretableComponents();` already in place from Task 9 (add `IconButton` to that destructuring), replace
+
+```tsx
+                    <button
+                      aria-expanded={openColumnId === entry.id}
+                      aria-haspopup="menu"
+                      aria-label={messages.toolPanelColumnMenuLabel({ label })}
+                      data-pretable-tool-row-menu-button=""
+```
+
+with
+
+```tsx
+                    <IconButton
+                      site="tool-row-menu-button"
+                      aria-expanded={openColumnId === entry.id}
+                      aria-haspopup="menu"
+                      aria-label={messages.toolPanelColumnMenuLabel({ label })}
+                      data-pretable-tool-row-menu-button=""
+```
+
+and its closing tag to `</IconButton>`; remove its `type="button"` line if present. The `ref` callback that fills `kebabNodesRef` stays.
+
+- [ ] **Step 4: GroupPanel chip remove**
+
+Import `usePretableComponents` from `"../components/context"`, add `const { IconButton } = usePretableComponents();` in the panel component, replace
+
+```tsx
+            <button
+              aria-label={`Remove ${label} from grouping`}
+              data-pretable-chip-remove=""
+```
+
+with
+
+```tsx
+            <IconButton
+              site="chip-remove"
+              aria-label={`Remove ${label} from grouping`}
+              data-pretable-chip-remove=""
+```
+
+its closing `</button>` (after `<CloseIcon />`) with `</IconButton>`, and drop any `type="button"`.
+
+- [ ] **Step 5: FilterRow remove, GroupingSection group remove**
+
+FilterRow: import from `"../../components/context"`, `const { IconButton } = usePretableComponents();`, and
+
+```tsx
+      <IconButton
+        site="filter-row-remove"
+        data-pretable-filter-row-remove=""
+        aria-label={messages.toolPanelRemoveFilterLabel({ label })}
+        onClick={onRemove}
+      >
+        <CloseIcon />
+      </IconButton>
+```
+
+(keep the comment about naming by what it removes). GroupingSection already destructures `Button`; extend it to `const { Button, IconButton } = usePretableComponents();` and replace the group-remove button with
+
+```tsx
+                <IconButton
+                  site="tool-group-remove"
+                  aria-label={messages.toolPanelRemoveGroupLabel({ label })}
+                  data-pretable-tool-group-remove=""
+                  onClick={() =>
+                    applyRowGroups(groupedIds.filter((id) => id !== columnId))
+                  }
+                >
+                  <CloseIcon />
+                </IconButton>
+```
+
+- [ ] **Step 6: Run the override tests — all green now**
+
+```bash
+cd packages/react && pnpm exec vitest run --environment jsdom src/__tests__/components-override.test.tsx; cd ../..
+```
+
+Expected: `Tests  7 passed (7)`.
+
+- [ ] **Step 7: Collapse the site CSS**
+
+In `packages/ui/grid.css`, edit each site rule to keep only what the component does not own. Exact edits:
+
+**`[data-pretable-filter-funnel]`** (~L886) — from
+
+```css
+    display: inline-flex; align-items: center; justify-content: center; width: 18px; height: 18px; padding: 0; border: 0; border-radius: var(--pretable-radius-control); background: transparent; color: var(--pretable-text-dim); cursor: pointer; opacity: 0; transition: opacity 0.1s ease; position: relative;
+```
+
+to
+
+```css
+    width: 18px;
+    height: 18px;
+    opacity: 0;
+    transition: opacity 0.1s ease;
+```
+
+(`color: var(--pretable-text-dim)` is now the icon-button default; keep the rule's comment.)
+
+**`[data-pretable-column-menu-button]`** (~L1164) — same reduction: keep `width: 18px; height: 18px; opacity: 0; transition: opacity 0.1s ease;`.
+
+**`[data-pretable-tool-row-menu-button]`** (~L1776) — keep `inline-size: 18px; block-size: 18px;` only.
+
+**`[data-pretable-chip-remove]`** (~L1127) — keep `width: 14px; height: 14px; font-size: 10px; line-height: 1;`.
+
+**`[data-pretable-filter-row-remove], [data-pretable-tool-group-remove]`** (~L1983) — keep `inline-size: 24px; block-size: 24px;`.
+
+**`[data-pretable-filter-clear]`** (~L1018) — keep `align-self: flex-end;` only.
+
+**`[data-pretable-tool-reset]`** (~L1811) — keep `align-self: flex-end;` only.
+
+**The ghost group** — delete the four-selector base rule (`display: inline-flex; … font: inherit;`), its `:hover:not(:disabled)` rule, its `:focus-visible` rule and its `:disabled` rule entirely: the component rules carry all four. Keep the two grouping-layout rules that follow them (`[data-pretable-tool-grouping] [data-pretable-add-group] { align-self: flex-start }` and the `> div:has([data-pretable-expand-all])` row rule).
+
+**Focus rings** — remove `[data-pretable-filter-clear]:focus-visible` from the filter-dialog ring list, and `[data-pretable-filter-row-remove]:focus-visible, [data-pretable-tool-group-remove]:focus-visible` from the builder ring list. The other entries in those lists (selects, inputs) stay.
+
+Every comment that explained a site's reason for a size, a reveal or an alignment stays with the declaration it explains. Comments that explained the box now live on the component rules (Task 6).
+
+- [ ] **Step 8: Run the ui suite — Task 7's guard goes green**
+
+```bash
+cd packages/ui && pnpm exec vitest run; cd ../..
+```
+
+Expected: all pass, including `a push-button site rule declares only what is its own`.
+
+- [ ] **Step 9: Mutation-check the two new guards**
+
+Temporarily add `border: 0;` back into the `[data-pretable-filter-funnel]` rule; run the ui suite; it must FAIL naming that selector; revert. Temporarily change the ghost hover selector to drop `:not(:disabled)`; run; it must FAIL; revert. Record both outcomes in the commit message.
+
+- [ ] **Step 10: Commit**
+
+```bash
+git add packages/react/src packages/ui/grid.css
+git commit -m "refactor(react,ui): the six icon buttons render the kit IconButton; site rules collapse
+
+Funnel, column menu, row kebab, chip remove, filter-row remove and group
+remove. Every site keeps its attribute, its size, its reveal and its
+alignment; the box, ring and disabled ink move to the component rules. The
+site-rule guard passes; mutation-checked by restoring border: 0 on one site
+and dropping :not(:disabled) from the ghost hover — both fail it.
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 11: Public API, and the type test against the package
+
+**Files:**
+
+- Modify: `packages/react/src/public_api.ts`
+- Modify: `type-tests/react/components-button.types.tsx` (imports)
+- Modify: `packages/react/react.api.md` (generated)
+
+- [ ] **Step 1: Export**
+
+In `public_api.ts`, after the `PretableStatus` component export block, add:
+
+```ts
+export { PretableButton, PretableIconButton } from "./components/button";
+export type {
+  PretableBuiltInButtonSite,
+  PretableButtonProps,
+  PretableButtonSite,
+  PretableButtonVariant,
+  PretableIconButtonProps,
+} from "./components/button";
+export type {
+  PretableButtonComponent,
+  PretableComponents,
+  PretableIconButtonComponent,
+} from "./components/context";
+```
+
+- [ ] **Step 2: Point the type test at the package**
+
+In `type-tests/react/components-button.types.tsx`, change the first import's source from `"../../packages/react/src/components/button"` to `"@pretable/react"` and add `type PretableComponents` to its list; append:
+
+```tsx
+// A replacement is written against the same props the built-in receives.
+const components: PretableComponents = {
+  Button: PretableButton,
+  IconButton: PretableIconButton,
+};
+export type ComponentsIsOptional = Expect<
+  Equal<PretableComponents["Button"], PretableComponents["Button"] | undefined>
+>;
+void components;
+```
+
+- [ ] **Step 3: Build, regenerate the report, run the public typecheck**
+
+```bash
+pnpm build && pnpm api && pnpm typecheck:public && pnpm api:check
+```
+
+Expected: `pnpm api` rewrites `packages/react/react.api.md` with the new `@public` symbols; `typecheck:public` exits 0; `api:check` reports the report is fresh.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add packages/react/src/public_api.ts packages/react/react.api.md type-tests/react/components-button.types.tsx
+git commit -m "feat(react): export the kit buttons and the components slot types
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 12: Re-measure the pixels
+
+**Files:**
+
+- Output: `<scratchpad>/buttons-after.json`
+
+- [ ] **Step 1: Build, serve, measure**
+
+```bash
+pnpm build && (cd apps/website && pnpm exec next start -p 3117 > /tmp/pt-server.log 2>&1 &) && sleep 6
+cp <scratchpad>/measure-buttons.mjs apps/website/measure.tmp.mjs && (cd apps/website && node measure.tmp.mjs <scratchpad>/buttons-after.json); rm -f apps/website/measure.tmp.mjs
+```
+
+Expected: `all 12 sites measured`.
+
+- [ ] **Step 2: Diff**
+
+```bash
+node -e '
+const a = require("<scratchpad>/buttons-before.json"), b = require("<scratchpad>/buttons-after.json");
+let diffs = 0;
+for (const site of Object.keys(a)) {
+  const flat = (o, p = "") => Object.entries(o).flatMap(([k, v]) => typeof v === "object" && v ? flat(v, p + k + ".") : [[p + k, v]]);
+  const A = Object.fromEntries(flat(a[site])), B = Object.fromEntries(flat(b[site]));
+  for (const k of Object.keys(A)) if (A[k] !== B[k]) { diffs++; console.log(`${site}  ${k}: ${A[k]}  ->  ${B[k]}`); }
+}
+console.log(diffs ? `${diffs} DIFFERENCES` : "no pixel moved");
+'
+```
+
+Expected: `no pixel moved`. Any line printed is a finding: read the site's collapsed rule against its baseline and restore the declaration that carried the difference. The one acceptable kind of change is a **rendered-equal** value — `font: inherit` resolving to the same family and size the button already inherited — and even that is confirmed by the diff, not assumed.
+
+- [ ] **Step 3: Stop the server; no commit unless a rule was corrected**
+
+```bash
+pkill -f "next start -p 3117"
+```
+
+If Step 2 required a CSS correction, commit it with a message naming the site and the declaration.
+
+---
+
+### Task 13: Docs page, example, nav, registry
+
+**Files:**
+
+- Create: `apps/website/content/examples/components-button/example.ts`, `demo.tsx`, `ComponentsGrid.tsx`, `BrandButton.tsx`, `data.ts`
+- Create: `apps/website/content/docs/grid/components.mdx`
+- Modify: `apps/website/app/docs/_nav.ts`
+- Modify: `apps/website/lib/docs/__tests__/docs-api-surface.test.ts` (`TABLES`)
+- Modify: `apps/website/content/docs/grid/pretable-surface.mdx` (Configuration table), `apps/website/content/docs/grid/pretable-component.mdx` (forwarded-props sentence)
+
+- [ ] **Step 1: The example**
+
+```ts
+// apps/website/content/examples/components-button/example.ts
+import { defineExample } from "../../../lib/docs/examples/define";
+
+export default defineExample({
+  title: "Replacing a component",
+  description:
+    "The grid's own tool panel and filter dialog, with every Button replaced by the app's — one slot, applied everywhere, branching on `site` for the one place it treats differently.",
+  files: ["ComponentsGrid.tsx", "BrandButton.tsx", "data.ts"],
+});
+```
+
+```tsx
+// apps/website/content/examples/components-button/demo.tsx
+import { ComponentsGrid } from "./ComponentsGrid";
+
+export default function Demo() {
+  return <ComponentsGrid />;
+}
+```
+
+```ts
+// apps/website/content/examples/components-button/data.ts
+export interface Trade {
+  id: string;
+  symbol: string;
+  side: "Buy" | "Sell";
+  qty: number;
+  price: number;
+}
+
+export const trades: Trade[] = [
+  { id: "t1", symbol: "AAPL", side: "Buy", qty: 100, price: 226.11 },
+  { id: "t2", symbol: "MSFT", side: "Sell", qty: 40, price: 418.38 },
+  { id: "t3", symbol: "NVDA", side: "Buy", qty: 25, price: 869.63 },
+  { id: "t4", symbol: "AMZN", side: "Buy", qty: 60, price: 183.91 },
+  { id: "t5", symbol: "META", side: "Sell", qty: 15, price: 509.62 },
+];
+```
+
+```tsx
+// apps/website/content/examples/components-button/BrandButton.tsx
+import { forwardRef } from "react";
+import type { PretableButtonProps } from "@pretable/react";
+
+/**
+ * The app's own button, standing in for every Button the grid renders. It
+ * receives exactly what pretable's does — `site` included — and forwards its
+ * ref, which is the one thing the grid asks of a replacement: menus anchor on
+ * the node, and focus returns to it.
+ */
+export const BrandButton = forwardRef<HTMLButtonElement, PretableButtonProps>(
+  function BrandButton({ site, variant, className, ...props }, ref) {
+    // One place treated differently: the reset is destructive, so it gets
+    // the app's danger styling. Everything else is the brand default.
+    const tone = site === "tool-reset" ? "danger" : variant;
+    return (
+      <button
+        {...props}
+        ref={ref}
+        type="button"
+        className={["brand-button", `brand-button--${tone}`, className]
+          .filter(Boolean)
+          .join(" ")}
+      />
+    );
+  },
+);
+```
+
+```tsx
+// apps/website/content/examples/components-button/ComponentsGrid.tsx
+import { PretableSurface, type PretableColumn } from "@pretable/react";
+
+import { BrandButton } from "./BrandButton";
+import { trades, type Trade } from "./data";
+
+const columns: PretableColumn<Trade>[] = [
+  { id: "symbol", header: "Symbol", widthPx: 110, type: "text" },
+  { id: "side", header: "Side", widthPx: 90, type: "enum" },
+  { id: "qty", header: "Qty", widthPx: 90, type: "number" },
+  { id: "price", header: "Price", widthPx: 110, type: "number" },
+];
+
+export function ComponentsGrid() {
+  return (
+    <>
+      <style>{`
+        .brand-button { border: 0; border-radius: 999px; padding: 0 12px; height: 26px; font: inherit; font-weight: 600; cursor: pointer; }
+        .brand-button--ghost { background: #eef2ff; color: #3730a3; }
+        .brand-button--link { background: transparent; color: #3730a3; padding: 0 4px; }
+        .brand-button--danger { background: #fee2e2; color: #991b1b; }
+        .brand-button:disabled { opacity: 0.5; cursor: default; }
+      `}</style>
+      <PretableSurface
+        ariaLabel="Trades"
+        columns={columns}
+        components={{ Button: BrandButton }}
+        getRowId={(row) => row.id}
+        rows={trades}
+        toolPanel={{ defaultActiveSection: "columns" }}
+        viewportHeight={320}
+      />
+    </>
+  );
+}
+```
+
+Then regenerate the registry and check it:
+
+```bash
+cd apps/website && pnpm examples:gen && pnpm examples:check; cd ../..
+```
+
+Expected: `Wrote registry for 44 examples.` (one more than before) and the check exits 0.
+
+- [ ] **Step 2: The docs page**
+
+```mdx
+---
+title: Components
+description: "The kit components the grid renders its own chrome from — Button and IconButton — how to style them, and how to replace either with your own."
+nav: Grid
+---
+
+`@pretable/react` renders its own controls from a small component kit, and
+ships those components for you to use and to replace. This page covers the
+first two: `PretableButton` and `PretableIconButton`. Here is a grid whose
+every button is the app's own:
+
+<Example id="components-button" />
+
+## The components
+
+Both render `<button type="button">`, always — every grid button is one, and
+a stray submit inside your `<form>` is a real bug class, so `type` is not a
+prop. `className` and `style` pass through and merge with the component's
+own attributes. Both forward their `ref` to the button node.
+
+### Button
+
+A labelled push-button in one of the grid's two looks.
+
+| Prop      | Type                    | Notes                                                                                  |
+| --------- | ----------------------- | -------------------------------------------------------------------------------------- |
+| `variant` | `"ghost" \| "link"`     | `ghost` is the 24px action with a hover tint; `link` is plain accent text. Default `ghost`. |
+| `site`    | `PretableButtonSite`    | Where in the grid the button is; lands as `data-pretable-site`. Open to your own names. |
+
+### IconButton
+
+An icon-only push-button. `aria-label` is **required** — it is the button's
+only accessible name, and omitting it is a compile error rather than an
+accessibility failure discovered later.
+
+| Prop         | Type                 | Notes                                                                 |
+| ------------ | -------------------- | --------------------------------------------------------------------- |
+| `aria-label` | `string`             | Required. The accessible name.                                        |
+| `site`       | `PretableButtonSite` | Where in the grid the button is; lands as `data-pretable-site`.       |
+
+## Styling
+
+The styling channel is the one the whole grid uses: attributes and tokens.
+Every button carries `data-pretable-button` or `data-pretable-icon-button`,
+its `data-pretable-variant`, and its `data-pretable-site`; the grid's own
+sites also keep their original attribute (`data-pretable-filter-clear`,
+`data-pretable-tool-reset`, …), so a selector you already wrote keeps
+matching.
+
+```css
+[data-pretable-button][data-pretable-variant="ghost"] {
+  --pretable-accent: rebeccapurple;
+}
+[data-pretable-site="tool-reset"] {
+  color: var(--pretable-text-error);
+}
+```
+
+## Replacing a component
+
+Pass `components` to `<PretableSurface>` (or `<Pretable>`) with one entry per
+component type you want to replace. The replacement is used everywhere that
+type appears — the tool panel, the header, and the portalled filter dialog —
+and receives exactly the props the built-in does, `site` included, so it can
+branch on where it is.
+
+| Prop         | Type                          | Notes                                                                         |
+| ------------ | ----------------------------- | ----------------------------------------------------------------------------- |
+| `Button`     | `PretableButtonComponent`     | Receives `PretableButtonProps`; must forward its `ref` to the button node.     |
+| `IconButton` | `PretableIconButtonComponent` | Receives `PretableIconButtonProps`; must forward its `ref` to the button node. |
+
+Forwarding the `ref` is the one obligation on a replacement: the grid anchors
+menus on the node and returns keyboard focus to it. The set of built-in
+`site` names is documented in the `PretableBuiltInButtonSite` type and grows
+additively — a new grid button may introduce a new site without a major bump.
+```
+
+- [ ] **Step 3: Nav, surface page, preset page**
+
+In `apps/website/app/docs/_nav.ts`, in the Grid section directly after the `Cell presentations` entry, add:
+
+```ts
+      { title: "Components", href: "/docs/grid/components" },
+```
+
+In `apps/website/content/docs/grid/pretable-surface.mdx`'s Configuration table, add a row after `Rendering`:
+
+```md
+| Components         | `components` — replace a kit component everywhere; see [Components](/docs/grid/components) |
+```
+
+In `apps/website/content/docs/grid/pretable-component.mdx`, in the sentence listing what the concise preset forwards (~L45), add "the components slot," after "messages,".
+
+- [ ] **Step 4: Register the three tables**
+
+In `docs-api-surface.test.ts`'s `TABLES`, after the `grid/tool-panel.mdx#The descriptor` entry, add:
+
+```ts
+  // The kit's first two components (SP1). `complete: true` on each: the
+  // table is the page's statement of the component's own props (the native
+  // button attributes it extends are not reported members), and a prop
+  // growing on the type without a row here is exactly the drift this file
+  // exists to catch.
+  "grid/components.mdx#Button": {
+    types: [{ pkg: "react", name: "PretableButtonProps" }],
+    complete: true,
+  },
+  "grid/components.mdx#IconButton": {
+    types: [{ pkg: "react", name: "PretableIconButtonProps" }],
+    complete: true,
+  },
+  "grid/components.mdx#Replacing a component": {
+    types: [{ pkg: "react", name: "PretableComponents" }],
+    complete: true,
+  },
+```
+
+- [ ] **Step 5: Run the docs guards and the website unit suite**
+
+```bash
+cd apps/website && pnpm exec vitest run --environment jsdom lib/docs app/docs; cd ../..
+```
+
+Expected: all pass. If the api-surface guard reports a row/member mismatch, the message names the table and the member — fix the table (or the registration's `complete` flag with a `partialReason`), not the guard.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add apps/website/content/examples/components-button apps/website/content/docs/grid/components.mdx apps/website/app/docs/_nav.ts apps/website/lib/docs/__tests__/docs-api-surface.test.ts apps/website/content/docs/grid/pretable-surface.mdx apps/website/content/docs/grid/pretable-component.mdx apps/website/lib/docs/examples/registry.ts
+git commit -m "docs: the Components page, its live example, and the registered tables
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+(If the registry file generated by `examples:gen` has a different path, add that path instead of `registry.ts`; `git status` shows it.)
+
+---
+
+### Task 14: Fixture page and browser proof
+
+**Files:**
+
+- Create: `apps/website/app/fixtures/components/page.tsx`
+- Create: `apps/website/e2e/components.spec.ts`
+
+- [ ] **Step 1: The fixture**
+
+```tsx
+// apps/website/app/fixtures/components/page.tsx
+"use client";
+
+import {
+  PretableSurface,
+  type PretableButtonComponent,
+  type PretableColumn,
+  type PretableIconButtonComponent,
+} from "@pretable/react";
+import { forwardRef } from "react";
+
+/**
+ * Test fixture for `apps/website/e2e/components.spec.ts`.
+ *
+ * The unit suite proves the components context in jsdom. What only a real
+ * browser can prove is that a replacement lands inside a popover the grid
+ * PORTALS into document.body — the case the context exists for — and that
+ * the grid's behaviour on that replacement (the menu it anchors, the focus
+ * it returns) survives. Both slots are replaced with components that mark
+ * themselves and record their `site`.
+ *
+ * Deliberately not part of the product surface; `fixtures/layout.tsx` keeps
+ * the route out of search engines.
+ */
+
+interface Row {
+  id: string;
+  name: string;
+  qty: number;
+}
+
+const ROWS: Row[] = [
+  { id: "a", name: "Alpha", qty: 1 },
+  { id: "b", name: "Bravo", qty: 2 },
+  { id: "c", name: "Charlie", qty: 3 },
+];
+
+const COLUMNS: PretableColumn<Row>[] = [
+  { id: "name", header: "Name", widthPx: 160, type: "text" },
+  { id: "qty", header: "Qty", widthPx: 100, type: "number" },
+];
+
+const FixtureButton: PretableButtonComponent = forwardRef(function FixtureButton(
+  { site, variant, ...props },
+  ref,
+) {
+  return (
+    <button
+      {...props}
+      ref={ref}
+      type="button"
+      data-fixture-button={site ?? ""}
+      data-fixture-variant={variant}
+    />
+  );
+});
+
+const FixtureIconButton: PretableIconButtonComponent = forwardRef(
+  function FixtureIconButton({ site, ...props }, ref) {
+    return <button {...props} ref={ref} type="button" data-fixture-icon={site ?? ""} />;
+  },
+);
+
+export default function ComponentsFixturePage() {
+  return (
+    <main style={{ padding: 24 }}>
+      <PretableSurface
+        ariaLabel="components-fixture"
+        columns={COLUMNS}
+        components={{ Button: FixtureButton, IconButton: FixtureIconButton }}
+        getRowId={(row) => row.id}
+        rows={ROWS}
+        toolPanel={{ defaultActiveSection: "columns" }}
+        viewportHeight={240}
+      />
+    </main>
+  );
+}
+```
+
+- [ ] **Step 2: The spec**
+
+```ts
+// apps/website/e2e/components.spec.ts
+import { expect, test } from "@playwright/test";
+
+import { waitForGridReady } from "./helpers";
+
+/**
+ * The `components` slot in a real browser. The jsdom suite proves the
+ * context resolves and reaches the sites; a browser is needed for the two
+ * claims that depend on the real DOM: that a replacement lands inside a
+ * popover portalled to document.body, and that the grid's own behaviour on
+ * the replacement — the menu it anchors on the node, the focus it returns
+ * there — still works through the forwarded ref.
+ */
+test("every button in the grid is the consumer's, including inside the portalled filter dialog", async ({ page }) => {
+  await page.goto("/fixtures/components");
+  await waitForGridReady(page);
+
+  // Nothing the kit draws itself is left.
+  await expect(page.locator("[data-pretable-button]")).toHaveCount(0);
+  await expect(page.locator("[data-pretable-icon-button]")).toHaveCount(0);
+
+  // The tool panel's reset is the replacement, with its site and variant.
+  const reset = page.locator("[data-pretable-tool-reset]");
+  await expect(reset).toHaveAttribute("data-fixture-button", "tool-reset");
+  await expect(reset).toHaveAttribute("data-fixture-variant", "link");
+
+  // The header funnel is the icon replacement; open its dialog.
+  await page.locator("[data-pretable-header-cell]").first().hover();
+  const funnel = page.locator("[data-pretable-filter-funnel]").first();
+  await expect(funnel).toHaveAttribute("data-fixture-icon", "filter-funnel");
+  await funnel.click();
+
+  // The dialog is a child of <body>, and its Clear button is ours.
+  const dialog = page.locator("[data-pretable-filter-menu]");
+  await expect(dialog).toBeVisible();
+  expect(await dialog.evaluate((el) => el.parentElement === document.body)).toBe(true);
+  await expect(dialog.locator("[data-pretable-filter-clear]")).toHaveAttribute(
+    "data-fixture-button",
+    "filter-clear",
+  );
+  await page.keyboard.press("Escape");
+});
+
+test("the grid still anchors a menu on, and returns focus to, a replaced icon button", async ({ page }) => {
+  await page.goto("/fixtures/components");
+  await waitForGridReady(page);
+
+  const kebab = page.locator("[data-pretable-tool-row-menu-button]").first();
+  await expect(kebab).toHaveAttribute("data-fixture-icon", "tool-row-menu-button");
+  await kebab.click();
+  const menu = page.locator("[data-pretable-column-menu]");
+  await expect(menu).toBeVisible();
+
+  // The menu opened below the node the replacement forwarded its ref to.
+  const [kebabBox, menuBox] = await Promise.all([kebab.boundingBox(), menu.boundingBox()]);
+  expect(menuBox!.y).toBeGreaterThanOrEqual(kebabBox!.y + kebabBox!.height);
+
+  // Escape closes it and puts focus back on that node.
+  await page.keyboard.press("Escape");
+  await expect(menu).toHaveCount(0);
+  await expect(kebab).toBeFocused();
+});
+```
+
+- [ ] **Step 3: Build, serve, run it**
+
+```bash
+pnpm build && (cd apps/website && pnpm exec next start -p 3117 > /tmp/pt-server.log 2>&1 &) && sleep 6
+cd apps/website && BASE_URL=http://localhost:3117 pnpm exec playwright test components --workers=1 --reporter=line; cd ../..
+```
+
+Expected: `4 passed` (2 tests × chromium + webkit). Keep the server up for Task 15.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add apps/website/app/fixtures/components/page.tsx apps/website/e2e/components.spec.ts
+git commit -m "test(website): the components slot in a real browser
+
+A replacement lands inside the portalled filter dialog, and the grid still
+anchors its menu on and returns focus to a replaced icon button.
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 15: Full verification, changeset, PR
+
+- [ ] **Step 1: Everything, from the root**
+
+```bash
+pnpm format:write >/dev/null; pnpm format && pnpm lint && pnpm typecheck && pnpm typecheck:public && pnpm api:check && pnpm test && pnpm bench:e2e
+```
+
+Expected: every command exits 0; `bench:e2e` prints `29 passed` or more.
+
+- [ ] **Step 2: The website e2e suites the migration touches**
+
+```bash
+cd apps/website && BASE_URL=http://localhost:3117 pnpm exec playwright test smoke tool-panel grid-header-keyboard grid-header-popover-scroll grouping components --workers=1 --reporter=line; cd ../..
+pkill -f "next start -p 3117"
+```
+
+Expected: all pass. A failure in `tool-panel` or `grid-header-keyboard` naming a button is a migrated site that lost a behaviour — `tabIndex`, `onPointerDown`, a `ref` — compare the site against Tasks 8–10 and restore it.
+
+- [ ] **Step 3: Changeset**
+
+```md
+<!-- .changeset/components-sp1-button.md -->
+---
+"@pretable/react": minor
+"@pretable/ui": patch
+---
+
+The first two components of a kit the grid renders its own chrome from, and a
+`components` prop to replace either with your own.
+
+`PretableButton` (two looks: `ghost`, the 24px action with a hover tint, and
+`link`, plain accent text) and `PretableIconButton` (an icon-only button whose
+`aria-label` is a required prop — omitting the accessible name is now a
+compile error). Both are always `type="button"`, pass `className` and `style`
+through, forward their `ref`, and carry `data-pretable-button` /
+`data-pretable-icon-button`, `data-pretable-variant` and `data-pretable-site`
+for styling through the grid's usual attributes-and-tokens channel.
+
+`components={{ Button, IconButton }}` on `<PretableSurface>` and `<Pretable>`
+replaces a component everywhere it appears — the tool panel, the header, and
+the portalled filter dialog — and the replacement receives exactly the props
+the built-in does, `site` included, so it can branch on where in the grid it
+is. It must forward its `ref`; the grid anchors menus on and returns focus to
+that node.
+
+The grid's twelve plain push-buttons now render from these. Each keeps its
+original attribute (`data-pretable-filter-clear`, …), so selectors and
+stylesheets keyed on them keep working; the shared look moved from twelve
+site rules onto the component rules, and no pixel moved — measured before and
+after on every site.
+```
+
+- [ ] **Step 4: Commit, push, PR**
+
+```bash
+git add .changeset/components-sp1-button.md
+git commit -m "chore: changeset for components SP1
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+git push -u origin HEAD
+gh pr create --title "feat(react): PretableButton, PretableIconButton, and the components slot" --body-file <(cat <<'EOF'
+Components SP1 — the contract, proven on the grid's twelve plain push-buttons. Spec: `docs/superpowers/specs/2026-09-04-components-sp1-button-design.md`.
+
+## What ships
+
+- `PretableButton` (`ghost` | `link`) and `PretableIconButton` (`aria-label` required — a compile error, not a WCAG failure found later). Always `type="button"`; `className`/`style` pass through; `ref` forwarded; styled through `data-pretable-button` / `-icon-button` / `-variant` / `-site`.
+- `components={{ Button, IconButton }}` on the surface and the preset: one slot per type, applied everywhere, resolved once and memoised on slot identity, delivered by context so the **portalled** filter dialog gets it too.
+- The twelve sites migrated. Every site keeps its original attribute, so nothing that identified a button stops identifying it. The shared look moved from twelve site rules onto the component rules; `grid.css` is smaller.
+
+## Verification
+
+- **No pixel moved.** Every site's computed longhands, box and focus ring were recorded before Task 2 and re-measured after Task 11 with the same script; the diff is empty.
+- Guards: kit rules present with the standard ring/disabled/hover discipline; every site rule declares only what is its own (mutation-checked both ways); the docs page's three tables registered with the api-surface guard.
+- jsdom: components, context, and the override through the surface — including a replacement inside the portalled dialog and a same-components re-render that does not remount.
+- Browser: `/fixtures/components` — every button is the consumer's, the dialog's Clear is a child of `<body>` and is the replacement, and a replaced kebab still anchors its menu and gets focus back.
+- `format`, `lint`, `typecheck`, `typecheck:public`, `api:check`, `test`, `bench:e2e`, and the website's smoke / tool-panel / header-keyboard / popover-scroll / grouping / components suites all pass.
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)
+gh pr merge --squash --auto
+```
+
+Expected: the PR URL, and auto-merge armed. Watch it for `FAILURE` **and** `CANCELLED` — a cancelled required job skips the deploy jobs and leaves the PR `BLOCKED` with an empty failure list.
+
+---
+
+## Self-review against the spec
+
+- **Placement** → Task 2, Task 11. **Components + guarantees** → Task 2 (type=button, passthrough, ref, attributes), Task 6 (ring, disabled, forced colours), Task 3 (aria-label required, no `type`, open `site`). **Override contract + plumbing** → Tasks 4, 5. **Migration, attributes kept, CSS collapse** → Tasks 8–10. **Pixel must not move** → Tasks 1, 12. **Testing** → Tasks 2–5 (jsdom, types), 6–7 (CSS guards, mutation), 14 (browser, portal, ref), 15 (bench + e2e), a11y names via `getByRole(name)` in Task 5. **Docs, registry, minor changeset** → Tasks 13, 15. **Excel light-only** → no task; recorded in the spec.
+- Names used consistently: `PretableButton`, `PretableIconButton`, `PretableButtonProps`, `PretableIconButtonProps`, `PretableButtonVariant`, `PretableButtonSite`, `PretableBuiltInButtonSite`, `PretableComponents`, `PretableButtonComponent`, `PretableIconButtonComponent`, `DEFAULT_COMPONENTS`, `PretableComponentsProvider`, `usePretableComponents`, `useResolvedComponents`; attributes `data-pretable-button`, `data-pretable-icon-button`, `data-pretable-variant`, `data-pretable-site`.
+- Line numbers are anchors from the tree at `aa3c64ae`; the surrounding code shown in each step is what to match.

From 700904a45393d808681c2a8c7e8bf4b4aea95e18 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 10:04:26 -0700
Subject: [PATCH 04/31] feat(react): PretableButton and PretableIconButton

The kit's first two components. Always type="button"; className and style
pass through; the contract attributes follow the spread so no prop displaces
them; IconButton's accessible name is a required prop.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../src/__tests__/components-button.test.tsx  | 112 +++++++++++++
 packages/react/src/components/button.tsx      | 156 ++++++++++++++++++
 2 files changed, 268 insertions(+)
 create mode 100644 packages/react/src/__tests__/components-button.test.tsx
 create mode 100644 packages/react/src/components/button.tsx

diff --git a/packages/react/src/__tests__/components-button.test.tsx b/packages/react/src/__tests__/components-button.test.tsx
new file mode 100644
index 00000000..c2433a07
--- /dev/null
+++ b/packages/react/src/__tests__/components-button.test.tsx
@@ -0,0 +1,112 @@
+import "@testing-library/jest-dom/vitest";
+import { cleanup, render } from "@testing-library/react";
+import { createRef } from "react";
+import { afterEach, describe, expect, test } from "vitest";
+
+import { PretableButton, PretableIconButton } from "../components/button";
+
+afterEach(() => {
+  cleanup();
+});
+
+describe("PretableButton", () => {
+  test("is always type=button, and carries its attributes", () => {
+    // Every grid button is type="button" today; a stray submit inside a
+    // consumer's <form> is a real bug class, so `type` is not a prop at all.
+    const { container } = render(
+      <PretableButton site="filter-clear">Clear</PretableButton>,
+    );
+    const button = container.querySelector("button")!;
+    expect(button).toHaveAttribute("type", "button");
+    expect(button).toHaveAttribute("data-pretable-button", "");
+    expect(button).toHaveAttribute("data-pretable-variant", "ghost");
+    expect(button).toHaveAttribute("data-pretable-site", "filter-clear");
+    expect(button).toHaveTextContent("Clear");
+  });
+
+  test("takes the link variant, and leaves the site attribute off when none is given", () => {
+    const { container } = render(
+      <PretableButton variant="link">Reset</PretableButton>,
+    );
+    const button = container.querySelector("button")!;
+    expect(button).toHaveAttribute("data-pretable-variant", "link");
+    expect(button).not.toHaveAttribute("data-pretable-site");
+  });
+
+  test("passes className, style and any other button attribute through", () => {
+    // The styling channel is the attributes plus the consumer's own class —
+    // a component that dropped className would have no styling channel.
+    const { container } = render(
+      <PretableButton
+        className="mine"
+        style={{ marginLeft: 4 }}
+        disabled
+        data-pretable-tool-reset=""
+        aria-describedby="why"
+      >
+        x
+      </PretableButton>,
+    );
+    const button = container.querySelector("button")!;
+    expect(button).toHaveClass("mine");
+    expect(button.style.marginLeft).toBe("4px");
+    expect(button).toBeDisabled();
+    expect(button).toHaveAttribute("data-pretable-tool-reset", "");
+    expect(button).toHaveAttribute("aria-describedby", "why");
+  });
+
+  test("forwards its ref to the button node", () => {
+    // The tool panel returns focus to button nodes and anchors menus on
+    // them; a component that hid the node would break both.
+    const ref = createRef<HTMLButtonElement>();
+    render(<PretableButton ref={ref}>x</PretableButton>);
+    expect(ref.current).toBeInstanceOf(HTMLButtonElement);
+  });
+
+  test("a consumer cannot override the contract attributes by spreading", () => {
+    // The data attributes follow the spread on purpose: they are the
+    // component's contract with grid.css, not inputs.
+    const { container } = render(
+      // @ts-expect-error — proving the runtime order, not the types
+      <PretableButton data-pretable-button="no" type="submit">
+        x
+      </PretableButton>,
+    );
+    const button = container.querySelector("button")!;
+    expect(button).toHaveAttribute("data-pretable-button", "");
+    expect(button).toHaveAttribute("type", "button");
+  });
+});
+
+describe("PretableIconButton", () => {
+  test("carries the icon-button attributes and its required name", () => {
+    const { container } = render(
+      <PretableIconButton aria-label="Remove Alpha" site="chip-remove">
+        <svg />
+      </PretableIconButton>,
+    );
+    const button = container.querySelector("button")!;
+    expect(button).toHaveAttribute("type", "button");
+    expect(button).toHaveAttribute("data-pretable-icon-button", "");
+    expect(button).toHaveAttribute("data-pretable-site", "chip-remove");
+    expect(button).not.toHaveAttribute("data-pretable-variant");
+    expect(button).toHaveAccessibleName("Remove Alpha");
+  });
+
+  test("forwards its ref and passes attributes through", () => {
+    const ref = createRef<HTMLButtonElement>();
+    const { container } = render(
+      <PretableIconButton
+        ref={ref}
+        aria-label="Filter Title"
+        tabIndex={-1}
+        aria-expanded={false}
+        data-pretable-filter-funnel=""
+      />,
+    );
+    expect(ref.current).toBe(container.querySelector("button"));
+    expect(ref.current).toHaveAttribute("tabindex", "-1");
+    expect(ref.current).toHaveAttribute("aria-expanded", "false");
+    expect(ref.current).toHaveAttribute("data-pretable-filter-funnel", "");
+  });
+});
diff --git a/packages/react/src/components/button.tsx b/packages/react/src/components/button.tsx
new file mode 100644
index 00000000..44e8c206
--- /dev/null
+++ b/packages/react/src/components/button.tsx
@@ -0,0 +1,156 @@
+/**
+ * The kit's push-buttons — the first two components of a collection the grid
+ * renders its own chrome from and a consumer can replace per type through
+ * `components` on the surface (see `./context.ts`).
+ *
+ * Both render `<button type="button">`, always: every grid button is
+ * `type="button"`, and a stray submit inside a consumer's `<form>` is a real
+ * bug class, so `type` is not a prop. `className` and `style` pass through
+ * and merge — the component sets neither, so the consumer's IS the merge —
+ * and the contract attributes follow the spread so no prop can displace them.
+ *
+ * Styled by `@pretable/ui`'s grid.css through the attributes written here.
+ * That is the whole styling channel: `data-pretable-button` /
+ * `data-pretable-icon-button` for the shared box, `data-pretable-variant` for
+ * the two labelled looks, `data-pretable-site` for where in the grid the
+ * button sits. A site's own attribute (`data-pretable-filter-clear`) still
+ * arrives through the spread, so nothing that identified a button before
+ * these existed stops identifying it.
+ */
+import {
+  createElement,
+  forwardRef,
+  type ButtonHTMLAttributes,
+  type ReactElement,
+} from "react";
+
+/**
+ * The two labelled looks the grid uses: `ghost` (a 24px box with a hover
+ * tint — `+ filter`, `Expand all`) and `link` (plain accent text — `Clear`,
+ * `Reset columns`).
+ *
+ * @public
+ */
+export type PretableButtonVariant = "ghost" | "link";
+
+/**
+ * Where in the grid a built-in button sits. Each name is the site's own
+ * `data-pretable-*` attribute suffix, so there is one vocabulary, not two.
+ *
+ * @public
+ */
+export type PretableBuiltInButtonSite =
+  | "filter-add"
+  | "add-group"
+  | "expand-all"
+  | "collapse-all"
+  | "filter-clear"
+  | "tool-reset"
+  | "filter-funnel"
+  | "column-menu-button"
+  | "tool-row-menu-button"
+  | "chip-remove"
+  | "filter-row-remove"
+  | "tool-group-remove";
+
+/**
+ * A built-in site, or any string: autocomplete for the grid's own, no type
+ * error when a consumer names one of theirs. Same shape as
+ * `PretableToolPanelSectionId`.
+ *
+ * @public
+ */
+export type PretableButtonSite = PretableBuiltInButtonSite | (string & {});
+
+/**
+ * Props for {@link PretableButton}.
+ *
+ * @public
+ */
+export interface PretableButtonProps extends Omit<
+  ButtonHTMLAttributes<HTMLButtonElement>,
+  "type"
+> {
+  /** The labelled look. Default: `"ghost"`. */
+  variant?: PretableButtonVariant;
+  /**
+   * Where in the grid this button is; lands as `data-pretable-site`. A
+   * replacement passed through `components` receives it and can branch on it.
+   * Named `site`, not `role`: `role` is the ARIA attribute on every button.
+   */
+  site?: PretableButtonSite;
+}
+
+/**
+ * Props for {@link PretableIconButton}.
+ *
+ * @public
+ */
+export interface PretableIconButtonProps extends Omit<
+  ButtonHTMLAttributes<HTMLButtonElement>,
+  "type" | "aria-label"
+> {
+  /**
+   * Required. An icon-only button has no other accessible name, so omitting
+   * it is a compile error rather than a WCAG failure discovered later.
+   */
+  "aria-label": string;
+  /** Where in the grid this button is; lands as `data-pretable-site`. */
+  site?: PretableButtonSite;
+}
+
+/**
+ * A labelled push-button in one of the grid's two looks.
+ *
+ * ```tsx
+ * <PretableButton variant="link" site="filter-clear" onClick={clear}>
+ *   Clear
+ * </PretableButton>
+ * ```
+ *
+ * @public
+ */
+export const PretableButton = forwardRef<
+  HTMLButtonElement,
+  PretableButtonProps
+>(function PretableButton(
+  { variant = "ghost", site, ...buttonProps },
+  ref,
+): ReactElement {
+  return (
+    <button
+      {...buttonProps}
+      ref={ref}
+      type="button"
+      data-pretable-button=""
+      data-pretable-variant={variant}
+      data-pretable-site={site}
+    />
+  );
+});
+
+/**
+ * An icon-only push-button. The accessible name is required.
+ *
+ * ```tsx
+ * <PretableIconButton aria-label={`Remove ${label}`} site="chip-remove">
+ *   <CloseIcon />
+ * </PretableIconButton>
+ * ```
+ *
+ * @public
+ */
+export const PretableIconButton = forwardRef<
+  HTMLButtonElement,
+  PretableIconButtonProps
+>(function PretableIconButton({ site, ...buttonProps }, ref): ReactElement {
+  return (
+    <button
+      {...buttonProps}
+      ref={ref}
+      type="button"
+      data-pretable-icon-button=""
+      data-pretable-site={site}
+    />
+  );
+});

From 4015cde4b3d484a77218f2edb52b2b03aa24c9b2 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 10:14:25 -0700
Subject: [PATCH 05/31] fix(react): IconButton warns on an empty accessible
 name; pin the contract attributes

"aria-label": string makes omission a compile error but lets "" through, which
is the failure the prop exists to prevent; warnOnce closes it in development
the way PretableStatus's missing-children warning does. The hostile-spread test
now pins all four contract attributes, and `site` is asserted never to reach
the DOM.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../src/__tests__/components-button.test.tsx  | 37 +++++++++++++++++--
 packages/react/src/components/button.tsx      | 26 ++++++++++++-
 2 files changed, 58 insertions(+), 5 deletions(-)

diff --git a/packages/react/src/__tests__/components-button.test.tsx b/packages/react/src/__tests__/components-button.test.tsx
index c2433a07..67fc4461 100644
--- a/packages/react/src/__tests__/components-button.test.tsx
+++ b/packages/react/src/__tests__/components-button.test.tsx
@@ -1,12 +1,18 @@
 import "@testing-library/jest-dom/vitest";
 import { cleanup, render } from "@testing-library/react";
 import { createRef } from "react";
-import { afterEach, describe, expect, test } from "vitest";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 
 import { PretableButton, PretableIconButton } from "../components/button";
+import { resetDevWarnings } from "../dev-warn";
 
 afterEach(() => {
   cleanup();
+  vi.restoreAllMocks();
+});
+
+beforeEach(() => {
+  resetDevWarnings();
 });
 
 describe("PretableButton", () => {
@@ -22,6 +28,7 @@ describe("PretableButton", () => {
     expect(button).toHaveAttribute("data-pretable-variant", "ghost");
     expect(button).toHaveAttribute("data-pretable-site", "filter-clear");
     expect(button).toHaveTextContent("Clear");
+    expect(button).not.toHaveAttribute("site");
   });
 
   test("takes the link variant, and leaves the site attribute off when none is given", () => {
@@ -67,14 +74,21 @@ describe("PretableButton", () => {
     // The data attributes follow the spread on purpose: they are the
     // component's contract with grid.css, not inputs.
     const { container } = render(
-      // @ts-expect-error — proving the runtime order, not the types
-      <PretableButton data-pretable-button="no" type="submit">
+      <PretableButton
+        data-pretable-button="no"
+        data-pretable-variant="x"
+        data-pretable-site="x"
+        // @ts-expect-error — proving the runtime order, not the types
+        type="submit"
+      >
         x
       </PretableButton>,
     );
     const button = container.querySelector("button")!;
     expect(button).toHaveAttribute("data-pretable-button", "");
     expect(button).toHaveAttribute("type", "button");
+    expect(button).toHaveAttribute("data-pretable-variant", "ghost");
+    expect(button).not.toHaveAttribute("data-pretable-site");
   });
 });
 
@@ -109,4 +123,21 @@ describe("PretableIconButton", () => {
     expect(ref.current).toHaveAttribute("aria-expanded", "false");
     expect(ref.current).toHaveAttribute("data-pretable-filter-funnel", "");
   });
+
+  test("warns in development when the accessible name is empty", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    render(<PretableIconButton aria-label="   " />);
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn.mock.calls[0]?.[0]).toMatch(/PretableIconButton/);
+    expect(warn.mock.calls[0]?.[0]).toMatch(/aria-label/);
+    // Once per session, like every dev warning here — not once per render.
+    render(<PretableIconButton aria-label="" />);
+    expect(warn).toHaveBeenCalledTimes(1);
+  });
+
+  test("does not warn when the name is present", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    render(<PretableIconButton aria-label="Remove Alpha" />);
+    expect(warn).not.toHaveBeenCalled();
+  });
 });
diff --git a/packages/react/src/components/button.tsx b/packages/react/src/components/button.tsx
index 44e8c206..df0c213b 100644
--- a/packages/react/src/components/button.tsx
+++ b/packages/react/src/components/button.tsx
@@ -24,6 +24,8 @@ import {
   type ReactElement,
 } from "react";
 
+import { warnOnce } from "../dev-warn";
+
 /**
  * The two labelled looks the grid uses: `ghost` (a 24px box with a hover
  * tint — `+ filter`, `Expand all`) and `link` (plain accent text — `Clear`,
@@ -77,6 +79,9 @@ export interface PretableButtonProps extends Omit<
    * Where in the grid this button is; lands as `data-pretable-site`. A
    * replacement passed through `components` receives it and can branch on it.
    * Named `site`, not `role`: `role` is the ARIA attribute on every button.
+   * The contract attributes are written after the spread, so a
+   * `data-pretable-site` passed as a raw attribute is replaced by this
+   * prop's value, or removed when the prop is absent.
    */
   site?: PretableButtonSite;
 }
@@ -92,10 +97,17 @@ export interface PretableIconButtonProps extends Omit<
 > {
   /**
    * Required. An icon-only button has no other accessible name, so omitting
-   * it is a compile error rather than a WCAG failure discovered later.
+   * it is a compile error rather than a WCAG failure discovered later. The
+   * type system cannot stop an empty or whitespace-only string, which
+   * warns in development instead.
    */
   "aria-label": string;
-  /** Where in the grid this button is; lands as `data-pretable-site`. */
+  /**
+   * Where in the grid this button is; lands as `data-pretable-site`. The
+   * contract attributes are written after the spread, so a
+   * `data-pretable-site` passed as a raw attribute is replaced by this
+   * prop's value, or removed when the prop is absent.
+   */
   site?: PretableButtonSite;
 }
 
@@ -144,6 +156,16 @@ export const PretableIconButton = forwardRef<
   HTMLButtonElement,
   PretableIconButtonProps
 >(function PretableIconButton({ site, ...buttonProps }, ref): ReactElement {
+  if (buttonProps["aria-label"].trim() === "") {
+    warnOnce(
+      "icon-button-empty-name",
+      "[pretable] <PretableIconButton> rendered with an empty aria-label. " +
+        "An icon-only button has no other accessible name, so screen-reader " +
+        "users hear nothing for it. Pass the action it performs, e.g. " +
+        "`Remove Alpha from grouping`.",
+    );
+  }
+
   return (
     <button
       {...buttonProps}

From 175756892d859ad631c2fad9ca040d7066055754 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 10:14:45 -0700
Subject: [PATCH 06/31] docs(spec): the two push-buttons share one file

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../specs/2026-09-04-components-sp1-button-design.md           | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/superpowers/specs/2026-09-04-components-sp1-button-design.md b/docs/superpowers/specs/2026-09-04-components-sp1-button-design.md
index dc748ae5..dcceac11 100644
--- a/docs/superpowers/specs/2026-09-04-components-sp1-button-design.md
+++ b/docs/superpowers/specs/2026-09-04-components-sp1-button-design.md
@@ -52,7 +52,8 @@ follows what those components need.
 
 ## Placement
 
-Components live in `packages/react/src/components/`, one file per component,
+Components live in `packages/react/src/components/` — the two push-buttons
+share `button.tsx`, since they share a props vocabulary — and are
 exported from `@pretable/react`'s public API alongside `PretableBadge`,
 `PretableDelta`, `PretableEntity` and `PretableStatus`. Same package, same
 api-extractor gate, same `Pretable*` naming. No new package: a second build,

From dc18d9801b88ebcb106bcbe83e02f08acf0c4e46 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 10:18:02 -0700
Subject: [PATCH 07/31] fix(react): the empty-name guard tolerates a missing
 aria-label

The type requires it; the runtime cannot, so the guard that warns about an
empty name must not itself throw on an absent one.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../react/src/__tests__/components-button.test.tsx     | 10 ++++++++++
 packages/react/src/components/button.tsx               |  2 +-
 2 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/packages/react/src/__tests__/components-button.test.tsx b/packages/react/src/__tests__/components-button.test.tsx
index 67fc4461..1a3577e7 100644
--- a/packages/react/src/__tests__/components-button.test.tsx
+++ b/packages/react/src/__tests__/components-button.test.tsx
@@ -140,4 +140,14 @@ describe("PretableIconButton", () => {
     render(<PretableIconButton aria-label="Remove Alpha" />);
     expect(warn).not.toHaveBeenCalled();
   });
+
+  test("a missing name (possible from JavaScript) warns rather than throwing", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    // The type requires it; the runtime cannot, so the guard must not assume it.
+    const props = { "aria-label": undefined } as unknown as {
+      "aria-label": string;
+    };
+    expect(() => render(<PretableIconButton {...props} />)).not.toThrow();
+    expect(warn).toHaveBeenCalledTimes(1);
+  });
 });
diff --git a/packages/react/src/components/button.tsx b/packages/react/src/components/button.tsx
index df0c213b..168fac55 100644
--- a/packages/react/src/components/button.tsx
+++ b/packages/react/src/components/button.tsx
@@ -156,7 +156,7 @@ export const PretableIconButton = forwardRef<
   HTMLButtonElement,
   PretableIconButtonProps
 >(function PretableIconButton({ site, ...buttonProps }, ref): ReactElement {
-  if (buttonProps["aria-label"].trim() === "") {
+  if ((buttonProps["aria-label"] ?? "").trim() === "") {
     warnOnce(
       "icon-button-empty-name",
       "[pretable] <PretableIconButton> rendered with an empty aria-label. " +

From dc275188ec82b39057fc19daa97adda9743b6bf8 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 10:18:25 -0700
Subject: [PATCH 08/31] test(react): pin the Button/IconButton type contract

aria-label required on IconButton, no `type` prop, an open `site`, a closed
variant, and native attributes flowing through with the ref.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 type-tests/react/components-button.types.tsx | 48 ++++++++++++++++++++
 1 file changed, 48 insertions(+)
 create mode 100644 type-tests/react/components-button.types.tsx

diff --git a/type-tests/react/components-button.types.tsx b/type-tests/react/components-button.types.tsx
new file mode 100644
index 00000000..5890223f
--- /dev/null
+++ b/type-tests/react/components-button.types.tsx
@@ -0,0 +1,48 @@
+import {
+  PretableButton,
+  PretableIconButton,
+  type PretableButtonProps,
+  type PretableButtonSite,
+  type PretableIconButtonProps,
+} from "../../packages/react/src/components/button";
+import type { Equal, Expect } from "../shared/assert";
+
+// An icon-only button has no accessible name but the one it is given, so
+// omitting it is a compile error — a WCAG failure the grid could otherwise
+// ship becomes one the compiler refuses.
+// @ts-expect-error — aria-label is required on an icon button
+<PretableIconButton onClick={() => {}} />;
+<PretableIconButton aria-label="Remove" />;
+
+// The element is always type="button"; the prop does not exist.
+// @ts-expect-error — `type` is not a prop
+<PretableButton type="submit">x</PretableButton>;
+// @ts-expect-error — `type` is not a prop on the icon button either
+<PretableIconButton aria-label="x" type="submit" />;
+
+// A site is a built-in name or any string, never a type error.
+<PretableButton site="filter-clear">x</PretableButton>;
+<PretableButton site="my-app-export">x</PretableButton>;
+export type SiteIsOpen = Expect<
+  Equal<Extract<PretableButtonSite, "filter-clear">, "filter-clear">
+>;
+
+// The variant is closed.
+<PretableButton variant="link">x</PretableButton>;
+// @ts-expect-error — only the two shipped looks exist
+<PretableButton variant="solid">x</PretableButton>;
+
+// Every native button attribute flows through, refs included.
+const ref = { current: null as HTMLButtonElement | null };
+<PretableButton ref={ref} aria-describedby="why" disabled tabIndex={-1}>
+  x
+</PretableButton>;
+<PretableIconButton ref={ref} aria-label="x" aria-expanded={false} />;
+
+// The props types are what a replacement is written against.
+export type ButtonHasSite = Expect<
+  Equal<PretableButtonProps["site"], PretableButtonSite | undefined>
+>;
+export type IconHasName = Expect<
+  Equal<PretableIconButtonProps["aria-label"], string>
+>;

From 11a8021ece1b912fdec4c4d59b4d59161295cddc Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 10:22:19 -0700
Subject: [PATCH 09/31] feat(react): the components context

One slot per type, resolved over the defaults and memoised on each slot's
identity; context rather than props because the popovers are portalled.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../src/__tests__/components-button.test.tsx  |  69 ++++++++++-
 packages/react/src/components/context.ts      | 110 ++++++++++++++++++
 2 files changed, 178 insertions(+), 1 deletion(-)
 create mode 100644 packages/react/src/components/context.ts

diff --git a/packages/react/src/__tests__/components-button.test.tsx b/packages/react/src/__tests__/components-button.test.tsx
index 1a3577e7..1274f345 100644
--- a/packages/react/src/__tests__/components-button.test.tsx
+++ b/packages/react/src/__tests__/components-button.test.tsx
@@ -1,9 +1,16 @@
 import "@testing-library/jest-dom/vitest";
-import { cleanup, render } from "@testing-library/react";
+import { cleanup, render, renderHook } from "@testing-library/react";
+import * as React from "react";
 import { createRef } from "react";
 import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 
 import { PretableButton, PretableIconButton } from "../components/button";
+import {
+  DEFAULT_COMPONENTS,
+  PretableComponentsProvider,
+  usePretableComponents,
+  useResolvedComponents,
+} from "../components/context";
 import { resetDevWarnings } from "../dev-warn";
 
 afterEach(() => {
@@ -151,3 +158,63 @@ describe("PretableIconButton", () => {
     expect(warn).toHaveBeenCalledTimes(1);
   });
 });
+
+describe("components context", () => {
+  test("outside any provider, the hook returns the built-in components", () => {
+    const { result } = renderHook(() => usePretableComponents());
+    expect(result.current).toBe(DEFAULT_COMPONENTS);
+    expect(result.current.Button).toBe(PretableButton);
+    expect(result.current.IconButton).toBe(PretableIconButton);
+  });
+
+  test("resolving nothing yields the default map, by identity", () => {
+    // Identity matters: the provider's value is what every button re-renders
+    // on, so an unchanged input must produce an unchanged output.
+    const { result, rerender } = renderHook(
+      ({ components }) => useResolvedComponents(components),
+      {
+        initialProps: {
+          components: undefined as
+            undefined | { Button?: typeof PretableButton },
+        },
+      },
+    );
+    expect(result.current).toBe(DEFAULT_COMPONENTS);
+    rerender({ components: {} });
+    expect(result.current).toBe(DEFAULT_COMPONENTS);
+  });
+
+  test("a replacement is merged over the defaults, and a stable input is a stable output", () => {
+    const MyButton = React.forwardRef<
+      HTMLButtonElement,
+      React.ComponentProps<typeof PretableButton>
+    >((props, ref) => <button {...props} ref={ref} data-mine="" />);
+    const { result, rerender } = renderHook(
+      ({ components }) => useResolvedComponents(components),
+      { initialProps: { components: { Button: MyButton } } },
+    );
+    const first = result.current;
+    expect(first.Button).toBe(MyButton);
+    expect(first.IconButton).toBe(PretableIconButton);
+    // A NEW object literal with the SAME values — what an inline
+    // `components={{ Button: MyButton }}` produces on every render.
+    rerender({ components: { Button: MyButton } });
+    expect(result.current).toBe(first);
+  });
+
+  test("the provider's value is what the hook reads", () => {
+    const MyIcon = React.forwardRef<
+      HTMLButtonElement,
+      React.ComponentProps<typeof PretableIconButton>
+    >((props, ref) => <button {...props} ref={ref} data-mine="" />);
+    const value = { Button: PretableButton, IconButton: MyIcon };
+    const { result } = renderHook(() => usePretableComponents(), {
+      wrapper: ({ children }) => (
+        <PretableComponentsProvider value={value}>
+          {children}
+        </PretableComponentsProvider>
+      ),
+    });
+    expect(result.current.IconButton).toBe(MyIcon);
+  });
+});
diff --git a/packages/react/src/components/context.ts b/packages/react/src/components/context.ts
new file mode 100644
index 00000000..fc84ef9e
--- /dev/null
+++ b/packages/react/src/components/context.ts
@@ -0,0 +1,110 @@
+/**
+ * How a consumer's replacement reaches every place the grid renders a kit
+ * component, and how the grid reads it.
+ *
+ * ONE slot per component type. `components={{ Button: MyButton }}` on the
+ * surface replaces every button the grid draws; the props ours passes —
+ * `site` included — are exactly what the replacement receives, so it can
+ * branch on `site` to treat one place differently. No per-site public names:
+ * the API does not grow a name for every control the grid gains.
+ *
+ * CONTEXT, not props. pretable portals its popovers — the filter dialog, the
+ * column menus — into document.body. Context crosses a portal; props do not,
+ * and the popovers are exactly where an override matters most. The value is
+ * resolved once at the surface and memoised on the identity of each slot, so
+ * an inline `{{ Button: MyButton }}` literal does not re-render every button
+ * on every keystroke.
+ *
+ * The default context value is the built-in map, so a kit component rendered
+ * outside any surface still resolves.
+ */
+import {
+  createContext,
+  useContext,
+  useMemo,
+  type ComponentType,
+  type RefAttributes,
+} from "react";
+
+import {
+  PretableButton,
+  PretableIconButton,
+  type PretableButtonProps,
+  type PretableIconButtonProps,
+} from "./button";
+
+/**
+ * The component a `components.Button` replacement must be: it receives
+ * {@link PretableButtonProps} and forwards its `ref` to the button node —
+ * the one obligation on a replacement, since the grid anchors menus on and
+ * returns focus to that node.
+ *
+ * @public
+ */
+export type PretableButtonComponent = ComponentType<
+  PretableButtonProps & RefAttributes<HTMLButtonElement>
+>;
+
+/**
+ * The component a `components.IconButton` replacement must be.
+ *
+ * @public
+ */
+export type PretableIconButtonComponent = ComponentType<
+  PretableIconButtonProps & RefAttributes<HTMLButtonElement>
+>;
+
+/**
+ * The kit components a consumer can replace, one slot per type. Every slot is
+ * optional; an absent one is the built-in.
+ *
+ * @public
+ */
+export interface PretableComponents {
+  readonly Button?: PretableButtonComponent;
+  readonly IconButton?: PretableIconButtonComponent;
+}
+
+/** The map after resolution: every slot filled. Internal. */
+export interface ResolvedPretableComponents {
+  readonly Button: PretableButtonComponent;
+  readonly IconButton: PretableIconButtonComponent;
+}
+
+/** The built-ins, frozen: also the identity a no-op resolution returns. */
+export const DEFAULT_COMPONENTS: ResolvedPretableComponents = Object.freeze({
+  Button: PretableButton,
+  IconButton: PretableIconButton,
+});
+
+const PretableComponentsContext =
+  createContext<ResolvedPretableComponents>(DEFAULT_COMPONENTS);
+
+/** Wraps the surface's tree. Internal — the public entry is the surface prop. */
+export const PretableComponentsProvider = PretableComponentsContext.Provider;
+
+/** What a call site renders its button from. Internal. */
+export function usePretableComponents(): ResolvedPretableComponents {
+  return useContext(PretableComponentsContext);
+}
+
+/**
+ * Merge a consumer's map over the defaults, memoised on the identity of each
+ * slot's VALUE rather than of the map, so a fresh object literal carrying the
+ * same components resolves to the same object — and the defaults, when
+ * nothing is replaced, to the frozen `DEFAULT_COMPONENTS` itself.
+ */
+export function useResolvedComponents(
+  components: PretableComponents | undefined,
+): ResolvedPretableComponents {
+  const Button = components?.Button ?? DEFAULT_COMPONENTS.Button;
+  const IconButton = components?.IconButton ?? DEFAULT_COMPONENTS.IconButton;
+  return useMemo(
+    () =>
+      Button === DEFAULT_COMPONENTS.Button &&
+      IconButton === DEFAULT_COMPONENTS.IconButton
+        ? DEFAULT_COMPONENTS
+        : { Button, IconButton },
+    [Button, IconButton],
+  );
+}

From 5ee107f11735c29a566da63840283ed2d0cae85e Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 10:26:07 -0700
Subject: [PATCH 10/31] test(react): the site union is pinned open AND
 built-in; anchor the hostile cast

`Extract<PretableButtonSite, "filter-clear">` was the same whether or not the
union was open, so the alias could not fail for the reason its name claimed;
`Equal` against the full union can, and was mutation-checked. The
source-relative import is marked as the temporary state it is, and the
missing-name test casts to the component's own props type.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../react/src/__tests__/components-button.test.tsx   | 12 ++++++++----
 type-tests/react/components-button.types.tsx         | 12 +++++++++---
 2 files changed, 17 insertions(+), 7 deletions(-)

diff --git a/packages/react/src/__tests__/components-button.test.tsx b/packages/react/src/__tests__/components-button.test.tsx
index 1274f345..9aac3ad8 100644
--- a/packages/react/src/__tests__/components-button.test.tsx
+++ b/packages/react/src/__tests__/components-button.test.tsx
@@ -4,7 +4,11 @@ import * as React from "react";
 import { createRef } from "react";
 import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 
-import { PretableButton, PretableIconButton } from "../components/button";
+import {
+  PretableButton,
+  PretableIconButton,
+  type PretableIconButtonProps,
+} from "../components/button";
 import {
   DEFAULT_COMPONENTS,
   PretableComponentsProvider,
@@ -151,9 +155,9 @@ describe("PretableIconButton", () => {
   test("a missing name (possible from JavaScript) warns rather than throwing", () => {
     const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
     // The type requires it; the runtime cannot, so the guard must not assume it.
-    const props = { "aria-label": undefined } as unknown as {
-      "aria-label": string;
-    };
+    const props = {
+      "aria-label": undefined,
+    } as unknown as PretableIconButtonProps;
     expect(() => render(<PretableIconButton {...props} />)).not.toThrow();
     expect(warn).toHaveBeenCalledTimes(1);
   });
diff --git a/type-tests/react/components-button.types.tsx b/type-tests/react/components-button.types.tsx
index 5890223f..8a56aa37 100644
--- a/type-tests/react/components-button.types.tsx
+++ b/type-tests/react/components-button.types.tsx
@@ -1,6 +1,10 @@
+// TEMPORARY: imported from source because `@pretable/react` does not export
+// these yet. Task 11 of the SP1 plan switches this to the package, which is
+// the surface every other file here tests — the built d.ts, not the source.
 import {
   PretableButton,
   PretableIconButton,
+  type PretableBuiltInButtonSite,
   type PretableButtonProps,
   type PretableButtonSite,
   type PretableIconButtonProps,
@@ -20,11 +24,13 @@ import type { Equal, Expect } from "../shared/assert";
 // @ts-expect-error — `type` is not a prop on the icon button either
 <PretableIconButton aria-label="x" type="submit" />;
 
-// A site is a built-in name or any string, never a type error.
+// A site is a built-in name or any string, never a type error — and the
+// built-ins keep their autocomplete, which a collapse to bare `string` would
+// lose. Both halves pinned at once.
 <PretableButton site="filter-clear">x</PretableButton>;
 <PretableButton site="my-app-export">x</PretableButton>;
-export type SiteIsOpen = Expect<
-  Equal<Extract<PretableButtonSite, "filter-clear">, "filter-clear">
+export type SiteIsOpenAndKeepsBuiltIns = Expect<
+  Equal<PretableButtonSite, PretableBuiltInButtonSite | (string & {})>
 >;
 
 // The variant is closed.

From 9e2fef07eda1b14c43b161d48a1e9a45a885bb75 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 10:30:41 -0700
Subject: [PATCH 11/31] test(react): pin the resolved-components memo with a
 changed-slot case

An empty dependency array passed every test, because every test fed the memo
unchanged values. The negative twin now fails it. Also: the React 18
forwardRef obligation is stated where the type cannot enforce it, both
branches of the resolution are frozen, and the context has a DevTools name.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../src/__tests__/components-button.test.tsx  | 33 +++++++++++++++----
 packages/react/src/components/context.ts      |  8 +++--
 2 files changed, 33 insertions(+), 8 deletions(-)

diff --git a/packages/react/src/__tests__/components-button.test.tsx b/packages/react/src/__tests__/components-button.test.tsx
index 9aac3ad8..5f21e247 100644
--- a/packages/react/src/__tests__/components-button.test.tsx
+++ b/packages/react/src/__tests__/components-button.test.tsx
@@ -1,7 +1,6 @@
 import "@testing-library/jest-dom/vitest";
 import { cleanup, render, renderHook } from "@testing-library/react";
-import * as React from "react";
-import { createRef } from "react";
+import { createRef, forwardRef, type ComponentProps } from "react";
 import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 
 import {
@@ -189,9 +188,9 @@ describe("components context", () => {
   });
 
   test("a replacement is merged over the defaults, and a stable input is a stable output", () => {
-    const MyButton = React.forwardRef<
+    const MyButton = forwardRef<
       HTMLButtonElement,
-      React.ComponentProps<typeof PretableButton>
+      ComponentProps<typeof PretableButton>
     >((props, ref) => <button {...props} ref={ref} data-mine="" />);
     const { result, rerender } = renderHook(
       ({ components }) => useResolvedComponents(components),
@@ -206,10 +205,32 @@ describe("components context", () => {
     expect(result.current).toBe(first);
   });
 
+  test("a changed slot yields a new map carrying the replacement", () => {
+    const A = forwardRef<
+      HTMLButtonElement,
+      ComponentProps<typeof PretableButton>
+    >((props, ref) => <button {...props} ref={ref} />);
+    const B = forwardRef<
+      HTMLButtonElement,
+      ComponentProps<typeof PretableButton>
+    >((props, ref) => <button {...props} ref={ref} />);
+    const { result, rerender } = renderHook(
+      ({ components }) => useResolvedComponents(components),
+      { initialProps: { components: { Button: A } as { Button?: typeof A } } },
+    );
+    const first = result.current;
+    rerender({ components: { Button: B } });
+    expect(result.current).not.toBe(first);
+    expect(result.current.Button).toBe(B);
+    // And back to nothing returns the frozen default by identity.
+    rerender({ components: {} });
+    expect(result.current).toBe(DEFAULT_COMPONENTS);
+  });
+
   test("the provider's value is what the hook reads", () => {
-    const MyIcon = React.forwardRef<
+    const MyIcon = forwardRef<
       HTMLButtonElement,
-      React.ComponentProps<typeof PretableIconButton>
+      ComponentProps<typeof PretableIconButton>
     >((props, ref) => <button {...props} ref={ref} data-mine="" />);
     const value = { Button: PretableButton, IconButton: MyIcon };
     const { result } = renderHook(() => usePretableComponents(), {
diff --git a/packages/react/src/components/context.ts b/packages/react/src/components/context.ts
index fc84ef9e..5d490cac 100644
--- a/packages/react/src/components/context.ts
+++ b/packages/react/src/components/context.ts
@@ -37,7 +37,10 @@ import {
  * The component a `components.Button` replacement must be: it receives
  * {@link PretableButtonProps} and forwards its `ref` to the button node —
  * the one obligation on a replacement, since the grid anchors menus on and
- * returns focus to that node.
+ * returns focus to that node. Under React 18 that means `forwardRef`; under
+ * React 19 a plain `ref` prop is enough. A plain function component compiles
+ * into this slot under both — the type cannot tell them apart — so this is
+ * the one obligation the docs carry rather than the compiler.
  *
  * @public
  */
@@ -79,6 +82,7 @@ export const DEFAULT_COMPONENTS: ResolvedPretableComponents = Object.freeze({
 
 const PretableComponentsContext =
   createContext<ResolvedPretableComponents>(DEFAULT_COMPONENTS);
+PretableComponentsContext.displayName = "PretableComponents";
 
 /** Wraps the surface's tree. Internal — the public entry is the surface prop. */
 export const PretableComponentsProvider = PretableComponentsContext.Provider;
@@ -104,7 +108,7 @@ export function useResolvedComponents(
       Button === DEFAULT_COMPONENTS.Button &&
       IconButton === DEFAULT_COMPONENTS.IconButton
         ? DEFAULT_COMPONENTS
-        : { Button, IconButton },
+        : Object.freeze({ Button, IconButton }),
     [Button, IconButton],
   );
 }

From f0ecc762a5a036ca0e7fd383975fff16f8a0536d Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 10:35:20 -0700
Subject: [PATCH 12/31] feat(react): the components prop on the surface and the
 preset

Resolved once, memoised on slot identity, provided on both of the surface's
return paths so the portalled popovers inherit it. The override tests land
red on the site assertions, which the migrations turn green.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../__tests__/components-override.test.tsx    | 170 ++++++++++++++++++
 packages/react/src/pretable-surface.tsx       | 128 ++++++++-----
 packages/react/src/pretable.tsx               |   1 +
 3 files changed, 250 insertions(+), 49 deletions(-)
 create mode 100644 packages/react/src/__tests__/components-override.test.tsx

diff --git a/packages/react/src/__tests__/components-override.test.tsx b/packages/react/src/__tests__/components-override.test.tsx
new file mode 100644
index 00000000..5ca5a5ea
--- /dev/null
+++ b/packages/react/src/__tests__/components-override.test.tsx
@@ -0,0 +1,170 @@
+// @vitest-environment jsdom
+import "@testing-library/jest-dom/vitest";
+import { cleanup, fireEvent, render, waitFor } from "@testing-library/react";
+import { forwardRef } from "react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { Pretable } from "../pretable";
+import { PretableSurface } from "../pretable-surface";
+import type { PretableColumn } from "../types";
+import type {
+  PretableButtonComponent,
+  PretableComponents,
+  PretableIconButtonComponent,
+} from "../components/context";
+
+afterEach(() => {
+  cleanup();
+});
+
+type Row = { id: string; name: string; qty: number };
+const columns: PretableColumn<Row>[] = [
+  { id: "name", header: "Name", widthPx: 160, type: "text" },
+  { id: "qty", header: "Qty", widthPx: 100, type: "number" },
+];
+const rows: Row[] = [
+  { id: "a", name: "Alpha", qty: 1 },
+  { id: "b", name: "Bravo", qty: 2 },
+];
+
+/** A replacement that marks itself and records what site it was asked for. */
+const MyButton: PretableButtonComponent = forwardRef(function MyButton(
+  { site, variant, ...props },
+  ref,
+) {
+  return (
+    <button
+      {...props}
+      ref={ref}
+      type="button"
+      data-mine={site ?? ""}
+      data-mine-variant={variant}
+    />
+  );
+});
+const MyIconButton: PretableIconButtonComponent = forwardRef(
+  function MyIconButton({ site, ...props }, ref) {
+    return (
+      <button {...props} ref={ref} type="button" data-mine-icon={site ?? ""} />
+    );
+  },
+);
+
+// `PretableSurface` is generic, so `ComponentProps<typeof PretableSurface>`
+// resolves its props against `{}`; the prop's own type is the direct thing to
+// name here anyway.
+function renderSurface(components?: PretableComponents) {
+  return render(
+    <PretableSurface<Row>
+      ariaLabel="override-grid"
+      columns={columns}
+      components={components}
+      getRowId={(row) => row.id}
+      rows={rows}
+      toolPanel={{ defaultActiveSection: "columns" }}
+      viewportHeight={240}
+    />,
+  );
+}
+
+describe("components on the surface", () => {
+  it("without the prop, the grid draws the kit's own buttons", () => {
+    const view = renderSurface();
+    const reset = view.getByRole("button", { name: "Reset columns" });
+    expect(reset).toHaveAttribute("data-pretable-button", "");
+    expect(reset).toHaveAttribute("data-pretable-site", "tool-reset");
+    expect(reset).toHaveAttribute("data-pretable-tool-reset", "");
+  });
+
+  it("replaces every Button, passing the site through, and keeps the site's own attribute", () => {
+    const view = renderSurface({ Button: MyButton });
+    const reset = view.getByRole("button", { name: "Reset columns" });
+    expect(reset).toHaveAttribute("data-mine", "tool-reset");
+    expect(reset).toHaveAttribute("data-mine-variant", "link");
+    // Nothing that identified this button before stops identifying it.
+    expect(reset).toHaveAttribute("data-pretable-tool-reset", "");
+    expect(reset).not.toHaveAttribute("data-pretable-button");
+    // The other slot is untouched.
+    expect(
+      view.container.querySelector("[data-pretable-icon-button]"),
+    ).not.toBeNull();
+  });
+
+  it("replaces every IconButton, including one in the header", () => {
+    const view = renderSurface({ IconButton: MyIconButton });
+    const funnel = view.getByRole("button", { name: "Filter Name" });
+    expect(funnel).toHaveAttribute("data-mine-icon", "filter-funnel");
+    expect(funnel).toHaveAttribute("data-pretable-filter-funnel", "");
+    expect(funnel).toHaveAttribute("tabindex", "-1");
+  });
+
+  it("reaches a button inside a PORTALLED popover — the reason this is context, not props", async () => {
+    const view = renderSurface({ Button: MyButton });
+    const funnel = view.getByRole("button", { name: "Filter Name" });
+    fireEvent.pointerDown(funnel);
+    fireEvent.click(funnel);
+    // The filter dialog renders through OverlayPortal into document.body.
+    const dialog = await waitFor(() => {
+      const el = document.querySelector("[data-pretable-filter-menu]");
+      if (!el) throw new Error("dialog not open");
+      return el;
+    });
+    expect(dialog.parentElement).toBe(document.body);
+    const clear = dialog.querySelector("[data-pretable-filter-clear]")!;
+    expect(clear).toHaveAttribute("data-mine", "filter-clear");
+  });
+
+  it("a fresh object literal with the same components does not remount the buttons", () => {
+    // Inline `components={{ Button: MyButton }}` is the common way to write
+    // it, and it produces a new object every render. The resolved map is
+    // memoised on the slot VALUES, so the node survives a re-render.
+    const view = renderSurface({ Button: MyButton });
+    const before = view.getByRole("button", { name: "Reset columns" });
+    view.rerender(
+      <PretableSurface<Row>
+        ariaLabel="override-grid"
+        columns={columns}
+        components={{ Button: MyButton }}
+        getRowId={(row) => row.id}
+        rows={rows}
+        toolPanel={{ defaultActiveSection: "columns" }}
+        viewportHeight={240}
+      />,
+    );
+    expect(view.getByRole("button", { name: "Reset columns" })).toBe(before);
+  });
+
+  it("the replacement still receives the ref the grid anchors on", () => {
+    // The kebab menu anchors on its button's node through a ref callback. A
+    // replacement that forwards its ref keeps that working.
+    const view = renderSurface({ IconButton: MyIconButton });
+    const kebab = view.container.querySelector(
+      "[data-pretable-tool-row-menu-button]",
+    )!;
+    fireEvent.pointerDown(kebab);
+    fireEvent.click(kebab);
+    expect(
+      document.querySelector("[data-pretable-column-menu]"),
+    ).not.toBeNull();
+  });
+});
+
+describe("components on the <Pretable> preset", () => {
+  it("forwards the prop", () => {
+    const view = render(
+      <Pretable<Row>
+        ariaLabel="preset-grid"
+        columns={columns}
+        components={{ Button: MyButton }}
+        rows={rows}
+      />,
+    );
+    // The preset ships the tool panel on by default; open the columns tab.
+    const tab = view.container.querySelector("[data-pretable-tool-tab]")!;
+    fireEvent.click(tab);
+    expect(view.getByRole("button", { name: "Reset columns" })).toHaveAttribute(
+      "data-mine",
+      "tool-reset",
+    );
+  });
+});
diff --git a/packages/react/src/pretable-surface.tsx b/packages/react/src/pretable-surface.tsx
index 251bf3dc..6bc82309 100644
--- a/packages/react/src/pretable-surface.tsx
+++ b/packages/react/src/pretable-surface.tsx
@@ -46,6 +46,11 @@ import type {
   PretableIndexedFocusRef,
   PretableIndexedSelectionState,
 } from "@pretable/core";
+import {
+  PretableComponentsProvider,
+  useResolvedComponents,
+  type PretableComponents,
+} from "./components/context";
 import type { PretableLocale } from "./locale";
 import type {
   PretableCellRenderInput,
@@ -1410,6 +1415,15 @@ export interface PretableSurfaceSharedProps<
    * optional; missing entries fall back to English defaults.
    */
   messages?: PretableSurfaceMessages;
+  /**
+   * Replace the kit components the grid renders its own chrome from — one
+   * slot per component type, applied everywhere that type appears. A
+   * replacement receives exactly the props the built-in does, `site`
+   * included, so it can branch on where in the grid it is; it must forward
+   * its `ref` to the button node, which the grid anchors menus on and returns
+   * focus to. Absent slots are the built-ins.
+   */
+  components?: PretableComponents;
   /**
    * Called once per clipboard paste, with every cell the block landed on that
    * survived the gate (`parseEditValue`/type coercion → `editable` →
@@ -1897,6 +1911,7 @@ export function PretableSurface<
   onExport,
   saveFile,
   messages,
+  components,
   onPaste,
 }: PretableSurfaceProps<TRow, TRowId, TColumns>) {
   const emitFocusChange = (
@@ -2203,6 +2218,7 @@ export function PretableSurface<
     }),
     [messages],
   );
+  const resolvedComponents = useResolvedComponents(components);
   // ---- Tool panel chrome state -------------------------------------------
   const toolPanelEnabled = toolPanel !== false;
   const toolPanelConfig = typeof toolPanel === "object" ? toolPanel : null;
@@ -7951,8 +7967,17 @@ export function PretableSurface<
   // effectively off (spec: equivalent to `toolPanel={false}`, reachable from a
   // dynamic roster without switching prop shapes). An empty rail — a bare
   // vertical strip with no tabs — serves nobody.
+  // The components provider wraps everything the surface returns, on both
+  // paths. It sits outside every popover's React parent, and context crosses
+  // a portal — so the filter dialog and the column menus, which
+  // `OverlayPortal` mounts into document.body, read the same resolved map as
+  // the inline chrome.
   if (!toolPanelEnabled || toolPanelSections.length === 0) {
-    return verticalStack;
+    return (
+      <PretableComponentsProvider value={resolvedComponents}>
+        {verticalStack}
+      </PretableComponentsProvider>
+    );
   }
 
   // The tool panel row: [vertical stack][pane?][rail], all inside one wrapper
@@ -7964,55 +7989,60 @@ export function PretableSurface<
   // (which re-derives `viewportWidth` from `clientWidth`) reflows the columns
   // and the right-pinned insets, exactly as it does for a container resize.
   return (
-    <div
-      data-pretable-tool-layout=""
-      ref={observeToolLayout}
-      style={getToolPanelLayoutStyle()}
-    >
-      <div data-pretable-tool-grid-area="" style={getToolPanelGridAreaStyle()}>
-        {verticalStack}
+    <PretableComponentsProvider value={resolvedComponents}>
+      <div
+        data-pretable-tool-layout=""
+        ref={observeToolLayout}
+        style={getToolPanelLayoutStyle()}
+      >
+        <div
+          data-pretable-tool-grid-area=""
+          style={getToolPanelGridAreaStyle()}
+        >
+          {verticalStack}
+        </div>
+        <ToolPanel
+          railLabel={effectiveMessages.toolPanelLabel()}
+          resizeLabel={effectiveMessages.toolPanelResizeLabel()}
+          sections={toolPanelSections}
+          activeSection={activeToolSection}
+          onActiveSectionChange={(next) => {
+            if (controlledToolSection === undefined) {
+              setUncontrolledToolSection(next);
+            }
+            toolPanelConfig?.onActiveSectionChange?.(next);
+          }}
+          paneWidthPx={appliedPaneWidth}
+          paneBounds={paneBounds}
+          // Every write path clamps then reports — the shell hands over raw
+          // gesture output, and this is the one place the bounds are applied
+          // so the controlled and uncontrolled forms cannot drift.
+          onPaneWidthChange={(next) => {
+            const clamped =
+              next === null ? null : clampPaneWidth(next, paneBounds);
+            if (controlledPaneWidth === undefined) {
+              setUncontrolledPaneWidth(clamped);
+            }
+            toolPanelConfig?.onPaneWidthChange?.(clamped);
+          }}
+          // Reset (double-click / Enter on the handle): back to
+          // `defaultPaneWidthPx` when the consumer gave one, else to `null` —
+          // the untouched state, which clears the inline style and restores the
+          // stylesheet width (spec A5).
+          onPaneWidthReset={() => {
+            const fallback = toolPanelConfig?.defaultPaneWidthPx;
+            const next =
+              fallback === undefined
+                ? null
+                : clampPaneWidth(fallback, paneBounds);
+            if (controlledPaneWidth === undefined) {
+              setUncontrolledPaneWidth(next);
+            }
+            toolPanelConfig?.onPaneWidthChange?.(next);
+          }}
+        />
       </div>
-      <ToolPanel
-        railLabel={effectiveMessages.toolPanelLabel()}
-        resizeLabel={effectiveMessages.toolPanelResizeLabel()}
-        sections={toolPanelSections}
-        activeSection={activeToolSection}
-        onActiveSectionChange={(next) => {
-          if (controlledToolSection === undefined) {
-            setUncontrolledToolSection(next);
-          }
-          toolPanelConfig?.onActiveSectionChange?.(next);
-        }}
-        paneWidthPx={appliedPaneWidth}
-        paneBounds={paneBounds}
-        // Every write path clamps then reports — the shell hands over raw
-        // gesture output, and this is the one place the bounds are applied
-        // so the controlled and uncontrolled forms cannot drift.
-        onPaneWidthChange={(next) => {
-          const clamped =
-            next === null ? null : clampPaneWidth(next, paneBounds);
-          if (controlledPaneWidth === undefined) {
-            setUncontrolledPaneWidth(clamped);
-          }
-          toolPanelConfig?.onPaneWidthChange?.(clamped);
-        }}
-        // Reset (double-click / Enter on the handle): back to
-        // `defaultPaneWidthPx` when the consumer gave one, else to `null` —
-        // the untouched state, which clears the inline style and restores the
-        // stylesheet width (spec A5).
-        onPaneWidthReset={() => {
-          const fallback = toolPanelConfig?.defaultPaneWidthPx;
-          const next =
-            fallback === undefined
-              ? null
-              : clampPaneWidth(fallback, paneBounds);
-          if (controlledPaneWidth === undefined) {
-            setUncontrolledPaneWidth(next);
-          }
-          toolPanelConfig?.onPaneWidthChange?.(next);
-        }}
-      />
-    </div>
+    </PretableComponentsProvider>
   );
 }
 
diff --git a/packages/react/src/pretable.tsx b/packages/react/src/pretable.tsx
index 9f8e61fb..ab65ff51 100644
--- a/packages/react/src/pretable.tsx
+++ b/packages/react/src/pretable.tsx
@@ -118,6 +118,7 @@ export interface PretableBaseProps<
     TColumns
   >["copyToClipboard"];
   messages?: PretableSurfaceSharedProps<TRow, TRowId, TColumns>["messages"];
+  components?: PretableSurfaceSharedProps<TRow, TRowId, TColumns>["components"];
   /** The tool panel rail at the grid's right edge. On by default — the
    *  default lives in the surface, so the preset only ever forwards; pass
    *  `false` to remove it or a config object to control the open section. */

From cb20aa2a05d54f4bd8a55951df9f8a8d1411caf5 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 10:38:37 -0700
Subject: [PATCH 13/31] feat(ui): the kit button rules

The shared push-button box on the component attributes, first in the file
so site rules still win by order; ghost and link looks; the standard ring,
disabled treatment and forced-colours ink.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 packages/ui/grid.css                          | 76 ++++++++++++++++++-
 packages/ui/src/__tests__/css-cascade.test.ts | 60 +++++++++++++++
 2 files changed, 135 insertions(+), 1 deletion(-)

diff --git a/packages/ui/grid.css b/packages/ui/grid.css
index 9b0148f6..5e909c3e 100644
--- a/packages/ui/grid.css
+++ b/packages/ui/grid.css
@@ -102,6 +102,76 @@
     background: var(--pretable-bg-header);
   }
 
+  /* ---- Kit components: push-buttons ------------------------------------
+     The shared look every plain push-button in the grid used to carry per
+     site — twelve rule lists for one box — now lives on the component's own
+     attributes, and each site keeps only what is genuinely its own: a size,
+     a reveal, an alignment. These rules come FIRST in the file so a site
+     rule can still win at equal specificity by source order. The site
+     attribute (`data-pretable-filter-clear`) still arrives on the element,
+     so every selector keyed on it keeps working. */
+  :where([data-pretable-button], [data-pretable-icon-button]) {
+    box-sizing: border-box;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    border: 0;
+    border-radius: var(--pretable-radius-control);
+    background: transparent;
+    color: var(--pretable-text-dim);
+    font: inherit;
+    cursor: pointer;
+  }
+  /* A labelled button speaks in the accent; an icon button in the dim ink
+     its site may lift on hover or reveal. */
+  :where([data-pretable-button]) {
+    color: var(--pretable-accent);
+  }
+  /* `ghost`: the 24px action row box — `+ filter`, `Expand all` — with a
+     hover tint painted as a background-IMAGE layer so a site's own surface
+     colour underneath survives. */
+  :where([data-pretable-button][data-pretable-variant="ghost"]) {
+    gap: 4px;
+    block-size: 24px;
+    padding-inline: 6px;
+  }
+  :where(
+    [data-pretable-button][data-pretable-variant="ghost"]:hover:not(:disabled)
+  ) {
+    background-image: linear-gradient(
+      var(--pretable-bg-hover),
+      var(--pretable-bg-hover)
+    );
+  }
+  /* `link`: plain accent text — `Clear`, `Reset columns`. No hover tint;
+     the two sites that use it never had one. */
+  :where([data-pretable-button][data-pretable-variant="link"]) {
+    padding: 2px 4px;
+  }
+  /* An icon button is a fixed box its site sizes (14, 18 and 24px boxes all
+     exist); `position: relative` is for the sites that enlarge the hit area
+     with a ::after. */
+  :where([data-pretable-icon-button]) {
+    flex: none;
+    padding: 0;
+    position: relative;
+  }
+  :where(
+    [data-pretable-button]:focus-visible,
+    [data-pretable-icon-button]:focus-visible
+  ) {
+    outline: 2px solid var(--pretable-focus-ring);
+    outline-offset: -2px;
+  }
+  /* The standard disabled treatment (#573): dim by token, drop the pointer. */
+  :where(
+    [data-pretable-button]:disabled,
+    [data-pretable-icon-button]:disabled
+  ) {
+    color: var(--pretable-text-dim);
+    cursor: default;
+  }
+
   /* Multi-sort priority badge (rendered only when 2+ columns are sorted) */
   :where([data-pretable-sort-priority]) {
     margin-left: 2px;
@@ -2427,7 +2497,11 @@
     /* GrayText is the system's own disabled ink. Without it a disabled item
        is forced to CanvasText — the enabled colour — and the menu goes back
        to offering the one thing that cannot be chosen. */
-    :where([data-pretable-menu-item]:disabled) {
+    :where(
+      [data-pretable-menu-item]:disabled,
+      [data-pretable-button]:disabled,
+      [data-pretable-icon-button]:disabled
+    ) {
       color: GrayText;
     }
   }
diff --git a/packages/ui/src/__tests__/css-cascade.test.ts b/packages/ui/src/__tests__/css-cascade.test.ts
index d7fb1541..9aac3c2d 100644
--- a/packages/ui/src/__tests__/css-cascade.test.ts
+++ b/packages/ui/src/__tests__/css-cascade.test.ts
@@ -279,6 +279,66 @@ describe("grid.css cascade contract", () => {
     expect(reduce).toMatch(/transition:\s*none/);
   });
 
+  test("the kit buttons carry the shared look, the standard ring and the disabled treatment", () => {
+    const css = strippedCss();
+    const rules = rulesSelecting(
+      css,
+      (selector) =>
+        selector.includes("data-pretable-button]") ||
+        selector.includes("data-pretable-icon-button]"),
+    );
+    expect(rules.length, "no kit button rules").toBeGreaterThan(0);
+    const bodies = rules.map((m) => m[2]).join("\n");
+
+    // The shared box every push-button had per site: no border, transparent,
+    // the control radius, the pointer, and the surrounding font.
+    expect(bodies).toMatch(/border:\s*0/);
+    expect(bodies).toMatch(/background:\s*transparent/);
+    expect(bodies).toMatch(/border-radius:\s*var\(--pretable-radius-control\)/);
+    expect(bodies).toMatch(/font:\s*inherit/);
+
+    // The two labelled looks.
+    const ghost = rulesSelecting(css, (s) =>
+      s.includes('data-pretable-variant="ghost"]'),
+    );
+    expect(ghost.map((m) => m[2]).join("")).toMatch(/block-size:\s*24px/);
+    const link = rulesSelecting(css, (s) =>
+      s.includes('data-pretable-variant="link"]'),
+    );
+    expect(link.map((m) => m[2]).join("")).toMatch(/padding:\s*2px 4px/);
+
+    // Hover never paints on a disabled control (#573).
+    for (const [, selector] of rules) {
+      if (selector.includes(":hover")) {
+        expect(
+          selector,
+          `"${selector.trim()}" hovers a disabled button`,
+        ).toContain(":not(:disabled)");
+      }
+    }
+    // The standard ring, and the standard disabled ink.
+    const ring = rules
+      .filter(([, s]) => s.includes(":focus-visible"))
+      .map((m) => m[2])
+      .join("");
+    expect(ring).toMatch(/outline:\s*2px solid var\(--pretable-focus-ring\)/);
+    const disabled = rules
+      .filter(([, s]) => s.includes(":disabled") && !s.includes(":hover"))
+      .map((m) => m[2])
+      .join("");
+    expect(disabled).toMatch(/color:\s*var\(--pretable-text-dim\)/);
+    expect(disabled).toMatch(/cursor:\s*default/);
+
+    // And under forced colours, the system's own disabled ink.
+    const forced = css.slice(css.indexOf("@media (forced-colors: active)"));
+    const forcedDisabled = rulesSelecting(forced, (s) =>
+      s.includes("data-pretable-button]:disabled"),
+    );
+    expect(forcedDisabled.map((m) => m[2]).join("")).toMatch(
+      /color:\s*GrayText/,
+    );
+  });
+
   test("a focused cell draws its ring with `outline`, never `box-shadow`", () => {
     // Two reasons, both load-bearing:
     //

From 22d3496ab5b563869ae9f675e3b42784c8fa61fe Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 10:38:55 -0700
Subject: [PATCH 14/31] test(ui): a push-button site rule declares only what is
 its own

Red until the site rules collapse onto the component rules (Task 10).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 packages/ui/src/__tests__/css-cascade.test.ts | 57 +++++++++++++++++++
 1 file changed, 57 insertions(+)

diff --git a/packages/ui/src/__tests__/css-cascade.test.ts b/packages/ui/src/__tests__/css-cascade.test.ts
index 9aac3c2d..3b71a894 100644
--- a/packages/ui/src/__tests__/css-cascade.test.ts
+++ b/packages/ui/src/__tests__/css-cascade.test.ts
@@ -339,6 +339,63 @@ describe("grid.css cascade contract", () => {
     );
   });
 
+  test("a push-button site rule declares only what is its own", () => {
+    // The component rules own the box: border, background, radius, cursor,
+    // font, the ring, the disabled ink. A site that redeclares any of them
+    // is the old per-site copy coming back — twelve of which is how the
+    // buttons drifted apart in the first place.
+    const css = strippedCss();
+    const OWNED = [
+      /(?:^|[;{\s])border:\s*0/,
+      /(?:^|[;{\s])background:\s*transparent/,
+      /border-radius:\s*var\(--pretable-radius-control\)/,
+      /(?:^|[;{\s])cursor:\s*pointer/,
+      /(?:^|[;{\s])font:\s*inherit/,
+    ];
+    const sites = [
+      "filter-add",
+      "add-group",
+      "expand-all",
+      "collapse-all",
+      "filter-clear",
+      "tool-reset",
+      "filter-funnel",
+      "column-menu-button",
+      "tool-row-menu-button",
+      "chip-remove",
+      "filter-row-remove",
+      "tool-group-remove",
+    ];
+    for (const site of sites) {
+      const rules = rulesSelecting(
+        css,
+        (selector) =>
+          selector.includes(`data-pretable-${site}]`) &&
+          !selector.includes("::") &&
+          !selector.includes(":hover") &&
+          !selector.includes(":focus") &&
+          !selector.includes(":disabled"),
+      );
+      for (const [, selector, body] of rules) {
+        for (const owned of OWNED) {
+          expect(
+            body,
+            `"${selector.trim()}" redeclares ${owned} — the kit button rule owns it`,
+          ).not.toMatch(owned);
+        }
+      }
+      // The ring and the disabled ink are the component's too.
+      const ring = rulesSelecting(css, (s) =>
+        s.includes(`data-pretable-${site}]:focus-visible`),
+      );
+      expect(ring.length, `${site} still carries its own focus ring`).toBe(0);
+      const dis = rulesSelecting(css, (s) =>
+        s.includes(`data-pretable-${site}]:disabled`),
+      );
+      expect(dis.length, `${site} still carries its own disabled rule`).toBe(0);
+    }
+  });
+
   test("a focused cell draws its ring with `outline`, never `box-shadow`", () => {
     // Two reasons, both load-bearing:
     //

From aa192e182b905a8d74f4ac4fddde1c21864aa9c0 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 10:42:19 -0700
Subject: [PATCH 15/31] refactor(react): the five ghost actions render the kit
 Button

+ filter, + group, Add group, Expand all, Collapse all. Each keeps its site
attribute, so nothing that identified it stops identifying it.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../src/tool-panel/filters/FiltersSection.tsx | 15 +++++++------
 .../tool-panel/grouping/GroupingSection.tsx   | 21 +++++++++++--------
 2 files changed, 21 insertions(+), 15 deletions(-)

diff --git a/packages/react/src/tool-panel/filters/FiltersSection.tsx b/packages/react/src/tool-panel/filters/FiltersSection.tsx
index b7a94fa0..859db407 100644
--- a/packages/react/src/tool-panel/filters/FiltersSection.tsx
+++ b/packages/react/src/tool-panel/filters/FiltersSection.tsx
@@ -35,6 +35,7 @@ import {
   type FilterRowLeaf,
 } from "./FilterRow";
 import { JoinControl } from "./JoinControl";
+import { usePretableComponents } from "../../components/context";
 import type { ToolPanelFiltersMessages } from "../messages";
 import {
   depthOf,
@@ -646,6 +647,8 @@ export function FiltersSection({
     };
   }, [loadDistinctValues, wantedKey]);
 
+  const { Button } = usePretableComponents();
+
   const addActions = (groupPath: FilterPath, count: number) => {
     // The depth the NEW node would land at, read from the group being added
     // INTO: `depthOf([])` is -1, so a root add lands at 0. The slot path handed
@@ -690,8 +693,8 @@ export function FiltersSection({
           };
     return (
       <div>
-        <button
-          type="button"
+        <Button
+          site="filter-add"
           data-pretable-filter-add=""
           {...refuse(filterReason)}
           onClick={() => {
@@ -723,9 +726,9 @@ export function FiltersSection({
           }}
         >
           {messages.toolPanelAddFilterLabel()}
-        </button>
-        <button
-          type="button"
+        </Button>
+        <Button
+          site="filter-add"
           data-pretable-filter-add=""
           {...refuse(groupReason)}
           onClick={() => {
@@ -739,7 +742,7 @@ export function FiltersSection({
           }}
         >
           {messages.toolPanelAddGroupLabel()}
-        </button>
+        </Button>
         {[
           ...new Set(
             [filterReason, groupReason].filter(
diff --git a/packages/react/src/tool-panel/grouping/GroupingSection.tsx b/packages/react/src/tool-panel/grouping/GroupingSection.tsx
index a54acb16..31cab41b 100644
--- a/packages/react/src/tool-panel/grouping/GroupingSection.tsx
+++ b/packages/react/src/tool-panel/grouping/GroupingSection.tsx
@@ -16,6 +16,7 @@ import type { GroupingSectionMessages } from "../messages";
 import type { ToolDropTarget, ToolRowRect } from "../tool-panel-drop-target";
 import { useToolRowDrag } from "../useToolRowDrag";
 import { AddGroupMenu } from "./AddGroupMenu";
+import { usePretableComponents } from "../../components/context";
 // Direct import, not the barrel: the barrel deliberately withholds
 // aggregate-options (it is the section's internal vocabulary, not API).
 import {
@@ -353,6 +354,8 @@ export function GroupingSection({
   // (`groupedIds.length` = after the last row).
   const indicatorAt = drag !== null ? drag.target.beforeRow : null;
 
+  const { Button } = usePretableComponents();
+
   return (
     // tabIndex -1: never in the tab order, but a programmatic focus landing
     // for the add-menu close when the button itself has become disabled.
@@ -437,7 +440,8 @@ export function GroupingSection({
             {messages.toolPanelNoGroupsMessage()}
           </div>
         ) : null}
-        <button
+        <Button
+          site="add-group"
           aria-expanded={menu !== null}
           aria-haspopup="menu"
           data-pretable-add-group=""
@@ -451,10 +455,9 @@ export function GroupingSection({
           onClick={(event) => {
             toggleMenu("menu", "add-group", event.currentTarget);
           }}
-          type="button"
         >
           {messages.toolPanelAddRowGroupLabel()}
-        </button>
+        </Button>
         {menu !== null && ungrouped.length > 0 ? (
           <AddGroupMenu
             messages={messages}
@@ -476,22 +479,22 @@ export function GroupingSection({
         display:none, so the pane's shape does not jump as grouping comes
         and goes. */}
       <div>
-        <button
+        <Button
+          site="expand-all"
           data-pretable-expand-all=""
           disabled={groupedIds.length === 0}
           onClick={() => rowModel.expandAll()}
-          type="button"
         >
           {messages.toolPanelExpandAllLabel()}
-        </button>
-        <button
+        </Button>
+        <Button
+          site="collapse-all"
           data-pretable-collapse-all=""
           disabled={groupedIds.length === 0}
           onClick={() => rowModel.collapseAll()}
-          type="button"
         >
           {messages.toolPanelCollapseAllLabel()}
-        </button>
+        </Button>
       </div>
       {/* Hide-grouped-columns switch (spec decision 8): a labelled checkbox
         over ENGINE state — read above via the section's own subscription,

From f58fad6878a4809216f206285a056e6cb3c7ec17 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 10:46:42 -0700
Subject: [PATCH 16/31] refactor(react): Clear and Reset columns render the kit
 Button, link variant

The Clear button is inside the portalled filter dialog, which is the case
the components context exists for.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 packages/react/src/filter-menu/FilterMenu.tsx    | 12 ++++++++++--
 packages/react/src/tool-panel/ColumnsSection.tsx | 12 ++++++++++--
 2 files changed, 20 insertions(+), 4 deletions(-)

diff --git a/packages/react/src/filter-menu/FilterMenu.tsx b/packages/react/src/filter-menu/FilterMenu.tsx
index 8e10773e..c8cf2547 100644
--- a/packages/react/src/filter-menu/FilterMenu.tsx
+++ b/packages/react/src/filter-menu/FilterMenu.tsx
@@ -25,6 +25,7 @@ import {
   toColumnFilter,
   type FilterDraft,
 } from "./filter-operators";
+import { usePretableComponents } from "../components/context";
 import { OverlayPortal } from "../overlay/OverlayPortal";
 
 const DEBOUNCE_MS = 200;
@@ -291,6 +292,8 @@ export function FilterMenu({
     [draft, pushNow],
   );
 
+  const { Button } = usePretableComponents();
+
   return (
     <OverlayPortal>
       <div
@@ -393,9 +396,14 @@ export function FilterMenu({
           </div>
         ) : null}
 
-        <button type="button" data-pretable-filter-clear="" onClick={onClear}>
+        <Button
+          variant="link"
+          site="filter-clear"
+          data-pretable-filter-clear=""
+          onClick={onClear}
+        >
           Clear
-        </button>
+        </Button>
       </div>
     </OverlayPortal>
   );
diff --git a/packages/react/src/tool-panel/ColumnsSection.tsx b/packages/react/src/tool-panel/ColumnsSection.tsx
index 6c1b0ce8..d9ede063 100644
--- a/packages/react/src/tool-panel/ColumnsSection.tsx
+++ b/packages/react/src/tool-panel/ColumnsSection.tsx
@@ -11,6 +11,7 @@ import {
 
 import { GROUP_COLUMN_ID } from "@pretable/core";
 
+import { usePretableComponents } from "../components/context";
 import { ROW_SELECT_COLUMN_ID } from "../constants";
 import { CheckIcon, GripIcon, OverflowIcon } from "../icons";
 import type { AutoWidthSetReader } from "../pretable-model";
@@ -118,6 +119,8 @@ export function ColumnsSection({
   autoWidths,
   messages,
 }: ColumnsSectionProps) {
+  const { Button } = usePretableComponents();
+
   // Live engine state, read through the section's OWN subscription — never a
   // snapshot baked into the descriptor closure. The read returns the state's
   // `columnLayout` array, whose identity only changes on a layout publish, so
@@ -583,9 +586,14 @@ export function ColumnsSection({
           />
         );
       })()}
-      <button data-pretable-tool-reset="" onClick={reset} type="button">
+      <Button
+        variant="link"
+        site="tool-reset"
+        data-pretable-tool-reset=""
+        onClick={reset}
+      >
         {messages.toolPanelResetColumnsLabel()}
-      </button>
+      </Button>
     </>
   );
 }

From 56de06233a4df80b3592a8d7b19747032e05b337 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 10:48:46 -0700
Subject: [PATCH 17/31] test(react): the ref test proves the replacement
 rendered; the memo test says what it pins

The kebab-menu test opened the menu on the built-in as readily as on a
replacement, so it could not fail; it now asserts the node is the replacement
first. The remount test's comment claimed the memo, which a same-type
reconcile hides from it; the memo is pinned at the hook level, and the comment
now points there.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../src/__tests__/components-override.test.tsx      | 13 ++++++++++---
 packages/react/src/pretable.tsx                     |  1 +
 2 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/packages/react/src/__tests__/components-override.test.tsx b/packages/react/src/__tests__/components-override.test.tsx
index 5ca5a5ea..4a661565 100644
--- a/packages/react/src/__tests__/components-override.test.tsx
+++ b/packages/react/src/__tests__/components-override.test.tsx
@@ -115,9 +115,13 @@ describe("components on the surface", () => {
   });
 
   it("a fresh object literal with the same components does not remount the buttons", () => {
-    // Inline `components={{ Button: MyButton }}` is the common way to write
-    // it, and it produces a new object every render. The resolved map is
-    // memoised on the slot VALUES, so the node survives a re-render.
+    // Inline `components={{ Button: MyButton }}` produces a new object every
+    // render; this pins that a re-render with it does not REMOUNT the button
+    // node. It does not pin the memo — a same-type element reconciles to the
+    // same node whether or not the context value changed identity — so the
+    // memoisation itself is proven at the hook level, in
+    // components-button.test.tsx ("a stable input is a stable output" and
+    // "a changed slot yields a new map").
     const view = renderSurface({ Button: MyButton });
     const before = view.getByRole("button", { name: "Reset columns" });
     view.rerender(
@@ -141,6 +145,9 @@ describe("components on the surface", () => {
     const kebab = view.container.querySelector(
       "[data-pretable-tool-row-menu-button]",
     )!;
+    // Prove the node IS the replacement before asking anything of it —
+    // otherwise the menu opening proves nothing about the forwarded ref.
+    expect(kebab).toHaveAttribute("data-mine-icon", "tool-row-menu-button");
     fireEvent.pointerDown(kebab);
     fireEvent.click(kebab);
     expect(
diff --git a/packages/react/src/pretable.tsx b/packages/react/src/pretable.tsx
index ab65ff51..74c90603 100644
--- a/packages/react/src/pretable.tsx
+++ b/packages/react/src/pretable.tsx
@@ -118,6 +118,7 @@ export interface PretableBaseProps<
     TColumns
   >["copyToClipboard"];
   messages?: PretableSurfaceSharedProps<TRow, TRowId, TColumns>["messages"];
+  /** Replace a kit component everywhere it appears; see `PretableSurfaceSharedProps.components`. */
   components?: PretableSurfaceSharedProps<TRow, TRowId, TColumns>["components"];
   /** The tool panel rail at the grid's right edge. On by default — the
    *  default lives in the surface, so the preset only ever forwards; pass

From 178902756244246ef40f8b0ee1a16df605361cbe Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 10:53:55 -0700
Subject: [PATCH 18/31] test(ui): the button guards check declarations, not
 selector counts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The site-rule guard demanded zero :focus-visible rules per site, which would
have forced the funnel's and the column menu's keyboard reveal (opacity: 1)
out of the file — a focus-visibility regression arriving through a test
whose message said the opposite. It now forbids the ring's DECLARATION at a
site, keeps a positive check of what each site genuinely owns so a deleted
rule cannot pass, forbids the whole shared box rather than five of its
lines, and its list is mirrored into the kit guard so the two read the same
list from both ends. A third guard pins the source order the design rests
on. Two stay red by design until the site rules collapse.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 packages/ui/src/__tests__/css-cascade.test.ts | 256 +++++++++++++++---
 1 file changed, 225 insertions(+), 31 deletions(-)

diff --git a/packages/ui/src/__tests__/css-cascade.test.ts b/packages/ui/src/__tests__/css-cascade.test.ts
index 3b71a894..6984ae92 100644
--- a/packages/ui/src/__tests__/css-cascade.test.ts
+++ b/packages/ui/src/__tests__/css-cascade.test.ts
@@ -16,6 +16,36 @@ const strippedCss = () =>
 const rulesSelecting = (css: string, match: (selector: string) => boolean) =>
   [...css.matchAll(/([^{}]+)\{([^{}]*)\}/g)].filter((m) => match(m[1]));
 
+/** The `@media (forced-colors: active)` block ALONE. Slicing to EOF instead
+ *  lets a rule from a later block — reduced motion, or whatever is added
+ *  next — satisfy an assertion that says "under forced colours". */
+const forcedColorsBlock = (css: string) => {
+  const at = css.indexOf("@media (forced-colors: active)");
+  if (at < 0) return "";
+  const next = css.indexOf("@media", at + 1);
+  return next < 0 ? css.slice(at) : css.slice(at, next);
+};
+
+/** The twelve plain push-button sites the kit rules collapsed. The first six
+ *  are labelled (text in the accent), the last six are icon boxes. */
+const LABELLED_BUTTON_SITES = [
+  "filter-add",
+  "add-group",
+  "expand-all",
+  "collapse-all",
+  "filter-clear",
+  "tool-reset",
+];
+const ICON_BUTTON_SITES = [
+  "filter-funnel",
+  "column-menu-button",
+  "tool-row-menu-button",
+  "chip-remove",
+  "filter-row-remove",
+  "tool-group-remove",
+];
+const PUSH_BUTTON_SITES = [...LABELLED_BUTTON_SITES, ...ICON_BUTTON_SITES];
+
 /** The token names pretable.css declares — the contract a section may read
  *  from and must not add to. Same source the token contract test loads. */
 const tokenContract = () => {
@@ -212,7 +242,7 @@ describe("grid.css cascade contract", () => {
     // selected and unselected cells both computed rgb(255,255,255) on
     // rgb(0,0,0).
     const css = strippedCss();
-    const forced = css.slice(css.indexOf("@media (forced-colors: active)"));
+    const forced = forcedColorsBlock(css);
     expect(css, "no forced-colors block at all").toContain(
       "@media (forced-colors: active)",
     );
@@ -296,6 +326,45 @@ describe("grid.css cascade contract", () => {
     expect(bodies).toMatch(/background:\s*transparent/);
     expect(bodies).toMatch(/border-radius:\s*var\(--pretable-radius-control\)/);
     expect(bodies).toMatch(/font:\s*inherit/);
+    // Every declaration the site guard forbids at a site is asserted here, so
+    // the two read the same list from both ends and dropping one from the kit
+    // cannot go unnoticed. `position: relative` is deliberately NOT on it: it
+    // stays per-site, on the three buttons that enlarge their hit area with an
+    // ::after.
+    expect(bodies).toMatch(/(?:^|[;{\s])cursor:\s*pointer/);
+    expect(bodies).toMatch(/(?:^|[;{\s])display:\s*inline-flex/);
+    expect(bodies).toMatch(/(?:^|[;{\s])align-items:\s*center/);
+    expect(bodies).toMatch(/(?:^|[;{\s])justify-content:\s*center/);
+    expect(bodies).toMatch(/(?:^|[;{\s])box-sizing:\s*border-box/);
+
+    // The labelled voice and the icon box each sit on their own attribute, so
+    // each is read from the rules that name only that attribute.
+    const labelledOnly = rules
+      .filter(
+        ([, s]) =>
+          s.includes("data-pretable-button]") &&
+          !s.includes("data-pretable-icon-button]"),
+      )
+      .map((m) => m[2])
+      .join("\n");
+    expect(
+      labelledOnly,
+      "the labelled button no longer speaks in the accent",
+    ).toMatch(/color:\s*var\(--pretable-accent\)/);
+    const iconOnly = rules
+      .filter(
+        ([, s]) =>
+          s.includes("data-pretable-icon-button]") &&
+          !s.includes("data-pretable-button]"),
+      )
+      .map((m) => m[2])
+      .join("\n");
+    expect(iconOnly, "the icon box no longer refuses to stretch").toMatch(
+      /(?:^|[;{\s])flex:\s*none/,
+    );
+    expect(iconOnly, "the icon box no longer zeroes its padding").toMatch(
+      /(?:^|[;{\s])padding:\s*0\s*;/,
+    );
 
     // The two labelled looks.
     const ghost = rulesSelecting(css, (s) =>
@@ -330,7 +399,7 @@ describe("grid.css cascade contract", () => {
     expect(disabled).toMatch(/cursor:\s*default/);
 
     // And under forced colours, the system's own disabled ink.
-    const forced = css.slice(css.indexOf("@media (forced-colors: active)"));
+    const forced = forcedColorsBlock(css);
     const forcedDisabled = rulesSelecting(forced, (s) =>
       s.includes("data-pretable-button]:disabled"),
     );
@@ -340,10 +409,15 @@ describe("grid.css cascade contract", () => {
   });
 
   test("a push-button site rule declares only what is its own", () => {
-    // The component rules own the box: border, background, radius, cursor,
-    // font, the ring, the disabled ink. A site that redeclares any of them
-    // is the old per-site copy coming back — twelve of which is how the
-    // buttons drifted apart in the first place.
+    // The kit rules own the box: the border, the background, the radius, the
+    // cursor, the font, the flex centring, the ring and the disabled ink. A
+    // site that redeclares any of them is the old per-site copy coming back —
+    // twelve of which is how the buttons drifted apart in the first place.
+    //
+    // `position: relative` is deliberately NOT on this list. It stays per
+    // site, on the three buttons that buy WCAG 2.5.8 target size with an
+    // ::after: only those need a containing block, and the kit rule that gave
+    // it to every icon button is what is being removed.
     const css = strippedCss();
     const OWNED = [
       /(?:^|[;{\s])border:\s*0/,
@@ -351,51 +425,171 @@ describe("grid.css cascade contract", () => {
       /border-radius:\s*var\(--pretable-radius-control\)/,
       /(?:^|[;{\s])cursor:\s*pointer/,
       /(?:^|[;{\s])font:\s*inherit/,
+      /(?:^|[;{\s])display:\s*inline-flex/,
+      /(?:^|[;{\s])align-items:\s*center/,
+      /(?:^|[;{\s])justify-content:\s*center/,
+      /(?:^|[;{\s])box-sizing:\s*border-box/,
     ];
-    const sites = [
-      "filter-add",
-      "add-group",
-      "expand-all",
-      "collapse-all",
-      "filter-clear",
-      "tool-reset",
-      "filter-funnel",
-      "column-menu-button",
-      "tool-row-menu-button",
-      "chip-remove",
-      "filter-row-remove",
-      "tool-group-remove",
+    // A labelled button speaks in the accent, an icon button is a fixed box
+    // that will not stretch — each on its own kit attribute, so each is
+    // forbidden only at the sites it covers.
+    const LABELLED_OWNED = [/(?:^|[;{\s])color:\s*var\(--pretable-accent\)/];
+    const ICON_OWNED = [
+      /(?:^|[;{\s])flex:\s*none/,
+      /(?:^|[;{\s])padding:\s*0\s*;/,
     ];
-    for (const site of sites) {
+
+    // What each site genuinely OWNS, and must keep after the collapse: a
+    // size, a reveal, an alignment. Without this the guard passes for a site
+    // whose rule was deleted outright rather than collapsed into the kit.
+    // `null` means the site owns nothing of its own — for those the check
+    // runs the other way: nothing left is fine, something left is not,
+    // because whatever it were would be the kit's.
+    const OWN: Record<string, RegExp | null> = {
+      // Only ever rode the four-site shared ghost rule; the collapse takes
+      // every line of it. What lays `+ filter` out is its block container.
+      "filter-add": null,
+      "add-group": /align-self:\s*flex-start/,
+      "expand-all": /flex-direction:\s*row/,
+      // Rides the expansion block's :has() rule, which is keyed on its
+      // partner's attribute, so it names nothing of its own either.
+      "collapse-all": null,
+      "filter-clear": /align-self:\s*flex-end/,
+      "tool-reset": /align-self:\s*flex-end/,
+      "filter-funnel": /width:\s*18px|inline-size:\s*18px/,
+      "column-menu-button": /width:\s*18px|inline-size:\s*18px/,
+      "tool-row-menu-button": /inline-size:\s*18px|width:\s*18px/,
+      "chip-remove": /width:\s*14px|inline-size:\s*14px/,
+      "filter-row-remove": /inline-size:\s*24px|width:\s*24px/,
+      "tool-group-remove": /inline-size:\s*24px|width:\s*24px/,
+    };
+
+    for (const site of PUSH_BUTTON_SITES) {
+      const attr = `data-pretable-${site}]`;
+      // Every rule that NAMES the site and is not a state or a pseudo —
+      // including the :has() ancestor rules, which is where two of these
+      // sites keep the whole of what they own.
       const rules = rulesSelecting(
         css,
         (selector) =>
-          selector.includes(`data-pretable-${site}]`) &&
+          selector.includes(attr) &&
           !selector.includes("::") &&
           !selector.includes(":hover") &&
           !selector.includes(":focus") &&
           !selector.includes(":disabled"),
       );
+      const forbidden = [
+        ...OWNED,
+        ...(LABELLED_BUTTON_SITES.includes(site) ? LABELLED_OWNED : ICON_OWNED),
+      ];
       for (const [, selector, body] of rules) {
-        for (const owned of OWNED) {
+        for (const owned of forbidden) {
           expect(
             body,
             `"${selector.trim()}" redeclares ${owned} — the kit button rule owns it`,
           ).not.toMatch(owned);
         }
       }
-      // The ring and the disabled ink are the component's too.
-      const ring = rulesSelecting(css, (s) =>
-        s.includes(`data-pretable-${site}]:focus-visible`),
-      );
-      expect(ring.length, `${site} still carries its own focus ring`).toBe(0);
-      const dis = rulesSelecting(css, (s) =>
-        s.includes(`data-pretable-${site}]:disabled`),
-      );
-      expect(dis.length, `${site} still carries its own disabled rule`).toBe(0);
+
+      // And the positive half: the site still says what is genuinely its own.
+      // Without it every assertion above is satisfied by deleting the rule,
+      // which is a different bug wearing this guard's green.
+      const own = OWN[site];
+      if (own) {
+        expect(
+          rules.map((m) => m[2]).join("\n"),
+          `${site} declares nothing of its own — its rule was deleted, not collapsed`,
+        ).toMatch(own);
+      } else {
+        expect(
+          rules.length,
+          `${site} owns nothing of its own, so anything left selecting it belongs to the kit`,
+        ).toBe(0);
+      }
+
+      // The ring and the disabled ink are the kit's — but the ban is on the
+      // DECLARATION, not on the rule. The funnel and the header ⋮ both answer
+      // :focus-visible with `opacity: 1`: that is a keyboard REVEAL of a
+      // hover-hidden control, the site's own business, and a guard demanding
+      // zero :focus-visible rules per site would have driven it out of the
+      // file — a keyboard-focused funnel that stays invisible.
+      for (const [, selector, body] of rulesSelecting(css, (selector) =>
+        selector.includes(`${attr}:focus-visible`),
+      )) {
+        expect(
+          body,
+          `"${selector.trim()}" draws ${site} its own focus ring; the kit owns the ring`,
+        ).not.toMatch(/(?:^|[;{\s])outline(?:-[a-z]+)?:/);
+      }
+      for (const [, selector, body] of rulesSelecting(css, (selector) =>
+        selector.includes(`${attr}:disabled`),
+      )) {
+        for (const decl of [/(?:^|[;{\s])color:/, /(?:^|[;{\s])cursor:/]) {
+          expect(
+            body,
+            `"${selector.trim()}" gives ${site} its own disabled treatment; the kit owns it`,
+          ).not.toMatch(decl);
+        }
+      }
     }
   });
 
+  test("the kit rules bracket the site rules in source order", () => {
+    // Everything above rests on source order, because every one of these
+    // rules sits at :where()'s zero specificity: the kit's shared box has to
+    // come BEFORE the site rules so a site's size or alignment still wins,
+    // and the kit's :focus-visible and :disabled have to come AFTER them so
+    // no site rule can overwrite the ring or the disabled ink from below.
+    //
+    // The state half is RED at HEAD by design: the two state rules still sit
+    // with the kit near the top of the layer, and the task that collapses the
+    // site rules moves them to the end of the layer. The first half already
+    // passes.
+    const css = strippedCss();
+    const kitBase = css.indexOf(
+      ":where([data-pretable-button], [data-pretable-icon-button])",
+    );
+    expect(kitBase, "no kit base rule").toBeGreaterThan(-1);
+
+    const positions = (attr: string) => {
+      const out: number[] = [];
+      for (let at = css.indexOf(attr); at > -1; at = css.indexOf(attr, at + 1))
+        out.push(at);
+      return out;
+    };
+    const sitePositions = PUSH_BUTTON_SITES.flatMap((site) =>
+      positions(`data-pretable-${site}]`),
+    );
+    expect(sitePositions.length, "no site rules at all").toBeGreaterThan(0);
+    expect(
+      kitBase,
+      "the kit's shared box comes after a site rule, which then cannot win at equal specificity",
+    ).toBeLessThan(Math.min(...sitePositions));
+
+    // Measured against the site rules OUTSIDE the media blocks: the coarse
+    // and forced-colours blocks at the end of the layer are the file's last
+    // word by construction, and holding the state rules after those would say
+    // nothing about the ordering this design rests on.
+    const firstMedia = css.indexOf("@media");
+    expect(firstMedia, "no @media block at all").toBeGreaterThan(-1);
+    const lastSite = Math.max(...sitePositions.filter((at) => at < firstMedia));
+
+    const ring = css.search(
+      /:where\(\s*\[data-pretable-button\]:focus-visible/,
+    );
+    expect(ring, "no kit focus-visible rule").toBeGreaterThan(-1);
+    expect(
+      ring,
+      "the kit ring precedes a site rule, which can then overwrite it at equal specificity",
+    ).toBeGreaterThan(lastSite);
+    const disabled = css.search(/:where\(\s*\[data-pretable-button\]:disabled/);
+    expect(disabled, "no kit disabled rule").toBeGreaterThan(-1);
+    expect(
+      disabled,
+      "the kit disabled treatment precedes a site rule, which can then overwrite it",
+    ).toBeGreaterThan(lastSite);
+  });
+
   test("a focused cell draws its ring with `outline`, never `box-shadow`", () => {
     // Two reasons, both load-bearing:
     //

From d71641f8966287006156d752f7e975e19937f984 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 11:00:21 -0700
Subject: [PATCH 19/31] refactor(react): the six icon buttons render the kit
 IconButton

Funnel, column menu, row kebab, chip remove, filter-row remove and group
remove. Every site keeps its attribute, its ref, its tabindex and its
handlers; the override suite goes fully green.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 packages/react/src/column-menu/MenuButton.tsx            | 9 ++++++---
 packages/react/src/filter-menu/FunnelButton.tsx          | 9 ++++++---
 packages/react/src/group-panel/GroupPanel.tsx            | 9 ++++++---
 packages/react/src/tool-panel/ColumnsSection.tsx         | 8 ++++----
 packages/react/src/tool-panel/filters/FilterRow.tsx      | 8 +++++---
 .../react/src/tool-panel/grouping/GroupingSection.tsx    | 8 ++++----
 6 files changed, 31 insertions(+), 20 deletions(-)

diff --git a/packages/react/src/column-menu/MenuButton.tsx b/packages/react/src/column-menu/MenuButton.tsx
index fb1b8c5f..f31a7c49 100644
--- a/packages/react/src/column-menu/MenuButton.tsx
+++ b/packages/react/src/column-menu/MenuButton.tsx
@@ -1,5 +1,6 @@
 // packages/react/src/column-menu/MenuButton.tsx
 import { createElement, type CSSProperties } from "react";
+import { usePretableComponents } from "../components/context";
 import { OverflowIcon } from "../icons";
 
 /**
@@ -22,9 +23,11 @@ export function MenuButton({
   onNodeChange?: (columnId: string, node: HTMLButtonElement | null) => void;
   onToggle: (columnId: string, anchor: HTMLElement) => void;
 }) {
+  const { IconButton } = usePretableComponents();
+
   return (
-    <button
-      type="button"
+    <IconButton
+      site="column-menu-button"
       data-pretable-column-menu-button=""
       data-pretable-column-id={columnId}
       aria-haspopup="menu"
@@ -51,6 +54,6 @@ export function MenuButton({
       }}
     >
       <OverflowIcon />
-    </button>
+    </IconButton>
   );
 }
diff --git a/packages/react/src/filter-menu/FunnelButton.tsx b/packages/react/src/filter-menu/FunnelButton.tsx
index 81ca061f..a37c26ec 100644
--- a/packages/react/src/filter-menu/FunnelButton.tsx
+++ b/packages/react/src/filter-menu/FunnelButton.tsx
@@ -1,5 +1,6 @@
 // packages/react/src/filter-menu/FunnelButton.tsx
 import { createElement, type CSSProperties } from "react";
+import { usePretableComponents } from "../components/context";
 import { FunnelIcon } from "../icons";
 
 export function FunnelButton({
@@ -17,9 +18,11 @@ export function FunnelButton({
   style?: CSSProperties;
   onToggle: (columnId: string, anchor: HTMLElement) => void;
 }) {
+  const { IconButton } = usePretableComponents();
+
   return (
-    <button
-      type="button"
+    <IconButton
+      site="filter-funnel"
       data-pretable-filter-funnel=""
       data-pretable-column-id={columnId}
       data-pretable-filter-active={active ? "true" : "false"}
@@ -48,6 +51,6 @@ export function FunnelButton({
       }}
     >
       <FunnelIcon />
-    </button>
+    </IconButton>
   );
 }
diff --git a/packages/react/src/group-panel/GroupPanel.tsx b/packages/react/src/group-panel/GroupPanel.tsx
index b28e51b4..024afa22 100644
--- a/packages/react/src/group-panel/GroupPanel.tsx
+++ b/packages/react/src/group-panel/GroupPanel.tsx
@@ -23,6 +23,7 @@ import {
   moveGroupLevel,
   removeGroupLevel,
 } from "./group-panel-model";
+import { usePretableComponents } from "../components/context";
 import { CloseIcon, GripIcon } from "../icons";
 
 /** Matches the header reorder drag's threshold, so both grabs feel the same. */
@@ -93,6 +94,8 @@ export function GroupPanel({
   onChange,
   style,
 }: GroupPanelProps) {
+  const { IconButton } = usePretableComponents();
+
   // The roving tab stop. This is the panel's ONLY state, and it is about the
   // keyboard rather than about the grouping — the levels themselves stay a
   // pure projection of the prop.
@@ -462,7 +465,8 @@ export function GroupPanel({
                 oversight to fix by changing the role (the spec commits to
                 listbox/option) — it is why Delete on the focused chip exists
                 as the equivalent keyboard path. */}
-            <button
+            <IconButton
+              site="chip-remove"
               aria-label={`Remove ${label} from grouping`}
               data-pretable-chip-remove=""
               onClick={(event) => {
@@ -480,10 +484,9 @@ export function GroupPanel({
                 );
               }}
               tabIndex={-1}
-              type="button"
             >
               <CloseIcon />
-            </button>
+            </IconButton>
           </div>,
         ];
       })}
diff --git a/packages/react/src/tool-panel/ColumnsSection.tsx b/packages/react/src/tool-panel/ColumnsSection.tsx
index d9ede063..ef496194 100644
--- a/packages/react/src/tool-panel/ColumnsSection.tsx
+++ b/packages/react/src/tool-panel/ColumnsSection.tsx
@@ -119,7 +119,7 @@ export function ColumnsSection({
   autoWidths,
   messages,
 }: ColumnsSectionProps) {
-  const { Button } = usePretableComponents();
+  const { Button, IconButton } = usePretableComponents();
 
   // Live engine state, read through the section's OWN subscription — never a
   // snapshot baked into the descriptor closure. The read returns the state's
@@ -507,7 +507,8 @@ export function ColumnsSection({
                       {visible ? <CheckIcon /> : null}
                     </button>
                     <span data-pretable-tool-column-label="">{label}</span>
-                    <button
+                    <IconButton
+                      site="tool-row-menu-button"
                       aria-expanded={openColumnId === entry.id}
                       aria-haspopup="menu"
                       aria-label={messages.toolPanelColumnMenuLabel({ label })}
@@ -526,10 +527,9 @@ export function ColumnsSection({
                       onClick={(e) => {
                         toggleMenu("menu", entry.id, e.currentTarget);
                       }}
-                      type="button"
                     >
                       <OverflowIcon />
-                    </button>
+                    </IconButton>
                   </div>
                 </Fragment>
               );
diff --git a/packages/react/src/tool-panel/filters/FilterRow.tsx b/packages/react/src/tool-panel/filters/FilterRow.tsx
index 6d1bbbeb..a61884ad 100644
--- a/packages/react/src/tool-panel/filters/FilterRow.tsx
+++ b/packages/react/src/tool-panel/filters/FilterRow.tsx
@@ -16,6 +16,7 @@ import {
   OPERATOR_LABELS,
   type FilterDraft,
 } from "../../filter-menu/filter-operators";
+import { usePretableComponents } from "../../components/context";
 import { CloseIcon } from "../../icons";
 import type { FilterRowMessages } from "../messages";
 
@@ -173,6 +174,7 @@ export function FilterRow({
   processing,
   messages,
 }: FilterRowProps) {
+  const { IconButton } = usePretableComponents();
   const column = columns.find((c) => c.id === columnId);
   const type = column?.type ?? "text";
   const label = column?.label ?? columnId;
@@ -407,8 +409,8 @@ export function FilterRow({
           whole filter, and an inert input beside it would invite a value the
           engine discards. */}
 
-      <button
-        type="button"
+      <IconButton
+        site="filter-row-remove"
         data-pretable-filter-row-remove=""
         // Named by what it removes. A pane of these is otherwise a list of
         // identical `Remove` buttons, which is exactly what a screen-reader
@@ -417,7 +419,7 @@ export function FilterRow({
         onClick={onRemove}
       >
         <CloseIcon />
-      </button>
+      </IconButton>
     </div>
   );
 }
diff --git a/packages/react/src/tool-panel/grouping/GroupingSection.tsx b/packages/react/src/tool-panel/grouping/GroupingSection.tsx
index 31cab41b..3054641c 100644
--- a/packages/react/src/tool-panel/grouping/GroupingSection.tsx
+++ b/packages/react/src/tool-panel/grouping/GroupingSection.tsx
@@ -354,7 +354,7 @@ export function GroupingSection({
   // (`groupedIds.length` = after the last row).
   const indicatorAt = drag !== null ? drag.target.beforeRow : null;
 
-  const { Button } = usePretableComponents();
+  const { Button, IconButton } = usePretableComponents();
 
   return (
     // tabIndex -1: never in the tab order, but a programmatic focus landing
@@ -418,16 +418,16 @@ export function GroupingSection({
                   <GripIcon />
                 </span>
                 <span data-pretable-tool-column-label="">{label}</span>
-                <button
+                <IconButton
+                  site="tool-group-remove"
                   aria-label={messages.toolPanelRemoveGroupLabel({ label })}
                   data-pretable-tool-group-remove=""
                   onClick={() =>
                     applyRowGroups(groupedIds.filter((id) => id !== columnId))
                   }
-                  type="button"
                 >
                   <CloseIcon />
-                </button>
+                </IconButton>
               </div>
             </Fragment>
           );

From b27670486c23fc57a0c3659852b9405525c01851 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 11:05:12 -0700
Subject: [PATCH 20/31] refactor(ui): the push-button site rules collapse onto
 the kit rules
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Twelve sites keep a size, a reveal, an alignment; the box, ring and disabled
ink are the component's. Kit state rules move to the end of the layer so a
site's own state colour cannot outrank the disabled ink; position: relative
leaves the kit icon rule and stays only where a ::after hit area needs it
(funnel, column menu, row kebab) — on the two remove buttons, which sit in
flow among later siblings, it would have reordered painting; the two shared
focus lists are split, not deleted, so the five non-button controls on them
keep their ring.

Deliberate changes, from the review, not regressions: filter-clear and
tool-reset gain the kit's border-radius and the product focus ring
(tool-reset wore the UA ring); for a consumer without a CSS reset
filter-clear also gains the dialog's font, which Tailwind preflight already
gave it on our own site; the funnel and the column-menu button gain
flex: none.

Four older guards read declarations that have moved onto the kit rules
(a radius, two padding: 0s, box-sizing, the ghost box and its disabled
state, and the existence of a [data-pretable-filter-add] rule). Each is
re-pointed at the kit rule that now carries it rather than dropped, so the
same claim is still made from the one place it is true.

Guards mutation-checked: border: 0 added back to the funnel's base rule
fails "a push-button site rule declares only what is its own" ("redeclares
/border:\s*0/ — the kit button rule owns it"); the kit :disabled rule moved
back to the top section fails "the kit rules bracket the site rules in
source order" ("expected 2545 to be greater than 36192"). Both reverted;
packages/ui 109/109, packages/react override suite 7/7, typecheck and lint
clean.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 packages/ui/grid.css                          | 209 ++++--------------
 packages/ui/src/__tests__/css-cascade.test.ts |  51 +++--
 2 files changed, 83 insertions(+), 177 deletions(-)

diff --git a/packages/ui/grid.css b/packages/ui/grid.css
index 5e909c3e..c37e1ee4 100644
--- a/packages/ui/grid.css
+++ b/packages/ui/grid.css
@@ -109,7 +109,11 @@
      a reveal, an alignment. These rules come FIRST in the file so a site
      rule can still win at equal specificity by source order. The site
      attribute (`data-pretable-filter-clear`) still arrives on the element,
-     so every selector keyed on it keeps working. */
+     so every selector keyed on it keeps working.
+     `font: inherit` resolves correctly here because every surface a labelled
+     button sits in declares its own font trio — see the filter menu's comment
+     about portaled surfaces below; a `PretableButton` rendered straight into
+     a bare portal would inherit the HOST PAGE instead. */
   :where([data-pretable-button], [data-pretable-icon-button]) {
     box-sizing: border-box;
     display: inline-flex;
@@ -149,27 +153,13 @@
     padding: 2px 4px;
   }
   /* An icon button is a fixed box its site sizes (14, 18 and 24px boxes all
-     exist); `position: relative` is for the sites that enlarge the hit area
-     with a ::after. */
+     exist). NO `position: relative` here: it moves an in-flow flex item into
+     the positioned paint phase, which for the two remove buttons that sit in
+     flow among later siblings would reorder painting. The three sites that
+     need a containing block for a ::after hit area declare it themselves. */
   :where([data-pretable-icon-button]) {
     flex: none;
     padding: 0;
-    position: relative;
-  }
-  :where(
-    [data-pretable-button]:focus-visible,
-    [data-pretable-icon-button]:focus-visible
-  ) {
-    outline: 2px solid var(--pretable-focus-ring);
-    outline-offset: -2px;
-  }
-  /* The standard disabled treatment (#573): dim by token, drop the pointer. */
-  :where(
-    [data-pretable-button]:disabled,
-    [data-pretable-icon-button]:disabled
-  ) {
-    color: var(--pretable-text-dim);
-    cursor: default;
   }
 
   /* Multi-sort priority badge (rendered only when 2+ columns are sorted) */
@@ -954,21 +944,12 @@
      (css-cascade.test.ts). A new funnel-family attribute belongs on that
      list; a new builder attribute does not. */
   :where([data-pretable-filter-funnel]) {
-    display: inline-flex;
-    align-items: center;
-    justify-content: center;
     width: 18px;
     height: 18px;
-    padding: 0;
-    border: 0;
-    border-radius: var(--pretable-radius-control);
-    background: transparent;
-    color: var(--pretable-text-dim);
-    cursor: pointer;
-    opacity: 0;
-    transition: opacity 0.1s ease;
     /* Containing block for the ::after hit area below. */
     position: relative;
+    opacity: 0;
+    transition: opacity 0.1s ease;
   }
   /* WCAG 2.5.8 (Target Size, Minimum) asks for 24x24 CSS px. The funnel drew
      an 18x18 tap target on every filterable column, so a phone got an 18px
@@ -1074,8 +1055,7 @@
      already share. */
   :where(
     [data-pretable-filter-menu] select:focus-visible,
-    [data-pretable-filter-menu] input:focus-visible,
-    [data-pretable-filter-clear]:focus-visible
+    [data-pretable-filter-menu] input:focus-visible
   ) {
     outline: 2px solid var(--pretable-focus-ring);
     outline-offset: -2px;
@@ -1087,11 +1067,6 @@
   }
   :where([data-pretable-filter-clear]) {
     align-self: flex-end;
-    background: transparent;
-    border: 0;
-    color: var(--pretable-accent);
-    cursor: pointer;
-    padding: 2px 4px;
   }
 
   /* ---- Drag-to-group panel (sub-project 3) ----------------------------- */
@@ -1195,20 +1170,12 @@
   }
 
   :where([data-pretable-chip-remove]) {
-    flex: none;
-    display: inline-flex;
-    align-items: center;
-    justify-content: center;
     width: 14px;
     height: 14px;
-    padding: 0;
-    border: 0;
-    border-radius: var(--pretable-radius-control);
-    background: transparent;
-    color: var(--pretable-text-dim);
+    /* The glyph is a Unicode ✕, not an icon from the set, so it is sized in
+       type rather than by --pretable-icon-size. */
     font-size: 10px;
     line-height: 1;
-    cursor: pointer;
   }
   :where([data-pretable-chip-remove]:hover) {
     background: var(--pretable-selection-bg);
@@ -1232,19 +1199,8 @@
      open case matters — without it the button vanishes the moment the pointer
      leaves the header, while its own menu is still up. */
   :where([data-pretable-column-menu-button]) {
-    display: inline-flex;
-    align-items: center;
-    justify-content: center;
     width: 18px;
     height: 18px;
-    padding: 0;
-    border: 0;
-    border-radius: var(--pretable-radius-control);
-    background: transparent;
-    color: var(--pretable-text-dim);
-    cursor: pointer;
-    opacity: 0;
-    transition: opacity 0.1s ease;
     /* Containing block for the coarse-pointer hit area at the end of the file.
        Declared here rather than beside it so the two cannot drift apart, and
        unconditional because it changes nothing on its own: the button is
@@ -1252,6 +1208,8 @@
        moves no pixel and reorders no paint — both slots were already in the
        positioned phase, ordered by tree order. */
     position: relative;
+    opacity: 0;
+    transition: opacity 0.1s ease;
   }
   :where([data-pretable-header-row]:hover [data-pretable-column-menu-button]),
   :where([data-pretable-column-menu-button]:focus-visible),
@@ -1844,18 +1802,8 @@
      header's opens — [data-pretable-column-menu] holding
      [data-pretable-menu-item]s — so the menu needs no rules of its own. */
   :where([data-pretable-tool-row-menu-button]) {
-    flex: none;
-    display: inline-flex;
-    align-items: center;
-    justify-content: center;
     inline-size: 18px;
     block-size: 18px;
-    padding: 0;
-    border: 0;
-    border-radius: var(--pretable-radius-control);
-    background: transparent;
-    color: var(--pretable-text-dim);
-    cursor: pointer;
     /* Containing block for the coarse-pointer hit area at the end of the
        file, like the grip's. */
     position: relative;
@@ -1880,12 +1828,6 @@
      at the foot of the pane would outweigh every row above it. */
   :where([data-pretable-tool-reset]) {
     align-self: flex-end;
-    padding: 2px 4px;
-    border: 0;
-    background: transparent;
-    color: var(--pretable-accent);
-    cursor: pointer;
-    font: inherit;
   }
 
   /* ---- Filter builder (SP2b) -------------------------------------------- */
@@ -2040,30 +1982,19 @@
      chip strip can argue its own case (a chip is a label with a glyph on the
      end); this row cannot, because it sits beside two 24px controls that
      already made the opposite choice. What IS taken from the chip is the
-     quiet-until-hover idea — dim by --pretable-text-dim, full text colour on
-     hover — and not its paint: the hover fill is this section's own
-     background-IMAGE gradient, the same one the row and the join use, rather
-     than the chip's --pretable-selection-bg.
-     `flex: none` and a square inline-size: it holds a glyph, so it must not
-     stretch the way the fields either side of it do. The glyph itself is a
-     CloseIcon from the set, sized by --pretable-icon-size through
-     [data-pretable-icon] — no font-size here, unlike the chip's Unicode. */
+     quiet-until-hover idea — full text colour on hover — and not its paint:
+     the hover fill is this section's own background-IMAGE gradient, the same
+     one the row and the join use, rather than the chip's
+     --pretable-selection-bg.
+     A square 24px box. NO `position: relative`: unlike the two ⋮ buttons this
+     one sits IN FLOW among later siblings, so making it a positioned box
+     would paint it above them. It buys no hit area with a ::after and needs
+     no containing block. */
   /* [data-pretable-tool-group-remove] (the group-by row's ✕) shares every
      rule: same glyph, same quiet treatment, one set of declarations. */
   :where([data-pretable-filter-row-remove], [data-pretable-tool-group-remove]) {
-    box-sizing: border-box;
-    flex: none;
-    display: inline-flex;
-    align-items: center;
-    justify-content: center;
     inline-size: 24px;
     block-size: 24px;
-    padding: 0;
-    border: 0;
-    border-radius: var(--pretable-radius-control);
-    background: transparent;
-    color: var(--pretable-text-dim);
-    cursor: pointer;
   }
   :where(
     [data-pretable-filter-row-remove]:hover,
@@ -2089,8 +2020,6 @@
     [data-pretable-filter-row-column]:focus-visible,
     [data-pretable-filter-row-operator]:focus-visible,
     input[data-pretable-filter-row-value]:focus-visible,
-    [data-pretable-filter-row-remove]:focus-visible,
-    [data-pretable-tool-group-remove]:focus-visible,
     [data-pretable-aggregate-row] select:focus-visible
   ) {
     outline: 2px solid var(--pretable-focus-ring);
@@ -2164,72 +2093,6 @@
     outline-offset: -2px;
   }
 
-  /* `+ filter` / `+ group`: the reset action's quiet-text-button voice,
-     because a bordered pair under the tree would outweigh the rows they add
-     to. 24px tall so the pair clears WCAG 2.5.8 on the same terms as the
-     join. */
-  /* [data-pretable-add-group] (the grouping section's `+ Add group`) rides
-     these four rules: same quiet-text-button voice, same disabled dimming
-     (there: tree depth; here: every column already grouped) — and so do the
-     expansion pair, [data-pretable-expand-all] / [data-pretable-collapse-all]
-     (disabled there: no groups to act on). One list per rule, extended in
-     place, so the sections cannot drift apart part by part. */
-  :where(
-    [data-pretable-filter-add],
-    [data-pretable-add-group],
-    [data-pretable-expand-all],
-    [data-pretable-collapse-all]
-  ) {
-    display: inline-flex;
-    align-items: center;
-    gap: 4px;
-    block-size: 24px;
-    padding-inline: 6px;
-    border: 0;
-    border-radius: var(--pretable-radius-control);
-    background: transparent;
-    color: var(--pretable-accent);
-    cursor: pointer;
-    /* The shorthand, unlike the join's longhands: this rule sets no size of
-       its own, so there is nothing for `font: inherit` to overwrite. */
-    font: inherit;
-  }
-  :where(
-    [data-pretable-filter-add]:hover:not(:disabled),
-    [data-pretable-add-group]:hover:not(:disabled),
-    [data-pretable-expand-all]:hover:not(:disabled),
-    [data-pretable-collapse-all]:hover:not(:disabled)
-  ) {
-    background-image: linear-gradient(
-      var(--pretable-bg-hover),
-      var(--pretable-bg-hover)
-    );
-  }
-  :where(
-    [data-pretable-filter-add]:focus-visible,
-    [data-pretable-add-group]:focus-visible,
-    [data-pretable-expand-all]:focus-visible,
-    [data-pretable-collapse-all]:focus-visible
-  ) {
-    outline: 2px solid var(--pretable-focus-ring);
-    outline-offset: -2px;
-  }
-
-  /* `+ group` refuses at the engine's 64-level bound — a deeper tree throws
-     `invalid-query` out of setQuery, which no consumer catches. Disabled
-     dims by token like the hidden row does, and drops the pointer
-     affordance; the REASON is the button's business (a title/aria-disabled
-     description), not the stylesheet's. */
-  :where(
-    [data-pretable-filter-add]:disabled,
-    [data-pretable-add-group]:disabled,
-    [data-pretable-expand-all]:disabled,
-    [data-pretable-collapse-all]:disabled
-  ) {
-    color: var(--pretable-text-dim);
-    cursor: default;
-  }
-
   /* What renders INSTEAD of the tree, so it sits with the actions that end
      it rather than opening the section. The group-label's voice: a dim line,
      not an empty box. A bordered placeholder would draw more attention than the
@@ -2296,6 +2159,30 @@
     outline-offset: 1px;
   }
 
+  /* ---- Kit components: state -------------------------------------------
+     The ring and the disabled ink come LAST in the layer, after every site
+     rule, because every selector here is :where()-flattened to (0,0,0) and
+     source order is the only cascade lever there is. A site's own state
+     colour — `[data-pretable-filter-funnel][data-pretable-filter-active="true"]
+     { color }`, a `:hover { color }` — would otherwise outrank the disabled
+     ink at equal specificity. The ghost group's old local `:disabled` rule
+     was protected only by being local and last; this is what replaces it. */
+  :where(
+    [data-pretable-button]:focus-visible,
+    [data-pretable-icon-button]:focus-visible
+  ) {
+    outline: 2px solid var(--pretable-focus-ring);
+    outline-offset: -2px;
+  }
+  /* The standard disabled treatment (#573): dim by token, drop the pointer. */
+  :where(
+    [data-pretable-button]:disabled,
+    [data-pretable-icon-button]:disabled
+  ) {
+    color: var(--pretable-text-dim);
+    cursor: default;
+  }
+
   /* ---- Coarse pointers -------------------------------------------------- */
 
   /* A finger, not a mouse. The header's overlay controls were built on three
diff --git a/packages/ui/src/__tests__/css-cascade.test.ts b/packages/ui/src/__tests__/css-cascade.test.ts
index 6984ae92..e6e8bbdd 100644
--- a/packages/ui/src/__tests__/css-cascade.test.ts
+++ b/packages/ui/src/__tests__/css-cascade.test.ts
@@ -725,10 +725,14 @@ describe("grid.css cascade contract", () => {
 
   test("small controls use the control radius, surfaces use the card radius", () => {
     const css = fs.readFileSync(GRID_CSS, "utf8");
-    const funnel = css.match(
-      /:where\(\[data-pretable-filter-funnel\]\)\s*\{([\s\S]*?)\}/,
+    // Read from the kit rule, not the funnel's: the radius moved onto the
+    // component the funnel now renders. The funnel is still the subject —
+    // it is a [data-pretable-icon-button] — but the declaration is shared.
+    const kit = css.match(
+      /:where\(\[data-pretable-button\], \[data-pretable-icon-button\]\)\s*\{([\s\S]*?)\}/,
     )?.[1];
-    expect(funnel).toMatch(/border-radius:\s*var\(--pretable-radius-control\)/);
+    expect(kit, "no kit push-button rule found").toBeDefined();
+    expect(kit).toMatch(/border-radius:\s*var\(--pretable-radius-control\)/);
     const viewport = css.match(
       /:where\(\[data-pretable-scroll-viewport\]\)\s*\{([\s\S]*?)\}/,
     )?.[1];
@@ -1628,7 +1632,13 @@ describe("grid.css cascade contract", () => {
       for (const attr of BUILDER_ATTRS.filter(
         (a) =>
           a !== "data-pretable-filter-column-hidden" &&
-          a !== "data-pretable-filter-column-grouped",
+          a !== "data-pretable-filter-column-grouped" &&
+          // `+ filter` is a kit <PretableButton variant="ghost">, and the
+          // ghost look is the component's: the site rule that used to carry
+          // it was deleted rather than collapsed, which the push-button site
+          // guard's OWN table pins (`filter-add: null`). Its box is proved
+          // there and in the kit-button guard, not here.
+          a !== "data-pretable-filter-add",
       )) {
         // Anywhere inside the `:where(...)` list, not only at its head: the
         // leaf row's three fields share ONE box and therefore one grouped
@@ -1661,19 +1671,19 @@ describe("grid.css cascade contract", () => {
         /:where\(\[data-pretable-filter-join\]:focus-visible\)\s*\{[^}]*outline:/,
       );
       // The depth-64 refusal is a DISABLED add button, and disabled dims by
-      // token like everything else here.
-      // List-tolerant: `+ Add group` and the grouping section's expansion
-      // pair ride the same rule (grid.css extends the list in place).
-      expect(css, "no disabled state for the add actions").toMatch(
-        /:where\(\s*\[data-pretable-filter-add\]:disabled[,\s)]/,
+      // token like everything else here. `+ filter` is a kit
+      // <PretableButton variant="ghost">, so the disabled treatment and the
+      // 24px box are the COMPONENT's — read from the kit rules, which every
+      // add action in this section and the grouping one alike matches.
+      expect(css, "no disabled state for the kit buttons").toMatch(
+        /:where\(\s*\[data-pretable-button\]:disabled[,\s)]/,
       );
       // The add actions carry the same explicit WCAG 2.5.8 claim the join
-      // does, so they get the same guard: 24px, in the base rule, on every
-      // pointer.
+      // does, so they get the same guard: 24px, on every pointer.
       const add = css.match(
-        /:where\(\s*\[data-pretable-filter-add\][^{]*\)\s*\{([\s\S]*?)\}/,
+        /:where\(\[data-pretable-button\]\[data-pretable-variant="ghost"\]\)\s*\{([\s\S]*?)\}/,
       )?.[1];
-      expect(add, "no add-action rule").toBeDefined();
+      expect(add, "no ghost-variant rule").toBeDefined();
       expect(add).toMatch(/block-size:\s*24px/);
 
       // The leaf row's remove button, on BOTH axes. It is the one control here
@@ -1695,7 +1705,10 @@ describe("grid.css cascade contract", () => {
       ).toMatch(/inline-size:\s*(2[4-9]|[3-9]\d|\d{3,})px/);
       // A border that lands outside a content-box host makes the 24 a 26 and
       // breaks the alignment the join's rule argues for one section down.
-      expect(remove).toMatch(/box-sizing:\s*border-box/);
+      // The kit rule owns the box-sizing now, for every push-button.
+      expect(css).toMatch(
+        /:where\(\[data-pretable-button\], \[data-pretable-icon-button\]\)\s*\{[^}]*box-sizing:\s*border-box/,
+      );
     });
 
     test("the leaf row's fields can shrink inside the pane", () => {
@@ -1881,7 +1894,10 @@ describe("grid.css cascade contract", () => {
       // ...which needs the button as its containing block.
       expect(funnelRule(css)).toMatch(/position:\s*relative/);
       // No padding on the button itself — that WOULD grow its border box.
-      expect(funnelRule(css)).toMatch(/padding:\s*0/);
+      // It is the kit icon rule that zeroes it now, for every icon button.
+      expect(css).toMatch(
+        /:where\(\[data-pretable-icon-button\]\)\s*\{[^}]*padding:\s*0/,
+      );
     });
 
     test("the hit area grows leftward only, clear of the 4px resize strip", () => {
@@ -2076,7 +2092,10 @@ describe("grid.css cascade contract", () => {
       expect(button, "no column-menu button rule").toBeDefined();
       expect(button).toMatch(/width:\s*18px/);
       expect(button).toMatch(/height:\s*18px/);
-      expect(button).toMatch(/padding:\s*0/);
+      // Zeroed by the kit icon rule now, for every icon button.
+      expect(css).toMatch(
+        /:where\(\[data-pretable-icon-button\]\)\s*\{[^}]*padding:\s*0/,
+      );
       // The ::after needs the button as its containing block.
       expect(button).toMatch(/position:\s*relative/);
 

From 32012e1361d9984907e17132b18ec698507ad9f7 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 11:08:46 -0700
Subject: [PATCH 21/31] feat(react): export the kit buttons and the components
 slot types

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 packages/react/react.api.md                  | 46 ++++++++++++++++++++
 packages/react/src/public_api.ts             | 14 ++++++
 type-tests/react/components-button.types.tsx | 17 ++++++--
 3 files changed, 73 insertions(+), 4 deletions(-)

diff --git a/packages/react/react.api.md b/packages/react/react.api.md
index a2e7ef90..14af2b37 100644
--- a/packages/react/react.api.md
+++ b/packages/react/react.api.md
@@ -4,12 +4,15 @@
 
 ```ts
 
+import { ButtonHTMLAttributes } from 'react';
 import { ComponentType } from 'react';
 import { CSSProperties } from 'react';
 import { DependencyList } from 'react';
+import { ForwardRefExoticComponent } from 'react';
 import { HTMLAttributes } from 'react';
 import { ReactElement } from 'react';
 import { ReactNode } from 'react';
+import { RefAttributes } from 'react';
 
 // @public
 export function buildExportFileName(input: BuildExportFileNameArgs): string;
@@ -378,6 +381,7 @@ export interface PretableBaseProps<TRow extends PretableRow = PretableRow, TRowI
     // (undocumented)
     ariaLabel: string;
     columns: TColumns;
+    components?: PretableSurfaceSharedProps<TRow, TRowId, TColumns>["components"];
     // (undocumented)
     copyToClipboard?: PretableSurfaceSharedProps<TRow, TRowId, TColumns>["copyToClipboard"];
     // (undocumented)
@@ -420,6 +424,27 @@ export type PretableBodyStateKind = "loading" | "empty" | "error" | "error-strip
 // @public (undocumented)
 export type PretableBuiltinAggregate<TValue, TType extends PretableColumnType> = "count" | (TType extends "number" ? NonNullable<TValue> extends number ? "sum" | "avg" | "min" | "max" : never : TType extends "date" ? NonNullable<TValue> extends string ? "min" | "max" : never : never);
 
+// @public
+export type PretableBuiltInButtonSite = "filter-add" | "add-group" | "expand-all" | "collapse-all" | "filter-clear" | "tool-reset" | "filter-funnel" | "column-menu-button" | "tool-row-menu-button" | "chip-remove" | "filter-row-remove" | "tool-group-remove";
+
+// @public
+export const PretableButton: ForwardRefExoticComponent<PretableButtonProps & RefAttributes<HTMLButtonElement>>;
+
+// @public
+export type PretableButtonComponent = ComponentType<PretableButtonProps & RefAttributes<HTMLButtonElement>>;
+
+// @public
+export interface PretableButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type"> {
+    site?: PretableButtonSite;
+    variant?: PretableButtonVariant;
+}
+
+// @public
+export type PretableButtonSite = PretableBuiltInButtonSite | (string & {});
+
+// @public
+export type PretableButtonVariant = "ghost" | "link";
+
 // @public
 export interface PretableCellAddress {
     // (undocumented)
@@ -817,6 +842,14 @@ export interface PretableCompatibleAggregator<TRow extends object, TValue, TOutp
     }["bivarianceHack"];
 }
 
+// @public
+export interface PretableComponents {
+    // (undocumented)
+    readonly Button?: PretableButtonComponent;
+    // (undocumented)
+    readonly IconButton?: PretableIconButtonComponent;
+}
+
 // @public
 export type PretableConventionalRowId<TRow> = TRow extends {
     readonly id: infer TRowId extends PretableRowId;
@@ -1313,6 +1346,18 @@ export interface PretableHeaderRowRef {
     readonly kind: "header";
 }
 
+// @public
+export const PretableIconButton: ForwardRefExoticComponent<PretableIconButtonProps & RefAttributes<HTMLButtonElement>>;
+
+// @public
+export type PretableIconButtonComponent = ComponentType<PretableIconButtonProps & RefAttributes<HTMLButtonElement>>;
+
+// @public
+export interface PretableIconButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type" | "aria-label"> {
+    "aria-label": string;
+    site?: PretableButtonSite;
+}
+
 // @public
 export interface PretableIndexedCellAddress<TRowId extends PretableRowId, TColumnId extends string> {
     // (undocumented)
@@ -2341,6 +2386,7 @@ export interface PretableSurfaceSharedProps<TRow extends PretableRow = PretableR
     ariaDescribedBy?: string;
     // (undocumented)
     ariaLabel: string;
+    components?: PretableComponents;
     copyToClipboard?: (payload: CopyPayload) => void | Promise<void>;
     copyWithHeaders?: boolean;
     csvOptions?: PretableCsvOptions<TRowId>;
diff --git a/packages/react/src/public_api.ts b/packages/react/src/public_api.ts
index 1c247569..52519e56 100644
--- a/packages/react/src/public_api.ts
+++ b/packages/react/src/public_api.ts
@@ -28,6 +28,20 @@ export type {
   PretableStatusTone,
 } from "./cells";
 
+export { PretableButton, PretableIconButton } from "./components/button";
+export type {
+  PretableBuiltInButtonSite,
+  PretableButtonProps,
+  PretableButtonSite,
+  PretableButtonVariant,
+  PretableIconButtonProps,
+} from "./components/button";
+export type {
+  PretableButtonComponent,
+  PretableComponents,
+  PretableIconButtonComponent,
+} from "./components/context";
+
 // Hooks
 export { usePretable } from "./use-pretable";
 export { useLocalRowModel } from "./use-local-row-model";
diff --git a/type-tests/react/components-button.types.tsx b/type-tests/react/components-button.types.tsx
index 8a56aa37..ab2750d8 100644
--- a/type-tests/react/components-button.types.tsx
+++ b/type-tests/react/components-button.types.tsx
@@ -1,14 +1,12 @@
-// TEMPORARY: imported from source because `@pretable/react` does not export
-// these yet. Task 11 of the SP1 plan switches this to the package, which is
-// the surface every other file here tests — the built d.ts, not the source.
 import {
   PretableButton,
   PretableIconButton,
   type PretableBuiltInButtonSite,
   type PretableButtonProps,
   type PretableButtonSite,
+  type PretableComponents,
   type PretableIconButtonProps,
-} from "../../packages/react/src/components/button";
+} from "@pretable/react";
 import type { Equal, Expect } from "../shared/assert";
 
 // An icon-only button has no accessible name but the one it is given, so
@@ -52,3 +50,14 @@ export type ButtonHasSite = Expect<
 export type IconHasName = Expect<
   Equal<PretableIconButtonProps["aria-label"], string>
 >;
+
+// A replacement is written against the same props the built-in receives, and
+// the built-ins themselves satisfy the slot types.
+const components: PretableComponents = {
+  Button: PretableButton,
+  IconButton: PretableIconButton,
+};
+export type ComponentsIsOptional = Expect<
+  Equal<PretableComponents["Button"], PretableComponents["Button"] | undefined>
+>;
+void components;

From f934a2dbea1a8dedd624ee7b93cf16eb9b994ef4 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 11:23:44 -0700
Subject: [PATCH 22/31] test(react): every migrated site is pinned to its kit
 component; review minors
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

All twelve sites are now asserted in jsdom to carry the kit attribute and
their site name — the bridge that makes the CSS guards load-bearing, since
a site quietly back on a raw <button> would have left them green. Also:
JSDoc on the two components slots (their report markers were
"undocumented"), a key-omissibility pin in the type test, the components
hook read at the top of every component body, and a stale "Task 8/9"
docblock in ColumnsSection removed.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 packages/react/react.api.md                   |  2 -
 .../__tests__/components-override.test.tsx    | 76 +++++++++++++++++++
 packages/react/src/components/context.ts      |  2 +
 packages/react/src/filter-menu/FilterMenu.tsx |  3 +-
 .../react/src/tool-panel/ColumnsSection.tsx   |  2 +-
 .../src/tool-panel/filters/FiltersSection.tsx |  3 +-
 .../tool-panel/grouping/GroupingSection.tsx   |  3 +-
 type-tests/react/components-button.types.tsx  |  4 +
 8 files changed, 86 insertions(+), 9 deletions(-)

diff --git a/packages/react/react.api.md b/packages/react/react.api.md
index 14af2b37..0924c00b 100644
--- a/packages/react/react.api.md
+++ b/packages/react/react.api.md
@@ -844,9 +844,7 @@ export interface PretableCompatibleAggregator<TRow extends object, TValue, TOutp
 
 // @public
 export interface PretableComponents {
-    // (undocumented)
     readonly Button?: PretableButtonComponent;
-    // (undocumented)
     readonly IconButton?: PretableIconButtonComponent;
 }
 
diff --git a/packages/react/src/__tests__/components-override.test.tsx b/packages/react/src/__tests__/components-override.test.tsx
index 4a661565..2a09dc64 100644
--- a/packages/react/src/__tests__/components-override.test.tsx
+++ b/packages/react/src/__tests__/components-override.test.tsx
@@ -154,6 +154,82 @@ describe("components on the surface", () => {
       document.querySelector("[data-pretable-column-menu]"),
     ).not.toBeNull();
   });
+
+  it("every migrated site renders the kit component, carrying its site name", () => {
+    // The CSS guards in @pretable/ui assume each site's element carries the
+    // kit attribute — a site that quietly went back to a raw <button> would
+    // leave those guards green while losing its whole box. This is the
+    // bridge that makes them load-bearing. Rows are grouped so the grouping
+    // section, its chips and its removes all render.
+    const view = render(
+      <PretableSurface<Row>
+        ariaLabel="sites-grid"
+        columns={columns}
+        getRowId={(row) => row.id}
+        rows={rows}
+        groupPanel={{ enabled: true }}
+        toolPanel={{ defaultActiveSection: "grouping" }}
+        viewportHeight={240}
+        query={{ filters: [], sort: [], rowGroups: [{ columnId: "name" }] }}
+        onQueryChange={() => {}}
+      />,
+    );
+    const expectKit = (
+      attr: string,
+      kind: "button" | "icon-button",
+      site: string,
+    ) => {
+      const el =
+        view.container.querySelector(`[data-pretable-${attr}]`) ??
+        document.querySelector(`[data-pretable-${attr}]`);
+      expect(el, `no element carries data-pretable-${attr}`).not.toBeNull();
+      expect(el).toHaveAttribute(`data-pretable-${kind}`, "");
+      expect(el).toHaveAttribute("data-pretable-site", site);
+    };
+    // Grouping section (open): add-group, expand-all, collapse-all, tool-group-remove.
+    expectKit("add-group", "button", "add-group");
+    expectKit("expand-all", "button", "expand-all");
+    expectKit("collapse-all", "button", "collapse-all");
+    expectKit("tool-group-remove", "icon-button", "tool-group-remove");
+    // Header: funnel and column menu.
+    expectKit("filter-funnel", "icon-button", "filter-funnel");
+    expectKit("column-menu-button", "icon-button", "column-menu-button");
+    // Group panel chip remove (a grouped column renders a chip).
+    expectKit("chip-remove", "icon-button", "chip-remove");
+  });
+
+  it("the columns and filters sections' sites render the kit component too", () => {
+    const view = renderSurface(); // columns section open
+    const kit = (
+      attr: string,
+      kind: "button" | "icon-button",
+      site: string,
+    ) => {
+      const el = view.container.querySelector(`[data-pretable-${attr}]`);
+      expect(el, `no element carries data-pretable-${attr}`).not.toBeNull();
+      expect(el).toHaveAttribute(`data-pretable-${kind}`, "");
+      expect(el).toHaveAttribute("data-pretable-site", site);
+    };
+    kit("tool-reset", "button", "tool-reset");
+    kit("tool-row-menu-button", "icon-button", "tool-row-menu-button");
+    // Filters section: + filter, then the row it adds carries its remove.
+    fireEvent.click(view.getByRole("tab", { name: /filter/i }));
+    kit("filter-add", "button", "filter-add");
+    fireEvent.click(
+      view.container.querySelector("[data-pretable-filter-add]")!,
+    );
+    kit("filter-row-remove", "icon-button", "filter-row-remove");
+    // The dialog's Clear is portalled: open a funnel.
+    const funnel = view.container.querySelector(
+      "[data-pretable-filter-funnel]",
+    )!;
+    fireEvent.pointerDown(funnel);
+    fireEvent.click(funnel);
+    const clear = document.querySelector("[data-pretable-filter-clear]");
+    expect(clear).not.toBeNull();
+    expect(clear).toHaveAttribute("data-pretable-button", "");
+    expect(clear).toHaveAttribute("data-pretable-site", "filter-clear");
+  });
 });
 
 describe("components on the <Pretable> preset", () => {
diff --git a/packages/react/src/components/context.ts b/packages/react/src/components/context.ts
index 5d490cac..909c53d1 100644
--- a/packages/react/src/components/context.ts
+++ b/packages/react/src/components/context.ts
@@ -64,7 +64,9 @@ export type PretableIconButtonComponent = ComponentType<
  * @public
  */
 export interface PretableComponents {
+  /** Every labelled push-button the grid draws; receives {@link PretableButtonProps}. */
   readonly Button?: PretableButtonComponent;
+  /** Every icon-only push-button the grid draws; receives {@link PretableIconButtonProps}. */
   readonly IconButton?: PretableIconButtonComponent;
 }
 
diff --git a/packages/react/src/filter-menu/FilterMenu.tsx b/packages/react/src/filter-menu/FilterMenu.tsx
index c8cf2547..1f55d7e1 100644
--- a/packages/react/src/filter-menu/FilterMenu.tsx
+++ b/packages/react/src/filter-menu/FilterMenu.tsx
@@ -74,6 +74,7 @@ export function FilterMenu({
   onChange: (columnId: string, filter: ColumnFilter | null) => void;
   onClose: () => void;
 }): JSX.Element {
+  const { Button } = usePretableComponents();
   const [draft, setDraft] = useState<FilterDraft>(() =>
     fromColumnFilter(type, initialFilter, allowedOperators),
   );
@@ -292,8 +293,6 @@ export function FilterMenu({
     [draft, pushNow],
   );
 
-  const { Button } = usePretableComponents();
-
   return (
     <OverlayPortal>
       <div
diff --git a/packages/react/src/tool-panel/ColumnsSection.tsx b/packages/react/src/tool-panel/ColumnsSection.tsx
index ef496194..6deb72bc 100644
--- a/packages/react/src/tool-panel/ColumnsSection.tsx
+++ b/packages/react/src/tool-panel/ColumnsSection.tsx
@@ -109,7 +109,7 @@ const PIN_GROUPS = [
  * entries included, because this pane is the one place a hidden column stays
  * visible — subgrouped by pin state, with visibility toggles, label search
  * and a reset to the mount-time layout. The grip and kebab complete the row
- * anatomy but are inert here: drag-reorder is Task 9's, the menu Task 8's.
+ * anatomy.
  */
 export function ColumnsSection({
   grid,
diff --git a/packages/react/src/tool-panel/filters/FiltersSection.tsx b/packages/react/src/tool-panel/filters/FiltersSection.tsx
index 859db407..a25ecfef 100644
--- a/packages/react/src/tool-panel/filters/FiltersSection.tsx
+++ b/packages/react/src/tool-panel/filters/FiltersSection.tsx
@@ -343,6 +343,7 @@ export function FiltersSection({
   processing,
   messages,
 }: FiltersSectionProps) {
+  const { Button } = usePretableComponents();
   // The section's OWN subscription, and the SNAPSHOT slice rather than the
   // state: `filters` changes identity only when a query commits, so every
   // other publish bails in useSyncExternalStore's equality check instead of
@@ -647,8 +648,6 @@ export function FiltersSection({
     };
   }, [loadDistinctValues, wantedKey]);
 
-  const { Button } = usePretableComponents();
-
   const addActions = (groupPath: FilterPath, count: number) => {
     // The depth the NEW node would land at, read from the group being added
     // INTO: `depthOf([])` is -1, so a root add lands at 0. The slot path handed
diff --git a/packages/react/src/tool-panel/grouping/GroupingSection.tsx b/packages/react/src/tool-panel/grouping/GroupingSection.tsx
index 3054641c..916cfca5 100644
--- a/packages/react/src/tool-panel/grouping/GroupingSection.tsx
+++ b/packages/react/src/tool-panel/grouping/GroupingSection.tsx
@@ -148,6 +148,7 @@ export function GroupingSection({
   aggregatesEnabled,
   messages,
 }: GroupingSectionProps) {
+  const { Button, IconButton } = usePretableComponents();
   // The section's OWN subscription, and the SNAPSHOT slice rather than the
   // state (FiltersSection's pattern): `rowGroups` changes identity only when
   // a query commits, so every other publish bails in useSyncExternalStore's
@@ -354,8 +355,6 @@ export function GroupingSection({
   // (`groupedIds.length` = after the last row).
   const indicatorAt = drag !== null ? drag.target.beforeRow : null;
 
-  const { Button, IconButton } = usePretableComponents();
-
   return (
     // tabIndex -1: never in the tab order, but a programmatic focus landing
     // for the add-menu close when the button itself has become disabled.
diff --git a/type-tests/react/components-button.types.tsx b/type-tests/react/components-button.types.tsx
index ab2750d8..da08c0e3 100644
--- a/type-tests/react/components-button.types.tsx
+++ b/type-tests/react/components-button.types.tsx
@@ -61,3 +61,7 @@ export type ComponentsIsOptional = Expect<
   Equal<PretableComponents["Button"], PretableComponents["Button"] | undefined>
 >;
 void components;
+
+// Every slot may be OMITTED, not merely set to undefined.
+const empty: PretableComponents = {};
+void empty;

From 13a5e899abebd3b017bc9d134d5beb32e01a17b6 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 11:27:37 -0700
Subject: [PATCH 23/31] fix(ui): chip-remove's dead type declarations go; site
 hovers guard :disabled
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The ✕ is a CloseIcon sized by --pretable-icon-size, so font-size and
line-height sized nothing and the comment that justified them was untrue.
Every icon site's hover now carries :not(:disabled), and the site guard
keeps it — latent today, since no icon site is disabled, but the rule is
#573's. The bracket guard's comment no longer describes a red state that
has since gone green.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../src/tool-panel/filters/FilterRow.tsx      |  2 +-
 .../tool-panel/grouping/GroupingSection.tsx   |  2 +-
 packages/ui/grid.css                          | 24 ++++++++++---------
 packages/ui/src/__tests__/css-cascade.test.ts | 22 +++++++++++++----
 4 files changed, 33 insertions(+), 17 deletions(-)

diff --git a/packages/react/src/tool-panel/filters/FilterRow.tsx b/packages/react/src/tool-panel/filters/FilterRow.tsx
index a61884ad..3fa455a8 100644
--- a/packages/react/src/tool-panel/filters/FilterRow.tsx
+++ b/packages/react/src/tool-panel/filters/FilterRow.tsx
@@ -6,6 +6,7 @@ import type {
 } from "@pretable/core";
 import { createElement, Fragment, type ReactNode } from "react";
 
+import { usePretableComponents } from "../../components/context";
 import { optionLabel } from "../../editors/enum-options";
 import {
   defaultDraft,
@@ -16,7 +17,6 @@ import {
   OPERATOR_LABELS,
   type FilterDraft,
 } from "../../filter-menu/filter-operators";
-import { usePretableComponents } from "../../components/context";
 import { CloseIcon } from "../../icons";
 import type { FilterRowMessages } from "../messages";
 
diff --git a/packages/react/src/tool-panel/grouping/GroupingSection.tsx b/packages/react/src/tool-panel/grouping/GroupingSection.tsx
index 916cfca5..3a3bc0e1 100644
--- a/packages/react/src/tool-panel/grouping/GroupingSection.tsx
+++ b/packages/react/src/tool-panel/grouping/GroupingSection.tsx
@@ -9,6 +9,7 @@ import {
 
 import type { ColumnType } from "@pretable/core";
 
+import { usePretableComponents } from "../../components/context";
 import { CloseIcon, GripIcon } from "../../icons";
 import { menuPopoverStyle } from "../../overlay/popover-position";
 import { useHeaderPopover } from "../../overlay/useHeaderPopover";
@@ -16,7 +17,6 @@ import type { GroupingSectionMessages } from "../messages";
 import type { ToolDropTarget, ToolRowRect } from "../tool-panel-drop-target";
 import { useToolRowDrag } from "../useToolRowDrag";
 import { AddGroupMenu } from "./AddGroupMenu";
-import { usePretableComponents } from "../../components/context";
 // Direct import, not the barrel: the barrel deliberately withholds
 // aggregate-options (it is the section's internal vocabulary, not API).
 import {
diff --git a/packages/ui/grid.css b/packages/ui/grid.css
index c37e1ee4..61732949 100644
--- a/packages/ui/grid.css
+++ b/packages/ui/grid.css
@@ -1008,7 +1008,7 @@
   :where([data-pretable-filter-funnel][data-pretable-filter-active="true"]) {
     color: var(--pretable-accent);
   }
-  :where([data-pretable-filter-funnel]:hover) {
+  :where([data-pretable-filter-funnel]:hover:not(:disabled)) {
     background: var(--pretable-bg-hover);
   }
 
@@ -1170,14 +1170,13 @@
   }
 
   :where([data-pretable-chip-remove]) {
+    /* 14px, one step under the 18px header buttons — the chip is a small
+       object and its ✕ is a CloseIcon sized by --pretable-icon-size, so
+       nothing here is type. */
     width: 14px;
     height: 14px;
-    /* The glyph is a Unicode ✕, not an icon from the set, so it is sized in
-       type rather than by --pretable-icon-size. */
-    font-size: 10px;
-    line-height: 1;
   }
-  :where([data-pretable-chip-remove]:hover) {
+  :where([data-pretable-chip-remove]:hover:not(:disabled)) {
     background: var(--pretable-selection-bg);
     color: var(--pretable-text-cell);
   }
@@ -1216,7 +1215,7 @@
   :where([data-pretable-column-menu-button][aria-expanded="true"]) {
     opacity: 1;
   }
-  :where([data-pretable-column-menu-button]:hover) {
+  :where([data-pretable-column-menu-button]:hover:not(:disabled)) {
     background: var(--pretable-selection-bg);
   }
 
@@ -1808,7 +1807,7 @@
        file, like the grip's. */
     position: relative;
   }
-  :where([data-pretable-tool-row-menu-button]:hover),
+  :where([data-pretable-tool-row-menu-button]:hover:not(:disabled)),
   :where([data-pretable-tool-row-menu-button][aria-expanded="true"]) {
     background: var(--pretable-selection-bg);
     color: var(--pretable-text-cell);
@@ -1997,8 +1996,8 @@
     block-size: 24px;
   }
   :where(
-    [data-pretable-filter-row-remove]:hover,
-    [data-pretable-tool-group-remove]:hover
+    [data-pretable-filter-row-remove]:hover:not(:disabled),
+    [data-pretable-tool-group-remove]:hover:not(:disabled)
   ) {
     background-image: linear-gradient(
       var(--pretable-bg-hover),
@@ -2166,7 +2165,10 @@
      colour — `[data-pretable-filter-funnel][data-pretable-filter-active="true"]
      { color }`, a `:hover { color }` — would otherwise outrank the disabled
      ink at equal specificity. The ghost group's old local `:disabled` rule
-     was protected only by being local and last; this is what replaces it. */
+     was protected only by being local and last; this is what replaces it.
+     The two @media blocks that follow this section are the file's last word
+     by construction, but they set only opacity and hit areas, never colour,
+     so they cannot be the site rule this ordering guards against. */
   :where(
     [data-pretable-button]:focus-visible,
     [data-pretable-icon-button]:focus-visible
diff --git a/packages/ui/src/__tests__/css-cascade.test.ts b/packages/ui/src/__tests__/css-cascade.test.ts
index e6e8bbdd..26952532 100644
--- a/packages/ui/src/__tests__/css-cascade.test.ts
+++ b/packages/ui/src/__tests__/css-cascade.test.ts
@@ -531,6 +531,19 @@ describe("grid.css cascade contract", () => {
           ).not.toMatch(decl);
         }
       }
+
+      // No icon site is disabled today, so this is latent — but the rule is
+      // the kit's (#573): a disabled button answers nothing to :hover, and a
+      // site rule that skips :not(:disabled) would paint a hover background
+      // on a disabled control the day one of these sites gains that state.
+      for (const [, selector] of rulesSelecting(css, (selector) =>
+        selector.includes(`${attr}:hover`),
+      )) {
+        expect(
+          selector,
+          `"${selector.trim()}" hovers ${site} without :not(:disabled)`,
+        ).toMatch(":not(:disabled)");
+      }
     }
   });
 
@@ -541,10 +554,11 @@ describe("grid.css cascade contract", () => {
     // and the kit's :focus-visible and :disabled have to come AFTER them so
     // no site rule can overwrite the ring or the disabled ink from below.
     //
-    // The state half is RED at HEAD by design: the two state rules still sit
-    // with the kit near the top of the layer, and the task that collapses the
-    // site rules moves them to the end of the layer. The first half already
-    // passes.
+    // Both halves pass: the shared box sits ahead of every site rule, and the
+    // ring and the disabled ink sit behind all of them. Site rules inside the
+    // trailing @media blocks are excluded from "last" — those blocks set only
+    // opacity and hit-areas, never colour, so they cannot be the rule this
+    // ordering protects against.
     const css = strippedCss();
     const kitBase = css.indexOf(
       ":where([data-pretable-button], [data-pretable-icon-button])",

From 16c6bedc3968d4ef2e44146c3e08d18099f2b608 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 11:37:32 -0700
Subject: [PATCH 24/31] docs: the Components page, its live example, and the
 registered tables

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 apps/website/app/docs/_nav.ts                 |  1 +
 apps/website/content/docs/grid/components.mdx | 75 +++++++++++++++++++
 .../content/docs/grid/pretable-component.mdx  |  2 +-
 .../content/docs/grid/pretable-surface.mdx    | 27 +++----
 .../components-button/BrandButton.tsx         | 28 +++++++
 .../components-button/ComponentsGrid.tsx      | 36 +++++++++
 .../components-button/brand-button.css        | 30 ++++++++
 .../examples/components-button/columns.ts     | 10 +++
 .../examples/components-button/data.ts        | 15 ++++
 .../examples/components-button/demo.tsx       |  5 ++
 .../examples/components-button/example.ts     | 14 ++++
 .../docs/__tests__/docs-api-surface.test.ts   | 48 +++++++++++-
 .../lib/docs/examples/demos.generated.ts      |  2 +
 .../lib/docs/examples/registry.generated.ts   |  5 ++
 .../seo/__tests__/content-metadata.test.ts    |  4 +-
 apps/website/lib/seo/__tests__/routes.test.ts |  2 +-
 .../__tests__/generate-sitemap.test.ts        |  4 +-
 17 files changed, 287 insertions(+), 21 deletions(-)
 create mode 100644 apps/website/content/docs/grid/components.mdx
 create mode 100644 apps/website/content/examples/components-button/BrandButton.tsx
 create mode 100644 apps/website/content/examples/components-button/ComponentsGrid.tsx
 create mode 100644 apps/website/content/examples/components-button/brand-button.css
 create mode 100644 apps/website/content/examples/components-button/columns.ts
 create mode 100644 apps/website/content/examples/components-button/data.ts
 create mode 100644 apps/website/content/examples/components-button/demo.tsx
 create mode 100644 apps/website/content/examples/components-button/example.ts

diff --git a/apps/website/app/docs/_nav.ts b/apps/website/app/docs/_nav.ts
index 0c691f06..305674a3 100644
--- a/apps/website/app/docs/_nav.ts
+++ b/apps/website/app/docs/_nav.ts
@@ -51,6 +51,7 @@ export const docsNav: DocsNavSection[] = [
         title: "Cell presentations",
         href: "/docs/grid/cell-presentations",
       },
+      { title: "Components", href: "/docs/grid/components" },
       {
         title: "Custom rendering",
         href: "/docs/grid/custom-rendering",
diff --git a/apps/website/content/docs/grid/components.mdx b/apps/website/content/docs/grid/components.mdx
new file mode 100644
index 00000000..2891a605
--- /dev/null
+++ b/apps/website/content/docs/grid/components.mdx
@@ -0,0 +1,75 @@
+---
+title: Components
+description: "The kit components the grid renders its own chrome from — Button and IconButton — how to style them, and how to replace either with your own."
+nav: Grid
+---
+
+`@pretable/react` renders its own controls from a small component kit, and
+ships those components for you to use and to replace. This page covers the
+first two: `PretableButton` and `PretableIconButton`. Here is a grid whose
+every button is the app's own:
+
+<Example id="components-button" />
+
+## The components
+
+Both render `<button type="button">`, always — every grid button is one, and a
+stray submit inside your `<form>` is a real bug class, so `type` is not a prop.
+`className` and `style` pass through and merge with the component's own
+attributes. Both forward their `ref` to the button node.
+
+### Button
+
+A labelled push-button in one of the grid's two looks.
+
+| Prop      | Type                 | Notes                                                                                       |
+| --------- | -------------------- | ------------------------------------------------------------------------------------------- |
+| `variant` | `"ghost" \| "link"`  | `ghost` is the 24px action with a hover tint; `link` is plain accent text. Default `ghost`. |
+| `site`    | `PretableButtonSite` | Where in the grid the button is; lands as `data-pretable-site`. Open to your own names.     |
+
+### IconButton
+
+An icon-only push-button. `aria-label` is **required** — it is the button's
+only accessible name, and omitting it is a compile error rather than an
+accessibility failure discovered later. An empty one warns in development.
+
+| Prop         | Type                 | Notes                                                           |
+| ------------ | -------------------- | --------------------------------------------------------------- |
+| `aria-label` | `string`             | Required. The accessible name.                                  |
+| `site`       | `PretableButtonSite` | Where in the grid the button is; lands as `data-pretable-site`. |
+
+## Styling
+
+The styling channel is the one the whole grid uses: attributes and tokens.
+Every button carries `data-pretable-button` or `data-pretable-icon-button`, its
+`data-pretable-variant`, and its `data-pretable-site`; the grid's own sites also
+keep their original attribute (`data-pretable-filter-clear`,
+`data-pretable-tool-reset`, …), so a selector you already wrote keeps matching.
+
+```css
+[data-pretable-button][data-pretable-variant="ghost"] {
+  --pretable-accent: rebeccapurple;
+}
+[data-pretable-site="tool-reset"] {
+  color: var(--pretable-text-error);
+}
+```
+
+## Replacing a component
+
+Pass `components` to `<PretableSurface>` (or `<Pretable>`) with one entry per
+component type you want to replace. The replacement is used everywhere that
+type appears — the tool panel, the header, and the portalled filter dialog —
+and receives exactly the props the built-in does, `site` included, so it can
+branch on where it is.
+
+| Prop         | Type                          | Notes                                                                          |
+| ------------ | ----------------------------- | ------------------------------------------------------------------------------ |
+| `Button`     | `PretableButtonComponent`     | Receives `PretableButtonProps`; must forward its `ref` to the button node.     |
+| `IconButton` | `PretableIconButtonComponent` | Receives `PretableIconButtonProps`; must forward its `ref` to the button node. |
+
+Forwarding the `ref` is the one obligation on a replacement: the grid anchors
+menus on the node and returns keyboard focus to it. Under React 18 that means
+`forwardRef`; under React 19 a plain `ref` prop is enough. The set of built-in
+`site` names is the `PretableBuiltInButtonSite` type and grows additively — a
+new grid button may introduce a new site without a major bump.
diff --git a/apps/website/content/docs/grid/pretable-component.mdx b/apps/website/content/docs/grid/pretable-component.mdx
index 4ea73ed5..b35484ec 100644
--- a/apps/website/content/docs/grid/pretable-component.mdx
+++ b/apps/website/content/docs/grid/pretable-component.mdx
@@ -42,7 +42,7 @@ Row identity is never derived from array position. `Person` above has a conventi
 
 ## Props
 
-`columns`, `rows`, and `ariaLabel` are required, and so is `getRowId` unless the row has a conventional string or number `id` — `ariaLabel` is the grid's accessible name, so give it something a screen reader user would recognize as this table's contents (e.g. `"People directory"`, not a generic placeholder). The concise preset also forwards row activation and selection callbacks, row changes, clipboard hooks, tab behavior, messages, the optional selection column, and column width/order/pinning callbacks. Use [`<PretableSurface>`](/docs/grid/pretable-surface) for controlled query and interaction state, grouping controls, custom renderers, explicit row-model ownership, telemetry, or a custom viewport height.
+`columns`, `rows`, and `ariaLabel` are required, and so is `getRowId` unless the row has a conventional string or number `id` — `ariaLabel` is the grid's accessible name, so give it something a screen reader user would recognize as this table's contents (e.g. `"People directory"`, not a generic placeholder). The concise preset also forwards row activation and selection callbacks, row changes, clipboard hooks, tab behavior, messages, the components slot, the optional selection column, and column width/order/pinning callbacks. Use [`<PretableSurface>`](/docs/grid/pretable-surface) for controlled query and interaction state, grouping controls, custom renderers, explicit row-model ownership, telemetry, or a custom viewport height.
 
 ## Server-side data
 
diff --git a/apps/website/content/docs/grid/pretable-surface.mdx b/apps/website/content/docs/grid/pretable-surface.mdx
index 32d45d13..dce459c1 100644
--- a/apps/website/content/docs/grid/pretable-surface.mdx
+++ b/apps/website/content/docs/grid/pretable-surface.mdx
@@ -67,19 +67,20 @@ The modes are mutually exclusive: do not pass `rows` or `getRowId` with `model`.
 
 ## Configuration
 
-| Area               | Props                                                                              |
-| ------------------ | ---------------------------------------------------------------------------------- |
-| Geometry           | `viewportHeight`, `viewportStyle`, `overscan`                                      |
-| Rendering          | `renderBodyCell`, `renderHeaderCell`, row/cell/header class and prop callbacks     |
-| Value presentation | `locale`; column `dateFormat`, `numberFormat`, `format`, and `formatAggregate`     |
-| Controlled UI      | `state`, `onSelectionChange`, `onFocusChange`                                      |
-| Row selection      | `rowSelectionColumn`, `state.rowSelection`, `onRowSelectionChange` — its own slice |
-| Rows-mode query    | the exact `query`, `onQueryChange` pair                                            |
-| Editing            | rows mode: `onRowChange`; model mode: `beforeRowChange`; shared: `onPaste`         |
-| Clipboard          | `onCopy`, `copyToClipboard`, `copyWithHeaders`, `messages`                         |
-| Grouping           | `groupPanel`, `groupColumn`, `hideGroupedColumns`, `initialExpansion`              |
-| Tool panel         | `toolPanel` — on by default; see [Tool panel](/docs/grid/tool-panel)               |
-| Observation        | `onGridReady`, `onTelemetryChange`, `onRejectedWriteChange`                        |
+| Area               | Props                                                                                      |
+| ------------------ | ------------------------------------------------------------------------------------------ |
+| Geometry           | `viewportHeight`, `viewportStyle`, `overscan`                                              |
+| Rendering          | `renderBodyCell`, `renderHeaderCell`, row/cell/header class and prop callbacks             |
+| Components         | `components` — replace a kit component everywhere; see [Components](/docs/grid/components) |
+| Value presentation | `locale`; column `dateFormat`, `numberFormat`, `format`, and `formatAggregate`             |
+| Controlled UI      | `state`, `onSelectionChange`, `onFocusChange`                                              |
+| Row selection      | `rowSelectionColumn`, `state.rowSelection`, `onRowSelectionChange` — its own slice         |
+| Rows-mode query    | the exact `query`, `onQueryChange` pair                                                    |
+| Editing            | rows mode: `onRowChange`; model mode: `beforeRowChange`; shared: `onPaste`                 |
+| Clipboard          | `onCopy`, `copyToClipboard`, `copyWithHeaders`, `messages`                                 |
+| Grouping           | `groupPanel`, `groupColumn`, `hideGroupedColumns`, `initialExpansion`                      |
+| Tool panel         | `toolPanel` — on by default; see [Tool panel](/docs/grid/tool-panel)                       |
+| Observation        | `onGridReady`, `onTelemetryChange`, `onRejectedWriteChange`                                |
 
 Rows-mode edit callbacks are proposals: update your `rows` value and let the next prop reconcile. Explicit-model edits validate the batch and publish one row-model transaction.
 
diff --git a/apps/website/content/examples/components-button/BrandButton.tsx b/apps/website/content/examples/components-button/BrandButton.tsx
new file mode 100644
index 00000000..3d8cec1b
--- /dev/null
+++ b/apps/website/content/examples/components-button/BrandButton.tsx
@@ -0,0 +1,28 @@
+"use client";
+
+import { forwardRef } from "react";
+import type { PretableButtonProps } from "@pretable/react";
+
+/**
+ * The app's own button, standing in for every Button the grid renders. It
+ * receives exactly what pretable's does — `site` included — and forwards its
+ * ref, which is the one thing the grid asks of a replacement: menus anchor on
+ * the node, and focus returns to it.
+ */
+export const BrandButton = forwardRef<HTMLButtonElement, PretableButtonProps>(
+  function BrandButton({ site, variant, className, ...props }, ref) {
+    // One place treated differently: the reset is destructive, so it gets the
+    // app's danger styling. Everything else is the brand default.
+    const tone = site === "tool-reset" ? "danger" : (variant ?? "ghost");
+    return (
+      <button
+        {...props}
+        ref={ref}
+        type="button"
+        className={["brand-button", `brand-button--${tone}`, className]
+          .filter(Boolean)
+          .join(" ")}
+      />
+    );
+  },
+);
diff --git a/apps/website/content/examples/components-button/ComponentsGrid.tsx b/apps/website/content/examples/components-button/ComponentsGrid.tsx
new file mode 100644
index 00000000..4121dc5e
--- /dev/null
+++ b/apps/website/content/examples/components-button/ComponentsGrid.tsx
@@ -0,0 +1,36 @@
+"use client";
+
+import { PretableSurface } from "@pretable/react";
+
+import "./brand-button.css";
+
+import { BrandButton } from "./BrandButton";
+import { columns } from "./columns";
+import { trades, type Trade } from "./data";
+
+const VIEWPORT_HEIGHT = 260;
+
+export function ComponentsGrid() {
+  return (
+    <div>
+      <p style={{ margin: "0 0 8px", fontSize: 13 }}>
+        Every button below is <code>BrandButton</code>, not pretable&apos;s —
+        one <code>components</code> slot, applied in the tool panel, the header
+        menus, and the portalled filter dialog alike. Open{" "}
+        <strong>Filters</strong> for <code>+ filter</code> and{" "}
+        <code>Clear</code>; open <strong>Columns</strong> for{" "}
+        <strong>Reset columns</strong>, the one site <code>BrandButton</code>{" "}
+        treats differently.
+      </p>
+      <PretableSurface<Trade>
+        ariaLabel="Trades"
+        columns={columns}
+        components={{ Button: BrandButton }}
+        getRowId={(row) => row.id}
+        rows={trades}
+        toolPanel={{ defaultActiveSection: "columns" }}
+        viewportHeight={VIEWPORT_HEIGHT}
+      />
+    </div>
+  );
+}
diff --git a/apps/website/content/examples/components-button/brand-button.css b/apps/website/content/examples/components-button/brand-button.css
new file mode 100644
index 00000000..bbea1782
--- /dev/null
+++ b/apps/website/content/examples/components-button/brand-button.css
@@ -0,0 +1,30 @@
+.brand-button {
+  border: 0;
+  border-radius: 999px;
+  padding: 0 12px;
+  height: 26px;
+  font: inherit;
+  font-weight: 600;
+  cursor: pointer;
+}
+
+.brand-button--ghost {
+  background: #eef2ff;
+  color: #3730a3;
+}
+
+.brand-button--link {
+  background: transparent;
+  color: #3730a3;
+  padding: 0 4px;
+}
+
+.brand-button--danger {
+  background: #fee2e2;
+  color: #991b1b;
+}
+
+.brand-button:disabled {
+  opacity: 0.5;
+  cursor: default;
+}
diff --git a/apps/website/content/examples/components-button/columns.ts b/apps/website/content/examples/components-button/columns.ts
new file mode 100644
index 00000000..7345bb0c
--- /dev/null
+++ b/apps/website/content/examples/components-button/columns.ts
@@ -0,0 +1,10 @@
+import type { PretableColumn } from "@pretable/react";
+
+import type { Trade } from "./data";
+
+export const columns: PretableColumn<Trade>[] = [
+  { id: "symbol", header: "Symbol", widthPx: 110, type: "text" },
+  { id: "side", header: "Side", widthPx: 90, type: "enum" },
+  { id: "qty", header: "Qty", widthPx: 90, type: "number" },
+  { id: "price", header: "Price", widthPx: 110, type: "number" },
+];
diff --git a/apps/website/content/examples/components-button/data.ts b/apps/website/content/examples/components-button/data.ts
new file mode 100644
index 00000000..5a06de00
--- /dev/null
+++ b/apps/website/content/examples/components-button/data.ts
@@ -0,0 +1,15 @@
+export interface Trade {
+  id: string;
+  symbol: string;
+  side: "Buy" | "Sell";
+  qty: number;
+  price: number;
+}
+
+export const trades: Trade[] = [
+  { id: "t1", symbol: "AAPL", side: "Buy", qty: 100, price: 226.11 },
+  { id: "t2", symbol: "MSFT", side: "Sell", qty: 40, price: 418.38 },
+  { id: "t3", symbol: "NVDA", side: "Buy", qty: 25, price: 869.63 },
+  { id: "t4", symbol: "AMZN", side: "Buy", qty: 60, price: 183.91 },
+  { id: "t5", symbol: "META", side: "Sell", qty: 15, price: 509.62 },
+];
diff --git a/apps/website/content/examples/components-button/demo.tsx b/apps/website/content/examples/components-button/demo.tsx
new file mode 100644
index 00000000..c9062dc6
--- /dev/null
+++ b/apps/website/content/examples/components-button/demo.tsx
@@ -0,0 +1,5 @@
+import { ComponentsGrid } from "./ComponentsGrid";
+
+export default function Demo() {
+  return <ComponentsGrid />;
+}
diff --git a/apps/website/content/examples/components-button/example.ts b/apps/website/content/examples/components-button/example.ts
new file mode 100644
index 00000000..f6717ee6
--- /dev/null
+++ b/apps/website/content/examples/components-button/example.ts
@@ -0,0 +1,14 @@
+import { defineExample } from "../../../lib/docs/examples/define";
+
+export default defineExample({
+  title: "Replacing a component",
+  description:
+    "The grid's own tool panel and filter dialog, with every Button replaced by the app's — one slot, applied everywhere, branching on site for the one place it treats differently.",
+  files: [
+    "ComponentsGrid.tsx",
+    "BrandButton.tsx",
+    "brand-button.css",
+    "columns.ts",
+    "data.ts",
+  ],
+});
diff --git a/apps/website/lib/docs/__tests__/docs-api-surface.test.ts b/apps/website/lib/docs/__tests__/docs-api-surface.test.ts
index 0f039bce..cceca147 100644
--- a/apps/website/lib/docs/__tests__/docs-api-surface.test.ts
+++ b/apps/website/lib/docs/__tests__/docs-api-surface.test.ts
@@ -287,8 +287,17 @@ const EXPORT_RE =
  * The separator is captured because it says which SHAPE the declaration is: a
  * `:` introduces a type, a `(` opens a method's parameter list, and the two are
  * read differently by {@link declaredTypeText}.
+ *
+ * A name that is not a bare identifier is QUOTED in the report —
+ * `"aria-label": string;` — and the quotes are stripped here rather than
+ * carried into the name, so the docs cell and the report agree on one
+ * spelling. Without this the member was invisible: `PretableIconButtonProps`
+ * reported exactly one member (`site`), and a table documenting the
+ * `aria-label` the whole component turns on read as documenting a member the
+ * type does not have.
  */
-const MEMBER_RE = /^ {4}(?:readonly )?([A-Za-z_$][A-Za-z0-9_$]*)(\?)?\s*([:(])/;
+const MEMBER_RE =
+  /^ {4}(?:readonly )?"?([A-Za-z_$][A-Za-z0-9_$-]*)"?(\?)?\s*([:(])/;
 
 const OPENERS = "{([";
 const CLOSERS = "})]";
@@ -1111,7 +1120,10 @@ function documentedNames(cell: string): DocumentedNames {
 
   for (const part of cell.replace(/`/g, "").split("/")) {
     const trimmed = part.trim();
-    const name = /^[A-Za-z_$][A-Za-z0-9_$]*/.exec(trimmed)?.[0];
+    // Hyphens are part of the name: a member the report quotes because it is
+    // not a bare identifier (`"aria-label"`) is written in a docs cell without
+    // the quotes, and stopping at the hyphen read `aria-label` as `aria`.
+    const name = /^[A-Za-z_$][A-Za-z0-9_$-]*/.exec(trimmed)?.[0];
 
     if (name) names.push(name);
     else unreadable.push(trimmed);
@@ -1345,6 +1357,23 @@ const TABLES: Record<string, TableBinding> = {
     types: [{ pkg: "react", name: "PretableToolPanelSection" }],
     complete: true,
   },
+
+  // The kit's first two components (SP1). `complete: true` on each: the table
+  // is the page's statement of the component's own props (the native button
+  // attributes it extends are not reported members), and a prop growing on the
+  // type without a row here is exactly the drift this file exists to catch.
+  "grid/components.mdx#Button": {
+    types: [{ pkg: "react", name: "PretableButtonProps" }],
+    complete: true,
+  },
+  "grid/components.mdx#IconButton": {
+    types: [{ pkg: "react", name: "PretableIconButtonProps" }],
+    complete: true,
+  },
+  "grid/components.mdx#Replacing a component": {
+    types: [{ pkg: "react", name: "PretableComponents" }],
+    complete: true,
+  },
   "grid/paste.mdx#The payload": {
     types: [{ pkg: "react", name: "PastePayload" }],
     complete: true,
@@ -1547,6 +1576,10 @@ const MEMBER_TABLE_TYPES: Record<string, true | string> = {
   // `grid/filtering.mdx`'s `ColumnType` cell gets, and for the same reason:
   // this table is the only place in the docs those two values are listed.
   "server-data/query-ownership.mdx#Processing authority": true,
+
+  "grid/components.mdx#Button": true,
+  "grid/components.mdx#IconButton": true,
+  "grid/components.mdx#Replacing a component": true,
 };
 
 /**
@@ -1737,6 +1770,17 @@ const STRING_UNIONS: Record<string, UnionBinding> = {
   // reader copies.
   "react/PretableBodyStateKind": { page: "server-data/lifecycle.mdx" },
 
+  // The built-in button sites. `grid/components.mdx` names the type as the
+  // vocabulary `site` draws from and says outright that it grows additively —
+  // a new grid control may introduce a new site without a major bump. The
+  // twelve names are the grid's own control inventory rather than a menu a
+  // reader picks from, so no page lists them, and there is nothing here to
+  // hold a sentence to.
+  "react/PretableBuiltInButtonSite": {
+    unenumerated:
+      "grid/components.mdx names the type as where `site`'s built-in values come from and states that the set grows additively; no page spells the members out.",
+  },
+
   // Named, never spelled out. Each of these appears once, in a "See also" list
   // of type names pointing at an API reference page — `ColumnType`,
   // `FilterOperator` on grid/filtering.mdx, `PretableEditStatus` on
diff --git a/apps/website/lib/docs/examples/demos.generated.ts b/apps/website/lib/docs/examples/demos.generated.ts
index caf61d7f..ebf9543d 100644
--- a/apps/website/lib/docs/examples/demos.generated.ts
+++ b/apps/website/lib/docs/examples/demos.generated.ts
@@ -11,6 +11,7 @@ import asyncCellEditingDemo from "../../../content/examples/async-cell-editing/d
 import cellPresentationsDemo from "../../../content/examples/cell-presentations/demo";
 import columnFiltersDemo from "../../../content/examples/column-filters/demo";
 import columnLayoutDemo from "../../../content/examples/column-layout/demo";
+import componentsButtonDemo from "../../../content/examples/components-button/demo";
 import customCellEditorDemo from "../../../content/examples/custom-cell-editor/demo";
 import customThemeDemo from "../../../content/examples/custom-theme/demo";
 import darkModeToggleDemo from "../../../content/examples/dark-mode-toggle/demo";
@@ -55,6 +56,7 @@ export const exampleDemos: Partial<Record<ExampleId, ComponentType>> = {
   "cell-presentations": cellPresentationsDemo,
   "column-filters": columnFiltersDemo,
   "column-layout": columnLayoutDemo,
+  "components-button": componentsButtonDemo,
   "custom-cell-editor": customCellEditorDemo,
   "custom-theme": customThemeDemo,
   "dark-mode-toggle": darkModeToggleDemo,
diff --git a/apps/website/lib/docs/examples/registry.generated.ts b/apps/website/lib/docs/examples/registry.generated.ts
index b4b2df03..95f1ed06 100644
--- a/apps/website/lib/docs/examples/registry.generated.ts
+++ b/apps/website/lib/docs/examples/registry.generated.ts
@@ -7,6 +7,7 @@ import asyncCellEditing from "../../../content/examples/async-cell-editing/examp
 import cellPresentations from "../../../content/examples/cell-presentations/example";
 import columnFilters from "../../../content/examples/column-filters/example";
 import columnLayout from "../../../content/examples/column-layout/example";
+import componentsButton from "../../../content/examples/components-button/example";
 import csvClipboardCopy from "../../../content/examples/csv-clipboard-copy/example";
 import customCellEditor from "../../../content/examples/custom-cell-editor/example";
 import customTheme from "../../../content/examples/custom-theme/example";
@@ -64,6 +65,10 @@ export const exampleRegistry = {
     meta: columnLayout,
     hasDemo: true,
   },
+  "components-button": {
+    meta: componentsButton,
+    hasDemo: true,
+  },
   "csv-clipboard-copy": {
     meta: csvClipboardCopy,
     hasDemo: false,
diff --git a/apps/website/lib/seo/__tests__/content-metadata.test.ts b/apps/website/lib/seo/__tests__/content-metadata.test.ts
index ea1bb03e..c0a872de 100644
--- a/apps/website/lib/seo/__tests__/content-metadata.test.ts
+++ b/apps/website/lib/seo/__tests__/content-metadata.test.ts
@@ -96,7 +96,7 @@ describe("canonical content metadata", () => {
     expect(invalid).toEqual([]);
   });
 
-  it("keeps all 50 rendered page titles unique", () => {
+  it("keeps all 51 rendered page titles unique", () => {
     const counts = new Map<string, number>();
     for (const page of pages) {
       counts.set(page.renderedTitle, (counts.get(page.renderedTitle) ?? 0) + 1);
@@ -105,7 +105,7 @@ describe("canonical content metadata", () => {
       .filter(([, count]) => count > 1)
       .map(([title, count]) => ({ title, count }));
 
-    expect(pages).toHaveLength(50);
+    expect(pages).toHaveLength(51);
     expect(duplicates).toEqual([]);
   });
 
diff --git a/apps/website/lib/seo/__tests__/routes.test.ts b/apps/website/lib/seo/__tests__/routes.test.ts
index 872c0977..31d59bb3 100644
--- a/apps/website/lib/seo/__tests__/routes.test.ts
+++ b/apps/website/lib/seo/__tests__/routes.test.ts
@@ -11,7 +11,7 @@ const DOCS_ROOT = path.join(__dirname, "../../../content/docs");
 
 describe("SEO route registry", () => {
   it("contains the canonical route set in navigation order", () => {
-    expect(routes).toHaveLength(50);
+    expect(routes).toHaveLength(51);
     expect(routes.map((route) => route.path)).toEqual([
       "/",
       "/bench",
diff --git a/apps/website/scripts/__tests__/generate-sitemap.test.ts b/apps/website/scripts/__tests__/generate-sitemap.test.ts
index 50a0d013..6f4df589 100644
--- a/apps/website/scripts/__tests__/generate-sitemap.test.ts
+++ b/apps/website/scripts/__tests__/generate-sitemap.test.ts
@@ -88,8 +88,8 @@ describe("generateSitemapXml", () => {
       }),
     );
 
-    expect(xml.match(new RegExp(`<loc>${SITE_ORIGIN}/`, "g"))).toHaveLength(50);
-    expect(xml.match(/<lastmod>/g)).toHaveLength(50);
+    expect(xml.match(new RegExp(`<loc>${SITE_ORIGIN}/`, "g"))).toHaveLength(51);
+    expect(xml.match(/<lastmod>/g)).toHaveLength(51);
     expect(xml).not.toContain("<loc>https://pretable.ai/docs</loc>");
   });
 

From 15c7dfcf772a99dc242cec3349f43a0198cd33c6 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 11:41:42 -0700
Subject: [PATCH 25/31] test: the portal read settles like its sibling; the
 hover guard checks per comma-part

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../__tests__/components-override.test.tsx    |  9 +++++++--
 packages/ui/src/__tests__/css-cascade.test.ts | 19 ++++++++++++++++---
 2 files changed, 23 insertions(+), 5 deletions(-)

diff --git a/packages/react/src/__tests__/components-override.test.tsx b/packages/react/src/__tests__/components-override.test.tsx
index 2a09dc64..fdde15ee 100644
--- a/packages/react/src/__tests__/components-override.test.tsx
+++ b/packages/react/src/__tests__/components-override.test.tsx
@@ -198,7 +198,7 @@ describe("components on the surface", () => {
     expectKit("chip-remove", "icon-button", "chip-remove");
   });
 
-  it("the columns and filters sections' sites render the kit component too", () => {
+  it("the columns and filters sections' sites render the kit component too", async () => {
     const view = renderSurface(); // columns section open
     const kit = (
       attr: string,
@@ -225,7 +225,12 @@ describe("components on the surface", () => {
     )!;
     fireEvent.pointerDown(funnel);
     fireEvent.click(funnel);
-    const clear = document.querySelector("[data-pretable-filter-clear]");
+    const dialog = await waitFor(() => {
+      const el = document.querySelector("[data-pretable-filter-menu]");
+      if (!el) throw new Error("dialog not open");
+      return el;
+    });
+    const clear = dialog.querySelector("[data-pretable-filter-clear]");
     expect(clear).not.toBeNull();
     expect(clear).toHaveAttribute("data-pretable-button", "");
     expect(clear).toHaveAttribute("data-pretable-site", "filter-clear");
diff --git a/packages/ui/src/__tests__/css-cascade.test.ts b/packages/ui/src/__tests__/css-cascade.test.ts
index 26952532..c3a995b9 100644
--- a/packages/ui/src/__tests__/css-cascade.test.ts
+++ b/packages/ui/src/__tests__/css-cascade.test.ts
@@ -539,10 +539,23 @@ describe("grid.css cascade contract", () => {
       for (const [, selector] of rulesSelecting(css, (selector) =>
         selector.includes(`${attr}:hover`),
       )) {
+        // A comma-grouped selector can carry another site's hover alongside
+        // this one — checking the whole string lets that OTHER part's
+        // `:not(:disabled)` vouch for a part that has none of its own. Split
+        // on the comma and hold only THIS site's part to that requirement.
+        const parts = selector
+          .split(",")
+          .filter((part) => part.includes(`${attr}:hover`));
         expect(
-          selector,
-          `"${selector.trim()}" hovers ${site} without :not(:disabled)`,
-        ).toMatch(":not(:disabled)");
+          parts.length,
+          `"${selector.trim()}" matched ${attr}:hover but no comma-part contains it`,
+        ).toBeGreaterThan(0);
+        for (const part of parts) {
+          expect(
+            part,
+            `"${part.trim()}" hovers ${site} without :not(:disabled)`,
+          ).toMatch(":not(:disabled)");
+        }
       }
     }
   });

From 96bd87b99ea1c024f03f6265c1ea07eac474c91b Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 11:45:31 -0700
Subject: [PATCH 26/31] test(website): the components slot in a real browser

A replacement lands inside the portalled filter dialog, and the grid still
anchors its menu on and returns focus to a replaced icon button.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 apps/website/app/fixtures/components/page.tsx | 85 ++++++++++++++++++
 apps/website/e2e/components.spec.ts           | 87 +++++++++++++++++++
 2 files changed, 172 insertions(+)
 create mode 100644 apps/website/app/fixtures/components/page.tsx
 create mode 100644 apps/website/e2e/components.spec.ts

diff --git a/apps/website/app/fixtures/components/page.tsx b/apps/website/app/fixtures/components/page.tsx
new file mode 100644
index 00000000..c6d7b457
--- /dev/null
+++ b/apps/website/app/fixtures/components/page.tsx
@@ -0,0 +1,85 @@
+"use client";
+
+import {
+  PretableSurface,
+  type PretableButtonComponent,
+  type PretableColumn,
+  type PretableIconButtonComponent,
+} from "@pretable/react";
+import { forwardRef } from "react";
+
+/**
+ * Test fixture for `apps/website/e2e/components.spec.ts`.
+ *
+ * The unit suite (`components-override.test.tsx`) proves the components
+ * context resolves and reaches every site in jsdom. What only a real
+ * browser can prove is that a replacement lands inside a popover the grid
+ * PORTALS into `document.body` — the case the context exists for — and
+ * that the grid's own behaviour on a replaced icon button (the menu it
+ * anchors on the node, the focus it returns there) survives through the
+ * forwarded ref. Both slots below are replaced with components that mark
+ * themselves and record their `site`.
+ *
+ * Deliberately not part of the product surface; `fixtures/layout.tsx` keeps
+ * the route out of search engines.
+ */
+
+interface Row {
+  id: string;
+  name: string;
+  qty: number;
+}
+
+const ROWS: Row[] = [
+  { id: "a", name: "Alpha", qty: 1 },
+  { id: "b", name: "Bravo", qty: 2 },
+  { id: "c", name: "Charlie", qty: 3 },
+];
+
+const COLUMNS: PretableColumn<Row>[] = [
+  { id: "name", header: "Name", widthPx: 160, type: "text" },
+  { id: "qty", header: "Qty", widthPx: 100, type: "number" },
+];
+
+const FixtureButton: PretableButtonComponent = forwardRef(
+  function FixtureButton({ site, variant, ...props }, ref) {
+    return (
+      <button
+        {...props}
+        ref={ref}
+        type="button"
+        data-fixture-button={site ?? ""}
+        data-fixture-variant={variant}
+      />
+    );
+  },
+);
+
+const FixtureIconButton: PretableIconButtonComponent = forwardRef(
+  function FixtureIconButton({ site, ...props }, ref) {
+    return (
+      <button
+        {...props}
+        ref={ref}
+        type="button"
+        data-fixture-icon={site ?? ""}
+      />
+    );
+  },
+);
+
+export default function ComponentsFixturePage() {
+  return (
+    <main style={{ padding: 24 }}>
+      <PretableSurface
+        ariaLabel="components-fixture"
+        columns={COLUMNS}
+        components={{ Button: FixtureButton, IconButton: FixtureIconButton }}
+        getRowId={(row) => row.id}
+        rows={ROWS}
+        toolPanel={{ defaultActiveSection: "columns" }}
+        viewportHeight={240}
+      />
+    </main>
+  );
+}
diff --git a/apps/website/e2e/components.spec.ts b/apps/website/e2e/components.spec.ts
new file mode 100644
index 00000000..76676c4f
--- /dev/null
+++ b/apps/website/e2e/components.spec.ts
@@ -0,0 +1,87 @@
+import { expect, test } from "@playwright/test";
+
+import { waitForGridReady } from "./helpers";
+
+/**
+ * The `components` slot in a real browser. The jsdom suite proves the
+ * context resolves and reaches the sites; a browser is needed for the two
+ * claims that depend on the real DOM: that a replacement lands inside a
+ * popover portalled to document.body, and that the grid's own behaviour on
+ * the replacement — the menu it anchors on the node, the focus it returns
+ * there — still works through the forwarded ref.
+ */
+test("every button in the grid is the consumer's, including inside the portalled filter dialog", async ({
+  page,
+}) => {
+  await page.goto("/fixtures/components");
+  await waitForGridReady(page);
+
+  // Nothing the kit draws itself is left.
+  await expect(page.locator("[data-pretable-button]")).toHaveCount(0);
+  await expect(page.locator("[data-pretable-icon-button]")).toHaveCount(0);
+
+  // The tool panel's reset is the replacement, with its site and variant.
+  const reset = page.locator("[data-pretable-tool-reset]");
+  await expect(reset).toHaveAttribute("data-fixture-button", "tool-reset");
+  await expect(reset).toHaveAttribute("data-fixture-variant", "link");
+
+  // The header funnel is the icon replacement; the funnel is out of the
+  // sequential tab order and only revealed on hover (grid-header-popover-scroll.spec.ts's
+  // recipe), so hover the header row before clicking it.
+  await page.locator("[data-pretable-header-row]").first().hover();
+  const funnel = page.locator("[data-pretable-filter-funnel]").first();
+  await expect(funnel).toHaveAttribute("data-fixture-icon", "filter-funnel");
+  await funnel.click();
+
+  // The dialog is a child of <body>, and its Clear button is ours.
+  const dialog = page.locator("[data-pretable-filter-menu]");
+  await expect(dialog).toBeVisible();
+  expect(
+    await dialog.evaluate((el) => el.parentElement === document.body),
+  ).toBe(true);
+  await expect(dialog.locator("[data-pretable-filter-clear]")).toHaveAttribute(
+    "data-fixture-button",
+    "filter-clear",
+  );
+  await page.keyboard.press("Escape");
+});
+
+test("the grid still anchors a menu on, and returns focus to, a replaced icon button", async ({
+  page,
+}) => {
+  await page.goto("/fixtures/components");
+  await waitForGridReady(page);
+
+  const kebab = page.locator("[data-pretable-tool-row-menu-button]").first();
+  await expect(kebab).toHaveAttribute(
+    "data-fixture-icon",
+    "tool-row-menu-button",
+  );
+  await kebab.click();
+  const menu = page.locator("[data-pretable-column-menu]");
+  await expect(menu).toBeVisible();
+
+  // The menu opened below the node the replacement forwarded its ref to.
+  // Horizontally, `popover-position.ts`'s `placement()` clamps `left` to
+  // `min(anchorRect.left, viewportWidth - WIDTH(240) - MARGIN(8))` — the
+  // kebab sits in the tool panel near the right edge of a desktop viewport,
+  // so this fixture actually exercises the clamp rather than the
+  // unclamped case; assert the exact rule the code guarantees instead of a
+  // "close to the anchor" heuristic that only holds when unclamped.
+  const [kebabBox, menuBox, viewportSize] = await Promise.all([
+    kebab.boundingBox(),
+    menu.boundingBox(),
+    page.viewportSize(),
+  ]);
+  expect(menuBox!.y).toBeGreaterThanOrEqual(kebabBox!.y + kebabBox!.height);
+  const expectedLeft = Math.max(
+    8,
+    Math.min(kebabBox!.x, viewportSize!.width - 240 - 8),
+  );
+  expect(Math.abs(menuBox!.x - expectedLeft)).toBeLessThanOrEqual(1);
+
+  // Escape closes it and puts focus back on that node.
+  await page.keyboard.press("Escape");
+  await expect(menu).toHaveCount(0);
+  await expect(kebab).toBeFocused();
+});

From 4a3908da7331c3a0982016a33d1a3382018aac27 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 11:47:23 -0700
Subject: [PATCH 27/31] docs: the Components page says what the code does

An icon button carries no variant; the site attribute is written only when a
site is given; the example replaces labelled buttons only, and its Clear
lives in a column funnel's dialog, not the Filters section.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 apps/website/content/docs/grid/components.mdx    | 16 +++++++++-------
 .../components-button/ComponentsGrid.tsx         | 14 +++++++-------
 2 files changed, 16 insertions(+), 14 deletions(-)

diff --git a/apps/website/content/docs/grid/components.mdx b/apps/website/content/docs/grid/components.mdx
index 2891a605..82b3ada0 100644
--- a/apps/website/content/docs/grid/components.mdx
+++ b/apps/website/content/docs/grid/components.mdx
@@ -7,7 +7,7 @@ nav: Grid
 `@pretable/react` renders its own controls from a small component kit, and
 ships those components for you to use and to replace. This page covers the
 first two: `PretableButton` and `PretableIconButton`. Here is a grid whose
-every button is the app's own:
+every labelled button is the app's own:
 
 <Example id="components-button" />
 
@@ -15,8 +15,8 @@ every button is the app's own:
 
 Both render `<button type="button">`, always — every grid button is one, and a
 stray submit inside your `<form>` is a real bug class, so `type` is not a prop.
-`className` and `style` pass through and merge with the component's own
-attributes. Both forward their `ref` to the button node.
+`className` and `style` pass straight through — the components set neither,
+so yours is the whole value. Both forward their `ref` to the button node.
 
 ### Button
 
@@ -41,8 +41,9 @@ accessibility failure discovered later. An empty one warns in development.
 ## Styling
 
 The styling channel is the one the whole grid uses: attributes and tokens.
-Every button carries `data-pretable-button` or `data-pretable-icon-button`, its
-`data-pretable-variant`, and its `data-pretable-site`; the grid's own sites also
+Every button carries `data-pretable-button` or `data-pretable-icon-button`; a
+labelled button also carries `data-pretable-variant`, and either carries
+`data-pretable-site` when the grid gave it one. The grid's own sites also
 keep their original attribute (`data-pretable-filter-clear`,
 `data-pretable-tool-reset`, …), so a selector you already wrote keeps matching.
 
@@ -59,8 +60,9 @@ keep their original attribute (`data-pretable-filter-clear`,
 
 Pass `components` to `<PretableSurface>` (or `<Pretable>`) with one entry per
 component type you want to replace. The replacement is used everywhere that
-type appears — the tool panel, the header, and the portalled filter dialog —
-and receives exactly the props the built-in does, `site` included, so it can
+type appears — the tool panel and the portalled filter dialog for `Button`;
+the header, the tool panel and the group panel for `IconButton` — and
+receives exactly the props the built-in does, `site` included, so it can
 branch on where it is.
 
 | Prop         | Type                          | Notes                                                                          |
diff --git a/apps/website/content/examples/components-button/ComponentsGrid.tsx b/apps/website/content/examples/components-button/ComponentsGrid.tsx
index 4121dc5e..81a6eb54 100644
--- a/apps/website/content/examples/components-button/ComponentsGrid.tsx
+++ b/apps/website/content/examples/components-button/ComponentsGrid.tsx
@@ -14,13 +14,13 @@ export function ComponentsGrid() {
   return (
     <div>
       <p style={{ margin: "0 0 8px", fontSize: 13 }}>
-        Every button below is <code>BrandButton</code>, not pretable&apos;s —
-        one <code>components</code> slot, applied in the tool panel, the header
-        menus, and the portalled filter dialog alike. Open{" "}
-        <strong>Filters</strong> for <code>+ filter</code> and{" "}
-        <code>Clear</code>; open <strong>Columns</strong> for{" "}
-        <strong>Reset columns</strong>, the one site <code>BrandButton</code>{" "}
-        treats differently.
+        Every labelled button below is <code>BrandButton</code>; the icon
+        buttons — the funnels, the ⋮ menus — are still pretable&apos;s, because
+        this demo replaces only <code>Button</code>. Reset columns is the
+        app&apos;s danger button (it branches on <code>site</code>); the Filters
+        section&apos;s <code>+ filter</code> / <code>+ group</code> are its
+        ghost buttons; a column funnel&apos;s dialog has its link-styled{" "}
+        <code>Clear</code>.
       </p>
       <PretableSurface<Trade>
         ariaLabel="Trades"

From 548ca91a95c411cf563ad78449b63924b41c0013 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 11:49:30 -0700
Subject: [PATCH 28/31] test(website): the ref claim is the focus-return line,
 and says so

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 apps/website/app/fixtures/components/page.tsx | 2 +-
 apps/website/e2e/components.spec.ts           | 9 ++++++++-
 2 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/apps/website/app/fixtures/components/page.tsx b/apps/website/app/fixtures/components/page.tsx
index c6d7b457..a6bf4729 100644
--- a/apps/website/app/fixtures/components/page.tsx
+++ b/apps/website/app/fixtures/components/page.tsx
@@ -49,7 +49,7 @@ const FixtureButton: PretableButtonComponent = forwardRef(
         ref={ref}
         type="button"
         data-fixture-button={site ?? ""}
-        data-fixture-variant={variant}
+        data-fixture-variant={variant ?? "ghost"}
       />
     );
   },
diff --git a/apps/website/e2e/components.spec.ts b/apps/website/e2e/components.spec.ts
index 76676c4f..d6e63807 100644
--- a/apps/website/e2e/components.spec.ts
+++ b/apps/website/e2e/components.spec.ts
@@ -61,7 +61,10 @@ test("the grid still anchors a menu on, and returns focus to, a replaced icon bu
   const menu = page.locator("[data-pretable-column-menu]");
   await expect(menu).toBeVisible();
 
-  // The menu opened below the node the replacement forwarded its ref to.
+  // The menu opened where the placement rule puts it for this anchor —
+  // proving the grid's own props (`onClick` → `event.currentTarget`) landed
+  // on the replacement's real node. This is a placement check, not a ref
+  // check.
   // Horizontally, `popover-position.ts`'s `placement()` clamps `left` to
   // `min(anchorRect.left, viewportWidth - WIDTH(240) - MARGIN(8))` — the
   // kebab sits in the tool panel near the right edge of a desktop viewport,
@@ -83,5 +86,9 @@ test("the grid still anchors a menu on, and returns focus to, a replaced icon bu
   // Escape closes it and puts focus back on that node.
   await page.keyboard.press("Escape");
   await expect(menu).toHaveCount(0);
+  // THIS is the ref claim. Focus moved onto the menu's first item when it
+  // opened (`menu-keyboard.ts`), and the grid returns it through
+  // `kebabNodesRef` — filled by the ref callback the replacement forwarded.
+  // A replacement that dropped its ref would leave focus on <body> here.
   await expect(kebab).toBeFocused();
 });

From 5a61f820d7f0a2cb4ec810320d328da8b902a3c1 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 11:53:29 -0700
Subject: [PATCH 29/31] fix(ui): the two portaled surfaces that host kit
 controls declare line-height

font: inherit on the kit button pulled the host page's line-height into the
filter dialog's Clear and every menu item; the surfaces declared family,
size and colour but not the fourth member. 1.5 is what the grid's own body
computes and what the pixel baseline measured. The portaled-trio guard now
requires it on these two blocks.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 packages/ui/grid.css                          | 12 ++++++++++++
 packages/ui/src/__tests__/css-cascade.test.ts | 14 ++++++++++++++
 2 files changed, 26 insertions(+)

diff --git a/packages/ui/grid.css b/packages/ui/grid.css
index 61732949..69635877 100644
--- a/packages/ui/grid.css
+++ b/packages/ui/grid.css
@@ -1027,6 +1027,12 @@
        popover sat at the cell size. */
     font-family: var(--pretable-font-sans);
     font-size: var(--pretable-font-size-cell);
+    /* The fourth member of the trio. Every kit control inside says
+       `font: inherit`, and a `link` button has no fixed block-size, so
+       without this a consumer with no CSS reset gets the UA's `normal`
+       here — 1.5 is what the grid's own body computes and what the pixel
+       baseline measured. */
+    line-height: 1.5;
     color: var(--pretable-text-cell);
   }
   :where([data-pretable-filter-menu]) select,
@@ -1228,6 +1234,12 @@
     /* Portaled into <body>, so nothing is inherited from the viewport. */
     font-family: var(--pretable-font-sans);
     font-size: var(--pretable-font-size-cell);
+    /* The fourth member of the trio. Every kit control inside says
+       `font: inherit`, and a `link` button has no fixed block-size, so
+       without this a consumer with no CSS reset gets the UA's `normal`
+       here — 1.5 is what the grid's own body computes and what the pixel
+       baseline measured. */
+    line-height: 1.5;
     color: var(--pretable-text-cell);
   }
   :where([data-pretable-menu-item]) {
diff --git a/packages/ui/src/__tests__/css-cascade.test.ts b/packages/ui/src/__tests__/css-cascade.test.ts
index c3a995b9..c26439d6 100644
--- a/packages/ui/src/__tests__/css-cascade.test.ts
+++ b/packages/ui/src/__tests__/css-cascade.test.ts
@@ -876,6 +876,20 @@ describe("grid.css cascade contract", () => {
       // line-height to the HOST page's before the longhands are read.
       expect(match?.[0]).not.toMatch(/font:\s*inherit/);
     }
+    // The filter dialog and the column menu both host kit controls that
+    // declare `font: inherit` themselves (the Clear button, every menu
+    // item) — and a `link` button has no fixed block-size, so without an
+    // explicit line-height here those controls fall through to the HOST
+    // page's. The listbox and the calendar don't have this exposure: they
+    // set their own row heights directly, so a fourth trio member would be
+    // redundant there.
+    for (const block of [
+      /:where\(\[data-pretable-filter-menu\]\)\s*\{[^}]*\}/,
+      /:where\(\[data-pretable-column-menu\]\)\s*\{[^}]*\}/,
+    ]) {
+      const match = css.match(block);
+      expect(match?.[0]).toMatch(/line-height:\s*[^;]+/);
+    }
   });
 
   test("the reorder ghost takes the HEADER's type, not the cell's", () => {

From bce97448e1affb5ad89c2616411bbe915ad77a9a Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 11:54:03 -0700
Subject: [PATCH 30/31] chore: changeset for components SP1

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .changeset/components-sp1-button.md | 46 +++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)
 create mode 100644 .changeset/components-sp1-button.md

diff --git a/.changeset/components-sp1-button.md b/.changeset/components-sp1-button.md
new file mode 100644
index 00000000..efca4ed9
--- /dev/null
+++ b/.changeset/components-sp1-button.md
@@ -0,0 +1,46 @@
+---
+"@pretable/react": minor
+"@pretable/ui": patch
+---
+
+The first two components of a kit the grid renders its own chrome from, and a
+`components` prop to replace either with your own.
+
+`PretableButton` (two looks: `ghost`, the 24px action with a hover tint, and
+`link`, plain accent text) and `PretableIconButton` (an icon-only button whose
+`aria-label` is a required prop — omitting the accessible name is now a
+compile error, and an empty one warns in development). Both are always
+`type="button"`, pass `className` and `style` straight through, forward their
+`ref`, and carry `data-pretable-button` / `data-pretable-icon-button`,
+`data-pretable-variant` (labelled buttons) and `data-pretable-site` for styling
+through the grid's usual attributes-and-tokens channel.
+
+`components={{ Button, IconButton }}` on `<PretableSurface>` and `<Pretable>`
+replaces a component everywhere it appears — the tool panel, the header, the
+group panel and the portalled filter dialog — and the replacement receives
+exactly the props the built-in does, `site` included, so it can branch on where
+in the grid it is. It must forward its `ref` (under React 18, `forwardRef`; under
+React 19 a plain `ref` prop): the grid anchors menus on and returns focus to
+that node.
+
+The grid's twelve plain push-buttons now render from these. Each keeps its
+original attribute (`data-pretable-filter-clear`, `data-pretable-tool-reset`,
+…), so selectors and stylesheets keyed on them keep working; the shared look
+moved from twelve site rules onto the component rules, and every site's
+computed box, colours and focus ring were measured before and after — no pixel
+moved. Three things did change on purpose: `Clear` and `Reset columns`, and the
+funnel, column-menu and chip-remove icon buttons, now wear the product's focus
+ring rather than the browser's; `Clear` and `Reset columns` carry the control
+radius (visible only on that ring's corners); and the kit icon-button rule does
+not set `position: relative` — the three grid buttons that enlarge their hit
+area with a `::after` declare it themselves, so a consumer rendering an
+absolutely-positioned child inside `PretableIconButton` should position the
+button explicitly.
+
+Two smaller notes. The set of built-in `site` names (`PretableBuiltInButtonSite`)
+grows additively — a new grid button may add one without a major bump. And the
+two portalled surfaces that host these controls, the filter dialog and the
+column menu, now declare `line-height` alongside the family, size and colour
+they already declared: `font: inherit` on a kit button had been pulling the
+host page's line-height into `Clear` and every menu item for a consumer with no
+CSS reset.

From 9766c9233da254af8e2c346fc316d692adddf89e Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 12:11:22 -0700
Subject: [PATCH 31/31] test(website): the sitemap has 51 entries with the
 Components page

Task 13 moved the three unit-test count constants and missed this e2e one.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 apps/website/e2e/smoke.spec.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/apps/website/e2e/smoke.spec.ts b/apps/website/e2e/smoke.spec.ts
index e6dffe8e..e28480cb 100644
--- a/apps/website/e2e/smoke.spec.ts
+++ b/apps/website/e2e/smoke.spec.ts
@@ -131,8 +131,8 @@ test.describe("crawler-visible SEO output", () => {
       /^(?:application|text)\/xml(?:;|$)/i,
     );
     const sitemapEntries = parseSitemapXml(await sitemap.text());
-    expect(sitemapEntries).toHaveLength(50);
-    expect(sitemapEntries.map((entry) => entry.lastmod)).toHaveLength(50);
+    expect(sitemapEntries).toHaveLength(51);
+    expect(sitemapEntries.map((entry) => entry.lastmod)).toHaveLength(51);
     expect(
       new Set(sitemapEntries.map((entry) => entry.lastmod)).size,
     ).toBeGreaterThan(1);