@timber-js/app 0.2.0-alpha.4 → 0.2.0-alpha.40

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';
 
 // ─── 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 ──────────────────────────────────────────────────────────────
 
 /**
@@ -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,13 +129,15 @@ export function defineCookie<T>(
     options: resolvedOptions,
     codec,
 
-    get(): T {
+    async getCookie(): Promise<T> {
+      const { cookies } = await import('#/server/request-context.js');
       const jar = cookies();
-      const raw = resolvedOptions.signed ? jar.getSigned(name) : jar.get(name);
+      const raw = jar.get(name);
       return codec.parse(raw);
     },
 
-    set(value: T): void {
+    async setCookie(value: T): Promise<void> {
+      const { cookies } = await import('#/server/request-context.js');
       const serialized = codec.serialize(value);
       if (serialized === null) {
         cookies().delete(name, {
@@ -101,7 +149,8 @@ export function defineCookie<T>(
       }
     },
 
-    delete(): void {
+    async deleteCookie(): Promise<void> {
+      const { cookies } = await import('#/server/request-context.js');
       cookies().delete(name, {
         path: resolvedOptions.path,
         domain: resolvedOptions.domain,
@@ -109,6 +158,8 @@ export function defineCookie<T>(
     },
 
     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/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/local.ts

@@ -100,18 +100,22 @@ export 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.
+ * uses a `url()` pointing to the served path under `/_timber/fonts/`.
+ * The `urlPrefix` defaults to `/_timber/fonts` — the path used by both
+ * the dev server middleware and the production build output.
  */
 export function generateLocalFontFaces(
   family: string,
   sources: LocalFontSrc[],
-  display: string
+  display: string,
+  urlPrefix = '/_timber/fonts'
 ): FontFaceDescriptor[] {
   return sources.map((entry) => {
     const format = inferFontFormat(entry.path);
+    const basename = entry.path.split('/').pop() ?? entry.path;
     return {
       family,
-      src: `url('${entry.path}') format('${format}')`,
+      src: `url('${urlPrefix}/${basename}') format('${format}')`,
       weight: entry.weight,
       style: entry.style,
       display,