@rangojs/router 0.5.1 → 0.6.0

package/skills/testing/middleware.md

@@ -86,7 +86,7 @@ Pass an array to run several in order. Cookies set inside middleware via the sta
 
 ## Caveats
 
-- No `handles`/`rendered` option by design: middleware runs BEFORE the render barrier, so it has no post-barrier `ctx.use(Handle)` access in production. Read handle data in a loader/handler and test it with `runLoader` (see `./handles.md`).
+- No `handles`/`rendered` option by design: the middleware context has no handle APIs in production — no push (`ctx.use(Handle)` is a handler/loader API) and no post-barrier read (`ctx.get(handle)` is loader-only, and middleware runs BEFORE the render barrier anyway). Read handle data in a loader and test it with `runLoader`; assert loader pushes via `runLoaderResult(...).handlePushes` (see `./handles.md`).
 - A COMPONENT route's guard stack cannot be exercised through `dispatch` (it throws on component routes), and `renderToFlightString`/`renderRoute` don't run route middleware. Extract the middleware fn and unit-test it here, or assert the guard stack at e2e.
 - Middleware-phase `ctx.reverse` is map-only (no auto-fill from current params), matching production — enable it with `routeMap`. `routeName` only feeds `ctx.routeName`; it does NOT scope `.name` reverse (the chain reverse stays map-only by design).
 - `ctx.theme` is `undefined` unless `theme` is passed; `redirect()` does no basename prefixing unless `basename` is seeded.

package/skills/theme/SKILL.md

@@ -33,16 +33,15 @@ const router = createRouter<Env>({
 });
 ```
 
-## Server (in loaders/middleware)
+## Server (in handlers/middleware)
 
 ```typescript
-import { createLoader } from "@rangojs/router";
 import type { Middleware } from "@rangojs/router";
 
-// In a loader
-export const SettingsLoader = createLoader(async (ctx) => {
+// In a handler
+path("/settings", (ctx) => {
   const currentTheme = ctx.theme; // read from cookie
-  return { theme: currentTheme };
+  return <SettingsPage theme={currentTheme} />;
 });
 
 // In middleware
@@ -53,6 +52,10 @@ export const themeMiddleware: Middleware = async (ctx, next) => {
 };
 ```
 
+Theme accessors are handler/middleware-only — the loader context has no
+`ctx.theme`/`ctx.setTheme`. A loader that needs the theme reads the cookie
+directly via `cookies()` (loaders always run fresh, so the read is safe).
+
 ## Client
 
 ```tsx

package/skills/typesafety/generated-files-and-cli.md

@@ -38,11 +38,11 @@ available globally.
 There are three distinct typing surfaces. They are **not** interchangeable —
 pick the one that matches what you need to type:
 
-| Surface             | Source                                   | Scope  | Gives                                    | Does not give                                                                                    |
-| ------------------- | ---------------------------------------- | ------ | ---------------------------------------- | ------------------------------------------------------------------------------------------------ |
-| `GeneratedRouteMap` | `router.named-routes.gen.ts` (auto)      | global | route names, path params, search schemas | response/MIME payloads                                                                           |
-| `routes`            | per-module `*.gen.ts` (`rango generate`) | local  | local names, params, search              | the global app map                                                                               |
-| `RegisteredRoutes`  | manual `extends typeof router.routeMap`  | global | paths, params, **response payloads**     | the `Handler`/`Prerender` default (those read `GeneratedRouteMap` to avoid a `router.tsx` cycle) |
+| Surface             | Source                                               | Scope  | Gives                                    | Does not give                                                                                    |
+| ------------------- | ---------------------------------------------------- | ------ | ---------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `GeneratedRouteMap` | `router.named-routes.gen.ts` (auto)                  | global | route names, path params, search schemas | response/MIME payloads                                                                           |
+| `routes`            | per-module `*.gen.ts` (`rango generate`)             | local  | local names, params, search              | the global app map                                                                               |
+| `RegisteredRoutes`  | manual `extends` of a `typeof router.routeMap` alias | global | paths, params, **response payloads**     | the `Handler`/`Prerender` default (those read `GeneratedRouteMap` to avoid a `router.tsx` cycle) |
 
 Key consequence: `href()` and the ambient `Rango.Path` type are typed from
 whichever map is present — they prefer `RegisteredRoutes` when you wire it, otherwise fall back to
@@ -63,11 +63,15 @@ import type { AppBindings, AppVars } from "./env";
 
 export const router = createRouter<AppBindings>({}).routes(urlpatterns);
 
+// The alias is required: an interface heritage clause cannot take a `typeof`
+// type query directly (TS1109).
+type AppRoutes = typeof router.routeMap;
+
 declare global {
   namespace Rango {
     interface Env extends AppBindings {}
     interface Vars extends AppVars {}
-    interface RegisteredRoutes extends typeof router.routeMap {}
+    interface RegisteredRoutes extends AppRoutes {}
   }
 }
 ```
@@ -257,10 +261,12 @@ export const router = createRouter<ShopEnv>({ document: Document }).routes(
   urlpatterns,
 );
 
+type ShopRoutes = typeof router.routeMap;
+
 declare global {
   namespace Rango {
     interface Env extends ShopEnv {}
-    interface RegisteredRoutes extends typeof router.routeMap {}
+    interface RegisteredRoutes extends ShopRoutes {}
   }
 }
 ```
@@ -312,8 +318,9 @@ export default router;
 //    router.named-routes.gen.ts (auto-registers GeneratedRouteMap globally).
 //    No manual RegisteredRoutes declaration is needed for named-route handlers,
 //    ctx.reverse, prerender, href(), or Rango.Path. Add `RegisteredRoutes
-//    extends typeof router.routeMap` when global response payload helpers such
-//    as Rango.PathResponse need the richer router.routeMap metadata.
+//    extends AppRoutes` (an alias of typeof router.routeMap) when global
+//    response payload helpers such as Rango.PathResponse need the richer
+//    router.routeMap metadata.
 
 // 5. loaders/*.ts - Type-safe loaders
 export const ProductLoader = createLoader(async (ctx) => {

package/skills/typesafety/route-types.md

@@ -76,9 +76,13 @@ below is only needed for **`Rango.PathResponse`** (response-payload inference),
 `GeneratedRouteMap` cannot provide:
 
 ```typescript
+// The alias is required: an interface heritage clause cannot take a `typeof`
+// type query directly (TS1109).
+type AppRoutes = typeof router.routeMap;
+
 declare global {
   namespace Rango {
-    interface RegisteredRoutes extends typeof router.routeMap {}
+    interface RegisteredRoutes extends AppRoutes {}
   }
 }
 ```

package/skills/use-cache/SKILL.md

@@ -307,6 +307,53 @@ intercept("@modal", ".product", async (ctx) => {
 }),
 ```
 
+## Embedding server actions in cached components
+
+A cached function may return a component that creates an inline `"use server"`
+action. The canonical case is a cached list whose items each carry an action --
+e.g. a cached article list where every row has a like button:
+
+```typescript
+export async function ArticleList() {
+  "use cache: articles";
+  const articles = await db.query("SELECT id, title FROM articles");
+  return (
+    <ul>
+      {articles.map((a) => {
+        const articleId = a.id; // captured -> frozen with the cache entry
+        async function like() {
+          "use server";
+          // runs live on click, in the CURRENT request scope
+          const user = cookies().get("session")?.value;
+          if (user) await db.like(articleId, user);
+        }
+        return <LikeButton key={a.id} title={a.title} action={like} />;
+      })}
+    </ul>
+  );
+}
+```
+
+Three behaviors, locked by `use-cache-inline-action.test.ts` (dev + prod):
+
+| What                                            | Behavior                  | Why                                                                                                                                                                           |
+| ----------------------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Values the action **closes over** (`articleId`) | **Frozen** at cache-write | The closure compiles to encrypted bound args, snapshotted when the entry is written and replayed verbatim on a hit. Correct for stable identities; wrong for volatile values. |
+| The action **body**                             | **Runs live** every call  | Once invoked it is an ordinary server function: fresh computation and live request context. `cookies()` / `headers()` work here (the body executes in the live request).      |
+| Invocability on a **cache hit**                 | **Works**                 | The action survives serialize -> cache -> deserialize and stays callable.                                                                                                     |
+
+Rule of thumb: **capture stable identities, read volatile/request-scoped values
+live in the body.** Do not close over a per-request token, the current user, or
+the current time and expect freshness -- those are frozen at cache-write. The
+`cookies()`/`headers()` read guard applies to the cached function body, NOT to an
+inline action's body.
+
+Deploy note: captured values are encrypted with a per-build key by default. If
+cache entries can outlive a deploy (a persistent store such as the Cloudflare
+cache store), set `RANGO_ENCRYPTION_KEY` (base64-encoded 32 bytes) in the build
+environment so actions embedded in entries written by a previous deploy still
+decrypt; without it they fail until the entry expires or revalidates.
+
 ## Vite Transform
 
 The `rango:use-cache` Vite plugin detects the directive and wraps exports with

package/src/bin/rango.ts

@@ -144,7 +144,10 @@ function runStaticGeneration(args: string[], mode: "default" | "static") {
       if (/\bcreateRouter\s*[<(]/.test(source)) {
         routerFiles.push(filePath);
       }
-      if (source.includes("urls(")) {
+      // Both spellings, matching the writer's own gate: "clientUrls(" does
+      // NOT contain the lowercase "urls(" token (capital U), so a
+      // clientUrls-only module fails the server-token sniff alone.
+      if (source.includes("urls(") || source.includes("clientUrls(")) {
         urlsFiles.push(filePath);
       }
     } catch (err) {
@@ -255,8 +258,9 @@ async function runRuntimeDiscovery(args: string[], configFile?: string) {
       if (/\bcreateRouter\s*[<(]/.test(source)) {
         routerEntries.push(filePath);
       }
-      // Also generate per-module types for urls files
-      if (source.includes("urls(")) {
+      // Also generate per-module types for urls files. Both spellings — a
+      // clientUrls-only module has no lowercase "urls(" token (capital U).
+      if (source.includes("urls(") || source.includes("clientUrls(")) {
         writePerModuleRouteTypesForFile(filePath);
       }
     } catch {

package/src/browser/event-controller.ts

@@ -234,6 +234,12 @@ export interface EventController {
     listener: ActionStateListener,
   ): () => void;
   subscribeToHandles(listener: HandleListener): () => void;
+  /**
+   * Deliver queued location, params, navigation, and handle notifications now.
+   * NavigationProvider calls this inside the payload update so React assigns
+   * every route-state hook update to the same normal or transition lane.
+   */
+  flushRouteState(): void;
 
   // Handle operations
   setHandleData(
@@ -367,19 +373,32 @@ function matchesActionId(
   return entryActionId.endsWith(`#${subscriptionId}`);
 }
 
-// Batch rapid notifications into one microtask to prevent render storms
-function makeDebouncedNotifier(listeners: Set<() => void>): () => void {
+interface DebouncedNotifier {
+  schedule(): void;
+  flush(): void;
+}
+
+// Batch rapid notifications into one task to prevent render storms. The
+// explicit flush lets a React update owner preserve its scheduling lane.
+function makeDebouncedNotifier(listeners: Set<() => void>): DebouncedNotifier {
   let timeout: ReturnType<typeof setTimeout> | null = null;
-  return () => {
-    if (timeout !== null) clearTimeout(timeout);
-    timeout = setTimeout(() => {
-      timeout = null;
-      notifyListeners(
-        [...listeners],
-        (listener) => listener(),
-        (listener) => listeners.has(listener),
-      );
-    }, 0);
+  const flush = () => {
+    if (timeout === null) return;
+    clearTimeout(timeout);
+    timeout = null;
+    notifyListeners(
+      [...listeners],
+      (listener) => listener(),
+      (listener) => listeners.has(listener),
+    );
+  };
+
+  return {
+    schedule() {
+      if (timeout !== null) clearTimeout(timeout);
+      timeout = setTimeout(flush, 0);
+    },
+    flush,
   };
 }
 
@@ -459,7 +478,7 @@ export function createEventController(
 
   function notify(): void {
     cachedDerivedState = null;
-    notifyStateListeners();
+    notifyStateListeners.schedule();
   }
 
   const actionNotifyTimeouts = new Map<string, ReturnType<typeof setTimeout>>();
@@ -517,6 +536,11 @@ export function createEventController(
 
   const notifyHandles = makeDebouncedNotifier(handleListeners);
 
+  function flushRouteState(): void {
+    notifyStateListeners.flush();
+    notifyHandles.flush();
+  }
+
   function getState(): DerivedNavigationState {
     if (cachedDerivedState) return cachedDerivedState;
 
@@ -1001,7 +1025,7 @@ export function createEventController(
     handleSegmentOrder = newSegmentOrder;
     routeSegmentIds = newRouteSegmentIds;
 
-    notifyHandles();
+    notifyHandles.schedule();
   }
 
   function getHandleState(): HandleState {
@@ -1021,7 +1045,7 @@ export function createEventController(
       return;
     }
     routeSegmentIds = next;
-    notifyHandles();
+    notifyHandles.schedule();
   }
 
   // ========================================================================
@@ -1102,6 +1126,7 @@ export function createEventController(
     subscribe,
     subscribeToAction,
     subscribeToHandles,
+    flushRouteState,
 
     // Direct access
     getCurrentNavigation: () => currentNavigation,

package/src/browser/navigation-bridge.ts

@@ -48,6 +48,7 @@ import {
   schedulePrefetchWhenRouterIdle,
 } from "./prefetch/loader.js";
 import type { PrefetchStrategy } from "../router/prefetch-default.js";
+import { beginClientUrlNavigation } from "../client-urls/navigation.js";
 
 // Polyfill Symbol.dispose for Safari and older browsers
 if (typeof Symbol.dispose === "undefined") {
@@ -342,6 +343,10 @@ export function createNavigationBridge(
         state: resolvedState,
         skipLoadingState: false,
       });
+      const clientUrlPresentation = beginClientUrlNavigation(
+        targetUrl,
+        tx.handle.signal,
+      );
 
       // REVALIDATE: Fetch fresh data from server
       try {
@@ -422,6 +427,7 @@ export function createNavigationBridge(
         console.error("[Browser] Unprocessable navigation response:", error);
         emitNavigationError(onUpdate, error, url);
       } finally {
+        clientUrlPresentation?.clear();
         tx[Symbol.dispose]();
       }
     },

package/src/browser/navigation-client.ts

@@ -14,6 +14,7 @@ import {
 } from "./logging.js";
 import { getRangoState } from "./rango-state.js";
 import { isActionFenceActive } from "./action-fence.js";
+import { CLIENT_REVALIDATION_HEADER } from "../client-urls/revalidation-protocol.js";
 import {
   expandPayloadFragments,
   SEGMENT_FRAGMENT_CAPABILITY_HEADER,
@@ -79,6 +80,7 @@ export function createNavigationClient(
         previousUrl,
         signal,
         staleRevalidation,
+        clientRevalidation,
         interceptSourceUrl,
         version,
         routerId,
@@ -261,6 +263,9 @@ export function createNavigationClient(
             ...(fragmentRecovery && {
               [SEGMENT_FRAGMENT_RECOVERY_HEADER]: "1",
             }),
+            ...(clientRevalidation && {
+              [CLIENT_REVALIDATION_HEADER]: clientRevalidation,
+            }),
             ...(tx && { "X-RSC-Router-Request-Id": tx.requestId }),
             ...(interceptSourceUrl && {
               "X-RSC-Router-Intercept-Source": interceptSourceUrl,

package/src/browser/partial-update.ts

@@ -30,6 +30,10 @@ import {
   validateExternalRedirect,
 } from "./validate-redirect-origin.js";
 import type { NavigationUpdate } from "./types.js";
+import {
+  collectClientRevalidationDecisions,
+  setActiveInterceptTargets,
+} from "../client-urls/navigation.js";
 
 function toScrollPayload(
   scroll: boolean | undefined,
@@ -187,6 +191,22 @@ export function createPartialUpdater(
       );
     }
 
+    // Client-run per-loader revalidation: execute the held clientUrls route's
+    // revalidate() predicates now and ship their decisions with the request.
+    // Fails soft to null (locked server defaults) when no group is active or
+    // URLs do not parse.
+    let clientRevalidation: string | null = null;
+    try {
+      clientRevalidation = collectClientRevalidationDecisions({
+        currentUrl: new URL(previousUrl, window.location.origin),
+        nextUrl: new URL(url, window.location.origin),
+        isAction: false,
+        stale: mode.type === "stale-revalidation",
+      });
+    } catch {
+      clientRevalidation = null;
+    }
+
     let fetchResult: Awaited<ReturnType<NavigationClient["fetchPartial"]>>;
     fetchResult = await client.fetchPartial({
       targetUrl: url,
@@ -194,6 +214,7 @@ export function createPartialUpdater(
       previousUrl,
       staleRevalidation:
         mode.type === "stale-revalidation" || segments.length === 0,
+      clientRevalidation,
       version: getVersion(),
       routerId: store.getRouterId?.(),
     });
@@ -421,10 +442,8 @@ export function createPartialUpdater(
         // forceAwait unwraps the ROUTER loader promises during render so they
         // land without a loading()/fallback frame. A fully-prefetched nav has
         // its router data already resolved (the prefetch stream drained), so
-        // awaiting it here is free and lets us commit NORMALLY (not in a
-        // transition) below — a normal commit still shows fallbacks for any
-        // CLIENT component that suspends on mount, which a transition would
-        // wrongly suppress by holding the old UI until that suspense settles.
+        // awaiting it here is free; the commit below then runs in a transition
+        // (fullyPrefetched branch) so nothing router-owned can flash.
         forceAwait: mode.type === "stale-revalidation" || fullyPrefetched,
         interceptSegments:
           reconciled.interceptSegments.length > 0
@@ -469,6 +488,23 @@ export function createPartialUpdater(
         payload.metadata?.slots,
       );
 
+      // Same-structure revalidation: every segment this commit will render
+      // already exists on screen (by id) — the navigation mounts nothing new,
+      // it only refreshes what the user is looking at. The hold this enables
+      // manifests on SEARCH-only navs (filters, tabs — search is never in the
+      // segment key, so the subtree reconciles); a PARAM nav outside a
+      // transition() scope still remounts via its param-bearing key
+      // (segment-system.tsx) and reveals its fresh skeleton inside the
+      // transition, unchanged. Compared against the CURRENT page's cache, not
+      // cachedSegs: for a popstate restore cachedSegs is the TARGET's history
+      // cache, which says nothing about what is visible now. Restricted to
+      // plain navigations — leave-intercept must close its modal urgently,
+      // and action/stale modes have their own transition branch.
+      const onScreenIds = new Set(getCurrentCachedSegments().map((s) => s.id));
+      const isSameStructureNav =
+        mode.type === "navigate" &&
+        reconciled.segments.every((s) => onScreenIds.has(s.id));
+
       const effectiveInterceptSource =
         interceptSourceUrl || segmentState.currentUrl;
       if (mode.type !== "action" && mode.type !== "stale-revalidation") {
@@ -525,6 +561,13 @@ export function createPartialUpdater(
           all: reconciled.segments.map((s) => s.id),
         });
       }
+      // Refresh the browser-local intercept-target set for the location being
+      // committed — the clientUrls matcher declines optimistic presentation
+      // for targets an intercept would claim from here. Back/forward commits
+      // served purely from the history cache keep the previous set (no fresh
+      // metadata); popstate navigations get no optimistic presentation anyway.
+      setActiveInterceptTargets(payload.metadata?.interceptTargets);
+
       const scrollPayload = toScrollPayload(navScroll);
 
       if (mode.type === "action" || mode.type === "stale-revalidation") {
@@ -549,13 +592,37 @@ export function createPartialUpdater(
             scroll: scrollPayload,
           });
         });
+      } else if (fullyPrefetched || isSameStructureNav) {
+        // Content-hold commit, two triggers. Fully-prefetched nav: the payload
+        // is fully resolved (forceAwait above), so the transition commits
+        // synchronously — no fallback flash. Same-structure nav: the re-run
+        // loaders are still streaming, and an urgent commit would re-suspend
+        // the ALREADY-REVEALED boundaries — replacing visible content with its
+        // own fallback for the loader's full duration (the PLP filter-change
+        // flash). Inside a transition React holds the current UI until the
+        // suspended data lands, the action treatment; nothing new mounts (by
+        // the isSameStructureNav definition), so no fallback is being withheld
+        // from a first paint. No addTransitionType: this is the React
+        // content-hold, not a view transition. Deliberate trade-off (#622
+        // introduced, #624 reverted, then reinstated): a client component that
+        // suspends during its FIRST render (use() of a promise created at
+        // mount — see ClientMountSuspense in the e2e test-app) under an
+        // ALREADY-REVEALED boundary holds the old content until it resolves
+        // instead of revealing that boundary's fallback; its render happens
+        // pre-commit inside the transition, so userland effects cannot run
+        // first. Boundaries newly mounted by this nav still reveal their
+        // fallbacks (React shows new boundaries inside transitions).
+        startTransition(() => {
+          onUpdate({
+            root: newTree,
+            metadata: payload.metadata!,
+            scroll: scrollPayload,
+          });
+        });
       } else {
-        // Normal commit for ALL navs here, never a transition (see the
-        // forceAwait comment above for why prefetched router data lands
-        // without fallback frames). A transition would hold the OLD UI until
-        // every suspense in the new tree settles — including a client
-        // component that only starts fetching post-mount, retaining the
-        // previous page indefinitely. Explicit transition() routes keep the
+        // Cold/partially-prefetched nav that mounts NEW segments: normal
+        // commit so fallbacks stream like a first load and the click has
+        // visible feedback. Explicit transition() routes keep the
         // content-hold via the hasTransition branch above (the opt-in).
         onUpdate({
           root: newTree,

package/src/browser/react/NavigationProvider.tsx

@@ -456,6 +456,13 @@ export function NavigationProvider({
           cached === undefined ? update.metadata.resolvedIds : undefined,
         );
       }
+
+      // tx.commit() and the metadata updates above mutate the controller
+      // synchronously, but its ordinary notifications are task-debounced. Flush
+      // them here so hook setState calls inherit this payload update's lane. In
+      // a transition that suspends, the source tree therefore keeps its source
+      // pathname/params until the destination payload commits with them.
+      eventController.flushRouteState();
     });
 
     return unsubscribe;

package/src/browser/react/use-router.ts

@@ -2,6 +2,7 @@
 
 import { useContext, useMemo } from "react";
 import { NavigationStoreContext } from "./context.js";
+import { useMount } from "./use-mount.js";
 import { prefetchDirect } from "../prefetch/loader.js";
 import { getAppVersion } from "../app-version.js";
 import type { RouterInstance, RouterNavigateOptions } from "../types.js";
@@ -9,8 +10,8 @@ import type { RouterInstance, RouterNavigateOptions } from "../types.js";
 /**
  * Hook to access router actions (push, replace, refresh, prefetch, back, forward).
  *
- * Returns a STABLE reference that never changes, so components using
- * useRouter() do not re-render on navigation state changes.
+ * Returns a STABLE reference per component, so components using useRouter()
+ * do not re-render on navigation state changes.
  * For reactive navigation state, use useNavigation() instead.
  *
  * Methods read `basename` from the context on each call. It is set once from
@@ -18,10 +19,17 @@ import type { RouterInstance, RouterNavigateOptions } from "../types.js";
  * is a full document load (X-RSC-Reload), so the target app mounts fresh with
  * its own basename.
  *
+ * RELATIVE paths (no leading `/`, no scheme/query/hash) resolve against the
+ * current include() mount: `router.push("cart")` inside `include("/shop")`
+ * navigates to `/shop/cart`. Absolute paths stay APP-absolute — unlike
+ * basename, the mount is scoped, and absolute pushes legitimately target
+ * outside it, so they are never auto-prefixed.
+ *
  * @example
  * ```tsx
  * const router = useRouter();
- * router.push("/products");
+ * router.push("/products");   // app-absolute
+ * router.push("cart");        // mount-relative
  * router.replace("/login", { scroll: false });
  * router.prefetch("/dashboard");
  * router.back();
@@ -29,15 +37,17 @@ import type { RouterInstance, RouterNavigateOptions } from "../types.js";
  */
 export function useRouter(): RouterInstance {
   const ctx = useContext(NavigationStoreContext);
+  const mount = useMount();
 
   if (!ctx) {
     throw new Error("useRouter must be used within NavigationProvider");
   }
 
-  // Stable reference: ctx itself is stable, and reads on each method call
-  // pick up live basename values from the context (backed by a live ref
-  // in NavigationProvider), so app-switch transitions are reflected without
-  // recreating this object.
+  // Stable reference per component: ctx is stable and mount is a static
+  // property of the component's position in the tree; reads on each method
+  // call pick up live basename values from the context (backed by a live
+  // ref in NavigationProvider), so app-switch transitions are reflected
+  // without recreating this object.
   return useMemo<RouterInstance>(() => {
     /** Prefix a root-relative path with basename if not already prefixed. */
     function withBasename(url: string): string {
@@ -47,13 +57,32 @@ export function useRouter(): RouterInstance {
       return url === "/" ? bn : bn + url;
     }
 
+    /**
+     * Resolve a navigation/prefetch target. RELATIVE paths — a leading word
+     * character or `./`, never a scheme (`http:`, `mailto:`), query, or
+     * hash form — join onto the include mount and then take the basename
+     * pass like any root-relative path. Everything else passes through
+     * unchanged.
+     */
+    function resolveTarget(url: string): string {
+      const relative = url.startsWith("./") ? url.slice(2) : url;
+      if (
+        !/^[A-Za-z0-9]/.test(relative) ||
+        /^[a-z][a-z0-9+.-]*:/i.test(relative)
+      ) {
+        return withBasename(url);
+      }
+      const base = mount === "/" ? "" : mount.replace(/\/$/, "");
+      return withBasename(`${base}/${relative}`);
+    }
+
     return {
       push(url: string, options?: RouterNavigateOptions): Promise<void> {
-        return ctx.navigate(withBasename(url), { ...options, replace: false });
+        return ctx.navigate(resolveTarget(url), { ...options, replace: false });
       },
 
       replace(url: string, options?: RouterNavigateOptions): Promise<void> {
-        return ctx.navigate(withBasename(url), { ...options, replace: true });
+        return ctx.navigate(resolveTarget(url), { ...options, replace: true });
       },
 
       refresh(): Promise<void> {
@@ -64,7 +93,7 @@ export function useRouter(): RouterInstance {
         const segmentState = ctx.store?.getSegmentState();
         if (segmentState) {
           prefetchDirect(
-            withBasename(url),
+            resolveTarget(url),
             segmentState.currentSegmentIds,
             getAppVersion(),
             ctx.store?.getRouterId?.(),
@@ -94,5 +123,5 @@ export function useRouter(): RouterInstance {
         window.history.forward();
       },
     };
-  }, []);
+  }, [mount]);
 }