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

package/src/params/define.ts

@@ -0,0 +1,327 @@
+/**
+ * defineParams — factory for typed route param coercion.
+ *
+ * Creates a ParamsDefinition that coerces raw string params from the
+ * URL into typed values. Used by exporting from layout.tsx (segment-level)
+ * or page.tsx (fallback).
+ *
+ * Reuses the shared Codec<T> protocol with Standard Schema auto-detection,
+ * same pattern as defineSearchParams. Runtime constraints are stricter:
+ * - serialize must return string (not null — path segments can't be omitted)
+ * - parse throwing → 404 (invalid param value)
+ *
+ * Design doc: design/07a-route-params-triage.md
+ */
+
+import type { Codec } from '../codec.js';
+
+// ---------------------------------------------------------------------------
+// Server-only ALS reference for .load()
+// ---------------------------------------------------------------------------
+
+// Same pattern as search-params: eagerly registered at server startup
+// to avoid dynamic imports that lose ALS context. See TIM-523.
+let _rawSegmentParams: (() => Promise<Record<string, string | string[]>>) | undefined;
+
+/**
+ * Register the rawSegmentParams function. Called once at module load time
+ * from request-context.ts to avoid dynamic import at call time.
+ * @internal
+ */
+export function _setRawSegmentParamsFn(fn: () => Promise<Record<string, string | string[]>>): void {
+  _rawSegmentParams = fn;
+}
+
+function getRawSegmentParams(): Promise<Record<string, string | string[]>> {
+  if (!_rawSegmentParams) {
+    throw new Error(
+      '[timber] segmentParams.load() is only available on the server. ' +
+        'Use useSegmentParams() on the client.'
+    );
+  }
+  return _rawSegmentParams();
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Infer the output type from a Codec or StandardSchemaV1. */
+export type InferParamField<V> =
+  V extends Codec<infer T> ? T : V extends StandardSchemaV1<infer T> ? T : never;
+
+/** Acceptable field value for defineParams: a Codec or a Standard Schema. */
+export type ParamField<T = unknown> = Codec<T> | StandardSchemaV1<T>;
+
+/**
+ * A typed route params definition.
+ *
+ * Returned by defineParams(). Provides parse (string → typed) and
+ * serialize (typed → string) for each declared param.
+ */
+export interface ParamsDefinition<T extends Record<string, unknown>> {
+  /** Parse raw string params into typed values. Throws on invalid values. */
+  parse(raw: Record<string, string | string[]>): T;
+
+  /** Serialize typed values back to strings for URL construction. */
+  serialize(values: T): Record<string, string>;
+
+  /**
+   * Load typed segment params from the current request context (ALS).
+   *
+   * Server-only. Reads rawSegmentParams() from ALS and coerces through
+   * this definition's codecs, returning fully typed params.
+   *
+   * ```ts
+   * // app/products/[id]/params.ts
+   * export const segmentParams = defineSegmentParams({ id: z.coerce.number() })
+   *
+   * // app/products/[id]/page.tsx
+   * import { segmentParams } from './params'
+   * export default async function Page() {
+   *   const { id } = await segmentParams.load() // id: number
+   * }
+   * ```
+   */
+  load(): Promise<T>;
+
+  /** Read-only codec map. */
+  codecs: { [K in keyof T]: Codec<T[K]> };
+}
+
+// ---------------------------------------------------------------------------
+// Standard Schema interface (subset — same as in search-params/define.ts)
+// ---------------------------------------------------------------------------
+
+interface StandardSchemaV1<Output = unknown> {
+  '~standard': {
+    validate(
+      value: unknown
+    ):
+      | { value: Output; issues?: undefined }
+      | { value?: undefined; issues: ReadonlyArray<{ message: string }> }
+      | Promise<
+          | { value: Output; issues?: undefined }
+          | { value?: undefined; issues: ReadonlyArray<{ message: string }> }
+        >;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function isStandardSchema(value: unknown): value is StandardSchemaV1 {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    '~standard' in value &&
+    typeof (value as StandardSchemaV1)['~standard']?.validate === 'function'
+  );
+}
+
+function isCodec(value: unknown): value is Codec<unknown> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as Codec<unknown>).parse === 'function' &&
+    typeof (value as Codec<unknown>).serialize === 'function'
+  );
+}
+
+/**
+ * Validate sync for Standard Schema (same helper as search-params/codecs.ts).
+ */
+function validateSync<Output>(
+  schema: StandardSchemaV1<Output>,
+  value: unknown
+):
+  | { value: Output; issues?: undefined }
+  | { value?: undefined; issues: ReadonlyArray<{ message: string }> } {
+  const result = schema['~standard'].validate(value);
+  if (result instanceof Promise) {
+    throw new Error(
+      '[timber] defineParams: schema returned a Promise — only sync schemas are supported.'
+    );
+  }
+  return result;
+}
+
+/**
+ * Wrap a Standard Schema into a Codec for route params.
+ *
+ * Unlike fromSchema for search params:
+ * - Parse throws on failure (no fallback to default)
+ * - Serialize returns string (not null)
+ */
+function fromParamSchema<T>(fieldName: string, schema: StandardSchemaV1<T>): Codec<T> {
+  return {
+    parse(value: string | string[] | undefined): T {
+      // Route params are always strings (single segment) or string[] (catch-all)
+      const input = Array.isArray(value) ? value : value;
+
+      const result = validateSync(schema, input);
+      if (!result.issues) {
+        return result.value;
+      }
+
+      // For route params, parse failure means the param is invalid → throw
+      const messages = result.issues.map((i) => i.message).join(', ');
+      throw new Error(`[timber] Param '${fieldName}' coercion failed: ${messages}`);
+    },
+
+    serialize(value: T): string | null {
+      if (value === null || value === undefined) {
+        return null;
+      }
+      // Catch-all segments produce arrays — join with '/' for path reconstruction
+      if (Array.isArray(value)) {
+        return value.join('/');
+      }
+      return String(value);
+    },
+  };
+}
+
+/**
+ * Resolve a field value to a Codec. Auto-detects Standard Schema objects.
+ */
+function resolveField(fieldName: string, value: ParamField): Codec<unknown> {
+  if (isCodec(value)) {
+    return value;
+  }
+
+  if (isStandardSchema(value)) {
+    return fromParamSchema(fieldName, value);
+  }
+
+  throw new Error(
+    `[timber] defineParams: field '${fieldName}' is not a valid codec or Standard Schema. ` +
+      `Expected an object with { parse, serialize } methods, or a Standard Schema object ` +
+      `(Zod, Valibot, ArkType).`
+  );
+}
+
+/**
+ * Validate that no codec's serialize returns null.
+ * Route params are structural — they must produce a valid path segment.
+ */
+function validateSerialize(codecMap: Record<string, Codec<unknown>>): void {
+  for (const [key, codec] of Object.entries(codecMap)) {
+    // Test serialize with a sample parsed value to check for null
+    // We can't exhaustively test, but we can check that serialize(parse("test"))
+    // doesn't return null for a basic input.
+    try {
+      const testValue = codec.parse('test');
+      const serialized = codec.serialize(testValue);
+      if (serialized === null) {
+        throw new Error(
+          `[timber] defineParams: field '${key}' codec.serialize() returned null.\n` +
+            `  Route params are path segments — they cannot be omitted.\n` +
+            `  Ensure serialize() always returns a string.`
+        );
+      }
+    } catch (e) {
+      // parse('test') may throw for strict codecs (e.g., number-only).
+      // That's fine — it means the codec validates. We only care about
+      // serialize returning null, which we can't test without a valid value.
+      if (e instanceof Error && e.message.includes('returned null')) {
+        throw e;
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a ParamsDefinition from a map of codecs and/or Standard Schema objects.
+ *
+ * ```ts
+ * // app/products/[id]/layout.tsx
+ * import { defineParams } from '@timber-js/app/params'
+ * import { z } from 'zod/v4'
+ *
+ * export const params = defineParams({
+ *   id: z.coerce.number().int().positive(),
+ * })
+ *
+ * export default function Layout({ children }) { return children }
+ * ```
+ */
+export function defineSegmentParams<C extends Record<string, ParamField>>(
+  codecs: C
+): ParamsDefinition<{ [K in keyof C]: InferParamField<C[K]> }> {
+  type T = { [K in keyof C]: InferParamField<C[K]> };
+
+  const resolvedCodecs: Record<string, Codec<unknown>> = {};
+
+  for (const [key, value] of Object.entries(codecs)) {
+    resolvedCodecs[key] = resolveField(key, value as ParamField);
+  }
+
+  // Validate that serialize doesn't return null
+  validateSerialize(resolvedCodecs);
+
+  // ---- parse ----
+  function parse(raw: Record<string, string | string[]>): T {
+    const result: Record<string, unknown> = {};
+
+    for (const [key, codec] of Object.entries(resolvedCodecs)) {
+      const rawValue = raw[key];
+      // Route params are always present (the route matched)
+      result[key] = codec.parse(rawValue);
+    }
+
+    return result as T;
+  }
+
+  // ---- serialize ----
+  function serialize(values: T): Record<string, string> {
+    const result: Record<string, string> = {};
+
+    for (const [key, codec] of Object.entries(resolvedCodecs)) {
+      const serialized = codec.serialize(values[key as keyof T] as unknown);
+      if (serialized === null) {
+        throw new Error(
+          `[timber] params.serialize: field '${key}' serialized to null. ` +
+            `Route params must produce a valid path segment.`
+        );
+      }
+      result[key] = serialized;
+    }
+
+    return result;
+  }
+
+  // ---- load ----
+  // ALS-backed: reads segment params from the current request context.
+  // Server-only — throws on client.
+  //
+  // The pipeline already coerces params via coerceSegmentParams() which
+  // calls parse() and stores typed values in ALS via setSegmentParams().
+  // We return those directly instead of re-parsing, because codecs may
+  // not be idempotent (e.g., a codec that only accepts raw strings would
+  // throw if given an already-parsed value). See TIM-574.
+  async function load(): Promise<T> {
+    if (typeof window !== 'undefined') {
+      throw new Error(
+        '[timber] segmentParams.load() is server-only. ' + 'Use useSegmentParams() on the client.'
+      );
+    }
+    const params = await getRawSegmentParams();
+    // params are already coerced by the pipeline — return as-is.
+    return params as unknown as T;
+  }
+
+  const definition: ParamsDefinition<T> = {
+    parse,
+    serialize,
+    load,
+    codecs: resolvedCodecs as { [K in keyof T]: Codec<T[K]> },
+  };
+
+  return definition;
+}

package/src/params/index.ts

@@ -0,0 +1,28 @@
+// @timber-js/app/params — Typed route param coercion and search param definitions
+//
+// This is the primary import path for both segmentParams and searchParams.
+// params.ts convention files import from here.
+//
+// See design/07-routing.md §"params.ts Convention File"
+
+// --- Segment params (route path param coercion) ---
+export type { ParamsDefinition, InferParamField, ParamField } from './define.js';
+export { defineSegmentParams } from './define.js';
+
+// --- Search params (re-exported from search-params for convenience) ---
+// This lets params.ts import both from a single path:
+//   import { defineSegmentParams, defineSearchParams } from '@timber-js/app/params'
+export { defineSearchParams } from '../search-params/define.js';
+
+// --- Codec utilities (re-exported for convenience) ---
+export { fromSchema, fromArraySchema } from '../search-params/codecs.js';
+export { withDefault, withUrlKey } from '../search-params/wrappers.js';
+export type { Codec } from '../codec.js';
+export type {
+  SearchParamCodec,
+  SearchParamsDefinition,
+  SetParams,
+  SetParamsOptions,
+  QueryStatesOptions,
+  CodecMap,
+} from '../search-params/define.js';

package/src/plugins/adapter-build.ts

@@ -16,8 +16,8 @@
 import type { Plugin } from 'vite';
 import { join } from 'node:path';
 import { readFile, writeFile } from 'node:fs/promises';
-import type { PluginContext } from '#/index.js';
-import type { TimberPlatformAdapter, TimberConfig } from '#/adapters/types.js';
+import type { PluginContext } from '../index.js';
+import type { TimberPlatformAdapter, TimberConfig } from '../adapters/types.js';
 
 export function timberAdapterBuild(ctx: PluginContext): Plugin {
   return {
@@ -50,6 +50,12 @@ export function timberAdapterBuild(ctx: PluginContext): Plugin {
             : ctx.buildManifest;
           const json = JSON.stringify(manifest);
           manifestInit = `globalThis.__TIMBER_BUILD_MANIFEST__ = ${json};\n`;
+
+          // Embed the deployment ID for version skew detection (TIM-446).
+          // The server reads this at startup via setDeploymentId().
+          if (ctx.deploymentId) {
+            manifestInit += `globalThis.__TIMBER_DEPLOYMENT_ID__ = ${JSON.stringify(ctx.deploymentId)};\n`;
+          }
         }
 
         // Strip JS from the RSC plugin's assets manifest when client JS

package/src/plugins/build-manifest.ts

@@ -16,9 +16,10 @@
  * Design docs: 18-build-system.md §"Build Manifest", 02-rendering-pipeline.md §"Early Hints"
  */
 
+import { randomUUID } from 'node:crypto';
 import type { Plugin, ResolvedConfig } from 'vite';
-import type { PluginContext } from '#/index.js';
-import type { BuildManifest } from '#/server/build-manifest.js';
+import type { PluginContext } from '../index.js';
+import type { BuildManifest } from '../server/build-manifest.js';
 
 // Rollup types used by generateBundle hook — imported from vite which re-exports them.
 // We define minimal interfaces here to avoid a direct 'rollup' dependency.
@@ -242,6 +243,16 @@ export function timberBuildManifest(ctx: PluginContext): Plugin {
     configResolved(config: ResolvedConfig) {
       resolvedBase = config.base;
       isDev = config.command === 'serve';
+
+      // Generate a per-build deployment ID early so virtual:timber-config
+      // can serialize it during the load hook (which runs before generateBundle).
+      // A random UUID is used instead of a content hash — determinism provides
+      // no real benefit here since you almost never redeploy identical code,
+      // and a random ID avoids the timing problem where the content hash was
+      // only available after generateBundle (TIM-452).
+      if (!isDev && !ctx.deploymentId) {
+        ctx.deploymentId = randomUUID().replace(/-/g, '').slice(0, 16);
+      }
     },
 
     resolveId(id: string) {

package/src/plugins/build-report.ts

@@ -15,9 +15,9 @@
 
 import { gzipSync } from 'node:zlib';
 import type { Plugin, Logger } from 'vite';
-import type { PluginContext } from '#/index.js';
-import type { SegmentNode, RouteTree } from '#/routing/types.js';
-import { formatSize } from '#/utils/format.js';
+import type { PluginContext } from '../index.js';
+import type { SegmentNode, RouteTree } from '../routing/types.js';
+import { formatSize } from '../utils/format.js';
 
 // ─── Public types ─────────────────────────────────────────────────────────
 

package/src/plugins/cache-transform.ts

@@ -1,5 +1,5 @@
 import type { Plugin } from 'vite';
-import { findFunctionsWithDirective, containsDirective } from '#/utils/directive-parser.js';
+import { findFunctionsWithDirective, containsDirective } from '../utils/directive-parser.js';
 
 /**
  * Parse a cacheLife duration string to seconds.

package/src/plugins/client-chunks.ts

@@ -0,0 +1,65 @@
+/**
+ * Client chunk grouping strategy for @vitejs/plugin-rsc.
+ *
+ * Groups client reference modules by layout boundary to balance route-scoped
+ * code splitting with HTTP request count. A constant group name would collapse
+ * all routes into one chunk (every page downloads every client component).
+ * Per-serverChunk grouping creates many sub-500B files. Layout-boundary
+ * grouping is the middle ground.
+ *
+ * See design/27-chunking-strategy.md, TIM-440, TIM-499.
+ */
+
+/**
+ * Derive a chunk group name for a client reference module.
+ *
+ * Groups by the first non-group route segment under appDir so that all
+ * client components belonging to the same layout boundary land in one
+ * chunk. For example:
+ *   - `facade:app/dashboard/settings/page.tsx` → `"client-dashboard"`
+ *   - `facade:app/(group-a)/group-page-a/page.tsx` → `"client-group-page-a"`
+ *   - `facade:app/layout.tsx` (root layout) → `"client-shared"`
+ *   - `shared:...` (shared across chunks) → `"client-shared"`
+ *
+ * This balances route-scoped code splitting with HTTP request count:
+ * fewer chunks than per-serverChunk, but still avoids downloading every
+ * client component on every page.
+ */
+export function clientChunkGroup(
+  meta: { id: string; normalizedId: string; serverChunk: string },
+  appDir: string
+): string {
+  const { normalizedId, serverChunk } = meta;
+
+  // Shared chunks (not associated with a single route entry) get one group.
+  if (serverChunk.startsWith('shared:')) return 'client-shared';
+
+  // Derive the layout boundary from the file's location relative to the
+  // app directory. normalizedId is root-relative (e.g. "app/dashboard/shell.tsx"
+  // or "src/app/dashboard/shell.tsx"). We find the "app/" prefix and walk
+  // segments after it to find the first non-group directory.
+  const relPath = normalizedId.replace(/\\/g, '/');
+
+  // Find the app directory boundary in the path. The last segment of appDir
+  // is the app folder name (usually "app").
+  const appDirName = appDir.replace(/\\/g, '/').split('/').pop() || 'app';
+  const appIdx = relPath.indexOf(appDirName + '/');
+  if (appIdx === -1) return 'client-shared';
+
+  const withinApp = relPath.slice(appIdx + appDirName.length + 1);
+  const segments = withinApp.split('/');
+
+  // Find first directory segment that isn't a route group like (group-a)
+  for (const seg of segments) {
+    // Skip the filename itself
+    if (seg.includes('.')) break;
+    // Skip route groups — parenthesized segments like (group-a)
+    if (seg.startsWith('(') && seg.endsWith(')')) continue;
+    // Found a real route segment
+    return `client-${seg}`;
+  }
+
+  // Root-level files (layout.tsx, page.tsx directly in app/) go into the
+  // shared group since the root layout is loaded on every page.
+  return 'client-shared';
+}

package/src/plugins/content.ts

@@ -11,7 +11,7 @@
 import type { Plugin } from 'vite';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import type { PluginContext } from '#/index.js';
+import type { PluginContext } from '../index.js';
 
 const CONFIG_FILE_NAMES = [
   'content-collections.ts',