@timber-js/app 0.1.0 → 0.1.2

package/src/server/dev-warnings.ts

@@ -0,0 +1,282 @@
+/**
+ * Dev-mode warnings for common timber.js misuse patterns.
+ *
+ * These fire in development only and are stripped from production builds.
+ * Each warning targets a specific misuse identified during design review.
+ *
+ * Warnings are deduplicated by warningId:filePath:line so the same warning
+ * is only emitted once per dev session (per unique source location).
+ *
+ * Warnings are written to stderr and, when a Vite dev server is available,
+ * forwarded to the browser console via Vite's WebSocket.
+ *
+ * See design/21-dev-server.md §"Dev-Mode Warnings"
+ * See design/11-platform.md §"Dev Mode"
+ */
+
+import type { ViteDevServer } from 'vite';
+
+// ─── Warning IDs ───────────────────────────────────────────────────────────
+
+export const WarningId = {
+  SUSPENSE_WRAPS_CHILDREN: 'SUSPENSE_WRAPS_CHILDREN',
+  DENY_IN_SUSPENSE: 'DENY_IN_SUSPENSE',
+  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;
+
+export type WarningId = (typeof WarningId)[keyof typeof WarningId];
+
+// ─── Configuration ──────────────────────────────────────────────────────────
+
+/** Configuration for dev warning behavior. */
+export interface DevWarningConfig {
+  /** Threshold in ms for "slow slot" warnings. Default: 200. */
+  slowSlotThresholdMs?: number;
+}
+
+// ─── Deduplication & Server ─────────────────────────────────────────────────
+
+const _emitted = new Set<string>();
+
+/** Vite dev server for forwarding warnings to browser console. */
+let _viteServer: ViteDevServer | null = null;
+
+/**
+ * Register the Vite dev server for browser console forwarding.
+ * Called by timber-dev-server during configureServer.
+ */
+export function setViteServer(server: ViteDevServer | null): void {
+  _viteServer = server;
+}
+
+function isDev(): boolean {
+  return process.env.NODE_ENV !== 'production';
+}
+
+/**
+ * Emit a warning only once per dedup key.
+ *
+ * Writes to stderr and forwards to browser console via Vite WebSocket.
+ * Returns true if emitted (not deduplicated).
+ */
+function emitOnce(
+  warningId: WarningId,
+  location: string,
+  level: 'warn' | 'error',
+  message: string
+): boolean {
+  if (!isDev()) return false;
+
+  const dedupKey = `${warningId}:${location}`;
+  if (_emitted.has(dedupKey)) return false;
+  _emitted.add(dedupKey);
+
+  // Write to stderr
+  const prefix = level === 'error' ? '\x1b[31m[timber]\x1b[0m' : '\x1b[33m[timber]\x1b[0m';
+  process.stderr.write(`${prefix} ${message}\n`);
+
+  // Forward to browser console via Vite WebSocket
+  if (_viteServer?.hot) {
+    _viteServer.hot.send('timber:dev-warning', {
+      warningId,
+      level,
+      message: `[timber] ${message}`,
+    });
+  }
+
+  return true;
+}
+
+// ─── Warning Functions ──────────────────────────────────────────────────────
+
+/**
+ * Warn when a layout wraps {children} in <Suspense>.
+ *
+ * This defers the page content — the primary resource — behind a fallback.
+ * The page's data fetches won't affect the HTTP status code because they
+ * resolve after onShellReady. If the page calls deny(404), the status code
+ * is already committed as 200.
+ *
+ * @param layoutFile - Relative path to the layout file (e.g., "app/(dashboard)/layout.tsx")
+ */
+export function warnSuspenseWrappingChildren(layoutFile: string): void {
+  emitOnce(
+    WarningId.SUSPENSE_WRAPS_CHILDREN,
+    layoutFile,
+    'warn',
+    `Layout at ${layoutFile} wraps {children} in <Suspense>. ` +
+      'This prevents child pages from setting HTTP status codes. ' +
+      'Use useNavigationPending() for loading states instead.'
+  );
+}
+
+/**
+ * Warn when deny() is called inside a Suspense boundary.
+ *
+ * After the shell has flushed and the status code is committed, deny()
+ * cannot change the HTTP response. The signal will be caught by the nearest
+ * error boundary instead of producing a correct status code.
+ *
+ * @param file - Relative path to the file
+ * @param line - Line number where deny() was called
+ */
+export function warnDenyInSuspense(file: string, line?: number): void {
+  const location = line ? `${file}:${line}` : file;
+  emitOnce(
+    WarningId.DENY_IN_SUSPENSE,
+    location,
+    'error',
+    `deny() called inside <Suspense> at ${location}. ` +
+      'The HTTP status is already committed — this will trigger an error boundary with a 200 status. ' +
+      'Move deny() outside <Suspense> for correct HTTP semantics.'
+  );
+}
+
+/**
+ * Warn when redirect() is called inside a Suspense boundary.
+ *
+ * This will perform a client-side navigation instead of an HTTP redirect.
+ *
+ * @param file - Relative path to the file
+ * @param line - Line number where redirect() was called
+ */
+export function warnRedirectInSuspense(file: string, line?: number): void {
+  const location = line ? `${file}:${line}` : file;
+  emitOnce(
+    WarningId.REDIRECT_IN_SUSPENSE,
+    location,
+    'error',
+    `redirect() called inside <Suspense> at ${location}. ` +
+      'This will perform a client-side navigation instead of an HTTP redirect.'
+  );
+}
+
+/**
+ * Warn when redirect() is called in a slot's access.ts.
+ *
+ * Slots use deny() for graceful degradation. Redirecting from a slot would
+ * redirect the entire page, breaking the contract that slot failure is
+ * isolated to the slot.
+ *
+ * @param accessFile - Relative path to the access.ts file
+ * @param line - Line number where redirect() was called
+ */
+export function warnRedirectInAccess(accessFile: string, line?: number): void {
+  const location = line ? `${accessFile}:${line}` : accessFile;
+  emitOnce(
+    WarningId.REDIRECT_IN_ACCESS,
+    location,
+    'error',
+    `redirect() called in access.ts at ${location}. ` +
+      'Only deny() is valid in slot access checks. ' +
+      'Use deny() to block access or move redirect() to middleware.ts.'
+  );
+}
+
+/**
+ * Warn when cookies() or headers() 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.
+ *
+ * @param api - The dynamic API name ("cookies" or "headers")
+ * @param file - Relative path to the file calling the API
+ */
+export function warnStaticRequestApi(api: 'cookies' | 'headers', file: string): void {
+  emitOnce(
+    WarningId.STATIC_REQUEST_API,
+    `${api}:${file}`,
+    'error',
+    `${api}() called during static generation of ${file}. ` +
+      'Dynamic request APIs are not available during prerendering.'
+  );
+}
+
+/**
+ * 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.'
+  );
+}
+
+/**
+ * Warn when a parallel slot resolves slowly without a <Suspense> wrapper.
+ *
+ * A slow slot without Suspense blocks onShellReady — and therefore the
+ * status code commit — for the entire page. Wrapping it in <Suspense>
+ * lets the shell flush without waiting for the slot.
+ *
+ * @param slotName - The slot name (e.g., "@admin")
+ * @param durationMs - How long the slot took to resolve
+ */
+export function warnSlowSlotWithoutSuspense(slotName: string, durationMs: number): void {
+  emitOnce(
+    WarningId.SLOW_SLOT_NO_SUSPENSE,
+    slotName,
+    'warn',
+    `Slot ${slotName} resolved in ${durationMs}ms and is not wrapped in <Suspense>. ` +
+      'Consider wrapping to avoid blocking the flush.'
+  );
+}
+
+// ─── 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 ────────────────────────────────────────────────────────────────
+
+/**
+ * Reset emitted warnings. For testing only.
+ * @internal
+ */
+export function _resetWarnings(): void {
+  _emitted.clear();
+}
+
+/**
+ * Get the set of emitted dedup keys. For testing only.
+ * @internal
+ */
+export function _getEmitted(): ReadonlySet<string> {
+  return _emitted;
+}

package/src/server/early-hints-sender.ts

@@ -0,0 +1,55 @@
+/**
+ * Per-request 103 Early Hints sender — ALS bridge for platform adapters.
+ *
+ * The pipeline collects Link headers for CSS, fonts, and JS chunks at
+ * route-match time. On platforms that support it (Node.js v18.11+, Bun),
+ * the adapter can send these as a 103 Early Hints interim response before
+ * the final response is ready.
+ *
+ * This module provides an ALS-based bridge: the generated entry point
+ * (e.g., the Nitro entry) wraps the handler with `runWithEarlyHintsSender`,
+ * binding a per-request sender function. The pipeline calls
+ * `sendEarlyHints103()` to fire the 103 if a sender is available.
+ *
+ * On platforms where 103 is handled at the CDN level (e.g., Cloudflare
+ * converts Link headers into 103 automatically), no sender is installed
+ * and `sendEarlyHints103()` is a no-op.
+ *
+ * Design doc: 02-rendering-pipeline.md §"Early Hints (103)"
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+/** Function that sends Link header values as a 103 Early Hints response. */
+export type EarlyHintsSenderFn = (links: string[]) => void;
+
+const earlyHintsSenderAls = new AsyncLocalStorage<EarlyHintsSenderFn>();
+
+/**
+ * Run a function with a per-request early hints sender installed.
+ *
+ * Called by generated entry points (e.g., Nitro node-server/bun) to
+ * bind the platform's writeEarlyHints capability for the request duration.
+ */
+export function runWithEarlyHintsSender<T>(sender: EarlyHintsSenderFn, fn: () => T): T {
+  return earlyHintsSenderAls.run(sender, fn);
+}
+
+/**
+ * Send collected Link headers as a 103 Early Hints response.
+ *
+ * No-op if no sender is installed for the current request (e.g., on
+ * Cloudflare where the CDN handles 103 automatically, or in dev mode).
+ *
+ * Non-fatal: errors from the sender are caught and silently ignored.
+ */
+export function sendEarlyHints103(links: string[]): void {
+  if (!links.length) return;
+  const sender = earlyHintsSenderAls.getStore();
+  if (!sender) return;
+  try {
+    sender(links);
+  } catch {
+    // Sending 103 is best-effort — failure never blocks the request.
+  }
+}

package/src/server/early-hints.ts

@@ -0,0 +1,142 @@
+/**
+ * 103 Early Hints utilities.
+ *
+ * Early Hints are sent before the final response to let the browser
+ * start fetching critical resources (CSS, fonts, JS) while the server
+ * is still rendering.
+ *
+ * The framework collects hints from two sources:
+ * 1. Build manifest — CSS, fonts, and JS chunks known at route-match time
+ * 2. ctx.earlyHints() — explicit hints added by middleware or route handlers
+ *
+ * Both are emitted as Link headers. Cloudflare CDN automatically converts
+ * Link headers into 103 Early Hints responses.
+ *
+ * Design docs: 02-rendering-pipeline.md §"Early Hints (103)"
+ */
+
+import {
+  collectRouteCss,
+  collectRouteFonts,
+  collectRouteModulepreloads,
+} from './build-manifest.js';
+import type { BuildManifest } from './build-manifest.js';
+
+/** Minimal segment shape needed for early hint collection. */
+interface SegmentWithFiles {
+  layout?: { filePath: string };
+  page?: { filePath: string };
+}
+
+// ─── EarlyHint type ───────────────────────────────────────────────────────
+
+/**
+ * A single Link header hint for 103 Early Hints.
+ *
+ * ```ts
+ * ctx.earlyHints([
+ *   { href: '/styles/critical.css', rel: 'preload', as: 'style' },
+ *   { href: 'https://fonts.googleapis.com', rel: 'preconnect' },
+ * ])
+ * ```
+ */
+export interface EarlyHint {
+  /** The resource URL (absolute or root-relative). */
+  href: string;
+  /** Link relation — `preload`, `modulepreload`, or `preconnect`. */
+  rel: 'preload' | 'modulepreload' | 'preconnect';
+  /** Resource type for `preload` hints (omit for `modulepreload` / `preconnect`). */
+  as?: 'style' | 'script' | 'font' | 'image' | 'fetch' | 'document';
+  /** Crossorigin attribute — required for font preloads per spec. */
+  crossOrigin?: 'anonymous' | 'use-credentials';
+  /** Fetch priority hint — `high`, `low`, or `auto`. */
+  fetchPriority?: 'high' | 'low' | 'auto';
+}
+
+// ─── formatLinkHeader ─────────────────────────────────────────────────────
+
+/**
+ * Format a single EarlyHint as a Link header value.
+ *
+ * Examples:
+ *   `</styles/root.css>; rel=preload; as=style`
+ *   `</fonts/inter.woff2>; rel=preload; as=font; crossorigin=anonymous`
+ *   `</_timber/client.js>; rel=modulepreload`
+ *   `<https://fonts.googleapis.com>; rel=preconnect`
+ */
+export function formatLinkHeader(hint: EarlyHint): string {
+  let value = `<${hint.href}>; rel=${hint.rel}`;
+  if (hint.as !== undefined) value += `; as=${hint.as}`;
+  if (hint.crossOrigin !== undefined) value += `; crossorigin=${hint.crossOrigin}`;
+  if (hint.fetchPriority !== undefined) value += `; fetchpriority=${hint.fetchPriority}`;
+  return value;
+}
+
+// ─── collectEarlyHintHeaders ──────────────────────────────────────────────
+
+/** Options for early hint collection. */
+export interface EarlyHintOptions {
+  /** Skip JS modulepreload hints (e.g. when client JavaScript is disabled). */
+  skipJs?: boolean;
+}
+
+/**
+ * Collect all Link header strings for a matched route's segment chain.
+ *
+ * Walks the build manifest to emit hints for:
+ * - CSS stylesheets (rel=preload; as=style)
+ * - Font assets (rel=preload; as=font; crossorigin)
+ * - JS modulepreload hints (rel=modulepreload) — unless skipJs is set
+ *
+ * Also emits global CSS from the `_global` manifest key. Route files
+ * are server components that don't appear in the client bundle, so
+ * per-route CSS keying doesn't work with the RSC plugin. The `_global`
+ * key contains all CSS assets from the client build — fine for early
+ * hints since they're just prefetch signals.
+ *
+ * Returns formatted Link header strings, deduplicated, root → leaf order.
+ * Returns an empty array in dev mode (manifest is empty).
+ */
+export function collectEarlyHintHeaders(
+  segments: SegmentWithFiles[],
+  manifest: BuildManifest,
+  options?: EarlyHintOptions
+): string[] {
+  const result: string[] = [];
+  const seen = new Set<string>();
+
+  const add = (header: string) => {
+    if (!seen.has(header)) {
+      seen.add(header);
+      result.push(header);
+    }
+  };
+
+  // Per-route CSS — rel=preload; as=style
+  for (const url of collectRouteCss(segments, manifest)) {
+    add(formatLinkHeader({ href: url, rel: 'preload', as: 'style' }));
+  }
+
+  // Global CSS — all CSS assets from the client bundle.
+  // Covers CSS that the RSC plugin injects via data-rsc-css-href,
+  // which isn't keyed to route segments in our manifest.
+  for (const url of manifest.css['_global'] ?? []) {
+    add(formatLinkHeader({ href: url, rel: 'preload', as: 'style' }));
+  }
+
+  // Fonts — rel=preload; as=font; crossorigin (crossorigin required per spec)
+  for (const font of collectRouteFonts(segments, manifest)) {
+    add(
+      formatLinkHeader({ href: font.href, rel: 'preload', as: 'font', crossOrigin: 'anonymous' })
+    );
+  }
+
+  // JS chunks — rel=modulepreload (skip when client JS is disabled)
+  if (!options?.skipJs) {
+    for (const url of collectRouteModulepreloads(segments, manifest)) {
+      add(formatLinkHeader({ href: url, rel: 'modulepreload' }));
+    }
+  }
+
+  return result;
+}

package/src/server/error-boundary-wrapper.ts

@@ -0,0 +1,69 @@
+/**
+ * Error boundary wrapper — wraps a React element in error boundaries from a route segment.
+ *
+ * Extracted to allow reuse by both rsc-entry.ts and route-element-builder.ts.
+ * See design/10-error-handling.md.
+ */
+
+import { TimberErrorBoundary } from '#/client/error-boundary.js';
+import type { ManifestSegmentNode } from './route-matcher.js';
+
+/**
+ * Wrap an element in error boundaries defined by a route segment.
+ *
+ * Processing order (innermost to outermost):
+ * 1. Specific status files (e.g., 404.tsx, 500.tsx) — highest priority at runtime
+ * 2. Category catch-alls (4xx.tsx, 5xx.tsx)
+ * 3. error.tsx — catches anything not matched by status files
+ */
+export async function wrapSegmentWithErrorBoundaries(
+  segment: ManifestSegmentNode,
+  element: React.ReactElement,
+  h: (...args: unknown[]) => React.ReactElement
+): Promise<React.ReactElement> {
+  // Specific status files (innermost — highest priority at runtime)
+  if (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 file.load()) as Record<string, unknown>;
+          if (mod.default) {
+            element = h(TimberErrorBoundary, {
+              fallbackComponent: mod.default,
+              status,
+              children: element,
+            });
+          }
+        }
+      }
+    }
+
+    // Category catch-alls (4xx.tsx, 5xx.tsx)
+    for (const [key, file] of Object.entries(segment.statusFiles)) {
+      if (key === '4xx' || key === '5xx') {
+        const mod = (await file.load()) as Record<string, unknown>;
+        if (mod.default) {
+          element = h(TimberErrorBoundary, {
+            fallbackComponent: mod.default,
+            status: key === '4xx' ? 400 : 500,
+            children: element,
+          });
+        }
+      }
+    }
+  }
+
+  // error.tsx (outermost — catches anything not matched by status files)
+  if (segment.error) {
+    const mod = (await segment.error.load()) as Record<string, unknown>;
+    if (mod.default) {
+      element = h(TimberErrorBoundary, {
+        fallbackComponent: mod.default,
+        children: element,
+      });
+    }
+  }
+
+  return element;
+}