@uniweb/kit 0.9.37 → 0.9.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/kit",
-  "version": "0.9.37",
+  "version": "0.9.39",
   "description": "Standard component library for Uniweb foundations",
   "type": "module",
   "exports": {
@@ -40,7 +40,7 @@
     "fuse.js": "^7.0.0",
     "shiki": "^3.0.0",
     "tailwind-merge": "^3.6.0",
-    "@uniweb/core": "0.7.29",
+    "@uniweb/core": "0.7.31",
     "@uniweb/scene": "0.1.2"
   },
   "peerDependencies": {

package/src/index.js

@@ -132,6 +132,6 @@ export { Scene } from './styled/Scene/index.jsx'
 // Search
 // ============================================================================
 
-export { createSearchClient, loadSearchIndex, clearSearchCache } from './search/client.js'
+export { createSearchClient, loadSearchIndex, clearSearchCache, emptyResult } from './search/client.js'
 export { buildSnippet, highlightMatches, escapeHtml } from './search/snippets.js'
 export { useSearch, useSearchIndex, useSearchShortcut, useSearchWithIntent } from './search/hooks.js'

package/src/search/client.js

@@ -1,157 +1,70 @@
 /**
  * Search Client
  *
- * Manages search index loading, caching, and querying using Fuse.js.
- */
-
-import { buildSnippet } from './snippets.js'
-
-// Storage versioning for cache invalidation
-const STORAGE_VERSION = 'v1'
-const STORAGE_PREFIX = `uniweb:search:${STORAGE_VERSION}:`
-
-// In-memory caches
-const indexCache = new Map()
-const fuseCache = new Map()
-
-/**
- * Default Fuse.js options optimized for site search
- */
-const DEFAULT_FUSE_OPTIONS = {
-  keys: [
-    { name: 'title', weight: 0.6 },
-    { name: 'content', weight: 0.4 },
-    { name: 'excerpt', weight: 0.3 },
-    { name: 'pageTitle', weight: 0.2 }
-  ],
-  threshold: 0.35,
-  includeMatches: true,
-  ignoreLocation: true,
-  minMatchCharLength: 2
-}
-
-/**
- * Get localStorage safely (handles SSR and access errors)
- * @returns {Storage|null}
- */
-function getStorage() {
-  if (typeof window === 'undefined') return null
-  try {
-    return window.localStorage
-  } catch {
-    return null
-  }
-}
-
-/**
- * Load index from localStorage
- * @param {string} cacheKey - Cache key
- * @returns {Object|null}
+ * Resolves which provider serves a site's search, then delegates to it. The
+ * site declares the provider; a component reads results the same way either
+ * way — the same contract `content.data` gives data fetching, applied to search.
+ *
+ * Providers are loaded dynamically, so a site using a server endpoint never
+ * bundles Fuse and a site using the local index never bundles anything else.
+ *
+ * Resolution order:
+ *   1. `site.yml  search.provider`  — the author's explicit choice
+ *   2. `'index'`                    — the free default, works on any host
+ *
+ * A future tier sits between them: a host that serves search declaring it in
+ * the payload it already sends, the way `config.base` already tells the runtime
+ * where the site is being served from. That wire key is the host's to specify,
+ * so it is deliberately not invented here.
+ *
+ * Provider contract (duck-typed, matching how the FetcherDispatcher treats
+ * transports):
+ *
+ *   { query(text, opts) → Promise<SearchResult[]>,
+ *     preload?() → Promise<void>,
+ *     clearCache?() → void }
+ *
+ * See ./providers/result.js for the result contract.
  */
-function loadFromStorage(cacheKey) {
-  const storage = getStorage()
-  if (!storage) return null
 
-  const raw = storage.getItem(`${STORAGE_PREFIX}${cacheKey}`)
-  if (!raw) return null
+import { emptyResult } from './providers/result.js'
 
-  try {
-    const parsed = JSON.parse(raw)
-    if (Array.isArray(parsed.entries)) {
-      return parsed
-    }
-    return null
-  } catch {
-    return null
-  }
-}
+// Re-exported so existing importers of these keep working; they live with the
+// provider that owns them now.
+export { loadSearchIndex, clearSearchCache } from './providers/index-provider.js'
 
 /**
- * Save index to localStorage
- * @param {string} cacheKey - Cache key
- * @param {Object} payload - Index data
- */
-function saveToStorage(cacheKey, payload) {
-  const storage = getStorage()
-  if (!storage) return
-
-  try {
-    storage.setItem(`${STORAGE_PREFIX}${cacheKey}`, JSON.stringify(payload))
-  } catch {
-    // Ignore quota errors
-  }
-}
-
-/**
- * Load search index for a locale
- * @param {string} indexUrl - URL to fetch the index from
- * @param {Object} options - Options
- * @param {string} [options.cacheKey] - Cache key (defaults to indexUrl)
- * @param {boolean} [options.useStorage=true] - Use localStorage caching
- * @returns {Promise<Object>} Search index
+ * Load a provider factory by name.
+ *
+ * Unknown names resolve to `null` rather than throwing, so a typo or a
+ * foundation transport that failed to register degrades to the default instead
+ * of taking down the site's search box — the same resilience the fetcher
+ * dispatcher applies to a malformed transport.
+ *
+ * @param {string} name
+ * @param {Object} transports - Foundation-supplied search transports
+ * @returns {Promise<Function|null>}
  */
-export async function loadSearchIndex(indexUrl, options = {}) {
-  const { cacheKey = indexUrl, useStorage = true } = options
-
-  // Check memory cache first
-  if (indexCache.has(cacheKey)) {
-    return indexCache.get(cacheKey)
+async function loadProviderFactory(name, transports) {
+  if (name === 'index') {
+    const mod = await import('./providers/index-provider.js')
+    return mod.createIndexProvider
   }
-
-  // Check localStorage cache
-  if (useStorage) {
-    const cached = loadFromStorage(cacheKey)
-    if (cached) {
-      indexCache.set(cacheKey, cached)
-      return cached
-    }
-  }
-
-  // Fetch from server
-  const response = await fetch(indexUrl, { cache: 'force-cache' })
-  if (!response.ok) {
-    throw new Error(`Failed to load search index: ${response.status}`)
+  if (name === 'endpoint') {
+    const mod = await import('./providers/endpoint-provider.js')
+    return mod.createEndpointProvider
   }
 
-  const payload = await response.json()
-
-  // Cache the result
-  indexCache.set(cacheKey, payload)
-  if (useStorage) {
-    saveToStorage(cacheKey, payload)
+  const transport = transports?.[name]
+  if (transport && typeof transport.query === 'function') {
+    return () => transport
   }
-
-  return payload
-}
-
-/**
- * Clear all search caches
- * @param {string} [cacheKey] - Specific cache key to clear, or all if omitted
- */
-export function clearSearchCache(cacheKey) {
-  if (cacheKey) {
-    indexCache.delete(cacheKey)
-    fuseCache.delete(cacheKey)
-    const storage = getStorage()
-    if (storage) {
-      storage.removeItem(`${STORAGE_PREFIX}${cacheKey}`)
-    }
-  } else {
-    indexCache.clear()
-    fuseCache.clear()
-    const storage = getStorage()
-    if (storage) {
-      // Clear all search-related storage
-      const keysToRemove = []
-      for (let i = 0; i < storage.length; i++) {
-        const key = storage.key(i)
-        if (key?.startsWith(STORAGE_PREFIX)) {
-          keysToRemove.push(key)
-        }
-      }
-      keysToRemove.forEach(key => storage.removeItem(key))
-    }
+  if (transport) {
+    console.warn(
+      `[uniweb] Search transport "${name}" has no query(); falling back to the index provider.`
+    )
   }
+  return null
 }
 
 /**
@@ -159,9 +72,11 @@ export function clearSearchCache(cacheKey) {
  *
  * @param {Object} website - Website instance from @uniweb/core
  * @param {Object} options - Configuration options
- * @param {Object} [options.fuseOptions] - Custom Fuse.js options
- * @param {boolean} [options.useStorage=true] - Use localStorage caching
+ * @param {Object} [options.fuseOptions] - Custom Fuse.js options (index provider)
+ * @param {boolean} [options.useStorage=true] - Use localStorage caching (index provider)
  * @param {number} [options.defaultLimit=10] - Default result limit
+ * @param {string} [options.provider] - Override the declared provider
+ * @param {Object} [options.transports] - Named search transports from a foundation
  * @returns {Object} Search client with query method
  *
  * @example
@@ -170,45 +85,66 @@ export function clearSearchCache(cacheKey) {
  */
 export function createSearchClient(website, options = {}) {
   const {
-    fuseOptions = {},
-    useStorage = true,
-    defaultLimit = 10
+    defaultLimit = 10,
+    provider: providerOverride,
+    transports,
+    ...providerOptions
   } = options
 
-  const mergedFuseOptions = { ...DEFAULT_FUSE_OPTIONS, ...fuseOptions }
+  const searchConfig = website.getSearchConfig?.() || {}
+  const declared = providerOverride || searchConfig.provider || 'index'
 
-  /**
-   * Get or create Fuse instance for the current locale
-   * @returns {Promise<Fuse>}
-   */
-  async function getFuse() {
-    const indexUrl = website.getSearchIndexUrl()
-    const cacheKey = indexUrl
+  // One in-flight resolution shared by every caller.
+  let providerPromise = null
+  let activeName = declared
 
-    // Check Fuse cache
-    if (fuseCache.has(cacheKey)) {
-      return fuseCache.get(cacheKey)
-    }
+  async function getProvider() {
+    if (providerPromise) return providerPromise
 
-    // Load index and create Fuse instance
-    const index = await loadSearchIndex(indexUrl, { cacheKey, useStorage })
+    providerPromise = (async () => {
+      let factory = await loadProviderFactory(declared, transports)
 
-    // Dynamically import Fuse.js (peer dependency)
-    let Fuse
-    try {
-      const fuseMod = await import('fuse.js')
-      Fuse = fuseMod.default || fuseMod
-    } catch (err) {
-      throw new Error(
-        'Fuse.js is required for search functionality. ' +
-        'Install it with: npm install fuse.js'
-      )
-    }
+      if (!factory) {
+        if (declared !== 'index') {
+          console.warn(
+            `[uniweb] Unknown search provider "${declared}"; falling back to the index provider.`
+          )
+        }
+        const mod = await import('./providers/index-provider.js')
+        factory = mod.createIndexProvider
+        activeName = 'index'
+      }
+
+      return factory(website, { ...providerOptions, endpoint: searchConfig.endpoint })
+    })()
 
-    const fuse = new Fuse(index.entries || [], mergedFuseOptions)
-    fuseCache.set(cacheKey, fuse)
+    return providerPromise
+  }
 
-    return fuse
+  /**
+   * Fall back to the local index when a non-index provider fails.
+   *
+   * A site that moves off a host serving search still has an index emitted at
+   * build, so this is usually a working answer rather than a consolation prize.
+   * Standalone-first means the degraded path is part of the design.
+   *
+   * @param {Error} err
+   * @returns {Promise<Object|null>}
+   */
+  async function fallbackToIndex(err) {
+    if (activeName === 'index') return null
+    console.warn(
+      `[uniweb] Search provider "${activeName}" failed (${err?.message}); trying the local index.`
+    )
+    try {
+      const mod = await import('./providers/index-provider.js')
+      const fallback = mod.createIndexProvider(website, providerOptions)
+      activeName = 'index'
+      providerPromise = Promise.resolve(fallback)
+      return fallback
+    } catch {
+      return null
+    }
   }
 
   return {
@@ -220,6 +156,15 @@ export function createSearchClient(website, options = {}) {
       return website.isSearchEnabled()
     },
 
+    /**
+     * Name of the provider serving results. Reflects the active provider, so
+     * after a fallback it reports `index` rather than what was declared.
+     * @returns {string}
+     */
+    getProviderName() {
+      return activeName
+    },
+
     /**
      * Get the search index URL
      * @returns {string}
@@ -244,10 +189,11 @@ export function createSearchClient(website, options = {}) {
      * @param {number} [queryOptions.limit] - Maximum results
      * @param {string} [queryOptions.type] - Filter by type ('page' or 'section')
      * @param {string} [queryOptions.route] - Filter by route prefix
+     * @param {AbortSignal} [queryOptions.signal] - Cancel an in-flight query
      * @returns {Promise<Array>} Search results
      */
     async query(query, queryOptions = {}) {
-      const { limit = defaultLimit, type, route } = queryOptions
+      const { limit = defaultLimit, type, route, signal } = queryOptions
 
       const trimmed = query?.trim()
       if (!trimmed) return []
@@ -257,69 +203,54 @@ export function createSearchClient(website, options = {}) {
         return []
       }
 
-      const fuse = await getFuse()
-      let results = fuse.search(trimmed)
+      const opts = { limit, type, route, signal }
 
-      // Apply type filter
-      if (type) {
-        results = results.filter(({ item }) => item.type === type)
-      }
+      try {
+        const provider = await getProvider()
+        return await provider.query(trimmed, opts)
+      } catch (err) {
+        // An aborted query is a caller decision, not a provider failure.
+        if (err?.name === 'AbortError') throw err
 
-      // Apply route filter
-      if (route) {
-        results = results.filter(({ item }) => item.route?.startsWith(route))
-      }
-
-      // Apply limit
-      const limited = results.slice(0, limit)
-
-      // Transform results
-      return limited.map(({ item, matches }) => {
-        const snippet = buildSnippet(item.content, matches, { key: 'content' })
-
-        return {
-          // Identity
-          id: item.id,
-          type: item.type,
-
-          // Navigation
-          route: item.route,
-          sectionId: item.sectionId,
-          anchor: item.anchor,
-          href: item.anchor ? `${item.route}#${item.anchor}` : item.route,
-
-          // Display
-          title: item.title,
-          pageTitle: item.pageTitle,
-          description: item.description,
-          excerpt: item.excerpt,
-          component: item.component,
-
-          // Search result specific
-          snippetText: snippet.text,
-          snippetHtml: snippet.html,
-          matches
+        const fallback = await fallbackToIndex(err)
+        if (!fallback) {
+          console.warn(`[uniweb] Search failed: ${err?.message}`)
+          return []
+        }
+        try {
+          return await fallback.query(trimmed, opts)
+        } catch (fallbackErr) {
+          console.warn(`[uniweb] Search fallback failed: ${fallbackErr?.message}`)
+          return []
         }
-      })
+      }
     },
 
     /**
-     * Preload the search index (call this to warm the cache)
+     * Preload whatever the provider needs to answer quickly.
+     * A no-op for providers with nothing to warm.
      * @returns {Promise<void>}
      */
     async preload() {
       if (!website.isSearchEnabled()) return
-      await getFuse()
+      try {
+        const provider = await getProvider()
+        await provider.preload?.()
+      } catch (err) {
+        // Preloading is an optimization; failing it must not surface to a user.
+        console.warn(`[uniweb] Search preload failed: ${err?.message}`)
+      }
     },
 
     /**
-     * Clear the search cache
+     * Clear the provider's cache, if it keeps one.
      */
     clearCache() {
-      const indexUrl = website.getSearchIndexUrl()
-      clearSearchCache(indexUrl)
+      if (!providerPromise) return
+      providerPromise.then(p => p.clearCache?.()).catch(() => {})
     }
   }
 }
 
+export { emptyResult }
 export default createSearchClient

package/src/search/index.js

@@ -21,6 +21,7 @@
  * })
  */
 
-export { createSearchClient, loadSearchIndex, clearSearchCache } from './client.js'
+export { createSearchClient, loadSearchIndex, clearSearchCache, emptyResult } from './client.js'
+export { resolveEndpointUrl } from './providers/endpoint-provider.js'
 export { buildSnippet, highlightMatches, escapeHtml } from './snippets.js'
 export { useSearch, useSearchIndex, useSearchShortcut, useSearchWithIntent } from './hooks.js'

package/src/search/providers/endpoint-provider.js

@@ -0,0 +1,149 @@
+/**
+ * The `endpoint` search provider — ask a server.
+ *
+ * What this buys over a downloaded index is not better matching; it is *when
+ * the index can be built*. A local index contains what existed at build time,
+ * so records that arrive from an API afterwards can never be in it. A server
+ * can index them, and can be told to re-index without the site being rebuilt.
+ *
+ * Nothing here is specific to any host. The endpoint is a declared path and the
+ * response envelope is sniffed, so this works against a self-hosted search API
+ * as readily as against a managed one. A backend whose shape is genuinely
+ * different wants a foundation-supplied transport, which is the open end of the
+ * seam — the same escalation `fetcher:` offers.
+ */
+
+import { emptyResult } from './result.js'
+
+/** Path used when a site declares `provider: endpoint` without an `endpoint:`. */
+const DEFAULT_ENDPOINT = '_search'
+
+/**
+ * Resolve the endpoint against the site's base path.
+ *
+ * This is the whole reason the endpoint is declared base-RELATIVE. One spelling
+ * — `_search` — has to work when the site is served from the root, from a
+ * subdirectory (`base: /docs/`), and from a backend subpath. It mirrors how the
+ * runtime's default fetcher resolves its base rather than assuming the origin
+ * root, and it is what lets a backend expose search as a subroute of the path
+ * it already serves the site from, with no framework change.
+ *
+ * An absolute URL is passed through untouched, for a search service on another
+ * origin.
+ *
+ * @param {string} endpoint - Declared endpoint (relative or absolute)
+ * @param {string} basePath - `website.basePath`, normalized without a trailing slash
+ * @returns {string}
+ */
+export function resolveEndpointUrl(endpoint, basePath = '') {
+  const path = endpoint || DEFAULT_ENDPOINT
+  if (/^https?:\/\//i.test(path)) return path
+
+  const base = (basePath || '').replace(/\/+$/, '')
+  const rel = path.replace(/^\/+/, '')
+  return `${base}/${rel}`
+}
+
+/**
+ * Pull the result array out of a response envelope.
+ *
+ * Deliberately tolerant: `results` is our own shape, `hits` and `items` are the
+ * two next most common spellings, and a bare array covers the rest. Anything
+ * further afield is a transport's job, not a guessing game here.
+ *
+ * @param {*} payload
+ * @returns {Object[]}
+ */
+function extractResults(payload) {
+  if (Array.isArray(payload)) return payload
+  if (Array.isArray(payload?.results)) return payload.results
+  if (Array.isArray(payload?.hits)) return payload.hits
+  if (Array.isArray(payload?.items)) return payload.items
+  return []
+}
+
+/**
+ * Normalize one server result into the shared contract.
+ *
+ * @param {Object} raw
+ * @returns {Object}
+ */
+function normalize(raw) {
+  const route = raw?.route ?? ''
+  const anchor = raw?.anchor ?? null
+
+  return {
+    ...emptyResult(),
+    id: raw?.id ?? '',
+    type: raw?.type ?? '',
+    route,
+    // Prefer a server-built href; fall back to composing one, so a backend that
+    // returns only route + anchor still yields a working link.
+    href: raw?.href ?? (anchor ? `${route}#${anchor}` : route),
+    title: raw?.title ?? '',
+    pageTitle: raw?.pageTitle ?? '',
+    excerpt: raw?.excerpt ?? '',
+    snippetHtml: raw?.snippetHtml ?? '',
+    sectionId: raw?.sectionId ?? null,
+    anchor,
+    description: raw?.description ?? null,
+    component: raw?.component ?? null,
+    snippetText: raw?.snippetText ?? null,
+    matches: raw?.matches ?? null,
+    collection: raw?.collection ?? null,
+    item: raw?.item ?? null
+  }
+}
+
+/**
+ * Create an `endpoint` provider bound to a Website.
+ *
+ * @param {Object} website - Website instance from @uniweb/core
+ * @param {Object} [options]
+ * @param {string} [options.endpoint] - Base-relative path or absolute URL
+ * @returns {{query: Function, preload: Function, clearCache: Function}}
+ */
+export function createEndpointProvider(website, options = {}) {
+  const { endpoint } = options
+
+  return {
+    async query(text, { limit = 10, type, route, signal } = {}) {
+      const url = new URL(
+        resolveEndpointUrl(endpoint, website.basePath),
+        // A base is required to parse a relative path; in a non-browser context
+        // (tests, SSR) there is no location, so use a placeholder we strip below.
+        typeof window !== 'undefined' ? window.location.origin : 'http://localhost'
+      )
+
+      url.searchParams.set('q', text)
+      url.searchParams.set('lang', website.getActiveLocale())
+      url.searchParams.set('limit', String(limit))
+
+      const response = await fetch(url.toString(), {
+        signal,
+        headers: { Accept: 'application/json' }
+      })
+
+      if (!response.ok) {
+        throw new Error(`Search endpoint returned ${response.status}`)
+      }
+
+      const results = extractResults(await response.json()).map(normalize)
+
+      // Filters are applied client-side because they are not part of the wire
+      // contract a third-party endpoint is expected to honor. A server that
+      // does support them narrows the set first; re-applying is a no-op.
+      let filtered = results
+      if (type) filtered = filtered.filter(r => r.type === type)
+      if (route) filtered = filtered.filter(r => r.route?.startsWith(route))
+
+      return filtered.slice(0, limit)
+    },
+
+    // Nothing to warm: there is no index to download. Defined so every provider
+    // answers the same calls.
+    async preload() {},
+
+    clearCache() {}
+  }
+}

package/src/search/providers/index-provider.js

@@ -0,0 +1,253 @@
+/**
+ * The `index` search provider — download a prebuilt index, query it locally.
+ *
+ * The free path, and the default. Works on any host, including a plain static
+ * one with no server at all, which is why it stays the fallback for every other
+ * provider (see `resolveProvider` in ../client.js).
+ *
+ * Its limit is structural rather than a quality gap: the index is built from
+ * what existed at build time, so content that arrives from an API afterwards
+ * cannot be in it. Fuzzy matching is the thing it does *better* than a server
+ * scorer — Fuse tolerates typos.
+ *
+ * Fuse is imported dynamically so a site using a different provider never
+ * bundles it.
+ */
+
+import { buildSnippet } from '../snippets.js'
+import { emptyResult } from './result.js'
+
+// In-memory caches, keyed by index URL. Module-scope is correct here: this
+// only ever runs in one browser tab, unlike the edge's per-PoP isolates.
+const indexCache = new Map()
+const fuseCache = new Map()
+
+const STORAGE_VERSION = 'v1'
+const STORAGE_PREFIX = `uniweb:search:${STORAGE_VERSION}:`
+
+/**
+ * Default Fuse.js options optimized for site search
+ */
+const DEFAULT_FUSE_OPTIONS = {
+  keys: [
+    { name: 'title', weight: 0.6 },
+    { name: 'content', weight: 0.4 },
+    { name: 'excerpt', weight: 0.3 },
+    { name: 'pageTitle', weight: 0.2 }
+  ],
+  threshold: 0.35,
+  includeMatches: true,
+  ignoreLocation: true,
+  minMatchCharLength: 2
+}
+
+/**
+ * Get localStorage safely (handles SSR and access errors)
+ * @returns {Storage|null}
+ */
+function getStorage() {
+  if (typeof window === 'undefined') return null
+  try {
+    return window.localStorage
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Load index from localStorage
+ * @param {string} cacheKey - Cache key
+ * @returns {Object|null}
+ */
+function loadFromStorage(cacheKey) {
+  const storage = getStorage()
+  if (!storage) return null
+
+  const raw = storage.getItem(`${STORAGE_PREFIX}${cacheKey}`)
+  if (!raw) return null
+
+  try {
+    const parsed = JSON.parse(raw)
+    if (Array.isArray(parsed.entries)) {
+      return parsed
+    }
+    return null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Save index to localStorage
+ * @param {string} cacheKey - Cache key
+ * @param {Object} payload - Index data
+ */
+function saveToStorage(cacheKey, payload) {
+  const storage = getStorage()
+  if (!storage) return
+
+  try {
+    storage.setItem(`${STORAGE_PREFIX}${cacheKey}`, JSON.stringify(payload))
+  } catch {
+    // Ignore quota errors
+  }
+}
+
+/**
+ * Load search index for a locale
+ * @param {string} indexUrl - URL to fetch the index from
+ * @param {Object} options - Options
+ * @param {string} [options.cacheKey] - Cache key (defaults to indexUrl)
+ * @param {boolean} [options.useStorage=true] - Use localStorage caching
+ * @returns {Promise<Object>} Search index
+ */
+export async function loadSearchIndex(indexUrl, options = {}) {
+  const { cacheKey = indexUrl, useStorage = true } = options
+
+  // Check memory cache first
+  if (indexCache.has(cacheKey)) {
+    return indexCache.get(cacheKey)
+  }
+
+  // Check localStorage cache
+  if (useStorage) {
+    const cached = loadFromStorage(cacheKey)
+    if (cached) {
+      indexCache.set(cacheKey, cached)
+      return cached
+    }
+  }
+
+  // Fetch from server
+  const response = await fetch(indexUrl, { cache: 'force-cache' })
+  if (!response.ok) {
+    throw new Error(`Failed to load search index: ${response.status}`)
+  }
+
+  const payload = await response.json()
+
+  // Cache the result
+  indexCache.set(cacheKey, payload)
+  if (useStorage) {
+    saveToStorage(cacheKey, payload)
+  }
+
+  return payload
+}
+
+/**
+ * Clear all search caches
+ * @param {string} [cacheKey] - Specific cache key to clear, or all if omitted
+ */
+export function clearSearchCache(cacheKey) {
+  if (cacheKey) {
+    indexCache.delete(cacheKey)
+    fuseCache.delete(cacheKey)
+    const storage = getStorage()
+    if (storage) {
+      storage.removeItem(`${STORAGE_PREFIX}${cacheKey}`)
+    }
+  } else {
+    indexCache.clear()
+    fuseCache.clear()
+    const storage = getStorage()
+    if (storage) {
+      // Clear all search-related storage
+      const keysToRemove = []
+      for (let i = 0; i < storage.length; i++) {
+        const key = storage.key(i)
+        if (key?.startsWith(STORAGE_PREFIX)) {
+          keysToRemove.push(key)
+        }
+      }
+      keysToRemove.forEach(key => storage.removeItem(key))
+    }
+  }
+}
+
+/**
+ * Create an `index` provider bound to a Website.
+ *
+ * @param {Object} website - Website instance from @uniweb/core
+ * @param {Object} [options]
+ * @param {Object} [options.fuseOptions] - Custom Fuse.js options
+ * @param {boolean} [options.useStorage=true] - Use localStorage caching
+ * @returns {{query: Function, preload: Function, clearCache: Function}}
+ */
+export function createIndexProvider(website, options = {}) {
+  const { fuseOptions = {}, useStorage = true } = options
+  const mergedFuseOptions = { ...DEFAULT_FUSE_OPTIONS, ...fuseOptions }
+
+  async function getFuse() {
+    // Read the URL per call rather than closing over it: the active locale can
+    // change without the client being rebuilt, and each locale has its own index.
+    const indexUrl = website.getSearchIndexUrl()
+    const cacheKey = indexUrl
+
+    if (fuseCache.has(cacheKey)) {
+      return fuseCache.get(cacheKey)
+    }
+
+    const index = await loadSearchIndex(indexUrl, { cacheKey, useStorage })
+
+    let Fuse
+    try {
+      const fuseMod = await import('fuse.js')
+      Fuse = fuseMod.default || fuseMod
+    } catch {
+      throw new Error(
+        'Fuse.js is required for the `index` search provider. ' +
+        'Install it with: npm install fuse.js'
+      )
+    }
+
+    const fuse = new Fuse(index.entries || [], mergedFuseOptions)
+    fuseCache.set(cacheKey, fuse)
+
+    return fuse
+  }
+
+  return {
+    async query(text, { limit = 10, type, route } = {}) {
+      const fuse = await getFuse()
+      let results = fuse.search(text)
+
+      if (type) {
+        results = results.filter(({ item }) => item.type === type)
+      }
+      if (route) {
+        results = results.filter(({ item }) => item.route?.startsWith(route))
+      }
+
+      return results.slice(0, limit).map(({ item, matches }) => {
+        const snippet = buildSnippet(item.content, matches, { key: 'content' })
+
+        return {
+          ...emptyResult(),
+          id: item.id,
+          type: item.type,
+          route: item.route,
+          sectionId: item.sectionId ?? null,
+          anchor: item.anchor ?? null,
+          href: item.anchor ? `${item.route}#${item.anchor}` : item.route,
+          title: item.title ?? '',
+          pageTitle: item.pageTitle ?? '',
+          description: item.description ?? null,
+          excerpt: item.excerpt ?? '',
+          component: item.component ?? null,
+          snippetText: snippet.text,
+          snippetHtml: snippet.html,
+          matches
+        }
+      })
+    },
+
+    async preload() {
+      await getFuse()
+    },
+
+    clearCache() {
+      clearSearchCache(website.getSearchIndexUrl())
+    }
+  }
+}

package/src/search/providers/result.js

@@ -0,0 +1,64 @@
+/**
+ * The search result contract.
+ *
+ * Every provider returns objects of this shape. The point is that a foundation's
+ * search UI is written once and works against any provider — the same reason
+ * `prepare-props` guarantees a content shape so components need no null checks.
+ *
+ * Two tiers, and the distinction is load-bearing:
+ *
+ * - **Guaranteed** — `id`, `type`, `route`, `href`, `title`, `pageTitle`,
+ *   `excerpt`, `snippetHtml`. Every provider fills these. A component may
+ *   render them unconditionally.
+ * - **Provider-optional** — everything else. Present when the provider can
+ *   supply it, `null` when it cannot. A component that renders one must
+ *   tolerate `null`, because whether it arrives is a *deployment* fact, not a
+ *   content fact: the same site yields `item` on a server-backed provider and
+ *   `null` on a static one.
+ *
+ * Concretely today: a local index can produce `matches` / `snippetText` (Fuse
+ * reports match ranges) but knows nothing about API-backed collection records;
+ * a server endpoint is the reverse. Neither is a subset of the other, which is
+ * why the contract is a union with a guaranteed core rather than a
+ * lowest-common-denominator.
+ *
+ * `snippetHtml` is HTML containing `<mark>` elements. Render it through kit's
+ * `SafeHtml`, never as text.
+ */
+
+/**
+ * A result with every optional field nulled and every guaranteed field at its
+ * empty value. Spread this first so a provider filling a subset still returns
+ * the full shape, and adding a field later cannot silently produce `undefined`
+ * at one provider and a value at another.
+ *
+ * @returns {Object}
+ */
+export function emptyResult() {
+  return {
+    // ── Guaranteed ──────────────────────────────────────────────
+    id: '',
+    type: '',
+    route: '',
+    href: '',
+    title: '',
+    pageTitle: '',
+    excerpt: '',
+    snippetHtml: '',
+
+    // ── Provider-optional ───────────────────────────────────────
+    // Deep-linking within a page.
+    sectionId: null,
+    anchor: null,
+    // Extra display material.
+    description: null,
+    component: null,
+    // Plain-text twin of snippetHtml, for non-HTML surfaces.
+    snippetText: null,
+    // Match ranges, when the provider scores locally and can report them.
+    matches: null,
+    // Collection provenance, when the hit is a record rather than a page.
+    collection: null,
+    item: null
+  }
+}

package/src/styled/Prose/index.jsx

@@ -170,6 +170,32 @@ function SequenceElement({ element, block }) {
       )
     }
 
+    case 'inset_block': {
+      // A component reference that carries block content — the block form of
+      // an inset. Children recurse; flattening them to text is what the
+      // sequence's default branch used to do, and it lost the body.
+      //
+      // Reaching this case means the container was NOT lifted — `@uniweb/core`
+      // rewrites `inset_block` to `inset_placeholder` when it builds the render
+      // graph, and the `inset` case resolves that against the foundation. This
+      // is the fallback for a document rendered without a Block behind it.
+      //
+      // kit does NOT map the name to one of its own components — see the longer
+      // note in Section/Render. A visible generic box; never a drop.
+      const body = element.children?.map((el, i) => (
+        <SequenceElement key={i} element={el} block={block} />
+      ))
+
+      return (
+        <div
+          data-inset-block={element.component || 'unknown'}
+          className="border border-border rounded-md p-4 my-4"
+        >
+          {body}
+        </div>
+      )
+    }
+
     case 'link': {
       const { href, label, role } = element.attrs || {}
       // Standalone links promoted from paragraphs

package/src/styled/Section/Render.jsx

@@ -225,6 +225,43 @@ function RenderNode({ node, block, ...props }) {
       )
     }
 
+    case 'inset_block': {
+      // The block form of an inset: a fenced `@Component{params}` container
+      // whose body is real block content, recursed like a blockquote's rather
+      // than flattened to a string.
+      //
+      // NOTE: a container reaching this case means it was NOT lifted.
+      // `@uniweb/core`'s Block rewrites every `inset_block` to an
+      // `inset_placeholder` when it builds the render graph, so the normal
+      // path is the `inset_placeholder` case below — which resolves the
+      // component against the FOUNDATION. This branch is what is left for a
+      // document rendered without a Block behind it.
+      //
+      // `@Component` names foundation vocabulary, so kit must not answer for
+      // it. kit's own Details and Alert are not reachable through
+      // `getInset()` and must not become reachable here, or a foundation
+      // shipping its own Alert would be shadowed by ours. (kit still renders
+      // `details` / `alert` above — those are the editor's DOCUMENT node
+      // types, a different mechanism that happens to share a name.)
+      //
+      // So: no name dispatch. A VISIBLE generic box that keeps its body.
+      // Never a drop — an unmapped node taking its subtree with it is the
+      // failure this container exists to fix.
+      const component = attrs?.component
+      const body = content?.map((child, i) => (
+        <RenderNode key={i} node={child} block={block} />
+      ))
+
+      return (
+        <div
+          data-inset-block={component || 'unknown'}
+          className="border border-border rounded-md p-4 my-4"
+        >
+          {body}
+        </div>
+      )
+    }
+
     case 'horizontalRule':
     case 'divider': {
       return <Divider type={attrs?.type} className="my-6" />