@astryxdesign/core 0.6.2 → 0.6.3-canary.0899f21

package/src/Chat/ChatComposerInput.doc.mjs

@@ -7,22 +7,79 @@ export const docs = {
   subComponentOf: 'Chat',
   displayName: 'Chat Composer Input',
   isHiddenFromOverview: true,
-  description: "Rich text input for the chat composer. Supports trigger menus (type @ or / to open a typeahead), inline tokens rendered as badges, message history recall with ArrowUp/Down, paste/drop file handling, and a 16px touch-device font-size floor to prevent iOS input zoom. Pass it to ChatComposer's input slot when you need more than a plain textarea.",
+  description:
+    "Rich text input for the chat composer. Supports trigger menus (type @ or / to open a typeahead), inline tokens rendered as badges, message history recall with ArrowUp/Down, paste/drop file handling, and a 16px iOS font-size floor to prevent input zoom. Pass it to ChatComposer's input slot when you need more than a plain textarea.",
+  usage: {
+    description:
+      "Pass ChatComposerInput to ChatComposer's input slot when the draft needs trigger menus, inline tokens, history recall, dictation insertion, or file intake.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Use handleRef for programmatic text or token insertion; inserted text follows the same onChange pipeline as typing.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use onFiles for files pasted or dropped onto the editor, and keep file validation and upload progress in the product layer.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use custom token rendering for ordinary mentions or commands; prefer the structured badge form so tokens remain predictable and themeable.',
+      },
+    ],
+    anatomy: [
+      {
+        name: 'Input root',
+        required: true,
+        description:
+          'The themed container that forwards the root ref and BaseProps styling seams.',
+      },
+      {
+        name: 'Editable surface',
+        required: true,
+        description:
+          'The labeled contenteditable textbox or combobox that owns text, selection, keyboard, paste, and drop behavior.',
+      },
+      {
+        name: 'Placeholder',
+        required: false,
+        description:
+          'Visual guidance shown only while the serialized draft is empty.',
+      },
+      {
+        name: 'Trigger menu',
+        required: false,
+        description:
+          'The suggestion popup rendered while a configured trigger is active.',
+      },
+      {
+        name: 'Inline token',
+        required: false,
+        description:
+          'A non-editable badge or custom rendering with a stable serialized value.',
+      },
+    ],
+  },
   props: [
     {
       name: 'handleRef',
       type: 'React.Ref<ChatComposerInputHandle>',
-      description: 'Imperative handle for programmatic control: insertToken, insertText, focus, and getValue.',
+      description:
+        'Imperative handle for programmatic control: insertToken, expandToken, insertText, focus, and getValue.',
     },
     {
       name: 'value',
       type: 'string',
-      description: 'Controlled input value. Pair with onChange for two-way binding.',
+      description:
+        'Controlled input value. Pair with onChange for two-way binding.',
     },
     {
       name: 'onChange',
       type: '(value: string) => void',
-      description: 'Called when the input value changes. The serialized string includes token placeholders.',
+      description:
+        'Called when the input value changes. The serialized string includes token placeholders.',
     },
     {
       name: 'placeholder',
@@ -33,24 +90,28 @@ export const docs = {
     {
       name: 'maxRows',
       type: 'number',
-      description: 'Maximum visible rows before the input scrolls. Use a lower value in compact layouts.',
+      description:
+        'Maximum visible rows before the input scrolls. Use a lower value in compact layouts.',
       default: '8',
     },
     {
       name: 'triggers',
       type: 'ChatComposerTrigger[]',
-      description: 'Trigger definitions for typeahead menus. Each trigger specifies a character (@ or /), a search source, and an onSelect handler that returns the token to insert.',
+      description:
+        'Trigger definitions for typeahead menus. Each trigger specifies a character (@ or /), a search source, and an onSelect handler that returns the token to insert.',
     },
     {
       name: 'debounceMs',
       type: 'number',
-      description: 'Debounce delay for async search sources to avoid excessive network requests.',
+      description:
+        'Debounce delay for async search sources to avoid excessive network requests.',
       default: '150',
     },
     {
       name: 'hasHistory',
       type: 'boolean',
-      description: 'Enable ArrowUp/Down to recall previously submitted messages.',
+      description:
+        'Enable ArrowUp/Down to recall previously submitted messages.',
       default: 'true',
     },
     {
@@ -62,28 +123,39 @@ export const docs = {
     {
       name: 'isDisabled',
       type: 'boolean',
-      description: 'Disables the input. Use during streaming or when a prerequisite is unmet.',
+      description:
+        'Disables the input. Use during streaming or when a prerequisite is unmet.',
       default: 'false',
     },
     {
       name: 'onPaste',
-      type: '(event, text) => void',
-      description: 'Called when text is pasted. Use to intercept or transform pasted content.',
+      type: '(event, text) => boolean | void',
+      description:
+        'Called when plain text is pasted. Return true after handling the text yourself; otherwise ChatComposerInput inserts it or applies paste-as-token behavior.',
+    },
+    {
+      name: 'pasteAsToken',
+      type: 'UseChatPasteAsTokenReturn | false',
+      description:
+        'Paste-as-token behavior. By default, plain-text pastes over 200 characters become expandable tokens. Pass false to keep every text paste inline, or provide useChatPasteAsToken() to customize the conversion.',
     },
     {
       name: 'onFiles',
       type: '(files: File[]) => void',
-      description: 'Called when files are pasted or dropped onto the input. Use to handle attachments.',
+      description:
+        'Called when files are pasted or dropped onto the input. Use to handle attachments.',
     },
     {
       name: 'onSubmit',
       type: '(value: string) => void',
-      description: 'Called when the user presses Enter without Shift. The serialized value includes token placeholders.',
+      description:
+        'Called when the user presses Enter without Shift. The serialized value includes token placeholders.',
     },
     {
       name: 'onKeyDown',
       type: '(event) => void',
-      description: 'Key-down handler invoked before the built-in Enter/history behavior (after any open trigger menu). The seam for platform-specific keys: call event.preventDefault() to suppress the default submit (e.g. newline on a touch keyboard), or act on the event yourself to add behavior (e.g. submit on Cmd/Ctrl+Enter). IME composition is always respected; Enter never submits mid-composition.',
+      description:
+        'Key-down handler invoked before the built-in Enter/history behavior (after any open trigger menu). The seam for platform-specific keys: call event.preventDefault() to suppress the default submit (e.g. newline on a touch keyboard), or act on the event yourself to add behavior (e.g. submit on Cmd/Ctrl+Enter). IME composition is always respected; Enter never submits mid-composition.',
     },
   ],
 };
@@ -92,22 +164,29 @@ export const docsZh = {
   name: 'ChatComposerInput',
   isHiddenFromOverview: true,
   displayName: 'Chat Composer Input',
-  description: '聊天编写器的富文本输入。支持触发菜单（输入 @ 或 / 打开 typeahead）、内联标记徽章、ArrowUp/Down 消息历史回溯、粘贴/拖放文件处理，并在触控设备上将字体大小保持至少 16px 以避免 iOS 输入缩放。当需要普通文本区域以外的功能时，传入 ChatComposer 的 input 插槽。',
+  description:
+    '聊天编写器的富文本输入。支持触发菜单（输入 @ 或 / 打开 typeahead）、内联标记徽章、ArrowUp/Down 消息历史回溯、粘贴/拖放文件处理，并在 iOS 上将字体大小保持至少 16px 以避免输入缩放。当需要普通文本区域以外的功能时，传入 ChatComposer 的 input 插槽。',
   propDescriptions: {
-    handleRef: '命令式句柄，用于编程式控制：insertToken、insertText、focus 和 getValue。',
+    handleRef:
+      '命令式句柄，用于编程式控制：insertToken、expandToken、insertText、focus 和 getValue。',
     value: '受控输入值。与 onChange 配对实现双向绑定。',
     onChange: '输入值变更时调用。序列化字符串包含标记占位符。',
     placeholder: '输入为空时显示的占位文本。',
     maxRows: '滚动前的最大可见行数。紧凑布局中使用较小值。',
-    triggers: '菜单的触发定义。每个触发器指定字符（@ 或 /）、搜索源和返回要插入标记的 onSelect 处理器。',
+    triggers:
+      '菜单的触发定义。每个触发器指定字符（@ 或 /）、搜索源和返回要插入标记的 onSelect 处理器。',
     debounceMs: '异步搜索源的去抖动延迟，避免过多网络请求。',
     hasHistory: '启用 ArrowUp/Down 回溯之前提交的消息。',
     label: '屏幕阅读器播报的无障碍标签。',
     isDisabled: '禁用输入。在流式输出期间或前置条件未满足时使用。',
-    onPaste: '粘贴文本时调用。用于拦截或转换粘贴内容。',
+    onPaste:
+      '粘贴纯文本时调用。自行处理后返回 true；否则由 ChatComposerInput 插入文本或应用粘贴转标记行为。',
+    pasteAsToken:
+      '粘贴转标记行为。默认将超过 200 个字符的纯文本粘贴转为可展开标记；传入 false 可始终内联粘贴，或传入 useChatPasteAsToken() 结果来自定义转换。',
     onFiles: '粘贴或拖放文件到输入时调用。用于处理附件。',
     onSubmit: '用户不按 Shift 按 Enter 时调用。序列化值包含标记占位符。',
-    onKeyDown: '在内置 Enter/历史处理之前（在打开的触发菜单之后）调用的按键处理器。平台特定按键的接缝：调用 event.preventDefault() 可抑制默认提交（例如触控键盘上插入换行），或自行处理事件以添加行为（例如 Cmd/Ctrl+Enter 提交）。始终尊重输入法组字状态——组字过程中 Enter 永不提交。',
+    onKeyDown:
+      '在内置 Enter/历史处理之前（在打开的触发菜单之后）调用的按键处理器。平台特定按键的接缝：调用 event.preventDefault() 可抑制默认提交（例如触控键盘上插入换行），或自行处理事件以添加行为（例如 Cmd/Ctrl+Enter 提交）。始终尊重输入法组字状态——组字过程中 Enter 永不提交。',
   },
 };
 
@@ -115,21 +194,30 @@ export const docsDense = {
   name: 'ChatComposerInput',
   isHiddenFromOverview: true,
   displayName: 'Chat Composer Input',
-  description: 'rich input for composer; trigger menus (@/commands), inline tokens, msg history, paste/drop files, 16px touch font-size floor to prevent iOS zoom. Use in ChatComposer input slot when you need more than plain textarea.',
+  description:
+    'rich input for composer; trigger menus (@/commands), inline tokens, msg history, paste/drop files, 16px iOS font-size floor to prevent zoom. Use in ChatComposer input slot when you need more than plain textarea.',
   propDescriptions: {
-    handleRef: 'imperative handle (insertToken/insertText/focus/getValue)',
+    handleRef:
+      'imperative handle (insertToken/expandToken/insertText/focus/getValue)',
     value: 'controlled value; pair w/ onChange for two-way binding',
-    onChange: 'value change handler; serialized string includes token placeholders',
+    onChange:
+      'value change handler; serialized string includes token placeholders',
     placeholder: 'placeholder when empty',
     maxRows: 'max visible rows before scroll; lower for compact layouts',
-    triggers: 'typeahead trigger defs; character(@/)+searchSource+onSelect returning token',
+    triggers:
+      'typeahead trigger defs; character(@/)+searchSource+onSelect returning token',
     debounceMs: 'debounce for async search to avoid excess requests',
     hasHistory: 'ArrowUp/Down to recall previous submissions',
     label: 'a11y label for screen readers',
     isDisabled: 'disabled; use during streaming or unmet prereqs',
-    onPaste: 'paste handler; intercept/transform pasted content',
+    onPaste:
+      'plain-text paste callback; return true when handled, otherwise built-in token/plain insertion runs',
+    pasteAsToken:
+      'paste-as-token behavior; >200 chars by default, false for inline-only, or custom useChatPasteAsToken() result',
     onFiles: 'file paste/drop handler; use for attachments',
-    onSubmit: 'Enter w/o Shift handler; serialized value includes token placeholders',
-    onKeyDown: 'keydown handler before built-in Enter/history (after trigger menu); preventDefault() to suppress default submit (touch newline) or act on event to add behavior (Cmd/Ctrl+Enter). IME composition always respected',
+    onSubmit:
+      'Enter w/o Shift handler; serialized value includes token placeholders',
+    onKeyDown:
+      'keydown handler before built-in Enter/history (after trigger menu); preventDefault() to suppress default submit (touch newline) or act on event to add behavior (Cmd/Ctrl+Enter). IME composition always respected',
   },
 };

package/src/Chat/ChatComposerInput.spec.md

@@ -0,0 +1,185 @@
+---
+schema_version: 3
+template_version: 5
+kind: component
+id: component:ChatComposerInput
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+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         | No API or default change. ChatComposerInput remains the optional rich editing surface for ChatComposer, with controlled draft, trigger, history, paste, file, and imperative seams.                                          |
+| 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 becomes sendable and does not remain hidden behind the empty placeholder; dropped files reach the product attachment flow.                                              |
+| Builder impact          | Existing props, callback signatures, defaults, exports, and token serialization stay unchanged. Builders relying on the documented `onPaste` and `onFiles` paths now receive those callbacks consistently.                   |
+| Compatibility/readiness | Patch-compatible correction to released behavior. This observational record adds no public concept or visual decision.                                                                                                       |
+| 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, or changed submit/token semantics. |
+| 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 behavior correction; no public type or default changes
+- Controlled and composition behavior: unchanged
+- Migration decision: none
+
+## 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.                      |
+| 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  | Candidate invariant                                                                                                                                                   | Basis                                                                       | Draft review state |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------ |
+| FR1 | Every user or imperative edit that changes serialized content MUST update empty state and emit the effective value through the active `onChange` channel.             | Shipped `onChange` contract, imperative handle, and ChatDictation callsite. | settled            |
+| 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.                                   | verify             |
+| FR3 | Shift+Enter and mid-text history arrows MUST retain native multiline editing behavior.                                                                                | Shipped implementation and focused tests.                                   | verify             |
+| 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.                         | verify             |
+| FR5 | Plain-text paste precedence MUST be consumer `onPaste` → configured/default paste-as-token → plain insertion.                                                         | Public callback meaning and objective callback composition.                 | settled            |
+| 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.  | Shipped public `onFiles` contract and consumer docs.                        | settled            |
+| FR7 | Trigger-menu keyboard handling MUST run before consumer and built-in editor handling; IME composition MUST never submit.                                              | Shipped interaction contract and tests.                                     | verify             |
+| 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.                                                 | verify             |
+| 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`.                | verify             |
+
+### 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.       | 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.      |
+| file paste or drop                  | Native insertion/navigation is prevented and files reach `onFiles` once.                               | 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.
+- **ORD5 — File intake.** Files on clipboard or data transfer → prevent native behavior → emit `onFiles` when enabled.
+
+### 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 and debounce ownership remain in `useTriggerMenu` and the supplied `SearchSource`.
+- **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.
+
+## 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                |
+| inline token     | structured Badge or caller content | Badge or caller owner    | supporting     | AV2                |
+
+The existing `chat-composer-input` target remains on the root. This observational
+draft 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`   |
+| 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
+
+No component-local policy decision is created by this observational draft.
+
+## 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 and objective corrections
+without expanding the public API or deciding a new visual representation.

package/src/Chat/ChatComposerInput.test.tsx

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 import {describe, it, expect, vi, afterEach} from 'vitest';
-import {render, screen, fireEvent, waitFor} from '@testing-library/react';
+import {render, screen, fireEvent, waitFor, act} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {ChatComposer} from './ChatComposer';
 import {useChatComposerContext} from './ChatContext';
@@ -570,6 +570,33 @@ describe('ChatComposerInput', () => {
       });
       expect(onFiles).toHaveBeenCalledWith([file]);
     });
+
+    it('calls onFiles when files are dropped onto the editor', () => {
+      const onFiles = vi.fn();
+      render(<ChatComposerInput onFiles={onFiles} />);
+      const textbox = screen.getByRole('textbox');
+      const file = new File(['content'], 'dropped.txt', {type: 'text/plain'});
+
+      const allowed = fireEvent.drop(textbox, {
+        dataTransfer: {files: [file], types: ['Files']},
+      });
+      expect(allowed).toBe(false);
+      expect(onFiles).toHaveBeenCalledWith([file]);
+    });
+
+    it('does not emit dropped files while disabled', () => {
+      const onFiles = vi.fn();
+      render(<ChatComposerInput isDisabled onFiles={onFiles} />);
+      const textbox = screen.getByRole('textbox');
+      const file = new File(['content'], 'blocked.txt', {type: 'text/plain'});
+
+      const allowed = fireEvent.drop(textbox, {
+        dataTransfer: {files: [file], types: ['Files']},
+      });
+
+      expect(allowed).toBe(false);
+      expect(onFiles).not.toHaveBeenCalled();
+    });
   });
 
   // Paste / insert paths used to bail silently when the contenteditable
@@ -651,10 +678,13 @@ describe('ChatComposerInput', () => {
       expect(textbox.querySelector('[data-astryx-token]')).toBeInTheDocument();
     });
 
-    it('imperative insertText works after a focus() with no selection range', () => {
+    it('imperative insertText updates the observable draft after a focus() with no selection range', () => {
       let handle: ChatComposerInputHandle | null = null;
+      const onChange = vi.fn();
       render(
         <ChatComposerInput
+          placeholder="Write a message"
+          onChange={onChange}
           handleRef={h => {
             handle = h;
           }}
@@ -665,8 +695,12 @@ describe('ChatComposerInput', () => {
       textbox.focus();
       clearSelection();
 
-      handle!.insertText('hello');
+      act(() => handle!.insertText('hello'));
+
       expect(textbox.textContent).toContain('hello');
+      expect(onChange).toHaveBeenCalledTimes(1);
+      expect(onChange).toHaveBeenLastCalledWith('hello');
+      expect(screen.queryByText('Write a message')).not.toBeInTheDocument();
     });
 
     // History recall reads where the caret sits, so where a programmatic
@@ -976,6 +1010,60 @@ describe('ChatComposerInput', () => {
       });
     });
 
+    it('lets onPaste intercept long text before default token conversion', () => {
+      const onPaste = vi.fn(() => true);
+      render(<ChatComposerInput onPaste={onPaste} />);
+      const textbox = screen.getByRole('textbox');
+      textbox.focus();
+      clearSelection();
+      const long = 'c'.repeat(250);
+
+      fireEvent.paste(textbox, {
+        clipboardData: {
+          files: [],
+          getData: (type: string) => (type === 'text/plain' ? long : ''),
+        },
+      });
+
+      expect(onPaste).toHaveBeenCalledWith(expect.anything(), long);
+      expect(
+        textbox.querySelector('[data-astryx-token]'),
+      ).not.toBeInTheDocument();
+      expect(textbox.textContent).toBe('');
+    });
+
+    it('emits once when onPaste inserts through the imperative handle', () => {
+      let handle: ChatComposerInputHandle | null = null;
+      const onChange = vi.fn();
+      const onPaste = vi.fn((_event: unknown, text: string) => {
+        handle!.insertText(text);
+        return true;
+      });
+      render(
+        <ChatComposerInput
+          handleRef={next => {
+            handle = next;
+          }}
+          onChange={onChange}
+          onPaste={onPaste}
+        />,
+      );
+      const textbox = screen.getByRole('textbox');
+      textbox.focus();
+      clearSelection();
+
+      fireEvent.paste(textbox, {
+        clipboardData: {
+          files: [],
+          getData: (type: string) => (type === 'text/plain' ? 'hello' : ''),
+        },
+      });
+
+      expect(textbox.textContent).toBe('hello');
+      expect(onChange).toHaveBeenCalledTimes(1);
+      expect(onChange).toHaveBeenCalledWith('hello');
+    });
+
     it('paste falls through to plain-text path when pasteAsToken={false}', () => {
       const onChange = vi.fn();
       render(<ChatComposerInput pasteAsToken={false} onChange={onChange} />);
@@ -1394,6 +1482,28 @@ describe('ChatComposerInput', () => {
 
       expect(textbox.getAttribute('aria-expanded')).toBe('true');
     });
+
+    it('emits once when a string trigger result is selected', async () => {
+      const {textbox, onChange} = setupTriggerInput([createCommandTrigger()]);
+
+      setCursorAfterText(textbox, '/');
+      fireEvent.input(textbox);
+      await waitFor(() => {
+        const menu = document.getElementById(
+          textbox.getAttribute('aria-controls')!,
+        );
+        expect(
+          menu?.querySelectorAll('[role="option"]').length ?? 0,
+        ).toBeGreaterThan(0);
+      });
+      onChange.mockClear();
+
+      fireEvent.keyDown(textbox, {key: 'Enter'});
+
+      expect(textbox.textContent).toBe('/summarize ');
+      expect(onChange).toHaveBeenCalledTimes(1);
+      expect(onChange).toHaveBeenCalledWith('/summarize ');
+    });
   });
 
   describe('trigger menu hover scrolling', () => {