@mandujs/core 0.41.2 → 0.43.0

package/src/content/collection.ts

@@ -1,809 +1,844 @@
-/**
- * Collection API (Issue #199)
- *
- * First-class content collection primitive inspired by Astro's
- * `astro:content` + Next.js `@next/mdx` + Fumadocs. Projects declare
- * collections once in `content.config.ts`, then read them anywhere
- * with full typed autocomplete:
- *
- * ```ts
- * // content.config.ts
- * import { defineCollection, z } from '@mandujs/core/content';
- *
- * export const docs = defineCollection({
- *   path: 'content/docs',
- *   schema: z.object({
- *     title: z.string(),
- *     order: z.number().optional(),
- *     draft: z.boolean().default(false),
- *   }),
- * });
- * ```
- *
- * ```ts
- * // anywhere in the app
- * import { docs } from './content.config';
- *
- * const entries = await docs.all();
- * const intro = await docs.get('intro');
- * ```
- *
- * # Overload compatibility
- *
- * The legacy `defineCollection({ loader, schema })` shape (used by the
- * existing ContentLayer in `content-layer.ts`) is still supported — we
- * detect the shape at runtime and pass config through unchanged. Only
- * the NEW `{ path, schema, ... }` shape returns a `Collection` instance
- * with `.load()/.all()/.get()/.getCompiled()`. This matters because the
- * CLI `mandu collection create` scaffolder already emits the legacy
- * shape, and breaking those projects on a minor version is not an
- * option for the MVP.
- */
-
-import * as fs from "fs";
-import * as path from "path";
-import type { ZodSchema } from "zod";
-import { parseFrontmatter } from "./frontmatter";
-import { slugFromPath, type SlugFromPathOptions } from "./slug";
-
-/** A single entry in a Collection after frontmatter + Zod validation. */
-export interface CollectionEntry<T = Record<string, unknown>> {
-  /** URL-safe slug derived from the file path (see `slugFromPath`). */
-  slug: string;
-  /** Absolute filesystem path of the source file. */
-  filePath: string;
-  /** Validated frontmatter data. */
-  data: T;
-  /** Raw markdown/MDX body (everything after the closing `---`). */
-  content: string;
-}
-
-/** A compiled MDX entry with a lazy-rendered React component. */
-export interface CompiledCollectionEntry<T = Record<string, unknown>>
-  extends CollectionEntry<T> {
-  /**
-   * Rendered component. Falls back to a raw-markdown `<pre>` shell
-   * when MDX-compiling tools (`unified`, `remark-*`, `rehype-*`) are
-   * not installed — the wrapper always returns SOMETHING so callers
-   * don't have to branch on "is MDX tooling present".
-   */
-  Component: () => unknown;
-  /** Rendered HTML string (only populated when MDX tooling is available). */
-  html?: string;
-  /**
-   * Diagnostic info describing which pipeline produced `Component`.
-   *
-   *   - `"unified"`  — the full `unified + remark + rehype` chain ran.
-   *     `html` is populated, `Component` wraps it via
-   *     `dangerouslySetInnerHTML`.
-   *   - `"fallback-missing-deps"` — one or more optional MDX deps were
-   *     absent. `Component` returns a `<pre>` shell.
-   *   - `"fallback-pipeline-error"` — deps loaded but the pipeline
-   *     threw; `Component` returns a `<pre>` shell with `error` set.
-   */
-  compilationMode: "unified" | "fallback-missing-deps" | "fallback-pipeline-error";
-  /** The pipeline error when `compilationMode === "fallback-pipeline-error"`. */
-  error?: Error;
-}
-
-/**
- * Compile-time options forwarded to `getCompiled()`. All fields are
- * optional; supplying any of the `*Plugins` arrays triggers the
- * `unified + remark-parse + remark-rehype + rehype-stringify` pipeline
- * (when the deps are installed).
- *
- * The plugins arrays are typed as `unknown[]` because the optional MDX
- * ecosystem does not carry types into `@mandujs/core`. Consumers pass
- * whatever their plugin entry exports — typically a function or a
- * `[plugin, options]` tuple.
- */
-export interface CompileOptions {
-  /** Extra remark plugins applied BEFORE `remark-rehype`. */
-  remarkPlugins?: unknown[];
-  /** Extra rehype plugins applied AFTER `remark-rehype`. */
-  rehypePlugins?: unknown[];
-  /**
-   * When true, suppress the warning emitted when optional MDX deps
-   * are missing and the function falls back to a `<pre>` shell.
-   * Use this in build scripts where you deliberately do not install
-   * the MDX toolchain. Default: false.
-   */
-  silent?: boolean;
-}
-
-/**
- * Callback invoked by `Collection.watch()` on every filesystem event
- * that could affect the collection. The handler is called with a
- * shallow describe object so consumers can decide whether to
- * `collection.invalidate()` and re-render, or skip (e.g. when the
- * event targets a file outside the `extensions` allow-list).
- *
- * The watcher intentionally does NOT call `invalidate()` itself —
- * callers typically know when to force a reload (debounce, batch with
- * other changes) and the library staying hands-off matches how
- * `chokidar`-style APIs behave in the wild.
- */
-export type CollectionWatchHandler = (event: {
-  type: "change" | "rename";
-  filePath: string;
-}) => void;
-
-/** Control handle returned by `Collection.watch()`. */
-export interface CollectionWatchHandle {
-  /** Stop listening to this watcher. Idempotent. */
-  unsubscribe(): void;
-}
-
-/**
- * Compare function for sorting `CollectionEntry` instances. Matches the
- * TS `Array.sort` signature so users can compose their own comparators.
- */
-export type CollectionSort<T> = (
-  a: CollectionEntry<T>,
-  b: CollectionEntry<T>
-) => number;
-
-/**
- * Options accepted by the MVP `defineCollection({ path, ... })` form.
- */
-export interface DefineCollectionOptions<T> {
-  /**
-   * Directory (relative to the project root, unless absolute) that
-   * holds the collection's source files. Glob patterns are NOT
-   * supported at the MVP — use one collection per directory. The
-   * collection scans this directory recursively for markdown files.
-   */
-  path: string;
-  /**
-   * Zod schema for frontmatter validation. When omitted, entries are
-   * returned with `data: Record<string, unknown>` and no type safety
-   * — useful for prototypes before the shape stabilizes.
-   */
-  schema?: ZodSchema<T>;
-  /**
-   * File extensions to include (default: `.md`, `.mdx`, `.markdown`).
-   * Caller values should include the leading dot.
-   */
-  extensions?: string[];
-  /**
-   * Override slug generation. Receives the collection-relative path
-   * (forward slashes) and the parsed frontmatter so authors can force
-   * a specific slug via `slug:` in frontmatter, fall back to `title`,
-   * etc. Return the resolved slug string.
-   */
-  slug?: (entry: {
-    path: string;
-    data: Record<string, unknown>;
-  }) => string;
-  /**
-   * Slug normalization options (forwarded to `slugFromPath`) for the
-   * default slug generator. Ignored when a custom `slug` callback is
-   * provided.
-   */
-  slugOptions?: SlugFromPathOptions;
-  /**
-   * Default sort applied by `.all()`. The framework applies a stable
-   * fallback-by-slug tiebreaker on top of whatever the caller returns
-   * so repeated loads always yield the same order. When absent, the
-   * collection sorts by `data.order` ascending (missing = +Infinity),
-   * then by slug alphabetical — matching the `generateSidebar`
-   * helper's default.
-   */
-  sort?: CollectionSort<T>;
-  /**
-   * Project root override. Normally the Collection resolves `path`
-   * against `process.cwd()` lazily at `.load()` time; passing this
-   * pins the root for tests or tooling contexts where cwd is unstable.
-   */
-  root?: string;
-}
-
-/** Legacy config shape — preserved to avoid churn on existing projects. */
-interface LegacyCollectionConfig {
-  loader: unknown;
-  schema?: unknown;
-}
-
-const DEFAULT_EXTENSIONS = [".md", ".mdx", ".markdown"] as const;
-
-/**
- * Collection instance returned by `defineCollection({ path, ... })`.
- *
- * # Caching
- *
- * Load results are cached in-memory after the first `.load()` call.
- * This is intentional — at the MVP we treat collections as build-time
- * data that doesn't change within a process lifetime. Call
- * `.invalidate()` to force a rescan.
- *
- * # Watcher lifecycle (Issue #204 — critical)
- *
- * **Default: zero watchers.** `all()`, `get()`, and `getCompiled()`
- * do NOT open any `fs.watch` handle. Build scripts like
- * `scripts/prebuild-docs.ts` can run `await docs.all()` and the
- * process will exit cleanly — no active handles left to pin the
- * event loop.
- *
- * **Opt-in via `watch()`**: dev-mode tooling that wants change
- * notifications calls `const handle = collection.watch(cb)`. This
- * opens ONE `fs.watch` handle per collection (not per file), so the
- * cost is bounded regardless of collection size.
- *
- * **Cleanup**: user code either calls `handle.unsubscribe()` or
- * `await collection[Symbol.asyncDispose]()` (ES2023 `using`
- * semantics). Either path closes every open watcher so the process
- * exits.
- */
-export class Collection<T = Record<string, unknown>> {
-  readonly options: DefineCollectionOptions<T>;
-  private entries: CollectionEntry<T>[] | null = null;
-  private loadPromise: Promise<CollectionEntry<T>[]> | null = null;
-  /**
-   * Active `fs.watch` handles — one per `watch()` call. Stored so
-   * `dispose()` can close every handle regardless of whether the
-   * user tracked the returned `unsubscribe` callback.
-   */
-  private watchHandles: Set<{ close: () => void }> = new Set();
-
-  constructor(options: DefineCollectionOptions<T>) {
-    this.options = options;
-  }
-
-  /** Resolve the collection root directory. */
-  private resolveRoot(): string {
-    const root = this.options.root ?? process.cwd();
-    if (path.isAbsolute(this.options.path)) return this.options.path;
-    return path.resolve(root, this.options.path);
-  }
-
-  /**
-   * Scan the collection directory, parse frontmatter, validate with
-   * the Zod schema, and cache entries. Safe to call repeatedly — the
-   * first call's promise is reused by concurrent callers, so a burst
-   * of `.all()` / `.get()` calls during initial render won't produce
-   * redundant disk I/O.
-   */
-  async load(): Promise<CollectionEntry<T>[]> {
-    if (this.entries) return this.entries;
-    if (this.loadPromise) return this.loadPromise;
-    this.loadPromise = this.doLoad();
-    try {
-      this.entries = await this.loadPromise;
-      return this.entries;
-    } finally {
-      this.loadPromise = null;
-    }
-  }
-
-  private async doLoad(): Promise<CollectionEntry<T>[]> {
-    const root = this.resolveRoot();
-    if (!fs.existsSync(root)) {
-      // An empty collection is a valid state — authors might scaffold
-      // the directory before adding entries. Returning `[]` here lets
-      // pages render with "no content yet" messaging instead of 500.
-      return [];
-    }
-    const extensions = this.options.extensions ?? [...DEFAULT_EXTENSIONS];
-    const extSet = new Set(extensions.map((e) => e.toLowerCase()));
-    const absPaths: string[] = [];
-    walkDir(root, absPaths, extSet);
-
-    const entries: CollectionEntry<T>[] = [];
-    for (const absPath of absPaths) {
-      const relPath = path
-        .relative(root, absPath)
-        .replace(/\\/g, "/");
-      const src = fs.readFileSync(absPath, "utf8");
-      let parsed;
-      try {
-        parsed = parseFrontmatter(src);
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        throw new Error(
-          `[content] failed to parse frontmatter in ${relPath}: ${msg}`
-        );
-      }
-      // Derive slug via the user's override or the built-in kebab-case
-      // generator. We pass the parsed frontmatter in so authors can
-      // honor a `slug:` field without writing their own loader.
-      const rawSlug = this.options.slug
-        ? this.options.slug({ path: relPath, data: parsed.data })
-        : typeof parsed.data.slug === "string" && parsed.data.slug.length > 0
-          ? String(parsed.data.slug)
-          : slugFromPath(relPath, this.options.slugOptions);
-
-      let data = parsed.data as unknown as T;
-      if (this.options.schema) {
-        const result = this.options.schema.safeParse(parsed.data);
-        if (!result.success) {
-          throw new Error(
-            `[content] schema validation failed for ${relPath}: ${formatZodError(
-              result.error
-            )}`
-          );
-        }
-        data = result.data;
-      }
-      entries.push({
-        slug: rawSlug,
-        filePath: absPath,
-        data,
-        content: parsed.body,
-      });
-    }
-
-    const sorter = this.options.sort ?? defaultSort<T>();
-    // Stable sort by applying a slug tiebreaker AFTER the user sort.
-    // Node's Array.sort is stable as of V8 7.0+ (Bun uses V8), but we
-    // prefer not to rely on user comparators returning 0 for
-    // equivalent entries, so we fold the tiebreaker into the key.
-    entries.sort((a, b) => {
-      const primary = sorter(a, b);
-      if (primary !== 0) return primary;
-      return a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0;
-    });
-    return entries;
-  }
-
-  /** Return all entries (cached). */
-  async all(): Promise<CollectionEntry<T>[]> {
-    return this.load();
-  }
-
-  /** Retrieve a single entry by slug, or undefined. */
-  async get(slug: string): Promise<CollectionEntry<T> | undefined> {
-    const entries = await this.load();
-    return entries.find((e) => e.slug === slug);
-  }
-
-  /**
-   * Return an entry with a lazy-rendered React component.
-   *
-   * When optional MDX tooling (`unified`, `remark-parse`, `remark-rehype`,
-   * `rehype-stringify`) is present in the user's deps, we pipe the body
-   * through it and return both the raw HTML and a React component that
-   * renders via `dangerouslySetInnerHTML` (safe because the source is
-   * build-time content the project controls). When tooling is absent,
-   * `Component` still returns a valid React element — a `<pre>` wrapper
-   * around the raw markdown — so callers never have to branch on the
-   * missing-dep case.
-   *
-   * # Plugin support (Issue #205)
-   *
-   * Pass `{ remarkPlugins, rehypePlugins }` to extend the pipeline
-   * — e.g. `rehype-slug`, `rehype-autolink-headings`, `shiki` for
-   * syntax highlighting. Plugins are applied in array order, remark
-   * plugins before `remark-rehype` and rehype plugins after.
-   *
-   * # Diagnostics (Issue #205)
-   *
-   * The returned entry includes a `compilationMode` discriminator
-   * so callers can tell whether the full pipeline ran or the fallback
-   * was used. When a dep is missing we emit a single-line warning
-   * (unless `silent: true`) naming which module could not be
-   * resolved — previously the fallback was silent, which made it
-   * impossible to diagnose why a `<pre>` appeared.
-   */
-  async getCompiled(
-    slug: string,
-    compileOptions: CompileOptions = {}
-  ): Promise<CompiledCollectionEntry<T> | undefined> {
-    const entry = await this.get(slug);
-    if (!entry) return undefined;
-    const rendered = await renderMarkdownSafe(entry.content, compileOptions);
-    const compiled: CompiledCollectionEntry<T> = {
-      ...entry,
-      Component: rendered.Component,
-      compilationMode: rendered.mode,
-    };
-    if (rendered.html !== undefined) compiled.html = rendered.html;
-    if (rendered.error !== undefined) compiled.error = rendered.error;
-    return compiled;
-  }
-
-  /**
-   * Reset the in-memory cache so the next `.load()` rescans disk.
-   * Used by tests and (eventually) the dev-mode file watcher.
-   */
-  invalidate(): void {
-    this.entries = null;
-  }
-
-  /**
-   * Subscribe to filesystem events for this collection's root
-   * directory. The watcher is lazy — created here, not in the
-   * constructor — so callers who never call `watch()` pay no cost
-   * and their process exits cleanly after `all()`.
-   *
-   * The callback is invoked with a `{ type, filePath }` object
-   * where `filePath` is relative to the collection root. The
-   * caller typically calls `collection.invalidate()` in response
-   * and re-renders.
-   *
-   * Returns a handle with `unsubscribe()`. You can call that
-   * directly, or call `collection.dispose()` / use `await using`
-   * (ES2023) to close every watcher at once.
-   */
-  watch(handler: CollectionWatchHandler): CollectionWatchHandle {
-    const root = this.resolveRoot();
-    if (!fs.existsSync(root)) {
-      // Nothing to watch — return a no-op handle so callers don't
-      // have to branch on "directory exists". If the directory
-      // appears later, they can unsubscribe and re-watch.
-      return { unsubscribe: () => {} };
-    }
-    const extensions = this.options.extensions ?? [...DEFAULT_EXTENSIONS];
-    const extSet = new Set(extensions.map((e) => e.toLowerCase()));
-
-    // Use node's `fs.watch` directly — one handle per collection
-    // root. `recursive: true` is the expensive bit; it is not
-    // supported on Linux before kernel 5.0 but the dev-mode path
-    // targets macOS/Windows/recent Linux where it works. If a
-    // project needs stricter compatibility, they can wrap
-    // `chokidar` in user code and call `invalidate()` themselves.
-    let watcher: fs.FSWatcher;
-    try {
-      watcher = fs.watch(root, { recursive: true }, (eventType, filename) => {
-        if (!filename) return;
-        const normalized = String(filename).replace(/\\/g, "/");
-        // Filter by extension so unrelated files don't fire the
-        // callback. We still let the event propagate for rename
-        // events on directories (no extension) — those can affect
-        // slugs.
-        const lastDot = normalized.lastIndexOf(".");
-        const ext = lastDot >= 0 ? normalized.slice(lastDot).toLowerCase() : "";
-        if (ext && !extSet.has(ext)) return;
-        try {
-          handler({
-            type: eventType === "rename" ? "rename" : "change",
-            filePath: normalized,
-          });
-        } catch (err) {
-          // Swallow user-handler errors so one buggy consumer
-          // does not tear down the watcher for everyone else.
-          console.error(
-            `[content] watch handler threw for ${normalized}:`,
-            err instanceof Error ? err.message : err
-          );
-        }
-      });
-    } catch (err) {
-      // Some platforms (notably older Linux) don't support
-      // `recursive: true`. Log once and return a no-op handle so
-      // the caller's code continues — missing-reload is
-      // degradation, not breakage.
-      console.warn(
-        `[content] fs.watch(${root}) failed — hot reload disabled for this collection:`,
-        err instanceof Error ? err.message : err
-      );
-      return { unsubscribe: () => {} };
-    }
-
-    const entry = { close: () => watcher.close() };
-    this.watchHandles.add(entry);
-
-    return {
-      unsubscribe: () => {
-        if (!this.watchHandles.has(entry)) return;
-        this.watchHandles.delete(entry);
-        try {
-          watcher.close();
-        } catch {
-          // Already closed — ignore.
-        }
-      },
-    };
-  }
-
-  /**
-   * Close every active watcher opened by `.watch()`. Safe to call
-   * repeatedly. After `dispose()` the collection remains usable
-   * — calling `watch()` again creates a fresh handle.
-   */
-  dispose(): void {
-    for (const handle of this.watchHandles) {
-      try {
-        handle.close();
-      } catch {
-        // Handle already closed — ignore.
-      }
-    }
-    this.watchHandles.clear();
-  }
-
-  /**
-   * ES2023 async-dispose support. Enables:
-   *
-   *   ```ts
-   *   await using docs = defineCollection({ path: 'content/docs' });
-   *   const unsubscribe = docs.watch(onChange);
-   *   // ... work ...
-   *   // docs[Symbol.asyncDispose]() runs automatically at scope exit
-   *   ```
-   *
-   * The async variant is used (instead of sync `Symbol.dispose`)
-   * because real watchers in the ecosystem close asynchronously
-   * — we keep the signature future-proof even though `fs.watch`
-   * happens to close synchronously today.
-   */
-  async [Symbol.asyncDispose](): Promise<void> {
-    this.dispose();
-  }
-}
-
-/**
- * Default comparator: `data.order` ascending, with missing order
- * treated as infinity so numbered entries sink to the top.
- */
-function defaultSort<T>(): CollectionSort<T> {
-  return (a, b) => {
-    const oa = (a.data as { order?: unknown })?.order;
-    const ob = (b.data as { order?: unknown })?.order;
-    const na = typeof oa === "number" ? oa : Number.POSITIVE_INFINITY;
-    const nb = typeof ob === "number" ? ob : Number.POSITIVE_INFINITY;
-    if (na !== nb) return na - nb;
-    return 0;
-  };
-}
-
-/**
- * Compact a Zod error into a single line suitable for the error
- * messages surfaced by `Collection.load()`. We deliberately avoid
- * `z.prettifyError` (not present in Zod 3) and the flattener —
- * `issue.path` + `issue.message` is enough for docs authors to
- * locate the broken field fast.
- */
-function formatZodError(error: {
-  issues: Array<{ path: (string | number)[]; message: string }>;
-}): string {
-  return error.issues
-    .map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`)
-    .join("; ");
-}
-
-/**
- * Synchronous recursive directory walker — the collection typically
- * has a bounded number of entries (dozens to low thousands) so the
- * sync cost is negligible, and using sync simplifies error paths
- * and the cache-hit fast-path in `load()`.
- */
-function walkDir(dir: string, out: string[], extSet: Set<string>): void {
-  let entries: fs.Dirent[];
-  try {
-    entries = fs.readdirSync(dir, { withFileTypes: true });
-  } catch {
-    return;
-  }
-  for (const entry of entries) {
-    const absPath = path.join(dir, entry.name);
-    if (entry.isDirectory()) {
-      walkDir(absPath, out, extSet);
-      continue;
-    }
-    if (!entry.isFile()) continue;
-    const ext = path.extname(entry.name).toLowerCase();
-    if (!extSet.has(ext)) continue;
-    out.push(absPath);
-  }
-}
-
-/** Internal result type from `renderMarkdownSafe`. */
-interface RenderedMarkdown {
-  html?: string;
-  Component: () => unknown;
-  mode: CompiledCollectionEntry<unknown>["compilationMode"];
-  error?: Error;
-}
-
-/**
- * Lazy markdown renderer. Attempts to load `unified` + the standard
- * remark/rehype plugin chain; when any piece is missing, falls back
- * to returning a `<pre>` shell so the caller gets a stable API.
- *
- * We go through `Function("return import(...)")` instead of a direct
- * dynamic `import()` so TS doesn't resolve the optional modules
- * during typecheck — they are NOT in `@mandujs/core` deps by design.
- *
- * The `options.remarkPlugins` / `options.rehypePlugins` arrays let
- * docs sites add `rehype-slug`, `rehype-autolink-headings`, `shiki`,
- * etc. — the caller is responsible for installing those modules.
- */
-async function renderMarkdownSafe(
-  body: string,
-  options: CompileOptions = {}
-): Promise<RenderedMarkdown> {
-  const { remarkPlugins = [], rehypePlugins = [], silent = false } = options;
-
-  // Passing the module specifier through a Function-wrapped dynamic
-  // import keeps TypeScript from erroring on optional peer deps; if
-  // any module is missing we fall through to the raw-markdown path.
-  const tryImport = async (id: string): Promise<unknown> => {
-    try {
-      return await (Function("x", "return import(x)") as (x: string) => Promise<unknown>)(id);
-    } catch {
-      return null;
-    }
-  };
-
-  const unified = (await tryImport("unified")) as
-    | { unified: () => unknown }
-    | null;
-  const remarkParse = (await tryImport("remark-parse")) as
-    | { default: unknown }
-    | null;
-  const remarkRehype = (await tryImport("remark-rehype")) as
-    | { default: unknown }
-    | null;
-  const rehypeStringify = (await tryImport("rehype-stringify")) as
-    | { default: unknown }
-    | null;
-
-  // Collect the names of missing modules so the warning is
-  // actionable — a generic "MDX tooling not installed" is hard to
-  // act on when you DO have some of it installed.
-  const missing: string[] = [];
-  if (!unified) missing.push("unified");
-  if (!remarkParse) missing.push("remark-parse");
-  if (!remarkRehype) missing.push("remark-rehype");
-  if (!rehypeStringify) missing.push("rehype-stringify");
-
-  if (missing.length === 0 && unified && remarkParse && remarkRehype && rehypeStringify) {
-    try {
-      type Processor = {
-        use: (plugin: unknown, options?: unknown) => Processor;
-        process: (src: string) => Promise<{ toString: () => string }>;
-      };
-      // Type-punned unified chain — optional peer deps don't carry
-      // their own types into our graph, so we route through `unknown`.
-      let chain = unified.unified() as unknown as Processor;
-      chain = chain.use(remarkParse.default);
-      // User-supplied remark plugins run between `remark-parse`
-      // and `remark-rehype` so they can transform the MDAST.
-      for (const plugin of remarkPlugins) {
-        chain = applyPlugin(chain, plugin);
-      }
-      chain = chain.use(remarkRehype.default);
-      // Rehype plugins run AFTER `remark-rehype` so they see the
-      // HAST — this is the hook point for `rehype-slug` etc.
-      for (const plugin of rehypePlugins) {
-        chain = applyPlugin(chain, plugin);
-      }
-      chain = chain.use(rehypeStringify.default);
-      const file = await chain.process(body);
-      const html = file.toString();
-      return {
-        html,
-        Component: () => createHtmlElement(html),
-        mode: "unified",
-      };
-    } catch (err) {
-      // Pipeline itself threw — report it so the caller sees the
-      // underlying failure instead of a silent `<pre>`.
-      if (!silent) {
-        console.warn(
-          "[content] MDX pipeline failed; falling back to <pre>. Underlying error:",
-          err instanceof Error ? err.message : err
-        );
-      }
-      return {
-        Component: () => createPreElement(body),
-        mode: "fallback-pipeline-error",
-        error: err instanceof Error ? err : new Error(String(err)),
-      };
-    }
-  }
-
-  // Fallback: emit a simple React element wrapping the raw body in a
-  // `<pre>` so pages don't 500. Pages that need real MDX should
-  // install `unified` + remark/rehype in their project.
-  if (!silent && missing.length > 0) {
-    // One warning per call — if the project is rendering 500 pages
-    // this will be noisy, but that noise is the feedback users
-    // need to know WHY their markdown is not compiling. `silent:
-    // true` mutes this for build scripts that deliberately opt out.
-    console.warn(
-      `[content] MDX tooling missing: ${missing.join(
-        ", "
-      )}. Install these peer deps to enable full rendering — falling back to <pre> shell.`
-    );
-  }
-  return {
-    Component: () => createPreElement(body),
-    mode: "fallback-missing-deps",
-  };
-}
-
-/**
- * Apply a plugin spec to a unified chain. The unified plugin
- * ecosystem accepts either a bare function or a `[plugin, options]`
- * tuple, so we handle both without pulling the unified types in.
- */
-function applyPlugin<P extends { use: (plugin: unknown, options?: unknown) => P }>(
-  chain: P,
-  plugin: unknown
-): P {
-  if (Array.isArray(plugin)) {
-    const [fn, ...rest] = plugin;
-    return chain.use(fn, ...rest);
-  }
-  return chain.use(plugin);
-}
-
-/**
- * Build a lightweight React element carrying HTML content. We avoid
- * importing React directly so `@mandujs/core/content` stays
- * React-free at import time — the returned value is the plain React
- * element shape (`{ type, props, key }`) which matches what
- * `React.createElement('div', { dangerouslySetInnerHTML: ... })`
- * produces. If the project hosts a React version that uses a
- * different shape, users can swap to their own compiler.
- */
-function createHtmlElement(html: string): unknown {
-  return {
-    type: "div",
-    props: {
-      dangerouslySetInnerHTML: { __html: html },
-    },
-    key: null,
-    // React 19 uses a $$typeof symbol to distinguish elements —
-    // stamp it so React.isValidElement() accepts us.
-    $$typeof: Symbol.for("react.element"),
-    ref: null,
-  };
-}
-
-function createPreElement(body: string): unknown {
-  return {
-    type: "pre",
-    props: { children: body },
-    key: null,
-    $$typeof: Symbol.for("react.element"),
-    ref: null,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// defineCollection overloads
-// ---------------------------------------------------------------------------
-
-/**
- * Legacy signature — pass-through for projects using the existing
- * ContentLayer (`{ loader, schema }`). We detect the shape at runtime
- * and return the config unchanged so downstream
- * `defineContentConfig({ collections: { ... } })` keeps working.
- */
-export function defineCollection<T extends LegacyCollectionConfig>(
-  config: T
-): T;
-
-/**
- * MVP signature — create a typed `Collection` from a directory path
- * and optional Zod schema.
- */
-export function defineCollection<T>(
-  options: DefineCollectionOptions<T>
-): Collection<T>;
-
-export function defineCollection(
-  config: LegacyCollectionConfig | DefineCollectionOptions<unknown>
-): unknown {
-  // Disambiguate by the presence of a `loader` property — the legacy
-  // config always has one, the MVP config never does. Passing both
-  // throws so the error points to the conflict rather than letting
-  // one branch silently win.
-  if (isLegacyConfig(config)) {
-    if ("path" in config) {
-      throw new Error(
-        "[defineCollection] config has both `loader` and `path`; pick one — the legacy ContentLayer uses `loader`, the MVP Collection API uses `path`."
-      );
-    }
-    return config;
-  }
-  return new Collection(config as DefineCollectionOptions<unknown>);
-}
-
-function isLegacyConfig(
-  cfg: LegacyCollectionConfig | DefineCollectionOptions<unknown>
-): cfg is LegacyCollectionConfig {
-  return typeof cfg === "object" && cfg !== null && "loader" in cfg;
-}
+/**
+ * Collection API (Issue #199)
+ *
+ * First-class content collection primitive inspired by Astro's
+ * `astro:content` + Next.js `@next/mdx` + Fumadocs. Projects declare
+ * collections once in `content.config.ts`, then read them anywhere
+ * with full typed autocomplete:
+ *
+ * ```ts
+ * // content.config.ts
+ * import { defineCollection, z } from '@mandujs/core/content';
+ *
+ * export const docs = defineCollection({
+ *   path: 'content/docs',
+ *   schema: z.object({
+ *     title: z.string(),
+ *     order: z.number().optional(),
+ *     draft: z.boolean().default(false),
+ *   }),
+ * });
+ * ```
+ *
+ * ```ts
+ * // anywhere in the app
+ * import { docs } from './content.config';
+ *
+ * const entries = await docs.all();
+ * const intro = await docs.get('intro');
+ * ```
+ *
+ * # Overload compatibility
+ *
+ * The legacy `defineCollection({ loader, schema })` shape (used by the
+ * existing ContentLayer in `content-layer.ts`) is still supported — we
+ * detect the shape at runtime and pass config through unchanged. Only
+ * the NEW `{ path, schema, ... }` shape returns a `Collection` instance
+ * with `.load()/.all()/.get()/.getCompiled()`. This matters because the
+ * CLI `mandu collection create` scaffolder already emits the legacy
+ * shape, and breaking those projects on a minor version is not an
+ * option for the MVP.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import type { ZodSchema } from "zod";
+import { parseFrontmatter } from "./frontmatter";
+import { slugFromPath, type SlugFromPathOptions } from "./slug";
+
+/** A single entry in a Collection after frontmatter + Zod validation. */
+export interface CollectionEntry<T = Record<string, unknown>> {
+  /** URL-safe slug derived from the file path (see `slugFromPath`). */
+  slug: string;
+  /** Absolute filesystem path of the source file. */
+  filePath: string;
+  /** Validated frontmatter data. */
+  data: T;
+  /** Raw markdown/MDX body (everything after the closing `---`). */
+  content: string;
+}
+
+/** A compiled MDX entry with a lazy-rendered React component. */
+export interface CompiledCollectionEntry<T = Record<string, unknown>>
+  extends CollectionEntry<T> {
+  /**
+   * Rendered component. Falls back to a raw-markdown `<pre>` shell
+   * when MDX-compiling tools (`unified`, `remark-*`, `rehype-*`) are
+   * not installed — the wrapper always returns SOMETHING so callers
+   * don't have to branch on "is MDX tooling present".
+   */
+  Component: () => unknown;
+  /** Rendered HTML string (only populated when MDX tooling is available). */
+  html?: string;
+  /**
+   * Diagnostic info describing which pipeline produced `Component`.
+   *
+   *   - `"unified"`  — the full `unified + remark + rehype` chain ran.
+   *     `html` is populated, `Component` wraps it via
+   *     `dangerouslySetInnerHTML`.
+   *   - `"fallback-missing-deps"` — one or more optional MDX deps were
+   *     absent. `Component` returns a `<pre>` shell.
+   *   - `"fallback-pipeline-error"` — deps loaded but the pipeline
+   *     threw; `Component` returns a `<pre>` shell with `error` set.
+   */
+  compilationMode: "unified" | "fallback-missing-deps" | "fallback-pipeline-error";
+  /** The pipeline error when `compilationMode === "fallback-pipeline-error"`. */
+  error?: Error;
+}
+
+/**
+ * Compile-time options forwarded to `getCompiled()`. All fields are
+ * optional; supplying any of the `*Plugins` arrays triggers the
+ * `unified + remark-parse + remark-rehype + rehype-stringify` pipeline
+ * (when the deps are installed).
+ *
+ * The plugins arrays are typed as `unknown[]` because the optional MDX
+ * ecosystem does not carry types into `@mandujs/core`. Consumers pass
+ * whatever their plugin entry exports — typically a function or a
+ * `[plugin, options]` tuple.
+ */
+export interface CompileOptions {
+  /** Extra remark plugins applied BEFORE `remark-rehype`. */
+  remarkPlugins?: unknown[];
+  /** Extra rehype plugins applied AFTER `remark-rehype`. */
+  rehypePlugins?: unknown[];
+  /**
+   * When true, suppress the warning emitted when optional MDX deps
+   * are missing and the function falls back to a `<pre>` shell.
+   * Use this in build scripts where you deliberately do not install
+   * the MDX toolchain. Default: false.
+   */
+  silent?: boolean;
+}
+
+/**
+ * Callback invoked by `Collection.watch()` on every filesystem event
+ * that could affect the collection. The handler is called with a
+ * shallow describe object so consumers can decide whether to
+ * `collection.invalidate()` and re-render, or skip (e.g. when the
+ * event targets a file outside the `extensions` allow-list).
+ *
+ * The watcher intentionally does NOT call `invalidate()` itself —
+ * callers typically know when to force a reload (debounce, batch with
+ * other changes) and the library staying hands-off matches how
+ * `chokidar`-style APIs behave in the wild.
+ */
+export type CollectionWatchHandler = (event: {
+  type: "change" | "rename";
+  filePath: string;
+}) => void;
+
+/** Control handle returned by `Collection.watch()`. */
+export interface CollectionWatchHandle {
+  /** Stop listening to this watcher. Idempotent. */
+  unsubscribe(): void;
+}
+
+/**
+ * Compare function for sorting `CollectionEntry` instances. Matches the
+ * TS `Array.sort` signature so users can compose their own comparators.
+ */
+export type CollectionSort<T> = (
+  a: CollectionEntry<T>,
+  b: CollectionEntry<T>
+) => number;
+
+/**
+ * Options accepted by the MVP `defineCollection({ path, ... })` form.
+ */
+export interface DefineCollectionOptions<T> {
+  /**
+   * Directory (relative to the project root, unless absolute) that
+   * holds the collection's source files. Glob patterns are NOT
+   * supported at the MVP — use one collection per directory. The
+   * collection scans this directory recursively for markdown files.
+   */
+  path: string;
+  /**
+   * Zod schema for frontmatter validation. When omitted, entries are
+   * returned with `data: Record<string, unknown>` and no type safety
+   * — useful for prototypes before the shape stabilizes.
+   */
+  schema?: ZodSchema<T>;
+  /**
+   * File extensions to include (default: `.md`, `.mdx`, `.markdown`).
+   * Caller values should include the leading dot.
+   */
+  extensions?: string[];
+  /**
+   * Override slug generation. Receives the collection-relative path
+   * (forward slashes) and the parsed frontmatter so authors can force
+   * a specific slug via `slug:` in frontmatter, fall back to `title`,
+   * etc. Return the resolved slug string.
+   */
+  slug?: (entry: {
+    path: string;
+    data: Record<string, unknown>;
+  }) => string;
+  /**
+   * Slug normalization options (forwarded to `slugFromPath`) for the
+   * default slug generator. Ignored when a custom `slug` callback is
+   * provided.
+   */
+  slugOptions?: SlugFromPathOptions;
+  /**
+   * Default sort applied by `.all()`. The framework applies a stable
+   * fallback-by-slug tiebreaker on top of whatever the caller returns
+   * so repeated loads always yield the same order. When absent, the
+   * collection sorts by `data.order` ascending (missing = +Infinity),
+   * then by slug alphabetical — matching the `generateSidebar`
+   * helper's default.
+   */
+  sort?: CollectionSort<T>;
+  /**
+   * Project root override. Normally the Collection resolves `path`
+   * against `process.cwd()` lazily at `.load()` time; passing this
+   * pins the root for tests or tooling contexts where cwd is unstable.
+   */
+  root?: string;
+}
+
+/** Legacy config shape — preserved to avoid churn on existing projects. */
+interface LegacyCollectionConfig {
+  loader: unknown;
+  schema?: unknown;
+}
+
+const DEFAULT_EXTENSIONS = [".md", ".mdx", ".markdown"] as const;
+
+/**
+ * Collection instance returned by `defineCollection({ path, ... })`.
+ *
+ * # Caching
+ *
+ * Load results are cached in-memory after the first `.load()` call.
+ * This is intentional — at the MVP we treat collections as build-time
+ * data that doesn't change within a process lifetime. Call
+ * `.invalidate()` to force a rescan.
+ *
+ * # Watcher lifecycle (Issue #204 — critical)
+ *
+ * **Default: zero watchers.** `all()`, `get()`, and `getCompiled()`
+ * do NOT open any `fs.watch` handle. Build scripts like
+ * `scripts/prebuild-docs.ts` can run `await docs.all()` and the
+ * process will exit cleanly — no active handles left to pin the
+ * event loop.
+ *
+ * **Opt-in via `watch()`**: dev-mode tooling that wants change
+ * notifications calls `const handle = collection.watch(cb)`. This
+ * opens ONE `fs.watch` handle per collection (not per file), so the
+ * cost is bounded regardless of collection size.
+ *
+ * **Cleanup**: user code either calls `handle.unsubscribe()` or
+ * `await collection[Symbol.asyncDispose]()` (ES2023 `using`
+ * semantics). Either path closes every open watcher so the process
+ * exits.
+ */
+export class Collection<T = Record<string, unknown>> {
+  readonly options: DefineCollectionOptions<T>;
+  private entries: CollectionEntry<T>[] | null = null;
+  private loadPromise: Promise<CollectionEntry<T>[]> | null = null;
+  /**
+   * Active `fs.watch` handles — one per `watch()` call. Stored so
+   * `dispose()` can close every handle regardless of whether the
+   * user tracked the returned `unsubscribe` callback.
+   */
+  private watchHandles: Set<{ close: () => void }> = new Set();
+
+  constructor(options: DefineCollectionOptions<T>) {
+    this.options = options;
+    // Register so dev-mode tooling (`getRegisteredCollections()` + the
+    // bundler's content watcher) can invalidate every collection on a
+    // filesystem add/unlink without each project wiring `.watch()` by
+    // hand. The set is module-scoped; every Collection constructed in
+    // this process joins automatically.
+    collectionRegistry.add(this as Collection<unknown>);
+  }
+
+  /** Resolve the collection root directory. */
+  private resolveRoot(): string {
+    const root = this.options.root ?? process.cwd();
+    if (path.isAbsolute(this.options.path)) return this.options.path;
+    return path.resolve(root, this.options.path);
+  }
+
+  /**
+   * Scan the collection directory, parse frontmatter, validate with
+   * the Zod schema, and cache entries. Safe to call repeatedly — the
+   * first call's promise is reused by concurrent callers, so a burst
+   * of `.all()` / `.get()` calls during initial render won't produce
+   * redundant disk I/O.
+   */
+  async load(): Promise<CollectionEntry<T>[]> {
+    if (this.entries) return this.entries;
+    if (this.loadPromise) return this.loadPromise;
+    this.loadPromise = this.doLoad();
+    try {
+      this.entries = await this.loadPromise;
+      return this.entries;
+    } finally {
+      this.loadPromise = null;
+    }
+  }
+
+  private async doLoad(): Promise<CollectionEntry<T>[]> {
+    const root = this.resolveRoot();
+    if (!fs.existsSync(root)) {
+      // An empty collection is a valid state — authors might scaffold
+      // the directory before adding entries. Returning `[]` here lets
+      // pages render with "no content yet" messaging instead of 500.
+      return [];
+    }
+    const extensions = this.options.extensions ?? [...DEFAULT_EXTENSIONS];
+    const extSet = new Set(extensions.map((e) => e.toLowerCase()));
+    const absPaths: string[] = [];
+    walkDir(root, absPaths, extSet);
+
+    const entries: CollectionEntry<T>[] = [];
+    for (const absPath of absPaths) {
+      const relPath = path
+        .relative(root, absPath)
+        .replace(/\\/g, "/");
+      const src = fs.readFileSync(absPath, "utf8");
+      let parsed;
+      try {
+        parsed = parseFrontmatter(src);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(
+          `[content] failed to parse frontmatter in ${relPath}: ${msg}`,
+          { cause: err }
+        );
+      }
+      // Derive slug via the user's override or the built-in kebab-case
+      // generator. We pass the parsed frontmatter in so authors can
+      // honor a `slug:` field without writing their own loader.
+      const rawSlug = this.options.slug
+        ? this.options.slug({ path: relPath, data: parsed.data })
+        : typeof parsed.data.slug === "string" && parsed.data.slug.length > 0
+          ? String(parsed.data.slug)
+          : slugFromPath(relPath, this.options.slugOptions);
+
+      let data = parsed.data as unknown as T;
+      if (this.options.schema) {
+        const result = this.options.schema.safeParse(parsed.data);
+        if (!result.success) {
+          throw new Error(
+            `[content] schema validation failed for ${relPath}: ${formatZodError(
+              result.error
+            )}`
+          );
+        }
+        data = result.data;
+      }
+      entries.push({
+        slug: rawSlug,
+        filePath: absPath,
+        data,
+        content: parsed.body,
+      });
+    }
+
+    const sorter = this.options.sort ?? defaultSort<T>();
+    // Stable sort by applying a slug tiebreaker AFTER the user sort.
+    // Node's Array.sort is stable as of V8 7.0+ (Bun uses V8), but we
+    // prefer not to rely on user comparators returning 0 for
+    // equivalent entries, so we fold the tiebreaker into the key.
+    entries.sort((a, b) => {
+      const primary = sorter(a, b);
+      if (primary !== 0) return primary;
+      return a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0;
+    });
+    return entries;
+  }
+
+  /** Return all entries (cached). */
+  async all(): Promise<CollectionEntry<T>[]> {
+    return this.load();
+  }
+
+  /** Retrieve a single entry by slug, or undefined. */
+  async get(slug: string): Promise<CollectionEntry<T> | undefined> {
+    const entries = await this.load();
+    return entries.find((e) => e.slug === slug);
+  }
+
+  /**
+   * Return an entry with a lazy-rendered React component.
+   *
+   * When optional MDX tooling (`unified`, `remark-parse`, `remark-rehype`,
+   * `rehype-stringify`) is present in the user's deps, we pipe the body
+   * through it and return both the raw HTML and a React component that
+   * renders via `dangerouslySetInnerHTML` (safe because the source is
+   * build-time content the project controls). When tooling is absent,
+   * `Component` still returns a valid React element — a `<pre>` wrapper
+   * around the raw markdown — so callers never have to branch on the
+   * missing-dep case.
+   *
+   * # Plugin support (Issue #205)
+   *
+   * Pass `{ remarkPlugins, rehypePlugins }` to extend the pipeline
+   * — e.g. `rehype-slug`, `rehype-autolink-headings`, `shiki` for
+   * syntax highlighting. Plugins are applied in array order, remark
+   * plugins before `remark-rehype` and rehype plugins after.
+   *
+   * # Diagnostics (Issue #205)
+   *
+   * The returned entry includes a `compilationMode` discriminator
+   * so callers can tell whether the full pipeline ran or the fallback
+   * was used. When a dep is missing we emit a single-line warning
+   * (unless `silent: true`) naming which module could not be
+   * resolved — previously the fallback was silent, which made it
+   * impossible to diagnose why a `<pre>` appeared.
+   */
+  async getCompiled(
+    slug: string,
+    compileOptions: CompileOptions = {}
+  ): Promise<CompiledCollectionEntry<T> | undefined> {
+    const entry = await this.get(slug);
+    if (!entry) return undefined;
+    const rendered = await renderMarkdownSafe(entry.content, compileOptions);
+    const compiled: CompiledCollectionEntry<T> = {
+      ...entry,
+      Component: rendered.Component,
+      compilationMode: rendered.mode,
+    };
+    if (rendered.html !== undefined) compiled.html = rendered.html;
+    if (rendered.error !== undefined) compiled.error = rendered.error;
+    return compiled;
+  }
+
+  /**
+   * Reset the in-memory cache so the next `.load()` rescans disk.
+   * Used by tests and (eventually) the dev-mode file watcher.
+   */
+  invalidate(): void {
+    this.entries = null;
+  }
+
+  /**
+   * Subscribe to filesystem events for this collection's root
+   * directory. The watcher is lazy — created here, not in the
+   * constructor — so callers who never call `watch()` pay no cost
+   * and their process exits cleanly after `all()`.
+   *
+   * The callback is invoked with a `{ type, filePath }` object
+   * where `filePath` is relative to the collection root. The
+   * caller typically calls `collection.invalidate()` in response
+   * and re-renders.
+   *
+   * Returns a handle with `unsubscribe()`. You can call that
+   * directly, or call `collection.dispose()` / use `await using`
+   * (ES2023) to close every watcher at once.
+   */
+  watch(handler: CollectionWatchHandler): CollectionWatchHandle {
+    const root = this.resolveRoot();
+    if (!fs.existsSync(root)) {
+      // Nothing to watch — return a no-op handle so callers don't
+      // have to branch on "directory exists". If the directory
+      // appears later, they can unsubscribe and re-watch.
+      return { unsubscribe: () => {} };
+    }
+    const extensions = this.options.extensions ?? [...DEFAULT_EXTENSIONS];
+    const extSet = new Set(extensions.map((e) => e.toLowerCase()));
+
+    // Use node's `fs.watch` directly — one handle per collection
+    // root. `recursive: true` is the expensive bit; it is not
+    // supported on Linux before kernel 5.0 but the dev-mode path
+    // targets macOS/Windows/recent Linux where it works. If a
+    // project needs stricter compatibility, they can wrap
+    // `chokidar` in user code and call `invalidate()` themselves.
+    let watcher: fs.FSWatcher;
+    try {
+      watcher = fs.watch(root, { recursive: true }, (eventType, filename) => {
+        if (!filename) return;
+        const normalized = String(filename).replace(/\\/g, "/");
+        // Filter by extension so unrelated files don't fire the
+        // callback. We still let the event propagate for rename
+        // events on directories (no extension) — those can affect
+        // slugs.
+        const lastDot = normalized.lastIndexOf(".");
+        const ext = lastDot >= 0 ? normalized.slice(lastDot).toLowerCase() : "";
+        if (ext && !extSet.has(ext)) return;
+        try {
+          handler({
+            type: eventType === "rename" ? "rename" : "change",
+            filePath: normalized,
+          });
+        } catch (err) {
+          // Swallow user-handler errors so one buggy consumer
+          // does not tear down the watcher for everyone else.
+          console.error(
+            `[content] watch handler threw for ${normalized}:`,
+            err instanceof Error ? err.message : err
+          );
+        }
+      });
+    } catch (err) {
+      // Some platforms (notably older Linux) don't support
+      // `recursive: true`. Log once and return a no-op handle so
+      // the caller's code continues — missing-reload is
+      // degradation, not breakage.
+      console.warn(
+        `[content] fs.watch(${root}) failed — hot reload disabled for this collection:`,
+        err instanceof Error ? err.message : err
+      );
+      return { unsubscribe: () => {} };
+    }
+
+    const entry = { close: () => watcher.close() };
+    this.watchHandles.add(entry);
+
+    return {
+      unsubscribe: () => {
+        if (!this.watchHandles.has(entry)) return;
+        this.watchHandles.delete(entry);
+        try {
+          watcher.close();
+        } catch {
+          // Already closed — ignore.
+        }
+      },
+    };
+  }
+
+  /**
+   * Close every active watcher opened by `.watch()`. Safe to call
+   * repeatedly. After `dispose()` the collection remains usable
+   * — calling `watch()` again creates a fresh handle.
+   */
+  dispose(): void {
+    for (const handle of this.watchHandles) {
+      try {
+        handle.close();
+      } catch {
+        // Handle already closed — ignore.
+      }
+    }
+    this.watchHandles.clear();
+  }
+
+  /**
+   * ES2023 async-dispose support. Enables:
+   *
+   *   ```ts
+   *   await using docs = defineCollection({ path: 'content/docs' });
+   *   const unsubscribe = docs.watch(onChange);
+   *   // ... work ...
+   *   // docs[Symbol.asyncDispose]() runs automatically at scope exit
+   *   ```
+   *
+   * The async variant is used (instead of sync `Symbol.dispose`)
+   * because real watchers in the ecosystem close asynchronously
+   * — we keep the signature future-proof even though `fs.watch`
+   * happens to close synchronously today.
+   */
+  async [Symbol.asyncDispose](): Promise<void> {
+    this.dispose();
+  }
+}
+
+/**
+ * Default comparator: `data.order` ascending, with missing order
+ * treated as infinity so numbered entries sink to the top.
+ */
+function defaultSort<T>(): CollectionSort<T> {
+  return (a, b) => {
+    const oa = (a.data as { order?: unknown })?.order;
+    const ob = (b.data as { order?: unknown })?.order;
+    const na = typeof oa === "number" ? oa : Number.POSITIVE_INFINITY;
+    const nb = typeof ob === "number" ? ob : Number.POSITIVE_INFINITY;
+    if (na !== nb) return na - nb;
+    return 0;
+  };
+}
+
+/**
+ * Compact a Zod error into a single line suitable for the error
+ * messages surfaced by `Collection.load()`. We deliberately avoid
+ * `z.prettifyError` (not present in Zod 3) and the flattener —
+ * `issue.path` + `issue.message` is enough for docs authors to
+ * locate the broken field fast.
+ */
+function formatZodError(error: {
+  issues: Array<{ path: (string | number)[]; message: string }>;
+}): string {
+  return error.issues
+    .map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`)
+    .join("; ");
+}
+
+/**
+ * Synchronous recursive directory walker — the collection typically
+ * has a bounded number of entries (dozens to low thousands) so the
+ * sync cost is negligible, and using sync simplifies error paths
+ * and the cache-hit fast-path in `load()`.
+ */
+function walkDir(dir: string, out: string[], extSet: Set<string>): void {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const absPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walkDir(absPath, out, extSet);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    const ext = path.extname(entry.name).toLowerCase();
+    if (!extSet.has(ext)) continue;
+    out.push(absPath);
+  }
+}
+
+/** Internal result type from `renderMarkdownSafe`. */
+interface RenderedMarkdown {
+  html?: string;
+  Component: () => unknown;
+  mode: CompiledCollectionEntry<unknown>["compilationMode"];
+  error?: Error;
+}
+
+/**
+ * Lazy markdown renderer. Attempts to load `unified` + the standard
+ * remark/rehype plugin chain; when any piece is missing, falls back
+ * to returning a `<pre>` shell so the caller gets a stable API.
+ *
+ * We go through `Function("return import(...)")` instead of a direct
+ * dynamic `import()` so TS doesn't resolve the optional modules
+ * during typecheck — they are NOT in `@mandujs/core` deps by design.
+ *
+ * The `options.remarkPlugins` / `options.rehypePlugins` arrays let
+ * docs sites add `rehype-slug`, `rehype-autolink-headings`, `shiki`,
+ * etc. — the caller is responsible for installing those modules.
+ */
+async function renderMarkdownSafe(
+  body: string,
+  options: CompileOptions = {}
+): Promise<RenderedMarkdown> {
+  const { remarkPlugins = [], rehypePlugins = [], silent = false } = options;
+
+  // Passing the module specifier through a Function-wrapped dynamic
+  // import keeps TypeScript from erroring on optional peer deps; if
+  // any module is missing we fall through to the raw-markdown path.
+  const tryImport = async (id: string): Promise<unknown> => {
+    try {
+      return await (Function("x", "return import(x)") as (x: string) => Promise<unknown>)(id);
+    } catch {
+      return null;
+    }
+  };
+
+  const unified = (await tryImport("unified")) as
+    | { unified: () => unknown }
+    | null;
+  const remarkParse = (await tryImport("remark-parse")) as
+    | { default: unknown }
+    | null;
+  const remarkRehype = (await tryImport("remark-rehype")) as
+    | { default: unknown }
+    | null;
+  const rehypeStringify = (await tryImport("rehype-stringify")) as
+    | { default: unknown }
+    | null;
+
+  // Collect the names of missing modules so the warning is
+  // actionable — a generic "MDX tooling not installed" is hard to
+  // act on when you DO have some of it installed.
+  const missing: string[] = [];
+  if (!unified) missing.push("unified");
+  if (!remarkParse) missing.push("remark-parse");
+  if (!remarkRehype) missing.push("remark-rehype");
+  if (!rehypeStringify) missing.push("rehype-stringify");
+
+  if (missing.length === 0 && unified && remarkParse && remarkRehype && rehypeStringify) {
+    try {
+      type Processor = {
+        use: (plugin: unknown, options?: unknown) => Processor;
+        process: (src: string) => Promise<{ toString: () => string }>;
+      };
+      // Type-punned unified chain — optional peer deps don't carry
+      // their own types into our graph, so we route through `unknown`.
+      let chain = unified.unified() as unknown as Processor;
+      chain = chain.use(remarkParse.default);
+      // User-supplied remark plugins run between `remark-parse`
+      // and `remark-rehype` so they can transform the MDAST.
+      for (const plugin of remarkPlugins) {
+        chain = applyPlugin(chain, plugin);
+      }
+      chain = chain.use(remarkRehype.default);
+      // Rehype plugins run AFTER `remark-rehype` so they see the
+      // HAST — this is the hook point for `rehype-slug` etc.
+      for (const plugin of rehypePlugins) {
+        chain = applyPlugin(chain, plugin);
+      }
+      chain = chain.use(rehypeStringify.default);
+      const file = await chain.process(body);
+      const html = file.toString();
+      return {
+        html,
+        Component: () => createHtmlElement(html),
+        mode: "unified",
+      };
+    } catch (err) {
+      // Pipeline itself threw — report it so the caller sees the
+      // underlying failure instead of a silent `<pre>`.
+      if (!silent) {
+        console.warn(
+          "[content] MDX pipeline failed; falling back to <pre>. Underlying error:",
+          err instanceof Error ? err.message : err
+        );
+      }
+      return {
+        Component: () => createPreElement(body),
+        mode: "fallback-pipeline-error",
+        error: err instanceof Error ? err : new Error(String(err)),
+      };
+    }
+  }
+
+  // Fallback: emit a simple React element wrapping the raw body in a
+  // `<pre>` so pages don't 500. Pages that need real MDX should
+  // install `unified` + remark/rehype in their project.
+  if (!silent && missing.length > 0) {
+    // One warning per call — if the project is rendering 500 pages
+    // this will be noisy, but that noise is the feedback users
+    // need to know WHY their markdown is not compiling. `silent:
+    // true` mutes this for build scripts that deliberately opt out.
+    console.warn(
+      `[content] MDX tooling missing: ${missing.join(
+        ", "
+      )}. Install these peer deps to enable full rendering — falling back to <pre> shell.`
+    );
+  }
+  return {
+    Component: () => createPreElement(body),
+    mode: "fallback-missing-deps",
+  };
+}
+
+/**
+ * Apply a plugin spec to a unified chain. The unified plugin
+ * ecosystem accepts either a bare function or a `[plugin, options]`
+ * tuple, so we handle both without pulling the unified types in.
+ */
+function applyPlugin<P extends { use: (plugin: unknown, options?: unknown) => P }>(
+  chain: P,
+  plugin: unknown
+): P {
+  if (Array.isArray(plugin)) {
+    const [fn, ...rest] = plugin;
+    return chain.use(fn, ...rest);
+  }
+  return chain.use(plugin);
+}
+
+/**
+ * Build a lightweight React element carrying HTML content. We avoid
+ * importing React directly so `@mandujs/core/content` stays
+ * React-free at import time — the returned value is the plain React
+ * element shape (`{ type, props, key }`) which matches what
+ * `React.createElement('div', { dangerouslySetInnerHTML: ... })`
+ * produces. If the project hosts a React version that uses a
+ * different shape, users can swap to their own compiler.
+ */
+function createHtmlElement(html: string): unknown {
+  return {
+    type: "div",
+    props: {
+      dangerouslySetInnerHTML: { __html: html },
+    },
+    key: null,
+    // React 19 uses a $$typeof symbol to distinguish elements —
+    // stamp it so React.isValidElement() accepts us.
+    $$typeof: Symbol.for("react.element"),
+    ref: null,
+  };
+}
+
+function createPreElement(body: string): unknown {
+  return {
+    type: "pre",
+    props: { children: body },
+    key: null,
+    $$typeof: Symbol.for("react.element"),
+    ref: null,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// defineCollection overloads
+// ---------------------------------------------------------------------------
+
+/**
+ * Legacy signature — pass-through for projects using the existing
+ * ContentLayer (`{ loader, schema }`). We detect the shape at runtime
+ * and return the config unchanged so downstream
+ * `defineContentConfig({ collections: { ... } })` keeps working.
+ */
+export function defineCollection<T extends LegacyCollectionConfig>(
+  config: T
+): T;
+
+/**
+ * MVP signature — create a typed `Collection` from a directory path
+ * and optional Zod schema.
+ */
+export function defineCollection<T>(
+  options: DefineCollectionOptions<T>
+): Collection<T>;
+
+export function defineCollection(
+  config: LegacyCollectionConfig | DefineCollectionOptions<unknown>
+): unknown {
+  // Disambiguate by the presence of a `loader` property — the legacy
+  // config always has one, the MVP config never does. Passing both
+  // throws so the error points to the conflict rather than letting
+  // one branch silently win.
+  if (isLegacyConfig(config)) {
+    if ("path" in config) {
+      throw new Error(
+        "[defineCollection] config has both `loader` and `path`; pick one — the legacy ContentLayer uses `loader`, the MVP Collection API uses `path`."
+      );
+    }
+    return config;
+  }
+  return new Collection(config as DefineCollectionOptions<unknown>);
+}
+
+function isLegacyConfig(
+  cfg: LegacyCollectionConfig | DefineCollectionOptions<unknown>
+): cfg is LegacyCollectionConfig {
+  return typeof cfg === "object" && cfg !== null && "loader" in cfg;
+}
+
+/**
+ * Module-scoped registry of every `Collection` instance ever constructed
+ * in this process. Consumed by the dev bundler's content-change handler
+ * to invalidate in-memory entries after a filesystem add/remove so the
+ * next SSR request rescans disk. Readers must treat the set as read-only.
+ */
+const collectionRegistry = new Set<Collection<unknown>>();
+
+/**
+ * Return the live registry of Collections. The returned set is live —
+ * a Collection constructed after the call still shows up on the next
+ * iteration. Intended for dev tooling; production code should go
+ * through the typed `getCollection()` / `defineCollection()` APIs.
+ */
+export function getRegisteredCollections(): ReadonlySet<Collection<unknown>> {
+  return collectionRegistry;
+}
+
+/**
+ * Invalidate every registered collection's in-memory cache. Called by
+ * the dev bundler when a file under a collection root is added or
+ * removed. Cheap (walks the registry and nulls each `entries` cache);
+ * the next `.all()` / `.get()` call rescans disk.
+ */
+export function invalidateAllCollections(): void {
+  for (const c of collectionRegistry) c.invalidate();
+}