@astryxdesign/core 0.7.1-canary.ff40b78 → 0.7.1

package/src/CommandPalette/CommandPalette.spec.md

@@ -1,6 +1,6 @@
 ---
 schema_version: 3
-template_version: 3
+template_version: 7
 kind: component
 id: component:CommandPalette
 authority: draft
@@ -18,6 +18,7 @@ verified_by:
     packages/core/src/CommandPalette/CommandPaletteItem.test.tsx,
     packages/core/src/CommandPalette/CommandPaletteGroup.test.tsx,
     packages/core/src/CommandPalette/CommandPaletteFooter.test.tsx,
+    packages/core/src/CommandPalette/__tests__/CommandPalette.a11y.chromium.spec.ts,
     packages/core/src/CommandPalette/__tests__/CommandPaletteFooter.a11y.chromium.spec.ts,
     packages/core/src/theme/themingTargets.test.ts,
     scripts/check-knowledge.mjs,
@@ -32,24 +33,43 @@ architecture:
     architecture:public-component-api,
   ]
 contributing: []
-system_specs: []
+system_specs: [spec:AST-056]
 ---
 
 # CommandPalette component contract
 
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                     |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | Prop and visual APIs are unchanged. The result surface exposes listbox semantics only with selectable results; the query input has a real default name; rich Empty content remains ordinary. |
+| Behavior                | Modal Escape delegates to Dialog; query-field Home/End and IME remain native; result changes reset stale highlight; Empty announcements mirror rendered content.                             |
+| End-user impact         | Nested dismissal and native text entry are preserved; assistive technology receives the visible empty message, an independent query-field name, and only existing active options.            |
+| Builder impact          | None; no migration or new caller choice.                                                                                                                                                     |
+| Compatibility/readiness | Visual output is preserved. Empty-result ARIA, query-field accessible naming, empty-state announcement, and highlight reset behavior are corrected and verified.                             |
+| Review checks           | Reject local modal Escape handling, IME routing, Home/End result navigation, empty listboxes, stale active descendants, placeholder-only names, mismatched Empty announcements, or gaps.     |
+| Governing rules         | `family:overlay-dismissal/FR1`, `FR2`, `FR4`, `FR5`; `spec:AST-056/FR3`, `AR1`, `AR2`; existing public component and delegated-owner contracts.                                              |
+
+This table is a review projection; the body below is authoritative.
+
 ## Intent
 
-CommandPalette presents searchable commands inside a Dialog. This draft records
-its current aggregate consumer anatomy, target ownership, and delegated stable
-parts without changing runtime behavior, styling, targets, or public API.
+CommandPalette presents searchable commands inside a Dialog. It owns search and
+selection orchestration plus the aggregate consumer anatomy while delegating its
+surface and modal dismissal ordering to Dialog.
 
 ## Compatibility and migration
 
-- Released default preserved: `yes`
-- Compatibility class: additive documentation only; runtime, DOM, styling,
-  targets, aliases, and public API remain unchanged
+- Released default preserved: `yes` for props and visual output
+- Compatibility class: behavioral and accessibility correction; empty states
+  conditionally omit listbox, expanded, controls, and active-descendant ARIA
+  attributes until selectable results exist; the default query accessible name
+  is independent of its placeholder; empty-search announcements mirror the
+  rendered content; public props, styling, targets, and visible defaults remain
+  unchanged
 - Controlled/uncontrolled behavior: unchanged
-- Migration decision: none
+- Migration decision: adopts `family:overlay-dismissal/FR1`, `FR2`, `FR4`, and
+  `FR5` through Dialog; no caller migration
 
 Consumer migration instructions belong in consumer docs and release notes.
 
@@ -57,9 +77,9 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 **Owns**
 
-- Search orchestration and the current Input, List, Item, Group, Group heading,
-  Empty, and Footer parts and targets.
-- The native Query field rendered inside the default Input.
+- Search orchestration and composition of the current Input, List, Item, Group,
+  Group heading, Empty, and Footer parts and targets.
+- Composition of the native Query field rendered inside the default Input; the field's semantics and native passthrough are owned by `component:CommandPaletteInput`.
 
 **Does not own / non-goals**
 
@@ -67,6 +87,8 @@ Consumer migration instructions belong in consumer docs and release notes.
   badges — owned by their respective components.
 - Caller-provided replacement Input, Footer, item content, or trailing input
   content — owned by the product callsite.
+- The Item option's passthrough, pointer, disabled, selected, highlighted, and
+  standalone-scroll semantics — owned by `component:CommandPaletteItem`.
 - A `command-palette` root target — no such current target exists, and this
   factual backfill does not invent one.
 - Shared layer hosting, positioning, or lifecycle rules beyond the current
@@ -81,12 +103,16 @@ documented in `CommandPalette.doc.mjs` and its subcomponent docs.
 
 ## Behavioral and layout contract
 
-| ID  | Candidate invariant                                                                                                                                                                                 | Basis                             | Draft review state                                                                    |
-| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------- |
-| FR1 | The current default render places Input and Footer around a List inside a delegated Dialog; the List contains Items, optional Groups and Group headings, or Empty according to the current results. | Current source, docs, and tests   | Verified current behavior; no new behavior decided                                    |
-| FR2 | Input, List, Item, Group, Group heading, Empty, and Footer carry the seven current `command-palette-*` targets documented below; no `command-palette` root target exists.                           | Current source and target docs    | Verified current inventory; focused placement covers Group, Group heading, and Footer |
-| FR3 | The default Input delegates its Search glyph to Icon and pending Loading spinner to Spinner; the default Footer delegates keyboard shortcuts to Kbd; the containing surface delegates to Dialog.    | Current source and component docs | Footer-to-Kbd composition is focused-test verified; no ownership change               |
-| FR4 | Query field is a distinct native text field inside Input and currently has no separate public target. The `command-palette-input` target is on the surrounding search region, not the native field. | Current source and target docs    | Verified current reachability; long-term theming intent remains unsettled             |
+| ID  | Candidate invariant                                                                                                                                                                                 | Basis                                                          | Draft review state                                                        |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| FR1 | The current default render places Input and Footer around a result surface inside a delegated Dialog. That surface is a List listbox while Items exist and an ordinary Empty container otherwise.   | Current source, docs, tests, and ARIA required-child rule      | Verified current anatomy and valid rich Empty semantics                   |
+| FR2 | Input, List, Item, Group, Group heading, Empty, and Footer carry the seven current `command-palette-*` targets documented below; no `command-palette` root target exists.                           | Current source and target docs                                 | Verified current inventory and focused placement coverage                 |
+| FR3 | The default Input delegates its Search glyph to Icon and pending Loading spinner to Spinner; the default Footer delegates keyboard shortcuts to Kbd; the containing surface delegates to Dialog.    | Current source and component docs                              | Verified current composition; no ownership change                         |
+| FR4 | Query field is a distinct native text field inside Input and currently has no separate public target. The `command-palette-input` target is on the surrounding search region, not the native field. | Current source and target docs                                 | Verified current reachability; long-term theming intent remains unsettled |
+| FR5 | A modal palette leaves Escape unclaimed for Dialog's shared dismissal stack so a nested member handles the first press; inline previews close locally because they do not register as layers.       | `family:overlay-dismissal/FR1`, `FR2`, `FR4`, `FR5`            | Verified by nested and inline integration tests                           |
+| FR6 | The editable query field keeps Home and End for native caret movement, uses PageUp and PageDown for first/last result navigation, and does not route active IME composition keys to commands.       | WAI-ARIA editable combobox convention; objective IME integrity | Verified by user-event navigation and composition-key tests               |
+| FR7 | A committed result set resets highlight before exposure; the query input emits active-descendant only for an index that exists in the current selectable set.                                       | WAI-ARIA active-descendant integrity                           | Verified across populated, empty, and repopulated results                 |
+| FR8 | Empty search announcements mirror rendered `emptySearchText`, including rich caller content; the query input's default accessible name is independent of its placeholder.                           | `spec:AST-056/FR3`, `AR1`, `AR2`                               | Verified by live-region and accessible-name tests                         |
 
 ### Allowed variation
 
@@ -99,14 +125,14 @@ documented in `CommandPalette.doc.mjs` and its subcomponent docs.
 
 ### Representative states
 
-| State                  | Required invariant                                      | Allowed variation                               |
-| ---------------------- | ------------------------------------------------------- | ----------------------------------------------- |
-| Ungrouped results      | List contains Item instances.                           | Item count and caller-rendered content.         |
-| Grouped results        | List contains Group, Group heading, and Item instances. | Group names, count, ordering, and item content. |
-| Empty bootstrap/search | List contains Empty instead of Items.                   | Caller-provided empty content.                  |
-| Pending search         | Default Input may contain Loading spinner.              | Spinner is absent when no search is pending.    |
-| Default slots          | Input and Footer render their documented defaults.      | Footer shortcut text and translated labels.     |
-| Caller-replaced slots  | The slot content replaces the corresponding default.    | Replacement structure remains caller-owned.     |
+| State                  | Required invariant                                                            | Allowed variation                                          |
+| ---------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| Ungrouped results      | List contains Item instances.                                                 | Item count and caller-rendered content.                    |
+| Grouped results        | List contains Group, Group heading, and Item instances.                       | Group names, count, ordering, and item content.            |
+| Empty bootstrap/search | Empty replaces listbox semantics; search-empty text is announced as rendered. | Caller-provided rich content, including ordinary controls. |
+| Pending search         | Default Input may contain Loading spinner.                                    | Spinner is absent when no search is pending.               |
+| Default slots          | Input and Footer render their documented defaults.                            | Footer shortcut text and translated labels.                |
+| Caller-replaced slots  | The slot content replaces the corresponding default.                          | Replacement structure remains caller-owned.                |
 
 ### Transformation and precedence order
 
@@ -118,8 +144,27 @@ documented in `CommandPalette.doc.mjs` and its subcomponent docs.
 
 ## Accessibility contract
 
-This draft does not change or extend CommandPalette's current Dialog, combobox,
-listbox, option, announcement, or keyboard behavior.
+- **AR1 — Named composite.** The containing Dialog, combobox, populated listbox,
+  groups, options, busy status, empty state, and keyboard guidance preserve their
+  owned accessible names and roles. When no selectable results exist, the result
+  surface and combobox omit listbox, expanded, controls, and active-descendant
+  semantics so rich Empty content stays ordinary non-nested content.
+- **AR2 — Topmost Escape.** A modal palette delegates unclaimed Escape presses to
+  Dialog's shared dismissal stack. A nested registered surface handles the first
+  press; the host palette remains open until it becomes topmost.
+- **AR3 — Inline preview.** Documentation-only inline rendering remains outside
+  the shared layer stack and preserves its local Escape close behavior.
+- **AR4 — Editable query keys.** Home and End preserve native caret movement;
+  PageUp and PageDown navigate to the first and last results; active IME
+  composition keys remain owned by the input method.
+- **AR5 — Rendered empty message.** A search dead end announces the text rendered
+  by `emptySearchText`, including text produced by caller components and links.
+- **AR6 — Query-field name.** The default query field name is a localized
+  "Search commands" label independent of its placeholder; caller `label` and
+  native `aria-label` overrides remain supported.
+- **AR7 — Existing active option.** Result changes reset highlight, and
+  `aria-activedescendant` is present only when the indexed option exists in the
+  current selectable set.
 
 ## Design relationships
 
@@ -185,27 +230,36 @@ current audit gap and does not authorize a new target.
   mapping, delegation, and factual `none` dispositions.
 - `architecture:public-component-api` owns the stable props and composition
   surface; this documentation adds no API.
-- `architecture:interaction-modality` owns shared keyboard and pointer modality;
-  this draft does not redefine focus ownership or input behavior.
-- `family:overlay-dismissal` identifies CommandPalette as a current member and
-  records its component-local Escape handling as an adoption gap.
-- No layer-runtime record is linked because no current record with that scope is
-  present in this checkout.
+- `architecture:interaction-modality/INV4` owns supported-modality path
+  reachability; the exact query-key details follow objective editable-combobox
+  and IME composition standards.
+- `spec:AST-056/FR3`, `AR1`, and `AR2` own rendered empty-search announcement
+  parity and an accessible query-field name independent of placeholder text.
+- `family:overlay-dismissal` owns topmost Escape and close-request ordering;
+  CommandPalette adopts it through Dialog while preserving local inline-preview
+  closing because inline mode does not register as a layer.
+- `architecture:layer-runtime` records that the modal path delegates Escape to
+  Dialog's shared dismissal registration while the unregistered inline preview
+  preserves local closing.
 
 ## Verification map
 
-| Contract            | Verification                                                                       | Representative states                                           | Mutation or failure expectation                                                                                                                                                                                                            | Audit section                  |
-| ------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ |
-| FR1                 | CommandPalette root and subcomponent render suites plus browser evidence           | Default, grouped, empty, pending, and replaced slots            | Removing the asserted Dialog, Query field, List, Item, Group, Group heading, Empty, or Footer content fails role, content, slot, or exact-head browser assertions; Search glyph and Loading spinner presence remain source-inspected only. | `audit:CommandPalette/anatomy` |
-| FR2                 | `themingTargets.test.ts`, focused subcomponent suites, and browser evidence        | Seven local targets; Group, Group heading, and Footer placement | Removing a current target fails the global inventory; moving Group, Group heading, or Footer fails focused class assertions and the Footer browser receipt.                                                                                | `audit:CommandPalette/theming` |
-| FR3                 | Focused Footer suite and browser evidence plus delegated component target metadata | Default surface, Input visuals, and Footer shortcuts            | Removing Footer's four Kbd shortcuts or either stable target fails focused unit and browser assertions; Icon and Spinner composition remain source-inspected.                                                                              | `audit:CommandPalette/theming` |
-| FR4                 | `CommandPaletteInput.test.tsx` and source inspection                               | Native query field with idle and pending Input                  | Removing the field fails combobox tests; adding a field target requires an explicit map update.                                                                                                                                            | `audit:CommandPalette/anatomy` |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                                      | Canonical anatomy and seven current local targets               | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation.                                                                                                                                                      | `audit:CommandPalette/theming` |
-
-Focused target-placement assertions cover Group, Group heading, and Footer.
-Input, List, Item, and Empty placement rely on source inspection plus the global
-target inventory. Focused Footer tests pin all four default Kbd instances; Icon
-and Spinner composition remain source-inspected.
+| Contract            | Verification                                                                          | Representative states                                            | Mutation or failure expectation                                                                                                                                      | Audit section                      |
+| ------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
+| FR1, AR1            | CommandPalette root and subcomponent suites plus exact-head Chromium evidence         | Default, grouped, empty, pending, rich Empty, and replaced slots | Exposing an empty listbox, leaving empty Input popup attributes, or nesting rich Empty controls under option semantics fails focused role and hosted axe assertions. | `audit:CommandPalette/anatomy`     |
+| FR2                 | Focused subcomponent suites and `themingTargets.test.ts`                              | Seven local targets at their owned elements                      | Removing or moving a current target fails a focused placement assertion or the global inventory.                                                                     | `audit:CommandPalette/theming`     |
+| FR3                 | `CommandPaletteInput.test.tsx`, `CommandPaletteFooter.test.tsx`, and browser evidence | Default Search glyph, pending spinner, and Footer Kbd            | Replacing or removing the delegated Icon, Spinner, or Kbd instance fails a composed-owner assertion and changes the exact-head evidence inventory.                   | `audit:CommandPalette/theming`     |
+| FR4                 | `CommandPaletteInput.test.tsx` and source inspection                                  | Native query field with idle and pending Input                   | Removing the field fails combobox tests; adding a field target requires an explicit map update.                                                                      | `audit:CommandPalette/anatomy`     |
+| FR5, AR2, AR3       | `CommandPalette.test.tsx`                                                             | Modal host with nested layer; inline preview                     | Restoring local modal Escape handling closes the host instead of the nested surface; removing the inline branch loses preview closing.                               | `audit:CommandPalette/interaction` |
+| FR6, AR4            | `CommandPalette.test.tsx` and `CommandPaletteInput.test.tsx`                          | Home, End, PageDown, Enter, and active IME composition           | Routing Home/End to results or forwarding a composing command key fails user-event and native composition assertions.                                                | `audit:CommandPalette/interaction` |
+| FR7, AR7            | `CommandPalette.test.tsx` and `CommandPaletteInput.test.tsx`                          | Populated, empty, and repopulated result sets                    | Preserving an out-of-range highlight or emitting its nonexistent active descendant fails transition and direct bounds assertions.                                    | `audit:CommandPalette/a11y`        |
+| FR8, AR5, AR6       | `CommandPalette.test.tsx`, `CommandPaletteInput.test.tsx`, and i18n checks            | Rich caller Empty content; default and caller query names        | Announcing catalog copy over rendered caller content or naming the query only through placeholder text fails live-region, name, and catalog assertions.              | `audit:CommandPalette/a11y`        |
+| Theming anatomy map | `scripts/check-knowledge.mjs` and exact-head Chromium evidence                        | Canonical anatomy and seven current local targets                | Missing, extra, prefixed, stale, alias-backed, or visually absent mappings fail repository validation or browser sensor counts.                                      | `audit:CommandPalette/theming`     |
+
+Focused target-placement assertions cover all seven local targets. The composed
+Input and Footer tests also pin the delegated Search Icon, pending Spinner, and
+four default Kbd shortcuts; exact-head browser evidence verifies the same owned
+anatomy across light, dark, LTR, RTL, and narrow rendering.
 
 ## Decision log
 
@@ -216,9 +270,6 @@ layer, API, or theming decision.
 
 - **OQ1 — Should Query field gain a stable public theming target?** (`human-api`)
   Its current lack of direct reachability is an audit gap, not settled intent.
-- **OQ2 — Should focused tests pin the default Search glyph and pending Loading
-  spinner?** (`checkable`) Their presence is currently source-inspected rather
-  than asserted.
 
 ## Content boundary
 

package/src/CommandPalette/CommandPalette.test.tsx

@@ -9,8 +9,11 @@
 
 import {describe, it, expect, vi, beforeEach} from 'vitest';
 import {render, screen, waitFor, fireEvent, act} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import {useState} from 'react';
 import {CommandPalette} from './CommandPalette';
+import {CommandPaletteInput} from './CommandPaletteInput';
+import {useLayerDismissal} from '../Layer/useLayerDismissal';
 import {createStaticSource} from '@astryxdesign/core/Typeahead';
 import type {SearchSource, SearchableItem} from '@astryxdesign/core/Typeahead';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
@@ -27,6 +30,11 @@ const groupedSource = createStaticSource([
 
 const emptySource = createStaticSource([]);
 
+function NestedDismissible({onDismiss}: {onDismiss: () => void}) {
+  useLayerDismissal({isActive: true, onDismiss});
+  return null;
+}
+
 // Mock showModal and close since jsdom doesn't implement them
 beforeEach(() => {
   HTMLDialogElement.prototype.showModal = vi.fn(function (
@@ -198,6 +206,31 @@ describe('CommandPalette', () => {
     });
   });
 
+  it('keeps actionable empty content outside listbox semantics', async () => {
+    const {container} = render(
+      <CommandPalette
+        isOpen={true}
+        onOpenChange={() => {}}
+        searchSource={emptySource}
+        emptyBootstrapText={<a href="/commands/new">Create a command</a>}
+      />,
+    );
+
+    expect(
+      await screen.findByRole('link', {name: 'Create a command'}),
+    ).toHaveAttribute('href', '/commands/new');
+    expect(screen.queryByRole('listbox')).not.toBeInTheDocument();
+    expect(screen.queryByRole('option')).not.toBeInTheDocument();
+    expect(
+      container.querySelectorAll('.astryx-command-palette-empty'),
+    ).toHaveLength(1);
+    expect(screen.getByRole('combobox')).toHaveAttribute(
+      'aria-expanded',
+      'false',
+    );
+    expect(screen.getByRole('combobox')).not.toHaveAttribute('aria-controls');
+  });
+
   it('shows default emptyBootstrapText when not provided', async () => {
     render(
       <CommandPalette
@@ -211,6 +244,40 @@ describe('CommandPalette', () => {
     });
   });
 
+  it('clears a stale highlight across empty and repopulated results', async () => {
+    render(
+      <CommandPalette
+        isOpen={true}
+        onOpenChange={() => {}}
+        searchSource={simpleSource}
+      />,
+    );
+    await waitFor(() =>
+      expect(screen.getByText('Settings')).toBeInTheDocument(),
+    );
+
+    const input = screen.getByRole('combobox');
+    fireEvent.keyDown(input, {key: 'ArrowDown'});
+    fireEvent.keyDown(input, {key: 'ArrowDown'});
+    expect(input.getAttribute('aria-activedescendant')).toMatch(/-item-1$/);
+
+    fireEvent.change(input, {target: {value: 'zzz'}});
+    await waitFor(() => expect(screen.queryByRole('listbox')).toBeNull());
+    expect(input).not.toHaveAttribute('aria-activedescendant');
+
+    fireEvent.change(input, {target: {value: 'hom'}});
+    await waitFor(() =>
+      expect(screen.getByRole('option', {name: 'Home'})).toBeInTheDocument(),
+    );
+    expect(input).not.toHaveAttribute('aria-activedescendant');
+
+    fireEvent.keyDown(input, {key: 'ArrowDown'});
+    expect(input).toHaveAttribute(
+      'aria-activedescendant',
+      screen.getByRole('option', {name: 'Home'}).id,
+    );
+  });
+
   it('calls onOpenChange(false) when Escape is pressed', () => {
     const handleOpenChange = vi.fn();
     render(
@@ -230,6 +297,46 @@ describe('CommandPalette', () => {
     expect(handleOpenChange).toHaveBeenCalledWith(false);
   });
 
+  it('lets the topmost nested layer handle Escape before the palette', () => {
+    const handleOpenChange = vi.fn();
+    const handleNestedDismiss = vi.fn();
+    render(
+      <CommandPalette
+        isOpen={true}
+        onOpenChange={handleOpenChange}
+        searchSource={simpleSource}
+        input={
+          <>
+            <CommandPaletteInput />
+            <NestedDismissible onDismiss={handleNestedDismiss} />
+          </>
+        }
+      />,
+    );
+
+    fireEvent.keyDown(screen.getByRole('combobox'), {key: 'Escape'});
+
+    expect(handleNestedDismiss).toHaveBeenCalledOnce();
+    expect(handleOpenChange).not.toHaveBeenCalled();
+  });
+
+  it('preserves local Escape closing for inline previews', () => {
+    const handleOpenChange = vi.fn();
+    render(
+      <CommandPalette
+        isOpen={true}
+        isInline
+        onOpenChange={handleOpenChange}
+        searchSource={simpleSource}
+      />,
+    );
+
+    fireEvent.keyDown(screen.getByRole('combobox'), {key: 'Escape'});
+
+    expect(handleOpenChange).toHaveBeenCalledOnce();
+    expect(handleOpenChange).toHaveBeenCalledWith(false);
+  });
+
   it('keeps the empty state mounted while a no-result search is pending', async () => {
     // A source whose searches resolve only when we release them, so we can
     // observe the render output while a search transition is in flight.
@@ -357,6 +464,52 @@ describe('CommandPalette', () => {
     expect(input).not.toHaveAttribute('aria-activedescendant');
   });
 
+  it('keeps Home and End on the query field and uses Page keys for results', async () => {
+    const user = userEvent.setup();
+    const handleOpenChange = vi.fn();
+    const handleValueChange = vi.fn();
+    render(
+      <CommandPalette
+        isOpen={true}
+        onOpenChange={handleOpenChange}
+        onValueChange={handleValueChange}
+        searchSource={simpleSource}
+      />,
+    );
+
+    const input = screen.getByRole<HTMLInputElement>('combobox');
+    await waitFor(() =>
+      expect(screen.getByText('Settings')).toBeInTheDocument(),
+    );
+    await user.click(input);
+    await user.type(input, 'e');
+    await waitFor(() =>
+      expect(screen.getByText('Settings')).toBeInTheDocument(),
+    );
+    const homeOption = screen.getByText('Home').closest('[role="option"]');
+    const settingsOption = screen
+      .getByText('Settings')
+      .closest('[role="option"]');
+
+    expect(input).toHaveValue('e');
+    expect(input.selectionStart).toBe(1);
+    await user.keyboard('{Home}');
+    expect(input.selectionStart).toBe(0);
+    await user.keyboard('{End}');
+    expect(input.selectionStart).toBe(1);
+    expect(input).not.toHaveAttribute('aria-activedescendant');
+
+    await user.keyboard('{PageDown}');
+    expect(input.getAttribute('aria-activedescendant')).toBe(
+      settingsOption?.id,
+    );
+    await user.keyboard('{PageUp}');
+    expect(input.getAttribute('aria-activedescendant')).toBe(homeOption?.id);
+    await user.keyboard('{Enter}');
+    expect(handleValueChange).toHaveBeenCalledWith('home');
+    expect(handleOpenChange).toHaveBeenCalledWith(false);
+  });
+
   it('highlights on hover without scrolling and scrolls once per key (#6077)', async () => {
     // Hover must be handled by the root's delegated list handler (routed to
     // useCombobox's hover-aware path), and the shared useHighlightedOptionScroll effect
@@ -453,19 +606,105 @@ describe('CommandPalette', () => {
       });
     });
 
-    it('announces the empty state with the query when nothing matches', async () => {
+    it('announces the rendered default empty state when nothing matches', async () => {
+      render(
+        <CommandPalette
+          isOpen={true}
+          onOpenChange={() => {}}
+          searchSource={simpleSource}
+        />,
+      );
+      await waitFor(() => expect(screen.getByText('Home')).toBeInTheDocument());
+      fireEvent.change(screen.getByRole('combobox'), {target: {value: 'zzz'}});
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent(/^No results$/);
+      });
+    });
+
+    it('announces rich emptySearchText exactly as rendered', async () => {
       render(
         <CommandPalette
           isOpen={true}
           onOpenChange={() => {}}
           searchSource={simpleSource}
+          emptySearchText={
+            <span>
+              Nothing like that here. <a href="/commands/new">Add a command</a>
+            </span>
+          }
         />,
       );
       await waitFor(() => expect(screen.getByText('Home')).toBeInTheDocument());
       fireEvent.change(screen.getByRole('combobox'), {target: {value: 'zzz'}});
+
+      expect(
+        await screen.findByRole('link', {name: 'Add a command'}),
+      ).toHaveAttribute('href', '/commands/new');
       await waitFor(() => {
-        expect(politeRegion()).toHaveTextContent('No results for zzz');
+        expect(politeRegion()).toHaveTextContent(
+          /^Nothing like that here\. Add a command$/,
+        );
+      });
+    });
+
+    it('waits for a narrowed search to settle before announcing no results', async () => {
+      const resolvers: ((items: SearchableItem[]) => void)[] = [];
+      const source: SearchSource = {
+        bootstrap: () => [
+          {id: 'home', label: 'Home'},
+          {id: 'settings', label: 'Settings'},
+        ],
+        async search(): Promise<SearchableItem[]> {
+          return new Promise<SearchableItem[]>(resolve => {
+            resolvers.push(resolve);
+          });
+        },
+      };
+      const spoken: string[] = [];
+      const observer = new MutationObserver(() => {
+        const text = politeRegion()?.textContent ?? '';
+        if (text !== '' && spoken.at(-1) !== text) {
+          spoken.push(text);
+        }
+      });
+      observer.observe(document.body, {
+        childList: true,
+        subtree: true,
+        characterData: true,
       });
+      try {
+        render(
+          <CommandPalette
+            isOpen={true}
+            onOpenChange={() => {}}
+            searchSource={source}
+          />,
+        );
+        await waitFor(() =>
+          expect(screen.getByText('Home')).toBeInTheDocument(),
+        );
+        const input = screen.getByRole('combobox');
+
+        fireEvent.change(input, {target: {value: 'e'}});
+        await act(async () =>
+          resolvers.shift()?.(source.bootstrap() as SearchableItem[]),
+        );
+        await waitFor(() => expect(spoken.at(-1)).toBe('2 results'));
+
+        // Optimistic narrowing empties the list while the source is still
+        // answering; the source then finds one match.
+        fireEvent.change(input, {target: {value: 'ez'}});
+        await act(async () => {
+          await new Promise(resolve => setTimeout(resolve, 50));
+        });
+        await act(async () =>
+          resolvers.shift()?.([{id: 'settings', label: 'Settings'}]),
+        );
+        await waitFor(() => expect(spoken.at(-1)).toBe('1 result'));
+        expect(spoken).not.toContain('No results');
+      } finally {
+        observer.disconnect();
+      }
     });
 
     it('announces loading politely while a search is in flight', async () => {