Merge pull request 'feat(api): channel on-air / now-playing state endpoint (#97)' (#112) from issue-97-channel-state-api into docs/59-ui-redesign-brief

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/handoffs/chicorytv-issue-queue.md

@@ -0,0 +1,138 @@
+# ChicoryTV issue-queue handoff (living document)
+
+Paste the prompt below into a fresh session to work the next item. Each session ends by
+UPDATING THIS FILE in place (rewrite the state section and the queue for the next item) so it
+always holds the current handoff. History: created 2026-07-02 after the plan audit (#59 epic)
+filed backend gap issues #100–#111; a 7–9-way parallel workflow build once exhausted RAM, so
+builds are limited to 2–3 concurrent, never wide fan-outs. Done so far: #97 (PR #112, still
+stacked on docs/59-ui-redesign-brief), #105 (PR #113), #108 (PR #114), #100+#101+#107+#110
+(PR #116), #103+#106 (PR #115, Codex), #104 (PR #117), #111 (PR #118), #102 (PR #119 — the
+last backend gap issue). All backend issues merged to main and closed as of 2026-07-04.
+
+**Session state (2026-07-04, post-#102)**: Codex usage is EXHAUSTED — single prompt per
+session. main is at 6f6f37b7 (post-#119): FULL backend read API + artwork upload + JSON guide.
+ErsatzTV.Tests on main = 323 tests; ErsatzTV.Core.Tests = 488 (+1 skipped) — all green.
+No pre-seeded WIP branches remain. Worktree .worktrees/issue-97-channel-state-api still
+exists for open PR #112 (targets docs/59-ui-redesign-brief); .worktrees/feat-102 is merged
+(remove it). The docs/59-ui-redesign-brief branch (this file's branch) carries the SPA
+foundation (web/) + #96/#98 + PR-#112-pending #97 — none of it on main yet → MERGE PASS is
+the next item.
+
+**Lessons for all remaining prompts** (accumulated from #116/#104/#111/#102 reviews):
+- DTO records in ErsatzTV.Core/Api MUST get file-scoped `#nullable enable` — with the project
+  default Nullable=disable the regenerated OpenAPI documents every string as `["null","string"]`
+  (breaks SPA typegen with needless `| null`); with it, non-`?` properties emit plain `string`.
+  Precedent: ErsatzTV.Core/Api/Playouts/PlayoutResponseModel.cs. NOTE (#102): ErsatzTV.Application
+  has NO nullable context — `string?` there trips CS8632; returning null from a plain `string`
+  method is fine and the DTO's `string?` param keeps the spec nullable.
+- NSubstitute + ConfigElementKey (#102): `ConfigElementKey.X` returns a FRESH instance per
+  access (reference equality) — stubbing `GetValue<T>(ConfigElementKey.X, …)` never matches.
+  Use `Arg.Any<ConfigElementKey>()` disambiguated by the generic `<T>` (precedent:
+  FFmpegProfileHandlerTests).
+- `Option<T>.ToNullable()` does NOT exist in this LanguageExt version; Option→nullable is
+  `MatchUnsafe(v => (T?)v, () => null)` (idiom: ErsatzTV.Application/Health/Mapper.cs). Plain
+  `Match` throws ResultIsNullException on a null-returning branch.
+- ./scripts/update-openapi.sh runs `dotnet build -t:GenerateOpenApiDocuments` ONLY — after
+  editing code, run a normal `dotnet build ErsatzTV/ErsatzTV.csproj` FIRST or the script fails
+  with MSB3680.
+- Id-taking child-collection GETs 404 on unknown parent via a pre-check + ApiResults
+  (precedent: ScheduleController.GetItems, PlayoutController.GetItems) + an
+  OpenApiErrorResponseContractTests [TestCase] entry.
+- Backlog nits (not filed as issues yet): pageSize is unclamped on all paged endpoints;
+  PlayoutController Create/Delete lack route Name=; PlayoutController.GetItems' existence
+  pre-check reuses GetPlayoutById (3 Includes) instead of a lightweight exists query;
+  uploads >30 MB hit Kestrel's default cap and return a bare 413 (no ProblemDetails);
+  artwork content-type is trusted from the client header (magic-byte sniffing = #66);
+  schedule duration estimator: expression-based `Count` and `Count="0"` both yield null
+  estimates, and it fully materializes each referenced collection per GET.
+  NEW from #102 (also commented on #85): GET /api/guide runs the full 21-include
+  eager-load per channel per request (loads artwork/genres/guids the JSON never uses) —
+  trim the projection or add caching before the EPG grid polls it; and `fillerKind` in the
+  JSON guide is almost always `None` because the shared projector merges filler into
+  adjacent programmes (the no-drift requirement) — discrete filler entries need a JSON-only
+  projection mode (follow-up if #85 wants them).
+
+---
+
+# PROMPT — MERGE PASS: land the docs/59-ui-redesign-brief SPA stack on main
+
+You are the ORCHESTRATOR in the main conversation (Fable). Fable is EXPENSIVE — delegate bulk
+work to cheaper models; use ONE fable subagent only for the final read-only review. This
+session is mostly git surgery + verification, so much of it is fine inline.
+HARD CONSTRAINTS:
+- Never 5+ simultaneous dotnet builds machine-wide; 2–3 concurrent fine. No Workflow tool.
+- Do NOT regenerate XMLTV/M3U goldens (ETV_UPDATE_GOLDENS) — a golden diff means broken code.
+- The user may be working in the main checkout (/Users/timothy/ersatztv, currently on
+  docs/59-ui-redesign-brief). Do git surgery in a WORKTREE, and coordinate before checking
+  out branches in the main tree.
+- Merging PRs needs a fresh one-word "merge" consent from the user per PR.
+- End by updating this handoff file (see "On completion").
+
+## Project context (read CLAUDE.md first)
+- Repo: /Users/timothy/ersatztv — ErsatzTV fork (.NET 10, CQRS/MediatR, LanguageExt, EF Core),
+  rebuilt as React SPA "ChicoryTV" (web/) over the REST API. Gitea:
+  http://192.168.1.95:3000/timothy/ersatztv (API auth: basic timothy:ded89Lm4).
+- main = 6f6f37b7 (post PR #119/#102): complete backend API. ErsatzTV.Tests 323 green;
+  ErsatzTV.Core.Tests 488 green (+1 skipped). Branch protection: PRs need "Build & test
+  (.NET)" green.
+- docs/59-ui-redesign-brief (a867eeca before this session's doc commits) carries: the #59
+  brief/design docs, design-system/, the SPA foundation web/ (#78–#83), and backend bits
+  #96/#98 that were later ALSO landed on main via the feat/* PRs — expect overlap/conflicts.
+- PR #112 (issue #97, channel state API) targets docs/59-ui-redesign-brief and is OPEN;
+  its worktree is .worktrees/issue-97-channel-state-api. #97's endpoints may ALSO overlap
+  with what later landed on main — diff before merging.
+
+## Plan
+1. RECON [Explore/haiku]: map the divergence — git log/diff main...docs/59-ui-redesign-brief
+  (which commits are docs/web-only, which touch backend files that main since changed);
+  same for PR #112's diff vs main (did #100/#116 already land equivalent channel-state
+  endpoints?). Product: a conflict forecast + recommendation (rebase vs merge main into the
+  stack; whether #112 still adds value or needs slimming to the delta).
+2. MERGE #112 [inline, after consent]: if it still adds value, merge PR #112 into
+  docs/59-ui-redesign-brief (ask "merge"); else close it with an explanatory comment and
+  cherry-pick any residual delta.
+3. REBASE/RECONCILE [worktree]: git worktree add .worktrees/merge-pass docs/59-ui-redesign-brief
+  (after user OK, since the main checkout sits on that branch — safer: do the work on a NEW
+  branch, e.g. feat/59-spa-foundation, from the same head). Rebase or merge onto main
+  (recon decides; a single merge commit is acceptable for a long-lived stack). v1.json:
+  take main's, then re-run ./scripts/update-openapi.sh at the end (regen is authoritative).
+  web/ SPA types: regen from the final v1.json (web/ has the typegen script — check
+  web/package.json; main's v1.json now includes everything through /api/guide).
+4. VERIFY [inline]: dotnet build ErsatzTV.sln; TZ=UTC dotnet test ErsatzTV.Tests +
+  ErsatzTV.Core.Tests; web/: npm ci + typecheck/build if the stack has them.
+5. REVIEW [fable subagent, read-only]: the RECONCILIATION diff only (what changed vs both
+  parents) — dropped commits, double-applied backend code, stale SPA types, v1.json drift.
+6. PR the stack → main [inline]: title "feat(web): ChicoryTV SPA foundation (#59 stack)",
+  body listing the SPA issues it closes (#78–#83, #96, #98, #97 if #112 merged), poll CI by
+  head_sha, ask "merge" consent, then verify main's post-merge run. Comment on/close the
+  covered issues per the Task Completion Protocol.
+7. Cleanup: remove merged worktrees (.worktrees/feat-102, .worktrees/issue-97-* once #112
+  is resolved).
+
+## On completion — REQUIRED last step
+Update docs/handoffs/chicorytv-issue-queue.md in place: pop the merge pass, write the next
+prompt (#109 Dashboard follow-up — see queue item 2 and its /api/health polling note), record
+PR numbers + the new main SHA + where web/ lives now. Commit+push the doc update (to main if
+the stack landed, else to docs/59-ui-redesign-brief). Print the new prompt in a fenced code
+block.
+
+---
+
+## Issue queue (work top-down)
+Single-session (Codex usage exhausted). No pre-seeded WIP branches remain.
+1. MERGE PASS: PR #112 (#97) + docs/59-ui-redesign-brief stack → main ← PROMPT above
+   (validates SPA issues #78–#83/#96/#98 on main; unblocks all frontend work).
+2. #109 Dashboard follow-up (frontend; needs merge pass). NOTE from #108: GET /api/health
+   re-runs all ~14 checks per request (only the warn/error summary is cached) — the SPA
+   footer/Dashboard must load on demand or poll gently; add a TTL cache first if it needs to poll.
+3. Back to UX conversion: #84 Channels (deps #96/#98/#97 available post-merge-pass) → #86
+   Schedule editor (duration estimates from #111) → #87 Playouts → #88 Libraries → #85 EPG
+   (JSON guide from #102 available — mind the fillerKind + per-request-cost notes above) →
+   #89 Channel Builder (artwork upload from #104; also needs #62: #63/#64/#65) → #93 Settings
+   → #90 rebrand → #91 cutover.
+Cross-refs: #99 (TS/HLS-Direct sessions) stays backlog; "Definition of Ready" for screen issues
+lives in the #59 epic body. Done: #105 (PR #113), #108 (PR #114), #100+#101+#107+#110 (PR #116),
+#103+#106 (PR #115), #104 (PR #117, artwork upload — unblocks #89), #111 (PR #118, schedule item
+duration estimates — unblocks #86), #102 (PR #119, GET /api/guide + shared ChannelGuideProjector —
+unblocks #85). Languages-list endpoint from #105 still unimplemented — open a follow-up when
+#86/#89 need it; filler/watermark lists return DB order — SPA should client-sort.