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

package/src/routing/segment-keys.ts

@@ -0,0 +1,186 @@
+/**
+ * Segment key computation — the stable identity of a segment in the route tree.
+ *
+ * A segment key is the string that names a segment across the RSC/SSR/client
+ * boundary: it appears in the X-Timber-State-Tree header, the X-Timber-Segments
+ * header, SegmentOutlet props, the client segment cache, and (since TIM-1279)
+ * interception scoping.
+ *
+ * This module lives in `routing/` rather than `server/` because the keys are a
+ * property of the route tree itself — both the build-time scanner tree and the
+ * runtime manifest tree produce identical keys for the same directory, which is
+ * what lets a build-time value (an interception scope) be compared against a
+ * request-time matched chain.
+ *
+ * See design/19-client-navigation.md §"X-Timber-State-Tree Header"
+ */
+
+/**
+ * Segment node shape expected by computeSegmentKeys.
+ *
+ * Structurally satisfied by both `SegmentNode` (build time) and
+ * `ManifestSegmentNode` (request time) — keys depend only on the
+ * URL path and the segment classification, never on file payloads.
+ */
+
+import type { CoercedParams } from '../shared/param-value.ts';
+
+export interface SegmentKeyInput {
+  urlPath: string;
+  segmentName?: string;
+  segmentType?: string;
+}
+
+/**
+ * Compute state-tree keys for a segment chain.
+ *
+ * Non-group segments use their urlPath as-is. Route groups accumulate
+ * ancestor group names to produce globally unique keys:
+ *   app/(a)/(shared)/dashboard → keys: ['/', '/(a)', '/(a)/(shared)', '/dashboard']
+ *
+ * **An intercepting segment switches the chain to name accumulation for good.**
+ * A children-path interception (TIM-1280) puts an intercepting node and its
+ * descendants into the *main* rendered chain, and their `urlPath`s are not
+ * URLs: interception adds no URL depth, so `app/(browse)/(...)[artistSlug]/[year]`
+ * carries `/` and `/[year]`. Keyed by urlPath the intercepting node would
+ * collide with its own owner, and `[year]` with any top-level `[year]` route —
+ * so a client that had one mounted would reuse the wrong cached layout. The
+ * switch is sticky rather than per-node because the *descendants* are where
+ * the false URLs are; the intercepting node alone is not the problem.
+ *
+ * This is the single source of truth for segment keys — used by the
+ * element builder (skip decisions, SegmentOutlet props), segment info
+ * (X-Timber-Segments header), the client cache/state tree, and
+ * interception scoping (`routing/interception.ts`).
+ */
+export function computeSegmentKeys(segments: SegmentKeyInput[]): string[] {
+  const keys: string[] = [];
+  let prevKey = '';
+  let insideIntercepting = false;
+
+  for (const segment of segments) {
+    if (segment.segmentType === 'intercepting') insideIntercepting = true;
+    if (segment.segmentType === 'group' || insideIntercepting) {
+      const base = prevKey === '/' ? '' : prevKey;
+      const key = `${base}/${segment.segmentName}`;
+      keys.push(key);
+      prevKey = key;
+    } else {
+      keys.push(segment.urlPath);
+      prevKey = segment.urlPath;
+    }
+  }
+
+  return keys;
+}
+
+/**
+ * Compute tree paths for a segment chain — the directory path of each segment
+ * with slots elided, e.g. `app/(browse)/feed` → `/(browse)/feed`.
+ *
+ * This is `computeSegmentKeys` with the group branch applied to *every*
+ * segment rather than only to groups. That one difference is the whole point:
+ * `computeSegmentKeys` resets to `urlPath` at each URL-visible segment, so
+ * `(browse)/feed` and `(landing)/feed` both key as `/feed`. Two directories
+ * that render different layouts must not share an identity.
+ *
+ * Used for interception scoping (`routing/interception.ts`), where the
+ * question is "does this route pass through *that* directory?" — not "does it
+ * render this URL?". Not interchangeable with `computeSegmentKeys`: the state
+ * tree is keyed by URL on purpose, because the client caches by URL.
+ */
+export function computeSegmentTreePaths(segments: SegmentKeyInput[]): string[] {
+  const paths: string[] = [];
+  let prev = '';
+
+  for (const segment of segments) {
+    const name = segment.segmentName ?? '';
+    if (!name) {
+      // The app root — no directory name of its own.
+      paths.push('/');
+      prev = '/';
+      continue;
+    }
+    const base = prev === '/' ? '' : prev;
+    const path = `${base}/${name}`;
+    paths.push(path);
+    prev = path;
+  }
+
+  return paths;
+}
+
+/**
+ * The directory names a tree path is built from — `/` is none, `/feed/(a)` is
+ * `['feed', '(a)']`.
+ *
+ * The inverse of the walk above, and it lives beside it so the format is
+ * stated once: `findChainByTreePath` (`server/children-interception.ts`) walks
+ * these names back down the tree to the directory the path addresses, and
+ * `treePathDepth` counts them. Both are readings of the same string, and a
+ * reader that disagreed with the producer about what separates two names
+ * resolves an interception to the wrong node or to none.
+ */
+export function treePathNames(treePath: string): string[] {
+  return treePath === '/' ? [] : treePath.slice(1).split('/');
+}
+
+/**
+ * How many directories a tree path names — `/` is 0, `/feed` is 1,
+ * `/feed/(a)` is 2.
+ *
+ * Two tree paths on a single rendered chain are strictly nested, so on that
+ * chain depth orders them totally — which is what makes it usable as "the
+ * deeper of these two directories" wherever a route passes through both
+ * (`routing/interception.ts`).
+ */
+export function treePathDepth(treePath: string): number {
+  return treePathNames(treePath).length;
+}
+
+/**
+ * Compute a unique key for a parallel route slot.
+ * Format: `{parentSegmentId}/@{slotName}`, e.g. `/@sidebar` or `/dashboard/@modal`.
+ */
+export function computeSlotKey(parentSegmentId: string, slotName: string): string {
+  const name = slotName.startsWith('@') ? slotName : `@${slotName}`;
+  const prefix = parentSegmentId === '/' ? '' : parentSegmentId;
+  return `${prefix}/${name}`;
+}
+
+/**
+ * Compute a content key for a parallel route slot.
+ *
+ * The content key encodes everything that determines the slot's rendered
+ * output for a given navigation: the slot key (which includes the owning
+ * segment's identity and the slot name), the URL parts consumed by the
+ * owning segment (which determine parent params the slot page might
+ * read), the matched page file (or a sentinel for `default.tsx`), and
+ * the slot's own extracted params.
+ *
+ * The slot key prevents cross-group collisions: two route groups at the
+ * same URL level each owning a `@sidebar` slot produce different keys
+ * even when both fall back to `default.tsx`.
+ *
+ * The key is opaque to the client — it stores whatever the server sent
+ * and advertises it back. The server computes the destination key and
+ * checks membership. This eliminates the need for the server to
+ * reconstruct the client's state from a departing URL.
+ *
+ * See design/07-routing.md §"Segment Tree Diffing on Navigation"
+ */
+export function computeSlotContentKey(
+  slotKey: string,
+  ownerParts: string[],
+  entryFile: string | null,
+  slotParams: CoercedParams
+): string {
+  const owner = ownerParts.join('/');
+  const entry = entryFile ?? '\x01';
+  const paramKeys = Object.keys(slotParams).sort();
+  const paramParts = paramKeys.map((k) => {
+    const v = slotParams[k];
+    return Array.isArray(v) ? `${k}=${v.map(String).join('\x02')}` : `${k}=${String(v)}`;
+  });
+  return [slotKey, owner, entry, ...paramParts].join('\0');
+}

package/src/routing/slot-placement.ts

@@ -0,0 +1,97 @@
+/**
+ * Parallel slot placement.
+ *
+ * One rule: a slot is resolved only for a segment on the **matched route
+ * chain**, and a slot's own subtree is never on that chain. So a slot declared
+ * anywhere inside another slot's subtree can never render, and is rejected at
+ * build time rather than left as a directory the author will keep editing.
+ *
+ * See design/07-routing.md §"Parallel Routes".
+ */
+
+import type { SegmentNode } from './types.ts';
+
+/**
+ * Reject every parallel slot that no renderer reaches.
+ *
+ * **Where slots are resolved.** Two places read `segment.slots`, and both walk
+ * the main route chain: `route-element-builder.ts` (the RSC render).
+ * It is not reachable from inside a slot. The slot's own
+ * subtree is rendered by `slot-resolver.ts`, which walks the slot's matched
+ * chain to apply that chain's layouts, error boundaries and access gates
+ * (`wrapWithIntermediateSegments`, `wrapWithLayout`) and never reads `.slots`
+ * on any of those nodes. So `app/feed/@modal/photo/@side/page.tsx` and
+ * everything below it is dead: the file is scanned, typed, code-split and
+ * shipped, and no request can render it.
+ *
+ * That is the TIM-1278 failure — a directory that silently never renders —
+ * and the reason it is a build error rather than a documented limit is that
+ * nothing at request time can report it. A slot that does not match renders
+ * `default.tsx` or `null`, which is exactly what a slot the resolver never
+ * looked at also produces, so the author sees the *designed* behaviour of a
+ * non-matching slot and has no signal to distinguish it from a slot that
+ * cannot match at all.
+ *
+ * **Interception is incidental.** TIM-1311 arrived as
+ * `feed/@modal/(.)photo/@side`, and the interception contributes nothing: the
+ * identical `feed/@modal/photo/@side` never renders either, for the same
+ * reason and with no marker anywhere. Rejecting only the intercepting spelling
+ * would have drawn a line the author cannot see from the directory names.
+ *
+ * The children-path interception shape is **not** affected and must not be:
+ * its intercepting node joins the main chain (`server/children-interception.ts`
+ * splices `[…owner ancestors, interceptingNode, …descendants]` into an ordinary
+ * `RouteMatch`), so `route-element-builder.ts` resolves slots on it and below
+ * it exactly as it does for any other chain segment. `(browse)/(...)photo/[id]/@side`
+ * renders; `feed/@modal/(.)photo/@side` does not. The discriminator is the slot
+ * boundary, which is what this walk tracks — not the marker.
+ */
+export function validateSlotPlacement(root: SegmentNode): void {
+  walkForSlotPlacement(root, '', null);
+}
+
+/**
+ * `enclosingSlotPath` is the `app/`-relative path of the nearest slot at or
+ * above `node`, or null on the main chain. It is carried rather than recomputed
+ * so the error can name the slot that swallows the offender — "this is inside
+ * @modal" is the part of the diagnosis the author cannot see from the offending
+ * path alone.
+ */
+function walkForSlotPlacement(
+  node: SegmentNode,
+  path: string,
+  enclosingSlotPath: string | null
+): void {
+  for (const [slotName, slotNode] of Object.entries(node.slots)) {
+    const slotPath = path ? `${path}/@${slotName}` : `@${slotName}`;
+    if (enclosingSlotPath !== null) {
+      throwNestedSlot(slotPath, enclosingSlotPath);
+    }
+    walkForSlotPlacement(slotNode, slotPath, slotPath);
+  }
+
+  for (const child of node.children) {
+    walkForSlotPlacement(
+      child,
+      path ? `${path}/${child.segmentName}` : child.segmentName,
+      enclosingSlotPath
+    );
+  }
+}
+
+function throwNestedSlot(slotPath: string, enclosingSlotPath: string): never {
+  throw new Error(
+    `Build error: parallel slot nested inside another parallel slot.\n` +
+      `  Directory: app/${slotPath}\n` +
+      `  Inside:    app/${enclosingSlotPath}\n` +
+      `A parallel slot is resolved only for a segment on the matched route chain, and a ` +
+      `slot's own subtree is never on that chain — the slot resolver walks the slot's ` +
+      `matched chain to apply its layouts, error boundaries and access gates, and never ` +
+      `looks at slots declared inside it. So app/${slotPath} and everything below it can ` +
+      `never render, and no request-time signal can tell you: an unreachable slot ` +
+      `produces exactly what a slot that simply did not match produces.\n` +
+      `Declare the slot on a segment of the main route chain instead, or move its pages ` +
+      `into app/${enclosingSlotPath}'s own subtree.\n` +
+      `See design/07-routing.md §"Parallel Routes".`
+  );
+}

package/src/routing/types.ts

@@ -3,6 +3,23 @@
  *
  * The route tree is built by scanning the app/ directory and recognizing
  * file conventions (page.*, layout.*, middleware.ts, access.ts, route.ts, etc.).
+ *
+ * **Single shape, two specializations** (TIM-848):
+ *
+ * `SegmentNode<TFile>` is the one canonical in-memory shape for the
+ * timber route tree. The same interface is used at build time (with
+ * `TFile = RouteFile`) and at request time (with `TFile = ManifestFile`,
+ * see `server/route-matcher.ts`). Walkers parameterized over `TFile`
+ * work on either, eliminating the previous duplication between
+ * `SegmentNode` (Map-based) and `ManifestSegmentNode` (object-based).
+ *
+ * Keyed groups (`slots`, `statusFiles`, `jsonStatusFiles`,
+ * `metadataRoutes`) are plain `Record<string, …>`
+ * objects rather than `Map`s so that the build-time tree can be
+ * serialized into the virtual route manifest with no shape transform.
+ *
+ * See design/07-routing.md §"Route Tree Shape" and design/18-build-system.md
+ * §"Route Manifest Shape".
  */
 
 /** Segment type classification */
@@ -27,7 +44,14 @@ export type InterceptionMarker = '(.)' | '(..)' | '(...)' | '(..)(..)';
 /** All recognized interception markers, ordered longest-first for parsing. */
 export const INTERCEPTION_MARKERS: InterceptionMarker[] = ['(..)(..)', '(.)', '(..)', '(...)'];
 
-/** A single file discovered in a route segment */
+/**
+ * A single file discovered in a route segment at build time.
+ *
+ * The runtime equivalent (`ManifestFile`, defined in
+ * `server/route-matcher.ts`) replaces `extension` with a lazy `load`
+ * function. Walkers that only need `filePath` are parameterized over
+ * `TFile` and accept either.
+ */
 export interface RouteFile {
   /** Absolute path to the file */
   filePath: string;
@@ -35,14 +59,27 @@ export interface RouteFile {
   extension: string;
 }
 
-/** A node in the segment tree */
-export interface SegmentNode {
+/**
+ * A node in the segment tree.
+ *
+ * Generic over `TFile` so the same interface describes both the
+ * build-time tree (`SegmentNode<RouteFile>`, the default) and the
+ * runtime manifest tree (`SegmentNode<ManifestFile>`, aliased as
+ * `ManifestSegmentNode`). All keyed groups use `Record` (not `Map`)
+ * so the build-time tree serializes to the virtual route manifest
+ * with no shape transform.
+ */
+export interface SegmentNode<TFile = RouteFile> {
   /** The raw directory name (e.g. "dashboard", "[id]", "(auth)", "@sidebar") */
   segmentName: string;
   /** Classified segment type */
   segmentType: SegmentType;
   /** The dynamic param name, if dynamic (e.g. "id" for "[id]", "slug" for "[...slug]") */
   paramName?: string;
+  /** Literal prefix before the dynamic bracket (e.g. "img-" for "img-[id].png") */
+  paramPrefix?: string;
+  /** Literal suffix after the dynamic bracket (e.g. ".png" for "img-[id].png") */
+  paramSuffix?: string;
   /** The URL path prefix at this segment level (e.g. "/dashboard") */
   urlPath: string;
   /** For intercepting segments: the marker used, e.g. "(.)". */
@@ -54,40 +91,59 @@ export interface SegmentNode {
   interceptedSegmentName?: string;
 
   // --- File conventions ---
-  page?: RouteFile;
-  layout?: RouteFile;
-  middleware?: RouteFile;
-  access?: RouteFile;
-  route?: RouteFile;
-  error?: RouteFile;
-  default?: RouteFile;
+  page?: TFile;
+  layout?: TFile;
+  middleware?: TFile;
+  access?: TFile;
+  route?: TFile;
+  /**
+   * Set when this segment's route.ts declares `export const csrf = false`.
+   * Read from source by the scanner, so the CSRF gate can consult it before
+   * any user module loads. See design/08-forms-and-actions.md
+   * §"Per-route exemption".
+   */
+  csrfExempt?: true;
+  error?: TFile;
+  default?: TFile;
   /** Status-code files: 4xx.tsx, 5xx.tsx, {status}.tsx (component format) */
-  statusFiles?: Map<string, RouteFile>;
+  statusFiles?: Record<string, TFile>;
   /** JSON status-code files: 4xx.json, 5xx.json, {status}.json */
-  jsonStatusFiles?: Map<string, RouteFile>;
+  jsonStatusFiles?: Record<string, TFile>;
   /** denied.tsx — slot-only denial rendering */
-  denied?: RouteFile;
-  /** Legacy compat: not-found.tsx (maps to 404), forbidden.tsx (403), unauthorized.tsx (401) */
-  legacyStatusFiles?: Map<string, RouteFile>;
-  /** prerender.ts — signals build-time pre-rendering for this segment's shell */
-  prerender?: RouteFile;
-  /** search-params.ts — typed search params definition for this route */
-  searchParams?: RouteFile;
+  denied?: TFile;
+
   /** Metadata route files (sitemap.ts, robots.ts, icon.tsx, etc.) keyed by base name */
-  metadataRoutes?: Map<string, RouteFile>;
+  metadataRoutes?: Record<string, TFile>;
 
   // --- Children ---
-  children: SegmentNode[];
+  children: SegmentNode<TFile>[];
   /** Parallel route slots (keyed by slot name without @) */
-  slots: Map<string, SegmentNode>;
+  slots: Record<string, SegmentNode<TFile>>;
 }
 
-/** The full route tree output from the scanner */
-export interface RouteTree {
+/**
+ * The full route tree output from the scanner (or the root of the
+ * runtime route manifest, when `TFile = ManifestFile`).
+ *
+ * Generic so the same wrapper carries app-root metadata for both
+ * shapes. The runtime manifest extends this with `viteRoot` (see
+ * `ManifestRoot` in `server/route-matcher.ts`).
+ */
+export interface RouteTree<TFile = RouteFile> {
   /** The root segment node (representing app/) */
-  root: SegmentNode;
+  root: SegmentNode<TFile>;
   /** All discovered proxy.ts files (should be at most one, in app/) */
-  proxy?: RouteFile;
+  proxy?: TFile;
+  /**
+   * Global error page: app/global-error.{tsx,ts,jsx,js}
+   *
+   * Rendered as a standalone full-page replacement (no layout wrapping)
+   * when no segment-level error file is found. SSR-only render path.
+   * Must provide its own <html> and <body>.
+   *
+   * See design/10-error-handling.md §"Tier 2 — Global Error Page"
+   */
+  globalError?: TFile;
 }
 
 /** Configuration passed to the scanner */

package/src/routing/walkers.ts

@@ -0,0 +1,98 @@
+/**
+ * Shared route-tree walkers (TIM-848).
+ *
+ * Tiny helpers that walk a `SegmentNode<TFile>` tree generically. Both the
+ * build-time tree (`SegmentNode<RouteFile>`) and the runtime manifest
+ * tree (`SegmentNode<ManifestFile>`) flow through these helpers because
+ * the walker only reads the structural fields shared by both shapes
+ * (`children`, `slots`, `page`, `route`, `urlPath`).
+ *
+ * Before this module, three near-identical `collectRoutes` functions
+ * lived in `plugins/dev-404-page.ts`, `plugins/build-report.ts`, and
+ * `routing/codegen.ts`. The codegen one is special-purpose (it
+ * accumulates `ParamEntry[]` and resolves codec chains) and stays
+ * local; the other two now share `collectLeafRoutes` from this file.
+ */
+
+import type { SegmentNode } from './types.ts';
+
+/** A leaf route discovered while walking the segment tree. */
+export interface LeafRoute<TFile> {
+  /** URL path of the leaf (root is "/"). */
+  urlPath: string;
+  /** Segment chain from root to this leaf, inclusive. */
+  segments: SegmentNode<TFile>[];
+  /** The page file at this leaf, if any. */
+  page?: TFile;
+  /** The route handler file at this leaf, if any. */
+  route?: TFile;
+}
+
+/** Options for `collectLeafRoutes`. */
+export interface CollectLeafRoutesOptions {
+  /**
+   * If true, recurse into parallel slots and emit slot leaves alongside
+   * the main route tree. Defaults to `false` because slots render
+   * alongside their parent at the same URL and are not separately
+   * URL-addressable. The build report excludes slots; route-listing
+   * UIs that want to show "all leaves with a page handler" can opt in.
+   */
+  includeSlots?: boolean;
+}
+
+/**
+ * Walk a segment tree and collect every leaf with a `page` or `route`
+ * handler. Generic over `TFile` so it works on both the build-time
+ * scanner output and the runtime manifest tree.
+ *
+ * - Pages and route handlers at the same URL produce two distinct
+ *   entries (the build report deduplicates by URL afterward).
+ * - Parallel slots are skipped unless `includeSlots: true` (slots
+ *   share their parent's URL and are not addressable on their own).
+ * - Intercepting subtrees are skipped unconditionally. They render only
+ *   on soft navigation and add no URL depth, so their computed `urlPath`s
+ *   are not addresses — listing them would advertise routes (`/[year]`)
+ *   that no request can reach. This matches every other consumer of the
+ *   tree that produces URLs: the sitemap generator, the static generator,
+ *   prerendering and the prebuilt-payload builder all skip them too.
+ * - Result is sorted by `urlPath` for deterministic output.
+ */
+export function collectLeafRoutes<TFile>(
+  root: SegmentNode<TFile>,
+  options: CollectLeafRoutesOptions = {}
+): LeafRoute<TFile>[] {
+  const { includeSlots = false } = options;
+  const result: LeafRoute<TFile>[] = [];
+  walk(root, [], result, includeSlots);
+  result.sort((a, b) => a.urlPath.localeCompare(b.urlPath));
+  return result;
+}
+
+function walk<TFile>(
+  node: SegmentNode<TFile>,
+  chain: SegmentNode<TFile>[],
+  result: LeafRoute<TFile>[],
+  includeSlots: boolean
+): void {
+  if (node.segmentType === 'intercepting') return;
+
+  const currentChain = [...chain, node];
+  const path = node.urlPath || '/';
+
+  if (node.page) {
+    result.push({ urlPath: path, segments: currentChain, page: node.page });
+  }
+  if (node.route) {
+    result.push({ urlPath: path, segments: currentChain, route: node.route });
+  }
+
+  for (const child of node.children) {
+    walk(child, currentChain, result, includeSlots);
+  }
+
+  if (includeSlots) {
+    for (const slotNode of Object.values(node.slots)) {
+      walk(slotNode, currentChain, result, includeSlots);
+    }
+  }
+}

package/src/rsc-runtime/rsc.ts

@@ -16,4 +16,13 @@ export {
   loadServerAction,
   decodeReply,
   decodeAction,
+  encryptActionBoundArgs,
+  decryptActionBoundArgs,
+  // Flight client running INSIDE the RSC environment — decodes a cached
+  // flight payload back into React elements. Client references revive as
+  // re-serializable reference proxies via plugin-rsc's server-decode
+  // manifest (registerClientReference under the hood). Used by the
+  // prebuilt component runtime (TIM-1140); same mechanism as Next.js
+  // "use cache" (use-cache-wrapper.ts).
+  createFromReadableStream,
 } from '@vitejs/plugin-rsc/rsc';

package/src/rsc-runtime/ssr.ts

@@ -11,3 +11,54 @@
  */
 
 export { createFromReadableStream } from '@vitejs/plugin-rsc/ssr';
+
+// ─── Node.js Stream Path ─────────────────────────────────────────────────────
+//
+// On Node.js, createFromNodeStream reads RSC Flight data from a Node.js
+// Readable (C++ backed) instead of a Web ReadableStream (JS reimplementation).
+// Eliminates Promise-per-chunk overhead on the SSR decode path.
+//
+// The plugin only exports createFromReadableStream (via client.edge.js).
+// createFromNodeStream lives in the vendored client.node.js. We import it
+// directly and wire up the same serverConsumerManifest the plugin uses.
+
+import { createServerConsumerManifest } from '@vitejs/plugin-rsc/ssr';
+
+type CreateFromNodeStreamFn = (
+  stream: import('node:stream').Readable,
+  manifest: ReturnType<typeof createServerConsumerManifest>,
+  options?: Record<string, unknown>
+) => React.ReactNode;
+
+let _createFromNodeStream: CreateFromNodeStreamFn | null = null;
+
+try {
+  if (typeof process !== 'undefined' && process.release?.name === 'node') {
+    const clientNode = await import('@vitejs/plugin-rsc/vendor/react-server-dom/client.node');
+    if (typeof clientNode.createFromNodeStream === 'function') {
+      _createFromNodeStream = clientNode.createFromNodeStream;
+    }
+  }
+} catch {
+  // Not available — fall back to createFromReadableStream
+}
+
+/**
+ * Decode an RSC Flight stream from a Node.js Readable.
+ *
+ * Uses the vendored createFromNodeStream which reads via Node.js native
+ * streams (C++ libuv) instead of Web ReadableStream (JS Promise per chunk).
+ *
+ * Returns null if createFromNodeStream isn't available (CF Workers, etc),
+ * signaling the caller to use createFromReadableStream instead.
+ */
+export function createFromNodeStream(
+  stream: import('node:stream').Readable,
+  options?: { nonce?: string }
+): React.ReactNode | null {
+  if (!_createFromNodeStream) return null;
+  return _createFromNodeStream(stream, createServerConsumerManifest(), options);
+}
+
+/** Whether the Node.js stream RSC decode path is available. */
+export const hasNodeStreamDecode = _createFromNodeStream !== null;

package/src/rsc-runtime/transforms.ts

@@ -0,0 +1,13 @@
+/**
+ * Transforms Adapter — Re-exports from @vitejs/plugin-rsc/transforms.
+ *
+ * This module insulates the rest of the framework from direct imports of
+ * @vitejs/plugin-rsc. The plugin is pre-1.0 and its API surface will change.
+ * By routing all transform-helper imports through this single file, a
+ * breaking upstream change only requires updating one place.
+ *
+ * Keep this as thin pass-through re-exports — the value is the single choke
+ * point, not abstraction.
+ */
+
+export { hasDirective } from '@vitejs/plugin-rsc/transforms';

package/src/rsc-runtime/vendor-types.d.ts

@@ -0,0 +1,27 @@
+declare module '@vitejs/plugin-rsc/vendor/react-server-dom/client.node' {
+  export function createFromNodeStream(
+    stream: import('node:stream').Readable,
+    manifest: unknown,
+    options?: Record<string, unknown>
+  ): React.ReactNode;
+}
+
+declare module '@vitejs/plugin-rsc/vendor/react-server-dom/server.edge' {
+  export function renderToReadableStream(
+    model: unknown,
+    manifest: unknown,
+    options?: {
+      signal?: AbortSignal;
+      onError?: (error: unknown) => string | void;
+      onPostpone?: (reason: string) => void;
+    }
+  ): ReadableStream<Uint8Array>;
+
+  // src decodes replies through plugin-rsc's wrapper; tests call the vendored
+  // server directly to exercise its array size limit (CVE-2025-55184).
+  export function decodeReply(
+    body: string | FormData,
+    manifest: unknown,
+    options?: { temporaryReferences?: unknown; arraySizeLimit?: number }
+  ): Promise<unknown[]>;
+}