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

package/src/Chat/ChatLayoutScrollButton.spec.md

@@ -1,13 +1,13 @@
 ---
 schema_version: 3
-template_version: 5
+template_version: 7
 kind: component
 id: component:ChatLayoutScrollButton
-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: [public-api, behavior, accessibility, theming, testing]
 verified_by:
@@ -38,15 +38,15 @@ system_specs: [spec:AST-029]
 
 ## Contract at a glance
 
-| Area                    | Contract                                                                                                                                                                                                                                                      |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | `isVisible`, `label`, and `onClick`, plus root `div` passthrough, styles, and ref. No public surface changes here.                                                                                                                                            |
-| Behavior                | A pill holding one ghost Button. Hidden state paints nothing and leaves the tab order; a non-empty `label` expands the pill and becomes the visible text; omitted or empty renders icon-only.                                                                 |
-| End-user impact         | A theme that restyles the documented target now repaints the pill a reader sees instead of an invisible full-width row behind it.                                                                                                                             |
-| Builder impact          | None. Props, defaults, DOM shape, ref target, and passthrough element are unchanged.                                                                                                                                                                          |
-| Compatibility/readiness | Patch-compatible repair. The public target keeps its name and stays a single target; it moves onto the element that paints, which no `guaranteedProperties` declaration existed to promise before. Three inherited violations remain open (FR1a, FR3a, FR6a). |
-| Review checks           | Reject a target on the centring row, a hidden pill that keeps keyboard focus, a non-empty label that is not also the accessible name, or a state that paints identically to its opposite. FR1a, FR3a, and FR6a are recorded open violations, not acceptances. |
-| Governing rules         | `architecture:component-theming-surface/INV4, INV6`; `architecture:component-style-authoring/INV1, INV5`; `architecture:public-component-api/INV5, INV6, INV8`; WCAG 2.2 SC 2.4.7 and SC 2.5.8 (AA).                                                          |
+| Area                    | Contract                                                                                                                                                                                                                                           |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `ChatLayoutScrollButton` with required `isVisible` and `onClick`, optional `label`, and root `div` passthrough, styles, and ref.                                                                                                                   |
+| Behavior                | A pill holding one ghost Button. Hidden state paints nothing and leaves the tab order; a non-empty `label` expands the pill and becomes the visible text; omitted or empty renders icon-only.                                                      |
+| End-user impact         | Readers who scrolled up get one control back to the newest message, which is hidden and out of the tab order when they are already there; a theme that restyles its target repaints the pill they see.                                             |
+| Builder impact          | None.                                                                                                                                                                                                                                              |
+| Compatibility/readiness | Records shipped behavior; no public change. Three implementation gaps (FR1a, FR3a, FR6a) are listed under Current-state impact; eight owner questions stay open.                                                                                   |
+| Review checks           | Reject a target on the centring row, a hidden pill that keeps keyboard focus, a non-empty label that is not also the accessible name, or a state that paints identically to its opposite. FR1a, FR3a, and FR6a are recorded gaps, not acceptances. |
+| Governing rules         | `architecture:component-theming-surface/INV4`; `architecture:component-style-authoring/INV1, INV5`; `architecture:public-component-api/INV5, INV6, INV8`; WCAG 2.2 SC 2.4.7 and SC 2.5.8 (AA).                                                     |
 
 This table is a review projection; the body below is authoritative.
 
@@ -58,24 +58,28 @@ it owns no scroll state. ChatLayout composes it with `useChatStreamScroll` and
 `useChatNewMessages` by default, and a caller may replace or remove it through
 `ChatLayout`'s `scrollButton` slot.
 
-This record is an observational backfill written during the 2026-09-23
-whole-component audit. It describes verified shipped behavior and the one
-objective repair that travels with it. It adds no behavior, default,
-compatibility promise, or design decision.
-
 ## Compatibility and migration
 
-- Released default preserved: yes — `@astryxdesign/core@0.6.3` ships
-  `isVisible`, `label`, and `onClick` with the same meanings.
-- Compatibility class: theming repair. The target name, its documentation entry,
-  and its count are unchanged; only the element carrying it moves, from the
-  centring row to the pill it centres.
-- Controlled/uncontrolled behavior: unchanged — visibility is a required caller
-  input, and the component holds no state.
-- Migration decision: `component:ChatLayoutScrollButton/DEC-1`
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public change
+- Controlled/uncontrolled behavior: visibility is a required caller input, and
+  the component holds no state
+- Migration decision: none; DEC-1 records where the target sits
 
 Consumer migration instructions belong in consumer docs and release notes.
 
+## Current-state impact
+
+- **An empty label leaves the control unnamed (FR1a).** `label=''` renders an
+  icon-only control with an empty accessible name; WCAG 2.2 SC 4.1.2 requires a
+  name (OQ7).
+- **The focus ring is clipped away (FR3a).** The pill's `overflow: hidden`
+  clips the Button's outset focus ring, so a focused control looks the same as
+  a resting one; WCAG 2.2 SC 2.4.7 requires a visible indicator (OQ8).
+- **A theme cannot address the pill's states (FR6a).** The pill's visible and
+  expanded states change its paint, but the target exposes neither, so a theme
+  can restyle the pill only as a whole (OQ1).
+
 ## Ownership boundary
 
 **Owns**
@@ -104,30 +108,27 @@ Consumer migration instructions belong in consumer docs and release notes.
 | `label` — omitted   | `undefined`                 | Icon-only; the translated default becomes the accessible name        | always                                    | this is the default | `component:ChatLayoutScrollButton`  | stable    | —                                                 |
 | `label` — non-empty | any non-empty string        | Visible text, which is also the accessible name                      | always                                    | —                   | `component:ChatLayoutScrollButton`  | stable    | —                                                 |
 | `label` — empty     | `''`                        | Icon-only with an empty accessible name — see FR1a                   | always                                    | —                   | `component:ChatLayoutScrollButton`  | stable    | no fallback is applied; the control is unnamed    |
-| `onClick`           | `() => void`                | Activation callback; receives no event                               | always                                    | required            | `component:ChatLayoutScrollButton`  | stable    | required; no default action                       |
+| `onClick`           | `() => void`                | Activation callback; its type declares no arguments                  | always                                    | required            | `component:ChatLayoutScrollButton`  | stable    | required; no default action                       |
 | root `div`          | `BaseProps<HTMLDivElement>` | `ref`, `xstyle`, `className`, `style`, and remaining DOM passthrough | always                                    | none                | `architecture:public-component-api` | stable    | `onClick` is omitted from the inherited DOM props |
 
 Consumer syntax and prop defaults remain in `ChatLayoutScrollButton.doc.mjs`.
 
 ## Behavioral and layout contract
 
-Draft requirements identify their basis so observed code is not mistaken for an
-intentional decision. A `current` contract contains no unresolved rows.
-
-| ID   | Candidate invariant                                                                                                                   | Basis                                                                  | Draft review state    |
-| ---- | ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | --------------------- |
-| FR1  | The control MUST expose a non-empty accessible name in every reachable state.                                                         | WCAG 2.2 SC 4.1.2                                                      | settled obligation    |
-| FR1a | `label` omitted uses the translated default; a non-empty `label` is the name. **`label=''` currently satisfies neither** — see below. | current behavior, which violates FR1                                   | **violation of FR1**  |
-| FR2  | While `isVisible` is false the pill MUST paint nothing and MUST NOT accept focus, programmatic or sequential.                         | current behavior; WCAG 2.2 SC 2.4.7                                    | settled               |
-| FR3  | While `isVisible` is true the pill MUST remain keyboard reachable and activate on Enter.                                              | current behavior; WCAG 2.2 SC 2.1.1                                    | settled               |
-| FR3a | A focused control MUST paint a visible focus indicator. **The ring is currently clipped away entirely** — see below.                  | WCAG 2.2 SC 2.4.7; `spec:AST-020/FR1`                                  | **violation of FR3a** |
-| FR4  | A **non-empty** `label` MUST render as visible text; omitted or empty renders icon-only with no visible text.                         | current behavior                                                       | settled               |
-| FR5  | The pill MUST take its resolved height from the element-size token so no theme scale makes it clip the Button it wraps.               | current behavior                                                       | settled               |
-| FR6  | The public theming target MUST sit on the pill — the element painting fill, elevation, and radius — not on the row that centres it.   | `architecture:component-theming-surface/INV4`                          | settled               |
-| FR6a | The target MUST expose the state axes that drive its painted styles. **Currently it reflects none** — see below.                      | `architecture:component-theming-surface/INV6`                          | **violation of INV6** |
-| FR7  | The transition between states MUST collapse to `0s` under `prefers-reduced-motion: reduce`.                                           | current behavior                                                       | settled               |
-| FR8  | The collapsed control MUST fit a 24x24 CSS-px square.                                                                                 | WCAG 2.2 SC 2.5.8 (AA)                                                 | settled               |
-| FR9  | Consumer `ref`, styles, and remaining DOM props MUST reach the component's outer element.                                             | current behavior; `architecture:public-component-api/INV5, INV6, INV8` | settled               |
+| ID   | Invariant                                                                                                                                                                                                            | Basis                                                                          |
+| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| FR1  | The control MUST expose a non-empty accessible name in every reachable state.                                                                                                                                        | WCAG 2.2 SC 4.1.2                                                              |
+| FR1a | `label` omitted uses the translated default; a non-empty `label` is the name. Implementation gap: `label=''` satisfies neither (Current-state impact).                                                               | Current source                                                                 |
+| FR2  | While `isVisible` is false the pill MUST paint nothing and MUST NOT accept focus, programmatic or sequential.                                                                                                        | Current source and tests; WCAG 2.2 SC 2.4.7                                    |
+| FR3  | While `isVisible` is true the pill MUST remain keyboard reachable and activate on Enter.                                                                                                                             | Current source and tests; WCAG 2.2 SC 2.1.1                                    |
+| FR3a | A focused control MUST paint a visible focus indicator. Implementation gap: the ring is clipped away entirely (Current-state impact).                                                                                | WCAG 2.2 SC 2.4.7; `spec:AST-020/FR1`                                          |
+| FR4  | A **non-empty** `label` MUST render as visible text; omitted or empty renders icon-only with no visible text.                                                                                                        | Current source and tests                                                       |
+| FR5  | The pill MUST take its resolved height from the element-size token so no theme scale makes it clip the Button it wraps.                                                                                              | Current source and tests                                                       |
+| FR6  | The public theming target MUST sit on the pill — the element painting fill, elevation, and radius — not on the row that centres it.                                                                                  | `architecture:component-theming-surface/INV4`                                  |
+| FR6a | The target reflects neither the visible nor the expanded state that drives its paint. Implementation gap: a theme cannot address either state; whether the target should reflect them is OQ1 (Current-state impact). | Current source                                                                 |
+| FR7  | The transition between states MUST collapse to `0s` under `prefers-reduced-motion: reduce`.                                                                                                                          | Current source                                                                 |
+| FR8  | The collapsed control MUST be at least 24 by 24 CSS pixels.                                                                                                                                                          | WCAG 2.2 SC 2.5.8 (AA)                                                         |
+| FR9  | Consumer `ref`, styles, and remaining DOM props MUST reach the component's outer element.                                                                                                                            | Current source and tests; `architecture:public-component-api/INV5, INV6, INV8` |
 
 **FR1a — the empty-label naming gap.** `label=''` is permitted by the public
 type and is what ordinary caller code produces from an empty or not-yet-loaded
@@ -141,25 +142,18 @@ operable control with no accessible name.
 This record states the obligation and records the current behavior as violating
 it. Closing the gap means choosing between falling back to the default name,
 rejecting the value, or treating an empty label as a caller error — a public
-API and compatibility decision that belongs to the owner, not to an audit. See
-OQ7.
-
-**FR3a — the clipped focus ring.** The composed Button declares a focus ring
-as an `outline` at a positive `outline-offset`, so it is painted entirely
-outside the button's border box. The button fills the pill exactly (measured
-32x32 in 32x32 collapsed, 149x32 in 149x32 labelled), and the pill clips with
-`overflow: hidden`, which it needs to keep the collapse/expand animation inside
-its own rounded shape. There is therefore no room for the ring on any side and
-none of it is painted: captured frames of the focused control are byte-identical
-to the resting control in both configurations and both color modes.
+API and compatibility decision that belongs to the owner. See OQ7.
+
+**FR3a — the clipped focus ring.** The composed Button draws its focus ring as
+an `outline` at a positive `outline-offset`, outside its border box. The button
+fills the pill, and the pill clips with `overflow: hidden` to keep the
+collapse/expand animation inside its rounded shape, so none of the ring is
+painted.
 
 Keyboard access itself is intact — the control takes focus and activates — so
 this is a visibility defect, not a reachability one. The remedy is a production
 change to how the pill clips or where the ring is drawn, and the choice between
-those changes rendered geometry, so it needs a visual review rather than a
-settled correction. `spec:AST-029/FR7` would allow a settled objective fix to
-travel with an audit; this one is not settled, so it is outside **this** PR.
-Recorded as OQ8.
+those changes rendered geometry, so it needs a visual review. Recorded as OQ8.
 
 **FR6a — the unreflected state axes.** `isVisible` selects visible/hidden
 styles and `label` selects collapsed/expanded styles, both on the painting
@@ -184,7 +178,7 @@ the owner. See OQ1.
 | State                     | Required invariant                                                                                           | Allowed variation                 |
 | ------------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------- |
 | hidden                    | paints nothing, refuses focus, keeps its layout box (FR2)                                                    | transition duration               |
-| visible, label omitted    | named from the default, focusable, fits a 24px square, no visible text (FR1, FR3, FR4, FR8)                  | resolved pill size                |
+| visible, label omitted    | named from the default, focusable, at least 24 by 24 CSS pixels, no visible text (FR1, FR3, FR4, FR8)        | resolved pill size                |
 | visible, non-empty label  | the label is both the visible text and the accessible name (FR1, FR4)                                        | expanded width up to the ceiling  |
 | visible, empty label      | **fails FR1** — icon-only with an empty accessible name (FR1a)                                               | none; this is a recorded defect   |
 | visible, hovered          | the pointer paints a state distinct from rest                                                                | the overlay the theme resolves    |
@@ -198,9 +192,6 @@ the owner. See OQ1.
   rendered difference from its props during render and registers no listener,
   timer, observer, or animation frame.
 
-Current measurements belong in the audit record; this subsection owns only
-durable constraints and their verification target.
-
 ## Accessibility contract
 
 - **AR1 — Named.** The control MUST expose a non-empty accessible name in every
@@ -214,8 +205,8 @@ durable constraints and their verification target.
 - **AR3a — Focus is visible.** A focused control MUST paint a focus indicator
   (WCAG 2.2 SC 2.4.7). The ring is declared but clipped away; recorded as FR3a
   rather than resolved here.
-- **AR3 — Target size.** The collapsed control MUST fit a 24x24 CSS-px square
-  (WCAG 2.2 SC 2.5.8 AA) (FR8).
+- **AR3 — Target size.** The collapsed control MUST be at least 24 by 24 CSS
+  pixels (WCAG 2.2 SC 2.5.8 AA) (FR8).
 - **AR4 — Reduced motion.** The state transition MUST collapse to `0s` under
   `prefers-reduced-motion: reduce` (FR7).
 - **AR5 — Translated strings.** The default accessible name MUST resolve through
@@ -242,23 +233,29 @@ scroll affordance today, so these rows record the gap rather than a requirement.
   excludes components that merely use a Button as an action slot. See OQ4.
 - `architecture:component-theming-surface` owns the target/anatomy relationship
   this component's theming must satisfy; FR6 adopts INV4 directly.
-- `spec:AST-029` owns the audit flow that produced this observational record.
+- `spec:AST-029` owns the audit evidence inventory this record's verification
+  map follows.
 
 ## Verification map
 
-| Contract       | Verification                                                                                                                                                                                                                                                                                             | Representative states                  | Mutation or failure expectation                                                                            | Audit section                             |
-| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
-| FR1, FR4       | `ChatLayoutScrollButton.test.tsx` role/name and visible-text cases                                                                                                                                                                                                                                       | label omitted; non-empty label         | dropping `isIconOnly` renders the translated name as clipped visible text, and the name case still passes  | `audit:ChatLayoutScrollButton/a11y`       |
-| FR1a           | **no oracle in any lane today.** Derived from source across three files (`??` passing `''` through, Button's `label !== ''` guard, the Icon's decorative default). A checked-in fixture would add an unnamed control to the shared story set and a new axe baseline entry, so the audit did not add one. | label empty                            | a fallback added here would make the derivation stale without any test failing                             | `audit:ChatLayoutScrollButton/a11y`       |
-| FR2, FR3       | `ChatLayoutScrollButton.test.tsx` tab cases; `ChatLayoutScrollButton.a11y.chromium.spec.ts`                                                                                                                                                                                                              | hidden at rest; scrolled up; re-hidden | replacing `visibility` with `opacity` alone leaves the invisible control in the tab order                  | `audit:ChatLayoutScrollButton/a11y`       |
-| FR3a           | `ChatLayoutScrollButtonSurface.a11y.chromium.spec.ts` interaction pass: the focused frame's bytes are compared with a rest frame captured from the same page, and the ring's outward reach is measured against the clipping ancestor's room (recorded as `ringChangedPixels`, `outreach`, `roomPx`)      | collapsed and labelled, light and dark | the result is recorded and annotated, never asserted, so repairing the clip cannot turn this check red     | `audit:ChatLayoutScrollButton/a11y`       |
-| FR5            | `ChatLayoutScrollButton.a11y.chromium.spec.ts` two-theme geometry pair and its pre-fix arm                                                                                                                                                                                                               | neutral and butter                     | a literal height lets a larger element scale clip the Button the pill wraps                                | `audit:ChatLayoutScrollButton/theming`    |
-| FR6            | `ChatLayoutScrollButtonSurface.a11y.chromium.spec.ts` placement and probe-theme reach tests                                                                                                                                                                                                              | visible, collapsed, neutral and probe  | moving the target back to the centring row leaves the pill unchanged under the probe theme                 | `audit:ChatLayoutScrollButton/theming`    |
-| FR6a           | source: `themeProps()` is called with no state argument, and `Chat.doc.mjs` declares the target with no `visualProps`/`states`                                                                                                                                                                           | visible/hidden; collapsed/expanded     | adding either axis is new public theming surface, so no test may assert its shape before the owner decides | `audit:ChatLayoutScrollButton/theming`    |
-| hover, pressed | `ChatLayoutScrollButtonSurface.a11y.chromium.spec.ts` interaction pass — each frame asserts the pseudo-class matched and that the captured bytes differ from a rest frame of the same page                                                                                                               | collapsed and labelled, light and dark | a frame captured after release, or with the pointer elsewhere, fails its own engagement assertion          | `audit:ChatLayoutScrollButton/design`     |
-| FR7            | source declaration plus `holdMotionStill` capture conditions                                                                                                                                                                                                                                             | any transition                         | removing the reduced-motion branch restores animation for readers who asked for none                       | `audit:ChatLayoutScrollButton/a11y`       |
-| FR8            | `ChatLayoutScrollButtonSurface.a11y.chromium.spec.ts` measured target box                                                                                                                                                                                                                                | visible, collapsed                     | a smaller resolved size drops the control below the AA minimum                                             | `audit:ChatLayoutScrollButton/a11y`       |
-| FR9            | `ChatLayoutScrollButton.test.tsx` passthrough case                                                                                                                                                                                                                                                       | any                                    | dropping `...rest` silently discards `data-*`, `id`, and ARIA the caller set                               | `audit:ChatLayoutScrollButton/public-api` |
+| Contract       | Verification                                                                                                                                                                                                                                                                                        | Representative states                  | Mutation or failure expectation                                                                            | Audit section                             |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| FR1, FR4       | `ChatLayoutScrollButton.test.tsx` role/name and visible-text cases                                                                                                                                                                                                                                  | label omitted; non-empty label         | dropping `isIconOnly` renders the translated name as clipped visible text, and the name case still passes  | `audit:ChatLayoutScrollButton/a11y`       |
+| FR1a           | No focused test; read from source across three files (`??` passing `''` through, Button's `label !== ''` guard, the Icon's decorative default).                                                                                                                                                     | label empty                            | a fallback added here would make the derivation stale without any test failing                             | `audit:ChatLayoutScrollButton/a11y`       |
+| FR2, FR3       | `ChatLayoutScrollButton.test.tsx` tab cases; `ChatLayoutScrollButton.a11y.chromium.spec.ts`                                                                                                                                                                                                         | hidden at rest; scrolled up; re-hidden | replacing `visibility` with `opacity` alone leaves the invisible control in the tab order                  | `audit:ChatLayoutScrollButton/a11y`       |
+| FR3a           | `ChatLayoutScrollButtonSurface.a11y.chromium.spec.ts` interaction pass: the focused frame's bytes are compared with a rest frame captured from the same page, and the ring's outward reach is measured against the clipping ancestor's room (recorded as `ringChangedPixels`, `outreach`, `roomPx`) | collapsed and labelled, light and dark | the result is recorded and annotated, never asserted, so repairing the clip cannot turn this check red     | `audit:ChatLayoutScrollButton/a11y`       |
+| FR5            | `ChatLayoutScrollButton.a11y.chromium.spec.ts` two-theme geometry pair                                                                                                                                                                                                                              | neutral and butter                     | a literal height lets a larger element scale clip the Button the pill wraps                                | `audit:ChatLayoutScrollButton/theming`    |
+| FR6            | `ChatLayoutScrollButtonSurface.a11y.chromium.spec.ts` placement and probe-theme reach tests                                                                                                                                                                                                         | visible, collapsed, neutral and probe  | moving the target back to the centring row leaves the pill unchanged under the probe theme                 | `audit:ChatLayoutScrollButton/theming`    |
+| FR6a           | source: `themeProps()` is called with no state argument, and `Chat.doc.mjs` declares the target with no `visualProps`/`states`                                                                                                                                                                      | visible/hidden; collapsed/expanded     | adding either axis is new public theming surface, so no test may assert its shape before the owner decides | `audit:ChatLayoutScrollButton/theming`    |
+| hover, pressed | `ChatLayoutScrollButtonSurface.a11y.chromium.spec.ts` interaction pass — each frame asserts the pseudo-class matched and that the captured bytes differ from a rest frame of the same page                                                                                                          | collapsed and labelled, light and dark | a frame captured after release, or with the pointer elsewhere, fails its own engagement assertion          | `audit:ChatLayoutScrollButton/design`     |
+| FR8            | `ChatLayoutScrollButtonSurface.a11y.chromium.spec.ts` measured target box                                                                                                                                                                                                                           | visible, collapsed                     | a smaller resolved size drops the control below the AA minimum                                             | `audit:ChatLayoutScrollButton/a11y`       |
+| FR9            | `ChatLayoutScrollButton.test.tsx` passthrough case                                                                                                                                                                                                                                                  | any                                    | dropping `...rest` silently discards `data-*`, `id`, and ARIA the caller set                               | `audit:ChatLayoutScrollButton/public-api` |
+
+Read from source, with no focused test yet:
+
+- FR1a: `label=''` producing an empty accessible name.
+- FR6a: the target reflecting no state.
+- FR7: the transition collapsing to `0s` under reduced motion.
 
 ## Decision log
 
@@ -267,28 +264,15 @@ scroll affordance today, so these rows record the gap rather than a requirement.
 **Reference:** `component:ChatLayoutScrollButton/DEC-1`
 **Decider:** `cixzhang`, `2026-09-23`
 
-`architecture:component-theming-surface/INV4` requires a target to sit on a
-stable visible element that paints theme-controlled output. The component
-renders two elements: a full-width row that centres the pill and holds the gap
-below it, and the pill itself, which paints the fill, elevation, and radius. The
-target sat on the row, so a theme that styled the documented name painted a band
-across the chat dock while the pill kept the surface the theme asked to replace.
-
-The name, the documentation entry, and the target count are unchanged, and no
-`guaranteedProperties` declaration existed to promise the old element, so this
-repairs a reachability gap rather than removing a compatibility path.
-
-Rejected: adding a second target for the pill. That is new public theming
-surface for a component that needs exactly one, and it would leave the
-non-painting target in place.
-
-Rejected: moving consumer passthrough to the pill alongside the target.
-`ref`, `xstyle`, `className`, `style`, and the remaining DOM props keep
-landing on the outer element, which is the element the released type, the
-existing passthrough test, and `architecture:public-component-api/INV5, INV8`
-name as the contract's owner. Relocating them would change where a caller's
-`id`, `data-*`, and ref resolve, which is a compatibility decision and not part
-of this repair.
+The component renders two elements: a full-width row that centres the pill and
+holds the gap below it, and the pill, which paints the fill, elevation, and
+radius. The public target sits on the pill, the element a theme restyles, as
+`architecture:component-theming-surface/INV4` requires. Consumer `ref`, styles,
+and DOM props stay on the outer row (FR9).
+
+Rejected: a second target for the pill — new theming surface for one painted part.
+
+Rejected: moving consumer passthrough to the pill — it changes where a caller's `id` and ref resolve.
 
 ## Open questions
 
@@ -327,10 +311,10 @@ of this repair.
   ring on the pill, or clip on a different element — each change rendered
   geometry and belong to a visual review.
 - **OQ7 — What should `label=''` do?** (`human-api`)
-  It currently produces an unnamed control (FR1a). The candidate answers — fall
+  It produces an unnamed control (FR1a). The candidate answers — fall
   back to the translated default, reject the value in the type, or treat it as
   a caller error — are a public API and compatibility decision on a released
-  prop, so the audit recorded the violation instead of choosing one.
+  prop, so this record states the gap without choosing one.
 
 ## Content boundary
 

package/src/Chat/ChatMessage.spec.md

@@ -1,18 +1,19 @@
 ---
 schema_version: 3
-template_version: 6
+template_version: 7
 kind: component
 id: component:ChatMessage
-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: [public-api, behavior, layout, theming, accessibility, testing]
 verified_by:
   [
     packages/core/src/Chat/ChatMessage.test.tsx,
+    packages/core/src/Chat/ChatMessageBubble.test.tsx,
     packages/core/src/theme/themingTargets.test.ts,
     apps/storybook/stories/ChatMessage.stories.tsx,
   ]
@@ -35,26 +36,17 @@ system_specs: [spec:AST-020, spec:AST-029]
 
 # ChatMessage component contract
 
-This record is an **observational backfill** written during the 2026-09-24
-component audit under `spec:AST-029/FR3–FR4`. Rows marked `verify` describe the
-audit base's released contract. Rows marked `proposed` describe the empty-slot
-behavior (FR3, FR6, ORD2, AR1–AR2, DEC-1) and await owner approval: `null`,
-booleans, and empty strings create no slot; any other slot content that renders
-nothing collapses its wrapper through CSS; and a name that renders no text falls
-back to the translated sender label. Slot content is never inspected to decide
-any of this. Unresolved questions remain open rather than becoming policy.
-
 ## Contract at a glance
 
-| Area                    | Contract                                                                                                                                                                         |
-| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | `sender`, `children`, `avatar`, `name`, `metadata`, `density`, plus `BaseProps<HTMLElement>` and `ref` on the message article.                                                   |
-| Behavior                | Sender controls logical alignment and system-message suppression; density resolves explicit prop → message-list context → `balanced`; descendants receive the resolved context.  |
-| End-user impact         | People reading a conversation can distinguish user, assistant, and system messages while names and translated fallback labels preserve each article's sender identity.           |
-| Builder impact          | No new caller choice. Slot content that renders nothing leaves no empty space and no unnamed article.                                                                            |
-| Compatibility/readiness | Draft. No public API, default, or theming target changes; the empty-slot rows are a patch fix. Authority remains `draft` until exact-head owner approval.                        |
-| Review checks           | Reject a row that states unshipped behavior, changes sender or density meaning, treats caller content as component-owned, or turns the unresolved theming question into new API. |
-| Governing rules         | `architecture:public-component-api/INV1, INV3, INV5–INV6, INV8–INV9`; `architecture:component-theming-surface/INV3–INV6`; `spec:AST-029/FR3–FR6`.                                |
+| Area                    | Contract                                                                                                                                                                        |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `sender`, `children`, `avatar`, `name`, `metadata`, `density`, plus `BaseProps<HTMLElement>` and `ref` on the message article.                                                  |
+| Behavior                | Sender controls logical alignment and system-message suppression; density resolves explicit prop → message-list context → `balanced`; descendants receive the resolved context. |
+| End-user impact         | People reading a conversation can distinguish user, assistant, and system messages while names and translated fallback labels preserve each article's sender identity.          |
+| Builder impact          | None.                                                                                                                                                                           |
+| Compatibility/readiness | Records shipped behavior; no public change. No implementation gap; one owner question stays open.                                                                               |
+| Review checks           | Reject a change that alters sender or density meaning, treats caller content as component-owned, or turns the unresolved theming question into new API.                         |
+| Governing rules         | `architecture:public-component-api/INV1, INV3, INV5–INV6, INV8–INV9`; `architecture:component-theming-surface/INV3–INV6`; `spec:AST-029/FR3–FR6`.                               |
 
 This table is a review projection; the body below is authoritative.
 
@@ -70,11 +62,8 @@ document.
 
 ## Compatibility and migration
 
-- Released default preserved: yes — the published `./Chat` subpath exports
-  `ChatMessage`, `ChatMessageProps`, `ChatMessageSender`, and `ChatDensity`.
-- Compatibility class: patch fix. Slot content that renders nothing creates no
-  visible slot, and a name that renders no text leaves the translated fallback
-  label; a name that renders text labels the article.
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public change
 - Controlled/uncontrolled behavior: not applicable; the component owns no
   controllable value.
 - Migration decision: none.
@@ -122,18 +111,15 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Behavioral and layout contract
 
-Draft requirements identify their basis so observed code is not mistaken for an
-intentional decision.
-
-| ID  | Candidate invariant                                                                                                                                                                                                                                                                                         | Basis                                                                  | Draft review state |
-| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------ |
-| FR1 | `assistant` MUST align to inline start, `user` to inline end, and `system` to the centre; the root MUST reflect the sender on the `chat-message` target.                                                                                                                                                    | shipped implementation; consumer docs; focused tests                   | verify             |
-| FR2 | `system` MUST suppress the supplied avatar, name, and metadata while continuing to render `children`.                                                                                                                                                                                                       | shipped implementation; Chat family anatomy; focused tests             | verify             |
-| FR3 | A non-system message MUST render supplied avatar, name, children, and metadata in that visual order. `null`, boolean, and empty-string auxiliary values MUST NOT create wrappers; a wrapper whose content renders nothing MUST collapse (DEC-1).                                                            | owner direction; focused tests                                         | proposed           |
-| FR4 | Density MUST resolve explicit `density` → nearest `ChatMessageList` density → `balanced`, and the resolved value MUST reflect on the root target.                                                                                                                                                           | shipped implementation; consumer docs; focused tests; theming metadata | verify             |
-| FR5 | Descendants MUST receive the resolved `{sender, density}` value through `ChatMessageContext`.                                                                                                                                                                                                               | shipped implementation; descendant composition                         | verify             |
-| FR6 | The article MUST carry the translated sender fallback as `aria-label`, and a non-system `name` that is not a skipped scalar MUST also label it through `aria-labelledby`. A name that renders text names the article; one that renders none leaves the fallback (accessible name computation 1.2, step 2B). | owner direction; accessible name computation 1.2; focused tests        | proposed           |
-| FR7 | Accepted `ref`, DOM/data/ARIA props, `className`, `style`, and `xstyle` MUST reach and compose on the same article that carries the `chat-message` target.                                                                                                                                                  | `architecture:public-component-api/INV5–INV6, INV8`; focused tests     | settled            |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                   | Basis                                                                  |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| FR1 | `assistant` MUST align to inline start, `user` to inline end, and `system` to the centre; the root MUST reflect the sender on the `chat-message` target.                                                                                                                                                    | shipped implementation; consumer docs; focused tests                   |
+| FR2 | `system` MUST suppress the supplied avatar, name, and metadata while continuing to render `children`.                                                                                                                                                                                                       | shipped implementation; Chat family anatomy; focused tests             |
+| FR3 | A non-system message MUST render supplied avatar, name, children, and metadata in that visual order. `null`, boolean, and empty-string auxiliary values MUST NOT create wrappers; a wrapper whose content renders nothing MUST collapse (DEC-1).                                                            | owner direction; focused tests                                         |
+| FR4 | Density MUST resolve explicit `density` → nearest `ChatMessageList` density → `balanced`, and the resolved value MUST reflect on the root target.                                                                                                                                                           | shipped implementation; consumer docs; focused tests; theming metadata |
+| FR5 | Descendants MUST receive the resolved `{sender, density}` value through `ChatMessageContext`.                                                                                                                                                                                                               | shipped implementation; descendant composition                         |
+| FR6 | The article MUST carry the translated sender fallback as `aria-label`, and a non-system `name` that is not a skipped scalar MUST also label it through `aria-labelledby`. A name that renders text names the article; one that renders none leaves the fallback (accessible name computation 1.2, step 2B). | owner direction; accessible name computation 1.2; focused tests        |
+| FR7 | Accepted `ref`, DOM/data/ARIA props, `className`, `style`, and `xstyle` MUST reach and compose on the same article that carries the `chat-message` target, except `aria-label` and `aria-labelledby`, which the component owns for naming (FR6, AR1).                                                       | `architecture:public-component-api/INV5–INV6, INV8`; focused tests     |
 
 ### Allowed variation
 
@@ -169,7 +155,8 @@ intentional decision.
 - **ORD2 — Accessible name.** A system `name` or a skipped scalar creates no
   name wrapper. Otherwise the article references the name wrapper's generated
   id; the rendered text there names the article, and empty text yields to the
-  translated fallback carried as `aria-label`.
+  translated fallback carried as `aria-label`. A caller `aria-label` or
+  `aria-labelledby` does not override this naming.
 
 ### Performance and resources
 
@@ -193,17 +180,17 @@ intentional decision.
 
 ## Design relationships
 
-| Anatomy or state | Design requirement                                      | Representation authority | Hierarchy role | Component contract |
-| ---------------- | ------------------------------------------------------- | ------------------------ | -------------- | ------------------ |
-| Assistant        | Align the message column to logical start               | observed                 | content        | FR1                |
-| User             | Align the message column to logical end                 | observed                 | content        | FR1                |
-| System           | Centre the content column and suppress identity slots   | observed                 | supporting     | FR1–FR2            |
-| Name             | Use supporting type and secondary text colour tokens    | observed                 | supporting     | FR3                |
-| Density          | Increase root and child gaps across the three-step axis | observed                 | structure      | FR4                |
+| Anatomy or state | Design requirement                                                                                                               | Representation authority | Hierarchy role | Component contract |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Assistant        | Align the message column to logical start                                                                                        | Current source           | content        | FR1                |
+| User             | Align the message column to logical end                                                                                          | Current source           | content        | FR1                |
+| System           | Centre the content column and suppress identity slots                                                                            | Current source           | supporting     | FR1–FR2            |
+| Name             | `none` — unsettled: the built-in name paints explicit supporting type and secondary colour on an untargeted descendant; see OQ1. | Current source           | supporting     | FR3                |
+| Density          | Increase root and child gaps across the three-step axis                                                                          | Current source           | structure      | FR4                |
 
-No component-local design decision is settled by this draft.
+No component-local design decision is recorded.
 
-### Theming reachability (observed)
+### Theming reachability
 
 | Anatomy part | Disposition                                                                                                                                                 |
 | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -223,26 +210,38 @@ No component-local design decision is settled by this draft.
   and owns bubble presentation.
 - There is no current direct owner for ChatMessage's
   `compact | balanced | spacious` density vocabulary or ordering. FR4–FR5 record
-  the shipped axis and precedence observationally; routed global layout claims do
-  not settle that component-specific vocabulary.
-- `spec:AST-029` permits this observational draft and keeps the closed audit
-  inventory outside the component contract.
+  the shipped axis and precedence; routed global layout claims do not settle
+  that component-specific vocabulary.
+- `spec:AST-029` owns the audit evidence inventory this record's verification
+  map follows.
 
 ## Verification map
 
-| Contract     | Verification                                                    | Representative states                                                                      | Mutation or failure expectation                                                     | Audit section          |
-| ------------ | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | ---------------------- |
-| FR1–FR3      | `ChatMessage.test.tsx`; `ChatMessage.stories.tsx`               | all senders; skipped scalar, renders-nothing, numeric, content, and suppressed slot states | Removing the scalar skip or the CSS collapse leaves an empty slot or a gap          | `audit:ChatMessage/§4` |
-| FR4–FR5      | `ChatMessage.test.tsx`; `themingTargets.test.ts`                | standalone; inherited density; explicit override                                           | Changing precedence or reflection gives descendants and themes a different density  | `audit:ChatMessage/§2` |
-| FR6, AR1–AR2 | `ChatMessage.test.tsx`; Chromium accessibility tree             | visible, omitted, skipped-scalar, renders-nothing, and system names                        | Dropping the fallback `aria-label` or the name reference leaves an article unnamed  | `audit:ChatMessage/§1` |
-| FR7          | `ChatMessage.test.tsx`; public export and theming-target checks | ref; data prop; class; style                                                               | Moving passthrough or ref off the target article breaks the public root contract    | `audit:ChatMessage/§3` |
-| AR3          | Source review plus component-scoped accessibility audit         | rich and interactive descendants                                                           | The wrapper introduces an interactive role or takes ownership away from descendants | `audit:ChatMessage/§1` |
-| RTL          | `ChatMessage.stories.tsx`; component-scoped RTL audit           | all senders; narrow long content                                                           | Physical direction keeps user or assistant on the same side in both directions      | `audit:ChatMessage/§9` |
+| Contract     | Verification                                                                   | Representative states                                                                      | Mutation or failure expectation                                                    | Audit section          |
+| ------------ | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | ---------------------- |
+| FR1–FR3      | `ChatMessage.test.tsx`; `ChatMessage.stories.tsx`                              | all senders; skipped scalar, renders-nothing, numeric, content, and suppressed slot states | Removing the scalar skip or the CSS collapse leaves an empty slot or a gap         | `audit:ChatMessage/§4` |
+| FR4–FR5      | `ChatMessage.test.tsx`; `ChatMessageBubble.test.tsx`; `themingTargets.test.ts` | standalone; inherited density; explicit override                                           | Changing precedence or reflection gives descendants and themes a different density | `audit:ChatMessage/§2` |
+| FR6, AR1–AR2 | `ChatMessage.test.tsx`                                                         | visible, omitted, skipped-scalar, renders-nothing, and system names                        | Dropping the fallback `aria-label` or the name reference leaves an article unnamed | `audit:ChatMessage/§1` |
+| FR7          | `ChatMessage.test.tsx`; public export and theming-target checks                | ref; data prop; class; style                                                               | Moving passthrough or ref off the target article breaks the public root contract   | `audit:ChatMessage/§3` |
+| RTL          | `ChatMessage.stories.tsx`                                                      | all senders; narrow long content                                                           | Physical direction keeps user or assistant on the same side in both directions     | `audit:ChatMessage/§9` |
+
+Read from source, with no focused test yet:
+
+- FR1: start, end, and centre alignment by sender.
+- FR2: a system message still rendering its children.
+- FR3: the visual slot order.
+- FR7: a caller `aria-label` or `aria-labelledby` not overriding the naming,
+  and `xstyle` composing on the article.
+- ORD1: root and children gaps following the resolved density.
+- FR6: a name that renders no text leaving the fallback name.
+- PR1–PR2: no listener or Effect, and a context value that changes only with
+  sender or density.
+- AR3: no keyboard model of the component's own.
 
 ## Decision log
 
-- **DEC-1 — Slot emptiness follows the rendered DOM.** (`proposed`, awaiting
-  owner approval) ChatMessage skips only `null`, boolean, and empty-string
+- **DEC-1 — Slot emptiness follows the rendered DOM.** (`cixzhang`,
+  2026-10-31) ChatMessage skips only `null`, boolean, and empty-string
   slot values. Any other content is passed to React unchanged; its wrapper
   collapses with `:empty` when it renders nothing, and the article's naming
   falls back to `aria-label` when the referenced name renders no text.
@@ -255,8 +254,8 @@ No component-local design decision is settled by this draft.
   (`human-api`) The released family inventory exposes only the aggregate
   `chat-message` target, while the name's explicit type and colour prevent a root
   override from reaching it by inheritance. Adding or splitting a target changes
-  public theming API, so this draft records the reachability gap without choosing a
-  remedy.
+  public theming API, so this record states the reachability gap without choosing
+  a remedy.
 
 ## Content boundary