@grimoire-rs/indexer 0.4.3 → 0.5.0

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

@@ -1,12 +1,12 @@
-import { jsx as _jsx, jsxs as _jsxs } from "preact/jsx-runtime";
-import { useEffect, useLayoutEffect, useMemo, useRef, useState } from "preact/hooks";
-// Lucide (ISC) draws the UI; brand marks come from `@mdi/js`, which Lucide
-// deliberately does not carry. No SVG on this site is hand-written.
-import { ArrowBigUp, Check, FolderRoot, Globe, Image, ImageOff } from "lucide-preact";
-import { mdiMicrosoftVisualStudioCode } from "@mdi/js";
-import { BrandMark } from "./BrandMark.js";
-import { withBase } from "../lib/base.js";
-import { lastUpdated, timeAgo, vscodeUrl } from "../lib/catalog.js";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "preact/jsx-runtime";
+import { 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, } from "lucide-preact";
+import { PackageCard } from "./PackageCard.js";
+import { PackageRow } from "./PackageRow.js";
+import { keywordFrequency, selectRailKeywords } from "../lib/keywordRail.js";
+import { lastUpdated } from "../lib/catalog.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"];
@@ -14,6 +14,28 @@ function kindOrder(kind) {
     const i = KNOWN_KINDS.indexOf(kind);
     return i === -1 ? KNOWN_KINDS.length : i;
 }
+/**
+ * How many keyword chips the rail shows at once, actives included.
+ *
+ * Everything past it goes behind the overflow menu. The cap is the point:
+ * this catalog's keyword vocabulary is open-ended, and a rail that renders
+ * all of it is a wall of chips nobody reads.
+ */
+const KEYWORD_CHIP_LIMIT = 8;
+/**
+ * The direction each field is *worth* reading first in — A→Z for a name,
+ * newest and best-liked first for the two ranked keys.
+ *
+ * Picking a field selects its natural direction; the toggle beside the
+ * combo box reverses that. So "descending" is not a global default a reader
+ * has to correct on every mode, and the arrow always describes what the
+ * order actually is rather than which way a flag is set.
+ */
+export const NATURAL = {
+    name: "asc",
+    updated: "desc",
+    rating: "desc",
+};
 /**
  * Bigger first, with `null` as its own bucket underneath every number.
  *
@@ -38,7 +60,8 @@ function updatedAt(p) {
  * mode, and it is unique, so no two rows ever compare equal — a browse order
  * that is not total is a browse order that reshuffles on rebuild.
  */
-const byName = (a, b) => a.name.localeCompare(b.name, undefined, { sensitivity: "accent" }) || a.ref.localeCompare(b.ref);
+const byName = (a, b) => a.name.localeCompare(b.name, undefined, { sensitivity: "accent" }) ||
+    a.ref.localeCompare(b.ref);
 /**
  * Newest first. No usable date is *unknown*, not epoch 0: dating an undated
  * package to 1970 sorts it below real packages by accident rather than by
@@ -62,11 +85,14 @@ const CHAINS = {
 // any other row when the toggle brings them back. grim's own browse order
 // (`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, b, sort) {
+export function compare(a, b, sort, dir = NATURAL[sort]) {
     for (const key of CHAINS[sort]) {
         const d = key(a, b);
+        // Reversed means reversed all the way down, the ref tiebreak included.
+        // Every chain ends on a unique key, so no two rows compare equal and
+        // negating the whole answer leaves the order just as total as it was.
         if (d !== 0)
-            return d;
+            return dir === NATURAL[sort] ? d : -d;
     }
     return 0;
 }
@@ -74,12 +100,56 @@ export function compare(a, b, sort) {
 // codicons so "project" and "global" read identically in both. That parity
 // is gone on purpose: every icon now comes from one set. `FolderRoot` and
 // `Globe` are the nearest Lucide equivalents and carry the same meaning.
+/**
+ * The reader's own preferences, kept out of the URL.
+ *
+ * The split is deliberate and matches grim: `q`, `kind` and `kw` are *what
+ * you are looking at* — a keyword chip on a package page links to
+ * `/?kw=<keyword>`, so that half has to stay shareable — while sort,
+ * direction, deprecated visibility and the cards/table choice are *how you
+ * like the catalog arranged*, the same answer on every visit. grim keeps
+ * `show_deprecated` in its config file for exactly that reason.
+ *
+ * Both accessors swallow: reading `localStorage` throws outright, not
+ * returns null, in a browser set to block site data, and a catalog is not
+ * worth a blank page. A reader who blocks it browses without preferences.
+ */
+const PREF = "grim.catalog.";
+function readPref(key) {
+    try {
+        return localStorage.getItem(PREF + key);
+    }
+    catch {
+        return null;
+    }
+}
+function writePref(key, value) {
+    try {
+        if (value === null)
+            localStorage.removeItem(PREF + key);
+        else
+            localStorage.setItem(PREF + key, value);
+    }
+    catch {
+        // Nothing to do and nothing to report: preferences are a convenience.
+    }
+}
+/**
+ * A comma-joined URL parameter, back into the list it was.
+ *
+ * Empty and absent are the same answer — `?kind=` is a reader who cleared
+ * the filter, not a request for the kind named "". Duplicates collapse so a
+ * hand-edited `?kw=a,a` cannot render the same chip twice.
+ */
+function list(value) {
+    return [...new Set((value ?? "").split(",").filter(Boolean))];
+}
 /** Typing inside one of these means a bare keystroke is text, not a shortcut. */
 function isTyping(el) {
     const node = el;
     if (!node)
         return false;
-    return node.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(node.tagName);
+    return (node.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(node.tagName));
 }
 /**
  * How many cards the grid actually laid out per row.
@@ -87,6 +157,10 @@ function isTyping(el) {
  * Measured, not read from CSS: the track list is `auto-fill` with a minimum
  * width, so the count is a layout outcome that depends on the viewport. The
  * first card whose top edge drops below the first row's starts row two.
+ *
+ * The table view needs no branch of its own — its rows stack, so the second
+ * one is already below the first and this measures the 1 that makes every
+ * arrow key move by a single row.
  */
 function columnCount(cards) {
     if (cards.length < 2)
@@ -96,69 +170,33 @@ function columnCount(cards) {
     return wrapped === -1 ? cards.length : wrapped;
 }
 /**
- * The card's 28px logo slot, in its three states.
+ * The same packages as a list, for reading down a column rather than across
+ * a grid.
+ *
+ * **A row is an anchor, and there is no `<table>`.** Two reasons, and the
+ * first is the load-bearing one: a header row that cannot sort is a header
+ * row that *looks* like it sorts — every reader who has met a data table
+ * clicks it once. Sorting lives in the toolbar, so the table has no headers,
+ * and a headerless table has no column semantics left to justify the element.
+ * What remains is a list of links, which is what this is. A CSS grid with
+ * `subgrid` rows keeps the columns aligned without the markup.
  *
- * The third one is the reason this is a component rather than inline JSX: a
- * package can declare a `logo` whose file is not actually served — the
- * enrich step failed, the asset was pruned, the path is stale — and the
- * browser's own broken-image glyph is both ugly and says nothing. So a
- * declared-but-unreachable logo degrades to a marked placeholder, which is
- * deliberately *not* the same as the initial-letter tile a package with no
- * logo at all gets: one is a fault worth seeing, the other is normal.
+ * The anchor is also what makes the whole row clickable, focusable and
+ * middle-clickable for free — no stretched-link overlay, no synthetic Enter
+ * handler. A row carries no controls of its own: the install buttons and the
+ * vote links are what the card exists for, and repeating them per row would
+ * be five columns of icons. The detail page has all of them.
  *
- * The static detail page needs the same treatment but cannot use `onError`,
- * so it opts into the global handler in `Base.astro` instead — keep the two
- * placeholders looking alike.
+ * Columns are fixed, unlike the keyword rail above — deliberately. A column
+ * is a slot the eye tracks down; one that appears and disappears as the
+ * filters change destroys the alignment the table exists to give. The rating
+ * column is the one exception, and it is decided once per index rather than
+ * per filter.
  */
-function CardLogo({ pkg }) {
-    const [state, setState] = useState("loading");
-    const imgRef = useRef(null);
-    // The image is server-rendered, so the browser begins fetching it while
-    // parsing the HTML — long before this island hydrates. Two consequences,
-    // and the slot markup below answers both: `onError` can fire before any
-    // listener exists (the placeholder used to appear only sometimes), and a
-    // failed image paints the browser's broken glyph on the way (the flash on
-    // reload). Starting the image hidden means nothing is ever shown until it
-    // is known to be good.
-    //
-    // `complete` says the browser finished, not how it went. `decode()` is
-    // what separates the two: it rejects for a failure and resolves for a good
-    // image — including an SVG with no intrinsic size, where the usual
-    // `naturalWidth === 0` test reports a false failure. Gating on `complete`
-    // means it never starts a fetch, so `loading="lazy"` still holds off
-    // -screen cards.
-    useEffect(() => {
-        setState("loading");
-        const img = imgRef.current;
-        if (!img?.complete)
-            return;
-        let live = true;
-        img.decode().then(() => live && setState("ready"), () => live && setState("broken"));
-        return () => {
-            live = false;
-        };
-    }, [pkg.logo]);
-    if (!pkg.logo) {
-        return (_jsx("span", { class: "card-logo card-logo-fallback", "aria-hidden": "true", style: { background: `var(--grim-color-kind-${pkg.kind}, var(--grim-color-muted))` }, children: pkg.name[0]?.toUpperCase() }));
-    }
-    return (_jsxs("span", { class: "card-logo logo-slot", "data-state": state, role: state === "broken" ? "img" : undefined, "aria-label": state === "broken" ? "Logo image unavailable" : undefined, title: state === "broken" ? "Logo image unavailable" : undefined, children: [state === "broken" ? (_jsx(ImageOff, { class: "logo-mark", "aria-hidden": "true" })) : (_jsx(Image, { class: "logo-mark", "aria-hidden": "true" })), _jsx("img", { ref: imgRef, src: withBase(pkg.logo), alt: "", loading: "lazy", onLoad: () => setState("ready"), onError: () => setState("broken") })] }));
-}
-function CopyButton({ command, variant = "default", name, }) {
-    const [copied, setCopied] = useState(false);
-    const copy = () => {
-        navigator.clipboard.writeText(command).then(() => {
-            setCopied(true);
-            // The toast lives in Base.astro's inline script, outside this island —
-            // an event is how a hydrated component reaches it without either side
-            // importing the other.
-            document.dispatchEvent(new CustomEvent("grimoire:copied", { detail: { name, value: command } }));
-            setTimeout(() => setCopied(false), 1500);
-        });
-    };
-    return (_jsx("button", { type: "button", class: copied ? "copy copied" : "copy", title: command, "aria-label": `Copy: ${command}`, 
-        // Out of the Tab sequence: the card is the stop, and the same command
-        // is copyable from the detail page Enter opens.
-        tabIndex: -1, onClick: copy, children: copied ? _jsx(Check, { size: 14 }) : variant === "global" ? _jsx(Globe, { size: 14 }) : _jsx(FolderRoot, { size: 14 }) }));
+function PackageTable({ packages, hasRatings, onKeyDown, rootRef, }) {
+    return (_jsx("div", { class: hasRatings ? "table rated" : "table", "data-slot": "package-table", ref: (el) => {
+            rootRef.current = el;
+        }, children: packages.map((p) => (_jsx(PackageRow, { pkg: p, hasRatings: hasRatings, onKeyDown: onKeyDown }, `${p.namespace}/${p.name}`))) }));
 }
 // `vscodeExtension` arrives as a prop, not from lib/data: this island
 // hydrates in the browser, so importing the build-time payload here would
@@ -179,19 +217,143 @@ export default function Catalog({ packages, vscodeExtension, }) {
     // Whether the URL's query has been applied. Gates the reveal below, so the
     // catalog is never unhidden while it still shows the unfiltered list.
     const [seeded, setSeeded] = useState(false);
-    const [kind, setKind] = useState(null);
+    // Kinds combine with OR, keywords with AND, and the two groups with each
+    // other. That is not an inconsistency, it follows from the data: a package
+    // has exactly one kind, so requiring both of two kinds always yields
+    // nothing, while it carries many keywords, so requiring both of two is the
+    // only reading under which a second click narrows. A facet whose second
+    // click *widens* the result set reads as broken.
+    const [kinds, setKinds] = useState([]);
+    const [keywords, setKeywords] = useState([]);
     const [sort, setSort] = useState("name");
+    // Direction, not "reversed": what the arrow draws is the order itself.
+    const [dir, setDir] = useState(NATURAL.name);
     // Deprecated packages are hidden until asked for: a retired package is
     // noise for someone browsing what to install, and the publisher already
     // said as much by deprecating it.
     const [showDeprecated, setShowDeprecated] = useState(false);
+    const [view, setView] = useState("cards");
+    // Local to the overflow menu and deliberately not shareable: it narrows
+    // the list of keywords, not the catalog.
+    const [keywordFilter, setKeywordFilter] = useState("");
     const searchRef = useRef(null);
     const gridRef = useRef(null);
     const controlsRef = useRef(null);
-    const cardsOf = () => [...(gridRef.current?.querySelectorAll("li.card") ?? [])];
+    // Both views, one selector: a table row is the Tab stop its card is, so
+    // every keyboard path below — the search hatch, ArrowDown out of the
+    // chips, Escape's blur — works in either without knowing which is up.
+    const cardsOf = () => [
+        ...(gridRef.current?.querySelectorAll("li.card, a.row") ?? []),
+    ];
+    // Clipped keyword chips are excluded: they are drawn as nothing, so an
+    // arrow key that landed on one would move focus somewhere the reader
+    // cannot see it.
     const chipsOf = () => [
-        ...(controlsRef.current?.querySelectorAll("button.chip") ?? []),
+        ...(controlsRef.current?.querySelectorAll('button.chip:not([aria-hidden="true"])') ?? []),
     ];
+    const railRefs = useRef(new Map());
+    const railRects = useRef(new Map());
+    const railRef = useRef(null);
+    /**
+     * How many keyword chips actually fit on the row, measured.
+     *
+     * Not a constant, because the answer is a layout outcome: the rail is the
+     * one flexible child of the filter row, so its width is whatever the kinds,
+     * the overflow menu and the deprecated toggle left, and the chips are as
+     * wide as the words publishers wrote. `KEYWORD_CHIP_LIMIT` bounds how many
+     * are *offered*; this is how many are shown.
+     *
+     * The rule it enforces: the rail never wraps and never scrolls. A second
+     * row makes the toolbar a different height on every filter click, and a
+     * scrollbar hides the chips behind a gesture nobody looks for — it also
+     * pushed the overflow menu off the end of the row entirely.
+     *
+     * Every chip stays in the flow whatever this says; the ones past it are
+     * drawn as nothing (see `.chip.kw.clipped`). Taking them out of the flow
+     * would free the width that excluded them, which is a measurement that
+     * disagrees with itself on every other frame.
+     */
+    const [railFit, setRailFit] = useState(KEYWORD_CHIP_LIMIT);
+    useLayoutEffect(() => {
+        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.
+    });
+    /**
+     * FLIP for the keyword rail: chips slide to their new places instead of
+     * teleporting.
+     *
+     * The rail is rescored against the current result set, so it reorders on
+     * every click — the chip just picked moves to the front and the rest flow
+     * around it. Animating that is not decoration: a rail whose contents change
+     * 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.
+     */
+    useLayoutEffect(() => {
+        const previous = railRects.current;
+        const current = new Map();
+        const moved = [];
+        for (const [keyword, el] of railRefs.current) {
+            const rect = el.getBoundingClientRect();
+            current.set(keyword, rect);
+            const was = previous.get(keyword);
+            if (!was)
+                continue;
+            const dx = was.left - rect.left;
+            const dy = was.top - rect.top;
+            if (dx !== 0 || dy !== 0)
+                moved.push({ el, dx, dy });
+        }
+        railRects.current = current;
+        if (moved.length === 0)
+            return;
+        for (const { el, dx, dy } of moved) {
+            el.style.transition = "none";
+            el.style.translate = `${dx}px ${dy}px`;
+        }
+        const frame = requestAnimationFrame(() => {
+            for (const { el } of moved) {
+                el.style.transition = "";
+                el.style.translate = "";
+            }
+        });
+        return () => cancelAnimationFrame(frame);
+    });
     /** Move focus `delta` cards along, clamping at both ends rather than wrapping. */
     const focusCard = (from, delta) => {
         const cards = cardsOf();
@@ -218,17 +380,90 @@ export default function Catalog({ packages, vscodeExtension, }) {
         input.select();
         input.scrollIntoView({
             block: "start",
-            behavior: matchMedia("(prefers-reduced-motion: reduce)").matches ? "auto" : "smooth",
+            behavior: matchMedia("(prefers-reduced-motion: reduce)").matches
+                ? "auto"
+                : "smooth",
         });
     };
-    // Apply `?q=…`, now that hydration has matched the server's markup and
-    // Preact owns the tree. A layout effect rather than a plain one: the
+    /**
+     * Put the reader's view into state — the query from the URL, the
+     * preferences from storage. Neither half was there before, and the missing
+     * preference half is what made a deprecated package unreachable by Back:
+     * you turned the toggle on, opened the package, came back, and the
+     * remounted catalog knew nothing about it, so the card you had just been
+     * looking at was hidden again.
+     *
+     * Unknown values are dropped rather than trusted at both doors: `kind`
+     * reaches a class name, `kw` reaches a chip that stays on screen until it
+     * is clicked off, and `sort` selects a comparator, so none of them follows
+     * a hand-typed URL or a hand-edited storage entry anywhere the controls
+     * cannot go. `kw` is checked against the catalog's own vocabulary rather
+     * than a fixed list, since keywords are whatever publishers wrote.
+     */
+    const applyView = () => {
+        const params = new URLSearchParams(location.search);
+        const s = readPref("sort");
+        const d = readPref("dir");
+        const v = readPref("view");
+        const field = s === "updated" || s === "rating" ? 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)));
+        setKeywords(list(params.get("kw")).filter((k) => published.has(k)));
+        setSort(field);
+        setDir(d === "asc" || d === "desc" ? d : NATURAL[field]);
+        // A flag: stored at all means on.
+        setShowDeprecated(readPref("deprecated") !== null);
+        setView(v === "table" ? "table" : "cards");
+    };
+    // Apply the URL's view, now that hydration has matched the server's markup
+    // and Preact owns the tree. A layout effect rather than a plain one: the
     // resulting render must land before the browser paints, or a `?q=` visitor
     // sees the whole catalog flash past on the way to their results.
     useLayoutEffect(() => {
-        setQuery(new URLSearchParams(location.search).get("q") ?? "");
+        applyView();
         setSeeded(true);
     }, []);
+    // Back and Forward within the catalog — a keyword chip on a package page
+    // links to `/?q=…`, so the reader can land here more than once without a
+    // reload, and `popstate` is the only notice of it.
+    useEffect(() => {
+        const onPop = () => applyView();
+        addEventListener("popstate", onPop);
+        return () => removeEventListener("popstate", onPop);
+    }, []);
+    // The query, into the URL — so it can be shared, and so Back lands on the
+    // search the reader left. `replaceState`, not `pushState`: a history entry
+    // per keystroke would make Back mean "undo one letter" rather than "the
+    // page I came from". Gated on `seeded`, since writing before the URL has
+    // been read would erase a deep link on arrival.
+    useEffect(() => {
+        if (!seeded)
+            return;
+        const params = new URLSearchParams(location.search);
+        const set = (key, value) => value === null ? params.delete(key) : params.set(key, value);
+        set("q", query || null);
+        set("kind", kinds.length > 0 ? kinds.join(",") : null);
+        set("kw", keywords.length > 0 ? keywords.join(",") : null);
+        const search = params.toString();
+        const next = `${location.pathname}${search ? `?${search}` : ""}${location.hash}`;
+        if (next !== `${location.pathname}${location.search}${location.hash}`) {
+            history.replaceState(history.state, "", next);
+        }
+        // `keywords` is compared by identity, which is what we want: the array is
+        // replaced on every toggle and never mutated in place.
+    }, [seeded, query, kinds, keywords]);
+    // The preferences, into storage — so the next visit opens the way this one
+    // ended. Each is stored only when it is not the default, so a reader who
+    // never touched a control leaves nothing behind.
+    useEffect(() => {
+        if (!seeded)
+            return;
+        writePref("sort", sort === "name" ? null : sort);
+        writePref("dir", dir === NATURAL[sort] ? null : dir);
+        writePref("deprecated", showDeprecated ? "1" : null);
+        writePref("view", view === "cards" ? null : view);
+    }, [seeded, sort, dir, showDeprecated, view]);
     // Base.astro hides the catalog before first paint when the URL carries a
     // query. Reveal it only once the filtered render is in the DOM — keyed on
     // `seeded`, so the unfiltered first render is never the one revealed.
@@ -282,28 +517,38 @@ export default function Catalog({ packages, vscodeExtension, }) {
             const active = document.activeElement;
             // Also true for a control *inside* a card, which is still the card
             // being selected as far as the reader is concerned.
-            const card = active instanceof HTMLElement ? active.closest("li.card") : null;
-            if (!query && kind === null && !card)
-                return; // nothing selected: not our key
+            const card = active instanceof HTMLElement ? active.closest("li.card, a.row") : null;
+            // Nothing selected: not our key.
+            if (!query && kinds.length === 0 && keywords.length === 0 && !card)
+                return;
             event.preventDefault();
             setQuery("");
-            setKind(null);
+            setKinds([]);
+            setKeywords([]);
             if (card)
                 active.blur();
         };
         document.addEventListener("keydown", onEscape);
         return () => document.removeEventListener("keydown", onEscape);
-    }, [query, kind]);
+    }, [query, kinds, keywords]);
+    /** Both facets toggle the same way; only the relation between values differs. */
+    const toggle = (set) => (value) => set((was) => was.includes(value) ? was.filter((v) => v !== value) : [...was, value]);
+    const toggleKind = toggle(setKinds);
+    // Appends rather than inserts, so the pinned chips below stay in the order
+    // they were picked — the rail reorders underneath them, the actives do not.
+    const toggleKeyword = toggle(setKeywords);
     /**
-     * The filter and sort chips are not Tab stops — Tab is reserved for
-     * crossing the catalog, so it runs search → card → card. The chips sit in
-     * the row above the grid, so they are reached the way that row is:
-     * ArrowUp out of the top card row, ArrowDown back into it.
+     * Arrow keys move *across* a rail the reader is already standing in. They
+     * are not Tab's replacement, and this is the correction of a real defect:
+     * the chips used to carry `tabIndex={-1}` whenever the grid had anything
+     * in it, which left filtering reachable by pointer and arrow key only.
+     * That is a WCAG 2.1.1 (A) failure — every control has to be operable from
+     * the keyboard through the ordinary sequence, and an undocumented arrow
+     * convention is not that sequence. The sibling `@ocx-sh/catalog` renderer
+     * shipped the same shortcut and reverted it for the same reason.
      *
-     * The one case that would strand them is an empty result set, where there
-     * is no card to arrow up from — so with nothing shown they rejoin the Tab
-     * order (see `chipTabIndex` below), which is also exactly when a reader
-     * needs them most.
+     * So the chips are ordinary Tab stops now, and ArrowUp/ArrowDown remain as
+     * the faster way to cross a long rail or drop back into the grid.
      */
     const onChipKeyDown = (event) => {
         const chips = chipsOf();
@@ -334,7 +579,33 @@ export default function Catalog({ packages, vscodeExtension, }) {
             event.preventDefault();
             cardsOf()[0]?.focus();
         }
-        else if (event.key === "Escape" && !query && kind === null) {
+        else if (event.key === "Tab" &&
+            !event.shiftKey &&
+            !event.metaKey &&
+            !event.ctrlKey &&
+            !event.altKey) {
+            // The hatch. Everything between the field and the grid — sort, the
+            // view toggle, every chip — sits after it in the DOM and is a real Tab
+            // stop again, so plain Tab would walk the whole toolbar before
+            // reaching a single package. Forward Tab skips to the results; the
+            // toolbar stays reachable by Shift+Tab back out of the grid.
+            //
+            // Reordering the DOM instead would have put focus order at odds with
+            // visual order, which is the worse defect of the two.
+            //
+            // With nothing to jump to — an empty result set — Tab is left alone
+            // rather than swallowed: trapping focus in the field is worse than the
+            // walk it was meant to save.
+            const first = cardsOf()[0];
+            if (!first)
+                return;
+            event.preventDefault();
+            first.focus();
+        }
+        else if (event.key === "Escape" &&
+            !query &&
+            kinds.length === 0 &&
+            keywords.length === 0) {
             // Clearing is the document handler's job; this is only the second
             // press, once there is nothing left to clear — so Escape leaves the
             // field rather than being a dead key.
@@ -382,6 +653,11 @@ export default function Catalog({ packages, vscodeExtension, }) {
                 // mouse must keep its own Space/Enter behaviour.
                 if (event.target !== card)
                     return;
+                // A table row *is* an anchor, so Enter is the browser's to handle —
+                // swallowing it here would break activation rather than provide it.
+                // Only the card needs its title link clicked on its behalf.
+                if (card instanceof HTMLAnchorElement)
+                    return;
                 event.preventDefault();
                 card.querySelector("h2 a")?.click();
                 return;
@@ -393,18 +669,24 @@ export default function Catalog({ packages, vscodeExtension, }) {
     // deprecated entries drop out of those totals too while they are hidden,
     // so no count ever promises more than the grid shows.
     const counted = useMemo(() => (showDeprecated ? packages : packages.filter((p) => !p.deprecated)), [packages, showDeprecated]);
-    const kinds = useMemo(() => {
-        const counts = new Map();
-        for (const p of counted)
-            counts.set(p.kind, (counts.get(p.kind) ?? 0) + 1);
-        return [...counts.entries()].sort((a, b) => kindOrder(a[0]) - kindOrder(b[0]) || a[0].localeCompare(b[0]));
+    // Which kinds this catalog publishes, in chip order. No counts on the
+    // chips: they cost every chip the width of a number, which is width the
+    // keyword rail beside them needs more, and the meta row already states how
+    // many packages the filters left. A per-chip count is also the harder one
+    // to read honestly — kinds are an OR group, so a count taken after the
+    // filter says "3" about a chip that is about to reveal thirty.
+    const kindNames = useMemo(() => {
+        const seen = new Set(counted.map((p) => p.kind));
+        return [...seen].sort((a, b) => kindOrder(a) - kindOrder(b) || a.localeCompare(b));
     }, [counted]);
     const q = query.trim().toLowerCase();
-    // Query and kind first, deprecation last — so the toggle can report how
+    // 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 (kind && p.kind !== kind)
+        if (kinds.length > 0 && !kinds.includes(p.kind))
+            return false;
+        if (!keywords.every((kw) => p.keywords?.includes(kw)))
             return false;
         if (!q)
             return true;
@@ -418,16 +700,93 @@ export default function Catalog({ packages, vscodeExtension, }) {
             (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));
+    const shown = (showDeprecated ? matching : matching.filter((p) => !p.deprecated)).sort((a, b) => compare(a, b, sort, dir));
+    /**
+     * The keyword rail, over what is on screen rather than over the catalog.
+     *
+     * Two decisions, both borrowed from `@ocx-sh/catalog` and both load-bearing:
+     *
+     * Active keywords are **pinned**, first and in the order they were clicked,
+     * and never scored. A filter that scrolls out of the rail is a filter the
+     * reader cannot lift. Their count is `shown.length` by construction — under
+     * AND, every surviving package carries every active keyword.
+     *
+     * The rest are picked by splitting power over `shown`, not by frequency
+     * over `packages`. A rail scored against the whole catalog keeps offering
+     * keywords no surviving package carries, and under AND that is most of
+     * them — every such chip is one click to an empty grid.
+     *
+     * The cost, accepted: the rail's contents move as the reader filters, which
+     * is what the FLIP effect above animates. The set changing invisibly is
+     * what would read as broken.
+     */
+    const pinned = keywords.map((keyword) => ({
+        keyword,
+        count: shown.length,
+    }));
+    const rail = selectRailKeywords(shown, KEYWORD_CHIP_LIMIT)
+        // `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))
+        .slice(0, Math.max(0, KEYWORD_CHIP_LIMIT - pinned.length));
+    const visibleKeywords = [...pinned, ...rail];
+    // What the menu has to carry: everything the rail had no slot for, plus
+    // everything it has a slot for but no ROOM for. The second half is why the
+    // menu is built from `railFit` rather than from `KEYWORD_CHIP_LIMIT` — a
+    // 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);
+    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
+    // looking at, and every entry in it is one short known word.
+    const menuShown = menuKeywords.filter((k) => k.keyword.toLowerCase().includes(keywordFilter.trim().toLowerCase()));
     // A catalog with nothing deprecated gets no toggle — a control that can
     // only ever be a no-op is worse than its absence. An index that publishes
     // no ratings gets no rating chip for the same reason.
     const hasDeprecated = packages.some((p) => p.deprecated);
     const hasRatings = packages.some((p) => p.rating);
-    // Chips leave the Tab order only while there is a grid to arrow up from.
-    const chipTabIndex = shown.length === 0 ? 0 : -1;
-    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 ${counted.length} packages…`, 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: "chips", role: "group", "aria-label": "Sort by", children: [_jsx("button", { type: "button", class: sort === "name" ? "chip active" : "chip", "data-slot": "filter-chip", tabIndex: chipTabIndex, onKeyDown: onChipKeyDown, onClick: () => setSort("name"), children: "name" }), _jsx("button", { type: "button", class: sort === "updated" ? "chip active" : "chip", "data-slot": "filter-chip", tabIndex: chipTabIndex, onKeyDown: onChipKeyDown, onClick: () => setSort("updated"), children: "updated" }), hasRatings && (_jsx("button", { type: "button", class: sort === "rating" ? "chip active" : "chip", "data-slot": "filter-chip", tabIndex: chipTabIndex, onKeyDown: onChipKeyDown, onClick: () => setSort("rating"), children: "rating" }))] }), _jsx("span", { class: "chip-sep", "aria-hidden": "true" }), _jsxs("div", { class: "chips", role: "group", "aria-label": "Filter by kind", children: [_jsxs("button", { type: "button", class: kind === null ? "chip active" : "chip", "data-slot": "filter-chip", tabIndex: chipTabIndex, onKeyDown: onChipKeyDown, onClick: () => setKind(null), children: ["all ", _jsx("small", { children: counted.length })] }), kinds.map(([k, count]) => (_jsxs("button", { type: "button", class: kind === k ? `chip active kind-${k}` : `chip kind-${k}`, "data-slot": "filter-chip", tabIndex: chipTabIndex, onKeyDown: onChipKeyDown, onClick: () => setKind(kind === k ? null : k), children: [k, " ", _jsx("small", { children: count })] }, k)))] }), hasDeprecated && (_jsx("button", { type: "button", class: showDeprecated ? "chip deprecated-toggle active" : "chip deprecated-toggle", "aria-pressed": showDeprecated, title: showDeprecated ? "Hide deprecated packages" : "Show deprecated packages", tabIndex: chipTabIndex, onKeyDown: onChipKeyDown, onClick: () => setShowDeprecated((on) => !on), children: "deprecated" }))] }), shown.length === 0 ? (_jsx("p", { class: "empty", children: "No packages match." })) : (_jsx("ul", { class: "grid", ref: gridRef, children: shown.map((p) => (_jsxs("li", { class: "card", "data-slot": "package-card", tabIndex: 0, onKeyDown: onCardKeyDown, children: [_jsxs("div", { class: "card-head", children: [_jsx(CardLogo, { pkg: p }), _jsx("h2", { "data-slot": "package-name", children: _jsx("a", { href: withBase(`/p/${p.namespace}/${p.name}/`), tabIndex: -1, children: p.name }) }), p.deprecated ? (_jsx("span", { class: "badge deprecated", "data-slot": "package-kind", children: "deprecated" })) : (_jsx("span", { class: `badge kind-${p.kind}`, "data-slot": "package-kind", children: p.kind }))] }), _jsx("p", { class: "namespace", children: p.namespace }), (p.version || p.license || lastUpdated(p) || p.rating) && (_jsxs("div", { class: "meta-row", "data-slot": "package-meta", children: [p.version && _jsxs("span", { class: "pill version", children: ["v", p.version] }), p.license && _jsx("span", { class: "pill license", children: p.license }), p.rating && (_jsxs("span", { class: "pill rating", title: `${p.rating.up} upvote${p.rating.up === 1 ? "" : "s"}`, children: [_jsx(ArrowBigUp, { size: 13, "aria-hidden": "true" }), p.rating.up] })), (() => {
-                                    const at = lastUpdated(p);
-                                    return at && timeAgo(at) ? (_jsxs("time", { class: "updated", datetime: at, title: at, children: ["updated ", timeAgo(at)] })) : null;
-                                })()] })), p.deprecated && (_jsxs("p", { class: "deprecated-strip", children: ["deprecated", p.replacedBy ? ` — replaced by ${p.replacedBy}` : ""] })), p.description && _jsx("p", { class: "description", children: p.description }), p.keywords && p.keywords.length > 0 && (_jsxs("div", { class: "keywords", "data-slot": "package-keywords", children: [p.keywords.slice(0, 5).map((kw) => (_jsx("button", { type: "button", class: "chip keyword", tabIndex: -1, onClick: () => setQuery(kw), children: kw }, kw))), p.keywords.length > 5 && (_jsxs("span", { class: "chip keyword overflow", children: ["+", p.keywords.length - 5] }))] })), _jsxs("div", { class: "card-foot", children: [_jsxs("div", { class: "copy-group", children: [_jsx(CopyButton, { command: `grim add --global ${p.ref}`, variant: "global", name: `global add for ${p.name}` }), _jsx(CopyButton, { command: `grim add ${p.ref}`, name: `project add for ${p.name}` }), vscodeUrl(vscodeExtension, p.ref) && (_jsx("a", { class: "copy vscode", href: vscodeUrl(vscodeExtension, p.ref), title: "Open in VS Code", "aria-label": `Open ${p.name} in VS Code`, tabIndex: -1, children: _jsx(BrandMark, { path: mdiMicrosoftVisualStudioCode }) }))] }), p.repository && (_jsx("a", { class: "source", href: p.repository, target: "_blank", rel: "noopener noreferrer", tabIndex: -1, children: "source" }))] })] }, `${p.namespace}/${p.name}`))) }))] }));
+    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) => {
+                                            // 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
+                                            // instead would free the width that excluded it, which is
+                                            // the oscillation this shape exists to avoid.
+                                            const clipped = i >= railFit;
+                                            return (_jsx("button", { ref: (el) => {
+                                                    // The FLIP effect measures whatever is in this map, so
+                                                    // a chip that leaves has to leave the map with it —
+                                                    // Preact calls back with null on unmount for that.
+                                                    if (el)
+                                                        railRefs.current.set(keyword, el);
+                                                    else
+                                                        railRefs.current.delete(keyword);
+                                                }, type: "button", class: [
+                                                    "chip kw",
+                                                    keywords.includes(keyword) ? "active" : "",
+                                                    clipped ? "clipped" : "",
+                                                ]
+                                                    .filter(Boolean)
+                                                    .join(" "), "data-slot": "filter-chip", "aria-pressed": keywords.includes(keyword), "aria-hidden": clipped ? "true" : undefined, tabIndex: clipped ? -1 : undefined, onKeyDown: onChipKeyDown, onClick: () => toggleKeyword(keyword), children: keyword }, keyword));
+                                        }) })] })), menuKeywords.length > 0 && (_jsxs("details", { class: "kw-menu", children: [_jsxs("summary", { class: "chip", "data-slot": "filter-chip", children: ["+", menuKeywords.length, " more"] }), _jsxs("div", { class: "kw-menu-panel", children: [_jsx("input", { type: "text", class: "kw-menu-search", placeholder: "Filter keywords\u2026", "aria-label": "Filter keywords", value: keywordFilter, onInput: (e) => setKeywordFilter(e.target.value) }), _jsxs("div", { class: "kw-menu-list", children: [menuShown.map(({ keyword, count }) => (_jsxs("button", { type: "button", class: "kw-menu-item", onClick: () => toggleKeyword(keyword), children: [_jsx("span", { children: keyword }), _jsx("small", { children: count })] }, keyword))), menuShown.length === 0 && (_jsx("p", { class: "kw-menu-empty", children: "No keyword matches." }))] })] })] })), hasDeprecated && (_jsx("button", { type: "button", class: showDeprecated
+                                    ? "chip deprecated-toggle active"
+                                    : "chip deprecated-toggle", "aria-pressed": showDeprecated, title: showDeprecated
+                                    ? "Hide deprecated packages"
+                                    : "Show deprecated packages", onKeyDown: onChipKeyDown, onClick: () => setShowDeprecated((on) => !on), children: "deprecated" }))] }), _jsxs("div", { class: "meta-row", children: [_jsx("p", { class: "result-count", role: "status", "aria-atomic": "true", children: shown.length === counted.length
+                                    ? `${counted.length} packages`
+                                    : `${shown.length} of ${counted.length} packages` }), _jsxs("div", { class: "sort-group", role: "group", "aria-label": "Sort by", children: [_jsx("button", { type: "button", class: "sort-dir", "data-slot": "filter-chip", title: dir === "asc"
+                                            ? "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) => {
+                                            const next = event.currentTarget
+                                                .value;
+                                            setSort(next);
+                                            // Picking a field takes that field's own direction. Carrying
+                                            // 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) => {
+                    gridRef.current = el;
+                }, children: shown.map((p) => (_jsx(PackageCard, { pkg: p, vscodeExtension: vscodeExtension, activeKeywords: keywords, onToggleKeyword: toggleKeyword, onKeyDown: onCardKeyDown }, `${p.namespace}/${p.name}`))) }))] }));
 }