@timber-js/app 0.2.0-alpha.10 → 0.2.0-alpha.100

package/src/server/version-skew.ts

@@ -0,0 +1,104 @@
+/**
+ * Version Skew Detection — graceful recovery when stale clients hit new deployments.
+ *
+ * When a new version of the app is deployed, clients with open tabs still have
+ * the old JavaScript bundle. Without version skew handling, these stale clients
+ * will experience:
+ *
+ * 1. Server action calls that crash (action IDs are content-hashed)
+ * 2. Chunk load failures (old filenames gone from CDN)
+ * 3. RSC payload mismatches (component references differ between builds)
+ *
+ * This module implements deployment ID comparison:
+ * - A per-build deployment ID is generated at build time (see build-manifest.ts)
+ * - The client sends it via `X-Timber-Deployment-Id` header on every RSC/action request
+ * - The server compares it against the current build's ID
+ * - On mismatch: signal the client to reload (not crash)
+ *
+ * The deployment ID is always-on in production. Dev mode skips the check
+ * (HMR handles code updates without full reloads).
+ *
+ * See design/25-production-deployments.md, TIM-446
+ */
+
+// ─── Constants ───────────────────────────────────────────────────
+
+/** Header sent by the client with every RSC/action request. */
+export const DEPLOYMENT_ID_HEADER = 'X-Timber-Deployment-Id';
+
+/** Response header that signals the client to do a full page reload. */
+export const RELOAD_HEADER = 'X-Timber-Reload';
+
+// ─── Deployment ID ───────────────────────────────────────────────
+
+/**
+ * The current build's deployment ID. Set at startup from the manifest init
+ * module (globalThis.__TIMBER_DEPLOYMENT_ID__). Null in dev mode.
+ */
+let currentDeploymentId: string | null = null;
+
+/**
+ * Set the current deployment ID. Called once at server startup from the
+ * manifest init module. In dev mode this is never called (deployment ID
+ * checks are skipped).
+ */
+export function setDeploymentId(id: string): void {
+  currentDeploymentId = id;
+}
+
+/**
+ * Get the current deployment ID. Returns null in dev mode.
+ */
+export function getDeploymentId(): string | null {
+  return currentDeploymentId;
+}
+
+// ─── Skew Detection ──────────────────────────────────────────────
+
+/** Result of a version skew check. */
+export interface SkewCheckResult {
+  /** Whether the client's deployment ID matches the server's. */
+  ok: boolean;
+  /** The client's deployment ID (null if header not sent — e.g., initial page load). */
+  clientId: string | null;
+}
+
+/**
+ * Check if a request's deployment ID matches the current build.
+ *
+ * Returns `{ ok: true }` when:
+ * - Dev mode (no deployment ID set — HMR handles updates)
+ * - No deployment ID header (initial page load, non-RSC request)
+ * - Deployment IDs match
+ *
+ * Returns `{ ok: false }` when:
+ * - Client sends a deployment ID that differs from the current build
+ */
+export function checkVersionSkew(req: Request): SkewCheckResult {
+  // Dev mode — no deployment ID checks (HMR handles updates)
+  if (!currentDeploymentId) {
+    return { ok: true, clientId: null };
+  }
+
+  const clientId = req.headers.get(DEPLOYMENT_ID_HEADER);
+
+  // No header — initial page load or non-RSC request. Always OK.
+  if (!clientId) {
+    return { ok: true, clientId: null };
+  }
+
+  // Compare deployment IDs
+  if (clientId === currentDeploymentId) {
+    return { ok: true, clientId };
+  }
+
+  return { ok: false, clientId };
+}
+
+/**
+ * Apply version skew reload headers to a response.
+ * Sets X-Timber-Reload: 1 to signal the client to do a full page reload.
+ */
+export function applyReloadHeaders(headers: Headers): void {
+  headers.set(RELOAD_HEADER, '1');
+}

package/src/shared/merge-search-params.ts

@@ -0,0 +1,55 @@
+/**
+ * Shared utility for merging preserved search params into a target URL.
+ *
+ * Used by both <Link> (client) and redirect() (server). Extracted to a shared
+ * module to avoid importing client code ('use client') from server modules.
+ */
+
+/**
+ * Merge preserved search params from the current URL into a target href.
+ *
+ * When `preserve` is `true`, all current search params are merged.
+ * When `preserve` is a `string[]`, only the named params are merged.
+ *
+ * The target href's own search params take precedence — preserved params
+ * are only added if the target doesn't already define them.
+ *
+ * @param targetHref - The resolved target href (may already contain query string)
+ * @param currentSearch - The current URL's search string (e.g. "?private=access&page=2")
+ * @param preserve - `true` to preserve all, or `string[]` to preserve specific params
+ * @returns The target href with preserved search params merged in
+ */
+export function mergePreservedSearchParams(
+  targetHref: string,
+  currentSearch: string,
+  preserve: true | string[]
+): string {
+  const currentParams = new URLSearchParams(currentSearch);
+  if (currentParams.size === 0) return targetHref;
+
+  // Split hash fragment from target before processing query params.
+  // Hash must come after query string: /path?query=value#hash
+  const hashIdx = targetHref.indexOf('#');
+  const hrefWithoutHash = hashIdx >= 0 ? targetHref.slice(0, hashIdx) : targetHref;
+  const hash = hashIdx >= 0 ? targetHref.slice(hashIdx) : '';
+
+  // Split target into path and existing query
+  const qIdx = hrefWithoutHash.indexOf('?');
+  const targetPath = qIdx >= 0 ? hrefWithoutHash.slice(0, qIdx) : hrefWithoutHash;
+  const targetParams = new URLSearchParams(qIdx >= 0 ? hrefWithoutHash.slice(qIdx + 1) : '');
+
+  // Collect params to preserve (that aren't already in the target)
+  const merged = new URLSearchParams(targetParams);
+  for (const [key, value] of currentParams) {
+    // Only preserve if: (a) not already in target, and (b) included in preserve list
+    if (!targetParams.has(key)) {
+      if (preserve === true || preserve.includes(key)) {
+        merged.append(key, value);
+      }
+    }
+  }
+
+  const qs = merged.toString();
+  const pathWithQuery = qs ? `${targetPath}?${qs}` : targetPath;
+  return pathWithQuery + hash;
+}

package/src/shims/font-google.ts

@@ -17,7 +17,7 @@
  * Design doc: 24-fonts.md, "Next.js Font Compatibility"
  */
 
-import type { GoogleFontConfig, FontResult } from '#/fonts/types.js';
+import type { GoogleFontConfig, FontResult } from '../fonts/types.js';
 
 export type { GoogleFontConfig, FontResult };
 

package/src/shims/font-local.ts

@@ -0,0 +1,34 @@
+/**
+ * Fallback shim for `next/font/local` → `@timber/fonts/local`.
+ *
+ * At build time, the timber-fonts plugin's transform hook replaces
+ * `localFont()` calls with static FontResult objects containing real
+ * class names and font stacks. This file serves two purposes:
+ *
+ * 1. **TypeScript resolution** — provides types for IDEs and `tsc` outside
+ *    of Vite's module graph (where the virtual module handles it).
+ * 2. **Runtime fallback** — returns empty className/fontFamily values when
+ *    the plugin hasn't processed a call (e.g. in tests or non-Vite environments).
+ *
+ * Design doc: 24-fonts.md, "Next.js Font Compatibility"
+ */
+
+import type { LocalFontConfig, FontResult } from '../fonts/types.js';
+
+export type { LocalFontConfig, FontResult };
+
+/**
+ * Create a local font.
+ *
+ * The timber-fonts plugin replaces these calls at build time with real
+ * class names and font stacks. This stub ensures code that imports
+ * `localFont` outside of the build pipeline (tests, type-checking)
+ * gets a valid FontResult shape without runtime errors.
+ */
+export default function localFont(config?: LocalFontConfig): FontResult {
+  return {
+    className: '',
+    style: { fontFamily: '' },
+    variable: config?.variable,
+  };
+}

package/src/shims/headers.ts

@@ -6,4 +6,8 @@
  * pipeline (both import from the same shared request-context chunk in dist/).
  */
 
-export { headers, cookies } from '@timber-js/app/server';
+// Re-export timber's primary API
+export { getHeaders, getCookieJar } from '@timber-js/app/server';
+
+// Next.js compat aliases — libraries importing from 'next/headers' expect these names.
+export { getHeaders as headers, getCookieJar as cookies } from '@timber-js/app/server';

package/src/shims/navigation-client.ts

@@ -16,11 +16,12 @@
  * See design/14-ecosystem.md §"next/navigation" for the full shim audit.
  */
 
-// Hooks — imported from the public barrel for module singleton consistency.
+// Hooks — useSegmentParams and useSearchParams import from direct modules
+// since they're no longer in @timber-js/app/client public exports.
+export { useSegmentParams } from '../client/use-segment-params.js';
+export { useSearchParams } from '../client/use-search-params.js';
 export {
-  useParams,
   usePathname,
-  useSearchParams,
   useRouter,
   useSelectedLayoutSegment,
   useSelectedLayoutSegments,

package/src/shims/navigation.ts

@@ -1,20 +1,27 @@
 /**
  * Shim: next/navigation → timber navigation primitives
  *
- * Client hooks import from @timber-js/app/client (the public barrel) so they
- * resolve to the same module instances as user code in Vite dev. Server
- * functions import from @timber-js/app/server for ALS singleton consistency.
+ * Client hooks import from their direct modules since useSegmentParams,
+ * useSearchParams, and useQueryStates are no longer part of
+ * @timber-js/app/client public exports (they live on define* factories).
+ * The shim re-exports them for next/navigation library compat (nuqs etc).
+ *
+ * Server functions import from @timber-js/app/server for ALS singleton consistency.
  */
 
-// Hooks (client-side — imported from public barrel for module singleton)
+// Hooks re-exported for next/navigation compat
+export { useSegmentParams, useSegmentParams as useParams } from '../client/use-segment-params.js';
+export { useSearchParams } from '../client/use-search-params.js';
 export {
-  useParams,
   usePathname,
-  useSearchParams,
   useRouter,
   useSelectedLayoutSegment,
   useSelectedLayoutSegments,
 } from '@timber-js/app/client';
 
 // Functions (server-side)
-export { redirect, permanentRedirect, notFound, RedirectType } from '@timber-js/app/server';
+export { redirect, redirectExternal, RedirectType } from '@timber-js/app/server';
+
+// Next.js compat aliases — these are not part of timber's primary API.
+// They exist so that libraries importing from 'next/navigation' still work.
+export { permanentRedirect, notFound } from '../server/primitives.js';

package/src/utils/directive-parser.ts

@@ -1,6 +1,5 @@
 /**
- * AST-based directive detection for 'use cache', 'use dynamic',
- * 'use client', and 'use server'.
+ * AST-based directive detection for 'use client' and 'use server'.
  *
  * Uses acorn to parse source code and detect directives properly,
  * avoiding false positives from regex matching inside string literals,
@@ -26,31 +25,6 @@ export interface FileDirective {
   line: number;
 }
 
-export interface FunctionWithDirective {
-  /** Function name (or 'default' for anonymous default exports) */
-  name: string;
-  /** The directive found in the function body */
-  directive: string;
-  /** 1-based line number of the directive */
-  directiveLine: number;
-  /** Start offset of the function in the source */
-  start: number;
-  /** End offset of the function in the source */
-  end: number;
-  /** Start offset of the function body block (after the '{') */
-  bodyStart: number;
-  /** End offset of the function body block (the '}') */
-  bodyEnd: number;
-  /** Content between { and } of the function body */
-  bodyContent: string;
-  /** 'export ', 'export default ', or '' */
-  prefix: string;
-  /** Whether this is an arrow function */
-  isArrow: boolean;
-  /** The function signature (everything before the body '{') */
-  declaration: string;
-}
-
 // ---------------------------------------------------------------------------
 // File-level directive detection
 // ---------------------------------------------------------------------------
@@ -164,366 +138,3 @@ function detectFileDirectiveFallback(code: string, directives: string[]): FileDi
 
   return null;
 }
-
-// ---------------------------------------------------------------------------
-// Function-body directive detection
-// ---------------------------------------------------------------------------
-
-/**
- * Find all functions in the source code that contain a directive
- * (e.g. 'use cache', 'use dynamic') as their first body statement.
- *
- * Parses the source with acorn and walks the AST looking for function
- * declarations and arrow function expressions whose body is a
- * BlockStatement with a directive prologue.
- *
- * Returns an array of function info objects, sorted by position
- * (descending) for safe end-to-start replacement.
- */
-export function findFunctionsWithDirective(
-  code: string,
-  directive: string
-): FunctionWithDirective[] {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  let ast: any;
-  try {
-    ast = jsxParser.parse(code, {
-      ecmaVersion: 'latest',
-      sourceType: 'module',
-      locations: true,
-    });
-  } catch {
-    // TypeScript fallback: return empty — callers should use the quick
-    // regex check first and skip non-matching files anyway
-    return findFunctionsWithDirectiveFallback(code, directive);
-  }
-
-  const results: FunctionWithDirective[] = [];
-  walkAst(ast, code, directive, results, []);
-
-  // Sort descending by start position for safe end-to-start replacement
-  results.sort((a, b) => b.start - a.start);
-  return results;
-}
-
-/**
- * Recursive AST walker that finds functions with a directive in their body.
- */
-function walkAst(
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  node: any,
-  code: string,
-  directive: string,
-  results: FunctionWithDirective[],
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  ancestors: any[]
-): void {
-  if (!node || typeof node !== 'object') return;
-
-  if (Array.isArray(node)) {
-    for (const child of node) {
-      walkAst(child, code, directive, results, ancestors);
-    }
-    return;
-  }
-
-  if (!node.type) return;
-
-  // Check function declarations and expressions
-  if (node.type === 'FunctionDeclaration' || node.type === 'FunctionExpression') {
-    checkFunctionBody(node, code, directive, results, ancestors);
-  }
-
-  // Check arrow functions with block bodies
-  if (node.type === 'ArrowFunctionExpression' && node.body && node.body.type === 'BlockStatement') {
-    checkFunctionBody(node, code, directive, results, ancestors);
-  }
-
-  // Walk children
-  const newAncestors = [...ancestors, node];
-  for (const key of Object.keys(node)) {
-    if (key === 'type' || key === 'loc' || key === 'start' || key === 'end') continue;
-    const child = node[key];
-    if (child && typeof child === 'object') {
-      walkAst(child, code, directive, results, newAncestors);
-    }
-  }
-}
-
-/**
- * Check if a function's body starts with the target directive.
- */
-function checkFunctionBody(
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  node: any,
-  code: string,
-  directive: string,
-  results: FunctionWithDirective[],
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  ancestors: any[]
-): void {
-  const body = node.type === 'ArrowFunctionExpression' ? node.body : node.body;
-  if (!body || body.type !== 'BlockStatement' || body.body.length === 0) return;
-
-  // Check the first statement for a directive
-  const firstStmt = body.body[0];
-  if (
-    firstStmt.type !== 'ExpressionStatement' ||
-    firstStmt.expression.type !== 'Literal' ||
-    firstStmt.expression.value !== directive
-  ) {
-    return;
-  }
-
-  // Determine function metadata from AST context
-  const parent = ancestors[ancestors.length - 1];
-  const grandparent = ancestors.length >= 2 ? ancestors[ancestors.length - 2] : null;
-
-  let name = '';
-  let prefix = '';
-  const isArrow = node.type === 'ArrowFunctionExpression';
-  let funcStart = node.start;
-  let funcEnd = node.end;
-
-  if (node.type === 'FunctionDeclaration') {
-    name = node.id?.name || 'default';
-
-    // Check for export
-    if (parent?.type === 'ExportNamedDeclaration') {
-      prefix = 'export ';
-      funcStart = parent.start;
-      funcEnd = parent.end;
-    } else if (parent?.type === 'ExportDefaultDeclaration') {
-      prefix = 'export default ';
-      funcStart = parent.start;
-      funcEnd = parent.end;
-    }
-  } else if (node.type === 'ArrowFunctionExpression') {
-    // Arrow in variable declaration: const name = async () => {}
-    if (parent?.type === 'VariableDeclarator' && parent.id?.name) {
-      name = parent.id.name;
-      // Include the full variable declaration
-      if (grandparent?.type === 'VariableDeclaration') {
-        funcStart = grandparent.start;
-        funcEnd = grandparent.end;
-      }
-    }
-  } else if (node.type === 'FunctionExpression') {
-    // Function expression in variable: const name = async function() {}
-    name = node.id?.name || '';
-    if (parent?.type === 'VariableDeclarator' && parent.id?.name) {
-      name = parent.id.name;
-      if (grandparent?.type === 'VariableDeclaration') {
-        funcStart = grandparent.start;
-        funcEnd = grandparent.end;
-      }
-    }
-  }
-
-  if (!name) return; // Skip anonymous functions we can't name
-
-  // Extract the body content (between the braces)
-  const bodyStart = body.start + 1; // after '{'
-  const bodyEnd = body.end - 1; // before '}'
-  const bodyContent = code.slice(bodyStart, bodyEnd);
-
-  // Extract declaration (everything before the body '{')
-  const declaration = code.slice(funcStart, body.start).trim();
-
-  results.push({
-    name,
-    directive,
-    directiveLine: firstStmt.loc.start.line,
-    start: funcStart,
-    end: funcEnd,
-    bodyStart,
-    bodyEnd,
-    bodyContent,
-    prefix,
-    isArrow,
-    declaration,
-  });
-}
-
-// ---------------------------------------------------------------------------
-// TypeScript fallback for function-body directives
-// ---------------------------------------------------------------------------
-
-/**
- * Fallback that uses regex to find functions with directives when acorn
- * cannot parse the file (TypeScript with type annotations).
- *
- * This is less precise but handles common patterns. The regex approach
- * is only used as a fallback — pure JS/JSX files always use the AST path.
- */
-function findFunctionsWithDirectiveFallback(
-  code: string,
-  directive: string
-): FunctionWithDirective[] {
-  const results: FunctionWithDirective[] = [];
-  const directivePattern = new RegExp(`['"]${escapeRegex(directive)}['"]`);
-
-  // Quick bail-out
-  if (!directivePattern.test(code)) return results;
-
-  // Pattern 1: function declarations
-  const fnDeclPattern =
-    /(?:(export\s+default\s+|export\s+))?async\s+function\s+(\w+)\s*\([^)]*\)\s*\{/g;
-  let match: RegExpExecArray | null;
-
-  while ((match = fnDeclPattern.exec(code)) !== null) {
-    const prefix = match[1]?.trim() || '';
-    const name = match[2];
-    const bodyStart = match.index + match[0].length;
-    const bodyEnd = findMatchingBraceFallback(code, bodyStart - 1);
-    if (bodyEnd === -1) continue;
-
-    const bodyContent = code.slice(bodyStart, bodyEnd);
-    // Check that the directive is the first meaningful statement
-    const trimmedBody = bodyContent.trimStart();
-    if (!trimmedBody.startsWith(`'${directive}'`) && !trimmedBody.startsWith(`"${directive}"`))
-      continue;
-
-    const directiveLine =
-      code.slice(0, bodyStart).split('\n').length +
-      bodyContent.slice(0, bodyContent.indexOf(directive)).split('\n').length -
-      1;
-
-    results.push({
-      name,
-      directive,
-      directiveLine,
-      start: match.index,
-      end: bodyEnd + 1,
-      bodyStart,
-      bodyEnd,
-      bodyContent,
-      prefix: prefix ? prefix + ' ' : '',
-      isArrow: false,
-      declaration: code.slice(match.index, bodyStart - 1).trimEnd(),
-    });
-  }
-
-  // Pattern 2: arrow functions
-  const arrowPattern = /(?:const|let|var)\s+(\w+)\s*=\s*async\s*(\([^)]*\)|[^=]*?)\s*=>\s*\{/g;
-  while ((match = arrowPattern.exec(code)) !== null) {
-    const name = match[1];
-    const bodyStart = match.index + match[0].length;
-    const bodyEnd = findMatchingBraceFallback(code, bodyStart - 1);
-    if (bodyEnd === -1) continue;
-
-    const bodyContent = code.slice(bodyStart, bodyEnd);
-    const trimmedBody = bodyContent.trimStart();
-    if (!trimmedBody.startsWith(`'${directive}'`) && !trimmedBody.startsWith(`"${directive}"`))
-      continue;
-
-    const directiveLine =
-      code.slice(0, bodyStart).split('\n').length +
-      bodyContent.slice(0, bodyContent.indexOf(directive)).split('\n').length -
-      1;
-
-    results.push({
-      name,
-      directive,
-      directiveLine,
-      start: match.index,
-      end: bodyEnd + 1,
-      bodyStart,
-      bodyEnd,
-      bodyContent,
-      prefix: '',
-      isArrow: true,
-      declaration: code.slice(match.index, bodyStart - 1).trimEnd(),
-    });
-  }
-
-  results.sort((a, b) => b.start - a.start);
-  return results;
-}
-
-function escapeRegex(s: string): string {
-  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
-/**
- * Find matching closing brace — same algorithm as cache-transform.ts
- * but kept here for the fallback path only.
- */
-function findMatchingBraceFallback(code: string, openPos: number): number {
-  let depth = 1;
-  let i = openPos + 1;
-
-  while (i < code.length && depth > 0) {
-    const ch = code[i];
-
-    if (ch === "'" || ch === '"') {
-      i = skipStringFallback(code, i);
-      continue;
-    }
-    if (ch === '`') {
-      i = skipTemplateFallback(code, i);
-      continue;
-    }
-    if (ch === '/' && code[i + 1] === '/') {
-      i = code.indexOf('\n', i);
-      if (i === -1) return -1;
-      i++;
-      continue;
-    }
-    if (ch === '/' && code[i + 1] === '*') {
-      i = code.indexOf('*/', i + 2);
-      if (i === -1) return -1;
-      i += 2;
-      continue;
-    }
-
-    if (ch === '{') depth++;
-    else if (ch === '}') depth--;
-    i++;
-  }
-
-  return depth === 0 ? i - 1 : -1;
-}
-
-function skipStringFallback(code: string, start: number): number {
-  const quote = code[start];
-  let i = start + 1;
-  while (i < code.length) {
-    if (code[i] === '\\') {
-      i += 2;
-      continue;
-    }
-    if (code[i] === quote) return i + 1;
-    i++;
-  }
-  return i;
-}
-
-function skipTemplateFallback(code: string, start: number): number {
-  let i = start + 1;
-  while (i < code.length) {
-    if (code[i] === '\\') {
-      i += 2;
-      continue;
-    }
-    if (code[i] === '`') return i + 1;
-    if (code[i] === '$' && code[i + 1] === '{') {
-      i = findMatchingBraceFallback(code, i + 1) + 1;
-      continue;
-    }
-    i++;
-  }
-  return i;
-}
-
-// ---------------------------------------------------------------------------
-// Convenience: quick regex check (for fast bail-out before AST parsing)
-// ---------------------------------------------------------------------------
-
-/**
- * Quick regex check for whether code contains a directive string.
- * Use as a fast bail-out before calling the AST-based functions.
- */
-export function containsDirective(code: string, directive: string): boolean {
-  return code.includes(directive);
-}