@timber-js/app 0.2.0-alpha.247 → 0.2.0-alpha.249

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/dist/fonts/ast.d.ts.map +1 -1
  2. package/dist/fonts/bundle.d.ts +26 -8
  3. package/dist/fonts/bundle.d.ts.map +1 -1
  4. package/dist/fonts/fallbacks.d.ts +46 -8
  5. package/dist/fonts/fallbacks.d.ts.map +1 -1
  6. package/dist/fonts/font-metrics.d.ts +54 -0
  7. package/dist/fonts/font-metrics.d.ts.map +1 -0
  8. package/dist/fonts/local-fallback.d.ts +64 -0
  9. package/dist/fonts/local-fallback.d.ts.map +1 -0
  10. package/dist/fonts/local.d.ts.map +1 -1
  11. package/dist/fonts/sfnt.d.ts +30 -0
  12. package/dist/fonts/sfnt.d.ts.map +1 -0
  13. package/dist/fonts/transform.d.ts.map +1 -1
  14. package/dist/fonts/types.d.ts +29 -0
  15. package/dist/fonts/types.d.ts.map +1 -1
  16. package/dist/index.d.ts.map +1 -1
  17. package/dist/index.js +1262 -351
  18. package/dist/index.js.map +1 -1
  19. package/dist/plugins/build-manifest.d.ts +5 -0
  20. package/dist/plugins/build-manifest.d.ts.map +1 -1
  21. package/dist/plugins/fonts.d.ts.map +1 -1
  22. package/dist/plugins/route-css.d.ts +63 -0
  23. package/dist/plugins/route-css.d.ts.map +1 -0
  24. package/package.json +1 -1
  25. package/src/fonts/ast.ts +35 -2
  26. package/src/fonts/bundle.ts +71 -17
  27. package/src/fonts/fallbacks.ts +92 -28
  28. package/src/fonts/font-metrics.ts +236 -0
  29. package/src/fonts/local-fallback.ts +249 -0
  30. package/src/fonts/local.ts +14 -1
  31. package/src/fonts/pipeline.ts +6 -3
  32. package/src/fonts/sfnt.ts +185 -0
  33. package/src/fonts/transform.ts +4 -1
  34. package/src/fonts/types.ts +29 -0
  35. package/src/index.ts +2 -0
  36. package/src/plugins/build-manifest.ts +1 -1
  37. package/src/plugins/fonts.ts +28 -2
  38. package/src/plugins/route-css.ts +237 -0
@@ -18,6 +18,7 @@
18
18
  import type { Plugin } from 'vite';
19
19
  import type { PluginContext } from '../plugin-context.ts';
20
20
  import { type BuildManifest } from '../server/build-manifest.ts';
21
+ import type { SegmentNode, RouteFile } from '../routing/types.ts';
21
22
  interface OutputChunk {
22
23
  type: 'chunk';
23
24
  fileName: string;
@@ -73,6 +74,10 @@ export declare function parseViteManifest(viteManifest: Record<string, ViteManif
73
74
  * Keys are input file paths relative to root.
74
75
  */
75
76
  export declare function buildManifestFromBundle(bundle: OutputBundle, base: string, root: string): BuildManifest;
77
+ /**
78
+ * Collect all route file paths (layout, page) from the route tree.
79
+ */
80
+ export declare function collectRouteFilePaths(node: SegmentNode<RouteFile>): string[];
76
81
  /**
77
82
  * Create the timber-build-manifest Vite plugin.
78
83
  *
@@ -1 +1 @@
1
- {"version":3,"file":"build-manifest.d.ts","sourceRoot":"","sources":["../../src/plugins/build-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAkB,MAAM,MAAM,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAKvF,UAAU,WAAW;IACnB,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;KAAE,CAAC;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC3E;AAED,UAAU,WAAW;IACnB,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,KAAK,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,CAAC,CAAC;AAK9D;;;GAGG;AACH,UAAU,iBAAiB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,EAC/C,IAAI,EAAE,MAAM,GACX,aAAa,CAmBf;AAqCD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,aAAa,CA0Cf;AAiID;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAqI9D"}
1
+ {"version":3,"file":"build-manifest.d.ts","sourceRoot":"","sources":["../../src/plugins/build-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAkB,MAAM,MAAM,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACvF,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAIlE,UAAU,WAAW;IACnB,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;KAAE,CAAC;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC3E;AAED,UAAU,WAAW;IACnB,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,KAAK,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,CAAC,CAAC;AAK9D;;;GAGG;AACH,UAAU,iBAAiB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,EAC/C,IAAI,EAAE,MAAM,GACX,aAAa,CAmBf;AAqCD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,aAAa,CA0Cf;AAgED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,WAAW,CAAC,SAAS,CAAC,GAAG,MAAM,EAAE,CAO5E;AAuDD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAqI9D"}
@@ -1 +1 @@
1
- {"version":3,"file":"fonts.d.ts","sourceRoot":"","sources":["../../src/plugins/fonts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAiC,MAAM,MAAM,CAAC;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AA2BjE,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACtB,uBAAuB,EACvB,wBAAwB,GACzB,MAAM,uBAAuB,CAAC;AAE/B;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,kBAAkB,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IAClD;;;OAGG;IACH,aAAa,IAAI,MAAM,EAAE,CAAC;CAC3B;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,GAAG;IAAE,GAAG,EAAE,cAAc,CAAA;CAAE,CAgQhF"}
1
+ {"version":3,"file":"fonts.d.ts","sourceRoot":"","sources":["../../src/plugins/fonts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAiC,MAAM,MAAM,CAAC;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAiCjE,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACtB,uBAAuB,EACvB,wBAAwB,GACzB,MAAM,uBAAuB,CAAC;AAE/B;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,kBAAkB,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IAClD;;;OAGG;IACH,aAAa,IAAI,MAAM,EAAE,CAAC;CAC3B;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,GAAG;IAAE,GAAG,EAAE,cAAc,CAAA;CAAE,CAoRhF"}
@@ -0,0 +1,63 @@
1
+ /**
2
+ * timber-route-css — link font CSS that a route file reaches only through
3
+ * a plain (non-component) module.
4
+ *
5
+ * @vitejs/plugin-rsc renders a server component's stylesheets by wrapping
6
+ * the component in `import.meta.viteRsc.loadCss()`, which collects every
7
+ * CSS file the module reaches, directly or through other modules. But it
8
+ * only applies that wrap to a module that imports CSS **itself**
9
+ * (`rsc:rsc-css-export-transform`). A font is usually defined in a plain
10
+ * module, and the font's CSS import is injected there:
11
+ *
12
+ * ```ts
13
+ * // app/fonts.ts — the font's @font-face CSS is imported here
14
+ * export const body = localFont({ src: './TX-02.woff2' });
15
+ *
16
+ * // app/layout.tsx — imports no CSS of its own, so nothing is wrapped
17
+ * import { body } from './fonts';
18
+ * ```
19
+ *
20
+ * The page rendered with the font's class and no `@font-face`.
21
+ *
22
+ * This plugin gives such a route file a static import of an empty
23
+ * stylesheet, so plugin-rsc wraps it exactly as it wraps a layout that
24
+ * imports `globals.css`, and `loadCss()` collects the font CSS. The anchor
25
+ * is imported with `?inline`: plugin-rsc's wrap check counts it as a CSS
26
+ * import, while its collector skips `?inline` ids (no `<link>` in dev) and
27
+ * the build compiles it to a JS string (no asset).
28
+ *
29
+ * **Only route files that reach a font module are touched.** The wrap is
30
+ * not free: in dev it renders an async `Resources` component beside the
31
+ * route component, which shifts shell timing (a delayed `deny()` can land
32
+ * before the shell commits). Wrapping every route file changed dev status
33
+ * codes in apps with no fonts at all. Route files that import CSS are
34
+ * wrapped by plugin-rsc already; this adds only the font case.
35
+ *
36
+ * A route file is transformed before its imports, so the font pipeline
37
+ * can't answer "does this reach a font?" yet. The plugin scans source
38
+ * instead: it follows the route file's static imports through local,
39
+ * server-side modules (not node_modules, not `'use client'` — a client
40
+ * module's CSS rides its client reference) and stops at the first module
41
+ * that imports a font loader. Scans are cached per file by mtime.
42
+ *
43
+ * Not touched: `'use client'` route files (a statement before the directive
44
+ * would cancel it), MDX (frontmatter must stay on line 1), and route.ts /
45
+ * middleware.ts / access.ts / metadata routes (not components).
46
+ *
47
+ * Known limit (dev): adding the first font call to a module a route file
48
+ * already imports takes effect when the route file is next transformed
49
+ * (edit or restart), because the route file's own source did not change.
50
+ *
51
+ * Design doc: 24-fonts.md §"Step 3: @font-face Generation"
52
+ */
53
+ import { type Plugin } from 'vite';
54
+ import type { PluginContext } from '../plugin-context.ts';
55
+ import type { SegmentNode } from '../routing/types.ts';
56
+ /** The import the transform adds. See the module comment for `?inline`. */
57
+ export declare const ROUTE_CSS_ANCHOR_IMPORT = "import 'virtual:timber-route-css.css?inline';\n";
58
+ /** Static value import/re-export specifiers of a module. */
59
+ export declare function staticSpecifiers(code: string, filename: string): string[];
60
+ /** Every route file that exports a server component plugin-rsc may wrap. */
61
+ export declare function collectComponentRouteFiles(node: SegmentNode, into?: Set<string>): Set<string>;
62
+ export declare function timberRouteCss(ctx: PluginContext): Plugin;
63
+ //# sourceMappingURL=route-css.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"route-css.d.ts","sourceRoot":"","sources":["../../src/plugins/route-css.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAIH,OAAO,EAAY,KAAK,MAAM,EAAE,MAAM,MAAM,CAAC;AAC7C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D,OAAO,KAAK,EAAa,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAIlE,2EAA2E;AAC3E,eAAO,MAAM,uBAAuB,oDAAoC,CAAC;AAyBzE,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CA4BzE;AAED,4EAA4E;AAC5E,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,WAAW,EACjB,IAAI,cAAoB,GACvB,GAAG,CAAC,MAAM,CAAC,CAQb;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAuGzD"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@timber-js/app",
3
- "version": "0.2.0-alpha.247",
3
+ "version": "0.2.0-alpha.249",
4
4
  "description": "Vite-native React framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript",
5
5
  "keywords": [
6
6
  "cloudflare-workers",
package/src/fonts/ast.ts CHANGED
@@ -299,6 +299,17 @@ function extractGoogleConfig(objNode: ObjectExpressionNode): GoogleFontConfig {
299
299
  return config;
300
300
  }
301
301
 
302
+ function isAdjustFontFallback(
303
+ value: boolean | string | undefined
304
+ ): value is NonNullable<LocalFontConfig['adjustFontFallback']> {
305
+ return (
306
+ typeof value === 'boolean' ||
307
+ value === 'Arial' ||
308
+ value === 'Times New Roman' ||
309
+ value === 'monospace'
310
+ );
311
+ }
312
+
302
313
  /** Shared implementation for LocalFontConfig extraction from an object node. */
303
314
  function extractLocalConfig(objNode: ObjectExpressionNode): LocalFontConfig | null {
304
315
  const props = objectProperties(objNode);
@@ -314,12 +325,34 @@ function extractLocalConfig(objNode: ObjectExpressionNode): LocalFontConfig | nu
314
325
  const familyNode = props.get('family');
315
326
  const family = familyNode ? extractString(familyNode) : undefined;
316
327
 
328
+ // Optional options: present-but-not-static is a hard failure (the caller
329
+ // reports it), never a silent default.
330
+ const options: Pick<LocalFontConfig, 'preload' | 'adjustFontFallback' | 'fallback'> = {};
331
+ const preloadNode = props.get('preload');
332
+ if (preloadNode) {
333
+ const b = extractBoolean(preloadNode);
334
+ if (b === undefined) return null;
335
+ options.preload = b;
336
+ }
337
+ const adjustNode = props.get('adjustFontFallback');
338
+ if (adjustNode) {
339
+ const value = extractBoolean(adjustNode) ?? extractString(adjustNode);
340
+ if (!isAdjustFontFallback(value)) return null;
341
+ options.adjustFontFallback = value;
342
+ }
343
+ const fallbackNode = props.get('fallback');
344
+ if (fallbackNode) {
345
+ const list = extractStringArray(fallbackNode);
346
+ if (!list) return null;
347
+ options.fallback = list;
348
+ }
349
+
317
350
  const srcNode = props.get('src');
318
351
  if (!srcNode) return null;
319
352
 
320
353
  const srcString = extractString(srcNode);
321
354
  if (srcString !== undefined) {
322
- return { src: srcString, display, variable, family };
355
+ return { src: srcString, display, variable, family, ...options };
323
356
  }
324
357
 
325
358
  if (srcNode.type === 'ArrayExpression') {
@@ -331,7 +364,7 @@ function extractLocalConfig(objNode: ObjectExpressionNode): LocalFontConfig | nu
331
364
  entries.push(entry);
332
365
  }
333
366
  if (entries.length === 0) return null;
334
- return { src: entries, display, variable, family };
367
+ return { src: entries, display, variable, family, ...options };
335
368
  }
336
369
 
337
370
  return null;
@@ -89,50 +89,104 @@ export function emitFontAssets(
89
89
  }
90
90
 
91
91
  /**
92
- * Populate `buildManifest.fonts` with `ManifestFontEntry[]` keyed by the
93
- * absolute importer path. This matches the runtime route manifest's
94
- * `filePath` values (which are absolute) and is consistent with how
95
- * `buildManifest.css` keys work after TIM-1014.
92
+ * Map each font importer to the route files (layouts and pages) that
93
+ * import it, directly or through any chain of modules.
96
94
  *
97
- * All font binaries use content-hashed filenames for immutable caching.
98
- * Hrefs are prefixed with Vite's resolved `base` so they match the URLs
99
- * the platform serves the emitted binaries under.
95
+ * A font is usually defined in a shared module (`app/fonts.ts`) and applied
96
+ * in a layout that imports it. The manifest is read per matched route
97
+ * segment (`collectRouteFonts`), so an entry keyed only by the defining
98
+ * module would never be found. Walking *up* the importer graph from each
99
+ * font module is cheap — there are a handful of font modules, and the walk
100
+ * stops at modules already visited.
101
+ *
102
+ * `getImporters` is Rollup's `getModuleInfo(id)?.importers` from the RSC
103
+ * build, where layouts and pages are real modules. A route file reached
104
+ * through another route file (a page importing a layout's module) still
105
+ * counts: the font is in that page's graph.
106
+ */
107
+ export function mapFontImportersToRoutes(
108
+ importers: Iterable<string>,
109
+ routeFiles: Iterable<string>,
110
+ getImporters: (id: string) => readonly string[] | null | undefined
111
+ ): Map<string, string[]> {
112
+ const routeSet = new Set(routeFiles);
113
+ const result = new Map<string, string[]>();
114
+ for (const importer of importers) {
115
+ const routes: string[] = [];
116
+ const visited = new Set<string>([importer]);
117
+ const queue = [importer];
118
+ while (queue.length > 0) {
119
+ const id = queue.shift()!;
120
+ if (routeSet.has(id)) routes.push(id);
121
+ for (const parent of getImporters(id) ?? []) {
122
+ if (visited.has(parent)) continue;
123
+ visited.add(parent);
124
+ queue.push(parent);
125
+ }
126
+ }
127
+ result.set(importer, routes);
128
+ }
129
+ return result;
130
+ }
131
+
132
+ /** Only upright faces are preloaded — italics are rarely above the fold. */
133
+ const isUpright = (style: string | undefined) => style === undefined || style === 'normal';
134
+
135
+ /**
136
+ * Populate `buildManifest.fonts` with the font binaries to preload, keyed
137
+ * by absolute path. The keys are the font's importer plus every route file
138
+ * that reaches it (`routesByImporter`, from `mapFontImportersToRoutes`), so
139
+ * `collectRouteFonts` finds a font defined outside the layout that applies
140
+ * it. Keys are absolute, matching the route manifest's `filePath` values
141
+ * (and `buildManifest.css`, TIM-1014).
142
+ *
143
+ * Fonts with `preload: false` and non-upright faces are left out. All
144
+ * hrefs are content-hashed and prefixed with Vite's resolved `base`.
100
145
  */
101
146
  export function writeFontManifest(
102
147
  pipeline: FontPipeline,
103
148
  buildManifest: BuildManifest,
104
- base = '/'
149
+ base = '/',
150
+ routesByImporter?: ReadonlyMap<string, readonly string[]>
105
151
  ): void {
106
152
  const urlPrefix = fontUrlPrefix(base);
107
- const fontsByImporter = new Map<string, ManifestFontEntry[]>();
153
+ const fontsByKey = new Map<string, Map<string, ManifestFontEntry>>();
108
154
 
109
155
  for (const entry of pipeline.entries()) {
110
- const manifestEntries = fontsByImporter.get(entry.importer) ?? [];
156
+ if (entry.preload === false) continue;
157
+ const preloads: ManifestFontEntry[] = [];
111
158
 
112
159
  if (entry.provider === 'local' && entry.localSources) {
113
160
  for (const src of entry.localSources) {
161
+ if (!isUpright(src.style)) continue;
114
162
  const filename = src.hashedBasename ?? fontOutputBasename(src.path);
115
- const format = inferFontFormat(src.path);
116
- manifestEntries.push({
163
+ preloads.push({
117
164
  href: `${urlPrefix}/${filename}`,
118
- format,
165
+ format: inferFontFormat(src.path),
119
166
  crossOrigin: 'anonymous',
120
167
  });
121
168
  }
122
169
  } else if (entry.cachedFiles) {
123
170
  for (const cf of entry.cachedFiles) {
124
- manifestEntries.push({
171
+ if (!isUpright(cf.face.style)) continue;
172
+ preloads.push({
125
173
  href: `${urlPrefix}/${cf.hashedFilename}`,
126
174
  format: 'woff2',
127
175
  crossOrigin: 'anonymous',
128
176
  });
129
177
  }
130
178
  }
179
+ if (preloads.length === 0) continue;
131
180
 
132
- fontsByImporter.set(entry.importer, manifestEntries);
181
+ const keys = new Set([entry.importer, ...(routesByImporter?.get(entry.importer) ?? [])]);
182
+ for (const key of keys) {
183
+ const byHref = fontsByKey.get(key) ?? new Map<string, ManifestFontEntry>();
184
+ for (const preload of preloads) byHref.set(preload.href, preload);
185
+ fontsByKey.set(key, byHref);
186
+ }
133
187
  }
134
188
 
135
- for (const [importer, entries] of fontsByImporter) {
136
- buildManifest.fonts[importer] = entries;
189
+ for (const [key, byHref] of fontsByKey) {
190
+ buildManifest.fonts[key] = [...byHref.values()];
137
191
  }
138
192
  }
@@ -5,9 +5,15 @@
5
5
  * `size-adjust`, `ascent-override`, `descent-override`, and
6
6
  * `line-gap-override` to match custom font metrics and eliminate CLS.
7
7
  *
8
+ * Google fonts use the precomputed `FALLBACK_METRICS` table below. Local
9
+ * fonts compute their faces from the font file (`local-fallback.ts`); both
10
+ * paths produce `FallbackFace` values serialized by `generateFallbackFaceCss`.
11
+ *
8
12
  * Design doc: 24-fonts.md §"Step 4: Size-Adjusted Fallbacks"
9
13
  */
10
14
 
15
+ import type { FontCategory } from './font-metrics.ts';
16
+
11
17
  /**
12
18
  * Font metrics for size-adjusted fallback calculation.
13
19
  *
@@ -158,7 +164,8 @@ const SERIF_FAMILIES = new Set([
158
164
  'cormorant garamond',
159
165
  ]);
160
166
 
161
- export function getGenericFamily(family: string): string {
167
+ /** Guess a family's generic category from its name alone. */
168
+ export function getGenericFamily(family: string): FontCategory {
162
169
  const lc = family.toLowerCase();
163
170
  if (lc.includes('mono') || lc.includes('code')) return 'monospace';
164
171
  if ((lc.includes('serif') && !lc.includes('sans')) || SERIF_FAMILIES.has(lc)) {
@@ -167,59 +174,116 @@ export function getGenericFamily(family: string): string {
167
174
  return 'sans-serif';
168
175
  }
169
176
 
177
+ // ─── Fallback faces ──────────────────────────────────────────────────────
178
+
170
179
  /**
171
- * Generate the full CSS for a size-adjusted fallback font.
172
- *
173
- * This produces a complete @font-face block with override descriptors
174
- * that FontFaceDescriptor doesn't natively support.
180
+ * One size-adjusted fallback `@font-face`. Percentages are final CSS values
181
+ * (e.g. `107.64` → `size-adjust: 107.64%`).
175
182
  */
176
- export function generateFallbackCss(family: string): string | null {
177
- const metrics = FALLBACK_METRICS[family.toLowerCase()];
178
- if (!metrics) return null;
183
+ export interface FallbackFace {
184
+ /** `'<Family> Fallback'`. */
185
+ family: string;
186
+ /** System fonts tried in order, as `local()` sources. */
187
+ local: string[];
188
+ /** `font-weight` descriptor. Omitted for the regular face (defaults to normal). */
189
+ weight?: string;
190
+ sizeAdjust: number;
191
+ ascentOverride: number;
192
+ descentOverride: number;
193
+ lineGapOverride: number;
194
+ }
179
195
 
180
- const fallbackFamily = `${family} Fallback`;
196
+ /** The fallback family name for `family`. */
197
+ export function fallbackFamilyName(family: string): string {
198
+ return `${family} Fallback`;
199
+ }
181
200
 
201
+ /** Serialize a fallback face to an `@font-face` rule. */
202
+ export function generateFallbackFaceCss(face: FallbackFace): string {
182
203
  const lines = [
183
204
  '@font-face {',
184
- ` font-family: '${fallbackFamily}';`,
185
- ` src: local('${metrics.fallbackFont}');`,
186
- ` size-adjust: ${metrics.sizeAdjust}%;`,
187
- ` ascent-override: ${metrics.ascentOverride}%;`,
188
- ` descent-override: ${metrics.descentOverride}%;`,
189
- ` line-gap-override: ${metrics.lineGapOverride}%;`,
190
- '}',
205
+ ` font-family: '${face.family}';`,
206
+ ` src: ${face.local.map((name) => `local('${name}')`).join(', ')};`,
191
207
  ];
192
-
208
+ if (face.weight) lines.push(` font-weight: ${face.weight};`);
209
+ lines.push(
210
+ ` size-adjust: ${face.sizeAdjust}%;`,
211
+ ` ascent-override: ${face.ascentOverride}%;`,
212
+ ` descent-override: ${face.descentOverride}%;`,
213
+ ` line-gap-override: ${face.lineGapOverride}%;`,
214
+ '}'
215
+ );
193
216
  return lines.join('\n');
194
217
  }
195
218
 
196
219
  /**
197
- * Check whether fallback metrics are available for a font family.
220
+ * The fallback faces for a Google font, from the precomputed table. Empty
221
+ * when the family isn't in the table.
198
222
  */
223
+ export function googleFallbackFaces(family: string): FallbackFace[] {
224
+ const metrics = FALLBACK_METRICS[family.toLowerCase()];
225
+ if (!metrics) return [];
226
+ return [
227
+ {
228
+ family: fallbackFamilyName(family),
229
+ local: [metrics.fallbackFont],
230
+ sizeAdjust: metrics.sizeAdjust,
231
+ ascentOverride: metrics.ascentOverride,
232
+ descentOverride: metrics.descentOverride,
233
+ lineGapOverride: metrics.lineGapOverride,
234
+ },
235
+ ];
236
+ }
237
+
238
+ /** Check whether the Google fallback table has metrics for a family. */
199
239
  export function hasFallbackMetrics(family: string): boolean {
200
240
  return family.toLowerCase() in FALLBACK_METRICS;
201
241
  }
202
242
 
243
+ /**
244
+ * Generate the fallback `@font-face` CSS for a Google font, or `null` when
245
+ * the family isn't in the table.
246
+ */
247
+ export function generateFallbackCss(family: string): string | null {
248
+ const faces = googleFallbackFaces(family);
249
+ return faces.length > 0 ? faces.map(generateFallbackFaceCss).join('\n\n') : null;
250
+ }
251
+
252
+ // ─── Font stack ──────────────────────────────────────────────────────────
253
+
254
+ export interface FontStackOptions {
255
+ /** Generic family. Defaults to the name heuristic (`getGenericFamily`). */
256
+ generic?: FontCategory;
257
+ /** Whether a `'<Family> Fallback'` face exists. Defaults to the Google table. */
258
+ hasFallbackFace?: boolean;
259
+ /**
260
+ * Replaces the default generic tail (`system-ui, sans-serif`, etc.) —
261
+ * the `fallback` option of `next/font`. Entries are emitted verbatim.
262
+ */
263
+ fallback?: string[];
264
+ }
265
+
203
266
  /**
204
267
  * Build the full font stack string for a font, including its
205
268
  * size-adjusted fallback and a generic family.
206
269
  *
207
270
  * Example: `'Inter', 'Inter Fallback', system-ui, sans-serif`
208
271
  */
209
- export function buildFontStack(family: string): string {
210
- const generic = getGenericFamily(family);
211
- const hasMetrics = hasFallbackMetrics(family);
272
+ export function buildFontStack(family: string, options: FontStackOptions = {}): string {
273
+ const generic = options.generic ?? getGenericFamily(family);
274
+ const hasFallbackFace = options.hasFallbackFace ?? hasFallbackMetrics(family);
212
275
 
213
276
  const parts = [`'${family}'`];
214
- if (hasMetrics) parts.push(`'${family} Fallback'`);
277
+ if (hasFallbackFace) parts.push(`'${fallbackFamilyName(family)}'`);
215
278
 
216
- // Add system-ui for sans-serif fonts, ui-monospace for mono
217
- if (generic === 'monospace') {
218
- parts.push('ui-monospace');
219
- } else if (generic === 'sans-serif') {
220
- parts.push('system-ui');
279
+ if (options.fallback) {
280
+ parts.push(...options.fallback);
281
+ } else {
282
+ // system-ui for sans-serif fonts, ui-monospace for mono
283
+ if (generic === 'monospace') parts.push('ui-monospace');
284
+ else if (generic === 'sans-serif') parts.push('system-ui');
285
+ parts.push(generic);
221
286
  }
222
- parts.push(generic);
223
287
 
224
288
  return parts.join(', ');
225
289
  }