feat(plex): subtitles rise above the control bar while it shows

On an iPad the bar covered the text whenever it was up: the browser places a
native cue by its line, which nothing animates. The track now stays loaded as
hidden and PlexSubtitles draws the active cues, measured against the bar and
lifted above it in 200 ms, back down when it hides. The viewer's size, colour,
background and outline settings style the text directly. Also fixes a test
typing slip from the search pill change.

frontend/src/components/PlexSubtitles.tsx

@@ -0,0 +1,157 @@
+import { useEffect, useLayoutEffect, useRef, useState, type RefObject } from "react";
+import { subShadow } from "../lib/plexPlayerPrefs";
+
+// The Plex player's subtitles, drawn by us instead of the browser. The track stays mounted (hls.js and
+// the VTT fetch need it) but `hidden`: the browser parses the cues and reports the active ones, and
+// this layer shows them. The browser's own rendering could not move out of the way of the control
+// bar — a cue is placed by `line`, which neither WebKit nor Chromium animates, and on an iPad the bar
+// covered the text whenever it was up. Here the text rises above the bar while it shows and slides
+// back when it hides, the same on every engine, and the viewer's size / colour / background / outline
+// settings style it directly.
+
+type Cue = TextTrackCue & { text?: string; getCueAsHTML?: () => DocumentFragment };
+
+// A cue's default type size, as both engines draw it: 5 % of the video box's height.
+const CUE_EM_OF_HEIGHT = 0.05;
+// The air left between the text and what it avoids (the bar's top, or the video's bottom edge).
+const CLEARANCE_PX = 8;
+
+/** The cues showing now, from every track of `video` that is not switched off. */
+function useActiveCues(video: HTMLVideoElement | null): Cue[] {
+  const [cues, setCues] = useState<Cue[]>([]);
+  useEffect(() => {
+    if (!video) return;
+    const tracks = video.textTracks;
+    const read = () => {
+      const now: Cue[] = [];
+      for (const tr of Array.from(tracks)) {
+        if (tr.mode === "disabled") continue;
+        for (const c of Array.from(tr.activeCues ?? [])) now.push(c as Cue);
+      }
+      setCues((prev) =>
+        prev.length === now.length && prev.every((c, i) => c === now[i]) ? prev : now,
+      );
+    };
+    const bound = new Set<TextTrack>();
+    const bind = (tr: TextTrack) => {
+      if (bound.has(tr)) return;
+      bound.add(tr);
+      tr.addEventListener("cuechange", read);
+    };
+    for (const tr of Array.from(tracks)) bind(tr);
+    const onAdd = (e: Event) => {
+      const tr = (e as TrackEvent).track;
+      if (tr) bind(tr as TextTrack);
+      read();
+    };
+    tracks.addEventListener("addtrack", onAdd);
+    tracks.addEventListener("removetrack", read);
+    read();
+    return () => {
+      tracks.removeEventListener("addtrack", onAdd);
+      tracks.removeEventListener("removetrack", read);
+      for (const tr of bound) tr.removeEventListener("cuechange", read);
+    };
+  }, [video]);
+  return cues;
+}
+
+/** The video box's height, followed as the window or fullscreen changes it. */
+function useHeight(el: HTMLElement | null): number {
+  const [height, setHeight] = useState(0);
+  useEffect(() => {
+    if (!el) return;
+    const measure = () => setHeight(el.clientHeight);
+    measure();
+    const ro = new ResizeObserver(measure);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [el]);
+  return height;
+}
+
+/** One cue's text. `getCueAsHTML` keeps its <i>/<b>; it builds DOM nodes from the parsed cue, never
+ *  markup from a string, so nothing in a subtitle file can run. */
+function CueText({ cue, style }: { cue: Cue; style: React.CSSProperties }) {
+  const ref = useRef<HTMLSpanElement>(null);
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    if (typeof cue.getCueAsHTML === "function") el.replaceChildren(cue.getCueAsHTML());
+    else el.textContent = cue.text ?? "";
+  }, [cue]);
+  return (
+    <span
+      ref={ref}
+      style={style}
+      className="whitespace-pre-line px-[0.25em] leading-[1.3] box-decoration-clone"
+    />
+  );
+}
+
+export default function PlexSubtitles({
+  video,
+  pos,
+  size,
+  color,
+  background,
+  shadowPx,
+  shadowColor,
+  avoid,
+  avoidRef,
+}: {
+  video: HTMLVideoElement | null;
+  /** Where the text's top sits, in % of the video box's height (the setting's "cue line"). */
+  pos: number;
+  size: number;
+  color: string;
+  background: string;
+  shadowPx: number;
+  shadowColor: string;
+  /** True while the control bar shows: the text then keeps above `avoidRef`'s top. */
+  avoid: boolean;
+  avoidRef: RefObject<HTMLElement | null>;
+}) {
+  const cues = useActiveCues(video);
+  const height = useHeight(video);
+  const boxRef = useRef<HTMLDivElement>(null);
+  const [lift, setLift] = useState(0);
+  const liftRef = useRef(0);
+
+  // How far up the text has to move to clear the bar (or, without it, the video's bottom edge). The
+  // box is measured where it would sit with no lift: its current rect plus the lift it carries now.
+  useLayoutEffect(() => {
+    const box = boxRef.current;
+    if (!box || !video || cues.length === 0) return;
+    const bottom = box.getBoundingClientRect().bottom + liftRef.current;
+    const bar = avoid ? avoidRef.current?.getBoundingClientRect().top : undefined;
+    const limit = (bar ?? video.getBoundingClientRect().bottom) - CLEARANCE_PX;
+    const next = Math.max(0, Math.round(bottom - limit));
+    liftRef.current = next;
+    setLift(next);
+  }, [avoid, avoidRef, cues, height, pos, size, video]);
+
+  if (cues.length === 0 || height === 0) return null;
+  const text: React.CSSProperties = {
+    color,
+    backgroundColor: background,
+    textShadow: subShadow(shadowPx, shadowColor),
+  };
+  return (
+    <div
+      ref={boxRef}
+      data-testid="plex-subtitles"
+      aria-hidden="true"
+      className="pointer-events-none absolute inset-x-0 flex flex-col items-center gap-[0.15em] px-[5%] text-center transition-transform duration-200 ease-out motion-reduce:transition-none"
+      style={{
+        top: `${pos}%`,
+        fontSize: `${(height * CUE_EM_OF_HEIGHT * size) / 100}px`,
+        transform: `translateY(${-lift}px)`,
+      }}
+    >
+      {cues.map((cue, i) => (
+        <CueText key={`${cue.startTime}-${i}`} cue={cue} style={text} />
+      ))}
+    </div>
+  );
+}