@moku-labs/web 0.2.0 → 0.3.1

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { t as __exportAll } from "./chunk-DQk6qfdC.mjs";
+import { t as __exportAll } from "./chunk-D7D4PA-g.mjs";
 import { createCoreConfig, createCorePlugin } from "@moku-labs/core";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { cp, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
@@ -23,7 +23,6 @@ import { Resvg } from "@resvg/resvg-js";
 import satori from "satori";
 import { jsx } from "preact/jsx-runtime";
 import { renderToString } from "preact-render-to-string";
-
 //#region src/plugins/env/api.ts
 /** Error prefix for all env API failures. */
 const ERROR_PREFIX$13 = "[web]";
@@ -44,26 +43,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
 /**
@@ -83,7 +131,6 @@ function createEnvState() {
 		publicMap: /* @__PURE__ */ new Map()
 	};
 }
-
 //#endregion
 //#region src/plugins/env/validate.ts
 /** Error message thrown by every frozen-map mutator. */
@@ -202,7 +249,6 @@ function validateSchema(ctx) {
 	freezeMap(state.resolved);
 	freezeMap(state.publicMap);
 }
-
 //#endregion
 //#region src/plugins/env/providers.ts
 /**
@@ -271,6 +317,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 (!existsSync(path)) return {};
 			return parseDotenv(readFileSync(path, "utf8"));
@@ -290,24 +345,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.
@@ -318,12 +369,15 @@ const defaultEnvConfig = {
 * ```
 */
 const envPlugin = createCorePlugin("env", {
-	config: defaultEnvConfig,
+	config: {
+		schema: {},
+		providers: [],
+		publicPrefix: "PUBLIC_"
+	},
 	createState: createEnvState,
 	api: createEnvApi,
 	onInit: validateSchema
 });
-
 //#endregion
 //#region src/plugins/log/expect.ts
 /**
@@ -434,10 +488,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()) {
@@ -451,6 +528,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}.`);
@@ -459,7 +548,6 @@ function createExpectChain(entries) {
 	};
 	return chain;
 }
-
 //#endregion
 //#region src/plugins/log/api.ts
 /**
@@ -528,33 +616,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
 /**
@@ -569,7 +734,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);
@@ -590,7 +765,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
 /**
@@ -611,15 +785,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`.
@@ -628,29 +793,40 @@ const defaultLogConfig = { mode: "production" };
 * @see README.md
 */
 const logPlugin = 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 = createCoreConfig("web", {
-	config: defaultConfig$6,
+	config: { mode: "production" },
 	plugins: [logPlugin, envPlugin],
 	pluginConfigs: {
 		log: { mode: "production" },
 		env: { providers: [dotenv(), processEnv()] }
 	}
 });
-const { createPlugin: createPlugin$1, createCore } = coreConfig;
-
+/**
+* Create a custom plugin bound to this framework's `Config`/`Events` and the core
+* plugin APIs (`log`, `env`). Plugin types are fully inferred from the spec
+* object — never write them explicitly. This is the binding every built-in
+* plugin is wired with, and the one consumer plugins should use too.
+*
+* @example
+* ```ts
+* const analytics = createPlugin("analytics", {
+*   config: { writeKey: "" },
+*   api: (ctx) => ({ track: (event: string) => ctx.log.info("analytics:track", { event }) })
+* });
+* ```
+*/
+const createPlugin$1 = coreConfig.createPlugin;
+/**
+* Step 2 of the factory chain — captures the framework's default plugin set and
+* returns the consumer entry points ({@link createApp} + a re-exported
+* `createPlugin`). Wired once in `src/index.ts`; consumers don't call it directly.
+*/
+const createCore = coreConfig.createCore;
 //#endregion
 //#region src/plugins/i18n/api.ts
 /** Error prefix for all i18n lifecycle failures. */
@@ -690,21 +866,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;
@@ -716,34 +954,36 @@ 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)`.
+* Internationalization plugin — locale registry plus a flat translation helper
+* with default-locale fallback. Pure config-as-data (no state or events);
+* consumed read-only by content, router, head, and build.
 *
-* @file i18n plugin wiring harness.
-* @see README.md
+* @example Register locales and translations
+* ```ts
+* const app = createApp({
+*   pluginConfigs: {
+*     i18n: {
+*       locales: ["en", "uk"],
+*       defaultLocale: "en",
+*       localeNames: { en: "English", uk: "Українська" },
+*       translations: { uk: { "nav.home": "Головна" } }
+*     }
+*   }
+* });
+* ```
 */
-/** 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
 /**
@@ -789,7 +1029,6 @@ function parseFrontmatter(raw, config) {
 		body: parsed.content
 	};
 }
-
 //#endregion
 //#region src/plugins/content/pipeline/plugins.ts
 /**
@@ -946,7 +1185,6 @@ function defaultRehypePlugins() {
 		sectionDividerPlugin
 	];
 }
-
 //#endregion
 //#region src/plugins/content/pipeline/sanitize.ts
 /**
@@ -1033,7 +1271,6 @@ function buildSanitizeSchema() {
 		}
 	};
 }
-
 //#endregion
 //#region src/plugins/content/pipeline/markdown.ts
 /**
@@ -1091,7 +1328,6 @@ function applyPluggable(processor, plugin) {
 	}
 	processor.use(plugin);
 }
-
 //#endregion
 //#region src/plugins/content/pipeline/reading-time.ts
 /**
@@ -1117,7 +1353,6 @@ function calculateReadingTime(text) {
 		wordCount: stats.words
 	};
 }
-
 //#endregion
 //#region src/plugins/content/api.ts
 /**
@@ -1329,6 +1564,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;
@@ -1356,6 +1603,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.`);
@@ -1364,10 +1624,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) {
@@ -1380,12 +1663,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
 /**
@@ -1406,7 +1699,6 @@ const defaultContentConfig = {
 	extraRehypePlugins: [],
 	shikiTheme: "github-dark"
 };
-
 //#endregion
 //#region src/plugins/content/events.ts
 /**
@@ -1425,7 +1717,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
 /**
@@ -1449,7 +1740,6 @@ function createContentState(_ctx) {
 		dirtyPaths: /* @__PURE__ */ new Set()
 	};
 }
-
 //#endregion
 //#region src/plugins/content/validate.ts
 /**
@@ -1468,7 +1758,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
 /**
@@ -1479,6 +1768,26 @@ function validateContentConfig(config) {
 * and `content:invalidated`.
 * @see README.md
 */
+/**
+* Content plugin — Markdown pipeline: discovers files, parses frontmatter, renders
+* to sanitized HTML (rehype-sanitize unless `trustedContent`), and exposes a
+* locale-keyed Article model. Depends on i18n; emits `content:ready` and
+* `content:invalidated`.
+*
+* @example Point at a content directory and pick a Shiki theme
+* ```ts
+* const app = createApp({
+*   pluginConfigs: {
+*     content: {
+*       contentDir: "./content",
+*       shikiTheme: "github-dark",
+*       defaultAuthor: "Ada Lovelace"
+*       // trustedContent: true // ONLY for fully author-controlled Markdown — disables sanitize
+*     }
+*   }
+* });
+* ```
+*/
 const contentPlugin = createPlugin$1("content", {
 	depends: [i18nPlugin],
 	events: contentEvents,
@@ -1487,7 +1796,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. */
@@ -1579,50 +1887,99 @@ 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.
+* Site plugin — holds global, frozen site metadata (name, url, author,
+* description) and builds canonical URLs. Consumed by router, head, and build.
+* `name` and `url` must be non-empty (validated at `onInit`).
 *
-* @file site plugin wiring harness.
-* @see README.md
+* @example Set your site identity
+* ```ts
+* const app = createApp({
+*   pluginConfigs: {
+*     site: {
+*       name: "My Blog",
+*       url: "https://blog.dev",
+*       author: "Ada Lovelace",
+*       description: "Notes on computing"
+*     }
+*   }
+* });
+* ```
 */
-/** 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
 /**
@@ -1692,7 +2049,6 @@ function matchRoute(compiled, pathname) {
 	}
 	return null;
 }
-
 //#endregion
 //#region src/plugins/router/api.ts
 /**
@@ -1755,23 +2111,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. */
@@ -1933,9 +2329,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);
 		},
@@ -1996,7 +2414,6 @@ function buildRouterTable(config, baseUrl, locales, defaultLocale) {
 		defaultLocale
 	});
 }
-
 //#endregion
 //#region src/plugins/router/builders/route-builder.ts
 /**
@@ -2042,28 +2459,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);
 		}
@@ -2084,7 +2581,6 @@ function route(pattern) {
 function defineRoutes(routes) {
 	return routes;
 }
-
 //#endregion
 //#region src/plugins/router/state.ts
 /**
@@ -2103,25 +2599,36 @@ 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
+* Router plugin — typed, named route definitions with locale-aware URL generation
+* and matching. Author routes with {@link route} + {@link defineRoutes}. Depends
+* on site (base URL) and i18n (locales).
+*
+* @example Define routes and choose a render mode
+* ```ts
+* const app = createApp({
+*   pluginConfigs: {
+*     router: {
+*       routes: defineRoutes({
+*         home: route("/"),
+*         article: route("/blog/{slug}/")
+*       }),
+*       mode: "hybrid" // "ssg" | "spa" | "hybrid" (default)
+*     }
+*   }
+* });
+* ```
 */
-/** 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) {
@@ -2130,7 +2637,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). */
@@ -2294,7 +2800,6 @@ function buildArticleHead(articleMeta, canonicalUrl) {
 	elements.push(jsonLd(ld));
 	return elements;
 }
-
 //#endregion
 //#region src/plugins/head/compose.ts
 /**
@@ -2455,7 +2960,6 @@ function serializeElement(element) {
 function serializeHead(elements) {
 	return elements.map((element) => serializeElement(element)).join("");
 }
-
 //#endregion
 //#region src/plugins/head/api.ts
 /**
@@ -2497,7 +3001,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,
@@ -2508,7 +3024,6 @@ function createApi$3(ctx) {
 		}));
 	} };
 }
-
 //#endregion
 //#region src/plugins/head/config.ts
 /** Error prefix for all head config-validation failures. */
@@ -2563,7 +3078,6 @@ function normalizeHeadConfig(config) {
 	if (config.twitterHandle !== void 0) defaults.twitterHandle = config.twitterHandle;
 	return Object.freeze(defaults);
 }
-
 //#endregion
 //#region src/plugins/head/helpers.ts
 /**
@@ -2592,7 +3106,6 @@ const headHelpers = {
 	feedLink,
 	buildArticleHead
 };
-
 //#endregion
 //#region src/plugins/head/state.ts
 /**
@@ -2613,13 +3126,31 @@ const headHelpers = {
 function createState$3(_ctx) {
 	return { defaults: null };
 }
-
 //#endregion
 //#region src/plugins/head/index.ts
 /**
 * @file head — Standard Plugin wiring harness (logic in primitives/compose/api/config).
 * @see README.md
 */
+/**
+* Head plugin — composes per-route `<head>` metadata (title template, Open Graph,
+* Twitter cards, canonical, hreflang). Use the re-exported SEO primitives
+* ({@link meta}, {@link og}, {@link twitter}, …) inside a route's `.head()`.
+* Depends on site, i18n, and router.
+*
+* @example Set global head defaults
+* ```ts
+* const app = createApp({
+*   pluginConfigs: {
+*     head: {
+*       titleTemplate: "%s — My Blog",
+*       twitterCard: "summary_large_image",
+*       twitterHandle: "@moku_labs"
+*     }
+*   }
+* });
+* ```
+*/
 const headPlugin = createPlugin$1("head", {
 	depends: [
 		sitePlugin,
@@ -2634,7 +3165,6 @@ const headPlugin = createPlugin$1("head", {
 		ctx.state.defaults = normalizeHeadConfig(ctx.config);
 	}
 });
-
 //#endregion
 //#region src/plugins/build/phases/bundle.ts
 /**
@@ -2736,7 +3266,6 @@ async function bundle(ctx, options = {}) {
 	await runOne(ctx, runner, "css", cssEntrypoints, path.join(outDir, "assets"), minify);
 	await runOne(ctx, runner, "js", jsEntrypoints, path.join(outDir, "assets"), minify);
 }
-
 //#endregion
 //#region src/plugins/build/phases/content.ts
 /**
@@ -2779,7 +3308,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
 /**
@@ -2861,7 +3389,6 @@ async function generateFeeds(ctx) {
 	ctx.log.debug("build:feeds", { items: guids.length });
 	return result;
 }
-
 //#endregion
 //#region src/plugins/build/phases/images.ts
 /**
@@ -2901,7 +3428,6 @@ async function processImages(ctx, options = {}) {
 	ctx.log.debug("build:images", { copied });
 	return copied;
 }
-
 //#endregion
 //#region src/plugins/build/phases/og-images.tsx
 /**
@@ -2915,8 +3441,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",
@@ -3037,7 +3561,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;
@@ -3110,7 +3634,6 @@ async function persistDiskCache(outDir, cache) {
 	await mkdir(dir, { recursive: true });
 	await writeFile(path.join(dir, "og-images.json"), JSON.stringify(Object.fromEntries(cache)), "utf8");
 }
-
 //#endregion
 //#region src/plugins/build/phases/pages.tsx
 /**
@@ -3278,7 +3801,6 @@ async function renderPages(ctx) {
 		rootHtml: root?.html ?? null
 	};
 }
-
 //#endregion
 //#region src/plugins/build/phases/sitemap.ts
 /**
@@ -3360,7 +3882,6 @@ async function generateSitemap(ctx) {
 		robots
 	};
 }
-
 //#endregion
 //#region src/plugins/build/pipeline.ts
 /**
@@ -3491,7 +4012,6 @@ async function runPipeline(ctx, options) {
 	phaseContext.emit("build:complete", result);
 	return result;
 }
-
 //#endregion
 //#region src/plugins/build/api.ts
 /**
@@ -3530,9 +4050,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];
 		}
@@ -3567,7 +4107,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
 /**
@@ -3587,7 +4126,6 @@ function createEvents(register) {
 		"build:complete": register("Emitted once after a successful build run")
 	};
 }
-
 //#endregion
 //#region src/plugins/build/state.ts
 /**
@@ -3614,13 +4152,33 @@ function createState$2(ctx) {
 		ogImageHashCache: /* @__PURE__ */ new Map()
 	};
 }
-
 //#endregion
 //#region src/plugins/build/index.ts
 /**
 * @file build — Complex plugin: SSG orchestrator (wiring harness only).
 * @see README.md
 */
+/**
+* Build plugin — the static-site-generation orchestrator. Renders every route to
+* `outDir`, and optionally emits feeds, a sitemap, optimized images, and OG
+* images. Depends on site, i18n, content, router, and head; emits `build:phase`.
+*
+* @example Configure the production build
+* ```ts
+* const app = createApp({
+*   pluginConfigs: {
+*     build: {
+*       outDir: "dist",
+*       minify: true,
+*       feeds: true,
+*       sitemap: true,
+*       images: true,
+*       ogImage: false // or an object to enable + configure OG-image generation
+*     }
+*   }
+* });
+* ```
+*/
 const buildPlugin = createPlugin$1("build", {
 	depends: [
 		sitePlugin,
@@ -3635,7 +4193,6 @@ const buildPlugin = createPlugin$1("build", {
 	api: createApi$2,
 	onInit: (ctx) => validateConfig$1(ctx.config)
 });
-
 //#endregion
 //#region src/plugins/deploy/wrangler.ts
 /**
@@ -3813,8 +4370,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;
@@ -3835,7 +4390,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)}`
 	};
 }
 /**
@@ -3894,7 +4449,6 @@ async function runWrangler(input) {
 		exitCode
 	};
 }
-
 //#endregion
 //#region src/plugins/deploy/generators/github-workflow.ts
 /**
@@ -3949,7 +4503,6 @@ jobs:
           command: pages deploy dist --project-name ${input.slug}
 `;
 }
-
 //#endregion
 //#region src/plugins/deploy/generators/wrangler-config.ts
 /**
@@ -3993,7 +4546,6 @@ async function readWranglerConfig(cwd) {
 		return null;
 	}
 }
-
 //#endregion
 //#region src/plugins/deploy/init.ts
 /**
@@ -4097,7 +4649,6 @@ async function reconcile(input) {
 	await writeFile(path.join(cwd, relativePath), expected, "utf8");
 	result.written.push(relativePath);
 }
-
 //#endregion
 //#region src/plugins/deploy/preflight.ts
 /**
@@ -4191,7 +4742,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
 /**
@@ -4232,7 +4782,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). */
@@ -4272,6 +4821,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());
@@ -4311,10 +4869,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({
@@ -4326,7 +4899,6 @@ function createApi$1(ctx) {
 		}
 	};
 }
-
 //#endregion
 //#region src/plugins/deploy/defaults.ts
 /**
@@ -4346,7 +4918,6 @@ const defaultConfig = {
 	compatibilityDate: "2024-01-01",
 	ci: false
 };
-
 //#endregion
 //#region src/plugins/deploy/events.ts
 /**
@@ -4361,7 +4932,6 @@ const defaultConfig = {
 * ```
 */
 const deployEvents = (register) => ({ "deploy:complete": register("Deployment completed successfully") });
-
 //#endregion
 //#region src/plugins/deploy/state.ts
 /**
@@ -4399,7 +4969,6 @@ function createState$1(_ctx) {
 		spawn: defaultSpawn
 	};
 }
-
 //#endregion
 //#region src/plugins/deploy/index.ts
 /**
@@ -4409,6 +4978,24 @@ function createState$1(_ctx) {
 * Depends: site. Emits: deploy:complete.
 * @see README.md
 */
+/**
+* Deploy plugin — ships the built `outDir` to Cloudflare Pages via the injectable
+* wrangler subprocess, with entropy-gated secret scrubbing of logged output.
+* Depends on site; emits `deploy:complete`.
+*
+* @example Configure the deploy target
+* ```ts
+* const app = createApp({
+*   pluginConfigs: {
+*     deploy: {
+*       target: "cloudflare-pages",
+*       outDir: "dist",
+*       productionBranch: "main"
+*     }
+*   }
+* });
+* ```
+*/
 const deployPlugin = createPlugin$1("deploy", {
 	config: defaultConfig,
 	depends: [sitePlugin],
@@ -4417,7 +5004,6 @@ const deployPlugin = createPlugin$1("deploy", {
 	onInit: validateConfig,
 	api: createApi$1
 });
-
 //#endregion
 //#region src/plugins/spa/api.ts
 /**
@@ -4432,19 +5018,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
 /**
@@ -4464,7 +5070,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 });
@@ -4477,11 +5082,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.
@@ -4649,7 +5250,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. */
@@ -4724,7 +5324,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. */
@@ -4808,7 +5407,6 @@ function createProgressBar(enabled) {
 		done
 	};
 }
-
 //#endregion
 //#region src/plugins/spa/router.ts
 /**
@@ -5043,7 +5641,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). */
@@ -5117,7 +5714,6 @@ function createState(_ctx) {
 		kernel: null
 	};
 }
-
 //#endregion
 //#region src/plugins/spa/kernel.ts
 /**
@@ -5226,10 +5822,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).`);
@@ -5239,16 +5847,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;
@@ -5277,7 +5911,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). */
@@ -5325,7 +5958,6 @@ function disposeSpa() {
 		logRef = void 0;
 	}
 }
-
 //#endregion
 //#region src/plugins/spa/index.ts
 /**
@@ -5336,6 +5968,26 @@ function disposeSpa() {
 * Emits: spa:navigate, spa:navigated, spa:component-mount, spa:component-unmount.
 * @see README.md
 */
+/**
+* SPA plugin — progressive client-side navigation layered over the static site:
+* swaps a page region on navigation, with an optional progress bar and View
+* Transitions. Register interactive islands with {@link createComponent}. Depends
+* on router and head; emits `spa:navigate`, `spa:navigated`, `spa:component-mount`,
+* and `spa:component-unmount`.
+*
+* @example Enable view transitions and a custom swap region
+* ```ts
+* const app = createApp({
+*   pluginConfigs: {
+*     spa: {
+*       swapSelector: "main > section",
+*       viewTransitions: true,
+*       progressBar: true
+*     }
+*   }
+* });
+* ```
+*/
 const spaPlugin = createPlugin$1("spa", {
 	depends: [routerPlugin, headPlugin],
 	config: defaultSpaConfig,
@@ -5349,35 +6001,27 @@ 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
 /**
@@ -5397,7 +6041,45 @@ const framework = createCore(coreConfig, {
 	],
 	pluginConfigs: {}
 });
-const { createApp, createPlugin } = framework;
-
+/**
+* Create and initialize a `@moku-labs/web` application — the Layer-3 entry point.
+* Your overrides are merged over the framework defaults through the 4-level config
+* cascade, every plugin's lifecycle runs, and a fully-typed, frozen app is returned.
+*
+* @param options - Optional configuration:
+*  - `pluginConfigs` — per-plugin overrides, keyed by plugin name
+*    (`site`, `i18n`, `router`, `content`, `head`, `build`, `spa`, `deploy`, `env`).
+*  - `config` — global framework config (e.g. `{ mode: "development" }`).
+*  - `plugins` — extra consumer plugins, merged into the app and its return type.
+*  - `onReady` / `onError` / `onStart` / `onStop` — lifecycle callbacks.
+* @returns The initialized app: `start()`, `stop()`, every plugin's API, and `log`.
+* @example
+* ```ts
+* const app = createApp({
+*   pluginConfigs: {
+*     site: { name: "My Blog", url: "https://blog.dev", author: "Ada", description: "Notes" },
+*     router: { routes: defineRoutes({ home: route("/"), post: route("/blog/{slug}/") }) }
+*   }
+* });
+* await app.start();
+* ```
+*/
+const createApp = framework.createApp;
+/**
+* Create a custom plugin bound to this framework's `Config`/`Events` and core
+* APIs. Plugin types are inferred from the spec object — never written explicitly.
+* Pass the result to {@link createApp} via `plugins`.
+*
+* @example
+* ```ts
+* const analytics = createPlugin("analytics", {
+*   config: { writeKey: "" },
+*   api: (ctx) => ({ track: (event: string) => ctx.log.info("analytics:track", { event }) })
+* });
+*
+* const app = createApp({ plugins: [analytics] });
+* ```
+*/
+const createPlugin = framework.createPlugin;
 //#endregion
-export { types_exports as Build, types_exports$1 as Content, types_exports$2 as Deploy, types_exports$3 as Env, types_exports$4 as Head, types_exports$5 as Log, types_exports$6 as Router, types_exports$7 as Spa, buildArticleHead, buildPlugin, canonical, contentPlugin, createApp, createPlugin, defineRoutes, deployPlugin, envPlugin, feedLink, headPlugin, hreflang, i18nPlugin, jsonLd, logPlugin, meta, og, route, routerPlugin, sitePlugin, spaPlugin, twitter };
+export { types_exports as Build, types_exports$1 as Content, types_exports$2 as Deploy, types_exports$3 as Env, types_exports$4 as Head, types_exports$5 as Log, types_exports$6 as Router, types_exports$7 as Spa, buildArticleHead, buildPlugin, canonical, contentPlugin, createApp, createPlugin, defineRoutes, deployPlugin, envPlugin, feedLink, headPlugin, hreflang, i18nPlugin, jsonLd, logPlugin, meta, og, route, routerPlugin, sitePlugin, spaPlugin, twitter };