@rangojs/router 0.0.0-experimental.e9c0b2f2 → 0.0.0-experimental.ea9f40f2

package/skills/typesafety/params-and-search.md

@@ -0,0 +1,153 @@
+# Params and Search Types
+
+## Typed Search Params
+
+Add a `search` schema to `path()` options for type-safe query parameters:
+
+```typescript
+// Route definition with search schema
+path("/search", SearchPage, {
+  name: "search",
+  search: { q: "string", page: "number?", sort: "string?" },
+});
+```
+
+### Handler with typed search params
+
+`Handler<"name">` automatically resolves route params and search params from the
+global `GeneratedRouteMap` (the gen file). No explicit route map import needed:
+
+```typescript
+// pages/search.tsx
+import type { Handler } from "@rangojs/router";
+
+export const SearchPage: Handler<"search"> = (ctx) => {
+  // ctx.search is typed: { q: string; page?: number; sort?: string }
+  const { q, page, sort } = ctx.search;
+  return <SearchResults q={q} page={page} sort={sort} />;
+};
+```
+
+This avoids circular references because `Handler` defaults to `GeneratedRouteMap`
+(from `router.named-routes.gen.ts`) instead of `RegisteredRoutes` (which depends on `router.tsx`).
+
+You can also pass an explicit route map for per-module isolation (opt-in,
+after running `npx rango generate`). With a local map, the route name is
+**dot-prefixed** so params and search resolve from `routes`, not the global map:
+
+```typescript
+import type { Handler } from "@rangojs/router";
+import type { routes } from "./urls.gen.js";
+
+export const SearchPage: Handler<".search", routes> = (ctx) => { ... };
+```
+
+Note the difference: `Handler<"search">` (no dot) resolves against the global
+`GeneratedRouteMap`; `Handler<".search", routes>` resolves against the local
+`routes` map. Mixing them — `Handler<"search", routes>` — silently ignores
+`routes` for param/search inference and only uses it for local `ctx.reverse(".x")`.
+
+Supported types: `"string"`, `"number"`, `"boolean"`, with `?` suffix for optional.
+Values are automatically coerced from query string (e.g., `"2"` becomes `2` for numbers).
+Routes without a `search` schema keep the standard `URLSearchParams` behavior.
+
+### RouteSearchParams and RouteParams utility types
+
+Extract typed params by route name for use in component props, return types, or anywhere:
+
+```typescript
+import type { RouteSearchParams, RouteParams } from "@rangojs/router";
+
+// RouteSearchParams<"name"> resolves the search schema to a typed object
+type SP = RouteSearchParams<"search">;
+// { q: string | undefined; page?: number; sort?: string }
+
+// RouteParams<"name"> resolves URL params from the route pattern
+type P = RouteParams<"blogPost">;
+// { slug: string }
+
+// Optional URL params (`:slug?`) resolve to `string | undefined`
+// because absent segments are omitted from `ctx.params` at runtime.
+type C = RouteParams<"checkout">;
+// { step?: string }
+// → ctx.params.step is `string | undefined`; use `?? "default"` to coalesce.
+
+// Use in component props
+interface SearchResultsProps {
+  params: RouteSearchParams<"search">;
+}
+```
+
+Both default to the global route map (`RegisteredRoutes` or `GeneratedRouteMap`).
+Pass an explicit route map as the second type argument when needed:
+
+```typescript
+import type { routes } from "./urls.gen.js";
+
+type SP = RouteSearchParams<"search", routes>;
+type P = RouteParams<"blogPost", routes>;
+```
+
+### Generated route types
+
+In the generated `router.named-routes.gen.ts`, routes with search schemas
+use `{ path, search }` objects:
+
+```typescript
+// router.named-routes.gen.ts (auto-generated)
+export const NamedRoutes = {
+  "search.index": {
+    path: "/search",
+    search: { q: "string", page: "number?", sort: "string?" },
+  },
+  "home.index": "/", // No search schema -> plain string
+} as const;
+```
+
+You never open a `.gen.ts` by hand. Treat the generated types as call-site
+honesty checks, not modules to read:
+
+- **Do not import `router.named-routes.gen.ts` directly**, and don't reach for
+  `Rango.GeneratedRouteMap`. It is the whole-app manifest, auto-wired
+  globally — `Handler<"name">` and `ctx.reverse("name")` already see it.
+- **Per-module `*.gen.ts` imports are fine** — they are the opt-in local-route
+  pattern for `useReverse(routes)` and explicit local handler typing
+  (`Handler<".name", routes>`). See `/links`.
+
+If a type error points at a generated map instead of your call site, that's a
+smell — fix the call site (or regenerate), never edit the generated file.
+
+## Loader Type Safety
+
+Loaders have typed return values:
+
+```typescript
+// loaders/product.ts
+export const ProductLoader = createLoader(async (ctx) => {
+  return {
+    id: ctx.params.slug,
+    name: "Widget",
+    price: 99,
+  };
+});
+
+// In server component - type is inferred
+import { useLoader } from "@rangojs/router/client";
+
+async function ProductPage() {
+  const product = await useLoader(ProductLoader);
+  // product: { id: string; name: string; price: number }
+  return <h1>{product.name}</h1>;
+}
+
+// In client component - same type
+"use client";
+import { useLoader } from "@rangojs/router/client";
+
+function ProductPrice() {
+  const { data } = useLoader(ProductLoader);
+  // data: { id: string; name: string; price: number }
+  const product = data;
+  return <span>${product.price}</span>;
+}
+```

package/skills/typesafety/route-types.md

@@ -0,0 +1,209 @@
+# Route Types
+
+## Route Definition with Type-Safe Names
+
+```typescript
+// urls.tsx
+import { urls } from "@rangojs/router";
+
+export const urlpatterns = urls(({ path, layout }) => [
+  path("/", HomePage, { name: "home" }),
+  path("/products", ProductsPage, { name: "products" }),
+  path("/product/:slug", ProductPage, { name: "product" }),
+  path("/cart", CartPage, { name: "cart" }),
+  path("/checkout/:step?", CheckoutPage, { name: "checkout" }),
+]);
+
+// Route names are inferred from the { name } option
+```
+
+## Type-Safe href()
+
+### Server: ctx.reverse with route names
+
+In route handlers, `ctx.reverse()` uses two namespaces:
+
+- **`.name`** — local route, resolved within the current `include()` scope
+- **`name`** — global route, from the named-routes definition
+
+```typescript
+import type { Handler } from "@rangojs/router";
+
+export const ProductHandler: Handler<"shop.product"> = (ctx) => {
+  ctx.reverse(".cart"); // Local: /shop/cart
+  ctx.reverse(".product", { slug: "widget" }); // Local: /shop/product/widget
+  ctx.reverse("blog.post", { slug: "1" }); // Global: /blog/1
+};
+```
+
+For type-safe local names, generate a route types file with `npx rango generate urls/shop.tsx`
+and pass it as the second generic to `Handler` or `Prerender`:
+
+```typescript
+import type { Handler } from "@rangojs/router";
+import type { routes } from "./shop.gen.js";
+
+export const ProductHandler: Handler<"shop.product", routes> = (ctx) => {
+  ctx.reverse(".cart"); // Type-safe local name
+  ctx.reverse(".product", { slug: "widget" }); // Type-safe local with params
+  ctx.reverse("blog.post", { slug: "hi" }); // Type-safe global name
+};
+```
+
+### Client: href + useHref
+
+On the client, `href()` validates paths against registered route patterns at compile time:
+
+```typescript
+"use client";
+import { href, useHref, Link } from "@rangojs/router/client";
+
+// href() validates absolute paths via PatternToPath types
+href("/about");                        // Valid path
+href("/blog/hello");                   // Matches /blog/:slug
+
+// useHref() auto-prefixes with include() mount
+function ShopNav() {
+  const href = useHref();
+  return <Link to={href("/cart")}>Cart</Link>; // "/shop/cart"
+}
+```
+
+`href()` and the `Rango.Path` type read from `RegisteredRoutes` when you augment
+it, otherwise from the auto-generated `GeneratedRouteMap` — so `rango generate`
+alone type-checks `href()` paths with no manual augmentation. The augmentation
+below is only needed for **`Rango.PathResponse`** (response-payload inference), which
+`GeneratedRouteMap` cannot provide:
+
+```typescript
+declare global {
+  namespace Rango {
+    interface RegisteredRoutes extends typeof router.routeMap {}
+  }
+}
+```
+
+For wrapper helpers, type the path parameter as `Rango.Path`. It is ambient (no
+import) and shares `href()`'s compile-time path checking, so a wrapper stays in
+sync with your routes automatically:
+
+```typescript
+import { href } from "@rangojs/router/client";
+
+export const appHref = (path: Rango.Path): string => href(path);
+```
+
+For response-route payloads, `Rango.PathResponse<T>` is the ambient lookup. It
+accepts a route _pattern_ **or** a concrete path, so it also serves as the return
+type of a typed `fetch` wrapper. It only resolves once `RegisteredRoutes` carries
+response metadata:
+
+```typescript
+import { href } from "@rangojs/router/client";
+
+type Product = Rango.PathResponse<"/api/products/:id">; // by pattern
+type Same = Rango.PathResponse<"/api/products/42">; // by concrete path
+
+// Response inferred from the concrete path passed in:
+async function get<T extends Rango.Path>(
+  path: T,
+): Promise<Rango.PathResponse<T>> {
+  return fetch(href(path)).then((r) => r.json());
+}
+const product = await get("/api/products/42"); // Product (bare value)
+```
+
+Pattern keys (`/:id`) match exactly; a concrete path under a _nested_ dynamic
+route can match several patterns and union their responses.
+
+`Rango.PathResponse` describes the JSON **wire** shape, not the handler's raw
+return. A `path.json()` handler returning `{ createdAt: Date }` resolves here to
+`{ createdAt: string }` (bare value), matching what `r.json()` yields. This
+is applied via the ambient `Rango.JsonSerialize<T>` transform (`Date -> string`,
+honors `toJSON()`, drops functions/`undefined`, `bigint -> never`). A separate
+`Rango.FlightSerialize<T>` models the higher-fidelity RSC Flight boundary
+(loaders / RSC props, where `Date` is preserved) — do **not** use it for
+`path.json()`.
+
+### Overriding serialization globally
+
+For your own types, the zero-config way to control the JSON wire shape is a
+`toJSON()` method — `Rango.JsonSerialize` honors it, and it matches the runtime
+exactly (`JSON.stringify` calls `toJSON()`):
+
+```typescript
+class Money {
+  constructor(private cents: number) {}
+  toJSON(): number {
+    return this.cents;
+  }
+}
+// Rango.JsonSerialize<Money> is number; Rango.PathResponse reflects it.
+```
+
+To override a transform for types you **don't** own (or for the Flight boundary,
+which has no `toJSON()`), augment its override slot. Because `Rango.JsonSerialize`
+/ `Rango.FlightSerialize` are type _aliases_ (TS can't merge those), you provide a
+single member that is your **complete** transform, delegating to the built-in for
+the cases you don't change:
+
+```typescript
+declare global {
+  namespace Rango {
+    interface JsonSerializeOverride<T> {
+      app: T extends Decimal ? string : Rango.JsonSerializeBuiltin<T>;
+    }
+    interface FlightSerializeOverride<T> {
+      app: T extends Money ? number : Rango.FlightSerializeBuiltin<T>;
+    }
+  }
+}
+// Rango.JsonSerialize<Decimal> -> string; Rango.FlightSerialize<Money> -> number;
+// everything else stays on the built-in, recursively (nested fields too).
+```
+
+Rules: provide **exactly one** member (the slot is read as
+`Override<T>[keyof Override<T>]`, so multiple members union and conflict).
+Overrides win over `toJSON()` and apply at every nesting level. Caveat for JSON:
+the `path.json()` runtime is plain `JSON.stringify`, which only honors `toJSON()`,
+so a `JsonSerializeOverride` that disagrees with what the runtime emits will lie —
+prefer `toJSON()` for your own types and use the slot only for types you can't
+modify.
+
+See `/links` for full URL generation guide.
+
+## Stable identity: `path#export`
+
+Loaders, handles, cached functions (`functionId`), and server actions
+(`actionId`) all share one identity scheme: `{modulePath}#{exportName}`,
+injected at build by the `exposeInternalIds` and `exposeActionId` Vite plugins.
+This is also the identity React server actions carry across the Flight boundary,
+which is why a `revalidate()` predicate sees an action as a `path#export` string:
+
+```typescript
+revalidate(
+  ({ actionId }) => actionId === "src/actions/cart.ts#addToCart" || undefined,
+);
+```
+
+`actionId` is the only stable reference React exposes across the Flight boundary,
+so it stays as the floor and escape hatch. The hand-written-string surface
+(`actionId?.includes("cart.ts#")`) is brittle: a renamed action or moved file
+silently stops matching with no compile error. Prefer **`ctx.isAction()`** in a
+revalidate predicate — it resolves the action's id from an imported reference, so
+a rename is a type error in one place instead of silent drift:
+
+```ts
+import { addToCart, removeFromCart } from "./actions/cart";
+import * as CartActions from "./actions/cart";
+
+revalidate((ctx) => ctx.isAction(addToCart) || undefined); // one action
+revalidate((ctx) => ctx.isAction(addToCart, removeFromCart) || undefined); // several
+revalidate((ctx) => ctx.isAction(CartActions) || undefined); // any action in the module
+```
+
+`ctx.isAction()` (only available on the revalidate predicate's context) returns a
+raw boolean — combine with `|| undefined` for the "revalidate on match, else
+defer" intent. It resolves the reference the same way the router derives
+`actionId` (`$id` in production, `$$id` in dev), so matching
+works in both modes. `actionId` stays available for advanced cases.

package/skills/use-cache/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: use-cache
-description: Function-level caching with "use cache" directive for RSC data functions and components
+description: Function-level caching with the "use cache" directive for RSC data functions and components in @rangojs/router. Use when a single function or component should memoize its own output, not a whole route/segment subtree or HTTP response.
 argument-hint: [profile-name]
 ---
 
@@ -10,6 +10,12 @@ Function-level caching for async server functions and RSC components. Caches
 return values with TTL + stale-while-revalidate. Complementary to the route-level
 `cache()` DSL and build-time `Static()`/`Prerender()`.
 
+## Not this skill if…
+
+- You want to cache a whole route or a rendered subtree of segments — that is
+  the segment-level `cache()` DSL: see `/caching`.
+- You are unsure which cache layer you need — start at `/cache-guide`.
+
 ## Basic Usage
 
 ### File-level (all exports cached with default profile)
@@ -63,12 +69,23 @@ createRouter({
     short: { ttl: 60, swr: 120 },
     long: { ttl: 3600, swr: 7200 },
     products: { ttl: 300, swr: 600, tags: ["products"] },
+    // Opt-in: a stale entry re-executes in the foreground during a server
+    // action's revalidation render (fresh action response), instead of SWR.
+    cms: { ttl: 300, swr: 600, foregroundOnAction: true },
   },
 });
 ```
 
 - `"use cache"` (no name) resolves to `default`.
 - `"use cache: short"` resolves to the `short` profile.
+- `foregroundOnAction: true` (default false): a stale entry serves stale +
+  revalidates in the background on a plain navigation (SWR), but re-executes in
+  the FOREGROUND during a server action's revalidation render so the action
+  response reflects a fresh value (only the store write is deferred). Use it for
+  mutation-related cached data; incidental TTL staleness on an ordinary action
+  stays SWR so the action is not turned into a synchronous cache-refresh barrier.
+  For strong read-your-own-writes after a mutation, prefer `updateTag()` (a hard
+  purge, so the action's own re-render is a fresh foreground miss).
 - Unknown profile names throw at runtime, on the first invocation of the cached
   function (the Vite transform does not validate names at build/boot). The error
   is actionable -- it names the missing profile and shows the `createRouter({
@@ -136,6 +153,13 @@ const locale = cookies().get("locale")?.value ?? "en";
 const data = await getCachedData(locale); // locale is now in the cache key
 ```
 
+The guard does not reach into LOADER bodies consumed inside the cached
+function (`await ctx.use(loader)`): loaders always run fresh, so their reads
+are exempt — but the CONSUMED VALUE is captured into the shared cache entry
+like any other computed data. Same rule across `cache()` and the PPR shell:
+handler/cached-scope consumption = baked copy, client-side `useLoader` = live
+(the consumption-lane rule, `/rango` → Invariants).
+
 ### Side-Effect Guards
 
 These ctx methods **throw** inside a `"use cache"` function because their effects
@@ -329,8 +353,11 @@ export async function getProducts() {
 Writes to the same `SegmentCacheStore` as `cache()` DSL, `Static()`, and `Prerender()`.
 One store, one configuration.
 
-Cache entries (and `cacheProfiles`) can be tagged via `cache({ tags })` or, inside
-a `"use cache"` function, runtime `cacheTag(...tags)`. The built-in
+Cache entries (and `cacheProfiles`) can be tagged via `cache({ tags })` or runtime
+`cacheTag(...tags)`. `cacheTag` has two forms: inside a `"use cache"` function it
+tags that entry; called during a request render outside `"use cache"` it tags the
+request's document/shell artifact (rides `_requestTags`) instead of throwing. The
+built-in
 `MemorySegmentCacheStore` and `CFCacheStore` index by tag. Invalidate on demand
 with `updateTag(...tags)` (awaitable, read-your-own-writes; for server actions) or
 `revalidateTag(...tags)` (background, non-blocking; for route handlers/webhooks).

package/skills/vercel/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vercel
-description: Deploy a Rango app to Vercel Functions (Build Output API v3)
+description: Deploy a Rango app to Vercel Functions (Build Output API v3). Use when deploying a Rango app to Vercel, or asking how the router works with Vercel Functions and the Build Output API.
 argument-hint:
 ---
 

package/skills/view-transitions/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: view-transitions
-description: Configure React View Transitions on layouts, routes, and parallel slots in @rangojs/router
+description: Configure React View Transitions on layouts, routes, and parallel slots in @rangojs/router. Use when navigation should animate smoothly between pages, or wiring up React View Transitions on a route or layout.
 argument-hint: [layout|route|parallel|intercept]
 ---
 
@@ -209,6 +209,10 @@ interface TransitionConfig {
   default?: string | Record<string, string>; // fallback for any phase
   name?: string; // explicit view-transition-name
   viewTransition?: "auto" | false; // boundary opt-out (see below)
+  // Conditional gate, evaluated server-side AFTER the route handler. Return
+  // false to drop this transition for the request, so the navigation streams its
+  // loading() fallback instead of holding. See the gate section below.
+  when?: (ctx: TransitionWhenContext) => boolean;
 }
 ```
 
@@ -217,6 +221,45 @@ interface TransitionConfig {
 - `name` lets you participate in cross-page morphs by name (advanced; you usually don't need this on a layout/route-level wrap).
 - `viewTransition` toggles whether rango places its own `<ViewTransition>` boundary. `"auto"` (default) wraps as described above; `false` opts out — see the next section.
 
+## Conditional transitions (`when`)
+
+`transition({ when })` gates the hold per request. The predicate runs **server-side, AFTER the route handler** and outside any cache scope; return `false` to drop this segment's transition for the request (the navigation streams its `loading()` fallback instead of holding).
+
+Its context mirrors the `revalidate()` predicate args — the same navigation/action metadata — plus `get`/`env` for post-handler reads:
+
+```ts
+import type { TransitionWhenContext } from "@rangojs/router";
+
+// Hold only when the handler marked this request (handler sets, gate reads):
+transition({ when: (ctx) => ctx.get(KeepScroll) === true });
+
+// Hold only when arriving from a specific page (the navigation SOURCE):
+transition({
+  when: ({ currentUrl }) => currentUrl?.pathname.startsWith("/list") === true,
+});
+transition({ when: ({ fromRouteName }) => fromRouteName === "products.list" });
+
+// Hold only after a specific action revalidated the route:
+transition({
+  when: ({ actionId }) => actionId === "src/actions/cart.ts#addToCart",
+});
+```
+
+| field                                                  | meaning                                      | populated                                                                             |
+| ------------------------------------------------------ | -------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `currentUrl` / `currentParams` / `fromRouteName`       | navigation **source**                        | soft nav + action-success; `undefined` on initial full load and action/PE error paths |
+| `nextUrl` / `nextParams`                               | navigation **target**                        | always                                                                                |
+| `toRouteName` (and `fromRouteName`)                    | route **name**                               | when the route is named (undefined for unnamed/auto-generated)                        |
+| `actionId` / `actionUrl` / `actionResult` / `formData` | the server action that triggered this render | action-triggered renders only                                                         |
+| `method`                                               | `"GET"` (nav) / `"POST"` (action)            | always                                                                                |
+| `get` / `env`                                          | read handler/middleware vars + app env       | always                                                                                |
+
+A predicate that throws is reported to `router.onError` (phase `"rendering"`) and treated as no-hold (conservative).
+
+**Same-route content-holds need the transition present on the FIRST render.** The same-route hold works by giving the route a param-agnostic key so a param change reconciles instead of remounting — but that key is established when the route first mounts. A source gate that returns `false` on the initial full load (where `currentUrl`/`currentParams`/`fromRouteName` are undefined) drops the transition before the route mounts, so the route mounts _outside_ a transition scope and **every** later same-route param nav remounts (flashing the skeleton) regardless of what the gate decides on those navs. Write source gates so they hold when there is no source — e.g. `({ currentParams }) => currentParams?.tab !== "raw"` (true on the initial load) rather than `=== "details"` (false on the initial load) — when the same-route content-hold must engage. This only affects same-route param navigations; action-only or cross-route gating is unaffected (no shared param key is in play).
+
+**Prefetch / cache caveat.** The gate runs during resolution, so a **prefetched** navigation decides at prefetch time — `currentUrl`/`currentParams`/`fromRouteName` reflect the page the prefetch fired from, not necessarily the click-time source — and a `cache()`/prerender hit replays the stored transition without re-running the predicate. A source-sensitive gate can therefore be frozen to prefetch/store-time state. This covers ~99% of navigations; if yours must reflect the exact click-time source, source-scope the prefetch (`<Link prefetchKey=":source">`) and don't `cache()` that segment.
+
 ## Opting out of the router boundary (place your own `<ViewTransition>`)
 
 By default a `transition()` segment gets a rango-placed `<ViewTransition>` boundary — a cross-fade of the whole outlet/route. If you'd rather animate specific elements yourself (place `<ViewTransition name="...">` in your components), set `viewTransition: false`. The router then contributes **no boundary of its own** but still:

package/src/browser/event-controller.ts

@@ -249,6 +249,14 @@ export interface EventController {
     resolvedIds?: string[],
   ): void;
   getHandleState(): HandleState;
+  /**
+   * Update ONLY `routeSegmentIds` (what `useSegments` reads) from `matched`,
+   * leaving `data` and `segmentOrder` (what `useHandle` collects over) untouched.
+   * Used while a deferred handle is resolving: the route has changed (so
+   * `useSegments` must reflect the new segment ids) but `useHandle` still holds
+   * its previous value until the deferred snapshot is applied.
+   */
+  setRouteSegmentIds(matched: string[]): void;
 
   // Params operations
   setParams(params: Record<string, string>): void;
@@ -269,6 +277,13 @@ const DEFAULT_ACTION_STATE: TrackedActionState = {
   result: null,
 };
 
+// Shared empty inflight-actions list. getState() hands back this exact reference
+// whenever no action is inflight (the overwhelmingly common case), so the derived
+// snapshot's `inflightActions` is referentially stable across notifies instead of
+// a fresh [] each call. Read-only by contract (consumers only read length/spread),
+// same as the shared DEFAULT_ACTION_STATE.
+const EMPTY_INFLIGHT_ACTIONS: InflightAction[] = [];
+
 /**
  * Check if a subscription ID matches an action's full ID.
  *
@@ -363,7 +378,19 @@ export function createEventController(
   const actionListeners = new Map<string, Set<ActionStateListener>>();
   const handleListeners = new Set<HandleListener>();
 
-  const notify = makeDebouncedNotifier(stateListeners);
+  const notifyStateListeners = makeDebouncedNotifier(stateListeners);
+
+  // Memoized derived snapshot. Every state mutation already funnels through
+  // notify(), so invalidating here (synchronously, before the debounced fire)
+  // means a getState() call between two mutations reuses the same object — an
+  // unchanged state returns the SAME reference — while any real change recomputes
+  // on the next read. Kept null when dirty.
+  let cachedDerivedState: DerivedNavigationState | null = null;
+
+  function notify(): void {
+    cachedDerivedState = null;
+    notifyStateListeners();
+  }
 
   const actionNotifyTimeouts = new Map<string, ReturnType<typeof setTimeout>>();
 
@@ -389,14 +416,21 @@ export function createEventController(
   const notifyHandles = makeDebouncedNotifier(handleListeners);
 
   function getState(): DerivedNavigationState {
-    const inflightActionsList: InflightAction[] = [...inflightActions.values()]
-      .filter((a) => a.phase !== "settling")
-      .map((a) => ({
-        id: a.id,
-        actionId: a.actionId,
-        payload: a.payload,
-        startedAt: a.startedAt,
-      }));
+    if (cachedDerivedState) return cachedDerivedState;
+
+    // Skip the spread/filter/map entirely when idle — the common case — and hand
+    // back the shared frozen empty list for referential stability.
+    const inflightActionsList: InflightAction[] =
+      inflightActions.size === 0
+        ? EMPTY_INFLIGHT_ACTIONS
+        : [...inflightActions.values()]
+            .filter((a) => a.phase !== "settling")
+            .map((a) => ({
+              id: a.id,
+              actionId: a.actionId,
+              payload: a.payload,
+              startedAt: a.startedAt,
+            }));
 
     const hasActiveActions = inflightActionsList.length > 0;
     const isVisibleNavigation =
@@ -406,7 +440,7 @@ export function createEventController(
 
     const isStreaming = activeStreamCount > 0 || state === "loading";
 
-    return {
+    cachedDerivedState = {
       state,
       isStreaming,
       // True when a navigation is active (fetching or streaming, before
@@ -422,9 +456,14 @@ export function createEventController(
           : null,
       inflightActions: inflightActionsList,
     };
+    return cachedDerivedState;
   }
 
   function getActionState(actionId: string): TrackedActionState {
+    // Nothing inflight — skip building/scanning the list and return the shared
+    // idle snapshot (the same reference use-action falls back to).
+    if (inflightActions.size === 0) return DEFAULT_ACTION_STATE;
+
     const entry = [...inflightActions.values()]
       .filter((a) => matchesActionId(actionId, a.actionId))
       .reduce<ActionEntry | undefined>((best, a) => {
@@ -860,6 +899,18 @@ export function createEventController(
     };
   }
 
+  function setRouteSegmentIds(matched: string[]): void {
+    const next = filterRouteSegmentIds(matched);
+    if (
+      next.length === routeSegmentIds.length &&
+      next.every((id, i) => id === routeSegmentIds[i])
+    ) {
+      return;
+    }
+    routeSegmentIds = next;
+    notifyHandles();
+  }
+
   // ========================================================================
   // Subscriptions
   // ========================================================================
@@ -928,6 +979,7 @@ export function createEventController(
     // Handles
     setHandleData,
     getHandleState,
+    setRouteSegmentIds,
 
     // Params
     setParams,

package/src/browser/logging.ts

@@ -1,5 +1,15 @@
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 
+/**
+ * Module-level debug flag for guarding call sites whose debug arguments do
+ * non-trivial work (joins, maps, spreads, object literals). Because the Vite
+ * transform folds INTERNAL_RANGO_DEBUG to a literal, an `if (IS_BROWSER_DEBUG)`
+ * guard is minifier-DCE-able — the whole block drops from the production bundle.
+ * Prefer this over isBrowserDebugEnabled() at hot call sites: a const guard folds
+ * where a function call may not.
+ */
+export const IS_BROWSER_DEBUG: boolean = INTERNAL_RANGO_DEBUG;
+
 interface BrowserLogContext {
   requestId: string;
   txId: string;
@@ -53,3 +63,21 @@ export function debugLog(msg: string, ...args: unknown[]): void {
     console.log(msg, ...args);
   }
 }
+
+/**
+ * Boot-sequence debug log: one line per initial-document step (flight decode,
+ * handle stream, bridge wiring, initial tree build, hydration commit), each
+ * stamped with performance.now() so the gap BEFORE hydrateRoot is visible.
+ * The initial document path was otherwise silent — FE debug only started
+ * talking at the first soft navigation, so a boot stall (e.g. an await that
+ * holds initBrowserApp, and with it hydrateRoot) was invisible.
+ */
+export function bootLog(step: string, details?: Record<string, unknown>): void {
+  if (!INTERNAL_RANGO_DEBUG) return;
+  const prefix = `[Browser][boot] ${step} @ ${Math.round(performance.now())}ms`;
+  if (details) {
+    console.log(prefix, details);
+    return;
+  }
+  console.log(prefix);
+}