@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.210

package/dist/shims/navigation-client.d.ts

@@ -1,12 +1,19 @@
 /**
  * Shim: next/navigation (client environment only)
  *
- * Re-exports only the client-side hooks from timber's client API.
- * Server-only functions (redirect, notFound, etc.) are excluded to prevent
- * server/primitives.ts from being pulled into the browser bundle.
+ * Re-exports the client-side hooks from timber's client API, and implements
+ * client-render `redirect()` without pulling server/primitives.ts into the
+ * browser bundle.
+ *
+ * Next.js supports calling redirect() during client component render.
+ * timber matches that by throwing a plain Error carrying the same JSON
+ * digest the server pipeline attaches to RedirectSignal. TimberErrorBoundary
+ * recognizes the digest and converts it to an SPA navigation (replace
+ * semantics), and browser-dev's isFrameworkSignalError() keeps it out of
+ * the dev overlay.
  *
  * The full shim (navigation.ts) is still used in the RSC and SSR environments
- * where both client hooks and server functions are needed.
+ * where the real server primitives produce proper HTTP responses.
  *
  * Imports use @timber-js/app/client (not #/ subpath imports) so they resolve
  * to the same module instances as user code in Vite dev — preventing module
@@ -15,12 +22,18 @@
  *
  * See design/14-ecosystem.md §"next/navigation" for the full shim audit.
  */
-export { useParams, usePathname, useSearchParams, useRouter, useSelectedLayoutSegment, useSelectedLayoutSegments, } from '@timber-js/app/client';
-export declare const RedirectType: {
-    readonly push: "push";
-    readonly replace: "replace";
-};
-export declare function redirect(): never;
-export declare function permanentRedirect(): never;
-export declare function notFound(): never;
+import type { RedirectTypeValue } from '../shared/redirect-type.ts';
+export { useSegmentParams, useSegmentParams as useParams } from '../client/use-segment-params.ts';
+export { useSearchParams } from '../client/use-search-params.ts';
+export { usePathname, useRouter, useSelectedLayoutSegment, useSelectedLayoutSegments, } from '@timber-js/app/client';
+export { RedirectType } from '../shared/redirect-type.ts';
+/**
+ * Client-render redirect. Throws a redirect-digest error that the nearest
+ * TimberErrorBoundary converts into an SPA navigation (replace semantics).
+ *
+ * The optional RedirectType argument is accepted for Next.js API
+ * compatibility but ignored — timber always uses replace semantics,
+ * matching the server-side redirect().
+ */
+export declare function redirect(path: string, _type?: RedirectTypeValue): never;
 //# sourceMappingURL=navigation-client.d.ts.map

package/dist/shims/navigation-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"navigation-client.d.ts","sourceRoot":"","sources":["../../src/shims/navigation-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EACL,SAAS,EACT,WAAW,EACX,eAAe,EACf,SAAS,EACT,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC;AAI/B,eAAO,MAAM,YAAY;;;CAGf,CAAC;AAKX,wBAAgB,QAAQ,IAAI,KAAK,CAKhC;AAED,wBAAgB,iBAAiB,IAAI,KAAK,CAKzC;AAED,wBAAgB,QAAQ,IAAI,KAAK,CAIhC"}
+{"version":3,"file":"navigation-client.d.ts","sourceRoot":"","sources":["../../src/shims/navigation-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAIpE,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,IAAI,SAAS,EAAE,MAAM,iCAAiC,CAAC;AAClG,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EACL,WAAW,EACX,SAAS,EACT,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAS1D;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,iBAAiB,GAAG,KAAK,CAGvE"}

package/dist/shims/navigation-rsc.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shim: next/navigation → RSC environment only
+ *
+ * RSC's stripped-down React provides neither `useContext` nor `createContext`,
+ * so the real hook modules cannot be evaluated there. This shim exports
+ * throwing stubs for every client hook, with the same error messages the
+ * guards previously produced inline, and re-exports the server functions
+ * from @timber-js/app/server unchanged.
+ *
+ * The shims plugin resolves `next/navigation` to this file in the RSC
+ * environment, `navigation.ts` in SSR, and `navigation-client.ts` in the
+ * browser. This split eliminates the `typeof React.useContext !== 'function'`
+ * guards that React Compiler flagged as conditional hook calls (TIM-1420).
+ */
+export declare function usePathname(): string;
+export declare function useSearchParams(): URLSearchParams;
+export declare function useSegmentParams(): Record<string, unknown>;
+export { useSegmentParams as useParams };
+export { useRouter, useSelectedLayoutSegment, useSelectedLayoutSegments, } from '@timber-js/app/client';
+export { redirect, redirectExternal, RedirectType } from '@timber-js/app/server';
+//# sourceMappingURL=navigation-rsc.d.ts.map

package/dist/shims/navigation-rsc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation-rsc.d.ts","sourceRoot":"","sources":["../../src/shims/navigation-rsc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AASH,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED,wBAAgB,eAAe,IAAI,eAAe,CAEjD;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAM1D;AAED,OAAO,EAAE,gBAAgB,IAAI,SAAS,EAAE,CAAC;AAEzC,OAAO,EACL,SAAS,EACT,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/shims/navigation.d.ts

@@ -1,10 +1,15 @@
 /**
  * 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.
  */
-export { useParams, usePathname, useSearchParams, useRouter, useSelectedLayoutSegment, useSelectedLayoutSegments, } from '@timber-js/app/client';
-export { redirect, permanentRedirect, notFound, RedirectType } from '@timber-js/app/server';
+export { useSegmentParams, useSegmentParams as useParams } from '../client/use-segment-params.ts';
+export { useSearchParams } from '../client/use-search-params.ts';
+export { usePathname, useRouter, useSelectedLayoutSegment, useSelectedLayoutSegments, } from '@timber-js/app/client';
+export { redirect, redirectExternal, RedirectType } from '@timber-js/app/server';
 //# sourceMappingURL=navigation.d.ts.map

package/dist/shims/navigation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../src/shims/navigation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EACL,SAAS,EACT,WAAW,EACX,eAAe,EACf,SAAS,EACT,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../src/shims/navigation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,IAAI,SAAS,EAAE,MAAM,iCAAiC,CAAC;AAClG,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EACL,WAAW,EACX,SAAS,EACT,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/utils/state-machine.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Tiny typed state machine utility.
+ *
+ * Enforces discriminated-union states, typed transitions with runtime
+ * guards, subscribe for external store integration, and assertPhase
+ * for function entry guards.
+ *
+ * Designed for 3–5 state consumers (stream transforms, client navigation,
+ * build phase sequencing). No async, no hierarchy, no history.
+ *
+ * Performance: send() is one object lookup + one function call.
+ * Equivalent cost to a boolean check after V8 inlining.
+ */
+/** A state machine instance with typed state and events. */
+export interface Machine<TState extends {
+    phase: string;
+}, TEvent extends {
+    type: string;
+}> {
+    /** Current state (discriminated union — narrowed by phase). */
+    readonly state: TState;
+    /** Transition with runtime guard. Throws on invalid source+event pair. */
+    send(event: TEvent): void;
+    /** Subscribe to state changes. Returns unsubscribe function. */
+    subscribe(listener: (state: TState) => void): () => void;
+    /** Throw if not in the expected phase. Entry guard for functions. */
+    assertPhase<P extends TState['phase']>(phase: P): void;
+}
+/**
+ * Transition map: `transitions[phase][eventType]` returns the next state.
+ *
+ * Each handler receives the current state (narrowed by phase context)
+ * and the event, returning the new state.
+ */
+export type TransitionMap<TState extends {
+    phase: string;
+}, TEvent extends {
+    type: string;
+}> = {
+    [P in TState['phase']]?: {
+        [E in TEvent['type']]?: (state: Extract<TState, {
+            phase: P;
+        }>, event: Extract<TEvent, {
+            type: E;
+        }>) => TState;
+    };
+};
+export interface MachineConfig<TState extends {
+    phase: string;
+}, TEvent extends {
+    type: string;
+}> {
+    initial: TState;
+    transitions: TransitionMap<TState, TEvent>;
+    /** Fires after every valid transition. Use for side effects. */
+    onTransition?: (prev: TState, next: TState, event: TEvent) => void;
+}
+/**
+ * Create a state machine from a config.
+ *
+ * @example
+ * ```ts
+ * type State = { phase: 'idle' } | { phase: 'running'; pid: number };
+ * type Event = { type: 'START'; pid: number } | { type: 'STOP' };
+ *
+ * const m = createMachine<State, Event>({
+ *   initial: { phase: 'idle' },
+ *   transitions: {
+ *     idle: { START: (_s, e) => ({ phase: 'running', pid: e.pid }) },
+ *     running: { STOP: () => ({ phase: 'idle' }) },
+ *   },
+ * });
+ * ```
+ */
+export declare function createMachine<TState extends {
+    phase: string;
+}, TEvent extends {
+    type: string;
+}>(config: MachineConfig<TState, TEvent>): Machine<TState, TEvent>;
+//# sourceMappingURL=state-machine.d.ts.map

package/dist/utils/state-machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-machine.d.ts","sourceRoot":"","sources":["../../src/utils/state-machine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,4DAA4D;AAC5D,MAAM,WAAW,OAAO,CAAC,MAAM,SAAS;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE;IACxF,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,0EAA0E;IAC1E,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAE1B,gEAAgE;IAChE,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAEzD,qEAAqE;IACrE,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;CACxD;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,CAAC,MAAM,SAAS;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,IAAI;KAC5F,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE;SACtB,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CACtB,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE;YAAE,KAAK,EAAE,CAAC,CAAA;SAAE,CAAC,EACpC,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE;YAAE,IAAI,EAAE,CAAC,CAAA;SAAE,CAAC,KAChC,MAAM;KACZ;CACF,CAAC;AAEF,MAAM,WAAW,aAAa,CAAC,MAAM,SAAS;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE;IAC9F,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C,gEAAgE;IAChE,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACpE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,MAAM,SAAS;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAC7F,MAAM,EAAE,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,GACpC,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAwCzB"}

package/dist/utils/write-file-atomic.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Replace a file's contents in one step: write a uniquely named temp sibling,
+ * then `rename()` it over the target.
+ *
+ * `writeFile()` opens its target with `O_TRUNC`, so for the length of the write
+ * a concurrent reader sees an empty or half-written file under the real name.
+ * `rename()` within one directory swaps the name atomically, so a reader sees
+ * either the old file or the new one — never a torn one — and a crashed
+ * writer leaves no partial artifact under the final name.
+ *
+ * The temp name is unique per call, not a fixed `${path}.tmp`: two writers of
+ * the same path (a dev server and a `vite build` rewriting the same route
+ * types, parallel CLI invocations sharing a cache) would otherwise write into
+ * one temp file and rename each other's half-written bytes into place.
+ */
+export declare function writeFileAtomic(path: string, data: Uint8Array | string): Promise<void>;
+//# sourceMappingURL=write-file-atomic.d.ts.map

package/dist/utils/write-file-atomic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-file-atomic.d.ts","sourceRoot":"","sources":["../../src/utils/write-file-atomic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAY5F"}

package/docs/api/30-api-server.mdx

@@ -0,0 +1,239 @@
+---
+title: 'API: @timber-js/app/server'
+description: 'Server-side exports — deny, redirect, getHeaders, getCookieJar, createActionClient, and context types.'
+slug: 'api-server'
+---
+
+# @timber-js/app/server
+
+Server-side utilities and types. Import from `@timber-js/app/server`.
+
+## Navigation & Status
+
+### `deny(status?, options?)`
+
+Universal denial/error primitive. Produces an HTTP error status and renders the matching status file. Accepts any 4xx or 5xx status code. Default status is 403.
+
+```ts
+import { deny } from '@timber-js/app/server';
+
+deny(); // 403 (default)
+deny(404); // 404 Not Found
+deny(503, { message: 'Maintenance' }); // server-only log message
+deny(404, { dangerouslyPassData: { resourceId: params.id } }); // data forwarded as `data` prop
+```
+
+### `redirect(url, type?)`
+
+Redirect to a URL. Sends HTTP 307 (temporary) by default.
+
+```ts
+import { redirect } from '@timber-js/app/server';
+
+redirect('/login'); // 302 Temporary Redirect
+redirect('/new-page', { permanent: true }); // 308 Permanent Redirect
+redirect('/new-page', { status: 301 }); // 301 (explicit status)
+redirect('/new-page', 301); // 301 (shorthand)
+```
+
+The `permanent` option defaults to status **308** (preserves HTTP method). If you need 301 specifically, pass `status: 301`. When both `permanent` and `status` are provided, `status` wins.
+
+### `redirectExternal(url, allowList, status?)`
+
+Redirect to an external URL. The target origin must be in the provided allow-list. Only `http:` and `https:` schemes are permitted — this prevents open redirect vulnerabilities and blocks `javascript:` scheme injection.
+
+```ts
+import { redirectExternal } from '@timber-js/app/server';
+
+// Redirect to an allowed external domain
+redirectExternal('https://auth.example.com/login', ['https://auth.example.com']);
+
+// With a custom status code
+redirectExternal('https://docs.example.com', ['https://docs.example.com'], 301);
+```
+
+| Parameter   | Type       | Default | Description                                      |
+| ----------- | ---------- | ------- | ------------------------------------------------ |
+| `url`       | `string`   | —       | Absolute URL to redirect to                      |
+| `allowList` | `string[]` | —       | Allowed origins (e.g. `['https://example.com']`) |
+| `status`    | `number`   | `302`   | HTTP redirect status code (3xx)                  |
+
+Throws if the origin is not in the allow-list, the scheme isn't `http:` or `https:`, or the URL is invalid.
+
+## Request Context
+
+### `getHeaders()`
+
+Returns the incoming request headers. ALS-backed — works in server components, middleware, access checks.
+
+```ts
+import { getHeaders } from '@timber-js/app/server';
+
+const h = getHeaders();
+const auth = h.get('authorization');
+```
+
+Returns `ReadonlyHeaders` — a read-only `Headers` interface (sync).
+
+### `getCookieJar()`
+
+Returns the request cookies with mutation methods.
+
+```ts
+import { getCookieJar } from '@timber-js/app/server';
+
+const c = getCookieJar();
+c.get('session'); // Read
+c.set('theme', 'dark'); // Set (before flush only)
+c.delete('session'); // Delete
+c.clear(); // Clear all
+```
+
+Mutations are only allowed before the response flushes. Attempting to set a cookie after flush throws in dev mode.
+
+For typed cookies with validation and a client React hook, see [`defineCookie()`](/docs/typed-params) from `@timber-js/app/cookies`.
+
+Cookies queued before a middleware error are included once on the HTTP 500 response. They also survive when `proxy.ts` awaits `next()` and then throws. This applies to both document requests and client navigations; a later error does not roll back queued cookie writes.
+
+## Actions
+
+### `createActionClient(options)`
+
+Create a reusable action client with middleware for auth and validation.
+
+```ts
+import { createActionClient, ActionError } from '@timber-js/app/server';
+import { getUser } from '@/lib/auth';
+
+const action = createActionClient({
+  middleware: async () => {
+    const user = await getUser();
+    if (!user) throw new ActionError('UNAUTHORIZED');
+    return { user };
+  },
+});
+
+// Usage:
+const myAction = action.schema(z.object({ title: z.string() })).action(async ({ input, ctx }) => {
+  // ctx.user is typed from middleware return
+});
+```
+
+### `ActionError`
+
+Throw from action middleware or bodies to produce a typed error result.
+
+```ts
+throw new ActionError('UNAUTHORIZED');
+throw new ActionError('VALIDATION_FAILED', { field: 'email' });
+```
+
+### `revalidatePath(path)`
+
+Re-render a path and return the RSC payload as part of the action response. Naming a page other than the one the action ran on makes the browser drop its cached pages, so the next navigation fetches fresh data. Server actions only: called anywhere else, it throws, because there is no action response to attach the render to. From a `route.ts` handler or a job, use `revalidateTag()` or `cache.invalidate()`.
+
+### `revalidateTag(tag)`
+
+Invalidate all cache entries with the given tag, and the pre-rendered components that carry it. Returns `Promise<void>`. Callable from any server code:
+
+- **In a server action**, the invalidation runs after the action body returns, before any `revalidatePath()` render, so that render sees fresh data. The promise resolves immediately.
+- **Anywhere else** (a `route.ts` webhook, a job), it invalidates immediately. `await` it before you respond.
+
+## Segment Params
+
+### `getSegmentParams(segmentPath?)`
+
+Returns route path params for the current request. Pass a `SEGMENT_PATH` string from `$segment` for exact types, or omit for `Partial<AllSegmentParams>`. ALS-backed — works in server components, middleware, access checks, and server actions.
+
+```ts
+import { SEGMENT_PATH } from './$segment';
+import { getSegmentParams } from '@timber-js/app/server';
+
+const { id } = getSegmentParams(SEGMENT_PATH); // Exact types from schema
+const params = getSegmentParams(); // Partial<AllSegmentParams>
+```
+
+For typed coercion, define codecs in `app/schema.ts` with `defineSchema()`. See [Typed Params](/docs/typed-params).
+
+## Types
+
+### `RouteContext`
+
+```ts
+interface RouteContext {
+  req: Request;
+  headers: Headers; // Response headers (writable)
+}
+```
+
+Segment params and query params are **not** on `RouteContext`. Read them the same way pages do — `getSegmentParams(SEGMENT_PATH)` (importing `SEGMENT_PATH` from the route's `./$segment` module) and `searchParams.get()` on an imported definition. For the raw query string, use `new URL(ctx.req.url).searchParams`.
+
+### `MiddlewareContext`
+
+```ts
+interface MiddlewareContext {
+  req: Request;
+  segmentParams: Record<string, string | string[]>;
+  headers: Headers; // Response headers (writable)
+  requestHeaders: Headers; // Request headers (injectable)
+  readonly nonce: string; // Per-request CSP nonce, generated on first read
+}
+```
+
+### `AccessContext`
+
+Empty interface — `access.ts` takes no arguments. Use ALS-backed imports like `getSegmentParams(SEGMENT_PATH)`.
+
+### `Metadata`
+
+The full metadata type — see [Metadata & SEO](/docs/metadata-and-fonts) for usage.
+
+### `MetadataRoute`
+
+Type for metadata route files (sitemap, robots, etc.).
+
+## Tracing
+
+### `getTraceId()`
+
+Returns the current request's 32-char hex trace ID. Works in middleware, access checks, server components, and server actions.
+
+```ts
+import { getTraceId } from '@timber-js/app/server';
+
+const id = getTraceId();
+```
+
+### `getSpanId()`
+
+Returns the current OTEL span ID, or `undefined` if OTEL is not active.
+
+### `withSpan(name, attributes, fn)`
+
+Run a function within an OTEL span. No-op passthrough if OTEL is not available.
+
+```ts
+import { withSpan } from '@timber-js/app/server';
+
+declare const db: { query(...args: unknown[]): Promise<unknown> };
+
+const result = await withSpan('db.query', { table: 'users' }, () => db.query());
+```
+
+### `addSpanEvent(name, attributes?)`
+
+Add an event to the current active span.
+
+See [Instrumentation & Tracing](/docs/instrumentation) for full documentation.
+
+## Lifecycle
+
+### `waitUntil(promise)`
+
+Register a promise to be kept alive after the response is sent. Platform-dependent — works on Cloudflare Workers and other platforms that support it.
+
+```ts
+import { waitUntil } from '@timber-js/app/server';
+
+waitUntil(analytics.track(event));
+```

package/docs/api/31-api-client.mdx

@@ -0,0 +1,170 @@
+---
+title: 'API: @timber-js/app/client'
+description: 'Client-side exports — Link, useRouter, usePathname, navigation hooks, and form utilities.'
+slug: 'api-client'
+---
+
+# @timber-js/app/client
+
+Client-side components and hooks. Import from `@timber-js/app/client`.
+
+## Components
+
+### `<Link>`
+
+Client-side navigation link. Type-checks `href` against the generated route map.
+
+```tsx
+import { Link } from '@timber-js/app/client';
+
+<Link href="/about">About</Link>
+<Link href="/products/123" replace>Product</Link>
+<Link href="/gallery" onNavigate={(e) => { /* intercept */ }}>Gallery</Link>
+```
+
+#### Props
+
+| Prop              | Type                | Description                                                                                                  |
+| ----------------- | ------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `href`            | `string`            | Target URL (type-checked against route map)                                                                  |
+| `replace`         | `boolean`           | Use `replaceState` instead of `pushState`                                                                    |
+| `prefetch`        | `boolean`           | Prefetch the RSC payload on hover                                                                            |
+| `onNavigate`      | `OnNavigateHandler` | Intercept navigation before routing                                                                          |
+| `transitionTypes` | `string[]`          | View transition types for this navigation (see [View transitions](/docs/client-navigation#view-transitions)) |
+
+`prefetch` also works for previously visited URLs. A click can reuse the prefetched payload for 30 seconds; after expiry, navigation fetches a fresh payload. Same-page fragment links only scroll within the page and do not prefetch.
+
+### `<TimberErrorBoundary>`
+
+Error boundary component with reset support.
+
+## Hooks
+
+### `useRouter()`
+
+Programmatic navigation.
+
+```tsx
+const router = useRouter();
+router.push('/dashboard');
+router.replace('/settings');
+router.refresh();
+router.back();
+router.forward();
+```
+
+#### `RouterInstance`
+
+| Method                    | Description                        |
+| ------------------------- | ---------------------------------- |
+| `push(href, options?)`    | Navigate, add history entry        |
+| `replace(href, options?)` | Navigate, replace history entry    |
+| `refresh()`               | Re-fetch current route RSC payload |
+| `back()`                  | Go back                            |
+| `forward()`               | Go forward                         |
+
+`options` is `{ scroll?: boolean; transitionTypes?: string[] }`. Set `scroll: false` to keep the scroll position. `transitionTypes` are view transition types for this navigation.
+
+A `deny()` reached by a client navigation renders your status page in place, without a page load — the denial travels in the navigation payload, and the boundary for the matching status file renders it. The payload response itself is always HTTP 200; the status code contract is a property of full page loads, where the browser, crawlers, and CDNs are the ones reading it.
+
+If the server cannot answer a navigation or a `refresh()` at all, the router hands the URL back to the server as a full page load so it can render the error page as HTML with the right status code. That applies to back/forward too. None of these methods report the failure to your code — there is nothing to catch, and nothing to render a fallback for.
+
+### `usePathname()`
+
+Returns the current pathname as a string.
+
+```tsx
+const pathname = usePathname(); // "/dashboard/settings"
+```
+
+### `useSelectedLayoutSegment()`
+
+Returns the active child segment within a layout.
+
+```tsx
+const segment = useSelectedLayoutSegment(); // "settings"
+```
+
+### `useSelectedLayoutSegments()`
+
+Returns all active segments below the current layout.
+
+```tsx
+const segments = useSelectedLayoutSegments(); // ["settings", "profile"]
+```
+
+### `usePendingNavigation()`
+
+Returns whether a navigation is in flight. Use instead of wrapping `children` in `<Suspense>`.
+
+```tsx
+const pending = usePendingNavigation();
+```
+
+### `useLinkStatus()`
+
+Per-link pending state. Must be used inside a `<Link>` component's children.
+
+```tsx
+const { isPending } = useLinkStatus();
+```
+
+### `useSegmentParams(segmentPath?)`
+
+Returns the current route segment params. Pass `SEGMENT_PATH` from `$segment` for exact types.
+
+```tsx
+import { SEGMENT_PATH } from './$segment';
+import { useSegmentParams } from '@timber-js/app/client';
+
+const { id } = useSegmentParams(SEGMENT_PATH); // Exact types from schema
+const params = useSegmentParams(); // Partial<AllSegmentParams>
+```
+
+## Form Hooks
+
+### `useActionState(action, initialState)`
+
+Typed wrapper around React 19's `useActionState`. Returns `[result, formAction, isPending, errors]` — the 4th element auto-derives field and form-level errors from the result.
+
+```tsx
+const [result, action, isPending, errors] = useActionState(createTodo, flash);
+
+errors.hasErrors; // boolean
+errors.fieldErrors; // Record<string, string[]>
+errors.formErrors; // string[]
+errors.serverError; // { code, data? } | null
+errors.getFieldError('title'); // string | null
+```
+
+### `useFormAction(action)`
+
+Bind a server action to a form with pending state.
+
+## Utilities
+
+### `interpolateParams(pattern, params)`
+
+Fill a route pattern with param values.
+
+```ts
+interpolateParams('/products/[id]', { id: '123' }); // "/products/123"
+```
+
+### `defineSearchParams().useQueryStates()`
+
+Sync typed search params to the URL. Called on a `defineSearchParams()` definition. See [Search Params](/docs/typed-params).
+
+## Cookie Hooks
+
+### `defineCookie().useCookie()`
+
+Reactive cookie access in client components. Define a typed cookie with `defineCookie()` from `@timber-js/app/cookies`, then call `.useCookie()` in client components. Returns `[value, setter, deleter]`.
+
+```tsx
+import { themeCookie } from '../lib/cookies';
+
+const [theme, setTheme, deleteTheme] = themeCookie.useCookie();
+```
+
+See [Cookies](/docs/typed-params) for full documentation.