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

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

@@ -0,0 +1,273 @@
+/**
+ * Slot subtree containment — keeps a nested `deny()` inside its slot.
+ *
+ * `SafeSlotPage` (slot-resolver.ts) catches a `DenySignal` thrown by the slot
+ * page's own body and returns the slot's fallback instead, which is what makes
+ * slot denial graceful degradation at HTTP 200. That catch covers only the
+ * function it calls. Every server component in the tree the page *returns*
+ * runs later, as its own Flight task, and a deny there reaches Flight's global
+ * `onError` — where it is indistinguishable from a main-route deny. Production
+ * Flight hands `onError` nothing but the error object (no task, no key path,
+ * no component stack; it even clears its request storage around the call), so
+ * nothing at that point can recover where the throw came from, and the status
+ * commit in `rsc-payload.ts` would take it for a page-level deny and answer 4xx.
+ *
+ * The only place the origin is known is *before* the component runs. So this
+ * module rewrites the tree a slot component returns: each server-component
+ * element is replaced by an element of `ContainedSlotComponent`, which invokes
+ * the original, catches `DenySignal`, and substitutes the slot fallback in that
+ * component's place. The wrapper rewrites its own output the same way, so
+ * containment follows the tree however deep it renders — one walk per
+ * component result, once each. No Flight error row, no signal, no client
+ * boundary involvement: the deny never leaves the slot, on the payload path
+ * and the document path alike.
+ *
+ * What is NOT contained, deliberately: anything other than `DenySignal`.
+ * `RedirectSignal` must still reach the pipeline (TIM-554), and a plain error
+ * still takes the slot's catch-all boundary. A thrown thenable — `use()` on a
+ * pending promise — passes through untouched so Flight can suspend the task.
+ *
+ * Flight's `renderElement` does not only invoke plain functions: it unwraps
+ * `memo` (renders `.type`), `forwardRef` (calls `.render`), and `lazy`
+ * (runs `_init`, then renders what it resolved to). A server component behind
+ * any of those is invoked all the same, so its deny would escape too. The walk
+ * therefore resolves an element type the way Flight would — down to the
+ * function Flight would call — and wraps that.
+ *
+ * See design/02-rendering-pipeline.md §"Slot Access Failure = Graceful
+ * Degradation", TIM-1450.
+ */
+
+import { createElement, type ElementType, type ReactElement, type ReactNode } from 'react';
+
+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
+// a dependency's output is walked rather than skipped.
+const ELEMENT_TAGS = new Set<symbol>([
+  Symbol.for('react.transitional.element'),
+  Symbol.for('react.element'),
+]);
+
+type ServerComponent = (props: Record<string, unknown>) => unknown;
+
+interface Thenable<T> {
+  then(onFulfilled: (value: T) => unknown, onRejected?: (reason: unknown) => unknown): unknown;
+}
+
+/** What one walk carries: the fallback to substitute, and the one subtree it must not enter. */
+interface Containment {
+  fallback: ReactNode;
+  /**
+   * An element the caller already owns and has contained on its own — a slot
+   * layout's `children`, which the resolver built. Left untouched by identity
+   * so the level below is not wrapped (and re-walked) a second time.
+   */
+  opaque: unknown;
+}
+
+function isThenable(value: unknown): value is Thenable<unknown> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as { then?: unknown }).then === 'function'
+  );
+}
+
+function isElement(value: unknown): value is ReactElement {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    ELEMENT_TAGS.has((value as { $$typeof?: symbol }).$$typeof as symbol)
+  );
+}
+
+/** A server component Flight would invoke: a function that is neither a client reference nor a class. */
+function isServerComponent(type: unknown): type is ServerComponent {
+  return (
+    typeof type === 'function' &&
+    !isClientReference(type) &&
+    !(type as { prototype?: { isReactComponent?: unknown } }).prototype?.isReactComponent
+  );
+}
+
+// The wrapper types Flight's renderElement unwraps before invoking a function.
+const MEMO_TAG = Symbol.for('react.memo');
+const FORWARD_REF_TAG = Symbol.for('react.forward_ref');
+const LAZY_TAG = Symbol.for('react.lazy');
+
+/** The shape React gives a `lazy()` result; `_init` is what Flight calls to resolve it. */
+interface LazyType {
+  _payload: unknown;
+  _init: (payload: unknown) => ElementType;
+}
+
+/**
+ * The server component Flight would invoke for an element type, or undefined
+ * when it would not invoke one (host tag, client reference, class, provider,
+ * Suspense, and so on). Mirrors the unwrapping in Flight's `renderElement`:
+ * a `memo` renders its `.type`, a `forwardRef` calls its `.render`, a `lazy`
+ * resolves through `_init` and renders the result.
+ */
+function serverComponentOf(type: unknown): ServerComponent | undefined {
+  if (isServerComponent(type)) return type;
+  if (typeof type !== 'object' || type === null) return undefined;
+  const tag = (type as { $$typeof?: symbol }).$$typeof;
+  if (tag === MEMO_TAG) return serverComponentOf((type as { type: unknown }).type);
+  if (tag === FORWARD_REF_TAG) return serverComponentOf((type as { render: unknown }).render);
+  if (tag === LAZY_TAG) {
+    const lazy = type as LazyType;
+    // Resolve as Flight does. Until the module has loaded, `_init` throws the
+    // pending thenable; the wrapper lets any non-deny throw through, so Flight
+    // suspends the task and retries it, and the next call returns the type.
+    // That type becomes an element the wrapper walks like any other result,
+    // so a server component (memo'd or not) behind the lazy is contained too.
+    return (props) => createElement(lazy._init(lazy._payload), props);
+  }
+  return undefined;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+/** On a deny, the fallback takes the denying component's place; anything else propagates. */
+function denyToFallback(fallback: ReactNode): (error: unknown) => ReactNode {
+  return (error) => {
+    if (isDenySignal(error)) return fallback;
+    throw error;
+  };
+}
+
+/**
+ * Invokes a server component from a slot's subtree and contains its output.
+ *
+ * Declared at module scope and given the component as a prop — the same
+ * pattern as `ScopedSlotLayout` — so its identity is stable across renders.
+ * Server component: `component` and `fallback` are consumed here and never
+ * reach the Flight stream.
+ */
+function ContainedSlotComponent(props: {
+  component: ServerComponent;
+  componentProps: Record<string, unknown>;
+  fallback: ReactNode;
+}): ReactNode | Promise<ReactNode> {
+  const { component: Component, componentProps, fallback } = props;
+  const containment: Containment = { fallback, opaque: undefined };
+  let result: unknown;
+  try {
+    result = Component(componentProps);
+  } catch (error) {
+    return denyToFallback(fallback)(error);
+  }
+  // The walk is typed over `unknown` because it descends into props of any
+  // shape; what comes back for a component result is the result, rewritten.
+  if (isThenable(result)) {
+    return Promise.resolve(result).then(
+      (value) => walk(value, containment, new WeakSet()) as ReactNode,
+      denyToFallback(fallback)
+    );
+  }
+  return walk(result, containment, new WeakSet()) as ReactNode;
+}
+
+/**
+ * Rewrite `node`, returning the input itself when nothing beneath it needed
+ * wrapping — so an unchanged subtree keeps its identity and Flight's own
+ * object deduplication still applies to it.
+ */
+function walk(node: unknown, c: Containment, seen: WeakSet<object>): unknown {
+  if (typeof node !== 'object' || node === null) return node;
+  if (node === c.opaque || seen.has(node)) return node;
+  seen.add(node);
+
+  if (isThenable(node)) {
+    // A promise rendered as a child resolves to more tree; a rejection with a
+    // deny is the slot denying, same as a component would.
+    return node.then((value) => walk(value, c, seen), denyToFallback(c.fallback));
+  }
+
+  if (Array.isArray(node)) {
+    let changed = false;
+    const next = node.map((child) => {
+      const walked = walk(child, c, seen);
+      if (walked !== child) changed = true;
+      return walked;
+    });
+    return changed ? next : node;
+  }
+
+  if (isElement(node)) {
+    const { type, key, props } = node;
+    const component = type === ContainedSlotComponent ? undefined : serverComponentOf(type);
+    if (component) {
+      const wrapped = {
+        component,
+        componentProps: props as Record<string, unknown>,
+        fallback: c.fallback,
+        ...(key !== null ? { key } : undefined),
+      };
+      return createElement(ContainedSlotComponent, wrapped);
+    }
+    // Host elements, fragments, Suspense, client references, providers, and
+    // wrappers this walk already made: keep the type, contain whatever server
+    // components ride in the props (children, `fallback`, render-prop-shaped
+    // slots).
+    const nextProps = walk(props, c, seen);
+    if (nextProps === props) return node;
+    // JSX compiles `<Flex><A /><B /></Flex>` to separate createElement
+    // arguments that React does not key-validate, but the walk produces
+    // `{ children: [A, B] }` inside props — an array that React treats as
+    // dynamic and warns about missing keys. For 2+ children, spread them as
+    // separate arguments to restore the JSX calling convention. For 0–1
+    // children, pass the array as a single child argument to preserve the
+    // array shape — spreading `[x]` would collapse it to a bare element,
+    // breaking components that call `children.map()`.
+    const { children, ...rest } = nextProps as Record<string, unknown>;
+    const propsWithKey = key === null ? rest : { ...rest, key };
+    if (Array.isArray(children) && children.length > 1) {
+      return createElement(type, propsWithKey, ...(children as ReactNode[]));
+    }
+    if (children !== undefined) {
+      return createElement(type, propsWithKey, children as ReactNode);
+    }
+    return createElement(type, propsWithKey);
+  }
+
+  if (isPlainObject(node)) {
+    let changed = false;
+    const next: Record<string, unknown> = {};
+    for (const [name, value] of Object.entries(node)) {
+      const walked = walk(value, c, seen);
+      if (walked !== value) changed = true;
+      next[name] = walked;
+    }
+    return changed ? next : node;
+  }
+
+  return node;
+}
+
+/**
+ * Contain every server component in the tree a slot component returned.
+ *
+ * `fallback` is the slot's deny fallback (`default.tsx`, or nothing) and
+ * replaces exactly the component that denied — siblings that already rendered
+ * stay, the same way a deny scoped by a Suspense boundary behaves on the main
+ * route.
+ *
+ * `opaque` is an element the caller built and has already contained, which
+ * the walk must leave alone: a slot layout passes the `children` element it
+ * received, so the page beneath it is not wrapped a second time.
+ */
+export function containSlotSubtree(
+  tree: ReactNode,
+  fallback: ReactNode,
+  opaque?: ReactNode
+): ReactNode {
+  return walk(tree, { fallback, opaque }, new WeakSet()) as ReactNode;
+}

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

@@ -0,0 +1,201 @@
+/**
+ * RSC ↔ SSR Bridge Contract
+ *
+ * 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. 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
+ *    an RSC-only runtime module here couples SSR to RSC internals.
+ *
+ * 3. **Shape changes are public-surface changes.** Adding, removing, or
+ *    renaming a field is a change to the contract between two
+ *    independently-built bundles. Update every caller in the same PR —
+ *    do not rely on back-compat shims.
+ *
+ * See `design/02-rendering-pipeline.md` §"RSC → SSR → Client Hydration"
+ * and `CLAUDE.md` §"RSC and SSR Are Separate Vite Environments".
+ */
+
+/**
+ * Navigation context passed from the RSC environment to SSR.
+ *
+ * Per-request state must be explicitly passed across the RSC→SSR
+ * environment boundary since they are separate Vite module graphs.
+ */
+export interface NavContext {
+  /** The requested pathname */
+  pathname: string;
+  /**
+   * The app-visible raw query string (`''` or `?…`), with the framework's
+   * `_rsc` cache key stripped — from `appVisibleSearch()`. The single
+   * representation of the request's search state on this contract: it feeds
+   * `NavigationProvider`, the nuqs SSR adapter, and the ALS-backed SSR data,
+   * so `useSearchParams()`, nuqs hooks, and `<Link preserveSearchParams>`
+   * read the identical value they will read from the address bar after
+   * hydration. The raw string preserves repeated keys (`?tag=a&tag=b`),
+   * which a collapsed `Record<string, string>` cannot represent — do not
+   * reintroduce one beside this field (TIM-1428).
+   */
+  search: string;
+  /** The committed HTTP status code */
+  statusCode: number;
+  /** Response headers from middleware/proxy */
+  responseHeaders: Headers;
+  /** Pre-rendered metadata HTML to inject before </head> */
+  headHtml: string;
+  /** Inline JS for React's bootstrapScriptContent — kicks off module loading */
+  bootstrapScriptContent: string;
+  /**
+   * Request CSP nonce, generated when middleware read `ctx.nonce` for its
+   * `Content-Security-Policy` header (`getCspNonce()`). SSR passes it to
+   * Fizz (`nonce` option → bootstrap + runtime scripts), to the Flight
+   * decoder (preinit scripts), and to every timber-generated inline
+   * `<script>`. Undefined when no middleware asked for one, in which case
+   * the markup is byte-identical to a nonce-less render.
+   * See design/13-security.md §"Content Security Policy" (TIM-1414).
+   */
+  nonce?: string;
+  /** Tee'd RSC stream for client-side hydration (inlined into HTML) */
+  rscStream?: ReadableStream<Uint8Array>;
+  /** Max Suspense hold window (ms). SSR delays the first flush by this
+   *  duration, racing allReady so that fast-resolving boundaries render inline
+   *  without ever showing a fallback. Derived from route `deferSuspenseFor` exports.
+   *  See design/05-streaming.md §"deferSuspenseFor". */
+  deferSuspenseFor?: number;
+  /** Request abort signal. When the client disconnects (page refresh,
+   *  navigation away), this signal fires. Passed to renderToReadableStream
+   *  so React stops rendering and doesn't fire error boundaries for aborts. */
+  signal?: AbortSignal;
+  /** Request cookies as name→value pairs. Used by useCookie() during SSR
+   *  to return correct cookie values before hydration. */
+  cookies?: Map<string, string>;
+  /**
+   * Lazy thunk that produces the `<script>self.__timber_segments=…</script>`
+   * tag. Invoked by the SSR entry AFTER `renderSsrNodeStream` /
+   * `renderSsrStream` returns (shell ready ⇒ AccessGates settled), so the
+   * `getFirstDeniedSegmentIndex()` ALS value is authoritative. The result
+   * is appended to headHtml before the head injector runs.
+   *
+   * Undefined when client JS is disabled (no client to consume it).
+   * See TIM-1365, TIM-1359.
+   *
+   * 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.
+   */
+  getHeadSegmentScript?: () => string;
+
+  /**
+   * Signal that fires when an unhandled RSC error is detected.
+   * The Flight injector checks this before writing each script tag —
+   * when aborted, it stops injecting Flight data to prevent corrupted
+   * 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;
+  /**
+   * Whether Fizz's `stream.allReady` settled before the
+   * `deferSuspenseFor` hold ended.
+   *
+   * 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 (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;
+}