# 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.