@timber-js/app 0.2.0-alpha.207 → 0.2.0-alpha.209

package/dist/server/tracing.d.ts

@@ -33,16 +33,12 @@ export declare function generateTraceId(): string;
  */
 export declare function runWithTraceId<T>(id: string, fn: () => T): T;
 /**
- * Replace the trace ID in the current ALS store. Used when OTEL creates
- * a root span and we want to switch from the UUID fallback to the real
- * OTEL trace ID.
+ * Replace the request's trace ID. Used when OTEL creates the root span and
+ * we want to switch from the UUID fallback to the real OTEL trace ID. Writes
+ * the request's shared trace, so every scope in the request sees it —
+ * including the ones outside the span this runs in.
  */
-export declare function replaceTraceId(newTraceId: string, newSpanId?: string): void;
-/**
- * Update the span ID in the current ALS store. Used when entering a new
- * OTEL span to keep log–trace correlation accurate.
- */
-export declare function updateSpanId(newSpanId: string | undefined): void;
+export declare function replaceTraceId(newTraceId: string): void;
 /**
  * Get the current trace store, or undefined if outside a request context.
  * Framework-internal — use getTraceId()/getSpanId() in user code.
@@ -57,7 +53,8 @@ export declare function getTraceStore(): TraceStore | undefined;
  * we create a BasicTracerProvider with our processor.
  *
  * Idempotent across module re-evaluations (HMR) — only the first call
- * registers. Only called in dev mode — zero overhead in production.
+ * registers. Called in dev, and in production only when TIMBER_DEBUG is
+ * set — otherwise production never loads the OTEL SDK.
  */
 export declare function initDevTracing(config: import('../dev-tools/logger.ts').DevLoggerConfig): Promise<void>;
 /**
@@ -104,7 +101,8 @@ export declare function getTracer(): Promise<import('@opentelemetry/api').Tracer
  *
  * Automatically:
  * - Creates the span as a child of the current context
- * - Updates the ALS span ID for log–trace correlation
+ * - Runs fn in its own trace scope carrying the span's IDs, for log–trace
+ *   correlation and setSpanAttribute()
  * - Ends the span when the function completes
  * - Records exceptions on error (OTEL channel)
  */
@@ -131,10 +129,8 @@ export declare function addSpanEvent(name: string, attributes?: Record<string, s
 export declare function addSpanEventSync(name: string, attributes?: Record<string, string | number | boolean>): void;
 /**
  * Try to extract the OTEL trace ID from the current active span context.
- * Returns undefined if OTEL is not active or no span exists.
+ * Returns undefined if OTEL is not active or no span exists. (The span ID
+ * reaches logs through the span's own trace scope, not from here.)
  */
-export declare function getOtelTraceId(): Promise<{
-    traceId: string;
-    spanId: string;
-} | undefined>;
+export declare function getOtelTraceId(): Promise<string | undefined>;
 //# sourceMappingURL=tracing.d.ts.map

package/dist/server/tracing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../../src/server/tracing.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAY,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAG9D,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAIpD;;;;;;;GAOG;AACH,wBAAgB,UAAU,IAAI,MAAM,CASnC;AAED;;GAEG;AACH,wBAAgB,SAAS,IAAI,MAAM,GAAG,SAAS,CAE9C;AAID;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAE5D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAM3E;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAKhE;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,UAAU,GAAG,SAAS,CAEtD;AAcD;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,OAAO,wBAAwB,EAAE,eAAe,GACvD,OAAO,CAAC,IAAI,CAAC,CA4Cf;AAID;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;CACnE;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,CAAC,GAAG,CAAC,CAAC;CAC9D;AAOD,uEAAuE;AACvE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG,SAAS,GAAG,IAAI,CAE1E;AAED,qDAAqD;AACrD,wBAAgB,iBAAiB,IAAI,cAAc,GAAG,SAAS,CAE9D;AA4BD;;GAEG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,OAAO,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC,CAUrF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,EACrD,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACvB,OAAO,CAAC,CAAC,CAAC,CAuBZ;AAkCD;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAC/B,OAAO,CAAC,IAAI,CAAC,CAcf;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GACrD,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GACrD,IAAI,CASN;AAED;;;GAGG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAAC,CAc/F"}
+{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../../src/server/tracing.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAY,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAG9D,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAIpD;;;;;;;GAOG;AACH,wBAAgB,UAAU,IAAI,MAAM,CASnC;AAED;;GAEG;AACH,wBAAgB,SAAS,IAAI,MAAM,GAAG,SAAS,CAE9C;AAID;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAKvD;AAiBD;;;GAGG;AACH,wBAAgB,aAAa,IAAI,UAAU,GAAG,SAAS,CAEtD;AAcD;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,OAAO,wBAAwB,EAAE,eAAe,GACvD,OAAO,CAAC,IAAI,CAAC,CAsBf;AAID;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;CACnE;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,CAAC,GAAG,CAAC,CAAC;CAC9D;AAOD,uEAAuE;AACvE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG,SAAS,GAAG,IAAI,CAE1E;AAED,qDAAqD;AACrD,wBAAgB,iBAAiB,IAAI,cAAc,GAAG,SAAS,CAE9D;AA4BD;;GAEG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,OAAO,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC,CAUrF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,EACrD,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACvB,OAAO,CAAC,CAAC,CAAC,CAeZ;AAwCD;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAC/B,OAAO,CAAC,IAAI,CAAC,CAcf;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GACrD,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GACrD,IAAI,CASN;AAED;;;;GAIG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAclE"}

package/dist/server/types.d.ts

@@ -3,7 +3,7 @@ import type { EarlyHint } from './early-hints.ts';
 /**
  * A value that is safe to pass through `JSON.stringify` without data loss.
  *
- * Used as the constraint for `deny(status, data)` and `RenderError` digest data
+ * Used as the constraint for `deny(status, { dangerouslyPassData })` data
  * because the post-flush path serializes via JSON.stringify, not React Flight.
  * Types that survive Flight (Date, Map, Set, BigInt) would silently coerce or
  * throw when serialized as JSON. This type prevents that at compile time.

package/dist/server/version-skew.d.ts

@@ -25,9 +25,9 @@ export declare const DEPLOYMENT_ID_HEADER = "X-Timber-Deployment-Id";
 /** Response header that signals the client to do a full page reload. */
 export declare const RELOAD_HEADER = "X-Timber-Reload";
 /**
- * Set the current deployment ID. Called once at server startup from the
- * manifest init module. In dev mode this is never called (deployment ID
- * checks are skipped).
+ * Set the current deployment ID. Called once at server startup by the RSC
+ * entry's `createRequestHandler()`. In dev mode this is never called
+ * (deployment ID checks are skipped).
  */
 export declare function setDeploymentId(id: string): void;
 /**

package/dist/shared/csrf-reject.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Marker header on CSRF rejections.
+ *
+ * A CSRF rejection is a 403, the same status as an access-control denial.
+ * The server stamps this header on every CSRF 403 so callers — the browser
+ * action runtime, a same-origin `fetch` in user code, a curl session — can
+ * tell the two apart without parsing the body. A cross-origin `fetch` cannot
+ * read it: the rejection returns before proxy.ts, so no CORS headers are set
+ * and the browser reports a network error instead. Shared so the server writer and the client
+ * reader cannot drift.
+ *
+ * See design/08-forms-and-actions.md §"CSRF Protection" (TIM-1459).
+ */
+export declare const CSRF_REJECT_HEADER = "X-Timber-Reject";
+export declare const CSRF_REJECT_VALUE = "csrf";
+//# sourceMappingURL=csrf-reject.d.ts.map

package/dist/shared/csrf-reject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csrf-reject.d.ts","sourceRoot":"","sources":["../../src/shared/csrf-reject.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,oBAAoB,CAAC;AACpD,eAAO,MAAM,iBAAiB,SAAS,CAAC"}

package/dist/shared/error-digest.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The digest an unhandled render error carries across Flight, and the
+ * correlation ID error pages read back out of it.
+ *
+ * Flight's `onError` (server/rsc-entry/rsc-stream.ts) returns this string for
+ * any error that is not a deny or redirect, and React sets it as `digest` on
+ * the Error it revives for that row, in SSR and on the client alike. The
+ * `errorId` is the one the server logged the error with, so an error page
+ * that shows it gives the reader something to quote that an operator can
+ * find. It is the `digest` prop every TSX error page receives.
+ *
+ * `message` is the real message only in dev; production sends a fixed string
+ * (design/13-security.md §"Errors don't leak").
+ */
+interface ErrorRowDigest {
+    type: 'error';
+    message: string;
+    errorId: string;
+}
+export declare function encodeErrorDigest(digest: Omit<ErrorRowDigest, 'type'>): string;
+/**
+ * The correlation ID in an error's Flight digest, or `null` when the error
+ * carries none — a deny or redirect row, an error that never crossed Flight,
+ * or anything that is not an object.
+ */
+export declare function errorDigestId(error: unknown): string | null;
+export {};
+//# sourceMappingURL=error-digest.d.ts.map

package/dist/shared/error-digest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-digest.d.ts","sourceRoot":"","sources":["../../src/shared/error-digest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,UAAU,cAAc;IACtB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,GAAG,MAAM,CAG9E;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAc3D"}

package/dist/shared/payload-root.d.ts

@@ -62,9 +62,9 @@ export interface RscPayloadRoot extends PublishedParams {
  * In the browser this is unreachable for a real response: all four producers
  * of a route payload go through `withPublishedParams`, and a client talking to
  * a different build is answered with 204 at Stage 1c
- * (`server/pipeline-phases.ts`) before any payload exists. It is reachable in
- * the router's test/fallback path, where `decodeRsc` is absent and the
- * "payload" is the raw response text.
+ * (`server/pipeline-phases.ts`) before any payload exists. It is what a page
+ * with no payload at all publishes — a document hydrated without an inlined
+ * payload, or a prefetch entry that carries no params.
  */
 export declare const NO_PUBLISHED_PARAMS: PublishedParams;
 /**
@@ -78,9 +78,8 @@ export declare function readPublishedParams(source: unknown): PublishedParams;
 /**
  * Read the renderable tree out of a payload root.
  *
- * Returns the value unchanged when it is not a root — the router's fallback
- * path stores raw response text under the same name, and a test asserting on
- * that text should see the text.
+ * Returns the value unchanged when it is not a root, so a malformed value
+ * reaches React (and its error boundaries) rather than vanishing here.
  */
 export declare function readPayloadTree(root: unknown): unknown;
 /** A decoded payload, split into the two things the client does with it. */
@@ -91,10 +90,12 @@ export interface SplitPayload {
      * The params published beside it. Settled when the root already is, so the
      * hydration path can render without an extra await.
      *
-     * **Never rejects.** A decode failure has to surface where React renders
-     * `tree`, so the error boundary *around the tree* catches it. Rejecting here
-     * too would take down the provider above every boundary in the app, turning
-     * a contained failure into a blank page (TIM-1297).
+     * **Never rejects.** A decode failure has to surface through `tree`: where
+     * React renders it on hydration, so the error boundary *around the tree*
+     * catches it, and where the router awaits it before handing a navigation
+     * over, so the navigation fails and recovers. Rejecting here too would take
+     * down the provider above every boundary in the app, turning a contained
+     * failure into a blank page (TIM-1297).
      */
     params: ParamsSource;
 }

package/dist/shared/payload-root.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"payload-root.d.ts","sourceRoot":"","sources":["../../src/shared/payload-root.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,MAAM,EAAE,aAAa,CAAC;IACtB,6EAA6E;IAC7E,UAAU,EAAE,gBAAgB,GAAG,IAAI,CAAC;CACrC;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GAAG,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;AAEtE,sCAAsC;AACtC,MAAM,WAAW,cAAe,SAAQ,eAAe;IACrD,gCAAgC;IAChC,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,EAAE,eAAkD,CAAC;AAarF;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,GAAG,eAAe,CAGpE;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAKtD;AAED,4EAA4E;AAC5E,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,IAAI,EAAE,OAAO,CAAC;IACd;;;;;;;;OAQG;IACH,MAAM,EAAE,YAAY,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,YAAY,CAgB5D"}
+{"version":3,"file":"payload-root.d.ts","sourceRoot":"","sources":["../../src/shared/payload-root.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,MAAM,EAAE,aAAa,CAAC;IACtB,6EAA6E;IAC7E,UAAU,EAAE,gBAAgB,GAAG,IAAI,CAAC;CACrC;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GAAG,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;AAEtE,sCAAsC;AACtC,MAAM,WAAW,cAAe,SAAQ,eAAe;IACrD,gCAAgC;IAChC,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,EAAE,eAAkD,CAAC;AAarF;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,GAAG,eAAe,CAGpE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAKtD;AAED,4EAA4E;AAC5E,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,IAAI,EAAE,OAAO,CAAC;IACd;;;;;;;;;;OAUG;IACH,MAAM,EAAE,YAAY,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,YAAY,CAgB5D"}

package/dist/shared/rsc-payload-path.d.ts

@@ -38,5 +38,11 @@
  *   normalize; this function does not, because the two callers normalize from
  *   different sources (a browser URL, a build-time route entry).
  */
+/**
+ * The directory, relative to the site root, that holds every static RSC
+ * payload. The one spelling: the build writes, hashes, and reports it as
+ * content-hashed from here.
+ */
+export declare const RSC_PAYLOAD_DIR = "_rsc";
 export declare function rscPayloadPath(routePath: string): string;
 //# sourceMappingURL=rsc-payload-path.d.ts.map

package/dist/shared/rsc-payload-path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rsc-payload-path.d.ts","sourceRoot":"","sources":["../../src/shared/rsc-payload-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAGxD"}
+{"version":3,"file":"rsc-payload-path.d.ts","sourceRoot":"","sources":["../../src/shared/rsc-payload-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH;;;;;;;GAOG;AACH;;;;GAIG;AACH,eAAO,MAAM,eAAe,SAAS,CAAC;AAEtC,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAGxD"}

package/dist/utils/write-file-atomic.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Replace a file's contents in one step: write a uniquely named temp sibling,
+ * then `rename()` it over the target.
+ *
+ * `writeFile()` opens its target with `O_TRUNC`, so for the length of the write
+ * a concurrent reader sees an empty or half-written file under the real name.
+ * `rename()` within one directory swaps the name atomically, so a reader sees
+ * either the old file or the new one — never a torn one — and a crashed
+ * writer leaves no partial artifact under the final name.
+ *
+ * The temp name is unique per call, not a fixed `${path}.tmp`: two writers of
+ * the same path (a dev server and a `vite build` rewriting the same route
+ * types, parallel CLI invocations sharing a cache) would otherwise write into
+ * one temp file and rename each other's half-written bytes into place.
+ */
+export declare function writeFileAtomic(path: string, data: Uint8Array | string): Promise<void>;
+//# sourceMappingURL=write-file-atomic.d.ts.map

package/dist/utils/write-file-atomic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-file-atomic.d.ts","sourceRoot":"","sources":["../../src/utils/write-file-atomic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAY5F"}

package/docs/api/30-api-server.mdx

@@ -17,9 +17,9 @@ Universal denial/error primitive. Produces an HTTP error status and renders the
 ```ts
 import { deny } from '@timber-js/app/server';
 
-deny();                                                        // 403 (default)
-deny(404);                                                     // 404 Not Found
-deny(503, { message: 'Maintenance' });                         // server-only log message
+deny(); // 403 (default)
+deny(404); // 404 Not Found
+deny(503, { message: 'Maintenance' }); // server-only log message
 deny(404, { dangerouslyPassData: { resourceId: params.id } }); // data forwarded as `data` prop
 ```
 
@@ -52,11 +52,11 @@ redirectExternal('https://auth.example.com/login', ['https://auth.example.com'])
 redirectExternal('https://docs.example.com', ['https://docs.example.com'], 301);
 ```
 
-| Parameter   | Type       | Default | Description                                                |
-| ----------- | ---------- | ------- | ---------------------------------------------------------- |
-| `url`       | `string`   | —       | Absolute URL to redirect to                                |
-| `allowList` | `string[]` | —       | Allowed origins (e.g. `['https://example.com']`)           |
-| `status`    | `number`   | `302`   | HTTP redirect status code (3xx)                            |
+| Parameter   | Type       | Default | Description                                      |
+| ----------- | ---------- | ------- | ------------------------------------------------ |
+| `url`       | `string`   | —       | Absolute URL to redirect to                      |
+| `allowList` | `string[]` | —       | Allowed origins (e.g. `['https://example.com']`) |
+| `status`    | `number`   | `302`   | HTTP redirect status code (3xx)                  |
 
 Throws if the origin is not in the allow-list, the scheme isn't `http:` or `https:`, or the URL is invalid.
 
@@ -130,11 +130,14 @@ throw new ActionError('VALIDATION_FAILED', { field: 'email' });
 
 ### `revalidatePath(path)`
 
-Re-render a path and return the RSC payload as part of the action response.
+Re-render a path and return the RSC payload as part of the action response. Server actions only: called anywhere else, it throws, because there is no action response to attach the render to. From a `route.ts` handler or a job, use `revalidateTag()` or `cache.invalidate()`.
 
 ### `revalidateTag(tag)`
 
-Invalidate all cache entries with the given tag.
+Invalidate all cache entries with the given tag, and the pre-rendered components that carry it. Returns `Promise<void>`. Callable from any server code:
+
+- **In a server action**, the invalidation runs after the action body returns, before any `revalidatePath()` render, so that render sees fresh data. The promise resolves immediately.
+- **Anywhere else** (a `route.ts` webhook, a job), it invalidates immediately. `await` it before you respond.
 
 ## Segment Params
 
@@ -146,8 +149,8 @@ Returns route path params for the current request. Pass a `SEGMENT_PATH` string
 import { SEGMENT_PATH } from './$segment';
 import { getSegmentParams } from '@timber-js/app/server';
 
-const { id } = getSegmentParams(SEGMENT_PATH);  // Exact types from schema
-const params = getSegmentParams();        // Partial<AllSegmentParams>
+const { id } = getSegmentParams(SEGMENT_PATH); // Exact types from schema
+const params = getSegmentParams(); // Partial<AllSegmentParams>
 ```
 
 For typed coercion, define codecs in `app/schema.ts` with `defineSchema()`. See [Typed Params](/docs/typed-params).
@@ -159,7 +162,7 @@ For typed coercion, define codecs in `app/schema.ts` with `defineSchema()`. See
 ```ts
 interface RouteContext {
   req: Request;
-  headers: Headers;        // Response headers (writable)
+  headers: Headers; // Response headers (writable)
 }
 ```
 
@@ -173,7 +176,7 @@ interface MiddlewareContext {
   segmentParams: Record<string, string | string[]>;
   headers: Headers; // Response headers (writable)
   requestHeaders: Headers; // Request headers (injectable)
-  readonly nonce: string;  // Per-request CSP nonce, generated on first read
+  readonly nonce: string; // Per-request CSP nonce, generated on first read
 }
 ```
 

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

@@ -15,7 +15,9 @@ Wrap an async function with cross-request caching.
 ```ts
 import { cache } from '@timber-js/app/cache';
 
-declare const db: { users: { findUnique(opts: { where: { id: string } }): Promise<{ id: string; name: string }> } };
+declare const db: {
+  users: { findUnique(opts: { where: { id: string } }): Promise<{ id: string; name: string }> };
+};
 
 const getUser = cache.data(
   async (userId: string) => {
@@ -87,14 +89,14 @@ const DocsPage = cache.component(DocsBody, { prerender: true, ttl: 3600, tags: [
 
 ### `PrebuiltComponentOptions`
 
-| Option                          | Type                                          | Description                                                                                   |
-| ------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| `prerender`                     | `boolean`                                     | Populate at build time via `generateStaticSegmentParams`                                      |
-| `ttl`                           | `number`                                      | Runtime freshness window in seconds                                                           |
-| `tags`                          | `string[] \| (props) => string[]`             | Tags for invalidation via `revalidateTag`                                                     |
-| `staleWhileRevalidate`          | `boolean`                                     | Serve stale while a background re-render refreshes                                            |
-| `slots`                         | `string[]`                                    | Prop names whose values are live React elements composed into the cached shell at request time |
-| `fallbackOnMissingSegmentParams`| `boolean`                                     | When `false`, a cache miss throws instead of rendering live (default: `true`)                  |
+| Option                           | Type                              | Description                                                                                    |
+| -------------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `prerender`                      | `boolean`                         | Populate at build time via `generateStaticSegmentParams`                                       |
+| `ttl`                            | `number`                          | Runtime freshness window in seconds                                                            |
+| `tags`                           | `string[] \| (props) => string[]` | Tags for invalidation via `revalidateTag`                                                      |
+| `staleWhileRevalidate`           | `boolean`                         | Serve stale while a background re-render refreshes                                             |
+| `slots`                          | `string[]`                        | Prop names whose values are live React elements composed into the cached shell at request time |
+| `fallbackOnMissingSegmentParams` | `boolean`                         | When `false`, a cache miss throws instead of rendering live (default: `true`)                  |
 
 Only module-scope declarations are transformed at build time:
 
@@ -110,11 +112,11 @@ export default function Page() {
 
 ### Tier Rules
 
-| Declaration                  | Enumerated params       | Unenumerated miss                    |
-| ---------------------------- | ----------------------- | ------------------------------------ |
-| `prerender` only             | Built at deploy         | Live render every time, never stored |
-| `ttl`/`tags` only            | —                       | Rendered + stored on first request   |
-| `prerender` + `ttl`/`tags`   | Built at deploy         | Rendered + stored on first request   |
+| Declaration                | Enumerated params | Unenumerated miss                    |
+| -------------------------- | ----------------- | ------------------------------------ |
+| `prerender` only           | Built at deploy   | Live render every time, never stored |
+| `ttl`/`tags` only          | —                 | Rendered + stored on first request   |
+| `prerender` + `ttl`/`tags` | Built at deploy   | Rendered + stored on first request   |
 
 ### Slots
 
@@ -128,7 +130,9 @@ const Shell = cache.component(ExpensiveWrapper, {
 });
 
 // Request time: the shell is served from cache; children render live.
-<Shell theme="dark"><LiveUserFeed /></Shell>
+<Shell theme="dark">
+  <LiveUserFeed />
+</Shell>;
 ```
 
 Slot props are excluded from the cache key — two instances with the same data props share one shell entry. Slots are **runtime tier only**: `prerender` is ignored when `slots` is active because the build cannot enumerate children variants.
@@ -149,7 +153,9 @@ This desugars to wrapping the page's default export in `cache.component(...)`. L
 
 ### Nesting
 
-When a cached component renders inside another cached component, the outer entry's lifetime wins. The inner's output is baked into the outer's payload as a flat copy — `revalidateTag` on the inner's tags does **not** refresh the embedded copy. The framework warns at capture time when the inner declares a refresh channel the outer cannot honor.
+When a cached component renders inside another cached component, the outer entry's lifetime wins. The inner's output is baked into the outer's payload as a flat copy — `revalidateTag` on the inner's tags does **not** refresh the embedded copy. The framework warns when the inner declares a refresh channel the outer cannot honor: its `ttl` is shorter than the outer's, or it has a tag the outer doesn't declare. The warning fires once per pair, from the build and from runtime re-renders. Declaring the inner's tags on the outer lets `revalidateTag` reach the copy and silences the tag warning.
+
+A cached component may render itself with different props — a comment thread, a tree. If the entry being cached renders itself again with the _same_ props, directly or through other components, the capture fails with an error naming the component. Recursion that never reaches a base case fails at the render timeout.
 
 ## `CacheHandler` Interface
 
@@ -225,11 +231,21 @@ const handler = new RedisCacheHandler({
     const p = redis.multi();
     for (const op of ops) {
       switch (op.op) {
-        case 'set': p.set(op.key, op.value, 'EX', op.ttlSeconds); break;
-        case 'sadd': p.sadd(op.key, ...op.members); break;
-        case 'expireNX': p.expire(op.key, op.seconds, 'NX'); break;
-        case 'expireGT': p.expire(op.key, op.seconds, 'GT'); break;
-        case 'del': p.del(op.key); break;
+        case 'set':
+          p.set(op.key, op.value, 'EX', op.ttlSeconds);
+          break;
+        case 'sadd':
+          p.sadd(op.key, ...op.members);
+          break;
+        case 'expireNX':
+          p.expire(op.key, op.seconds, 'NX');
+          break;
+        case 'expireGT':
+          p.expire(op.key, op.seconds, 'GT');
+          break;
+        case 'del':
+          p.del(op.key);
+          break;
       }
     }
     await p.exec();
@@ -302,8 +318,20 @@ Invalidate all cache entries with the given tag. Re-exported from `@timber-js/ap
 ```ts
 import { revalidateTag } from '@timber-js/app/server';
 
-revalidateTag('products');
-revalidateTag(`user:${userId}`);
+await revalidateTag('products');
+await revalidateTag(`user:${userId}`);
+```
+
+Returns `Promise<void>`. Inside a server action the invalidation is deferred until the action body returns, and the promise resolves at once. Anywhere else, it is `cache.invalidate({ tag })`, and the promise settles when the invalidation has, so a webhook awaits it:
+
+```ts title="app/api/cms-webhook/route.ts"
+import { revalidateTag } from '@timber-js/app/server';
+
+export async function POST(ctx: RouteContext) {
+  const { tag } = await ctx.req.json();
+  await revalidateTag(tag);
+  return new Response(null, { status: 204 });
+}
 ```
 
 ## Singleflight

package/docs/api/34-api-config.mdx

@@ -116,7 +116,7 @@ adapter: nitro({ preset: 'node-server' });
 ### `serverTiming`
 
 - **Type:** `'detailed' | 'total' | false`
-- **Default:** `'detailed'` in dev, `'total'` in production
+- **Default:** `'total'` (dev and production). `'detailed'` is opt-in.
 
 Controls the `Server-Timing` response header. See [Instrumentation & Tracing](/docs/instrumentation).
 
@@ -125,7 +125,7 @@ Controls the `Server-Timing` response header. See [Instrumentation & Tracing](/d
 - **Type:** `string[]`
 - **Default:** none
 
-Origins allowed for CORS and CSRF validation.
+Origins accepted by CSRF validation. When set, the incoming `Origin` must exactly match one of these full origins (e.g. `https://myapp.com`), replacing the default same-origin check. This option does not configure CORS.
 
 ### `csrf`
 
@@ -183,7 +183,7 @@ Slow request threshold in milliseconds. Requests exceeding this emit a warning v
 - **Type:** `number`
 - **Default:** `30000`
 
-Render timeout in milliseconds. If an SSR render or RSC stream read does not complete within this duration, the render is aborted and the connection is closed. Protects against hung fetches and Suspense components that never resolve. Setting `0` uses a 120-second safety ceiling rather than disabling the timeout entirely.
+Render timeout in milliseconds. If an SSR render or RSC stream read does not complete within this duration, the render is aborted and the connection is closed. Protects against hung fetches and Suspense components that never resolve. Setting `0` uses a 120-second safety ceiling rather than disabling the timeout entirely. The same value bounds how long concurrent `timber.cache` callers wait on a shared fill, and how long static generation waits for each page.
 
 ### `devBrowserLogs`
 
@@ -316,14 +316,42 @@ topLoader: {
 
 ## `TimberPlatformAdapter`
 
-The adapter interface for community adapters:
+The adapter interface for community adapters, importable as types from `@timber-js/app/adapters/types`:
 
 ```ts
+import type { TimberPlatformAdapter, BuildArtifacts } from '@timber-js/app/adapters/types';
+
 interface TimberPlatformAdapter {
   name: string;
-  buildOutput(config: TimberConfig, buildDir: string): Promise<void>;
-  preview?(config: TimberConfig, buildDir: string): Promise<void>;
+  buildOutput(config: TimberConfig, artifacts: BuildArtifacts): Promise<void>;
+  preview?(config: TimberConfig, target: { output: 'server' | 'static'; outputDir: string }): Promise<void>;
   waitUntil?(promise: Promise<unknown>): void;
   sendEarlyHints?(links: string[]): void;
 }
 ```
+
+`TimberConfig` carries configuration only (`root`, `base`, `clientJavascriptDisabled`). `BuildArtifacts` describes what the build produced, discriminated by `output`:
+
+```ts
+type BuildArtifacts =
+  | {
+      output: 'server';
+      outputDir: string;
+      client: { path: string };
+      immutableDirs: string[];
+      rsc: { path: string };
+      ssr: { path: string };
+      prebuilt?: { path: string };
+      manifestInit?: string;
+    }
+  | {
+      output: 'static';
+      outputDir: string;
+      client: { path: string };
+      immutableDirs: string[];
+      pages: { path: string };
+      contentTypes: Record<string, string>;
+    };
+```
+
+Every path is absolute. `prebuilt` and `manifestInit` are absent when the build did not produce them, so check the field rather than whether a directory exists on disk. `immutableDirs` lists the directories of the served site whose file names are content-hashed — such as `assets`, `_timber/fonts`, and a static build's `_rsc` — relative to the site root, without a leading slash or the deployment `base`. Give those a long-lived `immutable` cache rule instead of hard-coding the paths. `preview()` runs in a separate process after the build, so instead of `BuildArtifacts` it receives the build output directory and the configured `output` mode.

package/docs/api/36-cli.mdx

@@ -78,7 +78,17 @@ Serve the production build locally for testing.
 timber preview
 ```
 
-If your adapter provides a `preview()` method (e.g. Cloudflare's Miniflare-based preview), that takes priority. Otherwise falls back to Vite's built-in preview server.
+If your adapter provides a `preview()` method, that takes priority. Otherwise falls back to Vite's built-in preview server.
+
+Preview reads your project the same way `timber build` does: it resolves your Vite config, so options passed inline to `timber({ ... })`, a custom `--config`, and `build.outDir` all apply. It serves your last build using the `output` mode your config sets now. If you change `output`, rebuild before you preview:
+
+| Adapter | `output: 'server'` | `output: 'static'` |
+| --- | --- | --- |
+| Cloudflare | `wrangler dev --local` runs the Worker | `wrangler pages dev` serves the static site |
+| Nitro `node-server` / `bun` | A local Node (or Bun) server runs your app | A local static file server |
+| Other Nitro presets | Not supported. No local runtime, so preview exits with an error | A local static file server |
+
+The Nitro static preview serves under your `base` path, but it does not apply `_redirects` or `_headers` rules. Check those on your hosting platform.
 
 A `timber.config.ts` that exists but fails to load is a hard error naming the file — preview never silently falls back to the plain Vite preview server with your adapter ignored.
 

package/docs/learn/03-fetching-data.mdx

@@ -176,7 +176,23 @@ export const getUser = cache(async (id: string) => {
 });
 ```
 
-This deduplicates within a single request. For cross-request caching with TTL, use `timber.cache()` — see [Caching](/docs/caching).
+This deduplicates within a single request — across `middleware.ts`, `access.ts`, layouts, pages, and `route.ts` handlers, which all share one scope. Inside a server action `React.cache` does not dedupe (an action writes, so cached reads would go stale). The page that `revalidatePath()` re-renders afterwards starts fresh, so it sees the data the action just wrote.
+
+Pass request inputs in as arguments rather than reading them inside the cached function. A cached value doesn't see a cookie that middleware changes later in the same request, but a new argument is a new cache key:
+
+```tsx title="lib/session.ts"
+import { cache } from 'react';
+import { getCookieJar } from '@timber-js/app/server';
+
+declare function fetchUserBySession(token: string): Promise<{ id: string; name: string } | null>;
+
+// ✓ keyed on the token — a rotated or deleted session cookie is a cache miss
+export const getUserBySession = cache(async (token: string | undefined) =>
+  token ? fetchUserBySession(token) : null
+);
+
+export const getUser = () => getUserBySession(getCookieJar().get('session'));
+``` For cross-request caching with TTL, use `timber.cache()` — see [Caching](/docs/caching).
 
 ## Streaming Secondary Content
 

package/docs/learn/04-access-control.mdx

@@ -112,4 +112,4 @@ When access denies, that segment's `layout.tsx` never runs — `denied.tsx` rend
 
 ## Middleware vs Access
 
-`access.ts` runs inside the React tree, so it has `React.cache` and supports slot degradation. `middleware.ts` runs before rendering, for headers, redirects, and cache warming. The full comparison is in [Middleware](/docs/middleware).
+`access.ts` runs inside the React tree, so it gates each segment and supports slot degradation. `middleware.ts` runs before rendering, for headers, redirects, and cache warming. Both share the request's `React.cache` scope with your layouts and pages. The full comparison is in [Middleware](/docs/middleware).