File Browser Intent Prefetch 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: Prefetch a web document's Remix route when its site file-browser row is hovered or keyboard-focused so activation can reuse the route data.

Architecture: The shared file-browser component emits framework-neutral prefetch intent. The web resource-page integration converts that intent into a document href and renders Remix prefetch links, deduplicating destinations for the mounted page while leaving activation unchanged.

Tech Stack: React, TypeScript, Remix 2, Vitest, React DOM test utilities

---

Task 1: Emit prefetch intent from file-browser rows

Files:

Modify: frontend/packages/ui/src/site-file-browser.tsx

Test: frontend/packages/ui/src/__tests__/site-file-browser.test.tsx

[ ] Step 1: Write failing interaction tests

Add an onPrefetch spy to the existing browser test setup. Assert that pointerEnter and focus on a document button call it with that document's ID, while activation still calls onNavigate.

[ ] Step 2: Run the focused test and verify RED

Run: direnv exec . pnpm --dir frontend --filter @shm/ui test -- site-file-browser.test.tsx

Expected: failure because SiteFileBrowserProps does not accept onPrefetch and the interaction does not emit prefetch intent.

[ ] Step 3: Add the minimal callback behavior

Add optional onPrefetch?: (id: UnpackedHypermediaId) => void to SiteFileBrowserProps. Call it from the document button's onPointerEnter and onFocus handlers. Do not add timers or navigation coupling.

[ ] Step 4: Run the focused test and verify GREEN

Run: direnv exec . pnpm --dir frontend --filter @shm/ui test -- site-file-browser.test.tsx

Expected: all file-browser tests pass.

Task 2: Connect intent to Remix route prefetching

Files:

Modify: frontend/packages/ui/src/site-file-browser-layout.tsx

Modify: frontend/packages/ui/src/resource-page-common.tsx

Modify: frontend/apps/web/app/web-resource-page.tsx

Test: frontend/apps/web/app/web-resource-page.test.ts

[ ] Step 1: Write a failing web integration test

Render the web resource-page integration with a prefetch callback seam. Assert that repeated intent for one document produces only one destination href and that another document adds another href. Assert the generated href matches normal document navigation.

[ ] Step 2: Run the focused test and verify RED

Run: direnv exec . pnpm --dir frontend --filter @shm/web test -- web-resource-page.test.ts

Expected: failure because the resource-page/file-browser integration does not expose or handle prefetch intent.

[ ] Step 3: Thread the optional callback through shared UI

Add onPrefetch to SiteFileBrowserLayoutProps, pass it into SiteFileBrowser, and add the matching optional resource-page wrapper callback. Keep the shared UI independent of Remix imports.

[ ] Step 4: Implement the minimal Remix adapter

In the web resource-page layer, retain a set of requested document hrefs. Convert each intent ID with the same route-to-href logic used by navigation, add only unseen hrefs, and render PrefetchPageLinks for those hrefs. Prefetch errors remain handled by Remix; clicking never waits.

[ ] Step 5: Run the focused web test and verify GREEN

Run: direnv exec . pnpm --dir frontend --filter @shm/web test -- web-resource-page.test.ts

Expected: all focused web resource-page tests pass.

Task 3: Verify frontend quality gates

Files:

Verify all files modified above.

[ ] Step 1: Format the frontend workspace

Run: direnv exec . pnpm --dir frontend -r format:write

[ ] Step 2: Run focused tests and type checking

Run the two focused test commands above, then direnv exec . pnpm --dir frontend typecheck.

Expected: tests and type checking pass without errors.

[ ] Step 3: Confirm formatting

Run: direnv exec . pnpm --dir frontend -r format:check

Expected: tracked frontend source files pass formatting checks; any ignored generated artifacts are confirmed with git check-ignore.

[ ] Step 4: Inspect the final diff

Run: git diff --check and git diff -- frontend/packages/ui/src/site-file-browser.tsx frontend/packages/ui/src/site-file-browser-layout.tsx frontend/packages/ui/src/resource-page-common.tsx frontend/apps/web/app/web-resource-page.tsx.

Expected: no whitespace errors and only intent-prefetch changes.