@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/Chat/ChatComposerInput.spec.md

@@ -1,224 +0,0 @@
----
-schema_version: 3
-template_version: 5
-kind: component
-id: component:ChatComposerInput
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-14
-owners: [cixzhang]
-review_triggers: [public-api, behavior, accessibility, interaction, theming]
-verified_by:
-  [
-    packages/core/src/Chat/ChatComposerInput.test.tsx,
-    apps/storybook/stories/ChatComposerInput.stories.tsx,
-    apps/storybook/rtl-audit/verified-not-applicable.json,
-  ]
-modules: []
-families: []
-design_specs: []
-architecture:
-  [
-    architecture:interaction-modality,
-    architecture:public-component-api,
-    architecture:knowledge-contracts,
-  ]
-contributing: []
-system_specs: [spec:AST-002, spec:AST-029]
----
-
-# ChatComposerInput component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Public contract         | ChatComposerInput remains the optional rich editing surface for ChatComposer, with controlled draft, trigger, history, paste, file, and imperative seams. Each trigger definition may opt into multi-word queries with `hasMultiWordQuery`, default `false`.                                                                                                                                                                         |
-| Behavior                | Every edit path keeps the serialized draft observable. Files pasted or dropped reach `onFiles`; consumer `onPaste` receives first refusal over plain text before optional paste-as-token conversion.                                                                                                                                                                                                                                 |
-| End-user impact         | Dictated or otherwise programmatically inserted text is sendable and never hidden behind the empty placeholder; dropped files reach the product attachment flow.                                                                                                                                                                                                                                                                     |
-| Builder impact          | Existing props, callback signatures, prop defaults, exports, and token serialization are unchanged. Builders relying on the documented `onPaste` and `onFiles` paths receive those callbacks except where FR5 and FR6 record implementation gaps; `hasMultiWordQuery` is the one added optional trigger field. Every trigger receives the trigger-key corrections listed under Compatibility and migration (FR10, FR13, FR15, FR16). |
-| Compatibility/readiness | Patch-compatible. One additive optional trigger field (DEC-1) plus trigger-key corrections that apply to every trigger (FR10, FR13, FR15, FR16); no visual decision. Implementation gaps are recorded inline on FR1, FR5, FR6, FR10, and PR2.                                                                                                                                                                                        |
-| Review checks           | Reject an edit path that mutates the DOM without updating the serialized draft, a file drop that can navigate away or bypass `onFiles`, a text paste that bypasses consumer interception, changed submit/token semantics, a trigger query that alters typed text, a key that picks a row from an earlier trigger query, or a menu that reopens after a send.                                                                         |
-| Governing rules         | `architecture:public-component-api/INV1`; `architecture:interaction-modality/INV1–INV4`; `architecture:knowledge-contracts/INV11, INV16`; `spec:AST-002`; `spec:AST-029`; rubric B15.                                                                                                                                                                                                                                                |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-ChatComposerInput supplies ChatComposer's rich editing surface when a plain custom
-textarea is insufficient. It owns contenteditable text and selection, serialized
-inline tokens, trigger menus, history recall, paste and file intake, and the
-imperative editing handle.
-
-## Compatibility and migration
-
-- Released default preserved: yes
-- Compatibility class: patch-compatible; one additive optional trigger field, no prop default changes, and trigger-key corrections for every trigger
-- Controlled and composition behavior: unchanged
-- Migration decision: none
-- Trigger query shape: `hasMultiWordQuery` is an additive optional trigger field; omitting it keeps single-token queries
-- Every trigger, opted in or not, also receives these patch-compatible corrections:
-  - FR13, correction: a key never picks a row returned for an earlier query, and a result arriving after a send, clear, pick, or dismissal is discarded instead of reopening the menu.
-  - FR15, correction: IME composition keys never pick a row or move the highlighted row.
-  - FR16, correction: after Escape, the menu stays hidden while the same query keeps growing instead of reopening on the next keystroke.
-  - FR10, correction: a tab before the trigger character is a boundary, like a space or line break.
-
-## Ownership boundary
-
-**Owns**
-
-- The contenteditable surface, its accessible editing semantics, and serialization.
-- Trigger-menu invocation and token insertion inside the editor.
-- Enter submission, history navigation, paste precedence, file intake, and imperative edit observability.
-- Registration of the editing focus control with ChatComposer.
-
-**Does not own / non-goals**
-
-- ChatComposer layout, send-button state, status placement, or shell elevation.
-- Product validation, upload, progress, or error handling for files.
-- Search result data, custom token meaning, or custom token interaction semantics supplied by callers.
-- A new visual representation for the editor, token, menu, or drop target.
-
-## Public concepts
-
-| Concept            | Closed values or states                                        | Meaning                                                                                     | Availability by state           | Default                     | Owner                         | Stability | Invalid-value behavior                                                |
-| ------------------ | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------- | --------------------------- | ----------------------------- | --------- | --------------------------------------------------------------------- |
-| draft storage      | DOM-owned; `value` controlled; ChatComposer context controlled | Selects the serialized draft source and observable change channel.                          | every editor                    | context or empty DOM        | `component:ChatComposerInput` | stable    | Explicit `value` wins; unsupported values are rejected by TypeScript. |
-| submission         | Enter; Shift+Enter; IME Enter; consumer-cancelled Enter        | Submits one trimmed non-empty draft only on uncancelled Enter without Shift or composition. | enabled editor                  | Enter submits               | `component:ChatComposerInput` | stable    | Empty or composing submission is ignored.                             |
-| trigger menu       | omitted; one or more trigger definitions                       | Opens suggestions at a configured character and inserts text or a serialized token.         | when triggers are configured    | omitted                     | `component:ChatComposerInput` | stable    | Unknown trigger characters remain ordinary text.                      |
-| trigger query      | single-token; multi-word                                       | Sets where an active trigger query ends, as FR10 and FR11 state.                            | while a trigger is active       | single-token                | `component:ChatComposerInput` | stable    | Omitting `hasMultiWordQuery` keeps single-token queries.              |
-| history            | enabled; disabled                                              | Recalls submitted drafts at text boundaries with ArrowUp and ArrowDown.                     | when enabled and history exists | enabled                     | `component:ChatComposerInput` | stable    | Mid-text arrow keys retain native caret behavior.                     |
-| text paste         | consumer-handled; paste-as-token; plain text                   | Gives `onPaste` first refusal, then optional token conversion, then inserts plain text.     | enabled editor                  | long-paste token conversion | `component:ChatComposerInput` | stable    | A handled callback stops later insertion paths.                       |
-| file intake        | pasted; dropped                                                | Prevents browser navigation and passes the files to `onFiles`.                              | when files are supplied         | no callback                 | `component:ChatComposerInput` | stable    | Empty drops do nothing; disabled input does not emit files.           |
-| imperative editing | insert token; expand token; insert text; focus; get value      | Lets composing features such as dictation operate through the editor's owned behavior.      | while mounted                   | none                        | `component:ChatComposerInput` | stable    | Calls without a mounted editor are no-ops or return an empty value.   |
-
-## Behavioral and layout contract
-
-| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Basis                                                                       |
-| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
-| FR1  | Every user or imperative edit that changes serialized content MUST update empty state and emit the effective value through the active `onChange` channel. Implementation gap: `handleRef.insertToken` inserts the token without emitting the value through `onChange` or updating empty state, so the placeholder stays visible.                                                                                                                                                                                                                                                  | Shipped `onChange` contract, imperative handle, and ChatDictation callsite. |
-| FR2  | Enter without Shift MUST submit one trimmed non-empty draft and clear it unless the event is composing, the trigger menu consumes it, or a consumer prevents default.                                                                                                                                                                                                                                                                                                                                                                                                             | Shipped implementation and consumer docs.                                   |
-| FR3  | Shift+Enter and mid-text history arrows MUST retain native multiline editing behavior.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Shipped implementation and focused tests.                                   |
-| FR4  | `value` supplied directly on ChatComposerInput MUST win over ChatComposer context, while an emitted echo MUST NOT rebuild the DOM or move the caret.                                                                                                                                                                                                                                                                                                                                                                                                                              | Shipped controlled precedence and regression tests.                         |
-| FR5  | Plain-text paste precedence MUST be consumer `onPaste` → configured/default paste-as-token → plain insertion. Implementation gap: a paste whose selection starts inside a token inserts the text after that token without calling `onPaste`.                                                                                                                                                                                                                                                                                                                                      | Public callback meaning and objective callback composition.                 |
-| FR6  | File paste and file drop MUST prevent native insertion/navigation and deliver the same ordered `File[]` to `onFiles`; disabled editors MUST NOT emit file callbacks. Implementation gap: a file paste whose selection starts inside a token never reaches `onFiles`.                                                                                                                                                                                                                                                                                                              | Shipped public `onFiles` contract and consumer docs.                        |
-| FR7  | Trigger-menu keyboard handling MUST run before consumer and built-in editor handling; IME composition MUST never submit.                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Shipped interaction contract and tests.                                     |
-| FR8  | History recall MUST operate only at the draft boundaries and MUST restore the pending draft after stepping past the newest item.                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Shipped behavior and tests.                                                 |
-| FR9  | The root MUST keep forwarding its ref, BaseProps attributes, and styling seams; the imperative handle remains separate in `handleRef`.                                                                                                                                                                                                                                                                                                                                                                                                                                            | Released public API and `architecture:public-component-api`.                |
-| FR10 | A trigger activates when its character starts the text or follows a space, a tab, or a line break, and its query runs from after that character to the caret. Inside an active multi-word query, FR11 limits which characters activate. A no-break space, such as the one after an inserted token, is not a boundary. A single-token query ends at a space, a tab, or a line break. Implementation gap: a trigger character that begins a text node activates whatever precedes it, such as an `@` typed directly after an inserted token and before its trailing no-break space. | Shipped trigger detection; DEC-1.                                           |
-| FR11 | A trigger with `hasMultiWordQuery: true` keeps its query through spaces and punctuation. The query ends only at a line break, past an implementation-owned length bound of at least 64 characters, or where the same trigger's character after a space, a tab, or a line break starts a new query; no word count, punctuation list, or termination callback applies. Inside an active multi-word query, another trigger's character does not activate under FR10, so the query continues through it.                                                                              | DEC-1.                                                                      |
-| FR12 | Ending a trigger query MUST leave the typed text unchanged. Only an explicit pick of a current row replaces the range from the trigger character to the caret.                                                                                                                                                                                                                                                                                                                                                                                                                    | DEC-1.                                                                      |
-| FR13 | While a newer search for the active query is pending, Enter without Shift submits the draft as typed and MUST NOT pick a row; no key picks a row returned for an earlier query. Results for a superseded query, or arriving after a pick, dismissal, submission, or the query ending, are discarded, so the menu never reopens over a sent or cleared draft. This applies to every trigger.                                                                                                                                                                                       | DEC-1; reference chat composer behavior.                                    |
-| FR14 | When a multi-word query settles with no matches, the menu is hidden unless the trigger supplies `emptySearchText`. A single-token query with no matches shows the empty message.                                                                                                                                                                                                                                                                                                                                                                                                  | DEC-1.                                                                      |
-| FR15 | Keys pressed during IME composition MUST NOT pick a row or move the highlighted row.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | DEC-1; FR7.                                                                 |
-| FR16 | Escape on a visible menu dismisses it, and the menu stays hidden while the same query keeps growing from the same trigger.                                                                                                                                                                                                                                                                                                                                                                                                                                                        | DEC-1.                                                                      |
-
-### Allowed variation
-
-- **AV1 — Search content.** Builders own trigger characters, search sources, item rendering, and inserted values.
-- **AV2 — Token content.** Builders may use the structured Badge form or the custom render escape hatch and own custom semantics.
-- **AV3 — Product file workflow.** Builders own accepted types, validation, upload, progress, and errors after `onFiles` receives the files.
-
-### Representative states
-
-| State                               | Required invariant                                                                                                                   | Allowed variation                      |
-| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- |
-| empty                               | Placeholder is visible and the serialized value is empty.                                                                            | Placeholder copy.                      |
-| typed or imperatively inserted text | Placeholder is absent and the same serialized value is observable to ChatComposer and callbacks (FR1 records an implementation gap). | Draft content.                         |
-| controlled update                   | External value is reflected without corrupting a live caret or treating a stale echo as authoritative.                               | Parent update timing.                  |
-| trigger menu open                   | Combobox semantics and active option wiring are exposed; menu interaction owns its keys.                                             | Search source and item rendering.      |
-| trigger search pending              | Enter submits the draft as typed; no earlier query's row can be picked.                                                              | Loading copy and source latency.       |
-| trigger menu hidden                 | The editor reports a collapsed combobox and the menu consumes no keys.                                                               | Why the menu is hidden.                |
-| file paste or drop                  | Native insertion/navigation is prevented and files reach `onFiles` once (FR6 records an implementation gap).                         | File types and product handling.       |
-| disabled                            | Editing and file callbacks are unavailable and disabled state is exposed.                                                            | Product reason and surrounding status. |
-
-### Transformation and precedence order
-
-- **ORD1 — Draft source.** Explicit `value` → ChatComposer context value → editor DOM.
-- **ORD2 — Change channel.** Explicit controlled input callback when `value` is explicit → ChatComposer context callback → distinct local callback.
-- **ORD3 — Key handling.** Trigger menu → consumer `onKeyDown` → IME/submit/history behavior.
-- **ORD4 — Plain paste.** Consumer `onPaste` → paste-as-token behavior → plain insertion (FR5 records an implementation gap).
-- **ORD5 — File intake.** Files on clipboard or data transfer → prevent native behavior → emit `onFiles` when enabled (FR6 records an implementation gap).
-
-### Performance and resources
-
-- **PR1 — Selection work.** Selection reads and writes are scoped to the mounted editable and run only for direct editing actions or controlled synchronization.
-- **PR2 — Async trigger work.** Search cancellation goes through the supplied `SearchSource` and its optional `cancel`, and `debounceMs` sets the delay before an async search starts. Implementation gap: each keystroke that changes the query also calls `search('')` at once to detect whether the source is async, so an async source receives an undelayed search.
-- **PR3 — Portal cleanup.** Token portals are cleaned through the existing token hook when content changes or unmounts.
-
-## Accessibility contract
-
-- **AR1 — Editing semantics.** Without triggers, the surface is a named multiline textbox; with triggers, it exposes the adopted combobox semantics without invalid multiline ARIA.
-- **AR2 — Disabled state.** Disabled editing is exposed with `aria-disabled` and cannot accept content or file callbacks.
-- **AR3 — Keyboard ownership.** IME, trigger-menu keys, consumer cancellation, Enter submission, and boundary-only history do not steal one another's keys.
-- **AR4 — Focus visibility.** When composed in ChatComposer, the semantic editor focus owner drives the shell's shared keyboard focus indicator.
-- **AR5 — Collapsed suggestions.** While the menu is hidden, the editor reports `aria-expanded="false"`, exposes no active descendant, and arrow keys, Enter, and Escape reach the editor and its surroundings.
-
-## Design relationships
-
-| Anatomy or state | Design requirement                 | Representation authority | Hierarchy role | Component contract  |
-| ---------------- | ---------------------------------- | ------------------------ | -------------- | ------------------- |
-| input root       | existing themed target             | observed implementation  | supporting     | FR9                 |
-| editable surface | ordinary composer editing surface  | ChatComposer family      | prominent      | FR1–FR4, AR1–AR4    |
-| placeholder      | secondary text while empty         | current token role       | supporting     | FR1                 |
-| trigger menu     | delegated Typeahead behavior       | Typeahead owner          | floating       | FR7, FR10–FR16, AR5 |
-| inline token     | structured Badge or caller content | Badge or caller owner    | supporting     | AV2                 |
-
-The existing `chat-composer-input` target remains on the root. This record does not
-add a theming target or decide a new visual state.
-
-## Family and system relationships
-
-- `component:ChatComposer` owns layout, submission orchestration, send state, and the shell focus ring; this component owns the editing surface and its change channel.
-- Typeahead and SearchSource own result collection behavior; ChatComposerInput owns when the trigger menu participates in editor key precedence.
-- `architecture:interaction-modality` owns the shared focus-visibility mechanics.
-- `spec:AST-029` owns the observational audit-backfill boundary.
-
-## Verification map
-
-| Contract              | Verification                                                                       | Representative states                                                                       | Mutation or failure expectation                                                                                                                                                                  | Audit section                           |
-| --------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------- |
-| FR1, ORD1–ORD2        | focused imperative insertion and controlled-sync tests; `ImperativeInsertion` play | empty → inserted text; controlled echo; external override                                   | Text appears only in the DOM, placeholder remains, callback is stale, or the caret jumps.                                                                                                        | `audit:ChatComposerInput/behavior`      |
-| FR2–FR3, FR7–FR8, AR3 | focused keyboard, IME, trigger, and history tests                                  | Enter; Shift+Enter; composition; cancelled key; boundary and mid-text arrows                | A key submits twice, submits during composition, or steals native editing.                                                                                                                       | `audit:ChatComposerInput/interaction`   |
-| FR10–FR16, AR5        | focused trigger-query and trigger keyboard tests                                   | single-token; multi-word; line break; length bound; pending search; no matches; IME; Escape | A query ends early or alters text, Enter picks an earlier query's row or fails to submit while a search is pending, a late result reopens the menu after a send, or a hidden menu consumes keys. | `audit:ChatComposerInput/interaction`   |
-| FR5, ORD4             | focused long-paste interception tests                                              | consumer handled; token conversion; plain insertion                                         | Consumer interception is skipped or multiple insertion paths run.                                                                                                                                | `audit:ChatComposerInput/behavior`      |
-| FR6, ORD5, AR2        | focused paste/drop tests and `FileDrop` play                                       | paste; drop; disabled                                                                       | Files navigate away, insert into the editor, bypass `onFiles`, or emit while disabled.                                                                                                           | `audit:ChatComposerInput/behavior`      |
-| AR1, AR4              | role/name/ARIA tests plus exact-head accessibility and visual gates                | textbox; combobox; disabled; keyboard focus                                                 | Name, role, multiline, expanded, disabled, or visible focus semantics regress.                                                                                                                   | `audit:ChatComposerInput/accessibility` |
-| FR9                   | ref, target, package, and repository checks                                        | ref; BaseProps; xstyle; className; style                                                    | Root ownership or a styling seam moves or disappears.                                                                                                                                            | `audit:ChatComposerInput/api`           |
-
-## Decision log
-
-### DEC-1 — Trigger queries are non-destructive and act only on current results
-
-**Reference:** `component:ChatComposerInput/DEC-1`
-**Decider:** `cixzhang`, `2026-10-06`; pending-search Enter, `2026-10-14`; cross-trigger continuation applies the same reference-composer direction, `2026-10-14`
-
-Only the caller knows whether its suggestions contain spaces, so multi-word
-queries are a per-trigger opt-in and single-token triggers such as commands keep
-ending at whitespace. A multi-word query never changes what the person typed: it
-ends as FR11 states, and only an explicit pick replaces text. Suggestions act
-only on the current query: while a search is pending, Enter sends the message as
-typed and never picks a row from an earlier query, and results that arrive after
-the send are dropped so the menu never reopens over the cleared composer. This
-matches the reference chat composer, where a message may simply start with a
-trigger. An unmatched multi-word phrase hides the menu instead of covering prose
-with an empty panel. Inside an active multi-word query another trigger's
-character does not start a query, so `@Jordan /` keeps the mention query, while
-the same trigger's character starts a new query as FR11 states; both match the
-reference chat composer.
-
-Rejected: word caps, punctuation terminators, or a termination callback; they cut off real names and depend on language.
-
-Rejected: holding Enter until a pending search settles; it blocks sending a message that only starts with a trigger.
-
-## Open questions
-
-None.
-
-## Content boundary
-
-This file does not duplicate consumer prop tables, examples, current audit scores,
-or visual design rationale. It records shipped behavior, objective corrections, and
-the trigger-query contract in DEC-1, without deciding a new visual representation.

package/src/Chat/ChatComposerTokenElement.spec.md

@@ -1,164 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:ChatComposerTokenElement
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-31
-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         | `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.
-
-## 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: 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**
-
-- 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  | 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
-
-- 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
-
-- **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     | Current source           | 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 the audit evidence inventory this record's verification map follows.
-
-## Verification map
-
-| 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 decision is recorded.
-
-## Open questions
-
-None.
-
-## Content boundary
-
-This file does not duplicate consumer examples, current audit scores, Badge policy, or
-ChatComposerInput selection mechanics.

package/src/Chat/ChatDictationButton.spec.md

@@ -1,205 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:ChatDictationButton
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-31
-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: [design:reduced-motion]
-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, spec:AST-027]
----
-
-# ChatDictationButton component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                                                                          |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | `ChatDictationButton` with a required `dictation` state (`isSupported`, `isListening`, `volume`, `bands`, `toggle`), `size` (`sm`, `md`; default `md`), `isHiddenWhenUnsupported` (default true), `label`, `ref`, `xstyle`, `className`, `style`, and span props. |
-| Behavior                | An icon-only microphone Button that toggles dictation. While listening it shows five volume-reactive bars instead of the microphone; unsupported dictation renders nothing, or a disabled Button when kept visible.                                               |
-| End-user impact         | Voice input is one labelled button that says whether it starts or stops dictation; browsers without speech recognition see no action that cannot run.                                                                                                             |
-| Builder impact          | None.                                                                                                                                                                                                                                                             |
-| Compatibility/readiness | Records shipped behavior; no public change. Two implementation gaps, listed under Current-state impact.                                                                                                                                                           |
-| Review checks           | Reject an enabled unsupported action, a missing or stale start/stop name, bars exposed to assistive technology, or clipping color that a theme cannot retint.                                                                                                     |
-| Governing rules         | `architecture:public-component-api`; `architecture:theme-tokens` INV3; `architecture:component-style-authoring` INV7; `design:reduced-motion`.                                                                                                                    |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-ChatDictationButton is the visible control for a speech-recognition state
-owner. It turns that owner's support and listening state into one icon-only
-Button and a five-bar volume display. Consumer usage lives in
-`ChatDictationButton.doc.mjs`.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`
-- Compatibility class: records shipped behavior; no public change
-- Controlled/uncontrolled behavior: listening state is owned by the supplied
-  `dictation` value
-- Migration decision: none
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Current-state impact
-
-- **The volume bars are extra elements.** The listening display is a container
-  and five bar `span` elements that no theme target paints.
-  `architecture:component-style-authoring` INV7 renders one element per
-  semantic role or themable part.
-
-- **The bars set a z-index without isolation.** The bar container carries
-  `z-index: 1` and the wrapper does not isolate it, so the bars take part in
-  the page's stacking order. `spec:AST-027` FR1 keeps z-index local and lists
-  this case as a containment gap.
-
-## Ownership boundary
-
-**Owns**
-
-- The start and stop name, and the caller's `label` override (FR1, FR2).
-- Hiding or disabling the control when speech recognition is unsupported
-  (FR3).
-- The five-bar display of the supplied bands and its clipping color (FR2, FR4).
-- The wrapper span's ref, props, and styling (FR5).
-
-**Does not own / non-goals**
-
-- Speech recognition support detection, lifecycle, transcripts, errors, and
-  microphone permission — owned by the `dictation` state owner.
-- Activation, focus, disabled semantics, and icon-only presentation — owned by
-  `component:Button`.
-- Placement in ChatComposer — the caller's composition.
-- A public color, threshold, or bar-shape option.
-
-## Public concepts
-
-| Concept   | Closed values or states                                  | Meaning                                                    | Availability by variant/orientation/state | Default                 | Owner                           | Stability | Invalid-value behavior           |
-| --------- | -------------------------------------------------------- | ---------------------------------------------------------- | ----------------------------------------- | ----------------------- | ------------------------------- | --------- | -------------------------------- |
-| Support   | supported; unsupported and hidden; unsupported and shown | Whether the control renders and whether it can operate.    | Every control.                            | hidden when unsupported | `component:ChatDictationButton` | Stable    | TypeScript rejects other values. |
-| Listening | idle; listening                                          | Selects the start or stop name and the microphone or bars. | Supported controls.                       | idle                    | `dictation` owner               | Stable    | Not applicable.                  |
-| Size      | `sm`, `md`                                               | Sizes the Button and bars together.                        | Every control.                            | `md`                    | `component:ChatDictationButton` | Stable    | TypeScript rejects other values. |
-
-## Behavioral and layout contract
-
-| ID  | Invariant                                                                                                                                                                                          | Basis                                   |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
-| FR1 | When supported and idle, the control is an enabled, icon-only ghost Button with the microphone icon, named by `label` or the translated start label, that calls `dictation.toggle` when activated. | Current source and tests                |
-| FR2 | While listening, the Button is named by `label` or the translated stop label and shows no icon, and five bars, hidden from assistive technology, scale with the supplied `bands`.                  | Current source and tests                |
-| FR3 | When dictation is unsupported, the control renders nothing; with `isHiddenWhenUnsupported={false}` it renders a disabled Button.                                                                   | Current source and tests                |
-| FR4 | The bars use `--color-accent`, blending toward `--color-error` as `volume` passes the clipping threshold, so a theme retints both ends (`architecture:theme-tokens` INV3).                         | Current source and tests                |
-| FR5 | `ref`, DOM, data, and ARIA props, `className`, `style`, and `xstyle` reach the wrapper span, which carries the `chat-dictation-button` target; `size` sizes the Button and the bars together.      | Current source and tests                |
-| FR6 | Under reduced motion the bars change scale and color at once, with no transition.                                                                                                                  | `design:reduced-motion`; current source |
-
-### Allowed variation
-
-- **AV1 — Label.** Callers may replace the translated start and stop name.
-- **AV2 — Bars.** Bar heights and clipping strength follow the supplied
-  `bands` and `volume`.
-- **AV3 — Theme colors.** Themes may change the accent and error colors.
-
-### Representative states
-
-| State                     | Required invariant                             | Allowed variation |
-| ------------------------- | ---------------------------------------------- | ----------------- |
-| Supported, idle           | Enabled microphone Button with the start name. | Label, size.      |
-| Listening                 | Stop name; five hidden bars.                   | Bar heights.      |
-| Clipping                  | Bars blend from accent toward error.           | Theme colors.     |
-| Unsupported, default      | Nothing renders.                               | —                 |
-| Unsupported, kept visible | A disabled Button.                             | Label.            |
-
-### Transformation and precedence order
-
-- **ORD1 — Name.** The caller's `label`, then the translated start or stop
-  label for the listening state.
-- **ORD2 — Support.** Unsupported and hidden renders nothing before any other
-  state applies.
-
-### Performance and resources
-
-- No resource rule.
-
-## Accessibility contract
-
-- **AR1 — Name.** The control always has a name that says whether it starts or
-  stops dictation, unless the caller overrides it (FR1, FR2).
-- **AR2 — Decorative bars.** The bars are hidden from assistive technology
-  (FR2).
-- **AR3 — Unavailable action.** A visible unsupported control is disabled
-  (FR3); Button owns how disabled is conveyed.
-
-## Design relationships
-
-| Anatomy or state | Design requirement                                 | Representation authority | Hierarchy role | Component contract |
-| ---------------- | -------------------------------------------------- | ------------------------ | -------------- | ------------------ |
-| Button           | Icon-only microphone action.                       | `component:Button`       | Prominent      | FR1, FR3           |
-| Volume bars      | Five bars that show live input level and clipping. | Current source           | Supporting     | FR2, FR4, FR6      |
-
-No anatomy-theming map is recorded yet; the block is optional during
-migration, so the map is deferred.
-
-## Family and system relationships
-
-- `component:Button` owns activation, focus, disabled semantics, and icon-only
-  presentation.
-- `architecture:theme-tokens` owns the accent and error roles the bars use.
-- `design:reduced-motion` owns the reduced-motion rule FR6 follows.
-- The glyph and centered bars are direction-neutral; the RTL audit records
-  this as not applicable.
-
-## Verification map
-
-| Contract | Verification                                                                                          | Representative states         | Mutation or failure expectation                                         | Audit section                             |
-| -------- | ----------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------------------------------------------- | ----------------------------------------- |
-| FR1, AR1 | `ChatDictationButton.test.tsx` "labels and toggles the idle button"                                   | Idle                          | A missing name, or activation that does not toggle, fails.              | `audit:ChatDictationButton/behavior`      |
-| FR2, AR2 | `ChatDictationButton.test.tsx` "shows five hidden visualizer bars and the stop label while listening" | Listening                     | A wrong bar count, exposed bars, or a start name while listening fails. | `audit:ChatDictationButton/behavior`      |
-| FR3, AR3 | `ChatDictationButton.test.tsx` unsupported tests                                                      | Unsupported, hidden and shown | A rendered or enabled unsupported control fails.                        | `audit:ChatDictationButton/accessibility` |
-| FR4      | `ChatDictationButton.test.tsx` "uses theme-owned colors for clipping feedback"                        | Clipping                      | A raw color in place of the theme roles fails.                          | `audit:ChatDictationButton/theming`       |
-| FR5      | `ChatDictationButton.test.tsx` "forwards the root ref and accepted span props"                        | Ref and span props            | A dropped ref or prop fails.                                            | `audit:ChatDictationButton/api`           |
-| RTL N/A  | `apps/storybook/rtl-audit/verified-not-applicable.json`                                               | —                             | —                                                                       | `audit:ChatDictationButton/rtl`           |
-
-Read from source, with no focused test yet:
-
-- FR1: the ghost variant and the microphone icon.
-- FR2: no icon while listening, the bars scaling with `bands`, and the
-  caller's `label` while listening.
-- FR4: the plain accent below the clipping threshold.
-- FR5: ARIA props reaching the wrapper, `className`, `style`, and `xstyle` composing on the wrapper, the
-  `chat-dictation-button` target, and `sm` sizing.
-- FR6: the reduced-motion transition removal.
-
-## Decision log
-
-No component-local decision is recorded.
-
-## Open questions
-
-None.
-
-## Content boundary
-
-This file does not duplicate consumer prop tables, speech-recognition
-behavior, or Button's rules. It links to their owners.