@astryxdesign/core 0.7.5 → 0.7.6-canary.0d71e8d

package/src/Resizable/Resizable.spec.md

@@ -1,21 +1,24 @@
 ---
 schema_version: 3
-template_version: 3
+template_version: 7
 kind: component
 id: component:Resizable
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-31
 owners: [cixzhang]
-review_triggers: [behavior, layout, theming, accessibility]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
 verified_by:
   [
     packages/core/src/Resizable/ResizeHandle.test.tsx,
     packages/core/src/Resizable/useResizable.test.ts,
     packages/core/src/Resizable/shippedDirections.test.ts,
     packages/core/src/Resizable/utils.test.ts,
+    packages/core/src/Resizable/__tests__/ResizeHandle.a11y.test.tsx,
+    packages/core/src/Resizable/__tests__/ResizeHandle.a11y.chromium.spec.ts,
+    .github/visual-baseline/manifest.json,
     packages/core/src/theme/themingTargets.test.ts,
     scripts/check-knowledge.mjs,
   ]
@@ -29,129 +32,159 @@ architecture:
     architecture:public-component-api,
   ]
 contributing: []
-system_specs: [spec:AST-010]
+system_specs: [spec:AST-010, spec:AST-020, spec:AST-085]
 ---
 
 # Resizable component contract
 
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                                                                   |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `useResizable` (size, bounds, collapse, snaps, persistence) and `ResizeHandle` (`direction`, `position`, `isReversed`, `isDisabled`, `hasDivider`, `isAlwaysVisible`, `pillPlacement`, `label`, `resizable`, `children`), plus the `pixel()` and `percent()` size helpers. |
+| Behavior                | The hook owns a region's size in pixels; the Handle is a focusable window splitter that resizes it by pointer and keyboard.                                                                                                                                                |
+| End-user impact         | People drag or use the keyboard to resize a panel, collapse and restore it, and have the size remembered, with the divider moving the way the page reads.                                                                                                                  |
+| Builder impact          | None; the record describes shipped behavior.                                                                                                                                                                                                                               |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Implementation gaps are listed under Current-state impact.                                                                                                                                      |
+| Review checks           | Reject a Handle that loses its splitter role, values, or keys, arrows that move against the reading direction, a percentage default that rescales, or state, paint, storage, and ARIA that disagree.                                                                       |
+| Governing rules         | `spec:AST-010`; `spec:AST-020` FR15 (APG Window Splitter); `spec:AST-085`; `architecture:interaction-modality`; `architecture:component-theming-surface`; `architecture:public-component-api`.                                                                             |
+
+This table is a review projection; the body below is authoritative.
+
 ## Intent
 
 Resizable combines the useResizable state and behavior hook with a focusable
 ResizeHandle. The handle presents a default Grip pill over an enlarged invisible
-Grab zone. AST-010 adds explicit pixel and percentage configuration while keeping
-selected state, persistence, callbacks, paint, and ARIA in resolved pixels.
+Grab zone. Sizes may be configured in pixels or percentages, while selected
+state, persistence, callbacks, paint, and ARIA stay in resolved pixels.
+
+Consumer syntax and examples belong in `Resizable.doc.mjs` and
+`useResizable.doc.mjs`.
 
 ## Compatibility and migration
 
-- Released default preserved: `yes`; numeric and exact `Npx` stay pixels, exact
-  `N%` retains released one-time default behavior, and the broad `defaultSize`
-  string type remains source-compatible
-- Compatibility class: 0.6 removes the deprecated pixel-bound aliases after two
-  stable releases; numeric `minSize` / `maxSize` preserve their pixel semantics
-- Controlled/uncontrolled behavior: unchanged
-- Migration decision: CSS-like `min()` / `max()` strings are not supported. Use
-  `percent(value, {min: pixel(value)})` or
-  `percent(value, {max: pixel(value)})`.
+- Released default preserved: `yes`; numbers and exact `Npx` are pixels, exact
+  `N%` is a one-time default, and the broad `defaultSize` string type remains
+  source-compatible.
+- Compatibility class: records shipped behavior; `minSize` and `maxSize` are
+  the bound props, and numeric bounds are pixels.
+- Controlled/uncontrolled behavior: collapse may be controlled
+  (`isCollapsed`, `onCollapseChange`) or uncontrolled (`defaultIsCollapsed`);
+  size is hook-owned.
+- Migration decision: none. CSS-like `min()` and `max()` strings are not
+  supported; `percent(value, {min: pixel(value)})` and
+  `percent(value, {max: pixel(value)})` express a bounded percentage.
 
 Consumer migration instructions belong in consumer docs and release notes.
 
+## Current-state impact
+
+- **Handle direction not reflected (FR4).** `Resizable.doc.mjs` lists
+  `direction` as a visual state of the `resize-handle` target, but the Handle
+  does not reflect it, so a theme rule for one direction never matches, where
+  `architecture:component-theming-surface` INV6 keeps declared state on the
+  owning target.
+- **Disabled Handle leaves the tab order (FR3, AR1).** A disabled Handle sets
+  `tabIndex={-1}`, so keyboard users cannot reach it to hear that it is
+  disabled, where `spec:AST-085` FR1 keeps a disabled control's tab stop.
+- **Window-splitter gaps (AR1).** The Handle names the pane it resizes with
+  `aria-controls` only when its caller passes one; an unbounded Handle in a
+  container that no percentage bound observes carries no `aria-valuemax`; and
+  End does not move an unbounded Handle (`spec:AST-020` FR15).
+- **Caller focus and double-click handlers replace the Handle's (FR7).**
+  Caller props spread after the Handle's own `onFocus`, `onBlur`, and
+  `onDoubleClick`, so passing any of them stops the Handle's focus-visible
+  pill and its double-click collapse, where
+  `architecture:public-component-api` INV7 has handlers compose.
+- **`shrinkOrder` is inert.** useResizable accepts and documents
+  `shrinkOrder`, but no code reads it, so it has no effect.
+
 ## Ownership boundary
 
 **Owns**
 
-- useResizable size, collapse, snapping, persistence, and resize lifecycle.
+- useResizable size, collapse, snapping, persistence, and resize
+  lifecycle.
 - ResizeHandle's separator semantics, pointer and keyboard interaction, and
-  current `resize-handle` target.
-- The default Grip pill and its current `resize-handle-pill` target, plus the
-  aligned invisible Grab zone.
+  its `resize-handle` target.
+- The default Grip pill and its `resize-handle-pill` target, plus the aligned
+  invisible Grab zone.
 
 **Does not own / non-goals**
 
-- The structural region being resized — owned by LayoutPanel, SideNav, or another
-  caller.
-- Layout-region topology, inset, divider, or scrolling rules.
-- A public target for the Grab zone; none exists on current `main`.
-- Fixing the missing runtime reflection for the documented Handle `direction`
-  theming state; that remains a separate theming follow-up.
+- The region being resized — owned by LayoutPanel, SideNav, or another caller.
+- Layout-region topology, inset, divider, or scrolling rules — owned by
+  `family:layout-regions`.
+- A public target for the Grab zone; none exists.
 
 ## Public concepts
 
-`ResizableSize` is a Resizable-specific union: pixel number, exact `Npx`, exact
-`N%`, `PixelWidth`, or `ResizablePercentSize`.
-`pixel(value)` is Table's existing canonical structured pixel helper;
-`percent(value, {min: pixel(value)})` creates a literal percentage with a pixel
-floor; `percent(value, {max: pixel(value)})` creates one with a pixel ceiling.
-The options argument is required and the two bounds are mutually exclusive.
-`defaultSize` retains its released broad `SizeValue` type and adds the structured
-`PixelWidth` and `ResizablePercentSize` values; runtime validation remains
-authoritative for legacy strings.
-
-Numbers and exact `Npx` remain pixels. A descriptor default resolves once; a
-descriptor bound remains live. Consumer props, outputs, and examples are documented
-in `Resizable.doc.mjs` and `useResizable.doc.mjs`.
+| Concept          | Closed values or states                                                                        | Meaning                                                                                                     | Availability by variant/orientation/state | Default                                              | Owner                 | Stability | Invalid-value behavior                                                    |
+| ---------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------- | --------------------- | --------- | ------------------------------------------------------------------------- |
+| Size value       | pixel number; exact `Npx`; exact `N%`; `pixel()`; `percent(value, {min} or {max})`             | A size or bound in pixels or a percentage of the container, or of the viewport without a `containerRef`.    | `defaultSize`, `minSize`, `maxSize`       | `defaultSize` 250, `minSize` 50, `maxSize` unbounded | `component:Resizable` | Stable    | Invalid strings and descriptors fail runtime validation (`spec:AST-010`). |
+| Collapse         | collapsible; collapsed; expanded                                                               | A collapsible region collapses to 0 when a drag goes below `collapsedSize`, and restores its previous size. | `collapsible`                             | not collapsible; `collapsedSize` 40 (drag threshold) | `component:Resizable` | Stable    | —                                                                         |
+| Snaps            | pixel list                                                                                     | The only positions the region rests on, for drag, keyboard, and `resize()`.                                 | Optional                                  | none                                                 | `component:Resizable` | Stable    | —                                                                         |
+| Persistence      | `autoSaveId`                                                                                   | Remembers the pixel size across sessions.                                                                   | Optional                                  | none                                                 | `component:Resizable` | Stable    | —                                                                         |
+| Axis             | `horizontal`; `vertical`                                                                       | The axis the region resizes along.                                                                          | Handle and hook                           | `horizontal`                                         | `component:Resizable` | Stable    | Closed union.                                                             |
+| Handle placement | `position` `inline`, `overlay`; `isReversed`; `pillPlacement` `auto`, `start`, `center`, `end` | Whether the Handle takes layout space or overlays its parent; which side grows; where the pill sits.        | Handle                                    | `inline`; not reversed; `auto`                       | `component:Resizable` | Stable    | Closed union.                                                             |
+| Handle state     | enabled; disabled; divider; always-visible pill                                                | Interaction and paint options.                                                                              | Handle                                    | enabled; no divider; pill visible                    | `component:Resizable` | Stable    | —                                                                         |
+| Grip content     | caller `children`                                                                              | Replaces the Grip pill.                                                                                     | Handle                                    | Grip pill                                            | caller                | Stable    | —                                                                         |
 
 ## Behavioral and layout contract
 
-| ID  | Candidate invariant                                                                                                                                                                                                                      | Basis                            | Draft review state                                            |
-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ------------------------------------------------------------- |
-| FR1 | ResizeHandle renders one focusable Handle and one enlarged Grab zone; the default render also contains a Grip pill, while caller-provided children replace that pill.                                                                    | Current source, docs, and tests  | Verified current behavior; no new behavior decided            |
-| FR2 | Handle carries `resize-handle`, Grip pill carries `resize-handle-pill`, and Grab zone carries no public target.                                                                                                                          | Current source and public docs   | Verified current target inventory; no target change           |
-| FR3 | Pointer, keyboard, collapse, snap, persistence, reversal, and size behavior remain owned by ResizeHandle and useResizable rather than layout-regions collaborators.                                                                      | Current source, docs, and tests  | Verified current ownership; resize semantics remain unchanged |
-| FR4 | Resizable metadata advertises `direction` as a Handle visual state, but current runtime calls `themeProps('resize-handle')` without reflecting that value, so direction selectors cannot match.                                          | Current source and public docs   | Verified audit gap; deliberately not fixed in this change     |
-| FR5 | `percent(value, {min: pixel(value)})` and `percent(value, {max: pixel(value)})` resolve against the AST-010 basis; a default selects pixels once, while a bound re-resolves and clamps selected pixels. Both/neither bounds are invalid. | AST-010, source, tests, Chromium | New structured sizing behavior; selected state remains pixels |
-| FR6 | `minSize` and `maxSize` are the only bound spellings in 0.6; numeric values retain pixel semantics, and the upgrade codemod rewrites static inline uses of the removed aliases.                                                          | AST-010, source, codemod tests   | Breaking cleanup with mechanical migration                    |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Basis                                                         |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| FR1 | ResizeHandle renders one focusable Handle and one enlarged Grab zone (a `--spacing-4` strip on the resize axis); the default render also contains a Grip pill, and caller `children` replace the pill.                                                                                                                                                                                                                                                                                                                                                                                                    | Current source, docs, and tests                               |
+| FR2 | The Handle carries `resize-handle`, the Grip pill carries `resize-handle-pill`, and the Grab zone carries no public target.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Current source and docs                                       |
+| FR3 | Pointer drag, keyboard, double-click collapse, snapping, persistence, reversal, and size behavior are owned by ResizeHandle and useResizable; dragging under right-to-left inverts the pointer delta so the divider follows the pointer. A disabled Handle ignores pointer and keyboard input and exposes `aria-disabled`, and keeps its tab stop (`spec:AST-085` FR1). Implementation gap: a disabled Handle sets `tabIndex={-1}` (Current-state impact).                                                                                                                                                | Current source, docs, and tests                               |
+| FR4 | The Handle reflects the documented `direction` visual state on its target (`architecture:component-theming-surface` INV6). Implementation gap: it reflects no `direction` (Current-state impact).                                                                                                                                                                                                                                                                                                                                                                                                         | Current source and docs                                       |
+| FR5 | A `percent(value, {min: pixel(value)})` or `percent(value, {max: pixel(value)})` resolves against one basis — the supplied container, or the viewport when no `containerRef` is given (`spec:AST-010` FR1, FR2); as a default it selects pixels once, and as a bound it stays live and clamps the selected pixels. A descriptor with both or neither bound is invalid. Selected state, persistence, callbacks, paint, and ARIA are pixels.                                                                                                                                                                | `spec:AST-010`; current source and tests                      |
+| FR6 | `minSize` and `maxSize` are the bound props; numeric values are pixels. When resolved bounds conflict, the maximum wins.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `spec:AST-010`; current source and tests                      |
+| FR7 | `ref`, DOM, data, ARIA, and event props reach the Handle, and a caller's explicit `role`, ARIA attribute, or `tabIndex` reaches it as given; a caller `onKeyDown` runs before the Handle's own key handling; caller `onFocus`, `onBlur`, and `onDoubleClick` compose with the Handle's own focus tracking and double-click collapse (`architecture:public-component-api` INV5, INV7); `xstyle` and `className` compose after component styles, and `style` is not accepted. Implementation gap: caller `onFocus`, `onBlur`, and `onDoubleClick` replace the Handle's own handlers (Current-state impact). | Current source; `architecture:public-component-api` INV5–INV8 |
 
 ### Allowed variation
 
-- **AV1 — Axis.** Handle may resize along the horizontal or vertical layout axis;
-  separator orientation and cursor follow the current implementation.
-- **AV2 — Placement.** Handle may participate inline or overlay its parent, and
-  Grip pill may sit at start, end, center, or the current automatic side.
-- **AV3 — Grip content.** Caller-provided children may replace Grip pill without
+- **AV1 — Axis.** The Handle resizes along the horizontal or vertical axis;
+  separator orientation and cursor follow it.
+- **AV2 — Placement.** The Handle sits inline or overlays its parent, and the
+  Grip pill sits at start, end, center, or the automatic side.
+- **AV3 — Grip content.** Caller `children` may replace the Grip pill without
   changing Handle or Grab zone ownership.
-- **AV4 — Divider.** Handle may paint its current divider treatment; a composing
-  region remains responsible for avoiding a duplicate adjacent divider.
+- **AV4 — Divider.** The Handle may paint its divider; a composing region
+  avoids a duplicate adjacent divider.
 - **AV5 — Structured percentage bound.** A descriptor carries exactly one `min`
-  or `max`, whose value is a `PixelWidth`. Atomic percentages use the existing
-  exact `N%` string; arbitrary CSS expressions are outside this contract.
+  or `max`, whose value is a `PixelWidth`; plain percentages use exact `N%`.
 
 ### Representative states
 
-| State                  | Required invariant                                                    | Allowed variation                                  |
-| ---------------------- | --------------------------------------------------------------------- | -------------------------------------------------- |
-| Default handle         | Handle, Grab zone, and Grip pill render.                              | Divider and always-visible treatment may vary.     |
-| Custom handle content  | Handle and Grab zone remain; caller content replaces Grip pill.       | Caller content remains caller-owned.               |
-| Horizontal or vertical | Interaction follows the selected axis and current ARIA orientation.   | Size, reversal, and pill placement may vary.       |
-| Collapsed or expanded  | Handle preserves valid separator value semantics and resize controls. | Grip pill automatic side follows current behavior. |
-| Disabled               | Handle remains represented but is removed from interactive tab order. | Painted treatment follows existing styles.         |
+| State                  | Required invariant                                               | Allowed variation                |
+| ---------------------- | ---------------------------------------------------------------- | -------------------------------- |
+| Default handle         | Handle, Grab zone, and Grip pill render.                         | Divider and always-visible pill. |
+| Custom handle content  | Handle and Grab zone remain; caller content replaces the pill.   | Caller content.                  |
+| Horizontal or vertical | Interaction follows the axis; ARIA orientation is the divider's. | Size, reversal, pill placement.  |
+| Collapsed              | `aria-valuenow` at the minimum and "Collapsed" value text.       | Pill side.                       |
+| Disabled               | `aria-disabled`; no resize; tab stop kept (FR3 gap).             | Disabled paint.                  |
 
 ### Transformation and precedence order
 
-- Parse atomic strings exactly; validate `percent()` descriptors as a finite 0–100
-  percentage with exactly one finite non-negative pixel bound.
-- Resolve percentages against one active basis, then apply the descriptor's floor or
-  ceiling.
-- Commit a structured default as one initial pixel choice; keep percentage bounds
-  live and clamp with `Math.min(max, Math.max(min, size))`.
-- Maximum wins when resolved bounds conflict; interaction and persistence stay
-  pixel-only.
+- **ORD1 — Parsing.** Atomic strings parse exactly; a `percent()` descriptor is
+  a finite 0–100 percentage with exactly one finite non-negative pixel bound.
+- **ORD2 — Resolution.** Percentages resolve against one active basis, then the
+  descriptor's floor or ceiling applies.
+- **ORD3 — Commitment.** A structured default commits once as pixels;
+  percentage bounds stay live and clamp with
+  `Math.min(max, Math.max(min, size))`, so the maximum wins a conflict.
 
 ### Performance and resources
 
-- Atomic pixel paths add no observer or render work.
-- A structured default observes a supplied container only until its initial pixel
-  choice is final; persisted pixels skip that measurement.
-- Percentage bounds reuse the shared ResizeObserver and remain subscribed while
-  live. Structured validation and resolution are constant-time; no CSS parser is
-  introduced.
+- **PR1 — Observers only when needed.** Atomic pixel paths add no observer or
+  render work. A structured default observes a supplied container only until
+  its initial pixel choice is final, and persisted pixels skip that
+  measurement. Percentage bounds reuse the shared ResizeObserver while live.
+  Validation and resolution are constant-time, with no CSS parser.
 
 ## Accessibility contract
 
-The structured API does not change ResizeHandle's separator role, label,
-orientation, collapsed value text, focus, pointer, or keyboard behavior. Its
-`aria-valuemin`, `aria-valuemax`, and `aria-valuenow` remain the same resolved pixel
-values used by hook state and painted geometry.
-
 - **AR1 — ResizeHandle adopts the APG Window Splitter pattern**
   (`spec:AST-020/FR15`), as one composite control: the Handle is a focusable
   `role="separator"` with an accessible name, `aria-orientation` (the axis the
@@ -179,17 +212,12 @@ values used by hook state and painted geometry.
 
 ## Design relationships
 
-| Anatomy or state | Design requirement                                                      | Representation authority       | Hierarchy role | Component contract |
-| ---------------- | ----------------------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
-| Handle           | Presents the focusable resize separator and optional divider treatment. | Current source and public docs | Prominent      | FR1, FR2, FR3      |
-| Grip pill        | Presents the default visible resize affordance.                         | Current source and public docs | Supporting     | FR1, FR2           |
-| Grab zone        | Enlarges pointer reach while remaining visually transparent.            | Current source and tests       | Supporting     | FR1, FR2           |
-| Direction state  | Selects horizontal or vertical resize presentation.                     | Current public metadata        | Supporting     | FR3, FR4           |
-
-Grab zone is interaction structure rather than a painted public theming seam. Its
-`none` disposition records factual reachability. The missing Handle direction
-reflection is a separate current audit gap: the target exists, but runtime does
-not emit the documented target state.
+| Anatomy or state | Design requirement                                   | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ---------------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Handle           | The focusable resize separator and optional divider. | Current source and docs  | Prominent      | FR1–FR3            |
+| Grip pill        | The default visible resize affordance.               | Current source and docs  | Supporting     | FR1, FR2           |
+| Grab zone        | An enlarged, transparent pointer area.               | Current source and tests | Supporting     | FR1, FR2           |
+| Direction state  | Horizontal or vertical presentation.                 | Current docs             | Supporting     | FR4                |
 
 ### Theming anatomy
 
@@ -209,36 +237,31 @@ not emit the documented target state.
 
 ## Family and system relationships
 
-- `architecture:component-theming-surface` owns anatomy qualification, target
-  mapping, and target-state reflection requirements.
-- `architecture:interaction-modality` owns shared modality behavior;
-  `architecture:public-component-api` owns the additive structured API and
-  compatibility boundary.
-- `Resizable/utils` is server-safe and re-exports Table's exact `pixel()` binding
-  plus `PixelWidth`, alongside Resizable's `percent()` and structured types.
+- `spec:AST-010` owns structured sizing; FR5 and FR6 apply it.
+- `spec:AST-020` FR15 adopts the APG Window Splitter for the Handle; AR1
+  applies it and records its gaps.
+- `spec:AST-085` owns disabled-control behavior; FR3 records the tab-order gap.
+- `architecture:component-theming-surface` owns target mapping and state
+  reflection; FR4 records the `direction` gap.
+- `architecture:interaction-modality` owns shared modality and focus
+  indication; `architecture:public-component-api` owns caller-input routing.
 - `family:layout-regions` lists useResizable and ResizeHandle as collaborators
-  that may drive a LayoutPanel's size. Resizable is not a layout-regions member,
-  and that family does not own or redefine resize state, snapping, persistence,
-  collapse, pointer, or keyboard semantics.
+  that may size a LayoutPanel; it does not own resize state or interaction.
 
 ## Verification map
 
-| Contract            | Verification                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Representative states                                                                                           | Mutation or failure expectation                                                                                                                                   | Audit section                   |
-| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
-| FR1                 | `ResizeHandle.test.tsx` plus source inspection                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Default, custom, collapsed, disabled, both axes                                                                 | Handle and Grab zone regressions fail focused tests; custom Grip replacement currently relies on source review.                                                   | `audit:Resizable/anatomy`       |
-| AR1                 | `ResizeHandle.test.tsx` ("makes the separator focusable", "exposes the region size and bounds via ARIA", "grows the panel by a step on ArrowRight", "shrinks the panel by a step on ArrowLeft", "uses the large step when Shift is held", "jumps to the minimum on Home", "jumps to the maximum on End", "collapses on Enter when the region is collapsible", "inverts the pointer delta under RTL so dragging resizes intuitively", "restores the previous size, not the minimum, when Enter reopens a collapsed pane", "reopens on Enter even when the minimum size sits below the collapse threshold", "reports the window basis as aria-valuemax when no maximum is configured; End leaves an unbounded region alone", "reports the container basis as aria-valuemax while a percentage bound already observes it", "never reports aria-valuemax below aria-valuemin while collapsed in a small window", "reports no aria-valuemax for an unbounded pixel-only region in a container, which stays unobserved", "a grow arrow opens a collapsed pane one step above its minimum; the shrink arrow leaves it collapsed", "a grow arrow opens a collapsed pane at its collapsedSize when the minimum sits below it", "a grow arrow opens a collapsed pane in the reversed layout and under RTL too", "in a reversed layout, ArrowLeft opens a collapsed pane and ArrowRight leaves it collapsed", "under RTL, ArrowLeft opens a collapsed pane and ArrowRight leaves it collapsed", "a grow arrow opens a hand-built collapsed region one step above its minimum", "with snap points, an arrow moves to the adjacent point in its direction and Shift moves two, clamped to the ends", "with snap points past the bounds, a point beyond maxSize or minSize counts as that bound", "with snap points, the arrows follow the reversed layout and the reading direction", "with snap points in a reversed layout, ArrowLeft moves to the next point and ArrowRight to the previous", "with snap points, the grow arrow opens a collapsed pane at the snap point nearest one step above its minimum") and `shippedDirections.test.ts`; `SideNav.test.tsx` ("names the nav it resizes with aria-controls (APG window splitter)"); RTL keyboard mirroring, and the disabled state under the Window Splitter accessibility contract (`internal/a11y-spec`, pending) | Inline and block axes; LTR and RTL; collapsed; disabled                                                         | The Handle loses its role, name, orientation or value properties; an arrow, Home, End or Enter stops moving the divider or moves it against the reading direction | `audit:Resizable/accessibility` |
-| FR2                 | Source inspection and `themingTargets.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Handle, Grip pill, and Grab zone                                                                                | Removing a target or documenting an unshipped Grab zone target fails evidence or inventory.                                                                       | `audit:Resizable/theming`       |
-| FR3                 | `ResizeHandle.test.tsx` and `useResizable.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Pointer, keyboard, snap, collapse, persistence                                                                  | Moving resize ownership or changing current transformations fails focused behavior coverage.                                                                      | `audit:Resizable/behavior`      |
-| FR4                 | Source and public metadata comparison                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Horizontal and vertical Handle                                                                                  | No current test detects that documented `direction` is absent from runtime target-state reflection.                                                               | `audit:Resizable/theming`       |
-| FR5                 | Hook/utils tests, typecheck, and Chromium                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Canonical floor/ceiling/default; invalid XOR shape; SSR/hydration; basis changes; numeric `containerRef` parity | Wrong resolution, rescaling defaults, stale clamps, observer leaks, extra numeric renders/ref reads, or state/paint/storage/ARIA divergence fails.                | `audit:Resizable/behavior`      |
-| FR6                 | Hook type/runtime and codemod tests                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Removed alias type errors; single/multi-region inline migrations; numeric pixel bounds                          | A removed alias still type-checks, or migration changes its numeric meaning.                                                                                      | `audit:Resizable/behavior`      |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Canonical anatomy and two current targets                                                                       | Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation.                                                                        | `audit:Resizable/theming`       |
-
-Current tests exercise Handle and Grab zone structure and behavior but do not
-render `children` to prove that custom content replaces Grip pill. That branch is
-source-inspected and lacks focused regression evidence. The documented
-`direction` visual axis is a closed union, so `extensibleAxes.test.ts` does not
-cover its missing runtime reflection; that mismatch is currently unguarded.
+| Contract            | Verification                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Representative states                                                            | Mutation or failure expectation                                                                                                                                                                                                                                    | Audit section                   |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- |
+| FR1                 | `ResizeHandle.test.tsx`; stable visual baseline `core-resizable--horizontal-split`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Default, collapsed, both axes                                                    | Handle and Grab zone regressions fail focused tests; a changed default handle comes back changed for review. Gap: no test renders `children` to prove they replace the Grip pill.                                                                                  | `audit:Resizable/anatomy`       |
+| FR2                 | `themingTargets.test.ts`; source review                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Handle, Grip pill, Grab zone                                                     | A removed target fails the inventory. `themingTargets.test.ts` catches only a renamed or undocumented target; no check fails if the Handle or Grip pill stops carrying its target.                                                                                 | `audit:Resizable/theming`       |
+| FR3                 | `ResizeHandle.test.tsx` and `useResizable.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Pointer, keyboard, snap, collapse, persistence; RTL drag; disabled keyboard      | A changed transformation, an RTL drag that moves against the pointer, or keyboard input that resizes a disabled Handle fails. Gap: no test covers disabled pointer input or the disabled tab stop.                                                                 | `audit:Resizable/behavior`      |
+| FR4                 | Source and docs comparison                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Horizontal and vertical Handle                                                   | Gap: no test detects that the documented `direction` is not reflected.                                                                                                                                                                                             | `audit:Resizable/theming`       |
+| FR5, ORD1–ORD3      | `useResizable.test.ts`, `utils.test.ts`, typecheck                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Floor, ceiling, default; invalid shapes; basis changes; numeric container parity | Wrong resolution, a rescaled default, a stale clamp, an observer leak, or state, paint, storage, and ARIA that disagree fails.                                                                                                                                     | `audit:Resizable/behavior`      |
+| FR6                 | `useResizable.test.ts`; typecheck                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Numeric bounds; conflicting bounds                                               | A removed alias that type-checks, a numeric bound that is not pixels, or a minimum that wins a conflict fails.                                                                                                                                                     | `audit:Resizable/behavior`      |
+| FR7                 | `ResizeHandle.test.tsx` consumer `onKeyDown` test; source review                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Caller props and `onKeyDown`                                                     | A consumer `onKeyDown` that stops keyboard resizing, or keyboard resizing that skips the consumer handler, fails. Gap: no test covers other caller props, the styling merge, caller `onFocus`, `onBlur`, or `onDoubleClick`, or a caller `role` or ARIA attribute. | `audit:Resizable/api`           |
+| AR1                 | `ResizeHandle.test.tsx` ("makes the separator focusable", "exposes the region size and bounds via ARIA", "grows the panel by a step on ArrowRight", "shrinks the panel by a step on ArrowLeft", "uses the large step when Shift is held", "jumps to the minimum on Home", "jumps to the maximum on End", "collapses on Enter when the region is collapsible", "inverts the pointer delta under RTL so dragging resizes intuitively", "restores the previous size, not the minimum, when Enter reopens a collapsed pane", "reopens on Enter even when the minimum size sits below the collapse threshold", "reports the window basis as aria-valuemax when no maximum is configured; End leaves an unbounded region alone", "reports the container basis as aria-valuemax while a percentage bound already observes it", "never reports aria-valuemax below aria-valuemin while collapsed in a small window", "reports no aria-valuemax for an unbounded pixel-only region in a container, which stays unobserved", "a grow arrow opens a collapsed pane one step above its minimum; the shrink arrow leaves it collapsed", "a grow arrow opens a collapsed pane at its collapsedSize when the minimum sits below it", "a grow arrow opens a collapsed pane in the reversed layout and under RTL too", "in a reversed layout, ArrowLeft opens a collapsed pane and ArrowRight leaves it collapsed", "under RTL, ArrowLeft opens a collapsed pane and ArrowRight leaves it collapsed", "a grow arrow opens a hand-built collapsed region one step above its minimum", "with snap points, an arrow moves to the adjacent point in its direction and Shift moves two, clamped to the ends", "with snap points past the bounds, a point beyond maxSize or minSize counts as that bound", "with snap points, the arrows follow the reversed layout and the reading direction", "with snap points in a reversed layout, ArrowLeft moves to the next point and ArrowRight to the previous", "with snap points, the grow arrow opens a collapsed pane at the snap point nearest one step above its minimum") and `shippedDirections.test.ts`; `SideNav.test.tsx` ("names the nav it resizes with aria-controls (APG window splitter)"); RTL keyboard mirroring, and the disabled state under the Window Splitter accessibility contract (`internal/a11y-spec`, pending); `ResizeHandle.a11y.test.tsx` and `ResizeHandle.a11y.chromium.spec.ts` | Inline and block axes; LTR and RTL; collapsed; disabled                          | The Handle loses its role, name, orientation, or value properties; an arrow, Home, End, or Enter stops moving the divider or moves it against the reading direction.                                                                                               | `audit:Resizable/accessibility` |
+| PR1                 | `useResizable.test.ts` observer tests                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Pixel, percentage default, percentage bound                                      | An observer on a pixel-only path, or one that outlives a final default, fails.                                                                                                                                                                                     | `audit:Resizable/behavior`      |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Canonical anatomy and two targets                                                | Missing, extra, or stale mappings fail repository validation.                                                                                                                                                                                                      | `audit:Resizable/theming`       |
 
 ## Decision log
 
@@ -266,10 +289,7 @@ composition.
 
 ## Open questions
 
-- **OQ1 — Which follow-up should add and verify the missing Handle `direction`
-  target-state reflection?** (`checkable`)
-- **OQ2 — Which focused test should pin custom content replacing Grip pill?**
-  (`checkable`)
+None.
 
 ## Content boundary
 

package/src/Resizable/__tests__/ResizeHandle.a11y.chromium.spec.ts

@@ -87,23 +87,30 @@ async function runState(
   });
 }
 
-test('every window-splitter expectation is exercised by a ResizeHandle state', async ({
-  page,
-}) => {
-  // One test mounts and checks every binding state in turn: about 20s on an
-  // idle machine, three times that when the contract run shares a runner's
-  // cores, so the default 60s ran out mid-loop on whichever state it reached.
-  // Budget it like the other whole-inventory sweeps (Button, Checkbox).
-  test.setTimeout(3 * 60 * 1000);
-  const cdp = await page.context().newCDPSession(page);
+// Checking coverage runs every state again, which on a loaded runner nears
+// the per-test timeout as one test. It runs as one serial part per state,
+// sharing their results, then one check over all of them.
+test.describe('every window-splitter expectation is exercised by a ResizeHandle state', () => {
+  test.describe.configure({mode: 'serial'});
   const results: BindingResult[] = [];
+
   for (const state of RESIZE_HANDLE_BINDING_STATES) {
-    results.push(await runState(page, cdp, state));
+    test(`runs ${state.id}`, async ({page}) => {
+      const cdp = await page.context().newCDPSession(page);
+      results.push(await runState(page, cdp, state));
+    });
   }
-  expect(neverExercised(results)).toEqual([]);
-  expect(unmatchedKnownFailures(RESIZE_HANDLE_KNOWN_FAILURES, results)).toEqual(
-    [],
-  );
+
+  test('no expectation is left unexercised', () => {
+    // Every part ran in this worker; this test alone proves nothing.
+    expect(results.map(result => result.state).sort()).toEqual(
+      RESIZE_HANDLE_BINDING_STATES.map(state => state.id).sort(),
+    );
+    expect(neverExercised(results)).toEqual([]);
+    expect(
+      unmatchedKnownFailures(RESIZE_HANDLE_KNOWN_FAILURES, results),
+    ).toEqual([]);
+  });
 });
 
 for (const state of RESIZE_HANDLE_BINDING_STATES) {