blume 2.0.2 → 2.0.3

package/src/registry/eject.ts

@@ -3,10 +3,13 @@ import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 
 import { join, relative } from "pathe";
 
+import { OPENAPI_PATH } from "../ai/api/paths.ts";
+import { buildApiSpec } from "../ai/api/spec.ts";
 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 type { McpData } from "../ai/mcp/data.ts";
 import { buildMcpDiscovery, buildMcpServerCard } from "../ai/mcp/discovery.ts";
 import { planComponentSlots } from "../astro/component-slots.ts";
 import {
@@ -31,6 +34,11 @@ import {
 import { discoverIslands } from "../astro/islands.ts";
 import { customOgRoutes, discoverPages, routeIsTaken } from "../astro/pages.ts";
 import {
+  apiNavigationTemplate,
+  apiNotFoundTemplate,
+  apiPagesIndexTemplate,
+  apiPageTemplate,
+  apiSearchTemplate,
   askComponentTemplate,
   askEndpointTemplate,
   astroConfigTemplate,
@@ -46,6 +54,8 @@ import {
   mcpEndpointTemplate,
   mcpPageFile,
   mixedbreadSearchEndpointTemplate,
+  notFoundJsonTemplate,
+  notFoundMarkdownTemplate,
   notFoundPageTemplate,
   ogEndpointTemplate,
   playgroundProxyTemplate,
@@ -68,6 +78,7 @@ import {
 } from "../core/sources/collection.ts";
 import type { ProjectContext } from "../core/types.ts";
 import { buildRssFeeds, renderRssFeed } from "../deploy/rss.ts";
+import { resolveOgFonts } from "../og/derive.ts";
 import type { OpenApiData } from "../openapi/model.ts";
 import {
   hasScalarReferences,
@@ -80,6 +91,7 @@ import {
   examplesEntryTemplate,
   tailwindEntryTemplate,
 } from "../theme/entry.ts";
+import { fontLocaleCodes } from "../theme/fonts.ts";
 import { buildThemeCss } from "../theme/palette.ts";
 import { rebaseSourceDirectives } from "../theme/sources.ts";
 import { twoslashCss } from "../theme/twoslash.ts";
@@ -238,21 +250,33 @@ const playgroundProxyFiles = (
     : [];
 
 /**
- * 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.
+ * The agent data snapshot (`blume:mcp-data`) behind the MCP server and the
+ * JSON docs API, mirroring `publishAgentData` in generate.ts: built when
+ * either is on, null when neither needs it.
  */
-const mcpFiles = async (
+const ejectAgentData = async (
+  project: BlumeProject,
+  userPages: { pattern: string }[]
+): Promise<McpData | null> =>
+  hostsMcp(project, userPages) || project.config.agents.api
+    ? await buildMcpData(project)
+    : null;
+
+/**
+ * The MCP 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 = (
   project: BlumeProject,
   userPages: { pattern: string }[],
   srcDir: string,
-  genDir: string
-): Promise<{ content: string; path: string }[]> => {
-  if (!hostsMcp(project, userPages)) {
+  data: McpData | null
+): { content: string; path: string }[] => {
+  if (!(data && hostsMcp(project, userPages))) {
     return [];
   }
   const { route } = project.config.agents.mcp;
-  const data = await buildMcpData(project);
   const discoveryInput = {
     base: data.base,
     name: data.name,
@@ -261,10 +285,6 @@ const mcpFiles = async (
     version: data.version,
   };
   return [
-    {
-      content: `${JSON.stringify(data)}\n`,
-      path: join(genDir, "mcp-data.json"),
-    },
     {
       content: mcpEndpointTemplate(),
       path: join(srcDir, "pages", mcpPageFile(route)),
@@ -280,6 +300,87 @@ const mcpFiles = async (
   ];
 };
 
+/**
+ * The JSON docs API, mirroring `planApi` and `writeApiFiles` in generate.ts:
+ * the prerendered page index, per-page documents, and navigation; on server
+ * output the search endpoint and, unless a user page or a content page already
+ * lives under `/api/`, the JSON 404 catch-all; and `/openapi.json`, unless a
+ * `public/openapi.json` or a page owns that route. The ejected `llms.txt`,
+ * homepage `Link` header, and 404 page advertise these routes, so the ejected
+ * app serves them. Empty when `agents.api` is off.
+ */
+const apiFiles = (
+  project: BlumeProject,
+  userPages: { pattern: string }[],
+  root: string,
+  srcDir: string,
+  data: McpData | null
+): { content: string; path: string }[] => {
+  const { config } = project;
+  if (!(data && config.agents.api)) {
+    return [];
+  }
+  const server = config.deployment.options.output === "server";
+  const apiDir = join(srcDir, "pages", "api");
+  const files = [
+    {
+      content: apiPagesIndexTemplate(),
+      path: join(apiDir, "docs", "pages.json.ts"),
+    },
+    {
+      content: apiPageTemplate(),
+      path: join(apiDir, "docs", "pages", "[...route].json.ts"),
+    },
+    {
+      content: apiNavigationTemplate(),
+      path: join(apiDir, "docs", "navigation.json.ts"),
+    },
+  ];
+  if (server) {
+    files.push({
+      content: apiSearchTemplate(),
+      path: join(apiDir, "docs", "search.ts"),
+    });
+  }
+  const apiOwned =
+    userPages.some((page) => page.pattern.startsWith("/api/[")) ||
+    project.graph.pages.some(
+      (page) => page.route === "/api" || page.route.startsWith("/api/")
+    );
+  if (server && !apiOwned) {
+    files.push({
+      content: apiNotFoundTemplate({ base: data.base, site: data.site }),
+      path: join(apiDir, "[...path].ts"),
+    });
+  }
+  if (
+    !(
+      routeIsTaken(userPages, project.graph.pages, OPENAPI_PATH) ||
+      existsSync(join(root, "public", "openapi.json"))
+    )
+  ) {
+    files.push({
+      content: staticJsonEndpointTemplate(
+        buildApiSpec({
+          agentReadability: config.agents.agentReadability,
+          base: data.base,
+          description: config.description,
+          llmsTxt: config.agents.llmsTxt.enabled,
+          mcpRoute: hostsMcp(project, userPages)
+            ? config.agents.mcp.route
+            : null,
+          name: config.title,
+          search: server,
+          site: data.site,
+          version: data.version,
+        })
+      ),
+      path: join(srcDir, "pages", "openapi.json.ts"),
+    });
+  }
+  return files;
+};
+
 /**
  * The `/changelog` index page, mirroring `shouldGenerateChangelog` in
  * generate.ts: emitted when `type: changelog` entries or a release-backed
@@ -346,6 +447,25 @@ const contentAssetFiles = async (
   ];
 };
 
+/**
+ * The partial → including-pages map with every path relative to the project
+ * root, like every other path in the ejected app, so it holds in any checkout.
+ * Its readers (`includeHmrPlugin`, `withIncludeRefresh`) resolve each path
+ * against the app's root, which after eject is the project itself.
+ */
+const portableIncludeGraph = (
+  project: BlumeProject,
+  root: string
+): Record<string, string[]> =>
+  Object.fromEntries(
+    Object.entries(buildIncludeGraph(project.graph.pages)).map(
+      ([partial, includers]) => [
+        toPosix(relative(root, partial)),
+        includers.map((page) => toPosix(relative(root, page))),
+      ]
+    )
+  );
+
 /** Contents of the configured `examples.css`, or `""` when unset/absent. */
 /**
  * Read a user stylesheet that eject inlines into a generated entry under
@@ -655,7 +775,7 @@ export const eject = async (
       // hot update's read would silently no-op and partial edits would serve
       // stale pages. A snapshot like the rest of `src/generated`: the ejected
       // app owns (and may regenerate or prune) it.
-      content: `${JSON.stringify(buildIncludeGraph(project.graph.pages))}\n`,
+      content: `${JSON.stringify(portableIncludeGraph(project, root))}\n`,
       path: join(genDir, "includes.json"),
     },
     {
@@ -684,32 +804,69 @@ export const eject = async (
   });
 
   if (config.seo.og.enabled) {
+    // The default script fallbacks ride along (Google family names, nothing
+    // machine-specific), so a non-Latin card still renders after eject. An
+    // explicit seo.og.fonts replaces them, and isn't carried over.
+    const { fallbacks, families } = resolveOgFonts(
+      {
+        locales: fontLocaleCodes(config.i18n),
+        ogFonts: config.seo.og.fonts,
+        themeFonts: config.theme.fonts,
+        themeFontsConfigured: false,
+      },
+      root
+    );
     files.push({
       content: ogEndpointTemplate(
         customOgRoutes(pages, config.title, config.seo.og.titles),
-        { pageDescriptions: config.seo.og.description !== false },
+        {
+          fallbacks,
+          families,
+          pageDescriptions: config.seo.og.description !== false,
+        },
         changelog.length > 0
       ),
       path: join(srcDir, "pages", "og", "[...slug].png.ts"),
     });
   }
 
-  // The hosted MCP server and the playground's built-in proxy, mirrored from
-  // the generated runtime (`[]` when each is off).
+  // The hosted MCP server, the JSON docs API, and the playground's built-in
+  // proxy, mirrored from the generated runtime (`[]` when each is off). The
+  // server and the API share one agent data snapshot.
+  const agentData = await ejectAgentData(project, pages);
+  if (agentData) {
+    files.push({
+      content: `${JSON.stringify(agentData)}\n`,
+      path: join(genDir, "mcp-data.json"),
+    });
+  }
   files.push(
-    ...(await mcpFiles(project, pages, srcDir, genDir)),
+    ...mcpFiles(project, pages, srcDir, agentData),
+    ...apiFiles(project, pages, root, srcDir, agentData),
     ...changelog,
     ...playgroundProxyFiles(config, openApiData, srcDir)
   );
 
-  // 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.
+  // Default 404 page and its Markdown (`/404.md`) and JSON (`/404.json`)
+  // twins, mirroring `writeNotFoundPage` in generate.ts: all three are skipped
+  // when the project already owns `/404` (a custom `pages/404.astro` or a
+  // `404.md` content page). The ejected project owns the files afterwards and
+  // can edit or remove them.
   if (!routeIsTaken(pages, project.graph.pages, "/404")) {
-    files.push({
-      content: notFoundPageTemplate(),
-      path: join(srcDir, "pages", "404.astro"),
-    });
+    files.push(
+      {
+        content: notFoundPageTemplate(),
+        path: join(srcDir, "pages", "404.astro"),
+      },
+      {
+        content: notFoundMarkdownTemplate(),
+        path: join(srcDir, "pages", "404.md.ts"),
+      },
+      {
+        content: notFoundJsonTemplate(),
+        path: join(srcDir, "pages", "404.json.ts"),
+      }
+    );
   }
 
   // The client-feature loaders behind the `blume:features` alias, and the

package/src/search/adapters/version-scope.ts

@@ -0,0 +1,30 @@
+import type { SearchAdapterKind } from "./registry.ts";
+
+/**
+ * Whether each adapter's client can filter results to one docs version. The
+ * source-built indexes (Orama, FlexSearch) store every document's `version`,
+ * and the Algolia and Typesense syncs upload it as a facet their clients
+ * filter on. Pagefind indexes the built HTML with no version metadata, the
+ * Orama Cloud sync uploads no `version`, and the Mixedbread endpoint takes no
+ * filter, so those always search every version. Keyed by every kind so a new
+ * adapter has to decide.
+ */
+const SCOPES_VERSIONS = {
+  algolia: true,
+  flexsearch: true,
+  mixedbread: false,
+  none: false,
+  orama: true,
+  "orama-cloud": false,
+  pagefind: false,
+  typesense: true,
+} satisfies Record<SearchAdapterKind, boolean>;
+
+/**
+ * Whether the configured search adapter scopes results to the viewed docs
+ * version. The search dialog offers its "All versions" toggle only when it
+ * does: on the others the toggle would change nothing, and every query
+ * already spans all versions.
+ */
+export const scopesVersions = (kind: SearchAdapterKind): boolean =>
+  SCOPES_VERSIONS[kind];

package/src/search/documents.ts

@@ -23,7 +23,12 @@ import { HTML_COMMENT } from "../core/sources/normalize.ts";
 import { readExpandedEntryText } from "../core/sources/read.ts";
 import type { NavNode, PageRecord } from "../core/types.ts";
 import { parseCodeTitle } from "../markdown/code-title.ts";
-import { MARKDOWN_FEATURES, MDX_FEATURES } from "../markdown/features.ts";
+import { directiveSource } from "../markdown/directives.ts";
+import type { DirectiveNode } from "../markdown/directives.ts";
+import {
+  MARKDOWN_BODY_FEATURES,
+  MDX_BODY_FEATURES,
+} from "../markdown/features.ts";
 import { pageFacets } from "./facets.ts";
 
 /** A document indexed by the client-side search providers (Orama, FlexSearch). */
@@ -94,7 +99,6 @@ const INLINE_PARENTS = new Set([
   "strong",
   "subscript",
   "superscript",
-  "textDirective",
 ]);
 
 // Nodes that never render as prose: image alt text was never indexed, MDX
@@ -120,9 +124,9 @@ interface Walk {
 
 // Front matter is already off (core/frontmatter.ts) by the time a body gets
 // here, so a body that opens with a `---` divider must read as a thematic
-// break rather than a second front matter block.
-const MD_PARSE = { features: { ...MARKDOWN_FEATURES, frontmatter: false } };
-const MDX_PARSE = { features: { ...MDX_FEATURES, frontmatter: false } };
+// break rather than a second front matter block — as the renderer reads it.
+const MD_PARSE = { features: MARKDOWN_BODY_FEATURES };
+const MDX_PARSE = { features: MDX_BODY_FEATURES };
 
 const parseMdx = (markdown: string): Nodes | undefined => {
   try {
@@ -170,6 +174,25 @@ const collectCode = (
   out.push(node.value, " ");
 };
 
+/**
+ * A text or leaf directive as the page shows it. Blume renders neither (see
+ * `markdown/directives.ts`), and prose is full of text that parses as one —
+ * `16:9`, `og:image` — so the page shows the source the author wrote, and the
+ * index reads the same text rather than dropping the `:name` part.
+ */
+const directiveText = (
+  node: Extract<Nodes, { type: "leafDirective" | "textDirective" }>,
+  walk: Walk
+): string =>
+  directiveSource(
+    // SAFETY: DirectiveNode is a structural subset of Satteri's directive
+    // nodes — a `name`, optional attributes and children, and a position.
+    node as DirectiveNode,
+    node.type === "textDirective" ? ":" : "::",
+    // The walked tree was parsed from this text, so its offsets index into it.
+    walk.downlevel.source
+  );
+
 // Block boundaries separate words; so does an empty inline element (`<br />`,
 // a self-closing icon), which otherwise fuses its neighbors.
 const separatesWords = (node: Extract<Nodes, { children: unknown }>): boolean =>
@@ -223,28 +246,17 @@ const collectText = (node: Nodes, out: string[], walk: Walk): void => {
       out.push(" ");
       return;
     }
-    // Trailing heading markers (`[#custom-id]`, `{#custom-id}`, `[!toc]`,
-    // `[toc]`) are anchor
-
-    // metadata, not prose — strip them so they never pollute the index. Only
-    // a marker that ends the heading's final plain-text child counts,
-    // mirroring the renderer: a heading ending in inline code or an image
-    // keeps its bracketed text on the page (so it stays searchable), and a
-    // heading that is nothing but markers renders them literally.
+    case "textDirective": {
+      out.push(directiveText(node, walk));
+      return;
+    }
+    case "leafDirective": {
+      out.push(directiveText(node, walk), " ");
+      return;
+    }
     case "heading": {
-      const last = node.children.at(-1);
-      const trailing = last?.type === "text" ? last : undefined;
-      const inner: string[] = [];
-      const kept = trailing ? node.children.slice(0, -1) : node.children;
-      for (const child of kept) {
-        collectText(child, inner, walk);
-      }
-      if (trailing) {
-        const stripped = parseHeadingMarkers(trailing.value).text;
-        const literal = stripped === "" && node.children.length === 1;
-        inner.push(literal ? trailing.value : stripped);
-      }
-      out.push(inner.join("").trimEnd(), " ");
+      // oxlint-disable-next-line no-use-before-define -- mutual recursion: a heading's children are walked like any others
+      collectHeading(node, out, walk);
       return;
     }
     default: {
@@ -265,6 +277,35 @@ const collectText = (node: Nodes, out: string[], walk: Walk): void => {
   }
 };
 
+/**
+ * Fold a heading into the accumulator. Trailing heading markers
+ * (`[#custom-id]`, `{#custom-id}`, `[!toc]`, `[toc]`) are anchor metadata,
+ * not prose — strip them so they never pollute the index. Only a marker that
+ * ends the heading's final plain-text child counts, mirroring the renderer: a
+ * heading ending in inline code or an image keeps its bracketed text on the
+ * page (so it stays searchable), and a heading that is nothing but markers
+ * renders them literally.
+ */
+const collectHeading = (
+  node: Extract<Nodes, { type: "heading" }>,
+  out: string[],
+  walk: Walk
+): void => {
+  const last = node.children.at(-1);
+  const trailing = last?.type === "text" ? last : undefined;
+  const inner: string[] = [];
+  const kept = trailing ? node.children.slice(0, -1) : node.children;
+  for (const child of kept) {
+    collectText(child, inner, walk);
+  }
+  if (trailing) {
+    const stripped = parseHeadingMarkers(trailing.value).text;
+    const literal = stripped === "" && node.children.length === 1;
+    inner.push(literal ? trailing.value : stripped);
+  }
+  out.push(inner.join("").trimEnd(), " ");
+};
+
 /**
  * Reduce Markdown/MDX to plain, searchable text: parse (GFM included) and walk
  * the tree instead of regex-stripping the source, so reference-style links,

package/src/search/popular.ts

@@ -17,7 +17,8 @@ export interface SearchPopularPage {
  * `page.route`). `withBasePath` is idempotent and skips external URLs.
  *
  * `deployment.base` is deliberately *not* applied: routes stay deploy-base-less
- * so `createLinkRow` can prefix it at click time, same as sidebar-derived pages.
+ * so `Search.astro` can add it when it renders the entry, same as
+ * sidebar-derived pages.
  *
  * `icon` stays a name here (like `navigation.featured`): the icon set is a
  * server-only module, so `Search.astro` resolves it to inline SVG at render.

package/src/seo/jsonld.ts

@@ -1,5 +1,9 @@
 import type { Crumb } from "../components/layout/nav-utils.ts";
-import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
+import {
+  mountBasePath,
+  normalizeBasePath,
+  withBasePath,
+} from "../core/base-path.ts";
 
 /** A date-ish value carried through frontmatter (string, YAML Date, or unset). */
 type DateInput = string | Date | null;
@@ -301,7 +305,7 @@ const breadcrumbNode = (
     "@type": "BreadcrumbList",
     itemListElement: linked.map((crumb, index) => ({
       "@type": "ListItem",
-      item: absolute(base, withBasePath(deployBase, crumb.route)),
+      item: absolute(base, mountBasePath(deployBase, crumb.route)),
       name: crumb.label,
       position: index + 1,
     })),
@@ -323,7 +327,7 @@ export const buildStructuredData = (
   // 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 pageUrl = absolute(base, mountBasePath(deployBase, input.route));
   const rootUrl = absolute(base, deployBase);
   const graph: JsonLdNode[] = [];
 

package/src/translate/meta.ts

@@ -1,12 +1,14 @@
+import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 
 import { dirname, join, relative } from "pathe";
-import { glob } from "tinyglobby";
 
+import { localeTargetPath } from "../core/i18n.ts";
 import { createModuleLoader } from "../core/load-module.ts";
+import { findFolderMetaFiles } from "../core/meta.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { folderMetaSchema } from "../core/schema.ts";
-import type { FolderMeta } from "../core/schema.ts";
+import type { FolderMeta, ResolvedI18nConfig } from "../core/schema.ts";
 import type { Diagnostic } from "../core/types.ts";
 
 /**
@@ -37,7 +39,10 @@ export interface TranslatableMeta {
   title: string;
 }
 
-const META_FILES = ["**/meta.ts", "**/meta.js", "**/meta.mjs"];
+/** A folder's meta module names, in the order a lookup prefers them. */
+const META_NAMES = ["meta.ts", "meta.js", "meta.mjs"];
+
+const META_FILES = META_NAMES.map((name) => `**/${name}`);
 
 /**
  * Whether a loaded meta module default-exports a factory function. Generic so
@@ -48,21 +53,44 @@ const isFactoryModule = <T>(
 ): value is T & ((...args: never[]) => FolderMeta) =>
   typeof value === "function";
 
-/** Where a locale's generated meta module lives (always written as `meta.ts`). */
+/**
+ * Where a locale's meta module lives. The locale folder is resolved the way
+ * pages resolve it (`localeTargetPath`): `folders` are the content root's
+ * existing top-level folders, and one naming the locale in another casing
+ * (`pt-br/` for a configured `pt-BR`) is the locale's folder already. In that
+ * folder, a `meta.js`/`meta.mjs` that already exists is the target — the
+ * generated module is plain JavaScript, and writing a `meta.ts` beside it
+ * would leave the folder with two meta files. Otherwise it's a new `meta.ts`.
+ */
 export const metaTargetPath = (
   meta: TranslatableMeta,
-  locale: string
-): string => join(meta.contentRoot, locale, meta.dir, "meta.ts");
+  locale: string,
+  i18n: ResolvedI18nConfig,
+  folders: readonly string[]
+): string => {
+  const dir = join(
+    meta.contentRoot,
+    dirname(
+      localeTargetPath(join(meta.dir, "meta.ts"), ".ts", locale, i18n, folders)
+    )
+  );
+  const existing = META_NAMES.find((name) => existsSync(join(dir, name)));
+  return join(dir, existing ?? "meta.ts");
+};
 
 /**
  * Discover the default-locale `meta.{ts,js,mjs}` files whose titles a
  * translation run covers. Skips (in order): non-`dir` i18n projects entirely,
- * files inside a configured locale directory (those ARE translations), files
- * inside an archived-version snapshot (frozen, with their own translations —
- * the same folders the navigation's meta lookup hoists as versions),
- * factory-form modules (a warning — the generator can't re-emit a function),
- * modules that fail meta validation (the scan already errors on those), and
- * modules with no `title` (nothing to translate).
+ * files the scan's own folder-meta discovery never reads either — those
+ * matching the source's `exclude` globs (application code) or in folders its
+ * `include` globs don't reach (see `findFolderMetaFiles`) — files inside a
+ * configured locale directory (those ARE translations), files inside an
+ * archived-version snapshot (frozen, with their own translations — the same
+ * folders the navigation's meta lookup hoists as versions), modules that fail
+ * to load (the scan already errors on those), factory-form modules (a warning
+ * — the generator can't re-emit a function), modules that fail meta
+ * validation (the scan already errors on those too), and modules with no
+ * `title` (nothing to translate).
  */
 export const discoverTranslatableMeta = async (
   project: BlumeProject
@@ -85,16 +113,26 @@ export const discoverTranslatableMeta = async (
   const diagnostics: Diagnostic[] = [];
 
   const roots = project.sources.flatMap((source) =>
-    source.staged || !source.contentRoot ? [] : [source.contentRoot]
+    source.staged || !source.contentRoot
+      ? []
+      : [
+          {
+            contentRoot: source.contentRoot,
+            exclude: source.exclude,
+            include: source.include,
+          },
+        ]
   );
-  for (const contentRoot of roots) {
+  for (const { contentRoot, exclude, include } of roots) {
+    // The scan's own file set (`discoverFolderMeta`): a `meta.ts` under an
+    // excluded folder (`src/lib/meta.ts` beside `exclude: ["src/**"]`) is
+    // application code, and one in a folder no `include` glob reaches
+    // configures no group the build renders.
     // oxlint-disable-next-line no-await-in-loop -- a project has O(1) sources
-    const files = await glob(META_FILES, {
-      absolute: true,
-      cwd: contentRoot,
-      ignore: ["**/node_modules/**", "**/.blume/**", "**/dist/**"],
-      onlyFiles: true,
-    });
+    const files = await findFolderMetaFiles(
+      { exclude, include, root: contentRoot },
+      META_FILES
+    );
     for (const file of files.toSorted()) {
       const dir = relative(contentRoot, dirname(file));
       const [head] = dir.split("/");
@@ -104,11 +142,17 @@ export const discoverTranslatableMeta = async (
       ) {
         continue;
       }
+      let mod: Awaited<ReturnType<typeof load>>;
+      try {
+        // oxlint-disable-next-line no-await-in-loop -- sequential, ordered discovery
+        mod = await load(file);
+      } catch {
+        // Folder meta that fails to load is the scan's BLUME_META_LOAD_FAILED
+        // error, not a crash here; either way there's no title to read.
+        continue;
+      }
       // oxlint-disable-next-line no-await-in-loop -- sequential, ordered discovery
-      const [raw, mod] = await Promise.all([
-        readFile(file, "utf-8"),
-        load(file),
-      ]);
+      const raw = await readFile(file, "utf-8");
       if (isFactoryModule(mod)) {
         diagnostics.push({
           code: "BLUME_TRANSLATE_META_FACTORY",

package/src/translate/run.ts

@@ -146,9 +146,9 @@ const runPageItem = async (
   // SAFETY: `targets` maps every configured locale, and work items only carry
   // configured locale codes.
   const target = context.targets.get(item.locale) as LocaleConfig;
-  // A hand-authored translation can live at a non-canonical name (see
-  // WorkStatus); the disk probe finds only canonical targets, and a miss just
-  // means the prompt goes out without a style precedent.
+  // A stale item's target is the existing translation's own file, even at a
+  // non-canonical name (see `PageWorkItem.targetPath`), so it's the style
+  // precedent and the file rewritten; a missing item has nothing to read.
   const previousTranslation = existsSync(item.targetPath)
     ? await readFile(item.targetPath, "utf-8")
     : undefined;