@timber-js/app 0.2.0-alpha.11 → 0.2.0-alpha.111

package/src/routing/walkers.ts

@@ -0,0 +1,90 @@
+/**
+ * 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.js';
+
+/** 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).
+ * - 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 {
+  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,6 @@ export {
   loadServerAction,
   decodeReply,
   decodeAction,
+  encryptActionBoundArgs,
+  decryptActionBoundArgs,
 } from '@vitejs/plugin-rsc/rsc';

package/src/rsc-runtime/ssr.ts

@@ -11,3 +11,53 @@
  */
 
 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
+): React.ReactNode | null {
+  if (!_createFromNodeStream) return null;
+  return _createFromNodeStream(stream, createServerConsumerManifest());
+}
+
+/** Whether the Node.js stream RSC decode path is available. */
+export const hasNodeStreamDecode = _createFromNodeStream !== null;

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

@@ -0,0 +1,7 @@
+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;
+}

package/src/{search-params/codecs.ts → schema-bridge.ts}

@@ -1,11 +1,21 @@
 /**
- * Built-in codecs and the fromSchema bridge for Standard Schema-compatible
- * validation libraries (Zod, Valibot, ArkType).
+ * Standard Schema bridge — shared helpers for bridging Standard Schema-compatible
+ * validation libraries (Zod, Valibot, ArkType) to the Codec<T> protocol.
  *
- * Design doc: design/09-typescript.md §"The SearchParamCodec Protocol"
+ * This module is the single source of truth for:
+ * - StandardSchemaV1 interface (subset of the Standard Schema spec)
+ * - validateSync() helper
+ * - fromSchema() — bridge from Standard Schema to Codec<T>
+ * - fromArraySchema() — bridge for array-valued codecs
+ *
+ * These are re-exported from @timber-js/app/search-params, @timber-js/app/segment-params,
+ * and @timber-js/app/cookies for convenience. The canonical import is
+ * @timber-js/app/codec.
+ *
+ * Design doc: design/23a-search-params-triage.md §"Unify Codec<T> type"
  */
 
-import type { SearchParamCodec } from './create.js';
+import type { Codec } from './codec.js';
 
 // ---------------------------------------------------------------------------
 // Standard Schema interface (subset)
@@ -15,13 +25,14 @@ import type { SearchParamCodec } from './create.js';
 // We depend only on `~standard.validate` to avoid coupling to any specific lib.
 // ---------------------------------------------------------------------------
 
-interface StandardSchemaV1<Output = unknown> {
+/** Minimal Standard Schema interface for auto-detection. */
+export interface StandardSchemaV1<Output = unknown> {
   '~standard': {
     validate(value: unknown): StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
   };
 }
 
-type StandardSchemaResult<Output> =
+export type StandardSchemaResult<Output> =
   | { value: Output; issues?: undefined }
   | { value?: undefined; issues: ReadonlyArray<{ message: string }> };
 
@@ -30,46 +41,72 @@ type StandardSchemaResult<Output> =
 // ---------------------------------------------------------------------------
 
 /**
- * Zod v4's ~standard.validate() signature includes Promise in the return union
- * to satisfy the Standard Schema spec, but in practice Zod always validates
- * synchronously for the schema types we use. We assert the result is sync and
- * throw if it isn't — search params parsing must be synchronous.
+ * Run a Standard Schema's `~standard.validate()` synchronously.
+ *
+ * Zod v4's signature includes `Promise` in the return union to satisfy the
+ * Standard Schema spec, but in practice Zod always validates synchronously
+ * for the schema types we use. We assert the result is sync and throw if
+ * it isn't — codec parsing must be synchronous.
  */
-function validateSync<Output>(
+export function validateSync<Output>(
   schema: StandardSchemaV1<Output>,
   value: unknown
 ): StandardSchemaResult<Output> {
   const result = schema['~standard'].validate(value);
   if (result instanceof Promise) {
     throw new Error(
-      '[timber] fromSchema: schema returned a Promise — only sync schemas are supported for search params.'
+      '[timber] fromSchema: schema returned a Promise — only sync schemas are supported.'
     );
   }
   return result;
 }
 
 // ---------------------------------------------------------------------------
-// fromSchema — bridge from Standard Schema to SearchParamCodec
+// Type guards
+// ---------------------------------------------------------------------------
+
+/** Check if a value is a Standard Schema object. */
+export function isStandardSchema(value: unknown): value is StandardSchemaV1 {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    '~standard' in value &&
+    typeof (value as StandardSchemaV1)['~standard']?.validate === 'function'
+  );
+}
+
+/** Check if a value is a Codec (has parse + serialize methods). */
+export function isCodec(value: unknown): value is Codec<unknown> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as Codec<unknown>).parse === 'function' &&
+    typeof (value as Codec<unknown>).serialize === 'function'
+  );
+}
+
+// ---------------------------------------------------------------------------
+// fromSchema — bridge from Standard Schema to Codec<T>
 // ---------------------------------------------------------------------------
 
 /**
  * Bridge a Standard Schema-compatible schema (Zod, Valibot, ArkType) to a
- * SearchParamCodec.
+ * Codec<T>.
  *
- * Parse: coerces the raw URL string through the schema. On validation failure,
+ * Parse: coerces the raw string through the schema. On validation failure,
  * parses `undefined` to get the schema's default value (the schema should have
  * a `.default()` call). If that also fails, returns `undefined`.
  *
  * Serialize: uses `String()` for primitives, `null` for null/undefined.
  *
  * ```ts
- * import { fromSchema } from '@timber-js/app/search-params'
+ * import { fromSchema } from '@timber-js/app/codec'
  * import { z } from 'zod/v4'
  *
  * const pageCodec = fromSchema(z.coerce.number().int().min(1).default(1))
  * ```
  */
-export function fromSchema<T>(schema: StandardSchemaV1<T>): SearchParamCodec<T> {
+export function fromSchema<T>(schema: StandardSchemaV1<T>): Codec<T> {
   return {
     parse(value: string | string[] | undefined): T {
       // For array inputs, take the last value (consistent with URLSearchParams.get())
@@ -101,7 +138,7 @@ export function fromSchema<T>(schema: StandardSchemaV1<T>): SearchParamCodec<T>
 }
 
 // ---------------------------------------------------------------------------
-// fromArraySchema — bridge for array-valued search params
+// fromArraySchema — bridge for array-valued codecs
 // ---------------------------------------------------------------------------
 
 /**
@@ -109,13 +146,13 @@ export function fromSchema<T>(schema: StandardSchemaV1<T>): SearchParamCodec<T>
  * and repeated query keys (`?tag=a&tag=b`).
  *
  * ```ts
- * import { fromArraySchema } from '@timber-js/app/search-params'
+ * import { fromArraySchema } from '@timber-js/app/codec'
  * import { z } from 'zod/v4'
  *
  * const tagsCodec = fromArraySchema(z.array(z.string()).default([]))
  * ```
  */
-export function fromArraySchema<T>(schema: StandardSchemaV1<T>): SearchParamCodec<T> {
+export function fromArraySchema<T>(schema: StandardSchemaV1<T>): Codec<T> {
   return {
     parse(value: string | string[] | undefined): T {
       // Coerce single string to array for array schemas