@timber-js/app 0.2.0-alpha.16 → 0.2.0-alpha.161

package/dist/shims/image.d.ts

@@ -34,7 +34,7 @@ export declare function Image({ priority: _priority, quality: _quality, fill: _f
     alt?: string | undefined;
     crossOrigin?: "" | "anonymous" | "use-credentials" | undefined;
     decoding?: "async" | "auto" | "sync" | undefined;
-    fetchPriority?: "high" | "low" | "auto";
+    fetchPriority?: "high" | "low" | "auto" | undefined;
     height?: number | string | undefined;
     loading?: "eager" | "lazy" | undefined;
     referrerPolicy?: import("react").HTMLAttributeReferrerPolicy | undefined;
@@ -51,17 +51,17 @@ export declare function Image({ priority: _priority, quality: _quality, fill: _f
     autoCapitalize?: "off" | "none" | "on" | "sentences" | "words" | "characters" | undefined | (string & {});
     autoFocus?: boolean | undefined;
     className?: string | undefined;
-    contentEditable?: (boolean | "false" | "true") | "inherit" | "plaintext-only" | undefined;
+    contentEditable?: (boolean | "true" | "false") | "inherit" | "plaintext-only" | undefined;
     contextMenu?: string | undefined;
     dir?: string | undefined;
-    draggable?: (boolean | "false" | "true") | undefined;
+    draggable?: (boolean | "true" | "false") | undefined;
     enterKeyHint?: "enter" | "done" | "go" | "next" | "previous" | "search" | "send" | undefined;
     hidden?: boolean | undefined;
     id?: string | undefined;
     lang?: string | undefined;
     nonce?: string | undefined;
     slot?: string | undefined;
-    spellCheck?: (boolean | "false" | "true") | undefined;
+    spellCheck?: (boolean | "true" | "false") | undefined;
     style?: import("react").CSSProperties | undefined;
     tabIndex?: number | undefined;
     title?: string | undefined;
@@ -99,11 +99,11 @@ export declare function Image({ priority: _priority, quality: _quality, fill: _f
     exportparts?: string | undefined;
     part?: string | undefined;
     "aria-activedescendant"?: string | undefined;
-    "aria-atomic"?: (boolean | "false" | "true") | undefined;
+    "aria-atomic"?: (boolean | "true" | "false") | undefined;
     "aria-autocomplete"?: "none" | "inline" | "list" | "both" | undefined;
     "aria-braillelabel"?: string | undefined;
     "aria-brailleroledescription"?: string | undefined;
-    "aria-busy"?: (boolean | "false" | "true") | undefined;
+    "aria-busy"?: (boolean | "true" | "false") | undefined;
     "aria-checked"?: boolean | "false" | "mixed" | "true" | undefined;
     "aria-colcount"?: number | undefined;
     "aria-colindex"?: number | undefined;
@@ -114,37 +114,37 @@ export declare function Image({ priority: _priority, quality: _quality, fill: _f
     "aria-describedby"?: string | undefined;
     "aria-description"?: string | undefined;
     "aria-details"?: string | undefined;
-    "aria-disabled"?: (boolean | "false" | "true") | undefined;
+    "aria-disabled"?: (boolean | "true" | "false") | undefined;
     "aria-dropeffect"?: "none" | "copy" | "execute" | "link" | "move" | "popup" | undefined;
     "aria-errormessage"?: string | undefined;
-    "aria-expanded"?: (boolean | "false" | "true") | undefined;
+    "aria-expanded"?: (boolean | "true" | "false") | undefined;
     "aria-flowto"?: string | undefined;
-    "aria-grabbed"?: (boolean | "false" | "true") | undefined;
+    "aria-grabbed"?: (boolean | "true" | "false") | undefined;
     "aria-haspopup"?: boolean | "false" | "true" | "menu" | "listbox" | "tree" | "grid" | "dialog" | undefined;
-    "aria-hidden"?: (boolean | "false" | "true") | undefined;
+    "aria-hidden"?: (boolean | "true" | "false") | undefined;
     "aria-invalid"?: boolean | "false" | "true" | "grammar" | "spelling" | undefined;
     "aria-keyshortcuts"?: string | undefined;
     "aria-label"?: string | undefined;
     "aria-labelledby"?: string | undefined;
     "aria-level"?: number | undefined;
     "aria-live"?: "off" | "assertive" | "polite" | undefined;
-    "aria-modal"?: (boolean | "false" | "true") | undefined;
-    "aria-multiline"?: (boolean | "false" | "true") | undefined;
-    "aria-multiselectable"?: (boolean | "false" | "true") | undefined;
+    "aria-modal"?: (boolean | "true" | "false") | undefined;
+    "aria-multiline"?: (boolean | "true" | "false") | undefined;
+    "aria-multiselectable"?: (boolean | "true" | "false") | undefined;
     "aria-orientation"?: "horizontal" | "vertical" | undefined;
     "aria-owns"?: string | undefined;
     "aria-placeholder"?: string | undefined;
     "aria-posinset"?: number | undefined;
     "aria-pressed"?: boolean | "false" | "mixed" | "true" | undefined;
-    "aria-readonly"?: (boolean | "false" | "true") | undefined;
+    "aria-readonly"?: (boolean | "true" | "false") | undefined;
     "aria-relevant"?: "additions" | "additions removals" | "additions text" | "all" | "removals" | "removals additions" | "removals text" | "text" | "text additions" | "text removals" | undefined;
-    "aria-required"?: (boolean | "false" | "true") | undefined;
+    "aria-required"?: (boolean | "true" | "false") | undefined;
     "aria-roledescription"?: string | undefined;
     "aria-rowcount"?: number | undefined;
     "aria-rowindex"?: number | undefined;
     "aria-rowindextext"?: string | undefined;
     "aria-rowspan"?: number | undefined;
-    "aria-selected"?: (boolean | "false" | "true") | undefined;
+    "aria-selected"?: (boolean | "true" | "false") | undefined;
     "aria-setsize"?: number | undefined;
     "aria-sort"?: "none" | "ascending" | "descending" | "other" | undefined;
     "aria-valuemax"?: number | undefined;

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()` / `permanentRedirect()` / `notFound()` without
+ * pulling server/primitives.ts into the browser bundle.
+ *
+ * Next.js supports calling redirect()/notFound() during client component
+ * render. timber matches that by throwing a plain Error carrying the same
+ * JSON digest the server pipeline attaches to RedirectSignal/DenySignal.
+ * TimberErrorBoundary recognizes the digest and converts it to an SPA
+ * navigation (redirect) or a status-code fallback (notFound), 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,29 @@
  *
  * 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;
+import type { RedirectTypeValue } from '../shared/redirect-type.js';
+export { useSegmentParams, useSegmentParams as useParams } from '../client/use-segment-params.js';
+export { useSearchParams } from '../client/use-search-params.js';
+export { usePathname, useRouter, useSelectedLayoutSegment, useSelectedLayoutSegments, } from '@timber-js/app/client';
+export { RedirectType } from '../shared/redirect-type.js';
+/**
+ * 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;
+/**
+ * Client-render permanent redirect. On the client there is no HTTP status —
+ * this behaves identically to redirect() apart from the digest's status.
+ */
+export declare function permanentRedirect(path: string, _type?: RedirectTypeValue): never;
+/**
+ * Client-render notFound. Throws a deny-digest error (status 404) that the
+ * nearest matching TimberErrorBoundary renders as the 404 fallback. The
+ * message matches DenySignal's so digest-less fallback parsing still works.
+ */
 export declare function notFound(): 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;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,iBAAiB,GAAG,KAAK,CAGhF;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,IAAI,KAAK,CAEhC"}

package/dist/shims/navigation.d.ts

@@ -1,10 +1,16 @@
 /**
  * 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.js';
+export { useSearchParams } from '../client/use-search-params.js';
+export { usePathname, useRouter, useSelectedLayoutSegment, useSelectedLayoutSegments, } from '@timber-js/app/client';
+export { redirect, redirectExternal, RedirectType } from '@timber-js/app/server';
+export { permanentRedirect, notFound } from '../server/primitives.js';
 //# 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;AAIjF,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,yBAAyB,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/docs/api/30-api-server.mdx

@@ -0,0 +1,233 @@
+---
+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(statusOrOptions?, data?)`
+
+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, { retry: true }); // 503 with data
+deny({ status: 500, data: { title: 'Error' } }); // object form
+```
+
+### `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`.
+
+## 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.
+
+### `revalidateTag(tag)`
+
+Invalidate all cache entries with the given tag.
+
+## 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 via the same ALS-backed `.get()` accessors pages use — `segmentParams.get()` from `./params` and `searchParams.get()` from `./search-params`. 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)
+}
+```
+
+### `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,161 @@
+---
+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 on hover/viewport                  |
+| `onNavigate` | `OnNavigateHandler` | Intercept navigation before routing         |
+
+### `<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)`    | Navigate, add history entry        |
+| `replace(href)` | Navigate, replace history entry    |
+| `refresh()`     | Re-fetch current route RSC payload |
+| `back()`        | Go back                            |
+| `forward()`     | Go forward                         |
+
+### `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 { pending } = 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.