@moku-labs/web 0.1.0-alpha.4 → 0.3.0

package/dist/index.d.cts

@@ -1,136 +1,2108 @@
-import { A as ContentState, B as Events, C as RouterApi, D as Article, E as types_d_exports$7, F as types_d_exports$5, G as EnvState, H as EnvApi, I as SiteApi, J as LogApi, L as SiteState, M as I18nApi, N as I18nConfig, O as ContentApi, P as I18nState, R as types_d_exports$8, S as RouteSpec, T as RouterState, V as createPlugin, X as types_d_exports$6, Y as LogState, _ as BuildApi, a as i18n, b as types_d_exports, c as deploy, d as RouteSpecMap, f as WebAppConfig, g as types_d_exports$2, h as DeployState, i as log, j as types_d_exports$1, k as ContentConfig, l as content, m as DeployConfig, n as router, o as head, p as DeployApi, q as types_d_exports$3, r as route, s as env, t as site, u as build, v as BuildConfig, w as RouterConfig, x as RouteBuilder, y as BuildState, z as Config } from "./index-DaY7vTuo.cjs";
-import { a as meta, d as HeadPluginConfig, f as HeadState, i as jsonLd, l as HeadApi, m as types_d_exports$4, n as feedLink, o as og, r as hreflang, s as twitter, t as canonical } from "./primitives-yZqQkOVR.cjs";
-import { a as SpaConfig, i as SpaApi, n as ComponentDef, o as SpaState, r as ComponentHooks, s as types_d_exports$9, t as createComponent } from "./factory-k-YoScgB.cjs";
-import { spa } from "./plugins/spa/index.cjs";
-import * as _moku_labs_core0 from "@moku-labs/core";
+import { ComponentChildren, VNode } from "preact";
+import { Pluggable, Processor } from "unified";
+import { EmitFn } from "@moku-labs/core";
 
-//#region src/index.d.ts
-declare const kernelCreateApp: <const ExtraPlugins extends readonly _moku_labs_core0.AnyPluginInstance[] = readonly []>(options?: _moku_labs_core0.CreateAppOptions<Config, Events, (_moku_labs_core0.PluginInstance<"site", {
+//#region \0rolldown/runtime.js
+declare namespace types_d_exports$5 {
+  export { ExpectChain, LogApi, LogConfig, LogEntry, LogLevel, LogSink, LogState };
+}
+/**
+ * @file log plugin — type definitions skeleton.
+ *
+ * Core-plugin type surface: config, state, public API, and the supporting
+ * value/sink/assertion-chain types. These types are inferred onto the plugin
+ * via state.ts / api.ts; index.ts passes NO explicit generics.
+ */
+/**
+ * Runtime mode for the log plugin. Selects which default sinks are installed at
+ * onInit. The in-memory trace sink is ALWAYS installed regardless of mode.
+ *
+ * - "test"       — no console sink (keeps test output clean); trace only.
+ * - "silent"     — no console sink (explicit quiet); trace only.
+ * - "dev"        — console sink + trace.
+ * - "production" — console sink + trace.
+ */
+type LogConfig = {
+  /** Sink-selection mode. Defaults to `production`. */mode: "test" | "dev" | "production" | "silent";
+};
+/** Severity level for a log entry. */
+type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * A single recorded log entry.
+ */
+type LogEntry = {
+  /** Severity level. */level: LogLevel; /** Event identifier (free-form string; convention: `domain:action`). */
+  event: string; /** Optional structured payload associated with the event. */
+  data?: unknown; /** Capture timestamp in epoch milliseconds (`Date.now()` at append time). */
+  ts: number; /** Optional originating plugin name. Reserved for future enrichment. */
+  plugin?: string;
+};
+/**
+ * Pluggable output target. Implement this to add console/file/JSON/etc. sinks
+ * WITHOUT changing the log API. Each logged entry is passed to `write` once,
+ * in registration order.
+ */
+type LogSink = {
+  /**
+   * Write a single entry to this sink.
+   *
+   * @param entry - The entry to emit.
+   */
+  write(entry: LogEntry): void;
+};
+/**
+ * Fluent event-trace assertion chain. Reads the live entries array on each call,
+ * so assertions reflect the trace state at call time (not chain-creation time).
+ * Every method returns the same chain for fluent chaining; assertion failures throw.
+ */
+type ExpectChain = {
+  /**
+   * Assert at least one entry has `event`, optionally matching `partial` (subset match).
+   *
+   * @param event - Event name to find.
+   * @param partial - Optional partial data shape (subset-matched against `entry.data`).
+   * @returns The same chain for chaining.
+   * @throws {Error} `LogExpectAssertionError` when no matching entry exists.
+   */
+  toHaveEvent(event: string, partial?: Record<string, unknown>): ExpectChain;
+  /**
+   * Assert all of `events` appear in the trace in the given relative order
+   * (gaps allowed; later events must occur after earlier ones).
+   *
+   * @param events - Ordered list of event names.
+   * @returns The same chain for chaining.
+   * @throws {Error} `LogExpectAssertionError` when the ordering cannot be satisfied.
+   */
+  toHaveEventInOrder(events: string[]): ExpectChain;
+  /**
+   * Assert NO entry has `event` (optionally narrowed by `partial`).
+   *
+   * @param event - Event name that must be absent.
+   * @param partial - Optional partial data shape; only matching entries violate the assertion.
+   * @returns The same chain for chaining.
+   * @throws {Error} `LogExpectAssertionError` when a matching entry exists.
+   */
+  toNotHaveEvent(event: string, partial?: Record<string, unknown>): ExpectChain;
+};
+/**
+ * Internal mutable state for the log plugin. Created fresh per createApp construction.
+ */
+type LogState = {
+  /** Append-only ordered trace of every logged entry (the in-memory trace sink's backing store). */entries: LogEntry[]; /** Registered output sinks. Each entry is written to every sink in order. */
+  sinks: LogSink[];
+};
+/** Public log API injected as `ctx.log` on every regular plugin and exposed as `app.log`. */
+type LogApi = {
+  /**
+   * Append an `info` entry and fan it out to every sink.
+   *
+   * @param event - Event identifier (convention: `domain:action`).
+   * @param data - Optional structured payload.
+   */
+  info(event: string, data?: unknown): void;
+  /**
+   * Append a `debug` entry and fan it out to every sink.
+   *
+   * @param event - Event identifier (convention: `domain:action`).
+   * @param data - Optional structured payload.
+   */
+  debug(event: string, data?: unknown): void;
+  /**
+   * Append a `warn` entry and fan it out to every sink.
+   *
+   * @param event - Event identifier (convention: `domain:action`).
+   * @param data - Optional structured payload.
+   */
+  warn(event: string, data?: unknown): void;
+  /**
+   * Append an `error` entry. When `error` is provided, its `message`/`stack` are
+   * merged into `data` under an `error` key; otherwise `data` is recorded as-is.
+   *
+   * @param event - Event identifier (convention: `domain:action`).
+   * @param data - Optional structured payload.
+   * @param error - Optional originating Error to merge into `data`.
+   */
+  error(event: string, data?: unknown, error?: Error): void;
+  /**
+   * Return a frozen snapshot of the entries recorded so far (a fresh copy).
+   *
+   * @returns A readonly, frozen copy of the recorded entries.
+   */
+  trace(): readonly LogEntry[];
+  /**
+   * Return a fluent assertion chain bound to the live entries array.
+   *
+   * @returns A fresh {@link ExpectChain}.
+   */
+  expect(): ExpectChain;
+  /**
+   * Register an additional output sink at runtime.
+   *
+   * @param sink - The sink to add to the fan-out list.
+   */
+  addSink(sink: LogSink): void; /** Clear all recorded entries while keeping registered sinks. */
+  reset(): void;
+};
+declare namespace types_d_exports$3 {
+  export { EnvApi, EnvConfig, EnvProvider, EnvState, EnvVarSpec };
+}
+/**
+ * @file env plugin — public + boundary type definitions.
+ */
+/**
+ * A source of raw environment values.
+ *
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const custom: EnvProvider = {
+ *   name: "vault",
+ *   load: () => ({ DB_URL: readVaultSecret("db") })
+ * };
+ * ```
+ */
+interface EnvProvider {
+  /** Human-readable provider name, used in diagnostics and error messages. */
   name: string;
-  url: string;
-  author: string;
+  /**
+   * Reads this provider's current view of the environment.
+   *
+   * @returns A flat record of variable names to string values. Keys the
+   *   provider cannot supply must be omitted or set to `undefined`.
+   */
+  load(): Record<string, string | undefined>;
+}
+/**
+ * Declares how a single environment variable is validated and exposed.
+ *
+ * @example
+ * ```ts
+ * const port: EnvVarSpec = { public: false, required: false, default: "3000" };
+ * const apiBase: EnvVarSpec = { public: true }; // key must start with PUBLIC_
+ * const token: EnvVarSpec = { public: false, required: true, secret: true };
+ * ```
+ */
+interface EnvVarSpec {
+  /**
+   * Whether the variable is safe to ship to the browser. When `true`, the key
+   * **must** start with {@link EnvConfig.publicPrefix} (cross-checked at
+   * `onInit`), and the variable is included in {@link EnvApi.getPublicMap}.
+   */
+  public: boolean;
+  /** Whether resolution fails if the variable is still undefined after defaults. */
+  required?: boolean;
+  /** Value applied when no provider supplies the variable. */
+  default?: string;
+  /**
+   * Marks the variable as a secret for documentation / tooling. Has no runtime
+   * effect on resolution, but secrets are never permitted to be `public`.
+   */
+  secret?: boolean;
+}
+/**
+ * Configuration for the {@link envPlugin} core plugin.
+ *
+ * @example
+ * ```ts
+ * createCoreConfig("web", {
+ *   plugins: [envPlugin],
+ *   pluginConfigs: {
+ *     env: {
+ *       schema: {
+ *         PUBLIC_API_URL: { public: true, default: "/api" },
+ *         SESSION_SECRET: { public: false, required: true, secret: true }
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
+ */
+type EnvConfig = {
+  /** Per-variable validation + exposure rules, keyed by variable name. */schema: Record<string, EnvVarSpec>;
+  /**
+   * 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()]`.
+   */
+  providers: EnvProvider[];
+  /**
+   * Prefix that public variable names must carry. Bidirectionally enforced at
+   * `onInit`. Framework default is `"PUBLIC_"`.
+   */
+  publicPrefix: string;
+};
+/**
+ * Internal env plugin state: the resolved variable table and its public subset.
+ * Both maps are populated and frozen (via `freezeMap`) during `onInit`.
+ *
+ * Exported only to type the `createState` / `api` / `validate` boundary —
+ * consumers use {@link EnvApi}, never `EnvState`.
+ */
+interface EnvState {
+  /** All validated variables that resolved to a defined value (incl. defaults). */
+  resolved: Map<string, string>;
+  /** Subset of `resolved` where `schema[key].public === true`. */
+  publicMap: Map<string, string>;
+}
+/**
+ * The resolved-environment accessor mounted at `ctx.env`. Built by the plugin's
+ * `api` factory over `ctx.state` ({@link EnvState}).
+ *
+ * Available after `onInit` (i.e. inside any plugin's lifecycle and in consumer
+ * code). All accessors read from the frozen `resolved` / `publicMap` maps;
+ * mutation is impossible.
+ *
+ * @example
+ * ```ts
+ * const url = ctx.env.get("PUBLIC_API_URL"); // string | undefined
+ * const token = ctx.env.require("DEPLOY_TOKEN"); // string, or throws
+ * ```
+ */
+type EnvApi = {
+  /**
+   * Reads a resolved variable.
+   *
+   * @param key - Variable name.
+   * @returns The value, or `undefined` if not present / not in schema.
+   */
+  get(key: string): string | undefined;
+  /**
+   * Reads a variable that must exist.
+   *
+   * @param key - Variable name.
+   * @returns The value.
+   * @throws {Error} If the variable is undefined.
+   */
+  require(key: string): string;
+  /**
+   * Tests presence of a resolved variable.
+   *
+   * @param key - Variable name.
+   * @returns `true` if a value is present.
+   */
+  has(key: string): boolean;
+  /**
+   * Returns all public variables as a frozen plain object — convenient for
+   * spreading into a serializable payload.
+   *
+   * @returns A frozen `Record` of public variable names to values.
+   */
+  getPublic(): Readonly<Record<string, string>>;
+  /**
+   * Returns the frozen map of public variables. This is the **sole** intended
+   * input to a build-time `define` injection: every entry is safe to inline
+   * into the browser bundle.
+   *
+   * @returns The frozen public map.
+   */
+  getPublicMap(): ReadonlyMap<string, string>;
+};
+//#endregion
+//#region src/plugins/env/index.d.ts
+/**
+ * Core plugin that resolves, validates, and freezes the environment at `onInit`,
+ * exposing a read-only accessor at `ctx.env`. No `onStart`/`onStop` — holds no resource.
+ *
+ * @example
+ * ```ts
+ * createApp({ pluginConfigs: { env: { schema: { PUBLIC_API_URL: { public: true } } } } });
+ * ```
+ */
+declare const envPlugin: import("@moku-labs/core").CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>;
+//#endregion
+//#region src/config.d.ts
+/**
+ * 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";
+};
+/**
+ * Framework event contract. Empty base — each plugin declares its own events
+ * via the `events` register callback (spec/14 §2).
+ */
+type Events = {};
+//#endregion
+//#region src/plugins/site/types.d.ts
+/**
+ * @file site plugin — public type definitions (Config + Api).
+ */
+/**
+ * Configuration for the site plugin — global, frozen site metadata.
+ *
+ * All four fields are required at runtime. The framework ships empty-string
+ * defaults and `onInit` fails fast (at `createApp`) if `name` is blank or
+ * `url` is not a valid absolute URL. Consumers MUST supply real values via
+ * `pluginConfigs.site`.
+ *
+ * @example
+ * ```ts
+ * createApp({
+ *   pluginConfigs: {
+ *     site: {
+ *       name: "My Blog",
+ *       url: "https://blog.dev",
+ *       author: "Alex",
+ *       description: "A personal blog about web frameworks."
+ *     }
+ *   }
+ * });
+ * ```
+ */
+type Config$6 = {
+  /** 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. */
   description: string;
-}, SiteState, SiteApi, {}> & Record<never, never>) | (_moku_labs_core0.PluginInstance<"i18n", I18nConfig, I18nState<readonly string[]>, I18nApi<readonly string[]>, {}> & Record<never, never>) | (_moku_labs_core0.PluginInstance<"content", ContentConfig, ContentState, ContentApi, {
-  'content:ready': {
-    articles: Map<string, Article[]>;
-  };
-  'content:invalidated': {
-    paths: string[];
+};
+/**
+ * Public API of the site plugin — read-only accessors over frozen global
+ * site metadata, plus canonical URL construction.
+ */
+type Api$6 = {
+  /**
+   * Returns the configured site name.
+   *
+   * @returns {string} The human-readable site name from `config.name`.
+   * @example
+   * ```ts
+   * app.site.name(); // "My Blog"
+   * ```
+   */
+  name: () => string;
+  /**
+   * Returns the configured absolute base URL of the site.
+   *
+   * @returns {string} The base URL from `config.url`, e.g. "https://blog.dev".
+   * @example
+   * ```ts
+   * app.site.url(); // "https://blog.dev"
+   * ```
+   */
+  url: () => string;
+  /**
+   * Returns the configured site author/byline.
+   *
+   * @returns {string} The author from `config.author`.
+   * @example
+   * ```ts
+   * app.site.author(); // "Alex"
+   * ```
+   */
+  author: () => string;
+  /**
+   * Returns the configured site description.
+   *
+   * @returns {string} The description from `config.description`.
+   * @example
+   * ```ts
+   * app.site.description(); // "A personal blog about web frameworks."
+   * ```
+   */
+  description: () => string;
+  /**
+   * Joins a path against the configured base `url` to produce an absolute
+   * canonical URL. An empty path (or "/") returns the base URL unchanged.
+   *
+   * @param {string} path - Relative path for the page, e.g. "/about/" or "blog/post/".
+   * @returns {string} The absolute canonical URL, e.g. "https://blog.dev/about/".
+   * @example
+   * ```ts
+   * app.site.canonical("/about/"); // "https://blog.dev/about/"
+   * app.site.canonical("/");       // "https://blog.dev"
+   * ```
+   */
+  canonical: (path: string) => string;
+};
+//#endregion
+//#region src/plugins/i18n/types.d.ts
+/**
+ * @file i18n plugin — public type definitions (Config + Api).
+ */
+/**
+ * i18n plugin configuration. Mirrors the legacy `I18nConfig` shape.
+ *
+ * `locales` and `defaultLocale` are required and validated in `onInit`. The
+ * optional maps default to empty objects so every lookup method is total —
+ * lookups return `undefined` on a miss and `t()` falls back to the key.
+ *
+ * @example
+ * ```ts
+ * {
+ *   locales: ["en", "uk"],
+ *   defaultLocale: "en",
+ *   localeNames: { en: "English", uk: "Українська" },
+ *   ogLocaleMap: { en: "en_US", uk: "uk_UA" },
+ *   translations: { en: { "nav.home": "Home" }, uk: { "nav.home": "Головна" } }
+ * }
+ * ```
+ */
+type Config$5 = {
+  readonly locales: readonly string[];
+  readonly defaultLocale: string;
+  readonly localeNames?: Record<string, string>;
+  readonly ogLocaleMap?: Record<string, string>;
+  readonly translations?: Record<string, Record<string, string>>;
+};
+/**
+ * Public API of the i18n plugin. Injected as `app.i18n` and reachable from
+ * other plugins via `ctx.require(i18nPlugin)`.
+ */
+type Api$5 = {
+  /**
+   * Returns the configured supported locales in declared order.
+   *
+   * @returns The configured `locales` list (priority/display order).
+   * @example
+   * ```ts
+   * app.i18n.locales(); // ["en", "uk"]
+   * ```
+   */
+  locales(): readonly string[];
+  /**
+   * Returns the fallback locale used when a requested locale is absent.
+   *
+   * @returns The configured `defaultLocale`.
+   * @example
+   * ```ts
+   * app.i18n.defaultLocale(); // "en"
+   * ```
+   */
+  defaultLocale(): string;
+  /**
+   * Membership guard: whether `x` is one of the supported locales.
+   *
+   * @param x - Candidate locale code.
+   * @returns `true` if `x ∈ locales`, else `false`.
+   * @example
+   * ```ts
+   * app.i18n.isLocale("uk"); // true
+   * ```
+   */
+  isLocale(x: string): boolean;
+  /**
+   * Human-readable display name for a locale.
+   *
+   * @param locale - Locale code to look up.
+   * @returns The display name, or `undefined` if unmapped.
+   * @example
+   * ```ts
+   * app.i18n.localeName("uk"); // "Українська"
+   * ```
+   */
+  localeName(locale: string): string | undefined;
+  /**
+   * Open Graph `og:locale` value for a locale.
+   *
+   * @param locale - Locale code to look up.
+   * @returns The `og:locale` value (e.g. `"en_US"`), or `undefined` if unmapped.
+   * @example
+   * ```ts
+   * app.i18n.ogLocale("en"); // "en_US"
+   * ```
+   */
+  ogLocale(locale: string): string | undefined;
+  /**
+   * Translate `key` for `locale` with a deterministic fallback chain
+   * (requested locale → default locale → the key itself).
+   *
+   * @param locale - Requested locale code.
+   * @param key - Translation key (e.g. `"nav.home"`).
+   * @returns The translated value, the default-locale value, or `key`.
+   * @example
+   * ```ts
+   * app.i18n.t("uk", "nav.home"); // "Головна"
+   * ```
+   */
+  t(locale: string, key: string): string;
+};
+declare namespace types_d_exports$6 {
+  export { Api$4 as Api, CompileInput, CompiledRoute, Config$4 as Config, ExtractRouteParams, ExtractSegmentParameter, HeadConfig$1 as HeadConfig, MatcherTable, Prettify, RouteBuilder, RouteContext, RouteDefinition, RouteHandlers, RouteMap, RouteState, RouterApi, RouterConfig, RouterState, State$4 as State, TypedRoute };
+}
+/**
+ * Param contribution of a single path segment. `{name:?}` / `:name?` → optional;
+ * `{name}` / `:name` → required; static segments contribute nothing.
+ *
+ * @example
+ * type S = ExtractSegmentParameter<"{slug}">; // { slug: string }
+ */
+type ExtractSegmentParameter<Segment extends string> = Segment extends `{${infer Name}:?}` ? { [K in Name]?: string } : Segment extends `{${infer Name}}` ? { [K in Name]: string } : Segment extends `:${infer Name}?` ? { [K in Name]?: string } : Segment extends `:${infer Name}` ? { [K in Name]: string } : Record<never, never>;
+/**
+ * Template-literal type that extracts path params from a URL pattern by walking
+ * one `/`-delimited segment at a time (so mixed required/optional patterns infer
+ * correctly). `{name}` / `:name` become required; `{name:?}` becomes optional.
+ *
+ * @example
+ * type P = ExtractRouteParams<"/{lang:?}/{slug}/">; // { lang?: string; slug: string }
+ */
+type ExtractRouteParams<P extends string> = P extends `${infer Head}/${infer Tail}` ? ExtractSegmentParameter<Head> & ExtractRouteParams<Tail> : ExtractSegmentParameter<P>;
+/** Flattens an intersection type into a single object literal for readable IntelliSense. */
+type Prettify<T> = { [K in keyof T]: T[K] };
+/**
+ * Accumulating generic carried by `RouteBuilder` as the fluent chain grows.
+ * `P` is the pattern's extracted params; `D` is the data type produced by `.load()`.
+ */
+interface RouteState<P extends string = string, D = unknown> {
+  /** Path params inferred from the pattern. */
+  readonly params: Prettify<ExtractRouteParams<P>>;
+  /** Loaded data type produced by `.load()` (widened only by `.load()`). */
+  readonly data: D;
+}
+/** Render-time context handed to `.render()` / `.head()`; `data` is `.load()`'s return. */
+interface RouteContext<S extends RouteState> {
+  /** Resolved path params. */
+  readonly params: S["params"];
+  /** Loaded data (the return value of this route's `.load()`). */
+  readonly data: S["data"];
+  /** Active locale for this render. */
+  readonly locale: string;
+}
+/** Head metadata produced by a route's `.head()` handler. */
+interface HeadConfig$1 {
+  /** Document title. */
+  readonly title?: string;
+  /** Meta description. */
+  readonly description?: string;
+  /** Arbitrary extra head fields. */
+  readonly [key: string]: unknown;
+}
+/**
+ * Fluent route builder. Each chain method returns the same builder with a
+ * (possibly widened) state generic. Only `.load()` widens the data type `D`.
+ */
+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<{
+    readonly params: S["params"];
+    readonly data: Awaited<D>;
+  }>;
+  /** Attach a layout wrapper component. */
+  layout(component: (children: ComponentChildren) => VNode): RouteBuilder<S>;
+  /** Attach the page render handler. */
+  render(handler: (ctx: RouteContext<S>) => VNode): RouteBuilder<S>;
+  /** Attach the head/SEO handler. */
+  head(handler: (ctx: RouteContext<S>) => HeadConfig$1): RouteBuilder<S>;
+  /** Attach a static-generation param producer. */
+  generate(handler: (locale: string) => S["params"][] | Promise<S["params"][]>): RouteBuilder<S>;
+  /** Attach an arbitrary metadata bag. */
+  meta(meta: Record<string, unknown>): RouteBuilder<S>;
+  /** Attach a JSON serializer for the route's data. */
+  toJson(handler: (ctx: RouteContext<S>) => unknown): RouteBuilder<S>;
+  /** Override the output file-path producer. */
+  toFile(handler: (params: S["params"]) => string): RouteBuilder<S>;
+}
+/** 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;
+  /** Layout wrapper. */
+  readonly layout?: (children: ComponentChildren) => VNode;
+  /** Page renderer. */
+  readonly render?: (ctx: RouteContext<RouteState>) => VNode;
+  /** Head/SEO producer. */
+  readonly head?: (ctx: RouteContext<RouteState>) => HeadConfig$1;
+  /** Static-generation param producer. */
+  readonly generate?: (locale: string) => unknown[] | Promise<unknown[]>;
+  /** JSON serializer. */
+  readonly toJson?: (ctx: RouteContext<RouteState>) => unknown;
+  /** Output file-path producer. */
+  readonly toFile?: (params: Record<string, string>) => string;
+}
+/**
+ * A single route definition: the (erased) carrier produced by `route(...)`.
+ * Build consumes `_handlers` via `manifest()`; per-route param/data integrity
+ * is a call-site property established before config erasure.
+ */
+interface RouteDefinition {
+  /** URL pattern string, e.g. `/{lang:?}/{slug}/`. */
+  readonly pattern: string;
+  /** Metadata bag accumulated from `.meta()` (named `_meta` to avoid clashing with the `.meta()` builder method). */
+  readonly _meta: Record<string, unknown>;
+  /** Build-time handler bag (load/render/head/generate/toJson/toFile). */
+  readonly _handlers: RouteHandlers;
+}
+/**
+ * Map of route name → route definition. The element type is intentionally the
+ * base (erased) `RouteDefinition`; this is the documented generic-erasure boundary.
+ */
+type RouteMap = Record<string, RouteDefinition>;
+/**
+ * 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()`.
+ */
+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";
+};
+/** A resolved route exposing URL utilities with typed params (port of legacy TypedRoute). */
+interface TypedRoute<TParams = Record<string, string>> {
+  /** URL pattern string, e.g. `/{lang:?}/{slug}/`. */
+  readonly pattern: string;
+  /** Route name key. */
+  readonly name: string;
+  /** Metadata bag from `.meta()`. */
+  readonly meta: Record<string, unknown>;
+  /** Build a URL from typed params. */
+  toUrl(params: TParams): string;
+  /** Build an output file path from typed params. */
+  toFile(params: TParams): string;
+  /** Match a pathname into typed params, or `null`. */
+  match(pathname: string): TParams | null;
+}
+/** A single compiled route entry: name, pattern, specificity, matchers, URL utilities. */
+interface CompiledRoute {
+  /** Route name key from the route map. */
+  readonly name: string;
+  /** Original user pattern, e.g. `/{lang:?}/{slug}/`. */
+  readonly pattern: string;
+  /** Dynamic-segment count (lower = more specific = matched first). */
+  readonly dynamicSegmentCount: number;
+  /** Pre-built URLPattern matchers (lang-aware + bare fallback). */
+  readonly matchers: {
+    readonly withLang: URLPattern;
+    readonly bare: URLPattern;
   };
-}> & Record<never, never>) | (_moku_labs_core0.PluginInstance<"router", RouterConfig, RouterState, RouterApi, {
-  'router:registered': {
-    routeCount: number;
+  /** Resolve pathname into params (withLang first, then bare with defaultLocale injected). */
+  readonly matchFn: (pathname: string) => Record<string, string> | null;
+  /** Build a URL from params. */
+  readonly toUrl: (params: Record<string, string>) => string;
+  /** Build an output file path from params. */
+  readonly toFile: (params: Record<string, string>) => string;
+  /** The original (opaque) RouteDefinition — preserved for `manifest()`. */
+  readonly definition: RouteDefinition;
+  /** Route metadata bag from `.meta()`. */
+  readonly meta: Record<string, unknown>;
+}
+/** The compiled matcher table (immutable once `onInit` assigns it). */
+interface MatcherTable {
+  /** All compiled routes, sorted by specificity (fewest dynamic segments first). */
+  readonly compiled: readonly CompiledRoute[];
+  /** Name → CompiledRoute index for O(1) `toUrl(name, ...)` lookups. */
+  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).
+ */
+interface RouterState {
+  /** Compiled matcher table; `null` until `onInit` assigns it. */
+  table: MatcherTable | null;
+}
+/** Plain-data input to `compileRoutes` — resolved DATA only, never the plugin ctx. */
+interface CompileInput {
+  /** The opaque route map from config. */
+  readonly routes: RouteMap;
+  /** Resolved render mode. */
+  readonly mode: "ssg" | "spa" | "hybrid";
+  /** Site base URL (from `ctx.require(sitePlugin).url()`). */
+  readonly baseUrl: string;
+  /** Available locales (from `ctx.require(i18nPlugin).locales()`). */
+  readonly locales: readonly string[];
+  /** Default locale used for bare-pattern fallback. */
+  readonly defaultLocale: string;
+}
+/** Public API exposed via `ctx.require(routerPlugin)`. */
+type RouterApi = {
+  /**
+   * Match a pathname against the compiled route table (specificity-sorted).
+   *
+   * @param pathname - URL pathname, e.g. `/en/hello/`.
+   * @returns `{ params, route }` for the most specific match, or `null` if none.
+   * @example
+   * const hit = ctx.require(routerPlugin).match("/en/hello/");
+   */
+  match(pathname: string): {
+    params: Record<string, string>;
+    route: RouteDefinition;
+  } | null;
+  /**
+   * Build a URL for a named route from params.
+   *
+   * @param routeName - Route name key from the route map.
+   * @param params - Param values to substitute into the pattern.
+   * @returns The resolved URL string (e.g. `/en/hello/`).
+   * @throws {Error} If `routeName` is unknown.
+   * @example
+   * ctx.require(routerPlugin).toUrl("article", { lang: "en", slug: "hello" });
+   */
+  toUrl(routeName: string, params: Record<string, string>): string;
+  /**
+   * All resolved routes as typed URL utilities, in specificity order.
+   *
+   * @returns Read-only array of resolved typed routes.
+   * @example
+   * for (const r of ctx.require(routerPlugin).entries()) { r.toUrl({ slug: "x" }); }
+   */
+  entries(): readonly TypedRoute[];
+  /**
+   * The typed route set for build-time consumption (the KEY mechanism). An API
+   * return, NOT a config readback — preserves per-route types despite config erasure.
+   *
+   * @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"); }
+   */
+  manifest(): readonly RouteDefinition[];
+};
+/** Re-export under the canonical `Config` name for the plugin-types barrel. */
+type Config$4 = RouterConfig;
+/** Re-export under the canonical `State` name for the plugin-types barrel. */
+type State$4 = RouterState;
+/** Re-export under the canonical `Api` name for the plugin-types barrel. */
+type Api$4 = RouterApi;
+declare namespace types_d_exports$1 {
+  export { Api$3 as Api, Article, ArticleCard, ComputedFields, Config$3 as Config, ContentApiContext, ContentEvents, Frontmatter, State$3 as State };
+}
+/**
+ * Configuration for the content plugin.
+ *
+ * @example
+ * ```ts
+ * { contentDir: "./src/content", trustedContent: false, shikiTheme: "github-dark" }
+ * ```
+ */
+type Config$3 = {
+  /** Absolute or project-relative path to the content directory. Validated in onInit. */contentDir: string;
+  /**
+   * SECURITY GATE. When false (the default), rehype-sanitize runs as the final
+   * pipeline step. Set true ONLY for fully author-controlled Markdown — true
+   * disables sanitize and trusts all raw HTML.
+   */
+  trustedContent: boolean; /** Additional remark plugins, concatenated AFTER framework defaults. Defaults to []. */
+  extraRemarkPlugins?: readonly Pluggable[]; /** Additional rehype plugins, concatenated after custom transforms, before Shiki + sanitize. Defaults to []. */
+  extraRehypePlugins?: readonly Pluggable[]; /** Shiki theme name for syntax highlighting. Defaults to "github-dark". */
+  shikiTheme?: string; /** Author applied to articles whose frontmatter omits author. Defaults to undefined. */
+  defaultAuthor?: string;
+};
+/**
+ * Internal mutable state for the content plugin.
+ *
+ * @example
+ * ```ts
+ * { processor: null, articles: new Map(), slugs: null, dirtyPaths: new Set() }
+ * ```
+ */
+type State$3 = {
+  /** Lazily-created unified processor singleton. null until first render()/loadAll(). */processor: Processor | null; /** Article cache keyed locale -> (slug -> Article). Starts empty. */
+  articles: Map<string, Map<string, Article>>; /** Discovered, sorted slug list cached after first disk scan. null until first discovery. */
+  slugs: string[] | null; /** Paths marked stale by invalidate(); next loadAll() re-reads only these. Starts empty. */
+  dirtyPaths: Set<string>;
+};
+/**
+ * YAML frontmatter parsed from each article file.
+ *
+ * @example
+ * ```ts
+ * { title: "Hello", date: "2026-01-15", description: "Intro", tags: [], language: "en" }
+ * ```
+ */
+type Frontmatter = {
+  /** Article title. Required. */title: string; /** ISO 8601 date string, e.g. "2026-01-15". Required. */
+  date: string; /** Short summary used in cards, feeds, and meta description. Required. */
+  description: string; /** Topic tags. Required (may be empty array). */
+  tags: string[]; /** Source language code of this file. Required. */
+  language: string; /** Draft flag. Excluded from output in production mode. Defaults to false. */
+  draft?: boolean; /** Author name. Falls back to config.defaultAuthor when omitted. */
+  author?: string;
+};
+/**
+ * Fields computed by the pipeline (not authored in frontmatter).
+ *
+ * @example
+ * ```ts
+ * { slug: "hello", readingTime: 1, contentId: "hello", status: "published", wordCount: 42 }
+ * ```
+ */
+type ComputedFields = {
+  /** Article directory name. */slug: string; /** Reading time in minutes (ceiling, minimum 1). */
+  readingTime: number; /** Stable content identifier (slug by default). */
+  contentId: string; /** Derived publication status. */
+  status: "published" | "draft"; /** Word count from the source body. */
+  wordCount: number;
+};
+/**
+ * A fully processed, render-ready article.
+ *
+ * @example
+ * ```ts
+ * { frontmatter, computed, html: "<p>…</p>", locale: "en", isFallback: false, url: "/en/hello/" }
+ * ```
+ */
+type Article = {
+  /** Parsed frontmatter. */frontmatter: Frontmatter; /** Pipeline-computed metadata. */
+  computed: ComputedFields; /** Sanitized rendered HTML body. */
+  html: string; /** Locale this Article instance represents (the requested locale, even on fallback). */
+  locale: string; /** True when the default-locale file was used because the requested locale was missing. */
+  isFallback: boolean; /** Canonical URL for this article in this locale. */
+  url: string;
+};
+/**
+ * Lightweight projection of Article for cards/lists.
+ *
+ * @example
+ * ```ts
+ * { contentId: "hello", status: "published", title: "Hello", date: "2026-01-15", description: "Intro", tags: [], readingTime: 1, url: "/en/hello/" }
+ * ```
+ */
+type ArticleCard = {
+  /** Stable content identifier. */contentId: string; /** Derived publication status. */
+  status: "published" | "draft"; /** Article title. */
+  title: string; /** ISO 8601 date string. */
+  date: string; /** Short summary. */
+  description: string; /** Topic tags. */
+  tags: string[]; /** Reading time in minutes. */
+  readingTime: number; /** Canonical URL for this article in this locale. */
+  url: string;
+};
+/**
+ * Notification-only events emitted by the content plugin.
+ *
+ * @example
+ * ```ts
+ * emit("content:ready", { locales: ["en"], articleCount: 3 });
+ * ```
+ */
+type ContentEvents = {
+  /** All articles loaded across locales. */"content:ready": {
+    locales: readonly string[];
+    articleCount: number;
+  }; /** Article paths marked stale for dev rebuild. */
+  "content:invalidated": {
+    paths: readonly string[];
   };
-}> & Record<never, never>) | (_moku_labs_core0.PluginInstance<"head", HeadPluginConfig, HeadState, HeadApi, {}> & Record<never, never>) | (_moku_labs_core0.PluginInstance<"build", BuildConfig, BuildState, BuildApi, {
-  'build:phase': {
-    phase: "bundle" | "content" | "pages" | "feeds" | "sitemap" | "og" | "images";
+};
+/**
+ * Kernel-free domain context handed to createContentApi by the wiring harness.
+ * Carries ctx.state (mutable escape hatch), config, global, emit, and the
+ * i18n-derived locale/url helpers — so api.ts stays free of createPlugin/ctx.
+ *
+ * @example
+ * ```ts
+ * const apiContext: ContentApiContext = { state, config, global, emit, locales, defaultLocale, articleToUrl };
+ * ```
+ */
+type ContentApiContext = {
+  /** Mutable plugin state (article cache + lazy processor). */state: State$3; /** Resolved plugin configuration. */
+  config: Config$3; /** Global framework configuration (mode, etc.). */
+  global: {
+    mode: "production" | "development";
+  }; /** Emit a registered content event. */
+  emit: <K extends keyof ContentEvents>(event: K, payload: ContentEvents[K]) => void; /** Active locale codes from i18n. */
+  locales: () => readonly string[]; /** Default locale code from i18n (fallback source). */
+  defaultLocale: () => string; /** Build a canonical article URL for a locale + slug. */
+  articleToUrl: (locale: string, slug: string) => string;
+};
+/**
+ * Public API for the content plugin.
+ *
+ * @example
+ * ```ts
+ * const map = await app.content.loadAll();
+ * ```
+ */
+type Api$3 = {
+  /**
+   * Load every article across every active locale, returning a locale-keyed
+   * map of date-descending Article arrays. Emits content:ready.
+   */
+  loadAll(): Promise<Map<string, Article[]>>;
+  /**
+   * Resolve and render a single article for one locale, with locale fallback.
+   *
+   * @param slug - Article directory name.
+   * @param locale - Requested locale code.
+   */
+  load(slug: string, locale: string): Promise<Article>;
+  /**
+   * Render a raw Markdown string to HTML through the full pipeline.
+   *
+   * @param md - Raw Markdown source.
+   */
+  renderMarkdown(md: string): Promise<string>;
+  /**
+   * Mark file paths stale for incremental dev rebuilds. Emits content:invalidated.
+   *
+   * @param paths - File paths to invalidate.
+   */
+  invalidate(paths: readonly string[]): void;
+  /**
+   * Project a full Article to a lightweight ArticleCard for list/grid rendering.
+   *
+   * @param article - The source article.
+   */
+  articleToCard(article: Article): ArticleCard;
+};
+declare namespace types_d_exports$4 {
+  export { Api$2 as Api, ArticleMeta, Config$2 as Config, HeadConfig, HeadDefaults, HeadElement, ResolvedRoute, State$2 as State };
+}
+/**
+ * @file head plugin — type definitions skeleton
+ */
+/**
+ * Configuration for the `head` plugin.
+ *
+ * All fields are optional; sensible empty/identity defaults apply. Site-level values
+ * (title, description, base URL) are owned by the `site` plugin and read at render time.
+ *
+ * @example
+ * ```ts
+ * const config: Config = { titleTemplate: "%s — Moku" };
+ * ```
+ */
+type Config$2 = {
+  /** 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`. */
+  twitterHandle?: string;
+};
+/**
+ * Internal head state: a single `defaults` slot holding the normalized head defaults.
+ *
+ * `createState` initializes `defaults` to `null`; `onInit` assigns the normalized snapshot
+ * exactly once. The field is mutable (assigned in `onInit`) and nullable (initial value
+ * before `onInit`).
+ *
+ * @example
+ * ```ts
+ * const state: State = { defaults: null };
+ * ```
+ */
+type State$2 = {
+  /** Normalized head defaults, assigned once in `onInit` (initially `null`). */defaults: HeadDefaults | null;
+};
+/**
+ * The normalized, resolved head defaults snapshot built from `Config` in `onInit` and
+ * read by `render`.
+ *
+ * @example
+ * ```ts
+ * const defaults: HeadDefaults = { twitterCard: "summary_large_image" };
+ * ```
+ */
+type HeadDefaults = {
+  /** Title template carried over from config (validated to contain `%s`). */readonly titleTemplate?: string; /** Default Open Graph image URL. */
+  readonly defaultOgImage?: string; /** Resolved Twitter card type (defaulted to `"summary_large_image"`). */
+  readonly twitterCard: "summary" | "summary_large_image"; /** Default Twitter site handle. */
+  readonly twitterHandle?: string;
+};
+/**
+ * A serializable descriptor for a single `<head>` tag.
+ *
+ * Deliberately a PLAIN serializable object (NOT a Preact `VNode`) so `head` stays
+ * decoupled from any renderer and can be produced/consumed in build (string) and in the
+ * SPA (DOM) without pulling in `preact`.
+ *
+ * @example
+ * ```ts
+ * const el: HeadElement = { tag: "meta", attrs: { name: "robots", content: "index" } };
+ * ```
+ */
+type HeadElement = {
+  /** The tag name to emit. */tag: "meta" | "link" | "title" | "script"; /** Attribute map (already-unescaped values; escaping happens at serialization). */
+  attrs?: Record<string, string>; /** Inner text content (for `<title>` and JSON-LD `<script>`). */
+  children?: string; /** Stable identity used for de-duplication during `render` (e.g. `"meta:description"`). */
+  key?: string;
+};
+/**
+ * The shape returned by a route's `.head(data)` callback. All fields optional so routes
+ * supply only what they override.
+ *
+ * @example
+ * ```ts
+ * const head: HeadConfig = { title: "Home", description: "Welcome" };
+ * ```
+ */
+type HeadConfig = {
+  /** Page title (before `titleTemplate` is applied). */title?: string; /** Page description (`<meta name=description>` + og/twitter fallback). */
+  description?: string; /** Canonical URL override (otherwise derived from `router.toUrl`). */
+  canonical?: string; /** Open Graph image override for this page. */
+  image?: string; /** Arbitrary extra head elements (use the SEO primitive helpers to build these). */
+  elements?: HeadElement[];
+};
+/**
+ * Metadata describing an article page, consumed by `buildArticleHead`.
+ *
+ * @example
+ * ```ts
+ * const meta: ArticleMeta = { title: "Hi", author: "A", published: "2026-01-01" };
+ * ```
+ */
+type ArticleMeta = {
+  /** Article title. */title: string; /** Article description. */
+  description?: string; /** Article author. */
+  author?: string; /** ISO 8601 publish date. */
+  published?: string; /** ISO 8601 last-modified date. */
+  modified?: string; /** Section/category. */
+  section?: string; /** Article tags. */
+  tags?: string[]; /** Article image URL. */
+  image?: string;
+};
+/**
+ * A resolved route descriptor passed to `render` (path, params, locale, and its `.head()`
+ * result as a `HeadConfig`).
+ *
+ * @example
+ * ```ts
+ * const route: ResolvedRoute = { path: "/about", params: {}, name: "about" };
+ * ```
+ */
+type ResolvedRoute = {
+  /** The resolved path of the route. */path: string; /** The route name key (used by `router.toUrl` for canonical/alternate hrefs). */
+  name: string; /** Resolved route params. */
+  params: Record<string, string>; /** The active locale for this route render. */
+  locale?: string; /** The route's `.head()` result. */
+  head?: HeadConfig;
+};
+/**
+ * The public API surface of the `head` plugin.
+ *
+ * @example
+ * ```ts
+ * const html: string = api.render(route, data);
+ * ```
+ */
+type Api$2 = {
+  /**
+   * Compose the final `<head>` inner HTML for a route. Pulled synchronously by `build`.
+   *
+   * @param route - The resolved route descriptor (incl. its `.head()` HeadConfig).
+   * @param data - The page data object passed to the route's loader/render.
+   * @returns The serialized inner HTML of `<head>` (no surrounding `<head>` tags).
+   * @example
+   * ```ts
+   * api.render(route, data);
+   * ```
+   */
+  render(route: ResolvedRoute, data: unknown): string;
+};
+declare namespace types_d_exports {
+  export { Api$1 as Api, BuildEvents, BuildResult, Config$1 as Config, ExtractApi$1 as ExtractApi, OgImageConfig, OgPngRenderer, PhaseContext, PhaseEmit, PhaseLog, PhaseName, PhaseRequire, State$1 as State };
+}
+/**
+ * Structural extraction of a plugin instance's public API from its `_phantom`
+ * carrier (mirrors the kernel's non-exported `ExtractPluginApi`) so the
+ * framework's generic `require` is assignable to {@link PhaseContext.require}.
+ *
+ * @example
+ * ```ts
+ * type ContentApi = ExtractApi<typeof contentPlugin>;
+ * ```
+ */
+type ExtractApi$1<PluginCandidate> = PluginCandidate extends {
+  readonly _phantom: {
+    readonly api: infer PluginApi;
   };
-  'build:complete': {
-    pages: number;
+} ? PluginApi : never;
+/**
+ * Minimal logger slice used by the pipeline and phases (the core `log` API).
+ *
+ * @example
+ * ```ts
+ * const log: PhaseLog = { info: () => {}, debug: () => {}, warn: () => {}, error: () => {} };
+ * ```
+ */
+type PhaseLog = {
+  /** Record an informational event. */info(event: string, data?: unknown): void; /** Record a debug event. */
+  debug(event: string, data?: unknown): void; /** Record a warning event. */
+  warn(event: string, data?: unknown): void; /** Record an error event. */
+  error(event: string, data?: unknown): void;
+};
+/**
+ * Payload map for the events `build` emits, used to type the `emit` closure
+ * handed to the pipeline driver and phases.
+ *
+ * @example
+ * ```ts
+ * const emit: PhaseEmit = (name, payload) => kernel.emit(name, payload);
+ * ```
+ */
+type BuildEvents = {
+  /** Phase boundary marker (start, then done with durationMs). */"build:phase": {
+    phase: PhaseName;
+    status: "start" | "done";
+    durationMs?: number;
+  }; /** One successful-run summary. */
+  "build:complete": {
+    outDir: string;
+    pageCount: number;
     durationMs: number;
   };
-}> & Record<never, never>) | (_moku_labs_core0.PluginInstance<"spa", SpaConfig, SpaState, SpaApi, {
-  'component:create': {
-    name: string;
-    element: Element;
+};
+/** Strictly-typed emit closure for the build events (kernel overload form). */
+type PhaseEmit = EmitFn<BuildEvents>;
+/** Generic `require` closure for pulling dependency plugin APIs at run time. */
+type PhaseRequire = <PluginCandidate extends {
+  readonly name: string;
+  readonly spec: unknown;
+  readonly _phantom: {
+    readonly config: unknown;
+    readonly state: unknown;
+    readonly api: unknown;
+    readonly events: Record<string, unknown>;
   };
-  'component:mount': {
-    name: string;
-    element: Element;
+}>(plugin: PluginCandidate) => ExtractApi$1<PluginCandidate>;
+/**
+ * The plugin-context slice the pipeline driver and every phase consume: the
+ * mutable `state`, the resolved `config`/`global`, plus `require`/`emit`/`log`.
+ * Typed to match the kernel's generic context so the framework execution
+ * context is structurally assignable.
+ *
+ * @example
+ * ```ts
+ * const ctx: PhaseContext = { state, config, global, require, emit, log };
+ * ```
+ */
+type PhaseContext = {
+  /** Mutable per-run build state (caches + runId). */state: State$1; /** Resolved, frozen build config. */
+  readonly config: Readonly<Config$1>; /** Global framework config (mode, etc.). */
+  readonly global: Readonly<{
+    mode: "production" | "development";
+  }>; /** Resolve a depended-upon plugin instance to its public API. */
+  require: PhaseRequire; /** Emit a build event (notification-only). */
+  emit: PhaseEmit; /** Structured logger (core `log` API). */
+  readonly log: PhaseLog;
+};
+/**
+ * Injectable PNG renderer for the og-images phase. Defaults to the real
+ * Satori → resvg pipeline; unit tests inject a fake to assert hash-cache skip
+ * and the `p-limit` bound without rasterizing real images.
+ *
+ * @example
+ * ```ts
+ * const render: OgPngRenderer = async () => new Uint8Array();
+ * ```
+ */
+type OgPngRenderer = (input: {
+  /** Article title rendered into the card. */title: string; /** Output width in pixels. */
+  width: number; /** Output height in pixels. */
+  height: number;
+}) => Promise<Uint8Array>;
+/**
+ * Optional OG-image generation config. Omit the field (or set `false`) to disable.
+ *
+ * @example
+ * ```ts
+ * const og: OgImageConfig = { fontDir: "./fonts" };
+ * ```
+ */
+interface OgImageConfig {
+  /** Directory containing at least one .ttf/.otf/.woff font. Validated in onInit (void — config check only). */
+  fontDir: string;
+  /** Optional path to a custom OG template module. Falls back to the built-in template. */
+  template?: string;
+  /** Output dimensions. Defaults to 1200x630. */
+  size?: {
+    width: number;
+    height: number;
   };
-  'component:unmount': {
+}
+/**
+ * Public configuration for the `build` plugin. Flags give opt-in granularity over
+ * individual outputs without rewriting the pipeline.
+ *
+ * @example
+ * ```ts
+ * const config: Config = { outDir: "./dist", minify: true, feeds: true, sitemap: true, images: true, ogImage: false };
+ * ```
+ */
+type Config$1 = {
+  /** Output directory for the built site. */outDir: string; /** Minify bundled CSS/JS. */
+  minify: boolean; /** Generate RSS/Atom/JSON feeds. */
+  feeds: boolean; /** Generate sitemap.xml + robots.txt. */
+  sitemap: boolean; /** Optimize + copy content images. */
+  images: boolean; /** OG-image generation. `false` (or omitted) disables it; an object enables and configures it. */
+  ogImage: OgImageConfig | false;
+};
+/**
+ * Per-run closure state for the `build` plugin. Holds caches and config only —
+ * no domain data is duplicated here (pulled fresh via `ctx.require` each run).
+ *
+ * @example
+ * ```ts
+ * const state: State = { config, manifest: null, buildCache: new Map(), runId: null, ogImageHashCache: new Map() };
+ * ```
+ */
+interface State$1 {
+  /** Resolved, frozen config snapshot. */
+  config: Config$1;
+  /** Cached route manifest for the current run (populated in Phase 3 from router). */
+  manifest: RouteDefinition[] | null;
+  /** Per-run build artifacts (e.g. hashed CSS/JS asset paths from Phase 1). */
+  buildCache: Map<string, unknown>;
+  /** Unique id for the current run (timestamp/uuid) — injected as build-id meta. */
+  runId: string | null;
+  /**
+   * Content-hash cache for OG images: slug -> sha256(title + template + size).
+   * Loaded from `<outDir>/.cache/og-images.json` at the OG phase and written back,
+   * so unchanged articles are skipped on the next run.
+   */
+  ogImageHashCache: Map<string, string>;
+}
+/**
+ * Ordered names of the build pipeline phases, in execution order.
+ *
+ * @example
+ * ```ts
+ * const phase: PhaseName = "bundle";
+ * ```
+ */
+type PhaseName = "bundle" | "content" | "images" | "pages" | "feeds" | "sitemap" | "og-images" | "root-index";
+/**
+ * Result of a completed build run.
+ *
+ * @example
+ * ```ts
+ * const result: BuildResult = { outDir: "./dist", pageCount: 12, durationMs: 840 };
+ * ```
+ */
+interface BuildResult {
+  /** Resolved output directory the site was written to. */
+  outDir: string;
+  /** Number of route pages rendered. */
+  pageCount: number;
+  /** Total wall-clock duration of the run, in milliseconds. */
+  durationMs: number;
+}
+/**
+ * Public API surface mounted on `app.build`.
+ *
+ * @example
+ * ```ts
+ * const result = await app.build.run();
+ * ```
+ */
+type Api$1 = {
+  /**
+   * Run the full SSG pipeline and write the site to disk.
+   *
+   * @param options - Optional run overrides.
+   * @param options.outDir - Override the configured output directory for this run.
+   * @returns The build result (outDir, pageCount, durationMs).
+   * @example
+   * ```ts
+   * const result = await app.build.run({ outDir: "./preview" });
+   * ```
+   */
+  run(options?: {
+    outDir?: string;
+  }): Promise<BuildResult>;
+  /**
+   * List the phases in execution order (introspection / tooling).
+   *
+   * @returns The static ordered phase names.
+   * @example
+   * ```ts
+   * const order = app.build.phases();
+   * ```
+   */
+  phases(): PhaseName[];
+};
+declare namespace types_d_exports$7 {
+  export { COMPONENT_HOOK_NAMES, ComponentContext, ComponentDef, ComponentHooks, ComponentInstance, ExtractApi, PageData, ResolvedSpaConfig, SpaApi, SpaConfig, SpaContext, SpaEmitFunction, SpaEvents, SpaKernel, SpaKernelDeps, SpaRequire, SpaState };
+}
+/** Payload map for the events `spa` emits, used to type the kernel's `emit` closure. */
+type SpaEvents = {
+  /** A navigation has been intercepted and is starting. */"spa:navigate": {
+    from: string;
+    to: string;
+  }; /** The swap completed and the new URL is active. */
+  "spa:navigated": {
+    url: string;
+  }; /** A component instance attached to an element. */
+  "spa:component-mount": {
     name: string;
-    reason: "navigation" | "destroy";
-  };
-  'component:destroy': {
+    el: Element;
+  }; /** A component instance detached from an element. */
+  "spa:component-unmount": {
     name: string;
+    el: Element;
   };
-  'nav:start': {
-    url: string;
-    fromUrl: string;
+};
+/** Strictly-typed emit closure for the spa events (kernel overload form). */
+type SpaEmitFunction = EmitFn<SpaEvents>;
+/**
+ * Structural extraction of a plugin instance's public API from its `_phantom`
+ * carrier (mirrors the kernel's non-exported `ExtractPluginApi`).
+ *
+ * @example
+ * type RApi = ExtractApi<typeof routerPlugin>;
+ */
+type ExtractApi<PluginCandidate> = PluginCandidate extends {
+  readonly _phantom: {
+    readonly api: infer PluginApi;
   };
-  'nav:end': {
-    url: string;
+} ? PluginApi : never;
+/** Generic `require` closure for pulling dependency plugin APIs at init time. */
+type SpaRequire = <PluginCandidate extends {
+  readonly name: string;
+  readonly spec: unknown;
+  readonly _phantom: {
+    readonly config: unknown;
+    readonly state: unknown;
+    readonly api: unknown;
+    readonly events: Record<string, unknown>;
   };
-}> & Record<never, never>) | (_moku_labs_core0.PluginInstance<"deploy", DeployConfig, DeployState, DeployApi, {}> & Record<never, never>) | ExtraPlugins[number], [...ExtraPlugins], _moku_labs_core0.CoreApisFromTuple<[_moku_labs_core0.CorePluginInstance<"log", {
-  level: "info";
-  mode: "auto";
-}, LogState, LogApi>, _moku_labs_core0.CorePluginInstance<"env", {
-  schema: {};
-  providers: never[];
-  publicPrefix: string;
-}, EnvState, EnvApi>]>> | undefined) => _moku_labs_core0.App<Config, Events, (_moku_labs_core0.PluginInstance<"site", {
+}>(plugin: PluginCandidate) => ExtractApi<PluginCandidate>;
+/**
+ * The plugin-context slice the spa wiring consumes in `onInit`/`onStart`:
+ * mutable `state`, resolved `config`, `require`/`emit`/`log`. Structurally
+ * assignable from the framework's generic execution context.
+ */
+interface SpaContext {
+  /** Mutable spa state (all kernel data lives here). */
+  state: SpaState;
+  /** Resolved, frozen spa config. */
+  readonly config: Readonly<SpaConfig>;
+  /** Resolve a depended-upon plugin instance to its public API. */
+  require: SpaRequire;
+  /** Emit a spa lifecycle event (notification-only). */
+  emit: SpaEmitFunction;
+  /** Structured logger (core `log` API). */
+  readonly log: LogApi;
+}
+/** Configuration for the SPA runtime plugin. All fields optional; defaults applied in onInit. */
+type SpaConfig = {
+  /**
+   * CSS selector for the page region swapped on navigation. Defaults to
+   * `"main > section"`.
+   */
+  swapSelector?: string;
+  /**
+   * Use the View Transitions API for cross-fade swaps when available.
+   * Falls back to an instant swap when unsupported. Defaults to `false`.
+   */
+  viewTransitions?: boolean;
+  /**
+   * Show the in-house top progress bar during navigation. Defaults to `true`.
+   */
+  progressBar?: boolean;
+  /**
+   * Components to auto-register at init (in addition to runtime `register`).
+   * Defaults to an empty array.
+   */
+  components?: ComponentDef[];
+};
+/** Resolved SPA config after defaults are applied. */
+interface ResolvedSpaConfig {
+  /** CSS selector for the swapped page region. */
+  swapSelector: string;
+  /** Whether View Transitions are enabled. */
+  viewTransitions: boolean;
+  /** Whether the progress bar is enabled. */
+  progressBar: boolean;
+  /** Pre-registered components. */
+  components: ComponentDef[];
+}
+/** Context handed to every component lifecycle hook. */
+interface ComponentContext {
+  /** The element the component instance is bound to. */
+  el: Element;
+  /** Page data extracted from the `script#__DATA__` payload. */
+  data: PageData;
+}
+/** Lifecycle hooks a component may implement. */
+interface ComponentHooks {
+  /**
+   * Called once when the instance is created (before DOM attach).
+   *
+   * @param ctx - The component context for this instance.
+   * @returns void
+   * @example
+   * onCreate({ el }) { el.dataset.ready = "1"; }
+   */
+  onCreate?(ctx: ComponentContext): void;
+  /**
+   * Called after the instance is attached to its element.
+   *
+   * @param ctx - The component context for this instance.
+   * @returns void
+   * @example
+   * onMount({ el }) { el.textContent = "0"; }
+   */
+  onMount?(ctx: ComponentContext): void;
+  /**
+   * Called when a navigation begins while this instance is mounted.
+   *
+   * @param ctx - The component context for this instance.
+   * @returns void
+   * @example
+   * onNavStart({ el }) { el.dataset.loading = ""; }
+   */
+  onNavStart?(ctx: ComponentContext): void;
+  /**
+   * Called when a navigation completes while this instance is mounted.
+   *
+   * @param ctx - The component context for this instance.
+   * @returns void
+   * @example
+   * onNavEnd({ el }) { delete el.dataset.loading; }
+   */
+  onNavEnd?(ctx: ComponentContext): void;
+  /**
+   * Called before the instance is detached from its element.
+   *
+   * @param ctx - The component context for this instance.
+   * @returns void
+   * @example
+   * onUnMount({ el }) { el.replaceChildren(); }
+   */
+  onUnMount?(ctx: ComponentContext): void;
+  /**
+   * Called once when the instance is destroyed (after detach).
+   *
+   * @param ctx - The component context for this instance.
+   * @returns void
+   * @example
+   * onDestroy({ el }) { delete el.dataset.ready; }
+   */
+  onDestroy?(ctx: ComponentContext): void;
+}
+/** Allowed hook names — single source of truth for fail-fast validation. */
+declare const COMPONENT_HOOK_NAMES: readonly ["onCreate", "onMount", "onNavStart", "onNavEnd", "onUnMount", "onDestroy"];
+/** A registered component definition. */
+interface ComponentDef {
+  /** Unique component name (matched against `data-component`). */
   name: string;
-  url: string;
-  author: string;
-  description: string;
-}, SiteState, SiteApi, {}> & Record<never, never>) | (_moku_labs_core0.PluginInstance<"i18n", I18nConfig, I18nState<readonly string[]>, I18nApi<readonly string[]>, {}> & Record<never, never>) | (_moku_labs_core0.PluginInstance<"content", ContentConfig, ContentState, ContentApi, {
-  'content:ready': {
-    articles: Map<string, Article[]>;
-  };
-  'content:invalidated': {
-    paths: string[];
-  };
-}> & Record<never, never>) | (_moku_labs_core0.PluginInstance<"router", RouterConfig, RouterState, RouterApi, {
-  'router:registered': {
-    routeCount: number;
-  };
-}> & Record<never, never>) | (_moku_labs_core0.PluginInstance<"head", HeadPluginConfig, HeadState, HeadApi, {}> & Record<never, never>) | (_moku_labs_core0.PluginInstance<"build", BuildConfig, BuildState, BuildApi, {
-  'build:phase': {
-    phase: "bundle" | "content" | "pages" | "feeds" | "sitemap" | "og" | "images";
-  };
-  'build:complete': {
-    pages: number;
+  /** Lifecycle hooks. */
+  hooks: ComponentHooks;
+}
+/** A live, mounted component instance. */
+interface ComponentInstance {
+  /** The definition this instance was created from. */
+  def: ComponentDef;
+  /** The element this instance is bound to. */
+  el: Element;
+  /**
+   * True if the element is OUTSIDE the swap area — persists across navigations
+   * and receives onNavStart/onNavEnd (never onUnMount on nav). False =
+   * page-specific: full unmount/destroy on every navigation.
+   */
+  persistent: boolean;
+}
+/** Page data payload parsed from the inline `script#__DATA__` element. */
+type PageData = Record<string, unknown>;
+/** Resolved dependency APIs the kernel reuses (router match/manifest, head compose). */
+interface SpaKernelDeps {
+  /** Router plugin API — used for client-side route classification/matching. */
+  router: RouterApi;
+  /** Head plugin API — its pure compose is reused for client head-sync. */
+  head: Api$2;
+}
+/** The single shared SPA kernel — pure factory over state/config/emit/deps. */
+interface SpaKernel {
+  /**
+   * Validate config, register config.components, seed currentUrl.
+   *
+   * @returns void
+   * @example
+   * kernel.init();
+   */
+  init(): void;
+  /**
+   * Boot the browser runtime (router listeners + initial scan). Throws if started.
+   *
+   * @returns void
+   * @example
+   * kernel.boot();
+   */
+  boot(): void;
+  /**
+   * Register a component definition (last-registered-wins).
+   *
+   * @param component - The component definition to register.
+   * @returns void
+   * @example
+   * kernel.register(counter);
+   */
+  register(component: ComponentDef): void;
+  /**
+   * Process a navigation to `path`: fetch then swap then head-sync then emit.
+   *
+   * @param path - The target path to navigate to.
+   * @returns void
+   * @example
+   * kernel.processNav("/about");
+   */
+  processNav(path: string): void;
+  /**
+   * Query the swap region and mount components for matching elements.
+   *
+   * @returns void
+   * @example
+   * kernel.scan();
+   */
+  scan(): void;
+  /**
+   * Tear down router listeners, run unmount/destroy, clear instances.
+   *
+   * @returns void
+   * @example
+   * kernel.dispose();
+   */
+  dispose(): void;
+}
+/** Internal mutable state for the spa plugin (all kernel data lives here). */
+interface SpaState {
+  /** Components registered by name (last-registered-wins). */
+  registeredComponents: Map<string, ComponentDef>;
+  /** Live component instances keyed by their bound element. */
+  instances: Map<Element, ComponentInstance>;
+  /** The current resolved URL (pathname + search). */
+  currentUrl: string;
+  /** Teardown handle for the attached router listeners (null when detached). */
+  destroyRouter: (() => void) | null;
+  /** Whether the browser runtime has been booted. */
+  started: boolean;
+  /** The single shared SPA kernel instance (null until onInit builds it). */
+  kernel: SpaKernel | null;
+}
+/** Public API of the spa plugin (registration / control surface). */
+type SpaApi = {
+  /**
+   * Register a component definition for client mounting.
+   *
+   * @param component - The component definition created via `createComponent`.
+   * @returns void
+   * @example
+   * app.spa.register(counter);
+   */
+  register(component: ComponentDef): void;
+  /**
+   * Programmatically navigate to a path (client runtime; no-op without a DOM).
+   *
+   * @param path - Target path (pathname, optionally with search/hash).
+   * @returns void
+   * @example
+   * app.spa.navigate("/about");
+   */
+  navigate(path: string): void;
+  /**
+   * Read the current resolved URL.
+   *
+   * @returns The current pathname + search.
+   * @example
+   * const url = app.spa.current(); // "/about"
+   */
+  current(): string;
+};
+declare namespace types_d_exports$2 {
+  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
+/**
+ * @file deploy — Standard Plugin (wiring harness only). Deploys the built dist/
+ * to Cloudflare Pages via the injectable wrangler subprocess.
+ *
+ * Depends: site. Emits: deploy:complete.
+ * @see README.md
+ */
+declare const deployPlugin: import("@moku-labs/core").PluginInstance<"deploy", Config, State, Api, {
+  "deploy:complete": {
+    url: string;
+    deploymentId: string;
+    branch: string;
     durationMs: number;
   };
-}> & Record<never, never>) | (_moku_labs_core0.PluginInstance<"spa", SpaConfig, SpaState, SpaApi, {
-  'component:create': {
-    name: string;
-    element: Element;
-  };
-  'component:mount': {
-    name: string;
-    element: Element;
-  };
-  'component:unmount': {
-    name: string;
-    reason: "navigation" | "destroy";
+}> & Record<never, never>;
+//#endregion
+//#region src/plugins/build/index.d.ts
+declare const buildPlugin: import("@moku-labs/core").PluginInstance<"build", Config$1, State$1, Api$1, {
+  "build:phase": {
+    phase: PhaseName;
+    status: "start" | "done";
+    durationMs?: number;
   };
-  'component:destroy': {
-    name: string;
+  "build:complete": {
+    outDir: string;
+    pageCount: number;
+    durationMs: number;
   };
-  'nav:start': {
-    url: string;
-    fromUrl: string;
+}> & Record<never, never>;
+//#endregion
+//#region src/plugins/content/index.d.ts
+declare const contentPlugin: import("@moku-labs/core").PluginInstance<"content", Config$3, State$3, Api$3, {
+  "content:ready": {
+    locales: readonly string[];
+    articleCount: number;
   };
-  'nav:end': {
-    url: string;
+  "content:invalidated": {
+    paths: readonly string[];
   };
-}> & Record<never, never>) | (_moku_labs_core0.PluginInstance<"deploy", DeployConfig, DeployState, DeployApi, {}> & Record<never, never>) | ExtraPlugins[number], _moku_labs_core0.CoreApisFromTuple<[_moku_labs_core0.CorePluginInstance<"log", {
-  level: "info";
-  mode: "auto";
-}, LogState, LogApi>, _moku_labs_core0.CorePluginInstance<"env", {
-  schema: {};
-  providers: never[];
-  publicPrefix: string;
-}, EnvState, EnvApi>]>>;
+}> & Record<never, never>;
+//#endregion
+//#region src/plugins/head/primitives.d.ts
+/**
+ * Build a `<meta name=… content=…>` descriptor.
+ *
+ * @param name - The meta `name` attribute (e.g. `"description"`, `"robots"`).
+ * @param content - The meta `content` value.
+ * @returns A serializable head element keyed `meta:<name>`.
+ * @example meta("description", "A web framework built on @moku-labs/core")
+ */
+declare function meta(name: string, content: string): HeadElement;
+/**
+ * Build an Open Graph `<meta property=… content=…>` descriptor.
+ *
+ * @param property - The OG property, used verbatim (e.g. `"og:title"`, `"og:image"`).
+ * @param content - The property value.
+ * @returns A serializable head element keyed `meta:<property>`.
+ * @example og("og:title", "Home")
+ */
+declare function og(property: string, content: string): HeadElement;
 /**
- * Kernel app augmented so `app.router.routes` carries the consumer's literal
- * route-name keys (with `RouteSpec` values — the shape the router stores).
+ * Build a Twitter-card `<meta name=… content=…>` descriptor.
+ *
+ * @param name - The Twitter meta name, used verbatim (e.g. `"twitter:title"`).
+ * @param content - The value.
+ * @returns A serializable head element keyed `meta:<name>`.
+ * @example twitter("twitter:card", "summary_large_image")
  */
-type WebApp<Routes extends Record<string, RouteBuilder>> = Omit<ReturnType<typeof kernelCreateApp>, 'router'> & {
-  router: RouterApi<RouteSpecMap<Routes>>;
+declare function twitter(name: string, content: string): HeadElement;
+/**
+ * Build a JSON-LD `<script type="application/ld+json">` descriptor.
+ *
+ * XSS-SAFE: the serialized JSON has `<`, `>`, and `&` unicode-escaped (`<`,
+ * `>`, `&`) so the payload can never break out of the `<script>` element
+ * or inject markup, while still round-tripping via `JSON.parse`.
+ *
+ * @param data - Any JSON-serializable structured-data object.
+ * @returns A serializable head element carrying the escaped JSON-LD script.
+ * @example jsonLd({ "@context": "https://schema.org", "@type": "Article", headline: "Hi" })
+ */
+declare function jsonLd(data: unknown): HeadElement;
+/**
+ * Build a canonical `<link rel="canonical" href=…>` descriptor.
+ *
+ * @param url - The canonical absolute URL.
+ * @returns A serializable head element keyed `link:canonical`.
+ * @example canonical("https://example.com/post")
+ */
+declare function canonical(url: string): HeadElement;
+/**
+ * Build an alternate-language `<link rel="alternate" hreflang=… href=…>` descriptor.
+ *
+ * @param locale - The BCP-47 locale tag (e.g. `"en"`, `"uk"`, `"x-default"`).
+ * @param url - The absolute URL of the localized page.
+ * @returns A serializable head element keyed `link:alternate:<locale>`.
+ * @example hreflang("uk", "https://example.com/uk/post")
+ */
+declare function hreflang(locale: string, url: string): HeadElement;
+/**
+ * Build a feed `<link rel="alternate" type=… title=… href=…>` descriptor.
+ *
+ * @param title - Human-readable feed title.
+ * @param url - The feed URL.
+ * @param type - The feed MIME type. Defaults to `"application/rss+xml"`.
+ * @returns A serializable head element keyed `link:feed:<url>`.
+ * @example feedLink("My Blog", "/feed.xml", "application/atom+xml")
+ */
+declare function feedLink(title: string, url: string, type?: string): HeadElement;
+/**
+ * Compose the full head element set for an article page: og:type=article, published/
+ * modified times, author, section, tags, plus a JSON-LD `Article` block and canonical.
+ *
+ * @param articleMeta - Article metadata (title, description, author, dates, tags, image…).
+ * @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")
+ */
+declare function buildArticleHead(articleMeta: ArticleMeta, canonicalUrl: string): HeadElement[];
+//#endregion
+//#region src/plugins/head/index.d.ts
+declare const headPlugin: import("@moku-labs/core").PluginInstance<"head", Config$2, State$2, Api$2, {}> & {
+  meta: typeof meta;
+  og: typeof og;
+  twitter: typeof twitter;
+  jsonLd: typeof jsonLd;
+  canonical: typeof canonical;
+  hreflang: typeof hreflang;
+  feedLink: typeof feedLink;
+  buildArticleHead: typeof buildArticleHead;
 };
+//#endregion
+//#region src/plugins/i18n/index.d.ts
+declare const i18nPlugin: import("@moku-labs/core").PluginInstance<"i18n", Config$5, Record<string, never>, Api$5, {}> & Record<never, never>;
+//#endregion
+//#region src/plugins/log/index.d.ts
+/**
+ * Core logging plugin — always-on in-memory trace + `expect()` event-trace DSL.
+ * API injected as `ctx.log` on every regular plugin and surfaced as `app.log`.
+ * No depends / events / hooks (core plugin per spec/03 §5).
+ *
+ * @see README.md
+ */
+declare const logPlugin: import("@moku-labs/core").CorePluginInstance<"log", LogConfig, LogState, LogApi>;
+//#endregion
+//#region src/plugins/router/builders/route-builder.d.ts
 /**
- * Layer-2 createApp wrapper — generic-preserving signature.
+ * Create a fluent route builder from a URL pattern string. Captures the pattern
+ * as a literal type for compile-time param inference; `.load()` is the only method
+ * that widens the data generic, so `ctx.data` in `.render()`/`.head()` is typed by
+ * `.load()`'s return at the CALL SITE. The returned object is itself the route
+ * definition (`pattern` / `_meta` / `_handlers`), so it slots straight into a route map.
  *
- * Projects the consumer's flat config into pluginConfigs before delegating to
- * the kernel-bound createApp. The Routes generic flows through to
- * `app.router.routes` so callers get typed access to their route names.
+ * @param pattern - URL pattern with `{param}` / `{param:?}` placeholders.
+ * @returns A `RouteBuilder<RouteState<P>>` carrying the typed fluent chain.
+ * @example
+ * ```ts
+ * route("/{lang:?}/{slug}/")
+ *   .load(({ slug }) => loadArticle(slug))
+ *   .render((ctx) => <Article a={ctx.data} />)
+ *   .head((ctx) => ({ title: ctx.data.title }));
+ * ```
+ */
+declare function route<P extends string>(pattern: P): RouteBuilder<RouteState<P>>;
+/**
+ * Typed identity helper for route maps. Preserves the precise literal type of the
+ * route object for IntelliSense at the consumer call site (before config erasure).
  *
- * @param input - Consumer-facing flat web-app config.
- * @returns The assembled app with typed router routes.
+ * @param routes - The route map object.
+ * @returns The same object, with its precise type preserved.
+ * @example
+ * ```ts
+ * const routes = defineRoutes({ home: route("/"), article: route("/{slug}/") });
+ * ```
  */
-declare function createApp<Routes extends Record<string, RouteBuilder>>(input: WebAppConfig<Routes>): WebApp<Routes>;
+declare function defineRoutes<T extends RouteMap>(routes: T): T;
+//#endregion
+//#region src/plugins/router/index.d.ts
+declare const routerPlugin: import("@moku-labs/core").PluginInstance<"router", RouterConfig, RouterState, RouterApi, {}> & {
+  route: typeof route;
+  defineRoutes: typeof defineRoutes;
+};
+//#endregion
+//#region src/plugins/site/index.d.ts
+declare const sitePlugin: import("@moku-labs/core").PluginInstance<"site", Config$6, Record<string, never>, Api$6, {}> & Record<never, never>;
+//#endregion
+//#region src/plugins/spa/index.d.ts
+declare const spaPlugin: import("@moku-labs/core").PluginInstance<"spa", SpaConfig, SpaState, SpaApi, {
+  "spa:navigate": {
+    from: string;
+    to: string;
+  };
+  "spa:navigated": {
+    url: string;
+  };
+  "spa:component-mount": {
+    name: string;
+    el: Element;
+  };
+  "spa:component-unmount": {
+    name: string;
+    el: Element;
+  };
+}> & Record<never, never>;
+//#endregion
+//#region src/index.d.ts
+declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs/core").AnyPluginInstance[] = readonly []>(options?: import("@moku-labs/core").CreateAppOptions<Config$7, Events, (import("@moku-labs/core").PluginInstance<"site", Config$6, Record<string, never>, Api$6, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"i18n", Config$5, Record<string, never>, Api$5, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"router", RouterConfig, RouterState, RouterApi, {}> & {
+    route: typeof route;
+    defineRoutes: typeof defineRoutes;
+  }) | (import("@moku-labs/core").PluginInstance<"content", Config$3, State$3, Api$3, {
+    "content:ready": {
+      locales: readonly string[];
+      articleCount: number;
+    };
+    "content:invalidated": {
+      paths: readonly string[];
+    };
+  }> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"head", Config$2, State$2, Api$2, {}> & {
+    meta: typeof meta;
+    og: typeof og;
+    twitter: typeof twitter;
+    jsonLd: typeof jsonLd;
+    canonical: typeof canonical;
+    hreflang: typeof hreflang;
+    feedLink: typeof feedLink;
+    buildArticleHead: typeof buildArticleHead;
+  }) | (import("@moku-labs/core").PluginInstance<"build", Config$1, State$1, Api$1, {
+    "build:phase": {
+      phase: PhaseName;
+      status: "start" | "done";
+      durationMs?: number;
+    };
+    "build:complete": {
+      outDir: string;
+      pageCount: number;
+      durationMs: number;
+    };
+  }> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"spa", SpaConfig, SpaState, SpaApi, {
+    "spa:navigate": {
+      from: string;
+      to: string;
+    };
+    "spa:navigated": {
+      url: string;
+    };
+    "spa:component-mount": {
+      name: string;
+      el: Element;
+    };
+    "spa:component-unmount": {
+      name: string;
+      el: Element;
+    };
+  }> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"deploy", Config, State, Api, {
+    "deploy:complete": {
+      url: string;
+      deploymentId: string;
+      branch: string;
+      durationMs: number;
+    };
+  }> & Record<never, never>) | ExtraPlugins[number], [...ExtraPlugins], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", LogConfig, LogState, LogApi>, import("@moku-labs/core").CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>]>> | undefined) => import("@moku-labs/core").App<Config$7, Events, (import("@moku-labs/core").PluginInstance<"site", Config$6, Record<string, never>, Api$6, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"i18n", Config$5, Record<string, never>, Api$5, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"router", RouterConfig, RouterState, RouterApi, {}> & {
+    route: typeof route;
+    defineRoutes: typeof defineRoutes;
+  }) | (import("@moku-labs/core").PluginInstance<"content", Config$3, State$3, Api$3, {
+    "content:ready": {
+      locales: readonly string[];
+      articleCount: number;
+    };
+    "content:invalidated": {
+      paths: readonly string[];
+    };
+  }> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"head", Config$2, State$2, Api$2, {}> & {
+    meta: typeof meta;
+    og: typeof og;
+    twitter: typeof twitter;
+    jsonLd: typeof jsonLd;
+    canonical: typeof canonical;
+    hreflang: typeof hreflang;
+    feedLink: typeof feedLink;
+    buildArticleHead: typeof buildArticleHead;
+  }) | (import("@moku-labs/core").PluginInstance<"build", Config$1, State$1, Api$1, {
+    "build:phase": {
+      phase: PhaseName;
+      status: "start" | "done";
+      durationMs?: number;
+    };
+    "build:complete": {
+      outDir: string;
+      pageCount: number;
+      durationMs: number;
+    };
+  }> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"spa", SpaConfig, SpaState, SpaApi, {
+    "spa:navigate": {
+      from: string;
+      to: string;
+    };
+    "spa:navigated": {
+      url: string;
+    };
+    "spa:component-mount": {
+      name: string;
+      el: Element;
+    };
+    "spa:component-unmount": {
+      name: string;
+      el: Element;
+    };
+  }> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"deploy", Config, State, Api, {
+    "deploy:complete": {
+      url: string;
+      deploymentId: string;
+      branch: string;
+      durationMs: number;
+    };
+  }> & Record<never, never>) | ExtraPlugins[number], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", LogConfig, LogState, LogApi>, import("@moku-labs/core").CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>]>>, createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<Config$7, Events, import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", LogConfig, LogState, LogApi>, import("@moku-labs/core").CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>]>>;
 //#endregion
-export { types_d_exports as Build, type ComponentDef, type ComponentHooks, type Config, types_d_exports$1 as Content, types_d_exports$2 as Deploy, types_d_exports$3 as Env, type Events, types_d_exports$4 as Head, types_d_exports$5 as I18n, types_d_exports$6 as Log, type RouteBuilder, type RouteSpec, types_d_exports$7 as Router, types_d_exports$8 as Site, types_d_exports$9 as Spa, WebApp, type WebAppConfig, build, canonical, content, createApp, createComponent, createPlugin, deploy, env, feedLink, head, hreflang, i18n, jsonLd, log, meta, og, route, router, site, spa, twitter };
+export { types_d_exports as Build, types_d_exports$1 as Content, types_d_exports$2 as Deploy, types_d_exports$3 as Env, types_d_exports$4 as Head, types_d_exports$5 as Log, types_d_exports$6 as Router, types_d_exports$7 as Spa, buildArticleHead, buildPlugin, canonical, contentPlugin, createApp, createPlugin, defineRoutes, deployPlugin, envPlugin, feedLink, headPlugin, hreflang, i18nPlugin, jsonLd, logPlugin, meta, og, route, routerPlugin, sitePlugin, spaPlugin, twitter };