@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.191

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

@@ -0,0 +1,331 @@
+/**
+ * Dev error page — self-contained HTML error page for dev server 500s.
+ *
+ * Generates a styled, self-contained HTML page when the RSC pipeline fails
+ * and the Vite error overlay can't fire (e.g., first page load before HMR
+ * WebSocket connects, RSC entry module crash, early pipeline errors).
+ *
+ * This is NOT a replacement for Vite's error overlay — it's the fallback
+ * for when the overlay's transport (WebSocket) isn't available yet.
+ *
+ * Dev-only: this module is only imported by dev-server.ts (apply: 'serve')
+ * and via dynamic import from fallback-error.ts in dev mode. It is never
+ * included in production builds.
+ *
+ * Design doc: 21-dev-server.md §"Error Overlay"
+ */
+
+import { readFileSync } from 'node:fs';
+import { extractComponentStack, parseFirstAppFrame, type ErrorPhase } from './overlay.js';
+import { classifyStack } from './stack-classifier.js';
+import { escapeHtml } from '../server/utils/escape-html.js';
+import { renderDevPageShell, type DevErrorHmrOptions } from './dev-page-shell.js';
+
+// ─── Phase Labels ───────────────────────────────────────────────────────────
+
+const PHASE_LABELS: Record<ErrorPhase, string> = {
+  'module-transform': 'Module Transform',
+  'proxy': 'Proxy',
+  'middleware': 'Middleware',
+  'access': 'Access Check',
+  'render': 'RSC Render',
+  'handler': 'Route Handler',
+};
+
+const PHASE_HINTS: Record<ErrorPhase, string> = {
+  'module-transform':
+    'This error occurred while Vite was transforming a module. Check for syntax errors or missing imports.',
+  'proxy': 'This error occurred in proxy.ts. Check your proxy configuration.',
+  'middleware':
+    'This error occurred in a middleware.ts file. Check the middleware function for unhandled exceptions.',
+  'access': 'This error occurred in an access.ts file. Check your access control logic.',
+  'render':
+    'This error occurred while rendering a server component. Check the component for runtime errors.',
+  'handler': 'This error occurred in a route handler (route.ts). Check the handler function.',
+};
+
+// ─── Source Context ─────────────────────────────────────────────────────────
+
+/**
+ * Try to read a few lines of source code around the error location.
+ * Returns null if the file can't be read (e.g., virtual modules).
+ *
+ * Uses a top-level `node:fs` import — this module is dev-server-only and
+ * Node-only. A bare `require()` here would throw in the ESM build and the
+ * code frame would silently never render (TIM-1067, B48).
+ */
+function readSourceContext(
+  filePath: string,
+  line: number,
+  contextLines = 3
+): { lines: Array<{ num: number; text: string; highlight: boolean }>; startLine: number } | null {
+  try {
+    const content = readFileSync(filePath, 'utf-8');
+    const allLines = content.split('\n');
+
+    const start = Math.max(0, line - 1 - contextLines);
+    const end = Math.min(allLines.length, line + contextLines);
+
+    return {
+      startLine: start + 1,
+      lines: allLines.slice(start, end).map((text: string, i: number) => ({
+        num: start + 1 + i,
+        text,
+        highlight: start + 1 + i === line,
+      })),
+    };
+  } catch (e) {
+    console.debug('[timber] source context extraction failed:', e instanceof Error ? e.message : e);
+    return null;
+  }
+}
+
+// HTML escaping provided by server/utils/escape-html.ts
+const esc = escapeHtml;
+
+/**
+ * Escape a JSON string for safe embedding in an HTML `<script>` block.
+ *
+ * `JSON.stringify` does not escape `</script>`, so error text containing
+ * that sequence breaks out of the script block — an XSS vector.
+ * We replace all `<` with the equivalent unicode escape, which is valid in
+ * JSON strings and prevents the HTML parser from seeing a closing
+ * `</script>` tag.
+ *
+ * Security: TIM-788
+ */
+function escJsonForScript(json: string): string {
+  return json.replace(/</g, '\\u003c');
+}
+
+// ─── HTML Generation ────────────────────────────────────────────────────────
+
+/**
+ * Generate a self-contained HTML error page for dev server 500 responses.
+ *
+ * The page includes:
+ * - Error message and phase label
+ * - Source code context around the first app frame (if readable)
+ * - Component stack (for React render errors)
+ * - Classified stack trace (app frames highlighted, internals collapsed)
+ * - Copy button for the full error
+ * - Dark/light mode via prefers-color-scheme
+ * - Auto-reconnect script that watches for Vite HMR and reloads
+ */
+export function generateDevErrorPage(
+  error: Error,
+  phase: ErrorPhase,
+  projectRoot: string,
+  hmrOptions?: DevErrorHmrOptions
+): string {
+  const message = error.message || 'Unknown error';
+  const phaseLabel = PHASE_LABELS[phase];
+  const phaseHint = PHASE_HINTS[phase];
+  const componentStack = extractComponentStack(error);
+  const loc = parseFirstAppFrame(error.stack ?? '', projectRoot);
+  const frames = error.stack ? classifyStack(error.stack, projectRoot) : [];
+  const appFrames = frames.filter((f) => f.type === 'app');
+  const internalFrameCount = frames.filter((f) => f.type !== 'app').length;
+
+  // Try to read source code context
+  let sourceContext: ReturnType<typeof readSourceContext> = null;
+  if (loc) {
+    sourceContext = readSourceContext(loc.file, loc.line);
+  }
+
+  // Relative path for display
+  const relPath = loc?.file.startsWith(projectRoot)
+    ? loc.file.slice(projectRoot.length + 1)
+    : loc?.file;
+
+  const bodyHtml = `<header class="header">
+      <div class="badge">${esc(phaseLabel)} Error</div>
+      <h1 class="message">${esc(message)}</h1>
+      ${phaseHint ? `<p class="hint">${esc(phaseHint)}</p>` : ''}
+    </header>
+
+    ${relPath ? `<div class="location">${esc(relPath)}${loc ? `:${loc.line}:${loc.column}` : ''}</div>` : ''}
+
+    ${
+      sourceContext
+        ? `<div class="source-context">
+        <div class="section-header">Source</div>
+        <pre class="source-code"><code>${sourceContext.lines
+          .map(
+            (l) =>
+              `<span class="source-line${l.highlight ? ' source-line-highlight' : ''}"` +
+              `><span class="line-num">${l.num}</span>${esc(l.text)}</span>`
+          )
+          .join('\n')}</code></pre>
+      </div>`
+        : ''
+    }
+
+    ${
+      componentStack
+        ? `<div class="section">
+        <div class="section-header">Component Stack</div>
+        <pre class="component-stack">${esc(componentStack.trim())}</pre>
+      </div>`
+        : ''
+    }
+
+    ${
+      appFrames.length > 0
+        ? `<div class="section">
+        <div class="section-header">Application Frames</div>
+        <pre class="stack">${appFrames.map((f) => esc(f.raw)).join('\n')}</pre>
+      </div>`
+        : ''
+    }
+
+    ${
+      internalFrameCount > 0
+        ? `<details class="section internal-frames">
+        <summary class="section-header clickable">${internalFrameCount} internal frame${internalFrameCount !== 1 ? 's' : ''}</summary>
+        <pre class="stack dimmed">${frames
+          .filter((f) => f.type !== 'app')
+          .map((f) => esc(f.raw))
+          .join('\n')}</pre>
+      </details>`
+        : ''
+    }
+
+    <div class="actions">
+      <button class="btn" onclick="copyError()">Copy Error</button>
+    </div>`;
+
+  const copyScript = `    function copyError() {
+      var text = ${escJsonForScript(
+        JSON.stringify(
+          `${phaseLabel} Error: ${message}\n\n` +
+            (relPath ? `File: ${relPath}${loc ? `:${loc.line}:${loc.column}` : ''}\n\n` : '') +
+            (componentStack ? `Component Stack:\n${componentStack.trim()}\n\n` : '') +
+            `Stack Trace:\n${error.stack ?? ''}`
+        )
+      )};
+      navigator.clipboard.writeText(text).then(function() {
+        var btn = document.querySelector('.btn');
+        if (btn) { btn.textContent = 'Copied!'; setTimeout(function() { btn.textContent = 'Copy Error'; }, 1500); }
+      });
+    }
+`;
+
+  return renderDevPageShell({
+    title: `Error — ${phaseLabel} | timber.js`,
+    extraCss: ERROR_CSS,
+    bodyHtml,
+    footerHint: 'Fix the error and save — the page will reload automatically via HMR.',
+    extraScript: copyScript,
+    hmrOptions,
+  });
+}
+
+// ─── Page-Specific CSS ──────────────────────────────────────────────────────
+
+const ERROR_CSS = `
+  :root {
+    --badge-bg: #fef2f2;
+    --badge-fg: #991b1b;
+    --badge-border: #fecaca;
+    --highlight-bg: #fef2f2;
+    --highlight-border: #ef4444;
+    --line-num: #9ca3af;
+  }
+
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --badge-bg: #450a0a;
+      --badge-fg: #fca5a5;
+      --badge-border: #7f1d1d;
+      --highlight-bg: #450a0a;
+      --highlight-border: #dc2626;
+      --line-num: #6b7280;
+    }
+  }
+
+  .location {
+    font-family: var(--code-font);
+    font-size: 0.8125rem;
+    color: var(--link);
+    margin-bottom: 1rem;
+    padding: 0.5rem 0.75rem;
+    background: var(--source-bg);
+    border-radius: 0.375rem;
+    border: 1px solid var(--border);
+  }
+
+  .source-context {
+    margin-bottom: 1rem;
+    border: 1px solid var(--border);
+    border-radius: 0.5rem;
+    overflow: hidden;
+  }
+
+  .source-code {
+    overflow-x: auto;
+    font-family: var(--code-font);
+    font-size: 0.8125rem;
+    line-height: 1.7;
+    padding: 0;
+    margin: 0;
+  }
+
+  .source-code code {
+    display: block;
+  }
+
+  .source-line {
+    display: block;
+    padding: 0 0.75rem;
+    border-left: 3px solid transparent;
+  }
+
+  .source-line-highlight {
+    background: var(--highlight-bg);
+    border-left-color: var(--highlight-border);
+  }
+
+  .line-num {
+    display: inline-block;
+    width: 3rem;
+    text-align: right;
+    margin-right: 1rem;
+    color: var(--line-num);
+    user-select: none;
+  }
+
+  .clickable { cursor: pointer; }
+  .clickable:hover { background: var(--btn-bg); }
+
+  .component-stack, .stack {
+    font-family: var(--code-font);
+    font-size: 0.8125rem;
+    line-height: 1.7;
+    padding: 0.75rem;
+    overflow-x: auto;
+    white-space: pre;
+    margin: 0;
+  }
+
+  .dimmed { color: var(--fg-dim); }
+
+  .actions {
+    margin: 1.5rem 0;
+  }
+
+  .btn {
+    font-family: inherit;
+    font-size: 0.8125rem;
+    font-weight: 500;
+    padding: 0.5rem 1rem;
+    border-radius: 0.375rem;
+    border: 1px solid var(--btn-border);
+    background: var(--btn-bg);
+    color: var(--btn-fg);
+    cursor: pointer;
+    transition: background 0.15s;
+  }
+
+  .btn:hover { opacity: 0.85; }
+`;

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

@@ -0,0 +1,187 @@
+/**
+ * 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.
+ * // Use bindWithBump() to honor the default-3000 + auto-bump policy
+ * // (see ../server/port-resolution.ts and TIM-842).
+ * const holding = createHoldingServer();
+ * await bindWithBump((p) => holding.listen(p), { startPort: 3000, autoBump: true });
+ *
+ * // 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/dev-tools/hydration-overlay.ts

@@ -0,0 +1,158 @@
+/**
+ * Hydration mismatch diff overlay — dev-only.
+ *
+ * Parses React 19's structured diff from hydration error messages and
+ * renders a color-coded + Client / - Server diff in a dismissible overlay.
+ *
+ * See design/21-dev-server.md §"Error Overlay"
+ */
+
+const REACT_HYDRATION_LINK = 'https://react.dev/link/hydration-mismatch';
+
+const HYDRATION_PATTERNS = [
+  /^In HTML, (.+?) cannot be a child of <(.+?)>\./,
+  /^In HTML, (.+?) cannot be a descendant of <(.+?)>\./,
+  /^In HTML, text nodes cannot be a child of <(.+?)>\./,
+  /^In HTML, whitespace text nodes cannot be a child of <(.+?)>\./,
+  /Hydration failed because the server rendered (text|HTML) didn't match the client\./,
+  /A tree hydrated but some attributes of the server rendered HTML didn't match the client properties/,
+];
+
+export function isHydrationError(error: unknown): boolean {
+  if (!error || typeof error !== 'object') return false;
+  const msg = (error as { message?: string }).message;
+  if (typeof msg !== 'string') return false;
+  return HYDRATION_PATTERNS.some((re) => re.test(msg));
+}
+
+interface ParsedHydrationError {
+  message: string;
+  diff: string | null;
+}
+
+function parseHydrationError(msg: string): ParsedHydrationError {
+  const hasComponentStackDiff = [
+    /^In HTML, (.+?) cannot be a child of <(.+?)>\.(.*)\nThis will cause a hydration error\.(.*)/,
+    /^In HTML, (.+?) cannot be a descendant of <(.+?)>\.\nThis will cause a hydration error\.(.*)/,
+    /^In HTML, text nodes cannot be a child of <(.+?)>\.\nThis will cause a hydration error\./,
+    /^In HTML, whitespace text nodes cannot be a child of <(.+?)>\./,
+  ].some((re) => re.test(msg));
+
+  if (hasComponentStackDiff) {
+    const [message, diffLog = ''] = msg.split('\n\n');
+    const diff = diffLog.trim();
+    return { message: message.trim(), diff: diff || null };
+  }
+
+  const [before, after] = msg.split(REACT_HYDRATION_LINK);
+  if (after !== undefined && after.length > 1) {
+    const lines: string[] = [];
+    for (const line of after.split('\n')) {
+      const trimmed = line.trim();
+      if (trimmed === '' || trimmed.startsWith('at ')) continue;
+      lines.push(line);
+    }
+    return { message: before.trim(), diff: lines.join('\n') || null };
+  }
+
+  return { message: msg.trim(), diff: null };
+}
+
+let overlayEl: HTMLDivElement | null = null;
+let errors: ParsedHydrationError[] = [];
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function renderDiffHtml(diff: string): string {
+  return diff
+    .split('\n')
+    .map((line) => {
+      const trimmed = line.trimStart();
+      if (trimmed.startsWith('+')) {
+        return `<span style="color:#4ade80;display:block">${escapeHtml(line)}</span>`;
+      }
+      if (trimmed.startsWith('-')) {
+        return `<span style="color:#f87171;display:block">${escapeHtml(line)}</span>`;
+      }
+      return `<span style="color:#a1a1aa;display:block">${escapeHtml(line)}</span>`;
+    })
+    .join('');
+}
+
+function render(): void {
+  if (errors.length === 0) {
+    if (overlayEl) {
+      overlayEl.remove();
+      overlayEl = null;
+    }
+    return;
+  }
+
+  if (!overlayEl) {
+    overlayEl = document.createElement('div');
+    overlayEl.setAttribute('data-timber-hydration-overlay', '');
+    document.body.appendChild(overlayEl);
+  }
+
+  const count = errors.length;
+  const errorsHtml = errors
+    .map(
+      (err, i) => `
+      <div style="margin-bottom:${i < count - 1 ? '16px' : '0'};padding-bottom:${i < count - 1 ? '16px' : '0'};border-bottom:${i < count - 1 ? '1px solid #333' : 'none'}">
+        <div style="color:#fbbf24;font-weight:600;margin-bottom:8px">${escapeHtml(err.message)}</div>
+        ${
+          err.diff
+            ? `<div style="margin-top:8px">
+                <div style="display:flex;gap:16px;margin-bottom:6px;font-size:11px">
+                  <span><span style="color:#4ade80">+</span> Client</span>
+                  <span><span style="color:#f87171">-</span> Server</span>
+                </div>
+                <pre style="margin:0;padding:10px;background:#1a1a1a;border-radius:4px;overflow-x:auto;font-size:12px;line-height:1.5">${renderDiffHtml(err.diff)}</pre>
+              </div>`
+            : ''
+        }
+      </div>`
+    )
+    .join('');
+
+  overlayEl.innerHTML = `
+    <div style="position:fixed;inset:0;background:rgba(0,0,0,0.6);z-index:2147483646;display:flex;align-items:center;justify-content:center;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif" data-timber-hydration-backdrop>
+      <div style="background:#18181b;color:#e4e4e7;border:1px solid #333;border-radius:8px;max-width:720px;width:90vw;max-height:80vh;display:flex;flex-direction:column;box-shadow:0 8px 32px rgba(0,0,0,0.5)">
+        <div style="display:flex;justify-content:space-between;align-items:center;padding:12px 16px;border-bottom:1px solid #333">
+          <div style="display:flex;align-items:center;gap:8px">
+            <span style="background:#dc2626;color:#fff;padding:2px 8px;border-radius:4px;font-size:11px;font-weight:700;text-transform:uppercase">Hydration Mismatch</span>
+            ${count > 1 ? `<span style="color:#71717a;font-size:12px">${count} errors</span>` : ''}
+          </div>
+          <button data-timber-hydration-close style="background:none;border:1px solid #333;color:#a1a1aa;cursor:pointer;padding:4px 10px;border-radius:4px;font-size:12px;line-height:1">Dismiss</button>
+        </div>
+        <div style="padding:16px;overflow-y:auto;font-size:13px;line-height:1.6">
+          ${errorsHtml}
+        </div>
+      </div>
+    </div>`;
+
+  overlayEl.querySelector('[data-timber-hydration-close]')?.addEventListener('click', dismiss);
+  overlayEl.querySelector('[data-timber-hydration-backdrop]')?.addEventListener('click', (e) => {
+    if ((e.target as HTMLElement).hasAttribute('data-timber-hydration-backdrop')) dismiss();
+  });
+}
+
+function dismiss(): void {
+  errors = [];
+  render();
+}
+
+export function showHydrationError(error: unknown): void {
+  if (!error || typeof error !== 'object') return;
+  const msg = (error as { message?: string }).message;
+  if (typeof msg !== 'string') return;
+  const parsed = parseHydrationError(msg);
+  errors.push(parsed);
+  render();
+}