@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.201

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

@@ -0,0 +1,255 @@
+/**
+ * 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 { isDenySignal, DenySignal } from './primitives.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,
+      };
+      return createElement(ContainedSlotComponent, key === null ? wrapped : { ...wrapped, key });
+    }
+    // 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;
+    return createElement(type, key === null ? nextProps : { ...(nextProps as object), key });
+  }
+
+  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,165 @@
+/**
+ * RSC ↔ SSR Bridge Contract
+ *
+ * This file defines the payload that crosses the RSC → SSR environment
+ * boundary. 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.
+ *
+ * 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.
+ *
+ * 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".
+ */
+
+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.
+ *
+ * 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;
+  /** 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 */
+  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.
+   */
+  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.
+   */
+  _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;
+  };
+
+  /**
+   * 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;
+
+  /**
+   * Mutable flag: set by the SSR entry when 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 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.
+   *
+   * See design/05-streaming.md §"deferSuspenseFor and the Hold Window"
+   * and design/spike-signal-promotion-protocol.md (Option 1).
+   */
+  _fizzAllReadyResolved?: boolean;
+}