@rangojs/router 0.0.0-experimental.75 → 0.0.0-experimental.76

package/dist/vite/index.js

@@ -1864,7 +1864,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.75",
+  version: "0.0.0-experimental.76",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.75",
+  "version": "0.0.0-experimental.76",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/handler-use/SKILL.md

@@ -0,0 +1,362 @@
+---
+name: handler-use
+description: Attach default loaders, middleware, parallels, and other use items directly to handlers via handler.use, and compose them with explicit use() at mount sites
+argument-hint: "[handler]"
+---
+
+# Handler-Attached `.use`
+
+A handler function (or branded `Static`/`Prerender`/`Passthrough` definition) can carry its own defaults via a `.use` callback that returns an array of `use` items (loader, middleware, parallel, intercept, layout, loading, etc.). The mount-site DSL (`path()`, `layout()`, `parallel()`, `intercept()`) merges those defaults with any explicit `use()` callback supplied at the registration site.
+
+This lets handlers be **self-contained, reusable units** — a page brings its own loader, a layout brings its own middleware, a parallel slot brings its own data + skeleton — without forcing every caller to wire the same items at every mount site.
+
+Canonical implementation reference:
+[src/route-definition/resolve-handler-use.ts](../../src/route-definition/resolve-handler-use.ts)
+
+## Defining a handler with `.use`
+
+Attach `.use` to the function (or to the branded definition for `Static()`/`Prerender()`/`Passthrough()`):
+
+```typescript
+import {
+  loader,
+  middleware,
+  loading,
+  createLoader,
+  type Handler,
+} from "@rangojs/router";
+
+export const ProductLoader = createLoader(async (ctx) =>
+  fetchProduct(ctx.params.slug),
+);
+
+const ProductPage: Handler<"/product/:slug"> = async (ctx) => {
+  const product = await ctx.use(ProductLoader);
+  return <ProductView product={product} />;
+};
+
+ProductPage.use = () => [
+  loader(ProductLoader),
+  loading(<ProductSkeleton />),
+  middleware(async (ctx, next) => {
+    await next();
+    ctx.header("Cache-Control", "private, max-age=60");
+  }),
+];
+```
+
+Now `ProductPage` carries its loader, loading state, and response-header middleware regardless of where it is mounted.
+
+## Allowed items per mount site
+
+`handler.use()` is the same callback shape regardless of where the handler runs, but the runtime validates that the items it returns are valid for the mount site. Driven by `MOUNT_SITE_ALLOWED_TYPES` in [resolve-handler-use.ts](../../src/route-definition/resolve-handler-use.ts):
+
+| Mount site                                        | Allowed item types                                                                                                                             |
+| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `path()` / `route()`                              | `layout`, `parallel`, `intercept`, `middleware`, `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `cache`, `transition` |
+| `layout()`                                        | All of the above, plus `route`, `include`                                                                                                      |
+| `parallel()` (per slot)                           | `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `transition`                                                           |
+| `intercept()`                                     | `middleware`, `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `layout`, `route`, `when`, `transition`                  |
+| Response routes (`path.json()`, `path.text()`, …) | `middleware`, `cache`                                                                                                                          |
+
+If `handler.use()` returns a disallowed item for a mount site, registration throws:
+
+```
+handler.use() returned middleware() which is not valid inside parallel().
+Allowed types: revalidate, loader, loading, errorBoundary, notFoundBoundary, transition.
+```
+
+The narrowest contract is `parallel()` — slots cannot bring their own middleware or layout; only data, loading, error/notFound boundaries, revalidation, and transitions.
+
+## Composition with explicit `use()`
+
+Every mount site that takes a `use` callback merges in this order:
+
+1. **`handler.use()` items first** — the handler's defaults.
+2. **Explicit `use()` items second** — overrides specified at the mount site.
+
+Items of the same kind from the explicit `use()` follow the existing override rules of that item type. The most important ones for composition:
+
+- **`loading()`** — last definition wins, so explicit `loading()` replaces the handler's default.
+- **`parallel({ "@slot": … })`** — the last `parallel()` call wins per slot name. Other slots from earlier calls are preserved (see `skills/parallel`).
+- **`loader()`, `middleware()`, etc.** — accumulate; both the handler's and the explicit ones run.
+
+Skip the boilerplate: if neither `handler.use` nor explicit `use()` is provided, no merge happens.
+
+```typescript
+// Handler brings a loader + a (placeholder) loading; explicit use replaces loading.
+const SidebarSlot: Handler = async (ctx) => {
+  const data = await ctx.use(SidebarLoader);
+  return <Sidebar data={data} />;
+};
+SidebarSlot.use = () => [
+  loader(SidebarLoader),
+  loading(<DefaultSidebarSkeleton />),
+];
+
+parallel({ "@sidebar": SidebarSlot }, () => [
+  // Replaces the default skeleton; SidebarLoader from handler.use still runs.
+  loading(<SiteSpecificSidebarSkeleton />),
+]);
+```
+
+## Composable parallel slots (the main pay-off)
+
+The parallel slot site is where `handler.use` shines. A slot handler that owns its data/loading lets a layout declare **just** the slot names — every loader, skeleton, and revalidation contract travels with the slot itself.
+
+### Without `handler.use` (every caller wires it up)
+
+```typescript
+layout(<DashboardLayout />, () => [
+  parallel({ "@cart": CartSummary }, () => [
+    loader(CartLoader),
+    loading(<CartSkeleton />),
+    revalidate(revalidateCartData),
+  ]),
+  parallel({ "@notifs": NotificationPanel }, () => [
+    loader(NotificationsLoader),
+    loading(<NotifsSkeleton />),
+    revalidate(revalidateNotifs),
+  ]),
+  path("/dashboard", DashboardIndex, { name: "dashboard.index" }),
+]);
+```
+
+Every layout that wants `@cart` must repeat the same loader/loading/revalidate triplet.
+
+### With `handler.use` (slot owns its dependencies)
+
+```typescript
+const CartSummary: Handler = async (ctx) => {
+  const cart = await ctx.use(CartLoader);
+  return <CartSummaryView cart={cart} />;
+};
+CartSummary.use = () => [
+  loader(CartLoader),
+  loading(<CartSkeleton />),
+  revalidate(revalidateCartData),
+];
+
+const NotificationPanel: Handler = async (ctx) => {
+  const items = await ctx.use(NotificationsLoader);
+  return <NotificationsView items={items} />;
+};
+NotificationPanel.use = () => [
+  loader(NotificationsLoader),
+  loading(<NotifsSkeleton />),
+  revalidate(revalidateNotifs),
+];
+
+// Mount sites become declarative — no per-call data wiring.
+layout(<DashboardLayout />, () => [
+  parallel({ "@cart": CartSummary, "@notifs": NotificationPanel }),
+  path("/dashboard", DashboardIndex, { name: "dashboard.index" }),
+]);
+
+layout(<AccountLayout />, () => [
+  // Same slot, same defaults, zero re-wiring.
+  parallel({ "@cart": CartSummary }),
+  path("/account", AccountIndex, { name: "account.index" }),
+]);
+```
+
+Each slot handler is now a portable, self-contained unit. Different layouts can use the same slot without copying data plumbing.
+
+### Streaming behavior is per-slot
+
+A slot's `loading()` (whether from `handler.use` or explicit) makes that slot an independent streaming unit — its loader does not block the parent layout. Two slot handlers with their own loading skeletons stream independently.
+
+```typescript
+parallel({
+  "@cart": CartSummary, // handler.use loading() → streams independently
+  "@cartBadge": CartBadge, // no loading() anywhere → awaited before paint
+});
+```
+
+### Two scopes for explicit `use` at the mount site: shared (broadcast) and slot-local
+
+`parallel()` accepts an explicit `use()` callback that **broadcasts** to every slot in the call ([dsl-helpers.ts](../../src/route-definition/dsl-helpers.ts)). That's the right behavior for the items the parallel allow-list permits and that accumulate (`loader`, `revalidate`, `errorBoundary`, `notFoundBoundary`, `transition`) — every slot gets them. (Note: `middleware` is not allowed inside `parallel()`; see the allowed-types table above.)
+
+For single-assignment items like `loading()`, broadcasting overwrites every slot's `handler.use` default. Pass a **slot descriptor** `{ handler, use }` instead: items in the descriptor's `use` apply only to that slot.
+
+```typescript
+parallel({
+  "@meta": MetaSlot,
+  "@sidebar": {
+    handler: SidebarSlot,
+    use: () => [loading(<SidebarSkeleton />)], // ← only @sidebar
+  },
+});
+```
+
+Per-slot merge order is **handler.use → shared use → slot-local use** (narrowest scope wins for last-write-wins items like `loading()`):
+
+```typescript
+parallel(
+  {
+    "@cart": {
+      handler: Cart,
+      use: () => [loading(<CartSkeleton />)], // wins for @cart
+    },
+    "@notifs": Notifs, // gets <BroadcastSkeleton />
+  },
+  () => [
+    loader(SharedAnalyticsLoader), // accumulates on every slot
+    loading(<BroadcastSkeleton />), // applies to slots without slot-local
+  ],
+);
+```
+
+Use the descriptor's `use` for `loading(false)` too — opting one slot out of streaming without affecting siblings:
+
+```typescript
+parallel(
+  {
+    "@cart": { handler: Cart, use: () => [loading(false)] }, // @cart awaits
+    "@notifs": Notifs, // @notifs still streams with broadcast skeleton
+  },
+  () => [loading(<BroadcastSkeleton />)],
+);
+```
+
+Rule of thumb: shared `use` is for items that legitimately apply to every slot. Slot-local `use` is for per-slot precision — especially `loading()` and `loading(false)`.
+
+### Replacing a whole slot from a parent's `handler.use`
+
+A handler can publish a default `parallel({...})` set via its `.use`, and the mount site can replace any individual slot by re-declaring it. Last `parallel()` per slot name wins (see `skills/parallel` § Slot Override Semantics).
+
+```typescript
+const ProductPage: Handler<"/product/:slug"> = (ctx) => (
+  <article>
+    <ProductHero slug={ctx.params.slug} />
+    <ParallelOutlet name="@related" />
+    <ParallelOutlet name="@reviews" />
+  </article>
+);
+ProductPage.use = () => [
+  parallel({
+    "@related": DefaultRelatedProducts,
+    "@reviews": DefaultReviews,
+  }),
+];
+
+path("/product/:slug", ProductPage, { name: "product" }, () => [
+  // Override @related only; @reviews keeps the default from handler.use.
+  parallel({ "@related": SiteSpecificRelated }),
+]);
+```
+
+## Other mount sites
+
+### Pages (`path()`)
+
+Page handlers can carry middleware, loaders, error boundaries, parallel slots, etc. — anything from the `path` row of the table above.
+
+```typescript
+const CheckoutPage: Handler<"/checkout"> = async (ctx) => { /* … */ };
+CheckoutPage.use = () => [
+  middleware(requireAuth),
+  loader(CartLoader),
+  errorBoundary(<CheckoutError />),
+  notFoundBoundary(<CheckoutNotFound />),
+];
+```
+
+### Layouts (`layout()`)
+
+Layout handlers can carry middleware that runs for every child route, plus default parallels, includes, etc.
+
+```typescript
+const AdminLayout: Handler = (ctx) => {
+  const user = ctx.get(CurrentUser);
+  return <Admin user={user} />;
+};
+AdminLayout.use = () => [
+  middleware(requireAdmin),
+  parallel({ "@adminNotifs": AdminNotifsSlot }),
+];
+```
+
+### Intercepts (`intercept()`)
+
+Intercept handlers can carry their own middleware chain, loaders, and even nested layouts/routes for the modal shell.
+
+```typescript
+const QuickViewModal: Handler = async (ctx) => {
+  const product = await ctx.use(ProductLoader);
+  return <QuickView product={product} />;
+};
+QuickViewModal.use = () => [
+  loader(ProductLoader),
+  loading(<QuickViewSkeleton />),
+  layout(<ModalChrome />),
+];
+```
+
+## `loading()` is a single-assignment item — scope it correctly
+
+Most `use` items accumulate when merged: `handler.use` `middleware()` runs _and_ explicit `middleware()` runs; both `loader()` registrations apply. `loading()` is different — it mutates `entry.loading` directly, last call wins ([dsl-helpers.ts `loadingFn`](../../src/route-definition/dsl-helpers.ts)).
+
+For pages, layouts, and intercepts that's straightforward: explicit `loading()` at the mount site replaces any `loading()` from `handler.use`. The merge order is `handler.use → explicit`, so the explicit one is the last writer and wins.
+
+For parallel slots, the shared `parallel(..., () => [...])` callback is **broadcast** to every slot in the call. A single `loading()` placed there lands on every slot, overwriting each slot's `handler.use` default. To scope `loading()` to one slot, use the **slot descriptor** form:
+
+```typescript
+const Cart: Handler = async (ctx) => { /* … */ };
+Cart.use = () => [loader(CartLoader), loading(<CartSkeleton />)];
+
+const Notifs: Handler = async (ctx) => { /* … */ };
+Notifs.use = () => [loader(NotifsLoader), loading(<NotifsSkeleton />)];
+
+// ✅ @cart gets a custom skeleton; @notifs keeps its handler.use default.
+parallel({
+  "@cart": {
+    handler: Cart,
+    use: () => [loading(<CustomCartSkeleton />)],
+  },
+  "@notifs": Notifs,
+});
+
+// ✅ Opt one slot out of streaming while siblings still stream the broadcast.
+parallel(
+  {
+    "@cart": { handler: Cart, use: () => [loading(false)] },
+    "@notifs": Notifs,
+  },
+  () => [loading(<BroadcastSkeleton />)],
+);
+```
+
+Per-slot merge order is **handler.use → shared use → slot-local use**. Slot-local is the narrowest scope, so it wins for last-write-wins items like `loading()`. Items that accumulate within the parallel allow-list (`loader`, `revalidate`, `errorBoundary`, `notFoundBoundary`, `transition`) compose across all three layers regardless.
+
+Other things to keep in mind about `loading()`:
+
+- Any `loading()` (regardless of source) makes the segment a streaming unit. A handler that includes `loading()` in its `.use` opts every mount site into streaming by default. To opt back out, pass `loading(false)` at the mount site (`loading: false` handling in [match-middleware/segment-resolution.ts](../../src/router/match-middleware/segment-resolution.ts)) — use the slot descriptor form for parallel slots so the opt-out doesn't broadcast.
+
+Rule of thumb: only put `loading()` in `handler.use` if you genuinely want every mount site to stream by default. Use the slot descriptor's `use` for any per-slot intent at a `parallel()` call.
+
+## Edge cases & gotchas
+
+- **ReactNode handlers cannot have `.use`.** A bare JSX element passed as a handler (e.g., `path("/about", <About />)`) has no function to attach properties to. Pass a function or branded definition instead.
+- **Branded handlers** — `Static()`, `Prerender()`, and `Passthrough()` are positional constructors (not object-arg). Construct first, then attach `.use` to the returned definition:
+
+  ```typescript
+  const ProductPage = Prerender(async (ctx) => {
+    const product = await fetchProduct(ctx.params.slug);
+    return <ProductView product={product} />;
+  });
+  ProductPage.use = () => [loader(ProductLoader)];
+  ```
+
+- **Items can be flat or nested arrays.** `handler.use()` results are flattened with `.flat(3)` before validation, so factory helpers that return arrays inline work the same as in regular `use()` callbacks.
+- **Validation runs at registration / first match**, not at handler definition. A handler doesn't know its mount site at definition time — the same handler used in a `path()` and an `intercept()` is validated against each mount's allowed-types set when registered.
+- **No silent shadowing.** If a disallowed item slips through (e.g., a layout factory returning `cache()` from a slot's `handler.use`), the runtime throws with the offending type and mount site named.
+
+## Cross-references
+
+- `skills/route` — `path()` mount site basics
+- `skills/layout` — `layout()` mount site basics
+- `skills/parallel` — parallel slot semantics, slot override rules, streaming behavior
+- `skills/intercept` — intercept mount site basics
+- `skills/loader` — defining `createLoader` and reading via `ctx.use()`
+- `skills/middleware` — middleware semantics and ordering

package/skills/intercept/SKILL.md

@@ -311,3 +311,23 @@ export const shopPatterns = urls(({
   ]),
 ]);
 ```
+
+## Handler-attached `.use`
+
+Intercept handlers can carry their own middleware, loaders, loading state, error/notFound boundaries, and even nested `layout`/`route`/`when` defaults via `.use` — useful for self-contained modal components that travel with their own data and chrome.
+
+```typescript
+const QuickViewModal: Handler = async (ctx) => {
+  const product = await ctx.use(ProductLoader);
+  return <QuickView product={product} />;
+};
+QuickViewModal.use = () => [
+  loader(ProductLoader),
+  loading(<QuickViewSkeleton />),
+  layout(<ModalChrome />),
+];
+
+intercept("@modal", "product", QuickViewModal);
+```
+
+Explicit `use()` at the mount site merges with `handler.use` (handler defaults first, explicit second). See [skills/handler-use](../handler-use/SKILL.md) for merge order and the per-mount-site allowed-types table.

package/skills/layout/SKILL.md

@@ -308,3 +308,25 @@ export const shopPatterns = urls(({ path, layout, parallel, loader, revalidate }
   ]),
 ]);
 ```
+
+## Handler-attached `.use`
+
+Layout handlers can carry their own middleware, default parallels, and includes via `.use` so a layout becomes a self-contained unit reusable across mount sites.
+
+```typescript
+const AdminLayout: Handler = (ctx) => {
+  const user = ctx.get(CurrentUser);
+  return <Admin user={user} />;
+};
+AdminLayout.use = () => [
+  middleware(requireAdmin),
+  parallel({ "@adminNotifs": AdminNotifsSlot }),
+];
+
+// Mount site declares structure only; defaults travel with the layout.
+layout(AdminLayout, () => [
+  path("/admin", AdminIndex, { name: "admin.index" }),
+]);
+```
+
+Allowed item types in a layout's `.use` mirror the layout `use()` callback (the broadest set). Explicit `use()` at the mount site merges with `handler.use` (handler defaults first, explicit second). See [skills/handler-use](../handler-use/SKILL.md) for merge order and per-mount-site allowed types.

package/skills/parallel/SKILL.md

@@ -206,6 +206,65 @@ parallel(
 )
 ```
 
+## Composable Slots via `handler.use`
+
+Slot handlers can carry their own loader, loading, error/notFound boundaries, revalidation, and transition defaults via `.use`. The mount site then declares **just the slot names** — no per-call data wiring.
+
+```typescript
+const CartSummary: Handler = async (ctx) => {
+  const cart = await ctx.use(CartLoader);
+  return <CartSummaryView cart={cart} />;
+};
+CartSummary.use = () => [
+  loader(CartLoader),
+  loading(<CartSkeleton />),
+  revalidate(revalidateCartData),
+];
+
+// Same slot, no copy-pasted plumbing across layouts.
+layout(<DashboardLayout />, () => [
+  parallel({ "@cart": CartSummary }),
+  path("/dashboard", DashboardIndex, { name: "dashboard.index" }),
+]);
+
+layout(<AccountLayout />, () => [
+  parallel({ "@cart": CartSummary }),
+  path("/account", AccountIndex, { name: "account.index" }),
+]);
+```
+
+A slot's `loading()` (whether from `handler.use` or explicit) makes that slot an independent streaming unit, exactly as in the **Streaming Behavior** section above.
+
+The `parallel` mount site has the narrowest allow-list for `handler.use` items — slots cannot bring their own middleware or layout, only `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, and `transition`. See [skills/handler-use](../handler-use/SKILL.md) for the full table and merge rules.
+
+### Two scopes for explicit `use`: shared (broadcast) and slot-local
+
+`parallel({...slots}, () => [...use])` runs the shared `use()` callback **once per slot** ([dsl-helpers.ts](../../src/route-definition/dsl-helpers.ts)) — items in that callback land on every slot's entry. That's the right behavior for the items the parallel allow-list permits and that accumulate (`loader`, `revalidate`, `errorBoundary`, `notFoundBoundary`, `transition`). (Slots cannot bring `middleware` or `layout` — see the allowed-types note above.)
+
+For single-assignment items like `loading()`, broadcasting overwrites every slot's `handler.use` default. Pass a **slot descriptor** `{ handler, use }` instead — items in the descriptor's `use` apply only to that slot:
+
+```typescript
+// @cart gets a custom skeleton; @notifs keeps its handler.use default.
+parallel({
+  "@cart": {
+    handler: Cart,
+    use: () => [loading(<CustomCartSkeleton />)],
+  },
+  "@notifs": Notifs,
+});
+
+// Opt one slot out of streaming while siblings still stream the broadcast.
+parallel(
+  {
+    "@cart": { handler: Cart, use: () => [loading(false)] },
+    "@notifs": Notifs,
+  },
+  () => [loading(<BroadcastSkeleton />)],
+);
+```
+
+Per-slot merge order is **handler.use → shared use → slot-local use**. Slot-local is the narrowest scope, so it wins for last-write-wins items. See [skills/handler-use § `loading()` is a single-assignment item — scope it correctly](../handler-use/SKILL.md#loading-is-a-single-assignment-item--scope-it-correctly) for the full reasoning.
+
 ## Slot Override Semantics
 
 When multiple `parallel()` calls define the same slot name, **the last

package/skills/route/SKILL.md

@@ -383,6 +383,30 @@ urls(({ path, layout }) => [
 ])
 ```
 
+## Handler-attached `.use`
+
+Page handlers can carry their own loader, middleware, error boundaries, parallels, and other defaults via a `.use` callback — so the page is self-contained and reusable across mount sites without re-wiring the same items.
+
+```typescript
+const ProductPage: Handler<"/product/:slug"> = async (ctx) => {
+  const product = await ctx.use(ProductLoader);
+  return <ProductView product={product} />;
+};
+ProductPage.use = () => [
+  loader(ProductLoader),
+  loading(<ProductSkeleton />),
+  middleware(async (ctx, next) => {
+    await next();
+    ctx.header("Cache-Control", "private, max-age=60");
+  }),
+];
+
+// Mount site has no per-page wiring — defaults travel with the handler.
+path("/product/:slug", ProductPage, { name: "product" });
+```
+
+Explicit `use()` at the mount site merges with `handler.use` (handler defaults first, explicit second). See [skills/handler-use](../handler-use/SKILL.md) for the merge order, allowed item types per mount site, and override semantics.
+
 ## Complete Example
 
 ```typescript

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

@@ -491,13 +491,25 @@ const parallel: RouteHelpers<any, any>["parallel"] = (slots, use) => {
 
   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;
@@ -564,13 +576,25 @@ const parallel: RouteHelpers<any, any>["parallel"] = (slots, use) => {
           }),
     } satisfies EntryData;
 
-    // Per-slot: handler.use defaults first, then explicit use second.
-    // This matches the "defaults first, overrides second" rule used by
-    // path(), layout(), and intercept(). Each slot's handler.use is
-    // scoped to its own entry (no cross-slot bleed).
-    const slotHandler = (slots as Record<string, any>)[slotName];
-    const slotHandlerUse = resolveHandlerUse(slotHandler);
-    const slotMergedUse = mergeHandlerUse(slotHandlerUse, use, "parallel");
+    // 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) {
       const result = store.run(namespace, slotEntry, slotMergedUse)?.flat(3);
       invariant(
@@ -584,6 +608,28 @@ const parallel: RouteHelpers<any, any>["parallel"] = (slots, use) => {
   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
  */

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

@@ -123,7 +123,7 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *   "@main": async (ctx) => <MainContent data={ctx.use(DataLoader)} />,
    * })
    *
-   * // With loaders and loading states
+   * // With loaders and loading states (broadcast to every slot)
    * parallel({
    *   "@analytics": AnalyticsPanel,
    *   "@metrics": MetricsPanel,
@@ -131,12 +131,36 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *   loader(DashboardLoader),
    *   loading(<DashboardSkeleton />),
    * ])
+   *
+   * // Per-slot scoped use via slot descriptor — for single-assignment items
+   * // like loading() that should not broadcast to siblings.
+   * parallel({
+   *   "@meta": MetaSlot,
+   *   "@sidebar": {
+   *     handler: SidebarSlot,
+   *     use: () => [loading(<SidebarSkeleton />)],
+   *   },
+   * })
    * ```
    * @param slots - Object with slot names (prefixed with @) mapped to handlers
+   *                or `{ handler, use? }` slot descriptors.
    * @param use - Optional callback for loaders, loading, revalidate, etc.
+   *              Items here apply to every slot in the call (broadcast).
+   *              For per-slot single-assignment items, use the slot descriptor's
+   *              own `use` callback — slot-local items run after the broadcast,
+   *              so they take precedence on `loading()` and other last-write-wins
+   *              fields.
    */
   parallel: <
-    TSlots extends Record<`@${string}`, Handler<any, any, TEnv> | ReactNode>,
+    TSlots extends Record<
+      `@${string}`,
+      | Handler<any, any, TEnv>
+      | ReactNode
+      | {
+          handler: Handler<any, any, TEnv> | ReactNode;
+          use?: () => UseItems<ParallelUseItem>;
+        }
+    >,
   >(
     slots: TSlots,
     use?: () => UseItems<ParallelUseItem>,

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

@@ -233,12 +233,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,