@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/OverflowList/OverflowList.spec.md

@@ -1,204 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:OverflowList
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-31
-owners: [cixzhang]
-review_triggers: [public-api, behavior, layout, theming, accessibility]
-verified_by:
-  [
-    packages/core/src/OverflowList/OverflowList.test.tsx,
-    packages/core/src/hooks/useOverflow.test.ts,
-    packages/core/src/hooks/computeOverflow.test.ts,
-    packages/core/src/theme/themingTargets.test.ts,
-    .github/visual-baseline/manifest.json,
-    scripts/check-knowledge.mjs,
-  ]
-modules: []
-families: []
-design_specs: []
-architecture:
-  [architecture:component-theming-surface, architecture:public-component-api]
-contributing: []
-system_specs: []
----
-
-# OverflowList component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                         |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | `children`, `overflowRenderer`, `onOverflowChange`, `gap`, `minVisibleItems`, `maxVisibleItems`, `maxRows`, `collapseFrom`, `behavior`, root `BaseProps`, `ref`. |
-| Behavior                | Shows as many caller items as fit the measured width, row count, and count limits, and hands the rest to a caller-rendered indicator and callback.               |
-| End-user impact         | People see a single tidy row (or a few rows) of items, with a caller's "more" control standing in for the ones that do not fit.                                  |
-| Builder impact          | None; the record describes shipped behavior.                                                                                                                     |
-| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes.                                                                                       |
-| Review checks           | Reject a measurement copy that is exposed or focusable, an indicator on the wrong edge, a callback that fires before measurement or repeats an unchanged set.    |
-| Governing rules         | `architecture:component-theming-surface`; `architecture:public-component-api` INV5–INV8.                                                                         |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-OverflowList renders a measured subset of caller-supplied items in a visible
-list and lets the caller show the collapsed remainder. It owns measurement and
-the choice of visible items; the caller owns the items and the indicator.
-
-Consumer syntax and examples belong in `OverflowList.doc.mjs`.
-
-## Compatibility and migration
-
-- Released default preserved: `yes` — `gap` 2, one row, collapse from the end,
-  observe self, no count limits.
-- Compatibility class: records shipped behavior; no public prop, default, DOM,
-  target, or styling output changes.
-- Controlled/uncontrolled behavior: not applicable; the visible count is
-  measured.
-- Migration decision: none
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Ownership boundary
-
-**Owns**
-
-- The visible list container and its `overflow-list` target.
-- The hidden measurement copy, measuring available space, applying count and
-  row limits, and choosing which items stay visible.
-- When the overflow callback fires.
-
-**Does not own / non-goals**
-
-- The items supplied through `children` — owned by the caller.
-- The indicator returned by `overflowRenderer`, and any menu it opens — owned
-  by the caller.
-
-## Public concepts
-
-| Concept          | Closed values or states                | Meaning                                                                  | Availability by variant/orientation/state | Default       | Owner                    | Stability | Invalid-value behavior             |
-| ---------------- | -------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------- | ------------- | ------------------------ | --------- | ---------------------------------- |
-| Collapse edge    | `start`; `end`                         | Which end loses items first and holds the indicator.                     | Always                                    | `end`         | `component:OverflowList` | Stable    | Closed union; rejected by types.   |
-| Gap              | spacing step                           | Space between items and the indicator.                                   | Always                                    | 2             | `component:OverflowList` | Stable    | Closed union; rejected by types.   |
-| Count limits     | `minVisibleItems`; `maxVisibleItems`   | A floor and a cap on visible items.                                      | Always                                    | 0; no cap     | `component:OverflowList` | Stable    | The floor wins over a smaller cap. |
-| Rows             | positive number; unset                 | How many wrapped rows may show.                                          | Always                                    | one row       | `component:OverflowList` | Stable    | 1 or unset is a single line.       |
-| Measured box     | `observeSelf`; `observeParent`         | Whether the list measures its own width or its parent's.                 | Always                                    | `observeSelf` | `component:OverflowList` | Stable    | Closed union; rejected by types.   |
-| Overflow outputs | `overflowRenderer`; `onOverflowChange` | An indicator for the collapsed items; a callback with the collapsed set. | Optional                                  | none          | caller                   | Stable    | —                                  |
-
-## Behavioral and layout contract
-
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                        | Basis                                                                   |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- |
-| FR1 | OverflowList renders a hidden measurement copy of every item, plus the indicator rendered for all items, and a visible container carrying the `overflow-list` target. The copy is `aria-hidden`, `inert`, invisible, zero-height, and takes no pointer input, so it is neither read, focused, nor clicked.                                                                                                                                       | Current source and tests                                                |
-| FR2 | Once measured, the visible container shows the items that fit the measured width (its own, or its parent's with `observeParent`), at least `minVisibleItems` and at most `maxVisibleItems`, with the floor winning over a smaller cap. Before measurement, including a server render, it shows every item and no indicator. With `collapseFrom="end"` it keeps the leading items; with `start`, the trailing ones. Items render in caller order. | Current source and tests                                                |
-| FR3 | When items collapse, the indicator `overflowRenderer` returns for the collapsed items renders after the visible items with `end`, or before them with `start`; without a renderer, collapsed items are dropped and no indicator renders.                                                                                                                                                                                                         | Current source and tests                                                |
-| FR4 | One row is a non-wrapping flex line that clips overflow. `maxRows` above 1 wraps items and limits the container's height to that many measured rows plus gaps. `gap` sets the spacing between items. With `observeParent` and items collapsed, the container fills its parent's width.                                                                                                                                                           | Current source and tests                                                |
-| FR5 | `onOverflowChange` receives the collapsed items, by original index, once the current content is measured: once on mount while overflowing, then only when the collapsed set's membership or order changes, including back to empty; never while nothing has overflowed, and never after unmount.                                                                                                                                                 | Current source and tests                                                |
-| FR6 | `ref`, DOM, data, ARIA, and event props, `xstyle`, `className`, and `style` reach or compose on the visible container.                                                                                                                                                                                                                                                                                                                           | Current source and tests; `architecture:public-component-api` INV5–INV8 |
-
-### Allowed variation
-
-- **AV1 — Content.** Item and indicator content may vary without becoming
-  OverflowList-owned targets.
-
-### Representative states
-
-| State              | Required invariant                                                    | Allowed variation  |
-| ------------------ | --------------------------------------------------------------------- | ------------------ |
-| All fit            | Every item, no indicator, no callback.                                | Gap.               |
-| Collapse end       | Leading items; indicator after them.                                  | Indicator content. |
-| Collapse start     | Trailing items; indicator before them.                                | Indicator content. |
-| Capped             | Once measured, at most `maxVisibleItems`, unless the floor is larger. | —                  |
-| Before measurement | Every item; no indicator.                                             | Server render.     |
-| Multi-row          | Wrapped items within `maxRows` rows.                                  | Rows.              |
-
-### Transformation and precedence order
-
-- **ORD1 — Visible count.** Before measurement, every item; once measured, the
-  measured fit → at most `maxVisibleItems` → at least `minVisibleItems`.
-- **ORD2 — Reporting.** Measure the current content first; report only a
-  changed collapsed set.
-
-### Performance and resources
-
-- **PR1 — Measurement.** OverflowList observes the measured box's size, renders
-  every item in the hidden copy and the visible ones again in the list, and
-  reports collapsed sets after measurement, before the frame paints.
-
-## Accessibility contract
-
-- **AR1 — One readable copy.** Only the visible container's items reach
-  assistive technology and keyboard focus; the measurement copy is hidden and
-  inert (FR1).
-- **AR2 — Caller-owned access to collapsed items.** Collapsed items leave the
-  visible list; the caller's indicator is the way to reach them, and its
-  semantics are the caller's.
-
-## Design relationships
-
-| Anatomy or state   | Design requirement                                                  | Representation authority | Hierarchy role    | Component contract |
-| ------------------ | ------------------------------------------------------------------- | ------------------------ | ----------------- | ------------------ |
-| List               | The visible list container.                                         | Current source and docs  | Supporting        | FR1, FR4           |
-| Items              | Caller items selected for display by width, rows, and count limits. | Caller-supplied content  | Context-dependent | FR2                |
-| Overflow indicator | Caller-rendered access to, or a count of, collapsed items.          | Caller-supplied content  | Context-dependent | FR3                |
-
-The hidden measurement copy is implementation structure, not consumer anatomy.
-
-### Theming anatomy
-
-<!-- anatomy-theming:v1 -->
-
-```json
-{
-  "List": {"target": "overflow-list"},
-  "Items": {
-    "none": {
-      "reason": "intentional: Caller-supplied items retain their own theming ownership; OverflowList applies no target to them."
-    }
-  },
-  "Overflow indicator": {
-    "none": {
-      "reason": "intentional: The caller-rendered overflow indicator retains its own theming ownership; OverflowList applies no target to it."
-    }
-  }
-}
-```
-
-## Family and system relationships
-
-- `architecture:component-theming-surface` owns anatomy qualification and the
-  `none` dispositions for caller content.
-- `architecture:public-component-api` owns caller-input routing; FR6 applies
-  it.
-
-## Verification map
-
-| Contract            | Verification                                                                                                                                                                                                                           | Representative states                                                                                                                             | Mutation or failure expectation                                                                                                                              | Audit section                 |
-| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------- |
-| FR1, AR1            | `OverflowList.test.tsx` measurement-container and rendering-contract tests                                                                                                                                                             | Hidden copy; indicator measured against all items; visible class                                                                                  | A measurement copy that is not `aria-hidden` and `inert`, an indicator measured against fewer items, or a target off the visible container fails.            | `audit:OverflowList/theming`  |
-| FR2, ORD1           | `OverflowList.test.tsx` fit, overflow, `minVisibleItems`, and cap tests; `useOverflow.test.ts` (including `observeParent`); `computeOverflow.test.ts`; stable visual baselines `core-overflowlist--default` (neutral and probe themes) | All fit; end and start; floor; cap; floor over cap                                                                                                | Wrong visible items, too few under a floor, too many under a cap, or a cap beating the floor fails; a changed default row comes back changed for review.     | `audit:OverflowList/behavior` |
-| FR3                 | `OverflowList.test.tsx` indicator-placement and no-renderer tests                                                                                                                                                                      | End; start; no renderer                                                                                                                           | An indicator on the wrong side, or one rendered without a renderer, fails.                                                                                   | `audit:OverflowList/anatomy`  |
-| FR4                 | `OverflowList.test.tsx` gap and `maxRows` tests                                                                                                                                                                                        | Gap change; `maxRows` 2 and 1                                                                                                                     | No class change for a new gap or for wrapping, or wrapping at `maxRows={1}`, fails. Gap: the row height limit and the `observeParent` fill have no check.    | `audit:OverflowList/layout`   |
-| FR5, ORD2           | `OverflowList.test.tsx` `onOverflowChange` suite                                                                                                                                                                                       | Silent fit; mount; original indices; back to empty; unchanged; reorder; content change; count change; callback swap; state update; unmount; start | A callback that fires without overflow, repeats an unchanged set, misses a change, reports unmeasured content, loops on state, or fires after unmount fails. | `audit:OverflowList/behavior` |
-| FR6                 | `OverflowList.test.tsx` ref and passthrough tests                                                                                                                                                                                      | Ref; DOM props                                                                                                                                    | A ref on another element or a dropped DOM prop fails. Gap: no test covers `className`, `style`, or the `xstyle` merge order.                                 | `audit:OverflowList/api`      |
-| AR2, PR1            | Source review                                                                                                                                                                                                                          | Collapsed items                                                                                                                                   | Gap: no automated check covers keyboard reach to collapsed items or the observer lifecycle.                                                                  | `audit:OverflowList/a11y`     |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                                                                                                                          | Canonical anatomy and current target                                                                                                              | Missing, extra, or stale mappings fail repository validation.                                                                                                | `audit:OverflowList/theming`  |
-
-## Decision log
-
-None recorded. The record describes shipped behavior.
-
-## Open questions
-
-None.
-
-## Content boundary
-
-This file does not duplicate consumer prop tables, examples, overflow
-measurement mechanics, implementation steps, or system rules. It links to their
-owners.

package/src/Overlay/Overlay.spec.md

@@ -1,304 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:Overlay
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-22
-owners: [cixzhang]
-review_triggers: [public-api, layout, accessibility]
-verified_by:
-  [
-    packages/core/src/Overlay/Overlay.test.tsx,
-    apps/storybook/stories/Overlay.stories.tsx,
-  ]
-modules: []
-families: []
-design_specs: [design:bidirectionality]
-architecture:
-  [
-    architecture:public-component-api,
-    architecture:component-theming-surface,
-    architecture:internationalization,
-  ]
-contributing: []
-system_specs: [spec:AST-002/DEC-1, spec:AST-017/FR5, spec:AST-027/FR2]
----
-
-# Overlay component contract
-
-<!-- Describe the system, not the project: present tense, what it does. No proposals, history, pull requests, or research in the record; see docs/contributing/spec-writing.md and report its rubric results in the pull request. -->
-
-This record governs how several pieces of content are placed over an Overlay's
-surface, each at a preset spot or at fractional coordinates, including the
-stacking of a container that holds such content. Overlay's scrim, reveal modes,
-own `position` values, and alignment remain described by its source, tests, and
-`Overlay.doc.mjs` until a record claims them.
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                                                                                                                                  |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | New `OverlayRegion` component, exported beside Overlay: `position` (required) is a preset (`'fill' \| 'top' \| 'bottom' \| 'center' \| 'top-start' \| 'top-end' \| 'bottom-start' \| 'bottom-end'`) or open placement `{x, y, width?, height?}` in 0–1 fractions; plus `children`, `ref`, `xstyle`, `className`, `style`. |
-| Behavior                | Inside a fill Overlay, a preset region sits at that spot (corners follow the writing direction) and open placement sits at fractions of the media measured from its top-left corner, never mirrored. A sized open region stays inside the media. Regions scale with the media.                                            |
-| End-user impact         | Several captions, tags, badges, or hotspots over one image or video each stay on their spot of the media at every size, in either text direction.                                                                                                                                                                         |
-| Builder impact          | None by default. A builder places content with `OverlayRegion` instead of hand-written absolute positioning; moving a region stays the builder's code.                                                                                                                                                                    |
-| Compatibility/readiness | Additive: a new component and export; an Overlay without a region renders and stacks exactly as before. This record is current authority; `OverlayRegion`, its consumer docs, region tests, and region stories have not shipped yet.                                                                                      |
-| Review checks           | Reject open placement that mirrors in right-to-left, corner presets that do not, JavaScript measurement or observers, drag or resize behavior inside Overlay, a role or focus stop on the region, a theme target on it, or a region placed inside a strip.                                                                |
-| Governing rules         | FR1–FR11 below; `design:bidirectionality/DR3`, `DR5`, `DR6`; `architecture:component-theming-surface/INV4`; `spec:AST-017/FR5`; `spec:AST-027/FR2`.                                                                                                                                                                       |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-Overlay layers content over a bounded surface, usually media, and places that
-content as one block: the whole surface or a band at the top or bottom. Some
-surfaces carry several pieces of content, each belonging to its own spot: two
-captions drawn into an image, a badge in a corner beside a caption, a tag on a
-face. A spot is either one of Overlay's familiar places or a point on the media
-described as fractions of its width and height, because the media is shown at
-many sizes and the spot must stay on the same pixels of it. Overlay owns that
-placement because Overlay owns the surface it is measured against.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`; an Overlay without a region renders and
-  stacks exactly as before. Only a container that holds a region isolates its
-  stacking (FR10).
-- Compatibility class: additive component and export.
-- Controlled/uncontrolled behavior: not applicable; a region holds no state.
-- Migration decision: none required (`spec:AST-017/FR5`).
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Ownership boundary
-
-**Owns**
-
-- `OverlayRegion`: its `position` values, their geometry, clamping, scaling, and
-  reference box.
-- The rule that open placement is measured in the media's own physical space.
-- The rule that regions are placed only in fill overlays, and the fallback
-  everywhere else.
-- The stacking isolation of a container that holds a region.
-
-**Does not own / non-goals**
-
-- Moving, dragging, or resizing a region, including pointer capture, keyboard
-  steps, snapping, and when a new position is reported — owned by the product
-  callsite (`component:Overlay/DEC-3`).
-- What a region paints: borders, fills, handles, and text — owned by the
-  region's content.
-- Making the base content fill the surface — owned by the caller, as for every
-  Overlay; fractions are measured against the surface, so media that does not
-  fill it does not line up with them.
-- Overlay's own `position` and `align` — unchanged; a region does not read or
-  alter them beyond FR2.
-- Placement relative to a trigger or outside the surface — owned by the layer
-  runtime (Popover, Tooltip, HoverCard).
-
-## Public concepts
-
-| Concept        | Closed values or states                                                                 | Meaning                                                                                                                                                                                                                             | Availability by variant/orientation/state | Default             | Owner               | Stability | Invalid-value behavior                                                                                  |
-| -------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------- | ------------------- | --------- | ------------------------------------------------------------------------------------------------------- |
-| Preset         | `fill`, `top`, `bottom`, `center`, `top-start`, `top-end`, `bottom-start`, `bottom-end` | `fill`, `top`, and `bottom` are the places Overlay's own `position` names: the whole surface, or a full-width band at that edge. `center` and the corners hold content-sized boxes at that spot.                                    | Fill overlays (FR2)                       | None; required prop | `component:Overlay` | stable    | Other strings are rejected by the public type                                                           |
-| Open placement | `{x, y, width?, height?}`; each a number from 0 to 1                                    | `x`, `y`: the region's top-left corner as fractions of its reference box, measured from that box's top-left corner. `width`, `height`: the region's size as fractions, extending right and down; omitted means it fits its content. | Fill overlays (FR2)                       | None; required prop | `component:Overlay` | stable    | Values clamped into 0–1; a non-finite coordinate is treated as 0 and a non-finite size as omitted (FR6) |
-
-## Behavioral and layout contract
-
-| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Basis                                                       | Draft review state |
-| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------ |
-| FR1  | `OverlayRegion` rendered directly in the content of an Overlay or `useOverlay` host with `position="fill"`, the default, MUST position against that host's scrim box, which is the whole base surface: 0 and 1 are the media's edges, and the box matches the Overlay's `ref`. Any element between the region and the scrim that establishes a containing block for absolutely positioned descendants becomes its reference box instead. In this record, the surface means the region's reference box.                                                            | `component:Overlay/DEC-1`                                   | settled            |
-| FR2  | Regions are placed only in fill hosts. A region rendered anywhere else MUST NOT be placed: in the content of an Overlay or `useOverlay` host whose `position` is `"top"` or `"bottom"`, in an Overlay's `children`, or with no Overlay or `useOverlay` host at all, it renders its content as ordinary in-flow content where it stands (in a strip, that content reveals and slides with the strip) and MUST emit one development warning per mount naming the fill-only rule.                                                                                    | `component:Overlay/DEC-4`                                   | settled            |
-| FR3  | A preset region MUST sit at its spot inside Overlay's content inset: `fill` covers the inset box; `top` and `bottom` span its full width at that edge with content height; `center` is content-sized at its center; each corner is content-sized at that corner. Content larger than the inset box is clipped by the container, not shifted.                                                                                                                                                                                                                      | `component:Overlay/DEC-2`                                   | settled            |
-| FR4  | Corner presets MUST resolve `start` and `end` against the writing direction of the region's own context: `top-start` is the top-left corner in left-to-right and the top-right corner in right-to-left. `fill`, `top`, `bottom`, and `center` are symmetric and do not change with direction.                                                                                                                                                                                                                                                                     | `design:bidirectionality/DR3`                               | settled            |
-| FR5  | Open placement MUST measure `x` from the surface's left edge and `y` from its top edge in every writing direction, and MUST NOT mirror in right-to-left. The region's own content follows the ambient direction.                                                                                                                                                                                                                                                                                                                                                  | `design:bidirectionality/DR5`                               | settled            |
-| FR6  | Open coordinates and sizes MUST be clamped into 0–1 before placement. A non-finite coordinate MUST resolve to 0, and a non-finite size MUST resolve to omitted.                                                                                                                                                                                                                                                                                                                                                                                                   | Invalid-value behavior                                      | settled            |
-| FR7  | Open placement puts the region's top-left corner at (`x`, `y`) (`component:Overlay/DEC-6`). On an axis with a size, the region MUST be exactly that fraction of the surface, extending right or down, and MUST sit wholly inside it: its start is clamped between 0 and one minus the size. On an axis without a size, the region MUST fit its content starting at the coordinate, and any overhang past the container's edge is clipped, not shifted inward.                                                                                                     | `component:Overlay/DEC-5`                                   | settled            |
-| FR8  | When the surface changes size, every region MUST keep its spot: presets by their insets, open placement by its fractional position and size, without a re-render.                                                                                                                                                                                                                                                                                                                                                                                                 | `component:Overlay/DEC-1`                                   | settled            |
-| FR9  | A region MUST appear, hide, and become inert with the overlay content that contains it, following Overlay's `showOn` and `isOpen`, and MUST inherit the scrim's media theme. It adds no visibility rule of its own.                                                                                                                                                                                                                                                                                                                                               | Overlay's existing reveal behavior                          | settled            |
-| FR10 | A placed region MUST paint above the fill surface's in-flow overlay content, including positioned in-flow content written after it, and a later placed region MUST paint above an earlier one. A placed region inside a wrapper that forms a stacking context is ordered only among that wrapper's content. An Overlay or `useOverlay` container with a placed region anywhere inside it MUST own an isolated stacking context; a container with no region inside it keeps its stacking unchanged. A placed region MUST NOT take part in the scrim's flow layout. | Absolute positioning within the surface; `spec:AST-027/FR2` | settled            |
-| FR11 | Overlay and `OverlayRegion` MUST NOT move, drag, or resize a region, and MUST NOT attach pointer, keyboard, or gesture handlers to it. A region moves only when its caller passes a new `position`.                                                                                                                                                                                                                                                                                                                                                               | `component:Overlay/DEC-3`                                   | settled            |
-
-### Allowed variation
-
-- **AV1 — Content.** Any content may sit in a region; on an open region each
-  axis is sized or content-sized independently (FR7).
-- **AV2 — Surface size and shape.** The surface may be any size or aspect ratio,
-  and may change size at any time (FR8).
-- **AV3 — Mixed content.** In-flow overlay content, preset regions, and open
-  regions may share one surface (FR10).
-
-### Representative states
-
-| State                                                    | Required invariant                                                                                        | Allowed variation  |
-| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------ |
-| Two captions, `top` and `bottom` presets                 | Each spans the inset width at its edge, like Overlay's own strips.                                        | Caption text.      |
-| `top-start` badge, left-to-right and right-to-left       | Top-left corner in left-to-right; top-right corner in right-to-left.                                      | Badge content.     |
-| Open sized caption near the right edge                   | Box is the given fraction of the image and stays wholly inside, flush with that edge.                     | Which edge.        |
-| Open content-sized pin                                   | Pin starts at its point and extends right and down; overhang past the container is clipped.               | Pin content.       |
-| Open region, right-to-left page                          | Same spot on the media as left-to-right; the region's text reads right-to-left.                           | Writing direction. |
-| Surface resized from 640px to 320px wide                 | Every region keeps its spot, with no re-render.                                                           | Any surface size.  |
-| Region in an Overlay's `children` or outside any Overlay | Is not placed: its content flows where it stands, and it warns once in development.                       | Location.          |
-| Region in a `position="bottom"` Overlay                  | Is not placed: its content flows in the strip like other strip content, and it warns once in development. | Strip content.     |
-| `showOn="hover"` overlay at rest                         | Regions are hidden with the rest of the overlay content.                                                  | Reveal mode.       |
-
-### Transformation and precedence order
-
-- **ORD1 — Placement.** Resolve the reference box (FR1, FR2) → for a preset,
-  place it in the content inset and resolve start/end against direction (FR3,
-  FR4); for open placement, clamp values (FR6) and resolve each axis as sized or
-  content-sized in physical space (FR5, FR7) → express the result as insets and
-  fractions of the box (FR8). Styling inputs compose after placement in the order
-  `architecture:public-component-api/INV6` gives; a caller who overrides inset or
-  size properties owns the result.
-
-### Performance and resources
-
-- **PR1 — CSS geometry only.** Placement, clamping, and scaling MUST be achieved
-  with arithmetic on the given values and CSS: no measurement, observer,
-  listener, state, Effect, or extra render pass. The fill-only check adds no
-  measurement, state, or extra render pass.
-
-## Accessibility contract
-
-- **AR1 — Presentation only.** `OverlayRegion` MUST add no role, accessible name,
-  description, focus stop, or text. Its content keeps its own semantics.
-- **AR2 — Source order is reading order.** Assistive technology and keyboard
-  focus follow the regions' source order, not their position on the surface. A
-  caller renders regions in the order a reader should meet them.
-- **AR3 — Movement offers non-drag paths.** Overlay's documented move pattern
-  for open regions pairs pointer dragging with a single-pointer path that needs
-  no drag, where activating a spot on the media moves the region there, and a
-  keyboard path that moves a region whose content has focus by a fixed step per
-  arrow key, with arrow directions matching the visual axes
-  (`design:bidirectionality/DR6`).
-
-## Design relationships
-
-| Anatomy or state     | Design requirement                                           | Representation authority      | Hierarchy role | Component contract |
-| -------------------- | ------------------------------------------------------------ | ----------------------------- | -------------- | ------------------ |
-| Preset region        | Reads as Overlay's own places, with Overlay's content inset. | Owner direction               | Supporting     | FR3                |
-| Corner preset in RTL | Leading and trailing corners follow reading order.           | `design:bidirectionality/DR3` | Supporting     | FR4                |
-| Open region          | Stays on the same spot of the media at every size.           | Owner direction               | Supporting     | FR7, FR8           |
-| Open region in RTL   | Media is physical content and does not mirror.               | `design:bidirectionality/DR5` | Supporting     | FR5                |
-
-## Family and system relationships
-
-- `design:bidirectionality` owns direction behavior: FR4 applies DR3 to corner
-  presets, FR5 applies DR5 to open placement, and AR3 applies DR6 to movement.
-- `architecture:component-theming-surface/INV4` keeps a non-painting box out of
-  the theme surface: the region is a geometry-only box that paints nothing, so it
-  has no theme target and its content owns its paint.
-- `architecture:public-component-api` owns prop admission and styling-input
-  order; ORD1 applies INV6.
-- `spec:AST-027/FR2` puts the isolation boundary on the surface; FR10 makes the
-  Overlay or `useOverlay` container that holds a region that owner.
-- `spec:AST-017/FR5` classifies this as nonbreaking: it adds a new component,
-  changes no default, and a caller who never renders a region sees no change.
-
-## Verification map
-
-| Contract                      | Verification                                                         | Representative states                                                                                                                             | Mutation or failure expectation                                                                                                                                             | Audit section          |
-| ----------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
-| FR1, FR2, FR6, FR11           | `Overlay.test.tsx` region suite                                      | Region in Overlay and `useOverlay` content; in a `bottom` Overlay; outside any Overlay; out-of-range and non-finite input; pointer and key events | Unclamped values, a region outside the scrim, a placed region in a strip or a missing warning, or a region that moves on its own fails.                                     | `audit:Overlay/api`    |
-| FR3, FR4, FR5, FR7, FR8, FR10 | Real-Chromium assertions in the Overlay region story's play function | Every preset; open sized, edge-clamped, and content-sized; resized surface; RTL; a region before a positioned control                             | A region off its spot by more than 0.5px, a corner that does not flip or an open region that does, the in-flow control hit at a region's center, or wrong isolation, fails. | `audit:Overlay/layout` |
-| FR9                           | `Overlay.test.tsx` reveal case with a region                         | `isOpen={false}`                                                                                                                                  | A region outside the scrim, or a closed scrim that is not inert, fails.                                                                                                     | `audit:Overlay/api`    |
-| AR1, AR2                      | `Overlay.test.tsx` DOM check of the region element                   | Text content                                                                                                                                      | Any attribute other than `class` and `style` on the region element, or text it adds, fails.                                                                                 | `audit:Overlay/a11y`   |
-| AR3                           | Region move story's play function                                    | Arrow key and single activation on the media, LTR and RTL                                                                                         | ArrowRight moving a region left, or an activation that does not move the region to the activated spot, fails.                                                               | `audit:Overlay/a11y`   |
-| PR1                           | Source review of `OverlayRegion`                                     | All inputs                                                                                                                                        | A ref read, observer, listener, or Effect added for placement fails review.                                                                                                 | `audit:Overlay/layout` |
-
-## Decision log
-
-<!-- Record the boundary or requirement, not how it was reached. A rejected alternative is at most one line here, kept only when it is consequential and likely to recur. -->
-
-### DEC-1 — Several placed items are Overlay regions with one `position` prop
-
-**Reference:** `component:Overlay/DEC-1`
-**Decider:** cixzhang, 2026-10-22
-
-Overlay places one content block, so a surface with several spots needs a child
-that places itself. `OverlayRegion` inside Overlay's content inherits Overlay's
-surface, reveal, and media theme with no new Overlay prop, and one `position`
-prop covers both kinds of spot: a named place or open placement. Sizes live
-inside the open placement object, so a region never carries `width` or `height`
-props whose numbers mean fractions while the same names mean pixels on Card,
-Button, and Grid.
-
-Rejected: an object form of Overlay's own `position`, because it still places
-only one block.
-
-### DEC-2 — Presets reuse Overlay's places and add the center and corners
-
-**Reference:** `component:Overlay/DEC-2`
-**Decider:** cixzhang, 2026-10-22
-
-`fill`, `top`, and `bottom` mean on a region what they mean on Overlay, so a
-builder reads one vocabulary. Static badges and labels need the center and the
-corners, which Overlay's single block cannot hold beside other content. Corners
-use `start` and `end` because a leading badge leads in either direction.
-
-### DEC-3 — Moving a region stays at the callsite
-
-**Reference:** `component:Overlay/DEC-3`
-**Decider:** cixzhang, 2026-10-22
-
-What moving a region means differs by product: whether the position commits on
-release or live, the keyboard step, snapping, which regions move, and what
-happens while a new rendering of the media loads. Overlay therefore never moves
-a region; the caller converts pointer and keyboard input into new fractions
-measured against the region's reference box and passes them back.
-
-Rejected: a drag hook on Overlay, because a shared drag primitive needs its own
-record and more than one caller's needs.
-
-### DEC-4 — Regions belong to fill overlays
-
-**Reference:** `component:Overlay/DEC-4`
-**Decider:** cixzhang, 2026-10-22
-
-A spot on the media is meaningless inside a strip whose height follows its own
-content and which slides in and out. A strip is also the containing block of
-everything inside it, so CSS cannot place a region against the media from
-there. In a strip overlay a region therefore renders its content as ordinary
-strip content and warns in development, so the content stays visible. The
-public type cannot enforce the rule, because regions arrive through `content`.
-The same fallback applies outside any fill host, where there is no surface to
-measure against and nothing to isolate a region's paint order.
-
-Rejected: placing a strip's regions against the container, because escaping the
-strip needs a second rendering layer that duplicates Overlay's reveal.
-
-### DEC-5 — Open sized axes are clamped inside; content-sized axes are not
-
-**Reference:** `component:Overlay/DEC-5`
-**Decider:** cixzhang, 2026-10-22
-
-A sized region can be kept inside the surface with arithmetic on the given
-fractions, so it never spills off the media however far it is moved. Keeping a
-content-sized region inside would require measuring it, which PR1 forbids, so
-the container clips any overhang.
-
-### DEC-6 — Open placement names the region's top-left corner
-
-**Reference:** `component:Overlay/DEC-6`
-**Decider:** cixzhang, 2026-10-22
-
-`x` and `y` are the region's top-left corner, and `width` and `height` extend
-right and down. That matches how servers and editors report boxes (left, top,
-width, height) and how CSS insets read, so a reported box passes through with no
-conversion and is clamped with plain arithmetic.
-
-Rejected: the region's center, because every reported box would need converting.
-
-## Open questions
-
-None.
-
-## Content boundary
-
-This file does not duplicate consumer prop tables/examples, current audit
-results, implementation steps, or family/system rules. It links to their owners.