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

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,22 +26,87 @@ 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,
+]);
 
-/** Function that creates a React element. Matches React.createElement signature. */
+/**
+ * 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.
+ *
+ * `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 {
@@ -92,8 +158,8 @@ export interface AccessGateProps {
    * This prevents the error from reaching React Flight, eliminating the
    * second render pass. See TIM-666.
    */
-  denyPages?: import('./deny-page-resolver.js').DenyPageEntry[];
-  children: ReactElement;
+  denyPages?: import('./deny-boundary.js').DenyPageEntry[];
+  children: ReactNode;
 }
 
 /**
@@ -107,24 +173,33 @@ export interface AccessGateProps {
 export interface SlotAccessGateProps {
   accessFn: () => unknown;
   /** The denied.tsx component (not a pre-built element). null if no denied.tsx exists. */
-  DeniedComponent: ((...args: unknown[]) => unknown) | null;
+  DeniedComponent: LoadedComponent | null;
   /** Slot directory name without @ prefix (e.g. "admin", "sidebar"). */
   slotName: string;
   /** createElement function for building elements dynamically. */
   createElement: CreateElement;
-  defaultFallback: ReactElement | null;
-  children: ReactElement;
+  defaultFallback: ReactNode;
+  children: ReactNode;
 }
 
 /**
  * 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;
-  fallbackElement?: 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 ────────────────────────────────────────────────────────────
@@ -133,8 +208,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;
 }
@@ -167,7 +245,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(
@@ -177,7 +255,7 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
   }
 
   // Build the page element — params are accessed via getSegmentParams() from ALS
-  let element: ReactElement = createElement(PageComponent, {});
+  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--) {
@@ -206,15 +284,15 @@ 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,
               loadModule,
@@ -248,23 +326,21 @@ async function buildSlotElement(
   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, {}) : null;
   }
 
-  let element: ReactElement = createElement(PageComponent, {});
+  let element: ReactNode = createElement(PageComponent, {});
 
   // Wrap in error boundaries
   element = await wrapWithErrorBoundaries(
@@ -283,8 +359,7 @@ async function buildSlotElement(
     // 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) ?? null;
+    const DeniedComponent = (deniedModule?.default as LoadedComponent | undefined) ?? null;
 
     const defaultFallback = DefaultComponent ? createElement(DefaultComponent, {}) : null;
 
@@ -334,34 +409,37 @@ function isMdxFile(file: RouteFile): boolean {
  */
 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) {
-            const boundaryProps = isMdxFile(file)
-              ? ({
+            const boundaryProps: ErrorBoundaryProps = isMdxFile(file)
+              ? {
                   fallbackElement: createElement(Component, { status }),
                   status,
                   children: element,
-                } satisfies ErrorBoundaryProps)
-              : ({
+                }
+              : {
                   fallbackComponent: Component,
                   status,
                   children: element,
-                } satisfies ErrorBoundaryProps);
+                };
             element = createElement(errorBoundaryComponent, boundaryProps);
           }
         }
@@ -369,23 +447,23 @@ async function wrapWithErrorBoundaries(
     }
 
     // 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) {
           const categoryStatus = key === '4xx' ? 400 : 500;
-          const boundaryProps = isMdxFile(file)
-            ? ({
+          const boundaryProps: ErrorBoundaryProps = isMdxFile(file)
+            ? {
                 fallbackElement: createElement(Component, {}),
                 status: categoryStatus,
                 children: element,
-              } satisfies ErrorBoundaryProps)
-            : ({
+              }
+            : {
                 fallbackComponent: Component,
                 status: categoryStatus,
                 children: element,
-              } satisfies ErrorBoundaryProps);
+              };
           element = createElement(errorBoundaryComponent, boundaryProps);
         }
       }
@@ -397,17 +475,17 @@ async function wrapWithErrorBoundaries(
   // 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) {
-      const boundaryProps = isMdxFile(segment.error)
-        ? ({
+      const boundaryProps: ErrorBoundaryProps = isMdxFile(segment.error)
+        ? {
             fallbackElement: createElement(ErrorComponent, {}),
             children: element,
-          } satisfies ErrorBoundaryProps)
-        : ({
+          }
+        : {
             fallbackComponent: ErrorComponent,
             children: element,
-          } satisfies ErrorBoundaryProps);
+          };
       element = createElement(errorBoundaryComponent, boundaryProps);
     }
   }

package/src/server/types.ts

@@ -160,4 +160,56 @@ export namespace MetadataRoute {
     sitemap?: string | string[];
     host?: string;
   }
+  /**
+   * PWA Web App Manifest — serialized as `application/manifest+json`.
+   *
+   * Intentionally permissive: the manifest spec is large and evolving
+   * (W3C + browser-specific extensions). Users that want stricter typing
+   * can augment the return type with a library like `web-app-manifest`.
+   */
+  export type Manifest = Record<string, unknown>;
 }
+
+/**
+ * The value a dynamic metadata route handler may return.
+ *
+ * This is a structural union — the pipeline dispatches on the shape at
+ * request time (see `pipeline-phases.ts`):
+ *   - `Response` → returned as-is (e.g. `ImageResponse`, `Response.redirect()`).
+ *     Used by `icon.tsx`, `opengraph-image.tsx`, `twitter-image.tsx`,
+ *     `apple-icon.tsx`.
+ *   - `string` → written as the response body verbatim. Used by `robots.ts`
+ *     and by any handler that wants to emit a pre-serialized payload.
+ *   - `MetadataRoute.Sitemap` → serialized via the sitemap XML writer. Used
+ *     by `sitemap.ts`.
+ *   - `MetadataRoute.Manifest` → serialized via `JSON.stringify`. Used by
+ *     `manifest.ts`.
+ *
+ * See design/16-metadata.md §"Metadata Routes".
+ */
+export type MetadataResult = Response | string | MetadataRoute.Sitemap | MetadataRoute.Manifest;
+
+/**
+ * Default export signature for a dynamic metadata route file
+ * (`sitemap.ts`, `robots.ts`, `manifest.ts`, `icon.tsx`,
+ * `opengraph-image.tsx`, `twitter-image.tsx`, `apple-icon.tsx`).
+ *
+ * Parameterize `TResult` to narrow the return type for a specific route:
+ *
+ * ```ts
+ * // app/sitemap.ts
+ * import type { MetadataHandler, MetadataRoute } from '@timber-js/app/server';
+ *
+ * const sitemap: MetadataHandler<MetadataRoute.Sitemap> = async () => [
+ *   { url: 'https://example.com/', changeFrequency: 'weekly', priority: 1 },
+ * ];
+ * export default sitemap;
+ * ```
+ *
+ * The handler is currently invoked with no arguments. Per-request context
+ * (`params`, `searchParams`, `Request`) is not yet wired through to metadata
+ * route handlers; when it is, this signature will grow a context parameter.
+ */
+export type MetadataHandler<TResult extends MetadataResult = MetadataResult> = () =>
+  | TResult
+  | Promise<TResult>;

package/src/server/utils/escape-html.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared HTML escaping utility.
+ *
+ * Used by both dev-only paths (error pages, 404 page) and production
+ * paths (deny-renderer, RSC helpers). Lives in server/utils/ because
+ * it's not dev-only.
+ */
+
+/**
+ * Escape a string for safe embedding in HTML content or attributes.
+ *
+ * Replaces `&`, `<`, `>`, and `"` with their HTML entity equivalents.
+ */
+export function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}

package/src/shims/headers.ts

@@ -6,8 +6,8 @@
  * pipeline (both import from the same shared request-context chunk in dist/).
  */
 
-// Re-export timber's new names for the primary API
-export { getHeaders, getCookies } from '@timber-js/app/server';
+// Re-export timber's primary API
+export { getHeaders, getCookieJar } from '@timber-js/app/server';
 
 // Next.js compat aliases — libraries importing from 'next/headers' expect these names.
-export { getHeaders as headers, getCookies as cookies } from '@timber-js/app/server';
+export { getHeaders as headers, getCookieJar as cookies } from '@timber-js/app/server';

package/src/shims/navigation-client.ts

@@ -16,11 +16,12 @@
  * See design/14-ecosystem.md §"next/navigation" for the full shim audit.
  */
 
-// Hooks — imported from the public barrel for module singleton consistency.
+// Hooks — useSegmentParams and useSearchParams import from direct modules
+// since they're no longer in @timber-js/app/client public exports.
+export { useSegmentParams } from '../client/use-segment-params.js';
+export { useSearchParams } from '../client/use-search-params.js';
 export {
-  useSegmentParams,
   usePathname,
-  useSearchParams,
   useRouter,
   useSelectedLayoutSegment,
   useSelectedLayoutSegments,

package/src/shims/navigation.ts

@@ -1,17 +1,19 @@
 /**
  * Shim: next/navigation → timber navigation primitives
  *
- * Client hooks import from @timber-js/app/client (the public barrel) so they
- * resolve to the same module instances as user code in Vite dev. Server
- * functions import from @timber-js/app/server for ALS singleton consistency.
+ * Client hooks import from their direct modules since useSegmentParams,
+ * useSearchParams, and useQueryStates are no longer part of
+ * @timber-js/app/client public exports (they live on define* factories).
+ * The shim re-exports them for next/navigation library compat (nuqs etc).
+ *
+ * Server functions import from @timber-js/app/server for ALS singleton consistency.
  */
 
-// Hooks (client-side — imported from public barrel for module singleton)
+// Hooks re-exported for next/navigation compat
+export { useSegmentParams, useSegmentParams as useParams } from '../client/use-segment-params.js';
+export { useSearchParams } from '../client/use-search-params.js';
 export {
-  useSegmentParams,
-  useSegmentParams as useParams,
   usePathname,
-  useSearchParams,
   useRouter,
   useSelectedLayoutSegment,
   useSelectedLayoutSegments,