feat(search): client side fts

app/app.config.ts

@@ -185,7 +185,7 @@ export default defineAppConfig({
       // info: 'i-tabler-info-square-rounded-filled',
     },
   },
-  // `seo.siteName`, `header.title` and `github.*` are deliberately NOT defaulted here: modules/config.ts seeds
+  // `seo.siteName`, `header.title` and `github.*` are deliberately NOT defaulted here: modules/config/ seeds
   // them into `nuxt.options.appConfig`, and app.config values — even empty strings — would win over those.
   header: {
     to: '/',

app/app.vue

@@ -1,6 +1,5 @@
 <script setup lang="ts">
 import type { NavigationItem } from 'comark-content'
-import type { SearchSection } from './utils/search-sections'
 import { useRoute } from 'vue-router'
 
 const { seo, docs } = useAppConfig()
@@ -11,17 +10,6 @@ const route = useRoute()
 const { data: navigation } = await useAsyncData('navigation', () => content.value.client.navigation(), {
   watch: [() => content.value.base],
 })
-const {
-  data: files,
-  status,
-  execute: loadSearchSections,
-} = useLazyAsyncData('search-sections', () => content.value.client.searchSections(), {
-  server: false,
-  watch: [() => content.value.base],
-  immediate: false,
-})
-
-onNuxtReady(() => loadSearchSections())
 
 const nuxtApp = useNuxtApp()
 const navTree = computed<NavigationItem[]>(() => prefixNavigation(navigation.value ?? [], content.value.base))
@@ -31,12 +19,6 @@ onNuxtReady(() => {
     navigationLayout.value = findNavigationLayout(navTree.value, route.path)
   })
 })
-const searchFiles = computed<SearchSection[]>(() =>
-  (files.value ?? []).map((section) => {
-    const [path, hash] = section.id.split('#')
-    return { ...section, id: prefixLink(path!, content.value.base) + (hash ? `#${hash}` : '') }
-  })
-)
 
 useHead({
   meta: [{ name: 'viewport', content: 'width=device-width, initial-scale=1' }],
@@ -107,14 +89,9 @@ defineShortcuts({
 
     <AppFooter />
 
+    <AppSearch :navigation="navTree" />
+
     <ClientOnly>
-      <LazyUContentSearch
-        :files="searchFiles"
-        :navigation="navTree"
-        :transition="false"
-        :loading="status !== 'success'"
-        :placeholder="status !== 'success' ? 'Loading...' : undefined"
-      />
       <LazyVersionHistory />
       <LazyAssistantChat v-if="assistant?.enabled && assistantMounted" />
     </ClientOnly>

app/components/AppSearch.vue

@@ -0,0 +1,67 @@
+<script setup lang="ts">
+import type { NavigationItem } from 'comark-content'
+
+const props = defineProps<{
+  navigation: NavigationItem[]
+}>()
+
+const { search, status } = useSearch()
+
+const appConfig = useAppConfig()
+
+interface PageItem {
+  label: string
+  prefix?: string
+  suffix?: string
+  to: string
+  icon: string
+}
+
+/** Leaf pages, flattened; ancestor titles become the `Section > Page` prefix the palette renders. */
+function pageItems(items: NavigationItem[], ancestors: string[] = []): PageItem[] {
+  return items.flatMap((item) => {
+    if (item.children?.length) return pageItems(item.children, [...ancestors, item.title])
+    if (!item.path || item.page === false) return []
+    return [{
+      label: item.title,
+      prefix: ancestors.length ? `${ancestors.join(' > ')} >` : undefined,
+      suffix: item.description,
+      to: item.path,
+      icon: (item.icon as string | undefined) || appConfig.ui.icons.file,
+    }]
+  })
+}
+
+function browseOnly(query: string, items?: PageItem[]): PageItem[] {
+  return query ? [] : (items ?? [])
+}
+
+// One group per top-level section, mirroring how `UContentSearch` groups navigation when it can.
+const groups = computed(() => {
+  if (props.navigation.some((item) => item.children?.length)) {
+    return props.navigation
+      .filter((section) => section.children?.length)
+      .map((section) => ({
+        id: section.path,
+        label: section.title,
+        items: pageItems(section.children ?? []),
+        postFilter: browseOnly,
+      }))
+      .filter((group) => group.items.length > 0)
+  }
+  return [{ id: 'docs', items: pageItems(props.navigation), postFilter: browseOnly }]
+})
+</script>
+
+<template>
+  <ClientOnly>
+    <LazyUContentSearch
+      :search="search"
+      :search-status="status"
+      :navigation="navigation"
+      :groups="groups"
+      :transition="false"
+      :loading="status === 'loading'"
+    />
+  </ClientOnly>
+</template>

app/components/AssistantChat.vue

@@ -3,7 +3,7 @@ import { DefaultChatTransport, isReasoningUIPart, isTextUIPart, isToolUIPart, ge
 import { useChat } from '@ai-sdk/vue'
 import { isPartStreaming, isToolStreaming } from '@nuxt/ui/utils/ai'
 import rangi from 'comark/plugins/rangi'
-import { geistTheme } from '../../utils/geist-theme'
+import { geistTheme } from '../../utils/geist'
 
 const MAX_INPUT = 1000
 

app/components/landing/LandingHeroDemo.vue

@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import rangi from 'comark/plugins/rangi'
-import { geistTheme } from '../../../utils/geist-theme'
+import { geistTheme } from '../../../utils/geist'
 
 const props = defineProps<{
   /** Markdown source: shown highlighted in the source tab, rendered live in the output tab. */

app/composables/useDocsContent.ts

@@ -1,12 +1,10 @@
 import { createContentClient } from 'comark-content/client'
-import { searchSectionsClient } from '../utils/search-sections'
 import type { ContentMode } from '../types/content'
 import { withLeadingSlash } from 'ufo'
 
 export const prodContent = createContentClient({
   basePath: '/api/content',
   fetch: $fetch,
-  plugins: [searchSectionsClient()],
 })
 
 const clients = new Map<string, typeof prodContent>()
@@ -17,7 +15,6 @@ function getClient(basePath: string) {
     client = createContentClient({
       basePath,
       fetch: $fetch,
-      plugins: [searchSectionsClient()],
     })
     clients.set(basePath, client)
   }

app/composables/useSearch.ts

@@ -0,0 +1,61 @@
+import type { SearchOptions, SearchResult } from 'comark-content'
+
+type SearchStatus = 'idle' | 'loading' | 'ready' | 'error'
+
+const status = ref<SearchStatus>('idle')
+
+/**
+ * Hydration logging switch: `?debug=search`
+ */
+function searchDebug(): boolean {
+  if (!import.meta.client) return false
+  return new URLSearchParams(location.search).get('debug') === 'search'
+}
+
+/**
+ * Client-side full-text search over production content (sqlite-wasm FTS5) hydrated from the
+ * per-commit snapshot artifacts.
+ */
+export function useSearch() {
+  const { data: headSha } = useAsyncData(
+    'content-head-sha',
+    () => $fetch<{ sha: string | null }>('/api/content/head').then(({ sha }) => sha),
+    { default: () => null }
+  )
+
+  /**
+   * Load the database.
+   * No-op once loading or ready; retries after a failure.
+   */
+  async function warmup(): Promise<void> {
+    if (status.value === 'loading' || status.value === 'ready') return
+    status.value = 'loading'
+    try {
+      if (!headSha.value && !import.meta.dev) {
+        throw new Error('[search] /api/content/head returned no commit pin')
+      }
+
+      // Immutable per-commit artifacts, CDN-cached forever. Only unpinned in dev, per the guard above.
+      const apiBase = headSha.value ? `/api/content/blob/${headSha.value}` : '/api/content'
+
+      const debug = searchDebug()
+      if (debug) console.info(`[search] warmup from ${apiBase} (head ${headSha.value ?? 'unpinned'})`)
+
+      await warmupSearch(apiBase, location.origin, debug)
+      status.value = 'ready'
+    } catch (error) {
+      status.value = 'error'
+      console.error('[search] could not load the search database', error)
+    }
+  }
+
+  if (import.meta.client) {
+    onNuxtReady(warmup)
+  }
+
+  async function search(query: string, opts?: SearchOptions): Promise<SearchResult[]> {
+    return searchContent(query, opts)
+  }
+
+  return { search, status: readonly(status), warmup }
+}

app/error.vue

@@ -17,9 +17,6 @@ useSeoMeta({
 })
 
 const { data: navigation } = await useAsyncData('navigation', () => prodContent.navigation())
-const { data: files } = useLazyAsyncData('search-sections', () => prodContent.searchSections(), {
-  server: false,
-})
 
 provide('navigation', navigation)
 </script>
@@ -32,11 +29,6 @@ provide('navigation', navigation)
 
     <AppFooter />
 
-    <ClientOnly>
-      <LazyUContentSearch
-        :files="files ?? []"
-        :navigation="navigation ?? []"
-      />
-    </ClientOnly>
+    <AppSearch :navigation="navigation ?? []" />
   </UApp>
 </template>

app/utils/navigation.ts

@@ -23,7 +23,7 @@ function walk(items: NavigationItem[], path: string): boolean {
 }
 
 // Shared with the server-side `/raw/**` mirror (server/routes/raw/[...slug].md.get.ts).
-export { findFirstLeaf } from '../../utils/first-leaf'
+export { findFirstLeaf } from '../../utils/navigation'
 
 export interface BreadcrumbItem {
   title: string

app/workers/internal/search-logger.ts

@@ -0,0 +1,69 @@
+/**
+ * Logging for the search worker.
+ *
+ * Triggered by `?debug=search` param.
+ */
+import type { ContentFile, Logger, RelationalDatabase } from 'comark-content'
+
+const PREFIX = '[search:worker]'
+
+let debug = false
+
+/** Called on every `warmup`; once on, it stays on for the life of the worker. */
+export function setDebug(value: boolean): void {
+  debug = debug || value
+}
+
+export function isDebug(): boolean {
+  return debug
+}
+
+export function log(...args: unknown[]): void {
+  if (debug) console.info(PREFIX, ...args)
+}
+
+/** Milliseconds since `from`, for log lines. */
+export function since(from: number): string {
+  return `${(performance.now() - from).toFixed(1)}ms`
+}
+
+/**
+ * Warn and error are deliberately ungated: the FTS plugin reports a missing snapshot through this
+ * channel, and that failure is otherwise indistinguishable from "the query matched nothing".
+ */
+export const logger: Logger = {
+  debug: (tag, ...args) => log(`${tag}:`, ...args),
+  info: (tag, ...args) => log(`${tag}:`, ...args),
+  warn: (tag, ...args) => console.warn(`${PREFIX} ${tag}:`, ...args),
+  error: (tag, ...args) => console.error(`${PREFIX} ${tag}:`, ...args),
+}
+
+/**
+ * What a decoded artifact holds: a snapshot decodes to the source's items, the manifest to an object
+ * keyed by path. `with nodes` is the number that matters — the FTS plugin indexes
+ * `kind === 'document' && nodes?.length`, so a bodies-less (partial) snapshot builds an empty index.
+ */
+export function describeArtifact(decoded: unknown): string {
+  if (Array.isArray(decoded)) {
+    const items = decoded as ContentFile[]
+    const documents = items.filter((item) => item.meta.kind === 'document')
+    const withNodes = documents.filter((item) => item.nodes?.length)
+    return `${items.length} item(s), ${documents.length} document(s), ${withNodes.length} with nodes`
+  }
+  const items = (decoded as { items?: Record<string, unknown> } | null)?.items
+  return `${items ? Object.keys(items).length : 0} manifest item(s)`
+}
+
+/**
+ * Rows in the FTS plugin's index — the one number that separates "nothing was indexed" from "the
+ * query found nothing", since `search()` catches SQL errors and returns `[]` either way. Reads the
+ * plugin's private table, so it is a diagnostic, not something to build on.
+ */
+export async function indexedRows(database: RelationalDatabase, source: string): Promise<number | string> {
+  try {
+    const rows = await database.all<{ n: number }>('SELECT count(*) as n FROM __fts_search WHERE source = ?', [source])
+    return rows?.[0]?.n ?? 'unknown'
+  } catch (error) {
+    return `unknown (${error instanceof Error ? error.message : String(error)})`
+  }
+}