@timber-js/app 0.2.0-alpha.97 → 0.2.0-alpha.99

package/src/adapters/build-output-helper.ts

@@ -0,0 +1,77 @@
+// Shared build-output helper for adapter buildOutput() methods.
+//
+// Steps 1–5 of every adapter's buildOutput are platform-agnostic:
+//   1. Copy client assets to the public/static directory
+//   2. Write _headers file for static asset cache control
+//   3. Copy RSC + SSR server bundles
+//   4. Write manifest-init module (if present)
+//
+// Only the final steps (entry codegen, platform config) vary per adapter.
+//
+// IMPORTANT: This module must remain a leaf — no imports from ../server/,
+// ../client/, or Vite-dependent code. See adapters/shared.ts header.
+
+import { writeFile, mkdir, cp } from 'node:fs/promises';
+import { join } from 'node:path';
+import { generateHeadersFile } from './shared.js';
+import type { TimberConfig } from './types';
+
+/** Options for the shared build output steps. */
+export interface BuildOutputBaseOptions {
+  /** Resolved timber config. */
+  config: TimberConfig;
+  /** Root build directory (e.g. `.timber/build`). */
+  buildDir: string;
+  /** Adapter-specific output directory (e.g. `.timber/build/nitro`). */
+  outDir: string;
+  /**
+   * Name of the public/static directory within outDir.
+   * Nitro uses 'public', Cloudflare uses 'static'.
+   */
+  publicDirName: string;
+}
+
+/**
+ * Run the platform-agnostic build output steps shared by all adapters:
+ *
+ * 1. Create the output directory
+ * 2. Copy client assets to the public/static directory
+ * 3. Write the `_headers` file for static asset cache control
+ * 4. Copy RSC and SSR server bundles into the output directory
+ * 5. Write the manifest-init module if present
+ *
+ * Returns the resolved public directory path for further adapter-specific use.
+ */
+export async function runSharedBuildSteps(opts: BuildOutputBaseOptions): Promise<string> {
+  const { config, buildDir, outDir, publicDirName } = opts;
+
+  // 1. Create the output directory.
+  await mkdir(outDir, { recursive: true });
+
+  // 2. Copy client assets to public/static directory.
+  // When client JavaScript is disabled, skip .js files — only CSS,
+  // fonts, images, and other static assets are needed.
+  const clientDir = join(buildDir, 'client');
+  const publicDir = join(outDir, publicDirName);
+  await mkdir(publicDir, { recursive: true });
+  await cp(clientDir, publicDir, {
+    recursive: true,
+    filter: config.clientJavascriptDisabled ? (src: string) => !src.endsWith('.js') : undefined,
+  }).catch(() => {
+    // Client dir may not exist when client JavaScript is disabled
+  });
+
+  // 3. Write _headers file for static asset cache control.
+  await writeFile(join(publicDir, '_headers'), generateHeadersFile());
+
+  // 4. Copy RSC + SSR server bundles into the output directory.
+  await cp(join(buildDir, 'rsc'), join(outDir, 'rsc'), { recursive: true });
+  await cp(join(buildDir, 'ssr'), join(outDir, 'ssr'), { recursive: true }).catch(() => {});
+
+  // 5. Write manifest-init module if present.
+  if (config.manifestInit) {
+    await writeFile(join(outDir, '_timber-manifest-init.js'), config.manifestInit);
+  }
+
+  return publicDir;
+}

package/src/adapters/cloudflare.ts

@@ -3,28 +3,12 @@
 // Primary deployment target. Generates a Workers-compatible entry point
 // and wrangler.jsonc configuration. See design/11-platform.md §"Cloudflare Workers".
 
-import { writeFile, mkdir, cp } from 'node:fs/promises';
+import { writeFile } from 'node:fs/promises';
 import { execFile } from 'node:child_process';
 import { join, relative } from 'node:path';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import type { TimberPlatformAdapter, TimberConfig } from './types';
-// Inlined from server/asset-headers.ts — adapters are loaded by Node at
-// Vite startup time, before Vite's module resolver is available, so cross-
-// directory .ts imports don't resolve.
-const IMMUTABLE_CACHE = 'public, max-age=31536000, immutable';
-const STATIC_CACHE = 'public, max-age=3600, must-revalidate';
-
-function generateHeadersFile(): string {
-  return `# Auto-generated by @timber-js/app — static asset cache headers.
-# See design/25-production-deployments.md §"CDN / Edge Cache"
-
-/assets/*
-  Cache-Control: ${IMMUTABLE_CACHE}
-
-/*
-  Cache-Control: ${STATIC_CACHE}
-`;
-}
+import { runSharedBuildSteps } from './build-output-helper.js';
 
 // ─── Bindings passthrough ─────────────────────────────────────────────────
 // ALS stores the env object per-request so server components and middleware
@@ -243,39 +227,15 @@ export function cloudflare(options: CloudflareAdapterOptions = {}): TimberPlatfo
 
     async buildOutput(config: TimberConfig, buildDir: string) {
       const outDir = join(buildDir, 'cloudflare');
-      await mkdir(outDir, { recursive: true });
-
-      // Copy client assets to static output.
-      // When client JavaScript is disabled, skip .js files — only CSS,
-      // fonts, images, and other static assets are needed.
-      const clientDir = join(buildDir, 'client');
-      const staticDir = join(outDir, 'static');
-      await mkdir(staticDir, { recursive: true });
-      await cp(clientDir, staticDir, {
-        recursive: true,
-        filter: config.clientJavascriptDisabled ? (src: string) => !src.endsWith('.js') : undefined,
-      }).catch(() => {
-        // Client dir may not exist when client JavaScript is disabled
-      });
 
-      // Write _headers file for static asset cache control.
-      // Cloudflare Workers Static Assets reads this to set Cache-Control
-      // headers on responses. Hashed assets get immutable; others get 1h.
-      await writeFile(join(staticDir, '_headers'), generateHeadersFile());
-
-      // Copy server bundles (rsc + ssr) into the output directory.
-      // These are already fully bundled by Vite with resolve.noExternal: true.
-      const rscDir = join(buildDir, 'rsc');
-      const ssrDir = join(buildDir, 'ssr');
-      await cp(rscDir, join(outDir, 'rsc'), { recursive: true });
-      await cp(ssrDir, join(outDir, 'ssr'), { recursive: true });
-
-      // Write the build manifest init module (if manifest data was produced).
-      // This must be imported before the RSC handler so the global is set
-      // when virtual:timber-build-manifest evaluates.
-      if (config.manifestInit) {
-        await writeFile(join(outDir, '_timber-manifest-init.js'), config.manifestInit);
-      }
+      // Steps 1–5: shared across all adapters (mkdir, copy client/rsc/ssr,
+      // write _headers, write manifest-init).
+      await runSharedBuildSteps({
+        config,
+        buildDir,
+        outDir,
+        publicDirName: 'static',
+      });
 
       // Compile optional worker handlers (queue, scheduled, etc.)
       // Uses Vite's build API to bundle the TypeScript source into ESM.

package/src/adapters/nitro.ts

@@ -5,28 +5,13 @@
 // compression, graceful shutdown, static file serving, and platform quirks.
 // See design/11-platform.md and design/25-production-deployments.md.
 
-import { writeFile, readFile, mkdir, cp } from 'node:fs/promises';
+import { writeFile, readFile } from 'node:fs/promises';
 import { execFile } from 'node:child_process';
 import { join, relative } from 'node:path';
 import type { TimberPlatformAdapter, TimberConfig } from './types';
 import { generateCompressModule } from './compress-module.js';
-// Inlined from server/asset-headers.ts — adapters are loaded by Node at
-// Vite startup time, before Vite's module resolver is available, so cross-
-// directory .ts imports don't resolve.
-const IMMUTABLE_CACHE = 'public, max-age=31536000, immutable';
-const STATIC_CACHE = 'public, max-age=3600, must-revalidate';
-
-function generateHeadersFile(): string {
-  return `# Auto-generated by @timber-js/app — static asset cache headers.
-# See design/25-production-deployments.md §"CDN / Edge Cache"
-
-/assets/*
-  Cache-Control: ${IMMUTABLE_CACHE}
-
-/*
-  Cache-Control: ${STATIC_CACHE}
-`;
-}
+import { IMMUTABLE_CACHE } from './shared.js';
+import { runSharedBuildSteps } from './build-output-helper.js';
 
 // ─── Presets ─────────────────────────────────────────────────────────────────
 
@@ -202,40 +187,21 @@ export function nitro(options: NitroAdapterOptions = {}): TimberPlatformAdapter
 
     async buildOutput(config: TimberConfig, buildDir: string) {
       const outDir = join(buildDir, 'nitro');
-      await mkdir(outDir, { recursive: true });
-
-      // Copy client assets to public directory.
-      // When client JavaScript is disabled, skip .js files — only CSS,
-      // fonts, images, and other static assets are needed.
-      const clientDir = join(buildDir, 'client');
-      const publicDir = join(outDir, 'public');
-      await mkdir(publicDir, { recursive: true });
-      await cp(clientDir, publicDir, {
-        recursive: true,
-        filter: config.clientJavascriptDisabled ? (src: string) => !src.endsWith('.js') : undefined,
-      }).catch(() => {
-        // Client dir may not exist when client JavaScript is disabled
-      });
 
-      // Write _headers file for platforms that support it (Netlify, etc.).
-      // See design/25-production-deployments.md §"CDN / Edge Cache"
-      await writeFile(join(publicDir, '_headers'), generateHeadersFile());
-
-      // Write the build manifest init module (if manifest data was produced).
-      if (config.manifestInit) {
-        await writeFile(join(outDir, '_timber-manifest-init.js'), config.manifestInit);
-      }
+      // Steps 1–5: shared across all adapters (mkdir, copy client/rsc/ssr,
+      // write _headers, write manifest-init).
+      await runSharedBuildSteps({
+        config,
+        buildDir,
+        outDir,
+        publicDirName: 'public',
+      });
 
       // Write the compression helper module for runtime use.
       // See design/25-production-deployments.md — self-hosted deployments
       // need application-level compression (Cloudflare handles it at the edge).
       await writeFile(join(outDir, '_compress.mjs'), generateCompressModule());
 
-      // Copy rsc/ssr build output into the nitro dir so imports stay local
-      // during the Nitro bundling step (avoids broken relative paths in output).
-      await cp(join(buildDir, 'rsc'), join(outDir, 'rsc'), { recursive: true });
-      await cp(join(buildDir, 'ssr'), join(outDir, 'ssr'), { recursive: true }).catch(() => {});
-
       // Prepend the manifest assignment directly into the RSC entry so
       // globalThis.__TIMBER_BUILD_MANIFEST__ is set before any module reads it.
       // This must be top-level code, not an import, because rollup tree-shakes
@@ -486,11 +452,25 @@ const MIME_TYPES = {
 };
 
 const publicDir = join(__dirname, '${publicDir}');
-const port = parseInt(process.env.PORT || '3000', 10);
+
+// Port resolution (TIM-842):
+//   - Default to 3000
+//   - If PORT env var is set, honor it strictly (fail loudly on conflict)
+//   - Otherwise auto-bump from 3000 until a free port is found
+// Mirrors the dev server behavior so timber dev/preview/production all
+// behave the same way around port selection.
+const envPort = process.env.PORT ? parseInt(process.env.PORT, 10) : null;
+const portIsExplicit = envPort != null && Number.isFinite(envPort) && envPort > 0;
+const startPort = portIsExplicit ? envPort : 3000;
 const host = process.env.HOST || process.env.HOSTNAME || 'localhost';
 
+// Set after listenWithBump() resolves so request handlers can build
+// absolute URLs from the actual bound port (which may differ from
+// startPort after an auto-bump).
+let boundPort = startPort;
+
 const server = createServer(async (req, res) => {
-  const url = new URL(req.url || '/', \`http://\${host}:\${port}\`);
+  const url = new URL(req.url || '/', \`http://\${host}:\${boundPort}\`);
 
   // Try serving static files from the public directory first.
   const filePath = join(publicDir, url.pathname);
@@ -631,13 +611,49 @@ const server = createServer(async (req, res) => {
   }
 });
 
-server.listen(port, host, () => {
+function listenWithBump(port, attempt = 0) {
+  return new Promise((resolveListen, rejectListen) => {
+    const onError = (err) => {
+      server.removeListener('listening', onListening);
+      if (err && err.code === 'EADDRINUSE' && !portIsExplicit && attempt < 100) {
+        if (attempt === 0) {
+          console.log(\`  [timber] Port \${port} in use, trying \${port + 1}...\`);
+        }
+        listenWithBump(port + 1, attempt + 1).then(resolveListen, rejectListen);
+        return;
+      }
+      rejectListen(err);
+    };
+    const onListening = () => {
+      server.removeListener('error', onError);
+      resolveListen(port);
+    };
+    server.once('error', onError);
+    server.once('listening', onListening);
+    server.listen(port, host);
+  });
+}
+
+try {
+  boundPort = await listenWithBump(startPort);
+  if (boundPort !== startPort) {
+    console.log();
+    console.log(\`  [timber] Port \${startPort} in use, using \${boundPort}\`);
+  }
   console.log();
   console.log('  ⚡ timber preview server running at:');
   console.log();
-  console.log(\`    ➜  http://\${host}:\${port}\`);
+  console.log(\`    ➜  http://\${host}:\${boundPort}\`);
   console.log();
-});
+} catch (err) {
+  if (err && err.code === 'EADDRINUSE') {
+    console.error(\`[timber] Port \${startPort} is already in use. \` +
+      'Set PORT to a free port, or unset PORT to auto-pick.');
+  } else {
+    console.error('[timber] Failed to start preview server:', err);
+  }
+  process.exit(1);
+}
 `;
 }
 

package/src/adapters/shared.ts

@@ -0,0 +1,40 @@
+// Shared adapter utilities — leaf module with zero deps on server/, client/,
+// or any Vite-dependent code.
+//
+// Adapters are loaded by Node at Vite startup time, before Vite's module
+// resolver is available. This module uses only Node built-ins and can be
+// imported by both adapters via a relative path.
+//
+// IMPORTANT: Do NOT add imports from ../server/, ../client/, ../plugins/,
+// or any module that transitively depends on Vite. A test in
+// tests/adapters/shared-no-forbidden-imports.test.ts enforces this.
+
+// ─── Static asset cache headers ──────────────────────────────────────────
+
+/** Cache-Control value for hashed (immutable) assets. */
+export const IMMUTABLE_CACHE = 'public, max-age=31536000, immutable';
+
+/** Cache-Control value for unhashed static assets. */
+export const STATIC_CACHE = 'public, max-age=3600, must-revalidate';
+
+/**
+ * Generate a `_headers` file for static asset cache control.
+ *
+ * The `_headers` file is a platform convention supported by Cloudflare Workers
+ * Static Assets, Cloudflare Pages, and Netlify. It maps URL patterns to
+ * HTTP response headers.
+ *
+ * Vite places all hashed chunks under `/assets/` — these get immutable caching.
+ * Everything else (favicon.ico, robots.txt, etc.) gets a shorter cache.
+ */
+export function generateHeadersFile(): string {
+  return `# Auto-generated by @timber-js/app — static asset cache headers.
+# See design/25-production-deployments.md §"CDN / Edge Cache"
+
+/assets/*
+  Cache-Control: ${IMMUTABLE_CACHE}
+
+/*
+  Cache-Control: ${STATIC_CACHE}
+`;
+}

package/src/cache/timber-cache.ts

@@ -2,6 +2,7 @@ import type { CacheHandler, CacheOptions } from './index';
 import { stableStringify } from './stable-stringify';
 import { createSingleflight } from './singleflight';
 import { addSpanEventSync } from '../server/tracing.js';
+import { logSwrRefetchFailed } from '../server/logger.js';
 import { fnv1aHash } from './fast-hash.js';
 
 const defaultSingleflight = createSingleflight();
@@ -91,9 +92,9 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
           const fresh = await fn(...args);
           const tags = resolveTags(opts, args);
           await handler.set(key, fresh, { ttl: opts.ttl, tags });
-        } catch {
+        } catch (err) {
           // Failed refetch — stale entry continues to be served.
-          // Error is swallowed per design doc: "Error is logged."
+          logSwrRefetchFailed({ cacheKey: key, error: err });
         }
       }).catch(() => {
         // Singleflight promise rejection handled — stale continues.

package/src/client/form.tsx

@@ -27,13 +27,15 @@ export type UseActionStateFn<TData> = (
 ) => Promise<ActionResult<TData>>;
 
 /**
- * Return type of useActionState — matches React 19's useActionState return.
- * [result, formAction, isPending]
+ * Return type of useActionState.
+ * [result, formAction, isPending, errors]
+ * The 4th element is auto-derived from result via useFormErrors logic.
  */
 export type UseActionStateReturn<TData> = [
   result: ActionResult<TData> | null,
   formAction: (formData: FormData) => void,
   isPending: boolean,
+  errors: FormErrorsResult,
 ];
 
 // ─── useActionState ──────────────────────────────────────────────────────
@@ -73,7 +75,13 @@ export function useActionState<TData>(
 ): UseActionStateReturn<TData> {
   // FormFlashData is structurally compatible with ActionResult at runtime —
   // the cast satisfies React's generic inference which would otherwise widen TData.
-  return reactUseActionState(action, initialState as ActionResult<TData> | null, permalink);
+  const [result, formAction, isPending] = reactUseActionState(
+    action,
+    initialState as ActionResult<TData> | null,
+    permalink
+  );
+  const errors = deriveFormErrors(result);
+  return [result, formAction, isPending, errors];
 }
 
 // ─── useFormAction ───────────────────────────────────────────────────────
@@ -114,9 +122,9 @@ export function useFormAction<TData = unknown, TInput = unknown>(
   return [execute, isPending];
 }
 
-// ─── useFormErrors ──────────────────────────────────────────────────────
+// ─── Form error extraction ────────────────────────────────────────────────
 
-/** Return type of useFormErrors(). */
+/** Return type of the errors element in useActionState. */
 export interface FormErrorsResult {
   /** Per-field validation errors keyed by field name. */
   fieldErrors: Record<string, string[]>;
@@ -131,27 +139,11 @@ export interface FormErrorsResult {
 }
 
 /**
- * Extract per-field and form-level errors from an ActionResult.
- *
- * Pure function (no internal hooks) — follows React naming convention
- * since it's used in render. Accepts the result from `useActionState`
- * or flash data from `getFormFlash()`.
- *
- * @example
- * ```tsx
- * const [result, action, isPending] = useActionState(createTodo, null)
- * const errors = useFormErrors(result)
- *
- * return (
- *   <form action={action}>
- *     <input name="title" />
- *     {errors.getFieldError('title') && <p>{errors.getFieldError('title')}</p>}
- *     {errors.formErrors.map(e => <p key={e}>{e}</p>)}
- *   </form>
- * )
- * ```
+ * Derive FormErrorsResult from an action result.
+ * Used internally by useActionState 4th tuple element.
+ * @internal — exported for test access only.
  */
-export function useFormErrors<TData>(
+export function deriveFormErrors<TData>(
   result:
     | ActionResult<TData>
     | {

package/src/client/index.ts

@@ -66,26 +66,33 @@ export type { LinkStatus } from './use-link-status';
 export { useRouter } from './use-router';
 export type { AppRouterInstance } from './use-router';
 export { usePathname } from './use-pathname';
-export { useSearchParams } from './use-search-params';
+// useSearchParams removed from public exports — lives in next/navigation shim only.
 export { useSelectedLayoutSegment, useSelectedLayoutSegments } from './use-selected-layout-segment';
 
 // Forms
-export { useActionState, useFormAction, useFormErrors } from './form';
+export { useActionState, useFormAction } from './form';
 export type { UseActionStateFn, UseActionStateReturn, FormErrorsResult } from './form';
 
-// Params
-export { useSegmentParams } from './use-params';
+// Params — useSegmentParams lives on defineSegmentParams().useSegmentParams()
+// and in the next/navigation shim for library compat.
 
-// Query states (URL-synced search params)
-export { useQueryStates } from './use-query-states';
+// Query states — useQueryStates lives on defineSearchParams().useQueryStates()
+// and is available via direct import for advanced cases.
 
-// Cookies
-export { useCookie } from './use-cookie';
+// Cookies — useCookie lives on defineCookie().useCookie().
+// Types still exported for advanced use.
 export type { ClientCookieOptions, CookieSetter } from './use-cookie';
 
 // Register the client cookie module with defineCookie's lazy reference.
 // This runs at module load time in the client/SSR environment, wiring up
 // the useCookie hook without a top-level import in define-cookie.ts.
 import * as _useCookieMod from './use-cookie.js';
-import { _registerUseCookieModule } from '../cookies/define-cookie.js';
+import { _registerUseCookieModule, _registerFromSchema } from '../cookies/define-cookie.js';
+import { fromSchema } from '../schema-bridge.js';
 _registerUseCookieModule(_useCookieMod);
+_registerFromSchema(fromSchema);
+
+// Register the client useSegmentParams hook with defineSegmentParams.
+import { useSegmentParams as _useSegmentParams } from './use-segment-params.js';
+import { _registerUseSegmentParams } from '../segment-params/define.js';
+_registerUseSegmentParams(_useSegmentParams);

package/src/client/internal.ts

@@ -38,8 +38,9 @@ export type { SegmentNode, StateTree } from './segment-cache.js';
 export { HistoryStack } from './history.js';
 export type { HistoryEntry } from './history.js';
 
-// ── Params (internal setter) ─────────────────────────────────────────────
-export { setCurrentParams } from './use-params.js';
+// ── Params (internal setter + raw hooks) ─────────────────────────────────
+export { setCurrentParams, useSegmentParams } from './use-segment-params.js';
+export { useSearchParams } from './use-search-params.js';
 
 // ── Navigation context ───────────────────────────────────────────────────
 export {

package/src/client/router.ts

@@ -5,7 +5,7 @@ import { SegmentCache, PrefetchCache, buildSegmentTree } from './segment-cache';
 import type { SegmentInfo } from './segment-cache';
 import { HistoryStack } from './history';
 import type { HeadElement } from './head';
-import { setCurrentParams } from './use-params.js';
+import { setCurrentParams } from './use-segment-params.js';
 import {
   setNavigationState,
   getNavigationState,

package/src/client/rsc-fetch.ts

@@ -124,6 +124,17 @@ export function buildRscHeaders(
 
 // ─── Response Header Extraction ──────────────────────────────────
 
+/** Dev-only warning for malformed framework headers. Tree-shaken in production. */
+function warnMalformedHeader(headerName: string, raw: string): void {
+  if (process.env.NODE_ENV !== 'production') {
+    const preview = raw.length > 200 ? raw.slice(0, 200) + '…' : raw;
+    console.warn(
+      `[timber] Malformed ${headerName} header \u2014 JSON.parse failed. ` +
+        `This indicates a framework bug or header corruption. Raw (first 200 chars): ${preview}`
+    );
+  }
+}
+
 /**
  * Extract head elements from the X-Timber-Head response header.
  * Returns null if the header is missing or malformed.
@@ -134,6 +145,7 @@ export function extractHeadElements(response: Response): HeadElement[] | null {
   try {
     return JSON.parse(decodeURIComponent(header));
   } catch {
+    warnMalformedHeader('X-Timber-Head', header);
     return null;
   }
 }
@@ -152,6 +164,7 @@ export function extractSegmentInfo(response: Response): SegmentInfo[] | null {
   try {
     return JSON.parse(header);
   } catch {
+    warnMalformedHeader('X-Timber-Segments', header);
     return null;
   }
 }
@@ -171,6 +184,7 @@ export function extractSkippedSegments(response: Response): string[] | null {
     const parsed = JSON.parse(header);
     return Array.isArray(parsed) ? parsed : null;
   } catch {
+    warnMalformedHeader('X-Timber-Skipped-Segments', header);
     return null;
   }
 }
@@ -187,6 +201,7 @@ export function extractParams(response: Response): Record<string, string | strin
   try {
     return JSON.parse(header);
   } catch {
+    warnMalformedHeader('X-Timber-Params', header);
     return null;
   }
 }

package/src/client/state.ts

@@ -3,7 +3,7 @@
  *
  * ALL mutable module-level state that must have singleton semantics across
  * the client bundle lives here. Individual modules (router-ref.ts, ssr-data.ts,
- * use-params.ts, use-search-params.ts, unload-guard.ts) import from this file
+ * use-segment-params.ts, use-search-params.ts, unload-guard.ts) import from this file
  * and re-export thin wrapper functions.
  *
  * Why: In Vite dev, a module is instantiated separately if reached via different
@@ -50,7 +50,7 @@ export function _setCurrentSsrData(data: SsrData | undefined): void {
   currentSsrData = data;
 }
 
-// ─── Route Params (from use-params.ts) ──────────────────────────────────────
+// ─── Route Params (from use-segment-params.ts) ──────────────────────────────────────
 
 /** Current route params snapshot — replaced (not mutated) on each navigation. */
 export let currentParams: Record<string, string | string[]> = {};

package/src/client/use-cookie.ts

@@ -10,6 +10,7 @@
 
 import { useSyncExternalStore } from 'react';
 import { getSsrData } from './ssr-data.js';
+import { assertValidCookieName } from '../cookies/validation.js';
 
 // ─── Types ────────────────────────────────────────────────────────────────
 
@@ -68,6 +69,17 @@ function notify(name: string): void {
   }
 }
 
+/**
+ * Notify useCookie subscribers that a cookie value changed.
+ * Called by defineCookie's imperative client .set()/.delete() methods
+ * so mounted useCookie() consumers re-render.
+ *
+ * @internal — framework use only
+ */
+export function notifyCookieChange(name: string): void {
+  notify(name);
+}
+
 // ─── Hook ─────────────────────────────────────────────────────────────────
 
 /**
@@ -103,8 +115,25 @@ export function useCookie(
 
   const value = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
 
+  // Validate the name once per hook instance — names are typically
+  // stable string literals, so this catches the bug at first render
+  // rather than on every write. Throws via `assertValidCookieName` with
+  // a precise error if the name violates RFC 7230 token rules.
+  assertValidCookieName(name);
+
   const setCookie: CookieSetter = (newValue: string, options?: ClientCookieOptions) => {
+    if (typeof newValue !== 'string') {
+      throw new Error(
+        `[timber] useCookie(${JSON.stringify(name)}): value must be a string, got ${typeof newValue}.\n` +
+          `  To store a JSON-serializable value, use defineCookie + jsonCookieCodec from\n` +
+          `  '@timber-js/app/cookies' and call its useCookie() hook instead.`
+      );
+    }
     const merged = { ...defaultOptions, ...options };
+    // Auto-encode mirrors the server's `cookies().set()` contract:
+    // values are URL-encoded on write, URL-decoded on read, so the
+    // logical bytes round-trip losslessly. See design/29-cookies.md
+    // §"Encoding Contract".
     document.cookie = `${name}=${encodeURIComponent(newValue)}${serializeOptions(merged)}`;
     notify(name);
   };

package/src/codec.ts

@@ -39,11 +39,7 @@ export type JsonSerializable =
 
 // ─── Standard Schema bridge ──────────────────────────────────────────────
 
-export {
-  fromSchema,
-  fromArraySchema,
-  validateSync,
-  isStandardSchema,
-  isCodec,
-} from './schema-bridge.js';
+// fromSchema is internal — defineSearchParams and defineCookie auto-detect
+// Standard Schema objects. Users should pass raw schemas directly.
+export { fromArraySchema, validateSync, isStandardSchema, isCodec } from './schema-bridge.js';
 export type { StandardSchemaV1, StandardSchemaResult } from './schema-bridge.js';