@master/internal-site 0.1.3 → 0.2.1

package/README.md

@@ -68,6 +68,43 @@ Import individual component subpaths, including `.astro` and `.svelte` extension
 
 The CSS-specific subpaths require the matching optional compiler, tooling, schema, preset and language-service peers. Keep them out of browser-only imports. Shared public assets are served in development and copied into build output; consumer public files take precedence. No install hook writes consumer source files.
 
+## Local MDX translations
+
+English uses the root URL. The shared locale definitions map `ja`, `tw`, `ko`
+and `cn` to matching URL prefixes and the HTML language tags `ja`, `zh-TW`,
+`ko` and `zh-CN`. Keep complete sibling editions in `content.<locale>.mdx`;
+`metadata.ts` retains English identity, dates, authors and ordering. Translated
+frontmatter supplies titles, summaries, image descriptions and article-specific
+demonstration copy. Keep explicit heading IDs identical across editions.
+
+`build/localization.ts` supplies filesystem discovery, localized document reads,
+dependency fingerprints, explicit review operations and completeness checks.
+Configure `i18n.validation` with the consumer's resource-loader and review-index
+URLs. The integration validates them on every production build, including direct
+`astro build` calls. Source fingerprints include metadata and imported local or
+shared source files. A missing edition or changed source/translation fails the
+gate until independently reviewed. Builds never refresh review records.
+
+The resource loader also exposes local and shared UI dictionaries to the same
+gate. Common controls use `common/translations.js`; product copy belongs to each
+consumer. Both sites follow `common/terminology.json`. Use `sharedInterfaceKeys()`
+to include newly introduced literal interface requests in the UI inventory.
+
+The route registry imports each selected MDX edition through Astro's propagated
+asset boundary. Nested MDX imports inherit their parent's language through Vite;
+missing prose editions and draft includes throw. Prose-free fenced companion
+examples stay shared. Do not import every edition eagerly or reimplement the
+resolver in a consumer. Per-request `documentCopyOf(Astro)` and `demoCopy` let
+shared demonstrations read localized prose while retaining one executable model.
+
+Consumers derive navigation, search, Markdown, feeds and llms exports from their
+public inventory and the selected local edition. Use `extractSearchNodesFromMdx`
+for authored MDX and `extractSearchNodesFromMarkdown` for portable output; the
+latter retains explicit anchor targets and GFM tables. `transformMarkdownLinks`
+edits reader links without changing inline or fenced examples. Withdraw stale
+owned exports when a source becomes a draft or is removed. Required Reference
+inputs reject draft status instead of publishing a partial catalog.
+
 ## Development and releases
 
 From the Master repository, run `bun run build:packages`, `bun run --cwd packages/internal-site type-check` and `bun run --cwd packages/internal-site test`. Astro checks `.astro` implementations and Svelte checks interactive components separately. The root `build` builds the Node entrypoints before the site.

package/dist/astro.mjs

@@ -1,18 +1,18 @@
+import { d as validateSiteTranslations, f as isSharedMdxSample, h as createHeadingResolver, m as locales } from "./localization-LfIbIysE.mjs";
 import { svgoOptimizer } from "astro/config";
 import svelte from "@astrojs/svelte";
 import mdx from "@astrojs/mdx";
-import { unified } from "@astrojs/markdown-remark";
+import { parseFrontmatter, unified } from "@astrojs/markdown-remark";
 import masterCSS from "@master/css-astro";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { dirname, extname, join, relative, resolve, sep } from "node:path";
+import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { cp, mkdir, readFile, readdir, unlink, writeFile } from "node:fs/promises";
 import { createReadStream, existsSync } from "node:fs";
 import { isCSSRequest, searchForWorkspaceRoot, transformWithOxc } from "vite";
-import { optimize } from "svgo";
 import { createHash } from "node:crypto";
-import Slugger from "github-slugger";
-import { SKIP, visit } from "unist-util-visit";
 import { parse, parseExpressionAt } from "acorn";
+import { optimize } from "svgo";
+import { SKIP, visit } from "unist-util-visit";
 // src/astro/module-id.ts
 /** A Vite module id without its query or hash. */
 function cleanId(id) {
@@ -57,6 +57,33 @@ async function prepareContentPages(site, root, contentPrefix) {
 	const destination = join(root, ".astro/master-site/pages");
 	const pages = {};
 	const wanted = /* @__PURE__ */ new Set();
+	const localizedDocuments = {};
+	const localizedMetadata = {};
+	const availableLocales = {};
+	for (const file of files) {
+		if (!file.endsWith("/content.mdx")) continue;
+		const directory = dirname(file);
+		const route = relative(content, directory).replaceAll("\\", "/");
+		const pathname = "/" + route.split("/").filter((part) => !/^\(.+\)$/.test(part)).join("/");
+		const key = `${contentPrefix}/${route ? route + "/" : ""}page.astro`;
+		const section = route.split("/").find((part) => !/^\(.+\)$/.test(part)) ?? "home";
+		const locales = site.i18n.sectionLocales?.[section] ?? site.i18n.locales;
+		const metadataSource = await readFile(join(directory, "metadata.ts"), "utf8").catch(() => "");
+		const draft = parseFrontmatter(await readFile(file, "utf8")).frontmatter.draft === true || /\bdraft\s*:\s*true\b/.test(metadataSource);
+		const documents = {};
+		const metadata = {};
+		for (const locale of draft ? [] : locales) {
+			const variant = locale === site.i18n.defaultLocale ? file : join(directory, `content.${locale}.mdx`);
+			if (!files.has(variant)) continue;
+			const { frontmatter } = parseFrontmatter(await readFile(variant, "utf8"));
+			if (frontmatter.draft === true) continue;
+			documents[locale] = pathToFileURL(variant);
+			metadata[locale] = frontmatter;
+		}
+		localizedDocuments[pathname] = documents;
+		localizedMetadata[pathname] = metadata;
+		availableLocales[key] = Object.keys(documents);
+	}
 	for (const file of files) {
 		if (!file.endsWith("/content.mdx")) continue;
 		const directory = dirname(file);
@@ -87,15 +114,6 @@ export const generateMetadata = createPageMetadata(metadata, dictionaries)
 		pages[`${contentPrefix}/${route ? route + "/" : ""}page.astro`] = pathToFileURL(output);
 	}
 	for (const stale of await contentFiles(destination).catch(() => [])) if (stale.endsWith("/page.astro") && !wanted.has(stale)) await unlink(stale);
-	const availableLocales = {};
-	for (const file of files) {
-		if (!file.endsWith("/content.mdx")) continue;
-		const directory = dirname(file);
-		const route = relative(content, directory).replaceAll("\\", "/");
-		const section = route.split("/").find((segment) => !/^\(.+\)$/.test(segment)) ?? "home";
-		if (!site.i18n.translatedOnly?.includes(section)) continue;
-		availableLocales[`${contentPrefix}/${route ? route + "/" : ""}page.astro`] = site.i18n.locales.filter((locale) => locale === site.i18n.defaultLocale || files.has(join(directory, `content.${locale}.mdx`)));
-	}
 	for (const section of site.i18n.translatedOnly ?? []) {
 		const key = `${contentPrefix}/${section}/page.astro`;
 		if (!files.has(join(content, section, "page.astro"))) continue;
@@ -104,7 +122,9 @@ export const generateMetadata = createPageMetadata(metadata, dictionaries)
 	}
 	return {
 		pages,
-		availableLocales
+		availableLocales,
+		localizedDocuments,
+		localizedMetadata
 	};
 }
 // src/astro/server-styles.ts
@@ -157,6 +177,52 @@ function svgMarkup() {
 		}
 	};
 }
+// src/astro/localized-mdx.ts
+/** Nested article MDX follows its importer; executable examples keep one source. */
+function localizedMdx({ locales: locales$1 = locales, defaultLocale = "en" } = {}) {
+	return {
+		name: "@master/internal-site:localized-mdx",
+		enforce: "pre",
+		async resolveId(source, importer, options) {
+			if (!importer || !cleanId(importer).endsWith(".mdx")) return;
+			const language = cleanId(importer).match(/\.([a-z]{2})\.mdx$/)?.[1];
+			const locale = language && locales$1.includes(language) ? language : defaultLocale;
+			const resolved = await this.resolve(source, importer, {
+				...options,
+				skipSelf: true
+			});
+			if (!resolved || resolved.external) return;
+			const id = cleanId(resolved.id);
+			if (!id.endsWith(".mdx") || id.startsWith("\0")) return;
+			const suffix = resolved.id.slice(id.length) || source.slice(cleanId(source).length);
+			const file = id.startsWith("file:") ? fileURLToPath(id) : id.startsWith("/@fs/") ? id.slice(5) : id;
+			if (!isAbsolute(file)) return;
+			const original = file.replace(/\.([a-z]{2})\.mdx$/, (match, language) => locales$1.includes(language) ? ".mdx" : match);
+			this.addWatchFile(original);
+			const originalSource = await readFile(original, "utf8");
+			const originalMetadata = parseFrontmatter(originalSource).frontmatter;
+			if (originalMetadata.draft === true || originalMetadata.disabled === true) throw new Error(`Unpublished source MDX include: ${original}`);
+			if (locale === defaultLocale || !originalSource.trim() || isSharedMdxSample(original, originalSource)) return {
+				...resolved,
+				id: original + suffix
+			};
+			const translated = original.replace(/\.mdx$/, `.${locale}.mdx`);
+			this.addWatchFile(translated);
+			let translatedSource;
+			try {
+				translatedSource = await readFile(translated, "utf8");
+			} catch (cause) {
+				throw new Error(`Missing translated MDX include: ${translated}`, { cause });
+			}
+			const metadata = parseFrontmatter(translatedSource).frontmatter;
+			if (metadata.draft === true || metadata.disabled === true) throw new Error(`Unpublished translated MDX include: ${translated}`);
+			return {
+				...resolved,
+				id: translated + suffix
+			};
+		}
+	};
+}
 // src/astro/style-assets.ts
 /** Collapse only the compiler's unconditional, same-directory asset links.
 * This is concatenation of already compiled CSS, not a second CSS compiler.
@@ -259,41 +325,23 @@ async function compactStyleAssets(output) {
 		await writeFile(file, html);
 	}
 }
-// src/docs-shell/utils/resolve-heading.js
-function resolveHeading(title, id) {
-	const explicit = typeof title === "string" && title.match(/\s+\{#([\w-]+)\}$/);
-	if (explicit) {
-		title = title.slice(0, explicit.index);
-		id = explicit[1];
-	}
-	const words = title?.split?.(" ");
-	if (words?.pop() === "[sr-only]") return {
-		title: words.join(" "),
-		id: id?.replace("-sr-only", "")?.replace("-[sr-only]", ""),
-		className: "sr-only"
-	};
-	return {
-		title,
-		id
-	};
-}
 // src/docs-shell/remark/slug-and-toc.js
 function remarkSlugAndTOC() {
 	return (tree) => {
-		const slugs = new Slugger();
+		const resolveHeading = createHeadingResolver();
 		const toc = [];
 		visit(tree, "heading", (node) => {
 			const depth = node.depth;
-			if (depth !== 2 && depth !== 3) return;
+			if (depth < 2 || depth > 6) return;
 			const title = node.children.filter((n) => n.type === "text" || n.type === "inlineCode").map((n) => n.value).join(" ").trim();
-			const resolved = resolveHeading(title, slugs.slug(title));
+			const resolved = resolveHeading(title, depth);
 			const lastText = node.children.findLast((child) => child.type === "text");
 			if (lastText) lastText.value = lastText.value.replace(/\s+\{#[\w-]+\}$/, "");
 			node.data ??= {};
 			node.data.hProperties ??= {};
 			node.data.id = resolved.id;
 			node.data.hProperties.id = resolved.id;
-			toc.push({
+			if (depth === 2 || depth === 3) toc.push({
 				id: resolved.id,
 				title: resolved.title,
 				level: depth
@@ -498,7 +546,8 @@ function masterSite(site) {
 	return {
 		name: "@master/internal-site",
 		hooks: {
-			"astro:config:setup": async ({ config, updateConfig, addRenderer, injectRoute }) => {
+			"astro:config:setup": async ({ config, command, updateConfig, addRenderer, injectRoute }) => {
+				if (command === "build") await validateSiteTranslations(site.i18n);
 				const root = fileURLToPath(config.root);
 				const contentRelative = relative(root, fileURLToPath(site.content)).split(sep).join("/");
 				if (contentRelative.startsWith("..")) throw new Error("Site content must be inside the Astro project root");
@@ -516,7 +565,8 @@ function masterSite(site) {
 					"virtual:master-site/config": `export default ${JSON.stringify(site)}`,
 					"virtual:master-site/app": moduleImport(site.app),
 					"virtual:master-site/highlight": moduleImport(site.highlighter ?? new URL("../docs-shell/utils/highlight-code-core.ts", new URL("../src/astro/index.ts", import.meta.url).href)),
-					"virtual:master-site/translations": `export default import.meta.glob(${JSON.stringify(`${contentPrefix}/**/content.*.mdx`)})`
+					"virtual:master-site/translations": `export default {${Object.entries(prepared.localizedDocuments).map(([pathname, documents]) => `${JSON.stringify(pathname)}: {${Object.entries(documents).map(([locale, url]) => `${JSON.stringify(locale)}: ${propagated(url)}`).join(",")}}`).join(",")}}`,
+					"virtual:master-site/localized-metadata": `export default ${JSON.stringify(prepared.localizedMetadata)}`
 				};
 				const plugin = {
 					name: "@master/internal-site:modules",
@@ -554,10 +604,10 @@ function masterSite(site) {
 								server.restart();
 							}, 100);
 						};
-						server.watcher.on("add", refresh).on("unlink", refresh);
+						server.watcher.on("add", refresh).on("unlink", refresh).on("change", refresh);
 						server.httpServer?.once("close", () => {
 							clearTimeout(restart);
-							server.watcher.off("add", refresh).off("unlink", refresh);
+							server.watcher.off("add", refresh).off("unlink", refresh).off("change", refresh);
 						});
 						server.middlewares.use((request, response, next) => {
 							let pathname;
@@ -613,6 +663,7 @@ function masterSite(site) {
 					vite: {
 						plugins: [
 							plugin,
+							localizedMdx(site.i18n),
 							sourceURL(),
 							serverStyles([root, packageSource]),
 							svgMarkup()

package/dist/config.d.mts

@@ -31,10 +31,16 @@ export interface SiteI18nConfig {
   hreflangOfLocale: Record<string, string>;
   nameOfLocale: Record<string, string>;
   localizablePathnameRoots: string[];
+  localizableOrigins?: Record<string, readonly string[]>;
   translations: Record<string, Record<string, string>>;
   sectionLocales?: Record<string, readonly string[]>;
   /** These sections emit translated URLs only when translated MDX exists. */
   translatedOnly?: readonly string[];
+  /** Build-only resource loader and version-controlled explicit translation reviews. */
+  validation?: {
+    reviews: URL;
+    resources: URL;
+  };
 }
 export interface DocumentConfig {
   layout: URL;

package/dist/localization-LfIbIysE.mjs

@@ -0,0 +1,356 @@
+import { parseFrontmatter } from "@astrojs/markdown-remark";
+import { fileURLToPath } from "node:url";
+import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
+import { readFile, readdir } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { fromMarkdown } from "mdast-util-from-markdown";
+import { mdxjsEsm } from "micromark-extension-mdxjs-esm";
+import { mdxjsEsmFromMarkdown } from "mdast-util-mdxjs-esm";
+import { mdxJsx } from "micromark-extension-mdx-jsx";
+import { mdxJsxFromMarkdown } from "mdast-util-mdx-jsx";
+import * as acorn from "acorn";
+import Slugger from "github-slugger";
+// src/docs-shell/utils/resolve-heading.js
+function resolveHeading(title, id) {
+	const explicit = typeof title === "string" && title.match(/\s+\{#([\w-]+)\}$/);
+	if (explicit) {
+		title = title.slice(0, explicit.index);
+		id = explicit[1];
+	}
+	const words = title?.split?.(" ");
+	if (words?.pop() === "[sr-only]") return {
+		title: words.join(" "),
+		id: id?.replace("-sr-only", "")?.replace("-[sr-only]", ""),
+		className: "sr-only"
+	};
+	return {
+		title,
+		id
+	};
+}
+/** Section counters stay stable when a detail heading is inserted between them. */
+function createHeadingResolver() {
+	const sections = new Slugger();
+	const details = new Slugger();
+	const assigned = /* @__PURE__ */ new Set();
+	return (title, depth) => {
+		const explicit = /\s+\{#[\w-]+\}$/.test(title);
+		let heading;
+		if (explicit) heading = resolveHeading(title);
+		else {
+			const slugs = depth === 2 || depth === 3 ? sections : details;
+			do
+				heading = resolveHeading(title, slugs.slug(title));
+			while (heading.id && assigned.has(heading.id));
+		}
+		if (heading.id) assigned.add(heading.id);
+		return {
+			...heading,
+			explicit
+		};
+	};
+}
+// src/docs-shell/common/locales.js
+/** URL prefixes stay stable; document language tags use standard BCP 47 values. */
+const locales = [
+	"en",
+	"tw",
+	"ja",
+	"ko",
+	"cn"
+];
+// src/docs-shell/utils/localized-metadata.ts
+/** Prose can vary by locale; publication identity and technical configuration stay with the source. */
+function localizedMetadata(metadata, frontmatter, locale) {
+	const localized = {
+		...metadata,
+		locale
+	};
+	for (const key of ["description", "subtitle"]) if (typeof frontmatter[key] === "string") localized[key] = frontmatter[key];
+	if (typeof frontmatter.title === "string") localized.title = metadata.title && typeof metadata.title === "object" ? {
+		...metadata.title,
+		..."absolute" in metadata.title ? { absolute: frontmatter.title } : { default: frontmatter.title }
+	} : frontmatter.title;
+	if (metadata.cover && typeof frontmatter.cover?.alt === "string") localized.cover = {
+		...metadata.cover,
+		alt: frontmatter.cover.alt
+	};
+	for (const channel of ["openGraph", "twitter"]) {
+		const authored = frontmatter[channel];
+		if (metadata[channel] || authored) {
+			const prose = Object.fromEntries(["title", "description"].flatMap((key) => {
+				const text = authored?.[key] ?? (locale !== "en" ? frontmatter[key] : void 0);
+				return typeof text === "string" ? [[key, text]] : [];
+			}));
+			localized[channel] = {
+				...metadata[channel],
+				...prose
+			};
+		}
+	}
+	return localized;
+}
+// src/scripts/mdx-sample.ts
+/** Only prose-free companion examples share one source across editions. */
+function isSharedMdxSample(file, source) {
+	if (["content.mdx", "contract.mdx"].includes(basename(file))) return false;
+	const { content, frontmatter } = parseFrontmatter(source);
+	if (Object.keys(frontmatter).length) return false;
+	const nodes = fromMarkdown(content).children;
+	return nodes.length > 0 && nodes.every((node) => node.type === "code");
+}
+// src/scripts/localization.ts
+const emptyReviews = () => ({
+	version: 1,
+	resources: {}
+});
+const hash = (value) => createHash("sha256").update(value.replaceAll("\r\n", "\n")).digest("hex");
+const sourceHash = (resource) => hash(JSON.stringify([resource.source, Object.entries(resource.dependencies ?? {}).sort(([a], [b]) => a.localeCompare(b))]));
+/** Explicit review operation. Preparation and production builds never call this function. */
+function reviewTranslation(resource, locale) {
+	const translation = resource.translations[locale];
+	if (!translation?.trim()) throw new Error(`Missing translation: ${resource.id} (${locale})`);
+	return {
+		sourceHash: sourceHash(resource),
+		translationHash: hash(translation)
+	};
+}
+function auditTranslations(resources, reviews, { locales: locales$1 = locales, defaultLocale = "en" } = {}) {
+	if (reviews.version !== 1 || !reviews.resources) throw new Error("Unsupported translation review index; expected version 1");
+	const diagnostics = [];
+	const ids = /* @__PURE__ */ new Set();
+	for (const resource of resources) {
+		if (ids.has(resource.id)) throw new Error(`Duplicate translation resource: ${resource.id}`);
+		ids.add(resource.id);
+		if (resource.draft) continue;
+		for (const locale of resource.locales ?? locales$1) {
+			if (locale === defaultLocale) continue;
+			const report = (reason, message) => diagnostics.push({
+				id: resource.id,
+				locale,
+				reason,
+				message
+			});
+			const translation = resource.translations[locale];
+			if (!translation?.trim()) {
+				report("missing", "Translation is missing");
+				continue;
+			}
+			if (parseFrontmatter(translation).frontmatter.draft === true) {
+				report("missing", "Translation is a draft and is not available for publication");
+				continue;
+			}
+			const review = reviews.resources[resource.id]?.[locale];
+			if (!review) report("unreviewed", "Translation has not been reviewed");
+			else {
+				if (review.sourceHash !== sourceHash(resource)) report("source-changed", "English source changed after translation review");
+				if (review.translationHash !== hash(translation)) report("translation-changed", "Translation changed after review");
+			}
+			if (resource.checkAnchors) {
+				const expected = headingAnchors(resource.source);
+				const actual = headingAnchors(translation);
+				if (new Set(actual).size !== actual.length || JSON.stringify(expected) !== JSON.stringify(actual)) report("anchors", "Translated heading IDs must preserve source IDs and order");
+			}
+			if (resource.requireMetadata) {
+				const { frontmatter } = parseFrontmatter(translation);
+				if (typeof frontmatter.title !== "string" || !frontmatter.title.trim() || typeof frontmatter.description !== "string" || !frontmatter.description.trim()) report("metadata", "Localized MDX requires title and description frontmatter");
+			}
+		}
+	}
+	return diagnostics;
+}
+function assertTranslations(resources, reviews, options = {}) {
+	const diagnostics = auditTranslations(resources, reviews, options);
+	if (diagnostics.length) throw new Error(`Translation completeness check failed (${diagnostics.length}):\n${diagnostics.map((issue) => `${issue.id} [${issue.locale}] ${issue.reason}: ${issue.message}`).join("\n")}`);
+}
+/** Shared Astro build gate, also usable by a consumer's explicit audit command. */
+async function validateSiteTranslations({ validation, ...options }) {
+	const locales$2 = options.locales ?? locales;
+	if (!validation) {
+		if (locales$2.some((locale) => locale !== (options.defaultLocale ?? "en"))) throw new Error("Multilingual production builds require i18n.validation resources and reviews");
+		return;
+	}
+	const [{ default: load }, raw] = await Promise.all([import(validation.resources.href), readFile(validation.reviews, "utf8")]);
+	const resources = typeof load === "function" ? await load() : load;
+	if (!Array.isArray(resources) || resources.length === 0) throw new Error("Translation resource loader must return a nonempty resource inventory");
+	assertTranslations(resources, JSON.parse(raw), options);
+}
+async function readLocalizedDocument({ sourceFile, locale, defaultLocale = "en", metadata = {} }) {
+	const original = sourceFile.replace(/\.([a-z]{2})\.mdx$/, ".mdx");
+	const file = locale === defaultLocale ? original : original.replace(/\.mdx$/, `.${locale}.mdx`);
+	let source;
+	try {
+		source = await readFile(file, "utf8");
+	} catch (cause) {
+		throw new Error(`Missing localized document: ${file} (${locale})`, { cause });
+	}
+	const { content, frontmatter } = parseFrontmatter(source);
+	return {
+		file,
+		content,
+		frontmatter,
+		metadata: localizedMetadata(metadata, frontmatter, locale)
+	};
+}
+async function filesOf(directory) {
+	const files = [];
+	for (const entry of await readdir(directory, { withFileTypes: true })) {
+		if (entry.name.startsWith(".")) continue;
+		const file = join(directory, entry.name);
+		if (entry.isDirectory()) {
+			if (entry.name !== "drafts") files.push(...await filesOf(file));
+		} else files.push(file);
+	}
+	return files.sort();
+}
+/** Filesystem inventory, with no page imports, component execution or generated source writes. */
+async function discoverDocumentResources({ contentRoot, locales: locales$3 = locales, defaultLocale = "en", exclude = [], siteRoot = dirname(contentRoot) }) {
+	const files = new Set(await filesOf(contentRoot));
+	const resources = [];
+	for (const file of files) {
+		if (!file.endsWith(".mdx") || /\.[a-z]{2}\.mdx$/.test(file)) continue;
+		const source = await readFile(file, "utf8");
+		const id = relative(contentRoot, file).replaceAll("\\", "/");
+		if (!source.trim() || exclude.includes(id)) continue;
+		if (isSharedMdxSample(file, source)) continue;
+		const metadata = join(dirname(file), "metadata.ts");
+		const sourceMetadata = files.has(metadata) ? await readFile(metadata, "utf8") : void 0;
+		const dependencies = await collectSourceDependencies([file, ...sourceMetadata ? [metadata] : []], { siteRoot });
+		delete dependencies[relative(siteRoot, file).replaceAll("\\", "/")];
+		const translations = {};
+		for (const locale of locales$3) {
+			if (locale === defaultLocale) continue;
+			const translatedFile = file.replace(/\.mdx$/, `.${locale}.mdx`);
+			if (files.has(translatedFile)) translations[locale] = await readFile(translatedFile, "utf8");
+		}
+		resources.push({
+			id,
+			source,
+			translations,
+			dependencies,
+			checkAnchors: true,
+			requireMetadata: basename(file) === "content.mdx",
+			draft: parseFrontmatter(source).frontmatter.draft === true || /\bdraft\s*:\s*true\b/.test(sourceMetadata ?? "")
+		});
+	}
+	return resources;
+}
+/** Literal interface requests must exist even when a newly added control has no dictionary entry yet. */
+async function sharedInterfaceKeys(sourceRoot = join(dirname(fileURLToPath(import.meta.resolve("@master/internal-site/package.json"))), "src")) {
+	const keys = /* @__PURE__ */ new Set();
+	const visit = async (directory) => {
+		for (const entry of await readdir(directory, { withFileTypes: true })) {
+			const file = join(directory, entry.name);
+			if (entry.isDirectory()) await visit(file);
+			else if (/\.(?:astro|svelte|ts|js)$/.test(entry.name) && !/\.(?:test|spec)\./.test(entry.name)) {
+				const source = await readFile(file, "utf8");
+				for (const match of source.matchAll(/\bt\s*\(\s*(?=['"`])/g)) {
+					const expression = acorn.parseExpressionAt(source, match.index + match[0].length, { ecmaVersion: "latest" });
+					const value = expression.type === "Literal" ? expression.value : expression.type === "TemplateLiteral" && !expression.expressions.length ? expression.quasis[0].value.cooked : void 0;
+					if (typeof value === "string" && value.trim()) keys.add(value);
+				}
+			}
+		}
+	};
+	await visit(sourceRoot);
+	return [...keys].sort();
+}
+/** Follow local prose/data modules without executing them or importing product compiler code. */
+async function collectSourceDependencies(files, { siteRoot }) {
+	const root = resolve(siteRoot);
+	const sharedRoot = dirname(fileURLToPath(import.meta.resolve("@master/internal-site/package.json")));
+	const collected = {};
+	const seen = /* @__PURE__ */ new Set();
+	const visit = async (file) => {
+		file = resolve(file).replace(/\.(tw|ja|ko|cn)\.mdx$/, ".mdx");
+		if (!file.startsWith(root + sep) && !file.startsWith(sharedRoot + sep) || seen.has(file)) return;
+		if (file.startsWith(sharedRoot + sep) && /\/common\/(?:translations|locales)\.[jt]s$/.test(file.replaceAll("\\", "/"))) return;
+		seen.add(file);
+		const source = await readFile(file, "utf8").catch(() => void 0);
+		if (source === void 0) return;
+		const key = file.startsWith(sharedRoot + sep) ? `@master/internal-site/${relative(sharedRoot, file)}` : relative(root, file);
+		collected[key.replaceAll("\\", "/")] = source;
+		const imports = source.matchAll(/(?:\bfrom\s*|\bimport\s*(?:\(\s*)?)(['"])([^'"\n]+)\1/g);
+		for (const [, , specifier] of imports) {
+			if (!specifier.startsWith(".") && !specifier.startsWith("~/site/") && !specifier.startsWith("@master/internal-site/")) continue;
+			let target;
+			try {
+				target = specifier.startsWith("@master/internal-site/") ? fileURLToPath(import.meta.resolve(specifier.split("?")[0])) : specifier.startsWith("~/site/") ? resolve(root, specifier.slice(7)) : resolve(dirname(file), specifier.split("?")[0]);
+			} catch {
+				continue;
+			}
+			if (extname(target) && !/\.(?:[cm]?[jt]s|[jt]sx|mdx|astro|svelte)$/.test(target)) continue;
+			const candidates = extname(target) ? [target, .../\.js$/.test(target) ? [target.replace(/\.js$/, ".ts")] : []] : [
+				"",
+				".ts",
+				".js",
+				".mdx",
+				".astro",
+				".svelte",
+				"/index.ts",
+				"/index.js"
+			].map((suffix) => target + suffix);
+			for (const candidate of candidates) {
+				const before = Object.keys(collected).length;
+				await visit(candidate);
+				if (Object.keys(collected).length > before) break;
+			}
+		}
+	};
+	for (const file of files) await visit(file);
+	return Object.fromEntries(Object.entries(collected).sort(([a], [b]) => a.localeCompare(b)));
+}
+function headings(source) {
+	const parsed = parseFrontmatter(source);
+	const offset = source.indexOf(parsed.content, parsed.rawFrontmatter ? parsed.rawFrontmatter.length : 0);
+	const tree = fromMarkdown(parsed.content, {
+		extensions: [
+			{ disable: { null: [
+				"htmlFlow",
+				"htmlText",
+				"codeIndented"
+			] } },
+			mdxjsEsm({
+				acorn,
+				addResult: true
+			}),
+			mdxJsx({
+				acorn,
+				addResult: true
+			})
+		],
+		mdastExtensions: [mdxjsEsmFromMarkdown(), mdxJsxFromMarkdown()]
+	});
+	const resolveHeading = createHeadingResolver();
+	const found = [];
+	const visit = (node) => {
+		if (node.type === "heading" && node.depth >= 2 && node.depth <= 6) {
+			const title = node.children.filter((child) => child.type === "text" || child.type === "inlineCode").map((child) => child.value).join(" ").trim();
+			const resolved = resolveHeading(title, node.depth);
+			const raw = parsed.content.slice(node.position.start.offset, node.position.end.offset);
+			const end = raw.includes("\n") ? node.position.start.offset + raw.indexOf("\n") : node.position.end.offset;
+			found.push({
+				id: resolved.id ?? "",
+				explicit: resolved.explicit,
+				offset: Math.max(0, offset) + end
+			});
+		}
+		node.children?.forEach(visit);
+	};
+	visit(tree);
+	return found;
+}
+function headingAnchors(source) {
+	return headings(source).map((heading) => heading.id);
+}
+/** Pin the existing automatic English IDs before translation, without modifying fenced examples. */
+function stabilizeHeadingAnchors(source) {
+	for (const heading of headings(source).reverse()) {
+		if (heading.explicit || !heading.id) continue;
+		const closing = source.slice(0, heading.offset).match(/[ \t]+#+[ \t]*$/)?.[0] ?? "";
+		const at = heading.offset - closing.length;
+		source = source.slice(0, at) + ` \\{#${heading.id}\\}` + source.slice(at);
+	}
+	return source;
+}
+export { emptyReviews as a, reviewTranslation as c, validateSiteTranslations as d, isSharedMdxSample as f, createHeadingResolver as h, discoverDocumentResources as i, sharedInterfaceKeys as l, locales as m, auditTranslations as n, headingAnchors as o, localizedMetadata as p, collectSourceDependencies as r, readLocalizedDocument as s, assertTranslations as t, stabilizeHeadingAnchors as u };