@timber-js/app 0.2.0-alpha.14 → 0.2.0-alpha.141

package/src/client/error-boundary.tsx

@@ -20,6 +20,7 @@
 
 import { Component, createElement, type ReactNode } from 'react';
 import { getSsrData } from './ssr-data.js';
+import { getRouterOrNull } from './router-ref.js';
 
 // ─── Page Unload Detection ───────────────────────────────────────────────────
 // Track whether the page is being unloaded (user refreshed or navigated away).
@@ -65,17 +66,24 @@ type ParsedDigest = DenyDigest | RenderErrorDigest | RedirectDigest;
 
 export interface TimberErrorBoundaryProps {
   /** The component to render when an error is caught. */
-  fallbackComponent: (...args: unknown[]) => ReactNode;
+  fallbackComponent?: (...args: unknown[]) => ReactNode;
+  /**
+   * Pre-rendered fallback element. Used for MDX status files which are server
+   * components and cannot be passed as function props across the RSC→client
+   * boundary. When set, rendered directly instead of calling fallbackComponent.
+   *
+   * See design/10-error-handling.md §"Status-Code File Variants" — MDX status
+   * files are server components by default (zero client JS).
+   */
+  fallbackElement?: ReactNode;
   /**
    * Status code filter. If set, only catches errors matching this status.
    * 400 = any 4xx, 500 = any 5xx, specific number = exact match.
    */
   status?: number;
   /**
-   * When true, catching a DenySignal sets _denyHandledByBoundary on the
-   * nav context to prevent page-level deny promotion. Only slot catch-all
-   * boundaries should set this — segment boundaries (403.tsx, 4xx.tsx,
-   * error.tsx) must NOT, otherwise normal page denies get swallowed.
+   * When true, this boundary wraps a parallel slot. Slot denials are
+   * graceful degradation — they must NOT change the HTTP status code.
    */
   isSlotBoundary?: boolean;
   children: ReactNode;
@@ -86,6 +94,13 @@ interface TimberErrorBoundaryState {
   error: Error | null;
 }
 
+// Module-level guard: the first boundary to catch a given redirect digest
+// schedules the navigation and marks it handled here. Subsequent renders
+// (React retries the error-boundary render path multiple times in dev, and
+// outer boundaries that also see the error) become no-ops, preventing
+// duplicate router.navigate() calls.
+const _handledRedirects = new WeakSet<object>();
+
 // ─── Component ───────────────────────────────────────────────────────────────
 
 export class TimberErrorBoundary extends Component<
@@ -131,11 +146,48 @@ export class TimberErrorBoundary extends Component<
     const error = this.state.error;
     const parsed = parseDigest(error);
 
-    // RedirectSignal errors must propagate through all error boundaries
-    // so the SSR shell fails and the pipeline catch block can produce a
-    // proper HTTP redirect response. See design/04-authorization.md.
+    // RedirectSignal handling splits by environment:
+    //
+    // - SSR (no window): re-throw so the Fizz shell fails and the server
+    //   pipeline catch block can produce a proper HTTP 3xx response. See
+    //   design/04-authorization.md.
+    //
+    // - Client (window exists): a RedirectSignal that leaked into the RSC
+    //   Flight payload during client navigation would otherwise bubble past
+    //   every error boundary to `window.onerror`, which in dev triggers the
+    //   Vite error overlay (false positive — navigation itself works).
+    //   Instead, ask the router to perform an SPA navigation to the target
+    //   and render nothing while it takes over. The router's own catch path
+    //   handles cross-origin / hard navigations. See TIM-838.
     if (parsed?.type === 'redirect') {
-      throw error;
+      if (typeof window === 'undefined') {
+        throw error;
+      }
+      // Dedupe: React may render the error-boundary fallback path more
+      // than once for a single caught error (dev-mode double render, and
+      // additional boundaries above us in the tree). Only schedule the
+      // navigation on the first render that sees this error instance.
+      const alreadyHandled = _handledRedirects.has(error);
+      if (!alreadyHandled) {
+        _handledRedirects.add(error);
+        const router = getRouterOrNull();
+        if (router) {
+          // Schedule the navigation outside the render phase to avoid
+          // setState-during-render warnings from router state updates.
+          queueMicrotask(() => {
+            router.navigate(parsed.location, { replace: true }).catch(() => {
+              // Fall back to a hard navigation if the soft navigation fails.
+              window.location.href = parsed.location;
+            });
+          });
+        } else {
+          // No router available (shouldn't happen post-bootstrap) — fall
+          // back to a hard navigation so the user still ends up at the
+          // target.
+          window.location.href = parsed.location;
+        }
+      }
+      return null;
     }
 
     // If this boundary has a status filter, check whether the error matches.
@@ -148,20 +200,45 @@ export class TimberErrorBoundary extends Component<
       }
     }
 
-    // Report DenySignal handling to prevent page-level promotion — but only
-    // for slot boundaries. Segment boundaries (403.tsx, 4xx.tsx, error.tsx)
-    // must NOT set this flag, otherwise normal page/hold-window denies get
-    // swallowed as 200 with boundary HTML instead of the intended 4xx.
-    // Runs here in render() (not getDerivedStateFromError) so the status
-    // filter has already been applied — non-matching boundaries re-threw above.
-    // See LOCAL-298.
-    if (parsed?.type === 'deny' && this.props.isSlotBoundary) {
-      const ssrData = getSsrData();
-      if (ssrData?._navContext) {
-        ssrData._navContext._denyHandledByBoundary = true;
+    // Report DenySignal handling so the pipeline skips the redundant
+    // renderDenyPage() re-render — but ONLY when this boundary can fully
+    // handle the deny in-tree:
+    //
+    // ✅ TSX boundaries (fallbackComponent) — can receive runtime props
+    //    (status, dangerouslyPassData) dynamically in render()
+    // ❌ MDX boundaries (fallbackElement) — pre-rendered at tree-build time,
+    //    cannot receive runtime deny props. Must fall through to re-render.
+    //
+    // For qualifying segment boundaries: also set the HTTP status code from
+    // the DenySignal so the Response has the correct 4xx status. This runs
+    // synchronously during Fizz rendering, BEFORE onShellReady.
+    //
+    // For slot boundaries: set _denyHandledByBoundary but do NOT change
+    // statusCode — slot denials are graceful degradation.
+    //
+    // See TIM-664, LOCAL-298.
+    if (parsed?.type === 'deny') {
+      const canHandleInTree = this.props.fallbackElement == null;
+
+      if (canHandleInTree || this.props.isSlotBoundary) {
+        const ssrData = getSsrData();
+        if (ssrData?._navContext) {
+          ssrData._navContext._denyHandledByBoundary = true;
+          if (!this.props.isSlotBoundary) {
+            ssrData._navContext.statusCode = parsed.status;
+          }
+        }
       }
     }
 
+    // Pre-rendered fallback element (MDX status files) — render directly.
+    // MDX components are server components that cannot be passed as function
+    // props across the RSC→client boundary. Instead, they are pre-rendered
+    // as elements in the RSC environment and passed here as fallbackElement.
+    if (this.props.fallbackElement != null) {
+      return this.props.fallbackElement;
+    }
+
     // Render the fallback component with the right props shape.
     if (parsed?.type === 'deny') {
       return createElement(this.props.fallbackComponent as never, {
@@ -196,8 +273,8 @@ function parseDigest(error: Error): ParsedDigest | null {
     if (parsed && typeof parsed === 'object' && typeof parsed.type === 'string') {
       return parsed as ParsedDigest;
     }
-  } catch {
-    // Not JSON — legacy or unknown digest format
+  } catch (e) {
+    console.debug('[timber] error digest is not valid JSON:', e instanceof Error ? e.message : e);
   }
   return null;
 }

package/src/client/error-reconstituter.tsx

@@ -0,0 +1,65 @@
+'use client';
+
+/**
+ * Reconstitutes a SerializableError into a real Error instance before
+ * passing to the user's error component.
+ *
+ * TSX error pages are 'use client' components that receive { error: Error, digest, reset }.
+ * Error objects are not RSC-serializable (React Flight throws "Only plain objects
+ * can be passed to Client Components"). This wrapper receives the error as a plain
+ * SerializableError object, reconstitutes a real Error instance, and passes it
+ * to the user's error component — ensuring error instanceof Error works correctly.
+ *
+ * See design/spike-TIM-565-unify-error-pages.md §"Edge Case B"
+ * See design/10-error-handling.md §"RSC → SSR for Error Pages via SerializableError"
+ */
+
+import { createElement, type ReactNode, type ComponentType } from 'react';
+
+/**
+ * Plain-object representation of an Error that can cross the RSC → client boundary.
+ * Stack is only included in dev mode (gated by isDevMode() on the server).
+ */
+export interface SerializableError {
+  message: string;
+  name: string;
+  stack?: string;
+}
+
+/**
+ * Props for the ErrorReconstituter wrapper component.
+ * All props are RSC-serializable:
+ * - error: plain object (SerializableError)
+ * - digest: plain JSON or null
+ * - reset: undefined (only meaningful on client after boundary catch)
+ * - component: client module reference (RSC Flight serializes as opaque ref)
+ */
+interface ErrorReconstituterProps {
+  error: SerializableError;
+  digest: { code: string; data: unknown } | null;
+  reset: undefined;
+  component: ComponentType<{
+    error: Error;
+    digest: { code: string; data: unknown } | null;
+    reset: (() => void) | undefined;
+  }>;
+}
+
+/**
+ * Reconstitute a SerializableError into a real Error instance and render
+ * the user's error component with the proper props.
+ */
+export function ErrorReconstituter({
+  error: serialized,
+  digest,
+  reset,
+  component,
+}: ErrorReconstituterProps): ReactNode {
+  // Reconstitute a real Error so instanceof checks work in user code
+  const error = Object.assign(new Error(serialized.message), {
+    name: serialized.name,
+    ...(serialized.stack != null ? { stack: serialized.stack } : {}),
+  });
+
+  return createElement(component, { error, digest, reset });
+}

package/src/client/form.tsx

@@ -12,8 +12,8 @@
  */
 
 import { useActionState as reactUseActionState, useTransition } from 'react';
-import type { ActionResult, ValidationErrors } from '#/server/action-client';
-import type { FormFlashData } from '#/server/form-flash';
+import type { ActionFn, ActionResult, InputHint, ValidationErrors } from '../server/action-client';
+import type { FormFlashData } from '../server/form-flash';
 
 // ─── Types ───────────────────────────────────────────────────────────────
 
@@ -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 ───────────────────────────────────────────────────────
@@ -90,15 +98,22 @@ export function useActionState<TData>(
  * </button>
  * ```
  */
-export function useFormAction<TData>(
-  action: (input: unknown) => Promise<ActionResult<TData>>
-): [(input?: unknown) => Promise<ActionResult<TData>>, boolean] {
+export function useFormAction<TData = unknown, TInput = unknown>(
+  action: ActionFn<TData, TInput> | ((input: TInput) => Promise<ActionResult<TData>>)
+): [
+  (
+    ...args: undefined extends TInput ? [input?: InputHint<TInput>] : [input: InputHint<TInput>]
+  ) => Promise<ActionResult<TData>>,
+  boolean,
+] {
   const [isPending, startTransition] = useTransition();
 
-  const execute = (input?: unknown): Promise<ActionResult<TData>> => {
+  const execute = (input?: InputHint<TInput>): Promise<ActionResult<TData>> => {
     return new Promise((resolve) => {
       startTransition(async () => {
-        const result = await action(input);
+        const result = await (action as (input: InputHint<TInput>) => Promise<ActionResult<TData>>)(
+          input as InputHint<TInput>
+        );
         resolve(result);
       });
     });
@@ -107,9 +122,9 @@ export function useFormAction<TData>(
   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[]>;
@@ -124,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/history.ts

@@ -23,20 +23,42 @@ export interface HistoryEntry {
  * On forward navigation, the new page's payload is pushed onto the stack.
  * On popstate, the cached payload is replayed instantly.
  *
- * Scroll positions are stored in history.state (browser History API),
- * not in this stack — see design/19-client-navigation.md §Scroll Restoration.
+ * Supports two keying modes:
+ * - **URL-keyed** (default): entries keyed by pathname + search.
+ *   Used with the History API fallback.
+ * - **Entry-key + URL**: when the Navigation API is available,
+ *   entries can also be stored by Navigation entry key for
+ *   disambiguation of duplicate URLs in the history stack.
+ *   Falls back to URL lookup when entry key is not found.
+ *
+ * Scroll positions are stored in history.state or Navigation API entry
+ * state, not in this stack — see design/19-client-navigation.md §Scroll Restoration.
  *
  * Entries persist for the session duration (no expiry) and are cleared
  * when the tab is closed — matching browser back-button behavior.
  */
 export class HistoryStack {
   private entries = new Map<string, HistoryEntry>();
+  /** Entries keyed by Navigation API entry key for duplicate URL disambiguation. */
+  private entryKeyMap = new Map<string, HistoryEntry>();
 
-  push(url: string, entry: HistoryEntry): void {
+  push(url: string, entry: HistoryEntry, entryKey?: string): void {
     this.entries.set(url, entry);
+    if (entryKey) {
+      this.entryKeyMap.set(entryKey, entry);
+    }
   }
 
-  get(url: string): HistoryEntry | undefined {
+  /**
+   * Get an entry. When an entry key is provided (Navigation API),
+   * tries the entry-key map first for accurate disambiguation of
+   * duplicate URLs, then falls back to URL lookup.
+   */
+  get(url: string, entryKey?: string): HistoryEntry | undefined {
+    if (entryKey) {
+      const byKey = this.entryKeyMap.get(entryKey);
+      if (byKey) return byKey;
+    }
     return this.entries.get(url);
   }
 

package/src/client/index.ts

@@ -1,64 +1,86 @@
 // @timber-js/app/client — Client-side primitives
 // These are the primary imports for client components.
+//
+// Framework-internal bootstrap, SSR bridge, and segment plumbing is in
+// #client-internal (Node package import).
+// Design doc: design/triage/api-naming-spike.md §8.5
 
-export type { JsonSerializable, RenderErrorDigest } from './types';
+// JsonSerializable moved to @timber-js/app/codec as the single canonical path.
+// Re-export removed per TIM-721.
+export type { RenderErrorDigest } from './types';
 
 // Navigation
 export { Link, interpolateParams, resolveHref, validateLinkHref, buildLinkProps } from './link';
-export type { LinkProps, LinkPropsWithHref, LinkPropsWithParams } from './link';
-export type { OnNavigateHandler, OnNavigateEvent } from './link';
-export { createRouter } from './router';
-export type {
-  RouterInstance,
-  NavigationOptions,
-  RouterDeps,
-  RscDecoder,
-  RootRenderer,
-} from './router';
-export { useNavigationPending } from './use-navigation-pending';
+export { mergePreservedSearchParams } from '../shared/merge-search-params.js';
+export type { LinkProps, LinkPropsWithHref, LinkPropsWithParams, LinkBaseProps } from './link';
+export type { LinkSegmentParams, OnNavigateHandler, OnNavigateEvent } from './link';
+
+// ─── LinkFunction (originally declared here for module augmentation) ───
+//
+// The codegen emits TWO augmentations of this interface:
+//
+//   1. Per-route call signatures — `href: '/products/[id]'` with direct
+//      `segmentParams`/`searchParams` types.
+//   2. Catch-all call signatures — `ExternalHref` + computed `string`
+//      variable hrefs.
+//
+// Both live in the codegen output (NOT here). Overload ORDER matters
+// for error UX, and TypeScript's declaration-merging rule "later overload
+// sets ordered first" means that whichever augmentation block is
+// declared LATER in the codegen file ends up FIRST in the merged call-
+// signature list — and therefore the EARLIER block ends up LAST, which
+// is the overload whose error message TypeScript reports when no
+// overload matches.
+//
+// We want the PER-ROUTE overloads to be the error-reporting ones when
+// a user passes a known literal `href` with a mistyped segmentParam.
+// So the codegen emits them FIRST and the catch-all SECOND. That way
+// a call like:
+//
+//   <Link href="/products/[id]" segmentParams={{ id: maybeUndef }} />
+//
+// reports the actual mismatch (`'string | undefined' is not assignable
+// to 'string | number'` on `id`) instead of the notorious "Type 'string'
+// is not assignable to type 'never'" cascade that the old fixed
+// catch-all produced (TIM-832, sibling of TIM-830 / TIM-624).
+//
+// The interface is kept as an empty placeholder here so:
+// - module augmentation has a base interface to merge into
+// - `link.tsx` can `import type { LinkFunction }` and use it as the
+//   cast target for the `Link` const (an empty interface accepts any
+//   non-nullable value, so the cast is valid even without codegen run)
+// - NO call signatures live here — in a fresh checkout where codegen
+//   hasn't run yet, invoking `<Link>` is deliberately a type error,
+//   which surfaces "codegen hasn't run" rather than a misleading
+//   structural type mismatch.
+//
+// See TIM-624 (original typed Link), TIM-830 (flat searchParams), and
+// TIM-832 (this restructure for overload error UX).
+// eslint-disable-next-line typescript/no-empty-interface -- augmented by codegen
+export interface LinkFunction {
+  // intentionally empty — call signatures are provided via codegen
+  // augmentation in `.timber/timber-routes.d.ts`.
+}
+export { usePendingNavigation } from './use-pending-navigation';
 export { useLinkStatus, LinkStatusContext } from './use-link-status';
 export type { LinkStatus } from './use-link-status';
-export { getRouter, setGlobalRouter } from './router-ref';
 export { useRouter } from './use-router';
 export type { AppRouterInstance } from './use-router';
 export { usePathname } from './use-pathname';
-export { useSearchParams } from './use-search-params';
+export { replaceUrl } from './shallow-url';
+// useSearchParams removed from public exports — lives in next/navigation shim only.
 export { useSelectedLayoutSegment, useSelectedLayoutSegments } from './use-selected-layout-segment';
 
-// Segment context (internal, used by rsc-entry to inject layout position)
-export { SegmentProvider, useSegmentContext } from './segment-context';
-export type { SegmentContextValue } from './segment-context';
-
-// Segment cache (internal, but exported for advanced use)
-export { SegmentCache, PrefetchCache } from './segment-cache';
-export type { SegmentNode, StateTree } from './segment-cache';
-
-// History (internal, but exported for advanced use)
-export { HistoryStack } from './history';
-export type { HistoryEntry } from './history';
-
 // Forms
-export { useActionState, useFormAction, useFormErrors } from './form';
+export { useActionState, useFormAction } from './form';
 export type { UseActionStateFn, UseActionStateReturn, FormErrorsResult } from './form';
 
-// Params
-export { useParams, setCurrentParams } from './use-params';
+// Params — raw hook for untyped access. For typed params, use defineSegmentParams().useSegmentParams().
+export { useSegmentParams } from './use-segment-params';
 
-// Navigation context (framework-internal, used by browser-entry for atomic updates)
-export { NavigationProvider, getNavigationState, setNavigationState } from './navigation-context';
-export type { NavigationState } from './navigation-context';
+// Query states — useQueryStates lives on defineSearchParams().useQueryStates()
+// and is available via direct import for advanced cases.
 
-// Query states (URL-synced search params)
-export { useQueryStates, bindUseQueryStates } from './use-query-states';
-
-// 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';
-
-// SSR data (framework-internal, used by ssr-entry to provide request data to hooks)
-export { setSsrData, clearSsrData, getSsrData } from './ssr-data';
-export type { SsrData } from './ssr-data';
-
-// Error boundary (framework-internal, used by tree-builder and rsc-entry)
-export { TimberErrorBoundary } from './error-boundary';
-export type { TimberErrorBoundaryProps } from './error-boundary';

package/src/client/internal.ts

@@ -0,0 +1,58 @@
+// #client-internal — Framework-internal client exports
+//
+// This module is a Node package import (#client-internal in package.json
+// "imports" field). It is only resolvable from within @timber-js/app —
+// external consumers cannot import it.
+//
+// These exports are consumed by browser-entry, ssr-entry, and build plugins.
+// They are NOT part of the user-facing API and should not appear in
+// documentation or autocomplete for application developers.
+//
+// Design doc: design/triage/api-naming-spike.md §8.5
+
+// ── Bootstrap ────────────────────────────────────────────────────────────
+export { createRouter } from './router.js';
+export type {
+  RouterInstance,
+  NavigationOptions,
+  RouterDeps,
+  RouterPhase,
+  RscDecoder,
+  RootRenderer,
+} from './router.js';
+export { getRouter, getRouterOrNull, setGlobalRouter } from './router-ref.js';
+
+// ── SSR bridge ───────────────────────────────────────────────────────────
+export { setSsrData, clearSsrData, getSsrData } from './ssr-data.js';
+export type { SsrData } from './ssr-data.js';
+
+// ── Segment context ──────────────────────────────────────────────────────
+export { SegmentProvider, useSegmentContext } from './segment-context.js';
+export type { SegmentContextValue } from './segment-context.js';
+
+// ── Segment cache ────────────────────────────────────────────────────────
+export { SegmentCache, PrefetchCache } from './segment-cache.js';
+export type { SegmentNode, StateTree } from './segment-cache.js';
+
+// ── History ──────────────────────────────────────────────────────────────
+export { HistoryStack } from './history.js';
+export type { HistoryEntry } from './history.js';
+
+// ── Params (internal setter + raw hooks) ─────────────────────────────────
+export { setCurrentParams } from './use-segment-params.js';
+export { useSearchParams } from './use-search-params.js';
+
+// ── Navigation context ───────────────────────────────────────────────────
+export {
+  NavigationProvider,
+  getNavigationState,
+  setNavigationState,
+} from './navigation-context.js';
+export type { NavigationState } from './navigation-context.js';
+
+// ── Query states (internal binder) ───────────────────────────────────────
+export { bindUseQueryStates } from './use-query-states.js';
+
+// ── Error boundary ───────────────────────────────────────────────────────
+export { TimberErrorBoundary } from './error-boundary.js';
+export type { TimberErrorBoundaryProps } from './error-boundary.js';