blume 1.4.3 → 1.5.0

package/src/core/schema.ts

@@ -23,6 +23,14 @@ import type { StandardSchema } from "./standard-schema.ts";
 // Shared primitives
 // ---------------------------------------------------------------------------
 
+// `typeof` checks live in named predicates (the form the oxlint anti-slop
+// config sanctions); generic so each site keeps its own union narrowing.
+const isString = <Value>(value: Value): value is Value & string =>
+  typeof value === "string";
+
+const isBoolean = <Value>(value: Value): value is Value & boolean =>
+  typeof value === "boolean";
+
 /** Icon inputs in serializable contexts (frontmatter, meta files). */
 const iconName = z.string().min(1);
 
@@ -40,12 +48,28 @@ const dateSchema = z
   .union([z.string(), z.date()])
   .transform((value) => (value instanceof Date ? value.toISOString() : value));
 
+/**
+ * How a sidebar group renders:
+ * - `flat`: a non-collapsible header with its items listed beneath (default).
+ * - `group`: a collapsible `<details>` disclosure.
+ * - `page`: a single row that drills into a sub-panel showing only this group's
+ *   items, with a back arrow at the top.
+ */
+const sidebarDisplaySchema = z.enum(["flat", "group", "page"]);
+export type SidebarDisplay = z.infer<typeof sidebarDisplaySchema>;
+
 // ---------------------------------------------------------------------------
 // Page frontmatter
 // ---------------------------------------------------------------------------
 
 const sidebarMetaSchema = z.strictObject({
   badge: z.string().optional(),
+  /**
+   * Render mode for this page's folder group. Only meaningful on a folder's
+   * `index` page — it configures the group, not the page. Overrides the
+   * folder's `meta.ts` `display` and the global `navigation.sidebar.display`.
+   */
+  display: sidebarDisplaySchema.optional(),
   hidden: z.boolean().default(false),
   icon: iconName.optional(),
   label: z.string().optional(),
@@ -141,6 +165,11 @@ export const pageMetaSchema = pageMetaBaseSchema;
 export type PageMeta = z.infer<typeof pageMetaBaseSchema>;
 export type PageMetaInput = z.input<typeof pageMetaBaseSchema>;
 
+/** Built-in page frontmatter keys; custom keys must never redeclare one. */
+const BUILT_IN_PAGE_META_KEYS = new Set<string>(
+  pageMetaBaseSchema.keyof().options
+);
+
 /**
  * A map of custom frontmatter keys to user-supplied validation schemas,
  * consumed through the Standard Schema `~standard` contract — never Zod's own
@@ -162,7 +191,7 @@ const customKeySchemaRecord = (where: string) =>
     .default({})
     .superRefine((value, ctx) => {
       for (const key of Object.keys(value)) {
-        if (Object.hasOwn(pageMetaBaseSchema.shape, key)) {
+        if (BUILT_IN_PAGE_META_KEYS.has(key)) {
           ctx.addIssue({
             code: z.ZodIssueCode.custom,
             message: `"${key}" is a built-in frontmatter field and cannot be redeclared via ${where}.`,
@@ -176,18 +205,10 @@ const customKeySchemaRecord = (where: string) =>
 // Folder meta (meta.ts)
 // ---------------------------------------------------------------------------
 
-/**
- * How a sidebar group renders:
- * - `flat`: a non-collapsible header with its items listed beneath (default).
- * - `group`: a collapsible `<details>` disclosure.
- * - `page`: a single row that drills into a sub-panel showing only this group's
- *   items, with a back arrow at the top.
- */
-const sidebarDisplaySchema = z.enum(["flat", "group", "page"]);
-export type SidebarDisplay = z.infer<typeof sidebarDisplaySchema>;
-
 export const folderMetaSchema = z.strictObject({
   collapsed: z.boolean().optional(),
+  /** Render mode for this group; overrides `navigation.sidebar.display`. */
+  display: sidebarDisplaySchema.optional(),
   icon: iconName.optional(),
   order: z.number().optional(),
   /** Explicit child ordering by slug segment (without numeric prefix). */
@@ -355,11 +376,13 @@ const githubReleasesSourceSchema = z.strictObject({
  */
 const customSourceSchema = z.object({
   source: z.custom<ContentSource>(
-    (val) =>
+    (val): val is ContentSource =>
       typeof val === "object" &&
       val !== null &&
-      typeof (val as { load?: unknown }).load === "function" &&
-      typeof (val as { name?: unknown }).name === "string",
+      "load" in val &&
+      typeof val.load === "function" &&
+      "name" in val &&
+      typeof val.name === "string",
     { message: "custom source must be a ContentSource (with name + load)" }
   ),
   type: z.literal("custom"),
@@ -558,7 +581,7 @@ const localFontSchema = z.strictObject({
 const fontValueSchema = z
   .union([z.string(), remoteFontSchema, localFontSchema])
   .superRefine((value, ctx) => {
-    if (typeof value === "string" && !isFontSlug(value)) {
+    if (isString(value) && !isFontSlug(value)) {
       ctx.addIssue({
         code: z.ZodIssueCode.custom,
         message: `Unknown font "${value}". Supported fonts: ${FONT_SLUGS.join(", ")}. For any other family, use the object form: { name: "..." } (remote provider) or { name: "...", variants: [...] } (local files).`,
@@ -581,7 +604,7 @@ const perModeValueSchema = z
   ])
   .optional()
   .transform((value) =>
-    typeof value === "string" ? { dark: value, light: value } : value
+    isString(value) ? { dark: value, light: value } : value
   );
 
 const themeConfigSchema = z.strictObject({
@@ -592,7 +615,7 @@ const themeConfigSchema = z.strictObject({
     ])
     .default("blue")
     .transform((value) =>
-      typeof value === "string" ? { dark: value, light: value } : value
+      isString(value) ? { dark: value, light: value } : value
     ),
   action: z.string().optional(),
   background: perModeValueSchema,
@@ -682,6 +705,8 @@ const searchConfigSchema = z
   .superRefine((value, ctx) => {
     // Hosted providers can't work without their credentials; flag a missing
     // block with a path so the diagnostic points at `search.<provider>`.
+    // SAFETY: providers without a config block (orama, pagefind, …) miss the
+    // map and read undefined, which the `field &&` guard below absorbs.
     const field =
       PROVIDER_CONFIG_KEY[value.provider as keyof typeof PROVIDER_CONFIG_KEY];
     if (field && !value[field]) {
@@ -718,7 +743,7 @@ const PRIVATE_JWK_PARAMS = ["d", "p", "q", "dp", "dq", "qi", "oth", "k"];
 const publicJwkSchema = z
   .record(z.string(), z.unknown())
   .superRefine((jwk, ctx) => {
-    if (typeof jwk.kty !== "string" || jwk.kty.length === 0) {
+    if (!isString(jwk.kty) || jwk.kty.length === 0) {
       ctx.addIssue({
         code: z.ZodIssueCode.custom,
         message: 'A JWK must declare its key type ("kty").',
@@ -830,7 +855,7 @@ const aiConfigSchema = z.strictObject({
     ])
     .default(true)
     .transform((value) =>
-      typeof value === "boolean" ? { enabled: value, openapi: true } : value
+      isBoolean(value) ? { enabled: value, openapi: true } : value
     ),
   // Serializers for the agent-facing Markdown downlevel (the `.md` mirror,
   // llms-full.txt, MCP get_page), keyed by JSX name. Functions live here —
@@ -842,9 +867,12 @@ const aiConfigSchema = z.strictObject({
   markdownComponents: z
     .record(
       z.string(),
-      z.custom<ComponentMarkdown>((value) => typeof value === "function", {
-        message: "Expected a serializer function.",
-      })
+      z.custom<ComponentMarkdown>(
+        (value): value is ComponentMarkdown => typeof value === "function",
+        {
+          message: "Expected a serializer function.",
+        }
+      )
     )
     .default({}),
   /** Expose the docs as an MCP server for connecting agents. */
@@ -933,7 +961,7 @@ const exportConfigSchema = z
     }),
   ])
   .transform((value) =>
-    typeof value === "boolean" ? { epub: value, pdf: value } : value
+    isBoolean(value) ? { epub: value, pdf: value } : value
   );
 
 /** A configured locale: ISO-ish code plus display metadata for the switcher. */
@@ -990,6 +1018,82 @@ const i18nConfigSchema = z
     }
   });
 
+/**
+ * Version ids must start with a letter (`v1.0`, not `1.0`): the id doubles as
+ * the snapshot directory name, and a leading digit would collide with the
+ * numeric-prefix ordering convention (`01-intro.mdx`), which strips `1.0/` to
+ * `0/`. The rest allows word characters, dots, and hyphens — URL-safe as-is.
+ */
+export const VERSION_ID = /^[A-Za-z][\w.-]*$/u;
+
+/** A frozen documentation snapshot: a directory under the content root. */
+const archivedVersionSchema = z.strictObject({
+  /**
+   * The "you're viewing an old version" notice: `true` for the built-in
+   * message, a string for custom copy, `false` to hide it.
+   */
+  banner: z.union([z.boolean(), z.string()]).default(true),
+  /**
+   * Where this version's pages point their canonical URL: `latest` targets the
+   * same page in the current docs when it still exists (self otherwise), so
+   * search engines treat the live page as authoritative without deindexing
+   * version-only content. `self` keeps every page authoritative.
+   */
+  canonical: z.enum(["latest", "self"]).default("latest"),
+  /** Directory name under the content root, and the URL segment. */
+  id: z
+    .string()
+    .regex(
+      VERSION_ID,
+      'Version ids must start with a letter (e.g. "v1.0") and contain only letters, digits, dots, hyphens, and underscores.'
+    ),
+  /** Switcher label; defaults to the id. */
+  label: z.string().optional(),
+  /** Emit `noindex` on every page of this version. */
+  noindex: z.boolean().default(false),
+});
+
+/**
+ * Docs versioning. Opt-in: the latest docs live at the content root with
+ * unprefixed URLs, and each archived version is a frozen snapshot directory
+ * (`content/docs/<id>/`) cut with `blume version <id>`. Archived means frozen:
+ * snapshots carry their own translations and are never retranslated.
+ */
+const versionsConfigSchema = z
+  .strictObject({
+    /** Frozen snapshots, newest first — this order is the switcher order. */
+    archived: z.array(archivedVersionSchema).default([]),
+    /** Labels the unprefixed tree (the latest docs) in the switcher. */
+    current: z.strictObject({
+      /** Small tag rendered next to the label (e.g. `Latest`). */
+      badge: z.string().optional(),
+      label: z.string(),
+    }),
+    switcher: z
+      .strictObject({
+        /**
+         * Where switching lands when the page has no equivalent in the target
+         * version: `same-page` goes to the equivalent when it exists (version
+         * root otherwise); `root` always goes to the version root.
+         */
+        redirect: z.enum(["same-page", "root"]).default("same-page"),
+      })
+      .prefault({}),
+  })
+  .superRefine((value, ctx) => {
+    const seen = new Set<string>();
+    for (const [position, version] of value.archived.entries()) {
+      if (seen.has(version.id)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `versions.archived declares "${version.id}" more than once.`,
+          path: ["archived", position, "id"],
+        });
+      }
+      seen.add(version.id);
+    }
+  });
+
 const analyticsScriptSchema = z
   .strictObject({
     // Extra attributes (e.g. `data-domain`, `id`) spread onto the <script>.
@@ -1234,11 +1338,22 @@ const githubConfigSchema = z.strictObject({
   repo: z.string(),
 });
 
+/** The theme fields the structural code-theme check inspects. */
+interface CodeThemeFields {
+  colors?: unknown;
+  settings?: unknown;
+  tokenColors?: unknown;
+}
+
+/** A non-null, non-array object — the floor for a theme and its `colors` map. */
+const isThemeObject = <Value>(value: Value): value is Value & CodeThemeFields =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
 const codeThemeSchema = z.custom<CodeTheme>((value) => {
-  if (typeof value === "string") {
+  if (isString(value)) {
     return true;
   }
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+  if (!isThemeObject(value)) {
     return false;
   }
   // Token rules live in `settings` (Shiki's canonical field, also the TextMate
@@ -1246,20 +1361,15 @@ const codeThemeSchema = z.custom<CodeTheme>((value) => {
   // VS Code spelling Shiki falls back to). A colors-only theme (editor fg/bg,
   // no token rules) is also valid — Shiki renders it from `colors` alone. Each
   // field present must have the right shape, and at least one must be present.
-  const theme = value as Record<string, unknown>;
   const settingsValid =
-    theme.settings === undefined || Array.isArray(theme.settings);
+    value.settings === undefined || Array.isArray(value.settings);
   const tokenColorsValid =
-    theme.tokenColors === undefined || Array.isArray(theme.tokenColors);
-  const colorsValid =
-    theme.colors === undefined ||
-    (typeof theme.colors === "object" &&
-      theme.colors !== null &&
-      !Array.isArray(theme.colors));
+    value.tokenColors === undefined || Array.isArray(value.tokenColors);
+  const colorsValid = value.colors === undefined || isThemeObject(value.colors);
   const hasContent =
-    theme.settings !== undefined ||
-    theme.tokenColors !== undefined ||
-    theme.colors !== undefined;
+    value.settings !== undefined ||
+    value.tokenColors !== undefined ||
+    value.colors !== undefined;
   return settingsValid && tokenColorsValid && colorsValid && hasContent;
 }, "Expected a Shiki theme name or custom theme object");
 
@@ -1298,7 +1408,7 @@ const examplesConfigSchema = z
     }),
   ])
   .transform((value): { css?: string; source: string } =>
-    typeof value === "string" ? { source: value } : value
+    isString(value) ? { source: value } : value
   );
 
 /**
@@ -1398,7 +1508,8 @@ const reactConfigSchema = z.strictObject({
 
 /**
  * A single spec rendered by the API reference. `spec` is a local path or an
- * `http(s)` URL (OpenAPI for the Blume renderer; OpenAPI or AsyncAPI for Scalar).
+ * `http(s)` URL (an OpenAPI document under `openapi`, an AsyncAPI document
+ * under `asyncapi`).
  */
 const openapiSourceSchema = z.strictObject({
   /** Include generated pages from this spec in llms.txt/llms-full.txt. */
@@ -1427,6 +1538,35 @@ export type OpenApiSource = z.input<typeof openapiSourceSchema>;
  */
 const scalarConfigSchema = z.record(z.string(), z.unknown()).optional();
 
+/**
+ * The shared shape of both API-reference blocks — only the mount route and
+ * code-sample defaults differ per spec kind, so each block declares just
+ * those.
+ */
+const referenceConfigSchema = (defaults: {
+  codeSamples: string[];
+  route: string;
+}) =>
+  z.strictObject({
+    /** Code-sample languages/tools shown per operation (Blume renderer). */
+    codeSamples: z.array(z.string()).default(defaults.codeSamples),
+    enabled: z.boolean().default(false),
+    /** Start nested schema rows expanded rather than collapsed (Blume renderer). */
+    expandSchemas: z.boolean().default(false),
+    /** Who renders the reference: Blume's own UI, or the embedded Scalar SPA. */
+    renderer: z.enum(["blume", "scalar"]).default("blume"),
+    /** Where the reference mounts. */
+    route: z.string().default(defaults.route),
+    /** Extra Scalar config forwarded to `<ScalarComponent>` (Scalar renderer only). */
+    scalar: scalarConfigSchema,
+    /** One or more specs; each renders on its own route by default. */
+    sources: z.array(openapiSourceSchema).default([]),
+    /** Shorthand for a single source: `sources: [{ spec }]`. */
+    spec: z.string().optional(),
+    /** Scalar theme name (Scalar renderer only). */
+    theme: z.string().optional(),
+  });
+
 /**
  * OpenAPI reference. By default (`renderer: "blume"`) Blume parses the spec with
  * Scalar's parser and renders its own UI: one real page per operation, grouped
@@ -1434,38 +1574,22 @@ const scalarConfigSchema = z.record(z.string(), z.unknown()).optional();
  * `renderer: "scalar"` to fall back to the embedded Scalar SPA (a single
  * self-contained route that doesn't weave into the sidebar or search).
  */
-const openapiConfigSchema = z.strictObject({
-  /** Code-sample languages shown per operation (Blume renderer). */
-  codeSamples: z.array(z.string()).default(["curl", "js", "python"]),
-  enabled: z.boolean().default(false),
-  /** Start nested schema rows expanded rather than collapsed (Blume renderer). */
-  expandSchemas: z.boolean().default(false),
-  /** Who renders the reference: Blume's own UI, or the embedded Scalar SPA. */
-  renderer: z.enum(["blume", "scalar"]).default("blume"),
-  /** Where the reference mounts. */
-  route: z.string().default("/reference"),
-  /** Extra Scalar config forwarded to `<ScalarComponent>` (Scalar renderer only). */
-  scalar: scalarConfigSchema,
-  /** One or more specs; each renders on its own route by default. */
-  sources: z.array(openapiSourceSchema).default([]),
-  /** Shorthand for a single source: `sources: [{ spec }]`. */
-  spec: z.string().optional(),
-  /** Scalar theme name (Scalar renderer only). */
-  theme: z.string().optional(),
+const openapiConfigSchema = referenceConfigSchema({
+  codeSamples: ["curl", "js", "python"],
+  route: "/reference",
 });
 
 /**
- * AsyncAPI reference. Same shape and Scalar pipeline as {@link openapiConfigSchema}
- * (Scalar auto-detects the document type); only the default `route` differs.
+ * AsyncAPI reference. Same shape as {@link openapiConfigSchema}: by default
+ * (`renderer: "blume"`) Blume normalizes the spec to AsyncAPI 3.x and renders
+ * its own UI — one real page per operation — with `renderer: "scalar"` as the
+ * embedded-SPA opt-out. Only the defaults differ: the reference mounts at
+ * `/events`, and empty `codeSamples` means every tool the operation's protocol
+ * binding suggests.
  */
-const asyncapiConfigSchema = z.strictObject({
-  enabled: z.boolean().default(false),
-  route: z.string().default("/events"),
-  /** Extra Scalar config forwarded to `<ScalarComponent>`. */
-  scalar: scalarConfigSchema,
-  sources: z.array(openapiSourceSchema).default([]),
-  spec: z.string().optional(),
-  theme: z.string().optional(),
+const asyncapiConfigSchema = referenceConfigSchema({
+  codeSamples: [],
+  route: "/events",
 });
 
 /**
@@ -1500,7 +1624,7 @@ const tocConfigSchema = z
   ])
   .default(true)
   .transform((value) => {
-    if (typeof value === "boolean") {
+    if (isBoolean(value)) {
       return { enabled: value, maxLevel: 3, minLevel: 2 };
     }
     return {
@@ -1568,8 +1692,26 @@ export const blumeConfigSchema = z
     theme: themeConfigSchema.prefault({}),
     title: z.string().default("Documentation"),
     toc: tocConfigSchema,
+    versions: versionsConfigSchema.optional(),
   })
   .superRefine((config, ctx) => {
+    // A version id that is also a configured locale code would make a leading
+    // `<id>/` directory ambiguous between the two axes — refuse it outright so
+    // detection order (version first, then locale) never has to guess.
+    if (config.versions && config.i18n) {
+      const localeCodes = new Set(
+        config.i18n.locales.map((locale) => locale.code.toLowerCase())
+      );
+      for (const [position, version] of config.versions.archived.entries()) {
+        if (localeCodes.has(version.id.toLowerCase())) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `Version id "${version.id}" is also a configured locale code — rename the version (e.g. "v${version.id}").`,
+            path: ["versions", "archived", position, "id"],
+          });
+        }
+      }
+    }
     // A custom key is declared site-wide (`frontmatter.extend`) or per-type
     // (`content.types`), never both — two schemas for one key would make
     // precedence on pages of that type ambiguous.
@@ -1613,6 +1755,10 @@ export type FrontmatterExtend = Record<string, StandardSchema>;
 export type ResolvedI18nConfig = z.infer<typeof i18nConfigSchema>;
 /** A configured locale with display metadata. */
 export type LocaleConfig = z.infer<typeof localeSchema>;
+/** Resolved versions block (present only when the project opts into versioning). */
+export type ResolvedVersionsConfig = z.infer<typeof versionsConfigSchema>;
+/** A configured archived (frozen) version. */
+export type ArchivedVersionConfig = z.infer<typeof archivedVersionSchema>;
 /**
  * User-authored config, straight off the schema. The public, hand-documented
  * authoring type is `BlumeConfig` in `./config-input.ts`, which a compile-time

package/src/core/sources/assets.ts

@@ -78,6 +78,8 @@ export const materializeAssets = async (
         await writeFile(join(ctx.assetsDir, file), bytes);
         rewrites.set(url, `${ctx.assetsBaseUrl}/${file}`);
       } catch (error) {
+        // SAFETY: everything thrown in this block is an Error — the manual
+        // `!res.ok` throw above, and fetch/fs failures.
         diagnostics.push({
           code: "BLUME_ASSET_FETCH_FAILED",
           message: `Failed to download asset ${url}: ${(error as Error).message}`,

package/src/core/sources/cache.ts

@@ -85,6 +85,9 @@ export const snapshotCache = (cacheDir: string): SnapshotCache => {
   return {
     read: async () => {
       try {
+        // SAFETY: the snapshot file is only ever written by `write` below, from
+        // a `SourceEntry[]` via JSON.stringify; a corrupt file lands in the
+        // catch and reads as empty.
         return JSON.parse(await readFile(file, "utf-8")) as SourceEntry[];
       } catch {
         return [];
@@ -126,6 +129,8 @@ export const loadWithCache = async (
   } catch (error) {
     const fallback = await cache.read();
     if (fallback.length > 0) {
+      // SAFETY: everything thrown on this path is an Error — fetch rejects
+      // with a TypeError and the source adapters throw Error instances.
       const diagnostic: Diagnostic = {
         code: "BLUME_SOURCE_OFFLINE",
         message: `Source "${name}" could not be fetched (${(error as Error).message}); served ${fallback.length} cached entries.`,
@@ -133,6 +138,7 @@ export const loadWithCache = async (
       };
       return { diagnostics: [diagnostic], entries: fallback };
     }
+    // SAFETY: same invariant as above — `fetchEntries` failures are Errors.
     throw new BlumeError({
       code: "BLUME_SOURCE_FETCH_FAILED",
       message: `Source "${name}" failed to load and no cache is available: ${(error as Error).message}`,

package/src/core/sources/github-releases.ts

@@ -2,8 +2,10 @@ import { fromMarkdown } from "mdast-util-from-markdown";
 import { gfmFromMarkdown } from "mdast-util-gfm";
 import { toString as mdastToString } from "mdast-util-to-string";
 import { gfm } from "micromark-extension-gfm";
+import stringWidth from "string-width";
 
 import matter from "../frontmatter.ts";
+import { columnsPrefix } from "../text-width.ts";
 import {
   hashText,
   loadWithCache,
@@ -61,9 +63,10 @@ const LEADING_V = /^v/iu;
 const NON_SLUG = /[^a-z0-9]+/gu;
 const EDGE_DASHES = /^-+|-+$/gu;
 
-// `blume audit` grades meta descriptions against the 110–160 character search
-// snippet range (audit/types.ts thresholds), so the derived summary aims for
-// the longest word-boundary cut under the cap.
+// `blume audit` grades meta descriptions against the 110–160 display-column
+// search snippet range (audit/types.ts thresholds), so the derived summary
+// budgets in the same columns and aims for the longest word-boundary cut
+// under the cap.
 const DESCRIPTION_MAX = 160;
 const DESCRIPTION_MIN = 110;
 
@@ -85,26 +88,6 @@ const NON_PROSE = new Set(["code", "heading", "html", "thematicBreak"]);
  * content kept — then cut at a word boundary to fit the search snippet cap.
  * Undefined when the notes have no prose at all.
  */
-/**
- * The longest prefix of `text` that fits `max` UTF-16 units without cutting
- * inside a grapheme cluster. A bare `String#slice` counts code units, so it
- * can split a surrogate pair (emitting a lone surrogate — invalid Unicode —
- * into a meta description) or halve an emoji sequence. Grapheme segmentation
- * is rule-based (UAX #29), so unlike word segmentation it does not drift
- * across ICU builds.
- */
-const graphemePrefix = (text: string, max: number): string => {
-  let end = 0;
-  const graphemes = new Intl.Segmenter(undefined, { granularity: "grapheme" });
-  for (const { index, segment } of graphemes.segment(text)) {
-    if (index + segment.length > max) {
-      break;
-    }
-    end = index + segment.length;
-  }
-  return text.slice(0, end);
-};
-
 const releaseDescription = (body: string): string | undefined => {
   const tree = fromMarkdown(body.replaceAll(CHANGESET_HASH, "$<mark>"), {
     extensions: [gfm()],
@@ -123,15 +106,17 @@ const releaseDescription = (body: string): string | undefined => {
   if (!text) {
     return undefined;
   }
-  if (text.length <= DESCRIPTION_MAX) {
+  if (stringWidth(text) <= DESCRIPTION_MAX) {
     return text;
   }
   // Cut before the cap at a word boundary (kept only when it doesn't drop the
   // summary under the minimum), shed any dangling punctuation, and mark the cut.
-  const slice = graphemePrefix(text, DESCRIPTION_MAX - 1);
+  const slice = columnsPrefix(text, DESCRIPTION_MAX - 1);
   const boundary = slice.lastIndexOf(" ");
   const head = (
-    boundary >= DESCRIPTION_MIN ? slice.slice(0, boundary) : slice
+    boundary !== -1 && stringWidth(slice.slice(0, boundary)) >= DESCRIPTION_MIN
+      ? slice.slice(0, boundary)
+      : slice
   ).replace(TRAILING_FRAGMENT, "");
   return `${head}…`;
 };
@@ -150,6 +135,19 @@ const githubHeaders = (): Headers => {
   return headers;
 };
 
+/**
+ * The changelog frontmatter one release lowers to. `title`/`type` are always
+ * assigned (optional only so assignment order can keep the emitted YAML key
+ * order — and so each entry's content hash — stable).
+ */
+interface ChangelogFrontmatter {
+  changelog: { category: string; version: string };
+  date: string;
+  seo?: { description: string };
+  title?: string;
+  type?: string;
+}
+
 /**
  * Lower one release to a staged Markdown entry: the notes become the body,
  * `type: changelog` frontmatter (title/date/version/category) drives the
@@ -166,19 +164,25 @@ const releaseToEntry = (release: GithubRelease): SourceEntry => {
   // description (instead of the site-wide fallback) without also rendering the
   // visible lede paragraph a top-level `description` would add.
   const description = releaseDescription(body);
-  const data = {
+  // Assignment order matters: js-yaml serializes keys in insertion order, so
+  // `seo` lands between `date` and `title` exactly as it always has.
+  const data: ChangelogFrontmatter = {
     changelog: { category, version },
     date,
-    ...(description ? { seo: { description } } : {}),
-    title,
-    type: "changelog",
   };
+  if (description) {
+    data.seo = { description };
+  }
+  data.title = title;
+  data.type = "changelog";
   const raw = matter.stringify(`${body}\n`, data);
   const fallbackRef = `release-${release.id}`;
   const ref = `${slugifyTag(release.tag_name) || fallbackRef}.md`;
   return {
     body: { format: "md", text: body },
-    data,
+    // Spread: `SourceEntry.data` is an open dictionary, which the interface
+    // (no index signature) only satisfies as a fresh object literal.
+    data: { ...data },
     editUrl: release.html_url,
     hash: hashText(raw),
     lastModified: date,
@@ -214,6 +218,8 @@ export const githubReleasesSource = (
     if (!res.ok) {
       throw new Error(`${url} -> ${res.status}`);
     }
+    // SAFETY: GitHub's releases endpoint returns a JSON array of release
+    // objects; `GithubRelease` models only the fields the adapter reads.
     return (await res.json()) as GithubRelease[];
   };
 
@@ -253,6 +259,8 @@ export const githubReleasesSource = (
       // repo), degrade to an empty changelog with a warning rather than failing
       // the whole build.
       snapshot = new Map();
+      // SAFETY: everything thrown on this path is an Error — fetch rejects
+      // with a TypeError, fetchPage and loadWithCache throw Error instances.
       return {
         diagnostics: [
           {

package/src/core/sources/mdx-remote.ts

@@ -82,6 +82,8 @@ const enumerateGithub = async (
   if (!res.ok) {
     throw new Error(`${treeUrl} -> ${res.status}`);
   }
+  // SAFETY: GitHub's git/trees endpoint returns this envelope; a missing or
+  // differently-typed field falls through the `?? []` and blob filters below.
   const body = (await res.json()) as {
     tree?: GithubTreeEntry[];
     truncated?: boolean;
@@ -198,6 +200,8 @@ export const mdxRemoteSource = (
             } catch (error) {
               skipped.push({
                 code: "BLUME_SOURCE_FETCH_FAILED",
+                // SAFETY: fetch and decode failures throw Error instances;
+                // only the message is read for the skip diagnostic.
                 message: `Source "${options.name}" skipped "${ref.ref}" (${(error as Error).message}); the rest were imported.`,
                 severity: "warning",
               });