@rangojs/router 0.34.0 → 0.35.0

package/src/ssr/index.tsx

@@ -232,7 +232,7 @@ export interface SSRDependencies<TEnv = unknown> {
    *
    * When UNSET, createSSRHandler and createShellCaptureHandler auto-raise to
    * Number.MAX_SAFE_INTEGER for document renders and shell captures whose
-   * matched chain has a `loader(Def, { ssr: false })` entry (payload segments
+   * matched chain has a `loader(Def, { ssr: "await" })` entry (payload segments
    * carry `awaitBeforeFlush`): the loader was awaited before first flush
    * precisely so its content ships in-place, and React 19.2's Fizz would
    * otherwise move any completed boundary over ~500 bytes to an end-of-stream
@@ -441,7 +441,7 @@ function trackDocumentClientLoads<T>(decode: () => T): {
 const SSR_FALSE_FIRST_FLUSH_TURNS = 3;
 
 /**
- * True when the matched chain has a `loader(Def, { ssr: false })` entry: its
+ * True when the matched chain has a `loader(Def, { ssr: "await" })` entry: its
  * payload segments carry `awaitBeforeFlush` (resolveOwnerLoaders).
  */
 function hasAwaitBeforeFlush(payload: {
@@ -453,7 +453,7 @@ function hasAwaitBeforeFlush(payload: {
 /**
  * The progressiveChunkSize renderHTML and captureShellHTML pass to Fizz (see
  * SSRDependencies.progressiveChunkSize): the explicit option, else the
- * ssr:false auto-raise.
+ * ssr: "await" auto-raise.
  */
 function documentChunkSize(
   explicit: number | undefined,
@@ -463,7 +463,7 @@ function documentChunkSize(
 }
 
 /**
- * ssr: false documents only: before the first flush, give Fizz the turns a
+ * ssr: "await" documents only: before the first flush, give Fizz the turns a
  * task waiting on an already-settling thenable needs, so a boundary that
  * waits on nothing else completes in place (#1138).
  *
@@ -953,7 +953,7 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
 
       const bootstrap = await resolveBootstrap(deps);
 
-      // ssr:false auto-raise (see SSRDependencies.progressiveChunkSize).
+      // ssr: "await" auto-raise (see SSRDependencies.progressiveChunkSize).
       // Awaiting the payload here is latency-neutral: fizz cannot emit even
       // <html> until this same promise settles. A rejection lands in the
       // catch below — the same reportRenderError path a shell error takes.
@@ -1149,7 +1149,7 @@ export function createShellCaptureHandler<TEnv = unknown>(
         origin: opts.origin,
       });
 
-      // ssr:false auto-raise (SSRDependencies.progressiveChunkSize); resume()
+      // ssr: "await" auto-raise (SSRDependencies.progressiveChunkSize); resume()
       // inherits it from the postponed state. A rejected or late payload
       // skips it and fails or degrades below as before.
       const awaitsBeforeFlush = await Promise.race([

package/src/ssr/ssr-root.tsx

@@ -150,7 +150,7 @@ function createSsrEventController(opts: {
  * Deserialize the Flight stream branch into the payload SsrRoot renders,
  * fragment expansion included. Factored out of SsrRoot so createSSRHandler and
  * createShellCaptureHandler can create the promise BEFORE fizz starts and read
- * metadata that must influence the fizz call itself (the ssr:false
+ * metadata that must influence the fizz call itself (the ssr: "await"
  * progressiveChunkSize auto-raise) — awaiting it there is latency-neutral
  * because fizz cannot emit even <html> until this same promise settles.
  */

package/src/ssr-suspension-warning.ts

@@ -1,5 +1,5 @@
 /**
- * Dev-only diagnostic for the { ssr: false } SSR-completeness opt-in.
+ * Dev-only diagnostic for the { ssr: "await" } SSR-completeness opt-in.
  *
  * A document render that awaits flagged loaders before first flush is usually
  * expected to produce an SSR-complete boundary — but the await is scoped per
@@ -37,7 +37,7 @@ export function warnAwaitedSsrSuspension(
 
   if (awaitedLoaderIds.includes(loaderId)) {
     console.error(
-      `[rango] Loader "${loaderId}" is flagged { ssr: false } and was awaited ` +
+      `[rango] Loader "${loaderId}" is flagged { ssr: "await" } and was awaited ` +
         `before first flush, but its useLoader read observed a still-pending ` +
         `promise during SSR. If its Suspense fallback appears in the SSR'd HTML, ` +
         `please report it to @rangojs/router with a reproduction.`,
@@ -46,12 +46,12 @@ export function warnAwaitedSsrSuspension(
   }
 
   console.warn(
-    `[rango] The document render awaited { ssr: false } loader(s) ` +
+    `[rango] The document render awaited { ssr: "await" } loader(s) ` +
       `${JSON.stringify(awaitedLoaderIds)} before first flush, but ` +
       `useLoader("${loaderId}") still suspended during SSR. "${loaderId}" is not ` +
       `flagged, so the Suspense boundary above that read streams as its fallback ` +
       `and the content under it stays hidden until JS runs. If the boundary must ` +
-      `be SSR-complete, flag "${loaderId}" with { ssr: false } too, or move its ` +
+      `be SSR-complete, flag "${loaderId}" with { ssr: "await" } too, or move its ` +
       `read behind its own boundary. If it streams deliberately, ignore this.`,
   );
 }

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, { ssr: false })` so the document render awaits it
+   * `loader(Def, { ssr: "await" })` so the document render awaits it
    * (see {@link LoaderOptions}).
    *
    * @example
@@ -175,29 +175,29 @@ export type LoaderFn<
 /**
  * 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.
+ * Default (omitted / `"stream"`): 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
+ * `ssr: "await"` makes the server renders that produce HTML await this
+ * loader: 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); a ppr shell capture, at runtime or at build time
+ * for a Prerender + ppr route, awaits it too. 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), and so are its handle
  * pushes, a pushed promise or `.defer()` included: the capture awaits it and
  * every HIT serves the value it settled to (#1182). A pushed promise that
  * rejects, or misses `ppr.captureTimeout`, keeps the route on MISS. A value
- * that must stay per request belongs to a loader without `ssr: false` — see
+ * that must stay per request belongs to a loader without `ssr: "await"` — see
  * the ppr docs.
  *
- * Scoped per LOADER, not per segment: an `ssr: false` loader alongside a
+ * Scoped per LOADER, not per segment: an `ssr: "await"` loader alongside a
  * deliberately streaming sibling awaits only itself, and the sibling keeps
  * streaming behind its `loading()`/Suspense boundary. Watch the scoping when
  * the boundary must be SSR-complete: ONE unflagged read under it still
@@ -206,7 +206,7 @@ export type LoaderFn<
  * site naming the unflagged loader (ssr-suspension-warning.ts).
  */
 export type LoaderOptions = {
-  ssr?: boolean;
+  ssr?: "stream" | "await";
   /**
    * `prefetch: false` keeps this loader out of every `<Link>` prefetch: a
    * prefetch (a partial request with `X-Rango-Prefetch`) does not execute
@@ -236,7 +236,7 @@ export type LoaderOptions = {
    * Limits: a handler that awaits the loader with `ctx.use()` makes it run in
    * the prefetch anyway; the loader cannot call `ctx.rendered()` (it throws
    * on every request); on a `ppr` route the flag is ignored for an
-   * `ssr: false` loader (the bake lane), with a dev warning. In the fill
+   * `ssr: "await"` loader (the bake lane), with a dev warning. In the fill
    * request only deferred work and middleware run, so values a held handler
    * would have set with `ctx.set()` are not visible.
    */

package/src/types/segments.ts

@@ -164,7 +164,7 @@ export interface ResolvedSegment {
   loaderData?: any; // For loaders: the resolved data from loader execution
   /**
    * True when this loader was awaited before first flush
-   * (loader(Def, { ssr: false })). Stamped by resolveOwnerLoaders on
+   * (loader(Def, { ssr: "await" })). Stamped by resolveOwnerLoaders on
    * document AND shell-capture renders — capture bakes flagged loaders and
    * awaits the same lane. Feeds segment-system's settled-value delivery and
    * the dev SSR suspension warning (ssr-suspension-warning.ts).
@@ -185,7 +185,7 @@ export interface ResolvedSegment {
   loaderIds?: string[]; // IDs ($$id) of loaders for this segment
   /**
    * Per-loader UNDECODED results for a layout/route stream map.
-   * Flagged (ssr:false) entries are settled values; unflagged siblings
+   * Flagged (ssr: "await") entries are settled values; unflagged siblings
    * stay promises. Parallel slots do not use this channel — they pin
    * loading() / live-lane holes via use(loaderDataPromise).
    */

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

@@ -356,10 +356,10 @@ export type PathHelpers<TEnv> = {
   /**
    * Attach a data loader to the current route/layout.
    *
-   * 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.
+   * Pass `{ ssr: "await" }` 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

package/src/urls/pattern-types.ts

@@ -67,7 +67,7 @@ export interface PartialPrerenderProps {
    * Upper bound (serialized UTF-8 bytes) on the loader pins in the capture
    * data snapshot: the bake-lane loader records. The doc record (the handler
    * layer every HIT replays) is exempt. A document HIT is served only from an
-   * entry that holds a pin for every `ssr: false` loader its HTML baked, so
+   * entry that holds a pin for every `ssr: "await"` loader its HTML baked, so
    * over the cap no document shell is stored: documents render in full
    * (MISS), and client navigations still replay the handler layer and run
    * those loaders fresh. Reported once per key. Defaults to 8 MiB. The whole

package/src/use-loader.tsx

@@ -256,12 +256,13 @@ function useLoaderInternal<T>(
     [groupKey],
   );
   const hasGroups = groupList.length > 0;
+  // A grouped read without a key refreshes a bucket no other reader names.
+  const usesPrivateBucket = hasGroups && key === undefined;
   const privateBucketIdRef = useRef<string | null>(null);
-  if (hasGroups && key === undefined && privateBucketIdRef.current === null) {
+  if (usesPrivateBucket && privateBucketIdRef.current === null) {
     privateBucketIdRef.current = `__rg${privateGroupBucketSeq++}`;
   }
-  const effectiveKey =
-    key ?? (hasGroups ? privateBucketIdRef.current! : undefined);
+  const effectiveKey = usesPrivateBucket ? privateBucketIdRef.current! : key;
   const bucketKey =
     effectiveKey === undefined ? loaderId : `${loaderId}::${effectiveKey}`;
 
@@ -352,6 +353,7 @@ function useLoaderInternal<T>(
       {
         loaderId,
         ephemeral: !hasContextData,
+        owned: usesPrivateBucket,
         group: hasGroups ? groupList : undefined,
         refetch: hasGroups ? groupRefetch : undefined,
         onStreamPending: hasContextData

package/src/vite/discovery/shell-prerender-phase.ts

@@ -188,7 +188,7 @@ export async function runShellPrerenderPhase(
       injectRSCPayload: htmlStream.injectRSCPayload,
       headScripts: "preinit",
       // Build-captured shells honor the explicit outlining budget, or the
-      // ssr:false auto-raise without one (createShellCaptureHandler): the
+      // ssr: "await" auto-raise without one (createShellCaptureHandler): the
       // capture value rides the postponed state into every runtime resume().
       ...(s.opts?.progressiveChunkSize !== undefined && {
         progressiveChunkSize: s.opts.progressiveChunkSize,

package/src/vite/plugin-types.ts

@@ -190,7 +190,7 @@ interface RangoBaseOptions {
    * which is why React outlines by default.
    *
    * When UNSET, document renders and PPR shell captures whose matched chain
-   * has a `loader(Def, { ssr: false })` entry auto-raise to MAX_SAFE_INTEGER —
+   * has a `loader(Def, { ssr: "await" })` entry auto-raise to MAX_SAFE_INTEGER —
    * the loader was awaited before first flush precisely so its content ships
    * in-place, and outlining the boundary it feeds would defeat that. A shell
    * HIT inherits the captured value, so it matches the live render. Setting