Ui Ux Overhaul Branch2 Codex Subagents

Surfc UI/UX Overhaul — Branch 2 (Codex Subagent Plan)

For Codex orchestration: run this plan with superpowers:codex-subagents (preferred) or fall back to superpowers:executing-plans. Keep every checkbox in sync with PR progress.

Mission Context

• Goal: stack three CSS-only animations on top of Branch 1 — capture card slide-down, ink-bleed text reveal, staggered chip fade-in.
• Architecture tweak: useNoteForm.handleImageSelected must call nav.onCaptureReady(image) so App.jsx gates navigation until animationend fires. Ink bleed and chip logic remain inside NoteForm.jsx.
• Tech stack: React 18, Vite, Vitest + @testing-library/react, CSS @keyframes, existing tokens.css variables.
• Spec references: docs/ui-ux/user-journey-v2.md §5 and FUNCTIONAL.md Rule 8 (no JS animation loops, no blocked controls).
• Branch lineage: design/capture-animations cut from merged design/ui-structure-overhaul.

Codex Subagent Topology

Agent	Focus	Key Outputs
A. CSS + Tests	Create src/test/animations.test.jsx, append keyframes + utility classes in src/styles.css.	Green tests proving class wiring; lint-clean CSS block appended after @keyframes grain.
B. Capture Nav	Update src/hooks/useNoteForm.js, src/components/CaptureScreen.jsx, src/App.jsx so App manages capture animation + navigation.	captureAnimImg state, onCaptureReady, onCardSlideEnd, prop plumbing, animation preview.
C. NoteForm FX	Refactor src/components/NoteForm.jsx for ink bleed overlay + chip stagger inline delays.	Word-group logic, temporary overlay, chip delays, zero regression in save gating.
D. QA & Release	Enforce Rule 8, run targeted + full tests, npm run build, branch push + PR.	Passing suites, compliance notes, PR body referencing manual QA list.

Agents must commit only the files in their lane, then hand off. Agent D owns integration once Agents A–C signal done via checklist.

Repo & Branch Guardrails

• Checkout & branch (git pull failed: missing credentials, branch assumed current)

  git checkout design/ui-structure-overhaul
  git pull
  git checkout -b design/capture-animations

• Baseline tests (npm run test:run) before edits — required screenshot/log for the PR attachment.

File Map (source of truth for codex agents)

File	Change Owner
src/styles.css	Agent A appends card-slide, ink-bleed, chip-fade sections + comments.
src/test/animations.test.jsx	Agent A creates test suite validating DOM class hooks, inline delays, animation events.
src/hooks/useNoteForm.js	Agent B swaps goToNote calls for onCaptureReady fallback.
src/components/CaptureScreen.jsx	Agent B renders .capture-card-preview and onAnimationEnd plumbing.
src/App.jsx	Agent B adds captureAnimImg state + handlers, passes props to CaptureScreen, injects onCaptureReady into the hook.
src/components/NoteForm.jsx	Agent C adds ink-bleed overlay, textarea visibility toggle, chip delay styles.
src/test/capture.test.jsx	Agent B extends existing tests only if regressions appear (no change expected).

Phase Plan

Phase 0 — Pre-flight sync (Owner: Lead agent)

• Confirm workspace clean: git status.
• Document baseline npm run test:run output.
• Share branch + context with subagents A–D.

Phase 1 — CSS + animation tests (Agent A)

1. Author failing tests first: create src/test/animations.test.jsx per spec (CaptureScreen preview, ink bleed transitions, chip delays). Use a header comment to note jsdom limitations.
2. Run targeted suite to prove failure:

   npm run test:run -- --reporter=verbose src/test/animations.test.jsx

3. Append CSS blocks to src/styles.css after @keyframes grain. Include comments separating each animation. Use animation-delay only via inline styles.
4. Re-run targeted suite; expect CaptureScreen tests still failing until wiring lands.
5. Stage + commit:

   git add src/styles.css src/test/animations.test.jsx
   git commit -m "chore: add capture animation tests and keyframes"

6. Signal done in checklist + unblock Agents B/C.

Phase 2 — Capture navigation wiring (Agent B)

1. src/hooks/useNoteForm.js: destructure { goToNote, onSaveSuccess, onCaptureReady }. In handleImageSelected, replace each goToNote call with onCaptureReady ? onCaptureReady(compressedImage) : goToNote?.() while leaving error handling untouched.
2. src/components/CaptureScreen.jsx: accept captureAnimImg, onCardSlideEnd; render .capture-card-preview overlay (absolute, pointer-events none) only when image exists, call onCardSlideEnd on animationend.
3. src/App.jsx: add const [captureAnimImg, setCaptureAnimImg] = useState(null); plus handleCaptureReady (sets image) and handleCardSlideEnd (clears image, calls ui.goToNote()). Pass onCaptureReady in the hook nav config and feed the new props to CaptureScreen.
4. Update or extend src/test/capture.test.jsx only if new behavior requires coverage (the new animation tests should already cover most cases).
5. Run the animation test file; expect CaptureScreen block to pass while NoteForm block still fails.
6. Commit changes.

Phase 3 — NoteForm ink bleed + chip stagger (Agent C)

1. In src/components/NoteForm.jsx, import useEffect, useRef, useState if needed. Add helper toWordGroups(text, size = 4).
2. Track previous transcribeLoading via ref. When it transitions true→false and noteText.trim() exists, compute word groups, set isInkBleeding = true, store groups, and start a timeout to revert after (groups.length - 1)*50 + 300 + 100 ms. Clean up the timer on unmount.
3. Wrap the textarea inside .note-text-field. Apply text-hidden class while the ink bleed overlay is active. Render .ink-bleed-display with .ink-bleed-group spans using inline animationDelay: ${i * 50}ms.
4. Apply the same inline delay pattern to .idea-chip buttons (pendingTags.map). Ensure canSave logic continues to ignore isInkBleeding.
5. Run the animation test file — all blocks should now pass.
6. Commit NoteForm changes.

Phase 4 — Quality gates (Agent D)

1. Execute

   npm run test:run -- --reporter=verbose src/test/animations.test.jsx
   npm run test:run

2. Enforce Rule 8 checks:
   • rg "requestAnimationFrame|setInterval" src → expect no matches.
   • Confirm Save button gating via NoteForm source (no isInkBleeding in canSave).
   • Verify .capture-card-preview is separate from any camera element; no transforms applied to <video> or file input elements.
   • Ink bleed filter only on .ink-bleed-group spans.
3. Production build:

   npm run build

4. If tests/build fail, loop the issue back to the owning agent; document fix commits.
5. Once green, push branch and open PR:

   git push -u origin design/capture-animations
   gh pr create --title "feat: capture animations" --body <summary matching plan>

6. PR body must list manual QA (card slide, ink bleed, chip fade) and cite Rule 8 compliance statements.

Delivery Checklist

• Phase 0 complete (branch + baseline tests).
• Phase 1 CSS/tests merged.
• Phase 2 navigation wiring merged.
• Phase 3 NoteForm overlay merged.
• Phase 4 QA/build complete.
• Rule 8 compliance notes added to PR description.
• docs/ui-ux/user-journey-v2.md §5 referenced in PR summary.
• Screenshots or short videos of animations attached to PR (optional but recommended).

Keep this file updated as tasks finish; unchecked boxes block promotion to Branch 3.