fix(player): make the video seek bar work by touch (DR-099)

On Android, dragging or tapping the progress bar moved the thumb but playback stayed where it was. Two separate defects, both touch-only, which is why the mouse-driven scrub tests never caught either. 1. Gesture hijack. DR-098 taught handleTouchStart to ignore touches that land on a control, but handleTouchMove kept running. It measures against touchStartX/Y, which that early return leaves at the PREVIOUS gesture's values, so a seek-bar drag produced a huge bogus vertical delta: read as a brightness swipe, it dimmed the screen to the 0.3 floor and fired a spurious play/pause "correction" mid-drag. A gesture is now latched at touchstart (playerGestureActive) and touchmove ignores anything unlatched — re-checking the move target cannot recover a start point that was never recorded. 2. Commit signal. The seek was committed only from `change`, which Android's WebView does not reliably fire for a touch interaction on a range input, so the thumb moved to the tapped position and no seek ever ran. touchend/mouseup now commit too; `input` arms a one-shot latch so whichever release signal arrives first commits and the other is a no-op. seekRelative shares the same commitSeek entry point instead of fabricating a synthetic change event. Tests drive the slider with real touch events (UT-089, UT-090) and fail against the pre-fix component.
docs(requirements): UR-061/DR-092 no longer describe the removed deferral
2026-08-01 10:41:23 +02:00 · 2026-07-30 16:13:29 +02:00 · 2026-07-30 15:44:38 +02:00 · 2026-07-30 15:27:01 +02:00 · 2026-07-30 15:10:59 +02:00 · 2026-07-30 14:53:20 +02:00
45 changed files with 4228 additions and 880 deletions
@@ -42,30 +42,45 @@ jobs:
          echo "📊 Validating requirement traceability..."
          echo ""

-          # Parse JSON
+          # Denominators come from docs/requirements.md at run time — NEVER
+          # hardcode them here. This step previously divided by frozen literals
+          # (UR/39, IR/24, DR/48, JA/3, total 114) while the file had grown to
+          # 211 requirements, so it reported 158% coverage and the threshold
+          # below could never trip. See docs/specs/traceability-gate-repair.md.
          TOTAL_TRACES=$(jq '.totalTraces' traces-report.json)
-          UR=$(jq '.byType.UR | length' traces-report.json)
-          IR=$(jq '.byType.IR | length' traces-report.json)
-          DR=$(jq '.byType.DR | length' traces-report.json)
-          JA=$(jq '.byType.JA | length' traces-report.json)
+          COVERED=$(jq '.coverage.covered' traces-report.json)
+          TOTAL_REQS=$(jq '.coverage.total' traces-report.json)
+          COVERAGE=$(jq '.coverage.percent' traces-report.json)

-          # Print coverage report
          echo "✅ TRACES Found: $TOTAL_TRACES"
          echo ""
-          echo "📋 Coverage Summary:"
-          echo "   User Requirements (UR):         $UR / 39 ($(( UR * 100 / 39 ))%)"
-          echo "   Integration Requirements (IR): $IR / 24 ($(( IR * 100 / 24 ))%)"
-          echo "   Development Requirements (DR): $DR / 48 ($(( DR * 100 / 48 ))%)"
-          echo "   Jellyfin API Requirements (JA): $JA / 3 ($(( JA * 100 / 3 ))%)"
+          echo "📋 Coverage Summary (traced / defined):"
+          for T in UR IR DR JA; do
+            TRACED=$(jq --arg t "$T" '[.byType[$t][] | select(. != null)] | length' traces-report.json)
+            DEFINED=$(jq --arg t "$T" '.defined[$t]' traces-report.json)
+            echo "   $T: $TRACED / $DEFINED"
+          done
          echo ""

-          COVERED=$((UR + IR + DR + JA))
-          TOTAL_REQS=114
-          COVERAGE=$((COVERED * 100 / TOTAL_REQS))
-
          echo "📈 Overall Coverage: $COVERED / $TOTAL_REQS ($COVERAGE%)"
          echo ""

+          # Traced IDs that requirements.md does not define (typo, or a deleted
+          # requirement). These do not count toward coverage.
+          ORPHANED=$(jq -c '.coverage.orphaned' traces-report.json)
+          if [ "$ORPHANED" != "[]" ]; then
+            echo "⚠️  Traced but not defined in requirements.md: $ORPHANED"
+            echo ""
+          fi
+
+          # A ratio above 100% means the computation is broken — the exact
+          # condition that hid the stale-denominator bug. Fail loudly.
+          if [ "$COVERAGE" -gt 100 ]; then
+            echo "❌ ERROR: Coverage ($COVERAGE%) exceeds 100% — the gate is miscomputing."
+            echo "   Orphaned IDs: $ORPHANED"
+            exit 1
+          fi
+
          # Check minimum threshold
          MIN_THRESHOLD=50
          if [ "$COVERAGE" -lt "$MIN_THRESHOLD" ]; then
@@ -183,8 +183,14 @@ and [docs/build-release.md](docs/build-release.md).
  backend expand it. Single-type presentation (`itemType: "Movie"`, "this page
  shows albums") is fine; a *category → set of types* mapping in `src/` is a leak.
  `bun run check:boundary` is the tripwire; the real gate is the spec's layer
-  assignment. See [scoped-search-boundary.md](docs/specs/scoped-search-boundary.md)
-  for the incident this rule came from.
+  assignment. The canonical example lives in Rust:
+  `SearchScope::item_types()` in `repository/types.rs` expands an opaque scope the
+  frontend sends. See [scoped-search-boundary.md](docs/specs/scoped-search-boundary.md)
+  for the incident this rule came from — note the tripwire missed that leak for
+  months because the mapping was assigned to a named const rather than written
+  inline at the query, so **a green `check:boundary` is not proof**; it flags
+  item-type array literals only, not run-time-built sets or `switch`/`||`
+  taxonomy.

 ## Writing specs

@@ -117,9 +117,13 @@ RUN cd src-tauri && cargo fetch && cd .. && \

 # Desktop packaging stages build FROM the unified registry builder image (see the
 # BUILDER_IMAGE ARG at the top), which already carries every packaging tool
-# (rpm/file for Linux, mingw-w64 + nsis + the x86_64-pc-windows-gnu rust target
-# for Windows). ONE source of dependency truth, shared with CI — no per-stage
-# apt/rustup here.
+# (rpm/file for Linux, cargo-xwin + nsis + the x86_64-pc-windows-msvc rust
+# target for Windows). ONE source of dependency truth, shared with CI — no
+# per-stage apt/rustup here.
+#
+# NOTE: Windows uses the MSVC target via cargo-xwin, NOT mingw/GNU — the GNU
+# toolchain cannot bundle an NSIS installer from Linux. See
+# scripts/build-windows-cross.sh.

 # Linux desktop packaging environment (deb + rpm; Arch is Dockerfile.arch).
 # Thin layer over the builder — the actual build runs at container-run time on
@@ -71,7 +71,7 @@ For a narrative overview of the system design, see
 | UR-058 | On the home screen, a tap on a media card opens the item (movie/episode detail page, or the series Episode Focus View for episodes) rather than starting playback; a long-press starts "play now" after a confirm; an episode detail/focus page links back to its parent series and season (see [ux-flows.md §5B.5](ux-flows.md) and [§5B.1](ux-flows.md)) | Medium | Done |
 | UR-059 | Skipping to the next episode records the episode left behind as **fully watched** rather than saving a mid-episode resume point — skipping means "done with this one", not "stopped here" — and Continue Watching hides episodes the viewer has already moved past (a partial position behind that series' next-up episode), so the row only ever offers genuinely unfinished media | Medium | Done |
 | UR-060 | Search results are ordered by how well they match: a name that *starts* with the query outranks one matching mid-word (typing "parks" finds "Parks and Recreation" before "Sparks of Love"), and at equal match quality a container outranks its contents (a series before its episodes). Results are grouped into distinct categories — TV Shows, Episodes, Movies, Songs, Albums, Artists and People — so a show never competes with its own episodes for the same slot, and searching an actor's name reaches their bio | High | Done |
-| UR-061 | Double tapping the video skips within it — right half jumps **forward 30 seconds**, left half jumps **back 10 seconds** — with an on-screen indicator naming the amount. Because a double tap starts as a single tap, the single-tap play/pause is held back until the double-tap window has passed, so skipping never also pauses the video; the skip lands relative to the position the player actually reports, and repeated double taps accumulate rather than all skipping from the same spot | Medium | Done |
+| UR-061 | Double tapping the video skips within it — right half jumps **forward 30 seconds**, left half jumps **back 10 seconds** — with an on-screen indicator naming the amount. A double tap leaves the play state unchanged — playing jumps and keeps playing, paused jumps and stays paused — because the second tap re-toggles what the first tap toggled (see DR-098); the skip lands relative to the position the player actually reports, and repeated double taps accumulate rather than all skipping from the same spot | Medium | Done |

 ---

@@ -220,7 +220,7 @@ Internal architecture, components, and application logic.
 | DR-060 | Multi-server store and active-account selection: save/get/delete server, save/get user, set/get active user (per-server), active-session resolution | Storage | UR-047 | Partial (store done; server-switcher UI pending) |
 | DR-061 | Episode Focus View: episode hero followed *immediately* by the "More Episodes" strip — a forward-biased window (~3 before / ~6 after) around the current episode, spanning season boundaries in series order, with the current episode present and badged, per-card resume progress and watched state, and click-to-swap focus (no playback) | UI | UR-048 | Done |
 | DR-062 | Detail-page section ordering: continuation content precedes discovery content — Episode Focus View renders hero → episode strip → cast → similar; Series renders hero → seasons/episodes → cast → similar | UI | UR-048 | Done |
-| DR-063 | Search scope resolver mapping the originating route to an `includeItemTypes` set (All / Music / Movies / TV), defaulting to All for Home, `/library`, and the search tab | UI | UR-049 | Implemented |
+| DR-063 | Search scope taxonomy owned by Rust: `SearchScope` (All / Music / Movies / TV) crosses IPC as an opaque enum and `SearchScope::item_types()` expands it to Jellyfin item types, resolved once in `repository_search` before the cache and server paths diverge so online and offline filter identically; `All` expands to *no* filter rather than the union of the other scopes (which would drop People and folders). The frontend maps the originating route to a scope (`resolveSearchScope`, presentation) and never names an item type for search | Backend | UR-049 | Implemented |
 | DR-064 | Scope chip row rendered under the search bar on both the search page and the in-library header search: preselected from context, horizontally scrollable, re-runs the search preserving the query on change | UI | UR-049 | Implemented |
 | DR-065 | Thread `SearchOptions.includeItemTypes` through `library.search()` so the global/header search honours scope (backend online + offline paths already support it) | UI | UR-049 | Implemented |
 | DR-066 | Persisted search result group order with a drag-and-drop settings list, keyboard-accessible reordering, a shipped default (see DR-091 for the current group set and order), and empty-group omission | Settings | UR-050 | Implemented |
@@ -246,7 +246,14 @@ Internal architecture, components, and application logic.
 | DR-089 | Continue Watching suppresses resume entries superseded by Next Up: an in-progress episode whose series has a next-up entry strictly later in series order (season, then episode) is dropped from the Home and TV rows; movies, series without a next-up entry, and items with unknown/mixed episode ordering are always kept | UI | UR-059 | Done |
 | DR-090 | Relevance ranking in Rust (`domain/search_rank.rs`): results sort by match position (prefix → word-start → mid-word substring → no name match) then by media kind (containers before their contents), stably so the backend's own relevance breaks ties. Applied in `repository_search` to both the instant cache result and the merged cache+server union, so the list does not reshuffle when server results land | Backend | UR-060 | Done |
 | DR-091 | Search result groups split TV into separate Shows and Episodes groups and add a People group (default order: Shows → Episodes → Movies → Songs → Albums → Artists → People); a stored `tvShows` order from before the split expands in place to shows+episodes so an upgrading user keeps their arrangement | UI | UR-060 | Done |
-| DR-092 | Video tap gestures resolve in `tapGestures.ts` (pure, unit-tested) rather than inline in `VideoPlayer.svelte`: `registerTap` returns `pending` for a first tap — the component defers `togglePlayPause` behind a `DOUBLE_TAP_WINDOW_MS` (300 ms) timer that a second tap cancels — or `seek` (+30 s right / −10 s left) for a second tap inside the window; a consumed second tap resets the state so a third tap starts fresh, and a swipe cancels the pending tap. The compatibility `click` the browser synthesizes after a touch tap is filtered in `handleVideoClick` so it cannot bypass the deferral. `resolveSeekTarget` converts the delta to the absolute position the facade requires, clamped to `[0, duration]` and chained off a still-in-flight `pendingSeekTarget` so back-to-back skips accumulate instead of all resolving against a not-yet-updated position | UI | UR-061 | Done |
+| DR-092 | Video tap gestures resolve in `tapGestures.ts` (pure, unit-tested) rather than inline in `VideoPlayer.svelte`: `registerTap` classifies each tap and the component acts on it immediately — `togglePlayPause` for a first tap, or `seek` (+30 s right / −10 s left) plus a re-toggle for a second tap inside `DOUBLE_TAP_WINDOW_MS` (300 ms). A consumed pair resets the state, and a swipe forgets the tap. The deferral this originally used was removed in DR-098, which also covers suppressing the compatibility `click` the browser synthesizes after a touch tap. `resolveSeekTarget` converts the delta to the absolute position the facade requires, clamped per DR-095 and chained off a still-in-flight `pendingSeekTarget` so back-to-back skips accumulate instead of all resolving against a not-yet-updated position | UI | UR-061 | Done |
+| DR-094 | Frontend boundary tripwire (`scripts/check-frontend-boundary.sh`) detects Jellyfin item-type array literals **anywhere** in `src/` rather than only inline at an `includeItemTypes:` query site, so a category→type mapping cannot evade the check by being assigned to a named const (the evasion that let the `scoped-search` leak pass CI); requires two adjacent type literals so single-type presentation and `item.type ===` inspection stay legal, and caps the allowlist to force taxonomy into Rust instead of accumulating exceptions | Tooling | - | Done |
+| DR-098 | Video tap gestures act **immediately** — no deferral, no timer, and only first/second taps exist. A first tap toggles play/pause; a second tap inside `DOUBLE_TAP_WINDOW_MS` seeks *and* toggles again, so the two toggles cancel and a double tap preserves the play state (playing → jump and keep playing; paused → jump and stay paused). This replaces a design that deferred the first tap behind a 300 ms timer so a second tap could cancel it: the timer cleared its own handle *before* invoking the toggle, which reopened the `tapTimeout !== null` guard in `handleVideoClick` meant to suppress the compatibility `click` Android's WebView synthesizes after a touch — the late click then toggled a second time, producing a pause/unpause loop (long-press was unaffected, which is what identified the tap path). Click suppression no longer depends on the timer: `handleVideoClick` ignores `detail === 0` *and* any click within `TOUCH_CLICK_SUPPRESS_MS` of a touch tap. A swipe undoes the touchstart toggle exactly once (latched on `swipeGestureActive`) so brightness swipes never change play state. Click suppression is shared by **every** click target layered over the video via `isSynthesizedTouchClick`, not just the `<video>`: pausing renders a full-screen play-overlay button, so the synthesized click lands on *that* and an unguarded handler there resumed immediately — pausing appeared impossible while unpausing worked, because unpausing removes the overlay | UI | UR-061 | Done |
+| DR-099 | The video seek bar is usable by touch. Two Android-only defects made dragging or tapping it move the thumb without moving playback. (a) *Gesture hijack*: the container-level gesture layer skips `touchstart` on a control (DR-098) but kept handling `touchmove`, so a seek-bar drag was measured against the **previous** gesture's start point — a huge bogus vertical delta that read as a brightness swipe, dimmed the screen to the 0.3 floor, and fired a spurious play/pause "correction" mid-drag. A gesture is now latched at `touchstart` (`playerGestureActive`) and `touchmove` ignores anything not latched, since re-checking the move target cannot recover a start point that was never recorded. (b) *Commit signal*: the seek was committed **only** from `change`, which Android's WebView does not reliably fire for a touch interaction on a range input — the thumb moved to the tapped position and no seek ever ran. `touchend`/`mouseup` now commit as well; `input` arms a one-shot latch so whichever release signal arrives first commits and the other is a no-op. `seekRelative` shares the same `commitSeek` entry point instead of fabricating a synthetic `change` event | UI | UR-005, UR-061 | Done |
+| DR-097 | Transport authority (play/pause/toggle) lives in Rust for **webview-rendered** media, not just native. The controller tracks the state the HTML5 element reports (`html5_playing`, fed by `report_html5_state`, which now *stores* rather than only re-emitting); `play`/`pause`/`toggle_playback` consult it and drive the element by emitting a `ControlCommand` that `playerEvents.handleControlCommand` executes against the active adapter. A `stopped`/`idle` report clears it so the native backend (MPV/ExoPlayer) regains authority for music. The frontend facade no longer short-circuits transport into the adapter: `adapter.toggle()` previously decided play-vs-pause by reading `el.paused` off the DOM, a value that flips transiently while an element buffers or settles a seek — so two intents ~150 ms apart read *different* values, performed *opposing* actions, and self-sustained a play/pause loop needing no further input (observed on Android with a fully-buffered `readyState=4 networkState=1` element). Same "backend decides, adapter executes the primitive" split as `player_seek_video` | Player | UR-005 | Done |
+| DR-096 | `Html5PlayerAdapter.play()` is resilient to stall recovery: an in-flight attempt is memoised so concurrent callers (UI plus hls.js gap-controller recovery) share one `element.play()` instead of stacking calls, and an `AbortError` ("play() request was interrupted by a call to pause()") is logged at debug rather than pushed to `host.onError`. The browser raises it whenever a pending play promise is superseded by a pause/seek/source change, which hls.js does routinely while nudging past a stall — reporting it surfaced a player error roughly once per second for the whole stall and left the UI stuck showing paused | Player | UR-005 | Done |
+| DR-095 | Seek targets clamp strictly *inside* the media (`clampSeekTarget`, `END_SEEK_MARGIN_SECONDS` = 6 s ≈ one HLS segment) instead of to the exact `duration`. Landing on the duration makes hls.js request the segment whose start time lies past the end of the media (e.g. a 6330.324 s item → segment 1055 starting at 6336.33 s), which Jellyfin never produces; the fetch times out and hls.js' gap-controller stalls at the last buffered position, presenting as "unpausing or skipping bounces straight back to paused". Applied on both seek paths — the relative-skip `resolveSeekTarget` and the seek-bar drag, whose range input `max` is the duration itself — and floored at 0 so media shorter than the margin still seeks to the start | UI | UR-061 | Done |
+| DR-093 | Traceability coverage gate derives its requirement denominators from `requirements.md` at run time rather than hardcoded literals: `countDefinedRequirements` counts an ID only where it leads a markdown table row (ignoring the "Traces To" column and prose) and deduplicates IDs listed both in the definition tables and in the §3 traceability matrix; `computeCoverage` reports the *intersection* of traced and defined IDs so an ID traced in code but absent from `requirements.md` is surfaced as `orphaned` instead of inflating the ratio past 100%. UT/IT test identifiers are excluded as a separate taxonomy. CI and `bun run traces:coverage` share this computation and fail on both a sub-threshold and an impossible >100% result | Tooling | - | Done |

 ---

@@ -406,10 +413,13 @@ Internal architecture, components, and application logic.
 | UT-082 | EQ fields serialize as camelCase (`equalizerEnabled`/`equalizerBands`) and round-trip | DR-030 | Done |
 | UT-083 | EQ filter entries are empty when disabled or when the curve is flat (clears the `af` filter) | IR-020 | Done |
 | UT-084 | Enabled EQ builds one peaking `equalizer` per non-zero band at the right frequency and gain inside a single `lavfi` chain | IR-020 | Done |
-| UT-085 | A first tap resolves to `pending`, not an immediate play/pause, and becomes `togglePlayPause` only once the double-tap window has elapsed | DR-092 | Done |
-| UT-086 | A second tap inside the window seeks (+30 s right half, −10 s left half) with the matching feedback side, and clears the deferred play/pause so a double tap never pauses | DR-092 | Done |
-| UT-087 | A tap after the window, and a third tap after a consumed double tap, each start a fresh pending tap; repeated double taps keep seeking; `cancel()` drops a pending tap so a swipe cannot pause | DR-092 | Done |
-| UT-088 | `resolveSeekTarget` applies the delta to the reported position, clamps to `[0, duration]`, chains off an in-flight pending target so rapid skips accumulate, and ignores that target once the player reports past it | DR-092 | Done |
+| UT-085 | A first tap resolves to `togglePlayPause` immediately — no deferral and no timer | DR-092, DR-098 | Done |
+| UT-086 | A second tap inside the window seeks (+30 s right half, −10 s left half) with the matching feedback side **and** re-toggles play/pause, so the two toggles cancel and the play state is unchanged by a double tap | DR-092, DR-098 | Done |
+| UT-087 | A tap after the window, and the tap following a consumed pair, are each fresh first taps that toggle (there is no third-tap case); repeated double taps keep seeking; `cancel()` makes the next tap a first tap so an interpreted swipe cannot seek | DR-092, DR-098 | Done |
+| UT-088 | `resolveSeekTarget` applies the delta to the reported position, clamps into `[0, duration - END_SEEK_MARGIN_SECONDS]`, chains off an in-flight pending target so rapid skips accumulate, and ignores that target once the player reports past it | DR-092, DR-095 | Done |
+| UT-089 | A touch drag on the video seek bar seeks to the dragged position, never toggles play/pause, and never alters brightness — the container gesture layer stays out of a control drag entirely | DR-098, DR-099 | Done |
+| UT-090 | The seek bar commits its seek on `touchend` even when the engine never fires `change`, and commits exactly once when both signals arrive | DR-099 | Done |
+| UT-091 | Transport intents (play/pause/toggle) reach the backend even while a video adapter is registered, and never call the adapter's own `play`/`pause`/`toggle` — the webview must not decide play-vs-pause from the DOM | DR-097 | Done |

 ### Integration Tests

@@ -0,0 +1,215 @@
+# Spec: Harden the frontend boundary tripwire
+
+**Status:** Implemented
+**Requirements:** DR-094
+**UX spec:** n/a — developer tooling.
+**Supersedes / revises:** revises the detection rule in
+[scripts/check-frontend-boundary.sh](../../scripts/check-frontend-boundary.sh);
+the boundary *policy* in [scoped-search-boundary.md](scoped-search-boundary.md)
+is unchanged.
+
+## Summary
+
+`bun run check:boundary` passes on a tree that contains the exact leak it was
+built to catch. It matches a multi-type array only when written **inline at the
+query site**, so assigning the same array to a named const evades it entirely —
+which is how [searchScope.ts](../../src/lib/utils/searchScope.ts) has kept a
+category→item-type mapping through every green CI run. This spec broadens the
+match to item-type array literals anywhere in `src/`, and resolves the handful
+of legitimate hits that broadening surfaces.
+
+## Motivation
+
+The current pattern is anchored to the `includeItemTypes:` key:
+
+```sh
+PATTERN='includeItemTypes:[[:space:]]*\[[^]]*,[^]]*\]'
+```
+
+The live leak is not written that way:
+
+```ts
+// src/lib/utils/searchScope.ts:29 — invisible to the tripwire
+const SCOPE_ITEM_TYPES = { music: ["MusicAlbum", "MusicArtist", "Audio", "Playlist"], … };
+```
+
+The taxonomy and the query are one indirection apart, and the grep only sees the
+query. The script's own header is admirably honest that it is "a TRIPWIRE, NOT A
+PROOF" — but the gap here is not a subtle judgment call it was designed to
+defer to human review. It is the *crudest form* of the violation, one `const`
+away from the shape it does match, in the very file the founding incident was
+written about.
+
+Broadening the pattern to any item-type array literal finds it, with a
+manageable number of other hits (measured, not estimated):
+
+| Site | Verdict |
+|------|---------|
+| `searchScope.ts:30,32` | 🔴 The leak. Removed by [scoped-search-boundary-implementation.md](scoped-search-boundary-implementation.md). |
+| `PersonDetailView.svelte:30` | Already allowlisted, with a recorded reason. |
+| `DownloadedBrowse.svelte:95` | Borderline — `["MusicAlbum","Series","Season","BoxSet"].includes(item.type)` as an "is this a container?" predicate. |
+| `GenericMediaListPage.svelte:298` | Borderline — `["MusicAlbum","MusicArtist","Audio","Playlist"].includes(config.itemType)` as a music-styling predicate. |
+| 6 hits in `*.test.ts` | Excluded; tests legitimately name types. |
+
+Four non-test sites total. This is a tractable change, not a boil-the-ocean one.
+
+## Layer assignment
+
+Tooling only — no application logic, nothing crosses IPC. The two borderline
+*application* sites do get a layer decision, below.
+
+| Logic / responsibility | Layer | Why it belongs there |
+|------------------------|-------|----------------------|
+| Detecting item-type array literals in `src/` | Build tooling (`scripts/`) | Static analysis of repo source; belongs beside the existing check. |
+| "Is this item a container?" (`DownloadedBrowse`) | **Rust** (recommended) | Containers-vs-leaves is Jellyfin structure, and the set grows when Jellyfin adds a container type — the litmus test's "yes". Prefer a `MediaItem.isContainer` boolean from the backend over a type-set predicate in a component. |
+| "Is this music content?" (`GenericMediaListPage`) | **Frontend, allowlisted** | Selects a grid *style*. It reads `config.itemType`, a value the page already declares about itself, and changes only if the UI is redesigned — the litmus test's "no". Single-type presentation is explicitly not the target of the rule. |
+
+`DownloadedBrowse` defaults to Rust per the checklist's borderline rule; see
+Out of scope for why the migration itself is deferred rather than bundled.
+
+## Design
+
+### 1. Broaden the pattern
+
+Replace the key-anchored pattern with one matching an array literal of two or
+more known Jellyfin item types, wherever it appears:
+
+```sh
+# Two or more adjacent item-type string literals inside a bracket.
+TYPES='Movie|Series|Episode|Audio|MusicAlbum|MusicArtist|MusicVideo|Season|BoxSet|Playlist|Book|AudioBook|Video|Person|Folder|CollectionFolder|TvChannel|LiveTvChannel'
+PATTERN="\[[[:space:]]*\"($TYPES)\"[[:space:]]*,[[:space:]]*\"($TYPES)\""
+```
+
+Properties worth stating, because each is a deliberate trade:
+
+- **Not anchored to any key**, so a named const, a function return, a `Record`
+  value, or an inline query all match equally.
+- **Requires two adjacent type literals**, preserving the existing and correct
+  carve-out that single-type presentation (`itemType: "Movie"`) is legitimate.
+- **Requires string literals**, so `item.type === "Audio"` (display inspection)
+  still does not match.
+- **Explicit type list**, not `[A-Z][a-z]+`, so arbitrary string arrays
+  (`["High","Low"]`, `["Songs","Albums"]`) do not produce noise.
+
+Keep `grep -rInE`, the `*.test.*` exclusion, and the allowlist mechanism as they
+are — all three work.
+
+### 2. Resolve the surfaced sites
+
+- `PersonDetailView.svelte` — already allowlisted; entry unchanged.
+- `GenericMediaListPage.svelte` — **add to the allowlist** with the reason from
+  the layer table (grid styling over a self-declared `itemType`).
+- `DownloadedBrowse.svelte` — **add to the allowlist with a `TODO` naming the
+  preferred fix** (backend `isContainer`). An allowlist entry that records a
+  known-borderline decision is honest; silently broadening the pattern to miss
+  it would not be.
+- `searchScope.ts` — **not allowlisted.** It is the leak, and
+  [scoped-search-boundary-implementation.md](scoped-search-boundary-implementation.md)
+  deletes it.
+
+### 3. 🔴 Sequencing
+
+**This spec must land after Stage 1 of
+[scoped-search-boundary-implementation.md](scoped-search-boundary-implementation.md).**
+Hardening the tripwire first turns `master` red on a violation with no fix
+available, and the only ways out are reverting the hardening or allowlisting the
+leak — the second of which is exactly how a boundary rule dies.
+
+### 4. Keep the allowlist honest
+
+The script already warns that a growing allowlist means the boundary is eroding.
+This change takes it from 1 entry to 3, which is close to that line. Add a hard
+cap so drift is caught mechanically rather than by whoever notices:
+
+```sh
+MAX_ALLOWLIST=4
+if [ "${#ALLOWLIST[@]}" -gt "$MAX_ALLOWLIST" ]; then
+  echo "❌ Allowlist has ${#ALLOWLIST[@]} entries (max $MAX_ALLOWLIST)."
+  echo "   Push taxonomy into Rust instead of appending here."
+  exit 1
+fi
+```
+
+The cap is deliberately just above the current count: the next exception forces
+a conversation instead of a one-line append.
+
+### 5. Restate the limits
+
+The header's "tripwire, not a proof" caveat stays and gets sharper. The broadened
+pattern still cannot see:
+
+- a type set built at run time (`[...musicTypes, "Playlist"]`),
+- types split across variables (`const A = "Audio"; [A, B]`),
+- taxonomy expressed as a `switch` or chained `||` rather than an array.
+
+The spec-review checklist remains the real gate. This raises the floor; it does
+not close the class.
+
+## Out of scope
+
+- **Migrating `DownloadedBrowse` to a backend `isContainer` flag.** It touches
+  `MediaItem`, `bindings.ts`, and the offline path — its own spec. Allowlisted
+  with a TODO here so it is recorded, not forgotten.
+- The scoped-search fix itself — [scoped-search-boundary-implementation.md](scoped-search-boundary-implementation.md).
+- Detecting the run-time-construction cases listed above.
+- Extending the check to Rust or Kotlin (the rule is about `src/`).
+- Changing the boundary *policy* in CLAUDE.md.
+
+## Acceptance criteria
+
+- [ ] With `searchScope.ts` reverted to its leaking form, `bun run check:boundary`
+      **fails** and names `src/lib/utils/searchScope.ts`. This is the criterion
+      that proves the fix — verify it explicitly before landing.
+- [ ] On the post-fix tree, `bun run check:boundary` passes.
+- [ ] A newly introduced `const X = ["Movie", "Series"]` in any non-test `src/`
+      file fails the check (regression test for the const-indirection evasion).
+- [ ] `itemType: "Movie"` and `item.type === "Audio"` do **not** trip the check.
+- [ ] `["High", "Low"]` and other non-item-type arrays do **not** trip it.
+- [ ] Test files are still excluded (the 6 known test hits stay silent).
+- [ ] The allowlist has exactly 3 entries, each with a written reason; a 5th
+      entry fails the check via `MAX_ALLOWLIST`.
+- [ ] The script header still states it is a tripwire, not a proof, and names the
+      evasions it cannot see.
+- [ ] `bun run check` and `bun run test` pass.
+- [ ] `bun run test:all` passes.
+
+## Testing
+
+The script is bash and has no test harness. Verify by construction — each is a
+temporary edit, run, revert:
+
+1. Reintroduce the `SCOPE_ITEM_TYPES` const → **must fail**.
+2. Add `const T = ["Movie","Series"]` to a scratch `.svelte` file → **must fail**.
+3. Add the same to a `.test.ts` file → **must pass** (exclusion holds).
+4. Add `itemType: "Movie"` → **must pass**.
+5. Add a 5th allowlist entry → **must fail** on the cap.
+
+Record the five results in the PR description. A grep-based gate that has never
+been observed failing is indistinguishable from one that cannot fail — which is
+the precise condition this whole spec exists to correct.
+
+## TRACES
+
+Allocate in `requirements.md`:
+
+- **DR-094** — "Frontend boundary tripwire detects Jellyfin item-type array
+  literals anywhere in `src/` (not only inline at an `includeItemTypes:` query
+  site), so a category→type mapping cannot evade the check via a named const;
+  allowlist is capped to force taxonomy into Rust rather than accumulating
+  exceptions." Category: Tooling. Status: Done on merge.
+
+Shell scripts carry no `TRACES:` comment convention in this repo; reference
+DR-094 in the script header comment instead.
+
+## Notes for the implementer
+
+- A parallel Claude session may be active in this repo — `git diff` before
+  "repairing" unexpected changes (CLAUDE.md §Gotchas).
+- **Land after Stage 1 of the scoped-search fix** — see §3. This is the one
+  ordering constraint that will break `master` if ignored.
+- Test the regex against the current tree *before* committing:
+  `grep -rInE "$PATTERN" src/ | grep -v '\.test\.'` should return exactly the
+  four sites in the Motivation table.
+- The `TYPES` list will need occasional extension as Jellyfin adds types.
+  That is acceptable for a tripwire — an unlisted type produces a false
+  negative, never a false positive, so the check degrades safely.
@@ -0,0 +1,250 @@
+# Spec: Build provenance (git describe + build profile)
+
+**Status:** Proposed
+**Requirements:** new DR-093 (build provenance surfaced in-app and in logs); no UR — this is a diagnostic capability, not a user feature
+**UX spec:** n/a — adds an About block to Settings; no new flow
+**Supersedes / revises:** —
+
+## Summary
+
+Make every build say exactly what it is. Today a running JellyTau reports no
+version at all — not in the UI, not in the logs — and the only version string in
+the tree is the hand-maintained `0.2.0` duplicated across three files.
+
+This adds a `build.rs`-generated provenance string (`git describe` + short SHA +
+dirty flag + debug/release profile), exposes it over IPC, and renders it in a new
+Settings › About block. It also removes one of the three hand-bumped version
+files.
+
+## Motivation
+
+The concrete problem: when a user reports "the equalizer does nothing on my
+device" — which is a live risk for v0.2.0, whose Android audio settings are not
+yet device-verified — there is currently no way to tell which build they are
+running. Tag? Master? A local debug build from three weeks ago? The bug report
+cannot distinguish them.
+
+Two smaller irritations this also fixes:
+
+- **Debug builds masquerade as releases.** `0.2.0` is `0.2.0` whether it came
+  from a tagged release or `bun run tauri dev`.
+- **Three files carry the version.** `package.json`, `src-tauri/Cargo.toml` and
+  `src-tauri/tauri.conf.json` must be bumped in lockstep; the release checklist
+  exists partly to stop them drifting.
+
+### What this deliberately does *not* do
+
+**The canonical version stays hand-bumped in `Cargo.toml`.** Cargo requires a
+literal semver string at manifest-parse time and cannot derive it from git. The
+same is true of `tauri.conf.json`. Attempting to source the *release* version
+from a tag trades a scripted, reviewable bump for a fragile build-time
+dependency that breaks in exactly the environment we care most about (CI, in
+Docker, from a shallow clone).
+
+So: **the release version is authored; the build provenance is derived.** They
+answer different questions — "what release is this?" versus "what commit is this
+binary actually built from?" — and only the second benefits from git.
+
+## Layer assignment
+
+| Logic / responsibility | Layer | Why it belongs there |
+|------------------------|-------|----------------------|
+| Capturing git describe / SHA / dirty state at compile time | Rust (`build.rs`) | Only the Rust build has a compile step that can shell out to git and bake the result into the binary. A frontend equivalent would report the *dev server's* state, not the shipped binary's. |
+| Degrading to a sentinel when git is unavailable | Rust (`build.rs`) | Build-environment concern. Must never fail the build — CI runs in Docker from a shallow clone. |
+| Release version (`0.2.0`) | Rust (`Cargo.toml`, authored) | Domain fact about the product, not derivable from the environment. |
+| Deciding *what a build is* (release / dev / dirty) | Rust | Domain classification. The frontend must not infer "this is a dev build" from a string shape — it renders what it is told. |
+| Rendering the About block, copy-to-clipboard | Frontend | Pure presentation. |
+
+Borderline row: the release/dev/dirty classification could be done in the
+frontend by pattern-matching the describe string. It goes to Rust because that is
+a *rule about what constitutes a release build*, and it would have to change if
+the tagging scheme changed — the litmus test in the template puts that in Rust.
+Send a typed enum, not a string for the frontend to parse.
+
+## Design
+
+### `build.rs`
+
+```rust
+fn main() {
+    emit_build_provenance();
+    tauri_build::build()
+}
+
+fn emit_build_provenance() {
+    let describe = std::process::Command::new("git")
+        .args(["describe", "--tags", "--always", "--dirty"])
+        .output()
+        .ok()
+        .filter(|o| o.status.success())
+        .and_then(|o| String::from_utf8(o.stdout).ok())
+        .map(|s| s.trim().to_string())
+        .unwrap_or_else(|| "unknown".to_string());
+
+    println!("cargo:rustc-env=JELLYTAU_GIT_DESCRIBE={describe}");
+
+    // Rebuild when HEAD moves or a ref is written, so the string does not go
+    // stale across commits. Guarded: these paths do not exist in a git-less
+    // source tarball, and emitting rerun-if-changed for a missing path would
+    // force a rebuild every time.
+    for p in [".git/HEAD", ".git/refs"] {
+        if std::path::Path::new("../").join(p).exists() {
+            println!("cargo:rerun-if-changed=../{p}");
+        }
+    }
+}
+```
+
+🔴 **`build.rs` must never fail the build.** Every git call is
+`.ok()`-swallowed; a missing git binary, a shallow clone, or a source tarball all
+yield `"unknown"`. A build that breaks because git is absent would be a worse bug
+than the one this fixes.
+
+Note the `../` prefixes: `build.rs` runs with CWD at `src-tauri/`, so the repo's
+`.git` is one level up.
+
+### The provenance type
+
+```rust
+/// TRACES: DR-093
+#[derive(specta::Type, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct BuildInfo {
+    /// Authored release version (Cargo.toml).
+    pub version: String,
+    /// `git describe --tags --always --dirty`, or "unknown".
+    pub git_describe: String,
+    /// What kind of build this is — classified in Rust, not inferred by the UI.
+    pub kind: BuildKind,
+}
+
+/// TRACES: DR-093
+#[derive(specta::Type, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub enum BuildKind {
+    /// Built from a clean, exactly-tagged commit in release mode.
+    Release,
+    /// Release-mode build that is not on a clean tag (e.g. master, or dirty).
+    Untagged,
+    /// debug_assertions build.
+    Development,
+    /// Git state unavailable at build time.
+    Unknown,
+}
+```
+
+Classification:
+
+```rust
+let kind = if cfg!(debug_assertions) {
+    BuildKind::Development
+} else if describe == "unknown" {
+    BuildKind::Unknown
+} else if describe.contains('-') {   // "v0.2.0-3-gcb79a37" or "...-dirty"
+    BuildKind::Untagged
+} else {
+    BuildKind::Release
+};
+```
+
+### Command
+
+```rust
+/// TRACES: DR-093
+#[tauri::command]
+#[specta::specta]
+pub fn get_build_info() -> BuildInfo { … }
+```
+
+No parameters, so the camelCase param rule does not apply; the struct fields do
+need `#[serde(rename_all = "camelCase")]` (above). Regenerate `bindings.ts`.
+
+Also log the provenance once at startup, next to the existing init logging —
+that is what makes a user-submitted log file self-identifying, which is most of
+the value.
+
+### Settings › About
+
+A new block at the bottom of `src/routes/settings/+page.svelte`, rendering
+version, describe string, and a badge for non-release builds. One
+copy-to-clipboard button that yields a paste-ready block for bug reports:
+
+```
+JellyTau 0.2.0 (v0.2.0-3-gcb79a37-dirty, development)
+linux x86_64
+```
+
+Platform/arch come from the existing Tauri APIs; do not shell out.
+
+### Removing one version file
+
+`tauri.conf.json`'s `"version"` field can be omitted, in which case Tauri falls
+back to the Cargo version. That takes the bump from three files to two.
+
+**Verify before adopting**: confirm the Android `versionName`/`versionCode` and
+the NSIS installer version still resolve correctly with the field absent —
+Android packaging in particular reads the Tauri config. If either regresses,
+keep the field and drop this part; it is a convenience, not the point of the
+spec.
+
+## Out of scope
+
+- Deriving the *release* version from git tags (see Motivation).
+- A build-time timestamp. It defeats reproducible builds and adds little over
+  the commit SHA.
+- CI provenance/attestation, SBOM, signing.
+- Displaying the Jellyfin server version (separate concern, already available
+  from `/System/Info`).
+
+## Acceptance criteria
+
+- [ ] `cargo build` succeeds with git absent, from a shallow clone, and from a source tarball with no `.git` — yielding `"unknown"` in each case, never a build failure.
+- [ ] A tagged clean release build reports `BuildKind::Release`; `bun run tauri dev` reports `Development`; a dirty tree reports `Untagged` (release mode) with `-dirty` in the describe string.
+- [ ] The describe string changes after a new commit without a manual `cargo clean` (rerun-if-changed works).
+- [ ] Provenance is logged once at startup.
+- [ ] Settings › About renders version + describe + build-kind badge, with working copy-to-clipboard.
+- [ ] 🔴 CI checkouts that build a shippable artifact set `fetch-depth: 0`, or their artifacts are knowingly stamped `unknown`. Currently only `publish-docs.yml` sets it; `build-release.yml` has five checkouts and `build-and-test.yml` two, all of which would report `unknown` as-is.
+- [ ] **No toolchain installed in CI** — git is already present in the builder image; nothing new is added.
+- [ ] `bun run check`, `bun run test`, `bun run check:boundary` pass.
+- [ ] `cargo fmt` clean, `cargo clippy` clean, `bun run test:rust` passes.
+- [ ] `bindings.ts` regenerated.
+- [ ] DR-093 allocated in `requirements.md`; new code carries `// TRACES:`.
+
+## Testing
+
+**Rust**: the classification is pure and must be extracted from the command as
+`classify_build(describe: &str, debug: bool) -> BuildKind` so it can be tested
+directly. Cover: `"v0.2.0"` → `Release`; `"v0.2.0-3-gcb79a37"` → `Untagged`;
+`"v0.2.0-dirty"` → `Untagged`; `"unknown"` → `Unknown`; `debug = true` → always
+`Development` regardless of describe.
+
+`build.rs` itself is not unit-testable. Verify its failure path manually by
+building with `PATH` stripped of git, and from a `git archive` tarball — both
+must succeed with `"unknown"`.
+
+**Frontend**: assert the About block renders each `BuildKind` correctly, and that
+it renders the backend-supplied kind rather than re-deriving it from the string
+(a test that passes a `Release` kind with a `-dirty` describe and asserts the
+badge follows the *kind* would catch that regression).
+
+## TRACES
+
+- `build.rs` provenance emission → `// TRACES: | DR-093`
+- `BuildInfo` / `BuildKind` / `classify_build` → `// TRACES: | DR-093`
+- `get_build_info` command → `// TRACES: | DR-093`
+- Settings About block → `// TRACES: | DR-093`
+- `classify_build` tests → `UT-BUILD-1`
+- Allocate **DR-093** in `requirements.md` ("Build provenance: git describe and
+  build profile surfaced in-app and in logs"). Next free DR at time of writing
+  is DR-093.
+
+## Notes for the implementer
+
+- Do the `build.rs` + command + logging first; the About UI is the smaller half
+  and the logging alone delivers most of the diagnostic value.
+- The `fetch-depth: 0` change is the easiest part to forget and the one that
+  makes CI artifacts useless if missed — it is why that acceptance box is
+  flagged. Weigh it per workflow: test-only jobs do not need it.
+- Do not add a build timestamp "while you are in there" — see Out of scope.
+- A parallel Claude session may be active — `git diff` before "repairing"
+  unexpected changes.
@@ -0,0 +1,258 @@
+# Spec: Enforce the unified player boundary
+
+**Status:** Proposed
+**Requirements:** DR-095 (new); relates to UR-005 and the unified-player-boundary
+principle in CLAUDE.md and [02-svelte-frontend.md](../architecture/02-svelte-frontend.md)
+**UX spec:** n/a — refactor, no user-visible change.
+**Supersedes / revises:** n/a
+
+## Summary
+
+The stated principle is that UI controls playback **only** through
+`playerController` ([src/lib/player/index.ts](../../src/lib/player/index.ts)),
+never by calling `commands.player*` directly. There are **52 direct call sites
+outside** that facade. This spec routes the genuine playback-control calls
+through the facade, narrows the principle's wording so it stops forbidding
+things it never meant to forbid, and adds the lint rule that keeps it true —
+because this rule is the one design principle in the audit with **no automated
+check at all**, and it is also the one that drifted furthest.
+
+## Motivation
+
+Direct `commands.player*` usage outside `src/lib/player/`, by file:
+
+| File | Sites |
+|---|---|
+| [queue.ts](../../src/lib/stores/queue.ts) | 10 |
+| [player/[id]/+page.svelte](../../src/routes/player/[id]/+page.svelte) | 9 |
+| [VideoPlayer.svelte](../../src/lib/components/player/VideoPlayer.svelte) | 8 |
+| [settings/+page.svelte](../../src/routes/settings/+page.svelte) | 5 |
+| [sleepTimer.ts](../../src/lib/stores/sleepTimer.ts) / [auth.ts](../../src/lib/stores/auth.ts) / [autoplay.ts](../../src/lib/api/autoplay.ts) | 4 each |
+| [preload.ts](../../src/lib/services/preload.ts) | 3 |
+| [library/[id]](../../src/routes/library/[id]/+page.svelte), [playerEvents.ts](../../src/lib/services/playerEvents.ts), [playbackMode.ts](../../src/lib/stores/playbackMode.ts) | 1–2 each |
+
+These are **not** equivalent violations, and treating them as one number is why
+the rule has been easy to ignore. Three distinct groups:
+
+**(a) Genuine violations — playback control with a facade method that already
+exists.** `playerStop` ×6, `playerPlayTracks` ×4, `playerSeek` ×2,
+`playerPlayAlbumTrack` ×2, `playerNext`, `playerPrevious`, `playerSkipTo`,
+`playerToggleShuffle`, `playerCycleRepeat`, `playerRemoveFromQueue`,
+`playerMoveInQueue`, `playerAddTrackById`, `playerAddTracksByIds`,
+`playerSetSubtitleTrack`, `playerPlayItem`. The facade exposes `stop()`,
+`seek()`, `next()`, `previous()`, `skipTo()`, `toggleShuffle()`,
+`cycleRepeat()`, `removeFromQueue()`, `moveInQueue()`, `addTrackById()`,
+`addTracksByIds()`, `setSubtitleTrack()`, `playTracks()`, `playAlbumTrack()`,
+`playItem()` — every one of these has a facade equivalent that is simply not
+being called. `queue.ts` is the starkest case: it imports `commands` directly
+and re-implements ten methods the facade already provides.
+
+**(b) Playback control with no facade method.** `playerPlayQueue`,
+`playerGetQueue`, `playerGetStatus`, `playerEnterBackgroundAudio`,
+`playerExitBackgroundAudio`, `playerSetSleepTimer`, `playerCancelSleepTimer`,
+`playerPlayNextEpisode`, `playerCancelAutoplayCountdown`. In scope for the
+principle, but currently *impossible* to comply with — the facade has no surface
+for them. A rule that cannot be followed is not being broken so much as it is
+unfinished.
+
+**(c) Not playback control.** `playerConfigureJellyfin` ×3,
+`playerDisableJellyfin`, `playerGet/SetAudioSettings`,
+`playerGet/SetVideoSettings`, `playerGetEqPresets`,
+`playerGet/SetAutoplaySettings`, `playerGet/SetCacheConfig`,
+`playerPreloadUpcoming`. These are configuration and lifecycle calls that happen
+to live under the `player_` command prefix. The principle is about *who is
+authoritative for playback state* — settings CRUD isn't that.
+
+The audit's read: the rule as written is violated 52 times, which makes real
+drift indistinguishable from acceptable usage, and that ambiguity is what lets
+group (a) persist. Note also that the principle **is** well-honoured where it
+matters most — the read side is clean, with UI reading state exclusively from
+the facade's re-exported stores. The write side is what drifted.
+
+## Layer assignment
+
+Frontend-internal refactor. No domain logic moves and nothing new crosses IPC —
+the same Rust commands are called, through one module instead of many.
+
+| Logic / responsibility | Layer | Why it belongs there |
+|------------------------|-------|----------------------|
+| Playback command dispatch (adapter routing: native vs HTML5) | Frontend — `src/lib/player/` **only** | Presentation-layer plumbing, but must be centralised: the facade picks between the native backend and the HTML5 `<video>` adapter. A caller bypassing it silently skips that routing. |
+| Playback *authority* (position, pause, rate, track changes) | **Rust / the player** | Unchanged. The player is authoritative; UI is a consumer. This spec does not touch that direction. |
+| Queue mutation commands | Frontend facade → Rust | Rust owns queue state; the facade is the single call path to it. |
+| Player settings CRUD (EQ, video, autoplay, cache) | Frontend, **outside** the facade | Configuration, not playback control — read/written on a settings page with no adapter routing. Explicitly carved out below. |
+| Backend→frontend event handling | `playerEvents.ts` | Already correct. It is the facade's own plumbing, not a bypassing consumer. |
+
+No Jellyfin taxonomy is involved, so no boundary-leak risk.
+
+## Design
+
+### 1. Narrow the principle to what it actually means
+
+Amend CLAUDE.md and [02-svelte-frontend.md](../architecture/02-svelte-frontend.md):
+
+> **Unified player boundary.** UI controls **playback** — transport, queue
+> mutation, track selection, playback initiation — *only* through
+> `playerController`. Player **configuration** commands (`player_*_settings`,
+> `player_configure_jellyfin`, `player_*_cache_config`, `player_preload_upcoming`)
+> are ordinary IPC and may be called directly from settings surfaces.
+
+This is a clarification, not a relaxation: it makes group (c) explicitly fine so
+that a violation count means something. A rule with 52 nominal violations, most
+of them acceptable, provides no signal.
+
+### 2. Fill the facade gaps (group b)
+
+Add to `playerController`, each a thin pass-through preserving current
+behaviour:
+
+```ts
+playQueue, getQueue, getStatus,
+enterBackgroundAudio, exitBackgroundAudio,
+setSleepTimer, cancelSleepTimer,
+playNextEpisode, cancelAutoplayCountdown,
+```
+
+Do this **first** — group (a) cannot be fully migrated while callers still need
+a direct import for a neighbouring call, and a file that imports `commands` for
+one reason will keep using it for others.
+
+### 3. Migrate group (a)
+
+Mechanical: replace `commands.playerX(...)` with `playerController.x(...)`.
+Highest-value first: `queue.ts` (10 sites, all direct facade equivalents), then
+`player/[id]/+page.svelte`, `VideoPlayer.svelte`, `sleepTimer.ts`,
+`playbackMode.ts`, `library/[id]/+page.svelte`.
+
+Two sites need care rather than substitution:
+
+- **`playerEvents.ts`** (`playerOnPlaybackEnded`, `playerStop` in the error
+  path). This module *is* the facade's event plumbing — the counterpart to
+  `index.ts`, inside the boundary conceptually though not by directory. Treat
+  `src/lib/services/playerEvents.ts` as **inside** the boundary and exempt it,
+  rather than making it call the facade that calls back into it. Record this in
+  the lint config with the reason.
+- **`VideoPlayer.svelte`** — registers its own adapter via `setActiveAdapter`.
+  Its `playerStop`/`playerPlayItem` calls interact with adapter lifecycle, and
+  CLAUDE.md's gotcha ("no lifecycle calls after an `await` in `onMount`") applies.
+  Migrate this file **last and on its own**, so an Android seek regression is
+  bisectable to one commit.
+
+### 4. Add the lint rule (the part that makes it stick)
+
+The audit's finding was that principles with working checks held up and
+principles without them drifted. This principle has no check. Add
+`scripts/check-player-boundary.sh`, wired as `bun run check:player-boundary` and
+into `test-all.sh`:
+
+```sh
+# Playback-control commands that MUST go through the facade.
+CONTROL='player(Play|Pause|Toggle|Stop|Seek|Next|Previous|SkipTo|ToggleShuffle|CycleRepeat|RemoveFromQueue|MoveInQueue|SetVolume|ToggleMute|SetSubtitleTrack|SeekVideo|SwitchAudioTrack|PlayTracks|PlayAlbumTrack|PlayItem|PlayQueue|AddTrackById|AddTracksByIds|GetQueue|GetStatus|EnterBackgroundAudio|ExitBackgroundAudio|SetSleepTimer|CancelSleepTimer|PlayNextEpisode|CancelAutoplayCountdown|OnPlaybackEnded)'
+
+# Inside the boundary: the facade and its event plumbing.
+EXEMPT='^src/lib/player/|^src/lib/services/playerEvents\.ts$'
+```
+
+Flag `commands.$CONTROL` in non-test `src/` files outside `EXEMPT`. Config
+commands are deliberately absent from the list, matching §1 — so the check
+encodes the narrowed rule rather than the aspirational one.
+
+An ESLint `no-restricted-syntax` rule would give better editor feedback, but the
+project has no ESLint config; a shell check matches the existing
+`check:boundary` precedent and adds no dependency.
+
+## Out of scope
+
+- Changing playback *behaviour* — pure refactor.
+- The one-directional state principle (audited clean; UI reads from facade
+  stores only).
+- Moving settings CRUD behind the facade (§1 explicitly carves it out).
+- Introducing ESLint.
+- Refactoring `VideoPlayer.svelte`'s 2079 lines generally, beyond its facade
+  call sites.
+- The `commands.player*` calls **inside** `src/lib/player/` — that is the
+  facade doing its job.
+
+## Acceptance criteria
+
+- [ ] `playerController` exposes the group-(b) methods listed in §2.
+- [ ] `grep -rn "commands\.player" src/ --include='*.ts' --include='*.svelte' | grep -v '^src/lib/player/' | grep -v 'playerEvents\.ts' | grep -v '\.test\.' | grep -v bindings.ts`
+      returns **only** configuration commands per §1 — no transport, queue, or
+      playback-initiation call.
+- [ ] `queue.ts` no longer imports `commands` from bindings.
+- [ ] `bun run check:player-boundary` exists, is wired into `test-all.sh`, and
+      passes.
+- [ ] The check **fails** when a `commands.playerStop()` is added to a non-exempt
+      file — verify explicitly, as with the other gates in this batch.
+- [ ] The check does **not** fail on `commands.playerSetAudioSettings()` in
+      `settings/+page.svelte` (the §1 carve-out works).
+- [ ] CLAUDE.md and `02-svelte-frontend.md` carry the narrowed wording, including
+      the config carve-out and the `playerEvents.ts` exemption with its reason.
+- [ ] **No behavioural change**: audio and video playback, queue reorder,
+      shuffle/repeat, sleep timer, background audio, and autoplay all behave as
+      before on **both Linux and Android**.
+- [ ] Android seek and `onMount` lifecycle still correct after the
+      `VideoPlayer.svelte` migration (the known-fragile path).
+- [ ] `bun run check` and `bun run test` pass.
+- [ ] `bun run check:boundary` passes.
+- [ ] Changed code carries `// TRACES:` comments.
+- [ ] No Rust change, so no `bindings.ts` regeneration.
+
+## Testing
+
+**Frontend** (`bun run test`):
+- Extend the existing facade tests to cover each new group-(b) method: it
+  forwards to the right command with the right arguments, and routes to the
+  active adapter where applicable.
+- `queue.ts` tests: assert calls land on `playerController`, not `commands`. Mock
+  the facade — a test that mocks `commands` would pass either way and guard
+  nothing.
+- Keep `tauriIntegration.test.ts` and the other IPC param-naming tests green;
+  they cover the camelCase rule this refactor must not disturb.
+
+**Manual** (no automated coverage for these paths):
+- Linux: play/pause/seek/next/prev, queue reorder, shuffle, repeat, sleep timer,
+  transcoded video (HLS), background audio enter/exit.
+- Android: the same, plus lockscreen/MediaSession controls, and **seek after
+  entering the player** — the specific regression CLAUDE.md warns about.
+
+Because this is a pure refactor, the strongest signal is that no test *changes
+expectation*. A test needing its assertions rewritten means behaviour moved —
+investigate rather than update it.
+
+## TRACES
+
+Allocate in `requirements.md`:
+
+- **DR-095** — "UI playback control is routed exclusively through the
+  `playerController` facade (`src/lib/player/`), with `playerEvents.ts` inside
+  the boundary as its event plumbing and player *configuration* commands
+  explicitly outside it; enforced by `scripts/check-player-boundary.sh`."
+  Category: Player. Traces to UR-005. Status: Done on merge.
+
+```typescript
+// src/lib/player/index.ts
+// TRACES: UR-005 | DR-095
+```
+
+New facade tests take `@req-test: UT-089` onward (next free UT is **UT-089**;
+coordinate if landing alongside the sibling specs, which draw from the same
+pool).
+
+## Notes for the implementer
+
+- A parallel Claude session may be active in this repo — `git diff` before
+  "repairing" unexpected changes (CLAUDE.md §Gotchas).
+- **Order matters**: §2 (fill gaps) → §3 (migrate, `VideoPlayer.svelte` last and
+  alone) → §4 (add the check). Adding the check first turns `master` red.
+- 🔴 **`VideoPlayer.svelte`**: no lifecycle calls after an `await` in `onMount` —
+  it flips to HTML5 mode and breaks Android seek. Do not let a mechanical
+  substitution introduce an `await` before a lifecycle call.
+- The facade's `requireHandle()` may throw where a raw `commands` call did not.
+  Check each migrated call site's error handling rather than assuming the
+  try/catch still covers the same cases.
+- `playbackMode.ts` interacts with remote-mode routing (`play_on_session` vs
+  local MPV). Verify remote casting still works after migrating its
+  `playerPlayTracks` call.
+- This spec is deliberately the *lowest* priority of the audit batch: it is the
+  largest diff and the only one carrying real regression risk, while the
+  traceability gate is a few lines and restores a dead safety net.
@@ -0,0 +1,161 @@
+# Spec: Remove the broken `check-req-coverage.sh`
+
+**Status:** Implemented
+**Requirements:** supports DR-093 (see [traceability-gate-repair.md](traceability-gate-repair.md))
+**UX spec:** n/a — developer tooling.
+**Supersedes / revises:** n/a
+
+## Summary
+
+`scripts/check-req-coverage.sh` is broken, orphaned, and actively misleading: it
+reports `Total Requirements: 1`, zeros in every category, and then prints
+**"✨ All requirements have implementations!"**. Nothing references it — not CI,
+not `package.json`, not the docs. This spec deletes it, with a narrowly-scoped
+alternative (repair it) documented and rejected below.
+
+## Motivation
+
+Running it today produces:
+
+```
+Category Breakdown:
+UR:    0 requirements
+IR:    0 requirements
+DR:    0 requirements
+JA:    0 requirements
+
+Summary:
+Total Requirements:       1
+✅ Fully Implemented:     0 (0%)
+
+✨ All requirements have implementations!
+```
+
+Every number is wrong (the real totals are UR 61, IR 29, DR 89, JA 32), and the
+concluding message is the *opposite* of a warning — a developer running this to
+sanity-check coverage is told everything is fine.
+
+This is worse than having no script. It is a trap, and it sits in `scripts/`
+next to tools that do work, with nothing marking it as dead.
+
+Verification that it is genuinely orphaned:
+
+```console
+$ grep -rn "check-req-coverage" . --include='*.yml' --include='*.json' \
+      --include='*.sh' --include='*.md' | grep -v node_modules
+(no output)
+```
+
+## Layer assignment
+
+Developer tooling only; no application logic and nothing crosses the IPC
+boundary.
+
+| Logic / responsibility | Layer | Why it belongs there |
+|------------------------|-------|----------------------|
+| Requirement-coverage reporting | Build tooling — `extract-traces.ts` | One tool should own coverage analysis. A second, divergent implementation is how the two answers ("1 requirement" vs "211") came to disagree unnoticed. |
+
+## Design
+
+**Delete `scripts/check-req-coverage.sh`.**
+
+Coverage reporting is owned by [scripts/extract-traces.ts](../../scripts/extract-traces.ts),
+which is correct, is what CI runs, and gains a first-class local coverage mode
+in [traceability-gate-repair.md](traceability-gate-repair.md):
+
+```bash
+bun run traces:coverage   # the supported way to check coverage locally
+```
+
+Then check the sibling scripts for the same rot. `scripts/` also contains
+`check-test-coverage.sh` and `find-req-implementations.sh`, neither of which is
+referenced from `package.json`. An unreferenced script is never run and so rots
+silently — that is the actual failure mode being fixed here, and fixing only the
+one instance found by audit leaves the others to be rediscovered later.
+
+### Findings (investigation, 2026-07)
+
+All three scripts turned out to share a **single root cause**, and all three are
+deleted:
+
+| Script | Defect |
+|---|---|
+| `check-req-coverage.sh` | Reads `README.md`, which has held **zero** requirement rows since they moved to `docs/requirements.md` → `total_reqs=1`, every category 0, "✨ All requirements have implementations!" Also greps `src-tauri/` unscoped. |
+| `check-test-coverage.sh` | Greps `src-tauri/` unscoped — including **40 GB** of `target/` build artifacts. Hangs indefinitely; produces no output at all. |
+| `find-req-implementations.sh` | Same unscoped `src-tauri/` grep. Same hang. |
+
+So none of them were subtly wrong — two could never terminate, and the third
+inverted its own conclusion.
+
+They were nonetheless *salvageable*: scoping the greps to `src-tauri/src` and
+repointing at `docs/requirements.md` would be a few lines, and the `@req:` /
+`@req-test:` tags they read are still present in the tree (**146** and **76**
+occurrences).
+
+**Decision: delete all three anyway.** The tags are an undocumented parallel
+convention — `@req:` appears in no doc, and CLAUDE.md describes only `TRACES:`.
+Repairing the scripts would re-establish a second traceability system to keep in
+sync with the first, which is the same two-sources-of-truth condition that let
+"1 requirement" and "211 requirements" coexist unnoticed. `TRACES:` plus the
+repaired coverage engine ([traceability-gate-repair.md](traceability-gate-repair.md))
+already cover this ground.
+
+The existing `@req:` / `@req-test:` comments are left in place: they are
+harmless as prose, several encode genuinely useful test intent, and stripping
+222 comments across the tree is a large diff with no functional gain. They are
+simply no longer read by any tool.
+
+### Alternative considered: repair rather than delete
+
+Rejected. The script's output format duplicates what `traces:markdown` already
+generates, it has no tests, no caller, and no documented purpose distinct from
+`extract-traces.ts`. Repairing it recreates the two-sources-of-truth condition
+that produced the contradiction. If a shell-based coverage check is ever wanted,
+it should shell out to `traces:json` and `jq` rather than re-parse
+`requirements.md` independently.
+
+## Out of scope
+
+- The CI workflow denominators — [traceability-gate-repair.md](traceability-gate-repair.md).
+- Any change to `extract-traces.ts`'s output (that spec owns it).
+- Auditing scripts that *are* referenced from `package.json` — they run
+  regularly and would fail visibly.
+
+## Acceptance criteria
+
+- [ ] `scripts/check-req-coverage.sh` no longer exists.
+- [ ] `grep -rn "check-req-coverage" .` (excluding `node_modules` and this spec)
+      returns nothing — no dangling reference in CI, docs, or `package.json`.
+- [ ] `scripts/check-test-coverage.sh` and `find-req-implementations.sh` have each
+      been run and either wired into `package.json` or deleted; the decision and
+      reason are recorded in `scripts/README.md`. **Outcome: all three deleted —
+      see Findings.**
+- [ ] `scripts/README.md` documents `bun run traces:coverage` as the supported
+      way to check requirement coverage locally.
+- [ ] `bun run test:all` passes (confirms nothing invoked the deleted script).
+- [ ] `bun run check` and `bun run test` pass.
+- [ ] `bun run check:boundary` passes.
+
+## Testing
+
+No unit tests — this is a deletion. Verification is the grep in the acceptance
+criteria plus a green `bun run test:all`, which exercises the script paths that
+actually run.
+
+## TRACES
+
+No new requirement. The deletion is covered by **DR-093**
+([traceability-gate-repair.md](traceability-gate-repair.md)), which establishes
+`extract-traces.ts` as the single owner of coverage reporting. Note the removal
+in that DR's text when both land.
+
+## Notes for the implementer
+
+- A parallel Claude session may be active in this repo — `git diff` before
+  "repairing" unexpected changes (CLAUDE.md §Gotchas).
+- Land this **after** or alongside [traceability-gate-repair.md](traceability-gate-repair.md),
+  so `bun run traces:coverage` exists before the broken script is removed and
+  developers are never left without a coverage command.
+- Check `docs/traceability-ci.md` and `docs/traces-quick-ref.md` for prose
+  references to the deleted script; the grep above covers `.md`, but read the
+  surrounding sentence rather than deleting the line mechanically.
@@ -0,0 +1,254 @@
+# Spec: Land the scoped-search boundary fix (implementation)
+
+**Status:** Stage 1 Implemented — Stage 2 (result-side grouping) outstanding
+**Requirements:** UR-049, UR-050 | DR-063, DR-066, DR-067 (existing — no new IDs)
+**UX spec:** n/a — zero user-visible change is the point (see Acceptance criteria).
+**Supersedes / revises:** implements [scoped-search-boundary.md](scoped-search-boundary.md),
+which specified this fix but was never built. That spec remains the **design
+authority**; this one is the delivery plan and status correction.
+
+## Summary
+
+[scoped-search-boundary.md](scoped-search-boundary.md) diagnosed a domain-taxonomy
+leak, specified the fix in full detail, and became the justification for the
+project's boundary rule in CLAUDE.md, the `check:boundary` tripwire, and the
+spec-review checklist. **The fix was never implemented.** The leak it describes
+is still live in `main`. This spec exists to close that gap and to correct the
+record — the codebase currently enforces a rule against a violation it still
+contains.
+
+## Motivation
+
+The mapping the rule forbids is present and in use:
+
+```ts
+// src/lib/utils/searchScope.ts:29-32
+const SCOPE_ITEM_TYPES: Record<Exclude<SearchScope, "all">, string[]> = {
+  music: ["MusicAlbum", "MusicArtist", "Audio", "Playlist"],
+  movies: ["Movie"],
+  tv: ["Series", "Episode"],
+};
+```
+
+This is not dead code. [library.ts:262](../../src/lib/stores/library.ts#L262)
+calls `scopeItemTypes(scope)` and puts the result straight into
+`options.includeItemTypes`. Meanwhile there is **no `SearchScope` anywhere in
+`src-tauri/`**:
+
+```console
+$ grep -rn "SearchScope" src-tauri/src --include='*.rs'
+(no output)
+```
+
+Three things make this the highest-value item found in the design-principles
+audit:
+
+1. **The rule's own founding incident is unremediated.** CLAUDE.md cites this
+   spec as "the incident this rule came from." A rule whose originating
+   violation is still shipping is not credible.
+2. **The tripwire cannot see it.** `bun run check:boundary` passes — it greps for
+   a multi-type array literal *at the query site*, and this one is assigned to a
+   named const and dereferenced elsewhere. Broadening the tripwire is specified
+   separately in [boundary-tripwire-hardening.md](boundary-tripwire-hardening.md);
+   note that hardening it **without** landing this fix would turn `master` red.
+3. **The spec's own acceptance criterion fails today.** "Adding a hypothetical
+   new type to a scope requires editing only Rust" — adding a type to the Music
+   scope right now requires editing `searchScope.ts`.
+
+## Layer assignment
+
+Unchanged from [scoped-search-boundary.md](scoped-search-boundary.md) §Design;
+restated so this spec is reviewable on its own.
+
+| Logic / responsibility | Layer | Why it belongs there |
+|------------------------|-------|----------------------|
+| Scope → Jellyfin item types (`music` → `MusicAlbum`, `MusicArtist`, `Audio`, `Playlist`) | **Rust** | Domain vocabulary. Changes if Jellyfin adds/renames an item type — the litmus test's "yes" case. This is the leak being fixed. |
+| Result item → search group bucketing | **Rust** | Same taxonomy, result side. Classifying a `MediaItem` as a Song vs Album is Jellyfin vocabulary, not layout. |
+| `All` sends no filter at all (≠ union of enumerated types) | **Rust** | A query-shaping rule with a correctness consequence (Person/folder results would be silently dropped). Belongs with the expansion it qualifies. |
+| Group display order, labels, reordering, persistence | Frontend | Pure presentation — changes only if the UI is redesigned. Explicitly retained frontend-side. |
+| `resolveSearchScope(pathname)` — route → initial scope | Frontend | Routing/navigation, no Jellyfin vocabulary. Stays exactly as-is. |
+| Chip labels (`SCOPE_LABELS`), scope order (`SEARCH_SCOPES`) | Frontend | Display strings over an opaque enum. |
+| `GROUP_SCOPE` (which group belongs to which scope) | **Delete** | Borderline taxonomy, made redundant: once Rust filters by scope, out-of-scope groups arrive empty and drop via the empty-omit rule. Borderline defaults to Rust; here it defaults to *gone*. |
+
+The `SearchScope` and `SearchGroupId` **types** come to the frontend from
+generated `bindings.ts`. Naming an opaque enum variant is not taxonomy; knowing
+what item types it expands to is.
+
+## Design
+
+**Follow [scoped-search-boundary.md](scoped-search-boundary.md) §Design as
+written** — `SearchScope` enum + `item_types()` in `repository/types.rs`,
+`SearchOptions.scope`, `SearchGroupId`/`SearchGroup`/`GroupedSearchResult`,
+scope-wins precedence, `All` → `None` → no filter. It is not restated here;
+duplicating it would create two drifting copies of the same design.
+
+This spec adds only the delivery sequencing that the original left implicit.
+
+### Staging: land it in two reviewable pieces
+
+The original bundles the query side and the result side into one change. That is
+a large diff touching Rust types, `bindings.ts`, the store, and a component, with
+the `search-event` dual-payload hazard in the middle. Split it:
+
+**Stage 1 — query side (closes the leak).**
+`SearchScope` enum, `SearchOptions.scope`, command resolves scope →
+`include_item_types` in Rust, `library.ts` sends `{ scope }`, delete
+`SCOPE_ITEM_TYPES` and `scopeItemTypes()`. Result grouping stays as it is.
+
+After Stage 1 the actual boundary violation is gone and
+[boundary-tripwire-hardening.md](boundary-tripwire-hardening.md) can land safely.
+
+**Stage 2 — result side.** `SearchGroupId`/`SearchGroup`/`GroupedSearchResult`,
+Rust bucketing, both payloads converted, `composeSearchGroups()` shrunk,
+`GROUP_ITEM_TYPES`/`groupItemTypes()`/`GROUP_SCOPE` deleted.
+
+Both stages are required for the original spec's acceptance criteria to pass;
+Stage 1 alone leaves `GROUP_ITEM_TYPES` in the frontend. **Stage 1 is not a
+stopping point** — it is a review boundary. Do not mark the parent spec
+Implemented until Stage 2 lands.
+
+### Stage 1 — delivered (July 2026)
+
+- `SearchScope` enum + `item_types()` in [repository/types.rs](../../src-tauri/src/repository/types.rs);
+  `All` → `None` → no filter.
+- `SearchOptions.scope` with `resolve_scope()`; scope wins over
+  `include_item_types`, which stays for the non-search `get_items` callers.
+- `repository_search` resolves the scope **once, before** the cache/server split,
+  so both phases filter identically.
+- `SCOPE_ITEM_TYPES` and `scopeItemTypes()` deleted; `searchScope.ts` now
+  re-exports `SearchScope` from the generated bindings instead of a hand-written
+  union.
+- [library.ts](../../src/lib/stores/library.ts) sends `{ scope }`.
+- 8 Rust tests (`search_scope_tests`); the frontend suite now asserts the
+  *opaque scope* is sent rather than an item-type list.
+
+Verified: adding `"AudioBook"` to the Music scope changed **zero** files under
+`src/` — the criterion that failed before this work.
+
+**Stage 2 remains open**: `GROUP_ITEM_TYPES` / `groupItemTypes()` (result-side
+bucketing, single-type-per-group) are still in `searchScope.ts`, and both search
+payloads still carry a flat `MediaItem[]` rather than `GroupedSearchResult`.
+
+### 🔴 The `search-event` dual payload (Stage 2)
+
+The original flags this as "the single largest part of the change and the
+easiest to half-do." Restating because it is the one thing that silently breaks:
+search resolves **twice** — the command returns instant cache results, then the
+merged cache+server union arrives via `search-event`. Both payloads must carry
+`GroupedSearchResult`. Convert one and the UI flickers between shapes as server
+results land.
+
+Write the failing test for the *event* payload first — the command return is the
+obvious half, the event is the half that gets forgotten.
+
+### Note on `SearchOptions.scope` and specta
+
+`SearchOptions` is already `#[serde(rename_all = "camelCase")]` with
+`skip_serializing_if = "Option::is_none"`. Add `scope: Option<SearchScope>`
+following that pattern so `All`/absent omits the key. Regenerate `bindings.ts`
+— `SearchOptions` there is currently
+`{ limit?, includeItemTypes?, searchTerm? }` and must gain `scope?`. Never
+hand-edit it.
+
+## Out of scope
+
+- Redesigning anything in [scoped-search-boundary.md](scoped-search-boundary.md).
+  If implementation shows the design wrong, revise **that** spec, don't fork it.
+- Online/offline `include_item_types` **filtering** — already correct; only the
+  source of the type list moves.
+- Ranking within or across groups (DR-090 territory).
+- Chip UX, scope persistence, group-order persistence — unchanged.
+- The two lesser type-set sites in `DownloadedBrowse.svelte` and
+  `GenericMediaListPage.svelte`, handled in
+  [boundary-tripwire-hardening.md](boundary-tripwire-hardening.md).
+- Broadening the tripwire itself — same sibling spec.
+
+## Acceptance criteria
+
+Inherits every criterion from [scoped-search-boundary.md](scoped-search-boundary.md)
+§Acceptance criteria. Additionally:
+
+- [ ] `grep -rn "SearchScope" src-tauri/src --include='*.rs'` returns matches —
+      the enum exists in Rust (it does not today).
+- [ ] `grep -n "SCOPE_ITEM_TYPES\|scopeItemTypes\|GROUP_ITEM_TYPES\|groupItemTypes" src/lib/utils/searchScope.ts`
+      returns nothing.
+- [ ] `grep -rn "scopeItemTypes" src/` returns nothing — including the
+      `library.ts` import and call site.
+- [ ] `SearchOptions` in `bindings.ts` includes `scope`; regenerated, not
+      hand-edited.
+- [ ] **Behaviour is byte-identical for the user**: same scoping, same groups,
+      same order, same empty-group omission, offline included. This spec is a
+      pure refactor — any visible change is a defect.
+- [ ] `All` scope sends no `includeItemTypes` (asserted in a Rust test, not by
+      inspection).
+- [ ] Adding a type to the Music scope requires editing **only** Rust —
+      demonstrate by making the edit and confirming no `src/` file changes.
+- [ ] `scoped-search-boundary.md` status flips to **Implemented**, and
+      `scoped-search.md`'s "frontend only, no Rust changes" framing gets a
+      banner pointing at the corrected design.
+- [ ] `bun run check` and `bun run test` pass.
+- [ ] `cargo fmt` clean, `cargo clippy` clean, `bun run test:rust` passes.
+- [ ] `bun run check:boundary` passes.
+- [ ] Changed code carries `// TRACES:` comments (IDs below).
+
+## Testing
+
+Follow [scoped-search-boundary.md](scoped-search-boundary.md) §Testing. Emphases:
+
+**Rust** (`cargo test`):
+- `SearchScope::item_types()` per scope; `All` → `None`.
+- Scope resolution happens **before** the online/offline split, so both paths
+  get the same filter — a regression here is invisible until someone searches
+  offline.
+- `scope` set + `include_item_types` set → scope wins (the documented
+  precedence; assert it rather than trusting the doc).
+- Stage 2: mixed `Vec<MediaItem>` buckets correctly; unknown types dropped;
+  canonical group order; **the `search-event` payload is the grouped shape**.
+
+**Frontend** (`bun run test`):
+- `resolveSearchScope()` tests in `searchScope.test.ts` must pass **unchanged** —
+  they cover the part that is not moving, and are the regression net proving the
+  refactor didn't disturb routing.
+- `library.ts` sends `{ scope }` and never `includeItemTypes` for search.
+- `composeSearchGroups()` over fixture `SearchGroup[]` with no `.type`
+  inspection in the implementation.
+
+**Offline parity:** run a scoped search with the server unreachable and confirm
+identical grouping. The offline repository path honours `include_item_types`
+independently, and this is the case most likely to be missed.
+
+## TRACES
+
+No new requirement IDs — this implements existing ones. Retag as the code moves:
+
+```rust
+// src-tauri/src/repository/types.rs
+/// TRACES: UR-049 | DR-063
+pub enum SearchScope { … }
+```
+
+```typescript
+// src/lib/utils/searchScope.ts — keep the file header; it retains
+// resolveSearchScope + group-order presentation logic.
+// TRACES: UR-049, UR-050 | DR-063, DR-066, DR-067
+```
+
+Update DR-063's text in `requirements.md` to state that scope expansion is owned
+by Rust, so the requirement stops describing the leaked design. New Rust tests
+take `@req-test: UT-089` onward (next free UT is **UT-089**).
+
+## Notes for the implementer
+
+- A parallel Claude session may be active in this repo — `git diff` before
+  "repairing" unexpected changes (CLAUDE.md §Gotchas).
+- **Read [scoped-search-boundary.md](scoped-search-boundary.md) first.** This
+  spec is deliberately thin on design; that one is the authority.
+- Sequence with the sibling specs: **Stage 1 here → then
+  [boundary-tripwire-hardening.md](boundary-tripwire-hardening.md)**. Hardening
+  the tripwire first turns `master` red on a known-unfixed violation.
+- `git log --oneline -- docs/specs/scoped-search-boundary.md` is worth a look
+  before starting — understanding why the fix stalled may surface a constraint
+  the spec didn't record.
+- The user-visible-change count for this spec is zero. If QA reports a
+  difference in search results, that is a bug in the refactor, not an
+  improvement.
@@ -8,8 +8,14 @@
 > is being moved into Rust. The **user-facing behaviour and UX in this spec are
 > unchanged**; only where the scope→item-type mapping and result bucketing live
 > changes. Read the boundary spec before touching search code.
+>
+> **Progress:** the scope→item-type mapping now lives in Rust
+> (`SearchScope::item_types()`); the frontend sends an opaque scope. Result-side
+> bucketing (`GROUP_ITEM_TYPES`) is still frontend-side — see
+> [scoped-search-boundary-implementation.md](scoped-search-boundary-implementation.md)
+> §Stage 2.

-**Status:** Implemented (boundary revision pending — see banner above)
+**Status:** Implemented (boundary revision: query side done, result side pending)
 **Scope:** Frontend only. No Rust changes required. *(Revised — see banner.)*
 **Requirements:** UR-049 → DR-063, DR-064, DR-065; UR-050 → DR-066, DR-067
 (see [requirements.md](../requirements.md)).
@@ -0,0 +1,238 @@
+# Spec: Repair the traceability coverage gate
+
+**Status:** Implemented
+**Requirements:** DR-093 → supports the traceability practice described in CLAUDE.md
+**UX spec:** n/a — developer tooling, no user-facing surface.
+**Supersedes / revises:** n/a
+
+## Summary
+
+The CI traceability gate has been passing unconditionally for an unknown length
+of time because it divides traced-requirement counts by **hardcoded denominators
+that no longer match [requirements.md](../requirements.md)**. It currently
+reports **158% overall coverage** (and `JA 24 / 3 = 800%`), so the 50% threshold
+is mathematically unreachable and the job cannot fail. This spec makes the gate
+derive its denominators from `requirements.md` at run time, so it reports the
+real number (**85%** today) and can actually fail again.
+
+## Motivation
+
+`.gitea/workflows/traceability-check.yml` hardcodes `UR/39, IR/24, DR/48, JA/3`
+and `TOTAL_REQS=114`. The real counts are **UR 61, IR 29, DR 89, JA 32 — 211
+total**. Requirements were added over time; the divisors were never updated.
+
+The consequence is not a cosmetic reporting bug. The gate is the *only*
+automated defence for the traceability practice, and it is dead:
+
+```
+CI today:  181 / 114 = 158%  → threshold 50% can never trip
+Reality:   181 / 211 =  85%  → healthy, but unguarded
+```
+
+Coverage could collapse to 30% and CI would still print a green
+"✅ Coverage is acceptable". An audit of the design principles found that every
+principle with a *working* automated check is in good shape, and the ones that
+drifted are exactly the ones whose checks were broken or too narrow — this is
+the clearest instance.
+
+A second, related defect is handled in a sibling spec: `scripts/check-req-coverage.sh`
+is separately broken and orphaned (see
+[req-coverage-script-removal.md](req-coverage-script-removal.md)).
+
+## Layer assignment
+
+This spec touches only CI/build tooling — no application logic crosses the
+Rust/Svelte boundary. The table is filled in for completeness.
+
+| Logic / responsibility | Layer | Why it belongs there |
+|------------------------|-------|----------------------|
+| Counting requirement IDs defined in `requirements.md` | Build tooling (`scripts/`) | Neither runtime layer; it is repo metadata analysis. Belongs beside `extract-traces.ts`, not in the workflow YAML, so it is runnable and testable locally. |
+| Counting *traced* requirement IDs | Build tooling — existing `extract-traces.ts` | Already implemented and correct; this spec consumes it rather than duplicating it. |
+| Threshold policy (the 50% number) | CI workflow | Deployment policy, not analysis. Keeping it in YAML lets it be tuned without touching the script. |
+
+No frontend or Rust logic is added, so no taxonomy leak is possible.
+
+## Design
+
+### 1. Denominators come from `requirements.md`, not literals
+
+`requirements.md` defines requirements in markdown tables with a stable leading
+cell, e.g.:
+
+```
+| DR-001 | Player state machine (idle, loading, …) | Player | UR-005 | Done |
+| UR-002 | Access media when online or offline | High | Done |
+```
+
+Extend [scripts/extract-traces.ts](../../scripts/extract-traces.ts) to also emit
+the *defined* counts, so one tool owns both sides of the fraction and CI does no
+arithmetic on stale literals. Add a `defined` key to the JSON report:
+
+```jsonc
+{
+  "byType":   { "UR": [...], "IR": [...], "DR": [...], "JA": [...] },  // traced (existing)
+  "defined":  { "UR": 61, "IR": 29, "DR": 89, "JA": 32 },              // NEW
+  "coverage": { "covered": 181, "total": 211, "percent": 85 },         // NEW
+  "requirements": { ... },                                             // existing
+  "totalTraces": 318, "totalFiles": …, "timestamp": "…"                // existing
+}
+```
+
+Parsing rule for a *defined* requirement: a line in `docs/requirements.md`
+matching `^\|\s*(UR|IR|DR|JA)-\d{3}\s*\|` — the ID must be the table's first
+cell. This deliberately does **not** count IDs mentioned in the `Traces To`
+column or in prose, which is why a naive `grep -o` over the whole file
+overcounts.
+
+`defined` counts IDs that exist in the spec; `byType` counts IDs that appear in
+a `TRACES:` comment somewhere in the source. Coverage is
+`|byType ∩ defined| / |defined|`.
+
+> **Intersection, not raw length.** A `TRACES:` comment naming an ID that
+> `requirements.md` does not define (a typo, or a requirement later deleted)
+> must **not** inflate the numerator — that is how a ratio exceeds 100% in the
+> first place. Such IDs are reported separately as `orphaned` so they get fixed
+> rather than silently counted or silently dropped.
+
+```jsonc
+"orphaned": ["DR-097"]   // traced in code but not defined in requirements.md
+```
+
+### 2. The workflow consumes the computed number
+
+Replace the arithmetic in `.gitea/workflows/traceability-check.yml` (lines
+46–76) with reads of the precomputed fields:
+
+```sh
+COVERAGE=$(jq '.coverage.percent' traces-report.json)
+COVERED=$(jq '.coverage.covered' traces-report.json)
+TOTAL_REQS=$(jq '.coverage.total'   traces-report.json)
+
+for T in UR IR DR JA; do
+  TRACED=$(jq --arg t "$T" '.byType[$t] | length' traces-report.json)
+  DEFINED=$(jq --arg t "$T" '.defined[$t]'        traces-report.json)
+  echo "   $T: $TRACED / $DEFINED"
+done
+
+MIN_THRESHOLD=50
+[ "$COVERAGE" -lt "$MIN_THRESHOLD" ] && { echo "❌ …"; exit 1; }
+```
+
+No hardcoded denominator survives anywhere in the workflow.
+
+### 3. A self-check so this cannot silently rot again
+
+The root cause was a number that drifted with nothing watching it. Add a
+guard that fails the job on an arithmetically impossible result:
+
+```sh
+if [ "$COVERAGE" -gt 100 ]; then
+  echo "❌ Coverage > 100% — the gate is miscomputing; orphaned IDs: $(jq -c '.orphaned' traces-report.json)"
+  exit 1
+fi
+```
+
+A >100% reading is now a hard failure rather than a green tick.
+
+### 4. Local parity
+
+Add a script so the gate is runnable outside CI:
+
+```jsonc
+"traces:coverage": "bun run scripts/extract-traces.ts --format coverage"
+```
+
+Prints the same table CI prints and exits non-zero below threshold.
+
+### Threshold
+
+Keep `MIN_THRESHOLD=50` in this spec. Real coverage is 85%, so raising the bar
+is tempting, but doing it in the same change that repairs the gate conflates
+"restore the safety net" with "tighten the policy" — if the build then fails, it
+is ambiguous which change caused it. Ratcheting is deliberately deferred to
+follow-up work once the honest number has been observed on `master` for a few
+builds.
+
+## Out of scope
+
+- Raising `MIN_THRESHOLD` above 50 (see above).
+- Fixing/removing `scripts/check-req-coverage.sh` — [req-coverage-script-removal.md](req-coverage-script-removal.md).
+- Adding TRACES comments to raise the actual coverage number.
+- Changing the `TRACES:` comment format or the extractor's parsing of it.
+- The PR "modified files missing TRACES" step (lines 78–126), which is advisory
+  by design and stays advisory.
+
+## Acceptance criteria
+
+- [ ] `bun run traces:json` emits `defined`, `coverage`, and `orphaned` keys.
+- [ ] `coverage.total` equals the count of requirement IDs defined in
+      `requirements.md` (**211** at time of writing), not a literal.
+- [ ] `coverage.percent` reports **85** (±1 for rounding) on the current tree —
+      i.e. the honest number, not 158.
+- [ ] No hardcoded requirement denominator (`39`, `24`, `48`, `3`, `114`) remains
+      in `.gitea/workflows/traceability-check.yml`. Verify:
+      `grep -nE '/ *(39|24|48|3|114)\b' .gitea/workflows/traceability-check.yml`
+      returns nothing.
+- [ ] Adding a new requirement row to `requirements.md` **lowers** reported
+      coverage until it is traced (proves the denominator is live).
+- [ ] A `TRACES:` comment naming an undefined ID appears in `orphaned` and does
+      **not** raise `coverage.percent`.
+- [ ] The job fails if coverage is forced below 50% (test by temporarily raising
+      `MIN_THRESHOLD` to 99 locally) — proving the gate can fail again.
+- [ ] The job fails if coverage computes >100%.
+- [ ] `bun run check` and `bun run test` pass.
+- [ ] `bun run check:boundary` passes.
+- [ ] New requirement-implementing code carries `// TRACES:` comments.
+- [ ] No Rust types changed, so no `bindings.ts` regeneration needed.
+
+## Testing
+
+`extract-traces.ts` currently has no test coverage. Add
+`scripts/extract-traces.test.ts` (vitest) over fixture strings rather than the
+live `requirements.md`, so the tests do not change meaning as requirements are
+added:
+
+- **UT:** counts a well-formed table row as a defined requirement.
+- **UT:** does **not** count an ID appearing only in the `Traces To` column or
+  in prose — the specific overcounting bug this parse rule avoids.
+- **UT:** coverage is the intersection — a traced-but-undefined ID lands in
+  `orphaned` and does not inflate the numerator.
+- **UT:** coverage of an empty trace set is 0%, not a divide-by-zero.
+- **UT:** all-traced fixture reports exactly 100%, never above.
+
+CI behaviour is verified by the acceptance criteria above (the forced-failure
+check is the important one — a gate nobody has watched fail is not known to
+work).
+
+## TRACES
+
+Allocate in `requirements.md`:
+
+- **DR-093** — "Traceability coverage gate derives requirement denominators from
+  `requirements.md` at run time (not hardcoded literals), computes coverage as
+  the intersection of traced and defined IDs, reports IDs traced but undefined
+  as orphaned, and fails on an impossible >100% result." Category: Tooling.
+  Status: Done on merge.
+
+Tag:
+
+```typescript
+// scripts/extract-traces.ts
+// TRACES: | DR-093
+```
+
+Tests carry `@req-test: UT-089 …` onward (next free UT is **UT-089**).
+
+## Notes for the implementer
+
+- A parallel Claude session may be active in this repo — run `git diff` before
+  "repairing" unexpected changes (CLAUDE.md §Gotchas).
+- **Do not add tooling to the CI image for this.** `jq` and `bun` are already in
+  `jellytau-builder`; this spec needs nothing else. Installing a system package
+  in a workflow step violates the hard CI rule in CLAUDE.md.
+- Keep `traces:json`'s existing keys intact — `release-notes.ts` and
+  `traces:markdown` consume the same report, and the CI workflow uploads it as
+  an artifact. This is an additive change.
+- The `head -50 docs/traceability.md` and artifact-upload steps are unaffected.
+- Expect the first green build after this change to print a *lower* number than
+  before (85% vs 158%). That is the fix working, not a regression.
@@ -43,14 +43,26 @@ Extracts all TRACES comments from:

 ### 2. Coverage Thresholds
 The workflow checks:
- **Minimum overall coverage:** 50% (57+ requirements traced)
- **Requirements by type:**
-  - UR (User): 23+ of 39
-  - IR (Integration): 5+ of 24
-  - DR (Development): 28+ of 48
-  - JA (Jellyfin API): 0+ of 3
+- **Minimum overall coverage:** 50%

-If coverage drops below threshold, the workflow **fails** and blocks merge.
+Denominators are **derived from `docs/requirements.md` at run time** — they are
+never hardcoded here or in the workflow. Run `bun run traces:coverage` for the
+current per-type breakdown; any number written into this document is a snapshot
+that will drift.
+
+> **Why this matters.** The workflow used to divide by frozen literals
+> (UR/39, IR/24, DR/48, JA/3, total 114) while `requirements.md` had grown past
+> 200. It reported **158%** coverage, so the 50% threshold was unreachable and
+> the job could not fail regardless of how far coverage dropped. See
+> [specs/traceability-gate-repair.md](specs/traceability-gate-repair.md).
+
+Coverage is the *intersection* of traced and defined IDs: an ID that appears in
+a `TRACES:` comment but is not defined in `requirements.md` is reported as
+**orphaned** and does not count toward coverage. UT/IT test identifiers are a
+separate taxonomy and are excluded entirely.
+
+The workflow **fails** and blocks merge if coverage drops below 50% — or if it
+computes above 100%, which can only mean the gate is miscounting.

 ### 3. Modified File Checking
 On pull requests, the workflow:
@@ -153,11 +165,13 @@ cat docs/traceability.md
 ## Coverage Goals

 ### Current Status
- Overall: 51% (56/114)
- UR: 59% (23/39)
- IR: 21% (5/24)
- DR: 58% (28/48)
- JA: 0% (0/3)
+
+Run `bun run traces:coverage` — it prints the live figure and exits non-zero
+below threshold. Numbers are deliberately not pinned here; the previous snapshot
+in this section (51%, 56/114) was stale by roughly 100 requirements and was what
+made the broken CI arithmetic look plausible for so long.
+
+As of July 2026 overall coverage is ~86% (182/212).

 ### Targets
 - **Short term** (Sprint): Maintain ≥50% overall
@@ -1,6 +1,6 @@
 {
  "name": "jellytau",
-  "version": "0.2.0",
+  "version": "0.2.8",
  "description": "",
  "type": "module",
  "packageManager": "bun@1.3.5",
@@ -20,6 +20,8 @@
    "check:boundary": "bash scripts/check-frontend-boundary.sh",
    "android:build": "./scripts/build-android.sh",
    "android:build:release": "./scripts/build-android.sh release",
+    "android:build:device": "./scripts/build-android.sh --device",
+    "android:build:release:device": "./scripts/build-android.sh release --device",
    "android:build:clean": "rm -rf node_modules/.vite dist .svelte-kit .next build target src-tauri/target && bun install && bun run build",
    "android:deploy": "./scripts/deploy-android.sh",
    "android:dev": "./scripts/build-and-deploy.sh",
@@ -36,6 +38,7 @@
    "traces": "bun run scripts/extract-traces.ts",
    "traces:json": "bun run scripts/extract-traces.ts --format json",
    "traces:markdown": "bun run scripts/extract-traces.ts --format markdown > docs/traceability.md",
+    "traces:coverage": "bun run scripts/extract-traces.ts --format coverage",
    "release:notes": "bun run scripts/release-notes.ts"
  },
  "license": "MIT",
@@ -69,13 +69,29 @@ Extract requirement IDs (TRACES) from source code and generate a traceability ma
 bun run traces                    # Generate markdown report
 bun run traces:json              # Generate JSON report
 bun run traces:markdown           # Save to docs/traceability.md
+bun run traces:coverage           # Coverage gate — exits non-zero below 50%
 ```

-The script scans all TypeScript, Svelte, and Rust files looking for `TRACES:` comments and generates a comprehensive mapping of:
+The script scans all TypeScript, Svelte, and Rust files (plus `scripts/`)
+looking for `TRACES:` comments and generates a comprehensive mapping of:
 - Which code files implement which requirements
 - Line numbers and code context
 - Coverage summary by requirement type (UR, IR, DR, JA)

+**`bun run traces:coverage` is the supported way to check requirement coverage
+locally** — it runs the same computation CI does. Coverage denominators are
+derived from `docs/requirements.md` at run time; they are never hardcoded. An ID
+that appears in a `TRACES:` comment but is not defined in `requirements.md` is
+reported as *orphaned* and does not count toward coverage (see DR-093).
+
+> **Removed:** `check-req-coverage.sh`, `check-test-coverage.sh`, and
+> `find-req-implementations.sh` were deleted in July 2026. They read an
+> undocumented `@req:` tag convention parallel to `TRACES:`, grepped `src-tauri/`
+> unscoped (hanging on ~40 GB of `target/` artifacts), and in one case reported
+> "all requirements implemented" from an empty result set. `extract-traces.ts` is
+> the single source of truth for requirement coverage. See
+> [docs/specs/req-coverage-script-removal.md](../docs/specs/req-coverage-script-removal.md).
+
 Example TRACES comment in code:
 ```typescript
 // TRACES: UR-005, UR-026 | DR-029
@@ -18,15 +18,50 @@ echo ""
 # Parse args: build type (debug/release) and optional --clean flag.
 # By default the build is INCREMENTAL — Cargo and Vite reuse their caches.
 # Pass --clean (or CLEAN=1) to wipe all caches for a from-scratch build.
+#
+# ABI selection: by default Tauri builds all four ABIs (arm64/arm/x86/x86_64),
+# which is what a distributable universal APK needs — but for an on-device test
+# it means three wasted Rust compiles. Pass --device (or ABI=aarch64) to build
+# only the connected device's architecture; --abi <t> targets one explicitly.
 BUILD_TYPE="debug"
 CLEAN="${CLEAN:-0}"
+ABI="${ABI:-}"
+next_is_abi=0
 for arg in "$@"; do
+    if [ "$next_is_abi" = "1" ]; then
+        ABI="$arg"
+        next_is_abi=0
+        continue
+    fi
    case "$arg" in
        --clean) CLEAN=1 ;;
+        --abi) next_is_abi=1 ;;
+        --device) ABI="device" ;;
        debug|release) BUILD_TYPE="$arg" ;;
    esac
 done

+# Resolve --device to the attached device's Rust target triple.
+if [ "$ABI" = "device" ]; then
+    device_abi="$(adb shell getprop ro.product.cpu.abi 2>/dev/null | tr -d '\r\n')"
+    case "$device_abi" in
+        arm64-v8a)   ABI="aarch64" ;;
+        armeabi-v7a) ABI="armv7" ;;
+        x86_64)      ABI="x86_64" ;;
+        x86)         ABI="i686" ;;
+        *)
+            echo "⚠️  Could not detect device ABI (got '${device_abi:-none}') — building all targets."
+            ABI=""
+            ;;
+    esac
+    [ -n "$ABI" ] && echo "🎯 Device ABI $device_abi → building only '$ABI'"
+fi
+
+TARGET_ARGS=()
+if [ -n "$ABI" ]; then
+    TARGET_ARGS=(--target "$ABI")
+fi
+
 # Step 0: Optionally clear build caches for a fully fresh build.
 if [ "$CLEAN" = "1" ]; then
    echo "🧹 Clearing build caches (clean build)..."
@@ -48,10 +83,10 @@ if [ "$BUILD_TYPE" = "release" ]; then
    # after sync-android-sources.sh, since gen/android is (re)generated there.
    ./scripts/write-keystore-properties.sh
    echo "📦 Building release APK..."
-    bun run tauri android build --apk true
+    bun run tauri android build --apk true "${TARGET_ARGS[@]}"
 else
    echo "📦 Building debug APK..."
-    bun run tauri android build --apk true --debug
+    bun run tauri android build --apk true --debug "${TARGET_ARGS[@]}"
 fi

 echo ""
@@ -1,6 +1,8 @@
 #!/usr/bin/env bash
 # Boundary tripwire: flag domain-taxonomy leaks in the Svelte frontend.
 #
+# Implements DR-094 (see docs/requirements.md).
+#
 # The project rule (CLAUDE.md, docs/architecture/02-svelte-frontend.md) is that
 # the frontend is presentation-only and the Rust backend owns domain logic —
 # including Jellyfin's item-type *taxonomy* (what the category "Music" means as a
@@ -9,18 +11,29 @@
 #
 # ⚠️ This is a TRIPWIRE, NOT A PROOF. A grep cannot distinguish taxonomy-as-policy
 # (a leak) from taxonomy-as-display (legitimate: "is this a music card?"). It
-# targets the one machine-detectable signature of the leak class — a *query* that
-# names a multi-type category — and defers everything subtler to the human
-# spec-review checklist (docs/specs/SPEC-REVIEW-CHECKLIST.md). A clean run here
-# does not mean the boundary is respected; it means the crudest violation isn't
-# present.
+# targets the machine-detectable signature of the leak class and defers
+# everything subtler to the human spec-review checklist
+# (docs/specs/SPEC-REVIEW-CHECKLIST.md). A clean run here does not mean the
+# boundary is respected; it means the crudest violation isn't present.
 #
-# What it flags: an `includeItemTypes: [ ... , ... ]` array literal with two or
-# more types — i.e. the frontend deciding that a *category* maps to a *set* of
-# Jellyfin types, which is domain knowledge the backend should own. Single-type
-# query arrays (`includeItemTypes: ["Movie"]`) are a page saying "I show movies"
-# and are allowed. Type *inspection* (`item.type === "Audio"`) is display logic
-# and is not matched.
+# What it flags: an array literal naming two or more Jellyfin item types,
+# ANYWHERE in src/ — i.e. the frontend deciding that a *category* maps to a *set*
+# of Jellyfin types, which is domain knowledge the backend should own.
+# Single-type arrays (`includeItemTypes: ["Movie"]`) are a page saying "I show
+# movies" and are allowed. Type *inspection* (`item.type === "Audio"`) is display
+# logic and is not matched.
+#
+# 🔴 What it still CANNOT see (do not read a green run as proof):
+#   - a type set built at run time:      [...musicTypes, "Playlist"]
+#   - types split across variables:      const A = "Audio"; [A, B]
+#   - taxonomy as control flow:          switch (t) { case "Audio": … }
+#                                        t === "Audio" || t === "MusicAlbum"
+#   - an item type absent from ITEM_TYPES below (false negative by design)
+#
+# This check was hardened in July 2026 after the audit found it passing on the
+# very leak it was written for: the original pattern was anchored to
+# `includeItemTypes:` at the query site, so assigning the same array to a named
+# const evaded it entirely. See docs/specs/boundary-tripwire-hardening.md (DR-094).
 #
 # Escaping a genuine exception: add the file+reason to the ALLOWLIST below.

@@ -28,7 +41,7 @@ set -euo pipefail

 cd "$(dirname "$0")/.."

-# Files permitted to contain a multi-type includeItemTypes query, with the reason.
+# Files permitted to contain a multi-type item-type array, with the reason.
 # Keep this SHORT. A growing allowlist means the boundary is eroding — that is a
 # signal to push taxonomy into Rust, not to keep appending here.
 ALLOWLIST=(
@@ -36,8 +49,31 @@ ALLOWLIST=(
  # two-type filmography query with no category-configuration behind it. Tracked
  # as acceptable pending any person-scope work; revisit if it grows.
  "src/lib/components/library/PersonDetailView.svelte"
+
+  # Grid styling predicate over `config.itemType`, a value the page already
+  # declares about itself. Selects a *look*, issues no query, and would only
+  # change if the UI were redesigned — presentation, not taxonomy-as-policy.
+  "src/lib/components/library/GenericMediaListPage.svelte"
+
+  # "Is this item a container?" predicate for downloads browsing.
+  # BORDERLINE — leans domain: the container set grows when Jellyfin adds a
+  # container type. TODO: replace with a backend-supplied `MediaItem.isContainer`
+  # flag and remove this entry. Tracked in
+  # docs/specs/boundary-tripwire-hardening.md §Out of scope.
+  "src/lib/components/downloads/DownloadedBrowse.svelte"
 )

+# Hard cap so erosion is caught mechanically rather than by whoever notices.
+# Deliberately just above the current count: the next exception forces a
+# conversation instead of a one-line append.
+MAX_ALLOWLIST=4
+
+if [[ "${#ALLOWLIST[@]}" -gt "$MAX_ALLOWLIST" ]]; then
+  echo "❌ Allowlist has ${#ALLOWLIST[@]} entries (max $MAX_ALLOWLIST)."
+  echo "   Push taxonomy into Rust instead of appending here."
+  exit 1
+fi
+
 is_allowed() {
  local file="$1"
  for allowed in "${ALLOWLIST[@]}"; do
@@ -46,11 +82,28 @@ is_allowed() {
  return 1
 }

-# Multi-element includeItemTypes array: `includeItemTypes: [ <x> , <y> ... ]`.
-# The comma inside the brackets is what makes it multi-type.
-PATTERN='includeItemTypes:[[:space:]]*\[[^]]*,[^]]*\]'
+# Two or more adjacent Jellyfin item-type string literals inside a bracket.
+#
+# NOT anchored to `includeItemTypes:` — that was the original rule, and it missed
+# the real leak: `searchScope.ts` assigned the same array to a named const and
+# dereferenced it one indirection away from the query, so the grep never saw it
+# while CI stayed green. Matching the array literal itself catches a const, a
+# Record value, a function return, and an inline query alike.
+#
+# Deliberate limits:
+#   - requires TWO adjacent types, so single-type presentation
+#     (`itemType: "Movie"`) stays legal — the rule targets *category* taxonomy;
+#   - requires string literals, so `item.type === "Audio"` (display inspection)
+#     does not match;
+#   - uses an explicit type list rather than a generic capitalised-word pattern,
+#     so unrelated string arrays (`["High","Low"]`) produce no noise.
+#
+# An item type missing from this list is a false *negative*, never a false
+# positive — the check degrades safely as Jellyfin adds types.
+ITEM_TYPES='Movie|Series|Episode|Audio|MusicAlbum|MusicArtist|MusicVideo|Season|BoxSet|Playlist|Book|AudioBook|Video|Person|Folder|CollectionFolder|TvChannel|LiveTvChannel'
+PATTERN="\[[[:space:]]*\"($ITEM_TYPES)\"[[:space:]]*,[[:space:]]*\"($ITEM_TYPES)\""

-echo "🔎 Checking frontend for domain-taxonomy leaks (multi-type query arrays)…"
+echo "🔎 Checking frontend for domain-taxonomy leaks (item-type array literals)…"

 # Collect hits, excluding tests and the allowlist.
 violations=""
@@ -69,9 +122,11 @@ done < <(grep -rInE "$PATTERN" src/ 2>/dev/null || true)

 if [[ -n "$violations" ]]; then
  echo ""
-  echo "❌ Frontend boundary violation: a multi-type includeItemTypes query defines"
-  echo "   a category in the presentation layer. That taxonomy belongs in Rust —"
-  echo "   send an opaque scope and let the backend expand it to item types."
+  echo "❌ Frontend boundary violation: an item-type array literal defines a"
+  echo "   category in the presentation layer. That taxonomy belongs in Rust —"
+  echo "   send an opaque scope/enum and let the backend expand it to item types"
+  echo "   (see SearchScope::item_types() in src-tauri/src/repository/types.rs)."
+  echo "   Assigning the array to a const does not make it presentation."
  echo "   See docs/specs/scoped-search-boundary.md and CLAUDE.md."
  echo ""
  echo "$violations" | sed 's/^/   /'
@@ -1,84 +0,0 @@
-#!/bin/bash
-#
-# Requirements Coverage Checker
-# Extracts @req tags from codebase and compares with README.md
-#
-
-set -e
-
-REQUIREMENTS_FILE="README.md"
-SOURCE_DIRS="src-tauri/ src/"
-
-echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-echo "  Requirements Coverage Report"
-echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-echo ""
-
-# Extract requirement IDs from README.md (UR-, IR-, DR-, JA-)
-echo "📊 Scanning requirements from $REQUIREMENTS_FILE..."
-requirements=$(grep -E "^\| (UR|IR|DR|JA)-[0-9]+" "$REQUIREMENTS_FILE" | \
-               sed -E 's/^\| ([A-Z]+-[0-9]+).*/\1/' | \
-               sort -u)
-
-total_reqs=$(echo "$requirements" | wc -l)
-implemented=0
-partial=0
-planned=0
-missing=0
-
-echo ""
-echo "Category Breakdown:"
-echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-
-for category in UR IR DR JA; do
-    cat_count=$(echo "$requirements" | grep "^$category-" | wc -l)
-    printf "%-4s %3d requirements\n" "$category:" "$cat_count"
-done
-
-echo ""
-echo "Implementation Status:"
-echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-
-for req in $requirements; do
-    # Count full implementations
-    full_count=$(grep -r "@req: $req" $SOURCE_DIRS 2>/dev/null | grep -v "@req-partial" | grep -v "@req-planned" | wc -l)
-
-    # Count partial implementations
-    partial_count=$(grep -r "@req-partial: $req" $SOURCE_DIRS 2>/dev/null | wc -l)
-
-    # Count planned
-    planned_count=$(grep -r "@req-planned: $req" $SOURCE_DIRS 2>/dev/null | wc -l)
-
-    if [ "$full_count" -gt 0 ]; then
-        echo "✅ $req: $full_count implementation(s)"
-        ((implemented++))
-    elif [ "$partial_count" -gt 0 ]; then
-        echo "🔶 $req: $partial_count partial implementation(s)"
-        ((partial++))
-    elif [ "$planned_count" -gt 0 ]; then
-        echo "📋 $req: Planned (not yet implemented)"
-        ((planned++))
-    else
-        echo "❌ $req: No implementation found"
-        ((missing++))
-    fi
-done
-
-echo ""
-echo "Summary:"
-echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-printf "Total Requirements:     %3d\n" "$total_reqs"
-printf "✅ Fully Implemented:   %3d (%.0f%%)\n" "$implemented" "$(echo "scale=0; $implemented * 100 / $total_reqs" | bc)"
-printf "🔶 Partially Implemented: %3d (%.0f%%)\n" "$partial" "$(echo "scale=0; $partial * 100 / $total_reqs" | bc)"
-printf "📋 Planned:             %3d (%.0f%%)\n" "$planned" "$(echo "scale=0; $planned * 100 / $total_reqs" | bc)"
-printf "❌ Missing:             %3d (%.0f%%)\n" "$missing" "$(echo "scale=0; $missing * 100 / $total_reqs" | bc)"
-echo ""
-
-# Exit code based on missing critical requirements
-if [ "$missing" -gt 0 ]; then
-    echo "⚠️  Warning: $missing requirements have no implementation"
-    exit 1
-else
-    echo "✨ All requirements have implementations!"
-    exit 0
-fi
@@ -1,40 +0,0 @@
-#!/bin/bash
-#
-# Test Coverage Report
-# Links test requirements to implementations
-#
-
-echo "Test Coverage Report"
-echo "===================="
-echo ""
-
-test_reqs=$(grep -rh "@req-test:" src-tauri/ 2>/dev/null | \
-            sed 's/.*@req-test: \([A-Z][A-Z]-[0-9]*\).*/\1/' | \
-            sort -u)
-
-total_tests=0
-covered=0
-uncovered=0
-
-for req in $test_reqs; do
-    test_count=$(grep -r "@req-test: $req" src-tauri/ 2>/dev/null | wc -l)
-    impl_count=$(grep -r "@req: $req" src-tauri/ src/ 2>/dev/null | wc -l)
-
-    ((total_tests++))
-
-    if [ "$test_count" -gt 0 ] && [ "$impl_count" -gt 0 ]; then
-        echo "✅ $req: $test_count test(s), $impl_count implementation(s)"
-        ((covered++))
-    elif [ "$impl_count" -eq 0 ]; then
-        echo "⚠️  $req: $test_count test(s) but no implementation"
-        ((uncovered++))
-    fi
-done
-
-echo ""
-echo "Summary:"
-echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-printf "Total Test Requirements: %3d\n" "$total_tests"
-printf "✅ With Implementation:  %3d (%.0f%%)\n" "$covered" "$(echo "scale=0; $covered * 100 / $total_tests" | bc)"
-printf "⚠️  No Implementation:   %3d (%.0f%%)\n" "$uncovered" "$(echo "scale=0; $uncovered * 100 / $total_tests" | bc)"
-echo ""
@@ -0,0 +1,182 @@
+/**
+ * Tests for the traceability coverage computation.
+ *
+ * These run over fixture strings rather than the live docs/requirements.md, so
+ * their meaning does not drift as requirements are added.
+ *
+ * Background: the CI gate divided traced-requirement counts by hardcoded
+ * denominators (UR/39, IR/24, DR/48, JA/3, total 114) that had fallen out of
+ * date, reporting 158% coverage and making the 50% threshold unreachable. These
+ * tests pin the parsing and arithmetic that replace those literals.
+ *
+ * @req-test: UT-089 - Requirement definitions parsed from requirements.md
+ * @req-test: UT-090 - Coverage is the intersection of traced and defined IDs
+ */
+
+import { describe, it, expect } from "vitest";
+import { countDefinedRequirements, computeCoverage } from "./extract-traces";
+
+describe("countDefinedRequirements", () => {
+  it("counts a well-formed table row as a defined requirement", () => {
+    const md = `
+| ID | Requirement | Priority | Status |
+|----|-------------|----------|--------|
+| UR-001 | Run the app on multiple platforms | High | In Progress |
+| UR-002 | Access media when online or offline | High | Done |
+`;
+    const defined = countDefinedRequirements(md);
+    expect(defined.UR).toBe(2);
+    expect(defined.DR).toBe(0);
+  });
+
+  it("does not count IDs that appear only in the Traces To column", () => {
+    // The bug this rule avoids: a naive grep for /DR-\d{3}/ over the whole file
+    // counts DR-001 here as "defined", inflating the denominator with IDs that
+    // are merely referenced.
+    const md = `
+| DR-001 | Player state machine | Player | UR-005 | Done |
+| DR-002 | MediaItem struct | Player | UR-003, UR-004 | Done |
+`;
+    const defined = countDefinedRequirements(md);
+    expect(defined.DR).toBe(2);
+    // UR-005/UR-003/UR-004 are referenced, never defined here.
+    expect(defined.UR).toBe(0);
+  });
+
+  it("does not count IDs mentioned in prose", () => {
+    const md = `
+Some prose explaining that UR-005 relates to DR-001 and JA-002.
+
+| UR-005 | Control media playback | High | Done |
+`;
+    const defined = countDefinedRequirements(md);
+    expect(defined.UR).toBe(1);
+    expect(defined.DR).toBe(0);
+    expect(defined.JA).toBe(0);
+  });
+
+  it("deduplicates an ID listed in both the spec table and the traceability matrix", () => {
+    // requirements.md lists every UR twice: once in §1 (definition) and again in
+    // §3 (traceability matrix), both as a leading table cell. Counting rows
+    // instead of unique IDs double-counts the UR denominator (121 vs 61).
+    const md = `
+| UR-005 | Control media playback | High | Done |
+| UR-006 | Browse the library | High | Done |
+
+### Traceability Matrix
+
+| UR-005 | - | DR-001, DR-005, DR-009 |
+| UR-006 | - | DR-012 |
+`;
+    const defined = countDefinedRequirements(md);
+    expect(defined.UR).toBe(2);
+  });
+
+  it("collects the defined ID set, not just counts", () => {
+    const md = `
+| UR-001 | A | High | Done |
+| DR-050 | B | Player | UR-001 | Done |
+`;
+    const defined = countDefinedRequirements(md);
+    expect(defined.ids.has("UR-001")).toBe(true);
+    expect(defined.ids.has("DR-050")).toBe(true);
+    expect(defined.ids.has("UR-999")).toBe(false);
+  });
+});
+
+describe("computeCoverage", () => {
+  const defined = {
+    UR: 2,
+    IR: 0,
+    DR: 2,
+    JA: 0,
+    total: 4,
+    ids: new Set(["UR-001", "UR-002", "DR-001", "DR-002"]),
+  };
+
+  it("computes coverage as traced ∩ defined over defined", () => {
+    const traced = ["UR-001", "DR-001"];
+    const cov = computeCoverage(traced, defined);
+    expect(cov.covered).toBe(2);
+    expect(cov.total).toBe(4);
+    expect(cov.percent).toBe(50);
+  });
+
+  it("does not let a traced-but-undefined ID inflate the numerator", () => {
+    // This is how a ratio exceeds 100%: a TRACES comment naming a typo'd or
+    // deleted requirement counted as covered.
+    const traced = ["UR-001", "DR-001", "DR-097"];
+    const cov = computeCoverage(traced, defined);
+    expect(cov.covered).toBe(2);
+    expect(cov.percent).toBe(50);
+  });
+
+  it("reports traced-but-undefined IDs as orphaned so they get fixed", () => {
+    const traced = ["UR-001", "DR-097", "JA-404"];
+    const cov = computeCoverage(traced, defined);
+    expect(cov.orphaned).toEqual(["DR-097", "JA-404"]);
+  });
+
+  it("has no orphans when every traced ID is defined", () => {
+    const cov = computeCoverage(["UR-001", "UR-002"], defined);
+    expect(cov.orphaned).toEqual([]);
+  });
+
+  it("ignores UT/IT test IDs entirely — they are a separate taxonomy", () => {
+    // UT/IT are defined in §4 of requirements.md, not among the four
+    // requirement types. Treating them as orphans buries real typos in ~60
+    // lines of noise, and counting them would corrupt the ratio.
+    const cov = computeCoverage(["UR-001", "UT-088", "IT-017"], defined);
+    expect(cov.orphaned).toEqual([]);
+    expect(cov.covered).toBe(1);
+  });
+
+  it("reports 0% rather than dividing by zero for an empty trace set", () => {
+    const cov = computeCoverage([], defined);
+    expect(cov.covered).toBe(0);
+    expect(cov.percent).toBe(0);
+  });
+
+  it("reports 0% rather than NaN when nothing is defined", () => {
+    const empty = { UR: 0, IR: 0, DR: 0, JA: 0, total: 0, ids: new Set<string>() };
+    const cov = computeCoverage([], empty);
+    expect(cov.percent).toBe(0);
+    expect(Number.isNaN(cov.percent)).toBe(false);
+  });
+
+  it("reports exactly 100% when all defined requirements are traced, never above", () => {
+    const traced = ["UR-001", "UR-002", "DR-001", "DR-002"];
+    const cov = computeCoverage(traced, defined);
+    expect(cov.percent).toBe(100);
+  });
+
+  it("ignores duplicate traced IDs", () => {
+    const traced = ["UR-001", "UR-001", "UR-001"];
+    const cov = computeCoverage(traced, defined);
+    expect(cov.covered).toBe(1);
+  });
+});
+
+describe("live requirements.md", () => {
+  it("parses the real file to the counts the CI gate must use", () => {
+    // Guards the specific regression: CI hardcoded UR/39, IR/24, DR/48, JA/3
+    // (total 114) while the real file had grown to 211. Update these numbers
+    // deliberately when requirements are added — that edit is the signal the
+    // denominator is live rather than frozen.
+    const fs = require("fs");
+    const path = require("path");
+    // import.meta.dir is Bun-only; derive from import.meta.url under vitest.
+    const here = path.dirname(new URL(import.meta.url).pathname);
+    const md = fs.readFileSync(
+      path.resolve(here, "../docs/requirements.md"),
+      "utf-8"
+    );
+    const defined = countDefinedRequirements(md);
+
+    expect(defined.UR).toBe(61);
+    expect(defined.IR).toBe(29);
+    expect(defined.DR).toBe(96);
+    expect(defined.JA).toBe(32);
+    expect(defined.total).toBe(218);
+  });
+});
@@ -34,11 +34,20 @@ interface TracesData {
    DR: string[];
    JA: string[];
  };
+  /** Requirements *defined* in requirements.md — the coverage denominators. */
+  defined?: { UR: number; IR: number; DR: number; JA: number; total: number };
+  coverage?: CoverageResult;
 }

 // Repo root, derived from this script's location (scripts/ -> repo root).
 // Must NOT be hardcoded to a developer's machine, or CI checkouts see no files.
-const BASE_DIR = path.resolve(import.meta.dir, "..");
+//
+// `import.meta.dir` is a Bun extension and is undefined when this module is
+// imported by vitest (which runs it as an ordinary ESM module), so fall back to
+// import.meta.url — this file must stay importable for extract-traces.test.ts.
+const SCRIPT_DIR =
+  import.meta.dir ?? path.dirname(new URL(import.meta.url).pathname);
+const BASE_DIR = path.resolve(SCRIPT_DIR, "..");

 const TRACES_PATTERN = /TRACES:\s*([^\n]+)/gi;
 const REQ_ID_PATTERN = /([A-Z]{2})-(\d{3})/g;
@@ -50,7 +59,10 @@ function extractRequirementIds(tracesString: string): string[] {

 function getAllSourceFiles(): string[] {
  const baseDir = BASE_DIR;
-  const patterns = ["src", "src-tauri/src"];
+  // `scripts` is scanned too: build tooling implements requirements (e.g.
+  // DR-093, the coverage engine itself) and would otherwise be invisible to the
+  // very matrix it generates.
+  const patterns = ["src", "src-tauri/src", "scripts"];
  const files: string[] = [];

  function walkDir(dir: string) {
@@ -192,6 +204,109 @@ function extractTraces(): TracesData {
  };
 }

+// ---------------------------------------------------------------------------
+// Coverage: how many *defined* requirements are actually traced.
+//
+// The denominators MUST be derived from requirements.md, never hardcoded. The
+// CI gate previously divided by frozen literals (UR/39, IR/24, DR/48, JA/3,
+// total 114) while the real file had grown to 211 requirements, so it reported
+// 158% coverage and the 50% threshold became unreachable — the gate could not
+// fail. See docs/specs/traceability-gate-repair.md.
+//
+// TRACES: | DR-093
+// ---------------------------------------------------------------------------
+
+export interface DefinedRequirements {
+  UR: number;
+  IR: number;
+  DR: number;
+  JA: number;
+  total: number;
+  ids: Set<string>;
+}
+
+export interface CoverageResult {
+  covered: number;
+  total: number;
+  percent: number;
+  /** Traced in code but not defined in requirements.md (typo, or deleted req). */
+  orphaned: string[];
+}
+
+/**
+ * A requirement is *defined* only where its ID is the leading cell of a markdown
+ * table row: `| DR-001 | … |`.
+ *
+ * This deliberately ignores IDs in the "Traces To" column and in prose — a
+ * naive scan for /DR-\d{3}/ counts those as definitions and inflates the
+ * denominator. IDs are deduplicated because requirements.md lists each UR twice
+ * (once in §1 as a definition, again in §3's traceability matrix), which would
+ * otherwise double the UR count from 61 to 121.
+ *
+ * TRACES: | DR-093
+ */
+export function countDefinedRequirements(markdown: string): DefinedRequirements {
+  const ids = new Set<string>();
+  const ROW_ID = /^\|\s*(UR|IR|DR|JA)-(\d{3})\s*\|/;
+
+  for (const line of markdown.split("\n")) {
+    const match = line.match(ROW_ID);
+    if (match) ids.add(`${match[1]}-${match[2]}`);
+  }
+
+  const countOf = (type: string) =>
+    [...ids].filter((id) => id.startsWith(`${type}-`)).length;
+
+  return {
+    UR: countOf("UR"),
+    IR: countOf("IR"),
+    DR: countOf("DR"),
+    JA: countOf("JA"),
+    total: ids.size,
+    ids,
+  };
+}
+
+/**
+ * Coverage is the *intersection* of traced and defined IDs over defined IDs.
+ *
+ * Using the raw traced count as the numerator is what lets a ratio exceed 100%:
+ * a TRACES comment naming a requirement that no longer exists would count as
+ * covered. Those IDs are reported as `orphaned` so they get fixed rather than
+ * silently counted or silently dropped.
+ *
+ * TRACES: | DR-093
+ */
+export function computeCoverage(
+  tracedIds: string[],
+  defined: DefinedRequirements
+): CoverageResult {
+  // Only the four *requirement* types participate in coverage. UT/IT are test
+  // identifiers defined in §4 of requirements.md — a different taxonomy, and
+  // flagging them as orphans would bury real typos in ~60 lines of noise.
+  const isRequirement = (id: string) => /^(UR|IR|DR|JA)-\d{3}$/.test(id);
+
+  const traced = new Set(tracedIds.filter(isRequirement));
+  const covered = [...traced].filter((id) => defined.ids.has(id));
+  const orphaned = [...traced].filter((id) => !defined.ids.has(id)).sort();
+
+  return {
+    covered: covered.length,
+    total: defined.total,
+    percent:
+      defined.total === 0
+        ? 0
+        : Math.round((covered.length / defined.total) * 100),
+    orphaned,
+  };
+}
+
+/** Read requirements.md from the repo and count what it defines. */
+export function readDefinedRequirements(): DefinedRequirements {
+  const reqPath = path.join(BASE_DIR, "docs", "requirements.md");
+  return countDefinedRequirements(fs.readFileSync(reqPath, "utf-8"));
+}
+
 function generateMarkdown(data: TracesData): string {
  let md = `# Code Traceability Matrix

@@ -265,21 +380,83 @@ function generateJson(data: TracesData): string {
  return JSON.stringify(data, null, 2);
 }

-// Main
-const args = Bun.argv.slice(2);
-const format = args.includes("--format")
+/**
+ * Human-readable coverage report; exits non-zero below the threshold so this is
+ * runnable as a local gate (`bun run traces:coverage`), not just in CI.
+ *
+ * TRACES: | DR-093
+ */
+function reportCoverage(data: TracesData, minThreshold: number): number {
+  const defined = data.defined!;
+  const cov = data.coverage!;
+
+  const definedIds = readDefinedRequirements().ids;
+
+  console.log("📋 Requirement coverage (traced / defined):");
+  for (const type of ["UR", "IR", "DR", "JA"] as const) {
+    const traced = data.byType[type].filter((id) => definedIds.has(id)).length;
+    console.log(`   ${type}: ${traced} / ${defined[type]}`);
+  }
+  console.log("");
+  console.log(`📈 Overall: ${cov.covered} / ${cov.total} (${cov.percent}%)`);
+
+  if (cov.orphaned.length > 0) {
+    console.log("");
+    console.log(
+      `⚠️  Traced but not defined in requirements.md: ${cov.orphaned.join(", ")}`
+    );
+    console.log("   Fix the TRACES comment or add the requirement.");
+  }
+
+  // A ratio above 100% means the computation is broken (the condition that hid
+  // the stale-denominator bug for so long). Fail loudly rather than report it.
+  if (cov.percent > 100) {
+    console.log("");
+    console.log(`❌ Coverage > 100% — the gate is miscomputing.`);
+    return 1;
+  }
+
+  if (cov.percent < minThreshold) {
+    console.log("");
+    console.log(`❌ Coverage (${cov.percent}%) is below minimum (${minThreshold}%)`);
+    return 1;
+  }
+
+  console.log("");
+  console.log(`✅ Coverage is acceptable (${cov.percent}% >= ${minThreshold}%)`);
+  return 0;
+}
+
+// Main — guarded so this module stays importable from extract-traces.test.ts.
+if (import.meta.main) {
+  const args = process.argv.slice(2);
+  const format = args.includes("--format")
    ? args[args.indexOf("--format") + 1]
    : "markdown";

-console.error("🔍 Extracting TRACES from codebase...");
-const data = extractTraces();
+  console.error("🔍 Extracting TRACES from codebase...");
+  const data = extractTraces();

-if (format === "json") {
+  const defined = readDefinedRequirements();
+  const allTraced = Object.keys(data.requirements);
+  data.defined = {
+    UR: defined.UR,
+    IR: defined.IR,
+    DR: defined.DR,
+    JA: defined.JA,
+    total: defined.total,
+  };
+  data.coverage = computeCoverage(allTraced, defined);
+
+  if (format === "json") {
    console.log(generateJson(data));
-} else {
+  } else if (format === "coverage") {
+    process.exit(reportCoverage(data, 50));
+  } else {
    console.log(generateMarkdown(data));
-}
+  }

-console.error(
+  console.error(
    `\n✅ Complete! Found ${data.totalTraces} TRACES across ${data.totalFiles} files`
-);
+  );
+}
@@ -1,56 +0,0 @@
-#!/bin/bash
-#
-# Find all files implementing a specific requirement
-#
-# Usage: ./find-req-implementations.sh UR-004
-#
-
-if [ $# -eq 0 ]; then
-    echo "Usage: $0 <REQUIREMENT_ID>"
-    echo "Example: $0 UR-004"
-    exit 1
-fi
-
-REQ_ID=$1
-
-echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-echo "  Implementations of $REQ_ID"
-echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-echo ""
-
-# Full implementations
-echo "Full Implementations:"
-echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-grep -rn "@req: $REQ_ID" src-tauri/ src/ 2>/dev/null | \
-    grep -v "@req-partial" | \
-    grep -v "@req-planned" | \
-    sed 's/src-tauri\/src\///' | \
-    sed 's/src\///' || echo "  (none)"
-
-echo ""
-
-# Partial implementations
-echo "Partial Implementations:"
-echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-grep -rn "@req-partial: $REQ_ID" src-tauri/ src/ 2>/dev/null | \
-    sed 's/src-tauri\/src\///' | \
-    sed 's/src\///' || echo "  (none)"
-
-echo ""
-
-# Planned
-echo "Planned Implementations:"
-echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-grep -rn "@req-planned: $REQ_ID" src-tauri/ src/ 2>/dev/null | \
-    sed 's/src-tauri\/src\///' | \
-    sed 's/src\///' || echo "  (none)"
-
-echo ""
-
-# Tests
-echo "Test Cases:"
-echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-grep -rn "@req-test: $REQ_ID" src-tauri/ 2>/dev/null | \
-    sed 's/src-tauri\/src\///' || echo "  (none)"
-
-echo ""
@@ -7,7 +7,7 @@ echo "🧪 Running all tests..."
 echo ""

 echo "📦 Running frontend tests..."
-bun run test
+bun run test --run

 echo ""
 echo "🦀 Running Rust tests..."
@@ -15,5 +15,12 @@ cd src-tauri
 cargo test
 cd ..

+echo ""
+echo "🚧 Checking architectural gates..."
+# Boundary tripwire (DR-094): no Jellyfin taxonomy in the presentation layer.
+bun run check:boundary
+# Traceability coverage (DR-093): fails below 50%, or above 100% (miscount).
+bun run traces:coverage
+
 echo ""
 echo "✅ All tests passed!"
@@ -1994,7 +1994,7 @@ dependencies = [

 [[package]]
 name = "jellytau"
-version = "0.2.0"
+version = "0.2.8"
 dependencies = [
 "aes-gcm",
 "async-trait",
@@ -1,6 +1,6 @@
 [package]
 name = "jellytau"
-version = "0.2.0"
+version = "0.2.8"
 description = "A Tauri App"
 authors = ["you"]
 edition = "2021"
@@ -395,7 +395,12 @@ pub struct SearchUpdateEvent {
    pub result: SearchResult,
 }

-/// Search for items
+/// Search for items.
+///
+/// Resolves `SearchOptions::scope` into concrete Jellyfin item types before
+/// dispatching, so scope taxonomy stays in Rust.
+///
+/// TRACES: UR-049, UR-050 | DR-063
 #[tauri::command]
 #[specta::specta]
 pub async fn repository_search(
@@ -408,6 +413,16 @@ pub async fn repository_search(
 ) -> Result<SearchResult, String> {
    let repo = manager.0.get(&handle).ok_or("Repository not found")?;

+    // Expand the opaque scope into item types HERE — once, before the cache and
+    // server paths diverge — so both phases filter identically. Doing it later
+    // (or in only one path) makes offline results disagree with online ones.
+    // The frontend sends `scope` and never names a Jellyfin item type for
+    // search; see docs/specs/scoped-search-boundary.md.
+    let options = options.map(|mut o| {
+        o.resolve_scope();
+        o
+    });
+
    // Phase 1: instant local results from the cache (downloaded content) so the
    // UI can render immediately while the server is still being queried.
    let mut cache_result = repo
@@ -152,6 +152,17 @@ pub struct PlayerController {

    // Auto-play episode counter (session-based, resets on manual play)
    autoplay_episode_count: Arc<Mutex<u32>>,
+
+    // Last state reported by a webview-rendered HTML5 <video>/<audio> element.
+    //
+    // Webview-rendered media is played by an element the native backend cannot
+    // reach, so the backend's own state() says nothing about it. Tracking the
+    // REPORTED state here is what lets transport (play/pause/toggle) be decided
+    // in Rust for that media instead of the frontend reading `el.paused` off the
+    // DOM — a value that flips transiently while buffering/seeking and caused
+    // competing intents to take opposing actions. `None` means no webview media
+    // is active and the native backend is authoritative. See DR-097.
+    html5_playing: Arc<Mutex<Option<bool>>>,
 }

 impl PlayerController {
@@ -174,6 +185,7 @@ impl PlayerController {
            position_throttler,
            end_reason: Arc::new(Mutex::new(None)),
            autoplay_episode_count: Arc::new(Mutex::new(0)),
+            html5_playing: Arc::new(Mutex::new(None)),
        };

        // Start background timer thread for sleep timer countdown
@@ -476,21 +488,72 @@ impl PlayerController {
        Ok(())
    }

+    /// True while webview-rendered media (HTML5 `<video>`/`<audio>`) is the real
+    /// player, so transport must be routed to it rather than the native backend.
+    ///
+    /// TRACES: UR-005 | DR-097
+    pub fn is_html5_active(&self) -> bool {
+        self.html5_playing.lock_safe().is_some()
+    }
+
+    /// Whether the webview element last reported itself as playing. Meaningless
+    /// unless [`Self::is_html5_active`] is true.
+    ///
+    /// TRACES: UR-005 | DR-097
+    pub fn html5_is_playing(&self) -> bool {
+        self.html5_playing.lock_safe().unwrap_or(false)
+    }
+
+    /// Send a transport intent to the webview element that is rendering media.
+    fn emit_html5_control(&self, action: &str) {
+        if let Some(emitter) = self.event_emitter.lock_safe().as_ref() {
+            emitter.emit(PlayerStatusEvent::ControlCommand {
+                action: action.to_string(),
+                position: None,
+            });
+        }
+    }
+
    /// Play/resume playback
    pub fn play(&self) -> Result<(), PlayerError> {
        debug!("[PlayerController] play");
+        // Webview-rendered media: the native backend isn't playing it, so drive
+        // the element via a ControlCommand instead (DR-097).
+        if self.is_html5_active() {
+            self.emit_html5_control("play");
+            return Ok(());
+        }
        let mut backend = self.backend.lock_safe();
        backend.play()
    }

    /// Pause playback
    pub fn pause(&self) -> Result<(), PlayerError> {
+        if self.is_html5_active() {
+            self.emit_html5_control("pause");
+            return Ok(());
+        }
        let mut backend = self.backend.lock_safe();
        backend.pause()
    }

-    /// Toggle play/pause
+    /// Toggle play/pause.
+    ///
+    /// The decision is made HERE, from authoritative state — the reported webview
+    /// state for HTML5-rendered media, or the native backend's state otherwise.
+    /// The frontend must never decide this from the DOM (see DR-097).
+    ///
+    /// TRACES: UR-005 | DR-097
    pub fn toggle_playback(&self) -> Result<(), PlayerError> {
+        if self.is_html5_active() {
+            let action = if self.html5_is_playing() {
+                "pause"
+            } else {
+                "play"
+            };
+            self.emit_html5_control(action);
+            return Ok(());
+        }
        let mut backend = self.backend.lock_safe();
        if backend.state().is_playing() {
            backend.pause()
@@ -890,6 +953,23 @@ impl PlayerController {
    /// Re-emits a `StateChanged` event identical to what MpvBackend/ExoPlayer
    /// would emit, so `playerEvents.ts` needs no HTML5-specific branch.
    pub fn report_html5_state(&self, state: String, media_id: Option<String>) {
+        // Track it: this is the authoritative play/pause state for
+        // webview-rendered media, and what transport decisions read (DR-097).
+        // "stopped"/"idle" mean the element is gone, so hand authority back to
+        // the native backend — otherwise music playback would keep emitting
+        // ControlCommands at a element that no longer exists.
+        {
+            let mut tracked = self.html5_playing.lock_safe();
+            *tracked = match state.as_str() {
+                "playing" => Some(true),
+                // "loading" counts as active-but-not-playing so a toggle during
+                // load resolves to "play" rather than falling through to the
+                // native backend.
+                "paused" | "loading" => Some(false),
+                // "stopped"/"idle": element is gone, native backend resumes authority.
+                _ => None,
+            };
+        }
        if let Some(emitter) = self.event_emitter.lock_safe().as_ref() {
            emitter.emit(PlayerStatusEvent::StateChanged { state, media_id });
        }
@@ -1489,6 +1569,156 @@ mod tests {
        }
    }

+    // ===== HTML5 transport authority (DR-097) =====
+    //
+    // Webview-rendered video is played by an element the native backend cannot
+    // reach, so transport for it must be decided from the state the element
+    // REPORTS and executed by emitting a ControlCommand. Previously the frontend
+    // decided play-vs-pause itself by reading `el.paused` off the DOM, which
+    // flips transiently while buffering/seeking — two intents ~150ms apart read
+    // different values, took opposing actions, and self-sustained a pause loop.
+
+    #[test]
+    fn test_html5_state_is_tracked_from_reports() {
+        let controller = PlayerController::default();
+        let emitter = Arc::new(CapturingEmitter::new());
+        controller.set_event_emitter(emitter.clone());
+
+        // No HTML5 media reported yet: the native backend stays authoritative.
+        assert!(!controller.is_html5_active());
+
+        controller.report_html5_state("playing".to_string(), Some("item-1".to_string()));
+        assert!(controller.is_html5_active());
+        assert!(controller.html5_is_playing());
+
+        controller.report_html5_state("paused".to_string(), Some("item-1".to_string()));
+        assert!(controller.is_html5_active());
+        assert!(!controller.html5_is_playing());
+    }
+
+    #[test]
+    fn test_html5_toggle_from_paused_emits_play_control() {
+        let controller = PlayerController::default();
+        let emitter = Arc::new(CapturingEmitter::new());
+        controller.set_event_emitter(emitter.clone());
+        controller.report_html5_state("paused".to_string(), Some("item-1".to_string()));
+
+        controller.toggle_playback().unwrap();
+
+        let controls: Vec<_> = emitter
+            .events()
+            .into_iter()
+            .filter_map(|e| match e {
+                PlayerStatusEvent::ControlCommand { action, .. } => Some(action),
+                _ => None,
+            })
+            .collect();
+        assert_eq!(controls, vec!["play".to_string()]);
+    }
+
+    #[test]
+    fn test_html5_toggle_from_playing_emits_pause_control() {
+        let controller = PlayerController::default();
+        let emitter = Arc::new(CapturingEmitter::new());
+        controller.set_event_emitter(emitter.clone());
+        controller.report_html5_state("playing".to_string(), Some("item-1".to_string()));
+
+        controller.toggle_playback().unwrap();
+
+        let controls: Vec<_> = emitter
+            .events()
+            .into_iter()
+            .filter_map(|e| match e {
+                PlayerStatusEvent::ControlCommand { action, .. } => Some(action),
+                _ => None,
+            })
+            .collect();
+        assert_eq!(controls, vec!["pause".to_string()]);
+    }
+
+    #[test]
+    fn test_html5_repeated_toggles_alternate_and_never_repeat_an_action() {
+        // The loop signature: two intents in quick succession must NOT both
+        // resolve the same way, and must not produce opposing actions from a
+        // stale read. Rust's own tracked state makes the sequence deterministic
+        // as long as the element reports back between intents.
+        let controller = PlayerController::default();
+        let emitter = Arc::new(CapturingEmitter::new());
+        controller.set_event_emitter(emitter.clone());
+        controller.report_html5_state("playing".to_string(), Some("item-1".to_string()));
+
+        controller.toggle_playback().unwrap();
+        // Element confirms the pause it was told to do.
+        controller.report_html5_state("paused".to_string(), Some("item-1".to_string()));
+        controller.toggle_playback().unwrap();
+
+        let controls: Vec<_> = emitter
+            .events()
+            .into_iter()
+            .filter_map(|e| match e {
+                PlayerStatusEvent::ControlCommand { action, .. } => Some(action),
+                _ => None,
+            })
+            .collect();
+        assert_eq!(controls, vec!["pause".to_string(), "play".to_string()]);
+    }
+
+    #[test]
+    fn test_html5_play_and_pause_emit_control_commands() {
+        let controller = PlayerController::default();
+        let emitter = Arc::new(CapturingEmitter::new());
+        controller.set_event_emitter(emitter.clone());
+        controller.report_html5_state("paused".to_string(), Some("item-1".to_string()));
+
+        controller.play().unwrap();
+        controller.pause().unwrap();
+
+        let controls: Vec<_> = emitter
+            .events()
+            .into_iter()
+            .filter_map(|e| match e {
+                PlayerStatusEvent::ControlCommand { action, .. } => Some(action),
+                _ => None,
+            })
+            .collect();
+        assert_eq!(controls, vec!["play".to_string(), "pause".to_string()]);
+    }
+
+    #[test]
+    fn test_html5_stopped_report_releases_transport_to_native_backend() {
+        // When webview video goes away, transport must fall back to the native
+        // backend (music playback must not keep emitting ControlCommands).
+        let controller = PlayerController::default();
+        let emitter = Arc::new(CapturingEmitter::new());
+        controller.set_event_emitter(emitter.clone());
+
+        controller.report_html5_state("playing".to_string(), Some("item-1".to_string()));
+        assert!(controller.is_html5_active());
+
+        controller.report_html5_state("stopped".to_string(), None);
+        assert!(!controller.is_html5_active());
+    }
+
+    #[test]
+    fn test_html5_transport_emits_exactly_one_control_per_intent() {
+        // Guards against a double-drive on platforms where the *backend* is also
+        // webview-based (WebviewAudioBackend on Windows): the html5 short-circuit
+        // must replace the backend call, not run in addition to it.
+        let controller = PlayerController::default();
+        let emitter = Arc::new(CapturingEmitter::new());
+        controller.set_event_emitter(emitter.clone());
+        controller.report_html5_state("playing".to_string(), Some("item-1".to_string()));
+
+        controller.pause().unwrap();
+
+        let controls = emitter
+            .events()
+            .into_iter()
+            .filter(|e| matches!(e, PlayerStatusEvent::ControlCommand { .. }))
+            .count();
+        assert_eq!(controls, 1, "one intent must produce exactly one control");
+    }
+
    #[test]
    fn test_controller_volume_default() {
        let controller = PlayerController::default();
@@ -294,6 +294,53 @@ pub struct GetItemsOptions {
    pub genres: Option<Vec<String>>,
 }

+/// An opaque search scope the frontend selects; Rust owns what it *means*.
+///
+/// The expansion table below is Jellyfin domain vocabulary: it changes when
+/// Jellyfin adds or renames an item type, never when the UI is redesigned. It
+/// previously lived in the frontend (`searchScope.ts`), which is the boundary
+/// leak documented in docs/specs/scoped-search-boundary.md. The frontend now
+/// sends the enum and never names an item type in connection with search.
+///
+/// TRACES: UR-049 | DR-063
+#[derive(specta::Type, Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub enum SearchScope {
+    All,
+    Music,
+    Movies,
+    Tv,
+}
+
+impl SearchScope {
+    /// The Jellyfin item types this scope requests, or `None` for `All`.
+    ///
+    /// `All` returns `None` rather than the union of every listed type on
+    /// purpose: an explicit `includeItemTypes` list filters out anything not
+    /// named in it, so a union would silently drop People, folders and any type
+    /// nobody enumerated. Callers must omit the filter entirely on `None`.
+    ///
+    /// TRACES: UR-049 | DR-063
+    pub fn item_types(self) -> Option<Vec<String>> {
+        match self {
+            SearchScope::All => None,
+            SearchScope::Music => Some(
+                ["MusicAlbum", "MusicArtist", "Audio", "Playlist"]
+                    .into_iter()
+                    .map(String::from)
+                    .collect(),
+            ),
+            SearchScope::Movies => Some(vec!["Movie".to_string()]),
+            SearchScope::Tv => Some(
+                ["Series", "Episode"]
+                    .into_iter()
+                    .map(String::from)
+                    .collect(),
+            ),
+        }
+    }
+}
+
 /// Options for search queries
 #[derive(specta::Type, Debug, Clone, Serialize, Deserialize, Default)]
 #[serde(rename_all = "camelCase")]
@@ -304,6 +351,28 @@ pub struct SearchOptions {
    pub include_item_types: Option<Vec<String>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub search_term: Option<String>,
+    /// Opaque scope selected by the UI. When set it **wins** over
+    /// `include_item_types`, which remains for the non-search `get_items`
+    /// callers that legitimately request a single concrete type.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub scope: Option<SearchScope>,
+}
+
+impl SearchOptions {
+    /// Expand `scope` into `include_item_types` in place.
+    ///
+    /// Call this once, in the search command, *before* dispatching to the
+    /// cache and server paths — both already honour `include_item_types`, and
+    /// resolving in one place keeps online and offline results identical.
+    ///
+    /// TRACES: UR-049 | DR-063
+    pub fn resolve_scope(&mut self) {
+        if let Some(scope) = self.scope {
+            // `All` yields None, which clears the filter — the correct
+            // behaviour, not an omission.
+            self.include_item_types = scope.item_types();
+        }
+    }
 }

 /// Playback information
@@ -455,6 +524,131 @@ impl MeaningfulContent for PlaylistCreatedResult {
    }
 }

+#[cfg(test)]
+mod search_scope_tests {
+    use super::*;
+
+    /// Music expands to the four Jellyfin types that make up the category.
+    ///
+    /// This table is the domain vocabulary that used to live in the frontend
+    /// (`searchScope.ts`'s `SCOPE_ITEM_TYPES`) — the boundary leak that
+    /// docs/specs/scoped-search-boundary.md was written about.
+    ///
+    /// @req-test: UT-089 - SearchScope expands to Jellyfin item types
+    #[test]
+    fn music_scope_expands_to_music_item_types() {
+        assert_eq!(
+            SearchScope::Music.item_types(),
+            Some(vec![
+                "MusicAlbum".to_string(),
+                "MusicArtist".to_string(),
+                "Audio".to_string(),
+                "Playlist".to_string(),
+            ])
+        );
+    }
+
+    /// @req-test: UT-089 - SearchScope expands to Jellyfin item types
+    #[test]
+    fn movies_scope_expands_to_movie_only() {
+        assert_eq!(
+            SearchScope::Movies.item_types(),
+            Some(vec!["Movie".to_string()])
+        );
+    }
+
+    /// @req-test: UT-089 - SearchScope expands to Jellyfin item types
+    #[test]
+    fn tv_scope_expands_to_series_and_episode() {
+        assert_eq!(
+            SearchScope::Tv.item_types(),
+            Some(vec!["Series".to_string(), "Episode".to_string()])
+        );
+    }
+
+    /// `All` must send NO filter — not the union of the other scopes.
+    ///
+    /// Sending a union would silently drop every type nobody enumerated
+    /// (Person, folders, …), which an explicit `includeItemTypes` list filters
+    /// out. This is why `item_types()` returns Option rather than Vec.
+    ///
+    /// @req-test: UT-090 - All scope sends no item-type filter
+    #[test]
+    fn all_scope_sends_no_filter() {
+        assert_eq!(SearchScope::All.item_types(), None);
+    }
+
+    /// Scope wins over an explicitly supplied include_item_types.
+    ///
+    /// @req-test: UT-091 - Scope takes precedence over include_item_types
+    #[test]
+    fn resolve_scope_overrides_include_item_types() {
+        let mut options = SearchOptions {
+            include_item_types: Some(vec!["Movie".to_string()]),
+            scope: Some(SearchScope::Music),
+            ..Default::default()
+        };
+        options.resolve_scope();
+
+        assert_eq!(
+            options.include_item_types,
+            Some(vec![
+                "MusicAlbum".to_string(),
+                "MusicArtist".to_string(),
+                "Audio".to_string(),
+                "Playlist".to_string(),
+            ])
+        );
+    }
+
+    /// `All` clears any include_item_types so no filter reaches the query.
+    ///
+    /// @req-test: UT-090 - All scope sends no item-type filter
+    #[test]
+    fn resolve_all_scope_clears_include_item_types() {
+        let mut options = SearchOptions {
+            include_item_types: Some(vec!["Movie".to_string()]),
+            scope: Some(SearchScope::All),
+            ..Default::default()
+        };
+        options.resolve_scope();
+
+        assert_eq!(options.include_item_types, None);
+    }
+
+    /// With no scope set, include_item_types passes through untouched — the
+    /// non-search `getItems` callers rely on this.
+    ///
+    /// @req-test: UT-091 - Scope takes precedence over include_item_types
+    #[test]
+    fn resolve_without_scope_preserves_include_item_types() {
+        let mut options = SearchOptions {
+            include_item_types: Some(vec!["MusicAlbum".to_string()]),
+            scope: None,
+            ..Default::default()
+        };
+        options.resolve_scope();
+
+        assert_eq!(
+            options.include_item_types,
+            Some(vec!["MusicAlbum".to_string()])
+        );
+    }
+
+    /// The frontend sends the enum as camelCase over IPC.
+    ///
+    /// @req-test: UT-089 - SearchScope expands to Jellyfin item types
+    #[test]
+    fn scope_deserializes_from_camel_case() {
+        let options: SearchOptions =
+            serde_json::from_str(r#"{"scope": "music", "limit": 10}"#).unwrap();
+        assert!(matches!(options.scope, Some(SearchScope::Music)));
+
+        let all: SearchOptions = serde_json::from_str(r#"{"scope": "all"}"#).unwrap();
+        assert!(matches!(all.scope, Some(SearchScope::All)));
+    }
+}
+
 #[cfg(test)]
 mod tests {
    use super::*;
@@ -1,7 +1,7 @@
 {
  "$schema": "https://schema.tauri.app/config/2",
  "productName": "jellytau",
-  "version": "0.2.0",
+  "version": "0.2.8",
  "identifier": "com.dtourolle.jellytau",
  "build": {
    "beforeDevCommand": "bun run dev",
@@ -1290,7 +1290,12 @@ async repositoryGetGenres(handle: string, parentId: string | null) : Promise<Gen
    return await TAURI_INVOKE("repository_get_genres", { handle, parentId });
 },
 /**
- * Search for items
+ * Search for items.
+ * 
+ * Resolves `SearchOptions::scope` into concrete Jellyfin item types before
+ * dispatching, so scope taxonomy stays in Rust.
+ * 
+ * TRACES: UR-049, UR-050 | DR-063
 */
 async repositorySearch(handle: string, query: string, options: SearchOptions | null, requestId: number) : Promise<SearchResult> {
    return await TAURI_INVOKE("repository_search", { handle, query, options, requestId });
@@ -2517,11 +2522,29 @@ failed: number }
 /**
 * Options for search queries
 */
-export type SearchOptions = { limit?: number | null; includeItemTypes?: string[] | null; searchTerm?: string | null }
+export type SearchOptions = { limit?: number | null; includeItemTypes?: string[] | null; searchTerm?: string | null; 
+/**
+ * Opaque scope selected by the UI. When set it **wins** over
+ * `include_item_types`, which remains for the non-search `get_items`
+ * callers that legitimately request a single concrete type.
+ */
+scope?: SearchScope | null }
 /**
 * Search result with pagination
 */
 export type SearchResult = { items: MediaItem[]; totalRecordCount: number }
+/**
+ * An opaque search scope the frontend selects; Rust owns what it *means*.
+ * 
+ * The expansion table below is Jellyfin domain vocabulary: it changes when
+ * Jellyfin adds or renames an item type, never when the UI is redesigned. It
+ * previously lived in the frontend (`searchScope.ts`), which is the boundary
+ * leak documented in docs/specs/scoped-search-boundary.md. The frontend now
+ * sends the enum and never names an item type in connection with search.
+ * 
+ * TRACES: UR-049 | DR-063
+ */
+export type SearchScope = "all" | "music" | "movies" | "tv"
 /**
 * Security status info
 */
@@ -1,4 +1,4 @@
-<!-- TRACES: UR-003, UR-005, UR-020, UR-021, UR-026, UR-040, UR-061 | DR-010, DR-023, DR-024, DR-051, DR-052, DR-092 -->
+<!-- TRACES: UR-003, UR-005, UR-020, UR-021, UR-026, UR-040, UR-061 | DR-010, DR-023, DR-024, DR-051, DR-052, DR-092, DR-098, DR-099 -->
 <script lang="ts">
  import { onMount, onDestroy, untrack } from "svelte";
  import { goto } from "$app/navigation";
@@ -24,6 +24,9 @@
    createTapGestureState,
    registerTap,
    resolveSeekTarget,
+    clampSeekTarget,
+    isSynthesizedTouchClick,
+    isControlSurfaceTouch,
    SEEK_FORWARD_SECONDS,
    SEEK_BACKWARD_SECONDS,
    type TapFeedback,
@@ -111,7 +114,9 @@
  let touchStartY = $state(0);
  let touchStartTime = $state(0);
  let tapGestures = createTapGestureState();
-  let tapTimeout: ReturnType<typeof setTimeout> | null = null;
+  // When a touch tap last ran the gesture handler, so the compatibility click
+  // the browser synthesizes afterwards can be ignored (see handleVideoClick).
+  let lastTouchTapAt = 0;
  let brightness = $state(1); // 0-2, default 1
  let showDoubleTapFeedback = $state<TapFeedback | null>(null);
  let doubleTapFeedbackTimeout: ReturnType<typeof setTimeout> | null = null;
@@ -119,6 +124,14 @@
  // so back-to-back double taps chain instead of stacking on a stale position.
  let pendingSeekTarget: number | null = null;
  let swipeGestureActive = $state(false);
+  // Whether the in-flight touch belongs to the player surface (and so may be
+  // read as a tap/swipe gesture) rather than to a control. Set on touchstart,
+  // cleared on touchend — see handleTouchMove for why a per-gesture flag and not
+  // just a per-event target check.
+  let playerGestureActive = false;
+  // Raised when the user changes the seek bar's value, cleared by whichever
+  // release signal commits the seek. See handleSeekBarRelease.
+  let seekCommitArmed = false;

  // Backend info from Rust (Rust decides which backend to use based on platform)
  let useHtml5Element = $state(true); // Default to HTML5, Rust will override if using native backend
@@ -685,15 +698,19 @@
          bufferedRanges.push(`[${buffered.start(i).toFixed(1)} - ${buffered.end(i).toFixed(1)}]`);
        }

-        console.log("[VideoPlayer Debug]", {
-          currentTime: videoElement.currentTime.toFixed(2),
-          displayTime: currentTime.toFixed(2),
-          buffered: bufferedRanges.join(", "),
-          readyState: videoElement.readyState,
-          paused: videoElement.paused,
-          seeking: videoElement.seeking,
-          playbackRate: videoElement.playbackRate,
-        });
+        // Flattened to a single string on purpose: the Android WebView console
+        // bridge stringifies objects as "[object Object]" in logcat, which made
+        // this whole payload useless when diagnosing over adb.
+        console.log(
+          `[VideoPlayer Debug] t=${videoElement.currentTime.toFixed(2)}` +
+            ` display=${currentTime.toFixed(2)}` +
+            ` readyState=${videoElement.readyState}` +
+            ` networkState=${videoElement.networkState}` +
+            ` paused=${videoElement.paused}` +
+            ` seeking=${videoElement.seeking}` +
+            ` rate=${videoElement.playbackRate}` +
+            ` buffered=${bufferedRanges.join(", ")}`
+        );
      }
    }, 1000);
  });
@@ -714,11 +731,6 @@
    if (debugLogInterval) {
      clearInterval(debugLogInterval);
    }
-    // A deferred single tap must not fire play/pause after teardown.
-    if (tapTimeout) {
-      clearTimeout(tapTimeout);
-      tapTimeout = null;
-    }
    tapGestures.cancel();
    if (doubleTapFeedbackTimeout) {
      clearTimeout(doubleTapFeedbackTimeout);
@@ -1100,6 +1112,21 @@
  }

  function handlePause() {
+    // The element pausing is normally user intent, but a stall, a source change,
+    // or a competing controller can also do it — and the pause itself carries no
+    // reason. Log the element state so an unexplained pause/resume loop can be
+    // attributed from an adb capture instead of guessed at.
+    const el = videoElement;
+    console.log(
+      `[VideoPlayer] pause event — t=${el ? el.currentTime.toFixed(2) : "?"}` +
+        ` readyState=${el?.readyState}` +
+        ` networkState=${el?.networkState}` +
+        ` seeking=${el?.seeking}` +
+        ` ended=${el?.ended}` +
+        ` isSeeking=${isSeeking}` +
+        ` isBuffering=${isBuffering}` +
+        ` handoff=${handoffState.active}`
+    );
    isPlaying = false;
    stopTimeUpdates(); // Stop RAF loop when paused
    html5Adapter.reportState("paused", reportMediaId ?? null);
@@ -1143,11 +1170,33 @@
    const targetTime = parseFloat(input.value);
    // Update the displayed time immediately for smooth visual feedback
    currentTime = targetTime;
+    // The user has moved the value; the next release must commit it.
+    seekCommitArmed = true;
  }

-  async function handleSeekBarChange(e: Event) {
-    const input = e.target as HTMLInputElement;
-    const targetTime = parseFloat(input.value);
+  /**
+   * Seek-bar released — commit the value the user landed on, at most once.
+   *
+   * Wired to `touchend`/`mouseup` AND `change`, because `change` alone is not
+   * dependable: Android's WebView does not reliably fire it for a touch
+   * interaction on a range input, so the thumb moved to the tapped position but
+   * the seek never ran ("the bar moves, playback doesn't"). Engines that DO fire
+   * `change` deliver both signals, hence the arm/disarm — whichever arrives
+   * first commits and the other is a no-op.
+   */
+  function handleSeekBarRelease(e: Event) {
+    isDraggingSeekBar = false;
+    if (!seekCommitArmed) return;
+    seekCommitArmed = false;
+    const input = (e.currentTarget ?? e.target) as HTMLInputElement;
+    void commitSeek(parseFloat(input.value));
+  }
+
+  async function commitSeek(rawTarget: number) {
+    // Clamp strictly inside the media: the range input's max IS the duration, so
+    // dragging fully right would otherwise request a segment past the media end,
+    // which the server never produces (see END_SEEK_MARGIN_SECONDS).
+    const targetTime = clampSeekTarget(rawTarget, duration);

    // Set isSeeking immediately to prevent timeupdate from interfering
    isSeeking = true;
@@ -1384,16 +1433,9 @@
      to: newTime.toFixed(2),
    });

-    // Call the unified handleSeekBarChange logic with the new time
-    // Create a synthetic event to reuse the existing logic
-    const syntheticEvent = {
-      target: {
-        value: newTime.toString()
-      }
-    } as unknown as Event;
-
+    // Same commit path as the seek bar — one place decides how a seek is issued.
    try {
-      await handleSeekBarChange(syntheticEvent);
+      await commitSeek(newTime);
    } finally {
      // The player is authoritative again from here on.
      if (pendingSeekTarget === newTime) pendingSeekTarget = null;
@@ -1421,8 +1463,47 @@
    }
  }

+  /**
+   * Walk up from the touch target collecting the tag/attribute pairs
+   * `isControlSurfaceTouch` needs, so the rule itself stays DOM-free and testable.
+   */
+  function ancestorChain(target: EventTarget | null) {
+    const chain: Array<{
+      tag: string;
+      isPlayerControls?: boolean;
+      isPlayerSurface?: boolean;
+    }> = [];
+    let node = target as HTMLElement | null;
+    // Bounded walk: controls live a few levels below the player root, and
+    // stopping at <body> keeps this cheap and avoids depending on a bound ref.
+    while (node && node.tagName !== "BODY") {
+      chain.push({
+        tag: node.tagName ?? "",
+        isPlayerControls: node.dataset?.playerControls !== undefined,
+        isPlayerSurface: node.dataset?.playerSurface !== undefined,
+      });
+      node = node.parentElement;
+    }
+    return chain;
+  }
+
  // Touch gesture handlers
  function handleTouchStart(e: TouchEvent) {
+    // Taps on the controls belong to those controls. This listener is on the
+    // container and touch events bubble, so without this a tap on the bottom
+    // play button would toggle here AND again via the button's own click — the
+    // two cancelling out and leaving the control apparently dead (DR-098).
+    if (isControlSurfaceTouch(ancestorChain(e.target))) {
+      // The move handler must stay out of it too. It reads touchStartX/Y, which
+      // this early return leaves at the PREVIOUS gesture's values, so a seek-bar
+      // drag came out as a huge vertical delta: it was mis-read as a brightness
+      // swipe, which dimmed the screen and fired a spurious play/pause
+      // "correction" mid-drag (DR-098).
+      playerGestureActive = false;
+      return;
+    }
+    playerGestureActive = true;
+
    const touch = e.touches[0];
    touchStartX = touch.clientX;
    touchStartY = touch.clientY;
@@ -1434,28 +1515,29 @@
      now: Date.now(),
    });

-    if (tapTimeout) {
-      clearTimeout(tapTimeout);
-      tapTimeout = null;
-    }
+    // Suppress the compatibility click this touch will synthesize.
+    lastTouchTapAt = Date.now();

    if (outcome.action === "seek") {
      e.preventDefault();
      handleDoubleTap(outcome.seekSeconds, outcome.feedback);
+      // Re-toggle so the first tap's toggle is undone: a double tap seeks and
+      // leaves the play state as it was (playing keeps playing, paused stays
+      // paused).
+      if (outcome.togglePlayPause) togglePlayPause();
      return;
    }

-    // Single tap so far: defer play/pause until the double-tap window closes,
-    // so a double tap seeks without also toggling pause.
-    tapTimeout = setTimeout(() => {
-      tapTimeout = null;
-      if (tapGestures.resolvePending(Date.now())) {
+    // First tap: act now. Nothing is deferred, so there is no timer to race the
+    // compatibility click Android synthesizes after a touch tap (see DR-098).
    togglePlayPause();
  }
-    }, outcome.pendingAfterMs);
-  }

  function handleTouchMove(e: TouchEvent) {
+    // Only a gesture that began on the bare video surface is ours. Re-checking
+    // the target here would not be enough: the touch that started on a control
+    // never recorded a start point, so any delta computed here is meaningless.
+    if (!playerGestureActive) return;
    if (!e.touches[0]) return;

    const touch = e.touches[0];
@@ -1465,14 +1547,16 @@

    // Minimum movement to register as swipe (50px)
    if (Math.abs(deltaY) > 50 && timeDelta > 50) {
-      swipeGestureActive = true;
-
-      // This is a swipe, not a tap — drop the deferred play/pause.
+      // Only on the frame the gesture is first recognised as a swipe — this runs
+      // on every touchmove, and the correction below must happen exactly once.
+      if (!swipeGestureActive) {
+        // The touchstart already toggled play/pause (taps act immediately now),
+        // so undo it: a swipe must not change the play state. Forget the tap too,
+        // so it cannot pair with a later tap into a spurious seek.
+        togglePlayPause();
        tapGestures.cancel();
-      if (tapTimeout) {
-        clearTimeout(tapTimeout);
-        tapTimeout = null;
      }
+      swipeGestureActive = true;

      // Brightness control on vertical swipe
      swipeType = "brightness";
@@ -1486,19 +1570,22 @@
  }

  function handleTouchEnd(e: TouchEvent) {
+    playerGestureActive = false;
    swipeGestureActive = false;
    swipeType = null;
  }

  /**
-   * Mouse clicks toggle play/pause immediately. Touch taps are already handled
-   * by `handleTouchStart` (which defers play/pause past the double-tap window),
-   * so the compatibility click that follows a tap must be ignored here —
-   * otherwise it pauses on the first tap of a double tap.
+   * Mouse clicks toggle play/pause immediately. Touch taps are handled fully by
+   * `handleTouchStart`, so the compatibility click the browser synthesizes after
+   * a tap must be ignored or every tap toggles twice.
+   *
+   * Used by EVERY click target layered over the video, not just the <video>:
+   * pausing renders the full-screen play overlay, so the synthesized click lands
+   * on that button instead and would re-toggle straight back to playing.
   */
-  function handleVideoClick(e: MouseEvent) {
-    // A click synthesized from a touch reports no pointer movement detail.
-    if (e.detail === 0 || tapTimeout !== null) return;
+  function handleSurfaceClick(e: MouseEvent) {
+    if (isSynthesizedTouchClick(e.detail, Date.now(), lastTouchTapAt)) return;
    togglePlayPause();
  }

@@ -1666,7 +1753,7 @@
          onwaiting={handleWaiting}
          onplaying={handlePlaying}
          onloadstart={handleLoadStart}
-          onclick={handleVideoClick}
+          onclick={handleSurfaceClick}
        >
          <!-- Temporarily disabled to debug playback issues
          {#each subtitleTracks() as track}
@@ -1759,10 +1846,17 @@
        <div class="w-12 h-12 border-4 border-white border-t-transparent rounded-full animate-spin"></div>
      </div>
    {:else if !isPlaying}
-      <!-- Play/Pause overlay -->
+      <!-- Play overlay. Visually this IS the video surface, so it is marked
+           `data-player-surface`: it must keep participating in tap gestures even
+           though it is a <button>, or the second tap of a double tap (which lands
+           here, because the first tap paused and raised this overlay) is
+           discarded as "a tap on a control" and seeking dies. It still shares the
+           synthesized-click guard, since it appears exactly when a tap pauses.
+           See DR-098. -->
      <button
+        data-player-surface
        class="absolute inset-0 flex items-center justify-center bg-black/30"
-        onclick={togglePlayPause}
+        onclick={handleSurfaceClick}
        aria-label="Play"
      >
        <svg class="w-20 h-20 text-white" fill="currentColor" viewBox="0 0 24 24">
@@ -1810,8 +1904,10 @@
    {/if}
  </div>

-  <!-- Controls -->
+  <!-- Controls. `data-player-controls` marks this subtree as interactive so
+       container-level tap gestures ignore touches here (see DR-098). -->
  <div
+    data-player-controls
    class="absolute bottom-0 left-0 right-0 bg-gradient-to-t from-black/80 to-transparent p-4 transition-opacity duration-300"
    class:opacity-0={!showControls}
    class:pointer-events-none={!showControls}
@@ -1838,11 +1934,11 @@
          max={duration || 100}
          value={currentTime}
          oninput={handleSeekBarInput}
-          onchange={handleSeekBarChange}
+          onchange={handleSeekBarRelease}
          onmousedown={() => isDraggingSeekBar = true}
-          onmouseup={() => isDraggingSeekBar = false}
+          onmouseup={handleSeekBarRelease}
          ontouchstart={() => isDraggingSeekBar = true}
-          ontouchend={() => isDraggingSeekBar = false}
+          ontouchend={handleSeekBarRelease}
          class="flex-1 h-1 bg-white/30 rounded-full appearance-none cursor-pointer
                 [&::-webkit-slider-thumb]:appearance-none [&::-webkit-slider-thumb]:w-3 [&::-webkit-slider-thumb]:h-3
                 [&::-webkit-slider-thumb]:bg-white [&::-webkit-slider-thumb]:rounded-full"
@@ -0,0 +1,211 @@
+/**
+ * Behavioural regression tests for the video tap surface — rendered against the
+ * REAL component, not a hand-modelled DOM.
+ *
+ * TRACES: UR-005, UR-061 | DR-098 | UT-092
+ *
+ * Why this file exists:
+ *
+ * `tapGestures.test.ts` tests `registerTap` / `isControlSurfaceTouch` /
+ * `isSynthesizedTouchClick` as isolated pure functions. Every one of those tests
+ * passed while, on the device, in sequence: the player pause-looped, then
+ * pausing became impossible, then the bottom controls went dead, then
+ * double-tap-to-seek stopped working. The helpers were each behaving exactly as
+ * specified — the bugs were all in the *composition*: which element actually
+ * receives a tap once Svelte has re-rendered.
+ *
+ * Testing my own helpers could not catch that, and modelling the DOM by hand in
+ * a test just re-encodes the same wrong assumption. So these tests render
+ * VideoPlayer and dispatch real touch/click events at whatever element is
+ * genuinely on top, asserting user-visible outcomes ("a double tap seeks")
+ * rather than internals.
+ *
+ * The specific traps encoded here, each a bug that shipped:
+ *   - pausing renders a full-screen <button> play overlay OVER the video, so the
+ *     second tap of a double tap lands on a button, not the video;
+ *   - the browser synthesizes a `click` after a touch tap, which must not toggle
+ *     a second time, on ANY layered target;
+ *   - the bottom controls bar must drive its own buttons and NOT the container's
+ *     tap gestures.
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render } from "@testing-library/svelte";
+import { tick } from "svelte";
+import VideoPlayer from "./VideoPlayer.svelte";
+import { SEEK_FORWARD_SECONDS } from "./tapGestures";
+
+// --- Mocks: everything VideoPlayer reaches for that is not the tap surface. ---
+
+const toggleSpy = vi.fn();
+const seekVideoSpy = vi.fn();
+const seekSpy = vi.fn();
+
+vi.mock("$app/navigation", () => ({ goto: vi.fn() }));
+
+vi.mock("$lib/player", () => ({
+  playerController: {
+    toggle: (...a: unknown[]) => {
+      toggleSpy(...a);
+      return Promise.resolve();
+    },
+    seekVideo: (...a: unknown[]) => {
+      seekVideoSpy(...a);
+      return Promise.resolve();
+    },
+    seek: (...a: unknown[]) => {
+      seekSpy(...a);
+      return Promise.resolve();
+    },
+    setActiveAdapter: vi.fn(),
+    clearActiveAdapter: vi.fn(),
+    getActiveAdapter: vi.fn(() => null),
+  },
+}));
+
+vi.mock("$lib/player/adapters/rustReportHost", () => ({
+  createRustReportHost: () => ({
+    onState: vi.fn(),
+    onPosition: vi.fn(),
+    onMediaLoaded: vi.fn(),
+    onEnded: vi.fn(),
+    onError: vi.fn(),
+    onStreamUrlChanged: vi.fn(),
+    onBuffering: vi.fn(),
+    onReady: vi.fn(),
+  }),
+}));
+
+vi.mock("$lib/player/html5Adapter", () => ({
+  reportState: vi.fn(),
+  reportPosition: vi.fn(),
+  reportMediaLoaded: vi.fn(),
+  resetReporting: vi.fn(),
+}));
+
+vi.mock("$lib/utils/pictureInPicture", () => ({
+  isPipSupported: () => false,
+  enterPip: vi.fn(),
+  setAutoEnterEnabled: vi.fn(),
+}));
+
+vi.mock("$lib/stores/auth", () => ({
+  auth: {
+    getRepository: () => ({ getHandle: () => "h", jrayActorsAt: async () => [] }),
+    subscribe: (fn: (v: unknown) => void) => {
+      fn({ isAuthenticated: true });
+      return () => {};
+    },
+  },
+}));
+
+const MEDIA = {
+  id: "item-1",
+  name: "Test Episode",
+  type: "Episode",
+  runTimeTicks: 6_000_000_000, // 600s
+} as any;
+
+/** Dispatch a touch at (x, y) on whatever element is topmost there. */
+function touchAt(el: Element, x: number) {
+  const touch = { clientX: x, clientY: 300 } as Touch;
+  el.dispatchEvent(
+    new TouchEvent("touchstart", {
+      bubbles: true,
+      cancelable: true,
+      touches: [touch] as unknown as Touch[],
+    })
+  );
+}
+
+function renderPlayer() {
+  return render(VideoPlayer, {
+    props: { media: MEDIA, streamUrl: "http://x/master.m3u8", onClose: vi.fn() },
+  });
+}
+
+describe("VideoPlayer tap surface (real component)", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("a single tap on the video toggles play/pause exactly once", async () => {
+    const { container } = renderPlayer();
+    const video = container.querySelector("video");
+    expect(video).toBeTruthy();
+
+    touchAt(video!, 900);
+
+    expect(toggleSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("the synthesized click after a tap does not toggle a second time", async () => {
+    const { container } = renderPlayer();
+    const video = container.querySelector("video")!;
+
+    touchAt(video, 900);
+    // The compatibility click the browser fires after a touch tap. detail=0 is
+    // how engines mark it; a late real-detail click is covered by the recency
+    // guard, which this exercises too since it lands immediately.
+    video.dispatchEvent(new MouseEvent("click", { bubbles: true, detail: 0 }));
+
+    expect(toggleSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("a double tap seeks even though the first tap raised the play overlay", async () => {
+    // THE regression this file exists for. On device the first tap pauses, which
+    // makes Svelte render a full-screen <button> play overlay over the video —
+    // so the SECOND tap lands on a button, not the video. A control-surface
+    // guard that does not know about that overlay discards it and seeking dies.
+    //
+    // Reproducing it requires the overlay to actually render, which means
+    // driving `isPlaying` the way the real element does: via its `pause` event.
+    vi.useFakeTimers();
+    try {
+      const { container } = renderPlayer();
+      const video = container.querySelector("video")!;
+
+      // Tap 1 on the video.
+      touchAt(video, 900);
+
+      // The element reports it paused → isPlaying=false → overlay renders.
+      video.dispatchEvent(new Event("pause"));
+      await Promise.resolve();
+      await tick();
+
+      const overlay = container.querySelector("[data-player-surface]");
+      expect(overlay, "the play overlay should be covering the video").toBeTruthy();
+
+      vi.advanceTimersByTime(120); // inside DOUBLE_TAP_WINDOW_MS
+      // Tap 2 lands on the OVERLAY, exactly as on device.
+      touchAt(overlay!, 900);
+
+      // Either seek route is acceptable — which one runs depends on whether a
+      // video adapter is registered. What must hold is that a seek happened, to
+      // roughly the forward-skip target.
+      const calls = [...seekVideoSpy.mock.calls, ...seekSpy.mock.calls];
+      expect(calls.length).toBe(1);
+      const [position] = calls[0];
+      expect(position).toBeGreaterThan(0);
+      expect(position).toBeLessThanOrEqual(SEEK_FORWARD_SECONDS);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("tapping the bottom play/pause button toggles once, not twice", async () => {
+    const { container } = renderPlayer();
+    const controls = container.querySelector("[data-player-controls]");
+    expect(controls).toBeTruthy();
+
+    const playBtn = controls!.querySelector("button");
+    expect(playBtn).toBeTruthy();
+
+    // A real press: touchstart bubbles to the container's gesture handler, then
+    // the button's own click fires. Only ONE toggle may result.
+    touchAt(playBtn!, 40);
+    playBtn!.dispatchEvent(new MouseEvent("click", { bubbles: true, detail: 1 }));
+
+    expect(toggleSpy).toHaveBeenCalledTimes(1);
+  });
+});
@@ -0,0 +1,218 @@
+/**
+ * VideoPlayer seek-bar TOUCH scrub regression tests (Android).
+ *
+ * Reported bug: on Android, dragging the progress bar does not change the
+ * playback location.
+ *
+ * The gesture listener lives on the outer container and touch events bubble.
+ * `handleTouchStart` ignores touches that land on a control (the seek bar is an
+ * <input>, inside `data-player-controls`) — but `handleTouchMove` does not, so a
+ * seek-bar drag is still interpreted as a container swipe. That mis-read swipe
+ * fires `togglePlayPause()` (undoing a first-tap toggle that never happened) and
+ * hijacks the drag into brightness control.
+ *
+ * The existing scrub regression tests only drive the slider with MOUSE events,
+ * which never reach the touch handlers — which is why this survived.
+ *
+ * The seek was also committed only from `change`, which Android's WebView does
+ * not reliably fire for a touch interaction on a range input — so a tap moved
+ * the thumb and no seek ever ran. Release now commits from touchend/mouseup too.
+ *
+ * TRACES: UR-005, UR-061 | DR-098, DR-099 | UT-089, UT-090
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// ---- Mocks (must precede component import) --------------------------------
+
+const channelHandlers: Record<string, (event: any) => void> = {};
+vi.mock("@tauri-apps/api/event", () => ({
+  listen: vi.fn(async (channel: string, handler: any) => {
+    channelHandlers[channel] = handler;
+    return () => {
+      delete channelHandlers[channel];
+    };
+  }),
+}));
+
+vi.mock("@tauri-apps/api/core", () => ({
+  invoke: vi.fn(),
+}));
+
+const playerPlayItem = vi.fn(async () => ({
+  useHtml5Element: false,
+  backend: "exoplayer",
+  state: { kind: "playing" },
+}));
+const playerSeekVideo = vi.fn(async (_h: string, position: number) => ({
+  strategy: "native",
+  position,
+}));
+const playerStop = vi.fn(async () => ({}));
+const playerToggle = vi.fn(async () => ({ state: "playing" }));
+
+vi.mock("$lib/api/bindings", () => ({
+  commands: {
+    playerPlayItem: (...a: any[]) => playerPlayItem(...(a as [])),
+    playerSeekVideo: (...a: any[]) => playerSeekVideo(...(a as [string, number])),
+    playerStop: (...a: any[]) => playerStop(...(a as [])),
+    playerToggle: (...a: any[]) => playerToggle(...(a as [])),
+    playerPlay: vi.fn(async () => ({})),
+    playerPause: vi.fn(async () => ({})),
+    playerSetSleepTimer: vi.fn(async () => ({})),
+    playerCancelSleepTimer: vi.fn(async () => ({})),
+    playerSetSubtitleTrack: vi.fn(async () => ({})),
+    playerSwitchAudioTrack: vi.fn(async () => ({})),
+    storageGetSeriesAudioPreference: vi.fn(async () => null),
+    storageSaveSeriesAudioPreference: vi.fn(async () => ({})),
+  },
+  events: {
+    playerStatusEvent: { listen: vi.fn(async () => () => {}) },
+  },
+}));
+
+vi.mock("$lib/stores/auth", () => ({
+  auth: {
+    getUserId: () => "user-1",
+    getRepository: () => ({
+      getHandle: () => "repo-1",
+      getSubtitleUrl: async () => "",
+      jrayActorsAt: async () => [],
+    }),
+  },
+}));
+
+vi.mock("$app/navigation", () => ({
+  goto: vi.fn(),
+}));
+
+import { render, fireEvent, waitFor } from "@testing-library/svelte";
+import { tick } from "svelte";
+import VideoPlayer from "./VideoPlayer.svelte";
+import type { MediaItem } from "$lib/api/types";
+
+function makeEpisode(): MediaItem {
+  return {
+    id: "ep1",
+    name: "Episode 1",
+    kind: "episode",
+    durationMs: 24 * 60 * 1000, // 24 min
+  } as MediaItem;
+}
+
+async function mountAndroidPlayer() {
+  const utils = render(VideoPlayer, {
+    props: {
+      media: makeEpisode(),
+      streamUrl: "http://server/videos/ep1/master.m3u8",
+      mediaSourceId: "src-1",
+      needsTranscoding: false,
+      onClose: vi.fn(),
+    },
+  });
+
+  await waitFor(() => expect(playerPlayItem).toHaveBeenCalled());
+  await waitFor(() => expect(playerStop).toHaveBeenCalled());
+
+  const slider = utils.container.querySelector(
+    'input[type="range"]'
+  ) as HTMLInputElement;
+  const video = utils.container.querySelector("video") as HTMLVideoElement;
+  expect(slider).not.toBeNull();
+  return { ...utils, slider, video };
+}
+
+function touch(x: number, y: number) {
+  return { clientX: x, clientY: y } as Touch;
+}
+
+/**
+ * Drag the seek bar with TOUCH events, the way a finger does on Android.
+ *
+ * A real drag along the bar moves the finger far enough that the container's
+ * swipe detector (50px) would trigger if it were still listening.
+ */
+async function touchScrubTo(
+  slider: HTMLInputElement,
+  video: HTMLVideoElement,
+  target: number
+) {
+  await fireEvent.touchStart(slider, { touches: [touch(100, 700)] });
+  // Finger travels across the bar. Small vertical wander is normal for a thumb
+  // drag; the horizontal travel is what matters.
+  await fireEvent.touchMove(slider, { touches: [touch(400, 690)] });
+  slider.value = String(target);
+  await fireEvent.input(slider);
+  await fireEvent.touchMove(slider, { touches: [touch(700, 705)] });
+  await fireEvent.change(slider);
+  await fireEvent.touchEnd(slider, { touches: [] });
+  if (video) await fireEvent(video, new Event("seeked"));
+  await tick();
+}
+
+describe("VideoPlayer seek bar — touch drag (Android)", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    for (const key of Object.keys(channelHandlers)) delete channelHandlers[key];
+  });
+
+  it("a touch drag on the seek bar seeks to the dragged position", async () => {
+    const { slider, video } = await mountAndroidPlayer();
+
+    await touchScrubTo(slider, video, 600);
+
+    await waitFor(() =>
+      expect(playerSeekVideo).toHaveBeenCalledWith("repo-1", 600, "src-1", null, true)
+    );
+    expect(parseFloat(slider.value)).toBeCloseTo(600);
+  });
+
+  it("a touch drag on the seek bar never toggles play/pause", async () => {
+    const { slider, video } = await mountAndroidPlayer();
+
+    await touchScrubTo(slider, video, 600);
+
+    // The container gesture layer must stay out of a control drag entirely:
+    // no swipe mis-read, so no play/pause correction.
+    expect(playerToggle).not.toHaveBeenCalled();
+  });
+
+  it("commits the seek on touchend even when the engine never fires `change`", async () => {
+    const { slider, video } = await mountAndroidPlayer();
+
+    // Android's WebView does not reliably fire `change` for a touch interaction
+    // on a range input. A tap on the track still moves the thumb and fires
+    // `input` — the seek must be committed on release regardless.
+    await fireEvent.touchStart(slider, { touches: [touch(400, 700)] });
+    slider.value = "600";
+    await fireEvent.input(slider);
+    await fireEvent.touchEnd(slider, { touches: [] });
+    if (video) await fireEvent(video, new Event("seeked"));
+    await tick();
+
+    await waitFor(() =>
+      expect(playerSeekVideo).toHaveBeenCalledWith("repo-1", 600, "src-1", null, true)
+    );
+  });
+
+  it("commits the seek exactly once when both touchend and change fire", async () => {
+    const { slider, video } = await mountAndroidPlayer();
+
+    await touchScrubTo(slider, video, 600);
+
+    expect(playerSeekVideo).toHaveBeenCalledTimes(1);
+  });
+
+  it("a touch drag on the seek bar does not hijack into brightness control", async () => {
+    const { slider, video, container } = await mountAndroidPlayer();
+
+    await touchScrubTo(slider, video, 600);
+
+    // Brightness is applied as a CSS filter on the <video>; a control drag must
+    // leave it untouched.
+    const el = container.querySelector("video") as HTMLVideoElement | null;
+    if (el) {
+      expect(el.style.filter).toBe("brightness(1)");
+    }
+  });
+});
@@ -6,6 +6,11 @@ import {
  createTapGestureState,
  registerTap,
  resolveSeekTarget,
+  clampSeekTarget,
+  END_SEEK_MARGIN_SECONDS,
+  isSynthesizedTouchClick,
+  isControlSurfaceTouch,
+  TOUCH_CLICK_SUPPRESS_MS,
 } from "./tapGestures";

 const SCREEN_WIDTH = 1000;
@@ -25,24 +30,22 @@ function asSeek(outcome: ReturnType<typeof tap>) {
 }

 describe("tap gesture resolution", () => {
-  it("defers the single-tap action until the double-tap window has elapsed", () => {
-    const state = createTapGestureState();
-    const first = tap(state, RIGHT, 1000);
+  // Every tap acts IMMEDIATELY — there is no deferral and no timer.
+  //
+  //   1st tap: toggle play/pause
+  //   2nd tap: seek, then toggle play/pause AGAIN
+  //
+  // The second toggle undoes the first, so a double tap seeks while leaving the
+  // play state exactly as it was: playing -> jump and keep playing; paused ->
+  // jump and stay paused. The old design deferred the first tap behind a 300ms
+  // timer, which raced the synthesized click and produced a pause/unpause loop.

-    // The first tap must NOT immediately toggle play/pause — it may still
-    // become a double tap.
-    expect(first).toEqual({ action: "pending", pendingAfterMs: DOUBLE_TAP_WINDOW_MS });
+  it("toggles play/pause immediately on the first tap", () => {
+    const state = createTapGestureState();
+    expect(tap(state, RIGHT, 1000)).toEqual({ action: "togglePlayPause" });
  });

-  it("resolves an isolated tap to togglePlayPause once the window expires", () => {
-    const state = createTapGestureState();
-    tap(state, RIGHT, 1000);
-
-    const resolved = state.resolvePending(1000 + DOUBLE_TAP_WINDOW_MS);
-    expect(resolved).toEqual({ action: "togglePlayPause" });
-  });
-
-  it("seeks forward 30s on a double tap on the right half and never pauses", () => {
+  it("seeks forward 30s AND toggles again on a second right-side tap", () => {
    const state = createTapGestureState();
    tap(state, RIGHT, 1000);
    const second = asSeek(tap(state, RIGHT, 1150));
@@ -50,12 +53,11 @@ describe("tap gesture resolution", () => {
    expect(second.seekSeconds).toBe(SEEK_FORWARD_SECONDS);
    expect(second.seekSeconds).toBe(30);
    expect(second.feedback).toBe("right");
-
-    // The deferred single-tap pause must have been cancelled.
-    expect(state.resolvePending(1150 + DOUBLE_TAP_WINDOW_MS)).toBeNull();
+    // The re-toggle is what preserves the play state across a double tap.
+    expect(second.togglePlayPause).toBe(true);
  });

-  it("seeks back 10s on a double tap on the left half", () => {
+  it("seeks back 10s AND toggles again on a second left-side tap", () => {
    const state = createTapGestureState();
    tap(state, LEFT, 1000);
    const second = asSeek(tap(state, LEFT, 1100));
@@ -63,24 +65,44 @@ describe("tap gesture resolution", () => {
    expect(second.seekSeconds).toBe(SEEK_BACKWARD_SECONDS);
    expect(second.seekSeconds).toBe(-10);
    expect(second.feedback).toBe("left");
+    expect(second.togglePlayPause).toBe(true);
  });

-  it("treats a second tap after the window as a new pending single tap", () => {
+  it("net play state is unchanged by a double tap (two toggles cancel out)", () => {
+    const state = createTapGestureState();
+    let playing = true;
+    const apply = (outcome: ReturnType<typeof tap>) => {
+      if (outcome.action === "togglePlayPause") playing = !playing;
+      else if (outcome.action === "seek" && outcome.togglePlayPause) playing = !playing;
+    };
+
+    apply(tap(state, RIGHT, 1000)); // toggle -> paused
+    apply(tap(state, RIGHT, 1100)); // seek + toggle -> playing again
+    expect(playing).toBe(true);
+
+    // And from paused, a double tap leaves it paused.
+    playing = false;
+    apply(tap(state, RIGHT, 2000));
+    apply(tap(state, RIGHT, 2100));
+    expect(playing).toBe(false);
+  });
+
+  it("treats a tap after the window as a fresh first tap", () => {
    const state = createTapGestureState();
    tap(state, RIGHT, 1000);
    const late = tap(state, RIGHT, 1000 + DOUBLE_TAP_WINDOW_MS + 1);

-    expect(late.action).toBe("pending");
+    expect(late.action).toBe("togglePlayPause");
  });

-  it("does not treat a third tap as another double tap", () => {
+  it("only ever has first and second taps — the tap after a pair is a fresh toggle", () => {
    const state = createTapGestureState();
    tap(state, RIGHT, 1000);
    expect(tap(state, RIGHT, 1100).action).toBe("seek");

-    // Triple tap: the third tap starts a fresh pending tap rather than
-    // seeking again off the consumed second tap.
-    expect(tap(state, RIGHT, 1200).action).toBe("pending");
+    // The pair is consumed. The next tap is a FIRST tap again, so it toggles
+    // play/pause — there is no "third tap" concept.
+    expect(tap(state, RIGHT, 1200).action).toBe("togglePlayPause");
  });

  it("accumulates repeated double taps on the same side", () => {
@@ -103,12 +125,13 @@ describe("tap gesture resolution", () => {
    expect(second.feedback).toBe("right");
  });

-  it("cancel() drops a pending tap so an interpreted swipe cannot pause", () => {
+  it("cancel() makes the next tap a fresh first tap (swipe interrupted the pair)", () => {
    const state = createTapGestureState();
    tap(state, RIGHT, 1000);
    state.cancel();

-    expect(state.resolvePending(1000 + DOUBLE_TAP_WINDOW_MS)).toBeNull();
+    // Without cancel() this would have been the seeking second tap.
+    expect(tap(state, RIGHT, 1100).action).toBe("togglePlayPause");
  });
 });

@@ -123,8 +146,28 @@ describe("seek target resolution", () => {
    expect(resolveSeekTarget({ delta: -10, reportedPosition: 4, duration: DURATION })).toBe(0);
  });

-  it("clamps to the duration when skipping past the end", () => {
-    expect(resolveSeekTarget({ delta: 30, reportedPosition: 590, duration: DURATION })).toBe(DURATION);
+  it("clamps short of the duration when skipping past the end", () => {
+    // Never land exactly on `duration`: hls.js would then request the segment
+    // that starts at/after the media end, which the server never produces —
+    // the fetch times out and the gap-controller stalls in a pause loop.
+    expect(resolveSeekTarget({ delta: 30, reportedPosition: 590, duration: DURATION })).toBe(
+      DURATION - END_SEEK_MARGIN_SECONDS
+    );
+  });
+
+  it("keeps the end clamp strictly inside the media for a long transcoded item", () => {
+    // Regression: seeking near the end of a ~105min transcoded item clamped to
+    // the exact runtime (6330.324s), making hls.js fetch segment 1055 which
+    // starts at 6336.33s — past the end. That segment 404s/times out forever.
+    const runtime = 6330.324;
+    const target = resolveSeekTarget({ delta: 30, reportedPosition: 6320, duration: runtime });
+
+    expect(target).toBeLessThan(runtime);
+    expect(target).toBeCloseTo(runtime - END_SEEK_MARGIN_SECONDS, 5);
+  });
+
+  it("does not clamp below zero for media shorter than the end margin", () => {
+    expect(resolveSeekTarget({ delta: 30, reportedPosition: 1, duration: 1 })).toBe(0);
  });

  it("chains off a pending target so rapid taps do not compound off a stale position", () => {
@@ -156,3 +199,78 @@ describe("seek target resolution", () => {
    expect(resolveSeekTarget({ delta: 30, reportedPosition: 100, duration: 0 })).toBe(130);
  });
 });
+
+describe("control-surface touches are not gestures", () => {
+  // Regression: the gesture listener is on the outer container and touch events
+  // bubble, so tapping the bottom play/pause button ran the gesture handler
+  // (toggle #1) AND the button's own click handler (toggle #2). The two
+  // cancelled out and the control appeared dead.
+  it("treats a tap on a button as a control, not a gesture", () => {
+    expect(isControlSurfaceTouch([{ tag: "svg" }, { tag: "button" }, { tag: "div" }])).toBe(true);
+  });
+
+  it("treats the seek bar input as a control", () => {
+    expect(isControlSurfaceTouch([{ tag: "input" }, { tag: "div" }])).toBe(true);
+  });
+
+  it("treats anything inside the controls bar as a control", () => {
+    expect(
+      isControlSurfaceTouch([{ tag: "span" }, { tag: "div", isPlayerControls: true }])
+    ).toBe(true);
+  });
+
+  it("lets a tap on the bare video surface through as a gesture", () => {
+    expect(isControlSurfaceTouch([{ tag: "video" }, { tag: "div" }, { tag: "div" }])).toBe(false);
+  });
+
+  it("is case-insensitive about tag names", () => {
+    expect(isControlSurfaceTouch([{ tag: "BUTTON" }])).toBe(true);
+  });
+});
+
+describe("synthesized touch-click suppression", () => {
+  // Regression: pausing renders a full-screen play-overlay button over the
+  // video, so the compatibility click Android synthesizes from the tap lands on
+  // the OVERLAY, not the <video>. With no guard there it re-toggled and undid
+  // the pause — pausing looked impossible while unpausing worked fine (the
+  // overlay is removed when playing, so nothing intercepted that direction).
+  it("suppresses a click with detail 0 (clearly synthesized)", () => {
+    expect(isSynthesizedTouchClick(0, 10_000, 0)).toBe(true);
+  });
+
+  it("suppresses a real-detail click that closely follows a touch tap", () => {
+    const tapAt = 10_000;
+    expect(isSynthesizedTouchClick(1, tapAt + 120, tapAt)).toBe(true);
+    expect(isSynthesizedTouchClick(1, tapAt + TOUCH_CLICK_SUPPRESS_MS - 1, tapAt)).toBe(true);
+  });
+
+  it("allows a genuine mouse click well after any touch", () => {
+    const tapAt = 10_000;
+    expect(isSynthesizedTouchClick(1, tapAt + TOUCH_CLICK_SUPPRESS_MS + 1, tapAt)).toBe(false);
+  });
+
+  it("allows a genuine mouse click when no touch has ever happened", () => {
+    expect(isSynthesizedTouchClick(1, 10_000, 0)).toBe(false);
+  });
+});
+
+describe("seek target clamping (shared by skip and seek-bar drag)", () => {
+  it("keeps a mid-stream target untouched", () => {
+    expect(clampSeekTarget(100, 600)).toBe(100);
+  });
+
+  it("pulls a drag to the very end back inside the media", () => {
+    // The seek bar's max IS the duration, so dragging fully right yields
+    // exactly `duration` — the value that triggers the dead-segment stall.
+    expect(clampSeekTarget(6330.324, 6330.324)).toBeCloseTo(6330.324 - END_SEEK_MARGIN_SECONDS, 5);
+  });
+
+  it("clamps negative and non-finite targets to zero", () => {
+    expect(clampSeekTarget(-5, 600)).toBe(0);
+    expect(clampSeekTarget(NaN, 600)).toBe(0);
+  });
+
+  it("leaves the target alone when the duration is unknown", () => {
+    expect(clampSeekTarget(500, 0)).toBe(500);
+  });
+});
@@ -1,18 +1,86 @@
 /**
 * Tap-gesture interpretation for the video player surface.
 *
- * Pulled out of `VideoPlayer.svelte` so the timing rules are unit-testable:
- * a tap cannot be classified at the moment it lands, because it may still turn
- * out to be the first half of a double tap. Play/pause is therefore *deferred*
- * until the double-tap window closes, and cancelled outright if a second tap
- * arrives — otherwise a double tap both toggles pause and seeks.
+ * Every tap acts IMMEDIATELY — there are only first and second taps, and no
+ * deferral:
 *
- * TRACES: UR-005, UR-061 | DR-092 | UT-085, UT-086, UT-087, UT-088
+ *   1st tap: toggle play/pause
+ *   2nd tap (within the window): seek, then toggle play/pause AGAIN
+ *
+ * The second toggle undoes the first, so a double tap seeks while leaving the
+ * play state exactly as it started — playing stays playing, paused stays paused.
+ *
+ * This replaced a design that deferred the first tap behind a 300ms timer so it
+ * could be cancelled if a second tap arrived. That deferral raced the
+ * compatibility `click` Android's WebView synthesizes after a touch tap: the
+ * timer cleared its own handle *before* running the toggle, reopening the guard
+ * that was meant to suppress the late click, which then toggled a second time.
+ * The result was a play/pause loop about a second apart. Acting immediately
+ * removes the timer, the window race, and the loop.
+ *
+ * TRACES: UR-005, UR-061 | DR-092, DR-095, DR-098 | UT-085, UT-086, UT-087, UT-088
 */

-/** A second tap within this window makes a double tap. */
+/** A second tap within this window pairs with the previous one (seek + re-toggle). */
 export const DOUBLE_TAP_WINDOW_MS = 300;

+/**
+ * How long after a touch tap a mouse `click` is assumed to be the compatibility
+ * event the browser synthesizes from that touch. Android's WebView can deliver it
+ * noticeably late, so this is generous.
+ */
+export const TOUCH_CLICK_SUPPRESS_MS = 700;
+
+/**
+ * Whether a touch landed on an interactive control rather than the bare video
+ * surface, and so must NOT be interpreted as a play/pause or seek gesture.
+ *
+ * The gesture listener sits on the outer container, and touch events bubble, so
+ * without this a tap on the bottom control bar runs the gesture handler (toggle
+ * #1) *and* the button's own click handler (toggle #2) — the two cancel out and
+ * the button appears dead. Buttons, links, inputs (the seek bar), and anything
+ * inside an element marked `data-player-controls` are treated as controls.
+ *
+ * Takes the ancestor chain as plain tag/attribute pairs so the rule is unit
+ * testable without a DOM.
+ */
+export function isControlSurfaceTouch(
+  ancestors: Array<{ tag: string; isPlayerControls?: boolean; isPlayerSurface?: boolean }>
+): boolean {
+  const INTERACTIVE = new Set(["button", "a", "input", "select", "textarea", "label"]);
+  for (const node of ancestors) {
+    // `data-player-surface` wins over the tag check: the full-screen play overlay
+    // is a <button> but is visually the video itself, and must keep taking tap
+    // gestures — otherwise the second tap of a double tap (which lands on it,
+    // because the first tap paused and raised it) is discarded and seeking dies.
+    if (node.isPlayerSurface === true) return false;
+    if (node.isPlayerControls === true) return true;
+    if (INTERACTIVE.has(node.tag.toLowerCase())) return true;
+  }
+  return false;
+}
+
+/**
+ * Whether a `click` should be ignored because a touch tap already handled it.
+ *
+ * EVERY click target layered over the video must consult this — not just the
+ * `<video>` element. Pausing swaps in a full-screen play-overlay button, so the
+ * synthesized click lands on *that* button rather than the video, and an
+ * unguarded handler there re-toggles and undoes the pause (pause appeared
+ * impossible while unpause worked, because unpausing removes the overlay).
+ *
+ * `detail === 0` catches the synthesized click on engines that report it; the
+ * recency check covers engines that report a real `detail`.
+ */
+export function isSynthesizedTouchClick(
+  detail: number,
+  now: number,
+  lastTouchTapAt: number
+): boolean {
+  if (detail === 0) return true;
+  return now - lastTouchTapAt < TOUCH_CLICK_SUPPRESS_MS;
+}
+
 /** Double tap on the right half: skip forward. */
 export const SEEK_FORWARD_SECONDS = 30;

@@ -22,9 +90,18 @@ export const SEEK_BACKWARD_SECONDS = -10;
 export type TapFeedback = "left" | "right";

 export type TapOutcome =
-  /** Deferred: play/pause fires only if no second tap lands within the window. */
-  | { action: "pending"; pendingAfterMs: number }
-  | { action: "seek"; seekSeconds: number; feedback: TapFeedback };
+  /** First tap: toggle play/pause right now. */
+  | { action: "togglePlayPause" }
+  /**
+   * Second tap: seek, and toggle play/pause again so the first tap's toggle is
+   * undone and the play state survives the double tap unchanged.
+   */
+  | {
+      action: "seek";
+      seekSeconds: number;
+      feedback: TapFeedback;
+      togglePlayPause: true;
+    };

 export interface TapInput {
  /** Tap x position, viewport pixels. */
@@ -35,32 +112,20 @@ export interface TapInput {

 export interface TapGestureState {
  /**
-   * Resolve a still-pending single tap. Returns the play/pause action once the
-   * double-tap window has elapsed, or null if there is nothing pending (the tap
-   * became a double tap, or was cancelled).
+   * Forget the previous tap, so the next one is treated as a first tap. Used
+   * when the gesture turns out to be a swipe.
   */
-  resolvePending(now: number): { action: "togglePlayPause" } | null;
-  /** Drop any pending tap — used when the gesture turns into a swipe. */
  cancel(): void;
 }

 interface InternalState extends TapGestureState {
  lastTapTime: number;
-  pendingSince: number | null;
 }

 export function createTapGestureState(): TapGestureState {
  const state: InternalState = {
    lastTapTime: 0,
-    pendingSince: null,
-    resolvePending(now: number) {
-      if (state.pendingSince === null) return null;
-      if (now - state.pendingSince < DOUBLE_TAP_WINDOW_MS) return null;
-      state.pendingSince = null;
-      return { action: "togglePlayPause" };
-    },
    cancel() {
-      state.pendingSince = null;
      state.lastTapTime = 0;
    },
  };
@@ -68,27 +133,64 @@ export function createTapGestureState(): TapGestureState {
 }

 /**
- * Classify a tap. The first tap of a potential pair returns `pending` — the
- * caller schedules `resolvePending` after `pendingAfterMs`. A second tap inside
- * the window returns the seek and clears the pending play/pause.
+ * Classify a tap and return the action to perform *now*.
+ *
+ * A tap that closely follows another is the second of a pair: it seeks and
+ * re-toggles play/pause (undoing the first tap's toggle). Any other tap is a
+ * first tap and simply toggles. Nothing is deferred, so there is no window to
+ * race and no third-tap case — a consumed pair resets the state.
 */
 export function registerTap(state: TapGestureState, input: TapInput): TapOutcome {
  const s = state as InternalState;
  const sinceLastTap = input.now - s.lastTapTime;

  if (s.lastTapTime > 0 && sinceLastTap > 0 && sinceLastTap < DOUBLE_TAP_WINDOW_MS) {
-    // Second tap: cancel the deferred play/pause and seek instead.
-    s.pendingSince = null;
-    s.lastTapTime = 0; // consumed, so a third tap starts fresh
+    s.lastTapTime = 0; // pair consumed; the next tap is a first tap again
    const isLeftSide = input.x < input.screenWidth / 2;
    return isLeftSide
-      ? { action: "seek", seekSeconds: SEEK_BACKWARD_SECONDS, feedback: "left" }
-      : { action: "seek", seekSeconds: SEEK_FORWARD_SECONDS, feedback: "right" };
+      ? {
+          action: "seek",
+          seekSeconds: SEEK_BACKWARD_SECONDS,
+          feedback: "left",
+          togglePlayPause: true,
+        }
+      : {
+          action: "seek",
+          seekSeconds: SEEK_FORWARD_SECONDS,
+          feedback: "right",
+          togglePlayPause: true,
+        };
  }

  s.lastTapTime = input.now;
-  s.pendingSince = input.now;
-  return { action: "pending", pendingAfterMs: DOUBLE_TAP_WINDOW_MS };
+  return { action: "togglePlayPause" };
+}
+
+/**
+ * Safety margin (seconds) kept between a clamped seek target and the media end.
+ *
+ * Landing *exactly* on `duration` makes hls.js request the segment whose start
+ * time is at/after the end of the media. The server never produces that segment,
+ * so the fetch times out and hls.js' gap-controller stalls forever at the last
+ * buffered position — surfacing as "unpausing bounces straight back to paused".
+ * One segment length (~6s for Jellyfin's ts segments) is comfortably clear of
+ * the final segment boundary.
+ */
+export const END_SEEK_MARGIN_SECONDS = 6;
+
+/**
+ * Clamp an absolute seek target into the safely-playable range.
+ *
+ * Shared by the relative-skip path ({@link resolveSeekTarget}) and the seek-bar
+ * drag path, which can otherwise land exactly on `duration` because the range
+ * input's `max` is the duration itself.
+ */
+export function clampSeekTarget(target: number, duration: number): number {
+  if (!Number.isFinite(target) || target < 0) return 0;
+  if (duration > 0 && target > duration - END_SEEK_MARGIN_SECONDS) {
+    return Math.max(0, duration - END_SEEK_MARGIN_SECONDS);
+  }
+  return target;
 }

 export interface SeekTargetInput {
@@ -123,6 +225,10 @@ export function resolveSeekTarget(input: SeekTargetInput): number {

  const target = base + delta;
  if (target < 0) return 0;
-  if (duration > 0 && target > duration) return duration;
+  // Clamp strictly inside the media — see END_SEEK_MARGIN_SECONDS. Guard against
+  // going negative on media shorter than the margin itself.
+  if (duration > 0 && target > duration) {
+    return Math.max(0, duration - END_SEEK_MARGIN_SECONDS);
+  }
  return target;
 }
@@ -95,6 +95,63 @@ describe("Html5PlayerAdapter", () => {
    expect(video.play).toHaveBeenCalledTimes(1);
  });

+  // A stalling HLS stream makes hls.js' gap-controller nudge the element, which
+  // aborts an in-flight play(). That AbortError is transient — the element is
+  // still trying to play — so it must not be surfaced as a player error, or the
+  // UI reports failure ~once a second for the whole stall.
+  it("play() does not report an interrupted-by-pause AbortError as an error", async () => {
+    const abort = new DOMException(
+      "The play() request was interrupted by a call to pause().",
+      "AbortError"
+    );
+    video.play = vi.fn(async () => {
+      throw abort;
+    });
+
+    await adapter.play();
+
+    expect(host.onError).not.toHaveBeenCalled();
+  });
+
+  it("play() still reports a genuine failure", async () => {
+    video.play = vi.fn(async () => {
+      throw new DOMException("no supported source", "NotSupportedError");
+    });
+
+    await adapter.play();
+
+    expect(host.onError).toHaveBeenCalledTimes(1);
+    expect(String((host.onError as any).mock.calls[0][0])).toContain("play() failed");
+  });
+
+  it("play() coalesces concurrent attempts into one element.play() call", async () => {
+    // During a stall the UI and recovery paths can both ask to play. Stacking
+    // element.play() calls is what generates the AbortError storm.
+    let resolvePlay: () => void = () => {};
+    video.play = vi.fn(
+      () =>
+        new Promise<void>((r) => {
+          resolvePlay = () => {
+            video.paused = false;
+            r();
+          };
+        })
+    );
+
+    const first = adapter.play();
+    const second = adapter.play();
+    resolvePlay();
+    await Promise.all([first, second]);
+
+    expect(video.play).toHaveBeenCalledTimes(1);
+  });
+
+  it("play() works again after a previous attempt settled", async () => {
+    await adapter.play();
+    await adapter.play();
+    expect(video.play).toHaveBeenCalledTimes(2);
+  });
+
  it("pause() calls element.pause()", async () => {
    video.paused = false;
    await adapter.pause();
@@ -16,7 +16,7 @@
 * intents flowing through the PlayerAdapter interface while preserving the
 * hard-won element behavior verbatim.
 *
- * TRACES: UR-003, UR-005, UR-020, UR-021 | DR-001, DR-023, DR-024, DR-028
+ * TRACES: UR-003, UR-005, UR-020, UR-021 | DR-001, DR-023, DR-024, DR-028, DR-096
 */

 import type { AdapterHost, PlayerAdapter, PlayerLoadOptions } from "./types";
@@ -41,10 +41,24 @@ export interface Html5ElementBridge {
  getMediaSourceId(): string | null;
 }

+/**
+ * True for the `AbortError` the browser raises when a pending `play()` promise is
+ * cancelled by a `pause()` (or a source/seek change). It signals "that specific
+ * play attempt was superseded", not "playback failed" — hls.js' stall recovery
+ * produces it routinely, so it must not reach the player's error channel.
+ */
+function isPlayInterruptedError(err: unknown): boolean {
+  if (!err || typeof err !== "object") return false;
+  const { name, message } = err as { name?: string; message?: string };
+  return name === "AbortError" || (message ?? "").includes("interrupted");
+}
+
 export class Html5PlayerAdapter implements PlayerAdapter {
  readonly kind = "html5" as const;

  private attachedElement: HTMLVideoElement | null = null;
+  /** In-flight play() attempt, so concurrent callers share one element.play(). */
+  private pendingPlay: Promise<void> | null = null;
  private host: AdapterHost;
  private bridge: Html5ElementBridge;

@@ -81,12 +95,31 @@ export class Html5PlayerAdapter implements PlayerAdapter {
  async play(): Promise<void> {
    const el = this.element;
    if (!el) return;
+    // Coalesce concurrent attempts. While an HLS stream stalls, the UI and the
+    // gap-controller recovery path can both ask to play; stacking element.play()
+    // calls is what turns one stall into an AbortError storm.
+    if (this.pendingPlay) return this.pendingPlay;
+
+    this.pendingPlay = (async () => {
      try {
        await el.play();
        // handlePlay on the element reports "playing"; no double-report here.
      } catch (err) {
+        // A play() aborted by a pause() is transient, not a failure: hls.js
+        // nudges the element to recover from a stall, which cancels the pending
+        // play promise while the element keeps trying. Surfacing it would report
+        // an error roughly once a second for the duration of the stall.
+        if (isPlayInterruptedError(err)) {
+          console.debug("[Html5PlayerAdapter] play() interrupted by pause (stall recovery)");
+        } else {
          this.host.onError(`play() failed: ${err}`);
        }
+      } finally {
+        this.pendingPlay = null;
+      }
+    })();
+
+    return this.pendingPlay;
  }

  async pause(): Promise<void> {
@@ -12,7 +12,7 @@
 * derived + merged (remote-session-aware) stores so UI can import state and
 * actions from one place, in both local and remote modes.
 *
- * TRACES: UR-005 | DR-001, DR-009
+ * TRACES: UR-005 | DR-001, DR-009, DR-097 | UT-091
 */

 import { get } from "svelte/store";
@@ -83,18 +83,29 @@ function requireHandle(): string {
 // Transport controls (no repository handle required)
 // ---------------------------------------------------------------------------

+// Transport intents ALWAYS go to the backend, in both native and HTML5 modes.
+//
+// These used to short-circuit into the active video adapter, which made the
+// webview the decider: `adapter.toggle()` read `el.paused` off the DOM and
+// flipped the element, so Rust never saw the intent. `el.paused` flips
+// transiently while an element buffers or settles a seek, so two intents
+// ~150ms apart could read different values and take opposing actions — a
+// self-sustaining play/pause loop.
+//
+// Now Rust decides from PlayerController state and drives the element back
+// through a `ControlCommand` event (handled in playerEvents.ts), the same
+// "backend decides, adapter executes the primitive" split used by
+// player_seek_video. Do NOT reintroduce an adapter short-circuit here.
+
 async function play() {
-  if (activeAdapter) return void (await activeAdapter.play());
  await commands.playerPlay();
 }

 async function pause() {
-  if (activeAdapter) return void (await activeAdapter.pause());
  await commands.playerPause();
 }

 async function toggle() {
-  if (activeAdapter) return void (await activeAdapter.toggle());
  await commands.playerToggle();
 }

@@ -0,0 +1,113 @@
+/**
+ * Transport authority: play/pause/toggle are DECIDED in Rust, never in the webview.
+ *
+ * TRACES: UR-005 | DR-097 | UT-091
+ *
+ * The frontend used to short-circuit transport controls whenever a video adapter
+ * was registered: `toggle()` read `el.paused` off the DOM and flipped the element
+ * directly, so the Rust `PlayerController` never saw the intent and could not
+ * serialise competing ones. Because `el.paused` flips transiently while an HTML5
+ * element buffers or settles a seek, two intents arriving ~150ms apart could read
+ * *different* values and perform *opposing* actions — one playing, one pausing —
+ * which is the self-sustaining play/pause loop observed on Android.
+ *
+ * The rule these tests pin: a transport intent always reaches the backend. Rust
+ * decides play-vs-pause from controller state and drives the webview element back
+ * through a ControlCommand event (the same "backend decides, adapter executes"
+ * split `player_seek_video` already uses).
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+const mockCommands = {
+  playerPlay: vi.fn(async () => ({})),
+  playerPause: vi.fn(async () => ({})),
+  playerToggle: vi.fn(async () => ({})),
+  playerStop: vi.fn(async () => ({})),
+};
+
+vi.mock("$lib/api/bindings", () => ({
+  commands: mockCommands,
+  // Stores pulled in transitively subscribe to typed events at module load.
+  events: {
+    playerStatusEvent: { listen: vi.fn(async () => () => {}) },
+    downloadEvent: { listen: vi.fn(async () => () => {}) },
+    searchEvent: { listen: vi.fn(async () => () => {}) },
+  },
+}));
+
+vi.mock("$lib/stores/auth", () => ({
+  auth: {
+    subscribe: (fn: (v: unknown) => void) => {
+      fn({ isAuthenticated: true });
+      return () => {};
+    },
+    getRepository: () => ({ getHandle: () => "handle-1" }),
+  },
+}));
+
+/** A video adapter that records whether the facade reached into it directly. */
+function makeAdapter() {
+  return {
+    kind: "html5" as const,
+    play: vi.fn(async () => {}),
+    pause: vi.fn(async () => {}),
+    toggle: vi.fn(async () => true),
+    seekElement: vi.fn(async () => {}),
+    reloadSource: vi.fn(async () => {}),
+    attach: vi.fn(),
+    dispose: vi.fn(async () => {}),
+    setVolume: vi.fn(),
+    setMuted: vi.fn(),
+    selectSubtitle: vi.fn(async () => {}),
+    getPosition: vi.fn(() => 0),
+    load: vi.fn(async () => {}),
+  };
+}
+
+describe("transport authority lives in Rust", () => {
+  let playerController: any;
+  let adapter: ReturnType<typeof makeAdapter>;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    vi.resetModules();
+    ({ playerController } = await import("./index"));
+    adapter = makeAdapter();
+    playerController.setActiveAdapter(adapter);
+  });
+
+  it("routes toggle to the backend even when a video adapter is active", async () => {
+    await playerController.toggle();
+
+    expect(mockCommands.playerToggle).toHaveBeenCalledTimes(1);
+    // The webview must NOT decide play-vs-pause from the DOM.
+    expect(adapter.toggle).not.toHaveBeenCalled();
+  });
+
+  it("routes play to the backend even when a video adapter is active", async () => {
+    await playerController.play();
+
+    expect(mockCommands.playerPlay).toHaveBeenCalledTimes(1);
+    expect(adapter.play).not.toHaveBeenCalled();
+  });
+
+  it("routes pause to the backend even when a video adapter is active", async () => {
+    await playerController.pause();
+
+    expect(mockCommands.playerPause).toHaveBeenCalledTimes(1);
+    expect(adapter.pause).not.toHaveBeenCalled();
+  });
+
+  it("still routes transport to the backend with no adapter (audio path unchanged)", async () => {
+    playerController.clearActiveAdapter();
+
+    await playerController.toggle();
+    await playerController.play();
+    await playerController.pause();
+
+    expect(mockCommands.playerToggle).toHaveBeenCalledTimes(1);
+    expect(mockCommands.playerPlay).toHaveBeenCalledTimes(1);
+    expect(mockCommands.playerPause).toHaveBeenCalledTimes(1);
+  });
+});
@@ -5,7 +5,7 @@
 * frontend stores accordingly. This enables push-based updates instead
 * of polling.
 *
- * TRACES: UR-005, UR-019, UR-023, UR-026 | DR-001, DR-028, DR-047
+ * TRACES: UR-005, UR-019, UR-023, UR-026 | DR-001, DR-028, DR-047, DR-097
 */

 import { type UnlistenFn } from "@tauri-apps/api/event";
@@ -306,9 +306,15 @@ function handleSleepTimerChanged(mode: SleepTimerMode, remainingSeconds: number)

 /**
 * Route a backend-originated control command to the active player adapter, so a
- * backend intent (lockscreen/remote/sleep) can drive the webview <video> element
- * that Rust cannot reach directly. No-op when no video adapter is active (audio
- * playback is already fully backend-driven).
+ * backend intent can drive the webview <video>/<audio> element that Rust cannot
+ * reach directly. No-op when no adapter is active (native playback is already
+ * fully backend-driven).
+ *
+ * This is the EXECUTION half of transport authority: for webview-rendered media
+ * the Rust controller decides play-vs-pause from the state the element reported
+ * and emits it here as a ControlCommand. UI intents go *to* the backend (see the
+ * facade in $lib/player) and come back through this path — never short-circuited
+ * in the webview, which is what caused the DR-097 pause loop.
 */
 function handleControlCommand(action: string, position: number | null): void {
  const adapter = playerController.getActiveAdapter();
@@ -5,7 +5,7 @@ import { writable, derived } from "svelte/store";
 import { listen, type UnlistenFn } from "@tauri-apps/api/event";
 import type { Library, MediaItem, SearchResult, Genre } from "$lib/api/types";
 import type { SearchOptions } from "$lib/api/bindings";
-import { scopeItemTypes, type SearchScope } from "$lib/utils/searchScope";
+import type { SearchScope } from "$lib/utils/searchScope";
 import { auth } from "./auth";

 /**
@@ -227,12 +227,13 @@ function createLibraryStore() {
  /**
   * Search the library, optionally narrowed to a scope.
   *
-   * `scope` is additive and defaults to `all`, which sends no
-   * `includeItemTypes` at all — see scopeItemTypes() for why that differs from
-   * listing every type. Both the online and offline repository paths already
-   * honour the filter.
+   * The scope is sent **opaque**; Rust expands it into Jellyfin item types
+   * (`SearchScope::item_types()`) before the cache and server paths diverge, so
+   * online and offline results filter identically. `all` resolves to no filter
+   * at all — not the union of the other scopes, which would drop People and
+   * folders.
   *
-   * TRACES: UR-049 | DR-065
+   * TRACES: UR-049 | DR-063, DR-065
   */
  async function search(query: string, scope: SearchScope = "all") {
    // Bump the request id for every call (including clears) so any in-flight
@@ -259,10 +260,9 @@ function createLibraryStore() {
      // Phase 1: the command resolves with instant local-cache results. The
      // merged (cache + server) union arrives later via the `search-event`
      // listener above, tagged with this same requestId.
-      const itemTypes = scopeItemTypes(scope);
-      const options: SearchOptions = { limit: 10000 };
-      // Omit the key entirely for the `all` scope rather than sending null.
-      if (itemTypes) options.includeItemTypes = itemTypes;
+      // Send the opaque scope; Rust expands it to item types. The frontend
+      // never names a Jellyfin item type in connection with search.
+      const options: SearchOptions = { limit: 10000, scope };

      const result = await Promise.race([
        repo.search(query, options, requestId),
@@ -32,35 +32,43 @@ describe("library.search scoping", () => {
    library.clearSearch();
  });

-  it("omits includeItemTypes entirely for the default (all) scope", async () => {
+  // The frontend sends the OPAQUE scope and never names a Jellyfin item type.
+  // Expansion (music → MusicAlbum/MusicArtist/Audio/Playlist) is asserted in
+  // Rust — see `search_scope_tests` in src-tauri/src/repository/types.rs.
+  // Asserting item types here would mean the frontend knows the taxonomy again,
+  // which is the leak docs/specs/scoped-search-boundary.md exists to prevent.
+
+  it("sends the default (all) scope and never an item-type list", async () => {
    await library.search("office");

    const options = searchMock.mock.calls[0][1];
+    expect(options.scope).toBe("all");
    expect(options).not.toHaveProperty("includeItemTypes");
    expect(options.limit).toBe(10000);
  });

-  it("forwards music item types when scoped to music", async () => {
+  it("sends the opaque scope when scoped to music", async () => {
    await library.search("office", "music");

-    expect(searchMock.mock.calls[0][1].includeItemTypes).toEqual([
-      "MusicAlbum",
-      "MusicArtist",
-      "Audio",
-      "Playlist",
-    ]);
+    const options = searchMock.mock.calls[0][1];
+    expect(options.scope).toBe("music");
+    expect(options).not.toHaveProperty("includeItemTypes");
  });

-  it("forwards tv item types when scoped to tv", async () => {
+  it("sends the opaque scope when scoped to tv", async () => {
    await library.search("office", "tv");

-    expect(searchMock.mock.calls[0][1].includeItemTypes).toEqual(["Series", "Episode"]);
+    const options = searchMock.mock.calls[0][1];
+    expect(options.scope).toBe("tv");
+    expect(options).not.toHaveProperty("includeItemTypes");
  });

-  it("forwards movie item types when scoped to movies", async () => {
+  it("sends the opaque scope when scoped to movies", async () => {
    await library.search("office", "movies");

-    expect(searchMock.mock.calls[0][1].includeItemTypes).toEqual(["Movie"]);
+    const options = searchMock.mock.calls[0][1];
+    expect(options.scope).toBe("movies");
+    expect(options).not.toHaveProperty("includeItemTypes");
  });

  it("stores results and the query on success", async () => {
@@ -9,7 +9,6 @@ import {
  resolveSearchScope,
  searchRouteUrl,
  shouldNavigateToSearch,
-  scopeItemTypes,
  type SearchGroupId,
 } from "./searchScope";

@@ -62,25 +61,12 @@ describe("resolveSearchScope", () => {
  });
 });

-describe("scopeItemTypes", () => {
-  it("omits the key entirely for the all scope", () => {
-    // `all` must send no includeItemTypes — an explicit union would silently
-    // drop types nobody enumerated (Person, folders).
-    expect(scopeItemTypes("all")).toBeUndefined();
-  });
-
-  it("maps each narrow scope to its item types", () => {
-    expect(scopeItemTypes("music")).toEqual(["MusicAlbum", "MusicArtist", "Audio", "Playlist"]);
-    expect(scopeItemTypes("movies")).toEqual(["Movie"]);
-    expect(scopeItemTypes("tv")).toEqual(["Series", "Episode"]);
-  });
-
-  it("returns a fresh array callers cannot mutate into the table", () => {
-    const first = scopeItemTypes("movies")!;
-    first.push("Series");
-    expect(scopeItemTypes("movies")).toEqual(["Movie"]);
-  });
-});
+// NOTE: the former `scopeItemTypes` suite moved to Rust — see
+// `search_scope_tests` in src-tauri/src/repository/types.rs. The scope →
+// item-type expansion is domain vocabulary and is no longer reachable from the
+// frontend, so testing it here would mean re-introducing the leak to test it.
+// The "fresh array" test is gone because `item_types()` returns an owned Vec,
+// making the aliasing bug it guarded structurally impossible.

 describe("normalizeGroupOrder", () => {
  it("returns the default for missing or non-array input", () => {
@@ -8,7 +8,11 @@
 //
 // TRACES: UR-049, UR-050 | DR-063, DR-066, DR-067

-export type SearchScope = "all" | "music" | "movies" | "tv";
+// Sourced from Rust via the generated bindings — the backend owns what a scope
+// *means* (which Jellyfin item types it covers). Naming an opaque variant is
+// presentation; knowing its expansion is domain vocabulary and stays in Rust.
+export type { SearchScope } from "$lib/api/bindings";
+import type { SearchScope } from "$lib/api/bindings";

 export const SEARCH_SCOPES: readonly SearchScope[] = ["all", "music", "movies", "tv"];

@@ -19,29 +23,11 @@ export const SCOPE_LABELS: Record<SearchScope, string> = {
  tv: "TV",
 };

-/**
- * Jellyfin item types requested for each scope.
- *
- * `all` is deliberately absent: sending no `includeItemTypes` is *not* the same
- * as sending the union of the lists below — types nobody enumerated here
- * (Person, folders, …) would be filtered out by an explicit list.
- */
-const SCOPE_ITEM_TYPES: Record<Exclude<SearchScope, "all">, string[]> = {
-  music: ["MusicAlbum", "MusicArtist", "Audio", "Playlist"],
-  movies: ["Movie"],
-  tv: ["Series", "Episode"],
-};
-
-/**
- * Item types to send with a scoped search, or `undefined` for the `all` scope
- * so the caller omits the key entirely.
- *
- * TRACES: UR-049 | DR-063
- */
-export function scopeItemTypes(scope: SearchScope): string[] | undefined {
-  if (scope === "all") return undefined;
-  return [...SCOPE_ITEM_TYPES[scope]];
-}
+// NOTE: the scope → Jellyfin item-type mapping deliberately does NOT live here.
+// It is domain vocabulary and lives in Rust (`SearchScope::item_types()` in
+// repository/types.rs); the frontend sends the opaque scope and the backend
+// expands it. Re-introducing a `{ music: ["MusicAlbum", …] }` table in this file
+// is the boundary leak documented in docs/specs/scoped-search-boundary.md.

 /**
 * Resolve the scope a search started from a given route should default to.
@@ -8,7 +8,9 @@ export default defineConfig({
    globals: true,
    environment: "jsdom",
    setupFiles: ["./src/test/setup-globals.ts", "./src/test/setup.ts"],
-    include: ["src/**/*.{test,spec}.{js,ts}"],
+    // `scripts/` is included so build tooling (the traceability coverage
+    // engine) is covered by the normal suite rather than only by CI.
+    include: ["src/**/*.{test,spec}.{js,ts}", "scripts/**/*.{test,spec}.{js,ts}"],
    coverage: {
      provider: "v8",
      reporter: ["text", "json", "html"],