blume 2.0.1 → 2.0.3

package/src/search/documents.ts

@@ -16,13 +16,19 @@ import { applyAudienceVisibility } from "../ai/visibility.ts";
 import type { VisibilityAudience } from "../ai/visibility.ts";
 import matter from "../core/frontmatter.ts";
 import { parseHeadingMarkers } from "../core/heading-markers.ts";
+import { EN_UI, resolveUIStrings } from "../core/i18n-ui.ts";
 import { contentIndexable } from "../core/manifest.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 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). */
@@ -93,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
@@ -119,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 {
@@ -169,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 =>
@@ -222,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: {
@@ -264,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,
@@ -447,6 +489,26 @@ export const buildSearchDocuments = async (
   // otherwise.
   const components = projectComponentSerializers(project);
 
+  // A page in no sidebar group falls under the "Docs" section, in its own
+  // language: the label is a UI string, resolved once per locale.
+  const { i18n } = project.config;
+  const docsSections = new Map<string, string>();
+  const docsSection = (locale: string): string => {
+    let label = docsSections.get(locale);
+    if (label === undefined) {
+      label = (
+        i18n
+          ? resolveUIStrings(locale, {
+              defaultLocale: i18n.defaultLocale,
+              overrides: i18n.ui,
+            })
+          : EN_UI
+      ).search.docs;
+      docsSections.set(locale, label);
+    }
+    return label;
+  };
+
   return await Promise.all(
     indexable.map(async (route) => {
       const page = pageById.get(route.id);
@@ -461,7 +523,7 @@ export const buildSearchDocuments = async (
         description: page?.description ?? "",
         locale: route.locale,
         route: route.path,
-        section: crumb?.section || "Docs",
+        section: crumb?.section || docsSection(route.locale),
         tags: tags && tags.length > 0 ? tags : undefined,
         title: route.title,
         version: route.version,

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/search/sync/algolia.ts

@@ -7,6 +7,19 @@ import type { SearchRecord } from "../documents.ts";
 /** The adapter options the sync reads (the public `apiKey` is never used). */
 export type AlgoliaSyncConfig = Pick<AlgoliaOptions, "appId" | "indexName">;
 
+/**
+ * The record attributes the search dialog filters on (`facetFilters` on
+ * `locale:<code>` and `version:<id>`). In Algolia a facet filter on an
+ * attribute the index doesn't declare for faceting matches nothing — an i18n
+ * or versioned site would get no hits — so the sync declares them,
+ * filter-only.
+ */
+const FILTER_ATTRIBUTES = ["locale", "version"] as const;
+
+/** A faceting declaration's attribute: `filterOnly(locale)` → `locale`. */
+const facetAttribute = (declaration: string): string =>
+  declaration.replace(/^\w+\((?<name>.*)\)$/u, "$<name>");
+
 /**
  * Upload the search records to Algolia. Uses the admin key from
  * `ALGOLIA_ADMIN_API_KEY` (never the adapter options, which hold only the
@@ -14,7 +27,9 @@ export type AlgoliaSyncConfig = Pick<AlgoliaOptions, "appId" | "indexName">;
  *
  * Uses `replaceAllObjects`, which atomically replaces the index contents, so
  * pages deleted or renamed since the last sync don't linger as stale search
- * hits that 404 when clicked.
+ * hits that 404 when clicked. Then adds `filterOnly(locale)` and
+ * `filterOnly(version)` to the index's `attributesForFaceting`, keeping any
+ * the site declared itself, so the dialog's locale and version filters match.
  */
 export const syncAlgolia = async (
   records: SearchRecord[],
@@ -28,8 +43,27 @@ export const syncAlgolia = async (
   // `core/node-require.ts`).
   const { algoliasearch }: typeof AlgoliaSdk = nodeRequire("algoliasearch");
   const client = algoliasearch(config.appId, adminKey);
+  const { indexName } = config;
   await client.replaceAllObjects({
-    indexName: config.indexName,
+    indexName,
     objects: records.map((record) => ({ ...record, objectID: record._id })),
   });
+  const { attributesForFaceting = [] } = await client.getSettings({
+    indexName,
+  });
+  const declared = new Set(attributesForFaceting.map(facetAttribute));
+  const missing = FILTER_ATTRIBUTES.filter((name) => !declared.has(name));
+  if (missing.length === 0) {
+    return;
+  }
+  const { taskID } = await client.setSettings({
+    indexName,
+    indexSettings: {
+      attributesForFaceting: [
+        ...attributesForFaceting,
+        ...missing.map((name) => `filterOnly(${name})`),
+      ],
+    },
+  });
+  await client.waitForTask({ indexName, taskID });
 };

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/sources/registry.ts

@@ -165,6 +165,11 @@ const sourceEntrySchema = z
   .custom<SourceAdapterInput>(
     (value) => isObjectLike(value) && "kind" in value,
     {
+      // `z.custom` marks its failure as aborting by default, which makes Zod
+      // skip even the `content` refinement that opts in to running after a
+      // failed field (the shorthand beside `sources`). The pipe below stops
+      // at this entry either way.
+      abort: false,
       error: (issue) => {
         const legacy = legacyEntrySchema.safeParse(issue.input);
         return entryHint(legacy.success ? legacy.data.type : undefined);

package/src/theme/entry.ts

@@ -268,7 +268,7 @@ ${THEME_MAPPING}
   @apply block rounded-[0.65rem] px-2.5 py-1.5 text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground aria-[current=page]:bg-muted aria-[current=page]:font-medium aria-[current=page]:text-foreground;
 }
 @utility blume-nav-drill {
-  @apply flex w-full items-center gap-2 rounded-[0.65rem] px-2.5 py-1.5 text-left font-medium text-foreground text-sm transition-colors hover:bg-muted;
+  @apply flex w-full items-center gap-2 rounded-[0.65rem] px-2.5 py-1.5 text-start font-medium text-foreground text-sm transition-colors hover:bg-muted;
 }
 @utility blume-nav-summary {
   @apply flex cursor-pointer list-none items-center gap-1.5 rounded-[0.65rem] px-2.5 py-1.5 text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground [&::-webkit-details-marker]:hidden;
@@ -884,11 +884,18 @@ pre:has(.line.focused):hover .line:not(.focused) {
 }
 
 /* Print / "Save as PDF" (the page-actions Export → PDF runs window.print()).
-   Strip the surrounding chrome so the printout is just the article. */
+   Strip the surrounding chrome so the printout is just the article. Scoped to
+   the chrome itself, never bare \`header\`/\`aside\`: content renders those too
+   (every Callout and Panel is an <aside>, every changelog Update has a
+   <header>), and they belong in the printout. \`body > header\` keeps a
+   \`layout.Header\` override out as well. */
 @media print {
   [data-blume-banner],
-  header,
-  aside,
+  [data-blume-header],
+  body > header,
+  [data-blume-nav-drawer],
+  [data-blume-toc],
+  [data-blume-assistant-panel],
   [data-blume-page-actions],
   #blume-content > nav,
   #blume-content > details {

package/src/translate/agents.ts

@@ -1,5 +1,5 @@
 import type { AgentKind } from "../audit/agent.ts";
-import { DISALLOWED_TOOLS } from "../eval/agents.ts";
+import { CODEX_LOCKDOWN, DISALLOWED_TOOLS } from "../eval/agents.ts";
 
 /**
  * argv builders for the translator role. The subprocess machinery
@@ -28,6 +28,10 @@ const claudeArgs = (): string[] => [
   "1",
 ];
 
+// `--sandbox read-only` alone still lets codex's shell read any file the user
+// can, and the source page being translated is untrusted input (a remote
+// contributor's prose), so the translator gets the same lockdown as an eval
+// run: no shell, exec, or local-image tool, and no inherited environment.
 const codexArgs = (lastMessagePath: string): string[] => [
   "exec",
   "--skip-git-repo-check",
@@ -35,6 +39,7 @@ const codexArgs = (lastMessagePath: string): string[] => [
   "--ephemeral",
   "--sandbox",
   "read-only",
+  ...CODEX_LOCKDOWN,
   "--output-last-message",
   lastMessagePath,
   "-",

package/src/translate/ledger.ts

@@ -4,6 +4,7 @@ import { readFile } from "node:fs/promises";
 import { join } from "pathe";
 import { z } from "zod";
 
+import { BlumeError } from "../core/diagnostics.ts";
 import { writeTextAtomic } from "../core/fs-atomic.ts";
 
 /**
@@ -39,21 +40,34 @@ export const emptyLedger = (): TranslationLedger => ({
  * every locale's stamp. sha256-16 like the audit snapshot's content hash.
  * Kept as its own function rather than sharing core's `hashText`: ledger
  * stamps persist in user repos, so this hash must never change shape when an
- * ephemeral cache hash does.
+ * ephemeral cache hash does. CRLF line endings are normalized to LF first, so
+ * a Windows checkout (`core.autocrlf`) hashes the same as everyone else's —
+ * LF text hashes exactly as it always has.
  */
 export const hashSource = (text: string): string =>
-  createHash("sha256").update(text).digest("hex").slice(0, 16);
+  createHash("sha256")
+    .update(text.replaceAll("\r\n", "\n"))
+    .digest("hex")
+    .slice(0, 16);
+
+/** A git merge-conflict marker line: `<<<<<<< ours`, `=======`, `>>>>>>> theirs`. */
+const CONFLICT_MARKER = /^(?:<{7}|={7}|>{7})(?:[ \r]|$)/mu;
 
 /**
  * Read the ledger at `root`, tolerantly: a missing file, unparseable JSON, or
  * an unknown shape/version all resolve to an empty ledger rather than an error
  * (same posture as the dev lock's `parseLock`) — the worst outcome of a
  * corrupt ledger is retranslating files that were already up to date.
+ *
+ * Unresolved merge-conflict markers are the exception, and an error: read as
+ * empty, every existing translation would be adopted as current, so
+ * `--check` would pass over translations that are out of date.
  */
 export const readLedger = async (root: string): Promise<TranslationLedger> => {
+  const path = join(root, LEDGER_FILE);
   let raw: string;
   try {
-    raw = await readFile(join(root, LEDGER_FILE), "utf-8");
+    raw = await readFile(path, "utf-8");
   } catch {
     return emptyLedger();
   }
@@ -61,6 +75,15 @@ export const readLedger = async (root: string): Promise<TranslationLedger> => {
   try {
     data = JSON.parse(raw);
   } catch {
+    if (CONFLICT_MARKER.test(raw)) {
+      throw new BlumeError({
+        code: "BLUME_TRANSLATE_LEDGER_CONFLICT",
+        file: path,
+        message: `${LEDGER_FILE} has unresolved merge-conflict markers, so it can't say which translations are current.`,
+        severity: "error",
+        suggestion: `Resolve the merge conflict in ${LEDGER_FILE}, then rerun.`,
+      });
+    }
     return emptyLedger();
   }
   const parsed = ledgerSchema.safeParse(data);

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,19 +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),
- * 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
@@ -74,33 +104,55 @@ export const discoverTranslatableMeta = async (
       locale.code === i18n.defaultLocale ? [] : [locale.code.toLowerCase()]
     )
   );
+  const versionDirs = new Set(
+    project.config.versions?.archived.map((version) => version.id)
+  );
 
   const load = createModuleLoader();
   const metas: TranslatableMeta[] = [];
   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 first = dir.split("/")[0]?.toLowerCase();
-      if (first && localeDirs.has(first)) {
+      const [head] = dir.split("/");
+      if (
+        head &&
+        (localeDirs.has(head.toLowerCase()) || versionDirs.has(head))
+      ) {
+        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

@@ -4,7 +4,7 @@ import { tmpdir } from "node:os";
 
 import pLimit from "p-limit";
 import pMap from "p-map";
-import { join } from "pathe";
+import { dirname, join } from "pathe";
 
 import { AGENTS } from "../audit/agent.ts";
 import type { AgentKind } from "../audit/agent.ts";
@@ -18,6 +18,7 @@ import { DEFAULT_TRANSLATE_TIMEOUT_MS, translateAgentArgs } from "./agents.ts";
 import { hashSource, stampLedger } from "./ledger.ts";
 import type { TranslationLedger } from "./ledger.ts";
 import { generateMetaModule } from "./meta.ts";
+import type { TranslatableMeta } from "./meta.ts";
 import { metaPrompt, pagePrompt } from "./prompts.ts";
 import { parseMetaTitles, validateTranslation } from "./validate.ts";
 import type {
@@ -88,8 +89,13 @@ interface RunContext {
   timeoutMs: number;
 }
 
-/** The root directory's key in a meta-titles prompt (an empty key is opaque). */
-const metaDirKey = (dir: string): string => (dir === "" ? "." : dir);
+/**
+ * A meta file's key in a meta-titles prompt: its directory relative to the
+ * project root. The content-root-relative `dir` isn't unique — two
+ * filesystem sources can both have a `guides/` folder — and colliding keys
+ * would hand both folders one translation.
+ */
+const metaKey = (meta: TranslatableMeta): string => dirname(meta.sourceRel);
 
 /**
  * One headless agent call. A missing executable rejects with ENOENT on every
@@ -140,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;
@@ -183,7 +189,7 @@ const runMetaItem = async (
   });
 
   const titles = Object.fromEntries(
-    item.entries.map((entry) => [metaDirKey(entry.meta.dir), entry.meta.title])
+    item.entries.map((entry) => [metaKey(entry.meta), entry.meta.title])
   );
   // SAFETY: `targets` maps every configured locale, and work items only carry
   // configured locale codes.
@@ -199,7 +205,7 @@ const runMetaItem = async (
 
   const parsed = parseMetaTitles(output.text, Object.keys(titles));
   for (const entry of item.entries) {
-    const translated = parsed.titles[metaDirKey(entry.meta.dir)];
+    const translated = parsed.titles[metaKey(entry.meta)];
     if (translated === undefined) {
       continue;
     }

package/src/translate/validate.ts

@@ -32,7 +32,10 @@ interface FrontmatterData {
   [key: string]: FrontmatterValue;
 }
 
-const FRONTMATTER_OPEN = /^---\r?\n/u;
+// gray-matter strips a leading byte order mark before it looks for the fence,
+// so a BOM-prefixed file still has frontmatter — this test must agree, or the
+// reconstruction below writes the body alone and the metadata is lost.
+const FRONTMATTER_OPEN = /^?---\r?\n/u;
 const FENCE_LINE = /^\s*(?:```|~~~)/u;
 
 /**
@@ -102,7 +105,16 @@ export const validateTranslation = (
   sourceText: string,
   agentText: string
 ): ValidationResult => {
-  const candidate = stripOuterFence(agentText);
+  // Only a fence the agent added is stripped. A source that is itself one
+  // code block (a frontmatter-less partial holding a single bash block)
+  // starts and ends with its own fence, which the translation must keep — so
+  // for such a source the reply loses its outer fence only when it has more
+  // fence lines than the source.
+  const sourceIsFenced = stripOuterFence(sourceText) !== sourceText.trim();
+  const candidate =
+    sourceIsFenced && countFenceLines(agentText) <= countFenceLines(sourceText)
+      ? agentText.trim()
+      : stripOuterFence(agentText);
   if (candidate === "") {
     return { ok: false, reason: "agent returned empty output" };
   }