feat(app-router): filter skipped layouts from RSC responses and cached reads

Introduce app-page-skip-filter.ts with the canonical-bytes guarantee:
the render path always produces the full RSC payload and writes it to
the cache; the egress branch applies a byte-level filter that omits
layouts the client asked to skip, but only if the server independently
classified them as static (computeSkipDecision).

Wire the filter into renderAppPageLifecycle and buildAppPageCachedResponse
so both fresh renders and cache hits honor the skip header. Parse the
incoming X-Vinext-Router-Skip header at the handler scope and thread
the resulting set through render and ISR.

Gate the filter behind supportsFilteredRscStream: false in the generated
entry so this PR is dormant at runtime until the canonical-stream story
is validated. Tests exercise the filter directly by injecting the skip
set into renderAppPageLifecycle options.

Author: NathanDrake2406

packages/vinext/src/entries/app-rsc-entry.ts

@@ -394,6 +394,8 @@ import {
 import {
   APP_INTERCEPTION_CONTEXT_KEY as __APP_INTERCEPTION_CONTEXT_KEY,
   createAppPayloadRouteId as __createAppPayloadRouteId,
+  parseSkipHeader as __parseSkipHeader,
+  X_VINEXT_ROUTER_SKIP_HEADER as __X_VINEXT_ROUTER_SKIP_HEADER,
 } from ${JSON.stringify(appElementsPath)};
 import {
   buildAppPageElements as __buildAppPageElements,
@@ -1420,6 +1422,9 @@ async function _handleRequest(request, __reqCtx, _mwCtx) {
   }
 
   const isRscRequest = pathname.endsWith(".rsc") || request.headers.get("accept")?.includes("text/x-component");
+  const __skipLayoutIds = isRscRequest
+    ? __parseSkipHeader(request.headers.get(__X_VINEXT_ROUTER_SKIP_HEADER))
+    : new Set();
   // Read mounted-slots header once at the handler scope and thread it through
   // every buildPageElements call site. Previously both the handler and
   // buildPageElements read and normalized it independently, which invited
@@ -2206,6 +2211,7 @@ async function _handleRequest(request, __reqCtx, _mwCtx) {
       isrSet: __isrSet,
       mountedSlotsHeader: __mountedSlotsHeader,
       revalidateSeconds,
+      skipIds: __skipLayoutIds,
       renderFreshPageForCache: async function() {
         // Re-render the page to produce fresh HTML + RSC data for the cache
         // Use an empty headers context for background regeneration — not the original
@@ -2420,6 +2426,7 @@ async function _handleRequest(request, __reqCtx, _mwCtx) {
     isForceStatic,
     isProduction: process.env.NODE_ENV === "production",
     isRscRequest,
+    supportsFilteredRscStream: false,
     isrDebug: __isrDebug,
     isrHtmlKey: __isrHtmlKey,
     isrRscKey: __isrRscKey,
@@ -2468,6 +2475,7 @@ async function _handleRequest(request, __reqCtx, _mwCtx) {
     },
     revalidateSeconds,
     mountedSlotsHeader: __mountedSlotsHeader,
+    requestedSkipLayoutIds: __skipLayoutIds,
     renderErrorBoundaryResponse(renderErr) {
       return renderErrorBoundaryPage(route, renderErr, isRscRequest, request, params, _scriptNonce);
     },

packages/vinext/src/server/app-elements.ts

@@ -101,6 +101,47 @@ export function resolveVisitedResponseInterceptionContext(
   return payloadInterceptionContext ?? requestInterceptionContext;
 }
 
+export const X_VINEXT_ROUTER_SKIP_HEADER = "X-Vinext-Router-Skip";
+export const X_VINEXT_MOUNTED_SLOTS_HEADER = "X-Vinext-Mounted-Slots";
+
+export function parseSkipHeader(header: string | null): ReadonlySet<string> {
+  if (!header) return new Set();
+  const ids = new Set<string>();
+  for (const part of header.split(",")) {
+    const trimmed = part.trim();
+    if (trimmed.startsWith("layout:")) {
+      ids.add(trimmed);
+    }
+  }
+  return ids;
+}
+
+const EMPTY_SKIP_DECISION: ReadonlySet<string> = new Set<string>();
+
+/**
+ * Pure: computes the authoritative set of layout ids that should be omitted
+ * from the outgoing payload. Defense-in-depth — an id is only included if the
+ * server independently classified it as `"s"` (static). Empty or missing
+ * `requested` yields a shared empty set so the hot path does not allocate.
+ *
+ * See `LayoutFlags` type docblock in this file for lifecycle.
+ */
+export function computeSkipDecision(
+  layoutFlags: LayoutFlags,
+  requested: ReadonlySet<string> | undefined,
+): ReadonlySet<string> {
+  if (!requested || requested.size === 0) {
+    return EMPTY_SKIP_DECISION;
+  }
+  const decision = new Set<string>();
+  for (const id of requested) {
+    if (layoutFlags[id] === "s") {
+      decision.add(id);
+    }
+  }
+  return decision;
+}
+
 export function normalizeAppElements(elements: AppWireElements): AppElements {
   let needsNormalization = false;
   for (const [key, value] of Object.entries(elements)) {

packages/vinext/src/server/app-page-cache.ts

@@ -1,5 +1,8 @@
 import type { CachedAppPageValue } from "../shims/cache.js";
 import { buildAppPageCacheValue, type ISRCacheEntry } from "./isr-cache.js";
+import { wrapRscBytesForResponse } from "./app-page-skip-filter.js";
+
+const EMPTY_SKIP_SET: ReadonlySet<string> = new Set<string>();
 
 type AppPageDebugLogger = (event: string, detail: string) => void;
 type AppPageCacheGetter = (key: string) => Promise<ISRCacheEntry | null>;
@@ -22,6 +25,7 @@ export type BuildAppPageCachedResponseOptions = {
   isRscRequest: boolean;
   mountedSlotsHeader?: string | null;
   revalidateSeconds: number;
+  skipIds?: ReadonlySet<string>;
 };
 
 export type ReadAppPageCacheResponseOptions = {
@@ -37,6 +41,7 @@ export type ReadAppPageCacheResponseOptions = {
   revalidateSeconds: number;
   renderFreshPageForCache: () => Promise<AppPageCacheRenderResult>;
   scheduleBackgroundRegeneration: AppPageBackgroundRegenerator;
+  skipIds?: ReadonlySet<string>;
 };
 
 export type FinalizeAppPageHtmlCacheResponseOptions = {
@@ -106,7 +111,9 @@ export function buildAppPageCachedResponse(
       rscHeaders["X-Vinext-Mounted-Slots"] = options.mountedSlotsHeader;
     }
 
-    return new Response(cachedValue.rscData, {
+    const body = wrapRscBytesForResponse(cachedValue.rscData, options.skipIds ?? EMPTY_SKIP_SET);
+
+    return new Response(body, {
       status,
       headers: rscHeaders,
     });
@@ -142,6 +149,7 @@ export async function readAppPageCacheResponse(
         isRscRequest: options.isRscRequest,
         mountedSlotsHeader: options.mountedSlotsHeader,
         revalidateSeconds: options.revalidateSeconds,
+        skipIds: options.skipIds,
       });
 
       if (hitResponse) {
@@ -198,6 +206,7 @@ export async function readAppPageCacheResponse(
         isRscRequest: options.isRscRequest,
         mountedSlotsHeader: options.mountedSlotsHeader,
         revalidateSeconds: options.revalidateSeconds,
+        skipIds: options.skipIds,
       });
 
       if (staleResponse) {

packages/vinext/src/server/app-page-render.ts

@@ -1,10 +1,15 @@
 import type { ReactNode } from "react";
 import type { CachedAppPageValue } from "../shims/cache.js";
-import { buildOutgoingAppPayload, type AppOutgoingElements } from "./app-elements.js";
+import {
+  buildOutgoingAppPayload,
+  computeSkipDecision,
+  type AppOutgoingElements,
+} from "./app-elements.js";
 import {
   finalizeAppPageHtmlCacheResponse,
   scheduleAppPageRscCacheWrite,
 } from "./app-page-cache.js";
+import { createSkipFilterTransform } from "./app-page-skip-filter.js";
 import {
   buildAppPageFontLinkHeader,
   resolveAppPageSpecialError,
@@ -32,6 +37,8 @@ import {
   type AppPageSsrHandler,
 } from "./app-page-stream.js";
 
+const EMPTY_SKIP_SET: ReadonlySet<string> = new Set<string>();
+
 type AppPageBoundaryOnError = (
   error: unknown,
   requestInfo: unknown,
@@ -68,6 +75,7 @@ export type RenderAppPageLifecycleOptions = {
   isForceStatic: boolean;
   isProduction: boolean;
   isRscRequest: boolean;
+  supportsFilteredRscStream?: boolean;
   isrDebug?: AppPageDebugLogger;
   isrHtmlKey: (pathname: string) => string;
   isrRscKey: (pathname: string, mountedSlotsHeader?: string | null) => string;
@@ -97,6 +105,7 @@ export type RenderAppPageLifecycleOptions = {
   waitUntil?: (promise: Promise<void>) => void;
   element: ReactNode | Readonly<Record<string, ReactNode>>;
   classification?: LayoutClassificationOptions | null;
+  requestedSkipLayoutIds?: ReadonlySet<string>;
 };
 
 function buildResponseTiming(
@@ -148,9 +157,9 @@ export async function renderAppPageLifecycle(
 
   const layoutFlags = preRenderResult.layoutFlags;
 
-  // Render the CANONICAL element. The outgoing payload carries per-layout
-  // static/dynamic flags under `__layoutFlags` so the client can later tell
-  // which layouts are safe to skip on subsequent navigations.
+  // Always render the CANONICAL element. Skip semantics are applied on the
+  // egress branch only so the cache branch receives full bytes regardless of
+  // the client's skip header. See `app-page-skip-filter.ts`.
   const outgoingElement = buildOutgoingAppPayload({
     element: options.element,
     layoutFlags,
@@ -172,9 +181,17 @@ export async function renderAppPageLifecycle(
       revalidateSeconds !== Infinity &&
       !options.isForceDynamic,
   );
-  const rscForResponse = rscCapture.responseStream;
   const isrRscDataPromise = rscCapture.capturedRscDataPromise;
 
+  const skipIds =
+    options.isRscRequest && (options.supportsFilteredRscStream ?? true)
+      ? computeSkipDecision(layoutFlags, options.requestedSkipLayoutIds)
+      : EMPTY_SKIP_SET;
+  const rscForResponse =
+    skipIds.size > 0
+      ? rscCapture.responseStream.pipeThrough(createSkipFilterTransform(skipIds))
+      : rscCapture.responseStream;
+
   if (options.isRscRequest) {
     const dynamicUsedDuringBuild = options.consumeDynamicUsage();
     const rscResponsePolicy = resolveAppPageRscResponsePolicy({