blume 1.4.3 → 1.5.0

package/src/openapi/scalar.ts

@@ -32,9 +32,7 @@ const referencePagePath = (route: string): string => {
   return `${segments === "" ? "index" : segments}.astro`;
 };
 
-const darkModeConfig = (
-  mode: ResolvedConfig["theme"]["mode"]
-): Record<string, boolean> => {
+const darkModeConfig = (mode: ResolvedConfig["theme"]["mode"]) => {
   if (mode === "dark") {
     return { darkMode: true };
   }
@@ -51,10 +49,7 @@ const darkModeConfig = (
  * `customCss`. Scalar re-injects `customCss` after its bundled theme, so these
  * variables reliably override the defaults. Best-effort, not pixel-exact.
  */
-const themeConfiguration = (
-  config: ResolvedConfig,
-  override?: string
-): Record<string, unknown> => {
+const themeConfiguration = (config: ResolvedConfig, override?: string) => {
   if (override) {
     return { theme: override };
   }
@@ -70,7 +65,10 @@ const themeConfiguration = (
 const specConfiguration = async (
   spec: string,
   root: string
-): Promise<{ config: Record<string, unknown>; warning?: string }> => {
+): Promise<{
+  config: { content: string } | { url: string };
+  warning?: string;
+}> => {
   if (URL_SPEC.test(spec)) {
     return { config: { url: spec } };
   }

package/src/openapi/source.ts

@@ -9,19 +9,30 @@ import type {
   SourceLoadResult,
 } from "../core/sources/types.ts";
 import type { Diagnostic } from "../core/types.ts";
+import { extractAsyncApiOperations } from "./asyncapi.ts";
+import type { AsyncApiDocument } from "./asyncapi.ts";
 import { extractOperations } from "./model.ts";
-import type { ApiOperationRef, ApiSpecData, OpenApiData } from "./model.ts";
-import { InvalidSpecError, parseSpec } from "./parse.ts";
+import type {
+  ApiDocument,
+  ApiOperationRef,
+  ApiSpecData,
+  ApiTagRef,
+  OpenApiData,
+} from "./model.ts";
+import { InvalidSpecError, parseAsyncApiSpec, parseSpec } from "./parse.ts";
 import type { ReferenceSource } from "./references.ts";
 import { operationMdx, overviewMdx } from "./render-mdx.ts";
 import type { RenderedPage } from "./render-mdx.ts";
 
 /**
- * The staged content source behind Blume's own OpenAPI renderer. Each configured
- * spec is parsed once here, then lowered into one MDX page per operation plus an
- * overview page — so operations become first-class Blume pages (real routes,
- * sidebar, search, i18n, OG) and the parsed documents are handed to the
- * generated `blume:openapi` module for the UI components to render.
+ * The staged content source behind Blume's own API reference renderer (OpenAPI
+ * and AsyncAPI alike). Each configured spec is parsed once here, then lowered
+ * into one MDX page per operation plus an overview page — so operations become
+ * first-class Blume pages (real routes, sidebar, search, i18n, OG) and the
+ * parsed documents are handed to the generated `blume:openapi` module for the
+ * UI components to render. The source keeps its historical `openapi` name for
+ * both kinds — downstream consumers (`ai.llmsTxt.openapi`, the llms noindex
+ * exemption) key on it as "the generated API reference source".
  */
 
 /** A content source that also exposes the specs it parsed during `load()`. */
@@ -35,7 +46,7 @@ export interface OpenApiContentSource extends ContentSource {
 export const isOpenApiSource = (
   source: ContentSource
 ): source is OpenApiContentSource =>
-  (source as Partial<OpenApiContentSource>).kind === "openapi-source";
+  "kind" in source && source.kind === "openapi-source";
 
 /** Route (`/reference/pet/add-pet`) to a staged content ref, without extension. */
 const routeToRef = (route: string): string => route.replace(/^\/+/u, "");
@@ -44,7 +55,9 @@ const toEntry = (rendered: RenderedPage, ref: string): SourceEntry => {
   const raw = matter.stringify(`${rendered.body}\n`, rendered.data);
   return {
     body: { format: "mdx", text: rendered.body },
-    data: rendered.data,
+    // Spread so the named frontmatter shape satisfies the open metadata
+    // dictionary every source entry carries.
+    data: { ...rendered.data },
     hash: hashText(raw),
     raw,
     ref,
@@ -107,6 +120,50 @@ interface LoadedSpec {
   diagnostics: Diagnostic[];
 }
 
+/** One parsed spec, whichever front-end read it — the kind dispatch seam. */
+interface ParsedReference {
+  document: ApiDocument | AsyncApiDocument;
+  warnings: string[];
+  operations: ApiOperationRef[];
+  tags: ApiTagRef[];
+  extractWarnings: string[];
+}
+
+const parseReference = async (
+  reference: ReferenceSource,
+  ctx: SourceContext
+): Promise<ParsedReference> => {
+  const options = { cacheDir: ctx.cacheDir, refresh: ctx.refresh };
+  if (reference.kind === "asyncapi") {
+    const { document, warnings } = await parseAsyncApiSpec(
+      reference.spec,
+      ctx.projectRoot,
+      options
+    );
+    const extracted = extractAsyncApiOperations(document, reference.route);
+    return {
+      document,
+      extractWarnings: extracted.warnings,
+      operations: extracted.operations,
+      tags: extracted.tags,
+      warnings,
+    };
+  }
+  const { document, warnings } = await parseSpec(
+    reference.spec,
+    ctx.projectRoot,
+    options
+  );
+  const extracted = extractOperations(document, reference.route);
+  return {
+    document,
+    extractWarnings: extracted.warnings,
+    operations: extracted.operations,
+    tags: extracted.tags,
+    warnings,
+  };
+};
+
 export const openApiSource = (
   references: ReferenceSource[],
   ctx: SourceContext
@@ -116,23 +173,21 @@ export const openApiSource = (
   const loadReference = async (
     reference: ReferenceSource
   ): Promise<LoadedSpec | Diagnostic> => {
+    // Human label and diagnostic-code prefix for the spec's kind, so an
+    // AsyncAPI failure never reads as an OpenAPI one.
+    const kindLabel = reference.kind === "asyncapi" ? "AsyncAPI" : "OpenAPI";
+    const codePrefix =
+      reference.kind === "asyncapi" ? "BLUME_ASYNCAPI" : "BLUME_OPENAPI";
     try {
-      const { document, warnings } = await parseSpec(
-        reference.spec,
-        ctx.projectRoot,
-        { cacheDir: ctx.cacheDir, refresh: ctx.refresh }
-      );
-      const {
-        operations,
-        tags,
-        warnings: extractWarnings,
-      } = extractOperations(document, reference.route);
+      const { document, warnings, operations, tags, extractWarnings } =
+        await parseReference(reference, ctx);
       const info = document.info ?? { title: reference.label, version: "" };
       const spec: ApiSpecData = {
         codeSamples: reference.display.codeSamples,
         description: info.description ?? "",
         document,
         expandSchemas: reference.display.expandSchemas,
+        kind: reference.kind,
         label: reference.label,
         // Operation pages flow through the content pipeline, which mounts them
         // under the site-wide `basePath` (staged entry refs below stay
@@ -156,13 +211,24 @@ export const openApiSource = (
       return {
         diagnostics: [
           ...warnings.map((message) => ({
-            code: "BLUME_OPENAPI_STALE",
+            // Parse-level notes: an offline cache fallback for either kind,
+            // plus lossy 2.x→3.0 conversion notes for AsyncAPI — hence the
+            // broader code on that side (OpenAPI keeps its historical one).
+            code:
+              reference.kind === "asyncapi"
+                ? "BLUME_ASYNCAPI_SPEC_WARNING"
+                : "BLUME_OPENAPI_STALE",
             message,
             severity: "warning" as const,
           })),
           ...extractWarnings.map((message) => ({
-            code: "BLUME_OPENAPI_REF_PATH_ITEM",
-            message: `In OpenAPI spec "${reference.spec}": ${message}`,
+            // OpenAPI keeps its historical code (the only extract warning it
+            // emits is the unresolved $ref path item).
+            code:
+              reference.kind === "asyncapi"
+                ? "BLUME_ASYNCAPI_SKIPPED_OPERATION"
+                : "BLUME_OPENAPI_REF_PATH_ITEM",
+            message: `In ${kindLabel} spec "${reference.spec}": ${message}`,
             severity: "warning" as const,
           })),
           // A document with no operations (say, a config file that happens to
@@ -171,11 +237,13 @@ export const openApiSource = (
           ...(operations.length === 0
             ? [
                 {
-                  code: "BLUME_OPENAPI_EMPTY",
-                  message: `OpenAPI spec "${reference.spec}" for ${reference.route} declares no operations; its API reference is empty.`,
+                  code: `${codePrefix}_EMPTY`,
+                  message: `${kindLabel} spec "${reference.spec}" for ${reference.route} declares no operations; its API reference is empty.`,
                   severity: "warning" as const,
                   suggestion:
-                    "Check the spec points at an OpenAPI document with operations under `paths`.",
+                    reference.kind === "asyncapi"
+                      ? "Check the spec points at an AsyncAPI document with `channels` and `operations`."
+                      : "Check the spec points at an OpenAPI document with operations under `paths`.",
                 },
               ]
             : []),
@@ -187,8 +255,10 @@ export const openApiSource = (
       };
     } catch (error) {
       return {
-        code: "BLUME_OPENAPI_UNAVAILABLE",
-        message: `Could not load OpenAPI spec "${reference.spec}" for ${reference.route} (${(error as Error).message}); its reference pages were skipped.`,
+        code: `${codePrefix}_UNAVAILABLE`,
+        // SAFETY: spec loading fails with Error instances (fetch, read, and
+        // parse errors alike); only the message is read for the diagnostic.
+        message: `Could not load ${kindLabel} spec "${reference.spec}" for ${reference.route} (${(error as Error).message}); its reference pages were skipped.`,
         // A configured-but-unloadable spec ships a dead nav tab (a 404 route),
         // so fail loudly in build (blocks under --strict) while staying a warning
         // in dev so offline work still runs.
@@ -197,7 +267,7 @@ export const openApiSource = (
         // only point at reachability for actual fetch/read failures.
         suggestion:
           error instanceof InvalidSpecError
-            ? "Point the spec at an OpenAPI document (a YAML or JSON file with an object at the top level)."
+            ? `Point the spec at ${reference.kind === "asyncapi" ? "an AsyncAPI" : "an OpenAPI"} document (a YAML or JSON file with an object at the top level).`
             : "Check the spec URL/path is reachable from the build environment; behind a proxy, set HTTP(S)_PROXY.",
       };
     }

package/src/registry/eject.ts

@@ -49,6 +49,7 @@ import { scanProject } from "../core/project-graph.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { ProjectContext } from "../core/types.ts";
 import { buildRssFeeds, renderRssFeed } from "../deploy/rss.ts";
+import type { OpenApiData } from "../openapi/model.ts";
 import { hasScalarReferences } from "../openapi/references.ts";
 import { buildReferenceFiles } from "../openapi/scalar.ts";
 import { isOpenApiSource } from "../openapi/source.ts";
@@ -97,7 +98,7 @@ export const blumeSourceGlob = (
 };
 
 /** The `blume:openapi` payload for the ejected app (`{}` when none). */
-const ejectOpenApiData = (project: BlumeProject): unknown => {
+const ejectOpenApiData = (project: BlumeProject): OpenApiData => {
   const source = project.sources.find(isOpenApiSource);
   return source ? source.openApiData() : {};
 };
@@ -126,7 +127,11 @@ const askFiles = async (
   const grounded = ask.provider !== "inkeep";
   const files = [
     {
-      content: askEndpointTemplate(resolveAskBackend(ask), grounded),
+      content: askEndpointTemplate(
+        resolveAskBackend(ask),
+        grounded,
+        ask.instructions
+      ),
       path: join(srcDir, "pages", "api", "ask.ts"),
     },
   ];

package/src/search/documents.ts

@@ -26,6 +26,8 @@ export interface SearchDocument {
   locale: string;
   /** Resolved page `type` (`doc`, `blog`, a custom `rfc`…), for type filters. */
   contentType: string;
+  /** Docs version (`""` for the current docs), so results scope to the viewed version. */
+  version: string;
   /** Frontmatter `search.tags`, surfaced for hosted-provider faceting. */
   tags?: string[];
   /**
@@ -48,6 +50,12 @@ export interface SearchRecord {
   content: string;
   /** Locale code, carried as a facet for per-language filtering. */
   locale: string;
+  /**
+   * Docs version, carried as a facet for per-version filtering. The current
+   * docs upload as `"current"` — hosted backends treat an empty facet value
+   * unreliably, so the sentinel stands in for the empty version id.
+   */
+  version: string;
   /** Single faceting tag (the first frontmatter tag, when present). */
   tag?: string;
 }
@@ -213,10 +221,17 @@ export const buildSearchDocuments = async (
   // locale-prefixed routes), so localized pages get the right section/breadcrumb.
   // Falls back to the single default-locale nav when i18n is off.
   const byLocale = Object.values(project.graph.navigationByLocale ?? {});
-  const sidebars =
-    byLocale.length > 0
+  // Archived versions' trees contribute too, so snapshot pages get their own
+  // section/breadcrumb instead of falling through to the "Docs" default.
+  const byVersion = Object.values(project.graph.navigationByVersion ?? {})
+    .flatMap((locales) => Object.values(locales))
+    .map((nav) => nav.sidebar);
+  const sidebars = [
+    ...(byLocale.length > 0
       ? byLocale.map((nav) => nav.sidebar)
-      : [project.graph.navigation?.sidebar ?? []];
+      : [project.graph.navigation?.sidebar ?? []]),
+    ...byVersion,
+  ];
   const crumbs = new Map<string, Crumbs>();
   for (const sidebar of sidebars) {
     for (const [route, crumb] of buildCrumbIndex(sidebar)) {
@@ -246,18 +261,22 @@ export const buildSearchDocuments = async (
       const tags = page?.meta?.search?.tags;
       const crumb = crumbs.get(route.path);
       const facets = page ? pageFacets(page, project.config) : undefined;
-      return {
+      const document: SearchDocument = {
         breadcrumb: crumb?.breadcrumb ?? [],
         content: body,
         contentType: route.contentType,
         description: page?.description ?? "",
-        ...(facets ? { facets } : {}),
         locale: route.locale,
         route: route.path,
         section: crumb?.section || "Docs",
         tags: tags && tags.length > 0 ? tags : undefined,
         title: route.title,
+        version: route.version,
       };
+      if (facets) {
+        document.facets = facets;
+      }
+      return document;
     })
   );
 };
@@ -276,4 +295,5 @@ export const toSearchRecords = (documents: SearchDocument[]): SearchRecord[] =>
     tag: doc.tags?.[0],
     title: doc.title,
     url: doc.route,
+    version: doc.version || "current",
   }));

package/src/search/facets.ts

@@ -10,6 +10,12 @@ import type { PageRecord } from "../core/types.ts";
  * when nothing facets, so the field stays absent from serialized documents
  * rather than shipping as `{}` on every page.
  */
+/** Whether a custom frontmatter value stringifies into a usable facet value. */
+const isFacetValue = <T>(value: T): value is T & (string | number | boolean) =>
+  typeof value === "string" ||
+  typeof value === "number" ||
+  typeof value === "boolean";
+
 export const pageFacets = (
   page: Pick<PageRecord, "contentType" | "custom">,
   config: ResolvedConfig
@@ -21,11 +27,7 @@ export const pageFacets = (
   const facets: Record<string, string> = {};
   for (const key of declared) {
     const value = page.custom[key];
-    if (
-      typeof value === "string" ||
-      typeof value === "number" ||
-      typeof value === "boolean"
-    ) {
+    if (isFacetValue(value)) {
       facets[key] = String(value);
     }
   }

package/src/search/orama-index.ts

@@ -1,5 +1,10 @@
 import { create, insertMultiple, search } from "@orama/orama";
-import type { AnyOrama, Tokenizer } from "@orama/orama";
+import type {
+  AnyOrama,
+  EnumArrComparisonOperator,
+  EnumComparisonOperator,
+  Tokenizer,
+} from "@orama/orama";
 
 /**
  * The minimal document shape both the client-side search dialog and the
@@ -13,6 +18,11 @@ export interface OramaDoc {
   title: string;
   /** Locale code; indexed as an enum so queries can filter to one language. */
   locale?: string;
+  /**
+   * Docs version; indexed as an enum so queries can filter to one version.
+   * The current docs carry `""`, which the enum stores and matches exactly.
+   */
+  version?: string;
   /** Resolved page `type`; indexed as an enum so queries can filter by type. */
   contentType?: string;
   /** Declared facet values (`content.types.<type>.facets`), key → value. */
@@ -35,6 +45,7 @@ const SCHEMA = {
   locale: "enum",
   route: "string",
   title: "string",
+  version: "enum",
 } as const;
 
 /** Flatten a facet map to the `key:value` terms the `facetTerms` enum holds. */
@@ -141,12 +152,20 @@ const addBigrams = (run: string, tokens: Set<string>): void => {
  * either way — whether they stand between segments, as 「クーリング・オフ」
  * does, or inside one.
  */
+/**
+ * `Intl.Segmenter` is missing on some runtimes even though the lib type
+ * declares it, so the constructor's presence is probed before use.
+ */
+const hasSegmenter = (
+  segmenter: typeof Intl.Segmenter | undefined
+): segmenter is typeof Intl.Segmenter => typeof segmenter === "function";
+
 const segmentingTokenizer = (locale?: string): Tokenizer | undefined => {
   const language = locale?.toLowerCase().split(/[-_]/u)[0] ?? "";
   if (!SEGMENTED_LANGUAGES.has(language)) {
     return;
   }
-  if (typeof Intl.Segmenter !== "function") {
+  if (!hasSegmenter(Intl.Segmenter)) {
     return;
   }
   const segmenter = new Intl.Segmenter(language, { granularity: "word" });
@@ -217,10 +236,9 @@ export const buildOramaIndex = async (
   locale?: string
 ): Promise<AnyOrama> => {
   const tokenizer = segmentingTokenizer(locale);
-  const db = create({
-    schema: SCHEMA,
-    ...(tokenizer ? { components: { tokenizer } } : {}),
-  });
+  const db = tokenizer
+    ? create({ components: { tokenizer }, schema: SCHEMA })
+    : create({ schema: SCHEMA });
   await insertMultiple(
     db,
     documents.map((doc) =>
@@ -244,6 +262,23 @@ export interface OramaQueryFilters {
   facets?: Record<string, string>;
   /** Keep only documents in this locale. */
   locale?: string;
+  /**
+   * Keep only documents of this docs version (`""` is the current docs — a
+   * meaningful filter value, so absence alone disables version filtering).
+   */
+  version?: string;
+}
+
+/**
+ * The exact-match `where` clause the filters compile to. Orama types `where`
+ * openly (any schema property to an operator), mirrored here by the index
+ * signature; this module only ever emits the two enum operators.
+ */
+interface OramaWhereClause {
+  [property: string]:
+    | EnumArrComparisonOperator
+    | EnumComparisonOperator
+    | undefined;
 }
 
 /**
@@ -265,27 +300,38 @@ export const queryOramaIndex = async (
   filters?: OramaQueryFilters
 ): Promise<OramaDoc[]> => {
   const facetTerms = filters?.facets ? toFacetTerms(filters.facets) : [];
-  const where = {
-    ...(filters?.locale ? { locale: { eq: filters.locale } } : {}),
-    ...(filters?.contentTypes && filters.contentTypes.length > 0
-      ? { contentType: { in: filters.contentTypes } }
-      : {}),
-    ...(facetTerms.length > 0
-      ? { facetTerms: { containsAll: facetTerms } }
-      : {}),
-  };
-  const params = {
+  const where: OramaWhereClause = {};
+  if (filters?.locale) {
+    where.locale = { eq: filters.locale };
+  }
+  // `""` (the current docs) is a real filter value, so test for presence.
+  if (filters?.version !== undefined) {
+    where.version = { eq: filters.version };
+  }
+  if (filters?.contentTypes && filters.contentTypes.length > 0) {
+    where.contentType = { in: filters.contentTypes };
+  }
+  if (facetTerms.length > 0) {
+    where.facetTerms = { containsAll: facetTerms };
+  }
+  const unfiltered = {
     boost: BOOST,
     limit,
     properties: ["title", "description", "content"],
     term,
-    ...(Object.keys(where).length > 0 ? { where } : {}),
   };
+  const params =
+    Object.keys(where).length > 0 ? { ...unfiltered, where } : unfiltered;
   const bigrammed = BIGRAM_LANGUAGES.has(db.tokenizer?.language ?? "");
+  // The result-document generic is OramaDoc because `buildOramaIndex` is the
+  // only writer to this database and inserts OramaDoc records (plus the
+  // derived `facetTerms`).
   const strict = bigrammed
-    ? await search(db, { ...params, threshold: ALL_TOKENS })
+    ? await search<AnyOrama, OramaDoc>(db, { ...params, threshold: ALL_TOKENS })
     : undefined;
   const found =
-    strict && strict.hits.length > 0 ? strict : await search(db, params);
-  return found.hits.map((hit) => hit.document as unknown as OramaDoc);
+    strict && strict.hits.length > 0
+      ? strict
+      : await search<AnyOrama, OramaDoc>(db, params);
+  return found.hits.map((hit) => hit.document);
 };

package/src/search/popular.ts

@@ -26,8 +26,13 @@ export const resolveSearchPopular = (
   popular: { href: string; icon?: string; label: string }[],
   basePath: string
 ): SearchPopularPage[] =>
-  popular.map(({ href, icon, label }) => ({
-    ...(icon ? { icon } : {}),
-    label,
-    route: withBasePath(basePath, href),
-  }));
+  popular.map(({ href, icon, label }) => {
+    const page: SearchPopularPage = {
+      label,
+      route: withBasePath(basePath, href),
+    };
+    if (icon) {
+      page.icon = icon;
+    }
+    return page;
+  });

package/src/search/providers.ts

@@ -29,7 +29,7 @@ export interface SearchProviderMeta {
   syncs: boolean;
 }
 
-export const SEARCH_PROVIDERS: Record<SearchProvider, SearchProviderMeta> = {
+export const SEARCH_PROVIDERS = {
   algolia: {
     kind: "hosted",
     requiresServer: false,
@@ -80,7 +80,7 @@ export const SEARCH_PROVIDERS: Record<SearchProvider, SearchProviderMeta> = {
     runtimeDeps: ["typesense"],
     syncs: true,
   },
-};
+} satisfies Record<SearchProvider, SearchProviderMeta>;
 
 export const searchProviderMeta = (
   provider: SearchProvider

package/src/search/sync/index.ts

@@ -45,6 +45,8 @@ export const syncSearchProvider = async (
       `Synced ${records.length} record(s) to ${search.provider}`
     );
   } catch (error) {
+    // SAFETY: the three sync clients surface network/auth failures as Error
+    // instances; the message is read only to annotate the skip warning.
     reporter.warn(`Search sync skipped: ${(error as Error).message}`);
   }
 };

package/src/search/sync/typesense.ts

@@ -56,9 +56,10 @@ export const syncTypesense = async (
       { name: "content", type: "string" },
       { name: "url", type: "string" },
       { facet: true, name: "tag", optional: true, type: "string" },
-      // Carried as a facet so an i18n site can filter hosted results per
-      // language (the SearchRecord contract).
+      // Carried as facets so hosted results can filter per language and per
+      // docs version (the SearchRecord contract; current docs = "current").
       { facet: true, name: "locale", optional: true, type: "string" },
+      { facet: true, name: "version", optional: true, type: "string" },
     ],
     name: config.collection,
   });
@@ -71,6 +72,7 @@ export const syncTypesense = async (
     tag: record.tag,
     title: record.title,
     url: record.url,
+    version: record.version,
   }));
   await client
     .collections(config.collection)

package/src/seo/jsonld.ts

@@ -27,10 +27,25 @@ export interface StructuredDataInput {
 }
 
 /** schema.org `@type` for each content type; defaults to TechArticle. */
-const ARTICLE_TYPES: Record<string, string> = {
+const ARTICLE_TYPES = {
   blog: "BlogPosting",
   changelog: "TechArticle",
-};
+} as const;
+
+/**
+ * `hasOwn` (not a bare index) so a content type named like an
+ * `Object.prototype` member can't resolve a function up the prototype chain.
+ */
+const isArticleType = (value: string): value is keyof typeof ARTICLE_TYPES =>
+  Object.hasOwn(ARTICLE_TYPES, value);
+
+/** A value a schema.org node property can hold. */
+type JsonLdValue = string | number | JsonLdValue[] | JsonLdNode;
+
+/** A schema.org node: JSON-LD keys to concrete JSON values. */
+export interface JsonLdNode {
+  [key: string]: JsonLdValue;
+}
 
 const trimSlash = (value: string): string => value.replace(/\/$/u, "");
 
@@ -59,14 +74,14 @@ export const toIso = (value: DateInput | undefined): string | undefined => {
  */
 export const buildStructuredData = (
   input: StructuredDataInput
-): Record<string, unknown> | null => {
+): JsonLdNode | null => {
   const base = input.siteUrl ? trimSlash(input.siteUrl) : null;
   // Routes carry `basePath`; a `deployment.base` subdirectory is layered on top
   // so JSON-LD URLs match the served location.
   const deployBase = normalizeBasePath(input.base);
   const pageUrl = absolute(base, withBasePath(deployBase, input.route));
   const rootUrl = absolute(base, deployBase);
-  const graph: Record<string, unknown>[] = [];
+  const graph: JsonLdNode[] = [];
 
   if (base) {
     graph.push({
@@ -80,9 +95,12 @@ export const buildStructuredData = (
   // The homepage is fully described by the WebSite node; deeper pages get an
   // article node plus a breadcrumb trail.
   if (input.route !== "/") {
-    const node: Record<string, unknown> = {
+    const pageType = input.pageType ?? "";
+    const node: JsonLdNode = {
       "@id": `${pageUrl}#page`,
-      "@type": ARTICLE_TYPES[input.pageType ?? ""] ?? "TechArticle",
+      "@type": isArticleType(pageType)
+        ? ARTICLE_TYPES[pageType]
+        : "TechArticle",
       headline: input.title,
       inLanguage: input.locale || "en",
       name: input.title,

package/src/seo/x-handle.ts

@@ -1,3 +1,7 @@
+/** Frontmatter defense in depth: only a real string can carry a handle. */
+const isString = <Value>(value: Value): value is Value & string =>
+  typeof value === "string";
+
 /**
  * Normalize an X account to the leading `@` that `twitter:site`/`twitter:creator`
  * require, so `acme`, `@acme`, and `  @acme ` all land on `@acme`. Empty or
@@ -7,10 +11,11 @@
  * Astro's collections carry no schema here, so a page's `seo.x.creator` reaches
  * them as raw frontmatter, and the schema's own transform never runs on it.
  * (Blume's page pipeline does reject a non-string `creator` before the page is
- * built, so `unknown` is defense in depth rather than the expected path.)
+ * built, so the string guard is defense in depth rather than the expected
+ * path.)
  */
-export const normalizeXHandle = (value: unknown): string | undefined => {
-  if (typeof value !== "string") {
+export const normalizeXHandle = <Value>(value: Value): string | undefined => {
+  if (!isString(value)) {
     return;
   }
   const handle = value.trim().replace(/^@+/u, "");