refactor(frontend): satisfy noUncheckedIndexedAccess (S3b)

Enable noUncheckedIndexedAccess and fix all 98 call sites it surfaced across 18
files. Every fix is behaviour-preserving — the flag flagged reads TypeScript
couldn't prove in-bounds, all of which were already guarded by a length/index check,
a findIndex result, or a non-empty invariant:

- read-once so a ternary's narrowing sticks (Feed overrides, linkify mention);
- non-null assertion AFTER an existing guard (PlayerModal/VideoEditor queue+cut-list
  indexing, modules step, useUndoable stacks) with a comment stating the invariant;
- nullish fallback where undefined is a real possibility (GlassTuner slider ?? def,
  ConfigPanel active group ?? [], descriptionLinks id ?? null);
- optional chaining where the entry genuinely can be absent (PlexBrowse IO entry);
- a non-empty tuple type for the RELATIVE_UNITS constant (encodes "always has [0]").

The single highest-leverage fix: PlayerModal's `active` became `queue?.[index] ??
video` (always Video), clearing 34 of the 45 errors in that file at once. Verified:
tsc/eslint/prettier clean, 56 vitest + 34 pytest + 17/17 e2e green (the e2e suite
exercises the feed/player/channel components touched here).

frontend/src/components/ConfigPanel.tsx

@@ -81,6 +81,7 @@ export default function ConfigPanel() {
     try {
       for (const key of dirtyKeys) {
         const it = byKey[key];
+        if (!it) continue; // dirtyKeys are all config-item keys; skip if somehow not found
         const raw = draft[key] ?? "";
         if (it.secret) {
           if (secretReset[key] && !raw.trim()) await api.resetConfig(key);
@@ -170,14 +171,14 @@ export default function ConfigPanel() {
       <PageToolbar>
         <div className="px-4 pt-3 max-w-3xl w-full mx-auto">
           <p className="text-xs text-muted mb-3 leading-relaxed">{t("config.intro")}</p>
-          <Tabs tabs={groupTabs} active={activeGroup} onChange={setTab} />
+          <Tabs tabs={groupTabs} active={activeGroup ?? ""} onChange={setTab} />
         </div>
       </PageToolbar>
       <div className="px-4 pb-24 pt-3 max-w-3xl w-full mx-auto">
         {activeGroup && (
           <div className="glass rounded-2xl p-4 mb-4">
             <div className="divide-y divide-border/60">
-              {data.groups[activeGroup].map((item) => (
+              {(data.groups[activeGroup] ?? []).map((item) => (
                 <Field
                   key={item.key}
                   item={item}

frontend/src/components/Feed.tsx

@@ -330,8 +330,14 @@ export default function Feed({
   loadedRef.current = loaded;
   const withOverrides = (list: Video[]): Video[] =>
     list
-      .map((v) => (overrides[v.id] ? { ...v, status: overrides[v.id] } : v))
-      .map((v) => (savedOverrides[v.id] !== undefined ? { ...v, saved: savedOverrides[v.id] } : v));
+      .map((v) => {
+        const status = overrides[v.id]; // read once so the narrowing sticks
+        return status ? { ...v, status } : v;
+      })
+      .map((v) => {
+        const saved = savedOverrides[v.id];
+        return saved !== undefined ? { ...v, saved } : v;
+      });
   const merged: Video[] = withOverrides(loaded);
   const items: Video[] = merged.filter((v) => matchesView(v.status, filters.show));
   // The in-app player's queue (auto-advance / loop / prev-next). It's the filtered feed, but the

frontend/src/components/GlassTuner.tsx

@@ -339,7 +339,12 @@ export default function GlassTuner() {
               {tab === "glass" && (
                 <div className="flex flex-col gap-2.5">
                   {SLIDERS.map((s) => (
-                    <Ctl key={s.k} s={s} value={vars[s.k]} onChange={(v) => setVar(s.k, v)} />
+                    <Ctl
+                      key={s.k}
+                      s={s}
+                      value={vars[s.k] ?? s.def}
+                      onChange={(v) => setVar(s.k, v)}
+                    />
                   ))}
                 </div>
               )}

frontend/src/components/PlayerModal.tsx

@@ -124,7 +124,7 @@ export default function PlayerModal({
   // where a just-watched item could drop out and snap playback to queue[0]).
   let index = queue ? queue.findIndex((v) => v.id === playingId) : 0;
   if (index < 0) index = 0;
-  const active = queue && queue[index] ? queue[index] : video;
+  const active = queue?.[index] ?? video; // the queue item at index, else the opened video (never undefined)
   const hasQueue = !!queue && queue.length > 1;
   // startAt only applies to the item we opened with; advanced items resume their own pos.
   const resumeAt =
@@ -242,11 +242,11 @@ export default function PlayerModal({
   navRef.current = { queue, index };
   const goPrev = () => {
     const { queue: q, index: i } = navRef.current;
-    if (q && i > 0) setPlayingId(q[i - 1].id);
+    if (q && i > 0) setPlayingId(q[i - 1]!.id);
   };
   const goNext = () => {
     const { queue: q, index: i } = navRef.current;
-    if (q && i < q.length - 1) setPlayingId(q[i + 1].id);
+    if (q && i < q.length - 1) setPlayingId(q[i + 1]!.id);
   };
   // Relative seek within the current video (plain Arrow keys), matching YouTube's ±5s.
   const nudgeSeek = (delta: number) => {
@@ -277,12 +277,12 @@ export default function PlayerModal({
     );
   };
   const cycleAuto = () => {
-    const next = AUTO_MODES[(AUTO_MODES.indexOf(autoMode) + 1) % AUTO_MODES.length];
+    const next = AUTO_MODES[(AUTO_MODES.indexOf(autoMode) + 1) % AUTO_MODES.length]!;
     setAutoMode(next);
     persistPref({ playerAutoAdvance: next });
   };
   const cycleLoop = () => {
-    const next = LOOP_MODES[(LOOP_MODES.indexOf(loopMode) + 1) % LOOP_MODES.length];
+    const next = LOOP_MODES[(LOOP_MODES.indexOf(loopMode) + 1) % LOOP_MODES.length]!;
     setLoopMode(next);
     persistPref({ playerLoop: next });
   };
@@ -303,21 +303,21 @@ export default function PlayerModal({
     if (!q || q.length === 0) return;
     const wrap = l === "all";
     if (a === "next") {
-      if (i < q.length - 1) setPlayingId(q[i + 1].id);
+      if (i < q.length - 1) setPlayingId(q[i + 1]!.id);
       else if (wrap) {
         if (q.length === 1) replayCurrent();
-        else setPlayingId(q[0].id);
+        else setPlayingId(q[0]!.id);
       }
     } else if (a === "prev") {
-      if (i > 0) setPlayingId(q[i - 1].id);
+      if (i > 0) setPlayingId(q[i - 1]!.id);
       else if (wrap) {
         if (q.length === 1) replayCurrent();
-        else setPlayingId(q[q.length - 1].id);
+        else setPlayingId(q[q.length - 1]!.id);
       }
     } else if (a === "random" && q.length > 1) {
       let r = i;
       while (r === i) r = Math.floor(Math.random() * q.length);
-      setPlayingId(q[r].id);
+      setPlayingId(q[r]!.id);
     } else if (a === "random" && wrap) {
       replayCurrent();
     }

frontend/src/components/PlaylistsRail.tsx

@@ -69,7 +69,7 @@ export default function PlaylistsRail({
       return;
     }
     if (selectedId == null || !playlists.some((p) => p.id === selectedId)) {
-      setSelectedId(playlists[0].id);
+      setSelectedId(playlists[0]!.id); // playlists is non-empty (the length guard above returns)
     }
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [playlists, selectedId, listQuery.data]);

frontend/src/components/PlexBrowse.tsx

@@ -183,7 +183,7 @@ export default function PlexBrowse() {
     if (!sentinelEl) return;
     const io = new IntersectionObserver(
       (entries) => {
-        if (entries[0].isIntersecting && hasNextPage && !isFetchingNextPage) fetchNextPage();
+        if (entries[0]?.isIntersecting && hasNextPage && !isFetchingNextPage) fetchNextPage();
       },
       { rootMargin: "600px" },
     );

frontend/src/components/PlexPlayer.tsx

@@ -54,7 +54,7 @@ function audioOrdForLang(streams: AudioStream[], lang: string): number | null {
   // absent (-1) or already the FIRST track (0, which the backend plays by default) → no override.
   // (Match by index, NOT the `default` flag — some files mark a non-first track default, which made
   // the restored language silently fall back to track 0.)
-  return i <= 0 ? null : streams[i].ord;
+  return i <= 0 ? null : streams[i]!.ord; // i > 0 here, so streams[i] exists
 }
 function subOrdForLang(subs: SubStream[], lang: string): number | null {
   if (!lang) return null; // "" = subtitles off
@@ -666,14 +666,14 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
     const streams = detail?.audio_streams ?? [];
     if (streams.length < 2) return;
     const idx = streams.findIndex((s) => s.ord === (audioRef.current ?? 0));
-    const next = streams[(idx + 1) % streams.length];
+    const next = streams[(idx + 1) % streams.length]!; // length >= 2 (guarded), so in-bounds
     changeAudio(next.ord === 0 ? null : next.ord);
   }, [detail, changeAudio]);
   const cycleSubtitle = useCallback(() => {
     const subs = (detail?.subtitle_streams ?? []).filter((s) => s.text);
     const order: (number | null)[] = [null, ...subs.map((s) => s.ord)];
     const i = order.findIndex((o) => o === subOrd);
-    changeSubtitle(order[(i + 1) % order.length]);
+    changeSubtitle(order[(i + 1) % order.length]!); // order always has [null, ...] → non-empty
   }, [detail, subOrd, changeSubtitle]);
   // Audio A/V-sync offset: persist immediately (for the slider) but debounce the session restart so
   // dragging doesn't respawn ffmpeg on every step.

frontend/src/components/PlexPlaylistView.tsx

@@ -406,7 +406,7 @@ export default function PlexPlaylistView({
     const set = new Set(keys);
     setItems((prev) => prev.filter((i) => !set.has(i.id)));
     try {
-      if (keys.length === 1) await api.plexPlaylistRemoveItem(playlistId, keys[0]);
+      if (keys.length === 1) await api.plexPlaylistRemoveItem(playlistId, keys[0]!);
       else await api.plexPlaylistRemoveBulk(playlistId, keys);
       invalidate();
     } finally {
@@ -560,7 +560,7 @@ export default function PlexPlaylistView({
           </button>
           {items.length > 0 && (
             <button
-              onClick={() => onPlay(order[0], order)}
+              onClick={() => onPlay(order[0]!, order)}
               className="inline-flex items-center gap-2 rounded-xl bg-accent px-4 py-2 font-medium text-white hover:opacity-90"
             >
               <Play className="h-5 w-5 fill-current" />

frontend/src/components/VideoEditor.tsx

@@ -101,7 +101,7 @@ export default function VideoEditor({ job, onClose }: { job: DownloadJob; onClos
     // the true length (e.g. 213.44 vs 213). Without this the untouched last segment stays short, so
     // the no-op guard (isFullSingle: end >= duration) reads false and enables a "Create" that files a
     // clip of an unmodified video and drops its tail. Only touches the untouched segment (end===srcDur).
-    setSegments((s) => (s.length === 1 && s[0].end === srcDur ? [{ ...s[0], end: d }] : s));
+    setSegments((s) => (s.length === 1 && s[0]!.end === srcDur ? [{ ...s[0]!, end: d }] : s));
   };
   const onTimeUpdate = () => {
     const v = videoRef.current;
@@ -124,7 +124,7 @@ export default function VideoEditor({ job, onClose }: { job: DownloadJob; onClos
     setSegments((segs) => {
       const i = segs.findIndex((s) => time > s.start + MIN_SEG && time < s.end - MIN_SEG);
       if (i < 0) return segs;
-      const s = segs[i];
+      const s = segs[i]!; // i >= 0 from findIndex, so segs[i] exists
       const b: Seg = { id: nid(), start: time, end: s.end, keep: s.keep };
       const next = [...segs.slice(0, i), { ...s, end: time }, b, ...segs.slice(i + 1)];
       return next;
@@ -133,18 +133,19 @@ export default function VideoEditor({ job, onClose }: { job: DownloadJob; onClos
   const moveBoundary = (bi: number, time: number) =>
     setSegments((segs) => {
       if (bi < 0 || bi >= segs.length - 1) return segs;
-      const lo = segs[bi].start + MIN_SEG;
-      const hi = segs[bi + 1].end - MIN_SEG;
+      // bi is in [0, length-2] here, so bi and bi+1 both index existing segments.
+      const lo = segs[bi]!.start + MIN_SEG;
+      const hi = segs[bi + 1]!.end - MIN_SEG;
       const tt = Math.max(lo, Math.min(hi, time));
       const copy = [...segs];
-      copy[bi] = { ...copy[bi], end: tt };
-      copy[bi + 1] = { ...copy[bi + 1], start: tt };
+      copy[bi] = { ...copy[bi]!, end: tt };
+      copy[bi + 1] = { ...copy[bi + 1]!, start: tt };
       return copy;
     });
   const deleteBoundary = (bi: number) =>
     setSegments((segs) => {
       if (segs.length < 2) return segs;
-      const merged = { ...segs[bi], end: segs[bi + 1].end };
+      const merged = { ...segs[bi]!, end: segs[bi + 1]!.end };
       return [...segs.slice(0, bi), merged, ...segs.slice(bi + 2)];
     });
   const toggleKeep = (id: number) =>
@@ -257,8 +258,8 @@ export default function VideoEditor({ job, onClose }: { job: DownloadJob; onClos
   const isFullSingle =
     segments.length === 1 &&
     kept.length === 1 &&
-    kept[0].start <= 0.01 &&
-    kept[0].end >= duration - 0.01;
+    kept[0]!.start <= 0.01 &&
+    kept[0]!.end >= duration - 0.01;
   const valid = kept.length >= 1 && keptDur >= MIN_SEG && (cropOn || !isFullSingle);
   const willJoin = output === "join" && kept.length > 1;
   const reencode = cropOn || accurate;
@@ -296,7 +297,7 @@ export default function VideoEditor({ job, onClose }: { job: DownloadJob; onClos
       }
       const N = kept.length;
       for (let i = 0; i < N; i++) {
-        const s = kept[i];
+        const s = kept[i]!; // i < N === kept.length, so kept[i] exists
         const spec: EditSpec = { trim: { start_s: +s.start.toFixed(3), end_s: +s.end.toFixed(3) } };
         if (cp) spec.crop = cp;
         else spec.accurate = accurate;

frontend/src/i18n/index.ts

@@ -23,6 +23,7 @@ for (const [path, mod] of Object.entries(mods)) {
   const m = path.match(/\/locales\/([a-z]{2})\/([a-zA-Z0-9_]+)\.json$/);
   if (!m) continue;
   const [, lang, area] = m;
+  if (!lang || !area) continue; // both groups are required by the regex; satisfies the checker
   (resources[lang] ??= { translation: {} }).translation[area] = mod.default;
 }
 

frontend/src/lib/descriptionLinks.tsx

@@ -14,7 +14,8 @@ const INLINE_RE =
 
 function tsToSeconds(ts: string): number {
   const parts = ts.split(":").map((n) => parseInt(n, 10));
-  return parts.length === 3 ? parts[0] * 3600 + parts[1] * 60 + parts[2] : parts[0] * 60 + parts[1];
+  const [a = 0, b = 0, c = 0] = parts; // hh:mm:ss or mm:ss — absent segments default to 0
+  return parts.length === 3 ? a * 3600 + b * 60 + c : a * 60 + b;
 }
 
 // Parse a YouTube `t`/`start` param: "90", "90s", or "1h2m3s".
@@ -44,7 +45,7 @@ function parseYouTube(url: string): { id: string; start: number | null } | null
     if (u.pathname === "/watch") id = u.searchParams.get("v");
     else {
       const m = u.pathname.match(/^\/(?:shorts|embed|live)\/([^/?#]+)/);
-      if (m) id = m[1];
+      if (m) id = m[1] ?? null;
     }
   }
   if (!id) return null;
@@ -128,7 +129,9 @@ export function renderDescription(
           </a>,
         );
       } else {
-        const ts = m[3];
+        // Reached only when neither m[1] (email) nor m[2] (hashtag) matched, so the third
+        // alternative — the timestamp group — is the one that fired.
+        const ts = m[3]!;
         out.push(
           <button
             key={key++}

frontend/src/lib/format.ts

@@ -33,7 +33,12 @@ export function formatSpeed(bps: number | null | undefined): string {
  * MUST stay sorted ascending, with the first row doubling as the "just now" threshold: sorting it
  * largest-first — the natural instinct — would make every timestamp under a year read "just now".
  * Module-level because it is constant, and exported so the tests can hold that invariant. */
-export const RELATIVE_UNITS: readonly [number, Intl.RelativeTimeFormatUnit][] = [
+// A non-empty tuple type (first element + rest) so `RELATIVE_UNITS[0]` is known-present under
+// noUncheckedIndexedAccess — the "sub-minute" branch relies on that first entry always existing.
+export const RELATIVE_UNITS: readonly [
+  [number, Intl.RelativeTimeFormatUnit],
+  ...[number, Intl.RelativeTimeFormatUnit][],
+] = [
   [60, "minute"],
   [3600, "hour"],
   [86400, "day"],

frontend/src/lib/linkify.tsx

@@ -62,10 +62,14 @@ export function linkify(text: string): ReactNode[] {
       const raw = m[1];
       out.push(link(/^https?:\/\//i.test(raw) ? raw : `https://${raw}`, raw));
     } else {
-      // "<platform>: @handle" — keep the "<platform>: " prefix as text, link only the handle.
-      const handle = m[3];
+      // Reached only when the MENTION alternative matched, so its groups are present: m[2] is the
+      // platform (always one of PLATFORMS' own keys — the pattern is built from them) and m[3] the
+      // handle. "<platform>: @handle" — keep the "<platform>: " prefix as text, link only the handle.
+      const platform = m[2]!;
+      const handle = m[3]!;
+      const base = PLATFORMS[platform.toLowerCase()]!;
       out.push(<Fragment key={key++}>{m[0].slice(0, m[0].length - handle.length - 1)}</Fragment>);
-      out.push(link(PLATFORMS[m[2].toLowerCase()] + handle, "@" + handle));
+      out.push(link(base + handle, "@" + handle));
     }
     last = m.index + m[0].length;
   }

frontend/src/lib/modules.ts

@@ -128,6 +128,7 @@ export function stepModule(me: Me, current: Page, dir: 1 | -1): Page {
   const order = moduleOrder(me);
   if (order.length === 0) return current;
   const i = order.indexOf(current);
-  if (i === -1) return dir === 1 ? order[0] : order[order.length - 1];
-  return order[(i + dir + order.length) % order.length];
+  // order is non-empty (guarded above) and every index below is in-bounds, so none are undefined.
+  if (i === -1) return dir === 1 ? order[0]! : order[order.length - 1]!;
+  return order[(i + dir + order.length) % order.length]!;
 }

frontend/src/lib/useUndoable.ts

@@ -54,7 +54,7 @@ export function useUndoable<T>(
   const undo = useCallback(() => {
     const s = ref.current;
     if (!s.past.length) return;
-    const prev = s.past[s.past.length - 1];
+    const prev = s.past[s.past.length - 1]!; // past is non-empty (guarded above)
     ref.current = {
       past: s.past.slice(0, -1),
       present: prev,
@@ -67,7 +67,8 @@ export function useUndoable<T>(
   const redo = useCallback(() => {
     const s = ref.current;
     if (!s.future.length) return;
-    const [next, ...rest] = s.future;
+    const next = s.future[0]!; // future is non-empty (guarded above)
+    const rest = s.future.slice(1);
     ref.current = { past: [...s.past, s.present], present: next, future: rest };
     force();
     onApplyRef.current?.(next);

frontend/tsconfig.json

@@ -14,7 +14,8 @@
     "strict": true,
     "noUnusedLocals": true,
     "noUnusedParameters": true,
-    "noFallthroughCasesInSwitch": true
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true
   },
   "include": ["src"],
   // Editors resolve a file to the nearest tsconfig that INCLUDES it; vite.config.ts / vitest.config.ts