@moku-labs/web 1.1.0 → 1.3.0

package/dist/index.d.cts

@@ -1421,7 +1421,7 @@ type SpaApi = {
   current(): string;
 };
 declare namespace types_d_exports {
-  export { Api$3 as Api, BuildCacheEntry, BuildEvents, BuildResult, Config$3 as Config, ExtractApi, OgFont, OgImageConfig, PhaseContext, PhaseEmit, PhaseLog, PhaseName, PhaseRequire, RichOgInput, State$3 as State };
+  export { Api$3 as Api, BuildCacheEntry, BuildEvents, BuildResult, BuildRunOverrides, Config$3 as Config, ExtractApi, OgFont, OgImageConfig, PhaseContext, PhaseEmit, PhaseLog, PhaseName, PhaseRequire, RenderCacheEntry, RichOgInput, RunOptions, State$3 as State };
 }
 /**
  * Structural extraction of a plugin instance's public API from its `_phantom`
@@ -1629,6 +1629,20 @@ type Config$3 = {
  * ```
  */
 type BuildCacheEntry = Record<string, string>;
+/**
+ * One cached page render: the SSR body HTML keyed by a hash of the inputs that determine
+ * it (the route's loaded data). Lets a dev incremental rebuild skip the synchronous,
+ * dominant-cost `preact-render-to-string` for a page whose data is unchanged.
+ *
+ * @example
+ * ```ts
+ * const entry: RenderCacheEntry = { dataHash: "9f8e…", body: "<h1>Hi</h1>" };
+ * ```
+ */
+type RenderCacheEntry = {
+  /** Hash of the page's render inputs (its loaded data). */dataHash: string; /** The SSR-rendered body HTML for those inputs. */
+  body: string;
+};
 /**
  * Per-run closure state for the `build` plugin. Holds caches and config only —
  * no domain data is duplicated here (pulled fresh via `ctx.require` each run).
@@ -1653,6 +1667,13 @@ interface State$3 {
    * so unchanged articles are skipped on the next run.
    */
   ogImageHashCache: Map<string, string>;
+  /**
+   * Cross-run page-render cache: `name\0params\0locale` -> {@link RenderCacheEntry}.
+   * Persists across dev rebuilds (never reset by a run) so an incremental rebuild reuses
+   * the body of any page whose data is unchanged. Empty for a fresh process; cleared by a
+   * full (non-incremental) render so stale entries for removed routes never linger.
+   */
+  renderCache: Map<string, RenderCacheEntry>;
 }
 /**
  * Ordered names of the build pipeline phases, in execution order.
@@ -1679,6 +1700,51 @@ interface BuildResult {
   /** Total wall-clock duration of the run, in milliseconds. */
   durationMs: number;
 }
+/**
+ * Per-run {@link Config} field overrides for a single {@link Api.run} call. Lets a dev
+ * rebuild disable expensive, preview-irrelevant outputs (feeds / sitemap / og-images /
+ * locale-redirects) and minification WITHOUT mutating the persisted plugin config. Each
+ * key maps to the same-named {@link Config} flag and is merged over the config snapshot
+ * for that one run only.
+ *
+ * @example
+ * ```ts
+ * const dev: BuildRunOverrides = { minify: false, feeds: false, sitemap: false };
+ * ```
+ */
+type BuildRunOverrides = Readonly<Partial<Pick<Config$3, "minify" | "feeds" | "sitemap" | "ogImage" | "images" | "localeRedirects" | "notFound">>>;
+/**
+ * Options for a single {@link Api.run} call. All fields are optional; an absent/empty
+ * options object runs the full production build (clean + every configured phase). The
+ * dev server (`serve()`) passes `skipClean`/`overrides`/`changed` to make a rebuild
+ * fast without touching the production path.
+ *
+ * @example
+ * ```ts
+ * await app.build.run({ skipClean: true, overrides: { minify: false }, changed: ["/abs/content/intro/en.md"] });
+ * ```
+ */
+type RunOptions = {
+  /** Override the configured output directory for this run. */outDir?: string;
+  /**
+   * Skip the destructive clean (`rm -rf outDir`) so caches + unchanged assets survive a dev
+   * rebuild. TRADE-OFF: because nothing is pruned, output for a route DELETED or renamed
+   * since the last build lingers on disk (and is still served by the dev server) until the
+   * next full/clean build — restart `serve` or run a production `build` to clear it.
+   */
+  skipClean?: boolean; /** Per-run {@link Config} field overrides merged over the snapshot (e.g. disable feeds/sitemap/minify in dev). */
+  overrides?: BuildRunOverrides;
+  /**
+   * Paths changed since the last build (dev incremental rebuild). When present, the pipeline
+   * re-reads only changed Markdown and re-renders only pages whose loaded data changed; omit
+   * it for a full build (initial build + every production build). CORRECTNESS NOTE: render
+   * reuse is sound only when a route's render/layout output is a pure function of its
+   * `.load()` data (+ params/locale/code) — a route whose `.render()` reads module-global or
+   * other out-of-band state can show a stale body on a content-only rebuild until the next
+   * code change or restart. Production builds omit `changed`, so they are never affected.
+   */
+  changed?: readonly string[];
+};
 /**
  * Public API surface mounted on `app.build`.
  *
@@ -1689,19 +1755,18 @@ interface BuildResult {
  */
 type Api$3 = {
   /**
-   * Run the full SSG pipeline and write the site to disk.
+   * Run the full SSG pipeline and write the site to disk. With no options a full
+   * production build runs (clean + every configured phase); dev callers pass
+   * {@link RunOptions} (`skipClean`/`overrides`/`changed`) for a fast incremental rebuild.
    *
-   * @param options - Optional run overrides.
-   * @param options.outDir - Override the configured output directory for this run.
+   * @param options - Optional per-run overrides ({@link RunOptions}).
    * @returns The build result (outDir, pageCount, durationMs).
    * @example
    * ```ts
    * const result = await app.build.run({ outDir: "./preview" });
    * ```
    */
-  run(options?: {
-    outDir?: string;
-  }): Promise<BuildResult>;
+  run(options?: RunOptions): Promise<BuildResult>;
   /**
    * List the phases in execution order (introspection / tooling).
    *
@@ -1761,7 +1826,7 @@ declare const buildPlugin: import("@moku-labs/core").PluginInstance<"build", Con
  */
 type WorkflowTrigger = "auto" | "versioned-tag" | "dispatch";
 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, WorkflowTrigger, WranglerErrorKind };
+  export { Api$2 as Api, Config$2 as Config, CreateProjectResult, DeployErrorCode, DeployInitOptions, DeployResult, DeployRunOptions, InitResult, SpawnFunction, SpawnOptions, SpawnedProcess, State$2 as State, WorkflowTrigger, WranglerErrorKind };
 }
 /**
  * Options passed to the injected spawner — the subset of Bun.spawn's options the
@@ -1890,6 +1955,13 @@ type InitResult = {
   skipped: string[]; /** In check mode: paths whose on-disk content differs from what would be generated. */
   drifted: string[];
 };
+/**
+ * Result of creating the remote Cloudflare Pages project.
+ */
+type CreateProjectResult = {
+  /** The created project name (the `toSlug(site.name())` slug). */name: string; /** The production branch the project was created with. */
+  branch: string;
+};
 /**
  * Public API of the deploy plugin (returned from the api factory).
  */
@@ -1935,6 +2007,28 @@ type Api$2 = {
    * if (drift.drifted.length) process.exit(1);
    */
   init(options?: DeployInitOptions): Promise<InitResult>;
+  /**
+   * The Cloudflare Pages project name this app deploys to — `toSlug(site.name())`, the
+   * same slug `run()` passes as `--project-name` and `createProject()` creates. Lets a
+   * caller (e.g. the guided deploy wizard) name the project before it exists.
+   *
+   * @returns The project-name slug.
+   * @example
+   * app.deploy.projectName(); // "my-site"
+   */
+  projectName(): string;
+  /**
+   * Create the remote Cloudflare Pages project (`wrangler pages project create`) so a
+   * first deploy has a target. The slug is derived from `site.name()` and the production
+   * branch from `config.productionBranch` (or `"main"`). Wrangler errors if the project
+   * already exists; the guided wizard calls this only after a project-not-found failure.
+   *
+   * @returns The created project name + production branch.
+   * @throws {Error} With a `code` from the deploy error taxonomy on a non-zero exit.
+   * @example
+   * const created = await app.deploy.createProject(); // { name: "my-site", branch: "main" }
+   */
+  createProject(): Promise<CreateProjectResult>;
 };
 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 };
@@ -2109,6 +2203,17 @@ type CliRenderer = {
    * render.check(false, "CLOUDFLARE_API_TOKEN is set", "Create one at …");
    */
   check(ok: boolean, label: string, detail?: string): void;
+  /**
+   * Stop any running animation (the live `serve()` idle pulse, a phase/rebuild spinner)
+   * and release the renderer's interval timer. Called by `serve()`'s SIGINT/SIGTERM
+   * teardown so the persistent idle-pulse ticker never outlives the dev server. A no-op
+   * when nothing is animating; safe to call more than once.
+   *
+   * @returns Nothing.
+   * @example
+   * render.dispose();
+   */
+  dispose(): void;
 };
 /**
  * A live directory watcher handle returned by the injectable `watch` seam. Closing
@@ -2284,6 +2389,18 @@ type State$1 = {
    * const mtime = state.fileMtime("/abs/content/a.md");
    */
   fileMtime: (path: string) => number | null;
+  /**
+   * Resolve a file's content hash, or `null` when it does not exist. serve()'s change gate
+   * uses it to drop a no-op save whose bytes are identical to the last successful build (the
+   * double Ctrl-S habit). Default reads the file + hashes it (`node:fs` + `node:crypto`);
+   * tests inject deterministic values.
+   *
+   * @param path - The absolute path to hash.
+   * @returns The content hash, or `null` when the file is missing.
+   * @example
+   * const hash = state.fileHash("/abs/content/a.md");
+   */
+  fileHash: (path: string) => string | null;
 };
 /**
  * Summary returned by `cli.build()` — the awaited `build.run()` result.
@@ -2299,9 +2416,11 @@ type BuildSummary = {
 /**
  * Outcome returned by `cli.deploy()` — either a completed deploy (with details) or a
  * skipped one. A skip is `"declined"` when a user answers "no" at the confirm prompt,
- * or `"blocked"` when the guided wizard found unmet prerequisites and stopped before
- * deploying. Non-interactive direct runs (CI / non-TTY) never prompt and always proceed,
- * so they never skip — the scripts are CI-safe.
+ * `"blocked"` when the guided wizard found unmet prerequisites and stopped before
+ * deploying, or `"failed"` when the deploy itself errored (e.g. the Pages project does
+ * not exist) and the wizard surfaced it as a styled error + fix hint instead of a raw
+ * throw. Non-interactive direct runs (CI / non-TTY) never prompt and always proceed, so
+ * they never `declined`-skip — the scripts are CI-safe.
  *
  * @example
  * const outcome: DeployOutcome = { deployed: false, reason: "declined" };
@@ -2314,7 +2433,7 @@ type DeployOutcome = {
   durationMs: number;
 } | {
   deployed: false;
-  reason: "declined" | "blocked";
+  reason: "declined" | "blocked" | "failed";
 };
 /**
  * Options for `cli.build()`.
@@ -2334,6 +2453,15 @@ type BuildOptions = {
 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;
+  /**
+   * Re-enable OG-image generation for this dev session. `serve()` disables expensive,
+   * preview-irrelevant outputs by default for a fast rebuild; a thin consumer script
+   * maps `--og` to this. Defaults to `false`.
+   */
+  og?: boolean; /** Re-enable `sitemap.xml` + `robots.txt` for this dev session (maps to `--sitemap`). Defaults to `false`. */
+  sitemap?: boolean; /** Re-enable RSS/Atom/JSON feeds for this dev session (maps to `--feeds`). Defaults to `false`. */
+  feeds?: boolean; /** Re-enable i18n locale-redirect pages for this dev session (maps to `--locale-redirects`). Defaults to `false`. */
+  localeRedirects?: boolean;
 };
 /**
  * Options for `cli.preview()`.
@@ -2433,7 +2561,7 @@ type Api$1 = {
  */
 declare const cliPlugin: import("@moku-labs/core").PluginInstance<"cli", Config$1, State$1, Api$1, {}> & Record<never, never>;
 declare namespace types_d_exports$2 {
-  export { Api, Article, ArticleCard, ComputedFields, Config, ContentApiContext, ContentEvents, ContentProvider, ContentProviderState, FileSystemContentOptions, Frontmatter, State };
+  export { Api, Article, ArticleCard, ComputedFields, Config, ContentApiContext, ContentEvents, ContentProvider, ContentProviderState, FileSystemContentOptions, Frontmatter, LoadAllOptions, State };
 }
 /**
  * YAML frontmatter parsed from each article file.
@@ -2652,6 +2780,24 @@ type ContentApiContext = {
   defaultLocale: () => string; /** The resolved content source (merged from `config.providers`). */
   provider: ContentProvider;
 };
+/**
+ * Options for {@link Api.loadAll}.
+ *
+ * @example
+ * ```ts
+ * await app.content.loadAll({ reuse: true });
+ * ```
+ */
+type LoadAllOptions = {
+  /**
+   * Reuse already-cached articles for slugs NOT dropped by a preceding `invalidate()`,
+   * re-reading + re-rendering (Shiki) ONLY the invalidated (dirty) articles. The
+   * post-sort `contentId` ordinals are always recomputed across the full set, so order +
+   * ids match a full load. Default `false` (a full load that re-reads every article).
+   * Used by dev incremental rebuilds; a fresh process / production build never reuses.
+   */
+  reuse?: boolean;
+};
 /**
  * Public API for the content plugin.
  *
@@ -2664,8 +2810,10 @@ type Api = {
   /**
    * Load every article across every active locale, returning a locale-keyed
    * map of date-descending Article arrays. Emits content:ready.
+   *
+   * @param options - Optional load behaviour ({@link LoadAllOptions}); omit for a full load.
    */
-  loadAll(): Promise<Map<string, Article[]>>;
+  loadAll(options?: LoadAllOptions): Promise<Map<string, Article[]>>;
   /**
    * Resolve and render a single article for one locale, with locale fallback.
    *

package/dist/index.d.mts

@@ -1421,7 +1421,7 @@ type SpaApi = {
   current(): string;
 };
 declare namespace types_d_exports {
-  export { Api$3 as Api, BuildCacheEntry, BuildEvents, BuildResult, Config$3 as Config, ExtractApi, OgFont, OgImageConfig, PhaseContext, PhaseEmit, PhaseLog, PhaseName, PhaseRequire, RichOgInput, State$3 as State };
+  export { Api$3 as Api, BuildCacheEntry, BuildEvents, BuildResult, BuildRunOverrides, Config$3 as Config, ExtractApi, OgFont, OgImageConfig, PhaseContext, PhaseEmit, PhaseLog, PhaseName, PhaseRequire, RenderCacheEntry, RichOgInput, RunOptions, State$3 as State };
 }
 /**
  * Structural extraction of a plugin instance's public API from its `_phantom`
@@ -1629,6 +1629,20 @@ type Config$3 = {
  * ```
  */
 type BuildCacheEntry = Record<string, string>;
+/**
+ * One cached page render: the SSR body HTML keyed by a hash of the inputs that determine
+ * it (the route's loaded data). Lets a dev incremental rebuild skip the synchronous,
+ * dominant-cost `preact-render-to-string` for a page whose data is unchanged.
+ *
+ * @example
+ * ```ts
+ * const entry: RenderCacheEntry = { dataHash: "9f8e…", body: "<h1>Hi</h1>" };
+ * ```
+ */
+type RenderCacheEntry = {
+  /** Hash of the page's render inputs (its loaded data). */dataHash: string; /** The SSR-rendered body HTML for those inputs. */
+  body: string;
+};
 /**
  * Per-run closure state for the `build` plugin. Holds caches and config only —
  * no domain data is duplicated here (pulled fresh via `ctx.require` each run).
@@ -1653,6 +1667,13 @@ interface State$3 {
    * so unchanged articles are skipped on the next run.
    */
   ogImageHashCache: Map<string, string>;
+  /**
+   * Cross-run page-render cache: `name\0params\0locale` -> {@link RenderCacheEntry}.
+   * Persists across dev rebuilds (never reset by a run) so an incremental rebuild reuses
+   * the body of any page whose data is unchanged. Empty for a fresh process; cleared by a
+   * full (non-incremental) render so stale entries for removed routes never linger.
+   */
+  renderCache: Map<string, RenderCacheEntry>;
 }
 /**
  * Ordered names of the build pipeline phases, in execution order.
@@ -1679,6 +1700,51 @@ interface BuildResult {
   /** Total wall-clock duration of the run, in milliseconds. */
   durationMs: number;
 }
+/**
+ * Per-run {@link Config} field overrides for a single {@link Api.run} call. Lets a dev
+ * rebuild disable expensive, preview-irrelevant outputs (feeds / sitemap / og-images /
+ * locale-redirects) and minification WITHOUT mutating the persisted plugin config. Each
+ * key maps to the same-named {@link Config} flag and is merged over the config snapshot
+ * for that one run only.
+ *
+ * @example
+ * ```ts
+ * const dev: BuildRunOverrides = { minify: false, feeds: false, sitemap: false };
+ * ```
+ */
+type BuildRunOverrides = Readonly<Partial<Pick<Config$3, "minify" | "feeds" | "sitemap" | "ogImage" | "images" | "localeRedirects" | "notFound">>>;
+/**
+ * Options for a single {@link Api.run} call. All fields are optional; an absent/empty
+ * options object runs the full production build (clean + every configured phase). The
+ * dev server (`serve()`) passes `skipClean`/`overrides`/`changed` to make a rebuild
+ * fast without touching the production path.
+ *
+ * @example
+ * ```ts
+ * await app.build.run({ skipClean: true, overrides: { minify: false }, changed: ["/abs/content/intro/en.md"] });
+ * ```
+ */
+type RunOptions = {
+  /** Override the configured output directory for this run. */outDir?: string;
+  /**
+   * Skip the destructive clean (`rm -rf outDir`) so caches + unchanged assets survive a dev
+   * rebuild. TRADE-OFF: because nothing is pruned, output for a route DELETED or renamed
+   * since the last build lingers on disk (and is still served by the dev server) until the
+   * next full/clean build — restart `serve` or run a production `build` to clear it.
+   */
+  skipClean?: boolean; /** Per-run {@link Config} field overrides merged over the snapshot (e.g. disable feeds/sitemap/minify in dev). */
+  overrides?: BuildRunOverrides;
+  /**
+   * Paths changed since the last build (dev incremental rebuild). When present, the pipeline
+   * re-reads only changed Markdown and re-renders only pages whose loaded data changed; omit
+   * it for a full build (initial build + every production build). CORRECTNESS NOTE: render
+   * reuse is sound only when a route's render/layout output is a pure function of its
+   * `.load()` data (+ params/locale/code) — a route whose `.render()` reads module-global or
+   * other out-of-band state can show a stale body on a content-only rebuild until the next
+   * code change or restart. Production builds omit `changed`, so they are never affected.
+   */
+  changed?: readonly string[];
+};
 /**
  * Public API surface mounted on `app.build`.
  *
@@ -1689,19 +1755,18 @@ interface BuildResult {
  */
 type Api$3 = {
   /**
-   * Run the full SSG pipeline and write the site to disk.
+   * Run the full SSG pipeline and write the site to disk. With no options a full
+   * production build runs (clean + every configured phase); dev callers pass
+   * {@link RunOptions} (`skipClean`/`overrides`/`changed`) for a fast incremental rebuild.
    *
-   * @param options - Optional run overrides.
-   * @param options.outDir - Override the configured output directory for this run.
+   * @param options - Optional per-run overrides ({@link RunOptions}).
    * @returns The build result (outDir, pageCount, durationMs).
    * @example
    * ```ts
    * const result = await app.build.run({ outDir: "./preview" });
    * ```
    */
-  run(options?: {
-    outDir?: string;
-  }): Promise<BuildResult>;
+  run(options?: RunOptions): Promise<BuildResult>;
   /**
    * List the phases in execution order (introspection / tooling).
    *
@@ -1761,7 +1826,7 @@ declare const buildPlugin: import("@moku-labs/core").PluginInstance<"build", Con
  */
 type WorkflowTrigger = "auto" | "versioned-tag" | "dispatch";
 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, WorkflowTrigger, WranglerErrorKind };
+  export { Api$2 as Api, Config$2 as Config, CreateProjectResult, DeployErrorCode, DeployInitOptions, DeployResult, DeployRunOptions, InitResult, SpawnFunction, SpawnOptions, SpawnedProcess, State$2 as State, WorkflowTrigger, WranglerErrorKind };
 }
 /**
  * Options passed to the injected spawner — the subset of Bun.spawn's options the
@@ -1890,6 +1955,13 @@ type InitResult = {
   skipped: string[]; /** In check mode: paths whose on-disk content differs from what would be generated. */
   drifted: string[];
 };
+/**
+ * Result of creating the remote Cloudflare Pages project.
+ */
+type CreateProjectResult = {
+  /** The created project name (the `toSlug(site.name())` slug). */name: string; /** The production branch the project was created with. */
+  branch: string;
+};
 /**
  * Public API of the deploy plugin (returned from the api factory).
  */
@@ -1935,6 +2007,28 @@ type Api$2 = {
    * if (drift.drifted.length) process.exit(1);
    */
   init(options?: DeployInitOptions): Promise<InitResult>;
+  /**
+   * The Cloudflare Pages project name this app deploys to — `toSlug(site.name())`, the
+   * same slug `run()` passes as `--project-name` and `createProject()` creates. Lets a
+   * caller (e.g. the guided deploy wizard) name the project before it exists.
+   *
+   * @returns The project-name slug.
+   * @example
+   * app.deploy.projectName(); // "my-site"
+   */
+  projectName(): string;
+  /**
+   * Create the remote Cloudflare Pages project (`wrangler pages project create`) so a
+   * first deploy has a target. The slug is derived from `site.name()` and the production
+   * branch from `config.productionBranch` (or `"main"`). Wrangler errors if the project
+   * already exists; the guided wizard calls this only after a project-not-found failure.
+   *
+   * @returns The created project name + production branch.
+   * @throws {Error} With a `code` from the deploy error taxonomy on a non-zero exit.
+   * @example
+   * const created = await app.deploy.createProject(); // { name: "my-site", branch: "main" }
+   */
+  createProject(): Promise<CreateProjectResult>;
 };
 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 };
@@ -2109,6 +2203,17 @@ type CliRenderer = {
    * render.check(false, "CLOUDFLARE_API_TOKEN is set", "Create one at …");
    */
   check(ok: boolean, label: string, detail?: string): void;
+  /**
+   * Stop any running animation (the live `serve()` idle pulse, a phase/rebuild spinner)
+   * and release the renderer's interval timer. Called by `serve()`'s SIGINT/SIGTERM
+   * teardown so the persistent idle-pulse ticker never outlives the dev server. A no-op
+   * when nothing is animating; safe to call more than once.
+   *
+   * @returns Nothing.
+   * @example
+   * render.dispose();
+   */
+  dispose(): void;
 };
 /**
  * A live directory watcher handle returned by the injectable `watch` seam. Closing
@@ -2284,6 +2389,18 @@ type State$1 = {
    * const mtime = state.fileMtime("/abs/content/a.md");
    */
   fileMtime: (path: string) => number | null;
+  /**
+   * Resolve a file's content hash, or `null` when it does not exist. serve()'s change gate
+   * uses it to drop a no-op save whose bytes are identical to the last successful build (the
+   * double Ctrl-S habit). Default reads the file + hashes it (`node:fs` + `node:crypto`);
+   * tests inject deterministic values.
+   *
+   * @param path - The absolute path to hash.
+   * @returns The content hash, or `null` when the file is missing.
+   * @example
+   * const hash = state.fileHash("/abs/content/a.md");
+   */
+  fileHash: (path: string) => string | null;
 };
 /**
  * Summary returned by `cli.build()` — the awaited `build.run()` result.
@@ -2299,9 +2416,11 @@ type BuildSummary = {
 /**
  * Outcome returned by `cli.deploy()` — either a completed deploy (with details) or a
  * skipped one. A skip is `"declined"` when a user answers "no" at the confirm prompt,
- * or `"blocked"` when the guided wizard found unmet prerequisites and stopped before
- * deploying. Non-interactive direct runs (CI / non-TTY) never prompt and always proceed,
- * so they never skip — the scripts are CI-safe.
+ * `"blocked"` when the guided wizard found unmet prerequisites and stopped before
+ * deploying, or `"failed"` when the deploy itself errored (e.g. the Pages project does
+ * not exist) and the wizard surfaced it as a styled error + fix hint instead of a raw
+ * throw. Non-interactive direct runs (CI / non-TTY) never prompt and always proceed, so
+ * they never `declined`-skip — the scripts are CI-safe.
  *
  * @example
  * const outcome: DeployOutcome = { deployed: false, reason: "declined" };
@@ -2314,7 +2433,7 @@ type DeployOutcome = {
   durationMs: number;
 } | {
   deployed: false;
-  reason: "declined" | "blocked";
+  reason: "declined" | "blocked" | "failed";
 };
 /**
  * Options for `cli.build()`.
@@ -2334,6 +2453,15 @@ type BuildOptions = {
 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;
+  /**
+   * Re-enable OG-image generation for this dev session. `serve()` disables expensive,
+   * preview-irrelevant outputs by default for a fast rebuild; a thin consumer script
+   * maps `--og` to this. Defaults to `false`.
+   */
+  og?: boolean; /** Re-enable `sitemap.xml` + `robots.txt` for this dev session (maps to `--sitemap`). Defaults to `false`. */
+  sitemap?: boolean; /** Re-enable RSS/Atom/JSON feeds for this dev session (maps to `--feeds`). Defaults to `false`. */
+  feeds?: boolean; /** Re-enable i18n locale-redirect pages for this dev session (maps to `--locale-redirects`). Defaults to `false`. */
+  localeRedirects?: boolean;
 };
 /**
  * Options for `cli.preview()`.
@@ -2433,7 +2561,7 @@ type Api$1 = {
  */
 declare const cliPlugin: import("@moku-labs/core").PluginInstance<"cli", Config$1, State$1, Api$1, {}> & Record<never, never>;
 declare namespace types_d_exports$2 {
-  export { Api, Article, ArticleCard, ComputedFields, Config, ContentApiContext, ContentEvents, ContentProvider, ContentProviderState, FileSystemContentOptions, Frontmatter, State };
+  export { Api, Article, ArticleCard, ComputedFields, Config, ContentApiContext, ContentEvents, ContentProvider, ContentProviderState, FileSystemContentOptions, Frontmatter, LoadAllOptions, State };
 }
 /**
  * YAML frontmatter parsed from each article file.
@@ -2652,6 +2780,24 @@ type ContentApiContext = {
   defaultLocale: () => string; /** The resolved content source (merged from `config.providers`). */
   provider: ContentProvider;
 };
+/**
+ * Options for {@link Api.loadAll}.
+ *
+ * @example
+ * ```ts
+ * await app.content.loadAll({ reuse: true });
+ * ```
+ */
+type LoadAllOptions = {
+  /**
+   * Reuse already-cached articles for slugs NOT dropped by a preceding `invalidate()`,
+   * re-reading + re-rendering (Shiki) ONLY the invalidated (dirty) articles. The
+   * post-sort `contentId` ordinals are always recomputed across the full set, so order +
+   * ids match a full load. Default `false` (a full load that re-reads every article).
+   * Used by dev incremental rebuilds; a fresh process / production build never reuses.
+   */
+  reuse?: boolean;
+};
 /**
  * Public API for the content plugin.
  *
@@ -2664,8 +2810,10 @@ type Api = {
   /**
    * Load every article across every active locale, returning a locale-keyed
    * map of date-descending Article arrays. Emits content:ready.
+   *
+   * @param options - Optional load behaviour ({@link LoadAllOptions}); omit for a full load.
    */
-  loadAll(): Promise<Map<string, Article[]>>;
+  loadAll(options?: LoadAllOptions): Promise<Map<string, Article[]>>;
   /**
    * Resolve and render a single article for one locale, with locale fallback.
    *