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

package/src/client/global-context.ts

@@ -0,0 +1,31 @@
+/**
+ * createGlobalContext — a React context with a process-wide singleton identity.
+ *
+ * SINGLETON GUARANTEE: Uses globalThis + Symbol.for — same pattern as
+ * NavigationContext. The RSC client bundler can duplicate a module across
+ * chunks (browser-entry graph + client-reference graph). With ESM output,
+ * each chunk gets its own module scope — a bare createContext at module
+ * level would create separate instances per chunk. globalThis guarantees a
+ * single instance regardless of duplication.
+ *
+ * See design/19-client-navigation.md §"Singleton Guarantee via globalThis"
+ */
+
+'use client';
+
+import React from 'react';
+
+export function createGlobalContext<T>(key: string, defaultValue: T): React.Context<T> {
+  const g = globalThis as Record<symbol, unknown>;
+  const sym = Symbol.for(key);
+  const existing = g[sym] as React.Context<T> | undefined;
+  if (existing !== undefined) return existing;
+  if (typeof React.createContext === 'function') {
+    const ctx = React.createContext<T>(defaultValue);
+    g[sym] = ctx;
+    return ctx;
+  }
+  // RSC environment — createContext not available. Return a dummy that
+  // won't be used (the consumers only render on the client / during SSR).
+  return undefined as unknown as React.Context<T>;
+}

package/src/client/history.ts

@@ -1,17 +1,37 @@
 // History Stack — stores RSC payloads by URL for instant back/forward navigation
 // See design/19-client-navigation.md § History Stack
 
-import type { HeadElement } from './head';
+import type { ParamsSource } from '../shared/payload-root.ts';
+import type { SegmentInfo } from '../shared/segment-info.ts';
+import { routerUrlKey } from './router-url.ts';
 
 // ─── Types ───────────────────────────────────────────────────────
 
 export interface HistoryEntry {
   /** The complete segment tree payload at the time of navigation */
   payload: unknown;
-  /** Resolved head elements for this page (title, meta tags). Null for SSR'd initial page. */
-  headElements?: HeadElement[] | null;
-  /** Route params for this page (for useParams). Null for SSR'd initial page. */
-  params?: Record<string, string | string[]> | null;
+  /**
+   * The params that payload published. Replaying the tree republishes them,
+   * because the client owns the provider now and reads it from here
+   * (TIM-1297).
+   *
+   * Stored beside the tree but never *produced* beside it: both come out of
+   * one `splitPayloadRoot` on one decoded root and travel together through
+   * `prepareNavigation`, the only producer of an entry. That is the property
+   * that matters — when they were derived from separate channels, a replay
+   * could restore one route's tree with another route's params (TIM-1037,
+   * TIM-1285).
+   */
+  params: ParamsSource;
+  /**
+   * Segment metadata for this page's route. Restored into the segment cache
+   * on popstate cached replay so the next forward navigation computes a
+   * correct state tree. Without this, the segment cache retains the
+   * *previous* page's segments after back-button, causing the server to
+   * skip segments that aren't mounted — and the partial payload targets
+   * a non-existent outlet.
+   */
+  segmentInfo?: SegmentInfo[] | null;
 }
 
 // ─── History Stack ───────────────────────────────────────────────
@@ -23,24 +43,67 @@ 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.
+ * Entries are keyed by pathname + search in the browser's own spelling
+ * (`routerUrlKey`), whatever spelling a caller passes: an entry stored by
+ * `navigate('/café')` is found by a traversal that reads `/caf%C3%A9` off
+ * the address bar, and `/a?` is `/a` (TIM-1541). Used with the History API
+ * fallback and the Navigation API.
  *
- * Entries persist for the session duration (no expiry) and are cleared
- * when the tab is closed — matching browser back-button behavior.
+ * 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 have no expiry, but only the 50 most recently used URLs are kept
+ * by default. Traversing to an evicted entry fetches a fresh payload.
  */
 export class HistoryStack {
   private entries = new Map<string, HistoryEntry>();
+  private readonly maxEntries: number;
+
+  constructor({ maxEntries = 50 }: { maxEntries?: number } = {}) {
+    if (!Number.isInteger(maxEntries) || maxEntries < 1) {
+      throw new RangeError('HistoryStack maxEntries must be a positive integer');
+    }
+    this.maxEntries = maxEntries;
+  }
 
   push(url: string, entry: HistoryEntry): void {
+    url = routerUrlKey(url);
+    // Push runs when a page becomes current (or hydration seeds it). Promote
+    // replacements too, so the current page always survives overflow.
+    this.entries.delete(url);
     this.entries.set(url, entry);
+    if (this.entries.size > this.maxEntries) {
+      const oldest = this.entries.keys().next();
+      if (!oldest.done) this.entries.delete(oldest.value);
+    }
   }
 
   get(url: string): HistoryEntry | undefined {
-    return this.entries.get(url);
+    url = routerUrlKey(url);
+    const entry = this.entries.get(url);
+    if (entry) {
+      this.entries.delete(url);
+      this.entries.set(url, entry);
+    }
+    return entry;
   }
 
+  /** Presence checks (such as hover prefetch probes) do not promote entries. */
   has(url: string): boolean {
-    return this.entries.has(url);
+    return this.entries.has(routerUrlKey(url));
+  }
+
+  /**
+   * Evict every entry (TIM-1476). Called after a server action that
+   * revalidated data — history entries are equally stale since they replay
+   * on back/forward without a server check. Clearing forces a fresh fetch on
+   * the next traversal.
+   *
+   * The current page's entry goes too. Nothing reads it for anything but a
+   * replay: the segment metadata a revalidation needs is the committer's
+   * record of the current page, not this stack's (TIM-1541).
+   */
+  clear(): void {
+    this.entries.clear();
   }
 }

package/src/client/index.ts

@@ -1,64 +1,100 @@
 // @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.
 
 // 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 { 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 { useSelectedLayoutSegment, useSelectedLayoutSegments } from './use-selected-layout-segment';
+export { Link, interpolateParams, resolveHref, validateLinkHref, buildLinkProps } from './link.tsx';
+export { mergePreservedSearchParams } from '../shared/merge-search-params.ts';
+export type { LinkProps, LinkPropsWithHref, LinkPropsWithParams, LinkBaseProps } from './link.tsx';
+export type { LinkSegmentParams, OnNavigateHandler, OnNavigateEvent } from './link.tsx';
 
-// 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';
+// ─── 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.ts';
+export { useLinkStatus, LinkStatusContext } from './use-link-status.ts';
+export type { LinkStatus } from './use-link-status.ts';
+export { useRouter } from './use-router.ts';
+export type { AppRouterInstance, NavigateOptions } from './use-router.ts';
+export type { NavigationTransitionType } from './router-types.ts';
+export { usePathname } from './use-pathname.ts';
+export { replaceUrl } from './shallow-url.ts';
+// useSearchParams removed from public exports — lives in next/navigation shim only.
+export {
+  useSelectedLayoutSegment,
+  useSelectedLayoutSegments,
+} from './use-selected-layout-segment.ts';
 
 // Forms
-export { useActionState, useFormAction, useFormErrors } from './form';
-export type { UseActionStateFn, UseActionStateReturn, FormErrorsResult } from './form';
-
-// Params
-export { useParams, setCurrentParams } from './use-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 (URL-synced search params)
-export { useQueryStates, bindUseQueryStates } from './use-query-states';
+export { useActionState, useFormAction } from './form.tsx';
+export type { UseActionStateFn, UseActionStateReturn, FormErrorsResult } from './form.tsx';
 
-// Cookies
-export { useCookie } from './use-cookie';
-export type { ClientCookieOptions, CookieSetter } from './use-cookie';
+// Params. Called with no argument this returns the untyped accumulated params;
+// pass the route's SEGMENT_PATH (from its generated `./$segment` module) to get
+// the exact types `app/schema.ts` declares — `useSegmentParams(SEGMENT_PATH)`.
+export { useSegmentParams } from './use-segment-params.ts';
 
-// 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';
+// Query states. `definition.useQueryStates()` is the usual form; this standalone
+// export is the inline codec-map form, for shared param bundles reused across
+// routes (design/23-search-params.md §"Client Access").
+//
+// Until TIM-1341 this export did not exist, yet four doc sites told users to
+// import it from here. It type-checked only because the generated `.d.ts`
+// augmented this module with a `useQueryStates` overload — so TypeScript
+// believed in a binding that was never emitted, and the documented import
+// failed at build time. Deleting that overload removed the lie; exporting the
+// hook makes the docs true.
+export { useQueryStates } from './use-query-states.ts';
 
-// Error boundary (framework-internal, used by tree-builder and rsc-entry)
-export { TimberErrorBoundary } from './error-boundary';
-export type { TimberErrorBoundaryProps } from './error-boundary';
+// Cookies — useCookie lives on defineCookie().useCookie().
+// Types still exported for advanced use.
+export type { ClientCookieOptions, CookieSetter } from './use-cookie.ts';

package/src/client/internal.ts

@@ -0,0 +1,54 @@
+// #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.ts';
+export type {
+  RouterInstance,
+  NavigationOptions,
+  RouterDeps,
+  RouterPhase,
+  RscDecoder,
+} from './router-types.ts';
+export { getRouter, getRouterOrNull, setGlobalRouter } from './router-ref.ts';
+export type { NavigationEpoch } from './router-lifecycle.ts';
+
+// ── SSR bridge ───────────────────────────────────────────────────────────
+export { registerSsrDataProvider, getSsrData } from './ssr-data.ts';
+export type { SsrData } from './ssr-data.ts';
+
+// ── Segment context ──────────────────────────────────────────────────────
+export { SegmentProvider, useSegmentContext } from './segment-context.ts';
+export type { SegmentContextValue } from './segment-context.ts';
+
+// ── Segment cache ────────────────────────────────────────────────────────
+export { SegmentCache, PrefetchCache } from './segment-cache.ts';
+export type { SegmentNode, PrefetchKey } from './segment-cache.ts';
+export type { SegmentInfo, StateTree } from '../shared/segment-info.ts';
+
+// ── History ──────────────────────────────────────────────────────────────
+export { HistoryStack } from './history.ts';
+export type { HistoryEntry } from './history.ts';
+
+// ── Params (raw hooks) ───────────────────────────────────────────────────
+export { useSearchParams } from './use-search-params.ts';
+
+// ── Navigation context ───────────────────────────────────────────────────
+export { NavigationProvider } from './navigation-context.ts';
+export type { NavigationState } from './navigation-context.ts';
+
+// ── Query states (internal binder) ───────────────────────────────────────
+export { bindUseQueryStates } from './use-query-states.ts';
+
+// ── Error boundary ───────────────────────────────────────────────────────
+export { TimberErrorBoundary } from './error-boundary.tsx';
+export type { TimberErrorBoundaryProps } from './error-boundary.tsx';