Newsletter-Link-Catalog/docs/superpowers/plans/2026-05-17-newsletter-ui.md

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.