feat(config): migrate frontmatter schemas to Zod

Author: jikkai

README.md

@@ -1,50 +1,75 @@
 # @amamo/mdx
 
-Compile trusted MDX into JavaScript modules for a configurable JSX runtime (React by default),
-collection metadata, and JSON manifests. A Rust native binding handles parsing, validation, media
-rewriting, manifest projection, and persistent cache records; Shiki runs in JavaScript and feeds
-highlighted HAST back into the same compile pipeline.
+Build MDX collections for Vite 8, Next 16, or a custom Node.js build. Define each collection with
+the package's `z` schema builder, then import MDX as application modules or consume the generated
+collection registry and JSON manifests.
 
-The package exposes three import paths:
+`@amamo/mdx` provides:
 
-| Import            | Purpose                                            |
-| ----------------- | -------------------------------------------------- |
-| `@amamo/mdx`      | Configure and drive the compiler directly.         |
-| `@amamo/mdx/vite` | Compile MDX through Vite 8.                        |
-| `@amamo/mdx/next` | Compile MDX for Next 16 with Turbopack or Webpack. |
+- frontmatter validation and defaults;
+- JavaScript modules for a configurable JSX runtime, with React as the default;
+- fenced-code highlighting and Markdown media imports;
+- collection metadata with companion TypeScript declarations;
+- configurable JSON manifests and a persistent build cache.
 
-## Quick start
+## Requirements
+
+- Node.js 20.19 or newer.
+- A [supported native target](https://jikkai.github.io/mdx/native-targets/). There is no JavaScript
+  or WASI fallback for MDX compilation.
+- React 19 when using the default JSX runtime.
+
+MDX can contain imports, expressions, and JSX. Compile content from authors who are allowed to add
+application code.
+
+## Install
 
 ```sh
 pnpm add @amamo/mdx
 ```
 
-`@amamo/mdx` requires Node.js 20.19 or newer and a [supported native
-target](https://jikkai.github.io/mdx/native-targets/). It has no JavaScript or WASI fallback.
+The package manager installs the platform package for the current operating system and CPU. Install
+dependencies again after moving the project to a different platform instead of copying
+`node_modules`.
+
+## Define a collection
 
-Create a serializable config:
+Create `amamo.config.mjs`:
 
 ```js
-// amamo.config.mjs
-import { defineConfig } from '@amamo/mdx'
+import { defineConfig, z } from '@amamo/mdx'
 
 export default defineConfig({
   root: import.meta.dirname,
   collections: {
     posts: {
       directory: 'content/posts',
-      schema: {
-        $schema: 'https://json-schema.org/draft/2020-12/schema',
-        type: 'object',
-        properties: { title: { type: 'string' } },
-        required: ['title'],
-      },
+      schema: z.object({
+        title: z.string(),
+        publishedAt: z.string().optional(),
+      }),
     },
   },
 })
 ```
 
-Then choose the integration that owns the build.
+Then add `content/posts/hello.mdx`:
+
+```mdx
+---
+title: Hello
+publishedAt: 2026-08-15
+---
+
+# Hello
+
+This document is compiled by @amamo/mdx.
+```
+
+The collection directory must exist before the first full build. Relative collection, cache,
+generated, and manifest paths are resolved from `root`.
+
+## Choose an integration
 
 ### Vite
 
@@ -55,7 +80,9 @@ import { defineConfig } from 'vite'
 
 import amamo from './amamo.config.mjs'
 
-export default defineConfig({ plugins: [amamoMdx(amamo)] })
+export default defineConfig({
+  plugins: [amamoMdx(amamo)],
+})
 ```
 
 ### Next
@@ -66,17 +93,21 @@ import { withAmamoMdx } from '@amamo/mdx/next'
 
 import amamo from './amamo.config.mjs'
 
-export default withAmamoMdx(amamo)({ reactStrictMode: true })
+export default withAmamoMdx(amamo)({
+  reactStrictMode: true,
+})
 ```
 
 ### Direct compiler API
 
-```ts
+```js
+// build-content.mjs
 import { createCompiler } from '@amamo/mdx'
 
 import amamo from './amamo.config.mjs'
 
 const compiler = await createCompiler(amamo)
+
 try {
   const result = await compiler.build()
   console.log(result)
@@ -85,26 +116,57 @@ try {
 }
 ```
 
-The first build writes these compiler-owned files under `generatedDirectory` (default
-`.amamo-mdx`):
+Run the script with `node build-content.mjs`.
 
-- `collections.mjs` — collection metadata with lazy imports of the source MDX files.
-- `collections.d.ts` — a companion declaration output for the collection registry.
-- `index.json` — the private index used by the Next loader.
+## Use compiled content
 
-Cache and manifest paths are configured separately and are resolved from `root`.
+With the Vite plugin or Next wrapper configured, import an MDX file like an application module:
 
-## Security boundary
+```tsx
+import Post, { frontmatter } from './content/posts/hello.mdx'
 
-MDX modules can execute JavaScript when the host imports or renders them. Compile only content from
-trusted authors; schema validation is not a sandbox. Frontmatter fields are ordinary data and may
-appear in compiled modules, cache records, and configured manifests. Store protected values in an
-encrypted form and decrypt them in the consumer, or keep them outside frontmatter. See the
-[security model](https://jikkai.github.io/mdx/security/) before handling protected data.
+export function Page() {
+  return (
+    <main>
+      <h1>{frontmatter.title}</h1>
+      <Post />
+    </main>
+  )
+}
+```
 
-## Documentation
+Or load a document from the generated registry:
+
+```ts
+import { collections } from './.amamo-mdx/collections.mjs'
+
+const hello = collections.posts.find((document) => document.slug === 'hello')
+const module = await hello?.load()
+```
+
+Registry `load()` functions import the source MDX file, so they must run through the configured Vite
+plugin or Next loader.
 
-The complete English and Simplified Chinese documentation covers:
+## Generated files
+
+The first build writes these files under `generatedDirectory`, which defaults to `.amamo-mdx`:
+
+- `collections.mjs` — sorted collection metadata and lazy source imports;
+- `collections.d.ts` — TypeScript declarations for the registry;
+- `index.json` — the source-to-cache index used by the Next loader.
+
+Cache and manifest paths are configured separately from `generatedDirectory`. Add `.amamo-mdx/` to
+the host repository's ignore file unless the application deliberately tracks generated output.
+
+## Package entry points
+
+| Import            | Use it for                                 |
+| ----------------- | ------------------------------------------ |
+| `@amamo/mdx`      | Configuration and the direct compiler API. |
+| `@amamo/mdx/vite` | Vite 8 development and production builds.  |
+| `@amamo/mdx/next` | Next 16 development and production builds. |
+
+## Documentation
 
 - [Getting started](https://jikkai.github.io/mdx/getting-started/)
 - [Configuration reference](https://jikkai.github.io/mdx/configuration/)

apps/docs/docs/compiler-api.mdx

@@ -121,7 +121,8 @@ remove call rejects with `AMAMO_COMPILER_DISPOSED`.
 
 Different boundaries fail differently:
 
-- Invalid plain-data config throws `TypeError` with an `AMAMO_CONFIG_*` code in its message.
+- Invalid object schemas or non-schema configuration data throw `TypeError` with an
+  `AMAMO_CONFIG_*` code in the message.
 - Native parsing, schema, media, cache, and manifest failures become an error named
   `AmamoMdxError` with a `diagnostics` array.
 - Shiki setup and unknown-language failures are ordinary `Error` values.

apps/docs/docs/compiler-api.zh-CN.mdx

@@ -118,7 +118,7 @@ await compiler.dispose()
 
 不同边界的失败形式不同：
 
-- 非法纯数据配置会抛出 `TypeError`，消息中带 `AMAMO_CONFIG_*` code。
+- 非法 object schema 或其它配置数据会抛出 `TypeError`，消息中带 `AMAMO_CONFIG_*` code。
 - 原生解析、schema、媒体、缓存和 manifest 失败会变成名为 `AmamoMdxError` 的错误，并带
   `diagnostics` 数组。
 - Shiki 初始化和未知语言失败是普通 `Error`。

apps/docs/docs/configuration.mdx

@@ -4,18 +4,18 @@ description: Exact defaults and behavior for collections, MDX, math, highlightin
 
 # Configuration
 
-`defineConfig` returns its argument unchanged. `normalizeConfig` is the runtime boundary: it rejects
-non-plain data, applies defaults, resolves paths, and returns the `IAmamoMDXConfig` used by every
-compiler and adapter.
+`defineConfig` returns its argument unchanged. `normalizeConfig` is the runtime boundary: it converts
+Zod collection schemas to JSON Schema, rejects other non-plain data, applies defaults, resolves
+paths, and returns the `IAmamoMDXConfig` used by every compiler and adapter.
 
 ```ts
-import { defineConfig } from '@amamo/mdx'
+import { defineConfig, z } from '@amamo/mdx'
 
 export default defineConfig({
   collections: {
     posts: {
       directory: 'content/posts',
-      schema: { type: 'object' },
+      schema: z.object({}),
     },
   },
 })
@@ -37,27 +37,24 @@ At least one collection is required.
 | `cache`              | enabled           | Persistent compiled records. Use `false` to disable.     |
 | `generatedDirectory` | `.amamo-mdx`      | Registry, declaration, and private Next index directory. |
 
-Functions, symbols, accessors, class instances, cycles, `undefined`, `bigint`, and non-finite numbers
-are rejected. This check runs after your configuration module itself has been imported; it does not
-sandbox that module.
+Apart from collection Zod schemas, functions, symbols, accessors, class instances, cycles,
+`undefined`, `bigint`, and non-finite numbers are rejected. This check runs after your configuration
+module itself has been imported; it does not sandbox that module.
 
 ## Collections
 
 ```ts
+import { z } from '@amamo/mdx'
+
 collections: {
   posts: {
     directory: 'content/posts',
     extensions: ['.mdx'],
     locales: { default: 'en', names: ['en', 'zh-CN'] },
-    schema: {
-      $schema: 'https://json-schema.org/draft/2020-12/schema',
-      type: 'object',
-      properties: {
-        title: { type: 'string' },
-        draft: { type: 'boolean', default: false },
-      },
-      required: ['title'],
-    },
+    schema: z.object({
+      title: z.string(),
+      draft: z.boolean().default(false),
+    }),
     slug: { indexNames: ['index', 'page'] },
   },
 }
@@ -68,12 +65,15 @@ collections: {
 | `directory`       | required            | Resolved from `root`; the directory must exist before `build()`. |
 | `extensions`      | `['.mdx']`          | Included suffixes. Every value must begin with `.`.              |
 | `locales`         | none                | Optional filename-based locale mapping.                          |
-| `schema`          | required            | JSON Schema Draft 2020-12 for YAML frontmatter.                  |
+| `schema`          | required            | Zod object schema for YAML frontmatter.                          |
 | `slug.indexNames` | `['index', 'page']` | Basenames omitted from the derived slug.                         |
 
-Schema defaults declared under `properties`, `items`, and `allOf` are applied before validation.
-Values are never coerced. Validation diagnostics may contain submitted values; do not expose raw
-build errors to untrusted users.
+The package keeps Zod internal and exposes its compatible `z` builder. The config boundary is the
+structural `IFrontmatterSchema` interface, so another compatible object schema can also be passed.
+The object schema is converted to JSON Schema Draft 2020-12; raw JSON Schema objects are rejected.
+Rust applies `.default()` values before validation, but it does not run Zod parsing, coercion,
+transforms, or custom refinements. Use JSON-Schema-representable types and built-in checks. Validation
+diagnostics may contain submitted values; do not expose raw build errors to untrusted users.
 
 When locales are configured, an unsuffixed file uses the default locale. A recognized suffix such as
 `page.zh-CN.mdx` selects that locale. The default locale must appear in `names`. Document identity is

apps/docs/docs/configuration.zh-CN.mdx

@@ -4,17 +4,18 @@ description: 集合、MDX、数学公式、高亮、媒体、派生字段、mani
 
 # 配置
 
-`defineConfig` 会原样返回参数。`normalizeConfig` 才是运行时边界：它拒绝非纯数据、应用默认值、
-解析路径，并返回所有编译器和适配器共用的 `IAmamoMDXConfig`。
+`defineConfig` 会原样返回参数。`normalizeConfig` 才是运行时边界：它把集合的 Zod schema 转成
+JSON Schema、拒绝其它非纯数据、应用默认值、解析路径，并返回所有编译器和适配器共用的
+`IAmamoMDXConfig`。
 
 ```ts
-import { defineConfig } from '@amamo/mdx'
+import { defineConfig, z } from '@amamo/mdx'
 
 export default defineConfig({
   collections: {
     posts: {
       directory: 'content/posts',
-      schema: { type: 'object' },
+      schema: z.object({}),
     },
   },
 })
@@ -36,40 +37,40 @@ export default defineConfig({
 | `cache`              | 启用            | 持久化编译记录；设为 `false` 可禁用。            |
 | `generatedDirectory` | `.amamo-mdx`    | 注册表、声明文件和 Next 私有索引目录。           |
 
-函数、symbol、访问器、类实例、循环引用、`undefined`、`bigint` 和非有限数字都会被拒绝。检查
-发生在配置模块本身已经 import 之后，因此不会沙箱化那个模块。
+除集合的 Zod schema 外，函数、symbol、访问器、类实例、循环引用、`undefined`、`bigint` 和
+非有限数字都会被拒绝。检查发生在配置模块本身已经 import 之后，因此不会沙箱化那个模块。
 
 ## 集合
 
 ```ts
+import { z } from '@amamo/mdx'
+
 collections: {
   posts: {
     directory: 'content/posts',
     extensions: ['.mdx'],
     locales: { default: 'en', names: ['en', 'zh-CN'] },
-    schema: {
-      $schema: 'https://json-schema.org/draft/2020-12/schema',
-      type: 'object',
-      properties: {
-        title: { type: 'string' },
-        draft: { type: 'boolean', default: false },
-      },
-      required: ['title'],
-    },
+    schema: z.object({
+      title: z.string(),
+      draft: z.boolean().default(false),
+    }),
     slug: { indexNames: ['index', 'page'] },
   },
 }
 ```
 
-| 键                | 默认值              | 行为                                                 |
-| ----------------- | ------------------- | ---------------------------------------------------- |
-| `directory`       | 必填                | 从 `root` 解析；调用 `build()` 前目录必须存在。      |
-| `extensions`      | `['.mdx']`          | 纳入集合的后缀；每项必须以 `.` 开头。                |
-| `locales`         | 无                  | 可选的基于文件名的 locale 映射。                     |
-| `schema`          | 必填                | 校验 YAML frontmatter 的 JSON Schema Draft 2020-12。 |
-| `slug.indexNames` | `['index', 'page']` | 推导 slug 时省略的 basename。                        |
-
-校验前会应用 `properties`、`items` 和 `allOf` 中声明的 schema 默认值，但绝不做类型转换。
+| 键                | 默认值              | 行为                                            |
+| ----------------- | ------------------- | ----------------------------------------------- |
+| `directory`       | 必填                | 从 `root` 解析；调用 `build()` 前目录必须存在。 |
+| `extensions`      | `['.mdx']`          | 纳入集合的后缀；每项必须以 `.` 开头。           |
+| `locales`         | 无                  | 可选的基于文件名的 locale 映射。                |
+| `schema`          | 必填                | 校验 YAML frontmatter 的 Zod object schema。    |
+| `slug.indexNames` | `['index', 'page']` | 推导 slug 时省略的 basename。                   |
+
+包内维护 Zod，并对外提供兼容的 `z` builder。配置边界是结构化的 `IFrontmatterSchema` 接口，
+因此也可以传入其它兼容的 object schema。Object schema 会转换为 JSON Schema Draft 2020-12；
+原始 JSON Schema 对象会被拒绝。Rust 会在校验前应用 `.default()` 值，但不会执行 Zod parse、
+类型转换、transform 或自定义 refinement。请只使用可表示为 JSON Schema 的类型和内置检查。
 诊断可能包含用户提交的值；不要把原始构建错误暴露给不可信用户。
 
 配置 locale 后，无后缀文件使用默认 locale；`page.zh-CN.mdx` 这样的已知后缀会选择对应 locale。