@rangojs/router 0.0.0-experimental.2 → 0.0.0-experimental.21

package/dist/server/context.d.ts

@@ -0,0 +1,245 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { ReactNode } from "react";
+import type { PartialCacheOptions, ErrorBoundaryHandler, Handler, LoaderDefinition, MiddlewareFn, NotFoundBoundaryHandler, ShouldRevalidateFn } from "../types";
+/**
+ * Performance metric entry for a single measured operation
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export interface PerformanceMetric {
+    label: string;
+    duration: number;
+    startTime: number;
+}
+/**
+ * Request-scoped metrics store
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export interface MetricsStore {
+    enabled: boolean;
+    requestStart: number;
+    metrics: PerformanceMetric[];
+}
+/**
+ * Cache configuration for an entry
+ * When set, this entry and its children will use this cache config
+ * unless overridden by a nested cache() call.
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export type EntryCacheConfig = {
+    /** Cache options (false means caching disabled for this entry) - ttl is optional, uses defaults */
+    options: PartialCacheOptions | false;
+};
+/**
+ * Entry data structure for manifest
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export type EntryPropCommon = {
+    id: string;
+    shortCode: string;
+    parent: EntryData | null;
+    /** Cache configuration for this entry (set by cache() DSL) */
+    cache?: EntryCacheConfig;
+    /** URL prefix from include() scope, used for MountContext on client */
+    mountPath?: string;
+};
+/**
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export type EntryPropDatas = {
+    middleware: MiddlewareFn<any, any>[];
+    revalidate: ShouldRevalidateFn<any, any>[];
+    errorBoundary: (ReactNode | ErrorBoundaryHandler)[];
+    notFoundBoundary: (ReactNode | NotFoundBoundaryHandler)[];
+};
+/**
+ * Loader entry stored in EntryData
+ * Contains the loader definition and its revalidation rules
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export type LoaderEntry = {
+    loader: LoaderDefinition<any>;
+    revalidate: ShouldRevalidateFn<any, any>[];
+    /** Cache config for this specific loader (loaders are NOT cached by default) */
+    cache?: EntryCacheConfig;
+};
+/**
+ * Segments state for intercept context
+ * Matches the structure from useSegments() for consistency
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export type InterceptSegmentsState = {
+    /** URL path segments (e.g., /shop/products/123 → ["shop", "products", "123"]) */
+    path: readonly string[];
+    /** Matched segment IDs in order (layouts and routes only, e.g., ["L0", "L0L1", "L0L1R0"]) */
+    ids: readonly string[];
+};
+/**
+ * Context passed to intercept selector functions (when())
+ * Contains navigation context to determine if interception should occur.
+ *
+ * Note: when() is evaluated during route matching, BEFORE middleware runs.
+ * So ctx.get()/ctx.use() are not available, but env (platform bindings) is.
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export type InterceptSelectorContext<TEnv = any> = {
+    from: URL;
+    to: URL;
+    params: Record<string, string>;
+    request: Request;
+    env: TEnv;
+    segments: InterceptSegmentsState;
+};
+/**
+ * Selector function for conditional interception
+ * Returns true to intercept, false to skip and fall through to route handler
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export type InterceptWhenFn<TEnv = any> = (ctx: InterceptSelectorContext<TEnv>) => boolean;
+/**
+ * Intercept entry stored in EntryData
+ * Contains the slot name, route to intercept, and handler
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export type InterceptEntry = {
+    slotName: `@${string}`;
+    routeName: string;
+    handler: ReactNode | Handler<any, any, any>;
+    middleware: MiddlewareFn<any, any>[];
+    revalidate: ShouldRevalidateFn<any, any>[];
+    errorBoundary: (ReactNode | ErrorBoundaryHandler)[];
+    notFoundBoundary: (ReactNode | NotFoundBoundaryHandler)[];
+    loader: LoaderEntry[];
+    loading?: ReactNode | false;
+    layout?: ReactNode | Handler<any, any, any>;
+    when: InterceptWhenFn[];
+};
+export type EntryPropSegments = {
+    loader: LoaderEntry[];
+    layout: EntryData[];
+    parallel: EntryData[];
+    intercept: InterceptEntry[];
+};
+export type EntryData = ({
+    type: "route";
+    handler: Handler<any, any, any>;
+    loading?: ReactNode | false;
+    /** URL pattern for this route (used by path() in urls()) */
+    pattern?: string;
+    /** Set when handler is a Prerender definition */
+    isPrerender?: true;
+    /** Original PrerenderHandlerDefinition (for build-time getParams access) */
+    prerenderDef?: {
+        getParams?: () => Promise<any[]> | any[];
+        options?: {
+            passthrough?: boolean;
+        };
+    };
+    /** Set when handler is a Static definition (build-time only) */
+    isStaticPrerender?: true;
+    /** Response type for non-RSC routes (json, text, image, any) */
+    responseType?: string;
+} & EntryPropCommon & EntryPropDatas & EntryPropSegments) | ({
+    type: "layout";
+    handler: ReactNode | Handler<any, any, any>;
+    loading?: ReactNode | false;
+    /** Set when handler is a Static definition (build-time only) */
+    isStaticPrerender?: true;
+} & EntryPropCommon & EntryPropDatas & EntryPropSegments) | ({
+    type: "parallel";
+    handler: Record<`@${string}`, Handler<any, any, any> | ReactNode>;
+    loading?: ReactNode | false;
+    /** Set when any parallel slot is a Static definition */
+    isStaticPrerender?: true;
+} & EntryPropCommon & EntryPropDatas & EntryPropSegments) | ({
+    type: "cache";
+    /** Cache entries create cache boundaries and render like layouts (with Outlet) */
+    handler: ReactNode | Handler<any, any, any>;
+    loading?: ReactNode | false;
+} & EntryPropCommon & EntryPropDatas & EntryPropSegments);
+/**
+ * Tracked include info for build-time manifest generation
+ */
+export interface TrackedInclude {
+    prefix: string;
+    fullPrefix: string;
+    namePrefix?: string;
+    patterns: unknown;
+    lazy: boolean;
+}
+/**
+ * Context stored in AsyncLocalStorage
+ */
+interface HelperContext {
+    manifest: Map<string, EntryData>;
+    namespace: string;
+    parent: EntryData | null;
+    counters: Record<string, number>;
+    forRoute?: string;
+    mountIndex?: number;
+    metrics?: MetricsStore;
+    /** True when rendering for SSR (document requests) */
+    isSSR?: boolean;
+    /** URL patterns map for path() routes (route name -> pattern) */
+    patterns?: Map<string, string>;
+    /** URL patterns grouped by include prefix for separate entry creation */
+    patternsByPrefix?: Map<string, Map<string, string>>;
+    /** Trailing slash config per route name */
+    trailingSlash?: Map<string, "never" | "always" | "ignore">;
+    /** Search param schemas per route name */
+    searchSchemas?: Map<string, Record<string, string>>;
+    /** URL prefix from include() - applied to all path() patterns */
+    urlPrefix?: string;
+    /** Name prefix from include() - applied to all named routes */
+    namePrefix?: string;
+    /** Run helper for cleaner middleware code */
+    run?: <T>(fn: () => T | Promise<T>) => T | Promise<T>;
+    /** Tracked includes for build-time manifest generation */
+    trackedIncludes?: TrackedInclude[];
+}
+export declare const RSCRouterContext: AsyncLocalStorage<HelperContext>;
+export declare const getContext: () => {
+    context: AsyncLocalStorage<HelperContext>;
+    getStore: () => HelperContext;
+    getParent: () => EntryData | null;
+    getOrCreateStore: (forRoute?: string) => HelperContext;
+    getNextIndex: (type: (string & {}) | "layout" | "parallel" | "middleware" | "revalidate") => string;
+    getShortCode: (type: "layout" | "parallel" | "route" | "loader" | "cache") => string;
+    run: <T>(namespace: string, parent: EntryData | null, callback: (...args: any[]) => T) => T;
+    runWithStore: <T>(store: HelperContext, namespace: string, parent: EntryData | null, callback: (...args: any[]) => T) => T;
+};
+/**
+ * Run a callback with specific URL and name prefixes
+ * Used by include() to apply prefixes to nested patterns
+ */
+export declare function runWithPrefixes<T>(urlPrefix: string, namePrefix: string | undefined, callback: () => T): T;
+/**
+ * Get current URL prefix from context
+ */
+export declare function getUrlPrefix(): string;
+/**
+ * Get current name prefix from context
+ */
+export declare function getNamePrefix(): string | undefined;
+export type { HelperContext };
+/**
+ * Track performance of a code block (no-op if metrics not enabled)
+ * Returns a done() callback to mark completion and record duration
+ *
+ * @example
+ * ```typescript
+ * const done = track("route-matching");
+ * // ... do work ...
+ * done(); // Records duration
+ * ```
+ */
+export declare function track(label: string): () => void;
+//# sourceMappingURL=context.d.ts.map

package/dist/server/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/server/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAOhK;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,iBAAiB,EAAE,CAAC;CAC9B;AAKD;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,mGAAmG;IACnG,OAAO,EAAE,mBAAmB,GAAG,KAAK,CAAC;CACtC,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC;IACzB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,UAAU,EAAE,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC;IACrC,UAAU,EAAE,kBAAkB,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC;IAC3C,aAAa,EAAE,CAAC,SAAS,GAAG,oBAAoB,CAAC,EAAE,CAAC;IACpD,gBAAgB,EAAE,CAAC,SAAS,GAAG,uBAAuB,CAAC,EAAE,CAAC;CAC3D,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,gBAAgB,CAAC,GAAG,CAAC,CAAC;IAC9B,UAAU,EAAE,kBAAkB,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC;IAC3C,gFAAgF;IAChF,KAAK,CAAC,EAAE,gBAAgB,CAAC;CAC1B,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,iFAAiF;IACjF,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,6FAA6F;IAC7F,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;CACxB,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,wBAAwB,CAAC,IAAI,GAAG,GAAG,IAAI;IACjD,IAAI,EAAE,GAAG,CAAC;IACV,EAAE,EAAE,GAAG,CAAC;IACR,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,EAAE,IAAI,CAAC;IACV,QAAQ,EAAE,sBAAsB,CAAC;CAClC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,eAAe,CAAC,IAAI,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,wBAAwB,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC;AAE3F;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,EAAE,IAAI,MAAM,EAAE,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IAC5C,UAAU,EAAE,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC;IACrC,UAAU,EAAE,kBAAkB,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC;IAC3C,aAAa,EAAE,CAAC,SAAS,GAAG,oBAAoB,CAAC,EAAE,CAAC;IACpD,gBAAgB,EAAE,CAAC,SAAS,GAAG,uBAAuB,CAAC,EAAE,CAAC;IAC1D,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,OAAO,CAAC,EAAE,SAAS,GAAG,KAAK,CAAC;IAC5B,MAAM,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IAC5C,IAAI,EAAE,eAAe,EAAE,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,QAAQ,EAAE,SAAS,EAAE,CAAC;IACtB,SAAS,EAAE,cAAc,EAAE,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,SAAS,GACjB,CAAC;IACC,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IAChC,OAAO,CAAC,EAAE,SAAS,GAAG,KAAK,CAAC;IAC5B,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,WAAW,CAAC,EAAE,IAAI,CAAC;IACnB,4EAA4E;IAC5E,YAAY,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,GAAG,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC;QAAC,OAAO,CAAC,EAAE;YAAE,WAAW,CAAC,EAAE,OAAO,CAAA;SAAE,CAAA;KAAE,CAAC;IACjG,gEAAgE;IAChE,iBAAiB,CAAC,EAAE,IAAI,CAAC;IACzB,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,eAAe,GACjB,cAAc,GACd,iBAAiB,CAAC,GACpB,CAAC;IACC,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IAC5C,OAAO,CAAC,EAAE,SAAS,GAAG,KAAK,CAAC;IAC5B,gEAAgE;IAChE,iBAAiB,CAAC,EAAE,IAAI,CAAC;CAC1B,GAAG,eAAe,GACjB,cAAc,GACd,iBAAiB,CAAC,GACpB,CAAC;IACC,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC,IAAI,MAAM,EAAE,EAAE,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC;IAClE,OAAO,CAAC,EAAE,SAAS,GAAG,KAAK,CAAC;IAC5B,wDAAwD;IACxD,iBAAiB,CAAC,EAAE,IAAI,CAAC;CAC1B,GAAG,eAAe,GACjB,cAAc,GACd,iBAAiB,CAAC,GACpB,CAAC;IACC,IAAI,EAAE,OAAO,CAAC;IACd,kFAAkF;IAClF,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IAC5C,OAAO,CAAC,EAAE,SAAS,GAAG,KAAK,CAAC;CAC7B,GAAG,eAAe,GACjB,cAAc,GACd,iBAAiB,CAAC,CAAC;AAEzB;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;GAEG;AACH,UAAU,aAAa;IACrB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,sDAAsD;IACtD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,2CAA2C;IAC3C,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC,CAAC;IAC3D,0CAA0C;IAC1C,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACtD,0DAA0D;IAC1D,eAAe,CAAC,EAAE,cAAc,EAAE,CAAC;CACpC;AAOD,eAAO,MAAM,gBAAgB,EAAE,iBAAiB,CAAC,aAAa,CAEpB,CAAC;AAE3C,eAAO,MAAM,UAAU,QAAO;IAC5B,OAAO,EAAE,iBAAiB,CAAC,aAAa,CAAC,CAAC;IAC1C,QAAQ,EAAE,MAAM,aAAa,CAAC;IAC9B,SAAS,EAAE,MAAM,SAAS,GAAG,IAAI,CAAC;IAClC,gBAAgB,EAAE,CAAC,QAAQ,CAAC,EAAE,MAAM,KAAK,aAAa,CAAC;IACvD,YAAY,EAAE,CACZ,IAAI,EAAE,CAAC,MAAM,GAAG,EAAE,CAAC,GAAG,QAAQ,GAAG,UAAU,GAAG,YAAY,GAAG,YAAY,KACtE,MAAM,CAAC;IACZ,YAAY,EAAE,CACZ,IAAI,EAAE,QAAQ,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,KACvD,MAAM,CAAC;IACZ,GAAG,EAAE,CAAC,CAAC,EACL,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,SAAS,GAAG,IAAI,EACxB,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,KAC5B,CAAC,CAAC;IACP,YAAY,EAAE,CAAC,CAAC,EACd,KAAK,EAAE,aAAa,EACpB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,SAAS,GAAG,IAAI,EACxB,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,KAC5B,CAAC,CAAC;CAqIR,CAAC;AAEF;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,QAAQ,EAAE,MAAM,CAAC,GAChB,CAAC,CA+BH;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAGrC;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,GAAG,SAAS,CAGlD;AAGD,YAAY,EAAE,aAAa,EAAE,CAAC;AAM9B;;;;;;;;;;GAUG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,IAAI,CAc/C"}

package/dist/server/context.js

@@ -0,0 +1,197 @@
+var _a;
+import { AsyncLocalStorage } from "node:async_hooks";
+import { invariant } from "../errors";
+// Use a global symbol key so the AsyncLocalStorage instance survives HMR
+// module re-evaluation. Without this, Vite's RSC module runner may create
+// a new instance when context.ts is re-evaluated, while other modules still
+// hold references to the old instance — causing getStore() to return
+// undefined even inside a run() callback.
+const RSC_CONTEXT_KEY = Symbol.for("rangojs-router:rsc-context");
+export const RSCRouterContext = (_a = globalThis)[RSC_CONTEXT_KEY] ?? (_a[RSC_CONTEXT_KEY] = new AsyncLocalStorage());
+export const getContext = () => {
+    const context = RSCRouterContext;
+    return {
+        context,
+        getOrCreateStore: (forRoute) => {
+            let store = RSCRouterContext.getStore();
+            if (!store) {
+                store = {
+                    manifest: new Map(),
+                    namespace: "",
+                    parent: null,
+                    forRoute,
+                    counters: {},
+                    patterns: new Map(),
+                    patternsByPrefix: new Map(),
+                    trailingSlash: new Map(),
+                    searchSchemas: new Map(),
+                };
+            }
+            return store;
+        },
+        getStore: () => {
+            const store = context.getStore();
+            if (!store) {
+                throw new Error("RSC Router context store is not available. Make sure to run within RSC Router context.");
+            }
+            return store;
+        },
+        getParent: () => {
+            const store = context.getStore();
+            if (!store) {
+                return null;
+            }
+            return store.parent;
+        },
+        getNextIndex: (type) => {
+            var _a;
+            const store = context.getStore();
+            invariant(store, "No context RSCRouterContext available");
+            (_a = store.counters)[type] ?? (_a[type] = 0);
+            const index = store.counters[type];
+            store.counters[type] = index + 1;
+            return `$${type}.${index}`;
+        },
+        getShortCode: (type) => {
+            var _a, _b;
+            const store = context.getStore();
+            invariant(store, "No context RSCRouterContext available");
+            const parent = store.parent;
+            const prefix = type === "layout" ? "L" : type === "parallel" ? "P" : type === "loader" ? "D" : type === "cache" ? "C" : "R";
+            const mountPrefix = store.mountIndex !== undefined ? `M${store.mountIndex}` : "";
+            if (!parent) {
+                // Root entry: prefix with mount index and use mount-scoped counter
+                const counterKey = mountPrefix ? `${mountPrefix}_root_${type}` : `root_${type}`;
+                (_a = store.counters)[counterKey] ?? (_a[counterKey] = 0);
+                const index = store.counters[counterKey];
+                store.counters[counterKey] = index + 1;
+                return `${mountPrefix}${prefix}${index}`;
+            }
+            else {
+                // Child entry: use parent-scoped counter (parent already has M prefix)
+                const counterKey = `${parent.shortCode}_${type}`;
+                (_b = store.counters)[counterKey] ?? (_b[counterKey] = 0);
+                const index = store.counters[counterKey];
+                store.counters[counterKey] = index + 1;
+                return `${parent.shortCode}${prefix}${index}`;
+            }
+        },
+        runWithStore: (store, namespace, parent, callback) => {
+            return context.run({
+                manifest: store.manifest,
+                namespace,
+                parent: parent || null,
+                counters: store.counters,
+                forRoute: store.forRoute,
+                mountIndex: store.mountIndex,
+                metrics: store.metrics,
+                isSSR: store.isSSR,
+                patterns: store.patterns,
+                trailingSlash: store.trailingSlash,
+                searchSchemas: store.searchSchemas,
+                urlPrefix: store.urlPrefix,
+                namePrefix: store.namePrefix,
+                trackedIncludes: store.trackedIncludes,
+            }, callback);
+        },
+        run: (namespace, parent, callback) => {
+            const store = context.getStore();
+            // Preserve parent counters to ensure globally unique shortCodes
+            const counters = store?.counters || {};
+            const manifest = store ? store.manifest : new Map();
+            const patterns = store?.patterns || new Map();
+            const trailingSlash = store?.trailingSlash || new Map();
+            const searchSchemas = store?.searchSchemas || new Map();
+            return context.run({
+                manifest,
+                namespace,
+                parent: parent || null,
+                counters,
+                forRoute: store?.forRoute,
+                mountIndex: store?.mountIndex,
+                metrics: store?.metrics,
+                isSSR: store?.isSSR,
+                patterns,
+                trailingSlash,
+                searchSchemas,
+                urlPrefix: store?.urlPrefix,
+                namePrefix: store?.namePrefix,
+                trackedIncludes: store?.trackedIncludes,
+            }, callback);
+        },
+    };
+};
+/**
+ * Run a callback with specific URL and name prefixes
+ * Used by include() to apply prefixes to nested patterns
+ */
+export function runWithPrefixes(urlPrefix, namePrefix, callback) {
+    const store = RSCRouterContext.getStore();
+    if (!store) {
+        throw new Error("runWithPrefixes must be called within router context");
+    }
+    // Combine prefixes if there are existing ones, avoiding double slashes
+    let combinedUrlPrefix;
+    if (store.urlPrefix) {
+        if (store.urlPrefix.endsWith("/") && urlPrefix.startsWith("/")) {
+            combinedUrlPrefix = store.urlPrefix + urlPrefix.slice(1);
+        }
+        else {
+            combinedUrlPrefix = store.urlPrefix + urlPrefix;
+        }
+    }
+    else {
+        combinedUrlPrefix = urlPrefix;
+    }
+    const combinedNamePrefix = namePrefix
+        ? store.namePrefix
+            ? `${store.namePrefix}.${namePrefix}`
+            : namePrefix
+        : store.namePrefix;
+    return RSCRouterContext.run({
+        ...store,
+        urlPrefix: combinedUrlPrefix,
+        namePrefix: combinedNamePrefix,
+    }, callback);
+}
+/**
+ * Get current URL prefix from context
+ */
+export function getUrlPrefix() {
+    const store = RSCRouterContext.getStore();
+    return store?.urlPrefix || "";
+}
+/**
+ * Get current name prefix from context
+ */
+export function getNamePrefix() {
+    const store = RSCRouterContext.getStore();
+    return store?.namePrefix;
+}
+// ============================================================================
+//  Performance Metrics Helpers
+// ============================================================================
+/**
+ * Track performance of a code block (no-op if metrics not enabled)
+ * Returns a done() callback to mark completion and record duration
+ *
+ * @example
+ * ```typescript
+ * const done = track("route-matching");
+ * // ... do work ...
+ * done(); // Records duration
+ * ```
+ */
+export function track(label) {
+    const store = RSCRouterContext.getStore();
+    // No-op if context unavailable or metrics not enabled
+    if (!store?.metrics?.enabled) {
+        return () => { };
+    }
+    const startTime = performance.now() - store.metrics.requestStart;
+    return () => {
+        const duration = performance.now() - store.metrics.requestStart - startTime;
+        store.metrics.metrics.push({ label, duration, startTime });
+    };
+}
+//# sourceMappingURL=context.js.map

package/dist/server/context.js.map

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

package/dist/server/fetchable-loader-store.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Fetchable loader store - internal registry for fetchable loader functions.
+ *
+ * Extracted into its own module to avoid circular dependencies between
+ * loader.rsc.ts and request-context.ts. This module has no imports from
+ * either, so both can safely import from here.
+ *
+ * Populated by createLoader() in loader.rsc.ts.
+ * Read by request-context.ts (for ctx.use()) and loader-registry.ts (for GET-based fetching).
+ */
+import type { LoaderFn } from "../types.js";
+import type { MiddlewareFn } from "../router/middleware.js";
+export declare function registerFetchableLoader(id: string, fn: LoaderFn<any, any, any>, middleware: MiddlewareFn[]): void;
+export declare function getFetchableLoader(id: string): {
+    fn: LoaderFn<any, any, any>;
+    middleware: MiddlewareFn[];
+} | undefined;
+//# sourceMappingURL=fetchable-loader-store.d.ts.map

package/dist/server/fetchable-loader-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetchable-loader-store.d.ts","sourceRoot":"","sources":["../../src/server/fetchable-loader-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAO5D,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAC3B,UAAU,EAAE,YAAY,EAAE,GACzB,IAAI,CAEN;AAED,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,MAAM,GACT;IAAE,EAAE,EAAE,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IAAC,UAAU,EAAE,YAAY,EAAE,CAAA;CAAE,GAAG,SAAS,CAEzE"}

package/dist/server/fetchable-loader-store.js

@@ -0,0 +1,18 @@
+/**
+ * Fetchable loader store - internal registry for fetchable loader functions.
+ *
+ * Extracted into its own module to avoid circular dependencies between
+ * loader.rsc.ts and request-context.ts. This module has no imports from
+ * either, so both can safely import from here.
+ *
+ * Populated by createLoader() in loader.rsc.ts.
+ * Read by request-context.ts (for ctx.use()) and loader-registry.ts (for GET-based fetching).
+ */
+const fetchableLoaderRegistry = new Map();
+export function registerFetchableLoader(id, fn, middleware) {
+    fetchableLoaderRegistry.set(id, { fn, middleware });
+}
+export function getFetchableLoader(id) {
+    return fetchableLoaderRegistry.get(id);
+}
+//# sourceMappingURL=fetchable-loader-store.js.map

package/dist/server/fetchable-loader-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetchable-loader-store.js","sourceRoot":"","sources":["../../src/server/fetchable-loader-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,MAAM,uBAAuB,GAAG,IAAI,GAAG,EAGpC,CAAC;AAEJ,MAAM,UAAU,uBAAuB,CACrC,EAAU,EACV,EAA2B,EAC3B,UAA0B;IAE1B,uBAAuB,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,UAAU,EAAE,CAAC,CAAC;AACtD,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,EAAU;IAEV,OAAO,uBAAuB,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AACzC,CAAC"}

package/dist/server/handle-store.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Handle data structure: handleName -> segmentId -> entries[]
+ *
+ * @example
+ * ```ts
+ * {
+ *   "breadcrumbs": {
+ *     "$root.layout": [{ label: "Home", href: "/" }],
+ *     "shop.layout": [{ label: "Shop", href: "/shop" }],
+ *   }
+ * }
+ * ```
+ */
+export type HandleData = Record<string, Record<string, unknown[]>>;
+/**
+ * HandleStore tracks pending handler promises and stores handle data.
+ *
+ * Combines two responsibilities:
+ * 1. Promise tracking - know when all handlers have resolved
+ * 2. Data storage - collect handle data pushed by handlers
+ * 3. Streaming - emit handle data via async iterator on each push
+ */
+export interface HandleStore {
+    /**
+     * Track a handler promise (non-blocking).
+     * Returns the promise unchanged - just registers it for tracking.
+     */
+    track<T>(promise: Promise<T>): Promise<T>;
+    /**
+     * Promise that resolves when all tracked handlers have settled.
+     * Does not reject - uses Promise.allSettled internally.
+     */
+    readonly settled: Promise<void>;
+    /**
+     * Push handle data for a specific handle and segment.
+     * Multiple pushes to the same handle/segment accumulate in an array.
+     * Each push triggers an emission on the stream.
+     */
+    push(handleName: string, segmentId: string, data: unknown): void;
+    /**
+     * Get all collected handle data after all handlers have settled.
+     * Returns a promise that waits for `settled`, then returns the data.
+     * The data may contain unresolved promises which RSC will stream.
+     * @deprecated Use stream() for progressive updates
+     */
+    getData(): Promise<HandleData>;
+    /**
+     * Get an async iterator that yields handle data on each push.
+     * The iterator completes when all handlers have settled.
+     * Each yield contains the full accumulated state (not just the delta).
+     */
+    stream(): AsyncGenerator<HandleData, void, unknown>;
+    /**
+     * Get handle data for a specific segment (for caching).
+     * Returns data in format: { handleName: [values...] }
+     */
+    getDataForSegment(segmentId: string): Record<string, unknown[]>;
+    /**
+     * Replay cached handle data back into the store (for cache hits).
+     * Used to restore handle data when serving cached segments.
+     */
+    replaySegmentData(segmentId: string, segmentHandles: Record<string, unknown[]>): void;
+}
+/**
+ * Create a new HandleStore instance.
+ *
+ * @example
+ * ```ts
+ * const handleStore = createHandleStore();
+ *
+ * // In router - track without awaiting
+ * const component = handleStore.track(entry.handler(context));
+ *
+ * // In handler - push handle data (value, promise, or async callback result)
+ * handleStore.push("breadcrumbs", segmentId, { label: "Home", href: "/" });
+ * handleStore.push("meta", segmentId, fetchMetaAsync()); // promise
+ *
+ * // Stream handle data progressively
+ * for await (const handles of handleStore.stream()) {
+ *   console.log("Handle update:", handles);
+ * }
+ * ```
+ */
+export declare function createHandleStore(): HandleStore;
+//# sourceMappingURL=handle-store.d.ts.map

package/dist/server/handle-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle-store.d.ts","sourceRoot":"","sources":["../../src/server/handle-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;AAiBnE;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,KAAK,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAE1C;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhC;;;;OAIG;IACH,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IAEjE;;;;;OAKG;IACH,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;IAE/B;;;;OAIG;IACH,MAAM,IAAI,cAAc,CAAC,UAAU,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IAEpD;;;OAGG;IACH,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;IAEhE;;;OAGG;IACH,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC;CACvF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,IAAI,WAAW,CA0H/C"}