Sidebar Menu Rebuild Plan

This document outlines how we will restart the chat-folder effort without repeating the regressions introduced during the previous attempt. The roadmap deliberately stages the work so we regain stability first, re-establish clean primitives, then add the new UI capabilities in isolation before cutting over.

Goals

• Restore the production-quality sidebar exactly as it behaved before folder prototyping.
• Refactor the baseline menu so it owns a single data source, well-defined reducers, and test coverage.
• Ship the new folder-capable experience as an opt-in surface that can be dogfooded without risking the main navigation.
• Define objective exit criteria (tests, performance, rollback guardrails) before swapping the legacy menu out.

Step 1 — Revert To The Last Known-Good Menu

Purpose: Eliminate the regressions (extra renders, race conditions, layout drift) by going back to the previously stable implementation.

• Remove NewSidebarPreview from the render tree and disable all layout hydration/persistence hooks in ProjectContextV2.
• Delete/disable the incremental layout CRUD endpoints from the client bundle; keep the SQLite table/data for future reuse but stop reading it during bootstrap.
• Re-enable the canonical project list as the only source for ordering, selection, and state. Feature flag VITE_ENABLE_NEW_SIDEBAR_PREVIEW should default to false everywhere and gate any code path that still references layout data.
• Verification:
  • Run the existing regression suite (npm run test, Cypress smoke if available).
  • Manual QA for project selection, session navigation, rename/delete flows, hotkeys.
  • Profile sidebar render counts to confirm parity with pre-folder baselines.

Deliverable: A minimal diff that removes the folder UI while keeping the repo buildable and tests green.

Step 2 — Refactor & Harden The Legacy Menu (Same UX)

Purpose: Apply the architectural lessons while behavior remains unchanged.

• Single source of truth: move project list derivation into a dedicated reducer slice with typed actions; prohibit components from mutating layout-like state directly or relying on window.* shims.
• Server bootstrap ownership: ensure only the server seeds layout/project metadata. The client should never fall back to hard-coded defaults; add guardrails to fail loud if the API responds unexpectedly.
• State/test hygiene:
  • Add unit tests for the reducer (project ordering, selection, websocket updates).
  • Add integration tests that load the sidebar with mocked project responses to catch regressions automatically.
• Performance cleanup: strip console logging/debug-only helpers from hot paths, memoize expensive selectors, and document expected render counts.

Deliverable: Refactored legacy sidebar + context with tests proving existing functionality, ready to be extended.

Step 3 — Build The Next-Gen Menu In Parallel

Purpose: Implement the folder-capable UI as a second, isolated component that consumes the refactored primitives from Step 2.

• Create a new module (e.g., sidebar/NewSidebarTree.tsx) that only talks to the reducer/api layer via typed commands (layout.load, layout.reorder, etc.).
• Reintroduce layout APIs through a focused hook (useLayoutStore) that owns optimistic updates, websocket fan-out, and persistence debouncing. The hook must serialize writes and surface rollback callbacks so UI code stays declarative.
• Implement the documented UX features: drag/drop folders, inline composers, rename/delete with optimistic state, conversation list rendering, expand/collapse controls.
• Instrument the component with Storybook or visual regression tests to exercise interactions without touching the production sidebar.
• Wire the component behind a dedicated flag (env + server-config), rendering it in an isolated preview panel for internal users. Legacy sidebar remains the primary navigation.

Deliverable: A fully functional second menu that can be toggled on independently, backed by automated tests and protected behind configuration.

Step 4 — Validate, Cut Over, And Retire The Legacy Menu

Purpose: Graduate the new menu to production once it proves parity and reliability.

• Dogfood & QA: run the new menu in staged environments, execute the full feature matrix (create, rename, delete, drag, websocket updates, error handling), and document any behavioral deltas.
• Performance sign-off: compare render counts, bundle size, and latency against the legacy baseline. Add metrics dashboards if needed.
• Flag strategy: support gradual rollout (e.g., per-workspace toggle) with the ability to revert instantly.
• Cleanup: when the new UI meets acceptance criteria, remove the legacy sidebar, dead flags, and unused reducer paths. Keep the layout store + tests as the single path forward.

Deliverable: New sidebar enabled by default, legacy code removed, and rollback plan documented.

---

Following these four steps ensures we regain a clean base, avoid dual sources of truth, and only reintroduce the folder experience once it is isolated, tested, and easy to reason about. Each stage should land as its own PR with clear verification notes so we can stop or roll back without jeopardizing stability.