@rangojs/router 0.5.1 → 0.6.0

package/skills/ppr/SKILL.md

@@ -121,9 +121,9 @@ At capture the pending fetch cannot win the task-quantized quiet window, so
 the boundary postpones — fallback in the frozen prelude, value resumed fresh
 on every HIT. This is the PHYSICS class from the hole doctrine below, and it
 is exactly how an existing Suspense-shaped tree (e.g. migrated from Next.js
-PPR) works with zero restructuring. The e2e proof is
-`e2e/test-app/src/components/ShellPhysicsValue.tsx` — a promise hole living in
-a LAYOUT with no loader registration at all.
+PPR) works with zero restructuring. The e2e proof lives in the router
+repository (not shipped in this package): a promise hole living in a LAYOUT
+with no loader registration at all.
 
 A route WITHOUT the `ppr` option is pure axis 1: no store read, no capture, no
 logs, zero cost. `ppr` is per page route — declaring it on a layout is not
@@ -658,9 +658,19 @@ Three levers, in preference order:
    lane — masked at capture, fresh per serve — at the cost of a fallback in
    the shell.
 
-Head material (Meta) generally cannot be a hole — the head is shell — so its
-promises bake by design; make them cheap with lever 2. `bakeWaitMs` on the
-capture debug event tells you what each capture actually paid.
+Head material (Meta) pushed by HANDLERS cannot be a hole — the head is shell —
+so those promises bake by design; make them cheap with lever 2. `bakeWaitMs`
+on the capture debug event tells you what each capture actually paid. A
+LOADER-pushed Meta is different: loaders are masked at capture, so the push
+happens at request time and applies client-side (`metadata.handlesLate`) — it
+is never in the cached shell's head, by construction.
+
+One flag to know about here: `loader(Def, { stream: "navigation" })` (the
+document-render await, `/loader`) is **inert under PPR** — capture renders
+mask loaders and skip the await, and a shell HIT flushes the stored prelude
+before loaders resolve. Flagging a loader on a `ppr` route does not bake it
+into the shell and does not delay HIT serves; the flag only governs ordinary
+(axis-1) document renders.
 
 ## Execution matrix
 

package/skills/prerender/SKILL.md

@@ -553,10 +553,14 @@ Passthrough entries are logged distinctly:
 Loaders on pre-rendered routes run at request time. They are bundled normally
 and need `cache()` for caching. Do not use build-only APIs in loaders.
 
-### Handle data is frozen
-
-Handle values pushed via `ctx.use()` during pre-rendering are baked into the
-Flight payload. They do not update at request time.
+### Build-time handle data is frozen
+
+Handle values pushed via `ctx.use()` DURING pre-rendering (handler pushes at
+build) are baked into the Flight payload and do not update at request time.
+Loader pushes are the exception by construction: loaders run live at request
+time (previous section), so a loader-pushed handle (a data-derived Meta title,
+say) is request-time data — delivery follows the loader race model, see
+`/loader` → "Writing Handles from Loaders".
 
 ### Server actions work normally
 

package/skills/rango/SKILL.md

@@ -95,23 +95,26 @@ stated, greppable contract.
 
 ## Pick a primitive
 
-| I need to…                              | Use                                | Skill                   |
-| --------------------------------------- | ---------------------------------- | ----------------------- |
-| render data fresh every request         | `loader()` + `useLoader()`         | /loader                 |
-| cache a rendered subtree                | `cache()` on a segment             | /caching                |
-| cache one function/component's result   | `"use cache"`                      | /use-cache              |
-| cache a loader's data                   | `loader(L, () => [cache()])`       | /loader, /caching       |
-| re-render a segment after an action     | `revalidate()`                     | /loader                 |
-| mutate                                  | `"use server"` action              | /server-actions         |
-| debug a slow request                    | `debugPerformance` / telemetry     | /observability          |
-| share config across routes              | factory returning a helper array   | /composability          |
-| compose a sub-app / module              | `include()`                        | /route                  |
-| modal / soft navigation                 | `intercept()`                      | /intercept              |
-| pre-render a route at build time        | `Prerender(...)` wrapper           | /prerender              |
-| feed live loaders from a cached shell   | replayed handle + `ctx.rendered()` | /shell-manifest         |
-| cache the HTML shell, keep loaders live | `ppr` path option                  | /ppr                    |
-| choose in-function vs CDN caching       | deployment cache boundary          | /deployment-caching     |
-| stream SSE / upgrade a WebSocket        | `path.stream()` / `path.any()`     | /streams-and-websockets |
+| I need to…                              | Use                                   | Skill                   |
+| --------------------------------------- | ------------------------------------- | ----------------------- |
+| render data fresh every request         | `loader()` + `useLoader()`            | /loader                 |
+| cache a rendered subtree                | `cache()` on a segment                | /caching                |
+| cache one function/component's result   | `"use cache"`                         | /use-cache              |
+| cache a loader's data                   | `loader(L, () => [cache()])`          | /loader, /caching       |
+| re-render a segment after an action     | `revalidate()`                        | /loader                 |
+| mutate                                  | `"use server"` action                 | /server-actions         |
+| debug a slow request                    | `debugPerformance` / telemetry        | /observability          |
+| share config across routes              | factory returning a helper array      | /composability          |
+| compose a sub-app / module              | `include()`                           | /route                  |
+| modal / soft navigation                 | `intercept()`                         | /intercept              |
+| route group of client components        | `clientUrls()` in `"use client"`      | /client-urls            |
+| set meta/breadcrumbs from loader data   | `ctx.use(Handle)` in the loader       | /loader                 |
+| guarantee loader output in the SSR HTML | `loader(L, { stream: "navigation" })` | /loader                 |
+| pre-render a route at build time        | `Prerender(...)` wrapper              | /prerender              |
+| feed live loaders from a cached shell   | replayed handle + `ctx.rendered()`    | /shell-manifest         |
+| cache the HTML shell, keep loaders live | `ppr` path option                     | /ppr                    |
+| choose in-function vs CDN caching       | deployment cache boundary             | /deployment-caching     |
+| stream SSE / upgrade a WebSocket        | `path.stream()` / `path.any()`        | /streams-and-websockets |
 
 ## Invariants
 
@@ -243,6 +246,7 @@ Grouped by concern — read when you need to…
 | ------------------------- | -------------------------------------------------------------------------- |
 | `/router-setup`           | Create and configure the RSC router                                        |
 | `/route`                  | Define routes with `urls()`, `path()`, and `include()`                     |
+| `/client-urls`            | Client-component route groups with `clientUrls()` — no handlers            |
 | `/layout`                 | Layouts that wrap child routes                                             |
 | `/parallel`               | Multi-column layouts and sidebars                                          |
 | `/intercept`              | Modal/slide-over patterns for soft navigation                              |

package/skills/react-compiler/SKILL.md

@@ -163,6 +163,6 @@ should find **none** — that is the client-only contract.
 ## Reference
 
 A worked, tested wiring (dev + production e2e markers, incl. the client-only
-contract) lives in the `@rangojs/router` repo: `docs/react-compiler.md` and the
-`react-compiler.test.ts` files under `e2e/e2e-basic`, `tests/cloudflare-basic`,
-and `tests/vite-rsc-demo`.
+contract) lives in the `@rangojs/router` repository — not shipped in this
+package: `docs/react-compiler.md` and the `react-compiler.test.ts` files under
+`e2e/e2e-basic`, `tests/cloudflare-basic`, and `tests/vite-rsc-demo`.

package/skills/response-routes/SKILL.md

@@ -289,9 +289,11 @@ has no response payload metadata, so response routes resolve to `never`:
 // router.tsx
 export const router = createRouter({ document: Document }).routes(urlpatterns);
 
+type AppRoutes = typeof router.routeMap;
+
 declare global {
   namespace Rango {
-    interface RegisteredRoutes extends typeof router.routeMap {}
+    interface RegisteredRoutes extends AppRoutes {}
   }
 }
 ```
@@ -480,7 +482,7 @@ type Stats = RouteResponse<typeof blogApiPatterns, "stats">;
 // = { views: number; visitors: number }
 
 // After mounting -- names get prefixed.
-// Rango.PathResponse needs `RegisteredRoutes extends typeof router.routeMap` (see above),
+// Rango.PathResponse needs the RegisteredRoutes augmentation (see above),
 // otherwise it resolves to never.
 type BlogStats = Rango.PathResponse<"/blog/api/stats">;
 // = { views: number; visitors: number }

package/skills/route/SKILL.md

@@ -358,8 +358,11 @@ path("/moved", () => redirect("/new-location", 301), { name: "moved" });
 > **Redirecting from a route with `loading()`:** an `async` handler that returns
 > a `Response`/`redirect()` on a route that also declares `loading()` is streamed,
 > so the redirect is rendered into the RSC stream instead of becoming an HTTP
-> redirect. Issue the redirect from `middleware`, a loader, or a **synchronous**
-> handler return instead. (Dev logs a warning if this is hit.)
+> redirect. For a real HTTP redirect, issue it from `middleware` or a
+> **synchronous** handler return — pre-stream redirect authority belongs there.
+> (A loader `throw redirect()` also navigates the user, but it is ALWAYS a
+> client-side replace on document loads — 200 document, never a 302; see
+> `/loader` → "Loader Authority". Dev logs a warning if this is hit.)
 
 ### Redirect with location state
 

package/skills/router-setup/SKILL.md

@@ -347,12 +347,19 @@ Two distinct 404 scenarios:
 ```typescript
 import { notFound } from "@rangojs/router";
 
-// In a handler or loader
+// In a handler
 path("/product/:slug", async (ctx) => {
   const product = await db.getProduct(ctx.params.slug);
   if (!product) notFound("Product not found");
   return <ProductPage product={product} />;
 });
+
+// In a loader — data-dependent authority lives with the data
+export const ProductLoader = createLoader(async (ctx) => {
+  "use server";
+  if (!(await exists(ctx.params.slug))) notFound("Product not found");
+  return getProduct(ctx.params.slug);
+});
 ```
 
 ### Fallback chain for `notFound()`
@@ -364,7 +371,14 @@ When `notFound()` is thrown, the router looks for a fallback in this order:
 3. **`notFound`** — from `createRouter()` config (same component used for no-route-match)
 4. **Default `<h1>Not Found</h1>`** — built-in fallback
 
-All cases set HTTP 404 status.
+Handler and no-match cases set HTTP 404 status. A LOADER-thrown `notFound()`
+on a document load always streams the resolved not-found UI, but the 404
+STATUS is opportunistic — real only when the rejection settles before the
+document Response is constructed (loaders stream). Register the loader as
+`loader(Def, { stream: "navigation" })` to make the 404 status deterministic;
+on client navigations the 404 UI swaps in with the URL preserved (payload
+stays 200 — the client owns presentation there). See `/loader` → "Loader
+Authority".
 
 ### notFoundBoundary
 

package/skills/scripts/SKILL.md

@@ -7,9 +7,9 @@ argument-hint: "[vendor]"
 # Scripts
 
 Inject `<script>` tags into the document the idiomatic Rango way: push a config
-from a **server** route/layout handler with `ctx.use(Script)(config)`, and render
-them with the built-in **`<Scripts />`** component (the `Meta` / `<MetaTags>`
-pair, but for scripts). The request CSP **nonce is applied automatically to
+from a **server** route/layout handler — or a loader body — with
+`ctx.use(Script)(config)`, and render them with the built-in **`<Scripts />`**
+component (the `Meta` / `<MetaTags>` pair, but for scripts). The request CSP **nonce is applied automatically to
 document-rendered scripts** — you never read or pass it. (The one exception is an
 async script first encountered on a soft navigation; see the nonce caveat under
 "Execution contract".)
@@ -40,7 +40,7 @@ export function Document({ children }) {
 }
 ```
 
-## Push from a handler
+## Push from a handler (or loader)
 
 `ScriptConfig` is a discriminated union — exactly one of three shapes, so invalid
 combinations are compile errors:
@@ -101,6 +101,15 @@ inert (silently dead) `<script>`. Async configs stay reactive. Reusing an `id`
 shapes the INITIAL document output (last-push-wins) — it does not re-run a script
 during navigation.
 
+> **Loader pushes meet the freeze.** A LOADER push to the Script handle
+> follows the delivery race (`/loader`): it is in the initial HTML only if it
+> settles before the handler barrier. A push that lands after a slow fetch
+> arrives post-hydration — and for an inline/ordered script the frozen set
+> means it is silently dropped. If a loader must contribute an inline script
+> to the document, register it `loader(Def, { stream: "navigation" })` so the
+> document render awaits the push; otherwise push from a handler (or use an
+> `async` config, which stays reactive).
+
 **Nonce caveat for soft-nav async.** The "nonce is applied automatically" claim
 holds for DOCUMENT-RENDERED scripts (they carry the nonce in the SSR HTML). An
 async script first encountered on a soft navigation is injected by React on the
@@ -143,7 +152,7 @@ per-route data into the FIRST (hard-load) page_view server-side — the Script
 handle is collected after handlers run (parent → child, last-wins):
 
 ```ts
-// root layout: generic bootstrap
+// root layout: generic bootstrap (handler push — always pre-barrier)
 ctx.use(Script)({ id: "gtm", children: gtmBootstrap("GTM-XXXX") });
 // a route: same id, with content_group baked in
 ctx.use(Script)({
@@ -176,4 +185,5 @@ Otherwise allow the vendor hosts. For GTM/GA4 (Google's wildcards): `script-src
   `type: "text/partytown"` and wire Partytown's own nonce config manually.
 
 A full GTM + GA4-style integration (page_view on first render + soft nav, nonce,
-ecommerce events) lives in `tests/vite-rsc-demo`.
+ecommerce events) lives in the router repository's `tests/vite-rsc-demo` app
+(not shipped in this package).

package/skills/shell-manifest/SKILL.md

@@ -33,14 +33,18 @@ batched.
 
 1. **Handles record data at render time.** The handler pushes to a handle
    (`ctx.use(Handle)`) while it renders — at build time for `Prerender`, on
-   the cache miss for `cache()`.
+   the cache miss for `cache()`. (Loader bodies can push handles too — see
+   `/loader` — but a loader push is request-time and is NOT part of the
+   replayed artifact; a manifest handle must be pushed by the code that gets
+   frozen with the shell.)
 2. **Replay on every hit.** Handle data is stored with the Flight payload
    and replayed into the handle store on cache/prerender hits — handler code
    does not re-run, but its pushes do.
 3. **Loaders read after the render barrier.** A DSL loader can
    `await ctx.rendered()` (waits for all non-loader segments to settle —
-   fresh render or replay alike), then `ctx.use(Handle)` returns the
-   **collected** handle data.
+   fresh render or replay alike), then `ctx.get(Handle)` returns the
+   **collected** handle data. (`ctx.use(Handle)` in a loader is the WRITE —
+   it returns the push function; reads live on `ctx.get`.)
 
 Loaders are live by default, so the read happens on every request even when
 the shell is a hit.
@@ -90,7 +94,7 @@ import { RenderedProducts } from "../handles/rendered-products";
 export const PriceLoader = createLoader(async (ctx) => {
   "use server";
   await ctx.rendered();
-  const ids = ctx.use(RenderedProducts);
+  const ids = ctx.get(RenderedProducts);
   return db.pricesFor(ids); // Map<string, number> keyed by product id
 });
 ```
@@ -144,15 +148,20 @@ cache({ ttl: 600, tags: ["products"] }, () => [
   Ids, slugs, slot names, variant keys: yes. Anything derived from
   `cookies()`/`headers()`: no.
 - **`ctx.rendered()` is experimental and DSL-loaders-only.** It throws in
-  fetchable/standalone loader calls that run outside a route render.
+  fetchable/standalone loader calls that run outside a route render, in
+  handler-invoked loaders (a handler already awaiting the loader via
+  `ctx.use()` is a detected deadlock), and in loaders registered with
+  `{ stream: "navigation" }` (the document render awaits the loader before
+  the barrier — a cycle by construction; see `/loader`).
 - **The reading loader serializes after the shell.** `await ctx.rendered()`
   deliberately gives up loader/render parallelism — on a miss the loader
   waits for segment resolution; on a hit (the common case for a cached
   shell) replay is immediate and the wait is negligible. A
   `debugPerformance` waterfall shows this loader after the render bar; for
   this pattern that is the contract, not a regression.
-- **`ctx.use(Handle)` before `await ctx.rendered()` throws** in a loader,
-  with an error saying to await the barrier first.
+- **`ctx.get(handle)` before `await ctx.rendered()` throws** in a loader,
+  with an error saying to await the barrier first. (`ctx.use(Handle)` — the
+  push — is legal for the whole loader body, no barrier required.)
 - **Deferred handle values are resolved before storage** (resolve-by-default),
   so the manifest read always sees plain values, never promises.
 

package/skills/testing/SKILL.md

@@ -85,11 +85,11 @@ Each primitive links to its sub-file (API + recipe + caveats).
 | ---------------------------------------------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------- | -------------------------------- |
 | a pure function / `reverse` / `href` / a predicate (`revalidate`, `isAction`)                                                      | unit + types | [`reverse`/`@ts-expect-error`](./reverse-and-types.md)                                        | `@rangojs/router/testing`        |
 | one loader's data logic                                                                                                            | unit (node)  | [`runLoader`](./loader.md)                                                                    | `@rangojs/router/testing`        |
-| a loader's cookie / header / redirect output (auth-loader pattern)                                                                 | unit (node)  | [`runLoaderResult`](./loader.md)                                                              | `@rangojs/router/testing`        |
+| a loader's cookie / header / thrown `redirect()`/`notFound()` / handle-push output                                                 | unit (node)  | [`runLoaderResult`](./loader.md)                                                              | `@rangojs/router/testing`        |
 | one middleware's ordering / short-circuit / cookie+header merge                                                                    | unit (node)  | [`runMiddleware`](./middleware.md)                                                            | `@rangojs/router/testing`        |
 | a `"use server"` action's cookie / header / flash output (even on `throw redirect()`)                                              | unit (node)  | [`runInRequestContext`](./server-actions.md)                                                  | `@rangojs/router/testing`        |
 | a `transition({ when })` gate (keep/drop) against nav source / target / action metadata                                            | unit (node)  | `runTransitionWhen` (`{ kept, whenContext }`; pass `{ ppr: true }` for pre-handler timing)    | `@rangojs/router/testing`        |
-| a handle's `collect`/accumulator, or a seeded handle read                                                                          | unit         | [`collectHandle` / seeded `handles`](./handles.md)                                            | `@rangojs/router/testing`        |
+| a handle's `collect`/accumulator, a seeded handle read, or a loader handle write                                                   | unit         | [`collectHandle` / seeded `handles` / `handlePushes`](./handles.md)                           | `@rangojs/router/testing`        |
 | a CLIENT component reading router context (`useParams`/`useReverse`/`Outlet`/`useNavigation`/`useLoader`)                          | unit (DOM)   | [`renderRoute`](./client-components.md)                                                       | `@rangojs/router/testing/dom`    |
 | a redirect / status / headers / cookies / **response route** (json/text/html/xml/md), no Flight                                    | integration  | [`dispatch`](./response-routes.md)                                                            | `@rangojs/router/testing`        |
 | a real async **Server Component** (assert what it rendered: typed boundary props, server-rendered host content, inlined-vs-island) | RSC unit     | [`renderServerTree` + `findClientBoundaries`/`findElements`](./server-tree.md)                | `@rangojs/router/testing/flight` |

package/skills/testing/client-components.md

@@ -12,6 +12,7 @@ RTL-style stub (peer of React Router's `createRoutesStub` / Expo's `renderRouter
 | ----------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `request`         | `Request \| string`                                                    | Initial location. Only the URL is read (client render — headers/method ignored). Defaults to the leaf spec's static prefix or `"/"`.                                                                                                          |
 | `loaderData`      | `Record<string, unknown>`                                              | Loader data keyed by loader `$$id`. `useLoader(L)` reads `loaderData[L.$$id]`.                                                                                                                                                                |
+| `outletPending`   | `boolean`                                                              | Seed `useOutlet().pending` through each synthetic segment's production `OutletProvider`. Defaults to `false`; this is context seeding, not a simulated navigation/Suspense/action lifecycle.                                                  |
 | `loaders`         | `ReadonlyArray<readonly [LoaderDefinition<any>, unknown]>`             | Seed by REFERENCE: `[loader, data]` pairs. Robust for real `createLoader()` handles whose `$$id` is empty in a bare test. Prefer over `loaderData`.                                                                                           |
 | `params`          | `Record<string, string>`                                               | Explicit params, merged over (and overriding) params extracted from the `request` URL.                                                                                                                                                        |
 | `locationState`   | `ReadonlyArray<readonly [LocationStateDefinition<any, any>, unknown]>` | Seed `useLocationState(def)` by REFERENCE: `[def, value]` pairs; written to `history.state`.                                                                                                                                                  |
@@ -43,6 +44,7 @@ RTL-style stub (peer of React Router's `createRoutesStub` / Expo's `renderRouter
 | `useLocationState`             | SEEDED `history.state` value.                                                                 |
 | `useHandle`                    | SEEDED handle output (globally accumulated).                                                  |
 | `Outlet`                       | Renders the next segment in the chain (layout nesting).                                       |
+| `useOutlet`                    | Next-segment `content` plus SEEDED `options.outletPending`.                                   |
 | `useTheme`                     | Theme; throws without `options.theme` (see caveat).                                           |
 
 ### Returns — `RenderRouteResult`
@@ -110,6 +112,10 @@ it("resolves params + reverse + Outlet through the layout chain", async () => {
 
 - Client tree ONLY. Does NOT catch server/client boundary reference-identity remount bugs, real Flight serialization errors, loader execution, middleware, or handler ordering — those are `renderServerTree` / `renderHandler` / e2e territory. Loader data is SEEDED, never run.
 - `router.navigate()` bypasses the navigation lifecycle, so the controller never leaves `idle`. `useNavigation()` / `useLinkStatus()` / `useAction()` non-idle states (loading/streaming/pending, action result/error) are NOT reachable — test those at e2e.
+- `outletPending` seeds only the production-shaped outlet context. It is useful
+  for the two settled render states of a layout that reads `useOutlet()`, but it
+  does not prove the hydrated `clientUrls()` transition that toggles the value;
+  keep that transition in dev + production e2e.
 - CATCH — streaming `use(promise)` Suspense content (e.g. an async breadcrumb `content: Promise<ReactNode>`): a plain `Promise.resolve(node)` does NOT flush its Suspense retry in RTL/happy-dom, so the DOM stays on the fallback. Assert the PENDING fallback with `new Promise(() => {})`; for the ARRIVED state pass an already-settled promise so `use()` reads it synchronously: `const p = Promise.resolve(node) as any; p.status = "fulfilled"; p.value = node;`. The real pending->resolved transition is an e2e concern.
 - ARIA gotcha — an explicit `role` on a `<Link>` (e.g. `<Link role="tab">` in a tablist) OVERRIDES the implicit `link` role, so `getByRole("link")` finds nothing. Query the explicit role (`getByRole("tab")`) or fall back to `getByText` / `getByTestId` and assert `getAttribute("href")`.
 - `ctx.theme` is undefined unless `theme` is passed; the typed `ctx.search` defaults to `{}` (seed `searchData` on `runLoader`, not here).

package/skills/testing/handles.md

@@ -1,8 +1,8 @@
-# Testing a handle — collectHandle, plus the loader and client read paths
+# Testing a handle — collectHandle, plus the loader read/write and client read paths
 
 **Layer:** unit (node + DOM) · **Import:** `@rangojs/router/testing` (collectHandle), `@rangojs/router/testing/dom` (renderRoute) · **DSL it tests:** a handle e.g. Breadcrumbs/Meta (see `/handler-use`, `/breadcrumbs`)
 
-A handle's `collect`/accumulator (the `createHandle(collect)` argument that maps per-segment pushed values into one accumulated result) is otherwise unreachable — `createHandle` keeps it in a private registry keyed by `$$id`. These three primitives test it from different angles: `collectHandle` runs the REAL registered collect on per-segment values you SEED; `runLoader` seeds the POST-collect accumulated value a loader reads after the barrier; `renderRoute` seeds the RAW pushed values for a client component reading `useHandle`. None of them run the real push -> accumulate -> barrier wiring (that stays e2e).
+A handle's `collect`/accumulator (the `createHandle(collect)` argument that maps per-segment pushed values into one accumulated result) is otherwise unreachable — `createHandle` keeps it in a private registry keyed by `$$id`. These primitives test it from different angles: `collectHandle` runs the REAL registered collect on per-segment values you SEED; `runLoader` seeds the POST-collect accumulated value a loader READS (`ctx.get(handle)` after the barrier); `runLoaderResult(...).handlePushes` records what a loader WRITES (`ctx.use(SomeHandle)({...})`, in push order); `renderRoute` seeds the RAW pushed values for a client component reading `useHandle`. None of them run the real push -> accumulate -> barrier wiring (that stays e2e).
 
 ## API
 
@@ -17,10 +17,10 @@ A handle's `collect`/accumulator (the `createHandle(collect)` argument that maps
 
 ### runLoader option — `handles` — `src/testing/run-loader.ts`
 
-| Field      | Type                                        | Meaning                                                                                                                                                                                                                |
-| ---------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `handles`  | `ReadonlyArray<readonly [Handle, unknown]>` | Seeds the value `ctx.use(SomeHandle)` returns — the POST-collect **ACCUMULATED** value (singular `unknown`), what a loader reads after `await ctx.rendered()`. Matched by handle reference. Pair with `rendered`.      |
-| `rendered` | `boolean \| (() => void \| Promise<void>)`  | Mocks the `ctx.rendered()` barrier (throws by default). `true` resolves it immediately; a function controls timing/side effects. A `ctx.use(handle)` read before the barrier settles throws, exactly as in production. |
+| Field      | Type                                        | Meaning                                                                                                                                                                                                                                                                  |
+| ---------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `handles`  | `ReadonlyArray<readonly [Handle, unknown]>` | Seeds the value `ctx.get(SomeHandle)` returns — the POST-collect **ACCUMULATED** value (singular `unknown`), what a loader reads after `await ctx.rendered()`. Matched by handle reference. Pair with `rendered`.                                                        |
+| `rendered` | `boolean \| (() => void \| Promise<void>)`  | Mocks the `ctx.rendered()` barrier (throws by default). `true` resolves it immediately; a function controls timing/side effects. A `ctx.get(handle)` read before the barrier settles throws, exactly as in production. (`ctx.use(handle)` — the WRITE — is never gated.) |
 
 ### renderRoute option — `handles` — `src/testing/render-route.tsx`
 
@@ -66,7 +66,7 @@ import { RenderedProducts } from "../src/handles"; // a createHandle(...)
 
 const livePricesBody = async (ctx) => {
   await ctx.rendered(); // barrier: handle data is now readable
-  const ids = ctx.use(RenderedProducts) as string[];
+  const ids = ctx.get(RenderedProducts) as string[];
   return ids.map((id) => ({ id, price: 9.99 }));
 };
 
@@ -82,6 +82,27 @@ it("reads the accumulated handle value (seed the OUTPUT, mock the barrier)", asy
 });
 ```
 
+```ts
+// loader-writes-handle.test.ts — a loader PUSHING meta/breadcrumbs (handler parity)
+import { it, expect } from "vitest";
+import { runLoaderResult } from "@rangojs/router/testing";
+import { Meta } from "../src/handles";
+
+const productBody = async (ctx) => {
+  const product = { name: "Widget", slug: "widget" };
+  ctx.use(Meta)({ title: `${product.name} — Shop` });
+  return product;
+};
+
+it("records loader handle writes in push order", async () => {
+  const { result, handlePushes } = await runLoaderResult(productBody);
+  expect(result?.name).toBe("Widget");
+  expect(handlePushes).toEqual([
+    { handle: Meta, value: { title: "Widget — Shop" } },
+  ]);
+});
+```
+
 ```tsx
 // breadcrumb-trail.test.tsx — a client component reading useHandle
 // @vitest-environment happy-dom
@@ -121,7 +142,8 @@ it("renders the seeded trail (seed the INPUT pushes, the collect runs)", async (
 
 - `collectHandle` tests the pure collect/accumulator in ISOLATION (parent -> child segment order, empty arrays filtered to match production). It does NOT run the real push -> accumulate -> barrier wiring — that stays e2e.
 - renderRoute `handles` seeds the CLIENT read path with the RAW pushed values array (`unknown[]`), attached to the leaf segment. Handle data accumulates GLOBALLY (not segment-scoped like loaders), so a LAYOUT reading the same handle sees the seeded values too, not just the leaf route.
-- runLoader `handles` seeds the POST-collect ACCUMULATED value (singular `unknown`) a loader reads after `await ctx.rendered()`; pair with `{ rendered: true }`. Shape contrast: renderRoute feeds the barrier INPUT (pushes[]), runLoader feeds its OUTPUT (the accumulated value).
+- runLoader `handles` seeds the POST-collect ACCUMULATED value (singular `unknown`) a loader reads via `ctx.get(handle)` after `await ctx.rendered()`; pair with `{ rendered: true }`. Shape contrast: renderRoute feeds the barrier INPUT (pushes[]), runLoader feeds its OUTPUT (the accumulated value).
+- Loader WRITES are the other direction: `ctx.use(SomeHandle)({...})` records into `runLoaderResult(...).handlePushes` (push order; a `.defer()` resolver's value is recorded when the resolver runs). Nothing to seed — assert the envelope.
 - The renderRoute path is the CLIENT tree only: it does NOT catch server/client boundary remount bugs, real Flight serialization errors, or loader execution.
 
 ## See also

package/skills/testing/loader.md

@@ -8,62 +8,64 @@
 
 ### Options — `RunLoaderOptions<TEnv>`
 
-| Field           | Type                                                            | Meaning                                                                                                                                                                                                         |
-| --------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `params`        | `Record<string, string>`                                        | Route params; surfaced as `ctx.params` and `ctx.routeParams`.                                                                                                                                                   |
-| `search`        | `Record<string, string>`                                        | Search params; merged into the request URL so `ctx.searchParams` reflects them.                                                                                                                                 |
-| `searchData`    | `Record<string, unknown>`                                       | The TYPED `ctx.search` object a route's search schema would produce. Distinct from `search` (which sets the raw `ctx.searchParams`).                                                                            |
-| `basename`      | `string`                                                        | Router basename surfaced on the context; drives `redirect()` prefixing.                                                                                                                                         |
-| `theme`         | `ThemeConfig \| true`                                           | Theme config in the `createRouter({ theme })` shape (e.g. `true` or `{ themes: [...] }`). Without it `ctx.theme`/`ctx.setTheme` are inert.                                                                      |
-| `env`           | `TEnv`                                                          | Environment bindings surfaced as `ctx.env`.                                                                                                                                                                     |
-| `request`       | `Request \| string`                                             | Override the backing Request. Defaults to a localhost GET.                                                                                                                                                      |
-| `vars`          | `VarsInit`                                                      | Variables a prior middleware would have set (object `{ key: value }`, or `[key, value]` tuples where the key may be a `createVar()` handle).                                                                    |
-| `routeMap`      | `Record<string, string>`                                        | Route name -> pattern map enabling `ctx.reverse()`.                                                                                                                                                             |
-| `routeName`     | `string`                                                        | Matched route name for scoped `.name` reverse resolution.                                                                                                                                                       |
-| `method`        | `string`                                                        | HTTP method surfaced as `ctx.method`. Defaults to `"GET"`.                                                                                                                                                      |
-| `body`          | `unknown`                                                       | Request body surfaced as `ctx.body`.                                                                                                                                                                            |
-| `formData`      | `FormData`                                                      | Form data surfaced as `ctx.formData` (exposed verbatim; no multipart parsing).                                                                                                                                  |
-| `loaders`       | `ReadonlyArray<readonly [LoaderDefinition<any, any>, unknown]>` | Seed `ctx.use(OtherLoader)` by REFERENCE as `[[OtherLoader, data]]` tuples (same shape as `renderHandler`/`renderRoute`). Checked before `use`.                                                                 |
-| `use`           | `UseResolver`                                                   | Dynamic resolver for `ctx.use(OtherLoader)` composition. `loaders` wins when both match.                                                                                                                        |
-| `cacheStore`    | `SegmentCacheStore`                                             | Cache store backing `use cache` functions. Without one, a cached function bypasses and runs uncached (its taint/profile guards never fire).                                                                     |
-| `cacheProfiles` | `Record<string, CacheProfile>`                                  | Cache profiles, the `createRouter({ cacheProfiles })` shape.                                                                                                                                                    |
-| `stateCookie`   | `StateCookieSeed` (`{ prefix?, routerId?, version? }`)          | Customize the rango state cookie a loader calling `invalidateClientCache()` rotates (the name is always seeded — default `rango-state_router_0`).                                                               |
-| `rendered`      | `boolean \| (() => void \| Promise<void>)`                      | Mock the `ctx.rendered()` render barrier so a loader that `await ctx.rendered()`s can be unit-tested. By default `ctx.rendered()` throws. `true` resolves immediately; a function controls timing/side effects. |
-| `handles`       | `ReadonlyArray<readonly [Handle<any, any>, unknown]>`           | Seed the values `ctx.use(SomeHandle)` returns — the ACCUMULATED handle data read after `await ctx.rendered()`. Matched by handle reference.                                                                     |
+| Field           | Type                                                            | Meaning                                                                                                                                                                                                                    |
+| --------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `params`        | `Record<string, string>`                                        | Route params; surfaced as `ctx.params` and `ctx.routeParams`.                                                                                                                                                              |
+| `search`        | `Record<string, string>`                                        | Search params; merged into the request URL so `ctx.searchParams` reflects them.                                                                                                                                            |
+| `searchData`    | `Record<string, unknown>`                                       | The TYPED `ctx.search` object a route's search schema would produce. Distinct from `search` (which sets the raw `ctx.searchParams`).                                                                                       |
+| `basename`      | `string`                                                        | Router basename surfaced on the context; drives `redirect()` prefixing.                                                                                                                                                    |
+| `theme`         | `ThemeConfig \| true`                                           | Theme config in the `createRouter({ theme })` shape (e.g. `true` or `{ themes: [...] }`). Without it `ctx.theme`/`ctx.setTheme` are inert.                                                                                 |
+| `env`           | `TEnv`                                                          | Environment bindings surfaced as `ctx.env`.                                                                                                                                                                                |
+| `request`       | `Request \| string`                                             | Override the backing Request. Defaults to a localhost GET.                                                                                                                                                                 |
+| `vars`          | `VarsInit`                                                      | Variables a prior middleware would have set (object `{ key: value }`, or `[key, value]` tuples where the key may be a `createVar()` handle).                                                                               |
+| `routeMap`      | `Record<string, string>`                                        | Route name -> pattern map enabling `ctx.reverse()`.                                                                                                                                                                        |
+| `routeName`     | `string`                                                        | Matched route name for scoped `.name` reverse resolution.                                                                                                                                                                  |
+| `method`        | `string`                                                        | HTTP method surfaced as `ctx.method`. Defaults to `"GET"`.                                                                                                                                                                 |
+| `body`          | `unknown`                                                       | Request body surfaced as `ctx.body`.                                                                                                                                                                                       |
+| `formData`      | `FormData`                                                      | Form data surfaced as `ctx.formData` (exposed verbatim; no multipart parsing).                                                                                                                                             |
+| `loaders`       | `ReadonlyArray<readonly [LoaderDefinition<any, any>, unknown]>` | Seed `ctx.use(OtherLoader)` by REFERENCE as `[[OtherLoader, data]]` tuples (same shape as `renderHandler`/`renderRoute`). Checked before `use`.                                                                            |
+| `use`           | `UseResolver`                                                   | Dynamic resolver for `ctx.use(OtherLoader)` composition. `loaders` wins when both match.                                                                                                                                   |
+| `cacheStore`    | `SegmentCacheStore`                                             | Cache store backing `use cache` functions. Without one, a cached function bypasses and runs uncached (its taint/profile guards never fire).                                                                                |
+| `cacheProfiles` | `Record<string, CacheProfile>`                                  | Cache profiles, the `createRouter({ cacheProfiles })` shape.                                                                                                                                                               |
+| `stateCookie`   | `StateCookieSeed` (`{ prefix?, routerId?, version? }`)          | Customize the rango state cookie a loader calling `invalidateClientCache()` rotates (the name is always seeded — default `rango-state_router_0`).                                                                          |
+| `rendered`      | `boolean \| (() => void \| Promise<void>)`                      | Mock the `ctx.rendered()` render barrier so a loader that `await ctx.rendered()`s can be unit-tested. By default `ctx.rendered()` throws. `true` resolves immediately; a function controls timing/side effects.            |
+| `handles`       | `ReadonlyArray<readonly [Handle<any, any>, unknown]>`           | Seed the values `ctx.get(SomeHandle)` returns — the ACCUMULATED handle data read after `await ctx.rendered()`. Matched by handle reference. (Loader handle WRITES need no seed — see `runLoaderResult(...).handlePushes`.) |
 
 ### Context — `TestLoaderContext<TEnv>` (what your loader receives)
 
-| Field              | Type                                                                                      | Meaning                                                                                                                                              |
-| ------------------ | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `params`           | `Record<string, string>`                                                                  | Route params (from `opts.params`).                                                                                                                   |
-| `routeParams`      | `Record<string, string>`                                                                  | Same values as `params`.                                                                                                                             |
-| `request`          | `Request`                                                                                 | The backing request.                                                                                                                                 |
-| `searchParams`     | `URLSearchParams`                                                                         | Raw search params (from `opts.search` baked into the URL).                                                                                           |
-| `search`           | `Record<string, unknown>`                                                                 | The TYPED search object (from `opts.searchData`); defaults to `{}`.                                                                                  |
-| `pathname`         | `string`                                                                                  | Request pathname.                                                                                                                                    |
-| `url`              | `URL`                                                                                     | Request URL.                                                                                                                                         |
-| `originalUrl`      | `URL`                                                                                     | Pre-basename-rewrite URL.                                                                                                                            |
-| `env`              | `TEnv`                                                                                    | Environment bindings (from `opts.env`).                                                                                                              |
-| `get`              | `<T>(contextVar: ContextVar<T>) => T \| undefined` / `<T>(key: string) => T \| undefined` | Read a var seeded via `opts.vars` (by `createVar()` handle or string key).                                                                           |
-| `use`              | `(dep) => ...`                                                                            | Resolve `ctx.use(OtherLoader)`/`ctx.use(SomeHandle)`: handle seeds first, then loader seeds, then the `use` resolver, then the real context `use()`. |
-| `method`           | `string`                                                                                  | HTTP method (from `opts.method`, default `"GET"`).                                                                                                   |
-| `body`             | `unknown`                                                                                 | Request body (from `opts.body`).                                                                                                                     |
-| `formData`         | `FormData \| undefined`                                                                   | Form data (from `opts.formData`).                                                                                                                    |
-| `reverse`          | `(name, params?, search?) => string`                                                      | Build a URL; throws unless `opts.routeMap` was passed.                                                                                               |
-| `rendered`         | `() => Promise<void>`                                                                     | The render barrier; throws by default, mocked via `opts.rendered`.                                                                                   |
-| `waitUntil`        | `(p: Promise<unknown>) => void`                                                           | Register background work (no-op accounting in tests).                                                                                                |
-| `executionContext` | `ExecutionContext \| undefined`                                                           | Platform execution context from the backing request; pairs with `waitUntil`.                                                                         |
+| Field              | Type                                                                                      | Meaning                                                                                                                                                                                                                                             |
+| ------------------ | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `params`           | `Record<string, string>`                                                                  | Route params (from `opts.params`).                                                                                                                                                                                                                  |
+| `routeParams`      | `Record<string, string>`                                                                  | Same values as `params`.                                                                                                                                                                                                                            |
+| `request`          | `Request`                                                                                 | The backing request.                                                                                                                                                                                                                                |
+| `searchParams`     | `URLSearchParams`                                                                         | Raw search params (from `opts.search` baked into the URL).                                                                                                                                                                                          |
+| `search`           | `Record<string, unknown>`                                                                 | The TYPED search object (from `opts.searchData`); defaults to `{}`.                                                                                                                                                                                 |
+| `pathname`         | `string`                                                                                  | Request pathname.                                                                                                                                                                                                                                   |
+| `url`              | `URL`                                                                                     | Request URL.                                                                                                                                                                                                                                        |
+| `originalUrl`      | `URL`                                                                                     | Pre-basename-rewrite URL.                                                                                                                                                                                                                           |
+| `env`              | `TEnv`                                                                                    | Environment bindings (from `opts.env`).                                                                                                                                                                                                             |
+| `get`              | `<T>(contextVar: ContextVar<T>) => T \| undefined` / `<T>(key: string) => T \| undefined` | Read a var seeded via `opts.vars` — or READ a handle: `ctx.get(handle)` is rendered-gated (throws before the barrier) and returns the `opts.handles` seed.                                                                                          |
+| `use`              | `(dep) => ...`                                                                            | Resolve `ctx.use(OtherLoader)` (loader seeds, then the `use` resolver, then the real context `use()`) — or WRITE a handle: `ctx.use(SomeHandle)` returns the push function (withDefer-wrapped), recording into `runLoaderResult(...).handlePushes`. |
+| `method`           | `string`                                                                                  | HTTP method (from `opts.method`, default `"GET"`).                                                                                                                                                                                                  |
+| `body`             | `unknown`                                                                                 | Request body (from `opts.body`).                                                                                                                                                                                                                    |
+| `formData`         | `FormData \| undefined`                                                                   | Form data (from `opts.formData`).                                                                                                                                                                                                                   |
+| `reverse`          | `(name, params?, search?) => string`                                                      | Build a URL; throws unless `opts.routeMap` was passed.                                                                                                                                                                                              |
+| `rendered`         | `() => Promise<void>`                                                                     | The render barrier; throws by default, mocked via `opts.rendered`.                                                                                                                                                                                  |
+| `waitUntil`        | `(p: Promise<unknown>) => void`                                                           | Register background work (no-op accounting in tests).                                                                                                                                                                                               |
+| `executionContext` | `ExecutionContext \| undefined`                                                           | Platform execution context from the backing request; pairs with `waitUntil`.                                                                                                                                                                        |
 
 ### Returns — `Promise<T>`
 
 The loader data DIRECTLY (no envelope). `T` is the loader's return type.
 
-To assert a loader's EFFECTS — a `Set-Cookie`, a response header, or a
-`throw redirect(...)` (the auth-loader pattern) — use the sibling
-**`runLoaderResult(loader, opts)`** instead. Same options, but it returns an
-envelope: `{ result, thrown, response, cookies, headers, locationState, stateCookieName }`
-(parity with `runInRequestContext`; `result` is the loader's data). `runLoader`
-discards those effects.
+To assert a loader's EFFECTS — a `Set-Cookie`, a response header, a
+`throw redirect(...)` or `notFound()` (loader authority signals), or handle
+writes — use the sibling **`runLoaderResult(loader, opts)`** instead. Same
+options, but it returns an envelope:
+`{ result, thrown, response, cookies, headers, locationState, stateCookieName, handlePushes }`
+(parity with `runInRequestContext`; `result` is the loader's data;
+`handlePushes` records every `ctx.use(SomeHandle)({...})` write in push
+order). `runLoader` discards those effects.
 
 ## Recipe
 
@@ -113,7 +115,7 @@ it("asserts a loader's set-cookie + redirect (runLoaderResult)", async () => {
 ## Caveats
 
 - `ctx.reverse(...)` throws unless you pass `routeMap` (and `routeName` for scoped `.name` resolution). It does NOT fall back to the global route map.
-- `ctx.rendered()` throws by default (the render barrier only exists in a full match); pass `{ rendered: true }` to mock it for post-barrier logic, and `{ handles: [[SomeHandle, data]] }` to seed `ctx.use(SomeHandle)`. `ctx.isAction(...)` is unavailable — cover those at e2e.
+- `ctx.rendered()` throws by default (the render barrier only exists in a full match); pass `{ rendered: true }` to mock it for post-barrier logic, and `{ handles: [[SomeHandle, data]] }` to seed the `ctx.get(SomeHandle)` read. `ctx.isAction(...)` is unavailable — cover those at e2e.
 - Seeded `loaders` (by-reference tuples) are NOT executed — `ctx.use(OtherLoader)` returns the seeded value. The dynamic `use` resolver, by contrast, IS executed (it is a function called to compute the value). Either way the REAL loader body is not run; real loader execution and side-effects are e2e-only. `loaders` is checked before the `use` resolver.
 - A handle imported through the CLIENT build has its body dropped — `runLoader` throws a clear error pointing to the `rangoTestConfig()` preset or the raw body. A router using `Prerender()`/`createLoader()`/`Static()` now constructs in a bare test (each assigns a runtime fallback `$$id`); only the whole router _file_ may still need the plugin (its page modules pull app deps / `virtual:` modules).
 - No `cookies`/`headers` option: seed a cookie by passing a full Request with a Cookie header — `{ request: new Request(url, { headers: { Cookie: "sid=abc" } }) }`. (`search`/`method` are baked onto this request for you.)