@moku-labs/web 0.6.0 → 1.0.1

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 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
@@ -155,8 +155,9 @@ declare namespace types_d_exports$5 {
  *
  * 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$8 = {
-  /** Runtime mode. Drives log sink defaults, content draft filtering, build minify. */mode: "production" | "development";
+  /** 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
@@ -446,7 +461,7 @@ type Api$7 = {
  * @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 —
@@ -543,7 +558,7 @@ type Api$6 = {
   t(locale: string, key: string): string;
 };
 declare namespace types_d_exports$8 {
-  export { Api$5 as Api, ClientRoute, CompileInput, CompiledRoute, Config$5 as Config, ExtractRouteParams, ExtractSegmentParameter, HeadConfig$1 as HeadConfig, LayoutContext, MatcherTable, Prettify, RouteBuilder, RouteContext, RouteDefinition, RouteHandlers, RouteMap, RouteState, RouterApi, RouterConfig, RouterState, State$5 as State, TypedRoute };
+  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[];
   /**
@@ -1220,7 +1318,7 @@ interface SpaKernelDeps {
   /**
    * 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$3 as Api, BuildCacheEntry, BuildEvents, BuildResult, Config$3 as Config, ExtractApi, OgFont, OgImageConfig, OgPngRenderer, PhaseContext, PhaseEmit, PhaseLog, PhaseName, PhaseRequire, RichOgInput, State$3 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`
@@ -1401,26 +1499,15 @@ type PhaseRequire = <PluginCandidate extends {
  */
 type PhaseContext = {
   /** Mutable per-run build state (caches + runId). */state: State$3; /** Resolved, frozen build config. */
-  readonly config: Readonly<Config$3>; /** Global framework config (mode, etc.). */
+  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
@@ -1521,11 +1608,11 @@ type Config$3 = {
   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. */
@@ -1773,11 +1860,6 @@ type DeployRunOptions = {
    * /^[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.
@@ -1804,14 +1886,14 @@ type Api$2 = {
    * 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.
+   * @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", build: false });
+   * await app.deploy.run({ branch: "preview/landing" });
    */
   run(options?: DeployRunOptions): Promise<DeployResult>;
   /**
@@ -1871,14 +1953,15 @@ type ServerInfo = {
   watching?: string[];
 };
 /**
- * Information rendered after a single `serve()` rebuild: which file changed plus the
- * fresh build summary used to print the "rebuilt N pages" line.
+ * 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/post.md", pageCount: 12, durationMs: 84 };
+ * const info: ReloadInfo = { file: "content", pageCount: 12, durationMs: 84 };
  */
 type ReloadInfo = {
-  /** The changed path that triggered the rebuild. */file: string; /** Number of route pages rendered by the rebuild. */
+  /** 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;
 };
@@ -1930,12 +2013,13 @@ type CliRenderer = {
    */
   serverReady(info: ServerInfo): void;
   /**
-   * Render the post-rebuild line ("~ file" + "✓ rebuilt N pages · Xms · reloaded").
+   * 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 file plus the rebuild's page count and duration.
+   * @param info - The changed watched directory plus the rebuild's page count and duration.
    * @returns Nothing.
    * @example
-   * render.reload({ file: "content/a.md", pageCount: 12, durationMs: 84 });
+   * render.reload({ file: "content", pageCount: 12, durationMs: 84 });
    */
   reload(info: ReloadInfo): void;
   /**
@@ -2257,50 +2341,8 @@ type Api$1 = {
  */
 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, Frontmatter, State };
+  export { Api, Article, ArticleCard, ComputedFields, Config, ContentApiContext, ContentEvents, ContentProvider, ContentProviderState, FileSystemContentOptions, Frontmatter, State };
 }
-/**
- * Configuration for the content plugin.
- *
- * @example
- * ```ts
- * { contentDir: "./src/content", trustedContent: false, shikiTheme: "github-dark" }
- * ```
- */
-type Config = {
-  /** 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 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.)
-   */
-  shikiTheme?: BundledTheme | ThemeRegistrationAny; /** 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 = {
-  /** 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.
  *
@@ -2315,7 +2357,7 @@ type Frontmatter = {
   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. */
+  draft?: boolean; /** Author name. Falls back to the provider's defaultAuthor when omitted. */
   author?: string;
 };
 /**
@@ -2367,6 +2409,119 @@ type ArticleCard = {
   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.
  *
@@ -2386,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; /** Resolved plugin configuration. */
-  config: Config; /** 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.
@@ -2445,29 +2600,29 @@ type Api = {
    */
   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" })]
  *     }
  *   }
  * });
@@ -2491,13 +2646,13 @@ declare namespace types_d_exports$3 {
  * 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
@@ -2519,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;
 };
@@ -2562,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.
@@ -2616,13 +2771,14 @@ 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.
  * ```
@@ -2736,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")
@@ -2818,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 }));
  * ```
@@ -2836,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
@@ -2984,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.
@@ -2996,27 +3183,28 @@ 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$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;
+  createUrls: typeof createUrls;
 }) | (import("@moku-labs/core").PluginInstance<"head", Config$4, State$4, Api$4, {}> & {
   meta: typeof meta;
   og: typeof og;
@@ -3045,6 +3233,7 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
 }> & 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;
+  createUrls: typeof createUrls;
 }) | (import("@moku-labs/core").PluginInstance<"head", Config$4, State$4, Api$4, {}> & {
   meta: typeof meta;
   og: typeof og;
@@ -3088,4 +3277,4 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
  */
 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 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, 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 };