@rangojs/router 0.0.0-experimental.dfdb0387 → 0.0.0-experimental.e9c0b2f2

package/src/types/route-entry.ts

@@ -1,22 +1,27 @@
 import type { AllUseItems } from "../route-types.js";
 import type { TrailingSlashMode, ResolvedRouteMap } from "./route-config.js";
 
-/**
- * Context captured for lazy include evaluation
- */
 export interface LazyIncludeContext {
   urlPrefix: string;
   namePrefix: string | undefined;
   parent: unknown; // EntryData - avoid circular import
+  /** Counter snapshot from pattern extraction for consistent shortCode indices */
+  counters?: Record<string, number>;
   cacheProfiles?: Record<
     string,
     import("../cache/profile-registry.js").CacheProfile
   >;
+  /** Root scope flag for dot-local reverse resolution */
+  rootScoped?: boolean;
+  /**
+   * Positional include scope token composed from the parent scope plus this
+   * include's sibling index (`${parentScope}I${idx}`). Applied to direct-
+   * descendant shortCodes during lazy evaluation so routes inside the
+   * include cannot collide with siblings declared outside it.
+   */
+  includeScope?: string;
 }
 
-/**
- * Internal route entry stored in router
- */
 export interface RouteEntry<TEnv = any> {
   prefix: string;
   /**

package/src/types/segments.ts

@@ -10,7 +10,10 @@ export type ViewTransitionClass = Record<string, string> | string;
 
 /**
  * Configuration for React's <ViewTransition> component.
- * Maps directly to ViewTransitionProps (minus children/ref/callbacks).
+ *
+ * The phase fields (enter/exit/update/share/default/name) map directly to
+ * ViewTransitionProps (minus children/ref/callbacks). The `viewTransition`
+ * field is router-specific and is stripped before the config reaches React.
  */
 export interface TransitionConfig {
   enter?: ViewTransitionClass;
@@ -19,19 +22,25 @@ export interface TransitionConfig {
   share?: ViewTransitionClass;
   default?: ViewTransitionClass;
   name?: string;
+  /**
+   * Whether the router wraps this segment's content in its own
+   * <ViewTransition> boundary.
+   *
+   * - "auto" (default): the router places the boundary, producing the
+   *   router-owned cross-fade described by the phase fields above.
+   * - false: the router places no boundary. The navigation commit is still
+   *   driven through startTransition (so loaders hold instead of flashing a
+   *   skeleton, and consumer-placed <ViewTransition> elements still animate),
+   *   but the router contributes no cross-fade of its own.
+   *
+   * When unset, inherits the createRouter({ viewTransition }) default.
+   */
+  viewTransition?: "auto" | false;
 }
 
 /**
  * Resolved segment with component
  *
- * Segment types:
- * - layout: Wraps child content via <Outlet />
- * - route: The leaf content for a URL
- * - parallel: Named slots rendered via <ParallelOutlet name="@slot" />
- * - loader: Data segment (no visual rendering, carries loaderData)
- * - error: Error fallback segment (replaces failed segment with error UI)
- * - notFound: Not found fallback segment (replaces segment when data not found)
- *
  * @internal This type is an implementation detail and may change without notice.
  */
 export interface ResolvedSegment {
@@ -56,20 +65,22 @@ export interface ResolvedSegment {
   // Intercept loader fields (for streaming loader data in parallel segments)
   loaderDataPromise?: Promise<any[]> | any[]; // Loader data promise or resolved array
   loaderIds?: string[]; // IDs ($$id) of loaders for this segment
-  parallelLoaderSources?: any[]; // Internal: preserves stable aggregate promise across renders
   // Error-specific fields
   error?: ErrorInfo; // For error segments: the error information
   // NotFound-specific fields
   notFoundInfo?: NotFoundInfo; // For notFound segments: the not found information
   // Mount path from include() scope, used for MountContext.Provider wrapping
   mountPath?: string;
+  /**
+   * @internal Server-side marker: true when the segment's handler actually ran
+   * this request (not skipped via the revalidate cache path). Used by
+   * match-result.ts to populate `MatchResult.resolvedIds` for client-side
+   * handle-bucket cleanup. Stripped from the wire payload before serialization
+   * — never reaches the client.
+   */
+  _handlerRan?: boolean;
 }
 
-/**
- * Segment metadata (without component)
- *
- * @internal This type is an implementation detail and may change without notice.
- */
 export interface SegmentMetadata {
   id: string;
   type: "layout" | "route" | "parallel" | "loader" | "error" | "notFound";
@@ -117,6 +128,15 @@ export interface MatchResult {
   segments: ResolvedSegment[];
   matched: string[];
   diff: string[];
+  /**
+   * Every segment id whose handler actually ran on the server this request,
+   * including ones with `component === null` that get filtered out of
+   * `segments`/`diff` to avoid wasted bytes. Drives the client's handle-
+   * cleanup pass — a slot that re-resolves and pushes nothing must clear
+   * its previous handle bucket, but `diff` doesn't carry it because the
+   * segment payload doesn't either. A superset of `diff`.
+   */
+  resolvedIds: string[];
   /**
    * Merged route params from all matched segments
    * Available for use by the handler after route matching

package/src/urls/include-helper.ts

@@ -1,10 +1,8 @@
 import type { AllUseItems, IncludeItem } from "../route-types.js";
 import {
-  getContext,
-  runWithPrefixes,
   getUrlPrefix,
   getNamePrefix,
-  getRootScoped,
+  requireDslContext,
 } from "../server/context";
 import {
   INTERNAL_INCLUDE_SCOPE_PREFIX,
@@ -27,28 +25,10 @@ function allocateInternalIncludeScopeId(
 }
 
 /**
- * Process an IncludeItem by executing its nested patterns with prefixes
- * This expands the include into actual route registrations
- */
-function processIncludeItem(item: IncludeItem): AllUseItems[] {
-  const { prefix, patterns } = item;
-  const namePrefix =
-    (item as IncludeItem & { _lazyContext?: { namePrefix?: string } })
-      ._lazyContext?.namePrefix ?? item.options?.name;
-
-  // Execute the nested patterns' handler with URL and name prefixes
-  // The urlPrefix being set tells nested urls() to skip RootLayout wrapping
-  return runWithPrefixes(prefix, namePrefix, () => {
-    // Call the nested patterns' handler - this registers routes with prefixed patterns/names
-    return (patterns as UrlPatterns).handler();
-  });
-}
-
-/**
- * Recursively process items, expanding any IncludeItems
- * Returns items with IncludeItems expanded into actual route items
+ * Recursively walk items, recursing into layout children.
  *
- * Lazy includes are kept as-is (not expanded) for the router to handle later.
+ * All includes are lazy and kept as-is; the router expands them on the first
+ * matching request.
  */
 export function processItems(items: readonly AllUseItems[]): AllUseItems[] {
   const result: AllUseItems[] = [];
@@ -57,28 +37,8 @@ export function processItems(items: readonly AllUseItems[]): AllUseItems[] {
     if (!item) continue;
 
     if (item.type === "include") {
-      const includeItem = item as IncludeItem & {
-        _expanded?: AllUseItems[];
-        lazy?: boolean;
-      };
-
-      // Lazy includes are NOT expanded here - kept for router to handle
-      if (includeItem.lazy) {
-        result.push(item);
-        continue;
-      }
-
-      // Eager includes are already expanded during include() call
-      if (includeItem._expanded) {
-        // Items were expanded immediately - just process them recursively
-        result.push(...processItems(includeItem._expanded));
-      } else {
-        // Fallback for legacy include items without _expanded
-        const expanded = processIncludeItem(item as IncludeItem);
-        result.push(...processItems(expanded));
-      }
+      result.push(item);
     } else if (item.type === "layout" && (item as any).uses) {
-      // Process nested items in layout
       const layoutItem = item as any;
       layoutItem.uses = processItems(layoutItem.uses);
       result.push(layoutItem);
@@ -93,13 +53,9 @@ export function processItems(items: readonly AllUseItems[]): AllUseItems[] {
 /**
  * Create include() helper for composing URL patterns
  *
- * By default, include() IMMEDIATELY expands the nested patterns. This ensures
- * that routes from included patterns inherit the correct parent context
- * (the layout they're included in).
- *
- * With `lazy: true`, patterns are NOT expanded at definition time. Instead,
- * they're evaluated on first request that matches the prefix. This improves
- * cold start time for apps with many routes.
+ * All includes are lazy: the nested patterns are NOT expanded at definition
+ * time. Instead they are evaluated on the first request that matches the
+ * prefix, which improves cold start time for apps with many routes.
  */
 export function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
   return (
@@ -107,9 +63,7 @@ export function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
     patterns: UrlPatterns<TEnv>,
     options?: IncludeOptions,
   ): IncludeItem => {
-    const store = getContext();
-    const ctx = store.getStore();
-    if (!ctx) throw new Error("include() must be called inside urls()");
+    const { ctx } = requireDslContext("include() must be called inside urls()");
 
     const explicitName = options?.name;
     const hasExplicitName = hasExplicitNameOption(options);
@@ -149,22 +103,32 @@ export function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
       });
     }
 
-    // Snapshot parent's counters so lazy manifest generation starts
-    // at the correct index, preventing shortCode collisions with
-    // sibling entries (e.g., BlogLayout and ArticlesLayout under NavLayout).
-    const capturedCounters = { ...ctx.counters };
-
-    // Reserve a layout slot in the parent's counter so sibling lazy includes
-    // produce different shortCode indices for their root layout.
-    // Without this, consecutive include() calls capture identical counters
-    // and their first child layouts get the same shortCode (e.g., both M0L0L0),
-    // causing the client partial-update diff to see no changes on navigation.
+    // Allocate an include-scope token for this include() call. The token is
+    // appended to the parent's shortCode prefix whenever the include's
+    // direct-descendant shortCodes are generated (see getShortCode in
+    // context.ts), partitioning the parent's counter namespace so routes
+    // inside an include cannot collide with siblings declared outside it.
+    //
+    // Scopes compose: a nested include inside an outer include with scope
+    // "I0" allocates against the `${parent.shortCode}I0_include` counter
+    // and produces scope "I0I0", "I0I1", etc.
+    const parentScope = ctx.includeScope ?? "";
+    let includeScope = parentScope;
     if (capturedParent?.shortCode) {
-      const layoutCounterKey = `${capturedParent.shortCode}_layout`;
-      ctx.counters[layoutCounterKey] ??= 0;
-      ctx.counters[layoutCounterKey]++;
+      const includeCounterKey = `${capturedParent.shortCode}${parentScope}_include`;
+      ctx.counters[includeCounterKey] ??= 0;
+      const includeIdx = ctx.counters[includeCounterKey];
+      ctx.counters[includeCounterKey] = includeIdx + 1;
+      includeScope = `${parentScope}I${includeIdx}`;
     }
 
+    // Snapshot parent's counters AFTER allocating the include scope so lazy
+    // manifest generation starts with the same counter state this include
+    // observed — its descendants still get fresh per-scope counters because
+    // they key off `${parent.shortCode}${includeScope}_*` (not shared with
+    // siblings outside the include).
+    const capturedCounters = { ...ctx.counters };
+
     // Compute rootScoped at capture time, mirroring the logic in runWithPrefixes.
     // This ensures lazy evaluation restores the correct scope state.
     const parentRootScoped = ctx.rootScoped;
@@ -175,8 +139,6 @@ export function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
           ? (parentRootScoped ?? false)
           : parentRootScoped;
 
-    // All includes are lazy - patterns are evaluated on first matching request
-    // This improves cold start time significantly for large route sets
     return {
       type: "include",
       name,
@@ -191,6 +153,7 @@ export function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
         counters: capturedCounters,
         cacheProfiles: ctx.cacheProfiles,
         rootScoped: capturedRootScoped,
+        includeScope,
       },
     } as IncludeItem;
   };

package/src/urls/index.ts

@@ -1,4 +1,3 @@
-// Response types and symbols
 export {
   RESPONSE_TYPE,
   type ResponseHandler,
@@ -8,28 +7,21 @@ export {
   type ResponseHandlerContext,
 } from "./response-types.js";
 
-// Pattern types
 export type {
   UnnamedRoute,
   LocalOnlyInclude,
   PathOptions,
-  PathDefinition,
   UrlPatterns,
   IncludeOptions,
 } from "./pattern-types.js";
 
-// Type extraction utilities
 export type {
   ExtractRoutes,
   ExtractResponses,
-  ExtractRouteNames,
-  ExtractPathParams,
-  ResponseError,
-  ResponseEnvelope,
+  ProblemDetails,
   RouteResponse,
 } from "./type-extraction.js";
 
-// Path helper types
 export type {
   PathFn,
   ResponsePathFn,
@@ -39,10 +31,8 @@ export type {
   PathHelpers,
 } from "./path-helper-types.js";
 
-// Main entry point
 export { urls } from "./urls-function.js";
 
-// Re-exports from route-types
 export type {
   AllUseItems,
   IncludeItem,

package/src/urls/path-helper-types.ts

@@ -114,6 +114,12 @@ export type ResponsePathFn<TEnv> = <
  * Path function for JSON response routes (path.json()).
  * Handler can return plain JSON-serializable values or Response.
  * TData is inferred from the handler's return type (excluding Response/Promise wrappers).
+ *
+ * Note: a nested Promise in the return (a forgotten await) is caught at runtime
+ * by response-route-handler.ts (it throws instead of silently emitting `{}`). A
+ * compile-time JsonValue constraint was evaluated and rejected — it breaks
+ * interface-typed returns (interfaces lack the index signature JsonValue
+ * requires) and preserves literal types in the inferred response shape.
  */
 export type JsonResponsePathFn<TEnv> = <
   const TPattern extends string,
@@ -233,12 +239,27 @@ export type PathHelpers<TEnv> = {
   include: IncludeFn<TEnv>;
 
   /**
-   * Define parallel routes that render simultaneously in named slots
+   * Define parallel routes that render simultaneously in named slots.
+   *
+   * A slot value can be a Handler / ReactNode / StaticHandlerDefinition
+   * (legacy form, broadcast use applies to every slot) or a slot descriptor
+   * `{ handler, use? }` whose `use` is scoped to that slot only. Per-slot
+   * merge order is `handler.use` → shared `use` → slot-local `use`, with
+   * narrowest scope winning for last-write-wins items like `loading()`.
    */
   parallel: <
     TSlots extends Record<
       `@${string}`,
-      Handler<any, any, TEnv> | ReactNode | StaticHandlerDefinition
+      | Handler<any, any, TEnv>
+      | ReactNode
+      | StaticHandlerDefinition
+      | {
+          handler:
+            | Handler<any, any, TEnv>
+            | ReactNode
+            | StaticHandlerDefinition;
+          use?: () => ParallelUseItem[];
+        }
     >,
   >(
     slots: TSlots,
@@ -249,7 +270,7 @@ export type PathHelpers<TEnv> = {
    * Define an intercepting route for soft navigation
    * Note: routeName must match a named path() in this urlpatterns
    */
-  intercept: keyof RSCRouter.GeneratedRouteMap extends never
+  intercept: keyof Rango.GeneratedRouteMap extends never
     ? (
         slotName: `@${string}`,
         routeName: string,
@@ -258,15 +279,26 @@ export type PathHelpers<TEnv> = {
       ) => InterceptItem
     : (
         slotName: `@${string}`,
-        routeName: (keyof RSCRouter.GeneratedRouteMap & string) | `.${string}`,
+        routeName: (keyof Rango.GeneratedRouteMap & string) | `.${string}`,
         handler: ReactNode | Handler<any, any, TEnv>,
         use?: () => InterceptUseItem[],
       ) => InterceptItem;
 
   /**
-   * Attach middleware to the current route/layout
+   * Attach middleware to the current route/layout, or wrap child segments
    */
-  middleware: (...fns: MiddlewareFn<TEnv>[]) => MiddlewareItem;
+  middleware: {
+    (fn: MiddlewareFn<TEnv>): MiddlewareItem;
+    (
+      fn: MiddlewareFn<TEnv>,
+      children: () => UseItems<LayoutUseItem>,
+    ): MiddlewareItem;
+    (fns: MiddlewareFn<TEnv>[]): MiddlewareItem;
+    (
+      fns: MiddlewareFn<TEnv>[],
+      children: () => UseItems<LayoutUseItem>,
+    ): MiddlewareItem;
+  };
 
   /**
    * Control when a segment should revalidate during navigation
@@ -316,15 +348,23 @@ export type PathHelpers<TEnv> = {
     <const TChildren extends readonly (AllUseItems | readonly AllUseItems[])[]>(
       children: () => TChildren,
     ): TypedCacheItem<ExtractRoutes<TChildren>, ExtractResponses<TChildren>>;
-    (options: PartialCacheOptions | false): TypedCacheItem<{}, {}>;
+    (options: PartialCacheOptions<TEnv> | false): TypedCacheItem<{}, {}>;
     <const TChildren extends readonly (AllUseItems | readonly AllUseItems[])[]>(
-      options: PartialCacheOptions | false,
+      options: PartialCacheOptions<TEnv> | false,
       use: () => TChildren,
     ): TypedCacheItem<ExtractRoutes<TChildren>, ExtractResponses<TChildren>>;
   };
 
   /**
-   * Attach a ViewTransition boundary to the current segment or a group of routes
+   * Opt a route (or group of routes) into transition-driven navigation.
+   *
+   * Two independent layers: (1) startTransition, on all React versions, holds
+   * the previous content across a same-route nav (no skeleton flash) and is the
+   * precondition for any view transition; (2) on experimental React, an
+   * additional `<ViewTransition>` boundary cross-fades/morphs the swap. Pass
+   * `{ viewTransition: false }` to keep #1 without the router boundary. A view
+   * transition cannot fire without a startTransition. See
+   * skills/view-transitions for the startTransition x ViewTransition matrix.
    */
   transition: {
     (): TransitionItem;