@moku-labs/web 0.3.0 → 0.4.0

package/dist/index.d.mts

@@ -3,7 +3,7 @@ import { Pluggable, Processor } from "unified";
 import { ComponentChildren, VNode } from "preact";
 
 //#region src/plugins/log/types.d.ts
-declare namespace types_d_exports$5 {
+declare namespace types_d_exports$6 {
   export { ExpectChain, LogApi, LogConfig, LogEntry, LogLevel, LogSink, LogState };
 }
 /**
@@ -143,7 +143,7 @@ type LogApi = {
   addSink(sink: LogSink): void; /** Clear all recorded entries while keeping registered sinks. */
   reset(): void;
 };
-declare namespace types_d_exports$3 {
+declare namespace types_d_exports$4 {
   export { EnvApi, EnvConfig, EnvProvider, EnvState, EnvVarSpec };
 }
 /**
@@ -302,6 +302,26 @@ type EnvApi = {
   getPublicMap(): ReadonlyMap<string, string>;
 };
 //#endregion
+//#region src/plugins/env/providers.browser.d.ts
+/**
+ * A browser-safe {@link EnvProvider} that reads `import.meta.env` and an optional
+ * `globalThis[globalKey]` snapshot, merging them with the runtime global winning.
+ * Contains zero `node:*` imports, so it is safe to include in the client bundle.
+ * Never throws on missing sources — each absent source resolves to `{}`.
+ *
+ * @param options - Optional settings.
+ * @param options.globalKey - `globalThis` key to read a public-env snapshot from. Defaults to `"__ENV__"`.
+ * @returns An {@link EnvProvider} named `browser-env`.
+ * @example
+ * ```ts
+ * const provider = browserEnv();
+ * provider.load(); // { PUBLIC_API_URL: "/api", ... }
+ * ```
+ */
+declare function browserEnv(options?: {
+  globalKey?: string;
+}): EnvProvider;
+//#endregion
 //#region src/plugins/env/index.d.ts
 /**
  * Core plugin that resolves, validates, and freezes the environment at `onInit`,
@@ -521,8 +541,8 @@ type Api$5 = {
    */
   t(locale: string, key: string): string;
 };
-declare namespace types_d_exports$6 {
-  export { Api$4 as Api, CompileInput, CompiledRoute, Config$4 as Config, ExtractRouteParams, ExtractSegmentParameter, HeadConfig$1 as HeadConfig, MatcherTable, Prettify, RouteBuilder, RouteContext, RouteDefinition, RouteHandlers, RouteMap, RouteState, RouterApi, RouterConfig, RouterState, State$4 as State, TypedRoute };
+declare namespace types_d_exports$7 {
+  export { Api$4 as Api, ClientRoute, CompileInput, CompiledRoute, Config$4 as Config, ExtractRouteParams, ExtractSegmentParameter, HeadConfig$1 as HeadConfig, MatcherTable, Prettify, RouteBuilder, RouteContext, RouteDefinition, RouteHandlers, RouteMap, RouteState, RouterApi, RouterConfig, RouterState, State$4 as State, TypedRoute };
 }
 /**
  * Param contribution of a single path segment. `{name:?}` / `:name?` → optional;
@@ -588,11 +608,23 @@ interface RouteBuilder<S extends RouteState> extends RouteDefinition {
   layout(component: (children: ComponentChildren) => VNode): RouteBuilder<S>;
   /** Attach the page render handler. */
   render(handler: (ctx: RouteContext<S>) => VNode): RouteBuilder<S>;
+  /**
+   * Attach the client-side validation gate: parse the raw `unknown` fetched from
+   * the persisted data file back into this route's data type `S["data"]`. Runs at
+   * the trust boundary before `render` on the client (and MUST return `S["data"]`,
+   * so a mismatched schema is a compile error). Throw inside it to reject malformed
+   * data — `spa` then falls back to HTML-over-fetch. Use a hand guard or any
+   * Standard-Schema validator (zod/valibot/arktype).
+   */
+  parse(handler: (raw: unknown) => S["data"]): RouteBuilder<S>;
   /** Attach the head/SEO handler. */
   head(handler: (ctx: RouteContext<S>) => HeadConfig$1): RouteBuilder<S>;
   /** Attach a static-generation param producer. */
   generate(handler: (locale: string) => S["params"][] | Promise<S["params"][]>): RouteBuilder<S>;
-  /** Attach an arbitrary metadata bag. */
+  /**
+   * Attach an arbitrary metadata bag. The bag MUST be JSON-serializable: it is
+   * projected verbatim into `clientManifest()` and shipped to the browser.
+   */
   meta(meta: Record<string, unknown>): RouteBuilder<S>;
   /** Attach a JSON serializer for the route's data. */
   toJson(handler: (ctx: RouteContext<S>) => unknown): RouteBuilder<S>;
@@ -607,6 +639,8 @@ interface RouteHandlers {
   readonly layout?: (children: ComponentChildren) => VNode;
   /** Page renderer. */
   readonly render?: (ctx: RouteContext<RouteState>) => VNode;
+  /** Client-side validation gate: `unknown` (fetched JSON) → the route's data type, or throw. */
+  readonly parse?: (raw: unknown) => unknown;
   /** Head/SEO producer. */
   readonly head?: (ctx: RouteContext<RouteState>) => HeadConfig$1;
   /** Static-generation param producer. */
@@ -711,6 +745,8 @@ interface MatcherTable {
 interface RouterState {
   /** Compiled matcher table; `null` until `onInit` assigns it. */
   table: MatcherTable | null;
+  /** Resolved render mode (single source of truth; set in `onInit`). Defaults `"hybrid"`. */
+  mode: "ssg" | "spa" | "hybrid";
 }
 /** Plain-data input to `compileRoutes` — resolved DATA only, never the plugin ctx. */
 interface CompileInput {
@@ -725,6 +761,24 @@ interface CompileInput {
   /** Default locale used for bare-pattern fallback. */
   readonly defaultLocale: string;
 }
+/**
+ * Serializable route entry for the client route-index — a projection of the
+ * compiled route table with NO `_handlers` closures, safe to ship to the browser
+ * (the SPA recompiles matchers lazily from `pattern`).
+ *
+ * @remarks
+ * `meta` MUST be JSON-serializable: `clientManifest()` is intended to survive a
+ * `JSON.stringify`/`JSON.parse` round-trip, so a route's `.meta()` bag must contain
+ * only JSON-safe values (no functions, symbols, or class instances).
+ */
+interface ClientRoute {
+  /** URL pattern string, e.g. `/{lang:?}/{slug}/`. */
+  readonly pattern: string;
+  /** Route name key from the route map. */
+  readonly name: string;
+  /** Route metadata bag from `.meta()`. MUST be JSON-serializable. */
+  readonly meta: Record<string, unknown>;
+}
 /** Public API exposed via `ctx.require(routerPlugin)`. */
 type RouterApi = {
   /**
@@ -767,197 +821,36 @@ type RouterApi = {
    * for (const def of ctx.require(routerPlugin).manifest()) { def._handlers.load?.({}, "en"); }
    */
   manifest(): readonly RouteDefinition[];
-};
-/** Re-export under the canonical `Config` name for the plugin-types barrel. */
-type Config$4 = RouterConfig;
-/** Re-export under the canonical `State` name for the plugin-types barrel. */
-type State$4 = RouterState;
-/** Re-export under the canonical `Api` name for the plugin-types barrel. */
-type Api$4 = RouterApi;
-declare namespace types_d_exports$1 {
-  export { Api$3 as Api, Article, ArticleCard, ComputedFields, Config$3 as Config, ContentApiContext, ContentEvents, Frontmatter, State$3 as State };
-}
-/**
- * Configuration for the content plugin.
- *
- * @example
- * ```ts
- * { contentDir: "./src/content", trustedContent: false, shikiTheme: "github-dark" }
- * ```
- */
-type Config$3 = {
-  /** Absolute or project-relative path to the content directory. Validated in onInit. */contentDir: string;
-  /**
-   * SECURITY GATE. When false (the default), rehype-sanitize runs as the final
-   * pipeline step. Set true ONLY for fully author-controlled Markdown — true
-   * disables sanitize and trusts all raw HTML.
-   */
-  trustedContent: boolean; /** Additional remark plugins, concatenated AFTER framework defaults. Defaults to []. */
-  extraRemarkPlugins?: readonly Pluggable[]; /** Additional rehype plugins, concatenated after custom transforms, before Shiki + sanitize. Defaults to []. */
-  extraRehypePlugins?: readonly Pluggable[]; /** Shiki theme name for syntax highlighting. Defaults to "github-dark". */
-  shikiTheme?: string; /** Author applied to articles whose frontmatter omits author. Defaults to undefined. */
-  defaultAuthor?: string;
-};
-/**
- * Internal mutable state for the content plugin.
- *
- * @example
- * ```ts
- * { processor: null, articles: new Map(), slugs: null, dirtyPaths: new Set() }
- * ```
- */
-type State$3 = {
-  /** Lazily-created unified processor singleton. null until first render()/loadAll(). */processor: Processor | null; /** Article cache keyed locale -> (slug -> Article). Starts empty. */
-  articles: Map<string, Map<string, Article>>; /** Discovered, sorted slug list cached after first disk scan. null until first discovery. */
-  slugs: string[] | null; /** Paths marked stale by invalidate(); next loadAll() re-reads only these. Starts empty. */
-  dirtyPaths: Set<string>;
-};
-/**
- * YAML frontmatter parsed from each article file.
- *
- * @example
- * ```ts
- * { title: "Hello", date: "2026-01-15", description: "Intro", tags: [], language: "en" }
- * ```
- */
-type Frontmatter = {
-  /** Article title. Required. */title: string; /** ISO 8601 date string, e.g. "2026-01-15". Required. */
-  date: string; /** Short summary used in cards, feeds, and meta description. Required. */
-  description: string; /** Topic tags. Required (may be empty array). */
-  tags: string[]; /** Source language code of this file. Required. */
-  language: string; /** Draft flag. Excluded from output in production mode. Defaults to false. */
-  draft?: boolean; /** Author name. Falls back to config.defaultAuthor when omitted. */
-  author?: string;
-};
-/**
- * Fields computed by the pipeline (not authored in frontmatter).
- *
- * @example
- * ```ts
- * { slug: "hello", readingTime: 1, contentId: "hello", status: "published", wordCount: 42 }
- * ```
- */
-type ComputedFields = {
-  /** Article directory name. */slug: string; /** Reading time in minutes (ceiling, minimum 1). */
-  readingTime: number; /** Stable content identifier (slug by default). */
-  contentId: string; /** Derived publication status. */
-  status: "published" | "draft"; /** Word count from the source body. */
-  wordCount: number;
-};
-/**
- * A fully processed, render-ready article.
- *
- * @example
- * ```ts
- * { frontmatter, computed, html: "<p>…</p>", locale: "en", isFallback: false, url: "/en/hello/" }
- * ```
- */
-type Article = {
-  /** Parsed frontmatter. */frontmatter: Frontmatter; /** Pipeline-computed metadata. */
-  computed: ComputedFields; /** Sanitized rendered HTML body. */
-  html: string; /** Locale this Article instance represents (the requested locale, even on fallback). */
-  locale: string; /** True when the default-locale file was used because the requested locale was missing. */
-  isFallback: boolean; /** Canonical URL for this article in this locale. */
-  url: string;
-};
-/**
- * Lightweight projection of Article for cards/lists.
- *
- * @example
- * ```ts
- * { contentId: "hello", status: "published", title: "Hello", date: "2026-01-15", description: "Intro", tags: [], readingTime: 1, url: "/en/hello/" }
- * ```
- */
-type ArticleCard = {
-  /** Stable content identifier. */contentId: string; /** Derived publication status. */
-  status: "published" | "draft"; /** Article title. */
-  title: string; /** ISO 8601 date string. */
-  date: string; /** Short summary. */
-  description: string; /** Topic tags. */
-  tags: string[]; /** Reading time in minutes. */
-  readingTime: number; /** Canonical URL for this article in this locale. */
-  url: string;
-};
-/**
- * Notification-only events emitted by the content plugin.
- *
- * @example
- * ```ts
- * emit("content:ready", { locales: ["en"], articleCount: 3 });
- * ```
- */
-type ContentEvents = {
-  /** All articles loaded across locales. */"content:ready": {
-    locales: readonly string[];
-    articleCount: number;
-  }; /** Article paths marked stale for dev rebuild. */
-  "content:invalidated": {
-    paths: readonly string[];
-  };
-};
-/**
- * Kernel-free domain context handed to createContentApi by the wiring harness.
- * Carries ctx.state (mutable escape hatch), config, global, emit, and the
- * i18n-derived locale/url helpers — so api.ts stays free of createPlugin/ctx.
- *
- * @example
- * ```ts
- * const apiContext: ContentApiContext = { state, config, global, emit, locales, defaultLocale, articleToUrl };
- * ```
- */
-type ContentApiContext = {
-  /** Mutable plugin state (article cache + lazy processor). */state: State$3; /** Resolved plugin configuration. */
-  config: Config$3; /** Global framework configuration (mode, etc.). */
-  global: {
-    mode: "production" | "development";
-  }; /** Emit a registered content event. */
-  emit: <K extends keyof ContentEvents>(event: K, payload: ContentEvents[K]) => void; /** Active locale codes from i18n. */
-  locales: () => readonly string[]; /** Default locale code from i18n (fallback source). */
-  defaultLocale: () => string; /** Build a canonical article URL for a locale + slug. */
-  articleToUrl: (locale: string, slug: string) => string;
-};
-/**
- * Public API for the content plugin.
- *
- * @example
- * ```ts
- * const map = await app.content.loadAll();
- * ```
- */
-type Api$3 = {
-  /**
-   * Load every article across every active locale, returning a locale-keyed
-   * map of date-descending Article arrays. Emits content:ready.
-   */
-  loadAll(): Promise<Map<string, Article[]>>;
-  /**
-   * Resolve and render a single article for one locale, with locale fallback.
-   *
-   * @param slug - Article directory name.
-   * @param locale - Requested locale code.
-   */
-  load(slug: string, locale: string): Promise<Article>;
-  /**
-   * Render a raw Markdown string to HTML through the full pipeline.
-   *
-   * @param md - Raw Markdown source.
-   */
-  renderMarkdown(md: string): Promise<string>;
   /**
-   * Mark file paths stale for incremental dev rebuilds. Emits content:invalidated.
+   * Serializable, specificity-sorted projection of the route table for client
+   * shipping. Maps the compiled table to `{ pattern, name, meta }` entries with NO
+   * `_handlers` closures, returned as a fresh frozen array. JSON-serializable so the
+   * SPA can embed it and recompile matchers lazily in the browser.
    *
-   * @param paths - File paths to invalidate.
+   * @returns A fresh, frozen, specificity-sorted read-only array of {@link ClientRoute}.
+   * @example
+   * const json = JSON.stringify(ctx.require(routerPlugin).clientManifest());
    */
-  invalidate(paths: readonly string[]): void;
+  clientManifest(): readonly ClientRoute[];
   /**
-   * Project a full Article to a lightweight ArticleCard for list/grid rendering.
+   * The resolved render mode — the single source of truth for static/hybrid/spa
+   * behavior. `build` reads it to decide whether to emit client data sidecars;
+   * `spa` reads it to decide whether to attempt client DATA navigation.
    *
-   * @param article - The source article.
+   * @returns `"ssg" | "spa" | "hybrid"`.
+   * @example
+   * if (ctx.require(routerPlugin).mode() !== "ssg") { ... }
    */
-  articleToCard(article: Article): ArticleCard;
+  mode(): "ssg" | "spa" | "hybrid";
 };
-declare namespace types_d_exports$4 {
-  export { Api$2 as Api, ArticleMeta, Config$2 as Config, HeadConfig, HeadDefaults, HeadElement, ResolvedRoute, State$2 as State };
+/** Re-export under the canonical `Config` name for the plugin-types barrel. */
+type Config$4 = RouterConfig;
+/** Re-export under the canonical `State` name for the plugin-types barrel. */
+type State$4 = RouterState;
+/** Re-export under the canonical `Api` name for the plugin-types barrel. */
+type Api$4 = RouterApi;
+declare namespace types_d_exports$5 {
+  export { Api$3 as Api, ArticleMeta, Config$3 as Config, HeadConfig, HeadDefaults, HeadElement, ResolvedRoute, State$3 as State };
 }
 /**
  * @file head plugin — type definitions skeleton
@@ -973,7 +866,7 @@ declare namespace types_d_exports$4 {
  * const config: Config = { titleTemplate: "%s — Moku" };
  * ```
  */
-type Config$2 = {
+type Config$3 = {
   /** Title template applied to per-route titles. `%s` is replaced by the route title. */titleTemplate?: string; /** Default Open Graph image URL used when a route does not supply one. */
   defaultOgImage?: string; /** Default Twitter card type emitted when og/twitter content is present. */
   twitterCard?: "summary" | "summary_large_image"; /** Default Twitter site handle (e.g. `"@moku_labs"`) emitted as `twitter:site`. */
@@ -991,7 +884,7 @@ type Config$2 = {
  * const state: State = { defaults: null };
  * ```
  */
-type State$2 = {
+type State$3 = {
   /** Normalized head defaults, assigned once in `onInit` (initially `null`). */defaults: HeadDefaults | null;
 };
 /**
@@ -1085,7 +978,7 @@ type ResolvedRoute = {
  * const html: string = api.render(route, data);
  * ```
  */
-type Api$2 = {
+type Api$3 = {
   /**
    * Compose the final `<head>` inner HTML for a route. Pulled synchronously by `build`.
    *
@@ -1099,263 +992,41 @@ type Api$2 = {
    */
   render(route: ResolvedRoute, data: unknown): string;
 };
-declare namespace types_d_exports {
-  export { Api$1 as Api, BuildEvents, BuildResult, Config$1 as Config, ExtractApi$1 as ExtractApi, OgImageConfig, OgPngRenderer, PhaseContext, PhaseEmit, PhaseLog, PhaseName, PhaseRequire, State$1 as State };
+declare namespace types_d_exports$8 {
+  export { COMPONENT_HOOK_NAMES, ComponentContext, ComponentDef, ComponentHooks, ComponentInstance, ExtractApi$1 as ExtractApi, PageData, ResolvedSpaConfig, SpaApi, SpaConfig, SpaContext, SpaDataReader, SpaEmitFunction, SpaEvents, SpaKernel, SpaKernelDeps, SpaRequire, SpaState };
 }
+/** Payload map for the events `spa` emits, used to type the kernel's `emit` closure. */
+type SpaEvents = {
+  /** A navigation has been intercepted and is starting. */"spa:navigate": {
+    from: string;
+    to: string;
+  }; /** The swap completed and the new URL is active. */
+  "spa:navigated": {
+    url: string;
+  }; /** A component instance attached to an element. */
+  "spa:component-mount": {
+    name: string;
+    el: Element;
+  }; /** A component instance detached from an element. */
+  "spa:component-unmount": {
+    name: string;
+    el: Element;
+  };
+};
+/** Strictly-typed emit closure for the spa events (kernel overload form). */
+type SpaEmitFunction = EmitFn<SpaEvents>;
 /**
  * Structural extraction of a plugin instance's public API from its `_phantom`
- * carrier (mirrors the kernel's non-exported `ExtractPluginApi`) so the
- * framework's generic `require` is assignable to {@link PhaseContext.require}.
+ * carrier (mirrors the kernel's non-exported `ExtractPluginApi`).
  *
  * @example
- * ```ts
- * type ContentApi = ExtractApi<typeof contentPlugin>;
- * ```
+ * type RApi = ExtractApi<typeof routerPlugin>;
  */
 type ExtractApi$1<PluginCandidate> = PluginCandidate extends {
   readonly _phantom: {
     readonly api: infer PluginApi;
   };
 } ? PluginApi : never;
-/**
- * Minimal logger slice used by the pipeline and phases (the core `log` API).
- *
- * @example
- * ```ts
- * const log: PhaseLog = { info: () => {}, debug: () => {}, warn: () => {}, error: () => {} };
- * ```
- */
-type PhaseLog = {
-  /** Record an informational event. */info(event: string, data?: unknown): void; /** Record a debug event. */
-  debug(event: string, data?: unknown): void; /** Record a warning event. */
-  warn(event: string, data?: unknown): void; /** Record an error event. */
-  error(event: string, data?: unknown): void;
-};
-/**
- * Payload map for the events `build` emits, used to type the `emit` closure
- * handed to the pipeline driver and phases.
- *
- * @example
- * ```ts
- * const emit: PhaseEmit = (name, payload) => kernel.emit(name, payload);
- * ```
- */
-type BuildEvents = {
-  /** Phase boundary marker (start, then done with durationMs). */"build:phase": {
-    phase: PhaseName;
-    status: "start" | "done";
-    durationMs?: number;
-  }; /** One successful-run summary. */
-  "build:complete": {
-    outDir: string;
-    pageCount: number;
-    durationMs: number;
-  };
-};
-/** Strictly-typed emit closure for the build events (kernel overload form). */
-type PhaseEmit = EmitFn<BuildEvents>;
-/** Generic `require` closure for pulling dependency plugin APIs at run time. */
-type PhaseRequire = <PluginCandidate extends {
-  readonly name: string;
-  readonly spec: unknown;
-  readonly _phantom: {
-    readonly config: unknown;
-    readonly state: unknown;
-    readonly api: unknown;
-    readonly events: Record<string, unknown>;
-  };
-}>(plugin: PluginCandidate) => ExtractApi$1<PluginCandidate>;
-/**
- * The plugin-context slice the pipeline driver and every phase consume: the
- * mutable `state`, the resolved `config`/`global`, plus `require`/`emit`/`log`.
- * Typed to match the kernel's generic context so the framework execution
- * context is structurally assignable.
- *
- * @example
- * ```ts
- * const ctx: PhaseContext = { state, config, global, require, emit, log };
- * ```
- */
-type PhaseContext = {
-  /** Mutable per-run build state (caches + runId). */state: State$1; /** Resolved, frozen build config. */
-  readonly config: Readonly<Config$1>; /** Global framework config (mode, etc.). */
-  readonly global: Readonly<{
-    mode: "production" | "development";
-  }>; /** Resolve a depended-upon plugin instance to its public API. */
-  require: PhaseRequire; /** Emit a build event (notification-only). */
-  emit: PhaseEmit; /** Structured logger (core `log` API). */
-  readonly log: PhaseLog;
-};
-/**
- * Injectable PNG renderer for the og-images phase. Defaults to the real
- * Satori → resvg pipeline; unit tests inject a fake to assert hash-cache skip
- * and the `p-limit` bound without rasterizing real images.
- *
- * @example
- * ```ts
- * const render: OgPngRenderer = async () => new Uint8Array();
- * ```
- */
-type OgPngRenderer = (input: {
-  /** Article title rendered into the card. */title: string; /** Output width in pixels. */
-  width: number; /** Output height in pixels. */
-  height: number;
-}) => Promise<Uint8Array>;
-/**
- * Optional OG-image generation config. Omit the field (or set `false`) to disable.
- *
- * @example
- * ```ts
- * const og: OgImageConfig = { fontDir: "./fonts" };
- * ```
- */
-interface OgImageConfig {
-  /** Directory containing at least one .ttf/.otf/.woff font. Validated in onInit (void — config check only). */
-  fontDir: string;
-  /** Optional path to a custom OG template module. Falls back to the built-in template. */
-  template?: string;
-  /** Output dimensions. Defaults to 1200x630. */
-  size?: {
-    width: number;
-    height: number;
-  };
-}
-/**
- * Public configuration for the `build` plugin. Flags give opt-in granularity over
- * individual outputs without rewriting the pipeline.
- *
- * @example
- * ```ts
- * const config: Config = { outDir: "./dist", minify: true, feeds: true, sitemap: true, images: true, ogImage: false };
- * ```
- */
-type Config$1 = {
-  /** Output directory for the built site. */outDir: string; /** Minify bundled CSS/JS. */
-  minify: boolean; /** Generate RSS/Atom/JSON feeds. */
-  feeds: boolean; /** Generate sitemap.xml + robots.txt. */
-  sitemap: boolean; /** Optimize + copy content images. */
-  images: boolean; /** OG-image generation. `false` (or omitted) disables it; an object enables and configures it. */
-  ogImage: OgImageConfig | false;
-};
-/**
- * Per-run closure state for the `build` plugin. Holds caches and config only —
- * no domain data is duplicated here (pulled fresh via `ctx.require` each run).
- *
- * @example
- * ```ts
- * const state: State = { config, manifest: null, buildCache: new Map(), runId: null, ogImageHashCache: new Map() };
- * ```
- */
-interface State$1 {
-  /** Resolved, frozen config snapshot. */
-  config: Config$1;
-  /** Cached route manifest for the current run (populated in Phase 3 from router). */
-  manifest: RouteDefinition[] | null;
-  /** Per-run build artifacts (e.g. hashed CSS/JS asset paths from Phase 1). */
-  buildCache: Map<string, unknown>;
-  /** Unique id for the current run (timestamp/uuid) — injected as build-id meta. */
-  runId: string | null;
-  /**
-   * Content-hash cache for OG images: slug -> sha256(title + template + size).
-   * Loaded from `<outDir>/.cache/og-images.json` at the OG phase and written back,
-   * so unchanged articles are skipped on the next run.
-   */
-  ogImageHashCache: Map<string, string>;
-}
-/**
- * Ordered names of the build pipeline phases, in execution order.
- *
- * @example
- * ```ts
- * const phase: PhaseName = "bundle";
- * ```
- */
-type PhaseName = "bundle" | "content" | "images" | "pages" | "feeds" | "sitemap" | "og-images" | "root-index";
-/**
- * Result of a completed build run.
- *
- * @example
- * ```ts
- * const result: BuildResult = { outDir: "./dist", pageCount: 12, durationMs: 840 };
- * ```
- */
-interface BuildResult {
-  /** Resolved output directory the site was written to. */
-  outDir: string;
-  /** Number of route pages rendered. */
-  pageCount: number;
-  /** Total wall-clock duration of the run, in milliseconds. */
-  durationMs: number;
-}
-/**
- * Public API surface mounted on `app.build`.
- *
- * @example
- * ```ts
- * const result = await app.build.run();
- * ```
- */
-type Api$1 = {
-  /**
-   * 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
-   * const result = await app.build.run({ outDir: "./preview" });
-   * ```
-   */
-  run(options?: {
-    outDir?: string;
-  }): Promise<BuildResult>;
-  /**
-   * List the phases in execution order (introspection / tooling).
-   *
-   * @returns The static ordered phase names.
-   * @example
-   * ```ts
-   * const order = app.build.phases();
-   * ```
-   */
-  phases(): PhaseName[];
-};
-declare namespace types_d_exports$7 {
-  export { COMPONENT_HOOK_NAMES, ComponentContext, ComponentDef, ComponentHooks, ComponentInstance, ExtractApi, PageData, ResolvedSpaConfig, SpaApi, SpaConfig, SpaContext, SpaEmitFunction, SpaEvents, SpaKernel, SpaKernelDeps, SpaRequire, SpaState };
-}
-/** Payload map for the events `spa` emits, used to type the kernel's `emit` closure. */
-type SpaEvents = {
-  /** A navigation has been intercepted and is starting. */"spa:navigate": {
-    from: string;
-    to: string;
-  }; /** The swap completed and the new URL is active. */
-  "spa:navigated": {
-    url: string;
-  }; /** A component instance attached to an element. */
-  "spa:component-mount": {
-    name: string;
-    el: Element;
-  }; /** A component instance detached from an element. */
-  "spa:component-unmount": {
-    name: string;
-    el: Element;
-  };
-};
-/** Strictly-typed emit closure for the spa events (kernel overload form). */
-type SpaEmitFunction = EmitFn<SpaEvents>;
-/**
- * Structural extraction of a plugin instance's public API from its `_phantom`
- * carrier (mirrors the kernel's non-exported `ExtractPluginApi`).
- *
- * @example
- * type RApi = ExtractApi<typeof routerPlugin>;
- */
-type ExtractApi<PluginCandidate> = PluginCandidate extends {
-  readonly _phantom: {
-    readonly api: infer PluginApi;
-  };
-} ? PluginApi : never;
 /** Generic `require` closure for pulling dependency plugin APIs at init time. */
 type SpaRequire = <PluginCandidate extends {
   readonly name: string;
@@ -1366,7 +1037,7 @@ type SpaRequire = <PluginCandidate extends {
     readonly api: unknown;
     readonly events: Record<string, unknown>;
   };
-}>(plugin: PluginCandidate) => ExtractApi<PluginCandidate>;
+}>(plugin: PluginCandidate) => ExtractApi$1<PluginCandidate>;
 /**
  * The plugin-context slice the spa wiring consumes in `onInit`/`onStart`:
  * mutable `state`, resolved `config`, `require`/`emit`/`log`. Structurally
@@ -1379,6 +1050,11 @@ interface SpaContext {
   readonly config: Readonly<SpaConfig>;
   /** Resolve a depended-upon plugin instance to its public API. */
   require: SpaRequire;
+  /**
+   * Whether a plugin is registered (by name). Used to detect the OPTIONAL `data`
+   * plugin at init — `spa` enables client DATA navigation only when `has("data")`.
+   */
+  has: (name: string) => boolean;
   /** Emit a spa lifecycle event (notification-only). */
   emit: SpaEmitFunction;
   /** Structured logger (core `log` API). */
@@ -1505,12 +1181,26 @@ interface ComponentInstance {
 }
 /** Page data payload parsed from the inline `script#__DATA__` element. */
 type PageData = Record<string, unknown>;
-/** Resolved dependency APIs the kernel reuses (router match/manifest, head compose). */
+/**
+ * The OPTIONAL `data` provider reader the kernel uses for client DATA navigation —
+ * a structural slice of the `data` plugin's API (fetch the persisted JSON for a
+ * page path). Captured at init via `ctx.has("data")`/`ctx.require` so `spa` never
+ * imports the `data` plugin or its types.
+ */
+type SpaDataReader = (path: string) => Promise<unknown | null>;
+/** Resolved dependency APIs the kernel reuses (router match/mode, head compose, optional data). */
 interface SpaKernelDeps {
-  /** Router plugin API — used for client-side route classification/matching. */
+  /** Router plugin API — used for client-side route matching (`match`) + the resolved `mode`. */
   router: RouterApi;
   /** Head plugin API — its pure compose is reused for client head-sync. */
-  head: Api$2;
+  head: Api$3;
+  /**
+   * The OPTIONAL `data` reader. Present only when the `data` plugin is composed.
+   * When present (and `router.mode() !== "ssg"`), navigation first tries the client
+   * DATA path (match → `dataAt(path)` → `route.parse` → `route.render`); otherwise
+   * it always uses HTML-over-fetch.
+   */
+  dataAt?: SpaDataReader;
 }
 /** The single shared SPA kernel — pure factory over state/config/emit/deps. */
 interface SpaKernel {
@@ -1540,76 +1230,774 @@ interface SpaKernel {
    */
   register(component: ComponentDef): void;
   /**
-   * Process a navigation to `path`: fetch then swap then head-sync then emit.
-   *
-   * @param path - The target path to navigate to.
-   * @returns void
-   * @example
-   * kernel.processNav("/about");
+   * Process a navigation to `path`: fetch then swap then head-sync then emit.
+   *
+   * @param path - The target path to navigate to.
+   * @returns void
+   * @example
+   * kernel.processNav("/about");
+   */
+  processNav(path: string): void;
+  /**
+   * Query the swap region and mount components for matching elements.
+   *
+   * @returns void
+   * @example
+   * kernel.scan();
+   */
+  scan(): void;
+  /**
+   * Tear down router listeners, run unmount/destroy, clear instances.
+   *
+   * @returns void
+   * @example
+   * kernel.dispose();
+   */
+  dispose(): void;
+}
+/** Internal mutable state for the spa plugin (all kernel data lives here). */
+interface SpaState {
+  /** Components registered by name (last-registered-wins). */
+  registeredComponents: Map<string, ComponentDef>;
+  /** Live component instances keyed by their bound element. */
+  instances: Map<Element, ComponentInstance>;
+  /** The current resolved URL (pathname + search). */
+  currentUrl: string;
+  /** Teardown handle for the attached router listeners (null when detached). */
+  destroyRouter: (() => void) | null;
+  /** Whether the browser runtime has been booted. */
+  started: boolean;
+  /** The single shared SPA kernel instance (null until onInit builds it). */
+  kernel: SpaKernel | null;
+}
+/** Public API of the spa plugin (registration / control surface). */
+type SpaApi = {
+  /**
+   * Register a component definition for client mounting.
+   *
+   * @param component - The component definition created via `createComponent`.
+   * @returns void
+   * @example
+   * app.spa.register(counter);
+   */
+  register(component: ComponentDef): void;
+  /**
+   * Programmatically navigate to a path (client runtime; no-op without a DOM).
+   *
+   * @param path - Target path (pathname, optionally with search/hash).
+   * @returns void
+   * @example
+   * app.spa.navigate("/about");
+   */
+  navigate(path: string): void;
+  /**
+   * Read the current resolved URL.
+   *
+   * @returns The current pathname + search.
+   * @example
+   * const url = app.spa.current(); // "/about"
+   */
+  current(): string;
+};
+declare namespace types_d_exports {
+  export { Api$2 as Api, BuildCacheEntry, BuildEvents, BuildResult, Config$2 as Config, ExtractApi, OgFont, OgImageConfig, OgPngRenderer, PhaseContext, PhaseEmit, PhaseLog, PhaseName, PhaseRequire, RichOgInput, State$2 as State };
+}
+/**
+ * Structural extraction of a plugin instance's public API from its `_phantom`
+ * carrier (mirrors the kernel's non-exported `ExtractPluginApi`) so the
+ * framework's generic `require` is assignable to {@link PhaseContext.require}.
+ *
+ * @example
+ * ```ts
+ * type ContentApi = ExtractApi<typeof contentPlugin>;
+ * ```
+ */
+type ExtractApi<PluginCandidate> = PluginCandidate extends {
+  readonly _phantom: {
+    readonly api: infer PluginApi;
+  };
+} ? PluginApi : never;
+/**
+ * Minimal logger slice used by the pipeline and phases (the core `log` API).
+ *
+ * @example
+ * ```ts
+ * const log: PhaseLog = { info: () => {}, debug: () => {}, warn: () => {}, error: () => {} };
+ * ```
+ */
+type PhaseLog = {
+  /** Record an informational event. */info(event: string, data?: unknown): void; /** Record a debug event. */
+  debug(event: string, data?: unknown): void; /** Record a warning event. */
+  warn(event: string, data?: unknown): void; /** Record an error event. */
+  error(event: string, data?: unknown): void;
+};
+/**
+ * Payload map for the events `build` emits, used to type the `emit` closure
+ * handed to the pipeline driver and phases.
+ *
+ * @example
+ * ```ts
+ * const emit: PhaseEmit = (name, payload) => kernel.emit(name, payload);
+ * ```
+ */
+type BuildEvents = {
+  /** Phase boundary marker (start, then done with durationMs). */"build:phase": {
+    phase: PhaseName;
+    status: "start" | "done";
+    durationMs?: number;
+  }; /** One successful-run summary. */
+  "build:complete": {
+    outDir: string;
+    pageCount: number;
+    durationMs: number;
+  };
+};
+/** Strictly-typed emit closure for the build events (kernel overload form). */
+type PhaseEmit = EmitFn<BuildEvents>;
+/** Generic `require` closure for pulling dependency plugin APIs at run time. */
+type PhaseRequire = <PluginCandidate extends {
+  readonly name: string;
+  readonly spec: unknown;
+  readonly _phantom: {
+    readonly config: unknown;
+    readonly state: unknown;
+    readonly api: unknown;
+    readonly events: Record<string, unknown>;
+  };
+}>(plugin: PluginCandidate) => ExtractApi<PluginCandidate>;
+/**
+ * The plugin-context slice the pipeline driver and every phase consume: the
+ * mutable `state`, the resolved `config`/`global`, plus `require`/`emit`/`log`.
+ * Typed to match the kernel's generic context so the framework execution
+ * context is structurally assignable.
+ *
+ * @example
+ * ```ts
+ * const ctx: PhaseContext = { state, config, global, require, emit, log };
+ * ```
+ */
+type PhaseContext = {
+  /** Mutable per-run build state (caches + runId). */state: State$2; /** Resolved, frozen build config. */
+  readonly config: Readonly<Config$2>; /** Global framework config (mode, etc.). */
+  readonly global: Readonly<{
+    mode: "production" | "development";
+  }>; /** Resolve a depended-upon plugin instance to its public API. */
+  require: PhaseRequire; /** Whether a plugin is registered (by name) — used to detect the OPTIONAL `data` plugin. */
+  has: (name: string) => boolean; /** Emit a build event (notification-only). */
+  emit: PhaseEmit; /** Structured logger (core `log` API). */
+  readonly log: PhaseLog;
+};
+/**
+ * Injectable PNG renderer for the og-images phase. Defaults to the real
+ * Satori → resvg pipeline; unit tests inject a fake to assert hash-cache skip
+ * and the `p-limit` bound without rasterizing real images.
+ *
+ * @example
+ * ```ts
+ * const render: OgPngRenderer = async () => new Uint8Array();
+ * ```
+ */
+type OgPngRenderer = (input: RichOgInput) => Promise<Uint8Array>;
+/**
+ * Rich input handed to a custom OG `render` hook for a single article card. Carries
+ * the full article + site metadata so a consumer can compose any layout. Returned by
+ * the framework, not authored by consumers directly.
+ *
+ * @example
+ * ```ts
+ * const input: RichOgInput = {
+ *   title: "Hello", description: "Intro", date: "2026-01-15", tags: ["a"],
+ *   locale: "en", siteName: "Blog", size: { width: 1200, height: 630 }
+ * };
+ * ```
+ */
+interface RichOgInput {
+  /** Article title rendered into the card. */
+  title: string;
+  /** Article description / summary. */
+  description: string;
+  /** Publication date (ISO string from frontmatter). */
+  date: string;
+  /** Article tags. */
+  tags: string[];
+  /** Optional author name. */
+  author?: string;
+  /** Active locale for the card. */
+  locale: string;
+  /** Site name (from the site plugin / config). */
+  siteName: string;
+  /** Output dimensions for the card. */
+  size: {
+    width: number;
+    height: number;
+  };
+}
+/**
+ * A single custom OG font entry. Each `path` is read to a Buffer ONCE per build and
+ * handed to Satori. `weight`/`style` default to `400`/`"normal"` when omitted.
+ *
+ * @example
+ * ```ts
+ * const font: OgFont = { name: "Inter", path: "./fonts/Inter.ttf", weight: 600 };
+ * ```
+ */
+interface OgFont {
+  /** Font family name referenced by the rendered card. */
+  name: string;
+  /** Path to the .ttf/.otf/.woff file. */
+  path: string;
+  /** Numeric weight (defaults to 400). */
+  weight?: number;
+  /** Font style (defaults to "normal"). */
+  style?: "normal" | "italic";
+}
+/**
+ * Optional OG-image generation config. Omit the field (or set `false`) to disable.
+ *
+ * The optional `render` hook (`@jsxImportSource preact`) lets a consumer return a
+ * Preact `VNode` for the card; the framework casts it to Satori's input at the single
+ * render boundary. `fonts` supplies multiple named fonts loaded once per build.
+ *
+ * @example
+ * ```ts
+ * const og: OgImageConfig = { fontDir: "./fonts" };
+ * ```
+ */
+interface OgImageConfig {
+  /** Directory containing at least one .ttf/.otf/.woff font. Validated in onInit (void — config check only). */
+  fontDir: string;
+  /** Optional path to a custom OG template module. Falls back to the built-in template. */
+  template?: string;
+  /** Output dimensions. Defaults to 1200x630. */
+  size?: {
+    width: number;
+    height: number;
+  };
+  /** Custom card renderer; returns a Preact `VNode` from the {@link RichOgInput}. */
+  render?(input: RichOgInput): import("preact").VNode;
+  /** Explicit named fonts loaded once per build (overrides the first-file scan). */
+  fonts?: OgFont[];
+}
+/**
+ * Public configuration for the `build` plugin. Flags give opt-in granularity over
+ * individual outputs without rewriting the pipeline.
+ *
+ * @example
+ * ```ts
+ * const config: Config = { outDir: "./dist", minify: true, feeds: true, sitemap: true, images: true, ogImage: false };
+ * ```
+ */
+type Config$2 = {
+  /** Output directory for the built site. */outDir: string; /** Minify bundled CSS/JS. */
+  minify: boolean; /** Generate RSS/Atom/JSON feeds. */
+  feeds: boolean; /** Generate sitemap.xml + robots.txt. */
+  sitemap: boolean; /** Optimize + copy content images. */
+  images: boolean; /** OG-image generation. `false` (or omitted) disables it; an object enables and configures it. */
+  ogImage: OgImageConfig | false; /** Auto-inject bundled `main.{css,js}` into rendered pages. Default `true`. */
+  injectAssets?: boolean; /** Directory copied verbatim into `outDir` (skipped silently if absent). Default `"public"`. */
+  publicDir?: string;
+  /**
+   * Emit `outDir/404.html`. `true` for the built-in default page, or
+   * `{ route }` to supply the page's literal HTML body content (NOT a route
+   * path/slug — the string is written into the 404 page verbatim). Default `false`.
+   */
+  notFound?: boolean | {
+    route?: string;
+  }; /** Emit per-path i18n bare-path redirect HTML pages. Default `false`. */
+  localeRedirects?: boolean; /** Authoritative client bundle entry path (overrides the conventional scan). */
+  clientEntry?: string; /** HTML shell template with `<!--moku:head-->`/`<!--moku:body-->`/`<!--moku:assets-->` placeholders. */
+  template?: string;
+};
+/**
+ * A typed asset-manifest entry for one bundled asset kind (CSS or JS): a map of the
+ * original entry basename to its hashed on-disk output path. Replaces the untyped
+ * `Map<string, unknown>` reads when emitting `<link>`/`<script>` tags in pages.tsx.
+ *
+ * @example
+ * ```ts
+ * const entry: BuildCacheEntry = { "main.css": "assets/main-abc123.css" };
+ * ```
+ */
+type BuildCacheEntry = Record<string, string>;
+/**
+ * Per-run closure state for the `build` plugin. Holds caches and config only —
+ * no domain data is duplicated here (pulled fresh via `ctx.require` each run).
+ *
+ * @example
+ * ```ts
+ * const state: State = { config, manifest: null, buildCache: new Map(), runId: null, ogImageHashCache: new Map() };
+ * ```
+ */
+interface State$2 {
+  /** Resolved, frozen config snapshot. */
+  config: Config$2;
+  /** Cached route manifest for the current run (populated in Phase 3 from router). */
+  manifest: RouteDefinition[] | null;
+  /** Per-run build artifacts (e.g. hashed CSS/JS asset paths from Phase 1). */
+  buildCache: Map<string, unknown>;
+  /** Unique id for the current run (timestamp/uuid) — injected as build-id meta. */
+  runId: string | null;
+  /**
+   * Content-hash cache for OG images: slug -> sha256(title + template + size).
+   * Loaded from `<outDir>/.cache/og-images.json` at the OG phase and written back,
+   * so unchanged articles are skipped on the next run.
+   */
+  ogImageHashCache: Map<string, string>;
+}
+/**
+ * Ordered names of the build pipeline phases, in execution order.
+ *
+ * @example
+ * ```ts
+ * const phase: PhaseName = "bundle";
+ * ```
+ */
+type PhaseName = "bundle" | "content" | "images" | "pages" | "feeds" | "sitemap" | "og-images" | "public" | "not-found" | "locale-redirects" | "root-index";
+/**
+ * Result of a completed build run.
+ *
+ * @example
+ * ```ts
+ * const result: BuildResult = { outDir: "./dist", pageCount: 12, durationMs: 840 };
+ * ```
+ */
+interface BuildResult {
+  /** Resolved output directory the site was written to. */
+  outDir: string;
+  /** Number of route pages rendered. */
+  pageCount: number;
+  /** Total wall-clock duration of the run, in milliseconds. */
+  durationMs: number;
+}
+/**
+ * Public API surface mounted on `app.build`.
+ *
+ * @example
+ * ```ts
+ * const result = await app.build.run();
+ * ```
+ */
+type Api$2 = {
+  /**
+   * 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
+   * const result = await app.build.run({ outDir: "./preview" });
+   * ```
+   */
+  run(options?: {
+    outDir?: string;
+  }): Promise<BuildResult>;
+  /**
+   * List the phases in execution order (introspection / tooling).
+   *
+   * @returns The static ordered phase names.
+   * @example
+   * ```ts
+   * const order = app.build.phases();
+   * ```
+   */
+  phases(): PhaseName[];
+};
+//#endregion
+//#region src/plugins/build/index.d.ts
+/**
+ * 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
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare const buildPlugin: import("@moku-labs/core").PluginInstance<"build", Config$2, State$2, Api$2, {
+  "build:phase": {
+    phase: PhaseName;
+    status: "start" | "done";
+    durationMs?: number;
+  };
+  "build:complete": {
+    outDir: string;
+    pageCount: number;
+    durationMs: number;
+  };
+}> & Record<never, never>;
+declare namespace types_d_exports$1 {
+  export { Api$1 as Api, Article, ArticleCard, ComputedFields, Config$1 as Config, ContentApiContext, ContentEvents, Frontmatter, State$1 as State };
+}
+/**
+ * Configuration for the content plugin.
+ *
+ * @example
+ * ```ts
+ * { contentDir: "./src/content", trustedContent: false, shikiTheme: "github-dark" }
+ * ```
+ */
+type Config$1 = {
+  /** Absolute or project-relative path to the content directory. Validated in onInit. */contentDir: string;
+  /**
+   * SECURITY GATE. When false (the default), rehype-sanitize runs as the final
+   * pipeline step. Set true ONLY for fully author-controlled Markdown — true
+   * disables sanitize and trusts all raw HTML.
+   */
+  trustedContent: boolean; /** Additional remark plugins, concatenated AFTER framework defaults. Defaults to []. */
+  extraRemarkPlugins?: readonly Pluggable[]; /** Additional rehype plugins, concatenated after custom transforms, before Shiki + sanitize. Defaults to []. */
+  extraRehypePlugins?: readonly Pluggable[]; /** Shiki theme name for syntax highlighting. Defaults to "github-dark". */
+  shikiTheme?: string; /** Author applied to articles whose frontmatter omits author. Defaults to undefined. */
+  defaultAuthor?: string;
+};
+/**
+ * Internal mutable state for the content plugin.
+ *
+ * @example
+ * ```ts
+ * { processor: null, articles: new Map(), slugs: null, dirtyPaths: new Set() }
+ * ```
+ */
+type State$1 = {
+  /** Lazily-created unified processor singleton. null until first render()/loadAll(). */processor: Processor | null; /** Article cache keyed locale -> (slug -> Article). Starts empty. */
+  articles: Map<string, Map<string, Article>>; /** Discovered, sorted slug list cached after first disk scan. null until first discovery. */
+  slugs: string[] | null; /** Paths marked stale by invalidate(); next loadAll() re-reads only these. Starts empty. */
+  dirtyPaths: Set<string>;
+};
+/**
+ * YAML frontmatter parsed from each article file.
+ *
+ * @example
+ * ```ts
+ * { title: "Hello", date: "2026-01-15", description: "Intro", tags: [], language: "en" }
+ * ```
+ */
+type Frontmatter = {
+  /** Article title. Required. */title: string; /** ISO 8601 date string, e.g. "2026-01-15". Required. */
+  date: string; /** Short summary used in cards, feeds, and meta description. Required. */
+  description: string; /** Topic tags. Required (may be empty array). */
+  tags: string[]; /** Source language code of this file. Required. */
+  language: string; /** Draft flag. Excluded from output in production mode. Defaults to false. */
+  draft?: boolean; /** Author name. Falls back to config.defaultAuthor when omitted. */
+  author?: string;
+};
+/**
+ * Fields computed by the pipeline (not authored in frontmatter).
+ *
+ * @example
+ * ```ts
+ * { slug: "hello", readingTime: 1, contentId: "hello", status: "published", wordCount: 42 }
+ * ```
+ */
+type ComputedFields = {
+  /** Article directory name. */slug: string; /** Reading time in minutes (ceiling, minimum 1). */
+  readingTime: number; /** Stable content identifier (slug by default). */
+  contentId: string; /** Derived publication status. */
+  status: "published" | "draft"; /** Word count from the source body. */
+  wordCount: number;
+};
+/**
+ * A fully processed, render-ready article.
+ *
+ * @example
+ * ```ts
+ * { frontmatter, computed, html: "<p>…</p>", locale: "en", isFallback: false, url: "/en/hello/" }
+ * ```
+ */
+type Article = {
+  /** Parsed frontmatter. */frontmatter: Frontmatter; /** Pipeline-computed metadata. */
+  computed: ComputedFields; /** Sanitized rendered HTML body. */
+  html: string; /** Locale this Article instance represents (the requested locale, even on fallback). */
+  locale: string; /** True when the default-locale file was used because the requested locale was missing. */
+  isFallback: boolean; /** Canonical URL for this article in this locale. */
+  url: string;
+};
+/**
+ * Lightweight projection of Article for cards/lists.
+ *
+ * @example
+ * ```ts
+ * { contentId: "hello", status: "published", title: "Hello", date: "2026-01-15", description: "Intro", tags: [], readingTime: 1, url: "/en/hello/" }
+ * ```
+ */
+type ArticleCard = {
+  /** Stable content identifier. */contentId: string; /** Derived publication status. */
+  status: "published" | "draft"; /** Article title. */
+  title: string; /** ISO 8601 date string. */
+  date: string; /** Short summary. */
+  description: string; /** Topic tags. */
+  tags: string[]; /** Reading time in minutes. */
+  readingTime: number; /** Canonical URL for this article in this locale. */
+  url: string;
+};
+/**
+ * Notification-only events emitted by the content plugin.
+ *
+ * @example
+ * ```ts
+ * emit("content:ready", { locales: ["en"], articleCount: 3 });
+ * ```
+ */
+type ContentEvents = {
+  /** All articles loaded across locales. */"content:ready": {
+    locales: readonly string[];
+    articleCount: number;
+  }; /** Article paths marked stale for dev rebuild. */
+  "content:invalidated": {
+    paths: readonly string[];
+  };
+};
+/**
+ * Kernel-free domain context handed to createContentApi by the wiring harness.
+ * Carries ctx.state (mutable escape hatch), config, global, emit, and the
+ * i18n-derived locale/url helpers — so api.ts stays free of createPlugin/ctx.
+ *
+ * @example
+ * ```ts
+ * const apiContext: ContentApiContext = { state, config, global, emit, locales, defaultLocale, articleToUrl };
+ * ```
+ */
+type ContentApiContext = {
+  /** Mutable plugin state (article cache + lazy processor). */state: State$1; /** Resolved plugin configuration. */
+  config: Config$1; /** Global framework configuration (mode, etc.). */
+  global: {
+    mode: "production" | "development";
+  }; /** Emit a registered content event. */
+  emit: <K extends keyof ContentEvents>(event: K, payload: ContentEvents[K]) => void; /** Active locale codes from i18n. */
+  locales: () => readonly string[]; /** Default locale code from i18n (fallback source). */
+  defaultLocale: () => string; /** Build a canonical article URL for a locale + slug. */
+  articleToUrl: (locale: string, slug: string) => string;
+};
+/**
+ * Public API for the content plugin.
+ *
+ * @example
+ * ```ts
+ * const map = await app.content.loadAll();
+ * ```
+ */
+type Api$1 = {
+  /**
+   * Load every article across every active locale, returning a locale-keyed
+   * map of date-descending Article arrays. Emits content:ready.
+   */
+  loadAll(): Promise<Map<string, Article[]>>;
+  /**
+   * Resolve and render a single article for one locale, with locale fallback.
+   *
+   * @param slug - Article directory name.
+   * @param locale - Requested locale code.
+   */
+  load(slug: string, locale: string): Promise<Article>;
+  /**
+   * Render a raw Markdown string to HTML through the full pipeline.
+   *
+   * @param md - Raw Markdown source.
+   */
+  renderMarkdown(md: string): Promise<string>;
+  /**
+   * Mark file paths stale for incremental dev rebuilds. Emits content:invalidated.
+   *
+   * @param paths - File paths to invalidate.
+   */
+  invalidate(paths: readonly string[]): void;
+  /**
+   * Project a full Article to a lightweight ArticleCard for list/grid rendering.
+   *
+   * @param article - The source article.
+   */
+  articleToCard(article: Article): ArticleCard;
+};
+//#endregion
+//#region src/plugins/content/index.d.ts
+/**
+ * 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
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare const contentPlugin: import("@moku-labs/core").PluginInstance<"content", Config$1, State$1, Api$1, {
+  "content:ready": {
+    locales: readonly string[];
+    articleCount: number;
+  };
+  "content:invalidated": {
+    paths: readonly string[];
+  };
+}> & Record<never, never>;
+declare namespace types_d_exports$2 {
+  export { DataConfig, DataEntry, DataProvider, DataState, DataWriteSummary };
+}
+/**
+ * @file data plugin — type definitions (Standard tier).
+ *
+ * The `data` plugin is the **agnostic data provider** for the SSG→DATA→SPA pattern.
+ * It owns ONE thing: the contract `page path → persisted JSON file`. It knows
+ * NOTHING about what the data *is* — no domain types appear here. A route decides
+ * its own data shape (`load`'s return) and its own validation (`route.parse`).
+ *
+ *  - **Node (build):** `write(entries)` persists one JSON file per page, keyed by
+ *    the page's URL via {@link DataProvider.fileFor}. `build` supplies the entries
+ *    (it already expanded the routes), so there is no duplicate expansion here.
+ *  - **Browser (runtime):** `at(path)` fetches + caches that file as `unknown`; the
+ *    route's `parse` validates it into the route's data type before `render`.
+ *
+ * The Node-only file-writing code (`node:fs`) is isolated behind a lazy `import()`
+ * inside `write()`, so composing `data` in a browser app keeps the bundle free of
+ * `node:*`.
+ */
+/**
+ * Configuration for {@link dataPlugin}. All fields have defaults (see `./config`).
+ *
+ * @example
+ * ```ts
+ * const cfg: DataConfig = { outputDir: "_data", baseUrl: "/_data/" };
+ * ```
+ */
+type DataConfig = {
+  /**
+   * WRITE side (Node): output subdir relative to the build `outDir`, a filesystem
+   * path where `write()` persists the per-page JSON. Default `"_data"`.
    */
-  processNav(path: string): void;
+  outputDir: string;
   /**
-   * Query the swap region and mount components for matching elements.
-   *
-   * @returns void
-   * @example
-   * kernel.scan();
+   * READ side (browser): site-root-relative URL the client fetches the per-page
+   * JSON from. A different domain from {@link DataConfig.outputDir} (a filesystem
+   * path); keep consistent (`"/" + trim(outputDir) + "/"`). Default `"/_data/"`.
    */
-  scan(): void;
+  baseUrl: string;
+};
+/** One page's data to persist — `build` produces these from its route expansion. */
+interface DataEntry {
+  /** The page's URL path (e.g. `/en/hello/`); maps to a file via {@link DataProvider.fileFor}. */
+  path: string;
+  /** The serializable data for this page (the route's `load`/projection output). */
+  data: unknown;
+}
+/** Summary returned by {@link DataProvider.write} and cached in state. */
+interface DataWriteSummary {
+  /** Number of per-page JSON files written. */
+  fileCount: number;
+  /** Total bytes written across all files. */
+  bytes: number;
+  /** The written file paths, relative to the build `outDir`. */
+  files: string[];
+}
+/**
+ * Internal data state. `lastWrite` records the most recent `write()` (Node);
+ * `cache` memoizes fetched per-path data (browser, lazy). Both empty until their
+ * respective side first runs.
+ */
+interface DataState {
+  /** Result of the last `write()`, or `null` if it has not run yet (Node). */
+  lastWrite: DataWriteSummary | null;
+  /** Per-path fetched data, cached after the first `at(path)` (browser). */
+  cache: Map<string, unknown>;
+}
+/**
+ * Public API mounted at `app.data` — the agnostic data provider. `write()` is the
+ * Node persist side; `at()` is the browser read side; `urlFor`/`fileFor` are the
+ * pure URL convention shared by both so the written file and fetched URL can never
+ * drift.
+ *
+ * @example
+ * ```ts
+ * // Node build (build supplies the entries it already expanded):
+ * await app.data.write([{ path: "/en/hello/", data: article }]);
+ *
+ * // Browser (inside spa nav): fetch the page's data, then route.parse validates it:
+ * const raw = await app.data.at("/en/hello/"); // unknown | null
+ * ```
+ */
+type DataProvider = {
   /**
-   * Tear down router listeners, run unmount/destroy, clear instances.
+   * READ (browser) — fetch (and cache) the persisted data for a page path from
+   * `config.baseUrl`. Returns the raw parsed JSON as `unknown` (the caller's
+   * `route.parse` validates it), or `null` if the fetch/parse fails.
    *
-   * @returns void
-   * @example
-   * kernel.dispose();
+   * @param path - The page URL path (e.g. `/en/hello/`).
+   * @returns The page's raw data, or `null` on failure.
    */
-  dispose(): void;
-}
-/** Internal mutable state for the spa plugin (all kernel data lives here). */
-interface SpaState {
-  /** Components registered by name (last-registered-wins). */
-  registeredComponents: Map<string, ComponentDef>;
-  /** Live component instances keyed by their bound element. */
-  instances: Map<Element, ComponentInstance>;
-  /** The current resolved URL (pathname + search). */
-  currentUrl: string;
-  /** Teardown handle for the attached router listeners (null when detached). */
-  destroyRouter: (() => void) | null;
-  /** Whether the browser runtime has been booted. */
-  started: boolean;
-  /** The single shared SPA kernel instance (null until onInit builds it). */
-  kernel: SpaKernel | null;
-}
-/** Public API of the spa plugin (registration / control surface). */
-type SpaApi = {
+  at(path: string): Promise<unknown | null>;
   /**
-   * Register a component definition for client mounting.
+   * WRITE (Node) — persist one JSON file per entry, keyed by page path via
+   * {@link DataProvider.fileFor}. Called by `build` after it expands routes (no
+   * duplicate expansion). Lazily loads its `node:fs` writer, so it never
+   * contaminates a browser bundle.
    *
-   * @param component - The component definition created via `createComponent`.
-   * @returns void
-   * @example
-   * app.spa.register(counter);
+   * @param entries - The per-page data to persist.
+   * @param options - Optional overrides.
+   * @param options.outDir - Build output directory to write under (default `./dist`).
+   * @returns A summary of the written files.
    */
-  register(component: ComponentDef): void;
+  write(entries: readonly DataEntry[], options?: {
+    outDir?: string;
+  }): Promise<DataWriteSummary>;
   /**
-   * Programmatically navigate to a path (client runtime; no-op without a DOM).
+   * PURE — the browser fetch URL for a page path (e.g. `/en/hello/` →
+   * `/_data/en/hello/index.json`). Shared with {@link DataProvider.fileFor}.
    *
-   * @param path - Target path (pathname, optionally with search/hash).
-   * @returns void
-   * @example
-   * app.spa.navigate("/about");
+   * @param path - The page URL path.
+   * @returns The site-root-relative data URL.
    */
-  navigate(path: string): void;
+  urlFor(path: string): string;
   /**
-   * Read the current resolved URL.
+   * PURE — the `outDir`-relative file path for a page path (e.g. `/en/hello/` →
+   * `_data/en/hello/index.json`). Shared with {@link DataProvider.urlFor}.
    *
-   * @returns The current pathname + search.
-   * @example
-   * const url = app.spa.current(); // "/about"
+   * @param path - The page URL path.
+   * @returns The output-relative file path.
    */
-  current(): string;
+  fileFor(path: string): string;
 };
-declare namespace types_d_exports$2 {
+//#endregion
+//#region src/plugins/data/index.d.ts
+/**
+ * Data plugin — the agnostic data provider. Mounts `write(entries)` (Node persist),
+ * `at(path)` (browser read), and the pure `urlFor`/`fileFor` convention at `app.data`.
+ *
+ * @example
+ * ```ts
+ * // Node build: `build` calls app.data.write(...) during its pages phase when
+ * // router.mode !== "ssg". Just compose the plugin:
+ * const app = createApp({
+ *   plugins: [dataPlugin, contentPlugin, buildPlugin],
+ *   pluginConfigs: { content: { contentDir: "./content" }, router: { routes, mode: "hybrid" } }
+ * });
+ * await app.start();
+ * await app.build.run();   // writes HTML + per-page data sidecars
+ *
+ * // Browser app: compose `dataPlugin` too; spa fetches via app.data.at(path) on nav.
+ * ```
+ */
+declare const dataPlugin: import("@moku-labs/core").PluginInstance<"data", DataConfig, DataState, DataProvider, {}> & Record<never, never>;
+declare namespace types_d_exports$3 {
   export { Api, Config, DeployErrorCode, DeployInitOptions, DeployResult, DeployRunOptions, InitResult, SpawnFunction, SpawnOptions, SpawnedProcess, State, WranglerErrorKind };
 }
 /**
@@ -1797,6 +2185,24 @@ type Api = {
  * 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"
+ *     }
+ *   }
+ * });
+ * ```
+ */
 declare const deployPlugin: import("@moku-labs/core").PluginInstance<"deploy", Config, State, Api, {
   "deploy:complete": {
     url: string;
@@ -1806,31 +2212,6 @@ declare const deployPlugin: import("@moku-labs/core").PluginInstance<"deploy", C
   };
 }> & Record<never, never>;
 //#endregion
-//#region src/plugins/build/index.d.ts
-declare const buildPlugin: import("@moku-labs/core").PluginInstance<"build", Config$1, State$1, Api$1, {
-  "build:phase": {
-    phase: PhaseName;
-    status: "start" | "done";
-    durationMs?: number;
-  };
-  "build:complete": {
-    outDir: string;
-    pageCount: number;
-    durationMs: number;
-  };
-}> & Record<never, never>;
-//#endregion
-//#region src/plugins/content/index.d.ts
-declare const contentPlugin: import("@moku-labs/core").PluginInstance<"content", Config$3, State$3, Api$3, {
-  "content:ready": {
-    locales: readonly string[];
-    articleCount: number;
-  };
-  "content:invalidated": {
-    paths: readonly string[];
-  };
-}> & Record<never, never>;
-//#endregion
 //#region src/plugins/head/primitives.d.ts
 /**
  * Build a `<meta name=… content=…>` descriptor.
@@ -1910,7 +2291,26 @@ declare function feedLink(title: string, url: string, type?: string): HeadElemen
 declare function buildArticleHead(articleMeta: ArticleMeta, canonicalUrl: string): HeadElement[];
 //#endregion
 //#region src/plugins/head/index.d.ts
-declare const headPlugin: import("@moku-labs/core").PluginInstance<"head", Config$2, State$2, Api$2, {}> & {
+/**
+ * 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"
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare const headPlugin: import("@moku-labs/core").PluginInstance<"head", Config$3, State$3, Api$3, {}> & {
   meta: typeof meta;
   og: typeof og;
   twitter: typeof twitter;
@@ -1922,6 +2322,25 @@ declare const headPlugin: import("@moku-labs/core").PluginInstance<"head", Confi
 };
 //#endregion
 //#region src/plugins/i18n/index.d.ts
+/**
+ * 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.
+ *
+ * @example Register locales and translations
+ * ```ts
+ * const app = createApp({
+ *   pluginConfigs: {
+ *     i18n: {
+ *       locales: ["en", "uk"],
+ *       defaultLocale: "en",
+ *       localeNames: { en: "English", uk: "Українська" },
+ *       translations: { uk: { "nav.home": "Головна" } }
+ *     }
+ *   }
+ * });
+ * ```
+ */
 declare const i18nPlugin: import("@moku-labs/core").PluginInstance<"i18n", Config$5, Record<string, never>, Api$5, {}> & Record<never, never>;
 //#endregion
 //#region src/plugins/log/index.d.ts
@@ -1967,15 +2386,74 @@ declare function route<P extends string>(pattern: P): RouteBuilder<RouteState<P>
 declare function defineRoutes<T extends RouteMap>(routes: T): T;
 //#endregion
 //#region src/plugins/router/index.d.ts
+/**
+ * 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)
+ *     }
+ *   }
+ * });
+ * ```
+ */
 declare const routerPlugin: import("@moku-labs/core").PluginInstance<"router", RouterConfig, RouterState, RouterApi, {}> & {
   route: typeof route;
   defineRoutes: typeof defineRoutes;
 };
 //#endregion
 //#region src/plugins/site/index.d.ts
+/**
+ * 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`).
+ *
+ * @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"
+ *     }
+ *   }
+ * });
+ * ```
+ */
 declare const sitePlugin: import("@moku-labs/core").PluginInstance<"site", Config$6, Record<string, never>, Api$6, {}> & Record<never, never>;
 //#endregion
 //#region src/plugins/spa/index.d.ts
+/**
+ * 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
+ *     }
+ *   }
+ * });
+ * ```
+ */
 declare const spaPlugin: import("@moku-labs/core").PluginInstance<"spa", SpaConfig, SpaState, SpaApi, {
   "spa:navigate": {
     from: string;
@@ -1994,115 +2472,150 @@ declare const spaPlugin: import("@moku-labs/core").PluginInstance<"spa", SpaConf
   };
 }> & Record<never, never>;
 //#endregion
+//#region src/plugins/env/providers.d.ts
+/**
+ * A zero-dependency `.env`-style provider that re-reads and re-parses the file
+ * from disk on every `load()`. Missing file resolves to `{}` (optional
+ * overrides). Strips a single outer quote pair; does not strip trailing inline
+ * comments on unquoted values.
+ *
+ * @param path - Path to the dotenv file. Defaults to `.env.local`.
+ * @returns An {@link EnvProvider} named `dotenv:<path>` that reads fresh per call.
+ * @example
+ * ```ts
+ * const provider = dotenv(".env.local");
+ * provider.load(); // { PUBLIC_API_URL: "/api", ... }
+ * ```
+ */
+declare function dotenv(path?: string): EnvProvider;
+/**
+ * A provider that returns a shallow copy of `process.env` at `load()` time.
+ *
+ * @returns An {@link EnvProvider} named `process-env`.
+ * @example
+ * ```ts
+ * const provider = processEnv();
+ * provider.load().HOME; // current process value
+ * ```
+ */
+declare function processEnv(): EnvProvider;
+/**
+ * A provider that reads live, per-request Cloudflare bindings from
+ * `globalThis.__CLOUDFLARE_ENV__` at `load()` time (`?? {}` when absent). Never
+ * caches the binding object; the consumer owns the global's request lifecycle.
+ *
+ * @returns An {@link EnvProvider} named `cloudflare`.
+ * @example
+ * ```ts
+ * globalThis.__CLOUDFLARE_ENV__ = env; // set by the request handler
+ * const provider = cloudflareBindings();
+ * provider.load(); // reads the current request's bindings
+ * ```
+ */
+declare function cloudflareBindings(): EnvProvider;
+//#endregion
 //#region src/index.d.ts
+/**
+ * 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.
+ *
+ * The defaults are the isomorphic plugin set (`site`, `i18n`, `router`, `head`,
+ * `spa` + `log`/`env` core). Add the Node-only plugins for an SSG build:
+ * `createApp({ plugins: [contentPlugin, buildPlugin, deployPlugin] })`.
+ *
+ * @param options - Optional configuration:
+ *  - `pluginConfigs` — per-plugin overrides, keyed by plugin name.
+ *  - `config` — global framework config (e.g. `{ mode: "development" }`).
+ *  - `plugins` — extra plugins (Node-only built-ins or your own) merged into the app and its type.
+ *  - `onReady` / `onError` / `onStart` / `onStop` — lifecycle callbacks.
+ * @returns The initialized app: `start()`, `stop()`, every plugin's API, and `log`.
+ * @example
+ * ```ts
+ * // Node SSG build — add the node-only plugins:
+ * const app = createApp({
+ *   plugins: [contentPlugin, buildPlugin, deployPlugin],
+ *   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();
+ * await app.build.run();
+ * ```
+ */
 declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs/core").AnyPluginInstance[] = readonly []>(options?: import("@moku-labs/core").CreateAppOptions<Config$7, Events, (import("@moku-labs/core").PluginInstance<"site", Config$6, Record<string, never>, Api$6, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"i18n", Config$5, Record<string, never>, Api$5, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"router", RouterConfig, RouterState, RouterApi, {}> & {
-    route: typeof route;
-    defineRoutes: typeof defineRoutes;
-  }) | (import("@moku-labs/core").PluginInstance<"content", Config$3, State$3, Api$3, {
-    "content:ready": {
-      locales: readonly string[];
-      articleCount: number;
-    };
-    "content:invalidated": {
-      paths: readonly string[];
-    };
-  }> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"head", Config$2, State$2, Api$2, {}> & {
-    meta: typeof meta;
-    og: typeof og;
-    twitter: typeof twitter;
-    jsonLd: typeof jsonLd;
-    canonical: typeof canonical;
-    hreflang: typeof hreflang;
-    feedLink: typeof feedLink;
-    buildArticleHead: typeof buildArticleHead;
-  }) | (import("@moku-labs/core").PluginInstance<"build", Config$1, State$1, Api$1, {
-    "build:phase": {
-      phase: PhaseName;
-      status: "start" | "done";
-      durationMs?: number;
-    };
-    "build:complete": {
-      outDir: string;
-      pageCount: number;
-      durationMs: number;
-    };
-  }> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"spa", SpaConfig, SpaState, SpaApi, {
-    "spa:navigate": {
-      from: string;
-      to: string;
-    };
-    "spa:navigated": {
-      url: string;
-    };
-    "spa:component-mount": {
-      name: string;
-      el: Element;
-    };
-    "spa:component-unmount": {
-      name: string;
-      el: Element;
-    };
-  }> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"deploy", Config, State, Api, {
-    "deploy:complete": {
-      url: string;
-      deploymentId: string;
-      branch: string;
-      durationMs: number;
-    };
-  }> & Record<never, never>) | ExtraPlugins[number], [...ExtraPlugins], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", LogConfig, LogState, LogApi>, import("@moku-labs/core").CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>]>> | undefined) => import("@moku-labs/core").App<Config$7, Events, (import("@moku-labs/core").PluginInstance<"site", Config$6, Record<string, never>, Api$6, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"i18n", Config$5, Record<string, never>, Api$5, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"router", RouterConfig, RouterState, RouterApi, {}> & {
-    route: typeof route;
-    defineRoutes: typeof defineRoutes;
-  }) | (import("@moku-labs/core").PluginInstance<"content", Config$3, State$3, Api$3, {
-    "content:ready": {
-      locales: readonly string[];
-      articleCount: number;
-    };
-    "content:invalidated": {
-      paths: readonly string[];
-    };
-  }> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"head", Config$2, State$2, Api$2, {}> & {
-    meta: typeof meta;
-    og: typeof og;
-    twitter: typeof twitter;
-    jsonLd: typeof jsonLd;
-    canonical: typeof canonical;
-    hreflang: typeof hreflang;
-    feedLink: typeof feedLink;
-    buildArticleHead: typeof buildArticleHead;
-  }) | (import("@moku-labs/core").PluginInstance<"build", Config$1, State$1, Api$1, {
-    "build:phase": {
-      phase: PhaseName;
-      status: "start" | "done";
-      durationMs?: number;
-    };
-    "build:complete": {
-      outDir: string;
-      pageCount: number;
-      durationMs: number;
-    };
-  }> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"spa", SpaConfig, SpaState, SpaApi, {
-    "spa:navigate": {
-      from: string;
-      to: string;
-    };
-    "spa:navigated": {
-      url: string;
-    };
-    "spa:component-mount": {
-      name: string;
-      el: Element;
-    };
-    "spa:component-unmount": {
-      name: string;
-      el: Element;
-    };
-  }> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"deploy", Config, State, Api, {
-    "deploy:complete": {
-      url: string;
-      deploymentId: string;
-      branch: string;
-      durationMs: number;
-    };
-  }> & Record<never, never>) | ExtraPlugins[number], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", LogConfig, LogState, LogApi>, import("@moku-labs/core").CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>]>>, createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<Config$7, Events, import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", LogConfig, LogState, LogApi>, import("@moku-labs/core").CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>]>>;
+  route: typeof route;
+  defineRoutes: typeof defineRoutes;
+}) | (import("@moku-labs/core").PluginInstance<"head", Config$3, State$3, Api$3, {}> & {
+  meta: typeof meta;
+  og: typeof og;
+  twitter: typeof twitter;
+  jsonLd: typeof jsonLd;
+  canonical: typeof canonical;
+  hreflang: typeof hreflang;
+  feedLink: typeof feedLink;
+  buildArticleHead: typeof buildArticleHead;
+}) | (import("@moku-labs/core").PluginInstance<"spa", SpaConfig, SpaState, SpaApi, {
+  "spa:navigate": {
+    from: string;
+    to: string;
+  };
+  "spa:navigated": {
+    url: string;
+  };
+  "spa:component-mount": {
+    name: string;
+    el: Element;
+  };
+  "spa:component-unmount": {
+    name: string;
+    el: Element;
+  };
+}> & Record<never, never>) | ExtraPlugins[number], [...ExtraPlugins], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", LogConfig, LogState, LogApi>, import("@moku-labs/core").CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>]>> | undefined) => import("@moku-labs/core").App<Config$7, Events, (import("@moku-labs/core").PluginInstance<"site", Config$6, Record<string, never>, Api$6, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"i18n", Config$5, Record<string, never>, Api$5, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"router", RouterConfig, RouterState, RouterApi, {}> & {
+  route: typeof route;
+  defineRoutes: typeof defineRoutes;
+}) | (import("@moku-labs/core").PluginInstance<"head", Config$3, State$3, Api$3, {}> & {
+  meta: typeof meta;
+  og: typeof og;
+  twitter: typeof twitter;
+  jsonLd: typeof jsonLd;
+  canonical: typeof canonical;
+  hreflang: typeof hreflang;
+  feedLink: typeof feedLink;
+  buildArticleHead: typeof buildArticleHead;
+}) | (import("@moku-labs/core").PluginInstance<"spa", SpaConfig, SpaState, SpaApi, {
+  "spa:navigate": {
+    from: string;
+    to: string;
+  };
+  "spa:navigated": {
+    url: string;
+  };
+  "spa:component-mount": {
+    name: string;
+    el: Element;
+  };
+  "spa:component-unmount": {
+    name: string;
+    el: Element;
+  };
+}> & Record<never, never>) | ExtraPlugins[number], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", LogConfig, LogState, LogApi>, import("@moku-labs/core").CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>]>>;
+/**
+ * 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] });
+ * ```
+ */
+declare const createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<Config$7, Events, import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", LogConfig, LogState, LogApi>, import("@moku-labs/core").CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>]>>;
 //#endregion
-export { types_d_exports as Build, types_d_exports$1 as Content, types_d_exports$2 as Deploy, types_d_exports$3 as Env, types_d_exports$4 as Head, types_d_exports$5 as Log, types_d_exports$6 as Router, types_d_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_d_exports as Build, types_d_exports$1 as Content, types_d_exports$2 as Data, types_d_exports$3 as Deploy, types_d_exports$4 as Env, types_d_exports$5 as Head, types_d_exports$6 as Log, types_d_exports$7 as Router, types_d_exports$8 as Spa, browserEnv, buildArticleHead, buildPlugin, canonical, cloudflareBindings, contentPlugin, createApp, createPlugin, dataPlugin, defineRoutes, deployPlugin, dotenv, envPlugin, feedLink, headPlugin, hreflang, i18nPlugin, jsonLd, logPlugin, meta, og, processEnv, route, routerPlugin, sitePlugin, spaPlugin, twitter };