@timber-js/app 0.2.0-alpha.197 → 0.2.0-alpha.199

package/src/client/router.ts

@@ -1,6 +1,6 @@
 // Segment Router — the operations a client-side navigation can be.
 //
-// `navigate`, `refresh`, `handlePopState`, `prefetch` and `applyRevalidation`
+// `navigate`, `refresh`, `handlePopState`, `prefetch` and `applyActionResult`
 // live here; each is wiring over modules that own one concern apiece:
 //
 //   router-types.ts      — RouterDeps / RouterInstance / the option shapes
@@ -24,6 +24,7 @@ import { createNavigationLifecycle } from './router-lifecycle.ts';
 import { createNavigationPipeline, prefetchKeyFor } from './router-pipeline.ts';
 import { recordSkew } from './router-skew.ts';
 import type { NavigationOptions, RouterDeps, RouterInstance } from './router-types.ts';
+import { createRenderOwner, type CommitOutcome } from './navigation-transition.ts';
 
 // ─── Router Factory ──────────────────────────────────────────────
 
@@ -46,19 +47,20 @@ export function createRouter(deps: RouterDeps): RouterInstance {
 
   // Ownership of the router: who is navigating, whose fetch may be cut, and
   // the pending store TopLoader subscribes to. See router-lifecycle.ts.
+  const lifecycle = createNavigationLifecycle(deps);
   const {
-    currentNavAbort,
-    createNavAbort,
+    currentOwner,
+    createNavOwner,
     runNavigation,
     markHandedOff,
     forgetOlderHandoffs,
     isPending,
     getPendingUrl,
     onPendingChange,
-  } = createNavigationLifecycle(deps);
+  } = lifecycle;
 
   // Fetch → commit → hand to React. See router-pipeline.ts.
-  const { performNavigationFetch, renderViaTransition, renderPayload, resolveForFallback } =
+  const { performNavigationFetch, renderViaTransition, resolveForFallback } =
     createNavigationPipeline({
       deps,
       prefetchCache,
@@ -76,15 +78,15 @@ export function createRouter(deps: RouterDeps): RouterInstance {
   // navigation still own the router?" question is asked once rather than
   // per branch (TIM-1275, TIM-1276).
   const { leaveSpaIfOwned, leaveSpaSuperseding } = createSpaExits({
-    currentNavAbort,
-    supersede: () => void createNavAbort(),
+    currentOwner,
+    supersede: () => void createNavOwner('navigation'),
   });
 
   // Every way an RSC fetch can fail that the router answers rather than
   // rethrows. Shared by navigate(), refresh(), and traversals so a path that
   // grows a new branch grows it for all of them (TIM-1277).
   const recoverFromNavigationError = createNavigationRecovery({
-    currentNavAbort,
+    currentOwner,
     leaveSpaIfOwned,
     // Hoisted — `navigate` is a function declaration below.
     navigate: (url) => navigate(url, { replace: true }),
@@ -137,10 +139,10 @@ export function createRouter(deps: RouterDeps): RouterInstance {
 
     await runNavigation(
       url,
-      async (navAbort) => {
+      async (owner) => {
         // When Navigation API is active, initiate the navigation via
         // navigation.navigate() BEFORE the fetch. Must happen after
-        // createNavAbort supersedes the previous navigation (done by
+        // createNavOwner supersedes the previous navigation (done by
         // runNavigation) so the old deferred is resolved first.
         if (!effectiveSkipHistory && deps.navigationNavigate) {
           deps.setRouterNavigating?.(true);
@@ -150,14 +152,18 @@ export function createRouter(deps: RouterDeps): RouterInstance {
         }
 
         try {
-          await renderViaTransition(fetchUrl, navAbort, () =>
-            performNavigationFetch(fetchUrl, {
-              replace,
-              commitUrl: url,
-              signal: navAbort.signal,
-              skipHistory: effectiveSkipHistory,
-              departingUrl,
-            })
+          await renderViaTransition(
+            fetchUrl,
+            owner,
+            () =>
+              performNavigationFetch(fetchUrl, {
+                replace,
+                commitUrl: url,
+                signal: owner.fetchAbort.signal,
+                skipHistory: effectiveSkipHistory,
+                departingUrl,
+              }),
+            options.onCommit
           );
 
           // Scroll-to-top on forward navigation, scroll to the #fragment target
@@ -173,7 +179,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
           // load of the destination, fragment included (TIM-1234). Reloading
           // instead would rebuild the page they were *leaving* and discard
           // the click (TIM-1275).
-          if (await recoverFromNavigationError(error, navAbort, url, departingUrl)) return;
+          if (await recoverFromNavigationError(error, owner, url, departingUrl)) return;
           throw error;
         }
       },
@@ -198,31 +204,37 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       /** Restored after paint when present — traversals only. */
       scrollY?: number;
       externalSignal?: AbortSignal;
+      /** Fires once when React commits, or when the navigation is abandoned. */
+      onCommit?: (outcome: CommitOutcome) => void;
     } = {}
   ): Promise<void> {
     await runNavigation(
       url,
-      async (navAbort) => {
+      async (owner) => {
         try {
-          await renderViaTransition(url, navAbort, async () => {
-            const result = await fetchRscPayload(
-              url,
-              deps,
-              opts.stateTree,
-              undefined,
-              navAbort.signal
-            );
-            const payload = await resolveForFallback(result.payload);
-            const params = await result.params;
-            const { navState, commit } = prepareNavigation(url, {
-              payload,
-              params,
-              segmentInfo: result.segmentInfo,
-              status: result.status,
-              skippedSegments: result.skippedSegments,
-            });
-            return { ...result, payload, params, navState, commit };
-          });
+          await renderViaTransition(
+            url,
+            owner,
+            async () => {
+              const result = await fetchRscPayload(
+                url,
+                deps,
+                opts.stateTree,
+                undefined,
+                owner.fetchAbort.signal
+              );
+              const payload = await resolveForFallback(result.payload);
+              const params = await result.params;
+              const { navState, commit } = prepareNavigation(url, {
+                payload,
+                params,
+                segmentInfo: result.segmentInfo,
+                skippedSegments: result.skippedSegments,
+              });
+              return { ...result, payload, params, navState, commit };
+            },
+            opts.onCommit
+          );
         } catch (error) {
           // Neither path is a navigate(), and neither has a caller that
           // handles a rejection — `refresh()` is `void`-called everywhere it
@@ -235,7 +247,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
           // browser has already traversed, and `refresh()` is by definition
           // where it already is. So `hardNavigate()` takes its same-document
           // branch and reloads rather than pushing an entry.
-          if (await recoverFromNavigationError(error, navAbort, url, url)) return;
+          if (await recoverFromNavigationError(error, owner, url, url)) return;
           throw error;
         }
 
@@ -245,7 +257,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     );
   }
 
-  async function refresh(): Promise<void> {
+  async function refresh(options?: { onCommit?: (outcome: CommitOutcome) => void }): Promise<void> {
     const currentUrl = deps.getCurrentUrl();
 
     // A refresh on a stale client is a full document load of the current URL.
@@ -256,7 +268,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       await leaveSpaSuperseding(currentUrl, currentUrl);
     }
 
-    await fetchCommitAndRender(currentUrl);
+    await fetchCommitAndRender(currentUrl, { onCommit: options?.onCommit });
   }
 
   async function handlePopState(
@@ -290,7 +302,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       // synchronous — the fn resolves immediately.
       await runNavigation(
         url,
-        async () => {
+        async (owner) => {
           // clearSegmentCacheOnEmpty: popstate to an entry without layout
           // metadata (e.g., initial SSR page) clears the cache so the next
           // forward navigation gets a full render.
@@ -302,13 +314,30 @@ export function createRouter(deps: RouterDeps): RouterInstance {
           // here. Publishing first would advertise the replayed route's slot
           // keys while the slot content cache still describes the departing
           // one (TIM-1423, codex on #1108).
-          const { navState, commit } = prepareNavigation(url, {
-            payload: entry.payload,
-            params: entry.params,
-            segmentInfo: entry.segmentInfo,
-            clearSegmentCacheOnEmpty: true,
+          //
+          // Routed through renderViaTransition so the replay gets the same
+          // lifecycle every other render has — handoff tracking, commit-on-
+          // commit, forgetOlderHandoffs — rather than a hand-rolled publish
+          // that misses one of them (TIM-1478). The perform resolves
+          // immediately: there is no fetch, and the cached payload is
+          // already decoded.
+          await renderViaTransition(url, owner, async () => {
+            const { navState, commit } = prepareNavigation(url, {
+              payload: entry.payload,
+              params: entry.params,
+              segmentInfo: entry.segmentInfo,
+              clearSegmentCacheOnEmpty: true,
+            });
+            return {
+              payload: entry.payload,
+              params: entry.params,
+              navState,
+              commit,
+              decodePromise: null,
+              segmentInfo: entry.segmentInfo ?? null,
+              skippedSegments: null,
+            };
           });
-          renderPayload(entry.payload, navState, entry.params, commit);
           restoreScrollAfterPaint(scrollY);
         },
         externalSignal
@@ -356,7 +385,6 @@ export function createRouter(deps: RouterDeps): RouterInstance {
 
     // Don't prefetch if already cached (ready or negative)
     if (prefetchCache.has(cacheKey)) return;
-    if (historyStack.has(fetchUrl)) return;
 
     // Fire-and-forget. Concurrent hovers coalesce in the singleflight;
     // a click during the round-trip joins the same flight via
@@ -399,32 +427,77 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     getPendingUrl,
     onPendingChange,
     prefetch,
-    applyRevalidation(payloadRoot: unknown): void {
-      // Render the piggybacked payload from a server action response. Updates
-      // the current history entry with the fresh payload — same as refresh()
-      // but without a server fetch.
-      //
-      // The revalidation renderer builds its tree through the same
-      // `withPublishedParams` every route payload goes through, so it is a
-      // payload root and carries its own params. It is already decoded by the
-      // time it reaches here (action-dispatch awaits the Flight response), so
-      // the split is synchronous.
+    epoch: () => lifecycle.epoch(),
+
+    async applyActionResult(epoch, tree) {
+      if (!lifecycle.isEpochCurrent(epoch)) return false;
+      if (tree === undefined) {
+        // Await through the commit so the next queued action captures a
+        // current epoch — refresh() alone resolves before React commits
+        // on the History API fallback (codex on #1125). The outcome
+        // distinguishes a committed refresh from one superseded by a
+        // navigation the user started while the refresh was in flight
+        // (TIM-1477).
+        let outcomeResolve!: (o: CommitOutcome) => void;
+        const outcomePromise = new Promise<CommitOutcome>((r) => (outcomeResolve = r));
+        const [, outcome] = await Promise.all([
+          refresh({ onCommit: outcomeResolve }).catch(() => {}),
+          outcomePromise,
+        ]);
+        return outcome === 'committed';
+      }
+      // Render the piggybacked payload from a server action response.
+      // Routed through renderViaTransition so the piggybacked tree gets
+      // the same commit lifecycle every other render has (TIM-1478).
+      // The perform resolves immediately — the payload is already in hand.
       const currentUrl = deps.getCurrentUrl();
-      const tree = readPayloadTree(payloadRoot);
-      const params = readPublishedParams(payloadRoot);
-
-      // Preserve existing segmentInfo so away-and-back navigation replays
-      // with a correct segment cache (TIM-1037).
+      const payloadTree = readPayloadTree(tree);
+      const params = readPublishedParams(tree);
       const existingEntry = historyStack.get(currentUrl);
-      // Like the popstate replay: there is no fetch to be superseded and the
-      // payload is already decoded, but the publish still rides React's
-      // commit of the tree, not this call (TIM-1423).
-      const { navState, commit } = prepareNavigation(currentUrl, {
-        payload: tree,
-        params,
-        segmentInfo: existingEntry?.segmentInfo,
-      });
-      renderPayload(tree, navState, params, commit);
+
+      let outcomeResolve!: (o: CommitOutcome) => void;
+      const outcomePromise = new Promise<CommitOutcome>((r) => (outcomeResolve = r));
+      // Place in the lifecycle's slot so a concurrent navigation supersedes
+      // this owner. The epoch check above ensures the slot is idle. Don't use
+      // createNavOwner — that bumps navigationSeq, which is reserved for
+      // navigations (the epoch test pins this: TIM-1474).
+      const owner = createRenderOwner('revalidation');
+      lifecycle.placeRevalidationOwner(owner);
+      const [, outcome] = await Promise.all([
+        renderViaTransition(
+          currentUrl,
+          owner,
+          async () => {
+            const { navState, commit } = prepareNavigation(currentUrl, {
+              payload: payloadTree,
+              params,
+              segmentInfo: existingEntry?.segmentInfo,
+            });
+            return {
+              payload: payloadTree,
+              params,
+              navState,
+              commit,
+              decodePromise: null,
+              segmentInfo: existingEntry?.segmentInfo ?? null,
+              skippedSegments: null,
+            };
+          },
+          outcomeResolve
+        ).catch(() => {}),
+        outcomePromise,
+      ]);
+      return outcome === 'committed';
+    },
+    runWhenIdle: (task: () => void) => lifecycle.runWhenIdle(task),
+    settleHandoffs: () => lifecycle.settleHandoffs(),
+    invalidatePath(path: string): void {
+      historyStack.delete(path);
+      prefetchCache.invalidateUrl(path);
+    },
+    evictStaleCaches(): void {
+      prefetchCache.clearReady();
+      historyStack.clearExcept(deps.getCurrentUrl());
     },
     initSegmentCache: (segments: SegmentInfo[]) => updateSegmentCache(segments),
     segmentCache,

package/src/client/rsc-fetch.ts

@@ -58,15 +58,6 @@ export interface FetchResult {
   segmentInfo: SegmentInfo[] | null;
   /** Segment paths that were skipped by the server (for client-side merging). */
   skippedSegments: string[] | null;
-  /**
-   * HTTP status of the navigation response.
-   *
-   * Read at the commit site to decide whether the tree this payload produced
-   * is one worth caching. A deny page replaced a subtree, so `segmentInfo`
-   * describes more than actually mounted — but it cannot simply be emptied,
-   * because the merge point is chosen out of it. See TIM-1356.
-   */
-  status: number;
 }
 
 // ─── URL Helpers ─────────────────────────────────────────────────
@@ -537,7 +528,6 @@ export async function fetchRscPayload(
     const fetchPromise = deps.fetch(rscUrl, { headers, redirect: 'manual', signal });
     let segmentInfo: SegmentInfo[] | null = null;
     let skippedSegments: string[] | null = null;
-    let status = 200;
     // Track when the full RSC body stream is consumed (not just shell).
     // Initialized to resolved for bodyless responses; overwritten when
     // the response has a body.
@@ -592,7 +582,6 @@ export async function fetchRscPayload(
       // as React elements — React 19 Float handles them. See TIM-1151.
       segmentInfo = extractSegmentInfo(response);
       skippedSegments = extractSkippedSegments(response);
-      status = response.status;
 
       // Wrap the body to track full stream consumption. createFromFetch's
       // thenable resolves when the root model (shell) arrives, but we need
@@ -641,7 +630,6 @@ export async function fetchRscPayload(
       decodePromise,
       segmentInfo,
       skippedSegments,
-      status,
     };
   }
   // Test/fallback path: return raw text
@@ -681,6 +669,5 @@ export async function fetchRscPayload(
     decodePromise: null,
     segmentInfo: extractSegmentInfo(response),
     skippedSegments: extractSkippedSegments(response),
-    status: response.status,
   };
 }

package/src/client/segment-cache.ts

@@ -27,14 +27,6 @@ export interface PrefetchResult {
   params?: PublishedParams | Promise<PublishedParams>;
   /** Segment paths skipped by the server (for client-side merging). */
   skippedSegments?: string[] | null;
-  /**
-   * HTTP status of the prefetched response. A deny payload is an ordinary
-   * Flight response carrying a 4xx, so it prefetches and caches like any
-   * other — and the tree it renders is one the segment cache must not learn
-   * from. Absent on entries that predate the field, and on the negative
-   * sentinel. See TIM-1356.
-   */
-  status?: number;
 }
 
 /**
@@ -363,6 +355,7 @@ export class PrefetchCache {
   private static readonly TTL_MS = 30_000;
   private entries = new Map<string, ReadyEntry>();
   private flights = createSingleflight({ timeoutMs: PREFETCH_SINGLEFLIGHT_TIMEOUT_MS });
+  private evictionGen = 0;
 
   set(key: PrefetchKey, result: PrefetchResult): void {
     this.entries.set(prefetchMapKey(key), {
@@ -414,14 +407,18 @@ export class PrefetchCache {
     doFetch: (signal: AbortSignal) => Promise<PrefetchResult>,
     isNonRoute: (error: unknown) => boolean
   ): Promise<FlightOutcome> {
+    // 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).
+    const genAtStart = this.evictionGen;
     return this.flights.do(prefetchMapKey(key), async (signal) => {
       try {
         const result = await doFetch(signal);
-        if (!signal.aborted) this.set(key, result);
+        if (!signal.aborted && this.evictionGen === genAtStart) this.set(key, result);
         return { kind: 'ready' as const, result };
       } catch (err) {
         if (isNonRoute(err)) {
-          if (!signal.aborted) this.setNegative(key);
+          if (!signal.aborted && this.evictionGen === genAtStart) this.setNegative(key);
           return { kind: 'non-route' as const };
         }
         throw err;
@@ -456,4 +453,40 @@ export class PrefetchCache {
   isNegative(key: PrefetchKey): boolean {
     return this.get(key) === NEGATIVE_ENTRY;
   }
+
+  /**
+   * 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.
+   */
+  invalidateUrl(url: string): void {
+    for (const [mapKey] of this.entries) {
+      if (mapKey.endsWith(':' + url)) {
+        this.entries.delete(mapKey);
+      }
+    }
+  }
+
+  /**
+   * Evict all ready entries and fence in-flight singleflights (TIM-1476).
+   * Called after a server action that revalidated data — the mutation may
+   * affect any route, not just the paths the server named. In-flight
+   * singleflights are not aborted (they may carry post-mutation data),
+   * but their results are discarded if they complete after eviction:
+   * `fetchOrCoalesce` captures the generation before the flight and
+   * skips the store when it has been bumped.
+   *
+   * Consumers that join an in-flight flight via `joinInflight` must
+   * check `getEvictionGen()` before and after the await: if the gen
+   * changed, the result predates the eviction and must be discarded
+   * (codex on #1131 round 2).
+   */
+  clearReady(): void {
+    this.entries.clear();
+    this.evictionGen++;
+  }
+
+  getEvictionGen(): number {
+    return this.evictionGen;
+  }
 }

package/src/client/state.ts

@@ -69,3 +69,29 @@ export let unloading = false;
 export function _setUnloading(value: boolean): void {
   unloading = value;
 }
+
+// ─── Status Page Commit Flag (from navigation-commit.ts) ────────────────────
+
+/**
+ * Whether a status page for the main route has rendered since the last
+ * navigation was prepared. Raised by `StatusPageMarker`, consumed by the
+ * navigation's commit. See navigation-commit.ts §"What a status page
+ * teaches the cache".
+ */
+export let statusPageRendered = false;
+
+export function _setStatusPageRendered(value: boolean): void {
+  statusPageRendered = value;
+}
+
+/**
+ * What a status page report does beyond raising the flag: registered by the
+ * router's committer so the report can clear the segment cache at once, for
+ * the commits no navigation consumes (a row arriving inside Suspense after
+ * its navigation published, a status document being hydrated).
+ */
+export let onStatusPageRendered: (() => void) | undefined;
+
+export function _setOnStatusPageRendered(handler: (() => void) | undefined): void {
+  onStatusPageRendered = handler;
+}

package/src/client/status-page-marker.tsx

@@ -0,0 +1,32 @@
+'use client';
+
+/**
+ * The one way a status page tells the router it is on screen.
+ *
+ * A status page replaces a subtree, and the segment cache must not learn a
+ * chain that never mounted (see `navigation-commit.ts` §"What a status page
+ * teaches the cache"). Status pages are produced in three places — an
+ * in-tree catch site rendering the page it owns, the server's fallback
+ * renderers, and a client boundary rendering its fallback for a Flight row —
+ * and every one of them wraps the page in this marker, so the report does
+ * not depend on which producer it was. In particular the in-tree case, the
+ * common `access.ts` deny, never involves a client boundary at all.
+ *
+ * A layout effect, on every commit that renders the marker rather than on
+ * mount only: React reuses the fiber when one status page is replaced by
+ * another at the same position, and the second one must report too. Layout
+ * effects run child-before-parent, so the report lands before the ancestor
+ * `NavigationRoot` publishes the same commit, and never for a render React
+ * discards. Idempotent, so StrictMode's double invocation and a status page
+ * re-rendering on its own state are harmless. See TIM-1495.
+ */
+
+import { useLayoutEffect, type ReactNode } from 'react';
+import { reportStatusPageRendered } from './navigation-commit.ts';
+
+export function StatusPageMarker({ children }: { children: ReactNode }): ReactNode {
+  useLayoutEffect(() => {
+    reportStatusPageRendered();
+  });
+  return children;
+}

package/src/dev-tools/holding-server.ts

@@ -14,7 +14,7 @@
  * The holding server is started in rootSync's config() hook (the
  * earliest Vite plugin lifecycle point where we know the port) and
  * closed directly in timber-dev-server's configureServer() hook
- * (the last plugin, fire-and-forget). configureServer runs during
+ * (the last plugin, awaited). configureServer runs during
  * createServer(), well before Vite's port probe and bind, so the
  * port is free by the time httpServerStart() runs. (TIM-1419)
  *
@@ -121,22 +121,9 @@ const HOLDING_PAGE_HTML = [
 /**
  * Create a holding HTTP server that serves a loading page during startup.
  *
- * Usage (inside Vite plugin):
- * ```ts
- * // In config() hook — earliest point where port is known.
- * // Use bindWithBump() to honor the default-3000 + auto-bump policy
- * // (see ../server/port-resolution.ts and TIM-842).
- * const holding = createHoldingServer();
- * await bindWithBump((p) => holding.listen(p), { startPort: 3000, autoBump: true });
- *
- * // In last plugin's configureServer() — close directly so Vite 8's
- * // isPortAvailable() probe and httpServer.listen() both see a free
- * // port. SO_REUSEADDR allows immediate rebind. (TIM-1419)
- * if (ctx.holdingServer) {
- *   ctx.holdingServer.close().catch(() => {});
- *   ctx.holdingServer = null;
- * }
- * ```
+ * The config hook attempts one bind on the requested port. If it fails,
+ * startup continues without the holding page; Vite owns port selection.
+ * The last configureServer hook awaits close() before Vite probes/binds.
  */
 export function createHoldingServer(): HoldingServer {
   const server = http.createServer((req, res) => {

package/src/index.ts

@@ -50,7 +50,7 @@ import {
   shouldEnableEncryption,
 } from './server/action-encryption.ts';
 import { createHoldingServer } from './dev-tools/holding-server.ts';
-import { resolveStartPort, startDevServerPort } from './server/port-resolution.ts';
+import { resolveStartPort } from './server/port-resolution.ts';
 import type { TimberUserConfig } from './config-types.ts';
 import type { PluginContext, TimberPluginApi } from './plugin-context.ts';
 import {
@@ -319,13 +319,10 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
       // override below fixes Vite's native path; plugin-react's compiler
       // plugin is handled by patchReactCompilerForProdJsx above.
       // ── Resolve dev/preview port (TIM-842) ───────────────────────
-      // Default port is 3000 with auto-bump on conflict. Explicit user
-      // overrides (`--port`, `PORT` env, `vite.config.ts` server.port)
-      // are honored as-is and fail loudly via `strictPort: true`.
+      // Default port is 3000. Vite handles conflicts and honors server.strictPort.
       //
       // For dev (`command === 'serve' && !isPreview`) we start the
-      // holding server and use its `listen()` as the probe, pairing
-      // the probe with the real bind to eliminate TOCTOU races.
+      // holding server on the requested port when available.
       //
       // For `vite preview` (`command === 'serve' && isPreview`) we
       // resolve the config/env port but delegate the actual bind +
@@ -354,31 +351,20 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
             ? undefined
             : 'localhost';
       if (command === 'serve' && !isPreview && !isMiddlewareMode) {
-        ctx.holdingServer = createHoldingServer();
-        const holdingRef = ctx.holdingServer;
-        const result = await startDevServerPort({
-          configPort:
-            typeof userConfig.server?.port === 'number' ? userConfig.server.port : undefined,
+        const start = resolveStartPort({
+          configPort: userConfig.server?.port,
           envPort: process.env.PORT,
-          listen: (p) => holdingRef.listen(p, resolvedHost),
         });
-        if (!result.bound) {
-          // Holding server failed to bind. Drop the reference so the
-          // dev-server plugin doesn't try to close a server that was
-          // never listening.
-          ctx.holdingServer = null;
-        }
-        if (result.bound) {
-          // Forward the probed port so Vite starts there. strictPort
-          // matches explicit — explicit ports fail loudly on a race
-          // between close and bind; implicit ones let Vite re-bump.
-          resolvedDevPort = result.port;
-          resolvedDevPortExplicit = result.explicit;
-        } else if (result.explicit) {
-          // Explicit port failed to bind (another process holds it).
-          // Forward it as the starting point but without strictPort
-          // so Vite auto-bumps to the next free port. TIM-1419.
-          resolvedDevPort = result.port;
+        // Vite owns port selection and remembers its bound port on restart.
+        // Never forward a probed/bumped port: replacement config runs while
+        // the old listener still owns the port. The holding page is optional.
+        resolvedDevPort = start.port;
+        resolvedDevPortExplicit = userConfig.server?.strictPort ?? false;
+        if (start.port !== 0) {
+          ctx.holdingServer = createHoldingServer();
+          await ctx.holdingServer.listen(start.port, resolvedHost).catch(() => {
+            ctx.holdingServer = null;
+          });
         }
       } else if (command === 'serve' && isPreview) {
         // Preview mode: resolve the starting port from config/env/
@@ -445,11 +431,9 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
       // Dev/preview mode: set outDir so dev-time references are
       // consistent, and surface the resolved port to Vite.
       //
-      // For dev with an explicit port, we set strictPort: true so Vite
-      // fails loudly on conflict. For auto-bumped (implicit) ports, we
-      // leave strictPort false so Vite can re-bump if the holding server's
-      // port becomes unavailable between close and bind (e.g., a second
-      // app instance starting on the same default port). TIM-1419.
+      // Dev auto-bumps unless the user sets server.strictPort.
+      // Always forward the requested port so Vite can recognize unchanged
+      // config and reuse its actual bound port across restarts (TIM-1456).
       //
       // For `vite preview`, we set `preview.strictPort` based on
       // whether the user explicitly set the port. Implicit (default)