@grimoire-rs/indexer 0.5.1 → 0.5.3

package/dist/renderer/astro/components/Catalog.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "preact/jsx-runtime";
-import { useEffect, useLayoutEffect, useMemo, useRef, useState, } from "preact/hooks";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, } from "preact/hooks";
 // Lucide (ISC) draws the toolbar. The brand marks and kind glyphs moved out
 // with the card and the row that wear them.
 import { ArrowDownWideNarrow, ArrowUpNarrowWide, LayoutGrid, List, X, } from "lucide-preact";
@@ -7,6 +7,7 @@ import { PackageCard } from "./PackageCard.js";
 import { PackageRow } from "./PackageRow.js";
 import { keywordFrequency, selectRailKeywords } from "../lib/keywordRail.js";
 import { lastUpdated } from "../lib/catalog.js";
+import { withBase } from "../lib/base.js";
 // Known kinds get stable chip ordering + badge colors; unknown kinds
 // (future schema growth) still render with a neutral badge.
 const KNOWN_KINDS = ["skill", "rule", "agent", "mcp", "bundle"];
@@ -22,6 +23,10 @@ function kindOrder(kind) {
  * all of it is a wall of chips nobody reads.
  */
 const KEYWORD_CHIP_LIMIT = 8;
+/**
+ * How many packages the catalog builds at a time. See `limit` in `Catalog`.
+ */
+const WINDOW = 48;
 /**
  * `popovertarget` needs an id, and the catalog is a singleton on its page —
  * one island, one toolbar, one overflow menu — so this is a constant rather
@@ -41,6 +46,7 @@ export const NATURAL = {
     name: "asc",
     updated: "desc",
     rating: "desc",
+    relevance: "desc",
 };
 /**
  * Bigger first, with `null` as its own bucket underneath every number.
@@ -85,6 +91,16 @@ const CHAINS = {
     name: [byName],
     updated: [byUpdated, byName],
     rating: [byRating, byUpdated, byName],
+    // Relevance cannot be a key here: a score belongs to a query, not to a
+    // package, so it is not on the record `compare` is handed. `shown` sorts
+    // that mode itself.
+    //
+    // This entry is what the mode falls back to whenever there are no scores —
+    // no query typed, or the fuzzy index still downloading — which is also why
+    // relevance can be offered and stored like any other mode. Alphabetical is
+    // the honest answer to "rank these against nothing", and it is what the
+    // catalog already shows on arrival.
+    relevance: [byName],
 };
 // Deprecated packages get no special ordering here — they are filtered out
 // of the default browse entirely (see `shown` below) and interleave like
@@ -242,7 +258,13 @@ export default function Catalog({ packages, vscodeExtension, }) {
     // Local to the overflow menu and deliberately not shareable: it narrows
     // the list of keywords, not the catalog.
     const [keywordFilter, setKeywordFilter] = useState("");
+    // The fuzzy matcher, once it has been fetched. `null` is the normal state
+    // for most of a visit — see the loader below — and every consumer treats
+    // it as "fall back to the substring filter", never as an error.
+    const [index, setIndex] = useState(null);
     const searchRef = useRef(null);
+    /** Whether the sort combo's last interaction came from a pointer. */
+    const pickedByPointer = useRef(false);
     const gridRef = useRef(null);
     const controlsRef = useRef(null);
     // Both views, one selector: a table row is the Tab stop its card is, so
@@ -258,8 +280,40 @@ export default function Catalog({ packages, vscodeExtension, }) {
         ...(controlsRef.current?.querySelectorAll('button.chip:not([aria-hidden="true"])') ?? []),
     ];
     const railRefs = useRef(new Map());
-    const railRects = useRef(new Map());
+    /**
+     * Where each chip sat at the last commit, as `offsetLeft`/`offsetTop`.
+     *
+     * Layout positions, deliberately, not `getBoundingClientRect`: the offsets
+     * ignore transforms and page scroll, so a chip measured mid-slide reports
+     * the seat it is animating towards rather than the box it is drawn in this
+     * frame. See the FLIP effect below for why that distinction is the whole
+     * fix.
+     */
+    const railSeats = useRef(new Map());
+    /** The slide each chip is currently running, so a new one can replace it. */
+    const railSlides = useRef(new WeakMap());
     const railRef = useRef(null);
+    /**
+     * Which chips are up, in order, as of the current render — written below,
+     * once `visibleKeywords` exists, and read by the two layout effects.
+     *
+     * Both of those effects measure geometry, and a geometry read forces a
+     * synchronous style and layout pass over the WHOLE document. Neither had a
+     * dependency array, so both ran on every commit — including a commit that
+     * changed no chip at all. Switching to the list view is that commit, and at
+     * 500 packages it paid two forced layouts over several hundred rows Preact
+     * had just mounted: a 600ms task, most of it in `ForcedStyleAndLayout`.
+     *
+     * A ref rather than a dependency array because the chip list is computed
+     * hundreds of lines below these hooks, and a value cannot be a dependency
+     * before it exists. Writing a ref during render is safe — it is not state,
+     * nothing re-renders from it, and an effect body always runs after the
+     * render that wrote it.
+     */
+    const railSignature = useRef("");
+    /** What `railSignature` was when each effect last did its reads. */
+    const railMeasured = useRef(null);
+    const railFlipped = useRef(null);
     const kwMenuRef = useRef(null);
     const kwTriggerRef = useRef(null);
     // Drives the trigger's own `aria-expanded` and its open styling. The panel's
@@ -330,38 +384,55 @@ export default function Catalog({ packages, vscodeExtension, }) {
      * disagrees with itself on every other frame.
      */
     const [railFit, setRailFit] = useState(KEYWORD_CHIP_LIMIT);
-    useLayoutEffect(() => {
+    const measureRail = useCallback(() => {
         const rail = railRef.current;
         if (!rail)
             return;
-        const measure = () => {
-            const edge = rail.getBoundingClientRect().right;
-            let fits = 0;
-            for (const chip of rail.children) {
-                // Half a pixel of slack: a fractional layout can leave a chip's right
-                // edge a rounding error past a boundary it visually sits inside.
-                if (chip.getBoundingClientRect().right > edge + 0.5)
-                    break;
-                fits += 1;
-            }
-            // At least one, always. A rail too narrow for its shortest chip should
-            // show that chip clipped rather than render an empty group beside a
-            // divider that then divides nothing.
-            setRailFit(Math.max(1, fits));
-        };
-        measure();
-        // Guarded rather than assumed: this effect also runs under the test
-        // renderer, whose DOM has no `ResizeObserver` — and a missing one costs
-        // only re-measurement on viewport resize, which is not worth throwing
-        // during a render over.
-        if (typeof ResizeObserver === "undefined")
+        const edge = rail.getBoundingClientRect().right;
+        let fits = 0;
+        for (const chip of rail.children) {
+            // Half a pixel of slack: a fractional layout can leave a chip's right
+            // edge a rounding error past a boundary it visually sits inside.
+            if (chip.getBoundingClientRect().right > edge + 0.5)
+                break;
+            fits += 1;
+        }
+        // At least one, always. A rail too narrow for its shortest chip should
+        // show that chip clipped rather than render an empty group beside a
+        // divider that then divides nothing.
+        setRailFit(Math.max(1, fits));
+    }, []);
+    /**
+     * The rail's own `ref`, so the resize observer is attached exactly when the
+     * element exists. It is conditionally rendered — no keywords, no rail — and
+     * a `[]`-dependency effect would miss it appearing later.
+     *
+     * This also stops the observer being torn down and rebuilt on every commit,
+     * which was not free: `observe()` delivers an initial callback, so a rebuild
+     * per commit meant a measurement per commit no matter what gated the effect.
+     *
+     * Guarded rather than assumed: this runs under the test renderer too, whose
+     * DOM has no `ResizeObserver` — and a missing one costs only re-measurement
+     * on viewport resize, which is not worth throwing during a render over.
+     */
+    const railObserver = useRef(null);
+    const attachRail = useCallback((el) => {
+        railRef.current = el;
+        railObserver.current?.disconnect();
+        railObserver.current = null;
+        if (!el || typeof ResizeObserver === "undefined")
             return;
-        const observer = new ResizeObserver(measure);
-        observer.observe(rail);
-        return () => observer.disconnect();
-        // Re-measured on every commit that changes which chips are up, since the
-        // observer only fires when the rail's own box changes and a rescore can
-        // swap a short word for a long one at the same width.
+        railObserver.current = new ResizeObserver(measureRail);
+        railObserver.current.observe(el);
+    }, [measureRail]);
+    // Re-measured when the chips change, and only then — a rescore can swap a
+    // short word for a long one at the same width, which the observer above
+    // would never see. See `railSignature` for why the guard is a ref.
+    useLayoutEffect(() => {
+        if (railSignature.current === railMeasured.current)
+            return;
+        railMeasured.current = railSignature.current;
+        measureRail();
     });
     /**
      * FLIP for the keyword rail: chips slide to their new places instead of
@@ -373,71 +444,89 @@ export default function Catalog({ packages, vscodeExtension, }) {
      * between two frames reads as having been *replaced*, and a reader who
      * cannot see that a chip moved has no reason to believe it is the same one.
      *
-     * First (the map of rects kept from the last commit), Last (measured now),
-     * Invert (an inline translate back to where the chip was), Play (dropped on
-     * the next frame, so the stylesheet's transition carries it home). Measure
-     * every chip before transforming any: `translate` composites and does not
-     * reflow, but reading a rect after writing a style on a sibling is the
-     * shape that makes a layout thrash, and this runs per keystroke.
+     * Two choices carry the whole thing, and both are here because the shape
+     * they replace — an inline `translate` under the stylesheet's transition,
+     * dropped again on a `requestAnimationFrame` — could leave a chip stopped
+     * off its seat with no path back:
+     *
+     * - **Seats come from `offsetLeft`/`offsetTop`, never from
+     *   `getBoundingClientRect`.** The offsets are layout positions and ignore
+     *   both transforms and scroll; a rect is where the chip is *drawn*, so a
+     *   chip measured mid-slide recorded its animated box and the next
+     *   inversion compounded that error — the stutter. Mid-slide is the common
+     *   case, not a rare one: the fit measurement above commits a second time
+     *   whenever a rescore changes how many chips fit, and that commit lands
+     *   inside the previous slide. Because the offsets are transform-blind,
+     *   that second commit now measures the same seats and starts nothing.
+     * - **The slide is a Web Animation, not an inline style.** It needs no
+     *   frame to start, so no commit can land between an invert and its play
+     *   and freeze a chip at the offset. It writes nothing to `style`, so
+     *   there is nothing left to strip when a chip unmounts or a pass is
+     *   superseded. And it clears itself the instant it finishes or is
+     *   cancelled, which makes "the rail always ends up in its real state" a
+     *   property of the mechanism rather than of a cleanup remembering to run.
      */
     useLayoutEffect(() => {
-        // Undo whatever the last pass left on the chips before measuring
-        // anything. Two reasons, and both were visible: `getBoundingClientRect`
-        // reports the *translated* box, so a chip caught mid-slide would be
-        // measured where it is drawn rather than where it belongs and the next
-        // inversion would compound that error; and a chip whose play frame never
-        // ran is still carrying `transition: none` with an offset, which is a chip
-        // frozen off its seat. Clearing here is what unfreezes it.
+        // Same guard as the fit measurement, for the same reason: `offsetLeft`
+        // forces layout, and a commit that moved no chip has nothing to animate.
         //
-        // Mid-slide is not a rare case: the fit measurement above commits a second
-        // time whenever the rescore changes how many chips fit, and that commit
-        // lands between this one and its animation frame.
-        for (const el of railRefs.current.values()) {
-            el.style.transition = "";
-            el.style.translate = "";
-        }
-        const previous = railRects.current;
+        // The seats it leaves behind are therefore from the last chip change
+        // rather than from the last commit, which is what FLIP wants. The one
+        // case that costs: a viewport resize between two chip changes moves the
+        // chips without changing the signature, so the next slide starts from
+        // pre-resize seats. One slightly-off slide after a resize, against two
+        // forced layouts on every commit — including every keystroke and every
+        // view switch — which is the trade this makes.
+        if (railSignature.current === railFlipped.current)
+            return;
+        railFlipped.current = railSignature.current;
+        const previous = railSeats.current;
         const current = new Map();
         const moved = [];
-        // A second pass, deliberately: every write above is flushed before the
-        // first read below, rather than interleaving them per chip.
         for (const [keyword, el] of railRefs.current) {
-            const rect = el.getBoundingClientRect();
-            current.set(keyword, rect);
+            const x = el.offsetLeft;
+            const y = el.offsetTop;
+            current.set(keyword, { x, y });
             const was = previous.get(keyword);
             if (!was)
                 continue;
-            const dx = was.left - rect.left;
-            const dy = was.top - rect.top;
+            const dx = was.x - x;
+            const dy = was.y - y;
             if (dx !== 0 || dy !== 0)
                 moved.push({ el, dx, dy });
         }
-        railRects.current = current;
+        // Rebuilt from `railRefs` every pass, so a chip that left the rail leaves
+        // this map with it and cannot seed a slide if it comes back elsewhere.
+        railSeats.current = current;
         if (moved.length === 0)
             return;
+        const rail = railRef.current;
+        // Guarded rather than assumed, like the fit observer above: the test
+        // renderer's DOM has no Web Animations API, and a rail that does not
+        // slide is not worth throwing during a render over.
+        if (!rail || typeof rail.animate !== "function")
+            return;
+        // The motion is the ornament here — the filtering works identically
+        // without it — so a reader who asked for less of it gets none.
+        if (window.matchMedia?.("(prefers-reduced-motion: reduce)").matches)
+            return;
+        // The stylesheet stays the source of truth for how long a slide runs:
+        // `--grim-duration-slow` is written in milliseconds and that is the unit
+        // the Web Animations API takes, so the token survives the move out of CSS.
+        // Read once, after every seat above, so the reads and the writes below
+        // stay in two passes rather than interleaving per chip.
+        const ms = Number.parseFloat(getComputedStyle(rail).getPropertyValue("--grim-duration-slow"));
         for (const { el, dx, dy } of moved) {
-            el.style.transition = "none";
-            el.style.translate = `${dx}px ${dy}px`;
+            // One slide per chip. A chip that moves again mid-slide takes the new
+            // delta from its layout seat, which starts the second slide a step off
+            // where the first had drawn it — a jump measured in the pixels one
+            // frame of easing covers, and it is bounded, unlike two animations
+            // compositing the same property against each other.
+            // ponytail: not blended with the in-flight offset, which would cost a
+            // computed-style read per chip in the middle of the write pass.
+            railSlides.current.get(el)?.cancel();
+            railSlides.current.set(el, el.animate({ translate: [`${dx}px ${dy}px`, "none"] }, { duration: Number.isFinite(ms) ? ms : 200, easing: "ease-out" }));
         }
-        const frame = requestAnimationFrame(() => {
-            for (const { el } of moved) {
-                el.style.transition = "";
-                el.style.translate = "";
-            }
-        });
-        return () => {
-            cancelAnimationFrame(frame);
-            // Cancelling is not enough on its own. Nothing else takes these off, so
-            // a commit landing before the frame ran would leave every moved chip
-            // sitting at its inverted offset with transitions disabled — the rail
-            // stopping halfway and staying there. Deselecting the last keyword is
-            // the reliable way to see it: the rescore is at its largest, so the fit
-            // changes and the extra commit always lands.
-            for (const { el } of moved) {
-                el.style.transition = "";
-                el.style.translate = "";
-            }
-        };
     });
     /** Move focus `delta` cards along, clamping at both ends rather than wrapping. */
     const focusCard = (from, delta) => {
@@ -490,7 +579,7 @@ export default function Catalog({ packages, vscodeExtension, }) {
         const s = readPref("sort");
         const d = readPref("dir");
         const v = readPref("view");
-        const field = s === "updated" || s === "rating" ? s : "name";
+        const field = s === "updated" || s === "rating" || s === "relevance" ? s : "name";
         const published = new Set(packages.flatMap((p) => p.keywords ?? []));
         setQuery(params.get("q") ?? "");
         setKinds(list(params.get("kind")).filter((k) => KNOWN_KINDS.includes(k)));
@@ -765,16 +854,71 @@ export default function Catalog({ packages, vscodeExtension, }) {
         return [...seen].sort((a, b) => kindOrder(a) - kindOrder(b) || a.localeCompare(b));
     }, [counted]);
     const q = query.trim().toLowerCase();
+    /**
+     * Fetch the fuzzy matcher, once, the first time anyone searches.
+     *
+     * Not on mount: a reader who never types pays nothing — no `fuzzysort`
+     * chunk, no `/all.json`. Not per keystroke either; `tried` latches on the
+     * first attempt, so a failed load degrades to the substring filter for the
+     * rest of the visit rather than re-fetching on every letter.
+     *
+     * A failure is not shown to the reader on purpose. Search keeps working —
+     * the substring path over the card's own fields is what the catalog did
+     * before this existed — so an error banner would report a downgrade nobody
+     * asked about, over a page that is doing what they asked. It goes to the
+     * console with the error value itself, chain and stack intact.
+     */
+    const tried = useRef(false);
+    useEffect(() => {
+        if (!q || tried.current)
+            return;
+        tried.current = true;
+        // Self-catching, so the `void` attaches nothing it needs to: every await
+        // on the path is inside the try.
+        void (async () => {
+            try {
+                const { loadSearchIndex } = await import("../lib/search.js");
+                setIndex(await loadSearchIndex(withBase("/all.json")));
+            }
+            catch (err) {
+                console.error("catalog: fuzzy search unavailable, using substring match", err);
+            }
+        })();
+    }, [q]);
+    /**
+     * What the current query scored against every package, or `null` when
+     * there is no query or no matcher yet.
+     *
+     * Memoized on the pair: re-scoring the whole catalog is the one genuinely
+     * expensive thing a keystroke triggers, and every consumer below reads it.
+     */
+    const scores = useMemo(() => (index && q ? index.search(q) : null), [index, q]);
     // Query and facets first, deprecation last — so the toggle can report how
     // many entries *it alone* is holding back, rather than a catalog-wide
     // number that has nothing to do with what is on screen.
-    const matching = packages.filter((p) => {
+    //
+    // Memoized, and `shown` with it, for a reason beyond the scan's own cost:
+    // an unmemoized `.filter().sort()` yields a NEW array on every render, so
+    // anything downstream keyed on `shown` — the keyword rail's set-cover below
+    // — could never hit its own cache. Both had to move together or neither
+    // helped. Every dependency here is a primitive or a state array, so the
+    // identity is stable exactly when the answer is.
+    const matching = useMemo(() => packages.filter((p) => {
         if (kinds.length > 0 && !kinds.includes(p.kind))
             return false;
         if (!keywords.every((kw) => p.keywords?.includes(kw)))
             return false;
         if (!q)
             return true;
+        // The fuzzy index, once it is here: multi-term, order-independent,
+        // typo-tolerant, and over every field `/all.json` carries — the
+        // licence, the vendor, the repository, the authors, none of which
+        // are on the record this island was handed.
+        if (scores)
+            return scores.has(p.ref);
+        // Until then, and if the fetch never lands: the substring pass over
+        // the fields the card itself ships. Narrower on both axes, and the
+        // reason the search box is never dead while a chunk downloads.
         return [
             p.name,
             p.description ?? "",
@@ -784,8 +928,82 @@ export default function Catalog({ packages, vscodeExtension, }) {
             p.summary ?? "",
             (p.keywords ?? []).join(" "),
         ].some((field) => field.toLowerCase().includes(q));
-    });
-    const shown = (showDeprecated ? matching : matching.filter((p) => !p.deprecated)).sort((a, b) => compare(a, b, sort, dir));
+    }), [packages, kinds, keywords, q, scores]);
+    const shown = useMemo(() => {
+        // `.filter()` already returns a fresh array, so sorting in place here
+        // mutates nothing the memo above holds — except in the `showDeprecated`
+        // branch, where `matching` IS that array. Copy before sorting.
+        const list = showDeprecated
+            ? [...matching]
+            : matching.filter((p) => !p.deprecated);
+        // Relevance is sorted here rather than in `compare`, because the score is
+        // a property of the query and not of the package — see `CHAINS`. Name
+        // breaks the tie, so equally-scored packages keep a total order and the
+        // list cannot reshuffle between renders.
+        if (sort === "relevance" && scores) {
+            return list.sort((a, b) => {
+                const d = descending(scores.get(a.ref) ?? null, scores.get(b.ref) ?? null) ||
+                    byName(a, b);
+                return dir === NATURAL.relevance ? d : -d;
+            });
+        }
+        return list.sort((a, b) => compare(a, b, sort, dir));
+    }, [matching, showDeprecated, sort, dir, scores]);
+    /**
+     * How many of `shown` are actually built.
+     *
+     * The island's cost is dominated by constructing components, not by drawing
+     * them: `content-visibility` on the card and the row already means the
+     * browser skips layout and paint for anything off screen, but Preact still
+     * built every one. At 500 packages that was ~440 card components on
+     * hydration and another ~440 row components the moment the view changed —
+     * a 1.9s wait before a stored list view was on screen at all.
+     *
+     * So only a viewport's worth is built, and the slice GROWS as a sentinel
+     * below the list comes into view. It never shrinks, which is the whole
+     * reason this is a slice rather than true virtualization: an item that has
+     * been built stays built, so scrolling back up can never meet a blank row,
+     * and find-in-page keeps working over everything reached so far. The
+     * worst case — a reader who scrolls to the bottom — is exactly today's
+     * behaviour, and its paint is still bounded by `content-visibility`.
+     *
+     * 48 covers a tall viewport of either shape with room over: rows are 34px,
+     * and the card grid is three or four across at 19rem minimum.
+     */
+    const [limit, setLimit] = useState(WINDOW);
+    // A new result set starts a new window — otherwise narrowing to 3 matches
+    // and clearing the filter again would leave the whole catalog built.
+    // `shown` is memoized, so this identity changes exactly when the answer does.
+    const shownRef = useRef(shown);
+    if (shownRef.current !== shown) {
+        shownRef.current = shown;
+        if (limit !== WINDOW)
+            setLimit(WINDOW);
+    }
+    const visible = limit >= shown.length ? shown : shown.slice(0, limit);
+    /**
+     * Grow the window when the sentinel below the list is reached.
+     *
+     * `rootMargin` is what keeps this invisible in use: the next slice is built
+     * a screen and a half before the reader gets to it, so the list reads as
+     * complete rather than as something that loads while you look at it. The
+     * observer re-fires while the sentinel stays in view, so a fast scroll
+     * keeps growing the window a slice per frame rather than stalling.
+     */
+    const sentinelRef = useRef(null);
+    useEffect(() => {
+        const el = sentinelRef.current;
+        // Guarded like the rail's observer: the test renderer's DOM has neither.
+        if (!el || typeof IntersectionObserver === "undefined")
+            return;
+        const io = new IntersectionObserver((entries) => {
+            if (!entries.some((e) => e.isIntersecting))
+                return;
+            setLimit((l) => (l >= shown.length ? l : l + WINDOW));
+        }, { rootMargin: "150% 0px" });
+        io.observe(el);
+        return () => io.disconnect();
+    }, [shown.length]);
     /**
      * The keyword rail, over what is on screen rather than over the catalog.
      *
@@ -809,7 +1027,15 @@ export default function Catalog({ packages, vscodeExtension, }) {
         keyword,
         count: shown.length,
     }));
-    const rail = selectRailKeywords(shown, KEYWORD_CHIP_LIMIT)
+    // Memoized on `shown` alone, because that is the only thing the scan reads.
+    // `selectRailKeywords` is a greedy set-cover over every keyword of every
+    // shown package — it scales with catalog size, and unmemoized it ran on
+    // EVERY render: each keystroke in the search box, each chip click, each
+    // view toggle, and once more for every re-render none of those caused. At a
+    // corporate-sized catalog that is the most expensive thing in the render
+    // path, repeated for an answer that had not changed.
+    const scored = useMemo(() => selectRailKeywords(shown, KEYWORD_CHIP_LIMIT), [shown]);
+    const rail = scored
         // `selectRailKeywords` scores the actives like any other keyword, so
         // over-request and drop them rather than spend rail slots twice.
         .filter((k) => !keywords.includes(k.keyword))
@@ -821,6 +1047,10 @@ export default function Catalog({ packages, vscodeExtension, }) {
     // chip clipped at the rail's edge is one the reader cannot reach anywhere
     // else, and a "+N more" that does not count it is lying about where it is.
     const clippedKeywords = visibleKeywords.slice(railFit).map((k) => k.keyword);
+    // What the two layout effects above compare against. In render order, so a
+    // reorder counts as a change — the FLIP effect exists to animate exactly
+    // that. NUL-joined because a keyword may contain anything but that.
+    railSignature.current = visibleKeywords.map((k) => k.keyword).join("\u0000");
     const menuKeywords = keywordFrequency(shown).filter((k) => clippedKeywords.includes(k.keyword) ||
         !visibleKeywords.some((v) => v.keyword === k.keyword));
     // Plain substring, not a fuzzy match: this searches a list the reader is
@@ -831,7 +1061,10 @@ export default function Catalog({ packages, vscodeExtension, }) {
     // no ratings gets no rating chip for the same reason.
     const hasDeprecated = packages.some((p) => p.deprecated);
     const hasRatings = packages.some((p) => p.rating);
-    return (_jsxs("section", { class: "catalog", "data-slot": "catalog", children: [_jsxs("div", { class: "controls", "data-slot": "catalog-toolbar", ref: controlsRef, children: [_jsxs("div", { class: "search-field", "data-slot": "catalog-search", children: [_jsx("input", { ref: searchRef, type: "search", placeholder: "Search packages \u2014 name, keyword, description\u2026", value: query, onInput: (e) => setQuery(e.target.value), onKeyDown: onSearchKeyDown, "aria-label": "Search packages", "aria-keyshortcuts": "/" }), _jsx("kbd", { class: "search-hint", "aria-hidden": "true", children: "/" })] }), _jsxs("div", { class: "filter-row", children: [_jsxs("div", { class: "chips kind-chips", role: "group", "aria-label": "Filter by kind", children: [_jsx("button", { type: "button", class: kinds.length === 0 ? "chip active" : "chip", "data-slot": "filter-chip", "aria-pressed": kinds.length === 0, onKeyDown: onChipKeyDown, onClick: () => setKinds([]), children: "all" }), kindNames.map((k) => (_jsx("button", { type: "button", class: kinds.includes(k) ? `chip active kind-${k}` : `chip kind-${k}`, "data-slot": "filter-chip", "aria-pressed": kinds.includes(k), onKeyDown: onChipKeyDown, onClick: () => toggleKind(k), children: k }, k)))] }), visibleKeywords.length > 0 && (_jsxs(_Fragment, { children: [_jsx("span", { class: "filter-divider", "aria-hidden": "true" }), _jsx("div", { class: "chips kw-rail", role: "group", "aria-label": "Filter by keyword", ref: railRef, children: visibleKeywords.map(({ keyword }, i) => {
+    return (_jsxs("section", { class: "catalog", "data-slot": "catalog", children: [_jsxs("div", { class: "controls", "data-slot": "catalog-toolbar", ref: controlsRef, children: [_jsxs("div", { class: "search-field", "data-slot": "catalog-search", children: [_jsx("input", { ref: searchRef, type: "search", placeholder: "Search packages \u2014 name, keyword, description\u2026", value: query, onInput: (e) => setQuery(e.target.value), onKeyDown: onSearchKeyDown, "aria-label": "Search packages", "aria-keyshortcuts": "/" }), _jsx("kbd", { class: "search-hint", "aria-hidden": "true", children: "/" }), query && (_jsx("button", { type: "button", class: "search-clear", "aria-label": "Clear search", title: "Clear search", onClick: () => {
+                                    setQuery("");
+                                    searchRef.current?.focus();
+                                }, children: _jsx(X, { size: 12, "aria-hidden": "true" }) }))] }), _jsxs("div", { class: "filter-row", children: [_jsxs("div", { class: "chips kind-chips", role: "group", "aria-label": "Filter by kind", children: [_jsx("button", { type: "button", class: kinds.length === 0 ? "chip active" : "chip", "data-slot": "filter-chip", "aria-pressed": kinds.length === 0, onKeyDown: onChipKeyDown, onClick: () => setKinds([]), children: "all" }), kindNames.map((k) => (_jsx("button", { type: "button", class: kinds.includes(k) ? `chip active kind-${k}` : `chip kind-${k}`, "data-slot": "filter-chip", "aria-pressed": kinds.includes(k), onKeyDown: onChipKeyDown, onClick: () => toggleKind(k), children: k }, k)))] }), visibleKeywords.length > 0 && (_jsxs(_Fragment, { children: [_jsx("span", { class: "filter-divider", "aria-hidden": "true" }), _jsx("div", { class: "chips kw-rail", role: "group", "aria-label": "Filter by keyword", ref: attachRail, children: visibleKeywords.map(({ keyword }, i) => {
                                             // Past the measured fit: still laid out, so the measurement
                                             // that decided this stays true on the next pass, but drawn
                                             // as nothing and out of reach. Removing it from the flow
@@ -884,7 +1117,39 @@ export default function Catalog({ packages, vscodeExtension, }) {
                                             ? "Ascending — click for descending"
                                             : "Descending — click for ascending", "aria-label": dir === "asc"
                                             ? "Sorted ascending; sort descending"
-                                            : "Sorted descending; sort ascending", onClick: () => setDir((d) => (d === "asc" ? "desc" : "asc")), children: dir === "asc" ? (_jsx(ArrowUpNarrowWide, { size: 15, "aria-hidden": "true" })) : (_jsx(ArrowDownWideNarrow, { size: 15, "aria-hidden": "true" })) }), _jsxs("select", { class: "sort-field", "data-slot": "filter-chip", "aria-label": "Sort by", value: sort, onChange: (event) => {
+                                            : "Sorted descending; sort ascending", onClick: () => setDir((d) => (d === "asc" ? "desc" : "asc")), children: dir === "asc" ? (_jsx(ArrowUpNarrowWide, { size: 15, "aria-hidden": "true" })) : (_jsx(ArrowDownWideNarrow, { size: 15, "aria-hidden": "true" })) }), _jsxs("select", { class: "sort-field", "data-slot": "filter-chip", "aria-label": "Sort by", value: sort, 
+                                        // Chromium matches `:focus-visible` on a `<select>` after a
+                                        // plain MOUSE click — a select accepts keyboard input, so the
+                                        // engine treats every focus as keyboard focus. The repo's
+                                        // `:focus-visible` convention therefore cannot keep the accent
+                                        // ring off this one control, and CSS has nothing else to go on:
+                                        // no selector distinguishes focus that arrived from a pointer.
+                                        //
+                                        // So the pointer marks itself. `data-pointer` suppresses the
+                                        // ring for the whole pointer interaction — an open dropdown is
+                                        // its own affordance and needs no second one around the closed
+                                        // box behind it — and the pick then hands focus back, so
+                                        // nothing is left lit beside the thin neutral chips.
+                                        //
+                                        // The keyboard path must do NEITHER. Arrow keys on a closed
+                                        // select fire `change` per option, so blurring there would take
+                                        // the control away mid-selection, and a keyboard reader is
+                                        // exactly who the ring exists for. `onKeyDown` clears both, so
+                                        // a reader who clicks once and later tabs back is a keyboard
+                                        // reader again.
+                                        //
+                                        // Written to the node rather than to state: this fires while
+                                        // the native dropdown is open, and a re-render of the element
+                                        // holding it open is not worth the risk for a styling hint.
+                                        onPointerDown: (event) => {
+                                            pickedByPointer.current = true;
+                                            event.currentTarget.dataset.pointer = "";
+                                        }, onKeyDown: (event) => {
+                                            pickedByPointer.current = false;
+                                            delete event.currentTarget.dataset.pointer;
+                                        }, onBlur: (event) => {
+                                            delete event.currentTarget.dataset.pointer;
+                                        }, onChange: (event) => {
                                             const next = event.currentTarget
                                                 .value;
                                             setSort(next);
@@ -892,7 +1157,10 @@ export default function Catalog({ packages, vscodeExtension, }) {
                                             // the previous one over lands the reader on "oldest first"
                                             // because they had asked for Z→A a moment ago.
                                             setDir(NATURAL[next]);
-                                        }, children: [_jsx("option", { value: "name", children: "name" }), _jsx("option", { value: "updated", children: "updated" }), hasRatings && _jsx("option", { value: "rating", children: "rating" })] })] }), _jsxs("div", { class: "view-toggle", role: "group", "aria-label": "Catalog view", children: [_jsx("button", { type: "button", class: view === "cards" ? "view-pick active" : "view-pick", "data-slot": "filter-chip", "aria-pressed": view === "cards", title: "Cards", "aria-label": "Show packages as cards", onClick: () => setView("cards"), children: _jsx(LayoutGrid, { size: 15, "aria-hidden": "true" }) }), _jsx("button", { type: "button", class: view === "table" ? "view-pick active" : "view-pick", "data-slot": "filter-chip", "aria-pressed": view === "table", title: "List", "aria-label": "Show packages as a list", onClick: () => setView("table"), children: _jsx(List, { size: 15, "aria-hidden": "true" }) })] })] })] }), shown.length === 0 ? (_jsx("p", { class: "empty", children: "No packages match." })) : view === "table" ? (_jsx(PackageTable, { packages: shown, hasRatings: hasRatings, onKeyDown: onCardKeyDown, rootRef: gridRef })) : (_jsx("ul", { class: "grid", ref: (el) => {
+                                            // The pointer path only: see the handlers above.
+                                            if (pickedByPointer.current)
+                                                event.currentTarget.blur();
+                                        }, children: [_jsx("option", { value: "name", children: "name" }), _jsx("option", { value: "updated", children: "updated" }), hasRatings && _jsx("option", { value: "rating", children: "rating" }), _jsx("option", { value: "relevance", children: "relevance" })] })] }), _jsxs("div", { class: "view-toggle", role: "group", "aria-label": "Catalog view", children: [_jsx("button", { type: "button", class: view === "cards" ? "view-pick active" : "view-pick", "data-slot": "filter-chip", "aria-pressed": view === "cards", title: "Cards", "aria-label": "Show packages as cards", onClick: () => setView("cards"), children: _jsx(LayoutGrid, { size: 15, "aria-hidden": "true" }) }), _jsx("button", { type: "button", class: view === "table" ? "view-pick active" : "view-pick", "data-slot": "filter-chip", "aria-pressed": view === "table", title: "List", "aria-label": "Show packages as a list", onClick: () => setView("table"), children: _jsx(List, { size: 15, "aria-hidden": "true" }) })] })] })] }), shown.length === 0 ? (_jsx("p", { class: "empty", children: "No packages match." })) : view === "table" ? (_jsx(PackageTable, { packages: visible, hasRatings: hasRatings, onKeyDown: onCardKeyDown, rootRef: gridRef })) : (_jsx("ul", { class: "grid", ref: (el) => {
                     gridRef.current = el;
-                }, children: shown.map((p) => (_jsx(PackageCard, { pkg: p, vscodeExtension: vscodeExtension, activeKeywords: keywords, onToggleKeyword: toggleKeyword, onKeyDown: onCardKeyDown }, `${p.namespace}/${p.name}`))) }))] }));
+                }, children: visible.map((p) => (_jsx(PackageCard, { pkg: p, vscodeExtension: vscodeExtension, activeKeywords: keywords, onToggleKeyword: toggleKeyword, onKeyDown: onCardKeyDown }, `${p.namespace}/${p.name}`))) })), visible.length < shown.length && (_jsx("div", { ref: sentinelRef, "aria-hidden": "true" }))] }));
 }