@moku-labs/web 0.5.6 → 1.0.0

package/dist/index.d.mts

@@ -1,10 +1,10 @@
 import { EmitFn } from "@moku-labs/core";
-import { Pluggable, Processor } from "unified";
 import { ComponentChildren, VNode } from "preact";
+import { Pluggable, Processor } from "unified";
 import { BundledTheme, ThemeRegistrationAny } from "shiki";
 
 //#region src/plugins/log/types.d.ts
-declare namespace types_d_exports$6 {
+declare namespace types_d_exports$7 {
   export { ExpectChain, LogApi, LogConfig, LogEntry, LogLevel, LogSink, LogState };
 }
 /**
@@ -144,7 +144,7 @@ type LogApi = {
   addSink(sink: LogSink): void; /** Clear all recorded entries while keeping registered sinks. */
   reset(): void;
 };
-declare namespace types_d_exports$4 {
+declare namespace types_d_exports$5 {
   export { EnvApi, EnvConfig, EnvProvider, EnvState, EnvVarSpec };
 }
 /**
@@ -155,8 +155,9 @@ declare namespace types_d_exports$4 {
  *
  * Providers are walked in array order during resolution; the first provider to
  * return a non-`undefined` (and non-empty-string) value for a key wins. `load()`
- * is called once per resolution at `onInit` time — except for live, per-request
- * sources (e.g. {@link cloudflareBindings}) which read fresh on every call.
+ * is called exactly once per resolution at `onInit` time, after which both env
+ * maps are frozen. A provider like {@link cloudflareBindings} reads `globalThis`
+ * at that single `onInit` call (not per request).
  *
  * @example
  * ```ts
@@ -227,7 +228,8 @@ type EnvConfig = {
   /**
    * Ordered list of value sources. The first provider yielding a non-`undefined`
    * (and non-empty-string) value for a key wins. The plugin's own spec default is
-   * `[]`; the framework layer supplies the working default `[dotenv(), processEnv()]`.
+   * `[]`; the consumer supplies the providers per target (`[dotenv(), processEnv()]`
+   * on Node) — only the `/browser` entry pre-wires `browserEnv()` out of the box.
    */
   providers: EnvProvider[];
   /**
@@ -336,12 +338,25 @@ declare function browserEnv(options?: {
 declare const envPlugin: import("@moku-labs/core").CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>;
 //#endregion
 //#region src/config.d.ts
+/**
+ * Deployment stage. Drives content draft visibility — drafts are suppressed
+ * only in `"production"`; `"development"` and `"test"` both surface them.
+ */
+type Stage = "production" | "development" | "test";
 /**
  * Global framework configuration. Minimal by design — per-plugin config is
  * resolved via `pluginConfigs`, not merged here.
  */
-type Config$7 = {
-  /** Runtime mode. Drives log sink defaults, content draft filtering, build minify. */mode: "production" | "development";
+type Config$8 = {
+  /** Deployment stage. Drives content draft visibility (drafts hidden only in `"production"`). */stage: Stage;
+  /**
+   * Render mode — the single SSG/DATA/SPA switch, read by the router (`ctx.global`)
+   * and consumed by `build`/`spa` via `router.mode()`.
+   * - `"ssg"` static generation only (no client router emitted).
+   * - `"spa"` client-side routing only.
+   * - `"hybrid"` static HTML + client navigation overlay (default).
+   */
+  mode: "ssg" | "spa" | "hybrid";
 };
 /**
  * Framework event contract. Empty base — each plugin declares its own events
@@ -375,7 +390,7 @@ type Events = {};
  * });
  * ```
  */
-type Config$6 = {
+type Config$7 = {
   /** Human-readable site name. Used in feeds, og:site_name, and titles. MUST be non-empty. */name: string; /** Absolute base URL of the site, e.g. "https://blog.dev". MUST be a valid absolute URL (http/https). */
   url: string; /** Default author/byline for the site. Used in feeds and article author meta. */
   author: string; /** Short site description. Used in feeds, the default meta description, and og:description fallbacks. */
@@ -385,7 +400,7 @@ type Config$6 = {
  * Public API of the site plugin — read-only accessors over frozen global
  * site metadata, plus canonical URL construction.
  */
-type Api$6 = {
+type Api$7 = {
   /**
    * Returns the configured site name.
    *
@@ -446,7 +461,7 @@ type Api$6 = {
  * @file i18n plugin — public type definitions (Config + Api).
  */
 /**
- * i18n plugin configuration. Mirrors the legacy `I18nConfig` shape.
+ * i18n plugin configuration.
  *
  * `locales` and `defaultLocale` are required and validated in `onInit`. The
  * optional maps default to empty objects so every lookup method is total —
@@ -463,7 +478,7 @@ type Api$6 = {
  * }
  * ```
  */
-type Config$5 = {
+type Config$6 = {
   readonly locales: readonly string[];
   readonly defaultLocale: string;
   readonly localeNames?: Record<string, string>;
@@ -474,7 +489,7 @@ type Config$5 = {
  * Public API of the i18n plugin. Injected as `app.i18n` and reachable from
  * other plugins via `ctx.require(i18nPlugin)`.
  */
-type Api$5 = {
+type Api$6 = {
   /**
    * Returns the configured supported locales in declared order.
    *
@@ -542,8 +557,8 @@ type Api$5 = {
    */
   t(locale: string, key: string): string;
 };
-declare namespace types_d_exports$7 {
-  export { Api$4 as Api, ClientRoute, CompileInput, CompiledRoute, Config$4 as Config, ExtractRouteParams, ExtractSegmentParameter, HeadConfig$1 as HeadConfig, LayoutContext, MatcherTable, Prettify, RouteBuilder, RouteContext, RouteDefinition, RouteHandlers, RouteMap, RouteState, RouterApi, RouterConfig, RouterState, State$4 as State, TypedRoute };
+declare namespace types_d_exports$8 {
+  export { Api$5 as Api, ClientRoute, CompileInput, CompiledRoute, Config$5 as Config, ExtractApi$2 as ExtractApi, ExtractRouteParams, ExtractSegmentParameter, GenerateContext, HeadConfig$1 as HeadConfig, LayoutContext, LoadContext, MatcherTable, Prettify, RouteBuilder, RouteContext, RouteDefinition, RouteHandlers, RouteMap, RouteRequire, RouteState, RouterApi, RouterConfig, RouterState, State$5 as State, TypedRoute, Urls };
 }
 /**
  * Param contribution of a single path segment. `{name:?}` / `:name?` → optional;
@@ -582,6 +597,84 @@ interface RouteContext<S extends RouteState> {
   readonly data: S["data"];
   /** Active locale for this render. */
   readonly locale: string;
+  /**
+   * Build a link to a named route by pattern substitution — the framework delivers
+   * this on the context (same output as `app.router.toUrl`), so render/head build
+   * links with no `app`/`createUrls` reference. Works identically at build and on
+   * client navigation.
+   */
+  readonly url: (name: string, params?: Record<string, string>) => string;
+}
+/**
+ * Structural extraction of a plugin instance's public API from its `_phantom`
+ * carrier (mirrors the kernel's `ExtractApi` / spec/09 §3). Lets the loader/generator
+ * `require` resolve a plugin instance to its typed public API.
+ *
+ * @example
+ * type ContentApi = ExtractApi<typeof contentPlugin>;
+ */
+type ExtractApi$2<PluginCandidate> = PluginCandidate extends {
+  readonly _phantom: {
+    readonly api: infer PluginApi;
+  };
+} ? PluginApi : never;
+/**
+ * Generic, instance-only `require` handed to a route's `.load()` / `.generate()` —
+ * the SAME shape as the kernel's `RequireFunction` (spec/08 §7) and the build's
+ * `PhaseRequire`, so the build forwards its own `ctx.require` straight through.
+ * Resolves a plugin INSTANCE to its public API; the consumer supplies the instance
+ * (e.g. `ctx.require(contentPlugin)`), so the router never names a sibling plugin.
+ *
+ * @example
+ * const content = ctx.require(contentPlugin); // ContentApi
+ */
+type RouteRequire = <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$2<PluginCandidate>;
+/**
+ * Build-time context handed to a route's `.load()`. Carries the resolved path
+ * `params` and active `locale`, plus the spec's `require`/`has` so a loader pulls
+ * sibling plugin APIs the canonical way — `ctx.require(contentPlugin)` — with no
+ * module global and no router→content coupling. Loaders run ONLY at build time
+ * (never on the client), inside the build plugin's context, so `require`/`has` are
+ * always live here.
+ *
+ * @example
+ * route("/{slug}/").load((ctx) => ctx.require(contentPlugin).load(ctx.params.slug, ctx.locale));
+ */
+interface LoadContext<S extends RouteState> {
+  /** Resolved path params for this page instance. */
+  readonly params: S["params"];
+  /** Active locale this page instance is built for. */
+  readonly locale: string;
+  /** Resolve a sibling plugin instance to its public API (spec/08 §7). */
+  readonly require: RouteRequire;
+  /** Whether a plugin is registered (by name) — branch on OPTIONAL plugins. */
+  readonly has: (name: string) => boolean;
+}
+/**
+ * Build-time context handed to a route's `.generate()` — the static-param producer.
+ * Carries the active `locale` plus `require`/`has` (no `params` yet — `.generate()`
+ * PRODUCES the param sets). Same build-only guarantee as {@link LoadContext}.
+ *
+ * @example
+ * route("/{slug}/").generate(async (ctx) =>
+ *   [...(await ctx.require(contentPlugin).loadAll()).get(ctx.locale) ?? []].map((a) => ({ slug: a.computed.slug })));
+ */
+interface GenerateContext {
+  /** Active locale to enumerate param sets for. */
+  readonly locale: string;
+  /** Resolve a sibling plugin instance to its public API (spec/08 §7). */
+  readonly require: RouteRequire;
+  /** Whether a plugin is registered (by name). */
+  readonly has: (name: string) => boolean;
 }
 /**
  * Context handed to a route's `.layout()` wrapper: the render-time
@@ -617,7 +710,7 @@ interface RouteBuilder<S extends RouteState> extends RouteDefinition {
    * Attach a data loader; widens the data generic (and ONLY the data generic) so
    * `.render()`/`.head()` see its return. Path params are preserved unchanged.
    */
-  load<D>(loader: (params: S["params"], locale: string) => D | Promise<D>): RouteBuilder<{
+  load<D>(loader: (ctx: LoadContext<S>) => D | Promise<D>): RouteBuilder<{
     readonly params: S["params"];
     readonly data: Awaited<D>;
   }>;
@@ -631,19 +724,10 @@ interface RouteBuilder<S extends RouteState> extends RouteDefinition {
   layout(component: (ctx: LayoutContext<S>, 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 a static-generation param producer (receives a {@link GenerateContext}). */
+  generate(handler: (ctx: GenerateContext) => S["params"][] | Promise<S["params"][]>): RouteBuilder<S>;
   /**
    * Attach an arbitrary metadata bag. The bag MUST be JSON-serializable: it is
    * projected verbatim into `clientManifest()` and shipped to the browser.
@@ -656,18 +740,16 @@ interface RouteBuilder<S extends RouteState> extends RouteDefinition {
 }
 /** Build-only handler bag captured by a `RouteBuilder` (consumed by `build` via `manifest()`). */
 interface RouteHandlers {
-  /** Data loader. */
-  readonly load?: (params: Record<string, string>, locale: string) => unknown;
+  /** Data loader (receives a {@link LoadContext}: params + locale + require/has). */
+  readonly load?: (ctx: LoadContext<RouteState>) => unknown;
   /** Layout wrapper (ctx-aware): frames the page in persistent chrome. SSG-only. */
   readonly layout?: (ctx: LayoutContext<RouteState>, 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. */
-  readonly generate?: (locale: string) => unknown[] | Promise<unknown[]>;
+  /** Static-generation param producer (receives a {@link GenerateContext}). */
+  readonly generate?: (ctx: GenerateContext) => unknown[] | Promise<unknown[]>;
   /** JSON serializer. */
   readonly toJson?: (ctx: RouteContext<RouteState>) => unknown;
   /** Output file-path producer. */
@@ -691,28 +773,45 @@ interface RouteDefinition {
  * base (erased) `RouteDefinition`; this is the documented generic-erasure boundary.
  */
 type RouteMap = Record<string, RouteDefinition>;
+/**
+ * A pure, app-free URL builder over a route map (the return type of `createUrls`).
+ * `toUrl` builds a route's path by name + params via pattern substitution — it needs
+ * NO running app, router instance, base URL, or i18n: just the route map the consumer
+ * already holds at module scope. Works identically at build, on client navigation,
+ * and inside hydrated islands. Reuses the SAME `buildUrl` as the runtime `RouterApi`,
+ * so the helper and the API can never diverge.
+ *
+ * @example
+ * const url = createUrls(routes);
+ * url.toUrl("article", { lang: "en", slug: "hello" }); // "/en/hello/"
+ */
+interface Urls<T extends RouteMap> {
+  /**
+   * Build a route's URL path from its name and params. The name is typed to the
+   * route map's keys — only declared routes are accepted.
+   *
+   * @param name - Route name key from the map (e.g. `"home"`, `"article"`).
+   * @param params - Path params to substitute into the pattern. Defaults to `{}`.
+   * @returns The resolved relative URL path.
+   * @throws {Error} If `name` is not present in the route map.
+   * @example
+   * url.toUrl("home", { lang: "en" }); // "/en/"
+   */
+  toUrl<K extends keyof T & string>(name: K, params?: Record<string, string>): string;
+}
 /**
  * Configuration for the router plugin.
  *
  * @remarks
- * `routes` is an OPAQUE carrier at the config boundary — the framework `Config`
- * generic erases the per-route element types (spec/05 §8, spec/09 §4). Downstream
- * plugins read the typed route set via `ctx.require(routerPlugin).manifest()`.
+ * `routes` is the declarative route map — registered the normal config way via
+ * `createApp({ pluginConfigs: { router: { routes } } })` and compiled into the matcher
+ * table in the router's `onInit`. An `import * as routes` namespace is a valid value. It is
+ * the SOLE registration path: omitting it leaves the matcher table empty, so every read
+ * (`match`/`toUrl`/`entries`/…) throws. The render `mode` is NOT here — it is a GLOBAL
+ * framework option (`createApp({ config: { mode } })`), read by the router via `ctx.global`.
  */
 type RouterConfig = {
-  /**
-   * Named route definitions. Element type erases to the base `RouteDefinition`
-   * at this config boundary; per-route call-site types are preserved only through
-   * `defineRoutes()` + `route()` at the consumer and re-exposed via `manifest()`.
-   */
-  routes: RouteMap;
-  /**
-   * Render mode for URL/file resolution. Defaults to `"hybrid"`.
-   * - `"ssg"` static generation only (no client router emitted).
-   * - `"spa"` client-side routing only.
-   * - `"hybrid"` static HTML + client navigation overlay.
-   */
-  mode?: "ssg" | "spa" | "hybrid";
+  /** Declarative route map (route name → `route(...)`); compiled at init. An `import * as` namespace works. */readonly routes?: RouteMap;
 };
 /** A resolved route exposing URL utilities with typed params (port of legacy TypedRoute). */
 interface TypedRoute<TParams = Record<string, string>> {
@@ -761,15 +860,14 @@ interface MatcherTable {
   readonly byName: ReadonlyMap<string, CompiledRoute>;
 }
 /**
- * Router plugin state. `createState` runs with minimal context and returns a
- * mutable holder whose `table` is `null` until `onInit` (which has full context)
- * compiles and assigns it. Keeps all mutable state in `ctx.state` (no singletons).
+ * Router plugin state — a mutable holder whose `table` is `null` until the router's
+ * `onInit` compiles `config.routes`. The render `mode` is NOT stored here; it is read
+ * from the global framework config via the API context. Keeps all mutable state in
+ * `ctx.state` (no singletons).
  */
 interface RouterState {
-  /** Compiled matcher table; `null` until `onInit` assigns it. */
+  /** Compiled matcher table; `null` until `onInit` compiles `config.routes`. */
   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 {
@@ -802,7 +900,7 @@ interface ClientRoute {
   /** Route metadata bag from `.meta()`. MUST be JSON-serializable. */
   readonly meta: Record<string, unknown>;
 }
-/** Public API exposed via `ctx.require(routerPlugin)`. */
+/** Public API exposed via `ctx.require(routerPlugin)` and `app.router`. */
 type RouterApi = {
   /**
    * Match a pathname against the compiled route table (specificity-sorted).
@@ -841,7 +939,7 @@ type RouterApi = {
    *
    * @returns Read-only array of the typed route definitions, in declaration order.
    * @example
-   * for (const def of ctx.require(routerPlugin).manifest()) { def._handlers.load?.({}, "en"); }
+   * for (const def of ctx.require(routerPlugin).manifest()) def._handlers.render?.(routeContext);
    */
   manifest(): readonly RouteDefinition[];
   /**
@@ -867,13 +965,13 @@ type RouterApi = {
   mode(): "ssg" | "spa" | "hybrid";
 };
 /** Re-export under the canonical `Config` name for the plugin-types barrel. */
-type Config$4 = RouterConfig;
+type Config$5 = RouterConfig;
 /** Re-export under the canonical `State` name for the plugin-types barrel. */
-type State$4 = RouterState;
+type State$5 = 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 };
+type Api$5 = RouterApi;
+declare namespace types_d_exports$6 {
+  export { Api$4 as Api, ArticleMeta, Config$4 as Config, HeadConfig, HeadDefaults, HeadElement, ResolvedRoute, State$4 as State };
 }
 /**
  * @file head plugin — type definitions skeleton
@@ -889,7 +987,7 @@ declare namespace types_d_exports$5 {
  * const config: Config = { titleTemplate: "%s — Moku" };
  * ```
  */
-type Config$3 = {
+type Config$4 = {
   /** 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`. */
@@ -907,7 +1005,7 @@ type Config$3 = {
  * const state: State = { defaults: null };
  * ```
  */
-type State$3 = {
+type State$4 = {
   /** Normalized head defaults, assigned once in `onInit` (initially `null`). */defaults: HeadDefaults | null;
 };
 /**
@@ -1001,7 +1099,7 @@ type ResolvedRoute = {
  * const html: string = api.render(route, data);
  * ```
  */
-type Api$3 = {
+type Api$4 = {
   /**
    * Compose the final `<head>` inner HTML for a route. Pulled synchronously by `build`.
    *
@@ -1015,7 +1113,7 @@ type Api$3 = {
    */
   render(route: ResolvedRoute, data: unknown): string;
 };
-declare namespace types_d_exports$8 {
+declare namespace types_d_exports$9 {
   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. */
@@ -1216,11 +1314,11 @@ interface SpaKernelDeps {
   /** 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$3;
+  head: Api$4;
   /**
    * 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
+   * DATA path (match → `dataAt(path)` → `route.render`); otherwise
    * it always uses HTML-over-fetch.
    */
   dataAt?: SpaDataReader;
@@ -1323,7 +1421,7 @@ type SpaApi = {
   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 };
+  export { Api$3 as Api, BuildCacheEntry, BuildEvents, BuildResult, Config$3 as Config, ExtractApi, OgFont, OgImageConfig, PhaseContext, PhaseEmit, PhaseLog, PhaseName, PhaseRequire, RichOgInput, State$3 as State };
 }
 /**
  * Structural extraction of a plugin instance's public API from its `_phantom`
@@ -1400,27 +1498,16 @@ type PhaseRequire = <PluginCandidate extends {
  * ```
  */
 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.). */
+  /** Mutable per-run build state (caches + runId). */state: State$3; /** Resolved, frozen build config. */
+  readonly config: Readonly<Config$3>; /** Global framework config (deployment stage; render mode is read via `router.mode()`). */
   readonly global: Readonly<{
-    mode: "production" | "development";
+    stage: Stage;
   }>; /** 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
@@ -1510,7 +1597,7 @@ interface OgImageConfig {
  * const config: Config = { outDir: "./dist", minify: true, feeds: true, sitemap: true, images: true, ogImage: false };
  * ```
  */
-type Config$2 = {
+type Config$3 = {
   /** 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. */
@@ -1521,11 +1608,11 @@ type Config$2 = {
   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`.
+   * `{ body }` to supply the page's literal HTML body content (written into the
+   * 404 page verbatim). Default `false`.
    */
   notFound?: boolean | {
-    route?: string;
+    body?: 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. */
@@ -1551,9 +1638,9 @@ type BuildCacheEntry = Record<string, string>;
  * const state: State = { config, manifest: null, buildCache: new Map(), runId: null, ogImageHashCache: new Map() };
  * ```
  */
-interface State$2 {
+interface State$3 {
   /** Resolved, frozen config snapshot. */
-  config: Config$2;
+  config: Config$3;
   /** 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). */
@@ -1600,7 +1687,7 @@ interface BuildResult {
  * const result = await app.build.run();
  * ```
  */
-type Api$2 = {
+type Api$3 = {
   /**
    * Run the full SSG pipeline and write the site to disk.
    *
@@ -1649,7 +1736,7 @@ type Api$2 = {
  * });
  * ```
  */
-declare const buildPlugin: import("@moku-labs/core").PluginInstance<"build", Config$2, State$2, Api$2, {
+declare const buildPlugin: import("@moku-labs/core").PluginInstance<"build", Config$3, State$3, Api$3, {
   "build:phase": {
     phase: PhaseName;
     status: "start" | "done";
@@ -1661,117 +1748,780 @@ declare const buildPlugin: import("@moku-labs/core").PluginInstance<"build", Con
     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 };
+declare namespace types_d_exports$4 {
+  export { Api$2 as Api, Config$2 as Config, DeployErrorCode, DeployInitOptions, DeployResult, DeployRunOptions, InitResult, SpawnFunction, SpawnOptions, SpawnedProcess, State$2 as State, WranglerErrorKind };
 }
 /**
- * Configuration for the content plugin.
- *
- * @example
- * ```ts
- * { contentDir: "./src/content", trustedContent: false, shikiTheme: "github-dark" }
- * ```
+ * @file deploy plugin — type definitions.
  */
-type Config$1 = {
-  /** Absolute or project-relative path to the content directory. Validated in onInit. */contentDir: string;
+/**
+ * Options passed to the injected spawner — the subset of Bun.spawn's options the
+ * plugin uses (piped stdout/stderr plus an env carrying the API token).
+ */
+interface SpawnOptions {
+  /** Capture stdout as a readable stream. */
+  readonly stdout: "pipe";
+  /** Capture stderr as a readable stream. */
+  readonly stderr: "pipe";
+  /** Subprocess environment — the API token is injected here, never via argv. */
+  readonly env?: Record<string, string | undefined>;
+}
+/**
+ * The structural subprocess handle the plugin reads back: stdout/stderr streams
+ * plus the exit-code promise. Streams are typed `unknown` and narrowed at the read
+ * site so this carries no Bun namespace types.
+ */
+interface SpawnedProcess {
+  /** Standard output stream (narrowed to a ReadableStream at the read site). */
+  readonly stdout: unknown;
+  /** Standard error stream (narrowed to a ReadableStream at the read site). */
+  readonly stderr: unknown;
+  /** Resolves with the subprocess exit code. */
+  readonly exited: Promise<number>;
+}
+/**
+ * The subset of Bun.spawn's signature the plugin relies on (argv array + options).
+ * Declared structurally — with NO `import("bun")` namespace types — so it survives
+ * `.d.ts` bundling intact and tests can supply a fake spawn without importing Bun.
+ */
+type SpawnFunction = (cmd: string[], options: SpawnOptions) => SpawnedProcess;
+/**
+ * A deploy error `code` from the wrangler error taxonomy and preflight validators.
+ */
+type DeployErrorCode = "ERR_DEPLOY_NO_WRANGLER_CONFIG" | "ERR_DEPLOY_EMPTY_OUTDIR" | "ERR_DEPLOY_TOO_MANY_FILES" | "ERR_DEPLOY_FILE_TOO_LARGE" | "ERR_DEPLOY_PATH_TRAVERSAL" | "ERR_DEPLOY_INVALID_BRANCH" | "ERR_DEPLOY_NO_TOKEN" | "ERR_DEPLOY_PROJECT_NOT_FOUND" | "ERR_DEPLOY_AUTH_EXPIRED" | "ERR_DEPLOY_AUTH" | "ERR_DEPLOY_NETWORK" | "ERR_DEPLOY_WRANGLER_FAILED" | "ERR_DEPLOY_CONFIG";
+/**
+ * The subset of wrangler error `code`s classifyWranglerError can produce from a
+ * non-zero wrangler exit.
+ */
+type WranglerErrorKind = Extract<DeployErrorCode, "ERR_DEPLOY_PROJECT_NOT_FOUND" | "ERR_DEPLOY_AUTH_EXPIRED" | "ERR_DEPLOY_AUTH" | "ERR_DEPLOY_NETWORK" | "ERR_DEPLOY_WRANGLER_FAILED">;
+/**
+ * Configuration for the deploy plugin.
+ */
+type Config$2 = {
   /**
-   * 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.
+   * Deploy target. Only Cloudflare Pages is supported in this version.
+   * Defaults to `cloudflare-pages`.
    */
-  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[];
+  target: "cloudflare-pages";
+  /**
+   * Directory (relative to project root) containing the built site to deploy.
+   * Re-validated against cwd at run() time to block path traversal.
+   * Defaults to `dist`.
+   */
+  outDir: string;
   /**
-   * Shiki theme for syntax highlighting: a bundled theme NAME — typed as Shiki's
-   * `BundledTheme` union so editors autocomplete the ~60 built-ins (default
-   * "github-dark") — or a custom `ThemeRegistration` object. Passed straight through
-   * to `@shikijs/rehype`'s `theme`. (Like Shiki's own theme type, an arbitrary string
-   * still compiles via the object arm, so this is autocomplete, not typo-rejection.)
+   * Branch treated as the Cloudflare Pages production branch.
+   * Defaults to `main`.
    */
-  shikiTheme?: BundledTheme | ThemeRegistrationAny; /** Author applied to articles whose frontmatter omits author. Defaults to undefined. */
-  defaultAuthor?: string;
+  productionBranch?: string;
+  /**
+   * Substrings exempt from entropy-gated secret scrubbing in logged output.
+   * Defaults to `["CLOUDFLARE_ACCOUNT_ID"]`.
+   */
+  scrubAllowlist: string[];
+  /**
+   * Cloudflare compatibility date written into generated wrangler.jsonc.
+   * Defaults to `2024-01-01`.
+   */
+  compatibilityDate?: string;
+  /**
+   * Whether init() also generates a GitHub Actions workflow.
+   * Defaults to `false`.
+   */
+  ci?: boolean;
 };
 /**
- * Internal mutable state for the content plugin.
- *
- * @example
- * ```ts
- * { processor: null, articles: new Map(), slugs: null, dirtyPaths: new Set() }
- * ```
+ * Result of a successful deploy.
  */
-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>;
+type DeployResult = {
+  /** The public deployment URL (e.g. https://my-site.pages.dev). */url: string; /** Cloudflare deployment ID parsed from wrangler output. */
+  deploymentId: string; /** The branch that was deployed. */
+  branch: string; /** Wall-clock duration of the deploy in milliseconds. */
+  durationMs: number;
 };
 /**
- * YAML frontmatter parsed from each article file.
- *
- * @example
- * ```ts
- * { title: "Hello", date: "2026-01-15", description: "Intro", tags: [], language: "en" }
- * ```
+ * Runtime state for the deploy plugin. Created in createState() and accessed via
+ * ctx.state. deploy declares no onStop because nothing here is a long-lived resource.
  */
-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;
+type State$2 = {
+  /** Result of the most recent successful deploy, or null before the first run. */lastDeployment: DeployResult | null;
+  /**
+   * Injectable subprocess spawner. Defaults to Bun.spawn. Swapped for a mock in
+   * unit tests so wrangler is never actually invoked. Never reassigned at runtime.
+   */
+  spawn: SpawnFunction;
 };
 /**
- * Fields computed by the pipeline (not authored in frontmatter).
- *
- * @example
- * ```ts
- * { slug: "hello", readingTime: 1, contentId: "hello", status: "published", wordCount: 42 }
- * ```
+ * Options for DeployApi.run.
  */
-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;
+type DeployRunOptions = {
+  /**
+   * Branch to deploy. Defaults to config.productionBranch (or "main"). Must match
+   * /^[a-zA-Z0-9/_.-]+$/ — otherwise rejected with ERR_DEPLOY_INVALID_BRANCH.
+   */
+  branch?: string;
 };
 /**
- * A fully processed, render-ready article.
- *
- * @example
- * ```ts
- * { frontmatter, computed, html: "<p>…</p>", locale: "en", isFallback: false, url: "/en/hello/" }
- * ```
+ * Options for DeployApi.init.
  */
-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;
+type DeployInitOptions = {
+  /** Also generate the GitHub Actions workflow. Defaults to config.ci. */ci?: boolean; /** Drift-only mode: report differences without writing any files. Defaults to `false`. */
+  check?: boolean;
 };
 /**
- * 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/" }
- * ```
+ * Result of an init/scaffold operation.
  */
-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. */
+type InitResult = {
+  /** Paths written this invocation. */written: string[]; /** Paths skipped because they already exist. */
+  skipped: string[]; /** In check mode: paths whose on-disk content differs from what would be generated. */
+  drifted: string[];
+};
+/**
+ * Public API of the deploy plugin (returned from the api factory).
+ */
+type Api$2 = {
+  /**
+   * Deploy the built outDir to Cloudflare Pages via the wrangler subprocess.
+   * Runs preflight validators, re-validates the resolved outdir against cwd, guards
+   * the branch argument, spawns wrangler (no shell), scrubs all subprocess output
+   * before logging, records lastDeployment, and emits deploy:complete.
+   *
+   * @param options - Optional branch override.
+   * @returns The deploy result (url, deploymentId, branch, durationMs).
+   * @throws {Error} With a `code` from the deploy error taxonomy on any failure.
+   * @example
+   * const result = await app.deploy.run();
+   * console.log(result.url); // https://my-site.pages.dev
+   * @example
+   * await app.deploy.run({ branch: "preview/landing" });
+   */
+  run(options?: DeployRunOptions): Promise<DeployResult>;
+  /**
+   * Return the most recent successful deploy result, or null if none has occurred.
+   * The returned object is read-only (a defensive snapshot).
+   *
+   * @returns The last DeployResult, or null.
+   * @example
+   * const last = app.deploy.getLastDeployment();
+   * if (last) console.log(`Last deployed to ${last.url}`);
+   */
+  getLastDeployment(): Readonly<DeployResult> | null;
+  /**
+   * Generate deploy scaffolding: wrangler.jsonc (slug from site.name() + outDir +
+   * compatibilityDate) and, when ci is enabled, .github/workflows/deploy.yml. Never
+   * overwrites an existing wrangler.jsonc. In check mode, reports drift instead of writing.
+   *
+   * @param options - Optional ci toggle and check (drift-only) mode.
+   * @returns Which files were written, skipped, or would drift.
+   * @example
+   * const out = await app.deploy.init({ ci: true });
+   * // out.written -> ["wrangler.jsonc", ".github/workflows/deploy.yml"]
+   * @example
+   * const drift = await app.deploy.init({ check: true });
+   * if (drift.drifted.length) process.exit(1);
+   */
+  init(options?: DeployInitOptions): Promise<InitResult>;
+};
+declare namespace types_d_exports$1 {
+  export { Api$1 as Api, BuildOptions, BuildSummary, CliErrorCode, CliRenderer, Command, Config$1 as Config, DeployOptions, DeployOutcome, FileResponseFunction, PreviewOptions, ReloadInfo, ServeOptions, ServeStaticFunction, ServeStaticOptions, ServerHandle, ServerInfo, State$1 as State, WatchHandle };
+}
+/**
+ * A cli error `code` from the config-validation and runtime taxonomy. Mirrors the
+ * deploy plugin's coded-error pattern so every thrown value carries a stable `code`.
+ *
+ * @example
+ * const code: CliErrorCode = "ERR_CLI_CONFIG";
+ */
+type CliErrorCode = "ERR_CLI_CONFIG" | "ERR_CLI_NOT_FOUND";
+/**
+ * The four commands a single cli process can run. Each maps to one consumer script
+ * (`scripts/{build,serve,preview,deploy}.ts`) and is rendered as the Panel header.
+ *
+ * @example
+ * const command: Command = "build";
+ */
+type Command = "build" | "serve" | "preview" | "deploy";
+/**
+ * Information rendered into the bordered server-ready panel by `serve()`/`preview()`.
+ *
+ * @example
+ * const info: ServerInfo = { local: "http://localhost:4173", network: null };
+ */
+type ServerInfo = {
+  /** The loopback URL the server is reachable at (e.g. `http://localhost:4173`). */local: string; /** The LAN URL derived from the first non-internal IPv4, or `null` when offline. */
+  network: string | null; /** Directories `serve()` is watching for changes (omitted by `preview()`). */
+  watching?: string[];
+};
+/**
+ * Information rendered after a single `serve()` rebuild: the watched directory whose
+ * subtree changed plus the fresh build summary used to print the "rebuilt N pages"
+ * line.
+ *
+ * @example
+ * const info: ReloadInfo = { file: "content", pageCount: 12, durationMs: 84 };
+ */
+type ReloadInfo = {
+  /** The watched directory whose subtree changed (the rebuild is per-watchDir, not per-file). */file: string; /** Number of route pages rendered by the rebuild. */
+  pageCount: number; /** Wall-clock duration of the rebuild in milliseconds. */
+  durationMs: number;
+};
+/**
+ * The Panel renderer surface — every line of terminal output flows through this so
+ * tests can inject a line-capturing fake. Implemented by `createPanelRenderer` and
+ * is TTY/`NO_COLOR`-aware (box-drawing + color on a TTY, plain lines otherwise).
+ *
+ * @example
+ * const render: CliRenderer = createPanelRenderer();
+ * render.header("build");
+ */
+type CliRenderer = {
+  /**
+   * Render the boxed `MOKU WEB` logo + command label. Called once per command (one
+   * command = one process), so it never repeats within a run.
+   *
+   * @param command - The command being run, shown beside the logo.
+   * @returns Nothing.
+   * @example
+   * render.header("serve");
+   */
+  header(command: Command): void;
+  /**
+   * Render a live per-phase row from a `build:phase` event.
+   *
+   * @param phase - The `build:phase` payload (`{ phase, status, durationMs? }`).
+   * @returns Nothing.
+   * @example
+   * render.phase({ phase: "pages", status: "done", durationMs: 12 });
+   */
+  phase(phase: BuildEvents["build:phase"]): void;
+  /**
+   * Render the BUILD summary block from a `build:complete` event.
+   *
+   * @param summary - The `build:complete` payload (`{ outDir, pageCount, durationMs }`).
+   * @returns Nothing.
+   * @example
+   * render.built({ outDir: "dist", pageCount: 12, durationMs: 840 });
+   */
+  built(summary: BuildEvents["build:complete"]): void;
+  /**
+   * Render the bordered server-ready panel (Local / Network URLs + watched dirs).
+   *
+   * @param info - Local/Network URLs and optionally the watched directories.
+   * @returns Nothing.
+   * @example
+   * render.serverReady({ local: "http://localhost:4173", network: null });
+   */
+  serverReady(info: ServerInfo): void;
+  /**
+   * Render the post-rebuild line ("~ dir" + "✓ rebuilt N pages · Xms · reloaded"),
+   * where the label is the watched directory whose subtree changed (see {@link ReloadInfo.file}).
+   *
+   * @param info - The changed watched directory plus the rebuild's page count and duration.
+   * @returns Nothing.
+   * @example
+   * render.reload({ file: "content", pageCount: 12, durationMs: 84 });
+   */
+  reload(info: ReloadInfo): void;
+  /**
+   * Render the deploy result panel from a `deploy:complete` event.
+   *
+   * @param result - The `deploy:complete` payload (`{ url, deploymentId, branch, durationMs }`).
+   * @returns Nothing.
+   * @example
+   * render.deployed({ url: "https://x.pages.dev", deploymentId: "id", branch: "main", durationMs: 1200 });
+   */
+  deployed(result: DeployResult): void;
+  /**
+   * Render a neutral informational line (e.g. the non-interactive deploy note, watch notice).
+   *
+   * @param message - The line to print.
+   * @returns Nothing.
+   * @example
+   * render.info("watching for changes…");
+   */
+  info(message: string): void;
+  /**
+   * Render a warning line (written to stderr).
+   *
+   * @param message - The warning to print.
+   * @returns Nothing.
+   * @example
+   * render.warn("deploy skipped");
+   */
+  warn(message: string): void;
+  /**
+   * Render an error line (written to stderr), optionally with a cause.
+   *
+   * @param message - The error summary to print.
+   * @param cause - Optional underlying error/value to print beneath the summary.
+   * @returns Nothing.
+   * @example
+   * render.error("build failed", err);
+   */
+  error(message: string, cause?: unknown): void;
+};
+/**
+ * A live directory watcher handle returned by the injectable `watch` seam. Closing
+ * it detaches the underlying `node:fs.watch` listener.
+ *
+ * @example
+ * const handle: WatchHandle = state.watch("content", onChange);
+ * handle.close();
+ */
+type WatchHandle = {
+  /**
+   * Stop watching and release the underlying listener.
+   *
+   * @returns Nothing.
+   * @example
+   * handle.close();
+   */
+  close(): void;
+};
+/**
+ * A running static server handle the cli stops on teardown. Declared structurally
+ * (no Bun namespace types) so it survives `.d.ts` bundling and tests can supply a
+ * fake without importing Bun.
+ *
+ * @example
+ * const handle: ServerHandle = state.serveStatic({ port, fetch });
+ * handle.stop();
+ */
+type ServerHandle = {
+  /**
+   * Stop the server and release its socket.
+   *
+   * @returns Nothing.
+   * @example
+   * handle.stop();
+   */
+  stop(): void;
+};
+/**
+ * The subset of `Bun.serve`'s options the cli uses: a port plus a `fetch` handler.
+ * Declared structurally so no Bun namespace type reaches the public surface.
+ *
+ * @example
+ * const opts: ServeStaticOptions = { port: 4173, fetch: () => new Response("ok") };
+ */
+type ServeStaticOptions = {
+  /** Port to bind the server to. */port: number;
+  /**
+   * Per-request handler returning the response (sync or async).
+   *
+   * @param request - The incoming request.
+   * @returns The response (or a promise of it).
+   * @example
+   * fetch(req) { return new Response("ok"); }
+   */
+  fetch(request: Request): Response | Promise<Response>;
+};
+/**
+ * An injectable static-server factory (defaults to `Bun.serve`). Keeps the Bun
+ * runtime dependency behind a structural seam so `serve()`/`preview()` never open a
+ * real socket in tests.
+ *
+ * @example
+ * const serveStatic: ServeStaticFunction = options => Bun.serve(options);
+ */
+type ServeStaticFunction = (options: ServeStaticOptions) => ServerHandle;
+/**
+ * An injectable file-response factory (defaults to `new Response(Bun.file(path))`).
+ * Maps a resolved on-disk path + status to the response body the server returns.
+ *
+ * @example
+ * const fileResponse: FileResponseFunction = (path, status) => new Response(Bun.file(path), { status });
+ */
+type FileResponseFunction = (path: string, status: number) => Response;
+/**
+ * Configuration for the cli plugin — the complete resolved `Config` (not a partial).
+ * Consumers override individual fields via `pluginConfigs.cli`.
+ *
+ * @example
+ * const config: Config = {
+ *   outDir: "dist", port: 4173, watchDirs: ["content", "src"],
+ *   debounceMs: 150, notFoundFile: "404.html", liveReload: true
+ * };
+ */
+type Config$1 = {
+  /** Build output directory; served by preview, asserted by build, rebuilt by serve. Default `"dist"`. */outDir: string; /** Default port for serve()/preview() (overridable per-call via options.port). Default `4173`. */
+  port: number; /** Directories serve() watches for changes (recursive). Default `["content", "src"]`. */
+  watchDirs: string[]; /** Debounce window (ms) coalescing FS-event bursts into one rebuild. Default `150`. */
+  debounceMs: number; /** Filename build() asserts exists at outDir root (CF Pages flips to SPA mode without it). Default `"404.html"`. */
+  notFoundFile: string; /** Inject the live-reload SSE client into HTML during serve() (never during preview()). Default `true`. */
+  liveReload: boolean;
+};
+/**
+ * Runtime state for the cli plugin — injectable seams so every command is testable
+ * without real sockets/FS-watch/TTY (mirrors deploy's injectable `spawn`).
+ *
+ * @example
+ * const state: State = createState();
+ */
+type State$1 = {
+  /** Panel renderer — all terminal output flows through this. Tests inject a line-capturing fake. */render: CliRenderer;
+  /**
+   * Interactive y/N prompt used by deploy(). Default reads stdin (TTY); tests inject a canned answer.
+   *
+   * @param question - The yes/no question to display.
+   * @returns Resolves `true` when the user answered yes.
+   * @example
+   * const ok = await state.confirm("Deploy dist/?");
+   */
+  confirm: (question: string) => Promise<boolean>;
+  /**
+   * Monotonic clock for durations. Default `Date.now`; tests inject for deterministic timing.
+   *
+   * @returns The current time in milliseconds.
+   * @example
+   * const t = state.clock();
+   */
+  clock: () => number;
+  /**
+   * Recursive directory watcher factory used by serve(). Default wraps `node:fs.watch`;
+   * tests inject a fake emitter.
+   *
+   * @param dir - The directory to watch recursively.
+   * @param onChange - Invoked on any change beneath `dir`.
+   * @returns A handle whose `close()` detaches the watcher.
+   * @example
+   * const handle = state.watch("content", () => rebuild());
+   */
+  watch: (dir: string, onChange: () => void) => WatchHandle; /** Static-server factory used by serve()/preview(). Default `Bun.serve`; tests inject a fake. */
+  serveStatic: ServeStaticFunction; /** File-response factory mapping a resolved path + status to a `Response`. Default `Bun.file`. */
+  fileResponse: FileResponseFunction;
+  /**
+   * LAN network-URL deriver for the server-ready panel. Default reads `node:os`
+   * interfaces; tests inject a deterministic value.
+   *
+   * @param port - The port the server is bound to.
+   * @returns The `http://<ip>:<port>` URL, or `null` when offline.
+   * @example
+   * const url = state.networkUrl(4173);
+   */
+  networkUrl: (port: number) => string | null;
+};
+/**
+ * Summary returned by `cli.build()` — the awaited `build.run()` result.
+ *
+ * @example
+ * const summary: BuildSummary = { outDir: "dist", pageCount: 12, durationMs: 840 };
+ */
+type BuildSummary = {
+  /** 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;
+};
+/**
+ * Outcome returned by `cli.deploy()` — either a completed deploy (with details) or a
+ * skipped one. A skip happens only when an interactive TTY user answers "no" at the
+ * confirm prompt (`reason: "declined"`). Non-interactive runs (CI / non-TTY) never
+ * prompt and always proceed, so they never skip — the scripts are CI-safe.
+ *
+ * @example
+ * const outcome: DeployOutcome = { deployed: false, reason: "declined" };
+ */
+type DeployOutcome = {
+  deployed: true;
+  url: string;
+  deploymentId: string;
+  branch: string;
+  durationMs: number;
+} | {
+  deployed: false;
+  reason: "declined";
+};
+/**
+ * Options for `cli.build()`.
+ *
+ * @example
+ * await app.cli.build({ assertNotFound: false });
+ */
+type BuildOptions = {
+  /** Assert `outDir/notFoundFile` exists after the build. Defaults to `true`. */assertNotFound?: boolean;
+};
+/**
+ * Options for `cli.serve()`.
+ *
+ * @example
+ * await app.cli.serve({ port: 3000 });
+ */
+type ServeOptions = {
+  /** Port to bind the dev server to. Defaults to `config.port`. */port?: number; /** Reserved for opening the browser on start (not yet implemented). Defaults to `false`. */
+  open?: boolean;
+};
+/**
+ * Options for `cli.preview()`.
+ *
+ * @example
+ * await app.cli.preview({ port: 8080 });
+ */
+type PreviewOptions = {
+  /** Port to bind the preview server to. Defaults to `config.port`. */port?: number;
+};
+/**
+ * Options for `cli.deploy()`.
+ *
+ * @example
+ * await app.cli.deploy({ branch: "preview/x", yes: true });
+ */
+type DeployOptions = {
+  /** Branch to deploy. Defaults to the deploy plugin's production branch. */branch?: string; /** Skip the y/N confirm and deploy immediately. Defaults to `false`. */
+  yes?: boolean;
+};
+/**
+ * Public API of the cli plugin (mounted at `app.cli`) — exactly four methods.
+ *
+ * @example
+ * await app.cli.build();
+ */
+type Api$1 = {
+  /**
+   * Run the SSG build and assert the not-found page exists.
+   *
+   * @param options - Optional `assertNotFound` toggle (default `true`).
+   * @returns The build summary (`outDir`, `pageCount`, `durationMs`).
+   * @throws {Error} `ERR_CLI_NOT_FOUND` when the not-found page is missing and asserted.
+   * @example
+   * const summary = await app.cli.build();
+   */
+  build(options?: BuildOptions): Promise<BuildSummary>;
+  /**
+   * Dev loop: build once, serve `dist/` in-process (live-reload injected), watch
+   * `watchDirs`, debounced rebuild + reload. Resolves when SIGINT/SIGTERM tears down.
+   *
+   * @param options - Optional port override.
+   * @returns Resolves once the server has been torn down.
+   * @example
+   * await app.cli.serve({ port: 3000 });
+   */
+  serve(options?: ServeOptions): Promise<void>;
+  /**
+   * Static preview of the built `dist/` with CF-Pages clean-URL resolution. No
+   * reload injection (mirrors production). Resolves on SIGINT/SIGTERM.
+   *
+   * @param options - Optional port override.
+   * @returns Resolves once the server has been torn down.
+   * @example
+   * await app.cli.preview();
+   */
+  preview(options?: PreviewOptions): Promise<void>;
+  /**
+   * Scaffold, then deploy. A y/N confirm is shown only on an interactive TTY;
+   * non-interactive runs (CI, or any non-TTY) skip the prompt and deploy, so the
+   * consumer scripts never block a pipeline. `options.yes` forces the skip anywhere.
+   *
+   * @param options - Optional branch override and `yes` flag.
+   * @returns The deploy outcome (completed details, or `declined` if a TTY user says no).
+   * @example
+   * await app.cli.deploy({ branch: "preview/x", yes: true });
+   */
+  deploy(options?: DeployOptions): Promise<DeployOutcome>;
+};
+//#endregion
+//#region src/plugins/cli/index.d.ts
+/**
+ * cli plugin — the node-only developer CLI for `@moku-labs/web`. Mounts exactly four
+ * methods at `app.cli` (`build`/`serve`/`preview`/`deploy`), each rendering through
+ * the boxed Panel UI. Live build/deploy progress rides on hooks over the `build` and
+ * `deploy` plugins' events; there is no argv parser and no `run()` dispatcher — the
+ * consumer drives it from one thin script per command.
+ *
+ * @example Compose the CLI in a consumer app (node-only)
+ * ```ts
+ * import { buildPlugin, cliPlugin, createApp, deployPlugin } from "@moku-labs/web";
+ *
+ * const app = createApp({
+ *   plugins: [buildPlugin, deployPlugin, cliPlugin],
+ *   pluginConfigs: { cli: { outDir: "dist", port: 4173, watchDirs: ["content", "src"] } }
+ * });
+ * await app.start();
+ * await app.cli.build();
+ * ```
+ */
+declare const cliPlugin: import("@moku-labs/core").PluginInstance<"cli", Config$1, State$1, Api$1, {}> & Record<never, never>;
+declare namespace types_d_exports$2 {
+  export { Api, Article, ArticleCard, ComputedFields, Config, ContentApiContext, ContentEvents, ContentProvider, ContentProviderState, FileSystemContentOptions, Frontmatter, State };
+}
+/**
+ * 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 the provider's 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;
 };
+/**
+ * A pluggable content SOURCE. The shell calls these to read articles; whether content
+ * is read from the filesystem (Node) or some other source is chosen by which provider
+ * you compose — exactly like `env` providers (`dotenv`/`processEnv` vs `browserEnv`).
+ * The shell adds locale fallback, draft filtering, sorting, caching, and events on top.
+ *
+ * @example
+ * ```ts
+ * const provider = fileSystemContent({ contentDir: "./content" });
+ * ```
+ */
+interface ContentProvider {
+  /** Human-readable provider name, used in diagnostics. */
+  readonly name: string;
+  /** Source directory surfaced via `api.contentDir()` (filesystem providers; "" otherwise). */
+  readonly contentDir: string;
+  /**
+   * Discover the article slugs this provider can supply.
+   *
+   * @returns The provider's slug list.
+   */
+  slugs(): Promise<readonly string[]>;
+  /**
+   * Read + render ONE article for a file-locale; `null` if this provider has no such file.
+   *
+   * @param slug - Article directory name.
+   * @param fileLocale - Locale whose source file is read.
+   * @param outLocale - Locale the resulting Article represents (the requested locale).
+   * @param isFallback - Whether this resolution used the default-locale fallback.
+   * @returns The constructed Article, or `null` when absent.
+   */
+  readArticle(slug: string, fileLocale: string, outLocale: string, isFallback: boolean): Promise<Article | null>;
+  /**
+   * Render a standalone Markdown string to HTML through the provider's pipeline.
+   *
+   * @param markdown - Raw Markdown source.
+   * @returns The rendered HTML.
+   */
+  render(markdown: string): Promise<string>;
+  /**
+   * Optional dev hook: drop cached discovery so stale paths are re-read next time.
+   *
+   * @param paths - Stale file paths.
+   */
+  invalidate?(paths: readonly string[]): void;
+}
+/**
+ * Options for the node filesystem provider {@link ContentProvider} `fileSystemContent`.
+ * These are the markdown-pipeline + source concerns that used to live on the content
+ * plugin config; they now belong to the provider you compose.
+ *
+ * @example
+ * ```ts
+ * fileSystemContent({ contentDir: "./content", shikiTheme: "github-dark", defaultAuthor: "Ada" });
+ * ```
+ */
+type FileSystemContentOptions = {
+  /** Absolute or project-relative path to the content directory. */contentDir: string;
+  /**
+   * SECURITY GATE. When false (the default), rehype-sanitize runs as the final
+   * pipeline step. Set true ONLY for fully author-controlled Markdown.
+   */
+  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 for syntax highlighting: a bundled theme NAME (default "github-dark")
+   * or a custom `ThemeRegistration` object. Passed straight through to `@shikijs/rehype`.
+   */
+  shikiTheme?: BundledTheme | ThemeRegistrationAny; /** Author applied to articles whose frontmatter omits author. Defaults to undefined. */
+  defaultAuthor?: string;
+};
+/**
+ * Internal mutable state of the filesystem provider: the lazy unified processor and
+ * the discovery caches. Owned by the provider closure, never by the plugin shell.
+ *
+ * @example
+ * ```ts
+ * { processor: null, slugs: null, dirtyPaths: new Set() }
+ * ```
+ */
+type ContentProviderState = {
+  /** Lazily-created unified processor singleton. null until first render()/readArticle(). */processor: Processor | null; /** Discovered, sorted slug list cached after first disk scan. null until first discovery. */
+  slugs: string[] | null; /** Paths marked stale by invalidate(); next discovery re-reads only these. Starts empty. */
+  dirtyPaths: Set<string>;
+};
+/**
+ * Configuration for the content plugin (shell).
+ *
+ * @example
+ * ```ts
+ * { providers: [fileSystemContent({ contentDir: "./content" })] }
+ * ```
+ */
+type Config = {
+  /**
+   * Ordered content sources. Compose at least one (e.g. `fileSystemContent(...)` on
+   * Node). The first provider that supplies an article for a slug+locale wins;
+   * `slugs()` are unioned. The plugin's own spec default is `[]` (a build must supply one).
+   */
+  providers: ContentProvider[];
+};
+/**
+ * Internal mutable state for the content plugin shell: the locale-keyed article cache.
+ *
+ * @example
+ * ```ts
+ * { articles: new Map() }
+ * ```
+ */
+type State = {
+  /** Article cache keyed locale -> (slug -> Article). Starts empty. */articles: Map<string, Map<string, Article>>;
+};
 /**
  * Notification-only events emitted by the content plugin.
  *
@@ -1791,24 +2541,24 @@ type ContentEvents = {
 };
 /**
  * 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.
+ * Carries the shell state (article cache), global flag, emit, the i18n-derived
+ * locale helpers, and the resolved content {@link ContentProvider} — so api.ts stays
+ * free of createPlugin/ctx AND of any node/pipeline import.
  *
  * @example
  * ```ts
- * const apiContext: ContentApiContext = { state, config, global, emit, locales, defaultLocale, articleToUrl };
+ * const apiContext: ContentApiContext = { state, global, emit, locales, defaultLocale, provider };
  * ```
  */
 type ContentApiContext = {
-  /** Mutable plugin state (article cache + lazy processor). */state: State$1; /** Resolved plugin configuration. */
-  config: Config$1; /** Global framework configuration (mode, etc.). */
+  /** Mutable shell state (article cache). */state: State; /** Global framework configuration (deployment stage). */
   global: {
-    mode: "production" | "development";
+    stage: Stage;
   }; /** 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;
+  defaultLocale: () => string; /** The resolved content source (merged from `config.providers`). */
+  provider: ContentProvider;
 };
 /**
  * Public API for the content plugin.
@@ -1818,7 +2568,7 @@ type ContentApiContext = {
  * const map = await app.content.loadAll();
  * ```
  */
-type Api$1 = {
+type Api = {
   /**
    * Load every article across every active locale, returning a locale-keyed
    * map of date-descending Article arrays. Emits content:ready.
@@ -1850,35 +2600,35 @@ type Api$1 = {
    */
   articleToCard(article: Article): ArticleCard;
   /**
-   * The configured content source directory (e.g. `"./content"`). Lets the build copy each
-   * article's co-located assets (`<contentDir>/<slug>/images/`) into the output so the absolute
-   * image URLs the renderer emits resolve.
+   * The configured content source directory (e.g. `"./content"`), from the first
+   * provider. Lets the build copy each article's co-located assets
+   * (`<contentDir>/<slug>/images/`) into the output.
    */
   contentDir(): string;
 };
 //#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`.
+ * Content plugin (shell) — provider-driven locale-keyed Article model. Orchestration
+ * (locale fallback, draft filtering, sort, caching, events) lives here; source I/O +
+ * the Markdown pipeline live in a {@link ContentProvider} you compose (like `env`
+ * providers). The shell imports zero node code, so `contentPlugin` is browser-safe.
+ * Depends on i18n; emits `content:ready` and `content:invalidated`.
  *
- * @example Point at a content directory and pick a Shiki theme
+ * @example Compose the node filesystem provider with a content dir + Shiki theme
  * ```ts
+ * import { contentPlugin, fileSystemContent } from "@moku-labs/web";
  * const app = createApp({
+ *   plugins: [contentPlugin],
  *   pluginConfigs: {
  *     content: {
- *       contentDir: "./content",
- *       shikiTheme: "github-dark",
- *       defaultAuthor: "Ada Lovelace"
- *       // trustedContent: true // ONLY for fully author-controlled Markdown — disables sanitize
+ *       providers: [fileSystemContent({ contentDir: "./content", shikiTheme: "github-dark", defaultAuthor: "Ada" })]
  *     }
  *   }
  * });
  * ```
  */
-declare const contentPlugin: import("@moku-labs/core").PluginInstance<"content", Config$1, State$1, Api$1, {
+declare const contentPlugin: import("@moku-labs/core").PluginInstance<"content", Config, State, Api, {
   "content:ready": {
     locales: readonly string[];
     articleCount: number;
@@ -1887,7 +2637,7 @@ declare const contentPlugin: import("@moku-labs/core").PluginInstance<"content",
     paths: readonly string[];
   };
 }> & Record<never, never>;
-declare namespace types_d_exports$2 {
+declare namespace types_d_exports$3 {
   export { DataConfig, DataEntry, DataProvider, DataState, DataWriteSummary };
 }
 /**
@@ -1896,13 +2646,13 @@ declare namespace types_d_exports$2 {
  * 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`).
+ * its own data shape (`load`'s return).
  *
  *  - **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`.
+ *  - **Browser (runtime):** `at(path)` fetches + caches that file as `unknown`, which
+ *    the route uses directly as `ctx.data` in `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
@@ -1924,8 +2674,8 @@ type DataConfig = {
   outputDir: string;
   /**
    * 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/"`.
+   * JSON from. The URL-space mirror of {@link DataConfig.outputDir} (a filesystem
+   * path); keep them consistent (`"/" + trim(outputDir) + "/"`). Default `"/_data/"`.
    */
   baseUrl: string;
 };
@@ -1967,15 +2717,15 @@ interface DataState {
  * // 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
+ * // Browser (inside spa nav): fetch the page's data, used directly as ctx.data:
+ * const raw = await app.data.at("/en/hello/"); // unknown | null (null on failure)
  * ```
  */
 type DataProvider = {
   /**
    * 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.
+   * `config.baseUrl`. Returns the raw parsed JSON as `unknown`, used directly as
+   * the route's `ctx.data`; returns `null` if the fetch or JSON parse fails.
    *
    * @param path - The page URL path (e.g. `/en/hello/`).
    * @returns The page's raw data, or `null` on failure.
@@ -2021,197 +2771,19 @@ type DataProvider = {
  * @example
  * ```ts
  * // Node build: `build` calls app.data.write(...) during its pages phase when
- * // router.mode !== "ssg". Just compose the plugin:
+ * // router.mode() !== "ssg". Compose the plugin + set the global render mode:
+ * import * as routes from "./routes";
  * const app = createApp({
  *   plugins: [dataPlugin, contentPlugin, buildPlugin],
- *   pluginConfigs: { content: { contentDir: "./content" }, router: { routes, mode: "hybrid" } }
+ *   config: { mode: "hybrid" },
+ *   pluginConfigs: { content: { providers: [fileSystemContent({ contentDir: "./content" })] }, router: { routes } }
  * });
- * await app.start();
- * await app.build.run();   // writes HTML + per-page data sidecars
+ * await app.build.run();   // writes HTML + per-page data sidecars (routes compiled at init)
  *
  * // 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 };
-}
-/**
- * @file deploy plugin — type definitions.
- */
-/**
- * Options passed to the injected spawner — the subset of Bun.spawn's options the
- * plugin uses (piped stdout/stderr plus an env carrying the API token).
- */
-interface SpawnOptions {
-  /** Capture stdout as a readable stream. */
-  readonly stdout: "pipe";
-  /** Capture stderr as a readable stream. */
-  readonly stderr: "pipe";
-  /** Subprocess environment — the API token is injected here, never via argv. */
-  readonly env?: Record<string, string | undefined>;
-}
-/**
- * The structural subprocess handle the plugin reads back: stdout/stderr streams
- * plus the exit-code promise. Streams are typed `unknown` and narrowed at the read
- * site so this carries no Bun namespace types.
- */
-interface SpawnedProcess {
-  /** Standard output stream (narrowed to a ReadableStream at the read site). */
-  readonly stdout: unknown;
-  /** Standard error stream (narrowed to a ReadableStream at the read site). */
-  readonly stderr: unknown;
-  /** Resolves with the subprocess exit code. */
-  readonly exited: Promise<number>;
-}
-/**
- * The subset of Bun.spawn's signature the plugin relies on (argv array + options).
- * Declared structurally — with NO `import("bun")` namespace types — so it survives
- * `.d.ts` bundling intact and tests can supply a fake spawn without importing Bun.
- */
-type SpawnFunction = (cmd: string[], options: SpawnOptions) => SpawnedProcess;
-/**
- * A deploy error `code` from the wrangler error taxonomy and preflight validators.
- */
-type DeployErrorCode = "ERR_DEPLOY_NO_WRANGLER_CONFIG" | "ERR_DEPLOY_EMPTY_OUTDIR" | "ERR_DEPLOY_TOO_MANY_FILES" | "ERR_DEPLOY_FILE_TOO_LARGE" | "ERR_DEPLOY_PATH_TRAVERSAL" | "ERR_DEPLOY_INVALID_BRANCH" | "ERR_DEPLOY_NO_TOKEN" | "ERR_DEPLOY_PROJECT_NOT_FOUND" | "ERR_DEPLOY_AUTH_EXPIRED" | "ERR_DEPLOY_AUTH" | "ERR_DEPLOY_NETWORK" | "ERR_DEPLOY_WRANGLER_FAILED" | "ERR_DEPLOY_CONFIG";
-/**
- * The subset of wrangler error `code`s classifyWranglerError can produce from a
- * non-zero wrangler exit.
- */
-type WranglerErrorKind = Extract<DeployErrorCode, "ERR_DEPLOY_PROJECT_NOT_FOUND" | "ERR_DEPLOY_AUTH_EXPIRED" | "ERR_DEPLOY_AUTH" | "ERR_DEPLOY_NETWORK" | "ERR_DEPLOY_WRANGLER_FAILED">;
-/**
- * Configuration for the deploy plugin.
- */
-type Config = {
-  /**
-   * Deploy target. Only Cloudflare Pages is supported in this version.
-   * Defaults to `cloudflare-pages`.
-   */
-  target: "cloudflare-pages";
-  /**
-   * Directory (relative to project root) containing the built site to deploy.
-   * Re-validated against cwd at run() time to block path traversal.
-   * Defaults to `dist`.
-   */
-  outDir: string;
-  /**
-   * Branch treated as the Cloudflare Pages production branch.
-   * Defaults to `main`.
-   */
-  productionBranch?: string;
-  /**
-   * Substrings exempt from entropy-gated secret scrubbing in logged output.
-   * Defaults to `["CLOUDFLARE_ACCOUNT_ID"]`.
-   */
-  scrubAllowlist: string[];
-  /**
-   * Cloudflare compatibility date written into generated wrangler.jsonc.
-   * Defaults to `2024-01-01`.
-   */
-  compatibilityDate?: string;
-  /**
-   * Whether init() also generates a GitHub Actions workflow.
-   * Defaults to `false`.
-   */
-  ci?: boolean;
-};
-/**
- * Result of a successful deploy.
- */
-type DeployResult = {
-  /** The public deployment URL (e.g. https://my-site.pages.dev). */url: string; /** Cloudflare deployment ID parsed from wrangler output. */
-  deploymentId: string; /** The branch that was deployed. */
-  branch: string; /** Wall-clock duration of the deploy in milliseconds. */
-  durationMs: number;
-};
-/**
- * Runtime state for the deploy plugin. Created in createState() and accessed via
- * ctx.state. deploy declares no onStop because nothing here is a long-lived resource.
- */
-type State = {
-  /** Result of the most recent successful deploy, or null before the first run. */lastDeployment: DeployResult | null;
-  /**
-   * Injectable subprocess spawner. Defaults to Bun.spawn. Swapped for a mock in
-   * unit tests so wrangler is never actually invoked. Never reassigned at runtime.
-   */
-  spawn: SpawnFunction;
-};
-/**
- * Options for DeployApi.run.
- */
-type DeployRunOptions = {
-  /**
-   * Branch to deploy. Defaults to config.productionBranch (or "main"). Must match
-   * /^[a-zA-Z0-9/_.-]+$/ — otherwise rejected with ERR_DEPLOY_INVALID_BRANCH.
-   */
-  branch?: string;
-  /**
-   * Whether to run the build before deploying. When false, deploys the existing outDir.
-   * Defaults to `true`.
-   */
-  build?: boolean;
-};
-/**
- * Options for DeployApi.init.
- */
-type DeployInitOptions = {
-  /** Also generate the GitHub Actions workflow. Defaults to config.ci. */ci?: boolean; /** Drift-only mode: report differences without writing any files. Defaults to `false`. */
-  check?: boolean;
-};
-/**
- * Result of an init/scaffold operation.
- */
-type InitResult = {
-  /** Paths written this invocation. */written: string[]; /** Paths skipped because they already exist. */
-  skipped: string[]; /** In check mode: paths whose on-disk content differs from what would be generated. */
-  drifted: string[];
-};
-/**
- * Public API of the deploy plugin (returned from the api factory).
- */
-type Api = {
-  /**
-   * Deploy the built outDir to Cloudflare Pages via the wrangler subprocess.
-   * Runs preflight validators, re-validates the resolved outdir against cwd, guards
-   * the branch argument, spawns wrangler (no shell), scrubs all subprocess output
-   * before logging, records lastDeployment, and emits deploy:complete.
-   *
-   * @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
-   * const result = await app.deploy.run();
-   * console.log(result.url); // https://my-site.pages.dev
-   * @example
-   * await app.deploy.run({ branch: "preview/landing", build: false });
-   */
-  run(options?: DeployRunOptions): Promise<DeployResult>;
-  /**
-   * Return the most recent successful deploy result, or null if none has occurred.
-   * The returned object is read-only (a defensive snapshot).
-   *
-   * @returns The last DeployResult, or null.
-   * @example
-   * const last = app.deploy.getLastDeployment();
-   * if (last) console.log(`Last deployed to ${last.url}`);
-   */
-  getLastDeployment(): Readonly<DeployResult> | null;
-  /**
-   * Generate deploy scaffolding: wrangler.jsonc (slug from site.name() + outDir +
-   * compatibilityDate) and, when ci is enabled, .github/workflows/deploy.yml. Never
-   * overwrites an existing wrangler.jsonc. In check mode, reports drift instead of writing.
-   *
-   * @param options - Optional ci toggle and check (drift-only) mode.
-   * @returns Which files were written, skipped, or would drift.
-   * @example
-   * const out = await app.deploy.init({ ci: true });
-   * // out.written -> ["wrangler.jsonc", ".github/workflows/deploy.yml"]
-   * @example
-   * const drift = await app.deploy.init({ check: true });
-   * if (drift.drifted.length) process.exit(1);
-   */
-  init(options?: DeployInitOptions): Promise<InitResult>;
-};
 //#endregion
 //#region src/plugins/deploy/index.d.ts
 /**
@@ -2239,7 +2811,7 @@ type Api = {
  * });
  * ```
  */
-declare const deployPlugin: import("@moku-labs/core").PluginInstance<"deploy", Config, State, Api, {
+declare const deployPlugin: import("@moku-labs/core").PluginInstance<"deploy", Config$2, State$2, Api$2, {
   "deploy:complete": {
     url: string;
     deploymentId: string;
@@ -2320,6 +2892,8 @@ declare function feedLink(title: string, url: string, type?: string): HeadElemen
  * modified times, author, section, tags, plus a JSON-LD `Article` block and canonical.
  *
  * @param articleMeta - Article metadata (title, description, author, dates, tags, image…).
+ *   `image`, when present, is pushed to `og:image` verbatim and must therefore be
+ *   an absolute URL (this helper does not resolve relative paths against the site).
  * @param canonicalUrl - The article's canonical absolute URL.
  * @returns An ordered array of serializable head elements.
  * @example buildArticleHead({ title: "Hi", author: "A", published: "2026-01-01" }, "https://x/p")
@@ -2346,7 +2920,7 @@ declare function buildArticleHead(articleMeta: ArticleMeta, canonicalUrl: string
  * });
  * ```
  */
-declare const headPlugin: import("@moku-labs/core").PluginInstance<"head", Config$3, State$3, Api$3, {}> & {
+declare const headPlugin: import("@moku-labs/core").PluginInstance<"head", Config$4, State$4, Api$4, {}> & {
   meta: typeof meta;
   og: typeof og;
   twitter: typeof twitter;
@@ -2377,7 +2951,7 @@ declare const headPlugin: import("@moku-labs/core").PluginInstance<"head", Confi
  * });
  * ```
  */
-declare const i18nPlugin: import("@moku-labs/core").PluginInstance<"i18n", Config$5, Record<string, never>, Api$5, {}> & Record<never, never>;
+declare const i18nPlugin: import("@moku-labs/core").PluginInstance<"i18n", Config$6, Record<string, never>, Api$6, {}> & Record<never, never>;
 //#endregion
 //#region src/plugins/log/index.d.ts
 /**
@@ -2402,7 +2976,7 @@ declare const logPlugin: import("@moku-labs/core").CorePluginInstance<"log", Log
  * @example
  * ```ts
  * route("/{lang:?}/{slug}/")
- *   .load(({ slug }) => loadArticle(slug))
+ *   .load((ctx) => loadArticle(ctx.params.slug))
  *   .render((ctx) => <Article a={ctx.data} />)
  *   .head((ctx) => ({ title: ctx.data.title }));
  * ```
@@ -2420,31 +2994,46 @@ declare function route<P extends string>(pattern: P): RouteBuilder<RouteState<P>
  * ```
  */
 declare function defineRoutes<T extends RouteMap>(routes: T): T;
+/**
+ * Build a pure, app-free URL builder from a route map. `toUrl(name, params)` resolves
+ * a route's path by pattern substitution using the SAME `buildUrl` as the runtime
+ * `RouterApi.toUrl`, so the helper and the API can never diverge. It needs no running
+ * app, router instance, base URL, or i18n — just the route map the consumer already
+ * holds at module scope. So components, layouts, and hydrated islands import it
+ * directly: no `app.router` reference, no manual "bind", no module global, no
+ * "not bound" guard, and no createApp ↔ routes cycle.
+ *
+ * @param routes - The route map (typically the value returned by {@link defineRoutes}).
+ * @returns A {@link Urls} builder whose `toUrl` accepts only this map's route names.
+ * @example
+ * ```ts
+ * const url = createUrls(routes);
+ * url.toUrl("article", { lang: "en", slug: "hello" }); // "/en/hello/"
+ * ```
+ */
+declare function createUrls<T extends RouteMap>(routes: T): Urls<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).
+ * and matching. Author routes with {@link route}, then register them the normal config
+ * way via `pluginConfigs.router.routes` (compiled at init). Depends on site (base URL)
+ * and i18n (locales).
  *
- * @example Define routes and choose a render mode
+ * @example Register routes via config, then start/build
  * ```ts
+ * import * as routes from "./routes";
  * const app = createApp({
- *   pluginConfigs: {
- *     router: {
- *       routes: defineRoutes({
- *         home: route("/"),
- *         article: route("/blog/{slug}/")
- *       }),
- *       mode: "hybrid" // "ssg" | "spa" | "hybrid" (default)
- *     }
- *   }
+ *   config: { mode: "hybrid" },               // render mode is GLOBAL config
+ *   pluginConfigs: { router: { routes } }     // declarative route map (a namespace works)
  * });
+ * await app.build.run();    // or: await app.start();  — routes compiled at init
  * ```
  */
 declare const routerPlugin: import("@moku-labs/core").PluginInstance<"router", RouterConfig, RouterState, RouterApi, {}> & {
   route: typeof route;
   defineRoutes: typeof defineRoutes;
+  createUrls: typeof createUrls;
 };
 //#endregion
 //#region src/plugins/site/index.d.ts
@@ -2467,7 +3056,7 @@ declare const routerPlugin: import("@moku-labs/core").PluginInstance<"router", R
  * });
  * ```
  */
-declare const sitePlugin: import("@moku-labs/core").PluginInstance<"site", Config$6, Record<string, never>, Api$6, {}> & Record<never, never>;
+declare const sitePlugin: import("@moku-labs/core").PluginInstance<"site", Config$7, Record<string, never>, Api$7, {}> & Record<never, never>;
 //#endregion
 //#region src/plugins/spa/components.d.ts
 /**
@@ -2568,6 +3157,20 @@ declare function processEnv(): EnvProvider;
  */
 declare function cloudflareBindings(): EnvProvider;
 //#endregion
+//#region src/plugins/content/providers.d.ts
+/**
+ * The node filesystem content provider: reads + renders Markdown from `contentDir`
+ * through the full pipeline. Caches discovery + the unified processor internally.
+ *
+ * @param options - Filesystem + pipeline options (`contentDir`, `shikiTheme`, `trustedContent`, …).
+ * @returns A {@link ContentProvider} backed by the local filesystem.
+ * @example
+ * ```ts
+ * createApp({ pluginConfigs: { content: { providers: [fileSystemContent({ contentDir: "./content" })] } } });
+ * ```
+ */
+declare function fileSystemContent(options: FileSystemContentOptions): ContentProvider;
+//#endregion
 //#region src/index.d.ts
 /**
  * Create and initialize a `@moku-labs/web` application — the Layer-3 entry point.
@@ -2580,28 +3183,29 @@ declare function cloudflareBindings(): EnvProvider;
  *
  * @param options - Optional configuration:
  *  - `pluginConfigs` — per-plugin overrides, keyed by plugin name.
- *  - `config` — global framework config (e.g. `{ mode: "development" }`).
+ *  - `config` — global framework config (e.g. `{ mode: "spa" }`).
  *  - `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:
+ * // Node SSG build — add the node-only plugins, register routes via config, then build:
+ * import * as routes from "./routes";
  * 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}/") }) }
+ *     router: { routes }
  *   }
  * });
- * await app.start();
- * await app.build.run();
+ * await app.build.run();   // routes compiled at init
  * ```
  */
-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, {}> & {
+declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs/core").AnyPluginInstance[] = readonly []>(options?: import("@moku-labs/core").CreateAppOptions<Config$8, Events, (import("@moku-labs/core").PluginInstance<"site", Config$7, Record<string, never>, Api$7, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"i18n", Config$6, Record<string, never>, Api$6, {}> & 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, {}> & {
+  createUrls: typeof createUrls;
+}) | (import("@moku-labs/core").PluginInstance<"head", Config$4, State$4, Api$4, {}> & {
   meta: typeof meta;
   og: typeof og;
   twitter: typeof twitter;
@@ -2626,10 +3230,11 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
     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, {}> & {
+}> & 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$8, Events, (import("@moku-labs/core").PluginInstance<"site", Config$7, Record<string, never>, Api$7, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"i18n", Config$6, Record<string, never>, Api$6, {}> & 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, {}> & {
+  createUrls: typeof createUrls;
+}) | (import("@moku-labs/core").PluginInstance<"head", Config$4, State$4, Api$4, {}> & {
   meta: typeof meta;
   og: typeof og;
   twitter: typeof twitter;
@@ -2670,6 +3275,6 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
  * 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>]>>;
+declare const createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<Config$8, 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 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, createComponent, createPlugin, dataPlugin, defineRoutes, deployPlugin, dotenv, envPlugin, feedLink, headPlugin, hreflang, i18nPlugin, jsonLd, logPlugin, meta, og, processEnv, route, routerPlugin, sitePlugin, spaPlugin, twitter };
+export { types_d_exports as Build, types_d_exports$1 as Cli, types_d_exports$2 as Content, types_d_exports$3 as Data, types_d_exports$4 as Deploy, types_d_exports$5 as Env, types_d_exports$6 as Head, types_d_exports$7 as Log, types_d_exports$8 as Router, types_d_exports$9 as Spa, browserEnv, buildArticleHead, buildPlugin, canonical, cliPlugin, cloudflareBindings, contentPlugin, createApp, createComponent, createPlugin, createUrls, dataPlugin, defineRoutes, deployPlugin, dotenv, envPlugin, feedLink, fileSystemContent, headPlugin, hreflang, i18nPlugin, jsonLd, logPlugin, meta, og, processEnv, route, routerPlugin, sitePlugin, spaPlugin, twitter };