@timber-js/app 0.2.0-alpha.197 → 0.2.0-alpha.199

package/dist/server/tree-builder.d.ts

@@ -1,150 +0,0 @@
-/**
- * Element tree construction for timber.js rendering.
- *
- * Builds a unified React element tree from a matched segment chain, bottom-up:
- *   page → status-code error boundaries → access gates → layout → repeat up segment chain
- *
- * The tree is rendered via a single `renderToReadableStream` call,
- * giving one `React.cache` scope for the entire route.
- *
- * See design/02-rendering-pipeline.md §"Element Tree Construction"
- */
-import type { ReactNode } from 'react';
-import type { RouteFile, SegmentNode } from '../routing/types.ts';
-import type { LoadedComponent } from './utils/element-type.ts';
-/** A loaded module for a route file convention. */
-export interface LoadedModule {
-    /** The default export (component, access function, etc.) */
-    default?: unknown;
-    /** Named exports (for route.ts method handlers, metadata, etc.) */
-    [key: string]: unknown;
-}
-/** Function that loads a route file's module. */
-export type ModuleLoader = (file: RouteFile) => LoadedModule | Promise<LoadedModule>;
-/**
- * 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: object | null, ...children: unknown[]) => 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, ReactNode>;
-/** Configuration for the tree builder. */
-export interface TreeBuilderConfig {
-    /** The matched segment chain from root to leaf. */
-    segments: SegmentNode[];
-    /** Loads a route file's module. */
-    loadModule: ModuleLoader;
-    /** React.createElement or equivalent. */
-    createElement: CreateElement;
-    /**
-     * Error boundary component for wrapping segments.
-     *
-     * This is injected by the caller rather than imported directly to avoid
-     * pulling 'use client' code into the server barrel (@timber-js/app/server).
-     * In the RSC environment, the RSC plugin transforms this import to a
-     * client reference proxy — the caller handles the import so the server
-     * barrel stays free of client dependencies.
-     */
-    errorBoundaryComponent?: unknown;
-}
-/**
- * Framework-injected access gate component.
- *
- * When `verdict` is provided (from the pre-render pass), AccessGate replays
- * the stored result synchronously — no re-execution, no async, immune to
- * Suspense timing. When `verdict` is absent, falls back to calling `accessFn`
- * (backward compat for tree-builder.ts which doesn't run a pre-render pass).
- */
-export interface AccessGateProps {
-    accessFn: () => unknown;
-    /** Segment name for dev logging (e.g. "authenticated", "dashboard"). */
-    segmentName?: string;
-    /**
-     * Segment key of the gated segment (`computeSegmentKeys`). Decides whether
-     * a matched deny page renders here or is hoisted to the segment that owns
-     * it. Omitted by construction sites that build no deny chains — with no
-     * chain there is nothing to place. See TIM-1356.
-     */
-    segmentKey?: string;
-    /**
-     * Index of this segment in the matched segment chain. Recorded in ALS
-     * when the gate catches a DenySignal so post-render consumers
-     * (buildSegmentInfo, X-Timber-Segments) can bound the segment list
-     * without a pre-render access pass. See TIM-1363.
-     */
-    segmentIndex?: number;
-    /**
-     * 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.
-     *
-     * Omitted for skipped segments — a deny there must hard-navigate to
-     * avoid rendering the deny page inside cached layout chrome (TIM-1074).
-     */
-    denyPages?: import('./deny-boundary.ts').DenyPageEntry[];
-    /**
-     * When true, this gate wraps a skipped segment. On deny, the gate
-     * records the deny in ALS and rethrows so the response path can
-     * return rscErrorEnvelope for a client hard-navigate.
-     */
-    skippedSegment?: boolean;
-    /**
-     * Shell settlement callback. Called when the gate finishes (pass or
-     * deny). Tracked by shellSettled so the HTTP status is not committed
-     * before async access checks complete. See TIM-1045, TIM-1363.
-     */
-    onSettled?: () => void;
-    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: () => 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;
-}
-/**
- * Result of building the element tree.
- */
-export interface TreeBuildResult {
-    /**
-     * 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;
-}
-/**
- * Build the unified element tree from a matched segment chain.
- *
- * Construction is bottom-up:
- *   1. Start with the page component (leaf segment)
- *   2. Wrap in status-code error boundaries (fallback chain)
- *   3. Wrap in AccessGate (if segment has access.ts)
- *   4. Pass as children to the segment's layout
- *   5. Repeat up the segment chain to root
- *
- * Parallel slots are resolved at each layout level and composed as named props.
- */
-export declare function buildElementTree(config: TreeBuilderConfig): Promise<TreeBuildResult>;
-//# sourceMappingURL=tree-builder.d.ts.map

package/dist/server/tree-builder.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"tree-builder.d.ts","sourceRoot":"","sources":["../../src/server/tree-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAElE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAI/D,mDAAmD;AACnD,MAAM,WAAW,YAAY;IAC3B,4DAA4D;IAC5D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,mEAAmE;IACnE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,iDAAiD;AACjD,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,SAAS,KAAK,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;AAErF;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,GAAG,QAAQ,EAAE,OAAO,EAAE,KACnB,SAAS,CAAC;AAEf;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAElD,0CAA0C;AAC1C,MAAM,WAAW,iBAAiB;IAChC,mDAAmD;IACnD,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,mCAAmC;IACnC,UAAU,EAAE,YAAY,CAAC;IACzB,yCAAyC;IACzC,aAAa,EAAE,aAAa,CAAC;IAC7B;;;;;;;;OAQG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAID;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,OAAO,CAAC;IACxB,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,OAAO,oBAAoB,EAAE,aAAa,EAAE,CAAC;IACzD;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,OAAO,CAAC;IACxB,wFAAwF;IACxF,eAAe,EAAE,eAAe,GAAG,IAAI,CAAC;IACxC,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,aAAa,EAAE,aAAa,CAAC;IAC7B,eAAe,EAAE,SAAS,CAAC;IAC3B,QAAQ,EAAE,SAAS,CAAC;CACrB;AAID;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,IAAI,EAAE,SAAS,CAAC;IAChB,gFAAgF;IAChF,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,CAAC,CAkF1F"}

package/src/server/tree-builder.ts

@@ -1,313 +0,0 @@
-/**
- * Element tree construction for timber.js rendering.
- *
- * Builds a unified React element tree from a matched segment chain, bottom-up:
- *   page → status-code error boundaries → access gates → layout → repeat up segment chain
- *
- * The tree is rendered via a single `renderToReadableStream` call,
- * giving one `React.cache` scope for the entire route.
- *
- * See design/02-rendering-pipeline.md §"Element Tree Construction"
- */
-
-import type { ReactNode } from 'react';
-import type { RouteFile, SegmentNode } from '../routing/types.ts';
-import { wrapSegmentWithErrorBoundaries } from './error-boundary-wrapper.ts';
-import type { LoadedComponent } from './utils/element-type.ts';
-
-// ─── Types ───────────────────────────────────────────────────────────────────
-
-/** A loaded module for a route file convention. */
-export interface LoadedModule {
-  /** The default export (component, access function, etc.) */
-  default?: unknown;
-  /** Named exports (for route.ts method handlers, metadata, etc.) */
-  [key: string]: unknown;
-}
-
-/** Function that loads a route file's module. */
-export type ModuleLoader = (file: RouteFile) => LoadedModule | Promise<LoadedModule>;
-
-/**
- * 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: object | null,
-  ...children: unknown[]
-) => 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, ReactNode>;
-
-/** Configuration for the tree builder. */
-export interface TreeBuilderConfig {
-  /** The matched segment chain from root to leaf. */
-  segments: SegmentNode[];
-  /** Loads a route file's module. */
-  loadModule: ModuleLoader;
-  /** React.createElement or equivalent. */
-  createElement: CreateElement;
-  /**
-   * Error boundary component for wrapping segments.
-   *
-   * This is injected by the caller rather than imported directly to avoid
-   * pulling 'use client' code into the server barrel (@timber-js/app/server).
-   * In the RSC environment, the RSC plugin transforms this import to a
-   * client reference proxy — the caller handles the import so the server
-   * barrel stays free of client dependencies.
-   */
-  errorBoundaryComponent?: unknown;
-}
-
-// ─── Component wrappers ──────────────────────────────────────────────────────
-
-/**
- * Framework-injected access gate component.
- *
- * When `verdict` is provided (from the pre-render pass), AccessGate replays
- * the stored result synchronously — no re-execution, no async, immune to
- * Suspense timing. When `verdict` is absent, falls back to calling `accessFn`
- * (backward compat for tree-builder.ts which doesn't run a pre-render pass).
- */
-export interface AccessGateProps {
-  accessFn: () => unknown;
-  /** Segment name for dev logging (e.g. "authenticated", "dashboard"). */
-  segmentName?: string;
-  /**
-   * Segment key of the gated segment (`computeSegmentKeys`). Decides whether
-   * a matched deny page renders here or is hoisted to the segment that owns
-   * it. Omitted by construction sites that build no deny chains — with no
-   * chain there is nothing to place. See TIM-1356.
-   */
-  segmentKey?: string;
-  /**
-   * Index of this segment in the matched segment chain. Recorded in ALS
-   * when the gate catches a DenySignal so post-render consumers
-   * (buildSegmentInfo, X-Timber-Segments) can bound the segment list
-   * without a pre-render access pass. See TIM-1363.
-   */
-  segmentIndex?: number;
-  /**
-   * 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.
-   *
-   * Omitted for skipped segments — a deny there must hard-navigate to
-   * avoid rendering the deny page inside cached layout chrome (TIM-1074).
-   */
-  denyPages?: import('./deny-boundary.ts').DenyPageEntry[];
-  /**
-   * When true, this gate wraps a skipped segment. On deny, the gate
-   * records the deny in ALS and rethrows so the response path can
-   * return rscErrorEnvelope for a client hard-navigate.
-   */
-  skippedSegment?: boolean;
-  /**
-   * Shell settlement callback. Called when the gate finishes (pass or
-   * deny). Tracked by shellSettled so the HTTP status is not committed
-   * before async access checks complete. See TIM-1045, TIM-1363.
-   */
-  onSettled?: () => void;
-  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: () => 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;
-}
-
-// ─── Tree Builder ────────────────────────────────────────────────────────────
-
-/**
- * Result of building the element tree.
- */
-export interface TreeBuildResult {
-  /**
-   * 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;
-}
-
-/**
- * Build the unified element tree from a matched segment chain.
- *
- * Construction is bottom-up:
- *   1. Start with the page component (leaf segment)
- *   2. Wrap in status-code error boundaries (fallback chain)
- *   3. Wrap in AccessGate (if segment has access.ts)
- *   4. Pass as children to the segment's layout
- *   5. Repeat up the segment chain to root
- *
- * Parallel slots are resolved at each layout level and composed as named props.
- */
-export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeBuildResult> {
-  const { segments, loadModule, createElement, errorBoundaryComponent } = config;
-
-  if (segments.length === 0) {
-    throw new Error('[timber] buildElementTree: empty segment chain');
-  }
-
-  const leaf = segments[segments.length - 1];
-
-  // API routes (route.ts) don't build a React tree
-  if (leaf.route && !leaf.page) {
-    return { tree: null, isApiRoute: true };
-  }
-
-  // Start with the page component
-  const pageModule = leaf.page ? await loadModule(leaf.page) : null;
-  const PageComponent = pageModule?.default as LoadedComponent | undefined;
-
-  if (!PageComponent) {
-    throw new Error(
-      `[timber] No page component found for route at ${leaf.urlPath}. ` +
-        'Each route must have a page.tsx or route.ts.'
-    );
-  }
-
-  // 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--) {
-    const segment = segments[i];
-
-    // Wrap in error boundaries (status-code files + error.tsx)
-    element = await wrapSegmentWithErrorBoundaries(segment, element, {
-      loadModule,
-      createElement,
-      errorBoundaryComponent,
-    });
-
-    // Wrap in AccessGate if segment has access.ts
-    if (segment.access) {
-      const accessModule = await loadModule(segment.access);
-      const accessFn = accessModule.default as AccessGateProps['accessFn'];
-      element = createElement('timber:access-gate', {
-        accessFn,
-        segmentName: segment.segmentName,
-        children: element,
-      } satisfies AccessGateProps);
-    }
-
-    // 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 LoadedComponent | undefined;
-
-      if (LayoutComponent) {
-        // Resolve parallel slots for this layout
-        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,
-              loadModule,
-              createElement,
-              errorBoundaryComponent
-            );
-          }
-        }
-
-        /* eslint-disable react/no-children-prop -- createElement API */
-        element = createElement(LayoutComponent, {
-          ...slotProps,
-          children: element,
-        });
-        /* eslint-enable react/no-children-prop */
-      }
-    }
-  }
-
-  return { tree: element, isApiRoute: false };
-}
-
-// ─── Slot Element Builder ────────────────────────────────────────────────────
-
-/**
- * Build the element tree for a parallel slot.
- *
- * Slots have their own access.ts (SlotAccessGate) and error boundaries.
- * On access denial: denied.tsx → default.tsx → null (graceful degradation).
- */
-async function buildSlotElement(
-  slotNode: SegmentNode,
-  loadModule: ModuleLoader,
-  createElement: CreateElement,
-  errorBoundaryComponent: unknown
-): Promise<ReactNode> {
-  // Load slot page
-  const pageModule = slotNode.page ? await loadModule(slotNode.page) : null;
-  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 LoadedComponent | undefined;
-
-  // If no page, render default.tsx or null
-  if (!PageComponent) {
-    return DefaultComponent ? createElement(DefaultComponent, {}) : null;
-  }
-
-  let element: ReactNode = createElement(PageComponent, {});
-
-  // Wrap in error boundaries
-  element = await wrapSegmentWithErrorBoundaries(slotNode, element, {
-    loadModule,
-    createElement,
-    errorBoundaryComponent,
-  });
-
-  // Wrap in SlotAccessGate if slot has access.ts
-  if (slotNode.access) {
-    const accessModule = await loadModule(slotNode.access);
-    const accessFn = accessModule.default as SlotAccessGateProps['accessFn'];
-
-    // 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 LoadedComponent | undefined) ?? null;
-
-    const defaultFallback = DefaultComponent ? createElement(DefaultComponent, {}) : null;
-
-    element = createElement('timber:slot-access-gate', {
-      accessFn,
-      DeniedComponent,
-      slotName: slotNode.segmentName.replace(/^@/, ''),
-      createElement,
-      defaultFallback,
-      children: element,
-    } satisfies SlotAccessGateProps);
-  }
-
-  return element;
-}