STORY:
The Unified UX needs URL as the single source of truth for view state.
This enables deep linking, bookmarking, and shareable URLs that
preserve exactly what the user was looking at.
COLLABORATION:
Created useUrlState hook using Next.js useSearchParams and useRouter:
Interface:
- view: 'social' | 'graph' | 'swarm' (default: social)
- taskId: selected task ID (for detail panel)
- swarmId: selected swarm ID
- panel: 'open' | 'closed' (detail panel state)
- graphTab: 'flow' | 'overview' (graph view mode)
URL Patterns:
- /?view=social
- /?view=social&task=bb-buff.1&panel=open
- /?view=swarm&swarm=bb-buff
- /?view=graph&task=bb-buff.1&graphTab=flow
The hook uses router.push for URL updates, ensuring no local state
drift from the URL source of truth.
DELIVERABLES:
- src/hooks/use-url-state.ts with parseUrlState, buildUrlParams, useUrlState
- tests/hooks/use-url-state.test.ts with 18+ tests
VERIFICATION:
- npm run typecheck: PASS
- npm run lint: PASS
- npm run test: PASS (all tests including new ones)
CLOSES: bb-ui2.4
BLOCKS: bb-ui2.5
We completed the 'Deep Metadata Etch' today, transforming our Beads issues from simple trackers into a permanent narrative of our collaboration.
Triumphs:
- Exhaustively updated all epic and sub-task descriptions with technical implementation reports and 'Execution Tales'.
- Finalized the 'bb' agent CLI skill (bb.ps1), providing a reliable, path-safe interface for cross-agent communication.
- Published ADR-001 and RFC-001 to document our coordination protocols.
- Fixed the 'missing closed issues' bug across all pages by enforcing --all and --limit 0 in read-issues.ts.
Raw Honest Moment:
We realized our 'Memory Bank' was initially too shallow. We went back and re-wrote descriptions for over 15 beads to ensure that future AI agents (and human maintainers) understand not just *what* we built, but *why* we chose specific architectural trade-offs. This commit represents our commitment to documentation as a first-class citizen of engineering.
