@rangojs/router 0.7.0 → 0.9.0

package/src/rsc/rsc-rendering.ts

@@ -155,6 +155,7 @@ function createShellCaptureDescriptor(
   ctx: HandlerContext<any>,
   key: string,
   searchSeed: string,
+  originSeed: string,
   pprConfig: ResolvedPprConfig,
   store: SegmentCacheStore<any>,
   navigationOnly?: true,
@@ -162,6 +163,11 @@ function createShellCaptureDescriptor(
   return {
     key,
     searchSeed,
+    // Derived from the same request URL as the key (the callers compute
+    // both next to each other, so they cannot drift): seeding the origin
+    // keeps origin-dependent static markup (Link's data-external)
+    // identical across capture, resume, and browser hydration.
+    originSeed,
     buildVersion: ctx.version,
     ttl: pprConfig.ttl,
     swr: pprConfig.swr,
@@ -519,6 +525,7 @@ function* shellServePlan<TEnv>(
     ctx,
     key,
     shellSearchSeed(url, reqCtx._searchParamsFilter),
+    url.origin,
     pprConfig,
     store,
   );
@@ -1004,6 +1011,7 @@ function scheduleNavigationShellCapture<TEnv>(
       partialCaptureKey ??
         buildNavigationShellKey(url, reqCtx._searchParamsFilter),
       shellSearchSeed(url, reqCtx._searchParamsFilter),
+      url.origin,
       pprConfig,
       store,
       true,
@@ -1524,6 +1532,8 @@ function serveShellHit(
         // The shell key's own search — identical to the capture seed for
         // this key, so the resume tree matches the captured tree.
         search: shellSearchSeed(url, reqCtx._searchParamsFilter),
+        // The HIT request's origin — same host as the capture's (key-scoped).
+        origin: url.origin,
       }),
     );
   };

package/src/rsc/shell-build-manifest.ts

@@ -306,20 +306,27 @@ export async function lookupBuildShell(
     const entry = record.entry;
     if (record.tags && record.tags.length > 0) {
       const check = store.isTagsInvalidatedSince;
-      if (typeof check !== "function") {
+      if (typeof check !== "function" || store.tagHistoryInert) {
         // A tagged build entry on a store that cannot answer "was this tag
         // invalidated since the build" must not serve: updateTag() could
-        // never evict it. Declared intent that cannot be honored deserves a
+        // never evict it. That covers a store missing the method AND one
+        // whose answers have no durable history behind them
+        // (SegmentCacheStore.tagHistoryInert — a KV-less CFCacheStore's
+        // memo-only answers would let the immutable asset resurrect on the
+        // next request). Declared intent that cannot be honored deserves a
         // diagnostic; the route keeps runtime-capture semantics.
         const key = buildShellManifestKey(url.pathname);
         if (!warnedTagCheckUnsupported.has(key)) {
           warnedTagCheckUnsupported.add(key);
           console.warn(
             `[rango] Build-time shell for "${url.pathname}" carries cache tags, but ` +
-              "the app cache store does not implement isTagsInvalidatedSince(), so " +
-              "updateTag() could not evict it. The entry is not served; the route " +
-              "keeps runtime shell capture. Use MemorySegmentCacheStore, CFCacheStore, " +
-              "or VercelCacheStore (or add the method to your custom store).",
+              "the app cache store cannot answer tag-invalidation history durably " +
+              (typeof check !== "function"
+                ? "(isTagsInvalidatedSince() is not implemented), "
+                : "(no durable tag history — a CFCacheStore without a KV namespace), ") +
+              "so updateTag() could not evict it. The entry is not served; the route " +
+              "keeps runtime shell capture. Use MemorySegmentCacheStore, a KV-backed " +
+              "CFCacheStore, or VercelCacheStore (or add the method to your custom store).",
           );
         }
         return null;

package/src/rsc/shell-capture.ts

@@ -509,9 +509,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
@@ -554,7 +555,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. */
@@ -916,6 +917,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
@@ -1005,7 +1015,8 @@ export function scheduleShellCapture(
   // serialized queue (a promise-heavy route bakes for seconds per MISS),
   // starving captures that CAN store. Skip scheduling entirely when the
   // resolved store (same defaulting as captureAndStoreShell) has no shell
-  // family or declared it inert (CFCacheStore without a KV namespace).
+  // family or declared it inert (a custom-store escape hatch; built-in
+  // stores never declare it — a KV-less CFCacheStore stores L1-only).
   const scheduledStore = descriptor.store ?? reqCtx._cacheStore;
   if (!scheduledStore?.putShell || scheduledStore.shellFamilyInert) {
     publishCaptureDebugEvent(descriptor, { key, outcome: "skip-inert-store" });
@@ -1765,6 +1776,7 @@ async function captureAndStoreShell(
           // The shell key's own search seeds the capture render's store —
           // static-part search reads bake what the key names.
           search: capture.searchSeed,
+          origin: capture.originSeed,
         }),
       );
     } catch (error) {
@@ -2028,6 +2040,21 @@ async function captureAndStoreShell(
           );
           return "refused";
         }
+        if (storeWrite === "uncacheable") {
+          // The store declared the entry unstorable under its current
+          // configuration — every retry would refuse identically, so back
+          // the key off like any refused capture instead of burning a full
+          // serialized render per MISS. Store-neutral on purpose: the
+          // acknowledging store emits its own diagnostic naming the specific
+          // limit (CFCacheStore warns about the over-limit Cache-Tag set).
+          warnCaptureRefusedOnce(
+            capture.key,
+            "the store cannot cache this shell under its current configuration and acknowledged " +
+              "the write as permanently refusable, so the key is backed off. See the cache store's " +
+              "own warning for the specific limit and remedy.",
+          );
+          return "refused";
+        }
       } catch (error) {
         // Best-effort: a failed put must never throw out of the background task.
         reportCacheError(

package/src/rsc/ssr-setup.ts

@@ -120,6 +120,10 @@ export function createSsrHtmlStage<TEnv>(
           ...options.render,
           streamMode,
           search: options.url.search,
+          // origin: same out-of-band channel — seeds the SSR store location
+          // so origin-dependent markup (Link's data-external) agrees with the
+          // browser's window.location across hydration.
+          origin: options.url.origin,
         }),
       ...(options.init && { init: options.init }),
     };

package/src/rsc/types.ts

@@ -187,6 +187,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;
 }
 
 /**
@@ -208,7 +214,12 @@ export interface SSRModule {
    */
   captureShellHTML?: (
     rscStream: ReadableStream<Uint8Array>,
-    options: { quiesce: Promise<void>; maxWaitMs?: number; search?: string },
+    options: {
+      quiesce: Promise<void>;
+      maxWaitMs?: number;
+      search?: string;
+      origin?: string;
+    },
   ) => Promise<{ prelude: Uint8Array; postponed: string | null } | null>;
 
   /**
@@ -221,7 +232,12 @@ export interface SSRModule {
    */
   resumeShellHTML?: (
     rscStream: ReadableStream<Uint8Array>,
-    options: { postponed: string | null; nonce?: string; search?: string },
+    options: {
+      postponed: string | null;
+      nonce?: string;
+      search?: string;
+      origin?: string;
+    },
   ) => Promise<ReadableStream<Uint8Array>>;
 }
 

package/src/server/context.ts

@@ -108,7 +108,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/src/server/request-context.ts

@@ -620,7 +620,7 @@ export interface RequestContext<
 
   /**
    * @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/src/ssr/index.tsx

@@ -114,6 +114,14 @@ 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;
 }
 
 /**
@@ -363,6 +371,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;
 }
 
 /**
@@ -391,6 +406,8 @@ interface ShellResumeOptions {
    * postponed holes.
    */
   search?: string;
+  /** The HIT request's origin — same host as the capture's (key-scoped). */
+  origin?: string;
 }
 
 /**
@@ -472,7 +489,7 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
     rscStream: ReadableStream<Uint8Array>,
     options?: SSRRenderOptions,
   ): Promise<ReadableStream<Uint8Array>> {
-    const { nonce, formState, streamMode, search } = options ?? {};
+    const { nonce, formState, streamMode, search, origin } = options ?? {};
 
     try {
       // Tee the stream:
@@ -490,6 +507,7 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
         // same key => same seed, so the resume tree matches the captured
         // tree while static-part search reads render what the key names.
         search,
+        origin,
       });
 
       // Get bootstrap script content
@@ -594,6 +612,7 @@ export function createShellCaptureHandler<TEnv = unknown>(
         // The shell key's own search: static-part search reads render what
         // the key names, and the resume pass seeds the identical string.
         search: opts.search,
+        origin: opts.origin,
       });
 
       // Bootstrap load raced against the deadline. A load that never resolves
@@ -767,7 +786,7 @@ export function createShellResumeHandler<TEnv = unknown>(
     rscStream: ReadableStream<Uint8Array>,
     opts: ShellResumeOptions,
   ): Promise<ReadableStream<Uint8Array>> {
-    const { postponed, nonce, search } = opts;
+    const { postponed, nonce, search, origin } = opts;
 
     try {
       if (postponed === null) {
@@ -800,6 +819,7 @@ export function createShellResumeHandler<TEnv = unknown>(
         // Same seed as the capture pass for this key: the resume tree must
         // match the captured tree above the holes, search reads included.
         search,
+        origin,
       });
 
       // EAGER injection (resume-only): the stored prelude — a complete document

package/src/ssr/ssr-root.tsx

@@ -70,13 +70,22 @@ function createSsrEventController(opts: {
    * names and both passes agree byte-for-byte.
    */
   search?: string;
+  /**
+   * Origin seeding the store location. Live fizz passes the request's real
+   * origin so origin-dependent markup (Link's data-external compares link
+   * origins against it) agrees with the browser's window.location; ppr
+   * capture/resume pass their request's origin (shell keys are host-scoped,
+   * so the two agree modulo protocol drift). Absent (build-time bare
+   * captures, tests) falls back to the historical internal host.
+   */
+  origin?: string;
   params?: Record<string, string>;
   handleData?: HandleData;
   matched?: string[];
 }): EventController {
   const location = new URL(
     `${opts.pathname}${opts.search ?? ""}`,
-    "http://localhost",
+    opts.origin ?? "http://localhost",
   );
   let params = opts.params ?? {};
   const rawMatched = opts.matched ?? [];
@@ -162,6 +171,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;
 }
 
 /**
@@ -188,6 +202,7 @@ export function createSsrRootComponent(opts: SsrRootOptions): React.FC {
     nonce,
     onPayloadSettled,
     search,
+    origin,
   } = opts;
 
   let payload: Promise<RscPayload> | undefined;
@@ -238,6 +253,7 @@ export function createSsrRootComponent(opts: SsrRootOptions): React.FC {
       eventController: createSsrEventController({
         pathname,
         search,
+        origin,
         params: resolved.metadata?.params,
         handleData,
         matched: resolved.metadata?.matched,

package/src/types/loader-types.ts

@@ -75,7 +75,7 @@ export type LoaderContext<
    * 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
@@ -174,29 +174,31 @@ export type LoaderFn<
 > = (ctx: LoaderContext<TParams, TEnv>) => Promise<T> | T;
 
 /**
- * Delivery mode for a DSL-registered loader: `loader(Def, { stream })`.
+ * SSR delivery for a DSL-registered loader: `loader(Def, { ssr })`.
  *
- * 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.
+ * 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.
  *
- * `"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.
+ * `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: a baked loader alongside a deliberately
- * dynamic sibling awaits only itself, and the sibling keeps streaming behind its
- * `loading()`/Suspense boundary.
+ * 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;
 };
 
 /**

package/src/urls/path-helper-types.ts

@@ -347,13 +347,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>,