ersatztv/docs/handoffs/chicorytv-issue-queue.md

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. Backend gaps all landed by 2026-07-04 (#105/#108/#100+#101+#107+#110/#103+#106/#104/#111/#102 → PRs #113–#119). The MERGE PASS (2026-07-04) then landed the whole SPA stack on main via PR #120.

Session state (2026-07-04, post-#109): main = 4ffd777b (PR #123 "Dashboard real data sources"): the Dashboard is the first SPA screen running fully on live API data. On main: design-system/ + web/ foundation (#78–#83), backend #96/#98/#97, Dockerfile hotfix #122, direct-stream session tracker (#99 seam, PR #121), Dashboard data (#109, PR #123). #109 closed. #99 remains open ONLY for the final /api/channels/state wiring (combine IFFmpegSegmenterService.IsActive with IDirectStreamSessionTracker). Baselines: ErsatzTV.Tests 368, Core.Tests 493 (+1 skip); web tests 31 (App.test.tsx 20); web lint/typecheck/build clean (build output ErsatzTV/wwwroot/app/, gitignored; SPA types web/src/api/generated/v1.d.ts, regen npm run generate:api).

• #109 review cycle (pattern that worked): Codex implemented → Fable review caught 1 substantial bug (health widget matched status strings the API never emits — error/failed/unhealthy+warning/degraded vs the REAL pass|fail|warn|info from Health/Mapper.cs; fictional test fixtures masked it) + 4 nits → all fixed in-session by a sonnet subagent (e6197d63) → CI green → merged. LESSON: frontend tests must use fixture values copied from the backend serializer, not invented ones; reviewers should diff fixtures against the producing C# code.
• Dashboard health policy (binding for future screens): /api/health is fetched on mount + guarded manual refresh ONLY (no intervals) — it re-runs ~14 checks per request. A backend TTL cache is the unfiled prerequisite for any live health display.
• Worktrees: remove .worktrees/issue-99-session-tracking and .worktrees/issue-109-dashboard (both merged). The main checkout still sits on docs/59-ui-redesign-brief — fully merged, safe to switch to main.

Lessons for all remaining prompts (accumulated):

• Frontend fixtures/contracts: copy enum-ish string values from the producing backend code (serializers/mappers), never invent them; review = diff fixtures vs C#. (#109's bug.)
• The image-build job runs ONLY on main pushes — PR CI cannot catch Dockerfile breakage. Any Dockerfile change: verify base tags exist (hub.docker.com API) and, where docker is available, docker build --target <stage> locally before merging. (node:22-noble cost a red main run; node official images have no -noble variant.)
• DTO records in ErsatzTV.Core/Api MUST get file-scoped #nullable enable — else the spec emits ["null","string"] unions and SPA types get needless | null. NOTE: ErsatzTV.Application has NO nullable context — string? there trips CS8632.
• NSubstitute + ConfigElementKey: ConfigElementKey.X is a fresh instance per access — stub with Arg.Any<ConfigElementKey>() disambiguated by the generic <T>.
• Option<T>.ToNullable() doesn't exist here; use MatchUnsafe(v => (T?)v, () => null).
• ./scripts/update-openapi.sh only runs -t:GenerateOpenApiDocuments — do a normal dotnet build ErsatzTV/ErsatzTV.csproj FIRST or it fails with MSB3680.
• Id-taking child-collection GETs 404 on unknown parent via pre-check + ApiResults (precedent: ScheduleController.GetItems) + an OpenApiErrorResponseContractTests entry.
• Backlog nits (unfiled): unclamped pageSize on paged endpoints; PlayoutController Create/Delete lack route Name=; PlayoutController.GetItems existence pre-check is heavy;

  30 MB uploads return bare Kestrel 413; artwork content-type trusted from client (#66); schedule duration estimator: expression/zero Count → null estimate, materializes each referenced collection per GET; /api/health TTL cache (prereq for live health UI). From #102 (also on #85): GET /api/guide runs the full 21-include eager-load per channel per request — trim projection or add caching before the EPG grid polls it; fillerKind is almost always None (projector merges filler into adjacent programmes) — discrete filler entries need a JSON-only projection mode.

---

PROMPT FOR CODEX — #84: Channels screen (management table + live treatment)

You are Codex working solo in /Users/timothy/ersatztv (ErsatzTV fork; the React SPA "ChicoryTV" lives in web/ — Vite + TS, typed client in web/src/api/, generated types web/src/api/generated/v1.d.ts). Read CLAUDE.md and docs/contributing.md first; follow the SPA foundation's existing patterns (#78–#83) and the Dashboard's data-layer idioms from PR #123 (web/src/api/dashboard.ts hooks with the active unmount guard) — match, don't invent.

HARD CONSTRAINTS:

• Work in a NEW git worktree: git worktree add .worktrees/issue-84-channels -b feat/84-channels-screen origin/main (branch from origin/main; never touch the main checkout or other .worktrees/*).
• Max 2–3 concurrent builds machine-wide; keep to ONE dotnet build at a time here.
• NEVER set ETV_UPDATE_GOLDENS. A golden-file diff means your code is wrong.
• Do NOT merge anything. Open the PR, get CI green, and stop.
• Backend scope guard: FRONTEND issue. All needed endpoints exist (#96/#98/#97 below). If something is missing, note it in the PR and stub cleanly — do not add endpoints.
• CONTRACT RULE (#109 lesson): any string value you branch on or use in test fixtures must be copied from the producing backend code (mapper/serializer) or the generated v1.d.ts — never invented.

Context

• main = 4ffd777b (post-#123). Baselines: ErsatzTV.Tests 368, Core.Tests 493(+1 skip); web tests 31, lint/typecheck/build clean. Gitea: http://192.168.1.95:3000/timothy/ersatztv (basic auth timothy:ded89Lm4).
• Issue #84: the Channels screen — read its body AND the #59 epic's "Definition of Ready" for screen issues. Visual reference: design-system/templates/chicorytv-admin/Channels.jsx (static prototype) + the design brief; reuse web/src/components/* primitives.
• Available data (all on main):
  • GET /api/channels — enriched list (#96): group, enabled, EPG visibility, sort number…
  • Bulk ops (#98): POST /api/channels/bulk/renumber | /bulk/group | /bulk/delete (204 on success, 404/422 with ProblemDetails — see OpenApiErrorResponseContractTests).
  • GET /api/channels/state (#97): onAir + nowPlaying (nullable!) for live badges/rows. onAir is still segmenter-session-based until the final #99 wiring — render as-is.
  • Channel CRUD: POST/PUT/DELETE /api/channels{,/id} for create/edit/delete flows if the issue's scope includes them (check the issue body; the full Channel Builder is #89 — do NOT build it here).
• Polling: channel state may poll gently (≥30s) if the design calls for live updates; /api/health is NOT this screen's concern.

Process

1. Comment on issue #84 with findings + approach (table/widget → endpoint mapping, which CRUD flows are in/out of scope) before coding.
2. Implement with loading/error/empty states per design-system; bulk selection UX per the prototype; prefer refetch-after-mutate over optimistic updates unless the foundation already has an optimistic idiom (it does not, as of #123).
3. Verify: cd web && npm ci && npm run lint && npm run typecheck && npm test -- --run && npm run build; plus dotnet build ErsatzTV.sln + TZ=UTC dotnet test ErsatzTV.Tests + Core.Tests sequentially (expect 368 / 493+1skip — no backend regression).
4. Push, open PR → main: feat(web): Channels screen (#84), body lists the mapping and scope decisions; closes #84. Poll CI by head SHA until green. Do not merge.
5. Comment progress on #84 as you go.

On completion — REQUIRED final output

Print a fenced handoff prompt addressed to Claude (Fable) asking it to:

• Review the PR diff READ-ONLY in one Fable pass (endpoint/contract correctness incl. fixture values vs backend serializers, bulk-op error handling, polling discipline, type safety, design-system adherence, scope).
• Classify findings: NITS Fable may fix directly on the branch; SUBSTANTIAL issues either go back to Codex as a verbatim prompt or get fixed in-session by subagents — the user decides which at review time.
• After review: comment the verdict on the PR and #84; on approval + user merge consent, merge, verify main's post-merge run (image job included), then update THIS handoff file (pop #84, next prompt = #86 Schedule editor for Codex, record PR number + main SHA + baselines) and push it to main. Include: PR number, branch, head SHA, files changed, mapping table, test/web results, anything deferred or uncertain.

---

Issue queue (work top-down)

0. HOUSEKEEPING (carry into next session): remove .worktrees/issue-99-session-tracking and .worktrees/issue-109-dashboard if still present; #99 stays open for the final /api/channels/state onAir wiring (good small backend slot-filler between screens).
1. #84 Channels screen ← CODEX PROMPT above (review/merge/doc-update falls to the Fable session that Codex's end-of-run handoff spawns).
2. UX conversion order: #86 Schedule editor (#111 durations) → #87 Playouts → #88 Libraries → #85 EPG (#102 JSON guide; mind fillerKind + per-request-cost notes above) → #89 Channel Builder (#104 artwork upload; also needs #62: #63/#64/#65) → #93 Settings → #90 rebrand → #91 cutover. Cross-refs: #99 seam landed (PR #121), final wiring open. Done this pass: MERGE PASS → PR #120 (closed #97; validated #78–#83/#96/#98), hotfix PR #122, PR #121 (#99 seam), PR #123 (#109 Dashboard — first live-data screen). 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.