@rangojs/router 0.0.0-experimental.debug-cache-fix → 0.0.0-experimental.dfdb0387

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (115) hide show
  1. package/README.md +76 -18
  2. package/dist/bin/rango.js +130 -47
  3. package/dist/vite/index.js +702 -231
  4. package/package.json +2 -2
  5. package/skills/cache-guide/SKILL.md +32 -0
  6. package/skills/caching/SKILL.md +8 -0
  7. package/skills/links/SKILL.md +3 -1
  8. package/skills/loader/SKILL.md +53 -43
  9. package/skills/middleware/SKILL.md +2 -0
  10. package/skills/prerender/SKILL.md +110 -68
  11. package/skills/route/SKILL.md +31 -0
  12. package/skills/router-setup/SKILL.md +87 -2
  13. package/skills/typesafety/SKILL.md +10 -0
  14. package/src/__internal.ts +1 -1
  15. package/src/browser/app-version.ts +14 -0
  16. package/src/browser/navigation-bridge.ts +16 -3
  17. package/src/browser/navigation-client.ts +98 -46
  18. package/src/browser/navigation-store.ts +43 -8
  19. package/src/browser/partial-update.ts +32 -5
  20. package/src/browser/prefetch/cache.ts +16 -6
  21. package/src/browser/prefetch/fetch.ts +52 -6
  22. package/src/browser/prefetch/queue.ts +61 -29
  23. package/src/browser/prefetch/resource-ready.ts +77 -0
  24. package/src/browser/react/Link.tsx +67 -8
  25. package/src/browser/react/NavigationProvider.tsx +13 -4
  26. package/src/browser/react/context.ts +7 -2
  27. package/src/browser/react/use-handle.ts +9 -58
  28. package/src/browser/react/use-router.ts +21 -8
  29. package/src/browser/rsc-router.tsx +26 -3
  30. package/src/browser/scroll-restoration.ts +10 -8
  31. package/src/browser/segment-reconciler.ts +26 -0
  32. package/src/browser/server-action-bridge.ts +8 -6
  33. package/src/browser/types.ts +27 -5
  34. package/src/build/generate-manifest.ts +6 -6
  35. package/src/build/generate-route-types.ts +3 -0
  36. package/src/build/route-types/include-resolution.ts +8 -1
  37. package/src/build/route-types/router-processing.ts +211 -72
  38. package/src/build/route-types/scan-filter.ts +8 -1
  39. package/src/cache/cache-scope.ts +12 -14
  40. package/src/cache/taint.ts +55 -0
  41. package/src/client.tsx +2 -56
  42. package/src/context-var.ts +72 -2
  43. package/src/handle.ts +40 -0
  44. package/src/index.rsc.ts +3 -1
  45. package/src/index.ts +12 -0
  46. package/src/prerender/store.ts +5 -4
  47. package/src/prerender.ts +138 -77
  48. package/src/reverse.ts +22 -1
  49. package/src/route-definition/dsl-helpers.ts +42 -19
  50. package/src/route-definition/helpers-types.ts +10 -6
  51. package/src/route-definition/index.ts +3 -0
  52. package/src/route-definition/redirect.ts +9 -1
  53. package/src/route-definition/resolve-handler-use.ts +149 -0
  54. package/src/route-types.ts +11 -0
  55. package/src/router/content-negotiation.ts +100 -1
  56. package/src/router/handler-context.ts +79 -23
  57. package/src/router/intercept-resolution.ts +9 -4
  58. package/src/router/loader-resolution.ts +156 -21
  59. package/src/router/match-api.ts +124 -189
  60. package/src/router/match-middleware/cache-lookup.ts +26 -7
  61. package/src/router/match-middleware/segment-resolution.ts +53 -0
  62. package/src/router/match-result.ts +82 -4
  63. package/src/router/middleware-types.ts +6 -8
  64. package/src/router/middleware.ts +2 -5
  65. package/src/router/navigation-snapshot.ts +182 -0
  66. package/src/router/prerender-match.ts +110 -10
  67. package/src/router/preview-match.ts +30 -102
  68. package/src/router/request-classification.ts +310 -0
  69. package/src/router/route-snapshot.ts +245 -0
  70. package/src/router/router-interfaces.ts +36 -4
  71. package/src/router/router-options.ts +37 -11
  72. package/src/router/segment-resolution/fresh.ts +80 -9
  73. package/src/router/segment-resolution/helpers.ts +29 -24
  74. package/src/router/segment-resolution/revalidation.ts +91 -8
  75. package/src/router/types.ts +1 -0
  76. package/src/router.ts +54 -5
  77. package/src/rsc/handler.ts +472 -372
  78. package/src/rsc/loader-fetch.ts +23 -3
  79. package/src/rsc/manifest-init.ts +5 -1
  80. package/src/rsc/progressive-enhancement.ts +14 -2
  81. package/src/rsc/rsc-rendering.ts +10 -1
  82. package/src/rsc/server-action.ts +8 -0
  83. package/src/rsc/ssr-setup.ts +2 -2
  84. package/src/rsc/types.ts +9 -1
  85. package/src/server/context.ts +50 -1
  86. package/src/server/handle-store.ts +19 -0
  87. package/src/server/loader-registry.ts +9 -8
  88. package/src/server/request-context.ts +175 -15
  89. package/src/ssr/index.tsx +3 -0
  90. package/src/static-handler.ts +18 -6
  91. package/src/types/cache-types.ts +4 -4
  92. package/src/types/handler-context.ts +37 -19
  93. package/src/types/loader-types.ts +36 -9
  94. package/src/types/route-entry.ts +1 -1
  95. package/src/types/segments.ts +1 -0
  96. package/src/urls/path-helper-types.ts +9 -2
  97. package/src/urls/path-helper.ts +47 -12
  98. package/src/urls/pattern-types.ts +12 -0
  99. package/src/urls/response-types.ts +16 -6
  100. package/src/use-loader.tsx +77 -5
  101. package/src/vite/discovery/bundle-postprocess.ts +30 -33
  102. package/src/vite/discovery/discover-routers.ts +5 -1
  103. package/src/vite/discovery/prerender-collection.ts +128 -74
  104. package/src/vite/discovery/state.ts +13 -4
  105. package/src/vite/index.ts +4 -0
  106. package/src/vite/plugin-types.ts +60 -5
  107. package/src/vite/plugins/expose-id-utils.ts +12 -0
  108. package/src/vite/plugins/expose-ids/handler-transform.ts +30 -0
  109. package/src/vite/plugins/expose-internal-ids.ts +257 -40
  110. package/src/vite/plugins/performance-tracks.ts +88 -0
  111. package/src/vite/plugins/refresh-cmd.ts +88 -26
  112. package/src/vite/rango.ts +19 -2
  113. package/src/vite/router-discovery.ts +178 -37
  114. package/src/vite/utils/prerender-utils.ts +18 -0
  115. package/src/vite/utils/shared-utils.ts +3 -2
@@ -125,6 +125,69 @@ export async function collectSegments(
125
125
  return segments;
126
126
  }
127
127
 
128
+ /**
129
+ * Deduplicate inherited loader segments by loaderId.
130
+ *
131
+ * When a route has loaders and a child layout has parallel slots, the same
132
+ * loader is resolved twice: once for the route and once inherited into the
133
+ * layout (tagged with `_inherited`). The inherited copy is only needed when
134
+ * the route uses `loading()` — in that case, the loader data is inside a
135
+ * LoaderBoundary/Suspense that parallel slots can't reach through. Without
136
+ * loading(), useLoader() traverses parent contexts and finds the data.
137
+ */
138
+ function deduplicateLoaderSegments(
139
+ segments: ResolvedSegment[],
140
+ logPrefix: string,
141
+ ): ResolvedSegment[] {
142
+ // First pass: collect loaderIds of original (non-inherited) segments
143
+ // and whether their parent entry uses loading()
144
+ const originalLoaders = new Set<string>();
145
+ const loadersWithLoading = new Set<string>();
146
+ for (const s of segments) {
147
+ if (s.type === "loader" && s.loaderId && !s._inherited) {
148
+ originalLoaders.add(s.loaderId);
149
+ // If the segment has a sibling with loading, the parent uses loading()
150
+ // We detect this by checking if any non-loader segment in the same
151
+ // namespace has loading defined
152
+ }
153
+ }
154
+ // Check if any layout/route segment has loading — if a loader's namespace
155
+ // matches a segment with loading, the inherited copy is needed
156
+ for (const s of segments) {
157
+ if (s.type !== "loader" && s.loading !== undefined && s.loading !== false) {
158
+ // Find loaders in this namespace
159
+ for (const l of segments) {
160
+ if (l.type === "loader" && l.namespace === s.namespace && l.loaderId) {
161
+ loadersWithLoading.add(l.loaderId);
162
+ }
163
+ }
164
+ }
165
+ }
166
+
167
+ const result: ResolvedSegment[] = [];
168
+ let dedupCount = 0;
169
+
170
+ for (const s of segments) {
171
+ if (
172
+ s.type === "loader" &&
173
+ s.loaderId &&
174
+ s._inherited &&
175
+ originalLoaders.has(s.loaderId) &&
176
+ !loadersWithLoading.has(s.loaderId)
177
+ ) {
178
+ dedupCount++;
179
+ continue;
180
+ }
181
+ result.push(s);
182
+ }
183
+
184
+ if (dedupCount > 0) {
185
+ debugLog(logPrefix, `deduped ${dedupCount} inherited loader segment(s)`);
186
+ }
187
+
188
+ return result;
189
+ }
190
+
128
191
  /**
129
192
  * Build the final MatchResult from collected segments and context
130
193
  */
@@ -181,6 +244,11 @@ export function buildMatchResult<TEnv>(
181
244
  );
182
245
  }
183
246
 
247
+ const dedupedSegments = deduplicateLoaderSegments(
248
+ segmentsToRender,
249
+ logPrefix,
250
+ );
251
+
184
252
  debugLog(logPrefix, "all segments", {
185
253
  segments: allSegments.map((s) => ({
186
254
  id: s.id,
@@ -189,13 +257,23 @@ export function buildMatchResult<TEnv>(
189
257
  })),
190
258
  });
191
259
  debugLog(logPrefix, "segments to render", {
192
- segmentIds: segmentsToRender.map((s) => s.id),
260
+ segmentIds: dedupedSegments.map((s) => s.id),
193
261
  });
194
262
 
263
+ // Remove deduped loader IDs from matched so the client doesn't treat
264
+ // them as missing segments and trigger a fallback refetch.
265
+ const removedIds = new Set(
266
+ segmentsToRender
267
+ .filter((s) => !dedupedSegments.includes(s))
268
+ .map((s) => s.id),
269
+ );
270
+ const matchedIds =
271
+ removedIds.size > 0 ? allIds.filter((id) => !removedIds.has(id)) : allIds;
272
+
195
273
  return {
196
- segments: segmentsToRender,
197
- matched: allIds,
198
- diff: segmentsToRender.map((s) => s.id),
274
+ segments: dedupedSegments,
275
+ matched: matchedIds,
276
+ diff: dedupedSegments.map((s) => s.id),
199
277
  params: ctx.matched.params,
200
278
  routeName: ctx.routeKey,
201
279
  slots: Object.keys(state.slots).length > 0 ? state.slots : undefined,
@@ -27,8 +27,12 @@ type GetVariableFn = {
27
27
  * Set variable function type
28
28
  */
29
29
  type SetVariableFn = {
30
- <T>(contextVar: ContextVar<T>, value: T): void;
31
- <K extends keyof DefaultVars>(key: K, value: DefaultVars[K]): void;
30
+ <T>(contextVar: ContextVar<T>, value: T, options?: { cache?: boolean }): void;
31
+ <K extends keyof DefaultVars>(
32
+ key: K,
33
+ value: DefaultVars[K],
34
+ options?: { cache?: boolean },
35
+ ): void;
32
36
  };
33
37
 
34
38
  /**
@@ -91,12 +95,6 @@ export interface MiddlewareContext<
91
95
  /** Set a context variable (shared with route handlers) */
92
96
  set: SetVariableFn;
93
97
 
94
- /**
95
- * Middleware-injected variables.
96
- * Same shared dictionary as `ctx.get()`/`ctx.set()`.
97
- */
98
- var: DefaultVars;
99
-
100
98
  /**
101
99
  * Set a response header - can be called before or after `next()`.
102
100
  *
@@ -204,12 +204,9 @@ export function createMiddlewareContext<TEnv>(
204
204
  get: ((keyOrVar: any) =>
205
205
  contextGet(variables, keyOrVar)) as MiddlewareContext<TEnv>["get"],
206
206
 
207
- set: ((keyOrVar: any, value: unknown) => {
208
- contextSet(variables, keyOrVar, value);
207
+ set: ((keyOrVar: any, value: unknown, options?: any) => {
208
+ contextSet(variables, keyOrVar, value, options);
209
209
  }) as MiddlewareContext<TEnv>["set"],
210
-
211
- var: variables as MiddlewareContext<TEnv>["var"],
212
-
213
210
  header(name: string, value: string): void {
214
211
  // Before next(): delegate to shared RequestContext stub
215
212
  if (isPreNext()) {
@@ -0,0 +1,182 @@
1
+ /**
2
+ * Navigation Snapshot
3
+ *
4
+ * Pure data type representing the navigation-specific state for partial requests.
5
+ * Consolidates the header parsing, previous-route matching, intercept-context
6
+ * detection, and segment ID filtering that previously lived inline in
7
+ * createMatchContextForPartial (match-api.ts).
8
+ *
9
+ * resolveNavigation() is the factory: given a request + URL + current route key,
10
+ * it returns a NavigationSnapshot (or null if no previous URL).
11
+ */
12
+
13
+ import type { RouteMatchResult } from "./pattern-matching.js";
14
+
15
+ /**
16
+ * Snapshot of navigation state for a partial (navigation/action) request.
17
+ *
18
+ * Contains the "where are we coming from?" data: previous route, intercept
19
+ * source, client segment state, and derived flags.
20
+ */
21
+ export interface NavigationSnapshot {
22
+ /** Previous page URL (from X-RSC-Router-Client-Path or Referer) */
23
+ prevUrl: URL;
24
+ /** Params from the previous route match */
25
+ prevParams: Record<string, string>;
26
+ /** Previous route match result (null if prev URL doesn't match any route) */
27
+ prevMatch: RouteMatchResult | null;
28
+
29
+ /** URL used as intercept context source */
30
+ interceptContextUrl: URL;
31
+ /** Route match for the intercept context URL */
32
+ interceptContextMatch: RouteMatchResult | null;
33
+
34
+ /** Raw segment IDs the client currently has */
35
+ clientSegmentIds: string[];
36
+ /** Set version for O(1) lookup */
37
+ clientSegmentSet: Set<string>;
38
+ /** Segment IDs filtered to remove parallel (.@) and loader (D\d+.) entries */
39
+ filteredSegmentIds: string[];
40
+
41
+ /** Whether client considers its cache stale */
42
+ stale: boolean;
43
+
44
+ /** Whether the intercept context route is the same as the current route */
45
+ isSameRouteNavigation: boolean;
46
+
47
+ /** Effective "from" URL (intercept source URL when present, else prevUrl) */
48
+ effectiveFromUrl: URL;
49
+ /** Effective "from" match (intercept source match when present, else prevMatch) */
50
+ effectiveFromMatch: RouteMatchResult | null;
51
+
52
+ /** Whether an intercept source header was present */
53
+ hasInterceptSource: boolean;
54
+
55
+ /** Whether an HMR request header was present */
56
+ isHmr: boolean;
57
+ }
58
+
59
+ export interface ResolveNavigationDeps {
60
+ findMatch: (pathname: string) => RouteMatchResult | null;
61
+ }
62
+
63
+ /**
64
+ * Resolve navigation state from a partial request.
65
+ *
66
+ * Returns null if no previous URL is available (required for partial navigation).
67
+ *
68
+ * @param request - The incoming HTTP request
69
+ * @param url - Parsed URL of the request
70
+ * @param currentRouteKey - Route key of the current (target) route match
71
+ * @param deps - Dependencies (findMatch)
72
+ */
73
+ export function resolveNavigation(
74
+ request: Request,
75
+ url: URL,
76
+ currentRouteKey: string,
77
+ deps: ResolveNavigationDeps,
78
+ ): NavigationSnapshot | null {
79
+ // Parse client state from RSC request params/headers
80
+ const clientSegmentIds =
81
+ url.searchParams.get("_rsc_segments")?.split(",").filter(Boolean) || [];
82
+ const stale = url.searchParams.get("_rsc_stale") === "true";
83
+ const previousUrl =
84
+ request.headers.get("X-RSC-Router-Client-Path") ||
85
+ request.headers.get("Referer");
86
+ const interceptSourceUrl = request.headers.get(
87
+ "X-RSC-Router-Intercept-Source",
88
+ );
89
+ const isHmr = !!request.headers.get("X-RSC-HMR");
90
+
91
+ if (!previousUrl) {
92
+ return null;
93
+ }
94
+
95
+ // Parse previous URL
96
+ let prevUrl: URL;
97
+ try {
98
+ prevUrl = new URL(previousUrl, url.origin);
99
+ } catch {
100
+ return null;
101
+ }
102
+
103
+ // Parse intercept context URL
104
+ let interceptContextUrl: URL;
105
+ try {
106
+ interceptContextUrl = interceptSourceUrl
107
+ ? new URL(interceptSourceUrl, url.origin)
108
+ : prevUrl;
109
+ } catch {
110
+ interceptContextUrl = prevUrl;
111
+ }
112
+
113
+ // Match previous and intercept context routes
114
+ const prevMatch = deps.findMatch(prevUrl.pathname);
115
+ const prevParams = prevMatch?.params || {};
116
+ const interceptContextMatch = interceptSourceUrl
117
+ ? deps.findMatch(interceptContextUrl.pathname)
118
+ : prevMatch;
119
+
120
+ // Derived state
121
+ const isSameRouteNavigation = !!(
122
+ interceptContextMatch && interceptContextMatch.routeKey === currentRouteKey
123
+ );
124
+
125
+ const hasInterceptSource = !!interceptSourceUrl;
126
+ const effectiveFromUrl = hasInterceptSource ? interceptContextUrl : prevUrl;
127
+ const effectiveFromMatch = hasInterceptSource
128
+ ? interceptContextMatch
129
+ : prevMatch;
130
+
131
+ // Filter segment IDs: remove parallel (.@) and loader (D\d+.) entries
132
+ const filteredSegmentIds = clientSegmentIds.filter((id) => {
133
+ if (id.includes(".@")) return false;
134
+ if (/D\d+\./.test(id)) return false;
135
+ return true;
136
+ });
137
+
138
+ const clientSegmentSet = new Set(clientSegmentIds);
139
+
140
+ return {
141
+ prevUrl,
142
+ prevParams,
143
+ prevMatch,
144
+ interceptContextUrl,
145
+ interceptContextMatch,
146
+ clientSegmentIds,
147
+ clientSegmentSet,
148
+ filteredSegmentIds,
149
+ stale,
150
+ isSameRouteNavigation,
151
+ effectiveFromUrl,
152
+ effectiveFromMatch,
153
+ hasInterceptSource,
154
+ isHmr,
155
+ };
156
+ }
157
+
158
+ /**
159
+ * Test helper: create a NavigationSnapshot with sensible defaults and overrides.
160
+ */
161
+ export function createNavigationSnapshot(
162
+ overrides?: Partial<NavigationSnapshot>,
163
+ ): NavigationSnapshot {
164
+ const defaultUrl = new URL("http://localhost/");
165
+ return {
166
+ prevUrl: defaultUrl,
167
+ prevParams: {},
168
+ prevMatch: null,
169
+ interceptContextUrl: defaultUrl,
170
+ interceptContextMatch: null,
171
+ clientSegmentIds: [],
172
+ clientSegmentSet: new Set(),
173
+ filteredSegmentIds: [],
174
+ stale: false,
175
+ isSameRouteNavigation: false,
176
+ effectiveFromUrl: defaultUrl,
177
+ effectiveFromMatch: null,
178
+ hasInterceptSource: false,
179
+ isHmr: false,
180
+ ...overrides,
181
+ };
182
+ }
@@ -54,6 +54,9 @@ export async function matchForPrerender<TEnv = any>(
54
54
  deps: PrerenderMatchDeps<TEnv>,
55
55
  buildVars?: Record<string, any>,
56
56
  isPassthroughRoute?: boolean,
57
+ buildEnv?: TEnv,
58
+ /** Dev-only: check getParams() for passthrough routes to skip unknown params. */
59
+ devMode?: boolean,
57
60
  ): Promise<{
58
61
  segments: SerializedSegmentData[];
59
62
  handles: Record<string, SegmentHandleData>;
@@ -90,21 +93,106 @@ export async function matchForPrerender<TEnv = any>(
90
93
  entries.push(entry);
91
94
  }
92
95
 
96
+ // 3b. Dev-mode passthrough shortcut: if the route is a Passthrough route
97
+ // and has getParams(), check if the matched params are in the known list.
98
+ // In production, only known params are pre-rendered; unknown params fall
99
+ // through to the live handler. Mirror that behavior in dev mode to avoid
100
+ // rendering unknown params with build: true.
101
+ // Vars collected from getParams() probe — merged into render context below.
102
+ let devProbeBuildVars: Record<string, any> | undefined;
103
+
104
+ if (devMode && matchedPassthroughRoute) {
105
+ const routeEntry = entries.find(
106
+ (
107
+ e,
108
+ ): e is EntryData & {
109
+ type: "route";
110
+ prerenderDef: { getParams: (ctx: any) => Promise<any[]> | any[] };
111
+ } =>
112
+ e.type === "route" &&
113
+ !!(e as any).isPassthrough &&
114
+ !!(e as any).prerenderDef?.getParams,
115
+ );
116
+ if (routeEntry) {
117
+ try {
118
+ const probeBuildVars: Record<string, any> = {};
119
+ const knownParamsList = await routeEntry.prerenderDef.getParams({
120
+ build: true as const,
121
+ dev: true,
122
+ set: ((keyOrVar: any, value: any) => {
123
+ contextSet(probeBuildVars, keyOrVar, value);
124
+ }) as any,
125
+ reverse: createReverseFunction(deps.mergedRouteMap),
126
+ get env() {
127
+ if (buildEnv !== undefined) return buildEnv;
128
+ throw new Error(
129
+ "[rsc-router] ctx.env is not available during dev-mode getParams(). " +
130
+ "Configure buildEnv in your rango() plugin options to enable build-time env access.",
131
+ );
132
+ },
133
+ });
134
+ // Compare only the keys returned by getParams — ignore mount params
135
+ // from include() prefixes that aren't part of the handler's params.
136
+ const isKnown = knownParamsList.some((known: Record<string, any>) => {
137
+ const knownKeys = Object.keys(known);
138
+ return knownKeys.every(
139
+ (k) => String(known[k]) === String(matchedParams[k]),
140
+ );
141
+ });
142
+ if (!isKnown) {
143
+ return {
144
+ segments: [],
145
+ handles: {},
146
+ routeName: matched.routeKey,
147
+ params: matchedParams,
148
+ passthrough: true as const,
149
+ };
150
+ }
151
+ // Preserve vars set by getParams() for the render context
152
+ if (
153
+ Object.keys(probeBuildVars).length > 0 ||
154
+ Object.getOwnPropertySymbols(probeBuildVars).length > 0
155
+ ) {
156
+ devProbeBuildVars = probeBuildVars;
157
+ }
158
+ } catch (err: any) {
159
+ // Mirror production semantics (prerender-collection.ts):
160
+ // Skip errors are intentional — treat as passthrough.
161
+ // All other errors propagate so dev surfaces them.
162
+ if (err?.name === "Skip") {
163
+ return {
164
+ segments: [],
165
+ handles: {},
166
+ routeName: matched.routeKey,
167
+ params: matchedParams,
168
+ passthrough: true as const,
169
+ };
170
+ }
171
+ throw err;
172
+ }
173
+ }
174
+ }
175
+
93
176
  // 4. Create handle store for collecting handle data
94
177
  const handleStore = createHandleStore();
95
178
 
96
179
  // 5. Create a minimal request context with the handle store
97
- // Shallow-copy getParams vars so each param set is independent
98
- const variables: Record<string, any> = buildVars ? { ...buildVars } : {};
180
+ // Shallow-copy getParams vars so each param set is independent.
181
+ // In dev mode, merge vars from the getParams() probe if the caller
182
+ // didn't provide buildVars (production passes them from expandPrerenderRoutes).
183
+ const effectiveBuildVars = buildVars ?? devProbeBuildVars;
184
+ const variables: Record<string, any> = effectiveBuildVars
185
+ ? { ...effectiveBuildVars }
186
+ : {};
99
187
  const stubRes = new Response(null, { status: 200 });
100
188
  const minimalRequestContext: RequestContext<TEnv> = {
101
- env: {} as TEnv,
189
+ env: buildEnv ?? ({} as TEnv),
102
190
  request: new Request("http://prerender" + pathname),
103
191
  url: new URL("http://prerender" + pathname),
104
192
  originalUrl: new URL("http://prerender" + pathname),
105
193
  pathname,
106
194
  searchParams: new URLSearchParams(),
107
- var: variables,
195
+ _variables: variables,
108
196
  get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as any,
109
197
  set: ((keyOrVar: any, value: any) => {
110
198
  contextSet(variables, keyOrVar, value);
@@ -128,6 +216,8 @@ export async function matchForPrerender<TEnv = any>(
128
216
  _onResponseCallbacks: [],
129
217
  setLocationState() {},
130
218
  _locationState: undefined,
219
+ _renderBarrier: Promise.resolve(),
220
+ _resolveRenderBarrier: () => {},
131
221
  _reportedErrors: new WeakSet<object>(),
132
222
  reverse: createReverseFunction(
133
223
  deps.mergedRouteMap,
@@ -140,7 +230,7 @@ export async function matchForPrerender<TEnv = any>(
140
230
  return runWithRequestContext(minimalRequestContext, async () => {
141
231
  // 6. Create prerender context with synthetic URL.
142
232
  // Prerender handlers get params, pathname, url, searchParams, search,
143
- // reverse, and use(handle) but no request, env, headers, or cookies.
233
+ // reverse, use(handle), and optionally env (when buildEnv is configured).
144
234
  const buildCtx = createPrerenderContext<TEnv>(
145
235
  matchedParams,
146
236
  pathname,
@@ -148,6 +238,8 @@ export async function matchForPrerender<TEnv = any>(
148
238
  matched.routeKey,
149
239
  variables,
150
240
  matchedPassthroughRoute,
241
+ buildEnv,
242
+ devMode,
151
243
  );
152
244
 
153
245
  // 7. Wire use() for handles only (loaders throw)
@@ -320,6 +412,8 @@ export async function renderStaticSegment<TEnv = any>(
320
412
  handlerId: string,
321
413
  mergedRouteMap: Record<string, string>,
322
414
  routeName?: string,
415
+ buildEnv?: TEnv,
416
+ devMode?: boolean,
323
417
  ): Promise<{ encoded: string; handles: Record<string, unknown[]> } | null> {
324
418
  const syntheticUrl = new URL("http://prerender/");
325
419
  const syntheticRequest = new Request(syntheticUrl);
@@ -330,13 +424,13 @@ export async function renderStaticSegment<TEnv = any>(
330
424
  // Minimal request context so setupBuildUse can find the HandleStore
331
425
  const stubRes = new Response(null, { status: 200 });
332
426
  const minimalRequestContext: RequestContext<TEnv> = {
333
- env: {} as TEnv,
427
+ env: buildEnv ?? ({} as TEnv),
334
428
  request: syntheticRequest,
335
429
  url: syntheticUrl,
336
430
  originalUrl: syntheticUrl,
337
431
  pathname: "/",
338
432
  searchParams: syntheticUrl.searchParams,
339
- var: {},
433
+ _variables: {},
340
434
  get: () => undefined as any,
341
435
  set: () => {},
342
436
  params: {},
@@ -358,6 +452,8 @@ export async function renderStaticSegment<TEnv = any>(
358
452
  _onResponseCallbacks: [],
359
453
  setLocationState() {},
360
454
  _locationState: undefined,
455
+ _renderBarrier: Promise.resolve(),
456
+ _resolveRenderBarrier: () => {},
361
457
  _reportedErrors: new WeakSet<object>(),
362
458
  reverse: createReverseFunction(
363
459
  mergedRouteMap,
@@ -368,9 +464,13 @@ export async function renderStaticSegment<TEnv = any>(
368
464
  };
369
465
 
370
466
  return runWithRequestContext(minimalRequestContext, async () => {
371
- // Static handlers get only reverse and use(handle) no URL, params,
372
- // request, env, headers, or cookies.
373
- const buildCtx = createStaticContext<TEnv>(mergedRouteMap, routeName);
467
+ // Static handlers get only reverse, use(handle), and optionally env.
468
+ const buildCtx = createStaticContext<TEnv>(
469
+ mergedRouteMap,
470
+ routeName,
471
+ buildEnv,
472
+ devMode,
473
+ );
374
474
 
375
475
  // Set segment ID so handle pushes are keyed correctly
376
476
  (buildCtx as InternalHandlerContext<any, TEnv>)._currentSegmentId =
@@ -1,15 +1,9 @@
1
- import { loadManifest } from "./manifest.js";
2
- import { traverseBack } from "./pattern-matching.js";
3
- import { collectRouteMiddleware } from "./middleware.js";
4
- import {
5
- parseAcceptTypes,
6
- RSC_RESPONSE_TYPE,
7
- pickNegotiateVariant,
8
- } from "./content-negotiation.js";
1
+ import { negotiateRoute } from "./content-negotiation.js";
9
2
  import { runWithRouterLogContext, withRouterLogScope } from "./logging.js";
10
3
  import type { EntryData } from "../server/context";
11
4
  import type { RouteMatchResult } from "./pattern-matching.js";
12
5
  import type { MiddlewareFn } from "./middleware.js";
6
+ import { resolveRoute } from "./route-snapshot.js";
13
7
 
14
8
  export interface PreviewMatchDeps<TEnv = any> {
15
9
  findMatch: (pathname: string) => RouteMatchResult<TEnv> | null;
@@ -42,110 +36,44 @@ export async function previewMatch<TEnv = any>(
42
36
  const url = new URL(request.url);
43
37
  const pathname = url.pathname;
44
38
 
45
- // Quick route matching
46
- const matched = deps.findMatch(pathname);
47
- if (!matched) {
39
+ // Route resolution via snapshot (lite mode: skip entries/cacheScope
40
+ // since previewMatch only needs matched, manifestEntry, routeMiddleware,
41
+ // and responseType)
42
+ const result = await resolveRoute<TEnv>(pathname, {
43
+ findMatch: deps.findMatch,
44
+ lite: true,
45
+ });
46
+
47
+ if (!result) {
48
48
  return null;
49
49
  }
50
50
 
51
51
  // Skip redirect check - will be handled in full match
52
- if (matched.redirectTo) {
52
+ if (result.type === "redirect") {
53
53
  return { routeMiddleware: undefined };
54
54
  }
55
55
 
56
- // Load manifest (without segment resolution)
57
- const manifestEntry = await loadManifest(
58
- matched.entry,
59
- matched.routeKey,
60
- pathname,
61
- undefined, // No metrics store for preview
62
- false, // isSSR - doesn't matter for preview
63
- );
64
-
65
- // Collect route-level middleware from entry tree
66
- // Includes middleware from orphan layouts (inline layouts within routes)
67
- const routeMiddleware = collectRouteMiddleware(
68
- traverseBack(manifestEntry),
69
- matched.params,
70
- );
71
-
72
- // Check for response type (from trie match or manifest entry)
73
- const responseType =
74
- matched.responseType ||
75
- (manifestEntry.type === "route"
76
- ? manifestEntry.responseType
77
- : undefined);
78
-
79
- // Content negotiation: when negotiate variants exist, pick the best
80
- // handler based on the Accept header. Uses q-values and client order
81
- // as tiebreaker (matching Express/Hono behavior). RSC routes participate
82
- // as text/html candidates so browsers naturally get HTML without
83
- // special-casing.
84
- if (matched.negotiateVariants && matched.negotiateVariants.length > 0) {
85
- const acceptEntries = parseAcceptTypes(
86
- request.headers.get("accept") || "",
87
- );
88
-
89
- // Build candidate list preserving definition order.
90
- // For wildcard (*/*) and no-Accept fallback, the first candidate wins.
91
- const variants = matched.negotiateVariants;
92
- let candidates: Array<{ routeKey: string; responseType: string }>;
93
- if (responseType) {
94
- // Primary is response-type — include it as a candidate
95
- candidates = [
96
- ...variants,
97
- { routeKey: matched.routeKey, responseType },
98
- ];
99
- } else {
100
- // Primary is RSC — insert as text/html candidate in definition order
101
- const rscCandidate = {
102
- routeKey: matched.routeKey,
103
- responseType: RSC_RESPONSE_TYPE,
104
- };
105
- candidates = matched.rscFirst
106
- ? [rscCandidate, ...variants]
107
- : [...variants, rscCandidate];
108
- }
109
-
110
- const variant = pickNegotiateVariant(acceptEntries, candidates);
56
+ const snapshot = result.snapshot;
57
+ const { matched, manifestEntry, routeMiddleware, responseType } =
58
+ snapshot;
111
59
 
112
- // If the winner is RSC, fall through to default RSC handling
113
- if (variant.responseType === RSC_RESPONSE_TYPE) {
114
- // Fall through — RSC won negotiation
115
- } else if (responseType && variant.routeKey === matched.routeKey) {
116
- // Fall through — response-type primary won, already set
117
- } else {
118
- const negotiateEntry = await loadManifest(
119
- matched.entry,
120
- variant.routeKey,
121
- pathname,
122
- undefined,
123
- false,
124
- );
125
- // Recompute middleware from the selected variant's entry tree
126
- // since different variants can have different middleware chains.
127
- const variantMiddleware = collectRouteMiddleware(
128
- traverseBack(negotiateEntry),
129
- matched.params,
130
- );
131
- return {
132
- routeMiddleware:
133
- variantMiddleware.length > 0 ? variantMiddleware : undefined,
134
- responseType: variant.responseType,
135
- handler:
136
- negotiateEntry.type === "route"
137
- ? negotiateEntry.handler
138
- : undefined,
139
- params: matched.params,
140
- negotiated: true,
141
- manifestEntry: negotiateEntry,
142
- routeKey: matched.routeKey,
143
- };
144
- }
60
+ const negotiation = await negotiateRoute(request, pathname, snapshot);
61
+ if (negotiation) {
62
+ return {
63
+ routeMiddleware:
64
+ negotiation.routeMiddleware.length > 0
65
+ ? negotiation.routeMiddleware
66
+ : undefined,
67
+ responseType: negotiation.responseType,
68
+ handler: negotiation.handler,
69
+ params: matched.params,
70
+ negotiated: true,
71
+ manifestEntry: negotiation.manifestEntry,
72
+ routeKey: matched.routeKey,
73
+ };
145
74
  }
146
75
 
147
- // If we passed through the negotiation block (variants exist), mark as
148
- // negotiated so the handler sets Vary: Accept on the response.
76
+ // No negotiation or RSC won return default route info
149
77
  const hasVariants =
150
78
  matched.negotiateVariants && matched.negotiateVariants.length > 0;
151
79
  return {