@moku-labs/web 0.4.1 → 0.5.0

package/dist/browser.d.mts

@@ -0,0 +1,1852 @@
+import { EmitFn } from "@moku-labs/core";
+import { ComponentChildren, VNode } from "preact";
+
+//#region src/plugins/log/types.d.ts
+declare namespace types_d_exports$3 {
+  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$1 {
+  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;
+  /**
+   * 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/providers.browser.d.ts
+/**
+ * A browser-safe {@link EnvProvider} that reads `import.meta.env` and an optional
+ * `globalThis[globalKey]` snapshot, merging them with the runtime global winning.
+ * Contains zero `node:*` imports, so it is safe to include in the client bundle.
+ * Never throws on missing sources — each absent source resolves to `{}`.
+ *
+ * @param options - Optional settings.
+ * @param options.globalKey - `globalThis` key to read a public-env snapshot from. Defaults to `"__ENV__"`.
+ * @returns An {@link EnvProvider} named `browser-env`.
+ * @example
+ * ```ts
+ * const provider = browserEnv();
+ * provider.load(); // { PUBLIC_API_URL: "/api", ... }
+ * ```
+ */
+declare function browserEnv(options?: {
+  globalKey?: string;
+}): EnvProvider;
+//#endregion
+//#region src/plugins/env/index.d.ts
+/**
+ * Core plugin that resolves, validates, and freezes the environment at `onInit`,
+ * 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$4 = {
+  /** 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$3 = {
+  /** 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;
+};
+/**
+ * Public API of the site plugin — read-only accessors over frozen global
+ * site metadata, plus canonical URL construction.
+ */
+type Api$3 = {
+  /**
+   * 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$2 = {
+  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$2 = {
+  /**
+   * 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$4 {
+  export { Api$1 as Api, ClientRoute, CompileInput, CompiledRoute, Config$1 as Config, ExtractRouteParams, ExtractSegmentParameter, HeadConfig$1 as HeadConfig, LayoutContext, MatcherTable, Prettify, RouteBuilder, RouteContext, RouteDefinition, RouteHandlers, RouteMap, RouteState, RouterApi, RouterConfig, RouterState, State$1 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;
+}
+/**
+ * Context handed to a route's `.layout()` wrapper: the render-time
+ * {@link RouteContext} plus the route's `.meta()` bag, so persistent chrome (e.g. a
+ * TopBar/TabNav) can read `locale` and `meta.activeTab`. Distinct from
+ * `RouteContext` because the layout is the only handler that needs `meta`; keeping
+ * it on its own type leaves `.render()`/`.head()` contexts unchanged.
+ *
+ * @remarks
+ * The layout is applied in the SSG render path ONLY. On client (SPA) navigation the
+ * chrome is persistent and the layout is intentionally NOT re-applied — only the
+ * inner swap region is replaced. See `build`'s pages phase and `spa`'s kernel.
+ */
+interface LayoutContext<S extends RouteState> extends RouteContext<S> {
+  /** The route's `.meta()` bag (e.g. `{ activeTab: "home" }`). */
+  readonly meta: Record<string, unknown>;
+}
+/** 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 ctx-aware layout wrapper that frames this route's rendered page in
+   * persistent chrome. Receives the route's {@link LayoutContext} (render context +
+   * `meta`) and the page `children`. Applied in the SSG render path ONLY — on client
+   * navigation the chrome persists and only the inner swap region is replaced, so the
+   * layout is not re-run.
+   */
+  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 an arbitrary metadata bag. The bag MUST be JSON-serializable: it is
+   * projected verbatim into `clientManifest()` and shipped to the browser.
+   */
+  meta(meta: Record<string, unknown>): RouteBuilder<S>;
+  /** Attach a JSON serializer for the route's data. */
+  toJson(handler: (ctx: RouteContext<S>) => unknown): RouteBuilder<S>;
+  /** 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 (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[]>;
+  /** 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;
+  };
+  /** 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;
+  /** 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 {
+  /** 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;
+}
+/**
+ * Serializable route entry for the client route-index — a projection of the
+ * compiled route table with NO `_handlers` closures, safe to ship to the browser
+ * (the SPA recompiles matchers lazily from `pattern`).
+ *
+ * @remarks
+ * `meta` MUST be JSON-serializable: `clientManifest()` is intended to survive a
+ * `JSON.stringify`/`JSON.parse` round-trip, so a route's `.meta()` bag must contain
+ * only JSON-safe values (no functions, symbols, or class instances).
+ */
+interface ClientRoute {
+  /** URL pattern string, e.g. `/{lang:?}/{slug}/`. */
+  readonly pattern: string;
+  /** Route name key from the route map. */
+  readonly name: string;
+  /** Route metadata bag from `.meta()`. MUST be JSON-serializable. */
+  readonly meta: Record<string, unknown>;
+}
+/** Public API exposed via `ctx.require(routerPlugin)`. */
+type RouterApi = {
+  /**
+   * 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[];
+  /**
+   * Serializable, specificity-sorted projection of the route table for client
+   * shipping. Maps the compiled table to `{ pattern, name, meta }` entries with NO
+   * `_handlers` closures, returned as a fresh frozen array. JSON-serializable so the
+   * SPA can embed it and recompile matchers lazily in the browser.
+   *
+   * @returns A fresh, frozen, specificity-sorted read-only array of {@link ClientRoute}.
+   * @example
+   * const json = JSON.stringify(ctx.require(routerPlugin).clientManifest());
+   */
+  clientManifest(): readonly ClientRoute[];
+  /**
+   * The resolved render mode — the single source of truth for static/hybrid/spa
+   * behavior. `build` reads it to decide whether to emit client data sidecars;
+   * `spa` reads it to decide whether to attempt client DATA navigation.
+   *
+   * @returns `"ssg" | "spa" | "hybrid"`.
+   * @example
+   * if (ctx.require(routerPlugin).mode() !== "ssg") { ... }
+   */
+  mode(): "ssg" | "spa" | "hybrid";
+};
+/** Re-export under the canonical `Config` name for the plugin-types barrel. */
+type Config$1 = RouterConfig;
+/** Re-export under the canonical `State` name for the plugin-types barrel. */
+type State$1 = RouterState;
+/** Re-export under the canonical `Api` name for the plugin-types barrel. */
+type Api$1 = RouterApi;
+declare namespace types_d_exports$2 {
+  export { Api, ArticleMeta, Config, HeadConfig, HeadDefaults, HeadElement, ResolvedRoute, 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 = {
+  /** 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 = {
+  /** 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 = {
+  /**
+   * 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$5 {
+  export { COMPONENT_HOOK_NAMES, ComponentContext, ComponentDef, ComponentHooks, ComponentInstance, ExtractApi, PageData, ResolvedSpaConfig, SpaApi, SpaConfig, SpaContext, SpaDataReader, SpaEmitFunction, SpaEvents, SpaKernel, SpaKernelDeps, SpaRequire, SpaState };
+}
+/** Payload map for the events `spa` emits, used to type the kernel's `emit` closure. */
+type SpaEvents = {
+  /** A navigation has been intercepted and is starting. */"spa:navigate": {
+    from: string;
+    to: string;
+  }; /** The swap completed and the new URL is active. */
+  "spa:navigated": {
+    url: string;
+  }; /** A component instance attached to an element. */
+  "spa:component-mount": {
+    name: string;
+    el: Element;
+  }; /** A component instance detached from an element. */
+  "spa:component-unmount": {
+    name: string;
+    el: Element;
+  };
+};
+/** Strictly-typed emit closure for the spa events (kernel overload form). */
+type SpaEmitFunction = EmitFn<SpaEvents>;
+/**
+ * Structural extraction of a plugin instance's public API from its `_phantom`
+ * carrier (mirrors the kernel's non-exported `ExtractPluginApi`).
+ *
+ * @example
+ * type RApi = ExtractApi<typeof routerPlugin>;
+ */
+type ExtractApi<PluginCandidate> = PluginCandidate extends {
+  readonly _phantom: {
+    readonly api: infer PluginApi;
+  };
+} ? PluginApi : never;
+/** Generic `require` closure for pulling dependency plugin APIs at init time. */
+type SpaRequire = <PluginCandidate extends {
+  readonly name: string;
+  readonly spec: unknown;
+  readonly _phantom: {
+    readonly config: unknown;
+    readonly state: unknown;
+    readonly api: unknown;
+    readonly events: Record<string, unknown>;
+  };
+}>(plugin: PluginCandidate) => ExtractApi<PluginCandidate>;
+/**
+ * The plugin-context slice the 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;
+  /**
+   * Whether a plugin is registered (by name). Used to detect the OPTIONAL `data`
+   * plugin at init — `spa` enables client DATA navigation only when `has("data")`.
+   */
+  has: (name: string) => boolean;
+  /** Emit a spa lifecycle event (notification-only). */
+  emit: SpaEmitFunction;
+  /** Structured logger (core `log` API). */
+  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;
+  /** 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>;
+/**
+ * The OPTIONAL `data` provider reader the kernel uses for client DATA navigation —
+ * a structural slice of the `data` plugin's API (fetch the persisted JSON for a
+ * page path). Captured at init via `ctx.has("data")`/`ctx.require` so `spa` never
+ * imports the `data` plugin or its types.
+ */
+type SpaDataReader = (path: string) => Promise<unknown | null>;
+/** Resolved dependency APIs the kernel reuses (router match/mode, head compose, optional data). */
+interface SpaKernelDeps {
+  /** Router plugin API — used for client-side route matching (`match`) + the resolved `mode`. */
+  router: RouterApi;
+  /** Head plugin API — its pure compose is reused for client head-sync. */
+  head: Api;
+  /**
+   * The OPTIONAL `data` reader. Present only when the `data` plugin is composed.
+   * When present (and `router.mode() !== "ssg"`), navigation first tries the client
+   * DATA path (match → `dataAt(path)` → `route.parse` → `route.render`); otherwise
+   * it always uses HTML-over-fetch.
+   */
+  dataAt?: SpaDataReader;
+}
+/** The single shared SPA kernel — pure factory over state/config/emit/deps. */
+interface SpaKernel {
+  /**
+   * 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;
+};
+//#endregion
+//#region src/plugins/site/index.d.ts
+/**
+ * Site plugin — holds global, frozen site metadata (name, url, author,
+ * description) and builds canonical URLs. Consumed by router, head, and build.
+ * `name` and `url` must be non-empty (validated at `onInit`).
+ *
+ * @example Set your site identity
+ * ```ts
+ * const app = createApp({
+ *   pluginConfigs: {
+ *     site: {
+ *       name: "My Blog",
+ *       url: "https://blog.dev",
+ *       author: "Ada Lovelace",
+ *       description: "Notes on computing"
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare const sitePlugin: import("@moku-labs/core").PluginInstance<"site", Config$3, Record<string, never>, Api$3, {}> & Record<never, never>;
+//#endregion
+//#region src/plugins/i18n/index.d.ts
+/**
+ * Internationalization plugin — locale registry plus a flat translation helper
+ * with default-locale fallback. Pure config-as-data (no state or events);
+ * consumed read-only by content, router, head, and build.
+ *
+ * @example Register locales and translations
+ * ```ts
+ * const app = createApp({
+ *   pluginConfigs: {
+ *     i18n: {
+ *       locales: ["en", "uk"],
+ *       defaultLocale: "en",
+ *       localeNames: { en: "English", uk: "Українська" },
+ *       translations: { uk: { "nav.home": "Головна" } }
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare const i18nPlugin: import("@moku-labs/core").PluginInstance<"i18n", Config$2, Record<string, never>, Api$2, {}> & Record<never, never>;
+//#endregion
+//#region src/plugins/router/builders/route-builder.d.ts
+/**
+ * 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.
+ *
+ * @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 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 defineRoutes<T extends RouteMap>(routes: T): T;
+//#endregion
+//#region src/plugins/router/index.d.ts
+/**
+ * Router plugin — typed, named route definitions with locale-aware URL generation
+ * and matching. Author routes with {@link route} + {@link defineRoutes}. Depends
+ * on site (base URL) and i18n (locales).
+ *
+ * @example Define routes and choose a render mode
+ * ```ts
+ * const app = createApp({
+ *   pluginConfigs: {
+ *     router: {
+ *       routes: defineRoutes({
+ *         home: route("/"),
+ *         article: route("/blog/{slug}/")
+ *       }),
+ *       mode: "hybrid" // "ssg" | "spa" | "hybrid" (default)
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare const routerPlugin: import("@moku-labs/core").PluginInstance<"router", RouterConfig, RouterState, RouterApi, {}> & {
+  route: typeof route;
+  defineRoutes: typeof defineRoutes;
+};
+//#endregion
+//#region src/plugins/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;
+/**
+ * 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")
+ */
+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
+/**
+ * Head plugin — composes per-route `<head>` metadata (title template, Open Graph,
+ * Twitter cards, canonical, hreflang). Use the re-exported SEO primitives
+ * ({@link meta}, {@link og}, {@link twitter}, …) inside a route's `.head()`.
+ * Depends on site, i18n, and router.
+ *
+ * @example Set global head defaults
+ * ```ts
+ * const app = createApp({
+ *   pluginConfigs: {
+ *     head: {
+ *       titleTemplate: "%s — My Blog",
+ *       twitterCard: "summary_large_image",
+ *       twitterHandle: "@moku_labs"
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare const headPlugin: import("@moku-labs/core").PluginInstance<"head", Config, State, Api, {}> & {
+  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/spa/components.d.ts
+/**
+ * Create a validated component definition. Validates hook names at registration
+ * for fail-fast typo detection (e.g. `onMout` throws immediately) and asserts
+ * each provided hook is a function.
+ *
+ * @param name - Unique component name.
+ * @param hooks - Lifecycle hook implementations.
+ * @returns A `ComponentDef` ready to `register`.
+ * @throws {Error} If `name` is empty, any hook key is not in
+ *   `COMPONENT_HOOK_NAMES`, or any provided hook value is not a function.
+ * @example
+ * const counter = createComponent("counter", {
+ *   onMount({ el }) { el.textContent = "0"; }
+ * });
+ */
+declare function createComponent(name: string, hooks: ComponentHooks): ComponentDef;
+//#endregion
+//#region src/plugins/spa/index.d.ts
+/**
+ * SPA plugin — progressive client-side navigation layered over the static site:
+ * swaps a page region on navigation, with an optional progress bar and View
+ * Transitions. Register interactive islands with {@link createComponent}. Depends
+ * on router and head; emits `spa:navigate`, `spa:navigated`, `spa:component-mount`,
+ * and `spa:component-unmount`.
+ *
+ * @example Enable view transitions and a custom swap region
+ * ```ts
+ * const app = createApp({
+ *   pluginConfigs: {
+ *     spa: {
+ *       swapSelector: "main > section",
+ *       viewTransitions: true,
+ *       progressBar: true
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare const spaPlugin: import("@moku-labs/core").PluginInstance<"spa", SpaConfig, SpaState, SpaApi, {
+  "spa:navigate": {
+    from: string;
+    to: string;
+  };
+  "spa:navigated": {
+    url: string;
+  };
+  "spa:component-mount": {
+    name: string;
+    el: Element;
+  };
+  "spa:component-unmount": {
+    name: string;
+    el: Element;
+  };
+}> & Record<never, never>;
+declare namespace types_d_exports {
+  export { DataConfig, DataEntry, DataProvider, DataState, DataWriteSummary };
+}
+/**
+ * @file data plugin — type definitions (Standard tier).
+ *
+ * The `data` plugin is the **agnostic data provider** for the SSG→DATA→SPA pattern.
+ * It owns ONE thing: the contract `page path → persisted JSON file`. It knows
+ * NOTHING about what the data *is* — no domain types appear here. A route decides
+ * its own data shape (`load`'s return) and its own validation (`route.parse`).
+ *
+ *  - **Node (build):** `write(entries)` persists one JSON file per page, keyed by
+ *    the page's URL via {@link DataProvider.fileFor}. `build` supplies the entries
+ *    (it already expanded the routes), so there is no duplicate expansion here.
+ *  - **Browser (runtime):** `at(path)` fetches + caches that file as `unknown`; the
+ *    route's `parse` validates it into the route's data type before `render`.
+ *
+ * The Node-only file-writing code (`node:fs`) is isolated behind a lazy `import()`
+ * inside `write()`, so composing `data` in a browser app keeps the bundle free of
+ * `node:*`.
+ */
+/**
+ * Configuration for {@link dataPlugin}. All fields have defaults (see `./config`).
+ *
+ * @example
+ * ```ts
+ * const cfg: DataConfig = { outputDir: "_data", baseUrl: "/_data/" };
+ * ```
+ */
+type DataConfig = {
+  /**
+   * WRITE side (Node): output subdir relative to the build `outDir`, a filesystem
+   * path where `write()` persists the per-page JSON. Default `"_data"`.
+   */
+  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/"`.
+   */
+  baseUrl: string;
+};
+/** One page's data to persist — `build` produces these from its route expansion. */
+interface DataEntry {
+  /** The page's URL path (e.g. `/en/hello/`); maps to a file via {@link DataProvider.fileFor}. */
+  path: string;
+  /** The serializable data for this page (the route's `load`/projection output). */
+  data: unknown;
+}
+/** Summary returned by {@link DataProvider.write} and cached in state. */
+interface DataWriteSummary {
+  /** Number of per-page JSON files written. */
+  fileCount: number;
+  /** Total bytes written across all files. */
+  bytes: number;
+  /** The written file paths, relative to the build `outDir`. */
+  files: string[];
+}
+/**
+ * Internal data state. `lastWrite` records the most recent `write()` (Node);
+ * `cache` memoizes fetched per-path data (browser, lazy). Both empty until their
+ * respective side first runs.
+ */
+interface DataState {
+  /** Result of the last `write()`, or `null` if it has not run yet (Node). */
+  lastWrite: DataWriteSummary | null;
+  /** Per-path fetched data, cached after the first `at(path)` (browser). */
+  cache: Map<string, unknown>;
+}
+/**
+ * Public API mounted at `app.data` — the agnostic data provider. `write()` is the
+ * Node persist side; `at()` is the browser read side; `urlFor`/`fileFor` are the
+ * pure URL convention shared by both so the written file and fetched URL can never
+ * drift.
+ *
+ * @example
+ * ```ts
+ * // Node build (build supplies the entries it already expanded):
+ * await app.data.write([{ path: "/en/hello/", data: article }]);
+ *
+ * // Browser (inside spa nav): fetch the page's data, then route.parse validates it:
+ * const raw = await app.data.at("/en/hello/"); // unknown | null
+ * ```
+ */
+type DataProvider = {
+  /**
+   * 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.
+   *
+   * @param path - The page URL path (e.g. `/en/hello/`).
+   * @returns The page's raw data, or `null` on failure.
+   */
+  at(path: string): Promise<unknown | null>;
+  /**
+   * WRITE (Node) — persist one JSON file per entry, keyed by page path via
+   * {@link DataProvider.fileFor}. Called by `build` after it expands routes (no
+   * duplicate expansion). Lazily loads its `node:fs` writer, so it never
+   * contaminates a browser bundle.
+   *
+   * @param entries - The per-page data to persist.
+   * @param options - Optional overrides.
+   * @param options.outDir - Build output directory to write under (default `./dist`).
+   * @returns A summary of the written files.
+   */
+  write(entries: readonly DataEntry[], options?: {
+    outDir?: string;
+  }): Promise<DataWriteSummary>;
+  /**
+   * PURE — the browser fetch URL for a page path (e.g. `/en/hello/` →
+   * `/_data/en/hello/index.json`). Shared with {@link DataProvider.fileFor}.
+   *
+   * @param path - The page URL path.
+   * @returns The site-root-relative data URL.
+   */
+  urlFor(path: string): string;
+  /**
+   * PURE — the `outDir`-relative file path for a page path (e.g. `/en/hello/` →
+   * `_data/en/hello/index.json`). Shared with {@link DataProvider.urlFor}.
+   *
+   * @param path - The page URL path.
+   * @returns The output-relative file path.
+   */
+  fileFor(path: string): string;
+};
+//#endregion
+//#region src/plugins/data/index.d.ts
+/**
+ * Data plugin — the agnostic data provider. Mounts `write(entries)` (Node persist),
+ * `at(path)` (browser read), and the pure `urlFor`/`fileFor` convention at `app.data`.
+ *
+ * @example
+ * ```ts
+ * // Node build: `build` calls app.data.write(...) during its pages phase when
+ * // router.mode !== "ssg". Just compose the plugin:
+ * const app = createApp({
+ *   plugins: [dataPlugin, contentPlugin, buildPlugin],
+ *   pluginConfigs: { content: { contentDir: "./content" }, router: { routes, mode: "hybrid" } }
+ * });
+ * await app.start();
+ * await app.build.run();   // writes HTML + per-page data sidecars
+ *
+ * // Browser app: compose `dataPlugin` too; spa fetches via app.data.at(path) on nav.
+ * ```
+ */
+declare const dataPlugin: import("@moku-labs/core").PluginInstance<"data", DataConfig, DataState, DataProvider, {}> & Record<never, never>;
+//#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/browser.d.ts
+/**
+ * Create and initialize a browser-safe `@moku-labs/web` application — the Layer-3
+ * entry point for client bundles. Identical to the main entry's `createApp`, but
+ * this module's import graph contains zero node/native code, and `env` defaults to
+ * the `browserEnv()` provider (reads `import.meta.env` / `globalThis.__ENV__`).
+ *
+ * The defaults are the isomorphic plugin set (`site`, `i18n`, `router`, `head`,
+ * `spa` + `log`/`env` core). For client-data navigation (`router.mode("spa"|"hybrid")`)
+ * compose the `data` plugin — its consume-half (`at()`) is browser-safe.
+ *
+ * @param options - Optional configuration:
+ *  - `pluginConfigs` — per-plugin overrides, keyed by plugin name.
+ *  - `config` — global framework config (e.g. `{ mode: "development" }`).
+ *  - `plugins` — extra plugins (e.g. `dataPlugin` 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
+ * // Client SPA — env works with no wiring (browserEnv is the default provider):
+ * const app = createApp({
+ *   plugins: [dataPlugin],
+ *   pluginConfigs: {
+ *     router: { mode: "spa", routes: defineRoutes({ home: route("/"), post: route("/blog/{slug}/") }) }
+ *   }
+ * });
+ * await app.start();
+ * app.env.get("PUBLIC_API_URL"); // resolved from import.meta.env
+ * ```
+ */
+declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs/core").AnyPluginInstance[] = readonly []>(options?: import("@moku-labs/core").CreateAppOptions<Config$4, Events, (import("@moku-labs/core").PluginInstance<"site", Config$3, Record<string, never>, Api$3, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"i18n", Config$2, Record<string, never>, Api$2, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"router", RouterConfig, RouterState, RouterApi, {}> & {
+  route: typeof route;
+  defineRoutes: typeof defineRoutes;
+}) | (import("@moku-labs/core").PluginInstance<"head", Config, State, Api, {}> & {
+  meta: typeof meta;
+  og: typeof og;
+  twitter: typeof twitter;
+  jsonLd: typeof jsonLd;
+  canonical: typeof canonical;
+  hreflang: typeof hreflang;
+  feedLink: typeof feedLink;
+  buildArticleHead: typeof buildArticleHead;
+}) | (import("@moku-labs/core").PluginInstance<"spa", SpaConfig, SpaState, SpaApi, {
+  "spa:navigate": {
+    from: string;
+    to: string;
+  };
+  "spa:navigated": {
+    url: string;
+  };
+  "spa:component-mount": {
+    name: string;
+    el: Element;
+  };
+  "spa:component-unmount": {
+    name: string;
+    el: Element;
+  };
+}> & Record<never, never>) | ExtraPlugins[number], [...ExtraPlugins], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", LogConfig, LogState, LogApi>, import("@moku-labs/core").CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>]>> | undefined) => import("@moku-labs/core").App<Config$4, Events, (import("@moku-labs/core").PluginInstance<"site", Config$3, Record<string, never>, Api$3, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"i18n", Config$2, Record<string, never>, Api$2, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"router", RouterConfig, RouterState, RouterApi, {}> & {
+  route: typeof route;
+  defineRoutes: typeof defineRoutes;
+}) | (import("@moku-labs/core").PluginInstance<"head", Config, State, Api, {}> & {
+  meta: typeof meta;
+  og: typeof og;
+  twitter: typeof twitter;
+  jsonLd: typeof jsonLd;
+  canonical: typeof canonical;
+  hreflang: typeof hreflang;
+  feedLink: typeof feedLink;
+  buildArticleHead: typeof buildArticleHead;
+}) | (import("@moku-labs/core").PluginInstance<"spa", SpaConfig, SpaState, SpaApi, {
+  "spa:navigate": {
+    from: string;
+    to: string;
+  };
+  "spa:navigated": {
+    url: string;
+  };
+  "spa:component-mount": {
+    name: string;
+    el: Element;
+  };
+  "spa:component-unmount": {
+    name: string;
+    el: Element;
+  };
+}> & Record<never, never>) | ExtraPlugins[number], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", LogConfig, LogState, LogApi>, import("@moku-labs/core").CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>]>>;
+/**
+ * Create a custom plugin bound to this framework's `Config`/`Events` and core
+ * APIs. Plugin types are inferred from the spec object — never written explicitly.
+ * Pass the result to {@link createApp} via `plugins`.
+ *
+ * @example
+ * ```ts
+ * const analytics = createPlugin("analytics", {
+ *   config: { writeKey: "" },
+ *   api: (ctx) => ({ track: (event: string) => ctx.log.info("analytics:track", { event }) })
+ * });
+ *
+ * const app = createApp({ plugins: [analytics] });
+ * ```
+ */
+declare const createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<Config$4, 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 Data, types_d_exports$1 as Env, types_d_exports$2 as Head, types_d_exports$3 as Log, types_d_exports$4 as Router, types_d_exports$5 as Spa, browserEnv, buildArticleHead, canonical, createApp, createComponent, createPlugin, dataPlugin, defineRoutes, envPlugin, feedLink, headPlugin, hreflang, i18nPlugin, jsonLd, logPlugin, meta, og, route, routerPlugin, sitePlugin, spaPlugin, twitter };