@timber-js/app 0.2.0-alpha.185 → 0.2.0-alpha.187

package/src/server/tree-builder.ts

@@ -12,6 +12,8 @@
 
 import type { ReactNode } from 'react';
 import type { RouteFile, SegmentNode } from '../routing/types.js';
+import { wrapSegmentWithErrorBoundaries } from './error-boundary-wrapper.js';
+import type { LoadedComponent } from './utils/element-type.js';
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -26,69 +28,6 @@ export interface LoadedModule {
 /** Function that loads a route file's module. */
 export type ModuleLoader = (file: RouteFile) => LoadedModule | Promise<LoadedModule>;
 
-/**
- * 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.
  *
@@ -143,22 +82,41 @@ export interface AccessGateProps {
   /** Segment name for dev logging (e.g. "authenticated", "dashboard"). */
   segmentName?: string;
   /**
-   * Pre-computed verdict from the pre-render pass. When set, AccessGate
-   * replays this verdict synchronously instead of calling accessFn.
-   * - 'pass': render children
-   * - DenySignal/RedirectSignal: throw synchronously
+   * 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.
    */
-  verdict?:
-    | 'pass'
-    | import('./primitives.js').DenySignal
-    | import('./primitives.js').RedirectSignal;
+  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.js').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;
 }
 
@@ -192,26 +150,6 @@ export interface SlotAccessGateProps {
     | 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 {
-  /** 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: ReactNode;
-}
-
 // ─── Tree Builder ────────────────────────────────────────────────────────────
 
 /**
@@ -272,13 +210,11 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
     const segment = segments[i];
 
     // Wrap in error boundaries (status-code files + error.tsx)
-    element = await wrapWithErrorBoundaries(
-      segment,
-      element,
+    element = await wrapSegmentWithErrorBoundaries(segment, element, {
       loadModule,
       createElement,
-      errorBoundaryComponent
-    );
+      errorBoundaryComponent,
+    });
 
     // Wrap in AccessGate if segment has access.ts
     if (segment.access) {
@@ -355,13 +291,11 @@ async function buildSlotElement(
   let element: ReactNode = createElement(PageComponent, {});
 
   // Wrap in error boundaries
-  element = await wrapWithErrorBoundaries(
-    slotNode,
-    element,
+  element = await wrapSegmentWithErrorBoundaries(slotNode, element, {
     loadModule,
     createElement,
-    errorBoundaryComponent
-  );
+    errorBoundaryComponent,
+  });
 
   // Wrap in SlotAccessGate if slot has access.ts
   if (slotNode.access) {
@@ -387,120 +321,3 @@ async function buildSlotElement(
 
   return element;
 }
-
-// ─── 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.
- *
- * Wrapping order (innermost to outermost):
- *   1. Specific status files (503.tsx, 429.tsx, etc.)
- *   2. Category catch-alls (4xx.tsx, 5xx.tsx)
- *   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: ReactNode,
-  loadModule: ModuleLoader,
-  createElement: CreateElement,
-  errorBoundaryComponent: unknown
-): 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 Object.entries(segment.statusFiles)) {
-      if (key !== '4xx' && key !== '5xx') {
-        const status = parseInt(key, 10);
-        if (!isNaN(status)) {
-          const mod = await loadModule(file);
-          // 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) {
-            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 Object.entries(segment.statusFiles)) {
-      if (key === '4xx' || key === '5xx') {
-        const mod = await loadModule(file);
-        const Component = isValidElementType(mod.default) ? mod.default : null;
-        if (Component) {
-          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 = isValidElementType(errorModule.default) ? errorModule.default : null;
-    if (ErrorComponent) {
-      const boundaryProps: ErrorBoundaryProps = isMdxFile(segment.error)
-        ? {
-            fallbackElement: createElement(ErrorComponent, {}),
-            children: element,
-          }
-        : {
-            fallbackComponent: ErrorComponent,
-            children: element,
-          };
-      element = createElement(errorBoundaryComponent, boundaryProps);
-    }
-  }
-
-  return element;
-}

package/src/server/types.ts

@@ -33,21 +33,26 @@ export interface MiddlewareContext {
  * `req` is the original incoming Request; `headers` is the response-headers
  * container the framework will apply to the final Response.
  *
- * Segment params and query parameters are NOT on this context — they are
- * accessed via the same ALS-backed `.get()` accessors pages use:
+ * Segment params and query parameters are NOT on this context — they are read
+ * the same way pages read them:
  *
  * ```ts
- * // app/api/users/[id]/params.ts
- * export const segmentParams = defineSegmentParams({ id: z.coerce.number() });
+ * // app/schema.ts — every dynamic segment's codec, keyed by bracket name
+ * export default defineSchema({ segmentParams: { '[id]': z.coerce.number() } });
+ *
  * // app/api/users/[id]/route.ts
- * import { segmentParams } from './params';
+ * import { getSegmentParams } from '@timber-js/app/server';
+ * import { SEGMENT_PATH } from './$segment';
  * export async function GET() {
- *   const { id } = segmentParams.get(); // typed number — 404 on bad input
+ *   const { id } = getSegmentParams(SEGMENT_PATH); // typed number — 404 on bad input
  * }
  * ```
  *
+ * For query parameters, import a `defineSearchParams` definition and call
+ * `.get()` on it.
+ *
  * See design/07-routing.md §"RouteContext", design/23-search-params.md,
- * design/40-segment-params.md.
+ * design/41-global-params.md.
  */
 export interface RouteContext {
   req: Request;

package/src/server/utils/element-type.ts

@@ -0,0 +1,72 @@
+/**
+ * Component-type validation for values loaded from route modules.
+ *
+ * Route modules are loaded dynamically, so their `default` export is
+ * `unknown`. Every construction site that wants to pass one to
+ * `createElement` narrows it through `isValidElementType` first.
+ */
+
+import type { ReactNode } from 'react';
+
+/**
+ * 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.
+ */
+export 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);
+}

package/src/shared/als-slots.ts

@@ -0,0 +1,72 @@
+/**
+ * ALS getter slots for the isomorphic `define*` modules.
+ *
+ * `searchParams.get()` and `segmentParams.get()` read per-request state out of
+ * `server/als-registry.ts`, but the modules that expose them are *isomorphic*:
+ * `search-params/define.ts` and `segment-params/define.ts` are imported by
+ * `'use client'` components for their hooks, so neither may import
+ * `node:async_hooks` — not even transitively, because the dep optimizer
+ * pre-bundles them before per-environment resolution runs. So the server
+ * registers its getter into a slot at module-init time and the define modules
+ * read the slot.
+ *
+ * The slots live here, in a module with **no imports at all**, rather than in
+ * the define modules themselves. That is the whole point: `request-context.ts`
+ * has to reach the setter, and when the setter lived in
+ * `search-params/define.ts` every server entry that touched
+ * `@timber-js/app/server` pulled that module — and therefore its `'use client'`
+ * import of `client/use-query-states.ts`, and therefore `nuqs` — into the
+ * server graph. `nuqs` named-imports `createContext`/`useContext` from React,
+ * which React's `react-server` export withholds, so `@timber-js/app`,
+ * `@timber-js/app/server`, `@timber-js/app/cookies` and `@timber-js/app/cache`
+ * all failed to instantiate under the `react-server` condition (TIM-1298).
+ * A leaf module breaks the edge without a registration ceremony on either side.
+ *
+ * Registration must be eager, not a call-time `await import()`: the async
+ * microtask a dynamic import introduces loses AsyncLocalStorage context inside
+ * React's RSC Flight renderer, which broke `getSearchParams()` in parallel slot
+ * pages (TIM-523).
+ *
+ * See design/23-search-params.md §"defineSearchParams — The Factory" and
+ * design/41-global-params.md.
+ */
+
+interface AlsSlot<T> {
+  /** Register the server-side getter. Called once at module-init time. */
+  set(fn: () => T): void;
+  /** Read through to the registered getter, or throw the client-side message. */
+  get(): T;
+}
+
+function createAlsSlot<T>(message: string): AlsSlot<T> {
+  let fn: (() => T) | undefined;
+  return {
+    set(next) {
+      fn = next;
+    },
+    get() {
+      if (!fn) throw new Error(message);
+      return fn();
+    },
+  };
+}
+
+const searchParamsSlot = createAlsSlot<URLSearchParams>(
+  '[timber] searchParams.get() is only available on the server. ' +
+    'Use searchParams.useQueryStates() on the client.'
+);
+
+const segmentParamsSlot = createAlsSlot<Record<string, string | string[]>>(
+  '[timber] segmentParams.get() is only available on the server. ' +
+    'Use segmentParams.useSegmentParams() on the client.'
+);
+
+/** @internal Called from `server/request-context.ts` at module init. */
+export const _setGetSearchParamsFn = searchParamsSlot.set;
+/** @internal Read by `search-params/define.ts` inside `.get()`. */
+export const getSearchParamsFromAls = searchParamsSlot.get;
+
+/** @internal Called from `server/request-context.ts` at module init. */
+export const _setGetSegmentParamsFn = segmentParamsSlot.set;
+/** @internal Read by `segment-params/define.ts` inside `.get()`. */
+export const getSegmentParamsFromAls = segmentParamsSlot.get;

package/src/shared/base-path.ts

@@ -0,0 +1,80 @@
+/**
+ * Deployment base path — Vite's resolved `base`, as it applies to the URLs
+ * timber addresses at runtime.
+ *
+ * A static build deployed under a sub-path (`base: '/repo/'`, the GitHub
+ * Pages project-site layout) serves every generated file below that prefix:
+ * the document for `/about` lives at `/repo/about/index.html`, its flight
+ * payload at `/repo/_rsc/about/index.rsc`. The client works in *route space* — the
+ * paths the app declares — so both a strip (browser URL → route path) and a
+ * prefix (route-space path → URL) are needed, and this module owns both.
+ *
+ * Pure functions, no state: the caller supplies the base. `client/rsc-fetch.ts`
+ * holds the client's copy, set at bootstrap from `virtual:timber-config`.
+ *
+ * See design/11-platform.md §"Deploying under a non-root base" (TIM-1261).
+ */
+
+/** `https://cdn.example.com/`, `//cdn.example.com/` — a base pointing off-origin. */
+function isAbsoluteUrlBase(base: string): boolean {
+  return base.startsWith('//') || /^[a-z][a-z0-9+.-]*:\/\//i.test(base);
+}
+
+/**
+ * True when `base` is document-relative (`'./'`, `'foo/'`) — it makes asset
+ * URLs resolve against whatever document loaded them, which says nothing
+ * about where the deployment sits, so no prefix can be computed from it.
+ */
+export function isRelativeBase(base: string | undefined): boolean {
+  if (!base) return false;
+  return !base.startsWith('/') && !isAbsoluteUrlBase(base);
+}
+
+/**
+ * Normalize Vite's `base` into a path prefix. Always returns a value with a
+ * leading and trailing slash.
+ *
+ * Two forms carry no usable deployment prefix and normalize to `/`:
+ *
+ * - **An absolute-URL base** points *assets* at a CDN. The HTML documents and
+ *   `.rsc` payloads are still served from the deployment origin, so their
+ *   URLs stay root-relative. This is correct, not a degradation.
+ * - **A relative base** — see `isRelativeBase`. The static build warns,
+ *   because SPA navigation then only works at the domain root.
+ */
+export function normalizeBasePath(base: string | undefined): string {
+  if (!base) return '/';
+  if (isAbsoluteUrlBase(base) || isRelativeBase(base)) return '/';
+  return base.endsWith('/') ? base : `${base}/`;
+}
+
+/**
+ * Strip the base prefix from a browser pathname, returning the route-space
+ * path. With base `/repo/`: `/repo/about` → `/about`, `/repo/` and `/repo`
+ * → `/`.
+ *
+ * A pathname outside the base is returned unchanged. It cannot be served by
+ * this deployment at all, so there is no better answer than letting the
+ * resulting fetch 404 and the router hard-navigate — visibly wrong beats
+ * silently rewritten.
+ *
+ * @param base A normalized base (see `normalizeBasePath`).
+ */
+export function stripBasePath(base: string, pathname: string): string {
+  if (base === '/') return pathname;
+  const withoutTrailingSlash = base.slice(0, -1);
+  if (pathname === withoutTrailingSlash) return '/';
+  if (!pathname.startsWith(base)) return pathname;
+  return pathname.slice(withoutTrailingSlash.length);
+}
+
+/**
+ * Prefix a route-space, root-relative path with the base.
+ * `/_rsc/about/index.rsc` → `/repo/_rsc/about/index.rsc`.
+ *
+ * @param base A normalized base (see `normalizeBasePath`).
+ */
+export function withBasePath(base: string, path: string): string {
+  if (base === '/') return path;
+  return path.startsWith('/') ? base.slice(0, -1) + path : `${base}${path}`;
+}