diff --git a/ui/src/components/PdSidebar.test.tsx b/ui/src/components/PdSidebar.test.tsx
new file mode 100644
index 0000000..d372fd7
--- /dev/null
+++ b/ui/src/components/PdSidebar.test.tsx
@@ -0,0 +1,45 @@
+import { render, screen } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { NAV_KEYS } from '@/components/nav'
+import { PdSidebar } from '@/components/PdSidebar'
+import { usePlanStore, useUiStore } from '@/stores'
+import { resetStore } from '@/test/stores'
+
+vi.mock('@/ipc', async () => {
+ const { ipcMock } = await import('@/test/ipc')
+ return ipcMock()
+})
+
+describe('PdSidebar', () => {
+ beforeEach(() => {
+ resetStore(usePlanStore)
+ useUiStore.setState({ nav: 'installed' })
+ })
+
+ it('tells assistive technology which shortcut each tab has', () => {
+ // The `^1`…`^9` hints are `aria-hidden`, so the shortcut was visible and nowhere else.
+ render()
+ const tabs = screen.getAllByRole('button')
+
+ expect(tabs).toHaveLength(NAV_KEYS.length)
+ expect(tabs.map((tab) => tab.getAttribute('aria-keyshortcuts'))).toEqual(
+ NAV_KEYS.map((_, i) => `Control+${String(i + 1)}`),
+ )
+ })
+
+ it('draws the shortcut hints in a token, not at half opacity', () => {
+ // `opacity-50` over `text-text-dim` measured about 2.6:1 on the sidebar's background. Being
+ // hidden from a screen reader does not make visible text exempt from contrast.
+ render()
+ for (const hint of screen.getAllByText(/^\^\d$/)) {
+ expect(hint.className).not.toMatch(/opacity-/)
+ expect(hint).toHaveClass('text-text-dim')
+ }
+ })
+
+ it('marks the tab that is showing', () => {
+ render()
+ expect(screen.getByRole('button', { current: 'page' })).toHaveTextContent('Installed')
+ })
+})
diff --git a/ui/src/components/PdSidebar.tsx b/ui/src/components/PdSidebar.tsx
index 9f15565..627cfbd 100644
--- a/ui/src/components/PdSidebar.tsx
+++ b/ui/src/components/PdSidebar.tsx
@@ -45,6 +45,9 @@ export function PdSidebar() {
diff --git a/ui/src/screens/PdSearch.test.tsx b/ui/src/screens/PdSearch.test.tsx
new file mode 100644
index 0000000..4149b2e
--- /dev/null
+++ b/ui/src/screens/PdSearch.test.tsx
@@ -0,0 +1,70 @@
+import { render, screen, within } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { Hit } from '@/ipc'
+import { PdSearch } from '@/screens/PdSearch'
+import { useEnvStore, usePlanStore } from '@/stores'
+import { useIndexStore } from '@/stores/index-search'
+import { resetStore } from '@/test/stores'
+
+vi.mock('@/ipc', async () => {
+ const { ipcMock } = await import('@/test/ipc')
+ return ipcMock()
+})
+
+const HITS: Hit[] = [
+ { name: 'numpy', display: 'numpy', kind: 'exact' },
+ { name: 'numpydoc', display: 'numpydoc', kind: 'prefix' },
+]
+
+describe('what Search says without being looked at', () => {
+ beforeEach(() => {
+ vi.clearAllMocks()
+ resetStore(useIndexStore)
+ resetStore(useEnvStore)
+ resetStore(usePlanStore)
+ })
+
+ it('keeps one status region on screen from the first render', () => {
+ // A live region announces *changes* to itself. One that is mounted together with its first
+ // message has no earlier state to differ from, and most readers say nothing.
+ render()
+ expect(screen.getByRole('status')).toBeInTheDocument()
+ expect(screen.getByRole('status')).toBeEmptyDOMElement()
+ })
+
+ it('says it is searching', () => {
+ useIndexStore.setState({ query: 'num', searching: true })
+ render()
+ expect(screen.getByRole('status')).toHaveTextContent('Searching…')
+ })
+
+ it('says the index is still loading', () => {
+ useIndexStore.setState({ ready: false })
+ render()
+ expect(screen.getByRole('status')).toHaveTextContent('Preparing the package index…')
+ })
+
+ it('says how many results came back', () => {
+ // The list simply appeared. Nothing told a screen-reader user that the keystroke had an
+ // answer, or how long the answer was.
+ useIndexStore.setState({ query: 'num', hits: HITS })
+ render()
+ expect(screen.getByRole('status')).toHaveTextContent('2 results')
+ })
+
+ it('says when nothing matched, in the region as well as in the empty state', () => {
+ useIndexStore.setState({ query: 'zzzz', hits: [] })
+ render()
+ expect(within(screen.getByRole('status')).getByText(/nothing matches/)).toHaveClass('sr-only')
+ })
+
+ it('marks the result whose details are showing', () => {
+ // Selection was a background colour and nothing else, which forced-colors erases.
+ useIndexStore.setState({ query: 'num', hits: HITS, selected: 'numpydoc' })
+ render()
+
+ expect(screen.getByRole('button', { name: 'numpydoc' })).toHaveAttribute('aria-current', 'true')
+ expect(screen.getByRole('button', { name: 'numpy' })).not.toHaveAttribute('aria-current')
+ })
+})
diff --git a/ui/src/screens/PdSearch.tsx b/ui/src/screens/PdSearch.tsx
index 3d795f9..1f85a65 100644
--- a/ui/src/screens/PdSearch.tsx
+++ b/ui/src/screens/PdSearch.tsx
@@ -52,6 +52,8 @@ export function PdSearch() {
const planResolve = usePlanStore((s) => s.resolve)
const envRow = rows.find((r) => r.interpreter === envSelected)
+ /** A query has been asked and answered: the list on screen is the answer to what is typed. */
+ const settled = query.trim() !== '' && ready && !searching
// UI-SPEC §5: the Search flow's first click is spent arriving here, so the field must already
// have focus — "Search (autofocus) → result [Add] → Install → Confirm" is 4, not 5. In the app
@@ -98,11 +100,27 @@ export function PdSearch() {
className="mt-3 shrink-0 rounded-pd border border-border bg-surface px-3 py-1.5 font-mono text-data"
/>
-
+ {/* **One status region, mounted from the first render and never removed.** These were
+ plain spans, so a screen reader heard nothing between a keystroke and its answer — not
+ that the index was loading, not that a search was running, not that it had come back
+ or how much it found. A live region announces changes to itself, which is why it has
+ to exist before the first message: one that arrives together with its text has no
+ earlier state to differ from. */}
+
{/* Warming is a state, not a failure: the index is 864k names and takes ~140 ms to
load, and saying so beats a field that silently returns nothing. */}
{!ready && unavailable === null ? {t('search.warming')} : null}
{searching ? {t('search.searching')} : null}
+ {settled && hits.length > 0 ? (
+ {t('search.resultCount', { count: hits.length })}
+ ) : null}
+ {/* The empty state below says this to the eye; said once more here for the region. */}
+ {settled && hits.length === 0 ? (
+ {t('search.noResults', { query })}
+ ) : null}