@rangojs/router 0.0.0-experimental.9c9afef3 → 0.0.0-experimental.a014d2b7

package/src/route-definition/dsl-helpers.ts

@@ -11,12 +11,18 @@ import {
   getContext,
   getNamePrefix,
   getUrlPrefix,
+  requireDslContext,
   type EntryData,
+  type EntryPropDatas,
+  type EntryPropSegments,
+  type HelperContext,
   type InterceptEntry,
+  type InterceptConfig,
 } from "../server/context";
 import { invariant } from "../errors";
+import { validateUserRouteName } from "../route-name.js";
 import { isCachedFunction } from "../cache/taint.js";
-import { RSCRouterContext } from "../server/context";
+import { RangoContext } from "../server/context";
 import { isStaticHandler } from "../static-handler.js";
 import RootLayout from "../server/root-layout";
 import type {
@@ -31,12 +37,13 @@ import type {
   ErrorBoundaryItem,
   NotFoundBoundaryItem,
   LayoutItem,
-  WhenItem,
   CacheItem,
   TransitionItem,
   UseItems,
 } from "../route-types.js";
 import type { RouteHelpers } from "./helpers-types.js";
+import { resolveHandlerUse, mergeHandlerUse } from "./resolve-handler-use.js";
+import { ALL_USE_ITEM_TYPES } from "./use-item-types.js";
 
 /**
  * Check if an item contains routes (directly or inside nested structures like cache).
@@ -54,19 +61,111 @@ const hasRoutesInItem = (item: AllUseItems): boolean => {
   if (item.type === "layout" && item.uses) {
     return item.uses.some((child) => hasRoutesInItem(child));
   }
+  if (item.type === "middleware" && item.uses) {
+    return item.uses.some((child) => hasRoutesInItem(child));
+  }
   return false;
 };
 
+/**
+ * Fresh empty collections shared by every from-scratch segment entry. Returns
+ * new arrays/objects per call so no two entries share mutable references.
+ * mountPath is intentionally NOT included here — each call site adds it from
+ * getUrlPrefix() where applicable: the route() and transition() helpers add
+ * none, while path() (which also builds a `type: "route"` entry) and the
+ * structural helpers (layout/cache/middleware/parallel) do.
+ */
+const emptySegmentBase = (): EntryPropDatas &
+  EntryPropSegments & { loading: undefined } => ({
+  loading: undefined,
+  middleware: [],
+  revalidate: [],
+  errorBoundary: [],
+  notFoundBoundary: [],
+  layout: [],
+  parallel: {},
+  intercept: [],
+  loader: [],
+});
+
+/**
+ * Run a children/use callback as a nested scope, flatten the result, and assert
+ * every item is a valid use item. `kind` preserves the existing error wording
+ * ("use()" vs "children" callback).
+ */
+function runAndValidateUseItems(
+  store: ReturnType<typeof getContext>,
+  namespace: string,
+  entry: EntryData,
+  cb: () => any,
+  label: string,
+  kind: "use" | "children",
+): AllUseItems[] {
+  const result = store.run(namespace, entry, cb)?.flat(3);
+  return validateUseItems(result, namespace, label, kind);
+}
+
+/** Assert an already-invoked, flattened callback result is a use-item array. */
+function validateUseItems(
+  result: any,
+  namespace: string,
+  label: string,
+  kind: "use" | "children",
+): AllUseItems[] {
+  invariant(
+    Array.isArray(result) && result.every((item) => isValidUseItem(item)),
+    `${label}() ${kind === "use" ? "use()" : "children"} callback must return an array of use items [${namespace}]`,
+  );
+  return result as AllUseItems[];
+}
+
+/** True when a children/use result contains no routes (directly or nested). */
+const isOrphan = (result: AllUseItems[]): boolean =>
+  !result.some((item) => item != null && hasRoutesInItem(item));
+
+/**
+ * Register a routeless structural entry as an orphan sibling: clear its parent
+ * pointer so it leaves the middleware/parent-pointer chain (LOAD-BEARING — see
+ * docs/tree-structure.md) and push it onto the parent's layout[] so it renders
+ * as a wrapper. Used by cache()/middleware()/transition(); layout() runs extra
+ * validation and registers inline.
+ */
+const attachOrphanSibling = (
+  parent: EntryData | null,
+  entry: EntryData,
+): void => {
+  entry.parent = null;
+  if (parent && "layout" in parent) parent.layout.push(entry);
+};
+
+/**
+ * Run `fn` with `ctx.parent` temporarily redirected to `temp` — a satellite
+ * entry that captures the attachments declared by a use() callback — restoring
+ * the original parent afterward, including on throw. loader()/intercept() each
+ * build their own tempParent shape (intercept keeps a loading get/set accessor
+ * and a captured-layouts array); this only centralizes the save/restore.
+ */
+function withParent<T>(ctx: HelperContext, temp: EntryData, fn: () => T): T {
+  const original = ctx.parent;
+  ctx.parent = temp;
+  try {
+    return fn();
+  } finally {
+    ctx.parent = original;
+  }
+}
+
 const revalidate: RouteHelpers<any, any>["revalidate"] = (fn) => {
-  const ctx = getContext().getStore();
-  if (!ctx) throw new Error("revalidate() must be called inside map()");
+  const { store, ctx } = requireDslContext(
+    "revalidate() must be called inside urls()",
+  );
 
   // Attach to last entry in stack
   const parent = ctx.parent;
   if (!parent || !("revalidate" in parent)) {
     invariant(false, "No parent entry available for revalidate()");
   }
-  const name = `$${getContext().getNextIndex("revalidate")}`;
+  const name = `$${store.getNextIndex("revalidate")}`;
   parent.revalidate.push(fn);
   return { name, type: "revalidate" } as RevalidateItem;
 };
@@ -104,15 +203,16 @@ const revalidate: RouteHelpers<any, any>["revalidate"] = (fn) => {
  * ```
  */
 const errorBoundary: RouteHelpers<any, any>["errorBoundary"] = (fallback) => {
-  const ctx = getContext().getStore();
-  if (!ctx) throw new Error("errorBoundary() must be called inside map()");
+  const { store, ctx } = requireDslContext(
+    "errorBoundary() must be called inside urls()",
+  );
 
   // Attach to parent entry in stack
   const parent = ctx.parent;
   if (!parent || !("errorBoundary" in parent)) {
     invariant(false, "No parent entry available for errorBoundary()");
   }
-  const name = `$${getContext().getNextIndex("errorBoundary")}`;
+  const name = `$${store.getNextIndex("errorBoundary")}`;
   parent.errorBoundary.push(fallback);
   return { name, type: "errorBoundary" } as ErrorBoundaryItem;
 };
@@ -151,46 +251,20 @@ const errorBoundary: RouteHelpers<any, any>["errorBoundary"] = (fallback) => {
 const notFoundBoundary: RouteHelpers<any, any>["notFoundBoundary"] = (
   fallback,
 ) => {
-  const ctx = getContext().getStore();
-  if (!ctx) throw new Error("notFoundBoundary() must be called inside map()");
+  const { store, ctx } = requireDslContext(
+    "notFoundBoundary() must be called inside urls()",
+  );
 
   // Attach to parent entry in stack
   const parent = ctx.parent;
   if (!parent || !("notFoundBoundary" in parent)) {
     invariant(false, "No parent entry available for notFoundBoundary()");
   }
-  const name = `$${getContext().getNextIndex("notFoundBoundary")}`;
+  const name = `$${store.getNextIndex("notFoundBoundary")}`;
   parent.notFoundBoundary.push(fallback);
   return { name, type: "notFoundBoundary" } as NotFoundBoundaryItem;
 };
 
-/**
- * When helper - defines a condition for intercept activation
- *
- * Only valid inside intercept() use() callback. The when() function
- * is captured by the intercept and stored in its `when` array.
- * During soft navigation, all when() conditions must return true
- * for the intercept to activate.
- */
-const when: RouteHelpers<any, any>["when"] = (fn) => {
-  const ctx = getContext().getStore();
-  if (!ctx) throw new Error("when() must be called inside intercept()");
-
-  // The when() function needs to be captured by the intercept's tempParent
-  // which should have a `when` array. If not present, we're not inside intercept()
-  const parent = ctx.parent as any;
-  if (!parent || !("when" in parent)) {
-    invariant(
-      false,
-      "when() can only be used inside intercept() use() callback",
-    );
-  }
-
-  const name = `$${getContext().getNextIndex("when")}`;
-  parent.when.push(fn);
-  return { name, type: "when" } as WhenItem;
-};
-
 /**
  * Cache helper - defines caching configuration for segments
  *
@@ -201,21 +275,21 @@ const when: RouteHelpers<any, any>["when"] = (fn) => {
  * Supports these call signatures:
  * - cache() - no args, uses app-level defaults (for loader caching)
  * - cache(() => [...]) - wraps children with app-level defaults
- * - cache('profileName') - uses a named cache profile
- * - cache('profileName', () => [...]) - named profile with children
  * - cache({ ttl: 60 }, () => [...]) - with explicit options
+ *
+ * Named cache profiles are applied via the `"use cache: <profile>"` directive,
+ * not a `cache("profileName")` form in the route tree.
  */
 const cache: RouteHelpers<any, any>["cache"] = (
   optionsOrChildren?:
     | PartialCacheOptions
     | false
-    | string
     | (() => UseItems<AllUseItems>),
   maybeChildren?: () => UseItems<AllUseItems>,
 ) => {
-  const store = getContext();
-  const ctx = store.getStore();
-  if (!ctx) throw new Error("cache() must be called inside map()");
+  const { store, ctx } = requireDslContext(
+    "cache() must be called inside urls()",
+  );
 
   // Handle overloaded signature
   let options: PartialCacheOptions | false;
@@ -225,18 +299,6 @@ const cache: RouteHelpers<any, any>["cache"] = (
     // cache() - no args, use defaults
     options = {};
     children = undefined;
-  } else if (typeof optionsOrChildren === "string") {
-    // cache('profileName') or cache('profileName', () => [...])
-    // Resolve from context-scoped profiles (set per-router via HelperContext).
-    const ctxStore = RSCRouterContext.getStore();
-    const profile = ctxStore?.cacheProfiles?.[optionsOrChildren];
-    invariant(
-      profile,
-      `cache("${optionsOrChildren}"): unknown cache profile. ` +
-        `Define it in createRouter({ cacheProfiles: { "${optionsOrChildren}": { ttl: ... } } }).`,
-    );
-    options = { ttl: profile.ttl, swr: profile.swr, tags: profile.tags };
-    children = maybeChildren;
   } else if (typeof optionsOrChildren === "function") {
     // cache(() => [...]) - use empty options (will use defaults)
     options = {};
@@ -267,26 +329,18 @@ const cache: RouteHelpers<any, any>["cache"] = (
     // Create orphan cache entry (like orphan layout)
     // Subsequent siblings in the same array will attach to this entry
     const namespace = `${ctx.namespace}.${cacheIndex}`;
-    const cacheUrlPrefix = getUrlPrefix();
+    const urlPrefix = getUrlPrefix();
 
     const entry = {
+      ...emptySegmentBase(),
       id: namespace,
       shortCode: store.getShortCode("cache"),
       type: "cache",
       parent: parent, // link to current parent for hierarchy
       cache: cacheConfig,
       handler: RootLayout,
-      loading: undefined, // Allow loading() to attach loading state
-      middleware: [],
-      revalidate: [],
-      errorBoundary: [],
-      notFoundBoundary: [],
-      layout: [],
-      parallel: {},
-      intercept: [],
-      loader: [],
-      ...(cacheUrlPrefix ? { mountPath: cacheUrlPrefix } : {}),
-    } as EntryData;
+      ...(urlPrefix ? { mountPath: urlPrefix } : {}),
+    } satisfies EntryData;
 
     // Attach to parent's layout array (cache entries are structural like layouts)
     if (parent && "layout" in parent) {
@@ -300,13 +354,23 @@ const cache: RouteHelpers<any, any>["cache"] = (
     return { name: namespace, type: "cache" } as CacheItem;
   }
 
+  // Inside a loader() use() callback, only the direct form — cache()/cache(opts)
+  // — writes cache config to the loader entry. The wrapper form creates a
+  // structural cache boundary with its own children scope, which has no effect
+  // on the loader and would silently no-op.
+  invariant(
+    !(ctx.parent && (ctx.parent as any).type === "loader"),
+    "cache() wrapper form is not valid inside loader() use(). Use cache({...}) without children to configure the loader's cache.",
+  );
+
   // With children: create a cache entry (like layout with caching semantics)
   const namespace = `${ctx.namespace}.${cacheIndex}`;
   const cacheShortCode = store.getShortCode("cache");
 
-  const cacheUrlPrefix2 = getUrlPrefix();
+  const urlPrefix = getUrlPrefix();
 
   const entry = {
+    ...emptySegmentBase(),
     id: namespace,
     shortCode: cacheShortCode,
     type: "cache",
@@ -314,48 +378,57 @@ const cache: RouteHelpers<any, any>["cache"] = (
     cache: cacheConfig,
     // Cache entries render like layouts (with Outlet as default handler)
     handler: RootLayout, // RootLayout just renders <Outlet />
-    loading: undefined, // Allow loading() to attach loading state
-    middleware: [],
-    revalidate: [],
-    errorBoundary: [],
-    notFoundBoundary: [],
-    layout: [],
-    parallel: {},
-    intercept: [],
-    loader: [],
-    ...(cacheUrlPrefix2 ? { mountPath: cacheUrlPrefix2 } : {}),
-  } as EntryData;
+    ...(urlPrefix ? { mountPath: urlPrefix } : {}),
+  } satisfies EntryData;
 
   // Run children with cache entry as parent
-  const result = store.run(namespace, entry, children)?.flat(3);
-
-  invariant(
-    Array.isArray(result) && result.every((item) => isValidUseItem(item)),
-    `cache() children callback must return an array of use items [${namespace}]`,
+  const result = runAndValidateUseItems(
+    store,
+    namespace,
+    entry,
+    children,
+    "cache",
+    "children",
   );
 
-  // Check if this cache has routes (including nested caches/layouts)
-  const hasRoutes =
-    result &&
-    Array.isArray(result) &&
-    result.some((item) => hasRoutesInItem(item));
-
-  if (!hasRoutes) {
-    const parent = ctx.parent;
-    if (parent && "layout" in parent) {
-      // Attach to parent's layout array (cache entries are structural like layouts)
-      entry.parent = null;
-      parent.layout.push(entry);
-    }
-  }
+  // Cache entries are structural like layouts: with no routes inside, register
+  // as an orphan sibling.
+  if (isOrphan(result)) attachOrphanSibling(ctx.parent, entry);
 
   return { name: namespace, type: "cache", uses: result } as CacheItem;
 };
 
-const middleware: RouteHelpers<any, any>["middleware"] = (...fn) => {
+const middleware: RouteHelpers<any, any>["middleware"] = (...args: any[]) => {
+  // Four call forms:
+  //   middleware(fn)                       — single fn, sibling
+  //   middleware(fn, () => [...])          — single fn, wrapping
+  //   middleware([fn1, fn2])              — array, sibling
+  //   middleware([fn1, fn2], () => [...]) — array, wrapping
+  const isArray = Array.isArray(args[0]);
+
+  // Reject the removed variadic form before executing anything.
+  // middleware(fn1, fn2, fn3) — 3+ args, always wrong.
+  // middleware(fn1, fn2) where fn2 is a middleware fn (length >= 1), not a
+  // children callback (length === 0) — legacy two-fn form, reject early.
+  if (
+    args.length > 2 ||
+    (!isArray &&
+      args.length === 2 &&
+      typeof args[1] === "function" &&
+      args[1].length > 0)
+  ) {
+    throw new Error(
+      "middleware() no longer accepts variadic arguments. " +
+        "Use middleware([fn1, fn2, ...]) instead of middleware(fn1, fn2, ...).",
+    );
+  }
+
+  const fns: MiddlewareFn<any>[] = isArray ? args[0] : [args[0]];
+  const children: (() => any[]) | undefined =
+    typeof args[1] === "function" ? args[1] : undefined;
+
   // Prevent "use cache" functions from being used as middleware.
-  // Checked before context validation — this is a static invariant.
-  for (const f of fn) {
+  for (const f of fns) {
     if (isCachedFunction(f)) {
       throw new Error(
         `A "use cache" function cannot be used as middleware. ` +
@@ -366,23 +439,84 @@ const middleware: RouteHelpers<any, any>["middleware"] = (...fn) => {
     }
   }
 
-  const ctx = getContext().getStore();
-  if (!ctx) throw new Error("middleware() must be called inside map()");
+  const { store, ctx } = requireDslContext(
+    "middleware() must be called inside urls()",
+  );
 
-  // Attach to last entry in stack
-  const parent = ctx.parent;
-  if (!parent || !("middleware" in parent)) {
-    invariant(false, "No parent entry available for middleware()");
+  if (!children) {
+    // Sibling mode: attach to parent entry
+    const parent = ctx.parent;
+    if (!parent || !("middleware" in parent)) {
+      invariant(false, "No parent entry available for middleware()");
+    }
+    const name = `$${store.getNextIndex("middleware")}`;
+    parent.middleware.push(...fns);
+    return { name, type: "middleware" } as MiddlewareItem;
   }
-  const name = `$${getContext().getNextIndex("middleware")}`;
-  parent.middleware.push(...fn);
-  return { name, type: "middleware" } as MiddlewareItem;
+
+  // Wrapping mode: create a transparent layout that carries the middleware
+  const mwIndex = store.getNextIndex("middleware");
+  const namespace = `${ctx.namespace}.${mwIndex}`;
+
+  const urlPrefix = getUrlPrefix();
+  const entry = {
+    ...emptySegmentBase(),
+    id: namespace,
+    shortCode: store.getShortCode("layout"),
+    type: "layout",
+    parent: ctx.parent,
+    handler: RootLayout,
+    middleware: [...fns],
+    ...(urlPrefix ? { mountPath: urlPrefix } : {}),
+  } satisfies EntryData;
+
+  // Run children callback. If the second arg was actually a middleware fn
+  // (old variadic form: middleware(mw1, mw2)), this will return a non-array
+  // and the invariant below gives a clear migration error.
+  const rawResult = store.run(namespace, entry, children);
+
+  invariant(
+    Array.isArray(rawResult),
+    "middleware(fn, children) expects the second argument to return an array of use items. " +
+      "To pass multiple middleware, use middleware([fn1, fn2]).",
+  );
+
+  const result = validateUseItems(
+    rawResult.flat(3),
+    namespace,
+    "middleware",
+    "children",
+  );
+
+  if (isOrphan(result)) attachOrphanSibling(ctx.parent, entry);
+
+  return {
+    name: namespace,
+    type: "middleware",
+    uses: result,
+  } as MiddlewareItem;
 };
 
+// Slot names become part of segment ids: a parallel/intercept slot is encoded
+// as `${shortCode}.${slotName}`, and loader segments append `D${index}.${loaderId}`.
+// A "." in the slot name collides with that separator -- loaderParentId
+// (segment-system.tsx) strips from the FIRST `D<index>.`, so a name like
+// "@D3.foo" is mis-cut to "@" and the loader's data is silently dropped. Reject
+// the dot at definition time so the failure is loud, not a corrupted tree at
+// runtime. (A bare "D" without a trailing dot -- e.g. "@Detail" -- is fine.)
+function assertValidSlotName(slotName: string): void {
+  invariant(
+    !slotName.includes("."),
+    `Slot name "${slotName}" must not contain ".". The dot is a reserved ` +
+      `segment-id separator; a name like "@D3.foo" corrupts loader segment-id ` +
+      `parsing and silently drops the loader's data. Rename the slot.`,
+  );
+}
+
 const parallel: RouteHelpers<any, any>["parallel"] = (slots, use) => {
-  const store = getContext();
-  const ctx = store.getStore();
-  if (!ctx) throw new Error("parallel() must be called inside map()");
+  const { store, ctx } = requireDslContext(
+    "parallel() must be called inside urls()",
+  );
 
   if (!ctx.parent || !ctx.parent?.parallel) {
     invariant(false, "No parent entry available for parallel()");
@@ -394,16 +528,29 @@ const parallel: RouteHelpers<any, any>["parallel"] = (slots, use) => {
   );
 
   const slotNames = Object.keys(slots as Record<string, any>) as `@${string}`[];
+  for (const slotName of slotNames) assertValidSlotName(slotName);
 
   const namespace = `${ctx.namespace}.$${store.getNextIndex("parallel")}`;
 
-  // Unwrap any static handler definitions in parallel slots
+  // Unwrap slot values. A slot value can be:
+  //   - a Handler / ReactNode (legacy form)
+  //   - a Static() definition (build-time only)
+  //   - a slot descriptor `{ handler, use? }` for slot-local overrides
+  // The descriptor's `use` runs after the broadcast `use` for that slot,
+  // so single-assignment items like `loading()` placed there win without
+  // affecting siblings.
   const unwrappedSlots: Record<string, any> = {};
+  const slotLocalUses: Record<string, (() => any[]) | undefined> = {};
   let hasStaticSlot = false;
   const staticSlotIds: Record<string, string> = {};
-  for (const [slotName, slotHandler] of Object.entries(
+  for (const [slotName, rawSlot] of Object.entries(
     slots as Record<string, any>,
   )) {
+    let slotHandler: any = rawSlot;
+    if (isSlotDescriptor(rawSlot)) {
+      slotHandler = rawSlot.handler;
+      slotLocalUses[slotName] = rawSlot.use;
+    }
     if (isStaticHandler(slotHandler)) {
       hasStaticSlot = true;
       unwrappedSlots[slotName] = slotHandler.handler;
@@ -422,20 +569,12 @@ const parallel: RouteHelpers<any, any>["parallel"] = (slots, use) => {
   // Create full EntryData for parallel with its own loaders/revalidate/loading
   const parallelUrlPrefix = getUrlPrefix();
   const entry = {
+    ...emptySegmentBase(),
     id: namespace,
     shortCode: store.getShortCode("parallel"),
     type: "parallel",
     parent: null, // Parallels don't participate in parent chain traversal
     handler: unwrappedSlots,
-    loading: undefined, // Allow loading() to attach loading state
-    middleware: [],
-    revalidate: [],
-    errorBoundary: [],
-    notFoundBoundary: [],
-    layout: [],
-    parallel: {},
-    intercept: [],
-    loader: [],
     ...(parallelUrlPrefix ? { mountPath: parallelUrlPrefix } : {}),
     ...(hasStaticSlot
       ? {
@@ -447,15 +586,6 @@ const parallel: RouteHelpers<any, any>["parallel"] = (slots, use) => {
       : {}),
   } satisfies EntryData;
 
-  // Run use callback if provided to collect loaders, revalidate, loading
-  if (use && typeof use === "function") {
-    const result = store.run(namespace, entry, use)?.flat(3);
-    invariant(
-      Array.isArray(result) && result.every((item) => isValidUseItem(item)),
-      `parallel() use() callback must return an array of use items [${namespace}]`,
-    );
-  }
-
   for (const slotName of slotNames) {
     const slotEntry = {
       ...entry,
@@ -478,11 +608,64 @@ const parallel: RouteHelpers<any, any>["parallel"] = (slots, use) => {
             staticHandlerIds: undefined,
           }),
     } satisfies EntryData;
+
+    // Per-slot merge order (narrowest-scope-wins for single-assignment items
+    // like loading()):
+    //   1. handler.use      — defaults baked into the handler
+    //   2. shared `use`     — broadcast at the parallel() call site
+    //   3. slot-local `use` — per-slot override via `{ handler, use }` descriptor
+    // Items that accumulate (loader, middleware, revalidate, …) compose
+    // across all three layers regardless of order.
+    const rawSlot = (slots as Record<string, any>)[slotName];
+    const slotHandlerForUse = isSlotDescriptor(rawSlot)
+      ? rawSlot.handler
+      : rawSlot;
+    const slotHandlerUse = resolveHandlerUse(slotHandlerForUse);
+    const slotLocalUse = slotLocalUses[slotName];
+    const explicitUse = combineExplicitUses(use, slotLocalUse);
+    const slotMergedUse = mergeHandlerUse(
+      slotHandlerUse,
+      explicitUse,
+      "parallel",
+    );
+    if (slotMergedUse) {
+      runAndValidateUseItems(
+        store,
+        namespace,
+        slotEntry,
+        slotMergedUse,
+        "parallel",
+        "use",
+      );
+    }
+
     ctx.parent.parallel[slotName] = slotEntry;
   }
   return { name: namespace, type: "parallel" } as ParallelItem;
 };
 
+function isSlotDescriptor(
+  value: unknown,
+): value is { handler: unknown; use?: () => any[] } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !("__brand" in value) &&
+    "handler" in value &&
+    typeof (value as any).handler !== "undefined"
+  );
+}
+
+function combineExplicitUses(
+  sharedUse: (() => any[]) | undefined,
+  slotLocalUse: (() => any[]) | undefined,
+): (() => any[]) | undefined {
+  if (!sharedUse && !slotLocalUse) return undefined;
+  if (!slotLocalUse) return sharedUse;
+  if (!sharedUse) return slotLocalUse;
+  return () => [...sharedUse(), ...slotLocalUse()];
+}
+
 /**
  * Intercept helper - defines an intercepting route for soft navigation
  */
@@ -490,11 +673,22 @@ const intercept = (
   slotName: `@${string}`,
   routeName: string,
   handler: any,
+  configOrUse?: InterceptConfig | (() => any[]),
   use?: () => any[],
 ) => {
-  const store = getContext();
-  const ctx = store.getStore();
-  if (!ctx) throw new Error("intercept() must be called inside map()");
+  // arg4 discrimination: a function is the use() callback (no config); an object
+  // is the config carrying `when`. With config given, the use() callback is
+  // arg5. Keeps the no-config form intercept(slot, route, handler, () => [...])
+  // working unchanged.
+  const config: InterceptConfig | undefined =
+    typeof configOrUse === "function" || configOrUse == null
+      ? undefined
+      : configOrUse;
+  const useFn = typeof configOrUse === "function" ? configOrUse : use;
+
+  const { store, ctx } = requireDslContext(
+    "intercept() must be called inside urls()",
+  );
 
   if (!ctx.parent || !ctx.parent?.intercept) {
     invariant(false, "No parent entry available for intercept()");
@@ -505,6 +699,8 @@ const intercept = (
     "intercept() cannot be used inside parallel()",
   );
 
+  assertValidSlotName(slotName);
+
   const namespace = `${ctx.namespace}.$${store.getNextIndex("intercept")}.${slotName}`;
 
   // Dot-prefixed = local (add include prefix), unprefixed = global (use as-is)
@@ -527,25 +723,33 @@ const intercept = (
     when: [], // Selector conditions for conditional interception
   };
 
-  // Run use callback if provided to collect loaders, revalidate, middleware, etc.
-  if (use && typeof use === "function") {
-    // Create a temporary parent context for the use() callback
-    // so that middleware, loader, revalidate attach to the intercept entry
-    const originalParent = ctx.parent;
+  // Conditional interception: `when` from the config object — a single selector
+  // or an array (ALL must return true to activate). Replaces the former when()
+  // use-item captured inside the callback.
+  if (config?.when) {
+    const selectors = Array.isArray(config.when) ? config.when : [config.when];
+    entry.when.push(...selectors);
+  }
 
-    // Capture layouts in a temporary array
+  // Merge handler.use defaults with explicit use
+  const handlerUseFn = resolveHandlerUse(handler);
+  const mergedUse = mergeHandlerUse(handlerUseFn, useFn, "intercept");
+
+  // Run merged use callback to collect loaders, revalidate, middleware, etc.
+  if (mergedUse) {
+    // Capture layout() calls into a temporary array
     const capturedLayouts: EntryData[] = [];
 
+    // Temporary parent so middleware/loader/revalidate/when attach to the
+    // intercept entry; the loading get/set accessor mirrors writes onto `entry`.
     const tempParent = {
-      ...originalParent,
+      ...ctx.parent,
       middleware: entry.middleware,
       revalidate: entry.revalidate,
       errorBoundary: entry.errorBoundary,
       notFoundBoundary: entry.notFoundBoundary,
       loader: entry.loader,
       layout: capturedLayouts, // Capture layout() calls
-      when: entry.when, // Capture when() conditions
-      // Use getter/setter to capture loading on the entry
       get loading() {
         return entry.loading;
       },
@@ -553,12 +757,10 @@ const intercept = (
         entry.loading = value;
       },
     };
-    ctx.parent = tempParent as EntryData;
-
-    const result = use()?.flat(3);
 
-    // Restore original parent
-    ctx.parent = originalParent;
+    const result = withParent(ctx, tempParent as EntryData, () =>
+      mergedUse()?.flat(3),
+    );
 
     // Extract layout from captured layouts (use first one if multiple)
     // Layout inside intercept should always be ReactNode or Handler, not Record slots
@@ -568,10 +770,7 @@ const intercept = (
         | Handler<any, any, any>;
     }
 
-    invariant(
-      Array.isArray(result) && result.every((item) => isValidUseItem(item)),
-      `intercept() use() callback must return an array of use items [${namespace}]`,
-    );
+    validateUseItems(result, namespace, "intercept", "use");
   }
 
   ctx.parent.intercept.push(entry);
@@ -581,10 +780,10 @@ const intercept = (
 /**
  * Loader helper - attaches a loader to the current entry
  */
-const loaderFn: RouteHelpers<any, any>["loader"] = (loaderDef, use) => {
-  const store = getContext();
-  const ctx = store.getStore();
-  if (!ctx) throw new Error("loader() must be called inside map()");
+const loader: RouteHelpers<any, any>["loader"] = (loaderDef, use) => {
+  const { store, ctx } = requireDslContext(
+    "loader() must be called inside urls()",
+  );
 
   // Attach to last entry in stack
   if (!ctx.parent || !ctx.parent?.loader) {
@@ -599,25 +798,28 @@ const loaderFn: RouteHelpers<any, any>["loader"] = (loaderDef, use) => {
     revalidate: [] as ShouldRevalidateFn<any, any>[],
   };
 
-  // If use() callback provided, run it to collect revalidation rules and cache config
-  if (use && typeof use === "function") {
-    // Temporarily set context for revalidate()/cache() calls to target this loader
-    const originalParent = ctx.parent;
+  // Merge handler.use defaults (attached to the loader definition) with explicit use
+  const handlerUseFn = resolveHandlerUse(loaderDef);
+  const mergedUse = mergeHandlerUse(handlerUseFn, use, "loader");
+
+  // If any use callback is in effect, run it to collect revalidation rules and cache config
+  if (mergedUse) {
     // Create a temporary "parent" with type "loader" so cache() can detect it.
     // Save existing .cache to distinguish inherited config from newly set config.
-    const parentCache = (originalParent as any).cache;
+    const parentCache = (ctx.parent as any).cache;
     const tempParent = {
-      ...originalParent,
+      ...ctx.parent,
       type: "loader",
       revalidate: loaderEntry.revalidate,
     };
-    ctx.parent = tempParent as EntryData;
 
-    const result = use()?.flat(3);
+    const result = withParent(ctx, tempParent as EntryData, () =>
+      mergedUse()?.flat(3),
+    );
 
     // Copy cache config only if cache() was called during the use() callback.
-    // The spread from originalParent may carry an inherited .cache from
-    // a parent cache() boundary — only copy if it was newly set.
+    // The spread may carry an inherited .cache from a parent cache() boundary —
+    // only copy if it was newly set.
     if (
       (tempParent as any).cache &&
       (tempParent as any).cache !== parentCache
@@ -625,13 +827,7 @@ const loaderFn: RouteHelpers<any, any>["loader"] = (loaderDef, use) => {
       (loaderEntry as any).cache = (tempParent as any).cache;
     }
 
-    // Restore original parent
-    ctx.parent = originalParent;
-
-    invariant(
-      Array.isArray(result) && result.every((item) => isValidUseItem(item)),
-      `loader() use() callback must return an array of use items [${name}]`,
-    );
+    validateUseItems(result, name, "loader", "use");
   }
 
   ctx.parent.loader.push(loaderEntry);
@@ -642,21 +838,25 @@ const loaderFn: RouteHelpers<any, any>["loader"] = (loaderDef, use) => {
  * Loading helper - attaches a loading component to the current entry
  * Loading components are static (no context) and shown during navigation
  */
-const loadingFn: RouteHelpers<any, any>["loading"] = (component, options) => {
-  const store = getContext();
-  const ctx = store.getStore();
-  if (!ctx) throw new Error("loading() must be called inside map()");
+const loading: RouteHelpers<any, any>["loading"] = (component, options) => {
+  const { store, ctx } = requireDslContext(
+    "loading() must be called inside urls()",
+  );
 
   const parent = ctx.parent;
   if (!parent || !("loading" in parent)) {
     invariant(false, "No parent entry available for loading()");
   }
 
+  // Unwrap function form: loading(() => <Skeleton />) → loading(<Skeleton />)
+  const resolved =
+    typeof component === "function" ? (component as () => any)() : component;
+
   // If ssr: false and we're in SSR, set loading to false
   if (options?.ssr === false && ctx.isSSR) {
     parent.loading = false;
   } else {
-    parent.loading = component;
+    parent.loading = resolved;
   }
 
   const name = `$${store.getNextIndex("loading")}`;
@@ -664,10 +864,13 @@ const loadingFn: RouteHelpers<any, any>["loading"] = (component, options) => {
 };
 
 /**
- * Transition helper - attaches a ViewTransition config to the current entry
- * or wraps a group of routes in a transparent layout with ViewTransition
+ * Transition helper - opts the entry (or a wrapped group of routes) into
+ * transition-driven navigation by attaching a TransitionConfig. This drives the
+ * commit through startTransition (content hold on all React versions) and, on
+ * experimental React, places a `<ViewTransition>` boundary unless
+ * `viewTransition: false`. See skills/view-transitions for the matrix.
  */
-const transitionFn = (
+const transition = (
   configOrChildren?: TransitionConfig | (() => UseItems<AllUseItems>),
   maybeChildren?: () => UseItems<AllUseItems>,
 ): TransitionItem => {
@@ -681,11 +884,15 @@ const transitionFn = (
   const children: (() => UseItems<AllUseItems>) | undefined =
     typeof configOrChildren === "function" ? configOrChildren : maybeChildren;
 
-  const store = getContext();
-  const ctx = store.getStore();
-  if (!ctx) throw new Error("transition() must be called inside map()");
+  const { store, ctx } = requireDslContext(
+    "transition() must be called inside urls()",
+  );
 
-  const name = `$${store.getNextIndex("transition")}`;
+  // Allocate a single index for this transition() call (used in all paths),
+  // mirroring cache() — the child form uses it for the name, the wrapper form
+  // reuses it for the namespace, so no index is burned.
+  const transitionIndex = store.getNextIndex("transition");
+  const name = `$${transitionIndex}`;
 
   if (!children) {
     // Position 1: child of path() — attach to parent entry
@@ -698,70 +905,51 @@ const transitionFn = (
   }
 
   // Position 2: wrapper — create a transparent layout with transition config
-  const namespace = `${ctx.namespace}.${store.getNextIndex("transition")}`;
+  const namespace = `${ctx.namespace}.${transitionIndex}`;
   const entry = {
+    ...emptySegmentBase(),
     id: namespace,
     shortCode: store.getShortCode("layout"),
     type: "layout",
     parent: ctx.parent,
     handler: RootLayout,
-    loading: undefined,
     transition: config,
-    middleware: [],
-    revalidate: [],
-    errorBoundary: [],
-    notFoundBoundary: [],
-    layout: [],
-    parallel: {},
-    intercept: [],
-    loader: [],
-  } as EntryData;
-
-  const result = store.run(namespace, entry, children)?.flat(3);
+  } satisfies EntryData;
 
-  invariant(
-    Array.isArray(result) && result.every((item) => isValidUseItem(item)),
-    `transition() children callback must return an array of use items [${namespace}]`,
+  const result = runAndValidateUseItems(
+    store,
+    namespace,
+    entry,
+    children,
+    "transition",
+    "children",
   );
 
-  const hasRoutes =
-    result &&
-    Array.isArray(result) &&
-    result.some((item) => hasRoutesInItem(item));
-
-  if (!hasRoutes) {
-    const parent = ctx.parent;
-    if (parent && "layout" in parent) {
-      entry.parent = null;
-      parent.layout.push(entry);
-    }
-  }
+  if (isOrphan(result)) attachOrphanSibling(ctx.parent, entry);
 
   return { name: namespace, type: "transition" } as TransitionItem;
 };
 
-const routeFn: RouteHelpers<any, any>["route"] = (name, handler, use) => {
-  const store = getContext();
-  const ctx = store.getStore();
-  if (!ctx) throw new Error("route() must be called inside map()");
+const route: RouteHelpers<any, any>["route"] = (name, handler, use) => {
+  const { store, ctx } = requireDslContext(
+    "route() must be called inside urls()",
+  );
+
+  // Reject names colliding with reserved internal prefixes ($path_, $prefix_),
+  // the same guard path() and include() enforce. Without it such a name
+  // type-checks on an untyped router, then silently vanishes from generated
+  // route-types and public reverse() (isAutoGeneratedRouteName filters it out).
+  validateUserRouteName(name);
 
   const namespace = `${ctx.namespace}.${store.getNextIndex("route")}.${name}`;
 
   const entry = {
+    ...emptySegmentBase(),
     id: namespace,
     shortCode: store.getShortCode("route"),
     type: "route",
     parent: ctx.parent,
-    handler,
-    loading: undefined, // Allow loading() to attach loading state
-    middleware: [],
-    revalidate: [],
-    errorBoundary: [],
-    notFoundBoundary: [],
-    layout: [],
-    parallel: {},
-    intercept: [],
-    loader: [],
+    handler: handler as unknown as Handler<any, any, any>,
   } satisfies EntryData;
 
   /* We will throw if user is registring same route name twice */
@@ -771,12 +959,18 @@ const routeFn: RouteHelpers<any, any>["route"] = (name, handler, use) => {
   );
   /* Register route entry */
   ctx.manifest.set(name, entry);
+  /* Merge handler.use defaults with explicit use */
+  const handlerUseFn = resolveHandlerUse(handler);
+  const mergedUse = mergeHandlerUse(handlerUseFn, use, "route");
   /* Run use and attach handlers */
-  if (use && typeof use === "function") {
-    const result = store.run(namespace, entry, use)?.flat(3);
-    invariant(
-      Array.isArray(result) && result.every((item) => isValidUseItem(item)),
-      `route() use() callback must return an array of use items [${namespace}]`,
+  if (mergedUse) {
+    const result = runAndValidateUseItems(
+      store,
+      namespace,
+      entry,
+      mergedUse,
+      "route",
+      "use",
     );
     return { name: namespace, type: "route", uses: result } as RouteItem;
   }
@@ -786,9 +980,9 @@ const routeFn: RouteHelpers<any, any>["route"] = (name, handler, use) => {
 };
 
 const layout: RouteHelpers<any, any>["layout"] = (handler, use) => {
-  const store = getContext();
-  const ctx = store.getStore();
-  if (!ctx) throw new Error("layout() must be called inside map()");
+  const { store, ctx } = requireDslContext(
+    "layout() must be called inside urls()",
+  );
 
   invariant(
     !ctx.parent || ctx.parent.type !== "parallel",
@@ -806,20 +1000,12 @@ const layout: RouteHelpers<any, any>["layout"] = (handler, use) => {
 
   const urlPrefix = getUrlPrefix();
   const entry = {
+    ...emptySegmentBase(),
     id: namespace,
     shortCode,
     type: "layout",
     parent: ctx.parent,
     handler: unwrappedHandler,
-    loading: undefined, // Allow loading() to attach loading state
-    middleware: [],
-    revalidate: [],
-    errorBoundary: [],
-    notFoundBoundary: [],
-    parallel: {},
-    intercept: [],
-    layout: [],
-    loader: [],
     ...(urlPrefix ? { mountPath: urlPrefix } : {}),
     ...(isStatic
       ? {
@@ -834,14 +1020,20 @@ const layout: RouteHelpers<any, any>["layout"] = (handler, use) => {
     (handler as any).$$routePrefix = ctx.namePrefix;
   }
 
-  // Run use callback if provided
-  let result: AllUseItems[] | undefined;
-  if (use && typeof use === "function") {
-    result = store.run(namespace, entry, use)?.flat(3);
+  // Merge handler.use defaults with explicit use
+  const handlerUseFn = resolveHandlerUse(handler);
+  const mergedUse = mergeHandlerUse(handlerUseFn, use, "layout");
 
-    invariant(
-      Array.isArray(result) && result.every((item) => isValidUseItem(item)),
-      `layout() use() callback must return an array of use items [${namespace}]`,
+  // Run merged use callback if present
+  let result: AllUseItems[] | undefined;
+  if (mergedUse) {
+    result = runAndValidateUseItems(
+      store,
+      namespace,
+      entry,
+      mergedUse,
+      "layout",
+      "use",
     );
   }
 
@@ -883,9 +1075,7 @@ const layout: RouteHelpers<any, any>["layout"] = (handler, use) => {
         `Orphan layouts can only be defined inside route or layout > check [${namespace}]`,
       );
 
-      // Clear parent pointer for orphan layouts to prevent duplicate processing
-      entry.parent = null;
-      parent.layout.push(entry);
+      attachOrphanSibling(parent, entry);
     }
   }
 
@@ -898,33 +1088,15 @@ const layout: RouteHelpers<any, any>["layout"] = (handler, use) => {
   } as LayoutItem;
 };
 
-const isValidUseItem = (item: any): item is AllUseItems | undefined | null => {
-  return (
-    typeof item === "undefined" ||
-    item === null ||
-    (item &&
-      typeof item === "object" &&
-      "type" in item &&
-      [
-        "layout",
-        "route",
-        "middleware",
-        "revalidate",
-        "parallel",
-        "intercept",
-        "loader",
-        "loading",
-        "errorBoundary",
-        "notFoundBoundary",
-        "when",
-        "cache",
-        "transition",
-        "include", // For urls() include() helper
-      ].includes(item.type))
-  );
-};
+const isValidUseItem = (item: any): item is AllUseItems | undefined | null =>
+  item == null ||
+  (typeof item === "object" &&
+    "type" in item &&
+    ALL_USE_ITEM_TYPES.has(item.type));
 
-// Global helper exports for direct import from @rangojs/router
+// DSL helpers exported for direct import from @rangojs/router and for
+// assembly into the RouteHelpers object in helper-factories.ts. The route-item
+// types are discriminated by their `type` literal, so the helpers carry no brand.
 export {
   layout,
   cache,
@@ -932,28 +1104,13 @@ export {
   revalidate,
   parallel,
   intercept,
-  when,
   errorBoundary,
   notFoundBoundary,
-  loaderFn as loader,
-  loadingFn as loading,
-  transitionFn as transition,
-};
-
-const isOrphanLayout = (item: AllUseItems): boolean => {
-  return (
-    item.type === "layout" &&
-    !item.uses?.some((child) => hasRoutesInItem(child))
-  );
-};
-
-// Internal exports used by helper-factories.ts
-export {
-  routeFn,
-  loaderFn,
-  loadingFn,
-  transitionFn,
-  hasRoutesInItem,
+  route,
+  loader,
+  loading,
+  transition,
   isValidUseItem,
-  isOrphanLayout,
+  emptySegmentBase,
+  runAndValidateUseItems,
 };