@rangojs/router 0.0.0-experimental.0b82333f

package/dist/router/loader-resolution.js

@@ -0,0 +1,284 @@
+/**
+ * Router Loader Resolution
+ *
+ * Loader execution, memoization, and error handling utilities.
+ */
+import { track } from "../server/context";
+import { isHandle } from "../handle.js";
+import { getFetchableLoader } from "../server/fetchable-loader-store.js";
+import { getRequestContext } from "../server/request-context.js";
+import { debugLog } from "./logging.js";
+/**
+ * Wrap a loader promise with error handling for deferred client-side resolution.
+ * Catches errors and converts them to LoaderDataResult objects that include
+ * error info and pre-rendered fallback UI when an error boundary is available.
+ *
+ * @param onError - Optional callback invoked when loader errors occur.
+ *   This has a simplified signature for internal use - the caller (typically
+ *   wrapLoaderPromise in router.ts) is responsible for bridging to the full
+ *   OnErrorCallback with complete request context (request, url, env, etc.).
+ */
+export function wrapLoaderWithErrorHandling(promise, entry, segmentId, pathname, findNearestErrorBoundary, createErrorInfo, onError) {
+    // Extract loader name from segmentId (format: "M1L0D0.loaderName")
+    const loaderName = segmentId.split(".").pop() || "unknown";
+    return Promise.resolve(promise)
+        .then((data) => ({
+        __loaderResult: true,
+        ok: true,
+        data,
+    }))
+        .catch((error) => {
+        // Find nearest error boundary
+        const fallback = findNearestErrorBoundary(entry);
+        // Create error info
+        const errorInfo = createErrorInfo(error, segmentId, "loader");
+        // Invoke onError callback if provided
+        onError?.(error, {
+            segmentId,
+            loaderName,
+            handledByBoundary: !!fallback,
+        });
+        if (!fallback) {
+            // No error boundary - return error result without fallback
+            // Client will throw this error
+            return {
+                __loaderResult: true,
+                ok: false,
+                error: errorInfo,
+                fallback: null,
+            };
+        }
+        // Render fallback on server
+        let renderedFallback;
+        if (typeof fallback === "function") {
+            // ErrorBoundaryHandler - call with error info
+            const props = {
+                error: errorInfo,
+            };
+            renderedFallback = fallback(props);
+        }
+        else {
+            renderedFallback = fallback;
+        }
+        debugLog("loader", "loader error wrapped with boundary fallback", {
+            segmentId,
+            message: errorInfo.message,
+        });
+        return {
+            __loaderResult: true,
+            ok: false,
+            error: errorInfo,
+            fallback: renderedFallback,
+        };
+    });
+}
+/**
+ * Detect cycles in the loader dependency graph using DFS from a given node.
+ * Returns the cycle path (array of loader IDs forming the cycle) if one exists,
+ * or null if no cycle is found.
+ */
+function detectLoaderCycle(from, to, dependsOn) {
+    // If `to` can reach `from` via the dependency graph, adding the edge
+    // from -> to creates a cycle. We search from `to` looking for `from`.
+    const visited = new Set();
+    const path = [from, to];
+    function dfs(current) {
+        if (current === from) {
+            // Found a cycle: return the path leading back to `from`
+            return path;
+        }
+        if (visited.has(current))
+            return null;
+        visited.add(current);
+        const deps = dependsOn.get(current);
+        if (!deps)
+            return null;
+        for (const dep of deps) {
+            path.push(dep);
+            const cycle = dfs(dep);
+            if (cycle)
+                return cycle;
+            path.pop();
+        }
+        return null;
+    }
+    return dfs(to);
+}
+/**
+ * Creates a memoizing loader executor with cycle detection.
+ * Shared by setupLoaderAccess and setupLoaderAccessSilent; only the handle
+ * branch differs between the two, so only the loader logic is extracted here.
+ *
+ * Returns a useLoader(loader, callerLoaderId) function that:
+ * - Tracks dependency edges between loaders for cycle detection
+ * - Throws immediately (synchronously inside an async fn) on circular deps
+ * - Memoizes each loader's promise so it runs at most once per request
+ */
+function createLoaderExecutor(ctx, loaderPromises) {
+    // Dependency graph: loaderId -> set of loader IDs it directly depends on.
+    const dependsOn = new Map();
+    // Loaders whose promises have not yet settled.
+    // A dependency on a pending loader that closes a cycle means deadlock.
+    const pendingLoaders = new Set();
+    function useLoader(loader, callerLoaderId) {
+        // Record the dependency edge and check for cycles before running
+        if (callerLoaderId !== null) {
+            let deps = dependsOn.get(callerLoaderId);
+            if (!deps) {
+                deps = new Set();
+                dependsOn.set(callerLoaderId, deps);
+            }
+            // Only relevant when the target is still pending (would deadlock)
+            if (pendingLoaders.has(loader.$$id)) {
+                const cycle = detectLoaderCycle(callerLoaderId, loader.$$id, dependsOn);
+                if (cycle) {
+                    throw new Error(`Circular loader dependency detected: ${cycle.join(" -> ")}. ` +
+                        `Loaders cannot depend on each other in a cycle. ` +
+                        `Refactor to break the circular dependency.`);
+                }
+            }
+            deps.add(loader.$$id);
+        }
+        // Return cached promise if already started
+        if (loaderPromises.has(loader.$$id)) {
+            return loaderPromises.get(loader.$$id);
+        }
+        // Get loader function - either from loader object or fetchable registry
+        let loaderFn = loader.fn;
+        if (!loaderFn) {
+            const fetchable = getFetchableLoader(loader.$$id);
+            if (fetchable) {
+                loaderFn = fetchable.fn;
+            }
+        }
+        if (!loaderFn) {
+            throw new Error(`Loader "${loader.$$id}" has no function. This usually means the loader was defined without "use server" and the function was not included in the build.`);
+        }
+        pendingLoaders.add(loader.$$id);
+        const currentLoaderId = loader.$$id;
+        const loaderCtx = {
+            params: ctx.params,
+            request: ctx.request,
+            searchParams: ctx.searchParams,
+            pathname: ctx.pathname,
+            url: ctx.url,
+            env: ctx.env,
+            var: ctx.var,
+            get: ctx.get,
+            use: (dep) => {
+                return useLoader(dep, currentLoaderId);
+            },
+            method: "GET",
+            body: undefined,
+        };
+        const doneLoader = track(`loader:${loader.$$id}`);
+        const promise = Promise.resolve(loaderFn(loaderCtx)).finally(() => {
+            pendingLoaders.delete(loader.$$id);
+            doneLoader();
+        });
+        loaderPromises.set(loader.$$id, promise);
+        return promise;
+    }
+    return useLoader;
+}
+/**
+ * Set up the use() method on handler context to access loaders and handles.
+ *
+ * For loaders: Lazily runs loaders, memoizes results per request.
+ * For handles: Returns a push function bound to the current segment.
+ *
+ * Includes cycle detection: tracks dependency edges between loaders and
+ * throws on circular dependencies to prevent deadlocks.
+ */
+export function setupLoaderAccess(ctx, loaderPromises) {
+    const getHandleStore = () => {
+        return getRequestContext()?._handleStore;
+    };
+    const useLoader = createLoaderExecutor(ctx, loaderPromises);
+    ctx.use = ((item) => {
+        if (isHandle(item)) {
+            const handle = item;
+            const store = getHandleStore();
+            const segmentId = ctx._currentSegmentId;
+            if (!segmentId) {
+                throw new Error(`Handle "${handle.$$id}" used outside of handler context. ` +
+                    `Handles must be used within route/layout handlers.`);
+            }
+            return (dataOrFn) => {
+                if (!store)
+                    return;
+                const valueOrPromise = typeof dataOrFn === "function"
+                    ? dataOrFn()
+                    : dataOrFn;
+                store.push(handle.$$id, segmentId, valueOrPromise);
+            };
+        }
+        return useLoader(item, null);
+    });
+}
+/**
+ * Set up ctx.use() for pre-rendering (build-time).
+ * Handles push to HandleStore; loaders throw with a clear error.
+ */
+export function setupBuildUse(ctx) {
+    // Get HandleStore from request context
+    const getHandleStore = () => {
+        return getRequestContext()?._handleStore;
+    };
+    ctx.use = ((item) => {
+        // Handle case: return a push function bound to the current segment
+        if (isHandle(item)) {
+            const handle = item;
+            const store = getHandleStore();
+            const segmentId = ctx._currentSegmentId;
+            if (!segmentId) {
+                throw new Error(`Handle "${handle.$$id}" used outside of handler context. ` +
+                    `Handles must be used within route/layout handlers.`);
+            }
+            return (dataOrFn) => {
+                if (!store)
+                    return;
+                const valueOrPromise = typeof dataOrFn === "function"
+                    ? dataOrFn()
+                    : dataOrFn;
+                store.push(handle.$$id, segmentId, valueOrPromise);
+            };
+        }
+        // Loader case: not available during pre-rendering
+        throw new Error("Loaders are not available during pre-rendering. " +
+            "Use them on parent layouts with cache() for request-time data, " +
+            "or use a passthrough prerender handler.");
+    });
+}
+/**
+ * Set up ctx.use() for proactive caching (silent mode).
+ * Handles are silently ignored (no push to HandleStore).
+ * Loaders work normally but with fresh memoization and cycle detection.
+ *
+ * This prevents duplicate handle data (breadcrumbs, meta) from being
+ * pushed to the response stream during background proactive caching.
+ */
+export function setupLoaderAccessSilent(ctx, loaderPromises) {
+    const useLoader = createLoaderExecutor(ctx, loaderPromises);
+    ctx.use = ((item) => {
+        if (isHandle(item)) {
+            // Silent mode - return a no-op so handle data is not pushed during caching
+            return (_dataOrFn) => { };
+        }
+        return useLoader(item, null);
+    });
+}
+/**
+ * Conditional execution based on revalidation
+ * Evaluates revalidation logic lazily, then executes appropriate callback
+ *
+ * @param shouldRevalidate - Async function that determines if revalidation is needed
+ * @param onRevalidate - Callback executed if revalidation returns true
+ * @param onSkip - Callback executed if revalidation returns false
+ * @returns Result from either onRevalidate or onSkip
+ */
+export async function revalidate(shouldRevalidate, onRevalidate, onSkip) {
+    const needsRevalidation = await shouldRevalidate();
+    return needsRevalidation ? await onRevalidate() : onSkip();
+}
+//# sourceMappingURL=loader-resolution.js.map

package/dist/router/loader-resolution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader-resolution.js","sourceRoot":"","sources":["../../src/router/loader-resolution.ts"],"names":[],"mappings":"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"}

package/dist/router/logging.d.ts

@@ -0,0 +1,15 @@
+interface RouterLogOptions {
+    request: Request;
+    transaction: string;
+}
+interface LogDetails {
+    [key: string]: unknown;
+}
+export declare function runWithRouterLogContext<T>(options: RouterLogOptions, fn: () => T): T;
+export declare function withRouterLogScope<T>(label: string, fn: () => Promise<T>): Promise<T>;
+export declare function withRouterLogScope<T>(label: string, fn: () => T): T;
+export declare function isRouterDebugEnabled(): boolean;
+export declare function debugLog(scope: string, message: string, details?: LogDetails): void;
+export declare function debugWarn(scope: string, message: string, details?: LogDetails): void;
+export {};
+//# sourceMappingURL=logging.d.ts.map

package/dist/router/logging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.d.ts","sourceRoot":"","sources":["../../src/router/logging.ts"],"names":[],"mappings":"AASA,UAAU,gBAAgB;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,UAAU,UAAU;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAsCD,wBAAgB,uBAAuB,CAAC,CAAC,EACvC,OAAO,EAAE,gBAAgB,EACzB,EAAE,EAAE,MAAM,CAAC,GACV,CAAC,CAiBH;AAED,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AACvF,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;AA0BrE,wBAAgB,oBAAoB,IAAI,OAAO,CAE9C;AASD,wBAAgB,QAAQ,CACtB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,UAAU,GACnB,IAAI,CAUN;AAED,wBAAgB,SAAS,CACvB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,UAAU,GACnB,IAAI,CAUN"}

package/dist/router/logging.js

@@ -0,0 +1,99 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
+const routerLogContext = new AsyncLocalStorage();
+const requestIds = new WeakMap();
+let requestCounter = 0;
+let transactionCounter = 0;
+function nextId(prefix, counter) {
+    return `${prefix}${counter.toString(36)}`;
+}
+function getHeaderRequestId(request) {
+    const candidate = request.headers.get("x-rsc-router-request-id") ??
+        request.headers.get("x-request-id") ??
+        request.headers.get("cf-ray");
+    if (!candidate)
+        return null;
+    const trimmed = candidate.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function getOrCreateRequestId(request) {
+    const existing = requestIds.get(request);
+    if (existing)
+        return existing;
+    const fromHeaders = getHeaderRequestId(request);
+    if (fromHeaders) {
+        requestIds.set(request, fromHeaders);
+        return fromHeaders;
+    }
+    requestCounter += 1;
+    const generated = nextId("req-", requestCounter);
+    requestIds.set(request, generated);
+    return generated;
+}
+export function runWithRouterLogContext(options, fn) {
+    if (!INTERNAL_RANGO_DEBUG) {
+        return fn();
+    }
+    const requestId = getOrCreateRequestId(options.request);
+    transactionCounter += 1;
+    const transactionId = `${options.transaction}-${nextId("tx-", transactionCounter)}`;
+    return routerLogContext.run({
+        requestId,
+        transactionId,
+        depth: 0,
+    }, fn);
+}
+export function withRouterLogScope(label, fn) {
+    const ctx = routerLogContext.getStore();
+    if (!INTERNAL_RANGO_DEBUG || !ctx) {
+        return fn();
+    }
+    debugLog(label, "start");
+    return routerLogContext.run({ ...ctx, depth: ctx.depth + 1 }, () => {
+        try {
+            const result = fn();
+            if (result && typeof result.then === "function") {
+                return result.finally(() => {
+                    debugLog(label, "end");
+                });
+            }
+            debugLog(label, "end");
+            return result;
+        }
+        catch (error) {
+            debugLog(label, "error", { error: String(error) });
+            throw error;
+        }
+    });
+}
+export function isRouterDebugEnabled() {
+    return INTERNAL_RANGO_DEBUG && !!routerLogContext.getStore();
+}
+function formatPrefix(scope) {
+    const ctx = routerLogContext.getStore();
+    if (!ctx)
+        return `[Router][${scope}]`;
+    const indent = "  ".repeat(ctx.depth);
+    return `[Router][req:${ctx.requestId}][tx:${ctx.transactionId}] ${indent}[${scope}]`;
+}
+export function debugLog(scope, message, details) {
+    if (!isRouterDebugEnabled())
+        return;
+    const prefix = formatPrefix(scope);
+    if (details) {
+        console.log(`${prefix} ${message}`, details);
+        return;
+    }
+    console.log(`${prefix} ${message}`);
+}
+export function debugWarn(scope, message, details) {
+    if (!isRouterDebugEnabled())
+        return;
+    const prefix = formatPrefix(scope);
+    if (details) {
+        console.warn(`${prefix} ${message}`, details);
+        return;
+    }
+    console.warn(`${prefix} ${message}`);
+}
+//# sourceMappingURL=logging.js.map

package/dist/router/logging.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.js","sourceRoot":"","sources":["../../src/router/logging.ts"],"names":[],"mappings":"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"}

package/dist/router/manifest.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Router Manifest Loading
+ *
+ * Handles lazy loading and validation of route manifests.
+ */
+import { type EntryData, type MetricsStore } from "../server/context";
+import type { RouteEntry } from "../types";
+/**
+ * Load manifest from route entry with AsyncLocalStorage context
+ * Handles lazy imports, unwrapping, and validation
+ *
+ * Results are cached at module level after first execution. Subsequent calls
+ * for the same (routeKey, isSSR) within the same isolate return cached data
+ * without re-executing the DSL handler.
+ */
+/**
+ * Clear the module-level manifest cache.
+ * Called on HMR to ensure stale handler references are discarded.
+ */
+export declare function clearManifestCache(): void;
+export declare function loadManifest(entry: RouteEntry<any>, routeKey: string, path: string, metricsStore?: MetricsStore, isSSR?: boolean): Promise<EntryData>;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/router/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/router/manifest.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAA+B,KAAK,SAAS,EAAE,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEnG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAe3C;;;;;;;GAOG;AACH;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAED,wBAAsB,YAAY,CAChC,KAAK,EAAE,UAAU,CAAC,GAAG,CAAC,EACtB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,YAAY,CAAC,EAAE,YAAY,EAC3B,KAAK,CAAC,EAAE,OAAO,GACd,OAAO,CAAC,SAAS,CAAC,CA0LpB"}

package/dist/router/manifest.js

@@ -0,0 +1,181 @@
+/**
+ * Router Manifest Loading
+ *
+ * Handles lazy loading and validation of route manifests.
+ */
+import { invariant, RouteNotFoundError } from "../errors";
+import { createRouteHelpers } from "../route-definition";
+import { getContext, runWithPrefixes } from "../server/context";
+import MapRootLayout from "../server/root-layout";
+import { VERSION } from "@rangojs/router:version";
+// Module-level manifest cache: avoids re-executing DSL handler on every request.
+// Handler execution is deterministic (components, loaders, middleware are module-level
+// stable references), so the resulting EntryData tree can be safely cached and reused
+// across requests within the same isolate.
+//
+// Cache is keyed by (VERSION, mountIndex, routeKey, isSSR). VERSION comes from the
+// @rangojs/router:version virtual module which Vite invalidates on RSC module HMR.
+// When VERSION changes, this module re-evaluates and the cache is recreated empty.
+// Including VERSION in the key is additional defense against stale entries.
+const manifestModuleCache = new Map();
+/**
+ * Load manifest from route entry with AsyncLocalStorage context
+ * Handles lazy imports, unwrapping, and validation
+ *
+ * Results are cached at module level after first execution. Subsequent calls
+ * for the same (routeKey, isSSR) within the same isolate return cached data
+ * without re-executing the DSL handler.
+ */
+/**
+ * Clear the module-level manifest cache.
+ * Called on HMR to ensure stale handler references are discarded.
+ */
+export function clearManifestCache() {
+    manifestModuleCache.clear();
+}
+export async function loadManifest(entry, routeKey, path, metricsStore, isSSR) {
+    // Helper to push a metric entry
+    const pushMetric = metricsStore
+        ? (label, start) => {
+            metricsStore.metrics.push({
+                label,
+                duration: performance.now() - start,
+                startTime: start - metricsStore.requestStart,
+            });
+        }
+        : undefined;
+    const mountIndex = entry.mountIndex;
+    // Check module-level cache (persists across requests within same isolate)
+    const cacheKey = `${VERSION}:${mountIndex ?? ''}:${routeKey}:${isSSR ? 1 : 0}`;
+    const cached = manifestModuleCache.get(cacheKey);
+    if (cached) {
+        const cacheStart = performance.now();
+        // Set up Store for downstream consumers (segment resolution reads Store.manifest)
+        const Store = getContext().getOrCreateStore(routeKey);
+        Store.mountIndex = mountIndex;
+        Store.isSSR = isSSR;
+        if (metricsStore)
+            Store.metrics = metricsStore;
+        // Restore cached manifest into Store
+        for (const [k, v] of cached) {
+            Store.manifest.set(k, v);
+        }
+        pushMetric?.("manifest:cache-hit", cacheStart);
+        return cached.get(routeKey);
+    }
+    const storeSetupStart = performance.now();
+    const Store = getContext().getOrCreateStore(routeKey);
+    // Set mount index in store for unique shortCode prefixes
+    Store.mountIndex = mountIndex;
+    // Set isSSR flag so loading() can check if we're in SSR
+    Store.isSSR = isSSR;
+    // Attach metrics store to context if provided
+    if (metricsStore) {
+        Store.metrics = metricsStore;
+    }
+    pushMetric?.("manifest:store-setup", storeSetupStart);
+    // Clear manifest before rebuilding to prevent stale entry mutations
+    const clearStart = performance.now();
+    Store.manifest.clear();
+    pushMetric?.("manifest:clear", clearStart);
+    try {
+        // Include mountIndex in namespace to ensure unique cache keys per mount
+        const namespaceWithMount = mountIndex !== undefined
+            ? `#router.M${mountIndex}`
+            : "#router";
+        // For lazy entries, use the captured parent from include() context
+        // This ensures routes are registered under the correct layout hierarchy
+        const lazyContext = entry.lazy && entry.lazyPatterns ? entry.lazyContext : null;
+        const parentForContext = lazyContext?.parent ?? Store.parent;
+        // For lazy entries, merge captured counters from include() so the
+        // handler's entries get shortCode indices after sibling entries that
+        // were created during pattern extraction.  This prevents shortCode
+        // collisions between lazy and non-lazy entries under the same parent
+        // (e.g., ArticlesLayout and BlogLayout both under NavLayout).
+        if (lazyContext && lazyContext.counters) {
+            const captured = lazyContext.counters;
+            for (const [key, value] of Object.entries(captured)) {
+                Store.counters[key] = Math.max(Store.counters[key] ?? 0, value);
+            }
+        }
+        const handlerExecStart = performance.now();
+        const useItems = await getContext().runWithStore(Store, Store.namespace || namespaceWithMount, parentForContext, async () => {
+            // Create helpers for lazy-loaded handlers that need them
+            const helpers = createRouteHelpers();
+            // For lazy entries, use lazyPatterns.handler() with proper prefixes.
+            // Do NOT wrap in MapRootLayout here: the captured parent chain from
+            // pattern extraction already includes the synthetic MapRootLayout
+            // parent, so adding another would create an extra level that does
+            // not exist in the non-lazy (root handler) path and would produce
+            // mismatched shortCodes.
+            if (entry.lazy && entry.lazyPatterns) {
+                const lazyPatterns = entry.lazyPatterns;
+                const includePrefix = entry._lazyPrefix || "";
+                const fullPrefix = (lazyContext?.urlPrefix || "") + includePrefix;
+                if (fullPrefix || lazyContext?.namePrefix) {
+                    return runWithPrefixes(fullPrefix, lazyContext?.namePrefix, () => lazyPatterns.handler());
+                }
+                return lazyPatterns.handler();
+            }
+            // Wrap handler execution in root layout so routes get correct parent
+            // This ensures all routes are registered with the layout as their parent
+            let promiseResult = null;
+            const wrappedItems = helpers.layout(MapRootLayout, () => {
+                const result = entry.handler();
+                if (result instanceof Promise) {
+                    // Lazy handler detected - capture promise for async handling
+                    promiseResult = result;
+                    return []; // Return empty, we'll discard this wrapped result
+                }
+                return result;
+            });
+            // Handle lazy (Promise-based) handlers
+            if (promiseResult !== null) {
+                const load = await promiseResult;
+                if (load &&
+                    load !== null &&
+                    typeof load === "object" &&
+                    "default" in load) {
+                    // Promise<{ default: () => Array }> - e.g., dynamic import
+                    // Lazy-loaded handlers may need helpers (passed as optional arg)
+                    return load.default(helpers);
+                }
+                if (typeof load === "function") {
+                    // Promise<() => Array>
+                    return load(helpers);
+                }
+                // Promise<Array> - direct array from async handler
+                return load;
+            }
+            // Inline handler - routes were registered with correct parent inside layout
+            return [wrappedItems].flat(3);
+        });
+        pushMetric?.("manifest:handler-exec", handlerExecStart);
+        const validationStart = performance.now();
+        invariant(useItems && useItems.length > 0, "Did not receive any handler from router.map()");
+        // For non-lazy entries the root handler is wrapped in MapRootLayout,
+        // so the result always contains a layout item.  Lazy entries run the
+        // included patterns handler directly (no MapRootLayout wrapper) so
+        // we skip this check -- the layout is in the captured parent chain.
+        if (!lazyContext) {
+            invariant(useItems.some((item) => item.type === "layout"), "Top-level handler must be a layout");
+        }
+        invariant(Store.manifest.has(routeKey), `Route must be registered for ${routeKey}`);
+        pushMetric?.("manifest:validation", validationStart);
+        // Cache manifest for future requests in this isolate
+        manifestModuleCache.set(cacheKey, new Map(Store.manifest));
+        return Store.manifest.get(routeKey);
+    }
+    catch (e) {
+        throw new RouteNotFoundError(`Failed to load route handlers for ${path}: ${e.message}`, {
+            cause: {
+                error: e,
+                state: {
+                    path,
+                    routeKey,
+                },
+            },
+        });
+    }
+}
+//# sourceMappingURL=manifest.js.map

package/dist/router/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../src/router/manifest.ts"],"names":[],"mappings":"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"}