Sync sidebar organization, ordering, and navigation preferences through the server

[SawyerHood]

Human comments

What was wrong

With the server registry in place (#3303), the app still reads and writes the sidebar organization mode, chronological sort, the three section orders, navigation entry order and visibility, and the navigation and thread-list provider pickers from localStorage only. Separately, usePersistedSidebarSectionOrder wrote the normalized order back on every mount where it differed, which is harmless for localStorage but would become a server PUT from every window whenever a project appears or disappears.

What changed

Layer 2 of 3 (stack #3306). Base: #3303.

• apps/app/src/lib/ui-preferences/: createSyncedPreferenceAtom is a plain in-memory jotai atom per key. UiPreferencesSync (mounted in App) feeds the uiPreferences query into a controller that hydrates the atoms and writes through a per-key queue. Each queued edit is kept as an operation; functional updates compose in order and a plain value replaces the queue. The write path is one loop: read the base entry (cache or fetch), apply the operations to the server value at that revision, PUT with expectedRevision; on a 409 refetch and try once more with migration operations dropped; on a second 409 adopt the server value. Cache updates from write responses are monotonic in revision, and once a key's queue drains it goes through the same reconcile as query data, so a broadcast that arrived mid-write still lands. Writes issued while one is in flight compose into the next request. Non-conflict failures toast once and invalidate the query.
• No localStorage mirror. The sidebar list now waits for the preferences query alongside the project list (useUiPreferencesReady in ProjectList), showing the same loading state, so it never paints a default layout that then snaps. A failed query counts as ready with defaults.
• One-shot migration in legacy-local-preferences.ts: the first time a client sees a key at revision 0 it reads the old bb.sidebar.* browser value, validates it through the registry, uploads it with expectedRevision: 0, and deletes the old keys (including the retired folder-era and hidden-panel keys, which are cleared but no longer rewritten). A losing migration never retries. This file is the only piece meant to be deleted a release or two later.
• Converted atoms: sidebarOrganizationModeAtom, sidebarChronologicalSortAtom, sidebarSectionOrderAtom, sidebarManualSectionOrderAtom, sidebarMachineSectionOrderAtom, pluginNavPanelOrderAtom, pluginNavVisiblePanelKeysAtom, sidebarNavigationProviderAtom, threadListProviderAtom. Consumers keep the same atom interface. All atomWithStorage wrappers, custom SyncStorage adapters, legacy-key rewrites, and cross-window storage event plumbing for these keys are deleted. A window that is hidden defers its refetch until it becomes visible, which is the app's existing fetch-suspension behavior; the old localStorage mirror had masked that for these keys.
• usePersistedSidebarSectionOrder only derives the normalized order; PluginNavSidebarItems no longer writes normalized order or visibility back on mount and persists the normalized order with the next user action instead.
• docs/configuration.md and the guide template describe the wait-for-preferences behavior and the one-time upload.

Review

One GPT-6 Astra review round requested changes; every finding is addressed in this revision with a regression test:

1. Mounting the navigation strip could overwrite the server order with a normalized empty mirror: the write-back effects are gone.
2. A losing migration retried against revision 1: migration operations are tagged and never retried.
3. A delayed PUT response could roll the cache back below a newer broadcast: cache writes are revision-monotonic and the mirror reconciles to the cache when the queue drains.
4. Coalescing kept only the last functional update for conflict replay: operations compose in order.
5. Writes sent a mirror snapshot with an unrelated revision: operations are evaluated against the server value at the submitted revision.

How you verified

• apps/app/src/lib/ui-preferences/ui-preferences-sync.test.ts, legacy-local-preferences.test.ts, and UiPreferencesSync.test.tsx (readiness while pending, on data, on error): local-only without context, server value adopted over local state, legacy upload at revision 0 and not for defaults, migration never retried, cached revision write, list fetch when nothing cached, functional re-apply after conflict, plain-value retry after conflict, adopt-server after double conflict, coalescing plus reconcile skip, every queued update kept through a conflict, stale local state evaluated against the server value, queued update applied after a conflicting in-flight write, delayed response cannot regress a newer cache, broadcast adopted after the pending write, skip-equal write, toast-once on failure.
• PluginNavSidebarItems.test.tsx updated so mounting persists nothing and user actions persist the normalized order; the obsolete sidebarCollapsedAtoms.migration.test.ts and pluginNavSidebarAtoms.test.ts are replaced by the legacy-migration tests.
• Full @bb/app test suite green. pnpm exec turbo run typecheck --filter='...[origin/main]' green.
• Live in the dev app: a CLI or API write reaches every visible window without a reload; a chevron click in one window lands on the server and shows in another; seeding an old bb.sidebar.* key and reloading uploads it once and clears every old key; a hidden window catches up when brought to front.

AGENT GENERATED

🤖 Generated with Claude Code