fix(url-state): verification-round fixes — reject unparseable date params, tighten docs

- new parseAsDateString parser (logs + audit-logs): an unparseable
  ?start-date=/?end-date= now parses to null (missing bound) instead of
  crashing the audit-logs render via Invalid Date .toISOString(), and hardens
  the same class in logs
- audit-logs: remove the provably dead cancel-revert branch and its ref —
  the URL only holds 'Custom range' after Apply writes both bounds atomically
- workflow-mcp-servers: reset a lingering ?server-tab= when opening a server
  so a dead deep link can't re-target the next open
- knowledge document: drop the unreachable 'N selected' label branch
- sim-url-state.md fact-check corrections: cover apps/sim/ee in paths,
  focusedBlockId -> currentBlockId (the real store field), note that
  history/clearOnDefault are nuqs v2 defaults, fix the Suspense
  cross-reference and parseAsIsoDate serialize detail, clarify the *UrlKeys
  naming convention; list byok in the shared-search consumer docs

Author: waleedlatif1

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

@@ -3,6 +3,8 @@ paths:
   - "apps/sim/app/**/*.tsx"
   - "apps/sim/app/**/*.ts"
   - "apps/sim/app/**/search-params.ts"
+  - "apps/sim/ee/**/*.tsx"
+  - "apps/sim/ee/**/*.ts"
 ---
 
 # URL / Query-Param State (nuqs)
@@ -51,7 +53,7 @@ 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. 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.
+- Filter / search / toggle / pagination options: `{ history: 'replace', clearOnDefault: true }` — clean URLs, no back-stack churn. Note all three of `history: 'replace'`, `clearOnDefault: true`, and `shallow: true` are already the nuqs v2 defaults — writing the first two explicitly is documentation (and guards the groups whose options differ, e.g. `history: 'push'`), and `shallow: true` may be omitted entirely.
 - 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. 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.
@@ -77,11 +79,12 @@ export const thingsParsers = {
 /** Clean URLs, no back-stack churn for filter changes. */
 export const thingsUrlKeys = {
   history: 'replace',
-  shallow: true,
   clearOnDefault: true,
 } as const
 ```
 
+(The `*UrlKeys` suffix is the repo's naming convention for a feature's shared **options** object — which may itself contain a nuqs `urlKeys` key-remapping entry; the two are different things.)
+
 ### Client — `useQueryStates` (grouped) / `useQueryState` (single)
 
 ```typescript
@@ -184,7 +187,7 @@ Sort params live alongside — not inside — the feature's grouped filter parse
 
 A date-only param (a calendar anchor, a date filter) is stored as `yyyy-MM-dd` — never serialize a full `Date`/timestamp when only the day matters.
 
-**Local vs UTC — pick the parser that matches your date math.** nuqs's built-in `parseAsIsoDate` is **UTC-based** (`serialize` via `toISOString()`, `parse` to UTC midnight). If your `Date` is local-time (e.g. produced by local-time helpers and read by `date-fns` `startOfWeek`/`isSameDay`, which are all local), `parseAsIsoDate` will shift the day by ±1 in any non-UTC timezone on reload/deep-link/back-forward. For local-time date math, use a small local-date `createParser` that serializes/parses on local calendar fields (`getFullYear`/`getMonth`/`getDate` ↔ `new Date(y, m-1, d)`) with an `eq` comparing y/m/d. Only use `parseAsIsoDate` when the value is genuinely UTC/midnight-UTC. See `scheduled-tasks/search-params.ts` (`parseAsLocalDate`).
+**Local vs UTC — pick the parser that matches your date math.** nuqs's built-in `parseAsIsoDate` is **UTC-based** (`serialize` via `toISOString().slice(0, 10)`, `parse` to UTC midnight). If your `Date` is local-time (e.g. produced by local-time helpers and read by `date-fns` `startOfWeek`/`isSameDay`, which are all local), `parseAsIsoDate` will shift the day by ±1 in any non-UTC timezone on reload/deep-link/back-forward. For local-time date math, use a small local-date `createParser` that serializes/parses on local calendar fields (`getFullYear`/`getMonth`/`getDate` ↔ `new Date(y, m-1, d)`) with an `eq` comparing y/m/d. Only use `parseAsIsoDate` when the value is genuinely UTC/midnight-UTC. See `scheduled-tasks/search-params.ts` (`parseAsLocalDate`).
 
 When the default is **dynamic** (e.g. "today"), make the param **nullable** (omit `.withDefault`) and derive the fallback in the hook (`const anchor = param ?? today`), so a clean URL means the dynamic default and navigating back to it writes `null` (clears the param). See `scheduled-tasks/hooks/use-calendar.ts`.
 
@@ -202,7 +205,7 @@ const [skillId, setSkillId] = useQueryState(skillIdParam.key, {
 const editingSkill = skillId ? (skills.find((s) => s.id === skillId) ?? null) : null
 ```
 
-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`.
+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 "Suspense boundary" above). 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.
 
@@ -223,8 +226,8 @@ The workflow editor (`apps/sim/app/workspace/[workspaceId]/w/**`) is realtime/so
 
 Borderline candidates that *look* shareable but currently stay in Zustand because moving them fights existing machinery:
 
-- **Panel `activeTab`** and **`canvasMode`** — persisted local *preferences* wired into an SSR flash-prevention path (`data-panel-active-tab` + `_hasHydrated`). They are layout prefs, not destinations; moving them would unwind the SSR machinery and risk tab-flash on load.
-- **`focusedBlockId`** ("look at this block") — the only genuinely shareable candidate, but it is entangled with the persisted editor store and panel-open orchestration. Adding it is a *new feature*, not a migration; ship it deliberately (with runtime verification against a live socket), not as part of a sweep.
+- **Panel `activeTab`** — a persisted local *preference* wired into an SSR flash-prevention path (`data-panel-active-tab` + `_hasHydrated`); moving it would unwind that machinery and risk tab-flash on load. **Canvas mode** (`mode` on `useCanvasModeStore`) is likewise a persisted layout preference, not a destination.
+- **The panel editor's `currentBlockId`** (`stores/panel/editor/store.ts` — a would-be "look at this block" deep link) — the only genuinely shareable candidate, but it is persisted and entangled with panel-open orchestration. Adding a URL param for it is a *new feature*, not a migration; ship it deliberately (with runtime verification against a live socket), not as part of a sweep.
 
 Rule of thumb for the editor: if state is socket-coupled, high-frequency, viewport-related, or a persisted resize/preference, it stays in Zustand. When in doubt, leave it and flag it — do not force fragile URL state into the canvas.
 

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

@@ -639,8 +639,7 @@ export function Document({
 
   const enabledDisplayLabel = useMemo(() => {
     if (enabledFilter.length === 0) return 'All'
-    if (enabledFilter.length === 1) return enabledFilter[0] === 'enabled' ? 'Enabled' : 'Disabled'
-    return `${enabledFilter.length} selected`
+    return enabledFilter[0] === 'enabled' ? 'Enabled' : 'Disabled'
   }, [enabledFilter])
 
   const filterContent = useMemo(

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

@@ -77,6 +77,21 @@ export const parseAsLogLevel = createParser<LogLevel>({
   },
 })
 
+/**
+ * Parser for free-form date/datetime strings (`startDate`/`endDate`). Rejects
+ * unparseable values at the URL boundary — an invalid date string reaching
+ * `new Date(...).toISOString()` throws, so a malformed deep link must parse to
+ * `null` (treated as a missing bound) instead of crashing the consumer.
+ */
+export const parseAsDateString = createParser<string>({
+  parse(value) {
+    return Number.isNaN(Date.parse(value)) ? null : value
+  },
+  serialize(value) {
+    return value
+  },
+})
+
 const CORE_TRIGGER_SET = new Set<string>(CORE_TRIGGER_TYPES)
 
 /**
@@ -109,8 +124,8 @@ export const logFilterParsers = {
    * Deliberately nullable: only populated when timeRange is "Custom range";
    * every preset range derives its window from the label instead.
    */
-  startDate: parseAsString,
-  endDate: parseAsString,
+  startDate: parseAsDateString,
+  endDate: parseAsDateString,
   level: parseAsLogLevel.withDefault('all'),
   workflowIds: parseAsArrayOf(parseAsString).withDefault([]),
   folderIds: parseAsArrayOf(parseAsString).withDefault([]),

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

@@ -2,7 +2,7 @@ import { parseAsString } from 'nuqs/server'
 
 /**
  * Shared URL query-param definition for the settings list search boxes
- * (teammates, api-keys, copilot, custom-tools, mcp, secrets,
+ * (teammates, api-keys, byok, copilot, custom-tools, mcp, secrets,
  * workflow-mcp-servers, and the ee sections: audit-logs, access-control,
  * custom-blocks, data-drains, forks). Settings sections never co-render, so
  * they all share the `search` key without collisions.

apps/sim/app/workspace/[workspaceId]/settings/components/use-settings-search.ts

@@ -9,8 +9,9 @@ import { useDebouncedSearchSetter } from '@/hooks/use-debounced-search-setter'
 
 /**
  * The shared `?search=` binding for settings list search boxes (teammates,
- * api-keys, copilot, custom-tools, mcp, secrets, workflow-mcp-servers, and the
- * ee sections: audit-logs, access-control, custom-blocks, data-drains, forks).
+ * api-keys, byok, copilot, custom-tools, mcp, secrets, workflow-mcp-servers,
+ * and the ee sections: audit-logs, access-control, custom-blocks, data-drains,
+ * forks).
  * Composes `useDebouncedSearchSetter`, so it carries the canonical semantics:
  * the value updates instantly (drives the controlled input and the in-memory
  * filter), non-empty URL writes are debounced, and clearing (or a

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

@@ -1024,7 +1024,14 @@ export function WorkflowMcpServers() {
                       <RowActionsMenu
                         label='Server actions'
                         actions={[
-                          { label: 'Details', onSelect: () => setSelectedServerId(server.id) },
+                          {
+                            label: 'Details',
+                            onSelect: () => {
+                              // A lingering ?server-tab= (dead deep link) must not re-target the next open — reset it in the same batched push.
+                              void setServerTab(null)
+                              void setSelectedServerId(server.id)
+                            },
+                          },
                           ...(canAdmin
                             ? [
                                 {

apps/sim/ee/audit-logs/components/audit-logs.tsx

@@ -251,10 +251,6 @@ export function AuditLogs({ organizationId }: AuditLogsProps) {
       ? DEFAULT_AUDIT_TIME_RANGE
       : urlFilters.timeRange
   const [datePickerOpen, setDatePickerOpen] = useState(false)
-  /** Cancel target for the date picker — never 'Custom range' itself, so a deep link straight to an empty custom range still cancels back to a preset. */
-  const previousTimeRangeRef = useRef<TimeRange>(
-    timeRange === 'Custom range' ? DEFAULT_AUDIT_TIME_RANGE : timeRange
-  )
   const dateRangeAppliedRef = useRef(false)
   const [searchTerm, setSearchTerm] = useSettingsSearch()
   const debouncedSearch = useDebounce(searchTerm, SEARCH_DEBOUNCE_MS).trim()
@@ -307,7 +303,6 @@ export function AuditLogs({ organizationId }: AuditLogsProps) {
 
   const handleTimeRangeChange = (value: string) => {
     if (value === 'Custom range') {
-      previousTimeRangeRef.current = timeRange
       setDatePickerOpen(true)
     } else {
       void setUrlFilters({ timeRange: value as TimeRange, startDate: null, endDate: null })
@@ -320,10 +315,11 @@ export function AuditLogs({ organizationId }: AuditLogsProps) {
     setDatePickerOpen(false)
   }
 
+  /**
+   * Cancel is a pure close: the URL only ever holds 'Custom range' after Apply
+   * wrote both bounds atomically, so there is never a pending state to revert.
+   */
   const handleDatePickerCancel = () => {
-    if (timeRange === 'Custom range' && !customStartDate) {
-      void setUrlFilters({ timeRange: previousTimeRangeRef.current })
-    }
     setDatePickerOpen(false)
   }
 

apps/sim/ee/audit-logs/search-params.ts

@@ -1,5 +1,8 @@
 import { parseAsArrayOf, parseAsString } from 'nuqs/server'
-import { parseAsTimeRange } from '@/app/workspace/[workspaceId]/logs/search-params'
+import {
+  parseAsDateString,
+  parseAsTimeRange,
+} from '@/app/workspace/[workspaceId]/logs/search-params'
 import type { TimeRange } from '@/stores/logs/filters/types'
 
 export const DEFAULT_AUDIT_TIME_RANGE: TimeRange = 'Past 30 days'
@@ -18,8 +21,8 @@ export const DEFAULT_AUDIT_TIME_RANGE: TimeRange = 'Past 30 days'
 export const auditLogFilterParsers = {
   types: parseAsArrayOf(parseAsString).withDefault([]),
   timeRange: parseAsTimeRange.withDefault(DEFAULT_AUDIT_TIME_RANGE),
-  startDate: parseAsString,
-  endDate: parseAsString,
+  startDate: parseAsDateString,
+  endDate: parseAsDateString,
 } as const
 
 /** Filter view-state: clean URLs, no back-stack churn, kebab-case URL keys. */