Andrew Clark

This commit introduces an **experimental new capability** by adding a `useOffline()` hook, exported from `next/navigation`, to **Next.js's App Router**. This hook allows userland components to **semantically react to the application's offline status**, returning `true` when connectivity is lost. The offline state is managed by an `OfflineProvider` using `useState` and `useOptimistic` to ensure **responsive updates even during blocked transitions**, such as navigations awaiting network. This **new feature** provides developers with a direct way to build more resilient and optimistic UIs, and is currently **gated behind the `experimental.useOffline` flag**.

This commit introduces an **experimental `useOffline` flag** to enable robust **offline retry behavior** for network-dependent operations within the Next.js App Router. It adds a new **client-side offline detection and retry module** (`offline.ts`) that integrates into **navigations, server actions, and prefetching** mechanisms, allowing requests to automatically block and retry upon network restoration instead of failing. This **new capability** significantly enhances application resilience in unstable network conditions, preventing hard errors and improving the user experience by gracefully handling temporary disconnections. The feature is gated behind `experimental.useOffline` and includes comprehensive end-to-end tests to verify its functionality.

This commit introduces the final phase of the **segment bundling system**, enabling the server and client to combine small static segments into a single prefetch response, significantly **optimizing network requests** for static content. It unifies all prefetch behaviors under a size-based model, **refactoring** the **client-side segment cache** (`cache.ts`) and **prefetch scheduler** (`scheduler.ts`) to handle bundled responses and ensure independent metadata prefetching for runtime layouts. The **server-side segment data collection** (`collect-segment-data.tsx`) is updated to bundle static prefetches and skip generating unnecessary static output for `instant = false` or runtime prefetch segments, leading to **reduced build output size**. This **new capability** enhances prefetching performance and streamlines metadata handling across the application.

This commit introduces **scaffolding** to **optimize prefetching** within the **App Router's server-side rendering** by enhancing the **prefetch hint collection** logic. It teaches the system to identify and mark segments that should be omitted from static prefetching, such as those with runtime prefetching or `instant = false`, treating them as transparent pass-throughs for data flow. Additionally, the **head (metadata/viewport) inlining logic** is refined to ensure metadata is only inlined into page segments and skipped for runtime prefetch routes. This **new capability** is a **preparatory step** that lays the groundwork for future performance improvements by avoiding unnecessary server and client work, though it introduces no behavioral changes yet.

This commit **enhances the correctness and robustness of segment bundling inlining hints** within the **Next.js App Router's prefetching mechanism**. It addresses critical scenarios where prefetch hints might be stale, missing, or inapplicable, such as initial build-time static pages, ISR revalidation, and fully dynamic routes, by introducing client-side cache expiration for `InliningHintsStale` and `PrefetchDisabled` flags. Additionally, it **refactors the segment prefetch response format** to a unified `SegmentPrefetchResponse` structure, simplifying client parsing logic and preparing for future multi-segment bundles. This **bug fix and enhancement** prevents incorrect prefetching behavior and potential infinite re-fetch loops, significantly improving the reliability of **App Router navigation and data fetching**.

This commit **enhances the App Router's prerendering capabilities** by **implementing vary parameter tracking for runtime prefetches**. It integrates the `varyParamsAccumulator` into the `finalRuntimeServerPrerender` process, ensuring that dynamic parameters accessed during a runtime prefetch are correctly identified and resolved before the prerender aborts. This **feature extension** is crucial for accurate cache invalidation and consistent behavior of pages that rely on dynamic data during client-side navigation. The change is thoroughly validated with new **e2e tests** covering various scenarios, including `searchParams`, `metadata` access, and per-segment layout/page splits.

This commit **fixes a race condition** within the **segment cache** by ensuring that entries are always upserted at their correctly rekeyed vary path. Previously, a deferred upsert in the `scheduler.ts` could overwrite an entry that had already been rekeyed by the fetch functions, leading to less generic paths being stored. The **refactoring** involves **moving the upsert logic directly into the fetch functions** like `fetchSegmentOnCacheMiss` in `cache.ts`, eliminating the deferred upsert and simplifying the cache management model. This change improves the reliability and correctness of the **segment cache**, especially for responses with vary parameters, by preventing stale or incorrectly keyed entries.

This commit **refactors client-side prefetching logic** to buffer full prefetch responses before passing them to the Flight client. This ensures that metadata, encoded as thenables within the Flight stream, can be **synchronously unwrapped** without encountering asynchronous processing issues from HTTP chunking. The change primarily impacts the `next/src/client/components/segment-cache` module, introducing new stream handling functions like `createNonTaskyPrefetchResponseStream`. This **enhances the reliability of prefetch metadata handling**, guaranteeing that the Flight client always receives a complete, single chunk for processing and avoiding fallback behaviors. Dynamic prefetches are explicitly not affected by this change.

This commit **fixes a flaky e2e test** for **per-page dynamic stale time configuration** within the **segment cache staleness** suite. The flakiness was caused by `browser.back()` restoring `LinkAccordion` state from BFCache, leading to uncontrolled pre-prefetches outside `act` scopes that violated test assertions. To resolve this, the **test refactoring** now uses forward navigation to newly introduced "hub" pages, ensuring accordions start closed and prefetches are only triggered within controlled `act` scopes. This change significantly improves the reliability of **e2e tests** for Next.js's caching mechanisms. Additionally, **documentation updates** for the `router-act` testing utility provide guidance on preventing similar flakiness.

This commit introduces the `export const unstable_dynamicStaleTime` configuration, providing **per-page control over client-side router cache staleness** for dynamic navigation responses within the **Next.js App Router**. This **new capability** allows developers to specify how long data from dynamic pages should be retained in the client-side cache, overriding the global `experimental.staleTimes.dynamic` setting. It involves extensive updates across the **client-side router reducer**, **segment cache**, and **Back-Forward Cache (BFCache)** logic to extract, propagate, and apply these per-page stale times, including handling parallel routes where the minimum value applies. This feature offers a more granular approach to optimizing navigation performance and data freshness, serving as a migration path for existing `staleTimes.dynamic` users.

This commit introduces a significant **refactoring** of the **Next.js App Router's scroll restoration mechanism**, replacing the previous segment-path-matching system with a simpler model based on a shared mutable `ScrollRef` directly on `CacheNode` instances. This change streamlines how scroll state is managed during navigation, eliminating complex segment path accumulation and matching logic within `layout-router` and `ppr-navigations.ts`. As a direct result, it **fixes a regression** where calling `refresh()` from a server action would incorrectly scroll the page to the top, ensuring more predictable scroll behavior across various navigation and data refresh scenarios. The update affects core router reducers, `CacheNode` creation, and `link.tsx` behavior, improving the overall robustness and maintainability of the **App Router's client-side navigation**.

This commit introduces the **server-side infrastructure** for **prefetch inlining**, a **new capability** designed to optimize client-side data fetching in the **Next.js App Router**. It implements a build-time process to measure the gzip size of each segment's prefetch response and generate **size-based bundling hints**. These hints are persisted into a manifest and embedded into the route tree prefetch response, enabling future client-side consumption. This work primarily impacts the **server-side rendering** and **build pipeline**, adding new configuration options (`experimental.prefetchInlining`) and laying the groundwork for more efficient data transfer without changing current observable behavior.

This commit **enhances the instant navigation testing utility** by **enabling page hydration** during MPA loads, which previously resulted in non-interactive pages and skipped hydration. It achieves this by injecting a script to fetch the static RSC payload, allowing React to hydrate partially and provide an interactive experience while the navigation lock is held, with a soft refresh fetching dynamic data upon unlock. Additionally, the **cookie protocol for the instant navigation lock state is refactored** to use a JSON array, improving its integration and data representation within the **Next.js devtools**. This **new capability** ensures that tests can assert on a fully hydrated React tree during instant navigation, significantly **improving the reliability and testability** of this feature and enhancing the devtools experience.

This commit provides a **bug fix** for the **optimistic routing** mechanism in Next.js, specifically addressing an issue where the client-side **route matching algorithm** would incorrectly fall through to a dynamic catch-all sibling. Previously, if a URL part matched a static child but its subtree couldn't fully resolve the remaining path, the system would erroneously match a dynamic `[...catchall]` route instead of the intended static one, leading to **incorrect route resolution**. The fix modifies `matchKnownRoutePart` in `packages/next/src/client/components/segment-cache/optimistic-routes.ts` to ensure that if a static child exists but its subtree doesn't resolve, the system bails out to server resolution, making static matches authoritative and preventing **synthetic entries** for wrong routes. This improves the reliability of client-side navigation, particularly in applications with mixed static and dynamic catch-all routes.

This commit provides a **bug fix** addressing build failures in **Next.js App Router** applications when **prefetch inlining** was enabled for **dynamic routes**. Previously, the inlined segment response used `/_inlined` as its key, which caused build validation to fail with "Invariant: missing __PAGE__ segmentPath" because it expected `__PAGE__` in segment paths. The fix modifies the `collect-segment-data.tsx` and `cache.ts` modules to use the `PAGE_SEGMENT_KEY` (`__PAGE__`) constant for inlined segment identification, aligning it with the existing build validation logic. This ensures that applications can successfully build and deploy while utilizing both prefetch inlining and dynamic routes without encountering validation errors.

This commit **refactors** the **Flight Router State** rendering logic by **removing a redundant server-side check** for leaf segment re-fetching. It eliminates the `parallelRoutesKeys.length === 0` condition from the `renderComponentsOnThisLevel` function within `walk-tree-with-flight-router-state`. This change simplifies the **server-side rendering** process, as the client now correctly marks segments for re-fetching, making the previous server-side special-casing unnecessary. The update streamlines the rendering pipeline and ensures consistent refetching behavior without duplicate logic.

This commit **enables the publication** of the **`@next/playwright` experimental package** to npm, making it available in canary releases. This package provides **Playwright helpers for testing Next.js navigation behavior**, featuring an `instant()` API to assert routes designed for instant navigation using only cached or prefetched content. The change involves **removing the "private" field** from the package configuration, allowing developers to leverage this new tool for advanced navigation testing, which relies on **Cache Components**.

This commit **fixes cookie handling** within the **`instant` Playwright testing utility** by switching from `page.evaluate()` to Playwright's `browserContext.addCookies` API. This **resolves a bug** where cookies were not present on the very first navigation or fresh page loads, ensuring they are set reliably before any page content loads. The change enhances the `instant` helper's robustness for **end-to-end tests** that rely on initial cookie states, and introduces a new `baseURL` option for explicit control over cookie application. New **e2e tests** have been added to validate this improved functionality and error handling.

This commit introduces the **experimental.prefetchInlining** feature, a **new capability** designed to **optimize network performance** in the App Router by reducing the number of prefetch requests. When enabled via `next.config.js`, the **server-side rendering** logic (`collectSegmentData`) now bundles all segment data for a route into a single `/_inlined` response, which is then processed by the **client-side segment cache** (`cache.ts`, `scheduler.ts`). This change significantly **reduces network request volume** for prefetching, mitigating per-request overhead and potential costs, at the trade-off of potentially increasing total bytes transferred due to less deduplication of shared layout data. This provides developers with a configurable option to balance request count against data transfer efficiency, impacting how **segment data is fetched and processed** across the application.

This commit **removes a 500ms settling period** from the `act()` function within the `router-act` test utility, which was originally intended to accommodate client-side revalidation cooldowns. This period was unnecessarily applied to all `act()` calls, causing significant **test performance degradation** across numerous test files. Instead, **revalidation tests** in `test/e2e/app-dir/segment-cache/revalidation/segment-cache-revalidation.test.ts` are now updated to leverage Playwright's fake clock (`page.clock.fastForward`) for deterministic timing control. This **test infrastructure improvement** and **performance optimization** results in **faster and more reliable test execution** by eliminating an artificial delay and decoupling the test utility from specific client-side timer knowledge.