@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.210

package/src/plugins/mdx.ts

@@ -1,19 +1,35 @@
 /**
- * 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';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import type { PluginContext } from '#/index.js';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import type { PluginContext } from '../plugin-context.ts';
+/** MDX/markdown extensions (dotted) — the canonical list for the compiler plugin. */
+const MDX_EXTENSIONS = new Set(['.mdx', '.md']);
 
-const MDX_EXTENSIONS = ['mdx', 'md'];
+const MDX_EXTENSIONS_UNDOTTED = [...MDX_EXTENSIONS].map((ext) => ext.slice(1));
 
 /**
  * Check if mdx-components.tsx (or .ts, .jsx, .js) exists at the project root
@@ -41,8 +57,14 @@ 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))) {
+  if (exts && exts.some((ext) => MDX_EXTENSIONS_UNDOTTED.includes(ext))) {
     return true;
   }
 
@@ -54,15 +76,47 @@ function shouldActivate(ctx: PluginContext): boolean {
 }
 
 /**
- * Try to dynamically import a module by name. Returns the default export
- * or the module itself, or undefined if the module is not installed.
+ * Try to dynamically import a module by name, resolving from the user's
+ * project root rather than from `@timber-js/app`'s own location.
+ *
+ * Why this matters: pnpm only hoists declared (peer) dependencies into a
+ * package's resolution scope. The MDX integration's optional companions
+ * — `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
+ * pnpm puts the user's deps.
+ *
+ * Returns the default export, the module itself, or undefined if the
+ * module is not installed.
  */
-async function tryImport(name: string): Promise<unknown | undefined> {
+async function tryImport(name: string, projectRoot: string): Promise<unknown | undefined> {
   try {
-    const mod = await import(name);
+    // Anchor resolution at the consumer's package.json so we walk their
+    // node_modules tree, not @timber-js/app's. createRequire().resolve()
+    // returns an absolute file path that ESM dynamic import accepts when
+    // wrapped as a file:// URL.
+    const require = createRequire(join(projectRoot, 'package.json'));
+    const resolved = require.resolve(name);
+    const mod = await import(pathToFileURL(resolved).href);
     return mod.default ?? mod;
   } catch {
-    return undefined;
+    // Fall back to a bare import — covers the rare case where the package
+    // lives next to @timber-js/app (e.g. monorepo with hoisted deps).
+    try {
+      const mod = await import(name);
+      return mod.default ?? mod;
+    } catch (e) {
+      console.debug(
+        `[timber] optional MDX dependency '${name}' not available:`,
+        e instanceof Error ? e.message : e
+      );
+      return undefined;
+    }
   }
 }
 
@@ -70,9 +124,10 @@ async function tryImport(name: string): Promise<unknown | 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 function timberMdx(ctx: PluginContext): Plugin {
   let innerPlugin: Plugin | null = null;
@@ -80,49 +135,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')) 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
-    const remarkPlugins: unknown[] = [];
-    const remarkFrontmatter = await tryImport('remark-frontmatter');
-    const remarkMdxFrontmatter = await tryImport('remark-mdx-frontmatter');
-    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 {
@@ -171,6 +237,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/post-build.ts

@@ -0,0 +1,327 @@
+/**
+ * timber-post-build — the post-build phase, as one ordered handler.
+ *
+ * Everything timber does after Vite has built the three environments runs
+ * here, in this order, each step handed what the previous one returned:
+ *
+ *   1. finalize the build manifest — font entries, the RSC assets manifest
+ *      merged in once, JavaScript stripped once when client JS is disabled
+ *   2. prebuilt capture   (cache.component prerender payloads, design/44)
+ *   3. static generation  (output: 'static', design/11)
+ *   4. the build report
+ *   5. assemble `BuildArtifacts` and call the adapter's `buildOutput`
+ *
+ * One `buildApp` hook with `order: 'post'` — so Vite runs the RSC plugin's
+ * buildApp, which orchestrates every environment build and writes the
+ * assets manifests, first. The order above is this function's, not the
+ * plugin array's, and no step reads another's result off the shared
+ * context: sibling plugins contribute through the typed steps they expose
+ * (`FontsBuildStep`, `PrebuiltBuildStep`, `BuildReportStep`), which
+ * `timber()` hands to this plugin directly.
+ *
+ * Design docs: 18-build-system.md §"Post-Build Phase", 11-platform.md
+ * §"Build Artifacts", 49-explicit-subsystem-boundaries.md §B
+ */
+
+import type { Plugin, Rollup } from 'vite';
+import { readdir } from 'node:fs/promises';
+import { join, relative, resolve } from 'node:path';
+import { adapterConfig, contextAdapter, type PluginContext } from '../plugin-context.ts';
+import type { BuildArtifacts, DirectoryArtifact } from '../adapters/types.ts';
+import type { BuildManifest } from '../server/build-manifest.ts';
+import type { FontsBuildStep } from './fonts.ts';
+import type { PrebuiltBuildStep } from './prebuilt.ts';
+import type { BuildReportStep } from './build-report.ts';
+import { runStaticGeneration, type StaticSite } from './static-build.ts';
+import { mergeRscAssetsManifest, stripJsFromRscAssetsManifests } from './rsc-assets-manifest.ts';
+
+/** The Vite environments whose output adapters consume. */
+const ARTIFACT_ENVIRONMENTS = ['client', 'rsc', 'ssr'] as const;
+type ArtifactEnvironment = (typeof ARTIFACT_ENVIRONMENTS)[number];
+
+function isArtifactEnvironment(name: string): name is ArtifactEnvironment {
+  return (ARTIFACT_ENVIRONMENTS as readonly string[]).includes(name);
+}
+
+/** Each environment's output directory, as its own `writeBundle` recorded it. */
+export type EnvironmentOutputs = Partial<Record<ArtifactEnvironment, DirectoryArtifact>>;
+
+/** The steps sibling plugins own. */
+export interface PostBuildSteps {
+  fonts: FontsBuildStep;
+  prebuilt: PrebuiltBuildStep;
+  report: BuildReportStep;
+}
+
+export function timberPostBuild(ctx: PluginContext, steps: PostBuildSteps): Plugin {
+  const environments: EnvironmentOutputs = {};
+  /** What the client environment's bundle wrote, from its `writeBundle`. */
+  let clientOutput: ClientOutput = { assetsDir: '', emitted: new Set() };
+
+  return {
+    name: 'timber-post-build',
+
+    // Record each environment's output directory as it is written, so the
+    // phase learns what exists from the build rather than by probing for
+    // it. The RSC plugin's scan builds run with `write: false` and never
+    // reach this hook; only the real bundles do.
+    writeBundle(options, bundle) {
+      if (ctx.dev) return;
+      const env = this.environment;
+      if (!isArtifactEnvironment(env.name)) return;
+      environments[env.name] = { path: resolve(env.config.root, env.config.build.outDir) };
+      if (env.name === 'client') {
+        clientOutput = {
+          assetsDir: hashedAssetsDir(env.config.build.assetsDir, options),
+          emitted: new Set(Object.keys(bundle)),
+        };
+      }
+    },
+
+    buildApp: {
+      order: 'post' as const,
+      async handler() {
+        if (ctx.dev) return;
+        await runPostBuild(ctx, steps, environments, clientOutput);
+      },
+    },
+  };
+}
+
+/**
+ * The client bundle's assets directory, in the artifacts' form (no leading
+ * or trailing slash) — or `''` when its files are not all content-hashed.
+ *
+ * `assetsDir` names where Vite writes; it is the naming patterns that decide
+ * whether a file name carries a hash. Vite's defaults do
+ * (`<assetsDir>/[name]-[hash].js`), but an app can set
+ * `assetFileNames: 'static/[name][extname]'`, and marking that directory
+ * immutable would pin a changed image under an unchanged URL for a year. A
+ * pattern given as a function cannot be inspected, so it counts as unhashed:
+ * those files fall back to the revalidating per-file rule.
+ *
+ * @internal Exported for testing.
+ */
+export function hashedAssetsDir(
+  assetsDir: string,
+  output: Pick<
+    Rollup.NormalizedOutputOptions,
+    'entryFileNames' | 'chunkFileNames' | 'assetFileNames'
+  >
+): string {
+  const dir = assetsDir.replace(/^\/+|\/+$/g, '');
+  const patterns = [output.entryFileNames, output.chunkFileNames, output.assetFileNames];
+  const hashed = patterns.every((p) => typeof p === 'string' && p.includes('[hash'));
+  return hashed ? dir : '';
+}
+
+/** The client bundle as its own `writeBundle` saw it. */
+interface ClientOutput {
+  /** From `hashedAssetsDir` — `''` when the naming patterns are not all hashed. */
+  assetsDir: string;
+  /** Every file name the bundle emitted, relative to the client output directory. */
+  emitted: ReadonlySet<string>;
+}
+
+/**
+ * Keep only the directories whose every file the client bundle emitted.
+ *
+ * A producer knows it hashes what *it* writes, not what else lands beside it:
+ * Vite copies `public/` into the client output verbatim, so `public/assets/logo.png`
+ * sits in `assets/` under a stable name, and `public/_rsc/…` would sit among
+ * the hashed payloads. A directory holding any file the bundle did not emit
+ * is not content-hashed as a whole, and marking it immutable would pin that
+ * file for a year — so it is dropped, and its files take the per-file rule.
+ *
+ * @internal Exported for testing.
+ */
+export async function onlyEmittedDirs(
+  clientDir: string,
+  dirs: readonly string[],
+  emitted: ReadonlySet<string>
+): Promise<string[]> {
+  const kept: string[] = [];
+  for (const dir of dirs) {
+    const root = join(clientDir, dir);
+    const entries = await readdir(root, { recursive: true, withFileTypes: true }).catch(() => []);
+    const foreign = entries.some(
+      (entry) =>
+        entry.isFile() &&
+        !emitted.has(relative(clientDir, join(entry.parentPath, entry.name)).replace(/\\/g, '/'))
+    );
+    if (!foreign) kept.push(dir);
+  }
+  return kept;
+}
+
+async function runPostBuild(
+  ctx: PluginContext,
+  steps: PostBuildSteps,
+  environments: EnvironmentOutputs,
+  clientOutput: ClientOutput
+): Promise<void> {
+  const output = ctx.config.output ?? 'server';
+  const rsc = requireEnvironment(environments, 'rsc');
+  const ssr = requireEnvironment(environments, 'ssr');
+
+  // 1. The manifest is complete before anything renders with it. Published
+  // for the steps that import the built bundle in this process — the same
+  // value `manifestInit` carries to production. Assigned, never `??=`: a
+  // second build in one process must not render with the first one's.
+  const manifest = await finalizeBuildManifest(ctx, steps.fonts, rsc, ssr);
+  if (manifest) Reflect.set(globalThis, '__TIMBER_BUILD_MANIFEST__', manifest);
+
+  // 2–3. Each writes its own output and returns what it wrote.
+  const prebuilt = await steps.prebuilt.capture(rsc.path);
+  const site = output === 'static' ? await runStaticGeneration(ctx, rsc.path) : undefined;
+
+  // 4.
+  steps.report.print(prebuilt);
+
+  // 5.
+  const adapter = contextAdapter(ctx);
+  if (!adapter || typeof adapter.buildOutput !== 'function') return;
+
+  await adapter.buildOutput(
+    adapterConfig(ctx),
+    assembleBuildArtifacts({
+      output,
+      outputDir: ctx.buildDir,
+      environments,
+      immutableDirs: await onlyEmittedDirs(
+        requireEnvironment(environments, 'client').path,
+        [
+          ...(clientOutput.assetsDir ? [clientOutput.assetsDir] : []),
+          ...steps.fonts.immutableDirs(),
+          ...(site?.immutableDirs ?? []),
+        ],
+        clientOutput.emitted
+      ),
+      prebuilt: prebuilt?.artifact,
+      site,
+      manifestInit: manifest ? serializeManifestInit(manifest) : undefined,
+    })
+  );
+}
+
+function requireEnvironment(
+  environments: EnvironmentOutputs,
+  name: ArtifactEnvironment
+): DirectoryArtifact {
+  const artifact = environments[name];
+  if (!artifact) {
+    throw new Error(`[timber] Build output: the ${name} environment wrote no bundle`);
+  }
+  return artifact;
+}
+
+/**
+ * Step 1: bring the build manifest to its final shape, once.
+ *
+ * `timber-build-manifest` creates it from the client bundle; this adds what
+ * only exists once every environment is built — the font entries and the
+ * per-route CSS and modulepreloads in the RSC plugin's assets manifest —
+ * and then, when client JavaScript is disabled, removes every JavaScript
+ * reference, from the manifest and from the assets manifests on disk. The
+ * manifest's `js` / `modulepreload` are cleared after the merge has written
+ * into them, so nothing the merge adds survives.
+ *
+ * Returns null only when no client bundle produced a manifest.
+ *
+ * @internal Exported for testing.
+ */
+export async function finalizeBuildManifest(
+  ctx: PluginContext,
+  fonts: FontsBuildStep,
+  rsc: DirectoryArtifact,
+  ssr: DirectoryArtifact
+): Promise<BuildManifest | null> {
+  const manifest = ctx.buildManifest;
+  if (manifest) {
+    fonts.contributeManifest(manifest);
+    // Per-route CSS and client reference JS, for <link rel="stylesheet">
+    // and <link rel="modulepreload"> on server component routes (TIM-1014).
+    await mergeRscAssetsManifest(rsc.path, ctx.root, manifest, ctx.routeClientRefKeys);
+  }
+  if (ctx.clientJavascript.disabled) {
+    // Those files are not served, so hints for them are useless.
+    if (manifest) {
+      manifest.js = {};
+      manifest.modulepreload = {};
+    }
+    await stripJsFromRscAssetsManifests([rsc.path, ssr.path]);
+  }
+  return manifest;
+}
+
+/**
+ * The build manifest as a JS module that sets the global. Adapters write
+ * it as `_timber-manifest-init.js` (or prepend it to the entry) and
+ * evaluate it before the RSC handler, so `virtual:timber-build-manifest`
+ * finds it.
+ */
+function serializeManifestInit(manifest: BuildManifest): string {
+  return `globalThis.__TIMBER_BUILD_MANIFEST__ = ${JSON.stringify(manifest)};\n`;
+}
+
+/**
+ * Dedupe the producers' directories and drop any that sits inside another.
+ *
+ * Two producers can name overlapping directories — a custom `assetsDir` of
+ * `_timber` beside the fonts' `_timber/fonts`. Cloudflare and Netlify apply
+ * every matching `_headers` rule, so emitting both would send two
+ * `Cache-Control` values for one file; the outer directory already covers
+ * the inner one.
+ */
+function canonicalImmutableDirs(dirs: readonly string[]): string[] {
+  const unique = [...new Set(dirs)];
+  return unique.filter(
+    (dir) => !unique.some((other) => other !== dir && dir.startsWith(`${other}/`))
+  );
+}
+
+/**
+ * Assemble the adapter's view of the build from what each step returned.
+ *
+ * Not a validator: every field is copied from the phase that produced it.
+ * The throws are the states the union cannot represent — a Vite environment
+ * that wrote no bundle, a static build with no site. Each means an earlier
+ * phase failed without failing the build, and a deploy missing its SSR
+ * bundle fails on the first request rather than here.
+ *
+ * @internal Exported for testing.
+ */
+export function assembleBuildArtifacts(input: {
+  output: 'server' | 'static';
+  outputDir: string;
+  environments: EnvironmentOutputs;
+  immutableDirs: readonly string[];
+  prebuilt?: DirectoryArtifact;
+  site?: StaticSite;
+  manifestInit?: string;
+}): BuildArtifacts {
+  const { output, outputDir, environments } = input;
+  const client = requireEnvironment(environments, 'client');
+  const immutableDirs = canonicalImmutableDirs(input.immutableDirs);
+
+  if (output === 'static') {
+    if (!input.site) {
+      throw new Error(
+        "[timber] Build output: output is 'static' but static generation recorded no site"
+      );
+    }
+    const { pages, contentTypes } = input.site;
+    return { output, outputDir, client, immutableDirs, pages, contentTypes };
+  }
+
+  return {
+    output,
+    outputDir,
+    client,
+    immutableDirs,
+    rsc: requireEnvironment(environments, 'rsc'),
+    ssr: requireEnvironment(environments, 'ssr'),
+    prebuilt: input.prebuilt,
+    manifestInit: input.manifestInit,
+  };
+}