blume 1.2.0 → 1.3.0

package/src/core/i18n-ui.ts

@@ -31,7 +31,7 @@ const uiStringsObject = z.object({
       openInChat: z.string().default("Open in chat"),
       scrollToTop: z.string().default("Scroll to top"),
     })
-    .default({}),
+    .prefault({}),
   ask: z
     .object({
       ai: z.string().default("AI"),
@@ -47,12 +47,12 @@ const uiStringsObject = z.object({
       title: z.string().default("Ask AI"),
       you: z.string().default("You"),
     })
-    .default({}),
+    .prefault({}),
   banner: z
     .object({
       dismiss: z.string().default("Dismiss announcement"),
     })
-    .default({}),
+    .prefault({}),
   changelog: z
     .object({
       description: z
@@ -64,12 +64,12 @@ const uiStringsObject = z.object({
       showReleases: z.string().default("Show {version} releases"),
       title: z.string().default("Changelog"),
     })
-    .default({}),
+    .prefault({}),
   content: z
     .object({
       diagramError: z.string().default("Could not render this diagram."),
     })
-    .default({}),
+    .prefault({}),
   feedback: z
     .object({
       no: z.string().default("No"),
@@ -77,13 +77,13 @@ const uiStringsObject = z.object({
       thanks: z.string().default("Thanks for your feedback!"),
       yes: z.string().default("Yes"),
     })
-    .default({}),
+    .prefault({}),
   languageSwitcher: z
     .object({
       label: z.string().default("Language"),
       untranslated: z.string().default("Not translated"),
     })
-    .default({}),
+    .prefault({}),
   nav: z
     .object({
       back: z.string().default("Back"),
@@ -98,7 +98,7 @@ const uiStringsObject = z.object({
       toggleNavigation: z.string().default("Toggle navigation"),
       toggleTheme: z.string().default("Toggle color theme"),
     })
-    .default({}),
+    .prefault({}),
   notFound: z
     .object({
       description: z
@@ -107,7 +107,7 @@ const uiStringsObject = z.object({
       home: z.string().default("Back to home"),
       title: z.string().default("Page not found"),
     })
-    .default({}),
+    .prefault({}),
   page: z
     .object({
       lastUpdated: z.string().default("Last updated on"),
@@ -116,7 +116,7 @@ const uiStringsObject = z.object({
       previous: z.string().default("Previous"),
       skipToContent: z.string().default("Skip to content"),
     })
-    .default({}),
+    .prefault({}),
   search: z
     .object({
       all: z.string().default("All"),
@@ -137,36 +137,27 @@ const uiStringsObject = z.object({
       preview: z.string().default("preview"),
       results: z.string().default("Results"),
     })
-    .default({}),
+    .prefault({}),
   toc: z
     .object({
       title: z.string().default("On this page"),
     })
-    .default({}),
+    .prefault({}),
 });
 
-export const uiStringsSchema = uiStringsObject.default({});
+export const uiStringsSchema = uiStringsObject.prefault({});
 
 /** A fully-resolved dictionary; every key present. */
 export type UIStrings = z.infer<typeof uiStringsObject>;
 
 /**
- * The English baseline, derived from the schema defaults.
- *
- * Each group is passed explicitly as `{}` rather than parsing a bare `{}`: a
- * group's `.default({})` only re-applies its inner field defaults when the group
- * is *present but empty*. Zod 4 changed `.default()` to return the literal
- * default value without re-parsing it through the inner type, so a bare
- * `parse({})` leaves every group undefined and collapses each to `{}` there.
- * Because these components resolve Zod from the consuming project — which may be
- * on v4 while the CLI bundles v3 — the runtime baseline would silently render
- * blank (empty search labels, aria-labels, skip link). Naming every group keeps
- * the baseline fully populated on both Zod 3 and 4.
+ * The English baseline, derived from the schema defaults. The groups use
+ * `.prefault({})` (not `.default({})`) so an absent group is still parsed
+ * through its inner type and every field default applies — under Zod 4's
+ * `.default()` semantics a bare `parse({})` would collapse each group to a
+ * literal `{}` and the runtime would silently render blank chrome.
  */
-const EN_UI_INPUT: Record<string, unknown> = Object.fromEntries(
-  Object.keys(uiStringsObject.shape).map((group) => [group, {}])
-);
-export const EN_UI: UIStrings = uiStringsObject.parse(EN_UI_INPUT);
+export const EN_UI: UIStrings = uiStringsObject.parse({});
 
 /**
  * A partial override: `{ group: { key: "translation" } }`. Validated loosely

package/src/core/project-graph.ts

@@ -75,6 +75,11 @@ export interface BlumeProject {
   droppedPages: number;
   /** The instantiated content sources, for lazy entry reads (search/AI/raw). */
   sources: ContentSource[];
+  /**
+   * Whether the config file set `theme.fonts` itself (see
+   * {@link ConfigLoadResult.themeFontsConfigured}); gates OG font derivation.
+   */
+  themeFontsConfigured: boolean;
   /**
    * Discovered `examples/` sources keyed by `<Component path>`, attached by the
    * runtime/eject layer after {@link scanProject} (example discovery is an Astro
@@ -306,5 +311,6 @@ export const scanProject = async (
     manifest,
     mode,
     sources,
+    themeFontsConfigured: configResult.themeFontsConfigured,
   };
 };

package/src/core/schema.ts

@@ -61,10 +61,7 @@ const sidebarMetaSchema = z.strictObject({
 const xHandleSchema = z.string().transform(normalizeXHandle).optional();
 
 const seoMetaSchema = z.strictObject({
-  // blume bundles Zod 3; top-level `z.url()` is undefined at runtime and
-  // schemas must stay dual-compatible with consumer projects on Zod 4.
-  // oxlint-disable-next-line react-doctor/zod-v4-prefer-top-level-string-formats
-  canonical: z.string().url().optional(),
+  canonical: z.url().optional(),
   description: z.string().optional(),
   image: z.string().optional(),
   noindex: z.boolean().default(false),
@@ -109,9 +106,14 @@ const authorSchema = z.union([
     .catchall(z.unknown()),
 ]);
 
+// Shorthand defaults use `.prefault()`, not `.default()`, wherever the value
+// must still be parsed — Zod 4's `.default()` returns the value as-is, so a
+// `.default({})` on an object with inner defaults (or a transform) would
+// resolve to a bare `{}` instead of the fully-defaulted shape.
+
 /** Frontmatter accepted on any content page. */
 const pageMetaBaseSchema = z.strictObject({
-  ai: aiMetaSchema.default({}),
+  ai: aiMetaSchema.prefault({}),
   /** Post author(s) for blog/changelog content; preserved, not yet rendered. */
   authors: z.union([authorSchema, z.array(authorSchema)]).optional(),
   changelog: changelogMetaSchema.optional(),
@@ -125,9 +127,9 @@ const pageMetaBaseSchema = z.strictObject({
   /** Overrides the git-derived last-modified date when `lastModified` is on. */
   lastModified: dateSchema.optional(),
   noindex: z.boolean().default(false),
-  search: searchMetaSchema.default({}),
-  seo: seoMetaSchema.default({}),
-  sidebar: sidebarMetaSchema.default({}),
+  search: searchMetaSchema.prefault({}),
+  seo: seoMetaSchema.prefault({}),
+  sidebar: sidebarMetaSchema.prefault({}),
   slug: z.string().optional(),
   title: z.string().optional(),
   // No default: an absent `type` must fall through to `content.defaultType`.
@@ -410,33 +412,79 @@ export type SidebarItemConfig =
       root?: string;
     };
 
-const sidebarItemSchema: z.ZodType<SidebarItemConfig> = z.lazy(() =>
-  z.union([
-    z.string(),
-    z.strictObject({
-      badge: z.string().optional(),
-      collapsed: z.boolean().optional(),
-      directory: directoryModeSchema.optional(),
-      display: sidebarDisplaySchema.optional(),
-      href: z.string().optional(),
-      icon: iconName.optional(),
-      items: z.array(sidebarItemSchema).optional(),
-      label: z.string(),
-      root: z.string().optional(),
-    }),
-  ])
-);
-
-/** A curated Google Font slug (see `theme/fonts.ts`). */
-const fontSlug = z.string().superRefine((value, ctx) => {
-  if (!isFontSlug(value)) {
-    ctx.addIssue({
-      code: z.ZodIssueCode.custom,
-      message: `Unknown font "${value}". Supported fonts: ${FONT_SLUGS.join(", ")}.`,
-    });
-  }
+// Zod 4's `ZodType` defaults its Input parameter to `unknown` (it no longer
+// mirrors Output), so the recursive annotation names both — otherwise
+// `z.input` of anything containing this schema degrades to `unknown`.
+const sidebarItemSchema: z.ZodType<SidebarItemConfig, SidebarItemConfig> =
+  z.lazy(() =>
+    z.union([
+      z.string(),
+      z.strictObject({
+        badge: z.string().optional(),
+        collapsed: z.boolean().optional(),
+        directory: directoryModeSchema.optional(),
+        display: sidebarDisplaySchema.optional(),
+        href: z.string().optional(),
+        icon: iconName.optional(),
+        items: z.array(sidebarItemSchema).optional(),
+        label: z.string(),
+        root: z.string().optional(),
+      }),
+    ])
+  );
+
+const fontFallbackSchema = z.enum(["sans", "serif", "mono"]);
+
+/** Any family from a zero-config Astro provider, by name. */
+const remoteFontSchema = z.strictObject({
+  fallback: fontFallbackSchema.optional(),
+  name: z.string().min(1),
+  provider: z
+    .enum(["google", "fontsource", "bunny", "fontshare"])
+    .default("google"),
+  weights: z
+    .array(
+      z.union([z.number().int().positive(), z.string().regex(/^\d+\.\.\d+$/u)])
+    )
+    .nonempty()
+    .optional(),
+});
+
+/** One local `@font-face`: a file plus optional weight/style (else inferred). */
+const localFontVariantSchema = z.strictObject({
+  src: z.string().min(1),
+  style: z.enum(["normal", "italic", "oblique"]).optional(),
+  weight: z
+    .union([
+      z.number().int().positive(),
+      z.string().regex(/^\d+(?:\.\.\d+)?$/u),
+    ])
+    .optional(),
+});
+
+/** A self-hosted family loaded from font files in the project. */
+const localFontSchema = z.strictObject({
+  fallback: fontFallbackSchema.optional(),
+  name: z.string().min(1),
+  variants: z.array(localFontVariantSchema).nonempty(),
 });
 
+/**
+ * A role's font: a curated Google Font slug (see `theme/fonts.ts`), a
+ * remote-provider family, or local font files. Bare strings must be curated
+ * slugs so a typo fails with the supported list instead of a provider error.
+ */
+const fontValueSchema = z
+  .union([z.string(), remoteFontSchema, localFontSchema])
+  .superRefine((value, ctx) => {
+    if (typeof value === "string" && !isFontSlug(value)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `Unknown font "${value}". Supported fonts: ${FONT_SLUGS.join(", ")}. For any other family, use the object form: { name: "..." } (remote provider) or { name: "...", variants: [...] } (local files).`,
+      });
+    }
+  });
+
 /**
  * An optional per-mode theme value: a string applies to both color modes; a
  * `{ light, dark }` object sets each mode individually (either may be
@@ -470,11 +518,11 @@ const themeConfigSchema = z.strictObject({
   backgroundImage: perModeValueSchema,
   fonts: z
     .strictObject({
-      body: fontSlug.default("inter"),
-      display: fontSlug.default("inter-tight"),
-      mono: fontSlug.default("ibm-plex-mono"),
+      body: fontValueSchema.default("inter"),
+      display: fontValueSchema.default("inter-tight"),
+      mono: fontValueSchema.default("ibm-plex-mono"),
     })
-    .default({}),
+    .prefault({}),
   layout: z.enum(["sidebar"]).default("sidebar"),
   mode: z.enum(["system", "light", "dark"]).default("system"),
   radius: z.enum(["none", "sm", "md", "lg"]).default("md"),
@@ -542,7 +590,7 @@ const searchConfigSchema = z
       .strictObject({
         includeHiddenPages: z.boolean().default(false),
       })
-      .default({}),
+      .prefault({}),
     mixedbread: mixedbreadSearchSchema.optional(),
     oramaCloud: oramaCloudSearchSchema.optional(),
     /** Curated links for the Cmd+K empty state; defaults to the first sidebar pages. */
@@ -573,6 +621,37 @@ export const askAiProviders = [
   "openai-compatible",
 ] as const;
 
+/**
+ * JWK parameters that carry private or secret key material (RFC 7518): the
+ * private exponent/scalar, the RSA CRT parameters, and the symmetric key.
+ * A directory is public by definition, so any of these in a configured key is
+ * a leaked credential, not a config style choice — reject loudly.
+ */
+const PRIVATE_JWK_PARAMS = ["d", "p", "q", "dp", "dq", "qi", "oth", "k"];
+
+/**
+ * A public JWK for the Web Bot Auth signature directory. Shape is left to the
+ * signing setup (Ed25519 `OKP` keys in current deployments) — validation only
+ * requires the mandatory `kty` and refuses private key material.
+ */
+const publicJwkSchema = z
+  .record(z.string(), z.unknown())
+  .superRefine((jwk, ctx) => {
+    if (typeof jwk.kty !== "string" || jwk.kty.length === 0) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: 'A JWK must declare its key type ("kty").',
+      });
+    }
+    const leaked = PRIVATE_JWK_PARAMS.filter((param) => param in jwk);
+    if (leaked.length > 0) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `The JWK contains private key material ("${leaked.join('", "')}") — the signatures directory is public, so list only public keys and keep the private key where the signing agent runs.`,
+      });
+    }
+  });
+
 const mcpConfigSchema = z.strictObject({
   enabled: z.boolean().default(false),
   /** Optional system hint passed to connecting agents. */
@@ -616,9 +695,7 @@ const aiConfigSchema = z.strictObject({
       apiKeyEnv: z.string().optional(),
       // Base URL of the backend. Required for `openai-compatible` only when no
       // external endpoint is supplied; for named providers it overrides the preset.
-      // blume bundles Zod 3; top-level `z.url()` is undefined at runtime.
-      // oxlint-disable-next-line react-doctor/zod-v4-prefer-top-level-string-formats
-      baseUrl: z.string().url().optional(),
+      baseUrl: z.url().optional(),
       enabled: z.boolean().default(false),
       // Optional external endpoint for projects that keep their docs static
       // and host Ask AI in an existing backend. Absolute URLs and root-relative
@@ -686,7 +763,35 @@ const aiConfigSchema = z.strictObject({
     )
     .default({}),
   /** Expose the docs as an MCP server for connecting agents. */
-  mcp: mcpConfigSchema.default({}),
+  mcp: mcpConfigSchema.prefault({}),
+  /**
+   * Publish Agent Skills for discovery: a directory (resolved against the
+   * project root) whose subdirectories each hold a `SKILL.md`. The build
+   * copies each skill under `/.well-known/agent-skills/` — a lone `SKILL.md`
+   * verbatim, a skill with supporting files as a `.tar.gz` — and emits the
+   * discovery index (`index.json`) with SHA-256 digests per the Agent Skills
+   * Discovery RFC.
+   */
+  skills: z.string().min(1).optional(),
+  /**
+   * Web Bot Auth (IETF `webbotauth`): publish the org's HTTP Message
+   * Signature public keys at `/.well-known/http-message-signatures-directory`
+   * so sites receiving requests from the org's agents can verify them.
+   * Opt-in and public-keys-only — the private keys live wherever the signing
+   * agents run, never in the site.
+   */
+  webBotAuth: z
+    .strictObject({
+      keys: z.array(publicJwkSchema).default([]),
+    })
+    .prefault({}),
+  /**
+   * WebMCP: register in-page tools (search, page Markdown, the docs index)
+   * on the browser's model context so agentic browsers can drive the docs
+   * without a separate MCP connection. A tiny script that no-ops in browsers
+   * without the API; on by default.
+   */
+  webmcp: z.boolean().default(true),
 });
 
 /**
@@ -720,7 +825,7 @@ const navigationConfigSchema = z.strictObject({
         items: z.array(sidebarItemSchema).optional(),
       }),
     ])
-    .default({})
+    .prefault({})
     .transform((value) =>
       Array.isArray(value) ? { display: "flat" as const, items: value } : value
     ),
@@ -828,9 +933,7 @@ const deploymentConfigSchema = z.strictObject({
     .default(null),
   base: z.string().optional(),
   output: z.enum(["static", "server"]).default("static"),
-  // blume bundles Zod 3; top-level `z.url()` is undefined at runtime.
-  // oxlint-disable-next-line react-doctor/zod-v4-prefer-top-level-string-formats
-  site: z.string().url().optional(),
+  site: z.url().optional(),
 });
 
 const redirectSchema = z.strictObject({
@@ -841,6 +944,33 @@ const redirectSchema = z.strictObject({
   to: z.string(),
 });
 
+/**
+ * One authorized remote image source, passed through to Astro's
+ * `image.remotePatterns`. Wildcards follow Astro's rules: `hostname` accepts
+ * `**.example.com` (any depth) or `*.example.com` (one level), `pathname`
+ * accepts `/dir/**` or `/dir/*` the same way.
+ */
+const imageRemotePatternSchema = z.strictObject({
+  hostname: z.string().optional(),
+  pathname: z.string().optional(),
+  port: z.string().optional(),
+  protocol: z.string().optional(),
+});
+
+/**
+ * Image optimization (`image`). Local images referenced by relative path
+ * (`![alt](./diagram.png)`) are optimized at build time automatically —
+ * compressed, converted to WebP, and stamped with intrinsic dimensions.
+ * Remote images are only optimized when their host is authorized here;
+ * both fields map directly onto Astro's `image` config.
+ */
+const imageConfigSchema = z.strictObject({
+  /** Hosts whose remote images may be optimized, e.g. `["cdn.example.com"]`. */
+  domains: z.array(z.string()).default([]),
+  /** Pattern-based host authorization, for wildcards `domains` can't express. */
+  remotePatterns: z.array(imageRemotePatternSchema).default([]),
+});
+
 /**
  * X (Twitter) attribution. The account fields feed `twitter:site` (the site's
  * account) and `twitter:creator` (the author's), which is the one piece of X
@@ -872,10 +1002,11 @@ const ogPaletteSchema = z.strictObject({
 });
 
 /**
- * A Google Font family to load into the OG card renderer. A bare string is the
- * family name; the object form pins the weight (a number, a list, or a variable
- * range like `"100..900"`) and style. Fetched from Google Fonts at build and
- * handed to Takumi, which does per-glyph fallback so a family covering a script
+ * A font to load into the OG card renderer. A bare string is a Google Fonts
+ * family name; the name-only object form pins the weight (a number, a list, or
+ * a variable range like `"100..900"`) and style, fetched from Google Fonts at
+ * build. The `src` form reads a local font file from the project instead.
+ * Either way Takumi does per-glyph fallback, so a family covering a script
  * (e.g. Noto Sans JP for CJK) fixes tofu without touching how Latin renders.
  */
 const ogFontWeightSchema = z.union([
@@ -891,9 +1022,21 @@ const ogFontSchema = z.union([
     style: z.union([ogFontStyleSchema, z.array(ogFontStyleSchema)]).optional(),
     weight: ogFontWeightSchema.optional(),
   }),
+  /** A local font file, read from the project at build. */
+  z.strictObject({
+    name: z.string(),
+    src: z.string().min(1),
+    style: ogFontStyleSchema.optional(),
+    weight: z.number().int().positive().optional(),
+  }),
 ]);
 
 const ogConfigSchema = z.strictObject({
+  /**
+   * Card subtitle. Defaults to the site description; a string overrides it,
+   * `false` renders the card without one.
+   */
+  description: z.union([z.string(), z.literal(false)]).optional(),
   /**
    * Generate a per-page Open Graph image. Defaults to on once a deployment
    * site URL is known (set or auto-detected) and off otherwise, since
@@ -907,10 +1050,19 @@ const ogConfigSchema = z.strictObject({
    * Fetched from Google Fonts at build.
    */
   fonts: z.array(ogFontSchema).optional(),
-  /** Local SVG used in the generated card instead of the site logo. */
-  logo: z.string().optional(),
+  /**
+   * Local SVG used in the generated card instead of the site logo; `false`
+   * renders the card without any brand mark.
+   */
+  logo: z.union([z.string(), z.literal(false)]).optional(),
   /** Optional generated-card colors. */
   palette: ogPaletteSchema.optional(),
+  /**
+   * Footer site text. Defaults to the deployment site's host plus
+   * `deployment.base` (`docs.acme.com`, `user.github.io/repo`); a string
+   * overrides it, `false` hides it.
+   */
+  site: z.union([z.string(), z.literal(false)]).optional(),
   /**
    * Card headlines for custom `.astro` pages, keyed by route (`"/"`, `"/cli"`).
    * A custom page has no frontmatter to read, so its card is otherwise titled
@@ -970,11 +1122,11 @@ const seoConfigSchema = z.strictObject({
    */
   agentReadability: z.boolean().default(true),
   /** robots.txt `Content-Signal` usage declaration (on by default). */
-  contentSignals: contentSignalsSchema.default(true),
+  contentSignals: contentSignalsSchema.prefault(true),
   og: ogConfigSchema.default({}),
   /** Generate robots.txt (with a Sitemap reference when available). */
   robots: z.boolean().default(true),
-  rss: rssConfigSchema.default({}),
+  rss: rssConfigSchema.prefault({}),
   /** Generate sitemap.xml (requires deployment.site). */
   sitemap: z.boolean().default(true),
   /** Emit schema.org JSON-LD in each page's <head>. */
@@ -1026,7 +1178,7 @@ const codeBlockThemeSchema = z.strictObject({
 });
 
 const codeBlocksConfigSchema = z.strictObject({
-  theme: codeBlockThemeSchema.default({}),
+  theme: codeBlockThemeSchema.prefault({}),
 });
 
 /**
@@ -1127,8 +1279,8 @@ const codeConfigSchema = z.strictObject({
 
 const markdownConfigSchema = z.strictObject({
   /** Code-block rendering: language icons and line wrapping. */
-  code: codeConfigSchema.default({}),
-  codeBlocks: codeBlocksConfigSchema.default({}),
+  code: codeConfigSchema.prefault({}),
+  codeBlocks: codeBlocksConfigSchema.prefault({}),
   /**
    * Wrap each `##`–`######` heading in a link to its own anchor so readers can
    * click to copy, bookmark, or share a permalink to that section. On by
@@ -1293,9 +1445,9 @@ const tocConfigSchema = z
   });
 
 export const blumeConfigSchema = z.strictObject({
-  ai: aiConfigSchema.default({}),
+  ai: aiConfigSchema.prefault({}),
   analytics: analyticsConfigSchema.optional(),
-  asyncapi: asyncapiConfigSchema.default({}),
+  asyncapi: asyncapiConfigSchema.prefault({}),
   banner: bannerConfigSchema.optional(),
   /**
    * Site-wide mount point prepended to every generated route (e.g. `/docs`),
@@ -1307,13 +1459,13 @@ export const blumeConfigSchema = z.strictObject({
     .string()
     .optional()
     .transform((value) => normalizeBasePath(value)),
-  content: contentConfigSchema.default({}),
+  content: contentConfigSchema.prefault({}),
   /**
    * Date presentation for the "last updated" stamp and the changelog timeline.
    * Pass-through `Intl.DateTimeFormat` options; defaults to `{ dateStyle: "long" }`.
    */
   dateFormat: dateFormatConfigSchema.default({ dateStyle: "long" }),
-  deployment: deploymentConfigSchema.default({}),
+  deployment: deploymentConfigSchema.prefault({}),
   description: z.string().optional(),
   /**
    * Where `<Component path>` resolves live previews and their source from.
@@ -1322,24 +1474,25 @@ export const blumeConfigSchema = z.strictObject({
    * files. The object form adds `css`: a stylesheet injected into every
    * preview frame (design tokens, shadcn variables, `@theme` mappings).
    */
-  examples: examplesConfigSchema.default("examples"),
-  export: exportConfigSchema.default(false),
+  examples: examplesConfigSchema.prefault("examples"),
+  export: exportConfigSchema.prefault(false),
   feedback: z.boolean().default(true),
   /** Opt-in custom frontmatter keys, validated by user-supplied schemas. */
-  frontmatter: frontmatterConfigSchema.default({}),
+  frontmatter: frontmatterConfigSchema.prefault({}),
   github: githubConfigSchema.optional(),
   i18n: i18nConfigSchema.optional(),
+  image: imageConfigSchema.prefault({}),
   integrations: z.array(z.custom<AstroIntegration>()).default([]),
   lastModified: lastModifiedConfigSchema.default(false),
   logo: logoConfigSchema.optional(),
-  markdown: markdownConfigSchema.default({}),
-  navigation: navigationConfigSchema.default({}),
-  openapi: openapiConfigSchema.default({}),
-  react: reactConfigSchema.default({}),
+  markdown: markdownConfigSchema.prefault({}),
+  navigation: navigationConfigSchema.prefault({}),
+  openapi: openapiConfigSchema.prefault({}),
+  react: reactConfigSchema.prefault({}),
   redirects: z.array(redirectSchema).default([]),
-  search: searchConfigSchema.default({}),
-  seo: seoConfigSchema.default({}),
-  theme: themeConfigSchema.default({}),
+  search: searchConfigSchema.prefault({}),
+  seo: seoConfigSchema.prefault({}),
+  theme: themeConfigSchema.prefault({}),
   title: z.string().default("Documentation"),
   toc: tocConfigSchema,
 });

package/src/core/sources/normalize.ts

@@ -105,14 +105,14 @@ const mapRoute = (
 const CODE_FENCE = /^(?<delimiter>```|~~~)/u;
 
 /** The fence delimiter opening the current code block, or null outside one. */
-type FenceState = "```" | "~~~" | null;
+export type FenceState = "```" | "~~~" | null;
 
 /**
  * Advance the fenced-code state for one line: an opening fence records its
  * delimiter, only the matching delimiter closes it, and any other line leaves
  * the state untouched.
  */
-const nextFenceState = (line: string, fence: FenceState): FenceState => {
+export const nextFenceState = (line: string, fence: FenceState): FenceState => {
   const trimmed = line.trimStart();
   const delimiter = trimmed.match(CODE_FENCE)?.groups?.delimiter as
     | Exclude<FenceState, null>
@@ -340,12 +340,12 @@ const MD_LINK =
   /\[(?<label>(?:[^[\]]|\[[^\]]*\])*)\]\((?<target>(?:[^()\s]|\([^()\s]*\))+)(?<title>\s+"[^"]*")?\)/gu;
 // An image inside a link label; its target was matched (and so validated) as a
 // link of its own before labels admitted nesting, and still should be.
-const MD_IMAGE =
+export const MD_IMAGE =
   /!\[[^\]]*\]\((?<target>(?:[^()\s]|\([^()\s]*\))+)(?<title>\s+"[^"]*")?\)/gu;
-const INLINE_CODE = /`[^`]*`/gu;
+export const INLINE_CODE = /`[^`]*`/gu;
 
 /** Column (0-based, within `matched`) where a link/image match's target starts. */
-const targetOffsetIn = (
+export const targetOffsetIn = (
   matched: string,
   target: string,
   title: string | undefined