diff --git a/apps/website/content/docs/grid/api-reference.mdx b/apps/website/content/docs/grid/api-reference.mdx
index ce900dc05..68952cb04 100644
--- a/apps/website/content/docs/grid/api-reference.mdx
+++ b/apps/website/content/docs/grid/api-reference.mdx
@@ -140,6 +140,10 @@ interface SerializeRangesArgs<TRow, TRowId, TColumns> {
 - `Pretable` — concise declarative preset.
 - `usePretable` — surface internals for advanced custom rendering.
 - `PretableBadge`, `PretableDelta`, `PretableEntity`, `PretableStatus` — shared cell presentations.
+- `PretableButton`, `PretableIconButton`, `PretableSelect`, `PretableTextInput`, `PretableTextarea`, `PretableCheckbox` — [shared controls](/docs/grid/components#the-components), with corresponding `Props` and `Component` types.
+- `PretableComponents` — the [replacement map](/docs/grid/components#replacing-a-component) accepted by the surface's `components` prop.
+- `PretableSite` / `PretableBuiltInSite` — control placement names for styling and replacement logic.
+- `PretableOverlayProvider` / `PretableOverlayProviderProps` — [popup portal scope](/docs/grid/components#overlay-scope) for application-owned hosts and local themes.
 - `getDensityHeights` — public density-aware sizing for custom renderers.
 - `serializeRanges` / `defaultCoerceForCopy` — clipboard primitives.
 - `numberFormats.money` / `numberFormats.accounting` — native numeric option helpers.
diff --git a/apps/website/content/docs/grid/components.mdx b/apps/website/content/docs/grid/components.mdx
index 0b32e5cf1..40122764f 100644
--- a/apps/website/content/docs/grid/components.mdx
+++ b/apps/website/content/docs/grid/components.mdx
@@ -1,102 +1,136 @@
 ---
 title: Components
-description: "The kit the grid renders its own chrome from — Button, IconButton, Select, TextInput, Textarea and Checkbox — how to style them, and how to replace them."
+description: "Style the grid's controls, replace them with your own components, and keep editor and popup behavior intact."
 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
-six that ship today: `PretableButton`, `PretableIconButton`,
-`PretableSelect`, `PretableTextInput`, `PretableTextarea` and `PretableCheckbox`. Here is a grid
-whose kit buttons use the app's own component:
+Use your design system's controls throughout the grid, including its editors
+and popup menus. Choose the customization level that matches your task:
+
+| You want to…                                          | Use                                                                         |
+| ----------------------------------------------------- | --------------------------------------------------------------------------- |
+| Change colors, spacing, or borders                    | [Theme tokens](/docs/theming/override-tokens) and [CSS selectors](#styling) |
+| Replace a control while keeping the grid's behavior   | The [`components` prop](#replacing-a-component)                             |
+| Build a different editor, such as a date-range picker | Column [`renderEditor`](/docs/grid/editing#custom-editors)                  |
+
+The kit is exported from `@pretable/react`. For the default appearance, load
+the `@pretable/ui` skin as described in [Getting started](/docs).
+
+## Replacing a component
+
+Pass a replacement to `<PretableSurface>` or `<Pretable>`. Each slot applies
+wherever that kit control appears, including inside portals. Omitted slots
+keep their built-in components.
+
+```tsx
+import { forwardRef } from "react";
+import { PretableSurface, type PretableTextInputProps } from "@pretable/react";
+
+// Define the component outside the grid's render function.
+const AppInput = forwardRef<HTMLInputElement, PretableTextInputProps>(
+  function AppInput({ site, className, ...props }, ref) {
+    return (
+      <input
+        {...props}
+        ref={ref}
+        data-pretable-text-input=""
+        data-pretable-site={site}
+        className={["app-input", className].filter(Boolean).join(" ")}
+      />
+    );
+  },
+);
+
+<PretableSurface
+  ariaLabel="Orders"
+  rows={rows}
+  columns={columns}
+  getRowId={(row) => row.id}
+  components={{ TextInput: AppInput }}
+/>;
+```
+
+Forward the supplied **native props, handlers, ARIA/data attributes, and ref**
+to the actual control. Preserve `className` and `style` when adding your own
+styling. The grid uses the ref for editor autofocus, textarea sizing, popup
+anchoring, and focus restoration. React 18 requires `forwardRef`; React 19
+also supports a plain `ref` prop.
+
+Keep each replacement's component identity stable: define it at module scope,
+not inside the rendering component. An inline `components={{ TextInput: AppInput }}`
+map is fine; defining a new `AppInput` function on each render remounts the field
+and can lose focus or the caret.
+
+`site` identifies where a control is used. Fields use `cell-editor`; editor
+actions use `number-increment`, `number-decrement`, `date-previous-month`, and
+`date-next-month`. Branch on `site` when one placement needs different styling.
+`PretableBuiltInSite` lists the built-in names and may gain new names in minor
+releases; `PretableSite` also accepts application-defined strings.
+
+The slots cover kit controls. Structural column headers, tabs, tree expanders,
+menu items, and segmented filter joins keep their specialized behavior.
+
+### Use your own editor controls
+
+These replacements keep the built-in parsing, keyboard handling, save state,
+and errors. Open **Quantity** to use the replacement input and stepper buttons,
+or **Notes** to use the replacement textarea. The Code tab contains the complete
+controlled grid and native replacements.
+
+<Example id="components-editors" />
+
+### Replace a button
+
+This example replaces `Button` across the tool panel and filter dialog, using
+`site` to give Reset columns a different appearance.
 
 <Example id="components-button" />
 
 ## The components
 
-Four of the six render `<button type="button">`, always — a stray submit
-inside your `<form>` is a real bug class, so `type` is not a prop on any of
-them. `PretableTextInput` renders a native `<input>` and passes its `type` through.
-`PretableTextarea` renders a native `<textarea>`. `className` and `style` pass straight through on all six — the
-components set neither, so yours is the whole value — and each forwards its
-`ref` to the node it renders. Select, TextInput, Textarea and Checkbox compose that
-ref with their internal node ref. Callback refs that return a cleanup function
-have that cleanup called on detach or replacement; callbacks without one
-receive `null`. Object refs are cleared on detach.
+All controls forward refs to their native nodes and accept `className` and
+`style`. Button, IconButton, Select, and Checkbox render `<button type="button">`
+and do not accept a `type` prop. TextInput and Textarea render native fields.
+
+| Prop         | Type                          | Native ref                    |
+| ------------ | ----------------------------- | ----------------------------- |
+| `Button`     | `PretableButtonComponent`     | `HTMLButtonElement`           |
+| `IconButton` | `PretableIconButtonComponent` | `HTMLButtonElement`           |
+| `Select`     | `PretableSelectComponent`     | `HTMLButtonElement` (trigger) |
+| `TextInput`  | `PretableTextInputComponent`  | `HTMLInputElement`            |
+| `Textarea`   | `PretableTextareaComponent`   | `HTMLTextAreaElement`         |
+| `Checkbox`   | `PretableCheckboxComponent`   | `HTMLButtonElement`           |
+
+Each slot has a standalone export prefixed with `Pretable`, such as
+`PretableTextInput`, plus corresponding `Props` and `Component` types, for example
+`PretableTextInputProps` and `PretableTextInputComponent`. All accept `site`,
+which the built-in controls emit as `data-pretable-site`.
 
 ### Button
 
-A labelled push-button in one of the grid's two looks.
+A labelled action. `variant="ghost"` (the default) uses a hover tint;
+`variant="link"` uses plain accent text. Other props are native button props.
 
-| Prop      | Type                | Notes                                                                                       |
-| --------- | ------------------- | ------------------------------------------------------------------------------------------- |
-| `variant` | `"ghost" \| "link"` | `ghost` is the 24px action with a hover tint; `link` is plain accent text. Default `ghost`. |
-| `site`    | `PretableSite`      | Where in the grid the button is; lands as `data-pretable-site`. Open to your own names.     |
+| Prop      | Type                | Meaning                       |
+| --------- | ------------------- | ----------------------------- |
+| `variant` | `"ghost" \| "link"` | Appearance; defaults to ghost |
+| `site`    | `PretableSite`      | Placement name                |
 
 ### 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 once per page.
+An icon-only action. Supply its icon as children and a nonempty `aria-label`
+describing the action, such as `Next month`. The label is required by its type.
 
-| Prop         | Type           | Notes                                                           |
-| ------------ | -------------- | --------------------------------------------------------------- |
-| `aria-label` | `string`       | Required. The accessible name.                                  |
-| `site`       | `PretableSite` | Where in the grid the button is; lands as `data-pretable-site`. |
+| Prop         | Type           | Meaning                  |
+| ------------ | -------------- | ------------------------ |
+| `aria-label` | `string`       | Required accessible name |
+| `site`       | `PretableSite` | Placement name           |
 
 ### Select
 
-A select-only combobox: the kit's answer to the native `<select>`, whose open
-list no theme can reach. The trigger is a `<button role="combobox">`; the list
-is a portalled `role="listbox"` placed against it. `aria-label` is
-**required**, for the same reason it is on `IconButton` — a picker with no
-accessible name reads as an unnamed button — and an empty one warns once per
-page. Four grid pickers are this component: the funnel menu's
-[operator](/docs/grid/filtering#the-built-in-menu), the tool panel's
-[filter-builder column and operator](/docs/grid/tool-panel#dom-hooks-and-strings),
-and the grouping section's
-[aggregate picker](/docs/grid/tool-panel#aggregates).
-
-The keyboard is the listbox one: on a closed trigger, `↓`, `↑`, `Enter` or
-`Space` opens the list; open, `↓` / `↑` move through it, wrapping at the ends
-and skipping disabled options; `Home` / `End` jump to the first and last
-enabled option; typing jumps by label prefix, the prefix resetting after
-500ms of silence or when the list closes or reopens; `Enter` or `Space` commits the active option; `Escape`
-closes the list and returns focus to the trigger; `Tab` closes it and moves
-on. `onChange` fires only when the chosen value differs from `value`.
-
-A `disabled` option is shown, skipped by the keyboard and inert to click —
-that is how the aggregate picker shows a consumer-written custom aggregate it
-must never write back. And a `value` that is absent from `options` renders as
-its own label rather than as an empty trigger, so a picker never silently
-disagrees with the state behind it.
-
-Give every option a unique, stable `value`. If options change while the list
-is open, the highlight follows that value through reordering. Removing or
-disabling it moves the highlight to the first enabled option. An all-disabled
-list has no highlight and cannot commit; an empty roster closes the list.
-Adding options again does not reopen it.
-
-String and number labels supply their own typeahead text. Rich labels require
-`textValue`, the plain text to search; it can also override typeahead text for a
-primitive label. The component does not inspect or render arbitrary React
-components to discover their text. For example:
-
-```tsx
-const options = [
-  { value: "open", label: "Open" },
-  {
-    value: "review",
-    label: <strong>In review</strong>,
-    textValue: "In review",
-  },
-];
-```
-
-When migrating rich options, add `textValue` to each label that is not a
-string or number. `PretableSelectOption` is now a union type, so an interface
-that previously extended it should use a type intersection instead, such as
-`type AppOption = PretableSelectOption & { category: string }`.
+A controlled select-only combobox with a button trigger and a portalled
+listbox. It differs from the [editable enum editor](/docs/grid/editing#enums),
+which accepts typed queries in a text field.
 
 ```tsx
 import { PretableSelect } from "@pretable/react";
@@ -113,102 +147,68 @@ import { PretableSelect } from "@pretable/react";
 />;
 ```
 
-| Prop         | Type                              | Notes                                                                                                           |
-| ------------ | --------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| `options`    | `readonly PretableSelectOption[]` | The choices, in display order. Each has `value`, `label`, optional `disabled`, and `textValue` for rich labels. |
-| `value`      | `string`                          | The committed value. Absent from `options`, it renders as its own label.                                        |
-| `onChange`   | `(value: string) => void`         | Called with the chosen value, and only when it differs from `value`.                                            |
-| `aria-label` | `string`                          | Required. The accessible name — name what it chooses, e.g. `Filter operator`.                                   |
-| `site`       | `PretableSite`                    | Where in the grid the picker is; lands as `data-pretable-site`.                                                 |
+| Prop         | Type                              | Meaning                                                                                            |
+| ------------ | --------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `options`    | `readonly PretableSelectOption[]` | Choices with unique, stable `value`, `label`, optional `disabled`, and `textValue` for rich labels |
+| `value`      | `string`                          | Committed value; displayed as-is if absent from the options                                        |
+| `onChange`   | `(value: string) => void`         | Called when a different value is chosen                                                            |
+| `aria-label` | `string`                          | Required accessible name                                                                           |
+| `site`       | `PretableSite`                    | Placement name                                                                                     |
+
+String and number labels supply their own typeahead text. Rich labels need a
+plain-text `textValue`, for example
+`{ value: "review", label: <strong>In review</strong>, textValue: "In review" }`.
+
+| Key                               | Behavior                                                           |
+| --------------------------------- | ------------------------------------------------------------------ |
+| ArrowDown / ArrowUp, Enter, Space | Open a closed list                                                 |
+| ArrowDown / ArrowUp               | Move through enabled options, wrapping at the ends                 |
+| Home / End                        | Move to the first / last enabled option                            |
+| Typing                            | Match a label prefix; reset after 500ms or after closing/reopening |
+| Enter / Space                     | Choose the active option                                           |
+| Escape                            | Close and return focus to the trigger                              |
+| Tab                               | Close and continue normal focus traversal                          |
+
+If options change while open, the highlight follows its value through
+reordering. Removing or disabling that value selects the first enabled
+highlight. An all-disabled list cannot commit; an empty list closes and stays
+closed when options are added again.
 
 ### TextInput
 
-A text field. It is the native `<input>` and nothing more — no wrapper
-element, no clear button, no debounce — and that is the design rather than an
-omission. The native element is the accessible one, so a screen reader, a
-password manager and the platform's own autofill all keep working;
-`type="date"` keeps its native picker and `inputMode` keeps the right soft
-keyboard, neither of which survives a wrapper that reinterprets `type`. What
-a theme needs from this control is the box, and that arrives through
-`data-pretable-text-input`.
-
-Every native input prop passes straight through — `type`, `inputMode`,
-`value`, `onChange`, `placeholder`, `disabled`, `aria-*`, `className`,
-`style` — which is why the table below has one row: `site` is the only prop
-the component adds, and the rest are the native element's own. Value
-semantics stay with the site rather than the component: the filter fields
-[debounce their operand](/docs/grid/tool-panel#what-commits-and-when) and the
-search box does not, and a component that owned that for all of them would be
-wrong for most.
-
-The grid uses this component for the funnel menu's
-[value field and its min/max pair](/docs/grid/filtering#the-built-in-menu),
-the tool panel's
-[filter-row value and its min/max pair](/docs/grid/tool-panel#dom-hooks-and-strings),
-the [columns search box](/docs/grid/tool-panel#the-columns-section), and the
-text, number, enum and date cell editors.
-
-The naming check recognizes nonempty `aria-label`, resolved `aria-labelledby`
-text, native label text and `title`. It warns once per page when none is found;
-this bounded heuristic does not replace an accessibility audit.
+`PretableTextInput` renders a native `<input>`. It forwards input props such as
+`type`, `inputMode`, `value`, `onChange`, `readOnly`, and ARIA attributes. It adds
+only `site` and the `data-pretable-text-input` styling hook. Debouncing, parsing,
+and commit behavior belong to the caller.
 
 ```tsx
-import { PretableTextInput } from "@pretable/react";
-
 <PretableTextInput
   aria-label="Filter value"
   type="date"
   value={value}
   onChange={(event) => setValue(event.target.value)}
-/>;
+/>
 ```
 
-| Prop   | Type           | Notes                                                                                           |
-| ------ | -------------- | ----------------------------------------------------------------------------------------------- |
-| `site` | `PretableSite` | Where in the grid the field is; lands as `data-pretable-site`. Every other prop is the input's. |
+| Prop   | Type           | Meaning                                                 |
+| ------ | -------------- | ------------------------------------------------------- |
+| `site` | `PretableSite` | Placement name; other props are native input attributes |
 
 ### Textarea
 
-`PretableTextarea` is a native `<textarea>` with the same naming, ref and
-attribute-passthrough contract as TextInput. The multiline cell editor uses
-it through `components.Textarea`; standalone consumers can use it directly.
-It emits `data-pretable-textarea`. Native props such as `rows`, `value`,
-`onChange`, `readOnly`, `disabled` and ARIA attributes pass through. Auto-grow
-and commit keys belong to the editor, not the shared control.
+`PretableTextarea` renders a native `<textarea>` with the same prop and ref
+contract as TextInput. It emits `data-pretable-textarea`. The multiline editor
+handles auto-grow and commit keys; the shared control forwards native props
+such as `rows`, `value`, and `onChange`.
 
-| Prop   | Type           | Notes                                                                                            |
-| ------ | -------------- | ------------------------------------------------------------------------------------------------ |
-| `site` | `PretableSite` | Where the field appears; emits `data-pretable-site`. Other props are native textarea attributes. |
+| Prop   | Type           | Meaning                                                    |
+| ------ | -------------- | ---------------------------------------------------------- |
+| `site` | `PretableSite` | Placement name; other props are native textarea attributes |
 
 ### Checkbox
 
-A checkbox rendered as `<button type="button" role="checkbox">`, with
-`aria-checked` describing false, true or mixed. Native checkbox inputs also
-support `tabIndex` and indeterminate state. This kit uses a button to share
-its explicit state attributes and themed glyph: check, minus, or empty.
-
-It is controlled. `onCheckedChange` is called with the next value and
-nothing is written until you write it, and `"mixed"` toggles to `true` — the
-header select-all's "some rows, not all" resolving to "all". The keyboard is
-the native button's, so `Space` and `Enter` both activate and both arrive as
-a click; there is no key handler of its own to disagree with the platform. A
-consumer `onClick` runs **first** and may `preventDefault()` to veto the
-toggle, which is how a shift-click range select keeps the click without a
-second write following it. Native button props pass through — `disabled`,
-`tabIndex`, `aria-busy`, `aria-invalid`, `aria-errormessage`.
-
-Seven grid controls are this component: the
-[row-select header and cell checkboxes](/docs/grid/selection#checkbox-column),
-the [boolean cell](/docs/grid/editing#booleans), the
-[column visibility toggle](/docs/grid/tool-panel#the-columns-section), the
-[hide-grouped switch](/docs/grid/tool-panel#hide-grouped-columns), and the
-enum checklists in the [funnel menu](/docs/grid/filtering#the-built-in-menu)
-and the [tool panel's filter row](/docs/grid/tool-panel#rows-runs-and-the-join).
-
-An `aria-label` names it, and so does a wrapping `<label>` — a `<button>` is
-a labelable element, so the text names the control and clicking that text
-toggles it, which is the shape the hide-grouped switch uses. With neither it
-warns once per page, the way `IconButton` does.
+A controlled `<button role="checkbox">` with `aria-checked` set to `true`,
+`false`, or `mixed`. Space and Enter activate it through the native click.
 
 ```tsx
 import { PretableCheckbox } from "@pretable/react";
@@ -219,18 +219,65 @@ import { PretableCheckbox } from "@pretable/react";
 </label>;
 ```
 
-| Prop              | Type                      | Notes                                                                 |
-| ----------------- | ------------------------- | --------------------------------------------------------------------- |
-| `checked`         | `boolean \| "mixed"`      | The state. `"mixed"` draws the minus glyph and toggles to `true`.     |
-| `onCheckedChange` | `(next: boolean) => void` | Called with the next value after a click, before anything is written. |
-| `site`            | `PretableSite`            | Where in the grid the checkbox is; lands as `data-pretable-site`.     |
+| Prop              | Type                      | Meaning                                                   |
+| ----------------- | ------------------------- | --------------------------------------------------------- |
+| `checked`         | `boolean \| "mixed"`      | Current state; mixed toggles to true                      |
+| `onCheckedChange` | `(next: boolean) => void` | Requests a state change; the caller must update `checked` |
+| `site`            | `PretableSite`            | Placement name                                            |
+
+Native button props pass through. A supplied `onClick` runs first and can
+call `preventDefault()` to prevent the toggle.
+
+### Accessible names and refs
+
+Give every control an accessible name. Use visible text for Button, `aria-label`
+for IconButton and Select, and a native label or ARIA label for fields and
+Checkbox. Missing-name warnings check common naming sources once after mounting;
+they do not replace accessibility testing.
+
+Built-in controls support object refs and callback refs. Select, TextInput,
+Textarea, and Checkbox compose refs internally: on detach they run a returned
+cleanup, otherwise call the ref with `null`, and clear object refs. Button and
+IconButton forward refs directly; returned cleanups require React 19.
+
+## Styling
+
+Use [theme tokens](/docs/theming/override-tokens) for shared appearance.
+The built-in controls also expose these selectors. Native replacements can
+emit the same hooks to retain the skin's styles, as the input example above does.
+
+| Selector                                                  | Target                                                              |
+| --------------------------------------------------------- | ------------------------------------------------------------------- |
+| `[data-pretable-button]`, `[data-pretable-icon-button]`   | Action buttons                                                      |
+| `[data-pretable-variant="link"]`                          | A labelled button variant                                           |
+| `[data-pretable-site="tool-reset"]`                       | A specific placement                                                |
+| `[data-pretable-text-input]`, `[data-pretable-textarea]`  | Native fields                                                       |
+| `[data-pretable-select]`                                  | Select trigger; `data-pretable-value` holds its committed selection |
+| `[data-pretable-select-label]`, `[data-pretable-listbox]` | Select label and popup                                              |
+| `[data-pretable-option]`                                  | Option; `data-pretable-option-value` identifies it                  |
+| `[data-pretable-option][data-pretable-active]`            | Keyboard-highlighted option                                         |
+| `[data-pretable-option][aria-selected="true"]`            | Chosen option                                                       |
+| `[data-pretable-checkbox][aria-checked="mixed"]`          | Mixed checkbox state                                                |
+
+Checkbox is a button, so use `aria-checked` selectors instead of `:checked`.
+Select's `data-pretable-value` is independent of the native button's `value`.
+Placement-specific hooks such as `data-pretable-filter-clear` remain available.
+
+```css
+[data-pretable-site="tool-reset"] {
+  color: var(--pretable-text-error);
+}
+[data-pretable-checkbox][aria-checked="mixed"] {
+  --pretable-checkbox-checked-bg: var(--pretable-accent);
+}
+```
 
 ## Overlay scope
 
-Popups render into `document.body` by default, escaping the grid's clipping
-viewport. React context remains available across that portal; CSS inheritance
-comes from the popup's DOM ancestors. Use `PretableOverlayProvider` to place
-popups in an application-owned host inside a local theme scope:
+Popups render into `document.body` by default to escape the grid's clipping
+viewport. React context crosses the portal, but inherited CSS comes from the
+popup's DOM ancestors. For a local theme, use `PretableOverlayProvider` to
+place popups inside the same theme scope:
 
 ```tsx
 import { PretableOverlayProvider } from "@pretable/react";
@@ -249,109 +296,27 @@ function ScopedGrid({ children }: { children: ReactNode }) {
 }
 ```
 
-Put the grid in `ScopedGrid`, and place your token overrides on `.dashboard`.
-Both the grid and its popup host then inherit custom tokens, direction and
-color scheme, including live changes. The provider does **not** copy styles
-from a trigger: move overrides from the grid element to the shared section,
-or apply them to the portal host too. Props can also be passed to components
-inside portals; context avoids manually forwarding shared configuration.
-
-| Prop        | Type                  | Notes                                                                               |
-| ----------- | --------------------- | ----------------------------------------------------------------------------------- |
-| `container` | `HTMLElement \| null` | Required. Nearest provider wins; `null` defers popup content until a target exists. |
-| `children`  | `ReactNode`           | The grid or kit controls whose popups use this target.                              |
-
-Keep the host connected, in the same document as the trigger, and outside
-clipping or transformed containing blocks. The example's host is a sibling
-of the grid, not inside its scroll viewport. Replacing the host remounts portal
-content; focus is not preserved across target replacement. With a null target,
-open intent is retained, but triggers do not claim a visible popup or reference
-its unmounted options. Menus that take focus do so when their portal attaches.
-
-Nested popup presses belong to their parent overlay. Pressing a sibling
-Select closes the previous list; pressing the same trigger toggles its own
-list closed. Outside presses close without moving focus back, and Escape
-continues to dismiss the innermost popup first.
+Put the grid inside `ScopedGrid` and token overrides on `.dashboard`. The grid
+and popup host inherit its tokens, direction, and color scheme. The provider
+does not copy styles from the trigger.
 
-## Styling
+| Prop        | Type                  | Meaning                                                                                   |
+| ----------- | --------------------- | ----------------------------------------------------------------------------------------- |
+| `container` | `HTMLElement \| null` | Required target; nearest provider wins. `null` defers popup content until a target exists |
+| `children`  | `ReactNode`           | Grid or kit controls that use this target                                                 |
 
-The styling channel is the one the whole grid uses: attributes and tokens.
-Every push-button carries `data-pretable-button` or
-`data-pretable-icon-button`; a labelled button also carries
-`data-pretable-variant`, and any of them carries `data-pretable-site` when
-the grid gave it one. A select's trigger carries `data-pretable-select` and
-writes its committed option value to `data-pretable-value`, independently of
-the native button’s `.value` property. Tests and selectors can read this
-committed selection directly. Its label span is `data-pretable-select-label`; the open list is
-`data-pretable-listbox` with a `data-pretable-option` per entry, each
-carrying its own value as `data-pretable-option-value` — which option it
-**is**, as against the trigger's one committed `data-pretable-value` — the
-keyboard-active one carrying `data-pretable-active` (renamed from the old
-`data-active`; update custom selectors) and the chosen one
-`aria-selected="true"`. A text field carries `data-pretable-text-input`, and
-a checkbox `data-pretable-checkbox` plus the `aria-checked` its three states
-live in: match `[aria-checked="true"]` and `[aria-checked="mixed"]` rather
-than a `:checked` pseudo-class, which a `<button>` never has. The grid's own
-sites also keep their original attribute (`data-pretable-filter-clear`,
-`data-pretable-tool-reset`, `data-pretable-row-select`, …), so a selector you
-already wrote keeps matching.
+Keep the host connected, in the trigger's document, and outside clipping or
+transformed containing blocks. Replacing the host remounts its popup content
+and does not preserve focus. A null target retains open intent; focus-taking
+menus receive focus when the host attaches.
 
-```css
-[data-pretable-button][data-pretable-variant="ghost"] {
-  --pretable-accent: rebeccapurple;
-}
-[data-pretable-site="tool-reset"] {
-  color: var(--pretable-text-error);
-}
-[data-pretable-select][data-pretable-value="between"] {
-  font-variant-numeric: tabular-nums;
-}
-[data-pretable-option][data-pretable-active],
-[data-pretable-option][aria-selected="true"] {
-  background: var(--pretable-bg-hover);
-}
-[data-pretable-text-input][data-pretable-site="filter-value"] {
-  font-variant-numeric: tabular-nums;
-}
-[data-pretable-checkbox][aria-checked="mixed"] {
-  --pretable-checkbox-checked-bg: var(--pretable-accent);
-}
-```
+Nested popups dismiss from the inside out with Escape. Opening a sibling
+Select closes the previous list. Outside presses dismiss without returning
+focus to the trigger.
 
-## Replacing a component
+## Migration notes
 
-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 and the portalled filter dialog for `Button`;
-the header, the tool panel and the group panel for `IconButton`; the filter
-dialog, the filter builder and the grouping section for `Select`; the funnel
-menu's operand fields, the filter builder's operand fields and the Columns
-search box and single-line editors for `TextInput`; the multiline editor for `Textarea`; the row-select column, the boolean cell, the tool
-panel and both enum checklists for `Checkbox` — 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.     |
-| `Checkbox`   | `PretableCheckboxComponent`   | Receives `PretableCheckboxProps`; must forward its `ref` to the button node.   |
-| `IconButton` | `PretableIconButtonComponent` | Receives `PretableIconButtonProps`; must forward its `ref` to the button node. |
-| `Select`     | `PretableSelectComponent`     | Receives `PretableSelectProps`; must forward its `ref` to the button node.     |
-| `Textarea`   | `PretableTextareaComponent`   | Receives `PretableTextareaProps`; forwards its `ref` to the textarea node.     |
-| `TextInput`  | `PretableTextInputComponent`  | Receives `PretableTextInputProps`; must forward its `ref` to the input node.   |
-
-Replacements must forward the supplied props, handlers, ARIA and data
-attributes, and the `ref` to the actual native node. The grid uses those refs
-for menu anchoring, focus restoration, editor autofocus and textarea sizing.
-The slots cover kit controls; structural column headers, tabs, tree expanders,
-menu items, and segmented filter joins retain their specialized behavior.
-Editor fields use `site="cell-editor"`; action sites are `number-increment`,
-`number-decrement`, `date-previous-month` and `date-next-month`.
-Under React 18 that
-means `forwardRef`; under React 19 a plain `ref` prop is enough. The set of
-built-in `site` names is the
-`PretableBuiltInSite` type and grows additively — a new grid control
-may introduce a new site without a major bump.
-
-The field/checkbox naming warning runs once after mounting in any build. It
-checks common naming sources; it is a diagnostic heuristic, not a complete
-accessible-name computation or an accessibility certification.
+For older kit integrations, add `textValue` to rich Select labels.
+`PretableSelectOption` is a union; extend it with an intersection such as
+`type AppOption = PretableSelectOption & { category: string }`.
+Update option selectors from `data-active` to `data-pretable-active`.
diff --git a/apps/website/content/docs/grid/editing.mdx b/apps/website/content/docs/grid/editing.mdx
index 90cd34883..4400bba9a 100644
--- a/apps/website/content/docs/grid/editing.mdx
+++ b/apps/website/content/docs/grid/editing.mdx
@@ -4,29 +4,24 @@ description: "Controlled inline cell editing: typed editors driven by column.typ
 nav: Grid
 ---
 
-Inline editing has explicit ownership. In rows mode, a successful commit emits a typed `onRowChange` proposal containing the previous row and the complete proposed row; publish that row through your own state. In explicit-model mode, `beforeRowChange` validates the proposed batch before the surface publishes one row-model transaction. The grid owns the in-progress draft and lifecycle; your app or row model owns the data.
+Make a column editable with `editable: true`, then save accepted rows through
+`onRowChange`. The grid manages the draft; your application owns the stored data.
+Editing is off by default.
 
-Editing is **off by default** — a cell only becomes editable when its column opts in.
-
-<Callout type="note">
-  This is single-cell editing. Fill-handle drag, paste-to-edit, multi-cell
-  edits, and undo are not part of this phase.
-</Callout>
-
-Click a cell below, press `Enter` (or just start typing), edit, and commit — every column is a different [typed editor](#typed-editors): text, number, boolean, enum, and date. Edit **Quantity** to a fraction to see a synchronous `validate` rejection, or to a negative number to watch the full async `saving` → `error` lifecycle — the field dims and locks for ~800ms, then the commit is rejected with an inline error, and `Enter` retries:
+This guide covers single-cell editing. Fill-handle drag, paste-to-edit,
+multi-cell edits, and undo are not supported.
 
 <Example id="async-cell-editing" />
 
-That grid is this page's worked example throughout: `editable` columns, a controlled `rows` array, and `onRowChange` publishing the complete proposed row. Open its Code tab to read or copy `AsyncEditingGrid.tsx`.
-
 ## The controlled model
 
-Rows-mode `onRowChange` receives a fully correlated proposal. Return a promise to make the commit await your save:
+Set editable columns and publish the proposed row through your state. Return a
+promise from `onRowChange` to wait for an asynchronous save:
 
 ```tsx
 <PretableSurface
   ariaLabel="People"
-  columns={columns}
+  columns={[{ id: "name", header: "Name", editable: true }]}
   rows={rows}
   getRowId={(row) => row.id}
   onRowChange={({ rowId, row }) => {
@@ -37,7 +32,7 @@ Rows-mode `onRowChange` receives a fully correlated proposal. Return a promise t
 />
 ```
 
-The proposal preserves the row, ID, column, and value correlations inferred from the typed column tuple:
+`onRowChange` receives these fields:
 
 | Field         | Notes                                                                |
 | ------------- | -------------------------------------------------------------------- |
@@ -78,7 +73,12 @@ const columns: PretableColumn<Person>[] = [
 ];
 ```
 
-The function form receives a `PretableEditInput` (`{ rowId, columnId, row, column, value }`) and may return a `Promise<boolean>`, so a permission check can hit the network before the editor opens. While an async `editable` is pending, the edit sits in the `checking` phase (see [Lifecycle](#lifecycle)); if it resolves `false`, the edit is cancelled and no editor appears.
+The function receives a `PretableEditInput` (`{ rowId, columnId, row, column,
+value }`) and may return a `Promise<boolean>`. While permission is resolving,
+the built-in editor appears read-only and busy in the `checking` phase. A
+`false` result closes the edit without saving. A rejected promise leaves an
+established editor open with an error; retry checks permission again. See
+[Lifecycle](#lifecycle).
 
 ## Typed editors
 
@@ -153,7 +153,7 @@ An `enum` column that declares `options` (the same `{ value, label? }[]` the [fi
 A custom `parseEditValue` remains authoritative. It receives the canonical value
 as text for an explicit selection, or the typed query for text entry.
 
-The strictness is the point: the combobox picks from the declared set, it doesn't create new members. For a creatable or multi-select control, use [`renderEditor`](#custom-editors).
+For a creatable or multi-select control, use [`renderEditor`](#custom-editors).
 
 An `enum` column with **no** `options` gets the plain text editor and no strictness — the draft commits as typed.
 
@@ -167,7 +167,7 @@ An `enum` column with **no** `options` gets the plain text editor and no strictn
 - **Month navigation.** `PageDown` / `PageUp` move forward and back a month, as do the **‹** and **›** buttons in the popover header. The day-of-month is clamped to the target month's length, so 31 January + 1 month is 28 (or 29) February. Navigation also clamps at `0000-01-01` and `9999-12-31`; out-of-range calendar slots are disabled placeholders rather than wrapped dates.
 - **Commit keys.** After intentional calendar navigation, Enter chooses the cursor date and commits down (Shift+Enter up). Otherwise Enter commits typed text. Tab always commits the typed/current draft, moving right (Shift+Tab left); it never accepts a merely browsed date. Clicking a day chooses it in place. Escape cancels.
 - **Blur commits or reverts.** Clicking away with a valid (or empty) field commits; clicking away with an unparseable date cancels the edit rather than leaving a rejected value stuck open on the cell.
-- **Focus never leaves the field.** The popover is a passive surface: it takes no focus, so the day cells are announced through `aria-activedescendant` on the input rather than by moving focus into the grid.
+- **Calendar navigation keeps focus in the field.** Day cells are announced through `aria-activedescendant` on the input rather than by moving focus into the grid.
 
 #### Browsing and text editing
 
@@ -203,7 +203,7 @@ normalized automatically.
   formatting](/docs/grid/date-formatting#migration).
 </Callout>
 
-Out of scope for the built-in editor, by design: time-of-day, date ranges, `min`/`max` bounds, and a configurable week start. Reach for [`renderEditor`](#custom-editors) — paired with `parseEditValue` and `formatEditValue` — when you need any of them.
+The built-in editor does not support time-of-day, date ranges, `min`/`max` bounds, and a configurable week start. Reach for [`renderEditor`](#custom-editors) — paired with `parseEditValue` and `formatEditValue` — when you need any of them.
 
 ### Overriding the built-ins
 
@@ -234,17 +234,30 @@ const columns: PretableColumn<Person>[] = [
 
 `validate(value, input)` receives the parsed value and the same `PretableEditInput`. A returned string keeps the edit open with `snapshot.editing.error` set to that message; a `Promise<true | string>` lets you validate against a server. Commit only proceeds to `onRowChange` once validation passes.
 
-On a [typed column](#typed-editors), built-in parsing runs first: by the time `validate` sees the value, a `number` column has already rejected non-numeric drafts ("Not a number") and turned an empty draft into `null`, an `enum` column with `options` has resolved the typed label to that option's `value` (rejecting anything that matches none), and a `date` column has rejected anything that isn't a real `YYYY-MM-DD` day ("Use YYYY-MM-DD") — so `validate` is for domain rules, not parsing.
+On a [typed column](#typed-editors), built-in parsing runs first: by the time `validate` sees the value, a `number` column has already rejected non-numeric drafts ("Not a number") and turned an empty draft into `null`, an `enum` column with `options` has resolved the typed label to that option's `value` (rejecting unmatched or ambiguous text), and a `date` column has rejected anything that isn't a real `YYYY-MM-DD` day ("Use YYYY-MM-DD") — so `validate` is for domain rules, not parsing.
 
 ## Custom editors
 
-To render your own editor instead of the [built-in one](#typed-editors) — a `<select>`, a date-range picker, a tag input — supply `renderEditor`. Pair it with `parseEditValue` (string → your value type) and `formatEditValue` (your value → the string the editor seeds from). **Priority** below stores a plain number, but its `<select>` only ever hands back a string on `onChange` — `formatEditValue` and `parseEditValue` bridge the two directions:
+Use [`components`](/docs/grid/components#replacing-a-component) when you want
+your own input or button with built-in editing behavior. Use `renderEditor`
+when you need a different editor, such as a native select or date-range picker.
 
-<Example id="custom-cell-editor" />
+A custom renderer owns its field's accessible name, pending presentation,
+error message, and commit/cancel keys. It does not receive the built-in error
+UI automatically. The controller still prevents draft writes and duplicate
+commits during pending work.
 
-Its column definition:
+This example uses a labelled `PriorityEditor` with pending and error feedback.
+Priority is stored as a number; `formatEditValue` and `parseEditValue` bridge it
+to the string used by a native select. Open the Code tab for the full editor.
+
+<Example id="custom-cell-editor" />
 
 ```tsx
+import type { PretableColumn } from "@pretable/react";
+import { PriorityEditor } from "./PriorityEditor";
+import type { Task } from "./data";
+
 const columns: PretableColumn<Task>[] = [
   {
     id: "priority",
@@ -252,33 +265,22 @@ const columns: PretableColumn<Task>[] = [
     editable: true,
     formatEditValue: (value) => String(value),
     parseEditValue: (raw) => Number(raw),
-    renderEditor: ({ draft, setDraft, commit, cancel }) => (
-      <select
-        autoFocus
-        value={String(draft ?? "")}
-        onChange={(e) => setDraft(e.target.value)}
-        onKeyDown={(e) => {
-          if (e.key === "Escape") cancel();
-        }}
-        onBlur={() => commit()}
-      >
-        <option value="1">Low</option>
-        <option value="2">Medium</option>
-        <option value="3">High</option>
-      </select>
-    ),
+    renderEditor: (input) => <PriorityEditor {...input} />,
   },
 ];
 ```
 
 `renderEditor` receives a `PretableEditorInput` — the edit input (`rowId`, `columnId`, `row`, `column`, `value`) plus the live draft controls:
 
-| Field      | Type                                           | Notes                                                                                      |
-| ---------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| `draft`    | `unknown`                                      | the current in-progress value                                                              |
-| `setDraft` | `(value: unknown) => void`                     | update the draft while editing; ignored during checking, validating, or saving             |
-| `commit`   | `(direction?: PretableFocusDirection) => void` | commit the draft, optionally moving focus; ignored while permission or a commit is pending |
-| `cancel`   | `() => void`                                   | discard the edit and restore the cell                                                      |
+| Field              | Type                                           | Notes                                                                                      |
+| ------------------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `draft`            | `unknown`                                      | the current in-progress value                                                              |
+| `setDraft`         | `(value: unknown) => void`                     | update the draft while editing; ignored during checking, validating, or saving             |
+| `commit`           | `(direction?: PretableFocusDirection) => void` | commit the draft, optionally moving focus; ignored while permission or a commit is pending |
+| `cancel`           | `() => void`                                   | discard the edit and restore the cell                                                      |
+| `status`           | `PretableEditStatus`                           | use checking, validating, and saving to present pending work                               |
+| `error`            | `string \| undefined`                          | render the message and associate it with your field                                        |
+| `seededFromTyping` | `boolean \| undefined`                         | true when typing started the edit; avoid selecting that initial character on focus         |
 
 `parseEditValue(raw, input)` turns the editor's string draft into the value handed to `validate` and `onRowChange`, replacing the built-in type parsing entirely. It may return the value or a promise of that value; the editor stays in `validating` until parsing completes. `formatEditValue(value, input)` produces the initial string shown when the editor opens. Supply both when your stored value isn't a plain string (an application-owned instant `Date`, an enum) so the custom edit round-trip stays type-correct. For an instant, the application must choose its calendar-zone projection; these hooks do not make the value eligible for built-in date processing.
 
@@ -288,14 +290,6 @@ const columns: PretableColumn<Task>[] = [
 
 A commit is **pessimistic**: the grid keeps showing the draft while the work runs. In controlled `rows` mode, resolving `onRowChange` alone does not clear the editor: the supplied rows must also reflect the accepted change. Until then the cell remains in `saving`. The edit moves through phases observable as `snapshot.editing.status`:
 
-```text
-checking → editing → validating → saving → (cleared)
-                ↑__________|              |
-              invalid (validate            |
-              returned a string)           ↓
-                                         error (callback failed)
-```
-
 | Phase        | Meaning                                                       |
 | ------------ | ------------------------------------------------------------- |
 | `checking`   | edit permission is resolving; the editor is read-only         |
@@ -306,9 +300,7 @@ checking → editing → validating → saving → (cleared)
 
 When `validate` returns a string the edit returns to `editing` with `snapshot.editing.error` set to that message. When `onRowChange` throws or rejects, the edit enters `error` (it does **not** clear) so you can surface the failure and let the user retry or cancel.
 
-`saving` and `error` are the two phases text on this page can only assert, not show — the field visibly goes read-only and `aria-busy` while a commit is in flight, and a rejection leaves the editor open with an inline message. That's exactly what happens in the grid at the top of this page when you edit **Quantity** to a negative number: the field dims for ~800ms (`saving`), then the commit is rejected with an inline message (`error`).
-
-For most apps the default editor handles all of this and you never touch the phases directly. If you render cells yourself (a custom `render`, or the [headless engine](/docs/headless)), read `grid.getState().editing` — `{ rowId, columnId, draft, status, error? }` — to drive your own in-cell editor or status affordance:
+For most apps the default editor handles all of this and you never touch the phases directly. For custom editing UI with the [headless engine](/docs/headless), read `grid.getState().editing` — `{ rowId, columnId, draft, status, error? }` — to drive your own in-cell editor or status affordance:
 
 ```tsx
 const { editing } = grid.getState();
@@ -354,22 +346,18 @@ Editing reuses the focused cell from the [selection](/docs/grid/selection) model
 | `PageUp` / `PageDown`  | editing (date)       | move the calendar back / forward a month                               |
 | `Escape`               | editing              | cancel — discard the draft, restore the cell                           |
 
-A begin trigger on a non-editable column is a no-op. Editable [boolean columns](#booleans) never open an editor: `Enter` and `Space` toggle in place, `F2` and type-to-replace do nothing, and `Escape` cancels a failed toggle. While an editor is open it owns keystrokes; `Enter`, `Tab`, and `Escape` are handled by the editor and don't fall through to grid navigation — as are `ArrowUp` / `ArrowDown` in the [number](#numbers) and [enum](#enums) editors, and calendar navigation keys in the [date](#dates) editor.
+Editing shortcuts apply to editable cells; otherwise the normal grid keyboard behavior applies. Editable [boolean columns](#booleans) never open an editor: `Enter` and `Space` toggle in place, `F2` and type-to-replace do nothing, and `Escape` cancels a failed toggle. While an editor is open it owns keystrokes; `Enter`, `Tab`, and `Escape` are handled by the editor and don't fall through to grid navigation — as are `ArrowUp` / `ArrowDown` in the [number](#numbers) and [enum](#enums) editors, and calendar navigation keys in the [date](#dates) editor.
+
+IME composition takes precedence over built-in editor and grid commands.
+Enter, Escape, Tab, and arrow events during composition retain browser behavior
+and do not save, cancel, step values, or start an edit. Custom editors must
+preserve composition behavior in their own key handlers.
 
 ## See also
 
+- [Components](/docs/grid/components) — replace built-in fields and action buttons.
 - [Filtering](/docs/grid/filtering) — the same `column.type` picks the filter operator family.
 - [Selection](/docs/grid/selection) — focus is the cell editing begins on.
 - [Keyboard](/docs/grid/keyboard) — the full keyboard contract.
 - [Headless engine](/docs/headless) — read `snapshot.editing` to build your own editor.
 - [API reference](/docs/grid/api-reference) — `PretableEditInput`, `PretableEditorInput`, `PretableEditState`, `PretableEditStatus` types.
-
-IME composition takes precedence over editor and grid commands. Enter,
-Escape, Tab and arrow events during composition retain browser behavior and
-do not save, cancel, step values or start an edit. Automated coverage includes
-composition events and the legacy key-code fallback; physical OS IME and human
-screen-reader validation are separate from those automated checks.
-
-The built-in fields resolve `components.TextInput` and `components.Textarea`;
-number/date action buttons resolve `components.IconButton`. Replacements must
-preserve native props, event handlers, ARIA/data hooks, and forwarded refs.
diff --git a/apps/website/content/docs/grid/keyboard.mdx b/apps/website/content/docs/grid/keyboard.mdx
index dbf796b5c..e27420a19 100644
--- a/apps/website/content/docs/grid/keyboard.mdx
+++ b/apps/website/content/docs/grid/keyboard.mdx
@@ -44,10 +44,29 @@ Every key the grid above responds to:
 | `Enter`                                        | Select the focused row as a full-width range; fires `onRowActivate`.                                                |
 | `Space`                                        | As `Enter`, and additionally ticks the row's checkbox when [`rowSelectionColumn`](/docs/grid/selection) is enabled. |
 
-Every row above describes the cursor on a **body** row. On a column header several of these keys mean something else — `Enter` and `Space` sort rather than select, `↓` re-enters the body, and `↑` has nowhere to go — so read [The column header](#the-column-header) alongside this table rather than in place of it.
+The table describes a **body** row when editing does not handle the key (see [Editing](#editing)). On a column header several of these keys mean something else — `Enter` and `Space` sort rather than select, `↓` re-enters the body, and `↑` has nowhere to go — so read [The column header](#the-column-header) alongside this table rather than in place of it.
 
 When [row grouping](/docs/grid/grouping#keyboard) is active the grid becomes a `treegrid`: on a group row `←` and `→` take on collapse and expand inside the group column, and `Enter` / `Space` toggles the group instead of selecting it.
 
+## Editing
+
+On an editable cell, Enter starts editing instead of activating the row. F2,
+double-click, and typing also begin an edit. Editable boolean cells toggle
+with Enter or Space; they do not open an editor.
+
+While a built-in editor is open, it handles keys before grid navigation:
+
+| Key                 | Effect                                                  |
+| ------------------- | ------------------------------------------------------- |
+| Enter / Shift+Enter | Save and move down / up                                 |
+| Tab / Shift+Tab     | Save and move right / left, regardless of `tabBehavior` |
+| Escape              | Cancel and return focus to the cell                     |
+
+In a multiline editor, Enter inserts a newline; Cmd/Ctrl+Enter saves. Number,
+enum, and date editors also handle their own navigation keys. IME composition
+retains browser behavior. See [Editing keyboard controls](/docs/grid/editing#keyboard)
+for those details. A custom `renderEditor` supplies its own key handlers.
+
 ## The column header
 
 The header is a row of the same focus model, reached with `↑` from the first data row rather than with `Tab`. While the cursor is on it:
diff --git a/apps/website/content/examples/components-button/BrandButton.tsx b/apps/website/content/examples/components-button/BrandButton.tsx
index 3d8cec1b5..9c210e250 100644
--- a/apps/website/content/examples/components-button/BrandButton.tsx
+++ b/apps/website/content/examples/components-button/BrandButton.tsx
@@ -4,10 +4,8 @@ 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.
+ * Replaces the kit's labelled actions. Preserve native props and the ref so
+ * the grid's handlers, accessible names, anchoring and focus still work.
  */
 export const BrandButton = forwardRef<HTMLButtonElement, PretableButtonProps>(
   function BrandButton({ site, variant, className, ...props }, ref) {
diff --git a/apps/website/content/examples/components-button/ComponentsGrid.tsx b/apps/website/content/examples/components-button/ComponentsGrid.tsx
index 81a6eb540..80065bc71 100644
--- a/apps/website/content/examples/components-button/ComponentsGrid.tsx
+++ b/apps/website/content/examples/components-button/ComponentsGrid.tsx
@@ -14,7 +14,7 @@ export function ComponentsGrid() {
   return (
     <div>
       <p style={{ margin: "0 0 8px", fontSize: 13 }}>
-        Every labelled button below is <code>BrandButton</code>; the icon
+        The kit’s labelled actions below use <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
diff --git a/apps/website/content/examples/components-editors/EditorControls.tsx b/apps/website/content/examples/components-editors/EditorControls.tsx
new file mode 100644
index 000000000..81a5953c2
--- /dev/null
+++ b/apps/website/content/examples/components-editors/EditorControls.tsx
@@ -0,0 +1,60 @@
+import { forwardRef } from "react";
+import type {
+  PretableIconButtonProps,
+  PretableTextareaProps,
+  PretableTextInputProps,
+} from "@pretable/react";
+
+// Keep these component identities stable: defining them inside the grid
+// would remount the active editor each time the parent renders.
+export const AppTextInput = forwardRef<
+  HTMLInputElement,
+  PretableTextInputProps
+>(function AppTextInput({ site, className, ...props }, ref) {
+  return (
+    <input
+      {...props}
+      ref={ref}
+      className={["app-editor-input", className].filter(Boolean).join(" ")}
+      data-pretable-text-input=""
+      data-pretable-site={site}
+    />
+  );
+});
+
+export const AppTextarea = forwardRef<
+  HTMLTextAreaElement,
+  PretableTextareaProps
+>(function AppTextarea({ site, className, ...props }, ref) {
+  return (
+    <textarea
+      {...props}
+      ref={ref}
+      className={["app-editor-textarea", className].filter(Boolean).join(" ")}
+      data-pretable-textarea=""
+      data-pretable-site={site}
+    />
+  );
+});
+
+export const AppIconButton = forwardRef<
+  HTMLButtonElement,
+  PretableIconButtonProps
+>(function AppIconButton({ site, className, ...props }, ref) {
+  return (
+    <button
+      {...props}
+      ref={ref}
+      type="button"
+      className={["app-editor-icon-button", className]
+        .filter(Boolean)
+        .join(" ")}
+      data-pretable-icon-button=""
+      data-pretable-site={site}
+    />
+  );
+});
+
+// The spread preserves value, native handlers (including composition),
+// disabled, ARIA attributes, data attributes, children, and inline styles.
+// The kit attributes above keep @pretable/ui's layout and state styling.
diff --git a/apps/website/content/examples/components-editors/EditorControlsGrid.tsx b/apps/website/content/examples/components-editors/EditorControlsGrid.tsx
new file mode 100644
index 000000000..4c5cedcc6
--- /dev/null
+++ b/apps/website/content/examples/components-editors/EditorControlsGrid.tsx
@@ -0,0 +1,90 @@
+"use client";
+
+import { useState } from "react";
+import { PretableSurface, type PretableColumn } from "@pretable/react";
+
+import { AppIconButton, AppTextarea, AppTextInput } from "./EditorControls";
+import "./editor-controls.css";
+
+interface Item {
+  id: string;
+  name: string;
+  quantity: number | null;
+  notes: string;
+}
+
+const initialRows: Item[] = [
+  {
+    id: "notebook",
+    name: "Notebook",
+    quantity: 4,
+    notes: "Dot grid\nRecycled paper",
+  },
+  { id: "pencil", name: "Pencil", quantity: 12, notes: "Pack of twelve" },
+  { id: "folder", name: "Folder", quantity: 6, notes: "For project notes" },
+];
+
+const columns: PretableColumn<Item>[] = [
+  { id: "name", header: "Name", editable: true, widthPx: 170 },
+  {
+    id: "quantity",
+    header: "Quantity",
+    type: "number",
+    editable: true,
+    widthPx: 150,
+  },
+  { id: "notes", header: "Notes", editable: true, wrap: true, widthPx: 270 },
+];
+
+export function EditorControlsGrid() {
+  const [rows, setRows] = useState(initialRows);
+  const [status, setStatus] = useState(
+    "Ready to edit. Saves take about 800ms.",
+  );
+
+  return (
+    <div>
+      <p style={{ margin: "0 0 12px", fontSize: 13 }}>
+        Double-click a cell or select it and press <kbd>F2</kbd>. Try the
+        Quantity stepper, then enter <strong>-1</strong> and press{" "}
+        <kbd>Enter</kbd> to see a rejected save. Correct the value and press{" "}
+        <kbd>Enter</kbd> again. In Notes, <kbd>Enter</kbd> adds a line;{" "}
+        <kbd>Ctrl</kbd> / <kbd>Cmd</kbd> + <kbd>Enter</kbd> saves.{" "}
+        <kbd>Escape</kbd> cancels.
+      </p>
+      <PretableSurface
+        ariaLabel="Inventory with custom editors"
+        rows={rows}
+        columns={columns}
+        getRowId={(row) => row.id}
+        viewportHeight={230}
+        components={{
+          TextInput: AppTextInput,
+          Textarea: AppTextarea,
+          IconButton: AppIconButton,
+        }}
+        onRowChange={async ({ rowId, columnId, value, row }) => {
+          setStatus(`Saving ${columnId}…`);
+          await new Promise<void>((resolve) => setTimeout(resolve, 800));
+          if (
+            columnId === "quantity" &&
+            typeof value === "number" &&
+            value < 0
+          ) {
+            setStatus(
+              "Quantity rejected. Correct it and press Enter to retry.",
+            );
+            throw new Error("Quantity must be zero or greater");
+          }
+          setRows((current) =>
+            current.map((item) => (item.id === rowId ? row : item)),
+          );
+          setStatus(`Saved ${columnId}.`);
+        }}
+      />
+      <p role="status" style={{ margin: "8px 0 0", fontSize: 13 }}>
+        {status}
+      </p>
+    </div>
+  );
+}
diff --git a/apps/website/content/examples/components-editors/demo.tsx b/apps/website/content/examples/components-editors/demo.tsx
new file mode 100644
index 000000000..4ce2ac09e
--- /dev/null
+++ b/apps/website/content/examples/components-editors/demo.tsx
@@ -0,0 +1,5 @@
+import { EditorControlsGrid } from "./EditorControlsGrid";
+
+export default function Demo() {
+  return <EditorControlsGrid />;
+}
diff --git a/apps/website/content/examples/components-editors/editor-controls.css b/apps/website/content/examples/components-editors/editor-controls.css
new file mode 100644
index 000000000..cc4a57e87
--- /dev/null
+++ b/apps/website/content/examples/components-editors/editor-controls.css
@@ -0,0 +1,16 @@
+/* Keep the skin's editor sizing, focus, saving, and invalid states. */
+.app-editor-input,
+.app-editor-textarea {
+  border-radius: 6px;
+  font-family: inherit;
+  background: color-mix(in srgb, var(--pretable-bg-grid) 94%, #0d9488);
+}
+
+.app-editor-icon-button {
+  border-radius: 4px;
+  color: var(--pretable-accent);
+}
+
+.app-editor-icon-button:not(:disabled):hover {
+  background: color-mix(in srgb, var(--pretable-bg-grid) 85%, #0d9488);
+}
diff --git a/apps/website/content/examples/components-editors/example.ts b/apps/website/content/examples/components-editors/example.ts
new file mode 100644
index 000000000..7eafa4502
--- /dev/null
+++ b/apps/website/content/examples/components-editors/example.ts
@@ -0,0 +1,12 @@
+import { defineExample } from "../../../lib/docs/examples/define";
+
+export default defineExample({
+  title: "Use your own editor controls",
+  description:
+    "Native input, textarea, and icon-button replacements preserve built-in editing, including a number stepper, multiline drafts, and delayed saves with a corrected retry.",
+  files: [
+    "EditorControlsGrid.tsx",
+    "EditorControls.tsx",
+    "editor-controls.css",
+  ],
+});
diff --git a/apps/website/content/examples/custom-cell-editor/CustomEditorGrid.tsx b/apps/website/content/examples/custom-cell-editor/CustomEditorGrid.tsx
index 4588782f3..a0b8d1aab 100644
--- a/apps/website/content/examples/custom-cell-editor/CustomEditorGrid.tsx
+++ b/apps/website/content/examples/custom-cell-editor/CustomEditorGrid.tsx
@@ -15,11 +15,10 @@ export function CustomEditorGrid() {
   return (
     <div>
       <p style={{ margin: "0 0 8px", fontSize: 13 }}>
-        <strong>Title</strong> uses the built-in text editor. Double-click (or
-        press <kbd>Enter</kbd>) on a <strong>Priority</strong> cell to open the
-        custom <code>renderEditor</code> below — a plain
-        <code>{"<select>"}</code>, bridged to the numeric stored value by{" "}
-        <code>formatEditValue</code> and <code>parseEditValue</code>.
+        Edit Priority for Draft proposal, choose High, and press Enter to see a
+        rejected save. Choose Medium or Low to retry. Enter/Shift+Enter save
+        down/up; Tab/Shift+Tab save right/left. Escape cancels before saving.
+        Leaving the field saves in place.
       </p>
       <PretableSurface<Task>
         ariaLabel="Tasks"
@@ -27,7 +26,11 @@ export function CustomEditorGrid() {
         getRowId={(row) => row.id}
         rows={rows}
         viewportHeight={VIEWPORT_HEIGHT}
-        onRowChange={({ rowId, row }) => {
+        onRowChange={async ({ rowId, columnId, row }) => {
+          await new Promise((resolve) => setTimeout(resolve, 600));
+          if (columnId === "priority" && rowId === "t1" && row.priority === 3) {
+            throw new Error("Choose Medium or Low for the proposal.");
+          }
           setRows((previous) =>
             previous.map((candidate) =>
               candidate.id === rowId ? row : candidate,
diff --git a/apps/website/content/examples/custom-cell-editor/PriorityEditor.tsx b/apps/website/content/examples/custom-cell-editor/PriorityEditor.tsx
new file mode 100644
index 000000000..e8d48b7f1
--- /dev/null
+++ b/apps/website/content/examples/custom-cell-editor/PriorityEditor.tsx
@@ -0,0 +1,113 @@
+import { useId, useRef } from "react";
+import type { PretableEditorInput } from "@pretable/react";
+
+import type { Task } from "./data";
+
+// Keep the component at module scope so changing the draft preserves focus.
+export function PriorityEditor({
+  draft,
+  setDraft,
+  status,
+  error,
+  commit,
+  cancel,
+}: PretableEditorInput<Task>) {
+  const errorId = useId();
+  const composing = useRef(false);
+  const skipBlur = useRef(false);
+  const pending =
+    status === "checking" || status === "validating" || status === "saving";
+
+  return (
+    <div
+      style={{ width: "100%", display: "flex", alignItems: "center", gap: 8 }}
+    >
+      <select
+        autoFocus
+        aria-label="Priority"
+        aria-busy={pending || undefined}
+        aria-disabled={pending || undefined}
+        aria-invalid={error ? true : undefined}
+        aria-errormessage={error ? errorId : undefined}
+        aria-describedby={error ? errorId : undefined}
+        value={String(draft ?? "")}
+        style={{ width: 84, flexShrink: 0 }}
+        // A select has no readOnly. Keep it focusable while guarding changes.
+        onPointerDown={(event) => {
+          if (pending) event.preventDefault();
+        }}
+        onChange={(event) => {
+          if (!pending) {
+            skipBlur.current = false;
+            setDraft(event.target.value);
+          }
+        }}
+        onCompositionStart={() => {
+          composing.current = true;
+        }}
+        onCompositionEnd={() => {
+          composing.current = false;
+        }}
+        onKeyDown={(event) => {
+          event.stopPropagation();
+          if (
+            composing.current ||
+            event.nativeEvent.isComposing ||
+            event.nativeEvent.keyCode === 229
+          )
+            return;
+          if (pending) {
+            event.preventDefault();
+          } else if (event.key === "Escape") {
+            event.preventDefault();
+            skipBlur.current = true;
+            cancel();
+          } else if (event.key === "Enter" || event.key === "Tab") {
+            event.preventDefault();
+            skipBlur.current = true;
+            commit(
+              event.key === "Tab"
+                ? event.shiftKey
+                  ? "left"
+                  : "right"
+                : event.shiftKey
+                  ? "up"
+                  : "down",
+            );
+          }
+          // Arrow keys remain native option navigation; they never commit.
+        }}
+        onBlur={() => {
+          if (!skipBlur.current && status === "editing") commit();
+          skipBlur.current = false;
+        }}
+      >
+        <option value="1">Low</option>
+        <option value="2">Medium</option>
+        <option value="3">High</option>
+      </select>
+      {pending && (
+        <small role="status">
+          {status === "checking"
+            ? "Checking…"
+            : status === "validating"
+              ? "Validating…"
+              : "Saving…"}
+        </small>
+      )}
+      {/* renderEditor replaces the built-in error UI, so render it here. */}
+      {error && (
+        <small
+          id={errorId}
+          role="alert"
+          style={{
+            whiteSpace: "nowrap",
+            color: "var(--pretable-text-error, #b42318)",
+          }}
+        >
+          {error}
+        </small>
+      )}
+    </div>
+  );
+}
diff --git a/apps/website/content/examples/custom-cell-editor/__tests__/editor.test.tsx b/apps/website/content/examples/custom-cell-editor/__tests__/editor.test.tsx
new file mode 100644
index 000000000..6bff19574
--- /dev/null
+++ b/apps/website/content/examples/custom-cell-editor/__tests__/editor.test.tsx
@@ -0,0 +1,91 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import type { PretableEditorInput } from "@pretable/react";
+
+import { columns } from "../columns";
+import { tasks, type Task } from "../data";
+
+function setup(overrides: Partial<PretableEditorInput<Task>> = {}) {
+  const input = {
+    row: tasks[0],
+    rowId: "t1",
+    columnId: "priority",
+    column: columns[1],
+    value: 2,
+    draft: "2",
+    status: "editing",
+    setDraft: vi.fn(),
+    commit: vi.fn(),
+    cancel: vi.fn(),
+    ...overrides,
+  } as PretableEditorInput<Task>;
+  render(columns[1]!.renderEditor!(input));
+  return { input, field: screen.getByRole("combobox", { name: "Priority" }) };
+}
+
+describe("custom priority editor", () => {
+  it("labels the field, associates rendered errors, and keeps drafts as strings", () => {
+    const { input, field } = setup({ error: "Choose Medium or Low." });
+    expect(field).toHaveFocus();
+    expect(field).toHaveAttribute("aria-invalid", "true");
+    expect(
+      document.getElementById(field.getAttribute("aria-errormessage")!),
+    ).toHaveTextContent("Choose Medium or Low.");
+    fireEvent.change(field, { target: { value: "1" } });
+    expect(input.setDraft).toHaveBeenCalledWith("1");
+    expect(screen.getByRole("alert")).toHaveTextContent(
+      "Choose Medium or Low.",
+    );
+  });
+
+  it.each(["checking", "validating", "saving"] as const)(
+    "guards edits and commits while %s",
+    (status) => {
+      const { input, field } = setup({ status });
+      expect(field).toHaveAttribute("aria-busy", "true");
+      expect(field).toHaveAttribute("aria-disabled", "true");
+      expect(screen.getByRole("status")).toHaveTextContent(
+        new RegExp(status, "i"),
+      );
+      fireEvent.change(field, { target: { value: "1" } });
+      expect(field).toHaveValue("2");
+      fireEvent.keyDown(field, { key: "Enter" });
+      fireEvent.keyDown(field, { key: "Escape" });
+      fireEvent.blur(field);
+      expect(input.setDraft).not.toHaveBeenCalled();
+      expect(input.commit).not.toHaveBeenCalled();
+      expect(input.cancel).not.toHaveBeenCalled();
+    },
+  );
+
+  it.each([
+    ["Enter", false, "down"],
+    ["Enter", true, "up"],
+    ["Tab", false, "right"],
+    ["Tab", true, "left"],
+  ])("commits %s with shift=%s toward %s", (key, shiftKey, direction) => {
+    const { input, field } = setup();
+    fireEvent.keyDown(field, { key, shiftKey });
+    fireEvent.blur(field);
+    expect(input.commit).toHaveBeenCalledExactlyOnceWith(direction);
+  });
+
+  it("cancels without a blur save and leaves arrow keys native", () => {
+    const { input, field } = setup();
+    expect(fireEvent.keyDown(field, { key: "ArrowDown" })).toBe(true);
+    expect(input.commit).not.toHaveBeenCalled();
+    fireEvent.keyDown(field, { key: "Escape" });
+    fireEvent.blur(field);
+    expect(input.cancel).toHaveBeenCalledOnce();
+    expect(input.commit).not.toHaveBeenCalled();
+  });
+
+  it("ignores composition commands and commits ordinary blur in place", () => {
+    const { input, field } = setup();
+    fireEvent.keyDown(field, { key: "Enter", isComposing: true });
+    fireEvent.keyDown(field, { key: "Enter", keyCode: 229 });
+    expect(input.commit).not.toHaveBeenCalled();
+    fireEvent.blur(field);
+    expect(input.commit).toHaveBeenCalledExactlyOnceWith();
+  });
+});
diff --git a/apps/website/content/examples/custom-cell-editor/columns.tsx b/apps/website/content/examples/custom-cell-editor/columns.tsx
index 9f1f8e3e6..890ac21c9 100644
--- a/apps/website/content/examples/custom-cell-editor/columns.tsx
+++ b/apps/website/content/examples/custom-cell-editor/columns.tsx
@@ -1,6 +1,7 @@
 import type { PretableColumn } from "@pretable/react";
 
 import type { Task } from "./data";
+import { PriorityEditor } from "./PriorityEditor";
 
 const PRIORITY_LABEL: Record<number, string> = {
   1: "Low",
@@ -14,27 +15,13 @@ export const columns: PretableColumn<Task>[] = [
     id: "priority",
     header: "Priority",
     editable: true,
-    widthPx: 130,
+    widthPx: 360,
     render: ({ row }) => PRIORITY_LABEL[row.priority] ?? String(row.priority),
     // The stored value is a number; a native <select> only ever hands back
     // strings on change, so formatEditValue seeds the draft as a string and
     // parseEditValue converts it back on commit.
     formatEditValue: (value) => String(value),
     parseEditValue: (raw) => Number(raw),
-    renderEditor: ({ draft, setDraft, commit, cancel }) => (
-      <select
-        autoFocus
-        value={String(draft ?? "")}
-        onChange={(e) => setDraft(e.target.value)}
-        onKeyDown={(e) => {
-          if (e.key === "Escape") cancel();
-        }}
-        onBlur={() => commit()}
-      >
-        <option value="1">Low</option>
-        <option value="2">Medium</option>
-        <option value="3">High</option>
-      </select>
-    ),
+    renderEditor: (input) => <PriorityEditor {...input} />,
   },
 ];
diff --git a/apps/website/content/examples/custom-cell-editor/example.ts b/apps/website/content/examples/custom-cell-editor/example.ts
index 2650fda75..6466a1aa5 100644
--- a/apps/website/content/examples/custom-cell-editor/example.ts
+++ b/apps/website/content/examples/custom-cell-editor/example.ts
@@ -4,5 +4,10 @@ export default defineExample({
   title: "Custom cell editor",
   description:
     "A renderEditor select bridges a numeric priority column to and from the string a native control hands back, via formatEditValue and parseEditValue.",
-  files: ["CustomEditorGrid.tsx", "columns.tsx", "data.ts"],
+  files: [
+    "CustomEditorGrid.tsx",
+    "PriorityEditor.tsx",
+    "columns.tsx",
+    "data.ts",
+  ],
 });
diff --git a/apps/website/e2e/custom-editor-docs.spec.ts b/apps/website/e2e/custom-editor-docs.spec.ts
new file mode 100644
index 000000000..a36ce460d
--- /dev/null
+++ b/apps/website/e2e/custom-editor-docs.spec.ts
@@ -0,0 +1,82 @@
+import { expect, test, type Locator } from "@playwright/test";
+
+async function expectFeedbackInsideCell(feedback: Locator) {
+  const bounds = await feedback.evaluate((element) => {
+    const cell = element.closest("[data-pretable-column-id]")!;
+    const outer = cell.getBoundingClientRect();
+    const range = document.createRange();
+    range.selectNodeContents(element);
+    const text = range.getBoundingClientRect();
+    return {
+      fits:
+        text.left >= outer.left &&
+        text.right <= outer.right &&
+        text.top >= outer.top &&
+        text.bottom <= outer.bottom,
+      text: {
+        left: text.left,
+        right: text.right,
+        top: text.top,
+        bottom: text.bottom,
+      },
+      cell: {
+        left: outer.left,
+        right: outer.right,
+        top: outer.top,
+        bottom: outer.bottom,
+      },
+    };
+  });
+  expect(
+    bounds,
+    `Feedback text must fit inside the grid cell: ${JSON.stringify(bounds)}`,
+  ).toMatchObject({ fits: true });
+}
+
+test("custom priority select shows a failed save and accepts a corrected numeric value", async ({
+  page,
+}) => {
+  await page.goto("/docs/grid/editing", { waitUntil: "domcontentloaded" });
+  const example = page
+    .locator("figure")
+    .filter({ has: page.getByText("Custom cell editor", { exact: true }) });
+  await example.scrollIntoViewIfNeeded();
+  await expect(
+    example.locator("[data-pretable-scroll-viewport]"),
+  ).toHaveAttribute("data-pretable-hydrated", "true");
+  const cell = example.locator(
+    '[data-pretable-row-id="t1"] [data-pretable-column-id="priority"]',
+  );
+  await expect(cell).toHaveText("Medium");
+  await cell.click();
+  await page.keyboard.press("F2");
+  const editor = example.getByRole("combobox", { name: "Priority" });
+  await expect(editor).toBeFocused();
+  await editor.selectOption("3");
+  await editor.press("Enter");
+  await expect(editor).toHaveAttribute("aria-busy", "true");
+  await expect(
+    example.getByRole("status").filter({ hasText: "Saving…" }),
+  ).toHaveText("Saving…");
+  await expectFeedbackInsideCell(
+    example.getByRole("status").filter({ hasText: "Saving…" }),
+  );
+  await expect(example.getByRole("alert")).toHaveText(
+    "Choose Medium or Low for the proposal.",
+  );
+  await expectFeedbackInsideCell(example.getByRole("alert"));
+  await expect(editor).toHaveValue("3");
+  await expect(editor).toHaveAttribute("aria-invalid", "true");
+  await editor.selectOption("1");
+  await editor.press("Enter");
+  await expect(editor).toHaveCount(0);
+  await expect(cell).toHaveText("Low");
+  await expect(example.getByRole("alert")).toHaveCount(0);
+  await cell.click();
+  await page.keyboard.press("F2");
+  await expect(editor).toHaveValue("1");
+  await editor.selectOption("2");
+  await editor.press("Escape");
+  await expect(editor).toHaveCount(0);
+  await expect(cell).toHaveText("Low");
+});
diff --git a/apps/website/e2e/editor-slots-docs.spec.ts b/apps/website/e2e/editor-slots-docs.spec.ts
new file mode 100644
index 000000000..6407cd58e
--- /dev/null
+++ b/apps/website/e2e/editor-slots-docs.spec.ts
@@ -0,0 +1,80 @@
+import { expect, test, type Page } from "@playwright/test";
+
+const grid = (page: Page) =>
+  page.getByRole("grid", {
+    name: "Inventory with custom editors",
+    exact: true,
+  });
+const cell = (page: Page, column: string) =>
+  grid(page).locator(
+    `[data-pretable-row-id="notebook"] [data-pretable-column-id="${column}"]`,
+  );
+const field = (page: Page) => grid(page).locator(".pretable-cell-editor");
+
+async function edit(page: Page, column: string) {
+  await cell(page, column).click();
+  await page.keyboard.press("F2");
+  await expect(field(page)).toBeFocused();
+}
+
+test.beforeEach(async ({ page }) => {
+  await page.goto("/docs/grid/components");
+  // Previews mount when their figure enters the viewport.
+  await page
+    .locator("figure")
+    .filter({
+      has: page
+        .getByRole("link", { name: ".md", exact: true })
+        .and(page.locator('[href="/examples/components-editors.md"]')),
+    })
+    .scrollIntoViewIfNeeded();
+  await grid(page).scrollIntoViewIfNeeded();
+  await expect(grid(page)).toHaveAttribute("data-pretable-hydrated", "true");
+});
+
+test("custom editor controls retain focus, steppers, saving errors and corrected retry", async ({
+  page,
+}) => {
+  await edit(page, "quantity");
+  await expect(field(page)).toHaveClass(/app-editor-input/);
+  const increment = grid(page).getByRole("button", {
+    name: "Increment",
+    exact: true,
+  });
+  await expect(increment).toHaveClass(/app-editor-icon-button/);
+  await increment.click();
+  await expect(field(page)).toHaveValue("5");
+  await expect(field(page)).toBeFocused();
+  await field(page).fill("-1");
+  await field(page).press("Enter");
+  await expect(field(page)).toHaveAttribute("aria-busy", "true");
+  await expect(field(page)).toHaveAttribute("aria-invalid", "true");
+  await expect(
+    grid(page).locator("[data-pretable-edit-error]"),
+  ).toHaveAttribute("title", "Quantity must be zero or greater");
+  await expect(field(page)).toHaveValue("-1");
+  await field(page).fill("7");
+  await field(page).press("Enter");
+  await expect(field(page)).toHaveCount(0);
+  await expect(cell(page, "quantity")).toHaveText("7");
+});
+
+test("replacement input cancels and textarea preserves multiline editing", async ({
+  page,
+}) => {
+  await edit(page, "name");
+  await field(page).fill("Unsaved name");
+  await field(page).press("Escape");
+  await expect(cell(page, "name")).toHaveText("Notebook");
+  await edit(page, "notes");
+  await expect(field(page)).toHaveClass(/app-editor-textarea/);
+  await field(page).fill("First line");
+  await field(page).press("End");
+  await field(page).press("Enter");
+  await page.keyboard.type("Second line");
+  await expect(field(page)).toHaveValue("First line\nSecond line");
+  await field(page).press("Control+Enter");
+  await expect(field(page)).toHaveCount(0);
+  await edit(page, "notes");
+  await expect(field(page)).toHaveValue("First line\nSecond line");
+});
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 c2e3b3505..fcdffe2cb 100644
--- a/apps/website/lib/docs/__tests__/docs-api-surface.test.ts
+++ b/apps/website/lib/docs/__tests__/docs-api-surface.test.ts
@@ -1397,7 +1397,7 @@ const TABLES: Record<string, TableBinding> = {
     types: [{ pkg: "react", name: "PretableCheckboxProps" }],
     complete: true,
   },
-  "grid/components.mdx#Replacing a component": {
+  "grid/components.mdx#The components": {
     types: [{ pkg: "react", name: "PretableComponents" }],
     complete: true,
   },
@@ -1611,7 +1611,7 @@ const MEMBER_TABLE_TYPES: Record<string, true | string> = {
   "grid/components.mdx#Select": true,
   "grid/components.mdx#TextInput": true,
   "grid/components.mdx#Checkbox": true,
-  "grid/components.mdx#Replacing a component": true,
+  "grid/components.mdx#The components": true,
 };
 
 /**
diff --git a/apps/website/lib/docs/examples/demos.generated.ts b/apps/website/lib/docs/examples/demos.generated.ts
index ebf9543d3..2d1f40979 100644
--- a/apps/website/lib/docs/examples/demos.generated.ts
+++ b/apps/website/lib/docs/examples/demos.generated.ts
@@ -12,6 +12,7 @@ import cellPresentationsDemo from "../../../content/examples/cell-presentations/
 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 componentsEditorsDemo from "../../../content/examples/components-editors/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";
@@ -57,6 +58,7 @@ export const exampleDemos: Partial<Record<ExampleId, ComponentType>> = {
   "column-filters": columnFiltersDemo,
   "column-layout": columnLayoutDemo,
   "components-button": componentsButtonDemo,
+  "components-editors": componentsEditorsDemo,
   "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 95f1ed06c..33430833c 100644
--- a/apps/website/lib/docs/examples/registry.generated.ts
+++ b/apps/website/lib/docs/examples/registry.generated.ts
@@ -8,6 +8,7 @@ import cellPresentations from "../../../content/examples/cell-presentations/exam
 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 componentsEditors from "../../../content/examples/components-editors/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";
@@ -69,6 +70,10 @@ export const exampleRegistry = {
     meta: componentsButton,
     hasDemo: true,
   },
+  "components-editors": {
+    meta: componentsEditors,
+    hasDemo: true,
+  },
   "csv-clipboard-copy": {
     meta: csvClipboardCopy,
     hasDemo: false,
diff --git a/docs/superpowers/plans/2026-09-09-component-kit-docs.md b/docs/superpowers/plans/2026-09-09-component-kit-docs.md
new file mode 100644
index 000000000..ab3c96407
--- /dev/null
+++ b/docs/superpowers/plans/2026-09-09-component-kit-docs.md
@@ -0,0 +1,20 @@
+# Component Kit Documentation Implementation Plan
+
+> **For agentic workers:** Use superpowers:subagent-driven-development for independent example work and review.
+
+**Goal:** Make the component kit documentation accurate, approachable, and supported by complete examples.
+
+**Architecture:** Documentation changes stay in the website. Two examples distinguish control replacement from custom editing; no public runtime behavior changes.
+
+**Tech Stack:** MDX, React, TypeScript, Next.js, Playwright.
+
+- [x] Repair `content/examples/custom-cell-editor/`: introduce a named custom editor with pending and error UI, retain numeric conversion, register all source files, and verify its save/cancel/error interactions.
+- [x] Add `content/examples/components-editors/`: native input/textarea/action replacements at module scope, controlled rows and a delayed quantity rejection, concise scoped CSS, definition and demo modules.
+- [x] Rewrite `content/docs/grid/components.mdx` with decision table, minimal replacement, examples, compact API inventory, styling selectors, overlay guidance and migration notes.
+- [x] Edit `content/docs/grid/editing.mdx`, `keyboard.mdx`, and `api-reference.mdx`: correct permission behavior, document custom editor responsibility and fields, link customization, simplify lifecycle, and remove repetition.
+- [x] Correct the existing Button example's misleading caption and ref-only contract comment.
+- [x] Generate the example registry with `pnpm --filter @pretable/app-website examples:gen`; run website typecheck, lint, Vitest and build using the pinned toolchain.
+- [x] Add and run focused browser checks for the actual documentation examples, including pending/error, corrected retry, multiline editing, native refs and actions.
+- [ ] Review the diff and rendered docs, create a PR, verify its deployment in Chrome, merge after required checks pass, and verify production with Chrome.
+
+Paths above are relative to `apps/website/`. Use `PATH=/tmp/pretable-kit-bin:$PATH pnpm` for local commands. The working branch is `blove/component-kit-docs` in the existing isolated worktree.
diff --git a/docs/superpowers/specs/2026-09-09-component-kit-docs-design.md b/docs/superpowers/specs/2026-09-09-component-kit-docs-design.md
new file mode 100644
index 000000000..a67b3caa6
--- /dev/null
+++ b/docs/superpowers/specs/2026-09-09-component-kit-docs-design.md
@@ -0,0 +1,11 @@
+# Component kit documentation
+
+The approved audit recommendation is to correct factual gaps, repair the custom-editor example, add one editor-control replacement example, and restructure and trim the guides. Keep the public runtime API unchanged.
+
+Readers should first choose tokens (appearance), components (native control replacement while keeping editor behavior), or renderEditor (application-owned editing). Components should show a minimal replacement before its reference inventory. Preserve advanced overlay and native-control contracts in concise reference sections.
+
+Add a small editable grid with module-scope TextInput, Textarea, and IconButton replacements, controlled rows, a delayed save, and a rejected quantity. Preserve supplied native props, handlers, ARIA attributes, styles/classes, and refs. The existing custom select example must supply a label, pending feedback, error association, cancellation and commit behavior. Document that custom renderers own those UI responsibilities.
+
+Correct permission-check visibility, expose kit APIs in the website index, and explain editing exceptions in Keyboard. Consolidate repeated inventories, lifecycle descriptions, and warnings; place composition before See also. Retain canonical date/enum value contracts.
+
+Validate example interactions in automated browser checks, registry consistency, website types/lint/tests/build, and Chrome on the deployed site. Follow the user's existing PR and merge-on-green authorization.