@astryxdesign/core 0.7.1-canary.ff40b78 → 0.7.1

package/src/Carousel/__tests__/Carousel.a11y.states.ts

@@ -0,0 +1,139 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Carousel.a11y.states.ts
+ * @input Uses CarouselStateFacts from @astryxdesign/a11y-spec
+ * @output The AST-021 binding inventory for Carousel semantic parts
+ * @position Data-only inventory shared by jsdom, Storybook, and Chromium bindings.
+ */
+
+import type {CarouselStateFacts} from '@astryxdesign/a11y-spec';
+
+export interface CarouselBindingState {
+  readonly id: string;
+  readonly summary: string;
+  readonly facts: CarouselStateFacts;
+  readonly subject:
+    | {readonly role: 'region' | 'group' | 'button'; readonly name: string}
+    | {readonly selector: string};
+  readonly relations?: Readonly<Record<string, {readonly selector: string}>>;
+  readonly storyId: string;
+}
+
+export type CarouselBindingRow = CarouselBindingState;
+
+const story = (id: string) => `a11y-carousel-pattern--${id}`;
+const slideRelations = {
+  'slide-1': {selector: '[role="group"][aria-label="Slide 1 of 4"]'},
+  'slide-2': {selector: '[role="group"][aria-label="Slide 2 of 4"]'},
+  'slide-3': {selector: '[role="group"][aria-label="Slide 3 of 4"]'},
+  'slide-4': {selector: '[role="group"][aria-label="Slide 4 of 4"]'},
+} as const;
+
+export const CAROUSEL_BINDING_STATES = [
+  {
+    id: 'container-labelled',
+    summary: 'the labelled Carousel region and all four slides',
+    facts: {
+      part: 'container',
+      expectedName: 'Featured work',
+      slideRelations: Object.keys(slideRelations),
+      offscreen: false,
+      scrollable: false,
+      focusable: false,
+      preservesControlFocus: false,
+    },
+    subject: {role: 'region', name: 'Featured work'},
+    relations: slideRelations,
+    storyId: story('container-labelled'),
+  },
+  {
+    id: 'slide-visible',
+    summary: 'the first visible positional slide',
+    facts: {
+      part: 'slide',
+      expectedName: 'Slide 1 of 4',
+      slideRelations: [],
+      offscreen: false,
+      scrollable: false,
+      focusable: false,
+      preservesControlFocus: false,
+    },
+    subject: {role: 'group', name: 'Slide 1 of 4'},
+    storyId: story('slide-visible'),
+  },
+  {
+    id: 'slide-offscreen',
+    summary: 'the fourth off-screen slide that remains exposed',
+    facts: {
+      part: 'slide',
+      expectedName: 'Slide 4 of 4',
+      slideRelations: [],
+      offscreen: true,
+      scrollable: false,
+      focusable: false,
+      preservesControlFocus: false,
+    },
+    subject: {role: 'group', name: 'Slide 4 of 4'},
+    storyId: story('slide-offscreen'),
+  },
+  {
+    id: 'scroller-keyboard',
+    summary: 'the native horizontal scroll container in the tab sequence',
+    facts: {
+      part: 'scroller',
+      expectedName: '',
+      slideRelations: [],
+      offscreen: false,
+      scrollable: true,
+      focusable: true,
+      preservesControlFocus: false,
+    },
+    subject: {
+      selector: '[data-testid="carousel-a11y"] > .astryx-carousel-scroller',
+    },
+    storyId: story('scroller-keyboard'),
+  },
+  {
+    id: 'next-control-focus',
+    summary: 'the looping next control, which stays enabled and keeps focus',
+    facts: {
+      part: 'control',
+      expectedName: 'Scroll right',
+      slideRelations: [],
+      offscreen: false,
+      scrollable: false,
+      focusable: true,
+      preservesControlFocus: true,
+    },
+    subject: {role: 'button', name: 'Scroll right'},
+    storyId: story('next-control-focus'),
+  },
+] as const satisfies ReadonlyArray<CarouselBindingState>;
+
+export const CAROUSEL_EXCLUSIONS = [
+  {
+    owner: 'Button pattern',
+    classification: 'preserved',
+    reason:
+      'Navigation-control role, name, activation, unavailable state, and pointer cancellation remain owned by the shared Button contract.',
+  },
+  {
+    owner: 'Carousel implementation and visual gate',
+    classification: 'preserved',
+    reason:
+      'Scroll distance, snapping, looping, edge fades, focus-ring paint, target geometry, and reduced-motion behavior remain component-owned browser and visual evidence.',
+  },
+  {
+    owner: 'Caller content',
+    classification: 'out-of-scope',
+    reason:
+      'Slide descendants keep their own image, link, control, reading-order, and language obligations.',
+  },
+  {
+    owner: 'Automatic rotation',
+    classification: 'out-of-scope',
+    reason:
+      'Carousel does not auto-advance; the public docs explicitly tell consumers not to auto-advance items.',
+  },
+] as const;

package/src/Carousel/__tests__/Carousel.a11y.test.tsx

@@ -0,0 +1,127 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @vitest-environment jsdom */
+
+/**
+ * @file Carousel.a11y.test.tsx
+ * @input Uses the shared Carousel contract and complete Carousel binding inventory
+ * @output DOM-layer binding evidence; browser-owned outcomes remain explicitly unrun
+ * @position Fast migration lane for Carousel container, slides, scroller, and control.
+ */
+
+import {cleanup, render, screen} from '@testing-library/react';
+import {describe, expect, it} from 'vitest';
+import {
+  CAROUSEL_PATTERN,
+  checkAccessibilitySpec,
+  createJsdomHarness,
+  expectAccessibilitySpec,
+  summarize,
+  type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {CAROUSEL_KNOWN_FAILURES} from './Carousel.a11y.known-failures';
+import {CAROUSEL_STATE_RENDERS} from './Carousel.a11y.renders';
+import {
+  CAROUSEL_BINDING_STATES,
+  CAROUSEL_EXCLUSIONS,
+  type CarouselBindingRow,
+} from './Carousel.a11y.states';
+
+function subjectFor(state: CarouselBindingRow): Element {
+  if ('selector' in state.subject) {
+    const element = document.querySelector(state.subject.selector);
+    if (element == null) {
+      throw new Error(`no subject for ${state.id}`);
+    }
+    return element;
+  }
+  return screen.getByRole(state.subject.role, {
+    name: state.subject.name,
+    hidden: true,
+  });
+}
+
+function relatedFor(
+  state: CarouselBindingRow,
+): Readonly<Record<string, Element>> {
+  return Object.fromEntries(
+    Object.entries(state.relations ?? {}).map(([name, relation]) => {
+      const element = document.querySelector(relation.selector);
+      if (element == null) {
+        throw new Error(`no related subject "${name}" for ${state.id}`);
+      }
+      return [name, element];
+    }),
+  );
+}
+
+async function checkState(state: CarouselBindingRow): Promise<BindingResult> {
+  return checkAccessibilitySpec({
+    spec: CAROUSEL_PATTERN,
+    binding: 'Carousel',
+    state: state.id,
+    facts: state.facts,
+    knownFailures: CAROUSEL_KNOWN_FAILURES,
+    mount: async () => {
+      render(CAROUSEL_STATE_RENDERS[state.id]());
+      return createJsdomHarness({
+        subject: subjectFor(state),
+        related: relatedFor(state),
+      });
+    },
+    unmount: cleanup,
+  });
+}
+
+describe('the shared Carousel pattern, jsdom lane', () => {
+  it.each(
+    CAROUSEL_BINDING_STATES.map(
+      state => [`Carousel [${state.id}]`, state.summary, state] as const,
+    ),
+  )('%s — %s', async (_id, _summary, state) => {
+    await expectAccessibilitySpec({
+      spec: CAROUSEL_PATTERN,
+      binding: 'Carousel',
+      state: state.id,
+      facts: state.facts,
+      knownFailures: CAROUSEL_KNOWN_FAILURES,
+      render: () => {
+        render(CAROUSEL_STATE_RENDERS[state.id]());
+      },
+      subject: () => subjectFor(state),
+      related: () => relatedFor(state),
+      cleanup,
+    });
+  });
+
+  it('runs DOM expectations and reports higher layers as unrun', async () => {
+    const results: BindingResult[] = [];
+    for (const state of CAROUSEL_BINDING_STATES) {
+      results.push(await checkState(state));
+    }
+    const report = summarize(CAROUSEL_PATTERN, results);
+    expect(report.counts.pass).toBeGreaterThan(0);
+    expect(report.unrunLayers).toEqual(['accessibility-tree', 'real-browser']);
+    expect(report.counts.unexpectedPass).toBe(0);
+  });
+});
+
+describe('the Carousel binding inventory', () => {
+  it('names a distinct checked-in story for every state', () => {
+    const ids = CAROUSEL_BINDING_STATES.map(state => state.storyId);
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  it('records every excluded owner explicitly', () => {
+    expect(CAROUSEL_EXCLUSIONS.every(row => row.owner && row.reason)).toBe(
+      true,
+    );
+  });
+
+  it('renders exactly one subject for every state', () => {
+    for (const state of CAROUSEL_BINDING_STATES) {
+      render(CAROUSEL_STATE_RENDERS[state.id]());
+      expect(subjectFor(state), state.id).toBeTruthy();
+      cleanup();
+    }
+  });
+});

package/src/Chat/ChatComposerInput.doc.mjs

@@ -98,7 +98,7 @@ export const docs = {
       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. Per-trigger emptySearchText (ReactNode) is the message when the query matched nothing.',
+        'Trigger definitions for typeahead menus. Each trigger specifies a character (@ or /), a search source, and an onSelect handler that returns the token to insert. Set hasMultiWordQuery: true when suggestions contain spaces (people, topics): the query then runs to a line break or about 64 characters instead of ending at the first space. Per-trigger emptySearchText (ReactNode) is the message when the query matched nothing.',
     },
     {
       name: 'debounceMs',

package/src/Chat/ChatComposerInput.spec.md

@@ -3,11 +3,11 @@ schema_version: 3
 template_version: 5
 kind: component
 id: component:ChatComposerInput
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-14
 owners: [cixzhang]
 review_triggers: [public-api, behavior, accessibility, interaction, theming]
 verified_by:
@@ -33,15 +33,15 @@ system_specs: [spec:AST-002, spec:AST-029]
 
 ## 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.                                        |
+| 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.
 
@@ -55,9 +55,15 @@ imperative editing handle.
 ## Compatibility and migration
 
 - Released default preserved: yes
-- Compatibility class: patch-compatible behavior correction; no public type or default changes
+- 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
 
@@ -82,6 +88,7 @@ imperative editing handle.
 | 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.           |
@@ -89,17 +96,24 @@ imperative editing handle.
 
 ## 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             |
+| 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
 
@@ -109,27 +123,29 @@ imperative editing handle.
 
 ### 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. |
+| 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.
-- **ORD5 — File intake.** Files on clipboard or data transfer → prevent native behavior → emit `onFiles` when enabled.
+- **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 and debounce ownership remain in `useTriggerMenu` and the supplied `SearchSource`.
+- **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
@@ -138,19 +154,20 @@ imperative editing handle.
 - **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                |
-| inline token     | structured Badge or caller content | Badge or caller owner    | supporting     | AV2                |
+| 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 observational
-draft does not add a theming target or decide a new visual state.
+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
 
@@ -161,18 +178,40 @@ draft does not add a theming target or decide a new visual state.
 
 ## 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`           |
+| 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
 
-No component-local policy decision is created by this observational draft.
+### 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
 
@@ -181,5 +220,5 @@ 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.
+or visual design rationale. It records shipped behavior, objective corrections, and
+the trigger-query contract in DEC-1, without deciding a new visual representation.