@timber-js/app 0.2.0-alpha.9 → 0.2.0-alpha.90

package/src/cookies/define-cookie.ts

@@ -2,36 +2,42 @@
  * defineCookie — typed cookie definitions.
  *
  * Bundles name + codec + options into a reusable CookieDefinition<T>
- * with .get(), .set(), .delete() server methods and a .useCookie() client hook.
+ * with async .getCookie(), .setCookie(), .deleteCookie() server methods
+ * and a sync .useCookie() client hook.
+ *
+ * Server methods are async to future-proof the API for v2 features
+ * (signed cookies via crypto.subtle, encrypted cookies, external stores).
  *
  * Reuses the SearchParamCodec protocol via fromSchema() bridge.
  * Validation on read returns the codec default (never throws).
  *
+ * IMPORTANT: This module must NOT have top-level value imports from either
+ * server or client modules. Server methods lazy-import request-context;
+ * useCookie() lazy-imports use-cookie. This ensures:
+ * - Client bundles don't pull in ALS/server code
+ * - RSC bundles don't pull in useSyncExternalStore/client code
+ * - Tree-shaking is not required for correctness
+ *
  * See design/29-cookies.md §"Typed Cookies with Schema Validation"
  */
 
-import { cookies } from '#/server/request-context.js';
-import type { CookieOptions } from '#/server/request-context.js';
-import { useCookie as useRawCookie } from '#/client/use-cookie.js';
-import type { ClientCookieOptions } from '#/client/use-cookie.js';
+import type { CookieOptions } from '../server/request-context.js';
+import type { ClientCookieOptions } from '../client/use-cookie.js';
 
 // ─── Types ────────────────────────────────────────────────────────────────
 
+import type { Codec } from '../codec.js';
+
 /**
  * A codec that converts between string cookie values and typed values.
- * Intentionally identical to SearchParamCodec<T>.
+ * Type alias for the shared Codec<T> protocol.
  */
-export interface CookieCodec<T> {
-  parse(value: string | string[] | undefined): T;
-  serialize(value: T): string | null;
-}
+export type CookieCodec<T> = Codec<T>;
 
 /** Options for defineCookie: codec + CookieOptions merged. */
-export interface DefineCookieOptions<T> extends Omit<CookieOptions, 'signed'> {
+export interface DefineCookieOptions<T> extends CookieOptions {
   /** Codec for parsing/serializing the cookie value. */
   codec: CookieCodec<T>;
-  /** Sign the cookie with HMAC-SHA256. */
-  signed?: boolean;
 }
 
 /** A fully typed cookie definition with server and client methods. */
@@ -44,16 +50,49 @@ export interface CookieDefinition<T> {
   readonly codec: CookieCodec<T>;
 
   /** Server: read the typed value from the current request. */
-  get(): T;
+  getCookie(): Promise<T>;
   /** Server: set the typed value on the response. */
-  set(value: T): void;
+  setCookie(value: T): Promise<void>;
   /** Server: delete the cookie. */
-  delete(): void;
+  deleteCookie(): Promise<void>;
 
   /** Client: React hook for reading/writing this cookie. Returns [value, setter, deleter]. */
   useCookie(): [T, (value: T) => void, () => void];
 }
 
+// ─── Lazy Module References ───────────────────────────────────────────────
+//
+// These are resolved on first use, not at module load time. This prevents
+// the server module graph from pulling in client code and vice versa.
+// The dynamic import() in server methods is natural (they're async).
+// For useCookie() (sync), we cache the module reference after first load.
+
+let _useCookieModule: typeof import('../client/use-cookie.js') | undefined;
+
+function getUseCookieModule(): typeof import('../client/use-cookie.js') {
+  if (!_useCookieModule) {
+    // In the client/SSR environment, this module is already in the module
+    // graph (imported by the client entry). The throw is a safeguard —
+    // if useCookie() is somehow called before the module is available,
+    // the developer gets a clear error instead of a silent failure.
+    throw new Error(
+      '[timber] defineCookie().useCookie() requires @timber-js/app/client to be loaded. ' +
+        'This hook can only be used in client components.'
+    );
+  }
+  return _useCookieModule;
+}
+
+/**
+ * Register the client cookie module. Called by the client entry to wire
+ * up the lazy reference without a top-level import.
+ *
+ * @internal — framework use only
+ */
+export function _registerUseCookieModule(mod: typeof import('../client/use-cookie.js')): void {
+  _useCookieModule = mod;
+}
+
 // ─── Factory ──────────────────────────────────────────────────────────────
 
 /**
@@ -61,7 +100,7 @@ export interface CookieDefinition<T> {
  *
  * ```ts
  * import { defineCookie } from '@timber-js/app/cookies';
- * import { fromSchema } from '@timber-js/app/search-params';
+ * import { fromSchema } from '@timber-js/app/codec';
  * import { z } from 'zod/v4';
  *
  * export const themeCookie = defineCookie('theme', {
@@ -69,6 +108,13 @@ export interface CookieDefinition<T> {
  *   httpOnly: false,
  *   maxAge: 60 * 60 * 24 * 365,
  * });
+ *
+ * // Server
+ * const theme = await themeCookie.getCookie();
+ * await themeCookie.setCookie('dark');
+ *
+ * // Client
+ * const [theme, setTheme] = themeCookie.useCookie();
  * ```
  */
 export function defineCookie<T>(
@@ -83,32 +129,39 @@ export function defineCookie<T>(
     options: resolvedOptions,
     codec,
 
-    get(): T {
-      const jar = cookies();
-      const raw = resolvedOptions.signed ? jar.getSigned(name) : jar.get(name);
+    async getCookie(): Promise<T> {
+      const { getCookies } = await import('../server/request-context.js');
+      const jar = await getCookies();
+      const raw = jar.get(name);
       return codec.parse(raw);
     },
 
-    set(value: T): void {
+    async setCookie(value: T): Promise<void> {
+      const { getCookies } = await import('../server/request-context.js');
+      const jar = await getCookies();
       const serialized = codec.serialize(value);
       if (serialized === null) {
-        cookies().delete(name, {
+        jar.delete(name, {
           path: resolvedOptions.path,
           domain: resolvedOptions.domain,
         });
       } else {
-        cookies().set(name, serialized, resolvedOptions);
+        jar.set(name, serialized, resolvedOptions);
       }
     },
 
-    delete(): void {
-      cookies().delete(name, {
+    async deleteCookie(): Promise<void> {
+      const { getCookies } = await import('../server/request-context.js');
+      const jar = await getCookies();
+      jar.delete(name, {
         path: resolvedOptions.path,
         domain: resolvedOptions.domain,
       });
     },
 
     useCookie(): [T, (value: T) => void, () => void] {
+      const { useCookie: useRawCookie } = getUseCookieModule();
+
       // Extract client-safe options (no httpOnly — client cookies can't be httpOnly)
       const clientOpts: ClientCookieOptions = {
         path: resolvedOptions.path,

package/src/cookies/index.ts

@@ -3,3 +3,11 @@
 
 export { defineCookie } from './define-cookie.js';
 export type { CookieDefinition, CookieCodec, DefineCookieOptions } from './define-cookie.js';
+
+// Codec is the canonical home for the Codec type — import from
+// @timber-js/app/codec. Re-export removed per TIM-721.
+
+// cookies() is a server-only function (requires AsyncLocalStorage) and is
+// exported from @timber-js/app/server. It is intentionally NOT re-exported
+// here so that client-side code importing defineCookie doesn't pull in
+// server ALS code. See TIM-704.

package/src/fonts/bundle.ts

@@ -0,0 +1,142 @@
+/**
+ * Build-output emission for the timber-fonts plugin.
+ *
+ * Splits the `generateBundle` hook into pure helpers so the plugin shell
+ * can stay focused on Vite wiring. The functions here are deliberately
+ * Rollup-agnostic — they take an `EmitFile` callback so the plugin can
+ * pass `this.emitFile` from the `generateBundle` context.
+ *
+ * Design doc: 24-fonts.md
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, normalize } from 'node:path';
+import type { ManifestFontEntry, BuildManifest } from '../server/build-manifest.js';
+
+/**
+ * Minimal shape of the asset descriptor accepted by Rollup's `emitFile`.
+ * Declared inline rather than importing from `rollup` to keep `bundle.ts`
+ * Rollup-agnostic and avoid pulling the type into the build graph.
+ */
+interface EmittedAsset {
+  type: 'asset';
+  fileName: string;
+  source: string | Uint8Array;
+}
+import type { FontPipeline } from './pipeline.js';
+import type { CachedFont } from './google.js';
+import { inferFontFormat } from './local.js';
+
+type EmitFile = (asset: EmittedAsset) => string;
+type EmitWarning = (msg: string) => void;
+
+/** Group cached Google Font binaries by lowercase family name. */
+export function groupCachedFontsByFamily(
+  cachedFonts: readonly CachedFont[]
+): Map<string, CachedFont[]> {
+  const cachedByFamily = new Map<string, CachedFont[]>();
+  for (const cf of cachedFonts) {
+    const key = cf.face.family.toLowerCase();
+    const arr = cachedByFamily.get(key) ?? [];
+    arr.push(cf);
+    cachedByFamily.set(key, arr);
+  }
+  return cachedByFamily;
+}
+
+/**
+ * Emit cached Google Font binaries and local font files into the build
+ * output under `_timber/fonts/`. Local files missing on disk produce a
+ * warning rather than an error so the build still succeeds.
+ *
+ * Cached Google Font binaries are deduplicated by `hashedFilename` so
+ * each unique file is written exactly once even when multiple font
+ * entries share a family (and therefore share `CachedFont` references).
+ */
+export function emitFontAssets(
+  pipeline: FontPipeline,
+  emitFile: EmitFile,
+  warn: EmitWarning
+): void {
+  // Cached Google Font binaries (content-hashed, deduped by filename)
+  for (const cf of pipeline.uniqueCachedFiles()) {
+    emitFile({
+      type: 'asset',
+      fileName: `_timber/fonts/${cf.hashedFilename}`,
+      source: cf.data,
+    });
+  }
+
+  // Local font files (emitted by basename)
+  for (const font of pipeline.fonts()) {
+    if (font.provider !== 'local' || !font.localSources) continue;
+    for (const src of font.localSources) {
+      const absolutePath = normalize(resolve(src.path));
+      if (!existsSync(absolutePath)) {
+        warn(`Local font file not found: ${absolutePath}`);
+        continue;
+      }
+      const basename = src.path.split('/').pop() ?? src.path;
+      const data = readFileSync(absolutePath);
+      emitFile({
+        type: 'asset',
+        fileName: `_timber/fonts/${basename}`,
+        source: data,
+      });
+    }
+  }
+}
+
+/**
+ * Populate `buildManifest.fonts` with `ManifestFontEntry[]` keyed by the
+ * importer module path (relative to the project root, matching how Vite's
+ * `manifest.json` keys css/js).
+ *
+ * Google fonts use the content-hashed filenames produced during
+ * `buildStart`. Local fonts use the source basename.
+ */
+export function writeFontManifest(
+  pipeline: FontPipeline,
+  buildManifest: BuildManifest,
+  rootDir: string
+): void {
+  const fontsByImporter = new Map<string, ManifestFontEntry[]>();
+
+  for (const entry of pipeline.entries()) {
+    const manifestEntries = fontsByImporter.get(entry.importer) ?? [];
+
+    if (entry.provider === 'local' && entry.localSources) {
+      for (const src of entry.localSources) {
+        const filename = src.path.split('/').pop() ?? src.path;
+        const format = inferFontFormat(src.path);
+        manifestEntries.push({
+          href: `/_timber/fonts/${filename}`,
+          format,
+          crossOrigin: 'anonymous',
+        });
+      }
+    } else if (entry.cachedFiles) {
+      // Google fonts: use the per-entry cached files attached during
+      // buildStart. Each entry owns its own cached binaries (TIM-829),
+      // so we no longer need a family-grouped lookup.
+      for (const cf of entry.cachedFiles) {
+        manifestEntries.push({
+          href: `/_timber/fonts/${cf.hashedFilename}`,
+          format: 'woff2',
+          crossOrigin: 'anonymous',
+        });
+      }
+    }
+
+    fontsByImporter.set(entry.importer, manifestEntries);
+  }
+
+  // Normalize importer paths to be relative to project root (matching how
+  // Vite's manifest.json keys work for css/js).
+  for (const [importer, entries] of fontsByImporter) {
+    const relativePath = importer.startsWith(rootDir)
+      ? importer.slice(rootDir.length + 1)
+      : importer;
+    buildManifest.fonts[relativePath] = entries;
+  }
+}

package/src/fonts/css.ts

@@ -39,6 +39,7 @@ export function generateFontFaces(descriptors: FontFaceDescriptor[]): string {
  * ```css
  * .timber-font-inter {
  *   --font-sans: 'Inter', 'Inter Fallback', system-ui, sans-serif;
+ *   font-family: 'Inter', 'Inter Fallback', system-ui, sans-serif;
  * }
  * ```
  */
@@ -47,7 +48,7 @@ export function generateVariableClass(
   variable: string,
   fontFamily: string
 ): string {
-  return `.${className} {\n  ${variable}: ${fontFamily};\n}`;
+  return `.${className} {\n  ${variable}: ${fontFamily};\n  font-family: ${fontFamily};\n}`;
 }
 
 /**

package/src/fonts/dev-middleware.ts

@@ -0,0 +1,74 @@
+/**
+ * Dev-mode middleware that serves local font binaries under
+ * `/_timber/fonts/<basename>`.
+ *
+ * Only files registered in the FontPipeline are served, and only by
+ * basename — directory traversal and path separators in the requested
+ * filename are rejected up front. Font CSS is no longer served here; it
+ * goes through Vite's CSS pipeline via virtual modules.
+ *
+ * Design doc: 24-fonts.md
+ */
+
+import type { ViteDevServer } from 'vite';
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, normalize } from 'node:path';
+import type { FontPipeline } from './pipeline.js';
+
+const FONT_MIME_TYPES: Record<string, string> = {
+  woff2: 'font/woff2',
+  woff: 'font/woff',
+  ttf: 'font/ttf',
+  otf: 'font/otf',
+  eot: 'application/vnd.ms-fontopen',
+};
+
+/**
+ * Wire the timber-fonts dev middleware onto a Vite dev server.
+ *
+ * Returns synchronously after registering the middleware. The pipeline is
+ * captured by reference so that fonts registered after `configureServer`
+ * runs (during transform) are still resolvable.
+ */
+export function installFontDevMiddleware(server: ViteDevServer, pipeline: FontPipeline): void {
+  server.middlewares.use((req, res, next) => {
+    const url = req.url;
+    if (!url || !url.startsWith('/_timber/fonts/')) return next();
+
+    const requestedFilename = url.slice('/_timber/fonts/'.length);
+    // Reject path traversal attempts and any subdirectory access. We only
+    // serve flat basenames out of the registry.
+    if (requestedFilename.includes('..') || requestedFilename.includes('/')) {
+      res.statusCode = 400;
+      res.end('Bad request');
+      return;
+    }
+
+    // Find the matching font file in the registry. We iterate every local
+    // font's source list and match by basename. The set is small (one per
+    // localFont() call) so this is cheap.
+    for (const font of pipeline.fonts()) {
+      if (font.provider !== 'local' || !font.localSources) continue;
+      for (const src of font.localSources) {
+        const basename = src.path.split('/').pop() ?? '';
+        if (basename !== requestedFilename) continue;
+
+        const absolutePath = normalize(resolve(src.path));
+        if (!existsSync(absolutePath)) {
+          res.statusCode = 404;
+          res.end('Not found');
+          return;
+        }
+        const data = readFileSync(absolutePath);
+        const ext = absolutePath.split('.').pop()?.toLowerCase();
+        res.setHeader('Content-Type', FONT_MIME_TYPES[ext ?? ''] ?? 'application/octet-stream');
+        res.setHeader('Cache-Control', 'public, max-age=31536000, immutable');
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.end(data);
+        return;
+      }
+    }
+
+    next();
+  });
+}