@timber-js/app 0.2.0-alpha.146 → 0.2.0-alpha.148

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();
+}

package/src/dev-tools/index.ts

@@ -8,7 +8,6 @@
  * - 404-page: self-contained HTML 404 page
  * - terminal: boxed terminal error output
  * - logger: structured request tree logger
- * - warnings: dev-mode footgun warnings
  * - browser-logs: forward browser console to server
  * - logs: forward server console to browser
  * - holding-server: startup holding server
@@ -64,21 +63,6 @@ export {
   type DevLoggerConfig,
 } from './logger.js';
 
-// Dev-mode warnings
-export {
-  warnSuspenseWrappingChildren,
-  warnDenyInSuspense,
-  warnRedirectInSuspense,
-  warnRedirectInAccess,
-  warnStaticRequestApi,
-  warnSlowSlotWithoutSuspense,
-  setViteServer,
-  WarningId,
-  type DevWarningConfig,
-  _resetWarnings,
-  _getEmitted,
-} from './warnings.js';
-
 // Browser log forwarding
 export {
   timberDevBrowserLogs,
@@ -94,3 +78,6 @@ export { createHoldingServer, type HoldingServer } from './holding-server.js';
 
 // OTEL instrumentation
 export { instrumentDevFetch, DevSpanProcessor, type DevFetchCleanup } from './instrumentation.js';
+
+// Hydration mismatch overlay (client-side, dev-only)
+export { isHydrationError, showHydrationError } from './hydration-overlay.js';

package/src/fonts/ast-walk.ts

@@ -0,0 +1,235 @@
+/**
+ * Generic AST node types and recursive walkers for font static analysis.
+ *
+ * `ast.ts` owns parsing, config extraction, and call-site discovery; this
+ * module owns the recursive walks that police where font bindings may be
+ * used (dynamic configs, nested scopes, unconsumed references). Split out
+ * to keep `ast.ts` under the 500-code-line limit (design/18-build-system.md).
+ *
+ * Design doc: 24-fonts.md §"Step 1: Static Analysis"
+ */
+
+// ── AST node types (minimal subset of estree) ────────────────────────────────
+
+export interface AstNode {
+  type: string;
+  [key: string]: unknown;
+}
+
+export interface IdentifierNode extends AstNode {
+  type: 'Identifier';
+  name: string;
+}
+
+export interface PositionedNode extends AstNode {
+  start: number;
+  end: number;
+}
+
+/** A flagged reference/usage for build-error reporting. */
+export interface FlaggedUsage {
+  name: string;
+  line: number;
+  column: number;
+}
+
+// ── Offset → line/column helper ──────────────────────────────────────────────
+
+/** Convert a 0-based byte offset into a 1-based line and 0-based column. */
+export function offsetToLineColumn(
+  source: string,
+  offset: number
+): { line: number; column: number } {
+  let line = 1;
+  let lastNewline = -1;
+  for (let i = 0; i < offset; i++) {
+    if (source[i] === '\n') {
+      line++;
+      lastNewline = i;
+    }
+  }
+  return { line, column: offset - lastNewline - 1 };
+}
+
+// ── Shared recursion plumbing ────────────────────────────────────────────────
+
+/**
+ * Invoke `visit` on every direct child AST node of `node` (array elements
+ * and object-valued properties with a `type` field).
+ */
+export function walkChildNodes(node: AstNode, visit: (child: AstNode) => void): void {
+  for (const key of Object.keys(node)) {
+    if (key === 'type') continue;
+    const child = node[key];
+    if (Array.isArray(child)) {
+      for (const item of child) {
+        if (item && typeof item === 'object' && (item as AstNode).type) {
+          visit(item as AstNode);
+        }
+      }
+    } else if (child && typeof child === 'object' && (child as AstNode).type) {
+      visit(child as AstNode);
+    }
+  }
+}
+
+// ── Walkers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Recursively walk the AST looking for CallExpression nodes where
+ * the callee is one of the imported font names and the first argument
+ * is not an ObjectExpression (i.e. it's dynamic).
+ */
+export function walkForDynamicCalls(
+  node: AstNode,
+  names: ReadonlySet<string>,
+  source: string
+): string | null {
+  if (!node || typeof node !== 'object') return null;
+
+  if (node.type === 'CallExpression') {
+    const callee = node.callee as AstNode;
+    if (callee.type === 'Identifier' && names.has((callee as IdentifierNode).name)) {
+      const args = node.arguments as AstNode[];
+      if (args.length > 0 && args[0].type !== 'ObjectExpression') {
+        // Extract the argument source text
+        const argStart = (args[0] as PositionedNode).start;
+        const argEnd = (args[0] as PositionedNode).end;
+        const argText = source.slice(argStart, argEnd);
+        const calleeName = (callee as IdentifierNode).name;
+        return `${calleeName}(${argText})`;
+      }
+    }
+  }
+
+  let result: string | null = null;
+  walkChildNodes(node, (child) => {
+    if (!result) result = walkForDynamicCalls(child, names, source);
+  });
+  return result;
+}
+
+/**
+ * Node types that introduce a nested scope — any font call inside is an
+ * error (font calls must be module-level, same constraint as Next.js).
+ * Module scope so it isn't rebuilt on every recursive walk call.
+ */
+const NESTED_SCOPE_TYPES = new Set([
+  'FunctionDeclaration',
+  'FunctionExpression',
+  'ArrowFunctionExpression',
+  'IfStatement',
+  'ForStatement',
+  'ForInStatement',
+  'ForOfStatement',
+  'WhileStatement',
+  'DoWhileStatement',
+  'SwitchStatement',
+  'TryStatement',
+  'BlockStatement',
+  'ClassDeclaration',
+  'ClassExpression',
+]);
+
+/**
+ * Recursively walk an AST node looking for font CallExpressions in nested
+ * scopes (function bodies, if-blocks, loops, etc.). Font calls must be
+ * module-level; nested calls are collected as errors.
+ *
+ * `isNested` tracks whether we've descended past the top-level statement.
+ * Top-level VariableDeclarations and ExpressionStatements are already
+ * handled by the main loop in `findFontCallSites`, so we only flag calls
+ * found deeper.
+ */
+export function walkForNestedFontCalls(
+  node: AstNode,
+  bindingNames: ReadonlyMap<string, unknown>,
+  source: string,
+  out: FlaggedUsage[],
+  isNested: boolean
+): void {
+  if (!node || typeof node !== 'object') return;
+
+  if (node.type === 'CallExpression') {
+    const callee = node.callee as AstNode;
+    if (
+      isNested &&
+      callee.type === 'Identifier' &&
+      bindingNames.has((callee as IdentifierNode).name)
+    ) {
+      const pos = offsetToLineColumn(source, (node as PositionedNode).start);
+      out.push({ name: (callee as IdentifierNode).name, line: pos.line, column: pos.column });
+      return; // Don't recurse into this call's children
+    }
+  }
+
+  const enterNested = isNested || NESTED_SCOPE_TYPES.has(node.type);
+  walkChildNodes(node, (child) =>
+    walkForNestedFontCalls(child, bindingNames, source, out, enterNested)
+  );
+}
+
+/**
+ * Recursively walk an AST node looking for references to font bindings
+ * that were not consumed by a recognized call site.
+ *
+ * Skips:
+ * - recognized CallExpressions (the transform rewrites them wholesale)
+ * - TS type-position nodes (erased at runtime)
+ * - non-computed member properties (`obj.Inter` doesn't reference the binding)
+ * - non-computed object keys (`{ Inter: 1 }` doesn't reference the binding)
+ * - export aliases (`export { inter as Inter }` — only `local` is a reference)
+ */
+export function walkForUnconsumedReferences(
+  node: AstNode,
+  bindingNames: ReadonlyMap<string, unknown>,
+  consumedCallStarts: ReadonlySet<number>,
+  source: string,
+  out: FlaggedUsage[]
+): void {
+  if (!node || typeof node !== 'object') return;
+  if (node.type === 'ImportDeclaration' || node.type.startsWith('TS')) return;
+
+  if (node.type === 'Identifier') {
+    const name = (node as IdentifierNode).name;
+    if (bindingNames.has(name)) {
+      const pos = offsetToLineColumn(source, (node as PositionedNode).start);
+      out.push({ name, line: pos.line, column: pos.column });
+    }
+    return;
+  }
+
+  if (node.type === 'CallExpression' && consumedCallStarts.has((node as PositionedNode).start)) {
+    return; // The whole call (callee + config object) is rewritten.
+  }
+
+  if (node.type === 'MemberExpression' && !(node as { computed?: boolean }).computed) {
+    const object = (node as { object?: AstNode }).object;
+    if (object) {
+      walkForUnconsumedReferences(object, bindingNames, consumedCallStarts, source, out);
+    }
+    return;
+  }
+
+  if (node.type === 'Property' && !(node as { computed?: boolean }).computed) {
+    const value = (node as { value?: AstNode }).value;
+    if (value) {
+      walkForUnconsumedReferences(value, bindingNames, consumedCallStarts, source, out);
+    }
+    return;
+  }
+
+  if (node.type === 'ExportSpecifier') {
+    // Only `local` references a module binding. `exported` is just the
+    // public name — `export { inter as Inter }` must not flag `Inter`.
+    const local = (node as { local?: AstNode }).local;
+    if (local) {
+      walkForUnconsumedReferences(local, bindingNames, consumedCallStarts, source, out);
+    }
+    return;
+  }
+
+  walkChildNodes(node, (child) =>
+    walkForUnconsumedReferences(child, bindingNames, consumedCallStarts, source, out)
+  );
+}