Refactor ChicoryTV App.tsx into screen-owned modules and a small app shell #243

Closed
opened 2026-07-11 12:49:19 +02:00 by timothy · 5 comments
Owner

Context

web/src/App.tsx is now ~3,500 lines and App.test.tsx ~4,250 lines. The file is no longer just the application root: it owns shell/navigation/theme/TopBar, route metadata and dispatch, Dashboard, Channels, Guide, Libraries, most Playouts behavior, and their helpers.

The cost is behavioral coupling and review blind spots, not merely aesthetics. Recent examples:

  • #212's blank-channel action was implemented inside ChannelsScreen, but an earlier empty-state return hid it on a zero-channel installation.
  • #238 found TopBar primaryAction metadata produced inert buttons; the partial window-event dispatch introduced for Schedules makes screen/shell ownership implicit.
  • allowSubPaths screens require local pathname listeners because App route state is object-reference keyed.
  • App.test.tsx mixes shell/routing/screen behavior and one global API mock, making a local screen change expensive and easy to under-specify.

Schedules and most newer screens already demonstrate the preferred pattern: one screen module with colocated tests and domain helpers.

Objective

Reduce App.tsx to a small composition root that:

  1. Reads/matches the current route.
  2. Renders the application shell.
  3. Renders the matched screen.
  4. Owns only truly global state.

Screen modules own their query hooks, mutations, helpers, state, and tests. Shell actions and navigation become explicit contracts rather than string-keyed global events.

Constraints

  • Behavior-preserving structural work: no redesign, API change, route change, or new dependency in the extraction PRs.
  • Do not introduce React Router as part of this milestone.
  • Do not create a generic screen framework before repeated extracted screens prove a shared abstraction.
  • One bounded extraction per PR; keep diffs mechanically reviewable.
  • Move tests with the screen and keep route/shell tests in a small App-level suite.
  • Update docs/spa-conventions.md when the module/action convention is finalized.
  • Rebase/sequence around active work: #212/#230 touch Channels/navigation; #231–#235 touch playout/async surfaces; #202 will add media-source management.
  • #238 owns the current dead-button bug. This milestone may replace the event mechanism after #238 defines/fixes expected behavior, but must not duplicate or silently close it.

Child work

Create/track four phases under this epic:

  1. Extract Channels.
  2. Extract Playouts.
  3. Extract Dashboard + Guide + Libraries.
  4. Extract shell/routing and replace implicit primary-action coupling.

Acceptance criteria

  • App.tsx contains no domain-specific screen implementation.
  • App.test.tsx covers composition/routing/shell only; screen behavior is colocated.
  • Existing paths, back/forward behavior, dirty-navigation guards, primary actions, and sub-path ownership are preserved and regression-tested.
  • Full web test, lint, typecheck/build, and generated-API checks remain green after each phase.
  • Final architecture and deliberate non-goals recorded in SPA conventions/decisions.
  • No Blazor-removal milestone work is blocked on this refactor unless a concrete behavior defect is separately filed and triaged.

Rollback

No data or API changes. Each extraction must be independently revertible.

## Context `web/src/App.tsx` is now ~3,500 lines and `App.test.tsx` ~4,250 lines. The file is no longer just the application root: it owns shell/navigation/theme/TopBar, route metadata and dispatch, Dashboard, Channels, Guide, Libraries, most Playouts behavior, and their helpers. The cost is behavioral coupling and review blind spots, not merely aesthetics. Recent examples: - #212's blank-channel action was implemented inside `ChannelsScreen`, but an earlier empty-state return hid it on a zero-channel installation. - #238 found TopBar `primaryAction` metadata produced inert buttons; the partial window-event dispatch introduced for Schedules makes screen/shell ownership implicit. - `allowSubPaths` screens require local pathname listeners because App route state is object-reference keyed. - `App.test.tsx` mixes shell/routing/screen behavior and one global API mock, making a local screen change expensive and easy to under-specify. Schedules and most newer screens already demonstrate the preferred pattern: one screen module with colocated tests and domain helpers. ## Objective Reduce `App.tsx` to a small composition root that: 1. Reads/matches the current route. 2. Renders the application shell. 3. Renders the matched screen. 4. Owns only truly global state. Screen modules own their query hooks, mutations, helpers, state, and tests. Shell actions and navigation become explicit contracts rather than string-keyed global events. ## Constraints - Behavior-preserving structural work: no redesign, API change, route change, or new dependency in the extraction PRs. - Do not introduce React Router as part of this milestone. - Do not create a generic screen framework before repeated extracted screens prove a shared abstraction. - One bounded extraction per PR; keep diffs mechanically reviewable. - Move tests with the screen and keep route/shell tests in a small App-level suite. - Update `docs/spa-conventions.md` when the module/action convention is finalized. - Rebase/sequence around active work: #212/#230 touch Channels/navigation; #231–#235 touch playout/async surfaces; #202 will add media-source management. - #238 owns the current dead-button bug. This milestone may replace the event mechanism after #238 defines/fixes expected behavior, but must not duplicate or silently close it. ## Child work Create/track four phases under this epic: 1. Extract Channels. 2. Extract Playouts. 3. Extract Dashboard + Guide + Libraries. 4. Extract shell/routing and replace implicit primary-action coupling. ## Acceptance criteria - `App.tsx` contains no domain-specific screen implementation. - `App.test.tsx` covers composition/routing/shell only; screen behavior is colocated. - Existing paths, back/forward behavior, dirty-navigation guards, primary actions, and sub-path ownership are preserved and regression-tested. - Full web test, lint, typecheck/build, and generated-API checks remain green after each phase. - Final architecture and deliberate non-goals recorded in SPA conventions/decisions. - No Blazor-removal milestone work is blocked on this refactor unless a concrete behavior defect is separately filed and triaged. ## Rollback No data or API changes. Each extraction must be independently revertible.
timothy added this to the ChicoryTV modularization milestone 2026-07-11 12:49:19 +02:00
timothy added the enhancementpriority: mediumfrontend labels 2026-07-11 12:49:19 +02:00
Author
Owner

Tracking map

  • Plan review: adversarial-reviewer#24
  • #244 — Channels extraction; wait for #212, coordinate #230/#238
  • #245 — Playouts extraction; sequence after #231–#235
  • #246 — Dashboard/Guide/Libraries; avoid overlap with #202 and scan-contract work
  • #247 — final shell/routing/action ownership; wait for #230/#238

Suggested order is dependency-driven rather than numeric if active work changes: #244 once #212 is clean; #246's Dashboard/Guide portions may proceed independently but Libraries must avoid #202/#232/#235; #245 after playout lock/status work; #247 last.

## Tracking map - Plan review: [adversarial-reviewer#24](https://gitea.tblindustries.be/timothy/adversarial-reviewer/issues/24) - [#244](https://gitea.tblindustries.be/timothy/ersatztv/issues/244) — Channels extraction; wait for #212, coordinate #230/#238 - [#245](https://gitea.tblindustries.be/timothy/ersatztv/issues/245) — Playouts extraction; sequence after #231–#235 - [#246](https://gitea.tblindustries.be/timothy/ersatztv/issues/246) — Dashboard/Guide/Libraries; avoid overlap with #202 and scan-contract work - [#247](https://gitea.tblindustries.be/timothy/ersatztv/issues/247) — final shell/routing/action ownership; wait for #230/#238 Suggested order is dependency-driven rather than numeric if active work changes: #244 once #212 is clean; #246's Dashboard/Guide portions may proceed independently but Libraries must avoid #202/#232/#235; #245 after playout lock/status work; #247 last.
Author
Owner

Picking up the epic via phase 1 (#244). Children already filed: #244 Channels → #245 Playouts → #246 Dashboard/Guide/Libraries → #247 shell/routing. #244 extraction is held behind PR #242 (#212/#230 land on App.tsx first); running read-only recon now to stage a turnkey Channels extraction. See #244 for detail.

Picking up the epic via phase 1 (#244). Children already filed: #244 Channels → #245 Playouts → #246 Dashboard/Guide/Libraries → #247 shell/routing. #244 extraction is held behind PR #242 (#212/#230 land on `App.tsx` first); running read-only recon now to stage a turnkey Channels extraction. See #244 for detail.
Author
Owner

Phase 1 DONE: #244 merged (PR #249, 533c6c1e). ChannelsScreen extracted to web/src/screens/ChannelsScreen.tsx (+ colocated test); App.tsx down ~545 lines, retains only import + dispatch for Channels. Convention recorded in spa-conventions §6 + decisions.md (single-file screen, no web/src/channels/ sibling dir; extracted-screen own-fetch-mock test pattern). #238 (TopBar dead button) deliberately left to phase 4 (#247).

Remaining: #245 Playouts (phase 2, largest/riskiest surface) → #246 Dashboard/Guide/Libraries (phase 3) → #247 shell/routing + primary-action coupling (phase 4). Each rebases off 533c6c1e.

Phase 1 **DONE**: #244 merged (PR #249, `533c6c1e`). `ChannelsScreen` extracted to `web/src/screens/ChannelsScreen.tsx` (+ colocated test); `App.tsx` down ~545 lines, retains only import + dispatch for Channels. Convention recorded in spa-conventions §6 + decisions.md (single-file screen, no `web/src/channels/` sibling dir; extracted-screen own-fetch-mock test pattern). #238 (TopBar dead button) deliberately left to phase 4 (#247). Remaining: **#245** Playouts (phase 2, largest/riskiest surface) → **#246** Dashboard/Guide/Libraries (phase 3) → **#247** shell/routing + primary-action coupling (phase 4). Each rebases off `533c6c1e`.
Author
Owner

Epic refinements from the plan review (adversarial-reviewer#24, 2026-07-11) — verdict was PLAN SOUND, #244 proved the template; these two adjustments were applied to the child issues:

  1. #246 split into two sequenced batches. Batch A (DashboardScreen + GuideScreen) is eligible now — no #202 overlap. Batch B (LibrariesScreen) is hard-gated behind #202's merge: #202 is already in flight and churns the same App.tsx byte range (~1487-1710) + MediaSource imports, so a concurrent Libraries extraction would conflict. (#246's original "before #202 starts or after it lands, not concurrently" now forces Libraries to wait, since #202 has started.) Source-collision only — the scan temporal logic is insulated in api/libraries.ts.

  2. #238 promoted to a HARD prerequisite of #247 (and added to this milestone). #247's removal of the ctv:primary-action CustomEvent is only safe after #238 establishes a per-screen action contract — the event is the sole delivery path and only SchedulesScreen listens. #238 was drifting in backlog while gating the epic's final phase; it now needs to be scheduled before #247.

Also folded into the child issues' bodies as explicit invariants (from the review): the #247 route-table must stay one stable module-level array of shared ScreenRoute object references (the §2 allowSubPaths Object.is re-render bail depends on it) with a sub-path re-render regression test, and the navigate/popstate/currentPathRef/activeRoute machinery must stay co-located in the composition root (the #230 popstate re-push depends on it). #230 is confirmed settled in-code (PR #242); the heavy polling/current-guards already live in api/*.ts hooks, so #245/#246 move render code only (temporally low-risk). Suggested order unchanged: #245 (after the now-landed lock batch; coordinate vs open #235) → #246 Batch A → #246 Batch B (post-#202) → #238 → #247.

**Epic refinements from the plan review** ([adversarial-reviewer#24](https://gitea.tblindustries.be/timothy/adversarial-reviewer/issues/24), 2026-07-11) — verdict was PLAN SOUND, #244 proved the template; these two adjustments were applied to the child issues: 1. **#246 split into two sequenced batches.** Batch A (`DashboardScreen` + `GuideScreen`) is eligible now — no #202 overlap. Batch B (`LibrariesScreen`) is **hard-gated behind #202's merge**: #202 is already in flight and churns the same App.tsx byte range (~1487-1710) + `MediaSource` imports, so a concurrent Libraries extraction would conflict. (#246's original "before #202 starts or after it lands, not concurrently" now forces Libraries to wait, since #202 has started.) Source-collision only — the scan temporal logic is insulated in `api/libraries.ts`. 2. **#238 promoted to a HARD prerequisite of #247** (and added to this milestone). #247's removal of the `ctv:primary-action` CustomEvent is only safe after #238 establishes a per-screen action contract — the event is the sole delivery path and only SchedulesScreen listens. #238 was drifting in backlog while gating the epic's final phase; it now needs to be scheduled before #247. Also folded into the child issues' bodies as explicit invariants (from the review): the #247 route-table must stay one stable module-level array of shared `ScreenRoute` object references (the §2 `allowSubPaths` Object.is re-render bail depends on it) with a sub-path re-render regression test, and the `navigate`/`popstate`/`currentPathRef`/`activeRoute` machinery must stay co-located in the composition root (the #230 popstate re-push depends on it). #230 is confirmed settled in-code (PR #242); the heavy polling/current-guards already live in `api/*.ts` hooks, so #245/#246 move render code only (temporally low-risk). Suggested order unchanged: #245 (after the now-landed lock batch; coordinate vs open #235) → #246 Batch A → #246 Batch B (post-#202) → #238 → #247.
Author
Owner

Done

What was done: all four bounded phases are complete: Channels (#244), Playouts (#245), Dashboard/Guide/Libraries (#246), and final shell/routing/primary-action ownership (#247 via PR #361). App.tsx is a small composition root, screen behavior/tests are colocated, and the documented route, guard, subpath, and primary-action contracts are explicit and regression-tested.

Root cause: n/a — planned modularization epic.

Files changed: delivered across child issues #244–#247, including extracted screen modules/tests, the final web/src/app/ shell/routing modules, web/src/primaryAction.ts, and SPA architecture docs.

Verification: every child issue is closed. The final integration passed 90 web files / 775 tests, lint, typecheck/build, API sync, full .NET restore/build/test, hosted-SPA live E2E, cold adversarial review, and green CI run 648.

Deferred: none.

Follow-up issues: none.

Docs updated: docs/spa-conventions.md and append-only docs/decisions.md describe the final architecture and deliberate non-goals. The epic remained behavior-preserving and did not block Blazor-removal work.

## Done **What was done**: all four bounded phases are complete: Channels (#244), Playouts (#245), Dashboard/Guide/Libraries (#246), and final shell/routing/primary-action ownership (#247 via PR #361). `App.tsx` is a small composition root, screen behavior/tests are colocated, and the documented route, guard, subpath, and primary-action contracts are explicit and regression-tested. **Root cause**: n/a — planned modularization epic. **Files changed**: delivered across child issues #244–#247, including extracted screen modules/tests, the final `web/src/app/` shell/routing modules, `web/src/primaryAction.ts`, and SPA architecture docs. **Verification**: every child issue is closed. The final integration passed 90 web files / 775 tests, lint, typecheck/build, API sync, full .NET restore/build/test, hosted-SPA live E2E, cold adversarial review, and green CI run 648. **Deferred**: none. **Follow-up issues**: none. **Docs updated**: `docs/spa-conventions.md` and append-only `docs/decisions.md` describe the final architecture and deliberate non-goals. The epic remained behavior-preserving and did not block Blazor-removal work.
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: timothy/ersatztv#243