@timber-js/app 0.2.0-alpha.167 → 0.2.0-alpha.169

package/src/fonts/transform.ts

@@ -213,7 +213,11 @@ export function runFontsTransform(
 
   const s = new MagicString(code);
 
-  // Process each call site.
+  // Extract and validate all call sites before mutating the pipeline.
+  // If any extraction fails (emitError throws), the pipeline is untouched
+  // so the previous valid CSS stays intact (TIM-1087).
+  const pending: { extracted: ExtractedFont; site: (typeof analysis.callSites)[0] }[] = [];
+
   for (const site of analysis.callSites) {
     if (site.binding.provider === 'google') {
       const family = site.binding.importedName.replace(/_/g, ' ');
@@ -232,24 +236,22 @@ export function runFontsTransform(
       const fontStack = buildFontStack(family);
       const display = config!.display ?? 'swap';
 
-      const extracted: ExtractedFont = {
-        id: fontId,
-        family,
-        provider: 'google',
-        weights: normalizeWeightArray(config!.weight),
-        styles: normalizeStyleArray(config!.style),
-        subsets: config!.subsets ?? ['latin'],
-        display,
-        variable: config!.variable,
-        className,
-        fontFamily: fontStack,
-        importer: id,
-      };
-
-      pipeline.pruneFor(id, family);
-      pipeline.register(extracted);
-
-      s.overwrite(site.replaceStart, site.replaceEnd, buildFontResultLiteral(extracted));
+      pending.push({
+        site,
+        extracted: {
+          id: fontId,
+          family,
+          provider: 'google',
+          weights: normalizeWeightArray(config!.weight),
+          styles: normalizeStyleArray(config!.style),
+          subsets: config!.subsets ?? ['latin'],
+          display,
+          variable: config!.variable,
+          className,
+          fontFamily: fontStack,
+          importer: id,
+        },
+      });
     } else {
       // local font
       const config = extractLocalFontConfigFromNode(site.configNode);
@@ -261,14 +263,18 @@ export function runFontsTransform(
         );
       }
 
-      const extracted = processLocalFont(config!, id);
-      pipeline.pruneFor(id, extracted.family);
-      pipeline.register(extracted);
-
-      s.overwrite(site.replaceStart, site.replaceEnd, buildFontResultLiteral(extracted));
+      pending.push({ site, extracted: processLocalFont(config!, id) });
     }
   }
 
+  // All extractions succeeded — now prune stale entries and register.
+  // Handles family renames and deleted font calls (TIM-1087).
+  pipeline.pruneImporter(id);
+  for (const { extracted, site } of pending) {
+    pipeline.register(extracted);
+    s.overwrite(site.replaceStart, site.replaceEnd, buildFontResultLiteral(extracted));
+  }
+
   // Remove font import declarations. Use a Set to avoid double-removing
   // when multiple bindings come from the same ImportDeclaration.
   const removedRanges = new Set<string>();

package/src/plugins/adapter-build.ts

@@ -15,6 +15,7 @@
 
 import type { Plugin } from 'vite';
 import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
 import { readFile, writeFile } from 'node:fs/promises';
 import type { PluginContext } from '../plugin-context.js';
 import type { TimberPlatformAdapter, TimberConfig } from '../adapters/types.js';
@@ -95,6 +96,116 @@ export function timberAdapterBuild(ctx: PluginContext): Plugin {
   };
 }
 
+/**
+ * Parse the RSC assets manifest at `manifestPath`. Tries JSON.parse first
+ * (fast path for plain-string manifests); falls back to a dynamic import()
+ * for manifests that contain runtime expressions from renderBuiltUrl.
+ * Returns null if both paths fail.
+ */
+async function parseRscManifest(
+  manifestPath: string,
+  content: string
+): Promise<Record<string, unknown> | null> {
+  const jsonStr = content.replace(/^export default\s*/, '').replace(/;?\s*$/, '');
+  try {
+    return JSON.parse(jsonStr);
+  } catch {
+    // Not strict JSON — manifest likely contains renderBuiltUrl runtime
+    // expressions. Fall back to evaluating the module directly.
+  }
+
+  // When renderBuiltUrl's runtime expressions reference external helpers
+  // not defined in the manifest file, this import will fail. That's an
+  // inherent limitation: runtime-computed URLs can't be resolved at build
+  // time for <link> tag injection. The warning below provides observability.
+  try {
+    const url = pathToFileURL(manifestPath).href;
+    const mod = await import(`${url}?t=${Date.now()}`);
+    return mod.default ?? null;
+  } catch (err) {
+    swallow(err, `failed to evaluate RSC assets manifest: ${manifestPath}`, { level: 'warn' });
+    return null;
+  }
+}
+
+/**
+ * Replace all `"js": [...]` array contents with `"js": []` using balanced
+ * bracket matching. Handles nested brackets from runtime expressions like
+ * `__rbu("path/to/[slug]/file.js")`.
+ */
+function clearJsArrays(src: string): string {
+  const pattern = /"js"\s*:\s*\[/g;
+  let result = '';
+  let lastEnd = 0;
+  let match: RegExpExecArray | null;
+
+  while ((match = pattern.exec(src)) !== null) {
+    const arrayStart = match.index + match[0].length;
+    let depth = 1;
+    let i = arrayStart;
+    while (i < src.length && depth > 0) {
+      if (src[i] === '[') depth++;
+      else if (src[i] === ']') depth--;
+      i++;
+    }
+    result += src.slice(lastEnd, match.index) + '"js": []';
+    lastEnd = i;
+  }
+  result += src.slice(lastEnd);
+  return result;
+}
+
+/**
+ * Replace `"bootstrapScriptContent": <value>` with an empty string. The
+ * value may be a JS expression (e.g., concatenation with runtime helpers),
+ * not a simple string literal. Scans forward from the colon, tracking
+ * balanced parens and brackets, and stops at the next unbalanced `,` or `}`.
+ */
+function clearBootstrapScriptContent(src: string): string {
+  const key = '"bootstrapScriptContent"';
+  const idx = src.indexOf(key);
+  if (idx === -1) return src;
+
+  // Find the colon after the key
+  const colonIdx = src.indexOf(':', idx + key.length);
+  if (colonIdx === -1) return src;
+
+  // Skip whitespace after colon
+  let valStart = colonIdx + 1;
+  while (valStart < src.length && /\s/.test(src[valStart])) valStart++;
+
+  // Scan forward to find the end of the value expression
+  let i = valStart;
+  let depth = 0;
+  let inString = false;
+  let stringChar = '';
+
+  while (i < src.length) {
+    const ch = src[i];
+    if (inString) {
+      if (ch === '\\') {
+        i += 2;
+        continue;
+      }
+      if (ch === stringChar) inString = false;
+    } else {
+      if (ch === '"' || ch === "'") {
+        inString = true;
+        stringChar = ch;
+      } else if (ch === '(' || ch === '[') {
+        depth++;
+      } else if (ch === ')' || ch === ']') {
+        depth--;
+      } else if (depth === 0 && (ch === ',' || ch === '}' || ch === '\n')) {
+        break;
+      }
+    }
+    i++;
+  }
+
+  return src.slice(0, idx) + '"bootstrapScriptContent": ""' + src.slice(i);
+}
+
 /**
  * Strip JS references from the RSC plugin's assets manifest files.
  *
@@ -126,13 +237,8 @@ export async function mergeRscAssetsManifest(
     return;
   }
 
-  const jsonStr = content.replace(/^export default\s*/, '').replace(/;?\s*$/, '');
-  let manifest: Record<string, unknown>;
-  try {
-    manifest = JSON.parse(jsonStr);
-  } catch {
-    return;
-  }
+  const manifest = await parseRscManifest(manifestPath, content);
+  if (!manifest) return;
 
   // Merge serverResources CSS into buildManifest.css.
   // Keys in serverResources are root-relative (e.g., "app/layout.tsx" or
@@ -175,7 +281,7 @@ export async function mergeRscAssetsManifest(
   }
 }
 
-async function stripJsFromRscAssetsManifests(buildDir: string): Promise<void> {
+export async function stripJsFromRscAssetsManifests(buildDir: string): Promise<void> {
   const manifestName = '__vite_rsc_assets_manifest.js';
   const paths = [join(buildDir, 'rsc', manifestName), join(buildDir, 'ssr', manifestName)];
 
@@ -187,17 +293,29 @@ async function stripJsFromRscAssetsManifests(buildDir: string): Promise<void> {
       continue;
     }
 
+    // Try JSON.parse to check if we can safely re-serialize
     const jsonStr = content.replace(/^export default\s*/, '').replace(/;?\s*$/, '');
-    let manifest: Record<string, unknown>;
+    let isStrictJson = true;
+    let manifest: Record<string, unknown> | null = null;
     try {
       manifest = JSON.parse(jsonStr);
-    } catch (err) {
-      swallow(err, `corrupted RSC assets manifest: ${path}`, { level: 'warn' });
+    } catch {
+      isStrictJson = false;
+    }
+
+    if (!isStrictJson) {
+      // Manifest contains renderBuiltUrl runtime expressions — cannot
+      // safely re-serialize with JSON.stringify. Use targeted text
+      // transforms to clear JS arrays and bootstrapScriptContent.
+      let rewritten = content;
+      rewritten = clearJsArrays(rewritten);
+      rewritten = clearBootstrapScriptContent(rewritten);
+      await writeFile(path, rewritten);
       continue;
     }
 
     // Clear JS from clientReferenceDeps — preserves CSS
-    const deps = manifest.clientReferenceDeps as
+    const deps = manifest?.clientReferenceDeps as
       | Record<string, { js: string[]; css: string[] }>
       | undefined;
     if (deps) {
@@ -206,7 +324,7 @@ async function stripJsFromRscAssetsManifests(buildDir: string): Promise<void> {
       }
     }
 
-    manifest.bootstrapScriptContent = '';
+    if (manifest) manifest.bootstrapScriptContent = '';
 
     await writeFile(path, `export default ${JSON.stringify(manifest, null, 2)};\n`);
   }

package/src/plugins/entries.ts

@@ -154,6 +154,7 @@ function generateConfigModule(ctx: PluginContext): string {
     // Per-build deployment ID for version skew detection (TIM-446).
     // Null in dev mode — HMR handles code updates without full reloads.
     deploymentId: ctx.deploymentId ?? null,
+    clientSegmentCache: ctx.config.clientSegmentCache ?? false,
     // Browser log forwarding threshold — used by buildClientScripts to
     // decide whether /@vite/client is needed when clientJavascript is
     // disabled. See TIM-1152.
@@ -174,23 +175,39 @@ function generateConfigModule(ctx: PluginContext): string {
 }
 
 /**
- * Detect the user's instrumentation.ts file at the project root.
+ * Detect a user convention file at both root and src/.
  *
- * Checks for instrumentation.ts, .js, and .mjs — matching the same
- * extensions as timber.config.ts detection.
+ * Root takes precedence over src/, extension priority: .ts > .js > .mjs.
+ * Used for instrumentation.ts, timber.cache.ts, and similar file conventions.
  */
-export function detectInstrumentationFile(root: string): string | null {
+export function detectConventionFile(root: string, basename: string): string | null {
   const extensions = ['.ts', '.js', '.mjs'];
   const dirs = [root, resolve(root, 'src')];
   for (const dir of dirs) {
     for (const ext of extensions) {
-      const candidate = resolve(dir, `instrumentation${ext}`);
+      const candidate = resolve(dir, `${basename}${ext}`);
       if (existsSync(candidate)) return candidate;
     }
   }
   return null;
 }
 
+export function detectInstrumentationFile(root: string): string | null {
+  return detectConventionFile(root, 'instrumentation');
+}
+
+/**
+ * Detect the user's timber.cache file.
+ *
+ * This file holds runtime cache instances (cacheHandler, cdnPurge)
+ * that cannot be JSON-serialized. Separating them from timber.config.ts
+ * prevents the RSC build from pulling build-time deps (adapters, MDX,
+ * rollup) into the runtime bundle. See TIM-1211.
+ */
+export function detectCacheFile(root: string): string | null {
+  return detectConventionFile(root, 'timber.cache');
+}
+
 /**
  * Generate the virtual:timber-instrumentation module source.
  *
@@ -202,9 +219,6 @@ export function detectInstrumentationFile(root: string): string | null {
  */
 export function generateInstrumentationModule(instrumentationPath: string | null): string {
   if (instrumentationPath) {
-    // Use the absolute path so the bundler can resolve and include it.
-    // The dynamic import ensures the file is loaded lazily and errors
-    // in the user's code don't prevent the module from being parsed.
     return [
       '// Auto-generated instrumentation loader — do not edit.',
       '// Generated by timber-entries plugin.',
@@ -226,48 +240,33 @@ export function generateInstrumentationModule(instrumentationPath: string | null
   ].join('\n');
 }
 
-/**
- * Detect the user's timber.config file at the project root.
- * Returns the absolute path or null if not found.
- */
-function detectConfigFile(root: string): string | null {
-  const names = ['timber.config.ts', 'timber.config.js', 'timber.config.mjs'];
-  for (const name of names) {
-    const candidate = resolve(root, name);
-    if (existsSync(candidate)) return candidate;
-  }
-  return null;
-}
-
 /**
  * Generate the virtual:timber-cache-handler module source.
  *
- * When the user's config has a cacheHandler, generates a module that
- * dynamically imports the config file and extracts the cacheHandler.
- * The cacheHandler is a class instance (e.g. RedisCacheHandler) that
- * cannot be JSON-serialized into virtual:timber-config, so it must
- * be loaded at runtime via dynamic import. See TIM-599.
+ * When the user's timber.cache.ts exists, generates a module that
+ * dynamically imports it and extracts cacheHandler and cdnPurge.
+ * These are class instances (e.g. RedisCacheHandler) that cannot be
+ * JSON-serialized into virtual:timber-config, so they must be loaded
+ * at runtime via dynamic import.
+ *
+ * timber.cache.ts exports: default cacheHandler, named cdnPurge.
+ *
+ * See TIM-1211, TIM-599.
  */
-function generateCacheHandlerModule(
-  configPath: string | null,
-  hasCacheHandler: boolean,
-  hasCdnPurge: boolean
-): string {
-  if (configPath && (hasCacheHandler || hasCdnPurge)) {
+export function generateCacheHandlerModule(cachePath: string | null): string {
+  if (cachePath) {
     return [
       '// Auto-generated cache handler loader — do not edit.',
       '// Generated by timber-entries plugin.',
       '',
       `export default async function loadCacheHandler() {`,
-      `  const mod = await import(${JSON.stringify(configPath)});`,
-      `  const config = mod.default ?? mod;`,
-      `  return config.cacheHandler ?? null;`,
+      `  const mod = await import(${JSON.stringify(cachePath)});`,
+      `  return mod.default ?? null;`,
       `}`,
       '',
       `export async function loadCdnPurgeHandler() {`,
-      `  const mod = await import(${JSON.stringify(configPath)});`,
-      `  const config = mod.default ?? mod;`,
-      `  return config.cdnPurge ?? null;`,
+      `  const mod = await import(${JSON.stringify(cachePath)});`,
+      `  return mod.cdnPurge ?? null;`,
       `}`,
     ].join('\n');
   }
@@ -275,7 +274,7 @@ function generateCacheHandlerModule(
   return [
     '// Auto-generated cache handler loader — do not edit.',
     '// Generated by timber-entries plugin.',
-    '// No cacheHandler or cdnPurge configured in timber.config.',
+    '// No timber.cache.ts found.',
     '',
     `export default async function loadCacheHandler() {`,
     `  return null;`,
@@ -352,10 +351,8 @@ export function timberEntries(ctx: PluginContext): Plugin {
         return generateInstrumentationModule(instrumentationPath);
       }
       if (id === RESOLVED_CACHE_HANDLER_ID) {
-        const configPath = detectConfigFile(ctx.root);
-        const hasCacheHandler = ctx.config.cacheHandler != null;
-        const hasCdnPurge = ctx.config.cdnPurge != null;
-        return generateCacheHandlerModule(configPath, hasCacheHandler, hasCdnPurge);
+        const cachePath = detectCacheFile(ctx.root);
+        return generateCacheHandlerModule(cachePath);
       }
       return null;
     },

package/src/plugins/fonts.ts

@@ -18,6 +18,7 @@
  * Design doc: 24-fonts.md
  */
 
+import { parseAst } from 'vite';
 import type { Plugin, ResolvedConfig, ViteDevServer } from 'vite';
 import type { PluginContext } from '../plugin-context.js';
 import {
@@ -224,6 +225,35 @@ export function timberFonts(ctx: PluginContext): Plugin {
      */
     buildStart() {},
 
+    /**
+     * Prune stale font entries when a module that previously imported fonts
+     * no longer contains any font import. The transform hook's `filter.code`
+     * skips such modules, so without this hook the old entries would persist
+     * until dev restart. See TIM-1087.
+     */
+    async hotUpdate({ type, file, read }) {
+      if (!pipeline.hasImporter(file)) return;
+      if (type === 'delete') {
+        pipeline.pruneImporter(file);
+        return;
+      }
+      const code = await read();
+      const hasFontImport =
+        code.includes('@timber/fonts/') ||
+        code.includes('@timber-js/app/fonts/') ||
+        code.includes('next/font/');
+      if (hasFontImport) return;
+      // Only prune if the new source parses successfully. A syntax error
+      // means the HMR update will fail and the old module stays active —
+      // pruning would leave it without font CSS until the next valid save.
+      try {
+        parseAst(code, { lang: 'tsx' });
+      } catch {
+        return;
+      }
+      pipeline.pruneImporter(file);
+    },
+
     /**
      * Scan source files for font function calls and extract static config.
      *

package/src/plugins/server-bundle.ts

@@ -19,23 +19,15 @@ import type { Plugin } from 'vite';
 // Listing explicitly silences Vite's "Automatically externalized" warnings.
 const NODE_BUILTINS: string[] = builtinModules.flatMap((m) => [m, `node:${m}`]);
 
-// Build-time-only packages that must never be bundled into the runtime
-// server environments. With `noExternal: true` rolldown otherwise follows
-// the transitive graph through the user's `timber.config.ts` (loaded by the
-// `virtual:timber-cache-handler` dynamic import) into adapter code, dragging
-// build tooling into the prod server bundle. The most visible symptom is
-// rolldown trying to parse `fsevents.node` as JS and failing with
-// `[UNLOADABLE_DEPENDENCY] … stream did not contain valid UTF-8`.
+// Packages that must never be bundled into the runtime server environments.
+// With `noExternal: true`, rolldown follows all transitive imports. These
+// are build-time-only tools that have no runtime use in a server bundle.
 //
-//   - `nitro`, `@mdx-js/rollup`              — build-time tooling reachable
-//     transitively through adapter modules and timber's own MDX activation.
-//   - `rollup`                                — pulled in by nitro and
-//     @mdx-js/rollup; declares `fsevents` as an optional native dep.
-//   - `fsevents`, `chokidar`                  — native/optional deps of
-//     rollup/vite. They are macOS-only file watchers with no runtime use
-//     in a server bundle.
+// The primary leak path (TIM-988) — `virtual:timber-cache-handler` importing
+// `timber.config.ts` and pulling in adapter/MDX deps — was eliminated by
+// TIM-1211: the cache handler virtual module now imports `timber.cache.ts`
+// instead. These externals are retained as defense-in-depth.
 //
-// Mirrored on both rsc and ssr environments. See TIM-988.
 // Cloudflare runtime modules (cloudflare:workers, cloudflare:sockets, etc.)
 // available at runtime on Workers but must not be bundled.
 const CLOUDFLARE_BUILTINS = [

package/src/server/action-client.ts

@@ -8,7 +8,7 @@
  *   1. Direct call: action(input) → Promise<ActionResult>
  *   2. React useActionState: (prevState, formData) => Promise<ActionResult>
  *
- * See design/08-forms-and-actions.md §"Middleware for Server Actions"
+ * See design/08-forms-and-actions.md §"Middleware and Server Actions"
  */
 
 // ─── ActionError ─────────────────────────────────────────────────────────

package/src/server/middleware-runner.ts

@@ -57,47 +57,3 @@ export async function runMiddlewareChain(
   }
   return undefined;
 }
-
-// ─── Per-Request Middleware Bypass ─────────────────────────────────────────
-
-/**
- * Per-request marker for synthetic re-render requests that should NOT
- * re-execute `middleware.ts`. The action-dispatch wrapper runs middleware
- * once on the inbound action POST; when validation fails on the no-JS
- * path, it builds a synthetic GET that flows through the normal pipeline
- * to render the page with `getFormFlash()` data. Without this marker, the
- * pipeline would run middleware a second time on that synthetic GET.
- *
- * The set is keyed by the synthetic Request object itself, so the entry
- * lives exactly as long as the request and is garbage-collected with it.
- * Cannot be set or detected by user code — there is no header, no URL
- * parameter, nothing on the wire that an attacker could spoof.
- *
- * See TIM-871.
- *
- * @internal — framework use only.
- */
-const middlewareBypassRequests = new WeakSet<Request>();
-
-/**
- * Mark a request so the pipeline skips its middleware phase.
- *
- * Used by `wrap-action-dispatch.ts` for the no-JS form-rerender path.
- *
- * @internal
- */
-export function markRequestBypassMiddleware(req: Request): void {
-  middlewareBypassRequests.add(req);
-}
-
-/**
- * Check whether a request was marked to bypass middleware.
- *
- * Called by `handleRequest` in pipeline-phases.ts before invoking the
- * middleware phase. Returns false for any request not explicitly marked.
- *
- * @internal
- */
-export function shouldBypassMiddleware(req: Request): boolean {
-  return middlewareBypassRequests.has(req);
-}

package/src/server/param-coercion.ts

@@ -132,6 +132,7 @@ export async function coerceSegmentParams(match: RouteMatch): Promise<void> {
       if (!codec) continue; // no codec in schema → keep raw string
 
       const key = segment.paramName;
+      if (!(key in mergeTarget)) continue;
       try {
         mergeTarget[key] = sanitizeParamValue(codec.parse(mergeTarget[key] as string | string[]));
       } catch (err) {

package/src/server/pipeline-phases.ts

@@ -14,7 +14,7 @@
 
 import { canonicalize } from './canonicalize.js';
 import { runProxy } from './proxy.js';
-import { runMiddlewareChain, shouldBypassMiddleware } from './middleware-runner.js';
+import { runMiddlewareChain } from './middleware-runner.js';
 import { withTiming } from './server-timing.js';
 import {
   applyRequestHeaderOverlay,
@@ -66,8 +66,11 @@ function validateInterceptionHeader(raw: string, stripTrailingSlash: boolean): s
 // ─── Phase: Proxy ──────────────────────────────────────────────────────────
 
 /**
- * Run the proxy.ts phase. Calls user proxy code and uses `handleRequest` as
- * the inner `next()` continuation. The proxy resolver was picked at pipeline
+ * Run the proxy.ts phase. Calls user proxy code with a `next()` continuation.
+ *
+ * When `next` is provided, it replaces the default `handleRequest` as the
+ * continuation — this lets the pipeline inject action dispatch between proxy
+ * and route matching (TIM-1213). The proxy resolver was picked at pipeline
  * construction time so the hot path sees no per-request branching on the
  * `ProxyConfig` discriminant.
  */
@@ -76,13 +79,14 @@ export async function runProxyPhase(
   getProxy: ProxyResolver,
   req: Request,
   method: string,
-  path: string
+  path: string,
+  next?: () => Promise<Response>
 ): Promise<PhaseOutcome> {
   const detailed = config.serverTiming === 'detailed';
   try {
     const proxyExport = await getProxy();
-    const proxyFn = () =>
-      runProxy(proxyExport, req, () => handleRequest(config, req, method, path, true));
+    const continuation = next ?? (() => handleRequest(config, req, method, path, true));
+    const proxyFn = () => runProxy(proxyExport, req, continuation);
     const response = await withSpan('timber.proxy', {}, () =>
       detailed ? withTiming('proxy', 'proxy.ts', proxyFn) : proxyFn()
     );
@@ -514,14 +518,8 @@ export async function handleRequest(
       .join('/') || '/';
   setMatchedSegmentPath(segmentPath.startsWith('/') ? segmentPath : `/${segmentPath}`);
 
-  // Bypass middleware for synthetic re-render requests built by the
-  // action-dispatch wrapper after a no-JS form validation failure.
-  // The wrapper has already executed middleware once on the inbound POST;
-  // running it again on the rerender GET would double-execute auth, rate
-  // limiting, and request-header injection. See TIM-871.
-  const skipMiddleware = shouldBypassMiddleware(req);
   const outcome =
-    !skipMiddleware && match.middlewareChain.length > 0
+    match.middlewareChain.length > 0
       ? await runMiddlewarePhase(config, req, match, responseHeaders, requestHeaderOverlay, {
           canonicalPathname,
           interception,