vinext 0.0.47 → 0.0.49

package/dist/server/app-browser-state.js.map

@@ -1 +1 @@
-{"version":3,"file":"app-browser-state.js","names":[],"sources":["../../src/server/app-browser-state.ts"],"sourcesContent":["import { mergeElements } from \"vinext/shims/slot\";\nimport { stripBasePath } from \"../utils/base-path.js\";\nimport {\n  getMountedSlotIdsHeader,\n  readAppElementsMetadata,\n  type AppElements,\n  type LayoutFlags,\n} from \"./app-elements.js\";\nimport type { ClientNavigationRenderSnapshot } from \"vinext/shims/navigation\";\n\nconst VINEXT_PREVIOUS_NEXT_URL_HISTORY_STATE_KEY = \"__vinext_previousNextUrl\";\n\ntype HistoryStateRecord = {\n  [key: string]: unknown;\n};\n\nexport type AppRouterState = {\n  elements: AppElements;\n  interceptionContext: string | null;\n  layoutFlags: LayoutFlags;\n  previousNextUrl: string | null;\n  renderId: number;\n  navigationSnapshot: ClientNavigationRenderSnapshot;\n  rootLayoutTreePath: string | null;\n  routeId: string;\n};\n\nexport type AppRouterAction = {\n  elements: AppElements;\n  interceptionContext: string | null;\n  layoutFlags: LayoutFlags;\n  navigationSnapshot: ClientNavigationRenderSnapshot;\n  previousNextUrl: string | null;\n  renderId: number;\n  rootLayoutTreePath: string | null;\n  routeId: string;\n  type: \"navigate\" | \"replace\" | \"traverse\";\n};\n\ntype PendingNavigationCommit = {\n  action: AppRouterAction;\n  interceptionContext: string | null;\n  previousNextUrl: string | null;\n  rootLayoutTreePath: string | null;\n  routeId: string;\n};\n\ntype PendingNavigationCommitDisposition = \"dispatch\" | \"hard-navigate\" | \"skip\";\ntype ClassifiedPendingNavigationCommit = {\n  disposition: PendingNavigationCommitDisposition;\n  pending: PendingNavigationCommit;\n};\n\nfunction cloneHistoryState(state: unknown): HistoryStateRecord {\n  if (!state || typeof state !== \"object\") {\n    return {};\n  }\n\n  const nextState: HistoryStateRecord = {};\n  for (const [key, value] of Object.entries(state)) {\n    nextState[key] = value;\n  }\n  return nextState;\n}\n\nexport function createHistoryStateWithPreviousNextUrl(\n  state: unknown,\n  previousNextUrl: string | null,\n): HistoryStateRecord | null {\n  const nextState = cloneHistoryState(state);\n\n  if (previousNextUrl === null) {\n    delete nextState[VINEXT_PREVIOUS_NEXT_URL_HISTORY_STATE_KEY];\n  } else {\n    nextState[VINEXT_PREVIOUS_NEXT_URL_HISTORY_STATE_KEY] = previousNextUrl;\n  }\n\n  return Object.keys(nextState).length > 0 ? nextState : null;\n}\n\nexport function readHistoryStatePreviousNextUrl(state: unknown): string | null {\n  const value = cloneHistoryState(state)[VINEXT_PREVIOUS_NEXT_URL_HISTORY_STATE_KEY];\n  return typeof value === \"string\" ? value : null;\n}\n\nexport function resolveInterceptionContextFromPreviousNextUrl(\n  previousNextUrl: string | null,\n  basePath: string = \"\",\n): string | null {\n  if (previousNextUrl === null) {\n    return null;\n  }\n\n  const parsedUrl = new URL(previousNextUrl, \"http://localhost\");\n  return stripBasePath(parsedUrl.pathname, basePath);\n}\n\ntype ResolveServerActionRequestStateOptions = {\n  actionId: string;\n  basePath: string;\n  elements: AppElements;\n  previousNextUrl: string | null;\n};\n\ntype ResolveServerActionRequestStateResult = {\n  headers: Headers;\n};\n\n/**\n * Pure: builds the fetch Headers for a server-action POST. Carries the same\n * interception-context and mounted-slots headers the refresh path already\n * sends, so the server-action re-render can rebuild the intercepted tree\n * instead of replacing it with the direct route.\n *\n * Next.js sends `Next-URL: state.previousNextUrl || state.nextUrl` on action\n * POSTs when `hasInterceptionRouteInCurrentTree(state.tree)`. Vinext's\n * X-Vinext-Interception-Context is the equivalent signal for the server-side\n * `findIntercept` lookup.\n */\nexport function resolveServerActionRequestState(\n  options: ResolveServerActionRequestStateOptions,\n): ResolveServerActionRequestStateResult {\n  const headers = new Headers({\n    Accept: \"text/x-component\",\n    \"x-rsc-action\": options.actionId,\n  });\n\n  const interceptionContext = resolveInterceptionContextFromPreviousNextUrl(\n    options.previousNextUrl,\n    options.basePath,\n  );\n  if (interceptionContext !== null) {\n    headers.set(\"X-Vinext-Interception-Context\", interceptionContext);\n  }\n\n  const mountedSlotsHeader = getMountedSlotIdsHeader(options.elements);\n  if (mountedSlotsHeader !== null) {\n    headers.set(\"X-Vinext-Mounted-Slots\", mountedSlotsHeader);\n  }\n\n  return { headers };\n}\n\nexport function routerReducer(state: AppRouterState, action: AppRouterAction): AppRouterState {\n  switch (action.type) {\n    case \"traverse\":\n    case \"navigate\":\n      return {\n        elements: mergeElements(state.elements, action.elements, action.type === \"traverse\"),\n        interceptionContext: action.interceptionContext,\n        layoutFlags: { ...state.layoutFlags, ...action.layoutFlags },\n        navigationSnapshot: action.navigationSnapshot,\n        previousNextUrl: action.previousNextUrl,\n        renderId: action.renderId,\n        rootLayoutTreePath: action.rootLayoutTreePath,\n        routeId: action.routeId,\n      };\n    case \"replace\":\n      return {\n        elements: action.elements,\n        interceptionContext: action.interceptionContext,\n        layoutFlags: action.layoutFlags,\n        navigationSnapshot: action.navigationSnapshot,\n        previousNextUrl: action.previousNextUrl,\n        renderId: action.renderId,\n        rootLayoutTreePath: action.rootLayoutTreePath,\n        routeId: action.routeId,\n      };\n    default: {\n      const _exhaustive: never = action.type;\n      throw new Error(\"[vinext] Unknown router action: \" + String(_exhaustive));\n    }\n  }\n}\n\nexport function shouldHardNavigate(\n  currentRootLayoutTreePath: string | null,\n  nextRootLayoutTreePath: string | null,\n): boolean {\n  // `null` means the payload could not identify an enclosing root layout\n  // boundary. Treat that as soft-navigation compatible so fallback payloads\n  // do not force a hard reload purely because metadata is absent.\n  return (\n    currentRootLayoutTreePath !== null &&\n    nextRootLayoutTreePath !== null &&\n    currentRootLayoutTreePath !== nextRootLayoutTreePath\n  );\n}\n\nexport function resolvePendingNavigationCommitDisposition(options: {\n  activeNavigationId: number;\n  currentRootLayoutTreePath: string | null;\n  nextRootLayoutTreePath: string | null;\n  startedNavigationId: number;\n}): PendingNavigationCommitDisposition {\n  if (options.startedNavigationId !== options.activeNavigationId) {\n    return \"skip\";\n  }\n\n  if (shouldHardNavigate(options.currentRootLayoutTreePath, options.nextRootLayoutTreePath)) {\n    return \"hard-navigate\";\n  }\n\n  return \"dispatch\";\n}\n\nexport async function createPendingNavigationCommit(options: {\n  currentState: AppRouterState;\n  nextElements: Promise<AppElements>;\n  navigationSnapshot: ClientNavigationRenderSnapshot;\n  previousNextUrl?: string | null;\n  renderId: number;\n  type: \"navigate\" | \"replace\" | \"traverse\";\n}): Promise<PendingNavigationCommit> {\n  const elements = await options.nextElements;\n  const metadata = readAppElementsMetadata(elements);\n  const previousNextUrl =\n    options.previousNextUrl !== undefined\n      ? options.previousNextUrl\n      : options.currentState.previousNextUrl;\n\n  return {\n    action: {\n      elements,\n      interceptionContext: metadata.interceptionContext,\n      layoutFlags: metadata.layoutFlags,\n      navigationSnapshot: options.navigationSnapshot,\n      previousNextUrl,\n      renderId: options.renderId,\n      rootLayoutTreePath: metadata.rootLayoutTreePath,\n      routeId: metadata.routeId,\n      type: options.type,\n    },\n    // Convenience aliases — always equal action.interceptionContext / action.rootLayoutTreePath / action.routeId.\n    interceptionContext: metadata.interceptionContext,\n    previousNextUrl,\n    rootLayoutTreePath: metadata.rootLayoutTreePath,\n    routeId: metadata.routeId,\n  };\n}\n\nexport async function resolveAndClassifyNavigationCommit(options: {\n  activeNavigationId: number;\n  currentState: AppRouterState;\n  navigationSnapshot: ClientNavigationRenderSnapshot;\n  nextElements: Promise<AppElements>;\n  previousNextUrl?: string | null;\n  renderId: number;\n  startedNavigationId: number;\n  type: \"navigate\" | \"replace\" | \"traverse\";\n}): Promise<ClassifiedPendingNavigationCommit> {\n  const pending = await createPendingNavigationCommit({\n    currentState: options.currentState,\n    nextElements: options.nextElements,\n    navigationSnapshot: options.navigationSnapshot,\n    previousNextUrl: options.previousNextUrl,\n    renderId: options.renderId,\n    type: options.type,\n  });\n\n  return {\n    disposition: resolvePendingNavigationCommitDisposition({\n      activeNavigationId: options.activeNavigationId,\n      currentRootLayoutTreePath: options.currentState.rootLayoutTreePath,\n      nextRootLayoutTreePath: pending.rootLayoutTreePath,\n      startedNavigationId: options.startedNavigationId,\n    }),\n    pending,\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"app-browser-state.js","names":[],"sources":["../../src/server/app-browser-state.ts"],"sourcesContent":["import { stripBasePath } from \"../utils/base-path.js\";\nimport {\n  AppElementsWire,\n  getMountedSlotIdsHeader,\n  type AppElements,\n  type LayoutFlags,\n} from \"./app-elements.js\";\nimport { createRscRequestHeaders } from \"./app-rsc-cache-busting.js\";\nimport {\n  NavigationTraceReasonCodes,\n  createNavigationTrace,\n  type NavigationTrace,\n  type NavigationTraceReasonCode,\n} from \"./navigation-trace.js\";\nimport type { ClientNavigationRenderSnapshot } from \"vinext/shims/navigation\";\n\nconst VINEXT_PREVIOUS_NEXT_URL_HISTORY_STATE_KEY = \"__vinext_previousNextUrl\";\n\ntype HistoryStateRecord = {\n  [key: string]: unknown;\n};\n\nexport type OperationLane = \"navigation\" | \"refresh\" | \"traverse\" | \"server-action\" | \"hmr\";\n\ntype OperationRecordBase = {\n  id: number;\n  lane: OperationLane;\n  startedVisibleCommitVersion: number;\n};\n\nexport type PendingOperationRecord = OperationRecordBase & {\n  state: \"pending\";\n};\n\nexport type CommittedOperationRecord = OperationRecordBase & {\n  state: \"committed\";\n  visibleCommitVersion: number;\n};\n\nexport type OperationRecord = PendingOperationRecord | CommittedOperationRecord;\n\nexport type AppRouterState = {\n  activeOperation: OperationRecord | null;\n  elements: AppElements;\n  interceptionContext: string | null;\n  layoutFlags: LayoutFlags;\n  previousNextUrl: string | null;\n  renderId: number;\n  navigationSnapshot: ClientNavigationRenderSnapshot;\n  rootLayoutTreePath: string | null;\n  routeId: string;\n  visibleCommitVersion: number;\n};\n\nexport type AppRouterAction = {\n  elements: AppElements;\n  interceptionContext: string | null;\n  layoutFlags: LayoutFlags;\n  navigationSnapshot: ClientNavigationRenderSnapshot;\n  operation: PendingOperationRecord;\n  previousNextUrl: string | null;\n  renderId: number;\n  rootLayoutTreePath: string | null;\n  routeId: string;\n  type: \"navigate\" | \"replace\" | \"traverse\";\n};\n\nexport type PendingNavigationCommit = {\n  action: AppRouterAction;\n  interceptionContext: string | null;\n  previousNextUrl: string | null;\n  rootLayoutTreePath: string | null;\n  routeId: string;\n};\n\ntype PendingNavigationCommitDisposition = \"dispatch\" | \"hard-navigate\" | \"skip\";\ntype PendingNavigationCommitDispositionDecision = {\n  disposition: PendingNavigationCommitDisposition;\n  trace: NavigationTrace;\n};\n\nfunction cloneHistoryState(state: unknown): HistoryStateRecord {\n  if (!state || typeof state !== \"object\") {\n    return {};\n  }\n\n  const nextState: HistoryStateRecord = {};\n  for (const [key, value] of Object.entries(state)) {\n    nextState[key] = value;\n  }\n  return nextState;\n}\n\nexport function createHistoryStateWithPreviousNextUrl(\n  state: unknown,\n  previousNextUrl: string | null,\n): HistoryStateRecord | null {\n  const nextState = cloneHistoryState(state);\n\n  if (previousNextUrl === null) {\n    delete nextState[VINEXT_PREVIOUS_NEXT_URL_HISTORY_STATE_KEY];\n  } else {\n    nextState[VINEXT_PREVIOUS_NEXT_URL_HISTORY_STATE_KEY] = previousNextUrl;\n  }\n\n  return Object.keys(nextState).length > 0 ? nextState : null;\n}\n\nexport function readHistoryStatePreviousNextUrl(state: unknown): string | null {\n  const value = cloneHistoryState(state)[VINEXT_PREVIOUS_NEXT_URL_HISTORY_STATE_KEY];\n  return typeof value === \"string\" ? value : null;\n}\n\nfunction createOperationRecord(options: {\n  id: number;\n  lane: OperationLane;\n  startedVisibleCommitVersion: number;\n}): PendingOperationRecord {\n  return {\n    id: options.id,\n    lane: options.lane,\n    startedVisibleCommitVersion: options.startedVisibleCommitVersion,\n    state: \"pending\",\n  };\n}\n\nexport function resolveInterceptionContextFromPreviousNextUrl(\n  previousNextUrl: string | null,\n  basePath: string = \"\",\n): string | null {\n  if (previousNextUrl === null) {\n    return null;\n  }\n\n  const parsedUrl = new URL(previousNextUrl, \"http://localhost\");\n  return stripBasePath(parsedUrl.pathname, basePath);\n}\n\ntype ResolveServerActionRequestStateOptions = {\n  actionId: string;\n  basePath: string;\n  elements: AppElements;\n  previousNextUrl: string | null;\n};\n\ntype ResolveServerActionRequestStateResult = {\n  headers: Headers;\n};\n\n/**\n * Pure: builds the fetch Headers for a server-action POST. Carries the same\n * interception-context and mounted-slots headers the refresh path already\n * sends, so the server-action re-render can rebuild the intercepted tree\n * instead of replacing it with the direct route.\n *\n * Next.js sends `Next-URL: state.previousNextUrl || state.nextUrl` on action\n * POSTs when `hasInterceptionRouteInCurrentTree(state.tree)`. Vinext's\n * X-Vinext-Interception-Context is the equivalent signal for the server-side\n * `findIntercept` lookup.\n */\nexport function resolveServerActionRequestState(\n  options: ResolveServerActionRequestStateOptions,\n): ResolveServerActionRequestStateResult {\n  const headers = createRscRequestHeaders();\n  headers.set(\"x-rsc-action\", options.actionId);\n\n  const interceptionContext = resolveInterceptionContextFromPreviousNextUrl(\n    options.previousNextUrl,\n    options.basePath,\n  );\n  if (interceptionContext !== null) {\n    headers.set(\"X-Vinext-Interception-Context\", interceptionContext);\n  }\n\n  const mountedSlotsHeader = getMountedSlotIdsHeader(options.elements);\n  if (mountedSlotsHeader !== null) {\n    headers.set(\"X-Vinext-Mounted-Slots\", mountedSlotsHeader);\n  }\n\n  return { headers };\n}\n\nexport function shouldHardNavigate(\n  currentRootLayoutTreePath: string | null,\n  nextRootLayoutTreePath: string | null,\n): boolean {\n  // `null` means the payload could not identify an enclosing root layout\n  // boundary. Treat that as soft-navigation compatible so fallback payloads\n  // do not force a hard reload purely because metadata is absent.\n  return (\n    currentRootLayoutTreePath !== null &&\n    nextRootLayoutTreePath !== null &&\n    currentRootLayoutTreePath !== nextRootLayoutTreePath\n  );\n}\n\nexport function resolvePendingNavigationCommitDisposition(options: {\n  activeNavigationId: number;\n  currentVisibleCommitVersion: number;\n  currentRootLayoutTreePath: string | null;\n  nextRootLayoutTreePath: string | null;\n  startedNavigationId: number;\n  startedVisibleCommitVersion: number;\n}): PendingNavigationCommitDisposition {\n  if (options.startedNavigationId !== options.activeNavigationId) {\n    return \"skip\";\n  }\n\n  if (options.startedVisibleCommitVersion !== options.currentVisibleCommitVersion) {\n    return \"skip\";\n  }\n\n  if (shouldHardNavigate(options.currentRootLayoutTreePath, options.nextRootLayoutTreePath)) {\n    return \"hard-navigate\";\n  }\n\n  return \"dispatch\";\n}\n\nexport function resolvePendingNavigationCommitDispositionDecision(options: {\n  activeNavigationId: number;\n  currentVisibleCommitVersion: number;\n  currentRootLayoutTreePath: string | null;\n  nextRootLayoutTreePath: string | null;\n  startedNavigationId: number;\n  startedVisibleCommitVersion: number;\n}): PendingNavigationCommitDispositionDecision {\n  const disposition = resolvePendingNavigationCommitDisposition(options);\n  const traceFields = {\n    activeNavigationId: options.activeNavigationId,\n    currentRootLayoutTreePath: options.currentRootLayoutTreePath,\n    currentVisibleCommitVersion: options.currentVisibleCommitVersion,\n    nextRootLayoutTreePath: options.nextRootLayoutTreePath,\n    startedNavigationId: options.startedNavigationId,\n    startedVisibleCommitVersion: options.startedVisibleCommitVersion,\n  };\n\n  return {\n    disposition,\n    trace: createNavigationTrace(\n      getPendingNavigationCommitDispositionTraceCode({\n        currentRootLayoutTreePath: options.currentRootLayoutTreePath,\n        disposition,\n        nextRootLayoutTreePath: options.nextRootLayoutTreePath,\n      }),\n      traceFields,\n    ),\n  };\n}\n\nfunction getPendingNavigationCommitDispositionTraceCode(options: {\n  currentRootLayoutTreePath: string | null;\n  disposition: PendingNavigationCommitDisposition;\n  nextRootLayoutTreePath: string | null;\n}): NavigationTraceReasonCode {\n  switch (options.disposition) {\n    case \"skip\":\n      return NavigationTraceReasonCodes.staleOperation;\n    case \"hard-navigate\":\n      return NavigationTraceReasonCodes.rootBoundaryChanged;\n    case \"dispatch\":\n      return options.currentRootLayoutTreePath === null || options.nextRootLayoutTreePath === null\n        ? NavigationTraceReasonCodes.rootBoundaryUnknown\n        : NavigationTraceReasonCodes.commitCurrent;\n    default: {\n      const _exhaustive: never = options.disposition;\n      throw new Error(\"[vinext] Unknown navigation commit disposition: \" + String(_exhaustive));\n    }\n  }\n}\n\nexport async function createPendingNavigationCommit(options: {\n  currentState: AppRouterState;\n  nextElements: Promise<AppElements>;\n  navigationSnapshot: ClientNavigationRenderSnapshot;\n  operationLane: OperationLane;\n  previousNextUrl?: string | null;\n  renderId: number;\n  type: \"navigate\" | \"replace\" | \"traverse\";\n}): Promise<PendingNavigationCommit> {\n  const elements = await options.nextElements;\n  const metadata = AppElementsWire.readMetadata(elements);\n  const previousNextUrl =\n    options.previousNextUrl !== undefined\n      ? options.previousNextUrl\n      : options.currentState.previousNextUrl;\n\n  return {\n    action: {\n      elements,\n      interceptionContext: metadata.interceptionContext,\n      layoutFlags: metadata.layoutFlags,\n      navigationSnapshot: options.navigationSnapshot,\n      operation: createOperationRecord({\n        id: options.renderId,\n        lane: options.operationLane,\n        startedVisibleCommitVersion: options.currentState.visibleCommitVersion,\n      }),\n      previousNextUrl,\n      renderId: options.renderId,\n      rootLayoutTreePath: metadata.rootLayoutTreePath,\n      routeId: metadata.routeId,\n      type: options.type,\n    },\n    // Convenience aliases — always equal action.interceptionContext / action.rootLayoutTreePath / action.routeId.\n    interceptionContext: metadata.interceptionContext,\n    previousNextUrl,\n    rootLayoutTreePath: metadata.rootLayoutTreePath,\n    routeId: metadata.routeId,\n  };\n}\n"],"mappings":"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"}

package/dist/server/app-browser-visible-commit.d.ts

@@ -0,0 +1,68 @@
+import { ClientNavigationRenderSnapshot } from "../shims/navigation.js";
+import { AppElements } from "./app-elements-wire.js";
+import { NavigationTrace } from "./navigation-trace.js";
+import { AppRouterAction, AppRouterState, OperationLane, PendingNavigationCommit } from "./app-browser-state.js";
+
+//#region src/server/app-browser-visible-commit.d.ts
+type VisibleCommitDecision = {
+  disposition: "commit";
+  trace: NavigationTrace;
+};
+type HardNavigateCommitDecision = {
+  disposition: "hard-navigate";
+  trace: NavigationTrace;
+};
+type NoCommitDecision = {
+  disposition: "no-commit";
+  trace: NavigationTrace;
+};
+type CommitDecision = VisibleCommitDecision | HardNavigateCommitDecision | NoCommitDecision;
+declare const approvedVisibleCommitBrand: unique symbol;
+type ApprovedVisibleCommit = {
+  readonly [approvedVisibleCommitBrand]: true;
+  readonly action: AppRouterAction;
+  readonly decision: VisibleCommitDecision;
+  readonly interceptionContext: string | null;
+  readonly previousNextUrl: string | null;
+  readonly rootLayoutTreePath: string | null;
+  readonly routeId: string;
+};
+type VisibleCommitApproval = {
+  approvedCommit: ApprovedVisibleCommit;
+  decision: VisibleCommitDecision;
+};
+type NonVisibleCommitApproval = {
+  approvedCommit: null;
+  decision: HardNavigateCommitDecision | NoCommitDecision;
+};
+type CommitApproval = VisibleCommitApproval | NonVisibleCommitApproval;
+type ClassifiedPendingNavigationCommit = {
+  approvedCommit: ApprovedVisibleCommit | null;
+  decision: CommitDecision;
+  pending: PendingNavigationCommit;
+  trace: NavigationTrace;
+};
+declare function applyApprovedVisibleCommit(state: AppRouterState, commit: ApprovedVisibleCommit): AppRouterState;
+declare function approveHmrVisibleCommit(pending: PendingNavigationCommit): ApprovedVisibleCommit;
+declare function approvePendingNavigationCommit(options: {
+  activeNavigationId: number;
+  currentState: AppRouterState;
+  pending: PendingNavigationCommit;
+  startedNavigationId: number;
+}): CommitApproval;
+declare function resolveAndClassifyNavigationCommit(options: {
+  activeNavigationId: number;
+  currentState: AppRouterState;
+  getActiveNavigationId?: () => number;
+  getCurrentStateForApproval?: () => AppRouterState;
+  navigationSnapshot: ClientNavigationRenderSnapshot;
+  nextElements: Promise<AppElements>;
+  operationLane: OperationLane;
+  previousNextUrl?: string | null;
+  renderId: number;
+  startedNavigationId: number;
+  type: "navigate" | "replace" | "traverse";
+}): Promise<ClassifiedPendingNavigationCommit>;
+//#endregion
+export { ApprovedVisibleCommit, applyApprovedVisibleCommit, approveHmrVisibleCommit, approvePendingNavigationCommit, resolveAndClassifyNavigationCommit };
+//# sourceMappingURL=app-browser-visible-commit.d.ts.map

package/dist/server/app-browser-visible-commit.js

@@ -0,0 +1,182 @@
+import { mergeElements } from "../shims/slot.js";
+import { NavigationTraceReasonCodes, NavigationTraceTransactionCodes, createNavigationTrace, prependNavigationTraceEntry } from "./navigation-trace.js";
+import { createPendingNavigationCommit, resolvePendingNavigationCommitDispositionDecision } from "./app-browser-state.js";
+//#region src/server/app-browser-visible-commit.ts
+const approvedVisibleCommitBrand = Symbol("ApprovedVisibleCommit");
+function applyApprovedVisibleCommit(state, commit) {
+	assertApprovedVisibleCommit(commit);
+	return reduceApprovedVisibleCommitState(state, commit.action);
+}
+function assertApprovedVisibleCommit(commit) {
+	if (commit[approvedVisibleCommitBrand] !== true) throw new Error("[vinext] Visible router state mutation requires ApprovedVisibleCommit");
+}
+function commitOperationRecord(operation, visibleCommitVersion) {
+	return {
+		id: operation.id,
+		lane: operation.lane,
+		startedVisibleCommitVersion: operation.startedVisibleCommitVersion,
+		state: "committed",
+		visibleCommitVersion
+	};
+}
+function commitVisibleRouterState(state, nextState, operation) {
+	const visibleCommitVersion = state.visibleCommitVersion + 1;
+	return {
+		...nextState,
+		activeOperation: commitOperationRecord(operation, visibleCommitVersion),
+		visibleCommitVersion
+	};
+}
+function reduceApprovedVisibleCommitState(state, action) {
+	switch (action.type) {
+		case "traverse":
+		case "navigate": return commitVisibleRouterState(state, {
+			elements: mergeElements(state.elements, action.elements, action.type === "traverse"),
+			interceptionContext: action.interceptionContext,
+			layoutFlags: {
+				...state.layoutFlags,
+				...action.layoutFlags
+			},
+			navigationSnapshot: action.navigationSnapshot,
+			previousNextUrl: action.previousNextUrl,
+			renderId: action.renderId,
+			rootLayoutTreePath: action.rootLayoutTreePath,
+			routeId: action.routeId
+		}, action.operation);
+		case "replace": return commitVisibleRouterState(state, {
+			elements: action.elements,
+			interceptionContext: action.interceptionContext,
+			layoutFlags: action.layoutFlags,
+			navigationSnapshot: action.navigationSnapshot,
+			previousNextUrl: action.previousNextUrl,
+			renderId: action.renderId,
+			rootLayoutTreePath: action.rootLayoutTreePath,
+			routeId: action.routeId
+		}, action.operation);
+		default: {
+			const _exhaustive = action.type;
+			throw new Error("[vinext] Unknown router action: " + String(_exhaustive));
+		}
+	}
+}
+function resolvePendingNavigationCommitDecision(options) {
+	const { disposition, trace } = resolvePendingNavigationCommitDispositionDecision(options);
+	switch (disposition) {
+		case "skip": return {
+			disposition: "no-commit",
+			trace
+		};
+		case "hard-navigate": return {
+			disposition: "hard-navigate",
+			trace
+		};
+		case "dispatch": return createVisibleCommitDecision(trace);
+		default: throw new Error("[vinext] Unknown navigation commit disposition: " + String(disposition));
+	}
+}
+function createVisibleCommitDecision(trace = createNavigationTrace(NavigationTraceReasonCodes.commitCurrent)) {
+	return {
+		disposition: "commit",
+		trace
+	};
+}
+function createApprovedVisibleCommit(options) {
+	return {
+		[approvedVisibleCommitBrand]: true,
+		action: options.pending.action,
+		decision: options.decision,
+		interceptionContext: options.pending.interceptionContext,
+		previousNextUrl: options.pending.previousNextUrl,
+		rootLayoutTreePath: options.pending.rootLayoutTreePath,
+		routeId: options.pending.routeId
+	};
+}
+function createCommitTransactionFields(pending) {
+	return {
+		operationLane: pending.action.operation.lane,
+		pendingOperationId: pending.action.operation.id,
+		startedVisibleCommitVersion: pending.action.operation.startedVisibleCommitVersion
+	};
+}
+function prependCommitTransactionTrace(trace, code, pending) {
+	return prependNavigationTraceEntry(trace, code, createCommitTransactionFields(pending));
+}
+function addCommitTransactionTrace(decision, pending) {
+	switch (decision.disposition) {
+		case "commit": return {
+			...decision,
+			trace: prependCommitTransactionTrace(decision.trace, NavigationTraceTransactionCodes.visibleCommit, pending)
+		};
+		case "hard-navigate": return {
+			...decision,
+			trace: prependCommitTransactionTrace(decision.trace, NavigationTraceTransactionCodes.hardNavigate, pending)
+		};
+		case "no-commit": return {
+			...decision,
+			trace: prependCommitTransactionTrace(decision.trace, NavigationTraceTransactionCodes.noCommit, pending)
+		};
+		default: throw new Error("[vinext] Unknown commit decision: " + String(decision));
+	}
+}
+function approveHmrVisibleCommit(pending) {
+	if (pending.action.operation.lane !== "hmr") throw new Error("[vinext] HMR visible commit approval requires an HMR pending operation");
+	const decision = addCommitTransactionTrace(createVisibleCommitDecision(), pending);
+	if (decision.disposition !== "commit") throw new Error("[vinext] HMR visible commit approval did not produce a commit decision");
+	return createApprovedVisibleCommit({
+		decision,
+		pending
+	});
+}
+function approvePendingNavigationCommit(options) {
+	const decision = addCommitTransactionTrace(resolvePendingNavigationCommitDecision({
+		activeNavigationId: options.activeNavigationId,
+		currentVisibleCommitVersion: options.currentState.visibleCommitVersion,
+		currentRootLayoutTreePath: options.currentState.rootLayoutTreePath,
+		nextRootLayoutTreePath: options.pending.rootLayoutTreePath,
+		startedNavigationId: options.startedNavigationId,
+		startedVisibleCommitVersion: options.pending.action.operation.startedVisibleCommitVersion
+	}), options.pending);
+	switch (decision.disposition) {
+		case "commit": return {
+			approvedCommit: createApprovedVisibleCommit({
+				decision,
+				pending: options.pending
+			}),
+			decision
+		};
+		case "hard-navigate":
+		case "no-commit": return {
+			approvedCommit: null,
+			decision
+		};
+		default: throw new Error("[vinext] Unknown commit decision: " + String(decision));
+	}
+}
+async function resolveAndClassifyNavigationCommit(options) {
+	const pending = await createPendingNavigationCommit({
+		currentState: options.currentState,
+		nextElements: options.nextElements,
+		navigationSnapshot: options.navigationSnapshot,
+		operationLane: options.operationLane,
+		previousNextUrl: options.previousNextUrl,
+		renderId: options.renderId,
+		type: options.type
+	});
+	const approvalState = options.getCurrentStateForApproval?.() ?? options.currentState;
+	const approval = approvePendingNavigationCommit({
+		activeNavigationId: options.getActiveNavigationId?.() ?? options.activeNavigationId,
+		currentState: approvalState,
+		pending,
+		startedNavigationId: options.startedNavigationId
+	});
+	return {
+		approvedCommit: approval.approvedCommit,
+		decision: approval.decision,
+		pending,
+		trace: approval.decision.trace
+	};
+}
+//#endregion
+export { applyApprovedVisibleCommit, approveHmrVisibleCommit, approvePendingNavigationCommit, resolveAndClassifyNavigationCommit };
+
+//# sourceMappingURL=app-browser-visible-commit.js.map

package/dist/server/app-browser-visible-commit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-browser-visible-commit.js","names":[],"sources":["../../src/server/app-browser-visible-commit.ts"],"sourcesContent":["import type { ClientNavigationRenderSnapshot } from \"vinext/shims/navigation\";\nimport { mergeElements } from \"vinext/shims/slot\";\nimport type { AppElements } from \"./app-elements.js\";\nimport {\n  createPendingNavigationCommit,\n  resolvePendingNavigationCommitDispositionDecision,\n  type AppRouterAction,\n  type AppRouterState,\n  type CommittedOperationRecord,\n  type OperationLane,\n  type PendingNavigationCommit,\n  type PendingOperationRecord,\n} from \"./app-browser-state.js\";\nimport {\n  NavigationTraceReasonCodes,\n  NavigationTraceTransactionCodes,\n  createNavigationTrace,\n  prependNavigationTraceEntry,\n  type NavigationTrace,\n  type NavigationTraceFields,\n  type NavigationTraceTransactionCode,\n} from \"./navigation-trace.js\";\n\ntype VisibleCommitDecision = {\n  disposition: \"commit\";\n  trace: NavigationTrace;\n};\ntype HardNavigateCommitDecision = {\n  disposition: \"hard-navigate\";\n  trace: NavigationTrace;\n};\ntype NoCommitDecision = {\n  disposition: \"no-commit\";\n  trace: NavigationTrace;\n};\ntype CommitDecision = VisibleCommitDecision | HardNavigateCommitDecision | NoCommitDecision;\nconst approvedVisibleCommitBrand: unique symbol = Symbol(\"ApprovedVisibleCommit\");\nexport type ApprovedVisibleCommit = {\n  readonly [approvedVisibleCommitBrand]: true;\n  readonly action: AppRouterAction;\n  readonly decision: VisibleCommitDecision;\n  readonly interceptionContext: string | null;\n  readonly previousNextUrl: string | null;\n  readonly rootLayoutTreePath: string | null;\n  readonly routeId: string;\n};\ntype VisibleCommitApproval = {\n  approvedCommit: ApprovedVisibleCommit;\n  decision: VisibleCommitDecision;\n};\ntype NonVisibleCommitApproval = {\n  approvedCommit: null;\n  decision: HardNavigateCommitDecision | NoCommitDecision;\n};\ntype CommitApproval = VisibleCommitApproval | NonVisibleCommitApproval;\ntype ClassifiedPendingNavigationCommit = {\n  approvedCommit: ApprovedVisibleCommit | null;\n  decision: CommitDecision;\n  pending: PendingNavigationCommit;\n  trace: NavigationTrace;\n};\n\nexport function applyApprovedVisibleCommit(\n  state: AppRouterState,\n  commit: ApprovedVisibleCommit,\n): AppRouterState {\n  assertApprovedVisibleCommit(commit);\n  return reduceApprovedVisibleCommitState(state, commit.action);\n}\n\nfunction assertApprovedVisibleCommit(commit: ApprovedVisibleCommit): void {\n  if (commit[approvedVisibleCommitBrand] !== true) {\n    throw new Error(\"[vinext] Visible router state mutation requires ApprovedVisibleCommit\");\n  }\n}\n\nfunction commitOperationRecord(\n  operation: PendingOperationRecord,\n  visibleCommitVersion: number,\n): CommittedOperationRecord {\n  return {\n    id: operation.id,\n    lane: operation.lane,\n    startedVisibleCommitVersion: operation.startedVisibleCommitVersion,\n    state: \"committed\",\n    visibleCommitVersion,\n  };\n}\n\nfunction commitVisibleRouterState(\n  state: AppRouterState,\n  nextState: Omit<AppRouterState, \"activeOperation\" | \"visibleCommitVersion\">,\n  operation: PendingOperationRecord,\n): AppRouterState {\n  // Single owner for visibleCommitVersion: only an ApprovedVisibleCommit may\n  // advance it, and every accepted visible mutation advances it exactly once.\n  const visibleCommitVersion = state.visibleCommitVersion + 1;\n  return {\n    ...nextState,\n    activeOperation: commitOperationRecord(operation, visibleCommitVersion),\n    visibleCommitVersion,\n  };\n}\n\nfunction reduceApprovedVisibleCommitState(\n  state: AppRouterState,\n  action: AppRouterAction,\n): AppRouterState {\n  switch (action.type) {\n    case \"traverse\":\n    case \"navigate\":\n      return commitVisibleRouterState(\n        state,\n        {\n          elements: mergeElements(state.elements, action.elements, action.type === \"traverse\"),\n          interceptionContext: action.interceptionContext,\n          layoutFlags: { ...state.layoutFlags, ...action.layoutFlags },\n          navigationSnapshot: action.navigationSnapshot,\n          previousNextUrl: action.previousNextUrl,\n          renderId: action.renderId,\n          rootLayoutTreePath: action.rootLayoutTreePath,\n          routeId: action.routeId,\n        },\n        action.operation,\n      );\n    case \"replace\":\n      return commitVisibleRouterState(\n        state,\n        {\n          elements: action.elements,\n          interceptionContext: action.interceptionContext,\n          layoutFlags: action.layoutFlags,\n          navigationSnapshot: action.navigationSnapshot,\n          previousNextUrl: action.previousNextUrl,\n          renderId: action.renderId,\n          rootLayoutTreePath: action.rootLayoutTreePath,\n          routeId: action.routeId,\n        },\n        action.operation,\n      );\n    default: {\n      const _exhaustive: never = action.type;\n      throw new Error(\"[vinext] Unknown router action: \" + String(_exhaustive));\n    }\n  }\n}\n\nfunction resolvePendingNavigationCommitDecision(options: {\n  activeNavigationId: number;\n  currentVisibleCommitVersion: number;\n  currentRootLayoutTreePath: string | null;\n  nextRootLayoutTreePath: string | null;\n  startedNavigationId: number;\n  startedVisibleCommitVersion: number;\n}): CommitDecision {\n  const { disposition, trace } = resolvePendingNavigationCommitDispositionDecision(options);\n\n  switch (disposition) {\n    case \"skip\":\n      return { disposition: \"no-commit\", trace };\n    case \"hard-navigate\":\n      return { disposition: \"hard-navigate\", trace };\n    case \"dispatch\":\n      return createVisibleCommitDecision(trace);\n    default: {\n      const _exhaustive: never = disposition;\n      throw new Error(\"[vinext] Unknown navigation commit disposition: \" + String(_exhaustive));\n    }\n  }\n}\n\nfunction createVisibleCommitDecision(\n  trace: NavigationTrace = createNavigationTrace(NavigationTraceReasonCodes.commitCurrent),\n): VisibleCommitDecision {\n  return { disposition: \"commit\", trace };\n}\n\nfunction createApprovedVisibleCommit(options: {\n  decision: VisibleCommitDecision;\n  pending: PendingNavigationCommit;\n}): ApprovedVisibleCommit {\n  return {\n    [approvedVisibleCommitBrand]: true,\n    action: options.pending.action,\n    decision: options.decision,\n    interceptionContext: options.pending.interceptionContext,\n    previousNextUrl: options.pending.previousNextUrl,\n    rootLayoutTreePath: options.pending.rootLayoutTreePath,\n    routeId: options.pending.routeId,\n  };\n}\n\nfunction createCommitTransactionFields(pending: PendingNavigationCommit): NavigationTraceFields {\n  return {\n    operationLane: pending.action.operation.lane,\n    pendingOperationId: pending.action.operation.id,\n    startedVisibleCommitVersion: pending.action.operation.startedVisibleCommitVersion,\n  };\n}\n\nfunction prependCommitTransactionTrace(\n  trace: NavigationTrace,\n  code: NavigationTraceTransactionCode,\n  pending: PendingNavigationCommit,\n): NavigationTrace {\n  return prependNavigationTraceEntry(trace, code, createCommitTransactionFields(pending));\n}\n\nfunction addCommitTransactionTrace(\n  decision: CommitDecision,\n  pending: PendingNavigationCommit,\n): CommitDecision {\n  switch (decision.disposition) {\n    case \"commit\":\n      return {\n        ...decision,\n        trace: prependCommitTransactionTrace(\n          decision.trace,\n          NavigationTraceTransactionCodes.visibleCommit,\n          pending,\n        ),\n      };\n    case \"hard-navigate\":\n      return {\n        ...decision,\n        trace: prependCommitTransactionTrace(\n          decision.trace,\n          NavigationTraceTransactionCodes.hardNavigate,\n          pending,\n        ),\n      };\n    case \"no-commit\":\n      return {\n        ...decision,\n        trace: prependCommitTransactionTrace(\n          decision.trace,\n          NavigationTraceTransactionCodes.noCommit,\n          pending,\n        ),\n      };\n    default: {\n      const _exhaustive: never = decision;\n      throw new Error(\"[vinext] Unknown commit decision: \" + String(_exhaustive));\n    }\n  }\n}\n\nexport function approveHmrVisibleCommit(pending: PendingNavigationCommit): ApprovedVisibleCommit {\n  if (pending.action.operation.lane !== \"hmr\") {\n    throw new Error(\"[vinext] HMR visible commit approval requires an HMR pending operation\");\n  }\n\n  const decision = addCommitTransactionTrace(createVisibleCommitDecision(), pending);\n  // This guard is a type narrowing assertion: createVisibleCommitDecision()\n  // structurally produces a commit decision, and addCommitTransactionTrace()\n  // must preserve that disposition while adding operator trace context.\n  if (decision.disposition !== \"commit\") {\n    throw new Error(\"[vinext] HMR visible commit approval did not produce a commit decision\");\n  }\n\n  return createApprovedVisibleCommit({\n    decision,\n    pending,\n  });\n}\n\nexport function approvePendingNavigationCommit(options: {\n  activeNavigationId: number;\n  currentState: AppRouterState;\n  pending: PendingNavigationCommit;\n  startedNavigationId: number;\n}): CommitApproval {\n  const decision = addCommitTransactionTrace(\n    resolvePendingNavigationCommitDecision({\n      activeNavigationId: options.activeNavigationId,\n      currentVisibleCommitVersion: options.currentState.visibleCommitVersion,\n      currentRootLayoutTreePath: options.currentState.rootLayoutTreePath,\n      nextRootLayoutTreePath: options.pending.rootLayoutTreePath,\n      startedNavigationId: options.startedNavigationId,\n      startedVisibleCommitVersion: options.pending.action.operation.startedVisibleCommitVersion,\n    }),\n    options.pending,\n  );\n\n  switch (decision.disposition) {\n    case \"commit\":\n      return {\n        approvedCommit: createApprovedVisibleCommit({\n          decision,\n          pending: options.pending,\n        }),\n        decision,\n      };\n    case \"hard-navigate\":\n    case \"no-commit\":\n      return {\n        approvedCommit: null,\n        decision,\n      };\n    default: {\n      const _exhaustive: never = decision;\n      throw new Error(\"[vinext] Unknown commit decision: \" + String(_exhaustive));\n    }\n  }\n}\n\nexport async function resolveAndClassifyNavigationCommit(options: {\n  activeNavigationId: number;\n  currentState: AppRouterState;\n  // When provided, these getters are called after awaiting nextElements so\n  // approval uses the latest lifecycle authority instead of the call snapshot.\n  getActiveNavigationId?: () => number;\n  getCurrentStateForApproval?: () => AppRouterState;\n  navigationSnapshot: ClientNavigationRenderSnapshot;\n  nextElements: Promise<AppElements>;\n  operationLane: OperationLane;\n  previousNextUrl?: string | null;\n  renderId: number;\n  startedNavigationId: number;\n  type: \"navigate\" | \"replace\" | \"traverse\";\n}): Promise<ClassifiedPendingNavigationCommit> {\n  const pending = await createPendingNavigationCommit({\n    currentState: options.currentState,\n    nextElements: options.nextElements,\n    navigationSnapshot: options.navigationSnapshot,\n    operationLane: options.operationLane,\n    previousNextUrl: options.previousNextUrl,\n    renderId: options.renderId,\n    type: options.type,\n  });\n\n  const approvalState = options.getCurrentStateForApproval?.() ?? options.currentState;\n  const approval = approvePendingNavigationCommit({\n    activeNavigationId: options.getActiveNavigationId?.() ?? options.activeNavigationId,\n    currentState: approvalState,\n    pending,\n    startedNavigationId: options.startedNavigationId,\n  });\n\n  return {\n    approvedCommit: approval.approvedCommit,\n    decision: approval.decision,\n    pending,\n    trace: approval.decision.trace,\n  };\n}\n"],"mappings":"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"}

package/dist/server/app-client-reference-preloader.d.ts

@@ -0,0 +1,15 @@
+//#region src/server/app-client-reference-preloader.d.ts
+type ClientReferenceRequire = (id: string) => Promise<unknown>;
+type ClientReferenceMap = Readonly<Record<string, unknown>>;
+type ClientReferencePreloaderOptions = {
+  getReferences: () => ClientReferenceMap | undefined;
+  getClientRequire: () => ClientReferenceRequire | undefined;
+  onPreloadError?: (id: string, error: unknown) => void;
+};
+type ClientReferencePreloader = {
+  preload: (referenceIds?: Iterable<string>) => Promise<void>;
+};
+declare function createClientReferencePreloader(options: ClientReferencePreloaderOptions): ClientReferencePreloader;
+//#endregion
+export { createClientReferencePreloader };
+//# sourceMappingURL=app-client-reference-preloader.d.ts.map

package/dist/server/app-client-reference-preloader.js

@@ -0,0 +1,46 @@
+//#region src/server/app-client-reference-preloader.ts
+const resolvedPreload = Promise.resolve();
+function createClientReferencePreloader(options) {
+	let allReferencesPreloaded = false;
+	let allReferencesPreloadPromise = null;
+	const preloadedReferences = /* @__PURE__ */ new Set();
+	const referencePreloadPromises = /* @__PURE__ */ new Map();
+	function preloadReference(id, clientRequire) {
+		if (preloadedReferences.has(id)) return resolvedPreload;
+		const existing = referencePreloadPromises.get(id);
+		if (existing) return existing;
+		const preloadPromise = clientRequire(id).catch((error) => {
+			options.onPreloadError?.(id, error);
+		}).then(() => {
+			preloadedReferences.add(id);
+		}).finally(() => {
+			referencePreloadPromises.delete(id);
+		});
+		referencePreloadPromises.set(id, preloadPromise);
+		return preloadPromise;
+	}
+	function preloadReferenceSet(referenceIds, refs, clientRequire) {
+		const pending = [];
+		for (const id of referenceIds) if (Object.hasOwn(refs, id)) pending.push(preloadReference(id, clientRequire));
+		if (pending.length === 0) return resolvedPreload;
+		return Promise.all(pending).then(() => {});
+	}
+	return { preload(referenceIds) {
+		const refs = options.getReferences();
+		const clientRequire = options.getClientRequire();
+		if (!refs || !clientRequire) return resolvedPreload;
+		if (referenceIds) return preloadReferenceSet(referenceIds, refs, clientRequire);
+		if (allReferencesPreloaded) return resolvedPreload;
+		if (allReferencesPreloadPromise) return allReferencesPreloadPromise;
+		allReferencesPreloadPromise = preloadReferenceSet(Object.keys(refs), refs, clientRequire).then(() => {
+			allReferencesPreloaded = true;
+		}).finally(() => {
+			allReferencesPreloadPromise = null;
+		});
+		return allReferencesPreloadPromise;
+	} };
+}
+//#endregion
+export { createClientReferencePreloader };
+
+//# sourceMappingURL=app-client-reference-preloader.js.map

package/dist/server/app-client-reference-preloader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-client-reference-preloader.js","names":[],"sources":["../../src/server/app-client-reference-preloader.ts"],"sourcesContent":["type ClientReferenceRequire = (id: string) => Promise<unknown>;\n\ntype ClientReferenceMap = Readonly<Record<string, unknown>>;\n\ntype ClientReferencePreloaderOptions = {\n  getReferences: () => ClientReferenceMap | undefined;\n  getClientRequire: () => ClientReferenceRequire | undefined;\n  onPreloadError?: (id: string, error: unknown) => void;\n};\n\ntype ClientReferencePreloader = {\n  preload: (referenceIds?: Iterable<string>) => Promise<void>;\n};\n\nconst resolvedPreload = Promise.resolve();\n\nexport function createClientReferencePreloader(\n  options: ClientReferencePreloaderOptions,\n): ClientReferencePreloader {\n  let allReferencesPreloaded = false;\n  let allReferencesPreloadPromise: Promise<void> | null = null;\n  const preloadedReferences = new Set<string>();\n  const referencePreloadPromises = new Map<string, Promise<void>>();\n\n  function preloadReference(id: string, clientRequire: ClientReferenceRequire): Promise<void> {\n    if (preloadedReferences.has(id)) {\n      return resolvedPreload;\n    }\n\n    const existing = referencePreloadPromises.get(id);\n    if (existing) {\n      return existing;\n    }\n\n    const preloadPromise = clientRequire(id)\n      .catch((error) => {\n        options.onPreloadError?.(id, error);\n      })\n      .then(() => {\n        preloadedReferences.add(id);\n      })\n      .finally(() => {\n        referencePreloadPromises.delete(id);\n      });\n\n    referencePreloadPromises.set(id, preloadPromise);\n    return preloadPromise;\n  }\n\n  function preloadReferenceSet(\n    referenceIds: Iterable<string>,\n    refs: ClientReferenceMap,\n    clientRequire: ClientReferenceRequire,\n  ): Promise<void> {\n    const pending: Promise<void>[] = [];\n\n    for (const id of referenceIds) {\n      if (Object.hasOwn(refs, id)) {\n        pending.push(preloadReference(id, clientRequire));\n      }\n    }\n\n    if (pending.length === 0) {\n      return resolvedPreload;\n    }\n\n    return Promise.all(pending).then(() => {});\n  }\n\n  return {\n    preload(referenceIds) {\n      const refs = options.getReferences();\n      const clientRequire = options.getClientRequire();\n      if (!refs || !clientRequire) {\n        return resolvedPreload;\n      }\n\n      if (referenceIds) {\n        return preloadReferenceSet(referenceIds, refs, clientRequire);\n      }\n\n      if (allReferencesPreloaded) {\n        return resolvedPreload;\n      }\n      if (allReferencesPreloadPromise) {\n        return allReferencesPreloadPromise;\n      }\n\n      allReferencesPreloadPromise = preloadReferenceSet(Object.keys(refs), refs, clientRequire)\n        .then(() => {\n          allReferencesPreloaded = true;\n        })\n        .finally(() => {\n          allReferencesPreloadPromise = null;\n        });\n\n      return allReferencesPreloadPromise;\n    },\n  };\n}\n"],"mappings":";AAcA,MAAM,kBAAkB,QAAQ,SAAS;AAEzC,SAAgB,+BACd,SAC0B;CAC1B,IAAI,yBAAyB;CAC7B,IAAI,8BAAoD;CACxD,MAAM,sCAAsB,IAAI,KAAa;CAC7C,MAAM,2CAA2B,IAAI,KAA4B;CAEjE,SAAS,iBAAiB,IAAY,eAAsD;AAC1F,MAAI,oBAAoB,IAAI,GAAG,CAC7B,QAAO;EAGT,MAAM,WAAW,yBAAyB,IAAI,GAAG;AACjD,MAAI,SACF,QAAO;EAGT,MAAM,iBAAiB,cAAc,GAAG,CACrC,OAAO,UAAU;AAChB,WAAQ,iBAAiB,IAAI,MAAM;IACnC,CACD,WAAW;AACV,uBAAoB,IAAI,GAAG;IAC3B,CACD,cAAc;AACb,4BAAyB,OAAO,GAAG;IACnC;AAEJ,2BAAyB,IAAI,IAAI,eAAe;AAChD,SAAO;;CAGT,SAAS,oBACP,cACA,MACA,eACe;EACf,MAAM,UAA2B,EAAE;AAEnC,OAAK,MAAM,MAAM,aACf,KAAI,OAAO,OAAO,MAAM,GAAG,CACzB,SAAQ,KAAK,iBAAiB,IAAI,cAAc,CAAC;AAIrD,MAAI,QAAQ,WAAW,EACrB,QAAO;AAGT,SAAO,QAAQ,IAAI,QAAQ,CAAC,WAAW,GAAG;;AAG5C,QAAO,EACL,QAAQ,cAAc;EACpB,MAAM,OAAO,QAAQ,eAAe;EACpC,MAAM,gBAAgB,QAAQ,kBAAkB;AAChD,MAAI,CAAC,QAAQ,CAAC,cACZ,QAAO;AAGT,MAAI,aACF,QAAO,oBAAoB,cAAc,MAAM,cAAc;AAG/D,MAAI,uBACF,QAAO;AAET,MAAI,4BACF,QAAO;AAGT,gCAA8B,oBAAoB,OAAO,KAAK,KAAK,EAAE,MAAM,cAAc,CACtF,WAAW;AACV,4BAAyB;IACzB,CACD,cAAc;AACb,iCAA8B;IAC9B;AAEJ,SAAO;IAEV"}

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

@@ -0,0 +1,130 @@
+import { ArtifactCompatibilityEnvelope } from "./artifact-compatibility.js";
+import { ReactNode } from "react";
+
+//#region src/server/app-elements-wire.d.ts
+declare const APP_ARTIFACT_COMPATIBILITY_KEY = "__artifactCompatibility";
+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  — AppElementsWire.encodeOutgoingPayload writes `__layoutFlags`
+ *                into the outgoing App Router payload record.
+ *
+ *   3. WIRE    — renderToReadableStream serializes the record as RSC row 0.
+ *
+ *   4. PARSE   — AppElementsWire.readMetadata extracts layoutFlags from the
+ *                wire payload on the client side.
+ */
+type LayoutFlags = Readonly<Record<string, "s" | "d">>;
+type AppElementsMetadata = {
+  artifactCompatibility: ArtifactCompatibilityEnvelope;
+  interceptionContext: string | null;
+  layoutFlags: LayoutFlags;
+  routeId: string;
+  rootLayoutTreePath: string | null;
+};
+type AppElementsWireElementKey = {
+  kind: "layout";
+  treePath: string;
+} | {
+  interceptionContext: string | null;
+  kind: "page";
+  path: string;
+} | {
+  interceptionContext: string | null;
+  kind: "route";
+  path: string;
+} | {
+  kind: "slot";
+  name: string;
+  treePath: string;
+} | {
+  kind: "template";
+  treePath: string;
+};
+type AppElementsWireMetadataInput = {
+  interceptionContext: string | null;
+  routeId: string;
+  rootLayoutTreePath: string | null;
+};
+type AppElementsWireMetadataEntries = Readonly<{
+  [APP_ROUTE_KEY]: string;
+  [APP_INTERCEPTION_CONTEXT_KEY]: string | null;
+  [APP_ROOT_LAYOUT_KEY]: string | null;
+}>;
+/**
+ * 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 | ArtifactCompatibilityEnvelope>>;
+type AppElementsWireKeys = {
+  readonly artifactCompatibility: typeof APP_ARTIFACT_COMPATIBILITY_KEY;
+  readonly interceptionContext: typeof APP_INTERCEPTION_CONTEXT_KEY;
+  readonly layoutFlags: typeof APP_LAYOUT_FLAGS_KEY;
+  readonly rootLayout: typeof APP_ROOT_LAYOUT_KEY;
+  readonly route: typeof APP_ROUTE_KEY;
+};
+type AppElementsWireCodec = {
+  readonly keys: AppElementsWireKeys;
+  readonly unmatchedSlotValue: typeof APP_UNMATCHED_SLOT_WIRE_VALUE;
+  createMetadataEntries(input: AppElementsWireMetadataInput): AppElementsWireMetadataEntries;
+  decode(elements: AppWireElements): AppElements;
+  encodeCacheKey(rscUrl: string, interceptionContext: string | null): string;
+  encodeLayoutId(treePath: string): string;
+  encodeOutgoingPayload(input: {
+    element: ReactNode | Readonly<Record<string, ReactNode>>;
+    artifactCompatibility?: ArtifactCompatibilityEnvelope;
+    layoutFlags: LayoutFlags;
+  }): ReactNode | AppOutgoingElements;
+  encodePageId(routePath: string, interceptionContext: string | null): string;
+  encodeRouteId(routePath: string, interceptionContext: string | null): string;
+  encodeSlotId(slotName: string, treePath: string): string;
+  encodeTemplateId(treePath: string): string;
+  isSlotId(key: string): boolean;
+  parseElementKey(key: string): AppElementsWireElementKey | null;
+  readMetadata(elements: Readonly<Record<string, unknown>>): AppElementsMetadata;
+  withLayoutFlags<T extends Record<string, unknown>>(elements: T, layoutFlags: LayoutFlags): T & {
+    [APP_LAYOUT_FLAGS_KEY]: LayoutFlags;
+  };
+};
+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>>;
+declare function withLayoutFlags<T extends Record<string, unknown>>(elements: T, layoutFlags: LayoutFlags): T & {
+  [APP_LAYOUT_FLAGS_KEY]: LayoutFlags;
+};
+declare function buildOutgoingAppPayload(input: {
+  element: ReactNode | Readonly<Record<string, ReactNode>>;
+  artifactCompatibility?: ArtifactCompatibilityEnvelope;
+  layoutFlags: LayoutFlags;
+}): ReactNode | AppOutgoingElements;
+declare function readAppElementsMetadata(elements: Readonly<Record<string, unknown>>): AppElementsMetadata;
+declare const AppElementsWire: AppElementsWireCodec;
+//#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, AppElementValue, AppElements, AppElementsWire, AppOutgoingElements, AppWireElements, LayoutFlags, UNMATCHED_SLOT, buildOutgoingAppPayload, isAppElementsRecord, normalizeAppElements, readAppElementsMetadata, withLayoutFlags };
+//# sourceMappingURL=app-elements-wire.d.ts.map