@rangojs/router 0.8.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-capture.ts

@@ -917,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
@@ -1767,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) {

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