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

package/src/server/signal-identity.ts

@@ -0,0 +1,112 @@
+// Signal identity — the brands framework signals carry, the predicates that
+// recognise them, and SsrStreamError.
+//
+// No runtime imports (the one import is type-only), so any environment can
+// load it. The SSR entry's import graph
+// must not reach RSC request state (`request-context.ts` and friends, held
+// to that by `tests/ssr-import-boundary.test.ts`), and the signal classes
+// in primitives.ts sit beside `deny()` and `redirect()`, which read it. SSR
+// code that has to recognise a signal (the logger skips them) imports the
+// predicates from here; the classes stamp the brands exported here.
+
+import type { DenySignal, RedirectSignal } from './primitives.ts';
+
+// ─── Signal branding ────────────────────────────────────────────────────────
+//
+// Catch sites must NOT use `instanceof` on these classes. In dev, an HMR
+// program reload clears the RSC module cache; a request that is mid-render
+// still holds the catch sites from the old evaluation of primitives.ts while
+// user code loaded after the reload throws from the new one. The two
+// evaluations are distinct classes, so `instanceof` fails and a correct
+// deny() falls through every catch site as an unhandled 500 (TIM-1499).
+//
+// Each class stamps a `Symbol.for` brand on its instances in the constructor.
+// `Symbol.for` keys live in the realm-wide symbol registry, so every
+// evaluation of these modules — and every module graph in the same process —
+// agrees on the key. The `is*` predicates below check the brand and are the
+// only supported way to detect a signal. The classes themselves are NOT
+// anchored on globalThis: a re-evaluated module must hand out its own
+// (possibly updated) class, not a stale one.
+//
+// See design/18-build-system.md §"Dev Mode: Signal Identity Across Program Reloads".
+
+export const DENY_BRAND: unique symbol = Symbol.for('timber:signal.deny');
+export const REDIRECT_BRAND: unique symbol = Symbol.for('timber:signal.redirect');
+const SSR_STREAM_ERROR_BRAND: unique symbol = Symbol.for('timber:signal.ssr-stream-error');
+
+function hasBrand(value: unknown, brand: symbol): boolean {
+  return typeof value === 'object' && value !== null && brand in value;
+}
+
+/** True for any `DenySignal`, regardless of which module evaluation created it. */
+export function isDenySignal(error: unknown): error is DenySignal {
+  return hasBrand(error, DENY_BRAND);
+}
+
+/** True for any `RedirectSignal`, regardless of which module evaluation created it. */
+export function isRedirectSignal(error: unknown): error is RedirectSignal {
+  return hasBrand(error, REDIRECT_BRAND);
+}
+
+/**
+ * True for any `SsrStreamError`. This one also crosses Vite environments:
+ * it is thrown in SSR and caught in RSC, which are separate module graphs in
+ * the same process — the brand is the only identity the two share.
+ */
+export function isSsrStreamError(error: unknown): error is SsrStreamError {
+  return hasBrand(error, SSR_STREAM_ERROR_BRAND);
+}
+
+/**
+ * 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 function isControlFlowSignal(error: unknown): boolean {
+  if (isDenySignal(error) || isRedirectSignal(error)) {
+    return true;
+  }
+  if (error && typeof error === 'object') {
+    const digest = (error as { digest?: unknown }).digest;
+    if (typeof digest === 'string') {
+      try {
+        const parsed = JSON.parse(digest) as { type?: unknown } | null;
+        if (parsed && typeof parsed === 'object') {
+          return parsed.type === 'redirect' || parsed.type === 'deny';
+        }
+      } catch {
+        // Not valid digest JSON
+      }
+    }
+  }
+  return false;
+}
+
+// ─── SsrStreamError ─────────────────────────────────────────────────────────
+
+/**
+ * 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. A captured
+ * deny or redirect is rethrown to the pipeline first; with no captured
+ * signal, it renders the error page for the uncontained error.
+ *
+ * Not defined in ssr-entry.ts because ssr-entry.ts imports react-dom/server,
+ * which cannot be loaded in the RSC environment.
+ *
+ * Detect with `isSsrStreamError()` — it is thrown in the SSR environment and
+ * caught in RSC, so `instanceof` never matches. See "Signal branding" above.
+ */
+export class SsrStreamError extends Error {
+  readonly [SSR_STREAM_ERROR_BRAND] = true;
+  override readonly cause: unknown;
+
+  constructor(message: string, cause: unknown) {
+    super(message);
+    this.name = 'SsrStreamError';
+    this.cause = cause;
+  }
+}

package/src/server/slot-resolver.ts

@@ -22,10 +22,10 @@ import { SlotAccessGate } from './access-gate.tsx';
 import { wrapSegmentWithErrorBoundaries } from './error-boundary-wrapper.ts';
 import { isClientReference } from './utils/element-type.ts';
 import { containSlotSubtree } from './slot-subtree-contain.ts';
-import { loadModule } from './safe-load.ts';
+import { loadModule, type ManifestLoader } from './safe-load.ts';
 import type { InterceptionContext, RouteMatch } from './pipeline.ts';
-import { isDenySignal, isRedirectSignal } from './primitives.ts';
-import { logRenderError } from './logger.ts';
+import { isDenySignal, isRedirectSignal } from './signal-identity.ts';
+import { loadFallbackModule, reportRenderError } from './pipeline-helpers.ts';
 import type { ManifestSegmentNode } from './route-matcher.ts';
 import { setSlotParams, runWithSlotSegmentParams } from './request-context.ts';
 import { coerceSlotParams } from './param-coercion.ts';
@@ -87,6 +87,7 @@ export async function resolveSlotElement(
   slotNode: ManifestSegmentNode,
   match: RouteMatch,
   h: CreateElementFn,
+  req: Request,
   interception?: InterceptionContext,
   parentTreePath?: string
 ): Promise<React.ReactElement | null> {
@@ -167,13 +168,10 @@ export async function resolveSlotElement(
             if (isDenySignal(error)) {
               return denyFallback;
             }
-            // Log the error but don't re-throw — returning fallback ensures
+            // Report the error but don't re-throw — returning fallback ensures
             // the Flight row is resolved and the page hydrates correctly.
-            logRenderError({
-              method: '',
-              path: '',
-              error,
-            });
+            // Nothing downstream sees it, so this is its one report.
+            reportRenderError(error, req, { segments: match.segments });
             return denyFallback;
           }
         };
@@ -188,6 +186,7 @@ export async function resolveSlotElement(
         slotMatch.chain,
         element,
         h,
+        req,
         scope,
         denyFallback
       );
@@ -210,7 +209,7 @@ export async function resolveSlotElement(
       // status page must not set the document status or empty the main
       // route's segment cache.
       element = await wrapSegmentWithErrorBoundaries(slotNode, element, {
-        loadModule,
+        loadModule: (file: ManifestLoader) => loadFallbackModule(file, req, match.segments),
         createElement: h,
         errorBoundaryComponent: TimberErrorBoundary,
         isSlotBoundary: true,
@@ -289,13 +288,14 @@ async function wrapWithIntermediateSegments(
   chain: ManifestSegmentNode[],
   element: React.ReactElement,
   h: CreateElementFn,
+  req: Request,
   scope?: SlotParamScope,
   denyFallback?: React.ReactNode
 ): Promise<React.ReactElement> {
   for (let i = chain.length - 1; i > 0; i--) {
     const seg = chain[i];
     element = await wrapSegmentWithErrorBoundaries(seg, element, {
-      loadModule,
+      loadModule: (file: ManifestLoader) => loadFallbackModule(file, req),
       createElement: h,
       errorBoundaryComponent: TimberErrorBoundary,
       isSlotBoundary: true,
@@ -483,10 +483,8 @@ function findSlotMatch(slotNode: ManifestSegmentNode, match: RouteMatch): SlotMa
   const remainingSegments = parentIndex >= 0 ? segments.slice(parentIndex + 1) : [];
 
   // Extract raw URL parts from the remaining main-route segments.
-  // Use rawSegmentParams (pre-coercion) to ensure we get actual URL strings,
-  // not codec-transformed values. Fall back to segmentParams for tests/compat.
-  const rawParams = match.rawSegmentParams ?? match.segmentParams ?? {};
-  const urlParts = extractUrlParts(remainingSegments, rawParams);
+  // Raw (pre-coercion) params: actual URL strings, not codec-transformed values.
+  const urlParts = extractUrlParts(remainingSegments, match.rawSegmentParams);
 
   // Match URL parts against the slot's segment tree using the shared walker.
   // Handles zero parts (slot's own page), catch-all, optional-catch-all,
@@ -674,7 +672,8 @@ interface ResolveSlotPropsArgs {
   h: CreateElementFn;
   interception?: InterceptionContext;
   parentTreePath: string;
-  destinationUrl: string;
+  /** The request being rendered. Its URL is the slot-matching destination. */
+  req: Request;
   clientStateTree: ClientStateTree | null;
   slotSkipInfo: SlotSkipEntry[];
 }
@@ -699,7 +698,7 @@ export async function resolveSlotProps({
   h,
   interception,
   parentTreePath,
-  destinationUrl,
+  req,
   clientStateTree,
   slotSkipInfo,
 }: ResolveSlotPropsArgs): Promise<Record<string, unknown>> {
@@ -707,7 +706,7 @@ export async function resolveSlotProps({
   const slotEntries = Object.entries(segment.slots ?? {});
   if (slotEntries.length === 0) return slotProps;
 
-  const destinationParts = slotUrlParts(segment, match, destinationUrl);
+  const destinationParts = slotUrlParts(segment, match, req.url);
   const clientSlotKeys = clientStateTree?.slots ?? null;
 
   // Owner URL parts — the URL values consumed through this segment.
@@ -770,6 +769,7 @@ export async function resolveSlotProps({
         slotManifest,
         match,
         h,
+        req,
         interception,
         parentTreePath
       );

package/src/server/slot-subtree-contain.ts

@@ -40,7 +40,8 @@
 
 import { createElement, type ElementType, type ReactElement, type ReactNode } from 'react';
 
-import { isDenySignal, DenySignal } from './primitives.ts';
+import { DenySignal } from './primitives.ts';
+import { isDenySignal } from './signal-identity.ts';
 import { isClientReference } from './utils/element-type.ts';
 
 // React 19 elements; the legacy tag is accepted so a stray pre-19 element in

package/src/server/ssr-bridge-types.ts

@@ -1,20 +1,41 @@
 /**
  * RSC ↔ SSR Bridge Contract
  *
- * This file defines the payload that crosses the RSC → SSR environment
- * boundary. The RSC environment calls `handleSsr(rscStream, navContext)`
+ * This file defines what crosses the RSC ↔ SSR environment boundary: the
+ * `NavContext` input and the `SsrRenderResult` output. The RSC
+ * environment calls `handleSsr(rscStream, navContext)`
  * in the SSR environment via `import.meta.viteRsc.import(...)` (see
  * `rsc-entry/ssr-bridge.ts`). RSC and SSR are separate Vite module graphs
  * with separate module instances, so every per-request field that SSR
  * needs must be declared here and passed explicitly.
  *
+ * The ALS stores are the exception to "separate instances": `als-registry.ts`
+ * anchors them on `globalThis`, and SSR runs inside the RSC request's
+ * async context, so an SSR module that imported `request-context.ts` would
+ * read live RSC state. The framework's SSR code must not — that is the
+ * coupling this contract removes — and `tests/ssr-import-boundary.test.ts`
+ * holds the SSR entry's import graph to it (its allowlist names the one
+ * registry reader permitted). User `'use client'` code rendered in SSR can
+ * still reach request state through public APIs (`redirect()`, a
+ * `defineCookie()` cookie's `get()`); that test does not cover them.
+ *
  * Rules for changes to this file:
  *
  * 1. **Structurally serializable shape.** Fields must be values that can
  *    cross the environment boundary as plain data or as platform-neutral
  *    primitives (`Headers`, `ReadableStream`, `AbortSignal`, `Map`). Do
  *    not add closures, class instances tied to RSC-only modules, or
- *    anything whose identity must be preserved across the bridge.
+ *    anything whose identity must be preserved across the bridge. The one
+ *    sanctioned exception is `NavContext.getHeadSegmentScript`.
+ *
+ * 1a. **Directional.** `NavContext` is input. Anything SSR produces for
+ *    RSC is returned in `SsrRenderResult`, not written back onto the
+ *    context. SSR never writes to a `NavContext` or through one. That
+ *    includes `responseHeaders`: it is the pipeline's bag, passed by
+ *    reference, and SSR copies it before adding response-local headers.
+ *    RSC-side code may still write the bag after `handleSsr()` returns
+ *    (a promoted redirect's `Location`, for one); that is the pipeline
+ *    using its own bag, not a return channel.
  *
  * 2. **No runtime imports of RSC-only modules.** This file is read by
  *    both environments at type-check time. Keep it type-only. Importing
@@ -29,9 +50,6 @@
  * and `CLAUDE.md` §"RSC and SSR Are Separate Vite Environments".
  */
 
-import type { CoercedParams } from '../shared/param-value.ts';
-import type { SlotParamsRecord } from '../shared/slot-params.ts';
-
 /**
  * Navigation context passed from the RSC environment to SSR.
  *
@@ -53,14 +71,6 @@ export interface NavContext {
    * reintroduce one beside this field (TIM-1428).
    */
   search: string;
-  /** Extracted route segment params. Post-coercion, values may be non-string (TIM-1347). */
-  segmentParams: CoercedParams;
-  /**
-   * Per-slot segment params, keyed by slot tree path. Absent when the request
-   * rendered no slot with params of its own. Feeds `useSegmentParams(path)`
-   * during SSR and, via `__timber_slot_params`, after hydration (TIM-1285).
-   */
-  slotParams?: SlotParamsRecord;
   /** The committed HTTP status code */
   statusCode: number;
   /** Response headers from middleware/proxy */
@@ -102,39 +112,16 @@ export interface NavContext {
    *
    * Undefined when client JS is disabled (no client to consume it).
    * See TIM-1365, TIM-1359.
-   */
-  getHeadSegmentScript?: () => string;
-
-  /**
-   * Mutable flag: set by TimberErrorBoundary during SSR when it catches
-   * a DenySignal (via digest). This tells the RSC entry that the denial
-   * was contained by a slot error boundary and should NOT be promoted
-   * to a page-level deny. See LOCAL-298.
-   */
-  _denyHandledByBoundary?: boolean;
-
-  /**
-   * Mutable: SSR timing data populated by handleSsr().
-   * Read by the RSC entry to record sub-phase Server-Timing entries
-   * when `serverTiming: 'detailed'` is configured.
    *
-   * This bridges the RSC→SSR environment boundary: the SSR entry populates
-   * these fields, the RSC entry reads them after callSsr() returns.
+   * This is the bridge's one sanctioned exception to rule 1 (no closures).
+   * SSR must not import the RSC request state that holds the
+   * denied-segment index (tests/ssr-import-boundary.test.ts), and evaluating
+   * it eagerly, before AccessGates settle, would serialize a
+   * non-authoritative index. See
+   * design/49-explicit-subsystem-boundaries.md §"Decision: the head-segment
+   * callback stays". Do not add a second one.
    */
-  _ssrTimings?: {
-    /** Time to decode RSC stream (createFromReadableStream/createFromNodeStream) */
-    decodeMs: number;
-    /** Time for Fizz to render the shell (onShellReady) */
-    shellMs: number;
-    /** Time for pipe() to flush shell bytes to the output stream */
-    pipeMs: number;
-    /** Time to set up Node.js Transform pipeline / Web Stream transforms */
-    pipelineMs: number;
-    /** Total SSR time (decode → response ready) */
-    totalMs: number;
-    /** Whether the Node.js native stream path was used */
-    nodeStreams: boolean;
-  };
+  getHeadSegmentScript?: () => string;
 
   /**
    * Signal that fires when an unhandled RSC error is detected.
@@ -143,23 +130,72 @@ export interface NavContext {
    * chunks from crashing the client's Flight decoder.
    */
   _errorSignal?: AbortSignal;
+}
+
+/**
+ * SSR sub-phase timings, recorded by `handleSsr()` and turned into
+ * `Server-Timing` entries by the RSC renderer when
+ * `serverTiming: 'detailed'` is configured.
+ */
+export interface SsrTimings {
+  /** Time to decode the RSC stream (createFromReadableStream/createFromNodeStream) */
+  decodeMs: number;
+  /** Time for Fizz to render the shell (onShellReady, plus any hold window) */
+  shellMs: number;
+  /** Time to set up the Node.js Transform pipeline / Web Stream transforms */
+  pipelineMs: number;
+  /** Total SSR time (decode → response ready) */
+  totalMs: number;
+  /** Whether the Node.js native stream path was used */
+  nodeStreams: boolean;
+}
 
+/**
+ * What `handleSsr()` returns to the RSC environment.
+ *
+ * Directional and terminal: every field is produced by the SSR entry and
+ * settled by the time `handleSsr()` resolves. Do not add request inputs
+ * (those belong on `NavContext`) or methods here.
+ *
+ * `response.status` is not an SSR decision. It echoes
+ * `NavContext.statusCode`, and response status has exactly two owners,
+ * both in the RSC environment:
+ *
+ * 1. the `statusCode` on the `NavContext` itself, seeded by whichever
+ *    RSC-side renderer builds it before `callSsr()`: 200 from
+ *    `rsc-entry/ssr-renderer.ts`, the deny status from `renderDenyPage()`,
+ *    the error status from `rsc-entry/error-renderer.ts`; and
+ * 2. the post-`callSsr()` `getDenyStatus()` override in
+ *    `rsc-entry/ssr-renderer.ts`, which rebuilds the `Response` with the
+ *    status an in-tree `AccessGate`/`PageDenyBoundary` denial recorded
+ *    in the RSC-side ALS (TIM-666).
+ *
+ * The override reads RSC state after SSR returns; it is not a write back
+ * across the bridge. No SSR-side code (error boundaries included) sets a
+ * status: Fizz never renders a class boundary's fallback on the document
+ * path (design/spike-TIM-1441-eliminate-second-pass.md F1/F2), so there
+ * is nothing in-tree to report. See design/49 §"A2".
+ */
+export interface SsrRenderResult {
+  /** The HTML document response, streaming the post-shell remainder. */
+  response: Response;
+  timings: SsrTimings;
   /**
-   * Mutable flag: set by the SSR entry when Fizz's `stream.allReady`
-   * settled before the `deferSuspenseFor` hold ended.
+   * Whether Fizz's `stream.allReady` settled before the
+   * `deferSuspenseFor` hold ended.
    *
-   * When true, the RSC entry can skip its signal-promotion
-   * microtask-retry wait: Fizz allReady implies Flight closed its
-   * stream, which implies `onError` already fired for every rejected
-   * Flight task. Any DenySignal/RedirectSignal/RenderError in-tree has
-   * already been captured in `RenderSignals`.
+   * When true, the RSC renderer skips its signal-promotion microtask
+   * retry: Fizz allReady implies Flight closed its stream, which implies
+   * `onError` already fired for every rejected Flight task, so every
+   * DenySignal/RedirectSignal in the tree is already captured.
    *
-   * When false or undefined (hold timed out, no hold window, shell-only
-   * return, Node error path), no such guarantee — the RSC entry falls
-   * back to the bounded microtask retry loop.
+   * When false (hold timed out, no hold window, shell-only return), there
+   * is no such guarantee and the renderer falls back to the bounded retry.
+   * Settled before `handleSsr()` resolves: `onFizzAllReadyResolved` fires
+   * synchronously just before the render-stream promise resolves.
    *
    * See design/05-streaming.md §"deferSuspenseFor and the Hold Window"
    * and design/spike-signal-promotion-protocol.md (Option 1).
    */
-  _fizzAllReadyResolved?: boolean;
+  fizzAllReadyResolved: boolean;
 }