improvement(url-state): platform-wide sweep — migrate the last three view-state stragglers, codify conventions

Sweep across landing, workspace, and settings surfaces found only three
remaining candidates (everything else verified clean or correctly non-URL):

- knowledge document page: chunk enabled-status filter joins page/search/sort in
  the URL (?enabled=), resetting page in the same write
- workflow-mcp-servers: detail Details/Workflows tab deep-links via ?server-tab,
  cleared alongside the server id on close
- byok: provider search binds the shared settings ?search= via a controlled
  prop pair (modal/embedded consumers keep local state)

Rule updates (.claude/rules/sim-url-state.md): shallow defaults documented,
urlKeys kebab remapping, throttleMs deprecation, startTransition with
shallow:false, shared-parser null-fallback rule, resolve-before-open gating,
close-with-replace, and the reusable-component controlled-search pattern.

Author: waleedlatif1

.claude/rules/sim-url-state.md

@@ -50,11 +50,13 @@ Co-locate a `search-params.ts` next to the feature. Export the parser map (and s
 
 Conventions:
 
-- `.withDefault(...)` on every parser so reads are non-null.
-- Filter / search / toggle / pagination options: `{ history: 'replace', shallow: true, clearOnDefault: true }` — clean URLs, no back-stack churn.
+- `.withDefault(...)` on every parser so reads are non-null. A deliberately **nullable** parser (dynamic default, custom-range-only dates, nullable sort) must carry a comment saying why.
+- Filter / search / toggle / pagination options: `{ history: 'replace', clearOnDefault: true }` — clean URLs, no back-stack churn. `shallow` defaults to `true` in nuqs; writing `shallow: true` explicitly is fine but not required.
 - Navigations that belong in browser history (changing folder, opening a deep-linked entity): `{ history: 'push' }`.
-- `shallow: false` **only** when a Server Component / loader must re-read the param.
-- Short, stable, **kebab-case** URL keys. Renaming a key is a breaking change to shared links — treat it as one.
+- `shallow: false` **only** when a Server Component / loader must re-read the param. For loading states during the server re-render, pass React's `startTransition` via `.withOptions({ startTransition, shallow: false })`.
+- Short, stable, **kebab-case** URL keys. Renaming a key is a breaking change to shared links — treat it as one. When the parser-map key is camelCase (for clean destructuring), remap the wire key via the `urlKeys` option in the shared options object (see `files/search-params.ts` `uploadedBy: 'uploaded-by'`, `ee/audit-logs/search-params.ts` `timeRange: 'time-range'`); nuqs also exports a `UrlKeys<typeof parsers>` type helper for standalone mappings.
+- `throttleMs` is deprecated in nuqs — rate-limit URL writes with `limitUrlUpdates: throttle(ms)` / `debounce(ms)` (the debounced-search hook below already does this).
+- A parser **shared across surfaces with different defaults** (e.g. `parseAsTimeRange`) must `parse` unknown tokens to `null` — never to one surface's default — so each consumer's `.withDefault(...)` decides the fallback.
 - For an opaque/literal value use `parseAsStringLiteral([...] as const)`; for a custom wire format use [`createParser`](https://nuqs.dev/docs/parsers).
 - A `createParser` for a value **not** comparable with `===` (arrays, objects, `Date`) **must** define an `eq` — `clearOnDefault` uses it to detect the default, so without it an empty-array/object default never strips from the URL. Built-in `parseAsArrayOf(...)` already ships its own `eq`; only string/number/boolean custom parsers can omit it. Example (array): `eq: (a, b) => a.length === b.length && a.every((v, i) => v === b[i])`.
 
@@ -200,7 +202,11 @@ const [skillId, setSkillId] = useQueryState(skillIdParam.key, {
 const editingSkill = skillId ? (skills.find((s) => s.id === skillId) ?? null) : null
 ```
 
-Open the panel/modal when the id resolves to a loaded entity; closing it calls `setSkillId(null)`. Because this reads `useSearchParams` it needs a **Suspense** boundary on the page (see below). A separate "create new" flow has no id and stays in local `useState`.
+Open the panel/modal only when the id **resolves to a loaded entity** — never gate on the raw param alone, or a dead/stale id (deleted entity, old bookmark) renders a broken detail view and a still-loading list flashes one. A dead id simply falls back to the list; the lingering param is harmless. Because this reads `useSearchParams` it needs a **Suspense** boundary on the page (see below). A separate "create new" flow has no id and stays in local `useState`.
+
+**Close with `replace`, open with `push`.** Opening pushed a history entry; closing must not push another. Close via the setter's per-call options — `setSkillId(null, { history: 'replace' })` — so Back from the list leaves the page instead of reopening the detail (see `mcp.tsx`, `workflow-mcp-servers.tsx`, access-control, custom-blocks, forks). Secondary params scoped to the detail view (e.g. its active tab, `server-tab`) are cleared in the same close handler with their own setter — nuqs batches same-tick writes into one URL update.
+
+**Reusable components** rendered both as a settings/list page and inside a modal (e.g. `BYOKKeyManager`) expose an optional controlled `searchTerm`/`onSearchTermChange` prop pair: the page consumer binds the URL (`useSettingsSearch()`), modal consumers omit the props and keep local state. Never bind URL state from inside a component that can mount in a non-destination context.
 
 ## Read-then-strip deep links
 

apps/sim/app/workspace/[workspaceId]/knowledge/[id]/[documentId]/document.tsx

@@ -137,7 +137,12 @@ export function Document({
   const { workspaceId } = useParams()
   const router = useRouter()
   const [
-    { page: currentPageFromURL, chunk: chunkFromURL, search: searchQuery },
+    {
+      page: currentPageFromURL,
+      chunk: chunkFromURL,
+      search: searchQuery,
+      enabled: enabledFilterParam,
+    },
     setDocumentParams,
   ] = useQueryStates(documentParsers, documentUrlKeys)
   const userPermissions = useUserPermissionsContext()
@@ -160,16 +165,31 @@ export function Document({
   )
   /** Raw URL value drives the input; the chunk search query always sees it trimmed. */
   const debouncedSearchQuery = useDebounce(searchQuery, CHUNK_SEARCH_DEBOUNCE_MS).trim()
-  const [enabledFilter, setEnabledFilter] = useState<string[]>([])
   const {
     activeSort,
     onSort: onSortColumn,
     onClear: onClearSort,
   } = useUrlSort(documentChunkSortParams, documentUrlKeys)
 
-  const enabledFilterParam = useMemo(
-    () => (enabledFilter.length === 1 ? (enabledFilter[0] as 'enabled' | 'disabled') : 'all'),
-    [enabledFilter]
+  /** Multi-select UI view of the scalar `enabled` param (`all` ↔ nothing selected). */
+  const enabledFilter = useMemo<string[]>(
+    () => (enabledFilterParam === 'all' ? [] : [enabledFilterParam]),
+    [enabledFilterParam]
+  )
+
+  /**
+   * Collapses the dropdown's multi-select values to the scalar param (one value
+   * filters; none or both mean `all`) and resets `page` in the same write so a
+   * filter change always lands on the first page.
+   */
+  const setEnabledFilter = useCallback(
+    (values: string[]) => {
+      void setDocumentParams({
+        enabled: values.length === 1 ? (values[0] as 'enabled' | 'disabled') : null,
+        page: null,
+      })
+    },
+    [setDocumentParams]
   )
 
   const {
@@ -638,7 +658,6 @@ export function Document({
             onMultiSelectChange={(values) => {
               setEnabledFilter(values)
               setSelectedChunks(new Set())
-              void goToPage(1)
             }}
             overlayContent={
               <span className='truncate text-[var(--text-primary)]'>{enabledDisplayLabel}</span>
@@ -654,7 +673,6 @@ export function Document({
             onClick={() => {
               setEnabledFilter([])
               setSelectedChunks(new Set())
-              void goToPage(1)
             }}
             className='flex h-[32px] w-full items-center justify-center rounded-md text-[var(--text-secondary)] text-caption transition-colors hover-hover:bg-[var(--surface-active)]'
           >
@@ -663,20 +681,19 @@ export function Document({
         )}
       </div>
     ),
-    [enabledFilter, enabledDisplayLabel, goToPage]
+    [enabledFilter, enabledDisplayLabel, setEnabledFilter]
   )
 
   const filterTags: FilterTag[] = useMemo(
     () =>
       enabledFilter.map((value) => ({
         label: `Status: ${value === 'enabled' ? 'Enabled' : 'Disabled'}`,
         onRemove: () => {
-          setEnabledFilter((prev) => prev.filter((v) => v !== value))
+          setEnabledFilter(enabledFilter.filter((v) => v !== value))
           setSelectedChunks(new Set())
-          void goToPage(1)
         },
       })),
-    [enabledFilter, goToPage]
+    [enabledFilter, setEnabledFilter]
   )
 
   const handleChunkClick = useCallback(

apps/sim/app/workspace/[workspaceId]/knowledge/[id]/[documentId]/search-params.ts

@@ -1,6 +1,9 @@
-import { parseAsInteger, parseAsString } from 'nuqs/server'
+import { parseAsInteger, parseAsString, parseAsStringLiteral } from 'nuqs/server'
 import { createSortParams } from '@/lib/url-state'
 
+/** Chunk `enabled` filter buckets, matching the status filter dropdown. */
+const ENABLED_FILTERS = ['all', 'enabled', 'disabled'] as const
+
 /** Sortable chunk columns, matching the `Resource.Options` sort menu ids. */
 export const CHUNK_SORT_COLUMNS = ['index', 'tokens', 'status'] as const
 
@@ -24,11 +27,14 @@ export const documentChunkSortParams = createSortParams(CHUNK_SORT_COLUMNS)
  * - `search` is the chunk content search. The input is controlled directly by
  *   the instant nuqs value; only its URL write is debounced via
  *   `useDebouncedSearchSetter` — never written on every keystroke.
+ * - `enabled` filters chunks by enabled status (`all` clears from the URL),
+ *   mirroring the same filter on the knowledge base document list.
  */
 export const documentParsers = {
   page: parseAsInteger.withDefault(1),
   chunk: parseAsString,
   search: parseAsString.withDefault(''),
+  enabled: parseAsStringLiteral(ENABLED_FILTERS).withDefault('all'),
 } as const
 
 /**

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

@@ -49,6 +49,22 @@ export const forkViewUrlKeys = {
   clearOnDefault: true,
 } as const
 
+/**
+ * `server-tab` is the active tab (Details / Workflows) inside the deep-linked
+ * workflow MCP server detail view, so a shared `mcpServerId` link can land on
+ * either tab.
+ */
+export const serverTabParam = {
+  key: 'server-tab',
+  parser: parseAsStringLiteral(['details', 'workflows'] as const).withDefault('details'),
+} as const
+
+/** Tab view-state: clean URLs, no back-stack churn. */
+export const serverTabUrlKeys = {
+  history: 'replace',
+  clearOnDefault: true,
+} as const
+
 /**
  * `group-id` deep-links the Access Control settings tab to a specific
  * permission group's detail sub-view (mirrors `mcpServerId` on the MCP tab).

apps/sim/app/workspace/[workspaceId]/settings/components/byok/byok-key-manager.tsx

@@ -66,6 +66,13 @@ interface BYOKKeyManagerBaseProps {
   description?: string
   /** Show the provider search box (hidden when there are only a couple). */
   showSearch?: boolean
+  /**
+   * Controlled search value + setter. The BYOK settings page passes the shared
+   * `?search=` binding (`useSettingsSearch`) so the search is deep-linkable;
+   * modal/embedded consumers omit both and keep local state.
+   */
+  searchTerm?: string
+  onSearchTermChange?: (value: string) => void
 }
 
 /** One key per provider; saving replaces the stored key. */
@@ -138,7 +145,9 @@ export function BYOKKeyManager(props: BYOKKeyManagerProps) {
     showSearch = true,
   } = props
 
-  const [searchTerm, setSearchTerm] = useState('')
+  const [localSearchTerm, setLocalSearchTerm] = useState('')
+  const searchTerm = props.searchTerm ?? localSearchTerm
+  const setSearchTerm = props.onSearchTermChange ?? setLocalSearchTerm
   const [editing, setEditing] = useState<EditingState | null>(null)
   const [apiKeyInput, setApiKeyInput] = useState('')
   const [nameInput, setNameInput] = useState('')

apps/sim/app/workspace/[workspaceId]/settings/components/byok/byok.tsx

@@ -48,6 +48,7 @@ import {
   type BYOKProviderSection,
 } from '@/app/workspace/[workspaceId]/settings/components/byok/byok-key-manager'
 import { SettingsPanel } from '@/app/workspace/[workspaceId]/settings/components/settings-panel'
+import { useSettingsSearch } from '@/app/workspace/[workspaceId]/settings/components/use-settings-search'
 import { useBYOKKeys, useDeleteBYOKKey, useUpsertBYOKKey } from '@/hooks/queries/byok-keys'
 import type { BYOKProviderId } from '@/tools/types'
 
@@ -354,6 +355,7 @@ export function BYOK() {
   const workspaceId = (params?.workspaceId as string) || ''
   const workspacePermissions = useUserPermissionsContext()
   const canManage = canMutateWorkspaceSettingsSection('byok', workspacePermissions)
+  const [searchTerm, setSearchTerm] = useSettingsSearch()
 
   const { data, isLoading } = useBYOKKeys(workspaceId)
   const upsertKey = useUpsertBYOKKey()
@@ -381,6 +383,8 @@ export function BYOK() {
         isSaving={upsertKey.isPending}
         isDeleting={deleteKey.isPending}
         readOnly={!canManage}
+        searchTerm={searchTerm}
+        onSearchTermChange={setSearchTerm}
         onSaveKey={async ({ providerId, apiKey, keyId, name }) => {
           await upsertKey.mutateAsync({
             workspaceId,

apps/sim/app/workspace/[workspaceId]/settings/components/workflow-mcp-servers/workflow-mcp-servers.tsx

@@ -32,6 +32,8 @@ import { useUserPermissionsContext } from '@/app/workspace/[workspaceId]/provide
 import {
   mcpServerIdParam,
   mcpServerIdUrlKeys,
+  serverTabParam,
+  serverTabUrlKeys,
 } from '@/app/workspace/[workspaceId]/settings/[section]/search-params'
 import { CreateApiKeyModal } from '@/app/workspace/[workspaceId]/settings/components/api-keys/components'
 import { RowActionsMenu } from '@/app/workspace/[workspaceId]/settings/components/row-actions-menu'
@@ -108,7 +110,10 @@ function ServerDetailView({ canManage, workspaceId, serverId, onBack }: ServerDe
   const [editServerName, setEditServerName] = useState('')
   const [editServerDescription, setEditServerDescription] = useState('')
   const [editServerIsPublic, setEditServerIsPublic] = useState(false)
-  const [activeServerTab, setActiveServerTab] = useState<'workflows' | 'details'>('details')
+  const [activeServerTab, setActiveServerTab] = useQueryState(serverTabParam.key, {
+    ...serverTabParam.parser,
+    ...serverTabUrlKeys,
+  })
 
   const [selectedWorkflowId, setSelectedWorkflowId] = useState<string | null>(null)
 
@@ -401,7 +406,7 @@ function ServerDetailView({ canManage, workspaceId, serverId, onBack }: ServerDe
               { value: 'workflows', label: 'Workflows' },
             ]}
             value={activeServerTab}
-            onChange={(value) => setActiveServerTab(value as 'workflows' | 'details')}
+            onChange={(value) => void setActiveServerTab(value as 'workflows' | 'details')}
           />
 
           <div className='min-h-[300px] pt-4'>
@@ -892,6 +897,11 @@ export function WorkflowMcpServers() {
   })
   const [serverToDelete, setServerToDelete] = useState<WorkflowMcpServer | null>(null)
   const [deletingServers, setDeletingServers] = useState<Set<string>>(() => new Set())
+  /** Cleared alongside the server id on close so the tab never lingers on the list URL. */
+  const [, setServerTab] = useQueryState(serverTabParam.key, {
+    ...serverTabParam.parser,
+    ...serverTabUrlKeys,
+  })
 
   const filteredServers = useMemo(() => {
     if (!searchTerm.trim()) return servers
@@ -948,7 +958,10 @@ export function WorkflowMcpServers() {
         canManage={canAdmin}
         workspaceId={workspaceId}
         serverId={selectedServerId}
-        onBack={() => setSelectedServerId(null, { history: 'replace' })}
+        onBack={() => {
+          void setServerTab(null, { history: 'replace' })
+          void setSelectedServerId(null, { history: 'replace' })
+        }}
       />
     )
   }