@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.191

package/dist/server/prebuilt-builder.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Prebuilt payload capture — the post-build half of cache.component
+ * (TIM-1119, design/44-render-at-build-time.md §Build Phase).
+ *
+ * Runs AFTER Vite's 5-step build sequence, INSIDE the built RSC bundle:
+ * the component registry, the ALS instances, and the flight renderer are
+ * module instances in the bundle's graph, so the capture pass must share
+ * that graph — `server/rsc-entry/index.ts` re-exports this module's
+ * entry point as `__timber_capturePrebuilt`, and the timber-prebuilt
+ * plugin imports the built `rsc/index.js` and calls it.
+ *
+ * Per candidate route (a page with prebuilt components attributed by the
+ * build-time module-graph walk):
+ *
+ *   1. Load the page module (+ layout-chain modules that declare prebuilt
+ *      components) — module evaluation registers `__prebuilt` components.
+ *   2. Enumerate param combos: `generateStaticSegmentParams()` for dynamic
+ *      routes, the single empty combo for static routes.
+ *   3. Per combo, reconstruct the URL and run the REAL request-time pair —
+ *      `matchRoute` + `coerceSegmentParams` — so codec-coerced params hash
+ *      byte-identically to a live request. `computeComponentCacheKey` is
+ *      the single shared implementation (design/44 §Cache Key).
+ *   4. Render each registered component in isolation under a synthetic ALS
+ *      store (segment params only; cookies/headers/searchParams are hard
+ *      errors — synthetic-store.ts), fully drain the flight stream, and
+ *      smoke-revive the captured bytes once before accepting them.
+ *   5. Hand each payload to the caller's sink. Persistence (atomic file
+ *      writes, manifest.json) is the PLUGIN's job on the Node side —
+ *      keeping node:fs out of the server bundle, which must also run on
+ *      Cloudflare Workers.
+ *
+ * No payload source is registered while this runs, so wrappers rendered
+ * inside a captured subtree always miss and render live — inner output is
+ * baked flat into the outer entry, which is exactly the nesting clamp of
+ * design/45 §Nesting Semantics. The capture pass detects and reports the
+ * clamp (and fails cyclic entries) via capture-state.ts.
+ *
+ * Error policy (design/44 §Build-Phase Error Handling):
+ *   - `BuildTimeContextError` (cookies/headers/searchParams at build time)
+ *     → HARD error; the caller must fail the build.
+ *   - Anything else (bad data, deny(), cycles, timeouts, revival failures)
+ *     → skip that entry, warn, keep building.
+ */
+import type { CoercedParams } from '../shared/param-value.js';
+import type { ManifestRoot } from './route-matcher.js';
+/** One captured flight payload, ready for the caller's persistence sink. */
+export interface CapturedEntry {
+    componentId: string;
+    /** `computeComponentCacheKey(callSiteProps, coercedParams)` — names the .flight file. */
+    cacheKey: string;
+    /** The param combo — manifest metadata, not the hash input. */
+    params: CoercedParams;
+    /** Call-site props used for this entry (empty object for zero-prop usages). */
+    props?: Record<string, unknown>;
+    bytes: Uint8Array;
+    /** Resolved tags from callsite options — static or function-form, evaluated at capture time. */
+    tags?: string[];
+    /** Component does not read segment params — cache key uses `{}`. */
+    paramIndependent?: boolean;
+}
+/** A per-entry problem — either a skip (build continues) or a hard error. */
+export interface CaptureIssue {
+    componentId: string;
+    routeUrlPath: string;
+    params: CoercedParams;
+    message: string;
+}
+export interface CaptureSummary {
+    /** Entries captured, smoke-revived, and accepted by the sink. */
+    captured: number;
+    /** Skipped entries — reported, build continues (design/44 policy). */
+    skipped: CaptureIssue[];
+    /** Dynamic-context violations — the caller MUST fail the build. */
+    hardErrors: CaptureIssue[];
+    /** Nesting-clamp warnings emitted (design/45 §Nesting Semantics). */
+    nestingWarnings: number;
+}
+export interface CaptureOptions {
+    /**
+     * Route file path (page or layout, absolute) → prebuilt component IDs
+     * transitively reachable from it. Computed by the timber-prebuilt
+     * plugin's RSC module-graph walk at generateBundle time.
+     */
+    fileComponentMap: Record<string, string[]>;
+    /**
+     * Component ID → array of distinct static call-site prop objects captured
+     * from JSX usage sites (design/44 §Props Derivation). Each entry renders
+     * one payload per (props, params) combination. Components with no captured
+     * props (zero-prop usages) render with `{}` — the pre-TIM-1142 behavior.
+     */
+    callSiteProps?: Record<string, Record<string, unknown>[]>;
+    /**
+     * Persistence sink, called once per accepted payload. Throws propagate
+     * and abort the capture — a failed artifact write is an infrastructure
+     * failure, not a per-entry data problem.
+     */
+    onEntry: (entry: CapturedEntry) => Promise<void>;
+    /**
+     * Component ID → built chunk file name (or URL) for declaring modules
+     * behind dynamic imports. The capture pass imports these to trigger
+     * cache.component() registration before rendering.
+     */
+    lazyChunks?: Record<string, string>;
+    /** @internal Override chunk loader for testing. */
+    _loadChunk?: (chunkFile: string) => Promise<void>;
+    /**
+     * Per-entry ceiling on render + drain. A component that hangs (stalled
+     * fetch, unbounded recursion the cycle guard can't see) fails its entry
+     * instead of hanging the whole build — the A2 stream-read rule from
+     * design/13-security.md applied to the build process.
+     */
+    renderTimeoutMs?: number;
+    /** Progress/warning logger. Defaults to console.warn. */
+    log?: (message: string) => void;
+}
+/**
+ * Capture flight payloads for every attributed, registered, prerender-tier
+ * component across the route manifest. See module docblock for the flow.
+ */
+export declare function capturePrebuiltPayloads(manifest: ManifestRoot, options: CaptureOptions): Promise<CaptureSummary>;
+//# sourceMappingURL=prebuilt-builder.d.ts.map

package/dist/server/prebuilt-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prebuilt-builder.d.ts","sourceRoot":"","sources":["../../src/server/prebuilt-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAoB9D,OAAO,KAAK,EAAgB,YAAY,EAAuB,MAAM,oBAAoB,CAAC;AAO1F,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,yFAAyF;IACzF,QAAQ,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,MAAM,EAAE,aAAa,CAAC;IACtB,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,KAAK,EAAE,UAAU,CAAC;IAClB,gGAAgG;IAChG,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,oEAAoE;IACpE,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,aAAa,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,mEAAmE;IACnE,UAAU,EAAE,YAAY,EAAE,CAAC;IAC3B,qEAAqE;IACrE,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC3C;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;IAC1D;;;;OAIG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,mDAAmD;IACnD,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AA+UD;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,cAAc,CAAC,CA2TzB"}

package/dist/server/prebuilt-runtime.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Prebuilt component runtime — registration target for the timber-prebuilt
+ * transform (plugins/prebuilt.ts) and the request-time half of
+ * cache.component (TIM-1140).
+ *
+ * `cache.component(fn, opts)` call sites are rewritten at build time to
+ * `__prebuilt(stableId, fn, opts)` (production) or `__prebuiltDev(name, fn)`
+ * (dev). Both are exported via #server-internal — they are framework
+ * plumbing, never called by user code directly.
+ *
+ * Cache hits are served by FLIGHT REVIVAL: the cached `.flight` payload is
+ * decoded back into React elements inside the RSC environment with
+ * `createFromReadableStream` (the flight client running in the flight
+ * server — plugin-rsc wires the server-decode manifest so client
+ * references revive as re-serializable reference proxies). The revived
+ * element is returned from the wrapper and the outer render re-serializes
+ * it like any other subtree. This is the same mechanism as Next.js
+ * `"use cache"` (next/src/server/use-cache/use-cache-wrapper.ts).
+ *
+ * What a hit skips: all user work — data fetching, MDX compilation, the
+ * component function itself never runs. What it re-pays: React
+ * re-serializes the already-resolved tree (cost proportional to payload
+ * size, not to data latency). The alternative — splicing raw payload bytes
+ * into the outer stream — avoids re-serialization but requires byte-level
+ * coupling to the flight wire format (row framing, ID rebasing, marker
+ * detection); it was implemented and reviewed on PR #835 and deliberately
+ * replaced by revival. See design/44-render-at-build-time.md
+ * §Request-Time Injection.
+ *
+ * Misses render the original component live via the wrapper's own closure,
+ * inside the React pass — segment params from ALS, deny()/redirect()
+ * signals, Suspense, and error boundaries behave exactly as an unwrapped
+ * component. `fallbackOnMissingSegmentParams: false` throws instead.
+ */
+/**
+ * Set the timeout for component re-render captures. Called at boot from
+ * the RSC entry with renderTimeoutMs from timber.config.ts.
+ */
+export declare function setComponentRefreshTimeout(timeoutMs: number): void;
+/**
+ * Options captured from the `cache.component(fn, opts)` call site.
+ *
+ * `prerender`/`ttl`/`tags` (design/45) are carried through untouched — the
+ * build phase (TIM-1119) and runtime overlay (design/45 phase 3) consume
+ * them.
+ */
+export interface PrebuiltComponentOptions {
+    /** Populate the cache at build time via generateStaticSegmentParams. */
+    prerender?: boolean;
+    /** Runtime freshness window, seconds (design/45 runtime tier). */
+    ttl?: number;
+    /** Runtime invalidation tags (design/45 runtime tier). */
+    tags?: string[] | ((props: Record<string, unknown>) => string[]);
+    /** Serve stale while a background re-render refreshes (design/45 §SWR). */
+    staleWhileRevalidate?: boolean;
+    /**
+     * Slot props (TIM-1173): prop names whose values are live React
+     * elements composed into the cached shell at request time instead of
+     * participating in the cache. Each declared slot renders as a stable
+     * SlotOutlet client reference at capture time; the live value flows in
+     * through SlotContext per instance. Slot props are excluded from the
+     * cache key — only the remaining data props (+ segment params) hash.
+     * Runtime tier only: `prerender` is ignored (with a warning) because
+     * the build cannot enumerate children variants.
+     */
+    slots?: string[];
+    /**
+     * On a cache miss, render the component live (default: true). When false,
+     * a miss throws instead — for sites that must never render unknown params
+     * dynamically. See design/44 §fallbackOnMissingSegmentParams.
+     */
+    fallbackOnMissingSegmentParams?: boolean;
+}
+/** An async server component: props in, renderable out. */
+type ServerComponent = (props: any) => unknown;
+export interface PrebuiltRegistration {
+    id: string;
+    component: ServerComponent;
+    options: PrebuiltComponentOptions;
+}
+interface RscFunctions {
+    createFromReadableStream: (stream: ReadableStream<Uint8Array>) => Promise<unknown>;
+    renderToReadableStream: (element: unknown, options?: {
+        onError?: (error: unknown) => string;
+    }) => ReadableStream<Uint8Array>;
+}
+/**
+ * Wire the RSC flight client/server functions. Called once at server
+ * startup from the RSC entry module.
+ */
+export declare function setRscFunctions(fns: RscFunctions): void;
+/**
+ * Production wrapper injected by the timber-prebuilt transform. Registers
+ * the component under its stable ID and returns a wrapper component that
+ * either revives the cached payload (hit) or renders the original
+ * component live (miss).
+ */
+export declare function __prebuilt<C extends ServerComponent>(id: string, component: C, options?: PrebuiltComponentOptions): C;
+/** Look up a registration by stable component ID. */
+export declare function getPrebuiltRegistration(id: string): PrebuiltRegistration | undefined;
+/** All registrations, for the post-build capture pass (TIM-1119). */
+export declare function getPrebuiltRegistry(): ReadonlyMap<string, PrebuiltRegistration>;
+/**
+ * Dev-mode wrapper injected by the timber-prebuilt transform: a no-op that
+ * renders the component dynamically on every request, logging once per
+ * component on first render so the production behavior difference is visible.
+ * See design/44 §Dev Mode.
+ */
+export declare function __prebuiltDev<C extends ServerComponent>(name: string, component: C, options?: PrebuiltComponentOptions): C;
+export {};
+//# sourceMappingURL=prebuilt-runtime.d.ts.map

package/dist/server/prebuilt-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prebuilt-runtime.d.ts","sourceRoot":"","sources":["../../src/server/prebuilt-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AA+CH;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAGlE;AAID;;;;;;GAMG;AACH,MAAM,WAAW,wBAAwB;IACvC,wEAAwE;IACxE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC;IACjE,2EAA2E;IAC3E,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;;;;OAIG;IACH,8BAA8B,CAAC,EAAE,OAAO,CAAC;CAC1C;AAED,2DAA2D;AAE3D,KAAK,eAAe,GAAG,CAAC,KAAK,EAAE,GAAG,KAAK,OAAO,CAAC;AAY/C,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,eAAe,CAAC;IAC3B,OAAO,EAAE,wBAAwB,CAAC;CACnC;AAqID,UAAU,YAAY;IACpB,wBAAwB,EAAE,CAAC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACnF,sBAAsB,EAAE,CACtB,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAA;KAAE,KAC/C,cAAc,CAAC,UAAU,CAAC,CAAC;CACjC;AAID;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAEvD;AAoYD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,eAAe,EAClD,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,CAAC,EACZ,OAAO,GAAE,wBAA6B,GACrC,CAAC,CAoEH;AAED,qDAAqD;AACrD,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS,CAEpF;AAED,qEAAqE;AACrE,wBAAgB,mBAAmB,IAAI,WAAW,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAE/E;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,eAAe,EACrD,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,CAAC,EACZ,OAAO,GAAE,wBAA6B,GACrC,CAAC,CAmCH"}

package/dist/server/primitives.d.ts

@@ -13,6 +13,29 @@ export declare function findNonSerializable(value: unknown, path?: string): stri
 export declare class DenySignal extends Error {
     readonly status: number;
     readonly data: JsonSerializable | undefined;
+    /**
+     * Segment key of the segment that owns the deny page matched for this
+     * signal — set by a framework catch site that matched an entry it may not
+     * render at its own position, and re-threw so the boundary at the owning
+     * segment renders it instead.
+     *
+     * Written only by the three in-tree catch sites (`PageDenyBoundary`,
+     * `TracedLayout`, `AccessGate`), never by user code. Two readers depend on
+     * it: `TimberErrorBoundary`, which declines any deny whose `ownerKey` is
+     * not its own `segmentKey`, and `buildRscPayloadResponse`, which keeps
+     * streaming instead of re-rendering when it is set.
+     *
+     * See design/04-authorization.md §"Where a Deny Page Renders", TIM-1356.
+     */
+    ownerKey?: 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,37 +44,40 @@ export declare class DenySignal extends Error {
      */
     get sourceFile(): string | undefined;
 }
+/** Options for deny() when using the object form. */
+export interface DenyOptions {
+    /** HTTP status code (4xx or 5xx). Default: 403. */
+    status?: number;
+    /** Human-readable message (logged server-side, not sent to client). */
+    message?: string;
+    /** JSON-serializable data passed as `dangerouslyPassData` prop to status-code files. */
+    data?: 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)`.
+ * Supports both positional and object signatures:
+ * ```ts
+ * deny()                                          // 403 (default)
+ * deny(404)                                       // 404
+ * deny(503, { retry: true })                      // 503 with data
+ * deny({ status: 503, message: 'Maintenance' })   // object form
+ * ```
  *
- * 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. This replaces the need for
+ * `throw new RenderError(...)` in user code — RenderError is now an
+ * internal pipeline detail.
  *
- * 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 statusOrOptions - Status code (number) or options object. Default: 403.
+ * @param data - Optional JSON-serializable data (positional form only).
  */
-export declare const RedirectType: {
-    readonly push: "push";
-    readonly replace: "replace";
-};
+export declare function deny(statusOrOptions?: number | DenyOptions, data?: JsonSerializable): never;
+export { RedirectType } from '../shared/redirect-type.js';
 /**
  * Render-phase signal thrown by `redirect()` and `redirectExternal()`.
  * Caught by the framework to produce a 3xx response or client-side navigation.
@@ -61,28 +87,65 @@ export declare class RedirectSignal extends Error {
     readonly status: number;
     constructor(location: string, status: number);
 }
+/**
+ * Returns true if the error is a framework control-flow signal (RedirectSignal
+ * or DenySignal) rather than a genuine application error. Works both for direct
+ * instances (RSC-side) and deserialized digest errors (SSR cross-boundary).
+ *
+ * See also: isFrameworkSignalError() in client/browser-dev.ts (client-only).
+ */
+export declare function isControlFlowSignal(error: unknown): boolean;
+/**
+ * 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;
@@ -116,25 +179,18 @@ export declare class RenderError<TCode extends string = string, TData extends Js
         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

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":"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"}

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.js';
+/**
+ * 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/render-timeout.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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"
+ */
+/**
+ * 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;;;;;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,25 @@
+/**
+ * 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.
+ */
+/**
+ * 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) to
+ * ensure consistent Content-Length headers.
+ */
+export declare const NOINDEX_SCRIPT = "<script>document.head.appendChild(Object.assign(document.createElement(\"meta\"),{name:\"robots\",content:\"noindex\"}))</script>";
+//# 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;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAIpD;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,sIACoG,CAAC"}