# Web Roadmap

Status: In Progress
Parent: `docs/ROADMAP.md`
Stack: Next.js 16 + React 19 + TypeScript

# Phase W0 — Scaffold

- [x] Create Next.js app structure
- [x] Wire `@bytelyst/api-client`
- [x] Wire `@bytelyst/platform-client`
- [x] Wire `@bytelyst/react-auth`
- [x] Wire `@bytelyst/telemetry-client`
- [x] Wire `@bytelyst/diagnostics-client`
- [x] Import shared tokens
- [x] Create app shell/layout
- [x] Define route structure

# Phase W1 — Core Product Shell

- [x] Authenticated shell
- [x] Sidebar/navigation
- [x] Dashboard page
- [x] Workspace page
- [x] Note detail/editor page
- [x] Search page
- [x] Settings page
- [x] Empty/loading/error states

# Phase W2 — Notes MVP UX

- [x] Full note editor scaffold
- [x] Note metadata panel scaffold
- [x] Linked notes UI scaffold
- [x] Artifact/attachment UI scaffold
- [x] Task extraction/review UI scaffold
- [x] Workspace filters and saved views scaffold
- [x] Keyboard navigation improvements
- [x] Dense knowledge UX polish

# Phase W3 — Agent UX

- [x] Agent activity timeline scaffold
- [x] Approval queue UI scaffold
- [x] Before/after proposal review UI scaffold
- [x] Audit filters and review surfaces scaffold
- [x] Product-specific operator workflows scaffold

# Phase W4 — Search / Retrieval UX

- [x] Advanced search UI scaffold
- [x] Smart views / saved searches scaffold
- [x] Relationship-aware navigation UI scaffold
- [x] Higher-density overview improvements

# Phase W5 — Hardening

- [ ] Performance pass
- [x] Accessibility pass
- [ ] Token validation pass
- [x] Production build passes
- [x] UX polish pass

# High-Collision Areas

- [ ] top-level layout files
- [ ] auth provider setup
- [ ] navigation config
- [ ] token/theme entrypoints

# Progress Notes

- 2026-03-10
  - Created a new `web/` Next.js 16 scaffold from scratch because the repo started docs-only.
  - Added ByteLyst shared package wiring for auth, platform client, telemetry, diagnostics, and shared design tokens.
  - Implemented the first production-shaped route shells:
    - landing page
    - app shell layout
    - sidebar navigation
    - dashboard
    - workspaces
    - note detail/editor
    - search
    - settings
    - not-found
  - Initially used mock notes/workspaces and demo auth fallback so UI work could proceed before backend contracts were finalized.
  - Expanded W2/W3 surfaces with:
    - note metadata panel
    - linked notes panel
    - task review panel
    - artifact panel
    - workspace filter/saved-view shell
    - advanced search filter/explainability shell
    - review route with approval queue, before/after proposal card, and agent timeline
  - Installed `web/` dependencies and verified:
    - `npm run typecheck`
    - `npm run build`
  - Fixed verification issues:
    - aligned `ProductUser` with shared `@bytelyst/react-auth` `BaseUser`
    - guarded demo auth init so server prerender does not touch `localStorage`
  - Expanded the operational shell with:
    - saved view data wired into dashboard, workspaces, and search
    - denser search result rows with status/owner/workspace metadata
    - operator workflow summary cards on dashboard and reviews
    - workspace owner visibility for denser knowledge navigation
  - Hardened shared accessibility/keyboard affordances with:
    - skip-to-content support in the shared shell
    - stronger focus-visible treatment for interactive controls
    - clearer active-nav semantics via `aria-current`
    - keyboard/accessibility guidance surfaced in navigation/settings
  - Added the first web UI test harness and coverage for:
    - shared `AppShell` skip-link/main landmark behavior
    - shared `Sidebar` primary-nav and active-page semantics
  - Verified `web/` with:
    - `npm test`
    - `npm run typecheck`
    - `npm run build`
  - Hardened Next.js build config by setting `outputFileTracingRoot`, removing the repeated workspace-root warning during `web` production builds
  - Reconciled roadmap-vs-code drift by wiring the richer operational surfaces into the actual routes:
    - dashboard now derives saved views and operator workflow cards from live note/workspace/review data
    - workspaces now exposes saved-view inventory plus denser ownership/filter context from backend-backed workspace data
    - search now renders live-derived saved searches, retrieval filters, and denser result rows
    - reviews now surfaces live-derived operator workflow summaries alongside the approval queue
  - Re-verified the richer route slice with:
    - `npm run typecheck`
    - `npm test`
    - `npm run build`
  - Added the first backend relationship hydration in the note-detail client:
    - linked notes now load from the product backend `note-relationships` endpoint
    - the client falls back safely when relationship data is unavailable
  - Re-verified the backend-backed note/workspace slice with:
    - `npm run typecheck`
    - `npm test`
  - Review decisions are now actionable from the web operator surface (`1bb220b`):
    - proposal review cards now expose approve/reject controls
    - review decisions patch backend `note-agent-actions` state and update the local queue/timeline immediately
  - Re-verified the web review slice with:
    - `npm run typecheck`
    - `npm test`
  - Note detail editing is now backend-backed from the web authoring surface (`cdc03e3`):
    - note title/body edits now submit through the product backend note update route
    - the detail view refreshes the persisted note after save and exposes explicit saving state
  - Re-verified the web note-edit slice with:
    - `npm run typecheck`
    - `npm test`
  - Artifact creation is now backend-backed from the web note detail surface (`ef82747`):
    - artifact metadata now submits through the product backend `note-artifacts` route
    - the detail view refreshes live artifacts after a new artifact is created
  - Re-verified the web artifact slice with:
    - `npm run typecheck`
    - `npm test`
  - Task creation is now backend-backed from the web note detail surface (`c99390e`):
    - manual tasks now submit through the product backend `note-tasks` route
    - the detail view refreshes live tasks after a new task is created
  - Re-verified the web task slice with:
    - `npm run typecheck`
    - `npm test`
  - Search now uses the backend note search query path instead of local-only client-side filtering (`4748ed3`).
  - Workspace filtering is now active instead of passive UI (`ab15950`).
  - Dashboard recent-note activity now links directly into the note detail surface (`9f2670c`).
  - Dashboard saved views now route into real destinations, including seeded search queries (`99484a5`).
  - Sidebar no longer exposes a hardcoded single-note navigation target (`4376519`).
  - Review queue items are now selectable so the featured proposal follows the operator's choice (`5ce9401`).
  - Active web surface copy now reflects the backend-backed product state instead of scaffold-era wording (`5458090`).

# Open Questions

- What are the final values for:
  - product name
  - `productId`
  - backend port
  - domain identifiers
- What are the exact product-backend endpoints and response shapes for:
  - auth
  - notes CRUD
  - workspaces CRUD
  - search
- Which operator review/audit surfaces should stay product-local vs shared-dashboard-owned?

# Blockers

- Product identity is still draft-level in the planning docs, so the scaffold currently uses provisional values:
  - `ByteLyst Agentic Notes`
  - `agentic-notes`
  - `4016` as a placeholder notes API port in `.env.example`
- Backend integration contracts are only partially aligned with the web shell, so some routes still rely on demo auth fallback and client-derived operator/saved-view summaries.

# Deferred

- Real saved-view persistence and backend-backed workspace filters
- Artifact upload/download UX
- Extraction-backed task review flows
- Backend-backed agent activity timeline, approval queue, proposal diff review, and audit filtering
- Saved-view persistence, keyboard shortcut expansion, and deeper performance hardening

# Done When

- [ ] Web is the strongest authoring and operator surface
- [ ] Dense knowledge workflows feel production-shaped
- [ ] Agent review and approval flows are usable