Skip to content
Surfc Wiki

Surfc UI/UX Overhaul — Branch 1 (Codex Sub-Agent Execution Plan)

Surfc UI/UX Overhaul — Branch 1 (Codex Sub-Agent Execution Plan)

0) Mission + operating mode

Objective: Implement the Capture-First redesign by replacing the Home → Review → Note flow with a Capture → Note flow, adding Sources and Active Ideas screens, and preserving all existing data/sync boundaries.

Execution mode: This plan is written for a coordinator agent + sub-agents.

  • Coordinator owns sequencing, integration, regression checks, and final PR.
  • Sub-agents each own a scoped change-set with explicit file ownership.

Canonical product spec: docs/ui-ux/user-journey-v2.md.

Branch policy:

  • Base: main
  • Feature branch: design/ui-structure-overhaul

1) Global constraints (apply to every sub-agent)

  1. Do not alter architecture boundaries:
    • Dexie-first persistence and outbox sync remain unchanged.
    • Keep existing db.js + cloudWrite pathways for data writes.
  2. No new stores/tables/APIs for this branch.
  3. UI-only extractions for new screens (SourcesScreen, IdeasScreen).
  4. Capture-first launch must become default (mobileView = 'capture').
  5. Remove review state and ReviewScreen entirely.
  6. Auto-discover chaining must run once per successful capture via hasAutoDiscovered.
  7. Note form persistence in DOM: keep NoteForm mounted while navigating between note, sources, and active-ideas.
  8. Icon policy: @phosphor-icons/react with weight="light".
  9. Style tokens: use existing tokens.css variables only.

Phase A (foundation)

  1. Sub-agent A1: FUNCTIONAL.md contract update.
  2. Sub-agent A2: Navigation state machine (useUI.js).
  3. Sub-agent A3: Note form orchestration (useNoteForm.js).

Phase B (screen components)

  1. Sub-agent B1: SourcesScreen.jsx.
  2. Sub-agent B2: IdeasScreen.jsx.
  3. Sub-agent B3: HomeScreen.jsx rewrite.
  4. Sub-agent B4: CaptureScreen.jsx nav removal.
  5. Sub-agent B5: NoteForm.jsx rewrite.
  6. Sub-agent B6: IndexScreen.jsx header/settings update.

Phase C (integration + styling)

  1. Sub-agent C1: App.jsx integration rewrite.
  2. Sub-agent C2: styles.css appended styles.

Phase D (verification + cleanup)

  1. Sub-agent D1: capture.test.jsx rewrite + any required App.behaviour.test.jsx skips.
  2. Sub-agent D2: delete ReviewScreen.jsx, final build/tests.
  3. Coordinator: reconcile, run final suite, prepare PR.

3) Sub-agent task cards

Each card includes scope, hard requirements, and done criteria.

A1 — Functional contract doc

Files: FUNCTIONAL.md
Action: Replace with updated 9-rule contract from the source plan.
Done when: File content exactly reflects capture-first + auto-discover + navigation + animation + error-copy contracts.

A2 — Navigation state machine

Files: src/hooks/useUI.js
Action: Replace file with capture-first navigation model.
Hard requirements:

  • default mobileView = 'capture'
  • add sources and active-ideas routes
  • remove review route semantics
  • preserve existing idea-related computed state and actions
  • goBackFromNote returns to prior note-opening context Done when: All required navigation actions are exported and consumed cleanly by App.jsx.

A3 — Note form orchestration + auto-discover

Files: src/hooks/useNoteForm.js
Action: Replace file with new implementation.
Hard requirements:

  • add hasAutoDiscovered
  • auto-run callDiscoverIdeas(...) once after successful transcription
  • no auto-run when transcription fails or no text
  • expose dismissTranscribeError, addBookDirectly
  • remove local bookTitle/bookAuthor form state from this hook
  • reset hasAutoDiscovered on clearCapture() and saveNoteForm() Done when: capture success chains transcription → discover ideas exactly once per capture event.

B1 — Sources screen

Files: src/components/SourcesScreen.jsx (new)
Action: Create component exactly as specified.
Hard requirements:

  • local title/author inputs only
  • delegates writes/deletes through callbacks
  • settings gear in header Done when: screen renders list, add form, and delete action with no direct DB calls.

B2 — Active Ideas screen

Files: src/components/IdeasScreen.jsx (new)
Action: Create component exactly as specified.
Hard requirements:

  • list active ideas by ideaCounts > 0
  • sort descending by note count
  • selecting an idea routes to index via callbacks Done when: screen is pure UI, no data mutations.

B3 — Home screen rewrite

Files: src/components/HomeScreen.jsx
Action: Replace component with stat-box layout + CTA.
Hard requirements:

  • top-right settings gear
  • stat boxes for Notes / Ideas / Sources
  • single Start Capturing CTA Done when: no legacy nav assumptions remain.

B4 — Capture screen cleanup

Files: src/components/CaptureScreen.jsx
Action: Remove internal nav and keep capture/manual buttons only.
Done when: shared bottom nav in App.jsx is sole mobile nav.

B5 — Note form UI rewrite

Files: src/components/NoteForm.jsx
Action: Replace component with new source select + inline transcription status UX.
Hard requirements:

  • remove in-form source creation UI
  • add source <select> and + Add new source link
  • inline transcription error banner with approved copy
  • show manual Discover fallback only when !hasAutoDiscovered && !aiLoading && noteText.trim()
  • include X cancel + retake affordance Done when: form supports both capture and manual entry paths under new contract.

B6 — Index header gear

Files: src/components/IndexScreen.jsx
Action: add Gear import + onOpenSettings prop + header button.
Done when: settings gear appears without changing core index behavior.

C1 — App integration rewrite

Files: src/App.jsx
Action: Replace file with capture-first orchestration.
Hard requirements:

  • add SourcesScreen/IdeasScreen imports
  • remove ReviewScreen imports/render
  • keep NoteForm always mounted; hide via CSS class when not active
  • hide bottom nav on home
  • 3-button nav: Home / Capture / Index
  • wire all new props/actions end-to-end Done when: app compiles and routes work per journey v2.

C2 — Styles append

Files: src/styles.css
Action: append provided style blocks; do not remove existing styles.
Done when: new screens and note form variants render with token-based styling.

D1 — Tests update

Files:

  • src/test/capture.test.jsx
  • optionally src/test/App.behaviour.test.jsx

Action: Rewrite capture tests for v2 flow.
Hard requirements:

  • no helper for navigating to capture at startup
  • remove ReviewScreen assumptions
  • assert new error copy
  • add auto-discover tests
  • if legacy library-tab tests break, skip with comment: // Library tab removed in v2 — functionality moved to SourcesScreen Done when: capture.test.jsx passes and full suite is green (or known skips are explicit).

D2 — Cleanup + verification

Files: src/components/ReviewScreen.jsx (delete)
Action: remove obsolete screen and verify no import leftovers.
Done when: build + full tests pass.

4) Integration protocol for coordinator

  1. Merge/sequence sub-agent outputs in phase order.
  2. Resolve conflicts in App.jsx, styles.css, and tests first.
  3. Run mandatory checks:
    • npm run test:run -- --reporter=verbose src/test/capture.test.jsx
    • npm run test:run
    • npm run build
  4. If failures occur, assign focused repair task (single file owner) and rerun impacted checks.
  5. Remove stale imports and dead files (especially ReviewScreen).

5) Commit strategy (squash-friendly)

Use atomic commits grouped by concern:

  1. docs(functional): update capture-first contract and UX rules
  2. feat(ui): update navigation state for capture-first flow
  3. feat(noteForm): auto-discover chaining and source helpers
  4. feat(ui): add SourcesScreen and IdeasScreen
  5. feat(ui): rewrite Home/Capture/NoteForm/Index screens
  6. feat(app): integrate capture-first routing and shared nav
  7. style(ui): add v2 home/sources/ideas/note-form styles
  8. test(ui): update capture flow tests for v2
  9. chore(ui): remove ReviewScreen

Coordinator may squash to 1–3 commits before PR if team policy prefers.

6) PR template (for coordinator)

Title: feat: Capture-First UI overhaul — Branch 1 (structure)

Body:

  • Summary bullets for: capture-first default, new screens, removal of review screen, note form changes, nav changes, tests/build status.
  • Link spec: docs/ui-ux/user-journey-v2.md.
  • Test checklist:
    • npm run test:run
    • npm run build
    • manual smoke flow for launch/capture/note/sources/ideas.

7) Out of scope (Branch 2)

Do not implement animation branch here. Branch 2 (design/capture-animations) will handle:

  • card-slide capture animation,
  • ink-bleed transcription reveal,
  • idea-chip enter animations, with separate PR and no data/nav architecture changes.