@astryxdesign/core 0.6.3-canary.db4e378 → 0.6.3-canary.ddb63c3

package/dist/Chat/ChatMessageList.d.ts

@@ -1,6 +1,7 @@
 /**
  * @file ChatMessageList.tsx
- * @input Uses React, StyleX, ChatListContext, theme tokens, spacing step utilities
+ * @input Uses React, StyleX, ChatListContext, theme tokens, spacing step utilities,
+ *   and isRenderable to preserve accepted empty-state content
  * @output Exports ChatMessageList component and ChatMessageListProps
  * @position Presentational message container — holds ChatMessage children
  *

package/dist/Chat/ChatMessageList.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ChatMessageList.d.ts","sourceRoot":"","sources":["../../src/Chat/ChatMessageList.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAC,KAAK,SAAS,EAA4C,MAAM,OAAO,CAAC;AAGhF,OAAO,EAEL,KAAK,WAAW,EAEjB,MAAM,eAAe,CAAC;AAGvB,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAGhD,MAAM,WAAW,oBAAqB,SAAQ,SAAS,CAAC,cAAc,CAAC;IACrE,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAEhC;;;OAGG;IACH,QAAQ,EAAE,SAAS,CAAC;IAEpB;;OAEG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IAEvB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAExC;;;;OAIG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,WAAW,CAAC;IAElB;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC;IAEzB;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AA4FD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAAC,EAC9B,QAAQ,EACR,UAAU,EACV,iBAAiB,EACjB,OAAoB,EACpB,GAAG,EACH,KAAgB,EAChB,WAAmB,EACnB,MAAM,EACN,SAAS,EACT,KAAK,EACL,aAAa,EAAE,MAAM,EACrB,GAAG,EACH,GAAG,IAAI,EACR,EAAE,oBAAoB,+BAgGtB;yBA9Ge,eAAe"}
+{"version":3,"file":"ChatMessageList.d.ts","sourceRoot":"","sources":["../../src/Chat/ChatMessageList.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAC,KAAK,SAAS,EAA4C,MAAM,OAAO,CAAC;AAGhF,OAAO,EAEL,KAAK,WAAW,EAEjB,MAAM,eAAe,CAAC;AAGvB,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAGhD,MAAM,WAAW,oBAAqB,SAAQ,SAAS,CAAC,cAAc,CAAC;IACrE,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAEhC;;;OAGG;IACH,QAAQ,EAAE,SAAS,CAAC;IAEpB;;OAEG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IAEvB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAExC;;;;OAIG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,WAAW,CAAC;IAElB;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC;IAEzB;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AA4FD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAAC,EAC9B,QAAQ,EACR,UAAU,EACV,iBAAiB,EACjB,OAAoB,EACpB,GAAG,EACH,KAAgB,EAChB,WAAmB,EACnB,MAAM,EACN,SAAS,EACT,KAAK,EACL,aAAa,EAAE,MAAM,EACrB,GAAG,EACH,GAAG,IAAI,EACR,EAAE,oBAAoB,+BAgGtB;yBA9Ge,eAAe"}

package/dist/Chat/ChatMessageList.js

@@ -4,7 +4,8 @@
 
 /**
  * @file ChatMessageList.tsx
- * @input Uses React, StyleX, ChatListContext, theme tokens, spacing step utilities
+ * @input Uses React, StyleX, ChatListContext, theme tokens, spacing step utilities,
+ *   and isRenderable to preserve accepted empty-state content
  * @output Exports ChatMessageList component and ChatMessageListProps
  * @position Presentational message container — holds ChatMessage children
  *
@@ -27,7 +28,7 @@ import * as stylex from '@stylexjs/stylex';
 import "../theme/tokens.stylex.js";
 import { spacingVars } from "../theme/tokens.stylex.js";
 import { ChatListContext, useChatLayoutContext } from "./ChatContext.js";
-import { mergeProps } from "../utils/index.js";
+import { isRenderable, mergeProps } from "../utils/index.js";
 import { Spinner } from "../Spinner/index.js";
 import { themeProps } from "../utils/themeProps.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
@@ -225,7 +226,7 @@ export function ChatMessageList({
             className: "x98rzlu x2lwn1j"
           },
           "aria-hidden": true
-        }), hasChildren ? children : emptyState ? /*#__PURE__*/_jsx("div", {
+        }), hasChildren ? children : isRenderable(emptyState) ? /*#__PURE__*/_jsx("div", {
           ...{
             className: "x78zum5 x6s0dn4 xl56j7k x98rzlu x2lwn1j"
           },

package/dist/Markdown/plugins/index.d.ts

@@ -11,6 +11,7 @@ export type { MarkdownFenceContext, MarkdownFenceNode, MarkdownFenceTransformOpt
 export { createMarkdownSourceDecoration, getMarkdownSourceDecorations, } from './sourceDecoration';
 export type { MarkdownSourceDecoration, MarkdownSourceDecorationOptions, MarkdownSourceDecorationRange, } from './sourceDecoration';
 export { createMarkdownFrontmatter } from './frontmatter';
+export { markdownSoftBreaksPlugin } from './softBreaks';
 export type { MarkdownFrontmatter, MarkdownFrontmatterOptions, MarkdownFrontmatterParseResult, } from './frontmatter';
 export type { MarkdownPluginData, MarkdownExtensionNode, MarkdownTokenizerInput, MarkdownTokenizeResult, MarkdownSyntaxContribution, MarkdownSyntaxCapability, MarkdownTransformContext, MarkdownTransform, MarkdownExtensionRenderer, MarkdownExtensionRenderers, MarkdownSyntaxPluginDefinition, MarkdownTransformPluginDefinition, MarkdownPluginDefinition, MarkdownPluginEntry, MarkdownNodeOf, MarkdownExtensionsOf, } from './protocol';
 //# sourceMappingURL=index.d.ts.map

package/dist/Markdown/plugins/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/Markdown/plugins/index.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,OAAO,EAAC,oBAAoB,EAAE,uBAAuB,EAAC,MAAM,YAAY,CAAC;AACzE,OAAO,EAAC,2BAA2B,EAAC,MAAM,iBAAiB,CAAC;AAC5D,YAAY,EACV,4BAA4B,EAC5B,4BAA4B,GAC7B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAC,4BAA4B,EAAC,MAAM,iBAAiB,CAAC;AAC7D,YAAY,EACV,oBAAoB,EACpB,iBAAiB,EACjB,6BAA6B,GAC9B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,8BAA8B,EAC9B,4BAA4B,GAC7B,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,wBAAwB,EACxB,+BAA+B,EAC/B,6BAA6B,GAC9B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAC,yBAAyB,EAAC,MAAM,eAAe,CAAC;AACxD,YAAY,EACV,mBAAmB,EACnB,0BAA0B,EAC1B,8BAA8B,GAC/B,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,kBAAkB,EAClB,qBAAqB,EACrB,sBAAsB,EACtB,sBAAsB,EACtB,0BAA0B,EAC1B,wBAAwB,EACxB,wBAAwB,EACxB,iBAAiB,EACjB,yBAAyB,EACzB,0BAA0B,EAC1B,8BAA8B,EAC9B,iCAAiC,EACjC,wBAAwB,EACxB,mBAAmB,EACnB,cAAc,EACd,oBAAoB,GACrB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/Markdown/plugins/index.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,OAAO,EAAC,oBAAoB,EAAE,uBAAuB,EAAC,MAAM,YAAY,CAAC;AACzE,OAAO,EAAC,2BAA2B,EAAC,MAAM,iBAAiB,CAAC;AAC5D,YAAY,EACV,4BAA4B,EAC5B,4BAA4B,GAC7B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAC,4BAA4B,EAAC,MAAM,iBAAiB,CAAC;AAC7D,YAAY,EACV,oBAAoB,EACpB,iBAAiB,EACjB,6BAA6B,GAC9B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,8BAA8B,EAC9B,4BAA4B,GAC7B,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,wBAAwB,EACxB,+BAA+B,EAC/B,6BAA6B,GAC9B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAC,yBAAyB,EAAC,MAAM,eAAe,CAAC;AACxD,OAAO,EAAC,wBAAwB,EAAC,MAAM,cAAc,CAAC;AACtD,YAAY,EACV,mBAAmB,EACnB,0BAA0B,EAC1B,8BAA8B,GAC/B,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,kBAAkB,EAClB,qBAAqB,EACrB,sBAAsB,EACtB,sBAAsB,EACtB,0BAA0B,EAC1B,wBAAwB,EACxB,wBAAwB,EACxB,iBAAiB,EACjB,yBAAyB,EACzB,0BAA0B,EAC1B,8BAA8B,EAC9B,iCAAiC,EACjC,wBAAwB,EACxB,mBAAmB,EACnB,cAAc,EACd,oBAAoB,GACrB,MAAM,YAAY,CAAC"}

package/dist/Markdown/plugins/index.js

@@ -10,4 +10,5 @@ export { createMarkdownPlugin, isMarkdownExtensionNode } from "./protocol.js";
 export { createMarkdownTextTransform } from "./textTransform.js";
 export { createMarkdownFenceTransform } from "./semanticFence.js";
 export { createMarkdownSourceDecoration, getMarkdownSourceDecorations } from "./sourceDecoration.js";
-export { createMarkdownFrontmatter } from "./frontmatter.js";
+export { createMarkdownFrontmatter } from "./frontmatter.js";
+export { markdownSoftBreaksPlugin } from "./softBreaks.js";

package/dist/Markdown/plugins/softBreaks.d.ts

@@ -0,0 +1,3 @@
+/** Converts soft line endings in Markdown phrasing content to hard breaks. */
+export declare const markdownSoftBreaksPlugin: import("./protocol").MarkdownPluginEntry<never>;
+//# sourceMappingURL=softBreaks.d.ts.map

package/dist/Markdown/plugins/softBreaks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"softBreaks.d.ts","sourceRoot":"","sources":["../../../src/Markdown/plugins/softBreaks.ts"],"names":[],"mappings":"AAmKA,8EAA8E;AAC9E,eAAO,MAAM,wBAAwB,iDAInC,CAAC"}

package/dist/Markdown/plugins/softBreaks.js

@@ -0,0 +1,172 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file softBreaks.ts
+ * @input Soft line endings in Markdown phrasing content
+ * @output A first-party plugin that renders each soft line ending as a hard break
+ * @position Optional Markdown transform built only on the public plugin protocol
+ */
+
+import { createMarkdownPlugin } from "./protocol.js";
+function replaceLineEndings(value) {
+  const pattern = /\r?\n|\r/g;
+  let match = pattern.exec(value);
+  if (match == null) {
+    return null;
+  }
+  const output = [];
+  let cursor = 0;
+  do {
+    if (match.index > cursor) {
+      output.push({
+        type: 'text',
+        value: value.slice(cursor, match.index)
+      });
+    }
+    output.push({
+      type: 'break'
+    });
+    cursor = match.index + match[0].length;
+    match = pattern.exec(value);
+  } while (match != null);
+  if (cursor < value.length) {
+    output.push({
+      type: 'text',
+      value: value.slice(cursor)
+    });
+  }
+  return output;
+}
+function transformPhrasing(children) {
+  let next;
+  for (let index = 0; index < children.length; index++) {
+    const node = children[index];
+    if (node.type === 'text') {
+      const replacement = replaceLineEndings(node.value);
+      if (replacement == null) {
+        next?.push(node);
+      } else {
+        next ??= children.slice(0, index);
+        next.push(...replacement);
+      }
+      continue;
+    }
+    if (node.type === 'strong' || node.type === 'emphasis' || node.type === 'delete' || node.type === 'link') {
+      const nested = transformPhrasing(node.children);
+      if (nested !== node.children) {
+        next ??= children.slice(0, index);
+        next.push({
+          ...node,
+          children: nested
+        });
+      } else {
+        next?.push(node);
+      }
+      continue;
+    }
+    next?.push(node);
+  }
+  return next ?? children;
+}
+function transformTableCell(cell) {
+  const children = transformPhrasing(cell.children);
+  return children === cell.children ? cell : {
+    ...cell,
+    children
+  };
+}
+function transformTableRow(row) {
+  const children = row.children.map(transformTableCell);
+  return children.every((child, index) => child === row.children[index]) ? row : {
+    ...row,
+    children
+  };
+}
+function transformListItem(item) {
+  const children = transformBlocks(item.children);
+  return children === item.children ? item : {
+    ...item,
+    children
+  };
+}
+function transformBlocks(children) {
+  let next;
+  for (let index = 0; index < children.length; index++) {
+    const node = children[index];
+    let transformed = node;
+    switch (node.type) {
+      case 'heading':
+      case 'paragraph':
+        {
+          const nested = transformPhrasing(node.children);
+          if (nested !== node.children) {
+            transformed = {
+              ...node,
+              children: nested
+            };
+          }
+          break;
+        }
+      case 'blockquote':
+        {
+          const nested = transformBlocks(node.children);
+          if (nested !== node.children) {
+            transformed = {
+              ...node,
+              children: nested
+            };
+          }
+          break;
+        }
+      case 'list':
+        {
+          const nested = node.children.map(transformListItem);
+          if (nested.some((child, childIndex) => child !== node.children[childIndex])) {
+            transformed = {
+              ...node,
+              children: nested
+            };
+          }
+          break;
+        }
+      case 'table':
+        {
+          const nested = node.children.map(transformTableRow);
+          if (nested.some((child, childIndex) => child !== node.children[childIndex])) {
+            transformed = {
+              ...node,
+              children: nested
+            };
+          }
+          break;
+        }
+      case 'code':
+      case 'math':
+      case 'thematicBreak':
+      case 'image':
+      case 'extension':
+        break;
+      default:
+        node;
+    }
+    if (transformed !== node) {
+      next ??= children.slice(0, index);
+    }
+    next?.push(transformed);
+  }
+  return next ?? children;
+}
+const transformSoftBreaks = document => {
+  const children = transformBlocks(document.children);
+  return children === document.children ? document : {
+    ...document,
+    children
+  };
+};
+
+/** Converts soft line endings in Markdown phrasing content to hard breaks. */
+export const markdownSoftBreaksPlugin = createMarkdownPlugin({
+  name: 'soft-breaks',
+  apiVersion: 1,
+  transform: transformSoftBreaks
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.6.3-canary.db4e378",
+  "version": "0.6.3-canary.ddb63c3",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -692,8 +692,8 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
-    "@astryxdesign/a11y-spec": "0.6.3-canary.db4e378",
-    "@astryxdesign/cli": "0.6.3-canary.db4e378",
+    "@astryxdesign/a11y-spec": "0.6.3-canary.ddb63c3",
+    "@astryxdesign/cli": "0.6.3-canary.ddb63c3",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",

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.

package/src/Chat/ChatMessageList.test.tsx

@@ -1,7 +1,14 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-import {describe, it, expect} from 'vitest';
-import {render, screen} from '@testing-library/react';
+/**
+ * @file ChatMessageList.test.tsx
+ * @input React Testing Library, Vitest, and the public ChatMessageList surface
+ * @output Observable log, empty-state, alignment, and async-loading regressions
+ * @position Colocated component behavior tests
+ */
+
+import {describe, it, expect, vi} from 'vitest';
+import {act, render, screen} from '@testing-library/react';
 import {ChatMessageList} from './ChatMessageList';
 import {ChatMessage} from './ChatMessage';
 import {ChatMessageBubble} from './ChatMessageBubble';
@@ -55,6 +62,11 @@ describe('ChatMessageList', () => {
     expect(screen.getByText('No messages yet')).toBeTruthy();
   });
 
+  it('renders an accepted numeric empty state', () => {
+    render(<ChatMessageList emptyState={0}>{[]}</ChatMessageList>);
+    expect(screen.getByRole('log')).toHaveTextContent('0');
+  });
+
   it('applies density class', () => {
     render(
       <ChatMessageList density="compact" data-testid="list">
@@ -129,4 +141,54 @@ describe('ChatMessageList', () => {
     );
     expect(screen.getByText('Hello')).toBeTruthy();
   });
+
+  it('loads older messages through the top sentinel and exposes pending status', async () => {
+    let notify!: IntersectionObserverCallback;
+    let complete!: () => void;
+    const observeSentinel = vi.fn();
+    const disconnect = vi.fn();
+    const action = vi.fn(
+      async () =>
+        new Promise<void>(resolve => {
+          complete = resolve;
+        }),
+    );
+    class Observer {
+      constructor(callback: IntersectionObserverCallback) {
+        notify = callback;
+      }
+      observe = observeSentinel;
+      disconnect = disconnect;
+    }
+    vi.stubGlobal('IntersectionObserver', Observer);
+    try {
+      const {unmount} = render(
+        <ChatMessageList scrollToTopAction={action}>
+          <div>Earlier message</div>
+        </ChatMessageList>,
+      );
+      expect(observeSentinel).toHaveBeenCalledTimes(1);
+      act(() => {
+        notify(
+          [{isIntersecting: false} as IntersectionObserverEntry],
+          {} as IntersectionObserver,
+        );
+      });
+      expect(action).not.toHaveBeenCalled();
+      act(() => {
+        notify(
+          [{isIntersecting: true} as IntersectionObserverEntry],
+          {} as IntersectionObserver,
+        );
+      });
+      expect(action).toHaveBeenCalledTimes(1);
+      expect(screen.getByRole('status', {name: 'Loading'})).toBeTruthy();
+      await act(async () => complete());
+      expect(screen.queryByRole('status', {name: 'Loading'})).toBeNull();
+      unmount();
+      expect(disconnect).toHaveBeenCalledTimes(1);
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
 });

package/src/Chat/ChatMessageList.tsx

@@ -4,7 +4,8 @@
 
 /**
  * @file ChatMessageList.tsx
- * @input Uses React, StyleX, ChatListContext, theme tokens, spacing step utilities
+ * @input Uses React, StyleX, ChatListContext, theme tokens, spacing step utilities,
+ *   and isRenderable to preserve accepted empty-state content
  * @output Exports ChatMessageList component and ChatMessageListProps
  * @position Presentational message container — holds ChatMessage children
  *
@@ -31,7 +32,7 @@ import {
   type ChatDensity,
   useChatLayoutContext,
 } from './ChatContext';
-import {mergeProps} from '../utils';
+import {isRenderable, mergeProps} from '../utils';
 import {Spinner} from '../Spinner';
 import type {BaseProps} from '../BaseProps';
 import type {SpacingStep} from '../utils/types';
@@ -321,7 +322,7 @@ export function ChatMessageList({
           {/* Messages or empty state */}
           {hasChildren ? (
             children
-          ) : emptyState ? (
+          ) : isRenderable(emptyState) ? (
             <div {...stylex.props(styles.emptyState)}>{emptyState}</div>
           ) : null}
         </div>