@moku-labs/web 0.5.5 → 0.6.0

package/dist/index.d.mts

@@ -4,7 +4,7 @@ import { ComponentChildren, VNode } from "preact";
 import { BundledTheme, ThemeRegistrationAny } from "shiki";
 
 //#region src/plugins/log/types.d.ts
-declare namespace types_d_exports$6 {
+declare namespace types_d_exports$7 {
   export { ExpectChain, LogApi, LogConfig, LogEntry, LogLevel, LogSink, LogState };
 }
 /**
@@ -144,7 +144,7 @@ type LogApi = {
   addSink(sink: LogSink): void; /** Clear all recorded entries while keeping registered sinks. */
   reset(): void;
 };
-declare namespace types_d_exports$4 {
+declare namespace types_d_exports$5 {
   export { EnvApi, EnvConfig, EnvProvider, EnvState, EnvVarSpec };
 }
 /**
@@ -340,7 +340,7 @@ declare const envPlugin: import("@moku-labs/core").CorePluginInstance<"env", Env
  * Global framework configuration. Minimal by design — per-plugin config is
  * resolved via `pluginConfigs`, not merged here.
  */
-type Config$7 = {
+type Config$8 = {
   /** Runtime mode. Drives log sink defaults, content draft filtering, build minify. */mode: "production" | "development";
 };
 /**
@@ -375,7 +375,7 @@ type Events = {};
  * });
  * ```
  */
-type Config$6 = {
+type Config$7 = {
   /** Human-readable site name. Used in feeds, og:site_name, and titles. MUST be non-empty. */name: string; /** Absolute base URL of the site, e.g. "https://blog.dev". MUST be a valid absolute URL (http/https). */
   url: string; /** Default author/byline for the site. Used in feeds and article author meta. */
   author: string; /** Short site description. Used in feeds, the default meta description, and og:description fallbacks. */
@@ -385,7 +385,7 @@ type Config$6 = {
  * Public API of the site plugin — read-only accessors over frozen global
  * site metadata, plus canonical URL construction.
  */
-type Api$6 = {
+type Api$7 = {
   /**
    * Returns the configured site name.
    *
@@ -463,7 +463,7 @@ type Api$6 = {
  * }
  * ```
  */
-type Config$5 = {
+type Config$6 = {
   readonly locales: readonly string[];
   readonly defaultLocale: string;
   readonly localeNames?: Record<string, string>;
@@ -474,7 +474,7 @@ type Config$5 = {
  * Public API of the i18n plugin. Injected as `app.i18n` and reachable from
  * other plugins via `ctx.require(i18nPlugin)`.
  */
-type Api$5 = {
+type Api$6 = {
   /**
    * Returns the configured supported locales in declared order.
    *
@@ -542,8 +542,8 @@ type Api$5 = {
    */
   t(locale: string, key: string): string;
 };
-declare namespace types_d_exports$7 {
-  export { Api$4 as Api, ClientRoute, CompileInput, CompiledRoute, Config$4 as Config, ExtractRouteParams, ExtractSegmentParameter, HeadConfig$1 as HeadConfig, LayoutContext, MatcherTable, Prettify, RouteBuilder, RouteContext, RouteDefinition, RouteHandlers, RouteMap, RouteState, RouterApi, RouterConfig, RouterState, State$4 as State, TypedRoute };
+declare namespace types_d_exports$8 {
+  export { Api$5 as Api, ClientRoute, CompileInput, CompiledRoute, Config$5 as Config, ExtractRouteParams, ExtractSegmentParameter, HeadConfig$1 as HeadConfig, LayoutContext, MatcherTable, Prettify, RouteBuilder, RouteContext, RouteDefinition, RouteHandlers, RouteMap, RouteState, RouterApi, RouterConfig, RouterState, State$5 as State, TypedRoute };
 }
 /**
  * Param contribution of a single path segment. `{name:?}` / `:name?` → optional;
@@ -867,13 +867,13 @@ type RouterApi = {
   mode(): "ssg" | "spa" | "hybrid";
 };
 /** Re-export under the canonical `Config` name for the plugin-types barrel. */
-type Config$4 = RouterConfig;
+type Config$5 = RouterConfig;
 /** Re-export under the canonical `State` name for the plugin-types barrel. */
-type State$4 = RouterState;
+type State$5 = RouterState;
 /** Re-export under the canonical `Api` name for the plugin-types barrel. */
-type Api$4 = RouterApi;
-declare namespace types_d_exports$5 {
-  export { Api$3 as Api, ArticleMeta, Config$3 as Config, HeadConfig, HeadDefaults, HeadElement, ResolvedRoute, State$3 as State };
+type Api$5 = RouterApi;
+declare namespace types_d_exports$6 {
+  export { Api$4 as Api, ArticleMeta, Config$4 as Config, HeadConfig, HeadDefaults, HeadElement, ResolvedRoute, State$4 as State };
 }
 /**
  * @file head plugin — type definitions skeleton
@@ -889,7 +889,7 @@ declare namespace types_d_exports$5 {
  * const config: Config = { titleTemplate: "%s — Moku" };
  * ```
  */
-type Config$3 = {
+type Config$4 = {
   /** Title template applied to per-route titles. `%s` is replaced by the route title. */titleTemplate?: string; /** Default Open Graph image URL used when a route does not supply one. */
   defaultOgImage?: string; /** Default Twitter card type emitted when og/twitter content is present. */
   twitterCard?: "summary" | "summary_large_image"; /** Default Twitter site handle (e.g. `"@moku_labs"`) emitted as `twitter:site`. */
@@ -907,7 +907,7 @@ type Config$3 = {
  * const state: State = { defaults: null };
  * ```
  */
-type State$3 = {
+type State$4 = {
   /** Normalized head defaults, assigned once in `onInit` (initially `null`). */defaults: HeadDefaults | null;
 };
 /**
@@ -1001,7 +1001,7 @@ type ResolvedRoute = {
  * const html: string = api.render(route, data);
  * ```
  */
-type Api$3 = {
+type Api$4 = {
   /**
    * Compose the final `<head>` inner HTML for a route. Pulled synchronously by `build`.
    *
@@ -1015,7 +1015,7 @@ type Api$3 = {
    */
   render(route: ResolvedRoute, data: unknown): string;
 };
-declare namespace types_d_exports$8 {
+declare namespace types_d_exports$9 {
   export { COMPONENT_HOOK_NAMES, ComponentContext, ComponentDef, ComponentHooks, ComponentInstance, ExtractApi$1 as ExtractApi, PageData, ResolvedSpaConfig, SpaApi, SpaConfig, SpaContext, SpaDataReader, SpaEmitFunction, SpaEvents, SpaKernel, SpaKernelDeps, SpaRequire, SpaState };
 }
 /** Payload map for the events `spa` emits, used to type the kernel's `emit` closure. */
@@ -1216,7 +1216,7 @@ interface SpaKernelDeps {
   /** Router plugin API — used for client-side route matching (`match`) + the resolved `mode`. */
   router: RouterApi;
   /** Head plugin API — its pure compose is reused for client head-sync. */
-  head: Api$3;
+  head: Api$4;
   /**
    * The OPTIONAL `data` reader. Present only when the `data` plugin is composed.
    * When present (and `router.mode() !== "ssg"`), navigation first tries the client
@@ -1323,7 +1323,7 @@ type SpaApi = {
   current(): string;
 };
 declare namespace types_d_exports {
-  export { Api$2 as Api, BuildCacheEntry, BuildEvents, BuildResult, Config$2 as Config, ExtractApi, OgFont, OgImageConfig, OgPngRenderer, PhaseContext, PhaseEmit, PhaseLog, PhaseName, PhaseRequire, RichOgInput, State$2 as State };
+  export { Api$3 as Api, BuildCacheEntry, BuildEvents, BuildResult, Config$3 as Config, ExtractApi, OgFont, OgImageConfig, OgPngRenderer, PhaseContext, PhaseEmit, PhaseLog, PhaseName, PhaseRequire, RichOgInput, State$3 as State };
 }
 /**
  * Structural extraction of a plugin instance's public API from its `_phantom`
@@ -1400,8 +1400,8 @@ type PhaseRequire = <PluginCandidate extends {
  * ```
  */
 type PhaseContext = {
-  /** Mutable per-run build state (caches + runId). */state: State$2; /** Resolved, frozen build config. */
-  readonly config: Readonly<Config$2>; /** Global framework config (mode, etc.). */
+  /** Mutable per-run build state (caches + runId). */state: State$3; /** Resolved, frozen build config. */
+  readonly config: Readonly<Config$3>; /** Global framework config (mode, etc.). */
   readonly global: Readonly<{
     mode: "production" | "development";
   }>; /** Resolve a depended-upon plugin instance to its public API. */
@@ -1510,7 +1510,7 @@ interface OgImageConfig {
  * const config: Config = { outDir: "./dist", minify: true, feeds: true, sitemap: true, images: true, ogImage: false };
  * ```
  */
-type Config$2 = {
+type Config$3 = {
   /** Output directory for the built site. */outDir: string; /** Minify bundled CSS/JS. */
   minify: boolean; /** Generate RSS/Atom/JSON feeds. */
   feeds: boolean; /** Generate sitemap.xml + robots.txt. */
@@ -1551,9 +1551,9 @@ type BuildCacheEntry = Record<string, string>;
  * const state: State = { config, manifest: null, buildCache: new Map(), runId: null, ogImageHashCache: new Map() };
  * ```
  */
-interface State$2 {
+interface State$3 {
   /** Resolved, frozen config snapshot. */
-  config: Config$2;
+  config: Config$3;
   /** Cached route manifest for the current run (populated in Phase 3 from router). */
   manifest: RouteDefinition[] | null;
   /** Per-run build artifacts (e.g. hashed CSS/JS asset paths from Phase 1). */
@@ -1575,7 +1575,7 @@ interface State$2 {
  * const phase: PhaseName = "bundle";
  * ```
  */
-type PhaseName = "bundle" | "content" | "images" | "pages" | "feeds" | "sitemap" | "og-images" | "public" | "not-found" | "locale-redirects" | "root-index";
+type PhaseName = "bundle" | "content" | "images" | "pages" | "content-images" | "feeds" | "sitemap" | "og-images" | "public" | "not-found" | "locale-redirects" | "root-index";
 /**
  * Result of a completed build run.
  *
@@ -1600,7 +1600,7 @@ interface BuildResult {
  * const result = await app.build.run();
  * ```
  */
-type Api$2 = {
+type Api$3 = {
   /**
    * Run the full SSG pipeline and write the site to disk.
    *
@@ -1649,7 +1649,7 @@ type Api$2 = {
  * });
  * ```
  */
-declare const buildPlugin: import("@moku-labs/core").PluginInstance<"build", Config$2, State$2, Api$2, {
+declare const buildPlugin: import("@moku-labs/core").PluginInstance<"build", Config$3, State$3, Api$3, {
   "build:phase": {
     phase: PhaseName;
     status: "start" | "done";
@@ -1661,218 +1661,819 @@ declare const buildPlugin: import("@moku-labs/core").PluginInstance<"build", Con
     durationMs: number;
   };
 }> & Record<never, never>;
-declare namespace types_d_exports$1 {
-  export { Api$1 as Api, Article, ArticleCard, ComputedFields, Config$1 as Config, ContentApiContext, ContentEvents, Frontmatter, State$1 as State };
+declare namespace types_d_exports$4 {
+  export { Api$2 as Api, Config$2 as Config, DeployErrorCode, DeployInitOptions, DeployResult, DeployRunOptions, InitResult, SpawnFunction, SpawnOptions, SpawnedProcess, State$2 as State, WranglerErrorKind };
 }
 /**
- * Configuration for the content plugin.
- *
- * @example
- * ```ts
- * { contentDir: "./src/content", trustedContent: false, shikiTheme: "github-dark" }
- * ```
- */
-type Config$1 = {
-  /** Absolute or project-relative path to the content directory. Validated in onInit. */contentDir: string;
-  /**
-   * SECURITY GATE. When false (the default), rehype-sanitize runs as the final
-   * pipeline step. Set true ONLY for fully author-controlled Markdown — true
-   * disables sanitize and trusts all raw HTML.
-   */
-  trustedContent: boolean; /** Additional remark plugins, concatenated AFTER framework defaults. Defaults to []. */
-  extraRemarkPlugins?: readonly Pluggable[]; /** Additional rehype plugins, concatenated after custom transforms, before Shiki + sanitize. Defaults to []. */
-  extraRehypePlugins?: readonly Pluggable[];
-  /**
-   * Shiki theme for syntax highlighting: a bundled theme NAME — typed as Shiki's
-   * `BundledTheme` union so editors autocomplete the ~60 built-ins (default
-   * "github-dark") — or a custom `ThemeRegistration` object. Passed straight through
-   * to `@shikijs/rehype`'s `theme`. (Like Shiki's own theme type, an arbitrary string
-   * still compiles via the object arm, so this is autocomplete, not typo-rejection.)
-   */
-  shikiTheme?: BundledTheme | ThemeRegistrationAny; /** Author applied to articles whose frontmatter omits author. Defaults to undefined. */
-  defaultAuthor?: string;
-};
-/**
- * Internal mutable state for the content plugin.
- *
- * @example
- * ```ts
- * { processor: null, articles: new Map(), slugs: null, dirtyPaths: new Set() }
- * ```
- */
-type State$1 = {
-  /** Lazily-created unified processor singleton. null until first render()/loadAll(). */processor: Processor | null; /** Article cache keyed locale -> (slug -> Article). Starts empty. */
-  articles: Map<string, Map<string, Article>>; /** Discovered, sorted slug list cached after first disk scan. null until first discovery. */
-  slugs: string[] | null; /** Paths marked stale by invalidate(); next loadAll() re-reads only these. Starts empty. */
-  dirtyPaths: Set<string>;
-};
-/**
- * YAML frontmatter parsed from each article file.
- *
- * @example
- * ```ts
- * { title: "Hello", date: "2026-01-15", description: "Intro", tags: [], language: "en" }
- * ```
+ * @file deploy plugin — type definitions.
  */
-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 }
- * ```
+ * 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).
  */
-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;
-};
+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>;
+}
 /**
- * A fully processed, render-ready article.
- *
- * @example
- * ```ts
- * { frontmatter, computed, html: "<p>…</p>", locale: "en", isFallback: false, url: "/en/hello/" }
- * ```
+ * 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.
  */
-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;
-};
+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>;
+}
 /**
- * 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/" }
- * ```
+ * 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 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;
-};
+type SpawnFunction = (cmd: string[], options: SpawnOptions) => SpawnedProcess;
 /**
- * Notification-only events emitted by the content plugin.
- *
- * @example
- * ```ts
- * emit("content:ready", { locales: ["en"], articleCount: 3 });
- * ```
+ * A deploy error `code` from the wrangler error taxonomy and preflight validators.
  */
-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[];
-  };
-};
+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";
 /**
- * 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 };
- * ```
+ * The subset of wrangler error `code`s classifyWranglerError can produce from a
+ * non-zero wrangler exit.
  */
-type ContentApiContext = {
-  /** Mutable plugin state (article cache + lazy processor). */state: State$1; /** Resolved plugin configuration. */
-  config: Config$1; /** Global framework configuration (mode, etc.). */
-  global: {
-    mode: "production" | "development";
-  }; /** Emit a registered content event. */
-  emit: <K extends keyof ContentEvents>(event: K, payload: ContentEvents[K]) => void; /** Active locale codes from i18n. */
-  locales: () => readonly string[]; /** Default locale code from i18n (fallback source). */
-  defaultLocale: () => string; /** Build a canonical article URL for a locale + slug. */
-  articleToUrl: (locale: string, slug: string) => string;
-};
+type WranglerErrorKind = Extract<DeployErrorCode, "ERR_DEPLOY_PROJECT_NOT_FOUND" | "ERR_DEPLOY_AUTH_EXPIRED" | "ERR_DEPLOY_AUTH" | "ERR_DEPLOY_NETWORK" | "ERR_DEPLOY_WRANGLER_FAILED">;
 /**
- * Public API for the content plugin.
- *
- * @example
- * ```ts
- * const map = await app.content.loadAll();
- * ```
+ * Configuration for the deploy plugin.
  */
-type Api$1 = {
+type Config$2 = {
   /**
-   * Load every article across every active locale, returning a locale-keyed
-   * map of date-descending Article arrays. Emits content:ready.
+   * Deploy target. Only Cloudflare Pages is supported in this version.
+   * Defaults to `cloudflare-pages`.
    */
-  loadAll(): Promise<Map<string, Article[]>>;
+  target: "cloudflare-pages";
   /**
-   * Resolve and render a single article for one locale, with locale fallback.
-   *
-   * @param slug - Article directory name.
-   * @param locale - Requested locale code.
+   * 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`.
    */
-  load(slug: string, locale: string): Promise<Article>;
+  outDir: string;
   /**
-   * Render a raw Markdown string to HTML through the full pipeline.
-   *
-   * @param md - Raw Markdown source.
+   * Branch treated as the Cloudflare Pages production branch.
+   * Defaults to `main`.
    */
-  renderMarkdown(md: string): Promise<string>;
+  productionBranch?: string;
   /**
-   * Mark file paths stale for incremental dev rebuilds. Emits content:invalidated.
-   *
-   * @param paths - File paths to invalidate.
+   * Substrings exempt from entropy-gated secret scrubbing in logged output.
+   * Defaults to `["CLOUDFLARE_ACCOUNT_ID"]`.
    */
-  invalidate(paths: readonly string[]): void;
+  scrubAllowlist: string[];
   /**
-   * Project a full Article to a lightweight ArticleCard for list/grid rendering.
-   *
-   * @param article - The source article.
+   * Cloudflare compatibility date written into generated wrangler.jsonc.
+   * Defaults to `2024-01-01`.
    */
-  articleToCard(article: Article): ArticleCard;
+  compatibilityDate?: string;
+  /**
+   * Whether init() also generates a GitHub Actions workflow.
+   * Defaults to `false`.
+   */
+  ci?: boolean;
 };
-//#endregion
-//#region src/plugins/content/index.d.ts
 /**
- * Content plugin — Markdown pipeline: discovers files, parses frontmatter, renders
- * to sanitized HTML (rehype-sanitize unless `trustedContent`), and exposes a
- * locale-keyed Article model. Depends on i18n; emits `content:ready` and
- * `content:invalidated`.
- *
- * @example Point at a content directory and pick a Shiki theme
- * ```ts
- * const app = createApp({
- *   pluginConfigs: {
- *     content: {
- *       contentDir: "./content",
- *       shikiTheme: "github-dark",
- *       defaultAuthor: "Ada Lovelace"
- *       // trustedContent: true // ONLY for fully author-controlled Markdown — disables sanitize
- *     }
- *   }
- * });
- * ```
+ * 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$2 = {
+  /** Result of the most recent successful deploy, or null before the first run. */lastDeployment: DeployResult | null;
+  /**
+   * Injectable subprocess spawner. Defaults to Bun.spawn. Swapped for a mock in
+   * unit tests so wrangler is never actually invoked. Never reassigned at runtime.
+   */
+  spawn: SpawnFunction;
+};
+/**
+ * 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$2 = {
+  /**
+   * Deploy the built outDir to Cloudflare Pages via the wrangler subprocess.
+   * Runs preflight validators, re-validates the resolved outdir against cwd, guards
+   * the branch argument, spawns wrangler (no shell), scrubs all subprocess output
+   * before logging, records lastDeployment, and emits deploy:complete.
+   *
+   * @param options - Optional branch override 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>;
+};
+declare namespace types_d_exports$1 {
+  export { Api$1 as Api, BuildOptions, BuildSummary, CliErrorCode, CliRenderer, Command, Config$1 as Config, DeployOptions, DeployOutcome, FileResponseFunction, PreviewOptions, ReloadInfo, ServeOptions, ServeStaticFunction, ServeStaticOptions, ServerHandle, ServerInfo, State$1 as State, WatchHandle };
+}
+/**
+ * A cli error `code` from the config-validation and runtime taxonomy. Mirrors the
+ * deploy plugin's coded-error pattern so every thrown value carries a stable `code`.
+ *
+ * @example
+ * const code: CliErrorCode = "ERR_CLI_CONFIG";
+ */
+type CliErrorCode = "ERR_CLI_CONFIG" | "ERR_CLI_NOT_FOUND";
+/**
+ * The four commands a single cli process can run. Each maps to one consumer script
+ * (`scripts/{build,serve,preview,deploy}.ts`) and is rendered as the Panel header.
+ *
+ * @example
+ * const command: Command = "build";
+ */
+type Command = "build" | "serve" | "preview" | "deploy";
+/**
+ * Information rendered into the bordered server-ready panel by `serve()`/`preview()`.
+ *
+ * @example
+ * const info: ServerInfo = { local: "http://localhost:4173", network: null };
+ */
+type ServerInfo = {
+  /** The loopback URL the server is reachable at (e.g. `http://localhost:4173`). */local: string; /** The LAN URL derived from the first non-internal IPv4, or `null` when offline. */
+  network: string | null; /** Directories `serve()` is watching for changes (omitted by `preview()`). */
+  watching?: string[];
+};
+/**
+ * Information rendered after a single `serve()` rebuild: which file changed plus the
+ * fresh build summary used to print the "rebuilt N pages" line.
+ *
+ * @example
+ * const info: ReloadInfo = { file: "content/post.md", pageCount: 12, durationMs: 84 };
+ */
+type ReloadInfo = {
+  /** The changed path that triggered the rebuild. */file: string; /** Number of route pages rendered by the rebuild. */
+  pageCount: number; /** Wall-clock duration of the rebuild in milliseconds. */
+  durationMs: number;
+};
+/**
+ * The Panel renderer surface — every line of terminal output flows through this so
+ * tests can inject a line-capturing fake. Implemented by `createPanelRenderer` and
+ * is TTY/`NO_COLOR`-aware (box-drawing + color on a TTY, plain lines otherwise).
+ *
+ * @example
+ * const render: CliRenderer = createPanelRenderer();
+ * render.header("build");
+ */
+type CliRenderer = {
+  /**
+   * Render the boxed `MOKU WEB` logo + command label. Called once per command (one
+   * command = one process), so it never repeats within a run.
+   *
+   * @param command - The command being run, shown beside the logo.
+   * @returns Nothing.
+   * @example
+   * render.header("serve");
+   */
+  header(command: Command): void;
+  /**
+   * Render a live per-phase row from a `build:phase` event.
+   *
+   * @param phase - The `build:phase` payload (`{ phase, status, durationMs? }`).
+   * @returns Nothing.
+   * @example
+   * render.phase({ phase: "pages", status: "done", durationMs: 12 });
+   */
+  phase(phase: BuildEvents["build:phase"]): void;
+  /**
+   * Render the BUILD summary block from a `build:complete` event.
+   *
+   * @param summary - The `build:complete` payload (`{ outDir, pageCount, durationMs }`).
+   * @returns Nothing.
+   * @example
+   * render.built({ outDir: "dist", pageCount: 12, durationMs: 840 });
+   */
+  built(summary: BuildEvents["build:complete"]): void;
+  /**
+   * Render the bordered server-ready panel (Local / Network URLs + watched dirs).
+   *
+   * @param info - Local/Network URLs and optionally the watched directories.
+   * @returns Nothing.
+   * @example
+   * render.serverReady({ local: "http://localhost:4173", network: null });
+   */
+  serverReady(info: ServerInfo): void;
+  /**
+   * Render the post-rebuild line ("~ file" + "✓ rebuilt N pages · Xms · reloaded").
+   *
+   * @param info - The changed file plus the rebuild's page count and duration.
+   * @returns Nothing.
+   * @example
+   * render.reload({ file: "content/a.md", pageCount: 12, durationMs: 84 });
+   */
+  reload(info: ReloadInfo): void;
+  /**
+   * Render the deploy result panel from a `deploy:complete` event.
+   *
+   * @param result - The `deploy:complete` payload (`{ url, deploymentId, branch, durationMs }`).
+   * @returns Nothing.
+   * @example
+   * render.deployed({ url: "https://x.pages.dev", deploymentId: "id", branch: "main", durationMs: 1200 });
+   */
+  deployed(result: DeployResult): void;
+  /**
+   * Render a neutral informational line (e.g. the non-interactive deploy note, watch notice).
+   *
+   * @param message - The line to print.
+   * @returns Nothing.
+   * @example
+   * render.info("watching for changes…");
+   */
+  info(message: string): void;
+  /**
+   * Render a warning line (written to stderr).
+   *
+   * @param message - The warning to print.
+   * @returns Nothing.
+   * @example
+   * render.warn("deploy skipped");
+   */
+  warn(message: string): void;
+  /**
+   * Render an error line (written to stderr), optionally with a cause.
+   *
+   * @param message - The error summary to print.
+   * @param cause - Optional underlying error/value to print beneath the summary.
+   * @returns Nothing.
+   * @example
+   * render.error("build failed", err);
+   */
+  error(message: string, cause?: unknown): void;
+};
+/**
+ * A live directory watcher handle returned by the injectable `watch` seam. Closing
+ * it detaches the underlying `node:fs.watch` listener.
+ *
+ * @example
+ * const handle: WatchHandle = state.watch("content", onChange);
+ * handle.close();
+ */
+type WatchHandle = {
+  /**
+   * Stop watching and release the underlying listener.
+   *
+   * @returns Nothing.
+   * @example
+   * handle.close();
+   */
+  close(): void;
+};
+/**
+ * A running static server handle the cli stops on teardown. Declared structurally
+ * (no Bun namespace types) so it survives `.d.ts` bundling and tests can supply a
+ * fake without importing Bun.
+ *
+ * @example
+ * const handle: ServerHandle = state.serveStatic({ port, fetch });
+ * handle.stop();
+ */
+type ServerHandle = {
+  /**
+   * Stop the server and release its socket.
+   *
+   * @returns Nothing.
+   * @example
+   * handle.stop();
+   */
+  stop(): void;
+};
+/**
+ * The subset of `Bun.serve`'s options the cli uses: a port plus a `fetch` handler.
+ * Declared structurally so no Bun namespace type reaches the public surface.
+ *
+ * @example
+ * const opts: ServeStaticOptions = { port: 4173, fetch: () => new Response("ok") };
+ */
+type ServeStaticOptions = {
+  /** Port to bind the server to. */port: number;
+  /**
+   * Per-request handler returning the response (sync or async).
+   *
+   * @param request - The incoming request.
+   * @returns The response (or a promise of it).
+   * @example
+   * fetch(req) { return new Response("ok"); }
+   */
+  fetch(request: Request): Response | Promise<Response>;
+};
+/**
+ * An injectable static-server factory (defaults to `Bun.serve`). Keeps the Bun
+ * runtime dependency behind a structural seam so `serve()`/`preview()` never open a
+ * real socket in tests.
+ *
+ * @example
+ * const serveStatic: ServeStaticFunction = options => Bun.serve(options);
+ */
+type ServeStaticFunction = (options: ServeStaticOptions) => ServerHandle;
+/**
+ * An injectable file-response factory (defaults to `new Response(Bun.file(path))`).
+ * Maps a resolved on-disk path + status to the response body the server returns.
+ *
+ * @example
+ * const fileResponse: FileResponseFunction = (path, status) => new Response(Bun.file(path), { status });
+ */
+type FileResponseFunction = (path: string, status: number) => Response;
+/**
+ * Configuration for the cli plugin — the complete resolved `Config` (not a partial).
+ * Consumers override individual fields via `pluginConfigs.cli`.
+ *
+ * @example
+ * const config: Config = {
+ *   outDir: "dist", port: 4173, watchDirs: ["content", "src"],
+ *   debounceMs: 150, notFoundFile: "404.html", liveReload: true
+ * };
+ */
+type Config$1 = {
+  /** Build output directory; served by preview, asserted by build, rebuilt by serve. Default `"dist"`. */outDir: string; /** Default port for serve()/preview() (overridable per-call via options.port). Default `4173`. */
+  port: number; /** Directories serve() watches for changes (recursive). Default `["content", "src"]`. */
+  watchDirs: string[]; /** Debounce window (ms) coalescing FS-event bursts into one rebuild. Default `150`. */
+  debounceMs: number; /** Filename build() asserts exists at outDir root (CF Pages flips to SPA mode without it). Default `"404.html"`. */
+  notFoundFile: string; /** Inject the live-reload SSE client into HTML during serve() (never during preview()). Default `true`. */
+  liveReload: boolean;
+};
+/**
+ * Runtime state for the cli plugin — injectable seams so every command is testable
+ * without real sockets/FS-watch/TTY (mirrors deploy's injectable `spawn`).
+ *
+ * @example
+ * const state: State = createState();
+ */
+type State$1 = {
+  /** Panel renderer — all terminal output flows through this. Tests inject a line-capturing fake. */render: CliRenderer;
+  /**
+   * Interactive y/N prompt used by deploy(). Default reads stdin (TTY); tests inject a canned answer.
+   *
+   * @param question - The yes/no question to display.
+   * @returns Resolves `true` when the user answered yes.
+   * @example
+   * const ok = await state.confirm("Deploy dist/?");
+   */
+  confirm: (question: string) => Promise<boolean>;
+  /**
+   * Monotonic clock for durations. Default `Date.now`; tests inject for deterministic timing.
+   *
+   * @returns The current time in milliseconds.
+   * @example
+   * const t = state.clock();
+   */
+  clock: () => number;
+  /**
+   * Recursive directory watcher factory used by serve(). Default wraps `node:fs.watch`;
+   * tests inject a fake emitter.
+   *
+   * @param dir - The directory to watch recursively.
+   * @param onChange - Invoked on any change beneath `dir`.
+   * @returns A handle whose `close()` detaches the watcher.
+   * @example
+   * const handle = state.watch("content", () => rebuild());
+   */
+  watch: (dir: string, onChange: () => void) => WatchHandle; /** Static-server factory used by serve()/preview(). Default `Bun.serve`; tests inject a fake. */
+  serveStatic: ServeStaticFunction; /** File-response factory mapping a resolved path + status to a `Response`. Default `Bun.file`. */
+  fileResponse: FileResponseFunction;
+  /**
+   * LAN network-URL deriver for the server-ready panel. Default reads `node:os`
+   * interfaces; tests inject a deterministic value.
+   *
+   * @param port - The port the server is bound to.
+   * @returns The `http://<ip>:<port>` URL, or `null` when offline.
+   * @example
+   * const url = state.networkUrl(4173);
+   */
+  networkUrl: (port: number) => string | null;
+};
+/**
+ * Summary returned by `cli.build()` — the awaited `build.run()` result.
+ *
+ * @example
+ * const summary: BuildSummary = { outDir: "dist", pageCount: 12, durationMs: 840 };
+ */
+type BuildSummary = {
+  /** Resolved output directory the site was written to. */outDir: string; /** Number of route pages rendered. */
+  pageCount: number; /** Total wall-clock duration of the run, in milliseconds. */
+  durationMs: number;
+};
+/**
+ * Outcome returned by `cli.deploy()` — either a completed deploy (with details) or a
+ * skipped one. A skip happens only when an interactive TTY user answers "no" at the
+ * confirm prompt (`reason: "declined"`). Non-interactive runs (CI / non-TTY) never
+ * prompt and always proceed, so they never skip — the scripts are CI-safe.
+ *
+ * @example
+ * const outcome: DeployOutcome = { deployed: false, reason: "declined" };
+ */
+type DeployOutcome = {
+  deployed: true;
+  url: string;
+  deploymentId: string;
+  branch: string;
+  durationMs: number;
+} | {
+  deployed: false;
+  reason: "declined";
+};
+/**
+ * Options for `cli.build()`.
+ *
+ * @example
+ * await app.cli.build({ assertNotFound: false });
+ */
+type BuildOptions = {
+  /** Assert `outDir/notFoundFile` exists after the build. Defaults to `true`. */assertNotFound?: boolean;
+};
+/**
+ * Options for `cli.serve()`.
+ *
+ * @example
+ * await app.cli.serve({ port: 3000 });
+ */
+type ServeOptions = {
+  /** Port to bind the dev server to. Defaults to `config.port`. */port?: number; /** Reserved for opening the browser on start (not yet implemented). Defaults to `false`. */
+  open?: boolean;
+};
+/**
+ * Options for `cli.preview()`.
+ *
+ * @example
+ * await app.cli.preview({ port: 8080 });
+ */
+type PreviewOptions = {
+  /** Port to bind the preview server to. Defaults to `config.port`. */port?: number;
+};
+/**
+ * Options for `cli.deploy()`.
+ *
+ * @example
+ * await app.cli.deploy({ branch: "preview/x", yes: true });
+ */
+type DeployOptions = {
+  /** Branch to deploy. Defaults to the deploy plugin's production branch. */branch?: string; /** Skip the y/N confirm and deploy immediately. Defaults to `false`. */
+  yes?: boolean;
+};
+/**
+ * Public API of the cli plugin (mounted at `app.cli`) — exactly four methods.
+ *
+ * @example
+ * await app.cli.build();
+ */
+type Api$1 = {
+  /**
+   * Run the SSG build and assert the not-found page exists.
+   *
+   * @param options - Optional `assertNotFound` toggle (default `true`).
+   * @returns The build summary (`outDir`, `pageCount`, `durationMs`).
+   * @throws {Error} `ERR_CLI_NOT_FOUND` when the not-found page is missing and asserted.
+   * @example
+   * const summary = await app.cli.build();
+   */
+  build(options?: BuildOptions): Promise<BuildSummary>;
+  /**
+   * Dev loop: build once, serve `dist/` in-process (live-reload injected), watch
+   * `watchDirs`, debounced rebuild + reload. Resolves when SIGINT/SIGTERM tears down.
+   *
+   * @param options - Optional port override.
+   * @returns Resolves once the server has been torn down.
+   * @example
+   * await app.cli.serve({ port: 3000 });
+   */
+  serve(options?: ServeOptions): Promise<void>;
+  /**
+   * Static preview of the built `dist/` with CF-Pages clean-URL resolution. No
+   * reload injection (mirrors production). Resolves on SIGINT/SIGTERM.
+   *
+   * @param options - Optional port override.
+   * @returns Resolves once the server has been torn down.
+   * @example
+   * await app.cli.preview();
+   */
+  preview(options?: PreviewOptions): Promise<void>;
+  /**
+   * Scaffold, then deploy. A y/N confirm is shown only on an interactive TTY;
+   * non-interactive runs (CI, or any non-TTY) skip the prompt and deploy, so the
+   * consumer scripts never block a pipeline. `options.yes` forces the skip anywhere.
+   *
+   * @param options - Optional branch override and `yes` flag.
+   * @returns The deploy outcome (completed details, or `declined` if a TTY user says no).
+   * @example
+   * await app.cli.deploy({ branch: "preview/x", yes: true });
+   */
+  deploy(options?: DeployOptions): Promise<DeployOutcome>;
+};
+//#endregion
+//#region src/plugins/cli/index.d.ts
+/**
+ * cli plugin — the node-only developer CLI for `@moku-labs/web`. Mounts exactly four
+ * methods at `app.cli` (`build`/`serve`/`preview`/`deploy`), each rendering through
+ * the boxed Panel UI. Live build/deploy progress rides on hooks over the `build` and
+ * `deploy` plugins' events; there is no argv parser and no `run()` dispatcher — the
+ * consumer drives it from one thin script per command.
+ *
+ * @example Compose the CLI in a consumer app (node-only)
+ * ```ts
+ * import { buildPlugin, cliPlugin, createApp, deployPlugin } from "@moku-labs/web";
+ *
+ * const app = createApp({
+ *   plugins: [buildPlugin, deployPlugin, cliPlugin],
+ *   pluginConfigs: { cli: { outDir: "dist", port: 4173, watchDirs: ["content", "src"] } }
+ * });
+ * await app.start();
+ * await app.cli.build();
+ * ```
+ */
+declare const cliPlugin: import("@moku-labs/core").PluginInstance<"cli", Config$1, State$1, Api$1, {}> & Record<never, never>;
+declare namespace types_d_exports$2 {
+  export { Api, Article, ArticleCard, ComputedFields, Config, ContentApiContext, ContentEvents, Frontmatter, State };
+}
+/**
+ * Configuration for the content plugin.
+ *
+ * @example
+ * ```ts
+ * { contentDir: "./src/content", trustedContent: false, shikiTheme: "github-dark" }
+ * ```
+ */
+type Config = {
+  /** Absolute or project-relative path to the content directory. Validated in onInit. */contentDir: string;
+  /**
+   * SECURITY GATE. When false (the default), rehype-sanitize runs as the final
+   * pipeline step. Set true ONLY for fully author-controlled Markdown — true
+   * disables sanitize and trusts all raw HTML.
+   */
+  trustedContent: boolean; /** Additional remark plugins, concatenated AFTER framework defaults. Defaults to []. */
+  extraRemarkPlugins?: readonly Pluggable[]; /** Additional rehype plugins, concatenated after custom transforms, before Shiki + sanitize. Defaults to []. */
+  extraRehypePlugins?: readonly Pluggable[];
+  /**
+   * Shiki theme for syntax highlighting: a bundled theme NAME — typed as Shiki's
+   * `BundledTheme` union so editors autocomplete the ~60 built-ins (default
+   * "github-dark") — or a custom `ThemeRegistration` object. Passed straight through
+   * to `@shikijs/rehype`'s `theme`. (Like Shiki's own theme type, an arbitrary string
+   * still compiles via the object arm, so this is autocomplete, not typo-rejection.)
+   */
+  shikiTheme?: BundledTheme | ThemeRegistrationAny; /** Author applied to articles whose frontmatter omits author. Defaults to undefined. */
+  defaultAuthor?: string;
+};
+/**
+ * Internal mutable state for the content plugin.
+ *
+ * @example
+ * ```ts
+ * { processor: null, articles: new Map(), slugs: null, dirtyPaths: new Set() }
+ * ```
+ */
+type State = {
+  /** Lazily-created unified processor singleton. null until first render()/loadAll(). */processor: Processor | null; /** Article cache keyed locale -> (slug -> Article). Starts empty. */
+  articles: Map<string, Map<string, Article>>; /** Discovered, sorted slug list cached after first disk scan. null until first discovery. */
+  slugs: string[] | null; /** Paths marked stale by invalidate(); next loadAll() re-reads only these. Starts empty. */
+  dirtyPaths: Set<string>;
+};
+/**
+ * YAML frontmatter parsed from each article file.
+ *
+ * @example
+ * ```ts
+ * { title: "Hello", date: "2026-01-15", description: "Intro", tags: [], language: "en" }
+ * ```
+ */
+type Frontmatter = {
+  /** Article title. Required. */title: string; /** ISO 8601 date string, e.g. "2026-01-15". Required. */
+  date: string; /** Short summary used in cards, feeds, and meta description. Required. */
+  description: string; /** Topic tags. Required (may be empty array). */
+  tags: string[]; /** Source language code of this file. Required. */
+  language: string; /** Draft flag. Excluded from output in production mode. Defaults to false. */
+  draft?: boolean; /** Author name. Falls back to config.defaultAuthor when omitted. */
+  author?: string;
+};
+/**
+ * Fields computed by the pipeline (not authored in frontmatter).
+ *
+ * @example
+ * ```ts
+ * { slug: "hello", readingTime: 1, contentId: "hello", status: "published", wordCount: 42 }
+ * ```
+ */
+type ComputedFields = {
+  /** Article directory name. */slug: string; /** Reading time in minutes (ceiling, minimum 1). */
+  readingTime: number; /** Stable content identifier (slug by default). */
+  contentId: string; /** Derived publication status. */
+  status: "published" | "draft"; /** Word count from the source body. */
+  wordCount: number;
+};
+/**
+ * A fully processed, render-ready article.
+ *
+ * @example
+ * ```ts
+ * { frontmatter, computed, html: "<p>…</p>", locale: "en", isFallback: false, url: "/en/hello/" }
+ * ```
+ */
+type Article = {
+  /** Parsed frontmatter. */frontmatter: Frontmatter; /** Pipeline-computed metadata. */
+  computed: ComputedFields; /** Sanitized rendered HTML body. */
+  html: string; /** Locale this Article instance represents (the requested locale, even on fallback). */
+  locale: string; /** True when the default-locale file was used because the requested locale was missing. */
+  isFallback: boolean; /** Canonical URL for this article in this locale. */
+  url: string;
+};
+/**
+ * Lightweight projection of Article for cards/lists.
+ *
+ * @example
+ * ```ts
+ * { contentId: "hello", status: "published", title: "Hello", date: "2026-01-15", description: "Intro", tags: [], readingTime: 1, url: "/en/hello/" }
+ * ```
+ */
+type ArticleCard = {
+  /** Stable content identifier. */contentId: string; /** Derived publication status. */
+  status: "published" | "draft"; /** Article title. */
+  title: string; /** ISO 8601 date string. */
+  date: string; /** Short summary. */
+  description: string; /** Topic tags. */
+  tags: string[]; /** Reading time in minutes. */
+  readingTime: number; /** Canonical URL for this article in this locale. */
+  url: string;
+};
+/**
+ * Notification-only events emitted by the content plugin.
+ *
+ * @example
+ * ```ts
+ * emit("content:ready", { locales: ["en"], articleCount: 3 });
+ * ```
+ */
+type ContentEvents = {
+  /** All articles loaded across locales. */"content:ready": {
+    locales: readonly string[];
+    articleCount: number;
+  }; /** Article paths marked stale for dev rebuild. */
+  "content:invalidated": {
+    paths: readonly string[];
+  };
+};
+/**
+ * Kernel-free domain context handed to createContentApi by the wiring harness.
+ * Carries ctx.state (mutable escape hatch), config, global, emit, and the
+ * i18n-derived locale/url helpers — so api.ts stays free of createPlugin/ctx.
+ *
+ * @example
+ * ```ts
+ * const apiContext: ContentApiContext = { state, config, global, emit, locales, defaultLocale, articleToUrl };
+ * ```
+ */
+type ContentApiContext = {
+  /** Mutable plugin state (article cache + lazy processor). */state: State; /** Resolved plugin configuration. */
+  config: Config; /** 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 = {
+  /**
+   * 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;
+  /**
+   * The configured content source directory (e.g. `"./content"`). Lets the build copy each
+   * article's co-located assets (`<contentDir>/<slug>/images/`) into the output so the absolute
+   * image URLs the renderer emits resolve.
+   */
+  contentDir(): string;
+};
+//#endregion
+//#region src/plugins/content/index.d.ts
+/**
+ * Content plugin — Markdown pipeline: discovers files, parses frontmatter, renders
+ * to sanitized HTML (rehype-sanitize unless `trustedContent`), and exposes a
+ * locale-keyed Article model. Depends on i18n; emits `content:ready` and
+ * `content:invalidated`.
+ *
+ * @example Point at a content directory and pick a Shiki theme
+ * ```ts
+ * const app = createApp({
+ *   pluginConfigs: {
+ *     content: {
+ *       contentDir: "./content",
+ *       shikiTheme: "github-dark",
+ *       defaultAuthor: "Ada Lovelace"
+ *       // trustedContent: true // ONLY for fully author-controlled Markdown — disables sanitize
+ *     }
+ *   }
+ * });
+ * ```
  */
-declare const contentPlugin: import("@moku-labs/core").PluginInstance<"content", Config$1, State$1, Api$1, {
+declare const contentPlugin: import("@moku-labs/core").PluginInstance<"content", Config, State, Api, {
   "content:ready": {
     locales: readonly string[];
     articleCount: number;
@@ -1881,7 +2482,7 @@ declare const contentPlugin: import("@moku-labs/core").PluginInstance<"content",
     paths: readonly string[];
   };
 }> & Record<never, never>;
-declare namespace types_d_exports$2 {
+declare namespace types_d_exports$3 {
   export { DataConfig, DataEntry, DataProvider, DataState, DataWriteSummary };
 }
 /**
@@ -2027,185 +2628,6 @@ type DataProvider = {
  * ```
  */
 declare const dataPlugin: import("@moku-labs/core").PluginInstance<"data", DataConfig, DataState, DataProvider, {}> & Record<never, never>;
-declare namespace types_d_exports$3 {
-  export { Api, Config, DeployErrorCode, DeployInitOptions, DeployResult, DeployRunOptions, InitResult, SpawnFunction, SpawnOptions, SpawnedProcess, State, WranglerErrorKind };
-}
-/**
- * @file deploy plugin — type definitions.
- */
-/**
- * Options passed to the injected spawner — the subset of Bun.spawn's options the
- * plugin uses (piped stdout/stderr plus an env carrying the API token).
- */
-interface SpawnOptions {
-  /** Capture stdout as a readable stream. */
-  readonly stdout: "pipe";
-  /** Capture stderr as a readable stream. */
-  readonly stderr: "pipe";
-  /** Subprocess environment — the API token is injected here, never via argv. */
-  readonly env?: Record<string, string | undefined>;
-}
-/**
- * The structural subprocess handle the plugin reads back: stdout/stderr streams
- * plus the exit-code promise. Streams are typed `unknown` and narrowed at the read
- * site so this carries no Bun namespace types.
- */
-interface SpawnedProcess {
-  /** Standard output stream (narrowed to a ReadableStream at the read site). */
-  readonly stdout: unknown;
-  /** Standard error stream (narrowed to a ReadableStream at the read site). */
-  readonly stderr: unknown;
-  /** Resolves with the subprocess exit code. */
-  readonly exited: Promise<number>;
-}
-/**
- * The subset of Bun.spawn's signature the plugin relies on (argv array + options).
- * Declared structurally — with NO `import("bun")` namespace types — so it survives
- * `.d.ts` bundling intact and tests can supply a fake spawn without importing Bun.
- */
-type SpawnFunction = (cmd: string[], options: SpawnOptions) => SpawnedProcess;
-/**
- * A deploy error `code` from the wrangler error taxonomy and preflight validators.
- */
-type DeployErrorCode = "ERR_DEPLOY_NO_WRANGLER_CONFIG" | "ERR_DEPLOY_EMPTY_OUTDIR" | "ERR_DEPLOY_TOO_MANY_FILES" | "ERR_DEPLOY_FILE_TOO_LARGE" | "ERR_DEPLOY_PATH_TRAVERSAL" | "ERR_DEPLOY_INVALID_BRANCH" | "ERR_DEPLOY_NO_TOKEN" | "ERR_DEPLOY_PROJECT_NOT_FOUND" | "ERR_DEPLOY_AUTH_EXPIRED" | "ERR_DEPLOY_AUTH" | "ERR_DEPLOY_NETWORK" | "ERR_DEPLOY_WRANGLER_FAILED" | "ERR_DEPLOY_CONFIG";
-/**
- * The subset of wrangler error `code`s classifyWranglerError can produce from a
- * non-zero wrangler exit.
- */
-type WranglerErrorKind = Extract<DeployErrorCode, "ERR_DEPLOY_PROJECT_NOT_FOUND" | "ERR_DEPLOY_AUTH_EXPIRED" | "ERR_DEPLOY_AUTH" | "ERR_DEPLOY_NETWORK" | "ERR_DEPLOY_WRANGLER_FAILED">;
-/**
- * Configuration for the deploy plugin.
- */
-type Config = {
-  /**
-   * Deploy target. Only Cloudflare Pages is supported in this version.
-   * Defaults to `cloudflare-pages`.
-   */
-  target: "cloudflare-pages";
-  /**
-   * Directory (relative to project root) containing the built site to deploy.
-   * Re-validated against cwd at run() time to block path traversal.
-   * Defaults to `dist`.
-   */
-  outDir: string;
-  /**
-   * Branch treated as the Cloudflare Pages production branch.
-   * Defaults to `main`.
-   */
-  productionBranch?: string;
-  /**
-   * Substrings exempt from entropy-gated secret scrubbing in logged output.
-   * Defaults to `["CLOUDFLARE_ACCOUNT_ID"]`.
-   */
-  scrubAllowlist: string[];
-  /**
-   * Cloudflare compatibility date written into generated wrangler.jsonc.
-   * Defaults to `2024-01-01`.
-   */
-  compatibilityDate?: string;
-  /**
-   * Whether init() also generates a GitHub Actions workflow.
-   * Defaults to `false`.
-   */
-  ci?: boolean;
-};
-/**
- * Result of a successful deploy.
- */
-type DeployResult = {
-  /** The public deployment URL (e.g. https://my-site.pages.dev). */url: string; /** Cloudflare deployment ID parsed from wrangler output. */
-  deploymentId: string; /** The branch that was deployed. */
-  branch: string; /** Wall-clock duration of the deploy in milliseconds. */
-  durationMs: number;
-};
-/**
- * Runtime state for the deploy plugin. Created in createState() and accessed via
- * ctx.state. deploy declares no onStop because nothing here is a long-lived resource.
- */
-type State = {
-  /** Result of the most recent successful deploy, or null before the first run. */lastDeployment: DeployResult | null;
-  /**
-   * Injectable subprocess spawner. Defaults to Bun.spawn. Swapped for a mock in
-   * unit tests so wrangler is never actually invoked. Never reassigned at runtime.
-   */
-  spawn: SpawnFunction;
-};
-/**
- * Options for DeployApi.run.
- */
-type DeployRunOptions = {
-  /**
-   * Branch to deploy. Defaults to config.productionBranch (or "main"). Must match
-   * /^[a-zA-Z0-9/_.-]+$/ — otherwise rejected with ERR_DEPLOY_INVALID_BRANCH.
-   */
-  branch?: string;
-  /**
-   * Whether to run the build before deploying. When false, deploys the existing outDir.
-   * Defaults to `true`.
-   */
-  build?: boolean;
-};
-/**
- * Options for DeployApi.init.
- */
-type DeployInitOptions = {
-  /** Also generate the GitHub Actions workflow. Defaults to config.ci. */ci?: boolean; /** Drift-only mode: report differences without writing any files. Defaults to `false`. */
-  check?: boolean;
-};
-/**
- * Result of an init/scaffold operation.
- */
-type InitResult = {
-  /** Paths written this invocation. */written: string[]; /** Paths skipped because they already exist. */
-  skipped: string[]; /** In check mode: paths whose on-disk content differs from what would be generated. */
-  drifted: string[];
-};
-/**
- * Public API of the deploy plugin (returned from the api factory).
- */
-type Api = {
-  /**
-   * Deploy the built outDir to Cloudflare Pages via the wrangler subprocess.
-   * Runs preflight validators, re-validates the resolved outdir against cwd, guards
-   * the branch argument, spawns wrangler (no shell), scrubs all subprocess output
-   * before logging, records lastDeployment, and emits deploy:complete.
-   *
-   * @param options - Optional branch override and build toggle.
-   * @returns The deploy result (url, deploymentId, branch, durationMs).
-   * @throws {Error} With a `code` from the deploy error taxonomy on any failure.
-   * @example
-   * const result = await app.deploy.run();
-   * console.log(result.url); // https://my-site.pages.dev
-   * @example
-   * await app.deploy.run({ branch: "preview/landing", build: false });
-   */
-  run(options?: DeployRunOptions): Promise<DeployResult>;
-  /**
-   * Return the most recent successful deploy result, or null if none has occurred.
-   * The returned object is read-only (a defensive snapshot).
-   *
-   * @returns The last DeployResult, or null.
-   * @example
-   * const last = app.deploy.getLastDeployment();
-   * if (last) console.log(`Last deployed to ${last.url}`);
-   */
-  getLastDeployment(): Readonly<DeployResult> | null;
-  /**
-   * Generate deploy scaffolding: wrangler.jsonc (slug from site.name() + outDir +
-   * compatibilityDate) and, when ci is enabled, .github/workflows/deploy.yml. Never
-   * overwrites an existing wrangler.jsonc. In check mode, reports drift instead of writing.
-   *
-   * @param options - Optional ci toggle and check (drift-only) mode.
-   * @returns Which files were written, skipped, or would drift.
-   * @example
-   * const out = await app.deploy.init({ ci: true });
-   * // out.written -> ["wrangler.jsonc", ".github/workflows/deploy.yml"]
-   * @example
-   * const drift = await app.deploy.init({ check: true });
-   * if (drift.drifted.length) process.exit(1);
-   */
-  init(options?: DeployInitOptions): Promise<InitResult>;
-};
 //#endregion
 //#region src/plugins/deploy/index.d.ts
 /**
@@ -2233,7 +2655,7 @@ type Api = {
  * });
  * ```
  */
-declare const deployPlugin: import("@moku-labs/core").PluginInstance<"deploy", Config, State, Api, {
+declare const deployPlugin: import("@moku-labs/core").PluginInstance<"deploy", Config$2, State$2, Api$2, {
   "deploy:complete": {
     url: string;
     deploymentId: string;
@@ -2340,7 +2762,7 @@ declare function buildArticleHead(articleMeta: ArticleMeta, canonicalUrl: string
  * });
  * ```
  */
-declare const headPlugin: import("@moku-labs/core").PluginInstance<"head", Config$3, State$3, Api$3, {}> & {
+declare const headPlugin: import("@moku-labs/core").PluginInstance<"head", Config$4, State$4, Api$4, {}> & {
   meta: typeof meta;
   og: typeof og;
   twitter: typeof twitter;
@@ -2371,7 +2793,7 @@ declare const headPlugin: import("@moku-labs/core").PluginInstance<"head", Confi
  * });
  * ```
  */
-declare const i18nPlugin: import("@moku-labs/core").PluginInstance<"i18n", Config$5, Record<string, never>, Api$5, {}> & Record<never, never>;
+declare const i18nPlugin: import("@moku-labs/core").PluginInstance<"i18n", Config$6, Record<string, never>, Api$6, {}> & Record<never, never>;
 //#endregion
 //#region src/plugins/log/index.d.ts
 /**
@@ -2461,7 +2883,7 @@ declare const routerPlugin: import("@moku-labs/core").PluginInstance<"router", R
  * });
  * ```
  */
-declare const sitePlugin: import("@moku-labs/core").PluginInstance<"site", Config$6, Record<string, never>, Api$6, {}> & Record<never, never>;
+declare const sitePlugin: import("@moku-labs/core").PluginInstance<"site", Config$7, Record<string, never>, Api$7, {}> & Record<never, never>;
 //#endregion
 //#region src/plugins/spa/components.d.ts
 /**
@@ -2592,10 +3014,10 @@ declare function cloudflareBindings(): EnvProvider;
  * await app.build.run();
  * ```
  */
-declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs/core").AnyPluginInstance[] = readonly []>(options?: import("@moku-labs/core").CreateAppOptions<Config$7, Events, (import("@moku-labs/core").PluginInstance<"site", Config$6, Record<string, never>, Api$6, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"i18n", Config$5, Record<string, never>, Api$5, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"router", RouterConfig, RouterState, RouterApi, {}> & {
+declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs/core").AnyPluginInstance[] = readonly []>(options?: import("@moku-labs/core").CreateAppOptions<Config$8, Events, (import("@moku-labs/core").PluginInstance<"site", Config$7, Record<string, never>, Api$7, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"i18n", Config$6, Record<string, never>, Api$6, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"router", RouterConfig, RouterState, RouterApi, {}> & {
   route: typeof route;
   defineRoutes: typeof defineRoutes;
-}) | (import("@moku-labs/core").PluginInstance<"head", Config$3, State$3, Api$3, {}> & {
+}) | (import("@moku-labs/core").PluginInstance<"head", Config$4, State$4, Api$4, {}> & {
   meta: typeof meta;
   og: typeof og;
   twitter: typeof twitter;
@@ -2620,10 +3042,10 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
     name: string;
     el: Element;
   };
-}> & Record<never, never>) | ExtraPlugins[number], [...ExtraPlugins], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", LogConfig, LogState, LogApi>, import("@moku-labs/core").CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>]>> | undefined) => import("@moku-labs/core").App<Config$7, Events, (import("@moku-labs/core").PluginInstance<"site", Config$6, Record<string, never>, Api$6, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"i18n", Config$5, Record<string, never>, Api$5, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"router", RouterConfig, RouterState, RouterApi, {}> & {
+}> & Record<never, never>) | ExtraPlugins[number], [...ExtraPlugins], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", LogConfig, LogState, LogApi>, import("@moku-labs/core").CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>]>> | undefined) => import("@moku-labs/core").App<Config$8, Events, (import("@moku-labs/core").PluginInstance<"site", Config$7, Record<string, never>, Api$7, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"i18n", Config$6, Record<string, never>, Api$6, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"router", RouterConfig, RouterState, RouterApi, {}> & {
   route: typeof route;
   defineRoutes: typeof defineRoutes;
-}) | (import("@moku-labs/core").PluginInstance<"head", Config$3, State$3, Api$3, {}> & {
+}) | (import("@moku-labs/core").PluginInstance<"head", Config$4, State$4, Api$4, {}> & {
   meta: typeof meta;
   og: typeof og;
   twitter: typeof twitter;
@@ -2664,6 +3086,6 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
  * const app = createApp({ plugins: [analytics] });
  * ```
  */
-declare const createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<Config$7, Events, import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", LogConfig, LogState, LogApi>, import("@moku-labs/core").CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>]>>;
+declare const createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<Config$8, Events, import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", LogConfig, LogState, LogApi>, import("@moku-labs/core").CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>]>>;
 //#endregion
-export { types_d_exports as Build, types_d_exports$1 as Content, types_d_exports$2 as Data, types_d_exports$3 as Deploy, types_d_exports$4 as Env, types_d_exports$5 as Head, types_d_exports$6 as Log, types_d_exports$7 as Router, types_d_exports$8 as Spa, browserEnv, buildArticleHead, buildPlugin, canonical, cloudflareBindings, contentPlugin, createApp, createComponent, createPlugin, dataPlugin, defineRoutes, deployPlugin, dotenv, envPlugin, feedLink, headPlugin, hreflang, i18nPlugin, jsonLd, logPlugin, meta, og, processEnv, route, routerPlugin, sitePlugin, spaPlugin, twitter };
+export { types_d_exports as Build, types_d_exports$1 as Cli, types_d_exports$2 as Content, types_d_exports$3 as Data, types_d_exports$4 as Deploy, types_d_exports$5 as Env, types_d_exports$6 as Head, types_d_exports$7 as Log, types_d_exports$8 as Router, types_d_exports$9 as Spa, browserEnv, buildArticleHead, buildPlugin, canonical, cliPlugin, cloudflareBindings, contentPlugin, createApp, createComponent, createPlugin, dataPlugin, defineRoutes, deployPlugin, dotenv, envPlugin, feedLink, headPlugin, hreflang, i18nPlugin, jsonLd, logPlugin, meta, og, processEnv, route, routerPlugin, sitePlugin, spaPlugin, twitter };