blume 1.4.2 → 1.5.0

package/src/deploy/sitemap.ts

@@ -8,6 +8,7 @@ import {
 } from "../astro/pages.ts";
 import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
+import { siteRoot } from "../core/site-url.ts";
 
 /**
  * Astro's reserved error routes. A user-authored override (`pages/404.astro`,
@@ -29,22 +30,81 @@ const lastmodTag = (value: string | undefined): string => {
     : `<lastmod>${date.toISOString().slice(0, 10)}</lastmod>`;
 };
 
+/** One emitted sitemap artifact: its dist-root filename and XML body. */
+export interface SitemapFile {
+  name: string;
+  xml: string;
+}
+
+/**
+ * The sitemaps.org cap on `<url>` entries in a single file. Beyond it,
+ * `sitemap.xml` becomes a sitemap index pointing at numbered chunk files —
+ * search engines reject an oversized urlset outright.
+ */
+const URLS_PER_FILE = 50_000;
+
+const renderUrlset = (
+  urls: string[]
+): string => `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${urls.join("\n")}
+</urlset>
+`;
+
 /**
- * Build a sitemap.xml from the route manifest plus the routes the manifest
+ * Build the sitemap files from the route manifest plus the routes the manifest
  * can't see: custom `.astro` pages (most importantly a custom landing `/`) and
  * the generated `/changelog` index. Returns null when the sitemap is disabled
  * or no `site` is configured (absolute URLs are required for a valid sitemap).
  * Drafts, hidden, and `noindex` pages are excluded.
+ *
+ * Sites within the per-file URL cap get the single classic `sitemap.xml`;
+ * larger sites get `sitemap.xml` as a sitemap index over numbered
+ * `sitemap-N.xml` chunks, all served from the same directory robots.txt
+ * already points at.
  */
-export const buildSitemap = (project: BlumeProject): string | null => {
+export const buildSitemapFiles = (
+  project: BlumeProject
+): SitemapFile[] | null => {
   const { site } = project.config.deployment;
   if (!(site && project.config.seo.sitemap)) {
     return null;
   }
 
-  const base = site.replace(/\/$/u, "");
+  const base = siteRoot(site);
   // Routes carry `basePath`; a `deployment.base` subdirectory is layered on top.
   const deployBase = normalizeBasePath(project.config.deployment.base);
+
+  // Archived-version pages leave the sitemap when the version is noindexed,
+  // or when their canonical points at a still-existing latest equivalent —
+  // listing a URL whose canonical says "index the other page" invites the
+  // noindexed-page-in-sitemap incoherence Docusaurus is known for. A page
+  // that exists only in an archived version stays listed (self-canonical).
+  const { versions } = project.config;
+  const archivedById = new Map(
+    (versions?.archived ?? []).map((version) => [version.id, version])
+  );
+  const currentKeys = versions
+    ? new Set(
+        project.graph.pages.flatMap((page) =>
+          page.version === "" ? [`${page.versionKey}\u0000${page.locale}`] : []
+        )
+      )
+    : null;
+  const archivedExcluded = (page: (typeof project.graph.pages)[number]) => {
+    if (!page.version) {
+      return false;
+    }
+    // A non-empty version always names a configured archived entry — that is
+    // the only way detection assigns one.
+    const archived = archivedById.get(page.version);
+    return Boolean(
+      archived?.noindex ||
+      (archived?.canonical === "latest" &&
+        currentKeys?.has(`${page.versionKey}\u0000${page.locale}`))
+    );
+  };
+
   const seen = new Set<string>();
   const urls: string[] = [];
   const pushUrl = (route: string, lastModified?: string): void => {
@@ -64,7 +124,8 @@ export const buildSitemap = (project: BlumeProject): string | null => {
       page.meta.draft ||
       page.meta.sidebar.hidden ||
       page.meta.seo.noindex ||
-      ERROR_ROUTES.has(page.route)
+      ERROR_ROUTES.has(page.route) ||
+      archivedExcluded(page)
     ) {
       continue;
     }
@@ -87,9 +148,29 @@ export const buildSitemap = (project: BlumeProject): string | null => {
   }
   urls.sort();
 
-  return `<?xml version="1.0" encoding="UTF-8"?>
-<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
-${urls.join("\n")}
-</urlset>
+  if (urls.length <= URLS_PER_FILE) {
+    return [{ name: "sitemap.xml", xml: renderUrlset(urls) }];
+  }
+
+  const chunks: SitemapFile[] = [];
+  const references: string[] = [];
+  for (let start = 0; start < urls.length; start += URLS_PER_FILE) {
+    const name = `sitemap-${chunks.length + 1}.xml`;
+    chunks.push({
+      name,
+      xml: renderUrlset(urls.slice(start, start + URLS_PER_FILE)),
+    });
+    // Chunks sit next to sitemap.xml, so their URLs layer the same deployment
+    // base robots.txt uses for the index.
+    const loc = escapeXml(
+      encodeURI(`${base}${withBasePath(deployBase, `/${name}`)}`)
+    );
+    references.push(`  <sitemap><loc>${loc}</loc></sitemap>`);
+  }
+  const index = `<?xml version="1.0" encoding="UTF-8"?>
+<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${references.join("\n")}
+</sitemapindex>
 `;
+  return [{ name: "sitemap.xml", xml: index }, ...chunks];
 };

package/src/deploy/vercel-negotiation.ts

@@ -24,7 +24,11 @@
 export const ACCEPT_MARKDOWN_HEADER_VALUE =
   "(.*,)?\\s*text/(x-)?markdown(\\s*[;,].*)?$";
 
-/** A Build Output API route — the subset these helpers read and write. */
+/**
+ * A Build Output API route — the subset these helpers read and write. Parsed
+ * routes keep whatever other fields they carry at runtime; only these are
+ * typed.
+ */
 export interface VercelRoute {
   continue?: boolean;
   dest?: string;
@@ -32,9 +36,12 @@ export interface VercelRoute {
   has?: { key?: string; type: string; value?: string }[];
   headers?: Record<string, string>;
   src?: string;
-  [key: string]: unknown;
 }
 
+/** Whether a parsed route field is a real string (the config is raw JSON). */
+const isString = (value: string | undefined): value is string =>
+  typeof value === "string";
+
 const ACCEPT_MARKDOWN_CONDITION: VercelRoute["has"] = [
   { key: "accept", type: "header", value: ACCEPT_MARKDOWN_HEADER_VALUE },
 ];
@@ -171,10 +178,10 @@ const isNegotiationRoute = (route: VercelRoute): boolean =>
   ) === true ||
   (route.continue === true &&
     route.headers?.vary === "Accept" &&
-    typeof route.src === "string" &&
+    isString(route.src) &&
     Object.keys(route).length === 3) ||
   (route.continue === true &&
-    typeof route.headers?.link === "string" &&
+    isString(route.headers?.link) &&
     route.src === HOME_SRC &&
     Object.keys(route).length === 3);
 

package/src/eval/agents.ts

@@ -1,6 +1,6 @@
-import { spawn } from "node:child_process";
 import { readFile, writeFile } from "node:fs/promises";
 
+import spawn from "cross-spawn";
 import { join } from "pathe";
 import { z } from "zod";
 
@@ -48,7 +48,6 @@ export interface HeadlessResult {
 
 export interface HeadlessOptions {
   cwd: string;
-  platform?: NodeJS.Platform;
   prompt: string;
   timeoutMs: number;
 }
@@ -58,6 +57,15 @@ export interface HeadlessOptions {
  * cmd.exe newline quoting alike), stdout and stderr captured, SIGTERM at the
  * deadline with a SIGKILL follow-up. Resolves with the captured result;
  * rejects only when the executable cannot be spawned at all (ENOENT).
+ *
+ * Spawned through cross-spawn, which runs npm's `.cmd` shims on Windows with
+ * its own cmd.exe escaping — under the old `shell: true` launch, cmd.exe was
+ * free to mangle the JSON carried by codex's `-c` arguments, and a missing
+ * executable surfaced as exit code 9009 instead of an ENOENT rejection.
+ * execa was evaluated and rejected here: it waits for the stdio streams to
+ * close, and the `exit`-beats-`close` resolution below exists precisely
+ * because a killed agent's own children (an MCP server, a shell) hold the
+ * pipes open past the SIGTERM.
  */
 export const runAgentHeadless = (
   bin: string,
@@ -66,23 +74,18 @@ export const runAgentHeadless = (
 ): Promise<HeadlessResult> =>
   // oxlint-disable-next-line promise/avoid-new -- adapt spawn's event callbacks
   new Promise((resolve, reject) => {
-    const platform = options.platform ?? process.platform;
-    // npm installs agent CLIs as `.cmd` shims on Windows, which Node refuses
-    // to spawn without a shell. Arguments are plain flags and absolute paths,
-    // so shell interpolation has nothing to mangle.
     const child = spawn(bin, args, {
       cwd: options.cwd,
-      shell: platform === "win32",
       stdio: ["pipe", "pipe", "pipe"],
     });
 
     let stdout = "";
     let stderr = "";
     let timedOut = false;
-    child.stdout.on("data", (chunk: Buffer) => {
+    child.stdout?.on("data", (chunk: Buffer) => {
       stdout += chunk.toString("utf-8");
     });
-    child.stderr.on("data", (chunk: Buffer) => {
+    child.stderr?.on("data", (chunk: Buffer) => {
       stderr += chunk.toString("utf-8");
     });
 
@@ -112,7 +115,7 @@ export const runAgentHeadless = (
       }
     });
 
-    child.stdin.end(options.prompt);
+    child.stdin?.end(options.prompt);
   });
 
 /** The spawn signature `runEval` accepts, injectable for tests. */

package/src/eval/report.ts

@@ -6,40 +6,27 @@ import type { ColorFunction } from "consola/utils";
 import { join, relative } from "pathe";
 
 import { AGENTS } from "../audit/agent.ts";
+import { duration, money, seconds } from "../cli/report-format.ts";
 import { countBySeverity } from "../core/diagnostics.ts";
 import type { EvalResult, QuestionResult, QuestionStatus } from "./run.ts";
 
-const GLYPH: Record<QuestionStatus, string> = {
+const GLYPH = {
   error: "!",
   fail: "✖",
   pass: "✔",
   skip: "⊘",
-};
+} satisfies Record<QuestionStatus, string>;
 
-const STATUS_COLOR: Record<QuestionStatus, ColorFunction> = {
+const STATUS_COLOR = {
   error: colors.yellow,
   fail: colors.red,
   pass: colors.green,
   skip: colors.dim,
-};
+} satisfies Record<QuestionStatus, ColorFunction>;
 
 /** Longest id gets the room; everything shorter aligns to it. */
 const ID_PAD = 28;
 
-const seconds = (ms: number): string => `${(ms / 1000).toFixed(1)}s`;
-
-const money = (cost: number | undefined): string =>
-  cost === undefined ? "" : `$${cost.toFixed(2)}`;
-
-const duration = (ms: number): string => {
-  if (ms < 60_000) {
-    return seconds(ms);
-  }
-  const minutes = Math.floor(ms / 60_000);
-  const rest = Math.round((ms % 60_000) / 1000);
-  return `${minutes}m ${rest}s`;
-};
-
 /** One question's progress/report line: glyph, id, status, score, time, cost. */
 export const questionLine = (result: QuestionResult): string => {
   const color = STATUS_COLOR[result.status];

package/src/eval/run.ts

@@ -263,12 +263,12 @@ export const runEval = async (options: EvalRunOptions): Promise<EvalResult> => {
     });
   }
 
-  const counts: Record<QuestionStatus, number> = {
+  const counts = {
     error: 0,
     fail: 0,
     pass: 0,
     skip: 0,
-  };
+  } satisfies Record<QuestionStatus, number>;
   for (const result of results) {
     counts[result.status] += 1;
   }

package/src/eval/schema.ts

@@ -17,7 +17,7 @@ const questionSchema = z.strictObject({
   routes: z
     .union([z.string(), z.array(z.string())])
     .default([])
-    .transform((value) => (typeof value === "string" ? [value] : value)),
+    .transform((value) => (Array.isArray(value) ? value : [value])),
   severity: z.enum(["error", "warning"]).default("error"),
   skip: z.boolean().default(false),
 });

package/src/markdown/base-links.ts

@@ -11,7 +11,7 @@ interface UrlNode extends MdastNode {
  * `setProperty`, not by mutating the node object.
  */
 interface MdastUrlContext {
-  setProperty: (node: unknown, key: "url", value: string) => void;
+  setProperty: (node: MdastNode, key: "url", value: string) => void;
 }
 
 /**
@@ -26,6 +26,10 @@ const ASSET_PATH = /\.[a-z0-9]+$/iu;
 /** Strip any `#fragment`/`?query` so only the path is extension-tested. */
 const pathOf = (url: string): string => url.replace(/[#?].*$/u, "");
 
+/** Only a string URL can be rebased; MDAST allows null or absent urls. */
+const isUrl = (url: string | null | undefined): url is string =>
+  typeof url === "string";
+
 /**
  * Satteri MDAST plugin that prepends the served-URL base — `deployment.base`
  * layered over the site-wide `basePath` — to root-relative internal page links
@@ -38,11 +42,7 @@ const pathOf = (url: string): string => url.replace(/[#?].*$/u, "");
 export const baseLinksPlugin = (deployBase: string, basePath: string) => {
   const rebase = (node: UrlNode, ctx: MdastUrlContext): void => {
     const { url } = node;
-    if (
-      typeof url === "string" &&
-      isInternalPath(url) &&
-      !ASSET_PATH.test(pathOf(url))
-    ) {
+    if (isUrl(url) && isInternalPath(url) && !ASSET_PATH.test(pathOf(url))) {
       const next = withComposedBasePath(deployBase, basePath, url);
       if (next !== url) {
         ctx.setProperty(node, "url", next);

package/src/markdown/directives.ts

@@ -21,7 +21,11 @@ const CALLOUT_TYPES = new Set([
 ]);
 
 /** Friendly aliases for the canonical Callout types. */
-const ALIASES: Record<string, string> = {
+interface CalloutAliases {
+  [alias: string]: string;
+}
+
+const ALIASES: CalloutAliases = {
   caution: "warning",
   error: "danger",
   important: "note",
@@ -54,6 +58,8 @@ export const directiveToCalloutPlugin = () => ({
     let title = node.attributes?.title ?? undefined;
 
     // A leading `:::name[Label]` parses to a paragraph flagged `directiveLabel`.
+    // SAFETY: Satteri stamps `directiveLabel` on that paragraph's `data`; any
+    // other node reads undefined and fails the check.
     const labelIndex = children.findIndex(
       (child) =>
         child.type === "paragraph" &&

package/src/markdown/heading-anchors.ts

@@ -19,11 +19,14 @@
 import { satteriCollectHastText } from "@astrojs/markdown-satteri";
 import GithubSlugger from "github-slugger";
 
+/** A hast property value: an attribute primitive or a token list. */
+type HastPropertyValue = string | number | boolean | (string | number)[];
+
 /** A minimal hast node (avoids a hast type dependency). */
 interface HastNode {
   children?: HastNode[];
   name?: string;
-  properties?: Record<string, unknown>;
+  properties?: Record<string, HastPropertyValue>;
   tagName?: string;
   type: string;
   value?: string;
@@ -31,8 +34,10 @@ interface HastNode {
 
 /** The slice of Satteri's hast visitor context this plugin reads. */
 interface HastContext {
-  data?: { astro?: { frontmatter?: Record<string, unknown> } };
-  setProperty: (node: HastNode, key: string, value: unknown) => void;
+  data?: {
+    astro?: { frontmatter?: Parameters<typeof satteriCollectHastText>[1] };
+  };
+  setProperty: (node: HastNode, key: string, value: HastPropertyValue) => void;
   textContent: (node: HastNode) => string;
 }
 
@@ -63,7 +68,7 @@ const containsAnchor = (node: HastNode): boolean => {
 // page, but slug disambiguation must reset per document; the render-scoped
 // `astro` data object is a stable, unique key for one render (entries are
 // dropped once the render is collected, so this never leaks).
-const FALLBACK_SCOPE: object = {};
+const FALLBACK_SCOPE = {};
 const sluggers = new WeakMap<object, GithubSlugger>();
 
 const sluggerFor = (ctx: HastContext): GithubSlugger => {
@@ -77,6 +82,10 @@ const sluggerFor = (ctx: HastContext): GithubSlugger => {
   return slugger;
 };
 
+/** Whether a heading already carries a usable string `id`. */
+const isStringId = (value: HastPropertyValue | undefined): value is string =>
+  typeof value === "string";
+
 /** The slug for a heading, mirroring Satteri's `heading-ids` exactly. */
 const slugFor = (
   node: HastNode,
@@ -86,6 +95,8 @@ const slugFor = (
   const rawText = ctx.textContent(node);
   // `frontmatter`-interpolated MDX headings (`## {frontmatter.title}`) need the
   // resolved value; the helper is the same one `heading-ids` defers to.
+  // SAFETY: HastNode is a structural subset of the hast element shape the
+  // helper walks (children/type/value), so the visited node always fits.
   const text = rawText.includes("frontmatter")
     ? satteriCollectHastText(
         node as Parameters<typeof satteriCollectHastText>[0],
@@ -93,7 +104,7 @@ const slugFor = (
       )
     : rawText;
   const existingId = node.properties?.id;
-  return typeof existingId === "string" ? existingId : slugger.slug(text);
+  return isStringId(existingId) ? existingId : slugger.slug(text);
 };
 
 /** Build the plugin. Wraps `<h2>`–`<h6>` in self-linking anchors. */
@@ -108,7 +119,7 @@ export const headingAnchorPlugin = (): HeadingAnchorPlugin => ({
       if (!wrap) {
         // Unwrapped headings (h1, an empty slug, or one that already links) still
         // need the id so `heading-ids` adopts it instead of re-slugging.
-        if (typeof node.properties?.id !== "string") {
+        if (!isStringId(node.properties?.id)) {
           ctx.setProperty(node, "id", slug);
         }
         return;

package/src/markdown/index.ts

@@ -52,6 +52,28 @@ type HastPlugin = NonNullable<
   NonNullable<Parameters<typeof satteri>[0]>["hastPlugins"]
 >[number];
 
+/*
+ * Blume's plugins model only the node/context slices they touch (no hast or
+ * Satteri type dependency); these bridges are the single boundary where those
+ * minimal structural shapes meet the host pipeline's full plugin types.
+ */
+
+// SAFETY: Satteri drives plugins through the same visitor protocol Blume's
+// minimal structural shapes model; they narrow the node/context types the
+// visitor hooks receive, never widen them.
+const asHastPlugin = (plugin: { name: string }): HastPlugin =>
+  plugin as HastPlugin;
+
+// SAFETY: the same visitor-protocol bridge as `asHastPlugin`, for the mdast
+// phase's plugins.
+const asMdastPlugin = (plugin: { name: string }): MdastPlugin =>
+  plugin as MdastPlugin;
+
+// SAFETY: Shiki calls only the hooks a transformer declares, and Blume's
+// transformers type their hook parameters as the hast slices they touch.
+const asShikiTransformer = (transformer: { name: string }): ShikiTransformer =>
+  transformer as ShikiTransformer;
+
 /**
  * Hast plugins enabled by config. Inline `` `code`{:lang} `` highlighting is
  * always on: it only fires on an explicit trailing `{:lang}` marker, so plain
@@ -62,11 +84,11 @@ type HastPlugin = NonNullable<
  */
 const blumeHastPlugins = (options: BlumeMarkdownOptions): HastPlugin[] => {
   const plugins: HastPlugin[] = [
-    inlineCodeHighlightPlugin(options.codeThemes) as unknown as HastPlugin,
-    tableWrapPlugin() as unknown as HastPlugin,
+    asHastPlugin(inlineCodeHighlightPlugin(options.codeThemes)),
+    asHastPlugin(tableWrapPlugin()),
   ];
   if (options.headingAnchors !== false) {
-    plugins.push(headingAnchorPlugin() as unknown as HastPlugin);
+    plugins.push(asHastPlugin(headingAnchorPlugin()));
   }
   return plugins;
 };
@@ -101,29 +123,55 @@ export const blumeShikiTransformers = (
     transformerMetaHighlight(),
   ];
   if (options.icons !== false) {
-    transformers.push(languageIconTransformer() as unknown as ShikiTransformer);
+    transformers.push(asShikiTransformer(languageIconTransformer()));
   }
   // The fence-meta reader (title / line numbers) always runs last.
-  transformers.push(codeTitleTransformer() as unknown as ShikiTransformer);
+  transformers.push(asShikiTransformer(codeTitleTransformer()));
   return transformers;
 };
 
+/** The value space of a hast element property. */
+type HastPropertyValue =
+  | string
+  | number
+  | boolean
+  | (string | number)[]
+  | null
+  | undefined;
+
+/** The `<pre>` slice the class/language transformers touch. */
+interface PreElement {
+  properties: { class?: HastPropertyValue; dataLanguage?: HastPropertyValue };
+}
+
+const isStringProperty = (value: HastPropertyValue): value is string =>
+  typeof value === "string";
+
+/** A Blume-local Shiki transformer: a name plus the `pre` hook it declares. */
+interface PreTransformer {
+  name: string;
+  pre: (node: PreElement) => void;
+}
+
 /**
  * Tag the highlighted `<pre>` with `astro-code` (plus any extra classes) so the
  * theme's code-block styles apply — `codeToHtml`'s bare output is `pre.shiki`,
  * which the theme doesn't style.
  */
-const astroCodeClassTransformer = (extra?: string): ShikiTransformer =>
-  ({
+const astroCodeClassTransformer = (extra?: string): ShikiTransformer => {
+  const transformer: PreTransformer = {
     name: "blume:astro-code-class",
-    pre(node: { properties: Record<string, unknown> }) {
-      const existing =
-        typeof node.properties.class === "string" ? node.properties.class : "";
+    pre(node) {
+      const existing = isStringProperty(node.properties.class)
+        ? node.properties.class
+        : "";
       node.properties.class = `astro-code ${extra ?? ""} ${existing}`
         .replaceAll(/\s+/gu, " ")
         .trim();
     },
-  }) as unknown as ShikiTransformer;
+  };
+  return asShikiTransformer(transformer);
+};
 
 /**
  * Tag the `<pre>` with `data-language` — raw `codeToHtml` omits it (unlike
@@ -132,13 +180,15 @@ const astroCodeClassTransformer = (extra?: string): ShikiTransformer =>
  * fence would, while header-less panes (e.g. the Component source view) stay
  * untouched.
  */
-const languageAttrTransformer = (lang: string): ShikiTransformer =>
-  ({
+const languageAttrTransformer = (lang: string): ShikiTransformer => {
+  const transformer: PreTransformer = {
     name: "blume:data-language",
-    pre(node: { properties: Record<string, unknown> }) {
+    pre(node) {
       node.properties.dataLanguage ??= lang;
     },
-  }) as unknown as ShikiTransformer;
+  };
+  return asShikiTransformer(transformer);
+};
 
 export interface HighlightCodeOptions extends BlumeShikiOptions {
   /** Extra `<pre>` class names, e.g. `blume-source` for a height-capped pane. */
@@ -235,10 +285,9 @@ const blumeSharedMdastPlugins = (
 ): MdastPlugin[] =>
   options.basePath || options.deployBase
     ? [
-        baseLinksPlugin(
-          options.deployBase ?? "",
-          options.basePath ?? ""
-        ) as unknown as MdastPlugin,
+        asMdastPlugin(
+          baseLinksPlugin(options.deployBase ?? "", options.basePath ?? "")
+        ),
       ]
     : [];
 
@@ -278,10 +327,10 @@ export const blumeMdxProcessor = (options: BlumeMdxOptions = {}) =>
     },
     hastPlugins: blumeHastPlugins(options),
     mdastPlugins: [
-      packageInstallPlugin(),
-      directiveToCalloutPlugin(),
-      mermaidPlugin(),
-      mathPlugin(),
+      asMdastPlugin(packageInstallPlugin()),
+      asMdastPlugin(directiveToCalloutPlugin()),
+      asMdastPlugin(mermaidPlugin()),
+      asMdastPlugin(mathPlugin()),
       ...blumeSharedMdastPlugins(options),
-    ] as unknown as MdastPlugin[],
+    ],
   });

package/src/markdown/inline-code.ts

@@ -15,10 +15,19 @@
 import { DEFAULT_CODE_THEMES } from "./themes.ts";
 import type { CodeThemes } from "./themes.ts";
 
+/** The value space of a hast element property (mirrors hast's `Properties`). */
+type HastPropertyValue =
+  | string
+  | number
+  | boolean
+  | (string | number)[]
+  | null
+  | undefined;
+
 /** A minimal hast node (avoids a hast type dependency). */
 interface HastNode {
   children?: HastNode[];
-  properties?: Record<string, unknown>;
+  properties?: Record<string, HastPropertyValue>;
   tagName?: string;
   type: string;
   value?: string;
@@ -71,7 +80,10 @@ type InlineHighlighter = (
 // `import()` caches the module, so this dedupes Shiki across calls on its own.
 const loadHighlighter = async (): Promise<InlineHighlighter> => {
   const mod = await import("shiki");
-  return mod.codeToHast as unknown as InlineHighlighter;
+  // SAFETY: Shiki accepts arbitrary lang/theme strings at runtime (an unknown
+  // one rejects the promise, which the caller catches); only its bundled types
+  // constrain them to known ids, so the loose signature narrows nothing real.
+  return mod.codeToHast as InlineHighlighter;
 };
 
 /** Build the plugin. Highlights inline `` `code{:lang}` `` snippets. */

package/src/markdown/language-icon.ts

@@ -55,7 +55,11 @@ interface SimpleIcon {
 }
 
 /** Fence language (and common aliases) → icon. Unmapped languages get none. */
-const LANGUAGE_ICONS: Record<string, SimpleIcon> = {
+interface LanguageIcons {
+  [language: string]: SimpleIcon;
+}
+
+const LANGUAGE_ICONS: LanguageIcons = {
   astro: siAstro,
   bash: siGnubash,
   c: siC,
@@ -119,7 +123,7 @@ const LANGUAGE_ICONS: Record<string, SimpleIcon> = {
 /** A minimal hast node (avoids a hast type dependency). */
 interface HastNode {
   children?: HastNode[];
-  properties?: Record<string, unknown>;
+  properties?: Record<string, boolean | number | string | string[] | undefined>;
   tagName?: string;
   type: string;
   value?: string;