@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.200

package/src/fonts/bundle.ts

@@ -0,0 +1,138 @@
+/**
+ * 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.ts';
+import { fontOutputBasename, fontUrlPrefix, FONT_OUTPUT_DIR } from './paths.ts';
+
+/**
+ * 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.ts';
+import type { CachedFont } from './google.ts';
+import { inferFontFormat } from './local.ts';
+
+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: `${FONT_OUTPUT_DIR}/${cf.hashedFilename}`,
+      source: cf.data,
+    });
+  }
+
+  // Local font files (content-hashed for immutable caching)
+  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 filename = src.hashedBasename ?? fontOutputBasename(src.path);
+      const data = readFileSync(absolutePath);
+      emitFile({
+        type: 'asset',
+        fileName: `${FONT_OUTPUT_DIR}/${filename}`,
+        source: data,
+      });
+    }
+  }
+}
+
+/**
+ * Populate `buildManifest.fonts` with `ManifestFontEntry[]` keyed by the
+ * absolute importer path. This matches the runtime route manifest's
+ * `filePath` values (which are absolute) and is consistent with how
+ * `buildManifest.css` keys work after TIM-1014.
+ *
+ * All font binaries use content-hashed filenames for immutable caching.
+ * Hrefs are prefixed with Vite's resolved `base` so they match the URLs
+ * the platform serves the emitted binaries under.
+ */
+export function writeFontManifest(
+  pipeline: FontPipeline,
+  buildManifest: BuildManifest,
+  base = '/'
+): void {
+  const urlPrefix = fontUrlPrefix(base);
+  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.hashedBasename ?? fontOutputBasename(src.path);
+        const format = inferFontFormat(src.path);
+        manifestEntries.push({
+          href: `${urlPrefix}/${filename}`,
+          format,
+          crossOrigin: 'anonymous',
+        });
+      }
+    } else if (entry.cachedFiles) {
+      for (const cf of entry.cachedFiles) {
+        manifestEntries.push({
+          href: `${urlPrefix}/${cf.hashedFilename}`,
+          format: 'woff2',
+          crossOrigin: 'anonymous',
+        });
+      }
+    }
+
+    fontsByImporter.set(entry.importer, manifestEntries);
+  }
+
+  for (const [importer, entries] of fontsByImporter) {
+    buildManifest.fonts[importer] = entries;
+  }
+}

package/src/fonts/css.ts

@@ -7,7 +7,7 @@
  * Design doc: 24-fonts.md §"Step 3: @font-face Generation"
  */
 
-import type { FontFaceDescriptor } from './types.js';
+import type { FontFaceDescriptor } from './types.ts';
 
 /**
  * Generate a single `@font-face` CSS rule from a descriptor.

package/src/fonts/dev-middleware.ts

@@ -0,0 +1,85 @@
+/**
+ * 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.ts';
+import { fontOutputBasename, fontUrlPrefix } from './paths.ts';
+
+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,
+  base = '/'
+): void {
+  const urlPrefix = `${fontUrlPrefix(base)}/`;
+  server.middlewares.use((req, res, next) => {
+    const url = req.url;
+    if (!url || !url.startsWith(urlPrefix)) return next();
+
+    const requestedFilename = url.slice(urlPrefix.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 = fontOutputBasename(src.path);
+        if (basename !== requestedFilename && src.hashedBasename !== 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');
+        // Dev URLs are raw (unhashed) basenames — `immutable` is only
+        // justified by content hashing (design/24-fonts.md). `no-cache`
+        // keeps responses revalidatable so edited fonts update without a
+        // hard refresh. Production binaries are content-hashed and served
+        // immutable by the platform, not this middleware.
+        res.setHeader('Cache-Control', 'no-cache');
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.end(data);
+        return;
+      }
+    }
+
+    next();
+  });
+}

package/src/fonts/fallbacks.ts

@@ -8,8 +8,6 @@
  * Design doc: 24-fonts.md §"Step 4: Size-Adjusted Fallbacks"
  */
 
-import type { FontFaceDescriptor } from './types.js';
-
 /**
  * Font metrics for size-adjusted fallback calculation.
  *
@@ -169,27 +167,6 @@ export function getGenericFamily(family: string): string {
   return 'sans-serif';
 }
 
-/**
- * Generate a size-adjusted fallback @font-face for a given font family.
- *
- * Returns null if no metrics are available (unknown font — no fallback generated).
- */
-export function generateFallbackFontFace(family: string): FontFaceDescriptor | null {
-  const metrics = FALLBACK_METRICS[family.toLowerCase()];
-  if (!metrics) return null;
-
-  const fallbackFamily = `${family} Fallback`;
-
-  return {
-    family: fallbackFamily,
-    src: `local('${metrics.fallbackFont}')`,
-    // Encode the metrics into a CSS descriptor string.
-    // We abuse the 'style' field to carry the override properties
-    // since FontFaceDescriptor doesn't have dedicated fields.
-    // The generateFallbackCss function handles this specially.
-  };
-}
-
 /**
  * Generate the full CSS for a size-adjusted fallback font.
  *

package/src/fonts/google.ts

@@ -18,7 +18,52 @@
 import { createHash } from 'node:crypto';
 import { readFile, writeFile, mkdir, stat } from 'node:fs/promises';
 import { join } from 'node:path';
-import type { ExtractedFont, FontFaceDescriptor } from './types.js';
+import type { ExtractedFont, FontFaceDescriptor } from './types.ts';
+import { fontUrlPrefix } from './paths.ts';
+
+/**
+ * Extract a recognizable error code (ETIMEDOUT, ENOTFOUND, etc.) from a
+ * network error's cause chain. Node's undici-based `fetch` wraps the
+ * system error inside `cause` (sometimes as an AggregateError).
+ */
+function extractNetworkErrorCode(err: unknown): string | undefined {
+  if (!(err instanceof Error)) return undefined;
+  const code = (err as NodeJS.ErrnoException).code;
+  if (code) return code;
+  const cause = (err as { cause?: unknown }).cause;
+  if (cause instanceof AggregateError) {
+    for (const inner of cause.errors) {
+      const innerCode = (inner as NodeJS.ErrnoException).code;
+      if (innerCode) return innerCode;
+    }
+  }
+  if (cause instanceof Error) {
+    return (cause as NodeJS.ErrnoException).code;
+  }
+  return undefined;
+}
+
+const MAX_RETRIES = 3;
+const MIN_TIMEOUT_MS = 100;
+
+async function retry<T>(fn: () => Promise<T>): Promise<T> {
+  let lastError: unknown;
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err;
+      if (attempt < MAX_RETRIES) {
+        const delay = MIN_TIMEOUT_MS * 2 ** attempt;
+        console.error(
+          `${err instanceof Error ? err.message : String(err)}\n\nRetrying ${attempt + 1}/${MAX_RETRIES}...`
+        );
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+    }
+  }
+  throw lastError;
+}
 
 /** Google Fonts CSS API v2 base URL. */
 const GOOGLE_FONTS_API = 'https://fonts.googleapis.com/css2';
@@ -111,17 +156,31 @@ export function buildGoogleFontsUrl(font: ExtractedFont): string {
  * We parse each block to extract the font URL, unicode-range, and subset label.
  */
 export async function fetchGoogleFontsCss(url: string): Promise<GoogleFontFace[]> {
-  const response = await fetch(url, {
-    headers: { 'User-Agent': WOFF2_USER_AGENT },
-  });
+  const css = await retry(async () => {
+    let response: Response;
+    try {
+      response = await fetch(url, {
+        headers: { 'User-Agent': WOFF2_USER_AGENT },
+      });
+    } catch (err) {
+      const code = extractNetworkErrorCode(err);
+      throw new Error(
+        `[timber] Failed to fetch Google Fonts CSS from ${url}` +
+          (code ? ` (${code})` : '') +
+          `. Build requires internet access for font optimization.` +
+          ` If building offline, set TIMBER_SKIP_FONTS=1 to skip font downloading.`
+      );
+    }
 
-  if (!response.ok) {
-    throw new Error(
-      `Google Fonts API returned ${response.status}: ${response.statusText} for ${url}`
-    );
-  }
+    if (!response.ok) {
+      throw new Error(
+        `Google Fonts API returned ${response.status}: ${response.statusText} for ${url}`
+      );
+    }
+
+    return response.text();
+  });
 
-  const css = await response.text();
   return parseGoogleFontsCss(css);
 }
 
@@ -204,11 +263,24 @@ export function cacheKey(face: GoogleFontFace): string {
  * Download a single font file from its URL.
  */
 export async function downloadFontFile(url: string): Promise<Buffer> {
-  const response = await fetch(url);
-  if (!response.ok) {
-    throw new Error(`Failed to download font from ${url}: ${response.status}`);
-  }
-  return Buffer.from(await response.arrayBuffer());
+  return retry(async () => {
+    let response: Response;
+    try {
+      response = await fetch(url);
+    } catch (err) {
+      const code = extractNetworkErrorCode(err);
+      throw new Error(
+        `[timber] Failed to download font file from ${url}` +
+          (code ? ` (${code})` : '') +
+          `. Build requires internet access for font optimization.` +
+          ` If building offline, set TIMBER_SKIP_FONTS=1 to skip font downloading.`
+      );
+    }
+    if (!response.ok) {
+      throw new Error(`Failed to download font from ${url}: ${response.status}`);
+    }
+    return Buffer.from(await response.arrayBuffer());
+  });
 }
 
 /**
@@ -231,7 +303,14 @@ export async function downloadAndCacheFonts(
 
   for (const font of googleFonts) {
     const apiUrl = buildGoogleFontsUrl(font);
-    const faces = await fetchGoogleFontsCss(apiUrl);
+    let faces: GoogleFontFace[];
+    try {
+      faces = await fetchGoogleFontsCss(apiUrl);
+    } catch (err) {
+      throw new Error(
+        `[timber] Failed to download font '${font.family}': ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
     const filtered = filterBySubsets(faces, font.subsets);
 
     for (const face of filtered) {
@@ -281,15 +360,18 @@ async function isCacheHit(metaPath: string, dataPath: string): Promise<boolean>
  * Generate @font-face descriptors for cached (production) Google Fonts.
  *
  * Each CachedFont gets a FontFaceDescriptor pointing to the
- * content-hashed URL under `/_timber/fonts/`.
+ * content-hashed URL under `<base>_timber/fonts/`. The `urlPrefix` comes
+ * from `fontUrlPrefix(viteBase)` so apps deployed under a non-root base
+ * resolve fonts correctly.
  */
 export function generateProductionFontFaces(
   cachedFonts: CachedFont[],
-  display: string
+  display: string,
+  urlPrefix = fontUrlPrefix()
 ): FontFaceDescriptor[] {
   return cachedFonts.map((cf) => ({
     family: cf.face.family,
-    src: `url('/_timber/fonts/${cf.hashedFilename}') format('woff2')`,
+    src: `url('${urlPrefix}/${cf.hashedFilename}') format('woff2')`,
     weight: cf.face.weight,
     style: cf.face.style,
     display,

package/src/fonts/local.ts

@@ -14,9 +14,10 @@
  */
 
 import { resolve, dirname, extname } from 'node:path';
-import type { LocalFontConfig, LocalFontSrc, FontFaceDescriptor, ExtractedFont } from './types.js';
-import { buildFontStack } from './fallbacks.js';
-import { extractLocalFontConfigAst } from './ast.js';
+import type { LocalFontConfig, LocalFontSrc, FontFaceDescriptor, ExtractedFont } from './types.ts';
+import { buildFontStack } from './fallbacks.ts';
+import { extractLocalFontConfigAst } from './ast.ts';
+import { fontOutputBasename, fontUrlPrefix } from './paths.ts';
 
 /**
  * Infer the font format from a file extension.
@@ -85,7 +86,7 @@ export function resolveLocalFontPaths(
 export function generateFamilyName(sources: LocalFontSrc[]): string {
   if (sources.length === 0) return 'Local Font';
   const firstPath = sources[0].path;
-  const basename = firstPath.split('/').pop() ?? firstPath;
+  const basename = fontOutputBasename(firstPath);
   // Remove extension and weight/style suffixes for a cleaner family name
   const stem = basename.replace(/\.[^.]+$/, '');
   // Strip common weight/style suffixes to get the family root
@@ -100,22 +101,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 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.
+ * uses a `url()` pointing to the served path under `<base>_timber/fonts/`.
+ * The `urlPrefix` defaults to `fontUrlPrefix()` (root base) — pass
+ * `fontUrlPrefix(viteBase)` so non-root deployments resolve correctly.
  */
 export function generateLocalFontFaces(
   family: string,
   sources: LocalFontSrc[],
   display: string,
-  urlPrefix = '/_timber/fonts'
+  urlPrefix = fontUrlPrefix()
 ): FontFaceDescriptor[] {
   return sources.map((entry) => {
     const format = inferFontFormat(entry.path);
-    const basename = entry.path.split('/').pop() ?? entry.path;
+    const filename = entry.hashedBasename ?? fontOutputBasename(entry.path);
     return {
       family,
-      src: `url('${urlPrefix}/${basename}') format('${format}')`,
+      src: `url('${urlPrefix}/${filename}') format('${format}')`,
       weight: entry.weight,
       style: entry.style,
       display,
@@ -173,7 +174,7 @@ export function processLocalFont(config: LocalFontConfig, importerPath: string):
  *
  * Returns null if the call cannot be statically analyzed.
  *
- * Uses acorn AST parsing for robust handling of comments, trailing commas,
+ * Uses OXC (via vite.parseAst) AST parsing for robust handling of comments, trailing commas,
  * and multi-line configs.
  */
 export function extractLocalFontConfig(callSource: string): LocalFontConfig | null {

package/src/fonts/paths.ts

@@ -0,0 +1,58 @@
+/**
+ * Shared path/URL helpers for the timber-fonts pipeline.
+ *
+ * Two concerns live here:
+ *
+ * - `fontUrlPrefix` — the public URL prefix for font binaries, derived
+ *   from Vite's resolved `base`. Every URL the pipeline emits (@font-face
+ *   src, manifest hrefs, dev middleware matching) must go through this so
+ *   apps deployed under a non-root base (`base: '/my-app/'`) resolve
+ *   fonts correctly. Emitted *file* locations are not base-prefixed —
+ *   only URLs are.
+ *
+ * - `fontOutputBasename` / `hashedFontBasename` — basename derivation for
+ *   local font sources. Paths are absolutized with `resolve()`, which
+ *   produces backslash separators on Windows, so `split('/').pop()` is
+ *   not safe. `path.win32.basename` handles both separators.
+ *
+ * Design doc: 24-fonts.md
+ */
+
+import { win32 } from 'node:path';
+
+/** Directory (relative to the build output / URL root) holding font binaries. */
+export const FONT_OUTPUT_DIR = '_timber/fonts';
+
+/**
+ * Build the URL prefix for font binaries from Vite's resolved `base`.
+ *
+ * `fontUrlPrefix('/')` → `/_timber/fonts`
+ * `fontUrlPrefix('/my-app/')` → `/my-app/_timber/fonts`
+ */
+export function fontUrlPrefix(base = '/'): string {
+  const normalized = base.endsWith('/') ? base : `${base}/`;
+  return `${normalized}${FONT_OUTPUT_DIR}`;
+}
+
+/**
+ * Derive the output basename for a local font source path.
+ *
+ * Uses `path.win32.basename` because it splits on both `/` and `\`,
+ * handling absolute paths produced by `resolve()` on any platform.
+ */
+export function fontOutputBasename(srcPath: string): string {
+  return win32.basename(srcPath);
+}
+
+/**
+ * Derive the content-hashed output basename for a local font source.
+ *
+ * `hashedFontBasename('C:\\fonts\\MyFont-Bold.woff2', 'a1b2c3d4')`
+ * → `MyFont-Bold-a1b2c3d4.woff2`
+ */
+export function hashedFontBasename(srcPath: string, hash: string): string {
+  const basename = fontOutputBasename(srcPath);
+  const ext = win32.extname(basename);
+  const stem = ext ? basename.slice(0, -ext.length) : basename;
+  return `${stem}-${hash}${ext}`;
+}