@timber-js/app 0.2.0-alpha.18 → 0.2.0-alpha.180

package/src/server/tree-builder.ts

@@ -10,7 +10,8 @@
  * See design/02-rendering-pipeline.md §"Element Tree Construction"
  */
 
-import type { SegmentNode, RouteFile } from '#/routing/types.js';
+import type { ReactNode } from 'react';
+import type { RouteFile, SegmentNode } from '../routing/types.js';
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -25,31 +26,92 @@ export interface LoadedModule {
 /** Function that loads a route file's module. */
 export type ModuleLoader = (file: RouteFile) => LoadedModule | Promise<LoadedModule>;
 
-/** A React element — kept opaque to avoid a React dependency in this module. */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type ReactElement = any;
+/**
+ * A React component reference loaded from a route module's default export.
+ *
+ * Loaded modules' `default` is typed as `unknown` (modules are dynamic), so
+ * call sites narrow it through `isValidElementType` (below) before treating
+ * it as a component. The signature is a callable returning `ReactNode` —
+ * TypeScript's view of every valid React component shape, including exotic
+ * components (`memo`, `forwardRef`, `lazy`) which the type system treats as
+ * callable even though their runtime values are objects with `$$typeof`
+ * markers rather than functions.
+ */
+export type LoadedComponent = (...args: unknown[]) => ReactNode;
+
+// Marker symbols React stamps onto exotic component types. Mirrors the
+// internal `isValidElementType` check in `react.development.js` — React
+// doesn't export it, and we don't want to add `react-is` just for this one
+// validation. Inlined the same way `isClientReference` in
+// `route-element-builder.ts` inlines the client-reference marker.
+const REACT_FORWARD_REF_TYPE = Symbol.for('react.forward_ref');
+const REACT_MEMO_TYPE = Symbol.for('react.memo');
+const REACT_LAZY_TYPE = Symbol.for('react.lazy');
+const REACT_PROVIDER_TYPE = Symbol.for('react.provider');
+const REACT_CONTEXT_TYPE = Symbol.for('react.context');
+const REACT_SUSPENSE_TYPE = Symbol.for('react.suspense');
+const REACT_SUSPENSE_LIST_TYPE = Symbol.for('react.suspense_list');
+const REACT_CLIENT_REFERENCE_TYPE = Symbol.for('react.client.reference');
+
+const REACT_COMPONENT_TYPE_MARKERS: ReadonlySet<symbol> = new Set([
+  REACT_FORWARD_REF_TYPE,
+  REACT_MEMO_TYPE,
+  REACT_LAZY_TYPE,
+  REACT_PROVIDER_TYPE,
+  REACT_CONTEXT_TYPE,
+  REACT_SUSPENSE_TYPE,
+  REACT_SUSPENSE_LIST_TYPE,
+  REACT_CLIENT_REFERENCE_TYPE,
+]);
+
+/**
+ * Validate that a loaded module's `default` export is something React
+ * accepts as the first argument to `createElement` — i.e. a valid component
+ * type. React doesn't export `isValidElementType` (only `isValidElement`,
+ * which checks for *elements*, not *component types*), so this mirrors
+ * React's internal check:
+ *
+ *   - functions  → function or class components
+ *   - objects with a `$$typeof` matching one of React's known component
+ *     markers → exotic components (`memo`, `forwardRef`, `lazy`, context,
+ *     suspense, client references via `@vitejs/plugin-rsc`)
+ *
+ * Strings (HTML tag names) are valid for `createElement` but never appear
+ * as a route module's default export, so they're not recognized here.
+ *
+ * Anything else (numbers, plain config objects, JSON, etc.) is rejected so
+ * the boundary wrapper is skipped rather than crashing inside React.
+ */
+function isValidElementType(value: unknown): value is LoadedComponent {
+  if (typeof value === 'function') return true;
+  if (typeof value !== 'object' || value === null) return false;
+  const marker = (value as { $$typeof?: unknown }).$$typeof;
+  return typeof marker === 'symbol' && REACT_COMPONENT_TYPE_MARKERS.has(marker);
+}
 
-/** Function that creates a React element. Matches React.createElement signature. */
+/**
+ * Function that creates a React element. Matches React.createElement signature.
+ *
+ * `props` is typed as `object | null` rather than `Record<string, unknown>` so
+ * that interface types with known keys (e.g. `AccessGateProps`,
+ * `ErrorBoundaryProps`) flow through without an explicit index-signature cast.
+ */
 export type CreateElement = (
   type: unknown,
-  props: Record<string, unknown> | null,
+  props: object | null,
   ...children: unknown[]
-) => ReactElement;
+) => ReactNode;
 
 /**
  * Resolved slot content for a layout.
  * Key is slot name (without @), value is the element tree for that slot.
  */
-export type SlotElements = Map<string, ReactElement>;
+export type SlotElements = Map<string, ReactNode>;
 
 /** Configuration for the tree builder. */
 export interface TreeBuilderConfig {
   /** The matched segment chain from root to leaf. */
   segments: SegmentNode[];
-  /** Route params extracted by the matcher (catch-all segments produce string[]). */
-  params: Record<string, string | string[]>;
-  /** Parsed search params (typed or URLSearchParams). */
-  searchParams: unknown;
   /** Loads a route file's module. */
   loadModule: ModuleLoader;
   /** React.createElement or equivalent. */
@@ -77,9 +139,7 @@ export interface TreeBuilderConfig {
  * (backward compat for tree-builder.ts which doesn't run a pre-render pass).
  */
 export interface AccessGateProps {
-  accessFn: (ctx: { params: Record<string, string | string[]>; searchParams: unknown }) => unknown;
-  params: Record<string, string | string[]>;
-  searchParams: unknown;
+  accessFn: () => unknown;
   /** Segment name for dev logging (e.g. "authenticated", "dashboard"). */
   segmentName?: string;
   /**
@@ -92,30 +152,64 @@ export interface AccessGateProps {
     | 'pass'
     | import('./primitives.js').DenySignal
     | import('./primitives.js').RedirectSignal;
-  children: ReactElement;
+  /**
+   * Deny page fallback chain. When provided and a DenySignal is caught,
+   * AccessGate renders the matching deny page in-tree instead of throwing.
+   * This prevents the error from reaching React Flight, eliminating the
+   * second render pass. See TIM-666.
+   */
+  denyPages?: import('./deny-boundary.js').DenyPageEntry[];
+  children: ReactNode;
 }
 
 /**
  * Framework-injected slot access gate component.
  * On denial, renders denied.tsx → default.tsx → null instead of failing the page.
+ *
+ * DeniedComponent is passed instead of a pre-built element so that
+ * SlotAccessGate can forward DenySignal.data as dangerouslyPassData
+ * and slotName as the slot prop after catching the signal.
  */
 export interface SlotAccessGateProps {
-  accessFn: (ctx: { params: Record<string, string | string[]>; searchParams: unknown }) => unknown;
-  params: Record<string, string | string[]>;
-  searchParams: unknown;
-  deniedFallback: ReactElement | null;
-  defaultFallback: ReactElement | null;
-  children: ReactElement;
+  accessFn: () => unknown;
+  /** The denied.tsx component (not a pre-built element). null if no denied.tsx exists. */
+  DeniedComponent: LoadedComponent | null;
+  /** Slot directory name without @ prefix (e.g. "admin", "sidebar"). */
+  slotName: string;
+  /** createElement function for building elements dynamically. */
+  createElement: CreateElement;
+  defaultFallback: ReactNode;
+  children: ReactNode;
+  /**
+   * Pre-computed verdict from eager access evaluation. When provided,
+   * SlotAccessGate replays it synchronously instead of re-calling accessFn.
+   * 'pass' → render children. DenySignal → graceful degradation.
+   * undefined → call accessFn during render (backward compat, error re-run).
+   */
+  verdict?:
+    | 'pass'
+    | import('./primitives.js').DenySignal
+    | import('./primitives.js').RedirectSignal;
 }
 
 /**
  * Framework-injected error boundary wrapper.
  * Wraps content with status-code error boundary handling.
+ *
+ * Field types must agree with `TimberErrorBoundaryProps` in
+ * `client/error-boundary.tsx`. The two are kept structurally compatible by
+ * convention rather than by direct type import — tree-builder.ts is the
+ * server-side construction site and may not import types from a 'use client'
+ * module to keep the server barrel free of client coupling.
  */
 export interface ErrorBoundaryProps {
-  fallbackComponent: ReactElement | null;
+  /** The component to render when an error is caught (TSX status files). */
+  fallbackComponent?: LoadedComponent;
+  /** Pre-rendered fallback element (MDX status files — see TIM-503). */
+  fallbackElement?: ReactNode;
+  /** Status code filter: 400 = any 4xx, 500 = any 5xx, specific number = exact match. */
   status?: number;
-  children: ReactElement;
+  children: ReactNode;
 }
 
 // ─── Tree Builder ────────────────────────────────────────────────────────────
@@ -124,8 +218,11 @@ export interface ErrorBoundaryProps {
  * Result of building the element tree.
  */
 export interface TreeBuildResult {
-  /** The root React element tree ready for renderToReadableStream. */
-  tree: ReactElement;
+  /**
+   * The root React element tree ready for renderToReadableStream.
+   * `null` for API routes (route.ts), which don't render a React tree.
+   */
+  tree: ReactNode;
   /** Whether the leaf segment is a route.ts (API endpoint) rather than a page. */
   isApiRoute: boolean;
 }
@@ -143,8 +240,7 @@ export interface TreeBuildResult {
  * Parallel slots are resolved at each layout level and composed as named props.
  */
 export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeBuildResult> {
-  const { segments, params, searchParams, loadModule, createElement, errorBoundaryComponent } =
-    config;
+  const { segments, loadModule, createElement, errorBoundaryComponent } = config;
 
   if (segments.length === 0) {
     throw new Error('[timber] buildElementTree: empty segment chain');
@@ -159,7 +255,7 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
 
   // Start with the page component
   const pageModule = leaf.page ? await loadModule(leaf.page) : null;
-  const PageComponent = pageModule?.default as ((...args: unknown[]) => ReactElement) | undefined;
+  const PageComponent = pageModule?.default as LoadedComponent | undefined;
 
   if (!PageComponent) {
     throw new Error(
@@ -168,8 +264,8 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
     );
   }
 
-  // Build the page element with params and searchParams props
-  let element: ReactElement = createElement(PageComponent, { params, searchParams });
+  // Build the page element — params are accessed via getSegmentParams() from ALS
+  let element: ReactNode = createElement(PageComponent, {});
 
   // Build tree bottom-up: wrap page, then walk segments from leaf to root
   for (let i = segments.length - 1; i >= 0; i--) {
@@ -190,8 +286,6 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
       const accessFn = accessModule.default as AccessGateProps['accessFn'];
       element = createElement('timber:access-gate', {
         accessFn,
-        params,
-        searchParams,
         segmentName: segment.segmentName,
         children: element,
       } satisfies AccessGateProps);
@@ -200,19 +294,17 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
     // Wrap in layout (if exists and not the leaf's page-level wrapping)
     if (segment.layout) {
       const layoutModule = await loadModule(segment.layout);
-      const LayoutComponent = layoutModule.default as
-        | ((...args: unknown[]) => ReactElement)
-        | undefined;
+      const LayoutComponent = layoutModule.default as LoadedComponent | undefined;
 
       if (LayoutComponent) {
         // Resolve parallel slots for this layout
-        const slotProps: Record<string, ReactElement> = {};
-        if (segment.slots.size > 0) {
-          for (const [slotName, slotNode] of segment.slots) {
+        const slotProps: Record<string, ReactNode> = {};
+        const slotNames = Object.keys(segment.slots);
+        if (slotNames.length > 0) {
+          for (const slotName of slotNames) {
+            const slotNode = segment.slots[slotName]!;
             slotProps[slotName] = await buildSlotElement(
               slotNode,
-              params,
-              searchParams,
               loadModule,
               createElement,
               errorBoundaryComponent
@@ -220,12 +312,12 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
           }
         }
 
+        /* eslint-disable react/no-children-prop -- createElement API */
         element = createElement(LayoutComponent, {
           ...slotProps,
-          params,
-          searchParams,
           children: element,
         });
+        /* eslint-enable react/no-children-prop */
       }
     }
   }
@@ -243,28 +335,24 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
  */
 async function buildSlotElement(
   slotNode: SegmentNode,
-  params: Record<string, string | string[]>,
-  searchParams: unknown,
   loadModule: ModuleLoader,
   createElement: CreateElement,
   errorBoundaryComponent: unknown
-): Promise<ReactElement> {
+): Promise<ReactNode> {
   // Load slot page
   const pageModule = slotNode.page ? await loadModule(slotNode.page) : null;
-  const PageComponent = pageModule?.default as ((...args: unknown[]) => ReactElement) | undefined;
+  const PageComponent = pageModule?.default as LoadedComponent | undefined;
 
   // Load default.tsx fallback
   const defaultModule = slotNode.default ? await loadModule(slotNode.default) : null;
-  const DefaultComponent = defaultModule?.default as
-    | ((...args: unknown[]) => ReactElement)
-    | undefined;
+  const DefaultComponent = defaultModule?.default as LoadedComponent | undefined;
 
   // If no page, render default.tsx or null
   if (!PageComponent) {
-    return DefaultComponent ? createElement(DefaultComponent, { params, searchParams }) : null;
+    return DefaultComponent ? createElement(DefaultComponent, {}) : null;
   }
 
-  let element: ReactElement = createElement(PageComponent, { params, searchParams });
+  let element: ReactNode = createElement(PageComponent, {});
 
   // Wrap in error boundaries
   element = await wrapWithErrorBoundaries(
@@ -280,27 +368,18 @@ async function buildSlotElement(
     const accessModule = await loadModule(slotNode.access);
     const accessFn = accessModule.default as SlotAccessGateProps['accessFn'];
 
-    // Load denied.tsx
+    // Load denied.tsx — pass component (not pre-built element) so
+    // SlotAccessGate can forward DenySignal.data dynamically. See TIM-488.
     const deniedModule = slotNode.denied ? await loadModule(slotNode.denied) : null;
-    const DeniedComponent = deniedModule?.default as
-      | ((...args: unknown[]) => ReactElement)
-      | undefined;
-
-    const deniedFallback = DeniedComponent
-      ? createElement(DeniedComponent, {
-          slot: slotNode.segmentName.replace(/^@/, ''),
-          dangerouslyPassData: undefined,
-        })
-      : null;
-    const defaultFallback = DefaultComponent
-      ? createElement(DefaultComponent, { params, searchParams })
-      : null;
+    const DeniedComponent = (deniedModule?.default as LoadedComponent | undefined) ?? null;
+
+    const defaultFallback = DefaultComponent ? createElement(DefaultComponent, {}) : null;
 
     element = createElement('timber:slot-access-gate', {
       accessFn,
-      params,
-      searchParams,
-      deniedFallback,
+      DeniedComponent,
+      slotName: slotNode.segmentName.replace(/^@/, ''),
+      createElement,
       defaultFallback,
       children: element,
     } satisfies SlotAccessGateProps);
@@ -311,6 +390,19 @@ async function buildSlotElement(
 
 // ─── Error Boundary Wrapping ─────────────────────────────────────────────────
 
+/** MDX/markdown extensions — these are server components that cannot be passed as function props. */
+const MDX_EXTENSIONS = new Set(['mdx', 'md']);
+
+/**
+ * Check if a route file is an MDX/markdown file based on its extension.
+ * MDX components are server components by default and cannot cross the
+ * RSC→client boundary as function props. They must be pre-rendered as
+ * elements and passed as fallbackElement instead of fallbackComponent.
+ */
+function isMdxFile(file: RouteFile): boolean {
+  return MDX_EXTENSIONS.has(file.extension);
+}
+
 /**
  * Wrap an element with error boundaries from a segment's status-code files.
  *
@@ -320,61 +412,93 @@ async function buildSlotElement(
  *   3. error.tsx (general error boundary)
  *
  * This creates the fallback chain described in design/10-error-handling.md.
+ *
+ * MDX status files are server components and cannot be passed as function
+ * props to TimberErrorBoundary (a 'use client' component). Instead, they
+ * are pre-rendered as elements and passed as fallbackElement. The error
+ * boundary renders the element directly when an error is caught.
+ * See TIM-503.
  */
 async function wrapWithErrorBoundaries(
   segment: SegmentNode,
-  element: ReactElement,
+  element: ReactNode,
   loadModule: ModuleLoader,
   createElement: CreateElement,
   errorBoundaryComponent: unknown
-): Promise<ReactElement> {
+): Promise<ReactNode> {
   // Wrapping is applied inside-out. The last wrap call produces the outermost boundary.
   // Order: specific status → category → error.tsx (outermost)
 
   if (segment.statusFiles) {
     // Wrap with specific status files (innermost — highest priority at runtime)
-    for (const [key, file] of segment.statusFiles) {
+    for (const [key, file] of Object.entries(segment.statusFiles)) {
       if (key !== '4xx' && key !== '5xx') {
         const status = parseInt(key, 10);
         if (!isNaN(status)) {
           const mod = await loadModule(file);
-          const Component = mod.default;
+          // mod.default is `unknown` — narrow to a component reference.
+          // `isValidElementType` accepts memo/forwardRef objects in addition to
+          // bare functions; non-component values fall through.
+          const Component = isValidElementType(mod.default) ? mod.default : null;
           if (Component) {
-            element = createElement(errorBoundaryComponent, {
-              fallbackComponent: Component,
-              status,
-              children: element,
-            } satisfies ErrorBoundaryProps);
+            const boundaryProps: ErrorBoundaryProps = isMdxFile(file)
+              ? {
+                  fallbackElement: createElement(Component, { status }),
+                  status,
+                  children: element,
+                }
+              : {
+                  fallbackComponent: Component,
+                  status,
+                  children: element,
+                };
+            element = createElement(errorBoundaryComponent, boundaryProps);
           }
         }
       }
     }
 
     // Wrap with category catch-alls (4xx.tsx, 5xx.tsx)
-    for (const [key, file] of segment.statusFiles) {
+    for (const [key, file] of Object.entries(segment.statusFiles)) {
       if (key === '4xx' || key === '5xx') {
         const mod = await loadModule(file);
-        const Component = mod.default;
+        const Component = isValidElementType(mod.default) ? mod.default : null;
         if (Component) {
-          element = createElement(errorBoundaryComponent, {
-            fallbackComponent: Component,
-            status: key === '4xx' ? 400 : 500, // category marker
-            children: element,
-          } satisfies ErrorBoundaryProps);
+          const categoryStatus = key === '4xx' ? 400 : 500;
+          const boundaryProps: ErrorBoundaryProps = isMdxFile(file)
+            ? {
+                fallbackElement: createElement(Component, {}),
+                status: categoryStatus,
+                children: element,
+              }
+            : {
+                fallbackComponent: Component,
+                status: categoryStatus,
+                children: element,
+              };
+          element = createElement(errorBoundaryComponent, boundaryProps);
         }
       }
     }
   }
 
   // Wrap with error.tsx (outermost — catches anything not matched by status files)
+  // Note: error.tsx/error.mdx receives { error, digest, reset } props.
+  // MDX error files are pre-rendered without those props (they're static content).
   if (segment.error) {
     const errorModule = await loadModule(segment.error);
-    const ErrorComponent = errorModule.default;
+    const ErrorComponent = isValidElementType(errorModule.default) ? errorModule.default : null;
     if (ErrorComponent) {
-      element = createElement(errorBoundaryComponent, {
-        fallbackComponent: ErrorComponent,
-        children: element,
-      } satisfies ErrorBoundaryProps);
+      const boundaryProps: ErrorBoundaryProps = isMdxFile(segment.error)
+        ? {
+            fallbackElement: createElement(ErrorComponent, {}),
+            children: element,
+          }
+        : {
+            fallbackComponent: ErrorComponent,
+            children: element,
+          };
+      element = createElement(errorBoundaryComponent, boundaryProps);
     }
   }