@grimoire-rs/indexer 0.4.4 → 0.5.0

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

@@ -7,4 +7,29 @@
  * fragment — already resolves and is returned untouched.
  */
 export declare function withBase(url: string): string;
+/**
+ * The attributes a nav or footer link carries beyond its `href`.
+ *
+ * Two orthogonal axes, and conflating them is the defect this exists to
+ * stop. `withBase` applies to *every* link, unconditionally — it already
+ * no-ops on anything absolute — so guarding it on "is this internal" is
+ * never necessary and drops the base path from a site-root link the moment
+ * `external` forces one into a new tab. This decides the new-tab affordance
+ * and nothing else.
+ *
+ * `??`, not `||`: `external: false` is a decision — an absolute URL that is
+ * still this site, an intranet mirror or a staging host — and it is the one
+ * case the href's shape cannot express. Collapsing it into "unset" is what
+ * makes the field pointless.
+ *
+ * Shared by `SiteHeader` and `SiteFooter` rather than written twice: they
+ * shipped with two different answers to this question, which is the bug.
+ */
+export declare function linkAttrs(link: {
+    href: string;
+    external?: boolean;
+}): {
+    target?: string;
+    rel?: string;
+};
 //# sourceMappingURL=base.d.ts.map

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

@@ -15,3 +15,26 @@ export function withBase(url) {
     // doubles the slash.
     return __GRIMOIRE_BASE__.replace(/\/$/, "") + url;
 }
+/**
+ * The attributes a nav or footer link carries beyond its `href`.
+ *
+ * Two orthogonal axes, and conflating them is the defect this exists to
+ * stop. `withBase` applies to *every* link, unconditionally — it already
+ * no-ops on anything absolute — so guarding it on "is this internal" is
+ * never necessary and drops the base path from a site-root link the moment
+ * `external` forces one into a new tab. This decides the new-tab affordance
+ * and nothing else.
+ *
+ * `??`, not `||`: `external: false` is a decision — an absolute URL that is
+ * still this site, an intranet mirror or a staging host — and it is the one
+ * case the href's shape cannot express. Collapsing it into "unset" is what
+ * makes the field pointless.
+ *
+ * Shared by `SiteHeader` and `SiteFooter` rather than written twice: they
+ * shipped with two different answers to this question, which is the bug.
+ */
+export function linkAttrs(link) {
+    return link.external ?? !link.href.startsWith("/")
+        ? { target: "_blank", rel: "noopener noreferrer" }
+        : {};
+}

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

@@ -22,3 +22,30 @@ export function withBase(url: string): string {
   // doubles the slash.
   return __GRIMOIRE_BASE__.replace(/\/$/, "") + url;
 }
+
+/**
+ * The attributes a nav or footer link carries beyond its `href`.
+ *
+ * Two orthogonal axes, and conflating them is the defect this exists to
+ * stop. `withBase` applies to *every* link, unconditionally — it already
+ * no-ops on anything absolute — so guarding it on "is this internal" is
+ * never necessary and drops the base path from a site-root link the moment
+ * `external` forces one into a new tab. This decides the new-tab affordance
+ * and nothing else.
+ *
+ * `??`, not `||`: `external: false` is a decision — an absolute URL that is
+ * still this site, an intranet mirror or a staging host — and it is the one
+ * case the href's shape cannot express. Collapsing it into "unset" is what
+ * makes the field pointless.
+ *
+ * Shared by `SiteHeader` and `SiteFooter` rather than written twice: they
+ * shipped with two different answers to this question, which is the bug.
+ */
+export function linkAttrs(link: { href: string; external?: boolean }): {
+  target?: string;
+  rel?: string;
+} {
+  return link.external ?? !link.href.startsWith("/")
+    ? { target: "_blank", rel: "noopener noreferrer" }
+    : {};
+}

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

@@ -10,6 +10,20 @@ export type { CatalogPackage } from "../../types.js";
  * unknown bucket on the first build after an upgrade.
  */
 export declare function lastUpdated(p: CatalogPackage): string | undefined;
+/**
+ * The deprecation sentence, or `null` for a package that is not deprecated.
+ *
+ * `deprecated` is the publisher's own **message**, not a date — grim's own
+ * detail pane renders it as `Deprecated: use acme/code-review-2`. Dropping it
+ * and printing the bare word left the reader with the one thing they already
+ * knew from the badge and none of the reason, so it is the message that leads
+ * here; `replacedBy` is a separate field and rides after it.
+ *
+ * The detail page states it; a card shows the `deprecated` badge and stops
+ * there. A retirement notice is usually a sentence, and a sentence on a card
+ * pushed the description out of a grid whose rows have to stay even.
+ */
+export declare function deprecationNote(p: CatalogPackage): string | null;
 export declare function versionCascade(version: string | undefined, tags: string[]): string[];
 export declare function compareVersions(a: string, b: string): number;
 export declare function timeAgo(iso: string): string;
@@ -29,6 +43,16 @@ export declare function timeAgo(iso: string): string;
 export declare function externalUrl(raw: unknown): string | null;
 /** `vscode://<publisher.extension>/open?repo=<ref>`, or null when disabled. */
 export declare function vscodeUrl(extension: string | null, ref: string): string | null;
+/**
+ * One-click upvote through the VS Code extension.
+ *
+ * `/vote?repo=` is a route the extension ships for exactly this — its own
+ * handler comment says it "lets an index page offer a one-click upvote". The
+ * link authorizes nothing on its own: the extension gates the public post
+ * behind a disclosure modal naming the forge and the thread, and it refuses
+ * to *retract* from a link at all, since a retraction waives that modal.
+ */
+export declare function vscodeVoteUrl(extension: string | null, ref: string): string | null;
 /**
  * `vscode://<publisher.extension>/add-registry?index=<url>&alias=<name>` — the
  * one-click counterpart of the `grim config registry add` line beside it.

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

@@ -12,6 +12,30 @@
 export function lastUpdated(p) {
     return p.updated ?? p.created;
 }
+/**
+ * The deprecation sentence, or `null` for a package that is not deprecated.
+ *
+ * `deprecated` is the publisher's own **message**, not a date — grim's own
+ * detail pane renders it as `Deprecated: use acme/code-review-2`. Dropping it
+ * and printing the bare word left the reader with the one thing they already
+ * knew from the badge and none of the reason, so it is the message that leads
+ * here; `replacedBy` is a separate field and rides after it.
+ *
+ * The detail page states it; a card shows the `deprecated` badge and stops
+ * there. A retirement notice is usually a sentence, and a sentence on a card
+ * pushed the description out of a grid whose rows have to stay even.
+ */
+export function deprecationNote(p) {
+    if (!p.deprecated)
+        return null;
+    const reason = typeof p.deprecated === "string" ? p.deprecated.trim() : "";
+    return [
+        reason ? `deprecated: ${reason}` : "deprecated",
+        p.replacedBy ? `replaced by ${p.replacedBy}` : "",
+    ]
+        .filter(Boolean)
+        .join(" — ");
+}
 // Publishing 0.10.0 also moves the rolling tags 0.10, 0 and latest, so the
 // full tag list is mostly history. Return just the current release's chain
 // (latest | 0 | 0.10 | 0.10.0). `tags` must already be sorted newest-first.
@@ -104,6 +128,18 @@ export function externalUrl(raw) {
 export function vscodeUrl(extension, ref) {
     return extension ? `vscode://${extension}/open?repo=${encodeURIComponent(ref)}` : null;
 }
+/**
+ * One-click upvote through the VS Code extension.
+ *
+ * `/vote?repo=` is a route the extension ships for exactly this — its own
+ * handler comment says it "lets an index page offer a one-click upvote". The
+ * link authorizes nothing on its own: the extension gates the public post
+ * behind a disclosure modal naming the forge and the thread, and it refuses
+ * to *retract* from a link at all, since a retraction waives that modal.
+ */
+export function vscodeVoteUrl(extension, ref) {
+    return extension ? `vscode://${extension}/vote?repo=${encodeURIComponent(ref)}` : null;
+}
 /**
  * Alias charset the extension's `/add-registry` handler accepts. It has to be
  * a TOML bare key and safe as a CLI argument, so it refuses a link rather

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

@@ -22,6 +22,30 @@ export function lastUpdated(p: CatalogPackage): string | undefined {
   return p.updated ?? p.created;
 }
 
+/**
+ * The deprecation sentence, or `null` for a package that is not deprecated.
+ *
+ * `deprecated` is the publisher's own **message**, not a date — grim's own
+ * detail pane renders it as `Deprecated: use acme/code-review-2`. Dropping it
+ * and printing the bare word left the reader with the one thing they already
+ * knew from the badge and none of the reason, so it is the message that leads
+ * here; `replacedBy` is a separate field and rides after it.
+ *
+ * The detail page states it; a card shows the `deprecated` badge and stops
+ * there. A retirement notice is usually a sentence, and a sentence on a card
+ * pushed the description out of a grid whose rows have to stay even.
+ */
+export function deprecationNote(p: CatalogPackage): string | null {
+  if (!p.deprecated) return null;
+  const reason = typeof p.deprecated === "string" ? p.deprecated.trim() : "";
+  return [
+    reason ? `deprecated: ${reason}` : "deprecated",
+    p.replacedBy ? `replaced by ${p.replacedBy}` : "",
+  ]
+    .filter(Boolean)
+    .join(" — ");
+}
+
 // Publishing 0.10.0 also moves the rolling tags 0.10, 0 and latest, so the
 // full tag list is mostly history. Return just the current release's chain
 // (latest | 0 | 0.10 | 0.10.0). `tags` must already be sorted newest-first.
@@ -117,6 +141,19 @@ export function vscodeUrl(extension: string | null, ref: string): string | null
   return extension ? `vscode://${extension}/open?repo=${encodeURIComponent(ref)}` : null;
 }
 
+/**
+ * One-click upvote through the VS Code extension.
+ *
+ * `/vote?repo=` is a route the extension ships for exactly this — its own
+ * handler comment says it "lets an index page offer a one-click upvote". The
+ * link authorizes nothing on its own: the extension gates the public post
+ * behind a disclosure modal naming the forge and the thread, and it refuses
+ * to *retract* from a link at all, since a retraction waives that modal.
+ */
+export function vscodeVoteUrl(extension: string | null, ref: string): string | null {
+  return extension ? `vscode://${extension}/vote?repo=${encodeURIComponent(ref)}` : null;
+}
+
 /**
  * Alias charset the extension's `/add-registry` handler accepts. It has to be
  * a TOML bare key and safe as a CLI argument, so it refuses a link rather

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

@@ -0,0 +1,58 @@
+import type { ResolvedSiteConfig } from "../../../config.js";
+/**
+ * One option in a command bar: what it is called, what it copies, and the
+ * glyph that stands for it.
+ *
+ * Icons arrive one of two ways and both render to static SVG at build time —
+ * `path` for an `@mdi/js` brand mark, `Icon` for a Lucide component. Lucide
+ * carries no brand marks and MDI is not the set the rest of the site draws
+ * with, so neither alone covers every bar.
+ */
+export interface Choice {
+    /** Shown in the menu, and matched against `data-os-glyph` when picking. */
+    name: string;
+    /** What the field shows and copies once this choice is picked. */
+    command: string;
+    /** `@mdi/js` path string. */
+    path?: string;
+    /** Lucide component, taking a `size` prop. */
+    Icon?: (props: {
+        size?: number;
+    }) => unknown;
+}
+/**
+ * The installer choices, one per platform rather than one per config row.
+ *
+ * One row usually covers several platforms ("Linux / macOS"), and the toggle
+ * reads better as the platforms themselves than as the config's labels — so a
+ * row expands into one button per platform it names, all pointing at the same
+ * command. A row naming none (a custom label) keeps a single generic button,
+ * so an unrecognized platform is never dropped.
+ */
+export declare function installChoices(config: ResolvedSiteConfig): Choice[];
+/**
+ * The one command a visitor needs to point their own grim at this index —
+ * the `helm repo add` ergonomic. `null` when `registry` is unconfigured,
+ * which means the index has no public URL to hand out; the block is omitted
+ * rather than guessed.
+ */
+export declare function registryAddCommand(config: ResolvedSiteConfig): string | null;
+/**
+ * Scope choices for the registry-add bar. Empty when there is no command to
+ * scope — the bar can still render for the sake of its VS Code segment.
+ *
+ * Global leads: someone arriving from an index website wants this index
+ * available everywhere, not wired into whichever directory happens to be
+ * open, and it is also the scope that works with no project at all.
+ *
+ * `--global` leads the command rather than trailing it: it is a top-level
+ * flag, and appended after a long `--index <url>` it fell off the end of the
+ * line, so switching scope looked like it changed nothing at all.
+ */
+export declare function registryScopeChoices(config: ResolvedSiteConfig): Choice[];
+/**
+ * Scope choices for adding one package — the same two-way choice, the same
+ * two glyphs, the same order as the registry bar and the package cards.
+ */
+export declare function addArtifactChoices(ref: string): Choice[];
+//# sourceMappingURL=commands.d.ts.map

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

@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 The Grimoire Authors
+// What each command bar offers, derived from config. Separate from
+// `./catalog.ts` on purpose: that file is documented as safe to pull into the
+// client bundle and the catalog island imports it, while this one imports
+// icon components and is only ever read by an `.astro` page at build time.
+//
+// It exists so an index's own page can draw the site's real install or
+// registry bar in three lines rather than restating the command:
+//
+//   import CommandBar from "@grim/components/CommandBar.astro";
+//   import { installChoices } from "@grim/lib/commands";
+//   import { data } from "@grim/lib/data";
+//   <CommandBar choices={installChoices(data.config)} noun="install command" … />
+import { FolderRoot, Globe } from "lucide-preact";
+import { mdiApple, mdiConsole, mdiMicrosoftWindows, mdiPenguin, } from "@mdi/js";
+/**
+ * `mdiPenguin`, not `mdiLinux`: Tux's own silhouette is a solid mass that
+ * reads as an indistinct blob at 16px, where the plainer penguin keeps its
+ * outline. Still a brand mark from the same set, so it sits beside Apple and
+ * Windows without a weight change.
+ */
+const PLATFORMS = [
+    { match: /linux/i, name: "Linux", path: mdiPenguin },
+    { match: /mac|darwin|osx|apple/i, name: "macOS", path: mdiApple },
+    { match: /win/i, name: "Windows", path: mdiMicrosoftWindows },
+];
+/**
+ * The installer choices, one per platform rather than one per config row.
+ *
+ * One row usually covers several platforms ("Linux / macOS"), and the toggle
+ * reads better as the platforms themselves than as the config's labels — so a
+ * row expands into one button per platform it names, all pointing at the same
+ * command. A row naming none (a custom label) keeps a single generic button,
+ * so an unrecognized platform is never dropped.
+ */
+export function installChoices(config) {
+    return config.install.flatMap((row) => {
+        const hits = PLATFORMS.filter((p) => p.match.test(row.os));
+        return hits.length > 0
+            ? hits.map((p) => ({ name: p.name, path: p.path, command: row.command }))
+            : [{ name: row.os, path: mdiConsole, command: row.command }];
+    });
+}
+/**
+ * The one command a visitor needs to point their own grim at this index —
+ * the `helm repo add` ergonomic. `null` when `registry` is unconfigured,
+ * which means the index has no public URL to hand out; the block is omitted
+ * rather than guessed.
+ */
+export function registryAddCommand(config) {
+    return config.registry
+        ? `grim config registry add ${config.registry.alias} --index ${config.registry.index}`
+        : null;
+}
+/**
+ * Scope choices for the registry-add bar. Empty when there is no command to
+ * scope — the bar can still render for the sake of its VS Code segment.
+ *
+ * Global leads: someone arriving from an index website wants this index
+ * available everywhere, not wired into whichever directory happens to be
+ * open, and it is also the scope that works with no project at all.
+ *
+ * `--global` leads the command rather than trailing it: it is a top-level
+ * flag, and appended after a long `--index <url>` it fell off the end of the
+ * line, so switching scope looked like it changed nothing at all.
+ */
+export function registryScopeChoices(config) {
+    const add = registryAddCommand(config);
+    if (!add)
+        return [];
+    return [
+        { name: "Global", command: `grim --global ${add.slice("grim ".length)}`, Icon: Globe },
+        { name: "Project", command: add, Icon: FolderRoot },
+    ];
+}
+/**
+ * Scope choices for adding one package — the same two-way choice, the same
+ * two glyphs, the same order as the registry bar and the package cards.
+ */
+export function addArtifactChoices(ref) {
+    return [
+        { name: "Global", command: `grim add --global ${ref}`, Icon: Globe },
+        { name: "Project", command: `grim add ${ref}`, Icon: FolderRoot },
+    ];
+}

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

@@ -0,0 +1,117 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 The Grimoire Authors
+
+// What each command bar offers, derived from config. Separate from
+// `./catalog.ts` on purpose: that file is documented as safe to pull into the
+// client bundle and the catalog island imports it, while this one imports
+// icon components and is only ever read by an `.astro` page at build time.
+//
+// It exists so an index's own page can draw the site's real install or
+// registry bar in three lines rather than restating the command:
+//
+//   import CommandBar from "@grim/components/CommandBar.astro";
+//   import { installChoices } from "@grim/lib/commands";
+//   import { data } from "@grim/lib/data";
+//   <CommandBar choices={installChoices(data.config)} noun="install command" … />
+import { FolderRoot, Globe } from "lucide-preact";
+import {
+  mdiApple,
+  mdiConsole,
+  mdiMicrosoftWindows,
+  mdiPenguin,
+} from "@mdi/js";
+import type { ResolvedSiteConfig } from "../../../config.js";
+
+/**
+ * One option in a command bar: what it is called, what it copies, and the
+ * glyph that stands for it.
+ *
+ * Icons arrive one of two ways and both render to static SVG at build time —
+ * `path` for an `@mdi/js` brand mark, `Icon` for a Lucide component. Lucide
+ * carries no brand marks and MDI is not the set the rest of the site draws
+ * with, so neither alone covers every bar.
+ */
+export interface Choice {
+  /** Shown in the menu, and matched against `data-os-glyph` when picking. */
+  name: string;
+  /** What the field shows and copies once this choice is picked. */
+  command: string;
+  /** `@mdi/js` path string. */
+  path?: string;
+  /** Lucide component, taking a `size` prop. */
+  Icon?: (props: { size?: number }) => unknown;
+}
+
+/**
+ * `mdiPenguin`, not `mdiLinux`: Tux's own silhouette is a solid mass that
+ * reads as an indistinct blob at 16px, where the plainer penguin keeps its
+ * outline. Still a brand mark from the same set, so it sits beside Apple and
+ * Windows without a weight change.
+ */
+const PLATFORMS = [
+  { match: /linux/i, name: "Linux", path: mdiPenguin },
+  { match: /mac|darwin|osx|apple/i, name: "macOS", path: mdiApple },
+  { match: /win/i, name: "Windows", path: mdiMicrosoftWindows },
+];
+
+/**
+ * The installer choices, one per platform rather than one per config row.
+ *
+ * One row usually covers several platforms ("Linux / macOS"), and the toggle
+ * reads better as the platforms themselves than as the config's labels — so a
+ * row expands into one button per platform it names, all pointing at the same
+ * command. A row naming none (a custom label) keeps a single generic button,
+ * so an unrecognized platform is never dropped.
+ */
+export function installChoices(config: ResolvedSiteConfig): Choice[] {
+  return config.install.flatMap((row) => {
+    const hits = PLATFORMS.filter((p) => p.match.test(row.os));
+    return hits.length > 0
+      ? hits.map((p) => ({ name: p.name, path: p.path, command: row.command }))
+      : [{ name: row.os, path: mdiConsole, command: row.command }];
+  });
+}
+
+/**
+ * The one command a visitor needs to point their own grim at this index —
+ * the `helm repo add` ergonomic. `null` when `registry` is unconfigured,
+ * which means the index has no public URL to hand out; the block is omitted
+ * rather than guessed.
+ */
+export function registryAddCommand(config: ResolvedSiteConfig): string | null {
+  return config.registry
+    ? `grim config registry add ${config.registry.alias} --index ${config.registry.index}`
+    : null;
+}
+
+/**
+ * Scope choices for the registry-add bar. Empty when there is no command to
+ * scope — the bar can still render for the sake of its VS Code segment.
+ *
+ * Global leads: someone arriving from an index website wants this index
+ * available everywhere, not wired into whichever directory happens to be
+ * open, and it is also the scope that works with no project at all.
+ *
+ * `--global` leads the command rather than trailing it: it is a top-level
+ * flag, and appended after a long `--index <url>` it fell off the end of the
+ * line, so switching scope looked like it changed nothing at all.
+ */
+export function registryScopeChoices(config: ResolvedSiteConfig): Choice[] {
+  const add = registryAddCommand(config);
+  if (!add) return [];
+  return [
+    { name: "Global", command: `grim --global ${add.slice("grim ".length)}`, Icon: Globe },
+    { name: "Project", command: add, Icon: FolderRoot },
+  ];
+}
+
+/**
+ * Scope choices for adding one package — the same two-way choice, the same
+ * two glyphs, the same order as the registry bar and the package cards.
+ */
+export function addArtifactChoices(ref: string): Choice[] {
+  return [
+    { name: "Global", command: `grim add --global ${ref}`, Icon: Globe },
+    { name: "Project", command: `grim add ${ref}`, Icon: FolderRoot },
+  ];
+}

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

@@ -0,0 +1,44 @@
+export interface KeywordChip {
+    keyword: string;
+    count: number;
+}
+/**
+ * The rail's chips, picked by SPLITTING POWER rather than raw frequency.
+ *
+ * A chip is worth a rail slot when clicking it meaningfully partitions what
+ * is on screen, so:
+ *
+ * - a near-ubiquitous keyword scores ~0 (clicking it barely narrows),
+ * - a tiny keyword scores low (it barely selects anything),
+ * - a keyword redundant with one already picked scores low (its packages are
+ *   already reachable through that one).
+ *
+ * Greedy. Each round scores every unpicked keyword as
+ * `min(uncoveredCount, total - count)` — a tent over coverage, peaking near
+ * half the set, intersected with the marginal gain over what is already
+ * covered — and takes the best. Ties go to the higher total count, then
+ * alphabetically. When nothing scores above zero (a small or homogeneous
+ * catalog) the remaining slots are padded by plain frequency, so the rail is
+ * never emptier than it has to be.
+ *
+ * The input is deliberately narrow — only `keywords` is read — so the tests
+ * need no full `CatalogPackage` fixtures.
+ *
+ * Ported from `@ocx-sh/catalog`'s `src/theme/utils/keywordRail.ts`, which
+ * arrived at this after a frequency-ranked rail kept offering the tags every
+ * package already carries.
+ */
+export declare function selectRailKeywords(items: readonly {
+    keywords?: readonly string[];
+}[], limit: number): KeywordChip[];
+/**
+ * Every keyword in `items`, most common first. Feeds the overflow menu, which
+ * lists what the rail had no room for.
+ *
+ * Scored over the same set the rail is, so a menu row is never a click to an
+ * empty catalog: a keyword no surviving package carries is simply not there.
+ */
+export declare function keywordFrequency(items: readonly {
+    keywords?: readonly string[];
+}[]): KeywordChip[];
+//# sourceMappingURL=keywordRail.d.ts.map

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

@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 The Grimoire Authors
+/**
+ * The rail's chips, picked by SPLITTING POWER rather than raw frequency.
+ *
+ * A chip is worth a rail slot when clicking it meaningfully partitions what
+ * is on screen, so:
+ *
+ * - a near-ubiquitous keyword scores ~0 (clicking it barely narrows),
+ * - a tiny keyword scores low (it barely selects anything),
+ * - a keyword redundant with one already picked scores low (its packages are
+ *   already reachable through that one).
+ *
+ * Greedy. Each round scores every unpicked keyword as
+ * `min(uncoveredCount, total - count)` — a tent over coverage, peaking near
+ * half the set, intersected with the marginal gain over what is already
+ * covered — and takes the best. Ties go to the higher total count, then
+ * alphabetically. When nothing scores above zero (a small or homogeneous
+ * catalog) the remaining slots are padded by plain frequency, so the rail is
+ * never emptier than it has to be.
+ *
+ * The input is deliberately narrow — only `keywords` is read — so the tests
+ * need no full `CatalogPackage` fixtures.
+ *
+ * Ported from `@ocx-sh/catalog`'s `src/theme/utils/keywordRail.ts`, which
+ * arrived at this after a frequency-ranked rail kept offering the tags every
+ * package already carries.
+ */
+export function selectRailKeywords(items, limit) {
+    const total = items.length;
+    const members = new Map();
+    items.forEach((item, i) => {
+        for (const kw of item.keywords ?? []) {
+            let set = members.get(kw);
+            if (!set)
+                members.set(kw, (set = new Set()));
+            set.add(i);
+        }
+    });
+    const picked = [];
+    const pickedSet = new Set();
+    const covered = new Set();
+    while (picked.length < limit) {
+        let best = null;
+        let bestScore = 0;
+        let bestCount = 0;
+        for (const [kw, set] of members) {
+            if (pickedSet.has(kw))
+                continue;
+            let uncovered = 0;
+            for (const i of set)
+                if (!covered.has(i))
+                    uncovered++;
+            const score = Math.min(uncovered, total - set.size);
+            const wins = score > bestScore ||
+                (score === bestScore &&
+                    score > 0 &&
+                    (set.size > bestCount ||
+                        (set.size === bestCount && best !== null && kw < best)));
+            if (wins) {
+                best = kw;
+                bestScore = score;
+                bestCount = set.size;
+            }
+        }
+        if (best === null)
+            break;
+        picked.push({ keyword: best, count: members.get(best).size });
+        pickedSet.add(best);
+        for (const i of members.get(best))
+            covered.add(i);
+    }
+    // Frequency padding for the slots the greedy pass could not justify.
+    if (picked.length < limit) {
+        const rest = [...members]
+            .filter(([kw]) => !pickedSet.has(kw))
+            .map(([keyword, set]) => ({ keyword, count: set.size }))
+            .sort((a, b) => b.count - a.count || a.keyword.localeCompare(b.keyword));
+        picked.push(...rest.slice(0, limit - picked.length));
+    }
+    return picked;
+}
+/**
+ * Every keyword in `items`, most common first. Feeds the overflow menu, which
+ * lists what the rail had no room for.
+ *
+ * Scored over the same set the rail is, so a menu row is never a click to an
+ * empty catalog: a keyword no surviving package carries is simply not there.
+ */
+export function keywordFrequency(items) {
+    const counts = new Map();
+    for (const item of items) {
+        for (const kw of item.keywords ?? [])
+            counts.set(kw, (counts.get(kw) ?? 0) + 1);
+    }
+    return [...counts]
+        .map(([keyword, count]) => ({ keyword, count }))
+        .sort((a, b) => b.count - a.count || a.keyword.localeCompare(b.keyword));
+}