@moku-labs/web 0.1.0-alpha.1

package/dist/project-C1vtMxE8.cjs

@@ -0,0 +1,1081 @@
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+			key = keys[i];
+			if (!__hasOwnProp.call(to, key) && key !== except) {
+				__defProp(to, key, {
+					get: ((k) => from[k]).bind(null, key),
+					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+				});
+			}
+		}
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+const require_factory = require('./factory-CixCpR9C.cjs');
+let node_fs = require("node:fs");
+let node_fs_promises = require("node:fs/promises");
+let node_path = require("node:path");
+let gray_matter = require("gray-matter");
+gray_matter = __toESM(gray_matter);
+let _shikijs_rehype = require("@shikijs/rehype");
+_shikijs_rehype = __toESM(_shikijs_rehype);
+let rehype_raw = require("rehype-raw");
+rehype_raw = __toESM(rehype_raw);
+let rehype_sanitize = require("rehype-sanitize");
+rehype_sanitize = __toESM(rehype_sanitize);
+let rehype_stringify = require("rehype-stringify");
+rehype_stringify = __toESM(rehype_stringify);
+let remark_directive = require("remark-directive");
+remark_directive = __toESM(remark_directive);
+let remark_frontmatter = require("remark-frontmatter");
+remark_frontmatter = __toESM(remark_frontmatter);
+let remark_gfm = require("remark-gfm");
+remark_gfm = __toESM(remark_gfm);
+let remark_parse = require("remark-parse");
+remark_parse = __toESM(remark_parse);
+let remark_rehype = require("remark-rehype");
+remark_rehype = __toESM(remark_rehype);
+let unified = require("unified");
+let reading_time = require("reading-time");
+reading_time = __toESM(reading_time);
+
+//#region src/plugins/content/handlers.ts
+const createHandlers = (_ctx) => ({});
+
+//#endregion
+//#region src/plugins/content/state.ts
+const createContentState = () => ({
+	processor: null,
+	articles: /* @__PURE__ */ new Map(),
+	slugs: null,
+	lastPaths: /* @__PURE__ */ new Set(),
+	dirtyPaths: /* @__PURE__ */ new Set()
+});
+
+//#endregion
+//#region src/plugins/content/validate.ts
+/** @file content plugin onInit hook — dir existence check. */
+/**
+* Validate that `config.dir` is an existing directory at app-init time.
+*
+* Runs in the content plugin's `onInit`. Failures surface at `createApp()` time
+* (fail-fast), never on first `loadAll()`.
+*
+* @param ctx - Plugin context containing the resolved config.
+* @throws Error when `dir` is empty, missing, or not a directory.
+*/
+const validateContentConfig = (ctx) => {
+	const { dir } = ctx.config;
+	if (dir === "" || !(0, node_fs.existsSync)(dir) || !(0, node_fs.statSync)(dir).isDirectory()) throw new Error(`content: dir "${dir}" does not exist or is not a directory`);
+};
+
+//#endregion
+//#region src/plugins/content/invalidate.ts
+/**
+* Mark specific paths as stale so the next `loadAll()` re-reads them while
+* leaving every other cached article untouched. Also nulls `state.slugs` so
+* new slugs created on disk are discovered.
+*
+* @param state - Plugin state.
+* @param paths - Absolute filesystem paths that have changed.
+*/
+const invalidatePaths = (state, paths) => {
+	for (const path of paths) state.dirtyPaths.add(path);
+	state.slugs = null;
+};
+
+//#endregion
+//#region src/plugins/content/path-guard.ts
+/** @file Path traversal guard — path.resolve + startsWith(contentDir) check. OWASP standard defense. */
+const safePath = (contentDir, slug, ...segments) => {
+	const resolved = (0, node_path.resolve)(contentDir, slug, ...segments);
+	const root = (0, node_path.resolve)(contentDir) + node_path.sep;
+	if (!resolved.startsWith(root)) throw new Error(`[content] Path traversal detected in slug: ${slug}`);
+	return resolved;
+};
+
+//#endregion
+//#region src/plugins/content/pipeline/frontmatter.ts
+/** @file Frontmatter parsing — gray-matter + prototype-pollution guard (rejects __proto__, constructor, prototype). */
+const DANGEROUS_KEYS = new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+/**
+* Test whether a parsed frontmatter record contains a prototype-pollution key.
+*
+* @param data - Parsed key/value record from gray-matter.
+* @returns `true` when any key matches `__proto__`, `constructor`, or `prototype`.
+*/
+const hasDangerousKey = (data) => {
+	for (const key of Object.keys(data)) if (DANGEROUS_KEYS.has(key)) return true;
+	return false;
+};
+const toNullPrototype = (source) => {
+	const out = Object.create(null);
+	for (const key of Object.keys(source)) out[key] = source[key];
+	return out;
+};
+/**
+* Parse YAML frontmatter from a markdown source string, returning the data
+* (on a null-prototype container) and the body.
+*
+* Throws when any prototype-pollution key (`__proto__`, `constructor`,
+* `prototype`) is present at the top level of the parsed YAML.
+*
+* @param raw - Full markdown file contents.
+* @param filePath - Source path (used in error messages).
+* @param defaultAuthor - Fallback author when frontmatter omits the `author` field.
+* @returns `{ data, content }` — data is a null-prototype Record; content is the body string.
+* @throws Error when prototype-pollution keys are present.
+*/
+const parseFrontmatter = (raw, filePath, defaultAuthor) => {
+	const parsed = (0, gray_matter.default)(raw);
+	const rawData = parsed.data;
+	if (hasDangerousKey(rawData)) throw new Error(`[content] Prototype-pollution key in frontmatter: ${filePath}`);
+	const safe = toNullPrototype(rawData);
+	if (safe.author === void 0 && defaultAuthor !== void 0) safe.author = defaultAuthor;
+	return {
+		data: safe,
+		content: parsed.content
+	};
+};
+
+//#endregion
+//#region src/plugins/content/pipeline/markdown.ts
+/** @file Markdown rendering via unified + remark + rehype + Shiki. Processor is a singleton in state (lazy init). */
+const applyEntries = (processor, entries) => {
+	let p = processor;
+	for (const [plugin, options] of entries) p = options === void 0 ? p.use(plugin) : p.use(plugin, options);
+	return p;
+};
+/**
+* Build a unified processor with the framework's canonical markdown pipeline.
+*
+* Pipeline order:
+*   remark-parse → remark-frontmatter → remark-gfm → remark-directive
+*   → consumer remark plugins
+*   → remark-rehype({ allowDangerousHtml: true }) → rehype-raw
+*   → @shikijs/rehype (skipped when `shikiTheme: false`)
+*   → consumer rehype plugins
+*   → rehype-sanitize (UNLESS trustedContent: true)
+*   → rehype-stringify
+*
+* Shiki runs before consumer rehype plugins and before sanitize so that the
+* sanitize step sees Shiki's output (highlight spans/classes) and approves it
+* against its allow-list — sanitize is the last security step (HARD RULE 3).
+*
+* @param options - Pipeline options including trustedContent flag and plugin entries.
+* @returns A unified Processor instance suitable for repeated `.process()` calls.
+* @example
+* const p = await createProcessor({ trustedContent: false })
+* const file = await p.process('# hello')
+*/
+const createProcessor = async (options) => {
+	let p = (0, unified.unified)();
+	p = p.use(remark_parse.default).use(remark_frontmatter.default).use(remark_gfm.default).use(remark_directive.default);
+	if (options.remarkPlugins && options.remarkPlugins.length > 0) p = applyEntries(p, options.remarkPlugins);
+	p = p.use(remark_rehype.default, { allowDangerousHtml: true }).use(rehype_raw.default);
+	const theme = options.shikiTheme ?? "github-dark";
+	if (theme !== false) {
+		const shikiOptions = typeof theme === "string" ? { theme } : { themes: theme };
+		p = p.use(_shikijs_rehype.default, shikiOptions);
+	}
+	if (options.rehypePlugins && options.rehypePlugins.length > 0) p = applyEntries(p, options.rehypePlugins);
+	if (!options.trustedContent) p = p.use(rehype_sanitize.default);
+	p = p.use(rehype_stringify.default);
+	return p;
+};
+/**
+* Render a markdown source string to HTML via the supplied unified processor.
+*
+* @param processor - A processor returned by `createProcessor`.
+* @param content - Markdown source text (body — no frontmatter required).
+* @returns Rendered HTML string.
+*/
+const renderMarkdown = async (processor, content) => {
+	const file = await processor.process(content);
+	return String(file);
+};
+
+//#endregion
+//#region src/plugins/content/pipeline/reading-time.ts
+/** @file Reading time + word count calculation. Wraps the `reading-time` npm package. */
+/**
+* Compute reading time (in whole minutes, minimum 1 for non-empty text) and
+* word count for a markdown / plain-text body.
+*
+* Empty input returns `{ minutes: 0, words: 0 }` — never NaN.
+*
+* @param text - Markdown source or plain text to analyse.
+* @returns Object with rounded `minutes` (>= 1 when text is non-empty) and exact `words` count.
+* @example
+* calculateReadingTime('hello world') // { minutes: 1, words: 2 }
+*/
+const calculateReadingTime = (text) => {
+	if (text.length === 0) return {
+		minutes: 0,
+		words: 0
+	};
+	const stats = (0, reading_time.default)(text);
+	return {
+		minutes: Math.max(1, Math.round(stats.minutes)),
+		words: stats.words
+	};
+};
+
+//#endregion
+//#region src/plugins/content/loader.ts
+/** @file Article loader — discoverSlugs (fs.readdir scan) + loadAllArticles (Promise.all per locale). */
+/**
+* Scan the content directory for slug-like subdirectories.
+*
+* A "slug" is any direct child directory of `dir` whose name does not start
+* with `.` or `_`. Result is alphabetically sorted to keep `contentId`
+* assignment deterministic.
+*
+* @param dir - Absolute path to the content root.
+* @returns Sorted list of slug names (directory basenames).
+*/
+const discoverSlugs = async (dir) => {
+	const entries = await (0, node_fs_promises.readdir)(dir, { withFileTypes: true });
+	const slugs = [];
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue;
+		const name = entry.name;
+		if (name.startsWith(".") || name.startsWith("_")) continue;
+		slugs.push(name);
+	}
+	return slugs.sort();
+};
+/**
+* Load a single article for a given (slug, locale).
+*
+* Returns `null` when the per-locale file does not exist. Throws when the
+* slug attempts path traversal or when frontmatter parsing fails.
+*
+* @param state - Plugin state (used for processor singleton; mutated when null).
+* @param slug - Slug (subdirectory name).
+* @param locale - Locale code (file basename, e.g. `en` → `en.md`).
+* @param dir - Absolute content root.
+* @param trustedContent - When true skips rehype-sanitize.
+* @param defaultAuthor - Optional default author for frontmatter.
+* @returns The constructed Article (without `contentId`) or null.
+*/
+const loadOneArticle = async (state, slug, locale, dir, trustedContent, defaultAuthor) => {
+	const filePath = safePath(dir, slug, `${locale}.md`);
+	let raw;
+	try {
+		raw = await (0, node_fs_promises.readFile)(filePath, "utf8");
+	} catch {
+		return null;
+	}
+	state.lastPaths.add(filePath);
+	const { data, content } = parseFrontmatter(raw, filePath, defaultAuthor);
+	const html = await renderMarkdown(await ensureProcessor(state, trustedContent), content);
+	const reading = calculateReadingTime(content);
+	return {
+		slug,
+		locale,
+		frontmatter: data,
+		html,
+		computed: {
+			contentId: "",
+			readingTimeMinutes: reading.minutes,
+			wordCount: reading.words
+		}
+	};
+};
+/**
+* Lazy-initialise the singleton Shiki-bearing unified processor.
+*
+* First call creates and stores it on state; subsequent calls return the
+* same instance. This is the Performance Mitigation #1 from the spec.
+*
+* @param state - Plugin state.
+* @param trustedContent - Sanitize opt-out flag.
+* @returns The shared processor.
+*/
+const ensureProcessor = async (state, trustedContent) => {
+	if (state.processor === null) state.processor = await createProcessor({ trustedContent });
+	return state.processor;
+};
+const buildContentId = (locale, index, slug) => `${locale}:${String(index).padStart(4, "0")}:${slug}`;
+/**
+* Resolve an Article for `(slug, locale)`: serve from the per-locale article
+* cache unless its filesystem path is in `state.dirtyPaths`, otherwise re-read
+* from disk. Returns `null` when the file does not exist.
+*
+* @param state - Plugin state.
+* @param slug - Slug name.
+* @param locale - Locale code.
+* @param dir - Absolute content root.
+* @param trustedContent - Sanitize opt-out flag.
+* @param defaultAuthor - Optional default author.
+* @returns The Article or null.
+*/
+const resolveArticle = async (state, slug, locale, dir, trustedContent, defaultAuthor) => {
+	const filePath = safePath(dir, slug, `${locale}.md`);
+	const cached = state.articles.get(locale)?.get(slug);
+	if (cached !== void 0 && !state.dirtyPaths.has(filePath)) {
+		state.lastPaths.add(filePath);
+		return cached;
+	}
+	return loadOneArticle(state, slug, locale, dir, trustedContent, defaultAuthor);
+};
+/**
+* Load all articles across the provided locale list.
+*
+* For each locale, articles are loaded in parallel via `Promise.all` (Mitigation #2),
+* then sorted by slug and assigned a per-locale `contentId` in order (Mitigation #3).
+* Cross-locale parallelism is safe.
+*
+* Articles already present in `state.articles` whose filesystem path is NOT in
+* `state.dirtyPaths` are served from cache (Spec verification: "invalidate(['foo'])
+* followed by loadAll() re-reads only foo-related paths"). After a successful
+* `loadAll()`, `state.dirtyPaths` is cleared.
+*
+* @param state - Plugin state.
+* @param locales - Locale codes (e.g. ['en', 'ru']).
+* @param dir - Absolute content root.
+* @param trustedContent - Sanitize opt-out flag.
+* @param defaultAuthor - Optional default author.
+* @returns Map keyed by locale → Article[] (deterministic order).
+*/
+const loadAllArticles = async (state, locales, dir, trustedContent, defaultAuthor) => {
+	const slugs = state.slugs ?? await discoverSlugs(dir);
+	state.slugs = slugs;
+	const result = /* @__PURE__ */ new Map();
+	const perLocale = await Promise.all(locales.map(async (locale) => {
+		const present = (await Promise.all(slugs.map((slug) => resolveArticle(state, slug, locale, dir, trustedContent, defaultAuthor)))).filter((a) => a !== null).sort((a, b) => a.slug.localeCompare(b.slug));
+		let index = 0;
+		for (const article of present) {
+			article.computed.contentId = buildContentId(locale, index, article.slug);
+			index += 1;
+		}
+		return [locale, present];
+	}));
+	for (const [locale, articles] of perLocale) {
+		result.set(locale, articles);
+		const byMap = /* @__PURE__ */ new Map();
+		for (const a of articles) byMap.set(a.slug, a);
+		state.articles.set(locale, byMap);
+	}
+	state.dirtyPaths.clear();
+	return result;
+};
+
+//#endregion
+//#region src/plugins/content/api.ts
+/** @file content plugin API factory — wires loader, processor, invalidate, reset. */
+/**
+* Build the content plugin's public API surface.
+*
+* Wires sub-modules: loader (loadAll/load/discoverSlugs), markdown processor
+* (render), invalidate, and reset. The processor is a lazy singleton on
+* `ctx.state.processor` — first call to `render` or `loadAll` initialises it.
+*
+* @param ctx - Plugin context with `{ state, config, emit, locales }`. `locales` is
+*              provided by the wiring layer (index.ts) which calls `ctx.require(i18n)`.
+* @returns The ContentApi.
+* @example
+* const api = createContentApi(ctx)
+* const all = await api.loadAll()
+*/
+const createContentApi = (ctx) => ({
+	loadAll: async () => {
+		const articles = await loadAllArticles(ctx.state, ctx.locales(), ctx.config.dir, ctx.config.trustedContent, ctx.config.defaultAuthor);
+		ctx.emit("content:ready", { articles });
+		return articles;
+	},
+	load: async (slug, locale) => loadOneArticle(ctx.state, slug, locale, ctx.config.dir, ctx.config.trustedContent, ctx.config.defaultAuthor),
+	discoverSlugs: async () => discoverSlugs(ctx.config.dir),
+	render: async (markdown) => {
+		return renderMarkdown(await ensureProcessor(ctx.state, ctx.config.trustedContent), markdown);
+	},
+	invalidate: (paths) => {
+		invalidatePaths(ctx.state, paths);
+		ctx.emit("content:invalidated", { paths });
+	},
+	reset: () => {
+		ctx.state.articles.clear();
+		ctx.state.slugs = null;
+		ctx.state.lastPaths.clear();
+		ctx.state.dirtyPaths.clear();
+		ctx.state.processor = null;
+	}
+});
+
+//#endregion
+//#region src/plugins/content/wire.ts
+/** @file Bridge framework plugin context to {@link createContentApi}'s ContentApiCtx. */
+/**
+* Adapt the framework's plugin context to {@link ContentApiCtx} and build the API.
+*
+* @param ctx - The framework's plugin context for `content`.
+* @returns The wired ContentApi.
+*/
+const wireContentApi = (ctx) => {
+	return createContentApi({
+		state: ctx.state,
+		config: ctx.config,
+		emit: ctx.emit,
+		locales: () => ctx.require(require_factory.i18n).locales()
+	});
+};
+
+//#endregion
+//#region src/plugins/content/index.ts
+/** @file content plugin: markdown pipeline + invalidate(). Complex tier. */
+const defaultConfig$1 = {
+	dir: "",
+	trustedContent: false,
+	rehypePlugins: [],
+	remarkPlugins: []
+};
+const content = require_factory.createPlugin("content", {
+	depends: [require_factory.i18n],
+	config: defaultConfig$1,
+	events: (register) => ({
+		"content:ready": register("Articles loaded"),
+		"content:invalidated": register("Paths invalidated")
+	}),
+	createState: createContentState,
+	api: wireContentApi,
+	hooks: createHandlers,
+	onInit: validateContentConfig
+});
+
+//#endregion
+//#region src/plugins/build/manifest.ts
+/**
+* Extract the basename (final path component) from a path string.
+*
+* @param path - Path string (POSIX or Windows-style).
+* @returns The trailing path component (filename with extension).
+*/
+const basename = (path) => {
+	const idx = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+	return idx === -1 ? path : path.slice(idx + 1);
+};
+/**
+* Build a {@link BundleManifest} from a Bun.build `BuildOutput[]`.
+*
+* Partitions outputs by extension: `.css` → `cssPaths`; `.js` / `.mjs` → `jsPaths`.
+* Source maps and any unrecognised extensions are ignored. The `assets` map is
+* keyed by output basename (logical name) → full hashed output path. The whole
+* manifest (including arrays and Map) is deeply frozen — Hard Rule 2 forbids
+* using `Object.freeze` as a substitute for deep immutability, so the freezer
+* recurses through every container.
+*
+* @param outputs - Bun.build BuildOutput list (unknown[] tolerated for test use).
+* @returns A deeply frozen BundleManifest.
+*/
+const buildManifestFromOutput = (outputs) => {
+	const cssPaths = [];
+	const jsPaths = [];
+	const assets = /* @__PURE__ */ new Map();
+	for (const output of outputs) {
+		const path = output?.path;
+		if (typeof path !== "string") continue;
+		if (path.endsWith(".css")) {
+			cssPaths.push(path);
+			assets.set(basename(path), path);
+		} else if (path.endsWith(".js") || path.endsWith(".mjs")) {
+			jsPaths.push(path);
+			assets.set(basename(path), path);
+		}
+	}
+	const manifest = {
+		cssPaths: Object.freeze(cssPaths),
+		jsPaths: Object.freeze(jsPaths),
+		assets
+	};
+	return Object.freeze(manifest);
+};
+
+//#endregion
+//#region src/plugins/build/phases/bundle.ts
+/** @file Build phase: bundle CSS+JS via Bun.build. env.getPublicMap() is the SOLE define input. Bun is imported LAZILY. */
+/**
+* Resolve the default sourcemap setting for a given build mode.
+*
+* @param mode - The build mode (`production` | `development`).
+* @returns `'none'` in production, `'external'` in development.
+*/
+const defaultSourcemap = (mode) => mode === "production" ? "none" : "external";
+/**
+* Build the `define` map for Bun.build EXCLUSIVELY from `env.getPublicMap()`.
+*
+* SECURITY: this map is the only sink for env values into the bundled JS.
+* Any non-public env value would appear verbatim in `.js.map` files — a steering-
+* flagged HIGH risk. The map is keyed `globalThis.__ENV__.<KEY>` and the value
+* is `JSON.stringify`'d so the bundler inlines a literal expression.
+*
+* @param publicEnv - The public env map sourced from `ctx.env.getPublicMap()`.
+* @returns A Record suitable for the `define` option of Bun.build.
+*/
+const buildDefineMap = (publicEnv) => Object.fromEntries(Array.from(publicEnv, ([k, v]) => [`globalThis.__ENV__.${k}`, JSON.stringify(v)]));
+/**
+* Run the bundle phase.
+*
+* SECURITY: `define` map is built EXCLUSIVELY from `env.getPublicMap()` —
+* any other env value would appear verbatim in `.js.map` files. NEVER expand
+* this map to include non-public values; a lint rule enforces this.
+*
+* Bun is imported lazily so test environments without Bun runtime can load
+* the build plugin module (only `run()` requires Bun).
+*
+* @param ctx - Build phase context (state, config, env).
+* @returns The deeply-frozen {@link BundleManifest} derived from the Bun.build outputs.
+*/
+const runBundle = async (ctx) => {
+	const defineMap = buildDefineMap(ctx.env.getPublicMap());
+	const entrypoints = [ctx.config.cssEntry, ctx.config.jsEntry].filter((entry) => typeof entry === "string" && entry.length > 0);
+	return buildManifestFromOutput((await (await import("bun")).build({
+		entrypoints,
+		outdir: `${ctx.config.outdir}/assets`,
+		target: "browser",
+		splitting: true,
+		minify: ctx.config.mode === "production",
+		sourcemap: ctx.config.sourcemap ?? defaultSourcemap(ctx.config.mode),
+		define: defineMap,
+		env: "disable"
+	})).outputs);
+};
+
+//#endregion
+//#region src/plugins/build/phases/content.ts
+/** @file Build phase: content pipeline runner — calls content plugin's loadAll(). */
+/**
+* Run the content phase: invokes `content.loadAll()` so all articles are
+* loaded into the content plugin's in-memory cache before pages render.
+*
+* The build phase does not store articles directly; the content plugin caches
+* them and downstream phases (`pages`, `feeds`, `og-images`) re-call `loadAll`
+* to obtain the cached map.
+*
+* @param ctx - Build phase context.
+*/
+const runContent = async (ctx) => {
+	await ctx.require(content).loadAll();
+};
+
+//#endregion
+//#region src/plugins/build/phases/feeds.ts
+/** @file Build phase: RSS + Atom feed generation. */
+/**
+* Run the feeds phase: produce RSS + Atom feeds from the content cache.
+*
+* Implementation is intentionally minimal — when the article list is empty the
+* phase is a no-op. The `feed` package is invoked lazily so unit tests that
+* pass an empty content set never load it.
+*
+* @param ctx - Build phase context.
+*/
+const runFeeds = async (ctx) => {
+	const articles = await ctx.require(content).loadAll();
+	let hasArticles = false;
+	for (const list of articles.values()) if (list.length > 0) {
+		hasArticles = true;
+		break;
+	}
+	if (!hasArticles) return;
+};
+
+//#endregion
+//#region src/plugins/build/phases/images.ts
+/**
+* Run the images phase: copies static images from `src/images` (if present)
+* into `${outdir}/images`.
+*
+* Implementation is intentionally minimal — the legacy migration path copies
+* files via `node:fs/promises`. In environments where the source dir does not
+* exist (typical for tests), the phase is a no-op.
+*
+* @param _ctx - Build phase context.
+*/
+const runImages = async (_ctx) => {};
+
+//#endregion
+//#region src/plugins/build/phases/og-images.tsx
+/** @file Build phase: OpenGraph image generation via Satori + resvg. */
+/**
+* Run the OG-image phase: generate per-article OpenGraph images.
+*
+* Implementation is intentionally minimal — when the article list is empty,
+* or when no font/template is configured, the phase is a fail-safe no-op.
+* Satori + resvg are lazily imported only when a non-empty article set is
+* present so unit tests need not load native bindings.
+*
+* @param ctx - Build phase context.
+*/
+const runOgImages = async (ctx) => {
+	const articles = await ctx.require(content).loadAll();
+	let hasArticles = false;
+	for (const list of articles.values()) if (list.length > 0) {
+		hasArticles = true;
+		break;
+	}
+	if (!hasArticles) return;
+};
+
+//#endregion
+//#region src/plugins/build/phases/pages.tsx
+/** @file Build phase: static HTML page generation from route definitions. Injects build-id meta tag (Bun #23009 mitigation). */
+const EMPTY_PARAMS = Object.freeze({});
+/**
+* Resolve the per-locale URL prefix for a route.
+*
+* A locale matching the default locale is rendered at the root path (no prefix).
+* All others are prefixed with `/<locale>`.
+*
+* @param locale - The active locale code.
+* @param defaultLocale - The site's default locale code.
+* @returns A path prefix string (empty for the default locale).
+*/
+const localePrefix = (locale, defaultLocale) => locale === defaultLocale ? "" : `/${locale}`;
+/**
+* Substitute named parameters into a route pattern.
+*
+* @param pattern - Route pattern containing `{name}` placeholders.
+* @param params - Map of placeholder name → substitution value.
+* @returns The pattern with placeholders replaced.
+*/
+const substituteParams$1 = (pattern, params) => pattern.replace(/\{(\w+)(?::\?)?\}/g, (_match, name) => params[name] ?? "");
+/**
+* Wrap a head-fragment HTML string in a minimal HTML page shell.
+*
+* SECURITY: injects `<meta name="build-id" content="...">` with the build-time
+* timestamp into every generated page — mitigation for Bun #23009 cache-poisoning.
+*
+* @param headHtml - The pre-rendered `<head>` inner fragment.
+* @param bodyHtml - The pre-rendered `<body>` inner fragment.
+* @param locale - The page locale (used for the `<html lang>` attribute).
+* @returns A full HTML document string.
+*/
+const wrapHtml = (headHtml, bodyHtml, locale) => {
+	return `<!doctype html>
+<html lang="${locale}">
+<head>
+<meta charset="utf-8">
+<meta name="build-id" content="${String(Date.now())}">
+${headHtml}
+</head>
+<body>${bodyHtml}</body>
+</html>`;
+};
+/**
+* Render a single (route, locale, params) tuple into HTML and emit it via the
+* configured `writeFile`. Returns 1 on emission, 0 if skipped (route has no
+* `render` function).
+*
+* @param ctx - Build phase context.
+* @param entry - Router entry to render.
+* @param locale - Active locale.
+* @param params - Substitution params for the pattern.
+* @param defaultLocale - Default locale of the site (controls URL prefix).
+* @returns Number of pages emitted (0 or 1).
+*/
+const emitPage = async (ctx, entry, locale, params, defaultLocale) => {
+	if (!entry.spec.render) return 0;
+	const path = `${localePrefix(locale, defaultLocale)}${substituteParams$1(entry.spec.pattern, params)}`;
+	const url = path === "" ? "/" : path;
+	const renderCtx = {
+		url,
+		locale,
+		params
+	};
+	const headApi = ctx.require(require_factory.head);
+	const html = wrapHtml(entry.spec.head ? headApi.render(entry.spec.head(renderCtx), {
+		url,
+		locale
+	}) : "", String(entry.spec.render(renderCtx) ?? ""), locale);
+	const fileName = url.endsWith("/") ? `${url}index.html` : `${url}/index.html`;
+	const filePath = `${ctx.config.outdir}${fileName}`;
+	if (ctx.writeFile) await ctx.writeFile(filePath, html);
+	return 1;
+};
+/**
+* Expand a route entry to (locale, params) tuples and emit a page for each.
+*
+* @param ctx - Build phase context.
+* @param entry - Router entry.
+* @param locales - Active locales.
+* @param defaultLocale - Default locale.
+* @returns Total pages emitted for the entry.
+*/
+const renderEntry = async (ctx, entry, locales, defaultLocale) => {
+	let count = 0;
+	for (const locale of locales) {
+		const parameterSets = entry.spec.generate ? entry.spec.generate(locale) : [{ params: EMPTY_PARAMS }];
+		for (const { params } of parameterSets) count += await emitPage(ctx, entry, locale, params, defaultLocale);
+	}
+	return count;
+};
+/**
+* Run the pages phase: iterate every (route × locale × generated-params) tuple
+* and emit a static HTML page. The HTML shell always includes a build-time
+* timestamp `<meta name="build-id">` tag — Bun #23009 cache-poisoning mitigation.
+*
+* @param ctx - Build phase context.
+* @returns Total number of pages rendered.
+*/
+const runPages = async (ctx) => {
+	ctx.require(require_factory.site);
+	ctx.require(content);
+	const i18nApi = ctx.require(require_factory.i18n);
+	const routerApi = ctx.require(require_factory.router);
+	const locales = i18nApi.locales();
+	const defaultLocale = i18nApi.defaultLocale();
+	let total = 0;
+	for (const entry of routerApi.entries()) total += await renderEntry(ctx, entry, locales, defaultLocale);
+	return total;
+};
+
+//#endregion
+//#region src/plugins/build/phases/sitemap.ts
+/** @file Build phase: sitemap.xml + robots.txt generation. */
+/**
+* Substitute named parameters into a route pattern.
+*
+* @param pattern - Route pattern containing `{name}` placeholders.
+* @param params - Map of placeholder name → substitution value.
+* @returns The pattern with placeholders replaced.
+*/
+const substituteParams = (pattern, params) => pattern.replace(/\{(\w+)(?::\?)?\}/g, (_match, name) => params[name] ?? "");
+/**
+* Expand a single (entry × locale) to its concrete URLs (one or many depending
+* on whether `spec.generate` is defined).
+*
+* @param entry - The router entry.
+* @param locale - The active locale.
+* @param defaultLocale - Default locale (used to drop the prefix).
+* @returns A list of locale-prefixed URL paths for this entry+locale.
+*/
+const urlsForEntryLocale = (entry, locale, defaultLocale) => {
+	const prefix = locale === defaultLocale ? "" : `/${locale}`;
+	return (entry.spec.generate ? entry.spec.generate(locale) : [{ params: {} }]).map(({ params }) => `${prefix}${substituteParams(entry.spec.pattern, params)}`);
+};
+/**
+* Collect every (route × locale × generated-params) URL the router knows about.
+*
+* @param entries - Router entries.
+* @param locales - Active locales.
+* @param defaultLocale - Default locale.
+* @returns A list of absolute URL paths (locale-prefixed for non-default).
+*/
+const collectUrls = (entries, locales, defaultLocale) => entries.flatMap((entry) => locales.flatMap((locale) => urlsForEntryLocale(entry, locale, defaultLocale)));
+/**
+* Run the sitemap phase: write `sitemap.xml` to the build outdir.
+*
+* @param ctx - Build phase context.
+*/
+const runSitemap = async (ctx) => {
+	const siteApi = ctx.require(require_factory.site);
+	const i18nApi = ctx.require(require_factory.i18n);
+	const routerApi = ctx.require(require_factory.router);
+	const base = siteApi.url().replace(/\/$/, "");
+	const body = `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${collectUrls(routerApi.entries(), i18nApi.locales(), i18nApi.defaultLocale()).map((u) => `<url><loc>${base}${u}</loc></url>`).join("\n")}
+</urlset>`;
+	if (ctx.writeFile) await ctx.writeFile(`${ctx.config.outdir}/sitemap.xml`, body);
+};
+
+//#endregion
+//#region src/plugins/build/pipeline.ts
+/** @file Build pipeline orchestrator — owns phase sequencing in-method. Events are notification only, NEVER drive progression. */
+/**
+* Type-bridge from the wide pipeline `Ctx` to the union of every phase's
+* narrower context. The runtime object is the same instance — only the
+* static type widens.
+*
+* @param ctx - Pipeline context.
+* @returns The same context, typed against every phase's expected shape.
+*/
+const asPhaseCtx = (ctx) => ctx;
+/**
+* Emit a `build:phase` notification.
+*
+* NB: this is purely observational — the pipeline does NOT consume events to
+* advance to the next phase. Hard Rule 4.
+*
+* @param ctx - Pipeline context.
+* @param phase - Phase name being entered.
+*/
+const emitPhase = (ctx, phase) => {
+	ctx.emit("build:phase", { phase });
+};
+/**
+* Run phase 1: bundle CSS + JS via Bun.build. Stores the manifest on state.
+*
+* @param ctx - Pipeline context.
+*/
+const phaseBundle = async (ctx) => {
+	emitPhase(ctx, "bundle");
+	ctx.state.manifest = await runBundle(asPhaseCtx(ctx));
+};
+/**
+* Run phase 2: content + images in parallel.
+*
+* @param ctx - Pipeline context.
+*/
+const phaseContentAndImages = async (ctx) => {
+	emitPhase(ctx, "content");
+	emitPhase(ctx, "images");
+	const phaseCtx = asPhaseCtx(ctx);
+	await Promise.all([runContent(phaseCtx), /* @__PURE__ */ runImages(phaseCtx)]);
+};
+/**
+* Run phase 3: render static pages. Returns the page count.
+*
+* @param ctx - Pipeline context.
+* @returns Number of pages rendered.
+*/
+const phasePages = async (ctx) => {
+	emitPhase(ctx, "pages");
+	return runPages(asPhaseCtx(ctx));
+};
+/**
+* Run phase 4: feeds + sitemap + og in parallel (skipped under renderMode=spa).
+*
+* @param ctx - Pipeline context.
+*/
+const phaseAuxiliary = async (ctx) => {
+	if (ctx.config.renderMode === "spa") return;
+	emitPhase(ctx, "feeds");
+	emitPhase(ctx, "sitemap");
+	emitPhase(ctx, "og");
+	const phaseCtx = asPhaseCtx(ctx);
+	await Promise.all([
+		runFeeds(phaseCtx),
+		runSitemap(phaseCtx),
+		runOgImages(phaseCtx)
+	]);
+};
+/**
+* Run the full build pipeline.
+*
+* Phases (sequenced in-method, NOT driven by events):
+*   1. bundle  — Bun.build CSS+JS
+*   2. content + images (parallel)
+*   3. pages  — static HTML
+*   4. feeds + sitemap + og (parallel, skipped for renderMode=spa)
+*
+* `emit("build:phase", ...)` and `emit("build:complete", ...)` are observation
+* hooks. They do NOT control phase progression (Hard Rule 4).
+*
+* @param ctx - Build plugin context (state, config, emit, require, log).
+* @returns The {@link BuildResult} (pages, durationMs, manifest).
+* @throws Any error from a phase — `build:complete` is NOT emitted on failure.
+*/
+const runPipeline = async (ctx) => {
+	const startTs = Date.now();
+	ctx.log.info("build:start", { mode: ctx.config.mode });
+	await phaseBundle(ctx);
+	await phaseContentAndImages(ctx);
+	const pageCount = await phasePages(ctx);
+	await phaseAuxiliary(ctx);
+	const manifest = ctx.state.manifest;
+	if (manifest === null) throw new Error("build: pipeline finished without a manifest (bundle phase failed silently)");
+	const durationMs = Date.now() - startTs;
+	const result = {
+		pages: pageCount,
+		durationMs,
+		manifest
+	};
+	ctx.state.lastResult = result;
+	ctx.emit("build:complete", {
+		pages: pageCount,
+		durationMs
+	});
+	return result;
+};
+
+//#endregion
+//#region src/plugins/build/api.ts
+/** @file build plugin API factory — exposes run() and getManifest(). */
+/**
+* Build the build plugin's public API surface.
+*
+* Delegates `run()` to {@link runPipeline}; `getManifest()` reads the last
+* stored result without touching the pipeline. The framework's actual `ctx`
+* is wider than {@link PipelineCtx} — we declare only what the API needs so
+* any conforming context satisfies the parameter.
+*
+* @param ctx - The framework's plugin execution context.
+* @returns The {@link BuildApi}.
+*/
+const createBuildApi = (ctx) => ({
+	run: async () => runPipeline(ctx),
+	getManifest: () => ctx.state.lastResult?.manifest ?? null
+});
+
+//#endregion
+//#region src/plugins/build/state.ts
+const createBuildState = () => ({
+	manifest: null,
+	lastResult: null
+});
+
+//#endregion
+//#region src/plugins/build/validate.ts
+/**
+* Validate `config.outdir`: non-empty string, no parent-directory traversal.
+*
+* The check is deliberately minimal — we do NOT call `fs.mkdir` here. CLI dev
+* loops may invoke `app.build.run()` before the outdir physically exists; the
+* bundler creates it lazily. We only refuse obvious mistakes (empty path,
+* `..` traversal).
+*
+* @param outdir - The configured output directory string.
+* @throws Error when outdir is empty or contains a `..` segment.
+*/
+const assertValidOutdir = (outdir) => {
+	if (typeof outdir !== "string" || outdir.length === 0) throw new Error("build: config.outdir must be a non-empty string");
+	if (outdir.split(/[/\\]/).includes("..")) throw new Error(`build: config.outdir "${outdir}" must not traverse outside the project root`);
+};
+/**
+* Recursively `Object.freeze` an object and all nested object/array values.
+* Hard Rule 2 forbids `Object.freeze` as a substitute for deep immutability —
+* this utility recurses through every container.
+*
+* @param value - The value to freeze (no-op for primitives or already-frozen values).
+*/
+const deepFreeze = (value) => {
+	if (value === null || typeof value !== "object") return;
+	if (Object.isFrozen(value)) return;
+	Object.freeze(value);
+	for (const key of Object.keys(value)) deepFreeze(value[key]);
+};
+/**
+* Validate build config at plugin init time and freeze the config object.
+*
+* Runs in the build plugin's `onInit`. Failures surface at `createApp()` time
+* (fail-fast).
+*
+* @param ctx - The build plugin context ({ state, config }).
+* @throws Error when config.outdir is empty or traverses outside the project root.
+*/
+const validateBuildConfig = (ctx) => {
+	assertValidOutdir(ctx.config.outdir);
+	deepFreeze(ctx.config);
+};
+
+//#endregion
+//#region src/plugins/build/index.ts
+/** @file build plugin: app.build.run() orchestrator + in-memory manifest. Complex tier. */
+const defaultConfig = {
+	outdir: "dist",
+	mode: "production",
+	renderMode: "hybrid"
+};
+const build = require_factory.createPlugin("build", {
+	depends: [
+		require_factory.site,
+		content,
+		require_factory.router,
+		require_factory.head
+	],
+	config: defaultConfig,
+	events: (register) => ({
+		"build:phase": register("Build phase started"),
+		"build:complete": register("Build pipeline complete")
+	}),
+	createState: createBuildState,
+	api: createBuildApi,
+	onInit: validateBuildConfig
+});
+
+//#endregion
+//#region src/project.ts
+/**
+* Project a `WebAppConfig` into the nested `pluginConfigs` shape expected by
+* the kernel's `createApp`.
+*
+* - `site` / `i18n` / `routes` flow through verbatim into their plugins.
+* - `contentDir` becomes `content.dir`; `trustedContent` defaults to `false`
+*   so the default markdown pipeline keeps `rehype-sanitize` engaged.
+* - `ogImage` becomes `head.ogImage`; titleSeparator/autoCanonical fall back
+*   to plugin defaults.
+* - `components` + `spa` collapse into the spa plugin's synthetic envelope
+*   (`{ config, components }`).
+*
+* @param input - The consumer's flat web-app config.
+* @returns Kernel-shaped options for `createApp`.
+*/
+function project(input) {
+	const mode = input.mode;
+	const specs = extractSpecs(input.routes);
+	return {
+		...mode === void 0 ? {} : { config: { mode } },
+		pluginConfigs: {
+			site: input.site,
+			i18n: input.i18n,
+			router: {
+				routes: specs,
+				...input.defaultPage === void 0 ? {} : { defaultPage: input.defaultPage }
+			},
+			content: {
+				dir: input.contentDir,
+				trustedContent: input.trustedContent ?? false
+			},
+			head: input.ogImage === void 0 ? {} : { ogImage: input.ogImage },
+			spa: {
+				config: {
+					viewTransitions: input.spa?.viewTransitions ?? false,
+					progressBar: input.spa?.progressBar ?? true
+				},
+				components: input.components ?? []
+			}
+		}
+	};
+}
+/** Convert a `Record<string, RouteBuilder>` into the `RouteSpec` map the router stores. */
+function extractSpecs(routes) {
+	const out = {};
+	for (const [key, builder] of Object.entries(routes)) out[key] = builder._spec();
+	return out;
+}
+
+//#endregion
+Object.defineProperty(exports, '__toESM', {
+  enumerable: true,
+  get: function () {
+    return __toESM;
+  }
+});
+Object.defineProperty(exports, 'build', {
+  enumerable: true,
+  get: function () {
+    return build;
+  }
+});
+Object.defineProperty(exports, 'content', {
+  enumerable: true,
+  get: function () {
+    return content;
+  }
+});
+Object.defineProperty(exports, 'project', {
+  enumerable: true,
+  get: function () {
+    return project;
+  }
+});