# ChicoryTV SPA App Shell Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Build the ChicoryTV React admin shell for Gitea issue #82: fixed sidebar, compact top bar, client-side screen slots, Connect menu, and mounted theme switcher.

**Architecture:** Keep the shell in `web/src/App.tsx` because the current SPA is still small and the issue is about top-level chrome. Use local React state plus `history.pushState`/`popstate` for lightweight client-side routing without adding dependencies. Keep styling in the existing `web/src/shell.css` stub and reuse the ported design-system primitives.

**Tech Stack:** React 19, TypeScript, Vite, Vitest, Testing Library, Lucide React, ChicoryTV design-system CSS tokens.

---

### Task 1: Shell Behavior Tests

**Files:**
- Modify: `web/src/App.test.tsx`

- [ ] **Step 1: Replace scaffold expectations with shell expectations**

Add tests that render `App`, assert the 232px sidebar/top-bar shell content is present, verify navigation moves between placeholder screens, verify the Connect menu exposes M3U/XMLTV endpoints, and keep the existing theme persistence coverage.

- [ ] **Step 2: Run tests to verify failure**

Run: `cd web && npm test -- --run src/App.test.tsx`

Expected: tests fail because the current scaffold still renders "SPA foundation ready" and does not implement routed placeholder screens or the Connect menu.

### Task 2: App Shell Implementation

**Files:**
- Modify: `web/src/App.tsx`
- Modify: `web/src/shell.css`

- [ ] **Step 1: Implement shell structure**

Replace the scaffold/gallery with:
- Sidebar brand row, primary/media/system nav, health footer.
- Top bar with page title, search input, Connect menu, help/notification/avatar controls, and per-screen primary action slot.
- Theme switcher mounted in the shell.
- Placeholder content for Dashboard, Channels, New Channel, Guide, Schedules, Playouts, Collections, Libraries, and Settings.

- [ ] **Step 2: Implement routing**

Use a route table with paths under `/app`, `window.location.pathname`, `history.pushState`, and `popstate` to update active nav and rendered screen without a full reload.

- [ ] **Step 3: Style to prototype**

Rewrite `shell.css` so the sidebar is 232px, top bar is 52px, active nav uses accent rail plus soft tint, content scrolls independently, and the layout remains usable on narrow screens.

- [ ] **Step 4: Run focused tests**

Run: `cd web && npm test -- --run src/App.test.tsx`

Expected: all `App` tests pass.

### Task 3: Verification

**Files:**
- No code changes expected.

- [ ] **Step 1: Run web test suite**

Run: `cd web && npm test -- --run`

Expected: all tests pass.

- [ ] **Step 2: Run lint**

Run: `cd web && npm run lint`

Expected: no lint errors.

- [ ] **Step 3: Run production build**

Run: `cd web && npm run build`

Expected: TypeScript and Vite build successfully.
