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

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 (143) hide show
  1. package/dist/_chunks/{actions-DoTj0Jd3.js → actions-C7_xl9iA.js} +12 -8
  2. package/dist/_chunks/actions-C7_xl9iA.js.map +1 -0
  3. package/dist/_chunks/als-registry-C-iwbtvI.js.map +1 -1
  4. package/dist/_chunks/{cli-check-DlQBSKIN.js → cli-check-CetL-6Us.js} +5 -5
  5. package/dist/_chunks/cli-check-CetL-6Us.js.map +1 -0
  6. package/dist/_chunks/{codegen-vaCyFyVN.js → codegen-BxJGInWa.js} +76 -20
  7. package/dist/_chunks/codegen-BxJGInWa.js.map +1 -0
  8. package/dist/_chunks/{convention-lint-CGGcseNn.js → convention-lint-BWbKAV4x.js} +51 -15
  9. package/dist/_chunks/convention-lint-BWbKAV4x.js.map +1 -0
  10. package/dist/_chunks/{dev-server-LO4McfQi.js → dev-server-BZxFJNih.js} +66 -9
  11. package/dist/_chunks/{dev-server-LO4McfQi.js.map → dev-server-BZxFJNih.js.map} +1 -1
  12. package/dist/_chunks/dev-server-C72bB9Kg.js +1 -0
  13. package/dist/_chunks/{key-headers-uIig1_mU.js → key-headers-CVpa6fpW.js} +6 -2
  14. package/dist/_chunks/key-headers-CVpa6fpW.js.map +1 -0
  15. package/dist/cli-check.d.ts +3 -3
  16. package/dist/cli-check.d.ts.map +1 -1
  17. package/dist/cli.js +2 -2
  18. package/dist/config-types.d.ts +43 -22
  19. package/dist/config-types.d.ts.map +1 -1
  20. package/dist/config-validation.d.ts.map +1 -1
  21. package/dist/index.d.ts +1 -1
  22. package/dist/index.d.ts.map +1 -1
  23. package/dist/index.js +4 -4
  24. package/dist/index.js.map +1 -1
  25. package/dist/native/rsc/manifest.json +2 -0
  26. package/dist/native/rsc/routing/descendant-params.js +28 -0
  27. package/dist/native/rsc/routing/descendant-params.js.map +1 -0
  28. package/dist/native/rsc/server/als-registry.js.map +1 -1
  29. package/dist/native/rsc/server/request-context.js +1 -1
  30. package/dist/native/rsc/server/request-context.js.map +1 -1
  31. package/dist/native/rsc/server/route-element-builder.js +4 -3
  32. package/dist/native/rsc/server/route-element-builder.js.map +1 -1
  33. package/dist/native/rsc/server/route-module-loader.js +5 -4
  34. package/dist/native/rsc/server/route-module-loader.js.map +1 -1
  35. package/dist/native/rsc/server/rsc-entry/render-route.js +1 -1
  36. package/dist/native/rsc/server/rsc-entry/render-route.js.map +1 -1
  37. package/dist/native/rsc/server/rsc-entry/revalidate-renderer.js +1 -1
  38. package/dist/native/rsc/server/rsc-entry/revalidate-renderer.js.map +1 -1
  39. package/dist/native/rsc/server/segment-lifetime/outlet-gate.js +2 -1
  40. package/dist/native/rsc/server/segment-lifetime/outlet-gate.js.map +1 -1
  41. package/dist/native/rsc/server/segment-lifetime/read-rule.js +9 -5
  42. package/dist/native/rsc/server/segment-lifetime/read-rule.js.map +1 -1
  43. package/dist/native/rsc/server/segment-lifetime/read-scope.js +3 -1
  44. package/dist/native/rsc/server/segment-lifetime/read-scope.js.map +1 -1
  45. package/dist/native/rsc/server/segment-lifetime/segment-key.js +15 -9
  46. package/dist/native/rsc/server/segment-lifetime/segment-key.js.map +1 -1
  47. package/dist/native/rsc/server/segment-lifetime/slot-outlets.js +6 -5
  48. package/dist/native/rsc/server/segment-lifetime/slot-outlets.js.map +1 -1
  49. package/dist/native/rsc/shared/key-headers.js +4 -1
  50. package/dist/native/rsc/shared/key-headers.js.map +1 -1
  51. package/dist/native/rsc/shared/layout-defaults.js +19 -0
  52. package/dist/native/rsc/shared/layout-defaults.js.map +1 -0
  53. package/dist/native/ssr/manifest.json +1 -0
  54. package/dist/native/ssr/server/als-registry.js.map +1 -1
  55. package/dist/native/ssr/server/request-context.js +1 -1
  56. package/dist/native/ssr/server/request-context.js.map +1 -1
  57. package/dist/native/ssr/server/segment-lifetime/outlet-gate.js +1 -0
  58. package/dist/native/ssr/server/segment-lifetime/outlet-gate.js.map +1 -1
  59. package/dist/native/ssr/server/segment-lifetime/read-rule.js +9 -5
  60. package/dist/native/ssr/server/segment-lifetime/read-rule.js.map +1 -1
  61. package/dist/native/ssr/server/segment-lifetime/read-scope.js.map +1 -1
  62. package/dist/native/ssr/shared/key-headers.js +4 -1
  63. package/dist/native/ssr/shared/key-headers.js.map +1 -1
  64. package/dist/native/ssr/shared/layout-defaults.js +9 -0
  65. package/dist/native/ssr/shared/layout-defaults.js.map +1 -0
  66. package/dist/plugins/entries.d.ts.map +1 -1
  67. package/dist/routing/codegen-types.d.ts +9 -0
  68. package/dist/routing/codegen-types.d.ts.map +1 -1
  69. package/dist/routing/codegen.d.ts.map +1 -1
  70. package/dist/routing/convention-lint.d.ts +2 -2
  71. package/dist/routing/convention-lint.d.ts.map +1 -1
  72. package/dist/routing/descendant-params.d.ts +46 -0
  73. package/dist/routing/descendant-params.d.ts.map +1 -0
  74. package/dist/routing/index.js +1 -1
  75. package/dist/routing/route-options-lint.d.ts +2 -2
  76. package/dist/routing/route-options-lint.d.ts.map +1 -1
  77. package/dist/routing/route-options.d.ts +1 -1
  78. package/dist/routing/route-options.d.ts.map +1 -1
  79. package/dist/server/als-registry.d.ts +13 -0
  80. package/dist/server/als-registry.d.ts.map +1 -1
  81. package/dist/server/index.js +1 -1
  82. package/dist/server/internal.js +1 -1
  83. package/dist/server/internal.js.map +1 -1
  84. package/dist/server/route-element-builder.d.ts.map +1 -1
  85. package/dist/server/route-module-loader.d.ts +4 -3
  86. package/dist/server/route-module-loader.d.ts.map +1 -1
  87. package/dist/server/rsc-entry/index.d.ts.map +1 -1
  88. package/dist/server/rsc-entry/render-route.d.ts +3 -3
  89. package/dist/server/rsc-entry/render-route.d.ts.map +1 -1
  90. package/dist/server/rsc-entry/revalidate-renderer.d.ts +3 -3
  91. package/dist/server/rsc-entry/revalidate-renderer.d.ts.map +1 -1
  92. package/dist/server/segment-lifetime/outlet-gate.d.ts +5 -5
  93. package/dist/server/segment-lifetime/outlet-gate.d.ts.map +1 -1
  94. package/dist/server/segment-lifetime/read-rule.d.ts +8 -1
  95. package/dist/server/segment-lifetime/read-rule.d.ts.map +1 -1
  96. package/dist/server/segment-lifetime/read-scope.d.ts +8 -2
  97. package/dist/server/segment-lifetime/read-scope.d.ts.map +1 -1
  98. package/dist/server/segment-lifetime/segment-key.d.ts +28 -20
  99. package/dist/server/segment-lifetime/segment-key.d.ts.map +1 -1
  100. package/dist/server/segment-lifetime/slot-outlets.d.ts +2 -3
  101. package/dist/server/segment-lifetime/slot-outlets.d.ts.map +1 -1
  102. package/dist/server/types.d.ts +7 -5
  103. package/dist/server/types.d.ts.map +1 -1
  104. package/dist/shared/key-headers.d.ts +2 -0
  105. package/dist/shared/key-headers.d.ts.map +1 -1
  106. package/dist/shared/layout-defaults.d.ts +30 -0
  107. package/dist/shared/layout-defaults.d.ts.map +1 -0
  108. package/docs/api/30-api-server.mdx +2 -2
  109. package/docs/api/34-api-config.mdx +20 -3
  110. package/package.json +1 -1
  111. package/src/cli-check.ts +6 -6
  112. package/src/config-types.ts +44 -22
  113. package/src/config-validation.ts +96 -20
  114. package/src/index.ts +1 -1
  115. package/src/plugins/entries.ts +6 -3
  116. package/src/plugins/routing.ts +1 -1
  117. package/src/routing/codegen-types.ts +9 -0
  118. package/src/routing/codegen.ts +34 -20
  119. package/src/routing/convention-lint.ts +5 -3
  120. package/src/routing/descendant-params.ts +76 -0
  121. package/src/routing/route-options-lint.ts +34 -15
  122. package/src/routing/route-options.ts +3 -2
  123. package/src/server/als-registry.ts +13 -0
  124. package/src/server/request-context.ts +1 -1
  125. package/src/server/route-element-builder.ts +10 -3
  126. package/src/server/route-module-loader.ts +7 -6
  127. package/src/server/rsc-entry/index.ts +7 -8
  128. package/src/server/rsc-entry/render-route.ts +4 -4
  129. package/src/server/rsc-entry/revalidate-renderer.ts +4 -4
  130. package/src/server/segment-lifetime/outlet-gate.ts +6 -6
  131. package/src/server/segment-lifetime/read-rule.ts +37 -5
  132. package/src/server/segment-lifetime/read-scope.ts +11 -2
  133. package/src/server/segment-lifetime/segment-key.ts +50 -27
  134. package/src/server/segment-lifetime/slot-outlets.ts +10 -12
  135. package/src/server/types.ts +7 -5
  136. package/src/shared/key-headers.ts +5 -0
  137. package/src/shared/layout-defaults.ts +43 -0
  138. package/dist/_chunks/actions-DoTj0Jd3.js.map +0 -1
  139. package/dist/_chunks/cli-check-DlQBSKIN.js.map +0 -1
  140. package/dist/_chunks/codegen-vaCyFyVN.js.map +0 -1
  141. package/dist/_chunks/convention-lint-CGGcseNn.js.map +0 -1
  142. package/dist/_chunks/dev-server-DrjLscqT.js +0 -1
  143. package/dist/_chunks/key-headers-uIig1_mU.js.map +0 -1
@@ -44,6 +44,7 @@ import {
44
44
  pageOutletKey,
45
45
  } from '../routing/segment-keys.ts';
46
46
  import { documentOutletFor, pathParamNames } from './segment-lifetime/document-outlet.ts';
47
+ import { childrenChainParams } from '../routing/descendant-params.ts';
47
48
  import { getSegmentParams } from './request-context.ts';
48
49
  import { inReadScope, readScopeFor } from './segment-lifetime/read-scope.ts';
49
50
  import type { ServerComponent } from './subtree-walk.ts';
@@ -208,7 +209,7 @@ export async function buildRouteElement(
208
209
  deferSuspenseFor,
209
210
  accessFns,
210
211
  documentLifetimes,
211
- } = await loadRouteModules(segments, req.url, render.defaultLayoutLifetime);
212
+ } = await loadRouteModules(segments, req.url, render.layoutDefaults);
212
213
  // The coerced params every 'document' key on the main chain reads from —
213
214
  // read only when a segment needs them.
214
215
  const hasDocumentSegment =
@@ -246,7 +247,8 @@ export async function buildRouteElement(
246
247
  readScopeFor(
247
248
  pageOutletKey(segmentTreePaths[segments.length - 1]),
248
249
  documentLifetimes.page,
249
- pathParamNames(segments, segments.length - 1)
250
+ pathParamNames(segments, segments.length - 1),
251
+ []
250
252
  )
251
253
  )
252
254
  : LoadedPage;
@@ -458,7 +460,12 @@ export async function buildRouteElement(
458
460
  const layoutComponentRef = layoutLifetime
459
461
  ? inReadScope(
460
462
  layoutComponent as ServerComponent,
461
- readScopeFor(layoutOutletPath, layoutLifetime, pathParamNames(segments, i))
463
+ readScopeFor(
464
+ layoutOutletPath,
465
+ layoutLifetime,
466
+ pathParamNames(segments, i),
467
+ childrenChainParams(segment).keys()
468
+ )
462
469
  )
463
470
  : layoutComponent;
464
471
  const layoutDenyPages = denyPageChains.get(i);
@@ -9,12 +9,13 @@
9
9
  */
10
10
 
11
11
  import type { ManifestSegmentNode } from './route-matcher.ts';
12
- import type { Metadata, SegmentLifetime } from './types.ts';
12
+ import type { Metadata } from './types.ts';
13
+ import { NO_LAYOUT_DEFAULTS, type ResolvedLayoutDefaults } from '../shared/layout-defaults.ts';
13
14
  import { loadModule } from './safe-load.ts';
14
15
  import { ROUTE_OPTIONS_EXPORT } from '../shared/route-options-export.ts';
15
16
  import { NoPageComponentError, type LayoutComponentEntry } from './route-element-builder.ts';
16
17
  import {
17
- defaultLayoutLifetimeAt,
18
+ layoutDefaultsAt,
18
19
  readDocumentLifetime,
19
20
  type DocumentLifetime,
20
21
  } from './segment-lifetime/segment-key.ts';
@@ -112,8 +113,8 @@ function collectModuleExports(
112
113
  export async function loadRouteModules(
113
114
  segments: ManifestSegmentNode[],
114
115
  requestUrl: string,
115
- /** The app's `defaultLayoutLifetime` (design/53 §"App-wide default"). */
116
- defaultLayoutLifetime: SegmentLifetime
116
+ /** The app's `layoutDefaults` (design/53 §"App-wide defaults"). */
117
+ layoutDefaults: ResolvedLayoutDefaults
117
118
  ): Promise<LoadedRouteModules> {
118
119
  const metadataSources: MetadataSource[] = [];
119
120
  const layoutComponents: LayoutComponentEntry[] = [];
@@ -131,7 +132,7 @@ export async function loadRouteModules(
131
132
  documentLifetimes.layouts[i] = readDocumentLifetime(
132
133
  mod,
133
134
  'layout',
134
- defaultLayoutLifetimeAt(segments.slice(0, i + 1), defaultLayoutLifetime)
135
+ layoutDefaultsAt(segments.slice(0, i + 1), layoutDefaults)
135
136
  );
136
137
  if (mod.default) {
137
138
  layoutComponents.push({
@@ -154,7 +155,7 @@ export async function loadRouteModules(
154
155
  if (mod.default) {
155
156
  PageComponent = mod.default as (...args: unknown[]) => unknown;
156
157
  }
157
- documentLifetimes.page = readDocumentLifetime(mod, 'page', 'request');
158
+ documentLifetimes.page = readDocumentLifetime(mod, 'page', NO_LAYOUT_DEFAULTS);
158
159
  deferSuspenseFor = collectModuleExports(
159
160
  mod,
160
161
  segment,
@@ -45,7 +45,7 @@ import { buildActionDispatcher } from './action-dispatcher.ts';
45
45
  import type { BodyLimitsConfig } from '../body-limits.ts';
46
46
  import type { DevHooks } from '../../dev-tools/dev-page-shell.ts';
47
47
  import type { BuildManifest } from '../build-manifest.ts';
48
- import type { SegmentLifetime } from '../types.ts';
48
+ import { resolveLayoutDefaults } from '../../shared/layout-defaults.ts';
49
49
  import { resolveLogMode } from '../../dev-tools/logger.ts';
50
50
  import { sendEarlyHints103 } from '../early-hints-sender.ts';
51
51
  import { collectEarlyHintHeaders } from '../early-hints.ts';
@@ -273,11 +273,10 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
273
273
  | { disabled: boolean; enableHMRInDev: boolean }
274
274
  | undefined;
275
275
  const clientJsDisabled = clientJsConfig?.disabled ?? false;
276
- // Written by `plugins/entries.ts` as exactly 'request' or 'document'.
277
- const defaultLayoutLifetime: SegmentLifetime =
278
- (runtimeConfig as Record<string, unknown>).defaultLayoutLifetime === 'document'
279
- ? 'document'
280
- : 'request';
276
+ // Written by `plugins/entries.ts` in its config shape; resolved once, here.
277
+ const layoutDefaults = resolveLayoutDefaults(
278
+ (runtimeConfig as Record<string, unknown>).layoutDefaults
279
+ );
281
280
  // One signer per server; it reads the secret on first use.
282
281
  const keyDigestSigner = clientJsDisabled ? null : createKeyDigestSigner(encryptionKeySource);
283
282
  const clientBootstrap = buildClientScripts({
@@ -399,7 +398,7 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
399
398
  clientBootstrap,
400
399
  clientJsDisabled,
401
400
  keyDigestSigner,
402
- defaultLayoutLifetime,
401
+ layoutDefaults,
403
402
  renderDenyFallback,
404
403
  buildManifest: typedBuildManifest,
405
404
  renderTimeoutMs: (config as Record<string, unknown>).renderTimeoutMs as number,
@@ -504,7 +503,7 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
504
503
  coerceSegmentParams,
505
504
  buildManifest: buildManifest as BuildManifest,
506
505
  keyDigestSigner,
507
- defaultLayoutLifetime,
506
+ layoutDefaults,
508
507
  }),
509
508
  }),
510
509
  };
@@ -34,7 +34,7 @@ import { recordTiming } from '../server-timing.ts';
34
34
  import { parseClientStateTree } from '../client-state-tree.ts';
35
35
  import type { SegmentRender } from '../segment-lifetime/outlet-gate.ts';
36
36
  import type { KeyDigestSigner } from '../segment-lifetime/key-digest.ts';
37
- import type { SegmentLifetime } from '../types.ts';
37
+ import type { ResolvedLayoutDefaults } from '../../shared/layout-defaults.ts';
38
38
 
39
39
  import { handleApiRoute } from './api-handler.ts';
40
40
  import type { DenyFallbackRenderer } from './deny-fallback.ts';
@@ -59,8 +59,8 @@ export interface RenderRouteDeps {
59
59
  * since no client router can hold a segment.
60
60
  */
61
61
  keyDigestSigner: KeyDigestSigner | null;
62
- /** The app's `defaultLayoutLifetime` (design/53 §"App-wide default"). */
63
- defaultLayoutLifetime: SegmentLifetime;
62
+ /** The app's `layoutDefaults` (design/53 §"App-wide defaults"). */
63
+ layoutDefaults: ResolvedLayoutDefaults;
64
64
  renderDenyFallback: DenyFallbackRenderer;
65
65
  buildManifest: BuildManifest;
66
66
  /**
@@ -107,7 +107,7 @@ export async function renderRoute(
107
107
  const signer = clientJsDisabled ? null : deps.keyDigestSigner;
108
108
  const segmentRender: SegmentRender = {
109
109
  documents: signer ? { client: clientState?.documents ?? null, signer } : null,
110
- defaultLayoutLifetime: deps.defaultLayoutLifetime,
110
+ layoutDefaults: deps.layoutDefaults,
111
111
  };
112
112
 
113
113
  // Build the React element tree — runs access checks eagerly to gate
@@ -48,7 +48,7 @@ import type { CoercedParams } from '../../shared/param-value.ts';
48
48
 
49
49
  import { runMiddlewareForAction } from './action-middleware-runner.ts';
50
50
  import type { KeyDigestSigner } from '../segment-lifetime/key-digest.ts';
51
- import type { SegmentLifetime } from '../types.ts';
51
+ import type { ResolvedLayoutDefaults } from '../../shared/layout-defaults.ts';
52
52
  import { RSC_CONTENT_TYPE } from '../../shared/rsc-media-type.ts';
53
53
 
54
54
  /** Result of validating a `revalidatePath()` argument. */
@@ -146,8 +146,8 @@ export interface RevalidateRendererDeps {
146
146
  * (design/53-segment-lifetime.md open question 4).
147
147
  */
148
148
  keyDigestSigner: KeyDigestSigner | null;
149
- /** The app's `defaultLayoutLifetime` (design/53 §"App-wide default"). */
150
- defaultLayoutLifetime: SegmentLifetime;
149
+ /** The app's `layoutDefaults` (design/53 §"App-wide defaults"). */
150
+ layoutDefaults: ResolvedLayoutDefaults;
151
151
  }
152
152
 
153
153
  /**
@@ -351,7 +351,7 @@ export function createRevalidateRendererFactory(
351
351
  undefined,
352
352
  {
353
353
  documents: deps.keyDigestSigner ? { client: null, signer: deps.keyDigestSigner } : null,
354
- defaultLayoutLifetime: deps.defaultLayoutLifetime,
354
+ layoutDefaults: deps.layoutDefaults,
355
355
  },
356
356
  deps.buildManifest.metadataRouteHashes
357
357
  );
@@ -17,7 +17,7 @@ import { createElement, type ReactElement, type ReactNode } from 'react';
17
17
  import type { OutletDecision } from '../../shared/outlet-decision.ts';
18
18
  import { clientComponents } from '../vite-handoff-rsc.ts';
19
19
  import type { DocumentKeys, DocumentOutlet } from './document-outlet.ts';
20
- import type { SegmentLifetime } from '../types.ts';
20
+ import { NO_LAYOUT_DEFAULTS, type ResolvedLayoutDefaults } from '../../shared/layout-defaults.ts';
21
21
 
22
22
  /** One outlet in the element tree, and the outlets directly inside it. */
23
23
  export interface OutletSpec {
@@ -36,17 +36,17 @@ export interface SegmentRender {
36
36
  */
37
37
  documents: DocumentKeys | null;
38
38
  /**
39
- * The lifetime of a layout that declares none: the app's
40
- * `defaultLayoutLifetime` (design/53 §"App-wide default"). Pages always
41
- * default to `'request'`.
39
+ * What a layout that declares no lifetime, or a key without `headers`,
40
+ * takes: the app's `layoutDefaults` (design/53 §"App-wide defaults").
41
+ * Pages take none.
42
42
  */
43
- defaultLayoutLifetime: SegmentLifetime;
43
+ layoutDefaults: ResolvedLayoutDefaults;
44
44
  }
45
45
 
46
46
  /** A render with no client router to hold segments: every outlet live. */
47
47
  export const LIVE_ONLY_RENDER: SegmentRender = {
48
48
  documents: null,
49
- defaultLayoutLifetime: 'request',
49
+ layoutDefaults: NO_LAYOUT_DEFAULTS,
50
50
  };
51
51
 
52
52
  /**
@@ -62,10 +62,13 @@ function readOutsideKey(
62
62
  const fix =
63
63
  fixOverride ??
64
64
  (part
65
- ? `Add it to key.${part}, or declare lifetime: 'request'.`
65
+ ? `Add it to key.${part}, or declare lifetime: 'request'.` +
66
+ (part === 'headers'
67
+ ? ' A declared key.headers replaces layoutDefaults.key.headers, so list those too.'
68
+ : '')
66
69
  : "A 'document' segment cannot depend on it; declare lifetime: 'request'.");
67
70
  return new Error(
68
- `[timber] ${scope.segmentPath} is lifetime: 'document' (declared, or from defaultLayoutLifetime) ` +
71
+ `[timber] ${scope.segmentPath} is lifetime: 'document' (declared, or from layoutDefaults) ` +
69
72
  `and read ${what}, which is not in its key. ` +
70
73
  `${fix} The segment is skipped without rendering while its key is unchanged, so the read ` +
71
74
  `would freeze at its first value; until it is fixed, it renders as lifetime: 'request' ` +
@@ -192,16 +195,28 @@ const OBJECT_PROBES: ReadonlySet<string> = new Set([
192
195
  * own keys are only the params in the key, so spreading it, or passing it to
193
196
  * a client component, carries exactly what the segment may depend on.
194
197
  */
195
- export function scopedParams<T extends CoercedParams>(params: T): T {
198
+ export function scopedParams<T extends CoercedParams>(
199
+ params: T,
200
+ /**
201
+ * `'slot'` when `params` is a slot's record merged over the main route's
202
+ * (`getSegmentParams(slotPath)`). A key computes a descendant's param from
203
+ * the main route's record, and a slot may define the same name with another
204
+ * value, so a keyed descendant name is refused through it.
205
+ */
206
+ record: 'route' | 'slot' = 'route'
207
+ ): T {
196
208
  const scope = currentReadScope();
197
209
  if (!scope) return params;
210
+ const throughSlot = (name: string) => record === 'slot' && !scope.pathParams.has(name);
198
211
  // Refused: every name the key leaves out — a param on the segment's path, a
199
212
  // descendant's or a slot's, present in this request or not. Absence is a
200
213
  // value too: a layout reading a child's param that this URL lacks would
201
214
  // freeze `undefined` across the URLs that have it. Only the names runtimes
202
215
  // probe on any object pass.
203
216
  const refused = (name: string | symbol) =>
204
- typeof name === 'string' && !scope.params.has(name) && !OBJECT_PROBES.has(name);
217
+ typeof name === 'string' &&
218
+ (!scope.params.has(name) || throughSlot(name)) &&
219
+ !OBJECT_PROBES.has(name);
205
220
  const allowed = (name: string | symbol) => !refused(name);
206
221
  // Over a copy: the trap hides keys, which a frozen or non-configurable
207
222
  // target would forbid, and the request's own record stays untouched.
@@ -212,7 +227,24 @@ export function scopedParams<T extends CoercedParams>(params: T): T {
212
227
  return new Proxy(target, {
213
228
  get(target, name, receiver) {
214
229
  if (refused(name)) {
215
- refuseRead(scope, `the segment param "${String(name)}"`, 'segmentParams');
230
+ // A key may name only params on the segment's path or, for a layout,
231
+ // ones its children define (the build refuses any other), so "add it
232
+ // to the key" would be a build error here.
233
+ const key = name as string;
234
+ refuseRead(
235
+ scope,
236
+ `the segment param "${key}"`,
237
+ 'segmentParams',
238
+ scope.params.has(key)
239
+ ? `It is keyed from the route's params, and was read through a slot's, which may ` +
240
+ `hold another value: read it with getSegmentParams() and no slot path.`
241
+ : !scope.keyableParams.has(key)
242
+ ? `No key on this segment can name it: it is not on the segment's path, and it is ` +
243
+ `not a param a page below a main-chain layout binds (a page or a slot segment ` +
244
+ `keys only its path). Render what reads it in a segment whose path has it, or ` +
245
+ `declare lifetime: 'request'.`
246
+ : undefined
247
+ );
216
248
  }
217
249
  return Reflect.get(target, name, receiver);
218
250
  },
@@ -74,16 +74,25 @@ import {
74
74
  import { clientComponents } from '../vite-handoff-rsc.ts';
75
75
  import type { DocumentLifetime } from './segment-key.ts';
76
76
 
77
- /** The read scope of one `'document'` segment. */
77
+ /**
78
+ * The read scope of one `'document'` segment.
79
+ *
80
+ * @param pathParams Every param on the segment's path: the default key.
81
+ * @param descendants The params its `children` chain defines (a layout's;
82
+ * none for a page), which a key may also name.
83
+ */
78
84
  export function readScopeFor(
79
85
  segmentPath: string,
80
86
  lifetime: DocumentLifetime,
81
- pathParams: readonly string[]
87
+ pathParams: readonly string[],
88
+ descendants: Iterable<string>
82
89
  ): DocumentReadScope {
83
90
  const { key } = lifetime;
84
91
  return {
85
92
  segmentPath,
86
93
  params: new Set(key.segmentParams ?? pathParams),
94
+ keyableParams: new Set([...pathParams, ...descendants]),
95
+ pathParams: new Set(pathParams),
87
96
  searchParams: new Map(
88
97
  Object.entries(key.searchParams?.codecs ?? {}).map(([field, codec]) => [
89
98
  field,
@@ -9,7 +9,9 @@
9
9
  * definition that owns it, so two requests that differ only in a way the
10
10
  * segment cannot observe produce the same string:
11
11
  *
12
- * - **segment params** — the coerced params (each segment's codec applied);
12
+ * - **segment params** — the coerced params (each segment's codec applied),
13
+ * with a param absent from the record tagged apart from one present as
14
+ * `undefined`, since the segment can tell them apart (`in`, `Object.keys`);
13
15
  * - **search params** — `def.buildSearchParams(def.parse(…))`, which applies
14
16
  * defaults, aliases (`withUrlKey`) and drops values that parse to the default;
15
17
  * - **headers** — each named header's value as `Headers.get` returns it
@@ -26,8 +28,9 @@ import type { CoercedParams } from '../../shared/param-value.ts';
26
28
  import { ROUTE_OPTIONS_EXPORT, type RouteOptionsKind } from '../../shared/route-options-export.ts';
27
29
  import { getCookieJar } from '../cookie-context.ts';
28
30
  import { getHeaders, getSearchParams } from '../request-context.ts';
29
- import { headerKeyProblem } from '../../shared/key-headers.ts';
30
- import type { SegmentKey, SegmentLifetime } from '../types.ts';
31
+ import { headerKeyProblem, isHeaderList } from '../../shared/key-headers.ts';
32
+ import { NO_LAYOUT_DEFAULTS, type ResolvedLayoutDefaults } from '../../shared/layout-defaults.ts';
33
+ import type { SegmentKey } from '../types.ts';
31
34
 
32
35
  /** A segment declared `lifetime: 'document'`, with the key it declared (if any). */
33
36
  export interface DocumentLifetime {
@@ -35,45 +38,52 @@ export interface DocumentLifetime {
35
38
  }
36
39
 
37
40
  /**
38
- * The lifetime of a layout that declares none, at the end of `chain` (the
39
- * segments from the root down to it, slot chains included): the app's
40
- * `defaultLayoutLifetime`, except at or below an intercepting segment.
41
- * Options there are a build error (`routing/route-options-lint.ts`), so a
42
- * defaulted layout under an intercepting directory could never opt back to
43
- * `'request'` — it keeps `'request'` instead (design/53 §"App-wide default").
44
- * A page always defaults to `'request'`.
41
+ * The defaults of the layout at the end of `chain` (the segments from the
42
+ * root down to it, slot chains included): the app's `layoutDefaults`, except
43
+ * at or below an intercepting segment. Options there are a build error
44
+ * (`routing/route-options-lint.ts`), so a defaulted layout under an
45
+ * intercepting directory could never opt out — it takes no defaults instead
46
+ * (design/53 §"App-wide defaults"). A page always takes `NO_LAYOUT_DEFAULTS`.
45
47
  */
46
- export function defaultLayoutLifetimeAt(
48
+ export function layoutDefaultsAt(
47
49
  chain: readonly { segmentType?: string }[],
48
- appDefault: SegmentLifetime
49
- ): SegmentLifetime {
50
- return chain.some((segment) => segment.segmentType === 'intercepting') ? 'request' : appDefault;
50
+ appDefaults: ResolvedLayoutDefaults
51
+ ): ResolvedLayoutDefaults {
52
+ const intercepted = chain.some((segment) => segment.segmentType === 'intercepting');
53
+ return intercepted ? NO_LAYOUT_DEFAULTS : appDefaults;
51
54
  }
52
55
 
53
56
  /**
54
57
  * The module's lifetime: a `DocumentLifetime` when its options object
55
- * declares `lifetime: 'document'`, or declares no lifetime and
56
- * `defaultLifetime` is `'document'`; undefined otherwise. The build validated
57
- * the object from source (`routing/route-options.ts`); this runtime read is
58
- * what takes effect.
58
+ * declares `lifetime: 'document'`, or declares no lifetime and the default is
59
+ * `'document'`; undefined otherwise. The build validated the object from
60
+ * source (`routing/route-options.ts`); this runtime read is what takes effect.
59
61
  *
60
- * @param defaultLifetime The lifetime of a module that declares none: the
61
- * app's `defaultLayoutLifetime` for a layout, `'request'` for a page
62
- * (design/53 §"App-wide default").
62
+ * Each key part defaults on its own, as `segmentParams` already does: a
63
+ * `'document'` segment whose key omits `headers` takes the default headers,
64
+ * and one that declares `headers` replaces them.
65
+ *
66
+ * @param defaults What a module that declares none takes: the app's
67
+ * `layoutDefaults` for a layout (`layoutDefaultsAt`), `NO_LAYOUT_DEFAULTS`
68
+ * for a page (design/53 §"App-wide defaults").
63
69
  */
64
70
  export function readDocumentLifetime(
65
71
  mod: Record<string, unknown>,
66
72
  kind: RouteOptionsKind,
67
- defaultLifetime: SegmentLifetime
73
+ defaults: ResolvedLayoutDefaults
68
74
  ): DocumentLifetime | undefined {
69
75
  const exported = mod[ROUTE_OPTIONS_EXPORT[kind]];
70
76
  const options = typeof exported === 'object' && exported !== null ? exported : {};
71
77
  const lifetime = 'lifetime' in options ? options.lifetime : undefined;
72
- if ((lifetime ?? defaultLifetime) !== 'document') return undefined;
78
+ if ((lifetime ?? defaults.lifetime) !== 'document') return undefined;
73
79
  const key = 'key' in options ? options.key : undefined;
74
80
  // The module's own export, typed `satisfies LayoutOptions` / `PageOptions`
75
81
  // in source and shape-checked by the build; at runtime it is an `object`.
76
- const segmentKey = typeof key === 'object' && key !== null ? (key as SegmentKey) : {};
82
+ const declared = typeof key === 'object' && key !== null ? (key as SegmentKey) : {};
83
+ const segmentKey =
84
+ declared.headers === undefined && defaults.headers !== undefined
85
+ ? { ...declared, headers: defaults.headers }
86
+ : declared;
77
87
  assertKeyableHeaders(segmentKey.headers);
78
88
  return { key: segmentKey };
79
89
  }
@@ -85,7 +95,7 @@ export function readDocumentLifetime(
85
95
  */
86
96
  function assertKeyableHeaders(headers: unknown): void {
87
97
  if (headers === undefined) return;
88
- if (!Array.isArray(headers) || !headers.every((h) => typeof h === 'string')) {
98
+ if (!isHeaderList(headers)) {
89
99
  throw new Error('[timber] key.headers must be an array of header names.');
90
100
  }
91
101
  for (const name of headers) {
@@ -99,7 +109,10 @@ function assertKeyableHeaders(headers: unknown): void {
99
109
  *
100
110
  * @param pathParams Every param name on the segment's path, outermost first —
101
111
  * the default `segmentParams`.
102
- * @param params The coerced values of those params.
112
+ * @param params The matched route's coerced params, the record the segment
113
+ * reads. A keyed name may be absent from it: an optional catch-all with no
114
+ * segments, or a param a layout's `children` chain defines on other routes
115
+ * (design/53 §"Keying on a descendant's param").
103
116
  */
104
117
  export function readKeyValues(
105
118
  lifetime: DocumentLifetime,
@@ -108,7 +121,10 @@ export function readKeyValues(
108
121
  ): string {
109
122
  const { key } = lifetime;
110
123
  const names = key.segmentParams ?? pathParams;
111
- const segmentParams = names.map((name) => [name, canonicalParam(params[name])]);
124
+ const segmentParams = names.map((name) => [
125
+ name,
126
+ Object.hasOwn(params, name) ? canonicalParam(params[name]) : ABSENT,
127
+ ]);
112
128
 
113
129
  const definition = key.searchParams;
114
130
  const searchParams = definition
@@ -130,6 +146,13 @@ export function readKeyValues(
130
146
  return JSON.stringify([segmentParams, searchParams, cookies, headers]);
131
147
  }
132
148
 
149
+ /**
150
+ * A keyed param the record does not hold. Every present value is a tagged
151
+ * array with a one-letter tag (`tagged`), so this string spells none of them;
152
+ * in particular not `undefined` (`["u"]`), which a present param can hold.
153
+ */
154
+ const ABSENT = '["absent"]';
155
+
133
156
  /**
134
157
  * A coerced param as a stable string that keeps every distinct value of the
135
158
  * param domain (`shared/param-value.ts`) distinct. Every value is written as a
@@ -31,11 +31,8 @@ import type { CoercedParams } from '../../shared/param-value.ts';
31
31
  import type { ManifestSegmentNode } from '../route-matcher.ts';
32
32
  import { outletGate, type OutletSpec, type SegmentRender } from './outlet-gate.ts';
33
33
  import { documentOutletFor } from './document-outlet.ts';
34
- import {
35
- defaultLayoutLifetimeAt,
36
- readDocumentLifetime,
37
- type DocumentLifetime,
38
- } from './segment-key.ts';
34
+ import { layoutDefaultsAt, readDocumentLifetime, type DocumentLifetime } from './segment-key.ts';
35
+ import { NO_LAYOUT_DEFAULTS } from '../../shared/layout-defaults.ts';
39
36
  import { inReadScope, readScopeFor } from './read-scope.ts';
40
37
  import type { ServerComponent } from '../subtree-walk.ts';
41
38
 
@@ -73,19 +70,18 @@ export class SlotDocumentOutlets {
73
70
  }
74
71
 
75
72
  /**
76
- * A slot segment's lifetime: its own declaration, else the app's
77
- * `defaultLayoutLifetime` for a layout (`defaultLayoutLifetimeAt`) and
78
- * `'request'` for a page.
73
+ * A slot segment's lifetime: its own declaration, over the app's
74
+ * `layoutDefaults` for a layout (`layoutDefaultsAt`) and none for a page.
79
75
  */
80
76
  lifetimeOf(
81
77
  node: ManifestSegmentNode,
82
78
  mod: Record<string, unknown>,
83
79
  kind: 'page' | 'layout'
84
80
  ): DocumentLifetime | undefined {
85
- if (kind === 'page') return readDocumentLifetime(mod, kind, 'request');
81
+ if (kind === 'page') return readDocumentLifetime(mod, kind, NO_LAYOUT_DEFAULTS);
86
82
  const chain = [...this.ctx.ownerChain, ...this.ctx.chain.slice(0, this.depth(node) + 1)];
87
- const fallback = defaultLayoutLifetimeAt(chain, this.ctx.render.defaultLayoutLifetime);
88
- return readDocumentLifetime(mod, kind, fallback);
83
+ const defaults = layoutDefaultsAt(chain, this.ctx.render.layoutDefaults);
84
+ return readDocumentLifetime(mod, kind, defaults);
89
85
  }
90
86
 
91
87
  /** Wrap a `'document'` slot page in its own outlet. */
@@ -143,7 +139,9 @@ export class SlotDocumentOutlets {
143
139
  ): ServerComponent {
144
140
  const treePath = this.treePath(node);
145
141
  const segmentPath = kind === 'page' ? pageOutletKey(treePath) : layoutOutletKey(treePath);
146
- return inReadScope(component, readScopeFor(segmentPath, lifetime, this.pathParams(node)));
142
+ // A slot segment keys only params on its path (design/53 §"Keying on a
143
+ // descendant's param"): the build refuses a descendant's.
144
+ return inReadScope(component, readScopeFor(segmentPath, lifetime, this.pathParams(node), []));
147
145
  }
148
146
 
149
147
  private decision(node: ManifestSegmentNode, segmentPath: string, lifetime: DocumentLifetime) {
@@ -99,7 +99,7 @@ export type RoutePrerender = boolean | { ttl?: number; tags?: readonly string[]
99
99
 
100
100
  /**
101
101
  * How long a segment's output lives. `'request'` (the default, unless the app
102
- * sets `defaultLayoutLifetime` for its layouts) renders on every request. `'document'` renders on the document request and whenever its key
102
+ * sets `layoutDefaults.lifetime` for its layouts) renders on every request. `'document'` renders on the document request and whenever its key
103
103
  * changes or `router.refresh()` runs, and is skipped without rendering on
104
104
  * every other client navigation. See design/53-segment-lifetime.md.
105
105
  */
@@ -112,8 +112,9 @@ export type SegmentLifetime = 'request' | 'document';
112
112
  */
113
113
  export interface SegmentKey {
114
114
  /**
115
- * Param names on the segment's path. Default: every param on the path.
116
- * A name that is not on the path fails the build.
115
+ * Param names on the segment's path, or, for a main-chain layout, names a
116
+ * page below it binds (absent on the routes that do not). Default: every
117
+ * param on the path. Any other name fails the build.
117
118
  */
118
119
  segmentParams?: readonly string[];
119
120
  /** A search-params definition, often a `.pick()`. Default: none. */
@@ -146,12 +147,13 @@ export interface PageOptions {
146
147
 
147
148
  /** Options for a `layout.tsx`: `export const layoutOptions = { … } satisfies LayoutOptions`. */
148
149
  export interface LayoutOptions {
149
- /** See `SegmentLifetime`. Default: the app's `defaultLayoutLifetime` (`'request'` unless set). */
150
+ /** See `SegmentLifetime`. Default: the app's `layoutDefaults.lifetime` (`'request'` unless set). */
150
151
  lifetime?: SegmentLifetime;
151
152
  /**
152
153
  * What a `'document'` layout depends on. Only on a `'document'` layout: one
153
154
  * that declares `lifetime: 'document'`, or declares no lifetime under a
154
- * `'document'` `defaultLayoutLifetime`.
155
+ * `'document'` `layoutDefaults.lifetime`. A key that omits `headers` takes
156
+ * `layoutDefaults.key.headers`.
155
157
  */
156
158
  key?: SegmentKey;
157
159
  /**
@@ -28,6 +28,11 @@ const UNKEYABLE_HEADERS: ReadonlyMap<string, string> = new Map([
28
28
  ['x-api-key', CREDENTIAL],
29
29
  ]);
30
30
 
31
+ /** Whether `value` has the shape of `key.headers`: an array of strings. */
32
+ export function isHeaderList(value: unknown): value is readonly string[] {
33
+ return Array.isArray(value) && value.every((h) => typeof h === 'string');
34
+ }
35
+
31
36
  /** Why a key may not name `name`, or undefined when it may. */
32
37
  export function headerKeyProblem(name: string): string | undefined {
33
38
  if (!HEADER_NAME.test(name))
@@ -0,0 +1,43 @@
1
+ /**
2
+ * The app's layout defaults (`layoutDefaults` in `timber.config.ts`), as every
3
+ * reader takes them: the build lint (`routing/route-options-lint.ts`), the
4
+ * runtime config the RSC entry reads (`plugins/entries.ts`), and through it
5
+ * the main chain and slot layouts (`server/segment-lifetime/segment-key.ts`).
6
+ *
7
+ * See design/53-segment-lifetime.md §"App-wide defaults".
8
+ */
9
+
10
+ import type { SegmentLifetime } from '../server/types.ts';
11
+ import { isHeaderList } from './key-headers.ts';
12
+
13
+ /** What a layout takes when it declares no lifetime, or a key without `headers`. */
14
+ export interface ResolvedLayoutDefaults {
15
+ lifetime: SegmentLifetime;
16
+ /** The `key.headers` of a `'document'` layout whose key omits `headers`. */
17
+ headers: readonly string[] | undefined;
18
+ }
19
+
20
+ /**
21
+ * No defaults: what a page takes, and a layout at or below an intercepting
22
+ * directory, which could not opt out of one.
23
+ */
24
+ export const NO_LAYOUT_DEFAULTS: ResolvedLayoutDefaults = {
25
+ lifetime: 'request',
26
+ headers: undefined,
27
+ };
28
+
29
+ /**
30
+ * Resolve the configured value. Anything config validation reports as
31
+ * malformed reads as no default: a lifetime other than `'document'` is
32
+ * `'request'`, and headers that are not an array of strings are none —
33
+ * slower, never wrong. A header the key may not name is a fatal config error
34
+ * (`config-validation.ts`), and the runtime refuses it again when it reads a
35
+ * layout's key.
36
+ */
37
+ export function resolveLayoutDefaults(value: unknown): ResolvedLayoutDefaults {
38
+ if (typeof value !== 'object' || value === null) return NO_LAYOUT_DEFAULTS;
39
+ const lifetime = 'lifetime' in value && value.lifetime === 'document' ? 'document' : 'request';
40
+ const key = 'key' in value && typeof value.key === 'object' ? value.key : null;
41
+ const headers = key !== null && 'headers' in key ? key.headers : undefined;
42
+ return { lifetime, headers: isHeaderList(headers) ? headers : undefined };
43
+ }