@rangojs/router 0.7.0 → 0.9.0

package/dist/types/cache/cf/cf-cache-store.d.ts

@@ -30,8 +30,6 @@ import type { KVNamespace, CFCacheReadDebugEvent, CFCacheDebug, CFCacheStoreOpti
 export type { KVNamespace, CFCacheReadDebugEvent, CFCacheDebug, CFCacheStoreOptions, };
 export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     readonly supportsPassiveShellReads: true;
-    /** True when constructed without KV: the shell family no-ops (see ctor). */
-    readonly shellFamilyInert?: boolean;
     readonly defaults?: CacheDefaults;
     readonly keyGenerator?: (ctx: RequestContext<TEnv>, defaultKey: string) => string | Promise<string>;
     private readonly namespace?;
@@ -43,6 +41,8 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
     private readonly kvReadTimeoutMs;
     private readonly debug?;
     private readonly kv?;
+    /** True when constructed without KV: no durable tag history (see ctor). */
+    readonly tagHistoryInert?: boolean;
     private readonly onRevalidateTag?;
     private readonly tagPurge?;
     private readonly tagInvalidationTtl?;
@@ -257,15 +257,26 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      */
     setItem(key: string, value: string, options?: CacheItemOptions): Promise<void>;
     /**
-     * Warn once per isolate that the shell family is inert: getShell/putShell
-     * are ONLY called for routes that declared the `ppr` path option, so firing
-     * here (not in the constructor) scopes the warning to apps that actually
-     * use PPR — a KV-less CFCacheStore is a perfectly fine config otherwise.
-     * Without it, the correctness-first fail-open (issue #651) is invisible:
-     * every ppr route is a permanent MISS with zero diagnostics.
+     * Warn once per isolate that a TAGGED shell landed on a store with no
+     * eviction path for it: no KV (markers) and no tagPurge (purge-by-tag).
+     * The shell still caches and expires by ttl+swr, but updateTag()/
+     * revalidateTag() cannot reach it — silent staleness a consumer who tagged
+     * the route clearly did not intend. Fired from putShell (not the
+     * constructor) so an untagged edge-only ppr config stays warning-free.
      * @internal
      */
-    private warnShellFamilyInertOnce;
+    private warnShellTagsNoEvictionOnce;
+    /**
+     * Generation gate for shell writes and the capture scheduler
+     * (isTagsInvalidatedSince). With KV it is the durable marker cascade.
+     * Without KV there are no markers: in purge mode the per-request memo is
+     * the only signal — a capture racing THIS request's updateTag() is still
+     * rejected (read-your-own-writes), while cross-request races are bounded
+     * by ttl+swr exactly like the data families' purge-mode writes. Without
+     * either, fail open (ttl/swr-only semantics, warned at putShell).
+     * @internal
+     */
+    private isShellGenerationInvalidated;
     /**
      * Get a cached PPR shell entry from Cache API, falling through to KV and
      * promoting a valid KV hit. Both tiers store one envelope so the prelude,
@@ -278,13 +289,14 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
         shouldRevalidate?: boolean;
     } | null>;
     /**
-     * Store a PPR shell envelope in Cache API and, when its retention meets KV's
-     * 60-second floor, KV. The shared write is registered with waitUntil and
-     * awaited so invalidation rejection can be acknowledged to the capture
-     * scheduler. Short-lived shells remain useful in L1 even though KV rejects
-     * them.
+     * Store a PPR shell envelope in Cache API and, when KV is configured and
+     * the retention meets its 60-second floor, KV. The shared write is
+     * registered with waitUntil and awaited so invalidation rejection can be
+     * acknowledged to the capture scheduler. Short-lived shells remain useful
+     * in L1 even though KV rejects them; a KV-less store is L1-only by design
+     * (edge-only ppr — see the section comment).
      */
-    putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | void>;
+    putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | "uncacheable" | void>;
     /** Rebuild the public shell entry from its validated storage envelope. */
     private shellEnvelopeToEntry;
     /** Build the Cache API representation of the coupled shell envelope. */
@@ -569,7 +581,9 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * Shell tag-generation gate (SegmentCacheStore.isTagsInvalidatedSince): the
      * SAME KV markers used by runtime envelopes also evict immutable build shells
      * and captures whose write races updateTag(). Thin public wrapper over the
-     * private envelope check (marker >= since, fail open).
+     * shell generation check (marker >= since, fail open); KV-less it degrades
+     * to the per-request memo in purge mode and to false otherwise — see
+     * isShellGenerationInvalidated.
      */
     isTagsInvalidatedSince(tags: string[], sinceMs: number): Promise<boolean>;
     invalidateTags(tags: string[]): Promise<void>;

package/dist/types/cache/shell-snapshot.d.ts

@@ -90,7 +90,7 @@ export declare class RecordingShellStore<TEnv = unknown> implements SegmentCache
         entry: ShellCacheEntry;
         shouldRevalidate?: boolean;
     } | null>;
-    putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | void>;
+    putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | "uncacheable" | void>;
     invalidateTags(tags: string[]): Promise<void>;
 }
 /** True iff `store` is a RecordingShellStore (duck-typed across module copies). */
@@ -181,6 +181,6 @@ export declare class SeededShellStore<TEnv = unknown> implements SegmentCacheSto
         entry: ShellCacheEntry;
         shouldRevalidate?: boolean;
     } | null>;
-    putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | void>;
+    putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | "uncacheable" | void>;
     invalidateTags(tags: string[]): Promise<void>;
 }

package/dist/types/cache/types.d.ts

@@ -161,18 +161,37 @@ export interface SegmentCacheStore<TEnv = unknown> {
      * @param tags - Optional cache tags for invalidation (participates in
      *   invalidateTags via the same tag machinery as the item family)
      * @returns `invalidated` when a generation marker rejected the write,
-     *   `stored` when acknowledged, or void for stores without acknowledgements.
+     *   `stored` when acknowledged, `uncacheable` when the entry can NEVER be
+     *   stored under the current configuration (every retry would refuse
+     *   identically — the capture scheduler backs the key off instead of
+     *   recapturing per MISS; CFCacheStore returns it for a tag set whose
+     *   Cache-Tag header overflows in KV-less purge mode), or void for stores
+     *   without acknowledgements.
      */
-    putShell?(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | void>;
+    putShell?(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | "uncacheable" | void>;
     /**
      * Declares the shell family present-but-inert: getShell/putShell exist but
-     * no-op (CFCacheStore without a KV namespace). scheduleShellCapture skips
-     * captures whose only write target is inert — the background render would be
-     * dead work that still occupies the per-isolate serialized capture queue
-     * (a promise-heavy route bakes for seconds per MISS with nothing stored).
-     * Absent/false means the family, when present, actually stores.
+     * no-op (a custom store whose backing tier is conditionally unavailable).
+     * scheduleShellCapture skips captures whose only write target is inert —
+     * the background render would be dead work that still occupies the
+     * per-isolate serialized capture queue (a promise-heavy route bakes for
+     * seconds per MISS with nothing stored). Absent/false means the family,
+     * when present, actually stores. The built-in stores never declare it:
+     * CFCacheStore is L1-only without KV (edge-only ppr), not inert.
      */
     shellFamilyInert?: boolean;
+    /**
+     * Declares isTagsInvalidatedSince present-but-inert: the store implements
+     * the method but has no DURABLE invalidation history behind it (a KV-less
+     * CFCacheStore answers from the per-request memo at best). Runtime shells
+     * tolerate that — purge eviction plus ttl/swr bound their staleness — but
+     * a TAGGED build-manifest shell is immutable with no ttl of its own, so
+     * serving it on such a store would make updateTag() a permanent no-op for
+     * it. The build-shell read-through declines tagged entries on this flag
+     * (same declared-intent-cannot-be-honored doctrine as a store missing the
+     * method entirely). Absent/false means answers are durably backed.
+     */
+    tagHistoryInert?: boolean;
     /**
      * Get a cached function result by key.
      * Returns the serialized value, optional handle data, and staleness flag.

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

@@ -126,9 +126,10 @@ export interface ShellCaptureDebugEvent {
      *   the capture was not attempted
      * - skip-capacity: the isolate capture queue is full; a later request may retry
      * - skip-inert-store: the resolved store's shell family is missing or
-     *   declared inert (SegmentCacheStore.shellFamilyInert — a CFCacheStore
-     *   without a KV namespace); nothing could store the result, so the
-     *   background render was not scheduled at all
+     *   declared inert (SegmentCacheStore.shellFamilyInert — a custom store
+     *   whose backing tier is unavailable; built-in stores never declare it);
+     *   nothing could store the result, so the background render was not
+     *   scheduled at all
      * - skip-queue-timeout: the capture waited past CAPTURE_QUEUE_WAIT_BUDGET_MS
      *   behind other captures and was dropped unrun (no backoff — the route is
      *   not doomed, the isolate was busy; a later request re-probes). Carries
@@ -160,7 +161,7 @@ export interface ShellCaptureDebugEvent {
     /** A bake-lane loader settled into a shell that uses TTL/SWR-only invalidation. */
     untaggedBake?: true;
     /** Outcome reported by a store that supports shell-write acknowledgements. */
-    storeWrite?: "stored" | "invalidated";
+    storeWrite?: "stored" | "invalidated" | "uncacheable";
     /** Consecutive failure count in the key's backoff entry, when one exists. */
     backoffFailures?: number;
     /** Ms remaining in the key's backoff window, when one exists. */
@@ -282,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.7.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.7.0",
+  "version": "0.9.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

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"
     },