@timber-js/app 0.2.0-alpha.1 → 0.2.0-alpha.100

package/src/dev-tools/terminal.ts

@@ -0,0 +1,183 @@
+/**
+ * Terminal error formatting — boxed, color-coded error output for dev mode.
+ *
+ * Produces a visually scannable error block with:
+ * - Unicode box-drawing border around the error
+ * - Phase badge and error message
+ * - First app frame highlighted as the primary action item
+ * - OSC 8 clickable file:line links (VSCode terminal, iTerm2, etc.)
+ * - Internal/framework frames collapsed with a count
+ * - Component stack (for React render errors)
+ *
+ * Dev-only: this module is only imported by dev-error-overlay.ts.
+ *
+ * Design doc: 21-dev-server.md §"Error Overlay"
+ */
+
+import { pathToFileURL } from 'node:url';
+import {
+  extractComponentStack,
+  parseFirstAppFrame,
+  PHASE_LABELS,
+  type ErrorPhase,
+} from './overlay.js';
+import { classifyStack } from './stack-classifier.js';
+
+// ─── ANSI Codes ─────────────────────────────────────────────────────────────
+
+const RED = '\x1b[31m';
+const CYAN = '\x1b[36m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+const UNDERLINE = '\x1b[4m';
+
+// ─── OSC 8 Hyperlinks ──────────────────────────────────────────────────────
+
+/**
+ * Wrap text in an OSC 8 hyperlink escape sequence.
+ *
+ * Terminals that support OSC 8 (VSCode, iTerm2, Windows Terminal, etc.)
+ * render this as a clickable link. Others ignore the escape sequences
+ * and show the text normally.
+ *
+ * Format: \x1b]8;;URL\x07TEXT\x1b]8;;\x07
+ */
+function hyperlink(text: string, url: string): string {
+  return `\x1b]8;;${url}\x07${text}\x1b]8;;\x07`;
+}
+
+/**
+ * Format a file:line:col reference as a clickable terminal link.
+ *
+ * Uses file:// URLs so terminals open the file in the configured editor.
+ * The link text is styled with cyan + underline for visibility.
+ */
+function fileLink(filePath: string, line?: number, col?: number): string {
+  const display = line ? `${filePath}:${line}${col ? `:${col}` : ''}` : filePath;
+  // Use pathToFileURL for proper encoding of spaces, #, ?, and Windows
+  // drive letters (TIM-792). Append :line:col after the URL.
+  const base = pathToFileURL(filePath).href;
+  const url = line ? `${base}:${line}${col ? `:${col}` : ''}` : base;
+  return `${CYAN}${UNDERLINE}${hyperlink(display, url)}${RESET}`;
+}
+
+// ─── Box Drawing ────────────────────────────────────────────────────────────
+
+const BOX = {
+  topLeft: '╭',
+  topRight: '╮',
+  bottomLeft: '╰',
+  bottomRight: '╯',
+  horizontal: '─',
+  vertical: '│',
+};
+
+/**
+ * Wrap lines of text in a Unicode box with a colored left border.
+ *
+ * @param lines - Content lines (no ANSI length calculation — keeps it simple)
+ * @param width - Box width (characters). Lines longer than this are not truncated.
+ */
+function box(lines: string[], borderColor: string, width = 80): string {
+  const bar = BOX.horizontal.repeat(width - 2);
+  const output: string[] = [];
+
+  output.push(`${borderColor}${BOX.topLeft}${bar}${BOX.topRight}${RESET}`);
+  for (const line of lines) {
+    output.push(`${borderColor}${BOX.vertical}${RESET} ${line}`);
+  }
+  output.push(`${borderColor}${BOX.bottomLeft}${bar}${BOX.bottomRight}${RESET}`);
+
+  return output.join('\n');
+}
+
+// Frame classification and parsing provided by stack-classifier.ts
+
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+/**
+ * Format an error for terminal output with a boxed layout.
+ *
+ * The output is designed to be scannable at a glance:
+ * 1. Red box with phase badge and error message
+ * 2. First app frame as a clickable link (the primary action item)
+ * 3. App frames listed normally
+ * 4. Internal/framework frames collapsed with count
+ * 5. Component stack (if present)
+ */
+export function formatTerminalError(error: Error, phase: ErrorPhase, projectRoot: string): string {
+  const sections: string[] = [];
+  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 internalCount = frames.filter((f) => f.type !== 'app').length;
+
+  // ── Box: Phase + Message ──────────────────────────────────────────
+  const boxLines: string[] = [];
+  boxLines.push(`${RED}${BOLD}${PHASE_LABELS[phase]} Error${RESET}`);
+  boxLines.push('');
+
+  // Error message — may be multi-line
+  for (const msgLine of error.message.split('\n')) {
+    boxLines.push(`${RED}${msgLine}${RESET}`);
+  }
+
+  // Primary file location (clickable)
+  if (loc) {
+    boxLines.push('');
+    const relPath = loc.file.startsWith(projectRoot)
+      ? loc.file.slice(projectRoot.length + 1)
+      : loc.file;
+    boxLines.push(
+      `${BOLD}→${RESET} ${fileLink(loc.file, loc.line, loc.column)} ${DIM}(${relPath})${RESET}`
+    );
+  }
+
+  sections.push(box(boxLines, RED));
+
+  // ── Component Stack ───────────────────────────────────────────────
+  if (componentStack) {
+    sections.push('');
+    sections.push(`  ${BOLD}Component Stack:${RESET}`);
+    for (const csLine of componentStack.trim().split('\n')) {
+      sections.push(`  ${DIM}${csLine.trim()}${RESET}`);
+    }
+  }
+
+  // ── App Frames ────────────────────────────────────────────────────
+  if (appFrames.length > 0) {
+    sections.push('');
+    sections.push(`  ${BOLD}Application Frames:${RESET}`);
+    for (let i = 0; i < appFrames.length; i++) {
+      const f = appFrames[i]!;
+      if (f.file && f.line) {
+        const prefix = i === 0 ? `${BOLD}▸${RESET}` : ' ';
+        sections.push(
+          `  ${prefix} ${fileLink(f.file, f.line, f.col)} ${DIM}${extractFnName(f.raw)}${RESET}`
+        );
+      } else {
+        sections.push(`  ${f.raw}`);
+      }
+    }
+  }
+
+  // ── Internal Frames (collapsed) ───────────────────────────────────
+  if (internalCount > 0) {
+    sections.push(
+      `  ${DIM}… ${internalCount} internal frame${internalCount !== 1 ? 's' : ''} hidden${RESET}`
+    );
+  }
+
+  sections.push('');
+  return sections.join('\n');
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+/** Extract the function name from a stack frame line like "    at fnName (/path:1:2)". */
+function extractFnName(frameLine: string): string {
+  const match = /at\s+(\S+)\s+\(/.exec(frameLine.trim());
+  return match ? match[1]! : '';
+}

package/src/{server/dev-warnings.ts → dev-tools/warnings.ts}

@@ -15,6 +15,7 @@
  */
 
 import type { ViteDevServer } from 'vite';
+import { isDebug } from '../server/debug.js';
 
 // ─── Warning IDs ───────────────────────────────────────────────────────────
 
@@ -24,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;
 
@@ -54,7 +54,7 @@ export function setViteServer(server: ViteDevServer | null): void {
 }
 
 function isDev(): boolean {
-  return process.env.NODE_ENV !== 'production';
+  return isDebug();
 }
 
 /**
@@ -110,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.'
   );
 }
 
@@ -178,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.
@@ -196,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.
@@ -244,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 ────────────────────────────────────────────────────────────────
 
 /**

package/src/fonts/bundle.ts

@@ -0,0 +1,142 @@
+/**
+ * Build-output emission for the timber-fonts plugin.
+ *
+ * Splits the `generateBundle` hook into pure helpers so the plugin shell
+ * can stay focused on Vite wiring. The functions here are deliberately
+ * Rollup-agnostic — they take an `EmitFile` callback so the plugin can
+ * pass `this.emitFile` from the `generateBundle` context.
+ *
+ * Design doc: 24-fonts.md
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, normalize } from 'node:path';
+import type { ManifestFontEntry, BuildManifest } from '../server/build-manifest.js';
+
+/**
+ * Minimal shape of the asset descriptor accepted by Rollup's `emitFile`.
+ * Declared inline rather than importing from `rollup` to keep `bundle.ts`
+ * Rollup-agnostic and avoid pulling the type into the build graph.
+ */
+interface EmittedAsset {
+  type: 'asset';
+  fileName: string;
+  source: string | Uint8Array;
+}
+import type { FontPipeline } from './pipeline.js';
+import type { CachedFont } from './google.js';
+import { inferFontFormat } from './local.js';
+
+type EmitFile = (asset: EmittedAsset) => string;
+type EmitWarning = (msg: string) => void;
+
+/** Group cached Google Font binaries by lowercase family name. */
+export function groupCachedFontsByFamily(
+  cachedFonts: readonly CachedFont[]
+): Map<string, CachedFont[]> {
+  const cachedByFamily = new Map<string, CachedFont[]>();
+  for (const cf of cachedFonts) {
+    const key = cf.face.family.toLowerCase();
+    const arr = cachedByFamily.get(key) ?? [];
+    arr.push(cf);
+    cachedByFamily.set(key, arr);
+  }
+  return cachedByFamily;
+}
+
+/**
+ * Emit cached Google Font binaries and local font files into the build
+ * output under `_timber/fonts/`. Local files missing on disk produce a
+ * warning rather than an error so the build still succeeds.
+ *
+ * Cached Google Font binaries are deduplicated by `hashedFilename` so
+ * each unique file is written exactly once even when multiple font
+ * entries share a family (and therefore share `CachedFont` references).
+ */
+export function emitFontAssets(
+  pipeline: FontPipeline,
+  emitFile: EmitFile,
+  warn: EmitWarning
+): void {
+  // Cached Google Font binaries (content-hashed, deduped by filename)
+  for (const cf of pipeline.uniqueCachedFiles()) {
+    emitFile({
+      type: 'asset',
+      fileName: `_timber/fonts/${cf.hashedFilename}`,
+      source: cf.data,
+    });
+  }
+
+  // Local font files (emitted by basename)
+  for (const font of pipeline.fonts()) {
+    if (font.provider !== 'local' || !font.localSources) continue;
+    for (const src of font.localSources) {
+      const absolutePath = normalize(resolve(src.path));
+      if (!existsSync(absolutePath)) {
+        warn(`Local font file not found: ${absolutePath}`);
+        continue;
+      }
+      const basename = src.path.split('/').pop() ?? src.path;
+      const data = readFileSync(absolutePath);
+      emitFile({
+        type: 'asset',
+        fileName: `_timber/fonts/${basename}`,
+        source: data,
+      });
+    }
+  }
+}
+
+/**
+ * Populate `buildManifest.fonts` with `ManifestFontEntry[]` keyed by the
+ * importer module path (relative to the project root, matching how Vite's
+ * `manifest.json` keys css/js).
+ *
+ * Google fonts use the content-hashed filenames produced during
+ * `buildStart`. Local fonts use the source basename.
+ */
+export function writeFontManifest(
+  pipeline: FontPipeline,
+  buildManifest: BuildManifest,
+  rootDir: string
+): void {
+  const fontsByImporter = new Map<string, ManifestFontEntry[]>();
+
+  for (const entry of pipeline.entries()) {
+    const manifestEntries = fontsByImporter.get(entry.importer) ?? [];
+
+    if (entry.provider === 'local' && entry.localSources) {
+      for (const src of entry.localSources) {
+        const filename = src.path.split('/').pop() ?? src.path;
+        const format = inferFontFormat(src.path);
+        manifestEntries.push({
+          href: `/_timber/fonts/${filename}`,
+          format,
+          crossOrigin: 'anonymous',
+        });
+      }
+    } else if (entry.cachedFiles) {
+      // Google fonts: use the per-entry cached files attached during
+      // buildStart. Each entry owns its own cached binaries (TIM-829),
+      // so we no longer need a family-grouped lookup.
+      for (const cf of entry.cachedFiles) {
+        manifestEntries.push({
+          href: `/_timber/fonts/${cf.hashedFilename}`,
+          format: 'woff2',
+          crossOrigin: 'anonymous',
+        });
+      }
+    }
+
+    fontsByImporter.set(entry.importer, manifestEntries);
+  }
+
+  // Normalize importer paths to be relative to project root (matching how
+  // Vite's manifest.json keys work for css/js).
+  for (const [importer, entries] of fontsByImporter) {
+    const relativePath = importer.startsWith(rootDir)
+      ? importer.slice(rootDir.length + 1)
+      : importer;
+    buildManifest.fonts[relativePath] = entries;
+  }
+}

package/src/fonts/css.ts

@@ -39,6 +39,7 @@ export function generateFontFaces(descriptors: FontFaceDescriptor[]): string {
  * ```css
  * .timber-font-inter {
  *   --font-sans: 'Inter', 'Inter Fallback', system-ui, sans-serif;
+ *   font-family: 'Inter', 'Inter Fallback', system-ui, sans-serif;
  * }
  * ```
  */
@@ -47,7 +48,7 @@ export function generateVariableClass(
   variable: string,
   fontFamily: string
 ): string {
-  return `.${className} {\n  ${variable}: ${fontFamily};\n}`;
+  return `.${className} {\n  ${variable}: ${fontFamily};\n  font-family: ${fontFamily};\n}`;
 }
 
 /**

package/src/fonts/dev-middleware.ts

@@ -0,0 +1,74 @@
+/**
+ * Dev-mode middleware that serves local font binaries under
+ * `/_timber/fonts/<basename>`.
+ *
+ * Only files registered in the FontPipeline are served, and only by
+ * basename — directory traversal and path separators in the requested
+ * filename are rejected up front. Font CSS is no longer served here; it
+ * goes through Vite's CSS pipeline via virtual modules.
+ *
+ * Design doc: 24-fonts.md
+ */
+
+import type { ViteDevServer } from 'vite';
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, normalize } from 'node:path';
+import type { FontPipeline } from './pipeline.js';
+
+const FONT_MIME_TYPES: Record<string, string> = {
+  woff2: 'font/woff2',
+  woff: 'font/woff',
+  ttf: 'font/ttf',
+  otf: 'font/otf',
+  eot: 'application/vnd.ms-fontopen',
+};
+
+/**
+ * Wire the timber-fonts dev middleware onto a Vite dev server.
+ *
+ * Returns synchronously after registering the middleware. The pipeline is
+ * captured by reference so that fonts registered after `configureServer`
+ * runs (during transform) are still resolvable.
+ */
+export function installFontDevMiddleware(server: ViteDevServer, pipeline: FontPipeline): void {
+  server.middlewares.use((req, res, next) => {
+    const url = req.url;
+    if (!url || !url.startsWith('/_timber/fonts/')) return next();
+
+    const requestedFilename = url.slice('/_timber/fonts/'.length);
+    // Reject path traversal attempts and any subdirectory access. We only
+    // serve flat basenames out of the registry.
+    if (requestedFilename.includes('..') || requestedFilename.includes('/')) {
+      res.statusCode = 400;
+      res.end('Bad request');
+      return;
+    }
+
+    // Find the matching font file in the registry. We iterate every local
+    // font's source list and match by basename. The set is small (one per
+    // localFont() call) so this is cheap.
+    for (const font of pipeline.fonts()) {
+      if (font.provider !== 'local' || !font.localSources) continue;
+      for (const src of font.localSources) {
+        const basename = src.path.split('/').pop() ?? '';
+        if (basename !== requestedFilename) continue;
+
+        const absolutePath = normalize(resolve(src.path));
+        if (!existsSync(absolutePath)) {
+          res.statusCode = 404;
+          res.end('Not found');
+          return;
+        }
+        const data = readFileSync(absolutePath);
+        const ext = absolutePath.split('.').pop()?.toLowerCase();
+        res.setHeader('Content-Type', FONT_MIME_TYPES[ext ?? ''] ?? 'application/octet-stream');
+        res.setHeader('Cache-Control', 'public, max-age=31536000, immutable');
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.end(data);
+        return;
+      }
+    }
+
+    next();
+  });
+}

package/src/fonts/local.ts

@@ -100,18 +100,22 @@ export function generateFamilyName(sources: LocalFontSrc[]): string {
  * Generate @font-face descriptors for local font sources.
  *
  * Each source entry produces one @font-face rule. The `src` descriptor
- * uses a `url()` pointing to the resolved file path with the inferred format.
+ * uses a `url()` pointing to the served path under `/_timber/fonts/`.
+ * The `urlPrefix` defaults to `/_timber/fonts` — the path used by both
+ * the dev server middleware and the production build output.
  */
 export function generateLocalFontFaces(
   family: string,
   sources: LocalFontSrc[],
-  display: string
+  display: string,
+  urlPrefix = '/_timber/fonts'
 ): FontFaceDescriptor[] {
   return sources.map((entry) => {
     const format = inferFontFormat(entry.path);
+    const basename = entry.path.split('/').pop() ?? entry.path;
     return {
       family,
-      src: `url('${entry.path}') format('${format}')`,
+      src: `url('${urlPrefix}/${basename}') format('${format}')`,
       weight: entry.weight,
       style: entry.style,
       display,