chore(comments): drop epic, sprint and review-round ids from the code

The code cited its plan instead of saying why: `E28 review J4`, `(R6 S3b)`, `S1 justified…`,
`deep-review round 5`. That plan lives in the private ops repo, so for every reader of this one the
citation was noise, and a sentence whose subject was the plan step ("round 2 showed…") hid its
lesson behind an id. Each one is gone and the "why" kept: a bare citation is deleted, a sentence
carrying a lesson is reworded around it ("a later attempt showed…").

Measured (`scripts/audit_metrics.py`, product code): 652 lines in 270 files carried an epic code by
the definition the next commit holds (507 / 241 by the old, two-digit-only one) -> 0. Across all
code, tests, scripts and configs: ~1100 epic-code lines plus ~320 sprint/round ids.

Behaviour unchanged, checked mechanically: every changed .py file has the same AST once docstrings
are blanked; css/sh/toml/yml/json files are identical once comments are stripped; the only
non-comment changes in TS/JS are test titles, one description string in a contract table, and five
ESLint messages, whose text is all the gates snapshot diff holds. Not touched: Markdown (docs and
the changelog keep their history), Alembic migrations, TV episode notation (`S2 · E5`), DESIGN.md
ids (`C1`, `B4`, `S3h`), tracker ids (`SEC-16`, `DX-17`).

One stale claim fixed on the way: test_hls_reaper's docstring said the player checkpoints "every
10 s whether or not it is playing", which plex/stream.py calls wrong; it now says what the code does.
This commit is contained in:
2026-10-05 00:19:39 +02:00
parent c73d8be094
commit 4aaaaa7860
669 changed files with 1831 additions and 1904 deletions
+11 -11
View File
@@ -18,7 +18,7 @@ import {
import { useFullscreenPortalHost } from "../../lib/fullscreen";
import type { useAnchoredPopover } from "./anchoredPopoverHooks";
// R8 popover platform. ONE anchored-popover primitive over @floating-ui/react, replacing the ~9
// The popover platform. ONE anchored-popover primitive over @floating-ui/react, replacing the ~9
// hand-rolled positioning engines (measured flip / width clamp / rAF scroll-follow / scroller-relative
// visibility) that had each re-derived the same maths. Floating UI's middleware does all four:
// - flip() → measured two-way flip (top/bottom) when a side runs out of room
@@ -28,9 +28,9 @@ import type { useAnchoredPopover } from "./anchoredPopoverHooks";
// - autoUpdate → follows the trigger on scroll/resize (the old rAF loop), coalesced by the library
// Positioning is portalled through FloatingPortal (escapes ancestor stacking contexts — same job the
// house <Overlay> did for TagsCell). Every popover is a node in the app's <FloatingTree> so Escape /
// outside-press dispatch is topmost-only across nested layers (S3 folds the Modal + players in too).
// outside-press dispatch is topmost-only across nested layers (the Modal and players included).
//
// S2 (this layer) adds the keyboard/ARIA model the roles promise, mirroring `ViewSwitcher` (the house's
// This layer adds the keyboard/ARIA model the roles promise, mirroring `ViewSwitcher` (the house's
// textbook menu) but via Floating UI's idioms rather than a second hand-rolled roving engine:
// - useListNavigation → roving focus over the registered items (↑/↓/Home/End, loop), menu/listbox only;
// PageUp/PageDown (a page, no loop) are ours, for every list surface incl. the combobox
@@ -45,9 +45,9 @@ import type { useAnchoredPopover } from "./anchoredPopoverHooks";
//
// The trigger takes its ref DESTRUCTURED: `const { setReference } = pop.refs;` then
// `ref={setReference} {...pop.getReferenceProps()}`. Written `ref={pop.refs.setReference}`, the React
// Compiler treats the whole `pop` as a ref and skips the component (E32 S3 — 21 call sites did).
// Compiler treats the whole `pop` as a ref and skips the component (21 call sites once did).
//
// S? adds a "combobox" mode — the ONE right way to build a typeable combobox (a search/filter input
// A "combobox" mode — the ONE right way to build a typeable combobox (a search/filter input
// with a listbox of options below), so a hand-rolled floating-ui engine (the old MultiSelectChips /
// PlexSearchBox pattern) is no longer needed. It differs from menu/listbox in exactly the focus model:
// - the trigger IS a text input, so open is driven by the caller (focus/typing), NOT useClick;
@@ -93,7 +93,7 @@ type ItemRole = "menuitem" | "menuitemradio" | "menuitemcheckbox" | "option";
* key. (Since the Tailwind v4 migration `bg-accent/NN` works — v4 does the opacity modifier via
* color-mix — so the recipe no longer needs a hand-written color-mix arbitrary value.) */
// The roving-focus highlight. A hovered/roving row gets the SAME strong accent fill whether or not it
// is selected — a checked row no longer reads as a weak ring-only afterthought (R10 weak-ring fix). The
// is selected — a checked row no longer reads as a weak ring-only afterthought. The
// selected state stays legible ON the fill because these menus mark "selected" with a CHILD element (a
// checkmark / checkbox) that paints over the row tint; the selected row just gets a stronger ring
// (ring-2, accent/80) than an unselected one (ring-1, accent/60) to keep the two apart.
@@ -242,7 +242,7 @@ interface PopoverSurfaceProps {
passthrough?: boolean;
/** The panel's role (a combobox's `listbox`) goes on an inner `<PopoverList>` instead of the panel
* itself, so the panel can also hold lines ABOUT the list — loading, nothing found, a failed load
* with its Retry — outside it: a listbox may own options only (round 2, F4). */
* with its Retry — outside it: a listbox may own options only. */
listInside?: boolean;
}
@@ -308,7 +308,7 @@ function PopoverSurfaceInner({
// handled by the element-identity dependency. (Keying the portal to remount instead would rebuild
// the subtree and lose all of that.) Focus does NOT survive on its own — `appendChild` on an
// already-parented node is remove-then-insert, which blurs to <body>; the hook saves and restores
// it. This used to be a second copy of Modal's re-parent that lacked exactly that (round 5).
// it. This used to be a second copy of Modal's re-parent that lacked exactly that.
const container = useFullscreenPortalHost();
const { style: floatingPropStyle, ...floatingProps } = getFloatingProps() as {
@@ -336,7 +336,7 @@ function PopoverSurfaceInner({
// but when that element is not a Tab stop itself, to its first TABBABLE descendant instead, even
// when handed the element as a ref (its return runs through `getFirstTabbableElement` either way).
// A card the keyboard is on (lib/listNav gives its root tabindex=-1) is exactly that: measured in
// Chrome (deep-review E11 round 2), j, Shift+F10, Escape left focus on the card's thumbnail link, the
// Chrome, j, Shift+F10, Escape left focus on the card's thumbnail link, the
// ring off the card and the next Enter on a control. So for such an element the library's return is
// off and this gives the focus back to it as it is — captured at open, before focus moves into the
// panel, and only when the focus was still in a floating layer (or nowhere) as the panel closed:
@@ -345,7 +345,7 @@ function PopoverSurfaceInner({
//
// Only for a focus-managed surface, whose return this replaces: a hover card or a combobox never
// returned focus, and a hover card closing after the reader clicked a link in it must not pull the
// focus back to the card under it (deep-review E11 round 3).
// focus back to the card under it.
const [returnTo] = useState(() => {
const active = document.activeElement;
return managed &&
@@ -360,7 +360,7 @@ function PopoverSurfaceInner({
return () => {
// "Still in the layer" is read off the portal marker, not the panel: FloatingPortal renders the
// panel a commit after this surface mounts, so the panel's ref is still empty when this effect
// runs (deep-review E11 round 3).
// runs.
const active = document.activeElement;
const stillOurs =
!active || active === document.body || !!active.closest("[data-floating-ui-portal]");