@timber-js/app 0.2.0-alpha.147 → 0.2.0-alpha.149

package/src/fonts/ast.ts

@@ -19,13 +19,17 @@
 import { parseAst as viteParseAst } from 'vite';
 import type { GoogleFontConfig } from './types.js';
 import type { LocalFontConfig, LocalFontSrc } from './types.js';
+import type { AstNode, IdentifierNode, PositionedNode, FlaggedUsage } from './ast-walk.js';
+import {
+  offsetToLineColumn,
+  walkForDynamicCalls,
+  walkForNestedFontCalls,
+  walkForUnconsumedReferences,
+} from './ast-walk.js';
 
-// ── AST node types (minimal subset of estree) ────────────────────────────────
+export type { FlaggedUsage } from './ast-walk.js';
 
-interface AstNode {
-  type: string;
-  [key: string]: unknown;
-}
+// ── AST node types (font-config-specific, on top of ast-walk.ts's base) ──────
 
 interface LiteralNode extends AstNode {
   type: 'Literal';
@@ -48,26 +52,6 @@ interface PropertyNode extends AstNode {
   value: AstNode;
 }
 
-interface IdentifierNode extends AstNode {
-  type: 'Identifier';
-  name: string;
-}
-
-// ── Offset → line/column helper ──────────────────────────────────────────────
-
-/** Convert a 0-based byte offset into a 1-based line and 0-based column. */
-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 };
-}
-
 // ── Core AST extraction helpers ──────────────────────────────────────────────
 
 /**
@@ -166,63 +150,7 @@ function objectProperties(node: ObjectExpressionNode): Map<string, AstNode> {
 export function extractFontConfigAst(callSource: string): GoogleFontConfig | null {
   const node = parseExpression(callSource);
   if (!node || node.type !== 'ObjectExpression') return null;
-
-  const props = objectProperties(node as ObjectExpressionNode);
-  const config: GoogleFontConfig = {};
-
-  // subsets: string[]
-  const subsetsNode = props.get('subsets');
-  if (subsetsNode) {
-    const arr = extractStringArray(subsetsNode);
-    if (arr) config.subsets = arr;
-  }
-
-  // weight: string | string[]
-  const weightNode = props.get('weight');
-  if (weightNode) {
-    const arr = extractStringArray(weightNode);
-    if (arr) {
-      config.weight = arr;
-    } else {
-      const s = extractString(weightNode);
-      if (s !== undefined) config.weight = s;
-    }
-  }
-
-  // display: string
-  const displayNode = props.get('display');
-  if (displayNode) {
-    const s = extractString(displayNode);
-    if (s !== undefined) config.display = s as GoogleFontConfig['display'];
-  }
-
-  // variable: string
-  const variableNode = props.get('variable');
-  if (variableNode) {
-    const s = extractString(variableNode);
-    if (s !== undefined) config.variable = s;
-  }
-
-  // style: string | string[]
-  const styleNode = props.get('style');
-  if (styleNode) {
-    const arr = extractStringArray(styleNode);
-    if (arr) {
-      config.style = arr;
-    } else {
-      const s = extractString(styleNode);
-      if (s !== undefined) config.style = s;
-    }
-  }
-
-  // preload: boolean
-  const preloadNode = props.get('preload');
-  if (preloadNode) {
-    const b = extractBoolean(preloadNode);
-    if (b !== undefined) config.preload = b;
-  }
-
-  return config;
+  return extractGoogleConfig(node as ObjectExpressionNode);
 }
 
 // ── Local font config extraction ─────────────────────────────────────────────
@@ -265,47 +193,7 @@ function extractLocalFontSrcEntry(node: AstNode): LocalFontSrc | null {
 export function extractLocalFontConfigAst(callSource: string): LocalFontConfig | null {
   const node = parseExpression(callSource);
   if (!node || node.type !== 'ObjectExpression') return null;
-
-  const props = objectProperties(node as ObjectExpressionNode);
-
-  // display: string
-  const displayNode = props.get('display');
-  const display = displayNode
-    ? (extractString(displayNode) as LocalFontConfig['display'])
-    : undefined;
-
-  // variable: string
-  const variableNode = props.get('variable');
-  const variable = variableNode ? extractString(variableNode) : undefined;
-
-  // family: string
-  const familyNode = props.get('family');
-  const family = familyNode ? extractString(familyNode) : undefined;
-
-  // src: string | LocalFontSrc[]
-  const srcNode = props.get('src');
-  if (!srcNode) return null;
-
-  // String form: src: './fonts/MyFont.woff2'
-  const srcString = extractString(srcNode);
-  if (srcString !== undefined) {
-    return { src: srcString, display, variable, family };
-  }
-
-  // Array form: src: [{ path: '...', weight: '...' }, ...]
-  if (srcNode.type === 'ArrayExpression') {
-    const arr = srcNode as ArrayExpressionNode;
-    const entries: LocalFontSrc[] = [];
-    for (const elem of arr.elements) {
-      const entry = extractLocalFontSrcEntry(elem);
-      if (!entry) return null;
-      entries.push(entry);
-    }
-    if (entries.length === 0) return null;
-    return { src: entries, display, variable, family };
-  }
-
-  return null;
+  return extractLocalConfig(node as ObjectExpressionNode);
 }
 
 // ── Dynamic call detection ───────────────────────────────────────────────────
@@ -329,51 +217,7 @@ export function detectDynamicFontCallAst(source: string, importedNames: string[]
   }
 
   const nameSet = new Set(importedNames);
-  const result = walkForDynamicCalls(ast as unknown as AstNode, nameSet, source);
-  return result;
-}
-
-/**
- * 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).
- */
-function walkForDynamicCalls(node: AstNode, names: Set<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 AstNode & { start: number }).start;
-        const argEnd = (args[0] as AstNode & { end: number }).end;
-        const argText = source.slice(argStart, argEnd);
-        const calleeName = (callee as IdentifierNode).name;
-        return `${calleeName}(${argText})`;
-      }
-    }
-  }
-
-  // Walk all child properties
-  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) {
-          const result = walkForDynamicCalls(item as AstNode, names, source);
-          if (result) return result;
-        }
-      }
-    } else if (child && typeof child === 'object' && (child as AstNode).type) {
-      const result = walkForDynamicCalls(child as AstNode, names, source);
-      if (result) return result;
-    }
-  }
-
-  return null;
+  return walkForDynamicCalls(ast as unknown as AstNode, nameSet, source);
 }
 
 // ── AST-node-level config extraction ─────────────────────────────────────────
@@ -554,7 +398,12 @@ export interface FontCallSite {
 export interface FontAnalysis {
   bindings: FontBinding[];
   callSites: FontCallSite[];
-  /** Import nodes that should be removed (deduplicated). */
+  /**
+   * Import nodes that should be removed (deduplicated). Only imports that
+   * produced at least one font binding are listed — removing an import
+   * whose bindings the transform doesn't rewrite (e.g. a namespace
+   * import) would leave dangling references behind.
+   */
   importNodesToRemove: Array<{ start: number; end: number }>;
   /** First dynamic call expression text, or `null`. */
   dynamicCall: string | null;
@@ -562,12 +411,21 @@ export interface FontAnalysis {
    * Font calls found in nested scopes (functions, if-blocks, etc.).
    * These are errors — font calls must be module-level.
    */
-  nestedCalls: Array<{ name: string; line: number; column: number }>;
-}
-
-interface PositionedNode extends AstNode {
-  start: number;
-  end: number;
+  nestedCalls: FlaggedUsage[];
+  /**
+   * Namespace imports of font modules (`import * as fonts from ...`).
+   * These are errors — the transform cannot rewrite `fonts.Inter(...)`
+   * member calls, so the fonts would silently never load.
+   */
+  namespaceImports: FlaggedUsage[];
+  /**
+   * References to font bindings that were not consumed by a recognized
+   * call site (`export default Inter({...})`, object-literal nesting,
+   * member access on the call result, aliasing, re-exports). These are
+   * errors — the import is removed, so any leftover reference would be a
+   * silent runtime ReferenceError.
+   */
+  unsupportedUsages: FlaggedUsage[];
 }
 
 interface ImportDeclarationNode extends PositionedNode {
@@ -661,6 +519,7 @@ export function findFontCallSites(source: string): FontAnalysis | null {
   // Step 1: Find all font import declarations and build the bindings list.
   const bindings: FontBinding[] = [];
   const importNodesToRemove: Array<{ start: number; end: number }> = [];
+  const namespaceImports: FlaggedUsage[] = [];
 
   for (const stmt of program.body) {
     if (!isImportDeclaration(stmt)) continue;
@@ -672,8 +531,10 @@ export function findFontCallSites(source: string): FontAnalysis | null {
     else if (LOCAL_FONT_SOURCES.has(specSource)) provider = 'local';
     if (!provider) continue;
 
+    let producedBinding = false;
     for (const spec of importDecl.specifiers) {
       if (spec.type === 'ImportSpecifier' && provider === 'google') {
+        producedBinding = true;
         bindings.push({
           localName: spec.local.name,
           importedName: spec.imported?.name ?? spec.local.name,
@@ -681,27 +542,39 @@ export function findFontCallSites(source: string): FontAnalysis | null {
           importNode: importDecl,
         });
       } else if (spec.type === 'ImportDefaultSpecifier' && provider === 'local') {
+        producedBinding = true;
         bindings.push({
           localName: spec.local.name,
           importedName: 'default',
           provider,
           importNode: importDecl,
         });
+      } else if (spec.type === 'ImportNamespaceSpecifier') {
+        // `import * as fonts from ...` cannot be rewritten — the transform
+        // only matches direct identifier calls, so `fonts.Inter(...)` would
+        // silently fall through to the runtime fallback module and never
+        // load a real font. Collected as a build error.
+        const pos = offsetToLineColumn(source, spec.start);
+        namespaceImports.push({ name: spec.local.name, line: pos.line, column: pos.column });
       }
-      // ImportNamespaceSpecifier (`import * as fonts from ...`) is not
-      // currently supported — the old regex didn't handle it either.
-      // If we add it later, we'd need to also handle `fonts.Inter(...)`
-      // member expressions in the call-site walk.
     }
 
-    importNodesToRemove.push({ start: stmt.start, end: stmt.end });
+    // Only remove imports whose bindings the transform actually rewrites.
+    // Removing an import that produced no binding (namespace imports,
+    // default imports of the google module) would orphan its references.
+    if (producedBinding) {
+      importNodesToRemove.push({ start: stmt.start, end: stmt.end });
+    }
   }
 
-  if (bindings.length === 0) return null;
+  if (bindings.length === 0 && namespaceImports.length === 0) return null;
 
   // Step 2: Walk the AST for CallExpression nodes whose callee is a font binding.
   const bindingsByName = new Map(bindings.map((b) => [b.localName, b]));
   const callSites: FontCallSite[] = [];
+  // Start offsets of recognized (and dynamic-flagged) CallExpressions, so
+  // the unsupported-reference walk in step 4 can skip them.
+  const consumedCallStarts = new Set<number>();
   let dynamicCall: string | null = null;
 
   for (const stmt of program.body) {
@@ -720,6 +593,7 @@ export function findFontCallSites(source: string): FontAnalysis | null {
         if (!site) continue;
 
         if (site === 'dynamic') {
+          consumedCallStarts.add(call.start);
           if (!dynamicCall && isIdentifier(call.callee)) {
             const argStart = call.arguments[0].start;
             const argEnd = call.arguments[0].end;
@@ -731,6 +605,7 @@ export function findFontCallSites(source: string): FontAnalysis | null {
         const assignedName = isIdentifier(declarator.id) ? declarator.id.name : null;
 
         const { line, column } = offsetToLineColumn(source, call.start);
+        consumedCallStarts.add(call.start);
         callSites.push({
           binding: site.binding,
           assignedName,
@@ -750,6 +625,7 @@ export function findFontCallSites(source: string): FontAnalysis | null {
         const site = matchCallExpression(call, bindingsByName, source);
         if (site && site !== 'dynamic') {
           const { line, column } = offsetToLineColumn(source, call.start);
+          consumedCallStarts.add(call.start);
           callSites.push({
             binding: site.binding,
             assignedName: null,
@@ -759,10 +635,13 @@ export function findFontCallSites(source: string): FontAnalysis | null {
             line,
             column,
           });
-        } else if (site === 'dynamic' && !dynamicCall && isIdentifier(call.callee)) {
-          const argStart = call.arguments[0].start;
-          const argEnd = call.arguments[0].end;
-          dynamicCall = `${call.callee.name}(${source.slice(argStart, argEnd)})`;
+        } else if (site === 'dynamic') {
+          consumedCallStarts.add(call.start);
+          if (!dynamicCall && isIdentifier(call.callee)) {
+            const argStart = call.arguments[0].start;
+            const argEnd = call.arguments[0].end;
+            dynamicCall = `${call.callee.name}(${source.slice(argStart, argEnd)})`;
+          }
         }
       }
     }
@@ -771,75 +650,38 @@ export function findFontCallSites(source: string): FontAnalysis | null {
   // Step 3: Walk nested scopes to find font calls that aren't module-level.
   // Font calls must be at module scope (same constraint as Next.js).
   // If the import is removed but a nested call remains, it's a ReferenceError.
-  const nestedCalls: Array<{ name: string; line: number; column: number }> = [];
+  const nestedCalls: FlaggedUsage[] = [];
   for (const stmt of program.body) {
     if (stmt.type === 'ImportDeclaration') continue;
     walkForNestedFontCalls(stmt as AstNode, bindingsByName, source, nestedCalls, false);
   }
 
-  return { bindings, callSites, importNodesToRemove, dynamicCall, nestedCalls };
-}
-
-/**
- * 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.
- */
-function walkForNestedFontCalls(
-  node: AstNode,
-  bindings: Map<string, FontBinding>,
-  source: string,
-  out: Array<{ name: string; line: number; column: number }>,
-  isNested: boolean
-): void {
-  if (!node || typeof node !== 'object') return;
-
-  if (node.type === 'CallExpression') {
-    const callee = node.callee as AstNode;
-    if (isNested && callee.type === 'Identifier' && bindings.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
-    }
-  }
-
-  // These node types introduce a nested scope — any font call inside is an error.
-  const scopeTypes = new Set([
-    'FunctionDeclaration',
-    'FunctionExpression',
-    'ArrowFunctionExpression',
-    'IfStatement',
-    'ForStatement',
-    'ForInStatement',
-    'ForOfStatement',
-    'WhileStatement',
-    'DoWhileStatement',
-    'SwitchStatement',
-    'TryStatement',
-    'BlockStatement',
-    'ClassDeclaration',
-    'ClassExpression',
-  ]);
-  const enterNested = isNested || scopeTypes.has(node.type);
-
-  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) {
-          walkForNestedFontCalls(item as AstNode, bindings, source, out, enterNested);
-        }
-      }
-    } else if (child && typeof child === 'object' && (child as AstNode).type) {
-      walkForNestedFontCalls(child as AstNode, bindings, source, out, enterNested);
-    }
-  }
+  // Step 4: Walk for references to font bindings that were not consumed by
+  // a recognized call site. The transform removes the import declarations,
+  // so any leftover reference (`export default Inter({...})`, object-literal
+  // nesting, `Inter({...}).className`, `const f = Inter`, `export { Inter }`)
+  // would become a silent runtime ReferenceError. Collected as build errors.
+  const unsupportedUsages: FlaggedUsage[] = [];
+  for (const stmt of program.body) {
+    if (stmt.type === 'ImportDeclaration') continue;
+    walkForUnconsumedReferences(
+      stmt as AstNode,
+      bindingsByName,
+      consumedCallStarts,
+      source,
+      unsupportedUsages
+    );
+  }
+
+  return {
+    bindings,
+    callSites,
+    importNodesToRemove,
+    dynamicCall,
+    nestedCalls,
+    namespaceImports,
+    unsupportedUsages,
+  };
 }
 
 /**

package/src/fonts/bundle.ts

@@ -10,9 +10,9 @@
  */
 
 import { readFileSync, existsSync } from 'node:fs';
-import { resolve, normalize, extname } from 'node:path';
+import { resolve, normalize } from 'node:path';
 import type { ManifestFontEntry, BuildManifest } from '../server/build-manifest.js';
-import { contentHash } from './google.js';
+import { fontOutputBasename, fontUrlPrefix, FONT_OUTPUT_DIR } from './paths.js';
 
 /**
  * Minimal shape of the asset descriptor accepted by Rollup's `emitFile`.
@@ -63,7 +63,7 @@ export function emitFontAssets(
   for (const cf of pipeline.uniqueCachedFiles()) {
     emitFile({
       type: 'asset',
-      fileName: `_timber/fonts/${cf.hashedFilename}`,
+      fileName: `${FONT_OUTPUT_DIR}/${cf.hashedFilename}`,
       source: cf.data,
     });
   }
@@ -77,11 +77,11 @@ export function emitFontAssets(
         warn(`Local font file not found: ${absolutePath}`);
         continue;
       }
-      const filename = src.hashedBasename ?? src.path.split('/').pop() ?? src.path;
+      const filename = src.hashedBasename ?? fontOutputBasename(src.path);
       const data = readFileSync(absolutePath);
       emitFile({
         type: 'asset',
-        fileName: `_timber/fonts/${filename}`,
+        fileName: `${FONT_OUTPUT_DIR}/${filename}`,
         source: data,
       });
     }
@@ -95,8 +95,15 @@ export function emitFontAssets(
  * `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): void {
+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()) {
@@ -104,10 +111,10 @@ export function writeFontManifest(pipeline: FontPipeline, buildManifest: BuildMa
 
     if (entry.provider === 'local' && entry.localSources) {
       for (const src of entry.localSources) {
-        const filename = src.hashedBasename ?? src.path.split('/').pop() ?? src.path;
+        const filename = src.hashedBasename ?? fontOutputBasename(src.path);
         const format = inferFontFormat(src.path);
         manifestEntries.push({
-          href: `/_timber/fonts/${filename}`,
+          href: `${urlPrefix}/${filename}`,
           format,
           crossOrigin: 'anonymous',
         });
@@ -115,7 +122,7 @@ export function writeFontManifest(pipeline: FontPipeline, buildManifest: BuildMa
     } else if (entry.cachedFiles) {
       for (const cf of entry.cachedFiles) {
         manifestEntries.push({
-          href: `/_timber/fonts/${cf.hashedFilename}`,
+          href: `${urlPrefix}/${cf.hashedFilename}`,
           format: 'woff2',
           crossOrigin: 'anonymous',
         });

package/src/fonts/dev-middleware.ts

@@ -14,6 +14,7 @@ import type { ViteDevServer } from 'vite';
 import { readFileSync, existsSync } from 'node:fs';
 import { resolve, normalize } from 'node:path';
 import type { FontPipeline } from './pipeline.js';
+import { fontOutputBasename, fontUrlPrefix } from './paths.js';
 
 const FONT_MIME_TYPES: Record<string, string> = {
   woff2: 'font/woff2',
@@ -30,12 +31,17 @@ const FONT_MIME_TYPES: Record<string, string> = {
  * captured by reference so that fonts registered after `configureServer`
  * runs (during transform) are still resolvable.
  */
-export function installFontDevMiddleware(server: ViteDevServer, pipeline: FontPipeline): void {
+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('/_timber/fonts/')) return next();
+    if (!url || !url.startsWith(urlPrefix)) return next();
 
-    const requestedFilename = url.slice('/_timber/fonts/'.length);
+    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('/')) {
@@ -50,7 +56,7 @@ export function installFontDevMiddleware(server: ViteDevServer, pipeline: FontPi
     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() ?? '';
+        const basename = fontOutputBasename(src.path);
         if (basename !== requestedFilename && src.hashedBasename !== requestedFilename) continue;
 
         const absolutePath = normalize(resolve(src.path));
@@ -62,7 +68,12 @@ export function installFontDevMiddleware(server: ViteDevServer, pipeline: FontPi
         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');
+        // 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;

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

@@ -19,6 +19,7 @@ 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 { fontUrlPrefix } from './paths.js';
 
 /** Google Fonts CSS API v2 base URL. */
 const GOOGLE_FONTS_API = 'https://fonts.googleapis.com/css2';
@@ -281,15 +282,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,