@rangojs/router 0.16.0 → 0.18.0

package/dist/types/rsc/ssr-setup.d.ts

@@ -33,11 +33,11 @@ export interface SsrHtmlStageOptions<TEnv> {
     /** Metrics store for ssr:module-load / ssr:stream-mode timing (per call site). */
     metricsStore: MetricsStore | undefined;
     /**
-     * renderHTML options minus streamMode (the stage resolves streamMode). Carries
-     * the per-site nonce and, for the PE action re-render, formState. Spread
-     * verbatim so each call site's exact key set is preserved.
+     * renderHTML options minus streamMode and onError (the stage owns both).
+     * Carries the per-site nonce and, for the PE action re-render, formState.
+     * Spread verbatim so each call site's exact key set is preserved.
      */
-    render: Omit<SSRRenderOptions, "streamMode">;
+    render: Omit<SSRRenderOptions, "streamMode" | "onError">;
     /** ResponseInit merged into the prepared render (e.g. content-type). */
     init?: ResponseInit;
 }
@@ -59,8 +59,8 @@ export declare function getSSRSetup<TEnv>(ctx: HandlerContext<TEnv>, request: Re
  * Classify whether a request may require SSR (HTML rendering).
  *
  * Returns false for requests that are definitively RSC-only: transport
- * params (partial/action/loader/__rsc), prerender collection, or an explicit
- * Accept: text/x-component. Must never return false for a request whose
+ * params (partial/action/loader/__rsc) or an explicit Accept:
+ * text/x-component. Must never return false for a request whose
  * render-time decision (isRscRequest) will be HTML — the two share
  * acceptsFlightExplicitly so the Accept rule cannot drift. document-cache.ts
  * keys its HTML/RSC response slots off this function, so any divergence from

package/dist/types/rsc/types.d.ts

@@ -181,6 +181,12 @@ export interface SSRRenderOptions {
      * the browser across hydration. Absent on host-agnostic build captures.
      */
     origin?: string;
+    /**
+     * Called for each error Fizz reports through its onError: a component that
+     * threw inside a Suspense boundary, which leaves the boundary errored in an
+     * otherwise completed document. React's default console.error is kept.
+     */
+    onError?: (error: unknown) => void;
 }
 /**
  * SSR module interface for HTML rendering
@@ -200,6 +206,15 @@ export interface SSRModule {
         maxWaitMs?: number;
         search?: string;
         origin?: string;
+        /** Each component error the prerender reports (never the capture's own abort). */
+        onError?: (error: unknown) => void;
+        /**
+         * React's errorInfo for each task still pending at the capture's abort
+         * (its componentStack is computed when read).
+         */
+        onAbortedTask?: (errorInfo: {
+            componentStack?: string;
+        } | undefined) => void;
     }) => Promise<{
         prelude: Uint8Array;
         postponed: string | null;
@@ -217,6 +232,8 @@ export interface SSRModule {
         nonce?: string;
         search?: string;
         origin?: string;
+        /** Each component error the resumed holes report. */
+        onError?: (error: unknown) => void;
     }) => Promise<ReadableStream<Uint8Array>>;
 }
 /**

package/dist/types/server/context.d.ts

@@ -2,6 +2,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import type { ReactNode } from "react";
 import type { PartialCacheOptions, ErrorBoundaryHandler, Handler, LoaderDefinition, MiddlewareFn, NotFoundBoundaryHandler, ShouldRevalidateFn, TransitionConfig } from "../types";
 import type { DefaultRouteName } from "../types/global-namespace.js";
+import type { ContextVar } from "../context-var.js";
 /**
  * Performance metric entry for a single measured operation
  *
@@ -44,6 +45,17 @@ export type EntryPropCommon = {
     id: string;
     shortCode: string;
     parent: EntryData | null;
+    /**
+     * Orphan siblings only (attachOrphanSibling in
+     * route-definition/dsl-helpers.ts): the entry whose `layout[]` holds this
+     * one. `parent` stays null on an orphan (matchError's matched-id stack in
+     * router/match-api.ts starts at the boundary-holding entry, possibly an
+     * orphan, and must stop there), so the boundary walkers in
+     * router/error-handling.ts follow this instead. A lookup that starts at an
+     * orphan (its loaders, an intercept it declares) then reaches the owner's
+     * boundaries and the owner's ancestors.
+     */
+    orphanOwner?: EntryData;
     /** Cache configuration for this entry (set by cache() DSL) */
     cache?: EntryCacheConfig;
     /** URL prefix from include() scope, used for MountContext on client */
@@ -94,6 +106,15 @@ export type LoaderEntry = {
      * appears on navigation-lane entries.
      */
     awaitBeforeFlush?: true;
+    /**
+     * loader(Def, { ssr: false }) on every DSL evaluation, document and
+     * navigation: the loader's PPR bake lane (loader-cache.ts
+     * resolveLoaderData). The bake/seed key rides on it, so a client
+     * navigation's shell replay pins exactly the loaders a document HIT pins,
+     * whatever the entry's loading(). awaitBeforeFlush cannot carry that: a
+     * navigation evaluation never has it.
+     */
+    bake?: true;
 };
 /**
  * Segments state for intercept context
@@ -156,9 +177,6 @@ export type InterceptEntry = {
     routeName: string;
     handler: ReactNode | Handler<any, any, any>;
     middleware: MiddlewareFn<any, any>[];
-    revalidate: ShouldRevalidateFn<any, any>[];
-    errorBoundary: (ReactNode | ErrorBoundaryHandler)[];
-    notFoundBoundary: (ReactNode | NotFoundBoundaryHandler)[];
     loader: LoaderEntry[];
     loading?: ReactNode | false;
     transition?: TransitionConfig;
@@ -399,10 +417,113 @@ export declare function getParallelSlotCount(parallels: ParallelEntries | EntryD
 export declare function track(label: string, depth?: number): () => void;
 /**
  * Check if the current execution is inside a cache() DSL boundary.
- * Returns false inside loader execution — loaders are always fresh
- * (never cached), so non-cacheable reads are safe.
+ * Returns false inside loader execution: a route cache() does not store
+ * loader values, so non-cacheable reads are safe. A loader bound with its own
+ * cache() stores its value; recordLoaderIdentityRead guards that.
  */
 export declare function isInsideCacheScope(): boolean;
+/**
+ * Throw if called during the ACTIVE background shell-capture render
+ * (`_shellCaptureRun` true on the derived request context built by
+ * shell-capture.ts). The captured shell is shared across every user hitting
+ * the URL, so a request-scoped read here would bake one user's cookies,
+ * headers, or per-request variables into markup served to others — same
+ * hazard as the cache scopes above, at the document tier. DSL segment loaders
+ * need no exemption: the live lane is masked (never executed) during capture,
+ * and the bake lane is exactly what this guard exists for.
+ *
+ * It covers everything the capture waits for, not only synchronous handler
+ * code: a promise the handler passes or pushes, an async server component,
+ * and a loader the handler awaits (`await ctx.use(Loader)`) all run under the
+ * capture context and all bake. The last one used to be exempt (the
+ * consumption-lane rule, #672/#674): while a HIT re-ran handlers, a slot
+ * handler's `ctx.use` of an identity loader rendered per visitor on the HIT.
+ * Now every HIT replays the capture's copy, so the exemption would bake the
+ * capturing request's identity into every visitor's page. The cache()
+ * guards above keep it (a cache() HIT is a separate tier).
+ *
+ * Keys off `_shellCaptureRun`, NOT the `_shellCapture` descriptor: the descriptor
+ * is also present during the FOREGROUND render (it means "a capture is wanted"),
+ * and the foreground must read cookies/headers normally to serve the real user.
+ * Only the derived capture context sets `_shellCaptureRun`.
+ *
+ * Applies only to the READ surfaces (cookies(), headers(), a { cache: false }
+ * variable, and the theme reads through tripShellCaptureGuard) whose values
+ * become markup. Response directives
+ * (invalidateClientCache(), keepClientCache()) stay callable: during capture
+ * they are header effects on a discarded response, and on the live HIT path
+ * the full pipeline runs so their headers flow to the client normally.
+ *
+ * The throw can be caught by the code that made the read, so the guard also
+ * flags the capture context; the capture refuses on the flag
+ * (shell-capture.ts refuseOnCaptureGuard), nothing is stored, and every
+ * request keeps getting the normal axis-1 render.
+ */
+export declare function assertNotInsideShellCapture(ctx: unknown, fnName: string): void;
+/**
+ * True when `ctx` is the active capture render (assertNotInsideShellCapture
+ * above). On true the capture context is flagged with the read (`surface`,
+ * e.g. "cookies()", "ctx.theme") and the fix the refusal warning gives, plus
+ * the loader body (if any) that made the read, and the caller throws.
+ */
+export declare function tripShellCaptureGuard(ctx: unknown, surface: string, fix: string): boolean;
+/**
+ * Read guard for a non-cacheable variable (`createVar({ cache: false })` or a
+ * `ctx.set(..., { cache: false })` write). Callers check isNonCacheable() first
+ * so ordinary reads never reach the scope lookups.
+ *
+ * Throws during a PPR shell capture (`requestCtx` is the ambient request
+ * context; assertNotInsideShellCapture): the shell is shared per host+URL.
+ *
+ * Throws inside a "use cache" body: the key does not include the value, so the
+ * first caller's value would be stored and served to later callers (#925). A
+ * loader body entered INSIDE the cached function is exempt, the same baked-copy
+ * trade isInsideCacheScope() makes for cache(). A cached function called FROM a
+ * loader is not: the loader re-runs, the cached body does not. The body scope
+ * records the exec scope it was entered in, so the exemption holds only while
+ * that is still the innermost one.
+ */
+export declare function assertNonCacheableReadAllowed(keyOrVar: string | ContextVar<unknown>, requestCtx?: unknown): void;
+/** How the identity error words a read: a function call or a property read. */
+export type LoaderIdentityReadVerb = "called" | "read";
+/** A request-identity read a loader execution made (recordLoaderIdentityRead). */
+export interface LoaderIdentityRead {
+    /**
+     * The read as the error names it: "cookies()", "headers()",
+     * `ctx.get() for a non-cacheable variable "x"`, "ctx.theme" or
+     * "getRequestContext().theme".
+     */
+    surface: string;
+    /** "called" for a function, "read" for a property (the theme getters). */
+    verb: LoaderIdentityReadVerb;
+    /** The loader body that made the read. */
+    bodyId: string | undefined;
+    /**
+     * The cached loader whose value carries a read another loader made
+     * (loader-cache.ts identity mark): its readers read it through `via`.
+     */
+    via?: string;
+}
+/**
+ * Record a request-identity read (cookies(), headers(), a non-cacheable
+ * ctx.get()) on the current loader execution (#972).
+ *
+ * isInsideCacheScope() exempts loader bodies because a route cache() never
+ * stores their values. A loader bound with its own cache() does: with no key()
+ * and no store keyGenerator its entry is keyed by loader, host, path and
+ * params only, and an enclosing route cache() key does not partition it
+ * (#974). A cookies() read there stored the first visitor's session and served
+ * it to everyone for the TTL. The read is recorded on the execution, not
+ * thrown at the call: a reader that starts the loader before its binding does
+ * runs it outside any fill, and the binding's MISS then reuses that run. The
+ * fill checks what its execution recorded, through the same links as its tags
+ * (cache-tag.ts recordedIdentityRead), so both orders fail the same way.
+ * Response directives do not record: a key cannot make a skipped body's side
+ * effect reach a HIT.
+ */
+export declare function recordLoaderIdentityRead(surface: string, verb?: LoaderIdentityReadVerb): void;
+/** The error a loader cache() fill with no declared key fails with (#972). */
+export declare function loaderCacheIdentityError(read: LoaderIdentityRead, cachedLoaderId: string): Error;
 /**
  * Check if the current execution is inside a DSL loader scope
  * (wrapped by runInsideLoaderScope). Used by rendered() barrier
@@ -416,6 +537,10 @@ export declare function isInsideLoaderScope(): boolean;
  * Takes scalars so the already-latched path allocates nothing.
  */
 export declare function latchCachedHeaderScope(kind: CachedHeaderScope["kind"], routeKey?: string): void;
+/** True inside ANY loader execution — DSL loader scope or a loader body
+ *  (however invoked). The "loaders always re-run fresh" exemptions key off
+ *  this. */
+export declare function isInsideAnyLoaderScope(): boolean;
 /**
  * The one ppr opt-in predicate: a page route entry that DECLARED `ppr`
  * (`false` and undefined mean plain axis 1). Shared by the serve path
@@ -488,26 +613,25 @@ export declare function runInsideLoaderScope<T>(fn: () => T): T;
  * and handler-invoked via ctx.use) so request-scoped reads inside a loader
  * never trip the cache-scope guards — loaders always run fresh.
  */
-export declare function runInsideLoaderBodyScope<T>(fn: () => T, loaderId?: string, handlerInvoked?: boolean): T;
+export declare function runInsideLoaderBodyScope<T>(fn: () => T, loaderId?: string, tags?: Set<string>): T;
+/** The innermost loader body's execution tag set (runInsideLoaderBodyScope). */
+export declare function getLoaderBodyTags(): Set<string> | undefined;
 /**
  * The $$id of the loader whose body is currently executing, or undefined
  * outside any loader body. Used by the shell-capture identity guard
- * (cookie-store.ts) so its refusal warning can name the loader that read
+ * (assertNotInsideShellCapture) so its refusal warning can name the loader that read
  * cookies()/headers() instead of blaming a lane it cannot see — the old
  * hardcoded "bake-lane loader" text misled a live-lane debugging session
  * (issue #672, secondary).
  */
 export declare function getCurrentLoaderBodyId(): string | undefined;
 /**
- * True while a HANDLER-invoked loader body (`await ctx.use(Loader)` from a
- * handler, not the DSL segment funnel) is executing. The consumption-lane
- * rule keys off this: handler consumption yields a BAKED copy in every shared
- * artifact — cache(), "use cache", and the PPR shell — so the shell-capture
- * identity guard (cookie-store.ts) permits cookies()/headers() here, exactly
- * like the cache-purity guards do. DSL segment loaders (live lane masked at
- * capture, bake lane guarded) never set the flag.
+ * True while `loaderId`'s body, or a loader it awaits via ctx.use at any
+ * depth, is executing. The loader-level cache records these pushes
+ * (loader-cache.ts): a HIT skips the cached body, so a dep that no other
+ * reader runs in that request only reaches the page through the replay.
  */
-export declare function isInsideHandlerInvokedLoaderBody(): boolean;
+export declare function isInsideLoaderBody(loaderId: string): boolean;
 /**
  * Check if the current execution is inside a handle push callback (sync or an
  * async callback's continuation). Used by the handler-to-loader deadlock guard

package/dist/types/server/cookie-store.d.ts

@@ -63,6 +63,27 @@ export interface ReadonlyHeaders {
     [Symbol.iterator](): HeadersIterator<[string, string]>;
 }
 type HeadersIterator<T> = IterableIterator<T>;
+/** The public reads of the visitor's theme cookie that assertThemeReadAllowed guards. */
+export type ThemeReadSurface = "ctx.theme" | "getRequestContext().theme";
+/**
+ * Guard for a read of the visitor's theme: the handler and middleware
+ * `ctx.theme` (handler-context.ts, middleware.ts) and `getRequestContext().theme`
+ * (request-context.ts). The theme is the visitor's theme cookie, so it is an
+ * identity read like cookies(): it refuses in the same scopes, in the same
+ * order (refusingCacheScope, then tripShellCaptureGuard in context.ts), with
+ * the same exemption (a loader body under cache(); at capture there is none).
+ * Before #971 each read was a plain cookie read, so a ppr shell, a cache()
+ * entry or a "use cache" entry stored the first visitor's theme and served it
+ * to every later visitor.
+ *
+ * A read the guards allow is recorded on the current loader execution, as a
+ * cookies() read method records it (#972, recordLoaderIdentityRead).
+ *
+ * `ctx` is the request context at read time, as cookies() reads it. The
+ * router's own payload read (payloadInitialTheme, rsc/full-payload.ts) goes
+ * through the unguarded `_readTheme()`.
+ */
+export declare function assertThemeReadAllowed(ctx: unknown, surface: ThemeReadSurface): void;
 /**
  * Get the original request headers (read-only).
  *

package/dist/types/server/handle-store.d.ts

@@ -71,8 +71,23 @@ export interface HandleStore {
      * Push handle data for a specific handle and segment.
      * Multiple pushes to the same handle/segment accumulate in an array.
      * Each push triggers an emission on the stream.
+     *
+     * `loaderPush` overrides the push-time DSL-loader tag
+     * (isInsideLoaderScope()) that getDataForSegment(id, true) excludes. The
+     * PPR shell capture passes false for the bake-lane pushes its record keeps
+     * (shell-capture.ts deriveShellCaptureContext), with `owner` set to the
+     * pushing loader's id so the record can restore them through pushReplayed
+     * (getRecordOwners).
      */
-    push(handleName: string, segmentId: string, data: unknown): void;
+    push(handleName: string, segmentId: string, data: unknown, loaderPush?: boolean, owner?: string): void;
+    /**
+     * push() a loader-cache HIT's replayed value, recorded from `loaderId`'s
+     * body (loader-cache.ts replayLoaderHandles). If that loader then runs live
+     * in this request, its first push removes every value replayed for it and
+     * takes the first one's position (later live pushes follow it), so the
+     * handle output stays live without a duplicate.
+     */
+    pushReplayed(handleName: string, segmentId: string, data: unknown, loaderId: string): void;
     /**
      * Get all collected handle data after all handlers have settled.
      * Waits for `settled` (handler lane), then returns the data at that point.
@@ -100,8 +115,17 @@ export interface HandleStore {
     /**
      * Get handle data for a specific segment (for caching).
      * Returns data in format: { handleName: [values...] }
+     *
+     * `excludeLoaderPushes` drops values tagged as DSL-loader pushes at push
+     * time (see push); see captureHandles.
+     */
+    getDataForSegment(segmentId: string, excludeLoaderPushes?: boolean): Record<string, unknown[]>;
+    /**
+     * The push `owner` of each value in getDataForSegment(segmentId, true),
+     * index-aligned per handle (null: no owner). Handles without an owned
+     * value are omitted; undefined when none has one.
      */
-    getDataForSegment(segmentId: string): Record<string, unknown[]>;
+    getRecordOwners(segmentId: string): Record<string, (string | null)[]> | undefined;
     /**
      * Replay cached handle data back into the store (for cache hits).
      * Used to restore handle data when serving cached segments.