From bcf69fa5f4425b1ae756beb0b1919b55ad42ffab Mon Sep 17 00:00:00 2001
From: Waleed Latif <walif6@gmail.com>
Date: Sat, 7 Nov 2026 13:27:13 -0800
Subject: [PATCH 1/2] fix(docs): keep search responsive and contain sidebar
 scrolling

---
 .../components/docs/navigation-drawer.tsx     |   2 +-
 apps/docs/components/docs/shell.tsx           |   2 +-
 apps/docs/hooks/queries/search.ts             |  19 +-
 apps/docs/lib/search/build.ts                 |  35 +++-
 apps/docs/lib/search/precomputed.ts           |  12 +-
 apps/docs/lib/search/service.ts               | 174 +++++++++---------
 apps/docs/lib/search/types.ts                 |   9 +
 apps/docs/lib/search/utils.ts                 |   2 +-
 apps/docs/scripts/compile-content.ts          |   3 +-
 apps/docs/scripts/test-generators-e2e.ts      |   9 +-
 apps/docs/scripts/test-navigation-e2e.ts      |  19 ++
 apps/docs/scripts/test-search-postgres-e2e.ts | 153 +++++++++++++--
 12 files changed, 332 insertions(+), 107 deletions(-)

diff --git a/apps/docs/components/docs/navigation-drawer.tsx b/apps/docs/components/docs/navigation-drawer.tsx
index fa44acbe3b7..03aa7abcb58 100644
--- a/apps/docs/components/docs/navigation-drawer.tsx
+++ b/apps/docs/components/docs/navigation-drawer.tsx
@@ -54,7 +54,7 @@ export function DocsNavigationDrawer({ children }: DocsNavigationDrawerProps) {
             }}
             className={cn(
               docsScrollAreaClass,
-              '-mx-1 mt-5 min-h-0 flex-1 overflow-y-auto overscroll-contain px-1 pb-6'
+              '-mx-1 mt-5 min-h-0 flex-1 overflow-y-auto overflow-x-hidden overscroll-contain px-1 pb-6'
             )}
           >
             <SidebarNavigation
diff --git a/apps/docs/components/docs/shell.tsx b/apps/docs/components/docs/shell.tsx
index 212c6a2a960..e3192d808c6 100644
--- a/apps/docs/components/docs/shell.tsx
+++ b/apps/docs/components/docs/shell.tsx
@@ -98,7 +98,7 @@ export function DocsShell({ children, navigationBySection }: DocsShellProps) {
               key={section}
               className={cn(
                 docsScrollAreaClass,
-                '-mx-1 sticky top-24 hidden max-h-[calc(100dvh-120px)] min-w-0 space-y-5 overflow-y-auto overscroll-contain px-1 pb-5 lg:block'
+                '-mx-1 sticky top-24 hidden max-h-[calc(100dvh-120px)] min-w-0 space-y-5 overflow-y-auto overflow-x-hidden overscroll-contain px-1 pb-5 lg:block'
               )}
             >
               <DocsSearchTrigger />
diff --git a/apps/docs/hooks/queries/search.ts b/apps/docs/hooks/queries/search.ts
index 76226da52a2..3e1d599a6b0 100644
--- a/apps/docs/hooks/queries/search.ts
+++ b/apps/docs/hooks/queries/search.ts
@@ -5,6 +5,7 @@ import { z } from 'zod'
 
 const SEARCH_STALE_TIME = 60_000
 const SEARCH_GC_TIME = 300_000
+const SEARCH_TIMEOUT_MS = 5000
 const searchKeys = {
   all: ['docs-search'] as const,
   query: (query: string) => [...searchKeys.all, query] as const,
@@ -28,9 +29,21 @@ export function useDocsSearch(query: string) {
     gcTime: SEARCH_GC_TIME,
     retry: false,
     queryFn: async ({ signal }) => {
-      const response = await fetch(`/api/search?query=${encodeURIComponent(query)}`, { signal })
-      if (!response.ok) throw new Error('Search is unavailable. Try again.')
-      return resultsSchema.parse(await response.json())
+      const controller = new AbortController()
+      const abort = () => controller.abort(signal.reason)
+      signal.addEventListener('abort', abort, { once: true })
+      if (signal.aborted) abort()
+      const timeout = setTimeout(() => controller.abort(), SEARCH_TIMEOUT_MS)
+      try {
+        const response = await fetch(`/api/search?query=${encodeURIComponent(query)}`, {
+          signal: controller.signal,
+        })
+        if (!response.ok) throw new Error('Search is unavailable. Try again.')
+        return resultsSchema.parse(await response.json())
+      } finally {
+        clearTimeout(timeout)
+        signal.removeEventListener('abort', abort)
+      }
     },
   })
 }
diff --git a/apps/docs/lib/search/build.ts b/apps/docs/lib/search/build.ts
index d0f49c07f9a..4bf2986b7dc 100644
--- a/apps/docs/lib/search/build.ts
+++ b/apps/docs/lib/search/build.ts
@@ -1,9 +1,40 @@
-import type { DocsPage } from '@/lib/content/types'
+import { findNavigationGroup } from '@/lib/content/navigation'
+import type { ContentCatalog, DocsPage } from '@/lib/content/types'
 import { pageSearchChunks } from '@/lib/search/chunks'
-import type { SearchIndex } from '@/lib/search/types'
+import type { SearchIndex, SearchPage } from '@/lib/search/types'
 import { normalizeSearchText, searchCatalogHash } from '@/lib/search/utils'
 
 const MAX_SEARCH_INDEX_BYTES = 64 * 1024 * 1024
+const MAX_SEARCH_CATALOG_BYTES = 4 * 1024 * 1024
+const SECTION_LABELS = { docs: 'Documentation', api: 'API reference', cli: 'CLI', mcp: 'MCP' }
+
+/** Search citations need document identity and navigation, without loading document bodies. */
+export function buildSearchCatalog(catalog: ContentCatalog): SearchPage[] {
+  const pages: SearchPage[] = []
+  let bytes = 0
+  for (const page of catalog.pages) {
+    if (page.url === '/') continue
+    const section = SECTION_LABELS[page.section]
+    const group = findNavigationGroup(catalog.navigation[page.section], page.url)
+    const entry: SearchPage = {
+      id: page.id,
+      url: page.url,
+      title: page.title,
+      contentHash: page.contentHash,
+      headings: page.headings.map((heading) => heading.id),
+      breadcrumbs: [
+        section,
+        ...(group && group !== section && group !== page.title ? [group] : []),
+        page.title,
+      ],
+    }
+    bytes += Buffer.byteLength(JSON.stringify(entry)) + 1
+    if (bytes > MAX_SEARCH_CATALOG_BYTES - 2)
+      throw new Error('Generated search catalog exceeds the 4 MiB size budget')
+    pages.push(entry)
+  }
+  return pages
+}
 
 /** Build-time parsing keeps the public search cold path independent of corpus Markdown size. */
 export function buildSearchIndex(pages: DocsPage[]): SearchIndex {
diff --git a/apps/docs/lib/search/precomputed.ts b/apps/docs/lib/search/precomputed.ts
index 61f12a888e3..db2a7e63a01 100644
--- a/apps/docs/lib/search/precomputed.ts
+++ b/apps/docs/lib/search/precomputed.ts
@@ -1,14 +1,20 @@
 import 'server-only'
-import { getPages } from '@/lib/content/catalog'
-import type { SearchIndex } from '@/lib/search/types'
+import type { SearchIndex, SearchPage } from '@/lib/search/types'
 import { searchCatalogHash } from '@/lib/search/utils'
 import generatedIndex from '@/.content/search.json'
+import generatedCatalog from '@/.content/search-catalog.json'
 
 const index = generatedIndex as SearchIndex
-if (index.version !== 1 || index.catalogHash !== searchCatalogHash(getPages()))
+const pages = generatedCatalog as SearchPage[]
+const pagesByUrl = new Map(pages.map((page) => [page.url, page]))
+if (index.version !== 1 || index.catalogHash !== searchCatalogHash(pages))
   throw new Error('Search index does not match the documentation catalog. Run content:generate.')
 
 /** An immutable server-only index, generated and published with the canonical catalog. */
 export function getSearchIndex() {
   return index.entries
 }
+
+export function getSearchPage(path: string) {
+  return pagesByUrl.get(path)
+}
diff --git a/apps/docs/lib/search/service.ts b/apps/docs/lib/search/service.ts
index 5423a4772b8..ca8717f846d 100644
--- a/apps/docs/lib/search/service.ts
+++ b/apps/docs/lib/search/service.ts
@@ -1,11 +1,8 @@
 import { createLogger } from '@sim/logger'
 import { compareStrings, truncateAtCodePoint } from '@sim/utils/string'
-import { getNavigation, getPage } from '@/lib/content/catalog'
-import { findNavigationGroup } from '@/lib/content/navigation'
-import type { DocsPage } from '@/lib/content/types'
 import { generateSearchEmbedding } from '@/lib/embeddings'
-import { getSearchIndex } from '@/lib/search/precomputed'
-import type { SearchResult } from '@/lib/search/types'
+import { getSearchIndex, getSearchPage } from '@/lib/search/precomputed'
+import type { SearchPage, SearchResult } from '@/lib/search/types'
 import { normalizeSearchText } from '@/lib/search/utils'
 import { DOCS_BASE_URL } from '@/lib/urls'
 
@@ -24,22 +21,16 @@ const STOP_WORDS = new Set([
   'the',
   'to',
 ])
-const SECTION_LABELS = { docs: 'Documentation', api: 'API reference', cli: 'CLI', mcp: 'MCP' }
+const HYBRID_TIMEOUT_MS = 1000
 let hybridRequests = 0
 
-function resultFor(page: DocsPage, id: string, url: string, heading: string): SearchResult {
-  const section = SECTION_LABELS[page.section]
-  const group = findNavigationGroup(getNavigation(page.section), page.url)
+function resultFor(page: SearchPage, id: string, url: string, heading: string): SearchResult {
   return {
     id,
     type: 'page',
     url,
     content: heading || page.title,
-    breadcrumbs: [
-      section,
-      ...(group && group !== section && group !== page.title ? [group] : []),
-      page.title,
-    ],
+    breadcrumbs: [...page.breadcrumbs],
   }
 }
 
@@ -74,7 +65,7 @@ function lexicalSearch(query: string, limit: number): SearchResult[] {
     score += body.includes(phrase) ? 12 : 0
     const existing = scores.get(chunk.pageId)
     if (existing && existing.score >= score) continue
-    const page = getPage(new URL(chunk.sourceLink).pathname)
+    const page = getSearchPage(new URL(chunk.sourceLink).pathname)
     if (!page) continue
     scores.set(chunk.pageId, {
       score,
@@ -97,11 +88,48 @@ interface DatabaseResult {
   metadata: { contentHash?: string }
 }
 
-async function hybridSearch(query: string, limit: number, signal?: AbortSignal) {
+function hybridResults(lists: DatabaseResult[][], limit: number): SearchResult[] {
+  const scores = new Map<string, { score: number; result: SearchResult }>()
+  for (const list of lists) {
+    const seenPages = new Set<string>()
+    list.forEach((row, index) => {
+      let citation: URL
+      try {
+        citation = new URL(row.source_link)
+      } catch {
+        return
+      }
+      if (citation.origin !== new URL(DOCS_BASE_URL).origin) return
+      const page = getSearchPage(citation.pathname)
+      if (!page || row.metadata?.contentHash !== page.contentHash) return
+      if (citation.hash && !page.headings.includes(citation.hash.slice(1))) return
+      if (seenPages.has(page.id)) return
+      seenPages.add(page.id)
+      const existing = scores.get(page.id)
+      const score = (existing?.score ?? 0) + 1 / (60 + index + 1)
+      scores.set(page.id, {
+        score,
+        result: existing?.result ?? resultFor(page, row.chunk_id, citation.href, row.header_text),
+      })
+    })
+  }
+  return [...scores.values()]
+    .sort(
+      (left, right) => right.score - left.score || compareStrings(left.result.url, right.result.url)
+    )
+    .slice(0, limit)
+    .map(({ result }) => result)
+}
+
+async function hybridSearch(
+  query: string,
+  limit: number,
+  signal: AbortSignal,
+  onResults: (results: SearchResult[]) => void
+) {
   const { searchDatabase } = await import('@/lib/search/database')
+  if (signal.aborted) return []
   const sql = searchDatabase()
-  const embedding = await generateSearchEmbedding(query, signal).catch(() => null)
-  if (signal?.aborted) return []
   const keyword = sql<DatabaseResult[]>`
     SELECT chunk_id, source_document, source_link, header_text, metadata
     FROM docs_embeddings
@@ -109,64 +137,45 @@ async function hybridSearch(query: string, limit: number, signal?: AbortSignal)
     ORDER BY ts_rank(chunk_text_tsv, plainto_tsquery('english', ${query})) DESC, source_link
     LIMIT ${limit * 3}
   `
-  const vector = embedding
-    ? sql<DatabaseResult[]>`
+  let vector: typeof keyword | undefined
+  const sources: DatabaseResult[][] = [[], []]
+  async function collect(source: number, request: PromiseLike<DatabaseResult[]>) {
+    const rows = await request
+    if (signal.aborted) return
+    sources[source] = rows
+    onResults(hybridResults(sources, limit))
+  }
+  async function collectVector() {
+    const embedding = await generateSearchEmbedding(query, signal).catch(() => null)
+    if (!embedding || signal.aborted) return
+    vector = sql<DatabaseResult[]>`
         SELECT chunk_id, source_document, source_link, header_text, metadata
         FROM docs_embeddings
         WHERE 1 - (embedding <=> ${JSON.stringify(embedding)}::vector) >= 0.6
         ORDER BY embedding <=> ${JSON.stringify(embedding)}::vector, source_link
         LIMIT ${limit * 3}
       `
-    : undefined
+    await collect(1, vector)
+  }
   const cancel = () => {
     keyword.cancel()
     vector?.cancel()
   }
-  signal?.addEventListener('abort', cancel, { once: true })
+  signal.addEventListener('abort', cancel, { once: true })
   try {
-    const lists = await Promise.allSettled([keyword, vector ?? Promise.resolve([])])
-    const scores = new Map<string, { score: number; result: SearchResult }>()
+    const lists = await Promise.allSettled([collect(0, keyword), collectVector()])
     for (const [source, list] of lists.entries()) {
       if (list.status === 'rejected') {
-        if (!signal?.aborted)
+        if (!signal.aborted)
           logger.warn('Hybrid search query unavailable; serving remaining results', {
             source: source === 0 ? 'keyword' : 'vector',
             error: list.reason,
           })
-        continue
       }
-      const seenPages = new Set<string>()
-      list.value.forEach((row, index) => {
-        let citation: URL
-        try {
-          citation = new URL(row.source_link)
-        } catch {
-          return
-        }
-        if (citation.origin !== new URL(DOCS_BASE_URL).origin) return
-        const page = getPage(citation.pathname)
-        if (!page || row.metadata?.contentHash !== page.contentHash) return
-        if (citation.hash && !page.headings.some((heading) => `#${heading.id}` === citation.hash))
-          return
-        if (seenPages.has(page.id)) return
-        seenPages.add(page.id)
-        const existing = scores.get(page.id)
-        const score = (existing?.score ?? 0) + 1 / (60 + index + 1)
-        scores.set(page.id, {
-          score,
-          result: existing?.result ?? resultFor(page, row.chunk_id, citation.href, row.header_text),
-        })
-      })
     }
-    return [...scores.values()]
-      .sort(
-        (left, right) =>
-          right.score - left.score || compareStrings(left.result.url, right.result.url)
-      )
-      .slice(0, limit)
-      .map(({ result }) => result)
+    return hybridResults(sources, limit)
   } finally {
-    signal?.removeEventListener('abort', cancel)
+    signal.removeEventListener('abort', cancel)
   }
 }
 
@@ -182,35 +191,34 @@ export async function searchDocs(
     : 10
   if (!query) return []
   const lexical = lexicalSearch(query, limit)
-  if (!process.env.DATABASE_URL || hybridRequests >= 2 || signal?.aborted) return lexical
+  if (lexical.length || !process.env.DATABASE_URL || hybridRequests >= 2 || signal?.aborted)
+    return lexical
+  const controller = new AbortController()
+  const combined = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal
+  let partial: SearchResult[] = []
+  let onAbort: (() => void) | undefined
+  const aborted = new Promise<SearchResult[]>((resolve) => {
+    onAbort = () => resolve(partial)
+    combined.addEventListener('abort', onAbort, { once: true })
+    if (combined.aborted) onAbort()
+  })
+  const timeout = setTimeout(() => controller.abort(), HYBRID_TIMEOUT_MS)
   hybridRequests += 1
+  const pending = hybridSearch(query, limit, combined, (results) => {
+    partial = results
+  })
+    .catch((error) => {
+      if (!combined.aborted)
+        logger.warn('Hybrid search unavailable; serving local results', { error })
+      return partial
+    })
+    .finally(() => {
+      hybridRequests -= 1
+    })
   try {
-    const hybrid = await hybridSearch(query, limit, signal)
-    const results = new Map<string, { score: number; result: SearchResult }>()
-    for (const list of [lexical, hybrid]) {
-      list.forEach((result, rank) => {
-        const path = new URL(result.url).pathname
-        const existing = results.get(path)
-        const title = getPage(path)?.title
-        const exactTitle =
-          title && normalizeSearchText(title) === normalizeSearchText(query) ? 0.05 : 0
-        results.set(path, {
-          score: (existing?.score ?? exactTitle) + 1 / (60 + rank + 1),
-          result: existing?.result ?? result,
-        })
-      })
-    }
-    return [...results.values()]
-      .sort(
-        (left, right) =>
-          right.score - left.score || compareStrings(left.result.url, right.result.url)
-      )
-      .slice(0, limit)
-      .map(({ result }) => result)
-  } catch (error) {
-    if (!signal?.aborted) logger.warn('Hybrid search unavailable; serving local results', { error })
-    return lexical
+    return await Promise.race([pending, aborted])
   } finally {
-    hybridRequests -= 1
+    clearTimeout(timeout)
+    if (onAbort) combined.removeEventListener('abort', onAbort)
   }
 }
diff --git a/apps/docs/lib/search/types.ts b/apps/docs/lib/search/types.ts
index a21ca57b676..579e8d2ac11 100644
--- a/apps/docs/lib/search/types.ts
+++ b/apps/docs/lib/search/types.ts
@@ -6,6 +6,15 @@ export interface SearchResult {
   breadcrumbs: string[]
 }
 
+export interface SearchPage {
+  id: string
+  url: string
+  title: string
+  contentHash: string
+  headings: string[]
+  breadcrumbs: string[]
+}
+
 export interface SearchChunk {
   id: string
   pageId: string
diff --git a/apps/docs/lib/search/utils.ts b/apps/docs/lib/search/utils.ts
index 962dce23c8e..5c9d75a4f0b 100644
--- a/apps/docs/lib/search/utils.ts
+++ b/apps/docs/lib/search/utils.ts
@@ -7,7 +7,7 @@ export function normalizeSearchText(value: string): string {
 }
 
 /** Couples generated search data to exactly the catalog content it cites. */
-export function searchCatalogHash(pages: DocsPage[]): string {
+export function searchCatalogHash(pages: Pick<DocsPage, 'id' | 'url' | 'contentHash'>[]): string {
   const identities = pages
     .filter((page) => page.url !== '/')
     .map((page) => `${page.id}:${page.contentHash}`)
diff --git a/apps/docs/scripts/compile-content.ts b/apps/docs/scripts/compile-content.ts
index cf3601b0f61..7081d373098 100644
--- a/apps/docs/scripts/compile-content.ts
+++ b/apps/docs/scripts/compile-content.ts
@@ -14,7 +14,7 @@ import type { ContentCatalog, DocsPage, NavigationMeta } from '@/lib/content/typ
 import { writeFullMarkdown } from '@/lib/llms-build'
 import { OPENAPI_SPEC_FILES } from '@/lib/openapi-specs'
 import { DOCS_REDIRECTS } from '@/lib/redirects'
-import { buildSearchIndex } from '@/lib/search/build'
+import { buildSearchCatalog, buildSearchIndex } from '@/lib/search/build'
 
 const logger = createLogger('DocsContent')
 const DOCS_ROOT = path.resolve(import.meta.dirname, '..')
@@ -399,6 +399,7 @@ async function generate() {
     ['routes.json', JSON.stringify(pages.map((page) => page.url))],
     ['cache.json', JSON.stringify(cache)],
     ['search.json', searchIndex],
+    ['search-catalog.json', JSON.stringify(buildSearchCatalog(catalog))],
     ['catalog.json', serialized],
   ]) {
     await writeFile(path.join(OUTPUT_ROOT, `${name}.tmp`), data)
diff --git a/apps/docs/scripts/test-generators-e2e.ts b/apps/docs/scripts/test-generators-e2e.ts
index e0226d27b6b..1a37b326d20 100644
--- a/apps/docs/scripts/test-generators-e2e.ts
+++ b/apps/docs/scripts/test-generators-e2e.ts
@@ -57,7 +57,14 @@ async function runGenerator(command: string, logName: string) {
 
 async function contentArtifacts() {
   const artifacts: Record<string, string> = {}
-  for (const file of ['catalog.json', 'search.json', 'routes.json', 'registry.ts', 'cache.json'])
+  for (const file of [
+    'catalog.json',
+    'search.json',
+    'search-catalog.json',
+    'routes.json',
+    'registry.ts',
+    'cache.json',
+  ])
     artifacts[file] = hash(await readFile(resolve(root, 'apps/docs/.content', file), 'utf8'))
   artifacts.fullMarkdown = hash(
     await readFile(resolve(root, 'apps/docs/public/llms-full.txt'), 'utf8')
diff --git a/apps/docs/scripts/test-navigation-e2e.ts b/apps/docs/scripts/test-navigation-e2e.ts
index 81b193b4060..a00722580ad 100644
--- a/apps/docs/scripts/test-navigation-e2e.ts
+++ b/apps/docs/scripts/test-navigation-e2e.ts
@@ -1681,6 +1681,25 @@ try {
         ).toBeFocused()
       }
     )
+    await check('A stalled search request stops searching and offers a retry', async () => {
+      const page = await interactive.newPage()
+      try {
+        await open(page, '/introduction')
+        await page.route('**/api/search?query=timeout-probe', () => {})
+        await page
+          .getByRole('button', { name: /^(Search documentation|Search docs)$/, exact: true })
+          .click()
+        await page.getByRole('combobox', { name: 'Search documentation' }).fill('timeout-probe')
+        await page
+          .getByRole('button', { name: 'Try again', exact: true })
+          .waitFor({ timeout: 7000 })
+        await expect(page.getByRole('status')).toContainText('Search is unavailable')
+        await page.screenshot({ path: join(directory, 'search-timeout-retry.png') })
+      } finally {
+        await page.unrouteAll({ behavior: 'ignoreErrors' })
+        await page.close()
+      }
+    })
     await check('Closing search aborts a pending request', async () => {
       const page = await interactive.newPage()
       try {
diff --git a/apps/docs/scripts/test-search-postgres-e2e.ts b/apps/docs/scripts/test-search-postgres-e2e.ts
index f1a5c86f2ef..e8dd190edc6 100644
--- a/apps/docs/scripts/test-search-postgres-e2e.ts
+++ b/apps/docs/scripts/test-search-postgres-e2e.ts
@@ -2,9 +2,11 @@ import assert from 'node:assert/strict'
 import { spawn } from 'node:child_process'
 import { createHash } from 'node:crypto'
 import { mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { connect, createServer, type Socket } from 'node:net'
 import { dirname, join, resolve } from 'node:path'
 import { createLogger } from '@sim/logger'
 import { getErrorMessage } from '@sim/utils/errors'
+import { sleep } from '@sim/utils/helpers'
 import { generateId } from '@sim/utils/id'
 import { type Server, serve } from 'bun'
 import { toString as markdownToString } from 'mdast-util-to-string'
@@ -50,6 +52,7 @@ const results: Array<{
 }> = []
 const vector = JSON.stringify([1, ...Array.from({ length: 1535 }, () => 0)])
 let created = false
+let searchProxy: Awaited<ReturnType<typeof createSearchProxy>> | undefined
 const preloadPath = join(directory, 'embedding-transport.mjs')
 type ProviderScenario =
   | 'success'
@@ -87,6 +90,73 @@ async function check(name: string, action: () => Promise<void>) {
   }
 }
 
+async function createSearchProxy() {
+  const sockets = new Set<Socket>()
+  const buffered = new Map<Socket, Buffer[]>()
+  let paused = false
+  const server = createServer((client) => {
+    const upstream = connect(Number(databaseUrl.port || 5432), databaseUrl.hostname)
+    sockets.add(client)
+    sockets.add(upstream)
+    assert(sockets.size <= 16, 'Search proxy connection cap exceeded')
+    client.on('error', () => upstream.destroy())
+    upstream.on('error', () => client.destroy())
+    client.on('close', () => {
+      sockets.delete(client)
+      upstream.destroy()
+    })
+    upstream.on('close', () => {
+      sockets.delete(upstream)
+      buffered.delete(client)
+      client.destroy()
+    })
+    client.pipe(upstream)
+    upstream.on('data', (data: Buffer) => {
+      if (!paused) {
+        client.write(data)
+        return
+      }
+      const chunks = buffered.get(client) ?? []
+      assert(
+        chunks.reduce((bytes, chunk) => bytes + chunk.length, 0) + data.length <= 1024 * 1024,
+        'Search proxy byte cap exceeded'
+      )
+      chunks.push(data)
+      buffered.set(client, chunks)
+    })
+  })
+  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve))
+  const address = server.address()
+  assert(address && typeof address !== 'string')
+  const url = new URL(databaseUrl)
+  url.hostname = '127.0.0.1'
+  url.port = String(address.port)
+  return {
+    url: url.href,
+    pause() {
+      paused = true
+    },
+    resume() {
+      paused = false
+      for (const [client, chunks] of buffered) for (const chunk of chunks) client.write(chunk)
+      buffered.clear()
+    },
+    async close() {
+      for (const socket of sockets) socket.destroy()
+      await new Promise<void>((resolve) => server.close(() => resolve()))
+    },
+  }
+}
+
+async function within<T>(operation: Promise<T>, milliseconds: number): Promise<T> {
+  return Promise.race([
+    operation,
+    sleep(milliseconds).then(() => {
+      throw new Error('Search exceeded its response budget')
+    }),
+  ])
+}
+
 async function index(
   mode: 'check' | 'publish',
   name: string,
@@ -255,6 +325,9 @@ async function verifyDatabase() {
     Array<{ count: number }>
   >`SELECT count(*)::int AS count FROM information_schema.tables WHERE table_schema = 'public'`
   assert(existing?.count === 0, 'Refusing to mutate a database that already contains tables')
+  const proxy = await createSearchProxy()
+  searchProxy = proxy
+  process.env.DATABASE_URL = proxy.url
   await sql`CREATE EXTENSION IF NOT EXISTS vector`
   await sql`
     CREATE TABLE docs_embeddings (
@@ -296,6 +369,62 @@ async function verifyDatabase() {
     assert.equal(results[0]?.id, probe)
     assert.equal(results[0]?.url, 'https://docs.sim.ai/introduction')
   })
+  await check('Local search matches do not wait for database traffic', async () => {
+    proxy.pause()
+    const pending = searchDocs('Slack')
+    try {
+      const results = await within(pending, 500)
+      assert(results.some((result) => new URL(result.url).pathname === '/integrations/slack'))
+    } finally {
+      proxy.resume()
+      await pending
+    }
+  })
+  await check(
+    'Hybrid deadlines keep stalled requests bounded and recover after the network resumes',
+    async () => {
+      proxy.pause()
+      try {
+        assert.deepEqual(await within(searchDocs(query), 2000), [])
+        assert.deepEqual(await within(searchDocs(query), 2000), [])
+        assert.deepEqual(await within(searchDocs(query), 500), [])
+      } finally {
+        proxy.resume()
+        await searchDatabase()`SELECT 1`
+      }
+      assert.equal((await searchDocs(query))[0]?.id, probe)
+    }
+  )
+  await check('Database keywords survive a stalled embedding provider', async () => {
+    const transport = globalThis.fetch
+    let requests = 0
+    const delayedProvider = serve({
+      hostname: '127.0.0.1',
+      port: 0,
+      async fetch() {
+        assert(++requests <= 1, 'Search embedding request cap exceeded')
+        await sleep(3000)
+        return Response.json({ data: [{ embedding: JSON.parse(vector) }] })
+      },
+    })
+    globalThis.fetch = Object.assign(
+      (...[input, init]: Parameters<typeof fetch>) =>
+        transport(
+          input === 'https://api.openai.com/v1/embeddings' ? delayedProvider.url : input,
+          init
+        ),
+      transport
+    )
+    process.env.OPENAI_API_KEY = 'isolated-fixture'
+    try {
+      assert.equal((await within(searchDocs(query), 2000))[0]?.id, probe)
+      assert.equal(requests, 1)
+    } finally {
+      globalThis.fetch = transport
+      process.env.OPENAI_API_KEY = ''
+      await delayedProvider.stop(true)
+    }
+  })
   await check('Repeated lower-ranked chunks do not outrank a stronger page match', async () => {
     const otherPage = getPage('/getting-started')
     assert(otherPage)
@@ -341,18 +470,18 @@ async function verifyDatabase() {
       await sql`UPDATE docs_embeddings SET source_link = 'https://docs.sim.ai/introduction' WHERE chunk_id = ${probe}`
     }
   )
-  await check('Database query failures retain credential-free catalog results', async () => {
-    await sql`ALTER TABLE docs_embeddings RENAME TO docs_embeddings_unavailable`
-    try {
-      assert(
-        (await searchDocs('Slack')).some(
-          (result) => new URL(result.url).pathname === '/integrations/slack'
-        )
-      )
-    } finally {
-      await sql`ALTER TABLE docs_embeddings_unavailable RENAME TO docs_embeddings`
+  await check(
+    'Database query failures return no matches and recover after restoration',
+    async () => {
+      await sql`ALTER TABLE docs_embeddings RENAME TO docs_embeddings_unavailable`
+      try {
+        assert.deepEqual(await searchDocs(query), [])
+      } finally {
+        await sql`ALTER TABLE docs_embeddings_unavailable RENAME TO docs_embeddings`
+      }
+      assert.equal((await searchDocs(query))[0]?.id, probe)
     }
-  })
+  )
   await sql`DELETE FROM docs_embeddings`
   const pages = getPages().filter((page) => page.url !== '/')
   for (const page of pages) {
@@ -684,10 +813,12 @@ try {
     })
   }
 } finally {
+  searchProxy?.resume()
   await provider?.stop(true)
   await rm(preloadPath, { force: true })
   if (created) await sql`DROP TABLE docs_embeddings`
   await Promise.all([sql.end({ timeout: 5 }), searchDatabase().end({ timeout: 5 })])
+  await searchProxy?.close()
   await writeFile(
     reportPath,
     `${JSON.stringify({ scope: chunksOnly ? 'compiled-content' : 'postgres-publication', results, provider: { mode: 'loopback-http-fixture', maxRequests: 16, maxInputsPerRequest: 16, requests: providerRequests } }, null, 2)}\n`

From 1acb187a45bd99b71688da4a9cdecadeb421fe24 Mon Sep 17 00:00:00 2001
From: Waleed Latif <walif6@gmail.com>
Date: Sat, 7 Nov 2026 13:46:29 -0800
Subject: [PATCH 2/2] fix(docs): strengthen search cancellation and IPv6 checks

---
 apps/docs/scripts/test-navigation-e2e.ts      |  6 +++---
 apps/docs/scripts/test-search-postgres-e2e.ts | 15 ++++++++-------
 2 files changed, 11 insertions(+), 10 deletions(-)

diff --git a/apps/docs/scripts/test-navigation-e2e.ts b/apps/docs/scripts/test-navigation-e2e.ts
index a00722580ad..e6842fb0036 100644
--- a/apps/docs/scripts/test-navigation-e2e.ts
+++ b/apps/docs/scripts/test-navigation-e2e.ts
@@ -1711,12 +1711,12 @@ try {
         const requested = page.waitForRequest((request) =>
           request.url().includes('query=cancel-request')
         )
+        await page.getByRole('combobox', { name: 'Search documentation' }).fill('cancel-request')
+        await requested
         const failed = page.waitForEvent('requestfailed', {
           predicate: (request) => request.url().includes('query=cancel-request'),
-          timeout: 10000,
+          timeout: 2000,
         })
-        await page.getByRole('combobox', { name: 'Search documentation' }).fill('cancel-request')
-        await requested
         await page.keyboard.press('Escape')
         expect((await failed).failure()?.errorText).toMatch(/abort|cancel/i)
         await expect(page.getByRole('dialog')).toHaveCount(0)
diff --git a/apps/docs/scripts/test-search-postgres-e2e.ts b/apps/docs/scripts/test-search-postgres-e2e.ts
index e8dd190edc6..14f22a638c4 100644
--- a/apps/docs/scripts/test-search-postgres-e2e.ts
+++ b/apps/docs/scripts/test-search-postgres-e2e.ts
@@ -43,7 +43,10 @@ process.env.OPENAI_API_KEY = ''
 const reportPath: string = reportSetting
 const directory = dirname(reportPath)
 const workspace = resolve(import.meta.dirname, '..')
-const sql = postgres(databaseUrl.href, { max: 1 })
+const databaseHost = databaseUrl.hostname.replace(/^\[|\]$/g, '')
+await mkdir(directory, { recursive: true })
+const searchProxy = chunksOnly ? undefined : await createSearchProxy()
+const sql = postgres(searchProxy?.url ?? databaseUrl.href, { max: 1 })
 const results: Array<{
   name: string
   status: 'passed' | 'failed'
@@ -52,7 +55,6 @@ const results: Array<{
 }> = []
 const vector = JSON.stringify([1, ...Array.from({ length: 1535 }, () => 0)])
 let created = false
-let searchProxy: Awaited<ReturnType<typeof createSearchProxy>> | undefined
 const preloadPath = join(directory, 'embedding-transport.mjs')
 type ProviderScenario =
   | 'success'
@@ -72,7 +74,6 @@ const providerRequests: Array<{
   status: number
   inputs: number
 }> = []
-await mkdir(directory, { recursive: true })
 
 async function check(name: string, action: () => Promise<void>) {
   const started = performance.now()
@@ -95,7 +96,7 @@ async function createSearchProxy() {
   const buffered = new Map<Socket, Buffer[]>()
   let paused = false
   const server = createServer((client) => {
-    const upstream = connect(Number(databaseUrl.port || 5432), databaseUrl.hostname)
+    const upstream = connect(Number(databaseUrl.port || 5432), databaseHost)
     sockets.add(client)
     sockets.add(upstream)
     assert(sockets.size <= 16, 'Search proxy connection cap exceeded')
@@ -177,7 +178,7 @@ async function index(
       cwd: workspace,
       env: {
         ...process.env,
-        DATABASE_URL: databaseUrl.href,
+        DATABASE_URL: searchProxy?.url ?? databaseUrl.href,
         OPENAI_API_KEY: useProvider ? 'isolated-fixture' : '',
         DOCS_SEARCH_REPORT_PATH: outputPath,
       },
@@ -325,8 +326,8 @@ async function verifyDatabase() {
     Array<{ count: number }>
   >`SELECT count(*)::int AS count FROM information_schema.tables WHERE table_schema = 'public'`
   assert(existing?.count === 0, 'Refusing to mutate a database that already contains tables')
-  const proxy = await createSearchProxy()
-  searchProxy = proxy
+  const proxy = searchProxy
+  assert(proxy, 'Search proxy fixture is required for database verification')
   process.env.DATABASE_URL = proxy.url
   await sql`CREATE EXTENSION IF NOT EXISTS vector`
   await sql`