@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

package/dist/server/primitives.d.ts

@@ -1,4 +1,5 @@
-import type { JsonSerializable } from './types.js';
+import type { JsonSerializable } from './types.ts';
+import { DENY_BRAND, REDIRECT_BRAND } from './signal-identity.ts';
 /**
  * Check if a value is JSON-serializable without data loss.
  * Returns a description of the first non-serializable value found, or null if OK.
@@ -9,10 +10,35 @@ export declare function findNonSerializable(value: unknown, path?: string): stri
 /**
  * Render-phase signal thrown by `deny()`. Caught by the framework to produce
  * the correct HTTP status code (segment context) or graceful degradation (slot context).
+ *
+ * Detect with `isDenySignal()`, never `instanceof` — see "Signal branding" in signal-identity.ts.
  */
 export declare class DenySignal extends Error {
+    readonly [DENY_BRAND] = true;
     readonly status: number;
     readonly data: JsonSerializable | undefined;
+    /**
+     * Ordered list of segment keys that own matching deny pages for this
+     * signal, best match first. Present = addressed (a boundary should
+     * render it); absent = unplaced (the re-render fallback serves it).
+     *
+     * In-tree hoists stamp a single-element list (`[entry.ownerKey]`) —
+     * identical to the pre-TIM-1450 `ownerKey`. Late addressing (TIM-1450)
+     * stamps the full candidate list so the client can find the first
+     * *reachable* owner via its ancestry context, eliminating the
+     * owner-below-throw-site escape.
+     *
+     * See design/04-authorization.md §"Where a Deny Page Renders", TIM-1356.
+     */
+    owners?: string[];
+    /**
+     * When true, the pipeline must respond with `rscErrorEnvelope` so the
+     * client hard-navigates instead of attempting to render a deny page
+     * from the RSC payload. Set by AccessGate when a skipped segment
+     * denies — rendering the deny page in-tree would appear inside the
+     * client's cached layout chrome (TIM-1074). See TIM-1363.
+     */
+    _hardNavigate?: boolean;
     constructor(status: number, data?: JsonSerializable);
     /**
      * Extract the file that called deny() from the stack trace.
@@ -21,138 +47,123 @@ export declare class DenySignal extends Error {
      */
     get sourceFile(): string | undefined;
 }
+/** Options for deny(). */
+export interface DenyOptions {
+    /** Human-readable message (logged server-side, not sent to client). */
+    message?: string;
+    /**
+     * JSON-serializable data forwarded as the `data` prop to status-code files
+     * and `denied.tsx`. Named `dangerouslyPassData` because this data crosses
+     * the RSC → client serialization boundary — do not pass sensitive server
+     * state (tokens, internal IDs, database rows).
+     */
+    dangerouslyPassData?: JsonSerializable;
+}
 /**
- * Universal denial primitive. Throws a `DenySignal` that the framework catches.
+ * Universal denial/error primitive. Throws a `DenySignal` that the framework catches.
  *
  * - In segment context (outside Suspense): produces HTTP status code
  * - In slot context: graceful degradation → denied.tsx → default.tsx → null
  * - Inside Suspense (hold window): promoted to pre-flush behavior
  * - Inside Suspense (after flush): error boundary + noindex meta
  *
- * @param status - Any 4xx HTTP status code. Defaults to 403.
- * @param data - Optional JSON-serializable data passed as `dangerouslyPassData` prop to status-code files.
- */
-export declare function deny(status?: number, data?: JsonSerializable): never;
-/**
- * Convenience alias for `deny(404)`.
+ * ```ts
+ * deny()                                                        // 403 (default)
+ * deny(404)                                                     // 404
+ * deny(503, { message: 'Maintenance' })                         // server-only log message
+ * deny(404, { dangerouslyPassData: { resourceId: params.id } }) // explicit client opt-in
+ * ```
  *
- * Provided for Next.js API compatibility — libraries and user code that
- * call `notFound()` from `next/navigation` get the same behavior as
- * `deny(404)` in timber.
- */
-export declare function notFound(): never;
-/**
- * Next.js redirect type discriminator.
+ * Accepts any 4xx or 5xx status code — it is also how a page renders a 5xx
+ * status file with data. An unplanned throw needs no primitive: it renders
+ * the error page with a 500.
  *
- * Provided for API compatibility with libraries that import `RedirectType`
- * from `next/navigation`. In timber, `redirect()` always uses `replace`
- * semantics (no history entry for the redirect itself).
+ * @param status - HTTP status code (4xx or 5xx). Default: 403.
+ * @param options - Optional message and/or data to pass to the client.
  */
-export declare const RedirectType: {
-    readonly push: "push";
-    readonly replace: "replace";
-};
+export declare function deny(status?: number, options?: DenyOptions): never;
+export { RedirectType } from '../shared/redirect-type.ts';
 /**
  * Render-phase signal thrown by `redirect()` and `redirectExternal()`.
  * Caught by the framework to produce a 3xx response or client-side navigation.
+ *
+ * Detect with `isRedirectSignal()`, never `instanceof` — see "Signal branding" in signal-identity.ts.
  */
 export declare class RedirectSignal extends Error {
+    readonly [REDIRECT_BRAND] = true;
     readonly location: string;
     readonly status: number;
     constructor(location: string, status: number);
 }
+/**
+ * Options for redirect() — alternative to passing a bare status code.
+ */
+export interface RedirectOptions {
+    /** HTTP redirect status code (3xx). Defaults to 302 (or 308 when `permanent: true`). */
+    status?: number;
+    /**
+     * When true, defaults the status to 308 (Permanent Redirect, preserves HTTP method).
+     * If `status` is also provided, `status` takes precedence.
+     *
+     * @example
+     * redirect('/new-path', { permanent: true });       // 308
+     * redirect('/new-path', { permanent: true, status: 301 }); // 301
+     */
+    permanent?: boolean;
+    /**
+     * Preserve search params from the current request URL on the redirect target.
+     *
+     * - `true` — preserve ALL current search params (target params take precedence)
+     * - `string[]` — preserve only the named params (e.g. `['private', 'token']`)
+     *
+     * Target path's own query params always take precedence over preserved ones.
+     */
+    preserveSearchParams?: true | string[];
+}
 /**
  * Redirect to a relative path. Rejects absolute and protocol-relative URLs.
  * Use `redirectExternal()` for external redirects with an allow-list.
  *
  * @param path - Relative path (e.g. '/login', 'settings', '/login?returnTo=/dash')
- * @param status - HTTP redirect status code (3xx). Defaults to 302.
- */
-export declare function redirect(path: string, status?: number): never;
-/**
- * Permanent redirect to a relative path. Shorthand for `redirect(path, 308)`.
+ * @param statusOrOptions - HTTP status code (3xx, default 302) or options object.
+ *
+ * @example
+ * // Simple redirect
+ * redirect('/login');
  *
- * Uses 308 (Permanent Redirect) which preserves the HTTP method — the browser
- * will replay POST requests to the new location. This matches Next.js behavior.
+ * // With status code
+ * redirect('/login', 301);
  *
- * @param path - Relative path (e.g. '/new-page', '/dashboard')
+ * // With preserved search params
+ * redirect(`/docs/${version}/${slug}`, { preserveSearchParams: ['foo'] });
  */
-export declare function permanentRedirect(path: string): never;
+export declare function redirect(path: string, statusOrOptions?: number | RedirectOptions): never;
 /**
- * Redirect to an external URL. The hostname must be in the provided allow-list.
+ * Redirect to an external URL. The origin must be in the provided allow-list.
+ *
+ * Only http: and https: schemes are permitted. The allow-list is matched
+ * against full origins (scheme + host + port), not bare hostnames.
  *
  * @param url - Absolute URL to redirect to.
- * @param allowList - Array of allowed hostnames (e.g. ['example.com', 'auth.example.com']).
+ * @param allowList - Array of allowed origins (e.g. ['https://example.com', 'https://auth.example.com']).
  * @param status - HTTP redirect status code (3xx). Defaults to 302.
  */
 export declare function redirectExternal(url: string, allowList: string[], status?: number): never;
-/**
- * Typed digest that crosses the RSC → client boundary.
- * The `code` identifies the error class; `data` carries JSON-serializable context.
- */
-export interface RenderErrorDigest<TCode extends string = string, TData extends JsonSerializable = JsonSerializable> {
-    code: TCode;
-    data: TData;
-}
-/**
- * Typed throw for render-phase errors that carry structured context to error boundaries.
- *
- * The `digest` (code + data) is serialized into the RSC stream separately from the
- * Error instance — only the digest crosses the RSC → client boundary.
- *
- * @example
- * ```ts
- * throw new RenderError('PRODUCT_NOT_FOUND', {
- *   title: 'Product not found',
- *   resourceId: params.id,
- * })
- * ```
- */
-export declare class RenderError<TCode extends string = string, TData extends JsonSerializable = JsonSerializable> extends Error {
-    readonly code: TCode;
-    readonly digest: RenderErrorDigest<TCode, TData>;
-    readonly status: number;
-    constructor(code: TCode, data: TData, options?: {
-        status?: number;
-    });
-}
-/** Minimal interface for adapters that support background work. */
-export interface WaitUntilAdapter {
-    waitUntil?(promise: Promise<unknown>): void;
-}
 /**
  * Register a promise to be kept alive after the response is sent.
  * Maps to `ctx.waitUntil()` on Cloudflare Workers and similar platforms.
  *
- * In production, the platform adapter installs a per-request waitUntil
- * function via ALS (see waituntil-bridge.ts). This function checks the
- * ALS bridge first, then falls back to the legacy adapter argument.
- *
- * If neither is available, a warning is logged once and the promise is
- * left to resolve (or reject) without being tracked.
+ * The platform adapter installs a per-request waitUntil function via ALS
+ * (see waituntil-bridge.ts). If no ALS handler is available, a warning
+ * is logged once and the promise is left to resolve (or reject) without
+ * being tracked.
  *
  * @param promise - The background work to keep alive.
- * @param adapter - Optional legacy adapter (prefer ALS bridge in production).
  */
-export declare function waitUntil(promise: Promise<unknown>, adapter?: WaitUntilAdapter): void;
+export declare function waitUntil(promise: Promise<unknown>): void;
 /**
  * Reset the waitUntil warning state. Exported for testing only.
  * @internal
  */
 export declare function _resetWaitUntilWarning(): void;
-/**
- * Error thrown when SSR's renderToReadableStream fails due to an error
- * in the decoded RSC stream (e.g., uncontained slot errors).
- *
- * The RSC entry checks for this error type in its catch block to avoid
- * re-executing server components via renderDenyPage. Instead, it renders
- * a bare deny/error page without layout wrapping.
- *
- * Defined in primitives.ts (not ssr-entry.ts) because ssr-entry.ts imports
- * react-dom/server which cannot be loaded in the RSC environment.
- */
-export declare class SsrStreamError extends Error {
-    readonly cause: unknown;
-    constructor(message: string, cause: unknown);
-}
 //# sourceMappingURL=primitives.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../../src/server/primitives.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAMnD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,SAAS,GAAG,MAAM,GAAG,IAAI,CA8DhF;AAsBD;;;GAGG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,SAAS,CAAC;gBAEhC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB;IAOnD;;;;OAIG;IACH,IAAI,UAAU,IAAI,MAAM,GAAG,SAAS,CAqBnC;CACF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,IAAI,CAAC,MAAM,GAAE,MAAY,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,KAAK,CASzE;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,IAAI,KAAK,CAEhC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,YAAY;;;CAGf,CAAC;AAIX;;;GAGG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAM7C;AAKD;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,MAAY,GAAG,KAAK,CAWlE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAErD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,MAAM,GAAE,MAAY,GAAG,KAAK,CAoB9F;AAID;;;GAGG;AACH,MAAM,WAAW,iBAAiB,CAChC,KAAK,SAAS,MAAM,GAAG,MAAM,EAC7B,KAAK,SAAS,gBAAgB,GAAG,gBAAgB;IAEjD,IAAI,EAAE,KAAK,CAAC;IACZ,IAAI,EAAE,KAAK,CAAC;CACb;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,WAAW,CACtB,KAAK,SAAS,MAAM,GAAG,MAAM,EAC7B,KAAK,SAAS,gBAAgB,GAAG,gBAAgB,CACjD,SAAQ,KAAK;IACb,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;CAcpE;AAID,mEAAmE;AACnE,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;CAC7C;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAqBrF;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C;AAID;;;;;;;;;;GAUG;AACH,qBAAa,cAAe,SAAQ,KAAK;aAGrB,KAAK,EAAE,OAAO;gBAD9B,OAAO,EAAE,MAAM,EACC,KAAK,EAAE,OAAO;CAKjC"}
+{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../../src/server/primitives.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAKnD,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAQlE;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,SAAS,GAAG,MAAM,GAAG,IAAI,CA8DhF;AAsBD;;;;;GAKG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,CAAC,UAAU,CAAC,QAAQ;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAE5C;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAElB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB,YAAY,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,EAKlD;IAED;;;;OAIG;IACH,IAAI,UAAU,IAAI,MAAM,GAAG,SAAS,CAqBnC;CACF;AAED,0BAA0B;AAC1B,MAAM,WAAW,WAAW;IAC1B,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,gBAAgB,CAAC;CACxC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,KAAK,CASlE;AAID,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAI1D;;;;;GAKG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,CAAC,cAAc,CAAC,QAAQ;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,YAAY,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAK3C;CACF;AAID;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,wFAAwF;IACxF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE,IAAI,GAAG,MAAM,EAAE,CAAC;CACxC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,eAAe,GAAG,KAAK,CA4BxF;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,MAAM,GAAE,MAAY,GAAG,KAAK,CAO9F;AAQD;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAczD;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}

package/dist/server/publish-params.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Publishing the request's params onto the RSC payload.
+ *
+ * Every tree the server sends the browser goes through here: the ordinary
+ * route payload (`route-element-builder.ts`), both deny renderers
+ * (`deny-renderer.ts`) and the error renderer. One helper rather than a wrap
+ * at each site, because these previously *were* separate sites — a response
+ * header, an inline script, and a second copy of each on the deny path — and
+ * the deny path shipping empty params was the bug that came of it (TIM-1285).
+ *
+ * Reads the request store rather than taking params as an argument, so a
+ * caller cannot pass a different record than the one the request rendered
+ * with. See design/41-global-params.md §"Transport".
+ */
+import type { RscPayloadRoot } from '../shared/payload-root.ts';
+/**
+ * Build the payload root: the tree, and the params it rendered with beside it.
+ *
+ * The params are a *sibling* of the tree, not a provider around it. A provider
+ * inside the payload is shadowed by the retained tree's own provider on a
+ * partial navigation, and its props are not readable at the instant the root
+ * row resolves — see `shared/payload-root.ts` for both, and TIM-1297. The
+ * client renders the one provider readers see, above the merge point.
+ *
+ * The records are flattened to plain objects on the way out. Every param
+ * record the framework builds is `Object.create(null)` (design/13-security.md
+ * #36b/#36c), and React Flight rejects a null prototype — "Classes or null
+ * prototypes are not supported". `ParamsProvider` restores the prototype on
+ * the other side, so what the app reads is unchanged; only the wire
+ * representation differs.
+ */
+export declare function withPublishedParams(element: React.ReactElement): RscPayloadRoot;
+//# sourceMappingURL=publish-params.d.ts.map

package/dist/server/publish-params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish-params.d.ts","sourceRoot":"","sources":["../../src/server/publish-params.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAGhE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,YAAY,GAAG,cAAc,CAM/E"}

package/dist/server/react-cache-bridge.d.ts

@@ -0,0 +1,59 @@
+/**
+ * React.cache bridge — one `React.cache` scope per request, shared by
+ * `proxy.ts`, `middleware.ts`, route handlers, and the render.
+ *
+ * `React.cache(fn)` stores its memo table in whatever Map
+ * `ReactSharedInternals.A.getCacheForType()` returns. `A` is Flight's
+ * `DefaultAsyncDispatcher`, whose `getCacheForType` returns the active Flight
+ * request's `cache` Map, or a throwaway `new Map()` outside a render. So
+ * without this bridge a `React.cache` call in middleware silently never
+ * dedupes with the same call in `access.ts` or a layout.
+ *
+ * The bridge wraps that one method on the existing dispatcher object:
+ *
+ * - When a timber scope is active (`reactCacheScopeAls`), it returns the
+ *   scope's Map — inside or outside a Flight render.
+ * - Otherwise it calls Flight's original method, so behaviour outside a
+ *   request (build-time capture, tests, isolated renders) is unchanged.
+ *
+ * Opening, resuming, and leaving scopes lives in `react-cache-scope.ts`,
+ * which does not import `react` so request-context and cookie code can use it.
+ *
+ * Constraints (TIM-1529, design/spike-TIM-1529-react-cache-bridge.md):
+ *
+ * - Never reassign `ReactSharedInternals.A`. Flight's `Request` constructor
+ *   throws "Currently React only supports one RSC renderer at a time" when
+ *   `A` is set to anything but its own dispatcher.
+ * - Never shim the `react` module's `cache` export and never patch the
+ *   vendored Flight bundle.
+ * - Flight installs `A` lazily, in the `Request` constructor, so it is
+ *   `null` until the first render. `installReactCacheBridge` takes a
+ *   `warmUp` callback that constructs one throwaway render to install it.
+ * - Idempotent: a program reload that re-evaluates this module but not
+ *   Flight finds the brand on the live method and does not wrap it twice.
+ *   A reload that re-evaluates Flight too hands back a fresh dispatcher,
+ *   which the re-evaluated RSC entry patches again. The wrapper closes over
+ *   nothing but the `globalThis`-anchored ALS, so an old wrapper that
+ *   survives a reload still reads the current scope.
+ */
+/** Result of `installReactCacheBridge`, for the boot log and the canary test. */
+export type ReactCacheBridgeStatus = {
+    installed: true;
+    alreadyBridged: boolean;
+} | {
+    installed: false;
+    reason: string;
+};
+/**
+ * Patch Flight's dispatcher so `React.cache` resolves the active timber
+ * scope. Call once from the RSC entry, after the Flight server has loaded.
+ *
+ * `warmUp` must construct a Flight render (e.g. `renderToReadableStream(null)`
+ * and cancel it) — that is the only public way to make Flight install `A`.
+ *
+ * Never throws: if React's internals change shape the bridge is skipped,
+ * `React.cache` keeps its stock per-render behaviour, and the reason is
+ * returned. `tests/react-cache-bridge.test.ts` fails CI on that path.
+ */
+export declare function installReactCacheBridge(warmUp: () => void): ReactCacheBridgeStatus;
+//# sourceMappingURL=react-cache-bridge.d.ts.map

package/dist/server/react-cache-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react-cache-bridge.d.ts","sourceRoot":"","sources":["../../src/server/react-cache-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AA+BH,iFAAiF;AACjF,MAAM,MAAM,sBAAsB,GAC9B;IAAE,SAAS,EAAE,IAAI,CAAC;IAAC,cAAc,EAAE,OAAO,CAAA;CAAE,GAC5C;IAAE,SAAS,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzC;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,IAAI,GAAG,sBAAsB,CAuClF"}

package/dist/server/react-cache-scope.d.ts

@@ -0,0 +1,49 @@
+/**
+ * React.cache scopes — opening, resuming, and leaving the per-request
+ * `React.cache` scope that `react-cache-bridge.ts` makes Flight read.
+ *
+ * Kept apart from the bridge so request-context and cookie code can use
+ * it without importing `react`. See design/spike-TIM-1529-react-cache-bridge.md.
+ */
+import { type ReactCacheScope } from './als-registry.ts';
+export type { ReactCacheScope };
+/** A new, empty `React.cache` scope. */
+export declare function createReactCacheScope(): ReactCacheScope;
+/**
+ * Run `fn` in a `React.cache` scope — a fresh one unless `scope` is given.
+ * Every `React.cache` call made from `fn` — synchronously, in its async
+ * continuations, and in any Flight render it starts — shares one memo table.
+ *
+ * Opened by `runWithRequestContext`, so each request context gets its own
+ * scope. Pass `scope` to resume one across two ALS runs: the post-action
+ * revalidation opens a fresh scope for the target route's middleware and
+ * renders the revalidated tree in that same scope later.
+ */
+export declare function runWithReactCacheScope<T>(fn: () => T, scope?: ReactCacheScope): T;
+/**
+ * Run `fn` with no timber scope, so `React.cache` behaves as stock React:
+ * no dedupe outside a render, Flight's own per-render cache inside one.
+ *
+ * Used for server action bodies — an action reads, writes cookies, and
+ * mutates, so memoized reads would go stale mid-action (the same choice
+ * Next.js makes) — and for renders whose output outlives the request
+ * (`cache.component` capture), which must not bake request-memoized values
+ * into a cross-request cache entry.
+ */
+export declare function runOutsideReactCacheScope<T>(fn: () => T): T;
+/** Stands for "every cookie" — a getAll()/size read, or a clear() write. */
+export declare const ANY_COOKIE = "*";
+/**
+ * Dev-only: record that cookie `name` (or {@link ANY_COOKIE}) was read
+ * while `React.cache` held values in this request — the read may have
+ * happened inside a cached function.
+ */
+export declare function noteCookieReadForReactCache(name: string): void;
+/**
+ * Dev-only: warn (once per request) when a cookie recorded by
+ * {@link noteCookieReadForReactCache} is written. `name` is the written
+ * cookie, or {@link ANY_COOKIE} for `clear()`. Dev-only because reads are
+ * only recorded in dev.
+ */
+export declare function warnIfCachedCookieIsWritten(name: string): void;
+//# sourceMappingURL=react-cache-scope.d.ts.map

package/dist/server/react-cache-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react-cache-scope.d.ts","sourceRoot":"","sources":["../../src/server/react-cache-scope.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAsB,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAG7E,YAAY,EAAE,eAAe,EAAE,CAAC;AAEhC,wCAAwC;AACxC,wBAAgB,qBAAqB,IAAI,eAAe,CAEvD;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,EAAE,EAAE,MAAM,CAAC,EACX,KAAK,GAAE,eAAyC,GAC/C,CAAC,CAEH;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAE3D;AAaD,4EAA4E;AAC5E,eAAO,MAAM,UAAU,MAAM,CAAC;AAK9B;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAU9D;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAc9D"}

package/dist/server/render-timeout.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Render timeout utilities for SSR streaming pipeline.
+ *
+ * Provides a RenderTimeoutError class and a helper to create
+ * timeout-guarded AbortSignals. Used to defend against hung RSC
+ * streams and infinite SSR renders.
+ *
+ * Design doc: 02-rendering-pipeline.md §"Streaming Constraints"
+ */
+/** `renderTimeoutMs` when timber.config.ts leaves it unset. */
+export declare const DEFAULT_RENDER_TIMEOUT_MS = 30000;
+/**
+ * What `renderTimeoutMs: 0` means: a safety ceiling, never "no timeout" —
+ * an unbounded render or singleflight wait can hang a connection or
+ * deadlock a cache key forever.
+ */
+export declare const RENDER_TIMEOUT_CEILING_MS = 120000;
+/**
+ * The one mapping from configured `renderTimeoutMs` to the timeout every
+ * consumer enforces. Config enters the runtime already resolved (the
+ * runtime config module, static generation's options), so readers never
+ * see 0 or undefined.
+ */
+export declare function resolveRenderTimeoutMs(configured: number | undefined): number;
+/**
+ * Error thrown when an SSR render or RSC stream read exceeds the
+ * configured timeout. Callers can check `instanceof RenderTimeoutError`
+ * to distinguish timeout from other errors and return a 504 or close
+ * the connection cleanly.
+ */
+export declare class RenderTimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number, context?: string);
+}
+/**
+ * Result of createRenderTimeout — an AbortSignal that fires after
+ * the given duration, plus a cancel function to clear the timer
+ * when the render completes normally.
+ */
+export interface RenderTimeout {
+    /** AbortSignal that aborts after timeoutMs. */
+    signal: AbortSignal;
+    /** Cancel the timeout timer. Call this when the render completes. */
+    cancel: () => void;
+}
+/**
+ * Create a render timeout that aborts after the given duration.
+ *
+ * Returns an AbortSignal and a cancel function. The signal fires
+ * with a RenderTimeoutError as the abort reason after `timeoutMs`.
+ * Call `cancel()` when the render completes to prevent the timeout
+ * from firing.
+ *
+ * If an existing `parentSignal` is provided, the returned signal
+ * aborts when either the parent signal or the timeout fires —
+ * whichever comes first.
+ */
+export declare function createRenderTimeout(timeoutMs: number, parentSignal?: AbortSignal): RenderTimeout;
+/**
+ * Race a promise against a timeout. Rejects with RenderTimeoutError
+ * if the promise does not resolve within `timeoutMs`.
+ *
+ * Used to guard individual `rscReader.read()` calls inside pullLoop.
+ */
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, context?: string): Promise<T>;
+//# sourceMappingURL=render-timeout.d.ts.map

package/dist/server/render-timeout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-timeout.d.ts","sourceRoot":"","sources":["../../src/server/render-timeout.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,+DAA+D;AAC/D,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAEhD;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,SAAU,CAAC;AAEjD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAE7E;AAED;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,YAAY,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAO9C;CACF;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,+CAA+C;IAC/C,MAAM,EAAE,WAAW,CAAC;IACpB,qEAAqE;IACrE,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,WAAW,GAAG,aAAa,CA+BhG;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,CAAC,CAAC,CAWZ"}

package/dist/server/render-utils.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared render-phase utilities — used by both the Node.js and Web
+ * stream wrappers. Pure functions only; no stream-shape dependencies.
+ *
+ * Consolidated from duplicated copies in node-stream-transforms.ts,
+ * ssr-render.ts, and rsc-entry/helpers.ts. See TIM-1071 item 1.
+ */
+/**
+ * The ` nonce="…"` attribute fragment for a timber-generated `<script>` tag,
+ * or `''` when the request has no nonce. Callers interpolate it directly
+ * after the tag name: `` `<script${nonceAttr(nonce)}>` ``.
+ *
+ * The value comes from `generateNonce` in csp-nonce.ts and is base64, so no attribute
+ * escaping is required.
+ */
+export declare function nonceAttr(nonce: string | undefined): string;
+/**
+ * Check if an error is an abort error (connection closed by client).
+ *
+ * When the browser aborts a request (page refresh, navigation away),
+ * the AbortSignal fires and React/streams throw an AbortError. This
+ * is not an application error — suppress it from error boundaries and logs.
+ */
+export declare function isAbortError(error: unknown): boolean;
+/**
+ * Inline script that adds `<meta name="robots" content="noindex">` to the
+ * document head. Injected when a render-phase error replaces the shell so
+ * search engines don't index error pages.
+ *
+ * MUST be byte-identical across all stream wrappers (Node and Web) for a
+ * given nonce to ensure consistent Content-Length headers — which is why
+ * both wrappers call this one function rather than inlining the string.
+ */
+export declare function noindexScript(nonce?: string): string;
+//# sourceMappingURL=render-utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"render-utils.d.ts","sourceRoot":"","sources":["../../src/server/render-utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAE3D;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAIpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAEpD"}