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

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 (106) hide show
  1. package/dist/_chunks/{actions-DoTj0Jd3.js → actions-D_LiN5xG.js} +4 -4
  2. package/dist/_chunks/actions-D_LiN5xG.js.map +1 -0
  3. package/dist/_chunks/{cli-check-DlQBSKIN.js → cli-check-BE9BnXwi.js} +5 -5
  4. package/dist/_chunks/cli-check-BE9BnXwi.js.map +1 -0
  5. package/dist/_chunks/{convention-lint-CGGcseNn.js → convention-lint-DkSDlsPH.js} +36 -8
  6. package/dist/_chunks/convention-lint-DkSDlsPH.js.map +1 -0
  7. package/dist/_chunks/{dev-server-LO4McfQi.js → dev-server-BZxFJNih.js} +66 -9
  8. package/dist/_chunks/{dev-server-LO4McfQi.js.map → dev-server-BZxFJNih.js.map} +1 -1
  9. package/dist/_chunks/dev-server-C72bB9Kg.js +1 -0
  10. package/dist/_chunks/{key-headers-uIig1_mU.js → key-headers-CVpa6fpW.js} +6 -2
  11. package/dist/_chunks/key-headers-CVpa6fpW.js.map +1 -0
  12. package/dist/cli-check.d.ts +3 -3
  13. package/dist/cli-check.d.ts.map +1 -1
  14. package/dist/cli.js +2 -2
  15. package/dist/config-types.d.ts +43 -22
  16. package/dist/config-types.d.ts.map +1 -1
  17. package/dist/config-validation.d.ts.map +1 -1
  18. package/dist/index.d.ts +1 -1
  19. package/dist/index.d.ts.map +1 -1
  20. package/dist/index.js +4 -4
  21. package/dist/index.js.map +1 -1
  22. package/dist/native/rsc/manifest.json +1 -0
  23. package/dist/native/rsc/server/route-element-builder.js +1 -1
  24. package/dist/native/rsc/server/route-element-builder.js.map +1 -1
  25. package/dist/native/rsc/server/route-module-loader.js +5 -4
  26. package/dist/native/rsc/server/route-module-loader.js.map +1 -1
  27. package/dist/native/rsc/server/rsc-entry/render-route.js +1 -1
  28. package/dist/native/rsc/server/rsc-entry/render-route.js.map +1 -1
  29. package/dist/native/rsc/server/rsc-entry/revalidate-renderer.js +1 -1
  30. package/dist/native/rsc/server/rsc-entry/revalidate-renderer.js.map +1 -1
  31. package/dist/native/rsc/server/segment-lifetime/outlet-gate.js +2 -1
  32. package/dist/native/rsc/server/segment-lifetime/outlet-gate.js.map +1 -1
  33. package/dist/native/rsc/server/segment-lifetime/read-rule.js +2 -2
  34. package/dist/native/rsc/server/segment-lifetime/read-rule.js.map +1 -1
  35. package/dist/native/rsc/server/segment-lifetime/segment-key.js +13 -8
  36. package/dist/native/rsc/server/segment-lifetime/segment-key.js.map +1 -1
  37. package/dist/native/rsc/server/segment-lifetime/slot-outlets.js +5 -4
  38. package/dist/native/rsc/server/segment-lifetime/slot-outlets.js.map +1 -1
  39. package/dist/native/rsc/shared/key-headers.js +4 -1
  40. package/dist/native/rsc/shared/key-headers.js.map +1 -1
  41. package/dist/native/rsc/shared/layout-defaults.js +19 -0
  42. package/dist/native/rsc/shared/layout-defaults.js.map +1 -0
  43. package/dist/native/ssr/manifest.json +1 -0
  44. package/dist/native/ssr/server/segment-lifetime/outlet-gate.js +1 -0
  45. package/dist/native/ssr/server/segment-lifetime/outlet-gate.js.map +1 -1
  46. package/dist/native/ssr/server/segment-lifetime/read-rule.js +2 -2
  47. package/dist/native/ssr/server/segment-lifetime/read-rule.js.map +1 -1
  48. package/dist/native/ssr/shared/key-headers.js +4 -1
  49. package/dist/native/ssr/shared/key-headers.js.map +1 -1
  50. package/dist/native/ssr/shared/layout-defaults.js +9 -0
  51. package/dist/native/ssr/shared/layout-defaults.js.map +1 -0
  52. package/dist/plugins/entries.d.ts.map +1 -1
  53. package/dist/routing/convention-lint.d.ts +2 -2
  54. package/dist/routing/convention-lint.d.ts.map +1 -1
  55. package/dist/routing/route-options-lint.d.ts +2 -2
  56. package/dist/routing/route-options-lint.d.ts.map +1 -1
  57. package/dist/server/index.js +1 -1
  58. package/dist/server/internal.js +1 -1
  59. package/dist/server/route-module-loader.d.ts +4 -3
  60. package/dist/server/route-module-loader.d.ts.map +1 -1
  61. package/dist/server/rsc-entry/index.d.ts.map +1 -1
  62. package/dist/server/rsc-entry/render-route.d.ts +3 -3
  63. package/dist/server/rsc-entry/render-route.d.ts.map +1 -1
  64. package/dist/server/rsc-entry/revalidate-renderer.d.ts +3 -3
  65. package/dist/server/rsc-entry/revalidate-renderer.d.ts.map +1 -1
  66. package/dist/server/segment-lifetime/outlet-gate.d.ts +5 -5
  67. package/dist/server/segment-lifetime/outlet-gate.d.ts.map +1 -1
  68. package/dist/server/segment-lifetime/read-rule.d.ts.map +1 -1
  69. package/dist/server/segment-lifetime/segment-key.d.ts +21 -18
  70. package/dist/server/segment-lifetime/segment-key.d.ts.map +1 -1
  71. package/dist/server/segment-lifetime/slot-outlets.d.ts +2 -3
  72. package/dist/server/segment-lifetime/slot-outlets.d.ts.map +1 -1
  73. package/dist/server/types.d.ts +4 -3
  74. package/dist/server/types.d.ts.map +1 -1
  75. package/dist/shared/key-headers.d.ts +2 -0
  76. package/dist/shared/key-headers.d.ts.map +1 -1
  77. package/dist/shared/layout-defaults.d.ts +30 -0
  78. package/dist/shared/layout-defaults.d.ts.map +1 -0
  79. package/docs/api/30-api-server.mdx +1 -1
  80. package/docs/api/34-api-config.mdx +20 -3
  81. package/package.json +1 -1
  82. package/src/cli-check.ts +6 -6
  83. package/src/config-types.ts +44 -22
  84. package/src/config-validation.ts +96 -20
  85. package/src/index.ts +1 -1
  86. package/src/plugins/entries.ts +6 -3
  87. package/src/plugins/routing.ts +1 -1
  88. package/src/routing/convention-lint.ts +5 -3
  89. package/src/routing/route-options-lint.ts +6 -6
  90. package/src/server/route-element-builder.ts +1 -1
  91. package/src/server/route-module-loader.ts +7 -6
  92. package/src/server/rsc-entry/index.ts +7 -8
  93. package/src/server/rsc-entry/render-route.ts +4 -4
  94. package/src/server/rsc-entry/revalidate-renderer.ts +4 -4
  95. package/src/server/segment-lifetime/outlet-gate.ts +6 -6
  96. package/src/server/segment-lifetime/read-rule.ts +5 -2
  97. package/src/server/segment-lifetime/segment-key.ts +32 -24
  98. package/src/server/segment-lifetime/slot-outlets.ts +7 -11
  99. package/src/server/types.ts +4 -3
  100. package/src/shared/key-headers.ts +5 -0
  101. package/src/shared/layout-defaults.ts +43 -0
  102. package/dist/_chunks/actions-DoTj0Jd3.js.map +0 -1
  103. package/dist/_chunks/cli-check-DlQBSKIN.js.map +0 -1
  104. package/dist/_chunks/convention-lint-CGGcseNn.js.map +0 -1
  105. package/dist/_chunks/dev-server-DrjLscqT.js +0 -1
  106. package/dist/_chunks/key-headers-uIig1_mU.js.map +0 -1
@@ -115,7 +115,7 @@ export function timberRouting(ctx: PluginContext): Plugin {
115
115
  // deduplicated against `warnedFiles`: an error must not be downgraded to
116
116
  // silence by an earlier scan in the same process.
117
117
  const conventionWarnings = lintConventions(tree, ctx.appDir, {
118
- defaultLayoutLifetime: ctx.config.defaultLayoutLifetime,
118
+ layoutDefaults: ctx.config.layoutDefaults,
119
119
  });
120
120
  const fatal = conventionWarnings.filter((w) => w.level === 'error');
121
121
  if (fatal.length > 0) {
@@ -34,7 +34,8 @@ import {
34
34
  isScriptExtension,
35
35
  } from './export-detect.ts';
36
36
  import { checkRouteOptions } from './route-options-lint.ts';
37
- import type { SegmentLifetime } from '../server/types.ts';
37
+ import type { LayoutDefaults } from '../config-types.ts';
38
+ import { resolveLayoutDefaults } from '../shared/layout-defaults.ts';
38
39
 
39
40
  // ─── Types ──────────────────────────────────────────────────────────────────
40
41
 
@@ -60,7 +61,7 @@ export function lintConventions(
60
61
  tree: RouteTree,
61
62
  appDir: string,
62
63
  /** The config the checks depend on, as the build resolved it. */
63
- config: { defaultLayoutLifetime: SegmentLifetime | undefined }
64
+ config: { layoutDefaults: LayoutDefaults | undefined }
64
65
  ): ConventionWarning[] {
65
66
  const warnings: ConventionWarning[] = [];
66
67
 
@@ -103,7 +104,8 @@ export function lintConventions(
103
104
 
104
105
  // Check 10: layoutOptions / pageOptions the build cannot read, unknown
105
106
  // keys, and the removed floating exports (design/53)
106
- checkRouteOptions(tree.root, warnings, 'main', config.defaultLayoutLifetime ?? 'request');
107
+ const { lifetime } = resolveLayoutDefaults(config.layoutDefaults);
108
+ checkRouteOptions(tree.root, warnings, 'main', lifetime);
107
109
 
108
110
  return warnings;
109
111
  }
@@ -25,8 +25,8 @@ export function checkRouteOptions(
25
25
  node: SegmentNode,
26
26
  warnings: ConventionWarning[],
27
27
  position: RoutePosition,
28
- /** The app's `defaultLayoutLifetime` (design/53 §"App-wide default"). */
29
- defaultLayoutLifetime: SegmentLifetime,
28
+ /** `layoutDefaults.lifetime`, resolved (design/53 §"App-wide defaults"). */
29
+ layoutLifetimeDefault: SegmentLifetime,
30
30
  /** The params named on the path above this segment. */
31
31
  ancestorParams: readonly string[] = []
32
32
  ): void {
@@ -42,7 +42,7 @@ export function checkRouteOptions(
42
42
  problems.push(
43
43
  ...inertOptions(options, here),
44
44
  ...paramsOffPath(options, pathParams),
45
- ...keyWithoutDocument(options, kind === 'layout' ? defaultLayoutLifetime : 'request')
45
+ ...keyWithoutDocument(options, kind === 'layout' ? layoutLifetimeDefault : 'request')
46
46
  );
47
47
  if (problems.length === 0) continue;
48
48
  warnings.push({
@@ -71,18 +71,18 @@ export function checkRouteOptions(
71
71
  }
72
72
  }
73
73
  for (const child of node.children) {
74
- checkRouteOptions(child, warnings, here, defaultLayoutLifetime, pathParams);
74
+ checkRouteOptions(child, warnings, here, layoutLifetimeDefault, pathParams);
75
75
  }
76
76
  for (const slot of Object.values(node.slots)) {
77
77
  const slotPosition = here === 'intercepting' ? here : 'slot';
78
- checkRouteOptions(slot, warnings, slotPosition, defaultLayoutLifetime, pathParams);
78
+ checkRouteOptions(slot, warnings, slotPosition, layoutLifetimeDefault, pathParams);
79
79
  }
80
80
  }
81
81
 
82
82
  /**
83
83
  * A `key` applies only to a `'document'` segment; on any other it would
84
84
  * silently do nothing. A layout that declares no lifetime takes the app's
85
- * `defaultLayoutLifetime`, so under a `'document'` default it may declare a
85
+ * `layoutDefaults.lifetime`, so under a `'document'` default it may declare a
86
86
  * key alone. A page always defaults to `'request'`.
87
87
  */
88
88
  function keyWithoutDocument(
@@ -208,7 +208,7 @@ export async function buildRouteElement(
208
208
  deferSuspenseFor,
209
209
  accessFns,
210
210
  documentLifetimes,
211
- } = await loadRouteModules(segments, req.url, render.defaultLayoutLifetime);
211
+ } = await loadRouteModules(segments, req.url, render.layoutDefaults);
212
212
  // The coerced params every 'document' key on the main chain reads from —
213
213
  // read only when a segment needs them.
214
214
  const hasDocumentSegment =
@@ -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' ` +
@@ -26,8 +26,9 @@ import type { CoercedParams } from '../../shared/param-value.ts';
26
26
  import { ROUTE_OPTIONS_EXPORT, type RouteOptionsKind } from '../../shared/route-options-export.ts';
27
27
  import { getCookieJar } from '../cookie-context.ts';
28
28
  import { getHeaders, getSearchParams } from '../request-context.ts';
29
- import { headerKeyProblem } from '../../shared/key-headers.ts';
30
- import type { SegmentKey, SegmentLifetime } from '../types.ts';
29
+ import { headerKeyProblem, isHeaderList } from '../../shared/key-headers.ts';
30
+ import { NO_LAYOUT_DEFAULTS, type ResolvedLayoutDefaults } from '../../shared/layout-defaults.ts';
31
+ import type { SegmentKey } from '../types.ts';
31
32
 
32
33
  /** A segment declared `lifetime: 'document'`, with the key it declared (if any). */
33
34
  export interface DocumentLifetime {
@@ -35,45 +36,52 @@ export interface DocumentLifetime {
35
36
  }
36
37
 
37
38
  /**
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'`.
39
+ * The defaults of the layout at the end of `chain` (the segments from the
40
+ * root down to it, slot chains included): the app's `layoutDefaults`, except
41
+ * at or below an intercepting segment. Options there are a build error
42
+ * (`routing/route-options-lint.ts`), so a defaulted layout under an
43
+ * intercepting directory could never opt out — it takes no defaults instead
44
+ * (design/53 §"App-wide defaults"). A page always takes `NO_LAYOUT_DEFAULTS`.
45
45
  */
46
- export function defaultLayoutLifetimeAt(
46
+ export function layoutDefaultsAt(
47
47
  chain: readonly { segmentType?: string }[],
48
- appDefault: SegmentLifetime
49
- ): SegmentLifetime {
50
- return chain.some((segment) => segment.segmentType === 'intercepting') ? 'request' : appDefault;
48
+ appDefaults: ResolvedLayoutDefaults
49
+ ): ResolvedLayoutDefaults {
50
+ const intercepted = chain.some((segment) => segment.segmentType === 'intercepting');
51
+ return intercepted ? NO_LAYOUT_DEFAULTS : appDefaults;
51
52
  }
52
53
 
53
54
  /**
54
55
  * 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.
56
+ * declares `lifetime: 'document'`, or declares no lifetime and the default is
57
+ * `'document'`; undefined otherwise. The build validated the object from
58
+ * source (`routing/route-options.ts`); this runtime read is what takes effect.
59
59
  *
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").
60
+ * Each key part defaults on its own, as `segmentParams` already does: a
61
+ * `'document'` segment whose key omits `headers` takes the default headers,
62
+ * and one that declares `headers` replaces them.
63
+ *
64
+ * @param defaults What a module that declares none takes: the app's
65
+ * `layoutDefaults` for a layout (`layoutDefaultsAt`), `NO_LAYOUT_DEFAULTS`
66
+ * for a page (design/53 §"App-wide defaults").
63
67
  */
64
68
  export function readDocumentLifetime(
65
69
  mod: Record<string, unknown>,
66
70
  kind: RouteOptionsKind,
67
- defaultLifetime: SegmentLifetime
71
+ defaults: ResolvedLayoutDefaults
68
72
  ): DocumentLifetime | undefined {
69
73
  const exported = mod[ROUTE_OPTIONS_EXPORT[kind]];
70
74
  const options = typeof exported === 'object' && exported !== null ? exported : {};
71
75
  const lifetime = 'lifetime' in options ? options.lifetime : undefined;
72
- if ((lifetime ?? defaultLifetime) !== 'document') return undefined;
76
+ if ((lifetime ?? defaults.lifetime) !== 'document') return undefined;
73
77
  const key = 'key' in options ? options.key : undefined;
74
78
  // The module's own export, typed `satisfies LayoutOptions` / `PageOptions`
75
79
  // 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) : {};
80
+ const declared = typeof key === 'object' && key !== null ? (key as SegmentKey) : {};
81
+ const segmentKey =
82
+ declared.headers === undefined && defaults.headers !== undefined
83
+ ? { ...declared, headers: defaults.headers }
84
+ : declared;
77
85
  assertKeyableHeaders(segmentKey.headers);
78
86
  return { key: segmentKey };
79
87
  }
@@ -85,7 +93,7 @@ export function readDocumentLifetime(
85
93
  */
86
94
  function assertKeyableHeaders(headers: unknown): void {
87
95
  if (headers === undefined) return;
88
- if (!Array.isArray(headers) || !headers.every((h) => typeof h === 'string')) {
96
+ if (!isHeaderList(headers)) {
89
97
  throw new Error('[timber] key.headers must be an array of header names.');
90
98
  }
91
99
  for (const name of headers) {
@@ -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. */
@@ -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
  */
@@ -146,12 +146,13 @@ export interface PageOptions {
146
146
 
147
147
  /** Options for a `layout.tsx`: `export const layoutOptions = { … } satisfies LayoutOptions`. */
148
148
  export interface LayoutOptions {
149
- /** See `SegmentLifetime`. Default: the app's `defaultLayoutLifetime` (`'request'` unless set). */
149
+ /** See `SegmentLifetime`. Default: the app's `layoutDefaults.lifetime` (`'request'` unless set). */
150
150
  lifetime?: SegmentLifetime;
151
151
  /**
152
152
  * What a `'document'` layout depends on. Only on a `'document'` layout: one
153
153
  * that declares `lifetime: 'document'`, or declares no lifetime under a
154
- * `'document'` `defaultLayoutLifetime`.
154
+ * `'document'` `layoutDefaults.lifetime`. A key that omits `headers` takes
155
+ * `layoutDefaults.key.headers`.
155
156
  */
156
157
  key?: SegmentKey;
157
158
  /**
@@ -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
+ }