@astryxdesign/core 0.6.2 → 0.6.3-canary.0788c49

package/src/Chat/ChatDictationButton.test.tsx

@@ -1,43 +1,108 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-import {describe, it, expect} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {createRef} from 'react';
+import {describe, it, expect, vi} from 'vitest';
+import {fireEvent, render, screen} from '@testing-library/react';
+import {colorVars} from '../theme/tokens.stylex';
 import {ChatDictationButton} from './ChatDictationButton';
+import type {ChatDictationButtonProps} from './ChatDictationButton';
 import type {UseSpeechRecognitionReturn} from './useSpeechRecognition';
 
-const dictation: UseSpeechRecognitionReturn = {
-  isSupported: true,
-  isListening: false,
-  isSpeaking: false,
-  volume: 0,
-  bands: [0, 0, 0, 0, 0],
-  rawBands: [0, 0, 0, 0, 0],
-  interimTranscript: '',
-  start: () => {},
-  stop: () => {},
-  abort: () => {},
-  toggle: () => {},
-};
+function makeDictation(
+  overrides: Partial<UseSpeechRecognitionReturn> = {},
+): UseSpeechRecognitionReturn {
+  return {
+    isSupported: true,
+    isListening: false,
+    isSpeaking: false,
+    volume: 0,
+    bands: [0, 0, 0, 0, 0],
+    rawBands: [0, 0, 0, 0, 0],
+    interimTranscript: '',
+    start: vi.fn(),
+    stop: vi.fn(),
+    abort: vi.fn(),
+    toggle: vi.fn(),
+    ...overrides,
+  };
+}
 
 describe('ChatDictationButton', () => {
-  it('renders a dictation button', () => {
-    render(
-      <ChatDictationButton dictation={dictation} data-testid="dictation" />,
+  it('labels and toggles the idle button', () => {
+    const dictation = makeDictation();
+    render(<ChatDictationButton dictation={dictation} />);
+
+    fireEvent.click(screen.getByRole('button', {name: 'Start dictation'}));
+    expect(dictation.toggle).toHaveBeenCalledTimes(1);
+  });
+
+  it('shows five hidden visualizer bars and the stop label while listening', () => {
+    const dictation = makeDictation({
+      isListening: true,
+      bands: [0.02, 0.04, 0.08, 0.12, 0.18],
+    });
+    const {container} = render(<ChatDictationButton dictation={dictation} />);
+
+    expect(screen.getByRole('button', {name: 'Stop dictation'})).toBeEnabled();
+    const visualizer = container.querySelector('[aria-hidden="true"]');
+    expect(visualizer).not.toBeNull();
+    expect(visualizer?.children).toHaveLength(5);
+  });
+
+  it('uses theme-owned colors for clipping feedback', () => {
+    const dictation = makeDictation({
+      isListening: true,
+      volume: 0.3,
+      bands: [0.2, 0.2, 0.2, 0.2, 0.2],
+    });
+    const {container} = render(<ChatDictationButton dictation={dictation} />);
+
+    const barStyle = container
+      .querySelector('[aria-hidden="true"] > span')
+      ?.getAttribute('style');
+    expect(barStyle).toContain('color-mix(in srgb');
+    expect(barStyle).toContain(colorVars['--color-accent']);
+    expect(barStyle).toContain(colorVars['--color-error']);
+    expect(barStyle).not.toContain('hsl(');
+  });
+
+  it('hides unsupported dictation by default', () => {
+    const {container} = render(
+      <ChatDictationButton dictation={makeDictation({isSupported: false})} />,
     );
-    expect(screen.getByTestId('dictation')).toBeTruthy();
+
+    expect(container).toBeEmptyDOMElement();
   });
 
-  it('forwards rest props (data-*, aria-*, id) to the root element', () => {
+  it('disables an unsupported button when explicitly kept visible', () => {
     render(
       <ChatDictationButton
-        dictation={dictation}
-        data-testid="dictation"
-        data-custom="x"
-        id="dictate-1"
+        dictation={makeDictation({isSupported: false})}
+        isHiddenWhenUnsupported={false}
       />,
     );
-    const root = screen.getByTestId('dictation');
-    expect(root).toHaveAttribute('data-custom', 'x');
-    expect(root).toHaveAttribute('id', 'dictate-1');
+
+    expect(
+      screen.getByRole('button', {name: 'Start dictation'}),
+    ).toBeDisabled();
+  });
+
+  it('forwards the root ref and accepted span props', () => {
+    const ref = createRef<HTMLSpanElement>();
+    const props = {
+      dictation: makeDictation(),
+      'data-testid': 'dictation',
+      'data-custom': 'x',
+      id: 'dictate-1',
+      label: 'Use voice input',
+      ref,
+    } satisfies ChatDictationButtonProps;
+
+    render(<ChatDictationButton {...props} />);
+
+    expect(ref.current).toBe(screen.getByTestId('dictation'));
+    expect(ref.current).toHaveAttribute('data-custom', 'x');
+    expect(ref.current).toHaveAttribute('id', 'dictate-1');
+    expect(screen.getByRole('button', {name: 'Use voice input'})).toBeEnabled();
   });
 });

package/src/Chat/ChatDictationButton.tsx

@@ -11,7 +11,8 @@
  * A toggle button that connects to useChatDictation. Shows a microphone
  * icon when idle. When listening, replaces the icon with volume-reactive
  * frequency bars (equalizer style) that respond to real mic input.
- * Bars use the accent color and hue-shift when volume clips past 10%.
+ * Bars use the accent color and blend toward the semantic error color when
+ * volume clips past 20%.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Chat/index.ts (exports)
@@ -39,7 +40,7 @@ export interface ChatDictationButtonProps extends BaseProps<HTMLSpanElement> {
   dictation: UseSpeechRecognitionReturn;
   /** Button size. @default "md" */
   size?: 'sm' | 'md';
-  /** Hide the button when SpeechRecognition is not supported. @default true */
+  /** Hide the button when SpeechRecognition is unsupported. When false, the unsupported button remains visible but disabled. @default true */
   isHiddenWhenUnsupported?: boolean;
   /** Accessible label override. */
   label?: string;
@@ -128,13 +129,13 @@ export function ChatDictationButton({
   // Boost each band for visibility — quiet speech (0-10%) maps to full visual range
   const boostedBands = bands.map(b => Math.min(Math.pow(b / 0.2, 0.5), 1));
 
-  // Hue shift from accent color when volume clips past 10%
+  // Blend toward the theme's semantic error color as clipping increases.
   const isClipping = rawVolume >= 0.2;
-  const hueShift = isClipping ? Math.min((rawVolume - 0.2) / 0.1, 1) * 60 : 0;
+  const clippingStrength = Math.min((rawVolume - 0.2) / 0.1, 1) * 100;
 
   const barColor = isClipping
-    ? `hsl(calc(var(--accent-hue, 210) + ${hueShift}), 80%, 50%)`
-    : `var(--color-accent, ${colorVars['--color-accent']})`;
+    ? `color-mix(in srgb, ${colorVars['--color-accent']}, ${colorVars['--color-error']} ${clippingStrength}%)`
+    : colorVars['--color-accent'];
 
   const {barWidth, barGap, barMaxHeight} = SIZE_CONFIG[size];
 
@@ -180,6 +181,7 @@ export function ChatDictationButton({
         size={size}
         icon={isListening ? undefined : <Icon icon="microphone" size={size} />}
         isIconOnly
+        isDisabled={!dictation.isSupported}
         onClick={dictation.toggle}
       />
     </span>

package/src/Chat/ChatLayout.doc.mjs

@@ -6,7 +6,7 @@ export const docs = {
   name: 'ChatLayout',
   subComponentOf: 'Chat',
   displayName: 'Chat Layout',
-  description: 'Layout shell for full chat interfaces. Messages flow in normal page flow, composer is fixed to the bottom with a frosted glass dock. Adapts density (compact/balanced/spacious) automatically via container width observation. Includes built-in auto-scroll, a "New messages" scroll-to-bottom button, and a frosted glass blur layer behind the composer. By default the layout root is the scroll container; pass scrollRef to delegate scrolling to a parent element or the document body.',
+  description: 'Layout shell for full chat interfaces. Messages flow in normal page flow, composer is fixed to the bottom with a frosted glass dock. Set density (compact/balanced/spacious) to control spacing, message max-width, and blur layer sizing. Includes built-in auto-scroll, a "New messages" scroll-to-bottom button, and a frosted glass blur layer behind the composer. By default the layout root is the scroll container; pass scrollRef to delegate scrolling to a parent element or the document body.',
   props: [
     {
       name: 'children',
@@ -53,9 +53,15 @@ export const docs = {
       type: 'React.RefObject<HTMLElement | null>',
       description: 'External scroll container ref. When provided, auto-scroll and scroll-to-bottom target this element instead of the layout root. Use when the chat is embedded in a page where a parent element or the document body scrolls.',
     },
+    {
+      name: 'density',
+      type: "'compact' | 'balanced' | 'spacious'",
+      description: 'Visual density: controls dock padding, message-area max-width and inline padding, and the height of the frosted glass blur layer.',
+      default: "'balanced'",
+    },
   ],
   usage: {
-    description: 'ChatLayout is the layout shell for full-page chat interfaces. It renders messages in normal page flow and docks the composer to the bottom with a frosted glass blur layer. Density adapts automatically via container width observation. Use it to wrap ChatMessageList and ChatComposer for a complete chat experience with built-in auto-scroll and a scroll-to-bottom button.',
+    description: 'ChatLayout is the layout shell for full-page chat interfaces. It renders messages in normal page flow and docks the composer to the bottom with a frosted glass blur layer. Set the density prop to control spacing; it defaults to balanced. Use it to wrap ChatMessageList and ChatComposer for a complete chat experience with built-in auto-scroll and a scroll-to-bottom button.',
     bestPractices: [
       {
         guidance: true,
@@ -111,20 +117,21 @@ export const docs = {
 export const docsZh = {
   name: 'ChatLayout',
   displayName: 'Chat Layout',
-  description: '完整聊天界面的布局外壳。消息在页面中自然流动，编写器固定在底部，带有毛玻璃效果。通过容器宽度自动适配密度。',
+  description: '完整聊天界面的布局外壳。消息在页面中自然流动，编写器固定在底部，带有毛玻璃效果。通过 density 属性控制密度。',
   propDescriptions: {
     children: '消息内容，通常是 ChatMessageList。在页面中自然流动。',
     composer: '编写器元素，通常是 ChatComposer。固定在底部，带有毛玻璃底座。',
     emptyState: '子元素为空时显示的内容。',
     scrollButton: '编写器上方的滚动到底部按钮。默认使用 ChatLayoutScrollButton。传入 null 隐藏。',
     scrollRef: '外部滚动容器引用。提供时，自动滚动和滚动到底部将目标指向此元素。',
+    density: '视觉密度：控制底座内边距、消息区最大宽度和毛玻璃层高度。',
   },
 };
 
 export const docsDense = {
   name: 'ChatLayout',
   displayName: 'Chat Layout',
-  description: 'layout shell for full chat; msgs in page flow, composer fixed bottom w/ frosted glass dock; auto density via container width; scrollRef delegates to parent/body',
+  description: 'layout shell for full chat; msgs in page flow, composer fixed bottom w/ frosted glass dock; density prop (default balanced); scrollRef delegates to parent/body',
   usage: {
     bestPractices: [
       {guidance: true, description: 'Pass ChatMessageList as children and ChatComposer as composer prop for complete chat.'},
@@ -140,5 +147,6 @@ export const docsDense = {
     emptyState: 'content when children empty',
     scrollButton: 'scroll-to-bottom btn; defaults to ChatLayoutScrollButton; pass null to hide',
     scrollRef: 'external scroll container ref; targets parent/body instead of layout root',
+    density: 'visual density; dock padding, message max-width, blur height',
   },
 };

package/src/Chat/ChatLayout.spec.md

@@ -0,0 +1,271 @@
+---
+schema_version: 3
+template_version: 5
+kind: component
+id: component:ChatLayout
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+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
+
+This record is an **observational backfill** written during the 2026-09-23
+component audit under `spec:AST-029/FR3–FR4`. Every row below describes behavior
+already shipped on `main` and verified against source, focused tests, and
+consumer docs. It adds, improves, removes and reinterprets nothing. Rows whose
+basis is only current behavior are marked `verify`; unresolved questions stay in
+Open questions rather than being settled here.
+
+## 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 from this record. It documents the shipped surface; `density` becomes discoverable in consumer docs, which previously described an adaptation the component never performed.         |
+| Compatibility/readiness | Observational draft. No public API, default, or compatibility promise changes. Authority is `draft` until exact-head owner approval.                                                      |
+| 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 — `@astryxdesign/core@0.6.2` ships `./Chat`
+  with `ChatLayout`, `ChatLayoutProps`, and `ChatLayoutScrollButton`.
+- Compatibility class: no change. This record is descriptive.
+- 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  | Candidate invariant                                                                                                                                                    | Basis                                                          | Draft review state |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------ |
+| 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.                                        | regression fix for the phantom-scrollbar defect; pinned tests  | settled            |
+| 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.     | same regression fix; pinned tests                              | settled            |
+| FR3 | With no `scrollRef`, the root MUST be the scroll container and the dock MUST be `position: sticky`.                                                                    | shipped implementation; pinned test                            | verify             |
+| FR4 | With a `scrollRef`, the root MUST NOT become a scroll container and the dock MUST be `position: fixed`.                                                                | shipped implementation; pinned test                            | verify             |
+| FR5 | `emptyState` MUST replace `children` exactly when `children` is `null`, `undefined`, `false`, or an empty array, and MUST NOT replace any other children.              | shipped `hasVisibleContent`; pinned tests                      | verify             |
+| FR6 | `scrollButton` MUST distinguish three cases: omitted selects the wired default, `null` renders nothing, and a supplied node replaces the default.                      | shipped implementation; pinned tests                           | verify             |
+| 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. | shipped implementation; pinned tests; family doc `visualProps` | verify             |
+| FR8 | The layout MUST publish its scroll container and message content refs through `ChatLayoutContext` so the message list can register the observed content box.           | shipped implementation                                         | verify             |
+| 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`            | settled            |
+
+### 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 (observed)
+
+Observed 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` — reachability-gap: the dock, its inner column, and the backdrop-filter blur layer paint the component's most distinctive surface and carry no target.                                 |
+| 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` — reachability-gap: the empty-state box only centres caller content and carries no target.                                                                                             |
+
+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                                                                                                      | empty array; populated children                     | Treating populated children as empty hides the transcript                                         | `audit:ChatLayout/§4` |
+| FR6      | `ChatLayout.test.tsx` scroll-button cases                                                                                                    | default; custom node; `null`                        | Collapsing `null` into the default renders an affordance the caller removed                       | `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      | `useChatNewMessages.test.tsx`, `useChatStreamScroll.test.tsx`                                                                                | 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` |
+| PR2      | Source review of `useChatNewMessages`                                                                                                        | mounted list                                        | A per-instance `ResizeObserver` replaces the pooled one                                           | `audit:ChatLayout/§7` |
+
+## Decision log
+
+None. This record settles no decision; it describes shipped behavior.
+
+## 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/ChatLayout.test.tsx

@@ -2,6 +2,7 @@
 
 import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
 import {act, render, screen} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import {ChatLayout} from './ChatLayout';
 import {ChatMessageList} from './ChatMessageList';
 import {ChatMessage} from './ChatMessage';
@@ -103,6 +104,33 @@ describe('ChatLayout', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Keyboard reachability of the default scroll-to-bottom button
+//
+// At rest the layout is neither scrolled up nor holding new messages, so the
+// default ChatLayoutScrollButton renders in its hidden state. It is still in
+// the DOM, and it is the first control in the dock — ahead of the composer.
+// A control nobody can see must not be a tab stop: WCAG 2.2 SC 2.4.7 requires
+// a visible focus indicator wherever focus can land, and the hidden pill paints
+// nothing. `opacity: 0` and `pointer-events: none` do not remove an element
+// from sequential focus navigation; only visibility/display/inert do.
+// ---------------------------------------------------------------------------
+
+describe('ChatLayout — default scroll button keyboard reachability', () => {
+  it('does not make the resting scroll-to-bottom button the first tab stop', async () => {
+    const user = userEvent.setup();
+    render(
+      <ChatLayout composer={<button type="button">Send</button>}>
+        <div>msg</div>
+      </ChatLayout>,
+    );
+
+    await user.tab();
+
+    expect(screen.getByRole('button', {name: 'Send'})).toHaveFocus();
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Self-scroll layout contract (#2573)
 //

package/src/Chat/ChatLayout.tsx

@@ -268,6 +268,25 @@ function hasVisibleContent(children: ReactNode): boolean {
 // Component
 // =============================================================================
 
+/**
+ * Layout shell for a full chat interface: messages in page flow, composer
+ * docked to the bottom behind a frosted glass layer, with auto-scroll and a
+ * scroll-to-bottom button wired in.
+ *
+ * @example
+ * ```
+ * <ChatLayout
+ *   density="spacious"
+ *   composer={<ChatComposer onSubmit={send} />}
+ *   emptyState={<EmptyState title="No messages yet" />}>
+ *   <ChatMessageList>
+ *     <ChatMessage sender="assistant">
+ *       <ChatMessageBubble>How can I help?</ChatMessageBubble>
+ *     </ChatMessage>
+ *   </ChatMessageList>
+ * </ChatLayout>
+ * ```
+ */
 export function ChatLayout({
   children,
   composer,