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

package/dist/plugins/react-resolve.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 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 declare const REACT_DEDUPE_PACKAGES: readonly ['react', 'react-dom'];
+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 declare function detectReactMismatch(projectRoot: string): ReactVersionMismatch[];
+/**
+ * Format React version mismatches as an actionable warning.
+ */
+export declare function formatReactMismatch(mismatches: ReactVersionMismatch[]): string;
+/**
+ * Create the timber-react-resolve Vite plugin.
+ */
+export declare function timberReactResolve(): Plugin;
+//# sourceMappingURL=react-resolve.d.ts.map

package/dist/plugins/react-resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react-resolve.d.ts","sourceRoot":"","sources":["../../src/plugins/react-resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAEnC;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,YAAI,OAAO,EAAE,WAAW,CAAU,CAAC;AAsBrE,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,oBAAoB,EAAE,CAc/E;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,oBAAoB,EAAE,GAAG,MAAM,CA4B9E;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CA8B3C"}

package/dist/server/internal.js

@@ -13,7 +13,7 @@ import { a as getManifestEntry, b as wasInvalidatedSince, c as lookupPrebuiltPay
 import { n as createSingleflight } from "../_chunks/singleflight-2lUWfcAk.js";
 import { n as toBracketKey } from "../_chunks/resolve-schema-CBR6Lm4i.js";
 import { t as normalizeParamValue } from "../_chunks/param-value-C8TNYchQ.js";
-import { s as TIMBER_ERROR_HEADER, t as StatusPageMarker } from "../_chunks/status-page-marker-DwQBrLBz.js";
+import { s as TIMBER_ERROR_HEADER, t as StatusPageMarker } from "../_chunks/status-page-marker-CNbpUOPB.js";
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import React, { createElement, useContext } from "react";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.207",
+  "version": "0.2.0-alpha.208",
   "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",
@@ -165,8 +165,8 @@
     "@vitejs/plugin-react": "^6.1.0",
     "@vitejs/plugin-rsc": ">=0.5.35",
     "nuqs": "^2.0.0",
-    "react": "19.3.0",
-    "react-dom": "19.3.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
     "satteri": "^0.9.5",
     "vite": "8.3.0",
     "vite-plugin-satteri": "^0.2.15",

package/src/client/history.ts

@@ -91,6 +91,23 @@ export class HistoryStack {
     return this.entries.delete(url);
   }
 
+  /**
+   * Delete all entries whose pathname matches `pathname` (TIM-1465).
+   * Used by `invalidatePath` when the invalidation target has no search
+   * string — `/products` should evict `/products?page=1` too, because
+   * `revalidatePath('/products')` invalidates the route regardless of
+   * query.
+   */
+  deleteByPathname(pathname: string): void {
+    for (const url of this.entries.keys()) {
+      const qIndex = url.indexOf('?');
+      const urlPathname = qIndex === -1 ? url : url.slice(0, qIndex);
+      if (urlPathname === pathname) {
+        this.entries.delete(url);
+      }
+    }
+  }
+
   /**
    * Evict all cached payloads (TIM-1476). Called after a server action
    * that revalidated data — history entries are equally stale since they

package/src/client/navigation-commit.ts

@@ -154,6 +154,10 @@ export interface NavigationCommitter {
   prepareNavigation(url: string, opts: NavigationCommitInput): PreparedNavigation;
   currentStateTree(): StateTree | undefined;
   updateSegmentCache(segmentInfo: SegmentInfo[] | null | undefined): void;
+  /** Whether segment reuse is currently suppressed (TIM-1466). */
+  isSegmentReuseSuppressed(): boolean;
+  /** Lift segment reuse suppression after fresh data has been fetched (TIM-1466). */
+  restoreSegmentReuse(): void;
 }
 
 /**
@@ -205,6 +209,8 @@ export function createNavigationCommitter(deps: {
 
   return {
     updateSegmentCache,
+    isSegmentReuseSuppressed: () => segmentCache.isReuseSuppressed(),
+    restoreSegmentReuse: () => segmentCache.restoreReuse(),
 
     /**
      * The X-Timber-State-Tree to send with the next RSC request.

package/src/client/router-pipeline.ts

@@ -60,7 +60,7 @@ export interface NavigationFetchOptions {
 
 export interface NavigationPipelineDeps extends Pick<
   NavigationCommitter,
-  'prepareNavigation' | 'currentStateTree'
+  'prepareNavigation' | 'currentStateTree' | 'isSegmentReuseSuppressed' | 'restoreSegmentReuse'
 > {
   deps: RouterDeps;
   prefetchCache: PrefetchCache;
@@ -174,6 +174,8 @@ export function createNavigationPipeline({
   prefetchCache,
   currentStateTree,
   prepareNavigation,
+  isSegmentReuseSuppressed,
+  restoreSegmentReuse,
   markHandedOff,
   forgetOlderHandoffs,
 }: NavigationPipelineDeps): NavigationPipeline {
@@ -339,6 +341,11 @@ export function createNavigationPipeline({
     // `currentUrl` is read back off the key rather than computed beside it, so
     // the pathname sent as X-Timber-URL is the one the lookup used.
     const stateTree = currentStateTree();
+    // Capture whether reuse is suppressed at the time we build the state
+    // tree. If so, segments/slots are empty and the server will send a
+    // full render. We restore reuse after the response is processed so
+    // only navigations that fetched with suppression can lift it (TIM-1466).
+    let reuseSuppressedAtFetch = isSegmentReuseSuppressed();
     const cacheKey = prefetchKeyFor(url, options.departingUrl ?? deps.getCurrentUrl(), stateTree);
     const currentUrl = cacheKey.from;
 
@@ -381,11 +388,16 @@ export function createNavigationPipeline({
         // Capture the eviction generation before awaiting the flight.
         // If an action evicts caches while we wait, the result predates
         // the mutation and must be discarded (TIM-1476, codex on #1131).
+        // Also check the flight's own starting gen: if the flight started
+        // before a per-URL invalidation (TIM-1464), a joiner that arrived
+        // after the bump would see genBefore === genAfter but the flight
+        // still predates the invalidation.
         const genBefore = prefetchCache.getEvictionGen();
         try {
           const outcome = await raceAbort(inflight, options.signal);
-          if (prefetchCache.getEvictionGen() !== genBefore) {
-            // Eviction happened while we waited — discard stale result,
+          if (prefetchCache.getEvictionGen() !== genBefore || outcome.startGen !== genBefore) {
+            // Eviction happened while we waited, or the flight predates
+            // an invalidation we arrived after — discard stale result,
             // fall through to a fresh fetch below.
           } else if (outcome.kind === 'non-route') {
             throw new NonRscResponse(url);
@@ -422,7 +434,13 @@ export function createNavigationPipeline({
       // No in-flight hover prefetch, or the joined flight failed — fetch
       // directly with the navigation's signal so superseded navigations
       // abort immediately.
-      result = await fetchRscPayload(url, deps, stateTree, currentUrl, options.signal);
+      // Resample both the state tree and the suppression flag: if we fell
+      // through because an invalidation bumped the eviction gen,
+      // invalidateReuse() has suppressed segment/slot reuse since our
+      // original capture (TIM-1466, codex on #1167).
+      reuseSuppressedAtFetch = isSegmentReuseSuppressed();
+      const freshStateTree = currentStateTree();
+      result = await fetchRscPayload(url, deps, freshStateTree, currentUrl, options.signal);
     }
 
     // Update the browser history — skip when the Navigation API has already
@@ -467,6 +485,15 @@ export function createNavigationPipeline({
       skippedSegments: result.skippedSegments,
     });
 
+    // This navigation's fetch used the suppressed state tree (empty
+    // segments/slots), so the server sent a full render. The response
+    // data is post-invalidation — safe to restore reuse for subsequent
+    // navigations. Must happen here (at response time, before the commit
+    // thunk), not in set(), because a pre-invalidation navigation's
+    // commit thunk also calls set() and would lift suppression too early
+    // (codex on #1167).
+    if (reuseSuppressedAtFetch) restoreSegmentReuse();
+
     return {
       ...result,
       payload,

package/src/client/router.ts

@@ -39,7 +39,13 @@ export function createRouter(deps: RouterDeps): RouterInstance {
 
   // Every write that makes a page "current", and the read that reports the
   // current page back to the server. See navigation-commit.ts.
-  const { prepareNavigation, currentStateTree, updateSegmentCache } = createNavigationCommitter({
+  const {
+    prepareNavigation,
+    currentStateTree,
+    updateSegmentCache,
+    isSegmentReuseSuppressed,
+    restoreSegmentReuse,
+  } = createNavigationCommitter({
     segmentCache,
     historyStack,
     clientSegmentCache: () => deps.clientSegmentCache,
@@ -66,6 +72,8 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       prefetchCache,
       currentStateTree,
       prepareNavigation,
+      isSegmentReuseSuppressed,
+      restoreSegmentReuse,
       markHandedOff,
       forgetOlderHandoffs,
     });
@@ -492,8 +500,20 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     runWhenIdle: (task: () => void) => lifecycle.runWhenIdle(task),
     settleHandoffs: () => lifecycle.settleHandoffs(),
     invalidatePath(path: string): void {
-      historyStack.delete(path);
+      const hasSearch = path.includes('?');
+      if (hasSearch) {
+        historyStack.delete(path);
+      } else {
+        // TIM-1465: evict all query variants sharing this pathname
+        historyStack.deleteByPathname(path);
+      }
       prefetchCache.invalidateUrl(path);
+      // TIM-1466: suppress segment/slot reuse so the next navigation
+      // gets a full render instead of reusing stale shared layouts.
+      // Uses invalidateReuse() instead of clear() to preserve treePaths
+      // for interception scoping — a modal mounted on the current tree
+      // must still be navigable (codex on #1167).
+      segmentCache.invalidateReuse();
     },
     evictStaleCaches(): void {
       prefetchCache.clearReady();

package/src/client/segment-cache.ts

@@ -74,6 +74,16 @@ export interface SegmentNode {
  */
 export class SegmentCache {
   private root: SegmentNode | undefined;
+  /**
+   * Monotonic counter. Bumped by `invalidateReuse()` (TIM-1466).
+   * `serializeStateTree` suppresses `segments` and `slots` when
+   * `reuseInvalidatedAt > reuseRestoredAt`. Only `restoreReuse()`
+   * advances `reuseRestoredAt` — `set()` does not, because a
+   * pre-invalidation navigation's commit thunk would lift suppression
+   * before a post-invalidation request has been sent (codex on #1167).
+   */
+  private reuseInvalidatedAt = 0;
+  private reuseRestoredAt = 0;
 
   get(segment: string): SegmentNode | undefined {
     if (segment === '/' || segment === this.root?.segment) {
@@ -90,6 +100,33 @@ export class SegmentCache {
 
   clear(): void {
     this.root = undefined;
+    this.reuseRestoredAt = this.reuseInvalidatedAt;
+  }
+
+  /**
+   * Suppress segment and slot reuse without destroying the tree
+   * structure (TIM-1466). `serializeStateTree` sends empty
+   * `segments`/`slots` (forcing a full render) while `treePaths`
+   * still reflects the mounted tree for interception scoping.
+   * Call `restoreReuse()` once post-invalidation data has been
+   * fetched and committed.
+   */
+  invalidateReuse(): void {
+    this.reuseInvalidatedAt++;
+  }
+
+  /**
+   * Lift reuse suppression. Called after the segment cache has been
+   * rebuilt from a response that was fetched with suppression active
+   * (i.e. the server sent a full render). Safe to call idempotently.
+   */
+  restoreReuse(): void {
+    this.reuseRestoredAt = this.reuseInvalidatedAt;
+  }
+
+  /** Whether segment/slot reuse is currently suppressed (TIM-1466). */
+  isReuseSuppressed(): boolean {
+    return this.reuseInvalidatedAt > this.reuseRestoredAt;
   }
 
   /**
@@ -116,9 +153,12 @@ export class SegmentCache {
     const segments: string[] = [];
     const slots: string[] = [];
     const treePaths: string[] = [];
+    const suppressed = this.reuseInvalidatedAt > this.reuseRestoredAt;
     if (this.root) {
-      collectSyncSegments(this.root, segments, mergeableFilter);
-      collectSyncSlots(this.root, slots);
+      if (!suppressed) {
+        collectSyncSegments(this.root, segments, mergeableFilter);
+        collectSyncSlots(this.root, slots);
+      }
       collectTreePaths(this.root, treePaths);
     }
     const tree: StateTree = { segments };
@@ -324,6 +364,27 @@ function prefetchMapKey(key: PrefetchKey): string {
   return `${key.from.length}:${key.from}:${key.scope.length}:${key.scope}:${key.url}`;
 }
 
+/**
+ * Extract the destination URL from a length-prefixed map key.
+ * Key format: `${from.length}:${from}:${scope.length}:${scope}:${url}`
+ */
+function extractUrlFromMapKey(mapKey: string): string | null {
+  // Parse from-length prefix
+  const firstColon = mapKey.indexOf(':');
+  if (firstColon === -1) return null;
+  const fromLen = parseInt(mapKey.slice(0, firstColon), 10);
+  if (Number.isNaN(fromLen)) return null;
+  // Skip past `from.length:from:`
+  const scopeStart = firstColon + 1 + fromLen + 1;
+  // Parse scope-length prefix
+  const secondColon = mapKey.indexOf(':', scopeStart);
+  if (secondColon === -1) return null;
+  const scopeLen = parseInt(mapKey.slice(scopeStart, secondColon), 10);
+  if (Number.isNaN(scopeLen)) return null;
+  // Skip past `scope.length:scope:` — remainder is the URL
+  return mapKey.slice(secondColon + 1 + scopeLen + 1);
+}
+
 /**
  * The `scope` half of a `PrefetchKey`, derived from the state tree that will
  * actually be sent. Taking it from the header value rather than re-walking the
@@ -334,8 +395,12 @@ export function prefetchScopeOf(stateTree: StateTree | undefined): string {
 }
 
 /** Outcome of a prefetch flight — discriminated so NonRscResponse is a
- *  success (stores a negative entry) rather than a rejection. */
-export type FlightOutcome = { kind: 'ready'; result: PrefetchResult } | { kind: 'non-route' };
+ *  success (stores a negative entry) rather than a rejection.
+ *  `startGen` is the eviction generation at flight start — joiners that
+ *  started after a gen bump must reject pre-invalidation results (TIM-1464). */
+export type FlightOutcome =
+  | { kind: 'ready'; result: PrefetchResult; startGen: number }
+  | { kind: 'non-route'; startGen: number };
 
 /**
  * Short-lived cache for hover-triggered prefetches. Entries expire after
@@ -410,16 +475,19 @@ export class PrefetchCache {
     // Capture the eviction generation before the flight starts. If an
     // action evicts caches while this flight is in progress, the gen
     // will have bumped and the stale result is discarded (TIM-1476).
+    // The starting gen is also included in the outcome so joiners
+    // that started after a gen bump can detect pre-invalidation
+    // results (TIM-1464).
     const genAtStart = this.evictionGen;
     return this.flights.do(prefetchMapKey(key), async (signal) => {
       try {
         const result = await doFetch(signal);
         if (!signal.aborted && this.evictionGen === genAtStart) this.set(key, result);
-        return { kind: 'ready' as const, result };
+        return { kind: 'ready' as const, result, startGen: genAtStart };
       } catch (err) {
         if (isNonRoute(err)) {
           if (!signal.aborted && this.evictionGen === genAtStart) this.setNegative(key);
-          return { kind: 'non-route' as const };
+          return { kind: 'non-route' as const, startGen: genAtStart };
         }
         throw err;
       }
@@ -455,16 +523,47 @@ export class PrefetchCache {
   }
 
   /**
-   * Invalidate all entries whose destination URL matches (TIM-1454).
-   * Used by `revalidatePath` on a non-current route so the next navigation
-   * fetches fresh data instead of replaying a stale prefetch.
+   * Invalidate entries whose destination URL matches (TIM-1454).
+   *
+   * When `url` has no search string, evicts all entries sharing that
+   * pathname — `/products` evicts `/products?page=1` too, because
+   * `revalidatePath('/products')` invalidates the route regardless of
+   * query (TIM-1465).
+   *
+   * When `url` has a search string, only the exact URL is evicted.
+   *
+   * Also bumps the eviction generation so in-flight singleflight
+   * flights for the invalidated URL(s) discard their results on
+   * completion (TIM-1464).
    */
   invalidateUrl(url: string): void {
+    const hasSearch = url.includes('?');
+    const pathname = hasSearch ? null : url;
+
     for (const [mapKey] of this.entries) {
-      if (mapKey.endsWith(':' + url)) {
-        this.entries.delete(mapKey);
+      // The map key is `${from.length}:${from}:${scope.length}:${scope}:${url}`.
+      // The destination URL is the suffix after the last unescaped colon pair.
+      if (hasSearch) {
+        if (mapKey.endsWith(':' + url)) {
+          this.entries.delete(mapKey);
+        }
+      } else {
+        // Extract the URL suffix — everything after the scope block.
+        // Match any entry whose URL pathname matches.
+        const entryUrl = extractUrlFromMapKey(mapKey);
+        if (entryUrl !== null) {
+          const qIndex = entryUrl.indexOf('?');
+          const entryPathname = qIndex === -1 ? entryUrl : entryUrl.slice(0, qIndex);
+          if (entryPathname === pathname) {
+            this.entries.delete(mapKey);
+          }
+        }
       }
     }
+
+    // Fence in-flight flights so a prefetch that started before
+    // invalidation cannot store its stale result (TIM-1464).
+    this.evictionGen++;
   }
 
   /**

package/src/index.ts

@@ -28,6 +28,7 @@ import { timberBuildManifest } from './plugins/build-manifest.ts';
 import { timberDevLogs, originalConsole, wrapLoggerWithOriginalConsole } from './dev-tools/logs.ts';
 import { resolveForwardConsole } from './dev-tools/browser-logs.ts';
 import { timberReactProd } from './plugins/react-prod.ts';
+import { timberReactResolve } from './plugins/react-resolve.ts';
 import { timberChunks } from './plugins/chunks.ts';
 import { clientChunkGroup } from './plugins/client-chunks.ts';
 import { timberServerBundle } from './plugins/server-bundle.ts';
@@ -553,6 +554,7 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
   // imports manifest. See @vitejs/plugin-rsc's buildApp implementation.
   return [
     rootSync,
+    timberReactResolve(),
     timberReactProd(),
     // @vitejs/plugin-react provides React Fast Refresh (state-preserving HMR)
     // for client components via Babel transform. Placed before @vitejs/plugin-rsc

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`);
+      }
+    },
+  };
+}