@rangojs/router 0.0.0-experimental.114 → 0.0.0-experimental.116

package/src/router.ts

@@ -21,6 +21,7 @@ import type { AllUseItems } from "./route-types.js";
 import type { UrlPatterns } from "./urls.js";
 import type { UrlBuilder } from "./urls/pattern-types.js";
 import { urls } from "./urls.js";
+import { buildPrecomputedByPrefix } from "./build/prefix-tree-utils.js";
 import {
   type EntryData,
   getContext,
@@ -70,6 +71,7 @@ import {
 } from "./router/middleware.js";
 import {
   extractStaticPrefix,
+  joinPrefix,
   traverseBack,
 } from "./router/pattern-matching.js";
 import { resolveSink, safeEmit, getRequestId } from "./router/telemetry.js";
@@ -363,9 +365,11 @@ export function createRouter<TEnv = any>(
       getRouterPrecomputedEntries(routerId) ?? getPrecomputedEntries();
     if (current !== precomputedSource) {
       precomputedSource = current;
-      precomputedByPrefix = current
-        ? new Map(current.map((e) => [e.staticPrefix, e.routes]))
-        : null;
+      // buildPrecomputedByPrefix drops any staticPrefix owned by more than one
+      // leaf include instead of collapsing it last-wins (which would mis-assign
+      // one include's routes to another's entry and 500 a valid sibling route).
+      // Such shared-prefix includes resolve via the handler path instead.
+      precomputedByPrefix = current ? buildPrecomputedByPrefix(current) : null;
     }
     return precomputedByPrefix;
   }
@@ -832,10 +836,13 @@ export function createRouter<TEnv = any>(
 
       // Create placeholder RouteEntry for each lazy include
       for (const lazyInclude of lazyIncludes) {
-        // Compute the full URL prefix (combining parent prefix if any)
-        const fullPrefix = lazyInclude.context.urlPrefix
-          ? lazyInclude.context.urlPrefix + lazyInclude.prefix
-          : lazyInclude.prefix;
+        // Compute the full URL prefix (combining parent prefix if any). Use the
+        // slash-collapsing join so a trailing-slash parent prefix does not
+        // produce a double-slash staticPrefix the trie's sp can never match.
+        const fullPrefix = joinPrefix(
+          lazyInclude.context.urlPrefix,
+          lazyInclude.prefix,
+        );
 
         const lazyEntry: RouteEntry<TEnv> & { _lazyPrefix?: string } = {
           prefix: "",
@@ -998,6 +1005,13 @@ export function createRouter<TEnv = any>(
     // Expose basename for runtime manifest generation
     __basename: basename,
 
+    // Expose router-level boundary defaults for build-time clientChunks
+    // discovery (so a "use client" default boundary lands in app-fallback).
+    // These are createRouter options, never pushed onto EntryData.
+    __defaultErrorBoundary: defaultErrorBoundary,
+    __defaultNotFoundBoundary: defaultNotFoundBoundary,
+    __notFound: notFound,
+
     // RSC request handler (lazily created on first call)
     fetch: (() => {
       // Handler is created on first call and reused

package/src/rsc/manifest-init.ts

@@ -13,6 +13,7 @@ import {
   setRouteTrie,
   setRouterManifest,
   setRouterTrie,
+  setRouterPrecomputedEntries,
 } from "../route-map-builder.js";
 
 /**
@@ -36,47 +37,13 @@ export async function buildRouterTrieFromUrlpatterns(
     undefined,
     router.basename ? { urlPrefix: router.basename } : undefined,
   );
-  if (
-    generated._routeAncestry &&
-    Object.keys(generated._routeAncestry).length > 0
-  ) {
-    const { buildRouteTrie } = await import("../build/route-trie.js");
-    // Map each route to its include() staticPrefix so the trie
-    // returns the correct sp for lazy entry lookup in findMatch.
-    const routeToStaticPrefix: Record<string, string> = {};
-    for (const name of Object.keys(generated.routeManifest)) {
-      routeToStaticPrefix[name] = "";
-    }
-    // Override with prefix from include() entries so the trie
-    // returns the correct sp for lazy entry lookup in findMatch.
-    // Walk recursively to include routes in nested includes.
-    if (generated.prefixTree) {
-      const visitPrefixNode = (node: any): void => {
-        const sp = node.staticPrefix || "";
-        for (const route of node.routes || []) {
-          routeToStaticPrefix[route] = sp;
-        }
-        for (const child of Object.values(node.children || {})) {
-          visitPrefixNode(child);
-        }
-      };
-      for (const node of Object.values(generated.prefixTree)) {
-        visitPrefixNode(node);
-      }
-    }
-    const trie = buildRouteTrie(
-      generated.routeManifest,
-      generated._routeAncestry,
-      routeToStaticPrefix,
-      generated.routeTrailingSlash,
-      generated.prerenderRoutes
-        ? new Set(generated.prerenderRoutes)
-        : undefined,
-      generated.passthroughRoutes
-        ? new Set(generated.passthroughRoutes)
-        : undefined,
-      generated.responseTypeRoutes,
-    );
+  // Build the trie through the SAME shared helper the production discovery uses
+  // (discover-routers.ts), so the dev runtime-rebuilt trie and the prod
+  // serialized trie cannot drift. buildPerRouterTrie returns null when there
+  // are no routes.
+  const { buildPerRouterTrie } = await import("../build/route-trie.js");
+  const trie = buildPerRouterTrie(generated);
+  if (trie) {
     setRouterTrie(router.id, trie);
     // Set global trie only if not already set by another router
     if (!getRouteTrie()) {
@@ -84,6 +51,26 @@ export async function buildRouterTrieFromUrlpatterns(
     }
   }
   setRouterManifest(router.id, generated.routeManifest);
+
+  // Match the production discovery path: precompute leaf-include entries so the
+  // match-time shortcut in evaluateLazyEntry applies in dev/Cloudflare too.
+  // Without this, dev re-runs each matched leaf include's handler at match time
+  // (evaluateLazyEntry) AND again at render time (loadManifest); with it, the
+  // match-time run is skipped and the handler runs once per first request.
+  // Identical route ownership to the handler path (the shortcut is guarded by
+  // the same prefixIsShared and #506 checks production uses).
+  const { flattenLeafEntries } = await import("../build/prefix-tree-utils.js");
+  const precomputed: Array<{
+    staticPrefix: string;
+    routes: Record<string, string>;
+  }> = [];
+  flattenLeafEntries(
+    generated.prefixTree,
+    generated.routeManifest,
+    precomputed,
+  );
+  setRouterPrecomputedEntries(router.id, precomputed);
+
   // Merge into global manifest (needed for reverse/href across routers)
   const existing = hasCachedManifest() ? getGlobalRouteMap() : {};
   setCachedManifest({ ...existing, ...generated.routeManifest });

package/src/rsc/response-error.ts

@@ -1,37 +1,104 @@
 /**
- * Response Error Payload Builder
+ * Problem Details (RFC 9457) Builder
  *
- * Builds a ResponseError object from a caught error, controlling
- * what information is exposed based on error type and environment.
+ * Builds a problem+json error body from a caught error, controlling what
+ * information is exposed based on error type and environment.
  */
 
 import { RouterError } from "../errors.js";
-import type { ResponseError } from "../urls.js";
+import type { ProblemDetails } from "../urls.js";
 
 /**
- * Build a ResponseError payload from a caught error.
- * RouterError messages are always exposed (developer-crafted).
+ * HTTP reason phrases for the problem `title` member. Inlined because the
+ * router targets edge/worker runtimes without node's `http.STATUS_CODES`;
+ * covers the full standard 4xx/5xx range, with a generic fallback for any
+ * non-standard status a handler might set.
+ */
+const STATUS_PHRASES: Record<number, string> = {
+  400: "Bad Request",
+  401: "Unauthorized",
+  402: "Payment Required",
+  403: "Forbidden",
+  404: "Not Found",
+  405: "Method Not Allowed",
+  406: "Not Acceptable",
+  407: "Proxy Authentication Required",
+  408: "Request Timeout",
+  409: "Conflict",
+  410: "Gone",
+  411: "Length Required",
+  412: "Precondition Failed",
+  413: "Payload Too Large",
+  414: "URI Too Long",
+  415: "Unsupported Media Type",
+  416: "Range Not Satisfiable",
+  417: "Expectation Failed",
+  418: "I'm a Teapot",
+  421: "Misdirected Request",
+  422: "Unprocessable Entity",
+  423: "Locked",
+  424: "Failed Dependency",
+  425: "Too Early",
+  426: "Upgrade Required",
+  428: "Precondition Required",
+  429: "Too Many Requests",
+  431: "Request Header Fields Too Large",
+  451: "Unavailable For Legal Reasons",
+  500: "Internal Server Error",
+  501: "Not Implemented",
+  502: "Bad Gateway",
+  503: "Service Unavailable",
+  504: "Gateway Timeout",
+  505: "HTTP Version Not Supported",
+  506: "Variant Also Negotiates",
+  507: "Insufficient Storage",
+  508: "Loop Detected",
+  510: "Not Extended",
+  511: "Network Authentication Required",
+};
+
+function statusPhrase(status: number): string {
+  return STATUS_PHRASES[status] ?? "Error";
+}
+
+/**
+ * Build an RFC 9457 problem+json body from a caught error.
+ * RouterError messages/codes are always exposed (developer-crafted).
  * Standard Error messages are hidden in production.
+ *
+ * The `type` member is omitted in this phase: per RFC 9457 an absent `type` is
+ * treated as `"about:blank"` (no semantics beyond the HTTP status), so emitting
+ * it adds nothing. Per-route problem-type URIs arrive with the declared-errors
+ * map later. `code` is always present so consumers can branch on it
+ * (`"INTERNAL"` for non-RouterError failures).
  */
-export function createResponseErrorPayload(
+export function createProblemDetails(
   error: unknown,
+  status: number,
   isDev: boolean,
-): ResponseError {
+): ProblemDetails {
   if (error instanceof RouterError) {
     return {
-      message: error.message,
+      title: statusPhrase(status),
+      status,
+      detail: error.message,
       code: error.code,
-      ...(error.type ? { type: error.type } : {}),
       ...(isDev && error.stack ? { stack: error.stack } : {}),
     };
   }
   if (error instanceof Error) {
     return {
-      message: isDev ? error.message : "Internal Server Error",
+      title: statusPhrase(status),
+      status,
+      detail: isDev ? error.message : "Internal Server Error",
+      code: "INTERNAL",
       ...(isDev && error.stack ? { stack: error.stack } : {}),
     };
   }
   return {
-    message: isDev ? String(error) : "Internal Server Error",
+    title: statusPhrase(status),
+    status,
+    detail: isDev ? String(error) : "Internal Server Error",
+    code: "INTERNAL",
   };
 }

package/src/rsc/response-route-handler.ts

@@ -21,7 +21,7 @@ import {
 import type { MiddlewareFn } from "../router/middleware.js";
 import type { EntryData } from "../server/context.js";
 import type { HandlerContext } from "./handler-context.js";
-import { createResponseErrorPayload } from "./response-error.js";
+import { createProblemDetails } from "./response-error.js";
 import {
   createResponseWithMergedHeaders,
   finalizeResponse,
@@ -131,13 +131,10 @@ export async function handleResponseRoute<TEnv>(
 
       // Handled before the MIME lookup (json is also a RESPONSE_TYPE_MIME key).
       if (preview.responseType === "json") {
-        return createResponseWithMergedHeaders(
-          JSON.stringify({ data: result }),
-          {
-            status: 200,
-            headers: { "content-type": "application/json;charset=utf-8" },
-          },
-        );
+        return createResponseWithMergedHeaders(JSON.stringify(result), {
+          status: 200,
+          headers: { "content-type": "application/json;charset=utf-8" },
+        });
       }
 
       // Object.hasOwn (not truthiness) so prototype names like "toString" are not
@@ -157,16 +154,22 @@ export async function handleResponseRoute<TEnv>(
     } catch (error) {
       handlerCtx.callOnError(error, "handler", errorCtx);
       const isDev = process.env.NODE_ENV !== "production";
-      const status = error instanceof RouterError ? error.status : 500;
+      const derivedStatus = error instanceof RouterError ? error.status : 500;
+      // Resolve the effective status the same way createResponseWithMergedHeaders
+      // will (ctx.res.status override) so the problem body's status/title match
+      // the actual HTTP status — e.g. when a handler called ctx.setStatus()
+      // before throwing.
+      const status =
+        reqCtx.res.status !== 200 ? reqCtx.res.status : derivedStatus;
 
       if (preview.responseType === "json") {
         return createResponseWithMergedHeaders(
-          JSON.stringify({
-            error: createResponseErrorPayload(error, isDev),
-          }),
+          JSON.stringify(createProblemDetails(error, status, isDev)),
           {
             status,
-            headers: { "content-type": "application/json;charset=utf-8" },
+            headers: {
+              "content-type": "application/problem+json;charset=utf-8",
+            },
           },
         );
       }

package/src/urls/index.ts

@@ -21,8 +21,7 @@ export type {
 export type {
   ExtractRoutes,
   ExtractResponses,
-  ResponseError,
-  ResponseEnvelope,
+  ProblemDetails,
   RouteResponse,
 } from "./type-extraction.js";
 

package/src/urls/type-extraction.ts

@@ -220,44 +220,53 @@ export type ExtractResponses<T extends readonly any[]> =
   ExtractResponsesFromItems<T>;
 
 // ============================================================================
-// Response Envelope Types
+// Response Error (RFC 9457 problem+json) Type
 // ============================================================================
 
 /**
- * Error shape returned in the `{ error }` side of a JSON response envelope.
- */
-export interface ResponseError {
-  message: string;
-  code?: string;
-  type?: string;
-  stack?: string;
-}
-
-/**
- * Discriminated union envelope for JSON response routes.
- * Consumers check `result.error` to discriminate between success and failure.
+ * RFC 9457 (problem+json) error body returned by JSON response routes on a
+ * non-2xx status. Sent verbatim as the response body (not wrapped) with
+ * content-type `application/problem+json`.
  *
  * @example
  * ```typescript
- * const result: ResponseEnvelope<Product> = await fetch(url).then(r => r.json());
- * if (result.error) {
- *   console.log(result.error.message, result.error.code);
+ * const res = await fetch(url);
+ * if (!res.ok) {
+ *   const problem: ProblemDetails = await res.json();
+ *   console.log(problem.code, problem.detail); // "NOT_FOUND", "Product not found"
  *   return;
  * }
- * result.data.name // fully typed
+ * const product = await res.json(); // bare value, no envelope
  * ```
  */
-export type ResponseEnvelope<T> =
-  | { data: T; error?: undefined }
-  | { data?: undefined; error: ResponseError };
+export interface ProblemDetails {
+  /**
+   * URI reference identifying the problem type. Omitted in this phase (per RFC
+   * 9457 an absent `type` is treated as `"about:blank"` — no semantics beyond
+   * the HTTP status); per-route problem-type URIs arrive with the
+   * declared-errors map later.
+   */
+  type?: string;
+  /** Short, human-readable summary (the HTTP status reason phrase). */
+  title: string;
+  /** The HTTP status code. */
+  status: number;
+  /** Human-readable explanation specific to this occurrence (the error message). */
+  detail: string;
+  /** Stable machine-readable error code (`RouterError.code`, else `"INTERNAL"`). */
+  code: string;
+  /** Stack trace, included in development only. */
+  stack?: string;
+}
 
 // ============================================================================
 // Response Type Consumer Utilities
 // ============================================================================
 
 /**
- * Extract the response data type for a named route from a UrlPatterns instance.
- * Wraps in ResponseEnvelope since JSON response routes return enveloped data.
+ * Extract the JSON response payload type for a named route from a UrlPatterns
+ * instance. JSON response routes send the handler's return value verbatim
+ * (bare), so this resolves to the wire value a consumer receives — no envelope.
  *
  * @example
  * ```typescript
@@ -266,7 +275,7 @@ export type ResponseEnvelope<T> =
  * ]);
  *
  * type HealthData = RouteResponse<typeof apiPatterns, "health">;
- * // ResponseEnvelope<{ status: string; timestamp: number }>
+ * // { status: string; timestamp: number }
  * ```
  *
  * The payload is the JSON wire shape (via `Rango.JsonSerialize`), matching
@@ -277,6 +286,6 @@ export type RouteResponse<TPatterns, TName extends string> = TPatterns extends {
   readonly _responses?: infer R;
 }
   ? TName extends keyof R
-    ? ResponseEnvelope<JsonSerialize<Exclude<R[TName], Response>>>
+    ? JsonSerialize<Exclude<R[TName], Response>>
     : never
   : never;

package/src/vite/debug.ts

@@ -35,6 +35,7 @@ export const NS = {
   build: "rango:build",
   dev: "rango:dev",
   transform: "rango:transform",
+  chunks: "rango:chunks",
 } as const;
 
 // Back-compat: the legacy INTERNAL_RANGO_DEBUG env var enabled per-site

package/src/vite/discovery/discover-routers.ts

@@ -26,6 +26,7 @@ import {
   type CaughtDiscoveryError,
 } from "./discovery-errors.js";
 import { createRangoDebugger, timed, NS } from "../debug.js";
+import { computeProductionHash } from "../plugins/client-ref-hashing.js";
 
 const debug = createRangoDebugger(NS.discovery);
 
@@ -143,6 +144,28 @@ export async function discoverRouters(
   // Collect all manifests for trie building (avoid re-running generateManifest)
   const allManifests: Array<{ id: string; manifest: any }> = [];
 
+  // Built-in clientChunks context (present only when the built-in strategy is
+  // active). Collect the production hashes of "use client" error/notFound
+  // fallback modules so the strategy can route them into app-fallback.
+  const clientChunkCtx = state.opts?.clientChunkCtx;
+  const collectClientFallbackRef = clientChunkCtx
+    ? (refKey: string) =>
+        clientChunkCtx.fallbackRefs.add(
+          computeProductionHash(state.projectRoot, refKey),
+        )
+    : undefined;
+  // Router-level boundary defaults (`createRouter({ defaultErrorBoundary, ... })`)
+  // are NOT in EntryData, so generateManifestFull's walk misses them. Collect any
+  // "use client" default boundary directly off the router instance. The value is
+  // commonly a handler function wrapping the client boundary in server providers,
+  // so collectFallbackClientRefs invokes + walks the tree. Routed through buildMod
+  // so it runs in the same RSC runner realm the boundary value came from.
+  const collectFromBoundaryNode = (node: unknown): void => {
+    if (collectClientFallbackRef && buildMod.collectFallbackClientRefs) {
+      buildMod.collectFallbackClientRefs(node, collectClientFallbackRef);
+    }
+  };
+
   const manifestGenStart = debug ? performance.now() : 0;
   for (const [id, router] of registry) {
     if (!router.urlpatterns || !generateManifestFull) {
@@ -152,10 +175,23 @@ export async function discoverRouters(
     const manifest = generateManifestFull(
       router.urlpatterns,
       routerMountIndex,
-      router.__basename ? { urlPrefix: router.__basename } : undefined,
+      {
+        ...(router.__basename ? { urlPrefix: router.__basename } : {}),
+        ...(collectClientFallbackRef ? { collectClientFallbackRef } : {}),
+      },
     );
     routerMountIndex++;
     allManifests.push({ id, manifest });
+
+    // Router-level "use client" boundary defaults -> app-fallback (the
+    // route-tree errorBoundary()/notFoundBoundary() helpers are already
+    // collected inside generateManifestFull via collectClientFallbackRef).
+    if (collectClientFallbackRef) {
+      collectFromBoundaryNode(router.__defaultErrorBoundary);
+      collectFromBoundaryNode(router.__defaultNotFoundBoundary);
+      collectFromBoundaryNode(router.__notFound);
+    }
+
     const routeCount = Object.keys(manifest.routeManifest).length;
     const staticRoutes = Object.values(manifest.routeManifest).filter(
       (p: any) => !p.includes(":") && !p.includes("*"),
@@ -304,36 +340,17 @@ export async function discoverRouters(
         mergedResponseTypeRoutes,
       );
 
-      // Build per-router tries for multi-router isolation.
+      // Build per-router tries for multi-router isolation. Uses the single
+      // shared buildPerRouterTrie so the production serialized trie is built by
+      // exactly the same code as the dev/HMR runtime rebuild (manifest-init.ts).
+      const buildPerRouterTrie = buildMod.buildPerRouterTrie;
       for (const { id, manifest } of allManifests) {
-        if (
-          !manifest._routeAncestry ||
-          Object.keys(manifest._routeAncestry).length === 0
-        )
-          continue;
-        const perRouterStaticPrefix: Record<string, string> = {};
-        for (const name of Object.keys(manifest.routeManifest)) {
-          perRouterStaticPrefix[name] = "";
+        const perRouterTrie = buildPerRouterTrie
+          ? buildPerRouterTrie(manifest)
+          : null;
+        if (perRouterTrie) {
+          newPerRouterTrieMap.set(id, perRouterTrie);
         }
-        buildRouteToStaticPrefix(manifest.prefixTree, perRouterStaticPrefix);
-
-        const perRouterPrerenderNames = manifest.prerenderRoutes
-          ? new Set<string>(manifest.prerenderRoutes)
-          : undefined;
-        const perRouterPassthroughNames = manifest.passthroughRoutes
-          ? new Set<string>(manifest.passthroughRoutes)
-          : undefined;
-
-        const perRouterTrie = buildRouteTrie(
-          manifest.routeManifest,
-          manifest._routeAncestry,
-          perRouterStaticPrefix,
-          manifest.routeTrailingSlash,
-          perRouterPrerenderNames,
-          perRouterPassthroughNames,
-          manifest.responseTypeRoutes,
-        );
-        newPerRouterTrieMap.set(id, perRouterTrie);
       }
     }
   }

package/src/vite/discovery/state.ts

@@ -20,6 +20,13 @@ export interface PluginOptions {
   buildEnv?: import("../plugin-types.js").BuildEnvOption;
   /** Deployment preset (needed for buildEnv "auto" resolution). */
   preset?: "node" | "cloudflare";
+  /**
+   * Shared context the built-in clientChunks strategy reads. Discovery populates
+   * it (registered fallback hashes + single-router name) before the client build
+   * invokes the strategy. Present only when the built-in strategy is active
+   * (`clientChunks: true`/default); undefined for `false` or a custom function.
+   */
+  clientChunkCtx?: import("../utils/client-chunks.js").ClientChunkContext;
 }
 
 export interface PrecomputedEntry {

package/src/vite/index.ts

@@ -13,6 +13,8 @@ export type {
   RangoNodeOptions,
   RangoCloudflareOptions,
   RangoOptions,
+  ClientChunks,
+  ClientChunkMeta,
   BuildEnvOption,
   BuildEnvFactory,
   BuildEnvFactoryContext,

package/src/vite/plugin-types.ts

@@ -47,6 +47,64 @@ export type BuildEnvOption =
   | Record<string, unknown>
   | BuildEnvFactory;
 
+// -- Client chunking --------------------------------------------------------
+
+/**
+ * Metadata for one client ("use client") module, passed to a {@link ClientChunks}
+ * function. Mirrors the shape `@vitejs/plugin-rsc` passes to its own
+ * `clientChunks` option.
+ */
+export interface ClientChunkMeta {
+  /** Absolute module id of the "use client" file. */
+  id: string;
+  /** Normalized (posix) module id — convenient for path-based matching. */
+  normalizedId: string;
+  /**
+   * The RSC/server chunk that statically imports this client reference. This is
+   * the key used for the default grouping when no override is supplied: a single
+   * router that statically imports every route yields ONE `serverChunk`, hence
+   * one client chunk for all routes.
+   */
+  serverChunk: string;
+}
+
+/**
+ * Controls how client ("use client") components are grouped into browser
+ * chunks, i.e. per-route / per-feature code splitting of the client bundle.
+ *
+ * Without splitting, a single router ships ONE client chunk containing every
+ * route's client components (and their CSS) — navigating to one route downloads
+ * every other route's client code. (Host sub-apps loaded via a dynamic `import()`
+ * are the exception: each forms its own chunk.) This option controls how that
+ * monolith is split.
+ *
+ * Behavior branches:
+ * - `true` / omitted (**default**, pre-1.0): Rango's built-in **directory
+ *   strategy**. It splits app `"use client"` modules by **route id** — the segment
+ *   after a route-root directory (`routes`, `app`, `pages`, `features`, `handlers`,
+ *   …) — so `routes/dashboard/**` becomes `app-dashboard` at any nesting depth.
+ *   Where it finds NO route structure (a flat `src/components/`, or host sub-apps
+ *   already split by a dynamic `import()`), it inherits the default grouping
+ *   unchanged — so the shared `src/components` chunk stays shared and host apps do
+ *   not leak across each other. Shared runtime (React, the router, `node_modules`)
+ *   is never split.
+ * - `false`: opt out — inherit `@vitejs/plugin-rsc`'s default grouping everywhere
+ *   (one chunk per router / per host sub-app).
+ * - function: full override. Return a chunk group name, or `undefined` to fall
+ *   back to the default grouping for that one module. Forwarded directly to
+ *   `@vitejs/plugin-rsc`'s `clientChunks`.
+ *
+ * Every module maps to exactly one group, so there is no byte duplication: a
+ * component used by two routes lives in one group and is fetched whenever it
+ * renders. Put genuinely shared client components OUTSIDE route directories so
+ * they land in the shared group rather than one route's chunk.
+ *
+ * @default true
+ */
+export type ClientChunks =
+  | boolean
+  | ((meta: ClientChunkMeta) => string | undefined);
+
 // -- Plugin options ---------------------------------------------------------
 
 /**
@@ -59,6 +117,15 @@ interface RangoBaseOptions {
    */
   banner?: boolean;
 
+  /**
+   * Group client ("use client") components into browser chunks for per-route /
+   * per-feature code splitting. On by default (pre-1.0); pass `false` to opt out.
+   * See {@link ClientChunks}.
+   *
+   * @default true
+   */
+  clientChunks?: ClientChunks;
+
   /**
    * Environment bindings available to Prerender and Static handlers at build
    * time via `ctx.env`. Applies to both production build and dev on-demand