netfelix-audio-fix/docs/superpowers/plans/2026-04-15-scan-page-rework.md

Scan Page Rework 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: Rework the Scan page to prioritize progress + fresh ingest visibility, and add a scalable filterable/lazy-loaded library table.

Architecture: Keep /api/scan lightweight for status/progress and compact recent ingest rows. Add /api/scan/items for paginated/filterable DB browsing. Update ScanPage to render: scan card header count, compact 5-row recent ingest table, then a filterable lazy-loaded library table.

Tech Stack: Bun + Hono, React 19 + TanStack Router, bun:test, Biome.

---

Task 1: Backend scan payload + items endpoint (TDD)

Files:

• Modify: server/api/__tests__/scan.test.ts

• Modify: server/db/schema.ts

• Modify: server/db/index.ts

• Modify: server/services/rescan.ts

• Modify: server/api/scan.ts

• Add failing tests for scan item query parsing/normalization and SQL filter behavior helpers.

• Run targeted tests to verify failure.

• Add media_items.ingest_source schema + migration, set value on upsert (scan/webhook).

• Extend GET /api/scan recent item shape with timestamp + ingest source and clamp to 5 rows.

• Add GET /api/scan/items with filters (q,status,type,source) + pagination (offset,limit), returning { rows,total,hasMore }.

• Run targeted and full backend tests.

Task 2: Scan page UI rework + lazy table

Files:

• Modify: src/features/scan/ScanPage.tsx

• Refactor scan box header to show scanned count in top-right.

• Replace large recent-items table with a compact 5-row recent ingest list directly under progress bar.

• Add filter controls for library table (q,status,type,source) with default “All”.

• Add lazy loading flow (initial fetch + load more) against /api/scan/items.

• Render new table with useful file metadata columns and consistent truncation/tooltips.

Task 3: Verification

Files:

• Modify: none

• Run bun test.

• Run bun run lint and format if needed.

• Confirm no regressions in scan start/stop/progress behavior.