@grimoire-rs/indexer 0.3.2 → 0.4.0

package/dist/ratings/seed.d.ts

@@ -0,0 +1,60 @@
+/** The `stats.json` version this producer writes. */
+export declare const SCHEMA_VERSION = 1;
+/**
+ * Where a run leaves the sidecar in the repository root. The renderer reads it
+ * at build time and the deploy publishes it as `stats.json`; it is never
+ * committed, so a rollback is *both* dropping the `ratings` block and deleting
+ * the published file (S-016) — the last tally is otherwise served forever.
+ */
+export declare const STATS_FILE = ".stats.json";
+/** One ref's bag of stats — `{ rating: {...}, downloads: {...} }`. Values are opaque here. */
+export type StatEntries = Record<string, Record<string, unknown>>;
+/**
+ * The carry-forward surface of a published `stats.json`: the two maps that are
+ * keyed by stat name and must therefore survive a run that did not produce
+ * that stat. Everything else in the document (`schema_version`,
+ * `generated_at`) is re-derived, never carried.
+ */
+export interface StatsSeed {
+    /** Which backend produced each signal, keyed by stat name. */
+    providers: Record<string, string>;
+    entries: StatEntries;
+}
+/** The complete published document. */
+export interface StatsDocument extends StatsSeed {
+    schema_version: number;
+    generated_at: string;
+}
+/** The first run's seed, and the only shape a genuine 404 may produce. */
+export declare const EMPTY_SEED: StatsSeed;
+/**
+ * Fetch the currently published `stats.json` to merge over.
+ *
+ * | Outcome | Behaviour |
+ * |---|---|
+ * | 404 | empty seed — the first run, and the normal case |
+ * | 2xx that parses | merge base |
+ * | 2xx that does not parse | **throws** (65) |
+ * | transport / TLS / 5xx / timeout / over-cap | **throws** (69) |
+ *
+ * `request()` maps its transport catch *and* its response-size cap to
+ * `{status: 0}`, so that value is a hard error here and can never be read as
+ * "the seed was fine and empty".
+ */
+export declare function loadSeed(url: string): Promise<StatsSeed>;
+/**
+ * Merge one completed producer's output over the seed, per stat key.
+ *
+ * `fresh` is keyed by ref and holds only this producer's stat value, so a ref
+ * absent from it had its key genuinely observed as empty — the key is dropped,
+ * which is correct *because this producer completed*. A producer that failed
+ * never reaches here at all, and the seed it would have merged over is what
+ * gets published instead. That asymmetry is R-2.
+ *
+ * Refs are emitted in sorted order so a re-run over unchanged data produces an
+ * unchanged file.
+ */
+export declare function mergeStats(seed: StatsSeed, key: string, provider: string, fresh: Record<string, unknown>): StatsSeed;
+/** Wrap merged stats in the publishable document. */
+export declare function statsDocument(merged: StatsSeed, now?: Date): StatsDocument;
+//# sourceMappingURL=seed.d.ts.map

package/dist/ratings/seed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed.d.ts","sourceRoot":"","sources":["../../src/ratings/seed.ts"],"names":[],"mappings":"AAoBA,qDAAqD;AACrD,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC;;;;;GAKG;AACH,eAAO,MAAM,UAAU,gBAAgB,CAAC;AAExC,8FAA8F;AAC9F,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAElE;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,uCAAuC;AACvC,MAAM,WAAW,aAAc,SAAQ,SAAS;IAC9C,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,0EAA0E;AAC1E,eAAO,MAAM,UAAU,EAAE,SAA0C,CAAC;AAEpE;;;;;;;;;;;;;GAaG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CA2C9D;AAoBD;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,SAAS,EACf,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,SAAS,CAaX;AAED,qDAAqD;AACrD,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,GAAE,IAAiB,GAAG,aAAa,CAQtF"}

package/dist/ratings/seed.js

@@ -0,0 +1,132 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 The Grimoire Authors
+// Invariant R-2, "no silent emptying", in the two functions that carry it: the
+// seed fetch and the per-stat-key merge over what it returned.
+//
+// A published `stats.json` is not committed anywhere (ADR D8), so the live
+// site IS the checkpoint. Every run re-derives its own stat key and carries
+// every other one forward from that checkpoint untouched — never a whole-file
+// replacement, because a `rating` run must not drop a `downloads` key it never
+// computed.
+//
+// The status branching in [`loadSeed`] is the whole of it, and `|| true` is
+// forbidden: a corrupted or unreachable seed is indistinguishable from an
+// empty one, and treating it as empty is exactly how a published rating set
+// gets silently replaced with nothing. So a fetch that did not clearly say
+// "there is nothing here" fails the run instead.
+import { CliError, EXIT } from "../cli/exit.js";
+import { request } from "../validate/adapters/http.js";
+/** The `stats.json` version this producer writes. */
+export const SCHEMA_VERSION = 1;
+/**
+ * Where a run leaves the sidecar in the repository root. The renderer reads it
+ * at build time and the deploy publishes it as `stats.json`; it is never
+ * committed, so a rollback is *both* dropping the `ratings` block and deleting
+ * the published file (S-016) — the last tally is otherwise served forever.
+ */
+export const STATS_FILE = ".stats.json";
+/** The first run's seed, and the only shape a genuine 404 may produce. */
+export const EMPTY_SEED = { providers: {}, entries: {} };
+/**
+ * Fetch the currently published `stats.json` to merge over.
+ *
+ * | Outcome | Behaviour |
+ * |---|---|
+ * | 404 | empty seed — the first run, and the normal case |
+ * | 2xx that parses | merge base |
+ * | 2xx that does not parse | **throws** (65) |
+ * | transport / TLS / 5xx / timeout / over-cap | **throws** (69) |
+ *
+ * `request()` maps its transport catch *and* its response-size cap to
+ * `{status: 0}`, so that value is a hard error here and can never be read as
+ * "the seed was fine and empty".
+ */
+export async function loadSeed(url) {
+    const response = await request(url);
+    if (response.status === 404)
+        return { providers: {}, entries: {} };
+    if (response.status < 200 || response.status >= 300) {
+        // `status: 0` lands here too, and deliberately: it is the transport catch
+        // and the over-cap read, neither of which says anything about what is
+        // published.
+        throw new CliError(`could not read the published stats.json at ${url} (HTTP ${response.status}) — ` +
+            `refusing to publish a sidecar that would empty every rating`, EXIT.unavailable);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(response.body);
+    }
+    catch (err) {
+        throw new CliError(`the published stats.json at ${url} did not parse (${err.message}) — ` +
+            `refusing to treat an unreadable seed as an empty one`, EXIT.data);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new CliError(`the published stats.json at ${url} is not a JSON object`, EXIT.data);
+    }
+    // Absence *within* a document that parsed is first-class — a site that
+    // published a header and no entries yet has genuinely nothing to carry.
+    // A key that is PRESENT but the wrong shape is not absence, though: it is
+    // an unreadable seed wearing the clothes of an empty one, and coercing it
+    // to `{}` here would empty every published rating on the next deploy —
+    // the same silent emptying the parse guard above refuses, one layer in.
+    const doc = parsed;
+    return {
+        providers: object(doc.providers, "providers", url),
+        entries: object(doc.entries, "entries", url),
+    };
+}
+/**
+ * A nested map: `{}` when the key is absent, a hard error when it is present
+ * and not a plain object.
+ *
+ * @throws {CliError} `EXIT.data` when `value` is present but not an object.
+ */
+function object(value, key, url) {
+    if (value === undefined || value === null)
+        return {};
+    if (typeof value !== "object" || Array.isArray(value)) {
+        throw new CliError(`the published stats.json at ${url} has a '${key}' that is not an object ` +
+            `(${Array.isArray(value) ? "array" : typeof value}) — refusing to treat a malformed seed as an empty one`, EXIT.data);
+    }
+    return value;
+}
+/**
+ * Merge one completed producer's output over the seed, per stat key.
+ *
+ * `fresh` is keyed by ref and holds only this producer's stat value, so a ref
+ * absent from it had its key genuinely observed as empty — the key is dropped,
+ * which is correct *because this producer completed*. A producer that failed
+ * never reaches here at all, and the seed it would have merged over is what
+ * gets published instead. That asymmetry is R-2.
+ *
+ * Refs are emitted in sorted order so a re-run over unchanged data produces an
+ * unchanged file.
+ */
+export function mergeStats(seed, key, provider, fresh) {
+    const entries = {};
+    for (const ref of [...new Set([...Object.keys(seed.entries), ...Object.keys(fresh)])].sort()) {
+        const carried = {};
+        for (const [stat, value] of Object.entries(seed.entries[ref] ?? {})) {
+            if (stat !== key)
+                carried[stat] = value;
+        }
+        // A ref absent from `fresh` had this key genuinely observed as empty, so
+        // the key is dropped — correct only because this producer completed.
+        if (ref in fresh)
+            carried[key] = fresh[ref];
+        if (Object.keys(carried).length > 0)
+            entries[ref] = carried;
+    }
+    return { providers: { ...seed.providers, [key]: provider }, entries };
+}
+/** Wrap merged stats in the publishable document. */
+export function statsDocument(merged, now = new Date()) {
+    return {
+        schema_version: SCHEMA_VERSION,
+        // RFC 3339 UTC, seconds resolution — the shape every fixture pins.
+        generated_at: now.toISOString().replace(/\.\d+Z$/, "Z"),
+        providers: merged.providers,
+        entries: merged.entries,
+    };
+}
+//# sourceMappingURL=seed.js.map

package/dist/ratings/seed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed.js","sourceRoot":"","sources":["../../src/ratings/seed.ts"],"names":[],"mappings":"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"}

package/dist/renderer/astro/components/Catalog.d.ts

@@ -1,4 +1,6 @@
 import { type CatalogPackage } from "../lib/catalog.js";
+export type Sort = "name" | "updated" | "rating";
+export declare function compare(a: CatalogPackage, b: CatalogPackage, sort: Sort): number;
 export default function Catalog({ packages, vscodeExtension, }: {
     packages: CatalogPackage[];
     vscodeExtension: string | null;

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

@@ -2,11 +2,11 @@ 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 { Check, FolderRoot, Globe, Image, ImageOff } from "lucide-preact";
+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 { timeAgo, vscodeUrl } from "../lib/catalog.js";
+import { lastUpdated, timeAgo, vscodeUrl } 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,17 +14,61 @@ function kindOrder(kind) {
     const i = KNOWN_KINDS.indexOf(kind);
     return i === -1 ? KNOWN_KINDS.length : i;
 }
-// Deprecated packages sink to the bottom regardless of sort mode; the
-// chosen sort only orders within the two groups.
-function compare(a, b, sort) {
-    const dep = Number(!!a.deprecated) - Number(!!b.deprecated);
-    if (dep !== 0)
-        return dep;
-    if (sort === "name")
-        return a.name.localeCompare(b.name);
-    if (!a.created || !b.created)
-        return (a.created ? 0 : 1) - (b.created ? 0 : 1);
-    return new Date(b.created).getTime() - new Date(a.created).getTime();
+/**
+ * Bigger first, with `null` as its own bucket underneath every number.
+ *
+ * The shared shape of the two ranked keys, and the reason both are written
+ * this way: "missing" is not a low value, it is the absence of one. Folding
+ * it into a number — 0 upvotes, epoch 0 — orders those rows against real
+ * data by accident, and ties them all with each other.
+ */
+function descending(a, b) {
+    if (a === null || b === null)
+        return Number(a === null) - Number(b === null);
+    return b - a;
+}
+/** `updated` as epoch ms; null when absent, empty or not a date at all. */
+function updatedAt(p) {
+    const at = lastUpdated(p);
+    const ms = at ? new Date(at).getTime() : NaN;
+    return Number.isFinite(ms) ? ms : null;
+}
+/**
+ * Ascending, case-insensitive. The full ref breaks the last tie in every
+ * 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);
+/**
+ * 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
+ * rule, so it goes into a bucket of its own at the bottom.
+ */
+const byUpdated = (a, b) => descending(updatedAt(a), updatedAt(b));
+/**
+ * Most upvotes first. Unrated is its own bucket at the bottom, never a zero:
+ * a fresh index is all-unrated, and zeroes would leave every one of those
+ * rows comparing equal with nothing left to break the tie.
+ */
+const byRating = (a, b) => descending(a.rating?.up ?? null, b.rating?.up ?? null);
+/** Each mode as a chain of keys, most significant first. */
+const CHAINS = {
+    name: [byName],
+    updated: [byUpdated, byName],
+    rating: [byRating, byUpdated, byName],
+};
+// Deprecated packages get no special ordering here — they are filtered out
+// of the default browse entirely (see `shown` below) and interleave like
+// 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) {
+    for (const key of CHAINS[sort]) {
+        const d = key(a, b);
+        if (d !== 0)
+            return d;
+    }
+    return 0;
 }
 // The two install scopes previously wore the VS Code extension's own
 // codicons so "project" and "global" read identically in both. That parity
@@ -120,12 +164,21 @@ function CopyButton({ command, variant = "default", name, }) {
 // hydrates in the browser, so importing the build-time payload here would
 // ship the whole catalog twice.
 export default function Catalog({ packages, vscodeExtension, }) {
-    // Seeded from `?q=…` on the very first render, not from an effect: a
-    // keyword chip on a package page links here, and filtering one render late
-    // means painting the full catalog and then collapsing it. The server has
-    // no `location`, so it renders the unfiltered list — which is what a
-    // crawler and a `?q=`-less visitor should both get.
-    const [query, setQuery] = useState(() => typeof location === "undefined" ? "" : (new URLSearchParams(location.search).get("q") ?? ""));
+    // Empty on the first render, ALWAYS — `?q=…` is applied a beat later, in
+    // the layout effect below. This is not a style preference, it is the one
+    // rule this island has to obey.
+    //
+    // Preact does not diff props while hydrating; its own source says so, and
+    // only re-applies props whose value is a function. Text children *are*
+    // diffed. So when the first client render disagrees with the server's, you
+    // get cards whose text is right and whose every attribute belongs to
+    // whichever package the server put at that position: one package's logo
+    // over another's name, and a link that opens the wrong page. Nothing
+    // throws. This used to seed from `location` here, and did exactly that.
+    const [query, setQuery] = useState("");
+    // 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);
     const [sort, setSort] = useState("name");
     // Deprecated packages are hidden until asked for: a retired package is
@@ -168,19 +221,29 @@ export default function Catalog({ packages, vscodeExtension, }) {
             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
+    // 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") ?? "");
+        setSeeded(true);
+    }, []);
     // Base.astro hides the catalog before first paint when the URL carries a
-    // query. Reveal it once this render — the filtered one — has hit the DOM.
-    // A layout effect, so the reveal lands in the same frame as the content.
+    // 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.
     useLayoutEffect(() => {
-        // Hydration attaches handlers but does not diff props against the server
-        // markup, so the box the server rendered empty stays empty even though
-        // this render filtered on `query`. Written straight to the DOM, which is
-        // what the vnode already claims.
+        if (!seeded)
+            return;
+        // The input's `value` prop was skipped during hydration for the same
+        // reason every other prop was, and the render that applied the query is
+        // a normal diff — but write it anyway: this effect is also what runs on
+        // a `?q=`-less load, where no second render is queued at all.
         const input = searchRef.current;
         if (input && input.value !== query)
             input.value = query;
         delete document.documentElement.dataset.query;
-    }, []);
+    }, [seeded]);
     // `/` jumps to the search box, the convention every package registry
     // shares. Bound on the document so it works wherever the reader is.
     useEffect(() => {
@@ -357,9 +420,14 @@ export default function Catalog({ packages, vscodeExtension, }) {
     });
     const shown = (showDeprecated ? matching : matching.filter((p) => !p.deprecated)).sort((a, b) => compare(a, b, sort));
     // A catalog with nothing deprecated gets no toggle — a control that can
-    // only ever be a no-op is worse than its absence.
+    // 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", children: [_jsxs("div", { class: "controls", ref: controlsRef, children: [_jsxs("div", { class: "search-field", 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", tabIndex: chipTabIndex, onKeyDown: onChipKeyDown, onClick: () => setSort("name"), children: "name" }), _jsx("button", { type: "button", class: sort === "updated" ? "chip active" : "chip", tabIndex: chipTabIndex, onKeyDown: onChipKeyDown, onClick: () => setSort("updated"), children: "updated" })] }), _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", 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}`, 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", tabIndex: 0, onKeyDown: onCardKeyDown, children: [_jsxs("div", { class: "card-head", children: [_jsx(CardLogo, { pkg: p }), _jsx("h2", { children: _jsx("a", { href: withBase(`/p/${p.namespace}/${p.name}/`), tabIndex: -1, children: p.name }) }), p.deprecated ? (_jsx("span", { class: "badge deprecated", children: "deprecated" })) : (_jsx("span", { class: `badge kind-${p.kind}`, children: p.kind }))] }), _jsx("p", { class: "namespace", children: p.namespace }), (p.version || p.license || p.created) && (_jsxs("div", { class: "meta-row", children: [p.version && _jsxs("span", { class: "pill version", children: ["v", p.version] }), p.license && _jsx("span", { class: "pill license", children: p.license }), p.created && timeAgo(p.created) && (_jsxs("time", { class: "updated", datetime: p.created, title: p.created, children: ["updated ", timeAgo(p.created)] }))] })), 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", 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", children: [_jsxs("div", { class: "controls", ref: controlsRef, children: [_jsxs("div", { class: "search-field", 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", tabIndex: chipTabIndex, onKeyDown: onChipKeyDown, onClick: () => setSort("name"), children: "name" }), _jsx("button", { type: "button", class: sort === "updated" ? "chip active" : "chip", tabIndex: chipTabIndex, onKeyDown: onChipKeyDown, onClick: () => setSort("updated"), children: "updated" }), hasRatings && (_jsx("button", { type: "button", class: sort === "rating" ? "chip active" : "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", 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}`, 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", tabIndex: 0, onKeyDown: onCardKeyDown, children: [_jsxs("div", { class: "card-head", children: [_jsx(CardLogo, { pkg: p }), _jsx("h2", { children: _jsx("a", { href: withBase(`/p/${p.namespace}/${p.name}/`), tabIndex: -1, children: p.name }) }), p.deprecated ? (_jsx("span", { class: "badge deprecated", children: "deprecated" })) : (_jsx("span", { class: `badge kind-${p.kind}`, children: p.kind }))] }), _jsx("p", { class: "namespace", children: p.namespace }), (p.version || p.license || lastUpdated(p) || p.rating) && (_jsxs("div", { class: "meta-row", 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", 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}`))) }))] }));
 }

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

@@ -1,11 +1,11 @@
 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 { Check, FolderRoot, Globe, Image, ImageOff } from "lucide-preact";
+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 { timeAgo, vscodeUrl, type CatalogPackage } from "../lib/catalog.js";
+import { lastUpdated, timeAgo, vscodeUrl, type CatalogPackage } from "../lib/catalog.js";
 
 // Known kinds get stable chip ordering + badge colors; unknown kinds
 // (future schema growth) still render with a neutral badge.
@@ -16,16 +16,70 @@ function kindOrder(kind: string): number {
   return i === -1 ? KNOWN_KINDS.length : i;
 }
 
-type Sort = "name" | "updated";
+export type Sort = "name" | "updated" | "rating";
 
-// Deprecated packages sink to the bottom regardless of sort mode; the
-// chosen sort only orders within the two groups.
-function compare(a: CatalogPackage, b: CatalogPackage, sort: Sort): number {
-  const dep = Number(!!a.deprecated) - Number(!!b.deprecated);
-  if (dep !== 0) return dep;
-  if (sort === "name") return a.name.localeCompare(b.name);
-  if (!a.created || !b.created) return (a.created ? 0 : 1) - (b.created ? 0 : 1);
-  return new Date(b.created).getTime() - new Date(a.created).getTime();
+type Key = (a: CatalogPackage, b: CatalogPackage) => number;
+
+/**
+ * Bigger first, with `null` as its own bucket underneath every number.
+ *
+ * The shared shape of the two ranked keys, and the reason both are written
+ * this way: "missing" is not a low value, it is the absence of one. Folding
+ * it into a number — 0 upvotes, epoch 0 — orders those rows against real
+ * data by accident, and ties them all with each other.
+ */
+function descending(a: number | null, b: number | null): number {
+  if (a === null || b === null) return Number(a === null) - Number(b === null);
+  return b - a;
+}
+
+/** `updated` as epoch ms; null when absent, empty or not a date at all. */
+function updatedAt(p: CatalogPackage): number | null {
+  const at = lastUpdated(p);
+  const ms = at ? new Date(at).getTime() : NaN;
+  return Number.isFinite(ms) ? ms : null;
+}
+
+/**
+ * Ascending, case-insensitive. The full ref breaks the last tie in every
+ * 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: Key = (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
+ * rule, so it goes into a bucket of its own at the bottom.
+ */
+const byUpdated: Key = (a, b) => descending(updatedAt(a), updatedAt(b));
+
+/**
+ * Most upvotes first. Unrated is its own bucket at the bottom, never a zero:
+ * a fresh index is all-unrated, and zeroes would leave every one of those
+ * rows comparing equal with nothing left to break the tie.
+ */
+const byRating: Key = (a, b) => descending(a.rating?.up ?? null, b.rating?.up ?? null);
+
+/** Each mode as a chain of keys, most significant first. */
+const CHAINS: Record<Sort, Key[]> = {
+  name: [byName],
+  updated: [byUpdated, byName],
+  rating: [byRating, byUpdated, byName],
+};
+
+// Deprecated packages get no special ordering here — they are filtered out
+// of the default browse entirely (see `shown` below) and interleave like
+// 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: CatalogPackage, b: CatalogPackage, sort: Sort): number {
+  for (const key of CHAINS[sort]) {
+    const d = key(a, b);
+    if (d !== 0) return d;
+  }
+  return 0;
 }
 
 // The two install scopes previously wore the VS Code extension's own
@@ -187,14 +241,21 @@ export default function Catalog({
   packages: CatalogPackage[];
   vscodeExtension: string | null;
 }) {
-  // Seeded from `?q=…` on the very first render, not from an effect: a
-  // keyword chip on a package page links here, and filtering one render late
-  // means painting the full catalog and then collapsing it. The server has
-  // no `location`, so it renders the unfiltered list — which is what a
-  // crawler and a `?q=`-less visitor should both get.
-  const [query, setQuery] = useState(() =>
-    typeof location === "undefined" ? "" : (new URLSearchParams(location.search).get("q") ?? ""),
-  );
+  // Empty on the first render, ALWAYS — `?q=…` is applied a beat later, in
+  // the layout effect below. This is not a style preference, it is the one
+  // rule this island has to obey.
+  //
+  // Preact does not diff props while hydrating; its own source says so, and
+  // only re-applies props whose value is a function. Text children *are*
+  // diffed. So when the first client render disagrees with the server's, you
+  // get cards whose text is right and whose every attribute belongs to
+  // whichever package the server put at that position: one package's logo
+  // over another's name, and a link that opens the wrong page. Nothing
+  // throws. This used to seed from `location` here, and did exactly that.
+  const [query, setQuery] = useState("");
+  // 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<string | null>(null);
   const [sort, setSort] = useState<Sort>("name");
   // Deprecated packages are hidden until asked for: a retired package is
@@ -240,18 +301,28 @@ export default function Catalog({
     });
   };
 
+  // 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
+  // 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") ?? "");
+    setSeeded(true);
+  }, []);
+
   // Base.astro hides the catalog before first paint when the URL carries a
-  // query. Reveal it once this render — the filtered one — has hit the DOM.
-  // A layout effect, so the reveal lands in the same frame as the content.
+  // 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.
   useLayoutEffect(() => {
-    // Hydration attaches handlers but does not diff props against the server
-    // markup, so the box the server rendered empty stays empty even though
-    // this render filtered on `query`. Written straight to the DOM, which is
-    // what the vnode already claims.
+    if (!seeded) return;
+    // The input's `value` prop was skipped during hydration for the same
+    // reason every other prop was, and the render that applied the query is
+    // a normal diff — but write it anyway: this effect is also what runs on
+    // a `?q=`-less load, where no second render is queued at all.
     const input = searchRef.current;
     if (input && input.value !== query) input.value = query;
     delete document.documentElement.dataset.query;
-  }, []);
+  }, [seeded]);
 
   // `/` jumps to the search box, the convention every package registry
   // shares. Bound on the document so it works wherever the reader is.
@@ -432,8 +503,10 @@ export default function Catalog({
   );
 
   // A catalog with nothing deprecated gets no toggle — a control that can
-  // only ever be a no-op is worse than its absence.
+  // 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;
@@ -476,6 +549,17 @@ export default function Catalog({
           >
             updated
           </button>
+          {hasRatings && (
+            <button
+              type="button"
+              class={sort === "rating" ? "chip active" : "chip"}
+              tabIndex={chipTabIndex}
+              onKeyDown={onChipKeyDown}
+              onClick={() => setSort("rating")}
+            >
+              rating
+            </button>
+          )}
         </div>
         {/* Divides sort from filter — two different questions sharing a row.
             Decorative only: each group already carries its own aria-label,
@@ -557,15 +641,35 @@ export default function Catalog({
                 )}
               </div>
               <p class="namespace">{p.namespace}</p>
-              {(p.version || p.license || p.created) && (
+              {(p.version || p.license || lastUpdated(p) || p.rating) && (
                 <div class="meta-row">
                   {p.version && <span class="pill version">v{p.version}</span>}
                   {p.license && <span class="pill license">{p.license}</span>}
-                  {p.created && timeAgo(p.created) && (
-                    <time class="updated" datetime={p.created} title={p.created}>
-                      updated {timeAgo(p.created)}
-                    </time>
+                  {/* A count and nothing more. The page is prerendered once
+                      for everyone, so it cannot know whether *you* voted —
+                      showing "not voted" to someone who has would be worse
+                      than showing nothing. */}
+                  {p.rating && (
+                    <span
+                      class="pill rating"
+                      title={`${p.rating.up} upvote${p.rating.up === 1 ? "" : "s"}`}
+                    >
+                      <ArrowBigUp size={13} aria-hidden="true" />
+                      {p.rating.up}
+                    </span>
                   )}
+                  {/* The date the sidecar derived, not the artifact's own
+                      `created`: a package republished from the same commit
+                      keeps its date, and one with no commit date at all gets
+                      the day this index first saw its current digest. */}
+                  {(() => {
+                    const at = lastUpdated(p);
+                    return at && timeAgo(at) ? (
+                      <time class="updated" datetime={at} title={at}>
+                        updated {timeAgo(at)}
+                      </time>
+                    ) : null;
+                  })()}
                 </div>
               )}
               {p.deprecated && (