@timber-js/app 0.2.0-alpha.66 → 0.2.0-alpha.68

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

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

package/dist/client/nav-link-store.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Navigation Link Store — passes per-link metadata from Link's onClick
+ * to the Navigation API's navigate event handler.
+ *
+ * When the Navigation API is active, Link does NOT call event.preventDefault()
+ * or router.navigate(). Instead it stores metadata (scroll option, link
+ * pending instance) here, and lets the <a> click propagate naturally.
+ * The navigate event handler reads this metadata to configure the RSC
+ * navigation with the correct options.
+ *
+ * This store is consumed once per navigation — after reading, the metadata
+ * is cleared. If no metadata is present (e.g., a plain <a> tag without
+ * our Link component), the navigate handler uses default options.
+ *
+ * See design/19-client-navigation.md §"Navigation API Integration"
+ */
+import type { LinkPendingInstance } from './link-pending-store.js';
+export interface NavLinkMetadata {
+    /** Whether to scroll to top after navigation. Default: true. */
+    scroll: boolean;
+    /** The Link's pending state instance for per-link status tracking. */
+    linkInstance: LinkPendingInstance | null;
+}
+/**
+ * Store metadata from Link's onClick for the next navigate event.
+ * Called synchronously in the click handler — the navigate event
+ * fires synchronously after onClick returns.
+ */
+export declare function setNavLinkMetadata(metadata: NavLinkMetadata): void;
+/**
+ * Consume the stored metadata. Returns null if no Link onClick
+ * preceded this navigation (e.g., plain <a> tag, programmatic nav).
+ * Clears the store after reading.
+ */
+export declare function consumeNavLinkMetadata(): NavLinkMetadata | null;
+//# sourceMappingURL=nav-link-store.d.ts.map

package/dist/client/nav-link-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nav-link-store.d.ts","sourceRoot":"","sources":["../../src/client/nav-link-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAEnE,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,MAAM,EAAE,OAAO,CAAC;IAChB,sEAAsE;IACtE,YAAY,EAAE,mBAAmB,GAAG,IAAI,CAAC;CAC1C;AAID;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAElE;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,IAAI,eAAe,GAAG,IAAI,CAI/D"}

package/dist/client/navigation-api-types.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Ambient type declarations for the Navigation API.
+ *
+ * The Navigation API is not yet in TypeScript's standard lib. These types
+ * are used internally via type assertions — we never import Navigation API
+ * types unconditionally. Progressive enhancement only: the API is feature-
+ * detected at runtime.
+ *
+ * See https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API
+ */
+export interface NavigationHistoryEntry {
+    readonly key: string;
+    readonly id: string;
+    readonly url: string | null;
+    readonly index: number;
+    readonly sameDocument: boolean;
+    getState(): unknown;
+    addEventListener(type: string, listener: EventListener): void;
+    removeEventListener(type: string, listener: EventListener): void;
+}
+export interface NavigationDestination {
+    readonly url: string;
+    readonly key: string | null;
+    readonly id: string | null;
+    readonly index: number;
+    readonly sameDocument: boolean;
+    getState(): unknown;
+}
+export interface NavigateEvent extends Event {
+    readonly navigationType: 'push' | 'replace' | 'reload' | 'traverse';
+    readonly destination: NavigationDestination;
+    readonly canIntercept: boolean;
+    readonly userInitiated: boolean;
+    readonly hashChange: boolean;
+    readonly signal: AbortSignal;
+    readonly formData: FormData | null;
+    readonly downloadRequest: string | null;
+    readonly info: unknown;
+    intercept(options?: NavigateInterceptOptions): void;
+    scroll(): void;
+}
+export interface NavigateInterceptOptions {
+    handler?: () => Promise<void>;
+    focusReset?: 'after-transition' | 'manual';
+    scroll?: 'after-transition' | 'manual';
+}
+export interface NavigationTransition {
+    readonly navigationType: 'push' | 'replace' | 'reload' | 'traverse';
+    readonly from: NavigationHistoryEntry;
+    readonly finished: Promise<void>;
+}
+export interface NavigationResult {
+    committed: Promise<NavigationHistoryEntry>;
+    finished: Promise<NavigationHistoryEntry>;
+}
+export interface NavigationApi {
+    readonly currentEntry: NavigationHistoryEntry | null;
+    readonly transition: NavigationTransition | null;
+    readonly canGoBack: boolean;
+    readonly canGoForward: boolean;
+    entries(): NavigationHistoryEntry[];
+    navigate(url: string, options?: NavigationNavigateOptions): NavigationResult;
+    reload(options?: NavigationReloadOptions): NavigationResult;
+    traverseTo(key: string, options?: NavigationOptions): NavigationResult;
+    back(options?: NavigationOptions): NavigationResult;
+    forward(options?: NavigationOptions): NavigationResult;
+    updateCurrentEntry(options: NavigationUpdateCurrentEntryOptions): void;
+    addEventListener(type: 'navigate', listener: (event: NavigateEvent) => void): void;
+    addEventListener(type: 'navigatesuccess', listener: (event: Event) => void): void;
+    addEventListener(type: 'navigateerror', listener: (event: Event) => void): void;
+    addEventListener(type: 'currententrychange', listener: (event: Event) => void): void;
+    addEventListener(type: string, listener: EventListener): void;
+    removeEventListener(type: string, listener: EventListener): void;
+}
+export interface NavigationNavigateOptions {
+    state?: unknown;
+    history?: 'auto' | 'push' | 'replace';
+    info?: unknown;
+}
+export interface NavigationReloadOptions {
+    state?: unknown;
+    info?: unknown;
+}
+export interface NavigationOptions {
+    info?: unknown;
+}
+export interface NavigationUpdateCurrentEntryOptions {
+    state: unknown;
+}
+//# sourceMappingURL=navigation-api-types.d.ts.map

package/dist/client/navigation-api-types.d.ts.map

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

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

@@ -0,0 +1,115 @@
+/**
+ * Navigation API integration — progressive enhancement for client navigation.
+ *
+ * When the Navigation API (`window.navigation`) is available, this module
+ * provides an intercept-based navigation model that replaces the separate
+ * popstate + click handler approach with a single navigate event listener.
+ *
+ * Key benefits:
+ * - Intercepts ALL navigations (link clicks, form submissions, back/forward)
+ * - Built-in AbortSignal per navigation (auto-aborts in-flight fetches)
+ * - Per-entry state via NavigationHistoryEntry.getState()
+ * - navigation.transition for progress tracking
+ *
+ * When unavailable, all functions are no-ops and the History API fallback
+ * in browser-entry.ts handles navigation.
+ *
+ * See design/19-client-navigation.md
+ */
+import type { NavigationApi } from './navigation-api-types.js';
+/**
+ * Returns true if the Navigation API is available in the current environment.
+ * Feature-detected at runtime — no polyfill.
+ */
+export declare function hasNavigationApi(): boolean;
+/**
+ * Get the Navigation API instance. Returns null if unavailable.
+ * Uses type assertion — we never import Navigation API types unconditionally.
+ */
+export declare function getNavigationApi(): NavigationApi | null;
+/**
+ * Callbacks for the Navigation API event handler.
+ *
+ * When the Navigation API intercepts a navigation, it delegates to these
+ * callbacks which run the RSC fetch + render pipeline.
+ */
+export interface NavigationApiCallbacks {
+    /**
+     * Handle a push/replace navigation intercepted by the Navigation API.
+     * This covers both Link <a> clicks (user-initiated, with metadata from
+     * nav-link-store) and external navigations (plain <a> tags, programmatic).
+     * The Navigation API handles the URL update via event.intercept().
+     */
+    onExternalNavigate: (url: string, options: {
+        replace: boolean;
+        signal: AbortSignal;
+        scroll?: boolean;
+    }) => Promise<void>;
+    /**
+     * Handle a traversal (back/forward button). The Navigation API intercepts
+     * the traversal and delegates to us for RSC replay/fetch.
+     */
+    onTraverse: (url: string, scrollY: number, signal: AbortSignal) => Promise<void>;
+}
+/**
+ * Controller returned by setupNavigationApi. Provides methods to
+ * coordinate between the router and the navigate event listener.
+ */
+export interface NavigationApiController {
+    /**
+     * Set the router-navigating flag. When `true`, the next navigate event
+     * (from pushState/replaceState) is recognized as router-initiated. The
+     * handler still intercepts it — but ties the browser's native loading
+     * state to a deferred promise instead of running the RSC pipeline again.
+     *
+     * This means `navigation.transition` is active for the full duration of
+     * every router-initiated navigation, giving the browser a native loading
+     * indicator (tab spinner, address bar) aligned with the TopLoader.
+     *
+     * Must be called synchronously around pushState/replaceState:
+     *   controller.setRouterNavigating(true);
+     *   history.pushState(...);        // navigate event fires, intercepted
+     *   controller.setRouterNavigating(false);  // flag off, deferred stays open
+     */
+    setRouterNavigating: (value: boolean) => void;
+    /**
+     * Resolve the deferred promise created by setRouterNavigating(true),
+     * clearing the browser's native loading state. Call this when the
+     * navigation fully completes — aligned with when the TopLoader's
+     * pendingUrl clears (same finally block in router.navigate).
+     */
+    completeRouterNavigation: () => void;
+    /**
+     * Initiate a navigation via the Navigation API (`navigation.navigate()`).
+     * Unlike `history.pushState()`, this fires the navigate event BEFORE
+     * committing the URL — allowing Chrome to show its native loading
+     * indicator while the intercept handler runs.
+     *
+     * Must be called with setRouterNavigating(true) active so the handler
+     * recognizes it as router-initiated and uses the deferred promise.
+     */
+    navigate: (url: string, replace: boolean) => void;
+    /**
+     * Save scroll position into the current navigation entry's state.
+     * Uses navigation.updateCurrentEntry() for per-entry scroll storage.
+     */
+    saveScrollPosition: (scrollY: number) => void;
+    /**
+     * Check if the Navigation API has an active transition.
+     * Returns the transition object if available, null otherwise.
+     */
+    hasActiveTransition: () => boolean;
+    /** Remove the navigate event listener. */
+    cleanup: () => void;
+}
+/**
+ * Set up the Navigation API navigate event listener.
+ *
+ * Intercepts same-origin navigations and delegates to the provided callbacks.
+ * Router-initiated navigations (pushState from router.navigate) are detected
+ * via a synchronous flag and NOT intercepted — the router already handles them.
+ *
+ * Returns a controller for coordinating with the router.
+ */
+export declare function setupNavigationApi(callbacks: NavigationApiCallbacks): NavigationApiController;
+//# sourceMappingURL=navigation-api.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"navigation-api.d.ts","sourceRoot":"","sources":["../../src/client/navigation-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAiB,MAAM,2BAA2B,CAAC;AAK9E;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAM1C;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,IAAI,CAGvD;AAID;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;OAKG;IACH,kBAAkB,EAAE,CAClB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,WAAW,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,KACjE,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnB;;;OAGG;IACH,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAClF;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;;;;;;;;;;OAcG;IACH,mBAAmB,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAE9C;;;;;OAKG;IACH,wBAAwB,EAAE,MAAM,IAAI,CAAC;IAErC;;;;;;;;OAQG;IACH,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IAElD;;;OAGG;IACH,kBAAkB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAE9C;;;OAGG;IACH,mBAAmB,EAAE,MAAM,OAAO,CAAC;IAEnC,0CAA0C;IAC1C,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,sBAAsB,GAAG,uBAAuB,CAsK7F"}

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

@@ -73,4 +73,15 @@ export declare function PendingNavigationProvider({ value, children, }: {
     value: string | null;
     children?: ReactNode;
 }): React.ReactElement;
+/**
+ * Check if the browser's Navigation API has an active transition.
+ *
+ * When the Navigation API is available and a navigation has been intercepted
+ * via event.intercept(), `navigation.transition` is non-null until the
+ * handler resolves. This provides browser-native progress tracking that
+ * can be used alongside the existing pendingUrl mechanism.
+ *
+ * Returns false when Navigation API is unavailable or no transition is active.
+ */
+export declare function hasNativeNavigationTransition(): boolean;
 //# sourceMappingURL=navigation-context.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"navigation-context.d.ts","sourceRoot":"","sources":["../../src/client/navigation-context.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,EAAiB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAM7D,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAuCD;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,eAAe,GAAG,IAAI,CAM7D;AAMD,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,eAAe,CAAC;IACvB,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,KAAK,EACL,QAAQ,GACT,EAAE,uBAAuB,GAAG,KAAK,CAAC,YAAY,CAO9C;AA6BD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAE/D;AAED,wBAAgB,kBAAkB,IAAI,eAAe,CAEpD;AA8BD;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,GAAG,IAAI,CAKvD;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,EACxC,KAAK,EACL,QAAQ,GACT,EAAE;IACD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB,GAAG,KAAK,CAAC,YAAY,CAMrB"}
+{"version":3,"file":"navigation-context.d.ts","sourceRoot":"","sources":["../../src/client/navigation-context.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,EAAiB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAM7D,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAuCD;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,eAAe,GAAG,IAAI,CAM7D;AAMD,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,eAAe,CAAC;IACvB,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,KAAK,EACL,QAAQ,GACT,EAAE,uBAAuB,GAAG,KAAK,CAAC,YAAY,CAO9C;AA6BD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAE/D;AAED,wBAAgB,kBAAkB,IAAI,eAAe,CAEpD;AA8BD;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,GAAG,IAAI,CAKvD;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,EACxC,KAAK,EACL,QAAQ,GACT,EAAE;IACD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB,GAAG,KAAK,CAAC,YAAY,CAMrB;AAMD;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,IAAI,OAAO,CAIvD"}

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,2CAatE"}

package/dist/client/router.d.ts

@@ -8,6 +8,19 @@ export interface NavigationOptions {
     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;
 }
 /**
  * Function that decodes an RSC Flight stream into a React element tree.
@@ -62,6 +75,37 @@ export interface RouterDeps {
      * If not provided (tests), the router falls back to renderRoot.
      */
     navigateTransition?: (pendingUrl: string, perform: (wrapPayload: (payload: unknown, navState: NavigationState) => unknown) => Promise<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,
+     * aligned with when the TopLoader's pendingUrl clears.
+     */
+    completeRouterNavigation?: () => void;
+    /**
+     * 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;
 }
 export interface RouterInstance {
     /** Navigate to a new URL (forward navigation) */
@@ -69,7 +113,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 */

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

@@ -111,5 +111,5 @@ export declare class ServerErrorResponse extends Error {
  */
 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,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;AAoCnD,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;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;AAED;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;;CAI1C;AAED;;;;;;;;GAQG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;gBACT,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM;CAKxC;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,CAoEtB"}
+{"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,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;AAoCnD,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;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;AAED;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;;CAI1C;AAED;;;;;;;;GAQG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;gBACT,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM;CAKxC;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,EACnB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,WAAW,CAAC,CAoEtB"}

package/dist/client/top-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"top-loader.d.ts","sourceRoot":"","sources":["../../src/client/top-loader.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AASH,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAmDD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,EAAE,MAAM,EAAE,EAAE;IAAE,MAAM,CAAC,EAAE,eAAe,CAAA;CAAE,GAAG,KAAK,CAAC,YAAY,GAAG,IAAI,CA2F7F"}
+{"version":3,"file":"top-loader.d.ts","sourceRoot":"","sources":["../../src/client/top-loader.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AASH,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAmDD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,EAAE,MAAM,EAAE,EAAE;IAAE,MAAM,CAAC,EAAE,eAAe,CAAA;CAAE,GAAG,KAAK,CAAC,YAAY,GAAG,IAAI,CAmG7F"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.66",
+  "version": "0.2.0-alpha.68",
   "description": "Vite-native React framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",
@@ -88,11 +88,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "vite build --config vite.lib.config.ts && tsc --emitDeclarationOnly --project tsconfig.json --outDir dist",
-    "typecheck": "tsgo --noEmit",
-    "prepublishOnly": "pnpm run build"
-  },
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/context-async-hooks": "^2.6.1",
@@ -131,5 +126,9 @@
   },
   "engines": {
     "node": ">=22.12.0"
+  },
+  "scripts": {
+    "build": "vite build --config vite.lib.config.ts && tsc --emitDeclarationOnly --project tsconfig.json --outDir dist",
+    "typecheck": "tsgo --noEmit"
   }
-}
+}

package/src/client/browser-entry.ts

@@ -76,6 +76,11 @@ import {
   DEPLOYMENT_ID_HEADER,
   RELOAD_HEADER,
 } from './rsc-fetch.js';
+import {
+  hasNavigationApi,
+  setupNavigationApi,
+  type NavigationApiController,
+} from './navigation-api.js';
 
 // ─── Server Action Dispatch ──────────────────────────────────────
 
@@ -257,6 +262,12 @@ function bootstrap(runtimeConfig: typeof config): void {
   // Assigned inside initRouter() which is called in both branches.
   let router!: RouterInstance;
 
+  // Navigation API controller — initialized when the API is available.
+  // Declared here (before the hydration if/else) because initRouter()
+  // is called from runPreHydration() inside both branches, and it
+  // assigns to this variable. Must be in scope before first use.
+  let navApiController: NavigationApiController | null = null;
+
   if (timberChunks) {
     const encoder = new TextEncoder();
 
@@ -480,10 +491,16 @@ function bootstrap(runtimeConfig: typeof config): void {
   // the initial render. renderRoot uses transitionRender which is set
   // by the TransitionRoot component during hydration.
   function initRouter(): void {
+    // Feature-detect Navigation API. When available, the navigate event
+    // replaces popstate for back/forward and catches external navigations.
+    // See design/19-client-navigation.md §"Navigation API Integration"
+    const useNavApi = hasNavigationApi();
+
     const deps: RouterDeps = {
       fetch: (url, init) => window.fetch(url, init),
       pushState: (data, unused, url) => window.history.pushState(data, unused, url),
       replaceState: (data, unused, url) => window.history.replaceState(data, unused, url),
+      navigationApiActive: useNavApi,
       scrollTo: (x, y) => {
         // Scroll the document viewport.
         window.scrollTo(x, y);
@@ -584,6 +601,37 @@ function bootstrap(runtimeConfig: typeof config): void {
 
     router = createRouter(deps);
     setGlobalRouter(router);
+
+    // Set up Navigation API integration after router is created.
+    // The navigate event listener delegates to router.navigate and
+    // router.handlePopState for external navigations and traversals.
+    if (useNavApi) {
+      navApiController = setupNavigationApi({
+        onExternalNavigate: async (url, { replace, signal, scroll }) => {
+          // Navigation intercepted by the Navigation API. Covers both
+          // Link <a> clicks (user-initiated) and external navigations.
+          // The Navigation API handles the URL update via intercept(),
+          // so pass _skipHistory to avoid double pushState.
+          await router.navigate(url, {
+            replace,
+            scroll,
+            _signal: signal,
+            _skipHistory: true,
+          });
+        },
+        onTraverse: async (url, scrollY, signal) => {
+          // Back/forward — delegate to the router's popstate handler.
+          await router.handlePopState(url, scrollY, signal);
+        },
+      });
+
+      // Wire the router-navigating flag into RouterDeps.
+      // This must be done after setupNavigationApi returns the controller.
+      deps.setRouterNavigating = (v) => navApiController!.setRouterNavigating(v);
+      deps.saveNavigationEntryScroll = (y) => navApiController!.saveScrollPosition(y);
+      deps.completeRouterNavigation = () => navApiController!.completeRouterNavigation();
+      deps.navigationNavigate = (url, replace) => navApiController!.navigate(url, replace);
+    }
   }
 
   // ── Pre-hydration sequence ──────────────────────────────────────────
@@ -619,9 +667,17 @@ function bootstrap(runtimeConfig: typeof config): void {
     headElements: null, // SSR already set the correct head
   });
 
-  // Initialize history.state with scrollY for the initial entry.
-  // This ensures back navigation to the initial page restores scroll correctly.
-  window.history.replaceState({ timber: true, scrollY: 0 }, '');
+  // Initialize scroll state for the initial entry.
+  // When Navigation API is available, use per-entry state.
+  // Otherwise fall back to history.state.
+  // Note: navApiController is assigned inside initRouter() which runs
+  // synchronously before this point via runPreHydration().
+  const navApi = navApiController as NavigationApiController | null;
+  if (navApi) {
+    navApi.saveScrollPosition(0);
+  } else {
+    window.history.replaceState({ timber: true, scrollY: 0 }, '');
+  }
 
   // Populate the segment cache from server-embedded segment metadata.
   // This enables state tree diffing from the very first client navigation.
@@ -653,27 +709,40 @@ function bootstrap(runtimeConfig: typeof config): void {
   }
 
   // Register popstate handler for back/forward navigation.
+  // When Navigation API is active, the navigate event covers traversals —
+  // popstate is a no-op. When unavailable, popstate handles back/forward.
+  //
   // Use pathname+search (not full href) to match the URL format used by
   // navigate() — Link hrefs are relative paths like "/scroll-test/page-a".
   // Read scrollY from history.state — the browser maintains per-entry state
   // so duplicate URLs in history each have their own scroll position.
   window.addEventListener('popstate', () => {
+    // Navigation API handles traversals via the navigate event.
+    if (navApiController) return;
+
     const state = window.history.state;
     const scrollY = state && typeof state.scrollY === 'number' ? state.scrollY : 0;
     void router.handlePopState(window.location.pathname + window.location.search, scrollY);
   });
 
-  // Keep history.state.scrollY up to date as the user scrolls.
+  // Keep scroll position up to date as the user scrolls.
   // This ensures that when the user presses back/forward, the departing
   // page's scroll position is already saved in its history entry.
-  // Debounced to avoid excessive replaceState calls during smooth scrolling.
+  // When Navigation API is available, uses per-entry state via
+  // navigation.updateCurrentEntry(). Otherwise falls back to history.state.
+  // Debounced to avoid excessive state updates during smooth scrolling.
   let scrollTimer: ReturnType<typeof setTimeout>;
   function saveScrollPosition(): void {
     clearTimeout(scrollTimer);
     scrollTimer = setTimeout(() => {
-      const state = window.history.state;
-      if (state && typeof state === 'object') {
-        window.history.replaceState({ ...state, scrollY: getScrollY() }, '');
+      const y = getScrollY();
+      if (navApiController) {
+        navApiController.saveScrollPosition(y);
+      } else {
+        const state = window.history.state;
+        if (state && typeof state === 'object') {
+          window.history.replaceState({ ...state, scrollY: y }, '');
+        }
       }
     }, 100);
   }

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);
   }