Layout Persistence

[NathanDrake2406]

Implementation plan for layout persistence (#639). PR 1 (segmentMap migration) has landed as #737. PR 2a (client primitives) is implemented on branch feat/layout-persistence-pr-2a. See roadmap comment for the full PR breakdown and status.

Problem

The current RSC pipeline is monolithic: the server builds one complete React tree (root layout through all nested layouts down to the page) and passes it to renderToReadableStream() as a single ReactNode. On client-side navigation, createFromFetch() deserializes it into one ReactNode and replaces the entire React tree. This causes every layout to remount on navigation, replaying CSS animations and losing client component state.

Solution

Adopt Waku's flat keyed map architecture. Instead of one nested tree, the server returns a Record<string, ReactNode> where each layout, page, template, parallel slot, and route wiring are separate entries. On navigation, new entries are shallow-merged into existing ones. Old entries not in the new response persist. This preserves layouts across navigations.

Reference implementation: https://github.com/wakujs/waku — specifically packages/waku/src/minimal/client.tsx (Slot, Root, mergeElementsPromise) and packages/waku/src/router/ (route wiring, skip header).

Scope: Phase 1 only — flat map + merge. The skip header optimization (X-Vinext-Router-Skip) is deferred to a follow-up. The server always renders all entries; the client merges and preserves old layout entries.

Core Principle

Layout entries = static per-segment identity (persists across navigations).
Route wiring = dynamic per-navigation structure (always fresh).
mergeElementsPromise = the persistence mechanism (shallow spread preserves old entries).

Everything that changes on navigation lives in the wiring. Everything that persists lives in the entries.

---

Flat Map Payload Structure

The server produces a Record<string, ReactNode> with the following entry taxonomy:

Entry ID conventions: "tree path" is the layout's position in the filesystem route tree, including route groups (e.g., /, /(dashboard), /(dashboard)/blog). This prevents collisions when different route groups define different layouts at the same visible URL. "Route path" is the fully resolved leaf path (e.g., /blog/hello) — it's unique to one page.

Entry ID pattern	ID uses	Contains	Persists?
"layout:<treePath>"	Tree path	LayoutComponent with <Children /> as children prop	Yes
"template:<treePath>"	Tree path	TemplateComponent with <Children /> as children prop	No (re-rendered each nav)
"page:<routePath>"	Route path	PageComponent with params + searchParams	No
"slot:<slotName>:<treePath>"	Tree path	Parallel slot content (page + slot layout + slot boundaries)	No
"route:<routePath>"	Route path	Nested <Slot> chain with boundaries, LayoutSegmentProviders, template keys	No (always fresh)
"__route"	N/A	String value of the route wiring entry ID (e.g., "route:/blog/hello"). Runtime invariant: missing or non-string __route throws actionable error instead of silent blank screen.	No

Entry ID uses tree path, not visible segment path. "Tree path" includes route groups: layout:/(dashboard) vs layout:/(marketing) are distinct entries even though both resolve to URL /. This prevents collisions when different route groups define different layouts at the same visible URL segment. The routeSegments array already preserves route groups. Root layout switching detection also uses tree path comparison — /(dashboard)/layout.tsx → /(marketing)/layout.tsx is detected as a different root layout and triggers MPA navigation.

Example

Route /blog/hello with root layout, blog layout, blog template, blog error/loading, and @modal parallel slot on root:

{
  "layout:/":            <RootLayout params={...} modal={<ParallelSlot name="modal" />}><Children /></RootLayout>,
  "layout:/blog":        <BlogLayout params={...}><Children /></BlogLayout>,
  "template:/blog":      <BlogTemplate params={...}><Children /></BlogTemplate>,
  "page:/blog/hello":    <BlogPost params={...} searchParams={...} />,
  "slot:modal:/":        <ModalContent params={...} />,

  "route:/blog/hello":
    <LayoutSegmentProvider segmentMap={{ children: ["blog","hello"], modal: [] }}>
      <Slot id="layout:/" parallelSlots={{ modal: <LayoutSegmentProvider segmentMap={{ children: [] }}><Slot id="slot:modal:/" /></LayoutSegmentProvider> }}>
        <ErrorBoundary errorComponent={RootError}>
          <Suspense fallback={<RootLoading />}>
            <NotFoundBoundary notFound={<RootNotFound />}>
              <LayoutSegmentProvider segmentMap={{ children: ["hello"] }}>
                <Slot id="layout:/blog">
                  <ErrorBoundary errorComponent={BlogError}>
                    <Suspense fallback={<BlogLoading />}>
                      <NotFoundBoundary notFound={<BlogNotFound />}>
                        <Slot id="template:/blog" key="hello">
                          <LayoutSegmentProvider segmentMap={{ children: [] }}>
                            <Slot id="page:/blog/hello" />
                          </LayoutSegmentProvider>
                        </Slot>
                      </NotFoundBoundary>
                    </Suspense>
                  </ErrorBoundary>
                </Slot>
              </LayoutSegmentProvider>
            </NotFoundBoundary>
          </Suspense>
        </ErrorBoundary>
      </Slot>
    </LayoutSegmentProvider>
}

Why boundaries live in the route wiring

Error/not-found boundaries need to reset on navigation (stale error state from a previous route must not persist). The route wiring is always re-rendered per navigation, so boundaries in the wiring are naturally fresh for cross-route navigations (different route wiring entry ID → React unmounts/remounts boundary instances).

Same-route navigations (e.g., search param changes) keep the same wiring entry ID, so the boundary instance persists. Current gap: ErrorBoundary does NOT have pathname-based reset — only NotFoundBoundary does. ErrorBoundary has getDerivedStateFromError but no getDerivedStateFromProps reset path. This means same-route navigations after an error would keep the error state visible. Fix required in PR 2b or 2c: add pathname-based reset to ErrorBoundary (same pattern as NotFoundBoundary). PR 3 includes an explicit test case.

The boundary sits INSIDE <Slot id="layout:/blog">'s children, so it becomes the layout's <Children />. Errors from pages/nested layouts are caught by the boundary, but errors from the layout itself propagate UP to the parent segment's boundary. This matches Next.js semantics exactly.

Why LayoutSegmentProvider lives in the route wiring

Segment values (useSelectedLayoutSegment(s)) depend on the current route, not the layout. Since layouts persist but routes change, the provider must be in the per-navigation structure. The server computes exact segment values per layout level and embeds them in the route wiring.

parallelRoutesKey support in LayoutSegmentProvider

Status: The context type migration is complete (#737). LayoutSegmentContext is now SegmentMap and useSelectedLayoutSegments(parallelRoutesKey) indexes into the map. Per-slot segment population happens in PR 2c when route wiring wraps each slot with its own LayoutSegmentProvider.

useSelectedLayoutSegment(s) accepts an optional parallelRoutesKey argument (default "children") that selects which parallel route's segments to return. The flat map architecture enables this at two levels:

1. Layout-level provider — LayoutSegmentProvider accepts segmentMap: Record<string, string[]> instead of childSegments: string[]. The map includes "children" (the main route segments) plus an entry for each parallel slot at that layout level (e.g., { children: ["blog","hello"], modal: [] }). useSelectedLayoutSegments("modal") called from within the layout indexes into the map.

2. Per-slot provider — each parallel slot's <Slot> in the route wiring is wrapped with its own LayoutSegmentProvider containing { children: slotSegments }. This ensures components rendered inside a slot get the slot's own segments when calling useSelectedLayoutSegments() without arguments — matching Next.js behavior where each parallel route subtree has its own segment context.

The hook changes are minimal: useChildSegments(key = "children") indexes into the map instead of returning the flat array. The context type changes from React.Context<string[]> to React.Context<SegmentMap> where SegmentMap = { readonly children: string[] } & Readonly<Record<string, string[]>>.

Why templates are separate entries with keyed Slots

Templates must remount when navigation crosses their segment boundary (unlike layouts which persist). The template is its own flat map entry. The Slot for the template in the route wiring carries a key prop set to the immediate child segment value at the template's depth — NOT the full destination route path. This matches Next.js, where InnerLayoutRouter is keyed by createRouterCacheKey(childSegment).

Example: A template at /blog with routes /blog/hello and /blog/world:

• Navigating /blog/hello → /blog/world: key changes from "hello" to "world" → template remounts ✓
• A root template at / during /blog/hello → /blog/world: key stays "blog" → template does NOT remount ✓
• Root template at / during /blog/hello → /about: key changes from "blog" to "about" → template remounts ✓

Search param changes do NOT change the key (key is derived from path segments only). This matches Next.js behavior where templates persist across search param changes but remount on segment changes.

Parent templates only remount when their own direct child segment changes, not when deeper descendants change. This prevents unnecessary remounts of root-level templates on every page navigation.

Parallel slots

Parallel slots (@modal, @sidebar) are separate entries keyed as "slot:<slotName>:<treePath>" (tree path includes route groups). Layout entries reference them via <ParallelSlot name="..." /> client components passed as named props. The Slot component accepts an optional parallelSlots prop that gets provided via ParallelSlotsContext.

Route wiring passes parallel slot content through, with each slot wrapped in its own LayoutSegmentProvider so components inside the slot get correct segment context:

<Slot id="layout:/" parallelSlots={{
  modal: <LayoutSegmentProvider segmentMap={{ children: [] }}>
           <Slot id="slot:modal:/" />
         </LayoutSegmentProvider>
}}>

Unmatched parallel slot behavior

Next.js has three distinct behaviors when a parallel slot doesn't match the current route. The Slot component must handle all three:

1. Soft navigation (client-side nav to a route that doesn't define the slot): Preserve the last active content. The old slot entry stays in the elements map (merge doesn't remove it), and the Slot component renders the persisted entry. This is the default behavior — navigating from a route with @modal to one without keeps the modal visible.

2. Hard load / initial render (direct URL load, full page refresh): Fall back to default.js. If the route defines a default.js for the slot, render it. The server includes default.js content in the slot entry for hard loads. This is the "initial state" of an unmatched slot.

3. No default.js exists: Trigger the nearest not-found boundary. If a parallel slot has no match and no default.js fallback, the slot should render the nearest NotFoundBoundary. In development, a warning should be emitted (similar to Next.js's MissingSlotContext).

Design decision (from review): The server sends an explicit sentinel value for unmatched slots on hard loads. The sentinel is a unique Symbol (Symbol.for("vinext.unmatchedSlot")), not null, because default.tsx can legitimately return null (e.g., feed/@modal/default.tsx already does this in the test fixtures). Using null as the sentinel would make it impossible to distinguish "render default.js which returned null" from "no default.js exists."

The Slot component distinguishes three states:

• Key absent from map (!(id in elements)) → entry persists from prior soft nav (case 1). Render the persisted entry.
• Key present with UNMATCHED_SLOT symbol → server explicitly says this slot is unmatched and has no default.js (case 3). Trigger not-found boundary.
• Key present with any other value (including null) → render the entry (case 2). This covers default.js that returns null.

export const UNMATCHED_SLOT = Symbol.for("vinext.unmatchedSlot");

// In Slot component:
if (!(id in elements)) return null; // case 1: persisted from soft nav
const element = elements[id];
if (element === UNMATCHED_SLOT) { /* case 3: trigger not-found */ }
return element; // case 2: render normally (including null from default.tsx)

This keeps the distinction in the data, not the component, and avoids needing an isInitialLoad context flag.

RSC wire format consideration (PR 2c): Symbol values cannot survive React's flight serialization. Since slot.tsx is "use client", the RSC environment cannot import UNMATCHED_SLOT directly — it gets a client reference, not the actual Symbol. PR 2c must handle the translation: the server uses a serializable marker for unmatched slots in the elements map, and the client translates it to the UNMATCHED_SLOT Symbol after createFromFetch() resolves. The Slot component always checks against the Symbol, never against the wire format.

---

Client Components

Four new "use client" components in packages/vinext/src/shims/slot.tsx:

Slot

The core composition primitive. Reads an entry from the elements map by ID, provides children and parallel slots via context.

function Slot({
  id,
  children,
  parallelSlots,
}: {
  id: string;
  children?: ReactNode;
  parallelSlots?: Readonly<Record<string, ReactNode>>;
}) {
  const elements = use(useContext(ElementsContext));

  // Case 1: absent key — entry persists from prior soft nav
  if (!(id in elements)) return null;

  // Case 3: UNMATCHED_SLOT sentinel — no default.js, trigger not-found boundary
  const element = elements[id];
  if (element === UNMATCHED_SLOT) {
    notFound();
  }

  // Case 2: render the entry (including null from default.tsx that returns null)
  return (
    <ParallelSlotsContext.Provider value={parallelSlots ?? null}>
      <ChildrenContext.Provider value={children ?? null}>{element}</ChildrenContext.Provider>
    </ParallelSlotsContext.Provider>
  );
}

Children

How layouts render their child content. Maintains the Next.js {children} prop API — layouts receive <Children /> as their children prop, which reads the actual children from context.

const ChildrenContext = createContext<ReactNode>(null);

function Children() {
  return useContext(ChildrenContext);
}

ChildrenContext defaults to null. If <Children /> is rendered without a parent <Slot>, it renders nothing.

ParallelSlot

How layouts render named slots.

function ParallelSlot({ name }: { name: string }) {
  const slots = useContext(ParallelSlotsContext);
  return slots?.[name] ?? null;
}

mergeElementsPromise

The layout persistence mechanism. Shallow-merges new entries into existing ones. Uses WeakMap caching for referential stability (same input pair always returns same output Promise).

// WeakMap-based memoization: same (prev, next) pair always returns same Promise.
// Critical for React's referential stability — without this, every merge creates
// a new Promise, and use() in Slot would trigger unnecessary re-renders.
const cache1 = new WeakMap<Promise<Elements>, WeakMap<Promise<Elements>, Promise<Elements>>>();

function mergeElementsPromise(prev: Promise<Elements>, next: Promise<Elements>): Promise<Elements> {
  let cache2 = cache1.get(prev);
  if (!cache2) {
    cache2 = new WeakMap();
    cache1.set(prev, cache2);
  }
  let result = cache2.get(next);
  if (!result) {
    result = Promise.all([prev, next]).then(([a, b]) => ({ ...a, ...b }));
    cache2.set(next, result);
  }
  return result;
}

Concurrency safety

Known issue with the chained-promise model: Because each merge is Promise.all([prev, next]), a later navigation B depends on every earlier unresolved navigation A. A slow or abandoned navigation blocks all subsequent ones. Next.js avoids this with an interruptible reducer that can supersede pending navigations.

Mitigation for Phase 1: Navigation should await the new Promise<Elements> (from createFromFetch) before dispatching to the reducer. The reducer's mergeElementsPromise then receives a prev promise that is always already-resolved (it was the state at dispatch time) and a next promise that is also resolved (we awaited it). This eliminates the chaining problem because both inputs to Promise.all are settled.

1. Fetch RSC response
2. Await createFromFetch() → resolved Promise<Elements>
3. dispatch({ type: 'navigate', elements: resolvedPromise, routeId })
4. Reducer merges resolved prev + resolved next → no blocking

Abandoned navigations (user clicks a new link mid-flight) are naturally superseded — the fetch is abandoned (AbortController), and only the latest resolved payload reaches the reducer. The startTransition wrapper ensures React batches the update without showing intermediate states.

Loading state trade-off (from adversarial review): Awaiting the full response before dispatch means loading boundaries in the new route wiring cannot become visible during client navigation until the entire flat-map payload resolves. This is a regression from current behavior where React Flight can stream and show loading boundaries incrementally. The trade-off is correctness (no chained promises) vs streaming (loading states during nav). Revisit in Phase 4 (incremental streaming) whether the streaming promise can be passed directly to the reducer — this would require solving the chained-promise problem differently (e.g., promise superseding in the reducer instead of pre-await).

The elements map grows monotonically in Phase 1 (old entries are never evicted). Unreferenced entries are lightweight (just ReactNode references) — a long session visiting 100 routes accumulates ~100 ReactNode references, which is negligible. Eviction is deferred to Phase 2 (skip header), where stale layout entries become a real concern: if the client tells the server "I already have layout:/" but that entry contains stale data, the user sees outdated content. The Phase 2 eviction strategy will distinguish static layouts (no headers()/cookies()/uncached fetch() — safely skippable, no TTL needed) from dynamic layouts (always re-rendered, or skippable with configurable stale times à la Next.js's staleTimes). For reference: Waku has no eviction; Next.js uses a 3-tier segment cache with 50MB LRU and configurable staleTimes (static default 5min, dynamic default 0s).

Context structure

• ElementsContext: Context<Promise<Elements>> — the shared flat map, held by BrowserRoot
• ChildrenContext: Context<ReactNode> — set per Slot, read by Children. Default: null
• ParallelSlotsContext: Context<Record<string, ReactNode> | null> — set per Slot that has parallel slots. Default: null

In the pseudocode, ChildrenProvider and ParallelSlotsProvider are shorthand for ChildrenContext.Provider and ParallelSlotsContext.Provider.

---

Server Entry Changes (app-rsc-entry.ts)

The code generator produces a buildPageElements() function (replacing buildPageElement()) that returns Record<string, ReactNode>.

buildPageElements()

Iterates the layout chain, producing separate entries:

1. Layout entries: For each layout in the chain, create an entry keyed "layout:<segmentPath>" containing the layout component with <Children /> as its children prop and <ParallelSlot> references as named props.

2. Template entries: For each template, create an entry keyed "template:<segmentPath>" containing the template component with <Children />.

3. Page entry: Single entry keyed "page:<routePath>" with the page component, params, and searchParams.

4. Parallel slot entries: For each parallel slot, create an entry keyed "slot:<slotName>:<segmentPath>" containing the slot's page wrapped with its own layout/loading/error boundaries.

5. Route wiring entry: Entry keyed "route:<routePath>" containing the nested Slot chain with boundaries, LayoutSegmentProviders, and template keys. Built by a new buildRouteWiring() function.

renderToReadableStream call

const elements = buildPageElements(route, params, searchParams, opts);
const rscStream = renderToReadableStream(elements);

The RSC plugin's renderToReadableStream supports structured payloads — a Record<string, ReactNode> root is valid (confirmed by the plugin maintainer and verified locally via React Flight round-trip). However, all entries gate on a single root promise: every Slot reads from one shared Promise<Elements> via use(), so the entire app waits for the root record to resolve before any entry renders. Suspense boundaries inside individual entries work after the record resolves, but this does not enable true per-entry incremental reveal. The "incremental streaming per entry" future work item would require a fundamentally different store shape (e.g., per-entry promises or a streaming map).

ISR cache

ISR cache entries are keyed by build ID, so deploying the new version naturally invalidates old entries. No manual cache migration is needed. The raw bytes stored in the cache change format (structured payload instead of single node), but the cache layer is format-agnostic — it stores and retrieves ArrayBuffer snapshots.

The renderFreshPageForCache and background regeneration paths in the RSC entry must use buildPageElements() instead of buildPageElement().

Error/not-found/forbidden boundary rendering paths

The RSC entry has standalone rendering paths for error pages (renderHTTPAccessFallbackPage, renderErrorBoundaryPage) that build React trees outside the normal route flow. These paths also switch to the flat map format so the client doesn't need to handle two response formats.

For these paths, the elements map is minimal:

{
  "__route": "route:/__error",
  "page:/__error": <ErrorPage statusCode={...} />,
  "route:/__error":
    <Slot id="layout:/">
      <Slot id="page:/__error" />
    </Slot>
}

Layout entries from the normal route are included if available (the error page renders inside the nearest layout). If no layout is available, the error page renders standalone.

Entry ID limitations and known gaps

The flat map entry IDs use tree paths (including route groups) to avoid collisions. Known gaps:

• Intercepting routes: The same pathname can render different trees when intercepted (modal) vs directly loaded (full page). The current IDs don't encode interception context. Next.js tracks this via previousNextUrl in router state — refreshing an intercepted route stays intercepted; directly loaded routes stay non-intercepted. For Phase 1, intercepting routes work at the route-matching level (the server picks the intercepted vs direct route), but the visited response cache and entry IDs don't distinguish between the two contexts. This means refreshing an intercepted route may not preserve the interception. This is a known parity gap to address in a follow-up.

• Root layout switching (must be in PR 2c): Navigating between routes with different root layouts is an MPA navigation in Next.js (isNavigatingToNewRootLayout() triggers a full page load). Detected in the browser entry's navigation path — after deserializing new elements, compare root layout segment path with current. If different → window.location.assign() instead of merge. Merging elements from different root layouts produces a broken tree, so this is a correctness requirement, not a follow-up.

• Dynamic segment identity: Entry IDs use tree path (/blog) not segment value (/blog/[slug]). This is correct — layouts persist across different param values within the same segment. A /blog/[slug]/layout.tsx is the same layout for /blog/hello and /blog/world.

What stays the same

• Route matching (_trieMatch)
• Middleware pipeline
• makeThenableParams(), toPlainSearchParams()
• Intercepting route detection (server-side — picks correct route; client-side context tracking deferred)
• Metadata resolution (runs before buildPageElements(), injected into page or route wiring)

---

Browser Entry Changes (app-browser-entry.ts)

BrowserRoot

Changes from managing a single ReactNode to managing Promise<Elements> and routeId as atomic state via useReducer. Using two separate useState calls would allow intermediate renders where routeId and elements are out of sync (e.g., new route ID against old elements map). A reducer guarantees both update together.

type RouterState = {
  elements: Promise<Elements>;
  routeId: string;
};

type RouterAction =
  | { type: 'navigate'; elements: Promise<Elements>; routeId: string }
  | { type: 'replace'; elements: Promise<Elements>; routeId: string };

function routerReducer(state: RouterState, action: RouterAction): RouterState {
  switch (action.type) {
    case 'navigate':
      return {
        elements: mergeElementsPromise(state.elements, action.elements),
        routeId: action.routeId,
      };
    case 'replace':
      return {
        elements: action.elements,
        routeId: action.routeId,
      };
  }
}

function BrowserRoot({ initialElements, initialRouteId, initialNavigationSnapshot }) {
  const [state, dispatch] = useReducer(routerReducer, {
    elements: initialElements,
    routeId: initialRouteId,
  });

  return (
    <GlobalErrorBoundary errorComponent={globalError}>
      <ElementsContext.Provider value={state.elements}>
        <Slot id={state.routeId} />
      </ElementsContext.Provider>
    </GlobalErrorBoundary>
  );
}

Navigation dispatches { type: 'navigate', ... } (merge). HMR dispatches { type: 'replace', ... } (full replace).

Hydration

createFromReadableStream() returns Promise<Elements> (the structured payload). This becomes initialElements.

Navigation flow

1. Check visited response cache → if hit, restore as Promise<Elements>
2. Otherwise fetch RSC response (with AbortController for cancellation)
3. Buffer full response (snapshotRscResponse — unchanged)
4. Store in visited response cache (unchanged — still ArrayBuffer)
5. Deserialize via createFromFetch() → await to get resolved Promise<Elements>
6. Read `__route` key from resolved elements to get routeId
7. dispatch({ type: 'navigate', elements: resolvedPromise, routeId })
8. Reducer merges via mergeElementsPromise, updates routeId atomically
9. renderNavigationPayload() triggers startTransition

Step 7–8 are the key differences: atomic merge via reducer instead of separate state updates. Old layout entries persist. Awaiting at step 5 ensures both promise inputs to the merge are resolved, avoiding the chained-promise concurrency problem.

Torn URL state (from adversarial review): The reducer makes elements and routeId atomic, but usePathname() / useSearchParams() / useParams() read from a separate store (window.location + useSyncExternalStore). Currently navigateImpl() calls history.pushState() and notifies listeners before the RSC fetch completes, so persisted layouts would observe the destination URL while still rendering old content. Fix required in PR 2c: defer the history.pushState() and listener notification until after step 5 (RSC response received), or use a pending URL pattern where hooks don't update until startTransition commits the new elements. The history update and reducer dispatch must happen inside the same startTransition call to ensure React commits them atomically.

router.refresh()

Merges fresh elements via dispatch({ type: 'navigate', elements, routeId }). The server re-renders all entries for the current route (everything is fresh), and the reducer merges them atomically. Since all current-route entries are present in the response, the merge effectively updates every value while preserving entries from other routes accumulated during prior navigations. React reconciliation preserves layout DOM and state for unchanged layouts.

Both Next.js (FreshnessPolicy.RefreshAll with preserved tree structure) and Waku (router.reload() → same merge path as navigation) use merge semantics for refresh. Additionally, navigation caches should be invalidated since cached RSC responses may contain pre-refresh data.

Server actions

The existing ServerActionResult wire format changes. Currently: { root: ReactNode, returnValue? }. After: { root: Record<string, ReactNode>, returnValue? }. The root field contains the full flat elements map.

The client handles server action responses by:

1. Extracting root (the elements map) and returnValue
2. Reading root.__route to get the route wiring ID
3. Merging via dispatch({ type: 'navigate', elements, routeId }). The reducer merges post-mutation data into the existing map atomically. This preserves layout state (e.g., sidebar toggles, form inputs in layouts) while incorporating updated data. Both Next.js and Waku use merge semantics for server actions.
4. Updating routeId to the new wiring ID
5. Invalidating navigation caches (as today) — cached RSC responses may contain pre-mutation data

The isServerActionResult discriminator checks for { root: object, returnValue } shape — unchanged in logic, just the root type is now an elements record.

Back/forward navigation

Restore from visited response cache. The response is a full elements map. Merge with current map so layouts visited on other routes also persist.

HMR (rsc:update)

The HMR handler fetches a fresh RSC payload and must:

1. Deserialize the response as Promise<Elements> (not ReactNode)
2. Replace via dispatch({ type: 'replace', elements, routeId }). Unlike navigation, refresh, and server actions (which all merge), HMR replaces because code changes invalidate all module references and cached element state.
3. The reducer sets the new elements directly (no merge), updating routeId atomically.

HMR is the only operation that does a full replace. Both Waku (clears staticPathSetRef + cachedIdSetRef on HMR) and Next.js (full re-render on code change) agree that HMR should discard all cached state.

Visited response cache

No structural change. Stores ArrayBuffer snapshots of full RSC responses. The response now contains a flat map, but the cache is format-agnostic (just bytes).

Two-phase navigation commit

Unchanged in structure. NavigationCommitSignal still fires useLayoutEffect to drain pre-paint effects.

global-error.tsx

The global error boundary wraps the entire application, including the root layout. It lives in BrowserRoot (shown in the reducer-based code above), outside the ElementsContext.Provider and Slot chain. This catches errors from any layout (including root) and displays the global error fallback.

Both BrowserRoot and VinextFlightRoot (SSR) must include the GlobalErrorBoundary wrapper at the same tree position to avoid hydration mismatches. The globalError component reference is passed to both during hydration (generated by the RSC entry).

---

SSR Entry Changes (app-ssr-entry.ts)

Minimal changes. The VinextFlightRoot component wraps the deserialized elements map in ElementsContext.Provider and renders <Slot id={routeId} />. Critically, the SSR tree must mirror the BrowserRoot structure — including the GlobalErrorBoundary wrapper — to avoid hydration mismatches:

function VinextFlightRoot() {
  const elements = use(createFromReadableStream(rscStream));
  const routeId = elements.__route;
  return (
    <GlobalErrorBoundary errorComponent={globalError}>
      <ElementsContext.Provider value={Promise.resolve(elements)}>
        <Slot id={routeId} />
      </ElementsContext.Provider>
    </GlobalErrorBoundary>
  );
}

The routeId is read from elements.__route (the well-known key in the elements record). This travels with the RSC payload without needing header parsing. During SSR, the elements are available synchronously after use(createFromReadableStream(...)), so __route is immediately accessible.

Navigation context injection stays the same. ServerInsertedHTMLContext.Provider wrapping and font data injection must be preserved at the same tree positions in VinextFlightRoot to avoid breaking CSS-in-JS support (styled-components, emotion) and font optimization.

---

Integration Points (No Changes Needed)

• Navigation shims (navigation.ts): ✅ Done in feat: implement parallelRoutesKey support in useSelectedLayoutSegment(s) #737. useSelectedLayoutSegment(s) reads from LayoutSegmentContext which is now SegmentMap. useChildSegments(key) indexes into the map. Per-slot providers (added in PR 2c's route wiring) ensure components inside a slot see the slot's own segments.
• Link prefetching (link.tsx): Stores ArrayBuffer snapshots. Format-agnostic.
• Form component (form.tsx): Delegates to navigateClientSide().

---

Testing Strategy

New unit tests

• Slot renders entry from elements map, provides children via context
• Children reads from context, returns children
• ParallelSlot reads named slot from context
• mergeElementsPromise correctly shallow-merges, caches by reference
• buildRouteWiring() produces correct Slot chain with boundaries, segment providers, template keys

Modified tests

• tests/app-router.test.ts — navigation between routes sharing a layout preserves layout (key behavioral test: DOM persistence, client component state, CSS animation continuity)
• tests/entry-templates.test.ts — generated entry assertions updated for flat map structure
• tests/features.test.ts — error boundaries, loading, not-found still work
• Template remounting on navigation (key-driven)
• Parallel slots render correctly
• useSelectedLayoutSegment(s) returns correct values after navigation
• useSelectedLayoutSegment(s)(parallelRoutesKey) returns correct per-slot segments
• Components inside a parallel slot get slot-scoped segments via per-slot provider
• router.refresh() merges fresh entries, preserves layout state
• Server actions merge post-mutation entries, preserves layout state
• Back/forward navigation merges correctly

E2E tests (Playwright)

• Navigate between sibling routes, assert shared layout DOM node identity persists
• Client component state (counter, input value) survives navigation within same layout
• Template content remounts on navigation (state resets)
• Error boundary catches page error, then navigation clears it

---

Merge/Replace Semantics Summary

Operation	Semantics	Rationale
Navigation	MERGE	Preserve layouts, replace pages. Old layout entries persist via shallow spread.
Server action	MERGE	Preserve layout state after mutations. Post-mutation data merged in. Matches Next.js and Waku.
router.refresh()	MERGE	Re-fetch all data, preserve tree structure. All entries are fresh in response, so merge effectively updates everything.
Back/forward	MERGE (from cache)	Restore cached response, preserve accumulated layouts from other routes.
HMR	REPLACE	Code changed — all module references and cached state are stale. Only operation that does full replace.

Future Work (Not in Phase 1 Scope)

• Interception context tracking (Phase 2): Entry IDs and visited response cache need to encode whether a route was loaded via interception or directly. Required for previousNextUrl parity — refreshing an intercepted route should stay intercepted. See "Entry ID limitations" section. This is correctness, not perf — prioritized before skip headers.
• Skip header optimization (Phase 3, X-Vinext-Router-Skip): Client sends cached entry IDs to server. Server skips rendering static layouts. Pure optimization — persistence works without it.
• Static vs dynamic layout detection (Phase 3): Required for skip header. Layouts using headers(), cookies(), or uncached fetch() are dynamic; others are static.
• Entry eviction + LRU (Phase 3): When skip headers are added, stale layout entries become a real concern. Eviction strategy will distinguish static layouts (safely skippable, no TTL) from dynamic layouts (always re-rendered or skippable with configurable stale times). Bounded cache size as safety valve.
• Incremental streaming per entry (Phase 4): Currently all entries gate on a single root promise. True per-entry incremental reveal would require a fundamentally different store shape (per-entry promises or a streaming map), not just a change to renderToReadableStream. Lowest priority — Suspense inside entries already works.

[james-elicx]

My understanding is that Next.js maintains a tree that represents the hierarchy that they can diff / merge against. From what I understand in this plan, it sounds like we have some of that ability to do targeted updates with merges in the flat map, but other aspects will lose out, and we won't be leveraging it initially?

So if I navigated between two blog pages with the 'phase 1' proposed changes, it would still replace the entire tree. But after the 'phase 2' header is added, it only re-renders the targeted page content and not the layouts above it?

Additionally, it sounds like server actions and router.refresh would suffer the same problem - re-rendering the entire tree and replacing the client rather than more fine-grained for the parts of the tree that are actually affected? For server actions, I believe we should be able to do targetted updated - I think Next.js diffs the tree there. For router.refresh, we should be able to reconcile and preserve unaffected state instead of it being replaced as well I believe.

Slight nit but the map should have some sort of TTL associated with keys to prevent excessive growth or stale data.

[NathanDrake2406]

Phase 1 will persist layouts by merging via a useReducer that dispatches { type: 'navigate', elements, routeId } atomically. Phase 2 is more of an optimisation. I'll add the TTL in phase 2.
And yeah rest of the issues you raised are valid and I've updated the plan to reflect it

[NathanDrake2406]

Layout Persistence Roadmap

Updated 2026-04-12.

Current status: Phase 1 is complete. The latest merged roadmap PR is #753 (encode interception context). #755 (previousNextUrl) is the remaining open PR in the interception-context phase.

Reading the graph:

• Solid arrows = hard implementation dependencies
• Dotted arrows = recommended ordering / shared design pressure only
• Phases 4–6 are not strict blockers for each other once the flat-map foundation is in place

graph TD
    subgraph "Phase 1 · Flat Map + Merge"
        P1A["✅ PR 1 · segmentMap Migration<br/><i>merged #737</i>"]
        P1B["✅ PR 2a · Client Primitives<br/><i>landed via base commits in #750</i>"]
        P1C["✅ PR 2b · Extract Route Wiring<br/><i>merged #748</i>"]
        P1D["✅ PR 2c · The Switch<br/><i>merged #750</i>"]
        P1E["✅ PR 3 · Verification<br/><i>merged #752</i>"]
        P1A --> P1B --> P1C --> P1D --> P1E
    end

    subgraph "Phase 2 · Interception Context"
        P2A["✅ PR 4 · Entry ID encoding<br/><i>merged #753</i>"]
        P2B["PR 5 · previousNextUrl tracking<br/><i>open #755</i>"]
        P2A --> P2B
    end

    subgraph "Phase 3 · Skip Header Cluster"
        P3A["PR 6 · Static/dynamic detection<br/><i>tag layouts using headers(),<br/>cookies(), uncached fetch()<br/>as dynamic at build time</i>"]
        P3B["PR 7 · X-Vinext-Router-Skip<br/><i>client sends cached entry IDs,<br/>server skips static layouts</i>"]
        P3C["PR 8 · Entry eviction + LRU<br/><i>TTL for dynamic layouts,<br/>no eviction for static,<br/>bounded cache size</i>"]
        P3A --> P3B
        P3B -.-> P3C
    end

    subgraph "Phase 4 · Incremental Streaming"
        P4A["PR 9 · Streaming store<br/><i>per-entry promises or<br/>streaming map replacing<br/>single root promise</i>"]
        P4B["PR 10 · Progressive reveal<br/><i>entries render as they<br/>resolve, not all-at-once</i>"]
        P4A --> P4B
    end

    subgraph "Phase 5 · Activity Route Preservation"
        P5A["PR 11 · Hidden route model<br/><i>keep recent routes mounted<br/>behind React Activity instead<br/>of only preserving layout entries</i>"]
        P5B["PR 12 · Route eviction heuristics<br/><i>bound recent-route preservation<br/>to a small N, evict oldest,<br/>preserve back/fwd semantics</i>"]
        P5C["PR 13 · Hidden-route polish<br/><i>auth/reset semantics,<br/>scroll/focus restoration,<br/>style leakage, testing quirks,<br/>effect cleanup/recreate</i>"]
        P5A --> P5B --> P5C
    end

    subgraph "Phase 6 · Router Cache Policy"
        P6A["PR 14 · Invalidation semantics<br/><i>router.refresh, server actions,<br/>revalidatePath, revalidateTag,<br/>draft/auth/cookie boundaries</i>"]
        P6B["PR 15 · staleTimes / page reuse policy<br/><i>align page-segment reuse with<br/>current Next.js docs</i>"]
        P6C["PR 16 · Prefetch cache semantics<br/><i>define what prefetch seeds,<br/>when it goes stale, and how it<br/>composes with interception + hidden routes</i>"]
        P6A --> P6B
        P6A --> P6C
    end

    P1E --> P2A
    P2B -.->|prefer before skip-header rollout| P3A
    P1E -.->|can start after flat-map foundation| P4A
    P1E -.->|can start after flat-map foundation| P5A
    P2B -.->|policy work can start here| P6A
    P6A -.->|should inform invalidation rules| P3A
    P6A -.->|should inform hidden-route semantics| P5A

    classDef phaseDone fill:#0d3320,stroke:#2ecc71,color:#eee
    classDef phase2 fill:#1a1a2e,stroke:#0f3460,color:#eee
    classDef phase3 fill:#1a1a2e,stroke:#533483,color:#eee
    classDef phase4 fill:#1a1a2e,stroke:#16213e,color:#eee
    classDef phase5 fill:#1a1a2e,stroke:#2d6a4f,color:#eee
    classDef phase6 fill:#1a1a2e,stroke:#7b2cbf,color:#eee

    class P1A,P1B,P1C,P1D,P1E,P2A phaseDone
    class P2B phase2
    class P3A,P3B,P3C phase3
    class P4A,P4B phase4
    class P5A,P5B,P5C phase5
    class P6A,P6B,P6C phase6

Loading

Phase 1 — Flat Map + Merge complete

Layout persistence works. Layouts survive navigation. Client state preserved.

PR	Status	Risk	What shipped
PR 1 · segmentMap Migration	✅ Merged (#737)	Low	LayoutSegmentContext migrated from string[] to SegmentMap. parallelRoutesKey support in useSelectedLayoutSegment(s). Standalone improvement, no behavioral change.
PR 2a · Client Primitives	✅ Landed (base commits merged via #750)	Low	Slot, Children, ParallelSlot, mergeElementsPromise, UNMATCHED_SLOT, and the core contexts.
PR 2b · Extract Route Wiring	✅ Merged (#748)	Low	Boundary/layout/segment wiring moved out of the generated entry template into typed runtime modules.
PR 2c · The Switch	✅ Merged (#750)	High	Server flat-map payload, browser reducer + merge semantics, SSR adaptation, root-layout hard navigation fallback, unmatched-slot wire marker normalization, __route runtime invariant.
PR 3 · Verification	✅ Merged (#752)	Low	E2E proof that layout DOM persists, client state survives, templates remount on segment boundary changes, errors reset, and back/forward merges correctly.

Phase 2 — Interception Context in progress

Intercepting routes (modal pattern) behave correctly on refresh, traversal, and direct load.

PR	Status	Risk	What ships
PR 4 · Entry ID encoding	✅ Merged (#753)	Medium	Payload IDs, prefetch cache keys, visited-response cache keys, and browser state now encode interception context so intercepted and direct renders of the same pathname do not alias each other.
PR 5 · previousNextUrl tracking	Open (#755)	Medium	Browser state and history state track previousNextUrl so refresh/back-forward preserve the intercepted view when appropriate while hard reload still breaks out to the direct page.

Remaining known follow-up after PR 5: server-action interception-request parity is still intentionally deferred. PR 4 fixed payload/cache identity. PR 5 focuses on previousNextUrl, refresh, and traversal behavior.

---

Phase 3 — Skip Header Cluster 3 PRs

Server skips re-rendering static layouts the client already has. This is the first major perf phase.

PR	Risk	What ships
PR 6 · Static/dynamic detection	Medium	Build-time analysis tags layouts that use headers(), cookies(), or uncached fetch() as dynamic.
PR 7 · X-Vinext-Router-Skip	High	Client sends cached entry IDs and the server omits static layouts it can safely skip.
PR 8 · Entry eviction + LRU	Medium	Dynamic layout entries expire, static entries remain eligible for indefinite reuse, and the client cache gets a bounded size as a safety valve.

PR 8 is shown as a soft dependency after skip headers, not a hard gate. If we decide we want bounded caches earlier, we can pull it forward.

---

Phase 4 — Incremental Streaming 2 PRs

Entries stream to the client independently instead of gating on one root promise.

PR	Risk	What ships
PR 9 · Streaming store	High	Replace single Promise<Elements> with per-entry promises or a streaming map.
PR 10 · Progressive reveal	Medium	Fast entries render immediately while slower entries continue streaming behind Suspense.

This phase only depends on the flat-map foundation. It does not need to wait for Activity preservation or the full cache-policy track.

---

Phase 5 — Activity Route Preservation 3 PRs

Move from layout-entry persistence toward current Next.js cacheComponents behavior by preserving recent routes, not just shared layouts.

PR	Risk	What ships
PR 11 · Hidden route model	High	Recent routes stay mounted behind React Activity boundaries instead of being fully unmounted on navigation. This preserves page React state and DOM state (form drafts, scroll positions, expanded details), not just shared layouts.
PR 12 · Route eviction heuristics	Medium	Preserve only a small recent-route set, evict the oldest hidden route when the cap is exceeded, and keep back/forward restoration coherent when a route is still resident.
PR 13 · Hidden-route polish	Medium	Handle auth/user changes, reset semantics, scroll/focus restoration, page-level style leakage from hidden DOM, visibility-aware testing, and effect cleanup/recreate when a route transitions hidden ↔ visible.

This phase can begin once the flat-map/browser-state model is stable. It should be informed by the Router Cache policy work, but it is not strictly blocked on every perf phase landing first.

---

Phase 6 — Router Cache Policy cross-cutting

Make reuse and invalidation behavior explicit so vinext follows documented Next.js policy, not just similar architecture.

PR	Risk	What ships
PR 14 · Invalidation semantics	Medium	Define how visited-response cache, prefetch cache, hidden-route preservation, and skip-header caches respond to router.refresh(), server actions, revalidatePath, revalidateTag, draft mode, and auth/cookie changes.
PR 15 · staleTimes / page reuse policy	Medium	Align page-segment reuse with current Next.js docs: page segments are not reused from the client cache during navigation by default; explicit staleTimes opt page reuse back in. Keep this separate from hidden-route preservation.
PR 16 · Prefetch cache semantics	Medium	Define what next/link prefetch seeds, when prefetched entries go stale, and how prefetch keys/invalidation compose with interception context, previousNextUrl, hidden routes, and skip headers.

This is intentionally shown as a cross-cutting track rather than “the last phase.” It can start once the interception-context model is stable, and it should shape how Phases 3 and 5 behave.

Next.js references driving Phase 6

• Client cache / prefetching: prefetching guide
• staleTimes / page reuse: Version 15 upgrade note
• revalidatePath: caching without cache components
• revalidateTag: ISR guide
• cacheComponents + Activity: cacheComponents config docs

Current design decisions that still hold

• Unmatched parallel slot behavior: absent key = persisted from prior soft nav; explicit wire marker normalized to UNMATCHED_SLOT = unmatched with no default.js; any other value (including null) renders normally.
• Root layout switching: stays in the browser navigation path. Different root layout tree path means hard navigation (window.location.assign()), not merge.
• Error boundary reset: pathname-based reset remains required for same-route navigations; cross-route navigations get fresh route wiring entries.
• __route invariant: missing or non-string __route should fail loudly during development instead of producing a silent blank screen.
• SSR providers: ServerInsertedHTMLContext and font data must remain at the same tree positions in VinextFlightRoot.
• Entry eviction: still deferred until the skip-header/cache-policy phases where stale reused entries become a real correctness concern.

[NathanDrake2406]

@james-elicx Hey James could u pls ask Bonk to review this plan as well? Codex's only got a day of x2 left and they just reset the limit again.
I'll crank out the code tomorrow

[james-elicx]

I just ask that we please try and keep the PRs on the smaller side and break them up more where possible 🙏

[james-elicx]

/bigbonk please review the plan in this issue and share your thoughts.

[ask-bonk]

Now I have a thorough understanding of both the current architecture and the proposed plan. Let me write my review.

---

Plan Review: Waku-style Layout Persistence for vinext

Overall Assessment

This is a well-researched and detailed plan. The flat keyed map architecture is the right approach — it's how both Waku and (conceptually) Next.js solve layout persistence, and it maps cleanly onto React's reconciliation model. The phase breakdown is sensible and the entry taxonomy is well thought out. Here are my detailed thoughts.

What's Strong

The entry ID taxonomy is correct. Separating layout entries (persist) from route wiring entries (always fresh) is the core insight, and the plan gets this right. Boundaries in the wiring, LayoutSegmentProvider in the wiring, templates as separate entries with segment-scoped keys — all of this matches Next.js semantics.

The concurrency mitigation is sound. Awaiting createFromFetch() before dispatching to the reducer eliminates the chained-promise blocking problem. This is a pragmatic choice that avoids the complexity of Next.js's interruptible reducer while still being correct.

The merge/replace semantics table is clear and correct. Navigation, refresh, server actions all merge; only HMR replaces. This matches both Next.js and Waku behavior.

The useReducer for atomic state updates is the right call. The current useState<BrowserTreeState> with a module-level setter captured in useLayoutEffect is fragile. A reducer guarantees elements and routeId update atomically.

Concerns and Suggestions

1. PR 2 ("The Switch") is too large.

James flagged this in his comment, and I agree. PR 2 as described touches:

• 4 new client components (Slot, Children, ParallelSlot, mergeElementsPromise)
• buildRouteWiring() helper
• Complete rewrite of buildPageElement() → buildPageElements()
• Browser entry rewrite (useState → useReducer, single ReactNode → flat map)
• SSR entry adaptation
• Server action response format change
• HMR handler change

This is a flag day change across every layer of the stack. If anything goes wrong, bisecting is impossible. I'd suggest splitting PR 2 into at least 3 PRs:

• PR 2a: Client primitives — Slot, Children, ParallelSlot, mergeElementsPromise, ElementsContext, ChildrenContext, ParallelSlotsContext. Pure additions, no behavioral change. Unit tests for each.
• PR 2b: Server flat map — buildPageElements() + buildRouteWiring() in the RSC entry. Can be tested by verifying the generated code structure (entry-templates snapshot update) and by round-tripping through RSC serialization in unit tests.
• PR 2c: Browser + SSR switch — The actual cutover: browser reducer, SSR VinextFlightRoot, server action format, HMR. This is still the riskiest PR, but it's now focused on one concern (consuming the new format) rather than also producing it.

2. The __route string indirection adds fragility.

The __route entry is a string that points to the actual route wiring entry ID. The SSR entry reads it as elements.__route, the browser reads it after awaiting, navigation reads it from resolved elements. This is a runtime type-unsafe lookup — a typo or missing __route key silently produces undefined, and <Slot id={undefined} /> renders nothing.

Consider making __route a well-known symbol or at minimum adding a runtime invariant:

const routeId = elements.__route;
if (typeof routeId !== 'string') {
  throw new Error(`Missing __route key in RSC payload`);
}

This would turn a silent blank screen into an actionable error during development.

3. Parallel slot unmatched behavior (case 1 vs 2) needs more design detail.

The plan correctly identifies three cases (soft nav preserve, hard load default.js, no default.js → not-found), but doesn't specify how the Slot component distinguishes case 1 from case 2. The plan says:

The distinction is determined by whether the navigation is a client-side transition (merge — old entry persists) or a full page load (no prior entries exist).

But Slot only sees elements[id]. It doesn't know whether it's a first load or a subsequent navigation. The Slot component needs a signal — either:

• A isInitialLoad flag in context (set by BrowserRoot on first render, cleared after hydration)
• Or the server explicitly includes a null sentinel for unmatched slots on hard loads (distinguishing "slot not in payload because it persists from a prior navigation" from "slot not in payload because it doesn't match and has no default.js")

This distinction matters for correctness. I'd recommend addressing it in Phase 1, not deferring it — parallel slots without proper default.js handling on hard loads will produce blank areas.

4. Error boundary reset mechanism isn't fully specified.

The plan says boundaries in the route wiring "naturally reset" because the wiring is always fresh. But React error boundaries reset when their key changes or when getDerivedStateFromProps detects a prop change, not when a parent re-renders with new children. If the ErrorBoundary component instance is preserved by React reconciliation (same position, same key), its error state persists even if its children change.

The current NotFoundBoundary uses getDerivedStateFromProps to reset on pathname change (packages/vinext/src/shims/error-boundary.tsx). With the flat map architecture, the wiring is always a fresh React tree from createFromFetch, so React will unmount and remount the boundary instances. This is correct — but only if the route wiring entry ID changes between navigations (which it does: route:/blog/hello vs route:/about). Same-route navigations (e.g., search param changes) keep the same route wiring ID, so the boundary instance persists. Make sure the getDerivedStateFromProps pathname-based reset is preserved for same-route navigations, or error state will stick across search param changes.

5. The plan should address the ServerInsertedHTMLContext and font data injection paths.

The SSR entry currently wraps the tree with ServerInsertedHTMLContext.Provider for CSS-in-JS libraries (styled-components, etc.) and handles font data injection. The plan's SSR section shows VinextFlightRoot but doesn't mention these wrappers. They need to be preserved at the same tree positions to avoid breaking CSS-in-JS support and font optimization. This is likely just an omission in the writeup, but worth confirming.

6. renderToReadableStream with Record<string, ReactNode> — verify this works with the tick-buffered transform.

The plan says the RSC plugin supports structured payloads (confirmed by plugin maintainer). But the SSR entry's createTickBufferedTransform reads the RSC stream as raw bytes for HTML embedding. The stream format changes (single node → record), but since the transform is byte-level (not React-aware), it should be fine. Worth a quick verification that the embedded <script> chunks for the RSC payload correctly reconstruct the record on the client side during hydration.

7. Entry eviction deferral is acceptable but the monotonic growth should be bounded.

The plan acknowledges entries grow monotonically and argues 100 ReactNode references are negligible. This is true for the element references themselves, but each ReactNode holds closures over its props and component references. A long-running SPA session visiting routes with large data payloads (e.g., a dashboard with 50 different report pages, each with heavy server-fetched data) could accumulate non-trivial memory. Consider adding a simple LRU cap (e.g., 50 entries) in Phase 1 as a safety valve, even without the full eviction strategy.

8. Root layout switching detection.

The plan mentions this under "Entry ID limitations" but doesn't specify where the detection happens. It should be in the browser entry's navigation path — after deserializing the new elements, compare the root layout segment path with the current one. If different, window.location.assign(). This needs to be implemented in Phase 1, not deferred, because navigating between routes with different root layouts and merging would produce a broken tree.

On the Phasing

The 4-phase breakdown is good. Phase 1 is the critical path. Phases 2-4 are correctly identified as follow-ups. Two notes:

• Phase 2 (Interception Context) before Phase 3 (Skip Header) is correct — it's a correctness issue, not a perf issue.
• Phase 4 (Incremental Streaming) is correctly deprioritized — the current all-at-once gating with Suspense inside entries is fine for most apps.

On the PR Breakdown (from the roadmap comment)

The 3-PR Phase 1 breakdown (segmentMap Migration → The Switch → Verification) is reasonable but "The Switch" is still too big as noted above. The segmentMap migration PR (#737) as a standalone improvement is a good incremental step.

Bottom Line

The architecture is sound and well-aligned with both Next.js semantics and Waku's proven implementation. The main risk is in execution — specifically the size of "The Switch" PR and the parallel slot hard-load behavior. Breaking PR 2 into smaller pieces and nailing the Slot component's unmatched-slot logic will be the difference between a smooth rollout and a painful debugging session.

github run

[NathanDrake2406]

Response to bonk's review

Agreed with almost everything. Here's our response point by point, and updated roadmap below.

Accepted (will action)

1. PR 2 is too large. Splitting into 3 PRs (see updated roadmap). Client primitives → helper extraction → the actual switch. James asked for smaller PRs too.

2. __route string indirection. Will add a runtime invariant in PR 2c. One line, turns blank screen into actionable error.

3. Parallel slot unmatched behavior. This is the most important gap. Slot returns null for missing IDs but can't distinguish "missing because it persists from soft nav" (correct) from "missing because hard load + no default.js" (should show not-found). Plan: server sends explicit null sentinel for unmatched slots on hard loads. Absent key = persisted from prior nav. null value = unmatched, render default.js or not-found. Will design this before PR 2c.

4. Error boundary reset on same-route nav. Existing getDerivedStateFromProps pathname reset in error-boundary.tsx handles this. Will add an explicit test case during PR 2c to verify it's preserved.

5. ServerInsertedHTMLContext + font data. Writeup omission. SSR providers stay at same tree positions. Will note in PR 2c.

6. Tick-buffered transform with Record payload. Byte-level transform, not React-aware. Will verify during PR 2b (server flat map) that embedded <script> chunks correctly reconstruct the record.

8. Root layout switching must be Phase 1. Agreed — merging elements from different root layouts = broken tree. Will implement detection (compare root layout segment paths) + hard nav fallback (window.location.assign()) in PR 2c.

Disagreed

7. LRU cap in Phase 1. The elements map holds ReactNode references (element descriptors), not fetched data. Data lives in component closures that get GC'd on unmount. Waku has no eviction for the same reason. An LRU cap adds complexity (which entry to evict? what if a layout is still mounted?) that isn't justified until the skip header in Phase 3 makes staleness a real concern. Will revisit in Phase 3.