npm - @rangojs/router - Versions diffs - 0.7.0 → 0.9.0 - Mend

@rangojs/router 0.7.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (59) hide show

package/dist/types/cache/cf/cf-cache-store.d.ts +30 -16
package/dist/types/cache/shell-snapshot.d.ts +2 -2
package/dist/types/cache/types.d.ts +26 -7
package/dist/types/client-urls/server-projection.d.ts +4 -4
package/dist/types/client-urls/types.d.ts +13 -12
package/dist/types/route-definition/helpers-types.d.ts +6 -5
package/dist/types/router/segment-resolution/loader-mask.d.ts +1 -1
package/dist/types/rsc/shell-capture.d.ts +14 -4
package/dist/types/rsc/types.d.ts +8 -0
package/dist/types/server/context.d.ts +1 -1
package/dist/types/server/request-context.d.ts +1 -1
package/dist/types/ssr/index.d.ts +16 -0
package/dist/types/ssr/ssr-root.d.ts +5 -0
package/dist/types/types/loader-types.d.ts +24 -22
package/dist/types/urls/path-helper-types.d.ts +8 -7
package/dist/vite/index.js +8 -5
package/package.json +1 -1
package/skills/breadcrumbs/SKILL.md +2 -2
package/skills/catalog.json +2 -2
package/skills/client-urls/SKILL.md +9 -8
package/skills/cloudflare/SKILL.md +5 -3
package/skills/comparison/references/framework-comparison.md +2 -2
package/skills/hooks/data.md +1 -1
package/skills/hooks/handle-and-actions.md +1 -1
package/skills/loader/SKILL.md +29 -28
package/skills/migrate-nextjs/SKILL.md +3 -3
package/skills/migrate-react-router/component-migration.md +1 -1
package/skills/migrate-react-router/data-and-actions.md +1 -1
package/skills/migrate-react-router/route-mapping.md +1 -1
package/skills/parallel/SKILL.md +1 -1
package/skills/ppr/SKILL.md +12 -8
package/skills/rango/SKILL.md +20 -20
package/skills/router-setup/SKILL.md +1 -1
package/skills/scripts/SKILL.md +1 -1
package/skills/shell-manifest/SKILL.md +1 -1
package/src/browser/react/Link.tsx +27 -4
package/src/cache/cf/cf-cache-store.ts +118 -62
package/src/cache/shell-snapshot.ts +2 -2
package/src/cache/types.ts +27 -7
package/src/client-urls/client-urls.ts +12 -9
package/src/client-urls/server-projection.ts +6 -6
package/src/client-urls/types.ts +13 -12
package/src/route-definition/dsl-helpers.ts +7 -3
package/src/route-definition/helpers-types.ts +6 -5
package/src/router/loader-resolution.ts +3 -3
package/src/router/segment-resolution/fresh.ts +2 -2
package/src/router/segment-resolution/loader-cache.ts +1 -1
package/src/router/segment-resolution/loader-mask.ts +1 -1
package/src/rsc/rsc-rendering.ts +10 -0
package/src/rsc/shell-build-manifest.ts +13 -6
package/src/rsc/shell-capture.ts +32 -5
package/src/rsc/ssr-setup.ts +4 -0
package/src/rsc/types.ts +18 -2
package/src/server/context.ts +1 -1
package/src/server/request-context.ts +1 -1
package/src/ssr/index.tsx +22 -2
package/src/ssr/ssr-root.tsx +17 -1
package/src/types/loader-types.ts +21 -19
package/src/urls/path-helper-types.ts +8 -7

package/skills/client-urls/SKILL.md CHANGED Viewed

@@ -1,6 +1,6 @@
 ---
 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.
+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 ssr:false 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]"
 ---
@@ -122,7 +122,7 @@ typing work exactly as for server routes (`/typesafety`).
 | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `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                                                                               |
+| `loader()`     | `loader(Def, use?)` or `loader(Def, { ssr: false }, 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)                                                                              |
@@ -214,7 +214,7 @@ export const ProductLoader = createLoader(async (ctx) => {
 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
+fast, pre-fetch existence check usually wins; see `ssr: false` 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
@@ -228,7 +228,7 @@ 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
+## `ssr: false` — 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
@@ -238,12 +238,13 @@ 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(ProductLoader, { ssr: false }, () => [revalidate(productData)]),
   loader(RelatedLoader),   // untouched: still streams behind its boundary
 ]),
 ```
-The name says WHERE streaming still applies, not that it is disabled: document
+The knob mirrors `loading(fallback, { ssr: false })` — SSR delivery is off
+for this loader, so nothing of it is left to stream in the document: 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
@@ -303,7 +304,7 @@ a hard load of the target URL renders the full route.
   `<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
+  kick off in parallel, so awaiting one (`ssr: false`) 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
@@ -332,7 +333,7 @@ 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"`
+Meta/Breadcrumbs, viewport prefetch on cards, and the `ssr: false`
 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/cloudflare/SKILL.md CHANGED Viewed

@@ -130,9 +130,11 @@ export const router = createRouter<AppBindings>({
 ```
 PPR shells use Cache API as the per-colo L1 and KV as the durable cross-colo
-L2; a KV hit promotes the coupled shell envelope back into L1. KV remains
-required for this family. `CFCacheStore` without `kv` can still cache
-segment/response entries in Cache API, but its shell family is inert.
+L2; a KV hit promotes the coupled shell envelope back into L1. KV is optional:
+`CFCacheStore` without `kv` runs the shell family L1-only (edge-only ppr —
+each colo captures and serves its own shell). Tag eviction then needs purge
+mode (`tagPurge`); a tagged shell without either warns once and expires by
+ttl+swr only.
 ## Commands

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

@@ -621,7 +621,7 @@ 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" })`
+`await ctx.rendered()`), and opt into `loader(Def, { ssr: false })`
 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
@@ -691,7 +691,7 @@ that no loader-before-render has:
   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 (and gating is a deliberate
-  per-loader opt-in — `{ stream: "navigation" }` awaits ONE loader on document
+  per-loader opt-in — `{ ssr: false }` 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

package/skills/hooks/data.md CHANGED Viewed

@@ -26,7 +26,7 @@ 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
+with `{ ssr: false }` is already settled at first paint, so its
 reads never suspend there — see `/loader`.)
 **Precondition**: Loader must be registered on route via `loader()` helper.

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

@@ -33,7 +33,7 @@ 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
+`loader(Def, { ssr: false })` makes them deterministic in the
 document. See `/loader` → "Writing Handles from Loaders". `useHandle`
 re-renders on every handle update, late loader pushes included.

package/skills/loader/SKILL.md CHANGED Viewed

@@ -1,6 +1,6 @@
 ---
 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, 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").
+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 (ssr:false).
 argument-hint: "[loader]"
 ---
@@ -172,23 +172,23 @@ Loaders receive the same context shape as route handlers.
 ### Full field surface
-| Field          | Type                            | Notes                                                                                                                                                                                                    |
-| -------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `params`       | `TParams`                       | Merged route + explicit loader params; overridable by fetchable `load({ params })`.                                                                                                                      |
-| `routeParams`  | `Record<string, string>`        | Server-trusted route params from URL pattern matching; cannot be overridden.                                                                                                                             |
-| `request`      | `Request`                       | The incoming `Request` (headers, method, body, `signal` for abort).                                                                                                                                      |
-| `url`          | `URL`                           | Parsed request URL.                                                                                                                                                                                      |
-| `pathname`     | `string`                        | URL pathname (shortcut for `ctx.url.pathname`).                                                                                                                                                          |
-| `searchParams` | `URLSearchParams`               | Shortcut for `ctx.url.searchParams`.                                                                                                                                                                     |
-| `search`       | `ResolveSearchSchema<TSearch>`  | Typed query params when a search schema is declared on the route; `{}` otherwise.                                                                                                                        |
-| `env`          | `TEnv`                          | Plain bindings from `createRouter<TEnv>()` (DB, KV, secrets, etc.).                                                                                                                                      |
-| `get`          | `(key \| ContextVar \| handle)` | Reads middleware variables/context-vars — or READS a handle's collected data, after `await ctx.rendered()`.                                                                                              |
-| `use`          | `(loader \| handle) => T`       | Access another loader's data (Promise), or WRITE a handle: `ctx.use(Meta)({ title })` returns the push function — handler parity. Reads moved to `get`.                                                  |
-| `rendered`     | `() => Promise<void>`           | **Experimental.** DSL loaders only — waits for all non-loader segments (including `loading()` streaming handlers) to settle before reading handle data. Not with `stream: "navigation"` (cycle; throws). |
-| `method`       | `string`                        | HTTP method. `"GET"` for SSR loader runs; reflects real method for fetchable loaders.                                                                                                                    |
-| `body`         | `TBody \| undefined`            | Parsed request body for fetchable POST/PUT/PATCH/DELETE calls.                                                                                                                                           |
-| `formData`     | `FormData \| undefined`         | Present when a fetchable loader is invoked via form submission.                                                                                                                                          |
-| `reverse`      | `ScopedReverseFunction`         | Generate type-checked URLs from route names (same scoped semantics as route handlers).                                                                                                                   |
+| Field          | Type                            | Notes                                                                                                                                                                                          |
+| -------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `params`       | `TParams`                       | Merged route + explicit loader params; overridable by fetchable `load({ params })`.                                                                                                            |
+| `routeParams`  | `Record<string, string>`        | Server-trusted route params from URL pattern matching; cannot be overridden.                                                                                                                   |
+| `request`      | `Request`                       | The incoming `Request` (headers, method, body, `signal` for abort).                                                                                                                            |
+| `url`          | `URL`                           | Parsed request URL.                                                                                                                                                                            |
+| `pathname`     | `string`                        | URL pathname (shortcut for `ctx.url.pathname`).                                                                                                                                                |
+| `searchParams` | `URLSearchParams`               | Shortcut for `ctx.url.searchParams`.                                                                                                                                                           |
+| `search`       | `ResolveSearchSchema<TSearch>`  | Typed query params when a search schema is declared on the route; `{}` otherwise.                                                                                                              |
+| `env`          | `TEnv`                          | Plain bindings from `createRouter<TEnv>()` (DB, KV, secrets, etc.).                                                                                                                            |
+| `get`          | `(key \| ContextVar \| handle)` | Reads middleware variables/context-vars — or READS a handle's collected data, after `await ctx.rendered()`.                                                                                    |
+| `use`          | `(loader \| handle) => T`       | Access another loader's data (Promise), or WRITE a handle: `ctx.use(Meta)({ title })` returns the push function — handler parity. Reads moved to `get`.                                        |
+| `rendered`     | `() => Promise<void>`           | **Experimental.** DSL loaders only — waits for all non-loader segments (including `loading()` streaming handlers) to settle before reading handle data. Not with `ssr: false` (cycle; throws). |
+| `method`       | `string`                        | HTTP method. `"GET"` for SSR loader runs; reflects real method for fetchable loaders.                                                                                                          |
+| `body`         | `TBody \| undefined`            | Parsed request body for fetchable POST/PUT/PATCH/DELETE calls.                                                                                                                                 |
+| `formData`     | `FormData \| undefined`         | Present when a fetchable loader is invoked via form submission.                                                                                                                                |
+| `reverse`      | `ScopedReverseFunction`         | Generate type-checked URLs from route names (same scoped semantics as route handlers).                                                                                                         |
 ### Example
@@ -443,8 +443,8 @@ boundary a parallel loader blocks its parent, so add one to keep the overlap.)
 If you come from a framework where the loader is a blocking step that runs
 before the response is built, this is the shift to internalize: here the
 response starts streaming first and loader data fills in. (The one deliberate
-exception is per-loader: `loader(Def, { stream: "navigation" })` awaits that
-loader before first flush on document renders — see "`stream: "navigation"`"
+exception is per-loader: `loader(Def, { ssr: false })` awaits that
+loader before first flush on document renders — see "`ssr: false`"
 below.)
 ### See it: `debugPerformance`
@@ -687,10 +687,10 @@ export const ProductLoader = createLoader(async (ctx) => {
 Semantics by lane:
-| Signal       | Document load                                                                                                                                                                                                                                                         | Client navigation                                 |
-| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
-| `notFound()` | Not-found UI resolves server-side (nearest `notFoundBoundary` → router option → default) and rides the envelope; the 404 STATUS is **opportunistic** — real only if the rejection beats Response construction. `stream: "navigation"` (below) makes it deterministic. | 404 UI swaps in, URL preserved, payload stays 200 |
-| `redirect()` | 200 document, then a client-side replace to the target — **no document-lane 302 from loaders**; pre-stream redirect authority belongs to middleware                                                                                                                   | Redirect envelope navigates to the target         |
+| Signal       | Document load                                                                                                                                                                                                                                               | Client navigation                                 |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| `notFound()` | Not-found UI resolves server-side (nearest `notFoundBoundary` → router option → default) and rides the envelope; the 404 STATUS is **opportunistic** — real only if the rejection beats Response construction. `ssr: false` (below) makes it deterministic. | 404 UI swaps in, URL preserved, payload stays 200 |
+| `redirect()` | 200 document, then a client-side replace to the target — **no document-lane 302 from loaders**; pre-stream redirect authority belongs to middleware                                                                                                         | Redirect envelope navigates to the target         |
 Session/auth gates belong in middleware (they are request-shaped, not
 data-shaped, and middleware CAN emit a real pre-stream 302). Data-dependent
@@ -725,14 +725,14 @@ barrier ride the SSR handle snapshot (in the SSR'd document — `<MetaTags />`,
 on document loads (`metadata.handlesLate`) or progressively on navigations.
 A push before your slow fetch usually beats the barrier; a push derived from
 the fetched data usually does not. When it MUST be in the document, use
-`stream: "navigation"` below.
+`ssr: false` below.
 Reads are the other direction and gated: `ctx.get(handle)` throws unless the
 loader first does `await ctx.rendered()` (DSL-registered loaders only —
 handler-invoked loaders cannot use `rendered()`, and a handler already
 awaiting the loader via `ctx.use()` makes it a detected deadlock).
-## `stream: "navigation"` — Guarantee a Loader in the Document
+## `ssr: false` — Guarantee a Loader in the Document
 Streaming means nothing a slow loader produces is _guaranteed_ in the SSR'd
 HTML: its section SSRs as the fallback, a late handle push applies
@@ -743,12 +743,13 @@ use callback:
 ```typescript
 path("/product/:slug", ProductPage, { name: "product" }, () => [
-  loader(ProductLoader, { stream: "navigation" }, () => [cache({ ttl: 60 })]),
+  loader(ProductLoader, { ssr: false }, () => [cache({ ttl: 60 })]),
   loader(RelatedLoader),   // untouched: still streams behind its boundary
 ]),
 ```
-The name says WHERE streaming still applies, not that it is disabled:
+The knob mirrors `loading(fallback, { ssr: false })` — SSR delivery is off
+for this loader, so nothing of it is left to stream in the document:
 document renders await this loader before first flush — data is settled
 (`useLoader` reads it synchronously, no fallback paints), handle pushes beat
 the barrier snapshot, and a thrown `notFound()` deterministically precedes

package/skills/migrate-nextjs/SKILL.md CHANGED Viewed

@@ -726,7 +726,7 @@ const HomePage: Handler<"home"> = (ctx) => {
 `generateMetadata({ params })` — DATA-derived, document-blocking metadata —
 maps to a Meta push from the LOADER that owns the data, plus
-`{ stream: "navigation" }` for the blocking-until-in-head part:
+`{ ssr: false }` for the blocking-until-in-head part:
 ```typescript
 // Next.js: export async function generateMetadata({ params }) {
@@ -744,7 +744,7 @@ export const ProductLoader = createLoader(async (ctx) => {
 });
 path("/product/:slug", ProductPage, { name: "product" }, () => [
-  loader(ProductLoader, { stream: "navigation" }),
+  loader(ProductLoader, { ssr: false }),
 ]);
 ```
@@ -843,7 +843,7 @@ See `/theme` for full API including system detection and cookie persistence.
 10. [ ] Convert loading/error files to `loading()` / `errorBoundary()`
 11. [ ] Migrate API routes to `path.json()` / `path.text()`
 12. [ ] Update metadata to use `Meta` handle + `<MetaTags />` in document head
-        (`generateMetadata` → loader push + `{ stream: "navigation" }`)
+        (`generateMetadata` → loader push + `{ ssr: false }`)
 13. [ ] Replace `next-themes` with `theme: true` in createRouter (see `/theme`)
 14. [ ] Map rendering-mode segment config: `revalidate = N` → `cache({ ttl })`,
         `force-static` → `Static()`/`Prerender()`, `experimental_ppr` → the

package/skills/migrate-react-router/component-migration.md CHANGED Viewed

@@ -134,7 +134,7 @@ const HomePage: Handler<"home"> = (ctx) => {
 RR's data-derived `meta({ data })` maps to the same push from the LOADER that
 owns the data — `ctx.use(Meta)({ title: data.name })` in the loader body, with
-`loader(Def, { stream: "navigation" })` when the title must be in the SSR'd
+`loader(Def, { ssr: false })` when the title must be in the SSR'd
 head. See `/loader` → "Writing Handles from Loaders".
 Add `<MetaTags />` in the Document component's `<head>`:

package/skills/migrate-react-router/data-and-actions.md CHANGED Viewed

@@ -46,7 +46,7 @@ Use it only when you need capabilities beyond what the handler provides:
   document loads, never an HTTP 302 — pre-stream 302s move to middleware)
 - **`meta({ data })` / `handle` exports** — data-derived page metadata becomes
   a handle push from the loader body (`ctx.use(Meta)({ title: data.name })`),
-  with `loader(L, { stream: "navigation" })` when it must be in the SSR'd head
+  with `loader(L, { ssr: false })` when it must be in the SSR'd head
 If the React Router loader just fetches data for its page component AND the
 component can become a server component, merge it into the handler. If the

package/skills/migrate-react-router/route-mapping.md CHANGED Viewed

@@ -135,7 +135,7 @@ The loader-shaped variant is equally valid — and closer to the RR module when
 the loader carried authority. A `createLoader()` body can throw `notFound()`
 for the missing product AND push the data-derived meta itself
 (`ctx.use(Meta)({ title: product.name })`); register it with
-`loader(ProductLoader, { stream: "navigation" })` when the 404 status and
+`loader(ProductLoader, { ssr: false })` when the 404 status and
 title must be in the document deterministically. See `/loader` → "Loader
 Authority" and "Writing Handles from Loaders". (One RR habit that does NOT
 carry over: a loader `throw redirect()` is a client-side navigate on document

package/skills/parallel/SKILL.md CHANGED Viewed

@@ -136,7 +136,7 @@ naturally.
 > the baked lane under `cache()`/PPR — just to reach a `ctx.use(Meta)` call.
 > The loader can now push `Meta` itself (`/loader` → "Writing Handles from
 > Loaders"), keeping the data on the live lane; add
-> `loader(Def, { stream: "navigation" })` when the meta must be in the SSR'd
+> `loader(Def, { ssr: false })` when the meta must be in the SSR'd
 > head. Keep the `@meta` slot for metadata that is NOT loader-derived
 > (templates, static descriptions, structured data with independent inputs).

package/skills/ppr/SKILL.md CHANGED Viewed

@@ -356,13 +356,17 @@ curl -s -D - -o /dev/null https://app.example.com/products/1 | grep -i x-rango-s
   key — no header + a declared `ppr` means look for that warning.
 - On Cloudflare, `CFCacheStore` reads PPR shells from the per-colo Cache API,
   falls through to KV on a miss, and promotes the KV hit back into that colo.
-  WITHOUT a KV namespace its shell family remains inert: every ppr route stays
-  `MISS` forever. The store warns once per isolate — bind KV
-  (`new CFCacheStore({ ctx, kv: env.CACHE_KV })`) or use another store. An
-  inert store also stops captures at the gate: the store declares
-  `shellFamilyInert` and the scheduler skips the background render entirely
-  (`skip-inert-store` on the debug event) instead of burning a full capture per
-  MISS whose write could only no-op.
+  WITHOUT a KV namespace the family runs L1-only (edge-only ppr): every colo
+  captures and serves its own shell from the Cache API. What changes KV-less
+  is tag eviction — with `tagPurge` the purge-by-tag evicts shell L1 entries;
+  without it a TAGGED shell warns once that `updateTag()` cannot reach it
+  (ttl/swr-only freshness). Untagged edge-only ppr is warning-free. Tagged
+  BUILD-manifest shells decline on a KV-less store (`tagHistoryInert` — the
+  immutable asset could never be evicted), and an over-limit tag set is
+  acknowledged `"uncacheable"` so the capture backs off instead of
+  re-rendering per MISS. A custom store can still declare `shellFamilyInert`
+  to stop captures at the gate (`skip-inert-store` on the debug event); the
+  built-in stores never do.
 - Structured capture diagnostics: `createRouter({ debugShellCapture: true })`
   logs one line per capture attempt/skip (outcome, durations, prelude and
   snapshot bytes, backoff state); pass a function to receive each
@@ -665,7 +669,7 @@ 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
+One flag to know about here: `loader(Def, { ssr: false })` (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

package/skills/rango/SKILL.md CHANGED Viewed

@@ -95,26 +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              |
-| 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 |
+| 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, { ssr: false })`        | /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

package/skills/router-setup/SKILL.md CHANGED Viewed

@@ -375,7 +375,7 @@ 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;
+`loader(Def, { ssr: false })` 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".

package/skills/scripts/SKILL.md CHANGED Viewed

@@ -106,7 +106,7 @@ during navigation.
 > 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
+> to the document, register it `loader(Def, { ssr: false })` so the
 > document render awaits the push; otherwise push from a handler (or use an
 > `async` config, which stays reactive).

package/skills/shell-manifest/SKILL.md CHANGED Viewed

@@ -151,7 +151,7 @@ cache({ ttl: 600, tags: ["products"] }, () => [
   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
+  `{ ssr: false }` (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

package/src/browser/react/Link.tsx CHANGED Viewed

@@ -167,17 +167,28 @@ export interface LinkProps extends Omit<
 }
 /**
- * Check if URL is external (different origin)
+ * Check if URL is external (different origin). `origin` is resolved by the
+ * component from the navigation store location so SSR and browser agree —
+ * reading window here made every absolute-URL Link a hydration mismatch:
+ * on the server the ReferenceError was swallowed by the malformed-URL catch
+ * and the SSR HTML never carried data-external, then the browser evaluated
+ * the same link as external.
  */
-function isExternalUrl(href: string): boolean {
+function isExternalUrl(href: string, origin: string | undefined): boolean {
   // Protocol-relative URLs
   if (href.startsWith("//")) return true;
   // Absolute URLs
   if (href.startsWith("http://") || href.startsWith("https://")) {
+    // No known origin (no provider and no window): treat as internal — the
+    // pre-fix behavior for that configuration, and stable across hydration
+    // because both sides resolve the same store origin when a provider
+    // exists (the real-app case).
+    if (!origin) return false;
     try {
-      return new URL(href).origin !== window.location.origin;
+      return new URL(href).origin !== origin;
     } catch {
+      // Genuinely malformed absolute URL.
       return false;
     }
   }
@@ -225,7 +236,19 @@ export const Link: ForwardRefExoticComponent<
   ref,
 ) {
   const ctx = useContext(NavigationStoreContext);
-  const isExternal = isExternalUrl(to);
+  // Origin from the store location — the same both-sides source
+  // useSearchParams seeds from (SSR: the live request's URL; browser:
+  // window.location), so data-external agrees across hydration. Origin is
+  // immutable per document, so the inline getState() read cannot tear.
+  // window is the provider-less browser fallback (tests, portals outside
+  // the app root); provider-less SSR has no origin and keeps links internal.
+  const storeLocation = ctx?.eventController.getState().location as
+    | URL
+    | undefined;
+  const origin =
+    storeLocation?.origin ??
+    (typeof window !== "undefined" ? window.location.origin : undefined);
+  const isExternal = isExternalUrl(to, origin);
   // Auto-prefix with basename for app-local paths.
   // Skip if external, already prefixed, or not a root-relative path.