@timber-js/app 0.2.0-alpha.6 → 0.2.0-alpha.60

package/src/client/stale-reload.ts

@@ -16,6 +16,16 @@
 
 const RELOAD_FLAG_KEY = '__timber_stale_reload';
 
+/**
+ * In-memory fallback counter for environments where sessionStorage is
+ * unavailable (private browsing, storage full, extension interference).
+ * Incremented each time triggerStaleReload() falls into the catch path.
+ * If the counter exceeds 0 on a subsequent call, the reload is suppressed
+ * to prevent an infinite loop. Resets naturally on page load (module
+ * re-evaluates) and can be manually reset via clearStaleReloadFlag().
+ */
+let memoryReloadCount = 0;
+
 /**
  * Check if an error is a stale client reference error from React's
  * Flight client. These errors have the message pattern:
@@ -32,6 +42,34 @@ export function isStaleClientReference(error: unknown): boolean {
   return msg.includes('Could not find the module') || msg.includes('client reference not found');
 }
 
+/**
+ * Check if an error is a chunk load failure from a dynamic import.
+ *
+ * After a deployment, old chunk filenames no longer exist. When the client
+ * tries to dynamically import a chunk that's been replaced, the browser
+ * throws one of these errors:
+ *
+ * - Chromium: "Failed to fetch dynamically imported module: <url>"
+ * - Firefox: "error loading dynamically imported module: <url>"
+ * - Safari: "Importing a module script failed."
+ * - Vite/Rollup: "Unable to preload CSS for <url>"
+ *
+ * See TIM-446
+ */
+export function isChunkLoadError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  const msg = error.message.toLowerCase();
+  return (
+    msg.includes('failed to fetch dynamically imported module') ||
+    msg.includes('error loading dynamically imported module') ||
+    msg.includes('importing a module script failed') ||
+    msg.includes('unable to preload css') ||
+    // Webpack-style chunk load errors (unlikely in Vite but defensive)
+    msg.includes('loading chunk') ||
+    msg.includes('loading css chunk')
+  );
+}
+
 /**
  * Trigger a full page reload to pick up new bundles.
  *
@@ -48,8 +86,8 @@ export function triggerStaleReload(): boolean {
     if (sessionStorage.getItem(RELOAD_FLAG_KEY)) {
       console.warn(
         '[timber] Stale client reference detected again after reload. ' +
-        'Not reloading to prevent infinite loop. ' +
-        'This may indicate a deployment issue — try a hard refresh.'
+          'Not reloading to prevent infinite loop. ' +
+          'This may indicate a deployment issue — try a hard refresh.'
       );
       return false;
     }
@@ -59,16 +97,27 @@ export function triggerStaleReload(): boolean {
 
     console.warn(
       '[timber] Stale client reference detected — the server has been ' +
-      'redeployed with new bundles. Reloading to pick up the new version.'
+        'redeployed with new bundles. Reloading to pick up the new version.'
     );
 
     window.location.reload();
     return true;
   } catch {
-    // sessionStorage may be unavailable (private browsing, storage full, etc.)
-    // Fall back to reloading without loop protection
+    // sessionStorage unavailable (private browsing, storage full, etc.)
+    // Use in-memory counter as fallback loop guard
+    if (memoryReloadCount > 0) {
+      console.warn(
+        '[timber] Stale client reference detected again after reload. ' +
+          'Not reloading to prevent infinite loop. ' +
+          'This may indicate a deployment issue — try a hard refresh.'
+      );
+      return false;
+    }
+
+    memoryReloadCount++;
     console.warn(
-      '[timber] Stale client reference detected. Reloading page.'
+      '[timber] Stale client reference detected — the server has been ' +
+        'redeployed with new bundles. Reloading to pick up the new version.'
     );
     window.location.reload();
     return true;
@@ -81,6 +130,7 @@ export function triggerStaleReload(): boolean {
  * reference error should trigger a fresh reload attempt.
  */
 export function clearStaleReloadFlag(): void {
+  memoryReloadCount = 0;
   try {
     sessionStorage.removeItem(RELOAD_FLAG_KEY);
   } catch {

package/src/client/top-loader.tsx

@@ -39,7 +39,7 @@ export interface TopLoaderConfig {
   color?: string;
   /** Bar height in pixels. Default: 3. */
   height?: number;
-  /** Show subtle glow/shadow effect. Default: true. */
+  /** Show subtle glow/shadow effect. Default: false. */
   shadow?: boolean;
   /** Delay in ms before showing the bar. Default: 0. */
   delay?: number;
@@ -51,7 +51,7 @@ export interface TopLoaderConfig {
 
 const DEFAULT_COLOR = '#2299DD';
 const DEFAULT_HEIGHT = 3;
-const DEFAULT_SHADOW = true;
+const DEFAULT_SHADOW = false;
 const DEFAULT_DELAY = 0;
 const DEFAULT_Z_INDEX = 1600;
 
@@ -183,18 +183,19 @@ export function TopLoader({ config }: { config?: TopLoaderConfig }): React.React
   };
 
   // Clean up the finishing phase when the finish animation completes.
-  const handleAnimationEnd = phase === 'finishing'
-    ? (e: React.AnimationEvent) => {
-        if (e.animationName === FINISH_KEYFRAMES) {
-          setPhase('hidden');
+  const handleAnimationEnd =
+    phase === 'finishing'
+      ? (e: React.AnimationEvent) => {
+          if (e.animationName === FINISH_KEYFRAMES) {
+            setPhase('hidden');
+          }
         }
-      }
-    : undefined;
+      : undefined;
 
   return createElement(
     'div',
     {
-      style: containerStyle,
+      'style': containerStyle,
       'aria-hidden': 'true',
       'data-timber-top-loader': '',
     },

package/src/client/transition-root.tsx

@@ -25,6 +25,7 @@
 import { useState, useTransition, createElement, Fragment, type ReactNode } from 'react';
 import { PendingNavigationProvider } from './navigation-context.js';
 import { TopLoader, type TopLoaderConfig } from './top-loader.js';
+import { getCurrentNavId, resetLinkPending } from './link-pending-store.js';
 
 // ─── Module-level functions ──────────────────────────────────────
 
@@ -62,7 +63,13 @@ let _navigateTransition:
  * Non-navigation renders:
  *   transitionRender(newWrappedElement);
  */
-export function TransitionRoot({ initial, topLoaderConfig }: { initial: ReactNode; topLoaderConfig?: TopLoaderConfig }): ReactNode {
+export function TransitionRoot({
+  initial,
+  topLoaderConfig,
+}: {
+  initial: ReactNode;
+  topLoaderConfig?: TopLoaderConfig;
+}): ReactNode {
   const [element, setElement] = useState<ReactNode>(initial);
   const [pendingUrl, setPendingUrl] = useState<string | null>(null);
   const [, startTransition] = useTransition();
@@ -82,20 +89,31 @@ export function TransitionRoot({ initial, topLoaderConfig }: { initial: ReactNod
   // both apply in the same React commit — making the pending→active transition
   // atomic (no frame where pending is false but the old tree is still visible).
   _navigateTransition = (url: string, perform: () => Promise<ReactNode>) => {
-    // Urgent: show pending state immediately
+    // Urgent: show pending state immediately (for TopLoader / useNavigationPending)
     setPendingUrl(url);
 
     return new Promise<void>((resolve, reject) => {
       startTransition(async () => {
+        // Capture the current nav ID before async work begins.
+        // Used to guard against stale clears when a newer navigation
+        // supersedes this one.
+        const navId = getCurrentNavId();
         try {
           const newElement = await perform();
           setElement(newElement);
           // Clear pending inside the transition — commits atomically with new tree
           setPendingUrl(null);
+          // Reset per-link pending state. The navId guard ensures a stale
+          // transition (T1) doesn't clear a newer navigation's (T2) link.
+          // The setter call is a transition update — batched with setElement
+          // and setPendingUrl, so pending clears atomically with new tree.
+          // See design/19-client-navigation.md §"Per-Link Pending State"
+          resetLinkPending(navId);
           resolve();
         } catch (err) {
           // Clear pending on error too
           setPendingUrl(null);
+          resetLinkPending(navId);
           reject(err);
         }
       });

package/src/client/use-params.ts

@@ -30,7 +30,7 @@
  * Design doc: design/09-typescript.md §"Typed Routes"
  */
 
-import type { Routes } from '#/index.js';
+import type { Routes } from '../index.js';
 import { getSsrData } from './ssr-data.js';
 import { currentParams, _setCurrentParams, paramsListeners } from './state.js';
 import { useNavigationContext } from './navigation-context.js';
@@ -119,9 +119,9 @@ export function notifyParamsListeners(): void {
  *   exact params shape from the generated Routes interface.
  * @overload Fallback — returns the generic params record.
  */
-export function useParams<R extends keyof Routes>(route: R): Routes[R]['params'];
-export function useParams(route?: string): Record<string, string | string[]>;
-export function useParams(_route?: string): Record<string, string | string[]> {
+export function useSegmentParams<R extends keyof Routes>(route: R): Routes[R]['params'];
+export function useSegmentParams(route?: string): Record<string, string | string[]>;
+export function useSegmentParams(_route?: string): Record<string, string | string[]> {
   // Try reading from NavigationContext (client-side, inside React tree).
   // During SSR, no NavigationProvider is mounted, so this returns null.
   // When called outside a React component, useContext throws — caught below.

package/src/client/use-query-states.ts

@@ -17,8 +17,8 @@ import type {
   SearchParamsDefinition,
   SetParams,
   QueryStatesOptions,
-} from '#/search-params/create.js';
-import { getSearchParams } from '#/search-params/registry.js';
+} from '../search-params/define.js';
+import { getSearchParams } from '../search-params/registry.js';
 
 // ─── Codec Bridge ─────────────────────────────────────────────────
 

package/src/codec.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared codec protocol for parsing and serializing string values.
+ *
+ * Used by both search params and cookies. Any object with parse + serialize
+ * methods satisfies this interface. nuqs parsers are valid codecs natively.
+ *
+ * Design doc: design/23a-search-params-triage.md §"Unify Codec<T> type"
+ */
+
+/**
+ * A codec that converts between string values and typed values.
+ *
+ * The canonical protocol shared across search params, cookies, and
+ * any future timber feature that needs string ↔ typed conversion.
+ */
+export interface Codec<T> {
+  /** String → typed value. Receives undefined when the value is absent. */
+  parse(value: string | string[] | undefined): T;
+  /** Typed value → string. Return null to omit/clear. */
+  serialize(value: T): string | null;
+}

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 ──────────────────────────────────────────────────────────────
 
 /**
@@ -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}`;
 }
 
 /**