@amamo/mdx 0.2.0 → 0.4.0

package/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,25 +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. Mark top-level frontmatter fields as
-`sensitive` to keep their plaintext out of compiled modules, cache records, and manifests. See the
-[security model](https://jikkai.github.io/mdx/security/) before handling secrets.
+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/)

package/dist/compiler.d.ts

@@ -22,7 +22,11 @@ export interface ICompiler {
 export interface IAdapterCompiler extends ICompiler {
     readonly generatedCollectionModule: string;
     isContentFile(file: string): boolean;
+    scan(): Promise<IBuildResult>;
     startWatch(onGeneratedChange?: (paths: string[]) => Promise<void> | void): () => void;
+    transformSource(file: string, source: string): Promise<ITransformResult>;
 }
 export declare function createCompiler(config: IAmamoMdxConfig): Promise<ICompiler>;
-export declare function createAdapterCompiler(config: IAmamoMdxConfig): Promise<IAdapterCompiler>;
+export declare function createAdapterCompiler(config: IAmamoMdxConfig, options?: {
+    retainModules?: boolean;
+}): Promise<IAdapterCompiler>;

package/dist/compiler.js

@@ -10,19 +10,22 @@ let temporaryFileId = 0;
 const execFileAsync = promisify(execFile);
 class Compiler {
     config;
-    shiki;
+    retainModules;
     generatedCollectionModule;
     buildInFlight;
     disposed = false;
     generatedListener;
     gitModifiedTimes = new Map();
+    modules = new Map();
     records = new Map();
+    sources = new Map();
+    shikiPromise;
     tail = Promise.resolve();
     watcher;
     watcherError;
-    constructor(config, shiki) {
+    constructor(config, retainModules) {
         this.config = config;
-        this.shiki = shiki;
+        this.retainModules = retainModules;
         this.generatedCollectionModule = path.join(config.generatedDirectory, 'collections.mjs');
     }
     build() {
@@ -42,11 +45,19 @@ class Compiler {
     transform(file) {
         return this.enqueue(() => this.transformNow(cleanFileId(file)));
     }
+    transformSource(file, source) {
+        return this.enqueue(() => this.transformNow(cleanFileId(file), source));
+    }
+    scan() {
+        return this.enqueue(() => this.scanNow());
+    }
     remove(file) {
         return this.enqueue(async () => {
             const absolute = cleanFileId(file);
             if (!this.records.delete(absolute))
                 return 0;
+            this.modules.delete(absolute);
+            this.sources.delete(absolute);
             const changed = await this.writeOutputs();
             if (this.config.cache.enabled) {
                 pruneNativeCache(this.config.cache.directory, [...this.records.values()].map((record) => record.cacheKey));
@@ -61,7 +72,8 @@ class Compiler {
         await this.enqueue(async () => {
             this.watcher?.close();
             this.watcher = undefined;
-            this.shiki?.dispose();
+            const shiki = this.shikiPromise ? await this.shikiPromise : undefined;
+            shiki?.dispose();
             this.disposed = true;
         }, false);
     }
@@ -123,9 +135,12 @@ class Compiler {
     async buildNow() {
         const discovered = await this.discover();
         const records = await this.compile(discovered.map((document) => document.input));
-        this.records.clear();
-        for (const record of records)
-            this.records.set(path.resolve(record.file), record);
+        this.replaceRecords(records.map(documentMetadata), discovered.map((document) => document.input));
+        this.modules.clear();
+        if (this.retainModules) {
+            for (const record of records)
+                this.modules.set(path.resolve(record.file), record.module);
+        }
         const changed = await this.writeOutputs();
         if (this.config.cache.enabled) {
             pruneNativeCache(this.config.cache.directory, records.map((record) => record.cacheKey));
@@ -138,7 +153,39 @@ class Compiler {
             outputsWritten: changed.length,
         };
     }
-    async transformNow(file) {
+    async scanNow() {
+        const discovered = await this.discover();
+        const inputs = discovered.map((document) => document.input);
+        const records = prepareNativeBatch(this.config, inputs).takeMetadata();
+        this.replaceRecords(records, inputs);
+        this.modules.clear();
+        const changed = await this.writeOutputs();
+        if (this.config.cache.enabled) {
+            pruneNativeCache(this.config.cache.directory, records.map((record) => record.cacheKey));
+        }
+        await this.notifyGeneratedChange(changed);
+        return {
+            cached: records.filter((record) => record.cached).length,
+            compiled: 0,
+            discovered: discovered.length,
+            outputsWritten: changed.length,
+        };
+    }
+    async transformNow(file, source) {
+        const current = this.records.get(file);
+        const currentModule = this.modules.get(file);
+        if (source !== undefined &&
+            source === this.sources.get(file) &&
+            current &&
+            currentModule !== undefined) {
+            return {
+                cached: true,
+                code: currentModule,
+                map: null,
+                outputsWritten: 0,
+                record: { ...current, cached: true, module: currentModule },
+            };
+        }
         const metadata = this.metadataForFile(file);
         if (!metadata) {
             throw new Error(`AMAMO_FILE_OUTSIDE_COLLECTION: ${file}`);
@@ -150,12 +197,16 @@ class Compiler {
                 throw new Error(`AMAMO_DOCUMENT_DUPLICATE_KEY: ${metadata.collection}/${metadata.key}`);
             }
         }
-        const document = await this.readDocument(metadata);
+        const document = await this.readDocument(metadata, source);
         const records = await this.compile([document.input]);
         const record = records[0];
         if (!record)
             throw new Error(`AMAMO_NATIVE_RESULT_MISSING: ${file}`);
-        this.records.set(file, record);
+        this.records.set(file, documentMetadata(record));
+        if (this.retainModules) {
+            this.modules.set(file, record.module);
+            this.sources.set(file, document.input.source);
+        }
         const changed = await this.writeOutputs();
         if (this.config.cache.enabled) {
             pruneNativeCache(this.config.cache.directory, [...this.records.values()].map((value) => value.cacheKey));
@@ -171,7 +222,11 @@ class Compiler {
     }
     async compile(inputs) {
         const batch = prepareNativeBatch(this.config, inputs);
-        const highlights = this.shiki ? await this.shiki.highlight(batch.codeBlocks) : [];
+        let highlights = [];
+        if (this.config.highlight.enabled && batch.codeBlocks.length > 0) {
+            this.shikiPromise ??= createShikiRenderer(this.config.highlight);
+            highlights = await (await this.shikiPromise).highlight(batch.codeBlocks);
+        }
         return batch.finish(highlights);
     }
     async discover() {
@@ -200,10 +255,10 @@ class Compiler {
         const documents = await Promise.all(documentsMetadata.map((value) => this.readDocument(value)));
         return documents.toSorted((left, right) => left.input.file.localeCompare(right.input.file));
     }
-    async readDocument(metadata) {
+    async readDocument(metadata, providedSource) {
         const [source, stats] = await Promise.all([
-            readFile(metadata.file, 'utf8'),
-            stat(metadata.file),
+            providedSource ?? readFile(metadata.file, 'utf8'),
+            this.config.derived.lastModified ? stat(metadata.file) : undefined,
         ]);
         return {
             input: {
@@ -212,7 +267,7 @@ class Compiler {
                 key: metadata.key,
                 locale: metadata.locale,
                 modifiedAt: this.config.derived.lastModified
-                    ? (this.gitModifiedTimes.get(metadata.file) ?? stats.mtime.toISOString())
+                    ? (this.gitModifiedTimes.get(metadata.file) ?? stats?.mtime.toISOString())
                     : undefined,
                 slug: metadata.slug,
                 source,
@@ -246,9 +301,20 @@ class Compiler {
         }, {
             contents: `${JSON.stringify({
                 cacheDirectory: this.config.cache.directory,
+                config: this.config,
                 configFingerprint: configurationFingerprint(this.config),
-                documents: Object.fromEntries(records.map((record) => [record.file, { cacheKey: record.cacheKey }])),
-                version: 1,
+                documents: Object.fromEntries(records.map((record) => [
+                    record.file,
+                    {
+                        cacheKey: record.cacheKey,
+                        collection: record.collection,
+                        key: record.key,
+                        locale: record.locale,
+                        modifiedAt: record.modifiedAt,
+                        slug: record.slug,
+                    },
+                ])),
+                version: 2,
             }, null, 2)}\n`,
             path: path.join(this.config.generatedDirectory, 'index.json'),
         });
@@ -259,6 +325,16 @@ class Compiler {
         }
         return changed;
     }
+    replaceRecords(records, inputs) {
+        this.records.clear();
+        for (const record of records)
+            this.records.set(path.resolve(record.file), record);
+        this.sources.clear();
+        if (this.retainModules) {
+            for (const input of inputs)
+                this.sources.set(path.resolve(input.file), input.source);
+        }
+    }
     async notifyGeneratedChange(paths) {
         if (paths.length === 0 || !this.generatedListener)
             return;
@@ -268,12 +344,9 @@ class Compiler {
 export async function createCompiler(config) {
     return createAdapterCompiler(config);
 }
-export async function createAdapterCompiler(config) {
+export async function createAdapterCompiler(config, options = {}) {
     const normalized = normalizeConfig(config);
-    const shiki = normalized.highlight.enabled
-        ? await createShikiRenderer(normalized.highlight)
-        : undefined;
-    return new Compiler(normalized, shiki);
+    return new Compiler(normalized, options.retainModules ?? true);
 }
 function deriveMetadata(collection, config, file, extensionless) {
     const segments = extensionless.split(path.sep);
@@ -382,6 +455,24 @@ async function writeIfChanged(file, contents) {
 function compareRecords(left, right) {
     return left.collection.localeCompare(right.collection) || left.key.localeCompare(right.key);
 }
+function documentMetadata(record) {
+    return {
+        cacheKey: record.cacheKey,
+        cached: record.cached,
+        collection: record.collection,
+        dependencies: record.dependencies,
+        derived: record.derived,
+        diagnostics: record.diagnostics,
+        file: record.file,
+        frontmatter: record.frontmatter,
+        hash: record.hash,
+        key: record.key,
+        locale: record.locale,
+        modifiedAt: record.modifiedAt,
+        projections: record.projections,
+        slug: record.slug,
+    };
+}
 function cleanFileId(file) {
     const absolute = path.resolve(file.split('?')[0] ?? file);
     const missing = [];

package/dist/config.d.ts

@@ -1,3 +1,5 @@
+import * as z from 'zod';
+export { z };
 export type JsonValue = null | boolean | number | string | JsonValue[] | {
     [key: string]: JsonValue;
 };
@@ -13,14 +15,15 @@ export interface ILocaleConfig {
 export interface ISlugConfig {
     indexNames?: string[];
 }
+export interface IFrontmatterSchema {
+    readonly shape: Readonly<Record<string, unknown>>;
+    toJSONSchema(): unknown;
+}
 export interface ICollectionConfig {
     directory: string;
     extensions?: string[];
     locales?: ILocaleConfig;
-    schema: {
-        [key: string]: JsonValue;
-    };
-    sensitive?: string[];
+    schema: IFrontmatterSchema;
     slug?: ISlugConfig;
 }
 export interface IMathConfig {
@@ -90,7 +93,6 @@ export interface INormalizedCollectionConfig {
     schema: {
         [key: string]: JsonValue;
     };
-    sensitive: string[];
     slug: {
         indexNames: string[];
     };
@@ -116,7 +118,7 @@ export interface INormalizedManifestConfig extends Omit<IManifestConfig, 'collec
     collections: string[];
     output: string;
 }
-export interface INormalizedConfig {
+export interface IAmamoMDXConfig {
     cache: {
         directory: string;
         enabled: boolean;
@@ -142,4 +144,4 @@ export interface INormalizedConfig {
     root: string;
 }
 export declare function defineConfig<T extends IAmamoMdxConfig>(config: T): T;
-export declare function normalizeConfig(config: IAmamoMdxConfig): INormalizedConfig;
+export declare function normalizeConfig(config: IAmamoMdxConfig): IAmamoMDXConfig;

package/dist/config.js

@@ -1,6 +1,8 @@
 import { Buffer } from 'node:buffer';
 import { existsSync, realpathSync } from 'node:fs';
 import path from 'node:path';
+import * as z from 'zod';
+export { z };
 const DEFAULT_MEDIA_ATTRIBUTES = {
     audio: ['src'],
     embed: ['src'],
@@ -16,7 +18,9 @@ const MAX_MATH_MACROS_BYTES = 16 * 1024;
 function notSerializable(location, reason) {
     throw new TypeError(`AMAMO_CONFIG_NOT_SERIALIZABLE: ${location} ${reason}`);
 }
-function assertPlainData(value, location, active) {
+function assertPlainData(value, location, active, segments = []) {
+    if (segments.length === 3 && segments[0] === 'collections' && segments[2] === 'schema')
+        return;
     if (value === null || typeof value === 'string' || typeof value === 'boolean')
         return;
     if (typeof value === 'number') {
@@ -39,7 +43,7 @@ function assertPlainData(value, location, active) {
         const descriptor = Object.getOwnPropertyDescriptor(value, key);
         if (!descriptor || !('value' in descriptor))
             notSerializable(`${location}.${key}`, 'contains an accessor');
-        assertPlainData(descriptor.value, `${location}.${key}`, active);
+        assertPlainData(descriptor.value, `${location}.${key}`, active, [...segments, key]);
     }
     active.delete(value);
 }
@@ -57,14 +61,32 @@ function normalizeCollection(root, name, config) {
         throw new TypeError(`AMAMO_CONFIG_INVALID: collections.${name}.locales.default must be listed in names`);
     }
     const directory = path.resolve(root, requireNonEmpty(config.directory, `collections.${name}.directory`));
+    if (typeof config.schema?.shape !== 'object' ||
+        config.schema.shape === null ||
+        typeof config.schema.toJSONSchema !== 'function') {
+        throw new TypeError(`AMAMO_CONFIG_INVALID: collections.${name}.schema must be a compatible object schema`);
+    }
+    let schema;
+    try {
+        schema = JSON.parse(JSON.stringify(config.schema.toJSONSchema()));
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : 'could not be converted to JSON Schema';
+        throw new TypeError(`AMAMO_CONFIG_INVALID: collections.${name}.schema ${reason}`, {
+            cause: error,
+        });
+    }
+    if (schema.type !== 'object') {
+        throw new TypeError(`AMAMO_CONFIG_INVALID: collections.${name}.schema must convert to an object schema`);
+    }
+    assertPlainData(schema, `collections.${name}.schema`, new WeakSet());
     return {
         directory: existsSync(directory) ? realpathSync.native(directory) : directory,
         extensions: [...extensions],
         locales: config.locales
             ? { default: config.locales.default, names: [...config.locales.names] }
             : undefined,
-        schema: config.schema,
-        sensitive: [...(config.sensitive ?? [])],
+        schema,
         slug: { indexNames: [...(config.slug?.indexNames ?? ['index', 'page'])] },
     };
 }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export type { IAmamoMdxConfig, ICacheConfig, ICollectionConfig, IDerivedConfig, IHighlightConfig, ILocaleConfig, IManifestConfig, IMathConfig, IMdxConfig, IMdxExtensionsConfig, IMediaConfig, INormalizedConfig, JsonValue, ManifestField, } from './config.js';
-export { defineConfig, normalizeConfig } from './config.js';
+export type { IAmamoMDXConfig, IAmamoMdxConfig, ICacheConfig, ICollectionConfig, IDerivedConfig, IFrontmatterSchema, IHighlightConfig, ILocaleConfig, IManifestConfig, IMathConfig, IMdxConfig, IMdxExtensionsConfig, IMediaConfig, JsonValue, ManifestField, } from './config.js';
+export { defineConfig, normalizeConfig, z } from './config.js';
 export type { IBuildResult, ICompiler, ITransformResult } from './compiler.js';
 export { createCompiler } from './compiler.js';
 export type { IDiagnostic } from './native.js';

package/dist/index.js

@@ -1,2 +1,2 @@
-export { defineConfig, normalizeConfig } from './config.js';
+export { defineConfig, normalizeConfig, z } from './config.js';
 export { createCompiler } from './compiler.js';

package/dist/native.d.ts

@@ -1,4 +1,4 @@
-import type { INormalizedConfig, JsonValue } from './config.js';
+import type { IAmamoMDXConfig, JsonValue } from './config.js';
 export interface ISourcePoint {
     column: number;
     line: number;
@@ -37,7 +37,7 @@ export interface IHighlightedCodeBlock {
     documentId: string;
     hast: JsonValue;
 }
-export interface IDocumentRecord {
+export interface IDocumentMetadata {
     cacheKey: string;
     cached: boolean;
     collection: string;
@@ -49,10 +49,13 @@ export interface IDocumentRecord {
     hash: string;
     key: string;
     locale?: string;
-    module: string;
+    modifiedAt?: string;
     projections: Record<string, JsonValue>;
     slug?: string;
 }
+export interface IDocumentRecord extends IDocumentMetadata {
+    module: string;
+}
 export interface IRenderedManifest {
     contents: string;
     path: string;
@@ -60,12 +63,13 @@ export interface IRenderedManifest {
 export interface IPreparedNativeBatch {
     codeBlocks: ICodeBlock[];
     finish(highlights: IHighlightedCodeBlock[]): IDocumentRecord[];
+    takeMetadata(): IDocumentMetadata[];
 }
 export declare class AmamoMdxError extends Error {
     readonly diagnostics: IDiagnostic[];
     constructor(diagnostics: IDiagnostic[]);
 }
-export declare function configurationFingerprint(config: INormalizedConfig): string;
-export declare function prepareNativeBatch(config: INormalizedConfig, inputs: INativeDocumentInput[]): IPreparedNativeBatch;
+export declare function configurationFingerprint(config: IAmamoMDXConfig): string;
+export declare function prepareNativeBatch(config: IAmamoMDXConfig, inputs: INativeDocumentInput[]): IPreparedNativeBatch;
 export declare function pruneNativeCache(cacheDirectory: string, keepKeys: string[]): number;
-export declare function renderNativeManifests(config: INormalizedConfig, records: IDocumentRecord[]): IRenderedManifest[];
+export declare function renderNativeManifests(config: IAmamoMDXConfig, records: IDocumentMetadata[]): IRenderedManifest[];

package/dist/native.js

@@ -44,6 +44,14 @@ export function prepareNativeBatch(config, inputs) {
                     return mapNativeError(error);
                 }
             },
+            takeMetadata() {
+                try {
+                    return JSON.parse(batch.takeMetadataJson());
+                }
+                catch (error) {
+                    return mapNativeError(error);
+                }
+            },
         };
     }
     catch (error) {
@@ -60,7 +68,11 @@ export function pruneNativeCache(cacheDirectory, keepKeys) {
 }
 export function renderNativeManifests(config, records) {
     try {
-        return JSON.parse(loadBinding().renderManifests(nativeConfigJson(config), JSON.stringify(records)));
+        const manifestRecords = records.map(({ key, projections }) => ({
+            key,
+            projections,
+        }));
+        return JSON.parse(loadBinding().renderManifests(nativeConfigJson(config), JSON.stringify(manifestRecords)));
     }
     catch (error) {
         return mapNativeError(error);

package/dist/next-loader.cjs

@@ -4,30 +4,48 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 const promises_1 = require("node:fs/promises");
 const node_path_1 = __importDefault(require("node:path"));
-function nextLoader(_source) {
-    return readCompiledModule(this);
+function nextLoader(source) {
+    return compileModule(this, source);
 }
-async function readCompiledModule(context) {
+async function compileModule(context, source) {
     const options = context.getOptions();
+    context.addDependency(options.indexFile);
+    let config;
+    let input;
     try {
         const index = JSON.parse(await (0, promises_1.readFile)(options.indexFile, 'utf8'));
         const resource = await (0, promises_1.realpath)(node_path_1.default.resolve(context.resourcePath));
-        const cacheKey = index.documents?.[resource]?.cacheKey;
-        if (index.configFingerprint !== options.configFingerprint ||
+        const document = index.documents?.[resource];
+        if (index.version !== 2 ||
+            index.configFingerprint !== options.configFingerprint ||
             typeof index.cacheDirectory !== 'string' ||
-            typeof cacheKey !== 'string' ||
-            !/^[a-f0-9]{64}$/.test(cacheKey)) {
+            typeof index.config !== 'object' ||
+            index.config === null ||
+            index.config.cache.directory !== index.cacheDirectory ||
+            typeof document?.cacheKey !== 'string' ||
+            !/^[a-f0-9]{64}$/.test(document.cacheKey) ||
+            typeof document.collection !== 'string' ||
+            typeof document.key !== 'string') {
             throw new Error('index entry does not match this build');
         }
-        const cacheFile = node_path_1.default.join(index.cacheDirectory, cacheKey.slice(0, 2), `${cacheKey}.json`);
-        const record = JSON.parse(await (0, promises_1.readFile)(cacheFile, 'utf8'));
-        if (record.cacheKey !== cacheKey || typeof record.module !== 'string') {
-            throw new Error('cache record does not match its index entry');
-        }
-        return record.module;
+        config = index.config;
+        input = {
+            collection: document.collection,
+            file: resource,
+            key: document.key,
+            locale: document.locale,
+            modifiedAt: document.modifiedAt,
+            slug: document.slug,
+            source,
+        };
     }
     catch (error) {
         throw new Error(`AMAMO_NEXT_CACHE_MISS: ${context.resourcePath}; rerun the coordinated amamo-mdx build`, { cause: error });
     }
+    const { compileNextDocument } = await import('./next-runtime.js');
+    const record = await compileNextDocument(config, input);
+    for (const dependency of record.dependencies)
+        context.addDependency(dependency);
+    return record.module;
 }
 module.exports = nextLoader;

package/dist/next-runtime.d.ts

@@ -0,0 +1,3 @@
+import type { IAmamoMDXConfig } from './config.js';
+import type { IDocumentRecord, INativeDocumentInput } from './native.js';
+export declare function compileNextDocument(config: IAmamoMDXConfig, input: INativeDocumentInput): Promise<IDocumentRecord>;

package/dist/next-runtime.js

@@ -0,0 +1,20 @@
+import { configurationFingerprint, prepareNativeBatch } from './native.js';
+import { createShikiRenderer } from './shiki.js';
+const renderers = new Map();
+export async function compileNextDocument(config, input) {
+    const batch = prepareNativeBatch(config, [input]);
+    let highlights = [];
+    if (config.highlight.enabled && batch.codeBlocks.length > 0) {
+        const fingerprint = configurationFingerprint(config);
+        let renderer = renderers.get(fingerprint);
+        if (!renderer) {
+            renderer = createShikiRenderer(config.highlight);
+            renderers.set(fingerprint, renderer);
+        }
+        highlights = await (await renderer).highlight(batch.codeBlocks);
+    }
+    const record = batch.finish(highlights)[0];
+    if (!record)
+        throw new Error(`AMAMO_NATIVE_RESULT_MISSING: ${input.file}`);
+    return record;
+}

package/dist/next.js

@@ -13,17 +13,23 @@ export function withAmamoMdx(config) {
     };
     let compilerPromise;
     let buildPromise;
+    let scanPromise;
     let watching = false;
     function compiler() {
-        compilerPromise ??= createAdapterCompiler(config);
+        compilerPromise ??= createAdapterCompiler(config, { retainModules: false });
         return compilerPromise;
     }
     async function prepare(phase) {
         if (phase !== PHASE_DEVELOPMENT_SERVER && phase !== PHASE_PRODUCTION_BUILD)
             return;
-        buildPromise ??= compiler().then((instance) => instance.build());
-        await buildPromise;
-        if (phase === PHASE_DEVELOPMENT_SERVER && !watching) {
+        if (phase === PHASE_PRODUCTION_BUILD) {
+            buildPromise ??= compiler().then((instance) => instance.build());
+            await buildPromise;
+            return;
+        }
+        scanPromise ??= compiler().then((instance) => instance.scan());
+        await scanPromise;
+        if (!watching) {
             const instance = await compiler();
             instance.startWatch();
             watching = true;

package/dist/shiki.js

@@ -59,8 +59,17 @@ export async function createShikiRenderer(config) {
         async highlight(blocks) {
             if (disposed)
                 throw new Error('AMAMO_SHIKI_DISPOSED: Shiki renderer is disposed');
-            const languages = await Promise.all(blocks.map((block) => loadLanguage(block.lang)));
-            return blocks.map((block, index) => {
+            const keys = blocks.map((block) => JSON.stringify([block.lang, block.meta, block.code]));
+            const uniqueBlocks = new Map();
+            for (const [index, block] of blocks.entries()) {
+                const key = keys[index];
+                if (key !== undefined && !uniqueBlocks.has(key))
+                    uniqueBlocks.set(key, block);
+            }
+            const entries = [...uniqueBlocks.entries()];
+            const languages = await Promise.all(entries.map(([, block]) => loadLanguage(block.lang)));
+            const highlighted = new Map();
+            for (const [index, [key, block]] of entries.entries()) {
                 const language = block.lang;
                 const hast = highlighter.codeToHast(block.code, {
                     colorReplacements: config.colorReplacements,
@@ -82,10 +91,18 @@ export async function createShikiRenderer(config) {
                         ]
                         : undefined,
                 });
+                highlighted.set(key, JSON.parse(JSON.stringify(hast)));
+            }
+            return blocks.map((block, index) => {
+                const key = keys[index];
+                const hast = key === undefined ? undefined : highlighted.get(key);
+                if (hast === undefined) {
+                    throw new Error('AMAMO_SHIKI_RESULT_MISSING: Highlighted code block is missing');
+                }
                 return {
                     blockId: block.blockId,
                     documentId: block.documentId,
-                    hast: JSON.parse(JSON.stringify(hast)),
+                    hast,
                 };
             });
         },

package/dist/vite.js

@@ -25,11 +25,11 @@ export function amamoMdx(config) {
         async buildStart() {
             await ensureBuild();
         },
-        async transform(_source, id) {
+        async transform(source, id) {
             const instance = await compiler();
             if (!instance.isContentFile(id))
                 return null;
-            const result = await instance.transform(id);
+            const result = await instance.transformSource(id, source);
             return { code: result.code, map: result.map };
         },
         async configureServer(server) {

package/native.d.ts

@@ -2,6 +2,7 @@
 /* eslint-disable */
 export declare class PreparedBatch {
   get codeBlocksJson(): string
+  takeMetadataJson(): string
   finish(highlightsJson: string): string
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amamo/mdx",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "A native MDX content compiler with Vite and Next adapters",
   "homepage": "https://jikkai.github.io/mdx/",
   "license": "MIT",
@@ -48,30 +48,33 @@
     "test": "pnpm run build && vitest run src/__tests__",
     "test:rust": "cargo test",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "check": "pnpm run format:check && pnpm run lint && cargo clippy --all-targets -- -D warnings && cargo test && pnpm run typecheck && pnpm run test && pnpm run check:docs",
+    "check": "pnpm run format:check && pnpm run lint && pnpm run check:rust && pnpm run check:npm && pnpm run check:docs",
     "check:docs": "pnpm --filter @amamo/mdx-docs types:check && pnpm --filter @amamo/mdx-docs build",
+    "check:npm": "pnpm run typecheck && pnpm run test",
+    "check:rust": "cargo clippy --all-targets -- -D warnings && pnpm run test:rust",
     "release": "verso"
   },
   "dependencies": {
-    "shiki": "4.4.2"
+    "shiki": "4.4.3",
+    "zod": "4.5.4"
   },
   "devDependencies": {
-    "@amamo/oxlint-config": "1.0.0",
-    "@amamo/verso": "1.0.1",
-    "@napi-rs/cli": "3.8.4",
-    "@types/node": "26.2.0",
+    "@amamo/oxlint-config": "1.1.0",
+    "@amamo/verso": "1.2.0",
+    "@napi-rs/cli": "3.8.6",
+    "@types/node": "26.4.0",
     "@types/react": "19.2.18",
-    "@types/react-dom": "19.2.4",
-    "lint-staged": "17.3.0",
-    "next": "16.3.0",
-    "oxfmt": "0.62.0",
-    "oxlint": "1.77.0",
+    "@types/react-dom": "19.2.5",
+    "lint-staged": "17.4.1",
+    "next": "16.3.3",
+    "oxfmt": "0.65.0",
+    "oxlint": "1.80.0",
     "react": "19.2.8",
     "react-dom": "19.2.8",
-    "simple-git-hooks": "2.13.1",
+    "simple-git-hooks": "2.14.0",
     "typescript": "7.0.2",
-    "vite": "8.2.1",
-    "vitest": "4.1.10"
+    "vite": "8.2.2",
+    "vitest": "4.1.11"
   },
   "peerDependencies": {
     "next": "^16.0.0",
@@ -114,14 +117,14 @@
   "engines": {
     "node": ">=20.19"
   },
-  "packageManager": "pnpm@11.20.0",
+  "packageManager": "pnpm@12.1.0",
   "optionalDependencies": {
-    "@amamo/mdx-darwin-arm64": "0.2.0",
-    "@amamo/mdx-darwin-x64": "0.2.0",
-    "@amamo/mdx-linux-arm64-gnu": "0.2.0",
-    "@amamo/mdx-linux-x64-gnu": "0.2.0",
-    "@amamo/mdx-linux-arm64-musl": "0.2.0",
-    "@amamo/mdx-linux-x64-musl": "0.2.0",
-    "@amamo/mdx-win32-x64-msvc": "0.2.0"
+    "@amamo/mdx-darwin-arm64": "0.4.0",
+    "@amamo/mdx-darwin-x64": "0.4.0",
+    "@amamo/mdx-linux-arm64-gnu": "0.4.0",
+    "@amamo/mdx-linux-x64-gnu": "0.4.0",
+    "@amamo/mdx-linux-arm64-musl": "0.4.0",
+    "@amamo/mdx-linux-x64-musl": "0.4.0",
+    "@amamo/mdx-win32-x64-msvc": "0.4.0"
   }
 }