@timber-js/app 0.2.0-alpha.165 → 0.2.0-alpha.167

package/dist/server/route-element-builder.d.ts

@@ -73,6 +73,15 @@ export interface RouteElementResult {
      * See design/19-client-navigation.md §"X-Timber-State-Tree Header"
      */
     skippedSegments: string[];
+    /**
+     * Resolves when every deny-capable shell component (PageDenyBoundary and
+     * each TracedLayout with a deny page chain) has finished executing, OR
+     * immediately when any of them catches a DenySignal in-tree (the HTTP
+     * status is known at that point; inner components may never run).
+     * Undefined when the route has no deny-capable server components.
+     * See TIM-1045 (pages), TIM-1208 (layouts).
+     */
+    shellSettled?: Promise<void>;
 }
 /**
  * Build a React element tree from a matched route.

package/dist/server/route-element-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route-element-builder.d.ts","sourceRoot":"","sources":["../../src/server/route-element-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AA4B9D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,KAAK,CAAC,YAAY,CAW/E;AAwCD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,OAAO,GAAG,OAAO,CAM7D;AAID;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAI5B;AAID,+CAA+C;AAC/C,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;IAC3C,OAAO,EAAE,mBAAmB,CAAC;CAC9B;AAED,+CAA+C;AAC/C,MAAM,WAAW,kBAAkB;IACjC,wFAAwF;IACxF,OAAO,EAAE,KAAK,CAAC,YAAY,CAAC;IAC5B,wDAAwD;IACxD,gBAAgB,EAAE,oBAAoB,EAAE,CAAC;IACzC,qCAAqC;IACrC,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,4DAA4D;IAC5D,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AA8DD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,YAAY,CAAC,EAAE,mBAAmB,EAClC,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,EACpC,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC3C,OAAO,CAAC,kBAAkB,CAAC,CA0gB7B"}
+{"version":3,"file":"route-element-builder.d.ts","sourceRoot":"","sources":["../../src/server/route-element-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AA6B9D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,KAAK,CAAC,YAAY,CAW/E;AAwCD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,OAAO,GAAG,OAAO,CAM7D;AAID;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAI5B;AAID,+CAA+C;AAC/C,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;IAC3C,OAAO,EAAE,mBAAmB,CAAC;CAC9B;AAED,+CAA+C;AAC/C,MAAM,WAAW,kBAAkB;IACjC,wFAAwF;IACxF,OAAO,EAAE,KAAK,CAAC,YAAY,CAAC;IAC5B,wDAAwD;IACxD,gBAAgB,EAAE,oBAAoB,EAAE,CAAC;IACzC,qCAAqC;IACrC,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,4DAA4D;IAC5D,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AA8DD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,YAAY,CAAC,EAAE,mBAAmB,EAClC,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,EACpC,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC3C,OAAO,CAAC,kBAAkB,CAAC,CAyiB7B"}

package/dist/server/rsc-entry/render-route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-route.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/render-route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAW1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,KAAK,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAMtE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAa/D;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,eAAe,EAAE,qBAAqB,CAAC;IACvC,gBAAgB,EAAE,OAAO,CAAC;IAC1B,WAAW,EAAE,mBAAmB,CAAC;IACjC,aAAa,EAAE,aAAa,CAAC;IAC7B,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;CAClE;AAED;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,OAAO,EACxB,IAAI,EAAE,eAAe,EACrB,YAAY,CAAC,EAAE,mBAAmB,GACjC,OAAO,CAAC,QAAQ,CAAC,CA+MnB"}
+{"version":3,"file":"render-route.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/render-route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAW1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,KAAK,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAMtE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAa/D;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,eAAe,EAAE,qBAAqB,CAAC;IACvC,gBAAgB,EAAE,OAAO,CAAC;IAC1B,WAAW,EAAE,mBAAmB,CAAC;IACjC,aAAa,EAAE,aAAa,CAAC;IAC7B,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;CAClE;AAED;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,OAAO,EACxB,IAAI,EAAE,eAAe,EACrB,YAAY,CAAC,EAAE,mBAAmB,GACjC,OAAO,CAAC,QAAQ,CAAC,CAiNnB"}

package/dist/server/rsc-entry/rsc-payload.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rsc-payload.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/rsc-payload.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAQ/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,OAAO,EACZ,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,EACrC,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,mBAAmB,EAAE,EAC/B,gBAAgB,EAAE,oBAAoB,EAAE,EACxC,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,OAAO,EACxB,eAAe,CAAC,EAAE,MAAM,EAAE,GACzB,OAAO,CAAC,QAAQ,CAAC,CAmKnB"}
+{"version":3,"file":"rsc-payload.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/rsc-payload.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAQ/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,OAAO,EACZ,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,EACrC,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,mBAAmB,EAAE,EAC/B,gBAAgB,EAAE,oBAAoB,EAAE,EACxC,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,OAAO,EACxB,eAAe,CAAC,EAAE,MAAM,EAAE,GACzB,OAAO,CAAC,QAAQ,CAAC,CAoLnB"}

package/dist/server/rsc-entry/rsc-stream.d.ts

@@ -40,6 +40,14 @@ export interface RenderSignals {
     lastUnhandledError: unknown | null;
     /** Callback fired when a redirect or deny signal is captured in onError. */
     onSignal?: () => void;
+    /**
+     * Resolves when every deny-capable shell component (PageDenyBoundary +
+     * TracedLayouts with deny chains) has settled, OR immediately when any
+     * catches a DenySignal in-tree (status is known). Set by renderRoute
+     * after element-tree construction. Awaited by buildRscPayloadResponse
+     * before committing HTTP status. See TIM-1045, TIM-1208.
+     */
+    shellSettled?: Promise<void>;
     /** Callback fired when an unhandled error (non-signal) is captured. Used
      *  to halt Flight data injection into the inline stream. */
     onUnhandledError?: () => void;

package/dist/server/rsc-entry/rsc-stream.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rsc-stream.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/rsc-stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,OAAO,EAAE,UAAU,EAAE,cAAc,EAAe,MAAM,kBAAkB,CAAC;AAG3E,OAAO,EAIL,KAAK,mBAAmB,EACzB,MAAM,cAAc,CAAC;AAItB;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9B,cAAc,EAAE,cAAc,GAAG,IAAI,CAAC;IACtC,WAAW,EAAE;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACvD;;;;;;;;OAQG;IACH,kBAAkB,EAAE,OAAO,GAAG,IAAI,CAAC;IACnC,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB;gEAC4D;IAC5D,gBAAgB,CAAC,EAAE,MAAM,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,SAAS,CAAC;IAClD,OAAO,EAAE,aAAa,CAAC;IACvB,2EAA2E;IAC3E,kBAAkB,CAAC,EAAE,MAAM,mBAAmB,EAAE,CAAC;CAClD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,KAAK,CAAC,YAAY,EAAE,GAAG,EAAE,OAAO,GAAG,eAAe,CA6J1F"}
+{"version":3,"file":"rsc-stream.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/rsc-stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,OAAO,EAAE,UAAU,EAAE,cAAc,EAAe,MAAM,kBAAkB,CAAC;AAG3E,OAAO,EAIL,KAAK,mBAAmB,EACzB,MAAM,cAAc,CAAC;AAItB;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9B,cAAc,EAAE,cAAc,GAAG,IAAI,CAAC;IACtC,WAAW,EAAE;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACvD;;;;;;;;OAQG;IACH,kBAAkB,EAAE,OAAO,GAAG,IAAI,CAAC;IACnC,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B;gEAC4D;IAC5D,gBAAgB,CAAC,EAAE,MAAM,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,SAAS,CAAC;IAClD,OAAO,EAAE,aAAa,CAAC;IACvB,2EAA2E;IAC3E,kBAAkB,CAAC,EAAE,MAAM,mBAAmB,EAAE,CAAC;CAClD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,KAAK,CAAC,YAAY,EAAE,GAAG,EAAE,OAAO,GAAG,eAAe,CA6J1F"}

package/dist/server/stream-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stream-utils.d.ts","sourceRoot":"","sources":["../../src/server/stream-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,MAAM,WAAW,UAAU;IACzB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,OAAO,CAAC,EAAE,UAAU,GACnB,CAAC,cAAc,CAAC,UAAU,CAAC,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC,CAmK1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,EAChC,SAAS,EAAE,MAAM,GAChB,cAAc,CAAC,UAAU,CAAC,CA0D5B"}
+{"version":3,"file":"stream-utils.d.ts","sourceRoot":"","sources":["../../src/server/stream-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,MAAM,WAAW,UAAU;IACzB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,OAAO,CAAC,EAAE,UAAU,GACnB,CAAC,cAAc,CAAC,UAAU,CAAC,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC,CAmK1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,EAChC,SAAS,EAAE,MAAM,GAChB,cAAc,CAAC,UAAU,CAAC,CA4D5B"}

package/docs/api/32-api-cache.mdx

@@ -8,7 +8,7 @@ slug: 'api-cache'
 
 Caching primitives and cache handler interface. Import from `@timber-js/app/cache`.
 
-## `cache(fn, options)`
+## `cache.data(fn, options)`
 
 Wrap an async function with cross-request caching.
 
@@ -17,7 +17,7 @@ import { cache } from '@timber-js/app/cache';
 
 declare const db: { users: { findUnique(opts: { where: { id: string } }): Promise<{ id: string; name: string }> } };
 
-const getUser = cache(
+const getUser = cache.data(
   async (userId: string) => {
     return db.users.findUnique({ where: { id: userId } });
   },
@@ -41,9 +41,9 @@ const getUser = cache(
 
 Default key: FNV-1a hash of function identity + deterministic JSON serialization of arguments.
 
-The function identity is derived at build time from the source text of the `cache(...)` call, so it is stable across restarts, instances, and deploys. With a persistent shared handler (Redis/KV), cached entries survive deploys as long as the call itself is unchanged — reordering calls or editing unrelated code preserves the cache, while editing the wrapped function or its options gives the call a fresh identity (old entries simply expire via TTL). Renaming or moving the file also resets identity for every call in it.
+The function identity is derived at build time from the source text of the `cache.data(...)` call, so it is stable across restarts, instances, and deploys. With a persistent shared handler (Redis/KV), cached entries survive deploys as long as the call itself is unchanged — reordering calls or editing unrelated code preserves the cache, while editing the wrapped function or its options gives the call a fresh identity (old entries simply expire via TTL). Renaming or moving the file also resets identity for every call in it.
 
-Build-time identity covers calls the bundler can see statically: named imports (including aliases like `import { cache as c }`) and namespace imports (`import * as timber` + `timber.cache(fn, opts)`). Calls it can't trace — a local alias like `const c = cache`, or `cache` re-exported through your own wrapper module — fall back to a hash of the function's source text at runtime. The fallback is still deterministic across instances of the same build, but it resets across deploys, and byte-identical closures produced by a factory can collide — pass an explicit `key` in those cases (timber logs a warning when the fallback is used).
+Build-time identity covers calls the bundler can see statically: named imports (including aliases like `import { cache as c }`) and namespace imports (`import * as timber` + `timber.cache.data(fn, opts)`). Calls it can't trace — a local alias like `const c = cache`, or `cache` re-exported through your own wrapper module — fall back to a hash of the function's source text at runtime. The fallback is still deterministic across instances of the same build, but it resets across deploys, and byte-identical closures produced by a factory can collide — pass an explicit `key` in those cases (timber logs a warning when the fallback is used).
 
 ### `cache.invalidate(options)`
 

package/docs/api/33-api-search-params.mdx

@@ -23,6 +23,19 @@ export const searchParams = defineSearchParams({
 });
 ```
 
+### Implicit optionality
+
+Search params are optional by nature — the URL might not contain them. A schema without `.default()` or `.optional()` (e.g. bare `z.string()`) is treated as implicitly optional: absent or invalid input parses to `undefined`, and the field's inferred type widens to `T | undefined`. Definitions never throw at module-eval time, and schema-backed parsing never throws at request time.
+
+```ts
+const def = defineSearchParams({ name: z.string() });
+def.parse(new URLSearchParams(''));        // { name: undefined }
+def.parse(new URLSearchParams('name=x'));  // { name: 'x' }
+// Inferred type: { name: string | undefined }
+```
+
+Note: `z.coerce.*` schemas declare input `unknown`, so a coerce schema without `.default()` keeps its narrow type even though absent input yields `undefined` at runtime — add `.default()` to coerce schemas for accurate types.
+
 ### Returns: `SearchParamsDefinition<T>`
 
 | Method / Property         | Description                                            |

package/docs/learn/00-introduction.mdx

@@ -61,8 +61,7 @@ export const searchParams = defineSearchParams({
 const sp = searchParams.get();
 
 // or on the client
-
-const [sp, setSearchParams] = searchParams.useQueryState();
+const [sp, setSearchParams] = searchParams.useQueryStates();
 ```
 
 ### Typed Routes

package/docs/learn/09-caching.mdx

@@ -36,7 +36,7 @@ export const getUser = cache(async (id: string) => {
 });
 
 // Caches across requests for 60 seconds
-export const getPopularProducts = timberCache(
+export const getPopularProducts = timberCache.data(
   async () => {
     return db.products.findPopular();
   },
@@ -44,7 +44,7 @@ export const getPopularProducts = timberCache(
 );
 ```
 
-## `timber.cache()` Options
+## `cache.data()` Options
 
 ```ts
 import { cache } from '@timber-js/app/cache';
@@ -53,7 +53,7 @@ declare const db: {
   users: { findUnique(opts: { where: { id: string } }): Promise<{ id: string; name: string }> };
 };
 
-const getUser = cache(
+const getUser = cache.data(
   async (userId: string) => {
     return db.users.findUnique({ where: { id: userId } });
   },
@@ -74,7 +74,7 @@ Without an explicit `key`, the cache key is derived from the call site plus a de
 
 ### Content-Derived Cache Identities
 
-The call-site identity is content-based — derived from the source code of the `cache()` call, not its position in the file. This means:
+The call-site identity is content-based — derived from the source code of the `cache.data()` call, not its position in the file. This means:
 
 - **Unchanged code = cache survives deploys.** If you redeploy without changing a cached function, its entries remain valid on persistent handlers like Redis or KV.
 - **Changed code = automatic invalidation.** Editing the wrapped function or its options changes the cache identity, which invalidates old entries without manual cache busting.
@@ -86,7 +86,7 @@ Object key order doesn't matter — `{ a: 1, b: 2 }` and `{ b: 2, a: 1 }` produc
 Arguments that can't be serialized faithfully — functions, symbols, or class instances whose data lives behind getters with no `toJSON()` — throw a `TypeError` instead of silently colliding. If you hit this, pass an explicit `key`:
 
 ```ts
-cache(fn, { ttl: 60, key: (session) => `events:${session.userId}` });
+cache.data(fn, { ttl: 60, key: (session) => `events:${session.userId}` });
 ```
 
 ## Invalidation

package/docs/more/03-coming-from-nextjs.mdx

@@ -80,14 +80,14 @@ export const searchParams = defineSearchParams({
 
 **Next.js:** Implicit fetch caching, `unstable_cache`, ISR with `revalidate`.
 
-**timber:** No implicit caching. No ISR. Explicit `timber.cache()` with TTL and tags:
+**timber:** No implicit caching. No ISR. Explicit `cache.data()` with TTL and tags:
 
 ```ts
 import { cache } from '@timber-js/app/cache';
 
 declare const db: { products: { findPopular(): Promise<{ id: string; name: string }[]> } };
 
-const getProducts = cache(
+const getProducts = cache.data(
   async () => db.products.findPopular(),
   { ttl: 300, tags: ['products'] }
 );

package/docs/more/50-ai-agent-instructions.mdx

@@ -53,8 +53,8 @@ These are the things you will get wrong if you assume Next.js behavior.
 | Concept | Next.js | timber.js |
 | --- | --- | --- |
 | Default component type | Client components need `'use client'` | **All components are server components** by default. Only add `'use client'` when you need browser APIs or hooks. |
-| Fetch caching | `fetch()` is patched with implicit caching | `fetch()` is **never patched**. Use `cache()` from `@timber-js/app/cache` explicitly. |
-| ISR | `revalidate` option | **Does not exist.** Use `cache()` with TTL and tags. |
+| Fetch caching | `fetch()` is patched with implicit caching | `fetch()` is **never patched**. Use `cache.data()` from `@timber-js/app/cache` explicitly. |
+| ISR | `revalidate` option | **Does not exist.** Use `cache.data()` with TTL and tags. |
 | `loading.tsx` | Convention for auto-Suspense | **Does not exist.** Use `<Suspense>` explicitly. |
 | Middleware | Single global `middleware.ts` with matchers | Per-segment `middleware.ts` files + global `proxy.ts`. One-arg signature: `middleware(ctx)`. |
 | `notFound()` | `notFound()` from `next/navigation` | `deny(404)` from `@timber-js/app/server`. Sends a real HTTP 404. |
@@ -104,11 +104,11 @@ content-collections.ts  # Collection definitions (optional)
 
 2. **Adding `'use client'` to everything** — components are server components by default. Only add `'use client'` when you need browser APIs, event handlers, or React hooks like `useState`/`useEffect`.
 
-3. **Using `fetch()` and expecting caching** — timber never patches `fetch`. Wrap data-fetching functions in `cache()` from `@timber-js/app/cache` when you want caching.
+3. **Using `fetch()` and expecting caching** — timber never patches `fetch`. Wrap data-fetching functions in `cache.data()` from `@timber-js/app/cache` when you want caching.
 
 4. **Creating `loading.tsx` files** — this convention does not exist. Use `<Suspense>` with an explicit fallback where you want streaming.
 
-5. **Using ISR patterns** (`revalidate`, `unstable_cache`) — ISR does not exist. Use `cache()` with `{ ttl: seconds, tags: ['tag'] }`.
+5. **Using ISR patterns** (`revalidate`, `unstable_cache`) — ISR does not exist. Use `cache.data()` with `{ ttl: seconds, tags: ['tag'] }`.
 
 6. **Calling `notFound()`** — use `deny(404)` from `@timber-js/app/server` instead. It sends a real HTTP 404 status code.
 
@@ -123,7 +123,7 @@ content-collections.ts  # Collection definitions (optional)
 ```tsx
 import { cache } from '@timber-js/app/cache';
 
-const getProducts = cache(
+const getProducts = cache.data(
   async () => db.products.findMany(),
   { ttl: 300, tags: ['products'] }
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.165",
+  "version": "0.2.0-alpha.167",
   "description": "Vite-native React framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",
@@ -150,6 +150,12 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "copy-docs": "node scripts/copy-docs.js",
+    "build": "vite build --config vite.lib.config.ts && tsc --emitDeclarationOnly --project tsconfig.json --outDir dist && pnpm run copy-docs",
+    "typecheck": "tsgo --noEmit",
+    "prepublishOnly": "pnpm run build"
+  },
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/context-async-hooks": "^2.8.0",
@@ -157,7 +163,8 @@
     "cookie": "^1.1.1",
     "magic-string": "^0.30.21",
     "nitro": "3.0.260610-beta",
-    "srvx": "^0.11.17"
+    "srvx": "^0.11.17",
+    "jsonc-parser": "^3.3.1"
   },
   "peerDependencies": {
     "@content-collections/core": "^0.14.0 || ^0.15.0",
@@ -195,10 +202,5 @@
   },
   "engines": {
     "node": ">=22.18.0"
-  },
-  "scripts": {
-    "copy-docs": "node scripts/copy-docs.js",
-    "build": "vite build --config vite.lib.config.ts && tsc --emitDeclarationOnly --project tsconfig.json --outDir dist && pnpm run copy-docs",
-    "typecheck": "tsgo --noEmit"
   }
-}
+}

package/src/adapters/cloudflare.ts

@@ -3,9 +3,10 @@
 // Primary deployment target. Generates a Workers-compatible entry point
 // and wrangler.jsonc configuration. See design/11-platform.md §"Cloudflare Workers".
 
-import { writeFile, readFile, cp, rm, readdir } from 'node:fs/promises';
+import { writeFile, readFile, cp, rm, readdir, access } from 'node:fs/promises';
 import { execFile } from 'node:child_process';
 import { join, relative } from 'node:path';
+import { parse as parseJsonc } from 'jsonc-parser';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import type { TimberPlatformAdapter, TimberConfig } from './types';
 import { runSharedBuildSteps } from './build-output-helper.js';
@@ -158,6 +159,12 @@ export interface CloudflareBindings {
 
 /** Options for the Cloudflare Workers adapter. */
 export interface CloudflareAdapterOptions {
+  /**
+   * Worker name used in the generated wrangler.jsonc.
+   * @default 'timber-app'
+   */
+  name?: string;
+
   /**
    * Cloudflare compatibility date.
    * @default Current date in YYYY-MM-DD format at build time.
@@ -291,8 +298,10 @@ export function cloudflare(options: CloudflareAdapterOptions = {}): TimberPlatfo
       const workerEntry = generateWorkerEntry(outDir, outDir, hasManifestInit, hasWorkerHandlers);
       await writeFile(join(outDir, '_worker.js'), workerEntry);
 
-      // Generate wrangler.jsonc
-      const wranglerConfig = generateWranglerConfig(config, options);
+      // Generate wrangler.jsonc — merges user's wrangler config from disk if present
+      const root = config.root ?? process.cwd();
+      const userConfig = await readUserWranglerConfig(root);
+      const wranglerConfig = generateWranglerConfig(config, options, userConfig);
       await writeFile(join(outDir, 'wrangler.jsonc'), JSON.stringify(wranglerConfig, null, 2));
     },
 
@@ -682,22 +691,40 @@ function isPlainObject(val: unknown): val is Record<string, unknown> {
   return val !== null && typeof val === 'object' && !Array.isArray(val);
 }
 
+const WRANGLER_CONFIG_FILES = ['wrangler.jsonc', 'wrangler.json'] as const;
+
+/**
+ * Read the user's wrangler config from the project root, if one exists.
+ * Checks wrangler.jsonc first, then wrangler.json.
+ * @internal Exported for testing.
+ */
+export async function readUserWranglerConfig(
+  root: string
+): Promise<Record<string, unknown> | null> {
+  for (const filename of WRANGLER_CONFIG_FILES) {
+    const filepath = join(root, filename);
+    try {
+      await access(filepath);
+    } catch {
+      continue;
+    }
+    const content = await readFile(filepath, 'utf-8');
+    return parseJsonc(content) as Record<string, unknown>;
+  }
+  return null;
+}
+
 /** @internal Exported for testing. */
 export function generateWranglerConfig(
   config: TimberConfig,
-  options: CloudflareAdapterOptions
+  options: CloudflareAdapterOptions,
+  userConfig?: Record<string, unknown> | null
 ): Record<string, unknown> {
-  const compatDate = options.compatibilityDate ?? new Date().toISOString().slice(0, 10);
-
-  const flags = options.compatibilityFlags ?? ['nodejs_compat'];
-
   const base: Record<string, unknown> = {
     name: 'timber-app',
     main: '_worker.js',
-    compatibility_date: compatDate,
-    compatibility_flags: flags,
-    // The build output is already fully bundled by Vite — skip wrangler's
-    // esbuild pass to avoid issues with top-level await and module format.
+    compatibility_date: new Date().toISOString().slice(0, 10),
+    compatibility_flags: ['nodejs_compat'],
     no_bundle: true,
     find_additional_modules: true,
     rules: [{ type: 'ESModule', globs: ['**/*.js'] }],
@@ -705,29 +732,40 @@ export function generateWranglerConfig(
       directory: './static',
       binding: 'ASSETS',
     },
-    // Native trace destination — required for timber's pipeline spans
-    // (emitted via tracing.enterSpan in the generated _worker.js) to appear
-    // in the Cloudflare Observability dashboard. Gates traces only; does
-    // not enable Workers Logs. Override via the `wrangler` escape hatch:
-    // wrangler: { observability: { traces: { enabled: false } } }.
     observability: {
       traces: { enabled: true },
     },
   };
 
-  // Layer 1: merge bindings-generated sections into base
+  // Layer 1: user's wrangler.jsonc / wrangler.json from disk
+  let merged: Record<string, unknown> = userConfig ? shallowDeepMerge(base, userConfig) : base;
+
+  // Layer 2: explicit adapter options override disk config
+  const explicit: Record<string, unknown> = {};
+  if (options.name != null) explicit.name = options.name;
+  if (options.compatibilityDate != null) explicit.compatibility_date = options.compatibilityDate;
+  if (options.compatibilityFlags != null) explicit.compatibility_flags = options.compatibilityFlags;
+  if (Object.keys(explicit).length > 0) {
+    merged = { ...merged, ...explicit };
+  }
+
+  // Layer 3: declarative bindings
   const bindingsConfig = generateBindingsConfig(options.bindings);
-  const merged = { ...base, ...bindingsConfig };
+  merged = shallowDeepMerge(merged, bindingsConfig as Record<string, unknown>);
 
-  // Layer 2: wrangler escape hatch with deep merge for nested plain objects.
-  // A shallow spread would replace entire sections like durable_objects and
-  // queues — e.g. adding migrations via wrangler would drop the generated
-  // durable_objects.bindings. Deep merge preserves generated keys while
-  // letting wrangler override on actual key-level conflicts.
+  // Layer 4: wrangler escape hatch — highest priority, deep merge.
   if (options.wrangler) {
-    return shallowDeepMerge(merged, options.wrangler);
+    merged = shallowDeepMerge(merged, options.wrangler);
   }
 
+  // Generated config targets a single environment — env blocks can override
+  // main/assets per-environment and break the build output.
+  delete merged.env;
+
+  // These fields are required for the build output to work correctly.
+  merged.main = '_worker.js';
+  merged.find_additional_modules = true;
+
   return merged;
 }
 

package/src/adapters/types.ts

@@ -9,6 +9,8 @@
  * A subset of the resolved timber.config.ts relevant to adapters.
  */
 export interface TimberConfig {
+  /** Absolute path to the project root (Vite root). */
+  root?: string;
   output: 'server' | 'static';
   clientJavascriptDisabled?: boolean;
   /**

package/src/cache/cache-api.ts

@@ -6,102 +6,102 @@ import { recordInvalidation } from './invalidation-epoch';
 import { writeTombstonesForTag } from '../server/prebuilt/overlay.js';
 import { getCdnPurgeHandler } from '../cdn/purge-store.js';
 
+const componentFallbackWarned = new WeakSet<object>();
+
 /**
- * Public caching API: `cache(fn, opts)`.
- *
- * Wraps an async function with cross-request caching. Uses the configured
- * cache handler (defaults to MemoryCacheHandler, overridable via timber.config.ts).
+ * Cache namespace — `cache.data`, `cache.component`, `cache.invalidate`.
  *
  * ```ts
  * import { cache } from '@timber-js/app/cache';
  *
- * const getUser = cache(
+ * const getUser = cache.data(
  *   async (id: string) => db.users.findUnique({ where: { id } }),
  *   { ttl: 60, tags: (id) => [`user:${id}`] }
  * );
  * ```
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function cache<Fn extends (...args: any[]) => Promise<any>>(
-  fn: Fn,
-  opts: CacheOptions<Fn>,
-  stableId?: string
-): Fn {
-  // Pass the getter, not a resolved handler: the wrapper re-resolves it on
-  // every call, so module-scope wrappers created before the framework's boot
-  // wiring calls setCacheHandler() still pick up the configured handler
-  // instead of permanently binding the in-memory fallback (TIM-1029).
-  return createCache(fn, opts, getCacheHandler, stableId);
-}
+export const cache = {
+  /**
+   * Wrap an async function with cross-request caching.
+   *
+   * The configured cache handler (defaults to MemoryCacheHandler, overridable
+   * via timber.config.ts) is re-resolved on every call, so module-scope
+   * wrappers created before `setCacheHandler()` still pick up the configured
+   * handler (TIM-1029).
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  data<Fn extends (...args: any[]) => Promise<any>>(
+    fn: Fn,
+    opts: CacheOptions<Fn>,
+    stableId?: string
+  ): Fn {
+    return createCache(fn, opts, getCacheHandler, stableId);
+  },
 
-/**
- * Invalidate cache entries by tag or key.
- *
- * ```ts
- * cache.invalidate({ tag: 'products' });
- * cache.invalidate({ key: 'user:abc' });
- * ```
- */
-cache.invalidate = async function invalidate(opts: { key?: string; tag?: string }): Promise<void> {
-  // Record before the handler delete so a cached fn in flight skips its
-  // post-resolve set instead of resurrecting the invalidated value (TIM-1028).
-  recordInvalidation(opts);
-  await getCacheHandler().invalidate(opts);
-  // Write tombstones for build-seed entries carrying the tag (design/45
-  // §ISR mechanics). Runs AFTER handler.invalidate so the tombstone
-  // overwrites the cleared overlay slot. This covers ALL invalidation
-  // paths — actions, webhooks, route handlers — not just executeAction.
-  if (opts.tag) {
-    await writeTombstonesForTag(opts.tag);
-  }
-  // Trigger CDN purge if a handler is configured (design/25 §Layer 2).
-  // Purge is best-effort: a CDN API failure or timeout must not block
-  // cache invalidation. 10s ceiling prevents a hung CDN API from stalling
-  // the entire revalidateTag/action flow.
-  if (opts.tag) {
-    const purgeHandler = getCdnPurgeHandler();
-    if (purgeHandler) {
-      try {
-        await Promise.race([
-          purgeHandler.purgeTags([opts.tag]),
-          new Promise<void>((_, reject) =>
-            setTimeout(() => reject(new Error('CDN purge timed out (10s)')), 10_000)
-          ),
-        ]);
-      } catch (err) {
-        console.error('[timber] CDN purge failed for tag:', err);
+  /**
+   * Invalidate cache entries by tag or key.
+   *
+   * ```ts
+   * cache.invalidate({ tag: 'products' });
+   * cache.invalidate({ key: 'user:abc' });
+   * ```
+   */
+  async invalidate(opts: { key?: string; tag?: string }): Promise<void> {
+    // Record before the handler delete so a cached fn in flight skips its
+    // post-resolve set instead of resurrecting the invalidated value (TIM-1028).
+    recordInvalidation(opts);
+    await getCacheHandler().invalidate(opts);
+    // Write tombstones for build-seed entries carrying the tag (design/45
+    // §ISR mechanics). Runs AFTER handler.invalidate so the tombstone
+    // overwrites the cleared overlay slot. This covers ALL invalidation
+    // paths — actions, webhooks, route handlers — not just executeAction.
+    if (opts.tag) {
+      await writeTombstonesForTag(opts.tag);
+    }
+    // Trigger CDN purge if a handler is configured (design/25 §Layer 2).
+    // Purge is best-effort: a CDN API failure or timeout must not block
+    // cache invalidation. 10s ceiling prevents a hung CDN API from stalling
+    // the entire revalidateTag/action flow.
+    if (opts.tag) {
+      const purgeHandler = getCdnPurgeHandler();
+      if (purgeHandler) {
+        try {
+          await Promise.race([
+            purgeHandler.purgeTags([opts.tag]),
+            new Promise<void>((_, reject) =>
+              setTimeout(() => reject(new Error('CDN purge timed out (10s)')), 10_000)
+            ),
+          ]);
+        } catch (err) {
+          console.error('[timber] CDN purge failed for tag:', err);
+        }
       }
     }
-  }
-};
-
-const componentFallbackWarned = new WeakSet<object>();
+  },
 
-/**
- * Runtime fallback for `cache.component(...)` callsites the timber-prebuilt
- * transform does not rewrite — nested/computed/argument-position forms (see
- * plugins/prebuilt.ts). Only module-scope `const X = cache.component(...)`
- * declarations are transformed and eligible for prebuilding; everything else
- * lands here, warns once per component, and renders dynamically. Same
- * safety-net pattern as the data cache's runtime fnId fallback (TIM-1054):
- * an untraceable callsite degrades in performance, never in correctness.
- *
- * The full public surface (types, docs, `timber` namespace) is TIM-1121;
- * design/45-cache-lifetimes.md specifies the options.
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-cache.component = function component<C extends (props: any) => unknown>(
-  componentFn: C,
-  _options?: PrebuiltComponentOptions
-): C {
-  if (!componentFallbackWarned.has(componentFn)) {
-    componentFallbackWarned.add(componentFn);
-    const name = componentFn.name || 'anonymous component';
-    console.warn(
-      `[timber] cache.component: "${name}" was not transformed at build time — ` +
-        `rendering dynamically. Only module-scope declarations ` +
-        `(const X = cache.component(...)) are prebuilt.`
-    );
-  }
-  return componentFn;
+  /**
+   * Runtime fallback for `cache.component(...)` callsites the timber-prebuilt
+   * transform does not rewrite — nested/computed/argument-position forms (see
+   * plugins/prebuilt.ts). Only module-scope `const X = cache.component(...)`
+   * declarations are transformed and eligible for prebuilding; everything else
+   * lands here, warns once per component, and renders dynamically. Same
+   * safety-net pattern as the data cache's runtime fnId fallback (TIM-1054):
+   * an untraceable callsite degrades in performance, never in correctness.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  component<C extends (props: any) => unknown>(
+    componentFn: C,
+    _options?: PrebuiltComponentOptions
+  ): C {
+    if (!componentFallbackWarned.has(componentFn)) {
+      componentFallbackWarned.add(componentFn);
+      const name = componentFn.name || 'anonymous component';
+      console.warn(
+        `[timber] cache.component: "${name}" was not transformed at build time — ` +
+          `rendering dynamically. Only module-scope declarations ` +
+          `(const X = cache.component(...)) are prebuilt.`
+      );
+    }
+    return componentFn;
+  },
 };