@rangojs/router 0.5.2 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -182,6 +182,7 @@
     "prepublishOnly": "pnpm build",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
     "test": "playwright test",
+    "test:preload": "playwright test --config=playwright.preload.config.ts",
     "test:ui": "playwright test --ui",
     "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-basename --project=hmr-prerender --no-deps --workers=1 && RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
     "test:hmr-routes-local": "RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
@@ -191,7 +192,7 @@
   },
   "dependencies": {
     "@types/debug": "^4.1.12",
-    "@vitejs/plugin-rsc": "^0.5.30",
+    "@vitejs/plugin-rsc": "^0.5.31",
     "debug": "^4.4.1",
     "magic-string": "^0.30.17",
     "picomatch": "^4.0.4",
@@ -224,9 +225,9 @@
     "@playwright/test": "^1.49.1",
     "@testing-library/react": ">=16",
     "@vercel/functions": "^3.0.0",
-    "@vitejs/plugin-rsc": "^0.5.30",
-    "react": ">=19.2.6 <20",
-    "react-dom": ">=19.2.6 <20",
+    "@vitejs/plugin-rsc": "^0.5.31",
+    "react": ">=19.2.8 <20",
+    "react-dom": ">=19.2.8 <20",
     "vite": "^8.0.16",
     "vitest": ">=3"
   },

package/skills/breadcrumbs/SKILL.md

@@ -7,8 +7,9 @@ argument-hint: "[setup]"
 # Breadcrumbs
 
 Built-in handle for accumulating breadcrumb items across route segments.
-Each layout/route pushes items via `ctx.use(Breadcrumbs)`, and they are
-collected in parent-to-child order with automatic deduplication by `href`.
+Handlers and loader bodies push items via `ctx.use(Breadcrumbs)`, and they
+are collected in parent-to-child order with automatic deduplication by
+`href`.
 
 ## BreadcrumbItem Type
 
@@ -58,6 +59,32 @@ export const urlpatterns = urls(({ path, layout }) => [
 
 On `/blog/my-post`, breadcrumbs accumulate: `Home > Blog > my-post`.
 
+## Pushing from Loaders
+
+A data-derived crumb belongs where the data lives — the loader body pushes
+with the same API (handler parity), so routes without handlers (`useLoader`
+consumption, `clientUrls()` groups) still build trails:
+
+```typescript
+export const ProductLoader = createLoader(async (ctx) => {
+  "use server";
+  const product = await getProduct(ctx.params.slug);
+
+  const pushCrumb = ctx.use(Breadcrumbs);
+  pushCrumb({ label: "Shop", href: "/shop" });
+  pushCrumb({ label: product.name, href: `/shop/product/${product.slug}` });
+
+  return product;
+});
+```
+
+Two pushes from one segment accumulate in push order (`Shop › product`).
+Delivery follows the loader race model: a push that beats the handler barrier
+is in the SSR'd document; a push after a slow fetch streams and applies
+client-side (`useHandle` re-renders when it lands). To guarantee document
+delivery, register the loader as `loader(Def, { stream: "navigation" })` —
+see `/loader` → "Writing Handles from Loaders".
+
 ## Async Content
 
 The `content` field supports `Promise<ReactNode>` for streaming:
@@ -83,9 +110,10 @@ with React's `use()` hook wrapped in `<Suspense>`.
 
 ### Deferred content (decide now, resolve from a deep component)
 
-When the handler should DECIDE to push a crumb (it holds `ctx`, so the decision
-must land before the handles stream seals) but the value is produced far away — by
-a deep async component, not the handler — call `.defer()` on the push function.
+When the handler should DECIDE to push a crumb early but the value is produced
+far away — by a deep async component, not the handler — call `.defer()` on the
+push function. (If the value comes from a LOADER, skip `.defer()` entirely and
+push from the loader body — see "Pushing from Loaders" above.)
 `ctx.use(Handle)` returns the push function; `.defer(options)` reserves the crumb's
 slot synchronously and returns a **resolver that is push-equal** — you call it
 later, anywhere in the render, with the same argument you'd have passed to the
@@ -140,10 +168,12 @@ On a full/SSR load the value is resolved server-side; on a soft navigation the
 breadcrumbs HOLD the previous resolved value until the deferred value lands, then
 swap in — no blank, no pending entry. If the slot times out to `else: null`/
 undefined, the entry is simply dropped. Use `.defer()` only when even
-`label`/`href` are unknown at handler time — if you know them and only the
-`content` is async, push a concrete item with a `Promise` `content` field instead
-(the `content` field is a nested promise you resolve with `use()` in your
-component; no `.defer()` needed).
+`label`/`href` are unknown at handler time AND the producer is a component,
+not a loader — a loader-produced crumb pushes directly from the loader body
+(add `{ stream: "navigation" }` if it must be in the SSR'd document), and if
+you know `label`/`href` and only the `content` is async, push a concrete item
+with a `Promise` `content` field instead (the `content` field is a nested
+promise you resolve with `use()` in your component; no `.defer()` needed).
 
 ## Consuming Breadcrumbs (Client)
 

package/skills/catalog.json

@@ -33,6 +33,12 @@
       "argumentHint": "[setup]",
       "path": "skills/caching/SKILL.md"
     },
+    {
+      "name": "client-urls",
+      "description": "Define client-component route groups with clientUrls() in a \"use client\" module — no handlers, useLoader at read sites, client-run revalidate predicates, loader-thrown notFound/redirect, loader handle writes, and the stream:\"navigation\" SSR-completeness opt-in. Use when a route group's pages are client components, when building high-navigation-speed UIs (dashboards, admin panels, settings) where transitions must feel instant, when moving data reads from handler ctx.use() to useLoader at consumption sites, or when asking how routes defined in a \"use client\" file work.",
+      "argumentHint": "[setup]",
+      "path": "skills/client-urls/SKILL.md"
+    },
     {
       "name": "cloudflare",
       "description": "Deploy and operate @rangojs/router on Cloudflare Workers with the Cloudflare Vite plugin, typed D1/KV bindings, local migrations, secrets, streaming, preview parity, and built-worker deployment. Use when creating a Cloudflare Rango app, moving a Rango app to Workers, wiring D1 or KV, debugging dev/preview differences, or preparing a Worker deployment.",
@@ -131,7 +137,7 @@
     },
     {
       "name": "loader",
-      "description": "Define data loaders for fetching data in routes with createLoader. Use when pages need per-request data that stays fresh, data should stream while the page renders, or client components need reactive server data.",
+      "description": "Define data loaders for fetching data in routes with createLoader. Use when pages need per-request data that stays fresh, data should stream while the page renders, client components need reactive server data, a loader should throw notFound()/redirect(), set page meta/breadcrumbs from loader data (handle writes), or loader data must be guaranteed in the SSR'd document (stream:\"navigation\").",
       "argumentHint": "[loader]",
       "path": "skills/loader/SKILL.md"
     },

package/skills/client-urls/SKILL.md

@@ -0,0 +1,338 @@
+---
+name: client-urls
+description: Define client-component route groups with clientUrls() in a "use client" module — no handlers, useLoader at read sites, client-run revalidate predicates, loader-thrown notFound/redirect, loader handle writes, and the stream:"navigation" SSR-completeness opt-in. Use when a route group's pages are client components, when building high-navigation-speed UIs (dashboards, admin panels, settings) where transitions must feel instant, when moving data reads from handler ctx.use() to useLoader at consumption sites, or when asking how routes defined in a "use client" file work.
+argument-hint: "[setup]"
+---
+
+# Client route groups with clientUrls()
+
+`clientUrls()` defines a route group inside a `"use client"` module. The
+components are client components, and there are **no handlers at all** — every
+data read is `useLoader` at the consumption site, waiting is scoped by the
+inline `<Suspense>` above each read, and per-loader `revalidate()` predicates
+run in the browser. The server shop pattern — `await ctx.use(ProductLoader)` in
+a handler — is pipeline-blocking by contract: no pending UI can ever cover that
+latency. `clientUrls()` makes that shape unrepresentable.
+
+This is the fastest-transition shape Rango has, and the natural fit for
+dashboard / admin / settings-style apps — high navigation frequency inside one
+layout, mostly tab/param/filter switches. Three things compound: the
+definition also matches in the browser, so a soft navigation presents
+optimistic pending UI immediately (`useOutlet().pending`) with no server
+round-trip to start; browser-run `revalidate()` predicates HOLD data across
+navigations that don't invalidate it (a tab switch re-runs nothing — only the
+decision crosses the wire); and any read that does refresh streams behind its
+own inline boundary instead of gating the commit. Add per-Link prefetch
+(`/links`) and a warmed click lands the complete page instantly.
+
+## Not this skill if…
+
+- You are defining server routes with handlers — that is `urls()`: see
+  `/route`.
+- You want loader mechanics (createLoader, caching a loader, fetchable
+  loaders) — see `/loader`. This skill covers what is _different_ inside
+  `clientUrls()`.
+- You want `useOutlet`/`useLoader`/`useHandle` reference — see `/hooks`.
+
+## The shape
+
+A `clientUrls()` module never ships route-definition code to the server as
+code. The Vite plugin discovers the module (it must be `"use client"`, contain
+`clientUrls(`, and **default-export** the result), evaluates it, and serializes
+a JSON **projection**: patterns, names, options, loader ids, which loaders are
+flagged, loading/transition presence. The server tree materializes real routes
+from that projection — loader stubs resolved by id from the server loader
+registry, your client components referenced but never executed server-side as
+route code. In the browser the same definition matches locally, so soft
+navigations inside the group present optimistic pending UI
+(`useOutlet().pending`) while the canonical partial Flight settles.
+
+Consequences you will hit:
+
+- **Components must be named function values.** `path("/x", HomePage)`, not
+  `path("/x", <HomePage />)` and not an inline arrow — the projection stores a
+  component reference, and an anonymous value throws
+  (`clientUrls() path() expects a named client component value`).
+- **Loaders must be `createLoader()` definitions** whose bodies are
+  `"use server"` — they execute on the server, addressed by id; the client
+  module only imports the definition object.
+- **Everything in the definition must be JSON-projectable.** That is why the
+  unsupported helpers below are rejected rather than silently dropped.
+
+## Defining and mounting
+
+```tsx
+// src/urls/shop.client.tsx
+"use client";
+
+import { Suspense } from "react";
+import { clientUrls, useLoader, Link } from "@rangojs/router/client";
+import { ProductsLoader, ProductLoader } from "@/loaders/products.js";
+
+function ShopLayout() {
+  /* useOutlet().content + chrome */
+}
+function ShopIndex() {
+  /* <Suspense><Grid/></Suspense> */
+}
+function ProductPage() {
+  /* useLoader(ProductLoader) under Suspense */
+}
+
+export default clientUrls(({ path, layout, loader, revalidate }) => [
+  layout(ShopLayout, () => [
+    path("/", ShopIndex, { name: "index" }, () => [loader(ProductsLoader)]),
+    path("/product/:slug", ProductPage, { name: "product" }, () => [
+      loader(ProductLoader, () => [
+        revalidate(
+          ({
+            isAction,
+            currentParams,
+            nextParams,
+            defaultShouldRevalidate,
+          }) => {
+            if (isAction) return false;
+            return currentParams.slug !== nextParams.slug
+              ? defaultShouldRevalidate
+              : false;
+          },
+        ),
+      ]),
+    ]),
+  ]),
+]);
+```
+
+Mount it from the server tree like any module:
+
+```tsx
+// src/urls/index.tsx (server)
+import shopUrls from "./shop.client.js";
+
+include("/shop", shopUrls, { name: "shop" });
+```
+
+Route names compose through the include (`shop.index`, `shop.product`) and
+flow into the generated route map, so `href`/`reverse` and `Handler<"...">`
+typing work exactly as for server routes (`/typesafety`).
+
+## Helpers: what exists inside clientUrls()
+
+| Helper         | Notes                                                                                                                                                          |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `path()`       | Options are `name`, `search`, `trailingSlash`, `ppr` (shell caching — see /ppr skill; loader routes need `loading()` or capture refuses); no response variants |
+| `layout()`     | Must contain at least one `path()`                                                                                                                             |
+| `loader()`     | `loader(Def, use?)` or `loader(Def, { stream: "navigation" }, use?)` — see below                                                                               |
+| `loading()`    | Route/layout-level pending UI; inline `<Suspense>` at read sites is usually better                                                                             |
+| `revalidate()` | Valid **inside a loader() use callback only**; runs in the browser                                                                                             |
+| `transition()` | Data-only ViewTransition config — no `when` (that is a server-executed predicate)                                                                              |
+| `intercept()`  | Dot-local named target in the SAME definition; use may contain `loader()`/`loading()`                                                                          |
+
+`include`, `parallel`, `cache`, `middleware`, `errorBoundary`,
+`notFoundBoundary` **throw** — and that is a design position, not a gap.
+Client route groups are a PERFORMANCE surface (instant presentation, held
+data, streaming reads), not full-feature routing; the server tree around the
+mount is the full-feature router. Put those helpers at or around the
+`include()` mount in the server `urls()` tree: middleware wrapping the mount
+runs for every route in the group; a `notFoundBoundary()` on an enclosing
+server layout catches loader-thrown `notFound()` from the group. (Caching
+still reaches the group's data the right way: `"use cache"` inside a loader
+body — the loaders stay the live layer, the expensive function is what
+caches.)
+
+Boundaries are a deliberate exclusion, not a projection limitation: the
+server-tree boundary around the mount gives group-scoped custom UI with the
+uniform server-resolved envelope (PE/no-JS correct), and INSIDE the group
+plain React error boundaries just work — every component is a client
+component, and a streamed loader rejection throws to the boundary above its
+`useLoader` read (siblings keep reading it from `error`). Per-read boundary +
+inline Suspense is the clientUrls idiom; a route-level DSL boundary would be
+the same regression `loading()` is relative to inline Suspense.
+
+## Outer layouts and middleware across group navigations
+
+With the common shape — `layout(<AdminRscLayout />, () => [middleware(requireAdmin), include("/admin", adminUrls)])` — middleware and layout handlers ride
+DIFFERENT schedules:
+
+- **Middleware runs on EVERY canonical request**, not just the first
+  encounter. Every navigation inside the group — including a tab switch whose
+  loaders all hold — still sends the canonical partial request (it commits
+  URL/history and carries the revalidation decisions), and middleware wraps
+  each one: `requireAdmin` re-authorizes every navigation, and its
+  `ctx.set()` variables are fresh for the group's loaders on every pass. The
+  instant feel comes from held data and optimistic presentation, not from
+  skipping the server.
+- **The outer layout handler does NOT re-run on within-group navigations** —
+  partial rendering holds its segment (and the parent chain skips on actions
+  by default). Layout-rendered data that must track the group belongs in
+  middleware `ctx.set()`, not the layout body.
+- The only thing that precedes middleware is the optimistic branch
+  (destination `loading()` / `useOutlet().pending`) — presentation, never
+  authorization.
+
+All three pinned by dev + production e2e in the router repository (a
+middleware-stamped header per request, a layout run-count stamp held across
+navigations).
+
+## Revalidation runs in the browser
+
+A server-tree `revalidate()` predicate executes on the server. A `clientUrls()`
+predicate is client-module code, so it executes **in the browser** with
+client-computable args — `currentUrl`, `nextUrl`, `currentParams`,
+`nextParams`, `defaultShouldRevalidate`, `stale`, `isAction`, `actionId` — and
+only its _decision_ crosses the wire with the navigation request. Requests that
+carry no decisions (no-JS, progressive enhancement, prefetch, document loads)
+follow the locked server defaults.
+
+Two scars worth copying:
+
+- A blunt `() => false` keeps serving the OLD product on product→product
+  navigations (same route, new param). Make predicates param-sensitive:
+  return `defaultShouldRevalidate` when the identifying param changed.
+- One action, per-loader outcomes: a cart badge loader revalidates on actions
+  (`isAction ? defaultShouldRevalidate : false`) while product/related loaders
+  hold — three freshness outcomes in a single commit, decided per loader.
+
+## Loaders are full citizens: signals and handles
+
+Everything a DSL loader can do in the server tree works here — the loader body
+is server code either way.
+
+**Authority signals.** A loader may `throw notFound()` or
+`throw redirect(url)`:
+
+```ts
+export const ProductLoader = createLoader(async (ctx) => {
+  "use server";
+  const moved = LEGACY_SLUGS[ctx.params.slug];
+  if (moved) throw redirect(`/shop/product/${moved}`);
+  if (!(await exists(ctx.params.slug))) notFound(`No "${ctx.params.slug}"`);
+  return getProduct(ctx.params.slug);
+});
+```
+
+On a document load, `notFound()` streams the resolved not-found UI in the
+envelope and _opportunistically_ sets a real 404 status — the status write only
+wins if the rejection settles before the document Response is constructed (a
+fast, pre-fetch existence check usually wins; see `stream: "navigation"` below
+for the deterministic version). On navigations the 404 UI swaps in with the
+URL preserved. A loader `redirect()` is always a client-side navigate — there
+is no document-lane 302 from loaders; pre-stream redirect authority belongs to
+middleware.
+
+**Handle writes.** `ctx.use(Handle)` from the loader body is the WRITE, with
+handler parity — `ctx.use(Meta)({ title })` pushes exactly like a handler
+push. Reads moved to `ctx.get(handle)`, gated behind `await ctx.rendered()`.
+Delivery follows the race model: pushes that settle before the handler barrier
+ride the SSR handle snapshot; later ones stream and apply post-hydration
+(document loads) or progressively (navigations). See `/loader` for the full
+contract.
+
+## `stream: "navigation"` — the SSR-completeness opt-in
+
+By default every loader streams on every render, so nothing a slow loader
+produces is _guaranteed_ to be in the SSR'd HTML — data SSRs as the Suspense
+fallback, a late handle push applies post-hydration, a late `notFound()` loses
+the status race. When the loader feeds something that must exist in the
+document — `<head>` meta via a handle, or a real 404 status — flag it:
+
+```ts
+path("/product/:slug", ProductPage, { name: "product" }, () => [
+  loader(ProductLoader, { stream: "navigation" }, () => [revalidate(productData)]),
+  loader(RelatedLoader),   // untouched: still streams behind its boundary
+]),
+```
+
+The name says WHERE streaming still applies, not that it is disabled: document
+renders await this loader before first flush (data settled — no fallback
+paints; handle pushes beat the barrier snapshot; a thrown `notFound()` is a
+deterministic real 404, no warm-up race); client navigations stream exactly as
+before. Scoped per loader — the flagged loader awaits only itself, siblings
+keep streaming.
+
+Constraints:
+
+- A flagged loader must not `await ctx.rendered()` (or read handles via
+  `ctx.get(handle)`, which rendered() gates) — the document render awaits the
+  loader _before_ the render barrier resolves, so that wait is a cycle by
+  construction. It throws a deadlock error naming the fix.
+- `intercept()` loaders reject the flag — intercepts render on client
+  navigations only, so a document-render await can never apply.
+- It does not change PPR capture behavior: capture renders mask loaders and
+  skip the await.
+
+Every document load pays the flagged loader's latency before first byte —
+that is the point, but it is a real cost. Keep flagged loaders fast (existence
+checks before expensive fetches) and flag the loaders that need it, not the
+route.
+
+Pinned end to end by dev + production e2e in the router repository.
+
+## Intercepts
+
+```tsx
+export default clientUrls(({ path, intercept, loader, loading }) => [
+  path("/items", ItemsIndex, { name: "index" }),
+  path("/items/:id", ItemDetail, { name: "detail" }),
+  intercept("@modal", ".detail", ItemModal, () => [
+    loader(ItemLoader),
+    loading(<ModalSkeleton />),
+  ]),
+]);
+```
+
+Compared to the server `intercept()` (`/intercept`): the target must be a
+dot-local NAMED route in the same definition, there is no `when` selector and
+no middleware, and the use callback accepts `loader()`/`loading()` only —
+every field must be JSON-projectable. Scoping is module-local: only
+navigations originating inside this `clientUrls()` group render the intercept;
+a hard load of the target URL renders the full route.
+
+## Pitfalls
+
+- **Duplicate patterns or names throw** at definition time, per definition.
+- **`layout()` with no `path()` inside throws** — a client layout exists only
+  to wrap routes.
+- **`loading()` vs inline Suspense:** same-route SEARCH navigations
+  (filters, tabs) hold previous content by default — the canonical commit
+  runs in a `startTransition` when no new segments mount, and the wrapping
+  layout sees `useOutlet().pending === true` for the held window; a
+  route-level `loading()` no longer re-flashes there. PARAM navigations
+  still remount (fresh skeleton, fresh state) unless the route declares
+  `transition()` — that opt-in drops the param from the segment key. Inline
+  `<Suspense>` above each `useLoader` read is still the finer-grained tool
+  when different reads on one route should wait independently.
+- **Two parallel loaders with equal latency look "SSR'd" together.** Loaders
+  kick off in parallel, so awaiting one (`stream: "navigation"`) gives
+  same-or-faster siblings time to settle coincidentally. Do not read "it was
+  in the HTML once" as a guarantee — only the flagged loader is guaranteed.
+- **Hook semantics shift inside a group.** `usePathname` is ABSOLUTE (mount
+  included) — never compare it to your own `path()` patterns; build local
+  links with `useHref()` (`groupHref("/items/1")` composes the mount).
+  `useRouter().push("cart")` (RELATIVE,
+  no leading slash) resolves against the mount; `push("/x")` stays
+  app-absolute by design (never auto-prefixed). `useSearchParams` carries REAL
+  values during SSR (live request seeds the SSR store; on ppr routes the
+  capture/resume renders seed the shell key's own sorted search — search is
+  part of shell identity, so static-part reads are legal).
+  `useNavigation`/`useLinkStatus` report the canonical nav, but a reader
+  inside optimistically-swapped content (destination WITH `loading()`)
+  unmounts at click — put status readers in surviving chrome. Errors: wrap
+  throwers in the client `ErrorBoundary`; `useFetchLoader` works unchanged
+  (route-independent lane; `revalidate()` deliberately not consulted).
+  Pinned in the router repo's client-urls hook-probe e2e.
+- **Editing the module in dev:** projections refresh via HMR discovery; if a
+  route-shape edit ever serves stale routes, restart dev — and if you are
+  developing the router itself, rebuild the router dist before `pnpm dev`
+  (the discovery machinery ships compiled).
+
+## Reference app
+
+The router repository (not shipped in this package) carries a canonical
+consumer at `tests/vite-rsc-demo/src/urls/client-shop.client.tsx`: layout +
+index + product routes, param-sensitive predicates, action-scoped cart
+revalidation, loader-thrown `notFound()`/`redirect()`, loader-written
+Meta/Breadcrumbs, viewport prefetch on cards, and the `stream: "navigation"`
+fixtures — with e2e suites next to it pinning each contract in dev and
+production. The sections above are self-contained; the app is corroboration,
+not required reading.

package/skills/comparison/references/framework-comparison.md

@@ -601,8 +601,12 @@ the current state for a known no-op.
 TanStack Router is the real peer here (`preload="intent|viewport|render"`,
 `preloadDelay`, `preloadStaleTime`); Rango's edge is the resource-aware
 idle + image-ready gating and RSC-payload reuse. Next has an internal prefetch
-scheduler, but its public `<Link prefetch>` surface does not expose Rango's choice
-of trigger and resource gates. Waku has manual route prefetching plus experimental
+scheduler — the machinery behind its "instant navigations" pitch — but its
+public `<Link prefetch>` surface does not expose Rango's choice of trigger and
+resource gates. Rango's counterpart to instant navigations is the same
+outcome, spelled explicitly: a viewport/hover-warmed Link commits its
+prefetched payload as a whole on click, so the complete page lands with no
+fetch waterfall. Waku has manual route prefetching plus experimental
 `unstable_prefetchOnEnter` / `unstable_prefetchOnView` Link triggers, but without
 this resource-aware policy layer.
 
@@ -613,10 +617,14 @@ excluded from an enclosing segment cache and resolve on every request unless the
 loader itself explicitly opts into `cache()`. They may safely read `cookies()`,
 `headers()`, request context, and `env` because loader execution is outside the
 cached shell. Loaders run in parallel, stream independently under `loading()`
-boundaries, compose server-side via `ctx.use(OtherLoader)`, and can
-`await ctx.rendered()` to read handle data after the render settles. Reads happen
-through `useLoader` in a client component (including its SSR pass) or
-`useFetchLoader` for standalone client fetches. "Fetchable" loaders are callable
+boundaries, compose server-side via `ctx.use(OtherLoader)`, and carry
+route-level authority: they can throw `notFound()`/`redirect()`, WRITE handles
+(`ctx.use(Meta)({ title })` — data-derived page metadata pushed from the data's
+producer), read handle data after the render settles (`ctx.get(handle)` behind
+`await ctx.rendered()`), and opt into `loader(Def, { stream: "navigation" })`
+so a document render awaits them before first flush (deterministic SSR'd data,
+meta, and 404 status). Reads happen through `useLoader` in a client component
+(including its SSR pass) or `useFetchLoader` for standalone client fetches. "Fetchable" loaders are callable
 endpoints with their own middleware and GET/POST/PUT/PATCH/DELETE bodies.
 
 One sharp edge is worth stating because the distinction matters: a cached handler
@@ -682,12 +690,18 @@ that no loader-before-render has:
 - it is **standalone and composable**, not route-coupled — one `createLoader()`
   read by many segments, composed via `ctx.use`, or exposed as a fetchable endpoint;
 - it **streams as a hole, not a gate** — concurrent, Suspense-resolved under
-  `loading()`, so the shell never blocks on it;
+  `loading()`, so the shell never blocks on it (and gating is a deliberate
+  per-loader opt-in — `{ stream: "navigation" }` awaits ONE loader on document
+  renders while the rest keep streaming — not the model's default);
 - it is **client-addressable and refreshable** independent of navigation (`key`,
   `refreshGroup`, `useRefreshLoaders`), behaving like a built-in, server-defined
   data cell with zero loader logic in the client bundle;
-- it can **read render output** via `await ctx.rendered()` — a loader that depends
-  on what the render produced, which a strictly before-render model cannot express.
+- it carries **route authority and document side-effects** — thrown
+  `notFound()`/`redirect()` and handle writes (page meta, breadcrumbs) travel
+  with the data unit itself, not with a route-coupled function beside it;
+- it can **read render output** via `ctx.get(handle)` behind
+  `await ctx.rendered()` — a loader that depends on what the render produced,
+  which a strictly before-render model cannot express.
 
 The fair objections, and why they do not collapse the distinction:
 

package/skills/hooks/SKILL.md

@@ -28,7 +28,7 @@ the one for your case.
 | Stable router actions (push/replace/refresh/…)     | `useRouter()`               | [`./navigation.md`](./navigation.md)                 |
 | Current URL path & matched segments                | `useSegments()`             | [`./navigation.md`](./navigation.md)                 |
 | Pending state inside a `<Link>`                    | `useLinkStatus()`           | [`./navigation.md`](./navigation.md)                 |
-| Loader data (strict, guaranteed)                   | `useLoader()`               | [`./data.md`](./data.md)                             |
+| Loader data (streams; suspends until it lands)     | `useLoader()`               | [`./data.md`](./data.md)                             |
 | Loader data with on-demand fetch                   | `useFetchLoader()`          | [`./data.md`](./data.md)                             |
 | Refresh multiple loaders across groups             | `useRefreshLoaders()`       | [`./data.md`](./data.md)                             |
 | Accumulated handle data from route segments        | `useHandle()`               | [`./handle-and-actions.md`](./handle-and-actions.md) |
@@ -69,7 +69,7 @@ the one for your case.
 | ------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------ |
 | `useParams()`             | Route params                                                   | `Readonly<T>` (default `Record<string, string>`) or selected value |
 | `usePathname()`           | Current pathname                                               | `string`                                                           |
-| `useSearchParams()`       | URL search params                                              | `ReadonlyURLSearchParams`                                          |
+| `useSearchParams()`       | URL search params (read + write)                               | `[ReadonlyURLSearchParams, SetSearchParams]` (RR-style tuple)      |
 | `useHref()`               | Mount-aware href                                               | `(path) => string`                                                 |
 | `useMount()`              | Current include() mount path                                   | `string`                                                           |
 | `useReverse()`            | Local reverse for imported routes                              | `(name, params?, search?) => string`                               |

package/skills/hooks/data.md

@@ -2,7 +2,7 @@
 
 ### useLoader()
 
-Access loader data (strict - data guaranteed):
+Access loader data (strict — data guaranteed once the read returns):
 
 ```tsx
 "use client";
@@ -13,13 +13,22 @@ function ProductPrice() {
   const { data, isLoading, error } = useLoader(ProductLoader);
 
   // data: T (guaranteed - throws if not in context)
-  // isLoading: boolean
+  // isLoading: boolean (refetch/load() states — NOT the initial streamed read)
   // error: Error | null
 
   return <span>${data.price}</span>;
 }
 ```
 
+**Loaders stream, and `useLoader` implicitly suspends.** A first read whose
+loader data has not streamed in yet suspends to the nearest `<Suspense>`
+boundary (or the route's `loading()`) — it does NOT render with
+`isLoading: true`. Put a boundary above every read whose loader can be slow;
+`isLoading` covers later refetches (`load()`, key/group refreshes). Once the
+component renders, `data` is present. (On document loads a loader registered
+with `{ stream: "navigation" }` is already settled at first paint, so its
+reads never suspend there — see `/loader`.)
+
 **Precondition**: Loader must be registered on route via `loader()` helper.
 
 Loaders can also be passed as props from server to client components:

package/skills/hooks/handle-and-actions.md

@@ -30,6 +30,13 @@ function BreadcrumbNav() {
 const lastCrumb = useHandle(Breadcrumbs, (data) => data.at(-1));
 ```
 
+Writers: handlers AND loader bodies — `ctx.use(Handle)` returns the push
+function in each (middleware has no handle APIs). Loader pushes follow a delivery race (settle before
+the handler barrier → in the SSR'd document; later → applied client-side), and
+`loader(Def, { stream: "navigation" })` makes them deterministic in the
+document. See `/loader` → "Writing Handles from Loaders". `useHandle`
+re-renders on every handle update, late loader pushes included.
+
 Handles can be passed as props from server to client components:
 
 ```tsx

package/skills/hooks/outlets.md

@@ -22,20 +22,41 @@ function DashboardLayout({ children }: { children?: React.ReactNode }) {
 
 ### useOutlet()
 
-Access outlet content programmatically:
+Access outlet content and its client-route presentation state programmatically:
+
+```ts
+interface OutletState {
+  readonly content: ReactNode;
+  readonly pending: boolean;
+}
+```
 
 ```tsx
 "use client";
 import { useOutlet } from "@rangojs/router/client";
 
 function ConditionalLayout() {
-  const outlet = useOutlet();
-  // ReactNode | null
+  const { content, pending } = useOutlet();
 
-  return outlet ? (
-    <div className="with-content">{outlet}</div>
+  return content ? (
+    <div className="with-content" aria-busy={pending}>
+      {content}
+    </div>
   ) : (
     <div className="empty">No content</div>
   );
 }
 ```
+
+Migration from the old bare-node return is `const { content, pending } =
+useOutlet()`, then render `content` where you previously rendered the hook result.
+`<Outlet />` itself is unchanged.
+
+`pending` is narrow. After hydration, a `clientUrls()` layout receives `true`
+while a browser-local match to a different client route beneath it is presenting
+optimistic loading or retaining the current branch until canonical partial Flight
+settles. It clears on commit, error, redirect, cancellation, or supersession. It
+is `false` during SSR and does not describe ordinary server-route navigation,
+prefetch, generic Suspense, unrelated actions, or a params/search change that
+keeps the same client route record. Use `useNavigation()`, `useLinkStatus()`, or
+loader state for those scopes.