@timber-js/app 0.2.0-alpha.191 → 0.2.0-alpha.192

package/dist/plugins/mdx.d.ts

@@ -1,10 +1,22 @@
 /**
- * timber-mdx — Vite sub-plugin for MDX page rendering.
+ * timber-mdx — Vite sub-plugin for MDX and Markdown rendering.
  *
- * Wires @mdx-js/rollup into the Vite pipeline when MDX is activated.
+ * Wires vite-plugin-satteri into the Vite pipeline when MDX is activated.
  * MDX is activated when pageExtensions includes 'mdx' or 'md', or
  * when a content/ directory exists at the project root.
  *
+ * Satteri is a Rust-based Markdown/MDX compiler with a native Vite plugin:
+ * - `.mdx` files compile to React components (ES modules with real import
+ *   statements, so @vitejs/plugin-rsc client-boundary detection works).
+ * - `.md` files compile to modules exporting a rendered HTML string.
+ * - Frontmatter (YAML/TOML) parses natively and is emitted as a
+ *   `frontmatter` named export — no remark plugins needed.
+ * - GFM (tables, footnotes, strikethrough, task lists) is on by default.
+ *
+ * Extensibility is satteri's visitor-based plugin API (defineMdastPlugin /
+ * defineHastPlugin), not unified — the AST lives on the Rust side, so
+ * remark/rehype plugins cannot run. See design/20-content-collections.md.
+ *
  * Design doc: 20-content-collections.md §"The timber-mdx Plugin"
  */
 import type { Plugin } from 'vite';
@@ -19,9 +31,10 @@ export declare function findMdxComponents(root: string): string | undefined;
  * Create the timber-mdx Vite plugin.
  *
  * Uses the transform and resolveId hooks to delegate MDX compilation
- * to @mdx-js/rollup. The inner plugin is loaded lazily on first activation.
+ * to vite-plugin-satteri. The inner plugin is loaded lazily on first
+ * activation.
  *
- * Hooks: buildStart (loads @mdx-js/rollup), resolveId, load, transform
+ * Hooks: buildStart (loads vite-plugin-satteri), resolveId, load, transform
  */
 export declare function timberMdx(ctx: PluginContext): Plugin;
 //# sourceMappingURL=mdx.d.ts.map

package/dist/plugins/mdx.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mdx.d.ts","sourceRoot":"","sources":["../../src/plugins/mdx.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAKnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAI1D;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAelE;AAiED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CA2GpD"}
+{"version":3,"file":"mdx.d.ts","sourceRoot":"","sources":["../../src/plugins/mdx.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAKnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAI1D;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAelE;AAqED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CA4HpD"}

package/dist/plugins/server-bundle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-bundle.d.ts","sourceRoot":"","sources":["../../src/plugins/server-bundle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAoCnC,wBAAgB,kBAAkB,IAAI,MAAM,EAAE,CAuK7C"}
+{"version":3,"file":"server-bundle.d.ts","sourceRoot":"","sources":["../../src/plugins/server-bundle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAqCnC,wBAAgB,kBAAkB,IAAI,MAAM,EAAE,CAuK7C"}

package/docs/api/34-api-config.mdx

@@ -39,11 +39,10 @@ interface TimberUserConfig {
     firstLoadJs?: number;
   };
   appDir?: string;
-  mdx?: {
-    remarkPlugins?: any[];
-    rehypePlugins?: any[];
-    recmaPlugins?: any[];
-    remarkRehypeOptions?: any;
+  mdx?: false | {
+    mdastPlugins?: any[];
+    hastPlugins?: any[];
+    features?: Record<string, any>;
   };
   actionEncryption?: {
     disableInDev?: boolean;
@@ -226,15 +225,17 @@ Override the app directory location. Set to a relative path from the project roo
 
 ### `mdx`
 
-MDX compilation options — remark, rehype, and recma plugins:
+MDX compilation options — Satteri visitor plugins and parser feature toggles (GFM and frontmatter are on by default). Set `mdx: false` to disable timber's MDX support and bring your own compiler:
 
 ```ts
 mdx: {
-  remarkPlugins: [remarkGfm],
-  rehypePlugins: [rehypePrism],
+  hastPlugins: [myCodeHighlighter],
+  features: { math: true },
 }
 ```
 
+See [MDX](/docs/mdx) for the plugin model and how it differs from remark/rehype.
+
 ### `actionEncryption`
 
 Server action bound args encryption configuration. The RSC plugin encrypts closure variables captured by `'use server'` functions using AES-256-GCM so they are opaque and tamper-proof in the Flight payload. Encryption is always enabled in production.

package/docs/more/04b-mdx.mdx

@@ -17,10 +17,10 @@ export default {
 };
 ```
 
-Install the MDX compiler and frontmatter plugins:
+Install the MDX compiler — timber.js uses [Satteri](https://satteri.bruits.org), a Rust-based Markdown/MDX compiler with a native Vite plugin:
 
 ```bash title="Terminal"
-pnpm add -D @mdx-js/rollup remark-frontmatter remark-mdx-frontmatter
+pnpm add -D vite-plugin-satteri satteri
 ```
 
 That's it. Any `page.mdx` file in your `app/` directory is now a route.
@@ -57,7 +57,7 @@ This page is a **server component** — no JavaScript shipped to the browser.
 
 ## Frontmatter
 
-timber.js automatically registers `remark-frontmatter` and `remark-mdx-frontmatter` when installed. Frontmatter is exported as a single `frontmatter` object:
+Frontmatter parsing is built in — YAML between `---` fences or TOML between `+++` fences. Frontmatter is exported as a single `frontmatter` object:
 
 ````mdx title="app/blog/hello/page.mdx"
 ---
@@ -127,33 +127,52 @@ pnpm add @timber-js/app
 
 Only the `CopyButton` ships JavaScript. The rest of the page renders as static HTML.
 
-## Remark and Rehype Plugins
+## Plugins and Features
 
-Configure remark and rehype plugins through the `mdx` key in your config:
+GFM (tables, footnotes, strikethrough, task lists) and frontmatter are on by default. Additional syntax is enabled through `features`, and custom transforms are written as Satteri visitor plugins through the `mdx` key in your config:
 
 ```ts title="timber.config.ts"
-import remarkGfm from 'remark-gfm';
-import rehypeShiki from '@shikijs/rehype';
+import { defineHastPlugin } from 'satteri';
+
+const externalLinks = defineHastPlugin({
+  name: 'external-links',
+  element: {
+    filter: ['a'],
+    visit(node, ctx) {
+      const href = node.properties.href;
+      if (typeof href === 'string' && href.startsWith('http')) {
+        ctx.setProperty(node, 'target', '_blank');
+      }
+    },
+  },
+});
 
 export default {
   pageExtensions: ['tsx', 'ts', 'jsx', 'js', 'mdx'],
   mdx: {
-    remarkPlugins: [remarkGfm],
-    rehypePlugins: [[rehypeShiki, { theme: 'monokai' }]],
+    hastPlugins: [externalLinks],
+    features: { math: true },
   },
 };
 ```
 
-The `mdx` config maps directly to `@mdx-js/rollup` options. Available fields:
+The `mdx` config maps directly to `vite-plugin-satteri` options. Available fields:
+
+| Option         | Type                 | Description                                                                     |
+| -------------- | -------------------- | ------------------------------------------------------------------------------- |
+| `mdastPlugins` | `MdastPluginInput[]` | Markdown AST visitors (created with `defineMdastPlugin`)                        |
+| `hastPlugins`  | `HastPluginInput[]`  | HTML AST visitors (created with `defineHastPlugin`)                             |
+| `features`     | `Features`           | Parser toggles — `gfm`, `frontmatter`, `math`, `directive`, `wikilinks`, …      |
 
-| Option                | Type            | Description                                |
-| --------------------- | --------------- | ------------------------------------------ |
-| `remarkPlugins`       | `PluggableList` | remark plugins for Markdown AST transforms |
-| `rehypePlugins`       | `PluggableList` | rehype plugins for HTML AST transforms     |
-| `recmaPlugins`        | `PluggableList` | recma plugins for ESTree transforms        |
-| `remarkRehypeOptions` | `object`        | Options passed to `remark-rehype`          |
+Satteri plugins are filtered visitors, not unified plugins — **remark/rehype plugins do not run** on Satteri's Rust-side AST. Visitors can be async and can replace nodes, which is enough to build things like shiki-based syntax highlighting (shiki transformers such as `@shikijs/twoslash` still work, since they run inside shiki).
 
-Plugins like `remark-gfm` and `rehype-shiki` are your choice to install — timber.js doesn't bundle them.
+If you need the unified MDX pipeline (for example, CodeHike), bypass timber's MDX support entirely: set `mdx: false` in your config and register `@mdx-js/rollup` yourself in `vite.config.ts` with `enforce: 'pre'`:
+
+```ts title="timber.config.ts"
+export default {
+  mdx: false, // disable timber's built-in MDX — bring your own compiler
+};
+```
 
 ## Dynamic MDX Loading
 
@@ -205,5 +224,6 @@ For structured content outside the route tree (blog posts, docs, changelogs), us
 | `@next/mdx` wrapper package               | Built-in — just add `'mdx'` to pageExtensions |
 | `next.config.mjs` `withMDX()` wrapper     | `timber.config.ts` `mdx` key                  |
 | MDX pages are client components by default | MDX pages are server components by default     |
-| Custom loader for `.md` files              | `@mdx-js/rollup` handles both `.mdx` and `.md` |
+| unified (remark/rehype) plugins            | Satteri visitor plugins + built-in features   |
+| Custom loader for `.md` files              | Built in — `.md` imports export an HTML string |
 | `mdx-components.tsx` at project root       | Same convention                               |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.191",
+  "version": "0.2.0-alpha.192",
   "description": "Vite-native React framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",
@@ -160,14 +160,15 @@
     "@content-collections/core": "^0.14.0 || ^0.15.0",
     "@content-collections/mdx": "^0.2.0",
     "@content-collections/vite": "^0.2.0 || ^0.3.0",
-    "@mdx-js/rollup": "^3.0.0",
     "@typescript/native-preview": "^7.0.0-dev.0",
     "@vitejs/plugin-react": "^6.0.0",
     "@vitejs/plugin-rsc": ">=0.5.28",
     "nuqs": "^2.0.0",
     "react": "19.2.7",
     "react-dom": "19.2.7",
+    "satteri": "^0.9.5",
     "vite": "^8.1.0",
+    "vite-plugin-satteri": "^0.2.15",
     "wrangler": "^4.0.0",
     "zod": "^3.22.0 || ^4.0.0"
   },
@@ -181,7 +182,10 @@
     "@content-collections/vite": {
       "optional": true
     },
-    "@mdx-js/rollup": {
+    "satteri": {
+      "optional": true
+    },
+    "vite-plugin-satteri": {
       "optional": true
     },
     "@typescript/native-preview": {

package/src/config-types.ts

@@ -159,13 +159,33 @@ export interface TimberUserConfig {
    * to use a custom location.
    */
   appDir?: string;
-  /** MDX compilation options passed to @mdx-js/rollup. See design/20-content-collections.md. */
-  mdx?: {
-    remarkPlugins?: unknown[];
-    rehypePlugins?: unknown[];
-    recmaPlugins?: unknown[];
-    remarkRehypeOptions?: Record<string, unknown>;
-  };
+  /**
+   * MDX/Markdown compilation options passed to vite-plugin-satteri.
+   *
+   * Satteri's plugin API is visitor-based (`defineMdastPlugin` /
+   * `defineHastPlugin` from the `satteri` package) — unified
+   * remark/rehype plugins are not supported.
+   *
+   * Set to `false` to disable timber's MDX support entirely — even when a
+   * `content/` directory exists. Use this when registering your own MDX
+   * compiler (e.g. `@mdx-js/rollup` for the unified pipeline) directly in
+   * `vite.config.ts`.
+   *
+   * See design/20-content-collections.md.
+   */
+  mdx?:
+    | false
+    | {
+        /** MDAST-stage plugins (created with satteri's `defineMdastPlugin`). */
+        mdastPlugins?: unknown[];
+        /** HAST-stage plugins (created with satteri's `defineHastPlugin`). */
+        hastPlugins?: unknown[];
+        /**
+         * Parser feature toggles. Defaults: `gfm: true`, `frontmatter: true`,
+         * everything else (math, directive, wikilinks, …) off.
+         */
+        features?: Record<string, unknown>;
+      };
   /**
    * Server action bound args encryption configuration.
    *

package/src/plugins/mdx.ts

@@ -1,10 +1,22 @@
 /**
- * timber-mdx — Vite sub-plugin for MDX page rendering.
+ * timber-mdx — Vite sub-plugin for MDX and Markdown rendering.
  *
- * Wires @mdx-js/rollup into the Vite pipeline when MDX is activated.
+ * Wires vite-plugin-satteri into the Vite pipeline when MDX is activated.
  * MDX is activated when pageExtensions includes 'mdx' or 'md', or
  * when a content/ directory exists at the project root.
  *
+ * Satteri is a Rust-based Markdown/MDX compiler with a native Vite plugin:
+ * - `.mdx` files compile to React components (ES modules with real import
+ *   statements, so @vitejs/plugin-rsc client-boundary detection works).
+ * - `.md` files compile to modules exporting a rendered HTML string.
+ * - Frontmatter (YAML/TOML) parses natively and is emitted as a
+ *   `frontmatter` named export — no remark plugins needed.
+ * - GFM (tables, footnotes, strikethrough, task lists) is on by default.
+ *
+ * Extensibility is satteri's visitor-based plugin API (defineMdastPlugin /
+ * defineHastPlugin), not unified — the AST lives on the Rust side, so
+ * remark/rehype plugins cannot run. See design/20-content-collections.md.
+ *
  * Design doc: 20-content-collections.md §"The timber-mdx Plugin"
  */
 
@@ -43,6 +55,12 @@ export function findMdxComponents(root: string): string | undefined {
  * Determine if MDX should be activated based on config and project structure.
  */
 function shouldActivate(ctx: PluginContext): boolean {
+  // Explicit opt-out — the escape hatch for apps that register their own
+  // MDX compiler (e.g. @mdx-js/rollup for the unified pipeline) in
+  // vite.config.ts. Without this, a content/ directory would force
+  // activation no matter what pageExtensions says.
+  if (ctx.config.mdx === false) return false;
+
   const exts = ctx.config.pageExtensions;
   if (exts && exts.some((ext) => MDX_EXTENSIONS.includes(ext))) {
     return true;
@@ -61,13 +79,11 @@ function shouldActivate(ctx: PluginContext): boolean {
  *
  * Why this matters: pnpm only hoists declared (peer) dependencies into a
  * package's resolution scope. The MDX integration's optional companions
- * — `remark-frontmatter`, `remark-mdx-frontmatter`, `@mdx-js/rollup` — are
- * installed as direct deps of the consumer (e.g. `packages/website`), not
- * `@timber-js/app`. A bare `import('remark-frontmatter')` from inside this
- * file resolves against `packages/timber-app/node_modules` and silently
- * fails with `ERR_MODULE_NOT_FOUND`, which made `tryImport` return
- * `undefined` and skipped frontmatter parsing entirely — leaving MDX to
- * choke on YAML as JS expressions (TIM-840).
+ * — `vite-plugin-satteri` and `satteri` — are installed as direct deps of
+ * the consumer (e.g. `packages/website`), not `@timber-js/app`. A bare
+ * `import('vite-plugin-satteri')` from inside this file resolves against
+ * `packages/timber-app/node_modules` and silently fails with
+ * `ERR_MODULE_NOT_FOUND` (TIM-840).
  *
  * Resolving relative to `projectRoot` (via `createRequire`) makes the
  * lookup walk the consumer's `node_modules` tree first, which is where
@@ -106,9 +122,10 @@ async function tryImport(name: string, projectRoot: string): Promise<unknown | u
  * Create the timber-mdx Vite plugin.
  *
  * Uses the transform and resolveId hooks to delegate MDX compilation
- * to @mdx-js/rollup. The inner plugin is loaded lazily on first activation.
+ * to vite-plugin-satteri. The inner plugin is loaded lazily on first
+ * activation.
  *
- * Hooks: buildStart (loads @mdx-js/rollup), resolveId, load, transform
+ * Hooks: buildStart (loads vite-plugin-satteri), resolveId, load, transform
  */
 export function timberMdx(ctx: PluginContext): Plugin {
   let innerPlugin: Plugin | null = null;
@@ -116,50 +133,60 @@ export function timberMdx(ctx: PluginContext): Plugin {
   async function activate(): Promise<void> {
     if (innerPlugin !== null || !shouldActivate(ctx)) return;
 
-    const createMdxPlugin = (await tryImport('@mdx-js/rollup', ctx.root)) as
+    // Satteri compiles .md to an HTML string, not a component — a page.md
+    // route would make the renderer invoke a string as a component and
+    // TypeError at request time. Fail at startup instead. Imported .md
+    // files work without listing 'md' in pageExtensions.
+    if (ctx.config.pageExtensions?.includes('md')) {
+      throw new Error(
+        [
+          "[timber] pageExtensions includes 'md', but .md route pages are not supported:",
+          'Markdown files compile to HTML strings, not components.',
+          '',
+          "Use .mdx for pages (pageExtensions: ['tsx', 'ts', 'mdx']).",
+          '.md files can still be imported as HTML strings — no pageExtensions entry needed.',
+        ].join('\n')
+      );
+    }
+
+    const createSatteriPlugin = (await tryImport('vite-plugin-satteri', ctx.root)) as
       | ((options?: Record<string, unknown>) => Plugin)
       | undefined;
 
-    if (!createMdxPlugin) {
+    if (!createSatteriPlugin) {
       throw new Error(
         [
-          '[timber] MDX is enabled but @mdx-js/rollup is not installed.',
+          '[timber] MDX is enabled but vite-plugin-satteri is not installed.',
           '',
           'Install it:',
-          '  pnpm add -D @mdx-js/rollup remark-frontmatter remark-mdx-frontmatter',
+          '  pnpm add -D vite-plugin-satteri satteri',
           '',
           'MDX is activated because pageExtensions includes "mdx"/"md" or a content/ directory exists.',
         ].join('\n')
       );
     }
 
-    const mdxConfig = ctx.config.mdx ?? {};
-
-    // Auto-register frontmatter plugins. Resolve from the consumer's root
-    // so pnpm finds packages declared in the user's package.json (TIM-840).
-    const remarkPlugins: unknown[] = [];
-    const remarkFrontmatter = await tryImport('remark-frontmatter', ctx.root);
-    const remarkMdxFrontmatter = await tryImport('remark-mdx-frontmatter', ctx.root);
-    if (remarkFrontmatter) remarkPlugins.push(remarkFrontmatter);
-    if (remarkMdxFrontmatter) remarkPlugins.push(remarkMdxFrontmatter);
-
-    if (mdxConfig.remarkPlugins) {
-      remarkPlugins.push(...mdxConfig.remarkPlugins);
-    }
+    // `|| {}` (not `??`): mdx can be `false`, though shouldActivate() has
+    // already bailed in that case.
+    const mdxConfig = ctx.config.mdx || {};
 
-    const mdxOptions: Record<string, unknown> = {
-      remarkPlugins,
-      rehypePlugins: mdxConfig.rehypePlugins ?? [],
-      recmaPlugins: mdxConfig.recmaPlugins ?? [],
-      remarkRehypeOptions: mdxConfig.remarkRehypeOptions,
-    };
+    // We pass `development` explicitly (satteri otherwise infers it from
+    // Vite's command via its own configResolved hook, which we don't
+    // delegate) and control providerImportSource — the mdx-components.tsx
+    // convention belongs to the framework, not the user config.
+    const mdxOptions: Record<string, unknown> = { development: ctx.dev };
 
     const mdxComponentsPath = findMdxComponents(ctx.root);
     if (mdxComponentsPath) {
       mdxOptions.providerImportSource = mdxComponentsPath;
     }
 
-    innerPlugin = createMdxPlugin(mdxOptions);
+    innerPlugin = createSatteriPlugin({
+      mdx: mdxOptions,
+      ...(mdxConfig.mdastPlugins ? { mdastPlugins: mdxConfig.mdastPlugins } : {}),
+      ...(mdxConfig.hastPlugins ? { hastPlugins: mdxConfig.hastPlugins } : {}),
+      ...(mdxConfig.features ? { features: mdxConfig.features } : {}),
+    });
   }
 
   return {
@@ -208,6 +235,13 @@ export function timberMdx(ctx: PluginContext): Plugin {
 
     async transform(code, id) {
       if (!innerPlugin) return null;
+      // Ids with a Vite query (?raw, ?url, ?import) are asset requests, not
+      // modules to compile. vite-plugin-satteri's id regexes match them, but
+      // by the time this transform runs the code is already the asset module
+      // (e.g. `export default "<file text>"` for ?raw) — compiling that as
+      // markdown corrupts it. @mdx-js/rollup matched by extname and skipped
+      // queried ids; preserve that behavior.
+      if (id.includes('?')) return null;
       const envName = (this as unknown as { environment?: { name?: string } }).environment?.name;
       if (envName && envName !== 'rsc') return null;
       if (typeof innerPlugin.transform === 'function') {

package/src/plugins/server-bundle.ts

@@ -43,7 +43,8 @@ const BUILD_ONLY_EXTERNALS: string[] = [
   'vite',
   'nitro',
   'rollup',
-  '@mdx-js/rollup',
+  'vite-plugin-satteri',
+  'satteri',
   'fsevents',
   'chokidar',
 ];