@timber-js/app 0.2.0-alpha.13 → 0.2.0-alpha.132

package/src/server/tree-match.ts

@@ -0,0 +1,210 @@
+/**
+ * Shared URL-matching tree walker for segment trees.
+ *
+ * Both the main route matcher (`route-matcher.ts`) and slot resolver
+ * (`slot-resolver.ts`) need to walk a SegmentNode tree, matching URL
+ * parts against children with the same priority semantics:
+ *
+ *   static > dynamic > catch-all > optional-catch-all
+ *
+ * Before this module, each had its own walker with subtle divergences
+ * (different group handling, missing backtracking, incomplete
+ * optional-catch-all support). This shared walker is the single
+ * source of truth for URL-to-segment matching.
+ *
+ * See design/07-routing.md §"Request Lifecycle" and TIM-940.
+ */
+
+import type { SegmentNode } from '../routing/types.js';
+
+// ─── Public API ───────────────────────────────────────────────────────────
+
+/** Result of matching URL parts against a segment tree. */
+export interface TreeMatchResult<TFile> {
+  /** Matched segment chain from root to leaf, inclusive. */
+  chain: SegmentNode<TFile>[];
+  /** Collected params, keyed by param name. Catch-all params are string[]. */
+  params: Record<string, string | string[]>;
+}
+
+export interface TreeMatchOptions {
+  /**
+   * When true (default), only match if the leaf node has a page or route
+   * handler. Set to false for metadata route matching, where we just need
+   * to find the owning segment regardless of whether it has a page.
+   */
+  requireTerminal?: boolean;
+}
+
+/**
+ * Match URL path parts against a segment tree.
+ *
+ * Walks the tree depth-first with backtracking, applying priority
+ * ordering globally across group boundaries. Returns the matched
+ * segment chain and collected params, or null if no route matches.
+ *
+ * By default, a match requires a terminal node (one with `page` or
+ * `route`) at the leaf. Pass `{ requireTerminal: false }` to match
+ * any segment (used by metadata route matching).
+ *
+ * @param root  The root segment node to start matching from.
+ * @param parts URL path parts (e.g. ['blog', 'hello-world']).
+ *              Empty array matches the root itself (if terminal).
+ */
+export function matchUrlParts<TFile>(
+  root: SegmentNode<TFile>,
+  parts: string[],
+  options?: TreeMatchOptions
+): TreeMatchResult<TFile> | null {
+  const chain: SegmentNode<TFile>[] = [];
+  const params: Record<string, string | string[]> = {};
+  const requireTerminal = options?.requireTerminal ?? true;
+
+  if (matchNode(root, parts, 0, chain, params, requireTerminal)) {
+    return { chain, params };
+  }
+  return null;
+}
+
+// ─── Internal ─────────────────────────────────────────────────────────────
+
+/**
+ * A child node flattened through group segments, along with the
+ * chain of group nodes that must appear in the segment chain
+ * before the child to preserve the tree path.
+ */
+interface EffectiveChild<TFile> {
+  child: SegmentNode<TFile>;
+  groupChain: SegmentNode<TFile>[];
+}
+
+/**
+ * Flatten children through group segments.
+ *
+ * Groups are transparent for URL matching — their non-group descendants
+ * are returned with the chain of group nodes leading to them. This lets
+ * the caller apply priority ordering (static > dynamic > catch-all >
+ * optional-catch-all) across all groups uniformly instead of per-group.
+ */
+function collectEffectiveChildren<TFile>(
+  node: SegmentNode<TFile>,
+  groupChain: SegmentNode<TFile>[] = []
+): EffectiveChild<TFile>[] {
+  const result: EffectiveChild<TFile>[] = [];
+  for (const child of node.children) {
+    if (child.segmentType === 'group') {
+      const nested = collectEffectiveChildren(child, [...groupChain, child]);
+      result.push(...nested);
+    } else {
+      result.push({ child, groupChain });
+    }
+  }
+  return result;
+}
+
+/** A node is terminal if it can serve a response (has a page or route handler). */
+function isTerminal<TFile>(node: SegmentNode<TFile>): boolean {
+  return !!(node.page || node.route);
+}
+
+/**
+ * Recursive depth-first matcher with backtracking.
+ *
+ * Mutates `chain` and `params` in place for performance; backtracks
+ * (restores previous state) when a candidate doesn't lead to a match.
+ */
+function matchNode<TFile>(
+  node: SegmentNode<TFile>,
+  parts: string[],
+  index: number,
+  chain: SegmentNode<TFile>[],
+  params: Record<string, string | string[]>,
+  requireTerminal: boolean
+): boolean {
+  chain.push(node);
+
+  // All parts consumed — check if this node is terminal (or any node if !requireTerminal)
+  if (index >= parts.length) {
+    if (!requireTerminal || isTerminal(node)) return true;
+
+    // Groups don't consume URL segments, so a group child's page can
+    // match at the same URL depth. Recurse into groups transparently.
+    for (const child of node.children) {
+      if (child.segmentType === 'group') {
+        if (matchNode(child, parts, index, chain, params, requireTerminal)) {
+          return true;
+        }
+      }
+    }
+
+    // Optional catch-all with zero segments (direct and through groups).
+    // The param is NOT set — matching Next.js semantics for [[...slug]]
+    // with no path segments.
+    const effective = collectEffectiveChildren(node);
+    for (const { child, groupChain } of effective) {
+      if (child.segmentType === 'optional-catch-all' && isTerminal(child)) {
+        chain.push(...groupChain, child);
+        return true;
+      }
+    }
+
+    chain.pop();
+    return false;
+  }
+
+  const part = parts[index];
+
+  // Flatten children through groups so priority ordering applies globally.
+  const effective = collectEffectiveChildren(node);
+
+  // 1. Static segments (exact name match)
+  for (const { child, groupChain } of effective) {
+    if (child.segmentType === 'static' && child.segmentName === part) {
+      chain.push(...groupChain);
+      if (matchNode(child, parts, index + 1, chain, params, requireTerminal)) {
+        return true;
+      }
+      chain.length -= groupChain.length;
+    }
+  }
+
+  // 2. Dynamic segments ([param])
+  for (const { child, groupChain } of effective) {
+    if (child.segmentType === 'dynamic' && child.paramName) {
+      chain.push(...groupChain);
+      const prev = params[child.paramName];
+      params[child.paramName] = part;
+      if (matchNode(child, parts, index + 1, chain, params, requireTerminal)) {
+        return true;
+      }
+      // Backtrack
+      chain.length -= groupChain.length;
+      if (prev !== undefined) {
+        params[child.paramName] = prev;
+      } else {
+        delete params[child.paramName];
+      }
+    }
+  }
+
+  // 3. Catch-all segments ([...param]) — must be terminal
+  for (const { child, groupChain } of effective) {
+    if (child.segmentType === 'catch-all' && child.paramName && isTerminal(child)) {
+      chain.push(...groupChain, child);
+      params[child.paramName] = parts.slice(index);
+      return true;
+    }
+  }
+
+  // 4. Optional catch-all segments ([[...param]]) — must be terminal
+  for (const { child, groupChain } of effective) {
+    if (child.segmentType === 'optional-catch-all' && child.paramName && isTerminal(child)) {
+      chain.push(...groupChain, child);
+      params[child.paramName] = parts.slice(index);
+      return true;
+    }
+  }
+
+  chain.pop();
+  return false;
+}

package/src/server/types.ts

@@ -22,8 +22,7 @@ export interface MiddlewareContext {
   req: Request;
   requestHeaders: Headers;
   headers: Headers;
-  params: Record<string, string | string[]>;
-  searchParams: unknown;
+  segmentParams: Record<string, string | string[]>;
   /** Declare early hints for critical resources. Appends Link headers. */
   earlyHints: (hints: EarlyHint[]) => void;
 }
@@ -35,10 +34,8 @@ export interface RouteContext {
   headers: Headers;
 }
 
-export interface AccessContext {
-  params: Record<string, string | string[]>;
-  searchParams: unknown;
-}
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface AccessContext {}
 
 export interface Metadata {
   title?: string | { default?: string; template?: string; absolute?: string };
@@ -163,4 +160,56 @@ export namespace MetadataRoute {
     sitemap?: string | string[];
     host?: string;
   }
+  /**
+   * PWA Web App Manifest — serialized as `application/manifest+json`.
+   *
+   * Intentionally permissive: the manifest spec is large and evolving
+   * (W3C + browser-specific extensions). Users that want stricter typing
+   * can augment the return type with a library like `web-app-manifest`.
+   */
+  export type Manifest = Record<string, unknown>;
 }
+
+/**
+ * The value a dynamic metadata route handler may return.
+ *
+ * This is a structural union — the pipeline dispatches on the shape at
+ * request time (see `pipeline-phases.ts`):
+ *   - `Response` → returned as-is (e.g. `ImageResponse`, `Response.redirect()`).
+ *     Used by `icon.tsx`, `opengraph-image.tsx`,
+ *     `apple-icon.tsx`.
+ *   - `string` → written as the response body verbatim. Used by `robots.ts`
+ *     and by any handler that wants to emit a pre-serialized payload.
+ *   - `MetadataRoute.Sitemap` → serialized via the sitemap XML writer. Used
+ *     by `sitemap.ts`.
+ *   - `MetadataRoute.Manifest` → serialized via `JSON.stringify`. Used by
+ *     `manifest.ts`.
+ *
+ * See design/16-metadata.md §"Metadata Routes".
+ */
+export type MetadataResult = Response | string | MetadataRoute.Sitemap | MetadataRoute.Manifest;
+
+/**
+ * Default export signature for a dynamic metadata route file
+ * (`sitemap.ts`, `robots.ts`, `manifest.ts`, `icon.tsx`,
+ * `opengraph-image.tsx`, `apple-icon.tsx`).
+ *
+ * Parameterize `TResult` to narrow the return type for a specific route:
+ *
+ * ```ts
+ * // app/sitemap.ts
+ * import type { MetadataHandler, MetadataRoute } from '@timber-js/app/server';
+ *
+ * const sitemap: MetadataHandler<MetadataRoute.Sitemap> = async () => [
+ *   { url: 'https://example.com/', changeFrequency: 'weekly', priority: 1 },
+ * ];
+ * export default sitemap;
+ * ```
+ *
+ * The handler is currently invoked with no arguments. Per-request context
+ * (`params`, `searchParams`, `Request`) is not yet wired through to metadata
+ * route handlers; when it is, this signature will grow a context parameter.
+ */
+export type MetadataHandler<TResult extends MetadataResult = MetadataResult> = () =>
+  | TResult
+  | Promise<TResult>;

package/src/server/utils/escape-html.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared HTML escaping utility.
+ *
+ * Used by both dev-only paths (error pages, 404 page) and production
+ * paths (deny-renderer, RSC helpers). Lives in server/utils/ because
+ * it's not dev-only.
+ */
+
+/**
+ * Escape a string for safe embedding in HTML content or attributes.
+ *
+ * Replaces `&`, `<`, `>`, and `"` with their HTML entity equivalents.
+ */
+export function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}

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';