@grimoire-rs/indexer 0.5.0 → 0.5.1

package/dist/renderer/astro/components/CodeBlock.astro

@@ -0,0 +1,74 @@
+---
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 The Grimoire Authors
+
+// A highlighted code block wearing the site's own copy affordance, and
+// optionally a link out to VS Code.
+//
+// It exists for the same reason `CommandBar.astro` does: an index's own page
+// under `theme/pages/` should be able to draw what the rest of the site draws
+// rather than a `<pre>` that looks almost like it. A setup guide showing a
+// config snippet, a publish guide showing a workflow — both want this, and
+// neither wants to restate the Shiki theme pair or the copy markup.
+//
+//   ---
+//   import CodeBlock from "@grim/components/CodeBlock.astro";
+//   import { vscodeUrl } from "@grim/lib/catalog";
+//   import { data } from "@grim/lib/data";
+//   ---
+//   <CodeBlock code="grim add acme/code-review" name="add command"
+//              vscodeHref={vscodeUrl(data.config.vscodeExtension, "acme/code-review")}
+//              vscodeLabel="Open in VS Code" />
+//
+// The copy button itself is NOT rendered here. `Base.astro` injects one into
+// every code block on the page — it has to, because a block inside rendered
+// markdown has no markup to hang one on — and it fills the `.code-actions`
+// slot below when it finds it. One button, one clipboard path, one toast, and
+// no second copy of the markup to drift.
+import { Code } from "astro:components";
+import { mdiMicrosoftVisualStudioCode } from "@mdi/js";
+import { BrandMark } from "./BrandMark.tsx";
+import { SHIKI_THEMES } from "../lib/code";
+
+interface Props {
+  /** The snippet, verbatim. What the copy button copies. */
+  code: string;
+  /** Shiki language id. `sh` covers the commands this site mostly shows. */
+  lang?: string;
+  /** What the copy toast calls this, e.g. `"add command"`. */
+  name?: string;
+  /**
+   * Any URL for the trailing button — a `vscode://` deep link from
+   * `@grim/lib/catalog`'s builders, or one written by hand. Null or omitted
+   * draws no button, which is what an index with `vscodeExtension: null` gets
+   * from those builders.
+   */
+  vscodeHref?: string | null;
+  /** Accessible name for that button. */
+  vscodeLabel?: string;
+}
+
+const {
+  code,
+  lang = "sh",
+  name,
+  vscodeHref = null,
+  vscodeLabel = "Open in VS Code",
+} = Astro.props;
+---
+
+<div class="code-block" data-slot="code-block" data-copy-name={name}>
+  <Code code={code} lang={lang} themes={SHIKI_THEMES} />
+  {/* Present even when empty: it is where `Base.astro` puts the copy button,
+      and a block that renders one before the script runs would flash a second
+      one after it. */}
+  <span class="code-actions">
+    {
+      vscodeHref && (
+        <a class="code-vscode" href={vscodeHref} title={vscodeLabel} aria-label={vscodeLabel}>
+          <BrandMark path={mdiMicrosoftVisualStudioCode} size={15} />
+        </a>
+      )
+    }
+  </span>
+</div>

package/dist/renderer/astro/layouts/Base.astro

@@ -279,10 +279,25 @@ const { title, description, image = config.logo ?? config.favicon } = Astro.prop
         '<path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"/></svg>';
 
       for (const pre of document.querySelectorAll("pre.astro-code")) {
-        const wrapper = document.createElement("div");
-        wrapper.className = "code-block";
-        pre.replaceWith(wrapper);
-        wrapper.append(pre);
+        // `CodeBlock.astro` already ships the wrapper and the action slot, so
+        // adopt them where they are there. Wrapping a second time would nest
+        // two positioning contexts and orphan whatever the component put in
+        // the slot.
+        const parent = pre.parentElement;
+        let wrapper = parent?.classList.contains("code-block") ? parent : null;
+        if (!wrapper) {
+          wrapper = document.createElement("div");
+          wrapper.className = "code-block";
+          pre.replaceWith(wrapper);
+          wrapper.append(pre);
+        }
+
+        let actions = wrapper.querySelector(".code-actions");
+        if (!actions) {
+          actions = document.createElement("span");
+          actions.className = "code-actions";
+          wrapper.append(actions);
+        }
 
         const btn = document.createElement("button");
         btn.type = "button";
@@ -292,9 +307,10 @@ const { title, description, image = config.logo ?? config.favicon } = Astro.prop
         // `textContent`, not `innerText`: the block is not rendered yet at
         // this point, and `innerText` would collapse its whitespace.
         btn.dataset.copy = pre.textContent ?? "";
-        btn.dataset.copyName = "code block";
+        // A component-rendered block names itself; a markdown one cannot.
+        btn.dataset.copyName = wrapper.dataset.copyName || "code block";
         btn.innerHTML = CLIPBOARD_ICON + '<span class="sr-only" role="status"></span>';
-        wrapper.append(btn);
+        actions.append(btn);
       }
 
       for (const btn of document.querySelectorAll("[data-copy]")) {
@@ -917,6 +933,20 @@ const { title, description, image = config.logo ?? config.favicon } = Astro.prop
         .chip.deprecated-toggle {
           flex-shrink: 0;
         }
+        /* Lifts every keyword at once, and is only in the markup while there
+           is one to lift — so it never competes with the rail for room in the
+           common case. Muted until hovered: it undoes work, and it should not
+           read as another facet to pick. */
+        .chip.kw-clear {
+          flex-shrink: 0;
+          gap: var(--grim-space-2);
+          color: var(--grim-color-muted);
+        }
+        .chip.kw-clear:hover,
+        .chip.kw-clear:focus-visible {
+          border-color: var(--grim-color-accent);
+          color: var(--grim-color-fg);
+        }
         .kw-menu {
           flex-shrink: 0;
         }
@@ -1047,51 +1077,61 @@ const { title, description, image = config.logo ?? config.favicon } = Astro.prop
             transition: border-color var(--grim-duration-base) ease;
           }
         }
-        /* The overflow menu. A `<details>` for the same reasons the platform
-           picker is one — it opens, closes and takes Escape without a line of
-           script — and the panel is the `.os-menu` popover's measurements so
-           the two read as the same object in two places. */
+        /* The overflow menu. A popover, and it has to be one: `.filter-row`
+           above is a scroll container, and an absolutely-positioned panel
+           inside a scroll container is cropped to the row AND stretches the
+           row's scroll extent — which is where a menu that opened invisibly,
+           with a stray horizontal and vertical scrollbar to show for it, came
+           from. The top layer is outside every ancestor's `overflow`, and it
+           brings light dismiss and Escape, which the `<details>` this replaced
+           never had. Its seat is `placeKwMenu` in `Catalog.tsx`. */
         .kw-menu {
-          position: relative;
           display: flex;
         }
         /* The trigger wears `.chip`, so its box comes from there and cannot
            drift a pixel off the chips it sits beside. Only what a chip does
            not cover is stated here. */
-        .kw-menu > summary {
+        .kw-menu > button {
           display: inline-flex;
           align-items: center;
           color: var(--grim-color-muted);
-          /* Both spellings: the default triangle is a marker in Firefox and
-             a `::-webkit-details-marker` pseudo-element in older WebKit. */
-          list-style: none;
-        }
-        .kw-menu > summary::-webkit-details-marker {
-          display: none;
         }
-        .kw-menu > summary:hover,
-        .kw-menu > summary:focus-visible,
-        .kw-menu[open] > summary {
+        .kw-menu > button:hover,
+        .kw-menu > button:focus-visible,
+        .kw-menu > button[aria-expanded="true"] {
           border-color: var(--grim-color-accent);
           color: var(--grim-color-fg);
         }
+        /* `inset` and `margin` undo the UA's centring of a popover, so the
+           `left`/`top` the script writes are the whole position. `color` is
+           restated because the UA sets `CanvasText` on `[popover]` directly,
+           which beats what the panel would otherwise inherit. `display` is
+           deliberately absent: the UA's `display: none` for a closed popover
+           has to keep winning, so the flex box is declared on `:popover-open`
+           alone — an unconditional `display` here would show the menu shut. */
         .kw-menu-panel {
-          position: absolute;
-          top: calc(100% + var(--grim-space-2));
-          left: 0;
-          z-index: 5;
-          display: flex;
-          flex-direction: column;
-          gap: var(--grim-space-3);
+          position: fixed;
+          inset: auto;
+          margin: 0;
           /* The panel's own measurement: wide enough for the longest keyword
              a publisher is likely to write plus its count, and capped so a
              long vocabulary scrolls instead of running off the viewport. */
           width: 15rem;
           padding: var(--grim-space-3);
           background: var(--grim-color-card);
+          color: var(--grim-color-fg);
           border: var(--grim-border-width) solid var(--grim-color-border);
           border-radius: var(--grim-radius-control);
           box-shadow: var(--grim-shadow-raised);
+          /* The list inside is the thing that scrolls. Without this the UA's
+             own `overflow: auto` on `[popover]` adds a second scrollbar once
+             the script caps the panel's height. */
+          overflow: hidden;
+        }
+        .kw-menu-panel:popover-open {
+          display: flex;
+          flex-direction: column;
+          gap: var(--grim-space-3);
         }
         .kw-menu-search {
           width: 100%;
@@ -1115,6 +1155,11 @@ const { title, description, image = config.logo ?? config.favicon } = Astro.prop
              as a list rather than a page. */
           max-height: 15rem;
           overflow-y: auto;
+          /* And shorter still where the panel's own cap is tighter — a
+             flex item's automatic minimum size is its content, so without
+             `min-height` the list refuses to shrink and overflows the panel
+             the script just sized to the space below the trigger. */
+          min-height: 0;
         }
         .kw-menu-item {
           display: flex;
@@ -1208,6 +1253,27 @@ const { title, description, image = config.logo ?? config.favicon } = Astro.prop
           grid-template-columns: repeat(auto-fill, minmax(19rem, 1fr));
           gap: var(--grim-space-6);
         }
+        /* Off-screen cards skip layout and paint until they are scrolled to.
+           A card is the expensive item on this page — a masked keyword strip,
+           a clipped watermark in its own stacking context, a logo — and the
+           grid and the table are separate component trees, so switching view
+           repaints every one of them at once.
+
+           `auto` remembers each card's last real height, so the scrollbar
+           stops jumping after the first pass; the `18rem` is only the guess
+           before that. Cards stay focusable and findable — the engine renders
+           one on focus or find-in-page.
+
+           ponytail: this bounds the PAINT, not the JS. Measured in jsdom (no
+           layout at all) the Preact commit for one view switch is ~30ms at 100
+           packages, ~90-170ms at 500 and ~180-350ms at 1000, because the two
+           views share no element types and every card unmounts as every row
+           mounts. Past a few hundred packages the answer is windowing the
+           list, not another CSS property. */
+        .grid > li {
+          content-visibility: auto;
+          contain-intrinsic-size: auto 18rem;
+        }
         .card {
           display: flex;
           flex-direction: column;
@@ -1351,10 +1417,6 @@ const { title, description, image = config.logo ?? config.favicon } = Astro.prop
           height: 36px;
           border-radius: var(--grim-radius-inset);
         }
-        img.card-logo {
-          object-fit: contain;
-          background: var(--grim-color-chip-bg);
-        }
         .card-logo-fallback {
           display: flex;
           align-items: center;
@@ -1375,17 +1437,26 @@ const { title, description, image = config.logo ?? config.favicon } = Astro.prop
 
              loading  placeholder, no slash — the resting state
              ready    image faded in, placeholder faded out
-             broken   placeholder with its slash, dashed edge
+             broken   placeholder with its slash
 
            Kept distinct from `.card-logo-fallback`: that is a package with
            no logo at all, which is normal, not a fault. */
+        /* No background. A logo is already a designed mark on its own ground,
+           and a tinted square behind it framed it twice — worst on the many
+           logos that are themselves a rounded square, which then sat inside a
+           slightly larger rounded square. What is left is a box with a size,
+           so the three states still swap without shifting anything. Nothing is
+           drawn in any of them: the placeholder and the broken glyph carry
+           their own colour, and the slash is what separates the two — a
+           dashed frame around the broken one read as a fault in the layout
+           rather than in the image, which is not what it means. The state is
+           still announced, through `role="img"` and a label on the slot. */
         .logo-slot {
           position: relative;
           display: flex;
           align-items: center;
           justify-content: center;
           overflow: hidden;
-          background: var(--grim-color-chip-bg);
           color: var(--grim-color-muted);
         }
         .logo-slot .logo-mark,
@@ -1418,9 +1489,6 @@ const { title, description, image = config.logo ?? config.favicon } = Astro.prop
         .logo-slot:not([data-state="broken"]) .mark-broken {
           display: none;
         }
-        .logo-slot[data-state="broken"] {
-          border: var(--grim-border-width) dashed var(--grim-color-border);
-        }
         @media (prefers-reduced-motion: reduce) {
           .logo-slot .logo-mark,
           .logo-slot img {
@@ -1524,10 +1592,7 @@ const { title, description, image = config.logo ?? config.favicon } = Astro.prop
            name beside it starts on one line down the whole list. The colour
            is set inline, from the kind's own token or the deprecation one. */
         .t-kind {
-          text-align: center;
-        }
-        .t-kind svg {
-          vertical-align: middle;
+          justify-content: center;
         }
         /* The card's tile at a row's height. Geometry, not a scale step, and
            measured against the text line beside it rather than against the
@@ -1561,23 +1626,33 @@ const { title, description, image = config.logo ?? config.favicon } = Astro.prop
            wide cell — they are one reading, and the gap that separated them
            was the cell's width showing through. */
         .t-rating {
-          text-align: right;
+          justify-content: flex-end;
           color: var(--grim-color-muted);
         }
         .t-rating svg {
-          vertical-align: middle;
           margin-left: var(--grim-space-2);
-          /* Optical, not rhythm: the glyph's ink sits high in its own box, so
-             the middle of the box reads above the digits beside it. A pixel
-             down puts the two on the same visual line. */
-          translate: 0 1px;
+        }
+        /* The two cells that carry a glyph centre it as a box, not on the
+           text line. `vertical-align: middle` aligns to half the x-height,
+           which sits about 2px under the line's true middle at this step —
+           the eye reads that as the mark and the arrow sagging below the
+           words beside them. Neither cell owes anything to the row's
+           no-flex rule above: the kind is one mark and the rating is a
+           fixed-width count plus its arrow, so there is no text here for
+           `text-overflow` to elide. */
+        .t-kind,
+        .t-rating {
+          display: flex;
+          align-items: center;
         }
         /* The count carries the column's alignment, and the arrow after it
            inherits it: a fixed box, right-aligned, in tabular figures. Without
            the fixed box a three-digit count would push its own arrow right of
            the one above it. Geometry — it holds four digits at this step. */
         .t-votes {
-          display: inline-block;
+          /* Never shrunk to its digits: the box is what holds the arrow
+             after it in one place down the column. */
+          flex: none;
           width: 2rem;
           text-align: right;
           font-variant-numeric: tabular-nums;
@@ -1912,12 +1987,21 @@ const { title, description, image = config.logo ?? config.favicon } = Astro.prop
         .astro-code span:not([style*="background"]) {
           background-color: transparent !important;
         }
-        /* Reveals on hover or keyboard focus, so it is not a permanent
-           smudge over the first line of every block. */
-        .code-copy {
+        /* The corner the block's buttons sit in. It is a row rather than one
+           positioned button because `CodeBlock.astro` can add a second one —
+           a VS Code deep link — and the copy button `Base.astro` injects has
+           to land beside it without either knowing the other's width. */
+        .code-actions {
           position: absolute;
           top: 0.45rem;
           right: 0.45rem;
+          display: flex;
+          gap: var(--grim-space-2);
+        }
+        /* Reveals on hover or keyboard focus, so they are not a permanent
+           smudge over the first line of every block. */
+        .code-copy,
+        .code-vscode {
           display: inline-flex;
           align-items: center;
           justify-content: center;
@@ -1928,6 +2012,7 @@ const { title, description, image = config.logo ?? config.favicon } = Astro.prop
           border-radius: var(--grim-radius-inset);
           background: var(--grim-color-card);
           color: var(--grim-color-muted);
+          text-decoration: none;
           cursor: pointer;
           opacity: 0;
           transition:
@@ -1936,10 +2021,13 @@ const { title, description, image = config.logo ?? config.favicon } = Astro.prop
             border-color var(--grim-duration-fast) ease;
         }
         .code-block:hover .code-copy,
-        .code-copy:focus-visible {
+        .code-block:hover .code-vscode,
+        .code-copy:focus-visible,
+        .code-vscode:focus-visible {
           opacity: 1;
         }
-        .code-copy:hover {
+        .code-copy:hover,
+        .code-vscode:hover {
           color: var(--grim-color-accent);
           border-color: var(--grim-color-accent);
         }
@@ -1949,7 +2037,8 @@ const { title, description, image = config.logo ?? config.favicon } = Astro.prop
           opacity: 1;
         }
         @media (prefers-reduced-motion: reduce) {
-          .code-copy {
+          .code-copy,
+          .code-vscode {
             transition: none;
           }
         }

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

@@ -4,8 +4,8 @@
  * Shiki is what Astro already ships — the same highlighter VS Code renders
  * with — so nothing here adds a library; this only stops the two consumers
  * drifting onto different themes. The markdown pipeline reads it through
- * `astro.config`'s `shikiConfig`, and the `<Code>` component on the package
- * page takes it as a prop.
+ * `astro.config`'s `shikiConfig`, and `CodeBlock.astro` — what every
+ * hand-written snippet on the site goes through — passes it to `<Code>`.
  *
  * A *pair*, not one theme: with a single theme a block stays dark on a light
  * page. Given two, Shiki writes the light colour as an inline style and the

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

@@ -6,8 +6,8 @@
  * Shiki is what Astro already ships — the same highlighter VS Code renders
  * with — so nothing here adds a library; this only stops the two consumers
  * drifting onto different themes. The markdown pipeline reads it through
- * `astro.config`'s `shikiConfig`, and the `<Code>` component on the package
- * page takes it as a prop.
+ * `astro.config`'s `shikiConfig`, and `CodeBlock.astro` — what every
+ * hand-written snippet on the site goes through — passes it to `<Code>`.
  *
  * A *pair*, not one theme: with a single theme a block stays dark on a light
  * page. Given two, Shiki writes the light colour as an inline style and the

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

@@ -7,8 +7,8 @@
  * Shiki is what Astro already ships — the same highlighter VS Code renders
  * with — so nothing here adds a library; this only stops the two consumers
  * drifting onto different themes. The markdown pipeline reads it through
- * `astro.config`'s `shikiConfig`, and the `<Code>` component on the package
- * page takes it as a prop.
+ * `astro.config`'s `shikiConfig`, and `CodeBlock.astro` — what every
+ * hand-written snippet on the site goes through — passes it to `<Code>`.
  *
  * A *pair*, not one theme: with a single theme a block stays dark on a light
  * page. Given two, Shiki writes the light colour as an inline style and the

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

@@ -1,4 +1,5 @@
-import type { ResolvedSiteConfig } from "../../../config.js";
+import type { RegistryHint, ResolvedSiteConfig } from "../../../config.js";
+export type { RegistryHint };
 /**
  * One option in a command bar: what it is called, what it copies, and the
  * glyph that stands for it.
@@ -35,8 +36,13 @@ export declare function installChoices(config: ResolvedSiteConfig): Choice[];
  * 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.
+ *
+ * `registry` defaults to the site's own, and is a parameter so a page can draw
+ * the same bar for a *different* index: a corporate setup guide that hands out
+ * its own index in the hero and the public one further down needs two bars
+ * differing in nothing but this argument.
  */
-export declare function registryAddCommand(config: ResolvedSiteConfig): string | null;
+export declare function registryAddCommand(config: ResolvedSiteConfig, registry?: RegistryHint | null): 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.
@@ -49,7 +55,7 @@ export declare function registryAddCommand(config: ResolvedSiteConfig): string |
  * 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[];
+export declare function registryScopeChoices(config: ResolvedSiteConfig, registry?: RegistryHint | null): 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.

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

@@ -47,10 +47,15 @@ export function installChoices(config) {
  * 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.
+ *
+ * `registry` defaults to the site's own, and is a parameter so a page can draw
+ * the same bar for a *different* index: a corporate setup guide that hands out
+ * its own index in the hero and the public one further down needs two bars
+ * differing in nothing but this argument.
  */
-export function registryAddCommand(config) {
-    return config.registry
-        ? `grim config registry add ${config.registry.alias} --index ${config.registry.index}`
+export function registryAddCommand(config, registry = config.registry) {
+    return registry
+        ? `grim config registry add ${registry.alias} --index ${registry.index}`
         : null;
 }
 /**
@@ -65,8 +70,8 @@ export function registryAddCommand(config) {
  * 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);
+export function registryScopeChoices(config, registry = config.registry) {
+    const add = registryAddCommand(config, registry);
     if (!add)
         return [];
     return [

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

@@ -20,7 +20,12 @@ import {
   mdiMicrosoftWindows,
   mdiPenguin,
 } from "@mdi/js";
-import type { ResolvedSiteConfig } from "../../../config.js";
+import type { RegistryHint, ResolvedSiteConfig } from "../../../config.js";
+
+// Re-exported so an index's own page can name the shape it passes to the two
+// functions below without reaching past `@grim/lib/*` into the package's
+// internals, which the overlay does not publish.
+export type { RegistryHint };
 
 /**
  * One option in a command bar: what it is called, what it copies, and the
@@ -77,10 +82,18 @@ export function installChoices(config: ResolvedSiteConfig): Choice[] {
  * 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.
+ *
+ * `registry` defaults to the site's own, and is a parameter so a page can draw
+ * the same bar for a *different* index: a corporate setup guide that hands out
+ * its own index in the hero and the public one further down needs two bars
+ * differing in nothing but this argument.
  */
-export function registryAddCommand(config: ResolvedSiteConfig): string | null {
-  return config.registry
-    ? `grim config registry add ${config.registry.alias} --index ${config.registry.index}`
+export function registryAddCommand(
+  config: ResolvedSiteConfig,
+  registry: RegistryHint | null = config.registry,
+): string | null {
+  return registry
+    ? `grim config registry add ${registry.alias} --index ${registry.index}`
     : null;
 }
 
@@ -96,8 +109,11 @@ export function registryAddCommand(config: ResolvedSiteConfig): string | null {
  * 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);
+export function registryScopeChoices(
+  config: ResolvedSiteConfig,
+  registry: RegistryHint | null = config.registry,
+): Choice[] {
+  const add = registryAddCommand(config, registry);
   if (!add) return [];
   return [
     { name: "Global", command: `grim --global ${add.slice("grim ".length)}`, Icon: Globe },

package/dist/renderer/astro/pages/p/[...slug].astro

@@ -21,6 +21,7 @@ import {
 import Base from "../../layouts/Base.astro";
 import VersionMenu from "../../components/VersionMenu.astro";
 import CommandBar from "../../components/CommandBar.astro";
+import CodeBlock from "../../components/CodeBlock.astro";
 import { BrandMark } from "../../components/BrandMark.tsx";
 import { DEPRECATED_MARK, KIND_MARKS, KindMark } from "../../components/KindMark.tsx";
 import {
@@ -31,7 +32,6 @@ import {
   mdiMicrosoftVisualStudioCode,
 } from "@mdi/js";
 import { withBase } from "../../lib/base";
-import { SHIKI_THEMES } from "../../lib/code";
 import {
   compareVersions,
   deprecationNote,
@@ -47,7 +47,6 @@ import {
 import { addArtifactChoices } from "../../lib/commands";
 import { data } from "../../lib/data";
 import { getEntry, render } from "astro:content";
-import { Code } from "astro:components";
 
 export function getStaticPaths() {
   return data.packages.map((pkg) => ({
@@ -382,10 +381,10 @@ const headMarkColor = pkg.deprecated
                     ))}
                   </ul>
                 ) : (
-                  <Code
+                  <CodeBlock
                     code={JSON.stringify(contentsData, null, 2)}
                     lang="json"
-                    themes={SHIKI_THEMES}
+                    name="contents"
                   />
                 )}
               </div>
@@ -612,11 +611,14 @@ const headMarkColor = pkg.deprecated
     gap: var(--grim-space-7);
     min-width: 0;
   }
+  /* Top-aligned, not centred. Centring pinned the tile to the middle of the
+     text block beside it, so every extra line of description pushed the logo
+     further down the header — the same package's mark sat at a different
+     height on every page. Aligned to the start it keeps its place against the
+     name and the byline whatever the description runs to. */
   .detail-head {
     display: flex;
-    /* Stretch, so the logo can take the height of the whole text block
-       beside it rather than sitting centred against a third of it. */
-    align-items: stretch;
+    align-items: flex-start;
     gap: var(--grim-space-6);
     background: var(--grim-color-card);
     border: var(--grim-border-width) solid var(--grim-color-border);
@@ -626,19 +628,23 @@ const headMarkColor = pkg.deprecated
   .detail-head-text {
     min-width: 0;
   }
+  /* One fixed square, the same on every package — a size, not a frame: the
+     logo slot draws no background, so what this reserves is the space the
+     mark letterboxes into. Sizing it off the text block beside it did not
+     work: `aspect-ratio` derives the width from the height the box has
+     *before* `align-self: stretch` grows it, so the tile came out 56px wide
+     against a 93px-tall header — a portrait chip that hugged the logo instead
+     of framing it. A definite square has no such ordering problem, and every
+     package's mark then lands at one size whatever its aspect ratio.
+
+     `.tile.letter` below is the exception that keeps a background, and it is
+     not one: there the coloured ground IS the mark, and the initial sitting on
+     it would be invisible without it. */
   .tile {
     flex: 0 0 auto;
-    align-self: stretch;
-    width: auto;
-    height: auto;
-    /* Square, sized by the text block it stands beside. Bounded at both
-       ends: a one-line header must not shrink it to a favicon, and a long
-       summary must not grow it into the page. */
-    aspect-ratio: 1;
-    min-height: 3.5rem;
-    max-height: 7rem;
+    width: 4.5rem;
+    height: 4.5rem;
     border-radius: var(--grim-radius-surface);
-    object-fit: cover;
   }
   .tile.letter {
     display: flex;