@timber-js/app 0.2.0-alpha.94 → 0.2.0-alpha.96

package/dist/server/pipeline.d.ts

@@ -119,7 +119,16 @@ export interface PipelineConfig {
      * If this function throws, the pipeline falls back to a bare
      * `new Response(null, { status: denyStatus })`.
      */
-    renderDenyFallback?: (deny: DenySignal, req: Request, responseHeaders: Headers) => Response | Promise<Response>;
+    renderDenyFallback?: (deny: DenySignal, req: Request, responseHeaders: Headers, 
+    /**
+     * The matched route, if available. Provided by both the middleware-stage
+     * and render-stage catch blocks (matching runs before middleware). When
+     * present, the renderer should resolve the deny status file against the
+     * matched chain so colocated `403.tsx`/`4xx.tsx`/`401.json` files are
+     * picked up. Falls back to the root-only chain when omitted (e.g. for
+     * deny()s thrown before route matching could complete). See TIM-822.
+     */
+    match?: RouteMatch) => Response | Promise<Response>;
 }
 /**
  * Run segment param coercion on the matched route's segments.

package/dist/server/pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/server/pipeline.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/server/pipeline.ts"],"names":[],"mappings":"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"}

package/dist/server/rsc-entry/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/index.ts"],"names":[],"mappings":"AAuBA,OAAO,uCAAuC,CAAC;AA0C/C,OAAO,EAKL,KAAK,mBAAmB,EACzB,MAAM,cAAc,CAAC;AAoCtB;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,mBAAmB,EAAE,KAAK,IAAI,GACtF,IAAI,CAEN;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAE5E;AA4jBD,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAInE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;8BAnTrC,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC;AAqThD,wBAAiE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/index.ts"],"names":[],"mappings":"AAuBA,OAAO,uCAAuC,CAAC;AA0C/C,OAAO,EAKL,KAAK,mBAAmB,EACzB,MAAM,cAAc,CAAC;AAoCtB;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,mBAAmB,EAAE,KAAK,IAAI,GACtF,IAAI,CAEN;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAE5E;AAmnBD,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAInE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;8BA7UrC,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC;AA+UhD,wBAAiE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.94",
+  "version": "0.2.0-alpha.96",
   "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",
@@ -110,11 +110,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "vite build --config vite.lib.config.ts && tsc --emitDeclarationOnly --project tsconfig.json --outDir dist",
-    "typecheck": "tsgo --noEmit",
-    "prepublishOnly": "pnpm run build"
-  },
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/context-async-hooks": "^2.6.1",
@@ -157,5 +152,9 @@
   },
   "engines": {
     "node": ">=22.12.0"
+  },
+  "scripts": {
+    "build": "vite build --config vite.lib.config.ts && tsc --emitDeclarationOnly --project tsconfig.json --outDir dist",
+    "typecheck": "tsgo --noEmit"
   }
-}
+}

package/src/client/browser-dev.ts

@@ -242,6 +242,10 @@ export function setupClientErrorForwarding(hot: Pick<HotInterface, 'send'>): voi
     if (!event.error && !event.message) return;
     // Skip errors during page unload — these are abort-related, not application errors
     if (isPageUnloading()) return;
+    // Skip framework signal digests (redirect/deny) — these are control-flow
+    // signals, not application errors. They should never surface as dev
+    // overlays even if they escape an error boundary. See TIM-838.
+    if (isFrameworkSignalError(event.error)) return;
 
     const error = event.error;
     hot.send('timber:client-error', {
@@ -256,6 +260,8 @@ export function setupClientErrorForwarding(hot: Pick<HotInterface, 'send'>): voi
     if (!reason) return;
     // Skip rejections during page unload — aborted fetches/streams cause these
     if (isPageUnloading()) return;
+    // Skip framework signal digests (redirect/deny). See TIM-838.
+    if (isFrameworkSignalError(reason)) return;
 
     const message = reason instanceof Error ? reason.message : String(reason);
     const stack = reason instanceof Error ? (reason.stack ?? '') : '';
@@ -267,3 +273,22 @@ export function setupClientErrorForwarding(hot: Pick<HotInterface, 'send'>): voi
     });
   });
 }
+
+/**
+ * Detect errors whose `digest` marks them as a framework control-flow signal
+ * (RedirectSignal, DenySignal). These must never surface as dev overlays —
+ * they are expected during navigation and are handled by the error boundary
+ * and router. Exported for tests.
+ */
+export function isFrameworkSignalError(error: unknown): boolean {
+  if (!error || typeof error !== 'object') return false;
+  const digest = (error as { digest?: unknown }).digest;
+  if (typeof digest !== 'string') return false;
+  try {
+    const parsed = JSON.parse(digest) as { type?: unknown } | null;
+    if (!parsed || typeof parsed !== 'object') return false;
+    return parsed.type === 'redirect' || parsed.type === 'deny';
+  } catch {
+    return false;
+  }
+}

package/src/client/error-boundary.tsx

@@ -20,6 +20,7 @@
 
 import { Component, createElement, type ReactNode } from 'react';
 import { getSsrData } from './ssr-data.js';
+import { getRouterOrNull } from './router-ref.js';
 
 // ─── Page Unload Detection ───────────────────────────────────────────────────
 // Track whether the page is being unloaded (user refreshed or navigated away).
@@ -93,6 +94,13 @@ interface TimberErrorBoundaryState {
   error: Error | null;
 }
 
+// Module-level guard: the first boundary to catch a given redirect digest
+// schedules the navigation and marks it handled here. Subsequent renders
+// (React retries the error-boundary render path multiple times in dev, and
+// outer boundaries that also see the error) become no-ops, preventing
+// duplicate router.navigate() calls.
+const _handledRedirects = new WeakSet<object>();
+
 // ─── Component ───────────────────────────────────────────────────────────────
 
 export class TimberErrorBoundary extends Component<
@@ -138,11 +146,48 @@ export class TimberErrorBoundary extends Component<
     const error = this.state.error;
     const parsed = parseDigest(error);
 
-    // RedirectSignal errors must propagate through all error boundaries
-    // so the SSR shell fails and the pipeline catch block can produce a
-    // proper HTTP redirect response. See design/04-authorization.md.
+    // RedirectSignal handling splits by environment:
+    //
+    // - SSR (no window): re-throw so the Fizz shell fails and the server
+    //   pipeline catch block can produce a proper HTTP 3xx response. See
+    //   design/04-authorization.md.
+    //
+    // - Client (window exists): a RedirectSignal that leaked into the RSC
+    //   Flight payload during client navigation would otherwise bubble past
+    //   every error boundary to `window.onerror`, which in dev triggers the
+    //   Vite error overlay (false positive — navigation itself works).
+    //   Instead, ask the router to perform an SPA navigation to the target
+    //   and render nothing while it takes over. The router's own catch path
+    //   handles cross-origin / hard navigations. See TIM-838.
     if (parsed?.type === 'redirect') {
-      throw error;
+      if (typeof window === 'undefined') {
+        throw error;
+      }
+      // Dedupe: React may render the error-boundary fallback path more
+      // than once for a single caught error (dev-mode double render, and
+      // additional boundaries above us in the tree). Only schedule the
+      // navigation on the first render that sees this error instance.
+      const alreadyHandled = _handledRedirects.has(error);
+      if (!alreadyHandled) {
+        _handledRedirects.add(error);
+        const router = getRouterOrNull();
+        if (router) {
+          // Schedule the navigation outside the render phase to avoid
+          // setState-during-render warnings from router state updates.
+          queueMicrotask(() => {
+            router.navigate(parsed.location, { replace: true }).catch(() => {
+              // Fall back to a hard navigation if the soft navigation fails.
+              window.location.href = parsed.location;
+            });
+          });
+        } else {
+          // No router available (shouldn't happen post-bootstrap) — fall
+          // back to a hard navigation so the user still ends up at the
+          // target.
+          window.location.href = parsed.location;
+        }
+      }
+      return null;
     }
 
     // If this boundary has a status filter, check whether the error matches.

package/src/fonts/pipeline.ts

@@ -31,6 +31,7 @@ import type { CachedFont } from './google.js';
 import { generateVariableClass, generateFontFamilyClass, generateFontFaces } from './css.js';
 import { generateFallbackCss } from './fallbacks.js';
 import { generateLocalFontFaces } from './local.js';
+import { VirtualFontCssIdMap } from './virtual-modules.js';
 
 /**
  * Backwards-compatible alias for the registry shape that the standalone
@@ -55,6 +56,18 @@ export class FontPipeline {
    */
   private readonly _entries = new Map<string, FontEntry>();
 
+  /**
+   * Per-importer virtual CSS module id registry. Populated by the
+   * transform hook when it inlines a font function call, read by the
+   * plugin's `load` hook when Vite asks for the module's CSS source.
+   *
+   * Lives on the pipeline (rather than a module-level singleton) so
+   * multiple parallel plugin instances — e.g. in the test suite — cannot
+   * collide on the hash-to-importer map. Also makes `clear()` reset the
+   * id map alongside the font entries so test fixtures start clean.
+   */
+  readonly cssIdMap = new VirtualFontCssIdMap();
+
   // ── Read-only accessors ─────────────────────────────────────────────────
 
   /** Number of registered fonts. */
@@ -179,6 +192,7 @@ export class FontPipeline {
   /** Drop every registered font. Used by tests and rebuild flows. */
   clear(): void {
     this._entries.clear();
+    this.cssIdMap.clear();
   }
 
   // ── Derived views ───────────────────────────────────────────────────────
@@ -216,6 +230,31 @@ export class FontPipeline {
     }
     return cssParts.join('\n\n');
   }
+
+  /**
+   * Render the combined CSS for every font registered from a specific
+   * importer file. This is the anchor point for the per-importer virtual
+   * CSS module (`virtual:timber-font-css/<hash>.css`) that the transform
+   * hook injects as a side-effect import.
+   *
+   * Scoping by importer means two concurrent requests rendering different
+   * routes cannot see each other's font CSS: each importer's virtual
+   * module only contains CSS for fonts that module registered. It also
+   * means Vite's CSS HMR can surgically reload just the affected importer
+   * when a single file changes, rather than rebuilding one giant blob.
+   *
+   * Returns an empty string when no fonts are registered under `importer`.
+   * The empty string is semantically equivalent to "no CSS" — Vite's CSS
+   * pipeline handles it as a valid empty CSS module.
+   */
+  getCssForSegment(importer: string): string {
+    const cssParts: string[] = [];
+    for (const entry of this._entries.values()) {
+      if (entry.importer !== importer) continue;
+      cssParts.push(renderEntryCss(entry));
+    }
+    return cssParts.join('\n\n');
+  }
 }
 
 /**

package/src/fonts/transform.ts

@@ -19,7 +19,6 @@ import {
   detectDynamicFontCallAst,
 } from './ast.js';
 import type { FontPipeline } from './pipeline.js';
-import { VIRTUAL_FONT_CSS_REGISTER } from './virtual-modules.js';
 
 /**
  * Regex that matches imports from either `@timber/fonts/google` or
@@ -306,11 +305,46 @@ function transformLocalFonts(
 /**
  * Run the timber-fonts transform pass on a single source file.
  *
- * Returns the rewritten code (with font calls inlined and the side-effect
- * `virtual:timber-font-css-register` import prepended) or `null` if the
- * file does not import from any timber-fonts virtual module and therefore
- * needs no transformation.
+ * Returns the rewritten code (with font calls inlined and a side-effect
+ * `import 'virtual:timber-font-css/<hash>.css'` prepended so Vite's CSS
+ * pipeline owns the font CSS) or `null` if the file does not import from
+ * any timber-fonts virtual module and therefore needs no transformation.
  */
+/**
+ * File extensions that may contain real font imports. Only JS/TS module
+ * variants are scanned. Excluding non-JS extensions (.mdx, .md, .css,
+ * .json, etc.) prevents false-positive matches on text that mentions a
+ * font specifier inside documentation, code fences, or asset metadata.
+ *
+ * Why this matters: the heuristic below is a substring check (`code.includes`),
+ * not an AST parse. An MDX file documenting Next.js font compatibility
+ * (e.g. a code fence containing `import { Inter } from 'next/font/google'`)
+ * would trigger the same match as a real import. The transform then prepends
+ * `import 'virtual:timber-font-css/<hash>.css';` to the file, which breaks
+ * downstream parsers that require the file to start with their own delimiter
+ * — most notably MDX frontmatter, which must start at line 1 col 1 for
+ * `remark-frontmatter` to recognise it. See TIM-840.
+ */
+const FONT_IMPORT_SCANNABLE_EXTENSIONS = new Set([
+  '.js',
+  '.jsx',
+  '.ts',
+  '.tsx',
+  '.mjs',
+  '.cjs',
+  '.mts',
+  '.cts',
+]);
+
+function hasScannableExtension(id: string): boolean {
+  // Strip Vite query suffixes (?v=..., ?import, ?worker, etc.) before
+  // matching so files imported with a query string are still scanned.
+  const path = id.split('?', 1)[0];
+  const dot = path.lastIndexOf('.');
+  if (dot === -1) return false;
+  return FONT_IMPORT_SCANNABLE_EXTENSIONS.has(path.slice(dot).toLowerCase());
+}
+
 export function runFontsTransform(
   code: string,
   id: string,
@@ -320,6 +354,14 @@ export function runFontsTransform(
   // Skip virtual modules and node_modules
   if (id.startsWith('\0') || id.includes('node_modules')) return null;
 
+  // Only scan JS/TS module variants. .mdx, .md, .css, .json, etc. may
+  // mention font specifiers in documentation or asset metadata without
+  // ever importing them — a substring match would be a false positive
+  // and the prepended virtual CSS import would corrupt downstream
+  // parsers (e.g. MDX frontmatter, which must start at line 1).
+  // See TIM-840.
+  if (!hasScannableExtension(id)) return null;
+
   const hasGoogleImport =
     code.includes('@timber/fonts/google') ||
     code.includes('@timber-js/app/fonts/google') ||
@@ -341,10 +383,21 @@ export function runFontsTransform(
   }
 
   if (transformedCode !== code) {
-    // Inject side-effect import that registers font CSS on globalThis.
-    // The RSC entry reads globalThis.__timber_font_css to inline a <style> tag.
+    // Inject a side-effect import for this file's per-importer virtual
+    // CSS module. The `.css` suffix is what makes Vite's CSS pipeline
+    // own the module — in dev that gives us HMR + source maps, and in
+    // production @vitejs/plugin-rsc walks the RSC module graph via
+    // `collectCss`, finds this virtual CSS import, and injects a
+    // `<link rel="stylesheet" data-rsc-css-href=...>` through React
+    // Float's preinit mechanism (the same path component CSS rides on).
+    //
+    // The per-importer id guarantees two concurrent requests rendering
+    // different routes never see each other's font CSS: each importer's
+    // virtual module only resolves to the fonts that importer registered
+    // via `FontPipeline.getCssForSegment(importer)`. See TIM-828.
     if (pipeline.size() > 0) {
-      transformedCode = `import '${VIRTUAL_FONT_CSS_REGISTER}';\n` + transformedCode;
+      const virtualCssId = pipeline.cssIdMap.idFor(id);
+      transformedCode = `import '${virtualCssId}';\n` + transformedCode;
     }
     return { code: transformedCode, map: null };
   }

package/src/fonts/virtual-modules.ts

@@ -9,13 +9,27 @@
  *   transform hook hasn't run yet, or when an unknown font is referenced
  *   via the default export proxy).
  * - `@timber/fonts/local` — exports `localFont()` as a fallback default.
- * - `virtual:timber-font-css-register` — side-effect module that sets the
- *   combined `@font-face` CSS on `globalThis.__timber_font_css`. The RSC
- *   entry reads this at render time to inline a `<style>` tag.
+ * - `virtual:timber-font-css/<hash>.css` — per-importer CSS module that
+ *   holds the combined `@font-face` + fallback + class CSS for every
+ *   font registered under that importer. The transform hook injects a
+ *   side-effect `import 'virtual:timber-font-css/<hash>.css'` into each
+ *   file that calls a font function, so Vite's CSS pipeline picks it up
+ *   like any other CSS asset. @vitejs/plugin-rsc's `collectCss` walks
+ *   the RSC module graph, finds the virtual module, and injects a
+ *   `<link rel="stylesheet" data-rsc-css-href=...>` via React Float —
+ *   the same machinery component CSS rides on (TIM-828).
+ *
+ *   The `.css` suffix is load-bearing: Vite's `isCSSRequest` regex matches
+ *   on file extension, so keeping it in the virtual id is how we tell
+ *   Vite's CSS pipeline (dev HMR + build asset emission) that this
+ *   module is CSS. The old `virtual:timber-font-css-register` side-effect
+ *   module, `globalThis.__timber_font_css` channel, and inline `<style>`
+ *   tag in the RSC entry were all removed in TIM-828.
  *
  * Design doc: 24-fonts.md
  */
 
+import { createHash } from 'node:crypto';
 import type { ExtractedFont, FontFaceDescriptor } from './types.js';
 import { generateVariableClass, generateFontFamilyClass, generateFontFaces } from './css.js';
 import { generateFallbackCss } from './fallbacks.js';
@@ -26,8 +40,62 @@ export const VIRTUAL_LOCAL = '@timber/fonts/local';
 export const RESOLVED_GOOGLE = '\0@timber/fonts/google';
 export const RESOLVED_LOCAL = '\0@timber/fonts/local';
 
-export const VIRTUAL_FONT_CSS_REGISTER = 'virtual:timber-font-css-register';
-export const RESOLVED_FONT_CSS_REGISTER = '\0virtual:timber-font-css-register';
+/**
+ * Prefix used for the per-importer virtual CSS modules. The full id is
+ * `virtual:timber-font-css/<hash>.css` where `<hash>` is a short SHA-256
+ * digest of the importer path. We encode the hash (not the path itself)
+ * so the id stays filesystem-safe and opaque to downstream consumers.
+ */
+export const VIRTUAL_FONT_CSS_PREFIX = 'virtual:timber-font-css/';
+export const VIRTUAL_FONT_CSS_SUFFIX = '.css';
+export const RESOLVED_FONT_CSS_PREFIX = '\0' + VIRTUAL_FONT_CSS_PREFIX;
+
+/**
+ * In-memory map from the short hash used in virtual module ids back to
+ * the absolute importer path. Populated by `virtualFontCssIdFor()` when
+ * the transform hook registers an importer and read by the plugin's
+ * `load` hook when Vite asks for the CSS content.
+ *
+ * Scoped to a single `FontPipeline` instance to avoid cross-plugin-
+ * instance collisions during multi-build pipelines.
+ */
+export class VirtualFontCssIdMap {
+  private readonly map = new Map<string, string>();
+
+  /**
+   * Return a stable virtual module id for `importer`. Calling this twice
+   * with the same importer returns the same id. Registering under an
+   * existing hash is idempotent.
+   */
+  idFor(importer: string): string {
+    const hash = createHash('sha256').update(importer).digest('hex').slice(0, 16);
+    this.map.set(hash, importer);
+    return `${VIRTUAL_FONT_CSS_PREFIX}${hash}${VIRTUAL_FONT_CSS_SUFFIX}`;
+  }
+
+  /** Decode the importer from a resolved (or unresolved) virtual css id. */
+  importerFor(id: string): string | undefined {
+    const body = id.startsWith('\0') ? id.slice(1) : id;
+    if (!body.startsWith(VIRTUAL_FONT_CSS_PREFIX)) return undefined;
+    if (!body.endsWith(VIRTUAL_FONT_CSS_SUFFIX)) return undefined;
+    const hash = body.slice(
+      VIRTUAL_FONT_CSS_PREFIX.length,
+      body.length - VIRTUAL_FONT_CSS_SUFFIX.length
+    );
+    return this.map.get(hash);
+  }
+
+  /** True if `id` is any form of the virtual font css module. */
+  matches(id: string): boolean {
+    const body = id.startsWith('\0') ? id.slice(1) : id;
+    return body.startsWith(VIRTUAL_FONT_CSS_PREFIX) && body.endsWith(VIRTUAL_FONT_CSS_SUFFIX);
+  }
+
+  /** Drop every registered mapping. Used by tests. */
+  clear(): void {
+    this.map.clear();
+  }
+}
 
 /**
  * Convert a font family name to a PascalCase export name.

package/src/plugins/fonts.ts

@@ -32,10 +32,8 @@ import { emitFontAssets, writeFontManifest, groupCachedFontsByFamily } from '../
 import {
   RESOLVED_GOOGLE,
   RESOLVED_LOCAL,
-  RESOLVED_FONT_CSS_REGISTER,
   VIRTUAL_GOOGLE,
   VIRTUAL_LOCAL,
-  VIRTUAL_FONT_CSS_REGISTER,
   generateGoogleVirtualModule,
   generateLocalVirtualModule,
 } from '../fonts/virtual-modules.js';
@@ -68,12 +66,34 @@ export function timberFonts(ctx: PluginContext): Plugin {
     name: 'timber-fonts',
 
     /**
-     * Resolve `@timber/fonts/google`, `@timber/fonts/local`, and
-     * `virtual:timber-font-css-register` virtual modules.
+     * `enforce: 'pre'` is load-bearing for the font CSS pipeline (TIM-828).
+     *
+     * The transform hook injects a side-effect
+     * `import 'virtual:timber-font-css/<hash>.css'` into every file that
+     * registers a font. @vitejs/plugin-rsc's `rsc:rsc-css-export-transform`
+     * later inspects each server component's source for CSS imports and
+     * wraps the default export in `import.meta.viteRsc.loadCss(...)` so
+     * the matched virtual CSS module ends up `preinit`'d as
+     * `<link rel="stylesheet" data-rsc-css-href=...>`.
+     *
+     * If timber-fonts ran in normal order it would inject the CSS import
+     * *after* plugin-rsc had already scanned the source, and the font CSS
+     * would be silently dropped from the rendered HTML. Running in the
+     * `pre` slot guarantees our injected import is visible to plugin-rsc's
+     * later CSS-export scan.
+     */
+    enforce: 'pre',
+
+    /**
+     * Resolve `@timber/fonts/google`, `@timber/fonts/local`, and the
+     * per-importer `virtual:timber-font-css/<hash>.css` modules injected
+     * by the transform hook.
      *
      * Strips the `\0` prefix added by the RSC plugin's re-imports and the
      * absolute root prefix added by SSR build entries before comparing
-     * against the public IDs.
+     * against the public IDs. The `.css` suffix on font-css ids is
+     * preserved so Vite's CSS pipeline (`isCSSRequest`) recognises the
+     * resolved id as CSS.
      */
     resolveId(id: string) {
       let cleanId = id.startsWith('\0') ? id.slice(1) : id;
@@ -88,27 +108,42 @@ export function timberFonts(ctx: PluginContext): Plugin {
 
       if (cleanId === VIRTUAL_GOOGLE) return RESOLVED_GOOGLE;
       if (cleanId === VIRTUAL_LOCAL) return RESOLVED_LOCAL;
-      if (cleanId === VIRTUAL_FONT_CSS_REGISTER) return RESOLVED_FONT_CSS_REGISTER;
+      if (pipeline.cssIdMap.matches(cleanId)) return '\0' + cleanId;
       return null;
     },
 
     /**
      * Return generated source for font virtual modules.
      *
-     * `virtual:timber-font-css-register` is a side-effect module that sets
-     * the combined `@font-face` CSS on `globalThis.__timber_font_css`. The
-     * RSC entry imports it transitively via the layout file and reads
-     * `globalThis.__timber_font_css` at render time to inline a `<style>`
-     * tag. In dev mode we also lazily resolve Google `@font-face`
-     * descriptors from the CDN here, since `buildStart` is a no-op in dev.
+     * The per-importer `virtual:timber-font-css/<hash>.css` modules
+     * return the combined font CSS for the specific importer that
+     * registered them. Vite's CSS pipeline handles injection from here:
+     * in dev the module rides the CSS HMR channel; in production it is
+     * emitted as a real CSS asset and @vitejs/plugin-rsc's `collectCss`
+     * walks the RSC module graph to find it.
+     *
+     * In dev mode we also lazily resolve Google `@font-face` descriptors
+     * from the CDN here, since `buildStart` is a no-op in dev.
      */
     async load(id: string) {
       if (id === RESOLVED_GOOGLE) return generateGoogleVirtualModule(pipeline.fonts());
       if (id === RESOLVED_LOCAL) return generateLocalVirtualModule();
 
-      if (id === RESOLVED_FONT_CSS_REGISTER) {
+      if (pipeline.cssIdMap.matches(id)) {
+        const importer = pipeline.cssIdMap.importerFor(id);
+        if (!importer) {
+          // Hash is valid but no importer is registered — return an empty
+          // CSS module rather than `null`. This can happen if Vite's
+          // module graph invalidates the virtual module between the
+          // transform that registered the hash and the load that asks
+          // for it (e.g. after an HMR edit that removes every font from
+          // the file). An empty stylesheet is a valid, safe no-op.
+          return '';
+        }
+
         if (ctx.dev) {
           for (const font of pipeline.googleFonts()) {
+            if (font.importer !== importer) continue;
             if (pipeline.hasFaces(font.id)) continue;
             try {
               const faces = await resolveDevFontFaces(font);
@@ -125,7 +160,7 @@ export function timberFonts(ctx: PluginContext): Plugin {
           }
         }
 
-        return `globalThis.__timber_font_css = ${JSON.stringify(pipeline.getCss())};`;
+        return pipeline.getCssForSegment(importer);
       }
       return null;
     },

package/src/plugins/mdx.ts

@@ -11,6 +11,8 @@
 import type { Plugin } from 'vite';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
 import type { PluginContext } from '../plugin-context.js';
 
 const MDX_EXTENSIONS = ['mdx', 'md'];
@@ -54,15 +56,45 @@ 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
+ * — `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).
+ *
+ * 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 {
+      return undefined;
+    }
   }
 }
 
@@ -80,7 +112,7 @@ 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
+    const createMdxPlugin = (await tryImport('@mdx-js/rollup', ctx.root)) as
       | ((options?: Record<string, unknown>) => Plugin)
       | undefined;
 
@@ -99,10 +131,11 @@ export function timberMdx(ctx: PluginContext): Plugin {
 
     const mdxConfig = ctx.config.mdx ?? {};
 
-    // Auto-register frontmatter plugins
+    // 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');
-    const remarkMdxFrontmatter = await tryImport('remark-mdx-frontmatter');
+    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);