@grimoire-rs/indexer 0.5.2 → 0.5.3

package/dist/renderer/astro/layouts/Base.astro

@@ -62,16 +62,18 @@ const { title, description, image = config.logo ?? config.favicon } = Astro.prop
 
       // Also before first paint: a deep link (a keyword chip on a package
       // page) or a stored preference means the catalog the server rendered —
-      // every package, empty search box, name order, deprecated hidden — is
-      // the wrong one. Flag it so CSS holds the catalog back rather than
-      // showing the full list and rearranging it a moment later. The island
-      // drops the flag once it has applied the view — which is the render
-      // after hydration, never the hydrating one itself; the timeout is the
-      // failsafe for an island that never hydrates, where a flash beats a
-      // blank page.
+      // every package, empty search box, name order, deprecated hidden, as
+      // cards — is the wrong one. Flag it so CSS holds the catalog back
+      // rather than showing the full list and rearranging it a moment
+      // later. The island drops the flag once it has applied the view —
+      // which is the render after hydration, never the hydrating one
+      // itself; the timeout is the failsafe for an island that never
+      // hydrates, where a flash beats a blank page.
       const view = new URLSearchParams(location.search);
-      const arranged = ["sort", "dir", "deprecated"].some((k) => pref("grim.catalog." + k));
-      if (view.get("q") || view.get("kind") || arranged) {
+      const arranged = ["sort", "dir", "deprecated", "view"].some((k) =>
+        pref("grim.catalog." + k),
+      );
+      if (view.get("q") || view.get("kind") || view.get("kw") || arranged) {
         document.documentElement.dataset.query = "";
         setTimeout(() => delete document.documentElement.dataset.query, 3000);
       }
@@ -853,12 +855,12 @@ const { title, description, image = config.logo ?? config.favicon } = Astro.prop
            that is not yet in use, so it withdraws the moment the field is
            focused or holds a query — at which point it would only be
            sitting on top of what is being typed. */
-        .search-hint {
+        .search-hint,
+        .search-clear {
           position: absolute;
           right: 0.5rem;
           top: 50%;
           translate: 0 -50%;
-          pointer-events: none;
           border: var(--grim-border-width) solid var(--grim-color-border);
           border-bottom-width: 2px;
           border-radius: var(--grim-radius-inset);
@@ -869,10 +871,33 @@ const { title, description, image = config.logo ?? config.favicon } = Astro.prop
           line-height: 1;
           padding: var(--grim-space-2) var(--grim-space-3);
         }
+        .search-hint {
+          pointer-events: none;
+        }
+        /* The two never coexist — the hint withdraws exactly when a query
+           appears, which is when the clear button is rendered — so they share
+           one corner rather than sitting beside each other. */
         .search-field:focus-within .search-hint,
         .search-field:has(input:not(:placeholder-shown)) .search-hint {
           display: none;
         }
+        /* Sized to the glyph rather than to a text line, so the box matches
+           the hint's height instead of growing around an SVG on a baseline. */
+        .search-clear {
+          display: grid;
+          place-items: center;
+          cursor: pointer;
+        }
+        .search-clear:hover {
+          color: var(--grim-color-fg);
+        }
+        /* The UA's own clear button, gone: it renders in this same corner in
+           Chromium and Safari, in a style that answers to no token here, and
+           it cannot be restyled beyond hiding. Ours replaces it. */
+        .controls input[type="search"]::-webkit-search-cancel-button {
+          appearance: none;
+          display: none;
+        }
         /* One line, always. Wrapping was the defect: at a narrow width the
            row dropped `deprecated` onto a second line, because no chip can
            shrink below its own longest word and the rail's chip count is a
@@ -1240,6 +1265,18 @@ const { title, description, image = config.logo ?? config.favicon } = Astro.prop
           outline-offset: 0;
           border-color: var(--grim-color-accent);
         }
+        /* The sort combo, while a POINTER is driving it. Chromium hands a
+           `<select>` `:focus-visible` on an ordinary click, so this control
+           alone would wear the keyboard ring for a mouse interaction — around
+           a closed box sitting behind its own open dropdown, which already
+           says everything the ring would. `data-pointer` is set by the
+           element's own `pointerdown` and cleared by a keypress or a blur, so
+           the ring is only ever suppressed for the interaction that did not
+           need it; every keyboard focus keeps it. */
+        .sort-field[data-pointer]:focus-visible {
+          outline: none;
+          border-color: var(--grim-color-accent);
+        }
 
         .grid {
           list-style: none;
@@ -1504,13 +1541,20 @@ const { title, description, image = config.logo ?? config.favicon } = Astro.prop
            the container rather than cutting square across it. */
         .table {
           display: grid;
-          /* logo | kind | name | description | updated. The two fixed-width
-             marks lead, so the names start on one line down the whole list
-             and the eye runs the column it actually reads. The name is
-             capped rather than `max-content`: an unbounded name ate the
-             description's space, and past the cap both clip instead. The
-             description is the only track that grows. */
-          grid-template-columns: auto auto minmax(8rem, 14rem) 1fr auto;
+          /* logo | kind | name | description | updated. The two marks lead,
+             so the names start on one line down the whole list and the eye
+             runs the column it actually reads.
+
+             Every track is sized to give the description whatever is left.
+             The marks are `min-content` — a 20px tile and a 16px glyph, and
+             nothing about them should reserve more than they draw. The name
+             is `fit-content(14rem)`: as wide as the longest name in the list
+             and no wider, capped, past which it clips. It was
+             `minmax(8rem, 14rem)`, and that 8rem floor was a hole — a list of
+             short names paid a fixed 8rem for them, so the description read
+             as pushed away from a column of empty space. */
+          grid-template-columns:
+            min-content min-content fit-content(14rem) 1fr auto;
           background: var(--grim-color-card);
           border: var(--grim-border-width) solid var(--grim-color-border);
           /* `xl`, the content-surface step — the same one the card wears.
@@ -1524,20 +1568,45 @@ const { title, description, image = config.logo ?? config.favicon } = Astro.prop
         /* One more track when the index publishes ratings. Decided once per
            index, never per filter — see `PackageTable`. */
         .table.rated {
-          grid-template-columns: auto auto minmax(8rem, 14rem) 1fr auto auto;
+          grid-template-columns:
+            min-content min-content fit-content(14rem) 1fr auto auto;
         }
         .table .row {
           grid-column: 1 / -1;
           display: grid;
           grid-template-columns: subgrid;
           align-items: center;
-          gap: var(--grim-space-5);
+          /* One step tighter than the row's own padding. A 12px gutter either
+             side of a 16px glyph reads as a hole rather than as spacing. */
+          gap: var(--grim-space-4);
           padding: var(--grim-space-3) var(--grim-space-5);
           color: inherit;
           text-decoration: none;
           font-size: var(--grim-text-sm);
           transition: background-color var(--grim-duration-base) ease;
         }
+        /* NO `content-visibility` on a row, and the reason is load-bearing.
+           `content-visibility: auto` applies SIZE CONTAINMENT, and a
+           size-contained element cannot be a subgrid — the `subgrid` above
+           degrades to `none`, silently. Measured in Chromium 152 against a
+           real build: with it, `getComputedStyle(row).gridTemplateColumns`
+           reads `none` and every cell is one sixth of the table (181px each
+           at a 1280px viewport); without it the parent's tracks apply and the
+           description gets the 832px the `1fr` exists to give it.
+
+           It shipped in 2a77c15 as a paint bound, and the check made at the
+           time — first and last rows' cells at identical offsets, before and
+           after scrolling — could not have caught this: when EVERY row is the
+           same independently-computed grid, the offsets match perfectly and
+           the alignment is fake. Any check here must read the row's own
+           `gridTemplateColumns`, or a cell's width against its content, never
+           two rows against each other. `style_contract.test.ts` holds the
+           text form of the invariant.
+
+           What that commit bought is not lost. The logo fetches it was aimed
+           at are held off by `loading="lazy"` on the image itself, and the
+           list's real cost — building every row — is bounded by the window in
+           `Catalog.tsx`, which is that same commit's other half. */
         /* The rule belongs between rows, not under the last one — which the
            container's own border already draws. */
         .table .row + .row {
@@ -1683,10 +1752,11 @@ const { title, description, image = config.logo ?? config.favicon } = Astro.prop
         @media (max-width: 40rem) {
           .table,
           .table.rated {
-            grid-template-columns: auto auto minmax(6rem, 1fr) auto;
+            grid-template-columns: min-content min-content minmax(6rem, 1fr) auto;
           }
           .table.rated {
-            grid-template-columns: auto auto minmax(6rem, 1fr) auto auto;
+            grid-template-columns:
+              min-content min-content minmax(6rem, 1fr) auto auto;
           }
           .t-desc {
             display: none;

package/dist/renderer/astro/lib/catalog.d.ts

@@ -1,5 +1,35 @@
 import type { CatalogPackage } from "../../types.js";
 export type { CatalogPackage } from "../../types.js";
+/**
+ * The fields the CATALOG ISLAND may read — and, because the island's props
+ * are serialized into the page, the only fields that are worth shipping.
+ *
+ * `index.astro` projects every package through `cardPackage()` before handing
+ * the array to `<Catalog>`. Astro serializes island props into an HTML
+ * attribute on `<astro-island>`, so anything left in a record is paid for
+ * twice on the landing page: once in the server-rendered card markup, and
+ * again as escaped JSON the browser parses at hydration. At a corporate-sized
+ * catalog the untrimmed record set was 323 KB of that attribute, ~18% of the
+ * page, most of it fields no card or row ever looks at — `license`,
+ * `authors`, `vendor`, `documentation`, `compatibility`, `revision`,
+ * `support`, `repository`, and every unknown enrichment key riding
+ * `IndexRecord`'s index signature.
+ *
+ * This is a TYPE, not just a filter, and that is the point: a component that
+ * reaches for a field not listed here fails to compile, rather than silently
+ * rendering `undefined` in the browser while the server render — which reads
+ * the full record — looks correct. The detail pages are unaffected; they read
+ * `data` directly and hydrate nothing.
+ */
+export type CardPackage = Pick<CatalogPackage, "name" | "kind" | "ref" | "namespace" | "description" | "summary" | "version" | "keywords" | "created" | "updated" | "deprecated" | "replacedBy" | "logo" | "rating">;
+/**
+ * One package, trimmed to what the island renders.
+ *
+ * An absent key is omitted rather than set to `undefined`: `JSON.stringify`
+ * drops an undefined value anyway, and omitting it keeps the projection's
+ * output identical to what a hand-written object literal would produce.
+ */
+export declare function cardPackage(p: CatalogPackage): CardPackage;
 /**
  * When a package last moved, for sorting and for the "updated" stamp.
  *
@@ -9,7 +39,7 @@ export type { CatalogPackage } from "../../types.js";
  * existed: those records still date correctly instead of dropping into the
  * unknown bucket on the first build after an upgrade.
  */
-export declare function lastUpdated(p: CatalogPackage): string | undefined;
+export declare function lastUpdated(p: Pick<CatalogPackage, "updated" | "created">): string | undefined;
 /**
  * The deprecation sentence, or `null` for a package that is not deprecated.
  *

package/dist/renderer/astro/lib/catalog.js

@@ -1,5 +1,37 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright 2026 The Grimoire Authors
+/** The keys of `CardPackage`, as one list the projection actually iterates. */
+const CARD_FIELDS = [
+    "name",
+    "kind",
+    "ref",
+    "namespace",
+    "description",
+    "summary",
+    "version",
+    "keywords",
+    "created",
+    "updated",
+    "deprecated",
+    "replacedBy",
+    "logo",
+    "rating",
+];
+/**
+ * One package, trimmed to what the island renders.
+ *
+ * An absent key is omitted rather than set to `undefined`: `JSON.stringify`
+ * drops an undefined value anyway, and omitting it keeps the projection's
+ * output identical to what a hand-written object literal would produce.
+ */
+export function cardPackage(p) {
+    const out = {};
+    for (const key of CARD_FIELDS) {
+        if (p[key] !== undefined)
+            out[key] = p[key];
+    }
+    return out;
+}
 /**
  * When a package last moved, for sorting and for the "updated" stamp.
  *

package/dist/renderer/astro/lib/catalog.ts

@@ -9,6 +9,78 @@ import type { CatalogPackage } from "../../types.js";
 
 export type { CatalogPackage } from "../../types.js";
 
+/**
+ * The fields the CATALOG ISLAND may read — and, because the island's props
+ * are serialized into the page, the only fields that are worth shipping.
+ *
+ * `index.astro` projects every package through `cardPackage()` before handing
+ * the array to `<Catalog>`. Astro serializes island props into an HTML
+ * attribute on `<astro-island>`, so anything left in a record is paid for
+ * twice on the landing page: once in the server-rendered card markup, and
+ * again as escaped JSON the browser parses at hydration. At a corporate-sized
+ * catalog the untrimmed record set was 323 KB of that attribute, ~18% of the
+ * page, most of it fields no card or row ever looks at — `license`,
+ * `authors`, `vendor`, `documentation`, `compatibility`, `revision`,
+ * `support`, `repository`, and every unknown enrichment key riding
+ * `IndexRecord`'s index signature.
+ *
+ * This is a TYPE, not just a filter, and that is the point: a component that
+ * reaches for a field not listed here fails to compile, rather than silently
+ * rendering `undefined` in the browser while the server render — which reads
+ * the full record — looks correct. The detail pages are unaffected; they read
+ * `data` directly and hydrate nothing.
+ */
+export type CardPackage = Pick<
+  CatalogPackage,
+  | "name"
+  | "kind"
+  | "ref"
+  | "namespace"
+  | "description"
+  | "summary"
+  | "version"
+  | "keywords"
+  | "created"
+  | "updated"
+  | "deprecated"
+  | "replacedBy"
+  | "logo"
+  | "rating"
+>;
+
+/** The keys of `CardPackage`, as one list the projection actually iterates. */
+const CARD_FIELDS = [
+  "name",
+  "kind",
+  "ref",
+  "namespace",
+  "description",
+  "summary",
+  "version",
+  "keywords",
+  "created",
+  "updated",
+  "deprecated",
+  "replacedBy",
+  "logo",
+  "rating",
+] as const satisfies readonly (keyof CardPackage)[];
+
+/**
+ * One package, trimmed to what the island renders.
+ *
+ * An absent key is omitted rather than set to `undefined`: `JSON.stringify`
+ * drops an undefined value anyway, and omitting it keeps the projection's
+ * output identical to what a hand-written object literal would produce.
+ */
+export function cardPackage(p: CatalogPackage): CardPackage {
+  const out: Record<string, unknown> = {};
+  for (const key of CARD_FIELDS) {
+    if (p[key] !== undefined) out[key] = p[key];
+  }
+  return out as CardPackage;
+}
+
 /**
  * When a package last moved, for sorting and for the "updated" stamp.
  *
@@ -18,7 +90,7 @@ export type { CatalogPackage } from "../../types.js";
  * existed: those records still date correctly instead of dropping into the
  * unknown bucket on the first build after an upgrade.
  */
-export function lastUpdated(p: CatalogPackage): string | undefined {
+export function lastUpdated(p: Pick<CatalogPackage, "updated" | "created">): string | undefined {
   return p.updated ?? p.created;
 }
 

package/dist/renderer/astro/lib/search.d.ts

@@ -0,0 +1,17 @@
+/** Every package that matched, by `ref`, with its 0–1 score. */
+export type Scores = ReadonlyMap<string, number>;
+export interface SearchIndex {
+    /** Score one query against the whole catalog. Empty query, empty map. */
+    search(query: string): Scores;
+}
+/**
+ * Fetch the full catalog and build the matcher over it.
+ *
+ * Rejects rather than degrading quietly — the caller decides what a failure
+ * means, and for the island it means "keep the substring filter". Records
+ * without a string `ref` are dropped instead of failing the whole load: `ref`
+ * is how a hit is joined back onto the card the island already holds, so a
+ * record without one could never be shown even if it matched.
+ */
+export declare function loadSearchIndex(url: string): Promise<SearchIndex>;
+//# sourceMappingURL=search.d.ts.map

package/dist/renderer/astro/lib/search.js

@@ -0,0 +1,138 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 The Grimoire Authors
+// The catalog's fuzzy search, and the only module in the client bundle that
+// imports `fuzzysort`.
+//
+// It is reached exclusively through `await import()` from `Catalog.tsx`, so
+// the library and this file land in a chunk of their own that nothing
+// downloads until a reader actually types. That is the whole reason this is
+// a separate file rather than a function in the island: a static import here
+// would put ~7.6 KB of matcher on the critical path of a page most visitors
+// never search.
+//
+// It is also where the catalog stops being limited to what the island was
+// handed. `Catalog.tsx` receives `CardPackage` — the fourteen fields a card
+// or a row draws — because island props are serialized into the page and
+// every extra field is paid for twice. Search wants the opposite trade: the
+// whole record, including the fields no card shows. `/all.json` already
+// publishes exactly that and is a frozen public URL (see `renderer/index.ts`),
+// so the full text is one lazy fetch away and costs the initial render
+// nothing.
+import fuzzysort from "fuzzysort";
+/**
+ * How good a match has to be to count, on fuzzysort's 0–1 scale.
+ *
+ * Measured against the library's own scoring (4.0.2), not guessed: a
+ * one-character typo — `catlog` against `catalog-indexer` — scores .353, and
+ * a coincidental subsequence — `gard` finding g…a…r…d scattered across an
+ * unrelated description — scores .221. Anything between those two numbers
+ * keeps typo tolerance while dropping the coincidences, and .3 sits there.
+ *
+ * The library's own default is .5, which rejects every typo above, and its
+ * default `limit` is 10, which would silently cap a catalog search at the
+ * first ten hits. Both are overridden below on purpose.
+ */
+const THRESHOLD = 0.3;
+/**
+ * How long to wait for `/all.json` before giving up on fuzzy search.
+ *
+ * Failure here is not an error the reader sees: the island keeps its own
+ * substring filter over the fields it was handed, so a slow or unreachable
+ * index degrades to what the catalog did before this file existed.
+ */
+const TIMEOUT_MS = 15_000;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * One field as searchable text, or nothing.
+ *
+ * Arrays (`keywords`, `tags`) join; anything that is not a string is dropped
+ * rather than coerced. `String(value)` would put `[object Object]` and
+ * `undefined` into the haystack, which then match queries containing them.
+ */
+function text(value) {
+    if (typeof value === "string")
+        return value || undefined;
+    if (Array.isArray(value)) {
+        const parts = value.filter((item) => typeof item === "string");
+        return parts.length > 0 ? parts.join(" ") : undefined;
+    }
+    return undefined;
+}
+/**
+ * What a query is matched against — deliberately everything a human would
+ * expect to find a package by, not just what the card draws.
+ *
+ * Each key is scored separately and the terms of a multi-word query may land
+ * on different ones, so listing a field here means "typing this word finds
+ * the package", never "the word has to appear beside the others".
+ *
+ * Left out on purpose: `logo` and `revision` (opaque identifiers nobody
+ * searches for), `created`/`updated` (timestamps — the sort answers that
+ * question), `rating` (a count), `support` (contact URLs, not descriptions),
+ * and `deprecated`, whose reason text would pull retired packages into
+ * results for words their replacement never used.
+ */
+const KEYS = [
+    (p) => text(p.name),
+    (p) => text(p.title),
+    (p) => text(p.namespace),
+    (p) => text(p.kind),
+    (p) => text(p.ref),
+    (p) => text(p.description),
+    (p) => text(p.summary),
+    (p) => text(p.keywords),
+    (p) => text(p.tags),
+    (p) => text(p.vendor),
+    (p) => text(p.authors),
+    (p) => text(p.license),
+    (p) => text(p.repository),
+    (p) => text(p.url),
+    (p) => text(p.documentation),
+    (p) => text(p.compatibility),
+    (p) => text(p.replacedBy),
+];
+/**
+ * Fetch the full catalog and build the matcher over it.
+ *
+ * Rejects rather than degrading quietly — the caller decides what a failure
+ * means, and for the island it means "keep the substring filter". Records
+ * without a string `ref` are dropped instead of failing the whole load: `ref`
+ * is how a hit is joined back onto the card the island already holds, so a
+ * record without one could never be shown even if it matched.
+ */
+export async function loadSearchIndex(url) {
+    const response = await fetch(url, { signal: AbortSignal.timeout(TIMEOUT_MS) });
+    if (!response.ok) {
+        throw new Error(`GET ${url}: ${response.status} ${response.statusText}`);
+    }
+    const raw = await response.json();
+    if (!Array.isArray(raw))
+        throw new Error(`${url}: expected an array of records`);
+    const records = raw
+        .filter(isRecord)
+        .filter((record) => typeof record.ref === "string");
+    // Prepared once, reused for every keystroke — the whole point of the
+    // snapshot API, and what keeps typing cheap on a large catalog.
+    const snapshot = fuzzysort.snapshot(records, { keys: KEYS });
+    return {
+        search(query) {
+            const scores = new Map();
+            const needle = query.trim();
+            if (!needle)
+                return scores;
+            // `limit: 0` because this feeds a filter, not a typeahead: a capped
+            // result set would hide packages the reader can see are missing.
+            for (const hit of fuzzysort.go(needle, snapshot, {
+                limit: 0,
+                threshold: THRESHOLD,
+            })) {
+                const ref = hit.obj.ref;
+                if (typeof ref === "string")
+                    scores.set(ref, hit.score);
+            }
+            return scores;
+        },
+    };
+}

package/dist/renderer/astro/lib/search.ts

@@ -0,0 +1,157 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 The Grimoire Authors
+
+// The catalog's fuzzy search, and the only module in the client bundle that
+// imports `fuzzysort`.
+//
+// It is reached exclusively through `await import()` from `Catalog.tsx`, so
+// the library and this file land in a chunk of their own that nothing
+// downloads until a reader actually types. That is the whole reason this is
+// a separate file rather than a function in the island: a static import here
+// would put ~7.6 KB of matcher on the critical path of a page most visitors
+// never search.
+//
+// It is also where the catalog stops being limited to what the island was
+// handed. `Catalog.tsx` receives `CardPackage` — the fourteen fields a card
+// or a row draws — because island props are serialized into the page and
+// every extra field is paid for twice. Search wants the opposite trade: the
+// whole record, including the fields no card shows. `/all.json` already
+// publishes exactly that and is a frozen public URL (see `renderer/index.ts`),
+// so the full text is one lazy fetch away and costs the initial render
+// nothing.
+import fuzzysort from "fuzzysort";
+
+/**
+ * How good a match has to be to count, on fuzzysort's 0–1 scale.
+ *
+ * Measured against the library's own scoring (4.0.2), not guessed: a
+ * one-character typo — `catlog` against `catalog-indexer` — scores .353, and
+ * a coincidental subsequence — `gard` finding g…a…r…d scattered across an
+ * unrelated description — scores .221. Anything between those two numbers
+ * keeps typo tolerance while dropping the coincidences, and .3 sits there.
+ *
+ * The library's own default is .5, which rejects every typo above, and its
+ * default `limit` is 10, which would silently cap a catalog search at the
+ * first ten hits. Both are overridden below on purpose.
+ */
+const THRESHOLD = 0.3;
+
+/**
+ * How long to wait for `/all.json` before giving up on fuzzy search.
+ *
+ * Failure here is not an error the reader sees: the island keeps its own
+ * substring filter over the fields it was handed, so a slow or unreachable
+ * index degrades to what the catalog did before this file existed.
+ */
+const TIMEOUT_MS = 15_000;
+
+/** Every package that matched, by `ref`, with its 0–1 score. */
+export type Scores = ReadonlyMap<string, number>;
+
+export interface SearchIndex {
+  /** Score one query against the whole catalog. Empty query, empty map. */
+  search(query: string): Scores;
+}
+
+/**
+ * A record straight off the wire — every value `unknown`, because nothing
+ * validated it and `all.json` carries publisher-authored enrichment under an
+ * open index signature.
+ */
+type WireRecord = Readonly<Record<string, unknown>>;
+
+function isRecord(value: unknown): value is WireRecord {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * One field as searchable text, or nothing.
+ *
+ * Arrays (`keywords`, `tags`) join; anything that is not a string is dropped
+ * rather than coerced. `String(value)` would put `[object Object]` and
+ * `undefined` into the haystack, which then match queries containing them.
+ */
+function text(value: unknown): string | undefined {
+  if (typeof value === "string") return value || undefined;
+  if (Array.isArray(value)) {
+    const parts = value.filter((item) => typeof item === "string");
+    return parts.length > 0 ? parts.join(" ") : undefined;
+  }
+  return undefined;
+}
+
+/**
+ * What a query is matched against — deliberately everything a human would
+ * expect to find a package by, not just what the card draws.
+ *
+ * Each key is scored separately and the terms of a multi-word query may land
+ * on different ones, so listing a field here means "typing this word finds
+ * the package", never "the word has to appear beside the others".
+ *
+ * Left out on purpose: `logo` and `revision` (opaque identifiers nobody
+ * searches for), `created`/`updated` (timestamps — the sort answers that
+ * question), `rating` (a count), `support` (contact URLs, not descriptions),
+ * and `deprecated`, whose reason text would pull retired packages into
+ * results for words their replacement never used.
+ */
+const KEYS: readonly ((p: WireRecord) => string | undefined)[] = [
+  (p) => text(p.name),
+  (p) => text(p.title),
+  (p) => text(p.namespace),
+  (p) => text(p.kind),
+  (p) => text(p.ref),
+  (p) => text(p.description),
+  (p) => text(p.summary),
+  (p) => text(p.keywords),
+  (p) => text(p.tags),
+  (p) => text(p.vendor),
+  (p) => text(p.authors),
+  (p) => text(p.license),
+  (p) => text(p.repository),
+  (p) => text(p.url),
+  (p) => text(p.documentation),
+  (p) => text(p.compatibility),
+  (p) => text(p.replacedBy),
+];
+
+/**
+ * Fetch the full catalog and build the matcher over it.
+ *
+ * Rejects rather than degrading quietly — the caller decides what a failure
+ * means, and for the island it means "keep the substring filter". Records
+ * without a string `ref` are dropped instead of failing the whole load: `ref`
+ * is how a hit is joined back onto the card the island already holds, so a
+ * record without one could never be shown even if it matched.
+ */
+export async function loadSearchIndex(url: string): Promise<SearchIndex> {
+  const response = await fetch(url, { signal: AbortSignal.timeout(TIMEOUT_MS) });
+  if (!response.ok) {
+    throw new Error(`GET ${url}: ${response.status} ${response.statusText}`);
+  }
+  const raw: unknown = await response.json();
+  if (!Array.isArray(raw)) throw new Error(`${url}: expected an array of records`);
+  const records = raw
+    .filter(isRecord)
+    .filter((record) => typeof record.ref === "string");
+  // Prepared once, reused for every keystroke — the whole point of the
+  // snapshot API, and what keeps typing cheap on a large catalog.
+  const snapshot = fuzzysort.snapshot(records, { keys: KEYS });
+
+  return {
+    search(query) {
+      const scores = new Map<string, number>();
+      const needle = query.trim();
+      if (!needle) return scores;
+      // `limit: 0` because this feeds a filter, not a typeahead: a capped
+      // result set would hide packages the reader can see are missing.
+      for (const hit of fuzzysort.go(needle, snapshot, {
+        limit: 0,
+        threshold: THRESHOLD,
+      })) {
+        const ref = hit.obj.ref;
+        if (typeof ref === "string") scores.set(ref, hit.score);
+      }
+      return scores;
+    },
+  };
+}