@timber-js/app 0.2.0-alpha.9 → 0.2.0-alpha.90

package/src/server/deny-page-resolver.ts

@@ -0,0 +1,154 @@
+/**
+ * Deny Page Resolver — resolves status-code file components for in-tree deny handling.
+ *
+ * When AccessGate or PageDenyBoundary catches a DenySignal, they need to
+ * render the matching deny page (403.tsx, 4xx.tsx, error.tsx) as a normal
+ * element in the React tree. This module resolves the deny page chain from
+ * the segment chain — a list of fallback components ordered by specificity.
+ *
+ * The chain is built during buildRouteElement and passed as a prop to
+ * AccessGate and PageDenyBoundary. At catch time, the first matching
+ * component is rendered.
+ *
+ * See design/10-error-handling.md §"Status-Code Files", TIM-666.
+ */
+
+import { createElement } from 'react';
+
+import type { ManifestSegmentNode } from './route-matcher.js';
+import { loadModule } from './safe-load.js';
+import { requestContextAls } from './als-registry.js';
+
+// ─── Types ────────────────────────────────────────────────────────────────
+
+/** A single entry in the deny page fallback chain. */
+export interface DenyPageEntry {
+  /** Status code filter: specific (403), category (400 = any 4xx), or null (catch-all). */
+  status: number | null;
+  /** The component to render (server or client — both work). */
+  component: (...args: unknown[]) => unknown;
+}
+
+// ─── Resolver ─────────────────────────────────────────────────────────────
+
+/**
+ * Build the deny page fallback chain from the segment chain.
+ *
+ * Walks segments from `startIndex` outward (toward root) and collects
+ * status-code file components in fallback order:
+ * 1. Specific status files (403.tsx, 404.tsx) — exact match
+ * 2. Category catch-alls (4xx.tsx) — matches any 4xx
+ * 3. error.tsx — catches everything
+ *
+ * Each segment is checked in this order. The chain is ordered so the
+ * FIRST match wins at catch time.
+ */
+export async function buildDenyPageChain(
+  segments: ManifestSegmentNode[],
+  startIndex: number
+): Promise<DenyPageEntry[]> {
+  const chain: DenyPageEntry[] = [];
+
+  // Pass 1: Status files (specific + category) across ALL segments.
+  // These have higher priority than error.tsx — a root 4xx.tsx should
+  // match before a leaf error.tsx. Walking inner → outer ensures the
+  // nearest match wins within each priority tier.
+  for (let i = startIndex; i >= 0; i--) {
+    const segment = segments[i];
+    if (!segment.statusFiles) continue;
+
+    // Specific status files (403.tsx, 404.tsx, etc.)
+    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).catch(() => null);
+          if (mod?.default) {
+            chain.push({ status, component: mod.default as (...args: unknown[]) => unknown });
+          }
+        }
+      }
+    }
+
+    // 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).catch(() => null);
+        if (mod?.default) {
+          const categoryStatus = key === '4xx' ? 400 : 500;
+          chain.push({
+            status: categoryStatus,
+            component: mod.default as (...args: unknown[]) => unknown,
+          });
+        }
+      }
+    }
+  }
+
+  // Pass 2: error.tsx files — lowest priority catch-all.
+  // Only added AFTER all status files so they never shadow a specific
+  // or category status file from an ancestor segment.
+  for (let i = startIndex; i >= 0; i--) {
+    const segment = segments[i];
+    if (segment.error) {
+      const mod = await loadModule(segment.error).catch(() => null);
+      if (mod?.default) {
+        chain.push({ status: null, component: mod.default as (...args: unknown[]) => unknown });
+      }
+    }
+  }
+
+  return chain;
+}
+
+// ─── Matcher ──────────────────────────────────────────────────────────────
+
+/**
+ * Find the first deny page in the chain that matches the given status code.
+ * Returns a React element for the matching component, or null if no match.
+ */
+export function renderMatchingDenyPage(
+  chain: DenyPageEntry[],
+  status: number,
+  data: unknown
+): React.ReactElement | null {
+  const h = createElement as (...args: unknown[]) => React.ReactElement;
+
+  for (const entry of chain) {
+    if (entry.status === status) {
+      return h(entry.component, { status, dangerouslyPassData: data });
+    }
+    if (entry.status === 400 && status >= 400 && status <= 499) {
+      return h(entry.component, { status, dangerouslyPassData: data });
+    }
+    if (entry.status === 500 && status >= 500 && status <= 599) {
+      return h(entry.component, { status, dangerouslyPassData: data });
+    }
+    if (entry.status === null) {
+      return h(entry.component, { status, dangerouslyPassData: data });
+    }
+  }
+  return null;
+}
+
+// ─── ALS Helper ───────────────────────────────────────────────────────────
+
+/**
+ * Set the deny status in the request context ALS.
+ * Called from AccessGate / PageDenyBoundary when a DenySignal is caught.
+ * The pipeline reads this after render to set the HTTP status code.
+ */
+export function setDenyStatus(status: number): void {
+  const store = requestContextAls.getStore();
+  if (store) {
+    store.denyStatus = status;
+  }
+}
+
+/**
+ * Read the deny status from the request context ALS.
+ * Returns undefined if no deny was caught during render.
+ */
+export function getDenyStatus(): number | undefined {
+  return requestContextAls.getStore()?.denyStatus;
+}

package/src/server/deny-renderer.ts

@@ -16,18 +16,21 @@
  */
 
 import { createElement } from 'react';
-import { renderToReadableStream } from '#/rsc-runtime/rsc.js';
+import { renderToReadableStream } from '../rsc-runtime/rsc.js';
 
 import { DenySignal } from './primitives.js';
 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 type { ManifestSegmentNode } from './route-matcher.js';
 import type { RouteMatch } from './pipeline.js';
 import type { NavContext } from './ssr-entry.js';
+import { flightInitScript } from './flight-scripts.js';
 import type { ClientBootstrapConfig } from './html-injectors.js';
 import type { Metadata } from './types.js';
+import { teeWithErrorPropagation } from './stream-utils.js';
 
 /** RSC content type for client navigation payload requests. */
 const RSC_CONTENT_TYPE = 'text/x-component';
@@ -108,7 +111,7 @@ export async function renderDenyPage(
   }
 
   // Load the status-code page component
-  const mod = (await resolution.file.load()) as Record<string, unknown>;
+  const mod = await loadModule(resolution.file);
   if (!mod.default) {
     return new Response(null, { status: deny.status, headers: responseHeaders });
   }
@@ -116,9 +119,6 @@ export async function renderDenyPage(
   const ErrorPageComponent = mod.default as (...args: unknown[]) => unknown;
   const h = createElement as (...args: unknown[]) => React.ReactElement;
 
-  // Check shell opt-out: export const shell = false
-  const shellEnabled = mod.shell !== false;
-
   // 4xx status-code pages receive { status, dangerouslyPassData }
   // per design/10-error-handling.md §"Status-Code File Props"
   let element = h(ErrorPageComponent, {
@@ -126,23 +126,14 @@ export async function renderDenyPage(
     dangerouslyPassData: deny.data,
   });
 
-  // Wrap in layouts unless shell is explicitly disabled
-  if (shellEnabled) {
-    const resolvedSegments = new Set(segments.slice(0, resolution.segmentIndex + 1));
-    const layoutsToWrap = layoutComponents.filter((lc) => resolvedSegments.has(lc.segment));
-    for (let i = layoutsToWrap.length - 1; i >= 0; i--) {
-      const { component } = layoutsToWrap[i];
-      element = h(component, null, element);
-    }
-  } else if (isDebug()) {
-    // Dev-mode: warn if shell=false might conflict with Suspense
-    // The actual Suspense boundary check happens at render time in the pipeline.
-    // This is a preemptive log for developer awareness.
-    console.warn(
-      `[timber] Status-code file ${resolution.file.filePath} exports shell = false. ` +
-        'If deny() fires inside a Suspense boundary, layouts are already committed and ' +
-        'cannot be unwrapped. The shell opt-out will be ignored in that case.'
-    );
+  // Always wrap in layout shell.
+  // NOTE: Shell opt-out (export const shell = false) is a future feature
+  // pending a proper design doc. See design backlog.
+  const resolvedSegments = new Set(segments.slice(0, resolution.segmentIndex + 1));
+  const layoutsToWrap = layoutComponents.filter((lc) => resolvedSegments.has(lc.segment));
+  for (let i = layoutsToWrap.length - 1; i >= 0; i--) {
+    const { component } = layoutsToWrap[i];
+    element = h(component, null, element);
   }
 
   // Build head HTML from error page metadata (if any)
@@ -170,15 +161,15 @@ export async function renderDenyPage(
     debugChannel: createDebugChannelSink(),
   });
 
-  const [ssrStream, inlineStream] = rscStream.tee();
+  const [ssrStream, inlineStream] = teeWithErrorPropagation(rscStream);
 
   const navContext: NavContext = {
     pathname: new URL(req.url).pathname,
-    params: match.params,
+    params: match.segmentParams,
     searchParams: Object.fromEntries(new URL(req.url).searchParams),
     statusCode: deny.status,
     responseHeaders,
-    headHtml,
+    headHtml: headHtml + flightInitScript(),
     bootstrapScriptContent: clientBootstrap.bootstrapScriptContent,
     rscStream: inlineStream,
   };
@@ -206,7 +197,7 @@ export async function renderDenyPageAsRsc(
     return new Response(null, { status: deny.status, headers: responseHeaders });
   }
 
-  const mod = (await resolution.file.load()) as Record<string, unknown>;
+  const mod = await loadModule(resolution.file);
   if (!mod.default) {
     responseHeaders.set('content-type', `${RSC_CONTENT_TYPE}; charset=utf-8`);
     return new Response(null, { status: deny.status, headers: responseHeaders });
@@ -215,22 +206,17 @@ export async function renderDenyPageAsRsc(
   const ErrorPageComponent = mod.default as (...args: unknown[]) => unknown;
   const h = createElement as (...args: unknown[]) => React.ReactElement;
 
-  // Check shell opt-out
-  const shellEnabled = mod.shell !== false;
-
   let element = h(ErrorPageComponent, {
     status: deny.status,
     dangerouslyPassData: deny.data,
   });
 
-  // Wrap in layouts unless shell is explicitly disabled
-  if (shellEnabled) {
-    const resolvedSegments = new Set(segments.slice(0, resolution.segmentIndex + 1));
-    const layoutsToWrap = layoutComponents.filter((lc) => resolvedSegments.has(lc.segment));
-    for (let i = layoutsToWrap.length - 1; i >= 0; i--) {
-      const { component } = layoutsToWrap[i];
-      element = h(component, null, element);
-    }
+  // Always wrap in layout shell.
+  const resolvedSegments = new Set(segments.slice(0, resolution.segmentIndex + 1));
+  const layoutsToWrap = layoutComponents.filter((lc) => resolvedSegments.has(lc.segment));
+  for (let i = layoutsToWrap.length - 1; i >= 0; i--) {
+    const { component } = layoutsToWrap[i];
+    element = h(component, null, element);
   }
 
   const rscStream = renderToReadableStream(element, {
@@ -272,7 +258,7 @@ async function renderDenyPageJson(
   // JSON status files are loaded as modules that export the JSON content.
   // The manifest's load() imports the .json file, which Vite handles as a
   // default export of the parsed JSON object.
-  const mod = (await resolution.file.load()) as Record<string, unknown>;
+  const mod = await loadModule(resolution.file);
   const jsonContent = mod.default ?? mod;
 
   responseHeaders.set('content-type', 'application/json; charset=utf-8');

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

@@ -0,0 +1,185 @@
+/**
+ * Dev holding server — serves a loading page while Vite initializes.
+ *
+ * When `timber dev` (or `vite dev`) starts, Vite takes several seconds
+ * to initialize all plugins, scan routes, and boot the RSC environment.
+ * During this window, the port is unbound and browsers get
+ * ERR_CONNECTION_REFUSED.
+ *
+ * This module creates a lightweight HTTP server that binds the port
+ * immediately and serves a branded holding page with auto-refresh.
+ * Once Vite is ready, the holding server is closed and Vite's server
+ * takes over the port.
+ *
+ * The holding server is started in rootSync's config() hook (the
+ * earliest Vite plugin lifecycle point where we know the port) and
+ * closed in timber-dev-server's configureServer() hook (the last
+ * plugin, right before Vite calls server.listen()).
+ *
+ * Browser requests (Accept: text/html) get the HTML holding page.
+ * API requests (Accept: application/json) get a 503 JSON response.
+ * All responses include Retry-After: 1.
+ *
+ * See design/21-dev-server.md, TIM-665.
+ */
+
+import http from 'node:http';
+
+// ─── Types ────────────────────────────────────────────────────────────────
+
+export interface HoldingServer {
+  /**
+   * Start listening on the given port.
+   * Returns the actual bound port (useful when port is 0 for OS assignment).
+   */
+  listen(port: number): Promise<number>;
+
+  /** Gracefully close the server and stop accepting connections. */
+  close(): Promise<void>;
+}
+
+// ─── Holding Page HTML ────────────────────────────────────────────────────
+
+/**
+ * Minimal self-contained HTML holding page.
+ *
+ * Matches the timber.js docs site theme:
+ * - Light mode: warm stone/grain background, timber/bark text
+ * - Dark mode: stone-900 background, stone-200 text
+ * - 🪵 timber.js branding
+ *
+ * Uses meta-refresh (1s) for auto-reload — works without JavaScript.
+ * Inline CSS only, no external dependencies.
+ */
+const HOLDING_PAGE_HTML = [
+  '<!DOCTYPE html>',
+  '<html lang="en">',
+  '<head>',
+  '  <meta charset="utf-8">',
+  '  <meta name="viewport" content="width=device-width, initial-scale=1">',
+  '  <meta http-equiv="refresh" content="2">',
+  '  <title>timber — starting...</title>',
+  '  <style>',
+  '    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }',
+  '    body {',
+  '      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;',
+  '      background: #fafaf9;',
+  '      color: #44403c;',
+  '      display: flex;',
+  '      align-items: center;',
+  '      justify-content: center;',
+  '      min-height: 100vh;',
+  '      -webkit-font-smoothing: antialiased;',
+  '    }',
+  '    @media (prefers-color-scheme: dark) {',
+  '      body { background: #1c1917; color: #e7e5e4; }',
+  '      .message { color: #a8a29e; }',
+  '      .spinner { border-color: #57534e; border-top-color: #a1887f; }',
+  '      .logo { color: #e7e5e4; }',
+  '    }',
+  '    .container { text-align: center; padding: 2rem; }',
+  '    .logo {',
+  '      font-size: 1.5rem;',
+  '      font-weight: 700;',
+  '      letter-spacing: -0.02em;',
+  '      color: #5c3d2e;',
+  '      margin-bottom: 1.5rem;',
+  '    }',
+  '    .message {',
+  '      font-size: 0.95rem;',
+  '      color: #78716c;',
+  '      margin-bottom: 2rem;',
+  '    }',
+  '    .spinner {',
+  '      width: 24px;',
+  '      height: 24px;',
+  '      border: 2.5px solid #d7ccc8;',
+  '      border-top-color: #6d4c41;',
+  '      border-radius: 50%;',
+  '      animation: spin 0.8s linear infinite;',
+  '      margin: 0 auto;',
+  '    }',
+  '    @keyframes spin { to { transform: rotate(360deg); } }',
+  '  </style>',
+  '</head>',
+  '<body>',
+  '  <div class="container">',
+  '    <div class="logo">\u{1FAB5} timber.js</div>',
+  '    <p class="message">Dev server starting&hellip;</p>',
+  '    <div class="spinner"></div>',
+  '  </div>',
+  '</body>',
+  '</html>',
+].join('\n');
+
+// ─── Factory ──────────────────────────────────────────────────────────────
+
+/**
+ * Create a holding HTTP server that serves a loading page during startup.
+ *
+ * Usage (inside Vite plugin):
+ * ```ts
+ * // In config() hook — earliest point where port is known
+ * const holding = createHoldingServer();
+ * holding.listen(config.server?.port ?? 5173);
+ *
+ * // In last plugin's configureServer() — wrap listen for seamless handoff
+ * const originalListen = server.listen.bind(server);
+ * server.listen = async (...args) => {
+ *   await holding.close();
+ *   return originalListen(...args);
+ * };
+ * ```
+ */
+export function createHoldingServer(): HoldingServer {
+  const server = http.createServer((req, res) => {
+    const accept = req.headers.accept ?? '';
+
+    // API requests: JSON 503
+    if (accept.includes('application/json') && !accept.includes('text/html')) {
+      res.writeHead(503, {
+        'Content-Type': 'application/json; charset=utf-8',
+        'Retry-After': '1',
+        'Cache-Control': 'no-store',
+      });
+      res.end(
+        JSON.stringify({
+          error: 'Service Unavailable',
+          message: 'timber dev server is starting — please retry shortly',
+        })
+      );
+      return;
+    }
+
+    // Browser and other requests: HTML holding page
+    res.writeHead(503, {
+      'Content-Type': 'text/html; charset=utf-8',
+      'Retry-After': '1',
+      'Cache-Control': 'no-store',
+    });
+    res.end(HOLDING_PAGE_HTML);
+  });
+
+  return {
+    listen(port: number): Promise<number> {
+      return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, () => {
+          server.removeListener('error', reject);
+          const addr = server.address();
+          const boundPort = typeof addr === 'object' && addr ? addr.port : port;
+          resolve(boundPort);
+        });
+      });
+    },
+
+    close(): Promise<void> {
+      return new Promise((resolve, reject) => {
+        server.close((err) => {
+          if (err) reject(err);
+          else resolve();
+        });
+      });
+    },
+  };
+}

package/src/server/dev-source-map.ts

@@ -0,0 +1,31 @@
+/**
+ * Dev-only error source-mapping bridge.
+ *
+ * Stores a callback that rewrites an error's stack trace using the Vite
+ * dev server's module graph. Set by the RSC entry on startup (via
+ * setDevSourceMapHandler), consumed by error renderers before generating
+ * error pages.
+ *
+ * In production, the callback is never set — all calls are no-ops.
+ *
+ * See TIM-811.
+ */
+
+let _sourceMapError: ((error: Error) => void) | undefined;
+
+/**
+ * Set the source-map callback. Called once during dev server initialization.
+ */
+export function setSourceMapCallback(fn: (error: Error) => void): void {
+  _sourceMapError = fn;
+}
+
+/**
+ * Source-map an error's stack trace in-place if the callback is available.
+ * No-op in production or before the dev server initializes.
+ */
+export function sourceMapError(error: unknown): void {
+  if (_sourceMapError && error instanceof Error) {
+    _sourceMapError(error);
+  }
+}

package/src/server/dev-warnings.ts

@@ -25,7 +25,6 @@ export const WarningId = {
   REDIRECT_IN_SUSPENSE: 'REDIRECT_IN_SUSPENSE',
   REDIRECT_IN_ACCESS: 'REDIRECT_IN_ACCESS',
   STATIC_REQUEST_API: 'STATIC_REQUEST_API',
-  CACHE_REQUEST_PROPS: 'CACHE_REQUEST_PROPS',
   SLOW_SLOT_NO_SUSPENSE: 'SLOW_SLOT_NO_SUSPENSE',
 } as const;
 
@@ -111,7 +110,7 @@ export function warnSuspenseWrappingChildren(layoutFile: string): void {
     'warn',
     `Layout at ${layoutFile} wraps {children} in <Suspense>. ` +
       'This prevents child pages from setting HTTP status codes. ' +
-      'Use useNavigationPending() for loading states instead.'
+      'Use usePendingNavigation() for loading states instead.'
   );
 }
 
@@ -179,7 +178,7 @@ export function warnRedirectInAccess(accessFile: string, line?: number): void {
 }
 
 /**
- * Warn when cookies() or headers() is called during a static build.
+ * Warn when getCookies() or getHeaders() is called during a static build.
  *
  * In output: 'static' mode, there is no per-request context — these APIs
  * read build-time values only. This is almost always a mistake.
@@ -197,33 +196,8 @@ export function warnStaticRequestApi(api: 'cookies' | 'headers', file: string):
   );
 }
 
-/**
- * Warn when a "use cache" component receives request-specific props.
- *
- * Cached components should not depend on per-request data — a userId or
- * sessionId in the props means the cache will either be ineffective
- * (key per user) or dangerous (serve one user's data to another).
- *
- * @param componentName - Name of the cached component
- * @param propName - Name of the suspicious prop
- * @param file - Relative path to the component file
- * @param line - Line number
- */
-export function warnCacheRequestProps(
-  componentName: string,
-  propName: string,
-  file: string,
-  line?: number
-): void {
-  const location = line ? `${file}:${line}` : file;
-  emitOnce(
-    WarningId.CACHE_REQUEST_PROPS,
-    `${componentName}:${propName}:${location}`,
-    'warn',
-    `Cached component ${componentName} receives prop "${propName}" which appears request-specific. ` +
-      'Cached components should not depend on per-request data.'
-  );
-}
+// NOTE: warnCacheRequestProps removed — 'use cache' directive is a future feature.
+// See design/06-caching.md.
 
 /**
  * Warn when a parallel slot resolves slowly without a <Suspense> wrapper.
@@ -245,25 +219,6 @@ export function warnSlowSlotWithoutSuspense(slotName: string, durationMs: number
   );
 }
 
-// ─── Legacy aliases ─────────────────────────────────────────────────────────
-
-/** @deprecated Use warnStaticRequestApi instead */
-export const warnDynamicApiInStaticBuild = warnStaticRequestApi;
-
-/** @deprecated Use warnRedirectInAccess instead */
-export function warnRedirectInSlotAccess(slotName: string): void {
-  warnRedirectInAccess(`${slotName}/access.ts`);
-}
-
-/** @deprecated Use warnDenyInSuspense / warnRedirectInSuspense instead */
-export function warnDenyAfterFlush(signal: 'deny' | 'redirect'): void {
-  if (signal === 'deny') {
-    warnDenyInSuspense('unknown');
-  } else {
-    warnRedirectInSuspense('unknown');
-  }
-}
-
 // ─── Testing ────────────────────────────────────────────────────────────────
 
 /**