meshbay.git/docs/mediacenter.md, branch 0.16

docs: remove the documents MESHBAY_DESIGN.md replaces

2026-09-10T22:19:06Z

Twenty-four files, about 17 000 lines: the two architecture drafts, the three security reviews, eleven design notes, the roadmap, the decisions file, the v1–v4 archive, the deprecated user guide and the stale quickstart. Their content is in MESHBAY_DESIGN.md, and git history holds the originals. The reason to delete rather than keep bannered: a document that is superseded but present still gets read, and a reader cannot always tell which of two accounts of one mechanism is the live one. That was the argument for retiring the user guide rather than repairing it, and it applies to the whole set. What made this safe is the concordance. Roughly 290 comments and docstrings cite these files by section — `musicbay.md §6`, `mediacenter.md §5.5`, `draft-v6 §2.11` — and section 16 maps every one onto its replacement, so not a single comment needs editing to stay followable. It now says plainly that the files are gone and where to recover them, and it gained rows for the three reviews (their findings are section 13), and for the two guides. Four kept documents pointed into the set and were repointed first: `playlists.md` (nine references — it is a live proposal and must not dangle), `WINDOWS-PORT.md`, and CLAUDE.md's example. No dangling reference remains outside section 16. Two files were dropped from the list after checking what they hold. `HTTPS.md` is an operational runbook — Caddy, certificate renewal, DNS, troubleshooting — and MESHBAY_DESIGN.md deliberately covers no operations, so nothing would replace it; the versioned Caddyfile is the config, not the procedure. `cast-smart-tv.md` is the plan for the unbuilt DLNA phase of a feature whose first two phases ship, and section 11.4 summarises it in four lines rather than carrying the SSDP/UPnP work. There is no user guide now, and section 0.1 says so rather than leaving a reader to discover it. Suites green: 2258 passed, 4 skipped. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01YVoHVCcfBqud6ZjG4db3y7

docs: point the superseded drafts at the design document

2026-09-10T16:45:03Z

Twenty-three documents that MESHBAY_DESIGN.md absorbs gain a header saying so and naming the sections their content went to. None is deleted: code comments, tests and the documents themselves cite their sections and their labels, and each records reasoning a synthesis compresses. The header states the precedence, because two documents describing one system will disagree eventually: where a draft disagrees with MESHBAY_DESIGN.md the design document is right, and where either disagrees with the code the code is. Seven status lines were corrected on the way through, all of them claiming less than the truth. Videos, Music, Photos, partial-read hashing and account recovery were headed "proposal, not implemented" months after they shipped; the desktop client said "nothing here is implemented" with stages A through D running; draft v6 still called itself the current specification. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01YVoHVCcfBqud6ZjG4db3y7

fix(hub): stop badging every poster "unmatched" when TMDB is off

2026-09-08T00:17:00Z

The dashed warning outline and the "?" flag say a TMDB lookup ran and came back with nothing — that is how an operator finds the titles worth a "Fix match". With TMDB switched off for the group no lookup is made at all: media_meta_req answers confidence 0 for the whole library by design, so the poster grid drew every card as a failure of the very thing the operator chose, with no poster ever coming to clear it. Poster mode now shows the file's own thumbnail plainly in that case, the same as Flat does, and keeps the badge for what it was built for. - PosterCard takes tmdbEnabled and gates both the outline and the "?" on `tmdbEnabled && !confident`. The title still falls back to the parsed filename exactly as before, and the ready/imageReady anti-flash gating is untouched. - VideoDetailModal gates its "no confident match" paragraph the same way. A show still opens that modal with TMDB off — it is where the season list lives — so the card alone would have left the claim one click deeper. - Its operator-only "Fix match" / "Rematch" buttons are gated too: both act on a match that does not exist, one opening a search the node answers empty, the other dropping a cached match never made. Those buttons are the only entry points to TmdbSearchOverlay and doRematch. - Both props default to true, so a call site that forgets one keeps the badge rather than silently losing it. search-page.js is deliberately left passing `enabled: true`: a cross-group view has no single group's switch to read, and it never showed the operator buttons anyway (isNodeAdmin={false}). Recorded as §10.7 in docs/mediacenter.md. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01V8EDjk6pkYZrCbo63m2x87

fix(hub): stop the maintenance loop racing the tests, and pin _ASSETS

2026-09-02T15:31:50Z

Two defects found while closing out the Search merge, neither of them in that feature. The maintenance loop. create_app's lifespan starts cleanup_loop as an asyncio task, so every test — each entering that lifespan — ran a purge pass concurrently with its own requests. On SQLite :memory: that is not merely noisy: the engine uses a StaticPool, one connection for the whole process, so the request's session and the cleanup task's session interleave transactions on the same connection. A registration could commit and then be invisible to the login three lines later, surfacing as 401 Invalid credentials for an account created moments before, in roughly one run of test_node_ws_auth.py in four. The purge itself is not at fault and this is not a production condition. A passive SQL listener caught the DELETE removing 0 rows, and the INSERT carrying status='active' — so neither the pending-account mechanism nor the purge filter is involved, and PostgreSQL gives every session its own connection. What the fixture removes is the second user of the shared one. 60 runs of the previously flaky file, 0 failures; reproductions before the fix landed on attempts 4, 6, 13 and 29 of separate loops, so a clean run of 60 has about a 1% chance of being luck. _ASSETS. source-merge.js shipped missing from webapp._ASSETS, the cache-busting hash's input list — exactly the silent failure docs/apps.md §4 step 5 warns about: the file changes, the asset URL does not, and a browser holding the old page keeps the old copy. Harmless this time only because search-page.js changed in the same commit and is listed, which is the worst way for it to go unnoticed. Found by re-reading that checklist for the doc pass, not by any test — so there is a test now, holding _ASSETS to every .js in static/ (sw.js excepted, unversioned on purpose). It was the only one missing. Phase 9 of docs/refactoring-search.md also lands here: mediacenter.md §10.6, musicbay.md §9b, photos.md §10b, apps.md §2b and step 5. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01AbwJDbNTkiRUh7HTWEoyss

fix(hub): a show opens on its first season, not its first thumbnail

2026-09-02T08:00:23Z

Reported live: a show with a dozen seasons opened on season 6. Every season was in the picker and none was missing — the default was wrong. VideoDetailModal took it from `repEntry.season`. `repEntry` is the show's "representative entry", which the poster grid picks as `episodes.find((e) => e.thumb_hash) || episodes[0]`: the first episode that has a thumbnail, so the card has a fallback frame when TMDB has no poster. That is from the original Videos commit; the season tabs came later and read the same entry as "the episode the reader is looking at", which it never was on that path. Episodes are sorted by (season, episode), so a show whose first five seasons had no thumbnail yet — a partial enrichment pass, or ffmpeg failing on those files — hands back a season-6 episode. `defaultSeason(show)` reads the season list and nothing else: the lowest season present, specials only when there is nothing else, and the lowest *number* rather than the first entry so it does not quietly depend on buildSeasons keeping its sort. The effect's dependency on repEntry goes with it — nothing in it reads that any more. test_video_default_season.py runs the function in node. No input it takes can carry a thumbnail, which is the point. docs/mediacenter.md §10.5. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_014UtzVrzM7e2tG9fSpkR9ML

fix(hub): the show detail modal must not move when the season does

2026-09-02T07:49:41Z

The previous pass fixed the synopsis and the cast, and the dialog still jumped: the episode count moves things a fixed-height synopsis cannot reach. - The body scrolled as a whole, so a thirteen-episode season pushed the modal to its max-height where a six-episode one had not. `.video-overlay` centres its child, so the taller modal also *started higher up the screen* — title bar, close button and all. `.video-detail-steady` (a multi-season show only) gives the modal a height rather than a max-height, makes the body a flex column, and hands the leftover to the episode list as the one scrolling part. A constant-height box is centred in the same place every time, so both halves settle at once. - A scrolling season draws a scrollbar where a non-scrolling one draws none, which is a scrollbar's width of content and re-wrapped the file path above it, shifting everything below by a line. `scrollbar-gutter: stable`. - The season panel was clipped by the modal's own `overflow: hidden` whenever the seasons outran the room under the picker — at a 740px viewport it wanted 320px and had 288, and the rest sat where no scroll could reach it. It is `position: fixed` now, placed by `placeSeasonPanel()`, which takes the trigger's rect and the window height, picks whichever side has more room, and caps the panel to it. Scoped to multi-season shows throughout: a movie has no season to switch to and a fixed height would buy it nothing but empty space. test_video_detail_measured.py now builds each block inside a real `.video-overlay`, since the centring is half the defect, and asserts the modal top and height as well as the picker's offset — for a long and a short synopsis and for a six- and a twenty-four-episode season. test_season_panel_placement.py runs placeSeasonPanel() in node over a rect and a window height. Two guards are declarations rather than rectangles and say so in their docstrings: headless Chrome gives the probe zero-width overlay scrollbars, so the gutter cannot be measured there. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_014UtzVrzM7e2tG9fSpkR9ML

fix(hub): steady the show detail modal, and give a series its director

2026-09-02T01:23:46Z

Opening a different season of the same show moved everything under the synopsis, which is where the season control and the episode list are, so the thing just clicked was no longer under the pointer. - The synopsis is exactly three lines for a multi-season show, with a "read more" link floated into the third line box (-webkit-line-clamp only ever puts its ellipsis at the end of the last line and leaves no room after it). Clamped from above and pinned from below to the same number: a constant, not a range — a season summary runs two lines and the next one twelve, and a band still reads as a jump. Whether three lines is all of it depends on the modal's width, so it is measured in the browser and re-measured on a resize. - The cast is clamped to two lines. - SeasonMenu replaces SeasonTabs: the tab row scrolled sideways once a show had more seasons than fit, which is close to unusable on a phone. One trigger reading "Season 5 · 1997" and a menu of every season with its episode count, one row high whatever the season count. - media_meta_resp.director was filled from the credits crew's job == "Director", a movie shape. TMDB's aggregate tv_credits crew is routinely empty and never carries that job, so every show answered null and the modal dropped the line. It now comes from created_by on the show details. Cached show metadata keeps its null until TMDB_META_TTL_SECS expires or an operator re-matches. The facts line is joined rather than concatenated (a title with no rating used to open with " · ") and carries the show's own year next to the director; the selected season's air year moved onto the picker. test_video_detail_measured.py asserts rectangles through layout_probe.py, not declarations: the picker's offset inside its own modal body is the same pixel either way, the synopsis and cast heights, where the read-more link lands, and the open menu at 320 px. Each measured block sits in a whole-pixel-height container, or two identical layouts an eighth of a pixel apart round to tops one pixel apart. test_tmdb_show_director.py covers the credit. docs/mediacenter.md §10.4. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_014UtzVrzM7e2tG9fSpkR9ML

chore: scrub copyrighted names from tests, comments and docs

2026-08-30T15:05:15Z

Real franchise / show / release-group names had crept back into test fixtures, code comments, a docstring and docs/mediacenter.md while fixing the saga-match and misclassification bugs. Replace them all with invented placeholders ("Some Saga", "A Different Show") and shape descriptions ("a franchise-origin film", "a 3-season show"). Behaviour and assertions unchanged; 738 node tests still pass. Record the rule in CLAUDE.md so it stops recurring. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_018BMLQjqFGCize2KtNBT79v

fix(node): stop a numbered saga all matching its first film

2026-08-30T14:31:34Z

Every " Episode - " file in a numbered franchise resolved to the series' first entry (a real, older film). `sequel_variants` stripped "Episode " and offered the bare "" as a candidate query; that matches the first film's original_title at ratio 1.0 and beat PASS 1's correct-but-lower hit. A franchise's bare name is very often a real, different film. When a Part/Episode/Chapitre/… keyword carried the index, sequel_variants no longer emits the bare base — only " " and " ". Without a keyword (" 3") the bare base is still offered, so that fix is untouched. Verified live against TMDB: the franchise's episodes each resolve to their own entry; the earlier numbered-sequel, two-part-film and franchise-subtitle regressions all hold. docs/mediacenter.md §10.3. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_018BMLQjqFGCize2KtNBT79v

revert(hub): drop the poster-grid movie merge (V12)

2026-08-30T14:13:47Z

V12 collapsed movies that TMDB resolved to the same tmdb_id into one card. With the matcher still imperfect that fuses *different films*: every numbered entry of a saga whose bare title resolves to the same base id becomes one card, and two unrelated movies sharing a title do too (seen live on a 9-film saga and a 2-film pair). A tmdb_id-keyed merge only works once matching is reliable, which it is not yet. Movies render one card per file again; VideoDetailModal loses the `files` prop and the versions list, back to a single Play button; `.video-version-list` and the `video.versions` key (×10 locales) are removed. mergedShows (V6) is untouched — the operator's report was about movies. docs/mediacenter.md §10.1: V12 un-struck, marked reverted. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_018BMLQjqFGCize2KtNBT79v