@timber-js/app 0.2.0-alpha.220 → 0.2.0-alpha.222

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 (236) hide show
  1. package/dist/_chunks/{actions-BwkmAYXq.js → actions-vBHr2vqd.js} +3 -3
  2. package/dist/_chunks/{actions-BwkmAYXq.js.map → actions-vBHr2vqd.js.map} +1 -1
  3. package/dist/_chunks/{cache-api-LA3sBpUS.js → cache-api-DdcDLpBj.js} +72 -145
  4. package/dist/_chunks/cache-api-DdcDLpBj.js.map +1 -0
  5. package/dist/_chunks/chains-B8TCLved.js +1 -0
  6. package/dist/_chunks/{chains-e_Buf9vg.js → chains-BchW_AtW.js} +2 -2
  7. package/dist/_chunks/{chains-e_Buf9vg.js.map → chains-BchW_AtW.js.map} +1 -1
  8. package/dist/_chunks/{classify-2Yp3xJY1.js → classify-IqzMpxMs.js} +2 -2
  9. package/dist/_chunks/{classify-2Yp3xJY1.js.map → classify-IqzMpxMs.js.map} +1 -1
  10. package/dist/_chunks/{cli-check-DDwCkeDY.js → cli-check-DQne_YhU.js} +3 -3
  11. package/dist/_chunks/{cli-check-DDwCkeDY.js.map → cli-check-DQne_YhU.js.map} +1 -1
  12. package/dist/_chunks/{cli-schema-sync-BdIebmk3.js → cli-schema-sync-BS-RFGE2.js} +2 -2
  13. package/dist/_chunks/{cli-schema-sync-BdIebmk3.js.map → cli-schema-sync-BS-RFGE2.js.map} +1 -1
  14. package/dist/_chunks/{cli-schema-sync-CLNfXQDK.js → cli-schema-sync-v872sHms.js} +1 -1
  15. package/dist/_chunks/{client-dep-entries-BOkpKjj1.js → client-dep-entries-BJyP9SIu.js} +2 -2
  16. package/dist/_chunks/{client-dep-entries-BOkpKjj1.js.map → client-dep-entries-BJyP9SIu.js.map} +1 -1
  17. package/dist/_chunks/{convention-lint-ByKJ6aqD.js → convention-lint-VwzrtjIt.js} +3 -3
  18. package/dist/_chunks/{convention-lint-ByKJ6aqD.js.map → convention-lint-VwzrtjIt.js.map} +1 -1
  19. package/dist/_chunks/{dev-server-DnODXuNM.js → dev-server-BNr5drEO.js} +57 -8
  20. package/dist/_chunks/dev-server-BNr5drEO.js.map +1 -0
  21. package/dist/_chunks/dev-server-CUg7Mqh_.js +1 -0
  22. package/dist/_chunks/dev-store-BOa304m_.js +283 -0
  23. package/dist/_chunks/dev-store-BOa304m_.js.map +1 -0
  24. package/dist/_chunks/{error-boundary-xxxLtXt6.js → error-boundary-Bc8QPZuq.js} +71 -21
  25. package/dist/_chunks/error-boundary-Bc8QPZuq.js.map +1 -0
  26. package/dist/_chunks/{flight-source-node-0dE-t3kq.js → flight-source-node-BdHUOUqg.js} +6 -7
  27. package/dist/_chunks/flight-source-node-BdHUOUqg.js.map +1 -0
  28. package/dist/_chunks/global-context-B9PFncvb.js +48 -0
  29. package/dist/_chunks/global-context-B9PFncvb.js.map +1 -0
  30. package/dist/_chunks/{json-lossy-check-C8zBY2uZ.js → json-lossy-check-C3Sht92C.js} +2 -2
  31. package/dist/_chunks/{json-lossy-check-C8zBY2uZ.js.map → json-lossy-check-C3Sht92C.js.map} +1 -1
  32. package/dist/_chunks/{live-graph-tSWrv8eH.js → live-graph-DEu_GWbc.js} +4 -4
  33. package/dist/_chunks/{live-graph-tSWrv8eH.js.map → live-graph-DEu_GWbc.js.map} +1 -1
  34. package/dist/_chunks/{logger-CbLdcy-W.js → logger-CI_hThfy.js} +10 -2
  35. package/dist/_chunks/{logger-CbLdcy-W.js.map → logger-CI_hThfy.js.map} +1 -1
  36. package/dist/_chunks/{node-response-Dibufw_b.js → node-response-bF0bKoig.js} +49 -3
  37. package/dist/_chunks/node-response-bF0bKoig.js.map +1 -0
  38. package/dist/_chunks/{poison-scan-C4FgMxFl.js → poison-scan-DTWIfNgD.js} +2 -2
  39. package/dist/_chunks/{poison-scan-C4FgMxFl.js.map → poison-scan-DTWIfNgD.js.map} +1 -1
  40. package/dist/_chunks/{purge-store-Byr8XOjU.js → purge-store-WZaxu-3m.js} +2 -2
  41. package/dist/_chunks/purge-store-WZaxu-3m.js.map +1 -0
  42. package/dist/_chunks/{render-timeout-DOf_BBcO.js → render-timeout-Ln_u7fX-.js} +19 -11
  43. package/dist/_chunks/render-timeout-Ln_u7fX-.js.map +1 -0
  44. package/dist/_chunks/{resolve-schema-CBR6Lm4i.js → resolve-schema-CkAInout.js} +2 -2
  45. package/dist/_chunks/{resolve-schema-CBR6Lm4i.js.map → resolve-schema-CkAInout.js.map} +1 -1
  46. package/dist/_chunks/{scanner-Cb3fSjAC.js → scanner-C8fdKvKG.js} +2 -2
  47. package/dist/_chunks/{scanner-Cb3fSjAC.js.map → scanner-C8fdKvKG.js.map} +1 -1
  48. package/dist/_chunks/{schema-bridge-C83xa9lT.js → schema-bridge-DpOmvZlI.js} +60 -23
  49. package/dist/_chunks/schema-bridge-DpOmvZlI.js.map +1 -0
  50. package/dist/_chunks/{segment-context-xtPUGfdq.js → segment-context-D3DNxKFq.js} +4 -8
  51. package/dist/_chunks/segment-context-D3DNxKFq.js.map +1 -0
  52. package/dist/_chunks/{sizeof-QPE5nd3u.js → sizeof-CO3dk0V1.js} +2 -2
  53. package/dist/_chunks/{sizeof-QPE5nd3u.js.map → sizeof-CO3dk0V1.js.map} +1 -1
  54. package/dist/_chunks/{walkers-qu8TpiLh.js → walkers-BqzxnwGC.js} +3 -3
  55. package/dist/_chunks/{walkers-qu8TpiLh.js.map → walkers-BqzxnwGC.js.map} +1 -1
  56. package/dist/adapters/cloudflare-kv-cache.js +1 -1
  57. package/dist/analyze/crawl-entry.js +3 -3
  58. package/dist/analyze/graph-command.js +2 -2
  59. package/dist/cache/cache-api.d.ts.map +1 -1
  60. package/dist/cache/guarded-read.d.ts +29 -0
  61. package/dist/cache/guarded-read.d.ts.map +1 -0
  62. package/dist/cache/handler-store.d.ts +13 -1
  63. package/dist/cache/handler-store.d.ts.map +1 -1
  64. package/dist/cache/index.js +3 -2
  65. package/dist/cache/invalidation-epoch.d.ts +7 -0
  66. package/dist/cache/invalidation-epoch.d.ts.map +1 -1
  67. package/dist/cache/stores/memory.js +1 -1
  68. package/dist/cache/timber-cache.d.ts.map +1 -1
  69. package/dist/cdn/index.js +1 -1
  70. package/dist/cdn/purge-store.d.ts +10 -1
  71. package/dist/cdn/purge-store.d.ts.map +1 -1
  72. package/dist/cli.js +3 -3
  73. package/dist/client/browser-entry/router-init.d.ts.map +1 -1
  74. package/dist/client/error-boundary.js +1 -1
  75. package/dist/client/global-context.d.ts +21 -1
  76. package/dist/client/global-context.d.ts.map +1 -1
  77. package/dist/client/index.js +9 -27
  78. package/dist/client/index.js.map +1 -1
  79. package/dist/client/internal.js +38 -65
  80. package/dist/client/internal.js.map +1 -1
  81. package/dist/client/link.d.ts.map +1 -1
  82. package/dist/client/navigation-context.d.ts.map +1 -1
  83. package/dist/client/navigation-transition.d.ts +68 -14
  84. package/dist/client/navigation-transition.d.ts.map +1 -1
  85. package/dist/client/params-context.d.ts.map +1 -1
  86. package/dist/client/router-effects.d.ts +35 -31
  87. package/dist/client/router-effects.d.ts.map +1 -1
  88. package/dist/client/router-pipeline.d.ts +2 -6
  89. package/dist/client/router-pipeline.d.ts.map +1 -1
  90. package/dist/client/router-types.d.ts +10 -30
  91. package/dist/client/router-types.d.ts.map +1 -1
  92. package/dist/client/router.d.ts.map +1 -1
  93. package/dist/client/slot-context.d.ts +2 -2
  94. package/dist/client/slot-context.d.ts.map +1 -1
  95. package/dist/codec.js +1 -1
  96. package/dist/cookies/index.js +1 -1
  97. package/dist/dev-tools/logs.d.ts +2 -2
  98. package/dist/dev-tools/logs.d.ts.map +1 -1
  99. package/dist/index.js +149 -56
  100. package/dist/index.js.map +1 -1
  101. package/dist/params/index.js +1 -1
  102. package/dist/plugins/dev-server.d.ts +1 -1
  103. package/dist/plugins/dev-server.d.ts.map +1 -1
  104. package/dist/plugins/dev-store-clear.d.ts +28 -0
  105. package/dist/plugins/dev-store-clear.d.ts.map +1 -0
  106. package/dist/plugins/entries.d.ts +5 -0
  107. package/dist/plugins/entries.d.ts.map +1 -1
  108. package/dist/plugins/orphaned-modules.d.ts +57 -0
  109. package/dist/plugins/orphaned-modules.d.ts.map +1 -0
  110. package/dist/plugins/prebuilt.d.ts +6 -6
  111. package/dist/plugins/prerender-sugar.d.ts.map +1 -1
  112. package/dist/plugins/routing.d.ts +1 -1
  113. package/dist/plugins/routing.d.ts.map +1 -1
  114. package/dist/routing/index.js +2 -2
  115. package/dist/rsc-runtime/dev-reference-cache.d.ts +47 -0
  116. package/dist/rsc-runtime/dev-reference-cache.d.ts.map +1 -0
  117. package/dist/rsc-runtime/rsc.d.ts +0 -15
  118. package/dist/rsc-runtime/rsc.d.ts.map +1 -1
  119. package/dist/rsc-runtime/ssr.d.ts +0 -11
  120. package/dist/rsc-runtime/ssr.d.ts.map +1 -1
  121. package/dist/schema-bridge.d.ts +28 -19
  122. package/dist/schema-bridge.d.ts.map +1 -1
  123. package/dist/search-params/define.d.ts +1 -1
  124. package/dist/search-params/define.d.ts.map +1 -1
  125. package/dist/search-params/index.js +7 -8
  126. package/dist/search-params/index.js.map +1 -1
  127. package/dist/search-params/wrappers.d.ts +3 -3
  128. package/dist/server/abort-scope.d.ts +27 -0
  129. package/dist/server/abort-scope.d.ts.map +1 -0
  130. package/dist/server/flight-source-node.d.ts.map +1 -1
  131. package/dist/server/index.js +2 -2
  132. package/dist/server/instrumentation.d.ts +2 -1
  133. package/dist/server/instrumentation.d.ts.map +1 -1
  134. package/dist/server/internal.d.ts +1 -1
  135. package/dist/server/internal.d.ts.map +1 -1
  136. package/dist/server/internal.js +350 -151
  137. package/dist/server/internal.js.map +1 -1
  138. package/dist/server/logger.d.ts +9 -0
  139. package/dist/server/logger.d.ts.map +1 -1
  140. package/dist/server/pipeline-helpers.d.ts.map +1 -1
  141. package/dist/server/pipeline.d.ts +10 -7
  142. package/dist/server/pipeline.d.ts.map +1 -1
  143. package/dist/server/prebuilt/cache-key.d.ts +26 -0
  144. package/dist/server/prebuilt/cache-key.d.ts.map +1 -1
  145. package/dist/server/prebuilt/capture-render.d.ts +9 -4
  146. package/dist/server/prebuilt/capture-render.d.ts.map +1 -1
  147. package/dist/server/prebuilt/capture-routes.d.ts +1 -1
  148. package/dist/server/prebuilt/dev-store.d.ts +103 -0
  149. package/dist/server/prebuilt/dev-store.d.ts.map +1 -0
  150. package/dist/server/prebuilt/overlay.d.ts +14 -3
  151. package/dist/server/prebuilt/overlay.d.ts.map +1 -1
  152. package/dist/server/prebuilt/payload-source.d.ts +8 -0
  153. package/dist/server/prebuilt/payload-source.d.ts.map +1 -1
  154. package/dist/server/prebuilt/slots.d.ts +5 -6
  155. package/dist/server/prebuilt/slots.d.ts.map +1 -1
  156. package/dist/server/prebuilt-builder.d.ts.map +1 -1
  157. package/dist/server/prebuilt-runtime.d.ts +5 -10
  158. package/dist/server/prebuilt-runtime.d.ts.map +1 -1
  159. package/dist/server/render-timeout.d.ts.map +1 -1
  160. package/dist/server/rsc-entry/action-dispatcher.d.ts.map +1 -1
  161. package/dist/server/rsc-entry/index.d.ts.map +1 -1
  162. package/dist/server/ssr-render.d.ts.map +1 -1
  163. package/docs/api/32-api-cache.mdx +2 -0
  164. package/docs/api/33-api-search-params.mdx +3 -1
  165. package/docs/learn/06-typed-params.mdx +2 -2
  166. package/docs/learn/10-caching.mdx +12 -0
  167. package/docs/learn/11-middleware.mdx +2 -0
  168. package/package.json +1 -1
  169. package/src/cache/cache-api.ts +7 -1
  170. package/src/cache/guarded-read.ts +44 -0
  171. package/src/cache/handler-store.ts +38 -1
  172. package/src/cache/invalidation-epoch.ts +18 -6
  173. package/src/cache/timber-cache.ts +9 -3
  174. package/src/cdn/purge-store.ts +29 -1
  175. package/src/client/browser-entry/action-dispatch.ts +5 -5
  176. package/src/client/browser-entry/router-init.ts +2 -4
  177. package/src/client/global-context.ts +42 -14
  178. package/src/client/link.tsx +14 -18
  179. package/src/client/navigation-context.ts +4 -11
  180. package/src/client/navigation-transition.ts +86 -33
  181. package/src/client/params-context.ts +5 -17
  182. package/src/client/router-effects.ts +70 -45
  183. package/src/client/router-lifecycle.ts +1 -1
  184. package/src/client/router-pipeline.ts +52 -65
  185. package/src/client/router-types.ts +11 -31
  186. package/src/client/router.ts +98 -104
  187. package/src/client/segment-update-context.ts +1 -1
  188. package/src/client/slot-content-cache-context.ts +1 -1
  189. package/src/client/slot-context.ts +6 -17
  190. package/src/dev-tools/logs.ts +76 -50
  191. package/src/plugins/dev-server.ts +58 -9
  192. package/src/plugins/dev-store-clear.ts +47 -0
  193. package/src/plugins/entries.ts +6 -0
  194. package/src/plugins/orphaned-modules.ts +78 -0
  195. package/src/plugins/prebuilt.ts +17 -17
  196. package/src/plugins/prerender-sugar.ts +38 -6
  197. package/src/plugins/routing.ts +23 -1
  198. package/src/rsc-runtime/dev-reference-cache.ts +115 -0
  199. package/src/rsc-runtime/rsc.ts +10 -0
  200. package/src/rsc-runtime/ssr.ts +10 -0
  201. package/src/rsc-runtime/vendor-types.d.ts +8 -0
  202. package/src/schema-bridge.ts +93 -38
  203. package/src/search-params/define.ts +5 -6
  204. package/src/search-params/wrappers.ts +3 -3
  205. package/src/server/abort-scope.ts +49 -0
  206. package/src/server/action-handler.ts +18 -2
  207. package/src/server/flight-source-node.ts +5 -4
  208. package/src/server/instrumentation.ts +32 -8
  209. package/src/server/internal.ts +1 -6
  210. package/src/server/logger.ts +9 -0
  211. package/src/server/pipeline-helpers.ts +5 -3
  212. package/src/server/pipeline.ts +31 -20
  213. package/src/server/prebuilt/cache-key.ts +41 -0
  214. package/src/server/prebuilt/capture-render.ts +10 -6
  215. package/src/server/prebuilt/capture-routes.ts +1 -1
  216. package/src/server/prebuilt/dev-store.ts +173 -0
  217. package/src/server/prebuilt/overlay.ts +21 -5
  218. package/src/server/prebuilt/payload-source.ts +19 -0
  219. package/src/server/prebuilt/slots.ts +5 -6
  220. package/src/server/prebuilt-builder.ts +3 -2
  221. package/src/server/prebuilt-runtime.ts +194 -177
  222. package/src/server/render-timeout.ts +12 -17
  223. package/src/server/rsc-entry/action-dispatcher.ts +3 -1
  224. package/src/server/rsc-entry/index.ts +47 -13
  225. package/src/server/ssr-render.ts +9 -11
  226. package/dist/_chunks/cache-api-LA3sBpUS.js.map +0 -1
  227. package/dist/_chunks/chains-CDK1AWZQ.js +0 -1
  228. package/dist/_chunks/dev-server-DkytOEG2.js +0 -1
  229. package/dist/_chunks/dev-server-DnODXuNM.js.map +0 -1
  230. package/dist/_chunks/error-boundary-xxxLtXt6.js.map +0 -1
  231. package/dist/_chunks/flight-source-node-0dE-t3kq.js.map +0 -1
  232. package/dist/_chunks/node-response-Dibufw_b.js.map +0 -1
  233. package/dist/_chunks/purge-store-Byr8XOjU.js.map +0 -1
  234. package/dist/_chunks/render-timeout-DOf_BBcO.js.map +0 -1
  235. package/dist/_chunks/schema-bridge-C83xa9lT.js.map +0 -1
  236. package/dist/_chunks/segment-context-xtPUGfdq.js.map +0 -1
@@ -1,16 +1,19 @@
1
1
  /**
2
- * One build-time capture entry (server/prebuilt-builder.ts): render a
3
- * registered component in isolation under the synthetic build store and
4
- * drain its flight payload under a deadline.
2
+ * One build-time capture entry: render a registered component in isolation
3
+ * under the synthetic build store and drain its flight payload under a
4
+ * deadline. Run by the post-build capture pass (server/prebuilt-builder.ts)
5
+ * and, in dev, by the first request for a prerender entry
6
+ * (server/prebuilt-runtime.ts, TIM-1588) — which is why the flight renderer
7
+ * is a parameter: the request-time runtime renders through the functions
8
+ * the RSC entry injected.
5
9
  */
6
10
 
7
11
  import { createElement } from 'react';
8
12
 
9
13
  import { SlotOutlet } from '../../client/slot-outlet.tsx';
10
14
  import type { CoercedParams } from '../../shared/param-value.ts';
11
- import { renderFlight } from '../../rsc-runtime/rsc.ts';
12
15
  import { requestContextAls } from '../als-registry.ts';
13
- import { collectFlightBytes } from '../flight-source.ts';
16
+ import { collectFlightBytes, type RenderFlight } from '../flight-source.ts';
14
17
  import type { PrebuiltRegistration } from '../prebuilt-runtime.ts';
15
18
  import { createCaptureScope, type NestedWrapperRender } from './capture-state.ts';
16
19
  import { resolveTags } from './lifetime.ts';
@@ -53,7 +56,8 @@ export async function renderEntry(
53
56
  props: Record<string, unknown>,
54
57
  coercedParams: CoercedParams,
55
58
  timeoutMs: number,
56
- isLayout: boolean
59
+ isLayout: boolean,
60
+ renderFlight: RenderFlight
57
61
  ): Promise<EntryOutcome> {
58
62
  const storeHandle = createBuildTimeStore(registration.id, coercedParams);
59
63
  const { store, violations } = storeHandle;
@@ -27,7 +27,7 @@ export interface CandidateRoute {
27
27
  * layouts above it) has prebuilt components attributed to it. Slots and
28
28
  * intercepting/private segments are not walked — slot-scoped prebuilt is
29
29
  * already unkeyable at request time when slot params diverge (see
30
- * resolveKeyParams in prebuilt-runtime.ts), so the build doesn't model
30
+ * resolveKeyParams in prebuilt/cache-key.ts), so the build doesn't model
31
31
  * slots either.
32
32
  */
33
33
  export function collectCandidateRoutes(
@@ -0,0 +1,173 @@
1
+ /**
2
+ * Dev-mode store for cache.component output (TIM-1588, design/44 §Dev Mode).
3
+ *
4
+ * In production a `prerender` entry is captured at build time and frozen
5
+ * until the next deploy. Dev has no build step, so this in-memory store
6
+ * stands in for the build artifact: a prerender-tier render is captured on
7
+ * its first request (under the synthetic build store, so request-context
8
+ * reads fail exactly as `pnpm build` would) and served from here after
9
+ * that. Runtime-tier entries (`ttl`/`tags`) keep using the cache-handler
10
+ * overlay; in dev their keys carry this store's namespace (`overlayKey`).
11
+ *
12
+ * Invalidation is deliberately coarse: ANY dev-server watcher event clears
13
+ * everything. The dev-server plugin sends `PREBUILT_DEV_CLEAR_EVENT` to the
14
+ * RSC environment and the RSC entry calls `clearDevPrebuiltStore()`. There
15
+ * is no per-component dependency tracking — the module graph misses files
16
+ * read with `fs`, and one re-render per save is what dev used to pay on
17
+ * every request. A clear does three things:
18
+ *
19
+ * 1. drops every seed;
20
+ * 2. bumps the generation, which namespaces dev overlay keys, so
21
+ * runtime-tier entries stored before the save become unreachable;
22
+ * 3. records an invalidation of everything (`recordInvalidationOfAll`),
23
+ * so a capture already in flight — which may have loaded the
24
+ * pre-save code — is not stored, and a request arriving after the
25
+ * save does not join that flight (the TIM-1028 guard every capture
26
+ * path already runs).
27
+ *
28
+ * Inactive outside dev: production never enables it. Dev enables it only
29
+ * when HMR is on — with `server.hmr: false` Vite delivers no watcher events
30
+ * to plugins and nothing would clear the store, so dev bypasses caching
31
+ * entirely instead (`DevPrebuiltStoreMode`).
32
+ */
33
+
34
+ import { getCacheHandler } from '../../cache/handler-store.ts';
35
+ import { recordInvalidation, recordInvalidationOfAll } from '../../cache/invalidation-epoch.ts';
36
+
37
+ /** Custom HMR event the dev-server plugin sends to the RSC environment. */
38
+ export const PREBUILT_DEV_CLEAR_EVENT = 'timber:prebuilt-dev-clear';
39
+
40
+ /** One captured prerender-tier entry — the dev counterpart of a `.flight` seed. */
41
+ export interface DevSeed {
42
+ bytes: Uint8Array;
43
+ /** Resolved tags, so `revalidateTag` can drop an ISR seed. */
44
+ tags: string[];
45
+ /** Capture time; stands in for the manifest's buildTimestamp. */
46
+ capturedAt: number;
47
+ }
48
+
49
+ /**
50
+ * - `off`: production (and the default). Wrappers use the build artifact and
51
+ * the overlay.
52
+ * - `active`: dev with HMR. The dev store stands in for the build artifact.
53
+ * - `bypass`: dev without HMR (`server.hmr: false`). No watcher event would
54
+ * ever reach the store, so nothing is cached at all: every wrapper renders
55
+ * live, runtime-tier ones included (the overlay would otherwise hold
56
+ * entries a save never clears).
57
+ */
58
+ export type DevPrebuiltStoreMode = 'off' | 'active' | 'bypass';
59
+
60
+ let mode: DevPrebuiltStoreMode = 'off';
61
+ let generation = 0;
62
+ const seeds = new Map<string, DevSeed>();
63
+
64
+ /**
65
+ * Distinguishes this process's overlay keys from a previous dev session's,
66
+ * in case the configured cache handler outlives the process (Redis in dev).
67
+ * Created on first use, never at module load: production imports this
68
+ * module too, and Workers reject random-value generation in global scope.
69
+ * Global `crypto`, not node:crypto, because dev may run the RSC environment
70
+ * in workerd.
71
+ */
72
+ let processToken: string | null = null;
73
+
74
+ function seedKey(componentId: string, cacheKey: string): string {
75
+ return `${componentId}:${cacheKey}`;
76
+ }
77
+
78
+ /** Set by the RSC entry in dev (and by tests). The store starts empty either way. */
79
+ export function setDevPrebuiltStoreMode(next: DevPrebuiltStoreMode): void {
80
+ mode = next;
81
+ seeds.clear();
82
+ }
83
+
84
+ export function isDevPrebuiltStoreActive(): boolean {
85
+ return mode === 'active';
86
+ }
87
+
88
+ /** Dev without HMR: every cache.component wrapper renders live. */
89
+ export function isDevPrebuiltCacheBypassed(): boolean {
90
+ return mode === 'bypass';
91
+ }
92
+
93
+ /**
94
+ * Namespace for overlay keys while the dev store is active, in place of the
95
+ * deployment ID (which is null in dev). Changes on every clear. Null when
96
+ * inactive.
97
+ */
98
+ export function devOverlayNamespace(): string | null {
99
+ if (mode !== 'active') return null;
100
+ processToken ??= crypto.randomUUID().slice(0, 8);
101
+ return `dev-${processToken}-${generation}`;
102
+ }
103
+
104
+ /**
105
+ * The key a `cache.data` entry is stored under: the logical key, prefixed in
106
+ * dev with the namespace above. So a save makes every data entry stored
107
+ * before it unreachable, whatever the handler. A data function's ID comes
108
+ * from its call site, so editing a helper it calls, or a file it reads,
109
+ * would otherwise keep serving the old result to every component captured
110
+ * after the save. Invalidation epochs and singleflight stay on the logical
111
+ * key; only the handler sees the prefix.
112
+ */
113
+ export function devDataCacheKey(key: string): string {
114
+ const namespace = devOverlayNamespace();
115
+ return namespace === null ? key : `${namespace}\u0000${key}`;
116
+ }
117
+
118
+ export function getDevSeed(componentId: string, cacheKey: string): DevSeed | undefined {
119
+ return seeds.get(seedKey(componentId, cacheKey));
120
+ }
121
+
122
+ /**
123
+ * Store a captured seed. The caller has already checked that no clear (or
124
+ * tag invalidation) happened while it was capturing.
125
+ */
126
+ export function setDevSeed(componentId: string, cacheKey: string, seed: DevSeed): void {
127
+ seeds.set(seedKey(componentId, cacheKey), seed);
128
+ }
129
+
130
+ /** Drop everything — called on every dev-server watcher event. */
131
+ export function clearDevPrebuiltStore(): void {
132
+ seeds.clear();
133
+ generation++;
134
+ recordInvalidationOfAll();
135
+ }
136
+
137
+ /**
138
+ * A hard reload: discard one entry — its seed and its overlay record — so
139
+ * the request renders it again. Recorded as an invalidation of its key
140
+ * first, so a capture of it already in flight (which may have read the old
141
+ * external data) neither stores nor is joined by this request.
142
+ */
143
+ export async function discardDevEntry(
144
+ componentId: string,
145
+ cacheKey: string,
146
+ overlayKey: string
147
+ ): Promise<void> {
148
+ recordInvalidation({ key: overlayKey });
149
+ seeds.delete(seedKey(componentId, cacheKey));
150
+ await getCacheHandler().invalidate({ key: overlayKey });
151
+ }
152
+
153
+ /**
154
+ * `revalidateTag` in dev: drop the seeds carrying the tag. This is the dev
155
+ * counterpart of writing a tombstone over a build seed (design/45 §ISR
156
+ * mechanics) — the next request misses and captures again.
157
+ */
158
+ export function invalidateDevSeedsByTag(tag: string): void {
159
+ for (const [key, seed] of seeds) {
160
+ if (seed.tags.includes(tag)) seeds.delete(key);
161
+ }
162
+ }
163
+
164
+ /**
165
+ * Whether the request asks to skip caches — a browser hard reload, or any
166
+ * request while DevTools "Disable cache" is on, sends `Cache-Control:
167
+ * no-cache`. Dev only: the escape hatch for components that read external
168
+ * data (a CMS, a database) while it is being edited. Production never
169
+ * honors it — a client must not be able to force cache.component re-renders.
170
+ */
171
+ export function isHardReload(headers: Headers): boolean {
172
+ return /(?:^|,)\s*no-cache\s*(?:,|$)/i.test(headers.get('cache-control') ?? '');
173
+ }
@@ -15,7 +15,9 @@
15
15
 
16
16
  import { getCacheHandler, isCacheHandlerConfigured } from '../../cache/handler-store.ts';
17
17
  import { MemoryCacheHandler } from '../../cache/index.ts';
18
+ import { guardedRead } from '../../cache/guarded-read.ts';
18
19
  import { getDeploymentId } from '../version-skew.ts';
20
+ import { devOverlayNamespace } from './dev-store.ts';
19
21
  import { buildTagIndex, type SeedKeyInfo } from './manifest-tag-index.ts';
20
22
  import type { PrebuiltManifest } from './payload-source.ts';
21
23
  import { ensureManifestLoaded } from './payload-source.ts';
@@ -62,21 +64,34 @@ export function isTombstone(v: unknown): v is ComponentTombstoneRecord {
62
64
 
63
65
  // ─── Overlay key generation ──────────────────────────────────────────────
64
66
 
67
+ /**
68
+ * In dev the deployment ID is null; the dev store namespace stands in for
69
+ * it and changes on every source change, so entries stored before a save
70
+ * become unreachable (server/prebuilt/dev-store.ts).
71
+ */
65
72
  export function overlayKey(componentId: string, cacheKey: string): string {
66
- const deploymentId = getDeploymentId() ?? 'dev';
73
+ const deploymentId = getDeploymentId() ?? devOverlayNamespace() ?? 'dev';
67
74
  return `timber:c:${deploymentId}:${componentId}:${cacheKey}`;
68
75
  }
69
76
 
70
77
  // ─── Overlay read ────────────────────────────────────────────────────────
71
78
 
72
79
  export interface OverlayLookupResult {
73
- kind: 'fresh' | 'stale' | 'tombstone';
74
- /** The overlay value (null for tombstones). */
80
+ /**
81
+ * `unreadable`: the handler read threw or timed out (cache/guarded-read.ts).
82
+ * Not a miss — a miss falls through to the build seed, and the overlay the
83
+ * read could not reach may hold that seed's tombstone. The caller renders
84
+ * instead of trusting the seed.
85
+ */
86
+ kind: 'fresh' | 'stale' | 'tombstone' | 'unreadable';
87
+ /** The overlay value (null for tombstones and unreadable reads). */
75
88
  record: ComponentOverlayRecord | null;
76
- /** Raw flight payload bytes (decoded from base64). Null for tombstones. */
89
+ /** Raw flight payload bytes (decoded from base64). Null for tombstones and unreadable reads. */
77
90
  payload: Uint8Array | null;
78
91
  }
79
92
 
93
+ const READ_FAILED: unique symbol = Symbol('overlay read failed');
94
+
80
95
  /**
81
96
  * Look up an overlay entry in the cache handler.
82
97
  * Returns null on a clean miss (no overlay entry at all).
@@ -87,7 +102,8 @@ export async function lookupOverlay(
87
102
  ): Promise<OverlayLookupResult | null> {
88
103
  const handler = getCacheHandler();
89
104
  const key = overlayKey(componentId, cacheKey);
90
- const result = await handler.get(key);
105
+ const result = await guardedRead(key, () => handler.get(key), READ_FAILED);
106
+ if (result === READ_FAILED) return { kind: 'unreadable', record: null, payload: null };
91
107
  if (!result) return null;
92
108
 
93
109
  const value = result.value as OverlayValue;
@@ -200,3 +200,22 @@ export async function lookupPrebuiltPayload(
200
200
  return null;
201
201
  }
202
202
  }
203
+
204
+ /** A seed entry: build artifact bytes, or their dev-store counterpart. */
205
+ export interface Seed {
206
+ payload: Uint8Array;
207
+ /** When the seed was rendered — the logical start of its `ttl`. */
208
+ capturedAt: number;
209
+ }
210
+
211
+ /** The build-artifact seed for an entry, or null if the build has none. */
212
+ export async function lookupArtifactSeed(
213
+ id: string,
214
+ cacheKey: string,
215
+ needsTimestamp: boolean
216
+ ): Promise<Seed | null> {
217
+ const payload = await lookupPrebuiltPayload(id, cacheKey);
218
+ if (payload === null) return null;
219
+ const entry = needsTimestamp ? await getManifestEntry(id, cacheKey) : null;
220
+ return { payload, capturedAt: entry?.buildTimestamp ?? 0 };
221
+ }
@@ -8,9 +8,9 @@
8
8
  * TIM-1181 layout mechanism to explicitly declared, named slots on any
9
9
  * cached component. Layouts use the same mechanism with a `children` slot.
10
10
  *
11
- * Both the production wrapper (cache path) and the dev wrapper (no cache,
12
- * same tree shape for dev/prod parity) build their render from these
13
- * helpers. See design/45-cache-lifetimes.md §Slot Components.
11
+ * The `__prebuilt` wrapper builds its slot render from these helpers, in
12
+ * dev and production alike. See design/45-cache-lifetimes.md §Slot
13
+ * Components.
14
14
  */
15
15
 
16
16
  import { createElement } from 'react';
@@ -113,9 +113,8 @@ function isDenseStringArray(value: unknown): value is string[] {
113
113
  }
114
114
 
115
115
  /**
116
- * Validate the `slots` option. Both the production and dev wrappers gate
117
- * on this — slot substitution is active in dev exactly when it would be
118
- * active in production, so the tree shape a component sees never
116
+ * Validate the `slots` option. The `__prebuilt` wrapper gates on this in
117
+ * dev and production alike, so the tree shape a component sees never
119
118
  * diverges between the two.
120
119
  */
121
120
  export function resolveSlotNames(id: string, options: PrebuiltComponentOptions): SlotResolution {
@@ -58,7 +58,7 @@ import { BuildTimeContextError } from './prebuilt/synthetic-store.ts';
58
58
  import { getPrebuiltRegistration } from './prebuilt-runtime.ts';
59
59
  import { createRouteMatcher } from './route-matcher.ts';
60
60
  import type { ManifestRoot } from './route-matcher.ts';
61
- import { createFromReadableStream } from '../rsc-runtime/rsc.ts';
61
+ import { createFromReadableStream, renderFlight } from '../rsc-runtime/rsc.ts';
62
62
  import { loadModule } from './safe-load.ts';
63
63
  import { resolvePathWithParams } from './sitemap-generator.ts';
64
64
  import { resolveRenderTimeoutMs } from './render-timeout.ts';
@@ -390,7 +390,8 @@ export async function capturePrebuiltPayloads(
390
390
  callSiteProps,
391
391
  coercedParams,
392
392
  timeoutMs,
393
- isLayout
393
+ isLayout,
394
+ renderFlight
394
395
  );
395
396
  // Track param reads immediately — before any failure continue —
396
397
  // so a combo that reads params then fails still prevents