@grove-dev/astro 0.5.0-next.2 → 0.5.0

package/src/server/directory.ts

@@ -30,21 +30,17 @@
  *  resolution error, which is the correct signal — a build that
  *  silently renders an empty directory hides real config mistakes.
  */
-import fullPayload from "@grove/generated/records.full.json";
-import indexPayload from "@grove/generated/records.index.json";
-import siteConfigPayload from "@grove/generated/site-config.json";
-import { existsSync, readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { dirname, resolve } from "node:path";
-import { marked } from "marked";
-import sanitizeHtml from "sanitize-html";
-import { createHighlighter } from "shiki";
-import { prettySlug } from "../lib/display.js";
-import {
-  readContentFile,
-  stripFrontmatter,
-  uniqueSlug,
-} from "@grove-dev/core";
+import fullPayload from '@grove/generated/records.full.json';
+import indexPayload from '@grove/generated/records.index.json';
+import siteConfigPayload from '@grove/generated/site-config.json';
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { marked } from 'marked';
+import sanitizeHtml from 'sanitize-html';
+import { getSingletonHighlighter } from 'shiki';
+import { prettySlug } from '../lib/display.js';
+import { headingSlug, readContentFile, stripFrontmatter, uniqueSlug } from '@grove-dev/core';
 import type {
   ProjectRecord,
   ResourceRecord,
@@ -54,7 +50,7 @@ import type {
   IndexProjectRecord,
   IndexResourceRecord,
   IndexEntityRecord,
-} from "@grove-dev/core";
+} from '@grove-dev/core';
 
 interface FullPayload {
   schemaVersion?: number;
@@ -77,7 +73,7 @@ interface SiteConfigPayload {
   blueprint?: string;
   blueprintConfig?: {
     id?: string;
-    kind?: "project" | "resource" | "entity";
+    kind?: 'project' | 'resource' | 'entity';
     routeSlug?: string;
     itemSlug?: string;
     /** V1 canonical field name for the record detail slug
@@ -88,17 +84,15 @@ interface SiteConfigPayload {
   };
   taxonomy?: Partial<
     Record<
-      "categories" | "stacks" | "platforms" | "distributionChannels",
+      'categories' | 'stacks' | 'platforms' | 'topics' | 'licenses' | 'distributionChannels',
       Array<{ id: string; name: string }>
     >
   >;
   name?: string;
 }
 
-const fullRecordsRaw: Resource[] =
-  (fullPayload as unknown as FullPayload).records ?? [];
-const indexRecordsRaw: IndexRecord[] =
-  (indexPayload as unknown as IndexPayload).records ?? [];
+const fullRecordsRaw: Resource[] = (fullPayload as unknown as FullPayload).records ?? [];
+const indexRecordsRaw: IndexRecord[] = (indexPayload as unknown as IndexPayload).records ?? [];
 const siteConfigRaw: SiteConfigPayload = siteConfigPayload as SiteConfigPayload;
 const taxonomyMaps = Object.fromEntries(
   Object.entries(siteConfigRaw.taxonomy ?? {}).map(([kind, entries]) => [
@@ -107,14 +101,14 @@ const taxonomyMaps = Object.fromEntries(
   ]),
 ) as Partial<
   Record<
-    "categories" | "stacks" | "platforms" | "distributionChannels",
+    'categories' | 'stacks' | 'platforms' | 'topics' | 'licenses' | 'distributionChannels',
     Map<string, string>
   >
 >;
 export const taxonomy = siteConfigRaw.taxonomy ?? {};
 
 export function taxonomyLabel(
-  kind: "categories" | "stacks" | "platforms" | "distributionChannels",
+  kind: 'categories' | 'stacks' | 'platforms' | 'topics' | 'licenses' | 'distributionChannels',
   id: string,
 ): string {
   return taxonomyMaps[kind]?.get(id) ?? prettySlug(id);
@@ -132,18 +126,12 @@ export const records: IndexRecord[] = indexRecordsRaw;
 
 /** Resource-kind records — slim shape. */
 /** Project-kind records — slim shape, ready for list pages. */
-export const projects = records.filter(
-  (r): r is IndexProjectRecord => r.kind === "project",
-);
+export const projects = records.filter((r): r is IndexProjectRecord => r.kind === 'project');
 
-export const resources = records.filter(
-  (r): r is IndexResourceRecord => r.kind === "resource",
-);
+export const resources = records.filter((r): r is IndexResourceRecord => r.kind === 'resource');
 
 /** Entity-kind records — slim shape. */
-export const entities = records.filter(
-  (r): r is IndexEntityRecord => r.kind === "entity",
-);
+export const entities = records.filter((r): r is IndexEntityRecord => r.kind === 'entity');
 
 const bySlug = new Map(fullRecords.map((r) => [r.slug, r]));
 
@@ -161,17 +149,17 @@ export function findRecord(slug: string): Resource | undefined {
 
 export function projectBySlug(slug: string): ProjectRecord | undefined {
   const r = bySlug.get(slug);
-  return r && r.kind === "project" ? r : undefined;
+  return r && r.kind === 'project' ? r : undefined;
 }
 
 export function resourceBySlug(slug: string): ResourceRecord | undefined {
   const r = bySlug.get(slug);
-  return r && r.kind === "resource" ? r : undefined;
+  return r && r.kind === 'resource' ? r : undefined;
 }
 
 export function entityBySlug(slug: string): EntityRecord | undefined {
   const r = bySlug.get(slug);
-  return r && r.kind === "entity" ? r : undefined;
+  return r && r.kind === 'entity' ? r : undefined;
 }
 
 // ──────────────────────────────────────────────────────────────────────
@@ -189,14 +177,11 @@ export function entityBySlug(slug: string): EntityRecord | undefined {
 // the JSON instead of a switch statement.
 
 const blueprintConfig = siteConfigRaw.blueprintConfig ?? {};
-const blueprintKind = (blueprintConfig.kind ?? "project") as
-  | "project"
-  | "resource"
-  | "entity";
-const blueprintId = (blueprintConfig.id ?? "project-directory") as
-  | "project-directory"
-  | "resource-hub"
-  | "ecosystem-map";
+const blueprintKind = (blueprintConfig.kind ?? 'project') as 'project' | 'resource' | 'entity';
+const blueprintId = (blueprintConfig.id ?? 'project-directory') as
+  | 'project-directory'
+  | 'resource-hub'
+  | 'ecosystem-map';
 
 /**
  * URL slug for the directory index page (e.g. `/projects/`,
@@ -205,24 +190,24 @@ const blueprintId = (blueprintConfig.id ?? "project-directory") as
  * time.
  */
 export function indexSlug(): string {
-  return blueprintConfig.routeSlug ?? "projects";
+  return blueprintConfig.routeSlug ?? 'projects';
 }
 
 /** URL slug for a single record detail page (the dynamic
  * `[recordSlug]` segment). Default "project" for backwards-compat
  * with V0-published configs that exposed the field as `itemSlug`. */
 export function recordSlugConfig(): string {
-  return blueprintConfig.recordSlug ?? blueprintConfig.itemSlug ?? "project";
+  return blueprintConfig.recordSlug ?? blueprintConfig.itemSlug ?? 'project';
 }
 
 /** Singular human label, e.g. "project", "resource", "entity". */
 export function itemLabel(): string {
-  return blueprintConfig.labelSingular ?? "project";
+  return blueprintConfig.labelSingular ?? 'project';
 }
 
 /** Plural human label, e.g. "projects", "resources", "entities". */
 export function itemLabelPlural(): string {
-  return blueprintConfig.labelPlural ?? "projects";
+  return blueprintConfig.labelPlural ?? 'projects';
 }
 
 /** Active blueprint id. */
@@ -231,7 +216,7 @@ export function blueprintIdFn(): string {
 }
 
 /** Active record kind discriminator. */
-export function activeKind(): "project" | "resource" | "entity" {
+export function activeKind(): 'project' | 'resource' | 'entity' {
   return blueprintKind;
 }
 
@@ -243,11 +228,11 @@ export function activeKind(): "project" | "resource" | "entity" {
  */
 export const items: IndexRecord[] = (() => {
   switch (blueprintKind) {
-    case "resource":
+    case 'resource':
       return resources;
-    case "entity":
+    case 'entity':
       return entities;
-    case "project":
+    case 'project':
     default:
       return projects;
   }
@@ -259,7 +244,7 @@ export const fullItems: Resource[] = (() => {
 })();
 
 export const fullProjects: ProjectRecord[] = fullRecords.filter(
-  (record): record is ProjectRecord => record.kind === "project",
+  (record): record is ProjectRecord => record.kind === 'project',
 );
 
 // ──────────────────────────────────────────────────────────────────────
@@ -315,43 +300,98 @@ const here = dirname(fileURLToPath(import.meta.url));
 /** Wide allowlist used for `ProjectRecord.content` Markdown bodies. */
 const RECORD_BODY_ALLOWLIST = [
   // Headings — full depth.
-  "h1", "h2", "h3", "h4", "h5", "h6",
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
   // Block-level content.
-  "p", "br", "hr", "div", "blockquote",
+  'p',
+  'br',
+  'hr',
+  'div',
+  'blockquote',
   // Lists.
-  "ul", "ol", "li",
+  'ul',
+  'ol',
+  'li',
   // Definition lists.
-  "dl", "dt", "dd",
+  'dl',
+  'dt',
+  'dd',
   // Tables (GFM).
-  "table", "thead", "tbody", "tfoot", "tr", "th", "td",
-  "caption", "colgroup", "col",
+  'table',
+  'thead',
+  'tbody',
+  'tfoot',
+  'tr',
+  'th',
+  'td',
+  'caption',
+  'colgroup',
+  'col',
   // Inline formatting.
-  "strong", "em", "b", "i", "u", "s", "del", "ins",
-  "mark", "small", "sub", "sup", "kbd", "abbr",
+  'strong',
+  'em',
+  'b',
+  'i',
+  'u',
+  's',
+  'del',
+  'ins',
+  'mark',
+  'small',
+  'sub',
+  'sup',
+  'kbd',
+  'abbr',
   // `<span>` is only here for Shiki's per-token wrappers inside
   // highlighted code blocks. Sanitize-html's default is to strip
   // any tag not in this list, so without `span` here the syntax
   // highlights silently disappear from fenced code.
-  "span",
+  'span',
   // Links + images.
-  "a", "img",
+  'a',
+  'img',
   // Code.
-  "code", "pre",
+  'code',
+  'pre',
   // Forms (task-list checkboxes only).
-  "input", "label",
+  'input',
+  'label',
   // Collapsibles and semantic blocks.
-  "details", "summary",
-  "figure", "figcaption",
-  "time",
+  'details',
+  'summary',
+  'figure',
+  'figcaption',
+  'time',
 ];
 
 /** Narrow allowlist used for `content/pages/<page>.md`. */
 const PAGE_BODY_ALLOWLIST = [
-  "h1", "h2", "h3", "h4",
-  "p", "br", "hr",
-  "ul", "ol", "li",
-  "strong", "em", "b", "i", "u", "s", "del",
-  "a", "code", "pre", "blockquote", "img",
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'p',
+  'br',
+  'hr',
+  'ul',
+  'ol',
+  'li',
+  'strong',
+  'em',
+  'b',
+  'i',
+  'u',
+  's',
+  'del',
+  'a',
+  'code',
+  'pre',
+  'blockquote',
+  'img',
 ];
 
 /**
@@ -363,73 +403,75 @@ const PAGE_BODY_ALLOWLIST = [
  * becomes a hardened disabled checkbox for GFM task lists.
  */
 const COMMON_BODY_ATTRIBUTES = {
-  a: ["href", "title", "rel", "target"],
-  img: ["src", "alt", "title", "width", "height", "loading", "decoding"],
-  th: ["scope", "colspan", "rowspan", "align"],
-  td: ["colspan", "rowspan", "align"],
-  col: ["span", "align"],
-  input: ["type", "checked", "disabled"],
-  label: ["for"],
-  abbr: ["title"],
-  time: ["datetime"],
-  details: ["open"],
-  div: ["class"], // table-wrap div the renderer injects
-  span: ["style"], // Shiki emits inline `--shiki-light` / `--shiki-dark` CSS variables
-  pre: ["class", "style"], // Shiki also tags the outer `<pre>` with theme classes
-  code: ["class"],
-  "*": ["id"],
+  a: ['href', 'title', 'rel', 'target'],
+  img: ['src', 'alt', 'title', 'width', 'height', 'loading', 'decoding'],
+  th: ['scope', 'colspan', 'rowspan', 'align'],
+  td: ['colspan', 'rowspan', 'align'],
+  col: ['span', 'align'],
+  input: ['type', 'checked', 'disabled'],
+  label: ['for'],
+  abbr: ['title'],
+  time: ['datetime'],
+  details: ['open'],
+  div: ['class'], // table-wrap div the renderer injects
+  span: ['style'], // Shiki emits inline `--shiki-light` / `--shiki-dark` CSS variables
+  pre: ['class', 'style'], // Shiki also tags the outer `<pre>` with theme classes
+  code: ['class'],
+  '*': ['id'],
 };
 
+/**
+ * CSS *value* patterns allowed per property in markdown authors' inline
+ * `style="…"` attributes. Without this filter, sanitize-html leaves
+ * the entire `style` string in place, which means a markdown author
+ * could smuggle CSS expressions (e.g. `background:url(javascript:…)`)
+ * into the rendered output even though no `<script>` tag is allowed.
+ *
+ * The regex is tested against the *value* part of each CSS declaration
+ * (`prop:value` → value), per sanitize-html's `allowedStyles` contract
+ * (it uses a CSS parser and matches `regularExpression.test(value)`).
+ *
+ * Allowed surface:
+ *   - `--shiki-*` custom properties accept any value (Shiki's
+ *     `--shiki-light` / `--shiki-dark` carry the per-token colors).
+ *   - `color:` / `background-color:` accept only safe color values:
+ *     hex (#rgb / #rrggbb / #rrggbbaa), rgb() / rgba(), hsl() / hsla().
+ *
+ * Anything else (positioning, layout, animation, expression(), url(),
+ * …) is stripped by sanitize-html because no pattern matches.
+ */
+const SHIKI_VALUE = /.+/;
+const COLOR_VALUE = /^(?:#[0-9a-f]{3,8}|rgba?\([^)]*\)|hsla?\([^)]*\))$/i;
+
 /** `<a>` tag normalization — open in a new tab, no opener. */
 const ANCHOR_TRANSFORM = sanitizeHtml.simpleTransform(
-  "a",
-  { rel: "noopener noreferrer", target: "_blank" },
+  'a',
+  { rel: 'noopener noreferrer', target: '_blank' },
   true,
 );
 
 /** Hardens `<img>` to lazy-load + async-decode. */
-const IMG_TRANSFORM = (
-  tagName: string,
-  attribs: Record<string, string>,
-) => ({
+const IMG_TRANSFORM = (tagName: string, attribs: Record<string, string>) => ({
   tagName,
   attribs: {
     ...attribs,
-    loading: attribs.loading ?? "lazy",
-    decoding: attribs.decoding ?? "async",
+    loading: attribs.loading ?? 'lazy',
+    decoding: attribs.decoding ?? 'async',
   },
 });
 
 /** Forces `<input type="checkbox">` to be disabled so task lists
  *  render read-only at runtime (no on-page state to persist). */
-const INPUT_TRANSFORM = (
-  tagName: string,
-  attribs: Record<string, string>,
-) => ({
+const INPUT_TRANSFORM = (tagName: string, attribs: Record<string, string>) => ({
   tagName,
   attribs: {
     ...attribs,
-    type: "checkbox",
-    disabled: "",
-    ...(attribs.checked !== undefined ? { checked: "" } : {}),
+    type: 'checkbox',
+    disabled: '',
+    ...(attribs.checked !== undefined ? { checked: '' } : {}),
   },
 });
 
-/**
- * GitHub-style slug for a heading. Matches `core/extractToc` so the
- * IDs the renderer emits line up with the IDs a TOC consumer reads
- * out of the same body — keeping deep links in lockstep.
- */
-function headingSlug(text: string): string {
-  return text
-    .toLowerCase()
-    .replace(/[‘’]/g, "")
-    .replace(/[^a-z0-9\s-]/g, "")
-    .replace(/\s+/g, "-")
-    .replace(/-+/g, "-")
-    .replace(/^-|-+$/g, "");
-}
-
 /**
  * Render a Markdown string to sanitized HTML. The renderer is
  * configured once (heading IDs + table wrap) and reused for both
@@ -439,81 +481,114 @@ function headingSlug(text: string): string {
  * caller owns where the body came from (file, in-memory cache, …).
  * `getContentHtml(slug)` is the per-record wrapper that reads the
  * file and calls this.
+ *
+ * The heading-ID counter is allocated per call (not module-level) so
+ * concurrent renders — or any future worker-thread path — can never
+ * observe each other's counters.
  */
 export function renderMarkdownToSafeHtml(
   body: string,
   options: { allowlist?: string[] } = {},
 ): string {
   const allowlist = options.allowlist ?? RECORD_BODY_ALLOWLIST;
-  // Configure marked. GFM is on by default in v18 but set explicitly
-  // so the intent is visible; `breaks: false` keeps single newlines
-  // from becoming `<br>` per CommonMark.
-  //
-  // We register a small extension that:
-  //   1. Adds a stable `id` to every h2–h6 so the TOC sidebar can
-  //      deep-link into the rendered body.
-  //   2. Wraps GFM tables in `<div class="grove-prose-table-wrap">`
-  //      so the column-width overflow is contained inside a rounded
-  //      border instead of breaking the layout.
-  marked.use({
-    gfm: true,
-    breaks: false,
-    renderer: {
-      heading({ tokens, depth }) {
-        const inline = this.parser.parseInline(tokens);
-        const plain = tokens
-          .map((t: { text?: string; raw?: string }) => t.text ?? t.raw ?? "")
-          .join("");
-        const id = depth === 1 ? "" : ` id="${uniqueSlug(headingSlug(plain) || "section", headingIds)}"`;
-        return `<h${depth}${id}>${inline}</h${depth}>\n`;
-      },
-      table(token: {
-        header: Array<{ tokens: unknown[] }>;
-        rows: Array<Array<{ tokens: unknown[] }>>;
-      }) {
-        const head = token.header
-          .map((cell) => `<th>${this.parser.parseInline(cell.tokens)}</th>`)
-          .join("");
-        const body = token.rows
-          .map((row) =>
-            `<tr>${row
-              .map((cell) => `<td>${this.parser.parseInline(cell.tokens)}</td>`)
-              .join("")}</tr>`,
-          )
-          .join("");
-        return `<div class="grove-prose-table-wrap"><table><thead><tr>${head}</tr></thead><tbody>${body}</tbody></table></div>\n`;
-      },
-      // Fenced code blocks: route through Shiki instead of marked's
-      // default `<pre><code class="language-…">…</code></pre>`. The
-      // returned HTML already wraps in `<pre>` and `<code>`; we
-      // hand it to the sanitizer unchanged (Shiki's output is
-      // safe by construction — no script / event handlers).
-      code({ text, lang }) {
-        return highlightCode(text, lang ?? "") + "\n";
-      },
-    },
-  });
-
+  // Reset the heading-ID collision counter for this body so IDs are
+  // stable per render and never leak between records.
+  headingIds.clear();
   const rawHtml = marked.parse(body, { async: false }) as string;
   return sanitizeHtml(rawHtml, {
     allowedTags: allowlist,
     allowedAttributes: COMMON_BODY_ATTRIBUTES,
-    allowedSchemes: ["http", "https", "mailto", "tel"],
+    // `allowedStyles` is required because the `span` and `pre` tags
+    // accept `style` (for Shiki's CSS variables) — without it
+    // sanitize-html would pass any `style` content through, including
+    // CSS expressions and `url(javascript:…)` payloads.
+    allowedStyles: {
+      '*': {
+        // All `--shiki-*` custom properties (Shiki's CSS-variable
+        // output for code-block tokenization).
+        '--shiki-light': [SHIKI_VALUE],
+        '--shiki-dark': [SHIKI_VALUE],
+        // Hex / rgb() / rgba() / hsl() / hsla() colors only.
+        color: [COLOR_VALUE],
+        'background-color': [COLOR_VALUE],
+      },
+    },
+    allowedSchemes: ['http', 'https', 'mailto', 'tel'],
     allowedSchemesByTag: {
-      a: ["http", "https", "mailto", "tel"],
-      img: ["http", "https", "data"],
+      a: ['http', 'https', 'mailto', 'tel'],
+      img: ['http', 'https', 'data'],
     },
-    allowedSchemesAppliedToAttributes: ["href", "src"],
+    allowedSchemesAppliedToAttributes: ['href', 'src'],
     transformTags: {
       a: ANCHOR_TRANSFORM,
       img: IMG_TRANSFORM,
       input: INPUT_TRANSFORM,
     },
-    disallowedTagsMode: "discard",
+    disallowedTagsMode: 'discard',
   });
 }
 
-/** Per-render counter so heading IDs don't collide within a body. */
+// ── marked configuration (hoisted, runs once at module load) ────────
+//
+// `marked.use({...})` registers a renderer that:
+//   1. Adds a stable `id` to every h2–h6 so the TOC sidebar can
+//      deep-link into the rendered body.
+//   2. Wraps GFM tables in `<div class="grove-prose-table-wrap">`
+//      so the column-width overflow is contained inside a rounded
+//      border instead of breaking the layout.
+//   3. Routes fenced code blocks through Shiki (see below).
+//
+// Heading-ID collision counter is allocated *per render* below and
+// reset before each `marked.parse(...)` call so concurrent renders
+// can never observe each other's counters in the same module instance.
+marked.use({
+  gfm: true,
+  breaks: false,
+  renderer: {
+    heading({ tokens, depth }) {
+      const inline = this.parser.parseInline(tokens);
+      const plain = tokens
+        .map((t: { text?: string; raw?: string }) => t.text ?? t.raw ?? '')
+        .join('');
+      const id =
+        depth === 1 ? '' : ` id="${uniqueSlug(headingSlug(plain) || 'section', headingIds)}"`;
+      return `<h${depth}${id}>${inline}</h${depth}>\n`;
+    },
+    table(token: {
+      header: Array<{ tokens: unknown[] }>;
+      rows: Array<Array<{ tokens: unknown[] }>>;
+    }) {
+      const head = token.header
+        .map((cell) => `<th>${this.parser.parseInline(cell.tokens)}</th>`)
+        .join('');
+      const body = token.rows
+        .map(
+          (row) =>
+            `<tr>${row
+              .map((cell) => `<td>${this.parser.parseInline(cell.tokens)}</td>`)
+              .join('')}</tr>`,
+        )
+        .join('');
+      return `<div class="grove-prose-table-wrap"><table><thead><tr>${head}</tr></thead><tbody>${body}</tbody></table></div>\n`;
+    },
+    // Fenced code blocks: route through Shiki instead of marked's
+    // default `<pre><code class="language-…">…</code></pre>`. The
+    // returned HTML already wraps in `<pre>` and `<code>`; we
+    // hand it to the sanitizer unchanged (Shiki's output is
+    // safe by construction — no script / event handlers).
+    code({ text, lang }) {
+      return highlightCode(text, lang ?? '') + '\n';
+    },
+  },
+});
+
+/**
+ * Heading-ID collision counter. Reset at the start of every
+ * `renderMarkdownToSafeHtml` call so heading IDs stay stable per
+ * body. Module-level state is acceptable because Node is single-
+ * threaded per process; the synchronous `marked.parse(body, {async:false})`
+ * returns before any other caller can observe the counter.
+ */
 const headingIds = new Map<string, number>();
 
 // ── Shiki syntax highlighter ─────────────────────────────────────────
@@ -544,23 +619,76 @@ const headingIds = new Map<string, number>();
 // load takes a few hundred ms, so we want to amortise across all
 // records in a build. The list of supported languages is curated
 // (not `ALL`) so the build doesn't pull Shiki's full grammar pack.
+//
+// We additionally stash the in-flight promise on `globalThis` under
+// a `Symbol.for` key so Vite HMR — which re-evaluates this module
+// on every dev-server save — does not throw away the cached
+// highlighter and trigger Shiki's "X instances have been created"
+// warning. The shared promise is safe to await from any caller; once
+// it resolves it stays resolved. The previous engine is released
+// exactly once per HMR boundary via `import.meta.hot.dispose`.
+const SHIKI_HIGHLIGHTER = Symbol.for('grove.shiki.highlighter');
+type GlobalWithShiki = typeof globalThis & {
+  [SHIKI_HIGHLIGHTER]?: Promise<Awaited<ReturnType<typeof getSingletonHighlighter>>>;
+};
 const SUPPORTED_LANGS = [
-  "bash", "sh", "shell", "console",
-  "python", "py",
-  "javascript", "js", "jsx", "typescript", "ts", "tsx",
-  "json", "jsonc", "yaml", "yml", "toml",
-  "markdown", "md", "mdx",
-  "html", "css", "scss", "sass",
-  "sql", "graphql",
-  "dockerfile", "diff",
-  "rust", "go", "java", "kotlin", "swift", "ruby", "php",
-  "c", "cpp", "csharp", "objective-c",
-  "xml", "ini", "properties",
+  'bash',
+  'sh',
+  'shell',
+  'console',
+  'python',
+  'py',
+  'javascript',
+  'js',
+  'jsx',
+  'typescript',
+  'ts',
+  'tsx',
+  'json',
+  'jsonc',
+  'yaml',
+  'yml',
+  'toml',
+  'markdown',
+  'md',
+  'mdx',
+  'html',
+  'css',
+  'scss',
+  'sass',
+  'sql',
+  'graphql',
+  'dockerfile',
+  'diff',
+  'rust',
+  'go',
+  'java',
+  'kotlin',
+  'swift',
+  'ruby',
+  'php',
+  'c',
+  'cpp',
+  'csharp',
+  'objective-c',
+  'xml',
+  'ini',
+  'properties',
 ];
-const highlighter = await createHighlighter({
-  themes: ["github-light", "github-dark-default"],
+const globalAny = globalThis as GlobalWithShiki;
+const highlighter = await (globalAny[SHIKI_HIGHLIGHTER] ??= getSingletonHighlighter({
+  themes: ['github-light', 'github-dark-default'],
   langs: SUPPORTED_LANGS,
-});
+}));
+
+// Release the previous engine's WASM heap on HMR. Without this the
+// old engine is unreachable but not disposed, which is the leak
+// the Shiki warning was originally hinting at.
+if (import.meta.hot) {
+  import.meta.hot.dispose(() => {
+    globalAny[SHIKI_HIGHLIGHTER]?.then((h) => h.dispose()).catch(() => {});
+  });
+}
 
 /**
  * Highlight a fenced code block with Shiki. Returns the Shiki HTML
@@ -569,37 +697,32 @@ const highlighter = await createHighlighter({
  * scroll behaviour).
  */
 function highlightCode(text: string, lang: string): string {
-  const normalized = lang?.toLowerCase() ?? "";
-  const safeLang = highlighter.getLoadedLanguages().includes(normalized)
-    ? normalized
-    : "text";
+  const normalized = lang?.toLowerCase() ?? '';
+  const safeLang = highlighter.getLoadedLanguages().includes(normalized) ? normalized : 'text';
   const html = highlighter.codeToHtml(text, {
     lang: safeLang,
-    themes: { light: "github-light", dark: "github-dark-default" },
+    themes: { light: 'github-light', dark: 'github-dark-default' },
     defaultColor: false,
   });
   // Strip the outer `<pre>`'s inline `background-color` so it doesn't
   // fight our package's prose background. The per-token `<span>`
   // `style="--shiki-light: …; --shiki-dark: …"` declarations must
   // survive — they're what makes dual-theme work.
-  return html.replace(
-    /(<pre[^>]*?)\s+style="[^"]*"/g,
-    "$1",
-  );
+  return html.replace(/(<pre[^>]*?)\s+style="[^"]*"/g, '$1');
 }
 
 const contentHtmlBySlug = new Map<string, string>();
 for (const r of fullRecords) {
-  if (r.kind !== "project") continue;
+  if (r.kind !== 'project') continue;
   const projectRecord = r as ProjectRecord;
   if (!projectRecord.content) continue;
   const read = readContentFile(projectRecord.content);
   if (!read) continue;
   // Each render needs a fresh headingIds map so the per-body
-  // collision counter starts at zero. Otherwise the second record
-  // in the loop would inherit the first record's counters and
-  // duplicate-heading IDs would collide across records.
-  headingIds.clear();
+  // collision counter starts at zero (cleared inside
+  // `renderMarkdownToSafeHtml`); otherwise the second record in the
+  // loop would inherit the first record's counters and duplicate-
+  // heading IDs would collide across records.
   try {
     contentHtmlBySlug.set(r.slug, renderMarkdownToSafeHtml(read.body));
   } catch {
@@ -627,16 +750,15 @@ export function getContentHtml(slug: string): string | null {
  */
 export function getPageContentHtml(page: string): string | null {
   const candidates = [
-    resolve(here, "..", "..", "content", "pages", `${page}.md`),
-    resolve(here, "..", "..", "..", "content", "pages", `${page}.md`),
-    resolve(process.cwd(), "content", "pages", `${page}.md`),
+    resolve(here, '..', '..', 'content', 'pages', `${page}.md`),
+    resolve(here, '..', '..', '..', 'content', 'pages', `${page}.md`),
+    resolve(process.cwd(), 'content', 'pages', `${page}.md`),
   ];
   const path = candidates.find((candidate) => existsSync(candidate));
   if (!path) return null;
 
   try {
-    const markdown = stripFrontmatter(readFileSync(path, "utf8"));
-    headingIds.clear();
+    const markdown = stripFrontmatter(readFileSync(path, 'utf8'));
     return renderMarkdownToSafeHtml(markdown, {
       allowlist: PAGE_BODY_ALLOWLIST,
     });