@astryxdesign/core 0.6.2 → 0.6.3-canary.01fa439

package/src/Chat/ChatComposerInput.tsx

@@ -18,6 +18,10 @@
  *
  *
  * SYNC: When modified, update:
+ * - /packages/core/src/Chat/ChatComposerInput.test.tsx
+ * - /packages/core/src/Chat/ChatComposerInput.doc.mjs
+ * - /packages/core/src/Chat/ChatComposerInput.spec.md
+ * - /apps/storybook/stories/ChatComposerInput.stories.tsx
  * - /packages/core/src/Chat/index.ts
  * - /apps/storybook/stories/ChatComposer.stories.tsx
  * - /packages/cli/assets/templates/blocks/components/ChatComposerInput/ (block examples)
@@ -32,6 +36,7 @@ import {
   type ReactNode,
   type KeyboardEvent,
   type ClipboardEvent,
+  type DragEvent,
 } from 'react';
 import {createPortal} from 'react-dom';
 import type {BaseProps} from '../BaseProps';
@@ -109,6 +114,13 @@ export type ChatComposerTokenCustom = {
 export type ChatComposerToken =
   ChatComposerTokenBadge | ChatComposerTokenCustom;
 
+export interface ChatComposerTokenElementProps extends BaseProps<HTMLSpanElement> {
+  /** Ref forwarded to the token wrapper. */
+  ref?: React.Ref<HTMLSpanElement>;
+  /** Token rendered as a Badge or by its custom render function. */
+  token: ChatComposerToken;
+}
+
 export type ChatComposerTriggerItem = SearchableItem;
 
 export type ChatComposerTrigger = {
@@ -233,9 +245,14 @@ const styles = stylex.create({
     whiteSpace: 'pre-wrap',
     wordBreak: 'break-word',
     overflowY: 'auto',
+    // The 16px floor is iOS-only: iOS Safari zooms the page when a focused
+    // control sits under 16px, and only iOS WebKit implements
+    // -webkit-touch-callout to key the coarse-pointer floor to it.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: `${LINE_HEIGHT_PX}px`,
     fontFamily: typographyVars['--font-family-body'],
@@ -250,9 +267,12 @@ const styles = stylex.create({
     insetInlineEnd: 0,
     pointerEvents: 'none',
     color: colorVars['--color-text-secondary'],
+    // Same iOS-only floor as the editable region it stands in for.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: `${LINE_HEIGHT_PX}px`,
     fontFamily: typographyVars['--font-family-body'],
@@ -508,6 +528,7 @@ export function ChatComposerInput(props: ChatComposerInputProps) {
   }, [controlledValue]);
 
   const cleanupPortalsRef = useRef<(() => void) | null>(null);
+  const emitChangeVersionRef = useRef(0);
 
   const emitChange = useCallback(() => {
     if (!editableRef.current) {
@@ -524,6 +545,7 @@ export function ChatComposerInput(props: ChatComposerInputProps) {
     const nextValue = trimmedEmpty ? '' : text;
     pendingEchoValueRef.current = nextValue;
     setIsEmpty(trimmedEmpty);
+    emitChangeVersionRef.current += 1;
     onChange?.(nextValue);
     cleanupPortalsRef.current?.();
   }, [onChange]);
@@ -542,7 +564,7 @@ export function ChatComposerInput(props: ChatComposerInputProps) {
       ? null
       : (pasteAsTokenProp ?? defaultPasteAsToken);
 
-  const insertText = useCallback((text: string) => {
+  const insertTextWithoutEmit = useCallback((text: string) => {
     const editable = editableRef.current;
     if (!editable) {
       return;
@@ -550,6 +572,14 @@ export function ChatComposerInput(props: ChatComposerInputProps) {
     insertTextAtCursor(editable, text);
   }, []);
 
+  const insertText = useCallback(
+    (text: string) => {
+      insertTextWithoutEmit(text);
+      emitChange();
+    },
+    [emitChange, insertTextWithoutEmit],
+  );
+
   // Keep stable refs in sync for imperative handle
   insertTokenRef.current = tokens.insertToken;
   insertTextRef.current = insertText;
@@ -559,7 +589,7 @@ export function ChatComposerInput(props: ChatComposerInputProps) {
     triggers,
     editableRef,
     onInsertToken: tokens.insertToken,
-    onInsertText: insertText,
+    onInsertText: insertTextWithoutEmit,
     onEmitChange: emitChange,
     debounceMs,
   });
@@ -750,15 +780,21 @@ export function ChatComposerInput(props: ChatComposerInputProps) {
       e.preventDefault();
       const text = e.clipboardData.getData('text/plain');
 
-      // Paste-as-token: convert long pastes to token chips
-      if (pasteAsToken?.onPaste(e, text)) {
-        emitChange();
+      // Consumer onPaste gets first refusal over plain text. Return true after
+      // handling it so the built-in insertion paths do not run. A consumer may
+      // use the observable imperative handle while handling the event; emit only
+      // if that path did not already publish the change.
+      const versionBeforeConsumer = emitChangeVersionRef.current;
+      const handled = onPasteProp?.(e, text);
+      if (handled) {
+        if (emitChangeVersionRef.current === versionBeforeConsumer) {
+          emitChange();
+        }
         return;
       }
 
-      // Consumer onPaste — return true to prevent default text insert
-      const handled = onPasteProp?.(e, text);
-      if (handled) {
+      // Paste-as-token: convert long pastes to token chips.
+      if (pasteAsToken?.onPaste(e, text)) {
         emitChange();
         return;
       }
@@ -769,6 +805,28 @@ export function ChatComposerInput(props: ChatComposerInputProps) {
     [onFiles, onPasteProp, emitChange, tokens, pasteAsToken],
   );
 
+  const handleDragOver = useCallback((e: DragEvent<HTMLDivElement>) => {
+    if (Array.from(e.dataTransfer.types).includes('Files')) {
+      e.preventDefault();
+    }
+  }, []);
+
+  const handleDrop = useCallback(
+    (e: DragEvent<HTMLDivElement>) => {
+      const files = Array.from(e.dataTransfer.files);
+      if (files.length === 0) {
+        return;
+      }
+      // File drops navigate the page by default. The input owns that drop
+      // target even when no callback is supplied, so keep the user in place.
+      e.preventDefault();
+      if (!isDisabled) {
+        onFiles?.(files);
+      }
+    },
+    [isDisabled, onFiles],
+  );
+
   const maxHeight = maxRows * LINE_HEIGHT_PX;
 
   return (
@@ -794,7 +852,10 @@ export function ChatComposerInput(props: ChatComposerInputProps) {
         onInput={handleInput}
         onKeyDown={handleKeyDown}
         onPaste={handlePaste}
+        onDragOver={handleDragOver}
+        onDrop={handleDrop}
         {...triggerMenu.ariaProps}
+        aria-disabled={isDisabled || undefined}
         {...mergeProps(stylex.props(styles.editable), {
           style: {maxHeight: `${maxHeight}px`},
         })}
@@ -834,13 +895,17 @@ ChatComposerInput.displayName = 'ChatComposerInput';
 // Token element helper (for custom rendering in stories/consumers)
 // =============================================================================
 
-export function ChatComposerTokenElement({token}: {token: ChatComposerToken}) {
+export function ChatComposerTokenElement(props: ChatComposerTokenElementProps) {
+  const {token, ref, xstyle, className, style, ...rest} = props;
+
   return (
     <span
+      ref={ref}
+      {...mergeProps(stylex.props(styles.tokenSpan, xstyle), className, style)}
+      {...rest}
       data-astryx-token=""
       data-astryx-token-value={token.value}
-      contentEditable={false}
-      {...stylex.props(styles.tokenSpan)}>
+      contentEditable={false}>
       {isCustomToken(token) ? (
         token.render()
       ) : (

package/src/Chat/ChatComposerTokenElement.spec.md

@@ -0,0 +1,152 @@
+---
+schema_version: 3
+template_version: 5
+kind: component
+id: component:ChatComposerTokenElement
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [public-api, behavior, accessibility, theming, testing]
+verified_by:
+  [
+    packages/core/src/Chat/ChatComposerTokenElement.test.tsx,
+    apps/storybook/stories/ChatComposerTokenElement.stories.tsx,
+    apps/storybook/rtl-audit/verified-not-applicable.json,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [
+    architecture:public-component-api,
+    architecture:component-test-sufficiency,
+    architecture:knowledge-contracts,
+  ]
+contributing: []
+system_specs: [spec:AST-002, spec:AST-029]
+---
+
+# ChatComposerTokenElement component contract
+
+## 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`.                         |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+ChatComposerTokenElement renders one already-defined `ChatComposerToken` outside the
+editor insertion machinery. It supplies the same serialization marker used by
+ChatComposerInput while leaving structured Badge presentation or custom content to
+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
+- Migration decision: none
+
+## Ownership boundary
+
+**Owns**
+
+- The span carrying `data-astryx-token` and the token's serialized value.
+- Keeping that wrapper non-editable when composed inside a contenteditable region.
+- Choosing the existing structured Badge or custom-render branch.
+- Forwarding the wrapper ref and accepted neutral span props.
+
+**Does not own / non-goals**
+
+- Token value grammar or product semantics.
+- Badge colors, iconography, or sizing.
+- Accessibility semantics and interaction behavior inside caller custom content.
+- Token insertion, deletion, expansion, or composer selection management.
+
+## Public concepts
+
+| Concept          | Closed values or states                          | Meaning                                                               | Default        | Owner                                | Stability |
+| ---------------- | ------------------------------------------------ | --------------------------------------------------------------------- | -------------- | ------------------------------------ | --------- |
+| token form       | structured Badge config; custom render function  | Selects caller content without changing serialization.                | none; required | `component:ChatComposerTokenElement` | stable    |
+| serialized value | non-empty or empty string supplied by caller     | Value stored in `data-astryx-token-value` for composer serialization. | none; required | caller value through this component  | stable    |
+| wrapper surface  | ref; DOM/data/ARIA props; className/style/xstyle | Extends the serialization span without replacing owned markers.       | omitted        | `architecture:public-component-api`  | stable    |
+
+## 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            |
+
+### Allowed variation
+
+- Structured Badge labels, variants, and icons remain caller supplied.
+- Custom rendered content and its semantics remain caller owned.
+- The wrapper may be used inside or outside a contenteditable surface.
+
+### Representative states
+
+| State            | Required invariant                                                        | Allowed variation               |
+| ---------------- | ------------------------------------------------------------------------- | ------------------------------- |
+| structured token | Visible Badge content and exact serialized value.                         | Badge label, variant, and icon. |
+| custom token     | Caller output and exact serialized value.                                 | Any caller-owned React node.    |
+| extended wrapper | Neutral DOM props and ref reach the span without replacing owned markers. | Supported BaseProps values.     |
+
+## 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.
+
+## Design relationships
+
+| Anatomy or state   | Design requirement        | Representation authority | Hierarchy role | Component contract |
+| ------------------ | ------------------------- | ------------------------ | -------------- | ------------------ |
+| token wrapper      | Inline alignment only     | observed implementation  | supporting     | FR1, FR4           |
+| structured content | Badge presentation        | `component:Badge`        | supporting     | FR2                |
+| custom content     | caller-owned presentation | caller                   | supporting     | FR3                |
+
+The wrapper does not paint a component-owned visual surface or introduce a public theme
+target. Badge theming remains owned by Badge, and custom content remains caller owned.
+
+## Family and system relationships
+
+- `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.
+
+## 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` |
+
+## Decision log
+
+No component-local policy decision is created by this observational draft.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer examples, current audit scores, Badge policy, or
+ChatComposerInput selection mechanics.

package/src/Chat/ChatComposerTokenElement.test.tsx

@@ -0,0 +1,85 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ChatComposerTokenElement.test.tsx
+ * @input Public Chat token element and props contract
+ * @output Verifies serialization markers, rendering modes, and DOM passthrough
+ * @position Public contract tests for @astryxdesign/core/Chat
+ */
+
+import {render, screen} from '@testing-library/react';
+import {describe, expect, expectTypeOf, it} from 'vitest';
+import {
+  ChatComposerTokenElement,
+  type ChatComposerTokenElementProps,
+} from '@astryxdesign/core/Chat';
+
+describe('ChatComposerTokenElement', () => {
+  it('renders a structured token with its serialized value', () => {
+    render(
+      <ChatComposerTokenElement
+        token={{value: '@ada', label: 'Ada', variant: 'blue'}}
+        data-testid="token"
+      />,
+    );
+
+    const token = screen.getByTestId('token');
+    expect(token).toHaveAttribute('data-astryx-token', '');
+    expect(token).toHaveAttribute('data-astryx-token-value', '@ada');
+    expect(token).toHaveAttribute('contenteditable', 'false');
+    expect(token).toHaveTextContent('Ada');
+  });
+
+  it('renders caller-owned custom token content', () => {
+    render(
+      <ChatComposerTokenElement
+        token={{
+          value: '#design',
+          render: () => <strong>Design</strong>,
+        }}
+      />,
+    );
+
+    expect(screen.getByText('Design').tagName).toBe('STRONG');
+  });
+
+  it('forwards the span ref and neutral DOM props', () => {
+    const ref = {current: null as HTMLSpanElement | null};
+    render(
+      <ChatComposerTokenElement
+        ref={ref}
+        token={{value: '@ada', label: 'Ada'}}
+        aria-label="Mention Ada"
+      />,
+    );
+
+    expect(ref.current).toBeInstanceOf(HTMLSpanElement);
+    expect(ref.current).toHaveAttribute('aria-label', 'Mention Ada');
+  });
+
+  it('keeps component-owned serialization markers authoritative', () => {
+    const conflictingMarkers = {
+      'data-astryx-token': 'consumer-value',
+      'data-astryx-token-value': 'wrong-value',
+    };
+
+    render(
+      <ChatComposerTokenElement
+        {...conflictingMarkers}
+        token={{value: '@ada', label: 'Ada'}}
+        data-testid="token"
+      />,
+    );
+
+    const token = screen.getByTestId('token');
+    expect(token).toHaveAttribute('data-astryx-token', '');
+    expect(token).toHaveAttribute('data-astryx-token-value', '@ada');
+  });
+
+  it('publishes the span props contract', () => {
+    expectTypeOf<ChatComposerTokenElementProps>().toMatchTypeOf<{
+      token: {value: string};
+      ref?: React.Ref<HTMLSpanElement>;
+    }>();
+  });
+});

package/src/Chat/ChatDictationButton.doc.mjs

@@ -47,7 +47,7 @@ export const docs = {
       name: 'isHiddenWhenUnsupported',
       type: 'boolean',
       description:
-        'When true, renders nothing if the browser does not support SpeechRecognition.',
+        'When true, renders nothing if the browser does not support SpeechRecognition. When false, keeps the button visible but disabled.',
       default: 'true',
     },
     {
@@ -81,7 +81,7 @@ export const docsZh = {
   propDescriptions: {
     dictation: 'The return value from useChatDictation or useSpeechRecognition. Controls all button state.',
     size: 'Button size.',
-    isHiddenWhenUnsupported: 'When true, renders nothing if SpeechRecognition is unsupported.',
+    isHiddenWhenUnsupported: 'When true, hides unsupported dictation; when false, keeps a disabled button visible.',
     label: 'Accessible label override.',
     xstyle: 'Additional StyleX styles.',
   },
@@ -104,7 +104,7 @@ export const docsDense = {
   propDescriptions: {
     dictation: 'return from useChatDictation/useSpeechRecognition; controls state',
     size: 'btn size',
-    isHiddenWhenUnsupported: 'hide when SpeechRecognition unsupported',
+    isHiddenWhenUnsupported: 'hide unsupported dictation; false keeps disabled btn visible',
     label: 'a11y label override',
     xstyle: 'extra StyleX styles',
   },

package/src/Chat/ChatDictationButton.spec.md

@@ -0,0 +1,160 @@
+---
+schema_version: 3
+template_version: 5
+kind: component
+id: component:ChatDictationButton
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [public-api, behavior, accessibility, theming, testing]
+verified_by:
+  [
+    packages/core/src/Chat/ChatDictationButton.test.tsx,
+    apps/storybook/stories/ChatDictation.stories.tsx,
+    apps/storybook/rtl-audit/verified-not-applicable.json,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [
+    architecture:public-component-api,
+    architecture:component-style-authoring,
+    architecture:theme-tokens,
+    architecture:component-test-sufficiency,
+    architecture:knowledge-contracts,
+  ]
+contributing: []
+system_specs: [spec:AST-029]
+---
+
+# ChatDictationButton component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                           |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Public contract         | `dictation` supplies support, listening, volume, bands, and toggle state; `size`, `label`, root span props, styles, and ref remain additive inputs.                                                                |
+| Behavior                | The idle button shows the microphone action. Listening replaces the icon with five volume-reactive bars. Unsupported dictation is hidden by default or disabled when explicitly retained.                          |
+| End-user impact         | Voice input remains operable and labelled; unsupported browsers do not expose an action that cannot run.                                                                                                           |
+| Builder impact          | Builders can place the control in ChatComposer send actions and safely customize its root layout without owning speech state.                                                                                      |
+| Compatibility/readiness | Patch-compatible repair: existing supported behavior is unchanged; the opt-in unsupported-visible state becomes accurately disabled.                                                                               |
+| Review checks           | Reject an enabled unsupported action, a missing listening label, raw theme-inaccessible clipping color, or lost root passthrough.                                                                                  |
+| Governing rules         | `architecture:component-style-authoring/INV1–INV3`; `architecture:theme-tokens/INV3`; `architecture:public-component-api/INV1, INV5–INV6, INV8`; `architecture:component-test-sufficiency/INV1–INV8, INV10–INV11`. |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+ChatDictationButton renders the visible control for an existing speech-recognition
+state owner. It translates that owner's support and listening states into one
+icon-only Button and a direction-neutral equalizer visualization.
+
+## Compatibility and migration
+
+- Released default preserved: yes
+- Compatibility class: behavioral bug fix for the explicit unsupported-visible state
+- Supported idle and listening states: unchanged
+- Migration decision: none
+
+## Ownership boundary
+
+**Owns**
+
+- The start/stop accessible label and optional caller label override.
+- Hidden-versus-disabled presentation when speech recognition is unsupported.
+- The five-bar visual projection of supplied band and volume values.
+- Theme-aware accent-to-error clipping feedback.
+- Root span ref and accepted neutral span props.
+
+**Does not own / non-goals**
+
+- Speech recognition support detection, lifecycle, transcripts, or errors.
+- Microphone permission UX or audio capture.
+- ChatComposer placement beyond documented composition guidance.
+- A public color, threshold, or equalizer-shape axis.
+
+## Public concepts
+
+| Concept      | Closed values or states                            | Meaning                                                       | Default                     | Owner                                    | Stability |
+| ------------ | -------------------------------------------------- | ------------------------------------------------------------- | --------------------------- | ---------------------------------------- | --------- |
+| support      | supported; unsupported-hidden; unsupported-visible | Determines whether the control can render and operate.        | unsupported-hidden          | speech owner projected by this component | stable    |
+| listening    | idle; listening                                    | Selects the start/stop label and microphone/equalizer visual. | idle                        | `dictation`                              | stable    |
+| size         | `sm`; `md`                                         | Sizes the Button and equalizer geometry together.             | `md`                        | component                                | stable    |
+| label        | translated default; caller override                | Names the action for assistive technology.                    | state-dependent translation | component/caller                         | stable    |
+| root surface | ref; DOM/data/ARIA props; className/style/xstyle   | Extends the positioning wrapper.                              | omitted                     | public component API                     | stable    |
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                                      | Basis                                                 | Draft review state |
+| --- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------- | ------------------ |
+| FR1 | Supported idle state MUST expose an enabled Button named by the start label and invoke `dictation.toggle` on activation. | shipped API and Button contract                       | verify             |
+| FR2 | Supported listening state MUST expose the stop label and five aria-hidden visualizer bars derived from `bands`.          | shipped implementation and docs                       | verify             |
+| FR3 | Unsupported state MUST render nothing by default. If explicitly retained, its Button MUST be disabled.                   | public option plus operability/accessibility repair   | settled            |
+| FR4 | Clipping feedback MUST derive from portable semantic color tokens so a consumer theme can retint both endpoints.         | `architecture:theme-tokens/INV3` and lint enforcement | settled            |
+| FR5 | Accepted ref, DOM/data/ARIA, className, style, and xstyle inputs MUST reach and compose on the root span.                | `architecture:public-component-api`                   | settled            |
+
+### Allowed variation
+
+- Callers may replace the translated start/stop label with `label`.
+- Band amplitudes and clipping strength vary with the supplied dictation owner.
+- Consumer themes may change the accent and error colors used by the bars.
+
+## Accessibility contract
+
+- The nested Button owns keyboard and pointer activation, focus, and disabled semantics.
+- The equalizer is decorative and MUST remain hidden from the accessibility tree.
+- The visible control MUST have a state-appropriate accessible label.
+- An unsupported visible control MUST communicate disabled state and MUST NOT activate.
+- Reduced-motion preference removes the equalizer's transition duration.
+
+## Design relationships
+
+- Idle uses the shared microphone Icon through Button.
+- Listening bars begin at `--color-accent` and blend toward `--color-error` as clipping increases.
+- The component adds no portable token or public theme target.
+- Equalizer dimensions remain private component geometry.
+
+## Responsive and bidirectional behavior
+
+The control has fixed `sm` and `md` sizes and no viewport-owned behavior. Its
+microphone glyph, centered bars, and block-axis scale are direction-neutral; the
+verified-N/A ledger records this with source evidence.
+
+## Family and system relationships
+
+- ChatComposer owns placement through its `sendActions` slot.
+- Button owns activation, focus, disabled semantics, hit target, and icon-only presentation.
+- Icon owns the microphone glyph.
+- `useChatDictation` and `useSpeechRecognition` own speech lifecycle and state.
+- Theme token architecture owns the accent and error semantic roles.
+
+## Verification map
+
+| Contract                | Evidence                                                              |
+| ----------------------- | --------------------------------------------------------------------- |
+| FR1, labels, activation | `ChatDictationButton.test.tsx` idle activation and custom-label cases |
+| FR2                     | listening structure test and Listening/Speaking stories               |
+| FR3                     | unsupported hidden and visible-disabled tests/stories                 |
+| FR4                     | clipping semantic-color test, lint, and Clipping story                |
+| FR5                     | typed ref and root-passthrough test                                   |
+| rendered states         | exact-head Storybook, a11y, and visual CI                             |
+| RTL N/A                 | `apps/storybook/rtl-audit/verified-not-applicable.json`               |
+
+## Decision log
+
+| Decision                                                                           | Reason                                                                                    | Authority                                  |
+| ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------ |
+| Keep unsupported dictation hidden by default and disabled when explicitly visible. | An unavailable action must not present as operable.                                       | objective accessibility/operability repair |
+| Blend portable accent and error tokens for clipping.                               | Preserves the existing progressive clipping cue while keeping both endpoints theme-owned. | `architecture:theme-tokens/INV3`           |
+
+## Open questions
+
+None for this repair.
+
+## Content boundary
+
+Labels may be translated defaults or caller overrides. The component does not own transcript text, permission errors, microphone instructions, or product-specific voice-input guidance.