From 85964533c18b2751590f56d5938f7751220e7a15 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sun, 30 Aug 2026 07:50:18 -0700
Subject: [PATCH 01/11] docs: tool-panel pane-resize + auto-width design (SP5)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../2026-08-30-tool-panel-resize-autosize.md  | 163 ++++++++++++++++++
 1 file changed, 163 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-08-30-tool-panel-resize-autosize.md

diff --git a/docs/superpowers/specs/2026-08-30-tool-panel-resize-autosize.md b/docs/superpowers/specs/2026-08-30-tool-panel-resize-autosize.md
new file mode 100644
index 00000000..45e0745a
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-30-tool-panel-resize-autosize.md
@@ -0,0 +1,163 @@
+# Pane Resizing + Auto Width (Tool Panel SP5) — Design
+
+**Status:** approved direction, specced in full.
+**Parents:** `2026-08-24-tool-panel-design.md` — both items sit on SP1's
+out-of-scope-but-designed-for list: "panel width resizing" and "column
+autosize action in the kebab (menu is built to take it later)".
+
+## What this is
+
+Two finishing touches on the tool panel, one PR:
+
+- **A. Pane width resizing** — a drag handle on the pane's grid-side edge,
+  with keyboard parity, bounds, and the surface's controlled/uncontrolled
+  convention.
+- **B. Auto width in the columns section** — the kebab gains an "Auto
+  width" toggle per column, and the section footer gains "Auto-size all
+  columns", both over the auto-width machinery that already exists.
+
+## Facts the design rests on (verified in code)
+
+1. Pane width is a plain `inline-size: 264px` at (0,0,0) specificity in
+   `grid.css` (~1462), documented as consumer-overridable; the pane is a
+   "fixed budget the grid area yields", and the virtualizer already
+   observes resize (SP1).
+2. Auto width is a **live set**, not a one-shot fit:
+   `createAutoWidthStore` (pretable-model.ts) holds the set of column ids
+   in auto mode; columns with no declared `widthPx` START auto; the
+   renderer sizes auto columns from content continuously.
+   `autosizeColumns()` on the handle = set ALL columns auto;
+   `setColumnWidth(id, px)` flips that column to manual. There is no
+   public per-column auto setter yet.
+3. The pane's keyboard walks (columns, grouping, custom-section e2e) pin
+   tab-stop rosters, and the tab-exit guard is a hard gate — a new
+   focusable in the pane moves rosters deliberately, never accidentally.
+
+## Decisions — A. Pane resizing
+
+A1. **The handle is the pane's inline-start edge** (the pane/grid seam): a
+slim grab strip (`data-pretable-pane-resize`), full pane height,
+≥24px hit area on coarse pointers via the established coarse-pointer
+hit-area pattern. Zero new tokens; the visible affordance reuses
+existing rule/hover tokens.
+
+A2. **Live resize, pointer-captured, Escape-cancels.** Capture at
+pointerdown (the recorded rAF-coalescing lesson); width applies
+continuously during the drag (chrome-cheap; the grid reflows through
+the virtualizer's resize observer); Escape mid-drag restores the
+drag-start width; release commits. Double-click resets to the default
+width.
+
+A3. **State is React chrome state with the surface's assert-and-report
+trio**: `defaultPaneWidthPx?` / `paneWidthPx?` / `onPaneWidthChange?`
+on `PretableToolPanelConfig` — the same controlled/uncontrolled
+contract as `activeSection` (SP1 decision 5: chrome state is
+React-owned; engine state would be dead surface for headless
+consumers). Rejected: uncontrolled-only — cheaper, but it breaks the
+surface's otherwise-universal convention for interactive chrome, and
+a persisted-layout consumer needs the controlled form.
+
+A4. **Bounds, clamped everywhere**: a `MIN` floor (exact px chosen at
+implementation by measuring the filters section's narrowest usable
+row — the spec's rule, not a magic number) and a dynamic max
+(`surfaceWidth − rail − a grid minimum`), applied to drags, keyboard
+steps, AND incoming controlled/default values. A controlled value
+outside bounds renders clamped and reports the clamped value.
+
+A5. **No inline style until someone acts.** Untouched and uncontrolled,
+the pane keeps its stylesheet width — so the documented consumer css
+override keeps working exactly as today. The first drag/keyboard
+change (or a controlled/default prop) switches to an inline
+`inline-size`, which outranks any stylesheet. Documented on the docs
+page beside the existing override note.
+
+A6. **Keyboard parity (WCAG history makes this non-optional):** the handle
+is focusable, `role="separator"` with `aria-orientation="vertical"`,
+`aria-valuenow/min/max`, ArrowLeft/ArrowRight adjusting by 16px
+(direction-aware: "grow the pane" is the same arrow that drags the
+seam that way in the current writing direction — follow the header
+column-resize's RTL treatment), Home/End to min/max, Enter resets to
+default. It is a NEW tab stop inside the pane: every keyboard-walk
+roster that enumerates pane stops is updated deliberately, and the
+tab-exit guard must stay green.
+
+A7. **No persistence** (no saved-views concept — unchanged from SP1);
+consumers persist via the controlled trio.
+
+## Decisions — B. Auto width
+
+B1. **The kebab item is a TOGGLE named for the real semantic.** Auto width
+is continuous, so the menu gains a `role="menuitemcheckbox"` "Auto
+width" item, checked when the column is in the auto set. On →
+per-column auto; the column starts tracking content. Off → the column
+becomes manual at the engine's current stored width (no jump).
+Rejected: an AG-style one-shot "Autosize" action — it would
+misdescribe the machinery (the store has no one-shot mode), and a
+one-shot that silently left the column tracking content would be the
+worse lie.
+
+B2. **Public handle gains `setColumnAutoWidth(columnId, auto)`**,
+mirroring `setColumnWidth`'s shape and TSDoc conventions;
+`autosizeColumns()` keeps its all-columns meaning and its name. The
+kebab writes through the new method. (Handle addition → api report
+moves; docs guard will demand registration.)
+
+B3. **"Auto-size all columns" joins the columns section footer** beside
+Reset columns, calling `autosizeColumns()`. Same button anatomy as
+Reset.
+
+B4. **Reset columns restores the INITIAL auto set** — audit item: verify
+whether today's Reset already does (the initial set is "columns
+without declared widthPx"); if it doesn't, fixing it is in scope,
+because a Reset that restores order/pin/visibility but leaves
+auto-mode drift is a half-reset. Test both directions.
+
+B5. **The menu component sheds its stale name.** `ColumnPinMenu` grows a
+non-pin item; rename to what it is (e.g. `ColumnRowMenu` — the
+columns-section row's menu; exact name at implementation, following
+directory conventions). No-backcompat repo; internal component.
+
+B6. **Interaction with manual resize, documented not fought**: dragging a
+column's header resize strip (or the pane's setColumnWidth path)
+already flips auto off — the toggle reflects that on next open. The
+docs state the pair plainly: auto tracks content until you size the
+column yourself; the toggle turns tracking back on.
+
+## Verification
+
+- **A (resize):** jsdom — drag commits width within bounds; Escape-cancel
+  restores; double-click resets; controlled trio asserts-and-reports
+  (including out-of-bounds clamp report); no inline style before first
+  interaction (assert the attribute is absent, then present after a
+  drag); keyboard: arrows step (both directions × both writing modes if
+  the harness allows), Home/End, Enter-reset, aria-value* correctness.
+  Playwright — pointer drag on the real seam resizes pane AND grid
+  reflows (assert a grid column count/position change or scrollbar
+  change, not just the pane's width); the keyboard walks' updated rosters
+  pass; tab-exit guard green; coarse-pointer hit area ≥24px (the touch
+  spec's existing pattern).
+- **B (auto width):** jsdom — the toggle reflects the live set (a column
+  with declared width starts unchecked; one without starts checked);
+  toggling on makes a content change ACTUALLY change the drawn width
+  (disprove-capable: two contents with different widths — assert the
+  header cell's width moves, not that a method was called); toggling off
+  freezes it (content changes, width doesn't); manual header resize
+  unchecks it on next open; footer Auto-size-all sets every column;
+  Reset restores the initial set (B4, both directions). Mutation checks
+  on each: a toggle wired to the wrong column id or inverted must fail.
+- **Docs:** tool-panel page — resizing (with the css-override interplay
+  note, A5) and the auto-width pair (B6); configuration table gains the
+  width trio; handle docs gain `setColumnAutoWidth`; api reports
+  regenerate (build before api); docs guards satisfied honestly.
+- **Changesets:** `@pretable/react` minor (config + handle), `@pretable/ui`
+  patch (css).
+- Assert the old behavior survives: header column-resize, the kebab's pin
+  actions, Reset's existing restores, and the three keyboard walks.
+
+## Out of scope
+
+Width persistence beyond the controlled trio; per-section widths; a
+resize handle on the rail side; min/max-width props for the pane
+(the bounds are internal); autosize sampling options (padding, header
+inclusion — the store has no such knobs and none are invented here);
+touching the header column-resize implementation.

From 1512e813e841c51db623e008cd88f786dc86d3fd Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sun, 30 Aug 2026 07:51:35 -0700
Subject: [PATCH 02/11] docs: SP5 pane-resize + auto-width implementation plan

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../2026-08-30-tool-panel-resize-autosize.md  | 110 ++++++++++++++++++
 1 file changed, 110 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-08-30-tool-panel-resize-autosize.md

diff --git a/docs/superpowers/plans/2026-08-30-tool-panel-resize-autosize.md b/docs/superpowers/plans/2026-08-30-tool-panel-resize-autosize.md
new file mode 100644
index 00000000..f60f0706
--- /dev/null
+++ b/docs/superpowers/plans/2026-08-30-tool-panel-resize-autosize.md
@@ -0,0 +1,110 @@
+# Tool Panel SP5 — Pane Resizing + Auto Width Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Pane width resizing (drag + keyboard, controlled/uncontrolled) and the columns section's auto-width affordances (kebab toggle + auto-size-all footer action), per `docs/superpowers/specs/2026-08-30-tool-panel-resize-autosize.md`.
+
+**Architecture:** Resizing is React chrome state (the `activeSection` pattern) applied as an inline `inline-size` only after first interaction; the handle is a `role="separator"` strip on the pane's inline-start edge. Auto width rides the existing `createAutoWidthStore` — one new public handle method (`setColumnAutoWidth`), no engine changes.
+
+**Tech Stack:** React 19, TypeScript, vitest via the package `test` script (never bare `vitest run`; positional filters, never `--`), Playwright, api-extractor, changesets.
+
+**Read first, every task:** the spec (decisions A1–A7, B1–B6); `packages/react/src/tool-panel/ToolPanel.tsx` + the `<ToolPanel>` render site and `PretableToolPanelConfig` in `pretable-surface.tsx`; `packages/react/src/tool-panel/useToolRowDrag.ts` (#527 — the drag conventions: capture at pointerdown, Escape-cancel, the comment register); `createAutoWidthStore` + `autosizeColumns` + `setColumnWidth` in `packages/react/src/pretable-model.ts` (~lines 420-440, 655-745); `packages/react/src/tool-panel/ColumnPinMenu.tsx` + `overlay/menu-keyboard.ts`; the keyboard-walk rosters in `apps/website/e2e/tool-panel.spec.ts` and `grid-tab-wrap-rows.spec.ts`; the coarse-pointer hit-area pattern and the pane block in `packages/ui/src/grid.css` (~1455-1480).
+
+**House rules:** worktree only; no `git stash`; `pnpm format` before every commit (required gate); loaded box — isolate failures before believing; `pnpm build` before `pnpm api`; commit per task with trailer `Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>`.
+
+---
+
+### Task 1: `setColumnAutoWidth` on the handle + Reset audit (B2, B4)
+
+**Files:**
+- Modify: `packages/react/src/pretable-model.ts` (facade + type)
+- Modify: `packages/react/src/tool-panel/ColumnsSection.tsx` ONLY IF the Reset audit finds drift (see Step 3)
+- Test: `packages/react/src/__tests__/column-auto-width.test.tsx` (new)
+
+- [ ] **Step 1: Write the failing tests.**
+
+```tsx
+// Harness: a 2-column surface — "fixed" declares widthPx: 120, "fluid"
+// declares NO width (starts auto). Capture the grid via onGridReady.
+// Content strings chosen so auto width visibly differs between them
+// (choose-data-that-can-disprove): render "x" vs a long string, assert the
+// drawn header cell's offsetWidth/style width CHANGES when content changes
+// while auto, and does NOT change after setColumnAutoWidth(id, false).
+
+it("a column with no declared width starts auto; a declared one does not", ...);
+it("setColumnAutoWidth(id, true) makes content drive the drawn width", ...);
+it("setColumnAutoWidth(id, false) freezes the current width (no jump)", ...);
+it("setColumnWidth still flips auto OFF (old behavior survives)", ...);
+```
+
+(Adapt: jsdom has no real text measurement — read how existing auto-width behavior is tested; if drawn-width assertions need the renderer's measure seam mocked, follow that precedent. If jsdom cannot observe content-driven width at all, assert the STORE membership through the surface (a data attribute or the kebab state added in Task 3) AND add the drawn-width proof to the Playwright task instead — note the substitution honestly in the test header.)
+
+- [ ] **Step 2: Implement.** In `pretable-model.ts`: add `setColumnAutoWidth(columnId: TColumnId, auto: boolean)` to the `PretableReactGrid`/facade type beside `setColumnWidth`, TSDoc mirroring its conventions (declare-here-for-the-prototype-reach reason if applicable); implementation: `stores.autoWidths.setAuto(columnId as string, auto)`. Verify `autosizeColumns` and `setColumnWidth` interplay unchanged.
+- [ ] **Step 3: The Reset audit (B4).** Read ColumnsSection's Reset action: does it restore the initial auto set? Write the test either way: Reset after `setColumnAutoWidth("fixed", true)` must return "fixed" to manual and "fluid" to auto (the initial state). If Reset today doesn't touch the store, wire it (the initial set = ids without declared widthPx — the store's own constructor rule; expose what's needed via existing seams, not new public API).
+- [ ] **Step 4: Run the new file + the columns-section suites** (`pnpm --filter @pretable/react test column-auto-width tool-panel`). Mutation: make `setColumnAutoWidth` ignore its `auto` arg (always true) → the freeze test fails; revert.
+- [ ] **Step 5: Format, lint, typecheck, commit** — `feat(react): setColumnAutoWidth on the grid handle (SP5)`.
+
+---
+
+### Task 2: pane resize — state, handle, pointer + keyboard (A1–A7)
+
+**Files:**
+- Modify: `packages/react/src/pretable-surface.tsx` (config trio + state + clamp), `packages/react/src/tool-panel/ToolPanel.tsx` (the handle element + inline width application)
+- Create: `packages/react/src/tool-panel/pane-resize.ts` (pure: clamp logic, step math, direction resolution — the testable-without-React split)
+- Modify: `packages/ui/src/grid.css` (handle styling + coarse hit area; zero new tokens)
+- Tests: `packages/react/src/__tests__/tool-panel-pane-resize.test.tsx` (new) + pure `tool-panel-pane-resize-math.test.ts`; extend `attribute-contract.test.tsx` (`data-pretable-pane-resize`, asserted non-vacuously)
+
+- [ ] **Step 1: Pure module first, TDD.** `pane-resize.ts`: `clampPaneWidth(px, {min, max})`, `paneWidthAfterKey(key, current, {min, max, dir})` (arrows ±16, Home/End → min/max, direction-aware per A6), `paneWidthAfterDrag(startWidth, startX, currentX, dir, bounds)`. Write the table-driven tests red (both `ltr`/`rtl` rows — the direction flip is the mutation-prone branch), implement, green. MIN: measure the filters section's narrowest usable row in the browser once, record the number AND the measurement in a comment (A4's rule).
+- [ ] **Step 2: Config + state.** `PretableToolPanelConfig` gains `defaultPaneWidthPx?/paneWidthPx?/onPaneWidthChange?` (TSDoc per the `activeSection` fields' register, incl. the A5 inline-style note and the clamp-and-report rule). Surface: uncontrolled `useState<number | null>(defaultPaneWidthPx ?? null)` (`null` = untouched → no inline style); controlled presence wins; every write path clamps then reports. Pass width + change callback + bounds into `<ToolPanel>`.
+- [ ] **Step 3: The handle in ToolPanel.tsx.** Rendered at the pane's inline-start edge when a pane is open: `role="separator"`, `aria-orientation="vertical"`, `aria-valuenow/min/max`, `tabIndex={0}`, `data-pretable-pane-resize`, aria-label from a NEW message key `toolPanelResizeLabel` (add to messages layer per the established three-places pattern). Pointer: capture at pointerdown, live width updates via the pure drag math, Escape restores drag-start width (document-level listener while dragging, `preventDefault` interlock comment per the house pattern), release commits, double-click and Enter reset to default (clear to `null` when uncontrolled — restoring the stylesheet width per A5; controlled → report the default). Keyboard per the pure module.
+- [ ] **Step 4: jsdom tests red then green** (spec Verification A list): drag/clamp/Escape/dblclick-reset/controlled-trio/clamp-report/no-inline-before-interaction/aria values/arrow steps both directions. Follow `useToolRowDrag`'s test techniques for pointer sequences.
+- [ ] **Step 5: css** — the strip (reuse rule/hover tokens; a wider transparent hit area on coarse pointers via the established pattern); attribute-contract addition.
+- [ ] **Step 6: Mutations:** invert the direction resolution → the rtl rows fail; drop the clamp on the controlled path → the clamp-report test fails. Revert, green.
+- [ ] **Step 7: Full react suite + ui suite; format, lint, typecheck; commit** — `feat(react): the tool-panel pane resizes by pointer and keyboard (SP5)`.
+
+---
+
+### Task 3: the kebab toggle + footer action + rename (B1, B3, B5)
+
+**Files:**
+- Rename: `packages/react/src/tool-panel/ColumnPinMenu.tsx` → the honest name (B5; update imports/tests)
+- Modify: the renamed menu (menuitemcheckbox "Auto width"), `ColumnsSection.tsx` (footer "Auto-size all columns" beside Reset; plumb `setColumnAutoWidth` + the auto set), messages (+`toolPanelAutoWidthLabel`, `toolPanelAutosizeAllLabel` — three places), `grid.css` if the checkbox item needs styling
+- Tests: extend the menu's + columns-section's suites; attribute contract if new attributes
+
+- [ ] **Step 1: Failing tests:** the menu shows "Auto width" checked/unchecked per the live set (fixed → unchecked, fluid → checked — reuse Task 1's harness shape); toggling writes through `setColumnAutoWidth` with the RIGHT column id (mutation target); `role="menuitemcheckbox"` + `aria-checked` correct; keyboard operation via the shared `useMenuKeyboard` (no fourth hand-rolled copy); footer button sets ALL columns auto (assert the store effect through the UI, e.g. every kebab now checked); Reset restores (extends Task 1's B4 test through the UI).
+- [ ] **Step 2: Implement.** The section already subscribes to engine/layout state — the auto set needs its own subscription (`autoWidths.subscribe/getState` — check what the section can reach; plumb through the descriptor via a stable handle, respecting the DEPS RULE: the set is engine-ish state, so reach it by subscription, never bake it into the memo).
+- [ ] **Step 3: Mutations:** wire the toggle to a constant column id → the per-column test fails; invert checked-state derivation → the reflect test fails. Revert.
+- [ ] **Step 4: Run the tool-panel suites + full react suite; format, lint, typecheck; commit** — `feat(react): auto-width toggle and auto-size-all in the columns section (SP5)`.
+
+---
+
+### Task 4: e2e — the seam, the walks, the pixel proofs
+
+**Files:**
+- Modify: `apps/website/e2e/tool-panel.spec.ts` (+ possibly the fixtures page if the walk needs the handle)
+- Verify: `grid-tab-wrap-rows.spec.ts` untouched-green
+
+- [ ] **Step 1: New cases** (hydration-gated, helpers reused): (a) pointer-drag the seam → pane width changes AND the grid reflows (assert something grid-side: a header cell's x-position or the horizontal scrollbar state — prove the pixel, not the style); (b) keyboard: Tab reaches the handle inside the pane's roster (UPDATE every walk roster the handle joins — with the "update when…" comment style), arrows resize, Enter resets; tab-exit guard still green; (c) auto-width: toggle a column's "Auto width" in the kebab, stream/update content, the header width visibly changes; toggle off → frozen (this is the drawn-width proof if Task 1's jsdom couldn't observe it).
+- [ ] **Step 2: Run per the recipe** (root build, website build, prod server on a free port, `--workers=1`, both browsers, twice; isolate any failure). Include `grid-tab-wrap-rows.spec.ts` in the run.
+- [ ] **Step 3: Format/lint/typecheck website; commit** — `test(e2e): pane resize and auto width through the real shell (SP5)`.
+
+---
+
+### Task 5: docs, api, changesets, final verification
+
+**Files:**
+- Modify: `apps/website/content/docs/grid/tool-panel.mdx` (resizing subsection with the A5 css-override interplay note; the width trio joins the Configuration table; the columns-section prose gains the auto-width pair with B6's plain statement; new message keys join the strings listings — the #512 guard will demand them), handle docs for `setColumnAutoWidth` wherever the guard requires
+- Create: changesets — `@pretable/react` minor, `@pretable/ui` patch
+
+- [ ] **Step 1:** Docs + live-example touch-ups if the existing tool-panel example benefits (don't force one); run the website guard suite; satisfy every fail-closed demand honestly (SEO description ≤155 if touched).
+- [ ] **Step 2:** `pnpm build` then `pnpm api`; commit reports; `api:check` green. Expected moves: the config trio, `setColumnAutoWidth`, new message keys.
+- [ ] **Step 3:** Full verification: root build; react/ui/website suites; root lint + typecheck; format. Commit. Push branch, open PR `feat: tool-panel pane resizing and column auto width (SP5)` (body: spec decisions + test plan + generated-with footer). Merge on green only; read the merge back from origin/main.
+
+---
+
+## Self-review notes
+
+- Spec coverage: A1→T2 (handle/css), A2→T2 (pointer/Escape/dblclick), A3→T2 (trio), A4→T2 (pure clamp + measured MIN), A5→T2 (null-state inline rule) + T5 docs, A6→T2+T4 (keyboard + rosters), A7→spec-only (no work); B1→T3, B2→T1, B3→T3, B4→T1+T3, B5→T3, B6→T5 docs. Verification section maps to T1–T4 tests + T5 gates.
+- Names used consistently: `setColumnAutoWidth`, `defaultPaneWidthPx`/`paneWidthPx`/`onPaneWidthChange`, `pane-resize.ts` functions (T2 defines, T4 exercises), message keys `toolPanelResizeLabel`/`toolPanelAutoWidthLabel`/`toolPanelAutosizeAllLabel` (T2/T3 define, T5 documents).
+- No engine (grid-core/row-model) changes anywhere — if a task finds itself editing them, stop and escalate.
+- jsdom's text-measurement limitation is handled explicitly (T1 Step 1's substitution rule + T4's pixel proof), not discovered mid-task.

From 18d8a5aae3b13a0957da344417d8acaf4c281d84 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sun, 30 Aug 2026 13:06:07 -0700
Subject: [PATCH 03/11] feat(react): setColumnAutoWidth on the grid handle
 (SP5)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

B2: the public handle gains setColumnAutoWidth(columnId, auto) beside
setColumnWidth — true puts the column in the live auto-width set, false
makes it manual at the engine's current stored width. setColumnWidth
still flips auto off and autosizeColumns keeps its all-columns meaning;
both pinned by test.

B4 audit verdict: Reset restored pin/visibility/order but left auto-mode
drift — a half-reset. The surface now captures the mount-time auto set
(read from the store's own state, so the no-declared-widthPx rule keeps
one home) beside the layout baseline, and Reset replays it through the
new setter. The facade also carries an internal ɵautoWidths read seam
for chrome that must reflect membership (the SP5 kebab toggle's future
subscription).

jsdom observes the set at its real seam: mergeRenderColumns strips
widthPx for auto columns, so the drawn header width follows the
renderer's fallback (140) for auto and the engine store for manual —
content-driven pixels stay with Task 4's e2e.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../src/__tests__/column-auto-width.test.tsx  | 183 ++++++++++++++++++
 packages/react/src/pretable-model.ts          |  38 ++++
 packages/react/src/pretable-surface.tsx       |  12 ++
 .../react/src/tool-panel/ColumnsSection.tsx   |  18 ++
 4 files changed, 251 insertions(+)
 create mode 100644 packages/react/src/__tests__/column-auto-width.test.tsx

diff --git a/packages/react/src/__tests__/column-auto-width.test.tsx b/packages/react/src/__tests__/column-auto-width.test.tsx
new file mode 100644
index 00000000..e369c567
--- /dev/null
+++ b/packages/react/src/__tests__/column-auto-width.test.tsx
@@ -0,0 +1,183 @@
+// @vitest-environment jsdom
+import "@testing-library/jest-dom/vitest";
+import { act, cleanup, fireEvent, render } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import type { PretableColumn } from "../public_api";
+import { PretableSurface } from "../public_api";
+import type { PretableSurfaceGrid } from "../pretable-surface";
+
+/**
+ * `setColumnAutoWidth` and the auto-width set, observed at the drawn seam.
+ *
+ * WHAT JSDOM CAN AND CANNOT SEE — read before trusting these numbers. jsdom
+ * performs no text measurement, so "content drives the width" is not
+ * observable here; that pixel proof belongs to the Playwright pass (SP5
+ * Task 4). What jsdom CAN see is the seam the auto set actually acts
+ * through: `mergeRenderColumns` (pretable-model.ts) strips `widthPx` from
+ * every column in the auto set, so the renderer — not the engine — owns an
+ * auto column's drawn width (`resolveColumnWidth`'s fallback, 140px for an
+ * unwrapped column, or a flex share), while a manual column draws at the
+ * engine's stored width (grid-core's `DEFAULT_COLUMN_WIDTH_PX` 160 when the
+ * props declared none). 140 ≠ 160 ≠ any declared width, so auto-set
+ * membership is directly observable as WHICH owner the drawn header width
+ * follows: renderer fallback ⇒ auto, engine store ⇒ manual. Every assertion
+ * below reads the header cell's inline `style.width` — the real DOM output —
+ * never the store.
+ */
+
+type DemoRow = {
+  id: string;
+  fixed: string;
+  fluid: string;
+};
+
+const rows: DemoRow[] = [{ id: "r1", fixed: "x", fluid: "y" }];
+
+/** The renderer's fallback for an unwrapped column with no `widthPx` —
+ *  `FIXED_COLUMN_WIDTH` in renderer-dom's create-renderer.ts. */
+const RENDERER_AUTO_WIDTH = 140;
+/** grid-core's `DEFAULT_COLUMN_WIDTH_PX`: what the engine stores for a
+ *  column whose props declared no width. */
+const ENGINE_DEFAULT_WIDTH = 160;
+/** The "fixed" column's declared `widthPx`. */
+const DECLARED_WIDTH = 120;
+
+const columns: PretableColumn<DemoRow>[] = [
+  {
+    id: "fixed",
+    header: "Fixed",
+    widthPx: DECLARED_WIDTH,
+    value: (r) => r.fixed,
+  },
+  { id: "fluid", header: "Fluid", value: (r) => r.fluid },
+];
+
+type DemoGrid = PretableSurfaceGrid<
+  DemoRow,
+  string,
+  readonly PretableColumn<DemoRow>[]
+>;
+
+function mount(options?: { toolPanel?: boolean }) {
+  const captured = { current: null as DemoGrid | null };
+  const view = render(
+    <PretableSurface<DemoRow>
+      ariaLabel="Auto width demo"
+      columns={columns}
+      getRowId={(row) => row.id}
+      onGridReady={(g) => {
+        captured.current = g as DemoGrid;
+      }}
+      rows={rows}
+      toolPanel={{
+        defaultActiveSection: options?.toolPanel === true ? "columns" : null,
+      }}
+      viewportHeight={200}
+    />,
+  );
+  if (captured.current === null) {
+    throw new Error("onGridReady never fired: no grid captured at mount");
+  }
+  const grid = captured.current;
+  return {
+    view,
+    grid,
+    /** The drawn header width — the inline style the planner wrote. */
+    drawnWidth: (columnId: string) => {
+      const cell = view.container.querySelector(
+        `[data-pretable-header-cell][data-pretable-column-id="${columnId}"]`,
+      ) as HTMLElement | null;
+      if (cell === null) throw new Error(`No header cell for ${columnId}`);
+      return Number.parseFloat(cell.style.width.replace("px", ""));
+    },
+    /** What the ENGINE stores — distinct from what is drawn. */
+    engineWidth: (columnId: string) => {
+      const entry = grid
+        .getState()
+        .columnLayout.find((column) => column.id === columnId);
+      if (entry === undefined) throw new Error(`No layout entry ${columnId}`);
+      return entry.widthPx;
+    },
+    resetButton: () =>
+      view.container.querySelector(
+        "[data-pretable-tool-reset]",
+      ) as HTMLButtonElement,
+  };
+}
+
+afterEach(cleanup);
+
+describe("column auto width", () => {
+  it("a column with no declared width starts auto; a declared one does not", () => {
+    const h = mount();
+    // Manual: the engine's stored (declared) width is what draws.
+    expect(h.drawnWidth("fixed")).toBe(DECLARED_WIDTH);
+    expect(h.engineWidth("fixed")).toBe(DECLARED_WIDTH);
+    // Auto: the engine stores its 160 default, but the RENDERER owns the
+    // drawn width — the divergence is the membership proof.
+    expect(h.engineWidth("fluid")).toBe(ENGINE_DEFAULT_WIDTH);
+    expect(h.drawnWidth("fluid")).toBe(RENDERER_AUTO_WIDTH);
+  });
+
+  it("setColumnAutoWidth(id, true) hands the drawn width to the renderer", () => {
+    const h = mount();
+    act(() => {
+      h.grid.setColumnAutoWidth("fixed", true);
+    });
+    // The drawn width leaves the engine's stored value for the renderer's
+    // content-tracking mode (its fallback in jsdom, where nothing measures).
+    expect(h.drawnWidth("fixed")).toBe(RENDERER_AUTO_WIDTH);
+    // Non-destructive: the engine still remembers the declared width.
+    expect(h.engineWidth("fixed")).toBe(DECLARED_WIDTH);
+  });
+
+  it("setColumnAutoWidth(id, false) freezes at the engine's stored width", () => {
+    const h = mount();
+    act(() => {
+      h.grid.setColumnAutoWidth("fluid", false);
+    });
+    // Off means manual at the engine's current stored width (spec B1) —
+    // the drawn width now follows the store, not the renderer.
+    expect(h.drawnWidth("fluid")).toBe(ENGINE_DEFAULT_WIDTH);
+    // The other column is untouched.
+    expect(h.drawnWidth("fixed")).toBe(DECLARED_WIDTH);
+  });
+
+  it("setColumnWidth still flips auto OFF, and autosizeColumns still sets ALL auto", () => {
+    const h = mount();
+    // Old behavior 1: an explicit width write turns tracking off AND applies.
+    act(() => {
+      h.grid.setColumnWidth("fluid", 200);
+    });
+    expect(h.drawnWidth("fluid")).toBe(200);
+    expect(h.engineWidth("fluid")).toBe(200);
+    // Old behavior 2: autosizeColumns keeps its all-columns meaning.
+    act(() => {
+      h.grid.autosizeColumns();
+    });
+    expect(h.drawnWidth("fixed")).toBe(RENDERER_AUTO_WIDTH);
+    expect(h.drawnWidth("fluid")).toBe(RENDERER_AUTO_WIDTH);
+    // And the engine still remembers both stored widths underneath.
+    expect(h.engineWidth("fixed")).toBe(DECLARED_WIDTH);
+    expect(h.engineWidth("fluid")).toBe(200);
+  });
+
+  it("Reset columns restores the INITIAL auto set, both directions", () => {
+    const h = mount({ toolPanel: true });
+    // Drift both ways from the initial state.
+    act(() => {
+      h.grid.setColumnAutoWidth("fixed", true);
+      h.grid.setColumnAutoWidth("fluid", false);
+    });
+    expect(h.drawnWidth("fixed")).toBe(RENDERER_AUTO_WIDTH);
+    expect(h.drawnWidth("fluid")).toBe(ENGINE_DEFAULT_WIDTH);
+    // Reset: "fixed" declared a width, so it returns to manual; "fluid"
+    // declared none, so it returns to auto.
+    act(() => {
+      fireEvent.click(h.resetButton());
+    });
+    expect(h.drawnWidth("fixed")).toBe(DECLARED_WIDTH);
+    expect(h.drawnWidth("fluid")).toBe(RENDERER_AUTO_WIDTH);
+  });
+});
diff --git a/packages/react/src/pretable-model.ts b/packages/react/src/pretable-model.ts
index 968ade4b..03747817 100644
--- a/packages/react/src/pretable-model.ts
+++ b/packages/react/src/pretable-model.ts
@@ -137,6 +137,18 @@ export type PretableReactGrid<
   ) => void;
   readonly cancelEdit: () => void;
   readonly setColumnWidth: (columnId: TColumnId, width: number) => void;
+  /**
+   * Put one column into (or take it out of) the auto-width set — the LIVE set
+   * of columns whose drawn width the renderer owns and tracks from content,
+   * rather than the engine's stored width. `true` starts tracking; `false`
+   * makes the column manual again at the engine's current stored width, with
+   * no width write of its own. Columns that declare no `widthPx` start in the
+   * set; {@link setColumnWidth} takes a column OUT of it (an explicit width is
+   * a manual gesture), and `autosizeColumns` puts EVERY column in. Declared
+   * here beside `setColumnWidth` rather than inherited: the auto set lives in
+   * this layer's store, not in grid-core, so the facade is its only home.
+   */
+  readonly setColumnAutoWidth: (columnId: TColumnId, auto: boolean) => void;
   readonly setColumnPinned: (
     columnId: TColumnId,
     pinned: "left" | "right" | null,
@@ -530,6 +542,21 @@ export interface WindowState {
   readonly windowed: boolean;
 }
 
+/**
+ * The `ɵautoWidths` read seam the facade carries at runtime: subscribe +
+ * getState over the auto-width set. Not on {@link PretableReactGrid} — the
+ * public voice over the set is `setColumnAutoWidth` / `setColumnWidth` /
+ * `autosizeColumns`; this reader exists for the surface's own chrome, which
+ * must also REFLECT membership (the tool panel). Reached by a cast at the
+ * consumer, the `setWindowState` pattern.
+ *
+ * @internal
+ */
+export interface AutoWidthSetReader {
+  readonly subscribe: (listener: () => void) => () => void;
+  readonly getState: () => ReadonlySet<string>;
+}
+
 /** Internal indexed implementation shared by the public ownership overloads. */
 export function usePretableModelInternal<
   TRow extends object,
@@ -737,6 +764,17 @@ export function usePretableModelInternal<
       stores.gridCore.setColumnWidth(columnId, width);
       stores.autoWidths.setAuto(columnId, false);
     };
+    facade.setColumnAutoWidth = (columnId: TColumnId, auto: boolean) => {
+      stores.autoWidths.setAuto(columnId as string, auto);
+    };
+    // Internal read seam over the auto set for the surface's chrome (the
+    // tool panel's Reset and, later, its kebab toggle): membership is store
+    // state with no home in any snapshot, so chrome that must REFLECT it
+    // subscribes here rather than baking a copy into a descriptor closure.
+    facade.ɵautoWidths = {
+      subscribe: stores.autoWidths.subscribe,
+      getState: stores.autoWidths.getState,
+    };
     return facade as PretableReactGrid<TRow, TRowId, TColumns, TColumnId>;
   }, [
     presentationColumnsRef,
diff --git a/packages/react/src/pretable-surface.tsx b/packages/react/src/pretable-surface.tsx
index 34de4282..b2a4a723 100644
--- a/packages/react/src/pretable-surface.tsx
+++ b/packages/react/src/pretable-surface.tsx
@@ -94,6 +94,7 @@ import type {
   PretableTelemetry,
 } from "./surface-types";
 import type {
+  AutoWidthSetReader,
   PretableReactGrid,
   WindowSpacers,
   WindowState,
@@ -2514,6 +2515,16 @@ export function PretableSurface<
   if (initialColumnLayoutRef.current === null) {
     initialColumnLayoutRef.current = indexedGrid.getState().columnLayout;
   }
+  // The reset baseline's AUTO-WIDTH half, captured at the same instant for
+  // the same reason. At first render the set is exactly the store's
+  // constructor rule — "columns without a declared `widthPx`" — read from
+  // the store itself rather than re-derived here, so the rule has one home.
+  const initialAutoWidthIdsRef = useRef<ReadonlySet<string>>(null);
+  if (initialAutoWidthIdsRef.current === null) {
+    initialAutoWidthIdsRef.current = (
+      indexedGrid as unknown as { readonly ɵautoWidths: AutoWidthSetReader }
+    ).ɵautoWidths.getState();
+  }
   // The cell-edit controller owns a token for its UI lifecycle, but explicit
   // model writes happen inside its awaited commit callback — before the
   // controller gets a chance to check that token. Keep a surface-side token at
@@ -3909,6 +3920,7 @@ export function PretableSurface<
         render: () => (
           <ColumnsSection
             grid={indexedGrid}
+            initialAutoWidthRef={initialAutoWidthIdsRef}
             initialLayoutRef={initialColumnLayoutRef}
             labelForColumn={labelForColumn}
             messages={effectiveMessages}
diff --git a/packages/react/src/tool-panel/ColumnsSection.tsx b/packages/react/src/tool-panel/ColumnsSection.tsx
index 6e1b2b5c..fb9a0467 100644
--- a/packages/react/src/tool-panel/ColumnsSection.tsx
+++ b/packages/react/src/tool-panel/ColumnsSection.tsx
@@ -51,6 +51,7 @@ export interface ColumnsSectionGrid {
     pinned: "left" | "right" | null,
   ) => void;
   readonly setColumnOrder: (columnIds: readonly string[]) => void;
+  readonly setColumnAutoWidth: (columnId: string, auto: boolean) => void;
 }
 
 export interface ColumnsSectionProps {
@@ -72,6 +73,13 @@ export interface ColumnsSectionProps {
   readonly initialLayoutRef: RefObject<
     readonly ColumnsSectionLayoutEntry[] | null
   >;
+  /**
+   * The auto-width set as of the same surface-mount instant — the reset
+   * baseline's other half. Column ids whose width the renderer owned at
+   * mount (the ids that declared no `widthPx`); Reset returns exactly these
+   * to auto and every other replayed id to manual.
+   */
+  readonly initialAutoWidthRef: RefObject<ReadonlySet<string> | null>;
   /** Resolved surface messages — this section defaults no string itself. */
   readonly messages: ToolPanelColumnsMessages;
 }
@@ -98,6 +106,7 @@ export function ColumnsSection({
   grid,
   labelForColumn,
   initialLayoutRef,
+  initialAutoWidthRef,
   messages,
 }: ColumnsSectionProps) {
   // Live engine state, read through the section's OWN subscription — never a
@@ -316,6 +325,7 @@ export function ColumnsSection({
     // the already-restored pin groups and reproduces the initial layout
     // exactly. Only ids present in both rosters are replayed: a column the
     // props added or removed since mount has no initial state to restore.
+    const initialAuto = initialAutoWidthRef.current;
     for (const entry of current) {
       const initialEntry = initialById.get(entry.id);
       if (initialEntry === undefined) continue;
@@ -325,6 +335,14 @@ export function ColumnsSection({
       if ((entry.hidden === true) !== (initialEntry.hidden === true)) {
         grid.setColumnVisible(entry.id, initialEntry.hidden !== true);
       }
+      // The auto-width half of the baseline (spec B4): a reset that restores
+      // order/pin/visibility but leaves auto-mode drift is a half-reset. The
+      // write is unconditional over the replayed ids — the store no-ops when
+      // membership already matches — because unlike pin/visibility the
+      // CURRENT membership is not readable from the layout entry here.
+      if (initialAuto !== null) {
+        grid.setColumnAutoWidth(entry.id, initialAuto.has(entry.id));
+      }
     }
     // `setColumnOrder` demands EVERY current layout id. Ids the capture never
     // saw (a group column derived since mount) are spliced back at their

From 3fe5770206a61318ea05ce7144c96715ebb90dac Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sun, 30 Aug 2026 13:13:23 -0700
Subject: [PATCH 04/11] =?UTF-8?q?docs:=20SP5=20spec/plan=20amended=20?=
 =?UTF-8?q?=E2=80=94=20auto=20width=20is=20a=20mode=20bit,=20not=20a=20con?=
 =?UTF-8?q?tent=20fit?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Verified in a real browser: nothing measures cell content in the
column-width path. B3 (auto-size-all footer) dropped; the toggle and
docs say grid-managed width; the 140→160 jump documented.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../2026-08-30-tool-panel-resize-autosize.md  | 10 +--
 .../2026-08-30-tool-panel-resize-autosize.md  | 66 ++++++++++++-------
 2 files changed, 48 insertions(+), 28 deletions(-)

diff --git a/docs/superpowers/plans/2026-08-30-tool-panel-resize-autosize.md b/docs/superpowers/plans/2026-08-30-tool-panel-resize-autosize.md
index f60f0706..d50db75d 100644
--- a/docs/superpowers/plans/2026-08-30-tool-panel-resize-autosize.md
+++ b/docs/superpowers/plans/2026-08-30-tool-panel-resize-autosize.md
@@ -64,14 +64,14 @@ it("setColumnWidth still flips auto OFF (old behavior survives)", ...);
 
 ---
 
-### Task 3: the kebab toggle + footer action + rename (B1, B3, B5)
+### Task 3: the kebab toggle + rename (B1, B5; B3 DROPPED — see the amended spec)
 
 **Files:**
 - Rename: `packages/react/src/tool-panel/ColumnPinMenu.tsx` → the honest name (B5; update imports/tests)
-- Modify: the renamed menu (menuitemcheckbox "Auto width"), `ColumnsSection.tsx` (footer "Auto-size all columns" beside Reset; plumb `setColumnAutoWidth` + the auto set), messages (+`toolPanelAutoWidthLabel`, `toolPanelAutosizeAllLabel` — three places), `grid.css` if the checkbox item needs styling
+- Modify: the renamed menu (menuitemcheckbox "Auto width"), `ColumnsSection.tsx` (plumb `setColumnAutoWidth` + the auto set via the ɵautoWidths seam Task 1 added), messages (+`toolPanelAutoWidthLabel` — three places), `grid.css` if the checkbox item needs styling; correct the Task 1 test header's "content-tracking mode" phrase to the mode-bit wording
 - Tests: extend the menu's + columns-section's suites; attribute contract if new attributes
 
-- [ ] **Step 1: Failing tests:** the menu shows "Auto width" checked/unchecked per the live set (fixed → unchecked, fluid → checked — reuse Task 1's harness shape); toggling writes through `setColumnAutoWidth` with the RIGHT column id (mutation target); `role="menuitemcheckbox"` + `aria-checked` correct; keyboard operation via the shared `useMenuKeyboard` (no fourth hand-rolled copy); footer button sets ALL columns auto (assert the store effect through the UI, e.g. every kebab now checked); Reset restores (extends Task 1's B4 test through the UI).
+- [ ] **Step 1: Failing tests:** the menu shows "Auto width" checked/unchecked per the live set (fixed → unchecked, fluid → checked — reuse Task 1's harness shape); toggling writes through `setColumnAutoWidth` with the RIGHT column id (mutation target); `role="menuitemcheckbox"` + `aria-checked` correct; keyboard operation via the shared `useMenuKeyboard` (no fourth hand-rolled copy); Reset restores (extends Task 1's B4 test through the UI). Assertions state the REAL semantic (auto ⇒ renderer width, manual ⇒ engine width) — never a content-fit claim.
 - [ ] **Step 2: Implement.** The section already subscribes to engine/layout state — the auto set needs its own subscription (`autoWidths.subscribe/getState` — check what the section can reach; plumb through the descriptor via a stable handle, respecting the DEPS RULE: the set is engine-ish state, so reach it by subscription, never bake it into the memo).
 - [ ] **Step 3: Mutations:** wire the toggle to a constant column id → the per-column test fails; invert checked-state derivation → the reflect test fails. Revert.
 - [ ] **Step 4: Run the tool-panel suites + full react suite; format, lint, typecheck; commit** — `feat(react): auto-width toggle and auto-size-all in the columns section (SP5)`.
@@ -84,7 +84,7 @@ it("setColumnWidth still flips auto OFF (old behavior survives)", ...);
 - Modify: `apps/website/e2e/tool-panel.spec.ts` (+ possibly the fixtures page if the walk needs the handle)
 - Verify: `grid-tab-wrap-rows.spec.ts` untouched-green
 
-- [ ] **Step 1: New cases** (hydration-gated, helpers reused): (a) pointer-drag the seam → pane width changes AND the grid reflows (assert something grid-side: a header cell's x-position or the horizontal scrollbar state — prove the pixel, not the style); (b) keyboard: Tab reaches the handle inside the pane's roster (UPDATE every walk roster the handle joins — with the "update when…" comment style), arrows resize, Enter resets; tab-exit guard still green; (c) auto-width: toggle a column's "Auto width" in the kebab, stream/update content, the header width visibly changes; toggle off → frozen (this is the drawn-width proof if Task 1's jsdom couldn't observe it).
+- [ ] **Step 1: New cases** (hydration-gated, helpers reused): (a) pointer-drag the seam → pane width changes AND the grid reflows (assert something grid-side: a header cell's x-position or the horizontal scrollbar state — prove the pixel, not the style); (b) keyboard: Tab reaches the handle inside the pane's roster (UPDATE every walk roster the handle joins — with the "update when…" comment style), arrows resize, Enter resets; tab-exit guard still green; (c) auto-width: toggle a column's "Auto width" in the kebab → the drawn header width moves between the ENGINE's stored width and the RENDERER's width (140/flex share) — the verified mode-bit semantic; content changes must NOT move an auto column's width (assert the negative — it pins the semantic against the content-fit myth).
 - [ ] **Step 2: Run per the recipe** (root build, website build, prod server on a free port, `--workers=1`, both browsers, twice; isolate any failure). Include `grid-tab-wrap-rows.spec.ts` in the run.
 - [ ] **Step 3: Format/lint/typecheck website; commit** — `test(e2e): pane resize and auto width through the real shell (SP5)`.
 
@@ -105,6 +105,6 @@ it("setColumnWidth still flips auto OFF (old behavior survives)", ...);
 ## Self-review notes
 
 - Spec coverage: A1→T2 (handle/css), A2→T2 (pointer/Escape/dblclick), A3→T2 (trio), A4→T2 (pure clamp + measured MIN), A5→T2 (null-state inline rule) + T5 docs, A6→T2+T4 (keyboard + rosters), A7→spec-only (no work); B1→T3, B2→T1, B3→T3, B4→T1+T3, B5→T3, B6→T5 docs. Verification section maps to T1–T4 tests + T5 gates.
-- Names used consistently: `setColumnAutoWidth`, `defaultPaneWidthPx`/`paneWidthPx`/`onPaneWidthChange`, `pane-resize.ts` functions (T2 defines, T4 exercises), message keys `toolPanelResizeLabel`/`toolPanelAutoWidthLabel`/`toolPanelAutosizeAllLabel` (T2/T3 define, T5 documents).
+- Names used consistently: `setColumnAutoWidth`, `defaultPaneWidthPx`/`paneWidthPx`/`onPaneWidthChange`, `pane-resize.ts` functions (T2 defines, T4 exercises), message keys `toolPanelResizeLabel`/`toolPanelAutoWidthLabel` (T2/T3 define, T5 documents).
 - No engine (grid-core/row-model) changes anywhere — if a task finds itself editing them, stop and escalate.
 - jsdom's text-measurement limitation is handled explicitly (T1 Step 1's substitution rule + T4's pixel proof), not discovered mid-task.
diff --git a/docs/superpowers/specs/2026-08-30-tool-panel-resize-autosize.md b/docs/superpowers/specs/2026-08-30-tool-panel-resize-autosize.md
index 45e0745a..06bd19ef 100644
--- a/docs/superpowers/specs/2026-08-30-tool-panel-resize-autosize.md
+++ b/docs/superpowers/specs/2026-08-30-tool-panel-resize-autosize.md
@@ -22,13 +22,22 @@ Two finishing touches on the tool panel, one PR:
    `grid.css` (~1462), documented as consumer-overridable; the pane is a
    "fixed budget the grid area yields", and the virtualizer already
    observes resize (SP1).
-2. Auto width is a **live set**, not a one-shot fit:
-   `createAutoWidthStore` (pretable-model.ts) holds the set of column ids
-   in auto mode; columns with no declared `widthPx` START auto; the
-   renderer sizes auto columns from content continuously.
-   `autosizeColumns()` on the handle = set ALL columns auto;
-   `setColumnWidth(id, px)` flips that column to manual. There is no
-   public per-column auto setter yet.
+2. Auto width is a **mode bit, not a content fit** (verified in a real
+   browser, 2026-08-30 — the first draft of this fact claimed content
+   tracking and was WRONG): `createAutoWidthStore` (pretable-model.ts)
+   holds the set of column ids whose width is **grid-managed** — the
+   engine's stored width is withheld from the renderer
+   (`mergeRenderColumns` strips `widthPx`), and the renderer draws its
+   own default (140px, 220px wrapped — `resolveColumnWidth`) or a flex
+   share when the column declares `flex`. **Nothing measures cell
+   content anywhere in the column-width path** (the canvas text
+   measurement feeds row heights only). Columns with no declared
+   `widthPx` start auto; `setColumnWidth(id, px)` flips to manual;
+   `autosizeColumns()` marks all columns auto (its name over-promises —
+   filed for rename, out of scope here). Toggling auto OFF on a
+   never-resized column visibly jumps 140→160 (grid-core's
+   `DEFAULT_COLUMN_WIDTH_PX` never matched the renderer fallback —
+   unification filed, out of scope).
 3. The pane's keyboard walks (columns, grouping, custom-section e2e) pin
    tab-stop rosters, and the tab-exit guard is a hard gate — a new
    focusable in the pane moves rosters deliberately, never accidentally.
@@ -86,15 +95,18 @@ consumers persist via the controlled trio.
 
 ## Decisions — B. Auto width
 
-B1. **The kebab item is a TOGGLE named for the real semantic.** Auto width
-is continuous, so the menu gains a `role="menuitemcheckbox"` "Auto
-width" item, checked when the column is in the auto set. On →
-per-column auto; the column starts tracking content. Off → the column
-becomes manual at the engine's current stored width (no jump).
-Rejected: an AG-style one-shot "Autosize" action — it would
-misdescribe the machinery (the store has no one-shot mode), and a
-one-shot that silently left the column tracking content would be the
-worse lie.
+B1. **The kebab item is a TOGGLE named for the real semantic.** The menu
+gains a `role="menuitemcheckbox"` "Auto width" item, checked when the
+column is in the auto set. Its meaning — stated identically in the
+docs — is "let the grid manage this column's width" (renderer default,
+or a flex share when the column declares `flex`), NOT "fit to
+content". On → grid-managed; off → manual at the engine's current
+stored width. The 140→160 jump for a never-resized column is
+documented plainly rather than hidden. Rejected: an AG-style one-shot
+"Autosize" action — no machinery computes a content fit, and shipping
+the word "autosize" over a mode bit would be a lie the toggle avoids;
+a true fit-to-content action is new machinery, filed as a future
+candidate, out of scope.
 
 B2. **Public handle gains `setColumnAutoWidth(columnId, auto)`**,
 mirroring `setColumnWidth`'s shape and TSDoc conventions;
@@ -102,9 +114,12 @@ mirroring `setColumnWidth`'s shape and TSDoc conventions;
 kebab writes through the new method. (Handle addition → api report
 moves; docs guard will demand registration.)
 
-B3. **"Auto-size all columns" joins the columns section footer** beside
-Reset columns, calling `autosizeColumns()`. Same button anatomy as
-Reset.
+B3. **DROPPED: no "Auto-size all columns" footer action.** Its value was
+predicated on the fit-to-content reading; over a mode bit it is a
+low-value mass toggle with a misleading pedigree (`autosizeColumns`'s
+name). Per-column control via the kebab suffices; Reset columns
+already restores the initial auto set (B4). Revisit only with the
+fit-to-content machinery.
 
 B4. **Reset columns restores the INITIAL auto set** — audit item: verify
 whether today's Reset already does (the initial set is "columns
@@ -141,16 +156,21 @@ column yourself; the toggle turns tracking back on.
   toggling on makes a content change ACTUALLY change the drawn width
   (disprove-capable: two contents with different widths — assert the
   header cell's width moves, not that a method was called); toggling off
-  freezes it (content changes, width doesn't); manual header resize
-  unchecks it on next open; footer Auto-size-all sets every column;
-  Reset restores the initial set (B4, both directions). Mutation checks
-  on each: a toggle wired to the wrong column id or inverted must fail.
+  freezes it at the engine's stored width; manual header resize
+  unchecks it on next open; Reset restores the initial set (B4, both
+  directions). The drawn-width proof asserts the REAL semantic: auto ⇒
+  the renderer's width (140/flex), manual ⇒ the engine's stored width —
+  never a content-fit claim. Mutation checks on each: a toggle wired to
+  the wrong column id or inverted must fail.
 - **Docs:** tool-panel page — resizing (with the css-override interplay
   note, A5) and the auto-width pair (B6); configuration table gains the
   width trio; handle docs gain `setColumnAutoWidth`; api reports
   regenerate (build before api); docs guards satisfied honestly.
 - **Changesets:** `@pretable/react` minor (config + handle), `@pretable/ui`
   patch (css).
+- The Task 1 jsdom test header's "content-tracking mode" phrase is
+  corrected to the mode-bit wording (it currently repeats the myth its
+  own body debunks).
 - Assert the old behavior survives: header column-resize, the kebab's pin
   actions, Reset's existing restores, and the three keyboard walks.
 

From 4bda6d266fc5317df1da0a77ac704acb1925f8b0 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sun, 30 Aug 2026 13:27:29 -0700
Subject: [PATCH 05/11] feat(react): the tool-panel pane resizes by pointer and
 keyboard (SP5)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../src/__tests__/attribute-contract.test.tsx |   5 +
 .../tool-panel-pane-resize-math.test.ts       | 106 ++++++
 .../__tests__/tool-panel-pane-resize.test.tsx | 330 ++++++++++++++++++
 .../react/src/__tests__/tool-panel.test.tsx   |   8 +
 packages/react/src/messages.ts                |   1 +
 packages/react/src/pretable-surface.tsx       | 139 +++++++-
 packages/react/src/tool-panel/ToolPanel.tsx   | 248 ++++++++++++-
 packages/react/src/tool-panel/pane-resize.ts  | 106 ++++++
 packages/ui/grid.css                          |  53 +++
 9 files changed, 994 insertions(+), 2 deletions(-)
 create mode 100644 packages/react/src/__tests__/tool-panel-pane-resize-math.test.ts
 create mode 100644 packages/react/src/__tests__/tool-panel-pane-resize.test.tsx
 create mode 100644 packages/react/src/tool-panel/pane-resize.ts

diff --git a/packages/react/src/__tests__/attribute-contract.test.tsx b/packages/react/src/__tests__/attribute-contract.test.tsx
index 8aca3481..d1eced8f 100644
--- a/packages/react/src/__tests__/attribute-contract.test.tsx
+++ b/packages/react/src/__tests__/attribute-contract.test.tsx
@@ -99,6 +99,11 @@ describe("attribute contract", () => {
     expect(
       container.querySelector("[data-pretable-tool-grouping]"),
     ).not.toBeNull();
+    // The pane's resize handle (SP5) renders with any open pane — asserted
+    // here so the sweep covers data-pretable-pane-resize non-vacuously.
+    expect(
+      container.querySelector('[role="separator"][data-pretable-pane-resize]'),
+    ).not.toBeNull();
     expect(
       container.querySelector("[data-pretable-tool-group-row]"),
     ).not.toBeNull();
diff --git a/packages/react/src/__tests__/tool-panel-pane-resize-math.test.ts b/packages/react/src/__tests__/tool-panel-pane-resize-math.test.ts
new file mode 100644
index 00000000..81f456f2
--- /dev/null
+++ b/packages/react/src/__tests__/tool-panel-pane-resize-math.test.ts
@@ -0,0 +1,106 @@
+import { describe, expect, test } from "vitest";
+
+import {
+  PANE_KEY_STEP_PX,
+  clampPaneWidth,
+  paneWidthAfterDrag,
+  paneWidthAfterKey,
+} from "../tool-panel/pane-resize";
+
+const BOUNDS = { min: 200, max: 600 };
+const FLOOR_ONLY = { min: 200, max: null };
+
+describe("clampPaneWidth", () => {
+  test.each([
+    ["below min clamps up", 120, BOUNDS, 200],
+    ["above max clamps down", 900, BOUNDS, 600],
+    ["in bounds is identity", 300, BOUNDS, 300],
+    ["min itself survives", 200, BOUNDS, 200],
+    ["max itself survives", 600, BOUNDS, 600],
+    // max: null = the surface has no measurement yet (jsdom, pre-mount).
+    // Only the floor applies — never an invented ceiling.
+    ["floor-only: large value passes", 5000, FLOOR_ONLY, 5000],
+    ["floor-only: min still applies", 10, FLOOR_ONLY, 200],
+  ] as const)("%s", (_name, px, bounds, expected) => {
+    expect(clampPaneWidth(px, bounds)).toBe(expected);
+  });
+
+  test("fractional drag positions round to whole pixels", () => {
+    expect(clampPaneWidth(300.6, BOUNDS)).toBe(301);
+  });
+});
+
+describe("paneWidthAfterKey", () => {
+  // A6: "grow the pane" is the arrow that drags the seam that way. The pane
+  // docks at the layout row's inline END, so its resize seam moves toward
+  // inline-start as the pane grows: in ltr that is ArrowLeft, in rtl
+  // ArrowRight. These rtl rows are the mutation target — an inverted
+  // direction resolution must fail them.
+  test.each([
+    ["ltr ArrowLeft grows", "ArrowLeft", 300, "ltr", 300 + PANE_KEY_STEP_PX],
+    [
+      "ltr ArrowRight shrinks",
+      "ArrowRight",
+      300,
+      "ltr",
+      300 - PANE_KEY_STEP_PX,
+    ],
+    ["rtl ArrowRight grows", "ArrowRight", 300, "rtl", 300 + PANE_KEY_STEP_PX],
+    ["rtl ArrowLeft shrinks", "ArrowLeft", 300, "rtl", 300 - PANE_KEY_STEP_PX],
+    ["grow clamps at max", "ArrowLeft", 590, "ltr", 600],
+    ["shrink clamps at min", "ArrowRight", 210, "ltr", 200],
+    ["rtl grow clamps at max", "ArrowRight", 590, "rtl", 600],
+    ["Home goes to min", "Home", 300, "ltr", 200],
+    ["End goes to max", "End", 300, "ltr", 600],
+    ["Home in rtl still goes to min", "Home", 300, "rtl", 200],
+  ] as const)("%s", (_name, key, current, dir, expected) => {
+    expect(paneWidthAfterKey(key, current, { min: 200, max: 600, dir })).toBe(
+      expected,
+    );
+  });
+
+  test("End with an unmeasured max is a no-op (no invented ceiling)", () => {
+    expect(
+      paneWidthAfterKey("End", 300, { min: 200, max: null, dir: "ltr" }),
+    ).toBe(300);
+  });
+
+  test("a grow step with an unmeasured max still steps", () => {
+    expect(
+      paneWidthAfterKey("ArrowLeft", 300, { min: 200, max: null, dir: "ltr" }),
+    ).toBe(300 + PANE_KEY_STEP_PX);
+  });
+
+  test.each(["ArrowUp", "ArrowDown", "Enter", "a", "Escape"])(
+    "non-resize key %s returns null",
+    (key) => {
+      expect(
+        paneWidthAfterKey(key, 300, { min: 200, max: 600, dir: "ltr" }),
+      ).toBeNull();
+    },
+  );
+});
+
+describe("paneWidthAfterDrag", () => {
+  // Same seam geometry as the keys: in ltr the pointer moving LEFT
+  // (currentX < startX) grows the pane; in rtl the pointer moving RIGHT
+  // grows it. The rtl rows are the mutation target.
+  test.each([
+    ["ltr: pointer left grows", 300, 500, 440, "ltr", 360],
+    ["ltr: pointer right shrinks", 300, 500, 560, "ltr", 240],
+    ["rtl: pointer right grows", 300, 500, 560, "rtl", 360],
+    ["rtl: pointer left shrinks", 300, 500, 440, "rtl", 240],
+    ["no movement is identity", 300, 500, 500, "ltr", 300],
+    ["ltr grow clamps at max", 300, 500, 100, "ltr", 600],
+    ["ltr shrink clamps at min", 300, 500, 900, "ltr", 200],
+    ["rtl shrink clamps at min", 300, 500, 100, "rtl", 200],
+  ] as const)("%s", (_name, startWidth, startX, currentX, dir, expected) => {
+    expect(paneWidthAfterDrag(startWidth, startX, currentX, dir, BOUNDS)).toBe(
+      expected,
+    );
+  });
+
+  test("floor-only bounds never cap a grow drag", () => {
+    expect(paneWidthAfterDrag(300, 500, 0, "ltr", FLOOR_ONLY)).toBe(800);
+  });
+});
diff --git a/packages/react/src/__tests__/tool-panel-pane-resize.test.tsx b/packages/react/src/__tests__/tool-panel-pane-resize.test.tsx
new file mode 100644
index 00000000..145fabbc
--- /dev/null
+++ b/packages/react/src/__tests__/tool-panel-pane-resize.test.tsx
@@ -0,0 +1,330 @@
+/**
+ * The pane resize handle through the real surface (SP5, spec A1–A6): the
+ * separator contract, the A5 no-inline-style-until-someone-acts rule, drag /
+ * Escape / double-click / Enter, keyboard steps in both writing directions,
+ * and the controlled trio's clamp-and-report.
+ *
+ * jsdom cannot lay out, so the pane measures 0 wide and the surface's max
+ * bound stays unmeasured (`max: null`) throughout — every ceiling behavior
+ * here exercises the floor and the unmeasured-max degradations; the real
+ * ceiling is the pure module's table (tool-panel-pane-resize-math.test.ts)
+ * plus the Playwright seam drag (Task 4). Widths asserted below are style
+ * ATTRIBUTE text (`inline-size: Npx`): the inline style is the feature.
+ */
+import "@testing-library/jest-dom/vitest";
+import { fireEvent, render } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+
+import { PretableSurface } from "../public_api";
+import type { PretableColumn, PretableToolPanelConfig } from "../public_api";
+import { PANE_MIN_WIDTH_PX, PANE_KEY_STEP_PX } from "../tool-panel/pane-resize";
+
+type Row = { id: string; name: string; amount: number };
+
+const columns: PretableColumn<Row>[] = [
+  { id: "name", header: "Name" },
+  { id: "amount", header: "Amount" },
+];
+const rows: Row[] = [
+  { id: "r1", name: "Alpha", amount: 1 },
+  { id: "r2", name: "Beta", amount: 2 },
+];
+
+function renderSurface(toolPanel: PretableToolPanelConfig = {}, dir?: "rtl") {
+  const surface = (
+    <PretableSurface
+      ariaLabel="Pane resize grid"
+      columns={columns}
+      rows={rows}
+      getRowId={(r: Row) => r.id}
+      toolPanel={{ defaultActiveSection: "columns", ...toolPanel }}
+      viewportHeight={300}
+    />
+  );
+  return render(dir === "rtl" ? <div dir="rtl">{surface}</div> : surface);
+}
+
+const handleOf = (container: HTMLElement) =>
+  container.querySelector<HTMLElement>("[data-pretable-pane-resize]");
+const paneOf = (container: HTMLElement) =>
+  container.querySelector<HTMLElement>("[data-pretable-tool-pane]");
+const paneWidth = (container: HTMLElement) => {
+  const style = paneOf(container)?.getAttribute("style") ?? "";
+  const m = /inline-size:\s*([0-9.]+)px/.exec(style);
+  return m === null ? null : Number(m[1]);
+};
+
+describe("the resize handle's contract", () => {
+  it("renders in the open pane as a focusable vertical separator", () => {
+    const { container } = renderSurface();
+    const handle = handleOf(container);
+    expect(handle).not.toBeNull();
+    expect(handle).toHaveAttribute("role", "separator");
+    expect(handle).toHaveAttribute("aria-orientation", "vertical");
+    expect(handle).toHaveAttribute("aria-label", "Resize tool panel");
+    expect(handle?.tabIndex).toBe(0);
+    expect(handle).toHaveAttribute("aria-valuemin", String(PANE_MIN_WIDTH_PX));
+    // Unmeasured surface (jsdom): no max, and no invented valuenow.
+    expect(handle).not.toHaveAttribute("aria-valuemax");
+    expect(handle).not.toHaveAttribute("aria-valuenow");
+  });
+
+  it("does not render while the pane is closed", () => {
+    const { container } = renderSurface({ defaultActiveSection: null });
+    expect(handleOf(container)).toBeNull();
+  });
+
+  it("reflects the committed width in aria-valuenow", () => {
+    const { container } = renderSurface({ defaultPaneWidthPx: 300 });
+    expect(handleOf(container)).toHaveAttribute("aria-valuenow", "300");
+  });
+});
+
+describe("no inline style until someone acts (A5)", () => {
+  it("writes no inline width untouched, and one after a keystroke", () => {
+    const { container } = renderSurface();
+    expect(paneWidth(container)).toBeNull();
+    fireEvent.keyDown(handleOf(container)!, { key: "ArrowLeft" });
+    // Untouched + unmeasurable pane: the gesture starts from the floor.
+    expect(paneWidth(container)).toBe(PANE_MIN_WIDTH_PX + PANE_KEY_STEP_PX);
+  });
+
+  it("seeds an inline width from defaultPaneWidthPx", () => {
+    const { container } = renderSurface({ defaultPaneWidthPx: 300 });
+    expect(paneWidth(container)).toBe(300);
+  });
+});
+
+describe("keyboard resize (A6)", () => {
+  it("ltr: ArrowLeft grows, ArrowRight shrinks, Home floors", () => {
+    const { container } = renderSurface({ defaultPaneWidthPx: 300 });
+    const handle = handleOf(container)!;
+    fireEvent.keyDown(handle, { key: "ArrowLeft" });
+    expect(paneWidth(container)).toBe(300 + PANE_KEY_STEP_PX);
+    fireEvent.keyDown(handle, { key: "ArrowRight" });
+    fireEvent.keyDown(handle, { key: "ArrowRight" });
+    expect(paneWidth(container)).toBe(300 - PANE_KEY_STEP_PX);
+    fireEvent.keyDown(handle, { key: "Home" });
+    expect(paneWidth(container)).toBe(PANE_MIN_WIDTH_PX);
+  });
+
+  it("rtl: the arrows flip with the writing direction", () => {
+    const { container } = renderSurface({ defaultPaneWidthPx: 300 }, "rtl");
+    const handle = handleOf(container)!;
+    fireEvent.keyDown(handle, { key: "ArrowRight" });
+    expect(paneWidth(container)).toBe(300 + PANE_KEY_STEP_PX);
+    fireEvent.keyDown(handle, { key: "ArrowLeft" });
+    fireEvent.keyDown(handle, { key: "ArrowLeft" });
+    expect(paneWidth(container)).toBe(300 - PANE_KEY_STEP_PX);
+  });
+
+  it("a shrink step clamps at the floor", () => {
+    const { container } = renderSurface({
+      defaultPaneWidthPx: PANE_MIN_WIDTH_PX + 4,
+    });
+    fireEvent.keyDown(handleOf(container)!, { key: "ArrowRight" });
+    expect(paneWidth(container)).toBe(PANE_MIN_WIDTH_PX);
+  });
+
+  it("End with an unmeasured max is a no-op", () => {
+    const onPaneWidthChange = vi.fn();
+    const { container } = renderSurface({
+      defaultPaneWidthPx: 300,
+      onPaneWidthChange,
+    });
+    fireEvent.keyDown(handleOf(container)!, { key: "End" });
+    expect(paneWidth(container)).toBe(300);
+    expect(onPaneWidthChange).not.toHaveBeenCalled();
+  });
+
+  it("Enter resets to the default width", () => {
+    const { container } = renderSurface({ defaultPaneWidthPx: 300 });
+    const handle = handleOf(container)!;
+    fireEvent.keyDown(handle, { key: "ArrowLeft" });
+    expect(paneWidth(container)).toBe(300 + PANE_KEY_STEP_PX);
+    fireEvent.keyDown(handle, { key: "Enter" });
+    expect(paneWidth(container)).toBe(300);
+  });
+
+  it("Enter with no default clears back to the stylesheet width", () => {
+    const { container } = renderSurface();
+    const handle = handleOf(container)!;
+    fireEvent.keyDown(handle, { key: "ArrowLeft" });
+    expect(paneWidth(container)).not.toBeNull();
+    fireEvent.keyDown(handle, { key: "Enter" });
+    expect(paneWidth(container)).toBeNull();
+  });
+});
+
+describe("pointer drag (A2)", () => {
+  const drag = (
+    handle: HTMLElement,
+    moves: readonly number[],
+    startX = 500,
+  ) => {
+    fireEvent.pointerDown(handle, {
+      button: 0,
+      pointerId: 1,
+      clientX: startX,
+    });
+    for (const clientX of moves) {
+      fireEvent.pointerMove(handle, { pointerId: 1, clientX });
+    }
+  };
+
+  it("applies the width live and keeps it on release", () => {
+    const { container } = renderSurface({ defaultPaneWidthPx: 300 });
+    const handle = handleOf(container)!;
+    drag(handle, [440]);
+    // ltr: 60px toward inline-start grows the pane.
+    expect(paneWidth(container)).toBe(360);
+    fireEvent.pointerUp(handle, { pointerId: 1, clientX: 440 });
+    expect(paneWidth(container)).toBe(360);
+  });
+
+  it("rtl: the same pointer travel shrinks instead", () => {
+    const { container } = renderSurface({ defaultPaneWidthPx: 300 }, "rtl");
+    const handle = handleOf(container)!;
+    drag(handle, [440]);
+    expect(paneWidth(container)).toBe(240);
+    fireEvent.pointerUp(handle, { pointerId: 1, clientX: 440 });
+  });
+
+  it("clamps a runaway shrink at the floor", () => {
+    const { container } = renderSurface({ defaultPaneWidthPx: 300 });
+    const handle = handleOf(container)!;
+    drag(handle, [2000]);
+    expect(paneWidth(container)).toBe(PANE_MIN_WIDTH_PX);
+    fireEvent.pointerUp(handle, { pointerId: 1, clientX: 2000 });
+  });
+
+  it("Escape mid-drag restores the drag-start width", () => {
+    const { container } = renderSurface({ defaultPaneWidthPx: 300 });
+    const handle = handleOf(container)!;
+    drag(handle, [440]);
+    expect(paneWidth(container)).toBe(360);
+    fireEvent.keyDown(handle, { key: "Escape" });
+    expect(paneWidth(container)).toBe(300);
+    // The cancelled gesture is over: further moves change nothing.
+    fireEvent.pointerMove(handle, { pointerId: 1, clientX: 400 });
+    expect(paneWidth(container)).toBe(300);
+  });
+
+  it("Escape reaches a drag even when focus sits elsewhere", () => {
+    const { container } = renderSurface({ defaultPaneWidthPx: 300 });
+    drag(handleOf(container)!, [440]);
+    fireEvent.keyDown(document.body, { key: "Escape" });
+    expect(paneWidth(container)).toBe(300);
+  });
+
+  it("a drag from the untouched state restores to NO inline width", () => {
+    const { container } = renderSurface();
+    const handle = handleOf(container)!;
+    drag(handle, [400]);
+    expect(paneWidth(container)).not.toBeNull();
+    fireEvent.keyDown(handle, { key: "Escape" });
+    expect(paneWidth(container)).toBeNull();
+  });
+
+  it("double-click resets to the default width", () => {
+    const { container } = renderSurface({ defaultPaneWidthPx: 300 });
+    const handle = handleOf(container)!;
+    fireEvent.keyDown(handle, { key: "ArrowLeft" });
+    fireEvent.dblClick(handle);
+    expect(paneWidth(container)).toBe(300);
+  });
+
+  it("double-click with no default restores the stylesheet width", () => {
+    const { container } = renderSurface();
+    const handle = handleOf(container)!;
+    fireEvent.keyDown(handle, { key: "ArrowLeft" });
+    fireEvent.dblClick(handle);
+    expect(paneWidth(container)).toBeNull();
+  });
+
+  it("the dblclick a real drag's release fires does not reset", () => {
+    const { container } = renderSurface({ defaultPaneWidthPx: 300 });
+    const handle = handleOf(container)!;
+    drag(handle, [440]);
+    fireEvent.pointerUp(handle, { pointerId: 1, clientX: 440 });
+    fireEvent.dblClick(handle);
+    expect(paneWidth(container)).toBe(360);
+  });
+});
+
+describe("the controlled trio (A3, A4)", () => {
+  it("asserts through paneWidthPx and only reports gestures", () => {
+    const onPaneWidthChange = vi.fn();
+    const { container } = renderSurface({
+      paneWidthPx: 320,
+      onPaneWidthChange,
+    });
+    expect(paneWidth(container)).toBe(320);
+    const handle = handleOf(container)!;
+    fireEvent.keyDown(handle, { key: "ArrowLeft" });
+    // Reported, not applied — the parent did not accept the change.
+    expect(onPaneWidthChange).toHaveBeenCalledWith(320 + PANE_KEY_STEP_PX);
+    expect(paneWidth(container)).toBe(320);
+  });
+
+  it("paneWidthPx: null holds the stylesheet width under gestures", () => {
+    const onPaneWidthChange = vi.fn();
+    const { container } = renderSurface({
+      paneWidthPx: null,
+      onPaneWidthChange,
+    });
+    expect(paneWidth(container)).toBeNull();
+    fireEvent.keyDown(handleOf(container)!, { key: "ArrowLeft" });
+    expect(onPaneWidthChange).toHaveBeenCalledWith(
+      PANE_MIN_WIDTH_PX + PANE_KEY_STEP_PX,
+    );
+    expect(paneWidth(container)).toBeNull();
+  });
+
+  it("an out-of-bounds controlled width renders clamped and reports the clamp", () => {
+    const onPaneWidthChange = vi.fn();
+    const { container } = renderSurface({
+      paneWidthPx: 50,
+      onPaneWidthChange,
+    });
+    expect(paneWidth(container)).toBe(PANE_MIN_WIDTH_PX);
+    expect(handleOf(container)).toHaveAttribute(
+      "aria-valuenow",
+      String(PANE_MIN_WIDTH_PX),
+    );
+    expect(onPaneWidthChange).toHaveBeenCalledTimes(1);
+    expect(onPaneWidthChange).toHaveBeenCalledWith(PANE_MIN_WIDTH_PX);
+  });
+
+  it("an out-of-bounds DEFAULT renders clamped and reports too", () => {
+    const onPaneWidthChange = vi.fn();
+    const { container } = renderSurface({
+      defaultPaneWidthPx: 50,
+      onPaneWidthChange,
+    });
+    expect(paneWidth(container)).toBe(PANE_MIN_WIDTH_PX);
+    expect(onPaneWidthChange).toHaveBeenCalledWith(PANE_MIN_WIDTH_PX);
+  });
+
+  it("uncontrolled gestures report the committed width", () => {
+    const onPaneWidthChange = vi.fn();
+    const { container } = renderSurface({
+      defaultPaneWidthPx: 300,
+      onPaneWidthChange,
+    });
+    const handle = handleOf(container)!;
+    fireEvent.keyDown(handle, { key: "ArrowLeft" });
+    expect(onPaneWidthChange).toHaveBeenLastCalledWith(300 + PANE_KEY_STEP_PX);
+    fireEvent.keyDown(handle, { key: "Enter" });
+    expect(onPaneWidthChange).toHaveBeenLastCalledWith(300);
+  });
+
+  it("a reset with no default reports null", () => {
+    const onPaneWidthChange = vi.fn();
+    const { container } = renderSurface({ onPaneWidthChange });
+    const handle = handleOf(container)!;
+    fireEvent.keyDown(handle, { key: "ArrowLeft" });
+    fireEvent.keyDown(handle, { key: "Enter" });
+    expect(onPaneWidthChange).toHaveBeenLastCalledWith(null);
+  });
+});
diff --git a/packages/react/src/__tests__/tool-panel.test.tsx b/packages/react/src/__tests__/tool-panel.test.tsx
index d5f3f157..84811f90 100644
--- a/packages/react/src/__tests__/tool-panel.test.tsx
+++ b/packages/react/src/__tests__/tool-panel.test.tsx
@@ -68,15 +68,23 @@ function Host({
   onChange?: (next: string | null) => void;
 }) {
   const [active, setActive] = useState<string | null>(initial);
+  // The pane-width props are the surface's; this harness pins the untouched
+  // state (no inline width, floor-only bounds). The resize behavior itself is
+  // tested through the real surface in tool-panel-pane-resize.test.tsx.
   return (
     <ToolPanel
       railLabel="Tool panel"
+      resizeLabel="Resize tool panel"
       sections={makeSections()}
       activeSection={active}
       onActiveSectionChange={(next) => {
         onChange?.(next);
         setActive(next);
       }}
+      paneWidthPx={null}
+      paneBounds={{ min: 186, max: null }}
+      onPaneWidthChange={() => {}}
+      onPaneWidthReset={() => {}}
     />
   );
 }
diff --git a/packages/react/src/messages.ts b/packages/react/src/messages.ts
index b0d78173..87ef9df4 100644
--- a/packages/react/src/messages.ts
+++ b/packages/react/src/messages.ts
@@ -117,6 +117,7 @@ export const defaultMessages: Required<PretableSurfaceMessages> = {
   toolPanelFilterJoinActionLabel: ({ opLabel, nextLabel }) =>
     `${opLabel}, join all conditions in this list with ${nextLabel}`,
   toolPanelGroupingLabel: () => "Grouping",
+  toolPanelResizeLabel: () => "Resize tool panel",
   toolPanelGroupByLabel: () => "Group by",
   toolPanelAddRowGroupLabel: () => "Add group",
   toolPanelRemoveGroupLabel: ({ label }) => `Remove grouping by ${label}`,
diff --git a/packages/react/src/pretable-surface.tsx b/packages/react/src/pretable-surface.tsx
index b2a4a723..32ddc963 100644
--- a/packages/react/src/pretable-surface.tsx
+++ b/packages/react/src/pretable-surface.tsx
@@ -128,6 +128,7 @@ import {
   ToolPanel,
   resolveToolPanelRoster,
 } from "./tool-panel";
+import { PANE_MIN_WIDTH_PX, clampPaneWidth } from "./tool-panel/pane-resize";
 import { FiltersSection } from "./tool-panel/filters";
 import type { FilterRowColumn } from "./tool-panel/filters";
 import { GroupingSection } from "./tool-panel/grouping";
@@ -668,6 +669,12 @@ export interface PretableSurfaceMessages {
   toolPanelFiltersLabel?: () => string;
   /** The grouping section's tab label — its `aria-label` and tooltip text. */
   toolPanelGroupingLabel?: () => string;
+  /**
+   * Accessible name of the pane's width-resize handle (`role="separator"` on
+   * the pane's inline-start edge). Shell-level like `toolPanelLabel`, not a
+   * section string: the handle belongs to the pane, whichever section is open.
+   */
+  toolPanelResizeLabel?: () => string;
 
   // ---- Tool panel: columns section ---------------------------------------
 
@@ -889,6 +896,32 @@ export interface PretableToolPanelConfig {
   readonly onActiveSectionChange?: (
     section: PretableToolPanelSectionId | null,
   ) => void;
+  /**
+   * Seeds the pane's width for the uncontrolled form, in px. Absent, the pane
+   * keeps its STYLESHEET width until the user first resizes it — no inline
+   * style is written, so the documented css override
+   * (`[data-pretable-tool-pane] { inline-size: … }`) keeps working exactly as
+   * before. Present (or after any resize), the width is an inline
+   * `inline-size`, which outranks every stylesheet rule.
+   */
+  readonly defaultPaneWidthPx?: number;
+  /**
+   * The pane's width, in px — present (including `null`) makes it fully
+   * controlled, the `activeSection` contract: the handle then only reports
+   * through `onPaneWidthChange`. `null` means "the stylesheet width" — no
+   * inline style, the untouched state. A number outside the pane's bounds
+   * renders CLAMPED, and the clamped width is reported back once through
+   * `onPaneWidthChange` so a persisted layout converges on what is actually
+   * drawn.
+   */
+  readonly paneWidthPx?: number | null;
+  /**
+   * Reports every pane-width change, already clamped: live during a drag,
+   * per keystroke on the handle, and `null` when a reset (double-click or
+   * Enter on the handle, with no `defaultPaneWidthPx`) returns the pane to
+   * its stylesheet width.
+   */
+  readonly onPaneWidthChange?: (widthPx: number | null) => void;
 }
 
 const ANNOUNCE_DEBOUNCE_MS = 500;
@@ -2072,6 +2105,8 @@ export function PretableSurface<
       toolPanelGroupingLabel:
         messages?.toolPanelGroupingLabel ??
         defaultMessages.toolPanelGroupingLabel,
+      toolPanelResizeLabel:
+        messages?.toolPanelResizeLabel ?? defaultMessages.toolPanelResizeLabel,
       toolPanelGroupByLabel:
         messages?.toolPanelGroupByLabel ??
         defaultMessages.toolPanelGroupByLabel,
@@ -2148,6 +2183,75 @@ export function PretableSurface<
     controlledToolSection !== undefined
       ? controlledToolSection
       : uncontrolledToolSection;
+  // ---- Tool panel pane width (SP5) ---------------------------------------
+  // Chrome state on the `activeSection` pattern. `null` is a real state, not
+  // an absence: "untouched — keep the stylesheet width, write no inline
+  // style" (spec A5), which is what keeps the documented css override on
+  // `[data-pretable-tool-pane]` working until someone actually resizes.
+  const [uncontrolledPaneWidth, setUncontrolledPaneWidth] = useState<
+    number | null
+  >(() => toolPanelConfig?.defaultPaneWidthPx ?? null);
+  const controlledPaneWidth = toolPanelConfig?.paneWidthPx;
+  const rawPaneWidth =
+    controlledPaneWidth !== undefined
+      ? controlledPaneWidth
+      : uncontrolledPaneWidth;
+  // The dynamic max needs the tool layout row's rendered width. Observed the
+  // way the viewport observes its own (`viewportWidth` below): a ref plus a
+  // ResizeObserver, held as state so aria-valuemax and the clamp re-derive on
+  // a container resize. `null` until the observer's first delivery — jsdom,
+  // SSR, and the pre-mount render all live here — and while unmeasured the
+  // bounds degrade to the floor alone: `clampPaneWidth` treats `max: null`
+  // as "no ceiling", because clamping to an unmeasured guess would report a
+  // width nobody chose (the rule is stated on `PaneWidthBounds`).
+  //
+  // A CALLBACK ref rather than an effect over a plain one: the layout row
+  // mounts and unmounts with the panel (`toolPanel={false}`, an emptied
+  // roster), and a mount-time effect would never see a later attach.
+  const [toolLayoutWidth, setToolLayoutWidth] = useState<number | null>(null);
+  const toolLayoutObserverRef = useRef<ResizeObserver | null>(null);
+  const observeToolLayout = useCallback((el: HTMLDivElement | null) => {
+    toolLayoutObserverRef.current?.disconnect();
+    toolLayoutObserverRef.current = null;
+    if (el === null || typeof ResizeObserver === "undefined") {
+      setToolLayoutWidth(null);
+      return;
+    }
+    const read = () =>
+      setToolLayoutWidth(el.clientWidth === 0 ? null : el.clientWidth);
+    read();
+    const observer = new ResizeObserver(read);
+    observer.observe(el);
+    toolLayoutObserverRef.current = observer;
+  }, []);
+  const paneBounds = useMemo(() => {
+    if (toolLayoutWidth === null) {
+      return { min: PANE_MIN_WIDTH_PX, max: null };
+    }
+    // The grid keeps `surface − rail − pane`: 36 mirrors the rail's
+    // stylesheet `inline-size` (grid.css), and 160 is the grid-area floor —
+    // room for one 40px-minimum column beside a pinned selection column with
+    // the scrollbar's gutter, a UX floor rather than a contract. `max` never
+    // drops below `min`, or a small container would make the clamp oscillate.
+    const max = Math.max(PANE_MIN_WIDTH_PX, toolLayoutWidth - 36 - 160);
+    return { min: PANE_MIN_WIDTH_PX, max };
+  }, [toolLayoutWidth]);
+  const appliedPaneWidth =
+    rawPaneWidth === null ? null : clampPaneWidth(rawPaneWidth, paneBounds);
+  // Clamp-and-report (spec A4): an incoming controlled/default width outside
+  // bounds renders clamped, and the clamped value is reported back so a
+  // persisted layout converges on what is actually drawn. The callback rides
+  // a ref so an inline `toolPanel={{...}}` object — a new identity every
+  // render — cannot re-fire the report; the effect keys on the widths alone.
+  const paneWidthChangeRef = useRef(toolPanelConfig?.onPaneWidthChange);
+  useEffect(() => {
+    paneWidthChangeRef.current = toolPanelConfig?.onPaneWidthChange;
+  });
+  useEffect(() => {
+    if (rawPaneWidth === null || appliedPaneWidth === null) return;
+    if (appliedPaneWidth === rawPaneWidth) return;
+    paneWidthChangeRef.current?.(appliedPaneWidth);
+  }, [rawPaneWidth, appliedPaneWidth]);
   // `toolPanelSections` — the descriptor array — is declared further down,
   // beside `labelForColumn`: the columns section needs the grid handle and the
   // label resolver, neither of which exists yet at this point in the
@@ -7533,12 +7637,17 @@ export function PretableSurface<
   // (which re-derives `viewportWidth` from `clientWidth`) reflows the columns
   // and the right-pinned insets, exactly as it does for a container resize.
   return (
-    <div data-pretable-tool-layout="" style={getToolPanelLayoutStyle()}>
+    <div
+      data-pretable-tool-layout=""
+      ref={observeToolLayout}
+      style={getToolPanelLayoutStyle()}
+    >
       <div data-pretable-tool-grid-area="" style={getToolPanelGridAreaStyle()}>
         {verticalStack}
       </div>
       <ToolPanel
         railLabel={effectiveMessages.toolPanelLabel()}
+        resizeLabel={effectiveMessages.toolPanelResizeLabel()}
         sections={toolPanelSections}
         activeSection={activeToolSection}
         onActiveSectionChange={(next) => {
@@ -7547,6 +7656,34 @@ export function PretableSurface<
           }
           toolPanelConfig?.onActiveSectionChange?.(next);
         }}
+        paneWidthPx={appliedPaneWidth}
+        paneBounds={paneBounds}
+        // Every write path clamps then reports — the shell hands over raw
+        // gesture output, and this is the one place the bounds are applied
+        // so the controlled and uncontrolled forms cannot drift.
+        onPaneWidthChange={(next) => {
+          const clamped =
+            next === null ? null : clampPaneWidth(next, paneBounds);
+          if (controlledPaneWidth === undefined) {
+            setUncontrolledPaneWidth(clamped);
+          }
+          toolPanelConfig?.onPaneWidthChange?.(clamped);
+        }}
+        // Reset (double-click / Enter on the handle): back to
+        // `defaultPaneWidthPx` when the consumer gave one, else to `null` —
+        // the untouched state, which clears the inline style and restores the
+        // stylesheet width (spec A5).
+        onPaneWidthReset={() => {
+          const fallback = toolPanelConfig?.defaultPaneWidthPx;
+          const next =
+            fallback === undefined
+              ? null
+              : clampPaneWidth(fallback, paneBounds);
+          if (controlledPaneWidth === undefined) {
+            setUncontrolledPaneWidth(next);
+          }
+          toolPanelConfig?.onPaneWidthChange?.(next);
+        }}
       />
     </div>
   );
diff --git a/packages/react/src/tool-panel/ToolPanel.tsx b/packages/react/src/tool-panel/ToolPanel.tsx
index af8152f9..d30e00bb 100644
--- a/packages/react/src/tool-panel/ToolPanel.tsx
+++ b/packages/react/src/tool-panel/ToolPanel.tsx
@@ -1,9 +1,49 @@
-import { createElement, Fragment, useId, useRef } from "react";
+import type { PointerEvent as ReactPointerEvent } from "react";
+import {
+  createElement,
+  Fragment,
+  useCallback,
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from "react";
 
 import { focusTab } from "./focus";
+import type { PaneResizeDirection, PaneWidthBounds } from "./pane-resize";
+import { paneWidthAfterDrag, paneWidthAfterKey } from "./pane-resize";
 import { Rail } from "./Rail";
 import type { ToolPanelSectionDescriptor } from "./sections";
 
+/**
+ * The writing direction the resize arithmetic keys on, read from the
+ * RENDERED handle. The `dir` attribute is consulted before the computed
+ * style, not after: an explicit `dir="rtl"` is the common way a consumer
+ * flips the surface, and jsdom — where the keyboard tests run — does not
+ * cascade the attribute into `getComputedStyle().direction`.
+ */
+function resolveDirection(el: Element): PaneResizeDirection {
+  const attr = el.closest("[dir]")?.getAttribute("dir")?.toLowerCase();
+  if (attr === "rtl") return "rtl";
+  if (attr === "ltr") return "ltr";
+  const view = el.ownerDocument.defaultView;
+  return view?.getComputedStyle(el).direction === "rtl" ? "rtl" : "ltr";
+}
+
+/** A pane-width drag in flight. `startRaw` is what Escape restores. */
+interface PaneResizeDrag {
+  pointerId: number;
+  startX: number;
+  /** The committed width at pointerdown — `null` = the stylesheet width. */
+  startRaw: number | null;
+  /** The RENDERED width at pointerdown, the drag arithmetic's origin. */
+  startWidth: number;
+  dir: PaneResizeDirection;
+  /** True once any move changed the width — gates the dblclick reset. */
+  moved: boolean;
+}
+
 export interface ToolPanelProps {
   sections: readonly ToolPanelSectionDescriptor[];
   /**
@@ -27,6 +67,25 @@ export interface ToolPanelProps {
    * directory may default a user-facing string of its own.
    */
   railLabel: string;
+  /** Accessible name for the pane's resize handle — same messages-layer rule. */
+  resizeLabel: string;
+  /**
+   * The pane's width, already clamped by the surface, or `null` for "the
+   * stylesheet width — write no inline style" (spec A5). Fully controlled
+   * like `activeSection`, and for the same reason.
+   */
+  paneWidthPx: number | null;
+  /** The surface's bounds — `max: null` while its width is unmeasured. */
+  paneBounds: PaneWidthBounds;
+  /**
+   * Reports raw gesture output: live during a drag, per keystroke, and the
+   * drag-start width on an Escape cancel (`null` when the drag started from
+   * the stylesheet width). The SURFACE clamps — one clamp site for the
+   * controlled and uncontrolled forms both.
+   */
+  onPaneWidthChange: (next: number | null) => void;
+  /** Double-click or Enter on the handle — the surface owns what "default" is. */
+  onPaneWidthReset: () => void;
 }
 
 /**
@@ -46,25 +105,155 @@ export function ToolPanel({
   activeSection,
   onActiveSectionChange,
   railLabel,
+  resizeLabel,
+  paneWidthPx,
+  paneBounds,
+  onPaneWidthChange,
+  onPaneWidthReset,
 }: ToolPanelProps) {
   const baseId = useId();
   const paneId = `${baseId}-pane`;
   const tabId = (id: string) => `${baseId}-tab-${id}`;
   const railRef = useRef<HTMLDivElement | null>(null);
+  const paneRef = useRef<HTMLDivElement | null>(null);
 
   const active =
     activeSection == null
       ? undefined
       : sections.find((s) => s.id === activeSection);
 
+  // What the pane measures while it wears no inline width — the stylesheet
+  // width, whatever the consumer's css says it is. This is aria-valuenow's
+  // fallback and the origin of a drag or keystroke that starts from the
+  // untouched state; `null` where layout cannot answer (jsdom measures 0),
+  // in which case aria-valuenow is omitted rather than invented and the
+  // first gesture starts from the floor.
+  const [measuredPaneWidth, setMeasuredPaneWidth] = useState<number | null>(
+    null,
+  );
+  const activeId = active?.id;
+  useLayoutEffect(() => {
+    if (activeId === undefined || paneWidthPx !== null) return;
+    const el = paneRef.current;
+    if (el === null) return;
+    const width = Math.round(el.getBoundingClientRect().width);
+    setMeasuredPaneWidth(width === 0 ? null : width);
+  }, [activeId, paneWidthPx]);
+
+  const dragRef = useRef<PaneResizeDrag | null>(null);
+  /** True across the release that ends a real drag — gates the dblclick reset. */
+  const wasResizingRef = useRef(false);
+  /** Render state only so the Escape document listener below can arm. */
+  const [dragActive, setDragActive] = useState(false);
+  const currentWidth = paneWidthPx ?? measuredPaneWidth ?? paneBounds.min;
+
+  const cancelDrag = useCallback(() => {
+    const drag = dragRef.current;
+    if (drag === null) return;
+    dragRef.current = null;
+    setDragActive(false);
+    // Abandoning the gesture is NOT the restore here, unlike the row drags:
+    // this drag commits continuously (spec A2, live resize), so the restore
+    // is an explicit write of the drag-start width — `null` included, which
+    // returns a pane that started untouched to its stylesheet width.
+    onPaneWidthChange(drag.startRaw);
+  }, [onPaneWidthChange]);
+
+  // Escape mid-drag on a document listener, the register's pattern
+  // (`useToolRowDrag`): pointer capture routes the MOVES here, but keyboard
+  // events follow DOM focus, which a captured drag can leave anywhere. The
+  // handle's own keydown below handles the focused-on-the-handle case first
+  // and stops propagation — its comment carries the interlock with the
+  // pane's Escape-to-rail-tab courtesy; this listener is the catch-all for
+  // focus parked elsewhere, where `preventDefault` is what tells that pane
+  // handler (which skips defaultPrevented events) to stand down when it has
+  // not already run.
+  useEffect(() => {
+    if (!dragActive) return;
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== "Escape" && event.key !== "Esc") return;
+      event.preventDefault();
+      cancelDrag();
+    };
+    document.addEventListener("keydown", onKeyDown);
+    return () => document.removeEventListener("keydown", onKeyDown);
+  }, [dragActive, cancelDrag]);
+
+  const handlePointerDown = (event: ReactPointerEvent<HTMLDivElement>) => {
+    if (event.button !== 0) return;
+    const startWidth =
+      paneWidthPx ??
+      (paneRef.current
+        ? Math.round(paneRef.current.getBoundingClientRect().width)
+        : 0);
+    dragRef.current = {
+      pointerId: event.pointerId,
+      startX: event.clientX,
+      startRaw: paneWidthPx,
+      startWidth,
+      dir: resolveDirection(event.currentTarget),
+      moved: false,
+    };
+    wasResizingRef.current = false;
+    setDragActive(true);
+    // Capture at pointerdown, the register's rule (`useToolRowDrag`): engines
+    // rAF-coalesce pointermoves, so under load the first delivered move can
+    // already be off this slim strip, and a capture taken any later never
+    // happens — the drag silently dies.
+    try {
+      event.currentTarget.setPointerCapture(event.pointerId);
+    } catch {
+      // jsdom, or a pointer type without capture — no-op.
+    }
+  };
+
+  const handlePointerMove = (event: ReactPointerEvent<HTMLDivElement>) => {
+    const drag = dragRef.current;
+    if (drag === null || event.pointerId !== drag.pointerId) return;
+    const next = paneWidthAfterDrag(
+      drag.startWidth,
+      drag.startX,
+      event.clientX,
+      drag.dir,
+      paneBounds,
+    );
+    if (next !== drag.startWidth) drag.moved = true;
+    // Applied LIVE — the width goes through the surface's state on every
+    // move (chrome-cheap; the grid reflows through the virtualizer's resize
+    // observer), so release has nothing left to commit.
+    onPaneWidthChange(next);
+  };
+
+  const handlePointerUp = (event: ReactPointerEvent<HTMLDivElement>) => {
+    const drag = dragRef.current;
+    if (drag === null || event.pointerId !== drag.pointerId) return;
+    dragRef.current = null;
+    setDragActive(false);
+    // Survives into the dblclick that two fast press-drag-releases fire —
+    // the header resize strip's `wasResizing` guard, same reason.
+    wasResizingRef.current = drag.moved;
+    try {
+      event.currentTarget.releasePointerCapture(drag.pointerId);
+    } catch {
+      // jsdom — no-op.
+    }
+  };
+
   return (
     <>
       {active !== undefined ? (
         <div
           id={paneId}
+          ref={paneRef}
           role="tabpanel"
           aria-labelledby={tabId(active.id)}
           data-pretable-tool-pane=""
+          // No inline style until someone acts (spec A5): untouched and
+          // uncontrolled, the pane keeps its stylesheet width, so the
+          // documented consumer css override keeps working. The first
+          // drag/keystroke (or a width prop) switches to this inline
+          // `inline-size`, which outranks any stylesheet.
+          style={paneWidthPx === null ? undefined : { inlineSize: paneWidthPx }}
           // Escape hands focus back to the pane's rail tab — a keydown
           // listener on the container so it works from any control inside,
           // including ones a later section has not built yet. It does not close the
@@ -76,6 +265,63 @@ export function ToolPanel({
             }
           }}
         >
+          <div
+            role="separator"
+            aria-orientation="vertical"
+            aria-label={resizeLabel}
+            aria-valuemin={paneBounds.min}
+            aria-valuemax={paneBounds.max ?? undefined}
+            // Omitted, not invented, while nothing has measured the pane —
+            // the untouched jsdom/SSR state has no truthful number to offer.
+            aria-valuenow={paneWidthPx ?? measuredPaneWidth ?? undefined}
+            tabIndex={0}
+            data-pretable-pane-resize=""
+            onPointerDown={handlePointerDown}
+            onPointerMove={handlePointerMove}
+            onPointerUp={handlePointerUp}
+            onPointerCancel={cancelDrag}
+            onDoubleClick={() => {
+              // A drag that moved ends with two fast clicks often enough for
+              // the header's `wasResizing` guard to exist; same rule here.
+              if (wasResizingRef.current) {
+                wasResizingRef.current = false;
+                return;
+              }
+              onPaneWidthReset();
+            }}
+            onKeyDown={(event) => {
+              // Escape mid-drag restores the drag-start width. Handled on
+              // the handle itself — pointerdown gives it DOM focus in real
+              // browsers — with `stopPropagation` as the interlock so the
+              // pane's own Escape handler above does not also yank focus to
+              // the rail tab over a mere gesture cancel. A cancel with focus
+              // parked elsewhere loses only the courtesy restore; release
+              // still ends the drag at the live width.
+              if (event.key === "Escape" || event.key === "Esc") {
+                if (dragRef.current !== null) {
+                  event.preventDefault();
+                  event.stopPropagation();
+                  cancelDrag();
+                }
+                return;
+              }
+              if (event.key === "Enter") {
+                event.preventDefault();
+                onPaneWidthReset();
+                return;
+              }
+              const next = paneWidthAfterKey(event.key, currentWidth, {
+                min: paneBounds.min,
+                max: paneBounds.max,
+                dir: resolveDirection(event.currentTarget),
+              });
+              if (next === null) return;
+              event.preventDefault();
+              if (next !== currentWidth || paneWidthPx === null) {
+                onPaneWidthChange(next);
+              }
+            }}
+          />
           <div data-pretable-tool-section="">{active.render()}</div>
         </div>
       ) : null}
diff --git a/packages/react/src/tool-panel/pane-resize.ts b/packages/react/src/tool-panel/pane-resize.ts
new file mode 100644
index 00000000..40b344b4
--- /dev/null
+++ b/packages/react/src/tool-panel/pane-resize.ts
@@ -0,0 +1,106 @@
+/**
+ * The pane-resize arithmetic, React-free — the clamp, the keyboard step and
+ * the drag delta live here so the direction flip (the mutation-prone branch)
+ * is table-testable without a DOM. The handle in `ToolPanel.tsx` owns the
+ * gesture (capture, Escape, commit) and calls in for every number it applies.
+ *
+ * ## Direction (spec A6)
+ *
+ * The pane docks at the layout row's inline END, so the resize seam — the
+ * pane's inline-start edge — moves toward inline-start as the pane grows.
+ * "Grow the pane" is therefore the arrow that drags the seam that way in the
+ * current writing direction: ArrowLeft in `ltr`, ArrowRight in `rtl`; a drag
+ * grows the pane as the pointer travels toward inline-start. Both key and
+ * drag share `growthSign` so the two inputs cannot be inverted independently.
+ */
+
+/** Writing direction, resolved by the caller from the rendered handle. */
+export type PaneResizeDirection = "ltr" | "rtl";
+
+export interface PaneWidthBounds {
+  readonly min: number;
+  /**
+   * `null` = the surface has no width measurement yet (first render, jsdom, a
+   * detached observer). Only the floor applies then — a clamp must never
+   * invent a ceiling, or a controlled width asserted before the observer's
+   * first delivery would be "clamped" to a number nobody chose.
+   */
+  readonly max: number | null;
+}
+
+/**
+ * The pane's width floor, in px.
+ *
+ * Measured (2026-08-30, Chromium via the `fixtures/tool-panel-sections`
+ * route) against the filters section's narrowest usable row, per spec A4:
+ * the filter row wraps, so its floor is set by the widest control that must
+ * fit a wrapped line alone — the operator `<select>`, whose max-content
+ * width over its longest option ("does not contain", text vocabulary) is
+ * 161px. On its wrapped line the control receives `pane − 25px` (4px row
+ * padding ×2 + 8px section padding ×2 + 1px pane border), so the narrowest
+ * pane that renders every operator label unclipped is 161 + 25 = 186px.
+ */
+export const PANE_MIN_WIDTH_PX = 186;
+
+/** One arrow-key step, px — the header column-resize's keyboard granularity. */
+export const PANE_KEY_STEP_PX = 16;
+
+/** Clamp into bounds; rounds first so a live drag commits whole pixels. */
+export function clampPaneWidth(px: number, bounds: PaneWidthBounds): number {
+  const rounded = Math.round(px);
+  const floored = Math.max(bounds.min, rounded);
+  return bounds.max === null ? floored : Math.min(bounds.max, floored);
+}
+
+/** +1 when travel toward positive clientX grows the pane, else −1. */
+function growthSign(dir: PaneResizeDirection): 1 | -1 {
+  return dir === "rtl" ? 1 : -1;
+}
+
+/**
+ * The width after one keydown on the handle, or `null` for a key this module
+ * does not own (Enter's reset is the component's — it needs the default,
+ * which is state, not arithmetic).
+ */
+export function paneWidthAfterKey(
+  key: string,
+  current: number,
+  opts: { min: number; max: number | null; dir: PaneResizeDirection },
+): number | null {
+  const bounds: PaneWidthBounds = { min: opts.min, max: opts.max };
+  switch (key) {
+    case "ArrowLeft":
+      return clampPaneWidth(
+        current - growthSign(opts.dir) * PANE_KEY_STEP_PX,
+        bounds,
+      );
+    case "ArrowRight":
+      return clampPaneWidth(
+        current + growthSign(opts.dir) * PANE_KEY_STEP_PX,
+        bounds,
+      );
+    case "Home":
+      return opts.min;
+    case "End":
+      // No measured max → no destination. A no-op, not a jump to some
+      // sentinel: End means "as wide as allowed", and unmeasured bounds
+      // do not know what is allowed.
+      return opts.max === null ? current : opts.max;
+    default:
+      return null;
+  }
+}
+
+/** The live width while a drag's pointer sits at `currentX`. */
+export function paneWidthAfterDrag(
+  startWidth: number,
+  startX: number,
+  currentX: number,
+  dir: PaneResizeDirection,
+  bounds: PaneWidthBounds,
+): number {
+  return clampPaneWidth(
+    startWidth + growthSign(dir) * (currentX - startX),
+    bounds,
+  );
+}
diff --git a/packages/ui/grid.css b/packages/ui/grid.css
index 485e7264..c7252c9d 100644
--- a/packages/ui/grid.css
+++ b/packages/ui/grid.css
@@ -1464,6 +1464,9 @@
        area yields, never a negotiation. */
     flex: none;
     flex-direction: column;
+    /* Containing block for the resize handle below, which straddles the
+       pane/grid seam with a negative inline offset. */
+    position: relative;
     inline-size: 264px;
     min-block-size: 0;
     background: var(--pretable-bg-toolbar);
@@ -1474,6 +1477,33 @@
     font-size: var(--pretable-font-size-cell);
     color: var(--pretable-text-cell);
   }
+  /* The pane's width-resize handle (SP5): a slim strip straddling the
+     pane/grid seam — 3px each side of the border the pane already draws, so
+     the grab target sits ON the visible seam rather than beside it. Zero new
+     tokens (spec A1): the affordances below reuse the hover fill and the
+     focus ring every control in this file already wears. `touch-action:
+     none` for the drag's reason everywhere else: the browser must not
+     translate a captured pointer's movement into a scroll. */
+  :where([data-pretable-pane-resize]) {
+    position: absolute;
+    inset-block: 0;
+    inset-inline-start: -3px;
+    inline-size: 7px;
+    cursor: col-resize;
+    touch-action: none;
+    user-select: none;
+  }
+  /* A hover/focus TINT, not a painted bar: the seam's rule stays the visible
+     line, and the strip announces itself only when pointed at — the
+     hover-reveal register the row controls in this section follow. */
+  :where([data-pretable-pane-resize]:hover),
+  :where([data-pretable-pane-resize]:active) {
+    background: var(--pretable-bg-hover);
+  }
+  :where([data-pretable-pane-resize]:focus-visible) {
+    outline: 2px solid var(--pretable-focus-ring);
+    outline-offset: -2px;
+  }
   :where([data-pretable-tool-section]) {
     display: flex;
     flex-direction: column;
@@ -2172,5 +2202,28 @@
       height: 24px;
       transform: translate(-50%, -50%);
     }
+
+    /* WCAG 2.5.8 for the pane's resize seam, bought with the same
+       transparent out-of-flow ::after as the row controls above — the drawn
+       strip stays 7px so the seam reads as a seam, and the missing 17px
+       come from a box centred on it. CENTRED, unlike the header's
+       right-anchored menu box, and that is a judged trade rather than an
+       oversight: the ~8px that land pane-side overlap only the section's
+       padding gutter (the row grips start 8px in and carry 24px targets of
+       their own), and the grid-side pixels cover no target at all on a
+       coarse pointer, where the scrollbar is an overlay. The header REMOVED
+       its 4px column-resize strip on coarse pointers; this one is kept and
+       inflated instead because a full-height seam can actually be acquired
+       by a finger — the header strip's problem was 4px inside a column, not
+       resizing itself. */
+    :where([data-pretable-pane-resize])::after {
+      content: "";
+      position: absolute;
+      top: 0;
+      bottom: 0;
+      left: 50%;
+      width: 24px;
+      transform: translateX(-50%);
+    }
   }
 }

From 3c01d43b469c4decc01419122f969c915f8b8bb8 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sun, 30 Aug 2026 13:36:01 -0700
Subject: [PATCH 06/11] fix(react): the resize separator always carries a
 coherent aria value range (SP5 review)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../__tests__/tool-panel-pane-resize.test.tsx |  9 +++--
 .../react/src/__tests__/tool-panel.test.tsx   |  3 +-
 packages/react/src/messages.ts                |  2 +-
 packages/react/src/tool-panel/ToolPanel.tsx   | 39 ++++++++++++-------
 4 files changed, 35 insertions(+), 18 deletions(-)

diff --git a/packages/react/src/__tests__/tool-panel-pane-resize.test.tsx b/packages/react/src/__tests__/tool-panel-pane-resize.test.tsx
index 145fabbc..3751082f 100644
--- a/packages/react/src/__tests__/tool-panel-pane-resize.test.tsx
+++ b/packages/react/src/__tests__/tool-panel-pane-resize.test.tsx
@@ -64,9 +64,12 @@ describe("the resize handle's contract", () => {
     expect(handle).toHaveAttribute("aria-label", "Resize tool panel");
     expect(handle?.tabIndex).toBe(0);
     expect(handle).toHaveAttribute("aria-valuemin", String(PANE_MIN_WIDTH_PX));
-    // Unmeasured surface (jsdom): no max, and no invented valuenow.
-    expect(handle).not.toHaveAttribute("aria-valuemax");
-    expect(handle).not.toHaveAttribute("aria-valuenow");
+    // A focusable separator MUST carry aria-valuenow (ARIA 1.2 — omitted,
+    // AT assumes now=50 of max=100, an inverted range against min=186). On
+    // an unmeasured surface (jsdom) both now and max degrade to the floor
+    // the first keystroke would step from — a collapsed but coherent range.
+    expect(handle).toHaveAttribute("aria-valuenow", String(PANE_MIN_WIDTH_PX));
+    expect(handle).toHaveAttribute("aria-valuemax", String(PANE_MIN_WIDTH_PX));
   });
 
   it("does not render while the pane is closed", () => {
diff --git a/packages/react/src/__tests__/tool-panel.test.tsx b/packages/react/src/__tests__/tool-panel.test.tsx
index 84811f90..1d9fe4f5 100644
--- a/packages/react/src/__tests__/tool-panel.test.tsx
+++ b/packages/react/src/__tests__/tool-panel.test.tsx
@@ -20,6 +20,7 @@ import type {
 } from "../public_api";
 import type { PretableSurfaceGrid } from "../pretable-surface";
 import { ToolPanel } from "../tool-panel";
+import { PANE_MIN_WIDTH_PX } from "../tool-panel/pane-resize";
 import type {
   ToolPanelSectionDescriptor,
   ToolPanelSectionId,
@@ -82,7 +83,7 @@ function Host({
         setActive(next);
       }}
       paneWidthPx={null}
-      paneBounds={{ min: 186, max: null }}
+      paneBounds={{ min: PANE_MIN_WIDTH_PX, max: null }}
       onPaneWidthChange={() => {}}
       onPaneWidthReset={() => {}}
     />
diff --git a/packages/react/src/messages.ts b/packages/react/src/messages.ts
index 87ef9df4..d3cec093 100644
--- a/packages/react/src/messages.ts
+++ b/packages/react/src/messages.ts
@@ -73,6 +73,7 @@ export const defaultMessages: Required<PretableSurfaceMessages> = {
   toolPanelLabel: () => "Tool panel",
   toolPanelColumnsLabel: () => "Columns",
   toolPanelFiltersLabel: () => "Filters",
+  toolPanelResizeLabel: () => "Resize tool panel",
   toolPanelColumnGroupLabel: ({ pinned }) =>
     pinned === "left"
       ? "Pinned left"
@@ -117,7 +118,6 @@ export const defaultMessages: Required<PretableSurfaceMessages> = {
   toolPanelFilterJoinActionLabel: ({ opLabel, nextLabel }) =>
     `${opLabel}, join all conditions in this list with ${nextLabel}`,
   toolPanelGroupingLabel: () => "Grouping",
-  toolPanelResizeLabel: () => "Resize tool panel",
   toolPanelGroupByLabel: () => "Group by",
   toolPanelAddRowGroupLabel: () => "Add group",
   toolPanelRemoveGroupLabel: ({ label }) => `Remove grouping by ${label}`,
diff --git a/packages/react/src/tool-panel/ToolPanel.tsx b/packages/react/src/tool-panel/ToolPanel.tsx
index d30e00bb..3ef755f8 100644
--- a/packages/react/src/tool-panel/ToolPanel.tsx
+++ b/packages/react/src/tool-panel/ToolPanel.tsx
@@ -125,9 +125,13 @@ export function ToolPanel({
   // What the pane measures while it wears no inline width — the stylesheet
   // width, whatever the consumer's css says it is. This is aria-valuenow's
   // fallback and the origin of a drag or keystroke that starts from the
-  // untouched state; `null` where layout cannot answer (jsdom measures 0),
-  // in which case aria-valuenow is omitted rather than invented and the
-  // first gesture starts from the floor.
+  // untouched state; `null` where layout cannot answer (jsdom measures 0).
+  // Even then aria-valuenow is RENDERED, from the same floor the first
+  // gesture would step from: "omitted, not invented" was the first
+  // instinct here and it is wrong for this role — ARIA 1.2 requires
+  // aria-valuenow on a focusable separator, and an omitted value has AT
+  // assume now=50 of max=100 against a min of 186, an inverted range that
+  // axe's aria-required-attr flags.
   const [measuredPaneWidth, setMeasuredPaneWidth] = useState<number | null>(
     null,
   );
@@ -162,12 +166,17 @@ export function ToolPanel({
   // Escape mid-drag on a document listener, the register's pattern
   // (`useToolRowDrag`): pointer capture routes the MOVES here, but keyboard
   // events follow DOM focus, which a captured drag can leave anywhere. The
-  // handle's own keydown below handles the focused-on-the-handle case first
-  // and stops propagation — its comment carries the interlock with the
-  // pane's Escape-to-rail-tab courtesy; this listener is the catch-all for
-  // focus parked elsewhere, where `preventDefault` is what tells that pane
-  // handler (which skips defaultPrevented events) to stand down when it has
-  // not already run.
+  // handle's own keydown below covers the focused-on-the-handle case and
+  // stops propagation so the pane's Escape-to-rail-tab courtesy stays out
+  // of a mere gesture cancel; this listener covers focus OUTSIDE the pane.
+  // The one gap is focus on a pane control mid-drag: the pane's React
+  // handler runs before this document listener (React attaches at the root
+  // container, an ancestor document reaches later) and its stopPropagation
+  // starves this catch-all — that Escape yanks focus to the rail tab and
+  // the drag survives until release. Tolerated rather than fixed: reaching
+  // it takes pressing a pointer on the seam and then focusing a pane
+  // control by other means mid-hold, and the row drags share the exact
+  // ordering (their register documents the same characteristic).
   useEffect(() => {
     if (!dragActive) return;
     const onKeyDown = (event: KeyboardEvent) => {
@@ -270,10 +279,14 @@ export function ToolPanel({
             aria-orientation="vertical"
             aria-label={resizeLabel}
             aria-valuemin={paneBounds.min}
-            aria-valuemax={paneBounds.max ?? undefined}
-            // Omitted, not invented, while nothing has measured the pane —
-            // the untouched jsdom/SSR state has no truthful number to offer.
-            aria-valuenow={paneWidthPx ?? measuredPaneWidth ?? undefined}
+            // `currentWidth` — the number the first keystroke steps from —
+            // and a max that degrades to it while the surface is unmeasured:
+            // ARIA 1.2 requires valuenow on a focusable separator (see the
+            // `measuredPaneWidth` comment above), and an absent valuemax
+            // implies 100, under this min. A collapsed now=max range is the
+            // honest degraded shape until the ResizeObserver reports.
+            aria-valuemax={paneBounds.max ?? currentWidth}
+            aria-valuenow={currentWidth}
             tabIndex={0}
             data-pretable-pane-resize=""
             onPointerDown={handlePointerDown}

From 0590863bf9a2ce936d866a8b402209778a7b614f Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sun, 30 Aug 2026 13:45:14 -0700
Subject: [PATCH 07/11] feat(react): auto-width toggle in the columns section's
 row menu (SP5)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

B1: the kebab menu gains a role=menuitemcheckbox "Auto width" item,
checked from a live subscription over the facade's ɵautoWidths seam and
writing through setColumnAutoWidth. The item is a mode bit ("let the
grid manage this column's width"), never a content fit, and toggling
stays open — the native menuitemcheckbox pattern — while the pin items
keep their select-and-close command semantics.

B5: ColumnPinMenu sheds its stale name for ColumnRowMenu (it now holds a
non-pin item); ColumnPinMenuMessages follows. New message key
toolPanelAutoWidthLabel in the three established places. The Task 1 test
header's lingering "content-tracking mode" phrase is corrected to the
amended spec's mode-bit wording. B3 (auto-size-all footer) is dropped
per the amended spec.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../src/__tests__/column-auto-width.test.tsx  |   3 +-
 .../src/__tests__/filter-builder.test.tsx     |   2 +-
 .../react/src/__tests__/tool-panel.test.tsx   | 184 +++++++++++++++++-
 packages/react/src/messages.ts                |   1 +
 packages/react/src/overlay/menu-keyboard.ts   |   2 +-
 packages/react/src/pretable-surface.tsx       |  29 ++-
 .../{ColumnPinMenu.tsx => ColumnRowMenu.tsx}  |  39 +++-
 .../react/src/tool-panel/ColumnsSection.tsx   |  36 +++-
 .../src/tool-panel/filters/JoinControl.tsx    |   4 +-
 .../src/tool-panel/grouping/AddGroupMenu.tsx  |   2 +-
 packages/react/src/tool-panel/messages.ts     |   8 +-
 packages/ui/grid.css                          |  11 ++
 12 files changed, 292 insertions(+), 29 deletions(-)
 rename packages/react/src/tool-panel/{ColumnPinMenu.tsx => ColumnRowMenu.tsx} (60%)

diff --git a/packages/react/src/__tests__/column-auto-width.test.tsx b/packages/react/src/__tests__/column-auto-width.test.tsx
index e369c567..c9b50239 100644
--- a/packages/react/src/__tests__/column-auto-width.test.tsx
+++ b/packages/react/src/__tests__/column-auto-width.test.tsx
@@ -126,7 +126,8 @@ describe("column auto width", () => {
       h.grid.setColumnAutoWidth("fixed", true);
     });
     // The drawn width leaves the engine's stored value for the renderer's
-    // content-tracking mode (its fallback in jsdom, where nothing measures).
+    // own default — auto is a MODE BIT handing the renderer ownership (spec
+    // Fact 2); nothing measures content anywhere in this path.
     expect(h.drawnWidth("fixed")).toBe(RENDERER_AUTO_WIDTH);
     // Non-destructive: the engine still remembers the declared width.
     expect(h.engineWidth("fixed")).toBe(DECLARED_WIDTH);
diff --git a/packages/react/src/__tests__/filter-builder.test.tsx b/packages/react/src/__tests__/filter-builder.test.tsx
index 83fd59d5..7dc17633 100644
--- a/packages/react/src/__tests__/filter-builder.test.tsx
+++ b/packages/react/src/__tests__/filter-builder.test.tsx
@@ -170,7 +170,7 @@ describe("JoinControl", () => {
   });
 
   /* SC 2.5.3 Label in Name — the assertion this suite was missing. The
-     component's TSDoc carries the reasoning, including why `ColumnPinMenu`
+     component's TSDoc carries the reasoning, including why `ColumnRowMenu`
      is no precedent for a bare next-value name. */
   it.each(["and", "or"] as const)(
     "contains its visible text `%s` in its accessible name",
diff --git a/packages/react/src/__tests__/tool-panel.test.tsx b/packages/react/src/__tests__/tool-panel.test.tsx
index 1d9fe4f5..f32c6145 100644
--- a/packages/react/src/__tests__/tool-panel.test.tsx
+++ b/packages/react/src/__tests__/tool-panel.test.tsx
@@ -803,12 +803,21 @@ describe("columns section pin menu", () => {
       "Pin left",
       "Pin right",
       "Unpin",
+      "Auto width",
     ]);
-    for (const item of items) {
+    // The pin items are commands; the trailing auto-width item is the menu's
+    // one checkbox (SP5) — its own describe covers the toggle behavior.
+    for (const item of items.slice(0, 3)) {
       expect(item).toHaveAttribute("role", "menuitem");
     }
+    expect(items[3]).toHaveAttribute("role", "menuitemcheckbox");
     // Bravo is unpinned, so Unpin is the current state.
-    expect(items.map((item) => item.disabled)).toEqual([false, false, true]);
+    expect(items.map((item) => item.disabled)).toEqual([
+      false,
+      false,
+      true,
+      false,
+    ]);
   });
 
   it("disables the matching pin item for an already-pinned column", () => {
@@ -819,6 +828,7 @@ describe("columns section pin menu", () => {
       true,
       false,
       false,
+      false,
     ]);
   });
 
@@ -891,17 +901,20 @@ describe("columns section pin menu", () => {
   it("focuses the first enabled item on open and roves with ArrowDown/ArrowUp, skipping the disabled item", () => {
     const h = mountColumnsSection();
     openKebab(h.kebabFor("Bravo")!);
-    const [pinLeft, pinRight, unpin] = h.menuItems();
+    const [pinLeft, pinRight, unpin, autoWidth] = h.menuItems();
     expect(pinLeft).toHaveFocus();
     expect(unpin!.disabled).toBe(true);
 
     fireEvent.keyDown(pinLeft!, { key: "ArrowDown" });
     expect(pinRight).toHaveFocus();
-    // Wraps past the disabled Unpin back to the top.
+    // Skips the disabled Unpin to the auto-width toggle (SP5)…
     fireEvent.keyDown(pinRight!, { key: "ArrowDown" });
+    expect(autoWidth).toHaveFocus();
+    // …then wraps back to the top, and reverses the same way.
+    fireEvent.keyDown(autoWidth!, { key: "ArrowDown" });
     expect(pinLeft).toHaveFocus();
     fireEvent.keyDown(pinLeft!, { key: "ArrowUp" });
-    expect(pinRight).toHaveFocus();
+    expect(autoWidth).toHaveFocus();
   });
 
   it("follows its kebab through a scroll of the list box, and closes when the anchor scrolls off-screen", () => {
@@ -962,6 +975,160 @@ describe("columns section pin menu", () => {
   });
 });
 
+/* ---- SP5 Task 3: the row menu's auto-width toggle ----------------------- */
+
+/**
+ * The semantic under test is the MODE BIT, not a content fit (spec Fact 2):
+ * auto membership means the RENDERER owns the drawn width (its 140px
+ * fallback in jsdom, or a flex share), while manual means the ENGINE's
+ * stored width draws. Nothing measures cell content anywhere in this path,
+ * so every width assertion below reads which OWNER the drawn header width
+ * follows — never a fit-to-content claim.
+ */
+describe("columns section row menu — auto width toggle", () => {
+  /** One declared width (manual at mount), one undeclared (auto at mount). */
+  const widthColumns: PretableColumn<SectionRow>[] = [
+    { id: "a", header: "Alpha", widthPx: 120 },
+    { id: "b", header: "Bravo" },
+  ];
+  /** renderer-dom's `FIXED_COLUMN_WIDTH` — what an auto column draws at. */
+  const RENDERER_AUTO_WIDTH = 140;
+  /** grid-core's `DEFAULT_COLUMN_WIDTH_PX` — the engine's store for "b". */
+  const ENGINE_DEFAULT_WIDTH = 160;
+
+  const drawnWidth = (
+    h: ReturnType<typeof mountColumnsSection>,
+    columnId: string,
+  ) => {
+    const cell = h.view.container.querySelector(
+      `[data-pretable-header-cell][data-pretable-column-id="${columnId}"]`,
+    ) as HTMLElement | null;
+    if (cell === null) throw new Error(`No header cell for ${columnId}`);
+    return Number.parseFloat(cell.style.width.replace("px", ""));
+  };
+
+  const autoWidthItem = (h: ReturnType<typeof mountColumnsSection>) => {
+    const item = h
+      .menuItems()
+      .find((candidate) => candidate.textContent === "Auto width");
+    if (item === undefined) throw new Error("No Auto width item in the menu");
+    return item;
+  };
+
+  it("reflects the live set: a declared-width column opens unchecked, an undeclared one checked", () => {
+    const h = mountColumnsSection({ columns: widthColumns });
+    openKebab(h.kebabFor("Alpha")!);
+    let item = autoWidthItem(h);
+    expect(item).toHaveAttribute("role", "menuitemcheckbox");
+    expect(item).toHaveAttribute("aria-checked", "false");
+    fireEvent.keyDown(item, { key: "Escape" });
+
+    openKebab(h.kebabFor("Bravo")!);
+    item = autoWidthItem(h);
+    expect(item).toHaveAttribute("role", "menuitemcheckbox");
+    expect(item).toHaveAttribute("aria-checked", "true");
+  });
+
+  it("toggling flips the PRESSED row's column only, stays open, and aria-checked follows live", () => {
+    const h = mountColumnsSection({ columns: widthColumns });
+    // Mount state: "a" manual at its declared width, "b" auto at the
+    // renderer's default.
+    expect(drawnWidth(h, "a")).toBe(120);
+    expect(drawnWidth(h, "b")).toBe(RENDERER_AUTO_WIDTH);
+
+    openKebab(h.kebabFor("Bravo")!);
+    const item = autoWidthItem(h);
+    fireEvent.click(item);
+
+    // Checkbox semantics: the toggle applied and the menu STAYED open, its
+    // aria-checked state updated in place (the pin items close; a mode bit
+    // does not — the native menuitemcheckbox pattern).
+    expect(h.menu()).not.toBeNull();
+    expect(autoWidthItem(h)).toHaveAttribute("aria-checked", "false");
+    // Off ⇒ manual at the ENGINE's stored width (its 160 default — the
+    // props declared none), and the OTHER column is untouched: the write
+    // carried the pressed row's id, not some fixed one.
+    expect(drawnWidth(h, "b")).toBe(ENGINE_DEFAULT_WIDTH);
+    expect(drawnWidth(h, "a")).toBe(120);
+
+    // And back on: the renderer owns the width again.
+    fireEvent.click(autoWidthItem(h));
+    expect(h.menu()).not.toBeNull();
+    expect(autoWidthItem(h)).toHaveAttribute("aria-checked", "true");
+    expect(drawnWidth(h, "b")).toBe(RENDERER_AUTO_WIDTH);
+  });
+
+  it("turning auto ON hands a declared-width column to the renderer, without erasing the store", () => {
+    const h = mountColumnsSection({ columns: widthColumns });
+    openKebab(h.kebabFor("Alpha")!);
+    fireEvent.click(autoWidthItem(h));
+
+    expect(drawnWidth(h, "a")).toBe(RENDERER_AUTO_WIDTH);
+    // Non-destructive: the engine still remembers the declared width, so
+    // toggling back off restores 120, not a default.
+    fireEvent.click(autoWidthItem(h));
+    expect(drawnWidth(h, "a")).toBe(120);
+  });
+
+  it("is reachable by arrow roving, toggles from the keyboard focus, and Escape still closes with focus return", () => {
+    const h = mountColumnsSection({ columns: widthColumns });
+    const kebab = h.kebabFor("Bravo")!;
+    openKebab(kebab);
+    const [first] = h.menuItems();
+    expect(first).toHaveFocus();
+
+    // ArrowUp wraps from the first enabled item to the LAST — the toggle.
+    fireEvent.keyDown(first!, { key: "ArrowUp" });
+    const item = autoWidthItem(h);
+    expect(item).toHaveFocus();
+
+    // Activation: a native <button> synthesizes click from Enter/Space, so
+    // the click event IS the keyboard activation path jsdom can exercise.
+    fireEvent.click(item);
+    expect(h.menu()).not.toBeNull();
+    expect(autoWidthItem(h)).toHaveFocus();
+    expect(autoWidthItem(h)).toHaveAttribute("aria-checked", "false");
+
+    fireEvent.keyDown(autoWidthItem(h), { key: "Escape" });
+    expect(h.menu()).toBeNull();
+    expect(kebab).toHaveFocus();
+  });
+
+  it("a manual setColumnWidth shows unchecked on next open (old behavior reflected)", () => {
+    const h = mountColumnsSection({ columns: widthColumns });
+    act(() => h.grid.setColumnWidth("b", 200));
+    expect(drawnWidth(h, "b")).toBe(200);
+
+    openKebab(h.kebabFor("Bravo")!);
+    expect(autoWidthItem(h)).toHaveAttribute("aria-checked", "false");
+  });
+
+  it("Reset columns restores the initial auto set through the UI, both directions", () => {
+    const h = mountColumnsSection({ columns: widthColumns });
+    // Drift both ways through the menu itself.
+    openKebab(h.kebabFor("Alpha")!);
+    fireEvent.click(autoWidthItem(h)); // "a": manual → auto
+    fireEvent.keyDown(autoWidthItem(h), { key: "Escape" });
+    openKebab(h.kebabFor("Bravo")!);
+    fireEvent.click(autoWidthItem(h)); // "b": auto → manual
+    fireEvent.keyDown(autoWidthItem(h), { key: "Escape" });
+    expect(drawnWidth(h, "a")).toBe(RENDERER_AUTO_WIDTH);
+    expect(drawnWidth(h, "b")).toBe(ENGINE_DEFAULT_WIDTH);
+
+    fireEvent.click(h.reset());
+
+    // "a" declared a width → back to manual at it; "b" declared none →
+    // back to auto at the renderer's width.
+    expect(drawnWidth(h, "a")).toBe(120);
+    expect(drawnWidth(h, "b")).toBe(RENDERER_AUTO_WIDTH);
+    openKebab(h.kebabFor("Alpha")!);
+    expect(autoWidthItem(h)).toHaveAttribute("aria-checked", "false");
+    fireEvent.keyDown(autoWidthItem(h), { key: "Escape" });
+    openKebab(h.kebabFor("Bravo")!);
+    expect(autoWidthItem(h)).toHaveAttribute("aria-checked", "true");
+  });
+});
+
 /* ---- Task 9: drag reorder + keyboard alternative ------------------------ */
 
 /** The row's drag handle, focusable since Task 9. */
@@ -1703,16 +1870,17 @@ describe("tool panel messages", () => {
     errors.mockRestore();
   });
 
-  it("threads the pin menu's strings, portal and all", () => {
+  it("threads the row menu's strings, portal and all", () => {
     const view = render(
       <PretableSurface
-        ariaLabel="Pin menu messages grid"
+        ariaLabel="Row menu messages grid"
         columns={sectionColumns}
         rows={sectionRows}
         getRowId={(r: SectionRow) => r.id}
         messages={{
           toolPanelColumnMenuLabel: ({ label }) => `MENU:${label}`,
           toolPanelPinLabel: ({ pinned }) => `PIN:${pinned}`,
+          toolPanelAutoWidthLabel: () => "AUTO",
         }}
         toolPanel={{ defaultActiveSection: "columns" }}
         viewportHeight={300}
@@ -1736,7 +1904,7 @@ describe("tool panel messages", () => {
       Array.from(document.querySelectorAll("[data-pretable-menu-item]")).map(
         (item) => item.textContent,
       ),
-    ).toEqual(["PIN:left", "PIN:right", "PIN:null"]);
+    ).toEqual(["PIN:left", "PIN:right", "PIN:null", "AUTO"]);
   });
 
   it("threads every filters-section string, including the join sentence, to the DOM", () => {
diff --git a/packages/react/src/messages.ts b/packages/react/src/messages.ts
index d3cec093..d8b67add 100644
--- a/packages/react/src/messages.ts
+++ b/packages/react/src/messages.ts
@@ -89,6 +89,7 @@ export const defaultMessages: Required<PretableSurfaceMessages> = {
   toolPanelColumnMenuLabel: ({ label }) => `${label} column menu`,
   toolPanelPinLabel: ({ pinned }) =>
     pinned === "left" ? "Pin left" : pinned === "right" ? "Pin right" : "Unpin",
+  toolPanelAutoWidthLabel: () => "Auto width",
   toolPanelAddFilterLabel: () => "+ filter",
   toolPanelAddGroupLabel: () => "+ group",
   toolPanelNoFiltersMessage: () =>
diff --git a/packages/react/src/overlay/menu-keyboard.ts b/packages/react/src/overlay/menu-keyboard.ts
index 2647324d..ed908d83 100644
--- a/packages/react/src/overlay/menu-keyboard.ts
+++ b/packages/react/src/overlay/menu-keyboard.ts
@@ -4,7 +4,7 @@ import { useEffect, useRef } from "react";
 /**
  * The shared `role="menu"` behavior for the tool panel's popovers — one home
  * for the keyboard-and-dismissal contract every list-shaped menu owes, so it
- * cannot be hand-rolled per menu and drift (extracted from `ColumnPinMenu`,
+ * cannot be hand-rolled per menu and drift (extracted from `ColumnRowMenu`,
  * now also serving `AddGroupMenu`):
  *
  * - The first ENABLED item takes focus on mount — a menu opened from a
diff --git a/packages/react/src/pretable-surface.tsx b/packages/react/src/pretable-surface.tsx
index 32ddc963..e6d28e59 100644
--- a/packages/react/src/pretable-surface.tsx
+++ b/packages/react/src/pretable-surface.tsx
@@ -714,6 +714,12 @@ export interface PretableSurfaceMessages {
    * the family, as `toolPanelColumnGroupLabel` is.
    */
   toolPanelPinLabel?: (args: { pinned: "left" | "right" | null }) => string;
+  /**
+   * The row menu's auto-width toggle. Named for the real semantic — "let the
+   * grid manage this column's width" (a mode bit), NOT a fit-to-content
+   * action, which no machinery here computes.
+   */
+  toolPanelAutoWidthLabel?: () => string;
 
   // ---- Tool panel: filters section ----------------------------------------
 
@@ -2051,6 +2057,9 @@ export function PretableSurface<
         defaultMessages.toolPanelColumnMenuLabel,
       toolPanelPinLabel:
         messages?.toolPanelPinLabel ?? defaultMessages.toolPanelPinLabel,
+      toolPanelAutoWidthLabel:
+        messages?.toolPanelAutoWidthLabel ??
+        defaultMessages.toolPanelAutoWidthLabel,
       toolPanelAddFilterLabel:
         messages?.toolPanelAddFilterLabel ??
         defaultMessages.toolPanelAddFilterLabel,
@@ -2623,11 +2632,17 @@ export function PretableSurface<
   // the same reason. At first render the set is exactly the store's
   // constructor rule — "columns without a declared `widthPx`" — read from
   // the store itself rather than re-derived here, so the rule has one home.
+  // The facade's internal auto-width read seam, unwrapped once: the reader
+  // object is created with the facade and shares its lifetime, so this is a
+  // STABLE HANDLE by the descriptor memo's DEPS RULE — the SET behind it is
+  // engine-ish state that consumers (the columns section's toggle, the
+  // capture below) reach through subscribe/getState, never as a baked value.
+  const autoWidthReader = (
+    indexedGrid as unknown as { readonly ɵautoWidths: AutoWidthSetReader }
+  ).ɵautoWidths;
   const initialAutoWidthIdsRef = useRef<ReadonlySet<string>>(null);
   if (initialAutoWidthIdsRef.current === null) {
-    initialAutoWidthIdsRef.current = (
-      indexedGrid as unknown as { readonly ɵautoWidths: AutoWidthSetReader }
-    ).ɵautoWidths.getState();
+    initialAutoWidthIdsRef.current = autoWidthReader.getState();
   }
   // The cell-edit controller owns a token for its UI lifecycle, but explicit
   // model writes happen inside its awaited commit callback — before the
@@ -3979,7 +3994,8 @@ export function PretableSurface<
   );
   // The tool panel's BUILT-IN section descriptors. The deps are HANDLES and
   // props-derived values, never engine state: `indexedGrid`,
-  // `indexed.rowModel` and `initialColumnLayoutRef` are stable for the model's
+  // `indexed.rowModel`, `autoWidthReader` (a subscribe/getState pair, not the
+  // set it reads) and `initialColumnLayoutRef` are stable for the model's
   // lifetime; `loadDistinctValues` and `setFilterTree` are `useCallback`s over
   // those same handles; `labelForColumn` and `filterSectionColumns` change
   // identity exactly when the `columns` prop does (which is when labels can
@@ -4006,7 +4022,8 @@ export function PretableSurface<
   // state, so no memoized descriptor can hand a section a stale snapshot, and
   // both sections stay live by their own means: the columns section
   // subscribes to the engine itself (`useSyncExternalStore` over the layout
-  // slice), and the filters section subscribes to the row model for the
+  // slice, and over `autoWidthReader` for the auto-width set its row menu
+  // reflects), and the filters section subscribes to the row model for the
   // filter tree while its TWO pieces of engine state — which columns are
   // hidden, and which are grouped away under `hideGroupedColumns` — are read
   // afresh inside `render()` on every tool-panel render.
@@ -4023,6 +4040,7 @@ export function PretableSurface<
         label: effectiveMessages.toolPanelColumnsLabel(),
         render: () => (
           <ColumnsSection
+            autoWidths={autoWidthReader}
             grid={indexedGrid}
             initialAutoWidthRef={initialAutoWidthIdsRef}
             initialLayoutRef={initialColumnLayoutRef}
@@ -4116,6 +4134,7 @@ export function PretableSurface<
     ],
     [
       applyRowGroups,
+      autoWidthReader,
       effectiveMessages,
       filterSectionColumns,
       groupingSectionColumns,
diff --git a/packages/react/src/tool-panel/ColumnPinMenu.tsx b/packages/react/src/tool-panel/ColumnRowMenu.tsx
similarity index 60%
rename from packages/react/src/tool-panel/ColumnPinMenu.tsx
rename to packages/react/src/tool-panel/ColumnRowMenu.tsx
index b02dc1de..f8cf5013 100644
--- a/packages/react/src/tool-panel/ColumnPinMenu.tsx
+++ b/packages/react/src/tool-panel/ColumnRowMenu.tsx
@@ -1,8 +1,9 @@
 import { createElement, type CSSProperties } from "react";
 
+import { CheckIcon } from "../icons";
 import { useMenuKeyboard } from "../overlay/menu-keyboard";
 import { OverlayPortal } from "../overlay/OverlayPortal";
-import type { ColumnPinMenuMessages } from "./messages";
+import type { ColumnRowMenuMessages } from "./messages";
 
 /**
  * The three placements, in menu order. Structure only — the item's WORDS come
@@ -16,7 +17,8 @@ const PIN_MENU_ITEMS = [
 ] as const;
 
 /**
- * The kebab's popover: three pin placements, the row's current one disabled.
+ * The columns-section row's kebab popover: the three pin placements (the
+ * row's current one disabled) and the auto-width toggle.
  *
  * Portaled for the same reason every popover here is — the grid viewport's
  * `contain: content` makes it the containing block for `position: fixed`
@@ -27,28 +29,42 @@ const PIN_MENU_ITEMS = [
  * rules, and `useMenuKeyboard` for the focus/keyboard/dismissal contract
  * every list-shaped menu here shares.
  *
+ * Two activation behaviors on purpose. A pin item is a one-shot placement
+ * COMMAND — selecting it closes the menu (`onSelect`, and the row moves out
+ * from under the anchor anyway). The auto-width item is a `menuitemcheckbox`
+ * MODE BIT — toggling it stays open, the native menuitemcheckbox pattern, so
+ * the flip is visible where it was made and can be flipped straight back.
+ * Its `aria-checked` updates live while open because the section re-renders
+ * this menu from its auto-set subscription on every store publish.
+ *
  * Focus return is the CALLER's job, via `onClose`/`onSelect`: a pin change
  * moves the row across subgroup fragments, remounting the kebab, so only the
  * section (with its per-id node map) can find the button again.
  */
-export function ColumnPinMenu({
+export function ColumnRowMenu({
   columnId,
   label,
   pinned,
+  autoWidth,
   style,
   onSelect,
+  onToggleAutoWidth,
   onClose,
   messages,
 }: {
   columnId: string;
   label: string;
   pinned: "left" | "right" | null;
+  /** Live auto-set membership — the checkbox's checked state. */
+  autoWidth: boolean;
   style?: CSSProperties;
   onSelect: (pinned: "left" | "right" | null) => void;
+  /** Flips the column's auto-width mode bit; the menu stays open. */
+  onToggleAutoWidth: () => void;
   /** `restoreFocus` false only for outside clicks, which chose a new target. */
   onClose: (restoreFocus: boolean) => void;
   /** Resolved surface messages — this component defaults no string itself. */
-  messages: ColumnPinMenuMessages;
+  messages: ColumnRowMenuMessages;
 }) {
   const { rootRef, onKeyDown } = useMenuKeyboard(onClose);
 
@@ -77,6 +93,21 @@ export function ColumnPinMenu({
             {messages.toolPanelPinLabel({ pinned: item.pinned })}
           </button>
         ))}
+        {/* "Let the grid manage this column's width" — a mode bit over the
+            auto-width store, NOT a fit-to-content action (spec B1/Fact 2).
+            The check glyph trails the label so the label's position is
+            identical in both states with no reserved leading slot. */}
+        <button
+          type="button"
+          role="menuitemcheckbox"
+          aria-checked={autoWidth}
+          data-pretable-menu-item=""
+          data-pretable-menu-action="auto-width"
+          onClick={onToggleAutoWidth}
+        >
+          {messages.toolPanelAutoWidthLabel()}
+          {autoWidth ? <CheckIcon /> : null}
+        </button>
       </div>
     </OverlayPortal>
   );
diff --git a/packages/react/src/tool-panel/ColumnsSection.tsx b/packages/react/src/tool-panel/ColumnsSection.tsx
index fb9a0467..61120627 100644
--- a/packages/react/src/tool-panel/ColumnsSection.tsx
+++ b/packages/react/src/tool-panel/ColumnsSection.tsx
@@ -13,9 +13,10 @@ import { GROUP_COLUMN_ID } from "@pretable/core";
 
 import { ROW_SELECT_COLUMN_ID } from "../constants";
 import { CheckIcon, GripIcon, OverflowIcon } from "../icons";
+import type { AutoWidthSetReader } from "../pretable-model";
 import { popoverStyle } from "../overlay/popover-position";
 import { useHeaderPopover } from "../overlay/useHeaderPopover";
-import { ColumnPinMenu } from "./ColumnPinMenu";
+import { ColumnRowMenu } from "./ColumnRowMenu";
 import type { ToolPanelColumnsMessages } from "./messages";
 import type { ToolDropTarget, ToolRowRect } from "./tool-panel-drop-target";
 import { useToolRowDrag } from "./useToolRowDrag";
@@ -80,6 +81,13 @@ export interface ColumnsSectionProps {
    * to auto and every other replayed id to manual.
    */
   readonly initialAutoWidthRef: RefObject<ReadonlySet<string> | null>;
+  /**
+   * The facade's `ɵautoWidths` read seam (see {@link AutoWidthSetReader}) —
+   * a stable handle, so the descriptor memo's DEPS RULE holds: the SET is
+   * engine-ish state and is reached only through this subscription, never
+   * baked into a closure. The row menu's toggle reflects it live.
+   */
+  readonly autoWidths: AutoWidthSetReader;
   /** Resolved surface messages — this section defaults no string itself. */
   readonly messages: ToolPanelColumnsMessages;
 }
@@ -107,6 +115,7 @@ export function ColumnsSection({
   labelForColumn,
   initialLayoutRef,
   initialAutoWidthRef,
+  autoWidths,
   messages,
 }: ColumnsSectionProps) {
   // Live engine state, read through the section's OWN subscription — never a
@@ -117,6 +126,17 @@ export function ColumnsSection({
   const readLayout = useCallback(() => grid.getState().columnLayout, [grid]);
   const layout = useSyncExternalStore(grid.subscribe, readLayout, readLayout);
 
+  // The auto-width set, by its own subscription for the layout's reason: the
+  // row menu's toggle must REFLECT membership while it is open, and the
+  // store hands back the same Set identity until a membership change (writes
+  // that change nothing publish nothing), so unrelated renders bail in
+  // useSyncExternalStore's equality check.
+  const autoWidthSet = useSyncExternalStore(
+    autoWidths.subscribe,
+    autoWidths.getState,
+    autoWidths.getState,
+  );
+
   // Local, deliberately: the section unmounts when the pane closes, and a
   // reopened pane starting from an empty search is the expected behavior.
   const [query, setQuery] = useState("");
@@ -533,13 +553,25 @@ export function ColumnsSection({
         const open = matched.find(({ entry }) => entry.id === menu.columnId);
         if (open === undefined) return null;
         return (
-          <ColumnPinMenu
+          <ColumnRowMenu
+            autoWidth={autoWidthSet.has(open.entry.id)}
             columnId={open.entry.id}
             label={open.label}
             pinned={open.entry.pinned ?? null}
             messages={messages}
             style={popoverStyle(menu.rect)}
             onClose={closeMenu}
+            // The menu stays open (its comment carries the checkbox-vs-
+            // command rationale), so no pending-focus arming here: the row
+            // does not move and the kebab does not remount. The store's
+            // publish re-renders this section, which re-renders the open
+            // menu with the flipped `autoWidth`.
+            onToggleAutoWidth={() => {
+              grid.setColumnAutoWidth(
+                open.entry.id,
+                !autoWidthSet.has(open.entry.id),
+              );
+            }}
             onSelect={(pinned) => {
               grid.setColumnPinned(open.entry.id, pinned);
               closeMenuState();
diff --git a/packages/react/src/tool-panel/filters/JoinControl.tsx b/packages/react/src/tool-panel/filters/JoinControl.tsx
index 4cad84ac..5c7f7f65 100644
--- a/packages/react/src/tool-panel/filters/JoinControl.tsx
+++ b/packages/react/src/tool-panel/filters/JoinControl.tsx
@@ -57,14 +57,14 @@ const other = (op: Join): Join => (op === "and" ? "or" : "and");
  * Without it the accessibility tree simply omits what every sighted user can
  * read, and a screen-reader user cannot tell what the run currently is.
  *
- * `ColumnPinMenu`, whose voice this follows, is safe from all of the above by
+ * `ColumnRowMenu`, whose voice this follows, is safe from all of the above by
  * MECHANISM, not by wording: its items carry no `aria-label` at all, so their
  * visible text is their accessible name and cannot drift from it.
  *
  * ## Not `aria-pressed`
  *
  * The button sets a value, it does not toggle itself on and off — the same
- * distinction that makes `ColumnPinMenu`'s items read `Pin left` / `Unpin`
+ * distinction that makes `ColumnRowMenu`'s items read `Pin left` / `Unpin`
  * (what will happen) rather than a pressed state. `aria-pressed` here would
  * announce a state that does not exist alongside a name that already says
  * what the press does.
diff --git a/packages/react/src/tool-panel/grouping/AddGroupMenu.tsx b/packages/react/src/tool-panel/grouping/AddGroupMenu.tsx
index dcdb442c..78f03df6 100644
--- a/packages/react/src/tool-panel/grouping/AddGroupMenu.tsx
+++ b/packages/react/src/tool-panel/grouping/AddGroupMenu.tsx
@@ -15,7 +15,7 @@ import type { GroupingSectionMessages } from "../messages";
  * `contain: content` makes it the containing block for `position: fixed`
  * descendants AND clips them — and it wears the popover contract's styling
  * attributes (`data-pretable-popover` + `data-pretable-column-menu` on the
- * container, `data-pretable-menu-item` on items) exactly as `ColumnPinMenu`
+ * container, `data-pretable-menu-item` on items) exactly as `ColumnRowMenu`
  * does, so grid.css styles it with zero new rules.
  * `data-pretable-add-group-menu` is its own identity on top: this is not a
  * per-column menu, and a test or consumer must be able to tell it from one.
diff --git a/packages/react/src/tool-panel/messages.ts b/packages/react/src/tool-panel/messages.ts
index 09cdebff..a410ad76 100644
--- a/packages/react/src/tool-panel/messages.ts
+++ b/packages/react/src/tool-panel/messages.ts
@@ -27,13 +27,13 @@ type Resolved<K extends keyof PretableSurfaceMessages> = Required<
   Pick<PretableSurfaceMessages, K>
 >;
 
-/** The pin menu names its three placements and itself. */
-export type ColumnPinMenuMessages = Resolved<
-  "toolPanelColumnMenuLabel" | "toolPanelPinLabel"
+/** The row menu names its pin placements, its auto-width toggle and itself. */
+export type ColumnRowMenuMessages = Resolved<
+  "toolPanelColumnMenuLabel" | "toolPanelPinLabel" | "toolPanelAutoWidthLabel"
 >;
 
 /** The columns section — the pin menu's keys included, since it renders one. */
-export type ToolPanelColumnsMessages = ColumnPinMenuMessages &
+export type ToolPanelColumnsMessages = ColumnRowMenuMessages &
   Resolved<
     | "toolPanelColumnGroupLabel"
     | "toolPanelSearchColumnsLabel"
diff --git a/packages/ui/grid.css b/packages/ui/grid.css
index c7252c9d..71a5d06c 100644
--- a/packages/ui/grid.css
+++ b/packages/ui/grid.css
@@ -1118,6 +1118,17 @@
     outline: 2px solid var(--pretable-focus-ring);
     outline-offset: -2px;
   }
+  /* A checkbox item (the row menu's auto-width toggle) lays its check glyph
+     out on the trailing edge; the label keeps the block items' left
+     alignment in both states, so no leading slot is reserved. The glyph is
+     a CheckIcon — [data-pretable-icon] already sizes it. Selected by role,
+     not a new data attribute: aria is the checkbox contract's own marker. */
+  :where([data-pretable-menu-item][role="menuitemcheckbox"]) {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 8px;
+  }
 
   /* Enum combobox listbox (cell editor) */
   :where([data-pretable-enum-editor]) {

From 19e5bc28f3b5c5284318b4cc7cd54297f97637da Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sun, 30 Aug 2026 13:48:44 -0700
Subject: [PATCH 08/11] docs: purge the last content-tracking phrases from the
 SP5 spec

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../specs/2026-08-30-tool-panel-resize-autosize.md    | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/docs/superpowers/specs/2026-08-30-tool-panel-resize-autosize.md b/docs/superpowers/specs/2026-08-30-tool-panel-resize-autosize.md
index 06bd19ef..189d2623 100644
--- a/docs/superpowers/specs/2026-08-30-tool-panel-resize-autosize.md
+++ b/docs/superpowers/specs/2026-08-30-tool-panel-resize-autosize.md
@@ -135,8 +135,9 @@ directory conventions). No-backcompat repo; internal component.
 B6. **Interaction with manual resize, documented not fought**: dragging a
 column's header resize strip (or the pane's setColumnWidth path)
 already flips auto off — the toggle reflects that on next open. The
-docs state the pair plainly: auto tracks content until you size the
-column yourself; the toggle turns tracking back on.
+docs state the pair plainly in the MODE-BIT wording: the grid manages
+the width until you size the column yourself; the toggle hands the
+width back to the grid.
 
 ## Verification
 
@@ -153,9 +154,9 @@ column yourself; the toggle turns tracking back on.
   spec's existing pattern).
 - **B (auto width):** jsdom — the toggle reflects the live set (a column
   with declared width starts unchecked; one without starts checked);
-  toggling on makes a content change ACTUALLY change the drawn width
-  (disprove-capable: two contents with different widths — assert the
-  header cell's width moves, not that a method was called); toggling off
+  toggling on hands the width to the renderer (assert the drawn header
+  width moves to the renderer's value — 140/flex — not that a method
+  was called); toggling off
   freezes it at the engine's stored width; manual header resize
   unchecks it on next open; Reset restores the initial set (B4, both
   directions). The drawn-width proof asserts the REAL semantic: auto ⇒

From a3d2314a9c6b91b623093059023136a086aaf9e3 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sun, 30 Aug 2026 14:01:55 -0700
Subject: [PATCH 09/11] test(e2e): pane resize and auto width through the real
 shell (SP5)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 apps/website/e2e/tool-panel.spec.ts | 330 +++++++++++++++++++++++++---
 1 file changed, 304 insertions(+), 26 deletions(-)

diff --git a/apps/website/e2e/tool-panel.spec.ts b/apps/website/e2e/tool-panel.spec.ts
index e1c77c60..5384b742 100644
--- a/apps/website/e2e/tool-panel.spec.ts
+++ b/apps/website/e2e/tool-panel.spec.ts
@@ -4,12 +4,13 @@ import { waitForGridReady, waitForStablePosition } from "./helpers";
 
 /**
  * The tool panel, driven with a real pointer and a real keyboard — the
- * halves jsdom cannot express. Four blocks, each with its own target page:
+ * halves jsdom cannot express. Five blocks, each with its own target page:
  * the COLUMNS section (this opening block, on the keyboard-navigation
  * example), the FILTERS section (SP2b, on /docs/grid/tool-panel), the
  * GROUPING section (SP3b, on /fixtures/grouping plus the keyboard example),
- * and a consumer-supplied CUSTOM section (SP4, on
- * /fixtures/tool-panel-sections). The later blocks open with banner
+ * a consumer-supplied CUSTOM section (SP4, on
+ * /fixtures/tool-panel-sections), and PANE RESIZING + AUTO WIDTH (SP5, on
+ * the keyboard example and the filters example). The later blocks open with banner
  * comments naming their targets and why; what every block proves is the
  * same kind of thing — the measured DOM the handlers feed, the engine
  * commits, and the panel's tab order all behave on a live page, while the
@@ -608,12 +609,17 @@ test("filters: the pane is walkable and forward-Tab still exits the panel", asyn
       return "other";
     }, PARTS);
 
-  // Walk forward from the row's first control. Bounded: a trap would run the
-  // loop out rather than hang, and the assertions below name what it saw.
-  await filtersFigure(page)
-    .locator("[data-pretable-filter-row-column]")
-    .focus();
-  const seen: string[] = [await whereFocusIs()];
+  // Walk forward from the pane's FIRST stop — the resize handle (SP5), which
+  // sits before every section's content. Starting there rather than on the
+  // row's first control makes the walk itself prove the handle chains into
+  // the section: one Tab off the handle must land the row's column select.
+  // Update this start point if the pane ever gains an earlier stop.
+  const resizeHandle = filtersFigure(page).locator(
+    "[data-pretable-pane-resize]",
+  );
+  await resizeHandle.focus();
+  await expect(resizeHandle).toBeFocused();
+  const seen: string[] = [];
   let escaped = false;
   for (let i = 0; i < 20; i++) {
     await page.keyboard.press("Tab");
@@ -866,14 +872,16 @@ test("grouping: arrows reach its rail tab, Enter opens it, and forward-Tab exits
   const section = page.locator("[data-pretable-tool-grouping]");
   await expect(section).toBeVisible();
 
-  // Walk forward from the section's first control — the add-group button,
-  // which is the walk's START point and so can never appear in `seen`. This
-  // grid is ungrouped, so the recordable roster after it is: expand/
+  // Walk forward from the pane's FIRST stop — the resize handle (SP5), the
+  // walk's START point and so never in `seen`; update the start if the pane
+  // ever gains an earlier stop. This grid is ungrouped, so the recordable
+  // roster after it is: the add-group button (a plain <button> — a
+  // conditional stop, per the filters walk's WebKit note), expand/
   // collapse-all (DISABLED — never stops), the hide-grouped checkbox, one
   // aggregate select per column, then the rail. Selects — and the rail tab,
   // which carries an explicit tabindex — are Tab stops in every browser; the
-  // checkbox is the one conditional RECORDED stop, per the platform's "Tab
-  // moves between all controls" preference (the filters walk's WebKit note).
+  // checkbox and the add-group button are the conditional RECORDED stops,
+  // per the platform's "Tab moves between all controls" preference.
   const aggregateCount = await page
     .locator("[data-pretable-aggregate-row]")
     .count();
@@ -884,6 +892,7 @@ test("grouping: arrows reach its rail tab, Enter opens it, and forward-Tab exits
       const active = document.activeElement;
       if (!(active instanceof HTMLElement)) return "out";
       if (active.hasAttribute("data-pretable-tool-tab")) return "rail";
+      if (active.hasAttribute("data-pretable-pane-resize")) return "resize";
       if (active.hasAttribute("data-pretable-add-group")) return "add-group";
       if (active.hasAttribute("data-pretable-expand-all")) return "expand-all";
       if (active.hasAttribute("data-pretable-collapse-all")) {
@@ -898,7 +907,9 @@ test("grouping: arrows reach its rail tab, Enter opens it, and forward-Tab exits
       return "other";
     });
 
-  await page.locator("[data-pretable-add-group]").focus();
+  const groupingResizeHandle = page.locator("[data-pretable-pane-resize]");
+  await groupingResizeHandle.focus();
+  await expect(groupingResizeHandle).toBeFocused();
   const seen: string[] = [];
   let escaped = false;
   for (let i = 0; i < aggregateCount + 10; i++) {
@@ -915,12 +926,15 @@ test("grouping: arrows reach its rail tab, Enter opens it, and forward-Tab exits
   expect(escaped, `walk was ${seen.join(" → ")}`).toBe(true);
   expect(seen).not.toContain("expand-all");
   expect(seen).not.toContain("collapse-all");
+  expect(seen).not.toContain("resize"); // the start — seeing it again is a wrap
   expect(seen).not.toContain("other");
 
   // Tree order, the filters walk's way: the whole walk must be a subsequence
-  // of the full roster, so when the conditional checkbox IS a stop its
-  // POSITION is pinned too — before every picker, never between them.
+  // of the full roster, so when a conditional stop (the add-group button, the
+  // checkbox) IS a stop its POSITION is pinned too — add-group first,
+  // hide-grouped before every picker, never between them.
   const FULL = [
+    "add-group",
     "hide-grouped",
     ...Array<string>(aggregateCount).fill("aggregate-select"),
     "rail",
@@ -930,7 +944,9 @@ test("grouping: arrows reach its rail tab, Enter opens it, and forward-Tab exits
   );
   // The stops that exist in every browser, exactly: every aggregate picker,
   // then the rail as the panel's last stop.
-  expect(seen.filter((stop) => stop !== "hide-grouped")).toEqual([
+  expect(
+    seen.filter((stop) => stop !== "hide-grouped" && stop !== "add-group"),
+  ).toEqual([
     ...Array<string>(aggregateCount).fill("aggregate-select"),
     "rail",
   ]);
@@ -955,6 +971,8 @@ test("grouping: arrows reach its rail tab, Enter opens it, and forward-Tab exits
  * ROSTER PINS (update together with the fixture):
  * - rail order: columns, notes, filters, grouping — notes is SECOND, one
  *   ArrowDown from the walk's landing tab.
+ * - the pane's first stop is the SHELL's resize handle (SP5) — it precedes
+ *   every section's content, consumer sections included.
  * - notes pane controls, in DOM order: save button, clear button, text input.
  * ---------------------------------------------------------------------- */
 
@@ -1033,23 +1051,27 @@ test("custom section: arrows reach its tab, Enter opens the pane, and the walk e
   await expect(page.locator("[data-pretable-tool-pane]")).toBeVisible();
   await expect(page.locator("[data-notes-heading]")).toHaveText("Trade notes");
 
-  // Walk forward from the pane's first control — the save button, the walk's
-  // START point, so it can never appear in `seen`. The recordable roster
-  // after it: the clear button (a plain <button> — the one browser-
-  // conditional stop, per the filters walk's WebKit note), the text input,
+  // Walk forward from the pane's FIRST stop — the SHELL's resize handle
+  // (SP5), the walk's START point, so it can never appear in `seen`; update
+  // the start if the pane ever gains an earlier stop. The recordable roster
+  // after it: the save and clear buttons (plain <button>s — browser-
+  // conditional stops, per the filters walk's WebKit note), the text input,
   // then the rail. Bounded: a trap runs the loop out rather than hanging.
   const whereFocusIs = () =>
     page.evaluate(() => {
       const active = document.activeElement;
       if (!(active instanceof HTMLElement)) return "out";
       if (active.hasAttribute("data-pretable-tool-tab")) return "rail";
+      if (active.hasAttribute("data-pretable-pane-resize")) return "resize";
       if (active.hasAttribute("data-notes-save")) return "save";
       if (active.hasAttribute("data-notes-clear")) return "clear";
       if (active.hasAttribute("data-notes-input")) return "input";
       return "other";
     });
 
-  await page.locator("[data-notes-save]").focus();
+  const notesResizeHandle = page.locator("[data-pretable-pane-resize]");
+  await notesResizeHandle.focus();
+  await expect(notesResizeHandle).toBeFocused();
   const seen: string[] = [];
   let escaped = false;
   for (let i = 0; i < 10; i++) {
@@ -1064,18 +1086,22 @@ test("custom section: arrows reach its tab, Enter opens the pane, and the walk e
   // The walk LEAVES — no trap around consumer content — and saw nothing
   // stray: every stop belongs to the section or is the rail.
   expect(escaped, `walk was ${seen.join(" → ")}`).toBe(true);
+  expect(seen).not.toContain("resize"); // the start — seeing it again is a wrap
   expect(seen).not.toContain("other");
 
   // Tree order, the filters walk's way: the whole walk must be a
-  // subsequence of the full roster, so when the conditional button IS a
+  // subsequence of the full roster, so when a conditional button IS a
   // stop its POSITION is pinned too.
-  const FULL = ["clear", "input", "rail"];
+  const FULL = ["save", "clear", "input", "rail"];
   expect(isSubsequenceOf(FULL, seen), `walk was ${seen.join(" → ")}`).toBe(
     true,
   );
   // The stops that exist in every browser, exactly: the text input, then
   // the rail as the panel's last stop before the exit.
-  expect(seen.filter((stop) => stop !== "clear")).toEqual(["input", "rail"]);
+  expect(seen.filter((stop) => stop !== "save" && stop !== "clear")).toEqual([
+    "input",
+    "rail",
+  ]);
 });
 
 test("custom section: Escape from inside the pane returns focus to its rail tab", async ({
@@ -1092,3 +1118,255 @@ test("custom section: Escape from inside the pane returns focus to its rail tab"
   await page.keyboard.press("Escape");
   await expect(notesRailTab(page)).toBeFocused();
 });
+
+/* -------------------------------------------------------------------------
+ * Pane resizing + auto width (SP5).
+ *
+ * Two target pages, both already in this file. The RESIZE tests run on the
+ * keyboard example: its pane is untouched and uncontrolled (no width props),
+ * so the A5 inline-style rule is observable — no inline `inline-size` until
+ * someone acts, and Enter/Escape restore the stylesheet width by REMOVING
+ * the style rather than writing the old number back. Its grid also carries
+ * 780px of columns in a viewport narrower than that, so Status (pinned
+ * right) rides the viewport's right edge — which turns "the grid genuinely
+ * reflowed" into one measurable x-coordinate.
+ *
+ * The AUTO-WIDTH test runs on the filters example: auto width is a MODE BIT,
+ * not a content fit (spec Fact 2 — verified in a real browser), so proving
+ * the negative needs the visible content to CHANGE while the width must not,
+ * and this page's filter builder is the one place a test can swap the desk
+ * column's visible values ("Equities", 8 chars → "Macro", 5) without
+ * touching layout. None of these fixtures declare `flex`, so the renderer's
+ * width for an auto column is exactly its 140px default — the flex-share
+ * variant stays a unit-suite concern.
+ * ---------------------------------------------------------------------- */
+
+function paneResizeHandle(page: Page): Locator {
+  return page.locator("[data-pretable-pane-resize]");
+}
+
+function toolPane(page: Page): Locator {
+  return page.locator("[data-pretable-tool-pane]");
+}
+
+async function paneWidth(page: Page): Promise<number> {
+  return Math.round((await toolPane(page).boundingBox())!.width);
+}
+
+/**
+ * Press the seam and arm the drag, VERIFIED: the pane's width applies LIVE
+ * (spec A2), so a small probe travel that moved the width is the drag's own
+ * statement that the press landed on the slim strip. A missed press changes
+ * nothing — release and re-aim against fresh geometry, `beginGripDrag`'s
+ * pattern. Returns the probe position and the width the drag started from
+ * (BEFORE the probe's 8px), in ltr, where travel toward +x SHRINKS the pane.
+ */
+async function beginSeamDrag(
+  page: Page,
+): Promise<{ x: number; y: number; startWidth: number }> {
+  const handle = paneResizeHandle(page);
+  for (let attempt = 0; attempt < 3; attempt++) {
+    await waitForStablePosition(handle);
+    const box = await handle.boundingBox();
+    if (!box) continue;
+    const x = box.x + box.width / 2;
+    const y = box.y + box.height / 2;
+    const startWidth = await paneWidth(page);
+    await page.mouse.move(x, y);
+    await page.mouse.down();
+    // Two moves, like the grip drags: a single jump can be coalesced away.
+    await page.mouse.move(x + 4, y, { steps: 2 });
+    await page.mouse.move(x + 8, y, { steps: 2 });
+    try {
+      await expect
+        .poll(() => paneWidth(page), { timeout: 1_000 })
+        .toBe(startWidth - 8);
+      return { x, y, startWidth };
+    } catch {
+      await page.mouse.up(); // missed the strip: release and re-acquire
+    }
+  }
+  throw new Error("could not arm a drag on the pane resize seam");
+}
+
+test("pane resize: dragging the seam narrows the pane and the grid genuinely reflows", async ({
+  page,
+}) => {
+  await mountExample(page);
+  await openColumnsPane(page);
+
+  const statusHeader = page.locator(
+    '[data-pretable-header-cell][data-pretable-column-id="status"]',
+  );
+  const statusBefore = (await statusHeader.boundingBox())!;
+
+  // Precondition for the reflow assertion: the grid is horizontally
+  // scrollable (780px of columns in a narrower viewport), so Status rides
+  // the viewport's right edge and MUST move when the grid area grows. A
+  // wide-enough grid would leave Status parked at its column offset and the
+  // assertion below would measure nothing.
+  const viewport = page.locator("[data-pretable-scroll-viewport]");
+  expect(await viewport.evaluate((el) => el.scrollWidth > el.clientWidth)).toBe(
+    true,
+  );
+
+  const drag = await beginSeamDrag(page);
+  // +60 total from the press, toward +x: in ltr the seam's travel away from
+  // the pane SHRINKS it — the pane docks at the row's inline end.
+  await page.mouse.move(drag.x + 30, drag.y, { steps: 4 });
+  await page.mouse.move(drag.x + 60, drag.y, { steps: 4 });
+  await page.mouse.up();
+
+  // The pane gave up exactly the travel (rounded whole px by the clamp)...
+  await expect.poll(() => paneWidth(page)).toBe(drag.startWidth - 60);
+  // ...and the GRID took it: the right-pinned header cell moved with the
+  // viewport's right edge — the reflow, measured grid-side, not the pane's
+  // own style echoed back.
+  await expect
+    .poll(async () => {
+      const box = (await statusHeader.boundingBox())!;
+      return Math.abs(box.x - (statusBefore.x + 60)) <= 1.5;
+    })
+    .toBe(true);
+});
+
+test("pane resize: the handle is a tab stop; arrows resize, Enter restores the stylesheet width", async ({
+  page,
+}) => {
+  await mountExample(page);
+  await openColumnsPane(page);
+  const handle = paneResizeHandle(page);
+  const pane = toolPane(page);
+
+  // Untouched and uncontrolled: no inline width — the stylesheet's number
+  // is in charge (spec A5), which is what Enter must restore below.
+  expect(await pane.evaluate((el) => el.style.inlineSize)).toBe("");
+
+  // The handle is the pane's FIRST stop in the real sequential order: one
+  // Shift+Tab from the columns section's first control (the search box)
+  // lands on it. Update this hop if the pane ever gains an earlier stop.
+  await page.locator("[data-pretable-tool-search]").focus();
+  await page.keyboard.press("Shift+Tab");
+  await expect(handle).toBeFocused();
+
+  // aria-valuenow reports the RENDERED width even before any interaction.
+  const before = await paneWidth(page);
+  await expect(handle).toHaveAttribute("aria-valuenow", String(before));
+
+  // ltr: ArrowRight drags the seam away from the pane — shrink by the 16px
+  // step — and the REAL width follows the aria value, not just the number.
+  await page.keyboard.press("ArrowRight");
+  await expect(handle).toHaveAttribute("aria-valuenow", String(before - 16));
+  await expect.poll(() => paneWidth(page)).toBe(before - 16);
+  expect(await pane.evaluate((el) => el.style.inlineSize)).toBe(
+    `${before - 16}px`,
+  );
+
+  // ArrowLeft grows it back — the direction pair, not the same key twice.
+  await page.keyboard.press("ArrowLeft");
+  await expect(handle).toHaveAttribute("aria-valuenow", String(before));
+  await expect.poll(() => paneWidth(page)).toBe(before);
+
+  // Enter resets: uncontrolled with no default prop, "the default" is the
+  // stylesheet width, restored by REMOVING the inline style (A5).
+  await page.keyboard.press("ArrowRight");
+  await expect.poll(() => paneWidth(page)).toBe(before - 16);
+  await page.keyboard.press("Enter");
+  await expect.poll(() => pane.evaluate((el) => el.style.inlineSize)).toBe("");
+  await expect.poll(() => paneWidth(page)).toBe(before);
+});
+
+test("pane resize: Escape mid-drag restores the drag-start width", async ({
+  page,
+}) => {
+  await mountExample(page);
+  await openColumnsPane(page);
+  const pane = toolPane(page);
+
+  const drag = await beginSeamDrag(page);
+  await page.mouse.move(drag.x + 40, drag.y, { steps: 4 });
+  await expect.poll(() => paneWidth(page)).toBe(drag.startWidth - 40);
+
+  // The drag started from the untouched stylesheet width, so the cancel
+  // restores by REMOVING the inline style, not by writing the number back.
+  await page.keyboard.press("Escape");
+  await expect.poll(() => pane.evaluate((el) => el.style.inlineSize)).toBe("");
+  await expect.poll(() => paneWidth(page)).toBe(drag.startWidth);
+
+  // The release after a cancelled drag commits nothing.
+  await page.mouse.up();
+  await expect.poll(() => paneWidth(page)).toBe(drag.startWidth);
+});
+
+test("auto width: the kebab toggle swaps the drawn width between the engine's and the renderer's — and content changes never move it", async ({
+  page,
+}) => {
+  await mountFiltersExample(page);
+
+  // The desk column declares widthPx: 110 — manual, so the ENGINE's stored
+  // width is what the renderer draws.
+  const deskHeader = filtersFigure(page).locator(
+    '[data-pretable-header-cell][data-pretable-column-id="desk"]',
+  );
+  const drawnDeskWidth = async () =>
+    Math.round((await deskHeader.boundingBox())!.width);
+  expect(await drawnDeskWidth()).toBe(110);
+
+  // Open the columns section and desk's row menu.
+  await columnsRailTab(page).click();
+  const deskRow = filtersFigure(page).locator(
+    '[data-pretable-tool-column-row][data-pretable-column-id="desk"]',
+  );
+  await waitForStablePosition(deskRow);
+  await deskRow.locator("[data-pretable-tool-row-menu-button]").click();
+  // The menu is PORTALED out of the figure, so it is found document-wide by
+  // the column id it carries — only one menu is ever open.
+  const menu = page.locator(
+    '[data-pretable-column-menu][data-pretable-column-id="desk"]',
+  );
+  await expect(menu).toBeVisible();
+  const autoItem = menu.locator('[data-pretable-menu-action="auto-width"]');
+  await expect(autoItem).toHaveAttribute("role", "menuitemcheckbox");
+  await expect(autoItem).toHaveAttribute("aria-checked", "false");
+
+  // Toggle auto ON: a mode bit, so the menu STAYS OPEN (a checkbox, not a
+  // command) with its checked state flipped live...
+  await autoItem.click();
+  await expect(menu).toBeVisible();
+  await expect(autoItem).toHaveAttribute("aria-checked", "true");
+  // ...and the drawn width moves to the RENDERER's width — the 140px default
+  // (no `flex` on this fixture), NOT a measure of "Equities". The engine
+  // still stores 110; auto merely withholds it from the renderer.
+  await expect.poll(drawnDeskWidth).toBe(140);
+
+  // Now change the CONTENT while the column is auto: filter symbol to "tl"
+  // — only TLT survives, and desk's visible values collapse from a mix
+  // including "Equities" (8 chars) to just "Macro" (5). A content-fitting
+  // grid would shrink; the mode bit must not move.
+  await page.keyboard.press("Escape"); // close the menu first
+  await filtersRailTab(page).click();
+  await addFilterButton(page).click();
+  const filterRow = filtersFigure(page).locator("[data-pretable-filter-row]");
+  await filterRow.locator("[data-pretable-filter-row-value]").fill("tl");
+  await expect(shownRowCount(page)).toHaveText("1");
+  // The content really changed — the Equities rows are gone from the DOM.
+  await expect(
+    filtersFigure(page).locator(
+      '[data-pretable-row][data-pretable-row-id="h1"]',
+    ),
+  ).toHaveCount(0);
+  // The negative that pins the semantic: auto width did not budge.
+  await expect.poll(drawnDeskWidth).toBe(140);
+
+  // Toggle auto OFF: back to the ENGINE's stored width — 110 survived the
+  // whole excursion untouched, which is what "withheld, not overwritten"
+  // means.
+  await columnsRailTab(page).click();
+  await deskRow.locator("[data-pretable-tool-row-menu-button]").click();
+  await expect(menu).toBeVisible();
+  await expect(autoItem).toHaveAttribute("aria-checked", "true");
+  await autoItem.click();
+  await expect(menu).toBeVisible();
+  await expect(autoItem).toHaveAttribute("aria-checked", "false");
+  await expect.poll(drawnDeskWidth).toBe(110);
+});

From e58876d57837e7e592ea0472f399a07157619d2a Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sun, 30 Aug 2026 14:14:47 -0700
Subject: [PATCH 10/11] docs: pane resizing and the auto-width mode bit on the
 tool-panel page (SP5)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The tool-panel page gains a Resizing-the-pane section (drag, keyboard,
bounds, and the A5 stylesheet-vs-inline-width interplay), the width trio
joins the Configuration table, the columns section documents the Auto
width toggle in the mode-bit wording (including the 140→160 jump), and
the two new message keys are named and bound in the docs guard's roster
(mutation-verified: dropping the roster entry, retyping a table cell,
and unnaming a key each fail the guard). setColumnAutoWidth's TSDoc
sheds the pre-amendment content-tracking phrasing for the same mode-bit
wording. Changesets: @pretable/react minor, @pretable/ui patch.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .changeset/tool-panel-pane-resize-css.md      |  5 ++
 .changeset/tool-panel-pane-resize.md          |  9 ++++
 apps/website/content/docs/grid/tool-panel.mdx | 48 +++++++++++++------
 .../docs/__tests__/docs-api-surface.test.ts   |  9 ++++
 packages/react/src/pretable-model.ts          |  6 ++-
 5 files changed, 60 insertions(+), 17 deletions(-)
 create mode 100644 .changeset/tool-panel-pane-resize-css.md
 create mode 100644 .changeset/tool-panel-pane-resize.md

diff --git a/.changeset/tool-panel-pane-resize-css.md b/.changeset/tool-panel-pane-resize-css.md
new file mode 100644
index 00000000..e9248cfc
--- /dev/null
+++ b/.changeset/tool-panel-pane-resize-css.md
@@ -0,0 +1,5 @@
+---
+"@pretable/ui": patch
+---
+
+Styles for the tool panel's pane-resize handle: a slim strip on the pane/grid seam (`data-pretable-pane-resize`) with a hover/focus tint over existing tokens, a `col-resize` cursor, and a 24px hit area on coarse pointers.
diff --git a/.changeset/tool-panel-pane-resize.md b/.changeset/tool-panel-pane-resize.md
new file mode 100644
index 00000000..0c70b25d
--- /dev/null
+++ b/.changeset/tool-panel-pane-resize.md
@@ -0,0 +1,9 @@
+---
+"@pretable/react": minor
+---
+
+The tool panel's pane is resizable, and the columns section can hand a column's width back to the grid.
+
+The pane's grid-side edge is now a drag handle with full keyboard parity: a focusable `role="separator"` with live `aria-value*`, arrow keys stepping 16px (direction-aware in RTL), `Home`/`End` to the bounds, and `Enter` or double-click resetting to the default. Width is React chrome state with the surface's controlled/uncontrolled trio — `defaultPaneWidthPx` / `paneWidthPx` / `onPaneWidthChange` on `PretableToolPanelConfig` — clamped everywhere and reported already-clamped. An untouched, uncontrolled pane writes no inline style, so an existing stylesheet override of the pane's width keeps working until someone actually resizes.
+
+The columns section's row menu gains an "Auto width" toggle (`role="menuitemcheckbox"`, the new `toolPanelAutoWidthLabel` message), and the handle gains `setColumnAutoWidth(columnId, auto)`. Auto width is a mode bit, not a content fit: on, the grid manages the column's width (the renderer's default, or a flex share when the column declares `flex`); sizing the column yourself turns it off; the toggle hands the width back. The resize handle's accessible name is the new `toolPanelResizeLabel` message.
diff --git a/apps/website/content/docs/grid/tool-panel.mdx b/apps/website/content/docs/grid/tool-panel.mdx
index b4a3b590..c028c778 100644
--- a/apps/website/content/docs/grid/tool-panel.mdx
+++ b/apps/website/content/docs/grid/tool-panel.mdx
@@ -38,23 +38,40 @@ The `<Pretable>` preset forwards `toolPanel` verbatim, so the same two lines of
 
 Passing an object keeps the panel on, chooses which sections the rail carries, and controls which one is open. `ToolPanelSectionId` is the union of shipped section ids — today `"columns"`, `"filters"`, and `"grouping"`. The three active-section fields take the wider `PretableToolPanelSectionId` — the built-in literals plus any [custom section](#custom-sections)'s id — so a consumer-authored pane is nameable everywhere a built-in is.
 
-| Option                  | Type                                                          | Required | Description                                                                                                                                                                              |
-| ----------------------- | ------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `sections`              | `readonly (ToolPanelSectionId \| PretableToolPanelSection)[]` | no       | The complete rail, in order: built-ins by id, [custom sections](#custom-sections) as descriptors, freely interleaved. Absent, the rail is the three built-ins; `[]` turns the panel off. |
-| `defaultActiveSection`  | `PretableToolPanelSectionId \| null`                          | no       | The section open on mount when the surface owns the state. Defaults to `null` — rail visible, nothing open.                                                                              |
-| `activeSection`         | `PretableToolPanelSectionId \| null`                          | no       | Present (including `null`, meaning "open nothing") makes the open section fully controlled: tab clicks then only report through `onActiveSectionChange`.                                 |
-| `onActiveSectionChange` | `(section: PretableToolPanelSectionId \| null) => void`       | no       | Reports every open/close, controlled or not — the same assert-and-report split as `state` and `onSelectionChange`.                                                                       |
+| Option                  | Type                                                          | Required | Description                                                                                                                                                                                                               |
+| ----------------------- | ------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sections`              | `readonly (ToolPanelSectionId \| PretableToolPanelSection)[]` | no       | The complete rail, in order: built-ins by id, [custom sections](#custom-sections) as descriptors, freely interleaved. Absent, the rail is the three built-ins; `[]` turns the panel off.                                  |
+| `defaultActiveSection`  | `PretableToolPanelSectionId \| null`                          | no       | The section open on mount when the surface owns the state. Defaults to `null` — rail visible, nothing open.                                                                                                               |
+| `activeSection`         | `PretableToolPanelSectionId \| null`                          | no       | Present (including `null`, meaning "open nothing") makes the open section fully controlled: tab clicks then only report through `onActiveSectionChange`.                                                                  |
+| `onActiveSectionChange` | `(section: PretableToolPanelSectionId \| null) => void`       | no       | Reports every open/close, controlled or not — the same assert-and-report split as `state` and `onSelectionChange`.                                                                                                        |
+| `defaultPaneWidthPx`    | `number`                                                      | no       | Seeds the pane's width, in px, for the uncontrolled form. Absent, the pane keeps its **stylesheet** width until the user first resizes it — see [Resizing the pane](#resizing-the-pane) for why that distinction matters. |
+| `paneWidthPx`           | `number \| null`                                              | no       | Present (including `null`, meaning "the stylesheet width") makes the pane's width fully controlled: the resize handle then only reports through `onPaneWidthChange`. A number outside the pane's bounds renders clamped.  |
+| `onPaneWidthChange`     | `(widthPx: number \| null) => void`                           | no       | Reports every pane-width change, already clamped: live during a drag, per keystroke on the handle, and `null` when a reset returns the pane to its stylesheet width.                                                      |
 
 The rail's accessible name and the built-in section tab labels are messages like any other grid string: override `toolPanelLabel`, `toolPanelColumnsLabel`, `toolPanelFiltersLabel` and `toolPanelGroupingLabel` on the `messages` prop to localize them. A [custom section](#custom-sections)'s label is not a message — it is the descriptor's own plain string, localized where the rest of your application is.
 
+## Resizing the pane
+
+The pane's grid-side edge is a resize handle — a slim strip on the pane/grid seam, `data-pretable-pane-resize` in the DOM. Drag it and the pane resizes **live**: the width applies continuously while the pointer moves, the grid reflows beside it, and release commits. `Escape` mid-drag cancels, restoring the width the drag started at. Double-click resets to the default — `defaultPaneWidthPx` when you gave one, otherwise the stylesheet width. On touch screens the strip's hit area widens to 24px, the same coarse-pointer treatment the header's column-resize strip gets.
+
+The handle is a full keyboard citizen, and it is the pane's **first Tab stop** — whichever section is open, `Tab` from the open rail tab's `Shift+Tab` path or forward into the pane meets it before the section's own controls. It is a `role="separator"` with `aria-orientation="vertical"` and live `aria-valuenow`/`aria-valuemin`/`aria-valuemax`, so a screen reader hears the width and its bounds as they change. `←`/`→` adjust by 16px steps — direction-aware, so "grow the pane" is the arrow that drags the seam that way in the current writing direction, mirroring the header column-resize's RTL treatment; `Home`/`End` jump to the minimum and maximum; `Enter` resets, exactly as double-click does. The handle's accessible name is the `toolPanelResizeLabel` message — override it on the `messages` prop to localize it.
+
+**Bounds are enforced everywhere.** The floor is 186px — measured so the filters section's narrowest usable row still renders every operator label unclipped — and the ceiling is dynamic: the surface's width minus the rail and a working minimum for the grid area, so the pane can never squeeze the grid out of its own box. Drags and keystrokes clamp as they go, and so do incoming props: a controlled `paneWidthPx` (or a `defaultPaneWidthPx`) outside bounds renders clamped, and the clamped value is reported back once through `onPaneWidthChange` so a persisted layout converges on what is actually drawn.
+
+**The stylesheet width, and when an inline style takes over.** The pane's default width is a plain stylesheet rule at zero specificity, and it is deliberately consumer-overridable — `[data-pretable-tool-pane] { inline-size: 320px; }` in your own css is a supported way to pick a house width. An untouched, uncontrolled pane writes **no inline style at all**, so that override keeps working exactly as it always has. The first drag or keystroke on the handle — or any width prop — switches the pane to an inline `inline-size`, which outranks every stylesheet rule; a reset with no `defaultPaneWidthPx` clears the inline style again, handing the width back to the stylesheet (and reports `null`, which is what that state is called in `onPaneWidthChange` and `paneWidthPx` alike).
+
+The width trio follows the surface's controlled/uncontrolled convention — the same assert-and-report contract as `activeSection` above: uncontrolled with an optional seed, or fully controlled with every change reported already clamped. There is no built-in persistence; a consumer who wants the width remembered holds it in the controlled form.
+
 ## The columns section
 
 The pane lists every data column in **drawn order** — the order the engine actually renders, grouped into Pinned left, unpinned, and Pinned right subgroups. Each row carries:
 
 - **A visibility checkbox.** Unchecking hides the column from the grid. Hidden columns stay listed, dimmed, exactly where they were — a hidden column keeps its place in the order and its pin, so re-showing it puts it back where it came from rather than appending it somewhere surprising.
 - **A drag grip.** Dragging a row reorders the column; dragging past a subgroup boundary re-pins it (into Pinned left, Pinned right, or back to unpinned). The commit happens on drop, never mid-drag, and `Escape` mid-drag cancels without committing.
-- **A ⋮ menu** with Pin left, Pin right, and Unpin. The menu is also the only way to pin into an _empty_ pinned group: with no rows in a subgroup there is no boundary to drag or arrow across, so the menu is the affordance that creates the first member.
-- **Search** filters the list by column label; **Reset columns** restores the order, pinning, and visibility the grid mounted with.
+- **A ⋮ menu** with Pin left, Pin right, Unpin, and an **Auto width** toggle. The menu is also the only way to pin into an _empty_ pinned group: with no rows in a subgroup there is no boundary to drag or arrow across, so the menu is the affordance that creates the first member.
+- **Search** filters the list by column label; **Reset columns** restores the order, pinning, visibility, _and_ auto-width state the grid mounted with.
+
+**Auto width is a mode bit, not a content fit.** Checked, it means "let the grid manage this column's width": the column draws at the renderer's default, or takes a flex share when the column declares `flex` — nothing measures cell content. Columns that declare no `widthPx` start in auto mode; sizing a column yourself — dragging its header resize strip, or calling `setColumnWidth` — turns it off, and the toggle reflects that the next time the menu opens. Turning the toggle back on hands the width back to the grid. The same mode bit is scriptable as `grid.setColumnAutoWidth(columnId, auto)` on the handle. One visible consequence worth expecting: turning auto **off** on a column you never resized jumps its width from 140px to 160px — the renderer's default and the engine's stored default are two different numbers, so freezing the column at the engine's width is a real (if small) move, not a no-op. The toggle's label is the `toolPanelAutoWidthLabel` message.
 
 Everything the panel commits writes straight into the engine, so the grid it changes is the same layout header gestures change. That has one consequence worth knowing before you control layout state: a controlled `state.columnOrder` or `state.columnPinned` remains the authority, and it re-imposes the prop's layout over the panel's commits whenever the write-back effect re-runs — any state change reaching the surface is enough. Leave those slices uncontrolled when the panel should own them.
 
@@ -246,13 +263,14 @@ On a [server-rendered grid](/docs/grid#knowing-when-a-server-rendered-grid-is-in
 
 The rail is one Tab stop, however many sections it grows.
 
-| Key                               | Action                                                                                                                                                                                                              |
-| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `Tab`                             | Reach the rail (one stop). From the open rail tab, `Shift+Tab` enters the pane at its **last** control — the pane precedes the rail in tab order.                                                                   |
-| `↑` / `↓` (rail)                  | Move between section tabs. Focus only — nothing opens.                                                                                                                                                              |
-| `Enter` / `Space` (rail)          | Open the focused section; on the already-open section, close it.                                                                                                                                                    |
-| `Escape` (anywhere in the pane)   | Dismiss the innermost open thing first — a mid-drag reorder is cancelled (see above), an open ⋮ menu closes back to its kebab; with nothing open, focus returns to the rail tab.                                    |
-| `Shift+↑` / `Shift+↓` (on a grip) | Move the column — or, in the grouping pane, the grouping level — one position. Crossing a columns-section subgroup boundary re-pins; at the list's ends nothing moves. Focus follows the row, so the chord repeats. |
+| Key                                                | Action                                                                                                                                                                                                              |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Tab`                                              | Reach the rail (one stop). From the open rail tab, `Shift+Tab` enters the pane at its **last** control — the pane precedes the rail in tab order.                                                                   |
+| `↑` / `↓` (rail)                                   | Move between section tabs. Focus only — nothing opens.                                                                                                                                                              |
+| `Enter` / `Space` (rail)                           | Open the focused section; on the already-open section, close it.                                                                                                                                                    |
+| `Escape` (anywhere in the pane)                    | Dismiss the innermost open thing first — a mid-drag reorder is cancelled (see above), an open ⋮ menu closes back to its kebab; with nothing open, focus returns to the rail tab.                                    |
+| `Shift+↑` / `Shift+↓` (on a grip)                  | Move the column — or, in the grouping pane, the grouping level — one position. Crossing a columns-section subgroup boundary re-pins; at the list's ends nothing moves. Focus follows the row, so the chord repeats. |
+| `←` / `→`, `Home` / `End`, `Enter` (resize handle) | Step the pane's width by 16px, jump to its bounds, reset to the default. The handle is the pane's first Tab stop, whichever section is open — the full story is under [Resizing the pane](#resizing-the-pane).      |
 
 Each row's grip is its own Tab stop, so the chord is reachable without a pointer. The two panes' grips carry different accessible names — "Reorder {column}" in the columns section, "Reorder grouping by {column}" in the grouping section — because both can be in the panel at once. Pinning into an empty pinned group is the one operation the chord cannot express — that is the columns row's ⋮ menu.
 
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 f500ebd6..7931814e 100644
--- a/apps/website/lib/docs/__tests__/docs-api-surface.test.ts
+++ b/apps/website/lib/docs/__tests__/docs-api-surface.test.ts
@@ -1871,6 +1871,15 @@ const TOOL_PANEL_MESSAGE_KEYS: Record<string, MessageKeyBinding> = {
   toolPanelFiltersLabel: { section: "Configuration" },
   toolPanelGroupingLabel: { section: "Configuration" },
 
+  // The pane's resize handle is shell chrome, not a section's — its label is
+  // named where the handle itself is documented.
+  toolPanelResizeLabel: { section: "Resizing the pane" },
+
+  // The columns section still ships no strings listing (see the unlisted
+  // block below), but the auto-width toggle's paragraph names its key
+  // outright, so it binds plain rather than joining the excuse.
+  toolPanelAutoWidthLabel: { section: "The columns section" },
+
   // The filters section's strings paragraph names these outright…
   toolPanelAddFilterLabel: { section: "The filters section" },
   toolPanelAddGroupLabel: { section: "The filters section" },
diff --git a/packages/react/src/pretable-model.ts b/packages/react/src/pretable-model.ts
index 03747817..1a95c89f 100644
--- a/packages/react/src/pretable-model.ts
+++ b/packages/react/src/pretable-model.ts
@@ -139,8 +139,10 @@ export type PretableReactGrid<
   readonly setColumnWidth: (columnId: TColumnId, width: number) => void;
   /**
    * Put one column into (or take it out of) the auto-width set — the LIVE set
-   * of columns whose drawn width the renderer owns and tracks from content,
-   * rather than the engine's stored width. `true` starts tracking; `false`
+   * of columns whose drawn width the GRID manages: the renderer's default, or
+   * a flex share when the column declares `flex`, rather than the engine's
+   * stored width. A mode bit, not a content fit — nothing here measures cell
+   * content. `true` hands the width to the grid; `false`
    * makes the column manual again at the engine's current stored width, with
    * no width write of its own. Columns that declare no `widthPx` start in the
    * set; {@link setColumnWidth} takes a column OUT of it (an explicit width is

From 77cbf58c8dd4338a6a15ef1c87243a4a233bde06 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sun, 30 Aug 2026 14:14:47 -0700
Subject: [PATCH 11/11] chore: regenerate api reports for SP5 (config trio,
 setColumnAutoWidth, message keys)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/react/react.api.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/packages/react/react.api.md b/packages/react/react.api.md
index 3ef669d4..557ab665 100644
--- a/packages/react/react.api.md
+++ b/packages/react/react.api.md
@@ -1689,6 +1689,7 @@ export type PretableReactGrid<TRow extends object, TRowId extends PretableRowId,
     readonly setEditStatus: (status: PretableOpenEditStatus, error?: string) => void;
     readonly cancelEdit: () => void;
     readonly setColumnWidth: (columnId: TColumnId, width: number) => void;
+    readonly setColumnAutoWidth: (columnId: TColumnId, auto: boolean) => void;
     readonly setColumnPinned: (columnId: TColumnId, pinned: "left" | "right" | null) => void;
     readonly setColumnVisible: (columnId: TColumnId, visible: boolean) => void;
     readonly setColumnOrder: (columnIds: readonly TColumnId[]) => void;
@@ -2159,6 +2160,7 @@ export interface PretableSurfaceMessages {
     toolPanelAggregateNoneOption?: () => string;
     toolPanelAggregatesLabel?: () => string;
     toolPanelAggregateSumLabel?: () => string;
+    toolPanelAutoWidthLabel?: () => string;
     toolPanelCollapseAllLabel?: () => string;
     toolPanelColumnGroupedMarker?: () => string;
     toolPanelColumnGroupLabel?: (args: {
@@ -2218,6 +2220,7 @@ export interface PretableSurfaceMessages {
         label: string;
     }) => string;
     toolPanelResetColumnsLabel?: () => string;
+    toolPanelResizeLabel?: () => string;
     toolPanelSearchColumnsLabel?: () => string;
     toolPanelSearchColumnsPlaceholder?: () => string;
     toolPanelShowColumnLabel?: (args: {
@@ -2439,8 +2442,11 @@ export interface PretableTelemetry<TRowId extends PretableRowId = string> {
 export interface PretableToolPanelConfig {
     readonly activeSection?: PretableToolPanelSectionId | null;
     readonly defaultActiveSection?: PretableToolPanelSectionId | null;
+    readonly defaultPaneWidthPx?: number;
     // (undocumented)
     readonly onActiveSectionChange?: (section: PretableToolPanelSectionId | null) => void;
+    readonly onPaneWidthChange?: (widthPx: number | null) => void;
+    readonly paneWidthPx?: number | null;
     readonly sections?: readonly (ToolPanelSectionId | PretableToolPanelSection)[];
 }