@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.210

package/src/dev-tools/404-page.ts

@@ -0,0 +1,286 @@
+/**
+ * Dev 404 page — self-contained HTML page for dev-mode route misses.
+ *
+ * When no route matches and the user has no 404.tsx, this page shows:
+ * - The requested path
+ * - All registered routes in the app
+ * - "Did you mean?" suggestions based on string similarity
+ * - Setup instructions for new projects with no routes
+ *
+ * Dev-only: this module is only imported in dev mode. It is never
+ * included in production builds.
+ *
+ * Design doc: 21-dev-server.md, 07-routing.md
+ */
+
+import type { SegmentNode } from '../routing/types.ts';
+import { collectLeafRoutes } from '../routing/walkers.ts';
+import { escapeHtml } from '../server/utils/escape-html.ts';
+import { renderDevPageShell, type DevErrorHmrOptions } from './dev-page-shell.ts';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+interface RouteInfo {
+  /** URL path pattern (e.g., "/dashboard/[id]") */
+  path: string;
+  /** Whether this is a page route or API route handler */
+  type: 'page' | 'route';
+}
+
+// ─── Route Collection ───────────────────────────────────────────────────────
+
+/**
+ * Collect all routable paths from a route tree (build-time scanner output
+ * or runtime route manifest).
+ *
+ * Wraps the shared `collectLeafRoutes` walker (TIM-848). Includes parallel
+ * slots so the dev 404 page can list slot pages too — they aren't
+ * separately addressable, but they're still useful to know about when
+ * debugging a missing route.
+ */
+export function collectRoutes<TFile>(root: SegmentNode<TFile>): RouteInfo[] {
+  const leaves = collectLeafRoutes(root, { includeSlots: true });
+  const routes: RouteInfo[] = [];
+  for (const leaf of leaves) {
+    if (leaf.page) routes.push({ path: leaf.urlPath, type: 'page' });
+    if (leaf.route) routes.push({ path: leaf.urlPath, type: 'route' });
+  }
+  return routes;
+}
+
+// ─── String Similarity ──────────────────────────────────────────────────────
+
+/**
+ * Compute Levenshtein distance between two strings.
+ *
+ * Used for "did you mean?" suggestions. Simple O(n*m) implementation
+ * — fine for short URL paths.
+ */
+function levenshtein(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+
+  // Optimization: use single-row DP
+  const row = Array.from({ length: n + 1 }, (_, i) => i);
+
+  for (let i = 1; i <= m; i++) {
+    let prev = i;
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      const val = Math.min(
+        row[j]! + 1, // deletion
+        prev + 1, // insertion
+        row[j - 1]! + cost // substitution
+      );
+      row[j - 1] = prev;
+      prev = val;
+    }
+    row[n] = prev;
+  }
+
+  return row[n]!;
+}
+
+/**
+ * Find routes similar to the requested path.
+ *
+ * Returns up to 3 suggestions, sorted by similarity.
+ * Only includes routes with distance ≤ 40% of the longer string.
+ */
+export function findSimilarRoutes(requestedPath: string, routes: RouteInfo[]): RouteInfo[] {
+  if (routes.length === 0) return [];
+
+  const scored = routes
+    .map((route) => ({
+      route,
+      distance: levenshtein(requestedPath.toLowerCase(), route.path.toLowerCase()),
+    }))
+    .filter((s) => {
+      const maxLen = Math.max(requestedPath.length, s.route.path.length);
+      return s.distance <= maxLen * 0.4;
+    })
+    .sort((a, b) => a.distance - b.distance);
+
+  return scored.slice(0, 3).map((s) => s.route);
+}
+
+// ─── HTML Escaping ──────────────────────────────────────────────────────────
+
+const esc = escapeHtml;
+
+// ─── HTML Generation ────────────────────────────────────────────────────────
+
+/**
+ * Generate a dev-mode 404 page with route listing and suggestions.
+ *
+ * Returns an HTML string for a self-contained error page. `hmrOptions`
+ * carries the resolved Vite HMR connection options (including the WS token
+ * Vite 8 requires on browser upgrades) so the auto-reload script can
+ * actually connect (TIM-1067, B33).
+ */
+export function generateDev404Page(
+  requestedPath: string,
+  routes: RouteInfo[],
+  hmrOptions?: DevErrorHmrOptions
+): string {
+  const suggestions = findSimilarRoutes(requestedPath, routes);
+  const isEmpty = routes.length === 0;
+
+  const bodyHtml = `<header class="header">
+      <div class="badge">404 Not Found</div>
+      <h1 class="message">No route matches <code>${esc(requestedPath)}</code></h1>
+    </header>
+
+    ${
+      isEmpty
+        ? `<div class="welcome">
+        <h2>Welcome to timber.js</h2>
+        <p>Your app has no pages yet. Create your first page to get started:</p>
+        <div class="code-block">
+          <div class="code-header">app/page.tsx</div>
+          <pre><code>export default function Home() {
+  return &lt;h1&gt;Hello, timber.js!&lt;/h1&gt;;
+}</code></pre>
+        </div>
+        <p class="hint">Save the file and this page will reload automatically.</p>
+      </div>`
+        : ''
+    }
+
+    ${
+      suggestions.length > 0
+        ? `<div class="section">
+        <div class="section-header">Did you mean?</div>
+        <ul class="route-list suggestions">
+          ${suggestions.map((r) => `<li><a href="${esc(r.path)}">${esc(r.path)}</a> <span class="route-type">${r.type}</span></li>`).join('\n          ')}
+        </ul>
+      </div>`
+        : ''
+    }
+
+    ${
+      routes.length > 0
+        ? `<div class="section">
+        <div class="section-header">Available Routes (${routes.length})</div>
+        <ul class="route-list">
+          ${routes.map((r) => `<li><a href="${esc(r.path)}">${esc(r.path)}</a> <span class="route-type">${r.type}</span></li>`).join('\n          ')}
+        </ul>
+      </div>`
+        : ''
+    }`;
+
+  return renderDevPageShell({
+    title: `404 — ${requestedPath} | timber.js`,
+    extraCss: NOT_FOUND_CSS,
+    bodyHtml,
+    footerHint: 'Add or edit routes and this page will reload automatically.',
+    hmrOptions,
+  });
+}
+
+// ─── Page-Specific CSS ──────────────────────────────────────────────────────
+
+const NOT_FOUND_CSS = `
+  :root {
+    --badge-bg: #fefce8;
+    --badge-fg: #854d0e;
+    --badge-border: #fde68a;
+    --route-type-bg: #e0f2fe;
+    --route-type-fg: #0369a1;
+  }
+
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --badge-bg: #422006;
+      --badge-fg: #fde68a;
+      --badge-border: #854d0e;
+      --route-type-bg: #0c4a6e;
+      --route-type-fg: #bae6fd;
+    }
+  }
+
+  .message code {
+    font-family: var(--code-font);
+    background: var(--code-bg);
+    padding: 0.125rem 0.375rem;
+    border-radius: 0.25rem;
+    font-size: 1.125rem;
+  }
+
+  .welcome {
+    margin-bottom: 1.5rem;
+    padding: 1.5rem;
+    border: 1px solid var(--border);
+    border-radius: 0.5rem;
+    background: var(--source-bg);
+  }
+
+  .welcome h2 {
+    font-size: 1.125rem;
+    margin-bottom: 0.5rem;
+  }
+
+  .welcome p { color: var(--fg-dim); margin-bottom: 1rem; }
+
+  .code-block {
+    border: 1px solid var(--border);
+    border-radius: 0.5rem;
+    overflow: hidden;
+    margin-bottom: 1rem;
+  }
+
+  .code-header {
+    font-size: 0.75rem;
+    font-weight: 600;
+    padding: 0.5rem 0.75rem;
+    background: var(--code-bg);
+    border-bottom: 1px solid var(--border);
+    color: var(--fg-dim);
+    font-family: var(--code-font);
+  }
+
+  .code-block pre {
+    padding: 0.75rem;
+    font-family: var(--code-font);
+    font-size: 0.8125rem;
+    line-height: 1.7;
+    overflow-x: auto;
+    margin: 0;
+  }
+
+  .route-list {
+    list-style: none;
+    padding: 0.5rem 0;
+  }
+
+  .route-list li {
+    padding: 0.375rem 0.75rem;
+    font-family: var(--code-font);
+    font-size: 0.8125rem;
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+  }
+
+  .route-list li:hover { background: var(--source-bg); }
+
+  .route-list a {
+    color: var(--link);
+    text-decoration: none;
+  }
+
+  .route-list a:hover { text-decoration: underline; }
+
+  .route-type {
+    font-size: 0.625rem;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    padding: 0.125rem 0.375rem;
+    border-radius: 0.25rem;
+    background: var(--route-type-bg);
+    color: var(--route-type-fg);
+  }
+
+  .suggestions { background: var(--source-bg); }
+`;

package/src/dev-tools/browser-logs.ts

@@ -0,0 +1,55 @@
+/**
+ * Browser log forwarding — maps timber's devBrowserLogs config to Vite 8's
+ * server.forwardConsole option.
+ *
+ * Vite 8 ships built-in browser→terminal console forwarding via
+ * server.forwardConsole, which patches console methods in /@vite/client
+ * and prints forwarded output server-side. This replaces timber's custom
+ * client-side interception script and HMR WebSocket transport.
+ *
+ * Client error forwarding (overlay echo, digest filtering, componentStack)
+ * remains in browser-dev.ts — Vite's forwardConsole only logs to terminal
+ * and has no client-side filter hook. See TIM-1152.
+ *
+ * See design/21-dev-server.md §"Browser Log Forwarding"
+ */
+
+// ─── Types ───────────────────────────────────────────────────────────────
+
+/** Log levels forwarded from the browser. */
+export type BrowserLogLevel = 'error' | 'warn' | 'info';
+
+/** Configuration value for devBrowserLogs in timber.config.ts. */
+export type DevBrowserLogsConfig = BrowserLogLevel | 'none' | undefined;
+
+// ─── Vite Config Mapping ─────────────────────────────────────────────────
+
+/**
+ * Map timber's devBrowserLogs threshold to Vite 8's server.forwardConsole.
+ *
+ * Vite defaults forwardConsole OFF for non-agent dev; timber enables it
+ * based on the configured threshold (default: 'warn'). The threshold acts
+ * as a minimum severity — 'warn' forwards errors + warnings, 'info'
+ * forwards everything, 'error' forwards only errors, 'none' disables.
+ *
+ * Vite's unhandledErrors is explicitly disabled — timber's own
+ * setupClientErrorForwarding (browser-dev.ts) already catches window
+ * error/unhandledrejection, filters framework control-flow signals
+ * (redirect/deny digests) and page-unload aborts (TIM-838), and
+ * echoes errors to the Vite overlay. Enabling Vite's unhandledErrors
+ * would duplicate terminal output for normal errors and reintroduce
+ * unfiltered noise for framework signals.
+ */
+export function resolveForwardConsole(
+  threshold: DevBrowserLogsConfig
+): boolean | { unhandledErrors: boolean; logLevels: string[] } {
+  const resolved = threshold ?? 'warn';
+  if (resolved === 'none') return false;
+
+  const logLevels: string[] = [];
+  if (resolved === 'info') logLevels.push('info', 'warn', 'error');
+  else if (resolved === 'warn') logLevels.push('warn', 'error');
+  else logLevels.push('error');
+
+  return { unhandledErrors: false, logLevels };
+}

package/src/dev-tools/dev-page-shell.ts

@@ -0,0 +1,278 @@
+/**
+ * Shared scaffold for dev-mode HTML pages (dev error page, dev 404 page).
+ *
+ * Both pages are self-contained HTML documents served when the normal
+ * render pipeline can't produce a page. They share:
+ * - The document scaffold (head, container, footer)
+ * - Base CSS (layout, light/dark variables, common components)
+ * - The HMR auto-reload script that watches Vite's WebSocket and reloads
+ *   when the developer fixes the error / adds the missing route
+ *
+ * Dev-only: this module is only imported by dev-mode code paths. It is
+ * never included in production builds.
+ *
+ * Design doc: 21-dev-server.md §"Error Overlay", §"Dev 404 Page"
+ */
+
+import { escapeHtml } from '../server/utils/escape-html.ts';
+
+// ─── HMR Options ────────────────────────────────────────────────────────────
+
+/**
+ * HMR connection options for the dev page auto-reload WebSocket.
+ * Derived from Vite's resolved server config so the page can connect
+ * to the correct HMR endpoint (TIM-789).
+ */
+export interface DevErrorHmrOptions {
+  protocol?: string;
+  host?: string;
+  port?: number;
+  path?: string;
+  token?: string;
+}
+
+/**
+ * Hooks the dev server hands the RSC environment, which cannot read the
+ * Vite server itself (separate module graph). The RSC entry exports
+ * `setDevHooks()`; the dev server calls it after importing the entry.
+ *
+ * Declared here, not in the RSC entry, so the dev-server plugin can name
+ * the type without pulling the RSC entry into its type graph.
+ */
+export interface DevHooks {
+  /** Forwards a pipeline error to the browser error overlay. */
+  onPipelineError?: (error: Error, phase: string) => void;
+  /**
+   * The resolved HMR endpoint for the auto-reload WebSocket on the dev 404
+   * page and the fallback error page (TIM-1067).
+   */
+  hmrOptions?: DevErrorHmrOptions;
+}
+
+/**
+ * Extract HMR connection options from a Vite resolved config.
+ * Used by the dev server to pass HMR config to the dev page generators
+ * so the auto-reload WebSocket connects to the correct endpoint.
+ */
+export function extractHmrOptions(config: {
+  server?: {
+    hmr?:
+      | { protocol?: string; host?: string; port?: number; clientPort?: number; path?: string }
+      | boolean;
+  };
+  webSocketToken?: string;
+}): DevErrorHmrOptions | undefined {
+  const hmr = config.server?.hmr;
+  if (hmr === false) return undefined;
+  const hmrOpts = typeof hmr === 'object' ? hmr : {};
+  const opts: DevErrorHmrOptions = {
+    protocol: hmrOpts.protocol,
+    host: hmrOpts.host,
+    port: hmrOpts.clientPort || hmrOpts.port,
+    path: hmrOpts.path,
+    token: config.webSocketToken,
+  };
+  // If no HMR fields were explicitly configured, return undefined so the
+  // reload script derives everything from the browser's location, which
+  // correctly includes the current port (TIM-805).
+  if (!opts.protocol && !opts.host && !opts.port && !opts.path && !opts.token) {
+    return undefined;
+  }
+  return opts;
+}
+
+// ─── Auto-Reload Script ─────────────────────────────────────────────────────
+
+/**
+ * Build the inline auto-reload script for dev pages.
+ *
+ * The page is static HTML, not a Vite-managed module, so the normal HMR
+ * update flow can't reach it. Instead we connect to Vite's HMR WebSocket
+ * directly and reload on any update event.
+ *
+ * URL construction mirrors Vite's own client.mjs: explicitly configured
+ * values win, and the browser's location fills any gaps at runtime. This
+ * matters because Vite 8 requires a `?token=` on browser WS upgrades in
+ * every config — a config with only a token still needs the host and port
+ * from `location` (TIM-1067).
+ */
+export function buildReloadScript(hmrOptions?: DevErrorHmrOptions): string {
+  // `<` is escaped as a unicode escape so config text can never close the
+  // <script> block (same defense as escJsonForScript in error-page.ts, TIM-788).
+  const opts = JSON.stringify(hmrOptions ?? {}).replace(/</g, '\\u003c');
+  return `    (function() {
+      try {
+        var o = ${opts};
+        var protocol = o.protocol || (location.protocol === 'https:' ? 'wss' : 'ws');
+        var host = o.host || location.hostname;
+        var port = o.port || location.port;
+        var url = protocol + '://' + host + (port ? ':' + port : '') + (o.path || '')
+          + (o.token ? '?token=' + encodeURIComponent(o.token) : '');
+        var ws = new WebSocket(url, 'vite-hmr');
+        ws.addEventListener('message', function(e) {
+          try {
+            var data = JSON.parse(e.data);
+            if (data.type === 'full-reload' || data.type === 'update') {
+              location.reload();
+            }
+          } catch (ex) {}
+        });
+      } catch (ex) {}
+    })();`;
+}
+
+// ─── Page Shell ─────────────────────────────────────────────────────────────
+
+export interface DevPageShellOptions {
+  /** Page title — escaped by the shell. */
+  title: string;
+  /** Page-specific CSS appended after the shared base (badge colors, etc.). */
+  extraCss?: string;
+  /** Inner HTML of the container — must already be escaped by the caller. */
+  bodyHtml: string;
+  /** Hint text shown next to the timber logo in the footer. */
+  footerHint: string;
+  /** Additional inline script placed before the auto-reload script. */
+  extraScript?: string;
+  /** HMR connection options for the auto-reload WebSocket. */
+  hmrOptions?: DevErrorHmrOptions;
+}
+
+/**
+ * Render a self-contained dev page: scaffold + shared CSS + footer +
+ * HMR auto-reload script.
+ */
+export function renderDevPageShell(opts: DevPageShellOptions): string {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${escapeHtml(opts.title)}</title>
+  <style>${SHARED_CSS}${opts.extraCss ?? ''}</style>
+</head>
+<body>
+  <div class="container">
+    ${opts.bodyHtml}
+
+    <footer class="footer">
+      <span class="timber-logo">🪵 timber.js</span>
+      <span class="footer-hint">${opts.footerHint}</span>
+    </footer>
+  </div>
+
+  <script>
+${opts.extraScript ?? ''}
+    // Auto-reload when Vite HMR signals an update (file fixed, route added).
+${buildReloadScript(opts.hmrOptions)}
+  </script>
+</body>
+</html>`;
+}
+
+// ─── Shared CSS ─────────────────────────────────────────────────────────────
+
+/**
+ * Base CSS shared by all dev pages. Pages override the --badge-* variables
+ * (and add their own component styles) via `extraCss`.
+ */
+const SHARED_CSS = `
+  :root {
+    --bg: #fff;
+    --fg: #1a1a1a;
+    --fg-dim: #6b7280;
+    --border: #e5e7eb;
+    --source-bg: #fafafa;
+    --link: #2563eb;
+    --code-bg: #f3f4f6;
+    --btn-bg: #f3f4f6;
+    --btn-fg: #374151;
+    --btn-border: #d1d5db;
+    --code-font: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace;
+  }
+
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --bg: #0a0a0a;
+      --fg: #f5f5f5;
+      --fg-dim: #9ca3af;
+      --border: #27272a;
+      --source-bg: #18181b;
+      --link: #60a5fa;
+      --code-bg: #27272a;
+      --btn-bg: #27272a;
+      --btn-fg: #e5e7eb;
+      --btn-border: #3f3f46;
+    }
+  }
+
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+    background: var(--bg);
+    color: var(--fg);
+    line-height: 1.6;
+    padding: 2rem;
+  }
+
+  .container { max-width: 56rem; margin: 0 auto; }
+  .header { margin-bottom: 1.5rem; }
+
+  .badge {
+    display: inline-block;
+    font-size: 0.75rem;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    padding: 0.25rem 0.625rem;
+    border-radius: 0.375rem;
+    background: var(--badge-bg);
+    color: var(--badge-fg);
+    border: 1px solid var(--badge-border);
+    margin-bottom: 0.75rem;
+  }
+
+  .message {
+    font-size: 1.375rem;
+    font-weight: 600;
+    line-height: 1.3;
+    word-break: break-word;
+  }
+
+  .hint {
+    margin-top: 0.5rem;
+    color: var(--fg-dim);
+    font-size: 0.875rem;
+  }
+
+  .section {
+    margin-bottom: 1rem;
+    border: 1px solid var(--border);
+    border-radius: 0.5rem;
+    overflow: hidden;
+  }
+
+  .section-header {
+    font-size: 0.75rem;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    padding: 0.5rem 0.75rem;
+    background: var(--source-bg);
+    border-bottom: 1px solid var(--border);
+    color: var(--fg-dim);
+  }
+
+  .footer {
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+    padding-top: 1rem;
+    border-top: 1px solid var(--border);
+    font-size: 0.75rem;
+    color: var(--fg-dim);
+  }
+
+  .timber-logo { font-weight: 600; white-space: nowrap; }
+`;