@astryxdesign/core 0.7.5 → 0.7.6-canary.0135af4

package/src/Chat/ChatComposer.spec.md

@@ -1,13 +1,13 @@
 ---
 schema_version: 3
-template_version: 5
+template_version: 7
 kind: component
 id: component:ChatComposer
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-31
 owners: [cixzhang]
 review_triggers: [public-api, behavior, layout, theming, accessibility]
 verified_by:
@@ -47,15 +47,15 @@ system_specs:
 
 ## Contract at a glance
 
-| Area                    | Contract                                                                                                                                                                                                                      |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | No new API shape or default. The exported context submits its supplied value; the default disabled editor exposes its disabled state; and an explicitly shown Stop action remains operable while message editing is disabled. |
-| Behavior                | ChatComposer coordinates a controlled or uncontrolled draft, trims a submitted value, clears through the existing value channel, composes caller slots, and keeps the default send/stop action synchronized with context.     |
-| End-user impact         | Screen-reader users can identify the disabled editor, pointer and touch users can stop an interruptible response, and users of a custom editor send the draft that editor supplied instead of stale composer state.           |
-| Builder impact          | None. Existing props, defaults, exports, and slot shapes remain; custom inputs can rely on the published `onSubmit(value)` context operation.                                                                                 |
-| Compatibility/readiness | Patch-compatible corrections to released behavior. This observational draft is non-authoritative; body theming, BaseProps ownership, spacious density, and a stop state without `onStop` remain unresolved owner choices.     |
-| Review checks           | Reject ignored context submission arguments, a disabled state hidden from the default textbox, an ancestor that blocks an enabled Stop action, or any change that presents the open questions below as settled policy.        |
-| Governing rules         | `architecture:interaction-modality/INV4, INV7, INV9`; `architecture:public-component-api/INV5–INV6, INV9, INV12`; `architecture:component-theming-surface/INV4, INV6`; `spec:AST-020/FR1`; `spec:AST-029/DEC-4`.              |
+| Area                    | Contract                                                                                                                                                                                                                                                                                                |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `ChatComposer` with a controlled or uncontrolled draft (`value`, `onChange`), `onSubmit`, `placeholder`, `isDisabled`, `isStopShown`, `onStop`, `density`, `elevation`, `status`, `statusPosition`, the drawer, header, input, footer, and send slots, and BaseProps; the exported composition context. |
+| Behavior                | ChatComposer coordinates a controlled or uncontrolled draft, trims a submitted value, clears through the existing value channel, composes caller slots, and keeps the default send/stop action synchronized with context.                                                                               |
+| End-user impact         | Screen-reader users can identify the disabled editor, pointer and touch users can stop an interruptible response, and users of a custom editor send the draft that editor supplied instead of stale composer state.                                                                                     |
+| Builder impact          | None.                                                                                                                                                                                                                                                                                                   |
+| Compatibility/readiness | Records shipped behavior; no public change. Two implementation gaps are listed under Current-state impact; four owner questions stay open. Evidence still pending for parts of FR1, FR5–FR7, FR10, and PR1–PR2 (read from source; see the verification map).                                            |
+| Review checks           | Reject ignored context submission arguments, a disabled state hidden from the default textbox, an ancestor that blocks an enabled Stop action, or a change that settles an open question without its owner.                                                                                             |
+| Governing rules         | `architecture:interaction-modality/INV4, INV7, INV9`; `architecture:public-component-api/INV5–INV6, INV9, INV12`; `architecture:component-theming-surface/INV4, INV6`; `spec:AST-020/FR1`; `spec:AST-029/DEC-4`.                                                                                        |
 
 This table is a review projection; the body below is authoritative.
 
@@ -69,13 +69,25 @@ streaming state, validation policy, and the content placed in each slot.
 
 ## Compatibility and migration
 
-- Released default preserved: yes for ordinary editing, submission, layout, and visual defaults.
-- Compatibility class: patch-compatible behavioral correction; the public context operation now uses the value its caller supplies, and disabled-plus-stop restores the already enabled Stop path.
-- Controlled/uncontrolled behavior: unchanged; a successful submission still clears through `onChange` in controlled mode and local state otherwise.
-- Migration decision: `spec:AST-029/DEC-4`; each behavior correction was reproduced by a failing test before implementation changed.
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public change
+- Controlled/uncontrolled behavior: a successful submission clears through
+  `onChange` in controlled mode and local state otherwise
+- Migration decision: none
 
 Consumer migration instructions belong in consumer docs and release notes.
 
+## Current-state impact
+
+- **The public target does not reach the painted body.** The `chat-composer`
+  target sits on the outer frame, so a theme cannot select the body's elevation
+  and border. `architecture:component-theming-surface` INV4 puts each themable
+  part's paint on its target (FR7, OQ1).
+- **Styling inputs split across two elements.** `ref`, DOM props and events,
+  `className`, and `style` reach the outer frame while `xstyle` reaches the
+  painted body. `architecture:public-component-api` INV6 has styling inputs
+  compose on one element (FR10, OQ2).
+
 ## Ownership boundary
 
 **Owns**
@@ -101,31 +113,28 @@ Consumer migration instructions belong in consumer docs and release notes.
 | Submission              | input submit; default send; custom context `onSubmit(value)` | Delivers one trimmed, non-empty supplied value and clears the draft through the current channel. | Enabled composer with a non-empty supplied value | no submission               | `component:ChatComposer`            | stable    | Empty values and submissions while disabled are ignored.                      |
 | Input composition       | default ChatComposerInput; custom React node                 | Supplies the editing surface and optional registered focus control.                              | Every ChatComposer                               | ChatComposerInput           | `component:ChatComposer`            | stable    | A custom input without a registered control gets textarea focus fallback.     |
 | Editing availability    | enabled; disabled                                            | Controls whether the draft can be edited or submitted.                                           | Every ChatComposer                               | enabled                     | `component:ChatComposer`            | stable    | Disabled submission is ignored.                                               |
-| Primary action          | send; stop                                                   | Sends the current draft or requests interruption.                                                | Default ChatSendButton or a custom sendButton    | send                        | `component:ChatComposer`            | stable    | A shown Stop action without `onStop` is currently rendered but inert.         |
+| Primary action          | send; stop                                                   | Sends the current draft or requests interruption.                                                | Default ChatSendButton or a custom sendButton    | send                        | `component:ChatComposer`            | stable    | A shown Stop action without `onStop` renders but does nothing (OQ4).          |
 | Density                 | compact; balanced; spacious                                  | Selects composer spacing.                                                                        | Every ChatComposer                               | balanced                    | `component:ChatComposer`            | stable    | Unknown values are rejected by TypeScript.                                    |
 | Elevation               | low; none                                                    | Selects a raised body or a flat bordered body.                                                   | Every ChatComposer                               | low                         | `component:ChatComposer`            | stable    | Unknown values are rejected by TypeScript.                                    |
 | Status                  | absent; error; warning; top; bottom                          | Adds announced feedback before or after the body.                                                | Optional status object                           | absent; bottom when present | `component:ChatComposer`            | stable    | An omitted message renders the bar and announces nothing.                     |
 | Named composition slots | drawer; header actions/context; input; footer/send actions   | Lets callers compose supporting controls and information around the draft.                       | Optional, independently supplied                 | omitted                     | `component:ChatComposer`            | stable    | Omitted slot groups emit no empty header; footer remains for the send action. |
-| BaseProps surface       | ref; DOM props/events; className/style; xstyle               | Extends the component with DOM identity, behavior, and styling.                                  | Every ChatComposer                               | omitted                     | `architecture:public-component-api` | stable    | These surfaces currently have split root/body ownership; see OQ2.             |
+| BaseProps surface       | ref; DOM props/events; className/style; xstyle               | Extends the component with DOM identity, behavior, and styling.                                  | Every ChatComposer                               | omitted                     | `architecture:public-component-api` | stable    | Split between the frame and the body (FR10, OQ2).                             |
 
 ## 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  | Controlled mode MUST report changes through `onChange`; uncontrolled mode MUST retain them locally. Every successful submit MUST trim and deliver the value supplied to that operation, then clear through the same value channel.                                                                                                                                 | public types and docs; `architecture:public-component-api/INV3, INV9, INV12`; focused tests           | settled            |
-| FR2  | The default editor MUST serialize its current text/tokens, submit Enter without Shift, preserve Shift+Enter, defer during IME composition, and allow a caller key handler to prevent the default operation.                                                                                                                                                        | implementation, docs, and focused tests                                                               | verify             |
-| FR3  | `isDisabled` MUST prevent draft edits and submissions and MUST expose `aria-disabled="true"` on the default textbox; removing the prop MUST remove that state.                                                                                                                                                                                                     | `spec:AST-020/FR1` (WCAG 2.2 4.1.2); `architecture:interaction-modality/INV5`; red/green focused test | settled            |
-| FR4  | When `isStopShown` is true, the default primary action MUST remain an enabled, named Stop button and call `onStop`; if editing is also disabled, ancestor styling MUST NOT block its pointer, touch, or keyboard activation.                                                                                                                                       | `architecture:interaction-modality/INV4, INV7, INV9`; red/green focused and browser-story tests       | settled            |
-| FR5  | Omitted header slots MUST omit the header row; the drawer precedes the body; input fills the body between header and footer; footer actions precede send actions and the primary action; status follows `statusPosition`.                                                                                                                                          | implementation, props, stories, and blocks                                                            | verify             |
-| FR6  | Compact currently reduces body padding and gap. Balanced and spacious currently use the same body spacing. Whether spacious needs distinct output MUST remain unresolved until a component/design owner decides it.                                                                                                                                                | implementation and published union; no current owner selects distinct spacious geometry               | human decision     |
-| FR7  | `low` currently applies low rest and medium hover/focus-within elevation; `none` applies no shadow and a border. Public theme reachability MUST cover the painting body or the public target/model MUST change through an approved compatibility path.                                                                                                             | implementation; `architecture:component-theming-surface/INV4, INV6`; existing public issue            | human decision     |
-| FR8  | Keyboard focus entering the registered/default editor MUST add the shared focus indication to the body; pointer focus MUST not add that extra ring. Clicking non-interactive body space MUST focus the registered control, then a textarea fallback.                                                                                                               | implementation; `architecture:interaction-modality/INV1–INV3, INV9`; focused tests                    | verify             |
-| FR9  | Error status is announced assertively and warning status politely through the shared announcement channel, once per occasion: one state transition, which a rerender or an update to the same value does not repeat (`spec:AST-086` FR6); the status bar itself carries no live role. Both pair a semantic icon with color and can render above or below the body. | implementation, docs, and stories; `spec:AST-020/FR1`; `spec:AST-086/FR2, FR5, FR6`                   | verify             |
-| FR10 | BaseProps currently split across elements: ref, DOM props/events, `className`, and `style` reach the outer frame while `xstyle` reaches the painted body. The owning element MUST remain unresolved pending compatibility review.                                                                                                                                  | implementation; `architecture:public-component-api/INV5–INV6, INV8`                                   | human decision     |
-| FR11 | The exported context MUST expose the current value, change and submit operations, placeholder, disabled/stop/send state, stop callback, and mutable input focus control to custom composition.                                                                                                                                                                     | public export, types, docs, stories, and focused tests; `architecture:public-component-api/INV12`     | verify             |
+| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                          | Basis                                                                                                                                    |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1  | Controlled mode MUST report changes through `onChange`; uncontrolled mode MUST retain them locally. Every successful submit MUST trim and deliver the value supplied to that operation, then clear through the same value channel.                                                                                                                                 | public types and docs; `architecture:public-component-api/INV3, INV9, INV12`; focused tests                                              |
+| FR2  | The default editor MUST serialize its current text/tokens, submit Enter without Shift, preserve Shift+Enter, defer during IME composition, and allow a caller key handler to prevent the default operation.                                                                                                                                                        | implementation, docs, and focused tests                                                                                                  |
+| FR3  | `isDisabled` MUST prevent draft edits and submissions and MUST expose `aria-disabled="true"` on the default textbox; removing the prop MUST remove that state.                                                                                                                                                                                                     | `spec:AST-020/FR1` (WCAG 2.2 4.1.2); `architecture:interaction-modality/INV5`; red/green focused test                                    |
+| FR4  | When `isStopShown` is true, the default primary action MUST remain an enabled, named Stop button and call `onStop`; if editing is also disabled, ancestor styling MUST NOT block its pointer, touch, or keyboard activation.                                                                                                                                       | `architecture:interaction-modality/INV4, INV7, INV9`; red/green focused and browser-story tests                                          |
+| FR5  | Omitted header slots MUST omit the header row; the drawer precedes the body; input fills the body between header and footer; footer actions precede send actions and the primary action; status follows `statusPosition`.                                                                                                                                          | implementation, props, stories, and blocks                                                                                               |
+| FR6  | `compact` reduces body padding and gap; `balanced` and `spacious` produce the same body spacing. Whether `spacious` should differ is open (OQ3).                                                                                                                                                                                                                   | implementation and published union; no current owner selects distinct spacious geometry                                                  |
+| FR7  | `low` applies low rest and medium hover and focus-within elevation; `none` applies no shadow and a border. Implementation gap: the public target does not reach the painted body (Current-state impact; OQ1).                                                                                                                                                      | implementation; `architecture:component-theming-surface/INV4, INV6`; the `chat-composer` target sits on the frame (Current-state impact) |
+| FR8  | Keyboard focus entering the registered/default editor MUST add the shared focus indication to the body; pointer focus MUST not add that extra ring. Clicking non-interactive body space MUST focus the registered control, then a textarea fallback.                                                                                                               | implementation; `architecture:interaction-modality/INV1–INV3, INV9`; focused tests                                                       |
+| FR9  | Error status is announced assertively and warning status politely through the shared announcement channel, once per occasion: one state transition, which a rerender or an update to the same value does not repeat (`spec:AST-086` FR6); the status bar itself carries no live role. Both pair a semantic icon with color and can render above or below the body. | implementation, docs, and stories; `spec:AST-020/FR1`; `spec:AST-086/FR2, FR5, FR6`                                                      |
+| FR10 | `ref`, DOM props and events, `className`, and `style` reach the outer frame; `xstyle` reaches the painted body. Implementation gap: the styling inputs split across two elements (Current-state impact; OQ2).                                                                                                                                                      | implementation; `architecture:public-component-api/INV5–INV6, INV8`                                                                      |
+| FR11 | The exported context MUST expose the current value, change and submit operations, placeholder, disabled/stop/send state, stop callback, and mutable input focus control to custom composition.                                                                                                                                                                     | public export, types, docs, stories, and focused tests; `architecture:public-component-api/INV12`                                        |
 
 ### Allowed variation
 
@@ -157,7 +166,7 @@ intentional decision. A `current` contract contains no unresolved rows.
 ### Performance and resources
 
 - **PR1 — Context stability.** The exported context value SHOULD retain referential stability while none of its public members changes.
-- **PR2 — Focus coordination.** The component MUST NOT add document listeners or observers to implement body-click focus or modality-specific focus indication.
+- **PR2 — Focus coordination.** The component adds no document listener or observer of its own for body-click focus or focus indication; it mounts the shared interaction-modality tracker, which adds document-level `pointerdown` and `keydown` listeners (`architecture:interaction-modality`).
 
 ## Accessibility contract
 
@@ -171,19 +180,18 @@ intentional decision. A `current` contract contains no unresolved rows.
 
 | Anatomy or state    | Design requirement                                                  | Representation authority                                                                                   | Hierarchy role | Component contract |
 | ------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------- | ------------------ |
-| Composer frame      | Groups body and optional status into one compositional shell.       | observed implementation                                                                                    | container      | FR5                |
+| Composer frame      | Groups body and optional status into one compositional shell.       | Current source                                                                                             | container      | FR5                |
 | Composer body       | Provides the painted rounded input/action surface and elevation.    | elevation is shipped; public theme reachability is unsettled                                               | prominent      | FR7                |
 | Drawer              | Places attachment/context content before the body.                  | delegated to `component:ChatComposerDrawer`                                                                | supporting     | FR5                |
-| Header              | Places caller actions at start and caller context at end.           | observed implementation                                                                                    | supporting     | FR5                |
+| Header              | Places caller actions at start and caller context at end.           | Current source                                                                                             | supporting     | FR5                |
 | Input               | Owns or hosts the editing surface and its focus control.            | delegated to `component:ChatComposerInput` or caller custom input                                          | prominent      | FR1–FR3, FR8, FR11 |
-| Footer              | Places caller actions and the primary action on the final body row. | observed implementation                                                                                    | supporting     | FR4–FR5            |
+| Footer              | Places caller actions and the primary action on the final body row. | Current source                                                                                             | supporting     | FR4–FR5            |
 | Send or stop action | Presents the current primary operation.                             | delegated to `component:ChatSendButton` or caller custom send button                                       | prominent      | FR1, FR4           |
 | Status message      | Adds error or warning feedback before or after the body.            | shared-channel announcement and color are shipped; separate public theme reachability is not asserted here | supporting     | FR5, FR9, AR5      |
 
-The aggregate Chat record currently owns the public `chat-composer` target. That
-target sits on the frame and cannot select the body's non-inherited elevation and
-border properties. This draft records the reachability gap without opting into a
-machine theming map, selecting a new target name, or moving the released target.
+The public `chat-composer` target sits on the frame and cannot select the body's
+elevation and border (Current-state impact). No anatomy-theming map is recorded
+yet; the block is optional during migration, so the map is deferred.
 
 ## Family and system relationships
 
@@ -193,29 +201,37 @@ machine theming map, selecting a new target name, or moving the released target.
 - `architecture:component-theming-surface` owns the anatomy-to-target disposition and makes the current body reachability mismatch blocking without deciding its repair shape.
 - `architecture:component-test-sufficiency` owns public-state partitions, negative assertions, observable output, and the exact-head browser boundary.
 - `architecture:react-component-runtime` owns render-derived state and browser/server boundaries.
-- `architecture:knowledge-contracts` keeps consumer syntax in `ChatComposer.doc.mjs` and observed system behavior in this draft.
+- `architecture:knowledge-contracts` keeps consumer syntax in `ChatComposer.doc.mjs` and system behavior in this record.
 - `spec:AST-020/FR1` carries the current WCAG 2.2 accessibility baseline.
-- `spec:AST-029/DEC-4` owns red-before-green behavior remediation; the broader Night Watch contract owns this observational backfill, finite evidence inventory, and fail-closed readiness report.
+- `spec:AST-029` owns the audit evidence inventory this record's verification map follows.
 
 ## Verification map
 
-| Contract     | Verification                                                                       | Representative states                                                          | Mutation or failure expectation                                                                                       | Audit section                       |
-| ------------ | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| FR1, FR11    | `ChatComposer.test.tsx`; `ChatSendButton.test.tsx`; custom-input stories           | controlled/uncontrolled, context-supplied value, default/custom send           | Ignoring the context argument submits stale state; default Send passes no draft; clearing skips the active channel.   | `audit:ChatComposer/api-behavior`   |
-| FR2          | `ChatComposerInput.test.tsx`                                                       | Enter, Shift+Enter, composing, cancelled keydown, text and token serialization | A key path sends during IME, loses newline behavior, bypasses caller cancellation, or emits the wrong string.         | `audit:ChatComposer/input-behavior` |
-| FR3          | red/green disabled-state assertion; focused input tests; exact-head axe            | disabled and re-enabled default textbox                                        | The textbox loses its ARIA state, remains editable, or accepts a disabled submit.                                     | `audit:ChatComposer/accessibility`  |
-| FR4          | red/green pointer assertion; disabled-streaming Storybook play; exact-head test-ui | enabled send, shown Stop, disabled-plus-shown Stop                             | An ancestor blocks pointer hit-testing, Stop becomes native-disabled, or `onStop` does not fire.                      | `audit:ChatComposer/modality`       |
-| FR5, FR9     | ChatComposer stories, CLI block examples, production Storybook build               | omitted/full slots, attachments, top/bottom status, error/warning              | Slot order changes, an empty header appears, or status semantics and placement disagree.                              | `audit:ChatComposer/composition`    |
-| FR6          | source and future owner-selected density comparison                                | compact, balanced, spacious                                                    | The audit invents distinct spacious styling without authority or silently changes one public density.                 | `audit:ChatComposer/design-gap`     |
-| FR7          | elevation focused test; flat story; current theming guards; owner review pending   | low rest/hover/focus, none, public target                                      | Elevation output disappears or the reachability gap is represented as solved without an approved target mapping.      | `audit:ChatComposer/theming`        |
-| FR8, AR4     | `ChatComposer.test.tsx`; exact-head browser/visual gates                           | keyboard, pointer, programmatic focus, internal action, body click             | Pointer focus gains the keyboard ring, editor keyboard focus loses it, or body click bypasses the registered control. | `audit:ChatComposer/focus`          |
-| FR10         | source/DOM ownership review; owner decision pending                                | ref, DOM props, className/style, xstyle                                        | A compatibility-affecting root/body move is made without deciding one public owner.                                   | `audit:ChatComposer/api-gap`        |
-| narrow state | disabled-streaming mobile Storybook fixture and exact-head test-ui                 | 320px viewport with default input and Stop                                     | The composer widens its viewport or the primary action becomes unreachable.                                           | `audit:ChatComposer/responsive`     |
+| Contract  | Verification                                                                                                                                                       | Representative states                                                           | Mutation or failure expectation                                                                          | Audit section                       |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| FR1, FR11 | `ChatComposer.test.tsx` input composition tests                                                                                                                    | context-supplied value, custom input reading value, change, and disabled        | A context submission that ignores its argument, or a context member a custom input cannot read, fails.   | `audit:ChatComposer/api-behavior`   |
+| FR2, AR3  | `ChatComposerInput.test.tsx`                                                                                                                                       | Enter, Shift+Enter, composing, cancelled keydown                                | A key path that sends during composition or loses a newline fails.                                       | `audit:ChatComposer/input-behavior` |
+| FR3, AR1  | `ChatComposer.test.tsx` "exposes disabled state on the default textbox and clears it when enabled"                                                                 | disabled and re-enabled default textbox                                         | A textbox that loses or keeps its disabled state wrongly fails.                                          | `audit:ChatComposer/accessibility`  |
+| FR4, AR2  | `ChatComposer.test.tsx` "keeps the Stop action pointer-operable while editing is disabled"; the `DisabledStreamingNarrow` story play in `ChatComposer.stories.tsx` | disabled editing with Stop shown; a narrow viewport with no horizontal overflow | A Stop action an ancestor blocks, or one that does not call `onStop`, fails.                             | `audit:ChatComposer/modality`       |
+| FR7       | `ChatComposer.test.tsx` elevation tests                                                                                                                            | `low` default, `none`                                                           | Levels that share a body class, or a default other than `low`, fail.                                     | `audit:ChatComposer/theming`        |
+| FR8, AR4  | `ChatComposer.test.tsx` focus indication tests and custom-input focus tests                                                                                        | keyboard, pointer, programmatic after each, internal button, body click         | A ring on pointer focus, a missing ring on keyboard focus, or a body click that skips the control fails. | `audit:ChatComposer/focus`          |
+| FR9, AR5  | `ChatComposer.test.tsx` status announcement tests                                                                                                                  | error, warning, StrictMode mount, repeat after clear, no message, page load     | A live role on the bar, a repeated or missing announcement, or the wrong urgency fails.                  | `audit:ChatComposer/accessibility`  |
+
+Read from source, with no focused test yet:
+
+- FR1: controlled and uncontrolled draft storage, trimming, rejecting an empty
+  or disabled submission, and clearing through the active channel.
+- FR5: slot order, the omitted header row, and status placement above or below
+  the body.
+- FR6: the density spacing.
+- FR7: the shadow and border values for each elevation.
+- FR10: where each BaseProps input lands.
+- PR1–PR2: context stability, and no document listener or observer of the
+  component's own.
 
 ## Decision log
 
-None. This draft records shipped behavior plus corrections already required by
-current shared authority. It does not approve new ChatComposer policy.
+No component-local decision is recorded.
 
 ## Open questions
 

package/src/Chat/ChatComposer.tsx

@@ -54,11 +54,9 @@ import {ChatSendButton} from './ChatSendButton';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
 import {useAnnounceRenderedText} from '../hooks/useAnnounceRenderedText';
+import {useMergedRefs} from '../hooks/useMergedRefs';
 import {focusOutlineStyles} from '../utils/focusOutline.stylex';
-import {
-  getInteractionModality,
-  useInteractionModalityTracking,
-} from '../utils/interactionModality';
+import {useInteractionModalityTracking} from '../utils/interactionModality';
 
 // =============================================================================
 // Types
@@ -394,8 +392,6 @@ export function ChatComposer(props: ChatComposerProps) {
   const [internalValue, setInternalValue] = useState('');
   const [hasKeyboardEditorFocus, setHasKeyboardEditorFocus] = useState(false);
 
-  useInteractionModalityTracking();
-
   const isControlled = controlledValue !== undefined;
   const currentValue = isControlled ? controlledValue : internalValue;
 
@@ -424,6 +420,8 @@ export function ChatComposer(props: ChatComposerProps) {
   const canSend = currentValue.trim().length > 0 && !isDisabled;
 
   const bodyRef = useRef<HTMLDivElement>(null);
+  const {ref: modalityRef, readModality} = useInteractionModalityTracking();
+  const bodyComposedRef = useMergedRefs(bodyRef, modalityRef);
 
   // Input slot registers its focus (and future) control here so the shell can
   // drive it without knowing its DOM shape. Stable ref — safe in the memoized
@@ -458,11 +456,10 @@ export function ChatComposer(props: ChatComposerProps) {
   const handleBodyFocusCapture = useCallback(
     (event: FocusEvent<HTMLDivElement>) => {
       setHasKeyboardEditorFocus(
-        isComposerEditor(event.target) &&
-          getInteractionModality() === 'keyboard',
+        isComposerEditor(event.target) && readModality() === 'keyboard',
       );
     },
-    [],
+    [readModality],
   );
 
   const handleBodyBlurCapture = useCallback(
@@ -550,7 +547,7 @@ export function ChatComposer(props: ChatComposerProps) {
         {drawer}
 
         <div
-          ref={bodyRef}
+          ref={bodyComposedRef}
           onClick={handleBodyClick}
           onPointerDownCapture={() => setHasKeyboardEditorFocus(false)}
           onFocusCapture={handleBodyFocusCapture}

package/src/Chat/ChatComposerTokenElement.spec.md

@@ -1,13 +1,13 @@
 ---
 schema_version: 3
-template_version: 5
+template_version: 7
 kind: component
 id: component:ChatComposerTokenElement
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-31
 owners: [cixzhang]
 review_triggers: [public-api, behavior, accessibility, theming, testing]
 verified_by:
@@ -33,15 +33,15 @@ system_specs: [spec:AST-002, spec:AST-029]
 
 ## Contract at a glance
 
-| Area                    | Contract                                                                                                                                                                                      |
-| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | No token shape, default, or rendering change. The public props type and existing span passthrough are directly reachable from the Chat package path.                                          |
-| Behavior                | A structured token renders Badge content; a custom token renders caller content. Both retain the serialized value marker and stay non-editable when placed inside a contenteditable composer. |
-| End-user impact         | Token labels and caller content remain visible without becoming editable text.                                                                                                                |
-| Builder impact          | Builders can type the existing component props and attach neutral span attributes, styles, and a ref without recreating its contract.                                                         |
-| Compatibility/readiness | Additive patch-compatible contract repair. This observational record adds no token meaning or visual policy.                                                                                  |
-| Review checks           | Reject a token wrapper that loses its serialized value, becomes editable, drops accepted span props, or changes the structured/custom rendering split.                                        |
-| Governing rules         | `architecture:public-component-api/INV1, INV5–INV6, INV8–INV9, INV12`; `architecture:component-test-sufficiency/INV1–INV8, INV10–INV11`; `spec:AST-029/FR3–FR5, FR7`.                         |
+| Area                    | Contract                                                                                                                                                                                                                                                                                  |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `ChatComposerTokenElement` with a required `token`: structured, which is `value` plus Badge props, of which only `label`, `variant`, and `icon` render and the rest are accepted and ignored; or custom `{value, render}`, `ref`, `xstyle`, `className`, `style`, and neutral span props. |
+| Behavior                | A structured token renders Badge content; a custom token renders caller content. Both retain the serialized value marker and stay non-editable when placed inside a contenteditable composer.                                                                                             |
+| End-user impact         | Token labels and caller content remain visible without becoming editable text.                                                                                                                                                                                                            |
+| Builder impact          | None.                                                                                                                                                                                                                                                                                     |
+| Compatibility/readiness | Records shipped behavior; no public change. Evidence still pending for AR1 and parts of FR1, FR2, and FR4 (read from source; see the verification map).                                                                                                                                   |
+| Review checks           | Reject a token wrapper that loses its serialized value, becomes editable, drops accepted span props, or changes the structured/custom rendering split.                                                                                                                                    |
+| Governing rules         | `architecture:public-component-api/INV1, INV5–INV6, INV8–INV9, INV12`; `architecture:component-test-sufficiency/INV1–INV8, INV10–INV11`; `spec:AST-029/FR3–FR5, FR7`.                                                                                                                     |
 
 This table is a review projection; the body below is authoritative.
 
@@ -54,11 +54,13 @@ their existing owners.
 
 ## Compatibility and migration
 
-- Released default preserved: yes
-- Compatibility class: additive props-type and DOM-passthrough repair
-- Token values and rendering branches: unchanged
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public change
+- Controlled/uncontrolled behavior: not applicable
 - Migration decision: none
 
+Consumer migration instructions belong in consumer docs and release notes.
+
 ## Ownership boundary
 
 **Owns**
@@ -85,12 +87,12 @@ their existing owners.
 
 ## Behavioral and layout contract
 
-| ID  | Candidate invariant                                                                                                                                                        | Basis                                                                | Draft review state |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------ |
-| FR1 | The root MUST expose `data-astryx-token` and the exact supplied `token.value`, and MUST remain `contentEditable={false}`.                                                  | shipped implementation, public docs, ChatComposerInput serialization | verify             |
-| FR2 | Structured tokens MUST delegate label, variant, and icon rendering to Badge without changing the token value.                                                              | shipped implementation and public token type                         | verify             |
-| FR3 | Custom tokens MUST render the caller function result without adding component-owned semantics or interaction.                                                              | shipped implementation and public token type                         | verify             |
-| FR4 | Accepted ref, DOM/data/ARIA, className, style, and xstyle inputs MUST reach and compose on the root span while component-owned serialization attributes retain precedence. | `architecture:public-component-api/INV5–INV6, INV8`                  | settled            |
+| ID  | Invariant                                                                                                                                                                  | Basis                                               |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| FR1 | The root MUST expose `data-astryx-token` and the exact supplied `token.value`, and MUST remain `contentEditable={false}`.                                                  | Current source, docs, and tests                     |
+| FR2 | Structured tokens MUST delegate label, variant, and icon rendering to Badge without changing the token value.                                                              | shipped implementation and public token type        |
+| FR3 | Custom tokens MUST render the caller function result without adding component-owned semantics or interaction.                                                              | shipped implementation and public token type        |
+| FR4 | Accepted ref, DOM/data/ARIA, className, style, and xstyle inputs MUST reach and compose on the root span while component-owned serialization attributes retain precedence. | `architecture:public-component-api/INV5–INV6, INV8` |
 
 ### Allowed variation
 
@@ -108,15 +110,18 @@ their existing owners.
 
 ## Accessibility contract
 
-- The wrapper owns no interactive role or accessible name beyond accepted caller props.
-- Structured Badge text remains visible content; custom content semantics remain caller owned.
-- `contentEditable={false}` keeps the token atomically non-editable when nested in an editor.
+- **AR1 — No owned semantics.** The wrapper owns no interactive role or
+  accessible name beyond accepted caller props.
+- **AR2 — Visible content.** Structured Badge text remains visible content;
+  custom content semantics remain caller owned.
+- **AR3 — Atomic token.** `contentEditable={false}` keeps the token atomically
+  non-editable when nested in an editor.
 
 ## Design relationships
 
 | Anatomy or state   | Design requirement        | Representation authority | Hierarchy role | Component contract |
 | ------------------ | ------------------------- | ------------------------ | -------------- | ------------------ |
-| token wrapper      | Inline alignment only     | observed implementation  | supporting     | FR1, FR4           |
+| token wrapper      | Inline alignment only     | Current source           | supporting     | FR1, FR4           |
 | structured content | Badge presentation        | `component:Badge`        | supporting     | FR2                |
 | custom content     | caller-owned presentation | caller                   | supporting     | FR3                |
 
@@ -128,19 +133,26 @@ target. Badge theming remains owned by Badge, and custom content remains caller
 - `component:ChatComposerInput` owns insertion, serialization traversal, deletion, and selection behavior.
 - `architecture:public-component-api` owns the public props type, ref, and BaseProps composition.
 - `architecture:component-test-sufficiency` owns direct evidence for the established public serialization seam.
-- `spec:AST-029` owns this observational audit backfill and its finite evidence inventory.
+- `spec:AST-029` owns the audit evidence inventory this record's verification map follows.
 
 ## Verification map
 
-| Contract        | Verification                                                       | Representative states                        | Mutation or failure expectation                                                                 | Audit section                             |
-| --------------- | ------------------------------------------------------------------ | -------------------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------- |
-| FR1–FR3         | `ChatComposerTokenElement.test.tsx`; direct Storybook stories      | structured and custom tokens                 | A marker/value disappears, the wrapper becomes editable, or the wrong rendering branch appears. | `audit:ChatComposerTokenElement/behavior` |
-| FR4             | focused ref and DOM-passthrough test; public typecheck             | ref, ARIA/data props, styling seams          | An accepted input is dropped or an owned serialization marker is replaced.                      | `audit:ChatComposerTokenElement/api`      |
-| rendered states | direct Storybook stories and exact-head visual/accessibility gates | Badge and custom content in supported themes | A story is unreachable or introduces an accessibility/visual regression.                        | `audit:ChatComposerTokenElement/rendered` |
+| Contract         | Verification                                                  | Representative states                        | Mutation or failure expectation                                                                 | Audit section                             |
+| ---------------- | ------------------------------------------------------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| FR1–FR3, AR2–AR3 | `ChatComposerTokenElement.test.tsx`; direct Storybook stories | structured and custom tokens                 | A marker/value disappears, the wrapper becomes editable, or the wrong rendering branch appears. | `audit:ChatComposerTokenElement/behavior` |
+| FR4              | focused ref and DOM-passthrough test; public typecheck        | ref, ARIA/data props, styling seams          | An accepted input is dropped or an owned serialization marker is replaced.                      | `audit:ChatComposerTokenElement/api`      |
+| rendered states  | direct Storybook stories                                      | Badge and custom content in supported themes | An unreachable story fails the story checks.                                                    | `audit:ChatComposerTokenElement/rendered` |
+
+Read from source, with no focused test yet:
+
+- AR1: the wrapper adding no role or accessible name of its own.
+- FR1: `contentEditable` staying `false` when a caller passes it.
+- FR2: `variant` and `icon` reaching the Badge.
+- FR4: `className`, `style`, and `xstyle` composing on the span.
 
 ## Decision log
 
-No component-local policy decision is created by this observational draft.
+No component-local decision is recorded.
 
 ## Open questions