@timber-js/app 0.2.0-alpha.18 → 0.2.0-alpha.180

package/dist/client/navigation-root.d.ts

@@ -0,0 +1,119 @@
+/**
+ * NavigationRoot — Wrapper component for transition-based rendering.
+ *
+ * Solves the "new boundary has no old content" problem for client-side
+ * navigation. When React renders a completely new Suspense boundary via
+ * root.render(), it shows the fallback immediately — root.render() is
+ * always an urgent update regardless of startTransition.
+ *
+ * NavigationRoot holds the current element in React state. Navigation
+ * updates call startTransition(() => setState(newElement)), which IS
+ * a transition update. React keeps the old committed tree visible while
+ * any new Suspense boundaries in the transition resolve.
+ *
+ * Also manages `pendingUrl` as React state with an urgent/transition split:
+ * - Navigation START: `setPendingUrl(url)` is an urgent update — React
+ *   commits it before the next paint, showing the spinner immediately.
+ * - Navigation END: `setPendingUrl(null)` is inside `startTransition`
+ *   alongside `setElement(newTree)` — both commit atomically, so the
+ *   spinner disappears in the same frame as the new content appears.
+ *
+ * Hard navigation guard: When a hard navigation is triggered (500 error,
+ * version skew), the component throws an unresolved thenable AFTER all
+ * hooks to suspend forever — preventing React from rendering children
+ * during page teardown. The throw must come after hooks to satisfy
+ * React's rules (same hook count every render) while still preventing
+ * child renders that could hit hook count mismatches in components
+ * whose positions shift during teardown. This pattern is borrowed from
+ * Next.js (app-router.tsx pushRef.mpaNavigation — also after hooks).
+ *
+ * See design/05-streaming.md §"deferSuspenseFor"
+ * See design/19-client-navigation.md §"NavigationContext"
+ */
+import { type ReactNode } from 'react';
+import { type TopLoaderConfig } from './top-loader.js';
+/**
+ * Invalidate all in-flight navigation transitions. Any navigateTransition()
+ * call whose perform() has not yet committed will reject with AbortError
+ * instead of committing its element.
+ *
+ * Called by the router when a render supersedes in-flight navigations
+ * WITHOUT going through navigateTransition() — the cached popstate replay
+ * renders via transitionRender(), which doesn't bump the counter, so a
+ * stale forward navigation's setElement would otherwise pass the
+ * `counter.id !== transId` guard and commit the forward page over the
+ * replayed back page (TIM-1022).
+ */
+export declare function supersedeNavigationTransitions(): void;
+/**
+ * Set the hard-navigating flag. Call this BEFORE setting
+ * window.location.href or window.location.reload() to prevent:
+ * 1. React from rendering children during page teardown
+ * 2. Navigation API from intercepting the hard navigation
+ */
+export declare function setHardNavigating(value: boolean): void;
+/**
+ * Check if a hard navigation is in progress.
+ * Used by NavigationRoot (throw unresolvedThenable) and by the
+ * Navigation API handler (skip interception).
+ */
+export declare function isHardNavigating(): boolean;
+/**
+ * Root wrapper component that enables transition-based rendering.
+ *
+ * Renders PendingNavigationProvider around children for the pending URL
+ * context. The DOM tree matches the server-rendered HTML during hydration
+ * (the provider renders no extra DOM elements).
+ *
+ * Usage in browser-entry.ts:
+ *   const rootEl = createElement(NavigationRoot, { initial: wrapped });
+ *   reactRoot = hydrateRoot(document, rootEl);
+ *
+ * Subsequent navigations:
+ *   navigateTransition(url, async () => { fetch; return wrappedElement; });
+ *
+ * Non-navigation renders:
+ *   transitionRender(newWrappedElement);
+ */
+export declare function NavigationRoot({ initial, topLoaderConfig, }: {
+    initial: ReactNode;
+    topLoaderConfig?: TopLoaderConfig;
+}): ReactNode;
+/**
+ * Trigger a transition render for non-navigation updates.
+ * React keeps the old committed tree visible while any new Suspense
+ * boundaries in the update resolve.
+ *
+ * Used for: applyRevalidation, popstate replay with cached payload.
+ */
+export declare function transitionRender(element: ReactNode): void;
+/**
+ * Run a full navigation inside a React transition with optimistic pending URL.
+ *
+ * The `perform` callback runs inside `startTransition` — it should fetch the
+ * RSC payload, update router state, and return the wrapped React element.
+ * The pending URL shows immediately (urgent update) and reverts
+ * to null when the transition commits (atomic with the new tree).
+ *
+ * Returns a Promise that resolves when the async work completes (note: the
+ * React transition may not have committed yet, but all state updates are done).
+ *
+ * Used for: navigate(), refresh(), popstate with fetch.
+ */
+export declare function navigateTransition(pendingUrl: string, perform: () => Promise<{
+    element: ReactNode;
+    decodePromise: Promise<void> | null;
+}>): Promise<void>;
+/**
+ * Install one-shot deferred callbacks for the no-RSC bootstrap path (TIM-600).
+ *
+ * When there's no RSC payload, we can't create a React root immediately —
+ * `createRoot(document).render(...)` would blank the SSR HTML. Instead,
+ * this sets up `_transitionRender` and `_navigateTransition` so that the
+ * first client navigation triggers root creation via `createAndMount`.
+ *
+ * After `createAndMount` runs, NavigationRoot renders and overwrites these
+ * callbacks with its real `startTransition`-based implementations.
+ */
+export declare function installDeferredNavigation(createAndMount: (initial: ReactNode) => void): void;
+//# sourceMappingURL=navigation-root.d.ts.map

package/dist/client/navigation-root.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation-root.d.ts","sourceRoot":"","sources":["../../src/client/navigation-root.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAsD,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAE3F,OAAO,EAAa,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAyBlE;;;;;;;;;;;GAWG;AACH,wBAAgB,8BAA8B,IAAI,IAAI,CAErD;AA8BD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAEtD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAoCD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,EAC7B,OAAO,EACP,eAAe,GAChB,EAAE;IACD,OAAO,EAAE,SAAS,CAAC;IACnB,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC,GAAG,SAAS,CAyGZ;AAID;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI,CAIzD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,OAAO,CAAC;IAAE,OAAO,EAAE,SAAS,CAAC;IAAC,aAAa,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CAAE,CAAC,GAClF,OAAO,CAAC,IAAI,CAAC,CAMf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,cAAc,EAAE,CAAC,OAAO,EAAE,SAAS,KAAK,IAAI,GAAG,IAAI,CAiB5F"}

package/dist/client/nuqs-adapter.d.ts

@@ -7,5 +7,5 @@ import { type ReactNode } from 'react';
  */
 export declare function TimberNuqsAdapter({ children }: {
     children: ReactNode;
-}): import("react/jsx-runtime").JSX.Element;
+}): import("react").JSX.Element;
 //# sourceMappingURL=nuqs-adapter.d.ts.map

package/dist/client/nuqs-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nuqs-adapter.d.ts","sourceRoot":"","sources":["../../src/client/nuqs-adapter.tsx"],"names":[],"mappings":"AAcA,OAAO,EAAgC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAmFrE;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,2CAatE"}
+{"version":3,"file":"nuqs-adapter.d.ts","sourceRoot":"","sources":["../../src/client/nuqs-adapter.tsx"],"names":[],"mappings":"AAcA,OAAO,EAAgC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAgGrE;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,+BAatE"}

package/dist/client/router-ref.d.ts

@@ -5,7 +5,7 @@ import type { RouterInstance } from './router.js';
 export declare function setGlobalRouter(router: RouterInstance): void;
 /**
  * Get the global router instance. Throws if called before bootstrap.
- * Used by client-side hooks (useNavigationPending, etc.)
+ * Used by client-side hooks (usePendingNavigation, etc.)
  */
 export declare function getRouter(): RouterInstance;
 /**

package/dist/client/router.d.ts

@@ -1,12 +1,31 @@
 import { SegmentCache, PrefetchCache } from './segment-cache';
 import type { SegmentInfo } from './segment-cache';
 import { HistoryStack } from './history';
-import type { HeadElement } from './head';
+import { type NavigationState } from './navigation-context.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.
@@ -18,8 +37,12 @@ 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) => void;
+export type RootRenderer = (element: unknown, navState: NavigationState) => void;
 /**
  * Platform dependencies injected for testability. In production these
  * map to browser APIs; in tests they're replaced with mocks.
@@ -41,8 +64,6 @@ export interface RouterDeps {
      * In tests, this runs the callback synchronously.
      */
     afterPaint?: (callback: () => void) => void;
-    /** Apply resolved head elements (title, meta tags) to the DOM after navigation. */
-    applyHead?: (elements: HeadElement[]) => void;
     /**
      * Run a navigation inside a React transition with optimistic pending URL.
      * The pending URL shows immediately (useOptimistic urgent update) and
@@ -50,11 +71,66 @@ export interface RouterDeps {
      *
      * The `perform` callback receives a `wrapPayload` function to wrap the
      * decoded RSC payload with NavigationProvider + NuqsAdapter before
-     * TransitionRoot sets it as the new element.
+     * 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) => unknown) => Promise<unknown>) => Promise<void>;
+    navigateTransition?: (pendingUrl: string, perform: (wrapPayload: (payload: unknown, navState: NavigationState, segmentUpdates?: Map<string, unknown>) => unknown) => Promise<{
+        element: unknown;
+        decodePromise: Promise<void> | null;
+    }>) => 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,
+     * aligned with when the TopLoader's pendingUrl clears.
+     */
+    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 does not send X-Timber-State-Tree headers and does not
+     * populate the segment cache. Every navigation gets a full RSC payload.
+     */
+    clientSegmentCache?: boolean;
 }
 export interface RouterInstance {
     /** Navigate to a new URL (forward navigation) */
@@ -62,7 +138,7 @@ export interface RouterInstance {
     /** 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): Promise<void>;
+    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 */
@@ -76,18 +152,12 @@ export interface RouterInstance {
      * Renders the element tree and updates head elements without a server fetch.
      * See design/08-forms-and-actions.md §"Single-Roundtrip Revalidation".
      */
-    applyRevalidation(element: unknown, headElements: HeadElement[] | null): void;
+    applyRevalidation(element: 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;
-    /**
-     * Cache segment elements from a decoded RSC element tree.
-     * Called on initial hydration to populate the element cache so the
-     * first client navigation can use partial payloads.
-     */
-    cacheElementTree(element: unknown): void;
     /** The segment cache (exposed for tests and <Link> prefetch) */
     segmentCache: SegmentCache;
     /** The prefetch cache (exposed for tests and <Link> prefetch) */
@@ -99,5 +169,20 @@ export interface RouterInstance {
  * Create a router instance. In production, called once at app hydration
  * with real browser APIs. In tests, called with mock dependencies.
  */
+/**
+ * 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;
+};
 export declare function createRouter(deps: RouterDeps): RouterInstance;
 //# sourceMappingURL=router.d.ts.map

package/dist/client/router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/client/router.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/client/router.ts"],"names":[],"mappings":"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"}

package/dist/client/rsc-fetch.d.ts

@@ -11,33 +11,47 @@
  * See design/19-client-navigation.md §"RSC Payload Handling"
  */
 import type { SegmentInfo } from './segment-cache';
-import type { HeadElement } from './head';
 import type { RouterDeps } from './router';
-/** Result of fetching an RSC payload — includes head elements and segment metadata. */
+/** Result of fetching an RSC payload — includes segment metadata. */
 export interface FetchResult {
     payload: unknown;
-    headElements: HeadElement[] | null;
+    /**
+     * Promise that settles when the RSC decode completes or fails.
+     * The payload thenable is NOT awaited before returning (for streaming),
+     * so callers must monitor this to catch async decode errors
+     * (truncated streams, Flight parse failures) that would otherwise
+     * become unhandled rejections.
+     */
+    decodePromise: Promise<void> | 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(). */
+    /** Route params from X-Timber-Params header for populating useSegmentParams(). */
     params: Record<string, string | string[]> | null;
     /** Segment paths that were skipped by the server (for client-side merging). */
     skippedSegments: string[] | null;
 }
 export declare const RSC_CONTENT_TYPE = "text/x-component";
+/** Set the client deployment ID. Called once at bootstrap. */
+export declare function setClientDeploymentId(id: string | null): void;
+/** Get the client deployment ID. */
+export declare function getClientDeploymentId(): string | null;
+/** Header name used by the server to signal a version skew reload. */
+export declare const RELOAD_HEADER = "X-Timber-Reload";
+/** Header name for the client's deployment ID. */
+export declare const DEPLOYMENT_ID_HEADER = "X-Timber-Deployment-Id";
+/**
+ * Check if a response signals a version skew reload.
+ * Triggers a full page reload if the server indicates the client is stale.
+ */
+export declare function checkReloadSignal(response: Response): boolean;
 export declare function buildRscHeaders(stateTree: {
     segments: string[];
 } | undefined, currentUrl?: string): Record<string, string>;
-/**
- * Extract head elements from the X-Timber-Head response header.
- * Returns null if the header is missing or malformed.
- */
-export declare function extractHeadElements(response: Response): HeadElement[] | null;
 /**
  * Extract segment metadata from the X-Timber-Segments response header.
  * Returns null if the header is missing or malformed.
  *
- * Format: JSON array of {path, isAsync} objects describing the rendered
+ * Format: JSON array of {path, isRequestDependent} objects describing the rendered
  * segment chain from root to leaf. Used to populate the client-side
  * segment cache for state tree diffing on subsequent navigations.
  */
@@ -55,7 +69,7 @@ export declare function extractSkippedSegments(response: Response): string[] | n
  * Extract route params from the X-Timber-Params response header.
  * Returns null if the header is missing or malformed.
  *
- * Used to populate useParams() after client-side navigation.
+ * Used to populate useSegmentParams() after client-side navigation.
  */
 export declare function extractParams(response: Response): Record<string, string | string[]> | null;
 /**
@@ -66,15 +80,34 @@ export declare class RedirectError extends Error {
     readonly redirectUrl: string;
     constructor(url: string);
 }
+/**
+ * Thrown when the server signals a version skew (X-Timber-Reload header).
+ * Caught in navigate() to trigger a full page reload.
+ * See TIM-446.
+ */
+export declare class VersionSkewError extends Error {
+    constructor();
+}
+/**
+ * Thrown when the server returns an error for an RSC payload request.
+ * The server sends X-Timber-Error header and a JSON body instead of a
+ * broken RSC stream for any RenderError (4xx or 5xx). Caught in
+ * navigate() to trigger a hard navigation so the server can render
+ * the error page as HTML.
+ *
+ * See design/10-error-handling.md §"Error Page Rendering for Client Navigation"
+ */
+export declare class ServerErrorResponse extends Error {
+    readonly status: number;
+    readonly url: string;
+    constructor(status: number, url: string);
+}
 /**
  * Fetch an RSC payload from the server. If a decodeRsc function is provided,
  * the response is decoded into a React element tree via createFromFetch.
  * Otherwise, the raw response text is returned (test mode).
- *
- * Also extracts head elements from the X-Timber-Head response header
- * so the client can update document.title and <meta> tags after navigation.
  */
 export declare function fetchRscPayload(url: string, deps: RouterDeps, stateTree?: {
     segments: string[];
-}, currentUrl?: string): Promise<FetchResult>;
+}, currentUrl?: string, signal?: AbortSignal): Promise<FetchResult>;
 //# sourceMappingURL=rsc-fetch.d.ts.map

package/dist/client/rsc-fetch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rsc-fetch.d.ts","sourceRoot":"","sources":["../../src/client/rsc-fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAI3C,uFAAuF;AACvF,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IACnC,uFAAuF;IACvF,WAAW,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IAClC,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;IACjD,+EAA+E;IAC/E,eAAe,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CAClC;AAID,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AA2BnD,wBAAgB,eAAe,CAC7B,SAAS,EAAE;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,SAAS,EAC7C,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAexB;AAID;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,GAAG,WAAW,EAAE,GAAG,IAAI,CAQ5E;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,GAAG,WAAW,EAAE,GAAG,IAAI,CAQ3E;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,EAAE,GAAG,IAAI,CAS1E;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAQ1F;AAID;;;GAGG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBACjB,GAAG,EAAE,MAAM;CAIxB;AAID;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,UAAU,EAChB,SAAS,CAAC,EAAE;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,EAClC,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,WAAW,CAAC,CAuDtB"}
+{"version":3,"file":"rsc-fetch.d.ts","sourceRoot":"","sources":["../../src/client/rsc-fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAI3C,qEAAqE;AACrE,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;;OAMG;IACH,aAAa,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACpC,uFAAuF;IACvF,WAAW,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IAClC,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;IACjD,+EAA+E;IAC/E,eAAe,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CAClC;AAID,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AAyCnD,8DAA8D;AAC9D,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAE7D;AAED,oCAAoC;AACpC,wBAAgB,qBAAqB,IAAI,MAAM,GAAG,IAAI,CAErD;AAID,sEAAsE;AACtE,eAAO,MAAM,aAAa,oBAAoB,CAAC;AAE/C,kDAAkD;AAClD,eAAO,MAAM,oBAAoB,2BAA2B,CAAC;AAE7D;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAE7D;AAID,wBAAgB,eAAe,CAC7B,SAAS,EAAE;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,SAAS,EAC7C,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAsBxB;AAeD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,GAAG,WAAW,EAAE,GAAG,IAAI,CAS3E;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,EAAE,GAAG,IAAI,CAU1E;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAS1F;AAID;;;GAGG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,YAAY,GAAG,EAAE,MAAM,EAGtB;CACF;AAED;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,cAEC;CACF;AAED;;;;;;;;GAQG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,YAAY,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAItC;CACF;AAoDD;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,UAAU,EAChB,SAAS,CAAC,EAAE;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,EAClC,UAAU,CAAC,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,WAAW,CAAC,CAyGtB"}

package/dist/client/segment-cache.d.ts

@@ -1,11 +1,9 @@
-import type { HeadElement } from './head';
-/** A prefetched RSC result with optional head elements and segment metadata. */
+/** A prefetched RSC result with optional 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(). */
+    /** Route params from X-Timber-Params header for populating useSegmentParams(). */
     params?: Record<string, string | string[]> | null;
     /** Segment paths skipped by the server (for client-side merging). */
     skippedSegments?: string[] | null;
@@ -19,10 +17,20 @@ export interface SegmentNode {
     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;
+    /**
+     * Whether the segment/slot is request-dependent (calls getHeaders,
+     * getSearchParams, cookies, etc.). Request-dependent segments always
+     * re-render on navigation. For segments, this is still based on the
+     * AsyncFunction heuristic (to be replaced separately). For slots,
+     * this is taint-tracked via ALS.
+     */
+    isRequestDependent: boolean;
     /** Child segments keyed by segment path */
     children: Map<string, SegmentNode>;
+    /** Parallel route slots keyed by slot path (e.g., "/@sidebar") */
+    slots?: Map<string, SegmentNode>;
+    /** Whether this slot's access.ts denied on its last render. */
+    denied?: boolean;
 }
 /**
  * Serialized state tree sent via X-Timber-State-Tree header.
@@ -30,6 +38,7 @@ export interface SegmentNode {
  */
 export interface StateTree {
     segments: string[];
+    slots?: string[];
 }
 /**
  * Maintains the client-side segment tree representing currently mounted
@@ -62,7 +71,17 @@ export declare class SegmentCache {
  */
 export interface SegmentInfo {
     path: string;
-    isAsync: boolean;
+    /** Outlet key — includes route group name when applicable (e.g., "/(marketing)"). */
+    segmentId?: string;
+    isRequestDependent: boolean;
+    /** True for parallel route slot entries. Slots are keyed by their slot path (e.g., "/@sidebar"). */
+    slot?: boolean;
+    /** Parent segment path for slot entries. Used to attach the slot to the correct SegmentNode. */
+    parentSegment?: string;
+    /** True when the slot's access.ts denied on this render. Denied slots are excluded from the state tree. */
+    denied?: boolean;
+    /** True when the slot was skipped (cached content reused). Payloads with skipped slots are not replayable. */
+    skipped?: boolean;
 }
 /**
  * Build a SegmentNode tree from flat segment metadata.

package/dist/client/segment-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"segment-cache.d.ts","sourceRoot":"","sources":["../../src/client/segment-cache.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAI1C,gFAAgF;AAChF,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IACnC,uFAAuF;IACvF,WAAW,CAAC,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IACnC,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;IAClD,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,OAAO,EAAE,OAAO,CAAC;IACjB,kFAAkF;IAClF,OAAO,EAAE,OAAO,CAAC;IACjB,2CAA2C;IAC3C,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAID;;;;GAIG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,IAAI,CAA0B;IAEtC,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAO7C,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI;IAM7C,KAAK,IAAI,IAAI;IAIb;;;;;;;;;;;;OAYG;IACH,kBAAkB,CAAC,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS;CAO7D;AAkBD;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,WAAW,GAAG,SAAS,CA+BjF;AASD;;;;;;;GAOG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAU;IACxC,OAAO,CAAC,OAAO,CAAoC;IAEnD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI;IAO9C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAU5C,0EAA0E;IAC1E,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;CAOjD"}
+{"version":3,"file":"segment-cache.d.ts","sourceRoot":"","sources":["../../src/client/segment-cache.ts"],"names":[],"mappings":"AAKA,8DAA8D;AAC9D,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,uFAAuF;IACvF,WAAW,CAAC,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IACnC,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;IAClD,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;;OAMG;IACH,kBAAkB,EAAE,OAAO,CAAC;IAC5B,2CAA2C;IAC3C,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACnC,kEAAkE;IAClE,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACjC,+DAA+D;IAC/D,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAID;;;;GAIG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,IAAI,CAA0B;IAEtC,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAK5C;IAED,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAI5C;IAED,KAAK,IAAI,IAAI,CAEZ;IAED;;;;;;;;;;;;OAYG;IACH,kBAAkB,CAAC,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS,CAY3D;CACF;AAkCD;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,qFAAqF;IACrF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,oGAAoG;IACpG,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,gGAAgG;IAChG,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2GAA2G;IAC3G,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,8GAA8G;IAC9G,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,WAAW,GAAG,SAAS,CAiEjF;AASD;;;;;;;GAOG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAU;IACxC,OAAO,CAAC,OAAO,CAAoC;IAEnD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI,CAK7C;IAED,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAQ3C;IAED,0EAA0E;IAC1E,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAM/C;CACF"}

package/dist/client/segment-outlet.d.ts

@@ -0,0 +1,57 @@
+/**
+ * SegmentOutlet — client component boundary at each layout segment.
+ *
+ * Each layout in the segment tree is wrapped with a SegmentOutlet that:
+ * 1. Knows its segment path (prop from the server)
+ * 2. Reads from SegmentUpdateContext for partial navigation updates
+ * 3. Caches its rendered content in a ref across navigations
+ *
+ * On full navigation: receives new children via props, caches and renders them.
+ * On partial navigation (this segment skipped): the context map has no entry
+ * for this path, so the outlet returns cached content — preserving layout state.
+ * On partial navigation (this segment updated): the context map has content
+ * for this path, so the outlet renders the update.
+ *
+ * Uses React context instead of useSyncExternalStore to stay compatible
+ * with concurrent rendering (transitions). All outlets re-render when the
+ * context value changes, but each bails out quickly if its segment has
+ * no update — same approach as Next.js LayoutRouter.
+ *
+ * Security: performance optimization only. The server always runs all
+ * access.ts files regardless of segment skipping.
+ * See design/13-security.md §"State tree manipulation".
+ */
+import { type ReactNode } from 'react';
+export interface SegmentOutletProps {
+    /**
+     * Unique identifier for this segment. For normal segments this is the
+     * urlPath (e.g., "/", "/dashboard"). For route groups this includes the
+     * group name (e.g., "/(marketing)") to distinguish siblings that share
+     * the same urlPath. For slots this includes the slot name (e.g., "/@sidebar").
+     * Must match the segmentId used in state-tree-diff.ts.
+     */
+    segmentPath: string;
+    /** The segment's React subtree (layout + inner content). */
+    children: ReactNode;
+    /**
+     * When true, the outlet returns cached content instead of rendering
+     * new children. Used for skipped parallel route slots — the server
+     * sends an empty SegmentOutlet with skip=true, and the client keeps
+     * the previously cached slot content.
+     */
+    skip?: boolean;
+}
+/**
+ * Client component boundary at each layout segment in the element tree.
+ *
+ * On full navigation (context map is empty): renders children, caches in ref.
+ * On partial navigation: checks the context map for an update at segmentPath.
+ *   - Update found → renders update, caches in ref.
+ *   - No update → returns cached content (layout state preserved).
+ *
+ * React preserves component instances across reactRoot.render() calls
+ * when the same type appears at the same tree position. The ref persists
+ * across navigations because SegmentOutlet is reconciled, not remounted.
+ */
+export declare function SegmentOutlet({ segmentPath, children, skip }: SegmentOutletProps): ReactNode;
+//# sourceMappingURL=segment-outlet.d.ts.map

package/dist/client/segment-outlet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"segment-outlet.d.ts","sourceRoot":"","sources":["../../src/client/segment-outlet.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAG3D,MAAM,WAAW,kBAAkB;IACjC;;;;;;OAMG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB,4DAA4D;IAC5D,QAAQ,EAAE,SAAS,CAAC;IAEpB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAiCD;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,EAAE,WAAW,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,kBAAkB,aA8ChF"}

package/dist/client/segment-update-context.d.ts

@@ -0,0 +1,21 @@
+/**
+ * SegmentUpdateContext — React context for partial navigation updates.
+ *
+ * During partial navigation (server skips unchanged sync layouts), the
+ * router builds a Map of segment path → ReactNode updates and passes it
+ * as the context value. Mounted SegmentOutlet components read from this
+ * context to decide whether to render the update or their cached content.
+ *
+ * SINGLETON GUARANTEE: Uses globalThis + Symbol.for — same pattern as
+ * NavigationContext. The RSC client bundler can duplicate this 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"
+ */
+import React, { type ReactNode } from 'react';
+export declare const EMPTY_SEGMENT_UPDATES: Map<string, ReactNode>;
+export declare const SegmentUpdateContext: React.Context<Map<string, ReactNode>>;
+//# sourceMappingURL=segment-update-context.d.ts.map

package/dist/client/segment-update-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"segment-update-context.d.ts","sourceRoot":"","sources":["../../src/client/segment-update-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,EAAE,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAE9C,eAAO,MAAM,qBAAqB,wBAA+B,CAAC;AAmBlE,eAAO,MAAM,oBAAoB,uCAAuB,CAAC"}

package/dist/client/shallow-url.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Shallow URL replacement — update the browser URL bar without triggering
+ * RSC navigation, TopLoader, or any server round-trip.
+ *
+ * Uses the Navigation API's `info: { shallow: true }` when available (Chrome),
+ * which the navigate event handler intercepts with a no-op handler. Falls back
+ * to raw `history.replaceState` (Safari/Firefox — no navigate event fired).
+ */
+export declare function replaceUrl(url: string): void;
+//# sourceMappingURL=shallow-url.d.ts.map

package/dist/client/shallow-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shallow-url.d.ts","sourceRoot":"","sources":["../../src/client/shallow-url.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAU5C"}