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 (PRs #113–#119); merge pass PR #120; live-data screens so far: #109 Dashboard
(PR #123), #84 Channels (PR #124), #86 Schedule editor (PR #125), #87 Playouts (PR #127),
#88 Libraries (PR #128).

**PROCESS (2026-07-05, binding)**: Fable writes each Codex prompt AND performs the PR review
(via review subagents — parallel lenses: correctness fork + cheaper contract/tests +
design-system agents; plus a fork verification pass over any fix diff). Codex implements.
Every Codex prompt MUST mandate: (a) subagents where appropriate at fitting effort/model
levels, (b) `npm ci` in each fresh worktree. Review-driven fixes are applied by fitting
subagents too (NITS: Fable fixes on the branch; SUBSTANTIAL: back to Codex verbatim or fixed
in-session — user decides). Merges need explicit user consent (standing consent for this
stretch: merge when reviewers are happy and tests pass).

**Session state (2026-07-05, post-#88)**: main = d63719ec (PR #128 merge): Libraries screen
live — source cards (media-sources), per-library scan progress + triggers, per-source scan,
conditional 10s scan-status polling (pending∪active drives the interval; 3-tick grace window
covers the queue-to-start lag; drains on persistent errors; refetches sources once on
completion). Review found 2 production-visible substantials fixed pre-merge (bee686c8):
percent was a 0–1 wire fraction (bar showed ~0%), and the poll-start race. Fork verification
caught a StrictMode-unsafe ref mutation inside a setState updater — fixed via a pure hoist.
Baselines: ErsatzTV.Tests **368**, Core.Tests **493** (+1 skip); web tests **75**,
lint/typecheck/build clean. #84/#86/#87/#88 CLOSED. Main checkout sits on
docs/59-ui-redesign-brief (fully merged, safe to switch).

**Lessons for all remaining prompts** (accumulated):
- Fixture fidelity (#109/#127/#128): fixtures must be what the actually-called endpoint
  returns UNDER THE QUERY THE CLIENT SENDS. #128: `percent` is a 0–1 fraction despite its
  name (bar showed ~0%; 0–100 fixtures masked it). Enum-with-None fields are never
  truthiness-checked. Verify UNITS/scale of numeric wire fields against the producing code,
  not the field name.
- Trigger≠started (#128): a 202/200 on a trigger endpoint means QUEUED; status endpoints may
  lag by seconds. Pending-state with a grace window bridges the gap; poll while
  pending∪active nonempty; drain grace on persistent errors so UIs can't stick.
- setState updaters must be PURE — no fetches (#127) and no ref mutations (#128); hoist
  side-effects/bookkeeping out. StrictMode double-invokes updaters and the test renderer
  doesn't, so tests won't catch it — reviewers must.
- OpenAPI can UNDER-report the wire (#125/#126); check the serializer before widening types.
- Every new multi-column grid → the @media (max-width: 980px) collapse block; var() fallback
  = the token's resolved value; verify the token EXISTS (--ctv-surface-1, --text-faint don't).
- Prototype affordances: implemented or VISIBLY deferred — never silently dropped
  (#127 toggle = half a blocker; #128 per-source Scan).
- Actionable = visible (#84); disable all mutation triggers while mutating; ref-based
  double-submit guards; mutations never refetch the world (#125/#127).
- A screen listing N entities lets the user pick among them (#125).
- Honest tests: no scenarios the backend can't produce (no exception middleware → failures
  are BARE 4xx/5xx, not ProblemDetails, unless the controller explicitly returns them);
  mount call-counts assert the DELTA across navigation (Dashboard prefetches
  /api/playouts AND /api/media-sources); paging labels don't lie; test the search/filter UI
  you ship; status-dot state never color-only (StatusDot has a label prop).
- The image-build job runs ONLY on main pushes. DTO records in Core/Api need `#nullable
  enable`; Application has NO nullable context. NSubstitute+ConfigElementKey:
  `Arg.Any<ConfigElementKey>()` + `<T>`. `Option<T>.ToNullable()` → `MatchUnsafe`.
  update-openapi.sh needs a prior normal build. Child GETs 404 unknown parents via pre-check.
- Backlog nits (unfiled): unclamped pageSize; PlayoutController Create/Delete lack Name=;
  heavy GetItems pre-check; >30 MB uploads → bare 413; artwork content-type trusted (#66);
  schedule estimator materializes collections per GET; /api/health TTL cache; NEW (#128):
  `LibraryScanStatusResponseModel.percent` is a 0–1 fraction under a percent name — rename
  or ×100 server-side eventually; no Dialog/Modal component yet (likely needed by #89);
  1 pre-existing --text-faint usage in shell.css. Filed: #126 (OpenAPI polymorphism gap).

---

# PROMPT FOR CODEX — #85: Guide / EPG screen (channels × time grid)

You are Codex, the IMPLEMENTER, in /Users/timothy/ersatztv (ErsatzTV fork; React SPA
"ChicoryTV" in web/ — Vite + TS, typed client web/src/api/, generated types
web/src/api/generated/v1.d.ts). Fable (Claude) reviews your PR read-only afterwards — do NOT
merge. Read CLAUDE.md and docs/contributing.md first; follow the SPA patterns from Channels
(PR #124), Schedule editor (PR #125), Playouts (PR #127), Libraries (PR #128) — match, don't
invent.

HARD CONSTRAINTS:
- USE SUBAGENTS where appropriate, at fitting effort and model levels: cheap/fast agents for
  mechanical work (fixtures, CSS transcription, test boilerplate); higher-effort agents only
  for judgment work (grid virtualization/layout math, time-window state). Keep orchestration
  and final assembly in your main session.
- Worktree: `git worktree add .worktrees/issue-85-epg -b feat/85-epg origin/main`.
  Never touch the main checkout or other .worktrees/*.
- Run `npm ci` in web/ in the worktree BEFORE any lint/typecheck/test/build.
- Max 2–3 concurrent builds machine-wide; ONE dotnet build at a time here.
- NEVER set ETV_UPDATE_GOLDENS. A golden-file diff means your code is wrong.
- FRONTEND-only: no new endpoints, no ErsatzTV.Core/Application changes. Missing data =
  VISIBLE deferral (disabled + note) — never silently drop a prototype affordance.
- CONTRACT RULE: fixture values must be what the actually-called endpoint returns UNDER THE
  QUERY THE CLIENT SENDS; verify units/scale of numeric fields against the producing backend
  code, never the field name (#128's percent lesson). Enum-with-None fields are never
  truthiness-checked (#127's fillerKind lesson — this endpoint HAS fillerKind!).

## Task
Issue #85: recreate design-system/templates/chicorytv-admin/Epg.jsx wired to the JSON guide.
Dark channels×time grid, "now" marker, live focal color, jump-to-now. Acceptance: matches
prototype; live guide data; all 3 themes.

## Context (main = d63719ec; baselines: ErsatzTV.Tests 368, Core.Tests 493+1skip, web 75)
- Gitea: http://192.168.1.95:3000/timothy/ersatztv (basic auth timothy:ded89Lm4).
- API surface (verify in v1.d.ts; regen `npm run generate:api` if stale):
  - GET /api/guide?start=<ISO>&end=<ISO> (both optional DateTimeOffset; start defaults to
    now, end to start + configured XmltvDaysToBuild) → ChannelGuideResponseModel { start,
    end, channels: [{ number, name, programmes: [{ start, stop, title, subTitle (nullable),
    category (nullable), fillerKind }] }] }.
  - CRITICAL COST NOTE (#102): the guide endpoint runs a heavy 21-include eager-load PER
    CHANNEL PER REQUEST. Request a BOUNDED window (e.g. now-1h → now+12h), fetch ONCE on
    mount + on explicit user navigation (prev/next window, jump-to-now beyond the loaded
    range) — NEVER poll /api/guide. The "now" marker advances client-side on a timer
    (minute-ish tick moving the marker/highlight; NO refetch).
  - fillerKind in the JSON guide is almost always 'None' — the shared projector merges
    filler into adjacent programmes. Do NOT truthiness-check it; discrete filler rows would
    need a backend projection mode (out of scope — no UI toggle for it).
  - GET /api/channels/state (onAir) may drive the live focal treatment; if used, poll ≥30s
    (Channels precedent) — it's the only thing allowed on an interval besides the client-side
    now-marker tick.
  - Channel logos: check what the prototype uses; the SPA has ChannelLogo (initials-based).
    /iptv logo URLs exist but check what Channels/Dashboard screens do — match precedent.
- Grid math: programmes can start before / end after the requested window — clip to the
  window; overlapping/adjacent programmes must not produce negative/NaN widths; empty
  channels (no programmes) render an empty row, not a crash; timezone = render in the
  BROWSER's local time (the wire carries offsets; Date parsing is TZ-safe).
- No mutations on this screen. Read-only + navigation state only.
- CSS: design-system tokens only; verify each token EXISTS; fallback = resolved value; new
  multi-column grids → the 980px collapse block; the grid scrolls in its OWN container
  (both axes as needed) — never page-level horizontal scroll.
- Tests: mount fetch delta (guide fetched exactly once; no guide polling — assert interval
  ticks don't refetch /api/guide); window navigation triggers exactly one fetch per step;
  jump-to-now; now-marker position math (fixed fake now vs fixture times); programme
  clipping at window edges; empty channels; error+retry; fixture fillerKind 'None' (real
  wire value) with subTitle/category nulls exercised.

## Process
1. Comment on issue #85 with findings + approach (prototype surface → endpoint/DTO mapping
   table, scope decisions, chosen window size) BEFORE coding.
2. Implement; comment progress on #85 as you go.
3. Verify: cd web && npm ci && npm run lint && npm run typecheck && npm test -- --run &&
   npm run build; then TZ=UTC 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): Guide / EPG screen (#85)", body lists the mapping table
   and scope decisions; `closes #85`. Poll CI by head SHA until green. Do NOT merge.

## On completion — REQUIRED final output
Print a fenced handoff prompt addressed to Claude (Fable) asking it to review the PR
READ-ONLY (Fable runs its own review subagents). Include: PR number, branch, head SHA, base,
files changed, the mapping table, verification commands + results, deferred/uncertain list,
and the finding classification (NITS = Fable fixes on the branch; SUBSTANTIAL = back to
Codex verbatim or fixed in-session with subagents — user decides). After approval + user
merge consent, Fable merges, verifies main's post-merge run (image job included), updates
THIS handoff (pop #85, next prompt = #89 Channel Builder, record PR + main SHA + baselines),
and pushes it to main.

---

## Issue queue (work top-down)
0. HOUSEKEEPING: #99 stays open for the final /api/channels/state onAir wiring; #126
   (OpenAPI polymorphism gap) is a good backend slot-filler between screens.
1. #85 Guide/EPG screen ← CODEX PROMPT above (Fable reviews via subagents, merges on
   consent, updates this file).
2. UX conversion order: #89 Channel Builder (#104 artwork upload; also needs #62:
   #63/#64/#65; likely needs the first Dialog/Modal component; languages endpoint follow-up
   from #105 when needed) → #93 Settings → #90 rebrand → #91 cutover.
Cross-refs: #99 seam landed (PR #121), final wiring open. Done recently: PR #125 (#86),
PR #127 (#87), PR #128 (#88 Libraries — closed 2026-07-05, main d63719ec). Filed: #126.