@grimoire-rs/indexer 0.5.1 → 0.5.3

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

@@ -1,4 +1,5 @@
 import {
+  useCallback,
   useEffect,
   useLayoutEffect,
   useMemo,
@@ -17,7 +18,13 @@ import {
 import { PackageCard } from "./PackageCard.js";
 import { PackageRow } from "./PackageRow.js";
 import { keywordFrequency, selectRailKeywords } from "../lib/keywordRail.js";
-import { lastUpdated, type CatalogPackage } from "../lib/catalog.js";
+import { lastUpdated, type CardPackage } from "../lib/catalog.js";
+import { withBase } from "../lib/base.js";
+// TYPE-ONLY, and it has to stay that way: `../lib/search.js` is the only
+// module that pulls `fuzzysort` in, and it is loaded with `await import()`
+// below so neither reaches a reader who never types. A value import here
+// would fold both back into the island's own chunk.
+import type { Scores, SearchIndex } from "../lib/search.js";
 
 // Known kinds get stable chip ordering + badge colors; unknown kinds
 // (future schema growth) still render with a neutral badge.
@@ -28,7 +35,15 @@ function kindOrder(kind: string): number {
   return i === -1 ? KNOWN_KINDS.length : i;
 }
 
-export type Sort = "name" | "updated" | "rating";
+/**
+ * `relevance` orders by how well each package answered the query on screen,
+ * where the other three order by something every package carries. It is
+ * offered and stored like any of them even so: with no query it has nothing
+ * to rank, and `CHAINS.relevance` answers that with alphabetical — the order
+ * the catalog opens on anyway — so a reader can leave the catalog set to it
+ * and have every later search come back ranked without touching the control.
+ */
+export type Sort = "name" | "updated" | "rating" | "relevance";
 export type Dir = "asc" | "desc";
 /** Roomy cards, or the same packages as a scannable list. */
 export type View = "cards" | "table";
@@ -42,6 +57,11 @@ export type View = "cards" | "table";
  */
 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
@@ -62,9 +82,10 @@ export const NATURAL: Record<Sort, Dir> = {
   name: "asc",
   updated: "desc",
   rating: "desc",
+  relevance: "desc",
 };
 
-type Key = (a: CatalogPackage, b: CatalogPackage) => number;
+type Key = (a: CardPackage, b: CardPackage) => number;
 
 /**
  * Bigger first, with `null` as its own bucket underneath every number.
@@ -80,7 +101,7 @@ function descending(a: number | null, b: number | null): number {
 }
 
 /** `updated` as epoch ms; null when absent, empty or not a date at all. */
-function updatedAt(p: CatalogPackage): number | null {
+function updatedAt(p: CardPackage): number | null {
   const at = lastUpdated(p);
   const ms = at ? new Date(at).getTime() : NaN;
   return Number.isFinite(ms) ? ms : null;
@@ -115,6 +136,16 @@ const CHAINS: Record<Sort, Key[]> = {
   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
@@ -123,8 +154,8 @@ const CHAINS: Record<Sort, Key[]> = {
 // (`browse_sort.rs`) has no deprecated key either; keeping this comparator
 // silent on deprecation is what keeps the two in sync.
 export function compare(
-  a: CatalogPackage,
-  b: CatalogPackage,
+  a: CardPackage,
+  b: CardPackage,
   sort: Sort,
   dir: Dir = NATURAL[sort],
 ): number {
@@ -244,7 +275,7 @@ function PackageTable({
   onKeyDown,
   rootRef,
 }: {
-  packages: CatalogPackage[];
+  packages: CardPackage[];
   hasRatings: boolean;
   onKeyDown: (event: KeyboardEvent) => void;
   rootRef: { current: HTMLElement | null };
@@ -276,7 +307,7 @@ export default function Catalog({
   packages,
   vscodeExtension,
 }: {
-  packages: CatalogPackage[];
+  packages: CardPackage[];
   vscodeExtension: string | null;
 }) {
   // Empty on the first render, ALWAYS — `?q=…` is applied a beat later, in
@@ -313,8 +344,14 @@ export default function Catalog({
   // 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<SearchIndex | null>(null);
 
   const searchRef = useRef<HTMLInputElement>(null);
+  /** Whether the sort combo's last interaction came from a pointer. */
+  const pickedByPointer = useRef(false);
   const gridRef = useRef<HTMLElement>(null);
   const controlsRef = useRef<HTMLDivElement>(null);
 
@@ -334,8 +371,40 @@ export default function Catalog({
   ];
 
   const railRefs = useRef(new Map<string, HTMLElement>());
-  const railRects = useRef(new Map<string, DOMRect>());
+  /**
+   * 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<string, { x: number; y: number }>());
+  /** The slide each chip is currently running, so a new one can replace it. */
+  const railSlides = useRef(new WeakMap<HTMLElement, Animation>());
   const railRef = useRef<HTMLDivElement>(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<string | null>(null);
+  const railFlipped = useRef<string | null>(null);
 
   const kwMenuRef = useRef<HTMLDivElement>(null);
   const kwTriggerRef = useRef<HTMLButtonElement>(null);
@@ -409,35 +478,56 @@ export default function Catalog({
    */
   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") 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.
+    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<ResizeObserver | null>(null);
+  const attachRail = useCallback(
+    (el: HTMLDivElement | null) => {
+      railRef.current = el;
+      railObserver.current?.disconnect();
+      railObserver.current = null;
+      if (!el || typeof ResizeObserver === "undefined") return;
+      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();
   });
 
   /**
@@ -450,68 +540,91 @@ export default function Catalog({
    * 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;
-    const current = new Map<string, DOMRect>();
+    // 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<string, { x: number; y: number }>();
     const moved: { el: HTMLElement; dx: number; dy: number }[] = [];
-    // 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. */
@@ -565,7 +678,8 @@ export default function Catalog({
     const s = readPref("sort");
     const d = readPref("dir");
     const v = readPref("view");
-    const field: Sort = s === "updated" || s === "rating" ? s : "name";
+    const field: Sort =
+      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)));
@@ -855,26 +969,164 @@ export default function Catalog({
   }, [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: Scores | null = 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) => {
-    if (kinds.length > 0 && !kinds.includes(p.kind)) return false;
-    if (!keywords.every((kw) => p.keywords?.includes(kw))) return false;
-    if (!q) return true;
-    return [
-      p.name,
-      p.description ?? "",
-      p.namespace,
-      p.kind,
-      p.ref,
-      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));
+  //
+  // 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 ?? "",
+          p.namespace,
+          p.kind,
+          p.ref,
+          p.summary ?? "",
+          (p.keywords ?? []).join(" "),
+        ].some((field) => field.toLowerCase().includes(q));
+      }),
+    [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<HTMLDivElement>(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.
@@ -899,7 +1151,15 @@ export default function Catalog({
     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))
@@ -911,6 +1171,10 @@ export default function Catalog({
   // 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) ||
@@ -948,6 +1212,31 @@ export default function Catalog({
           <kbd class="search-hint" aria-hidden="true">
             /
           </kbd>
+          {/* Ours, in the hint's own box and its own place — the browser's
+              built-in `type="search"` clear button lands in the same corner
+              wearing the UA's styling, which belongs to no theme this site
+              has. It is hidden in CSS and this replaces it, so the corner
+              holds exactly one control that looks like the rest of the
+              toolbar: the key hint when the field is empty, the same box
+              carrying an X when it is not.
+
+              Focus goes back to the field rather than staying on a button
+              that is about to unmount — the same thing Escape already does
+              from in here. */}
+          {query && (
+            <button
+              type="button"
+              class="search-clear"
+              aria-label="Clear search"
+              title="Clear search"
+              onClick={() => {
+                setQuery("");
+                searchRef.current?.focus();
+              }}
+            >
+              <X size={12} aria-hidden="true" />
+            </button>
+          )}
         </div>
         {/* One row, three groups, in the order they narrow: what sort of
             thing, then what it is about, then what the catalog is
@@ -1001,7 +1290,7 @@ export default function Catalog({
                 class="chips kw-rail"
                 role="group"
                 aria-label="Filter by keyword"
-                ref={railRef}
+                ref={attachRail}
               >
                 {visibleKeywords.map(({ keyword }, i) => {
                   // Past the measured fit: still laid out, so the measurement
@@ -1222,6 +1511,40 @@ export default function Catalog({
               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 as HTMLSelectElement)
                   .value as Sort;
@@ -1230,11 +1553,14 @@ export default function Catalog({
                 // the previous one over lands the reader on "oldest first"
                 // because they had asked for Z→A a moment ago.
                 setDir(NATURAL[next]);
+                // The pointer path only: see the handlers above.
+                if (pickedByPointer.current) event.currentTarget.blur();
               }}
             >
               <option value="name">name</option>
               <option value="updated">updated</option>
               {hasRatings && <option value="rating">rating</option>}
+              <option value="relevance">relevance</option>
             </select>
           </div>
           {/* Beside sort, because it answers the same kind of question — how
@@ -1274,7 +1600,7 @@ export default function Catalog({
         <p class="empty">No packages match.</p>
       ) : view === "table" ? (
         <PackageTable
-          packages={shown}
+          packages={visible}
           hasRatings={hasRatings}
           onKeyDown={onCardKeyDown}
           rootRef={gridRef}
@@ -1286,7 +1612,7 @@ export default function Catalog({
             gridRef.current = el;
           }}
         >
-          {shown.map((p) => (
+          {visible.map((p) => (
             <PackageCard
               key={`${p.namespace}/${p.name}`}
               pkg={p}
@@ -1298,6 +1624,14 @@ export default function Catalog({
           ))}
         </ul>
       )}
+      {/* The sentinel. Outside the list rather than inside it, so it is not a
+          stray child of a `<ul>` whose children are all `<li>`, nor of the
+          table's grid where it would take a row of tracks. `aria-hidden`
+          because it is a scroll position, not content — the count above the
+          list is what tells a screen reader how many packages there are. */}
+      {visible.length < shown.length && (
+        <div ref={sentinelRef} aria-hidden="true" />
+      )}
     </section>
   );
 }