blume 1.4.3 → 1.5.0

package/src/astro/integration.ts

@@ -6,9 +6,20 @@ import { enrichDiagnostic } from "../core/diagnostics.ts";
 import type { Diagnostic } from "../core/types.ts";
 import { markdownVariantUrl, prefersMarkdown } from "./markdown-negotiation.ts";
 
+/** The `{ type: "error" }` payload Vite's browser overlay renders. */
+interface OverlayErrorPayload {
+  err: {
+    id?: string;
+    message: string;
+    plugin: string;
+    stack: string;
+  };
+  type: "error";
+}
+
 /** The dev server's HMR channel — either `.ws` (Vite ≤5) or `.hot` (Vite 6+). */
 interface OverlayChannel {
-  send: (payload: unknown) => void;
+  send: (payload: OverlayErrorPayload) => void;
 }
 interface OverlayServer {
   hot?: OverlayChannel;
@@ -164,7 +175,7 @@ export const blumeIntegration = (
     "astro:server:setup": ({ server }) => {
       // Keep a handle on the dev server so Blume diagnostics can be pushed to
       // its browser error overlay (see `showBlumeErrorOverlay`).
-      overlayServer = server as unknown as OverlayServer;
+      overlayServer = server;
       // Prepend so the rewrite happens before Astro's own request handler,
       // letting the rewritten URL resolve to the `.md` endpoint.
       server.middlewares.stack.unshift({

package/src/astro/islands.ts

@@ -40,13 +40,20 @@ const VALID_MODES = new Set<IslandClientMode>([
   "visible",
 ]);
 
+/** Whether a declared client mode is one Astro's directives support. */
+const isClientMode = (mode: string): mode is IslandClientMode =>
+  // SAFETY: `Set.has` only compares identity at runtime; the assertion widens
+  // the lookup key so the narrower-typed set accepts it, and the `has` result
+  // is exactly the predicate being claimed.
+  VALID_MODES.has(mode as IslandClientMode);
+
 /** Island extensions mapped to the Astro renderer that handles them. */
-const FRAMEWORK_BY_EXT: Record<string, IslandFramework> = {
-  jsx: "react",
-  svelte: "svelte",
-  tsx: "react",
-  vue: "vue",
-};
+const FRAMEWORK_BY_EXT = new Map<string, IslandFramework>([
+  ["jsx", "react"],
+  ["svelte", "svelte"],
+  ["tsx", "react"],
+  ["vue", "vue"],
+]);
 
 // Captures the extension so we can both strip it from the name and pick the
 // framework. Kept in sync with the glob below.
@@ -66,13 +73,13 @@ export const readClientMode = (
   if (!mode) {
     return DEFAULT_CLIENT;
   }
-  if (!VALID_MODES.has(mode as IslandClientMode)) {
+  if (!isClientMode(mode)) {
     warnings.push(
       `Island "${file}" declares an unknown client mode "${mode}"; defaulting to "${DEFAULT_CLIENT}". Use "load", "idle", "visible", or "only".`
     );
     return DEFAULT_CLIENT;
   }
-  return mode as IslandClientMode;
+  return mode;
 };
 
 /**
@@ -109,7 +116,7 @@ export const discoverIslands = async (
   const collectIsland = (file: string, source: string): void => {
     const base = basename(file);
     const ext = base.match(ISLAND_FILE)?.groups?.ext;
-    const framework = ext ? FRAMEWORK_BY_EXT[ext] : undefined;
+    const framework = ext ? FRAMEWORK_BY_EXT.get(ext) : undefined;
     if (!framework) {
       return;
     }

package/src/astro/templates.ts

@@ -37,6 +37,8 @@ const hasWorkspacesField = (pkgPath: string): boolean => {
     return false;
   }
   try {
+    // SAFETY: parsed from the user's own package.json; only the presence of a
+    // `workspaces` field is read, so this loose shape is all the cast claims.
     const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as {
       workspaces?: unknown;
     };
@@ -71,16 +73,19 @@ const findWorkspaceRoot = (start: string): string => {
   }
 };
 
-const ADAPTER_IMPORTS: Record<string, string> = {
+type DeploymentAdapter = NonNullable<ResolvedConfig["deployment"]["adapter"]>;
+
+const ADAPTER_IMPORTS = {
   cloudflare: "@astrojs/cloudflare",
   netlify: "@astrojs/netlify",
   node: "@astrojs/node",
   vercel: "@astrojs/vercel",
-};
+} satisfies Record<DeploymentAdapter, string>;
 
-const ADAPTER_OPTIONS: Record<string, string> = {
-  node: '{ mode: "standalone" }',
-};
+/** Adapter constructor arguments, for the adapters that need any. */
+const ADAPTER_OPTIONS = new Map<DeploymentAdapter, string>([
+  ["node", '{ mode: "standalone" }'],
+]);
 
 const WRANGLER_CONFIG_FILES = [
   "wrangler.jsonc",
@@ -169,8 +174,8 @@ export const runtimeDependencies = (options: {
     deps.push("@astrojs/svelte");
   }
   // The Scalar integration is only declared for a Scalar-rendered reference
-  // (the `renderer: "scalar"` fallback, or AsyncAPI). Blume-rendered OpenAPI
-  // parses at generate time and needs no runtime Scalar dependency.
+  // (the `renderer: "scalar"` opt-out on either block). Blume-rendered
+  // references parse at generate time and need no runtime Scalar dependency.
   if (hasScalarReferences(config)) {
     deps.push("@scalar/astro");
   }
@@ -370,6 +375,12 @@ const renderImageOption = (config: ResolvedConfig): string =>
     ? `\n  image: ${JSON.stringify(config.image)},`
     : "";
 
+/** What `resolveOptimizeDeps` feeds the generated `optimizeDeps` block. */
+interface OptimizeDepsConfig {
+  optimizeDepsEntries: string[];
+  optimizeDepsInclude: string[];
+}
+
 /**
  * Startup-scan entry points and forced includes for the dev dep optimizer:
  * the Vite root is the generated runtime, so user pages, convention islands,
@@ -383,7 +394,7 @@ const resolveOptimizeDeps = (options: {
   context: ProjectContext;
   needsReact: boolean;
   reactCompilerPath: string | null | undefined;
-}): { optimizeDepsEntries: string[]; optimizeDepsInclude: string[] } => {
+}): OptimizeDepsConfig => {
   const { context } = options;
   const optimizeDepsEntries = [
     ...(context.pagesRoot ? [`${context.pagesRoot}/**/*.astro`] : []),
@@ -474,7 +485,7 @@ export const astroConfigTemplate = (options: {
     if (deployment.adapter === "cloudflare") {
       return resolveCloudflareAdapterArgs(context);
     }
-    return ADAPTER_OPTIONS[deployment.adapter] ?? "";
+    return ADAPTER_OPTIONS.get(deployment.adapter) ?? "";
   })();
   // Vercel resolves its Build Output tree and its `@vercel/nft` dependency
   // trace against the Astro root, which for Blume is the hidden `.blume`
@@ -547,19 +558,23 @@ export const astroConfigTemplate = (options: {
               )}, fallbacks: ${JSON.stringify(
                 font.fallbacks
               )}, options: { variants: ${JSON.stringify(
-                font.variants.map((variant) => ({
-                  ...(variant.weight === undefined
-                    ? {}
-                    : { weight: variant.weight }),
-                  ...(variant.style === undefined
-                    ? {}
-                    : { style: variant.style }),
-                  src: [
-                    isAbsolute(variant.src)
-                      ? variant.src
-                      : join(context.root, variant.src),
-                  ],
-                }))
+                font.variants.map((variant) => {
+                  const face: Pick<typeof variant, "style" | "weight"> = {};
+                  if (variant.weight !== undefined) {
+                    face.weight = variant.weight;
+                  }
+                  if (variant.style !== undefined) {
+                    face.style = variant.style;
+                  }
+                  return {
+                    ...face,
+                    src: [
+                      isAbsolute(variant.src)
+                        ? variant.src
+                        : join(context.root, variant.src),
+                    ],
+                  };
+                })
               )} } }`
             : `{ provider: fontProviders.${font.provider}(), name: ${JSON.stringify(
                 font.name
@@ -1095,10 +1110,17 @@ export const createSearch = () => create({ indexUrl${
   } });
 `;
 
+/**
+ * Public credential fields baked into a hosted provider's generated client
+ * (Algolia/Orama Cloud/Typesense config values from `search.*`, all plain
+ * strings or numbers; `JSON.stringify` drops the absent ones).
+ */
+type HostedSearchCredentials = Record<string, string | number | undefined>;
+
 /** A client that passes public credentials straight to the provider SDK. */
 const hostedSearchClient = (
   module: string,
-  options: Record<string, unknown>
+  options: HostedSearchCredentials
 ): string =>
   `${SEARCH_CLIENT_HEADER}${searchClientImport(module)}
 export const createSearch = () => create(${JSON.stringify(options)});
@@ -1107,7 +1129,7 @@ export const createSearch = () => create(${JSON.stringify(options)});
 /** Build the per-provider config object the hosted client is created with. */
 const hostedSearchOptions = (
   search: ResolvedConfig["search"]
-): { module: string; options: Record<string, unknown> } | null => {
+): { module: string; options: HostedSearchCredentials } | null => {
   switch (search.provider) {
     case "algolia": {
       return { module: "algolia", options: { ...search.algolia } };
@@ -1389,7 +1411,9 @@ export const ALL: APIRoute = ({ request }) => handler(request);
 };
 
 /** Generate a prerendered endpoint that serves a fixed JSON payload. */
-export const staticJsonEndpointTemplate = (payload: unknown): string =>
+export const staticJsonEndpointTemplate = <Payload extends object>(
+  payload: Payload
+): string =>
   `// Generated by Blume. Do not edit.
 export const prerender = true;
 
@@ -1510,8 +1534,9 @@ export async function GET({ props }: { props: { title: string } }) {
  * live inside our shell. `dataImport` is the route-depth-aware relative path to
  * the generated data module the layout reads.
  */
-export const scalarReferenceTemplate = (options: {
-  configuration: Record<string, unknown>;
+export const scalarReferenceTemplate = <Configuration extends object>(options: {
+  /** Scalar options forwarded verbatim (spec/theme config plus the author's `scalar` escape hatch). */
+  configuration: Configuration;
   dataImport: string;
   noindex?: boolean;
   route: string;
@@ -1687,11 +1712,13 @@ export function getStaticPaths() {
       locale: route.locale,
       route: route.path,
       title: route.title,
+      version: route.version,
+      versionAlternates: route.versionAlternates,
     },
   }));
 }
 
-const { entryId, collection, route, title, indexable, editUrl, lastModified, locale, alternates, fallback } = Astro.props;
+const { entryId, collection, route, title, indexable, editUrl, lastModified, locale, alternates, fallback, version, versionAlternates } = Astro.props;
 const entry = await getEntry(collection as CollectionKey, entryId);
 if (!entry) {
   return new Response(null, { status: 404 });
@@ -1723,9 +1750,6 @@ const ogGenerated = !seo.image && Boolean(ogPath);
 const x = { ...data.config.x, ...(seo.x?.creator ? { creator: seo.x.creator } : {}) };
 
 const basedRoute = withBase(route);
-const canonical =
-  seo.canonical ??
-  (base ? \`\${base}\${basedRoute === "/" ? "" : encodeURI(basedRoute)}\` : null);
 
 // Locale resolution. With i18n on, pick the active locale's nav + dictionary,
 // build hreflang alternates, and derive the language-switcher targets.
@@ -1746,7 +1770,20 @@ const stripLocale = (path: string, codeArg: string) => {
   return prefix && path.startsWith(prefix) ? path.slice(prefix.length) || "/" : path;
 };
 
-const navigation = i18n ? (data.navigationByLocale[locale] ?? data.navigation) : data.navigation;
+// Version resolution. An archived page renders its snapshot's navigation tree,
+// points its canonical at the latest equivalent (unless configured otherwise),
+// and shows the old-version notice.
+const versionsConfig = data.config.versions;
+const archived = versionsConfig && version
+  ? (versionsConfig.archived.find((v) => v.id === version) ?? null)
+  : null;
+const latestVersionAlt = (versionAlternates ?? []).find((alt) => alt.version === "");
+
+const navigation = version
+  ? (data.navigationByVersion[version]?.[i18n ? locale : ""] ?? data.navigation)
+  : i18n
+    ? (data.navigationByLocale[locale] ?? data.navigation)
+    : data.navigation;
 const ui = i18n ? (data.uiByLocale[locale] ?? data.ui) : data.ui;
 const localeMeta = i18n ? i18n.locales.find((l) => l.code === locale) : null;
 const dir = localeMeta?.dir ?? "ltr";
@@ -1763,6 +1800,19 @@ const absolute = (path: string) => {
   return base + (p === "/" ? "" : p);
 };
 
+// An archived page defaults its canonical to the same page in the latest docs
+// when that page still exists — search engines treat the live page as
+// authoritative without deindexing version-only content. A page's own
+// \`seo.canonical\` always wins, and \`canonical: "self"\` keeps the default.
+const canonical =
+  seo.canonical ??
+  (archived && archived.canonical === "latest" && latestVersionAlt && base
+    ? absolute(latestVersionAlt.path)
+    : base
+      ? \`\${base}\${basedRoute === "/" ? "" : encodeURI(basedRoute)}\`
+      : null);
+const effectiveNoindex = Boolean(seo.noindex) || (archived?.noindex ?? false);
+
 const localeAlternates =
   i18n && base
     ? (alternates ?? []).map((alt) => ({ hreflang: alt.locale, href: absolute(alt.path) }))
@@ -1785,6 +1835,72 @@ const localeSwitch = i18n
     })
   : [];
 
+// Version switcher + old-version notice. The switcher auto-populates from the
+// versions config as a \`kind: "version"\` selector; a user-declared version
+// selector in \`navigation.selectors\` suppresses it (theirs renders instead).
+// Fallback version roots compose like real routes — \`{basePath}/{locale?}/{id}\`
+// (manifest \`versionAlternates\` paths arrive with the base already applied).
+const versionRootFor = (id: string) => {
+  const logical = id ? \`/\${id}\` : "/";
+  const localized = i18n ? localizeRoute(logical, locale) : logical;
+  const mount = data.config.basePath;
+  if (!mount) {
+    return localized;
+  }
+  return localized === "/" ? mount : \`\${mount}\${localized}\`;
+};
+const samePageSwitch = versionsConfig
+  ? versionsConfig.switcher.redirect === "same-page"
+  : true;
+const userHasVersionSelector = navigation.selectors.some(
+  (selector) => selector.kind === "version"
+);
+const versionSelector =
+  versionsConfig && !userHasVersionSelector
+    ? {
+        items: [
+          {
+            id: "",
+            label: versionsConfig.current.label,
+            tag: versionsConfig.current.badge,
+          },
+          ...versionsConfig.archived.map((v) => ({
+            id: v.id,
+            label: v.label ?? v.id,
+            tag: undefined,
+          })),
+        ].map((entry) => {
+          const alt = (versionAlternates ?? []).find(
+            (a) => a.version === entry.id
+          );
+          return {
+            label: entry.label,
+            path: samePageSwitch && alt ? alt.path : versionRootFor(entry.id),
+            ...(entry.tag ? { tag: entry.tag } : {}),
+          };
+        }),
+        kind: "version" as const,
+        label: ui.versions.switcher,
+      }
+    : null;
+
+const versionNotice =
+  archived && archived.banner !== false
+    ? {
+        latestHref: latestVersionAlt
+          ? latestVersionAlt.path
+          : versionRootFor(""),
+        latestLabel: ui.versions.latest,
+        message:
+          typeof archived.banner === "string"
+            ? archived.banner
+            : ui.versions.notice.replace(
+                "{version}",
+                archived.label ?? archived.id
+              ),
+      }
+    : null;
+
 // The whole page shell is overridable via \`layout.Layout\`; it receives the same
 // props as the built-in RootLayout, plus the \`layout\` map for its inner slots.
 const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
@@ -1809,6 +1925,9 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   localeAlternates={localeAlternates}
   xDefault={xDefault}
   localeSwitch={localeSwitch}
+  versionSelector={versionSelector}
+  versionNotice={versionNotice}
+  searchVersion={versionsConfig ? version : null}
   page={{ title: seo.title ?? title, description: seo.description ?? frontmatter.description, route }}
   headings={headings}
   toc={data.config.toc}
@@ -1831,7 +1950,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   pageType={frontmatter.type}
   published={frontmatter.date ?? frontmatter.changelog?.date ?? null}
   lastModified={lastModified}
-  noindex={seo.noindex}
+  noindex={effectiveNoindex}
   structuredDataEnabled={data.config.structuredData}
 >
   <h1>{title}</h1>

package/src/audit/agent.ts

@@ -19,7 +19,7 @@ export interface AgentCli {
 
 export type AgentKind = "claude" | "codex";
 
-export const AGENTS: Record<AgentKind, AgentCli> = {
+export const AGENTS = {
   claude: {
     bin: "claude",
     install: "npm install -g @anthropic-ai/claude-code",
@@ -30,7 +30,7 @@ export const AGENTS: Record<AgentKind, AgentCli> = {
     install: "npm install -g @openai/codex",
     name: "Codex",
   },
-};
+} satisfies Record<AgentKind, AgentCli>;
 
 /**
  * Write the full JSON report where the agent can read it. A file rather than

package/src/audit/checks/content.ts

@@ -1,3 +1,5 @@
+import stringWidth from "string-width";
+
 import matter from "../../core/frontmatter.ts";
 import type { Diagnostic } from "../../core/types.ts";
 import { finding } from "../catalog.ts";
@@ -5,6 +7,17 @@ import { pageSite } from "../locate.ts";
 import { ERROR_ROUTES } from "../types.ts";
 import type { AuditContext, CheckModule, PageSnapshot } from "../types.ts";
 
+// Extraction trims only the ends; interior runs of whitespace (a <title>
+// authored across indented source lines) survive. A search engine collapses
+// them to single spaces before rendering, so the width is measured on the
+// collapsed text — source formatting must not move a page across a threshold.
+const WHITESPACE = /\s+/gu;
+
+/** Whether front matter `date` arrived in one of YAML's two date spellings. */
+const isDateValue = (
+  value: string | Date | undefined
+): value is string | Date => typeof value === "string" || value instanceof Date;
+
 /**
  * The `date` a source file's front matter declares, when it parses to a real
  * date. YAML hands back a `Date` for an unquoted `2026-01-01` and a string for
@@ -14,8 +27,8 @@ import type { AuditContext, CheckModule, PageSnapshot } from "../types.ts";
  */
 const frontmatterDate = (source: string): Date | null => {
   try {
-    const { date } = matter(source).data as { date?: unknown };
-    if (typeof date !== "string" && !(date instanceof Date)) {
+    const { date } = matter(source).data;
+    if (!isDateValue(date)) {
       return null;
     }
     const parsed = date instanceof Date ? date : new Date(date);
@@ -52,13 +65,16 @@ const titleChecks = (
       )
     );
   }
-  if (title.length > titleMax || title.length < titleMin) {
-    const direction = title.length > titleMax ? "long" : "short";
+  // Columns, not characters: a search engine truncates by the space the text
+  // takes up. See {@link AuditThresholds}.
+  const width = stringWidth(title.replaceAll(WHITESPACE, " "));
+  if (width > titleMax || width < titleMin) {
+    const direction = width > titleMax ? "long" : "short";
     found.push(
       finding(
         "BLUME_AUDIT_TITLE_LENGTH",
         pageSite(context, page, ["title"]),
-        `Title is ${title.length} characters — too ${direction} (aim for ${titleMin}–${titleMax}).`
+        `Title renders ${width} columns wide — too ${direction} (aim for ${titleMin}–${titleMax}).`
       )
     );
   }
@@ -99,16 +115,15 @@ const descriptionChecks = (
       )
     );
   }
-  if (
-    description.length > descriptionMax ||
-    description.length < descriptionMin
-  ) {
-    const direction = description.length > descriptionMax ? "long" : "short";
+  // Columns, not characters. See {@link AuditThresholds}.
+  const width = stringWidth(description.replaceAll(WHITESPACE, " "));
+  if (width > descriptionMax || width < descriptionMin) {
+    const direction = width > descriptionMax ? "long" : "short";
     found.push(
       finding(
         "BLUME_AUDIT_DESCRIPTION_LENGTH",
         pageSite(context, page, ["description"]),
-        `Meta description is ${description.length} characters — too ${direction} (aim for ${descriptionMin}–${descriptionMax}).`
+        `Meta description renders ${width} columns wide — too ${direction} (aim for ${descriptionMin}–${descriptionMax}).`
       )
     );
   }

package/src/audit/checks/dns-aid.ts

@@ -68,6 +68,9 @@ const fetchDohJson = async (
     if (!response.ok) {
       return null;
     }
+    // SAFETY: the resolver answered a dns-json query, whose response schema
+    // DohResponse models with every field optional; a malformed body that
+    // fails to parse rejects into the catch below.
     return (await response.json()) as DohResponse;
   } catch {
     return null;

package/src/audit/checks/indexability.ts

@@ -101,13 +101,31 @@ const canonicalChecks = (
       )
     );
   } else if (context.byUrl.has(target)) {
-    found.push(
-      finding(
-        "BLUME_AUDIT_CANONICAL_NOT_SELF",
-        pageSite(context, page, ["seo", "canonical"]),
-        `Page declares ${target} as its canonical, so it will not be indexed itself.`
-      )
+    // An archived-version page pointing at its latest equivalent is Blume's
+    // own default (versions.archived[].canonical: "latest"), not a defect —
+    // the live page is the authoritative one by design.
+    const version = page.route?.version;
+    const archived = version
+      ? context.project.config.versions?.archived.find(
+          (entry) => entry.id === version
+        )
+      : undefined;
+    const latestAlternate = page.route?.versionAlternates.find(
+      (alternate) => alternate.version === ""
     );
+    const intentional =
+      archived?.canonical === "latest" &&
+      latestAlternate !== undefined &&
+      normalizePath(latestAlternate.path) === target;
+    if (!intentional) {
+      found.push(
+        finding(
+          "BLUME_AUDIT_CANONICAL_NOT_SELF",
+          pageSite(context, page, ["seo", "canonical"]),
+          `Page declares ${target} as its canonical, so it will not be indexed itself.`
+        )
+      );
+    }
   } else {
     found.push(
       finding(

package/src/audit/checks/llms.ts

@@ -6,12 +6,17 @@ import { ERROR_ROUTES } from "../types.ts";
 import type { AuditContext, CheckModule } from "../types.ts";
 import { normalizePath, siteOrigin } from "../url.ts";
 
+/** The object form of `ai.llmsTxt`. The schema always emits it, but hand-built
+ * audit contexts (tests, partial configs) may still carry the raw boolean. */
+const isLlmsToggleObject = (
+  value: boolean | { enabled: boolean; openapi: boolean } | undefined
+): value is { enabled: boolean; openapi: boolean } =>
+  typeof value === "object" && value !== null;
+
 /** The `ai.llmsTxt` config normalized to what the checks need. */
-const llmsConfig = (
-  context: AuditContext
-): { enabled: boolean; openapi: boolean } => {
+const llmsConfig = (context: AuditContext) => {
   const value = context.project.config.ai?.llmsTxt;
-  if (typeof value === "object" && value !== null) {
+  if (isLlmsToggleObject(value)) {
     return { enabled: value.enabled, openapi: value.openapi };
   }
   return { enabled: value !== false, openapi: true };

package/src/audit/checks/network.ts

@@ -252,6 +252,8 @@ export const externalChecks: CheckModule = {
       if (!result) {
         continue;
       }
+      // SAFETY: every `linkers` entry is created with its linking page and only
+      // ever appended to, so the array is never empty.
       const site = pageSite(context, pages[0] as PageSnapshot);
 
       const grade = gradeExternal(result);

package/src/audit/checks/social.ts

@@ -89,6 +89,18 @@ export const socialChecks: CheckModule = {
   tier: "static",
 };
 
+/** The JSON-LD keywords the audit reads off a parsed block. */
+interface JsonLdNode {
+  "@context"?: unknown;
+  "@graph"?: unknown;
+  "@type"?: unknown;
+}
+
+/** Whether one parsed JSON-LD value is an object the keyword checks can read. */
+const isJsonLdNode = (
+  value: PageSnapshot["jsonld"][number]
+): value is JsonLdNode => typeof value === "object" && value !== null;
+
 /**
  * What's missing from one JSON-LD block.
  *
@@ -98,28 +110,24 @@ export const socialChecks: CheckModule = {
  * and each entry carries its own `@type` — so demanding `@type` on the root, or
  * `@context` on each entry, would flag perfectly valid structured data.
  */
-const jsonLdProblems = (node: unknown): string[] => {
-  if (typeof node !== "object" || node === null) {
+const jsonLdProblems = (node: PageSnapshot["jsonld"][number]): string[] => {
+  if (!isJsonLdNode(node)) {
     return ["it is not an object"];
   }
-  const record = node as Record<string, unknown>;
   const problems: string[] = [];
-  if (!record["@context"]) {
+  if (!node["@context"]) {
     problems.push("@context");
   }
 
-  const graph = record["@graph"];
+  const graph = node["@graph"];
   if (Array.isArray(graph)) {
     const untyped = graph.filter(
-      (entry) =>
-        typeof entry !== "object" ||
-        entry === null ||
-        !(entry as Record<string, unknown>)["@type"]
+      (entry) => !isJsonLdNode(entry) || !entry["@type"]
     ).length;
     if (untyped > 0) {
       problems.push(`@type on ${untyped} of its ${graph.length} @graph nodes`);
     }
-  } else if (!record["@type"]) {
+  } else if (!node["@type"]) {
     problems.push("@type");
   }