@timber-js/app 0.2.0-alpha.97 → 0.2.0-alpha.98

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`,
+ * `legacyStatusFiles`, `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,8 +59,17 @@ 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 */
@@ -54,43 +87,50 @@ export interface SegmentNode {
   interceptedSegmentName?: string;
 
   // --- File conventions ---
-  page?: RouteFile;
-  layout?: RouteFile;
-  middleware?: RouteFile;
-  access?: RouteFile;
-  route?: RouteFile;
+  page?: TFile;
+  layout?: TFile;
+  middleware?: TFile;
+  access?: TFile;
+  route?: TFile;
   /**
    * params.ts — isomorphic convention file exporting segmentParams and/or searchParams.
    * Discovered by the scanner like middleware.ts and access.ts.
    * See design/07-routing.md §"params.ts Convention File"
    */
-  params?: RouteFile;
-  error?: RouteFile;
-  default?: RouteFile;
+  params?: TFile;
+  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;
+  denied?: TFile;
   /** Legacy compat: not-found.tsx (maps to 404), forbidden.tsx (403), unauthorized.tsx (401) */
-  legacyStatusFiles?: Map<string, RouteFile>;
+  legacyStatusFiles?: Record<string, 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}
    *
@@ -100,7 +140,7 @@ export interface RouteTree {
    *
    * See design/10-error-handling.md §"Tier 2 — Global Error Page"
    */
-  globalError?: RouteFile;
+  globalError?: TFile;
 }
 
 /** Configuration passed to the scanner */

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/server/action-handler.ts

@@ -158,6 +158,12 @@ export async function handleActionRequest(
   }
 
   // CSRF validation — reject cross-origin mutation requests.
+  //
+  // Defense-in-depth: the pipeline boundary in rsc-entry/index.ts already
+  // validates Origin on every unsafe-method request before dispatch reaches
+  // here, so this call is a no-op on the happy path. It is intentionally
+  // retained so that handleActionRequest remains safe to call from any
+  // future entry point that bypasses the wrapper. See LOCAL-773.
   const csrfResult = validateCsrf(req, config.csrf);
   if (!csrfResult.ok) {
     return new Response(null, { status: csrfResult.status });

package/src/server/deny-renderer.ts

@@ -23,7 +23,7 @@ import { logRenderError } from './logger.js';
 import { loadModule } from './safe-load.js';
 import { isDebug } from './debug.js';
 import { resolveMetadata, renderMetadataToElements } from './metadata.js';
-import { resolveManifestStatusFile } from './manifest-status-resolver.js';
+import { resolveStatusFile } from './status-code-resolver.js';
 import type { ManifestSegmentNode } from './route-matcher.js';
 import type { RouteMatch } from './pipeline.js';
 import type { NavContext } from './ssr-entry.js';
@@ -87,7 +87,7 @@ export async function renderDenyPage(
   }
 
   // Page routes → component chain first, JSON fallback only if no component found.
-  const resolution = resolveManifestStatusFile(deny.status, segments, 'component');
+  const resolution = resolveStatusFile(deny.status, segments, 'component');
 
   // No component status file — try JSON chain before bare fallback
   if (!resolution) {
@@ -99,7 +99,7 @@ export async function renderDenyPage(
   // Dev warning: JSON status file exists but is shadowed by the component chain.
   // This helps developers understand why their .json file isn't being served.
   if (isDebug()) {
-    const jsonResolution = resolveManifestStatusFile(deny.status, segments, 'json');
+    const jsonResolution = resolveStatusFile(deny.status, segments, 'json');
     if (jsonResolution) {
       console.warn(
         `[timber] ${jsonResolution.file.filePath} exists but is shadowed by ` +
@@ -190,7 +190,7 @@ export async function renderDenyPageAsRsc(
   responseHeaders: Headers,
   createDebugChannelSink: DebugChannelFactory
 ): Promise<Response> {
-  const resolution = resolveManifestStatusFile(deny.status, segments, 'component');
+  const resolution = resolveStatusFile(deny.status, segments, 'component');
 
   if (!resolution) {
     responseHeaders.set('content-type', `${RSC_CONTENT_TYPE}; charset=utf-8`);
@@ -249,7 +249,7 @@ async function renderDenyPageJson(
   segments: ManifestSegmentNode[],
   responseHeaders: Headers
 ): Promise<Response | null> {
-  const resolution = resolveManifestStatusFile(deny.status, segments, 'json');
+  const resolution = resolveStatusFile(deny.status, segments, 'json');
 
   if (!resolution) {
     return null;

package/src/server/dev-holding-server.ts

@@ -119,9 +119,11 @@ const HOLDING_PAGE_HTML = [
  *
  * Usage (inside Vite plugin):
  * ```ts
- * // In config() hook — earliest point where port is known
+ * // In config() hook — earliest point where port is known.
+ * // Use bindWithBump() to honor the default-3000 + auto-bump policy
+ * // (see ../server/port-resolution.ts and TIM-842).
  * const holding = createHoldingServer();
- * holding.listen(config.server?.port ?? 5173);
+ * await bindWithBump((p) => holding.listen(p), { startPort: 3000, autoBump: true });
  *
  * // In last plugin's configureServer() — wrap listen for seamless handoff
  * const originalListen = server.listen.bind(server);

package/src/server/fallback-error.ts

@@ -66,7 +66,7 @@ export async function renderFallbackError(
     // then fall through to global-error.tsx if those also fail.
     logRenderError({ method: req.method, path: new URL(req.url).pathname, error: layoutError });
   }
-  const match: RouteMatch = { segments: segments as never, segmentParams: {}, middlewareChain: [] };
+  const match: RouteMatch = { segments, segmentParams: {}, middlewareChain: [] };
   return renderErrorPage(
     error,
     500,