@timber-js/app 0.2.0-alpha.15 → 0.2.0-alpha.151

package/src/fonts/types.ts

@@ -7,6 +7,10 @@
  * Design doc: 24-fonts.md
  */
 
+// `CachedFont` lives in `google.ts`. Importing it here is type-only so
+// there is no runtime dependency cycle — TypeScript erases the import.
+import type { CachedFont } from './google.js';
+
 /** Configuration passed to a Google font function (e.g. `Inter({ ... })`). */
 export interface GoogleFontConfig {
   weight?: string | string[];
@@ -22,6 +26,8 @@ export interface LocalFontSrc {
   path: string;
   weight?: string;
   style?: string;
+  /** Content-hashed basename for production builds (e.g. `MyFont-Bold-a1b2c3d4.woff2`). */
+  hashedBasename?: string;
 }
 
 /** Configuration passed to `localFont()`. */
@@ -47,7 +53,16 @@ export interface FontResult {
   variable?: string;
 }
 
-/** Internal representation of a font extracted during static analysis. */
+/**
+ * Internal representation of a font extracted during static analysis.
+ *
+ * `ExtractedFont` is the **registration input** to `FontPipeline.register()`.
+ * Once a font has been registered the pipeline stores a `FontEntry` (which
+ * extends `ExtractedFont` with optional resolved `@font-face` descriptors
+ * and cached binary files). External code that needs to model a font that
+ * is not yet inside a pipeline (e.g. test fixtures) should use
+ * `ExtractedFont` directly.
+ */
 export interface ExtractedFont {
   /** Unique identifier for this font instance (e.g. `inter-400-normal-latin`). */
   id: string;
@@ -86,3 +101,39 @@ export interface FontFaceDescriptor {
   display?: string;
   unicodeRange?: string;
 }
+
+/**
+ * The unified per-font store entry held inside `FontPipeline`.
+ *
+ * Combines what used to live in three parallel maps:
+ *
+ * - `registry: Map<string, ExtractedFont>`            → the base extracted config
+ * - `googleFontFacesMap: Map<string, FontFaceDescriptor[]>` → `faces`
+ * - `cachedFonts: CachedFont[]` (flat, family-grouped)       → `cachedFiles`
+ *
+ * `pruneFor` drops the entry **and** all of its attached state in one
+ * operation, so future code paths cannot reintroduce a TIM-824-style
+ * desync between parallel maps.
+ *
+ * See TIM-829.
+ */
+export interface FontEntry extends ExtractedFont {
+  /**
+   * Pre-resolved `@font-face` descriptors. Populated in `buildStart`
+   * (production) or lazily in `load` (dev). For local fonts the descriptors
+   * are derived from the source list at CSS-generation time and are not
+   * stored here.
+   */
+  faces?: FontFaceDescriptor[];
+
+  /**
+   * Downloaded Google Font binaries that back this entry's `@font-face`
+   * declarations. Empty for local fonts and in dev mode (where Google fonts
+   * are served straight from the CDN).
+   *
+   * Multiple entries that share the same `family` will hold references to
+   * the same `CachedFont` objects. The bundle emitter dedupes by
+   * `hashedFilename` so each binary is written exactly once.
+   */
+  cachedFiles?: CachedFont[];
+}

package/src/fonts/virtual-modules.ts

@@ -0,0 +1,179 @@
+/**
+ * Virtual module source generators for the timber-fonts plugin.
+ *
+ * The plugin exposes three virtual modules:
+ *
+ * - `@timber/fonts/google` — exports Google font loader functions. The
+ *   transform hook replaces actual call sites with static `FontResult`
+ *   objects, so this module is only loaded as a fallback (e.g. when the
+ *   transform hook hasn't run yet, or when an unknown font is referenced
+ *   via the default export proxy).
+ * - `@timber/fonts/local` — exports `localFont()` as a fallback default.
+ * - `virtual:timber-font-css/<hash>.css` — per-importer CSS module that
+ *   holds the combined `@font-face` + fallback + class CSS for every
+ *   font registered under that importer. The transform hook injects a
+ *   side-effect `import 'virtual:timber-font-css/<hash>.css'` into each
+ *   file that calls a font function, so Vite's CSS pipeline picks it up
+ *   like any other CSS asset. @vitejs/plugin-rsc's `collectCss` walks
+ *   the RSC module graph, finds the virtual module, and injects a
+ *   `<link rel="stylesheet" data-rsc-css-href=...>` via React Float —
+ *   the same machinery component CSS rides on (TIM-828).
+ *
+ *   The `.css` suffix is load-bearing: Vite's `isCSSRequest` regex matches
+ *   on file extension, so keeping it in the virtual id is how we tell
+ *   Vite's CSS pipeline (dev HMR + build asset emission) that this
+ *   module is CSS. The old `virtual:timber-font-css-register` side-effect
+ *   module, `globalThis.__timber_font_css` channel, and inline `<style>`
+ *   tag in the RSC entry were all removed in TIM-828.
+ *
+ * Design doc: 24-fonts.md
+ */
+
+import { createHash } from 'node:crypto';
+import type { ExtractedFont } from './types.js';
+
+export const VIRTUAL_GOOGLE = '@timber/fonts/google';
+export const VIRTUAL_LOCAL = '@timber/fonts/local';
+export const RESOLVED_GOOGLE = '\0@timber/fonts/google';
+export const RESOLVED_LOCAL = '\0@timber/fonts/local';
+
+/**
+ * Prefix used for the per-importer virtual CSS modules. The full id is
+ * `virtual:timber-font-css/<hash>.css` where `<hash>` is a short SHA-256
+ * digest of the importer path. We encode the hash (not the path itself)
+ * so the id stays filesystem-safe and opaque to downstream consumers.
+ */
+export const VIRTUAL_FONT_CSS_PREFIX = 'virtual:timber-font-css/';
+export const VIRTUAL_FONT_CSS_SUFFIX = '.css';
+export const RESOLVED_FONT_CSS_PREFIX = '\0' + VIRTUAL_FONT_CSS_PREFIX;
+
+/**
+ * In-memory map from the short hash used in virtual module ids back to
+ * the absolute importer path. Populated by `virtualFontCssIdFor()` when
+ * the transform hook registers an importer and read by the plugin's
+ * `load` hook when Vite asks for the CSS content.
+ *
+ * Scoped to a single `FontPipeline` instance to avoid cross-plugin-
+ * instance collisions during multi-build pipelines.
+ */
+function stripIdDecorations(id: string): string {
+  const bare = id.startsWith('\0') ? id.slice(1) : id;
+  const qIdx = bare.indexOf('?');
+  return qIdx === -1 ? bare : bare.slice(0, qIdx);
+}
+
+export class VirtualFontCssIdMap {
+  private readonly map = new Map<string, string>();
+
+  /**
+   * Return a stable virtual module id for `importer`. Calling this twice
+   * with the same importer returns the same id. Registering under an
+   * existing hash is idempotent.
+   */
+  idFor(importer: string): string {
+    const hash = createHash('sha256').update(importer).digest('hex').slice(0, 16);
+    this.map.set(hash, importer);
+    return `${VIRTUAL_FONT_CSS_PREFIX}${hash}${VIRTUAL_FONT_CSS_SUFFIX}`;
+  }
+
+  /** Decode the importer from a resolved (or unresolved) virtual css id. */
+  importerFor(id: string): string | undefined {
+    const body = stripIdDecorations(id);
+    if (!body.startsWith(VIRTUAL_FONT_CSS_PREFIX)) return undefined;
+    if (!body.endsWith(VIRTUAL_FONT_CSS_SUFFIX)) return undefined;
+    const hash = body.slice(
+      VIRTUAL_FONT_CSS_PREFIX.length,
+      body.length - VIRTUAL_FONT_CSS_SUFFIX.length
+    );
+    return this.map.get(hash);
+  }
+
+  /** True if `id` is any form of the virtual font css module. */
+  matches(id: string): boolean {
+    const body = stripIdDecorations(id);
+    return body.startsWith(VIRTUAL_FONT_CSS_PREFIX) && body.endsWith(VIRTUAL_FONT_CSS_SUFFIX);
+  }
+
+  /** Drop every registered mapping. Used by tests. */
+  clear(): void {
+    this.map.clear();
+  }
+}
+
+/**
+ * Convert a font family name to a PascalCase export name.
+ * e.g. "JetBrains Mono" → "JetBrains_Mono"
+ */
+function familyToExportName(family: string): string {
+  return family.replace(/\s+/g, '_');
+}
+
+/**
+ * Generate the virtual module source for `@timber/fonts/google`.
+ *
+ * The transform hook replaces real call sites at build time, so this
+ * module only matters as a runtime fallback. We export a Proxy default
+ * that handles any font name plus named exports for known families
+ * (for tree-shaking).
+ */
+export function generateGoogleVirtualModule(fonts: Iterable<ExtractedFont>): string {
+  const families = new Set<string>();
+  for (const font of fonts) {
+    if (font.provider === 'google') families.add(font.family);
+  }
+
+  const lines = [
+    '// Auto-generated virtual module: @timber/fonts/google',
+    '// Each export is a font loader function that returns a FontResult.',
+    '',
+    'function createFontResult(family, config) {',
+    '  return {',
+    // eslint-disable-next-line no-template-curly-in-string -- codegen output
+    '    className: `timber-font-${family.toLowerCase().replace(/\\s+/g, "-")}`,',
+    '    style: { fontFamily: family },',
+    '    variable: config?.variable,',
+    '  };',
+    '}',
+    '',
+    'export default new Proxy({}, {',
+    '  get(_, prop) {',
+    '    if (typeof prop === "string") {',
+    '      return (config) => createFontResult(prop.replace(/_/g, " "), config);',
+    '    }',
+    '  }',
+    '});',
+  ];
+
+  for (const family of families) {
+    const exportName = familyToExportName(family);
+    lines.push('');
+    lines.push(`export function ${exportName}(config) {`);
+    lines.push(`  return createFontResult('${family}', config);`);
+    lines.push('}');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Generate the virtual module source for `@timber/fonts/local`.
+ *
+ * Like the google virtual module, this is a runtime fallback. The
+ * transform hook normally replaces `localFont(...)` calls with static
+ * `FontResult` objects at build time.
+ */
+export function generateLocalVirtualModule(): string {
+  return [
+    '// Auto-generated virtual module: @timber/fonts/local',
+    '',
+    'export default function localFont(config) {',
+    '  const family = config?.family || "Local Font";',
+    '  return {',
+    // eslint-disable-next-line no-template-curly-in-string -- codegen output
+    '    className: `timber-font-${family.toLowerCase().replace(/\\s+/g, "-")}`,',
+    '    style: { fontFamily: family },',
+    '    variable: config?.variable,',
+    '  };',
+    '}',
+  ].join('\n');
+}