vinext 0.0.47 → 0.0.48

package/dist/server/app-elements-wire.js

@@ -0,0 +1,205 @@
+import { createArtifactCompatibilityEnvelope, parseArtifactCompatibilityEnvelope } from "./artifact-compatibility.js";
+import { isValidElement } from "react";
+//#region src/server/app-elements-wire.ts
+const APP_INTERCEPTION_SEPARATOR = "\0";
+const APP_ARTIFACT_COMPATIBILITY_KEY = "__artifactCompatibility";
+const APP_INTERCEPTION_CONTEXT_KEY = "__interceptionContext";
+const APP_LAYOUT_FLAGS_KEY = "__layoutFlags";
+const APP_ROUTE_KEY = "__route";
+const APP_ROOT_LAYOUT_KEY = "__rootLayout";
+const APP_UNMATCHED_SLOT_WIRE_VALUE = "__VINEXT_UNMATCHED_SLOT__";
+const UNMATCHED_SLOT = Symbol.for("vinext.unmatchedSlot");
+function appendInterceptionContext(identity, interceptionContext) {
+	return interceptionContext === null ? identity : `${identity}${APP_INTERCEPTION_SEPARATOR}${interceptionContext}`;
+}
+function createAppPayloadRouteId(routePath, interceptionContext) {
+	return appendInterceptionContext(`route:${routePath}`, interceptionContext);
+}
+function createAppPayloadPageId(routePath, interceptionContext) {
+	return appendInterceptionContext(`page:${routePath}`, interceptionContext);
+}
+function createAppPayloadLayoutId(treePath) {
+	return `layout:${treePath}`;
+}
+function createAppPayloadTemplateId(treePath) {
+	return `template:${treePath}`;
+}
+function createAppPayloadSlotId(slotName, treePath) {
+	return `slot:${slotName}:${treePath}`;
+}
+function createAppPayloadCacheKey(rscUrl, interceptionContext) {
+	return appendInterceptionContext(rscUrl, interceptionContext);
+}
+function parsePathWithInterception(input) {
+	const separatorIndex = input.indexOf(APP_INTERCEPTION_SEPARATOR);
+	const path = separatorIndex === -1 ? input : input.slice(0, separatorIndex);
+	if (!path.startsWith("/")) return null;
+	return {
+		interceptionContext: separatorIndex === -1 ? null : input.slice(separatorIndex + 1),
+		path
+	};
+}
+/**
+* AppElements tree paths are absolute route-tree paths on the wire.
+* Bare segment names are not valid layout/template/slot tree identities.
+*/
+function parseTreePath(input) {
+	return input.startsWith("/") ? input : null;
+}
+function parseAppElementsWireElementKey(key) {
+	if (key.startsWith("route:")) {
+		const parsed = parsePathWithInterception(key.slice(6));
+		if (!parsed) return null;
+		return {
+			interceptionContext: parsed.interceptionContext,
+			kind: "route",
+			path: parsed.path
+		};
+	}
+	if (key.startsWith("page:")) {
+		const parsed = parsePathWithInterception(key.slice(5));
+		if (!parsed) return null;
+		return {
+			interceptionContext: parsed.interceptionContext,
+			kind: "page",
+			path: parsed.path
+		};
+	}
+	if (key.startsWith("layout:")) {
+		const treePath = parseTreePath(key.slice(7));
+		return treePath ? {
+			kind: "layout",
+			treePath
+		} : null;
+	}
+	if (key.startsWith("template:")) {
+		const treePath = parseTreePath(key.slice(9));
+		return treePath ? {
+			kind: "template",
+			treePath
+		} : null;
+	}
+	if (key.startsWith("slot:")) {
+		const body = key.slice(5);
+		const separatorIndex = body.indexOf(":");
+		if (separatorIndex <= 0) return null;
+		const name = body.slice(0, separatorIndex);
+		const treePath = parseTreePath(body.slice(separatorIndex + 1));
+		return treePath ? {
+			kind: "slot",
+			name,
+			treePath
+		} : null;
+	}
+	return null;
+}
+function isAppElementsWireSlotId(key) {
+	if (!key.startsWith("slot:")) return false;
+	const body = key.slice(5);
+	const separatorIndex = body.indexOf(":");
+	return separatorIndex > 0 && body.charCodeAt(separatorIndex + 1) === 47;
+}
+function createAppElementsWireMetadataEntries(input) {
+	return {
+		[APP_ROUTE_KEY]: input.routeId,
+		[APP_INTERCEPTION_CONTEXT_KEY]: input.interceptionContext,
+		[APP_ROOT_LAYOUT_KEY]: input.rootLayoutTreePath
+	};
+}
+function normalizeAppElements(elements) {
+	let needsNormalization = false;
+	for (const [key, value] of Object.entries(elements)) if (isAppElementsWireSlotId(key) && value === "__VINEXT_UNMATCHED_SLOT__") {
+		needsNormalization = true;
+		break;
+	}
+	if (!needsNormalization) return elements;
+	const normalized = {};
+	for (const [key, value] of Object.entries(elements)) normalized[key] = isAppElementsWireSlotId(key) && value === "__VINEXT_UNMATCHED_SLOT__" ? UNMATCHED_SLOT : value;
+	return normalized;
+}
+function isLayoutFlagsRecord(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	for (const v of Object.values(value)) if (v !== "s" && v !== "d") return false;
+	return true;
+}
+function parseLayoutFlags(value) {
+	if (isLayoutFlagsRecord(value)) return value;
+	return {};
+}
+/**
+* Type predicate for a plain (non-null, non-array) record of app payload values.
+* Used to distinguish the App Router payload object from bare React elements at
+* the render boundary. Narrows to `Readonly<Record<string, unknown>>` because
+* the outgoing payload carries heterogeneous values (ReactNodes for the rendered
+* tree, plus metadata like `__layoutFlags` which is a plain object). Delegates
+* to React's canonical `isValidElement` so we don't depend on React's internal
+* `$$typeof` marker scheme.
+*/
+function isAppElementsRecord(value) {
+	if (typeof value !== "object" || value === null) return false;
+	if (Array.isArray(value)) return false;
+	if (isValidElement(value)) return false;
+	return true;
+}
+function withLayoutFlags(elements, layoutFlags) {
+	return {
+		...elements,
+		[APP_LAYOUT_FLAGS_KEY]: layoutFlags
+	};
+}
+function buildOutgoingAppPayload(input) {
+	if (!isAppElementsRecord(input.element)) return input.element;
+	return {
+		...input.element,
+		[APP_LAYOUT_FLAGS_KEY]: input.layoutFlags,
+		[APP_ARTIFACT_COMPATIBILITY_KEY]: input.artifactCompatibility ?? createArtifactCompatibilityEnvelope()
+	};
+}
+function readArtifactCompatibilityMetadata(value) {
+	if (value === void 0) return createArtifactCompatibilityEnvelope();
+	return parseArtifactCompatibilityEnvelope(value) ?? createArtifactCompatibilityEnvelope();
+}
+function readAppElementsMetadata(elements) {
+	const routeId = elements[APP_ROUTE_KEY];
+	if (typeof routeId !== "string") throw new Error("[vinext] Missing __route string in App Router payload");
+	const interceptionContext = elements[APP_INTERCEPTION_CONTEXT_KEY];
+	if (interceptionContext !== void 0 && interceptionContext !== null && typeof interceptionContext !== "string") throw new Error("[vinext] Invalid __interceptionContext in App Router payload");
+	const rootLayoutTreePath = elements[APP_ROOT_LAYOUT_KEY];
+	if (rootLayoutTreePath === void 0) throw new Error("[vinext] Missing __rootLayout key in App Router payload");
+	if (rootLayoutTreePath !== null && typeof rootLayoutTreePath !== "string") throw new Error("[vinext] Invalid __rootLayout in App Router payload: expected string or null");
+	const layoutFlags = parseLayoutFlags(elements[APP_LAYOUT_FLAGS_KEY]);
+	return {
+		artifactCompatibility: readArtifactCompatibilityMetadata(elements[APP_ARTIFACT_COMPATIBILITY_KEY]),
+		interceptionContext: interceptionContext ?? null,
+		layoutFlags,
+		routeId,
+		rootLayoutTreePath
+	};
+}
+const AppElementsWire = {
+	keys: {
+		artifactCompatibility: APP_ARTIFACT_COMPATIBILITY_KEY,
+		interceptionContext: APP_INTERCEPTION_CONTEXT_KEY,
+		layoutFlags: APP_LAYOUT_FLAGS_KEY,
+		rootLayout: APP_ROOT_LAYOUT_KEY,
+		route: APP_ROUTE_KEY
+	},
+	unmatchedSlotValue: APP_UNMATCHED_SLOT_WIRE_VALUE,
+	createMetadataEntries: createAppElementsWireMetadataEntries,
+	decode: normalizeAppElements,
+	encodeCacheKey: createAppPayloadCacheKey,
+	encodeLayoutId: createAppPayloadLayoutId,
+	encodeOutgoingPayload: buildOutgoingAppPayload,
+	encodePageId: createAppPayloadPageId,
+	encodeRouteId: createAppPayloadRouteId,
+	encodeSlotId: createAppPayloadSlotId,
+	encodeTemplateId: createAppPayloadTemplateId,
+	isSlotId: isAppElementsWireSlotId,
+	parseElementKey: parseAppElementsWireElementKey,
+	readMetadata: readAppElementsMetadata,
+	withLayoutFlags
+};
+//#endregion
+export { APP_ARTIFACT_COMPATIBILITY_KEY, APP_INTERCEPTION_CONTEXT_KEY, APP_LAYOUT_FLAGS_KEY, APP_ROOT_LAYOUT_KEY, APP_ROUTE_KEY, APP_UNMATCHED_SLOT_WIRE_VALUE, AppElementsWire, UNMATCHED_SLOT, buildOutgoingAppPayload, isAppElementsRecord, normalizeAppElements, readAppElementsMetadata, withLayoutFlags };
+
+//# sourceMappingURL=app-elements-wire.js.map

package/dist/server/app-elements-wire.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-elements-wire.js","names":[],"sources":["../../src/server/app-elements-wire.ts"],"sourcesContent":["import { isValidElement, type ReactNode } from \"react\";\nimport {\n  createArtifactCompatibilityEnvelope,\n  parseArtifactCompatibilityEnvelope,\n  type ArtifactCompatibilityEnvelope,\n} from \"./artifact-compatibility.js\";\n\nconst APP_INTERCEPTION_SEPARATOR = \"\\0\";\n\nexport const APP_ARTIFACT_COMPATIBILITY_KEY = \"__artifactCompatibility\";\nexport const APP_INTERCEPTION_CONTEXT_KEY = \"__interceptionContext\";\nexport const APP_LAYOUT_FLAGS_KEY = \"__layoutFlags\";\nexport const APP_ROUTE_KEY = \"__route\";\nexport const APP_ROOT_LAYOUT_KEY = \"__rootLayout\";\nexport const APP_UNMATCHED_SLOT_WIRE_VALUE = \"__VINEXT_UNMATCHED_SLOT__\";\n\nexport const UNMATCHED_SLOT = Symbol.for(\"vinext.unmatchedSlot\");\n\nexport type AppElementValue = ReactNode | typeof UNMATCHED_SLOT | string | null;\ntype AppWireElementValue = ReactNode | string | null;\n\nexport type AppElements = Readonly<Record<string, AppElementValue>>;\nexport type AppWireElements = Readonly<Record<string, AppWireElementValue>>;\n\n/**\n * Per-layout static/dynamic flags. `\"s\"` = static (skippable on next nav);\n * `\"d\"` = dynamic (must always render).\n *\n * Lifecycle (partial — later PRs extend this):\n *\n *   1. PROBE   — probeAppPageLayouts (server/app-page-execution.ts) returns\n *                LayoutFlags for every layout in the route at render time.\n *\n *   2. ATTACH  — AppElementsWire.encodeOutgoingPayload writes `__layoutFlags`\n *                into the outgoing App Router payload record.\n *\n *   3. WIRE    — renderToReadableStream serializes the record as RSC row 0.\n *\n *   4. PARSE   — AppElementsWire.readMetadata extracts layoutFlags from the\n *                wire payload on the client side.\n */\nexport type LayoutFlags = Readonly<Record<string, \"s\" | \"d\">>;\n\ntype AppElementsMetadata = {\n  artifactCompatibility: ArtifactCompatibilityEnvelope;\n  interceptionContext: string | null;\n  layoutFlags: LayoutFlags;\n  routeId: string;\n  rootLayoutTreePath: string | null;\n};\n\ntype AppElementsWireElementKey =\n  | { kind: \"layout\"; treePath: string }\n  | { interceptionContext: string | null; kind: \"page\"; path: string }\n  | { interceptionContext: string | null; kind: \"route\"; path: string }\n  | { kind: \"slot\"; name: string; treePath: string }\n  | { kind: \"template\"; treePath: string };\n\ntype AppElementsWireMetadataInput = {\n  interceptionContext: string | null;\n  routeId: string;\n  rootLayoutTreePath: string | null;\n};\n\ntype AppElementsWireMetadataEntries = Readonly<{\n  [APP_ROUTE_KEY]: string;\n  [APP_INTERCEPTION_CONTEXT_KEY]: string | null;\n  [APP_ROOT_LAYOUT_KEY]: string | null;\n}>;\n\n/**\n * The outgoing wire payload shape. Includes ReactNode values for the\n * rendered tree plus metadata values like LayoutFlags attached under\n * known keys (e.g. __layoutFlags). Distinct from AppElements / AppWireElements\n * which only carry render-time values.\n */\nexport type AppOutgoingElements = Readonly<\n  Record<string, ReactNode | LayoutFlags | ArtifactCompatibilityEnvelope>\n>;\n\ntype AppElementsWireKeys = {\n  readonly artifactCompatibility: typeof APP_ARTIFACT_COMPATIBILITY_KEY;\n  readonly interceptionContext: typeof APP_INTERCEPTION_CONTEXT_KEY;\n  readonly layoutFlags: typeof APP_LAYOUT_FLAGS_KEY;\n  readonly rootLayout: typeof APP_ROOT_LAYOUT_KEY;\n  readonly route: typeof APP_ROUTE_KEY;\n};\n\ntype AppElementsWireCodec = {\n  readonly keys: AppElementsWireKeys;\n  readonly unmatchedSlotValue: typeof APP_UNMATCHED_SLOT_WIRE_VALUE;\n  createMetadataEntries(input: AppElementsWireMetadataInput): AppElementsWireMetadataEntries;\n  decode(elements: AppWireElements): AppElements;\n  encodeCacheKey(rscUrl: string, interceptionContext: string | null): string;\n  encodeLayoutId(treePath: string): string;\n  encodeOutgoingPayload(input: {\n    element: ReactNode | Readonly<Record<string, ReactNode>>;\n    artifactCompatibility?: ArtifactCompatibilityEnvelope;\n    layoutFlags: LayoutFlags;\n  }): ReactNode | AppOutgoingElements;\n  encodePageId(routePath: string, interceptionContext: string | null): string;\n  encodeRouteId(routePath: string, interceptionContext: string | null): string;\n  encodeSlotId(slotName: string, treePath: string): string;\n  encodeTemplateId(treePath: string): string;\n  isSlotId(key: string): boolean;\n  parseElementKey(key: string): AppElementsWireElementKey | null;\n  readMetadata(elements: Readonly<Record<string, unknown>>): AppElementsMetadata;\n  withLayoutFlags<T extends Record<string, unknown>>(\n    elements: T,\n    layoutFlags: LayoutFlags,\n  ): T & { [APP_LAYOUT_FLAGS_KEY]: LayoutFlags };\n};\n\nfunction appendInterceptionContext(identity: string, interceptionContext: string | null): string {\n  return interceptionContext === null\n    ? identity\n    : `${identity}${APP_INTERCEPTION_SEPARATOR}${interceptionContext}`;\n}\n\nfunction createAppPayloadRouteId(routePath: string, interceptionContext: string | null): string {\n  return appendInterceptionContext(`route:${routePath}`, interceptionContext);\n}\n\nfunction createAppPayloadPageId(routePath: string, interceptionContext: string | null): string {\n  return appendInterceptionContext(`page:${routePath}`, interceptionContext);\n}\n\nfunction createAppPayloadLayoutId(treePath: string): string {\n  return `layout:${treePath}`;\n}\n\nfunction createAppPayloadTemplateId(treePath: string): string {\n  return `template:${treePath}`;\n}\n\nfunction createAppPayloadSlotId(slotName: string, treePath: string): string {\n  return `slot:${slotName}:${treePath}`;\n}\n\nfunction createAppPayloadCacheKey(rscUrl: string, interceptionContext: string | null): string {\n  return appendInterceptionContext(rscUrl, interceptionContext);\n}\n\nfunction parsePathWithInterception(input: string): {\n  interceptionContext: string | null;\n  path: string;\n} | null {\n  const separatorIndex = input.indexOf(APP_INTERCEPTION_SEPARATOR);\n  const path = separatorIndex === -1 ? input : input.slice(0, separatorIndex);\n  if (!path.startsWith(\"/\")) return null;\n\n  return {\n    interceptionContext: separatorIndex === -1 ? null : input.slice(separatorIndex + 1),\n    path,\n  };\n}\n\n/**\n * AppElements tree paths are absolute route-tree paths on the wire.\n * Bare segment names are not valid layout/template/slot tree identities.\n */\nfunction parseTreePath(input: string): string | null {\n  return input.startsWith(\"/\") ? input : null;\n}\n\nfunction parseAppElementsWireElementKey(key: string): AppElementsWireElementKey | null {\n  if (key.startsWith(\"route:\")) {\n    const parsed = parsePathWithInterception(key.slice(\"route:\".length));\n    if (!parsed) return null;\n    return { interceptionContext: parsed.interceptionContext, kind: \"route\", path: parsed.path };\n  }\n\n  if (key.startsWith(\"page:\")) {\n    const parsed = parsePathWithInterception(key.slice(\"page:\".length));\n    if (!parsed) return null;\n    return { interceptionContext: parsed.interceptionContext, kind: \"page\", path: parsed.path };\n  }\n\n  if (key.startsWith(\"layout:\")) {\n    const treePath = parseTreePath(key.slice(\"layout:\".length));\n    return treePath ? { kind: \"layout\", treePath } : null;\n  }\n\n  if (key.startsWith(\"template:\")) {\n    const treePath = parseTreePath(key.slice(\"template:\".length));\n    return treePath ? { kind: \"template\", treePath } : null;\n  }\n\n  if (key.startsWith(\"slot:\")) {\n    const body = key.slice(\"slot:\".length);\n    const separatorIndex = body.indexOf(\":\");\n    if (separatorIndex <= 0) return null;\n    const name = body.slice(0, separatorIndex);\n    const treePath = parseTreePath(body.slice(separatorIndex + 1));\n    return treePath ? { kind: \"slot\", name, treePath } : null;\n  }\n\n  return null;\n}\n\nfunction isAppElementsWireSlotId(key: string): boolean {\n  if (!key.startsWith(\"slot:\")) return false;\n  const body = key.slice(\"slot:\".length);\n  const separatorIndex = body.indexOf(\":\");\n  return separatorIndex > 0 && body.charCodeAt(separatorIndex + 1) === 0x2f;\n}\n\nfunction createAppElementsWireMetadataEntries(\n  input: AppElementsWireMetadataInput,\n): AppElementsWireMetadataEntries {\n  return {\n    [APP_ROUTE_KEY]: input.routeId,\n    [APP_INTERCEPTION_CONTEXT_KEY]: input.interceptionContext,\n    [APP_ROOT_LAYOUT_KEY]: input.rootLayoutTreePath,\n  };\n}\n\nexport function normalizeAppElements(elements: AppWireElements): AppElements {\n  let needsNormalization = false;\n  for (const [key, value] of Object.entries(elements)) {\n    if (isAppElementsWireSlotId(key) && value === APP_UNMATCHED_SLOT_WIRE_VALUE) {\n      needsNormalization = true;\n      break;\n    }\n  }\n\n  if (!needsNormalization) {\n    return elements;\n  }\n\n  const normalized: Record<string, AppElementValue> = {};\n  for (const [key, value] of Object.entries(elements)) {\n    normalized[key] =\n      isAppElementsWireSlotId(key) && value === APP_UNMATCHED_SLOT_WIRE_VALUE\n        ? UNMATCHED_SLOT\n        : value;\n  }\n\n  return normalized;\n}\n\nfunction isLayoutFlagsRecord(value: unknown): value is LayoutFlags {\n  if (typeof value !== \"object\" || value === null || Array.isArray(value)) return false;\n  for (const v of Object.values(value)) {\n    if (v !== \"s\" && v !== \"d\") return false;\n  }\n  return true;\n}\n\nfunction parseLayoutFlags(value: unknown): LayoutFlags {\n  if (isLayoutFlagsRecord(value)) return value;\n  return {};\n}\n\n/**\n * Type predicate for a plain (non-null, non-array) record of app payload values.\n * Used to distinguish the App Router payload object from bare React elements at\n * the render boundary. Narrows to `Readonly<Record<string, unknown>>` because\n * the outgoing payload carries heterogeneous values (ReactNodes for the rendered\n * tree, plus metadata like `__layoutFlags` which is a plain object). Delegates\n * to React's canonical `isValidElement` so we don't depend on React's internal\n * `$$typeof` marker scheme.\n */\nexport function isAppElementsRecord(value: unknown): value is Readonly<Record<string, unknown>> {\n  if (typeof value !== \"object\" || value === null) return false;\n  if (Array.isArray(value)) return false;\n  if (isValidElement(value)) return false;\n  return true;\n}\n\nexport function withLayoutFlags<T extends Record<string, unknown>>(\n  elements: T,\n  layoutFlags: LayoutFlags,\n): T & { [APP_LAYOUT_FLAGS_KEY]: LayoutFlags } {\n  return { ...elements, [APP_LAYOUT_FLAGS_KEY]: layoutFlags };\n}\n\nexport function buildOutgoingAppPayload(input: {\n  element: ReactNode | Readonly<Record<string, ReactNode>>;\n  artifactCompatibility?: ArtifactCompatibilityEnvelope;\n  layoutFlags: LayoutFlags;\n}): ReactNode | AppOutgoingElements {\n  if (!isAppElementsRecord(input.element)) {\n    return input.element;\n  }\n  return {\n    ...input.element,\n    [APP_LAYOUT_FLAGS_KEY]: input.layoutFlags,\n    [APP_ARTIFACT_COMPATIBILITY_KEY]:\n      input.artifactCompatibility ?? createArtifactCompatibilityEnvelope(),\n  };\n}\n\nfunction readArtifactCompatibilityMetadata(value: unknown): ArtifactCompatibilityEnvelope {\n  if (value === undefined) return createArtifactCompatibilityEnvelope();\n\n  const artifactCompatibility = parseArtifactCompatibilityEnvelope(value);\n  // TODO(#726-COMPAT-04): hard-fail malformed compatibility metadata once\n  // cache/skip consumers depend on this proof. During Wave01 the field is\n  // emitted as scaffolding, so bad or future-version values degrade like\n  // missing __layoutFlags instead of crashing render paths that do not read it.\n  return artifactCompatibility ?? createArtifactCompatibilityEnvelope();\n}\n\nexport function readAppElementsMetadata(\n  elements: Readonly<Record<string, unknown>>,\n): AppElementsMetadata {\n  const routeId = elements[APP_ROUTE_KEY];\n  if (typeof routeId !== \"string\") {\n    throw new Error(\"[vinext] Missing __route string in App Router payload\");\n  }\n\n  const interceptionContext = elements[APP_INTERCEPTION_CONTEXT_KEY];\n  if (\n    interceptionContext !== undefined &&\n    interceptionContext !== null &&\n    typeof interceptionContext !== \"string\"\n  ) {\n    throw new Error(\"[vinext] Invalid __interceptionContext in App Router payload\");\n  }\n\n  const rootLayoutTreePath = elements[APP_ROOT_LAYOUT_KEY];\n  if (rootLayoutTreePath === undefined) {\n    throw new Error(\"[vinext] Missing __rootLayout key in App Router payload\");\n  }\n  if (rootLayoutTreePath !== null && typeof rootLayoutTreePath !== \"string\") {\n    throw new Error(\"[vinext] Invalid __rootLayout in App Router payload: expected string or null\");\n  }\n\n  const layoutFlags = parseLayoutFlags(elements[APP_LAYOUT_FLAGS_KEY]);\n  const artifactCompatibility = readArtifactCompatibilityMetadata(\n    elements[APP_ARTIFACT_COMPATIBILITY_KEY],\n  );\n\n  return {\n    artifactCompatibility,\n    interceptionContext: interceptionContext ?? null,\n    layoutFlags,\n    routeId,\n    rootLayoutTreePath,\n  };\n}\n\nexport const AppElementsWire: AppElementsWireCodec = {\n  // WIRE follow-ups use these stable key names when moving payload readers and writers\n  // behind the codec boundary.\n  keys: {\n    artifactCompatibility: APP_ARTIFACT_COMPATIBILITY_KEY,\n    interceptionContext: APP_INTERCEPTION_CONTEXT_KEY,\n    layoutFlags: APP_LAYOUT_FLAGS_KEY,\n    rootLayout: APP_ROOT_LAYOUT_KEY,\n    route: APP_ROUTE_KEY,\n  },\n  unmatchedSlotValue: APP_UNMATCHED_SLOT_WIRE_VALUE,\n  createMetadataEntries: createAppElementsWireMetadataEntries,\n  decode: normalizeAppElements,\n  encodeCacheKey: createAppPayloadCacheKey,\n  encodeLayoutId: createAppPayloadLayoutId,\n  encodeOutgoingPayload: buildOutgoingAppPayload,\n  encodePageId: createAppPayloadPageId,\n  encodeRouteId: createAppPayloadRouteId,\n  encodeSlotId: createAppPayloadSlotId,\n  encodeTemplateId: createAppPayloadTemplateId,\n  isSlotId: isAppElementsWireSlotId,\n  parseElementKey: parseAppElementsWireElementKey,\n  readMetadata: readAppElementsMetadata,\n  withLayoutFlags,\n};\n"],"mappings":"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"}

package/dist/server/app-elements.d.ts

@@ -1,91 +1,9 @@
-import { ReactNode } from "react";
+import { APP_ARTIFACT_COMPATIBILITY_KEY, APP_INTERCEPTION_CONTEXT_KEY, APP_LAYOUT_FLAGS_KEY, APP_ROOT_LAYOUT_KEY, APP_ROUTE_KEY, APP_UNMATCHED_SLOT_WIRE_VALUE, AppElementValue, AppElements, AppElementsWire, AppOutgoingElements, AppWireElements, LayoutFlags, UNMATCHED_SLOT, buildOutgoingAppPayload, isAppElementsRecord, normalizeAppElements, readAppElementsMetadata, withLayoutFlags } from "./app-elements-wire.js";
 
 //#region src/server/app-elements.d.ts
-declare const APP_INTERCEPTION_CONTEXT_KEY = "__interceptionContext";
-declare const APP_LAYOUT_FLAGS_KEY = "__layoutFlags";
-declare const APP_ROUTE_KEY = "__route";
-declare const APP_ROOT_LAYOUT_KEY = "__rootLayout";
-declare const APP_UNMATCHED_SLOT_WIRE_VALUE = "__VINEXT_UNMATCHED_SLOT__";
-declare const UNMATCHED_SLOT: unique symbol;
-type AppElementValue = ReactNode | typeof UNMATCHED_SLOT | string | null;
-type AppWireElementValue = ReactNode | string | null;
-type AppElements = Readonly<Record<string, AppElementValue>>;
-type AppWireElements = Readonly<Record<string, AppWireElementValue>>;
-/**
- * Per-layout static/dynamic flags. `"s"` = static (skippable on next nav);
- * `"d"` = dynamic (must always render).
- *
- * Lifecycle (partial — later PRs extend this):
- *
- *   1. PROBE   — probeAppPageLayouts (server/app-page-execution.ts) returns
- *                LayoutFlags for every layout in the route at render time.
- *
- *   2. ATTACH  — withLayoutFlags (this file) writes `__layoutFlags` into the
- *                outgoing App Router payload record.
- *
- *   3. WIRE    — renderToReadableStream serializes the record as RSC row 0.
- *
- *   4. PARSE   — readAppElementsMetadata (this file) extracts layoutFlags from
- *                the wire payload on the client side.
- */
-type LayoutFlags = Readonly<Record<string, "s" | "d">>;
-type AppElementsMetadata = {
-  interceptionContext: string | null;
-  layoutFlags: LayoutFlags;
-  routeId: string;
-  rootLayoutTreePath: string | null;
-};
 declare function getMountedSlotIds(elements: AppElements): string[];
 declare function getMountedSlotIdsHeader(elements: AppElements): string | null;
-declare function createAppPayloadRouteId(routePath: string, interceptionContext: string | null): string;
-declare function createAppPayloadPageId(routePath: string, interceptionContext: string | null): string;
-declare function createAppPayloadCacheKey(rscUrl: string, interceptionContext: string | null): string;
 declare function resolveVisitedResponseInterceptionContext(requestInterceptionContext: string | null, payloadInterceptionContext: string | null): string | null;
-declare function normalizeAppElements(elements: AppWireElements): AppElements;
-/**
- * Type predicate for a plain (non-null, non-array) record of app payload values.
- * Used to distinguish the App Router payload object from bare React elements at
- * the render boundary. Narrows to `Readonly<Record<string, unknown>>` because
- * the outgoing payload carries heterogeneous values (ReactNodes for the rendered
- * tree, plus metadata like `__layoutFlags` which is a plain object). Delegates
- * to React's canonical `isValidElement` so we don't depend on React's internal
- * `$$typeof` marker scheme.
- */
-declare function isAppElementsRecord(value: unknown): value is Readonly<Record<string, unknown>>;
-/**
- * Pure: returns a new record with `__layoutFlags` attached. Owns the write
- * boundary for the layout flags key so the write side sits next to
- * `readAppElementsMetadata`.
- *
- * See `LayoutFlags` type docblock in this file for lifecycle.
- */
-declare function withLayoutFlags<T extends Record<string, unknown>>(elements: T, layoutFlags: LayoutFlags): T & {
-  [APP_LAYOUT_FLAGS_KEY]: LayoutFlags;
-};
-/**
- * The outgoing wire payload shape. Includes ReactNode values for the
- * rendered tree plus metadata values like LayoutFlags attached under
- * known keys (e.g. __layoutFlags). Distinct from AppElements / AppWireElements
- * which only carry render-time values.
- */
-type AppOutgoingElements = Readonly<Record<string, ReactNode | LayoutFlags>>;
-/**
- * Pure: builds the outgoing payload for the wire. Non-record inputs (e.g. a
- * bare React element) are returned unchanged. Record inputs get a fresh copy
- * with `__layoutFlags` attached. Never mutates `input.element`.
- */
-declare function buildOutgoingAppPayload(input: {
-  element: ReactNode | Readonly<Record<string, ReactNode>>;
-  layoutFlags: LayoutFlags;
-}): ReactNode | AppOutgoingElements;
-/**
- * Parses metadata from the wire payload. Accepts `Record<string, unknown>`
- * because the RSC payload carries heterogeneous values (React elements,
- * strings, and plain objects like layout flags) under the same record type.
- *
- * See `LayoutFlags` type docblock in this file for lifecycle.
- */
-declare function readAppElementsMetadata(elements: Readonly<Record<string, unknown>>): AppElementsMetadata;
 //#endregion
-export { APP_INTERCEPTION_CONTEXT_KEY, APP_LAYOUT_FLAGS_KEY, APP_ROOT_LAYOUT_KEY, APP_ROUTE_KEY, APP_UNMATCHED_SLOT_WIRE_VALUE, AppElementValue, AppElements, AppOutgoingElements, AppWireElements, LayoutFlags, UNMATCHED_SLOT, buildOutgoingAppPayload, createAppPayloadCacheKey, createAppPayloadPageId, createAppPayloadRouteId, getMountedSlotIds, getMountedSlotIdsHeader, isAppElementsRecord, normalizeAppElements, readAppElementsMetadata, resolveVisitedResponseInterceptionContext, withLayoutFlags };
+export { APP_ARTIFACT_COMPATIBILITY_KEY, APP_INTERCEPTION_CONTEXT_KEY, APP_LAYOUT_FLAGS_KEY, APP_ROOT_LAYOUT_KEY, APP_ROUTE_KEY, APP_UNMATCHED_SLOT_WIRE_VALUE, type AppElementValue, type AppElements, AppElementsWire, type AppOutgoingElements, type AppWireElements, type LayoutFlags, UNMATCHED_SLOT, buildOutgoingAppPayload, getMountedSlotIds, getMountedSlotIdsHeader, isAppElementsRecord, normalizeAppElements, readAppElementsMetadata, resolveVisitedResponseInterceptionContext, withLayoutFlags };
 //# sourceMappingURL=app-elements.d.ts.map

package/dist/server/app-elements.js

@@ -1,118 +1,19 @@
 import { normalizeMountedSlotsHeader } from "./app-mounted-slots-header.js";
-import { isValidElement } from "react";
+import { APP_ARTIFACT_COMPATIBILITY_KEY, APP_INTERCEPTION_CONTEXT_KEY, APP_LAYOUT_FLAGS_KEY, APP_ROOT_LAYOUT_KEY, APP_ROUTE_KEY, APP_UNMATCHED_SLOT_WIRE_VALUE, AppElementsWire, UNMATCHED_SLOT, buildOutgoingAppPayload, isAppElementsRecord, normalizeAppElements, readAppElementsMetadata, withLayoutFlags } from "./app-elements-wire.js";
 //#region src/server/app-elements.ts
-const APP_INTERCEPTION_SEPARATOR = "\0";
-const APP_INTERCEPTION_CONTEXT_KEY = "__interceptionContext";
-const APP_LAYOUT_FLAGS_KEY = "__layoutFlags";
-const APP_ROUTE_KEY = "__route";
-const APP_ROOT_LAYOUT_KEY = "__rootLayout";
-const APP_UNMATCHED_SLOT_WIRE_VALUE = "__VINEXT_UNMATCHED_SLOT__";
-const UNMATCHED_SLOT = Symbol.for("vinext.unmatchedSlot");
 function getMountedSlotIds(elements) {
 	return Object.keys(elements).filter((key) => {
 		const value = elements[key];
-		return key.startsWith("slot:") && value !== null && value !== void 0 && value !== UNMATCHED_SLOT;
+		return AppElementsWire.isSlotId(key) && value !== null && value !== void 0 && value !== UNMATCHED_SLOT;
 	}).sort();
 }
 function getMountedSlotIdsHeader(elements) {
 	return normalizeMountedSlotsHeader(getMountedSlotIds(elements).join(" "));
 }
-function appendInterceptionContext(identity, interceptionContext) {
-	return interceptionContext === null ? identity : `${identity}${APP_INTERCEPTION_SEPARATOR}${interceptionContext}`;
-}
-function createAppPayloadRouteId(routePath, interceptionContext) {
-	return appendInterceptionContext(`route:${routePath}`, interceptionContext);
-}
-function createAppPayloadPageId(routePath, interceptionContext) {
-	return appendInterceptionContext(`page:${routePath}`, interceptionContext);
-}
-function createAppPayloadCacheKey(rscUrl, interceptionContext) {
-	return appendInterceptionContext(rscUrl, interceptionContext);
-}
 function resolveVisitedResponseInterceptionContext(requestInterceptionContext, payloadInterceptionContext) {
 	return payloadInterceptionContext ?? requestInterceptionContext;
 }
-function normalizeAppElements(elements) {
-	let needsNormalization = false;
-	for (const [key, value] of Object.entries(elements)) if (key.startsWith("slot:") && value === "__VINEXT_UNMATCHED_SLOT__") {
-		needsNormalization = true;
-		break;
-	}
-	if (!needsNormalization) return elements;
-	const normalized = {};
-	for (const [key, value] of Object.entries(elements)) normalized[key] = key.startsWith("slot:") && value === "__VINEXT_UNMATCHED_SLOT__" ? UNMATCHED_SLOT : value;
-	return normalized;
-}
-function isLayoutFlagsRecord(value) {
-	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
-	for (const v of Object.values(value)) if (v !== "s" && v !== "d") return false;
-	return true;
-}
-function parseLayoutFlags(value) {
-	if (isLayoutFlagsRecord(value)) return value;
-	return {};
-}
-/**
-* Type predicate for a plain (non-null, non-array) record of app payload values.
-* Used to distinguish the App Router payload object from bare React elements at
-* the render boundary. Narrows to `Readonly<Record<string, unknown>>` because
-* the outgoing payload carries heterogeneous values (ReactNodes for the rendered
-* tree, plus metadata like `__layoutFlags` which is a plain object). Delegates
-* to React's canonical `isValidElement` so we don't depend on React's internal
-* `$$typeof` marker scheme.
-*/
-function isAppElementsRecord(value) {
-	if (typeof value !== "object" || value === null) return false;
-	if (Array.isArray(value)) return false;
-	if (isValidElement(value)) return false;
-	return true;
-}
-/**
-* Pure: returns a new record with `__layoutFlags` attached. Owns the write
-* boundary for the layout flags key so the write side sits next to
-* `readAppElementsMetadata`.
-*
-* See `LayoutFlags` type docblock in this file for lifecycle.
-*/
-function withLayoutFlags(elements, layoutFlags) {
-	return {
-		...elements,
-		[APP_LAYOUT_FLAGS_KEY]: layoutFlags
-	};
-}
-/**
-* Pure: builds the outgoing payload for the wire. Non-record inputs (e.g. a
-* bare React element) are returned unchanged. Record inputs get a fresh copy
-* with `__layoutFlags` attached. Never mutates `input.element`.
-*/
-function buildOutgoingAppPayload(input) {
-	if (!isAppElementsRecord(input.element)) return input.element;
-	return withLayoutFlags(input.element, input.layoutFlags);
-}
-/**
-* Parses metadata from the wire payload. Accepts `Record<string, unknown>`
-* because the RSC payload carries heterogeneous values (React elements,
-* strings, and plain objects like layout flags) under the same record type.
-*
-* See `LayoutFlags` type docblock in this file for lifecycle.
-*/
-function readAppElementsMetadata(elements) {
-	const routeId = elements[APP_ROUTE_KEY];
-	if (typeof routeId !== "string") throw new Error("[vinext] Missing __route string in App Router payload");
-	const interceptionContext = elements[APP_INTERCEPTION_CONTEXT_KEY];
-	if (interceptionContext !== void 0 && interceptionContext !== null && typeof interceptionContext !== "string") throw new Error("[vinext] Invalid __interceptionContext in App Router payload");
-	const rootLayoutTreePath = elements[APP_ROOT_LAYOUT_KEY];
-	if (rootLayoutTreePath === void 0) throw new Error("[vinext] Missing __rootLayout key in App Router payload");
-	if (rootLayoutTreePath !== null && typeof rootLayoutTreePath !== "string") throw new Error("[vinext] Invalid __rootLayout in App Router payload: expected string or null");
-	const layoutFlags = parseLayoutFlags(elements[APP_LAYOUT_FLAGS_KEY]);
-	return {
-		interceptionContext: interceptionContext ?? null,
-		layoutFlags,
-		routeId,
-		rootLayoutTreePath
-	};
-}
 //#endregion
-export { APP_INTERCEPTION_CONTEXT_KEY, APP_LAYOUT_FLAGS_KEY, APP_ROOT_LAYOUT_KEY, APP_ROUTE_KEY, APP_UNMATCHED_SLOT_WIRE_VALUE, UNMATCHED_SLOT, buildOutgoingAppPayload, createAppPayloadCacheKey, createAppPayloadPageId, createAppPayloadRouteId, getMountedSlotIds, getMountedSlotIdsHeader, isAppElementsRecord, normalizeAppElements, readAppElementsMetadata, resolveVisitedResponseInterceptionContext, withLayoutFlags };
+export { APP_ARTIFACT_COMPATIBILITY_KEY, APP_INTERCEPTION_CONTEXT_KEY, APP_LAYOUT_FLAGS_KEY, APP_ROOT_LAYOUT_KEY, APP_ROUTE_KEY, APP_UNMATCHED_SLOT_WIRE_VALUE, AppElementsWire, UNMATCHED_SLOT, buildOutgoingAppPayload, getMountedSlotIds, getMountedSlotIdsHeader, isAppElementsRecord, normalizeAppElements, readAppElementsMetadata, resolveVisitedResponseInterceptionContext, withLayoutFlags };
 
 //# sourceMappingURL=app-elements.js.map

package/dist/server/app-elements.js.map

@@ -1 +1 @@
-{"version":3,"file":"app-elements.js","names":[],"sources":["../../src/server/app-elements.ts"],"sourcesContent":["import { isValidElement, type ReactNode } from \"react\";\nimport { normalizeMountedSlotsHeader } from \"./app-mounted-slots-header.js\";\n\nconst APP_INTERCEPTION_SEPARATOR = \"\\0\";\n\nexport const APP_INTERCEPTION_CONTEXT_KEY = \"__interceptionContext\";\nexport const APP_LAYOUT_FLAGS_KEY = \"__layoutFlags\";\nexport const APP_ROUTE_KEY = \"__route\";\nexport const APP_ROOT_LAYOUT_KEY = \"__rootLayout\";\nexport const APP_UNMATCHED_SLOT_WIRE_VALUE = \"__VINEXT_UNMATCHED_SLOT__\";\n\nexport const UNMATCHED_SLOT = Symbol.for(\"vinext.unmatchedSlot\");\n\nexport type AppElementValue = ReactNode | typeof UNMATCHED_SLOT | string | null;\ntype AppWireElementValue = ReactNode | string | null;\n\nexport type AppElements = Readonly<Record<string, AppElementValue>>;\nexport type AppWireElements = Readonly<Record<string, AppWireElementValue>>;\n\n/**\n * Per-layout static/dynamic flags. `\"s\"` = static (skippable on next nav);\n * `\"d\"` = dynamic (must always render).\n *\n * Lifecycle (partial — later PRs extend this):\n *\n *   1. PROBE   — probeAppPageLayouts (server/app-page-execution.ts) returns\n *                LayoutFlags for every layout in the route at render time.\n *\n *   2. ATTACH  — withLayoutFlags (this file) writes `__layoutFlags` into the\n *                outgoing App Router payload record.\n *\n *   3. WIRE    — renderToReadableStream serializes the record as RSC row 0.\n *\n *   4. PARSE   — readAppElementsMetadata (this file) extracts layoutFlags from\n *                the wire payload on the client side.\n */\nexport type LayoutFlags = Readonly<Record<string, \"s\" | \"d\">>;\n\ntype AppElementsMetadata = {\n  interceptionContext: string | null;\n  layoutFlags: LayoutFlags;\n  routeId: string;\n  rootLayoutTreePath: string | null;\n};\n\nexport function getMountedSlotIds(elements: AppElements): string[] {\n  return Object.keys(elements)\n    .filter((key) => {\n      const value = elements[key];\n      return (\n        key.startsWith(\"slot:\") && value !== null && value !== undefined && value !== UNMATCHED_SLOT\n      );\n    })\n    .sort();\n}\n\nexport function getMountedSlotIdsHeader(elements: AppElements): string | null {\n  return normalizeMountedSlotsHeader(getMountedSlotIds(elements).join(\" \"));\n}\n\nfunction appendInterceptionContext(identity: string, interceptionContext: string | null): string {\n  return interceptionContext === null\n    ? identity\n    : `${identity}${APP_INTERCEPTION_SEPARATOR}${interceptionContext}`;\n}\n\nexport function createAppPayloadRouteId(\n  routePath: string,\n  interceptionContext: string | null,\n): string {\n  return appendInterceptionContext(`route:${routePath}`, interceptionContext);\n}\n\nexport function createAppPayloadPageId(\n  routePath: string,\n  interceptionContext: string | null,\n): string {\n  return appendInterceptionContext(`page:${routePath}`, interceptionContext);\n}\n\nexport function createAppPayloadCacheKey(\n  rscUrl: string,\n  interceptionContext: string | null,\n): string {\n  return appendInterceptionContext(rscUrl, interceptionContext);\n}\n\nexport function resolveVisitedResponseInterceptionContext(\n  requestInterceptionContext: string | null,\n  payloadInterceptionContext: string | null,\n): string | null {\n  return payloadInterceptionContext ?? requestInterceptionContext;\n}\n\nexport function normalizeAppElements(elements: AppWireElements): AppElements {\n  let needsNormalization = false;\n  for (const [key, value] of Object.entries(elements)) {\n    if (key.startsWith(\"slot:\") && value === APP_UNMATCHED_SLOT_WIRE_VALUE) {\n      needsNormalization = true;\n      break;\n    }\n  }\n\n  if (!needsNormalization) {\n    return elements;\n  }\n\n  const normalized: Record<string, AppElementValue> = {};\n  for (const [key, value] of Object.entries(elements)) {\n    normalized[key] =\n      key.startsWith(\"slot:\") && value === APP_UNMATCHED_SLOT_WIRE_VALUE ? UNMATCHED_SLOT : value;\n  }\n\n  return normalized;\n}\n\nfunction isLayoutFlagsRecord(value: unknown): value is LayoutFlags {\n  if (!value || typeof value !== \"object\" || Array.isArray(value)) return false;\n  for (const v of Object.values(value)) {\n    if (v !== \"s\" && v !== \"d\") return false;\n  }\n  return true;\n}\n\nfunction parseLayoutFlags(value: unknown): LayoutFlags {\n  if (isLayoutFlagsRecord(value)) return value;\n  return {};\n}\n\n/**\n * Type predicate for a plain (non-null, non-array) record of app payload values.\n * Used to distinguish the App Router payload object from bare React elements at\n * the render boundary. Narrows to `Readonly<Record<string, unknown>>` because\n * the outgoing payload carries heterogeneous values (ReactNodes for the rendered\n * tree, plus metadata like `__layoutFlags` which is a plain object). Delegates\n * to React's canonical `isValidElement` so we don't depend on React's internal\n * `$$typeof` marker scheme.\n */\nexport function isAppElementsRecord(value: unknown): value is Readonly<Record<string, unknown>> {\n  if (typeof value !== \"object\" || value === null) return false;\n  if (Array.isArray(value)) return false;\n  if (isValidElement(value)) return false;\n  return true;\n}\n\n/**\n * Pure: returns a new record with `__layoutFlags` attached. Owns the write\n * boundary for the layout flags key so the write side sits next to\n * `readAppElementsMetadata`.\n *\n * See `LayoutFlags` type docblock in this file for lifecycle.\n */\nexport function withLayoutFlags<T extends Record<string, unknown>>(\n  elements: T,\n  layoutFlags: LayoutFlags,\n): T & { [APP_LAYOUT_FLAGS_KEY]: LayoutFlags } {\n  return { ...elements, [APP_LAYOUT_FLAGS_KEY]: layoutFlags };\n}\n\n/**\n * The outgoing wire payload shape. Includes ReactNode values for the\n * rendered tree plus metadata values like LayoutFlags attached under\n * known keys (e.g. __layoutFlags). Distinct from AppElements / AppWireElements\n * which only carry render-time values.\n */\nexport type AppOutgoingElements = Readonly<Record<string, ReactNode | LayoutFlags>>;\n\n/**\n * Pure: builds the outgoing payload for the wire. Non-record inputs (e.g. a\n * bare React element) are returned unchanged. Record inputs get a fresh copy\n * with `__layoutFlags` attached. Never mutates `input.element`.\n */\nexport function buildOutgoingAppPayload(input: {\n  element: ReactNode | Readonly<Record<string, ReactNode>>;\n  layoutFlags: LayoutFlags;\n}): ReactNode | AppOutgoingElements {\n  if (!isAppElementsRecord(input.element)) {\n    return input.element;\n  }\n  return withLayoutFlags(input.element, input.layoutFlags);\n}\n\n/**\n * Parses metadata from the wire payload. Accepts `Record<string, unknown>`\n * because the RSC payload carries heterogeneous values (React elements,\n * strings, and plain objects like layout flags) under the same record type.\n *\n * See `LayoutFlags` type docblock in this file for lifecycle.\n */\nexport function readAppElementsMetadata(\n  elements: Readonly<Record<string, unknown>>,\n): AppElementsMetadata {\n  const routeId = elements[APP_ROUTE_KEY];\n  if (typeof routeId !== \"string\") {\n    throw new Error(\"[vinext] Missing __route string in App Router payload\");\n  }\n\n  const interceptionContext = elements[APP_INTERCEPTION_CONTEXT_KEY];\n  if (\n    interceptionContext !== undefined &&\n    interceptionContext !== null &&\n    typeof interceptionContext !== \"string\"\n  ) {\n    throw new Error(\"[vinext] Invalid __interceptionContext in App Router payload\");\n  }\n\n  const rootLayoutTreePath = elements[APP_ROOT_LAYOUT_KEY];\n  if (rootLayoutTreePath === undefined) {\n    throw new Error(\"[vinext] Missing __rootLayout key in App Router payload\");\n  }\n  if (rootLayoutTreePath !== null && typeof rootLayoutTreePath !== \"string\") {\n    throw new Error(\"[vinext] Invalid __rootLayout in App Router payload: expected string or null\");\n  }\n\n  const layoutFlags = parseLayoutFlags(elements[APP_LAYOUT_FLAGS_KEY]);\n\n  return {\n    interceptionContext: interceptionContext ?? null,\n    layoutFlags,\n    routeId,\n    rootLayoutTreePath,\n  };\n}\n"],"mappings":";;;AAGA,MAAM,6BAA6B;AAEnC,MAAa,+BAA+B;AAC5C,MAAa,uBAAuB;AACpC,MAAa,gBAAgB;AAC7B,MAAa,sBAAsB;AACnC,MAAa,gCAAgC;AAE7C,MAAa,iBAAiB,OAAO,IAAI,uBAAuB;AAkChE,SAAgB,kBAAkB,UAAiC;AACjE,QAAO,OAAO,KAAK,SAAS,CACzB,QAAQ,QAAQ;EACf,MAAM,QAAQ,SAAS;AACvB,SACE,IAAI,WAAW,QAAQ,IAAI,UAAU,QAAQ,UAAU,KAAA,KAAa,UAAU;GAEhF,CACD,MAAM;;AAGX,SAAgB,wBAAwB,UAAsC;AAC5E,QAAO,4BAA4B,kBAAkB,SAAS,CAAC,KAAK,IAAI,CAAC;;AAG3E,SAAS,0BAA0B,UAAkB,qBAA4C;AAC/F,QAAO,wBAAwB,OAC3B,WACA,GAAG,WAAW,6BAA6B;;AAGjD,SAAgB,wBACd,WACA,qBACQ;AACR,QAAO,0BAA0B,SAAS,aAAa,oBAAoB;;AAG7E,SAAgB,uBACd,WACA,qBACQ;AACR,QAAO,0BAA0B,QAAQ,aAAa,oBAAoB;;AAG5E,SAAgB,yBACd,QACA,qBACQ;AACR,QAAO,0BAA0B,QAAQ,oBAAoB;;AAG/D,SAAgB,0CACd,4BACA,4BACe;AACf,QAAO,8BAA8B;;AAGvC,SAAgB,qBAAqB,UAAwC;CAC3E,IAAI,qBAAqB;AACzB,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,SAAS,CACjD,KAAI,IAAI,WAAW,QAAQ,IAAI,UAAA,6BAAyC;AACtE,uBAAqB;AACrB;;AAIJ,KAAI,CAAC,mBACH,QAAO;CAGT,MAAM,aAA8C,EAAE;AACtD,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,SAAS,CACjD,YAAW,OACT,IAAI,WAAW,QAAQ,IAAI,UAAA,8BAA0C,iBAAiB;AAG1F,QAAO;;AAGT,SAAS,oBAAoB,OAAsC;AACjE,KAAI,CAAC,SAAS,OAAO,UAAU,YAAY,MAAM,QAAQ,MAAM,CAAE,QAAO;AACxE,MAAK,MAAM,KAAK,OAAO,OAAO,MAAM,CAClC,KAAI,MAAM,OAAO,MAAM,IAAK,QAAO;AAErC,QAAO;;AAGT,SAAS,iBAAiB,OAA6B;AACrD,KAAI,oBAAoB,MAAM,CAAE,QAAO;AACvC,QAAO,EAAE;;;;;;;;;;;AAYX,SAAgB,oBAAoB,OAA4D;AAC9F,KAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;AACxD,KAAI,MAAM,QAAQ,MAAM,CAAE,QAAO;AACjC,KAAI,eAAe,MAAM,CAAE,QAAO;AAClC,QAAO;;;;;;;;;AAUT,SAAgB,gBACd,UACA,aAC6C;AAC7C,QAAO;EAAE,GAAG;GAAW,uBAAuB;EAAa;;;;;;;AAgB7D,SAAgB,wBAAwB,OAGJ;AAClC,KAAI,CAAC,oBAAoB,MAAM,QAAQ,CACrC,QAAO,MAAM;AAEf,QAAO,gBAAgB,MAAM,SAAS,MAAM,YAAY;;;;;;;;;AAU1D,SAAgB,wBACd,UACqB;CACrB,MAAM,UAAU,SAAS;AACzB,KAAI,OAAO,YAAY,SACrB,OAAM,IAAI,MAAM,wDAAwD;CAG1E,MAAM,sBAAsB,SAAS;AACrC,KACE,wBAAwB,KAAA,KACxB,wBAAwB,QACxB,OAAO,wBAAwB,SAE/B,OAAM,IAAI,MAAM,+DAA+D;CAGjF,MAAM,qBAAqB,SAAS;AACpC,KAAI,uBAAuB,KAAA,EACzB,OAAM,IAAI,MAAM,0DAA0D;AAE5E,KAAI,uBAAuB,QAAQ,OAAO,uBAAuB,SAC/D,OAAM,IAAI,MAAM,+EAA+E;CAGjG,MAAM,cAAc,iBAAiB,SAAS,sBAAsB;AAEpE,QAAO;EACL,qBAAqB,uBAAuB;EAC5C;EACA;EACA;EACD"}
+{"version":3,"file":"app-elements.js","names":[],"sources":["../../src/server/app-elements.ts"],"sourcesContent":["import { normalizeMountedSlotsHeader } from \"./app-mounted-slots-header.js\";\nimport { AppElementsWire, UNMATCHED_SLOT, type AppElements } from \"./app-elements-wire.js\";\n\nexport {\n  AppElementsWire,\n  APP_ARTIFACT_COMPATIBILITY_KEY,\n  APP_INTERCEPTION_CONTEXT_KEY,\n  APP_LAYOUT_FLAGS_KEY,\n  APP_ROOT_LAYOUT_KEY,\n  APP_ROUTE_KEY,\n  APP_UNMATCHED_SLOT_WIRE_VALUE,\n  UNMATCHED_SLOT,\n  buildOutgoingAppPayload,\n  isAppElementsRecord,\n  normalizeAppElements,\n  readAppElementsMetadata,\n  withLayoutFlags,\n  type AppElementValue,\n  type AppElements,\n  type AppOutgoingElements,\n  type AppWireElements,\n  type LayoutFlags,\n} from \"./app-elements-wire.js\";\n\n// Raw constructor helpers stay private because callers use AppElementsWire codecs.\n\nexport function getMountedSlotIds(elements: AppElements): string[] {\n  return Object.keys(elements)\n    .filter((key) => {\n      const value = elements[key];\n      return (\n        AppElementsWire.isSlotId(key) &&\n        value !== null &&\n        value !== undefined &&\n        value !== UNMATCHED_SLOT\n      );\n    })\n    .sort();\n}\n\nexport function getMountedSlotIdsHeader(elements: AppElements): string | null {\n  return normalizeMountedSlotsHeader(getMountedSlotIds(elements).join(\" \"));\n}\n\nexport function resolveVisitedResponseInterceptionContext(\n  requestInterceptionContext: string | null,\n  payloadInterceptionContext: string | null,\n): string | null {\n  return payloadInterceptionContext ?? requestInterceptionContext;\n}\n"],"mappings":";;;AA0BA,SAAgB,kBAAkB,UAAiC;AACjE,QAAO,OAAO,KAAK,SAAS,CACzB,QAAQ,QAAQ;EACf,MAAM,QAAQ,SAAS;AACvB,SACE,gBAAgB,SAAS,IAAI,IAC7B,UAAU,QACV,UAAU,KAAA,KACV,UAAU;GAEZ,CACD,MAAM;;AAGX,SAAgB,wBAAwB,UAAsC;AAC5E,QAAO,4BAA4B,kBAAkB,SAAS,CAAC,KAAK,IAAI,CAAC;;AAG3E,SAAgB,0CACd,4BACA,4BACe;AACf,QAAO,8BAA8B"}

package/dist/server/app-fallback-renderer.d.ts

@@ -1,5 +1,5 @@
 import { MetadataFileRoute } from "./metadata-routes.js";
-import { AppElements } from "./app-elements.js";
+import { AppElements } from "./app-elements-wire.js";
 import { AppPageParams } from "./app-page-boundary.js";
 import { AppPageFontPreload } from "./app-page-execution.js";
 import { AppPageMiddlewareContext } from "./app-page-response.js";

package/dist/server/app-middleware.d.ts

@@ -24,9 +24,10 @@ type ApplyAppMiddlewareResult = {
   kind: "response";
   response: Response;
 };
+declare const FLIGHT_HEADERS: readonly string[];
 declare function isExternalMiddlewareRewrite(rewriteUrl: string, request: Request): boolean;
 declare function proxyExternalMiddlewareRewrite(request: Request, rewriteUrl: string, context: AppMiddlewareContext): Promise<Response>;
 declare function applyAppMiddleware(options: ApplyAppMiddlewareOptions): Promise<ApplyAppMiddlewareResult>;
 //#endregion
-export { AppMiddlewareContext, ApplyAppMiddlewareOptions, ApplyAppMiddlewareResult, applyAppMiddleware, isExternalMiddlewareRewrite, proxyExternalMiddlewareRewrite };
+export { AppMiddlewareContext, ApplyAppMiddlewareOptions, ApplyAppMiddlewareResult, FLIGHT_HEADERS, applyAppMiddleware, isExternalMiddlewareRewrite, proxyExternalMiddlewareRewrite };
 //# sourceMappingURL=app-middleware.d.ts.map

package/dist/server/app-middleware.js

@@ -1,14 +1,31 @@
 import { buildRequestHeadersFromMiddlewareResponse } from "./middleware-request-headers.js";
 import { isExternalUrl, proxyExternalRequest } from "../config/config-matchers.js";
-import { processMiddlewareHeaders } from "./request-pipeline.js";
+import { internalServerErrorResponse } from "./http-error-responses.js";
+import { cloneRequestWithHeaders, processMiddlewareHeaders } from "./request-pipeline.js";
 import { executeMiddleware } from "./middleware-runtime.js";
 import { applyMiddlewareRequestHeaders, setHeadersContext } from "../shims/headers.js";
 import { setNavigationContext } from "../shims/navigation.js";
 import { mergeMiddlewareResponseHeaders } from "./middleware-response-headers.js";
 //#region src/server/app-middleware.ts
+const FLIGHT_HEADERS = [
+	"rsc",
+	"next-router-state-tree",
+	"next-router-prefetch",
+	"next-hmr-refresh",
+	"next-router-segment-prefetch"
+];
+const FLIGHT_HEADER_SET = new Set(FLIGHT_HEADERS);
 function isForwardedMiddlewareContext(value) {
 	return !!value && typeof value === "object";
 }
+function requestWithoutFlightHeaders(request) {
+	let hasFlightHeader = false;
+	const headers = new Headers();
+	for (const [key, value] of request.headers) if (FLIGHT_HEADER_SET.has(key.toLowerCase())) hasFlightHeader = true;
+	else headers.append(key, value);
+	if (!hasFlightHeader) return request;
+	return cloneRequestWithHeaders(request.body ? request.clone() : request, headers);
+}
 function appendForwardedHeader(headers, value) {
 	if (!Array.isArray(value) || value.length < 2) return;
 	const key = value[0];
@@ -46,10 +63,15 @@ async function proxyExternalMiddlewareRewrite(request, rewriteUrl, context) {
 	setHeadersContext(null);
 	setNavigationContext(null);
 	const proxyResponse = await proxyExternalRequest(proxyRequest, rewriteUrl);
-	if (!context.headers) return proxyResponse;
+	const headers = new Headers(proxyResponse.headers);
+	processMiddlewareHeaders(headers);
+	if (!context.headers) return new Response(proxyResponse.body, {
+		status: proxyResponse.status,
+		statusText: proxyResponse.statusText,
+		headers
+	});
 	const middlewareHeaders = new Headers(context.headers);
 	processMiddlewareHeaders(middlewareHeaders);
-	const headers = new Headers(proxyResponse.headers);
 	mergeMiddlewareResponseHeaders(headers, middlewareHeaders);
 	return new Response(proxyResponse.body, {
 		status: proxyResponse.status,
@@ -81,14 +103,15 @@ function applyForwardedMiddlewareContext(request, context) {
 }
 async function applyAppMiddleware(options) {
 	const forwarded = applyForwardedMiddlewareContext(options.request, options.context);
+	const middlewareRequest = requestWithoutFlightHeaders(options.request);
 	let cleanPathname = options.cleanPathname;
 	let search = null;
 	if (forwarded.rewriteUrl) try {
-		if (isExternalMiddlewareRewrite(forwarded.rewriteUrl, options.request)) return {
+		if (isExternalMiddlewareRewrite(forwarded.rewriteUrl, middlewareRequest)) return {
 			kind: "response",
-			response: await proxyExternalMiddlewareRewrite(options.request, forwarded.rewriteUrl, options.context)
+			response: await proxyExternalMiddlewareRewrite(middlewareRequest, forwarded.rewriteUrl, options.context)
 		};
-		const rewriteParsed = new URL(forwarded.rewriteUrl, options.request.url);
+		const rewriteParsed = new URL(forwarded.rewriteUrl, middlewareRequest.url);
 		cleanPathname = rewriteParsed.pathname;
 		search = rewriteParsed.search;
 	} catch (e) {
@@ -102,7 +125,7 @@ async function applyAppMiddleware(options) {
 			isProxy: options.isProxy,
 			module: options.module,
 			normalizedPathname: cleanPathname,
-			request: options.request
+			request: middlewareRequest
 		});
 		if (!result.continue) {
 			if (result.redirectUrl) return {
@@ -115,7 +138,7 @@ async function applyAppMiddleware(options) {
 			};
 			return {
 				kind: "response",
-				response: new Response("Internal Server Error", { status: 500 })
+				response: internalServerErrorResponse()
 			};
 		}
 		if (result.responseHeaders) options.context.headers = new Headers(result.responseHeaders);
@@ -123,9 +146,9 @@ async function applyAppMiddleware(options) {
 			if (result.rewriteStatus !== void 0) options.context.status = result.rewriteStatus;
 			if (isExternalUrl(result.rewriteUrl)) return {
 				kind: "response",
-				response: await proxyExternalMiddlewareRewrite(options.request, result.rewriteUrl, options.context)
+				response: await proxyExternalMiddlewareRewrite(middlewareRequest, result.rewriteUrl, options.context)
 			};
-			const rewriteParsed = new URL(result.rewriteUrl, options.request.url);
+			const rewriteParsed = new URL(result.rewriteUrl, middlewareRequest.url);
 			cleanPathname = rewriteParsed.pathname;
 			search = rewriteParsed.search;
 		}
@@ -142,6 +165,6 @@ async function applyAppMiddleware(options) {
 	};
 }
 //#endregion
-export { applyAppMiddleware, isExternalMiddlewareRewrite, proxyExternalMiddlewareRewrite };
+export { FLIGHT_HEADERS, applyAppMiddleware, isExternalMiddlewareRewrite, proxyExternalMiddlewareRewrite };
 
 //# sourceMappingURL=app-middleware.js.map