@master/internal-site 0.1.2 → 0.2.0

package/README.md

@@ -27,6 +27,12 @@ Optional `header.communityNavs` selects the links shown beside search without re
 
 The app module exports its logo component, navigation, version links and source/feedback URLs using the `SiteApp` contract. Consumers retain their own content and homepage composition. Ordinary documents use `content/<section>/<slug>/content.mdx` and `metadata.ts`; a local `page.astro` can override the generated entry. Dynamic routes enumerate params from lightweight `params.ts` files. The integration owns generated routes, page asset collection and the Astro/Svelte renderer setup.
 
+Blog articles with a cover declare `cover: { src, alt, width, height }` in their
+metadata. The shared article layout renders it below the byline and uses it for
+Open Graph and Twitter images. An optional `socialImage` points to a PNG/JPEG
+version of the same artwork; a cover takes precedence over separate social-card
+images. Articles without a cover retain their existing layout and social cards.
+
 ```css
 /* styles/globals.css */
 @import '@master/css';
@@ -62,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,17 +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 { createHash } from "node:crypto";
+import { parse, parseExpressionAt } from "acorn";
 import { optimize } from "svgo";
-import Slugger from "github-slugger";
 import { SKIP, visit } from "unist-util-visit";
-import { parse, parseExpressionAt } from "acorn";
 // src/astro/module-id.ts
 /** A Vite module id without its query or hash. */
 function cleanId(id) {
@@ -56,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);
@@ -86,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;
@@ -103,7 +122,9 @@ export const generateMetadata = createPageMetadata(metadata, dictionaries)
 	}
 	return {
 		pages,
-		availableLocales
+		availableLocales,
+		localizedDocuments,
+		localizedMetadata
 	};
 }
 // src/astro/server-styles.ts
@@ -156,41 +177,171 @@ function svgMarkup() {
 		}
 	};
 }
-// 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"
-	};
+// 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 {
-		title,
-		id
+		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.
+* Keep conditions, layers, URLs, repeated occurrences and unrelated imports intact.
+*/
+async function inlineGeneratedStyles(file, ancestors = []) {
+	if (ancestors.includes(file)) throw new Error(`Cyclic generated stylesheet: ${file}`);
+	const source = await readFile(file, "utf8");
+	let code = "", cursor = 0;
+	while (cursor < source.length) {
+		const rest = source.slice(cursor);
+		const trivia = /^(?:\s+|\/\*[\s\S]*?\*\/|@layer\s+[\w,\s-]+;)/.exec(rest);
+		if (trivia) {
+			code += trivia[0];
+			cursor += trivia[0].length;
+			continue;
+		}
+		const match = /^@import\s+["'](\.\/master-css-[\w-]+\.css)["']\s*;/.exec(rest);
+		if (!match) break;
+		code += await inlineGeneratedStyles(resolve(dirname(file), match[1]), [...ancestors, file]) + "\n";
+		cursor += match[0].length;
+	}
+	const expanded = code + source.slice(cursor);
+	return /@(?:import|charset|namespace)\b/.test(expanded) ? source : expanded;
+}
+/** Preserve HTML link order and each reusable entry's cache identity. Originals
+* remain available to any JS/CSS references; no client loading logic is added. */
+async function compactStyleAssets(output) {
+	const root = resolve(output), replacements = /* @__PURE__ */ new Map();
+	const documents = /* @__PURE__ */ new Map(), users = /* @__PURE__ */ new Map();
+	const boundaries = /* @__PURE__ */ new Set();
+	async function emit(code) {
+		const href = `/_astro/site-style-${createHash("sha256").update(code).digest("hex").slice(0, 20)}.css`;
+		await writeFile(resolve(root, "." + href), code);
+		return href;
+	}
+	async function walk(directory) {
+		for (const entry of await readdir(directory, { withFileTypes: true })) {
+			const file = resolve(directory, entry.name);
+			if (entry.isDirectory()) {
+				await walk(file);
+				continue;
+			}
+			if (!entry.name.endsWith(".html")) continue;
+			let html = await readFile(file, "utf8");
+			const links = [...html.matchAll(/<link\b(?=[^>]*\brel="stylesheet")(?=[^>]*\bhref="(\/_astro\/[^"/]+\.css)")[^>]*>/g)];
+			for (const match of links) {
+				const href = match[1];
+				if (!replacements.has(href)) {
+					const input = resolve(root, "." + href);
+					const source = await readFile(input, "utf8");
+					const code = await inlineGeneratedStyles(input);
+					const next = source === code ? href : await emit(code);
+					replacements.set(href, next);
+				}
+				const next = replacements.get(href);
+				if (/\/(site|interface|documents)\./.test(href)) boundaries.add(next);
+				const pages = users.get(next) ?? [];
+				if (!pages.includes(file)) pages.push(file);
+				users.set(next, pages);
+				html = html.replace(match[0], match[0].replace(`href="${href}"`, `href="${next}"`));
+			}
+			documents.set(file, html);
+		}
+	}
+	await walk(root);
+	const signatures = new Map([...users].map(([href, pages]) => [href, pages.sort().join("\n")]));
+	const adjacent = /* @__PURE__ */ new Map();
+	for (const [file, html] of documents) for (const match of html.matchAll(/(?=<link rel="stylesheet" href="([^"\s]+)">\s*<link rel="stylesheet" href="([^"\s]+)">)/g)) {
+		const key = `${match[1]}\n${match[2]}`;
+		const pages = adjacent.get(key) ?? /* @__PURE__ */ new Set();
+		pages.add(file);
+		adjacent.set(key, pages);
+	}
+	for (const [file, source] of documents) {
+		let html = source;
+		const runs = [...source.matchAll(/(?:<link rel="stylesheet" href="\/_astro\/[^"/]+\.css">\s*){2,}/g)];
+		for (const run of runs) {
+			const links = [...run[0].matchAll(/<link rel="stylesheet" href="([^"\s]+)">\s*/g)];
+			let replacement = "", group = [];
+			async function flush() {
+				if (group.length > 1) {
+					const code = (await Promise.all(group.map((link) => readFile(resolve(root, "." + link[1]), "utf8")))).join("\n");
+					replacement += code.includes("@import") ? group.map((link) => link[0]).join("") : `<link rel="stylesheet" href="${await emit(code)}">`;
+				} else replacement += group.map((link) => link[0]).join("");
+				group = [];
+			}
+			for (const link of links) {
+				if (boundaries.has(link[1])) {
+					await flush();
+					replacement += link[0];
+					continue;
+				}
+				if (group.length && (signatures.get(group[0][1]) !== signatures.get(link[1]) || adjacent.get(`${group.at(-1)[1]}\n${link[1]}`)?.size !== users.get(link[1])?.length)) await flush();
+				group.push(link);
+			}
+			await flush();
+			html = html.replace(run[0], replacement);
+		}
+		await writeFile(file, html);
+	}
+}
 // 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
@@ -301,8 +452,38 @@ function fenceProps(node) {
 	if (!props.lang) props.lang = node.lang ?? "";
 	return props;
 }
-const componentsExport = `import { markdownComponents as __markdownComponents } from '@master/internal-site/components/markdown-components'
-export const components = __markdownComponents`;
+const componentPaths = {
+	a: "markdown/Anchor.astro",
+	h2: "markdown/Heading2.astro",
+	h3: "markdown/Heading3.astro",
+	img: "Image.svelte",
+	Image: "Image.svelte",
+	table: "markdown/Table.astro",
+	Code: "Code.astro",
+	InlineCode: "InlineCode.astro",
+	PMAction: "PMAction.astro",
+	Do: "Do.astro",
+	DoNot: "DoNot.astro",
+	Info: "Info.astro",
+	Warn: "Warn.astro",
+	InteractingIndicator: "InteractingIndicator.astro"
+};
+function documentComponents(tree) {
+	const used = /* @__PURE__ */ new Set();
+	visit(tree, (node) => {
+		if (node.type === "link" || node.type === "linkReference") used.add("a");
+		if (node.type === "image" || node.type === "imageReference") used.add("img");
+		if (node.type === "table") used.add("table");
+		if (node.type === "heading" && [2, 3].includes(node.depth)) used.add(`h${node.depth}`);
+		if (["mdxJsxFlowElement", "mdxJsxTextElement"].includes(node.type) && node.name in componentPaths) used.add(node.name);
+	});
+	const entries = [...used].sort().map((name, index) => ({
+		name,
+		local: `__masterComponent${index}`,
+		path: componentPaths[name]
+	}));
+	return entries.map(({ local, path }) => `import ${local} from '@master/internal-site/components/${path}'`).join("\n") + `\nexport const components = {${entries.map(({ name, local }) => `${name}: ${local}`).join(", ")}}`;
+}
 /**
 * Markdown constructs that render through site components: fences become `Code` (or a
 * package-manager `PMAction`), inline code becomes `InlineCode`, and marked paragraphs become
@@ -310,14 +491,6 @@ export const components = __markdownComponents`;
 */
 function remarkMarkdownComponents() {
 	return (tree) => {
-		tree.children.unshift({
-			type: "mdxjsEsm",
-			value: componentsExport,
-			data: { estree: parse(componentsExport, {
-				ecmaVersion: "latest",
-				sourceType: "module"
-			}) }
-		});
 		visit(tree, (node, index, parent) => {
 			if (!parent || index === void 0) return;
 			if (node.type === "code") {
@@ -352,6 +525,15 @@ function remarkMarkdownComponents() {
 				return index;
 			}
 		});
+		const source = documentComponents(tree);
+		tree.children.unshift({
+			type: "mdxjsEsm",
+			value: source,
+			data: { estree: parse(source, {
+				ecmaVersion: "latest",
+				sourceType: "module"
+			}) }
+		});
 	};
 }
 // src/astro/index.ts
@@ -364,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");
@@ -382,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",
@@ -420,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;
@@ -479,6 +663,7 @@ function masterSite(site) {
 					vite: {
 						plugins: [
 							plugin,
+							localizedMdx(site.i18n),
 							sourceURL(),
 							serverStyles([root, packageSource]),
 							svgMarkup()
@@ -503,6 +688,7 @@ function masterSite(site) {
 					recursive: true,
 					force: false
 				});
+				await compactStyleAssets(fileURLToPath(destination));
 			}
 		}
 	};

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;