@uniweb/kit 0.9.42 → 0.9.44

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/kit",
-  "version": "0.9.42",
+  "version": "0.9.44",
   "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.32",
+    "@uniweb/core": "0.7.33",
     "@uniweb/scene": "0.1.2"
   },
   "peerDependencies": {

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

@@ -22,8 +22,12 @@ import { emptyResult } from './result.js'
 const indexCache = new Map()
 const fuseCache = new Map()
 
-const STORAGE_VERSION = 'v1'
-const STORAGE_PREFIX = `uniweb:search:${STORAGE_VERSION}:`
+// Bumped to v2 when stored entries gained a validator. The version is part of
+// the key, so every v1 entry — which had no way to be revalidated and could
+// outlive any number of rebuilds — is orphaned rather than trusted.
+const STORAGE_VERSION = 'v2'
+const STORAGE_PREFIX = 'uniweb:search:'
+const STORAGE_KEY = (cacheKey) => `${STORAGE_PREFIX}${STORAGE_VERSION}:${cacheKey}`
 
 /**
  * Default Fuse.js options optimized for site search
@@ -37,10 +41,43 @@ const DEFAULT_FUSE_OPTIONS = {
   ],
   threshold: 0.35,
   includeMatches: true,
+  // Exposed so ranking is inspectable, and so a foundation that wants its own
+  // ordering has something to order by. Fuse omits `score` entirely without it,
+  // which is why nothing could be ranked on relevance before.
+  includeScore: true,
   ignoreLocation: true,
   minMatchCharLength: 2
 }
 
+/**
+ * Does this entry literally contain every word of the query?
+ *
+ * Fuse is approximate by design, and on fields the size of a whole page that
+ * turns into a real problem: searching "inset" on a documentation site
+ * returned 68 hits of which 4 contained the word, and all four ranked below
+ * the tenth result — so every result the reader saw was a near-miss on a page
+ * that never mentions the term.
+ *
+ * Fuzzy is the right FALLBACK — it is what tolerates a typo — but it must not
+ * outrank an exact match. Checking containment directly is the cheap, honest
+ * signal Fuse's score does not provide here.
+ *
+ * Every token must appear, so "Inset Components" does not match a page that
+ * merely says "components". Matching is substring-based rather than
+ * word-boundary so that "inset" still finds "insets".
+ */
+function literalTier(item, tokens) {
+  if (!tokens.length) return 2
+
+  const title = `${item.title || ''} ${item.pageTitle || ''}`.toLowerCase()
+  if (tokens.every((t) => title.includes(t))) return 0
+
+  const body = `${title} ${item.content || ''} ${item.excerpt || ''}`.toLowerCase()
+  if (tokens.every((t) => body.includes(t))) return 1
+
+  return 2
+}
+
 /**
  * Get localStorage safely (handles SSR and access errors)
  * @returns {Storage|null}
@@ -63,14 +100,12 @@ function loadFromStorage(cacheKey) {
   const storage = getStorage()
   if (!storage) return null
 
-  const raw = storage.getItem(`${STORAGE_PREFIX}${cacheKey}`)
+  const raw = storage.getItem(STORAGE_KEY(cacheKey))
   if (!raw) return null
 
   try {
     const parsed = JSON.parse(raw)
-    if (Array.isArray(parsed.entries)) {
-      return parsed
-    }
+    if (Array.isArray(parsed.payload?.entries)) return parsed
     return null
   } catch {
     return null
@@ -78,21 +113,52 @@ function loadFromStorage(cacheKey) {
 }
 
 /**
- * Save index to localStorage
+ * Save index to localStorage, together with the validator that lets a later
+ * load ask the server whether it is still current.
+ *
  * @param {string} cacheKey - Cache key
  * @param {Object} payload - Index data
+ * @param {{etag?: string|null, lastModified?: string|null}} [validator]
  */
-function saveToStorage(cacheKey, payload) {
+function saveToStorage(cacheKey, payload, validator = {}) {
   const storage = getStorage()
   if (!storage) return
 
   try {
-    storage.setItem(`${STORAGE_PREFIX}${cacheKey}`, JSON.stringify(payload))
+    storage.setItem(
+      STORAGE_KEY(cacheKey),
+      JSON.stringify({
+        payload,
+        etag: validator.etag || null,
+        lastModified: validator.lastModified || null,
+      })
+    )
   } catch {
     // Ignore quota errors
   }
 }
 
+/**
+ * Drop entries written by an older storage schema.
+ *
+ * A search index runs to hundreds of kilobytes, so an orphaned one is a real
+ * bite out of a origin's storage quota rather than a tidiness issue.
+ */
+function pruneOldVersions() {
+  const storage = getStorage()
+  if (!storage) return
+
+  const current = `${STORAGE_PREFIX}${STORAGE_VERSION}:`
+  const stale = []
+  for (let i = 0; i < storage.length; i++) {
+    const key = storage.key(i)
+    if (key?.startsWith(STORAGE_PREFIX) && !key.startsWith(current)) stale.push(key)
+  }
+  stale.forEach((key) => {
+    try { storage.removeItem(key) } catch { /* ignore */ }
+  })
+}
+
 /**
  * Load search index for a locale
  * @param {string} indexUrl - URL to fetch the index from
@@ -104,32 +170,72 @@ function saveToStorage(cacheKey, payload) {
 export async function loadSearchIndex(indexUrl, options = {}) {
   const { cacheKey = indexUrl, useStorage = true } = options
 
-  // Check memory cache first
+  // Memory cache: scoped to one page load, where the index cannot change
+  // underneath us. This is the only cache read that needs no validation.
   if (indexCache.has(cacheKey)) {
     return indexCache.get(cacheKey)
   }
 
-  // Check localStorage cache
-  if (useStorage) {
-    const cached = loadFromStorage(cacheKey)
+  if (useStorage) pruneOldVersions()
+  const cached = useStorage ? loadFromStorage(cacheKey) : null
+
+  // ALWAYS ask the server, even holding a stored copy.
+  //
+  // Returning the stored index unconditionally — what this did before — has no
+  // expiry and no way to notice a rebuild, so a visitor who searched once kept
+  // answering from that index for as long as the entry survived. A redeploy
+  // did not dislodge it.
+  //
+  // It also collided across sites. The key is the index URL, which is
+  // `/search-index.json` for every Uniweb project, and localStorage is scoped
+  // to an origin — so two projects sharing a dev port shared one entry, and a
+  // search on one could return the other's pages. Revalidating settles that
+  // too: a different server answers 200 with its own index and replaces it.
+  const headers = {}
+  if (cached?.etag) headers['If-None-Match'] = cached.etag
+  else if (cached?.lastModified) headers['If-Modified-Since'] = cached.lastModified
+
+  let response
+  try {
+    // `no-cache` = revalidate, not "don't cache". `force-cache` (the previous
+    // value) told the browser to prefer any stored response regardless of age,
+    // which defeated revalidation a second time over.
+    response = await fetch(indexUrl, { headers, cache: 'no-cache' })
+  } catch (error) {
+    // Offline or unreachable. A stored index is better than no search at all,
+    // and this is the one path where serving it unvalidated is the right call.
     if (cached) {
-      indexCache.set(cacheKey, cached)
-      return cached
+      indexCache.set(cacheKey, cached.payload)
+      return cached.payload
     }
+    throw error
+  }
+
+  // Unchanged since we stored it — the whole point of keeping the validator.
+  if (response.status === 304 && cached) {
+    indexCache.set(cacheKey, cached.payload)
+    return cached.payload
   }
 
-  // Fetch from server
-  const response = await fetch(indexUrl, { cache: 'force-cache' })
   if (!response.ok) {
+    if (cached) {
+      indexCache.set(cacheKey, cached.payload)
+      return cached.payload
+    }
     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)
+    // A host that sends no validator still gets stored — it just costs a full
+    // fetch next time instead of a 304. What it never does is get served as
+    // though it were known to be current.
+    saveToStorage(cacheKey, payload, {
+      etag: response.headers?.get?.('etag'),
+      lastModified: response.headers?.get?.('last-modified'),
+    })
   }
 
   return payload
@@ -145,7 +251,7 @@ export function clearSearchCache(cacheKey) {
     fuseCache.delete(cacheKey)
     const storage = getStorage()
     if (storage) {
-      storage.removeItem(`${STORAGE_PREFIX}${cacheKey}`)
+      storage.removeItem(STORAGE_KEY(cacheKey))
     }
   } else {
     indexCache.clear()
@@ -219,6 +325,23 @@ export function createIndexProvider(website, options = {}) {
         results = results.filter(({ item }) => item.route?.startsWith(route))
       }
 
+      // Rank pages that actually contain the words above Fuse's near-misses.
+      //
+      // Fuse sorts by its own score, which on page-sized content fields rates
+      // an approximate match as highly as an exact one — so a page containing
+      // the search term could sit below ten pages that never mention it, and
+      // the reader concludes the site has nothing on the subject.
+      //
+      // A stable sort by tier keeps Fuse's ordering *within* each tier, so
+      // relevance still decides among equals and the fuzzy tail is preserved
+      // rather than discarded. Applied before `limit`, because the cutoff is
+      // exactly where the problem showed up.
+      const tokens = String(text || '').toLowerCase().split(/\s+/).filter(Boolean)
+      results = results
+        .map((r, i) => ({ r, i, tier: literalTier(r.item, tokens) }))
+        .sort((a, b) => a.tier - b.tier || a.i - b.i)
+        .map(({ r }) => r)
+
       return results.slice(0, limit).map(({ item, matches }) => {
         const snippet = buildSnippet(item.content, matches, { key: 'content' })