@timber-js/app 0.2.0-alpha.7 → 0.2.0-alpha.71

package/src/client/error-boundary.tsx

@@ -65,17 +65,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;
@@ -148,20 +155,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, {

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 { ActionResult, ValidationErrors } from '../server/action-client';
+import type { FormFlashData } from '../server/form-flash';
 
 // ─── Types ───────────────────────────────────────────────────────────────
 

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

@@ -5,20 +5,22 @@ export type { JsonSerializable, 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 { mergePreservedSearchParams } from '../shared/merge-search-params.js';
+export type { LinkFunction, LinkProps, LinkPropsWithHref, LinkPropsWithParams } from './link';
+export type { LinkSegmentParams, OnNavigateHandler, OnNavigateEvent } from './link';
 export { createRouter } from './router';
 export type {
   RouterInstance,
   NavigationOptions,
   RouterDeps,
+  RouterPhase,
   RscDecoder,
   RootRenderer,
 } from './router';
 export { useNavigationPending } from './use-navigation-pending';
 export { useLinkStatus, LinkStatusContext } from './use-link-status';
 export type { LinkStatus } from './use-link-status';
-export { getRouter, setGlobalRouter } from './router-ref';
+export { getRouter, getRouterOrNull, setGlobalRouter } from './router-ref';
 export { useRouter } from './use-router';
 export type { AppRouterInstance } from './use-router';
 export { usePathname } from './use-pathname';
@@ -42,7 +44,7 @@ export { useActionState, useFormAction, useFormErrors } from './form';
 export type { UseActionStateFn, UseActionStateReturn, FormErrorsResult } from './form';
 
 // Params
-export { useParams, setCurrentParams } from './use-params';
+export { useSegmentParams, setCurrentParams } from './use-params';
 
 // Navigation context (framework-internal, used by browser-entry for atomic updates)
 export { NavigationProvider, getNavigationState, setNavigationState } from './navigation-context';
@@ -55,6 +57,13 @@ export { useQueryStates, bindUseQueryStates } from './use-query-states';
 export { useCookie } from './use-cookie';
 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';
+_registerUseCookieModule(_useCookieMod);
+
 // 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';

package/src/client/link-pending-store.ts

@@ -0,0 +1,136 @@
+/**
+ * Link Pending Store — module-level singleton for per-link pending state.
+ *
+ * Tracks which link instance is currently navigating so that only the
+ * clicked link shows pending. All other links remain unaffected — zero
+ * wasted re-renders.
+ *
+ * The store holds:
+ * - A reference to the currently navigating link's state setter
+ * - A navigation counter to guard against stale clears (race condition
+ *   when the user clicks Link B before Link A's navigation completes)
+ *
+ * Flow:
+ * 1. Link click handler: setLinkForCurrentNavigation(instance) →
+ *    resets previous link (urgent), sets new link pending (urgent),
+ *    stores setter + increments navId
+ * 2. NavigationRoot startTransition: captures navId, does async work
+ * 3. NavigationRoot commit: resetLinkPending(capturedNavId) →
+ *    calls setter(IDLE) inside the transition (batched, atomic with tree)
+ *    Only clears if navId matches (prevents stale T1 from clearing T2's link)
+ *
+ * SINGLETON GUARANTEE: Uses `globalThis` via `Symbol.for` keys (same
+ * pattern as NavigationContext) because the RSC client bundler can
+ * duplicate this module across chunks. Module-level variables would
+ * create separate instances per chunk.
+ *
+ * See design/19-client-navigation.md §"Per-Link Pending State"
+ */
+
+import type { LinkStatus } from './use-link-status.js';
+
+// ─── Types ───────────────────────────────────────────────────────
+
+export interface LinkPendingInstance {
+  setLinkStatus: (status: LinkStatus) => void;
+}
+
+// ─── Singleton Storage ───────────────────────────────────────────
+
+const LINK_PENDING_KEY = Symbol.for('__timber_link_pending');
+
+/** Status object indicating link is pending — shared reference */
+export const PENDING_LINK_STATUS: LinkStatus = { pending: true };
+
+/** Status object indicating link is idle — shared reference */
+export const IDLE_LINK_STATUS: LinkStatus = { pending: false };
+
+interface LinkPendingState {
+  /** The link instance that initiated the current navigation, or null */
+  current: LinkPendingInstance | null;
+  /** Monotonically increasing counter — guards against stale clears */
+  navId: number;
+}
+
+function getStore(): LinkPendingState {
+  const g = globalThis as Record<symbol, unknown>;
+  if (!g[LINK_PENDING_KEY]) {
+    g[LINK_PENDING_KEY] = { current: null, navId: 0 };
+  }
+  return g[LINK_PENDING_KEY] as LinkPendingState;
+}
+
+// ─── Public API ──────────────────────────────────────────────────
+
+/**
+ * Register the link instance that initiated the current navigation.
+ *
+ * Called from <Link>'s click handler before router.navigate().
+ * - Resets the previous pending link to IDLE (urgent update, immediate)
+ * - Does NOT set the new link to PENDING here — the Link's click handler
+ *   calls setLinkStatus(PENDING) directly for the eager show
+ * - Increments the navId counter for stale-clear protection
+ *
+ * Pass `null` to clear (e.g., for programmatic navigations).
+ */
+export function setLinkForCurrentNavigation(link: LinkPendingInstance | null): void {
+  const store = getStore();
+  const prev = store.current;
+
+  // Reset previous pending link to idle (urgent update — shows immediately)
+  if (prev && prev !== link) {
+    prev.setLinkStatus(IDLE_LINK_STATUS);
+  }
+
+  store.current = link;
+  store.navId++;
+}
+
+/**
+ * Get the current navigation ID. Called at the start of the transition
+ * to capture the ID before async work begins.
+ */
+export function getCurrentNavId(): number {
+  return getStore().navId;
+}
+
+/**
+ * Reset the current link's pending state to IDLE, but only if the navId
+ * matches. Called inside NavigationRoot's startTransition after the async
+ * work completes — the setter call is a transition update, so it commits
+ * atomically with the new tree.
+ *
+ * The navId guard prevents stale transitions from clearing a newer
+ * navigation's pending state. Scenario:
+ *   Click A → navId=1, T1 starts
+ *   Click B → navId=2, A reset to IDLE, T2 starts
+ *   T1 completes → resetLinkPending(1) → navId is 2, skip ✓
+ *   T2 completes → resetLinkPending(2) → navId is 2, clear ✓
+ */
+export function resetLinkPending(forNavId: number): void {
+  const store = getStore();
+  if (store.navId === forNavId && store.current) {
+    store.current.setLinkStatus(IDLE_LINK_STATUS);
+    store.current = null;
+  }
+}
+
+/**
+ * Clean up the link pending store entirely. Safety net for error paths.
+ */
+export function clearLinkPendingSetter(): void {
+  const store = getStore();
+  store.current = null;
+}
+
+/**
+ * Unmount a link instance from navigation tracking. Called when a Link
+ * component unmounts while it is the current navigation link. Prevents
+ * calling setState on an unmounted component.
+ */
+export function unmountLinkForCurrentNavigation(link: LinkPendingInstance): void {
+  const store = getStore();
+  if (store.current === link) {
+    store.current = null;
+  }
+}