@timber-js/app 0.2.0-alpha.242 → 0.2.0-alpha.243

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 (177) hide show
  1. package/dist/_chunks/{actions-BkwgRwCl.js → actions-DoTj0Jd3.js} +55 -37
  2. package/dist/_chunks/actions-DoTj0Jd3.js.map +1 -0
  3. package/dist/_chunks/als-registry-C-iwbtvI.js.map +1 -1
  4. package/dist/_chunks/{cache-api-BGA7c5qJ.js → cache-api-D3HmgsFh.js} +4 -4
  5. package/dist/_chunks/{cache-api-BGA7c5qJ.js.map → cache-api-D3HmgsFh.js.map} +1 -1
  6. package/dist/_chunks/{chains-Cuwwjv6T.js → chains-BpvDwp08.js} +2 -2
  7. package/dist/_chunks/{chains-Cuwwjv6T.js.map → chains-BpvDwp08.js.map} +1 -1
  8. package/dist/_chunks/chains-CjlZZ5ad.js +1 -0
  9. package/dist/_chunks/{classify-Y8S9C0Na.js → classify-Bbb_lKjH.js} +2 -2
  10. package/dist/_chunks/{classify-Y8S9C0Na.js.map → classify-Bbb_lKjH.js.map} +1 -1
  11. package/dist/_chunks/{cli-check-KeE1QaIx.js → cli-check-DlQBSKIN.js} +3 -3
  12. package/dist/_chunks/{cli-check-KeE1QaIx.js.map → cli-check-DlQBSKIN.js.map} +1 -1
  13. package/dist/_chunks/{cli-schema-sync-DZEF31wd.js → cli-schema-sync-CWkGFlYu.js} +2 -2
  14. package/dist/_chunks/{cli-schema-sync-DZEF31wd.js.map → cli-schema-sync-CWkGFlYu.js.map} +1 -1
  15. package/dist/_chunks/{cli-schema-sync-_y5O6MIg.js → cli-schema-sync-Dyvdkv_I.js} +1 -1
  16. package/dist/_chunks/{client-dep-entries-DpiwvoDi.js → client-dep-entries-Dka67elj.js} +2 -2
  17. package/dist/_chunks/{client-dep-entries-DpiwvoDi.js.map → client-dep-entries-Dka67elj.js.map} +1 -1
  18. package/dist/_chunks/{convention-lint-0AEsPK2T.js → convention-lint-CGGcseNn.js} +3 -3
  19. package/dist/_chunks/{convention-lint-0AEsPK2T.js.map → convention-lint-CGGcseNn.js.map} +1 -1
  20. package/dist/_chunks/dev-server-DrjLscqT.js +1 -0
  21. package/dist/_chunks/{dev-server-DYDr8KIc.js → dev-server-LO4McfQi.js} +3 -3
  22. package/dist/_chunks/{dev-server-DYDr8KIc.js.map → dev-server-LO4McfQi.js.map} +1 -1
  23. package/dist/_chunks/error-boundary-wuNvAJ4n.js.map +1 -1
  24. package/dist/_chunks/{flight-source-node-KQsX_OhS.js → flight-source-node-BeF00Wo_.js} +2 -2
  25. package/dist/_chunks/{flight-source-node-KQsX_OhS.js.map → flight-source-node-BeF00Wo_.js.map} +1 -1
  26. package/dist/_chunks/{interception-CtNt9jPt.js → interception-D1dCGNmQ.js} +6 -6
  27. package/dist/_chunks/{interception-CtNt9jPt.js.map → interception-D1dCGNmQ.js.map} +1 -1
  28. package/dist/_chunks/{json-lossy-check-BVDALqMf.js → json-lossy-check-DpXneTBm.js} +2 -2
  29. package/dist/_chunks/{json-lossy-check-BVDALqMf.js.map → json-lossy-check-DpXneTBm.js.map} +1 -1
  30. package/dist/_chunks/{live-graph-VhzO7Ol9.js → live-graph-DXhz6A_X.js} +4 -4
  31. package/dist/_chunks/{live-graph-VhzO7Ol9.js.map → live-graph-DXhz6A_X.js.map} +1 -1
  32. package/dist/_chunks/{logger-C4m8rfMy.js → logger-D1sWX2I0.js} +17 -2
  33. package/dist/_chunks/logger-D1sWX2I0.js.map +1 -0
  34. package/dist/_chunks/{node-response-8Vz29cGS.js → node-response-Cp62CtH1.js} +2 -2
  35. package/dist/_chunks/{node-response-8Vz29cGS.js.map → node-response-Cp62CtH1.js.map} +1 -1
  36. package/dist/_chunks/{poison-scan-Dpl3ibG-.js → poison-scan-DdkJoHvP.js} +2 -2
  37. package/dist/_chunks/{poison-scan-Dpl3ibG-.js.map → poison-scan-DdkJoHvP.js.map} +1 -1
  38. package/dist/_chunks/{scanner-CCEHN9Jg.js → scanner-B6V2RqqF.js} +20 -3
  39. package/dist/_chunks/scanner-B6V2RqqF.js.map +1 -0
  40. package/dist/_chunks/{sizeof-CIF7fwSJ.js → sizeof-BKA6qOZq.js} +2 -2
  41. package/dist/_chunks/{sizeof-CIF7fwSJ.js.map → sizeof-BKA6qOZq.js.map} +1 -1
  42. package/dist/_chunks/{walkers-BbotBhNG.js → walkers-BAZoAlfI.js} +3 -3
  43. package/dist/_chunks/{walkers-BbotBhNG.js.map → walkers-BAZoAlfI.js.map} +1 -1
  44. package/dist/adapters/cloudflare-kv-cache.js +1 -1
  45. package/dist/analyze/crawl-entry.js +3 -3
  46. package/dist/analyze/graph-command.js +2 -2
  47. package/dist/cache/index.js +2 -2
  48. package/dist/cache/stores/memory.js +1 -1
  49. package/dist/cli.js +3 -3
  50. package/dist/client/document-withdrawal.d.ts +2 -0
  51. package/dist/client/document-withdrawal.d.ts.map +1 -0
  52. package/dist/client/outlet-content-cache.d.ts +13 -1
  53. package/dist/client/outlet-content-cache.d.ts.map +1 -1
  54. package/dist/client/outlet-scope-context.d.ts +5 -0
  55. package/dist/client/outlet-scope-context.d.ts.map +1 -1
  56. package/dist/client/segment-outlet.d.ts.map +1 -1
  57. package/dist/config-types.d.ts +2 -1
  58. package/dist/config-types.d.ts.map +1 -1
  59. package/dist/index.js +7 -7
  60. package/dist/native/rsc/manifest.json +1 -0
  61. package/dist/native/rsc/server/als-registry.js.map +1 -1
  62. package/dist/native/rsc/server/cookie-context.js +7 -7
  63. package/dist/native/rsc/server/cookie-context.js.map +1 -1
  64. package/dist/native/rsc/server/deny-boundary.js +2 -1
  65. package/dist/native/rsc/server/deny-boundary.js.map +1 -1
  66. package/dist/native/rsc/server/dev-overlay-report.js +13 -0
  67. package/dist/native/rsc/server/dev-overlay-report.js.map +1 -0
  68. package/dist/native/rsc/server/logger.js +6 -1
  69. package/dist/native/rsc/server/logger.js.map +1 -1
  70. package/dist/native/rsc/server/pipeline-interception.js +4 -1
  71. package/dist/native/rsc/server/pipeline-interception.js.map +1 -1
  72. package/dist/native/rsc/server/pipeline.js.map +1 -1
  73. package/dist/native/rsc/server/request-context.js +4 -4
  74. package/dist/native/rsc/server/request-context.js.map +1 -1
  75. package/dist/native/rsc/server/segment-lifetime/read-rule.js +30 -19
  76. package/dist/native/rsc/server/segment-lifetime/read-rule.js.map +1 -1
  77. package/dist/native/rsc/server/segment-lifetime/read-scope.js +48 -7
  78. package/dist/native/rsc/server/segment-lifetime/read-scope.js.map +1 -1
  79. package/dist/native/rsc/server/slot-resolver.js +5 -4
  80. package/dist/native/rsc/server/slot-resolver.js.map +1 -1
  81. package/dist/native/rsc/server/slot-subtree-contain.js +2 -1
  82. package/dist/native/rsc/server/slot-subtree-contain.js.map +1 -1
  83. package/dist/native/rsc/server/subtree-walk.js +14 -5
  84. package/dist/native/rsc/server/subtree-walk.js.map +1 -1
  85. package/dist/native/rsc/server/vite-handoff-rsc.js.map +1 -1
  86. package/dist/native/ssr/client/document-withdrawal.js +17 -0
  87. package/dist/native/ssr/client/document-withdrawal.js.map +1 -0
  88. package/dist/native/ssr/client/outlet-content-cache.js +6 -1
  89. package/dist/native/ssr/client/outlet-content-cache.js.map +1 -1
  90. package/dist/native/ssr/client/outlet-scope-context.js.map +1 -1
  91. package/dist/native/ssr/client/segment-outlet.js +11 -2
  92. package/dist/native/ssr/client/segment-outlet.js.map +1 -1
  93. package/dist/native/ssr/manifest.json +5 -0
  94. package/dist/native/ssr/server/als-registry.js.map +1 -1
  95. package/dist/native/ssr/server/cookie-context.js +7 -7
  96. package/dist/native/ssr/server/cookie-context.js.map +1 -1
  97. package/dist/native/ssr/server/deny-boundary.js +2 -1
  98. package/dist/native/ssr/server/deny-boundary.js.map +1 -1
  99. package/dist/native/ssr/server/dev-overlay-report.js +6 -0
  100. package/dist/native/ssr/server/dev-overlay-report.js.map +1 -0
  101. package/dist/native/ssr/server/logger.js +6 -1
  102. package/dist/native/ssr/server/logger.js.map +1 -1
  103. package/dist/native/ssr/server/pipeline-interception.js +4 -1
  104. package/dist/native/ssr/server/pipeline-interception.js.map +1 -1
  105. package/dist/native/ssr/server/pipeline.js.map +1 -1
  106. package/dist/native/ssr/server/request-context.js +4 -4
  107. package/dist/native/ssr/server/request-context.js.map +1 -1
  108. package/dist/native/ssr/server/segment-lifetime/outlet-gate.js +11 -0
  109. package/dist/native/ssr/server/segment-lifetime/outlet-gate.js.map +1 -0
  110. package/dist/native/ssr/server/segment-lifetime/read-rule.js +30 -19
  111. package/dist/native/ssr/server/segment-lifetime/read-rule.js.map +1 -1
  112. package/dist/native/ssr/server/segment-lifetime/read-scope.js +16 -0
  113. package/dist/native/ssr/server/segment-lifetime/read-scope.js.map +1 -0
  114. package/dist/native/ssr/server/subtree-walk.js +149 -0
  115. package/dist/native/ssr/server/subtree-walk.js.map +1 -0
  116. package/dist/native/ssr/server/utils/element-type.js +21 -9
  117. package/dist/native/ssr/server/utils/element-type.js.map +1 -1
  118. package/dist/native/ssr/server/vite-handoff-rsc.js.map +1 -1
  119. package/dist/routing/index.js +3 -3
  120. package/dist/routing/slot-placement.d.ts +23 -4
  121. package/dist/routing/slot-placement.d.ts.map +1 -1
  122. package/dist/server/als-registry.d.ts +18 -0
  123. package/dist/server/als-registry.d.ts.map +1 -1
  124. package/dist/server/deny-boundary.d.ts.map +1 -1
  125. package/dist/server/dev-overlay-report.d.ts +13 -0
  126. package/dist/server/dev-overlay-report.d.ts.map +1 -0
  127. package/dist/server/index.js +2 -2
  128. package/dist/server/internal.js +97 -8
  129. package/dist/server/internal.js.map +1 -1
  130. package/dist/server/logger.d.ts +10 -0
  131. package/dist/server/logger.d.ts.map +1 -1
  132. package/dist/server/pipeline-interception.d.ts.map +1 -1
  133. package/dist/server/pipeline.d.ts +13 -1
  134. package/dist/server/pipeline.d.ts.map +1 -1
  135. package/dist/server/rsc-entry/index.d.ts.map +1 -1
  136. package/dist/server/segment-lifetime/read-rule.d.ts +14 -18
  137. package/dist/server/segment-lifetime/read-rule.d.ts.map +1 -1
  138. package/dist/server/segment-lifetime/read-scope.d.ts +47 -6
  139. package/dist/server/segment-lifetime/read-scope.d.ts.map +1 -1
  140. package/dist/server/segment-lifetime/slot-outlets.d.ts +1 -1
  141. package/dist/server/slot-resolver.d.ts.map +1 -1
  142. package/dist/server/slot-subtree-contain.d.ts.map +1 -1
  143. package/dist/server/subtree-walk.d.ts +17 -3
  144. package/dist/server/subtree-walk.d.ts.map +1 -1
  145. package/dist/server/vite-handoff-rsc.d.ts +2 -0
  146. package/dist/server/vite-handoff-rsc.d.ts.map +1 -1
  147. package/docs/api/34-api-config.mdx +1 -1
  148. package/package.json +1 -1
  149. package/src/client/document-withdrawal.tsx +41 -0
  150. package/src/client/outlet-content-cache.ts +18 -2
  151. package/src/client/outlet-scope-context.ts +5 -0
  152. package/src/client/segment-outlet.tsx +9 -3
  153. package/src/config-types.ts +2 -1
  154. package/src/routing/interception.ts +5 -5
  155. package/src/routing/slot-placement.ts +41 -4
  156. package/src/server/als-registry.ts +14 -0
  157. package/src/server/cookie-context.ts +7 -7
  158. package/src/server/deny-boundary.ts +4 -1
  159. package/src/server/dev-overlay-report.ts +22 -0
  160. package/src/server/logger.ts +13 -0
  161. package/src/server/pipeline-interception.ts +11 -2
  162. package/src/server/pipeline.ts +13 -1
  163. package/src/server/request-context.ts +6 -6
  164. package/src/server/route-element-builder.ts +2 -2
  165. package/src/server/rsc-entry/index.ts +7 -0
  166. package/src/server/segment-lifetime/read-rule.ts +62 -31
  167. package/src/server/segment-lifetime/read-scope.ts +128 -14
  168. package/src/server/segment-lifetime/slot-outlets.ts +1 -1
  169. package/src/server/slot-resolver.ts +22 -10
  170. package/src/server/slot-subtree-contain.ts +2 -1
  171. package/src/server/subtree-walk.ts +34 -9
  172. package/src/server/vite-handoff-rsc.ts +2 -0
  173. package/dist/_chunks/actions-BkwgRwCl.js.map +0 -1
  174. package/dist/_chunks/chains-LGjBHfSN.js +0 -1
  175. package/dist/_chunks/dev-server-CboXr8zX.js +0 -1
  176. package/dist/_chunks/logger-C4m8rfMy.js.map +0 -1
  177. package/dist/_chunks/scanner-CCEHN9Jg.js.map +0 -1
@@ -12,7 +12,7 @@
12
12
  * smuggling primitive that the encoding contract closes.
13
13
  */
14
14
 
15
- import { assertCookieRead, assertUnscopedRead } from './segment-lifetime/read-rule.ts';
15
+ import { checkCookieRead, checkUnscopedRead } from './segment-lifetime/read-rule.ts';
16
16
  import { COOKIE_READ_THROUGH, type CookieReadThrough } from '../shared/cookie-read-through.ts';
17
17
  import { requestContextAls, type RequestContextStore } from './als-registry.ts';
18
18
  import { isDebug } from './debug.ts';
@@ -80,29 +80,29 @@ export function getCookieJar(): RequestCookies {
80
80
  // warn if React.cache may have memoized the old value (TIM-1529 D3).
81
81
  // Inside a 'document' segment, only the cookies in its key (design/53).
82
82
  get(name: string): string | undefined {
83
- assertCookieRead(name);
83
+ checkCookieRead(name);
84
84
  noteCookieReadForReactCache(name);
85
85
  return map.get(name);
86
86
  },
87
87
  // A typed definition's read: allowed for a keyed cookie read through the
88
88
  // key's own definition (shared/cookie-read-through.ts).
89
89
  [COOKIE_READ_THROUGH](name: string, codec: unknown): string | undefined {
90
- assertCookieRead(name, codec);
90
+ checkCookieRead(name, codec);
91
91
  noteCookieReadForReactCache(name);
92
92
  return map.get(name);
93
93
  },
94
94
  has(name: string): boolean {
95
- assertCookieRead(name);
95
+ checkCookieRead(name);
96
96
  noteCookieReadForReactCache(name);
97
97
  return map.has(name);
98
98
  },
99
99
  getAll(): Array<{ name: string; value: string }> {
100
- assertUnscopedRead('every cookie');
100
+ checkUnscopedRead('every cookie');
101
101
  noteCookieReadForReactCache(ANY_COOKIE);
102
102
  return Array.from(map.entries()).map(([name, value]) => ({ name, value }));
103
103
  },
104
104
  get size(): number {
105
- assertUnscopedRead('the number of cookies');
105
+ checkUnscopedRead('the number of cookies');
106
106
  noteCookieReadForReactCache(ANY_COOKIE);
107
107
  return map.size;
108
108
  },
@@ -248,7 +248,7 @@ export function getCookieJar(): RequestCookies {
248
248
  },
249
249
 
250
250
  toString(): string {
251
- assertUnscopedRead('every cookie');
251
+ checkUnscopedRead('every cookie');
252
252
  noteCookieReadForReactCache(ANY_COOKIE);
253
253
  // Re-encode values when serializing as a Cookie header — the
254
254
  // RYW map holds decoded logical values, but a Cookie header has
@@ -43,6 +43,7 @@ import { isDenySignal } from './signal-identity.ts';
43
43
  import { loadFallbackModule } from './pipeline-helpers.ts';
44
44
  import type { ManifestLoader } from './safe-load.ts';
45
45
  import { withSpan } from './tracing.ts';
46
+ import { fallbackAfter } from './segment-lifetime/read-scope.ts';
46
47
  import { isValidElementType, type LoadedComponent } from './utils/element-type.ts';
47
48
  import type { ManifestSegmentNode } from './route-matcher.ts';
48
49
 
@@ -426,7 +427,9 @@ export function handleCaughtDeny(
426
427
 
427
428
  if (placement?.kind === 'render') {
428
429
  setDenyStatus(error.status);
429
- return placement.element;
430
+ // A deny from a 'document' segment that read outside its key: the page
431
+ // must not be kept under the key digest (design/53 §"Reads outside the key").
432
+ return fallbackAfter(error, placement.element);
430
433
  }
431
434
  if (placement?.kind === 'hoist') {
432
435
  setDenyStatus(error.status);
@@ -0,0 +1,22 @@
1
+ /**
2
+ * Reports a problem the request survived to the dev server's error overlay.
3
+ *
4
+ * The dev server hands the RSC entry its overlay through `setDevHooks`
5
+ * (`plugins/dev-server.ts`); the entry sets the reporter here, so render code
6
+ * that cannot see the entry can still report. Unset in production, in tests,
7
+ * and under any server that is not timber's dev server: the caller logs instead.
8
+ */
9
+
10
+ let reporter: ((error: Error) => void) | undefined;
11
+
12
+ /** Set (or clear) the reporter. Called by the RSC entry's `setDevHooks`. */
13
+ export function setDevOverlayReporter(report: ((error: Error) => void) | undefined): void {
14
+ reporter = report;
15
+ }
16
+
17
+ /** Report `error` to the overlay; false when no dev server is listening. */
18
+ export function reportToDevOverlay(error: Error): boolean {
19
+ if (!reporter) return false;
20
+ reporter(error);
21
+ return true;
22
+ }
@@ -11,6 +11,7 @@
11
11
  import { generateTraceId, getTraceStore } from './tracing.ts';
12
12
  import { createDefaultLogger } from './default-logger.ts';
13
13
  import { isDevMode } from './debug.ts';
14
+ import { reportToDevOverlay } from './dev-overlay-report.ts';
14
15
  import { isControlFlowSignal } from './signal-identity.ts';
15
16
  import type { CsrfRejectReason } from './csrf.ts';
16
17
 
@@ -86,6 +87,18 @@ export function logCsrfRejected(
86
87
  _logger.warn(`CSRF origin check failed: ${detail}`, fields);
87
88
  }
88
89
 
90
+ /**
91
+ * Report a `'document'` segment's read outside its key. The render survives
92
+ * it: the segment degrades to `'request'` for the client that rendered it
93
+ * (design/53-segment-lifetime.md §"Reads outside the key"). Under the dev
94
+ * server it goes to the error overlay, which also prints it; otherwise it is
95
+ * logged at warn, and this line is the only sign the key is wrong.
96
+ */
97
+ export function logDocumentReadOutsideKey(error: Error, data: { segment: string }): void {
98
+ if (reportToDevOverlay(error)) return;
99
+ _logger.warn(error.message, withTraceContext(data));
100
+ }
101
+
89
102
  /** Log a completed request. Level: info. */
90
103
  export function logRequestCompleted(data: {
91
104
  method: string;
@@ -258,7 +258,7 @@ export function resolveInterceptedRoute(
258
258
  // `[…owner ancestors, interceptingNode, …descendants]`, which renders
259
259
  // as an ordinary route. `interception` stays unset — there is no slot
260
260
  // to intercept into, and setting it would additionally arm the modal
261
- // path for every slot in the tree we are about to render.
261
+ // path for the owner's slots, which the swap does not render into.
262
262
  //
263
263
  // A null here means the scope named nothing in this manifest, or no
264
264
  // intercepting child matched the target. Both fall through to the
@@ -278,12 +278,21 @@ export function resolveInterceptedRoute(
278
278
  // a valid tree: the rewrite hijacks the navigation and no slot exists
279
279
  // to render the intercepting page. Fall through to the canonical
280
280
  // target route instead.
281
+ //
282
+ // Passing through the scope is enough: the owner is then on the chain
283
+ // with its layout, because the build rejects a slot whose owner has no
284
+ // layout (`validateSlotPlacement`, TIM-1443) — and only the winning
285
+ // owner's slots intercept, so a winner that could not resolve its
286
+ // slots would render the source page with no modal at all.
281
287
  const rendersTheSlot =
282
288
  sourceMatch !== null &&
283
289
  computeSegmentTreePaths(sourceMatch.segments).includes(rewrite.interceptingScope);
284
290
  if (rendersTheSlot) {
285
291
  match = sourceMatch;
286
- interception = { targetPathname: canonicalPathname };
292
+ interception = {
293
+ targetPathname: canonicalPathname,
294
+ interceptingScope: rewrite.interceptingScope,
295
+ };
287
296
  }
288
297
  }
289
298
  }
@@ -99,10 +99,22 @@ export type MetadataRouteMatcher = (
99
99
  pathname: string
100
100
  ) => import('./route-matcher.ts').MetadataRouteMatch | null;
101
101
 
102
- /** Context for intercepting route resolution (modal pattern). */
102
+ /**
103
+ * The pipeline's decision for a modal-shape interception — which rewrite won,
104
+ * stated once, for the slot resolver to consume rather than re-derive.
105
+ */
103
106
  export interface InterceptionContext {
104
107
  /** The URL the user is navigating TO (the intercepted route). */
105
108
  targetPathname: string;
109
+ /**
110
+ * The winning rewrite's `interceptingScope`: the tree path of the segment
111
+ * whose slots hold the interception. Only that owner's slots intercept. The
112
+ * re-matched chain can pass through other owners with interceptors for the
113
+ * same URL — `app/@modal/(...)photo` above `app/feed/@modal/(..)photo` —
114
+ * and those lost the deepest-scope ranking, so they render as on any other
115
+ * navigation (TIM-1443, design/07-routing.md §"Selection Between Owners").
116
+ */
117
+ interceptingScope: string;
106
118
  }
107
119
 
108
120
  /** Function that renders a matched route into a Response. */
@@ -34,8 +34,8 @@ import {
34
34
  import { isDebug } from './debug.ts';
35
35
  import { runWithReactCacheScope, type ReactCacheScope } from './react-cache-scope.ts';
36
36
  import {
37
- assertSearchParamsRead,
38
- assertUnscopedRead,
37
+ checkSearchParamsRead,
38
+ checkUnscopedRead,
39
39
  currentReadScope,
40
40
  keyedHeaders,
41
41
  scopedParams,
@@ -99,8 +99,8 @@ export function getSearchParams(reader?: SearchParamsReader): URLSearchParams {
99
99
  }
100
100
  // A definition's `.get()` passes what it parses; a 'document' segment may
101
101
  // read only fields its key reads the same way, and never the raw params.
102
- if (reader) assertSearchParamsRead(reader);
103
- else assertUnscopedRead('the raw search params');
102
+ if (reader) checkSearchParamsRead(reader);
103
+ else checkUnscopedRead('the raw search params');
104
104
 
105
105
  return store.searchParams;
106
106
  }
@@ -149,7 +149,7 @@ export function getSegmentParams(segmentPath?: string): CoercedParams {
149
149
  // client's useSegmentParams() also reads, so the two halves of one
150
150
  // documented API cannot drift (TIM-1285).
151
151
  const slotResolved = resolveSegmentParams(store.segmentParams, store.slotParams, segmentPath);
152
- // Inside a 'document' segment, a param outside its key throws (design/53).
152
+ // Inside a 'document' segment, a param outside its key is refused (design/53).
153
153
  if (slotResolved !== store.segmentParams) return scopedParams(slotResolved);
154
154
 
155
155
  // Dev-mode validation: warn when the segment path expects dynamic
@@ -342,7 +342,7 @@ export function getRequestSearchString(): string {
342
342
  const store = requestContextAls.getStore();
343
343
  // A 'document' segment's redirect cannot carry search params outside its
344
344
  // key (design/53): what it redirects to would freeze.
345
- if (store) assertUnscopedRead('the raw search params');
345
+ if (store) checkUnscopedRead('the raw search params');
346
346
  return store?.searchString ?? '';
347
347
  }
348
348
 
@@ -237,8 +237,8 @@ export async function buildRouteElement(
237
237
  // compares against. One derivation, so a slot cannot be keyed two ways.
238
238
  const segmentTreePaths = computeSegmentTreePaths(segments);
239
239
 
240
- // A 'document' page runs in its read scope: a read outside its key throws
241
- // (segment-lifetime/read-scope.ts). A client page never runs on the server.
240
+ // A 'document' page runs in its read scope: a read outside its key is
241
+ // refused (segment-lifetime/read-scope.ts). A client page never runs on the server.
242
242
  const PageComponent =
243
243
  documentLifetimes.page && !isClientReference(LoadedPage)
244
244
  ? inReadScope(
@@ -92,8 +92,10 @@ import { StatusPageMarker } from '../../client/status-page-marker.tsx';
92
92
  import { SlotOutlet } from '../../client/slot-outlet.tsx';
93
93
  import { SlotsProvider } from '../../client/slot-provider.tsx';
94
94
  import { DenyLastResort } from '../../client/deny-last-resort.tsx';
95
+ import { DocumentWithdrawal } from '../../client/document-withdrawal.tsx';
95
96
  import { provideRscViteHandoff } from '../vite-handoff-rsc.ts';
96
97
  import { markRouteModulesImmutable } from '../safe-load.ts';
98
+ import { setDevOverlayReporter } from '../dev-overlay-report.ts';
97
99
 
98
100
  // Before anything can render: the runtime reads these at call and render
99
101
  // time through server/vite-handoff-rsc.ts (design/51-native-dev-runtime.md).
@@ -117,6 +119,7 @@ provideRscViteHandoff({
117
119
  SlotOutlet,
118
120
  SlotsProvider,
119
121
  DenyLastResort,
122
+ DocumentWithdrawal,
120
123
  },
121
124
  });
122
125
 
@@ -145,6 +148,10 @@ let devHooks: DevHooks = {};
145
148
  */
146
149
  export function setDevHooks(hooks: DevHooks): void {
147
150
  devHooks = hooks;
151
+ // Problems a render survives (a 'document' segment's read outside its key)
152
+ // reach the overlay without failing the request.
153
+ const { onPipelineError } = hooks;
154
+ setDevOverlayReporter(onPipelineError && ((error) => onPipelineError(error, 'render')));
148
155
  }
149
156
 
150
157
  /**
@@ -3,6 +3,12 @@
3
3
  * segment's read scope (`read-scope.ts`, design/53-segment-lifetime.md §"What
4
4
  * a 'document' segment may read"). No React and no render machinery: the
5
5
  * accessors in `request-context.ts` and `cookie-context.ts` import this.
6
+ *
7
+ * A read outside the key is detected and reported in every environment: the
8
+ * dev server's error overlay, or a warning in the log. The read returns its
9
+ * real value, and the component call that read is marked, so its output
10
+ * withdraws the segment from the client (`read-scope.ts`) and the segment renders
11
+ * as `'request'` for that client from then on (design/53 §"Reads outside the key").
6
12
  */
7
13
 
8
14
  import { documentReadScopeAls, type DocumentReadScope } from '../als-registry.ts';
@@ -10,6 +16,7 @@ import type { CoercedParams } from '../../shared/param-value.ts';
10
16
  import type { SearchParamsReader } from '../../shared/als-slots.ts';
11
17
  import type { ReadonlyHeaders } from '../request-context.ts';
12
18
  import { isUnkeyableHeader } from '../../shared/key-headers.ts';
19
+ import { logDocumentReadOutsideKey } from '../logger.ts';
13
20
 
14
21
  /** The read scope the current render runs in, if it is a `'document'` segment's. */
15
22
  export function currentReadScope(): DocumentReadScope | undefined {
@@ -20,15 +27,37 @@ export function currentReadScope(): DocumentReadScope | undefined {
20
27
  type KeyPart = 'segmentParams' | 'searchParams' | 'cookies' | 'headers';
21
28
 
22
29
  /**
23
- * The error for a read outside the key. Names the segment, what was read, and
24
- * the fix: add it to the key, or make the segment `'request'`.
30
+ * Refuse a read outside the key: mark the component call that made it, report
31
+ * it once per segment render (naming the segment, what was read and the fix:
32
+ * add it to the key, or make the segment `'request'`), and return, so the
33
+ * caller performs the read.
25
34
  */
26
- export function readOutsideKey(
35
+ function refuseRead(
27
36
  scope: DocumentReadScope,
28
37
  what: string,
29
38
  part?: KeyPart,
30
39
  /** Overrides the fix when adding the read to the key is not possible. */
31
40
  fixOverride?: string
41
+ ): void {
42
+ // A view (`keyedHeaders`, `scopedParams`) keeps the scope it was made in,
43
+ // and can be handed to a component that reads through it later: the call
44
+ // reading now is the one whose output carries the value, so it is marked
45
+ // too (codex on #1317).
46
+ scope.call.read = true;
47
+ const active = currentReadScope();
48
+ if (active) active.call.read = true;
49
+ if (scope.reported.done) return;
50
+ scope.reported.done = true;
51
+ logDocumentReadOutsideKey(readOutsideKey(scope, what, part, fixOverride), {
52
+ segment: scope.segmentPath,
53
+ });
54
+ }
55
+
56
+ function readOutsideKey(
57
+ scope: DocumentReadScope,
58
+ what: string,
59
+ part?: KeyPart,
60
+ fixOverride?: string
32
61
  ): Error {
33
62
  const fix =
34
63
  fixOverride ??
@@ -39,14 +68,15 @@ export function readOutsideKey(
39
68
  `[timber] ${scope.segmentPath} is lifetime: 'document' (declared, or from defaultLayoutLifetime) ` +
40
69
  `and read ${what}, which is not in its key. ` +
41
70
  `${fix} The segment is skipped without rendering while its key is unchanged, so the read ` +
42
- `would freeze at its first value. See design/53-segment-lifetime.md ` +
71
+ `would freeze at its first value; until it is fixed, it renders as lifetime: 'request' ` +
72
+ `for this client instead. See design/53-segment-lifetime.md ` +
43
73
  `§"What a 'document' segment may read".`
44
74
  );
45
75
  }
46
76
 
47
77
  /**
48
78
  * The request headers as a `'document'` segment may read them: `get` and
49
- * `has` of a header in its key. Any other name throws, and so does reading
79
+ * `has` of a header in its key. Any other name is refused, and so is reading
50
80
  * them all (iteration, `entries`, `forEach`), which could see headers the
51
81
  * key leaves out — the pathname among them.
52
82
  */
@@ -55,56 +85,58 @@ export function keyedHeaders(headers: ReadonlyHeaders, scope: DocumentReadScope)
55
85
  if (scope.headers.has(name.toLowerCase())) return name;
56
86
  const what = `the header "${name}"`;
57
87
  if (name.toLowerCase() === 'cookie') {
58
- throw readOutsideKey(
88
+ refuseRead(
59
89
  scope,
60
90
  what,
61
91
  'cookies',
62
92
  'Read cookies through a cookie definition in key.cookies.'
63
93
  );
64
- }
65
- if (isUnkeyableHeader(name)) {
66
- throw readOutsideKey(
94
+ } else if (isUnkeyableHeader(name)) {
95
+ refuseRead(
67
96
  scope,
68
97
  what,
69
98
  undefined,
70
99
  "A key may not name a credential; declare lifetime: 'request'."
71
100
  );
101
+ } else {
102
+ refuseRead(scope, what, 'headers');
72
103
  }
73
- throw readOutsideKey(scope, what, 'headers');
104
+ return name;
74
105
  };
75
- const all = (): never => {
76
- throw readOutsideKey(
106
+ const all = (): ReadonlyHeaders => {
107
+ refuseRead(
77
108
  scope,
78
109
  'every request header',
79
110
  undefined,
80
111
  "Read each header you need with getHeaders().get(name) and add it to key.headers, or declare lifetime: 'request'."
81
112
  );
113
+ return headers;
82
114
  };
83
115
  return {
84
116
  get: (name) => headers.get(keyed(name)),
85
117
  has: (name) => headers.has(keyed(name)),
86
- entries: all,
87
- keys: all,
88
- values: all,
89
- forEach: all,
90
- [Symbol.iterator]: all,
118
+ entries: () => all().entries(),
119
+ keys: () => all().keys(),
120
+ values: () => all().values(),
121
+ forEach: (callback, thisArg) => all().forEach(callback, thisArg),
122
+ [Symbol.iterator]: () => all()[Symbol.iterator](),
91
123
  };
92
124
  }
93
125
 
94
- /** Throw if the current render may not read `what` at all (raw search params). */
95
- export function assertUnscopedRead(what: string): void {
126
+ /** Refuse the read if the current render may not read `what` at all (raw search params). */
127
+ export function checkUnscopedRead(what: string): void {
96
128
  const scope = currentReadScope();
97
- if (scope) throw readOutsideKey(scope, what);
129
+ if (scope) refuseRead(scope, what);
98
130
  }
99
131
 
100
132
  /**
101
- * Throw if the current render reads search-param fields outside its key. A
133
+ * Refuse the read if the current render reads search-param fields outside its key. A
102
134
  * field is in the key only when the key's definition reads it through the
103
135
  * same codec and URL key — a `.pick()` of the keyed definition, or the keyed
104
136
  * definition itself. Another definition with a field of the same name may map
105
137
  * it to another URL parameter or parse it differently.
106
138
  */
107
- export function assertSearchParamsRead(reader: SearchParamsReader): void {
139
+ export function checkSearchParamsRead(reader: SearchParamsReader): void {
108
140
  const scope = currentReadScope();
109
141
  if (!scope) return;
110
142
  const outside = Object.keys(reader.codecs).filter((field) => {
@@ -116,24 +148,23 @@ export function assertSearchParamsRead(reader: SearchParamsReader): void {
116
148
  );
117
149
  });
118
150
  if (outside.length > 0) {
119
- throw readOutsideKey(scope, `the search params ${outside.join(', ')}`, 'searchParams');
151
+ refuseRead(scope, `the search params ${outside.join(', ')}`, 'searchParams');
120
152
  }
121
153
  }
122
154
 
123
155
  /**
124
- * Throw if the current render reads a cookie outside its key. A keyed cookie
156
+ * Refuse the read if the current render reads a cookie outside its key. A keyed cookie
125
157
  * is in the key only as its definition parses it, so it may be read only
126
158
  * through that definition (`codec` is the reader's); a raw read, or another
127
159
  * definition of the same name, could see a difference the key does not.
128
160
  */
129
- export function assertCookieRead(name: string, codec?: unknown): void {
161
+ export function checkCookieRead(name: string, codec?: unknown): void {
130
162
  const scope = currentReadScope();
131
163
  if (!scope) return;
132
164
  if (!scope.cookies.has(name)) {
133
- throw readOutsideKey(scope, `the cookie "${name}"`, 'cookies');
134
- }
135
- if (codec === undefined || scope.cookies.get(name) !== codec) {
136
- throw readOutsideKey(
165
+ refuseRead(scope, `the cookie "${name}"`, 'cookies');
166
+ } else if (codec === undefined || scope.cookies.get(name) !== codec) {
167
+ refuseRead(
137
168
  scope,
138
169
  `the raw value of the cookie "${name}" (read it through the definition in its key)`,
139
170
  'cookies'
@@ -157,7 +188,7 @@ const OBJECT_PROBES: ReadonlySet<string> = new Set([
157
188
  ]);
158
189
 
159
190
  /**
160
- * The params a scoped render sees: reading one outside the key throws. Its
191
+ * The params a scoped render sees: reading one outside the key is refused. Its
161
192
  * own keys are only the params in the key, so spreading it, or passing it to
162
193
  * a client component, carries exactly what the segment may depend on.
163
194
  */
@@ -181,7 +212,7 @@ export function scopedParams<T extends CoercedParams>(params: T): T {
181
212
  return new Proxy(target, {
182
213
  get(target, name, receiver) {
183
214
  if (refused(name)) {
184
- throw readOutsideKey(scope, `the segment param "${String(name)}"`, 'segmentParams');
215
+ refuseRead(scope, `the segment param "${String(name)}"`, 'segmentParams');
185
216
  }
186
217
  return Reflect.get(target, name, receiver);
187
218
  },
@@ -5,14 +5,16 @@
5
5
  *
6
6
  * A `'document'` segment is skipped without rendering whenever its key is
7
7
  * unchanged, so anything else it read would freeze silently at its load-time
8
- * value. The rule makes that a thrown error instead, in every environment:
8
+ * value. The rule detects that in every environment, reports it (the dev
9
+ * overlay, or a warning in the log), and degrades the segment to `'request'`
10
+ * for the client (below). What it refuses:
9
11
  *
10
- * - `getSegmentParams()` returns a view that throws on a param outside the key;
11
- * - a search-params definition's `.get()` throws unless every field it reads is
12
- * in the key's definition, and the raw search params throw;
13
- * - the cookie jar throws on a cookie outside the key, and on `getAll()`;
12
+ * - `getSegmentParams()` returns a view that refuses a param outside the key;
13
+ * - a search-params definition's `.get()` is refused unless every field it
14
+ * reads is in the key's definition, and so are the raw search params;
15
+ * - the cookie jar refuses a cookie outside the key, and `getAll()`;
14
16
  * - `getHeaders()` reads only the headers in the key; any other header, and
15
- * iterating them all, throws — and with that the pathname, which no timber
17
+ * iterating them all, is refused — and with that the pathname, which no timber
16
18
  * API exposes to a component except through a header.
17
19
  *
18
20
  * **Reach.** The scope is an AsyncLocalStorage scope around the segment's
@@ -26,13 +28,50 @@
26
28
  * Not covered: values computed outside this render and handed to it — a
27
29
  * `timber.cache` entry an earlier request filled, or a module-level value. The
28
30
  * accessors' checks are `read-rule.ts`.
31
+ *
32
+ * **Degrading.** The read rule reports a refused read, lets it return its
33
+ * real value and marks the component call that made it: each scoped call runs
34
+ * in its own copy of the scope, with a fresh `call` record. The render has
35
+ * already sent the outlet's key digest (the outlet decides before the segment
36
+ * renders), so the content withdraws itself instead: when a call that read
37
+ * outside the key returns, its output gets a `DocumentWithdrawal` marker. The
38
+ * marker sits beside what the read produced, so the client commits it exactly
39
+ * when it commits that content — not in a Suspense fallback or an unrendered
40
+ * prop another component happened to finish in. When it commits, the client
41
+ * drops the segment's entry and records none for that outlet for the rest of
42
+ * the document (`client/outlet-content-cache.ts`). The client never advertises
43
+ * a digest for it again, so every later navigation renders it live —
44
+ * `'request'` for that client.
45
+ *
46
+ * A call that reads and then throws has no output to mark. Its error is
47
+ * remembered, and each catcher that renders a fallback in its place inside an
48
+ * outlet (a deny page, a slot's `default.tsx`) passes the fallback through
49
+ * `fallbackAfter`, which marks it. The marker withdraws whichever outlet the
50
+ * fallback lands in.
51
+ *
52
+ * An async iterable the call returned is advanced later, in a call record of
53
+ * its own; the first chunk it yields after a read carries the marker, or, for
54
+ * a read on its closing step, a last chunk of the marker alone.
55
+ *
56
+ * A scoped view (`getHeaders()`, `getSegmentParams()`) handed down to another
57
+ * component marks the call reading through it, as well as the one that made it.
58
+ *
59
+ * Not marked: a read in other work the call did not await, such as a promise
60
+ * handed to a client component (it lands in a call record nobody checks).
61
+ * See design/53 §"Reads outside the key".
29
62
  */
30
63
 
31
- import { createElement, type ReactNode } from 'react';
64
+ import { createElement, Fragment, type ReactElement, type ReactNode } from 'react';
32
65
 
33
66
  import { documentReadScopeAls, type DocumentReadScope } from '../als-registry.ts';
34
67
  import { isOutletGateElement } from './outlet-gate.ts';
35
- import { callAndRewrite, type ServerComponent, type SubtreeRule } from '../subtree-walk.ts';
68
+ import {
69
+ callAndRewrite,
70
+ isThenable,
71
+ type ServerComponent,
72
+ type SubtreeRule,
73
+ } from '../subtree-walk.ts';
74
+ import { clientComponents } from '../vite-handoff-rsc.ts';
36
75
  import type { DocumentLifetime } from './segment-key.ts';
37
76
 
38
77
  /** The read scope of one `'document'` segment. */
@@ -53,6 +92,8 @@ export function readScopeFor(
53
92
  ),
54
93
  cookies: new Map((key.cookies ?? []).map((cookie) => [cookie.name, cookie.codec])),
55
94
  headers: new Set((key.headers ?? []).map((name) => name.toLowerCase())),
95
+ reported: { done: false },
96
+ call: { read: false },
56
97
  };
57
98
  }
58
99
 
@@ -62,7 +103,7 @@ export function readScopeFor(
62
103
  */
63
104
  export function inReadScope(component: ServerComponent, scope: DocumentReadScope): ServerComponent {
64
105
  const rule = scopeRule(scope);
65
- return (props) => documentReadScopeAls.run(scope, () => callAndRewrite(component, props, rule));
106
+ return (props) => runCall(scope, () => callAndRewrite(component, props, rule));
66
107
  }
67
108
 
68
109
  /**
@@ -77,9 +118,66 @@ function ScopedServerComponent(props: {
77
118
  scope: DocumentReadScope;
78
119
  }): ReactNode | Promise<ReactNode> {
79
120
  const { component, componentProps, scope } = props;
80
- return documentReadScopeAls.run(scope, () =>
81
- callAndRewrite(component, componentProps, scopeRule(scope))
82
- );
121
+ return runCall(scope, () => callAndRewrite(component, componentProps, scopeRule(scope)));
122
+ }
123
+
124
+ /**
125
+ * Run one scoped component call in its own copy of the scope — a fresh
126
+ * `call` record, the segment's shared `reported` — and append the client's
127
+ * withdrawal marker to its output if the call, or work it awaited, read
128
+ * outside the key.
129
+ */
130
+ function runCall(
131
+ scope: DocumentReadScope,
132
+ call: () => ReactNode | Promise<ReactNode>
133
+ ): ReactNode | Promise<ReactNode> {
134
+ const frame: DocumentReadScope = { ...scope, call: { read: false } };
135
+ const thrown = (error: unknown): never => {
136
+ if (frame.call.read && typeof error === 'object' && error !== null) {
137
+ THROWN_AFTER_READ.add(error);
138
+ }
139
+ throw error;
140
+ };
141
+ let output: ReactNode | Promise<ReactNode>;
142
+ try {
143
+ output = documentReadScopeAls.run(frame, call);
144
+ } catch (error) {
145
+ return thrown(error);
146
+ }
147
+ if (isThenable(output)) {
148
+ return Promise.resolve(output).then(
149
+ (node) => (frame.call.read ? withMarker(node) : node),
150
+ thrown
151
+ );
152
+ }
153
+ return frame.call.read ? withMarker(output) : output;
154
+ }
155
+
156
+ /**
157
+ * Errors thrown by a scoped call after it read outside its key. Weak: an
158
+ * error lives only as long as whoever handles it holds it.
159
+ */
160
+ const THROWN_AFTER_READ = new WeakSet<object>();
161
+
162
+ /**
163
+ * The fallback a catcher renders in place of a component that threw: marked
164
+ * to withdraw its outlet when the throw came from a scoped call that read
165
+ * outside its key, so the client does not keep the fallback under the key
166
+ * digest. Every catcher that renders a fallback inside an outlet calls this.
167
+ */
168
+ export function fallbackAfter<T extends ReactNode>(error: unknown, fallback: T): T | ReactElement {
169
+ const marked = typeof error === 'object' && error !== null && THROWN_AFTER_READ.has(error);
170
+ return marked ? withMarker(fallback) : fallback;
171
+ }
172
+
173
+ /**
174
+ * `node` with a `DocumentWithdrawal` marker beside it. Two arguments, not an
175
+ * array: no key is needed, and `node` keeps its position as the fragment's
176
+ * first child.
177
+ */
178
+ function withMarker(node: ReactNode): ReactElement {
179
+ const { DocumentWithdrawal } = clientComponents();
180
+ return createElement(Fragment, null, node, createElement(DocumentWithdrawal));
83
181
  }
84
182
 
85
183
  function scopeRule(scope: DocumentReadScope): SubtreeRule {
@@ -95,7 +193,23 @@ function scopeRule(scope: DocumentReadScope): SubtreeRule {
95
193
  }),
96
194
  // A nested outlet is another segment: its own lifetime decides what it reads.
97
195
  isOpaque: isOutletGateElement,
98
- // An async iterable it returned reads, as it is advanced, inside the scope.
99
- runIn: (fn) => documentReadScopeAls.run(scope, fn),
196
+ // An async iterable it returned reads, as it is advanced, inside the scope:
197
+ // in a call record of its own, so a chunk produced after a read outside
198
+ // the key carries the marker as a call's output would.
199
+ // Marked once: the marker commits with that chunk, and each marked chunk
200
+ // becomes an element, which an iterable read as data would notice. A read
201
+ // on the closing step yields the marker alone, since the return value is
202
+ // not rendered (codex on #1317).
203
+ iterate: () => {
204
+ const frame: DocumentReadScope = { ...scope, call: { read: false } };
205
+ let marked = false;
206
+ const due = () => frame.call.read && !marked && (marked = true);
207
+ return {
208
+ run: (fn) => documentReadScopeAls.run(frame, fn),
209
+ // What an async iterable rendered as a child yields is rendered as nodes.
210
+ yielded: (value) => (due() ? withMarker(value as ReactNode) : value),
211
+ beforeClose: () => (due() ? withMarker(null) : undefined),
212
+ };
213
+ },
100
214
  };
101
215
  }