@ivogt/rsc-router 0.0.0-experimental.12 → 0.0.0-experimental.14

package/dist/vite/index.js

@@ -102,7 +102,7 @@ function exposeActionId() {
   let hashToFileMap;
   let rscPluginApi;
   return {
-    name: "rsc-router:expose-action-id",
+    name: "@ivogt/rsc-router:expose-action-id",
     // Run after all other plugins (including RSC plugin's transforms)
     enforce: "post",
     configResolved(resolvedConfig) {
@@ -116,7 +116,7 @@ function exposeActionId() {
       }
       if (!rscPluginApi) {
         throw new Error(
-          "[rsc-router] Could not find @vitejs/plugin-rsc. rsc-router requires the Vite RSC plugin.\nThe RSC plugin should be included automatically. If you disabled it with\nrscRouter({ rsc: false }), add rsc() before rscRouter() in your config."
+          "[rsc-router] Could not find @vitejs/plugin-rsc. @ivogt/rsc-router requires the Vite RSC plugin.\nThe RSC plugin should be included automatically. If you disabled it with\nrscRouter({ rsc: false }), add rsc() before rscRouter() in your config."
         );
       }
       if (!isBuild) return;
@@ -189,7 +189,7 @@ function hashLoaderId(filePath, exportName) {
   return `${hash.slice(0, 8)}#${exportName}`;
 }
 function hasCreateLoaderImport(code) {
-  const pattern = /import\s*\{[^}]*\bcreateLoader\b[^}]*\}\s*from\s*["']rsc-router(?:\/server)?["']/;
+  const pattern = /import\s*\{[^}]*\bcreateLoader\b[^}]*\}\s*from\s*["']@ivogt\/rsc-router(?:\/server)?["']/;
   return pattern.test(code);
 }
 function countCreateLoaderArgs(code, startPos, endPos) {
@@ -265,7 +265,7 @@ function exposeLoaderId() {
   const loaderRegistry = /* @__PURE__ */ new Map();
   const pendingLoaderScans = /* @__PURE__ */ new Map();
   return {
-    name: "rsc-router:expose-loader-id",
+    name: "@ivogt/rsc-router:expose-loader-id",
     enforce: "post",
     configResolved(resolvedConfig) {
       config = resolvedConfig;
@@ -325,7 +325,7 @@ function exposeLoaderId() {
     load(id) {
       if (id === RESOLVED_VIRTUAL_LOADER_MANIFEST) {
         if (!isBuild) {
-          return `import { setLoaderImports } from "rsc-router/server";
+          return `import { setLoaderImports } from "@ivogt/rsc-router/server";
 
 // Dev mode: empty map, loaders are resolved dynamically via path parsing
 setLoaderImports({});
@@ -338,13 +338,13 @@ setLoaderImports({});
           );
         }
         if (lazyImports.length === 0) {
-          return `import { setLoaderImports } from "rsc-router/server";
+          return `import { setLoaderImports } from "@ivogt/rsc-router/server";
 
 // No fetchable loaders discovered during build
 setLoaderImports({});
 `;
         }
-        const code = `import { setLoaderImports } from "rsc-router/server";
+        const code = `import { setLoaderImports } from "@ivogt/rsc-router/server";
 
 // Lazy import map - loaders are loaded on-demand when first requested
 setLoaderImports({
@@ -394,7 +394,7 @@ function hashHandleId(filePath, exportName) {
   return `${hash.slice(0, 8)}#${exportName}`;
 }
 function hasCreateHandleImport(code) {
-  const pattern = /import\s*\{[^}]*\bcreateHandle\b[^}]*\}\s*from\s*["']rsc-router(?:\/[^"']+)?["']/;
+  const pattern = /import\s*\{[^}]*\bcreateHandle\b[^}]*\}\s*from\s*["']@ivogt\/rsc-router(?:\/[^"']+)?["']/;
   return pattern.test(code);
 }
 function analyzeCreateHandleArgs(code, startPos, endPos) {
@@ -462,7 +462,7 @@ function exposeHandleId() {
   let config;
   let isBuild = false;
   return {
-    name: "rsc-router:expose-handle-id",
+    name: "@ivogt/rsc-router:expose-handle-id",
     enforce: "post",
     configResolved(resolvedConfig) {
       config = resolvedConfig;
@@ -497,7 +497,7 @@ function hashLocationStateKey(filePath, exportName) {
   return `${hash.slice(0, 8)}#${exportName}`;
 }
 function hasCreateLocationStateImport(code) {
-  const pattern = /import\s*\{[^}]*\bcreateLocationState\b[^}]*\}\s*from\s*["']rsc-router(?:\/[^"']+)?["']/;
+  const pattern = /import\s*\{[^}]*\bcreateLocationState\b[^}]*\}\s*from\s*["']@ivogt\/rsc-router(?:\/[^"']+)?["']/;
   return pattern.test(code);
 }
 function transformLocationStateExports(code, filePath, sourceId, isBuild = false) {
@@ -554,7 +554,7 @@ function exposeLocationStateId() {
   let config;
   let isBuild = false;
   return {
-    name: "rsc-router:expose-location-state-id",
+    name: "@ivogt/rsc-router:expose-location-state-id",
     enforce: "post",
     configResolved(resolvedConfig) {
       config = resolvedConfig;
@@ -584,11 +584,11 @@ import {
   setServerCallback,
   encodeReply,
   createTemporaryReferenceSet,
-} from "rsc-router/internal/deps/browser";
+} from "@ivogt/rsc-router/internal/deps/browser";
 import { createElement, StrictMode } from "react";
 import { hydrateRoot } from "react-dom/client";
-import { rscStream } from "rsc-router/internal/deps/html-stream-client";
-import { initBrowserApp, RSCRouter } from "rsc-router/browser";
+import { rscStream } from "@ivogt/rsc-router/internal/deps/html-stream-client";
+import { initBrowserApp, RSCRouter } from "@ivogt/rsc-router/browser";
 
 async function initializeApp() {
   const deps = {
@@ -610,10 +610,10 @@ async function initializeApp() {
 initializeApp().catch(console.error);
 `.trim();
 var VIRTUAL_ENTRY_SSR = `
-import { createFromReadableStream } from "rsc-router/internal/deps/ssr";
+import { createFromReadableStream } from "@ivogt/rsc-router/internal/deps/ssr";
 import { renderToReadableStream } from "react-dom/server.edge";
-import { injectRSCPayload } from "rsc-router/internal/deps/html-stream-server";
-import { createSSRHandler } from "rsc-router/ssr";
+import { injectRSCPayload } from "@ivogt/rsc-router/internal/deps/html-stream-server";
+import { createSSRHandler } from "@ivogt/rsc-router/ssr";
 
 export const renderHTML = createSSRHandler({
   createFromReadableStream,
@@ -632,10 +632,10 @@ import {
   loadServerAction,
   decodeAction,
   decodeFormState,
-} from "rsc-router/internal/deps/rsc";
+} from "@ivogt/rsc-router/internal/deps/rsc";
 import { router } from "${routerPath}";
-import { createRSCHandler } from "rsc-router/rsc";
-import { VERSION } from "rsc-router:version";
+import { createRSCHandler } from "@ivogt/rsc-router/rsc";
+import { VERSION } from "@ivogt/rsc-router:version";
 
 // Import loader manifest to ensure all fetchable loaders are registered at startup
 // This is critical for serverless/multi-process deployments where the loader module
@@ -662,7 +662,7 @@ var VIRTUAL_IDS = {
   browser: "virtual:rsc-router/entry.browser.js",
   ssr: "virtual:rsc-router/entry.ssr.js",
   rsc: "virtual:rsc-router/entry.rsc.js",
-  version: "rsc-router:version"
+  version: "@ivogt/rsc-router:version"
 };
 function getVirtualVersionContent(version) {
   return `export const VERSION = ${JSON.stringify(version)};`;
@@ -675,7 +675,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@ivogt/rsc-router",
-  version: "0.0.0-experimental.12",
+  version: "0.0.0-experimental.14",
   type: "module",
   description: "Type-safe RSC router with partial rendering support",
   author: "Ivo Todorov",
@@ -810,7 +810,7 @@ var package_default = {
 };
 
 // src/vite/package-resolution.ts
-var VIRTUAL_PACKAGE_NAME = "rsc-router";
+var VIRTUAL_PACKAGE_NAME = "@ivogt/rsc-router";
 function getPublishedPackageName() {
   return package_default.name;
 }
@@ -870,13 +870,13 @@ function getPackageAliases() {
 
 // src/vite/index.ts
 var versionEsbuildPlugin = {
-  name: "rsc-router-version",
+  name: "@ivogt/rsc-router-version",
   setup(build) {
     build.onResolve({ filter: /^rsc-router:version$/ }, (args) => ({
       path: args.path,
-      namespace: "rsc-router-virtual"
+      namespace: "@ivogt/rsc-router-virtual"
     }));
-    build.onLoad({ filter: /.*/, namespace: "rsc-router-virtual" }, () => ({
+    build.onLoad({ filter: /.*/, namespace: "@ivogt/rsc-router-virtual" }, () => ({
       contents: `export const VERSION = "dev";`,
       loader: "js"
     }));
@@ -898,7 +898,7 @@ function createVirtualEntriesPlugin(entries, routerPath) {
     virtualModules[VIRTUAL_IDS.rsc] = getVirtualEntryRSC(absoluteRouterPath);
   }
   return {
-    name: "rsc-router:virtual-entries",
+    name: "@ivogt/rsc-router:virtual-entries",
     enforce: "pre",
     resolveId(id) {
       if (id in virtualModules) {
@@ -936,7 +936,7 @@ function createVersionPlugin() {
   let isDev = false;
   let server = null;
   return {
-    name: "rsc-router:version",
+    name: "@ivogt/rsc-router:version",
     enforce: "pre",
     configResolved(config) {
       isDev = config.command === "serve";
@@ -984,7 +984,7 @@ function createVersionInjectorPlugin(rscEntryPath) {
   let projectRoot = "";
   let resolvedEntryPath = "";
   return {
-    name: "rsc-router:version-injector",
+    name: "@ivogt/rsc-router:version-injector",
     enforce: "pre",
     configResolved(config) {
       projectRoot = config.root;
@@ -999,7 +999,7 @@ function createVersionInjectorPlugin(rscEntryPath) {
       if (!code.includes("createRSCHandler")) {
         return null;
       }
-      if (code.includes("rsc-router:version")) {
+      if (code.includes("@ivogt/rsc-router:version")) {
         return null;
       }
       const handlerCallMatch = code.match(/createRSCHandler\s*\(\s*\{/);
@@ -1020,7 +1020,7 @@ function createVersionInjectorPlugin(rscEntryPath) {
         if (nextNewline === -1) break;
         insertIndex = nextNewline + 1;
       }
-      const versionImport = `import { VERSION } from "rsc-router:version";
+      const versionImport = `import { VERSION } from "@ivogt/rsc-router:version";
 `;
       let newCode = code.slice(0, insertIndex) + versionImport + code.slice(insertIndex);
       newCode = newCode.replace(
@@ -1048,7 +1048,7 @@ async function rscRouter(options) {
       ssr: VIRTUAL_IDS.ssr
     };
     plugins.push({
-      name: "rsc-router:cloudflare-integration",
+      name: "@ivogt/rsc-router:cloudflare-integration",
       enforce: "pre",
       config() {
         return {
@@ -1137,7 +1137,7 @@ async function rscRouter(options) {
       rscEntryPath = userEntries.rsc ?? null;
       let hasWarnedDuplicate = false;
       plugins.push({
-        name: "rsc-router:rsc-integration",
+        name: "@ivogt/rsc-router:rsc-integration",
         enforce: "pre",
         config() {
           const useVirtualClient = finalEntries.client === VIRTUAL_IDS.browser;
@@ -1231,7 +1231,7 @@ async function rscRouter(options) {
 }
 function createCjsToEsmPlugin() {
   return {
-    name: "rsc-router:cjs-to-esm",
+    name: "@ivogt/rsc-router:cjs-to-esm",
     enforce: "pre",
     transform(code, id) {
       const cleanId = id.split("?")[0];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ivogt/rsc-router",
-  "version": "0.0.0-experimental.12",
+  "version": "0.0.0-experimental.14",
   "type": "module",
   "description": "Type-safe RSC router with partial rendering support",
   "author": "Ivo Todorov",

package/src/__tests__/component-utils.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect } from "vitest";
+import { isClientComponent, assertClientComponent } from "../component-utils";
+
+describe("component-utils", () => {
+  describe("isClientComponent", () => {
+    it("should return false for regular functions", () => {
+      const ServerComponent = () => null;
+      expect(isClientComponent(ServerComponent)).toBe(false);
+    });
+
+    it("should return false for non-functions", () => {
+      expect(isClientComponent(null)).toBe(false);
+      expect(isClientComponent(undefined)).toBe(false);
+      expect(isClientComponent("string")).toBe(false);
+      expect(isClientComponent(123)).toBe(false);
+      expect(isClientComponent({})).toBe(false);
+    });
+
+    it("should return true for functions with client reference marker", () => {
+      const ClientComponent = () => null;
+      // Simulate what the bundler does for "use client" components
+      (ClientComponent as any).$$typeof = Symbol.for("react.client.reference");
+      (ClientComponent as any).$$id = "src/components/MyComponent.tsx#default";
+
+      expect(isClientComponent(ClientComponent)).toBe(true);
+    });
+
+    it("should return false for functions with wrong $$typeof symbol", () => {
+      const Component = () => null;
+      (Component as any).$$typeof = Symbol.for("react.element");
+
+      expect(isClientComponent(Component)).toBe(false);
+    });
+  });
+
+  describe("assertClientComponent", () => {
+    it("should throw for non-function values", () => {
+      expect(() => assertClientComponent(null, "document")).toThrow(
+        'document must be a client component function with "use client" directive'
+      );
+
+      expect(() => assertClientComponent({}, "document")).toThrow(
+        'document must be a client component function with "use client" directive'
+      );
+    });
+
+    it("should throw for server components (no client marker)", () => {
+      const ServerComponent = () => null;
+
+      expect(() => assertClientComponent(ServerComponent, "document")).toThrow(
+        'document must be a client component with "use client" directive'
+      );
+      expect(() => assertClientComponent(ServerComponent, "document")).toThrow(
+        "cannot be serialized in the RSC payload"
+      );
+    });
+
+    it("should not throw for client components", () => {
+      const ClientComponent = () => null;
+      (ClientComponent as any).$$typeof = Symbol.for("react.client.reference");
+      (ClientComponent as any).$$id = "src/document.tsx#default";
+
+      expect(() =>
+        assertClientComponent(ClientComponent, "document")
+      ).not.toThrow();
+    });
+
+    it("should include component name in error message", () => {
+      const ServerComponent = () => null;
+
+      expect(() => assertClientComponent(ServerComponent, "myLayout")).toThrow(
+        "myLayout must be a client component"
+      );
+    });
+  });
+});

package/src/cache/cf/cf-cache-store.ts

@@ -19,7 +19,7 @@ import type {
   CacheGetResult,
 } from "../types.js";
 import type { RequestContext } from "../../server/request-context.js";
-import { VERSION } from "rsc-router:version";
+import { VERSION } from "@ivogt/rsc-router:version";
 
 // ============================================================================
 // Constants

package/src/component-utils.ts

@@ -0,0 +1,76 @@
+/**
+ * Component utilities for RSC
+ *
+ * Helpers for working with React Server Components and client components.
+ */
+
+import type { ComponentType } from "react";
+
+/**
+ * Symbol used by React to mark client component references.
+ * When a file has "use client" directive, the bundler transforms the exports
+ * to include this symbol on $$typeof.
+ */
+const CLIENT_REFERENCE = Symbol.for("react.client.reference");
+
+/**
+ * Check if a component is a client component (has "use client" directive).
+ *
+ * Client components are marked by the bundler with:
+ * - $$typeof: Symbol.for("react.client.reference")
+ * - $$id: string (module identifier)
+ *
+ * @param component - The component to check
+ * @returns true if the component has client reference marker
+ *
+ * @example
+ * ```typescript
+ * import { MyComponent } from "./my-component"; // has "use client"
+ *
+ * if (!isClientComponent(MyComponent)) {
+ *   throw new Error("MyComponent must be a client component");
+ * }
+ * ```
+ */
+export function isClientComponent(
+  component: ComponentType<unknown> | unknown
+): boolean {
+  if (typeof component !== "function") {
+    return false;
+  }
+  const withMeta = component as { $$typeof?: symbol };
+  return withMeta.$$typeof === CLIENT_REFERENCE;
+}
+
+/**
+ * Assert that a component is a client component.
+ * Throws a descriptive error if not.
+ *
+ * @param component - The component to check
+ * @param name - Name to use in error message (e.g., "document")
+ * @throws Error if the component is not a client component
+ */
+export function assertClientComponent(
+  component: ComponentType<unknown> | unknown,
+  name: string
+): asserts component is ComponentType<unknown> {
+  if (typeof component !== "function") {
+    throw new Error(
+      `${name} must be a client component function with "use client" directive. ` +
+        `Make sure to pass the component itself, not a JSX element: ` +
+        `${name}: My${capitalize(name)} (correct) vs ${name}: <My${capitalize(name)} /> (incorrect)`
+    );
+  }
+
+  if (!isClientComponent(component)) {
+    throw new Error(
+      `${name} must be a client component with "use client" directive at the top of the file. ` +
+        `Server components cannot be used as the ${name} because their function reference ` +
+        `cannot be serialized in the RSC payload. Add "use client" to your ${name} file.`
+    );
+  }
+}
+
+function capitalize(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}

package/src/href.ts

@@ -8,19 +8,22 @@ export type SanitizePrefix<T extends string> = T extends `/${infer P}` ? P : T;
 
 /**
  * Helper type to merge multiple route definitions into a single accumulated type.
- * Use this to define your app's complete route map for type-safe router.href().
+ * Note: When using createRSCRouter, types accumulate automatically through the
+ * builder chain, so this type is typically not needed.
  *
  * @example
  * ```typescript
- * import { homeRoutes, blogRoutes, shopRoutes } from "./routes";
- *
+ * // Manual type merging (rarely needed):
  * type AppRoutes = MergeRoutes<[
  *   typeof homeRoutes,
- *   PrefixedRoutes<typeof blogRoutes, "blog">,
- *   PrefixedRoutes<typeof shopRoutes, "shop">,
+ *   PrefixRoutePatterns<typeof blogRoutes, "/blog">,
  * ]>;
  *
- * export const router = createRSCRouter<AppEnv>() as RSCRouter<AppEnv, AppRoutes>;
+ * // Preferred: Let router accumulate types automatically
+ * const router = createRSCRouter<AppEnv>()
+ *   .routes(homeRoutes).map(...)
+ *   .routes("/blog", blogRoutes).map(...);
+ * type AppRoutes = typeof router.routeMap;
  * ```
  */
 export type MergeRoutes<T extends Record<string, string>[]> = T extends [
@@ -111,9 +114,10 @@ export type HrefFunction<TRoutes extends Record<string, string>> = {
  *
  * @example
  * ```typescript
- * const href = createHref(mergedRouteMap);
- * href("shop.cart"); // "/shop/cart"
- * href("shop.products.detail", { slug: "my-product" }); // "/shop/product/my-product"
+ * // Given routes: { cart: "/shop/cart", detail: "/shop/product/:slug" }
+ * const href = createHref(routeMap);
+ * href("cart"); // "/shop/cart"
+ * href("detail", { slug: "my-product" }); // "/shop/product/my-product"
  * ```
  */
 export function createHref<TRoutes extends Record<string, string>>(

package/src/route-definition.ts

@@ -1248,6 +1248,30 @@ export function map<const T extends RouteDefinition, TEnv = DefaultEnv>(
   };
 }
 
+/**
+ * Create RouteHelpers for inline route definitions
+ * Used internally by router.map() for inline handler syntax
+ */
+export function createRouteHelpers<
+  T extends RouteDefinition,
+  TEnv,
+>(): RouteHelpers<T, TEnv> {
+  return {
+    route: createRouteHelper<T, TEnv>(),
+    layout: createLayoutHelper<TEnv>(),
+    parallel: createParallelHelper<TEnv>(),
+    intercept: createInterceptHelper<T, TEnv>(),
+    middleware: createMiddlewareHelper<TEnv>(),
+    revalidate: createRevalidateHelper<TEnv>(),
+    loader: createLoaderHelper<TEnv>(),
+    loading: createLoadingHelper(),
+    errorBoundary: createErrorBoundaryHelper<TEnv>(),
+    notFoundBoundary: createNotFoundBoundaryHelper<TEnv>(),
+    when: createWhenHelper(),
+    cache: createCacheHelper(),
+  };
+}
+
 /**
  * Create a loader definition
  *

package/src/route-map-builder.ts

@@ -23,7 +23,7 @@
  * ```
  */
 
-import type { PrefixedRoutes } from "./href.js";
+import type { PrefixRoutePatterns } from "./href.js";
 
 /**
  * Route map builder interface
@@ -37,12 +37,14 @@ export interface RouteMapBuilder<TRoutes extends Record<string, string> = {}> {
   add<T extends Record<string, string>>(routes: T): RouteMapBuilder<TRoutes & T>;
 
   /**
-   * Add routes with prefix
+   * Add routes with prefix (only URL patterns are prefixed, keys stay unchanged)
+   * @param routes - Route definitions to add
+   * @param prefix - URL prefix WITHOUT leading slash (e.g., "blog" not "/blog")
    */
   add<T extends Record<string, string>, P extends string>(
     routes: T,
     prefix: P
-  ): RouteMapBuilder<TRoutes & PrefixedRoutes<T, P>>;
+  ): RouteMapBuilder<TRoutes & PrefixRoutePatterns<T, `/${P}`>>;
 
   /**
    * The accumulated route map (for typeof extraction in module augmentation)
@@ -52,25 +54,29 @@ export interface RouteMapBuilder<TRoutes extends Record<string, string> = {}> {
 
 /**
  * Add routes to a map with optional prefix
+ * Keys stay unchanged for composability - only URL patterns get prefixed.
  *
  * @param routeMap - The map to add routes to
  * @param routes - Routes to add
- * @param prefix - Optional prefix for keys and paths
+ * @param prefix - Optional prefix for URL paths WITHOUT leading slash (keys stay unchanged)
  */
 function addRoutes(
   routeMap: Record<string, string>,
   routes: Record<string, string>,
   prefix: string = ""
 ): void {
+  // Normalize prefix: remove leading slash if accidentally provided
+  const normalizedPrefix = prefix.startsWith("/") ? prefix.slice(1) : prefix;
+
   for (const [key, pattern] of Object.entries(routes)) {
-    const prefixedKey = prefix ? `${prefix}.${key}` : key;
     const prefixedPattern =
-      prefix && pattern !== "/"
-        ? `/${prefix}${pattern}`
-        : prefix && pattern === "/"
-          ? `/${prefix}`
+      normalizedPrefix && pattern !== "/"
+        ? `/${normalizedPrefix}${pattern}`
+        : normalizedPrefix && pattern === "/"
+          ? `/${normalizedPrefix}`
           : pattern;
-    routeMap[prefixedKey] = prefixedPattern;
+    // Use original key - enables reusable route modules
+    routeMap[key] = prefixedPattern;
   }
 }
 

package/src/router/manifest.ts

@@ -5,7 +5,9 @@
  */
 
 import { invariant, RouteNotFoundError } from "../errors";
+import { createRouteHelpers } from "../route-definition";
 import { getContext, type EntryData, type MetricsStore } from "../server/context";
+import MapRootLayout from "../server/root-layout";
 import type { RouteEntry } from "../types";
 
 /**
@@ -63,19 +65,39 @@ export async function loadManifest(
       Store.namespace || namespaceWithMount,
       Store.parent,
       async () => {
-        const load = await entry.handler();
-        if (
-          load &&
-          load !== null &&
-          typeof load === "object" &&
-          "default" in load
-        ) {
-          return load.default();
-        }
-        if (typeof load === "function") {
-          return load();
+        // Create helpers - inline handlers use them, lazy handlers ignore them
+        const helpers = createRouteHelpers();
+
+        // Call handler with helpers - works for both inline and lazy
+        const result = entry.handler(helpers);
+
+        // Handle based on return type
+        if (result instanceof Promise) {
+          // Lazy: () => import(...) - returns Promise
+          const load = await result;
+          if (
+            load &&
+            load !== null &&
+            typeof load === "object" &&
+            "default" in load
+          ) {
+            // Promise<{ default: () => Array }> - e.g., dynamic import
+            // Pass helpers - functions that need them will use them,
+            // functions from route-definition's map() will ignore them
+            return load.default(helpers);
+          }
+          if (typeof load === "function") {
+            // Promise<() => Array>
+            return load(helpers);
+          }
+          // Promise<Array> - direct array from async handler
+          return load;
         }
-        return load;
+
+        // Inline: ({ route }) => [...] - returns Array directly
+        // Wrap with layout (like map() from route-definition does)
+        // Flatten nested arrays from layout/route definitions
+        return [helpers.layout(MapRootLayout, () => result)].flat(3);
       }
     );