@astryxdesign/core 0.6.2 → 0.6.3-canary.039a67e

package/src/Chat/ChatTokenizedText.spec.md

@@ -0,0 +1,190 @@
+---
+schema_version: 3
+template_version: 6
+kind: component
+id: component:ChatTokenizedText
+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/ChatTokenizedText.test.tsx,
+    packages/core/src/Chat/__tests__/ChatTokenizedText.a11y.chromium.spec.ts,
+    apps/storybook/stories/ChatTokenizedText.stories.tsx,
+    apps/storybook/rtl-audit/verified-not-applicable.json,
+    packages/core/src/theme/themingTargets.test.ts,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [
+    architecture:public-component-api,
+    architecture:component-theming-surface,
+    architecture:component-test-sufficiency,
+    architecture:react-component-runtime,
+    architecture:theme-tokens,
+    architecture:knowledge-contracts,
+  ]
+contributing: []
+system_specs: [spec:AST-002, spec:AST-020, spec:AST-029]
+---
+
+# ChatTokenizedText component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                       |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | The exported component accepts required plain-text children, optional composer token definitions, and supported root span props and ref. No prop, export, or theme target is added or removed. |
+| Behavior                | Unmatched text is preserved. Non-empty token values match literally from left to right. Structured tokens delegate to Badge and custom tokens to callers.                                      |
+| End-user impact         | Tokenized messages finish rendering when a caller-supplied token definition has an empty serialized value.                                                                                     |
+| Builder impact          | Existing token arrays keep working, and empty serialized values are safely ignored instead of creating a non-advancing match.                                                                  |
+| Compatibility/readiness | Patch-compatible correctness repair and observational documentation. The pending inline-alignment change remains owned by its separate pull request.                                           |
+| Review checks           | Reject zero-width matching, lost unmatched text, execution of custom renderers without a match, dropped root inputs, or claims about caller-owned content.                                     |
+| Governing rules         | `architecture:public-component-api/INV1, INV5–INV6, INV8–INV9`; `architecture:component-test-sufficiency/INV1–INV7`; `spec:AST-029/FR3–FR7`; ECMAScript RegExp progress semantics.             |
+
+This table is a review projection. The draft body records verified current or
+remediated behavior and creates no new token grammar or visual policy.
+
+## Intent
+
+ChatTokenizedText projects serialized token values embedded in a plain chat message
+into inline structured Badge content or caller-rendered content while preserving the
+surrounding text.
+
+## Compatibility and migration
+
+- Released default preserved: yes; messages without matching non-empty tokens remain plain text.
+- Compatibility class: patch-compatible correctness repair for invalid zero-width matches.
+- Controlled/uncontrolled behavior: not applicable; the component owns no state.
+- Migration decision: none. No public type, prop, export, default, or theme target changes.
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- Literal matching of serialized token values against the supplied message text.
+- Preserving unmatched text and source order.
+- Choosing the existing structured Badge or custom-render branch for each match.
+- The root span, its `chat-tokenized-text` target, accepted BaseProps composition, and ref.
+
+**Does not own / non-goals**
+
+- Token value grammar, identity, validation, or product semantics.
+- Badge color, iconography, sizing, or accessibility semantics.
+- Semantics and interaction inside caller-provided custom token content.
+- Composer insertion, serialization, deletion, selection, or token-element alignment.
+- The inline-alignment change proposed independently in pull request #6418.
+
+## Public concepts
+
+| Concept      | Closed values or states                         | Meaning                                                                   | Availability by variant/orientation/state | Default  | Owner                               | Stability                 | Invalid-value behavior               |
+| ------------ | ----------------------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------- | -------- | ----------------------------------- | ------------------------- | ------------------------------------ |
+| Message text | any string                                      | Plain text whose literal token values may be projected inline.            | Every render                              | required | `component:ChatTokenizedText`       | released observed surface | Empty text renders an empty span.    |
+| Token set    | omitted; empty; non-empty                       | Candidate serialized values and their structured or custom presentations. | Every render                              | omitted  | caller and component                | released observed surface | Empty token values are ignored.      |
+| Token form   | structured Badge config; custom render function | Selects delegated Badge content or caller-rendered content.               | Matching non-empty values                 | none     | caller and delegated component      | released observed surface | Type-invalid forms are rejected.     |
+| Root surface | ref; supported DOM/data/ARIA/class/style/xstyle | Extends the inline root without replacing its owned target.               | Every render                              | omitted  | `architecture:public-component-api` | released observed surface | Unsupported inputs stay unsupported. |
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                                                                             | Basis                                                                          | Draft review state      |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ----------------------- |
+| FR1 | The component MUST preserve unmatched text exactly and replace each matched non-empty serialized value at its original reading-order position.                  | Released consumer docs and implementation                                      | verified                |
+| FR2 | Empty token values MUST be ignored so the renderer always makes progress and never enters a zero-width global-match loop.                                       | Objective ECMAScript RegExp progress semantics and responsive rendering        | remediated and verified |
+| FR3 | Structured matches MUST delegate label, variant, and icon rendering to Badge; custom matches MUST invoke the caller renderer only for an actual match.          | Released token type, source, docs, and tests                                   | verified                |
+| FR4 | Supported ref, DOM/data/ARIA, className, style, and xstyle inputs MUST reach or compose on the root span while the `chat-tokenized-text` target remains intact. | `architecture:public-component-api/INV5–INV6, INV8`                            | verified                |
+| FR5 | The component MUST remain render-only, with no state, Effect, listener, observer, timer, or owned asynchronous resource.                                        | Current source and `architecture:component-test-sufficiency` evidence boundary | verified                |
+
+### Allowed variation
+
+- **AV1 — Caller tokens.** Labels, variants, icons, custom content, and serialized values remain caller supplied.
+- **AV2 — Caller styling.** Supported root styling inputs may extend the component without replacing its public target.
+- **AV3 — Unmatched input.** Text with no matching non-empty value remains unchanged.
+
+### Representative states
+
+| State                | Required invariant                                                      | Allowed variation                     |
+| -------------------- | ----------------------------------------------------------------------- | ------------------------------------- |
+| Plain text           | Exact text remains visible.                                             | Any string content.                   |
+| Structured match     | Matching text is replaced by delegated Badge content.                   | Label, variant, and icon.             |
+| Custom match         | Matching text is replaced by caller-rendered content.                   | Any caller-owned React node.          |
+| Repeated match       | Every occurrence is replaced in reading order.                          | Number and position of occurrences.   |
+| Empty token value    | The value is ignored and rendering terminates with text preserved.      | Presence beside valid tokens.         |
+| Narrow / RTL context | Inline content remains readable and follows surrounding text direction. | Theme, direction, and message length. |
+
+### Transformation and precedence order
+
+- **ORD1 — Normalize candidates.** Remove empty serialized values while preserving caller order.
+- **ORD2 — Match literally.** Escape values for RegExp syntax and scan the message from left to right.
+- **ORD3 — Render.** Preserve unmatched slices and delegate each matched token to Badge or the caller renderer.
+- **ORD4 — Compose root.** Apply the component target and styles, then combine accepted consumer styling and root props.
+
+### Performance and resources
+
+- **PR1 — Finite progress.** Every successful match consumes at least one UTF-16 code unit; empty values cannot enter the matcher.
+- **PR2 — Render-only projection.** Matching allocates one candidate list, lookup map, and result list per render and owns no persistent resource.
+
+## Accessibility contract
+
+- **AR1 — Reading order.** Unmatched text and token content remain in source reading order inside one inline text wrapper.
+- **AR2 — Delegated content.** Structured token semantics remain owned by Badge; custom token semantics remain caller owned.
+- **AR3 — Noninteractive root.** The component introduces no role, focus target, keyboard command, pointer action, or live-region behavior.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                           | Representation authority         | Hierarchy role | Component contract |
+| ---------------- | -------------------------------------------- | -------------------------------- | -------------- | ------------------ |
+| Tokenized text   | Inline root preserves surrounding text flow. | Current source and released docs | supporting     | FR1, FR5           |
+| Rendered token   | Delegates paint to Badge or caller content.  | `component:Badge` or caller      | supporting     | FR4, AR2           |
+
+This observational draft does not choose new spacing, alignment, token paint,
+proportion, or state representation.
+
+### Theme ownership
+
+The Chat family document owns the shared anatomy and target inventory inherited by
+this subcomponent. The existing `chat-tokenized-text` target remains on the inline
+root. Structured token paint delegates to Badge, while custom rendered token content
+remains caller owned. This observational draft does not redefine the family map.
+
+## Family and system relationships
+
+- `component:Badge` owns structured token paint, variants, iconography, and label semantics.
+- `component:ChatComposerInput` owns token insertion, serialization, deletion, and composer selection behavior.
+- `architecture:public-component-api` owns released exports, BaseProps reachability, styling composition, and refs.
+- `architecture:component-theming-surface` owns the target/anatomy mapping.
+- `architecture:component-test-sufficiency` owns bounded, mutation-sensitive evidence.
+- `spec:AST-029` owns this observational audit backfill and closed evidence receipt.
+
+## Verification map
+
+| Contract       | Verification                                                   | Representative states                            | Mutation or failure expectation                                                           | Audit section                         |
+| -------------- | -------------------------------------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------- | ------------------------------------- |
+| FR1–FR3, PR1   | `ChatTokenizedText.test.tsx`                                   | plain, structured, custom, repeated, empty       | Lost text, zero-width nontermination, or the wrong render branch fails.                   | `audit:ChatTokenizedText/behavior`    |
+| FR4            | focused root passthrough/ref checks, theming target guard      | plain and tokenized roots                        | A supported root input or public target is dropped or replaced.                           | `audit:ChatTokenizedText/public-api`  |
+| FR5            | source inspection and strict lint                              | every render                                     | Hidden state or an owned external resource triggers runtime review.                       | `audit:ChatTokenizedText/code-health` |
+| RTL relation   | source-hashed verified-N/A record                              | all existing stories                             | Component-owned directional behavior invalidates the record.                              | `audit:ChatTokenizedText/i18n-rtl`    |
+| Browser matrix | Storybook stories, exact-head visual gate, and scoped a11y     | plain, multiple, mixed, edge, custom, narrow     | Missing text/token content, overflow, visual regression, or an a11y violation fails.      | `audit:ChatTokenizedText/rendered`    |
+| Docs / surface | docs, declarations, exports, `check:knowledge`, docs typecheck | public props, Chat subpath, target, draft record | Missing or stale docs, export, target map, or knowledge shape fails validation or review. | `audit:ChatTokenizedText/docs`        |
+
+## Decision log
+
+No component-local product decision is created by this observational draft. The
+matching repair follows the component's released promise to replace supplied literal
+token values while preserving surrounding text.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer examples, audit scores, screenshots, Badge
+policy, token grammar, or composer editing behavior.

package/src/Chat/ChatTokenizedText.test.tsx

@@ -1,6 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-import {describe, it, expect} from 'vitest';
+import {describe, it, expect, vi} from 'vitest';
+import {createRef} from 'react';
 import {render, screen} from '@testing-library/react';
 import {ChatTokenizedText} from './ChatTokenizedText';
 
@@ -79,6 +80,64 @@ describe('ChatTokenizedText', () => {
     expect(container.textContent).toContain('@Cindy Zhang');
   });
 
+  it('ignores empty token values instead of creating zero-width matches', () => {
+    render(
+      <ChatTokenizedText
+        tokens={[
+          {value: '', label: 'Empty'},
+          {value: '@alice', label: '@Alice'},
+        ]}>
+        Hello @alice
+      </ChatTokenizedText>,
+    );
+
+    expect(screen.getByText('@Alice')).toBeInTheDocument();
+    expect(screen.queryByText('Empty')).not.toBeInTheDocument();
+  });
+
+  it('renders plain text when every token value is empty', () => {
+    render(
+      <ChatTokenizedText
+        tokens={[
+          {value: '', label: 'First empty'},
+          {value: '', label: 'Second empty'},
+        ]}>
+        Hello world
+      </ChatTokenizedText>,
+    );
+
+    expect(screen.getByText('Hello world')).toBeInTheDocument();
+    expect(screen.queryByText('First empty')).not.toBeInTheDocument();
+    expect(screen.queryByText('Second empty')).not.toBeInTheDocument();
+  });
+
+  it('renders custom tokens only for actual matches', () => {
+    const renderCustom = vi.fn(() => <span>Custom token</span>);
+
+    const {rerender} = render(
+      <ChatTokenizedText tokens={[{value: '@custom', render: renderCustom}]}>
+        Hello @custom
+      </ChatTokenizedText>,
+    );
+    expect(screen.getByText('Custom token')).toBeInTheDocument();
+    expect(renderCustom).toHaveBeenCalledTimes(1);
+
+    rerender(
+      <ChatTokenizedText tokens={[{value: '@custom', render: renderCustom}]}>
+        Hello world
+      </ChatTokenizedText>,
+    );
+    expect(screen.queryByText('Custom token')).not.toBeInTheDocument();
+    expect(renderCustom).toHaveBeenCalledTimes(1);
+  });
+
+  it('forwards refs to the root span', () => {
+    const ref = createRef<HTMLSpanElement>();
+    render(<ChatTokenizedText ref={ref}>Plain text</ChatTokenizedText>);
+    expect(ref.current?.tagName).toBe('SPAN');
+    expect(ref.current?.textContent).toBe('Plain text');
+  });
+
   it('forwards rest props (data-*, id) to the root element', () => {
     render(
       <ChatTokenizedText data-testid="tokenized" data-custom="x" id="tok-1">

package/src/Chat/ChatTokenizedText.tsx

@@ -8,9 +8,9 @@
  * @output Exports ChatTokenizedText component
  * @position Utility component for rendering tokenized text in message bubbles
  *
- * Parses a plain text string and replaces token values with inline badges.
- * Accepts the same ChatComposerToken type used by the input triggers,
- * so the same token definitions work for both input and display.
+ * Parses a plain text string and replaces non-empty token values with inline
+ * token content. Accepts the same ChatComposerToken type used by the input
+ * triggers, so the same token definitions work for both input and display.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Chat/index.ts
@@ -51,8 +51,8 @@ export interface ChatTokenizedTextProps extends BaseProps<HTMLSpanElement> {
   children: string;
   /**
    * Token definitions — same type returned by trigger onSelect.
-   * Each token's `value` is matched against the text and replaced
-   * with its badge representation (label, variant, icon).
+   * Each non-empty token `value` is matched literally against the text and
+   * replaced with its Badge or custom representation. Empty values are ignored.
    *
    * @example
    * ```
@@ -88,7 +88,7 @@ function escapeRegExp(str: string): string {
 // =============================================================================
 
 /**
- * Renders text with token values replaced by inline badges.
+ * Renders text with token values replaced by inline token content.
  *
  * Accepts the same `ChatComposerToken` type used by input triggers,
  * so you can share a single token definition between input and display.
@@ -141,11 +141,17 @@ ChatTokenizedText.displayName = 'ChatTokenizedText';
 // =============================================================================
 
 function renderTokens(text: string, tokens: ChatComposerToken[]): ReactNode[] {
-  const pattern = tokens.map(t => escapeRegExp(t.value)).join('|');
+  const matchableTokens = tokens.filter(token => token.value.length > 0);
+
+  if (matchableTokens.length === 0) {
+    return [text];
+  }
+
+  const pattern = matchableTokens.map(t => escapeRegExp(t.value)).join('|');
   const regex = new RegExp(`(${pattern})`, 'g');
 
   const tokenMap = new Map<string, ChatComposerToken>();
-  for (const t of tokens) {
+  for (const t of matchableTokens) {
     tokenMap.set(t.value, t);
   }
 

package/src/Chat/ChatToolCalls.doc.mjs

@@ -16,6 +16,7 @@ export const docs = {
     bestPractices: [
       {guidance: true, description: 'Include a target string on every call so the user can see what the tool acted on: a file path, a shell command, or a search query.'},
       {guidance: true, description: 'Show a duration on completed calls so users can judge which tools are slow and understand why a response took time.'},
+      {guidance: true, description: 'Provide a group label when the automatic count does not explain what the calls represent.'},
       {guidance: true, description: 'Provide resultDetail with a code block for calls that produce output (diffs for edits, terminal output for shell commands) so users can inspect results inline.'},
       {guidance: true, description: 'Set a unique key on each call item when streaming so React can animate additions without re-mounting completed rows.'},
       {guidance: false, description: "Don't omit the status field. Without it the call defaults to complete, which is misleading for calls that are still running or have failed."},
@@ -54,7 +55,7 @@ export const docs = {
       name: 'label',
       type: 'string',
       description:
-        'Custom summary label for groups. Auto-generated from count if omitted.',
+        'Custom summary label shown for an expanded group. The translated call count is used when omitted.',
     },
     {
       name: 'isExpanded',
@@ -90,6 +91,7 @@ export const docsZh = {
     bestPractices: [
       {guidance: true, description: 'Include a target string on every call so the user can see what the tool acted on: a file path, a shell command, or a search query.'},
       {guidance: true, description: 'Show a duration on completed calls so users can judge which tools are slow and understand why a response took time.'},
+      {guidance: true, description: 'Provide a group label when the automatic count does not explain what the calls represent.'},
       {guidance: true, description: 'Provide resultDetail with a code block for calls that produce output (diffs for edits, terminal output for shell commands) so users can inspect results inline.'},
       {guidance: true, description: 'Set a unique key on each call item when streaming so React can animate additions without re-mounting completed rows.'},
       {guidance: false, description: "Don't omit the status field. Without it the call defaults to complete, which is misleading for calls that are still running or have failed."},
@@ -115,6 +117,7 @@ export const docsDense = {
     bestPractices: [
       {guidance: true, description: 'Include target on every call: file path, command, or search query.'},
       {guidance: true, description: 'Show duration on completed calls so users understand timing.'},
+      {guidance: true, description: 'Provide group label when count alone is ambiguous.'},
       {guidance: true, description: 'Provide resultDetail with code blocks for calls that produce output.'},
       {guidance: true, description: 'Set unique key on each call item when streaming for stable animations.'},
       {guidance: false, description: "Don't omit status; defaults to complete, misleading for running/failed calls."},

package/src/Chat/ChatToolCalls.spec.md

@@ -0,0 +1,194 @@
+---
+schema_version: 3
+template_version: 6
+kind: component
+id: component:ChatToolCalls
+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/ChatToolCalls.test.tsx,
+    apps/storybook/stories/ChatToolCalls.stories.tsx,
+    apps/storybook/rtl-audit/verified-not-applicable.json,
+    packages/core/src/theme/themingTargets.test.ts,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [
+    architecture:public-component-api,
+    architecture:component-theming-surface,
+    architecture:component-test-sufficiency,
+    architecture:react-component-runtime,
+    architecture:interaction-modality,
+    architecture:theme-tokens,
+    architecture:knowledge-contracts,
+  ]
+contributing: []
+system_specs: [spec:AST-009, spec:AST-029]
+---
+
+# ChatToolCalls component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                 |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | The exported component accepts a required call list, optional group label, controlled or uncontrolled expansion, a change callback, and supported root div props and ref.                |
+| Behavior                | No calls render nothing; one call renders directly; multiple calls expose a disclosure whose collapsed surface shows the latest call and whose expanded surface shows every call.        |
+| End-user impact         | Group labels appear as supplied, collapsed detail controls leave keyboard and accessibility navigation, and every disclosure has the shared visible focus treatment.                     |
+| Builder impact          | Existing calls keep their shape and defaults. Builders may rely on the released `label` prop and continue to omit it for the translated count.                                           |
+| Compatibility/readiness | Patch-compatible restoration of documented behavior and objective accessibility requirements. No prop, export, default, theme target, call ordering, or caller-content contract changes. |
+| Review checks           | Reject ignored labels, focusable descendants inside a collapsed group, lost keyboard activation, unreadable supporting text, dropped root inputs, or changed call ordering/defaults.     |
+| Governing rules         | `architecture:public-component-api/INV5–INV6, INV8–INV9`; `architecture:interaction-modality`; `spec:AST-009/FR7`; `spec:AST-029/FR3–FR7`; WCAG 2.2 SC 1.4.3 and 2.4.7.                  |
+
+This table is a review projection. The draft body records verified shipped or
+remediated behavior and creates no new tool-call protocol or visual policy.
+
+## Intent
+
+ChatToolCalls presents tool or function invocations inside an assistant message,
+including execution status, optional metadata, and inspectable result details.
+
+## Compatibility and migration
+
+- Released default preserved: yes; omitted status means complete and groups start collapsed unless `defaultIsExpanded` is true.
+- Compatibility class: patch-compatible correctness and accessibility repair.
+- Controlled/uncontrolled behavior: `isExpanded` remains authoritative when supplied; otherwise local state starts from `defaultIsExpanded ?? false`.
+- Migration decision: none. No public type, prop, export, default, or theme target changes.
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- Projection of ordered call data into single-call or grouped presentation.
+- Group and per-call disclosures, including keyboard operation and focus treatment.
+- Status, metadata, duration, statistics, and result-detail placement.
+- The root div, `chat-tool-calls` target, supported BaseProps composition, and ref.
+
+**Does not own / non-goals**
+
+- Tool execution, streaming transport, result parsing, or error recovery.
+- Semantics and interaction inside caller-provided `stats` or `resultDetail` content.
+- Badge, Icon, Spinner, or CodeBlock internals.
+- Product policy for which tool calls may be shown.
+
+## Public concepts
+
+| Concept       | Closed values or states                               | Meaning                                                      | Availability        | Default   | Owner                               | Stability                 | Invalid-value behavior               |
+| ------------- | ----------------------------------------------------- | ------------------------------------------------------------ | ------------------- | --------- | ----------------------------------- | ------------------------- | ------------------------------------ |
+| Call list     | empty; single; multiple                               | Selects absent, direct-row, or grouped presentation.         | Every render        | required  | `component:ChatToolCalls`           | released observed surface | Empty renders nothing.               |
+| Status        | pending; running; complete; error                     | Selects the visible and accessible execution state.          | Every call          | complete  | `component:ChatToolCalls`           | released observed surface | Type-invalid values reject.          |
+| Group label   | omitted; supplied string                              | Names an expanded group; omission uses the translated count. | Multiple calls      | omitted   | caller and component                | released observed surface | Supplied strings render verbatim.    |
+| Group state   | controlled; uncontrolled collapsed; uncontrolled open | Controls whether grouped rows are exposed.                   | Multiple calls      | collapsed | caller or component                 | released observed surface | Conflicting control is avoided.      |
+| Result detail | omitted; caller React node                            | Adds an independently operable per-call disclosure.          | Any call            | omitted   | caller and component                | released observed surface | Omitted content adds no control.     |
+| Root surface  | ref; supported DOM/data/ARIA/class/style/xstyle       | Extends the root without replacing its owned target.         | Non-empty call list | omitted   | `architecture:public-component-api` | released observed surface | Unsupported inputs stay unsupported. |
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                                                                                                                 | Basis                                                         | Draft review state       |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------ |
+| FR1 | An empty call list MUST render no root; one call MUST render directly; multiple calls MUST render one group disclosure and preserve caller order in its full list.                                  | Released implementation, docs, stories, and tests             | verified                 |
+| FR2 | A supplied `label` MUST replace the translated count on the expanded group surface; omission MUST retain the translated count fallback.                                                             | Released public prop and consumer docs; public API INV5, INV9 | remediated and verified  |
+| FR3 | A collapsed group MUST keep its descendant call disclosures out of keyboard and accessibility navigation; expansion MUST restore them.                                                              | HTML `inert`, disclosure semantics, WCAG operability          | remediated and verified  |
+| FR4 | Every component-owned disclosure MUST activate with Enter, Space, and pointer input, expose expansion state, and draw the shared keyboard focus ring.                                               | Current interaction-modality architecture and WCAG 2.4.7      | remediated and verified  |
+| FR5 | Neutral supporting labels, targets, durations, and custom statistics MUST use the readable secondary foreground; signed addition/deletion counts retain their released semantic colors pending OQ2. | WCAG 2.2 SC 1.4.3 and current token architecture              | partial remediation; OQ2 |
+| FR6 | Supported root ref, DOM/data/ARIA, className, style, and xstyle inputs MUST reach or compose on the root while the public target remains intact.                                                    | `architecture:public-component-api/INV5–INV6, INV8`           | verified                 |
+
+### Allowed variation
+
+- **AV1 — Call content.** Tool names, targets, node names, durations, statistics, error messages, and result details remain caller supplied.
+- **AV2 — Group control.** Callers may control expansion or supply only its initial uncontrolled value.
+- **AV3 — Styling.** Supported root styling inputs may extend the component without replacing its public target.
+
+### Representative states
+
+| State                | Required invariant                                                                                      | Allowed variation                                                                   |
+| -------------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| Empty                | No root is rendered.                                                                                    | Empty array identity may vary.                                                      |
+| Single               | One row appears without group chrome.                                                                   | Metadata and result detail may be absent.                                           |
+| Multiple, collapsed  | Latest call and count appear; full rows are inert.                                                      | Call count and latest status may vary.                                              |
+| Multiple, expanded   | Every call appears in source order; supplied label or translated count names the group.                 | Label text and row metadata may vary.                                               |
+| Detail closed/open   | The row exposes its state and conditionally mounts the caller-owned detail.                             | Any caller React node.                                                              |
+| Statuses             | All statuses expose translated accessible text; complete and error also retain distinct semantic marks. | Theme may change semantic artwork; pending and running share a spinner pending OQ1. |
+| Narrow / RTL context | Rows truncate without horizontal overflow and follow logical inline direction.                          | Content length, theme, and direction.                                               |
+
+### Transformation and precedence order
+
+- **ORD1 — Choose presentation.** Empty, single, and grouped branches are selected from list length.
+- **ORD2 — Resolve state.** Controlled expansion wins; otherwise local state starts from the initial default.
+- **ORD3 — Resolve label.** A supplied group label wins; otherwise use the translated count.
+- **ORD4 — Compose rows.** Preserve call order, render status and metadata, then add caller-owned detail disclosure where present.
+- **ORD5 — Compose root.** Apply the component target and styles, then combine supported consumer inputs.
+
+### Performance and resources
+
+- **PR1 — Local state only.** The component owns disclosure state and no Effect, listener, observer, timer, or external resource.
+- **PR2 — Linear projection.** Group rendering traverses the supplied call list once and does not mutate caller data.
+
+## Accessibility contract
+
+- **AR1 — Disclosure operation.** Group and detail disclosures expose `aria-expanded`, operate with pointer, Enter, and Space, and use the shared visible focus ring.
+- **AR2 — Collapsed ownership.** Collapsed group content is inert; hidden detail content is unmounted.
+- **AR3 — Status meaning.** Every status exposes translated visually hidden text. Complete and error also use distinct semantic marks; pending and running currently share the same subtle spinner (OQ1). Error messages are exposed to assistive technology and echoed in the status icon's hover tooltip.
+- **AR4 — Static evidence.** Focus appearance, keyboard behavior, inertness, color contrast, and DOM relationships use unit, axe, and real-browser evidence under `spec:AST-009/FR7`; this audit makes no AT-announcement claim.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                                                             | Representation authority          | Hierarchy role | Component contract |
+| ---------------- | ---------------------------------------------------------------------------------------------- | --------------------------------- | -------------- | ------------------ |
+| Call row         | Compact inline status and metadata remain legible.                                             | Current source and WCAG contrast  | supporting     | FR5, AR3           |
+| Disclosure       | Keyboard focus remains visible without changing layout.                                        | Current interaction architecture  | supporting     | FR4, AR1           |
+| Status           | Translated hidden text preserves accessible meaning; complete and error retain semantic marks. | Current source and objective a11y | supporting     | FR5, AR3           |
+
+This observational draft does not choose new spacing, density, iconography,
+proportion, status vocabulary, or motion.
+
+### Theme ownership
+
+The existing `chat-tool-calls` target remains on the root. Badge, Icon, and Spinner
+own their nested targets and paint. This observational draft does not add a public
+theme target or redefine inherited Chat-family anatomy.
+
+## Family and system relationships
+
+- `architecture:public-component-api` owns released exports, accepted inputs, styling composition, and refs.
+- `architecture:component-theming-surface` owns the target and delegated anatomy contract.
+- `architecture:interaction-modality` owns shared keyboard focus treatment.
+- `architecture:component-test-sufficiency` owns bounded, mutation-sensitive evidence.
+- `spec:AST-009` assigns these static semantics, keyboard, focus, and contrast claims to lower evidence layers rather than real AT.
+- `spec:AST-029` owns this observational audit backfill and closed evidence receipt.
+
+## Verification map
+
+| Contract         | Verification                                                                  | Representative states                                                | Mutation or failure expectation                                                        | Audit section                       |
+| ---------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------- |
+| FR1–FR4, AR1–AR2 | `ChatToolCalls.test.tsx`                                                      | empty, single, grouped, label, disclosures                           | Ignored label, wrong state, operable collapsed row, or missing ring fails.             | `audit:ChatToolCalls/behavior`      |
+| FR5, AR3–AR4     | scoped Chromium axe plus existing-baseline visual comparisons                 | neutral metadata in light mode; existing visual states in light/dark | Reintroducing disabled-text contrast fails; semantic stats remain baselined under OQ2. | `audit:ChatToolCalls/accessibility` |
+| FR6              | focused root passthrough/ref checks and theming target guard                  | single root                                                          | A supported input, ref, or public target is dropped or replaced.                       | `audit:ChatToolCalls/public-api`    |
+| RTL relation     | source-hashed verified-N/A record                                             | all checked-in stories                                               | Component-owned directional behavior invalidates the record.                           | `audit:ChatToolCalls/i18n-rtl`      |
+| Browser matrix   | existing visual baselines, scoped a11y, and required real-browser play guards | grouped focus and 320px narrow overflow; existing light/dark states  | Missing focus, overflow, visual regressions, or new a11y violations fail.              | `audit:ChatToolCalls/rendered`      |
+| Docs / surface   | docs, declarations, exports, knowledge check, docs typecheck                  | public props, Chat subpath, draft record                             | Missing or stale docs, export, target, or knowledge shape fails.                       | `audit:ChatToolCalls/docs`          |
+
+## Decision log
+
+No component-local product decision is created by this observational draft. The
+repairs restore released API behavior and objective accessibility requirements.
+
+## Open questions
+
+- **OQ1 — Pending/running visual distinction.** Pending and running currently render the same subtle spinner and differ only in translated accessible text. Which approved visible treatment should distinguish them without inventing component-local status policy?
+- **OQ2 — Semantic statistics contrast.** The released success/error foreground tokens for signed `+N`/`-N` statistics do not reach 4.5:1 in every shipped light/dark surface. Which system-level semantic text token should replace them while preserving addition/deletion meaning? The five affected axe baselines remain until that owner decision lands.
+
+## Content boundary
+
+This file does not duplicate consumer examples, audit scores, screenshots, tool
+execution policy, or delegated component contracts.