From 28ce8c4dfe065f131e470741e60c5d06a020893b Mon Sep 17 00:00:00 2001
From: Timothy <timothy@noreply.gitea.tblindustries.be>
Date: Wed, 5 Aug 2026 18:27:25 +0200
Subject: [PATCH 1/5] fix(685): gate AddItemsDialog on a real query instead of
 windowing the whole type
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

AddItemsDialog.runSearch was reachable with an empty query two ways — a blank
form submit, and a kind-chip click, which called it immediately — and
getLibraryBrowseItems omits a falsy `query`, so each path degraded into an
unfiltered browse of the whole media-library type (first 50 rows, per kind)
presented as the answer with nothing surfacing the truncation. All ten
ADDABLE_TYPE_LIST entries are spa-conventions §3b Class B media-library types.

The dialog is multi-select, so §3b's SearchPicker (single-select) does not fit;
it takes §3b's constraints instead:

- no request below LIBRARY_PICKER_MIN_QUERY, enforced in runSearch — the single
  sink both entry paths route through, not duplicated per caller
- typed text compiled with titleContainsQuery rather than forwarded raw (a
  second latent §3b violation here: the search index's default field does not
  match bare title words)
- each kind bounded to LIBRARY_PICKER_RESULTS
- merged.slice(0, 50) removed — it silently dropped up to 100 of 150 fetched
  rows even for a real query

Tests assert zero requests below the gate on both paths, exactly one bounded
request per kind above it (20k-row fixture), the compiled+escaped query, and
that no fetched row is dropped. Each was verified to fail with its mechanism
removed.

The pageSize registry entry moves from `deviation` to `search-bounded`. That
leaves zero deviation entries, so the anti-vacuity assertion guarding that list
is deleted deliberately, per its own instruction.

Done-when box 4 (collection-family truncation hint) has no subject: this screen
offers no collection-family type.

fixes #685
---
 docs/spa-conventions.md                     |  11 ++
 web/src/api/pageSizeCallSites.guard.test.ts |  28 ++--
 web/src/screens/CollectionsScreen.test.tsx  | 167 +++++++++++++++++++-
 web/src/screens/CollectionsScreen.tsx       |  35 +++-
 4 files changed, 220 insertions(+), 21 deletions(-)

diff --git a/docs/spa-conventions.md b/docs/spa-conventions.md
index 63a26266f..62e29fab5 100644
--- a/docs/spa-conventions.md
+++ b/docs/spa-conventions.md
@@ -183,6 +183,17 @@ the #644 follow-up got Class A right and Class B only half right):
   is gone from these pickers along with the window it described. Prove the bound with a
   **request-count assertion against a large (20k-row) fixture**, not by inspection.
 
+  - **`SearchPicker` is the single-select SHAPE, not the rule itself.** A MULTI-select picker
+    (`CollectionsScreen`'s `AddItemsDialog` — checkbox rows, many items added at once, fanned out
+    over several kinds) cannot render `SearchPicker` and must not be forced to. It satisfies this
+    section by keeping its own result list and taking the *constraints* instead: gate on
+    `LIBRARY_PICKER_MIN_QUERY`, `titleContainsQuery` the typed text, `LIBRARY_PICKER_RESULTS` per
+    kind, and no post-fetch `slice` — a fetched-then-discarded row is a silent drop, and removing
+    the drop is the fix, not hinting at it. **Put the gate in the single search sink, not at each
+    caller**: `AddItemsDialog` has two entry paths (blank form submit, kind-chip click), and #685's
+    first fix duplicated the check at one of them, which measurably tested nothing — deleting the
+    duplicate reddened no test, while deleting the sink's gate reddened both paths.
+
   - **Compile typed text; never forward raw Lucene.** Send `titleContainsQuery(text)` →
     `title:*<escaped>*`. The index's default field does not match bare title words (`Alpha` finds
     nothing for "Show Alpha" — see `e2e-local.md`), so a raw forward looks broken in a *name* picker.
diff --git a/web/src/api/pageSizeCallSites.guard.test.ts b/web/src/api/pageSizeCallSites.guard.test.ts
index a923d9126..27af1822f 100644
--- a/web/src/api/pageSizeCallSites.guard.test.ts
+++ b/web/src/api/pageSizeCallSites.guard.test.ts
@@ -249,18 +249,16 @@ const REGISTRY: RegistryEntry[] = [
   {
     file: 'screens/CollectionsScreen.tsx',
     kind: 'literal',
-    value: '50',
-    classification: 'deviation',
-    issue: 685,
+    value: 'LIBRARY_PICKER_RESULTS',
+    classification: 'search-bounded',
     note:
-      'TRACKED §3b VIOLATION — #685. AddItemsDialog.runSearch is reachable with an EMPTY query ' +
-      '(blank form submit, and a kind-chip click, which calls it immediately), and ' +
-      'getLibraryBrowseItems omits a falsy query — so it degrades to an unfiltered 50-row window ' +
-      'over the whole media-library type, per kind. Nothing surfaces it: totalCount is never read ' +
-      'here and no hint renders, and merged.slice(0, 50) drops up to 100 of 150 fetched rows even ' +
-      'for a real query. Under the cap, so #644 and #650 both missed it. NOT search-bounded (the ' +
-      'query is not required) and NOT class-b (no hint) — labelling it either would make this ' +
-      'registry vouch for behaviour that does not exist.'
+      'AddItemsDialog.runSearch — fixed for #685. No request is issued below ' +
+      'LIBRARY_PICKER_MIN_QUERY (a blank form submit and a kind-chip click below the gate both ' +
+      'issue zero requests, and results are cleared instead), the typed text is compiled via ' +
+      'titleContainsQuery rather than forwarded raw, and each kind is bounded to one ' +
+      'getLibraryBrowseItems request per settled query at LIBRARY_PICKER_RESULTS rows. The old ' +
+      'merged.slice(0, 50) post-fetch drop is gone: every merged row renders, so there is nothing ' +
+      'left to hint at.'
   },
   {
     file: 'screens/FillerPresetsScreen.tsx',
@@ -535,9 +533,11 @@ describe('pageSize call-site guard (#650)', () => {
   it("every 'deviation' entry names the issue tracking it", () => {
     const deviations = REGISTRY.filter((entry) => entry.classification === 'deviation');
 
-    // Anti-vacuity: if the deviations are ever all fixed, this must be deleted deliberately, not
-    // silently pass over an empty list while claiming to enforce something.
-    expect(deviations.length).toBeGreaterThan(0);
+    // No live 'deviation' entries as of #685 (the last one — CollectionsScreen.tsx's raw-50 window
+    // — was fixed and reclassified 'search-bounded' above). The anti-vacuity
+    // `expect(deviations.length).toBeGreaterThan(0)` this comment used to enforce is deleted
+    // DELIBERATELY here, per its own instruction, rather than left to silently pass over an empty
+    // list — re-add it the day a new 'deviation' entry is registered.
 
     for (const entry of deviations) {
       expect(entry.issue, `${entry.file}:${entry.value} is a deviation but names no tracking issue`).toEqual(
diff --git a/web/src/screens/CollectionsScreen.test.tsx b/web/src/screens/CollectionsScreen.test.tsx
index b238a82f8..7323dee09 100644
--- a/web/src/screens/CollectionsScreen.test.tsx
+++ b/web/src/screens/CollectionsScreen.test.tsx
@@ -1,5 +1,11 @@
 import { cleanup, fireEvent, render, screen, waitFor, within } from '@testing-library/react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  LIBRARY_PICKER_LUCENE_SPECIALS,
+  LIBRARY_PICKER_MIN_QUERY,
+  LIBRARY_PICKER_RESULTS,
+  titleContainsQuery
+} from '../api';
 import { CollectionsScreen } from './CollectionsScreen';
 
 // The rule builder's field catalog normally comes from a live /api/v1/search/fields fetch; mock it
@@ -401,7 +407,7 @@ describe('CollectionsScreen', () => {
 
     const dialog = await openAddItemsDialog();
     fireEvent.change(within(dialog).getByPlaceholderText('Search movies, shows, seasons, artists…'), {
-      target: { value: 'a' }
+      target: { value: 'za' }
     });
     fireEvent.click(within(dialog).getByRole('button', { name: 'Search' }));
 
@@ -419,7 +425,7 @@ describe('CollectionsScreen', () => {
 
     const dialog = await openAddItemsDialog();
     fireEvent.change(within(dialog).getByPlaceholderText('Search movies, shows, seasons, artists…'), {
-      target: { value: 'a' }
+      target: { value: 'za' }
     });
     fireEvent.click(within(dialog).getByRole('button', { name: 'Seasons' }));
 
@@ -451,7 +457,7 @@ describe('CollectionsScreen', () => {
 
     const dialog = await openAddItemsDialog();
     fireEvent.change(within(dialog).getByPlaceholderText('Search movies, shows, seasons, artists…'), {
-      target: { value: 'a' }
+      target: { value: 'za' }
     });
     fireEvent.click(within(dialog).getByRole('button', { name: 'Song' }));
 
@@ -475,6 +481,161 @@ describe('CollectionsScreen', () => {
     });
   });
 
+  /* ---------- add-items search bounds (#685) ---------- */
+
+  function buildLibraryFixture(mediaType: string, count: number): { id: number; mediaItemId: number; mediaType: string; title: string }[] {
+    return Array.from({ length: count }, (_, index) => ({
+      id: index + 1,
+      mediaItemId: index + 1,
+      mediaType,
+      title: `${mediaType} Item ${index + 1}`
+    }));
+  }
+
+  // Simulates a library with `rowsPerKind` rows of EACH media type (20,000 by default — large
+  // enough that "the client bounds itself" is the only thing keeping this fast), honoring the
+  // requested pageSize the way the real server-side clamp does (spa-conventions §3b).
+  function mockLargeLibraryApi(rowsPerKind = 20000) {
+    const fixtures = new Map<string, ReturnType<typeof buildLibraryFixture>>();
+
+    return mockApi({
+      onRequest: (url) => {
+        if (!url.startsWith('/api/v1/library/browse')) {
+          return null;
+        }
+
+        const params = new URL(url, 'http://localhost').searchParams;
+        const mediaType = params.get('mediaType') ?? 'Movie';
+        const pageSize = Number(params.get('pageSize') ?? '0');
+
+        if (!fixtures.has(mediaType)) {
+          fixtures.set(mediaType, buildLibraryFixture(mediaType, rowsPerKind));
+        }
+
+        const fixture = fixtures.get(mediaType) ?? [];
+        return jsonResponse({ page: fixture.slice(0, pageSize), totalCount: fixture.length });
+      }
+    });
+  }
+
+  function browseCallsOf(fetchMock: ReturnType<typeof mockApi>) {
+    return fetchMock.mock.calls.filter(([u]) => u.toString().startsWith('/api/v1/library/browse'));
+  }
+
+  it('issues zero requests for a blank submit, and renders the min-query guidance', async () => {
+    const fetchMock = mockLargeLibraryApi();
+
+    const dialog = await openAddItemsDialog();
+
+    expect(
+      within(dialog).getByText(`Type at least ${LIBRARY_PICKER_MIN_QUERY} characters to search.`)
+    ).toBeInTheDocument();
+
+    fireEvent.click(within(dialog).getByRole('button', { name: 'Search' }));
+
+    // No await-for-settle race: a blank submit never issues a fetch, so there is nothing async
+    // to wait on — assert immediately that the guidance is still the only thing shown.
+    expect(
+      within(dialog).getByText(`Type at least ${LIBRARY_PICKER_MIN_QUERY} characters to search.`)
+    ).toBeInTheDocument();
+    expect(browseCallsOf(fetchMock).length).toBe(0);
+  });
+
+  it('a kind-chip click below the min-query gate issues zero requests', async () => {
+    const fetchMock = mockLargeLibraryApi();
+
+    const dialog = await openAddItemsDialog();
+    fireEvent.click(within(dialog).getByRole('button', { name: 'Song' }));
+
+    expect(
+      within(dialog).getByText(`Type at least ${LIBRARY_PICKER_MIN_QUERY} characters to search.`)
+    ).toBeInTheDocument();
+    expect(browseCallsOf(fetchMock).length).toBe(0);
+  });
+
+  it(
+    'a valid query issues exactly one request per kind, bounded to LIBRARY_PICKER_RESULTS, with the compiled query',
+    { timeout: 15000 },
+    async () => {
+      const fetchMock = mockLargeLibraryApi();
+
+      const dialog = await openAddItemsDialog();
+      fireEvent.change(within(dialog).getByPlaceholderText('Search movies, shows, seasons, artists…'), {
+        target: { value: 'za' }
+      });
+      fireEvent.click(within(dialog).getByRole('button', { name: 'Search' }));
+
+      await within(dialog).findByText('Movie Item 1');
+
+      const browseCalls = browseCallsOf(fetchMock);
+      // DEFAULT_SEARCH_KINDS fan-out: Movie, TelevisionShow, Artist — exactly one request each,
+      // never more.
+      expect(browseCalls.length).toBe(3);
+
+      const kindsRequested = browseCalls.map(
+        ([u]) => new URL(u.toString(), 'http://localhost').searchParams.get('mediaType')
+      );
+      expect(new Set(kindsRequested)).toEqual(new Set(['Movie', 'TelevisionShow', 'Artist']));
+
+      for (const [u] of browseCalls) {
+        const params = new URL(u.toString(), 'http://localhost').searchParams;
+        expect(params.get('pageSize')).toBe(String(LIBRARY_PICKER_RESULTS));
+        expect(params.get('query')).toBe(titleContainsQuery('za'));
+      }
+    }
+  );
+
+  it(
+    'compiles typed text and escapes a Lucene special character rather than forwarding it raw',
+    { timeout: 15000 },
+    async () => {
+      const fetchMock = mockLargeLibraryApi();
+      // Drive the escaping test from the exported character set, not a hand-copied sample — a
+      // sample can't see what it omits.
+      const special = LIBRARY_PICKER_LUCENE_SPECIALS[0];
+      const typed = `ro${special}ck`;
+
+      const dialog = await openAddItemsDialog();
+      fireEvent.change(within(dialog).getByPlaceholderText('Search movies, shows, seasons, artists…'), {
+        target: { value: typed }
+      });
+      fireEvent.click(within(dialog).getByRole('button', { name: 'Search' }));
+
+      await within(dialog).findByText('Movie Item 1');
+
+      const browseCall = browseCallsOf(fetchMock)[0];
+      const params = new URL(String(browseCall?.[0]), 'http://localhost').searchParams;
+      const sentQuery = params.get('query');
+
+      expect(sentQuery).toBe(titleContainsQuery(typed));
+      // A raw, unescaped forward would still contain the bare special character; the compiled
+      // form never does (it is backslash-escaped instead).
+      expect(sentQuery).not.toBe(`title:*${typed}*`);
+      expect(sentQuery).toContain(`\\${special}`);
+    }
+  );
+
+  it(
+    'renders every merged row across all kinds — no post-fetch drop',
+    { timeout: 15000 },
+    async () => {
+      mockLargeLibraryApi(LIBRARY_PICKER_RESULTS);
+
+      const dialog = await openAddItemsDialog();
+      fireEvent.change(within(dialog).getByPlaceholderText('Search movies, shows, seasons, artists…'), {
+        target: { value: 'za' }
+      });
+      fireEvent.click(within(dialog).getByRole('button', { name: 'Search' }));
+
+      await within(dialog).findByText('Movie Item 1');
+
+      // Each of the 3 default-fan-out kinds returns a full LIBRARY_PICKER_RESULTS-row page;
+      // nothing fetched should be discarded, so all of them must render.
+      const titleEls = dialog.querySelectorAll('.ctv-collections-picker-row-title');
+      expect(titleEls.length).toBe(3 * LIBRARY_PICKER_RESULTS);
+    }
+  );
+
   /* ---------- reorder mode (#211) ---------- */
 
   function reorderPages(id: number) {
diff --git a/web/src/screens/CollectionsScreen.tsx b/web/src/screens/CollectionsScreen.tsx
index 8b726e1f4..b781aac23 100644
--- a/web/src/screens/CollectionsScreen.tsx
+++ b/web/src/screens/CollectionsScreen.tsx
@@ -37,8 +37,11 @@ import {
   getCollections,
   getLibraryBrowseItems,
   getSmartCollections,
+  LIBRARY_PICKER_MIN_QUERY,
+  LIBRARY_PICKER_RESULTS,
   messageFromCollectionError,
   removeItemFromCollection,
+  titleContainsQuery,
   toAddItemsRequest,
   updateCollection,
   updateCollectionCustomOrder,
@@ -223,21 +226,36 @@ function AddItemsDialog({
   const [adding, setAdding] = useState(false);
   const [kindFilter, setKindFilter] = useState<MediaKindFilter>('all');
 
+  // Below LIBRARY_PICKER_MIN_QUERY, this issues NOTHING: a blank/short form submit and a
+  // kind-chip click (see selectKindFilter) both route through here, and #685 was exactly this
+  // gate missing — an empty query degraded into an unfiltered browse of the whole
+  // media-library type, per kind, with no truncation indicator.
   const runSearch = async (filter: MediaKindFilter = kindFilter) => {
+    const trimmed = query.trim();
+
+    if (trimmed.length < LIBRARY_PICKER_MIN_QUERY) {
+      setResults([]);
+      setError(null);
+      return;
+    }
+
     setSearching(true);
     setError(null);
 
     try {
-      const trimmed = query.trim();
       const kinds = filter === 'all' ? DEFAULT_SEARCH_KINDS : [filter];
       const perKind = await Promise.all(
-        kinds.map((mediaType) => getLibraryBrowseItems({ pageSize: 50, query: trimmed, mediaType }))
+        kinds.map((mediaType) =>
+          getLibraryBrowseItems({ mediaType, pageSize: LIBRARY_PICKER_RESULTS, query: titleContainsQuery(trimmed) })
+        )
       );
       const merged = perKind
         .flatMap((result) => result.page ?? [])
         .filter((item) => ADDABLE_TYPES.has(item.mediaType))
         .sort((left, right) => left.title.localeCompare(right.title, undefined, { sensitivity: 'base' }));
-      setResults(merged.slice(0, 50));
+      // No slice: each kind is already bounded to LIBRARY_PICKER_RESULTS server-side, so nothing
+      // fetched is discarded here (#685 — merged.slice(0, 50) used to drop up to 100 of 150 rows).
+      setResults(merged);
     } catch (searchError) {
       setError(messageFromCollectionError(searchError, 'Unable to search library'));
     } finally {
@@ -245,6 +263,11 @@ function AddItemsDialog({
     }
   };
 
+  // A kind-chip click is the second path into runSearch (a blank form submit is the other), and it
+  // is deliberately NOT gated here: runSearch is the single sink and owns the min-query gate for
+  // every caller. A duplicate check at this one call site was verified non-load-bearing (removing
+  // it changed no test), and §3b is explicit that an unreachable guard is an untested one — the
+  // next path added would be the one nobody remembers to gate.
   const selectKindFilter = (filter: MediaKindFilter) => {
     setKindFilter(filter);
     void runSearch(filter);
@@ -347,7 +370,11 @@ function AddItemsDialog({
         </span>
       )}
       <div className="ctv-collections-picker-results">
-        {results.length === 0 && !searching ? (
+        {query.trim().length < LIBRARY_PICKER_MIN_QUERY ? (
+          <div className="ctv-collections-picker-empty">
+            Type at least {LIBRARY_PICKER_MIN_QUERY} characters to search.
+          </div>
+        ) : results.length === 0 && !searching ? (
           <div className="ctv-collections-picker-empty">No results — try a search above.</div>
         ) : (
           results.map((item) => {

From 4be3f247d8938912dabe7516705790b52dded923 Mon Sep 17 00:00:00 2001
From: Timothy <timothy@noreply.gitea.tblindustries.be>
Date: Wed, 5 Aug 2026 18:46:43 +0200
Subject: [PATCH 2/5] fix(685): move the picker bound into the helper; surface
 the per-kind cap
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Independent review round 2. Verdict was MERGEABLE with no blockers; this takes
the two recommended fixes plus the structural one it listed as a follow-up.

- The bound was caller discipline, not code: getLibraryBrowseItems does not
  clamp pageSize, so the bound was only the constant this one call site chose
  to pass, and §3b is explicit that a bound a caller can exceed is not a bound.
  New searchLibraryBrowseItems in libraryBrowse.ts owns the min-query gate, the
  pageSize clamp and the titleContainsQuery compile, returning full
  LibraryBrowseItem rows plus totalCount (searchLibraryPickerOptions' {id,name}
  shape loses the mediaType that toAddItemsRequest needs). runSearch keeps one
  early return, for the spinner only, and no longer re-implements the gate.

- The min-query guidance was keyed to the LIVE input, so backspacing below the
  gate after a search wiped the rendered rows and their checkmarks while
  `selected` and the Add button still counted them. Keyed to results.length too.

- "Nothing left to hint at" was false: each kind is still capped at
  LIBRARY_PICKER_RESULTS and totalCount was never read. This is a bulk
  multi-select add, so the cap is surfaced — per-kind totalCounts are summed and
  rendered as "Showing N of M matches" once it exceeds the rendered rows. The
  registry note and the §3b bullet are corrected to stop claiming otherwise.

- Gate boundary tested at 1 character (§3b: inclusive endpoints, or a > for >=
  slip passes the whole suite).

- The guard test's deviation loop iterates an empty list now, so it gains one
  bidirectional assertion that is non-vacuous: the set carrying an `issue` field
  must equal the set classified 'deviation'.

- The §3b bullet no longer reads as a conformance certificate: AddItemsDialog
  still lacks the seqRef and useIsMountedRef guards §3b mandates. That defect is
  PRE-EXISTING, not introduced here, and is tracked in #740.

refs #740
---
 docs/spa-conventions.md                     | 21 +++--
 web/src/api/libraryBrowse.ts                | 35 ++++++++
 web/src/api/pageSizeCallSites.guard.test.ts | 46 ++++++----
 web/src/screens/CollectionsScreen.test.tsx  | 99 ++++++++++++++++++++-
 web/src/screens/CollectionsScreen.tsx       | 38 +++++---
 5 files changed, 200 insertions(+), 39 deletions(-)

diff --git a/docs/spa-conventions.md b/docs/spa-conventions.md
index 62e29fab5..4b27e59d0 100644
--- a/docs/spa-conventions.md
+++ b/docs/spa-conventions.md
@@ -186,13 +186,22 @@ the #644 follow-up got Class A right and Class B only half right):
   - **`SearchPicker` is the single-select SHAPE, not the rule itself.** A MULTI-select picker
     (`CollectionsScreen`'s `AddItemsDialog` — checkbox rows, many items added at once, fanned out
     over several kinds) cannot render `SearchPicker` and must not be forced to. It satisfies this
-    section by keeping its own result list and taking the *constraints* instead: gate on
+    section by taking the same *constraints* the helper enforces for single-select — the gate on
     `LIBRARY_PICKER_MIN_QUERY`, `titleContainsQuery` the typed text, `LIBRARY_PICKER_RESULTS` per
-    kind, and no post-fetch `slice` — a fetched-then-discarded row is a silent drop, and removing
-    the drop is the fix, not hinting at it. **Put the gate in the single search sink, not at each
-    caller**: `AddItemsDialog` has two entry paths (blank form submit, kind-chip click), and #685's
-    first fix duplicated the check at one of them, which measurably tested nothing — deleting the
-    duplicate reddened no test, while deleting the sink's gate reddened both paths.
+    kind — via `searchLibraryBrowseItems` (`web/src/api/libraryBrowse.ts`), a sibling of
+    `searchLibraryPickerOptions` that returns full `LibraryBrowseItem` rows plus `totalCount`
+    instead of `{id, name}`, so the bound lives in the helper rather than the caller (#685 review
+    finding 2). There is no post-fetch `slice`, but the per-kind cap can still truncate the real
+    match count — this is a bulk multi-select add, where "add the 40 matching episodes" is a
+    first-class use, so `AddItemsDialog` sums each kind's `totalCount` and renders a `Showing N of
+    M matches` hint once it exceeds the rendered rows (finding 4 — an earlier revision of this
+    bullet called the truncation nothing left to hint at). **Put the gate in the single search
+    sink, not at each caller**: `AddItemsDialog` has two entry paths (blank form submit, kind-chip
+    click), and #685's first fix duplicated the check at one of them, which measurably tested
+    nothing — deleting the duplicate reddened no test, while deleting the sink's gate reddened both
+    paths. **Outstanding on this screen**: `AddItemsDialog` still lacks the monotonic `seqRef`
+    stale-response guard and `useIsMountedRef()` this section mandates elsewhere (see "Debounced
+    typeaheads" below) — tracked in **ersatztv#740**, not yet fixed here.
 
   - **Compile typed text; never forward raw Lucene.** Send `titleContainsQuery(text)` →
     `title:*<escaped>*`. The index's default field does not match bare title words (`Alpha` finds
diff --git a/web/src/api/libraryBrowse.ts b/web/src/api/libraryBrowse.ts
index 0d9ea5deb..59f0857ec 100644
--- a/web/src/api/libraryBrowse.ts
+++ b/web/src/api/libraryBrowse.ts
@@ -111,6 +111,41 @@ export function searchLibraryPickerOptions(
   );
 }
 
+export interface LibraryBrowseSearchResult {
+  items: LibraryBrowseItem[];
+  totalCount: number;
+}
+
+// Like `searchLibraryPickerOptions` above — same min-query gate, same clamp, same compiled query —
+// but for a MULTI-select caller (`CollectionsScreen`'s `AddItemsDialog`) that needs the full
+// `LibraryBrowseItem` row (mediaType + id, for `toAddItemsRequest`) rather than the `{id, name}`
+// shape a single-select `SearchPicker` renders, plus the response's `totalCount` so the caller can
+// surface how much of a match was actually returned. The gate/clamp/compile live HERE, not at the
+// call site, so no caller can accidentally skip them (§3b — "the bound belongs to the helper, not
+// the caller").
+export function searchLibraryBrowseItems(
+  mediaType: LibraryBrowseMediaType,
+  text: string,
+  pageSize: number = LIBRARY_PICKER_RESULTS
+): Promise<LibraryBrowseSearchResult> {
+  const trimmed = text.trim();
+  if (trimmed.length < LIBRARY_PICKER_MIN_QUERY) {
+    return Promise.resolve({ items: [], totalCount: 0 });
+  }
+
+  const boundedPageSize = Math.max(1, Math.min(Math.floor(pageSize), LIBRARY_PICKER_RESULTS));
+
+  return getLibraryBrowseItems({
+    mediaType,
+    pageNum: 0,
+    pageSize: boundedPageSize,
+    query: titleContainsQuery(trimmed)
+  }).then((result) => ({
+    items: result.page ?? [],
+    totalCount: result.totalCount ?? 0
+  }));
+}
+
 export function messageFromLibraryBrowseError(error: unknown, fallback = 'Unable to load library items'): string {
   if (error instanceof ApiError) {
     return error.detail ?? error.message;
diff --git a/web/src/api/pageSizeCallSites.guard.test.ts b/web/src/api/pageSizeCallSites.guard.test.ts
index 27af1822f..49a8a0483 100644
--- a/web/src/api/pageSizeCallSites.guard.test.ts
+++ b/web/src/api/pageSizeCallSites.guard.test.ts
@@ -163,6 +163,28 @@ const REGISTRY: RegistryEntry[] = [
       'correctly absent). The bound is a clamp, not a default: Math.min(pageSize, ' +
       'LIBRARY_PICKER_RESULTS) inside the helper, so a caller cannot widen it.'
   },
+  {
+    file: 'api/libraryBrowse.ts',
+    kind: 'literal',
+    value: 'boundedPageSize',
+    classification: 'search-bounded',
+    note:
+      "searchLibraryBrowseItems — the #685 review fix that moved AddItemsDialog.runSearch's " +
+      'pageSize call site out of screens/CollectionsScreen.tsx and into this shared helper (same ' +
+      'gate/clamp/compile as searchLibraryPickerOptions above), so a multi-select caller needing ' +
+      'full LibraryBrowseItem rows plus totalCount cannot skip the bound either. A deliberate ' +
+      'second occurrence of the same (file, kind, value) identity — the multiset comparison ' +
+      'requires it be discovered twice. No request is issued below LIBRARY_PICKER_MIN_QUERY (a ' +
+      'blank form submit and a kind-chip click below the gate both issue zero requests, and ' +
+      'AddItemsDialog clears results instead), the typed text is compiled via titleContainsQuery ' +
+      'rather than forwarded raw, and each kind is bounded to one request per settled query at ' +
+      'LIBRARY_PICKER_RESULTS rows. Unlike the #685 first fix, this is NOT "nothing left to hint ' +
+      'at": the per-kind cap can still truncate the real match count below what totalCount reports, ' +
+      "and AddItemsDialog now sums each kind's totalCount and renders a 'Showing N of M' hint when " +
+      "it exceeds the rendered rows. The only remaining client-side filter in AddItemsDialog " +
+      "(ADDABLE_TYPES.has(item.mediaType)) is inert, not a silent drop — every mediaType " +
+      'AddItemsDialog requests is already in ADDABLE_TYPE_LIST.'
+  },
   {
     file: 'api/paging.ts',
     kind: 'shorthand',
@@ -246,20 +268,6 @@ const REGISTRY: RegistryEntry[] = [
       'Playout block history: forwards a user-adjustable `pageSize` state (persisted, backed by a ' +
       'page-size <Select>) to a real pager keyed off the response totalCount.'
   },
-  {
-    file: 'screens/CollectionsScreen.tsx',
-    kind: 'literal',
-    value: 'LIBRARY_PICKER_RESULTS',
-    classification: 'search-bounded',
-    note:
-      'AddItemsDialog.runSearch — fixed for #685. No request is issued below ' +
-      'LIBRARY_PICKER_MIN_QUERY (a blank form submit and a kind-chip click below the gate both ' +
-      'issue zero requests, and results are cleared instead), the typed text is compiled via ' +
-      'titleContainsQuery rather than forwarded raw, and each kind is bounded to one ' +
-      'getLibraryBrowseItems request per settled query at LIBRARY_PICKER_RESULTS rows. The old ' +
-      'merged.slice(0, 50) post-fetch drop is gone: every merged row renders, so there is nothing ' +
-      'left to hint at.'
-  },
   {
     file: 'screens/FillerPresetsScreen.tsx',
     kind: 'literal',
@@ -546,10 +554,12 @@ describe('pageSize call-site guard (#650)', () => {
       expect(entry.issue!).toBeGreaterThan(0);
     }
 
-    // The converse, so the field cannot drift into decoration: only a deviation carries one.
-    for (const entry of REGISTRY.filter((e) => e.classification !== 'deviation')) {
-      expect(entry.issue, `${entry.file}:${entry.value} is not a deviation but carries an issue`).toBeUndefined();
-    }
+    // The converse, so the field cannot drift into decoration: only a deviation carries one. With
+    // `deviations` currently empty, the loop above evaluates nothing — so this single bidirectional
+    // assertion is what actually gives the test teeth today: it fails the moment any non-deviation
+    // entry picks up an `issue` field, or a 'deviation' entry is added without one (#685 review
+    // finding 7).
+    expect(REGISTRY.filter((entry) => entry.issue !== undefined)).toEqual(deviations);
   });
 
   // Pins the report format, not the comparison key (#684 review M3): dropping the position from
diff --git a/web/src/screens/CollectionsScreen.test.tsx b/web/src/screens/CollectionsScreen.test.tsx
index 7323dee09..751d020b4 100644
--- a/web/src/screens/CollectionsScreen.test.tsx
+++ b/web/src/screens/CollectionsScreen.test.tsx
@@ -481,6 +481,76 @@ describe('CollectionsScreen', () => {
     });
   });
 
+  it(
+    'backspacing the query below the min-query length after a search keeps the rows, checkmarks, and Add count (#685 review finding 1)',
+    async () => {
+      mockAddItemsApi();
+
+      const dialog = await openAddItemsDialog();
+      fireEvent.change(within(dialog).getByPlaceholderText('Search movies, shows, seasons, artists…'), {
+        target: { value: 'za' }
+      });
+      fireEvent.click(within(dialog).getByRole('button', { name: 'Search' }));
+
+      expect(await within(dialog).findByText('Zathura')).toBeInTheDocument();
+
+      fireEvent.click(within(dialog).getByText('Zathura'));
+      expect(within(dialog).getByRole('button', { name: /Add 1 item/ })).toBeInTheDocument();
+
+      // Backspace the LIVE input down to one character — below LIBRARY_PICKER_MIN_QUERY — WITHOUT
+      // re-submitting. Before the fix, the render condition keyed the min-query guidance to the
+      // live input alone, so this wiped the visible row list and its checkmark even though
+      // `results` and `selected` were untouched in state.
+      fireEvent.change(within(dialog).getByPlaceholderText('Search movies, shows, seasons, artists…'), {
+        target: { value: 'z' }
+      });
+
+      expect(within(dialog).getByText('Zathura')).toBeInTheDocument();
+      expect(within(dialog).getByText('Adventure Time')).toBeInTheDocument();
+      expect(
+        within(dialog).queryByText(`Type at least ${LIBRARY_PICKER_MIN_QUERY} characters to search.`)
+      ).not.toBeInTheDocument();
+      const zathuraRow = within(dialog).getByText('Zathura').closest('button');
+      expect(zathuraRow).toHaveAttribute('aria-pressed', 'true');
+      expect(within(dialog).getByRole('button', { name: /Add 1 item/ })).toBeInTheDocument();
+    }
+  );
+
+  it(
+    'sums totalCount across kinds and hints at truncation once it exceeds the rendered rows (#685 review finding 4)',
+    { timeout: 15000 },
+    async () => {
+      mockLargeLibraryApi();
+
+      const dialog = await openAddItemsDialog();
+      fireEvent.change(within(dialog).getByPlaceholderText('Search movies, shows, seasons, artists…'), {
+        target: { value: 'za' }
+      });
+      fireEvent.click(within(dialog).getByRole('button', { name: 'Search' }));
+
+      await within(dialog).findByText('Movie Item 1');
+
+      // 3 kinds (Movie, TelevisionShow, Artist) each report a 20,000-row totalCount but only
+      // LIBRARY_PICKER_RESULTS (25) rows land per kind, so the sum (60,000) is far above the 75
+      // rows actually rendered.
+      expect(within(dialog).getByText(/Showing 75 of 60000 matches/)).toBeInTheDocument();
+    }
+  );
+
+  it('does not render a truncation hint when totalCount does not exceed the rendered rows', async () => {
+    mockAddItemsApi();
+
+    const dialog = await openAddItemsDialog();
+    fireEvent.change(within(dialog).getByPlaceholderText('Search movies, shows, seasons, artists…'), {
+      target: { value: 'za' }
+    });
+    fireEvent.click(within(dialog).getByRole('button', { name: 'Search' }));
+
+    await within(dialog).findByText('Zathura');
+
+    expect(within(dialog).queryByText(/Showing .* of .* matches/)).not.toBeInTheDocument();
+  });
+
   /* ---------- add-items search bounds (#685) ---------- */
 
   function buildLibraryFixture(mediaType: string, count: number): { id: number; mediaItemId: number; mediaType: string; title: string }[] {
@@ -541,6 +611,27 @@ describe('CollectionsScreen', () => {
     expect(browseCallsOf(fetchMock).length).toBe(0);
   });
 
+  it(
+    `a ${LIBRARY_PICKER_MIN_QUERY - 1}-character submit (one below the minimum) issues zero requests`,
+    async () => {
+      // §3b: unit-test the INCLUSIVE endpoint directly — existing coverage only exercised 0 chars
+      // (blank submit) and a valid 2-char query, so a `>` for `>=` slip in the gate would have
+      // passed the whole suite (#685 review finding 3).
+      const fetchMock = mockLargeLibraryApi();
+
+      const dialog = await openAddItemsDialog();
+      fireEvent.change(within(dialog).getByPlaceholderText('Search movies, shows, seasons, artists…'), {
+        target: { value: 'z' }
+      });
+      fireEvent.click(within(dialog).getByRole('button', { name: 'Search' }));
+
+      expect(
+        within(dialog).getByText(`Type at least ${LIBRARY_PICKER_MIN_QUERY} characters to search.`)
+      ).toBeInTheDocument();
+      expect(browseCallsOf(fetchMock).length).toBe(0);
+    }
+  );
+
   it('a kind-chip click below the min-query gate issues zero requests', async () => {
     const fetchMock = mockLargeLibraryApi();
 
@@ -590,8 +681,12 @@ describe('CollectionsScreen', () => {
     { timeout: 15000 },
     async () => {
       const fetchMock = mockLargeLibraryApi();
-      // Drive the escaping test from the exported character set, not a hand-copied sample — a
-      // sample can't see what it omits.
+      // This is a smoke check that the compiled query reaches the wire intact for ONE special
+      // character — it does not need to be exhaustive, because the exhaustive per-character case
+      // (every character in LIBRARY_PICKER_LUCENE_SPECIALS) already lives in
+      // web/src/api/libraryBrowse.test.ts, against titleContainsQuery directly. Picking element 0
+      // here is an arbitrary representative, not a hand-copied "every special" sample (#685 review
+      // finding 6).
       const special = LIBRARY_PICKER_LUCENE_SPECIALS[0];
       const typed = `ro${special}ck`;
 
diff --git a/web/src/screens/CollectionsScreen.tsx b/web/src/screens/CollectionsScreen.tsx
index b781aac23..b7d819194 100644
--- a/web/src/screens/CollectionsScreen.tsx
+++ b/web/src/screens/CollectionsScreen.tsx
@@ -35,13 +35,11 @@ import {
   getCollectionItems,
   getCollectionItemsWithMeta,
   getCollections,
-  getLibraryBrowseItems,
   getSmartCollections,
   LIBRARY_PICKER_MIN_QUERY,
-  LIBRARY_PICKER_RESULTS,
   messageFromCollectionError,
   removeItemFromCollection,
-  titleContainsQuery,
+  searchLibraryBrowseItems,
   toAddItemsRequest,
   updateCollection,
   updateCollectionCustomOrder,
@@ -220,6 +218,7 @@ function AddItemsDialog({
 }) {
   const [query, setQuery] = useState('');
   const [results, setResults] = useState<LibraryBrowseItem[]>([]);
+  const [totalMatches, setTotalMatches] = useState(0);
   const [searching, setSearching] = useState(false);
   const [selected, setSelected] = useState<Map<string, LibraryBrowseItem>>(() => new Map());
   const [error, setError] = useState<string | null>(null);
@@ -229,12 +228,17 @@ function AddItemsDialog({
   // Below LIBRARY_PICKER_MIN_QUERY, this issues NOTHING: a blank/short form submit and a
   // kind-chip click (see selectKindFilter) both route through here, and #685 was exactly this
   // gate missing — an empty query degraded into an unfiltered browse of the whole
-  // media-library type, per kind, with no truncation indicator.
+  // media-library type, per kind, with no truncation indicator. The gate itself — along with the
+  // pageSize clamp and the raw-Lucene-vs-compiled-query choice — now lives in
+  // `searchLibraryBrowseItems` (§3b: "the bound belongs to the helper, not the caller"), so this is
+  // the only early return left here, kept to avoid flipping the searching spinner for a sub-gate
+  // query rather than to re-implement the gate.
   const runSearch = async (filter: MediaKindFilter = kindFilter) => {
     const trimmed = query.trim();
 
     if (trimmed.length < LIBRARY_PICKER_MIN_QUERY) {
       setResults([]);
+      setTotalMatches(0);
       setError(null);
       return;
     }
@@ -244,18 +248,17 @@ function AddItemsDialog({
 
     try {
       const kinds = filter === 'all' ? DEFAULT_SEARCH_KINDS : [filter];
-      const perKind = await Promise.all(
-        kinds.map((mediaType) =>
-          getLibraryBrowseItems({ mediaType, pageSize: LIBRARY_PICKER_RESULTS, query: titleContainsQuery(trimmed) })
-        )
-      );
+      const perKind = await Promise.all(kinds.map((mediaType) => searchLibraryBrowseItems(mediaType, trimmed)));
       const merged = perKind
-        .flatMap((result) => result.page ?? [])
+        .flatMap((result) => result.items)
         .filter((item) => ADDABLE_TYPES.has(item.mediaType))
         .sort((left, right) => left.title.localeCompare(right.title, undefined, { sensitivity: 'base' }));
-      // No slice: each kind is already bounded to LIBRARY_PICKER_RESULTS server-side, so nothing
-      // fetched is discarded here (#685 — merged.slice(0, 50) used to drop up to 100 of 150 rows).
+      // No slice: each kind is already bounded to LIBRARY_PICKER_RESULTS server-side by the helper,
+      // so nothing fetched is discarded here (#685 — merged.slice(0, 50) used to drop up to 100 of
+      // 150 rows). The per-kind cap can still truncate the real match count, though — surfaced
+      // below via totalMatches (#685 review finding 4).
       setResults(merged);
+      setTotalMatches(perKind.reduce((sum, result) => sum + result.totalCount, 0));
     } catch (searchError) {
       setError(messageFromCollectionError(searchError, 'Unable to search library'));
     } finally {
@@ -369,8 +372,17 @@ function AddItemsDialog({
           {error}
         </span>
       )}
+      {totalMatches > results.length && (
+        <p className="ctv-collections-picker-note">
+          Showing {results.length} of {totalMatches} matches — narrow your search.
+        </p>
+      )}
       <div className="ctv-collections-picker-results">
-        {query.trim().length < LIBRARY_PICKER_MIN_QUERY ? (
+        {results.length === 0 && query.trim().length < LIBRARY_PICKER_MIN_QUERY ? (
+          // Keyed to results.length, not just the live input: without it, backspacing the query
+          // back below the min-query length after a successful search wiped the rendered rows AND
+          // their checkmarks while `selected` (and the Add button's count) still held them
+          // (#685 review finding 1).
           <div className="ctv-collections-picker-empty">
             Type at least {LIBRARY_PICKER_MIN_QUERY} characters to search.
           </div>

From b6bf94f1294309bea999fe2f409ea170fea44280 Mon Sep 17 00:00:00 2001
From: Timothy <timothy@noreply.gitea.tblindustries.be>
Date: Wed, 5 Aug 2026 19:08:13 +0200
Subject: [PATCH 3/5] fix(685): test the helper's bound; delete the masking
 duplicate gate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Independent review round 2 returned BLOCKED on two findings, both correct.

- The helper's bound was dead code to the suite. searchLibraryBrowseItems had
  zero tests, so deleting its clamp OR its gate left the whole suite green —
  while the registry note claimed a caller "cannot skip the bound". That is the
  previous round's finding relocated, not removed. It now has the three tests
  its sibling searchLibraryPickerOptions already had (clamp, gate, compile),
  plus one pinning the full-row return that is its reason to exist.

- The screen kept a second copy of the min-query check, and the two masked each
  other: the 1-character boundary test passed with EITHER gate alone, so it
  pinned nothing. The screen's copy is deleted; the helper is the sole gate.
  Measured before/after: with the duplicate present, removing the helper's gate
  left that test green; with it gone, the same removal reddens it.

- §3b contradicted itself two lines apart — the parent still said "there is no
  truncation, so there is no truncation hint" above a sub-bullet mandating one.
  Reworded so a hint is permitted, required only where bulk selection makes the
  count actionable. Same correction to the 'search-bounded' definition.

- A failed search left results/totalMatches stale, rendering a confident
  "Showing 75 of 60000 matches" beside the error banner. The catch clears them.

- Results now carry a `Results for "<query>"` heading and the guidance is keyed
  to the settled query, not the live input, so rows are never shown without
  saying which search produced them. `selected` persists across queries (correct
  for a multi-select picker); the Add button's count keeps it discoverable.

- The hint sums pre-filter totalCount against post-filter rows, which is only
  correct because every filterable kind is addable. MediaKindFilter is now
  derived from ADDABLE_TYPE_LIST, making that a compile error rather than prose.

- aria-live on the hint; the #740 doc caveat no longer overstates the typeahead
  rule as a mandate this screen violates.

Declined: the NaN pageSize edge (copied faithfully from the sibling helper) and
the registry's same-identity substitution gap (already disclosed in that file).

refs #740
---
 docs/spa-conventions.md                     | 19 +++--
 web/src/api/libraryBrowse.test.ts           | 51 ++++++++++++
 web/src/api/pageSizeCallSites.guard.test.ts | 37 +++++----
 web/src/screens/CollectionsScreen.test.tsx  | 92 +++++++++++++++++++++
 web/src/screens/CollectionsScreen.tsx       | 76 ++++++++++-------
 5 files changed, 226 insertions(+), 49 deletions(-)

diff --git a/docs/spa-conventions.md b/docs/spa-conventions.md
index 4b27e59d0..a1261376e 100644
--- a/docs/spa-conventions.md
+++ b/docs/spa-conventions.md
@@ -178,10 +178,14 @@ the #644 follow-up got Class A right and Class B only half right):
 
   The helper owns both bounds: at most ONE `getLibraryBrowseItems` request per settled query, at most
   `LIBRARY_PICKER_RESULTS` (25) rows, and no request at all below `LIBRARY_PICKER_MIN_QUERY` (2)
-  characters. Selecting a media-library type must issue **zero** requests. There is no truncation, so
-  there is no truncation hint — the old `Showing the first 100 of 5000 — use search to narrow.` copy
-  is gone from these pickers along with the window it described. Prove the bound with a
-  **request-count assertion against a large (20k-row) fixture**, not by inspection.
+  characters. Selecting a media-library type must issue **zero** requests. The per-kind
+  `LIBRARY_PICKER_RESULTS` cap is the only truncation this class has — there is no whole-type window
+  left to hint at, so the old `Showing the first 100 of 5000 — use search to narrow.` copy is gone
+  from these pickers along with the window it described. Surfacing the per-kind cap is *permitted*
+  wherever it is reachable, and *required* only where bulk selection makes the count actionable — see
+  the `AddItemsDialog` sub-bullet below, which sums the cap across kinds and renders a `Showing N of
+  M matches` hint for exactly that reason. Prove the bound with a **request-count assertion against a
+  large (20k-row) fixture**, not by inspection.
 
   - **`SearchPicker` is the single-select SHAPE, not the rule itself.** A MULTI-select picker
     (`CollectionsScreen`'s `AddItemsDialog` — checkbox rows, many items added at once, fanned out
@@ -200,8 +204,11 @@ the #644 follow-up got Class A right and Class B only half right):
     click), and #685's first fix duplicated the check at one of them, which measurably tested
     nothing — deleting the duplicate reddened no test, while deleting the sink's gate reddened both
     paths. **Outstanding on this screen**: `AddItemsDialog` still lacks the monotonic `seqRef`
-    stale-response guard and `useIsMountedRef()` this section mandates elsewhere (see "Debounced
-    typeaheads" below) — tracked in **ersatztv#740**, not yet fixed here.
+    stale-response guard and `useIsMountedRef()` — the same class of guard "Debounced typeaheads"
+    below mandates there, applied to a debounced-while-typing fetch; `AddItemsDialog` is an explicit
+    Search-button submission, not a typeahead, so that mandate doesn't reach it directly, but the
+    same race (a superseded search settling after a newer one) can still occur here — tracked in
+    **ersatztv#740**, not yet fixed here.
 
   - **Compile typed text; never forward raw Lucene.** Send `titleContainsQuery(text)` →
     `title:*<escaped>*`. The index's default field does not match bare title words (`Alpha` finds
diff --git a/web/src/api/libraryBrowse.test.ts b/web/src/api/libraryBrowse.test.ts
index e2b16ff05..2b4db9db8 100644
--- a/web/src/api/libraryBrowse.test.ts
+++ b/web/src/api/libraryBrowse.test.ts
@@ -1,6 +1,7 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import {
   getLibraryBrowseItems,
+  searchLibraryBrowseItems,
   searchLibraryPickerOptions,
   titleContainsQuery,
   LIBRARY_PICKER_LUCENE_SPECIALS,
@@ -150,3 +151,53 @@ describe('searchLibraryPickerOptions (#651)', () => {
     expect(fetchMock).not.toHaveBeenCalled();
   });
 });
+
+describe('searchLibraryBrowseItems (#685 — AddItemsDialog sibling of searchLibraryPickerOptions)', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  // The reviewer proved this helper was dead code to the suite: deleting its clamp, or deleting
+  // its gate, both left the whole suite green. These three tests mirror the ones above for
+  // searchLibraryPickerOptions so the same bound is pinned for the sibling helper.
+
+  it('#651 F4: CLAMPS an oversized pageSize rather than forwarding it', async () => {
+    const fetchMock = vi.spyOn(window, 'fetch').mockResolvedValue(jsonResponse({ page: [], totalCount: 20000 }));
+
+    await searchLibraryBrowseItems('Episode', 'Alpha', 5000);
+
+    expect(browseUrl(fetchMock).searchParams.get('pageSize')).toBe(String(LIBRARY_PICKER_RESULTS));
+  });
+
+  it('issues NO request for a query below the minimum length, and resolves an empty result', async () => {
+    const fetchMock = vi.spyOn(window, 'fetch').mockResolvedValue(jsonResponse({ page: [], totalCount: 0 }));
+
+    expect(await searchLibraryBrowseItems('Episode', 'a')).toEqual({ items: [], totalCount: 0 });
+    expect(await searchLibraryBrowseItems('Episode', '   ')).toEqual({ items: [], totalCount: 0 });
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it('compiles/escapes the trimmed query, and returns the FULL row (mediaType present) plus totalCount', async () => {
+    const fetchMock = vi.spyOn(window, 'fetch').mockResolvedValue(
+      jsonResponse({
+        page: [{ id: 1, mediaItemId: 7, mediaType: 'Movie', title: 'Show Alpha' }],
+        totalCount: 42
+      })
+    );
+
+    const result = await searchLibraryBrowseItems('Movie', '  Show Alpha  ');
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const url = browseUrl(fetchMock);
+    expect(url.searchParams.get('query')).toBe(titleContainsQuery('Show Alpha'));
+    expect(url.searchParams.get('mediaType')).toBe('Movie');
+    expect(url.searchParams.get('pageNum')).toBe('0');
+    expect(url.searchParams.get('pageSize')).toBe(String(LIBRARY_PICKER_RESULTS));
+    // The reason this helper exists rather than reusing searchLibraryPickerOptions: the full row
+    // (mediaType included), not the {id, name} shape.
+    expect(result).toEqual({
+      items: [{ id: 1, mediaItemId: 7, mediaType: 'Movie', title: 'Show Alpha' }],
+      totalCount: 42
+    });
+  });
+});
diff --git a/web/src/api/pageSizeCallSites.guard.test.ts b/web/src/api/pageSizeCallSites.guard.test.ts
index 49a8a0483..bdc597b3f 100644
--- a/web/src/api/pageSizeCallSites.guard.test.ts
+++ b/web/src/api/pageSizeCallSites.guard.test.ts
@@ -83,12 +83,15 @@ import { scanPageSizeSites } from './pageSizeScan';
  *                          mechanism, and the row bound is a property of the CODE rather than of a
  *                          caller's discipline (a clamp inside the shared helper for #651's
  *                          library picker; a fixed small constant at the inline preview sites).
- *                          Nothing is list-loaded, so there is no truncation to surface and the
- *                          absence of a truncation hint is correct — which is why such a site
- *                          cannot be filed under 'class-b', whose defining evidence IS a surfaced
- *                          `totalCount`. Applies only where the query is genuinely required: a
- *                          site that degrades to an unfiltered browse when the query is empty is
- *                          NOT search-bounded (see 'deviation').
+ *                          Nothing is list-loaded, so a truncation hint is not REQUIRED here — but,
+ *                          unlike 'class-b', it is not the defining evidence either: a search-bounded
+ *                          site MAY surface its own per-kind cap (e.g. summed across kinds) once that
+ *                          count is actionable, without that hint reclassifying it as 'class-b'. What
+ *                          distinguishes the two classes is the SHAPE of the bound (one clamped
+ *                          search request per settled query vs. one bounded page of a list), not
+ *                          whether a hint is rendered. Applies only where the query is genuinely
+ *                          required: a site that degrades to an unfiltered browse when the query is
+ *                          empty is NOT search-bounded (see 'deviation').
  *   - 'class-b'         — one bounded page at (or under) the cap, with the real truncation
  *                          (`totalCount` vs items shown) surfaced to the user. Post-#651 this no
  *                          longer covers media-library pickers (those are 'search-bounded').
@@ -175,15 +178,19 @@ const REGISTRY: RegistryEntry[] = [
       'full LibraryBrowseItem rows plus totalCount cannot skip the bound either. A deliberate ' +
       'second occurrence of the same (file, kind, value) identity — the multiset comparison ' +
       'requires it be discovered twice. No request is issued below LIBRARY_PICKER_MIN_QUERY (a ' +
-      'blank form submit and a kind-chip click below the gate both issue zero requests, and ' +
-      'AddItemsDialog clears results instead), the typed text is compiled via titleContainsQuery ' +
-      'rather than forwarded raw, and each kind is bounded to one request per settled query at ' +
-      'LIBRARY_PICKER_RESULTS rows. Unlike the #685 first fix, this is NOT "nothing left to hint ' +
-      'at": the per-kind cap can still truncate the real match count below what totalCount reports, ' +
-      "and AddItemsDialog now sums each kind's totalCount and renders a 'Showing N of M' hint when " +
-      "it exceeds the rendered rows. The only remaining client-side filter in AddItemsDialog " +
-      "(ADDABLE_TYPES.has(item.mediaType)) is inert, not a silent drop — every mediaType " +
-      'AddItemsDialog requests is already in ADDABLE_TYPE_LIST.'
+      'blank form submit and a kind-chip click below the gate both resolve every kind to ' +
+      '{items: [], totalCount: 0} via the HELPER\'s own gate — CollectionsScreen no longer keeps a ' +
+      'second copy of this check; the #685 second review proved the two masked each other), the ' +
+      'typed text is compiled via titleContainsQuery rather than forwarded raw, and each kind is ' +
+      'bounded to one request per settled query at LIBRARY_PICKER_RESULTS rows. Unlike the #685 ' +
+      'first fix, this is NOT "nothing left to hint at": the per-kind cap can still truncate the ' +
+      "real match count below what totalCount reports, and AddItemsDialog now sums each kind's " +
+      "totalCount and renders a 'Showing N of M' hint when it exceeds the rendered rows. The only " +
+      'remaining client-side filter in AddItemsDialog (ADDABLE_TYPES.has(item.mediaType)) is inert, ' +
+      'not a silent drop, and this is now enforced by the type system rather than by convention: ' +
+      "MediaKindFilter is derived from ADDABLE_TYPE_LIST (`(typeof ADDABLE_TYPE_LIST)[number]`), so " +
+      'adding a non-addable kind to MEDIA_KIND_FILTERS is a compile error, not a silently-possible ' +
+      'mismatch.'
   },
   {
     file: 'api/paging.ts',
diff --git a/web/src/screens/CollectionsScreen.test.tsx b/web/src/screens/CollectionsScreen.test.tsx
index 751d020b4..831ce49fd 100644
--- a/web/src/screens/CollectionsScreen.test.tsx
+++ b/web/src/screens/CollectionsScreen.test.tsx
@@ -551,6 +551,98 @@ describe('CollectionsScreen', () => {
     expect(within(dialog).queryByText(/Showing .* of .* matches/)).not.toBeInTheDocument();
   });
 
+  it(
+    'labels the results with the query that produced them, and clearing without re-submitting keeps rows + label (#685 review)',
+    async () => {
+      mockAddItemsApi();
+
+      const dialog = await openAddItemsDialog();
+      fireEvent.change(within(dialog).getByPlaceholderText('Search movies, shows, seasons, artists…'), {
+        target: { value: 'za' }
+      });
+      fireEvent.click(within(dialog).getByRole('button', { name: 'Search' }));
+
+      expect(await within(dialog).findByText('Zathura')).toBeInTheDocument();
+      expect(
+        within(dialog).getByText(
+          (_content, element) => element?.tagName === 'P' && element.textContent === 'Results for “za”'
+        )
+      ).toBeInTheDocument();
+
+      // Clear the input WITHOUT re-submitting: the rows and their label must still describe the
+      // original ("za") search — nothing says which query produced an on-screen row otherwise.
+      fireEvent.change(within(dialog).getByPlaceholderText('Search movies, shows, seasons, artists…'), {
+        target: { value: '' }
+      });
+
+      expect(within(dialog).getByText('Zathura')).toBeInTheDocument();
+      expect(
+        within(dialog).getByText(
+          (_content, element) => element?.tagName === 'P' && element.textContent === 'Results for “za”'
+        )
+      ).toBeInTheDocument();
+    }
+  );
+
+  it(
+    'clearing the input and re-submitting shows the min-query guidance while the selection stays discoverable (#685 review)',
+    async () => {
+      mockAddItemsApi();
+
+      const dialog = await openAddItemsDialog();
+      fireEvent.change(within(dialog).getByPlaceholderText('Search movies, shows, seasons, artists…'), {
+        target: { value: 'za' }
+      });
+      fireEvent.click(within(dialog).getByRole('button', { name: 'Search' }));
+
+      expect(await within(dialog).findByText('Zathura')).toBeInTheDocument();
+      fireEvent.click(within(dialog).getByText('Zathura'));
+      expect(within(dialog).getByRole('button', { name: /Add 1 item/ })).toBeInTheDocument();
+
+      // Clear the input and re-submit: the helper's gate resolves every kind to
+      // { items: [], totalCount: 0 }, so the (now query-less) results are empty.
+      fireEvent.change(within(dialog).getByPlaceholderText('Search movies, shows, seasons, artists…'), {
+        target: { value: '' }
+      });
+      fireEvent.click(within(dialog).getByRole('button', { name: 'Search' }));
+
+      await waitFor(() => {
+        expect(
+          within(dialog).getByText(`Type at least ${LIBRARY_PICKER_MIN_QUERY} characters to search.`)
+        ).toBeInTheDocument();
+      });
+      // `selected` persists across queries (correct for a multi-select picker) — it must never be
+      // invisible-but-counted, and the Add button's count is where that stays discoverable even
+      // though the previously-ticked row isn't in the (now empty) result set.
+      expect(within(dialog).getByRole('button', { name: /Add 1 item/ })).toBeInTheDocument();
+      // And the "Results for" heading is gone, not showing a stale/misleading query.
+      expect(within(dialog).queryByText(/^Results for /)).not.toBeInTheDocument();
+    }
+  );
+
+  it('clears the truncation hint on a failed search (#685 review)', async () => {
+    const fetchMock = mockApi({
+      onRequest: (url) => {
+        if (url.startsWith('/api/v1/library/browse')) {
+          return jsonResponse({ page: [], totalCount: 0 }, 500);
+        }
+        return null;
+      }
+    });
+
+    const dialog = await openAddItemsDialog();
+    fireEvent.change(within(dialog).getByPlaceholderText('Search movies, shows, seasons, artists…'), {
+      target: { value: 'za' }
+    });
+    fireEvent.click(within(dialog).getByRole('button', { name: 'Search' }));
+
+    await waitFor(() => {
+      expect(within(dialog).getByRole('alert')).toBeInTheDocument();
+    });
+    expect(within(dialog).queryByText(/Showing .* of .* matches/)).not.toBeInTheDocument();
+    expect(fetchMock).toHaveBeenCalled();
+  });
+
   /* ---------- add-items search bounds (#685) ---------- */
 
   function buildLibraryFixture(mediaType: string, count: number): { id: number; mediaItemId: number; mediaType: string; title: string }[] {
diff --git a/web/src/screens/CollectionsScreen.tsx b/web/src/screens/CollectionsScreen.tsx
index b7d819194..a43412187 100644
--- a/web/src/screens/CollectionsScreen.tsx
+++ b/web/src/screens/CollectionsScreen.tsx
@@ -53,8 +53,13 @@ import { SmartCollectionDialog } from '../builder/SmartCollectionDialog';
 
 type Tab = 'manual' | 'smart';
 
-// Every kind that can be added to a manual collection from the picker.
-const ADDABLE_TYPE_LIST: LibraryBrowseItem['mediaType'][] = [
+// Every kind that can be added to a manual collection from the picker. `as const satisfies`
+// keeps this a literal-string tuple (rather than widening to the whole `mediaType` union) while
+// still checking each entry against it, so `MediaKindFilter` below can be DERIVED from this list:
+// adding a non-addable kind to `MEDIA_KIND_FILTERS` becomes a compile error instead of a
+// convention nothing enforces (#685 review — the sum-of-totalCount hint is only correct because
+// every filterable kind is addable, and this makes that structural rather than a comment).
+const ADDABLE_TYPE_LIST = [
   'Movie',
   'TelevisionShow',
   'TelevisionSeason',
@@ -65,7 +70,7 @@ const ADDABLE_TYPE_LIST: LibraryBrowseItem['mediaType'][] = [
   'OtherVideo',
   'Image',
   'RemoteStream'
-];
+] as const satisfies readonly LibraryBrowseItem['mediaType'][];
 const ADDABLE_TYPES = new Set<LibraryBrowseItem['mediaType']>(ADDABLE_TYPE_LIST);
 
 // The default fan-out excludes seasons so a multi-season show doesn't flood the
@@ -73,7 +78,7 @@ const ADDABLE_TYPES = new Set<LibraryBrowseItem['mediaType']>(ADDABLE_TYPE_LIST)
 // added for #211) stay reachable via the explicit media-kind filter below.
 const DEFAULT_SEARCH_KINDS: LibraryBrowseItem['mediaType'][] = ['Movie', 'TelevisionShow', 'Artist'];
 
-type MediaKindFilter = 'all' | LibraryBrowseItem['mediaType'];
+type MediaKindFilter = 'all' | (typeof ADDABLE_TYPE_LIST)[number];
 
 const MEDIA_KIND_FILTERS: { label: string; value: MediaKindFilter }[] = [
   { label: 'All', value: 'all' },
@@ -219,30 +224,26 @@ function AddItemsDialog({
   const [query, setQuery] = useState('');
   const [results, setResults] = useState<LibraryBrowseItem[]>([]);
   const [totalMatches, setTotalMatches] = useState(0);
+  // The query a *settled* search actually ran for — never the live input. Rendered as a heading
+  // over the results so a submitted-then-cleared input, or a selection made under an earlier
+  // query, is never shown without saying which query produced it (#685 review). Reset to '' when
+  // a search settles below LIBRARY_PICKER_MIN_QUERY (nothing was actually searched) or errors.
+  const [submittedQuery, setSubmittedQuery] = useState('');
   const [searching, setSearching] = useState(false);
   const [selected, setSelected] = useState<Map<string, LibraryBrowseItem>>(() => new Map());
   const [error, setError] = useState<string | null>(null);
   const [adding, setAdding] = useState(false);
   const [kindFilter, setKindFilter] = useState<MediaKindFilter>('all');
 
-  // Below LIBRARY_PICKER_MIN_QUERY, this issues NOTHING: a blank/short form submit and a
-  // kind-chip click (see selectKindFilter) both route through here, and #685 was exactly this
-  // gate missing — an empty query degraded into an unfiltered browse of the whole
-  // media-library type, per kind, with no truncation indicator. The gate itself — along with the
-  // pageSize clamp and the raw-Lucene-vs-compiled-query choice — now lives in
-  // `searchLibraryBrowseItems` (§3b: "the bound belongs to the helper, not the caller"), so this is
-  // the only early return left here, kept to avoid flipping the searching spinner for a sub-gate
-  // query rather than to re-implement the gate.
+  // `searchLibraryBrowseItems` owns the min-query gate, the pageSize clamp, and the
+  // raw-Lucene-vs-compiled-query choice (§3b: "the bound belongs to the helper, not the caller").
+  // This screen used to keep a SECOND copy of the min-query check here — the #685 review proved
+  // the two masked each other (deleting either one left the whole suite green, so the boundary
+  // test pinned nothing) — so there is now exactly one gate, in the helper, and every caller
+  // (blank form submit, kind-chip click) routes through it unconditionally.
   const runSearch = async (filter: MediaKindFilter = kindFilter) => {
     const trimmed = query.trim();
 
-    if (trimmed.length < LIBRARY_PICKER_MIN_QUERY) {
-      setResults([]);
-      setTotalMatches(0);
-      setError(null);
-      return;
-    }
-
     setSearching(true);
     setError(null);
 
@@ -259,8 +260,18 @@ function AddItemsDialog({
       // below via totalMatches (#685 review finding 4).
       setResults(merged);
       setTotalMatches(perKind.reduce((sum, result) => sum + result.totalCount, 0));
+      // Below LIBRARY_PICKER_MIN_QUERY, the helper's own gate resolves every kind to
+      // { items: [], totalCount: 0 } without issuing a request — so `merged`/`totalMatches` above
+      // are already empty in that case, but `submittedQuery` must say "nothing was actually
+      // searched" rather than name the sub-gate text.
+      setSubmittedQuery(trimmed.length < LIBRARY_PICKER_MIN_QUERY ? '' : trimmed);
     } catch (searchError) {
       setError(messageFromCollectionError(searchError, 'Unable to search library'));
+      // A failed search must not leave a stale results/totalMatches pair rendering a confident
+      // "Showing N of M matches" hint beside the error banner (#685 review).
+      setResults([]);
+      setTotalMatches(0);
+      setSubmittedQuery('');
     } finally {
       setSearching(false);
     }
@@ -268,9 +279,8 @@ function AddItemsDialog({
 
   // A kind-chip click is the second path into runSearch (a blank form submit is the other), and it
   // is deliberately NOT gated here: runSearch is the single sink and owns the min-query gate for
-  // every caller. A duplicate check at this one call site was verified non-load-bearing (removing
-  // it changed no test), and §3b is explicit that an unreachable guard is an untested one — the
-  // next path added would be the one nobody remembers to gate.
+  // every caller via searchLibraryBrowseItems. §3b is explicit that an unreachable guard is an
+  // untested one — the next path added would be the one nobody remembers to gate.
   const selectKindFilter = (filter: MediaKindFilter) => {
     setKindFilter(filter);
     void runSearch(filter);
@@ -372,17 +382,27 @@ function AddItemsDialog({
           {error}
         </span>
       )}
-      {totalMatches > results.length && (
+      {submittedQuery !== '' && (
+        // Names the query the CURRENT results (or the empty-results/"no matches" state) belong
+        // to — never the live input, so a submitted-then-cleared query, or a selection made under
+        // an earlier query, is never shown without saying which search produced it (#685 review).
         <p className="ctv-collections-picker-note">
+          Results for &ldquo;{submittedQuery}&rdquo;
+        </p>
+      )}
+      {totalMatches > results.length && (
+        <p aria-live="polite" className="ctv-collections-picker-note">
           Showing {results.length} of {totalMatches} matches — narrow your search.
         </p>
       )}
       <div className="ctv-collections-picker-results">
-        {results.length === 0 && query.trim().length < LIBRARY_PICKER_MIN_QUERY ? (
-          // Keyed to results.length, not just the live input: without it, backspacing the query
-          // back below the min-query length after a successful search wiped the rendered rows AND
-          // their checkmarks while `selected` (and the Add button's count) still held them
-          // (#685 review finding 1).
+        {results.length === 0 && submittedQuery === '' ? (
+          // Keyed to submittedQuery, not the live input: without it, backspacing the query back
+          // below the min-query length after a successful search wiped the rendered rows AND their
+          // checkmarks while `selected` (and the Add button's count) still held them (#685 review
+          // finding 1) — and, separately, submitting a blank/cleared query after a real selection
+          // must still say the selection persists rather than rendering as if nothing was ever
+          // searched (#685 second review).
           <div className="ctv-collections-picker-empty">
             Type at least {LIBRARY_PICKER_MIN_QUERY} characters to search.
           </div>

From d7725c274c8ee0d968fef8dbf2e66d5933dd6feb Mon Sep 17 00:00:00 2001
From: Timothy <timothy@noreply.gitea.tblindustries.be>
Date: Wed, 5 Aug 2026 19:20:26 +0200
Subject: [PATCH 4/5] fix(685): close the second ingress; stop the error path
 claiming a short query
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Verification round returned MERGEABLE with all three blocking findings resolved
by measurement. These are its four remaining items.

- DEFAULT_SEARCH_KINDS was the SECOND ingress into the searched kinds and was
  not derived, so the previous commit's "enforced by the type system" claim held
  for one of two paths. A non-addable kind there typechecked clean and would
  have overstated the hint with every one of its rows dropped — the exact defect
  the derivation exists to prevent. Now derived; verified by mutation that
  adding 'Collection' to it is a compile error.

- The error path fell into the min-query guidance branch, so a valid 2-character
  query that got a 500 told the user to type at least 2 characters. That branch
  conflated "nothing searched yet" with "the last search failed". Newly
  introduced by the previous commit's error-path reset; now gated on !error and
  pinned by a test.

- The aria-live region was mounted conditionally, creating the region and its
  text in one commit — which most screen readers do not announce. It is now
  mounted unconditionally with the condition inside.

- The §3b lesson mis-stated where the duplicate gate lived: it was inside
  runSearch, the genuine single sink, NOT at one of the callers — so the rule as
  written ("put the gate in the single sink, not at each caller") described the
  revision that was rejected. Reworded to the actual lesson: the gate's home is
  the shared helper, and "it's the single sink" is not evidence it is the only
  guard. That misreading is why #685 got this wrong twice.

Declined again, with reasons: the NaN pageSize edge (faithful to the sibling
helper), the clamp test's unpinned lower bound (same), and the registry's
disclosed same-identity substitution gap.

refs #740
---
 docs/spa-conventions.md                     | 14 +++++++++-----
 web/src/api/pageSizeCallSites.guard.test.ts | 11 +++++++----
 web/src/screens/CollectionsScreen.test.tsx  |  8 ++++++++
 web/src/screens/CollectionsScreen.tsx       | 20 +++++++++++++-------
 4 files changed, 37 insertions(+), 16 deletions(-)

diff --git a/docs/spa-conventions.md b/docs/spa-conventions.md
index a1261376e..41e72f174 100644
--- a/docs/spa-conventions.md
+++ b/docs/spa-conventions.md
@@ -199,11 +199,15 @@ the #644 follow-up got Class A right and Class B only half right):
     match count — this is a bulk multi-select add, where "add the 40 matching episodes" is a
     first-class use, so `AddItemsDialog` sums each kind's `totalCount` and renders a `Showing N of
     M matches` hint once it exceeds the rendered rows (finding 4 — an earlier revision of this
-    bullet called the truncation nothing left to hint at). **Put the gate in the single search
-    sink, not at each caller**: `AddItemsDialog` has two entry paths (blank form submit, kind-chip
-    click), and #685's first fix duplicated the check at one of them, which measurably tested
-    nothing — deleting the duplicate reddened no test, while deleting the sink's gate reddened both
-    paths. **Outstanding on this screen**: `AddItemsDialog` still lacks the monotonic `seqRef`
+    bullet called the truncation nothing left to hint at). **The gate's home is the shared HELPER,
+    not the screen — however single-sink the screen's own function looks.** #685 got this wrong
+    twice in a row, and the second time is the instructive one: the check sat inside `runSearch`,
+    which genuinely IS the one sink both entry paths route through, so it read as correct. It was
+    still a duplicate of the helper's gate, and the two masked each other — with both present,
+    deleting EITHER left the whole suite green, so the min-query boundary test pinned nothing.
+    Measured after removing the screen's copy: deleting the helper's gate alone reddens that test
+    and three more. A guard you cannot redden is not a guard, and "it's the single sink" is not
+    evidence that it is the only one. **Outstanding on this screen**: `AddItemsDialog` still lacks the monotonic `seqRef`
     stale-response guard and `useIsMountedRef()` — the same class of guard "Debounced typeaheads"
     below mandates there, applied to a debounced-while-typing fetch; `AddItemsDialog` is an explicit
     Search-button submission, not a typeahead, so that mandate doesn't reach it directly, but the
diff --git a/web/src/api/pageSizeCallSites.guard.test.ts b/web/src/api/pageSizeCallSites.guard.test.ts
index bdc597b3f..d729f0e3a 100644
--- a/web/src/api/pageSizeCallSites.guard.test.ts
+++ b/web/src/api/pageSizeCallSites.guard.test.ts
@@ -187,10 +187,13 @@ const REGISTRY: RegistryEntry[] = [
       "real match count below what totalCount reports, and AddItemsDialog now sums each kind's " +
       "totalCount and renders a 'Showing N of M' hint when it exceeds the rendered rows. The only " +
       'remaining client-side filter in AddItemsDialog (ADDABLE_TYPES.has(item.mediaType)) is inert, ' +
-      'not a silent drop, and this is now enforced by the type system rather than by convention: ' +
-      "MediaKindFilter is derived from ADDABLE_TYPE_LIST (`(typeof ADDABLE_TYPE_LIST)[number]`), so " +
-      'adding a non-addable kind to MEDIA_KIND_FILTERS is a compile error, not a silently-possible ' +
-      'mismatch.'
+      'not a silent drop, and this is now enforced by the type system rather than by convention on ' +
+      'BOTH ingress paths into the searched kinds — MediaKindFilter (the explicit-chip path) and ' +
+      'DEFAULT_SEARCH_KINDS (the `all` fan-out) are each derived from ADDABLE_TYPE_LIST via ' +
+      '`(typeof ADDABLE_TYPE_LIST)[number]`, so adding a non-addable kind to either is a compile ' +
+      'error. Enforcing only the first was the #685 round-3 review finding: the hint sums ' +
+      'PRE-filter totalCounts against POST-filter rows, so one unenforced ingress is enough to ' +
+      'overstate it with every row of that kind dropped.'
   },
   {
     file: 'api/paging.ts',
diff --git a/web/src/screens/CollectionsScreen.test.tsx b/web/src/screens/CollectionsScreen.test.tsx
index 831ce49fd..237919112 100644
--- a/web/src/screens/CollectionsScreen.test.tsx
+++ b/web/src/screens/CollectionsScreen.test.tsx
@@ -641,6 +641,14 @@ describe('CollectionsScreen', () => {
     });
     expect(within(dialog).queryByText(/Showing .* of .* matches/)).not.toBeInTheDocument();
     expect(fetchMock).toHaveBeenCalled();
+
+    // A failed search must NOT fall into the min-query guidance branch: the user typed a valid
+    // 2-character query and got a 500, so telling them to "type at least 2 characters" states
+    // something false about what they just did. The error banner is the whole message (#685
+    // review round 3 — that branch conflated "nothing searched yet" with "the last search failed").
+    expect(
+      within(dialog).queryByText(`Type at least ${LIBRARY_PICKER_MIN_QUERY} characters to search.`)
+    ).not.toBeInTheDocument();
   });
 
   /* ---------- add-items search bounds (#685) ---------- */
diff --git a/web/src/screens/CollectionsScreen.tsx b/web/src/screens/CollectionsScreen.tsx
index a43412187..0165ace4b 100644
--- a/web/src/screens/CollectionsScreen.tsx
+++ b/web/src/screens/CollectionsScreen.tsx
@@ -76,7 +76,12 @@ const ADDABLE_TYPES = new Set<LibraryBrowseItem['mediaType']>(ADDABLE_TYPE_LIST)
 // The default fan-out excludes seasons so a multi-season show doesn't flood the
 // results with per-season rows (issue #180); seasons (and the other narrower kinds
 // added for #211) stay reachable via the explicit media-kind filter below.
-const DEFAULT_SEARCH_KINDS: LibraryBrowseItem['mediaType'][] = ['Movie', 'TelevisionShow', 'Artist'];
+// Derived from ADDABLE_TYPE_LIST for the same reason MediaKindFilter is: this is the SECOND
+// ingress into `kinds` (the `all` branch of runSearch), and the truncation hint sums pre-filter
+// totalCounts against post-ADDABLE_TYPES rows. A non-addable kind here would overstate the hint
+// with every one of its rows dropped, and typing it as the whole mediaType union let that through
+// (#685 review round 3 — one of two ingress paths was enforced, which is not an invariant).
+const DEFAULT_SEARCH_KINDS: (typeof ADDABLE_TYPE_LIST)[number][] = ['Movie', 'TelevisionShow', 'Artist'];
 
 type MediaKindFilter = 'all' | (typeof ADDABLE_TYPE_LIST)[number];
 
@@ -390,13 +395,14 @@ function AddItemsDialog({
           Results for &ldquo;{submittedQuery}&rdquo;
         </p>
       )}
-      {totalMatches > results.length && (
-        <p aria-live="polite" className="ctv-collections-picker-note">
-          Showing {results.length} of {totalMatches} matches — narrow your search.
-        </p>
-      )}
+      {/* The live region is mounted UNCONDITIONALLY with the condition inside it: most screen
+          readers only announce mutations to a region that already existed, so creating the region
+          and its text in the same commit announces nothing (#685 review round 3). */}
+      <p aria-live="polite" className="ctv-collections-picker-note">
+        {totalMatches > results.length ? `Showing ${results.length} of ${totalMatches} matches — narrow your search.` : ''}
+      </p>
       <div className="ctv-collections-picker-results">
-        {results.length === 0 && submittedQuery === '' ? (
+        {results.length === 0 && submittedQuery === '' && !error ? (
           // Keyed to submittedQuery, not the live input: without it, backspacing the query back
           // below the min-query length after a successful search wiped the rendered rows AND their
           // checkmarks while `selected` (and the Add button's count) still held them (#685 review

From 7be42654feb996113f3f977f460998ea1481ca52 Mon Sep 17 00:00:00 2001
From: Timothy <timothy@noreply.gitea.tblindustries.be>
Date: Wed, 5 Aug 2026 19:32:08 +0200
Subject: [PATCH 5/5] fix(685): suppress both empty-states on error; name the
 addable-kind derivation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Round-4 verification returned MERGEABLE with no new defects and no
BLOCKER/HIGH/MEDIUM. These are its remaining LOW and nits.

- "No results — try a search above." asserts a search that COMPLETED and found
  nothing, so it was false beside a failed request. Both empty-state messages
  are now suppressed on error and the role="alert" banner is the whole message,
  as that test's comment already claimed. Pinned positively and negatively so a
  refactor cannot satisfy the assertion by rendering nothing at all.

- The (typeof ADDABLE_TYPE_LIST)[number] derivation is now the named
  AddableKind, spelled once instead of twice: a third ingress into the searched
  kinds is most likely to be written by copying one of the existing two, and the
  "one list, all ingresses" property should be visible at a glance rather than
  reassembled.

- The §3b lesson cited two measured test counts, which go stale against the very
  suite they describe — a count taken before the helper had unit tests no longer
  holds now that it does. Scoped the observation to the sha it was measured on
  and replaced the counts with the invariant they were evidence for: every gate
  needs at least one test that reddens when that gate ALONE is removed.

- Documented why the error banner stays conditionally mounted while the hint's
  live region does not: role="alert" is the one live-region role screen readers
  reliably announce on insertion, so the two are correct for opposite reasons.
  The review flagged the divergence as unexplained, not as wrong.

refs #740
---
 docs/spa-conventions.md                    | 11 ++++++-----
 web/src/screens/CollectionsScreen.test.tsx |  6 ++++++
 web/src/screens/CollectionsScreen.tsx      | 19 ++++++++++++++++---
 3 files changed, 28 insertions(+), 8 deletions(-)

diff --git a/docs/spa-conventions.md b/docs/spa-conventions.md
index 41e72f174..45764c1ec 100644
--- a/docs/spa-conventions.md
+++ b/docs/spa-conventions.md
@@ -203,11 +203,12 @@ the #644 follow-up got Class A right and Class B only half right):
     not the screen — however single-sink the screen's own function looks.** #685 got this wrong
     twice in a row, and the second time is the instructive one: the check sat inside `runSearch`,
     which genuinely IS the one sink both entry paths route through, so it read as correct. It was
-    still a duplicate of the helper's gate, and the two masked each other — with both present,
-    deleting EITHER left the whole suite green, so the min-query boundary test pinned nothing.
-    Measured after removing the screen's copy: deleting the helper's gate alone reddens that test
-    and three more. A guard you cannot redden is not a guard, and "it's the single sink" is not
-    evidence that it is the only one. **Outstanding on this screen**: `AddItemsDialog` still lacks the monotonic `seqRef`
+    still a duplicate of the helper's gate, and the two masked each other: as of `4be3f247d` —
+    which had no unit tests on the helper — deleting EITHER copy left the whole suite green, so the
+    min-query boundary test pinned nothing. Removing the screen's copy is what made the helper's
+    gate load-bearing. **The invariant, not the count: every gate must have at least one test that
+    reddens when that gate ALONE is removed.** A guard you cannot redden is not a guard, and "it's
+    the single sink" is not evidence that it is the only one. **Outstanding on this screen**: `AddItemsDialog` still lacks the monotonic `seqRef`
     stale-response guard and `useIsMountedRef()` — the same class of guard "Debounced typeaheads"
     below mandates there, applied to a debounced-while-typing fetch; `AddItemsDialog` is an explicit
     Search-button submission, not a typeahead, so that mandate doesn't reach it directly, but the
diff --git a/web/src/screens/CollectionsScreen.test.tsx b/web/src/screens/CollectionsScreen.test.tsx
index 237919112..3b1ab1485 100644
--- a/web/src/screens/CollectionsScreen.test.tsx
+++ b/web/src/screens/CollectionsScreen.test.tsx
@@ -649,6 +649,12 @@ describe('CollectionsScreen', () => {
     expect(
       within(dialog).queryByText(`Type at least ${LIBRARY_PICKER_MIN_QUERY} characters to search.`)
     ).not.toBeInTheDocument();
+    // Nor "No results", which asserts a search that COMPLETED and found nothing. Both empty-state
+    // messages are suppressed on error, leaving the alert banner as the whole message. Pinned
+    // positively as well as negatively so a refactor cannot satisfy this by rendering nothing at
+    // all (#685 review round 4).
+    expect(within(dialog).queryByText('No results — try a search above.')).not.toBeInTheDocument();
+    expect(within(dialog).getByRole('alert')).toHaveTextContent(/500/);
   });
 
   /* ---------- add-items search bounds (#685) ---------- */
diff --git a/web/src/screens/CollectionsScreen.tsx b/web/src/screens/CollectionsScreen.tsx
index 0165ace4b..d73b3f7d1 100644
--- a/web/src/screens/CollectionsScreen.tsx
+++ b/web/src/screens/CollectionsScreen.tsx
@@ -81,9 +81,15 @@ const ADDABLE_TYPES = new Set<LibraryBrowseItem['mediaType']>(ADDABLE_TYPE_LIST)
 // totalCounts against post-ADDABLE_TYPES rows. A non-addable kind here would overstate the hint
 // with every one of its rows dropped, and typing it as the whole mediaType union let that through
 // (#685 review round 3 — one of two ingress paths was enforced, which is not an invariant).
-const DEFAULT_SEARCH_KINDS: (typeof ADDABLE_TYPE_LIST)[number][] = ['Movie', 'TelevisionShow', 'Artist'];
+const DEFAULT_SEARCH_KINDS: AddableKind[] = ['Movie', 'TelevisionShow', 'Artist'];
 
-type MediaKindFilter = 'all' | (typeof ADDABLE_TYPE_LIST)[number];
+// The single derivation every ingress into the searched kinds goes through. Named rather than
+// spelled inline at each use so the "one list, all ingresses" property is visible at a glance —
+// a fourth ingress is most likely to be written by copying one of the existing three (#685
+// review round 4).
+type AddableKind = (typeof ADDABLE_TYPE_LIST)[number];
+
+type MediaKindFilter = 'all' | AddableKind;
 
 const MEDIA_KIND_FILTERS: { label: string; value: MediaKindFilter }[] = [
   { label: 'All', value: 'all' },
@@ -382,6 +388,10 @@ function AddItemsDialog({
         &ldquo;All&rdquo; searches movies, shows and artists; pick a specific kind to add seasons, episodes,
         music videos, songs, other videos, images or remote streams.
       </p>
+      {/* Conditionally mounted, unlike the aria-live hint below — deliberately, not by oversight:
+          `role="alert"` is the one live-region role screen readers reliably announce on INSERTION,
+          so mounting it together with its content is right here and would be wrong there (#685
+          review round 4 flagged the divergence as unexplained). */}
       {error && (
         <span className="ctv-field-error" role="alert">
           {error}
@@ -412,7 +422,10 @@ function AddItemsDialog({
           <div className="ctv-collections-picker-empty">
             Type at least {LIBRARY_PICKER_MIN_QUERY} characters to search.
           </div>
-        ) : results.length === 0 && !searching ? (
+        ) : results.length === 0 && !searching && !error ? (
+          // Also suppressed on `error`: "No results" asserts a search that COMPLETED and found
+          // nothing, which is false when the request failed. The role="alert" banner above is the
+          // whole message in that state (#685 review round 4).
           <div className="ctv-collections-picker-empty">No results — try a search above.</div>
         ) : (
           results.map((item) => {