@astryxdesign/core 0.6.2 → 0.6.3-canary.0899f21

package/src/Chat/ChatMessageBubble.spec.md

@@ -0,0 +1,263 @@
+---
+schema_version: 3
+template_version: 6
+kind: component
+id: component:ChatMessageBubble
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming, accessibility, testing]
+verified_by:
+  [
+    packages/core/src/Chat/ChatMessageBubble.test.tsx,
+    packages/core/src/Chat/__tests__/ChatMessageBubble.a11y.chromium.spec.ts,
+    apps/storybook/stories/ChatMessageBubble.stories.tsx,
+    apps/storybook/rtl-audit/targets.json,
+    packages/core/src/theme/themingTargets.test.ts,
+  ]
+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]
+---
+
+# ChatMessageBubble component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                                                   |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | Required `children`; optional `variant`, `name`, `metadata`, `group`, and `width`; root `div` passthrough, styles, and ref. This audit changes no public API shape or default.                                                                             |
+| Behavior                | The bubble derives sender and density from Chat message context, paints filled or ghost content, groups logical sender-side corners, and keeps renderable scalar name/metadata content inside aligned wrappers.                                            |
+| End-user impact         | Numeric zero stays aligned above or below the bubble instead of escaping its wrapper, while non-rendering scalars no longer create empty spacing. Direct light/dark, a11y, RTL, and narrow-layout evidence protects the result.                            |
+| Builder impact          | Existing props and values remain compatible. Builders passing `0` now get the same aligned placement as other visible scalars; nullish, boolean, and empty-string slot values emit no wrapper.                                                             |
+| Compatibility/readiness | Patch-compatible behavior correction. `@astryxdesign/core@0.6.3` already ships this surface through `./Chat`. The draft records the scalar correction and leaves composite/asynchronous content ownership and local visual representation unsettled.       |
+| Review checks           | Reject a dropped root passthrough/ref, missing target metadata, physical grouped-corner logic, an explicit width that retains the default cap, scalar `0` outside its wrapper, empty scalar wrappers, or a claim that settles the open composite boundary. |
+| Governing rules         | `architecture:public-component-api/INV1, INV5, INV6, INV8–INV9`; `architecture:component-theming-surface/INV4, INV6–INV8`; `architecture:component-test-sufficiency/INV1–INV7, INV10–INV11`; WCAG 2.2 SC 1.4.10.                                           |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+ChatMessageBubble is the optional sender-aware painted content surface inside a
+ChatMessage. It gives conversation content a bubble boundary, text inset,
+grouped-corner treatment, and aligned name/metadata placement that raw message
+content does not have.
+
+This record is an observational backfill written during the 2026-09-24
+whole-component audit. It describes verified shipped behavior. It does not
+decide new visual direction, expand the variant axis, or decide how the
+component should inspect composite or asynchronous React content.
+
+## Compatibility and migration
+
+- Released default preserved: yes — `@astryxdesign/core@0.6.3` ships the `./Chat`
+  subpath, all six component props, the assistant/balanced fallback, and the
+  filled default.
+- Compatibility class: patch. Visible numeric zero is moved into the existing
+  aligned wrapper; non-rendering scalar slots no longer create wrappers.
+- Controlled/uncontrolled behavior: unchanged — the component owns no state.
+- Migration decision: none. Existing consumers need no code change.
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The bubble root's fill, text color, typography, radius, padding, wrapping, and
+  width cap.
+- Mapping message sender and density context to bubble paint and geometry.
+- Grouped corner geometry on the sender side, using logical corners.
+- The aligned wrappers around optional `name` and `metadata` content.
+- Root DOM passthrough, consumer style composition, and the root ref.
+
+**Does not own / non-goals**
+
+- Message semantics, sender layout, avatar placement, or message-level names and
+  metadata — owned by ChatMessage or the shared Chat composition surface.
+- Timestamp, delivery status, and footer semantics — owned by
+  ChatMessageMetadata.
+- The meaning, accessibility, lifetime, or eventual rendered output of
+  caller-supplied React nodes.
+- List scrolling, transcript semantics, composer behavior, or system notices —
+  owned by their Chat components.
+
+## Public concepts
+
+| Concept                      | Closed values or states                                                                                           | Meaning                                                                                  | Availability by variant/orientation/state | Default                | Owner                                    | Stability     | Invalid-value behavior                                                           |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------- | ---------------------- | ---------------------------------------- | ------------- | -------------------------------------------------------------------------------- |
+| `children`                   | any `ReactNode`                                                                                                   | Content rendered inside the bubble root                                                  | always                                    | required               | caller                                   | stable        | n/a — required                                                                   |
+| `variant`                    | `filled`, `ghost`                                                                                                 | Selects a filled sender-aware boundary or transparent aligned content                    | always                                    | `filled`               | component                                | stable        | closed union; rejected by types                                                  |
+| `name`                       | omitted; any `ReactNode`                                                                                          | Optional content above the bubble in an aligned wrapper                                  | always                                    | omitted                | caller/component wrapper                 | stable        | non-rendering scalars omit; visible scalars including `0` align; see FR7 and OQ1 |
+| `metadata`                   | omitted; any `ReactNode`                                                                                          | Optional content below the bubble in an aligned wrapper                                  | always                                    | omitted                | caller/component wrapper                 | stable        | non-rendering scalars omit; visible scalars including `0` align; see FR7 and OQ1 |
+| `group`                      | omitted, `first`, `middle`, `last`                                                                                | Tightens sender-side corners for consecutive bubbles                                     | filled, ghost                             | omitted                | component                                | stable        | omitted keeps full radius; other values rejected by types                        |
+| `width`                      | omitted; any `SizeValue`                                                                                          | Replaces the default width cap with an explicit width                                    | filled, ghost                             | omitted                | caller                                   | stable        | numbers become CSS pixels; strings pass through                                  |
+| message context              | sender `user`, `assistant`, `system`; density `compact`, `balanced`, `spacious`; absent                           | Selects reflected sender/density and corresponding paint and geometry                    | when nested or standalone                 | assistant and balanced | Chat context / this projection           | observational | absent context uses component fallbacks                                          |
+| root `div`                   | `BaseProps<HTMLDivElement>` and `ref`                                                                             | Extends and references the element carrying children, paint, target, and bubble geometry | always                                    | none                   | `architecture:public-component-api`      | stable        | component target data and consumer styling compose                               |
+| `chat-message-bubble` target | sender, variant, and density reflected as `data-*`; exact guaranteed-property set not separately declared in docs | Public selector for the painting bubble root                                             | always                                    | one target per bubble  | `architecture:component-theming-surface` | stable        | undeclared generic properties remain best effort                                 |
+
+Consumer syntax and prop defaults remain in `ChatMessageBubble.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 component MUST always render one root `div` for `children`, including when the caller supplies non-rendering child content.                                                                                                             | shipped implementation and required `children` public seam                                    | verified observation      |
+| FR2 | The root MUST reflect the resolved sender. `user` selects user paint; `assistant`, `system`, and absent context use the non-user paint path; absent context reflects `assistant`.                                                           | shipped implementation and browser/unit evidence                                              | verified observation      |
+| FR3 | The root MUST reflect the resolved density. `compact` uses the compact radius and inset; `balanced` is the fallback; `spacious` uses its wider block and inline inset.                                                                      | shipped implementation and browser/unit evidence                                              | verified observation      |
+| FR4 | `filled` MUST paint sender-aware bubble styles; `ghost` MUST remove the fill and block-axis padding while preserving inline alignment.                                                                                                      | shipped implementation, consumer docs, and rendered evidence                                  | verified observation      |
+| FR5 | `first`, `middle`, and `last` MUST tighten the logical sender-side end, both, and start corner respectively. User uses inline-end; every non-user sender uses inline-start.                                                                 | shipped implementation plus real-browser LTR/RTL evidence                                     | verified observation      |
+| FR6 | Omitted `width` MUST keep `max(80%, 280px)`. An explicit number or string MUST set width and replace the default cap with `none`.                                                                                                           | shipped consumer docs, implementation, and unit evidence                                      | verified observation      |
+| FR7 | `name` and `metadata` MUST omit their aligned wrappers for null, undefined, booleans, and the empty string. Visible scalar values, including numeric zero, MUST remain inside their aligned wrappers. Non-scalar React nodes remain opaque. | shared `isRenderable` scalar contract, public `ReactNode` seam, and red-before-green evidence | settled scalar obligation |
+| FR8 | Root `ref`, neutral DOM/data/ARIA props, class, style, and `xstyle` MUST reach or combine on the painting root without losing the component target or owned styles.                                                                         | `architecture:public-component-api/INV5, INV6, INV8`                                          | settled obligation        |
+| FR9 | Exactly one `chat-message-bubble` target MUST ride the painting root and reflect sender, variant, and density.                                                                                                                              | `architecture:component-theming-surface/INV4, INV6–INV8`; public Chat docs                    | settled obligation        |
+
+FR7 corrects two reachable scalar mismatches. JavaScript truthiness previously
+returned numeric `0` as an unwrapped Fragment sibling, so React painted it
+outside the promised alignment, while `true` created an empty wrapper and gap.
+The shared scalar predicate now keeps visible scalars in their wrappers and
+omits scalar values that React does not paint.
+
+The public type also admits arrays, Fragments, elements, one-shot iterables,
+lazy content, and promises. The scalar correction does not traverse, clone,
+consume, await, or materialize those values: each remains caller-owned opaque
+content. Whether any composite or asynchronous category should be normalized is
+OQ1 rather than an implicit extension of this patch.
+
+### Allowed variation
+
+- **AV1 — Theme tokens.** Resolved colors, radii, spacing, and typography may vary
+  by theme while the semantic token roles remain.
+- **AV2 — Caller content.** Child, name, and metadata node structure and semantics
+  remain caller-owned.
+- **AV3 — Absolute geometry.** Token-resolved padding and radius may vary; logical
+  sender-side grouping and width precedence do not.
+
+### Representative states
+
+| State                     | Required invariant                                                   | Allowed variation                  |
+| ------------------------- | -------------------------------------------------------------------- | ---------------------------------- |
+| standalone                | assistant sender and balanced density fallback; one painting target  | caller content                     |
+| assistant/system, filled  | non-user paint; inline-start grouped corners                         | token-resolved paint               |
+| user, filled              | user paint; inline-end grouped corners                               | token-resolved paint               |
+| any sender, ghost         | transparent surface; inline inset retained; block inset removed      | themed text and padding            |
+| compact/balanced/spacious | reflected density and corresponding padding/radius path              | resolved token scale               |
+| group first/middle/last   | logical sender-side corner sequence in LTR and RTL                   | token-resolved radii               |
+| numeric slot `0`          | visible zero remains inside the aligned wrapper                      | none                               |
+| non-rendering scalar slot | null, undefined, booleans, and empty string emit no aligned wrapper  | none                               |
+| opaque name/metadata      | non-scalar inputs emit wrappers without traversal or materialization | eventual caller-owned React output |
+| width omitted/explicit    | default cap retained / explicit width replaces cap                   | valid CSS length                   |
+| narrow/long text          | text wraps with no horizontal overflow at 320 CSS px                 | line breaks and resulting height   |
+
+### Transformation and precedence order
+
+- **ORD1 — Context to paint.** Resolve sender/density from the nearest message
+  context or local fallback, select paint and geometry, then merge component
+  theme props, StyleX output, and consumer styling inputs through the shared
+  `mergeProps` contract.
+- **ORD2 — Width.** Apply the default maximum width when omitted; when explicit,
+  set width and replace that cap before consumer styling composition.
+- **ORD3 — Grouping.** Resolve sender side first, then group position, then use
+  logical corner properties so CSS direction mirrors the physical edge.
+
+### Performance and resources
+
+- **PR1 — Pure render derivation.** The component owns no state, Effect, event
+  listener, observer, timer, or animation frame. Every output derives from props
+  and context during render.
+- **PR2 — Caller content is not inspected.** The current implementation does not
+  traverse, clone, consume, await, or materialize caller-supplied React nodes.
+  Whether to preserve that boundary or normalize selected inputs is OQ1.
+
+## Accessibility contract
+
+- **AR1 — Display surface.** ChatMessageBubble adds no widget role, tab stop,
+  keyboard behavior, focus management, announcement, or accessible name of its
+  own. Semantics belong to the enclosing ChatMessage and caller content.
+- **AR2 — Content preservation.** Caller DOM and ARIA passthrough reach the bubble
+  root under FR8; component target metadata MUST NOT overwrite neutral caller ARIA.
+- **AR3 — Reflow.** At a 320 CSS-px parent width, long content and the documented
+  full-width case MUST wrap without horizontal page overflow (WCAG 2.2 SC 1.4.10).
+- **AR4 — Color.** Bubble text remains meaningful content and requires WCAG 2.2
+  AA text contrast against the final rendered bubble/backdrop in light and dark.
+  The component uses semantic token pairs; rendered measurement remains the audit
+  oracle.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                    | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ----------------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| bubble content   | sender-aware filled boundary or aligned ghost surface | unsettled                | primary        | FR2–FR4            |
+| grouped corners  | visually connect consecutive bubbles on sender side   | unsettled                | supporting     | FR5                |
+| name             | align auxiliary content with bubble text inset        | unsettled                | supporting     | FR7                |
+| metadata         | align auxiliary content with bubble text inset        | unsettled                | supporting     | FR7                |
+
+No `authority: current` design record owns ChatMessageBubble's local
+representation today. These rows record shipped appearance for review; they do
+not authorize a redesign or convert rendered judgment into policy.
+
+## Family and system relationships
+
+- The shared Chat consumer docs own composition guidance across message, bubble,
+  metadata, list, layout, and composer components.
+- `architecture:public-component-api` owns export, passthrough, styling-input,
+  and ref behavior.
+- `architecture:component-theming-surface` owns the painting target and reflected
+  axes. It does not independently require this closed variant axis to become
+  extensible; that would need a component-level public API decision.
+- `architecture:component-test-sufficiency` owns the closed, risk-based evidence
+  inventory and the red-before-green requirement for any future slot repair.
+- `spec:AST-029` owns the Night Watch observational backfill and remediation flow.
+
+## Verification map
+
+| Contract | Verification                                                         | Representative states                                        | Mutation or failure expectation                                                                 | Audit section                           |
+| -------- | -------------------------------------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- | --------------------------------------- |
+| FR1–FR3  | `ChatMessageBubble.test.tsx`; dedicated Storybook fixture            | standalone; user/assistant; compact/balanced/spacious        | removing fallback/reflection or a density path fails DOM or browser state evidence              | `audit:ChatMessageBubble/behavior`      |
+| FR4, FR9 | `themingTargets.test.ts`; scoped axe report; Chromium evidence       | filled; ghost; user/assistant/density                        | dropping reflection or moving the target fails DOM, generated, or rendered evidence             | `audit:ChatMessageBubble/theming`       |
+| FR5      | dedicated RTL target plus Chromium LTR/RTL frames                    | user/assistant × first/middle/last                           | physical corner logic or wrong sender side fails mirrored geometry and pixels                   | `audit:ChatMessageBubble/rtl`           |
+| FR6      | `ChatMessageBubble.test.tsx`; narrow browser fixture                 | omitted; string `100%`; number `420`                         | retaining the cap or changing numeric CSS semantics fails the width assertions                  | `audit:ChatMessageBubble/behavior`      |
+| FR7      | `ChatMessageBubble.test.tsx`; pre-fix Chromium receipts and pixels   | zero; true; false; empty string; nullish; opaque non-scalars | reverting to truthiness loses wrapper alignment or restores an empty scalar wrapper             | `audit:ChatMessageBubble/behavior`      |
+| FR8      | public-API checks and existing `data-testid`/style composition tests | ref; DOM/data/ARIA; class; style                             | removing rest/ref forwarding or replacing consumer styling fails shared or focused checks       | `audit:ChatMessageBubble/public-api`    |
+| AR1–AR4  | scoped axe report; Chromium receipts and pixels; narrow fixture      | all visible states, light/dark, RTL, 320px                   | a semantic violation, low-contrast pair, or horizontal overflow fails its owning evidence layer | `audit:ChatMessageBubble/accessibility` |
+
+## Decision log
+
+No component-local decision has been approved. This draft records only verified
+shipped behavior and the evidence routes added by the audit.
+
+## Open questions
+
+- **OQ1 — Should ChatMessageBubble keep every non-scalar `ReactNode`
+  name/metadata value as caller-owned opaque content, or normalize selected
+  arrays, Fragments, one-shot iterables, lazy values, or promises into a stable,
+  rerender-safe empty/non-empty contract?** (`human-api`)
+- **OQ2 — Should the aligned name and metadata wrappers become independently
+  themeable, inherit a current owner, or remain intentionally unreachable?**
+  (`human-api`)
+- **OQ3 — Which current design owner, if any, should make filled/ghost usage and
+  grouped-corner representation durable rather than observational?**
+  (`human-design`)
+
+## Content boundary
+
+This file does not duplicate the consumer prop table/examples, current audit
+scores, implementation steps, or shared architecture rules. Those remain in
+`ChatMessageBubble.doc.mjs`, the audit report, and their canonical owners.

package/src/Chat/ChatMessageBubble.test.tsx

@@ -1,5 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+import {createRef, type ReactNode} from 'react';
 import {describe, it, expect} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import {ChatMessage} from './ChatMessage';
@@ -66,6 +67,98 @@ describe('ChatMessageBubble', () => {
     expect(screen.getByTestId('my-bubble')).toBeTruthy();
   });
 
+  it('renders aligned name and metadata slots around the bubble root', () => {
+    render(
+      <ChatMessage sender="assistant">
+        <ChatMessageBubble
+          data-testid="bubble"
+          name="Navi"
+          metadata={<span>10:32 AM</span>}>
+          Hi
+        </ChatMessageBubble>
+      </ChatMessage>,
+    );
+    const bubble = screen.getByTestId('bubble');
+
+    expect(bubble.previousElementSibling).toHaveTextContent('Navi');
+    expect(bubble.nextElementSibling).toHaveTextContent('10:32 AM');
+  });
+
+  it('keeps numeric zero inside the aligned name and metadata slots', () => {
+    render(
+      <ChatMessageBubble data-testid="bubble" name={0} metadata={0}>
+        Zero slots
+      </ChatMessageBubble>,
+    );
+    const bubble = screen.getByTestId('bubble');
+
+    expect(bubble.previousElementSibling).toHaveAttribute('data-chat-name');
+    expect(bubble.previousElementSibling).toHaveTextContent('0');
+    expect(bubble.nextElementSibling).toHaveTextContent('0');
+  });
+
+  it.each([
+    ['null', null],
+    ['undefined', undefined],
+    ['false', false],
+    ['true', true],
+    ['empty string', ''],
+  ] satisfies [string, ReactNode][])(
+    'omits aligned wrappers for %s',
+    (_, value) => {
+      const {container} = render(
+        <ChatMessageBubble data-testid="bubble" name={value} metadata={value}>
+          Empty scalar slots
+        </ChatMessageBubble>,
+      );
+      const bubble = screen.getByTestId('bubble');
+
+      expect(container.querySelector('[data-chat-name]')).toBeNull();
+      expect(bubble.previousElementSibling).toBeNull();
+      expect(bubble.nextElementSibling).toBeNull();
+    },
+  );
+
+  it('forwards the ref and neutral DOM props to the bubble root', () => {
+    const ref = createRef<HTMLDivElement>();
+    render(
+      <ChatMessageBubble
+        ref={ref}
+        id="bubble-id"
+        aria-label="Message content"
+        data-consumer="preserved"
+        data-testid="bubble">
+        Standalone
+      </ChatMessageBubble>,
+    );
+    const bubble = screen.getByTestId('bubble');
+
+    expect(ref.current).toBe(bubble);
+    expect(bubble).toHaveAttribute('id', 'bubble-id');
+    expect(bubble).toHaveAttribute('aria-label', 'Message content');
+    expect(bubble).toHaveAttribute('data-consumer', 'preserved');
+  });
+
+  it('reflects both built-in visual variants on the painting root', () => {
+    render(
+      <>
+        <ChatMessageBubble data-testid="filled">Filled</ChatMessageBubble>
+        <ChatMessageBubble data-testid="ghost" variant="ghost">
+          Ghost
+        </ChatMessageBubble>
+      </>,
+    );
+
+    expect(screen.getByTestId('filled')).toHaveAttribute(
+      'data-variant',
+      'filled',
+    );
+    expect(screen.getByTestId('ghost')).toHaveAttribute(
+      'data-variant',
+      'ghost',
+    );
+  });
+
   it('ghost variant aligns custom content with the bubble text column (#2574)', () => {
     // Repro from the issue: a raw child renders flush with the message
     // edge — it carries none of the inset the bubble's name slot gets.

package/src/Chat/ChatMessageBubble.tsx

@@ -38,7 +38,7 @@ import {
   typographyVars,
 } from '../theme/tokens.stylex';
 import {useChatMessageContext} from './ChatContext';
-import {mergeProps} from '../utils';
+import {isRenderable, mergeProps} from '../utils';
 import type {SizeValue} from '../utils/types';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
@@ -64,6 +64,7 @@ export interface ChatMessageBubbleProps extends BaseProps<HTMLDivElement> {
 
   /**
    * Sender name rendered above the bubble, aligned with bubble text padding.
+   * Non-rendering scalar values omit the aligned wrapper; numeric zero remains.
    * Use when the first content in a message is a bubble.
    * If the first content is raw (no bubble), use ChatMessage's `name`
    * prop instead.
@@ -72,6 +73,7 @@ export interface ChatMessageBubbleProps extends BaseProps<HTMLDivElement> {
 
   /**
    * Metadata content rendered below the bubble, aligned with bubble text padding.
+   * Non-rendering scalar values omit the aligned wrapper; numeric zero remains.
    * Use when the last content in a message is a bubble.
    * If the last content is raw (no bubble), use ChatMessage's `metadata`
    * prop instead.
@@ -289,9 +291,12 @@ export function ChatMessageBubble({
         ? styles.metadataPaddingSpacious
         : styles.metadataPaddingBalanced;
 
+  const hasName = isRenderable(name);
+  const hasMetadata = isRenderable(metadata);
+
   return (
     <>
-      {name && (
+      {hasName && (
         <div
           data-chat-name
           {...stylex.props(
@@ -324,7 +329,7 @@ export function ChatMessageBubble({
         )}>
         {children}
       </div>
-      {metadata && (
+      {hasMetadata && (
         <div
           {...stylex.props(
             metadataPaddingStyle,

package/src/Chat/ChatMessageList.spec.md

@@ -0,0 +1,222 @@
+---
+schema_version: 3
+template_version: 6
+kind: component
+id: component:ChatMessageList
+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/ChatMessageList.test.tsx,
+    packages/core/src/Chat/__tests__/ChatMessageList.a11y.chromium.spec.ts,
+    apps/storybook/stories/ChatMessageList.stories.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [
+    architecture:public-component-api,
+    architecture:component-test-sufficiency,
+    architecture:component-style-authoring,
+    architecture:component-theming-surface,
+    architecture:react-component-runtime,
+    architecture:knowledge-contracts,
+  ]
+contributing: []
+system_specs: [spec:AST-029]
+---
+
+# ChatMessageList component contract
+
+This draft is an observational account of shipped `core/ChatMessageList`. Its
+candidate invariants name their source and evidence; they do not decide any
+new API, default, loading protocol, or visual direction. The current shared
+records linked above continue to govern independently.
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                           |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `children`, `emptyState`, `scrollToTopAction`, `density`, `gap`, `align`, `isStreaming`, the root's `BaseProps<HTMLDivElement>`, and `ref`.                                        |
+| Behavior                | A polite log holds caller messages. Density selects row spacing and passes through context. A top sentinel can request older messages. A spacer moves short lists down by default. |
+| End-user impact         | A reader with a numeric empty-state value sees `0`; other transcript arrangements remain unchanged.                                                                                |
+| Builder impact          | None. No new caller choice or migration is introduced.                                                                                                                             |
+| Compatibility/readiness | The published `./Chat` subpath and its defaults remain unchanged. This is a draft pending verification and exact-head owner review.                                                |
+| Review checks           | Reject a claim that the list owns ChatLayout auto-scroll, that a draft settles an unobserved loading policy, or that DOM `aria-busy` proves spoken output.                         |
+| Governing rules         | `architecture:public-component-api/INV1, INV5–INV8`; `architecture:react-component-runtime/INV3, INV5–INV6`; `spec:AST-029/FR2–FR5`.                                               |
+
+This table is a review projection; the body below describes the observed
+surface rather than creating new authority.
+
+## Intent
+
+ChatMessageList is the presentational message container within the Chat
+composition. It owns a flex-column transcript, spacing/density context, an
+optional empty state and older-message sentinel, and the log's rendered ARIA
+attributes. `ChatLayout` owns auto-follow scrolling and the dock; message and
+bubble components own sender presentation and content.
+
+Consumer prop syntax and examples remain in `ChatMessageList.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: yes. The published Core package exposes `./Chat`
+  with `ChatMessageList` and `ChatMessageListProps`.
+- Compatibility class: no new API, default, or migration. Visible numeric
+  empty-state content follows the existing `ReactNode` type.
+- Controlled/uncontrolled behavior: not applicable; there is no controlled
+  value on this component.
+- Migration decision: none.
+
+## Ownership boundary
+
+**Owns**
+
+- The outer log element, its public DOM/ref/style passthrough, and the
+  `chat-message-list` target with its `density` selector.
+- The inner flex-column message box and density-based padding and gap.
+- The short-list block spacer when `align` is `bottom`.
+- The optional `emptyState` substitution and older-message sentinel/loading
+  indicator.
+- Passing the inner content element to `ChatLayoutContext.contentRef` while a
+  layout is present.
+
+**Does not own / non-goals**
+
+- Auto-scroll, scroll-to-bottom, dock, and scroll-owner selection, which belong
+  to `component:ChatLayout` and its scroll hooks.
+- Sender identity, message alignment, bubbles, metadata, and text semantics,
+  which belong to their child components.
+- The caller's region landmark or an accessible name for arbitrary transcript
+  context; no new naming policy is made by this draft.
+
+## Public concepts
+
+| Concept             | Closed values or states                         | Meaning observed                                                | Availability  | Default    | Owner     | Stability | Invalid-value behavior                             |
+| ------------------- | ----------------------------------------------- | --------------------------------------------------------------- | ------------- | ---------- | --------- | --------- | -------------------------------------------------- |
+| `children`          | `ReactNode`                                     | Top-level transcript content                                    | every render  | required   | caller    | released  | null, false, or `[]` counts empty at the top level |
+| `emptyState`        | `ReactNode`; omitted                            | Substitutes for top-level empty children                        | empty state   | omitted    | caller    | released  | absent renders no substitute                       |
+| `scrollToTopAction` | async function; omitted                         | Invoked when the top sentinel intersects                        | when supplied | omitted    | caller    | released  | absent creates no sentinel or observer             |
+| `density`           | `compact`; `balanced`; `spacious`               | Chooses message spacing and child density context               | every render  | `balanced` | component | released  | closed type union                                  |
+| `gap`               | published `SpacingStep`; omitted                | Overrides the list's top-level row gap independently of density | every render  | omitted    | caller    | released  | closed type union                                  |
+| `align`             | `top`; `bottom`                                 | Positions short content at the start or block end               | every render  | `bottom`   | component | released  | closed type union                                  |
+| `isStreaming`       | `true`; `false`                                 | Exposes `aria-busy` on the polite log while streaming           | every render  | `false`    | caller    | released  | boolean                                            |
+| root passthrough    | `ref`, accepted DOM/data/ARIA and styling props | Extends the outer log element                                   | every render  | omitted    | caller    | released  | owned role/live/busy attributes retain precedence  |
+
+The table records the implementation's top-level emptiness test; it does not
+promise recursive child inspection or resolve the meaning of arbitrary
+non-rendering React nodes.
+
+## Behavioral and layout contract
+
+These candidate invariants record observable shipped behavior. A `verify`
+state means the audit has not upgraded implementation into policy.
+
+| ID  | Candidate invariant                                                                                                                                                      | Basis                                                  | Draft review state |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ | ------------------ |
+| FR1 | The outer root renders `role="log"`, `aria-live="polite"`, and `tabIndex=0`; `isStreaming=true` adds `aria-busy="true"`, which is absent otherwise.                      | Shipped source, colocated DOM tests and consumer docs  | verify             |
+| FR2 | The chosen density is reflected as `data-density` on the root and flows to child messages through `ChatListContext`; it selects three spacing groups.                    | Shipped source, colocated density test, family docs    | verify             |
+| FR3 | The optional `gap` replaces only the top-level row gap; density still selects padding and context.                                                                       | Shipped source and consumer docs                       | verify             |
+| FR4 | `emptyState` renders only when `children` is nullish, `false`, or an empty top-level array. Otherwise the passed children render unchanged.                              | Shipped source, empty-array and numeric-zero tests     | verify             |
+| FR5 | `align="bottom"` includes a flex spacer before messages; `align="top"` omits it. Overflowing content is not given a different rendering path.                            | Shipped source, colocated tests, existing family story | verify             |
+| FR6 | Supplying `scrollToTopAction` creates an observed top sentinel. An intersection starts its async transition, and a top-positioned spinner renders while it is pending.   | Shipped source, consumer docs, focused async test      | verify             |
+| FR7 | Inside ChatLayout, the inner content element is passed to the layout's `contentRef` and removed from that registration on cleanup; standalone lists have no layout ref.  | Shipped source and context definition                  | verify             |
+| FR8 | The root receives `ref`, accepted DOM/data/ARIA props, and composed `className`, `style`, and `xstyle`; component-owned log semantics are applied after forwarded props. | Shipped source and shared public API authority         | verify             |
+
+For the `emptyState` slot, numeric `0` is visible content. Nullish values,
+booleans, and an empty string do not create an empty wrapper. This describes
+scalar output only; it does not decide how to inspect nested children.
+
+### Allowed variation
+
+- **AV1 - Content.** Any caller-owned ReactNode may be placed in the list; the
+  list does not infer sender metadata from children.
+- **AV2 - Spacing.** Density selects token-based defaults; the optional `gap`
+  selects a published spacing step without changing the child density.
+- **AV3 - Scroll ownership.** The list may be used alone or inside ChatLayout;
+  auto-follow behavior remains outside this component.
+
+### Representative states
+
+| State                         | Observed result                                       | Allowed variation                          |
+| ----------------------------- | ----------------------------------------------------- | ------------------------------------------ |
+| Two messages and a system row | Polite log with messages in source order              | Caller controls row content                |
+| Empty top-level children      | Optional centered empty state                         | An omitted empty state leaves an empty log |
+| Compact/balanced/spacious     | Different token-derived row spacing and child density | `gap` may override only row spacing        |
+| Short top/bottom list         | Bottom includes a spacer, top omits it                | Container height is caller-owned           |
+| Streaming                     | Log has `aria-busy=true`                              | Message content remains caller-owned       |
+| Top action pending            | Spinner above content while transition is pending     | Async action result is caller-owned        |
+
+### Performance and resources
+
+- An `IntersectionObserver` is installed only when `scrollToTopAction` exists,
+  and disconnected on cleanup. Its root is ChatLayout's scroll container when
+  available, otherwise the document viewport.
+- An Effect registers the inner content element with ChatLayout, then clears
+  that registration on cleanup. This draft does not prescribe an internal hook
+  or listener implementation.
+
+## Accessibility contract
+
+- The shipped root is a focusable polite log with `aria-busy` reflecting
+  `isStreaming`; this describes browser-exposed semantics, not an observed
+  screen-reader announcement transcript.
+- The loading spinner is a separate child of the log. The list adds no
+  interactive button or directional keyboard behavior of its own.
+- Caller-supplied content remains responsible for names and semantics inside
+  messages. This record does not claim one browser/AT pairing proves another.
+
+## Design relationships
+
+No current component-local design decision is added by this observational
+backfill. Spacing uses portable semantic token steps. The family consumer doc
+owns the published `chat-message-list` theme target and its `density` axis.
+This record does not choose a new visual representation or a new theming target.
+
+## Family and system relationships
+
+- No `family:chat` authority record currently exists. `Chat.doc.mjs` is the
+  consumer family document, not a product-authority family contract.
+- `ChatLayout` owns the scroll container and provides `contentRef`; the list
+  registers its content element without taking over ChatLayout's scrolling.
+- `spec:AST-029` governs observational audit backfills and keeps their
+  evidence inventory separate from component policy.
+
+## Verification map
+
+| Contract | Evidence                                                            | Representative states              | Mutation or failure expectation                          | Audit section              |
+| -------- | ------------------------------------------------------------------- | ---------------------------------- | -------------------------------------------------------- | -------------------------- |
+| FR1      | `ChatMessageList.test.tsx` ARIA assertions; Chromium audit receipts | rest, streaming                    | Dropping busy or the log role changes the exposed state  | `audit:ChatMessageList/§1` |
+| FR2–FR3  | density test, theming-target guard, rendered comparison             | three densities and gap override   | Losing density reflection or row spacing becomes visible | `audit:ChatMessageList/§2` |
+| FR4–FR5  | empty/align tests, component-owned Storybook and Chromium receipts  | empty, top and bottom              | Empty substitute or short-list placement changes         | `audit:ChatMessageList/§4` |
+| FR6      | `ChatMessageList.test.tsx` async action/status test                 | sentinel absent, pending, settled  | Action loss or stuck spinner fails the focused test      | `audit:ChatMessageList/§6` |
+| FR7      | ChatLayout integration and source review                            | standalone, inside layout, unmount | Content observation can lose registration                | `audit:ChatMessageList/§7` |
+| FR8      | `themingTargets.test.ts`, focused root passthrough inspection       | ref, DOM/ARIA, styling             | Consumer inputs fail to reach or compose on the root     | `audit:ChatMessageList/§3` |
+
+## Decision log
+
+None. This draft settles no component-local product decision.
+
+## Open questions
+
+- **OQ1 - What is the intended overlap policy for repeated top-sentinel
+  intersections while an async load remains pending?** (`human-api`) The current
+  source invokes the action on intersection; this record does not add a
+  single-flight, initial-load, or exhaustion guarantee.
+- **OQ2 - Should emptiness inspect nested non-rendering ReactNode values?**
+  (`human-api`) The shipped test is limited to the top-level `children` value.
+  Do not reinterpret that test as a policy about generators, fragments,
+  promised children, or arrays of non-rendering values.
+
+## Content boundary
+
+This file contains no audit score, screenshot matrix, run transcript, consumer
+prop example, new public API, or cross-component visual policy.