diff --git a/docs/decisions/README.md b/docs/decisions/README.md index 901b99aaf..d75159af8 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -164,7 +164,7 @@ the link for rationale. Superseded/retired history lives in `archive/`. Regenera | `spa.deco-templates-table` | The deco-templates editor also renders its day/deco assignment as a table, extending (not replacing) the templates-editor-table convention. | 2026-07-09 | [link](records/spa/deco-templates-table.md) | | `spa.download-sample-gate` | The SPA disables both Download Media Sample and Download Results while a troubleshooting session is starting/running (Blazor only gated Download Results). | 2026-07-09 | [link](records/spa/download-sample-gate.md) | | `spa.legacy-redirect-matcher` | `LegacyUiRedirects.TryGetRedirect` is a two-tier matcher — an exact `OrdinalIgnoreCase` `Map` (Tier 1) then an ordered segment-template pattern list (Tier 2, first-match-wins) — collision-free by construction, with a guard invariant that no rule may prefix-match `/api`, `/artwork`, `/docs`, `/openapi`, `/iptv`, `/app`, or `/media/sources`. | 2026-07-11 | [link](records/spa/legacy-redirect-matcher.md) | -| `spa.list-completeness-vs-bounded-pickers` | The shared `loadAllPages` helper (`web/src/api/paging.ts`) pages a `/api/v1` list to completeness against `totalCount` and is used ONLY for lists that are bounded by construction (rerun collections, multi-collections, playlists — admin-created, hundreds of rows at most). A `getLibraryBrowseItems` picker over a media-library table (Episode/Song/Image/Movie/MusicVideo, tens of thousands of rows possible) must NOT page to completeness — it fetches ONE bounded page (the server cap) and surfaces the truncation (a `ctv-field-help` hint wired to the real `totalCount`) instead of silently dropping the rest. | 2026-07-26 | [link](records/spa/list-completeness-vs-bounded-pickers.md) | +| `spa.library-pickers-resolve-by-search` | A picker over a media-library table (Episode/Song/Image/Movie/MusicVideo/TelevisionShow/TelevisionSeason/Artist/OtherVideo/RemoteStream) resolves its options by SEARCH — a debounced `SearchPicker` calling `searchLibraryPickerOptions`, which issues at most ONE `getLibraryBrowseItems` request per settled query, bounded to `LIBRARY_PICKER_RESULTS` (25) rows — CLAMPED inside the helper, not merely defaulted — and gated on `LIBRARY_PICKER_MIN_QUERY` (2) characters. It list-loads NOTHING on mount or on a type switch, so there is no truncation to surface and no truncation hint. The typed text is COMPILED (`titleContainsQuery` → `title:**`), never forwarded raw. The current selection renders from the OWNING RECORD, not from the result set (`selectedName` on a rerun collection / playlist item; a single by-id detail read — `getShow`/`getSeason`/`getArtist` — for a filler preset, which stores only the id), and an edit draft is INITIALIZED ONCE from the detail read — never seeded from the list row, never reconciled against a late response — with the form withheld until it lands, the editor failing CLOSED when the response carries no USABLE concurrency token — absent, empty and whitespace-only ETags are ONE case, normalized in one place, so a PUT without `If-Match` is unreachable, and a deadline plus a route back so a hung request cannot strand it. An id NEVER travels without its namespace: search results are cached against `(source, query)` and list-backed options carry the type they were loaded for, so no id from one type can be offered under another; and every id entering editor state — search result, list-backed option, or a selection restored from a detail read — passes ONE shared `isSelectionId` (int32) predicate at that boundary, an unbindable id being treated as ABSENT rather than coerced. Conflicts are detected at SAVE time via `If-Match` -> 412 -> Reload, and Reload simply drops the draft back to null and re-runs the same initialize-once load, so the form is unmounted while the replacement is in flight; an asynchronously-resolved name is keyed to the id it was resolved for and never overwrites a label naming a different id. The typeahead implements the full ARIA combobox keyboard contract, because it replaces a natively keyboard-operable ``. The other half of the superseded record is UNCHANGED: bounded-by-construction admin lists (collections, multi-collections, smart collections, playlists) still page to completeness via `loadAllPages` and still report `complete`/`hint: incomplete`. Server-side caps are not raised — this is a web-only change.' +signals: 'library picker typeahead, SearchPicker, searchLibraryPickerOptions, titleContainsQuery, LIBRARY_PICKER_RESULTS, LIBRARY_PICKER_MIN_QUERY, LIBRARY_PICKER_LUCENE_SPECIALS, compile typed text not raw Lucene, Lucene && || escaping, picker truncation hint removed, loadAllPages Class A, LuceneSearchIndex.Search hitsLimit, useIsMountedRef, aria-activedescendant combobox keyboard, initialize-once draft not hydrate-merge, no list-row seeding, fail closed on a missing or blank ETag, usable concurrency token, cross-type id, id never travels without its namespace, results keyed on (source query), failed search not cached as empty, selection id int32 boundary predicate, isSelectionId, npm run typecheck not tsc --noEmit, stale result set not committable by keyboard OR pointer · paths: `web/src/api/libraryBrowse.ts`, `web/src/schedules/pickers.tsx`, `web/src/hooks.ts`, `web/src/screens/RerunCollectionsScreen.tsx`, `web/src/screens/PlaylistsScreen.tsx`, `web/src/screens/FillerPresetsScreen.tsx`, `web/src/api/paging.ts`, `docs/spa-conventions.md` §3b · issues: #651, #644, #578, #440' +mechanics: '`docs/spa-conventions.md` §3b' +--- + +#644 fixed a silent truncation: three `getLibraryBrowseItems` pickers asked for an over-cap +`pageSize` and got the server's `MaxPageSize` back with no indication. Its follow-up review +(`spa.list-completeness-vs-bounded-pickers`) correctly refused to "fix" that by paging to +completeness — ~200 serial requests against a 20,000-row table, each more expensive than the last +(`LuceneSearchIndex.Search` computes `hitsLimit = skip + limit`), ending in a ``, backed by one shared +`searchLibraryPickerOptions(mediaType, text)`. Selecting a media-library type now issues **zero** +requests; a settled query issues **one**, for at most 25 rows. Both bounds are properties of the +helper, not of a caller's discipline, and are pinned by request-count assertions against a +20,000-row fixture rather than by inspection. + +**Typed text is compiled, never forwarded.** The rule from #440's Auto-Tune add-source typeahead now +binds here too, and its helper is shared rather than re-implemented: `titleContainsQuery` moved out +of `AutoTuneScreen` into `web/src/api/libraryBrowse.ts`. The search index's default field does not +match bare title words — `Alpha` finds nothing for "Show Alpha" — so forwarding the literal text the +way an explicit query box does would look broken in a *name* picker. Every Lucene special (and +whitespace) is escaped so the boundary stars are the only live wildcards, the same shape +`builder/rules/compile.ts` emits for `contains`. + +**The already-selected item is preserved by rendering it from the record, not the result set.** This +is the failure mode that would make a search picker *worse* than the windowed one: a user opening an +existing record must see what it points at, before typing anything and after any search that doesn't +happen to include it. `SearchPicker` already renders `selectedName` independently of `results`, and +rerun collections and playlist items already carry that name on their own DTOs. `FillerPresetFullResponseModel` +does **not** — it stores only the id — so the edit path resolves the name through a single by-id +detail read (`/api/v1/shows|seasons|artists/{id}`), which is *stricter* than the behaviour it +replaces: the old picker could only name a selection that happened to fall inside the first 100 +browse rows, and rendered a bare `#9999` otherwise. A failed resolution degrades to `#id`; it never +clears the id. + +A cold cross-family review found that "renders from the record" was not by itself enough, because +the *record* can arrive without its selection. `RerunCollectionsController.ProjectToResponseModel` +derives both `selectedId` and `selectedName` from the same eager-loaded navigation, and +`GetRerunCollectionByIdHandler` loads media metadata only for Show/Season/Artist/Movie while +`MediaCollections/Mapper` maps RemoteStream through `_ => null` — so opening a RemoteStream rerun +collection returned HTTP 200 with a null selection and the edit-load refresh *cleared a stored id*, +leaving Save permanently disabled. The rule is therefore stated as a prohibition on the client: +**no code path may clear a stored id it merely failed to name.** Every affected type (RemoteStream, +Episode, MusicVideo, Song, OtherVideo, Image) is covered by its own test. The underlying read-model +gaps are server-side, tracked as **#671**; this branch is web-only and the client guard stays after +that lands. + +**The obvious form of that fix is worse than the bug, and this is the part worth remembering.** The +first attempt coalesced the two fields independently — `refreshed.selectedId ?? current.selectedId` +and `refreshed.selectedName || current.selectedName`. But an id and its display name are ONE value: +against a `Song` response (id resolves, name does not), a user selecting a different song while the +refresh was in flight got the *new* name paired with the *stored* id. The chip read "New Song" and +Save wrote 42 — the user's choice discarded with no error and no visual cue, where the original +defect at least cleared the field visibly. A second cold review caught it. The trade is: a visible +failure is strictly better than a silent one, so a "smarter coalesce" is the wrong shape of fix. + +**Round 5 deleted all of it.** What follows is kept because the reasoning is the point, but the +mechanism it describes no longer exists: rounds 2-4 built and rebuilt a layer that reconciled a late +detail response against a draft the user was already editing, and that layer produced a HIGH finding +every single round — three of them cross-user lost updates. The final one was unfixable in kind: the +merge had no immutable baseline, so it could not distinguish "the user changed this" from "the server +changed this", giving both a missed conflict and a false one (the false one leaving `etagRef` null, +turning the next save into a silent force-write). The fix was to **remove the race rather than +referee it**: initialize the draft exactly once from the detail GET, withhold the form until it +lands, and detect conflicts at save time through the `If-Match` -> 412 -> Reload path that already +existed. `touchedRef`, `hydrateDraft`, `hydrateIdentity`, `identityConflicts`, `replaceDraft` and +`replacePending` are all gone. + +Two facts made that safe rather than lossy. First, the list row could never have helped: its handler +applies **zero** `.Include()`s where the detail handler applies **fourteen**, and both project +through the same mapper, so the list response is a strict subset — the id it was being seeded with +is null in production for every row (#671). Every round-1 "preserve the id from the list" guarantee +was therefore protecting a value that only existed in test fixtures. Second, the sibling screens +(`FillerPresetsScreen`, `PlaylistsScreen`) already worked this way; `RerunCollectionsScreen` was the +outlier, which is why nearly every finding in rounds 3-5 traced to it. + +The historical reasoning, retained because the *classes* still bind anywhere a draft is reconciled: + +What replaced it is atomicity plus a race rule — and a third review round showed the first attempt +at *that* had made the same mistake one level up: it enumerated the instance (id/name) instead of +covering the class. **A picker selection is one value spread across three fields**: `collectionType` +says which table an id indexes, `selectedId` picks the row, `selectedName` labels it. Splitting type +from id is the identical bug to splitting id from name — the editor displayed and would have saved +a Collection id as a RemoteStream id, when the record's type changed server-side mid-load. So the +whole `{collectionType, selectedId, selectedName}` unit resolves together: either half touched by +the user pins all of it; a differing type takes the response's unit whole (null selection included, +since an id from the old type's space cannot be carried across); and only once both sides agree on +the type does the id/name rule apply. + +Hydration also **loses every race against the user**: a `touchedRef` records which fields have been +edited, through a single `edit()` funnel so "touched" cannot drift from "changed". + +**Refresh and replace are different policies and must be different functions.** The same review +found a *cross-user lost update*, the worst defect in the series: the conflict "Reload" — which +exists to discard local edits — ran through the refresh path with a touched-set reset. Because the +reloaded record reports `selectedId: null` under the #671 gap, the keep-ours fallback restored the +user's **dirty** selection, the fresh ETag was installed, and the next Save silently overwrote the +collaborator's change with edits the user had explicitly asked to throw away. `replaceDraft` was made a separate function with the mode carried on the load — machinery that +round 5 then deleted outright along with the rest of the reconciliation layer. Every interleaving is tested by holding the detail response open, acting as the user, then +releasing it. + +Symmetrically, a name resolved asynchronously is **keyed to the id it was resolved for** and refuses +to overwrite a label that already names a different id — otherwise a slow edit-load read landing +after the user picked something else labels the new selection with the old item's title while the +saved id says otherwise. Keying the render alone stops the mislabelling but still throws away the +newer, correct label, so both halves are needed. + +**Scope: Lucene-backed types only.** `GetLibraryBrowseItemsHandler` applies `query` two different +ways — as a Lucene clause for media items, and as a plain SQL `LIKE` on `Name` for the +collection-family types (Collection / SmartCollection / MultiCollection / RerunCollection / +Playlist). A compiled `title:*x*` sent at the latter would be LIKE-matched literally and match +nothing. So `FillerPresetsScreen` marks only its media-item types `searchable`; its +collection-family types keep the bounded single-page load and the truncation hint, and the Class A +`loadAllPages` paths in the other two screens are untouched. The `api.search-allitems-paging` +precedent holds: the client bounds itself, the server cap is not raised. + +**The generalisation that took four rounds: an id never travels without its namespace.** Rounds 2 +and 3 made *hydration* treat `{collectionType, selectedId, selectedName}` as one value. Round 4 found +the same defect in three more places, because the fix had been applied to the one structure that was +named rather than to every structure that carries an id. A typeahead cached its results against the +query TEXT, so switching the search source with the same text made the re-query guard *suppress* the +new request and leave the previous namespace's hit clickable under the new label. List-backed +`` is fully +keyboard-operable, so an input-plus-listbox that only responds to Tab and click is a regression +introduced by this change rather than a pre-existing gap. `SearchPicker` implements the ARIA +combobox pattern: `role="combobox"` with `aria-expanded`/`aria-controls`/`aria-autocomplete`, +Arrow/Home/End moving a virtual cursor exposed through `aria-activedescendant`, Enter committing, +Escape dismissing, and options as non-tab-stops. Two defects specific to an *asynchronous* combobox +also had to be closed: a stale result set was committable (highlight Alpha for "Al", retype "Be", +press Enter before the debounce — Enter selected Alpha), so the highlight now drops on input change +and the guard lives in the single `choose()` sink rather than on each call site (gating Enter while +leaving `onClick` open was the same defect in another modality, found a round later); and Escape +closed the popup while focus stayed in the input, where `onFocus` can never re-arm it, so the picker +was dead until the user blurred and refocused — typing and ArrowDown now both reopen it, without +re-querying results that are already current, since the duplicate response would reset the cursor +and leave Enter doing nothing. + +Folded in from #578 (same components): the rule-builder facet typeahead arms on **focus** rather +than on mount, so an N-row rule tree no longer fires N unrequested `search/fields/*/values` +requests; and both it and `SearchPicker` now pair their `seqRef` stale-response guard with a shared +`useIsMountedRef` (`web/src/hooks.ts`) so a fetch resolving after unmount is dropped. Proving that +guard needs two tests, because React 19 no longer warns on a setState-after-unmount and an unmounted +tree renders nothing either way: a unit test of the hook (including a StrictMode double-invoke for +the re-arm) plus an integration test that mocks the hook module and asserts `SearchPicker` actually +read `current` and saw `false`. #578's remaining item — extending the `artist` facet source beyond +entity artists — is a `GetSearchFieldValuesHandler` change, out of scope for a web-only fix, and is +being done on its own branch. + +*(Over the 60-line prose ceiling: checked for redundancy against +`spa.list-completeness-vs-bounded-pickers` in `archive/` and declined to cut. The length is six +distinct findings — the search bound, the compile rule, selection preservation, the +clear-what-you-cannot-name prohibition, the async-name keying, and the keyboard contract — most of +which came from review rounds, and each of which names a specific way the obvious implementation is +wrong. The recurring error across four review rounds was always the same: patching the named +instance instead of covering its class — which is why the record states the rules as classes. Summarising any of them back out would lose the counter-example that makes it actionable.)* diff --git a/docs/spa-conventions.md b/docs/spa-conventions.md index c7c4c016b..5f14ea0c3 100644 --- a/docs/spa-conventions.md +++ b/docs/spa-conventions.md @@ -121,7 +121,7 @@ Convention — when a screen keeps stale results visible during a refetch: current (compare against a ref that always holds the committed value — `SearchScreen` reuses `lastQueryRef`) and **discard** otherwise. Checking only `activeRef` (mounted) is insufficient. -## 3b. Paged list endpoints clamp server-side — page to completeness ONLY for bounded lists, never a media-library picker +## 3b. Paged list endpoints clamp server-side — page to completeness ONLY for bounded lists; a media-library picker searches instead Every paged `/api/v1` list endpoint (rerun-collections, multi-collections, library/browse, search, trakt-lists, …) clamps `pageSize` to its own controller's `MaxPageSize` (100, as of #644) regardless @@ -131,14 +131,14 @@ UI to notice the gap. This was issue #644 (following on from #634, which fixed t `SchedulesScreen`'s rerun-collections picker load). **Two classes of call site, treated differently** (decision record: -`docs/decisions/records/spa/list-completeness-vs-bounded-pickers.md`, `spa.list-completeness-vs-bounded-pickers` -— a #644 follow-up review found the original blanket "use `loadAllPages` for any picker" guidance -below was itself the defect for one class of caller): +`docs/decisions/records/spa/library-pickers-resolve-by-search.md`, +`spa.library-pickers-resolve-by-search`, superseding `spa.list-completeness-vs-bounded-pickers` — +the #644 follow-up got Class A right and Class B only half right): -- **Bounded-by-construction lists** (rerun collections, multi-collections, playlists — admin-created, - hundreds of rows at most): genuinely need the complete list, and completeness is cheap. Use the - shared `loadAllPages` helper (`web/src/api/paging.ts`, re-exported via `web/src/api/index.ts`) - instead of an inflated `pageSize`: +- **Class A — bounded-by-construction lists** (collections, multi-collections, smart collections, + playlists — admin-created, hundreds of rows at most): genuinely need the complete list, and + completeness is cheap. Use the shared `loadAllPages` helper (`web/src/api/paging.ts`, re-exported + via `web/src/api/index.ts`) instead of an inflated `pageSize`: ```ts const { items, complete } = await loadAllPages(getMultiCollections); // pages against totalCount, cap defaults to 100 @@ -150,41 +150,206 @@ below was itself the defect for one class of caller): a caller that needs the full list must not treat a resolved promise as proof the list is whole (a partial result is otherwise silently indistinguishable from a complete one — the same defect class as #644 itself, since `GetLibraryBrowseItemsHandler.HydrateMediaItems` can legitimately drop stale - Lucene hits and produce a short/empty page in normal operation). Pass an `AbortSignal` (4th arg) - from the caller's effect cleanup so a superseded load stops issuing further page requests instead - of hammering the server for a result nobody will see. **Do not raise the server-side cap to work - around this** — the `api.search-allitems-paging` precedent is that the client pages and the server - stays bounded; that's a backend decision, out of scope for a screen fix. + Lucene hits and produce a short/empty page in normal operation). Render `complete: false` as its own + copy ("List may be incomplete — retry to reload"), never through search-narrowing text — a + `loadPickerOptions` result that can come from either class carries a `hint: 'incomplete' | 'none'` + discriminator, not a boolean shared with an unrelated condition (#644 follow-up round-3 review F1). + Pass an `AbortSignal` (4th arg) from the caller's effect cleanup so a superseded load stops issuing + further page requests, and gate any `console.warn` on `!signal?.aborted` — a superseded or + user-aborted load returns `complete: false` too, and that's expected, not a defect. **Do not raise + the server-side cap to work around any of this** — the `api.search-allitems-paging` precedent is + that the client bounds itself and the server stays bounded. -- **Media-library pickers** (`getLibraryBrowseItems` backing a `` - with thousands of `