@moku-labs/web 0.2.0 → 0.3.0

package/dist/index.cjs

@@ -1,4 +1,4 @@
-Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 //#region \0rolldown/runtime.js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -8,28 +8,20 @@ var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __exportAll = (all, no_symbols) => {
 	let target = {};
-	for (var name in all) {
-		__defProp(target, name, {
-			get: all[name],
-			enumerable: true
-		});
-	}
-	if (!no_symbols) {
-		__defProp(target, Symbol.toStringTag, { value: "Module" });
-	}
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
 	return target;
 };
 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
-				});
-			}
-		}
+	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;
 };
@@ -37,38 +29,38 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	value: mod,
 	enumerable: true
 }) : target, mod));
-
 //#endregion
 let _moku_labs_core = require("@moku-labs/core");
 let node_fs = require("node:fs");
 let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");
+let node_path$1 = __toESM(node_path, 1);
 node_path = __toESM(node_path);
 let gray_matter = require("gray-matter");
-gray_matter = __toESM(gray_matter);
+gray_matter = __toESM(gray_matter, 1);
 let _shikijs_rehype = require("@shikijs/rehype");
-_shikijs_rehype = __toESM(_shikijs_rehype);
+_shikijs_rehype = __toESM(_shikijs_rehype, 1);
 let rehype_sanitize = require("rehype-sanitize");
-rehype_sanitize = __toESM(rehype_sanitize);
+rehype_sanitize = __toESM(rehype_sanitize, 1);
 let rehype_stringify = require("rehype-stringify");
-rehype_stringify = __toESM(rehype_stringify);
+rehype_stringify = __toESM(rehype_stringify, 1);
 let unified = require("unified");
 let rehype_raw = require("rehype-raw");
-rehype_raw = __toESM(rehype_raw);
+rehype_raw = __toESM(rehype_raw, 1);
 let remark_directive = require("remark-directive");
-remark_directive = __toESM(remark_directive);
+remark_directive = __toESM(remark_directive, 1);
 let remark_frontmatter = require("remark-frontmatter");
-remark_frontmatter = __toESM(remark_frontmatter);
+remark_frontmatter = __toESM(remark_frontmatter, 1);
 let remark_gfm = require("remark-gfm");
-remark_gfm = __toESM(remark_gfm);
+remark_gfm = __toESM(remark_gfm, 1);
 let remark_parse = require("remark-parse");
-remark_parse = __toESM(remark_parse);
+remark_parse = __toESM(remark_parse, 1);
 let remark_rehype = require("remark-rehype");
-remark_rehype = __toESM(remark_rehype);
+remark_rehype = __toESM(remark_rehype, 1);
 let unist_util_visit = require("unist-util-visit");
 let hast_util_sanitize = require("hast-util-sanitize");
 let reading_time = require("reading-time");
-reading_time = __toESM(reading_time);
+reading_time = __toESM(reading_time, 1);
 let node_crypto = require("node:crypto");
 let feed = require("feed");
 let _resvg_resvg_js = require("@resvg/resvg-js");
@@ -76,7 +68,6 @@ let satori = require("satori");
 satori = __toESM(satori);
 let preact_jsx_runtime = require("preact/jsx-runtime");
 let preact_render_to_string = require("preact-render-to-string");
-
 //#region src/plugins/env/api.ts
 /** Error prefix for all env API failures. */
 const ERROR_PREFIX$13 = "[web]";
@@ -97,26 +88,75 @@ const ERROR_PREFIX$13 = "[web]";
 function createEnvApi(ctx) {
 	const { resolved, publicMap } = ctx.state;
 	return {
+		/**
+		* Reads a resolved variable.
+		*
+		* @param key - Variable name.
+		* @returns The value, or `undefined` if not present.
+		* @example
+		* ```ts
+		* api.get("PUBLIC_API_URL");
+		* ```
+		*/
 		get(key) {
 			return resolved.get(key);
 		},
+		/**
+		* Reads a variable that must exist.
+		*
+		* @param key - Variable name.
+		* @returns The value.
+		* @throws {Error} If the variable is undefined.
+		* @example
+		* ```ts
+		* api.require("DEPLOY_TOKEN");
+		* ```
+		*/
 		require(key) {
 			const value = resolved.get(key);
 			if (value === void 0) throw new Error(`${ERROR_PREFIX$13} env: required variable "${key}" is not defined.`);
 			return value;
 		},
+		/**
+		* Tests presence of a resolved variable.
+		*
+		* @param key - Variable name.
+		* @returns `true` if a value is present.
+		* @example
+		* ```ts
+		* api.has("PUBLIC_API_URL");
+		* ```
+		*/
 		has(key) {
 			return resolved.has(key);
 		},
+		/**
+		* Returns all public variables as a frozen plain object — a fresh copy,
+		* never the raw state map.
+		*
+		* @returns A frozen `Record` of public variable names to values.
+		* @example
+		* ```ts
+		* const payload = { ...api.getPublic() };
+		* ```
+		*/
 		getPublic() {
 			return Object.freeze(Object.fromEntries(publicMap));
 		},
+		/**
+		* Returns the already-frozen map of public variables.
+		*
+		* @returns The frozen public map.
+		* @example
+		* ```ts
+		* [...api.getPublicMap()];
+		* ```
+		*/
 		getPublicMap() {
 			return publicMap;
 		}
 	};
 }
-
 //#endregion
 //#region src/plugins/env/state.ts
 /**
@@ -136,7 +176,6 @@ function createEnvState() {
 		publicMap: /* @__PURE__ */ new Map()
 	};
 }
-
 //#endregion
 //#region src/plugins/env/validate.ts
 /** Error message thrown by every frozen-map mutator. */
@@ -255,7 +294,6 @@ function validateSchema(ctx) {
 	freezeMap(state.resolved);
 	freezeMap(state.publicMap);
 }
-
 //#endregion
 //#region src/plugins/env/providers.ts
 /**
@@ -324,6 +362,15 @@ function parseDotenv(text) {
 function dotenv(path = DEFAULT_DOTENV_PATH) {
 	return {
 		name: `dotenv:${path}`,
+		/**
+		* Reads and parses the dotenv file fresh from disk; `{}` if it is missing.
+		*
+		* @returns The parsed environment record, or `{}` when the file is absent.
+		* @example
+		* ```ts
+		* dotenv(".env.local").load();
+		* ```
+		*/
 		load() {
 			if (!(0, node_fs.existsSync)(path)) return {};
 			return parseDotenv((0, node_fs.readFileSync)(path, "utf8"));
@@ -343,24 +390,20 @@ function dotenv(path = DEFAULT_DOTENV_PATH) {
 function processEnv() {
 	return {
 		name: "process-env",
+		/**
+		* Returns a shallow copy of `process.env` at call time.
+		*
+		* @returns A fresh shallow copy of `process.env`.
+		* @example
+		* ```ts
+		* processEnv().load();
+		* ```
+		*/
 		load() {
 			return { ...process.env };
 		}
 	};
 }
-
-//#endregion
-//#region src/plugins/env/index.ts
-/**
-* @file Core plugin: universal env injection — schema + providers + PUBLIC_ cross-validation at onInit.
-* @see README.md
-*/
-/** Plugin config defaults (R6 typed const). `providers: []` — framework sets `[dotenv(), processEnv()]` via the 4-level cascade. */
-const defaultEnvConfig = {
-	schema: {},
-	providers: [],
-	publicPrefix: "PUBLIC_"
-};
 /**
 * Core plugin that resolves, validates, and freezes the environment at `onInit`,
 * exposing a read-only accessor at `ctx.env`. No `onStart`/`onStop` — holds no resource.
@@ -371,12 +414,15 @@ const defaultEnvConfig = {
 * ```
 */
 const envPlugin = (0, _moku_labs_core.createCorePlugin)("env", {
-	config: defaultEnvConfig,
+	config: {
+		schema: {},
+		providers: [],
+		publicPrefix: "PUBLIC_"
+	},
 	createState: createEnvState,
 	api: createEnvApi,
 	onInit: validateSchema
 });
-
 //#endregion
 //#region src/plugins/log/expect.ts
 /**
@@ -487,10 +533,33 @@ function describePartial(partial) {
 */
 function createExpectChain(entries) {
 	const chain = {
+		/**
+		* Assert at least one entry has `event`, optionally matching `partial`.
+		*
+		* @param event - Event name to find.
+		* @param partial - Optional partial data shape (subset-matched).
+		* @returns The same chain for chaining.
+		* @throws {LogExpectAssertionError} When no matching entry exists.
+		* @example
+		* ```ts
+		* chain.toHaveEvent("build:phase", { status: "start" });
+		* ```
+		*/
 		toHaveEvent(event, partial) {
 			if (!entries.some((entry) => entryMatches(entry, event, partial))) throw new LogExpectAssertionError(`Expected trace to contain event "${event}"${describePartial(partial)}, but none was found.`);
 			return chain;
 		},
+		/**
+		* Assert all of `events` appear in the trace in the given relative order.
+		*
+		* @param events - Ordered list of event names (gaps allowed).
+		* @returns The same chain for chaining.
+		* @throws {LogExpectAssertionError} When the ordering cannot be satisfied.
+		* @example
+		* ```ts
+		* chain.toHaveEventInOrder(["build:phase", "build:complete"]);
+		* ```
+		*/
 		toHaveEventInOrder(events) {
 			let cursor = 0;
 			for (const [position, event] of events.entries()) {
@@ -504,6 +573,18 @@ function createExpectChain(entries) {
 			}
 			return chain;
 		},
+		/**
+		* Assert NO entry has `event` (optionally narrowed by `partial`).
+		*
+		* @param event - Event name that must be absent.
+		* @param partial - Optional partial data shape; only matching entries violate.
+		* @returns The same chain for chaining.
+		* @throws {LogExpectAssertionError} When a matching entry exists.
+		* @example
+		* ```ts
+		* chain.toNotHaveEvent("deploy:failed");
+		* ```
+		*/
 		toNotHaveEvent(event, partial) {
 			const offending = entries.findIndex((entry) => entryMatches(entry, event, partial));
 			if (offending !== -1) throw new LogExpectAssertionError(`Expected trace to NOT contain event "${event}"${describePartial(partial)}, but found one at index ${offending}.`);
@@ -512,7 +593,6 @@ function createExpectChain(entries) {
 	};
 	return chain;
 }
-
 //#endregion
 //#region src/plugins/log/api.ts
 /**
@@ -581,33 +661,110 @@ function mergeError(data, error) {
 function createLogApi(ctx) {
 	const { state } = ctx;
 	return {
+		/**
+		* Append an `info` entry and fan it out to every sink.
+		*
+		* @param event - Event identifier (convention: `domain:action`).
+		* @param data - Optional structured payload.
+		* @example
+		* ```ts
+		* log.info("content:ready", { count: 12 });
+		* ```
+		*/
 		info(event, data) {
 			append(state, "info", event, data);
 		},
+		/**
+		* Append a `debug` entry and fan it out to every sink.
+		*
+		* @param event - Event identifier (convention: `domain:action`).
+		* @param data - Optional structured payload.
+		* @example
+		* ```ts
+		* log.debug("router:match", { path: "/blog/" });
+		* ```
+		*/
 		debug(event, data) {
 			append(state, "debug", event, data);
 		},
+		/**
+		* Append a `warn` entry and fan it out to every sink.
+		*
+		* @param event - Event identifier (convention: `domain:action`).
+		* @param data - Optional structured payload.
+		* @example
+		* ```ts
+		* log.warn("build:skip", { reason: "no sitemap" });
+		* ```
+		*/
 		warn(event, data) {
 			append(state, "warn", event, data);
 		},
+		/**
+		* Append an `error` entry. When `error` is provided, its `message`/`stack`
+		* are merged into `data` under an `error` key (existing keys preserved);
+		* otherwise `data` is recorded as-is.
+		*
+		* @param event - Event identifier (convention: `domain:action`).
+		* @param data - Optional structured payload.
+		* @param error - Optional originating Error to merge into `data`.
+		* @example
+		* ```ts
+		* log.error("deploy:failed", { target: "cf" }, err);
+		* ```
+		*/
 		error(event, data, error) {
 			append(state, "error", event, error === void 0 ? data : mergeError(data, error));
 		},
+		/**
+		* Return a frozen snapshot (fresh copy) of the entries recorded so far.
+		*
+		* @returns A readonly, frozen copy of the recorded entries.
+		* @example
+		* ```ts
+		* const entries = log.trace();
+		* ```
+		*/
 		trace() {
 			return Object.freeze([...state.entries]);
 		},
+		/**
+		* Return a fluent assertion chain bound to the live entries array.
+		*
+		* @returns A fresh {@link ExpectChain} reading `state.entries` live.
+		* @example
+		* ```ts
+		* log.expect().toHaveEvent("build:complete");
+		* ```
+		*/
 		expect() {
 			return createExpectChain(state.entries);
 		},
+		/**
+		* Register an additional output sink at runtime.
+		*
+		* @param sink - The sink to add to the fan-out list.
+		* @example
+		* ```ts
+		* log.addSink({ write: (e) => stream.write(JSON.stringify(e)) });
+		* ```
+		*/
 		addSink(sink) {
 			state.sinks.push(sink);
 		},
+		/**
+		* Clear all recorded entries while keeping registered sinks.
+		*
+		* @example
+		* ```ts
+		* log.reset();
+		* ```
+		*/
 		reset() {
 			state.entries.length = 0;
 		}
 	};
 }
-
 //#endregion
 //#region src/plugins/log/sinks.ts
 /**
@@ -622,7 +779,17 @@ function createLogApi(ctx) {
 * ```
 */
 function consoleSink() {
-	return { write(entry) {
+	return { 
+	/**
+	* Route a single entry to the console channel matching its level.
+	*
+	* @param entry - The entry to emit.
+	* @example
+	* ```ts
+	* sink.write({ level: "warn", event: "build:skip", ts: Date.now() });
+	* ```
+	*/
+write(entry) {
 		if (entry.level === "error") console.error(entry);
 		else if (entry.level === "warn") console.warn(entry);
 		else console.log(entry);
@@ -643,7 +810,6 @@ function consoleSink() {
 function installDefaultSinks(ctx) {
 	if (ctx.config.mode === "dev" || ctx.config.mode === "production") ctx.state.sinks.push(consoleSink());
 }
-
 //#endregion
 //#region src/plugins/log/state.ts
 /**
@@ -664,15 +830,6 @@ function createLogState(_ctx) {
 		sinks: []
 	};
 }
-
-//#endregion
-//#region src/plugins/log/index.ts
-/**
-* @file log — Core Plugin (Standard tier): in-memory trace + expect() DSL.
-* @see README.md
-*/
-/** Default config; overridden via the 4-level pluginConfigs.log merge. */
-const defaultLogConfig = { mode: "production" };
 /**
 * Core logging plugin — always-on in-memory trace + `expect()` event-trace DSL.
 * API injected as `ctx.log` on every regular plugin and surfaced as `app.log`.
@@ -681,21 +838,13 @@ const defaultLogConfig = { mode: "production" };
 * @see README.md
 */
 const logPlugin = (0, _moku_labs_core.createCorePlugin)("log", {
-	config: defaultLogConfig,
+	config: { mode: "production" },
 	createState: createLogState,
 	api: createLogApi,
 	onInit: installDefaultSinks
 });
-
-//#endregion
-//#region src/config.ts
-/**
-* @file Framework configuration — Config + Events types, core plugin registration.
-* @see README.md
-*/
-const defaultConfig$6 = { mode: "production" };
 const coreConfig = (0, _moku_labs_core.createCoreConfig)("web", {
-	config: defaultConfig$6,
+	config: { mode: "production" },
 	plugins: [logPlugin, envPlugin],
 	pluginConfigs: {
 		log: { mode: "production" },
@@ -703,7 +852,6 @@ const coreConfig = (0, _moku_labs_core.createCoreConfig)("web", {
 	}
 });
 const { createPlugin: createPlugin$1, createCore } = coreConfig;
-
 //#endregion
 //#region src/plugins/i18n/api.ts
 /** Error prefix for all i18n lifecycle failures. */
@@ -743,21 +891,83 @@ function validateI18nConfig(ctx) {
 function createI18nApi(ctx) {
 	const { config } = ctx;
 	return {
+		/**
+		* Returns the configured supported locales in declared order.
+		*
+		* @returns The configured `locales` list (priority/display order).
+		* @example
+		* ```ts
+		* api.locales(); // ["en", "uk"]
+		* ```
+		*/
 		locales() {
 			return config.locales;
 		},
+		/**
+		* Returns the fallback locale used when a requested locale is absent.
+		*
+		* @returns The configured `defaultLocale`.
+		* @example
+		* ```ts
+		* api.defaultLocale(); // "en"
+		* ```
+		*/
 		defaultLocale() {
 			return config.defaultLocale;
 		},
+		/**
+		* Membership guard: whether `x` is one of the supported locales
+		* (case-sensitive).
+		*
+		* @param x - Candidate locale code.
+		* @returns `true` if `x ∈ locales`, else `false`.
+		* @example
+		* ```ts
+		* api.isLocale("uk"); // true
+		* ```
+		*/
 		isLocale(x) {
 			return config.locales.includes(x);
 		},
+		/**
+		* Human-readable display name for a locale.
+		*
+		* @param locale - Locale code to look up.
+		* @returns The display name, or `undefined` if unmapped.
+		* @example
+		* ```ts
+		* api.localeName("uk"); // "Українська"
+		* ```
+		*/
 		localeName(locale) {
 			return config.localeNames?.[locale];
 		},
+		/**
+		* Open Graph `og:locale` value for a locale.
+		*
+		* @param locale - Locale code to look up.
+		* @returns The `og:locale` value (e.g. `"en_US"`), or `undefined` if unmapped.
+		* @example
+		* ```ts
+		* api.ogLocale("en"); // "en_US"
+		* ```
+		*/
 		ogLocale(locale) {
 			return config.ogLocaleMap?.[locale];
 		},
+		/**
+		* Translate `key` for `locale` with a deterministic fallback chain
+		* (requested locale → default locale → the key itself). The default-locale
+		* lookup is skipped when `locale === defaultLocale`.
+		*
+		* @param locale - Requested locale code.
+		* @param key - Translation key (e.g. `"nav.home"`).
+		* @returns The translated value, the default-locale value, or `key`.
+		* @example
+		* ```ts
+		* api.t("uk", "nav.home"); // "Головна"
+		* ```
+		*/
 		t(locale, key) {
 			const exact = config.translations?.[locale]?.[key];
 			if (exact !== void 0) return exact;
@@ -769,34 +979,17 @@ function createI18nApi(ctx) {
 		}
 	};
 }
-
-//#endregion
-//#region src/plugins/i18n/index.ts
-/**
-* i18n — Micro tier. Multi-file layout (index wiring + api.ts + types.ts) so
-* index.ts stays within the ≤30-line wiring-only hook; logic lives in api.ts.
-*
-* Locale registry + flat translation helper with default-locale fallback.
-* Pure config-as-data: no state, no events, no lifecycle resources.
-* Consumed read-only by content/router/head/build via `ctx.require(i18nPlugin)`.
-*
-* @file i18n plugin wiring harness.
-* @see README.md
-*/
-/** Typed default config (R6: no inline `as`). Optional maps default to `{}` so every lookup is total. */
-const defaultConfig$5 = {
-	locales: ["en"],
-	defaultLocale: "en",
-	localeNames: {},
-	ogLocaleMap: {},
-	translations: {}
-};
 const i18nPlugin = createPlugin$1("i18n", {
-	config: defaultConfig$5,
+	config: {
+		locales: ["en"],
+		defaultLocale: "en",
+		localeNames: {},
+		ogLocaleMap: {},
+		translations: {}
+	},
 	onInit: validateI18nConfig,
 	api: createI18nApi
 });
-
 //#endregion
 //#region src/plugins/content/pipeline/frontmatter.ts
 /**
@@ -842,7 +1035,6 @@ function parseFrontmatter(raw, config) {
 		body: parsed.content
 	};
 }
-
 //#endregion
 //#region src/plugins/content/pipeline/plugins.ts
 /**
@@ -999,7 +1191,6 @@ function defaultRehypePlugins() {
 		sectionDividerPlugin
 	];
 }
-
 //#endregion
 //#region src/plugins/content/pipeline/sanitize.ts
 /**
@@ -1086,7 +1277,6 @@ function buildSanitizeSchema() {
 		}
 	};
 }
-
 //#endregion
 //#region src/plugins/content/pipeline/markdown.ts
 /**
@@ -1144,7 +1334,6 @@ function applyPluggable(processor, plugin) {
 	}
 	processor.use(plugin);
 }
-
 //#endregion
 //#region src/plugins/content/pipeline/reading-time.ts
 /**
@@ -1170,7 +1359,6 @@ function calculateReadingTime(text) {
 		wordCount: stats.words
 	};
 }
-
 //#endregion
 //#region src/plugins/content/api.ts
 /**
@@ -1278,7 +1466,7 @@ async function discoverSlugs(dir) {
 * ```
 */
 async function readArticle(ctx, slug, fileLocale, outLocale, isFallback) {
-	const filePath = node_path.default.join(ctx.config.contentDir, slug, `${fileLocale}.md`);
+	const filePath = node_path$1.default.join(ctx.config.contentDir, slug, `${fileLocale}.md`);
 	let raw;
 	try {
 		raw = await (0, node_fs_promises.readFile)(filePath, "utf8");
@@ -1382,6 +1570,18 @@ function toCard(article) {
 */
 function createContentApi(ctx) {
 	return {
+		/**
+		* Load every article across every active locale, returning a locale-keyed
+		* map of date-descending Article arrays. Lazily builds the processor and
+		* discovers slugs, applies locale fallback, excludes drafts in production,
+		* assigns `contentId` after sorting, then emits `content:ready`.
+		*
+		* @returns A locale-keyed map of date-descending articles.
+		* @example
+		* ```ts
+		* const byLocale = await api.loadAll();
+		* ```
+		*/
 		async loadAll() {
 			const slugs = ctx.state.slugs ?? await discoverSlugs(ctx.config.contentDir);
 			ctx.state.slugs = slugs;
@@ -1409,6 +1609,19 @@ function createContentApi(ctx) {
 			});
 			return result;
 		},
+		/**
+		* Resolve and render a single article for one locale with locale fallback.
+		* Throws a `[web] content` error when neither the requested nor the
+		* default-locale file exists.
+		*
+		* @param slug - Article directory name.
+		* @param locale - Requested locale code.
+		* @returns The resolved Article.
+		* @example
+		* ```ts
+		* const article = await api.load("intro", "uk");
+		* ```
+		*/
 		async load(slug, locale) {
 			const article = await resolveArticle(ctx, slug, locale);
 			if (article === null) throw new Error(`[web] content article "${slug}" not found for locale "${locale}".\n  Looked for ${slug}/${locale}.md and the default-locale fallback.`);
@@ -1417,10 +1630,33 @@ function createContentApi(ctx) {
 			ctx.state.articles.set(locale, cache);
 			return article;
 		},
+		/**
+		* Render a raw Markdown string to HTML through the full pipeline (sanitize
+		* last when `trustedContent` is false). Lazily builds the processor.
+		*
+		* @param md - Raw Markdown source.
+		* @returns The rendered HTML string.
+		* @example
+		* ```ts
+		* const html = await api.renderMarkdown("# Hi");
+		* ```
+		*/
 		async renderMarkdown(md) {
 			const processor = ensureProcessor(ctx.state, ctx.config);
 			return String(await processor.process(md));
 		},
+		/**
+		* Mark file paths stale for incremental dev rebuilds. Each non-blank path is
+		* added to `dirtyPaths` and its derived slug cache entry is dropped so the
+		* next `loadAll()` re-reads only those files. Empty/whitespace paths are
+		* ignored. Emits `content:invalidated` with the accepted paths.
+		*
+		* @param paths - File paths to invalidate.
+		* @example
+		* ```ts
+		* api.invalidate(["src/content/intro/en.md"]);
+		* ```
+		*/
 		invalidate(paths) {
 			const accepted = [];
 			for (const path of paths) {
@@ -1433,12 +1669,22 @@ function createContentApi(ctx) {
 			ctx.state.slugs = null;
 			ctx.emit("content:invalidated", { paths: accepted });
 		},
+		/**
+		* Project a full Article to a lightweight ArticleCard for list/grid
+		* rendering without shipping rendered HTML.
+		*
+		* @param article - The source article.
+		* @returns The card projection.
+		* @example
+		* ```ts
+		* const card = api.articleToCard(article);
+		* ```
+		*/
 		articleToCard(article) {
 			return toCard(article);
 		}
 	};
 }
-
 //#endregion
 //#region src/plugins/content/config.ts
 /**
@@ -1459,7 +1705,6 @@ const defaultContentConfig = {
 	extraRehypePlugins: [],
 	shikiTheme: "github-dark"
 };
-
 //#endregion
 //#region src/plugins/content/events.ts
 /**
@@ -1478,7 +1723,6 @@ const contentEvents = (register) => ({
 	"content:ready": register("All articles loaded across locales"),
 	"content:invalidated": register("Article paths marked stale for dev rebuild")
 });
-
 //#endregion
 //#region src/plugins/content/state.ts
 /**
@@ -1502,7 +1746,6 @@ function createContentState(_ctx) {
 		dirtyPaths: /* @__PURE__ */ new Set()
 	};
 }
-
 //#endregion
 //#region src/plugins/content/validate.ts
 /**
@@ -1521,7 +1764,6 @@ function validateContentConfig(config) {
 	if (typeof config.contentDir !== "string" || config.contentDir.trim() === "") throw new Error("[web] content.contentDir is required.\n  Set pluginConfigs.content.contentDir to your content directory.");
 	if (typeof config.trustedContent !== "boolean") throw new TypeError("[web] content.trustedContent must be a boolean.");
 }
-
 //#endregion
 //#region src/plugins/content/index.ts
 /**
@@ -1540,7 +1782,6 @@ const contentPlugin = createPlugin$1("content", {
 	onInit: (ctx) => validateContentConfig(ctx.config),
 	api: contentApi
 });
-
 //#endregion
 //#region src/plugins/site/api.ts
 /** Error prefix for all site lifecycle/validation failures. */
@@ -1632,50 +1873,80 @@ function validateSiteConfig(ctx) {
 function createSiteApi(ctx) {
 	const { config } = ctx;
 	return {
+		/**
+		* Returns the configured site name.
+		*
+		* @returns The human-readable site name from `config.name`.
+		* @example
+		* ```ts
+		* api.name(); // "My Blog"
+		* ```
+		*/
 		name() {
 			return config.name;
 		},
+		/**
+		* Returns the configured absolute base URL of the site.
+		*
+		* @returns The base URL from `config.url`.
+		* @example
+		* ```ts
+		* api.url(); // "https://blog.dev"
+		* ```
+		*/
 		url() {
 			return config.url;
 		},
+		/**
+		* Returns the configured site author/byline.
+		*
+		* @returns The author from `config.author`.
+		* @example
+		* ```ts
+		* api.author(); // "Alex"
+		* ```
+		*/
 		author() {
 			return config.author;
 		},
+		/**
+		* Returns the configured site description.
+		*
+		* @returns The description from `config.description`.
+		* @example
+		* ```ts
+		* api.description(); // "A personal blog about web frameworks."
+		* ```
+		*/
 		description() {
 			return config.description;
 		},
+		/**
+		* Joins a path against the configured base `url` to produce an absolute
+		* canonical URL. An empty path (or "/") returns the base URL unchanged.
+		*
+		* @param path - Relative path for the page, e.g. "/about/".
+		* @returns The absolute canonical URL.
+		* @example
+		* ```ts
+		* api.canonical("/about/"); // "https://blog.dev/about/"
+		* ```
+		*/
 		canonical(path) {
 			return joinCanonical(config.url, path);
 		}
 	};
 }
-
-//#endregion
-//#region src/plugins/site/index.ts
-/**
-* site — Micro tier. Multi-file layout (index wiring + api.ts + types.ts) so
-* index.ts stays within the ≤30-line wiring-only hook; logic lives in api.ts.
-*
-* Holds global, frozen site metadata (name, url, author, description) and
-* constructs canonical URLs. Consumed by router/head/build via
-* `ctx.require(sitePlugin)`. No events, no dependencies, no state.
-*
-* @file site plugin wiring harness.
-* @see README.md
-*/
-/** Typed default config (R6: no inline `as`). Consumers override via `pluginConfigs.site`. */
-const defaultConfig$4 = {
-	name: "",
-	url: "",
-	author: "",
-	description: ""
-};
 const sitePlugin = createPlugin$1("site", {
-	config: defaultConfig$4,
+	config: {
+		name: "",
+		url: "",
+		author: "",
+		description: ""
+	},
 	onInit: validateSiteConfig,
 	api: createSiteApi
 });
-
 //#endregion
 //#region src/plugins/router/builders/match.ts
 /**
@@ -1745,7 +2016,6 @@ function matchRoute(compiled, pathname) {
 	}
 	return null;
 }
-
 //#endregion
 //#region src/plugins/router/api.ts
 /**
@@ -1808,23 +2078,63 @@ function toTypedRoute(entry) {
 function createApi$4(ctx) {
 	const { state } = ctx;
 	return {
+		/**
+		* Match a pathname against the compiled route table (specificity-sorted).
+		*
+		* @param pathname - URL pathname, e.g. `/en/hello/`.
+		* @returns `{ params, route }` for the most specific match, or `null`.
+		* @example
+		* ```ts
+		* api.match("/en/hello/");
+		* ```
+		*/
 		match(pathname) {
 			return matchRoute(readTable(state).compiled, pathname);
 		},
+		/**
+		* Build a URL for a named route from params.
+		*
+		* @param routeName - Route name key from the route map.
+		* @param params - Param values to substitute into the pattern.
+		* @returns The resolved URL string (e.g. `/en/hello/`).
+		* @throws {Error} If `routeName` is unknown.
+		* @example
+		* ```ts
+		* api.toUrl("article", { lang: "en", slug: "hello" });
+		* ```
+		*/
 		toUrl(routeName, params) {
 			const entry = readTable(state).byName.get(routeName);
 			if (!entry) throw new Error(`${ERROR_PREFIX$9}: unknown route name "${routeName}".`);
 			return entry.toUrl(params);
 		},
+		/**
+		* All resolved routes as typed URL utilities, in specificity order.
+		*
+		* @returns A fresh read-only array of resolved typed routes.
+		* @example
+		* ```ts
+		* for (const r of api.entries()) r.toUrl({ slug: "x" });
+		* ```
+		*/
 		entries() {
 			return readTable(state).compiled.map((entry) => toTypedRoute(entry));
 		},
+		/**
+		* The typed route set for build-time consumption (declaration order). An API
+		* return, NOT a config readback — preserves per-route types despite erasure.
+		*
+		* @returns A fresh read-only array of the typed route definitions.
+		* @example
+		* ```ts
+		* for (const def of api.manifest()) def._handlers.load?.({}, "en");
+		* ```
+		*/
 		manifest() {
 			return [...readTable(state).byName.values()].map((entry) => entry.definition);
 		}
 	};
 }
-
 //#endregion
 //#region src/plugins/router/builders/compile.ts
 /** Shared `[web]` error prefix for router validation failures. */
@@ -1986,9 +2296,31 @@ function compileRoute(name, definition, input) {
 		dynamicSegmentCount: countDynamicSegments(pattern),
 		matchers,
 		matchFn: createMatchFunction(matchers, input.defaultLocale),
+		/**
+		* Build a URL for this route from params.
+		*
+		* @param params - Param values to substitute.
+		* @returns The resolved relative URL.
+		* @example
+		* ```ts
+		* entry.toUrl({ slug: "x" });
+		* ```
+		*/
 		toUrl(params) {
 			return buildUrl(pattern, params, input.baseUrl);
 		},
+		/**
+		* Build the output file path for this route from params. Honors a custom
+		* `.toFile()` override (captured in `_handlers.toFile`) when present, falling
+		* back to the pattern-derived `…/index.html` path otherwise.
+		*
+		* @param params - Param values to substitute.
+		* @returns The output file path.
+		* @example
+		* ```ts
+		* entry.toFile({ slug: "x" });
+		* ```
+		*/
 		toFile(params) {
 			return definition._handlers.toFile?.(params) ?? buildFilePath(pattern, params);
 		},
@@ -2049,7 +2381,6 @@ function buildRouterTable(config, baseUrl, locales, defaultLocale) {
 		defaultLocale
 	});
 }
-
 //#endregion
 //#region src/plugins/router/builders/route-builder.ts
 /**
@@ -2095,28 +2426,108 @@ function route(pattern) {
 		pattern: carrier.pattern,
 		_meta: carrier._meta,
 		_handlers: carrier._handlers,
+		/**
+		* Attach a data loader; widens the data generic for downstream handlers.
+		*
+		* @param loader - The loader producing this route's data.
+		* @returns The same builder, with the data generic widened.
+		* @example
+		* ```ts
+		* route("/{slug}/").load(({ slug }) => ({ slug }));
+		* ```
+		*/
 		load(loader) {
 			return set("load", loader);
 		},
+		/**
+		* Attach a layout wrapper component.
+		*
+		* @param component - The layout component.
+		* @returns The same builder for chaining.
+		* @example
+		* ```ts
+		* route("/").layout((children) => children);
+		* ```
+		*/
 		layout(component) {
 			return set("layout", component);
 		},
+		/**
+		* Attach the page render handler.
+		*
+		* @param handler - The render handler.
+		* @returns The same builder for chaining.
+		* @example
+		* ```ts
+		* route("/").render(() => null);
+		* ```
+		*/
 		render(handler) {
 			return set("render", handler);
 		},
+		/**
+		* Attach the head/SEO handler.
+		*
+		* @param handler - The head handler.
+		* @returns The same builder for chaining.
+		* @example
+		* ```ts
+		* route("/").head(() => ({ title: "Home" }));
+		* ```
+		*/
 		head(handler) {
 			return set("head", handler);
 		},
+		/**
+		* Attach a static-generation param producer.
+		*
+		* @param handler - The param producer.
+		* @returns The same builder for chaining.
+		* @example
+		* ```ts
+		* route("/{slug}/").generate(() => [{ slug: "x" }]);
+		* ```
+		*/
 		generate(handler) {
 			return set("generate", handler);
 		},
+		/**
+		* Merge an arbitrary metadata bag into the route's `_meta`.
+		*
+		* @param meta - Metadata to merge.
+		* @returns The same builder for chaining.
+		* @example
+		* ```ts
+		* route("/").meta({ activeTab: "home" });
+		* ```
+		*/
 		meta(meta) {
 			Object.assign(carrier._meta, meta);
 			return builder;
 		},
+		/**
+		* Attach a JSON serializer for the route's data.
+		*
+		* @param handler - The JSON serializer.
+		* @returns The same builder for chaining.
+		* @example
+		* ```ts
+		* route("/api/").toJson(() => ({ ok: true }));
+		* ```
+		*/
 		toJson(handler) {
 			return set("toJson", handler);
 		},
+		/**
+		* Override the output file-path producer.
+		*
+		* @param handler - The file-path producer.
+		* @returns The same builder for chaining.
+		* @example
+		* ```ts
+		* route("/feed/").toFile(() => "feed.xml");
+		* ```
+		*/
 		toFile(handler) {
 			return set("toFile", handler);
 		}
@@ -2137,7 +2548,6 @@ function route(pattern) {
 function defineRoutes(routes) {
 	return routes;
 }
-
 //#endregion
 //#region src/plugins/router/state.ts
 /**
@@ -2156,25 +2566,16 @@ function defineRoutes(routes) {
 function createState$4(_ctx) {
 	return { table: null };
 }
-
-//#endregion
-//#region src/plugins/router/index.ts
-/**
-* @file router — Complex plugin wiring (logic in builders/, api.ts, state.ts).
-* @see README.md
-*/
-/** Default router config: empty route map (validated in onInit), hybrid mode. */
-const defaultConfig$3 = {
-	routes: {},
-	mode: "hybrid"
-};
 const routerPlugin = createPlugin$1("router", {
 	depends: [sitePlugin, i18nPlugin],
 	helpers: {
 		route,
 		defineRoutes
 	},
-	config: defaultConfig$3,
+	config: {
+		routes: {},
+		mode: "hybrid"
+	},
 	createState: createState$4,
 	api: createApi$4,
 	onInit(ctx) {
@@ -2183,7 +2584,6 @@ const routerPlugin = createPlugin$1("router", {
 		ctx.state.table = buildRouterTable(ctx.config, baseUrl, i18n.locales(), i18n.defaultLocale());
 	}
 });
-
 //#endregion
 //#region src/plugins/head/primitives.ts
 /** OG/Twitter article-meta property prefixes (factored to satisfy no-duplicate-string). */
@@ -2347,7 +2747,6 @@ function buildArticleHead(articleMeta, canonicalUrl) {
 	elements.push(jsonLd(ld));
 	return elements;
 }
-
 //#endregion
 //#region src/plugins/head/compose.ts
 /**
@@ -2508,7 +2907,6 @@ function serializeElement(element) {
 function serializeHead(elements) {
 	return elements.map((element) => serializeElement(element)).join("");
 }
-
 //#endregion
 //#region src/plugins/head/api.ts
 /**
@@ -2550,7 +2948,19 @@ function readDefaults(state) {
 * ```
 */
 function createApi$3(ctx) {
-	return { render(route, data) {
+	return { 
+	/**
+	* Compose the final `<head>` inner HTML for a route (pulled by `build`).
+	*
+	* @param route - The resolved route descriptor (incl. its `.head()` HeadConfig).
+	* @param data - The page data object passed to the route's loader/render.
+	* @returns The serialized inner HTML of `<head>`.
+	* @example
+	* ```ts
+	* api.render(route, { title: "Post" });
+	* ```
+	*/
+render(route, data) {
 		return serializeHead(composeHead({
 			route,
 			data,
@@ -2561,7 +2971,6 @@ function createApi$3(ctx) {
 		}));
 	} };
 }
-
 //#endregion
 //#region src/plugins/head/config.ts
 /** Error prefix for all head config-validation failures. */
@@ -2616,7 +3025,6 @@ function normalizeHeadConfig(config) {
 	if (config.twitterHandle !== void 0) defaults.twitterHandle = config.twitterHandle;
 	return Object.freeze(defaults);
 }
-
 //#endregion
 //#region src/plugins/head/helpers.ts
 /**
@@ -2645,7 +3053,6 @@ const headHelpers = {
 	feedLink,
 	buildArticleHead
 };
-
 //#endregion
 //#region src/plugins/head/state.ts
 /**
@@ -2666,7 +3073,6 @@ const headHelpers = {
 function createState$3(_ctx) {
 	return { defaults: null };
 }
-
 //#endregion
 //#region src/plugins/head/index.ts
 /**
@@ -2687,7 +3093,6 @@ const headPlugin = createPlugin$1("head", {
 		ctx.state.defaults = normalizeHeadConfig(ctx.config);
 	}
 });
-
 //#endregion
 //#region src/plugins/build/phases/bundle.ts
 /**
@@ -2761,7 +3166,7 @@ async function runOne(ctx, runner, kind, entrypoints, outdir, minify) {
 	});
 	if (!result.success) throw new Error(`[web] build.bundle ${kind} build failed`);
 	const hashed = {};
-	for (const output of result.outputs) hashed[node_path.default.basename(output.path)] = output.path;
+	for (const output of result.outputs) hashed[node_path$1.default.basename(output.path)] = output.path;
 	ctx.state.buildCache.set(kind, hashed);
 	ctx.log.debug("build:bundle", {
 		kind,
@@ -2786,10 +3191,9 @@ async function bundle(ctx, options = {}) {
 	const { minify, outDir } = ctx.config;
 	const cssEntrypoints = options.cssEntrypoints ?? resolveEntrypoints(CSS_ENTRY_CANDIDATES);
 	const jsEntrypoints = options.jsEntrypoints ?? resolveEntrypoints(JS_ENTRY_CANDIDATES);
-	await runOne(ctx, runner, "css", cssEntrypoints, node_path.default.join(outDir, "assets"), minify);
-	await runOne(ctx, runner, "js", jsEntrypoints, node_path.default.join(outDir, "assets"), minify);
+	await runOne(ctx, runner, "css", cssEntrypoints, node_path$1.default.join(outDir, "assets"), minify);
+	await runOne(ctx, runner, "js", jsEntrypoints, node_path$1.default.join(outDir, "assets"), minify);
 }
-
 //#endregion
 //#region src/plugins/build/phases/content.ts
 /**
@@ -2832,7 +3236,6 @@ function readCachedContent(ctx) {
 	const cached = ctx.state.buildCache.get(CONTENT_CACHE_KEY);
 	return cached instanceof Map ? cached : /* @__PURE__ */ new Map();
 }
-
 //#endregion
 //#region src/plugins/build/phases/feeds.ts
 /**
@@ -2907,14 +3310,13 @@ async function generateFeeds(ctx) {
 	};
 	await (0, node_fs_promises.mkdir)(ctx.config.outDir, { recursive: true });
 	await Promise.all([
-		(0, node_fs_promises.writeFile)(node_path.default.join(ctx.config.outDir, "feed.xml"), result.rss, "utf8"),
-		(0, node_fs_promises.writeFile)(node_path.default.join(ctx.config.outDir, "atom.xml"), result.atom, "utf8"),
-		(0, node_fs_promises.writeFile)(node_path.default.join(ctx.config.outDir, "feed.json"), result.json, "utf8")
+		(0, node_fs_promises.writeFile)(node_path$1.default.join(ctx.config.outDir, "feed.xml"), result.rss, "utf8"),
+		(0, node_fs_promises.writeFile)(node_path$1.default.join(ctx.config.outDir, "atom.xml"), result.atom, "utf8"),
+		(0, node_fs_promises.writeFile)(node_path$1.default.join(ctx.config.outDir, "feed.json"), result.json, "utf8")
 	]);
 	ctx.log.debug("build:feeds", { items: guids.length });
 	return result;
 }
-
 //#endregion
 //#region src/plugins/build/phases/images.ts
 /**
@@ -2942,7 +3344,7 @@ async function processImages(ctx, options = {}) {
 		return 0;
 	}
 	const sourceDirectories = options.sourceDirectories ?? IMAGE_SOURCE_DIRECTORIES;
-	const target = node_path.default.join(ctx.config.outDir, "assets");
+	const target = node_path$1.default.join(ctx.config.outDir, "assets");
 	let copied = 0;
 	for (const directory of sourceDirectories) {
 		if (!(0, node_fs.existsSync)(directory)) continue;
@@ -2954,7 +3356,6 @@ async function processImages(ctx, options = {}) {
 	ctx.log.debug("build:images", { copied });
 	return copied;
 }
-
 //#endregion
 //#region src/plugins/build/phases/og-images.tsx
 /**
@@ -2968,8 +3369,6 @@ const DEFAULT_SIZE = {
 	width: 1200,
 	height: 630
 };
-/** The fixed concurrency bound for the OG render pool. */
-const OG_CONCURRENCY = 4;
 /** Recognized font file extensions. */
 const FONT_EXTENSIONS$1 = [
 	".ttf",
@@ -3090,7 +3489,7 @@ async function generateOgImages(ctx, options = {}) {
 	const articles = selectArticles(readCachedContent(ctx));
 	const cache = ctx.state.ogImageHashCache;
 	await loadDiskCache(ctx.config.outDir, cache);
-	const limit = pLimit(OG_CONCURRENCY);
+	const limit = pLimit(4);
 	let active = 0;
 	let peakConcurrency = 0;
 	let rendered = 0;
@@ -3163,7 +3562,6 @@ async function persistDiskCache(outDir, cache) {
 	await (0, node_fs_promises.mkdir)(dir, { recursive: true });
 	await (0, node_fs_promises.writeFile)(node_path.default.join(dir, "og-images.json"), JSON.stringify(Object.fromEntries(cache)), "utf8");
 }
-
 //#endregion
 //#region src/plugins/build/phases/pages.tsx
 /**
@@ -3331,7 +3729,6 @@ async function renderPages(ctx) {
 		rootHtml: root?.html ?? null
 	};
 }
-
 //#endregion
 //#region src/plugins/build/phases/sitemap.ts
 /**
@@ -3405,7 +3802,7 @@ async function generateSitemap(ctx) {
 	const xml = serializeSitemap(urls);
 	const robots = `User-agent: *\nAllow: /\nSitemap: ${site.canonical("/sitemap.xml")}\n`;
 	await (0, node_fs_promises.mkdir)(ctx.config.outDir, { recursive: true });
-	await Promise.all([(0, node_fs_promises.writeFile)(node_path.default.join(ctx.config.outDir, "sitemap.xml"), xml, "utf8"), (0, node_fs_promises.writeFile)(node_path.default.join(ctx.config.outDir, "robots.txt"), robots, "utf8")]);
+	await Promise.all([(0, node_fs_promises.writeFile)(node_path$1.default.join(ctx.config.outDir, "sitemap.xml"), xml, "utf8"), (0, node_fs_promises.writeFile)(node_path$1.default.join(ctx.config.outDir, "robots.txt"), robots, "utf8")]);
 	ctx.log.debug("build:sitemap", { urls: urls.length });
 	return {
 		urls,
@@ -3413,7 +3810,6 @@ async function generateSitemap(ctx) {
 		robots
 	};
 }
-
 //#endregion
 //#region src/plugins/build/pipeline.ts
 /**
@@ -3534,7 +3930,7 @@ async function runPipeline(ctx, options) {
 	const pages = await withPhase(phaseContext, "pages", () => renderPages(phaseContext));
 	await runOutputs(phaseContext);
 	await withPhase(phaseContext, "root-index", async () => {
-		if (pages.rootHtml !== null) await (0, node_fs_promises.writeFile)(node_path.default.join(outDir, "index.html"), pages.rootHtml, "utf8");
+		if (pages.rootHtml !== null) await (0, node_fs_promises.writeFile)(node_path$1.default.join(outDir, "index.html"), pages.rootHtml, "utf8");
 	});
 	const result = {
 		outDir,
@@ -3544,7 +3940,6 @@ async function runPipeline(ctx, options) {
 	phaseContext.emit("build:complete", result);
 	return result;
 }
-
 //#endregion
 //#region src/plugins/build/api.ts
 /**
@@ -3583,9 +3978,29 @@ const defaultConfig$1 = {
 */
 function createApi$2(ctx) {
 	return {
+		/**
+		* Run the full SSG pipeline and write the site to disk.
+		*
+		* @param options - Optional run overrides.
+		* @param options.outDir - Override the configured output directory for this run.
+		* @returns The build result (outDir, pageCount, durationMs).
+		* @example
+		* ```ts
+		* await api.run({ outDir: "./preview" });
+		* ```
+		*/
 		run(options) {
 			return runPipeline(ctx, options);
 		},
+		/**
+		* List the phases in execution order (introspection / tooling).
+		*
+		* @returns A fresh array of the static ordered phase names.
+		* @example
+		* ```ts
+		* api.phases();
+		* ```
+		*/
 		phases() {
 			return [...PHASE_ORDER];
 		}
@@ -3620,7 +4035,6 @@ function validateConfig$1(config) {
 	if (typeof config.outDir !== "string" || config.outDir.trim().length === 0) throw new Error(`${ERROR_PREFIX$5}.outDir: must be a non-empty string.`);
 	if (config.ogImage) validateFonts(config.ogImage);
 }
-
 //#endregion
 //#region src/plugins/build/events.ts
 /**
@@ -3640,7 +4054,6 @@ function createEvents(register) {
 		"build:complete": register("Emitted once after a successful build run")
 	};
 }
-
 //#endregion
 //#region src/plugins/build/state.ts
 /**
@@ -3667,7 +4080,6 @@ function createState$2(ctx) {
 		ogImageHashCache: /* @__PURE__ */ new Map()
 	};
 }
-
 //#endregion
 //#region src/plugins/build/index.ts
 /**
@@ -3688,7 +4100,6 @@ const buildPlugin = createPlugin$1("build", {
 	api: createApi$2,
 	onInit: (ctx) => validateConfig$1(ctx.config)
 });
-
 //#endregion
 //#region src/plugins/deploy/wrangler.ts
 /**
@@ -3795,9 +4206,9 @@ function guardBranch(branch) {
 * assertWithinRoot("dist", process.cwd());
 */
 function assertWithinRoot(outDir, root) {
-	const resolved = node_path.default.isAbsolute(outDir) ? node_path.default.resolve(outDir) : node_path.default.resolve(root, outDir);
-	const rootResolved = node_path.default.resolve(root);
-	if (resolved !== rootResolved && !resolved.startsWith(rootResolved + node_path.default.sep)) throw deployError("ERR_DEPLOY_PATH_TRAVERSAL", `${ERROR_PREFIX$4}: outDir ${JSON.stringify(outDir)} resolves outside the project root.\n  Point outDir at a directory inside ${JSON.stringify(rootResolved)}.`);
+	const resolved = node_path$1.default.isAbsolute(outDir) ? node_path$1.default.resolve(outDir) : node_path$1.default.resolve(root, outDir);
+	const rootResolved = node_path$1.default.resolve(root);
+	if (resolved !== rootResolved && !resolved.startsWith(rootResolved + node_path$1.default.sep)) throw deployError("ERR_DEPLOY_PATH_TRAVERSAL", `${ERROR_PREFIX$4}: outDir ${JSON.stringify(outDir)} resolves outside the project root.\n  Point outDir at a directory inside ${JSON.stringify(rootResolved)}.`);
 	return resolved;
 }
 /**
@@ -3866,8 +4277,6 @@ const ERROR_SIGNATURES = [
 		advice: "A network failure occurred. Check connectivity and retry."
 	}
 ];
-/** Number of trailing characters of scrubbed stderr to surface on an unknown failure. */
-const STDERR_TAIL_LENGTH = 500;
 /**
 * Map a non-zero wrangler exit and scrubbed stderr to an actionable error
 * `code` + message. Matching is case-insensitive against the scrubbed stderr;
@@ -3888,7 +4297,7 @@ function classifyWranglerError(exitCode, scrubbedStderr) {
 	};
 	return {
 		code: "ERR_DEPLOY_WRANGLER_FAILED",
-		message: `${ERROR_PREFIX$4}: wrangler failed (exit ${exitCode}).\n  ${scrubbedStderr.trim().slice(-STDERR_TAIL_LENGTH)}`
+		message: `${ERROR_PREFIX$4}: wrangler failed (exit ${exitCode}).\n  ${scrubbedStderr.trim().slice(-500)}`
 	};
 }
 /**
@@ -3947,7 +4356,6 @@ async function runWrangler(input) {
 		exitCode
 	};
 }
-
 //#endregion
 //#region src/plugins/deploy/generators/github-workflow.ts
 /**
@@ -4002,7 +4410,6 @@ jobs:
           command: pages deploy dist --project-name ${input.slug}
 `;
 }
-
 //#endregion
 //#region src/plugins/deploy/generators/wrangler-config.ts
 /**
@@ -4041,12 +4448,11 @@ function generateWranglerConfig(input) {
 */
 async function readWranglerConfig(cwd) {
 	try {
-		return await (0, node_fs_promises.readFile)(node_path.default.join(cwd, "wrangler.jsonc"), "utf8");
+		return await (0, node_fs_promises.readFile)(node_path$1.default.join(cwd, "wrangler.jsonc"), "utf8");
 	} catch {
 		return null;
 	}
 }
-
 //#endregion
 //#region src/plugins/deploy/init.ts
 /**
@@ -4068,7 +4474,7 @@ const WORKFLOW_PATH = ".github/workflows/deploy.yml";
 */
 async function readMaybe(cwd, relativePath) {
 	try {
-		return await (0, node_fs_promises.readFile)(node_path.default.join(cwd, relativePath), "utf8");
+		return await (0, node_fs_promises.readFile)(node_path$1.default.join(cwd, relativePath), "utf8");
 	} catch {
 		return null;
 	}
@@ -4146,11 +4552,10 @@ async function reconcile(input) {
 		result.skipped.push(relativePath);
 		return;
 	}
-	await (0, node_fs_promises.mkdir)(node_path.default.dirname(node_path.default.join(cwd, relativePath)), { recursive: true });
-	await (0, node_fs_promises.writeFile)(node_path.default.join(cwd, relativePath), expected, "utf8");
+	await (0, node_fs_promises.mkdir)(node_path$1.default.dirname(node_path$1.default.join(cwd, relativePath)), { recursive: true });
+	await (0, node_fs_promises.writeFile)(node_path$1.default.join(cwd, relativePath), expected, "utf8");
 	result.written.push(relativePath);
 }
-
 //#endregion
 //#region src/plugins/deploy/preflight.ts
 /**
@@ -4202,7 +4607,7 @@ async function inspectOutdir(dir) {
 		if (current === void 0) break;
 		const entries = await (0, node_fs_promises.readdir)(current, { withFileTypes: true });
 		for (const entry of entries) {
-			const entryPath = node_path.default.join(current, entry.name);
+			const entryPath = node_path$1.default.join(current, entry.name);
 			if (entry.isDirectory()) stack.push(entryPath);
 			else if (entry.isFile()) {
 				result.fileCount += 1;
@@ -4230,13 +4635,13 @@ async function inspectOutdir(dir) {
 * await runPreflight(config, process.cwd());
 */
 async function runPreflight(config, root, env = process.env) {
-	const wranglerPath = node_path.default.join(root, "wrangler.jsonc");
+	const wranglerPath = node_path$1.default.join(root, "wrangler.jsonc");
 	try {
 		await (0, node_fs_promises.stat)(wranglerPath);
 	} catch {
 		throw deployError("ERR_DEPLOY_NO_WRANGLER_CONFIG", `${ERROR_PREFIX$3}: wrangler.jsonc not found.\n  Run \`app.deploy.init()\` to scaffold it, then retry.`);
 	}
-	const stats = await inspectOutdir(node_path.default.isAbsolute(config.outDir) ? node_path.default.resolve(config.outDir) : node_path.default.resolve(root, config.outDir)).catch(() => {
+	const stats = await inspectOutdir(node_path$1.default.isAbsolute(config.outDir) ? node_path$1.default.resolve(config.outDir) : node_path$1.default.resolve(root, config.outDir)).catch(() => {
 		throw deployError("ERR_DEPLOY_EMPTY_OUTDIR", `${ERROR_PREFIX$3}: outDir ${JSON.stringify(config.outDir)} is missing.\n  Run your build first, then retry.`);
 	});
 	if (stats.fileCount === 0) throw deployError("ERR_DEPLOY_EMPTY_OUTDIR", `${ERROR_PREFIX$3}: outDir ${JSON.stringify(config.outDir)} is empty — nothing to deploy.`);
@@ -4244,7 +4649,6 @@ async function runPreflight(config, root, env = process.env) {
 	if (stats.fileCount > limit) throw deployError("ERR_DEPLOY_TOO_MANY_FILES", `${ERROR_PREFIX$3}: outDir contains ${stats.fileCount} files; the limit is ${limit}.\n  Raise it with ${MAX_FILES_ENV} (paid tier) or reduce the output.`);
 	if (stats.oversizePath !== null) throw deployError("ERR_DEPLOY_FILE_TOO_LARGE", `${ERROR_PREFIX$3}: file ${JSON.stringify(stats.oversizePath)} exceeds the 25 MiB per-file limit.`);
 }
-
 //#endregion
 //#region src/plugins/deploy/slug.ts
 /**
@@ -4285,7 +4689,6 @@ function toSlug(name) {
 	slug = slug.slice(0, end);
 	return slug.length > 0 ? slug : FALLBACK_SLUG;
 }
-
 //#endregion
 //#region src/plugins/deploy/api.ts
 /** Error prefix for deploy config/validation failures (spec/11 Part-3). */
@@ -4325,6 +4728,15 @@ function validateConfig(ctx) {
 */
 function createApi$1(ctx) {
 	return {
+		/**
+		* Deploy the built outDir to Cloudflare Pages via the wrangler subprocess.
+		*
+		* @param options - Optional branch override and build toggle.
+		* @returns The deploy result (url, deploymentId, branch, durationMs).
+		* @throws {Error} With a `code` from the deploy error taxonomy on any failure.
+		* @example
+		* await api.run();
+		*/
 		async run(options = {}) {
 			const root = process.cwd();
 			const slug = toSlug(ctx.require(sitePlugin).name());
@@ -4364,10 +4776,25 @@ function createApi$1(ctx) {
 			});
 			return result;
 		},
+		/**
+		* Return the most recent successful deploy result, or null if none occurred.
+		*
+		* @returns A frozen snapshot of the last DeployResult, or null.
+		* @example
+		* const last = api.getLastDeployment();
+		*/
 		getLastDeployment() {
 			const last = ctx.state.lastDeployment;
 			return last ? Object.freeze({ ...last }) : null;
 		},
+		/**
+		* Generate deploy scaffolding (wrangler.jsonc + optional GitHub workflow).
+		*
+		* @param options - Optional ci toggle and check (drift-only) mode.
+		* @returns Which files were written, skipped, or would drift.
+		* @example
+		* await api.init({ ci: true });
+		*/
 		async init(options = {}) {
 			const slug = toSlug(ctx.require(sitePlugin).name());
 			return writeScaffolding({
@@ -4379,7 +4806,6 @@ function createApi$1(ctx) {
 		}
 	};
 }
-
 //#endregion
 //#region src/plugins/deploy/defaults.ts
 /**
@@ -4399,7 +4825,6 @@ const defaultConfig = {
 	compatibilityDate: "2024-01-01",
 	ci: false
 };
-
 //#endregion
 //#region src/plugins/deploy/events.ts
 /**
@@ -4414,7 +4839,6 @@ const defaultConfig = {
 * ```
 */
 const deployEvents = (register) => ({ "deploy:complete": register("Deployment completed successfully") });
-
 //#endregion
 //#region src/plugins/deploy/state.ts
 /**
@@ -4452,7 +4876,6 @@ function createState$1(_ctx) {
 		spawn: defaultSpawn
 	};
 }
-
 //#endregion
 //#region src/plugins/deploy/index.ts
 /**
@@ -4470,7 +4893,6 @@ const deployPlugin = createPlugin$1("deploy", {
 	onInit: validateConfig,
 	api: createApi$1
 });
-
 //#endregion
 //#region src/plugins/spa/api.ts
 /**
@@ -4485,19 +4907,39 @@ const deployPlugin = createPlugin$1("deploy", {
 */
 function createApi(ctx) {
 	return {
+		/**
+		* Register a component definition (last-registered-wins); warns on collision.
+		*
+		* @param component - The component definition created via `createComponent`.
+		* @example
+		* app.spa.register(counter);
+		*/
 		register(component) {
 			if (ctx.state.registeredComponents.has(component.name)) ctx.log.warn("spa:component-collision", { name: component.name });
 			ctx.state.kernel?.register(component);
 		},
+		/**
+		* Programmatically navigate to a path (client runtime; no-op without a DOM).
+		*
+		* @param path - Target path (pathname, optionally with search/hash).
+		* @example
+		* app.spa.navigate("/about");
+		*/
 		navigate(path) {
 			ctx.state.kernel?.processNav(path);
 		},
+		/**
+		* Read the current resolved URL.
+		*
+		* @returns The current pathname + search.
+		* @example
+		* app.spa.current();
+		*/
 		current() {
 			return ctx.state.currentUrl;
 		}
 	};
 }
-
 //#endregion
 //#region src/plugins/spa/events.ts
 /**
@@ -4517,7 +4959,6 @@ function spaEvents(register) {
 		"spa:component-unmount": register("A component instance detached from an element.")
 	};
 }
-
 //#endregion
 //#region src/plugins/spa/types.ts
 var types_exports$7 = /* @__PURE__ */ __exportAll({ COMPONENT_HOOK_NAMES: () => COMPONENT_HOOK_NAMES });
@@ -4530,11 +4971,7 @@ const COMPONENT_HOOK_NAMES = [
 	"onUnMount",
 	"onDestroy"
 ];
-
-//#endregion
-//#region src/plugins/spa/components.ts
-/** The set of legal hook names, frozen for O(1) membership checks. */
-const HOOK_NAME_SET = new Set(COMPONENT_HOOK_NAMES);
+new Set(COMPONENT_HOOK_NAMES);
 /**
 * Extracts the page data payload from the inline `script#__DATA__` element.
 * Returns an empty object when the script is absent, empty, or invalid JSON.
@@ -4702,7 +5139,6 @@ function notifyNavEnd(state) {
 	const data = typeof document === "undefined" ? {} : extractPageData(document);
 	for (const [element, instance] of state.instances) if (instance.persistent) runHook(instance, "onNavEnd", makeContext(element, data));
 }
-
 //#endregion
 //#region src/plugins/spa/head.ts
 /** Single-element head selectors synced by replace/append/remove on navigation. */
@@ -4777,7 +5213,6 @@ function syncHead(_head, doc) {
 	for (const selector of META_SELECTORS) syncElement(selector, doc);
 	for (const selector of REPLACE_ALL_SELECTORS) replaceAllBySelector(selector, doc);
 }
-
 //#endregion
 //#region src/plugins/spa/progress.ts
 /** Delay before the bar appears, so fast navigations show no indicator. */
@@ -4861,7 +5296,6 @@ function createProgressBar(enabled) {
 		done
 	};
 }
-
 //#endregion
 //#region src/plugins/spa/router.ts
 /**
@@ -5096,7 +5530,6 @@ function attachRouter(handlers) {
 	const navigation = getNavigation();
 	return navigation ? attachNavigationApi(navigation, handlers) : attachHistoryFallback(handlers);
 }
-
 //#endregion
 //#region src/plugins/spa/state.ts
 /** Error prefix for spa config-validation failures (spec/11 Part-3). */
@@ -5170,7 +5603,6 @@ function createState(_ctx) {
 		kernel: null
 	};
 }
-
 //#endregion
 //#region src/plugins/spa/kernel.ts
 /**
@@ -5279,10 +5711,22 @@ function createSpaKernel(state, config, emit, deps) {
 		onError: handleError
 	};
 	return {
+		/**
+		* Register config components and seed currentUrl from the document.
+		*
+		* @example
+		* kernel.init();
+		*/
 		init() {
 			for (const component of resolved.components) registerComponent(state, component);
 			state.currentUrl = currentLocationUrl();
 		},
+		/**
+		* Boot navigation interception + initial scan (throws if already started).
+		*
+		* @example
+		* kernel.boot();
+		*/
 		boot() {
 			if (typeof document === "undefined") return;
 			if (state.started) throw new Error(`${ERROR_PREFIX} spa kernel already started.\n  Call app.stop() before booting again (single boot per app).`);
@@ -5292,16 +5736,42 @@ function createSpaKernel(state, config, emit, deps) {
 			scanAndMount(state, emit, resolved.swapSelector);
 			state.started = true;
 		},
+		/**
+		* Register a component definition (last-registered-wins).
+		*
+		* @param component - The component definition to register.
+		* @example
+		* kernel.register(counter);
+		*/
 		register(component) {
 			registerComponent(state, component);
 		},
+		/**
+		* Process a navigation to `path` (fetch then swap; full reload on error).
+		*
+		* @param path - The target path to navigate to.
+		* @example
+		* kernel.processNav("/about");
+		*/
 		processNav(path) {
 			if (typeof document === "undefined") return;
 			performNavigation(path, handlers).catch(() => {});
 		},
+		/**
+		* Scan the swap region and mount components for matching elements.
+		*
+		* @example
+		* kernel.scan();
+		*/
 		scan() {
 			scanAndMount(state, emit, resolved.swapSelector);
 		},
+		/**
+		* Tear down router listeners, dispose all instances, reset boot state.
+		*
+		* @example
+		* kernel.dispose();
+		*/
 		dispose() {
 			state.destroyRouter?.();
 			state.destroyRouter = null;
@@ -5330,7 +5800,6 @@ function initSpa(ctx) {
 	kernelRef.current = kernel;
 	kernel.init();
 }
-
 //#endregion
 //#region src/plugins/spa/lifecycle.ts
 /** Router/instance teardown captured during onStart (undefined when stopped). */
@@ -5378,7 +5847,6 @@ function disposeSpa() {
 		logRef = void 0;
 	}
 }
-
 //#endregion
 //#region src/plugins/spa/index.ts
 /**
@@ -5402,42 +5870,28 @@ const spaPlugin = createPlugin$1("spa", {
 	},
 	onStop: disposeSpa
 });
-
 //#endregion
 //#region src/plugins/build/types.ts
 var types_exports = /* @__PURE__ */ __exportAll({});
-
 //#endregion
 //#region src/plugins/content/types.ts
 var types_exports$1 = /* @__PURE__ */ __exportAll({});
-
 //#endregion
 //#region src/plugins/deploy/types.ts
 var types_exports$2 = /* @__PURE__ */ __exportAll({});
-
 //#endregion
 //#region src/plugins/env/types.ts
 var types_exports$3 = /* @__PURE__ */ __exportAll({});
-
 //#endregion
 //#region src/plugins/head/types.ts
 var types_exports$4 = /* @__PURE__ */ __exportAll({});
-
 //#endregion
 //#region src/plugins/log/types.ts
 var types_exports$5 = /* @__PURE__ */ __exportAll({});
-
 //#endregion
 //#region src/plugins/router/types.ts
 var types_exports$6 = /* @__PURE__ */ __exportAll({});
-
-//#endregion
-//#region src/index.ts
-/**
-* @file `@moku-labs/web` — a Moku Layer-2 content static-site + SPA framework.
-* @see README.md
-*/
-const framework = createCore(coreConfig, {
+const { createApp, createPlugin } = createCore(coreConfig, {
 	plugins: [
 		sitePlugin,
 		i18nPlugin,
@@ -5450,56 +5904,54 @@ const framework = createCore(coreConfig, {
 	],
 	pluginConfigs: {}
 });
-const { createApp, createPlugin } = framework;
-
 //#endregion
-Object.defineProperty(exports, 'Build', {
-  enumerable: true,
-  get: function () {
-    return types_exports;
-  }
+Object.defineProperty(exports, "Build", {
+	enumerable: true,
+	get: function() {
+		return types_exports;
+	}
 });
-Object.defineProperty(exports, 'Content', {
-  enumerable: true,
-  get: function () {
-    return types_exports$1;
-  }
+Object.defineProperty(exports, "Content", {
+	enumerable: true,
+	get: function() {
+		return types_exports$1;
+	}
 });
-Object.defineProperty(exports, 'Deploy', {
-  enumerable: true,
-  get: function () {
-    return types_exports$2;
-  }
+Object.defineProperty(exports, "Deploy", {
+	enumerable: true,
+	get: function() {
+		return types_exports$2;
+	}
 });
-Object.defineProperty(exports, 'Env', {
-  enumerable: true,
-  get: function () {
-    return types_exports$3;
-  }
+Object.defineProperty(exports, "Env", {
+	enumerable: true,
+	get: function() {
+		return types_exports$3;
+	}
 });
-Object.defineProperty(exports, 'Head', {
-  enumerable: true,
-  get: function () {
-    return types_exports$4;
-  }
+Object.defineProperty(exports, "Head", {
+	enumerable: true,
+	get: function() {
+		return types_exports$4;
+	}
 });
-Object.defineProperty(exports, 'Log', {
-  enumerable: true,
-  get: function () {
-    return types_exports$5;
-  }
+Object.defineProperty(exports, "Log", {
+	enumerable: true,
+	get: function() {
+		return types_exports$5;
+	}
 });
-Object.defineProperty(exports, 'Router', {
-  enumerable: true,
-  get: function () {
-    return types_exports$6;
-  }
+Object.defineProperty(exports, "Router", {
+	enumerable: true,
+	get: function() {
+		return types_exports$6;
+	}
 });
-Object.defineProperty(exports, 'Spa', {
-  enumerable: true,
-  get: function () {
-    return types_exports$7;
-  }
+Object.defineProperty(exports, "Spa", {
+	enumerable: true,
+	get: function() {
+		return types_exports$7;
+	}
 });
 exports.buildArticleHead = buildArticleHead;
 exports.buildPlugin = buildPlugin;
@@ -5522,4 +5974,4 @@ exports.route = route;
 exports.routerPlugin = routerPlugin;
 exports.sitePlugin = sitePlugin;
 exports.spaPlugin = spaPlugin;
-exports.twitter = twitter;
+exports.twitter = twitter;