blume 0.7.0 → 1.0.0

package/src/openapi/render-mdx.ts

@@ -58,6 +58,61 @@ export interface RenderedPage {
   body: string;
 }
 
+// Meta descriptions. A page that sets none falls back to the site-wide default,
+// so a spec's pages would otherwise all ship one identical description — what
+// search engines treat as duplicate content. These go in `seo.description`, not
+// `description`: the prose already renders in the body, and a `description`
+// frontmatter field would print it a second time as the page subtitle.
+const META_DESCRIPTION_MAX = 160;
+const PARAGRAPH_BREAK = /\n\s*\n/u;
+const MARKDOWN_LINK = /\[(?<text>[^\]]*)\]\([^)]*\)/gu;
+const MARKDOWN_MARKS = /[*_`#>]/gu;
+const WHITESPACE = /\s+/gu;
+const TRAILING_WORD = /\s+\S*$/u;
+
+/** Flatten markdown prose to its first paragraph as single-line plain text. */
+const plainProse = (markdown: string): string =>
+  (markdown.trim().split(PARAGRAPH_BREAK).at(0) ?? "")
+    .replace(MARKDOWN_LINK, "$<text>")
+    .replace(MARKDOWN_MARKS, "")
+    .replace(WHITESPACE, " ")
+    .trim();
+
+/** Cap `text` at `max` characters, cutting on a word boundary. */
+const clip = (text: string, max: number): string => {
+  if (max <= 0) {
+    return "";
+  }
+  if (text.length <= max) {
+    return text;
+  }
+  const head = text.slice(0, max - 1);
+  const onWordBoundary = head.replace(TRAILING_WORD, "");
+  // One very long token — an endpoint path has no spaces — would be dropped
+  // whole, leaving a stub. Hard-cut it instead of losing it.
+  return `${onWordBoundary.length >= max / 2 ? onWordBoundary : head}…`;
+};
+
+const apiName = (spec: ApiSpecData): string => spec.title || spec.label;
+
+/**
+ * The spec's own prose for the operation, followed by the endpoint it documents
+ * — so every operation page carries a distinct, self-describing meta
+ * description even when the spec's summaries are terse.
+ */
+const operationDescription = (
+  spec: ApiSpecData,
+  operation: ApiOperationRef
+): string => {
+  const endpoint = `${operation.method.toUpperCase()} ${operation.path}`;
+  const suffix = `Reference for the ${endpoint} endpoint in the ${apiName(spec)} API.`;
+  const prose = clip(
+    plainProse(operation.description || operation.summary),
+    META_DESCRIPTION_MAX - suffix.length - 1
+  );
+  return clip([prose, suffix].filter(Boolean).join(" "), META_DESCRIPTION_MAX);
+};
+
 /** Prepend a markdown description (if any) above a component invocation. */
 const withDescription = (description: string, component: string): string =>
   description.trim()
@@ -84,6 +139,7 @@ export const operationMdx = (
     data: {
       ...(operation.deprecated ? { deprecated: true } : {}),
       search: { tags: [operation.tag, method] },
+      seo: { description: operationDescription(spec, operation) },
       sidebar: { badge: method, label: operation.summary || operation.path },
       title,
       // Signals the two-column API layout (request panel instead of the TOC).
@@ -144,8 +200,13 @@ export const overviewMdx = (spec: ApiSpecData): RenderedPage => {
       ...tagSections,
     ].join("\n\n"),
     data: {
+      seo: {
+        description:
+          clip(plainProse(spec.description), META_DESCRIPTION_MAX) ||
+          `${apiName(spec)} API reference.`,
+      },
       sidebar: { label: "Overview" },
-      title: spec.title || spec.label,
+      title: apiName(spec),
     },
   };
 };

package/src/openapi/source.ts

@@ -1,3 +1,4 @@
+import { withBasePath } from "../core/base-path.ts";
 import matter from "../core/frontmatter.ts";
 import { hashText } from "../core/sources/cache.ts";
 import type {
@@ -9,7 +10,7 @@ import type {
 import type { Diagnostic } from "../core/types.ts";
 import { extractOperations } from "./model.ts";
 import type { ApiOperationRef, ApiSpecData, OpenApiData } from "./model.ts";
-import { parseSpec } from "./parse.ts";
+import { InvalidSpecError, parseSpec } from "./parse.ts";
 import type { ReferenceSource } from "./references.ts";
 import { operationMdx, overviewMdx } from "./render-mdx.ts";
 import type { RenderedPage } from "./render-mdx.ts";
@@ -90,7 +91,11 @@ export const openApiSource = (
         ctx.projectRoot,
         { cacheDir: ctx.cacheDir, refresh: ctx.refresh }
       );
-      const { operations, tags } = extractOperations(document, reference.route);
+      const {
+        operations,
+        tags,
+        warnings: extractWarnings,
+      } = extractOperations(document, reference.route);
       const info = document.info ?? { title: reference.label, version: "" };
       const spec: ApiSpecData = {
         codeSamples: reference.display.codeSamples,
@@ -98,8 +103,18 @@ export const openApiSource = (
         document,
         expandSchemas: reference.display.expandSchemas,
         label: reference.label,
+        // Operation pages flow through the content pipeline, which mounts them
+        // under the site-wide `basePath` (staged entry refs below stay
+        // base-less); serialize the served route so components link to the
+        // pages' real URLs.
         operations: Object.fromEntries(
-          operations.map((operation) => [operation.key, operation])
+          operations.map((operation) => [
+            operation.key,
+            {
+              ...operation,
+              route: withBasePath(reference.basePath, operation.route),
+            },
+          ])
         ),
         route: reference.route,
         slug: reference.slug,
@@ -108,11 +123,32 @@ export const openApiSource = (
         version: info.version ?? "",
       };
       return {
-        diagnostics: warnings.map((message) => ({
-          code: "BLUME_OPENAPI_STALE",
-          message,
-          severity: "warning" as const,
-        })),
+        diagnostics: [
+          ...warnings.map((message) => ({
+            code: "BLUME_OPENAPI_STALE",
+            message,
+            severity: "warning" as const,
+          })),
+          ...extractWarnings.map((message) => ({
+            code: "BLUME_OPENAPI_REF_PATH_ITEM",
+            message: `In OpenAPI spec "${reference.spec}": ${message}`,
+            severity: "warning" as const,
+          })),
+          // A document with no operations (say, a config file that happens to
+          // parse as YAML) would otherwise build a nav tab onto an empty
+          // reference with no hint why.
+          ...(operations.length === 0
+            ? [
+                {
+                  code: "BLUME_OPENAPI_EMPTY",
+                  message: `OpenAPI 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`.",
+                },
+              ]
+            : []),
+        ],
         entries: specEntries(spec, operations),
         slug: reference.slug,
         spec,
@@ -125,8 +161,12 @@ export const openApiSource = (
         // so fail loudly in build (blocks under --strict) while staying a warning
         // in dev so offline work still runs.
         severity: ctx.mode === "build" ? "error" : "warning",
+        // A readable-but-invalid file is a content problem, not a network one;
+        // only point at reachability for actual fetch/read failures.
         suggestion:
-          "Check the spec URL/path is reachable from the build environment; behind a proxy, set HTTP(S)_PROXY.",
+          error instanceof InvalidSpecError
+            ? "Point the spec at 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.",
       };
     }
   };
@@ -134,7 +174,16 @@ export const openApiSource = (
   const load = async (): Promise<SourceLoadResult> => {
     const results = await Promise.all(references.map(loadReference));
     const entries: SourceEntry[] = [];
-    const diagnostics: Diagnostic[] = [];
+    // Route collisions recorded while deduping (see `blumeReferences`): a
+    // dropped source loses a whole spec's pages, so warn even when the kept
+    // spec loads cleanly.
+    const diagnostics: Diagnostic[] = references.flatMap((reference) =>
+      (reference.collisions ?? []).map((message) => ({
+        code: "BLUME_OPENAPI_ROUTE_COLLISION",
+        message,
+        severity: "warning" as const,
+      }))
+    );
     const data: OpenApiData = {};
     for (const result of results) {
       if ("severity" in result) {

package/src/registry/eject.ts

@@ -6,6 +6,8 @@ import { join, relative } from "pathe";
 import { buildAskData } from "../ai/ask-data.ts";
 import { resolveAskBackend } from "../ai/ask.ts";
 import { buildRawMarkdown } from "../ai/markdown.ts";
+import { buildMcpData } from "../ai/mcp/data.ts";
+import { buildMcpDiscovery, buildMcpServerCard } from "../ai/mcp/discovery.ts";
 import { planComponentSlots } from "../astro/component-slots.ts";
 import { discoverExamples } from "../astro/examples.ts";
 import {
@@ -20,6 +22,7 @@ import {
   askEndpointTemplate,
   astroConfigTemplate,
   catchAllPageTemplate,
+  changelogIndexTemplate,
   contentConfigTemplate,
   envTemplate,
   exampleMapTemplate,
@@ -28,6 +31,8 @@ import {
   exampleSlug,
   islandMapTemplate,
   islandWrapperTemplate,
+  mcpEndpointTemplate,
+  mcpPageFile,
   mixedbreadSearchEndpointTemplate,
   notFoundPageTemplate,
   ogEndpointTemplate,
@@ -36,7 +41,9 @@ import {
   runtimeTsconfigTemplate,
   searchClientTemplate,
   searchEndpointTemplate,
+  staticJsonEndpointTemplate,
 } from "../astro/templates.ts";
+import { packageRoot } from "../core/package-root.ts";
 import { scanProject } from "../core/project-graph.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { ProjectContext } from "../core/types.ts";
@@ -55,6 +62,39 @@ import { twoslashCss } from "../theme/twoslash.ts";
 
 const toPosix = (path: string): string => path.split("\\").join("/");
 
+/** The portable `@source` guess: blume in the project's own node_modules. */
+const LOCAL_BLUME_SOURCE = "../../node_modules/blume/src/**/*.{astro,ts,tsx}";
+
+/**
+ * The `@source` glob pointing Tailwind at Blume's own source, relative to the
+ * ejected `src/generated/app.css`. The project-local `node_modules/blume` is
+ * preferred (portable, and under pnpm the symlink survives version bumps), but
+ * hoisted installs (npm/yarn workspaces lift blume into the workspace root's
+ * node_modules) would make that guess match nothing and silently drop utility
+ * classes — so fall back to the package's real installed location, and when
+ * even that fails, warn instead of failing silently.
+ *
+ * Exported for testing.
+ */
+export const blumeSourceGlob = (
+  root: string,
+  genDir: string,
+  resolveBlumeRoot: () => string = packageRoot
+): string => {
+  if (existsSync(join(root, "node_modules", "blume"))) {
+    return LOCAL_BLUME_SOURCE;
+  }
+  try {
+    const src = join(resolveBlumeRoot(), "src");
+    return `${toPosix(relative(genDir, src))}/**/*.{astro,ts,tsx}`;
+  } catch {
+    console.warn(
+      'blume: could not locate the installed blume package; src/generated/app.css keeps its default `@source "../../node_modules/blume/..."` glob. If blume is hoisted elsewhere, point that glob at its install location or Blume\'s utility classes will be missing.'
+    );
+    return LOCAL_BLUME_SOURCE;
+  }
+};
+
 /** The `blume:openapi` payload for the ejected app (`{}` when none). */
 const ejectOpenApiData = (project: BlumeProject): unknown => {
   const source = project.sources.find(isOpenApiSource);
@@ -90,6 +130,112 @@ const askFiles = async (
   return files;
 };
 
+/** Whether the ejected app hosts the MCP server (enabled and route free). */
+const hostsMcp = (
+  project: BlumeProject,
+  userPages: { pattern: string }[]
+): boolean =>
+  project.config.mcp.enabled &&
+  !routeIsTaken(userPages, project.graph.pages, project.config.mcp.route);
+
+/**
+ * The `.well-known` MCP discovery routes, injected as prerendered pages
+ * alongside the user's own so the ejected Astro config wires them in. Empty
+ * when the server is disabled or its route is already owned by a page.
+ */
+const mcpDiscoveryPages = (
+  project: BlumeProject,
+  userPages: { pattern: string }[]
+): { entrypoint: string; pattern: string }[] =>
+  hostsMcp(project, userPages)
+    ? [
+        {
+          entrypoint: "src/blume-mcp/discovery.ts",
+          pattern: "/.well-known/mcp.json",
+        },
+        {
+          entrypoint: "src/blume-mcp/server-card.ts",
+          pattern: "/.well-known/mcp/server-card.json",
+        },
+      ]
+    : [];
+
+/**
+ * The MCP data snapshot, server endpoint, and `.well-known` discovery
+ * documents, mirroring `writeMcpFiles` in generate.ts. Empty when the server
+ * is disabled or its route is already owned by a page.
+ */
+const mcpFiles = async (
+  project: BlumeProject,
+  userPages: { pattern: string }[],
+  srcDir: string,
+  genDir: string
+): Promise<{ content: string; path: string }[]> => {
+  if (!hostsMcp(project, userPages)) {
+    return [];
+  }
+  const { route } = project.config.mcp;
+  const data = await buildMcpData(project);
+  const discoveryInput = {
+    base: data.base,
+    name: data.name,
+    route,
+    site: data.site,
+    version: data.version,
+  };
+  return [
+    {
+      content: `${JSON.stringify(data)}\n`,
+      path: join(genDir, "mcp-data.json"),
+    },
+    {
+      content: mcpEndpointTemplate(route),
+      path: join(srcDir, "pages", mcpPageFile(route)),
+    },
+    {
+      content: staticJsonEndpointTemplate(buildMcpDiscovery(discoveryInput)),
+      path: join(srcDir, "blume-mcp", "discovery.ts"),
+    },
+    {
+      content: staticJsonEndpointTemplate(buildMcpServerCard(discoveryInput)),
+      path: join(srcDir, "blume-mcp", "server-card.ts"),
+    },
+  ];
+};
+
+/**
+ * The `/changelog` index page, mirroring `shouldGenerateChangelog` in
+ * generate.ts: emitted when `type: changelog` entries or a release-backed
+ * changelog source exist, unless a user page already owns the route.
+ */
+const changelogFiles = (
+  project: BlumeProject,
+  userPages: { pattern: string }[],
+  srcDir: string,
+  options: Parameters<typeof changelogIndexTemplate>[0]
+): { content: string; path: string }[] => {
+  const hasChangelog = project.graph.pages.some(
+    (page) =>
+      page.contentType === "changelog" &&
+      !(page.meta.draft || page.meta.sidebar.hidden)
+  );
+  const hasChangelogSource = (project.config.content.sources ?? []).some(
+    (source) => source.type === "github-releases"
+  );
+  if (
+    !(hasChangelog || hasChangelogSource) ||
+    routeIsTaken(userPages, project.graph.pages, "/changelog")
+  ) {
+    return [];
+  }
+  return [
+    {
+      content: changelogIndexTemplate(options),
+      path: join(srcDir, "pages", "changelog.astro"),
+    },
+  ];
+};
+
 /** Contents of the configured `examples.css`, or `""` when unset/absent. */
 const readExamplesCss = (
   root: string,
@@ -129,9 +275,13 @@ const examplesPreviewFiles = (
  * eject the project has a normal `astro.config.mjs` and `src/`, the `blume` CLI
  * is no longer required, and the `blume` package remains importable.
  *
- * Returns the list of written files.
+ * Returns the written files plus non-fatal warnings, mirroring the generated
+ * runtime (e.g. a Scalar reference spec that wasn't found, or a reference
+ * route colliding with a content page).
  */
-export const eject = async (root: string): Promise<string[]> => {
+export const eject = async (
+  root: string
+): Promise<{ files: string[]; warnings: string[] }> => {
   const project = await scanProject(root, { mode: "build" });
   const { context, config } = project;
 
@@ -183,10 +333,13 @@ export const eject = async (root: string): Promise<string[]> => {
   const componentsImport = context.componentsFile
     ? `../../${toPosix(relative(root, context.componentsFile))}`
     : null;
-  const relPages = pages.map((page) => ({
-    entrypoint: toPosix(relative(root, page.entrypoint)),
-    pattern: page.pattern,
-  }));
+  const relPages = [
+    ...pages.map((page) => ({
+      entrypoint: toPosix(relative(root, page.entrypoint)),
+      pattern: page.pattern,
+    })),
+    ...mcpDiscoveryPages(project, pages),
+  ];
 
   // Non-filesystem sources eject their materialized MDX into `<root>/blume-staged`
   // (a dedicated dir so it never clashes with a content root literally named
@@ -275,9 +428,11 @@ export const eject = async (root: string): Promise<string[]> => {
     {
       content: tailwindEntryTemplate({
         configTokens: buildThemeCss(config.theme),
-        // Relative paths from src/generated/app.css keep the ejected app portable.
+        // Relative paths from src/generated/app.css keep the ejected app
+        // portable; the blume glob resolves the real install location when
+        // the package is hoisted out of the project's own node_modules.
         sources: [
-          "../../node_modules/blume/src/**/*.{astro,ts,tsx}",
+          blumeSourceGlob(root, genDir),
           "../../**/*.{astro,mdx,ts,tsx}",
         ],
         twoslashCss: twoslashCss(),
@@ -295,11 +450,11 @@ export const eject = async (root: string): Promise<string[]> => {
       path: join(genDir, "raw-markdown.json"),
     },
     {
-      content: rawMarkdownEndpointTemplate(),
+      content: rawMarkdownEndpointTemplate("md"),
       path: join(srcDir, "pages", "[...slug].md.ts"),
     },
     {
-      content: rawMarkdownEndpointTemplate(),
+      content: rawMarkdownEndpointTemplate("mdx"),
       path: join(srcDir, "pages", "[...slug].mdx.ts"),
     },
   ];
@@ -315,6 +470,19 @@ export const eject = async (root: string): Promise<string[]> => {
     });
   }
 
+  // The hosted MCP server and the `/changelog` index, mirrored from the
+  // generated runtime (each helper returns `[]` when its feature is off).
+  files.push(
+    ...(await mcpFiles(project, pages, srcDir, genDir)),
+    ...changelogFiles(project, pages, srcDir, {
+      askEnabled,
+      exportEpub,
+      exportPdf,
+      needsReact,
+      staged: hasStaged,
+    })
+  );
+
   // Default 404 page, unless the project already owns `/404` (a custom
   // `pages/404.astro` or a `404.md` content page). The ejected project owns the
   // file afterwards and can edit or remove it.
@@ -372,13 +540,17 @@ export const eject = async (root: string): Promise<string[]> => {
   }
 
   // Scalar API/AsyncAPI reference pages, mirrored from the generated runtime so
-  // the ejected app keeps its reference routes.
+  // the ejected app keeps its reference routes — including the warnings (a
+  // missing spec file, a route collision), which the caller surfaces exactly
+  // like the generated-runtime path does.
+  const warnings: string[] = [];
   if (hasScalarReferences(config)) {
     const references = await buildReferenceFiles({
       config,
       contentRoutes: new Set(project.graph.pages.map((page) => page.route)),
       root,
     });
+    warnings.push(...references.warnings);
     for (const file of references.files) {
       files.push({
         content: file.content,
@@ -433,5 +605,5 @@ export const eject = async (root: string): Promise<string[]> => {
   // The hidden runtime is no longer the source of truth.
   await rm(context.outDir, { force: true, recursive: true });
 
-  return written.map((file) => file.path);
+  return { files: written.map((file) => file.path), warnings };
 };

package/src/registry/registry.ts

@@ -23,9 +23,6 @@ export interface RegistryItem {
 /** Absolute path to the blume package `src` directory (the copy source root). */
 export const packageSrc = join(packageRoot(), "src");
 
-/** Absolute path to the bundled registry item sources. */
-export const itemsRoot = join(packageRoot(), "src", "registry", "items");
-
 /**
  * A built-in layout component offered as editable source. `blume add` rewrites
  * its relative imports to `blume/*`, so it renders identically to the built-in

package/src/search/documents.ts

@@ -1,3 +1,5 @@
+import { applyAudienceVisibility } from "../ai/visibility.ts";
+import type { VisibilityAudience } from "../ai/visibility.ts";
 import matter from "../core/frontmatter.ts";
 import { contentIndexable } from "../core/manifest.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
@@ -93,9 +95,21 @@ interface Crumbs {
  */
 const buildCrumbIndex = (sidebar: NavNode[]): Map<string, Crumbs> => {
   const index = new Map<string, Crumbs>();
+  // A config-sidebar section's landing page (the group's `root`) lives on the
+  // *group* node, not on any page leaf — record it under the group's own label
+  // so the section's landing page carries the same facet as its children. A
+  // real page leaf for the route (filesystem sidebars emit index pages as
+  // leaves) wins, so group routes are merged in only where no leaf claimed one.
+  const groupRoutes = new Map<string, Crumbs>();
   const walk = (nodes: NavNode[], trail: string[]): void => {
     for (const node of nodes) {
       if (node.kind === "group") {
+        if (node.route && !groupRoutes.has(node.route)) {
+          groupRoutes.set(node.route, {
+            breadcrumb: [...trail, node.label],
+            section: node.label,
+          });
+        }
         walk(node.children, [...trail, node.label]);
       } else if (node.route) {
         index.set(node.route, {
@@ -106,6 +120,11 @@ const buildCrumbIndex = (sidebar: NavNode[]): Map<string, Crumbs> => {
     }
   };
   walk(sidebar, []);
+  for (const [route, crumbs] of groupRoutes) {
+    if (!index.has(route)) {
+      index.set(route, crumbs);
+    }
+  }
   return index;
 };
 
@@ -122,10 +141,19 @@ const buildCrumbIndex = (sidebar: NavNode[]): Map<string, Crumbs> => {
  * searchable text; `"markdown"` keeps the body's Markdown — code blocks, lists,
  * headings — for Ask AI grounding, where fenced examples are often the answer
  * and stripping them makes the model unable to cite content the docs do contain.
+ *
+ * `audience` resolves `<Visibility>` blocks before extraction: `"web"`
+ * (default) keeps web-only content and drops agents-only blocks — the site
+ * search and hosted syncs must not surface content the page hides — while
+ * `"agents"` mirrors llms-full.txt/MCP `get_page` (web removed, agents kept).
  */
 export const buildSearchDocuments = async (
   project: BlumeProject,
-  options?: { includeWhenDisabled?: boolean; content?: "markdown" | "plain" }
+  options?: {
+    includeWhenDisabled?: boolean;
+    content?: "markdown" | "plain";
+    audience?: VisibilityAudience;
+  }
 ): Promise<SearchDocument[]> => {
   const pageById = new Map(project.graph.pages.map((page) => [page.id, page]));
 
@@ -157,8 +185,12 @@ export const buildSearchDocuments = async (
       const page = pageById.get(route.id);
       const raw = page ? await readEntryText(project, page) : "";
       const source = raw ? matter(raw).content : "";
+      const visible = applyAudienceVisibility(
+        source,
+        options?.audience ?? "web"
+      );
       const body =
-        options?.content === "markdown" ? source.trim() : toPlainText(source);
+        options?.content === "markdown" ? visible.trim() : toPlainText(visible);
       const tags = page?.meta?.search?.tags;
       const crumb = crumbs.get(route.path);
       return {

package/src/seo/jsonld.ts

@@ -37,7 +37,13 @@ const trimSlash = (value: string): string => value.replace(/\/$/u, "");
 const absolute = (base: string | null, path: string): string =>
   base ? `${base}${path}` : path;
 
-const toIso = (value: DateInput | undefined): string | undefined => {
+/**
+ * Frontmatter date → ISO 8601, or undefined when absent/unparseable. Shared with
+ * the layout's `article:published_time`/`article:modified_time` so both date
+ * surfaces treat a malformed date the same way: omit it rather than emit
+ * "Invalid Date".
+ */
+export const toIso = (value: DateInput | undefined): string | undefined => {
   if (!value) {
     return;
   }
@@ -98,20 +104,21 @@ export const buildStructuredData = (
     }
     graph.push(node);
 
-    if (input.breadcrumbs.length > 1) {
+    // Google requires `item` on every ListItem except the last; sidebar groups
+    // without an index page produce route-less crumbs, so those are dropped
+    // (positions renumbered) rather than emitted as invalid link-less items.
+    const linked = input.breadcrumbs.filter(
+      (crumb): crumb is Required<Crumb> => typeof crumb.route === "string"
+    );
+    if (linked.length > 1) {
       graph.push({
         "@type": "BreadcrumbList",
-        itemListElement: input.breadcrumbs.map((crumb, index) => {
-          const item: Record<string, unknown> = {
-            "@type": "ListItem",
-            name: crumb.label,
-            position: index + 1,
-          };
-          if (crumb.route) {
-            item.item = absolute(base, withBasePath(deployBase, crumb.route));
-          }
-          return item;
-        }),
+        itemListElement: linked.map((crumb, index) => ({
+          "@type": "ListItem",
+          item: absolute(base, withBasePath(deployBase, crumb.route)),
+          name: crumb.label,
+          position: index + 1,
+        })),
       });
     }
   }

package/src/seo/x-handle.ts

@@ -0,0 +1,18 @@
+/**
+ * Normalize an X account to the leading `@` that `twitter:site`/`twitter:creator`
+ * require, so `acme`, `@acme`, and `  @acme ` all land on `@acme`. Empty or
+ * blank input yields undefined, which renders no tag at all.
+ *
+ * The layouts call this on values that never passed through the config schema:
+ * 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.)
+ */
+export const normalizeXHandle = (value: unknown): string | undefined => {
+  if (typeof value !== "string") {
+    return;
+  }
+  const handle = value.trim().replace(/^@+/u, "");
+  return handle ? `@${handle}` : undefined;
+};