@timber-js/app 0.2.0-alpha.207 → 0.2.0-alpha.209

package/src/plugins/react-resolve.ts

@@ -0,0 +1,149 @@
+/**
+ * timber-react-resolve — Deduplicate React across timber and user project.
+ *
+ * Without this plugin, pnpm's strict isolation can install two physical
+ * copies of React when the user's pinned version differs from timber's
+ * peer dep. Timber's 47 bare `from 'react'` imports resolve to one copy
+ * while react-dom uses the other — causing "Invalid hook call" hydration
+ * crashes with no indication of the real cause.
+ *
+ * The fix: inject `resolve.dedupe` entries so Vite always resolves React
+ * packages from the project root. Unlike `resolve.alias`, `dedupe`
+ * preserves Vite's per-environment export conditions — the RSC
+ * environment still gets the `react-server` build, SSR gets the SSR
+ * build, and the browser gets the browser build. The deduplication
+ * happens at the package level, not the file level.
+ *
+ * A `configResolved` check detects version mismatches between timber's
+ * resolved React and the project's React, and logs an actionable error.
+ *
+ * Design doc: 18-build-system.md §"Module Resolution"
+ * Task: TIM-1520
+ */
+
+import { createRequire } from 'node:module';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { Plugin } from 'vite';
+
+/**
+ * React packages to deduplicate. Vite's `resolve.dedupe` extracts the
+ * base package name (via `deepImportRE`) before checking, so subpath
+ * specifiers like `react/jsx-runtime` are covered by the base `react`
+ * entry — listing them separately has no effect.
+ */
+export const REACT_DEDUPE_PACKAGES = ['react', 'react-dom'] as const;
+
+// ANSI escape codes — match config-validation.ts style
+const RED = '\x1b[31m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+
+/**
+ * Read the version from a package's package.json given a resolve root.
+ */
+function readPackageVersion(packageName: string, resolveRoot: string): string | null {
+  try {
+    const req = createRequire(`${resolveRoot}/package.json`);
+    const pkgJsonPath = req.resolve(`${packageName}/package.json`);
+    const pkg = req(pkgJsonPath) as { version?: string };
+    return pkg.version ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export interface ReactVersionMismatch {
+  specifier: string;
+  timberVersion: string;
+  projectVersion: string;
+}
+
+/**
+ * Check whether timber's React and the user project's React resolve to
+ * the same version. Returns mismatches if any.
+ */
+export function detectReactMismatch(projectRoot: string): ReactVersionMismatch[] {
+  const mismatches: ReactVersionMismatch[] = [];
+  const timberRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+
+  for (const pkg of ['react', 'react-dom'] as const) {
+    const timberVersion = readPackageVersion(pkg, timberRoot);
+    const projectVersion = readPackageVersion(pkg, projectRoot);
+
+    if (timberVersion && projectVersion && timberVersion !== projectVersion) {
+      mismatches.push({ specifier: pkg, timberVersion, projectVersion });
+    }
+  }
+
+  return mismatches;
+}
+
+/**
+ * Format React version mismatches as an actionable warning.
+ */
+export function formatReactMismatch(mismatches: ReactVersionMismatch[]): string {
+  if (mismatches.length === 0) return '';
+
+  const lines: string[] = [];
+  lines.push(
+    `${RED}${BOLD}[timber]${RESET} ${RED}React version mismatch detected — this causes silent hydration crashes${RESET}`
+  );
+  lines.push('');
+  for (const m of mismatches) {
+    lines.push(
+      `  ${RED}✗${RESET} ${m.specifier}: timber has ${BOLD}${m.timberVersion}${RESET}, project has ${BOLD}${m.projectVersion}${RESET}`
+    );
+  }
+  lines.push('');
+  lines.push(
+    `  ${DIM}This typically causes "Invalid hook call" errors because two copies of${RESET}`
+  );
+  lines.push(`  ${DIM}React are loaded. timber's resolve.dedupe should handle this, but${RESET}`);
+  lines.push(
+    `  ${DIM}if you see hook errors, ensure your React version satisfies timber's peer dep.${RESET}`
+  );
+  lines.push('');
+  lines.push(`  ${DIM}Fix: update React in your project to match —${RESET}`);
+  lines.push(
+    `  ${BOLD}pnpm add react@${mismatches[0].timberVersion} react-dom@${mismatches[0].timberVersion}${RESET}`
+  );
+
+  return lines.join('\n');
+}
+
+/**
+ * Create the timber-react-resolve Vite plugin.
+ */
+export function timberReactResolve(): Plugin {
+  return {
+    name: 'timber-react-resolve',
+    enforce: 'pre',
+
+    config(userConfig) {
+      // Merge with any existing dedupe entries the user may have set.
+      const existing = userConfig.resolve?.dedupe ?? [];
+      const merged = [...existing];
+
+      for (const pkg of REACT_DEDUPE_PACKAGES) {
+        if (!merged.includes(pkg)) {
+          merged.push(pkg);
+        }
+      }
+
+      return {
+        resolve: {
+          dedupe: merged,
+        },
+      };
+    },
+
+    configResolved(resolved) {
+      const mismatches = detectReactMismatch(resolved.root);
+      if (mismatches.length > 0) {
+        process.stderr.write(`${formatReactMismatch(mismatches)}\n\n`);
+      }
+    },
+  };
+}

package/src/plugins/{adapter-build.ts → rsc-assets-manifest.ts}

@@ -1,109 +1,21 @@
 /**
- * timber-adapter-build — Invoke the adapter's buildOutput after vite build.
+ * The RSC plugin's assets manifest (`__vite_rsc_assets_manifest.js`) — read
+ * into the build manifest, and stripped of JavaScript when client JS is off.
  *
- * After all environments are built and the RSC plugin has written its
- * asset manifests, calls `adapter.buildOutput()` to transform the output
- * into a deployable artifact (e.g., Cloudflare Workers entry + wrangler.jsonc).
+ * The RSC plugin writes the file to rsc/ and ssr/ as a standalone file, not
+ * a Rollup chunk, so no `generateBundle` can intercept it; both operations
+ * work on the written files. Both run once, from the post-build phase's
+ * manifest finalization step (plugins/post-build.ts), before anything
+ * imports the built bundle.
  *
- * Uses a `buildApp` hook with `order: 'post'` so that Vite calls the
- * RSC plugin's buildApp (which orchestrates all environment builds and
- * writes asset manifests) first, then runs this handler after everything
- * is complete.
- *
- * Design docs: design/11-platform.md, design/25-production-deployments.md
+ * Design doc: 18-build-system.md §"Post-Build Phase"
  */
 
-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.ts';
-import type { TimberPlatformAdapter, TimberConfig } from '../adapters/types.ts';
 import type { BuildManifest } from '../server/build-manifest.ts';
 import { swallow } from '../server/logger.ts';
-import { normalizeBasePath } from '../shared/base-path.ts';
-
-export function timberAdapterBuild(ctx: PluginContext): Plugin {
-  return {
-    name: 'timber-adapter-build',
-
-    // order: 'post' causes Vite to run configBuilder.buildApp() (which
-    // includes the RSC plugin's buildApp) before calling this handler.
-    // By the time we run, all environments are built and asset manifests
-    // are written — safe to copy the output.
-    buildApp: {
-      order: 'post' as const,
-      async handler() {
-        if (ctx.dev) return;
-
-        const adapter = ctx.config.adapter as TimberPlatformAdapter | undefined;
-        if (!adapter || typeof adapter.buildOutput !== 'function') return;
-
-        const buildDir = ctx.buildDir;
-
-        // Merge per-route CSS and client reference JS from the RSC plugin's
-        // assets manifest into the build manifest. This data enables
-        // <link rel="stylesheet"> and <link rel="modulepreload"> tags in
-        // <head> for server component routes (TIM-1014).
-        if (ctx.buildManifest) {
-          await mergeRscAssetsManifest(
-            buildDir,
-            ctx.root,
-            ctx.buildManifest,
-            ctx.routeClientRefKeys
-          );
-        }
-
-        // Serialize the build manifest as a JS module that sets the global.
-        // The adapter writes this as _timber-manifest-init.mjs and imports it
-        // before the RSC handler, so globalThis.__TIMBER_BUILD_MANIFEST__ is
-        // available when virtual:timber-build-manifest evaluates.
-        let manifestInit: string | undefined;
-        if (ctx.buildManifest) {
-          // Strip JS/modulepreload from manifest when client JS is disabled —
-          // those files aren't served, so hints for them are useless.
-          const manifest = ctx.clientJavascript.disabled
-            ? { ...ctx.buildManifest, js: {}, modulepreload: {} }
-            : ctx.buildManifest;
-          const json = JSON.stringify(manifest);
-          manifestInit = `globalThis.__TIMBER_BUILD_MANIFEST__ = ${json};\n`;
-
-          // Embed the deployment ID for version skew detection (TIM-446).
-          // The server reads this at startup via setDeploymentId().
-          if (ctx.deploymentId) {
-            manifestInit += `globalThis.__TIMBER_DEPLOYMENT_ID__ = ${JSON.stringify(ctx.deploymentId)};\n`;
-          }
-        }
-
-        // Strip JS from the RSC plugin's assets manifest when client JS
-        // is disabled. The RSC plugin writes __vite_rsc_assets_manifest.js
-        // with clientReferenceDeps containing JS URLs — used to inject
-        // <link rel="modulepreload"> tags. Must happen before the adapter
-        // copies files to the output directory.
-        if (ctx.clientJavascript.disabled) {
-          await stripJsFromRscAssetsManifests(buildDir);
-        }
-
-        const adapterConfig: TimberConfig = {
-          root: ctx.root,
-          // Normalized once here, not in each adapter: the platform files
-          // adapters write address deployed-URL space (TIM-1274).
-          base: normalizeBasePath(ctx.base),
-          output: ctx.config.output ?? 'server',
-          clientJavascriptDisabled: ctx.clientJavascript.disabled,
-          manifestInit,
-          staticPagesDir:
-            (ctx.config.output ?? 'server') === 'static'
-              ? join(buildDir, 'static-pages')
-              : undefined,
-          staticContentTypes: ctx.staticContentTypes,
-        };
-
-        await adapter.buildOutput(adapterConfig, buildDir);
-      },
-    },
-  };
-}
 
 /**
  * Parse the RSC assets manifest at `manifestPath`. Tries JSON.parse first
@@ -215,14 +127,6 @@ function clearBootstrapScriptContent(src: string): string {
   return src.slice(0, idx) + '"bootstrapScriptContent": ""' + src.slice(i);
 }
 
-/**
- * Strip JS references from the RSC plugin's assets manifest files.
- *
- * The RSC plugin writes `__vite_rsc_assets_manifest.js` to rsc/ and ssr/
- * as standalone files (not Rollup chunks), so generateBundle can't
- * intercept them. This rewrites the files on disk after all builds
- * complete but before the adapter copies them to the output directory.
- */
 /**
  * Read the RSC plugin's assets manifest and merge per-route CSS and
  * per-route JS modulepreloads into the build manifest.
@@ -233,12 +137,12 @@ function clearBootstrapScriptContent(src: string): string {
  *     module graph walk) to produce per-route modulepreload entries.
  */
 export async function mergeRscAssetsManifest(
-  buildDir: string,
+  rscDir: string,
   root: string,
   buildManifest: BuildManifest,
   routeClientRefKeys?: Map<string, Set<string>>
 ): Promise<void> {
-  const manifestPath = join(buildDir, 'rsc', '__vite_rsc_assets_manifest.js');
+  const manifestPath = join(rscDir, '__vite_rsc_assets_manifest.js');
   let content: string;
   try {
     content = await readFile(manifestPath, 'utf-8');
@@ -290,9 +194,16 @@ export async function mergeRscAssetsManifest(
   }
 }
 
-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)];
+/**
+ * Strip JS references from the RSC plugin's assets manifest files.
+ *
+ * The RSC plugin writes `__vite_rsc_assets_manifest.js` to rsc/ and ssr/
+ * as standalone files (not Rollup chunks), so generateBundle can't
+ * intercept them. This rewrites the files on disk after all builds
+ * complete but before the adapter copies them to the output directory.
+ */
+export async function stripJsFromRscAssetsManifests(serverDirs: string[]): Promise<void> {
+  const paths = serverDirs.map((dir) => join(dir, '__vite_rsc_assets_manifest.js'));
 
   for (const path of paths) {
     let content: string;

package/src/plugins/shims.ts

@@ -70,6 +70,7 @@ export const SUBPATH_SRC_MAP: Record<string, string> = {
   'adapters/cloudflare/cache': 'adapters/cloudflare-kv-cache.ts',
   'adapters/cloudflare/dev': 'adapters/cloudflare-dev.ts',
   'adapters/nitro': 'adapters/nitro.ts',
+  'adapters/types': 'adapters/types.ts',
 };
 
 /**

package/src/plugins/static-build.ts

@@ -1,31 +1,34 @@
 /**
  * timber-static-build — Vite sub-plugin for static output mode.
  *
- * When `output: 'static'` is set in timber.config.ts, this plugin:
- * 1. Validates that no dynamic APIs (getCookies(), getHeaders()) are used
- * 2. After the build, renders all routes to static HTML + RSC flight files
+ * When `output: 'static'` is set in timber.config.ts:
+ * 1. The plugin validates that no dynamic APIs (getCookies(), getHeaders())
+ *    are used
+ * 2. `runStaticGeneration`, the static generation step of the post-build
+ *    phase (plugins/post-build.ts), renders all routes to static HTML + RSC
+ *    flight files
  *
  * Design doc: design/11-platform.md §"static output mode"
  */
 
 import type { Plugin } from 'vite';
-import { existsSync } from 'node:fs';
 import { mkdir, readdir, readFile, writeFile, rename, rm, stat } from 'node:fs/promises';
 import { createHash, randomUUID } from 'node:crypto';
 import { dirname, extname, isAbsolute, join, resolve, relative } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { writeFileAtomic } from '../utils/write-file-atomic.ts';
 import type { PluginContext } from '../plugin-context.ts';
+import type { DirectoryArtifact } from '../adapters/types.ts';
 import type {
   StaticGenerationOptions,
   StaticGenerationSummary,
   StaticPageEntry,
   StaticRedirectEntry,
 } from '../server/static-generator.ts';
-import { mergeRscAssetsManifest } from './adapter-build.ts';
 import { isRelativeBase, normalizeBasePath, withBasePath } from '../shared/base-path.ts';
 import type { RscManifest, RscManifestEntry } from '../shared/rsc-manifest.ts';
 import { htmlEscapeJsonString } from '../server/flight-scripts.ts';
-import { rscPayloadPath } from '../shared/rsc-payload-path.ts';
+import { RSC_PAYLOAD_DIR, rscPayloadPath } from '../shared/rsc-payload-path.ts';
 import { REDIRECTS_FILE, RESERVED_OUTPUT_PATHS } from '../shared/static-platform-files.ts';
 import {
   detectFsIdentity,
@@ -138,13 +141,6 @@ export function generateRedirectsFile(redirects: StaticRedirectEntry[], base: st
 // File output helpers
 // ---------------------------------------------------------------------------
 
-/** Write a file atomically: temp sibling + rename. */
-async function writeFileAtomic(path: string, data: Uint8Array | string): Promise<void> {
-  const tmp = `${path}.tmp`;
-  await writeFile(tmp, data);
-  await rename(tmp, path);
-}
-
 /**
  * Determine the output file path for a static page entry.
  *
@@ -204,7 +200,7 @@ export function staticOutputPath(entry: StaticPageEntry): string {
  * API route, `about/index.html` from a page). The filesystem does refuse that
  * one — `EISDIR` on the rename, `ENOTDIR` on the mkdir, depending on which
  * lands second — but an errno names a path, and in the rename case the path
- * it names is `about.tmp`. Reported here instead, so the message says which
+ * it names is the write's temp file. Reported here instead, so the message says which
  * two routes.
  *
  * Collisions are **collected, not thrown**. `onEntry` runs inside the
@@ -391,7 +387,7 @@ export class StaticSiteWriter {
  * @internal Exported for testing.
  */
 export async function cleanConditionalArtifacts(staticDir: string): Promise<void> {
-  await rm(join(staticDir, '_rsc'), { recursive: true, force: true }).catch(() => {});
+  await rm(join(staticDir, RSC_PAYLOAD_DIR), { recursive: true, force: true }).catch(() => {});
   await rm(join(staticDir, REDIRECTS_FILE), { force: true }).catch(() => {});
 }
 
@@ -454,37 +450,33 @@ export async function withSchedulerPortsReleased<T>(fn: () => Promise<T>): Promi
   }
 }
 
+/** The pre-rendered site a static generation pass wrote. */
+export interface StaticSite {
+  pages: DirectoryArtifact;
+  /** Content-Type per URL path for extensionless API outputs (TIM-1241). */
+  contentTypes: Record<string, string>;
+  /** `[RSC_PAYLOAD_DIR]` when payloads were written and content-hashed, else none. */
+  immutableDirs: string[];
+}
+
 /**
- * Load the built RSC entry and run the static generation pass.
+ * Load the built RSC entry and run the static generation pass — the static
+ * generation step of the post-build phase (plugins/post-build.ts).
  *
- * Unlike prebuilt capture, this needs the FULL pipeline handler, so
+ * The build manifest it renders with is already final: the phase merged the
+ * RSC assets manifest into it and published it before this step. Unlike
+ * prebuilt capture, this needs the FULL pipeline handler, so
  * __TIMBER_CAPTURE_MODE__ must be false.
+ *
+ * Returns the site only once it is complete, so an adapter is never handed a
+ * directory a failed pass left half-written — a failure throws instead.
  */
-async function runStaticGeneration(ctx: PluginContext): Promise<StaticGenerationSummary> {
-  const entryPath = join(ctx.buildDir, 'rsc', 'index.js');
-  if (!existsSync(entryPath)) {
-    throw new Error(
-      `[timber] Static generation: built RSC entry not found at ${entryPath} — ` +
-        `the build output is missing`
-    );
-  }
-
-  const g = globalThis as Record<string, unknown>;
-
-  // Set up the build manifest (same as adapter-build and prebuilt-capture).
-  if (ctx.buildManifest) g.__TIMBER_BUILD_MANIFEST__ ??= ctx.buildManifest;
-  if (ctx.deploymentId) g.__TIMBER_DEPLOYMENT_ID__ ??= ctx.deploymentId;
+export async function runStaticGeneration(ctx: PluginContext, rscDir: string): Promise<StaticSite> {
+  const entryPath = join(rscDir, 'index.js');
+  warnUnusableBase(ctx);
 
   // Ensure capture mode is off — we need the full handler.
-  g.__TIMBER_CAPTURE_MODE__ = false;
-
-  // Merge per-route CSS and modulepreload entries from the RSC assets
-  // manifest into the build manifest BEFORE rendering, so rendered HTML
-  // includes all <link> tags. This same merge normally runs in
-  // adapter-build, but static generation runs first.
-  if (ctx.buildManifest) {
-    await mergeRscAssetsManifest(ctx.buildDir, ctx.root, ctx.buildManifest, ctx.routeClientRefKeys);
-  }
+  (globalThis as Record<string, unknown>).__TIMBER_CAPTURE_MODE__ = false;
 
   console.log('[timber] Static generation: building site…');
 
@@ -512,6 +504,7 @@ async function runStaticGeneration(ctx: PluginContext): Promise<StaticGeneration
       const entryUrl = `${pathToFileURL(entryPath).href}?t=${Date.now()}`;
       mod = (await import(/* @vite-ignore */ entryUrl)) as StaticGenerateModule;
     } catch (error) {
+      // A missing entry lands here too: the import is the existence check.
       throw new Error(
         `[timber] Static generation: failed to load the built RSC entry (${entryPath}). ` +
           `The full request handler must initialize for static rendering.`,
@@ -556,22 +549,17 @@ async function runStaticGeneration(ctx: PluginContext): Promise<StaticGeneration
   // ambiguous, not that a page failed, and the message names both routes.
   writer.assertNoCollisions();
 
-  // Store content-type mappings on the plugin context so adapters
-  // can include them in the _headers file. TIM-1241.
-  if (Object.keys(writer.contentTypes).length > 0) {
-    ctx.staticContentTypes = writer.contentTypes;
-  }
-
   // Hash RSC flight payloads for immutable caching (TIM-1254).
   // Renames _rsc/*.rsc → _rsc/*-<hash>.rsc and injects a manifest
   // into each HTML file so the client can resolve hashed URLs.
   // Skip when client JS is disabled — no SPA navigation, no RSC fetches,
   // and injecting a <script> tag would violate the no-JS contract.
+  const immutableDirs: string[] = [];
   if (!ctx.clientJavascript.disabled) {
     const rscManifest = await hashRscPayloads(staticDir);
     if (Object.keys(rscManifest).length > 0) {
+      immutableDirs.push(RSC_PAYLOAD_DIR);
       await injectRscManifestIntoHtml(staticDir, rscManifest);
-      ctx.rscManifest = rscManifest;
       console.log(
         `[timber] Static generation: hashed ${Object.keys(rscManifest).length} RSC flight payloads`
       );
@@ -600,7 +588,9 @@ async function runStaticGeneration(ctx: PluginContext): Promise<StaticGeneration
     }
   }
 
-  return summary;
+  // Content types travel with the site because they describe it: a static
+  // host cannot infer the type of an extensionless API output (TIM-1241).
+  return { pages: { path: staticDir }, contentTypes: writer.contentTypes, immutableDirs };
 }
 
 // ---------------------------------------------------------------------------
@@ -694,7 +684,7 @@ async function walkDir(dir: string): Promise<string[]> {
  * @internal Exported for testing.
  */
 export async function hashRscPayloads(staticDir: string): Promise<RscManifest> {
-  const rscDir = join(staticDir, '_rsc');
+  const rscDir = join(staticDir, RSC_PAYLOAD_DIR);
   const files = await walkDir(rscDir);
   const manifest: RscManifest = {};
 
@@ -777,11 +767,9 @@ export async function readUserRedirects(root: string): Promise<string | null> {
 /**
  * Create the timber-static-build Vite plugin.
  *
- * Only active when output: 'static' is configured.
- *
- * Hooks:
- * - transform: Validates source files for static mode violations
- * - buildApp (post): Renders all routes to static HTML after the build
+ * Only active when output: 'static' is configured. Validates source files
+ * for static mode violations; rendering the site is `runStaticGeneration`,
+ * which the post-build phase calls.
  */
 export function timberStaticBuild(ctx: PluginContext): Plugin {
   return {
@@ -825,25 +813,5 @@ export function timberStaticBuild(ctx: PluginContext): Plugin {
 
       return null;
     },
-
-    /**
-     * After all environments are built, render every route to static HTML.
-     *
-     * Runs with order: 'post' so the RSC plugin's buildApp completes first,
-     * producing the built entry we import. Must run BEFORE the adapter
-     * build copies output to its platform-specific directory.
-     */
-    buildApp: {
-      order: 'post' as const,
-      async handler() {
-        if (ctx.dev) return;
-
-        const isStatic = ctx.config.output === 'static';
-        if (!isStatic) return;
-
-        warnUnusableBase(ctx);
-        await runStaticGeneration(ctx);
-      },
-    },
   };
 }

package/src/routing/codegen-write.ts

@@ -15,10 +15,11 @@
  * Design docs: 09-typescript.md §"Typed Routes", 18-build-system.md
  */
 
-import { writeFile, mkdir } from 'node:fs/promises';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { generateRouteMap } from './codegen.ts';
 import { writeSegmentTypes } from './segment-codegen.ts';
+import { writeFileAtomic } from '../utils/write-file-atomic.ts';
 import type { RouteTree } from './types.ts';
 
 /**
@@ -114,6 +115,22 @@ export async function flushCodegenWrites(): Promise<void> {
  * dependency) and logs instead; `timber check` awaits it and fails the command.
  * Either way the write is registered with `flushCodegenWrites()`.
  */
+/**
+ * Write `timber-env.d.ts` only when its content differs.
+ *
+ * Its content is constant per timber version, so almost every call is a no-op
+ * — and a file that is not rewritten cannot be read half-written. It is not
+ * replaced atomically because it lives in the user's project root, often
+ * committed: a rename would turn a symlink into a regular file, reset its
+ * permissions, and a process killed mid-write would leave a temp file next to
+ * their source. The in-place write happens only on first run or a timber
+ * upgrade.
+ */
+async function writeEnvDts(envPath: string): Promise<void> {
+  const existing = await readFile(envPath, 'utf-8').catch(() => null);
+  if (existing !== TIMBER_ENV_DTS) await writeFile(envPath, TIMBER_ENV_DTS, 'utf-8');
+}
+
 export function writeRouteCodegen(tree: RouteTree, appDir: string, root: string): Promise<void> {
   const timberDir = join(root, '.timber');
   const content = generateRouteMap(tree, { appDir, outputDir: timberDir });
@@ -122,9 +139,14 @@ export function writeRouteCodegen(tree: RouteTree, appDir: string, root: string)
 
   const done = mkdir(timberDir, { recursive: true })
     .then(() =>
+      // The type checker can read these while they are being rewritten — an
+      // editor's TS server during `timber dev`, a `tsgo` run during `vite
+      // build`. A truncating write shows it an empty route map for the length
+      // of the write, and every typed route degrades to `any` (TIM-1562).
+      // The generated files under `.timber/` are replaced atomically.
       Promise.all([
-        writeFile(routesPath, content, 'utf-8'),
-        writeFile(envPath, TIMBER_ENV_DTS, 'utf-8'),
+        writeFileAtomic(routesPath, content),
+        writeEnvDts(envPath),
         writeSegmentTypes(tree, appDir, root),
       ])
     )

package/src/routing/segment-codegen.ts

@@ -8,8 +8,9 @@
  * Design doc: design/41-global-params.md §The $segment Module
  */
 
-import { writeFile, mkdir } from 'node:fs/promises';
+import { mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
+import { writeFileAtomic } from '../utils/write-file-atomic.ts';
 import type { RouteTree, SegmentNode } from './types.ts';
 
 /** Info carried per directory for type generation. */
@@ -90,7 +91,7 @@ export async function writeSegmentTypes(
     const content = generateSegmentDts(info);
 
     writes.push(
-      mkdir(segmentDir, { recursive: true }).then(() => writeFile(segmentFile, content, 'utf-8'))
+      mkdir(segmentDir, { recursive: true }).then(() => writeFileAtomic(segmentFile, content))
     );
   }
 

package/src/rsc-runtime/vendor-types.d.ts

@@ -16,4 +16,12 @@ declare module '@vitejs/plugin-rsc/vendor/react-server-dom/server.edge' {
       onPostpone?: (reason: string) => void;
     }
   ): ReadableStream<Uint8Array>;
+
+  // src decodes replies through plugin-rsc's wrapper; tests call the vendored
+  // server directly to exercise its array size limit (CVE-2025-55184).
+  export function decodeReply(
+    body: string | FormData,
+    manifest: unknown,
+    options?: { temporaryReferences?: unknown; arraySizeLimit?: number }
+  ): Promise<unknown[]>;
 }

package/src/server/access-gate.tsx

@@ -13,7 +13,8 @@
  * See design/04-authorization.md and design/02-rendering-pipeline.md §"AccessGate"
  */
 
-import { isDenySignal, isRedirectSignal, DenySignal, RedirectSignal } from './primitives.ts';
+import { DenySignal, RedirectSignal } from './primitives.ts';
+import { isDenySignal, isRedirectSignal } from './signal-identity.ts';
 import { withSpan, setSpanAttribute } from './tracing.ts';
 import { isDebug } from './debug.ts';
 import type { DenyPageEntry } from './deny-boundary.ts';

package/src/server/action-client.ts

@@ -225,7 +225,7 @@ async function runActionMiddleware<TCtx>(
 import { parseFormData } from './form-data.ts';
 import { formatSize } from '../utils/format.ts';
 import { isDebug, isDevMode } from './debug.ts';
-import { isDenySignal, isRedirectSignal } from './primitives.ts';
+import { isDenySignal, isRedirectSignal } from './signal-identity.ts';
 import {
   stripSensitiveFields,
   resolveSensitivePredicate,