@timber-js/app 0.1.1 → 0.1.3

package/src/client/segment-cache.ts

@@ -0,0 +1,194 @@
+// Segment Cache — stores the mounted segment tree and prefetched payloads
+// See design/19-client-navigation.md for architecture details.
+
+import type { HeadElement } from './head';
+
+// ─── Types ───────────────────────────────────────────────────────
+
+/** A prefetched RSC result with optional head elements and segment metadata. */
+export interface PrefetchResult {
+  payload: unknown;
+  headElements: HeadElement[] | null;
+  /** Segment metadata from X-Timber-Segments header for populating the segment cache. */
+  segmentInfo?: SegmentInfo[] | null;
+  /** Route params from X-Timber-Params header for populating useParams(). */
+  params?: Record<string, string | string[]> | null;
+}
+
+/**
+ * A node in the client-side segment tree. Each node represents a mounted
+ * layout or page segment with its RSC flight payload.
+ */
+export interface SegmentNode {
+  /** The segment's URL pattern (e.g., "/", "/dashboard", "/projects/[id]") */
+  segment: string;
+  /** The RSC flight payload for this segment (opaque to the cache) */
+  payload: unknown;
+  /** Whether the segment is async (async layouts always re-render on navigation) */
+  isAsync: boolean;
+  /** Child segments keyed by segment path */
+  children: Map<string, SegmentNode>;
+}
+
+/**
+ * Serialized state tree sent via X-Timber-State-Tree header.
+ * Only sync segments are included — async segments always re-render.
+ */
+export interface StateTree {
+  segments: string[];
+}
+
+// ─── Segment Cache ───────────────────────────────────────────────
+
+/**
+ * Maintains the client-side segment tree representing currently mounted
+ * layouts and pages. Used for navigation reconciliation — the router diffs
+ * new routes against this tree to determine which segments to re-fetch.
+ */
+export class SegmentCache {
+  private root: SegmentNode | undefined;
+
+  get(segment: string): SegmentNode | undefined {
+    if (segment === '/' || segment === this.root?.segment) {
+      return this.root;
+    }
+    return undefined;
+  }
+
+  set(segment: string, node: SegmentNode): void {
+    if (segment === '/' || !this.root) {
+      this.root = node;
+    }
+  }
+
+  clear(): void {
+    this.root = undefined;
+  }
+
+  /**
+   * Serialize the mounted segment tree for the X-Timber-State-Tree header.
+   * Only includes sync segments — async segments are excluded because the
+   * server must always re-render them (they may depend on request context).
+   *
+   * This is a performance optimization only, NOT a security boundary.
+   * The server always runs all access.ts files regardless of the state tree.
+   */
+  serializeStateTree(): StateTree {
+    const segments: string[] = [];
+    if (this.root) {
+      collectSyncSegments(this.root, segments);
+    }
+    return { segments };
+  }
+}
+
+/** Recursively collect sync segment paths from the tree */
+function collectSyncSegments(node: SegmentNode, out: string[]): void {
+  if (!node.isAsync) {
+    out.push(node.segment);
+  }
+  for (const child of node.children.values()) {
+    collectSyncSegments(child, out);
+  }
+}
+
+// ─── Segment Tree Builder ────────────────────────────────────────
+
+/**
+ * Segment metadata from the server, sent via X-Timber-Segments header.
+ * Describes a rendered segment's path and whether it's async.
+ */
+export interface SegmentInfo {
+  path: string;
+  isAsync: boolean;
+}
+
+/**
+ * Build a SegmentNode tree from flat segment metadata.
+ *
+ * Takes an ordered list of segment descriptors (root → leaf) from the
+ * server's X-Timber-Segments header and constructs the hierarchical
+ * tree structure that SegmentCache expects.
+ *
+ * Each segment is nested as a child of the previous one, forming a
+ * linear chain from root to leaf. The leaf segment (page) is excluded
+ * from the tree — pages are never cached across navigations.
+ */
+export function buildSegmentTree(segments: SegmentInfo[]): SegmentNode | undefined {
+  // Need at least a root segment to build a tree
+  if (segments.length === 0) return undefined;
+
+  // Exclude the leaf (page) — pages always re-render on navigation.
+  // Only layouts are cached in the segment tree.
+  const layouts = segments.length > 1 ? segments.slice(0, -1) : segments;
+
+  let root: SegmentNode | undefined;
+  let parent: SegmentNode | undefined;
+
+  for (const info of layouts) {
+    const node: SegmentNode = {
+      segment: info.path,
+      payload: null,
+      isAsync: info.isAsync,
+      children: new Map(),
+    };
+
+    if (!root) {
+      root = node;
+    }
+
+    if (parent) {
+      parent.children.set(info.path, node);
+    }
+
+    parent = node;
+  }
+
+  return root;
+}
+
+// ─── Prefetch Cache ──────────────────────────────────────────────
+
+interface PrefetchEntry {
+  result: PrefetchResult;
+  expiresAt: number;
+}
+
+/**
+ * Short-lived cache for hover-triggered prefetches. Entries expire after
+ * 30 seconds. When a link is clicked, the prefetched payload is consumed
+ * (moved to the history stack) and removed from this cache.
+ *
+ * timber.js does NOT prefetch on viewport intersection — only explicit
+ * hover on <Link prefetch> triggers a prefetch.
+ */
+export class PrefetchCache {
+  private static readonly TTL_MS = 30_000;
+  private entries = new Map<string, PrefetchEntry>();
+
+  set(url: string, result: PrefetchResult): void {
+    this.entries.set(url, {
+      result,
+      expiresAt: Date.now() + PrefetchCache.TTL_MS,
+    });
+  }
+
+  get(url: string): PrefetchResult | undefined {
+    const entry = this.entries.get(url);
+    if (!entry) return undefined;
+    if (Date.now() >= entry.expiresAt) {
+      this.entries.delete(url);
+      return undefined;
+    }
+    return entry.result;
+  }
+
+  /** Get and remove the entry (used when navigation consumes a prefetch) */
+  consume(url: string): PrefetchResult | undefined {
+    const result = this.get(url);
+    if (result !== undefined) {
+      this.entries.delete(url);
+    }
+    return result;
+  }
+}

package/src/client/segment-context.ts

@@ -0,0 +1,57 @@
+/**
+ * Segment Context — provides layout segment position for useSelectedLayoutSegment hooks.
+ *
+ * Each layout in the segment tree is wrapped with a SegmentProvider that stores
+ * the URL segments from root to the current layout level. The hooks read this
+ * context to determine which child segments are active below the calling layout.
+ *
+ * The context value is intentionally minimal: just the segment path array and
+ * parallel route keys. No internal cache details are exposed.
+ *
+ * Design docs: design/19-client-navigation.md, design/14-ecosystem.md
+ */
+
+'use client';
+
+import { createContext, useContext, createElement, useMemo } from 'react';
+
+// ─── Types ───────────────────────────────────────────────────────
+
+export interface SegmentContextValue {
+  /** URL segments from root to this layout (e.g. ['', 'dashboard', 'settings']) */
+  segments: string[];
+  /** Parallel route slot keys available at this layout level (e.g. ['sidebar', 'modal']) */
+  parallelRouteKeys: string[];
+}
+
+// ─── Context ─────────────────────────────────────────────────────
+
+const SegmentContext = createContext<SegmentContextValue | null>(null);
+
+/** Read the segment context. Returns null if no provider is above this component. */
+export function useSegmentContext(): SegmentContextValue | null {
+  return useContext(SegmentContext);
+}
+
+// ─── Provider ────────────────────────────────────────────────────
+
+interface SegmentProviderProps {
+  segments: string[];
+  parallelRouteKeys: string[];
+  children: React.ReactNode;
+}
+
+/**
+ * Wraps each layout to provide segment position context.
+ * Injected by rsc-entry.ts during element tree construction.
+ */
+export function SegmentProvider({ segments, parallelRouteKeys, children }: SegmentProviderProps) {
+  const value = useMemo(
+    () => ({ segments, parallelRouteKeys }),
+    // segments and parallelRouteKeys are static per layout — they don't change
+    // across navigations. The layout's position in the tree is fixed.
+    // Intentionally using derived keys — segments/parallelRouteKeys are static per layout
+    [segments.join('/'), parallelRouteKeys.join(',')]
+  );
+  return createElement(SegmentContext.Provider, { value }, children);
+}

package/src/client/ssr-data.ts

@@ -0,0 +1,95 @@
+/**
+ * SSR Data — per-request state for client hooks during server-side rendering.
+ *
+ * RSC and SSR are separate Vite module graphs (see design/18-build-system.md),
+ * so the RSC environment's request-context ALS is not visible to SSR modules.
+ * This module provides getter/setter functions that ssr-entry.ts uses to
+ * populate per-request data for React's render.
+ *
+ * Request isolation: On the server, ssr-entry.ts registers an ALS-backed
+ * provider via registerSsrDataProvider(). getSsrData() reads from the ALS
+ * store, ensuring correct per-request data even when Suspense boundaries
+ * resolve asynchronously across concurrent requests. The module-level
+ * setSsrData/clearSsrData functions are kept as a fallback for tests
+ * and environments without ALS.
+ *
+ * IMPORTANT: This module must NOT import node:async_hooks or any Node.js-only
+ * APIs, as it's imported by 'use client' hooks that are bundled for the browser.
+ * The ALS instance lives in ssr-entry.ts (server-only); this module only holds
+ * a reference to the provider function.
+ */
+
+// ─── Types ────────────────────────────────────────────────────────
+
+export interface SsrData {
+  /** The request's URL pathname (e.g. '/dashboard/settings') */
+  pathname: string;
+  /** The request's search params as a plain record */
+  searchParams: Record<string, string>;
+  /** The request's cookies as name→value pairs */
+  cookies: Map<string, string>;
+  /** The request's route params (e.g. { id: '123' }) */
+  params: Record<string, string | string[]>;
+}
+
+// ─── ALS-Backed Provider ─────────────────────────────────────────
+//
+// Server-side code (ssr-entry.ts) registers a provider that reads
+// from AsyncLocalStorage. This avoids importing node:async_hooks
+// in this browser-bundled module.
+
+let _ssrDataProvider: (() => SsrData | undefined) | undefined;
+
+/**
+ * Register an ALS-backed SSR data provider. Called once at module load
+ * by ssr-entry.ts to wire up per-request data via AsyncLocalStorage.
+ *
+ * When registered, getSsrData() reads from the provider (ALS store)
+ * instead of module-level state, ensuring correct isolation for
+ * concurrent requests with streaming Suspense.
+ */
+export function registerSsrDataProvider(provider: () => SsrData | undefined): void {
+  _ssrDataProvider = provider;
+}
+
+// ─── Module-Level Fallback ────────────────────────────────────────
+//
+// Used by tests and as a fallback when no ALS provider is registered.
+
+let currentSsrData: SsrData | undefined;
+
+/**
+ * Set the SSR data for the current request via module-level state.
+ *
+ * In production, ssr-entry.ts uses ALS (runWithSsrData) instead.
+ * This function is retained for tests and as a fallback.
+ */
+export function setSsrData(data: SsrData): void {
+  currentSsrData = data;
+}
+
+/**
+ * Clear the SSR data after rendering completes.
+ *
+ * In production, ALS scope handles cleanup automatically.
+ * This function is retained for tests and as a fallback.
+ */
+export function clearSsrData(): void {
+  currentSsrData = undefined;
+}
+
+/**
+ * Read the current request's SSR data. Returns undefined when called
+ * outside an SSR render (i.e. on the client after hydration).
+ *
+ * Prefers the ALS-backed provider when registered (server-side),
+ * falling back to module-level state (tests, legacy).
+ *
+ * Used by client hooks' server snapshot functions.
+ */
+export function getSsrData(): SsrData | undefined {
+  if (_ssrDataProvider) {
+    return _ssrDataProvider();
+  }
+  return currentSsrData;
+}

package/src/client/types.ts

@@ -0,0 +1,4 @@
+export interface RenderErrorDigest<Code extends string = string, Data = unknown> {
+  code: Code;
+  data: Data;
+}

package/src/client/unload-guard.ts

@@ -0,0 +1,34 @@
+/**
+ * Page unload detection — suppresses spurious errors during page refresh/navigation.
+ *
+ * When the user refreshes the page or navigates away while React is still
+ * streaming Suspense content, the aborted connection causes streaming errors.
+ * These are not application errors — they're a side effect of the browser
+ * tearing down the connection. This module tracks whether the page is being
+ * unloaded so error boundaries and error handlers can suppress abort-related
+ * errors during the unload window.
+ *
+ * See design/10-error-handling.md §"Known limitation: deny() inside Suspense and hydration"
+ */
+
+let unloading = false;
+
+if (typeof window !== 'undefined') {
+  window.addEventListener('beforeunload', () => {
+    unloading = true;
+  });
+
+  // Also detect pagehide for bfcache-aware browsers (Safari).
+  // pagehide fires for both navigations and page hide events.
+  window.addEventListener('pagehide', () => {
+    unloading = true;
+  });
+}
+
+/**
+ * Returns true if the page is currently being unloaded (user refreshed
+ * or navigated away). Error boundaries should suppress errors in this state.
+ */
+export function isPageUnloading(): boolean {
+  return unloading;
+}

package/src/client/use-cookie.ts

@@ -0,0 +1,122 @@
+/**
+ * useCookie — reactive client-side cookie hook.
+ *
+ * Uses useSyncExternalStore for SSR-safe, reactive cookie access.
+ * All components reading the same cookie name re-render on change.
+ * No cross-tab sync (intentional — see design/29-cookies.md).
+ *
+ * See design/29-cookies.md §"useCookie(name) Hook"
+ */
+
+import { useSyncExternalStore } from 'react';
+import { getSsrData } from './ssr-data.js';
+
+// ─── Types ────────────────────────────────────────────────────────────────
+
+export interface ClientCookieOptions {
+  /** URL path scope. Default: '/'. */
+  path?: string;
+  /** Domain scope. Default: omitted (current domain). */
+  domain?: string;
+  /** Max age in seconds. */
+  maxAge?: number;
+  /** Expiration date. */
+  expires?: Date;
+  /** Cross-site policy. Default: 'lax'. */
+  sameSite?: 'strict' | 'lax' | 'none';
+  /** Only send over HTTPS. Default: true in production. */
+  secure?: boolean;
+}
+
+export type CookieSetter = (value: string, options?: ClientCookieOptions) => void;
+
+// ─── Module-Level Cookie Store ────────────────────────────────────────────
+
+type Listener = () => void;
+
+/** Per-name subscriber sets. */
+const listeners = new Map<string, Set<Listener>>();
+
+/** Parse a cookie name from document.cookie. */
+function getCookieValue(name: string): string | undefined {
+  if (typeof document === 'undefined') return undefined;
+  const match = document.cookie.match(
+    new RegExp('(?:^|;\\s*)' + name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '\\s*=\\s*([^;]*)')
+  );
+  return match ? decodeURIComponent(match[1]) : undefined;
+}
+
+/** Serialize options into a cookie string suffix. */
+function serializeOptions(options?: ClientCookieOptions): string {
+  if (!options) return '; Path=/; SameSite=Lax';
+  const parts: string[] = [];
+  parts.push(`Path=${options.path ?? '/'}`);
+  if (options.domain) parts.push(`Domain=${options.domain}`);
+  if (options.maxAge !== undefined) parts.push(`Max-Age=${options.maxAge}`);
+  if (options.expires) parts.push(`Expires=${options.expires.toUTCString()}`);
+  const sameSite = options.sameSite ?? 'lax';
+  parts.push(`SameSite=${sameSite.charAt(0).toUpperCase()}${sameSite.slice(1)}`);
+  if (options.secure) parts.push('Secure');
+  return '; ' + parts.join('; ');
+}
+
+/** Notify all subscribers for a given cookie name. */
+function notify(name: string): void {
+  const subs = listeners.get(name);
+  if (subs) {
+    for (const fn of subs) fn();
+  }
+}
+
+// ─── Hook ─────────────────────────────────────────────────────────────────
+
+/**
+ * Reactive hook for reading/writing a client-side cookie.
+ *
+ * Returns `[value, setCookie, deleteCookie]`:
+ * - `value`: current cookie value (string | undefined)
+ * - `setCookie`: sets the cookie and triggers re-renders
+ * - `deleteCookie`: deletes the cookie and triggers re-renders
+ *
+ * @param name - Cookie name.
+ * @param defaultOptions - Default options for setCookie calls.
+ */
+export function useCookie(
+  name: string,
+  defaultOptions?: ClientCookieOptions
+): [value: string | undefined, setCookie: CookieSetter, deleteCookie: () => void] {
+  const subscribe = (callback: Listener): (() => void) => {
+    let subs = listeners.get(name);
+    if (!subs) {
+      subs = new Set();
+      listeners.set(name, subs);
+    }
+    subs.add(callback);
+    return () => {
+      subs!.delete(callback);
+      if (subs!.size === 0) listeners.delete(name);
+    };
+  };
+
+  const getSnapshot = (): string | undefined => getCookieValue(name);
+  const getServerSnapshot = (): string | undefined => getSsrData()?.cookies.get(name);
+
+  const value = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+
+  const setCookie: CookieSetter = (newValue: string, options?: ClientCookieOptions) => {
+    const merged = { ...defaultOptions, ...options };
+    document.cookie = `${name}=${encodeURIComponent(newValue)}${serializeOptions(merged)}`;
+    notify(name);
+  };
+
+  const deleteCookie = (): void => {
+    const path = defaultOptions?.path ?? '/';
+    const domain = defaultOptions?.domain;
+    let cookieStr = `${name}=; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=${path}`;
+    if (domain) cookieStr += `; Domain=${domain}`;
+    document.cookie = cookieStr;
+    notify(name);
+  };
+
+  return [value, setCookie, deleteCookie];
+}

package/src/client/use-link-status.ts

@@ -0,0 +1,46 @@
+'use client';
+
+// useLinkStatus — returns { pending: true } while the nearest parent <Link>'s
+// navigation is in flight. No arguments — scoped via React context.
+// See design/19-client-navigation.md §"useLinkStatus()"
+
+import { useContext, createContext } from 'react';
+
+export interface LinkStatus {
+  pending: boolean;
+}
+
+/**
+ * React context provided by <Link>. Holds the pending status
+ * for that specific link's navigation.
+ */
+export const LinkStatusContext = createContext<LinkStatus>({ pending: false });
+
+/**
+ * Returns `{ pending: true }` while the nearest parent `<Link>` component's
+ * navigation is in flight. Must be used inside a `<Link>` component's children.
+ *
+ * Unlike `useNavigationPending()` which is global, this hook is scoped to
+ * the nearest parent `<Link>` — only the link the user clicked shows pending.
+ *
+ * ```tsx
+ * 'use client'
+ * import { Link, useLinkStatus } from '@timber/app/client'
+ *
+ * function Hint() {
+ *   const { pending } = useLinkStatus()
+ *   return <span className={pending ? 'opacity-50' : ''} />
+ * }
+ *
+ * export function NavLink({ href, children }) {
+ *   return (
+ *     <Link href={href}>
+ *       {children} <Hint />
+ *     </Link>
+ *   )
+ * }
+ * ```
+ */
+export function useLinkStatus(): LinkStatus {
+  return useContext(LinkStatusContext);
+}

package/src/client/use-navigation-pending.ts

@@ -0,0 +1,47 @@
+// useNavigationPending — returns true while an RSC navigation is in flight.
+// See design/19-client-navigation.md §"useNavigationPending()"
+
+import { useSyncExternalStore } from 'react';
+import { getRouter } from './router-ref.js';
+
+/**
+ * Returns true while an RSC navigation is in flight.
+ *
+ * The pending state is true from the moment the RSC fetch starts until
+ * React reconciliation completes. This includes the fetch itself,
+ * RSC stream parsing, and React tree reconciliation.
+ *
+ * It does NOT include Suspense streaming after the shell — only the
+ * initial shell reconciliation.
+ *
+ * ```tsx
+ * 'use client'
+ * import { useNavigationPending } from '@timber/app/client'
+ *
+ * export function NavBar() {
+ *   const isPending = useNavigationPending()
+ *   return (
+ *     <nav className={isPending ? 'opacity-50' : ''}>
+ *       <Link href="/dashboard">Dashboard</Link>
+ *     </nav>
+ *   )
+ * }
+ * ```
+ */
+export function useNavigationPending(): boolean {
+  return useSyncExternalStore(
+    (callback) => {
+      const router = getRouter();
+      return router.onPendingChange(callback);
+    },
+    () => {
+      try {
+        return getRouter().isPending();
+      } catch {
+        return false;
+      }
+    },
+    // Server snapshot — always false during SSR
+    () => false
+  );
+}

package/src/client/use-params.ts

@@ -0,0 +1,71 @@
+/**
+ * useParams() — client-side hook for accessing route params.
+ *
+ * Returns the dynamic route parameters for the current URL.
+ * When called with a route pattern argument, TypeScript narrows
+ * the return type to the exact params shape for that route.
+ *
+ * Two layers of type narrowing work together:
+ * 1. The generic overload here uses the Routes interface directly —
+ *    `useParams<R>()` returns `Routes[R]['params']`.
+ * 2. Build-time codegen generates per-route string-literal overloads
+ *    in the .d.ts file for IDE autocomplete (see routing/codegen.ts).
+ *
+ * When the Routes interface is empty (no codegen yet), the generic
+ * overload has `keyof Routes = never`, so only the fallback matches.
+ *
+ * During SSR, params are read from the ALS-backed SSR data context
+ * (populated by ssr-entry.ts) to ensure correct per-request isolation
+ * across concurrent requests with streaming Suspense.
+ *
+ * Design doc: design/09-typescript.md §"Typed Routes"
+ */
+
+import type { Routes } from '#/index.js';
+import { getSsrData } from './ssr-data.js';
+
+// The current params are set by the framework during navigation.
+// In production, this is populated by the segment router when it
+// processes an RSC payload and extracts the matched route params.
+// During SSR, params are read from getSsrData() instead (ALS-backed).
+let currentParams: Record<string, string | string[]> = {};
+
+/**
+ * Set the current route params. Called by the framework internals
+ * during navigation — not intended for direct use by app code.
+ *
+ * On the client, the segment router calls this on each navigation.
+ * During SSR, params are also available via getSsrData().params
+ * (ALS-backed), but setCurrentParams is still called for the
+ * module-level fallback path.
+ */
+export function setCurrentParams(params: Record<string, string | string[]>): void {
+  currentParams = params;
+}
+
+/**
+ * Read the current route's dynamic params.
+ *
+ * The optional `_route` argument exists only for TypeScript narrowing —
+ * it does not affect the runtime return value.
+ *
+ * During SSR, reads from the ALS-backed SSR data context to ensure
+ * per-request isolation. On the client, reads from module-level state
+ * (set by the segment router on each navigation).
+ *
+ * @overload Typed — when a known route path is passed, returns the
+ *   exact params shape from the generated Routes interface.
+ * @overload Fallback — returns the generic params record.
+ */
+export function useParams<R extends keyof Routes>(route: R): Routes[R]['params'];
+export function useParams(route?: string): Record<string, string | string[]>;
+export function useParams(_route?: string): Record<string, string | string[]> {
+  // During SSR, read from the ALS-backed SSR data context.
+  // This ensures correct params even for components inside Suspense
+  // boundaries that resolve asynchronously across concurrent requests.
+  const ssrData = getSsrData();
+  if (ssrData) {
+    return ssrData.params;
+  }
+  return currentParams;
+}