@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/Chat/ChatLayout.spec.md

@@ -1,276 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:ChatLayout
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-31
-owners: [cixzhang]
-review_triggers:
-  [public-api, behavior, layout, scrolling, accessibility, theming, testing]
-verified_by:
-  [
-    packages/core/src/Chat/ChatLayout.test.tsx,
-    packages/core/src/Chat/ChatLayoutScrollButton.test.tsx,
-    packages/core/src/Chat/useChatStreamScroll.test.tsx,
-    packages/core/src/Chat/useChatNewMessages.test.tsx,
-    apps/storybook/stories/ChatLayout.stories.tsx,
-  ]
-modules: []
-families: []
-design_specs: []
-architecture:
-  [
-    architecture:public-component-api,
-    architecture:component-style-authoring,
-    architecture:component-theming-surface,
-    architecture:theme-tokens,
-    architecture:react-component-runtime,
-    architecture:component-test-sufficiency,
-    architecture:knowledge-contracts,
-  ]
-contributing: []
-system_specs: [spec:AST-025, spec:AST-029]
----
-
-# ChatLayout component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                  |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | `children`, `composer`, `emptyState`, `scrollButton`, `scrollRef`, `density`, plus `BaseProps<HTMLDivElement>` and `ref` on the layout root.                                              |
-| Behavior                | The root is a flex column; the message area grows and never shrinks; the dock is sticky when the root scrolls and fixed when `scrollRef` names an outer scroller.                         |
-| End-user impact         | A chat transcript scrolls under a composer that stays reachable, auto-follows streaming output, and offers a scroll-to-bottom affordance when the reader has moved away from the bottom.  |
-| Builder impact          | None.                                                                                                                                                                                     |
-| Compatibility/readiness | Records shipped behavior; no public change. Two owner questions stay open.                                                                                                                |
-| Review checks           | Reject any row that states unshipped behavior, promises a default this component does not apply, or resolves OQ1 or OQ2 without an owner decision.                                        |
-| Governing rules         | `architecture:public-component-api/INV1, INV5–INV6, INV8`; `architecture:component-style-authoring/INV1–INV3, INV5`; `architecture:theme-tokens/INV3`; `spec:AST-025/FR12` (not adopted). |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-ChatLayout is the structural shell for a chat surface. It owns one job: place a
-scrolling transcript above a docked composer so that short conversations do not
-overflow, long ones scroll, and the composer stays at the bottom edge of
-whichever element actually scrolls. Scroll mechanics live in
-`useChatStreamScroll` and `useChatNewMessages`; this component wires them to the
-DOM it owns and publishes the resulting refs through `ChatLayoutContext`.
-
-Consumer usage, prop syntax, and examples belong in `ChatLayout.doc.mjs`.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`
-- Compatibility class: records shipped behavior; no public change
-- Controlled/uncontrolled behavior: not applicable; the component holds no
-  controllable value.
-- Migration decision: none.
-
-## Ownership boundary
-
-**Owns**
-
-- The layout root: flex column, relative positioning, `container-type:
-inline-size`, and the `chat-layout` theming target with its `density` axis.
-- Which element scrolls: the root itself, or the element named by `scrollRef`.
-- Dock positioning — `sticky` in self-scroll mode, `fixed` in external-scroll
-  mode — and the frosted glass layer painted behind it.
-- Density geometry: dock padding, message-column max-width and inline padding,
-  and the blur layer's height and mask.
-- Empty-state substitution and its centering box.
-- The default scroll-to-bottom affordance and the visibility signal it receives.
-- Publication of `scrollContainerRef` and `contentRef` through `ChatLayoutContext`.
-
-**Does not own / non-goals**
-
-- Scroll measurement, spring animation, lock behavior, or new-message detection —
-  owned by `useChatStreamScroll` and `useChatNewMessages`.
-- Message presentation, grouping, or sender semantics — owned by
-  `component:ChatMessageList` and `component:ChatMessage`.
-- Composer behavior, sizing, or status — owned by `component:ChatComposer`.
-- The scroll-to-bottom control's own presentation — owned by
-  `component:ChatLayoutScrollButton`.
-- Page shell, navigation, and landmark assignment — the caller's.
-- The shared effective-axis scroll capability defined by `spec:AST-025`. This
-  component predates it and has not adopted it; see OQ1.
-
-## Public concepts
-
-| Concept        | Closed values or states                                  | Meaning                                                                            | Default     | Owner                | Stability | Invalid-value behavior                     |
-| -------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------- | ----------- | -------------------- | --------- | ------------------------------------------ |
-| `children`     | any `ReactNode`                                          | Transcript content placed in the message area.                                     | required    | caller               | stable    | n/a — required                             |
-| `composer`     | any `ReactNode`                                          | Content placed inside the dock.                                                    | required    | caller               | stable    | n/a — required                             |
-| `emptyState`   | `ReactNode`; omitted                                     | Rendered centred in place of `children` when `children` is empty.                  | omitted     | caller               | stable    | omitted renders `children` unchanged       |
-| `scrollButton` | `undefined`; `null`; any `ReactNode`                     | `undefined` selects the wired default, `null` renders nothing, a node replaces it. | `undefined` | component/caller     | stable    | any node renders as given                  |
-| `scrollRef`    | `RefObject<HTMLElement \| null>`; omitted                | Names the scrolling element; omitted makes the root scroll.                        | omitted     | caller               | stable    | a null `current` leaves scrolling inactive |
-| `density`      | `compact`; `balanced`; `spacious`                        | Selects dock padding, message-column width, and blur-layer size.                   | `balanced`  | component            | stable    | closed union; rejected by types            |
-| root surface   | `ref`; DOM/data/ARIA props; `className`/`style`/`xstyle` | Extends the layout root.                                                           | omitted     | public component API | stable    | n/a                                        |
-
-`density` is a closed union. It is a documented `visualProps` axis of the
-`chat-layout` target, and it is not theme-extensible: no unavailable custom value
-has a safe theme-independent baseline, so it stays closed under
-`architecture:component-theming-surface/INV14`.
-
-## Behavioral and layout contract
-
-| ID  | Invariant                                                                                                                                                              | Basis                                               |
-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
-| FR1 | The root MUST be a flex column, so an in-flow sticky dock's height is part of the root's height rather than added on top of it.                                        | Current source and tests                            |
-| FR2 | The message area MUST grow into leftover space and MUST NOT shrink below its content height, so short transcripts fill the root exactly and long ones overflow it.     | Current source and tests                            |
-| FR3 | With no `scrollRef`, the root MUST be the scroll container and the dock MUST be `position: sticky`.                                                                    | Current source and tests                            |
-| FR4 | With a `scrollRef`, the root MUST NOT become a scroll container and the dock MUST be `position: fixed`.                                                                | Current source and tests                            |
-| FR5 | `emptyState` MUST replace `children` exactly when `children` is `null`, `undefined`, `false`, or an empty array, and MUST NOT replace any other children.              | Current source and tests                            |
-| FR6 | `scrollButton` MUST distinguish three cases: omitted selects the wired default, `null` renders nothing, and a supplied node replaces the default.                      | Current source and tests                            |
-| FR7 | `density` MUST reflect on the root as the `chat-layout` target's `data-density`, and MUST select the dock, message-area, dock-inner, and blur-layer geometry together. | Current source, tests, and docs                     |
-| FR8 | The layout MUST publish its scroll container and message content refs through `ChatLayoutContext` so the message list can register the observed content box.           | Current source                                      |
-| FR9 | Accepted `ref`, DOM/data/ARIA props, `className`, `style`, and `xstyle` MUST reach and compose on the layout root.                                                     | `architecture:public-component-api/INV5–INV6, INV8` |
-
-### Allowed variation
-
-- **AV1 — Scroll ownership.** The caller chooses between root-owned and
-  externally-owned scrolling; the dock's positioning strategy follows that choice.
-- **AV2 — Scroll affordance.** The caller may keep the wired default, remove it,
-  or substitute any node.
-- **AV3 — Transcript content.** Any content is allowed in the message area;
-  ChatMessageList is a convention, not a requirement.
-- **AV4 — Density geometry.** Resolved spacing and widths follow the active
-  theme's spacing scale; only the relationships between the three steps are fixed.
-
-### Representative states
-
-| State                               | Required invariant                                              | Allowed variation                             |
-| ----------------------------------- | --------------------------------------------------------------- | --------------------------------------------- |
-| Self-scroll, short transcript       | Root fills without overflowing; dock sticky at the block end    | Empty state may occupy the message area       |
-| Self-scroll, overflowing transcript | Root scrolls; message area keeps content height                 | Scroll affordance becomes visible             |
-| External `scrollRef`                | Root does not scroll; dock is fixed to the viewport's block end | The named element may be the document element |
-| Empty children with `emptyState`    | Centred empty state replaces the transcript                     | Any node may be the empty state               |
-| `scrollButton={null}`               | No scroll affordance renders                                    | Auto-scroll behavior is unchanged             |
-
-### Performance and resources
-
-- **PR1 — No layout measurement in the component.** Density is a prop. ChatLayout
-  MUST NOT add a `ResizeObserver`, media query, or animation frame of its own for
-  presentation the CSS container/flex model already resolves
-  (`architecture:component-style-authoring/INV2`).
-- **PR2 — Shared observation only.** Content-size observation reaches the browser
-  through the pooled `observeResize` utility used by `useChatNewMessages`, never a
-  per-instance observer.
-
-## Accessibility contract
-
-- **AR1 — The wired default scroll affordance MUST NOT be focusable while it is
-  visually hidden.** The hidden pill paints nothing, so focus landing on it would
-  have no visible indicator (WCAG 2.2 SC 2.4.7, Level AA). `opacity` and
-  `pointer-events` do not remove an element from sequential focus navigation.
-- **AR2 — The scroll affordance MUST remain keyboard reachable and operable while
-  visible**, with its accessible name supplied by the catalog and replaced by the
-  new-messages label when new messages have arrived.
-- **AR3 — All user-visible and AT-facing strings MUST come from the catalog**:
-  `@astryx.chatLayout.newMessages` and
-  `@astryx.chatLayoutScrollButton.scrollToBottom`.
-- **AR4 — The layout MUST NOT assign a landmark role or accessible name to the
-  caller's regions.** Region semantics stay caller-owned.
-- The self-scroll root carries no `tabIndex`, role, or accessible name of its
-  own; the keyboard path into scrolled content comes from whatever `children`
-  supplies. Which layer should own that guarantee is unresolved; see OQ1.
-
-## Design relationships
-
-- The dock paints a `backdrop-filter` blur with a block-start mask so the
-  transcript fades out behind the composer rather than ending at a hard edge.
-  Blur height and mask distance step with `density`.
-- The scroll affordance is a pill whose height tracks `--size-element-md`, the
-  same token that sizes the `md` Button it wraps, so the pill's `overflow: hidden`
-  cannot clip that Button under a theme that retunes the element scale
-  (`architecture:theme-tokens/INV3`).
-- Spacing, radius, shadow, duration, and easing all resolve from portable
-  semantic tokens. Component-local geometry that has no semantic role — the
-  message-column and dock-inner caps, the blur heights, and the empty-state
-  minimum height — remains a named component design decision.
-- The component declares no portable token and no public custom property.
-
-### Theming reachability
-
-Dispositions for ChatLayout's five anatomy parts. This record carries no
-`anatomy-theming:v1` block; the block is optional during migration, and see OQ2.
-
-| Anatomy part            | Disposition                                                                                                                                                                                   |
-| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Message area            | `none` — reachability-gap: an internal element with no `themeProps` call. `chat-layout` sits on the scrolling root, so a theme cannot reach the transcript column's own padding or width cap. |
-| Frosted glass dock      | `none` — unsettled: the dock, its inner column, and the blur layer paint the signature surface and carry no target; see OQ2.                                                                  |
-| Scroll-to-bottom button | `delegatesTo` the `chat-layout-scroll-button` target, whose canonical owner in the current inventory is `component:Chat`.                                                                     |
-| Composer                | `delegatesTo` the `chat-composer` target, whose canonical owner in the current inventory is `component:Chat`.                                                                                 |
-| Empty state             | `none` — intentional: the empty-state box only centres caller content, which is layout plumbing.                                                                                              |
-
-The `chat-layout` target itself is declared on the Chat family document
-(`Chat.doc.mjs`) rather than on `ChatLayout.doc.mjs`.
-
-## Family and system relationships
-
-- There is no `family:chat` record. The Chat components share the `Chat.doc.mjs`
-  family document and its theming target inventory, which is not a knowledge-record
-  family contract.
-- `component:ChatLayoutScrollButton` owns the scroll affordance's presentation,
-  label, and focus behavior. ChatLayout owns only when it is visible.
-- `component:ChatMessageList` consumes `ChatLayoutContext.contentRef`.
-- `spec:AST-025` owns the shared effective-axis scroll capability. ChatLayout
-  does not adopt it today: it declares `overflow-y: auto` unconditionally in
-  self-scroll mode rather than resolving an effective axis, and it assigns no
-  keyboard access to the viewport itself. FR12 accepts an existing focusable
-  descendant as the keyboard path; see OQ1 for the open ownership question.
-
-## Verification map
-
-| Contract | Verification                                                                                                                                 | Representative states                               | Mutation or failure expectation                                                                   | Audit section         |
-| -------- | -------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------- | --------------------- |
-| FR1, FR2 | `ChatLayout.test.tsx` self-scroll layout contract                                                                                            | self-scroll, short and long transcript              | Restoring `min-height: 100%` on the message area re-adds the dock's height and the root overflows | `audit:ChatLayout/§4` |
-| FR3, FR4 | `ChatLayout.test.tsx` dock positioning                                                                                                       | no `scrollRef`; external `scrollRef`                | Swapping sticky and fixed detaches the dock from the element that actually scrolls                | `audit:ChatLayout/§4` |
-| FR5      | `ChatLayout.test.tsx` empty-state cases; `useChatNewMessages.test.tsx` conditional list case                                                 | empty array; populated children                     | Treating populated children as empty hides the transcript                                         | `audit:ChatLayout/§4` |
-| FR6      | `ChatLayout.test.tsx` scroll-button cases                                                                                                    | custom node                                         | Rendering the default in place of a supplied node fails                                           | `audit:ChatLayout/§4` |
-| FR7      | `ChatLayout.test.tsx` density cases; `themingTargets.test.ts`                                                                                | compact; balanced; spacious                         | Dropping the reflected attribute makes the theming axis unselectable                              | `audit:ChatLayout/§2` |
-| FR8      | `ChatLayout.test.tsx` "first-fill scroll positioning" cases; `useChatNewMessages.test.tsx` conditional-list case                             | first fill; streaming growth                        | Losing the published refs stops auto-scroll from observing content growth                         | `audit:ChatLayout/§7` |
-| AR1, AR2 | `ChatLayoutScrollButton.test.tsx` and `ChatLayout.test.tsx` tab-order cases; `ChatLayoutScrollButton.a11y.chromium.spec.ts` in real Chromium | hidden at rest; visible; re-hidden after activation | Reverting to `opacity`-only hiding puts an invisible control back in the tab order                | `audit:ChatLayout/§1` |
-
-Read from source, with no focused test yet:
-
-- FR3, FR4: whether the root is the scroll container.
-- FR5: `null` and `undefined` children selecting the empty state.
-- FR6: `null` rendering nothing, an omitted `scrollButton` selecting the wired
-  default, and the default not rendering beside a supplied node.
-- FR8: the published scroll container.
-- FR7: the dock, message-area, dock-inner, and blur geometry for each density.
-- FR9: `ref`, DOM props, `className`, `style`, and `xstyle` on the root.
-- AR2: the new-messages label replacing the catalog name.
-- AR3: the catalog strings; AR4: no landmark or name on caller regions.
-- PR1–PR2: no layout measurement of the component's own, and the pooled
-  observer.
-
-## Decision log
-
-No component-local decision is recorded.
-
-## Open questions
-
-- **OQ1 — Which layer owns the keyboard path to scrolled content, and should
-  ChatLayout guarantee it?** (`human-api`) In self-scroll mode the root is the
-  scroll container and carries no `tabIndex`, role, or accessible name of its
-  own. `component:ChatMessageList`, the documented child, carries `role="log"`
-  and `tabIndex={0}`, and `spec:AST-025/FR12` accepts such an existing
-  focusable descendant instead of a named viewport. `children` is typed
-  `ReactNode`, so whether a composition supplying no focusable descendant is
-  also covered is unresolved, as is which layer should own the guarantee. This
-  record states the arrangement and asserts no defect.
-- **OQ2 — Should the frosted dock be themeable?** (`human-api`) The dock, its
-  inner column, and the blur layer paint the component's signature surface, and
-  no current target reaches them.
-
-## Content boundary
-
-This file does not duplicate `ChatLayout.doc.mjs` prop tables or examples, the
-audit's scores and evidence, or the scroll, message, and composer contracts owned
-by their own components and hooks.

package/src/Chat/ChatLayoutScrollButton.spec.md

@@ -1,322 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:ChatLayoutScrollButton
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-31
-owners: [cixzhang]
-review_triggers: [public-api, behavior, accessibility, theming, testing]
-verified_by:
-  [
-    packages/core/src/Chat/ChatLayoutScrollButton.test.tsx,
-    packages/core/src/Chat/__tests__/ChatLayoutScrollButton.a11y.chromium.spec.ts,
-    packages/core/src/Chat/__tests__/ChatLayoutScrollButtonSurface.a11y.chromium.spec.ts,
-    apps/storybook/stories/ChatLayout.stories.tsx,
-    apps/storybook/rtl-audit/verified-not-applicable.json,
-  ]
-modules: []
-families: []
-design_specs: []
-architecture:
-  [
-    architecture:public-component-api,
-    architecture:component-style-authoring,
-    architecture:component-theming-surface,
-    architecture:theme-tokens,
-    architecture:component-test-sufficiency,
-    architecture:knowledge-contracts,
-  ]
-contributing: []
-system_specs: [spec:AST-029]
----
-
-# ChatLayoutScrollButton component contract
-
-## Contract at a glance
-
-| 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.
-
-## Intent
-
-ChatLayoutScrollButton is the floating return-to-newest affordance for a chat
-transcript. It owns the pill's appearance and its visible/hidden presentation;
-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.
-
-## Compatibility and migration
-
-- 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**
-
-- The pill surface: its fill, elevation, radius, resolved height, and the
-  collapsed/expanded width ceiling.
-- The visible/hidden presentation, including removal from sequential focus
-  navigation while hidden.
-- The default accessible name when the caller supplies no `label`.
-- Centring within its parent, and the gap between the pill and what sits below.
-
-**Does not own / non-goals**
-
-- Scroll position, lock state, and new-message detection — owned by
-  `useChatStreamScroll` and `useChatNewMessages`.
-- Placement in the chat dock and whether the affordance renders at all — owned
-  by `component:ChatLayout` through its `scrollButton` slot.
-- Action semantics, focus ring, press feedback, size geometry, and variant
-  surface — owned by `component:Button`, which this component composes.
-
-## Public concepts
-
-| Concept             | Closed values or states     | Meaning                                                              | Availability by variant/orientation/state | Default             | Owner                               | Stability | Invalid-value behavior                            |
-| ------------------- | --------------------------- | -------------------------------------------------------------------- | ----------------------------------------- | ------------------- | ----------------------------------- | --------- | ------------------------------------------------- |
-| `isVisible`         | `true`, `false`             | Whether the affordance is presented and operable                     | always                                    | required            | `component:ChatLayoutScrollButton`  | stable    | required boolean; no fallback                     |
-| `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; 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
-
-| 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
-string. It reaches the Button as `label=''`, `aria-label=''`, and
-`isIconOnly={true}`, because `??` passes an empty string through. Button sets
-its own `aria-label` only when `label !== ''`, so the caller's empty
-`aria-label` survives; icon-only renders no visible text; and the chevron Icon
-carries no `label`, so it is `aria-hidden="true"`. The result is a focusable,
-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. 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. Recorded as OQ8.
-
-**FR6a — the unreflected state axes.** `isVisible` selects visible/hidden
-styles and `label` selects collapsed/expanded styles, both on the painting
-target, and `themeProps('chat-layout-scroll-button')` is called with no state
-argument. A theme can therefore restyle the pill but cannot address either
-state. Naming those axes is new public theming surface, so the shape belongs to
-the owner. See OQ1.
-
-### Allowed variation
-
-- **AV1 — Expanded width.** The labelled pill's width ceiling is a component
-  design decision, not a theme value. What happens to a label past that ceiling
-  is not settled here; see OQ3.
-- **AV2 — Resolved geometry.** Height, radius, spacing, and duration resolve
-  from theme tokens, so absolute values differ by theme without becoming
-  regressions.
-- **AV3 — Composition.** ChatLayout renders this by default, but a caller may
-  substitute any node or remove the affordance entirely.
-
-### Representative states
-
-| 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, 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    |
-| visible, keyboard-focused | **fails FR3a** — focus is held and `:focus-visible` matches, but the ring is clipped away and paints nothing | none; this is a recorded defect   |
-| visible, pressed          | the press paints a state distinct from hover and rest                                                        | the pressed treatment             |
-| any visible state, themed | the documented target repaints the pill (FR6); its state axes are unreachable (FR6a)                         | which properties a theme declares |
-
-### Performance and resources
-
-- **PR1 — No state, no effects, no observers.** The component derives every
-  rendered difference from its props during render and registers no listener,
-  timer, observer, or animation frame.
-
-## Accessibility contract
-
-- **AR1 — Named.** The control MUST expose a non-empty accessible name in every
-  reachable state (WCAG 2.2 SC 4.1.2) (FR1). Omitted and non-empty `label`
-  satisfy this; `label=''` does not, and that gap is recorded as FR1a rather
-  than resolved here.
-- **AR2 — Focus follows paint.** A control that paints nothing MUST NOT be
-  focusable, because focus landing on it would have no visible indicator
-  (WCAG 2.2 SC 2.4.7). `opacity` and `pointer-events` do not achieve this;
-  `visibility` does (FR2).
-- **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 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
-  the translator catalog, never a literal.
-
-## Design relationships
-
-| Anatomy or state | Design requirement                          | Representation authority | Hierarchy role | Component contract |
-| ---------------- | ------------------------------------------- | ------------------------ | -------------- | ------------------ |
-| pill surface     | floating affordance over the transcript     | unsettled                | supporting     | FR5, FR6           |
-| hidden state     | absent rather than dimmed                   | unsettled                | supporting     | FR2, AR2           |
-| labelled state   | text accompanies the glyph on the same pill | unsettled                | supporting     | FR4                |
-
-The component implements design requirements without copying their rationale.
-An `unsettled` representation remains a human decision; principles do not let an
-agent invent the answer. No `authority: current` design record covers a floating
-scroll affordance today, so these rows record the gap rather than a requirement.
-
-## Family and system relationships
-
-- `family:buttons` owns the action surface this component composes through
-  `component:Button`. This component is not a member: its public purpose is a
-  transcript affordance that contains a button, and the family's membership rule
-  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 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 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
-
-### DEC-1 — The public theming target rides the pill, not the row that centres it
-
-**Reference:** `component:ChatLayoutScrollButton/DEC-1`
-**Decider:** `cixzhang`, `2026-09-23`
-
-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
-
-- **OQ1 — Should the target reflect its style-driving states?** (`human-api`)
-  The pill selects between visible/hidden and collapsed/expanded style objects,
-  and `themeProps` reflects neither, so a theme cannot address either state.
-  Exposing them means adding `visualProps`/`states` to a public target, which is
-  new theming surface rather than a repair.
-- **OQ2 — Is `isVisible` the right name on a non-layer component?** (`human-api`)
-  The shared convention reserves `isOpen`/`isVisible` for layer components. The
-  prop is released in `@astryxdesign/core@0.6.3`, so any change is breaking and
-  needs a compatibility decision.
-- **OQ3 — What should happen to a label past the expanded ceiling?** (`human-design`)
-  The pill clips at its width ceiling with no ellipsis and no wrap. The
-  accessible name survives, so only sighted readers lose text, and locale
-  expansion is the realistic trigger. No `authority: current` design record
-  covers truncation for this surface.
-- **OQ4 — Does this component belong to `family:buttons`?** (`human-api`)
-  Its public purpose is a transcript affordance, and it is absent from the
-  family's member list, but it is a single composed Button with no other
-  content. The family contract's exclusion for "components that merely use a
-  Button as a trigger or action slot" is the reading applied above.
-- **OQ5 — Is animating the pill's `max-width` acceptable?** (`human-design`)
-  Expanding and collapsing animates a layout property. Reduced motion is
-  honored and the subtree is one button, but the record that would govern
-  animated properties, `design:motion`, is `authority: draft`.
-- **OQ6 — The consumer doc has no anatomy inventory.** (`human-api`)
-  `architecture:component-theming-surface` records this as open migration work
-  across Core, so no `### Theming anatomy` block is written here: there are no
-  published anatomy names for it to map.
-
-- **OQ8 — How should the focus ring escape the pill's clip?** (`human-design`)
-  The pill needs `overflow: hidden` for its collapse/expand animation, and the
-  Button's ring is drawn outside its border box, so the two are in direct
-  conflict. Candidate answers — inset the button so the ring fits, draw the
-  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 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 this record states the gap without choosing one.
-
-## 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.