@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.191

package/src/server/types.ts

@@ -1,5 +1,6 @@
 // Server-side type definitions
 
+import type { CoercedParams } from '../shared/param-value.js';
 import type { EarlyHint } from './early-hints.js';
 
 /**
@@ -22,23 +23,45 @@ export interface MiddlewareContext {
   req: Request;
   requestHeaders: Headers;
   headers: Headers;
-  params: Record<string, string | string[]>;
-  searchParams: unknown;
+  segmentParams: CoercedParams;
   /** Declare early hints for critical resources. Appends Link headers. */
   earlyHints: (hints: EarlyHint[]) => void;
 }
 
+/**
+ * Context passed to `route.ts` HTTP method handlers (GET/POST/etc.).
+ *
+ * `req` is the original incoming Request; `headers` is the response-headers
+ * container the framework will apply to the final Response.
+ *
+ * Segment params and query parameters are NOT on this context — they are read
+ * the same way pages read them:
+ *
+ * ```ts
+ * // app/schema.ts — every dynamic segment's codec, keyed by bracket name
+ * export default defineSchema({ segmentParams: { '[id]': z.coerce.number() } });
+ *
+ * // app/api/users/[id]/route.ts
+ * import { getSegmentParams } from '@timber-js/app/server';
+ * import { SEGMENT_PATH } from './$segment';
+ * export async function GET() {
+ *   const { id } = getSegmentParams(SEGMENT_PATH); // typed number — 404 on bad input
+ * }
+ * ```
+ *
+ * For query parameters, import a `defineSearchParams` definition and call
+ * `.get()` on it.
+ *
+ * See design/07-routing.md §"RouteContext", design/23-search-params.md,
+ * design/41-global-params.md.
+ */
 export interface RouteContext {
   req: Request;
-  params: Record<string, string | string[]>;
-  searchParams: URLSearchParams;
   headers: Headers;
 }
 
-export interface AccessContext {
-  params: Record<string, string | string[]>;
-  searchParams: unknown;
-}
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type, typescript/no-empty-interface
+export interface AccessContext {}
 
 export interface Metadata {
   title?: string | { default?: string; template?: string; absolute?: string };
@@ -146,7 +169,7 @@ export interface Metadata {
 
 // eslint-disable-next-line @typescript-eslint/no-namespace
 export namespace MetadataRoute {
-  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type, typescript/no-empty-interface
   export interface Sitemap extends Array<SitemapEntry> {}
   export interface SitemapEntry {
     url: string;
@@ -163,4 +186,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/element-type.ts

@@ -0,0 +1,72 @@
+/**
+ * Component-type validation for values loaded from route modules.
+ *
+ * Route modules are loaded dynamically, so their `default` export is
+ * `unknown`. Every construction site that wants to pass one to
+ * `createElement` narrows it through `isValidElementType` first.
+ */
+
+import type { ReactNode } from 'react';
+
+/**
+ * A React component reference loaded from a route module's default export.
+ *
+ * Loaded modules' `default` is typed as `unknown` (modules are dynamic), so
+ * call sites narrow it through `isValidElementType` (below) before treating
+ * it as a component. The signature is a callable returning `ReactNode` —
+ * TypeScript's view of every valid React component shape, including exotic
+ * components (`memo`, `forwardRef`, `lazy`) which the type system treats as
+ * callable even though their runtime values are objects with `$$typeof`
+ * markers rather than functions.
+ */
+export type LoadedComponent = (...args: unknown[]) => ReactNode;
+
+// Marker symbols React stamps onto exotic component types. Mirrors the
+// internal `isValidElementType` check in `react.development.js` — React
+// doesn't export it, and we don't want to add `react-is` just for this one
+// validation. Inlined the same way `isClientReference` in
+// `route-element-builder.ts` inlines the client-reference marker.
+const REACT_FORWARD_REF_TYPE = Symbol.for('react.forward_ref');
+const REACT_MEMO_TYPE = Symbol.for('react.memo');
+const REACT_LAZY_TYPE = Symbol.for('react.lazy');
+const REACT_PROVIDER_TYPE = Symbol.for('react.provider');
+const REACT_CONTEXT_TYPE = Symbol.for('react.context');
+const REACT_SUSPENSE_TYPE = Symbol.for('react.suspense');
+const REACT_SUSPENSE_LIST_TYPE = Symbol.for('react.suspense_list');
+const REACT_CLIENT_REFERENCE_TYPE = Symbol.for('react.client.reference');
+
+const REACT_COMPONENT_TYPE_MARKERS: ReadonlySet<symbol> = new Set([
+  REACT_FORWARD_REF_TYPE,
+  REACT_MEMO_TYPE,
+  REACT_LAZY_TYPE,
+  REACT_PROVIDER_TYPE,
+  REACT_CONTEXT_TYPE,
+  REACT_SUSPENSE_TYPE,
+  REACT_SUSPENSE_LIST_TYPE,
+  REACT_CLIENT_REFERENCE_TYPE,
+]);
+
+/**
+ * Validate that a loaded module's `default` export is something React
+ * accepts as the first argument to `createElement` — i.e. a valid component
+ * type. React doesn't export `isValidElementType` (only `isValidElement`,
+ * which checks for *elements*, not *component types*), so this mirrors
+ * React's internal check:
+ *
+ *   - functions  → function or class components
+ *   - objects with a `$$typeof` matching one of React's known component
+ *     markers → exotic components (`memo`, `forwardRef`, `lazy`, context,
+ *     suspense, client references via `@vitejs/plugin-rsc`)
+ *
+ * Strings (HTML tag names) are valid for `createElement` but never appear
+ * as a route module's default export, so they're not recognized here.
+ *
+ * Anything else (numbers, plain config objects, JSON, etc.) is rejected so
+ * the boundary wrapper is skipped rather than crashing inside React.
+ */
+export function isValidElementType(value: unknown): value is LoadedComponent {
+  if (typeof value === 'function') return true;
+  if (typeof value !== 'object' || value === null) return false;
+  const marker = (value as { $$typeof?: unknown }).$$typeof;
+  return typeof marker === 'symbol' && REACT_COMPONENT_TYPE_MARKERS.has(marker);
+}

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/utils/mdx-file.ts

@@ -0,0 +1,22 @@
+/**
+ * MDX file-path detection shared by error/deny rendering paths.
+ *
+ * MDX status and error files are server components — they cannot be passed
+ * as function props across the RSC→client boundary (e.g. to
+ * TimberErrorBoundary or ErrorReconstituter) and must be pre-rendered as
+ * elements with plain props instead.
+ *
+ * See design/10-error-handling.md §"Status-Code File Variants".
+ */
+
+/** MDX/markdown extensions — server components by default. */
+const MDX_EXTENSIONS = new Set(['.mdx', '.md']);
+
+/**
+ * Check if a file path ends with an MDX/markdown extension.
+ */
+export function isMdxFilePath(filePath: string): boolean {
+  const dotIndex = filePath.lastIndexOf('.');
+  if (dotIndex === -1) return false;
+  return MDX_EXTENSIONS.has(filePath.slice(dotIndex));
+}

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/server/workers-cache-bridge.ts

@@ -0,0 +1,33 @@
+/**
+ * Per-request Workers Cache purge bridge — ALS bridge for Cloudflare adapter.
+ *
+ * The generated _worker.js wraps each request with `runWithWorkersCachePurge`,
+ * binding `ctx.cache` from the Cloudflare ExecutionContext. The
+ * `WorkersCachePurge` CDN purge handler reads from this ALS to call
+ * `ctx.cache.purge({ tags })` without needing an API token.
+ *
+ * Design doc: design/06-caching.md, design/25-production-deployments.md
+ */
+
+import { workersCachePurgeAls } from './als-registry.js';
+import type { WorkersCachePurgeCtx } from './als-registry.js';
+
+/**
+ * Run a function with Workers Cache purge context available.
+ *
+ * Called by the generated Cloudflare _worker.js entry to bind
+ * `ctx.cache` for the request duration.
+ */
+export function runWithWorkersCachePurge<T>(ctx: WorkersCachePurgeCtx, fn: () => T): T {
+  return workersCachePurgeAls.run(ctx, fn);
+}
+
+/**
+ * Get the current request's Workers Cache context, if available.
+ *
+ * Returns undefined outside a Cloudflare Workers request context
+ * or on platforms without Workers Cache support.
+ */
+export function getWorkersCachePurgeCtx(): WorkersCachePurgeCtx | undefined {
+  return workersCachePurgeAls.getStore();
+}

package/src/shared/als-slots.ts

@@ -0,0 +1,74 @@
+/**
+ * ALS getter slots for the isomorphic `define*` modules.
+ *
+ * `searchParams.get()` and `segmentParams.get()` read per-request state out of
+ * `server/als-registry.ts`, but the modules that expose them are *isomorphic*:
+ * `search-params/define.ts` and `segment-params/define.ts` are imported by
+ * `'use client'` components for their hooks, so neither may import
+ * `node:async_hooks` — not even transitively, because the dep optimizer
+ * pre-bundles them before per-environment resolution runs. So the server
+ * registers its getter into a slot at module-init time and the define modules
+ * read the slot.
+ *
+ * The slots live here, in a module with **no imports at all**, rather than in
+ * the define modules themselves. That is the whole point: `request-context.ts`
+ * has to reach the setter, and when the setter lived in
+ * `search-params/define.ts` every server entry that touched
+ * `@timber-js/app/server` pulled that module — and therefore its `'use client'`
+ * import of `client/use-query-states.ts`, and therefore `nuqs` — into the
+ * server graph. `nuqs` named-imports `createContext`/`useContext` from React,
+ * which React's `react-server` export withholds, so `@timber-js/app`,
+ * `@timber-js/app/server`, `@timber-js/app/cookies` and `@timber-js/app/cache`
+ * all failed to instantiate under the `react-server` condition (TIM-1298).
+ * A leaf module breaks the edge without a registration ceremony on either side.
+ *
+ * Registration must be eager, not a call-time `await import()`: the async
+ * microtask a dynamic import introduces loses AsyncLocalStorage context inside
+ * React's RSC Flight renderer, which broke `getSearchParams()` in parallel slot
+ * pages (TIM-523).
+ *
+ * See design/23-search-params.md §"defineSearchParams — The Factory" and
+ * design/41-global-params.md.
+ */
+
+import type { CoercedParams } from './param-value.js';
+
+interface AlsSlot<T> {
+  /** Register the server-side getter. Called once at module-init time. */
+  set(fn: () => T): void;
+  /** Read through to the registered getter, or throw the client-side message. */
+  get(): T;
+}
+
+function createAlsSlot<T>(message: string): AlsSlot<T> {
+  let fn: (() => T) | undefined;
+  return {
+    set(next) {
+      fn = next;
+    },
+    get() {
+      if (!fn) throw new Error(message);
+      return fn();
+    },
+  };
+}
+
+const searchParamsSlot = createAlsSlot<URLSearchParams>(
+  '[timber] searchParams.get() is only available on the server. ' +
+    'Use searchParams.useQueryStates() on the client.'
+);
+
+const segmentParamsSlot = createAlsSlot<CoercedParams>(
+  '[timber] segmentParams.get() is only available on the server. ' +
+    'Use segmentParams.useSegmentParams() on the client.'
+);
+
+/** @internal Called from `server/request-context.ts` at module init. */
+export const _setGetSearchParamsFn = searchParamsSlot.set;
+/** @internal Read by `search-params/define.ts` inside `.get()`. */
+export const getSearchParamsFromAls = searchParamsSlot.get;
+
+/** @internal Called from `server/request-context.ts` at module init. */
+export const _setGetSegmentParamsFn = segmentParamsSlot.set;
+/** @internal Read by `segment-params/define.ts` inside `.get()`. */
+export const getSegmentParamsFromAls = segmentParamsSlot.get;

package/src/shared/base-path.ts

@@ -0,0 +1,80 @@
+/**
+ * Deployment base path — Vite's resolved `base`, as it applies to the URLs
+ * timber addresses at runtime.
+ *
+ * A static build deployed under a sub-path (`base: '/repo/'`, the GitHub
+ * Pages project-site layout) serves every generated file below that prefix:
+ * the document for `/about` lives at `/repo/about/index.html`, its flight
+ * payload at `/repo/_rsc/about/index.rsc`. The client works in *route space* — the
+ * paths the app declares — so both a strip (browser URL → route path) and a
+ * prefix (route-space path → URL) are needed, and this module owns both.
+ *
+ * Pure functions, no state: the caller supplies the base. `client/rsc-fetch.ts`
+ * holds the client's copy, set at bootstrap from `virtual:timber-config`.
+ *
+ * See design/11-platform.md §"Deploying under a non-root base" (TIM-1261).
+ */
+
+/** `https://cdn.example.com/`, `//cdn.example.com/` — a base pointing off-origin. */
+function isAbsoluteUrlBase(base: string): boolean {
+  return base.startsWith('//') || /^[a-z][a-z0-9+.-]*:\/\//i.test(base);
+}
+
+/**
+ * True when `base` is document-relative (`'./'`, `'foo/'`) — it makes asset
+ * URLs resolve against whatever document loaded them, which says nothing
+ * about where the deployment sits, so no prefix can be computed from it.
+ */
+export function isRelativeBase(base: string | undefined): boolean {
+  if (!base) return false;
+  return !base.startsWith('/') && !isAbsoluteUrlBase(base);
+}
+
+/**
+ * Normalize Vite's `base` into a path prefix. Always returns a value with a
+ * leading and trailing slash.
+ *
+ * Two forms carry no usable deployment prefix and normalize to `/`:
+ *
+ * - **An absolute-URL base** points *assets* at a CDN. The HTML documents and
+ *   `.rsc` payloads are still served from the deployment origin, so their
+ *   URLs stay root-relative. This is correct, not a degradation.
+ * - **A relative base** — see `isRelativeBase`. The static build warns,
+ *   because SPA navigation then only works at the domain root.
+ */
+export function normalizeBasePath(base: string | undefined): string {
+  if (!base) return '/';
+  if (isAbsoluteUrlBase(base) || isRelativeBase(base)) return '/';
+  return base.endsWith('/') ? base : `${base}/`;
+}
+
+/**
+ * Strip the base prefix from a browser pathname, returning the route-space
+ * path. With base `/repo/`: `/repo/about` → `/about`, `/repo/` and `/repo`
+ * → `/`.
+ *
+ * A pathname outside the base is returned unchanged. It cannot be served by
+ * this deployment at all, so there is no better answer than letting the
+ * resulting fetch 404 and the router hard-navigate — visibly wrong beats
+ * silently rewritten.
+ *
+ * @param base A normalized base (see `normalizeBasePath`).
+ */
+export function stripBasePath(base: string, pathname: string): string {
+  if (base === '/') return pathname;
+  const withoutTrailingSlash = base.slice(0, -1);
+  if (pathname === withoutTrailingSlash) return '/';
+  if (!pathname.startsWith(base)) return pathname;
+  return pathname.slice(withoutTrailingSlash.length);
+}
+
+/**
+ * Prefix a route-space, root-relative path with the base.
+ * `/_rsc/about/index.rsc` → `/repo/_rsc/about/index.rsc`.
+ *
+ * @param base A normalized base (see `normalizeBasePath`).
+ */
+export function withBasePath(base: string, path: string): string {
+  if (base === '/') return path;
+  return path.startsWith('/') ? base.slice(0, -1) + path : `${base}${path}`;
+}