CollectionsScreen AddItemsDialog windows the whole media-library type on an empty query, with no truncation surfaced (§3b deviation) #685

Closed
opened 2026-07-27 19:01:09 +02:00 by timothy · 2 comments
Owner

Found while reconciling the #650 pageSize registry in #684. Not fixed there — #684 records it
honestly as a deviation rather than mislabelling it compliant. This issue is the fix.

The defect

AddItemsDialog.runSearch (web/src/screens/CollectionsScreen.tsx:225) is reachable with an empty
query
by two paths:

  • submitting the search form with a blank input (:311)
  • clicking any media-kind filter chip before typing — selectKindFilter calls runSearch(filter)
    immediately (:247, :333)

getLibraryBrowseItems omits query when falsy (web/src/api/libraryBrowse.ts:21, if (params.query)), so an empty query degrades the request into an unfiltered browse of the whole
type, first 50 rows
— for each of DEFAULT_SEARCH_KINDS when the filter is all. That is exactly
the bounded-window picker shape docs/spa-conventions.md §3b forbids for media-library types
post-#651.

Nothing surfaces the truncation: runSearch never reads result.totalCount, and the render
(:346-372) has no hint. Separately, merged.slice(0, 50) (:239) silently drops up to 100 of 150
fetched rows even for a real query.

Scenario: open "Add items" on a 20k-episode library, click the "Episodes" chip, and the
alphabetically-first 50 episodes are presented as the answer with no indication anything is missing.

Why it was invisible

It requests pageSize: 50 — under the cap — so neither #644's inflated-pageSize grep nor #650's
at-cap check could see it. The #650 registry classified it class-b ("bounded page with totalCount
surfaced"), which was already false: no hint has ever rendered here.

Fix direction

Per §3b, media-library types resolve by SEARCH: render SearchPicker over
searchLibraryPickerOptions (spa.library-pickers-resolve-by-search), gated on
LIBRARY_PICKER_MIN_QUERY, so a kind-chip click issues zero requests. Note ADDABLE_TYPES
includes collection-family types, which §3b excludes from search (the handler LIKE-matches query
for those) — those keep the bounded page and must gain a real truncation hint.

Once fixed, flip the registry entry in web/src/api/pageSizeCallSites.guard.test.ts from
deviation to its true class and drop the deviation note.

Done-when

  • An empty query issues no whole-type browse (either no request, or a bounded one whose truncation is surfaced)
  • Kind-chip selection issues zero requests before the min-query gate
  • The merged.slice(0, 50) drop is either removed or surfaced
  • Collection-family types (excluded from search by §3b) surface a real truncation hint — no subject on this screen; see note below
  • Registry entry reclassified away from deviation; guard green
  • Adversarial review passed

Note on box 4 (ticked as not-applicable, not as done): this issue's body states that
ADDABLE_TYPES includes collection-family types. It does not. All ten ADDABLE_TYPE_LIST entries
(Movie, TelevisionShow, TelevisionSeason, Artist, Episode, MusicVideo, Song,
OtherVideo, Image, RemoteStream) are §3b Class B media-library types, and
MEDIA_KIND_FILTERS offers no collection-family kind — so there is no collection-family picker here
to give a truncation hint to. Verified in code before the fix was designed, and confirmed
independently during review. Nothing was skipped.

The media truncation the box was reaching for IS surfaced: each kind is capped at
LIBRARY_PICKER_RESULTS, and AddItemsDialog now sums the per-kind totalCount and renders
Showing N of M matches — narrow your search.

Found while reconciling the #650 `pageSize` registry in #684. **Not fixed there** — #684 records it honestly as a deviation rather than mislabelling it compliant. This issue is the fix. ## The defect `AddItemsDialog.runSearch` (`web/src/screens/CollectionsScreen.tsx:225`) is reachable with an **empty query** by two paths: - submitting the search form with a blank input (`:311`) - clicking any media-kind filter chip before typing — `selectKindFilter` calls `runSearch(filter)` immediately (`:247`, `:333`) `getLibraryBrowseItems` omits `query` when falsy (`web/src/api/libraryBrowse.ts:21`, `if (params.query)`), so an empty query degrades the request into an **unfiltered browse of the whole type, first 50 rows** — for each of `DEFAULT_SEARCH_KINDS` when the filter is `all`. That is exactly the bounded-window picker shape `docs/spa-conventions.md` §3b forbids for media-library types post-#651. Nothing surfaces the truncation: `runSearch` never reads `result.totalCount`, and the render (`:346-372`) has no hint. Separately, `merged.slice(0, 50)` (`:239`) silently drops up to 100 of 150 fetched rows even for a *real* query. **Scenario:** open "Add items" on a 20k-episode library, click the "Episodes" chip, and the alphabetically-first 50 episodes are presented as the answer with no indication anything is missing. ## Why it was invisible It requests `pageSize: 50` — under the cap — so neither #644's inflated-`pageSize` grep nor #650's at-cap check could see it. The #650 registry classified it `class-b` ("bounded page with `totalCount` surfaced"), which was already false: no hint has ever rendered here. ## Fix direction Per §3b, media-library types resolve by SEARCH: render `SearchPicker` over `searchLibraryPickerOptions` (`spa.library-pickers-resolve-by-search`), gated on `LIBRARY_PICKER_MIN_QUERY`, so a kind-chip click issues **zero** requests. Note `ADDABLE_TYPES` includes collection-family types, which §3b excludes from search (the handler LIKE-matches `query` for those) — those keep the bounded page and must gain a real truncation hint. Once fixed, flip the registry entry in `web/src/api/pageSizeCallSites.guard.test.ts` from `deviation` to its true class and drop the deviation note. ## Done-when - [x] An empty query issues no whole-type browse (either no request, or a bounded one whose truncation is surfaced) - [x] Kind-chip selection issues zero requests before the min-query gate - [x] The `merged.slice(0, 50)` drop is either removed or surfaced - [x] ~~Collection-family types (excluded from search by §3b) surface a real truncation hint~~ — **no subject on this screen**; see note below - [x] Registry entry reclassified away from `deviation`; guard green - [x] Adversarial review passed **Note on box 4** (ticked as not-applicable, not as done): this issue's body states that `ADDABLE_TYPES` includes collection-family types. It does not. All ten `ADDABLE_TYPE_LIST` entries (`Movie`, `TelevisionShow`, `TelevisionSeason`, `Artist`, `Episode`, `MusicVideo`, `Song`, `OtherVideo`, `Image`, `RemoteStream`) are §3b **Class B** media-library types, and `MEDIA_KIND_FILTERS` offers no collection-family kind — so there is no collection-family picker here to give a truncation hint to. Verified in code before the fix was designed, and confirmed independently during review. Nothing was skipped. The *media* truncation the box was reaching for IS surfaced: each kind is capped at `LIBRARY_PICKER_RESULTS`, and `AddItemsDialog` now sums the per-kind `totalCount` and renders `Showing N of M matches — narrow your search.`
timothy added the bugfrontendpriority: medium labels 2026-07-27 19:40:49 +02:00
Author
Owner

Claiming this — Claude Code session, 2026-08-05. Working the §3b SearchPicker conversion for AddItemsDialog per the fix direction in the body.

Claiming this — Claude Code session, 2026-08-05. Working the §3b SearchPicker conversion for AddItemsDialog per the fix direction in the body.
timothy added the in-progress label 2026-08-05 18:14:11 +02:00
Author
Owner

Closing record

Outcome: Fixed and merged — PR #741 (5 commits, merged to main). AddItemsDialog now resolves by search: no request below LIBRARY_PICKER_MIN_QUERY from either entry path, one bounded request per kind per settled query, raw text compiled via titleContainsQuery, merged.slice(0, 50) removed, and the per-kind cap surfaced as Showing N of M matches. Results carry a Results for "<query>" label keyed to the settled query.

Root cause: Two independent causes, both invisible to the checks that should have caught them.
(1) getLibraryBrowseItems omits query when falsy (if (params.query)), so an empty query silently becomes no filter rather than no results — a browse of the whole type. runSearch never required a query, and selectKindFilter called it immediately on a chip click.
(2) It requested pageSize: 50, under the 100 cap, so neither #644's inflated-pageSize grep nor #650's at-cap check could see it. The #650 registry then classified it class-b ("bounded page with totalCount surfaced"), which was already false — no hint had ever rendered here. A registry entry vouching for behaviour that does not exist is the deeper cause: it converted an unexamined call site into a documented-as-safe one.

Decisions/conventions changed: No new key:. docs/spa-conventions.md §3b extended: (a) SearchPicker is the single-select shape, not the rule — a multi-select picker satisfies §3b by taking the constraints via a shared helper; (b) the parent paragraph's "there is no truncation, so there is no truncation hint" corrected, since it contradicted the new hint two lines below; (c) a gate's home is the shared helper, not the screen.

Reusable knowledge:

  • A gate needs a test that reddens when that gate ALONE is removed. This fix duplicated a min-query check twice in a row. The second time it sat inside runSearch — the genuine single sink both entry paths route through, so it read as correct — while the helper also gated. The two masked each other: with both present, deleting either left the whole suite green, so the boundary test pinned nothing. "It's the single sink" is not evidence it is the only guard.
  • Moving a bound into a helper does not move its proof. Extracting searchLibraryBrowseItems to make the bound structural shipped with zero tests, so deleting its clamp left 1119/1119 green while the registry note claimed callers "cannot skip the bound". Review round 2 BLOCKED on exactly this — the previous round's finding relocated, not removed.
  • A derived-type invariant must cover every ingress. MediaKindFilter was derived from ADDABLE_TYPE_LIST and the note claimed type-system enforcement — but DEFAULT_SEARCH_KINDS, the all fan-out, was a second ingress and still typed as the whole union. One unenforced ingress is enough to overstate a hint that sums pre-filter counts against post-filter rows.
  • A <p aria-live> mounted together with its content announces nothing — most screen readers only announce mutations to a region that already existed. role="alert" is the opposite: it is the one live-region role reliably announced on insertion. The two are correct for opposite reasons.
  • The issue body was wrong on two points, both verified before designing the fix: ADDABLE_TYPES contains no collection-family types (all ten are Class B media types), and the prescribed SearchPicker is single-select and cannot serve this multi-select dialog.

Verification: npm run typecheck clean (never npx tsc --noEmit — solution-style config checks zero files), npm run lint clean, 1199/1199 web tests green locally on current origin/main. CI on head 7be4265: 11/12 green, 1 skipped (image push, not run on PRs); Build & test (.NET) ran ~11 min, so the web suite genuinely executed rather than taking the docs-only fast path. Every new test verified by mutating its single clause and confirming it reddens. Four independent adversarial review rounds (cold brief, isolated worktree, different context each time); round 2 returned BLOCKED, rounds 4 and 5 confirmed no new defects with all severity bands empty. No live-E2E: pure-SPA change, no API or server-state effect.

Deferred: #740 — AddItemsDialog.runSearch has no seqRef stale-response guard, no AbortSignal, and no useIsMountedRef(). Pre-existing, not introduced here (the pre-fix runSearch was equally async and equally unguarded from both paths), and confirmed as such by review. Also declined with reasons, all NIT-level: the NaN pageSize edge (copied faithfully from the sibling helper — diverging would be worse), the clamp test's unpinned lower bound (same), and the registry's same-identity substitution gap (already disclosed in that file's header). One further nit noted and left: error is shared between search and add failures, so a failed add also suppresses a search-derived empty state — same class, no new regression.

Docs updated: docs/spa-conventions.md (§3b, as above) and the web/src/api/pageSizeCallSites.guard.test.ts registry — the CollectionsScreen.tsx deviation entry retired and replaced by a search-bounded entry on api/libraryBrowse.ts, which zeroed the registry's deviation list and required its anti-vacuity assertion to be deliberately retired per that assertion's own instruction, with a bidirectional replacement that still has teeth.

## Closing record **Outcome:** Fixed and merged — PR #741 (5 commits, merged to `main`). `AddItemsDialog` now resolves by search: no request below `LIBRARY_PICKER_MIN_QUERY` from either entry path, one bounded request per kind per settled query, raw text compiled via `titleContainsQuery`, `merged.slice(0, 50)` removed, and the per-kind cap surfaced as `Showing N of M matches`. Results carry a `Results for "<query>"` label keyed to the settled query. **Root cause:** Two independent causes, both invisible to the checks that should have caught them. (1) `getLibraryBrowseItems` omits `query` when falsy (`if (params.query)`), so an empty query silently becomes *no filter* rather than *no results* — a browse of the whole type. `runSearch` never required a query, and `selectKindFilter` called it immediately on a chip click. (2) It requested `pageSize: 50`, **under** the 100 cap, so neither #644's inflated-`pageSize` grep nor #650's at-cap check could see it. The #650 registry then classified it `class-b` ("bounded page with `totalCount` surfaced"), which was already false — no hint had ever rendered here. A registry entry vouching for behaviour that does not exist is the deeper cause: it converted an unexamined call site into a documented-as-safe one. **Decisions/conventions changed:** No new `key:`. `docs/spa-conventions.md` §3b extended: (a) `SearchPicker` is the single-select *shape*, not the rule — a multi-select picker satisfies §3b by taking the constraints via a shared helper; (b) the parent paragraph's "there is no truncation, so there is no truncation hint" corrected, since it contradicted the new hint two lines below; (c) a gate's home is the shared **helper**, not the screen. **Reusable knowledge:** - **A gate needs a test that reddens when that gate ALONE is removed.** This fix duplicated a min-query check twice in a row. The second time it sat inside `runSearch` — the genuine single sink both entry paths route through, so it read as correct — while the helper also gated. The two masked each other: with both present, deleting *either* left the whole suite green, so the boundary test pinned nothing. "It's the single sink" is not evidence it is the only guard. - **Moving a bound into a helper does not move its proof.** Extracting `searchLibraryBrowseItems` to make the bound structural shipped with zero tests, so deleting its clamp left 1119/1119 green while the registry note claimed callers "cannot skip the bound". Review round 2 BLOCKED on exactly this — the previous round's finding relocated, not removed. - **A derived-type invariant must cover every ingress.** `MediaKindFilter` was derived from `ADDABLE_TYPE_LIST` and the note claimed type-system enforcement — but `DEFAULT_SEARCH_KINDS`, the `all` fan-out, was a second ingress and still typed as the whole union. One unenforced ingress is enough to overstate a hint that sums pre-filter counts against post-filter rows. - **A `<p aria-live>` mounted together with its content announces nothing** — most screen readers only announce mutations to a region that already existed. `role="alert"` is the opposite: it is the one live-region role reliably announced *on insertion*. The two are correct for opposite reasons. - **The issue body was wrong on two points**, both verified before designing the fix: `ADDABLE_TYPES` contains no collection-family types (all ten are Class B media types), and the prescribed `SearchPicker` is single-select and cannot serve this multi-select dialog. **Verification:** `npm run typecheck` clean (never `npx tsc --noEmit` — solution-style config checks zero files), `npm run lint` clean, **1199/1199** web tests green locally on current `origin/main`. CI on head `7be4265`: 11/12 green, 1 skipped (image push, not run on PRs); `Build & test (.NET)` ran ~11 min, so the web suite genuinely executed rather than taking the docs-only fast path. Every new test verified by mutating its single clause and confirming it reddens. Four independent adversarial review rounds (cold brief, isolated worktree, different context each time); round 2 returned BLOCKED, rounds 4 and 5 confirmed no new defects with all severity bands empty. No live-E2E: pure-SPA change, no API or server-state effect. **Deferred:** #740 — `AddItemsDialog.runSearch` has no `seqRef` stale-response guard, no `AbortSignal`, and no `useIsMountedRef()`. **Pre-existing, not introduced here** (the pre-fix `runSearch` was equally async and equally unguarded from both paths), and confirmed as such by review. Also declined with reasons, all NIT-level: the `NaN` `pageSize` edge (copied faithfully from the sibling helper — diverging would be worse), the clamp test's unpinned lower bound (same), and the registry's same-identity substitution gap (already disclosed in that file's header). One further nit noted and left: `error` is shared between search and add failures, so a failed *add* also suppresses a search-derived empty state — same class, no new regression. **Docs updated:** `docs/spa-conventions.md` (§3b, as above) and the `web/src/api/pageSizeCallSites.guard.test.ts` registry — the `CollectionsScreen.tsx` `deviation` entry retired and replaced by a `search-bounded` entry on `api/libraryBrowse.ts`, which zeroed the registry's deviation list and required its anti-vacuity assertion to be deliberately retired per that assertion's own instruction, with a bidirectional replacement that still has teeth.
timothy removed the in-progress label 2026-08-05 20:02:54 +02:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: timothy/ersatztv#685