# Newsletter UI 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:** Replace the rough web views with a functional two-pane newsletter browser that defaults to the latest issue and can switch to all issues.

**Architecture:** Keep the current Express/server-rendered UI. Add focused SQLite read methods to `CatalogDatabase`, render reusable layout/navigation/table helpers in `src/web/views.ts`, and wire new routes in `src/web/app.ts` for dashboard, newsletter browser, all links, sponsors, dead links, and runs. Use query parameters for selected newsletter, issue scope, link search, and category filters.

**Tech Stack:** TypeScript, Express, Node `node:sqlite`, server-rendered HTML/CSS, Vitest.

---

### Task 1: Database Read Models

**Files:**

- Modify: `src/database/store.ts`
- Test: `tests/web.test.ts`

- [ ] Write failing tests that a fixture database can return newsletter summaries with issue/link/sponsor counts.
- [ ] Write failing tests that selected newsletter links default to the latest issue and can include all issues.
- [ ] Add `newsletterSummaries()`, `newsletterById()`, `newsletterLinks()`, `categoriesForNewsletter()`, and `allLinks()` read methods.
- [ ] Run `npm test -- tests/web.test.ts`.

### Task 2: Two-Pane Newsletter Page

**Files:**

- Modify: `src/web/views.ts`
- Modify: `src/web/app.ts`
- Test: `tests/web.test.ts`

- [ ] Write failing tests that `/newsletters` renders a two-pane layout, newsletter search input, selected state, latest/all issue controls, category filter, and external link attributes.
- [ ] Implement reusable page layout with dark default styling, light mode toggle, global nav, responsive two-pane layout, and empty states.
- [ ] Implement `/newsletters` with query params: `newsletter`, `scope`, `q`, `category`.
- [ ] Run `npm test -- tests/web.test.ts`.

### Task 3: Global Views and Smoke

**Files:**

- Modify: `src/web/app.ts`
- Modify: `src/web/views.ts`
- Modify: `scripts/smoke.mjs`
- Test: `tests/web.test.ts`

- [ ] Write failing tests that dashboard, all links, sponsored links, dead links, and runs use the new layout.
- [ ] Update `/`, `/links`, `/sponsors`, `/dead-links`, and `/runs` to use the shared layout and table helpers.
- [ ] Keep `nlc serve --help` in smoke validation.
- [ ] Run `npm test -- tests/web.test.ts`.

### Task 4: Docs and Verification

**Files:**

- Add: `notes/UI Spec.md`
- Modify: `README.md`

- [ ] Track the approved UI spec.
- [ ] Document `nlc serve` and the newsletter browser behavior.
- [ ] Run `npm run lint`.
- [ ] Run `npm run format:check`.
- [ ] Run `npm run typecheck`.
- [ ] Run `npm test`.
- [ ] Run `npm run build`.
- [ ] Run `npm run smoke`.

## Self-Review

The plan covers the approved UI spec: two-pane layout, newsletter navigation, latest issue default, all-issues option, global navigation, search/filter controls, dark default, light option, mobile-friendly responsive behavior, and safe external links. It avoids a frontend build stack and keeps the first implementation functional.