@timber-js/app 0.1.0

package/dist/cookies/index.js

@@ -0,0 +1,82 @@
+import { n as cookies } from "../_chunks/request-context-D6XHINkR.js";
+import { t as useCookie } from "../_chunks/use-cookie-8ZlA0rr3.js";
+//#region src/cookies/define-cookie.ts
+/**
+* defineCookie — typed cookie definitions.
+*
+* Bundles name + codec + options into a reusable CookieDefinition<T>
+* with .get(), .set(), .delete() server methods and a .useCookie() client hook.
+*
+* Reuses the SearchParamCodec protocol via fromSchema() bridge.
+* Validation on read returns the codec default (never throws).
+*
+* See design/29-cookies.md §"Typed Cookies with Schema Validation"
+*/
+/**
+* Define a typed cookie.
+*
+* ```ts
+* import { defineCookie } from '@timber/app/cookies';
+* import { fromSchema } from '@timber/app/search-params';
+* import { z } from 'zod/v4';
+*
+* export const themeCookie = defineCookie('theme', {
+*   codec: fromSchema(z.enum(['light', 'dark', 'system']).default('system')),
+*   httpOnly: false,
+*   maxAge: 60 * 60 * 24 * 365,
+* });
+* ```
+*/
+function defineCookie(name, options) {
+	const { codec, ...cookieOpts } = options;
+	const resolvedOptions = { ...cookieOpts };
+	return {
+		name,
+		options: resolvedOptions,
+		codec,
+		get() {
+			const jar = cookies();
+			const raw = resolvedOptions.signed ? jar.getSigned(name) : jar.get(name);
+			return codec.parse(raw);
+		},
+		set(value) {
+			const serialized = codec.serialize(value);
+			if (serialized === null) cookies().delete(name, {
+				path: resolvedOptions.path,
+				domain: resolvedOptions.domain
+			});
+			else cookies().set(name, serialized, resolvedOptions);
+		},
+		delete() {
+			cookies().delete(name, {
+				path: resolvedOptions.path,
+				domain: resolvedOptions.domain
+			});
+		},
+		useCookie() {
+			const [raw, setRaw, deleteRaw] = useCookie(name, {
+				path: resolvedOptions.path,
+				domain: resolvedOptions.domain,
+				maxAge: resolvedOptions.maxAge,
+				expires: resolvedOptions.expires,
+				sameSite: resolvedOptions.sameSite,
+				secure: resolvedOptions.secure
+			});
+			const parsed = codec.parse(raw);
+			const setTyped = (value) => {
+				const serialized = codec.serialize(value);
+				if (serialized === null) deleteRaw();
+				else setRaw(serialized);
+			};
+			return [
+				parsed,
+				setTyped,
+				deleteRaw
+			];
+		}
+	};
+}
+//#endregion
+export { defineCookie };
+
+//# sourceMappingURL=index.js.map

package/dist/cookies/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/cookies/define-cookie.ts"],"sourcesContent":["/**\n * defineCookie — typed cookie definitions.\n *\n * Bundles name + codec + options into a reusable CookieDefinition<T>\n * with .get(), .set(), .delete() server methods and a .useCookie() client hook.\n *\n * Reuses the SearchParamCodec protocol via fromSchema() bridge.\n * Validation on read returns the codec default (never throws).\n *\n * See design/29-cookies.md §\"Typed Cookies with Schema Validation\"\n */\n\nimport { cookies } from '#/server/request-context.js';\nimport type { CookieOptions } from '#/server/request-context.js';\nimport { useCookie as useRawCookie } from '#/client/use-cookie.js';\nimport type { ClientCookieOptions } from '#/client/use-cookie.js';\n\n// ─── Types ────────────────────────────────────────────────────────────────\n\n/**\n * A codec that converts between string cookie values and typed values.\n * Intentionally identical to SearchParamCodec<T>.\n */\nexport interface CookieCodec<T> {\n  parse(value: string | string[] | undefined): T;\n  serialize(value: T): string | null;\n}\n\n/** Options for defineCookie: codec + CookieOptions merged. */\nexport interface DefineCookieOptions<T> extends Omit<CookieOptions, 'signed'> {\n  /** Codec for parsing/serializing the cookie value. */\n  codec: CookieCodec<T>;\n  /** Sign the cookie with HMAC-SHA256. */\n  signed?: boolean;\n}\n\n/** A fully typed cookie definition with server and client methods. */\nexport interface CookieDefinition<T> {\n  /** The cookie name. */\n  readonly name: string;\n  /** The resolved cookie options (without codec). */\n  readonly options: CookieOptions;\n  /** The codec used for parsing/serializing. */\n  readonly codec: CookieCodec<T>;\n\n  /** Server: read the typed value from the current request. */\n  get(): T;\n  /** Server: set the typed value on the response. */\n  set(value: T): void;\n  /** Server: delete the cookie. */\n  delete(): void;\n\n  /** Client: React hook for reading/writing this cookie. Returns [value, setter, deleter]. */\n  useCookie(): [T, (value: T) => void, () => void];\n}\n\n// ─── Factory ──────────────────────────────────────────────────────────────\n\n/**\n * Define a typed cookie.\n *\n * ```ts\n * import { defineCookie } from '@timber/app/cookies';\n * import { fromSchema } from '@timber/app/search-params';\n * import { z } from 'zod/v4';\n *\n * export const themeCookie = defineCookie('theme', {\n *   codec: fromSchema(z.enum(['light', 'dark', 'system']).default('system')),\n *   httpOnly: false,\n *   maxAge: 60 * 60 * 24 * 365,\n * });\n * ```\n */\nexport function defineCookie<T>(\n  name: string,\n  options: DefineCookieOptions<T>\n): CookieDefinition<T> {\n  const { codec, ...cookieOpts } = options;\n  const resolvedOptions: CookieOptions = { ...cookieOpts };\n\n  return {\n    name,\n    options: resolvedOptions,\n    codec,\n\n    get(): T {\n      const jar = cookies();\n      const raw = resolvedOptions.signed ? jar.getSigned(name) : jar.get(name);\n      return codec.parse(raw);\n    },\n\n    set(value: T): void {\n      const serialized = codec.serialize(value);\n      if (serialized === null) {\n        cookies().delete(name, {\n          path: resolvedOptions.path,\n          domain: resolvedOptions.domain,\n        });\n      } else {\n        cookies().set(name, serialized, resolvedOptions);\n      }\n    },\n\n    delete(): void {\n      cookies().delete(name, {\n        path: resolvedOptions.path,\n        domain: resolvedOptions.domain,\n      });\n    },\n\n    useCookie(): [T, (value: T) => void, () => void] {\n      // Extract client-safe options (no httpOnly — client cookies can't be httpOnly)\n      const clientOpts: ClientCookieOptions = {\n        path: resolvedOptions.path,\n        domain: resolvedOptions.domain,\n        maxAge: resolvedOptions.maxAge,\n        expires: resolvedOptions.expires,\n        sameSite: resolvedOptions.sameSite,\n        secure: resolvedOptions.secure,\n      };\n\n      const [raw, setRaw, deleteRaw] = useRawCookie(name, clientOpts);\n      const parsed = codec.parse(raw);\n\n      const setTyped = (value: T): void => {\n        const serialized = codec.serialize(value);\n        if (serialized === null) {\n          deleteRaw();\n        } else {\n          setRaw(serialized);\n        }\n      };\n\n      return [parsed, setTyped, deleteRaw];\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyEA,SAAgB,aACd,MACA,SACqB;CACrB,MAAM,EAAE,OAAO,GAAG,eAAe;CACjC,MAAM,kBAAiC,EAAE,GAAG,YAAY;AAExD,QAAO;EACL;EACA,SAAS;EACT;EAEA,MAAS;GACP,MAAM,MAAM,SAAS;GACrB,MAAM,MAAM,gBAAgB,SAAS,IAAI,UAAU,KAAK,GAAG,IAAI,IAAI,KAAK;AACxE,UAAO,MAAM,MAAM,IAAI;;EAGzB,IAAI,OAAgB;GAClB,MAAM,aAAa,MAAM,UAAU,MAAM;AACzC,OAAI,eAAe,KACjB,UAAS,CAAC,OAAO,MAAM;IACrB,MAAM,gBAAgB;IACtB,QAAQ,gBAAgB;IACzB,CAAC;OAEF,UAAS,CAAC,IAAI,MAAM,YAAY,gBAAgB;;EAIpD,SAAe;AACb,YAAS,CAAC,OAAO,MAAM;IACrB,MAAM,gBAAgB;IACtB,QAAQ,gBAAgB;IACzB,CAAC;;EAGJ,YAAiD;GAW/C,MAAM,CAAC,KAAK,QAAQ,aAAa,UAAa,MATN;IACtC,MAAM,gBAAgB;IACtB,QAAQ,gBAAgB;IACxB,QAAQ,gBAAgB;IACxB,SAAS,gBAAgB;IACzB,UAAU,gBAAgB;IAC1B,QAAQ,gBAAgB;IACzB,CAE8D;GAC/D,MAAM,SAAS,MAAM,MAAM,IAAI;GAE/B,MAAM,YAAY,UAAmB;IACnC,MAAM,aAAa,MAAM,UAAU,MAAM;AACzC,QAAI,eAAe,KACjB,YAAW;QAEX,QAAO,WAAW;;AAItB,UAAO;IAAC;IAAQ;IAAU;IAAU;;EAEvC"}

package/dist/fonts/ast.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Acorn-based AST utilities for extracting static font configs from source code.
+ *
+ * Replaces the fragile regex-based extraction in fonts.ts and local.ts.
+ * Uses acorn (already a Vite dependency) for robust parsing that handles
+ * comments, trailing commas, multi-line configs, and other edge cases
+ * the regex approach missed.
+ *
+ * Design doc: 24-fonts.md §"Step 1: Static Analysis"
+ */
+import type { GoogleFontConfig } from './types.js';
+import type { LocalFontConfig } from './types.js';
+/**
+ * Extract a GoogleFontConfig from the source text of a font function call's
+ * object argument.
+ *
+ * The `callSource` should be the text of the call's argument list including
+ * parens, e.g. `({ subsets: ['latin'], weight: '400' })`.
+ *
+ * Returns null if parsing or extraction fails.
+ */
+export declare function extractFontConfigAst(callSource: string): GoogleFontConfig | null;
+/**
+ * Extract a LocalFontConfig from the source text of a localFont() call's
+ * object argument.
+ *
+ * Returns null if parsing or extraction fails.
+ */
+export declare function extractLocalFontConfigAst(callSource: string): LocalFontConfig | null;
+/**
+ * Detect if source code contains dynamic/computed font function calls
+ * that cannot be statically analyzed.
+ *
+ * Uses acorn to parse the full source and inspect CallExpression nodes.
+ * Returns the offending expression string if found, null if all calls are static.
+ */
+export declare function detectDynamicFontCallAst(source: string, importedNames: string[]): string | null;
+//# sourceMappingURL=ast.d.ts.map

package/dist/fonts/ast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast.d.ts","sourceRoot":"","sources":["../../src/fonts/ast.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAgB,MAAM,YAAY,CAAC;AA0HhE;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CA4DhF;AAiCD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CA4CpF;AAID;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAiB/F"}

package/dist/fonts/css.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @font-face CSS generation.
+ *
+ * Generates CSS strings from font face descriptors. Used by both
+ * Google and local font providers.
+ *
+ * Design doc: 24-fonts.md §"Step 3: @font-face Generation"
+ */
+import type { FontFaceDescriptor } from './types.js';
+/**
+ * Generate a single `@font-face` CSS rule from a descriptor.
+ */
+export declare function generateFontFace(desc: FontFaceDescriptor): string;
+/**
+ * Generate multiple `@font-face` rules from an array of descriptors.
+ */
+export declare function generateFontFaces(descriptors: FontFaceDescriptor[]): string;
+/**
+ * Generate a scoped CSS class that sets a CSS custom property for the font.
+ *
+ * Example output:
+ * ```css
+ * .timber-font-inter {
+ *   --font-sans: 'Inter', 'Inter Fallback', system-ui, sans-serif;
+ * }
+ * ```
+ */
+export declare function generateVariableClass(className: string, variable: string, fontFamily: string): string;
+/**
+ * Generate a scoped CSS class that applies font-family directly.
+ *
+ * Used when no `variable` is specified — the className applies
+ * the font-family inline instead of through a CSS custom property.
+ *
+ * Example output:
+ * ```css
+ * .timber-font-inter {
+ *   font-family: 'Inter', 'Inter Fallback', system-ui, sans-serif;
+ * }
+ * ```
+ */
+export declare function generateFontFamilyClass(className: string, fontFamily: string): string;
+//# sourceMappingURL=css.d.ts.map

package/dist/fonts/css.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"css.d.ts","sourceRoot":"","sources":["../../src/fonts/css.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAWjE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,kBAAkB,EAAE,GAAG,MAAM,CAE3E;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,MAAM,CAER;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAErF"}

package/dist/fonts/fallbacks.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Size-adjusted fallback font generation.
+ *
+ * Generates `@font-face` declarations for fallback fonts with
+ * `size-adjust`, `ascent-override`, `descent-override`, and
+ * `line-gap-override` to match custom font metrics and eliminate CLS.
+ *
+ * Design doc: 24-fonts.md §"Step 4: Size-Adjusted Fallbacks"
+ */
+import type { FontFaceDescriptor } from './types.js';
+export declare function getGenericFamily(family: string): string;
+/**
+ * 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 declare function generateFallbackFontFace(family: string): FontFaceDescriptor | null;
+/**
+ * Generate the full CSS for a size-adjusted fallback font.
+ *
+ * This produces a complete @font-face block with override descriptors
+ * that FontFaceDescriptor doesn't natively support.
+ */
+export declare function generateFallbackCss(family: string): string | null;
+/**
+ * Check whether fallback metrics are available for a font family.
+ */
+export declare function hasFallbackMetrics(family: string): boolean;
+/**
+ * Build the full font stack string for a font, including its
+ * size-adjusted fallback and a generic family.
+ *
+ * Example: `'Inter', 'Inter Fallback', system-ui, sans-serif`
+ */
+export declare function buildFontStack(family: string): string;
+//# sourceMappingURL=fallbacks.d.ts.map

package/dist/fonts/fallbacks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fallbacks.d.ts","sourceRoot":"","sources":["../../src/fonts/fallbacks.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAwJrD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAOvD;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAclF;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAkBjE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAgBrD"}

package/dist/fonts/google.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Google Fonts download, caching, and dev CDN fallback.
+ *
+ * At build time (production only):
+ * 1. Queries Google Fonts CSS API v2 for font metadata and file URLs
+ * 2. Downloads woff2 font files
+ * 3. Caches them in node_modules/.cache/timber-fonts/
+ * 4. Content-hashes filenames for cache busting
+ * 5. Emits font files into the build output via generateBundle
+ *
+ * In dev mode:
+ * - Generates @font-face rules pointing to Google Fonts CDN
+ * - No downloads, no caching
+ *
+ * Design doc: 24-fonts.md §"Step 2: Font Download & Subsetting"
+ */
+import type { ExtractedFont, FontFaceDescriptor } from './types.js';
+/** A parsed @font-face block from the Google Fonts CSS response. */
+export interface GoogleFontFace {
+    family: string;
+    weight: string;
+    style: string;
+    /** The remote URL to the font file. */
+    url: string;
+    /** The unicode-range from the CSS (e.g. `U+0000-00FF, U+0131`). */
+    unicodeRange: string;
+    /** Subset label extracted from the CSS comment (e.g. `latin`, `cyrillic`). */
+    subset: string;
+}
+/** A downloaded and cached font file, ready for build output. */
+export interface CachedFont {
+    /** The original parsed face data. */
+    face: GoogleFontFace;
+    /** Content-hashed filename (e.g. `inter-latin-400-normal-abc123.woff2`). */
+    hashedFilename: string;
+    /** Absolute path to the cached file. */
+    cachePath: string;
+    /** Raw font file bytes. */
+    data: Buffer;
+}
+/**
+ * Build the Google Fonts CSS API v2 URL for a given font config.
+ *
+ * Example output:
+ * https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap&subset=latin
+ */
+export declare function buildGoogleFontsUrl(font: ExtractedFont): string;
+/**
+ * Fetch the CSS from Google Fonts API and parse out @font-face blocks.
+ *
+ * The API returns CSS with subset comments like:
+ * ```
+ * /* latin * /
+ * @font-face { ... }
+ * ```
+ *
+ * We parse each block to extract the font URL, unicode-range, and subset label.
+ */
+export declare function fetchGoogleFontsCss(url: string): Promise<GoogleFontFace[]>;
+/**
+ * Parse the CSS response from Google Fonts API into structured font face data.
+ *
+ * Handles the Google Fonts CSS format with subset comments and @font-face blocks.
+ */
+export declare function parseGoogleFontsCss(css: string): GoogleFontFace[];
+/**
+ * Filter parsed font faces to only the requested subsets.
+ */
+export declare function filterBySubsets(faces: GoogleFontFace[], subsets: string[]): GoogleFontFace[];
+/**
+ * Generate a content hash for font data.
+ * Returns the first 8 hex chars of the SHA-256 hash.
+ */
+export declare function contentHash(data: Buffer): string;
+/**
+ * Generate a content-hashed filename for a font face.
+ *
+ * Format: `<family>-<subset>-<weight>-<style>-<hash>.woff2`
+ * Example: `inter-latin-400-normal-abc12345.woff2`
+ */
+export declare function hashedFontFilename(face: GoogleFontFace, data: Buffer): string;
+/**
+ * Build the cache key for a font face.
+ * Used to check if a font has already been downloaded.
+ */
+export declare function cacheKey(face: GoogleFontFace): string;
+/**
+ * Download a single font file from its URL.
+ */
+export declare function downloadFontFile(url: string): Promise<Buffer>;
+/**
+ * Download and cache all font files for a set of extracted Google fonts.
+ *
+ * - Checks the local cache first (node_modules/.cache/timber-fonts/)
+ * - Downloads missing fonts from Google Fonts CDN
+ * - Writes downloaded fonts to cache
+ * - Returns CachedFont entries with content-hashed filenames
+ */
+export declare function downloadAndCacheFonts(fonts: ExtractedFont[], projectRoot: string): Promise<CachedFont[]>;
+/**
+ * Generate @font-face descriptors for cached (production) Google Fonts.
+ *
+ * Each CachedFont gets a FontFaceDescriptor pointing to the
+ * content-hashed URL under `/_timber/fonts/`.
+ */
+export declare function generateProductionFontFaces(cachedFonts: CachedFont[], display: string): FontFaceDescriptor[];
+/**
+ * Generate @font-face descriptors for dev mode (CDN-pointing).
+ *
+ * In dev mode, we query the Google Fonts API but use the CDN URLs
+ * directly instead of downloading. This avoids the download/cache
+ * step during `vite dev`.
+ */
+export declare function generateDevFontFaces(faces: GoogleFontFace[], display: string): FontFaceDescriptor[];
+/**
+ * Resolve dev-mode font faces for an extracted font.
+ *
+ * Fetches the CSS from Google Fonts API and returns FontFaceDescriptors
+ * pointing to CDN URLs. No files are downloaded.
+ */
+export declare function resolveDevFontFaces(font: ExtractedFont): Promise<FontFaceDescriptor[]>;
+//# sourceMappingURL=google.d.ts.map

package/dist/fonts/google.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"google.d.ts","sourceRoot":"","sources":["../../src/fonts/google.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAepE,oEAAoE;AACpE,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,mEAAmE;IACnE,YAAY,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,iEAAiE;AACjE,MAAM,WAAW,UAAU;IACzB,qCAAqC;IACrC,IAAI,EAAE,cAAc,CAAC;IACrB,4EAA4E;IAC5E,cAAc,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAiC/D;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAahF;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,EAAE,CA8BjE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,cAAc,EAAE,CAI5F;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAI7E;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAGrD;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAMnE;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,aAAa,EAAE,EACtB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,UAAU,EAAE,CAAC,CAwCvB;AAeD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,UAAU,EAAE,EACzB,OAAO,EAAE,MAAM,GACd,kBAAkB,EAAE,CAStB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,EAAE,MAAM,GACd,kBAAkB,EAAE,CAStB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAK5F"}

package/dist/fonts/local.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Local font processing for the timber-fonts pipeline.
+ *
+ * Handles:
+ * - Resolving font file paths relative to the importing module
+ * - Normalizing single-string `src` to array form
+ * - Generating @font-face descriptors for each weight/style variant
+ *
+ * Does NOT handle:
+ * - Font format conversion (serve whatever the user provides)
+ * - Font subsetting (user's responsibility for local fonts)
+ *
+ * Design doc: 24-fonts.md §"Local Fonts"
+ */
+import type { LocalFontConfig, LocalFontSrc, FontFaceDescriptor, ExtractedFont } from './types.js';
+/**
+ * Infer the font format from a file extension.
+ *
+ * Returns the CSS `format()` value for `@font-face` src descriptors.
+ */
+export declare function inferFontFormat(filePath: string): string;
+/**
+ * Normalize `src` config to an array of LocalFontSrc entries.
+ *
+ * When `src` is a single string, it becomes a single entry with
+ * default weight '400' and style 'normal'.
+ */
+export declare function normalizeSrc(src: string | LocalFontSrc[]): LocalFontSrc[];
+/**
+ * Resolve font file paths relative to the importing module's directory.
+ *
+ * Takes the importer's file path and the normalized src entries,
+ * returns new entries with absolute resolved paths.
+ */
+export declare function resolveLocalFontPaths(importerPath: string, sources: LocalFontSrc[]): LocalFontSrc[];
+/**
+ * Generate a deterministic font family name from the file path
+ * when no explicit `family` is provided.
+ *
+ * Uses the filename without extension, e.g. "MyFont-Regular.woff2" → "MyFont-Regular".
+ * For multi-weight sources, uses the first file's name stem.
+ */
+export declare 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.
+ */
+export declare function generateLocalFontFaces(family: string, sources: LocalFontSrc[], display: string): FontFaceDescriptor[];
+/**
+ * Build the className for a local font, following the same convention
+ * as Google fonts: `timber-font-<lowercase-hyphenated-family>`.
+ */
+export declare function localFontClassName(family: string): string;
+/**
+ * Process a local font config into an ExtractedFont.
+ *
+ * This is the main entry point called by the fonts plugin's transform hook
+ * when it encounters a `localFont()` call.
+ */
+export declare function processLocalFont(config: LocalFontConfig, importerPath: string): ExtractedFont;
+/**
+ * Extract a LocalFontConfig from a static `localFont()` call source.
+ *
+ * Parses patterns like:
+ *   localFont({ src: './fonts/MyFont.woff2', display: 'swap', variable: '--font-custom' })
+ *   localFont({ src: [{ path: './a.woff2', weight: '400' }, { path: './b.woff2', weight: '700' }] })
+ *
+ * Returns null if the call cannot be statically analyzed.
+ *
+ * Uses acorn AST parsing for robust handling of comments, trailing commas,
+ * and multi-line configs.
+ */
+export declare function extractLocalFontConfig(callSource: string): LocalFontConfig | null;
+//# sourceMappingURL=local.d.ts.map

package/dist/fonts/local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../src/fonts/local.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAInG;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAgBxD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,EAAE,GAAG,YAAY,EAAE,CASzE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,YAAY,EAAE,GACtB,YAAY,EAAE,CAMhB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,MAAM,CAYlE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,YAAY,EAAE,EACvB,OAAO,EAAE,MAAM,GACd,kBAAkB,EAAE,CAWtB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,GAAG,aAAa,CAyB7F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAEjF"}

package/dist/fonts/types.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Shared types for the timber-fonts pipeline.
+ *
+ * Used by the fonts plugin, CSS generator, fallback generator,
+ * and the Google/local font providers.
+ *
+ * Design doc: 24-fonts.md
+ */
+/** Configuration passed to a Google font function (e.g. `Inter({ ... })`). */
+export interface GoogleFontConfig {
+    weight?: string | string[];
+    subsets?: string[];
+    display?: 'auto' | 'block' | 'swap' | 'fallback' | 'optional';
+    variable?: string;
+    style?: string | string[];
+    preload?: boolean;
+}
+/** A single local font source entry (multi-weight). */
+export interface LocalFontSrc {
+    path: string;
+    weight?: string;
+    style?: string;
+}
+/** Configuration passed to `localFont()`. */
+export interface LocalFontConfig {
+    src: string | LocalFontSrc[];
+    display?: 'auto' | 'block' | 'swap' | 'fallback' | 'optional';
+    variable?: string;
+    /** Override the font family name. Defaults to a generated name. */
+    family?: string;
+}
+/**
+ * The return value of a font function call.
+ *
+ * Matches the Next.js `next/font` return shape for compatibility.
+ */
+export interface FontResult {
+    /** Scoped CSS class that applies font-family (e.g. `timber-font-inter`). */
+    className: string;
+    /** Inline style with the full font stack including fallbacks. */
+    style: {
+        fontFamily: string;
+    };
+    /** CSS custom property name when `variable` is specified (e.g. `--font-sans`). */
+    variable?: string;
+}
+/** Internal representation of a font extracted during static analysis. */
+export interface ExtractedFont {
+    /** Unique identifier for this font instance (e.g. `inter-400-normal-latin`). */
+    id: string;
+    /** The font family name (e.g. `Inter`). */
+    family: string;
+    /** Provider: 'google' or 'local'. */
+    provider: 'google' | 'local';
+    /** Weights requested (e.g. ['400', '700']). */
+    weights: string[];
+    /** Styles requested (e.g. ['normal', 'italic']). */
+    styles: string[];
+    /** Subsets requested (e.g. ['latin']). Google fonts only. */
+    subsets: string[];
+    /** font-display value. */
+    display: string;
+    /** CSS variable name (e.g. `--font-sans`). */
+    variable?: string;
+    /** Source file paths for local fonts. */
+    localSources?: LocalFontSrc[];
+    /** The module that imported this font (for segment association). */
+    importer: string;
+    /** Generated scoped class name. */
+    className: string;
+    /** Full font stack including fallback. */
+    fontFamily: string;
+}
+/**
+ * A single @font-face declaration's data (before CSS serialization).
+ */
+export interface FontFaceDescriptor {
+    family: string;
+    src: string;
+    weight?: string;
+    style?: string;
+    display?: string;
+    unicodeRange?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/fonts/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/fonts/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,CAAC;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,uDAAuD;AACvD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,6CAA6C;AAC7C,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,GAAG,YAAY,EAAE,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,CAAC;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,KAAK,EAAE;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9B,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,gFAAgF;IAChF,EAAE,EAAE,MAAM,CAAC;IACX,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC7B,+CAA+C;IAC/C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,oDAAoD;IACpD,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,6DAA6D;IAC7D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,YAAY,CAAC,EAAE,YAAY,EAAE,CAAC;IAC9B,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB"}