@rangojs/router 0.8.0 → 0.9.0

package/dist/types/client-urls/server-projection.d.ts

@@ -27,10 +27,10 @@ export interface ClientUrlProjectionRoute {
     readonly options: ClientUrlProjectionOptions;
     readonly loaderIds: readonly string[];
     readonly hasLoading: boolean;
-    /** Indices into loaderIds of loaders declared loader(Def, { stream:
-     *  "navigation" }); materialization passes the option through to the server
-     *  loader() so document renders await them before first flush. Absent (=
-     *  none) in projections serialized before stream support. */
+    /** Indices into loaderIds of loaders declared loader(Def, { ssr: false });
+     *  materialization passes the option through to the server loader() so
+     *  document renders await them before first flush. Absent (= none) in
+     *  projections serialized before the option existed. */
     readonly awaitedLoaderIndices?: readonly number[];
     /** Data-only transition config (no `when` — server-tree only); absent in
      *  projections serialized before transition support. */

package/dist/types/client-urls/types.d.ts

@@ -54,12 +54,12 @@ export interface ClientUrlLoaderRecord {
     /** Client-run per-loader revalidation predicates; empty = locked defaults. */
     readonly revalidate: readonly ClientRevalidateFn[];
     /**
-     * loader(Def, { stream: "navigation" }): document renders await this loader
-     * before first flush (see {@link LoaderOptions}). Projected into the server
-     * tree, where the per-isSSR entry stamping applies — client navigations
-     * stream regardless.
+     * loader(Def, { ssr: false }): document renders await this loader before
+     * first flush (see {@link LoaderOptions}). Projected into the server tree,
+     * where the per-isSSR entry stamping applies — client navigations stream
+     * regardless.
      */
-    readonly stream?: "navigation";
+    readonly ssr?: false;
 }
 /**
  * The data-only subset of TransitionConfig a clientUrls() route may declare:
@@ -101,13 +101,14 @@ export interface ClientUrlHelpers {
      * revalidate() only — a CLIENT-RUN per-loader predicate; its decision (not
      * the function) is sent with the revalidation request.
      *
-     * Pass `{ stream: "navigation" }` to await this loader before first flush
-     * on DOCUMENT requests (see {@link LoaderOptions}) — the opt-in for loaders
-     * whose data, handle pushes, or thrown notFound()/redirect() must be in the
-     * SSR'd HTML. Per-loader: a dynamic sibling keeps streaming. Under a
-     * `ppr` group route the flag BAKES: the loader executes at shell capture
-     * and its settled return freezes into the shell (nested promises stay
-     * live holes).
+     * Pass `{ ssr: false }` — the same knob as loading(fallback, { ssr:
+     * false }) — to await this loader before first flush on DOCUMENT requests
+     * (see {@link LoaderOptions}): the opt-in for loaders whose data, handle
+     * pushes, or thrown notFound()/redirect() must be in the SSR'd HTML.
+     * Per-loader: a streaming sibling keeps streaming. Under a `ppr` group
+     * route the flag BAKES: the loader executes at shell capture and its
+     * settled return freezes into the shell (nested promises stay live
+     * holes).
      */
     readonly loader: <TData>(definition: LoaderDefinition<TData>, optionsOrUse?: LoaderOptions | ClientUrlUse, use?: ClientUrlUse) => ClientUrlItem;
     readonly loading: (component: ReactNode) => ClientUrlItem;

package/dist/types/route-definition/helpers-types.d.ts

@@ -208,13 +208,14 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
      *   return <div>{data.name}</div>;
      * }
      * ```
-     * Pass `{ stream: "navigation" }` to await this loader before first flush on
-     * DOCUMENT requests (see {@link LoaderOptions}) — the opt-in for loaders whose
-     * data, handle pushes, or thrown notFound()/redirect() must be in the SSR'd
-     * HTML. Per-loader: a dynamic sibling in the same segment keeps streaming.
+     * Pass `{ ssr: false }` — the same knob as loading(fallback, { ssr:
+     * false }) — to await this loader before first flush on DOCUMENT requests
+     * (see {@link LoaderOptions}): the opt-in for loaders whose data, handle
+     * pushes, or thrown notFound()/redirect() must be in the SSR'd HTML.
+     * Per-loader: a streaming sibling in the same segment keeps streaming.
      *
      * ```typescript
-     * loader(ProductLoader, { stream: "navigation" }, () => [cache()]),
+     * loader(ProductLoader, { ssr: false }, () => [cache()]),
      * loader(RecommendationsLoader),  // still streams behind loading()
      * ```
      *

package/dist/types/router/segment-resolution/loader-mask.d.ts

@@ -30,7 +30,7 @@ export { createMaskedLoaderPromise } from "./mask-nested.js";
 /**
  * Entry-level lane input for an entry's loaders under PPR (the loading()
  * value; docs/design/loader-container-bake.md). The CAPTURE decision itself
- * is per LOADER in loader-cache.ts: a `stream: "navigation"`
+ * is per LOADER in loader-cache.ts: an `ssr: false`
  * (awaitBeforeFlush) loader BAKES at capture regardless of this value — the
  * flag's document promise ("data in the HTML before first flush") maps to
  * the frozen prelude — while every other loader is LIVE (masked at capture,

package/dist/types/rsc/shell-capture.d.ts

@@ -283,6 +283,15 @@ export interface ShellCaptureDescriptor {
      * Omitted (build-time bare-pathname captures) = search-less, same as "".
      */
     searchSeed?: string;
+    /**
+     * The scheduling request's origin, seeding the capture render's SSR store
+     * location. Shell keys are host-scoped, so the resume pass's request
+     * agrees modulo protocol drift; the seed keeps origin-dependent static
+     * markup (Link's data-external) identical across capture, resume, and
+     * browser hydration. Omitted (build-time host-agnostic captures) falls
+     * back to the internal host.
+     */
+    originSeed?: string;
     /**
      * The RSC handler's build version (HandlerContext.version), stamped into the
      * stored entry as ShellCacheEntry.buildVersion — the serve-side

package/dist/types/rsc/types.d.ts

@@ -175,6 +175,12 @@ export interface SSRRenderOptions {
      * search; see ShellCaptureOptions.search in the SSR entry).
      */
     search?: string;
+    /**
+     * The live request's origin (`url.origin`), seeding the SSR store
+     * location so origin-dependent markup (Link's data-external) agrees with
+     * the browser across hydration. Absent on host-agnostic build captures.
+     */
+    origin?: string;
 }
 /**
  * SSR module interface for HTML rendering
@@ -193,6 +199,7 @@ export interface SSRModule {
         quiesce: Promise<void>;
         maxWaitMs?: number;
         search?: string;
+        origin?: string;
     }) => Promise<{
         prelude: Uint8Array;
         postponed: string | null;
@@ -209,6 +216,7 @@ export interface SSRModule {
         postponed: string | null;
         nonce?: string;
         search?: string;
+        origin?: string;
     }) => Promise<ReadableStream<Uint8Array>>;
 }
 /**

package/dist/types/server/context.d.ts

@@ -84,7 +84,7 @@ export type LoaderEntry = {
     cache?: EntryCacheConfig;
     /**
      * Document renders await this loader before segment resolution returns
-     * (loader(Def, { stream: "navigation" })), so its data, handle pushes, and
+     * (loader(Def, { ssr: false })), so its data, handle pushes, and
      * thrown notFound()/redirect() deterministically precede first flush.
      * Resolved at DSL-evaluation time from ctx.isSSR — entries are cached
      * per-isSSR (router/manifest.ts cache key), so the flag is already

package/dist/types/server/request-context.d.ts

@@ -509,7 +509,7 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
     _handlerLoaderDeps?: Set<string>;
     /**
      * @internal Loader IDs ($$id) whose entries carry `awaitBeforeFlush`
-     * (loader(Def, { stream: "navigation" })): segment resolution awaits these
+     * (loader(Def, { ssr: false })): segment resolution awaits these
      * before returning, so the render barrier cannot resolve until they settle.
      * rendered() checks this set to fail fast — a flagged loader awaiting the
      * barrier is a guaranteed cycle, not a race. Registered by resolveLoaders

package/dist/types/ssr/index.d.ts

@@ -90,6 +90,13 @@ export interface SSRRenderOptions {
      * only (runtime captures own the search variants, seeded per key).
      */
     search?: string;
+    /**
+     * The live request's origin, seeding the SSR store location so
+     * origin-dependent markup (Link's data-external) agrees with the
+     * browser's window.location across hydration. Absent on the build-time
+     * prerender pass (host-agnostic bare captures).
+     */
+    origin?: string;
 }
 /**
  * SSR dependencies from external packages
@@ -184,6 +191,13 @@ interface ShellCaptureOptions {
      * the shell's own key. MUST equal the resume pass's seed for the same key.
      */
     search?: string;
+    /**
+     * The capture request's origin. Shell keys are host-scoped, so the resume
+     * pass's request agrees modulo protocol drift; seeding it keeps
+     * origin-dependent static markup (Link's data-external) identical across
+     * capture, resume, and browser hydration.
+     */
+    origin?: string;
 }
 /**
  * Result of a successful shell capture. `prelude` is the raw prelude bytes;
@@ -210,6 +224,8 @@ interface ShellResumeOptions {
      * postponed holes.
      */
     search?: string;
+    /** The HIT request's origin — same host as the capture's (key-scoped). */
+    origin?: string;
 }
 /**
  * Create an SSR handler that converts RSC streams to HTML.

package/dist/types/ssr/ssr-root.d.ts

@@ -58,6 +58,11 @@ export interface SsrRootOptions {
      * the resume tree matches the captured tree above the postponed holes.
      */
     search?: string;
+    /**
+     * Origin seeding the SSR store location (see createSsrEventController):
+     * live fizz passes the request's origin; capture/resume pass theirs.
+     */
+    origin?: string;
 }
 /**
  * Build the closure component that deserializes the Flight payload, consumes

package/dist/types/types/loader-types.d.ts

@@ -63,7 +63,7 @@ export type LoaderContext<TParams = Record<string, string | undefined>, TEnv = D
      * later ones stream to the client and apply post-hydration (document lane)
      * or progressively (navigation/action lanes). To guarantee a loader's
      * handles are in the SSR'd document, register it as
-     * `loader(Def, { stream: "navigation" })` so the document render awaits it
+     * `loader(Def, { ssr: false })` so the document render awaits it
      * (see {@link LoaderOptions}).
      *
      * @example
@@ -149,29 +149,31 @@ export type LoaderContext<TParams = Record<string, string | undefined>, TEnv = D
  */
 export type LoaderFn<T, TParams = Record<string, string | undefined>, TEnv = DefaultEnv> = (ctx: LoaderContext<TParams, TEnv>) => Promise<T> | T;
 /**
- * Delivery mode for a DSL-registered loader: `loader(Def, { stream })`.
- *
- * Default (omitted): the loader streams on every render. Its data, its
- * `ctx.use(Handle)` pushes, and any `notFound()`/`redirect()` it throws may land
- * AFTER the document Response is constructed, so none of them are guaranteed to
- * be in the SSR'd HTML.
- *
- * `"navigation"` narrows streaming to client navigations only: on a DOCUMENT
- * request the loader is awaited before first flush. `useLoader` still suspends,
- * but on an already-settled promise, so no fallback paints. This is the
- * SSR-completeness opt-in — the name is about WHERE streaming still applies, not
- * about disabling it. Choose it when the loader feeds something that must exist
- * in the document: `<head>` meta via a handle, or a real 404 status (an awaited
- * `notFound()` deterministically precedes Response construction, where the
- * streamed default only wins that race opportunistically). It does NOT change
- * PPR capture behavior: capture renders mask loaders and skip this await.
- *
- * Scoped per LOADER, not per segment: a baked loader alongside a deliberately
- * dynamic sibling awaits only itself, and the sibling keeps streaming behind its
- * `loading()`/Suspense boundary.
+ * SSR delivery for a DSL-registered loader: `loader(Def, { ssr })`.
+ *
+ * Default (omitted / `true`): the loader streams on every render. Its data,
+ * its `ctx.use(Handle)` pushes, and any `notFound()`/`redirect()` it throws
+ * may land AFTER the document Response is constructed, so none of them are
+ * guaranteed to be in the SSR'd HTML.
+ *
+ * `ssr: false` turns SSR streaming off for this loader — the same knob
+ * `loading(fallback, { ssr: false })` is for the fallback: on a DOCUMENT
+ * request the loader is awaited before first flush, so no fallback paints for
+ * it (`useLoader` still suspends, but on an already-settled promise). Client
+ * navigations keep streaming it. This is the SSR-completeness opt-in. Choose
+ * it when the loader feeds something that must exist in the document:
+ * `<head>` meta via a handle, or a real 404 status (an awaited `notFound()`
+ * deterministically precedes Response construction, where the streamed
+ * default only wins that race opportunistically). Under ppr it is also the
+ * BAKE lane: the loader executes at shell capture and its settled return is
+ * shell material (nested promises stay live holes) — see the ppr docs.
+ *
+ * Scoped per LOADER, not per segment: an `ssr: false` loader alongside a
+ * deliberately streaming sibling awaits only itself, and the sibling keeps
+ * streaming behind its `loading()`/Suspense boundary.
  */
 export type LoaderOptions = {
-    stream?: "navigation";
+    ssr?: boolean;
 };
 /**
  * Options for fetchable loaders

package/dist/types/urls/path-helper-types.d.ts

@@ -148,13 +148,14 @@ export type PathHelpers<TEnv> = {
     /**
      * Attach a data loader to the current route/layout.
      *
-     * Pass `{ stream: "navigation" }` to await this loader before first flush
-     * on DOCUMENT requests (see {@link LoaderOptions}) — the opt-in for loaders
-     * whose data, handle pushes, or thrown notFound()/redirect() must be in the
-     * SSR'd HTML. Per-loader: a dynamic sibling keeps streaming. Under a
-     * `ppr` route the flag BAKES: the loader executes at shell capture and
-     * its settled return freezes into the shell (nested promises stay live
-     * holes) — the pre-flush promise applied to the prelude.
+     * Pass `{ ssr: false }` — the same knob as loading(fallback, { ssr:
+     * false }) — to await this loader before first flush on DOCUMENT requests
+     * (see {@link LoaderOptions}): the opt-in for loaders whose data, handle
+     * pushes, or thrown notFound()/redirect() must be in the SSR'd HTML.
+     * Per-loader: a streaming sibling keeps streaming. Under a `ppr` route the
+     * flag BAKES: the loader executes at shell capture and its settled return
+     * freezes into the shell (nested promises stay live holes) — the pre-flush
+     * promise applied to the prelude.
      */
     loader: <TData>(loaderDef: LoaderDefinition<TData>, optionsOrUse?: LoaderOptions | (() => LoaderUseItem[]), use?: () => LoaderUseItem[]) => LoaderItem;
     /**

package/dist/vite/index.js

@@ -3685,7 +3685,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.8.0",
+  version: "0.9.0",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -8304,11 +8304,12 @@ init_loader();
 import { jsx as jsx6 } from "react/jsx-runtime";
 var IGNORE_STRATEGY_CHANGES = (_listener) => () => {
 };
-function isExternalUrl(href2) {
+function isExternalUrl(href2, origin) {
   if (href2.startsWith("//")) return true;
   if (href2.startsWith("http://") || href2.startsWith("https://")) {
+    if (!origin) return false;
     try {
-      return new URL(href2).origin !== window.location.origin;
+      return new URL(href2).origin !== origin;
     } catch {
       return false;
     }
@@ -8332,7 +8333,9 @@ var Link = forwardRef(function Link2({
   ...props
 }, ref) {
   const ctx = useContext14(NavigationStoreContext);
-  const isExternal = isExternalUrl(to);
+  const storeLocation = ctx?.eventController.getState().location;
+  const origin = storeLocation?.origin ?? (typeof window !== "undefined" ? window.location.origin : void 0);
+  const isExternal = isExternalUrl(to, origin);
   const resolvedTo = useMemo7(() => {
     if (isExternal) return to;
     const bn = ctx?.basename;
@@ -9018,7 +9021,7 @@ function serializeRoute(route2) {
     }
     return loader2.$$id;
   });
-  const awaitedLoaderIndices = route2.loaders.map(({ stream }, index) => stream === "navigation" ? index : -1).filter((index) => index >= 0);
+  const awaitedLoaderIndices = route2.loaders.map(({ ssr }, index) => ssr === false ? index : -1).filter((index) => index >= 0);
   const transition2 = serializeTransition(route2);
   return Object.freeze({
     id: route2.id,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -176,6 +176,20 @@
     "access": "public",
     "tag": "latest"
   },
+  "scripts": {
+    "build": "pnpm run build:types && pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
+    "build:types": "rm -rf dist/types && pnpm exec tsc -p tsconfig.types.json",
+    "prepublishOnly": "pnpm build",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
+    "test": "playwright test",
+    "test:preload": "playwright test --config=playwright.preload.config.ts",
+    "test:ui": "playwright test --ui",
+    "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-basename --project=hmr-prerender --no-deps --workers=1 && RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
+    "test:hmr-routes-local": "RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
+    "test:unit": "pnpm run build:types && vitest run",
+    "test:unit:watch": "vitest",
+    "test:unit:rsc": "vitest run --config vitest.rsc.config.ts"
+  },
   "dependencies": {
     "@types/debug": "^4.1.12",
     "@vitejs/plugin-rsc": "^0.5.31",
@@ -192,18 +206,18 @@
     "@opentelemetry/context-async-hooks": "^2.9.0",
     "@opentelemetry/sdk-trace-base": "^2.9.0",
     "@playwright/test": "^1.49.1",
+    "@shared/e2e": "workspace:*",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^24.10.1",
-    "@types/react": "^19.2.7",
-    "@types/react-dom": "^19.2.3",
+    "@types/react": "catalog:",
+    "@types/react-dom": "catalog:",
     "esbuild": "^0.28.1",
     "happy-dom": "^20.10.1",
     "jiti": "^2.7.0",
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8",
-    "vitest": "^4.1.9",
-    "@shared/e2e": "0.0.1"
+    "react": "catalog:",
+    "react-dom": "catalog:",
+    "vitest": "^4.1.9"
   },
   "peerDependencies": {
     "@cloudflare/vite-plugin": "^1.42.1",
@@ -242,18 +256,5 @@
   },
   "engines": {
     "node": ">=24.0.0"
-  },
-  "scripts": {
-    "build": "pnpm run build:types && pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
-    "build:types": "rm -rf dist/types && pnpm exec tsc -p tsconfig.types.json",
-    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
-    "test": "playwright test",
-    "test:preload": "playwright test --config=playwright.preload.config.ts",
-    "test:ui": "playwright test --ui",
-    "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-basename --project=hmr-prerender --no-deps --workers=1 && RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
-    "test:hmr-routes-local": "RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
-    "test:unit": "pnpm run build:types && vitest run",
-    "test:unit:watch": "vitest",
-    "test:unit:rsc": "vitest run --config vitest.rsc.config.ts"
   }
-}
+}

package/skills/breadcrumbs/SKILL.md

@@ -82,7 +82,7 @@ Two pushes from one segment accumulate in push order (`Shop › product`).
 Delivery follows the loader race model: a push that beats the handler barrier
 is in the SSR'd document; a push after a slow fetch streams and applies
 client-side (`useHandle` re-renders when it lands). To guarantee document
-delivery, register the loader as `loader(Def, { stream: "navigation" })` —
+delivery, register the loader as `loader(Def, { ssr: false })` —
 see `/loader` → "Writing Handles from Loaders".
 
 ## Async Content
@@ -170,7 +170,7 @@ swap in — no blank, no pending entry. If the slot times out to `else: null`/
 undefined, the entry is simply dropped. Use `.defer()` only when even
 `label`/`href` are unknown at handler time AND the producer is a component,
 not a loader — a loader-produced crumb pushes directly from the loader body
-(add `{ stream: "navigation" }` if it must be in the SSR'd document), and if
+(add `{ ssr: false }` if it must be in the SSR'd document), and if
 you know `label`/`href` and only the `content` is async, push a concrete item
 with a `Promise` `content` field instead (the `content` field is a nested
 promise you resolve with `use()` in your component; no `.defer()` needed).

package/skills/catalog.json

@@ -35,7 +35,7 @@
     },
     {
       "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.",
       "argumentHint": "[setup]",
       "path": "skills/client-urls/SKILL.md"
     },
@@ -137,7 +137,7 @@
     },
     {
       "name": "loader",
-      "description": "Define data loaders for fetching data in routes with createLoader. Use when pages need per-request data that stays fresh, data should stream while the page renders, 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).",
       "argumentHint": "[loader]",
       "path": "skills/loader/SKILL.md"
     },

package/skills/client-urls/SKILL.md

@@ -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/comparison/references/framework-comparison.md

@@ -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

@@ -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

@@ -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.