fix(sidebar): render workspace recency order on the server to stop refresh reshuffle

Author: waleedlatif1

apps/sim/app/o/[organizationId]/components/organization-sidebar/hooks/use-organization-workspaces.test.tsx

@@ -5,7 +5,9 @@ import { act } from 'react'
 import { createRoot, hydrateRoot, type Root } from 'react-dom/client'
 import { renderToString } from 'react-dom/server'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { WorkspaceRecencyProvider } from '@/components/workspaces/workspace-recency-provider'
 import { STORAGE_KEYS, WorkspaceRecencyStorage } from '@/lib/core/utils/browser-storage'
+import { WORKSPACE_RECENCY_COOKIE } from '@/lib/workspaces/recency-cookie'
 
 const { mockUseWorkspacesQuery, pins } = vi.hoisted(() => ({
   pins: { current: new Set<string>() },
@@ -64,20 +66,31 @@ function workspaceIds() {
 }
 
 describe('useOrganizationWorkspaces', () => {
-  it('hydrates the prefetched order before applying visit history without changing the query cache', async () => {
+  it('renders the visit order on the server so hydration does not reshuffle rows', async () => {
     localStorage.setItem(
       STORAGE_KEYS.WORKSPACE_RECENCY,
       JSON.stringify({ oldest: 100, older: 200, 'other-org': 300 })
     )
-    container.innerHTML = renderToString(<Harness />)
-    expect(workspaceIds()).toEqual(['newest', 'older', 'oldest'])
+    const recentIds = ['other-org', 'older', 'oldest']
+    const tree = (
+      <WorkspaceRecencyProvider recentWorkspaceIds={recentIds}>
+        <Harness />
+      </WorkspaceRecencyProvider>
+    )
+    container.innerHTML = renderToString(tree)
+    expect(workspaceIds()).toEqual(['older', 'oldest', 'newest'])
 
     const onRecoverableError = vi.fn()
+    const observed: string[][] = []
+    const observer = new MutationObserver(() => observed.push(workspaceIds()))
+    observer.observe(container, { childList: true, subtree: true, characterData: true })
     await act(async () => {
-      root = hydrateRoot(container, <Harness />, { onRecoverableError })
+      root = hydrateRoot(container, tree, { onRecoverableError })
     })
+    observer.disconnect()
 
     expect(onRecoverableError).not.toHaveBeenCalled()
+    expect(observed).toEqual([])
     expect(workspaceIds()).toEqual(['older', 'oldest', 'newest'])
     expect(mockUseWorkspacesQuery().data.map(({ id }: { id: string }) => id)).toEqual([
       'newest',
@@ -87,6 +100,15 @@ describe('useOrganizationWorkspaces', () => {
     ])
   })
 
+  it('mirrors visits into the recency cookie', async () => {
+    await act(async () => {
+      root = createRoot(container)
+      root.render(<Harness />)
+    })
+    await act(async () => WorkspaceRecencyStorage.touch('older'))
+    expect(document.cookie).toContain(`${WORKSPACE_RECENCY_COOKIE}=older`)
+  })
+
   it('preserves creation-date order when the browser has no visit history', async () => {
     await act(async () => {
       root = createRoot(container)

apps/sim/app/o/[organizationId]/layout.tsx

@@ -1,12 +1,14 @@
 import { dehydrate, HydrationBoundary } from '@tanstack/react-query'
 import { cookies } from 'next/headers'
 import { redirect } from 'next/navigation'
+import { WorkspaceRecencyProvider } from '@/components/workspaces/workspace-recency-provider'
 import { getSession } from '@/lib/auth'
 import { getActiveOrganizationId } from '@/lib/auth/session-response'
 import { isMothershipModelSelectorEnabled, isPlanModeEnabled } from '@/lib/mothership/feature-flags'
 import { organizationRoutes, WORKSPACE_SETTINGS_PATH } from '@/lib/navigation/paths'
 import { getOrganizationSurfaceContext } from '@/lib/organizations/surface'
 import { isTableRowTtlEnabled } from '@/lib/table/ttl-availability'
+import { parseWorkspaceRecency, WORKSPACE_RECENCY_COOKIE } from '@/lib/workspaces/recency-cookie'
 import { getQueryClient } from '@/app/_shell/providers/get-query-client'
 import { buildAuthCrossLink } from '@/app/(auth)/auth-redirect'
 import { OrganizationAccessDenied } from '@/app/o/[organizationId]/components/organization-access-denied'
@@ -66,6 +68,7 @@ export default async function OrganizationLayout({
     isPlanModeEnabled(),
   ])
   const initialSidebarCollapsed = cookieStore.get('sidebar_collapsed')?.value === '1'
+  const recentWorkspaceIds = parseWorkspaceRecency(cookieStore.get(WORKSPACE_RECENCY_COOKIE)?.value)
 
   return (
     <HydrationBoundary state={dehydrate(queryClient)}>
@@ -81,12 +84,14 @@ export default async function OrganizationLayout({
             <div className='workspace-root flex h-screen w-full flex-col overflow-hidden bg-[var(--surface-1)]'>
               <ImpersonationBanner />
               <SessionExpired />
-              <WorkspaceChrome
-                sidebar={<OrganizationSidebar />}
-                initialSidebarCollapsed={initialSidebarCollapsed}
-              >
-                {children}
-              </WorkspaceChrome>
+              <WorkspaceRecencyProvider recentWorkspaceIds={recentWorkspaceIds}>
+                <WorkspaceChrome
+                  sidebar={<OrganizationSidebar />}
+                  initialSidebarCollapsed={initialSidebarCollapsed}
+                >
+                  {children}
+                </WorkspaceChrome>
+              </WorkspaceRecencyProvider>
             </div>
           </GlobalCommandsProvider>
         </OrganizationProvider>

apps/sim/app/workspace/[workspaceId]/layout.tsx

@@ -1,11 +1,13 @@
 import { dehydrate, HydrationBoundary } from '@tanstack/react-query'
 import { cookies } from 'next/headers'
 import { redirect } from 'next/navigation'
+import { WorkspaceRecencyProvider } from '@/components/workspaces/workspace-recency-provider'
 import { getSession } from '@/lib/auth'
 import { getActiveOrganizationId } from '@/lib/auth/session-response'
 import { isMothershipModelSelectorEnabled, isPlanModeEnabled } from '@/lib/mothership/feature-flags'
 import { resolveOrganizationEntryPath } from '@/lib/navigation/resolve-app-entry'
 import { isTableRowTtlEnabled } from '@/lib/table/ttl-availability'
+import { parseWorkspaceRecency, WORKSPACE_RECENCY_COOKIE } from '@/lib/workspaces/recency-cookie'
 import { getQueryClient } from '@/app/_shell/providers/get-query-client'
 import { ImpersonationBanner } from '@/app/workspace/[workspaceId]/components/impersonation-banner'
 import { SessionExpired } from '@/app/workspace/[workspaceId]/components/session-expired'
@@ -81,6 +83,7 @@ export default async function WorkspaceLayout({
     }),
   ])
   const initialSidebarCollapsed = cookieStore.get('sidebar_collapsed')?.value === '1'
+  const recentWorkspaceIds = parseWorkspaceRecency(cookieStore.get(WORKSPACE_RECENCY_COOKIE)?.value)
 
   return (
     <HydrationBoundary state={dehydrate(queryClient)}>
@@ -108,12 +111,14 @@ export default async function WorkspaceLayout({
                 <SessionExpired />
                 <WorkspacePermissionsProvider>
                   <WorkspaceScopeSync />
-                  <WorkspaceChrome
-                    sidebar={<Sidebar organizationHref={organizationHref} />}
-                    initialSidebarCollapsed={initialSidebarCollapsed}
-                  >
-                    {children}
-                  </WorkspaceChrome>
+                  <WorkspaceRecencyProvider recentWorkspaceIds={recentWorkspaceIds}>
+                    <WorkspaceChrome
+                      sidebar={<Sidebar organizationHref={organizationHref} />}
+                      initialSidebarCollapsed={initialSidebarCollapsed}
+                    >
+                      {children}
+                    </WorkspaceChrome>
+                  </WorkspaceRecencyProvider>
                 </WorkspacePermissionsProvider>
               </div>
             </GlobalCommandsProvider>

apps/sim/components/workspaces/workspace-recency-provider.tsx

@@ -0,0 +1,32 @@
+'use client'
+
+import { createContext, useContext } from 'react'
+
+const EMPTY_RECENT_WORKSPACE_IDS: readonly string[] = []
+
+const WorkspaceRecencyContext = createContext<readonly string[]>(EMPTY_RECENT_WORKSPACE_IDS)
+
+interface WorkspaceRecencyProviderProps {
+  /** Most-recent-first workspace ids read from the recency cookie by the layout. */
+  recentWorkspaceIds: readonly string[]
+  children: React.ReactNode
+}
+
+/**
+ * Hands the server-read visit order to the workspace lists so server render and
+ * hydration agree with the order the browser's visit history applies after it.
+ */
+export function WorkspaceRecencyProvider({
+  recentWorkspaceIds,
+  children,
+}: WorkspaceRecencyProviderProps) {
+  return (
+    <WorkspaceRecencyContext.Provider value={recentWorkspaceIds}>
+      {children}
+    </WorkspaceRecencyContext.Provider>
+  )
+}
+
+export function useInitialRecentWorkspaceIds(): readonly string[] {
+  return useContext(WorkspaceRecencyContext)
+}

apps/sim/hooks/use-workspace-order.ts

@@ -1,13 +1,21 @@
 'use client'
 
 import { useMemo, useSyncExternalStore } from 'react'
+import { useInitialRecentWorkspaceIds } from '@/components/workspaces/workspace-recency-provider'
 import { WorkspaceRecencyStorage } from '@/lib/core/utils/browser-storage'
+import { sortByRecentIds } from '@/lib/workspaces/recency-cookie'
 import type { Workspace } from '@/hooks/queries/workspace'
 
 const serverSnapshot = () => null
 
-/** Layers the viewer's pins and visit history over the server's newest-first list. */
+/**
+ * Layers the viewer's pins and visit history over the server's newest-first list.
+ * Server render and hydration order by the recency cookie, which mirrors the head
+ * of the localStorage history, so switching to that history after hydration does
+ * not reshuffle the rows.
+ */
 export function useWorkspaceOrder(workspaces: Workspace[], pinnedIds: ReadonlySet<string>) {
+  const initialRecentIds = useInitialRecentWorkspaceIds()
   const recencySnapshot = useSyncExternalStore(
     WorkspaceRecencyStorage.subscribe,
     WorkspaceRecencyStorage.getSnapshot,
@@ -16,7 +24,7 @@ export function useWorkspaceOrder(workspaces: Workspace[], pinnedIds: ReadonlySe
   return useMemo(() => {
     const byRecency = recencySnapshot
       ? WorkspaceRecencyStorage.sortByRecency(workspaces)
-      : workspaces
+      : sortByRecentIds(workspaces, initialRecentIds)
     return [...byRecency].sort((a, b) => Number(pinnedIds.has(b.id)) - Number(pinnedIds.has(a.id)))
-  }, [workspaces, pinnedIds, recencySnapshot])
+  }, [workspaces, pinnedIds, recencySnapshot, initialRecentIds])
 }

apps/sim/lib/core/utils/browser-storage.ts

@@ -3,6 +3,10 @@ import {
   workspaceSearchFiltersSchema,
 } from '@/lib/api/contracts/knowledge/search'
 import { AssistantSearchLevel } from '@/lib/mothership/generated/assistant'
+import {
+  serializeWorkspaceRecency,
+  WORKSPACE_RECENCY_COOKIE,
+} from '@/lib/workspaces/recency-cookie'
 /**
  * Safe localStorage utilities with SSR support
  * Provides clean error handling and type safety for browser storage operations
@@ -141,8 +145,10 @@ export class WorkspaceRecencyStorage {
     }
   }
 
+  /** Also mirrors the head of the history into a cookie so server renders use the same order. */
   private static save(map: Record<string, number>): void {
     if (BrowserStorage.setItem(WorkspaceRecencyStorage.KEY, map)) {
+      document.cookie = `${WORKSPACE_RECENCY_COOKIE}=${serializeWorkspaceRecency(map)}; path=/; max-age=31536000; samesite=lax`
       window.dispatchEvent(new Event(WorkspaceRecencyStorage.CHANGE_EVENT))
     }
   }

apps/sim/lib/workspaces/recency-cookie.test.ts

@@ -0,0 +1,40 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, expect, it } from 'vitest'
+import {
+  parseWorkspaceRecency,
+  serializeWorkspaceRecency,
+  sortByRecentIds,
+} from '@/lib/workspaces/recency-cookie'
+
+describe('workspace recency cookie', () => {
+  it('serializes visits most recent first and round-trips through parse', () => {
+    const value = serializeWorkspaceRecency({ a: 1, b: 3, c: 2 })
+    expect(value).toBe('b.c.a')
+    expect(parseWorkspaceRecency(value)).toEqual(['b', 'c', 'a'])
+  })
+
+  it('caps the cookie to the most recent twenty workspaces', () => {
+    const visits = Object.fromEntries(Array.from({ length: 30 }, (_, i) => [`ws-${i}`, i]))
+    const ids = parseWorkspaceRecency(serializeWorkspaceRecency(visits))
+    expect(ids).toHaveLength(20)
+    expect(ids[0]).toBe('ws-29')
+  })
+
+  it('drops malformed ids from a tampered cookie', () => {
+    expect(parseWorkspaceRecency('ok-1.<script>..ok_2')).toEqual(['ok-1', 'ok_2'])
+    expect(parseWorkspaceRecency(undefined)).toEqual([])
+  })
+
+  it('orders tracked items first and keeps untracked items in incoming order', () => {
+    const items = [{ id: 'n1' }, { id: 't2' }, { id: 'n2' }, { id: 't1' }]
+    expect(sortByRecentIds(items, ['t1', 't2']).map(({ id }) => id)).toEqual([
+      't1',
+      't2',
+      'n1',
+      'n2',
+    ])
+    expect(sortByRecentIds(items, [])).toBe(items)
+  })
+})

apps/sim/lib/workspaces/recency-cookie.ts

@@ -0,0 +1,45 @@
+/**
+ * Mirrors the viewer's most recent workspace visits into a cookie so the server
+ * can render the workspace list in the order the browser's visit history will
+ * produce. Visit history itself stays in localStorage; this is only the head of
+ * it, capped because the cookie rides along on every request.
+ */
+export const WORKSPACE_RECENCY_COOKIE = 'workspace_recency'
+
+const MAX_RECENT_WORKSPACES = 20
+const SEPARATOR = '.'
+const WORKSPACE_ID_PATTERN = /^[\w-]{1,64}$/
+
+/** Most-recent-first workspace ids from a visit-time map, ready for `document.cookie`. */
+export function serializeWorkspaceRecency(visits: Record<string, number>): string {
+  return Object.entries(visits)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, MAX_RECENT_WORKSPACES)
+    .map(([id]) => id)
+    .filter((id) => WORKSPACE_ID_PATTERN.test(id))
+    .join(SEPARATOR)
+}
+
+/** Parses the cookie defensively: it is client-written, so malformed ids are dropped. */
+export function parseWorkspaceRecency(value: string | undefined): string[] {
+  if (!value) return []
+  return value
+    .split(SEPARATOR)
+    .filter((id) => WORKSPACE_ID_PATTERN.test(id))
+    .slice(0, MAX_RECENT_WORKSPACES)
+}
+
+/**
+ * Orders items by their position in `recentIds`, leaving untracked items after
+ * them in their incoming order — the same result `sortByRecency` gives for
+ * the ids the cookie holds.
+ */
+export function sortByRecentIds<T extends { id: string }>(
+  items: T[],
+  recentIds: readonly string[]
+): T[] {
+  if (recentIds.length === 0) return items
+  const rank = new Map(recentIds.map((id, index) => [id, index]))
+  const untracked = recentIds.length
+  return [...items].sort((a, b) => (rank.get(a.id) ?? untracked) - (rank.get(b.id) ?? untracked))
+}