@timber-js/app 0.2.0-alpha.221 → 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 (118) hide show
  1. package/dist/_chunks/{actions-BDqn4Oxj.js → actions-vBHr2vqd.js} +3 -3
  2. package/dist/_chunks/{actions-BDqn4Oxj.js.map → actions-vBHr2vqd.js.map} +1 -1
  3. package/dist/_chunks/{cache-api-GE4AOe2H.js → cache-api-DdcDLpBj.js} +54 -6
  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-DIy-SY-J.js → dev-server-BNr5drEO.js} +49 -5
  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/{flight-source-node-HptmGMT8.js → flight-source-node-BdHUOUqg.js} +3 -3
  23. package/dist/_chunks/{flight-source-node-HptmGMT8.js.map → flight-source-node-BdHUOUqg.js.map} +1 -1
  24. package/dist/_chunks/global-context-B9PFncvb.js +48 -0
  25. package/dist/_chunks/global-context-B9PFncvb.js.map +1 -0
  26. package/dist/_chunks/{json-lossy-check-C8zBY2uZ.js → json-lossy-check-C3Sht92C.js} +2 -2
  27. package/dist/_chunks/{json-lossy-check-C8zBY2uZ.js.map → json-lossy-check-C3Sht92C.js.map} +1 -1
  28. package/dist/_chunks/{live-graph-tSWrv8eH.js → live-graph-DEu_GWbc.js} +4 -4
  29. package/dist/_chunks/{live-graph-tSWrv8eH.js.map → live-graph-DEu_GWbc.js.map} +1 -1
  30. package/dist/_chunks/{logger-CbLdcy-W.js → logger-CI_hThfy.js} +10 -2
  31. package/dist/_chunks/{logger-CbLdcy-W.js.map → logger-CI_hThfy.js.map} +1 -1
  32. package/dist/_chunks/{node-response-rkQqcFGq.js → node-response-bF0bKoig.js} +2 -2
  33. package/dist/_chunks/{node-response-rkQqcFGq.js.map → node-response-bF0bKoig.js.map} +1 -1
  34. package/dist/_chunks/{poison-scan-C4FgMxFl.js → poison-scan-DTWIfNgD.js} +2 -2
  35. package/dist/_chunks/{poison-scan-C4FgMxFl.js.map → poison-scan-DTWIfNgD.js.map} +1 -1
  36. package/dist/_chunks/{render-timeout-joFhz4KH.js → render-timeout-Ln_u7fX-.js} +19 -2
  37. package/dist/_chunks/{render-timeout-joFhz4KH.js.map → render-timeout-Ln_u7fX-.js.map} +1 -1
  38. package/dist/_chunks/{resolve-schema-CBR6Lm4i.js → resolve-schema-CkAInout.js} +2 -2
  39. package/dist/_chunks/{resolve-schema-CBR6Lm4i.js.map → resolve-schema-CkAInout.js.map} +1 -1
  40. package/dist/_chunks/{scanner-Cb3fSjAC.js → scanner-C8fdKvKG.js} +2 -2
  41. package/dist/_chunks/{scanner-Cb3fSjAC.js.map → scanner-C8fdKvKG.js.map} +1 -1
  42. package/dist/_chunks/{schema-bridge-C83xa9lT.js → schema-bridge-DpOmvZlI.js} +60 -23
  43. package/dist/_chunks/schema-bridge-DpOmvZlI.js.map +1 -0
  44. package/dist/_chunks/{segment-context-xtPUGfdq.js → segment-context-D3DNxKFq.js} +4 -8
  45. package/dist/_chunks/segment-context-D3DNxKFq.js.map +1 -0
  46. package/dist/_chunks/{sizeof-QPE5nd3u.js → sizeof-CO3dk0V1.js} +2 -2
  47. package/dist/_chunks/{sizeof-QPE5nd3u.js.map → sizeof-CO3dk0V1.js.map} +1 -1
  48. package/dist/_chunks/{walkers-qu8TpiLh.js → walkers-BqzxnwGC.js} +3 -3
  49. package/dist/_chunks/{walkers-qu8TpiLh.js.map → walkers-BqzxnwGC.js.map} +1 -1
  50. package/dist/adapters/cloudflare-kv-cache.js +1 -1
  51. package/dist/analyze/crawl-entry.js +3 -3
  52. package/dist/analyze/graph-command.js +2 -2
  53. package/dist/cache/guarded-read.d.ts +29 -0
  54. package/dist/cache/guarded-read.d.ts.map +1 -0
  55. package/dist/cache/index.js +2 -2
  56. package/dist/cache/stores/memory.js +1 -1
  57. package/dist/cache/timber-cache.d.ts.map +1 -1
  58. package/dist/cli.js +3 -3
  59. package/dist/client/global-context.d.ts +21 -1
  60. package/dist/client/global-context.d.ts.map +1 -1
  61. package/dist/client/index.js +3 -12
  62. package/dist/client/index.js.map +1 -1
  63. package/dist/client/internal.js +1 -1
  64. package/dist/client/navigation-context.d.ts.map +1 -1
  65. package/dist/client/params-context.d.ts.map +1 -1
  66. package/dist/client/slot-context.d.ts +2 -2
  67. package/dist/client/slot-context.d.ts.map +1 -1
  68. package/dist/codec.js +1 -1
  69. package/dist/cookies/index.js +1 -1
  70. package/dist/index.js +7 -7
  71. package/dist/params/index.js +1 -1
  72. package/dist/plugins/dev-server.d.ts +1 -1
  73. package/dist/plugins/dev-server.d.ts.map +1 -1
  74. package/dist/plugins/dev-store-clear.d.ts +28 -0
  75. package/dist/plugins/dev-store-clear.d.ts.map +1 -0
  76. package/dist/routing/index.js +2 -2
  77. package/dist/schema-bridge.d.ts +28 -19
  78. package/dist/schema-bridge.d.ts.map +1 -1
  79. package/dist/search-params/define.d.ts +1 -1
  80. package/dist/search-params/define.d.ts.map +1 -1
  81. package/dist/search-params/index.js +7 -8
  82. package/dist/search-params/index.js.map +1 -1
  83. package/dist/search-params/wrappers.d.ts +3 -3
  84. package/dist/server/index.js +2 -2
  85. package/dist/server/internal.js +27 -24
  86. package/dist/server/internal.js.map +1 -1
  87. package/dist/server/logger.d.ts +9 -0
  88. package/dist/server/logger.d.ts.map +1 -1
  89. package/dist/server/prebuilt/overlay.d.ts +9 -3
  90. package/dist/server/prebuilt/overlay.d.ts.map +1 -1
  91. package/dist/server/prebuilt-runtime.d.ts.map +1 -1
  92. package/docs/api/33-api-search-params.mdx +3 -1
  93. package/docs/learn/06-typed-params.mdx +2 -2
  94. package/package.json +1 -1
  95. package/src/cache/guarded-read.ts +44 -0
  96. package/src/cache/timber-cache.ts +4 -2
  97. package/src/client/global-context.ts +42 -14
  98. package/src/client/navigation-context.ts +4 -11
  99. package/src/client/params-context.ts +5 -17
  100. package/src/client/segment-update-context.ts +1 -1
  101. package/src/client/slot-content-cache-context.ts +1 -1
  102. package/src/client/slot-context.ts +6 -17
  103. package/src/plugins/dev-server.ts +37 -3
  104. package/src/plugins/dev-store-clear.ts +47 -0
  105. package/src/rsc-runtime/vendor-types.d.ts +8 -0
  106. package/src/schema-bridge.ts +93 -38
  107. package/src/search-params/define.ts +5 -6
  108. package/src/search-params/wrappers.ts +3 -3
  109. package/src/server/action-handler.ts +18 -2
  110. package/src/server/logger.ts +9 -0
  111. package/src/server/prebuilt/overlay.ts +14 -4
  112. package/src/server/prebuilt-runtime.ts +20 -1
  113. package/dist/_chunks/cache-api-GE4AOe2H.js.map +0 -1
  114. package/dist/_chunks/chains-CDK1AWZQ.js +0 -1
  115. package/dist/_chunks/dev-server-BiWNMBVU.js +0 -1
  116. package/dist/_chunks/dev-server-DIy-SY-J.js.map +0 -1
  117. package/dist/_chunks/schema-bridge-C83xa9lT.js.map +0 -1
  118. package/dist/_chunks/segment-context-xtPUGfdq.js.map +0 -1
@@ -142,6 +142,15 @@ export declare function logLossyCacheValue(data: {
142
142
  export declare function logCacheMiss(data: {
143
143
  cacheKey: string;
144
144
  }): void;
145
+ /**
146
+ * Log a cache read that threw or timed out and was served as a miss.
147
+ * Level: warn — the request still succeeds, but a failing store (Redis down,
148
+ * KV erroring) means every read is paying for a live fetch.
149
+ */
150
+ export declare function logCacheReadFailed(data: {
151
+ cacheKey: string;
152
+ error: unknown;
153
+ }): void;
145
154
  /**
146
155
  * Log an intentionally swallowed error. Provides observability into catch
147
156
  * blocks that are deliberately empty — the error is consumed, never rethrown.
@@ -1 +1 @@
1
- {"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/server/logger.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/server/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAIlD,6FAA6F;AAC7F,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACzD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC1D;AAQD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAEpD;AAED;;;GAGG;AACH,wBAAgB,SAAS,IAAI,YAAY,CAExC;AAsBD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,gBAAgB,CAAA;CAAE,GAC/D,IAAI,CAIN;AAED,4CAA4C;AAC5C,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,uFAAuF;IACvF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,IAAI,CAEP;AAED,0CAA0C;AAC1C,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAE/E;AAED,+CAA+C;AAC/C,wBAAgB,cAAc,CAAC,IAAI,EAAE;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,sFAAsF;IACtF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,IAAI,CAEP;AAED,kDAAkD;AAClD,wBAAgB,yBAAyB,CAAC,IAAI,EAAE;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,IAAI,CAEP;AAED,6DAA6D;AAC7D,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAG/F;AAED,mFAAmF;AACnF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAG/F;AAED,sDAAsD;AACtD,wBAAgB,cAAc,CAAC,IAAI,EAAE;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,IAAI,CAGP;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,IAAI,CAEP;AAED,iDAAiD;AACjD,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAE5D;AAED,0DAA0D;AAC1D,wBAAgB,cAAc,CAAC,IAAI,EAAE;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,IAAI,CAGP;AAED,0DAA0D;AAC1D,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAG1F;AAED,0DAA0D;AAC1D,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAEhE;AAED,sEAAsE;AACtE,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAED,sDAAsD;AACtD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAEnE;AAED,6DAA6D;AAC7D,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAEpF;AAED,qFAAqF;AACrF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAQlF;AAED,oCAAoC;AACpC,wBAAgB,YAAY,CAAC,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAE7D;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAEnF;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;CAAE,GAAG,IAAI,CAO/F"}
@@ -43,10 +43,16 @@ export declare function isTombstone(v: unknown): v is ComponentTombstoneRecord;
43
43
  */
44
44
  export declare function overlayKey(componentId: string, cacheKey: string): string;
45
45
  export interface OverlayLookupResult {
46
- kind: 'fresh' | 'stale' | 'tombstone';
47
- /** The overlay value (null for tombstones). */
46
+ /**
47
+ * `unreadable`: the handler read threw or timed out (cache/guarded-read.ts).
48
+ * Not a miss — a miss falls through to the build seed, and the overlay the
49
+ * read could not reach may hold that seed's tombstone. The caller renders
50
+ * instead of trusting the seed.
51
+ */
52
+ kind: 'fresh' | 'stale' | 'tombstone' | 'unreadable';
53
+ /** The overlay value (null for tombstones and unreadable reads). */
48
54
  record: ComponentOverlayRecord | null;
49
- /** Raw flight payload bytes (decoded from base64). Null for tombstones. */
55
+ /** Raw flight payload bytes (decoded from base64). Null for tombstones and unreadable reads. */
50
56
  payload: Uint8Array | null;
51
57
  }
52
58
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"overlay.d.ts","sourceRoot":"","sources":["../../../src/server/prebuilt/overlay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAW5D;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,IAAI,CAAC;IACT,2CAA2C;IAC3C,CAAC,EAAE,MAAM,CAAC;IACV,4DAA4D;IAC5D,EAAE,EAAE,MAAM,CAAC;IACX,yDAAyD;IACzD,CAAC,EAAE,OAAO,CAAC;CACZ;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,IAAI,CAAC;CACV;AAID,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,sBAAsB,CAEvE;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,wBAAwB,CAErE;AAID;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGxE;AAID,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,WAAW,CAAC;IACtC,+CAA+C;IAC/C,MAAM,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACtC,2EAA2E;IAC3E,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC;CAC5B;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAoBrC;AAID;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAE5D;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,UAAU,EACxB,IAAI,EAAE;IACJ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CAClB,GACA,OAAO,CAAC,IAAI,CAAC,CAcf;AAMD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAG7D;AAED;;;GAGG;AACH,wBAAgB,WAAW,IAAI,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,GAAG,IAAI,CAE/D;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAEpC;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBtE;AA8BD;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}
1
+ {"version":3,"file":"overlay.d.ts","sourceRoot":"","sources":["../../../src/server/prebuilt/overlay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAOH,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAW5D;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,IAAI,CAAC;IACT,2CAA2C;IAC3C,CAAC,EAAE,MAAM,CAAC;IACV,4DAA4D;IAC5D,EAAE,EAAE,MAAM,CAAC;IACX,yDAAyD;IACzD,CAAC,EAAE,OAAO,CAAC;CACZ;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,IAAI,CAAC;CACV;AAID,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,sBAAsB,CAEvE;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,wBAAwB,CAErE;AAID;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGxE;AAID,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,WAAW,GAAG,YAAY,CAAC;IACrD,oEAAoE;IACpE,MAAM,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACtC,gGAAgG;IAChG,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC;CAC5B;AAID;;;GAGG;AACH,wBAAsB,aAAa,CACjC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAqBrC;AAID;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAE5D;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,UAAU,EACxB,IAAI,EAAE;IACJ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CAClB,GACA,OAAO,CAAC,IAAI,CAAC,CAcf;AAMD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAG7D;AAED;;;GAGG;AACH,wBAAgB,WAAW,IAAI,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,GAAG,IAAI,CAE/D;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAEpC;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBtE;AA8BD;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}
@@ -1 +1 @@
1
- {"version":3,"file":"prebuilt-runtime.d.ts","sourceRoot":"","sources":["../../src/server/prebuilt-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AA8CH,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAkB3E;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAGlE;AAYD;;;;;;GAMG;AACH,MAAM,WAAW,wBAAwB;IACvC,wEAAwE;IACxE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC;IACjE,2EAA2E;IAC3E,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;;;;OAIG;IACH,8BAA8B,CAAC,EAAE,OAAO,CAAC;CAC1C;AAED,2DAA2D;AAE3D,KAAK,eAAe,GAAG,CAAC,KAAK,EAAE,GAAG,KAAK,OAAO,CAAC;AAY/C,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,eAAe,CAAC;IAC3B,OAAO,EAAE,wBAAwB,CAAC;CACnC;AAoDD,UAAU,YAAY;IACpB,wBAAwB,EAAE,CAAC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACnF,YAAY,EAAE,YAAY,CAAC;CAC5B;AAID;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAEvD;AAidD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,eAAe,EAClD,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,CAAC,EACZ,OAAO,GAAE,wBAA6B,GACrC,CAAC,CAsFH;AAED,qDAAqD;AACrD,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS,CAEpF;AAED,qEAAqE;AACrE,wBAAgB,mBAAmB,IAAI,WAAW,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAE/E"}
1
+ {"version":3,"file":"prebuilt-runtime.d.ts","sourceRoot":"","sources":["../../src/server/prebuilt-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AA+CH,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAkB3E;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAGlE;AAYD;;;;;;GAMG;AACH,MAAM,WAAW,wBAAwB;IACvC,wEAAwE;IACxE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC;IACjE,2EAA2E;IAC3E,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;;;;OAIG;IACH,8BAA8B,CAAC,EAAE,OAAO,CAAC;CAC1C;AAED,2DAA2D;AAE3D,KAAK,eAAe,GAAG,CAAC,KAAK,EAAE,GAAG,KAAK,OAAO,CAAC;AAY/C,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,eAAe,CAAC;IAC3B,OAAO,EAAE,wBAAwB,CAAC;CACnC;AAoDD,UAAU,YAAY;IACpB,wBAAwB,EAAE,CAAC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACnF,YAAY,EAAE,YAAY,CAAC;CAC5B;AAID;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAEvD;AAmeD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,eAAe,EAClD,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,CAAC,EACZ,OAAO,GAAE,wBAA6B,GACrC,CAAC,CAsFH;AAED,qDAAqD;AACrD,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS,CAEpF;AAED,qEAAqE;AACrE,wBAAgB,mBAAmB,IAAI,WAAW,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAE/E"}
@@ -129,6 +129,8 @@ Compatible codecs:
129
129
 
130
130
  Timber does not ship or re-export `parseAs*` parsers. Import them from [nuqs](https://nuqs.47ng.com/), which is a peer dependency; timber ships the wrappers (`withDefault`, `withUrlKey`) and the schema bridge.
131
131
 
132
+ Import parsers from `nuqs/server`, not `nuqs`. A search-params definition is loaded by server components, and the `nuqs` entry is marked `'use client'`, so on the server its parsers are client references: calling one throws. `nuqs/server` exports the same parsers with no directive, so it works on both sides.
133
+
132
134
  nuqs checks whether a param is present before calling `parse`, so a parser's `parse` assumes a present scalar. Timber calls the parser's `parseServerSide` instead — nuqs's own adapter for the raw URL value — so every **single**-value parser is total:
133
135
 
134
136
  | Raw value | Result |
@@ -158,7 +160,7 @@ Wrap a codec to supply a value whenever the inner codec produces none — `null`
158
160
 
159
161
  ```ts
160
162
  import { withDefault } from '@timber-js/app/search-params';
161
- import { parseAsInteger } from 'nuqs';
163
+ import { parseAsInteger } from 'nuqs/server';
162
164
  const page = withDefault(parseAsInteger, 1); // number (never null)
163
165
  ```
164
166
 
@@ -116,7 +116,7 @@ Declare typed search params with `defineSearchParams` in any module, then import
116
116
 
117
117
  ```ts title="app/products/search-params.ts" id="search-params"
118
118
  import { defineSearchParams, withDefault } from '@timber-js/app/search-params';
119
- import { parseAsInteger } from 'nuqs';
119
+ import { parseAsInteger } from 'nuqs/server';
120
120
  import { z } from 'zod/v4';
121
121
 
122
122
  export const searchParams = defineSearchParams({
@@ -239,7 +239,7 @@ Compose codec maps via plain object spread:
239
239
 
240
240
  ```ts title="lib/search-params/pagination.ts"
241
241
  import { withDefault } from '@timber-js/app/search-params';
242
- import { parseAsInteger } from 'nuqs';
242
+ import { parseAsInteger } from 'nuqs/server';
243
243
 
244
244
  export const pagination = {
245
245
  page: withDefault(parseAsInteger, 1),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@timber-js/app",
3
- "version": "0.2.0-alpha.221",
3
+ "version": "0.2.0-alpha.222",
4
4
  "description": "Vite-native React framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript",
5
5
  "keywords": [
6
6
  "cloudflare-workers",
@@ -0,0 +1,44 @@
1
+ /**
2
+ * Cache reads never fail a request.
3
+ *
4
+ * A cache is an optimization: when the store is down, slow, or returns
5
+ * garbage, the request must still succeed by doing the work the cache would
6
+ * have skipped. Writes already follow this rule (timber-cache.ts swallows a
7
+ * failed handler.set, TIM-1046); reads go through here so a throwing or hung
8
+ * handler.get costs a live fetch or render, never a failed or stalled request.
9
+ *
10
+ * The timeout matters as much as the catch. Shared-store clients often queue
11
+ * commands while disconnected (ioredis retries each one up to 20 times by
12
+ * default), so an outage shows up as a read that never settles, not an error.
13
+ *
14
+ * Invalidation is deliberately NOT guarded: a failed invalidate that looked
15
+ * like success would leave stale data in place silently.
16
+ *
17
+ * See design/06-caching.md §"Store failures".
18
+ */
19
+
20
+ import { logCacheReadFailed } from '../server/logger.ts';
21
+ import { withTimeout } from '../server/render-timeout.ts';
22
+
23
+ /** Ceiling for a single cache read. A healthy store answers in milliseconds. */
24
+ export const CACHE_READ_TIMEOUT_MS = 1_000;
25
+
26
+ /**
27
+ * Run a cache read. A throw, a rejection, or no answer within
28
+ * CACHE_READ_TIMEOUT_MS logs a warning and resolves to `onFailure`, which the
29
+ * caller picks: `null` where a failed read means "miss", a distinct value
30
+ * where a miss would fall back to something the failed read might have
31
+ * overridden (an invalidated build seed — server/prebuilt/overlay.ts).
32
+ */
33
+ export async function guardedRead<T, F>(
34
+ cacheKey: string,
35
+ read: () => Promise<T>,
36
+ onFailure: F
37
+ ): Promise<T | F> {
38
+ try {
39
+ return await withTimeout(read(), CACHE_READ_TIMEOUT_MS, `cache read for "${cacheKey}"`);
40
+ } catch (error) {
41
+ logCacheReadFailed({ cacheKey, error });
42
+ return onFailure;
43
+ }
44
+ }
@@ -7,7 +7,8 @@ import {
7
7
  wasInvalidatedSince,
8
8
  } from './invalidation-epoch.ts';
9
9
  import { addSpanEventSync } from '../server/tracing.ts';
10
- import { logSwrRefetchFailed, swallow } from '../server/logger.ts';
10
+ import { logCacheMiss, logSwrRefetchFailed, swallow } from '../server/logger.ts';
11
+ import { guardedRead } from './guarded-read.ts';
11
12
  import { getWaitUntil } from '../server/waituntil-bridge.ts';
12
13
  import { fnv1aHash } from './fast-hash.ts';
13
14
  import { devDataCacheKey } from '../server/prebuilt/dev-store.ts';
@@ -157,7 +158,7 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
157
158
  const storeKey = devDataCacheKey(key);
158
159
 
159
160
  const cacheStart = performance.now();
160
- const cached = await getHandler().get(storeKey);
161
+ const cached = await guardedRead(key, () => getHandler().get(storeKey), null);
161
162
 
162
163
  if (cached && !cached.stale) {
163
164
  // Record as OTEL span event on enclosing span (not a child span).
@@ -246,6 +247,7 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
246
247
  key,
247
248
  duration_ms: Math.round(performance.now() - cacheStart),
248
249
  });
250
+ logCacheMiss({ cacheKey: key });
249
251
 
250
252
  return result;
251
253
  }) as unknown as Fn;
@@ -8,24 +8,52 @@
8
8
  * level would create separate instances per chunk. globalThis guarantees a
9
9
  * single instance regardless of duplication.
10
10
  *
11
+ * One context per React instance, not per process. Duplicated chunks share
12
+ * one React, so they share the context. A dev SSR program reload evaluates
13
+ * React and react-dom/server again, in the same process: the new renderer
14
+ * must get a context of its own. Handed the previous one, React logs
15
+ * "Detected multiple renderers concurrently rendering the same context
16
+ * provider" on every client-component edit, and the stale context keeps a
17
+ * piece of the discarded copy alive (TIM-1590).
18
+ *
11
19
  * See design/19-client-navigation.md §"Singleton Guarantee via globalThis"
12
20
  */
13
21
 
14
- 'use client';
15
-
16
22
  import React from 'react';
17
23
 
18
- export function createGlobalContext<T>(key: string, defaultValue: T): React.Context<T> {
19
- const g = globalThis as Record<symbol, unknown>;
20
- const sym = Symbol.for(key);
21
- const existing = g[sym] as React.Context<T> | undefined;
22
- if (existing !== undefined) return existing;
23
- if (typeof React.createContext === 'function') {
24
- const ctx = React.createContext<T>(defaultValue);
25
- g[sym] = ctx;
26
- return ctx;
24
+ /** The part of a React instance a context comes from. */
25
+ export interface ContextFactory {
26
+ createContext?: typeof React.createContext;
27
+ }
28
+
29
+ /**
30
+ * The context `key` names for this React instance, created on first use.
31
+ * Pass the key as a `Symbol.for('…')` literal at the call site, so each key
32
+ * stays greppable in the build output (tests/bundle-singleton-audit.test.ts
33
+ * checks `__timber_nav_ctx`).
34
+ */
35
+ export function createGlobalContext<T>(key: symbol, defaultValue: T): React.Context<T> {
36
+ return createGlobalContextFor(React, key, defaultValue);
37
+ }
38
+
39
+ /** createGlobalContext for a given React instance. Exported for tests. */
40
+ export function createGlobalContextFor<T>(
41
+ react: ContextFactory,
42
+ key: symbol,
43
+ defaultValue: T
44
+ ): React.Context<T> {
45
+ if (typeof react.createContext !== 'function') {
46
+ // RSC environment — createContext not available. Return a dummy that
47
+ // won't be used (the consumers only render on the client / during SSR).
48
+ return undefined as unknown as React.Context<T>;
49
+ }
50
+ const slot: unknown = Reflect.get(globalThis, key);
51
+ const byReact = slot instanceof WeakMap ? slot : new WeakMap<object, React.Context<T>>();
52
+ if (byReact !== slot) Reflect.set(globalThis, key, byReact);
53
+ let ctx: React.Context<T> | undefined = byReact.get(react);
54
+ if (!ctx) {
55
+ ctx = react.createContext<T>(defaultValue);
56
+ byReact.set(react, ctx);
27
57
  }
28
- // RSC environment — createContext not available. Return a dummy that
29
- // won't be used (the consumers only render on the client / during SSR).
30
- return undefined as unknown as React.Context<T>;
58
+ return ctx;
31
59
  }
@@ -42,7 +42,8 @@
42
42
  * See design/19-client-navigation.md §"NavigationContext"
43
43
  */
44
44
 
45
- import { createContext, useContext, createElement, type ReactNode } from 'react';
45
+ import { useContext, createElement, type ReactNode } from 'react';
46
+ import { createGlobalContext } from './global-context.ts';
46
47
 
47
48
  // ---------------------------------------------------------------------------
48
49
  // Context type
@@ -80,19 +81,11 @@ export interface NavigationState {
80
81
  * The shims plugin resolves next/navigation to navigation-rsc.ts in RSC,
81
82
  * which has throwing stubs for the hooks (TIM-1420).
82
83
  *
83
- * See design/27-chunking-strategy.md §"Singleton Safety"
84
+ * See design/19-client-navigation.md §"Singleton Guarantee via globalThis"
84
85
  */
85
86
 
86
- const NAV_CTX_KEY = Symbol.for('__timber_nav_ctx');
87
-
88
87
  function getOrCreateContext(): import('react').Context<NavigationState | null> {
89
- const existing = (globalThis as Record<symbol, unknown>)[NAV_CTX_KEY] as
90
- | import('react').Context<NavigationState | null>
91
- | undefined;
92
- if (existing !== undefined) return existing;
93
- const ctx = createContext<NavigationState | null>(null);
94
- (globalThis as Record<symbol, unknown>)[NAV_CTX_KEY] = ctx;
95
- return ctx;
88
+ return createGlobalContext<NavigationState | null>(Symbol.for('__timber_nav_ctx'), null);
96
89
  }
97
90
 
98
91
  /**
@@ -34,6 +34,7 @@ import React, { createElement, useMemo, use } from 'react';
34
34
  import { toNullProtoRecord, type CoercedParams } from '../shared/param-value.ts';
35
35
  import { readPublishedParams, type PublishedParams } from '../shared/payload-root.ts';
36
36
  import type { SlotParamsRecord } from '../shared/slot-params.ts';
37
+ import { createGlobalContext } from './global-context.ts';
37
38
 
38
39
  // ─── Types ───────────────────────────────────────────────────────
39
40
 
@@ -72,23 +73,10 @@ export type ParamsContextValue = PublishedParams;
72
73
  *
73
74
  * See design/19-client-navigation.md §"Singleton Guarantee via globalThis"
74
75
  */
75
- const PARAMS_CTX_KEY = Symbol.for('__timber_params_ctx');
76
-
77
- function getOrCreateContext(): React.Context<ParamsContextValue | null> {
78
- const store = globalThis as Record<symbol, unknown>;
79
- const existing = store[PARAMS_CTX_KEY] as React.Context<ParamsContextValue | null> | undefined;
80
- if (existing !== undefined) return existing;
81
- if (typeof React.createContext !== 'function') {
82
- // RSC environment — no contexts here. Nothing in this module runs on that
83
- // side; it only has to import cleanly.
84
- return undefined as unknown as React.Context<ParamsContextValue | null>;
85
- }
86
- const ctx = React.createContext<ParamsContextValue | null>(null);
87
- store[PARAMS_CTX_KEY] = ctx;
88
- return ctx;
89
- }
90
-
91
- const ParamsContext = getOrCreateContext();
76
+ const ParamsContext = createGlobalContext<ParamsContextValue | null>(
77
+ Symbol.for('__timber_params_ctx'),
78
+ null
79
+ );
92
80
 
93
81
  /**
94
82
  * Read the params provided by the tree. Returns null only when no provider
@@ -18,6 +18,6 @@ import { createGlobalContext } from './global-context.ts';
18
18
  export const EMPTY_SEGMENT_UPDATES = new Map<string, ReactNode>();
19
19
 
20
20
  export const SegmentUpdateContext = createGlobalContext<Map<string, ReactNode>>(
21
- '__timber_segment_update_ctx',
21
+ Symbol.for('__timber_segment_update_ctx'),
22
22
  EMPTY_SEGMENT_UPDATES
23
23
  );
@@ -38,6 +38,6 @@ import { createGlobalContext } from './global-context.ts';
38
38
  export type SlotContentCache = Map<string, ReactNode>;
39
39
 
40
40
  export const SlotContentCacheContext = createGlobalContext<SlotContentCache | null>(
41
- '__timber_slot_content_cache_ctx',
41
+ Symbol.for('__timber_slot_content_cache_ctx'),
42
42
  null
43
43
  );
@@ -28,23 +28,12 @@
28
28
 
29
29
  'use client';
30
30
 
31
- import React, { type ReactNode } from 'react';
31
+ import { type ReactNode } from 'react';
32
+ import { createGlobalContext } from './global-context.ts';
32
33
 
33
34
  export type SlotValues = Record<string, ReactNode>;
34
35
 
35
- const CTX_KEY = Symbol.for('__timber_slot_ctx');
36
-
37
- function getOrCreateContext(): React.Context<SlotValues | null> {
38
- const existing = (globalThis as Record<symbol, unknown>)[CTX_KEY] as
39
- | React.Context<SlotValues | null>
40
- | undefined;
41
- if (existing !== undefined) return existing;
42
- if (typeof React.createContext === 'function') {
43
- const ctx = React.createContext<SlotValues | null>(null);
44
- (globalThis as Record<symbol, unknown>)[CTX_KEY] = ctx;
45
- return ctx;
46
- }
47
- return undefined as unknown as React.Context<SlotValues | null>;
48
- }
49
-
50
- export const SlotContext = getOrCreateContext();
36
+ export const SlotContext = createGlobalContext<SlotValues | null>(
37
+ Symbol.for('__timber_slot_ctx'),
38
+ null
39
+ );
@@ -12,7 +12,7 @@
12
12
  * Design docs: 18-build-system.md §"Dev Server", 02-rendering-pipeline.md
13
13
  */
14
14
 
15
- import type { Plugin, ViteDevServer, DevEnvironment } from 'vite';
15
+ import { loadConfigFromFile, type Plugin, type ViteDevServer, type DevEnvironment } from 'vite';
16
16
  import type { IncomingMessage, ServerResponse } from 'node:http';
17
17
  import type { TLSSocket } from 'node:tls';
18
18
  import { existsSync, realpathSync, statSync } from 'node:fs';
@@ -42,6 +42,7 @@ import { compressResponse } from '../server/compress.ts';
42
42
  import { isMetadataRouteServePath } from '../server/metadata-routes.ts';
43
43
  import { canonicalize } from '../server/canonicalize.ts';
44
44
  import { PREBUILT_DEV_CLEAR_EVENT } from '../server/prebuilt/dev-store.ts';
45
+ import { clearDevStoreOnWatcherEvents } from './dev-store-clear.ts';
45
46
  import { matchUrlParts } from '../server/tree-match.ts';
46
47
  import type { RouteTree } from '../routing/types.ts';
47
48
 
@@ -159,6 +160,38 @@ export function timberDevServer(ctx: PluginContext): Plugin {
159
160
  server.watcher.on('add', onConfigChange);
160
161
  server.watcher.on('unlink', onConfigChange);
161
162
 
163
+ // Vite's own restarts (vite.config.ts or one of its dependencies, a
164
+ // .env file) go through server.restart(), which
165
+ // builds a new server in this process and leaks the old one through
166
+ // rolldown's native resolver (rolldown#10887). Under the supervisor,
167
+ // restart the process instead, as timber.config.ts changes do
168
+ // (TIM-1590). The new config is loaded here first: a vite.config.ts
169
+ // that fails to evaluate would fail the new worker's startup, and the
170
+ // supervisor respawns only on RESTART_EXIT_CODE, so exiting would take
171
+ // the dev server down. Vite's own restart keeps the old server then.
172
+ if (hasSupervisor) {
173
+ server.restart = async () => {
174
+ const { configFile, mode, root, logger } = server.config;
175
+ try {
176
+ await loadConfigFromFile(
177
+ { command: 'serve', mode },
178
+ configFile || undefined,
179
+ root,
180
+ 'silent'
181
+ );
182
+ } catch (error) {
183
+ logger.error(
184
+ `[timber] ${configFile ? basename(configFile) : 'Vite config'} failed to load — ` +
185
+ `keeping the running server.\n${error instanceof Error ? error.message : String(error)}`,
186
+ { timestamp: true }
187
+ );
188
+ return;
189
+ }
190
+ console.log('\n[timber] Restarting the dev server process...\n');
191
+ process.exit(RESTART_EXIT_CODE);
192
+ };
193
+ }
194
+
162
195
  // Listen for client-side errors forwarded from the browser.
163
196
  // The browser entry sends 'timber:client-error' events via HMR
164
197
  // for uncaught errors and unhandled rejections. We echo them back
@@ -179,9 +212,10 @@ export function timberDevServer(ctx: PluginContext): Plugin {
179
212
  // listener (timber-routing's reloads included), before Vite's own
180
213
  // handling sends any HMR update. A browser that a reload or update
181
214
  // makes refetch can only reach the server after the clear has gone
182
- // out.
215
+ // out. A trailing clear covers the saves the watcher drops
216
+ // (dev-store-clear.ts).
183
217
  const rscHot = server.environments.rsc?.hot;
184
- server.watcher.on('all', () => {
218
+ clearDevStoreOnWatcherEvents(server.watcher, () => {
185
219
  rscHot?.send({ type: 'custom', event: PREBUILT_DEV_CLEAR_EVENT });
186
220
  });
187
221
  graphChannel = makeGraphUpdateChannel(
@@ -0,0 +1,47 @@
1
+ /**
2
+ * Clear the cache.component dev store on every dev-server watcher event
3
+ * (TIM-1588, server/prebuilt/dev-store.ts) — and once more shortly after.
4
+ *
5
+ * Vite's watcher (chokidar) throttles `change`: once it emits one for a
6
+ * path, it DROPS every further `change` for that path for 50ms, and never
7
+ * emits a trailing event for them. So a save is invisible when it lands
8
+ * inside that window, which is easy to hit: save a file, the next request
9
+ * renders and stores it in a few milliseconds, save again (an editor that
10
+ * writes twice, a script that rewrites a file the page reads with fs).
11
+ * The store keeps the first save's render until some later, unrelated
12
+ * save. Before the store, a dropped event cost nothing: a file read with
13
+ * fs was read again on every request.
14
+ *
15
+ * The trailing clear lands after that window closes, so it follows any
16
+ * write whose event was dropped. A render that started before it cannot
17
+ * store (the clear records an invalidation of everything), and a render
18
+ * after it reads the file as written. Debounced, so a burst of saves gets
19
+ * one trailing clear, after the last of them. The cost is at most one
20
+ * extra re-render per save, in dev only.
21
+ */
22
+
23
+ /** chokidar's per-path `change` throttle (`_throttle(EV_CHANGE, path, 50)`). */
24
+ const WATCHER_CHANGE_THROTTLE_MS = 50;
25
+
26
+ /**
27
+ * Comfortably past the throttle window. Both are timers started in the same
28
+ * synchronous emit, so this one always fires after the throttle has expired,
29
+ * however late the event loop runs them.
30
+ */
31
+ const TRAILING_CLEAR_DELAY_MS = WATCHER_CHANGE_THROTTLE_MS * 2;
32
+
33
+ /** The part of Vite's `FSWatcher` this needs. */
34
+ interface WatcherEvents {
35
+ on(event: 'all', listener: () => void): unknown;
36
+ }
37
+
38
+ export function clearDevStoreOnWatcherEvents(watcher: WatcherEvents, clear: () => void): void {
39
+ let trailing: ReturnType<typeof setTimeout> | undefined;
40
+ watcher.on('all', () => {
41
+ clear();
42
+ clearTimeout(trailing);
43
+ trailing = setTimeout(clear, TRAILING_CLEAR_DELAY_MS);
44
+ // Never the reason the dev process stays alive.
45
+ trailing.unref?.();
46
+ });
47
+ }
@@ -53,6 +53,14 @@ declare module '@vitejs/plugin-rsc/vendor/react-server-dom/server.edge' {
53
53
  manifest: unknown,
54
54
  options?: { temporaryReferences?: unknown; arraySizeLimit?: number }
55
55
  ): Promise<unknown[]>;
56
+
57
+ // Tests stub `loadServerAction` with functions registered the way the
58
+ // use-server transform registers a module's exports.
59
+ export function registerServerReference<T extends Function>(
60
+ reference: T,
61
+ id: string,
62
+ exportName: string | null
63
+ ): T;
56
64
  }
57
65
 
58
66
  // src decodes through plugin-rsc's wrappers; tests decode a Flight response