feat(home): migrate ?resource deep-link to nuqs (URL as source of truth)

Replace the banned window.history.replaceState effect on the home/Chat
surface with a nuqs useQueryState('resource') binding. The URL is now the
single source of truth for the selected resource.

- Add co-located home/search-params.ts (resource param, history: replace)
- useChat accepts a controlled activeResourceState binding; home passes the
  nuqs-backed tuple. The workflow editor copilot keeps internal useState so
  its resource selection stays out of the URL (editor carve-out)
- Preserve the old effect's url.hash='' fragment strip in the binding setter
  (fragment-only rewrite, not a param mutation)
- Drop initialResourceId SSR prop from both page entries (nuqs reads the URL
  on mount; no dual source) and wrap Home in Suspense for useSearchParams

Author: waleedlatif1

apps/sim/app/workspace/[workspaceId]/chat/[chatId]/page.tsx

@@ -1,6 +1,8 @@
+import { Suspense } from 'react'
 import type { Metadata } from 'next'
 import { getSession } from '@/lib/auth'
 import { Home } from '@/app/workspace/[workspaceId]/home/home'
+import { HomeFallback } from '@/app/workspace/[workspaceId]/home/home-fallback'
 
 export const metadata: Metadata = {
   title: 'Chat',
@@ -11,22 +13,18 @@ interface ChatPageProps {
     workspaceId: string
     chatId: string
   }>
-  searchParams: Promise<{ resource?: string }>
 }
 
-export default async function ChatPage({ params, searchParams }: ChatPageProps) {
-  const [{ chatId }, { resource }, session] = await Promise.all([
-    params,
-    searchParams,
-    getSession(),
-  ])
+export default async function ChatPage({ params }: ChatPageProps) {
+  const [{ chatId }, session] = await Promise.all([params, getSession()])
   return (
-    <Home
-      key={chatId}
-      chatId={chatId}
-      userName={session?.user?.name}
-      userId={session?.user?.id}
-      initialResourceId={resource ?? null}
-    />
+    <Suspense fallback={<HomeFallback />}>
+      <Home
+        key={chatId}
+        chatId={chatId}
+        userName={session?.user?.name}
+        userId={session?.user?.id}
+      />
+    </Suspense>
   )
 }

apps/sim/app/workspace/[workspaceId]/home/home-fallback.tsx

@@ -0,0 +1,10 @@
+/**
+ * Suspense fallback for the home/Chat surface. `Home` reads the `?resource=`
+ * URL param via nuqs (`useQueryState`, which uses `useSearchParams`
+ * internally), so it must sit under a Suspense boundary. This renders the
+ * surface background so a suspend never flashes a blank frame before the chat
+ * mounts.
+ */
+export function HomeFallback() {
+  return <div className='h-full bg-[var(--bg)]' />
+}

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

@@ -1,8 +1,17 @@
 'use client'
 
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import {
+  type Dispatch,
+  type SetStateAction,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
 import { createLogger } from '@sim/logger'
 import { useParams, useRouter } from 'next/navigation'
+import { useQueryState } from 'nuqs'
 import { usePostHog } from 'posthog-js/react'
 import { Button } from '@/components/emcn'
 import { PanelLeft } from '@/components/emcn/icons'
@@ -25,6 +34,7 @@ import {
 } from '@/lib/mothership/events'
 import { captureEvent } from '@/lib/posthog/client'
 import { persistImportedWorkflow } from '@/lib/workflows/operations/import-export'
+import { resourceParam, resourceUrlKeys } from '@/app/workspace/[workspaceId]/home/search-params'
 import { useFolders } from '@/hooks/queries/folders'
 import {
   useMarkMothershipChatRead,
@@ -53,13 +63,42 @@ interface HomeProps {
   chatId?: string
   userName?: string
   userId?: string
-  initialResourceId?: string | null
 }
 
-export function Home({ chatId, userName, userId, initialResourceId = null }: HomeProps) {
+export function Home({ chatId, userName, userId }: HomeProps) {
   useOAuthReturnRouter()
   const { workspaceId } = useParams<{ workspaceId: string }>()
   const router = useRouter()
+  // URL is the single source of truth for the selected resource. `Home` renders
+  // client-side, so nuqs reads `?resource=` from the URL on mount — the same
+  // value the page previously threaded through `initialResourceId` — and writes
+  // it back with `history: 'replace'`, the previous behavior, minus the banned
+  // `window.history.replaceState` param-mutation effect. The page wraps `Home`
+  // in Suspense for the `useSearchParams` requirement.
+  const [activeResourceParam, setResourceParam] = useQueryState(resourceParam.key, {
+    ...resourceParam.parser,
+    ...resourceUrlKeys,
+  })
+  // Strips any leftover URL fragment on selection change, preserving the old
+  // effect's `url.hash = ''` (the only hash usage on this surface) without a
+  // separate effect-sync mirror. This rewrites the fragment only — it never
+  // mutates a query param via the History API.
+  const setActiveResourceUrl = useCallback<Dispatch<SetStateAction<string | null>>>(
+    (action) => {
+      if (typeof window !== 'undefined' && window.location.hash) {
+        const { pathname, search } = window.location
+        window.history.replaceState(window.history.state, '', `${pathname}${search}`)
+      }
+      void setResourceParam(action)
+    },
+    [setResourceParam]
+  )
+  // Controlled binding handed to `useChat` so the URL is the sole owner of the
+  // selection with no dual source.
+  const activeResourceState = useMemo<[string | null, Dispatch<SetStateAction<string | null>>]>(
+    () => [activeResourceParam, setActiveResourceUrl],
+    [activeResourceParam, setActiveResourceUrl]
+  )
   const firstName = userName?.split(' ')[0] ?? ''
   const { data: workspaceFiles = [] } = useWorkspaceFiles(workspaceId)
   const { data: workflows = [] } = useWorkflows(workspaceId)
@@ -179,7 +218,7 @@ export function Home({ chatId, userName, userId, initialResourceId = null }: Hom
     chatId,
     getMothershipUseChatOptions({
       onResourceEvent: handleResourceEvent,
-      initialActiveResourceId: initialResourceId,
+      activeResourceState,
       onRequestStarted: ({ requestId, userMessageId }) => {
         captureEvent(posthogRef.current, 'task_request_started', {
           workspace_id: workspaceId,
@@ -191,17 +230,6 @@ export function Home({ chatId, userName, userId, initialResourceId = null }: Hom
     })
   )
 
-  useEffect(() => {
-    const url = new URL(window.location.href)
-    if (activeResourceId) {
-      url.searchParams.set('resource', activeResourceId)
-    } else {
-      url.searchParams.delete('resource')
-    }
-    url.hash = ''
-    window.history.replaceState(null, '', url.toString())
-  }, [activeResourceId])
-
   useEffect(() => {
     wasSendingRef.current = false
     if (resolvedChatId) {

apps/sim/app/workspace/[workspaceId]/home/hooks/use-chat.ts

@@ -1,4 +1,12 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import {
+  type Dispatch,
+  type SetStateAction,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
 import { createLogger } from '@sim/logger'
 import { getErrorMessage, toError } from '@sim/utils/errors'
 import { sleep } from '@sim/utils/helpers'
@@ -987,6 +995,17 @@ export interface UseChatOptions {
   onTitleUpdate?: () => void
   onStreamEnd?: (chatId: string, messages: ChatMessage[]) => void
   initialActiveResourceId?: string | null
+  /**
+   * Controlled binding for the active resource id, supplied as a
+   * `[value, setValue]` tuple (e.g. a URL-backed nuqs `useQueryState`). When
+   * provided, it is the single source of truth for the selected resource — the
+   * hook reads and writes it directly instead of owning the state internally,
+   * so no effect-sync mirror is needed. When omitted, `useChat` owns the state
+   * via local `useState` (seeded from `initialActiveResourceId`); this is the
+   * mode used by the socket-synced workflow editor copilot, whose resource
+   * selection intentionally stays out of the URL.
+   */
+  activeResourceState?: [string | null, Dispatch<SetStateAction<string | null>>]
   /** Fired when the server's `traceparent` response header arrives, before any stream content. */
   onRequestStarted?: (info: { requestId: string; userMessageId: string }) => void
 }
@@ -1006,7 +1025,11 @@ interface StopGenerationOptions {
 export function getMothershipUseChatOptions(
   options: Pick<
     UseChatOptions,
-    'onResourceEvent' | 'onStreamEnd' | 'initialActiveResourceId' | 'onRequestStarted'
+    | 'onResourceEvent'
+    | 'onStreamEnd'
+    | 'initialActiveResourceId'
+    | 'activeResourceState'
+    | 'onRequestStarted'
   > = {}
 ): UseChatOptions {
   return {
@@ -1044,9 +1067,14 @@ export function useChat(
   const [resolvedChatId, setResolvedChatId] = useState<string | undefined>(initialChatId)
   const [queuedHandoffRecoveryEpoch, setQueuedHandoffRecoveryEpoch] = useState(0)
   const [resources, setResources] = useState<MothershipResource[]>([])
-  const [activeResourceId, setActiveResourceId] = useState<string | null>(
+  const internalActiveResourceState = useState<string | null>(
     options?.initialActiveResourceId ?? null
   )
+  // Prefer a caller-supplied controlled binding (URL-backed nuqs on the home/Chat
+  // surface) so the URL is the single source of truth; fall back to internal state
+  // for the workflow editor copilot, which keeps resource selection out of the URL.
+  const [activeResourceId, setActiveResourceId] =
+    options?.activeResourceState ?? internalActiveResourceState
   const [genericResourceData, setGenericResourceData] = useState<GenericResourceData | null>(null)
   const onResourceEventRef = useRef(options?.onResourceEvent)
   const revealedSimKeysRef = useRef<RevealedSimKeysByMessage>(new Map())

apps/sim/app/workspace/[workspaceId]/home/page.tsx

@@ -1,22 +1,18 @@
+import { Suspense } from 'react'
 import type { Metadata } from 'next'
 import { getSession } from '@/lib/auth'
 import { Home } from './home'
+import { HomeFallback } from './home-fallback'
 
 export const metadata: Metadata = {
   title: 'New chat',
 }
 
-interface HomePageProps {
-  searchParams: Promise<{ resource?: string }>
-}
-
-export default async function HomePage({ searchParams }: HomePageProps) {
-  const [session, { resource }] = await Promise.all([getSession(), searchParams])
+export default async function HomePage() {
+  const session = await getSession()
   return (
-    <Home
-      userName={session?.user?.name}
-      userId={session?.user?.id}
-      initialResourceId={resource ?? null}
-    />
+    <Suspense fallback={<HomeFallback />}>
+      <Home userName={session?.user?.name} userId={session?.user?.id} />
+    </Suspense>
   )
 }

apps/sim/app/workspace/[workspaceId]/home/search-params.ts

@@ -0,0 +1,27 @@
+import { parseAsString } from 'nuqs/server'
+
+/**
+ * Co-located, typed URL query-param definition for the home/Chat surface.
+ *
+ * `resource` deep-links the resource panel to the selected resource. The active
+ * resource id is the single source of truth for which resource the panel shows;
+ * `useChat` reads and writes it through this param, and the effective selection
+ * is derived against the loaded resource list (an unknown/stale id falls back to
+ * the last resource). The URL key is `resource` — existing shared links depend on
+ * it, so it must not be renamed.
+ */
+export const resourceParam = {
+  key: 'resource',
+  parser: parseAsString,
+} as const
+
+/**
+ * Selecting a resource is a filter-like view change, not back-stack navigation,
+ * so it replaces the current history entry (matching the previous
+ * `window.history.replaceState` behavior). `clearOnDefault` drops the key from
+ * the URL when no resource is active.
+ */
+export const resourceUrlKeys = {
+  history: 'replace',
+  clearOnDefault: true,
+} as const