@rangojs/router 0.16.0 → 0.18.0

package/src/router/router-options.ts

@@ -164,8 +164,10 @@ export interface RangoOptions<TEnv = any> {
    *
    * Must be a client component ("use client") that accepts { children }.
    *
-   * If not provided, a default document with basic HTML structure is used:
-   * `<html><head><meta charset/viewport></head><body>{children}</body></html>`
+   * If not provided, a default document is used: `Html.Meta` and `Html.Scripts`
+   * in `<head>`, `Html.Scripts position="body"` before `{children}` and
+   * `Html.ScrollRestoration` after it. Pass your own to set `getKey` or to
+   * leave back/forward scrolling to the browser.
    *
    * @example
    * ```typescript
@@ -201,7 +203,8 @@ export interface RangoOptions<TEnv = any> {
 
   /**
    * Default not-found boundary fallback used when no notFoundBoundary is defined in the route tree
-   * If not provided, DataNotFoundError will be treated as a regular error
+   * If not provided, notFound() renders the `notFound` option, else a plain
+   * `<h1>Not Found</h1>` (status 404)
    */
   defaultNotFoundBoundary?: ReactNode | NotFoundBoundaryHandler;
 
@@ -211,7 +214,7 @@ export interface RangoOptions<TEnv = any> {
    * This is rendered within your document/app shell with a 404 status code.
    * Use this for a custom 404 page that maintains your app's look and feel.
    *
-   * If not provided, a default "Page not found" component is rendered.
+   * If not provided, a plain `<h1>Not Found</h1>` is rendered.
    *
    * Can be a static ReactNode or a function receiving the pathname.
    *
@@ -368,7 +371,7 @@ export interface RangoOptions<TEnv = any> {
    * When provided, enables:
    * - ctx.theme and ctx.setTheme() in route handlers
    * - useTheme() hook for client components
-   * - FOUC prevention via inline script in MetaTags
+   * - FOUC prevention via inline script in `<Html.Meta />`
    * - Automatic ThemeProvider wrapping in NavigationProvider
    *
    * @example

package/src/router/segment-resolution/fresh.ts

@@ -37,7 +37,7 @@ import { applyViewTransitionDefault } from "./view-transition-default.js";
 import { _getRequestContext } from "../../server/request-context.js";
 import { getRouterContext } from "../router-context.js";
 import { observeStreamedHandler } from "./streamed-handler-telemetry.js";
-import { observeHandler } from "../instrument.js";
+import { observeSegmentHandler } from "../instrument.js";
 import {
   track,
   RangoContext,
@@ -120,12 +120,8 @@ export async function resolveLoaders<TEnv>(
   // loading-disabled entries consult it), so normal requests are unchanged.
   const emitStreaming = !loadingDisabled || isShellCaptureActive();
 
-  // PPR lane decision for this entry's loaders (loader-container-bake): an
-  // entry WITHOUT renderable loading() puts its loaders on the BAKE lane —
-  // executed at capture (container bakes, nested pending promises hole at the
-  // consumer's Suspense) and overlay-pinned from the shell snapshot on a HIT.
-  // Renderable loading() keeps the LIVE lane (masked at capture, always
-  // fresh). Computed per entry; resolveLoaderData applies the policy.
+  // PPR bake/seed key input only; lane rule: see resolveLoaderData
+  // (loader-cache.ts). Unflagged loaders mask at capture regardless of the key.
   const bakeLane = !entryLoadingMasksLoaders(entry.loading);
 
   // Error context for wrapLoaderPromise: without it, a throwing DSL loader never
@@ -146,9 +142,9 @@ export async function resolveLoaders<TEnv>(
     // barrier), and the loader body can call rendered() before the await below
     // is reached.
     //
-    // Shell-capture renders await too: flagged loaders BAKE at capture
-    // (loader-mask masks only LIVE-lane loaders). Capture must await them so
-    // bake-lane handle pushes land in the prelude.
+    // Shell-capture renders await too: flagged loaders execute at capture
+    // (lane rule: see resolveLoaderData, loader-cache.ts), so their handle
+    // pushes must land in the prelude.
     const awaitedIndices = registerAwaitBeforeFlushIds(loaderEntries);
 
     // Streaming loaders: promises kick off now, settle during RSC serialization.
@@ -177,9 +173,7 @@ export async function resolveLoaders<TEnv>(
               // bakes at capture regardless of the entry's loading() lane
               // (loader-cache.ts capture branch) and its HIT-tail seed
               // overlay needs the same key.
-              bakeLane || loaderEntry.awaitBeforeFlush === true
-                ? segmentId
-                : null,
+              bakeLane || loaderEntry.bake === true ? segmentId : null,
             ),
           ),
           entry,
@@ -227,7 +221,7 @@ export async function resolveLoaders<TEnv>(
           loaderEntry,
           ctx,
           ctx.pathname,
-          bakeLane || loaderEntry.awaitBeforeFlush === true ? segmentId : null,
+          bakeLane || loaderEntry.bake === true ? segmentId : null,
         ),
       ),
       entry,
@@ -276,6 +270,16 @@ export interface ResolveSegmentOptions {
    * so error boundaries keep catching at request time.
    */
   throwOnError?: boolean;
+  /**
+   * The matched route's full entry chain. resolveAllSegments defaults it to
+   * its `entries`; withCacheLookup passes it when it resolves only the entries
+   * above a cache() boundary. An orphan list can hold an entry of the chain: a
+   * bare cache() marker sits in its layout's layout[] (it wraps that layout's
+   * routes) and is the parent of the routes after it. For those routes it
+   * resolves once, as a chain entry, below the cache() header latch (issue
+   * #918: resolved twice on a MISS, once and discarded on a HIT).
+   */
+  chain?: readonly EntryData[];
 }
 
 /**
@@ -349,6 +353,7 @@ export async function resolveSegment<TEnv>(
     }
 
     for (const orphan of entry.layout) {
+      if (options?.chain?.includes(orphan)) continue;
       const orphanSegments = await resolveOrphanLayout(
         orphan,
         params,
@@ -389,7 +394,7 @@ export async function resolveSegment<TEnv>(
       const doneRouteHandler = track(`handler:${entry.id}`, 2);
       if (entry.loading) {
         const result = handleHandlerResult(
-          observeHandler(entry.id, handler, context),
+          observeSegmentHandler(entry.shortCode, entry.id, handler, context),
         );
         if (result instanceof Promise) {
           warnOnStreamedResponse(result, entry.id);
@@ -413,7 +418,12 @@ export async function resolveSegment<TEnv>(
         }
       } else {
         component = handleHandlerResult(
-          await observeHandler(entry.id, handler, context),
+          await observeSegmentHandler(
+            entry.shortCode,
+            entry.id,
+            handler,
+            context,
+          ),
         );
         doneRouteHandler();
       }
@@ -578,6 +588,26 @@ export async function resolveOrphanLayout<TEnv>(
     resolvedParallelEntries.add(parallelEntry.id);
   }
 
+  // Routeless entries nested in this one (a layout() after a bare cache()
+  // marker, a wrapper inside a routeless wrapper) wrap the same content one
+  // level deeper. Issue #918: they were never rendered. None is in the
+  // matched chain: that would put this orphan in it, and resolveSegment
+  // skips those.
+  for (const nested of orphan.layout) {
+    segments.push(
+      ...(await resolveOrphanLayout(
+        nested,
+        params,
+        context,
+        loaderPromises,
+        belongsToRoute,
+        deps,
+        options,
+        routeKey,
+      )),
+    );
+  }
+
   return segments;
 }
 
@@ -643,7 +673,12 @@ export async function resolveParallelEntry<TEnv>(
       if (hasLoadingFallback) {
         const result =
           typeof handler === "function"
-            ? observeHandler(`${parallelEntry.id}.${slot}`, handler, context)
+            ? observeSegmentHandler(
+                `${parentShortCode}.${slot}`,
+                `${parallelEntry.id}.${slot}`,
+                handler,
+                context,
+              )
             : handler;
         if (result instanceof Promise) {
           result.finally(doneParallelHandler).catch(() => {});
@@ -667,7 +702,8 @@ export async function resolveParallelEntry<TEnv>(
       } else {
         component =
           typeof handler === "function"
-            ? await observeHandler(
+            ? await observeSegmentHandler(
+                `${parentShortCode}.${slot}`,
                 `${parallelEntry.id}.${slot}`,
                 handler,
                 context,
@@ -736,6 +772,10 @@ export async function resolveAllSegments<TEnv>(
 ): Promise<ResolvedSegment[]> {
   const allSegments: ResolvedSegment[] = [];
   const seenIds = new Set<string>();
+  const segmentOptions: ResolveSegmentOptions = {
+    ...options,
+    chain: options?.chain ?? entries,
+  };
 
   // ppr routes are document-scoped cached territory: the whole chain (root
   // layout down to the page) bakes into the shared shell, so the header-write
@@ -760,8 +800,9 @@ export async function resolveAllSegments<TEnv>(
     // Set ALS flag when entering a cache() boundary so that ctx.get()
     // can guard non-cacheable variable reads. Also latch the header-write
     // scope (response-level side effects — headers/cookies/status).
-    // Persists for all descendant entries.
-    if (entry.type === "cache") {
+    // Persists for all descendant entries. A route entry carries `cache` when
+    // cache() is among its own children (dsl-helpers.ts cache()).
+    if (entry.cache) {
       const store = RangoContext.getStore();
       if (store) store.insideCacheScope = true;
       latchCachedHeaderScope("cache", routeKey);
@@ -779,7 +820,7 @@ export async function resolveAllSegments<TEnv>(
           loaderPromises,
           deps,
           false,
-          options,
+          segmentOptions,
         ),
       (seg) => [seg],
       deps,

package/src/router/segment-resolution/helpers.ts

@@ -29,7 +29,7 @@ import type {
 import type { SegmentResolutionDeps } from "../types.js";
 import { debugLog } from "../logging.js";
 import { tryStaticLookup } from "./static-store.js";
-import { observeHandler } from "../instrument.js";
+import { observeSegmentHandler } from "../instrument.js";
 import type { TelemetrySink } from "../telemetry.js";
 import { resolveSink, safeEmit, getRequestId } from "../telemetry.js";
 
@@ -175,7 +175,9 @@ export async function resolveLayoutComponent<TEnv>(
   // by track("handler:<id>") at the call site). handleHandlerResult stays OUTSIDE
   // the span so a handler that returns a Response (redirect control flow, which it
   // rethrows) is not recorded as a span error — mirrors the route-handler sites.
-  return handleHandlerResult(await observeHandler(entry.id, handler, context));
+  return handleHandlerResult(
+    await observeSegmentHandler(entry.shortCode, entry.id, handler, context),
+  );
 }
 
 // ---------------------------------------------------------------------------