@timber-js/app 0.2.0-alpha.185 → 0.2.0-alpha.187

package/src/client/router-skew.ts

@@ -0,0 +1,30 @@
+/**
+ * Router Skew Recording — turning a rejection into "this bundle is superseded".
+ *
+ * Detection lives in `stale-client.ts`; this is the one place the router (and
+ * anything else holding an RSC rejection) turns an error into that verdict.
+ * Recovery is not here: every path that gives up on client-side navigation —
+ * skew or not — leaves through `createSpaExits()` in `router-effects.ts`.
+ *
+ * See design/33-version-skew.md §"Recovery on the next navigation"
+ */
+
+import { VersionSkewError } from './rsc-fetch.js';
+import { markClientStale, markStaleFromError } from './stale-client.js';
+
+/**
+ * Record a version skew if `error` is one, and report whether it was.
+ *
+ * `VersionSkewError` is the origin saying so outright; the reactive shapes are
+ * inferred from the error text and are a no-op in dev.
+ *
+ * Closes over nothing — anywhere an RSC payload can fail needs it, including
+ * places that have no router instance to hand.
+ */
+export function recordSkew(error: unknown): boolean {
+  if (error instanceof VersionSkewError) {
+    markClientStale();
+    return true;
+  }
+  return markStaleFromError(error);
+}

package/src/client/router-types.ts

@@ -0,0 +1,230 @@
+/**
+ * Router Types — the router's surface, stated once.
+ *
+ * Split out of `router.ts` so the factory file is navigation logic rather than
+ * declarations (design/18-build-system.md §"No file >500 lines"), and because
+ * `rsc-fetch.ts` needs `RouterDeps` while `router.ts` needs `FetchResult`:
+ * with the types here, neither imports the other.
+ *
+ * See design/19-client-navigation.md for the architecture these describe.
+ */
+
+import type { NavigationState } from './navigation-context.js';
+import type { ParamsSource } from '../shared/payload-root.js';
+import type { SegmentInfo } from '../shared/segment-info.js';
+import type { SegmentCache, PrefetchCache } from './segment-cache.js';
+import type { HistoryStack } from './history.js';
+import type { TransitionResult } from './navigation-root.js';
+
+export interface NavigationOptions {
+  /** Set to false to prevent scroll-to-top on forward navigation */
+  scroll?: boolean;
+  /** Use replaceState instead of pushState (replaces current history entry) */
+  replace?: boolean;
+  /**
+   * @internal AbortSignal from the Navigation API's NavigateEvent.
+   * When provided, the signal is linked to the router's per-navigation
+   * AbortController so in-flight RSC fetches are cancelled when a new
+   * navigation starts.
+   */
+  _signal?: AbortSignal;
+  /**
+   * @internal Skip pushState/replaceState — the Navigation API has already
+   * updated the URL via event.intercept(). Used for external navigations
+   * intercepted by the navigate event handler.
+   */
+  _skipHistory?: boolean;
+  /**
+   * @internal The URL the user is navigating FROM, captured before the
+   * Navigation API commits the destination. Sent as X-Timber-URL for
+   * slot skip comparison on the server (TIM-1232).
+   */
+  _departingUrl?: string;
+}
+
+/**
+ * Function that decodes an RSC Flight stream into a React element tree.
+ * In production: createFromFetch from @vitejs/plugin-rsc/browser.
+ * In tests: a mock that returns the raw payload.
+ */
+export type RscDecoder = (fetchPromise: Promise<Response>) => unknown;
+
+/**
+ * Function that renders a decoded RSC element tree into the DOM.
+ * In production: reactRoot.render(element).
+ * In tests: a no-op or mock.
+ *
+ * Receives the current NavigationState explicitly — no temporal
+ * coupling with setNavigationState/getNavigationState. The renderer
+ * wraps the element in NavigationProvider with this state.
+ */
+export type RootRenderer = (
+  element: unknown,
+  navState: NavigationState,
+  params: ParamsSource
+) => void;
+
+/**
+ * Platform dependencies injected for testability. In production these
+ * map to browser APIs; in tests they're replaced with mocks.
+ */
+export interface RouterDeps {
+  fetch: (url: string, init: RequestInit) => Promise<Response>;
+  pushState: (data: unknown, unused: string, url: string) => void;
+  replaceState: (data: unknown, unused: string, url: string) => void;
+  scrollTo: (x: number, y: number) => void;
+  getCurrentUrl: () => string;
+  getScrollY: () => number;
+  /** Decode RSC Flight stream into React elements. If not provided, raw response text is stored. */
+  decodeRsc?: RscDecoder;
+  /** Render decoded RSC tree into the DOM. If not provided, rendering is a no-op. */
+  renderRoot?: RootRenderer;
+  /**
+   * Schedule a callback after the next paint. In the browser, this is
+   * requestAnimationFrame + setTimeout(0) to run after React commits.
+   * In tests, this runs the callback synchronously.
+   */
+  afterPaint?: (callback: () => void) => void;
+  /**
+   * Hand a navigation's tree to React in a transition, so the departing page
+   * stays visible while the destination resolves. Pending state is not React
+   * state — it lives in this router's external store (`setPending`), which
+   * `TopLoader` and `usePendingNavigation()` subscribe to (TIM-1307).
+   *
+   * The `perform` callback receives a `wrapPayload` function to wrap the
+   * decoded RSC payload with NavigationProvider + NuqsAdapter before
+   * NavigationRoot sets it as the new element. The `wrapPayload` function
+   * receives the NavigationState explicitly — no temporal coupling with
+   * getNavigationState().
+   *
+   * If not provided (tests), the router falls back to renderRoot.
+   */
+  navigateTransition?: (
+    pendingUrl: string,
+    perform: (
+      wrapPayload: (
+        payload: unknown,
+        navState: NavigationState,
+        /**
+         * The params to publish over `payload`. On a partial navigation
+         * `payload` is the *retained* tree and these are the *incoming*
+         * route's — the two deliberately come from different payloads,
+         * which is the entire point of the client owning the provider
+         * (TIM-1297).
+         */
+        params: ParamsSource,
+        segmentUpdates?: Map<string, unknown>
+      ) => unknown
+    ) => Promise<TransitionResult<unknown>>
+  ) => Promise<void>;
+
+  /**
+   * Whether the Navigation API is active and handling traversals.
+   * When true, the popstate handler is a no-op — the Navigation API's
+   * navigate event covers back/forward button presses.
+   */
+  navigationApiActive?: boolean;
+
+  /**
+   * Called around pushState/replaceState to set a flag that prevents
+   * the Navigation API's navigate listener from double-handling
+   * router-initiated navigations.
+   */
+  setRouterNavigating?: (value: boolean) => void;
+
+  /**
+   * Save scroll position via the Navigation API's per-entry state.
+   * When provided, used instead of history.replaceState for scroll storage.
+   */
+  saveNavigationEntryScroll?: (scrollY: number) => void;
+
+  /**
+   * Signal that a router-initiated navigation has completed. Resolves the
+   * deferred promise that ties the browser's native loading state to the
+   * navigation lifecycle. Called in the finally block of navigate/refresh,
+   * the same place `setPending(false)` clears the TopLoader.
+   */
+  completeRouterNavigation?: () => void;
+
+  /**
+   * Get the current unwrapped RSC payload element. Used for partial
+   * navigation: the router re-wraps the same element with new
+   * NavigationProvider context so mounted SegmentOutlets are preserved.
+   */
+  _getCurrentPayload?: () => unknown;
+
+  /**
+   * Initiate a navigation via the Navigation API (`navigation.navigate()`).
+   * Fires the navigate event BEFORE committing the URL, allowing Chrome
+   * to show its native loading indicator. Falls back to pushState when
+   * unavailable.
+   */
+  navigationNavigate?: (url: string, replace: boolean) => void;
+
+  /**
+   * Scroll the element matching a URL #fragment into view. Returns true
+   * when a matching element was found and scrolled. When absent or false,
+   * the router falls back to scroll-to-top on forward navigation — same
+   * as a full page load with an unknown fragment landing at the top.
+   */
+  scrollToHash?: (hash: string) => boolean;
+
+  /**
+   * Whether the client segment cache is enabled. When false (the default),
+   * the router sends no segment/slot lists, so every navigation gets a full
+   * RSC payload.
+   *
+   * It does NOT gate the `treePaths` half of X-Timber-State-Tree. Those
+   * describe the tree currently mounted, and interception scoping needs them
+   * to open a modal on top of a modal — a routing behaviour, not a caching
+   * optimization, so it must not depend on a performance opt-in (TIM-1282).
+   */
+  clientSegmentCache?: boolean;
+}
+
+export interface RouterInstance {
+  /** Navigate to a new URL (forward navigation) */
+  navigate(url: string, options?: NavigationOptions): Promise<void>;
+  /** Full re-render of the current URL — no state tree sent */
+  refresh(): Promise<void>;
+  /** Handle a popstate event (back/forward button). scrollY is read from history.state. */
+  handlePopState(url: string, scrollY?: number, externalSignal?: AbortSignal): Promise<void>;
+  /** Whether a navigation is currently in flight */
+  isPending(): boolean;
+  /** The URL currently being navigated to, or null if idle */
+  getPendingUrl(): string | null;
+  /** Subscribe to pending state changes */
+  onPendingChange(listener: (pending: boolean) => void): () => void;
+  /** Prefetch an RSC payload for a URL (used by Link hover) */
+  prefetch(url: string): void;
+  /**
+   * Apply a piggybacked revalidation payload from a server action response.
+   * Takes the decoded payload *root* — tree plus the params it published —
+   * and renders it without a server fetch.
+   * See design/08-forms-and-actions.md §"Single-Roundtrip Revalidation".
+   */
+  applyRevalidation(payloadRoot: unknown): void;
+  /**
+   * Populate the segment cache from server-provided segment metadata.
+   * Called on initial hydration with segment info embedded in the HTML.
+   */
+  initSegmentCache(segments: SegmentInfo[]): void;
+
+  /** The segment cache (exposed for tests and <Link> prefetch) */
+  segmentCache: SegmentCache;
+  /** The prefetch cache (exposed for tests and <Link> prefetch) */
+  prefetchCache: PrefetchCache;
+  /** The history stack (exposed for tests) */
+  historyStack: HistoryStack;
+}
+
+/**
+ * Router navigation phase — discriminated union replacing scattered
+ * `pending` + `pendingUrl` boolean flags.
+ *
+ * - `idle`: No navigation in flight. The committed params/pathname
+ *   are current.
+ * - `navigating`: A fetch or render is in progress. `targetUrl` is
+ *   the destination being navigated to.
+ */
+export type RouterPhase = { phase: 'idle' } | { phase: 'navigating'; targetUrl: string };