toiljs 0.0.8 → 0.0.9

package/src/client/navigation/navigation.ts

@@ -3,6 +3,9 @@
  * the per-entry history keys used for scroll restoration. Consumed by `useLocation` (to re-render),
  * `Link` / `navigate` (to change location), and `Router` (which calls `applyScroll` after commit).
  */
+import { startTransition } from 'react';
+import { flushSync } from 'react-dom';
+
 import {
     enableManualScrollRestoration,
     planScroll,
@@ -13,6 +16,26 @@ import type { Href } from '../types.js';
 const listeners = new Set<() => void>();
 let popstateBound = false;
 
+/** `document.startViewTransition`, present only where the View Transitions API is supported. */
+interface ViewTransitionDocument {
+    startViewTransition?: (callback: () => void) => unknown;
+}
+let viewTransitions = false;
+
+/** Enables animated View Transitions for navigation. Called once by `mount` from `client.viewTransitions`. */
+export function setViewTransitions(enabled: boolean): void {
+    viewTransitions = enabled;
+}
+
+/** Whether the current navigation should animate via the View Transitions API. */
+function shouldViewTransition(): boolean {
+    if (!viewTransitions || typeof document === 'undefined' || typeof window === 'undefined') {
+        return false;
+    }
+    if (typeof (document as ViewTransitionDocument).startViewTransition !== 'function') return false;
+    return !window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+
 interface ToilHistoryState {
     __toilKey?: string;
 }
@@ -23,11 +46,51 @@ function nextKey(): string {
     return `t${String(keyCounter)}`;
 }
 
-/** Notifies every subscriber that the location may have changed. */
-function notify(): void {
+function runListeners(): void {
     for (const listener of listeners) listener();
 }
 
+/**
+ * Re-renders subscribers for a location change. Normally wrapped in `startTransition` (smooth: the
+ * current page stays while the next route loads). When View Transitions are enabled and supported,
+ * the commit runs synchronously inside `document.startViewTransition` so the browser animates the
+ * old and new DOM (a crossfade, or shared-element transitions via `view-transition-name`).
+ */
+function notify(): void {
+    if (shouldViewTransition()) {
+        (document as ViewTransitionDocument).startViewTransition?.(() => {
+            flushSync(runListeners);
+        });
+    } else {
+        startTransition(runListeners);
+    }
+}
+
+// Soft vs hard navigation, for intercepting routes. The initial page load (and any full refresh) is
+// "hard"; client navigations (`navigate` / back / forward) are "soft". `previousPath` is the path we
+// were on before the latest soft navigation, the route the main view keeps showing while an
+// intercepting route fills a slot (the modal overlay).
+let softNav = false;
+let currentPath = typeof window === 'undefined' ? '/' : window.location.pathname;
+let previousPath = currentPath;
+
+/** Records a transition to the live location; `soft` is false only for the initial load. */
+function recordTransition(soft: boolean): void {
+    previousPath = currentPath;
+    currentPath = typeof window === 'undefined' ? '/' : window.location.pathname;
+    softNav = soft;
+}
+
+/** Whether the current location was reached by a client navigation (not an initial load / refresh). */
+export function isSoftNavigation(): boolean {
+    return softNav;
+}
+
+/** The path the app was on before the latest navigation (what the main view keeps during an intercept). */
+export function previousPathname(): string {
+    return previousPath;
+}
+
 // Navigation-pending tracking: a navigation is "pending" from when it starts until the new route
 // commits. Drives useNavigationPending() (e.g. a top loading bar).
 let startedTick = 0;
@@ -54,7 +117,7 @@ export function isNavigationPending(): boolean {
     return startedTick !== committedTick;
 }
 
-/** Monotonic id incremented on each navigation — used to key/revalidate per-navigation route data. */
+/** Monotonic id incremented on each navigation, used to key/revalidate per-navigation route data. */
 export function navigationEpoch(): number {
     return startedTick;
 }
@@ -103,6 +166,7 @@ export function navigate(href: Href, options?: NavigateOptions): void {
         currentKey = nextKey();
         window.history.pushState({ __toilKey: currentKey }, '', href);
     }
+    recordTransition(true);
     planScroll({ hash, toTop: options?.scroll !== false });
     notify();
 }
@@ -117,8 +181,13 @@ export function forward(): void {
     window.history.forward();
 }
 
-/** Re-renders the current route without changing the URL (there is no server data to refetch). */
+/**
+ * Re-renders the current route, bumping the navigation epoch so a revalidation of the *same* URL
+ * re-keys its Suspense boundary (its `loading.tsx` shows while the loader re-runs) and
+ * `useNavigationPending` reports the in-flight refetch, instead of silently freezing the old page.
+ */
 export function refresh(): void {
+    beginNavigation();
     notify();
 }
 
@@ -128,6 +197,7 @@ function handlePopState(event: PopStateEvent): void {
     rememberScroll(currentKey);
     const state = event.state as ToilHistoryState | null;
     currentKey = state?.__toilKey ?? 'initial';
+    recordTransition(true);
     planScroll({ restoreKey: currentKey, hash: window.location.hash, toTop: false });
     notify();
 }

package/src/client/navigation/prefetch.ts

@@ -45,7 +45,7 @@ function warm(route: RouteDef): void {
 
 /**
  * Prefetches the route chunk for an internal `href` so a later navigation resolves instantly.
- * No-op for external, unknown, or already-prefetched targets — safe to call from anywhere,
+ * No-op for external, unknown, or already-prefetched targets, safe to call from anywhere,
  * including before an imperative {@link navigate} (e.g. `prefetch('/dashboard')` on hover/intent).
  */
 export function prefetch(href: string): void {
@@ -83,7 +83,7 @@ function shouldSkipForConnection(): boolean {
 
 /**
  * Starts idle-time prefetching of internal links. As each `<a>` pointing at a known route scrolls
- * into view (or near it — 200px margin) its chunk is warmed once; links added later by client
+ * into view (or near it, 200px margin) its chunk is warmed once; links added later by client
  * navigation are picked up via a MutationObserver. Called by {@link mount}; runs once per app.
  */
 export function startPrefetcher(routes: RouteDef[]): void {

package/src/client/routing/Router.tsx

@@ -11,8 +11,15 @@ import {
 } from './lazy.js';
 import { loaderKey, LoaderDataContext, readRouteData } from './loader.js';
 import { matchRoute, type RouteParams } from './match.js';
+import { useRouteHead } from '../head/head.js';
 import { ParamsContext } from './params-context.js';
-import { navigationEpoch, settleNavigation } from '../navigation/navigation.js';
+import { SlotContext } from './slot-context.js';
+import {
+    isSoftNavigation,
+    navigationEpoch,
+    previousPathname,
+    settleNavigation,
+} from '../navigation/navigation.js';
 import { applyScroll } from '../navigation/scroll.js';
 import type { ErrorComponentLoader, LayoutLoader, NotFoundLoader, RouteDef } from '../types.js';
 
@@ -23,18 +30,99 @@ function RoutePage(props: {
     dataKey: string;
     epoch: number;
 }): ReactNode {
-    const { Component, data } = readRouteData(props.route, props.params, props.dataKey, props.epoch);
+    const { Component, data, head } = readRouteData(props.route, props.params, props.dataKey, props.epoch);
+    useRouteHead(head);
     return <LoaderDataContext.Provider value={data}>{createElement(Component)}</LoaderDataContext.Provider>;
 }
 
+/**
+ * Wraps a matched route's page in its loading boundary, templates, nested layouts, and error
+ * boundary. `keyPrefix` namespaces the loader-cache key and boundary keys so a parallel slot and the
+ * main route can match the same URL without colliding.
+ */
+function renderMatched(
+    matched: RouteDef,
+    params: RouteParams,
+    pathname: string,
+    epoch: number,
+    keyPrefix: string,
+): ReactNode {
+    const search = typeof window === 'undefined' ? '' : window.location.search;
+    const dataKey = keyPrefix + loaderKey(pathname, search);
+    const fallback: ReactNode = matched.loading
+        ? createElement(Suspense, { fallback: null }, createElement(loadingComponent(matched.loading)))
+        : null;
+
+    // A route with a `loading.tsx` keys its boundary per URL *and* navigation epoch, so its fallback
+    // shows even inside the transition, on first nav and on an in-place revalidate of the same URL
+    // (the epoch bumps). A route without one keeps a stable boundary so the transition holds the old
+    // page. The loader cache key stays the bare URL, so the boundary remount still reuses cached data.
+    let content: ReactNode = (
+        <Suspense
+            key={matched.loading ? `${dataKey}:${String(epoch)}` : undefined}
+            fallback={fallback}>
+            <RoutePage
+                route={matched}
+                params={params}
+                dataKey={dataKey}
+                epoch={epoch}
+            />
+        </Suspense>
+    );
+    // Templates wrap inside the layouts and re-mount on every navigation (keyed by URL).
+    const templates = matched.templates ?? [];
+    for (let i = templates.length - 1; i >= 0; i--) {
+        const Template = nestedLayout(templates[i]);
+        content = (
+            <Suspense
+                key={`${keyPrefix}${pathname}:${String(i)}`}
+                fallback={null}>
+                <Template>{content}</Template>
+            </Suspense>
+        );
+    }
+    // Nested layouts, deepest first so the shallowest ends up outermost.
+    const chain = matched.layouts ?? [];
+    for (let i = chain.length - 1; i >= 0; i--) {
+        const NestedLayout = nestedLayout(chain[i]);
+        content = (
+            <Suspense fallback={null}>
+                <NestedLayout>{content}</NestedLayout>
+            </Suspense>
+        );
+    }
+    if (matched.errorComponent) {
+        content = <ErrorBoundary fallback={errorComponent(matched.errorComponent)}>{content}</ErrorBoundary>;
+    }
+    return content;
+}
+
+/**
+ * Finds the first route (already specificity-sorted) matching `pathname`. Intercepting routes are
+ * skipped unless `allowIntercept`, they only apply on soft navigation.
+ */
+function match(
+    routes: RouteDef[],
+    pathname: string,
+    allowIntercept = true,
+): { route: RouteDef; params: RouteParams } | null {
+    for (const route of routes) {
+        if (route.intercept && !allowIntercept) continue;
+        const params = matchRoute(route.pattern, pathname);
+        if (params) return { route, params };
+    }
+    return null;
+}
+
 /** Matches the current location to a route and renders it, optionally wrapped in the root layout. */
 export function Router(props: {
     routes: RouteDef[];
     layout?: LayoutLoader;
     notFound?: NotFoundLoader;
     globalError?: ErrorComponentLoader;
+    slots?: Record<string, RouteDef[]>;
 }): ReactNode {
-    const { routes, layout = null, notFound = null, globalError = null } = props;
+    const { routes, layout = null, notFound = null, globalError = null, slots = {} } = props;
     const pathname = useLocation();
 
     // After each navigation commits, apply the planned scroll (top / restore / #hash) and mark the
@@ -44,71 +132,33 @@ export function Router(props: {
         settleNavigation();
     });
 
-    let matched: RouteDef | undefined;
-    let params: RouteParams = {};
-    for (const route of routes) {
-        const result = matchRoute(route.pattern, pathname);
-        if (result) {
-            matched = route;
-            params = result;
-            break;
-        }
+    const epoch = navigationEpoch();
+    const soft = isSoftNavigation();
+
+    // Parallel slots: each `@slot` tree matches the current URL independently (intercepting routes
+    // only on soft navigation). Each match is exposed by name via SlotContext and rendered wherever a
+    // layout/page places a `Slot`. If an intercepting route matches, the main view holds the previous
+    // page (the backdrop) while the slot shows the intercepted route, i.e. a modal overlay.
+    const slotElements: Record<string, ReactNode> = {};
+    let intercepting = false;
+    for (const [name, defs] of Object.entries(slots)) {
+        const slotMatch = match(defs, pathname, soft);
+        if (!slotMatch) continue;
+        if (slotMatch.route.intercept) intercepting = true;
+        slotElements[name] = (
+            <ParamsContext.Provider value={slotMatch.params}>
+                {renderMatched(slotMatch.route, slotMatch.params, pathname, epoch, `@${name} `)}
+            </ParamsContext.Provider>
+        );
     }
 
+    const mainPath = intercepting ? previousPathname() : pathname;
+    const matched = match(routes, mainPath);
+    const params: RouteParams = matched?.params ?? {};
+
     let content: ReactNode;
     if (matched) {
-        const fallback: ReactNode = matched.loading
-            ? createElement(Suspense, { fallback: null }, createElement(loadingComponent(matched.loading)))
-            : null;
-        const search = typeof window === 'undefined' ? '' : window.location.search;
-        const dataKey = loaderKey(pathname, search);
-        // Navigation runs in a transition (smooth — the old page stays during load). A route with a
-        // `loading.tsx` opts into an immediate loading state: keying its Suspense boundary per URL
-        // makes React show the fallback even inside the transition. Routes without one keep a stable
-        // boundary, so the transition holds the previous page instead of flashing a blank fallback.
-        content = (
-            <Suspense
-                key={matched.loading ? dataKey : undefined}
-                fallback={fallback}>
-                <RoutePage
-                    route={matched}
-                    params={params}
-                    dataKey={dataKey}
-                    epoch={navigationEpoch()}
-                />
-            </Suspense>
-        );
-        // Wrap in templates, deepest first so the shallowest ends up outermost. Templates sit
-        // inside the layouts and are keyed by pathname so they re-mount on every navigation
-        // (resetting their state), unlike layouts which persist across navigations.
-        const templates = matched.templates ?? [];
-        for (let i = templates.length - 1; i >= 0; i--) {
-            const Template = nestedLayout(templates[i]);
-            content = (
-                <Suspense
-                    key={`${pathname}:${String(i)}`}
-                    fallback={null}>
-                    <Template>{content}</Template>
-                </Suspense>
-            );
-        }
-        // Wrap in nested layouts, deepest first so the shallowest ends up outermost.
-        const chain = matched.layouts ?? [];
-        for (let i = chain.length - 1; i >= 0; i--) {
-            const NestedLayout = nestedLayout(chain[i]);
-            content = (
-                <Suspense fallback={null}>
-                    <NestedLayout>{content}</NestedLayout>
-                </Suspense>
-            );
-        }
-        if (matched.errorComponent) {
-            content = (
-                <ErrorBoundary fallback={errorComponent(matched.errorComponent)}>
-                    {content}
-                </ErrorBoundary>
-            );
-        }
+        content = renderMatched(matched.route, matched.params, mainPath, epoch, '');
     } else if (notFound) {
         const NotFound = resolveNotFound(notFound);
         content = (
@@ -117,7 +167,7 @@ export function Router(props: {
             </Suspense>
         );
     } else {
-        content = <div style={{ padding: 24, fontFamily: 'system-ui' }}>404 — Not found</div>;
+        content = <div style={{ padding: 24, fontFamily: 'system-ui' }}>404, Not found</div>;
     }
 
     if (layout) {
@@ -130,10 +180,14 @@ export function Router(props: {
     }
 
     // The root error boundary (global-error.tsx) sits outside the root layout, so it catches
-    // errors thrown by the layout itself — the last line of defense before a blank screen.
+    // errors thrown by the layout itself, the last line of defense before a blank screen.
     if (globalError) {
         content = <ErrorBoundary fallback={errorComponent(globalError)}>{content}</ErrorBoundary>;
     }
 
-    return <ParamsContext.Provider value={params}>{content}</ParamsContext.Provider>;
+    return (
+        <ParamsContext.Provider value={params}>
+            <SlotContext.Provider value={slotElements}>{content}</SlotContext.Provider>
+        </ParamsContext.Provider>
+    );
 }

package/src/client/routing/action.ts

@@ -1,5 +1,5 @@
 /**
- * Mutations (writes) — the counterpart to loaders (reads). A loader fetches data on navigation;
+ * Mutations (writes), the counterpart to loaders (reads). A loader fetches data on navigation;
  * an action performs a write (save, delete, a server/WASM call) on demand, then revalidates the
  * affected loader data so the UI reflects the change. `useAction` tracks pending/error/result state;
  * `<Form>` is sugar over it for the form case.
@@ -12,9 +12,9 @@ import type { Href } from '../types.js';
 
 /**
  * Which loader data to refetch after an action succeeds:
- * - `true` (default) — the current route.
- * - an `Href` (or array) — those specific routes.
- * - `false` — nothing.
+ * - `true` (default), the current route.
+ * - an `Href` (or array), those specific routes.
+ * - `false`, nothing.
  */
 export type RevalidateTarget = boolean | Href | readonly Href[];
 

package/src/client/routing/error-boundary.tsx

@@ -12,7 +12,7 @@ interface ErrorBoundaryState {
 
 /**
  * Catches render errors in its subtree and shows the route's `error.tsx` (with a `reset` to retry).
- * Error boundaries must be class components — React has no hook equivalent.
+ * Error boundaries must be class components, React has no hook equivalent.
  */
 export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
     state: ErrorBoundaryState = { error: null };

package/src/client/routing/hooks.ts

@@ -2,14 +2,7 @@
  * Router hooks for user route components: read the params / pathname / search params, navigate
  * imperatively, and grab a router handle.
  */
-import {
-    startTransition,
-    useContext,
-    useEffect,
-    useMemo,
-    useReducer,
-    useSyncExternalStore,
-} from 'react';
+import { useContext, useEffect, useMemo, useReducer, useSyncExternalStore } from 'react';
 
 import type { RouteParams } from './match.js';
 import {
@@ -84,25 +77,13 @@ export function useRouter(): RouterInstance {
 
 /**
  * Subscribes to location changes and reads the live `window.location` on render. Re-renders on any
- * pathname, search, or hash change.
- *
- * The update runs in a `startTransition` so navigation is smooth: React keeps the current page on
- * screen while the next route's chunk/data load, instead of flashing a blank fallback. Routes that
- * define a `loading.tsx` opt back into an immediate loading state — the Router keys their Suspense
- * boundary per navigation, so the fallback shows even within the transition (no frozen page). Warm
- * routes (prefetched, no loader) render synchronously and commit instantly.
+ * pathname, search, or hash change. The re-render is orchestrated by `navigate`/`notify` (wrapped in
+ * `startTransition` for smooth nav, or `document.startViewTransition` when enabled), so the listener
+ * itself is a plain force-update.
  */
 function useLocationSubscription(): void {
     const [, forceUpdate] = useReducer((n: number): number => n + 1, 0);
-    useEffect(
-        () =>
-            subscribeLocation(() => {
-                startTransition(() => {
-                    forceUpdate();
-                });
-            }),
-        [],
-    );
+    useEffect(() => subscribeLocation(forceUpdate), []);
 }
 
 /** Subscribes to and returns the current `location.pathname`. */
@@ -123,7 +104,7 @@ export function useSearchParams(): URLSearchParams {
     return useMemo(() => new URLSearchParams(search), [search]);
 }
 
-/** True while a navigation is in flight (started but not yet committed) — e.g. for a loading bar. */
+/** True while a navigation is in flight (started but not yet committed), e.g. for a loading bar. */
 export function useNavigationPending(): boolean {
     return useSyncExternalStore(
         subscribePending,

package/src/client/routing/loader.ts

@@ -12,6 +12,8 @@
  */
 import { createContext, useContext, type ComponentType } from 'react';
 
+import type { HeadSpec } from '../head/head.js';
+import { resolveMetadata, type GenerateMetadata, type Metadata } from '../head/metadata.js';
 import { refresh as rerender } from '../navigation/navigation.js';
 import type { RouteDef } from '../types.js';
 import type { RouteParams } from './match.js';
@@ -40,10 +42,14 @@ interface RouteModule {
     default: ComponentType;
     loader?: LoaderFunction;
     revalidate?: Revalidate;
+    metadata?: Metadata;
+    generateMetadata?: GenerateMetadata;
 }
 interface RouteData {
     Component: ComponentType;
     data: unknown;
+    /** Resolved baseline head from the route's `metadata` / `generateMetadata`, if any. */
+    head?: HeadSpec;
 }
 interface Entry {
     status: 'pending' | 'done' | 'error';
@@ -56,14 +62,14 @@ interface Entry {
     revalidate: Revalidate;
     /** Navigation epoch at which this entry was (re)fetched. */
     epoch: number;
-    /** Whether the route exports a `loader` — a route without one has no data that can change. */
+    /** Whether the route exports a `loader`, a route without one has no data that can change. */
     hasLoader: boolean;
 }
 
 const cache = new Map<string, Entry>();
 const MAX_ENTRIES = 32;
 
-/** Cache key for a URL: path + query (hash is ignored — it never changes loader data). */
+/** Cache key for a URL: path + query (hash is ignored, it never changes loader data). */
 export function loaderKey(pathname: string, search: string): string {
     return `${pathname}${search}`;
 }
@@ -78,8 +84,14 @@ async function loadRoute(
         typeof window === 'undefined' ? '' : window.location.search,
     );
     const data = mod.loader ? await mod.loader({ params, searchParams }) : undefined;
+    let head: HeadSpec | undefined;
+    if (mod.generateMetadata) {
+        head = resolveMetadata(await mod.generateMetadata({ params, searchParams, data }));
+    } else if (mod.metadata) {
+        head = resolveMetadata(mod.metadata);
+    }
     return {
-        data: { Component: mod.default, data },
+        data: { Component: mod.default, data, head },
         revalidate: mod.revalidate ?? 0,
         hasLoader: mod.loader != null,
     };
@@ -88,7 +100,7 @@ async function loadRoute(
 /** Whether a settled entry must be refetched for the current navigation. */
 function isStale(entry: Entry, epoch: number): boolean {
     if (entry.status === 'error') return true; // always retry a failed load
-    // A route with no loader has no data that can change — keep it cached so repeat navigations
+    // A route with no loader has no data that can change, keep it cached so repeat navigations
     // render synchronously (instant) instead of re-suspending and remounting on every switch.
     if (!entry.hasLoader) return false;
     if (entry.revalidate === false) return false; // cache forever
@@ -170,7 +182,7 @@ function keyForHref(href: string): string | undefined {
 /**
  * Invalidates cached loader data so it refetches on the next render. With no argument, clears every
  * route; with an `href`, clears just that route's entry. Pair with a re-render (the active route
- * refetches and suspends) — see {@link revalidate}.
+ * refetches and suspends), see {@link revalidate}.
  */
 export function invalidateLoaderData(href?: string): void {
     if (href === undefined) {
@@ -197,14 +209,14 @@ export const LoaderDataContext = createContext<unknown>(undefined);
 /**
  * The data returned by the active route's `loader`. Three ways to type it, easiest first:
  *
- * 1. **Pass the loader** — zero generics, fully inferred from your loader's return:
+ * 1. **Pass the loader**, zero generics, fully inferred from your loader's return:
  *    `const data = useLoaderData(loader);`
  * 2. Pass `typeof loader` as a type argument: `useLoaderData<typeof loader>();`
  * 3. Pass an explicit shape: `useLoaderData<Post>();`
  *
- * With no argument and no type, it returns `unknown` (never `any`) — so the data is there at runtime,
+ * With no argument and no type, it returns `unknown` (never `any`), so the data is there at runtime,
  * but you must annotate or narrow before using it. There's no way to infer the type from a bare call:
- * TypeScript can't tell which file (and so which `loader`) the call belongs to — hence option 1.
+ * TypeScript can't tell which file (and so which `loader`) the call belongs to, hence option 1.
  */
 export function useLoaderData<L extends LoaderFunction>(loader: L): Awaited<ReturnType<L>>;
 export function useLoaderData<T = unknown>(): LoaderData<T>;

package/src/client/routing/mount.tsx

@@ -1,5 +1,11 @@
 import { createRoot } from 'react-dom/client';
 
+import {
+    DevErrorBoundary,
+    DevErrorOverlay,
+    initDevErrorOverlay,
+    isDevMode,
+} from '../dev/error-overlay.js';
 import { initNavigation } from '../navigation/navigation.js';
 import { startPrefetcher } from '../navigation/prefetch.js';
 import { Router } from './Router.js';
@@ -14,17 +20,33 @@ export function mount(
     layout: LayoutLoader = null,
     notFound: NotFoundLoader = null,
     globalError: ErrorComponentLoader = null,
+    slots: Record<string, RouteDef[]> = {},
 ): void {
     const el = document.getElementById('root');
     if (!el) throw new Error('toil: #root element not found');
     initNavigation();
-    createRoot(el).render(
+    const app = (
         <Router
             routes={routes}
             layout={layout}
             notFound={notFound}
             globalError={globalError}
-        />,
+            slots={slots}
+        />
     );
-    startPrefetcher(routes);
+    // In dev, wrap the app in the error overlay so uncaught render/async errors surface on screen
+    // (not a blank page). In production it's omitted entirely.
+    if (isDevMode()) {
+        initDevErrorOverlay();
+        createRoot(el).render(
+            <>
+                <DevErrorBoundary>{app}</DevErrorBoundary>
+                <DevErrorOverlay />
+            </>,
+        );
+    } else {
+        createRoot(el).render(app);
+    }
+    // Prefetch across the main tree and every slot tree (one prefetcher owns the whole table).
+    startPrefetcher([...routes, ...Object.values(slots).flat()]);
 }

package/src/client/routing/slot-context.ts

@@ -0,0 +1,7 @@
+/**
+ * Context carrying the rendered element for each parallel-route slot (`@slot`), keyed by name.
+ * Provided by the Router for the current URL, consumed by {@link Slot}.
+ */
+import { createContext, type ReactNode } from 'react';
+
+export const SlotContext = createContext<Record<string, ReactNode>>({});

package/src/client/types.ts

@@ -12,7 +12,7 @@ import type { ComponentType, ReactNode } from 'react';
 export interface Register {}
 
 /**
- * Union of the project's route paths — static routes as literals, dynamic/catch-all as
+ * Union of the project's route paths, static routes as literals, dynamic/catch-all as
  * `` `…/${string}` `` templates. Falls back to `string` before the types are generated.
  */
 export type RoutePath = Register extends { routePath: infer P }
@@ -56,12 +56,14 @@ export interface RouteDef {
     readonly pattern: string;
     readonly load: () => Promise<{ default: ComponentType }>;
     readonly layouts?: readonly LayoutComponentLoader[];
-    /** `template.tsx` chain (root → nested) — like layouts, but re-mounted on each navigation. */
+    /** `template.tsx` chain (root → nested), like layouts, but re-mounted on each navigation. */
     readonly templates?: readonly LayoutComponentLoader[];
-    /** Nearest `loading.tsx` — shown as the Suspense fallback while this route loads. */
+    /** Nearest `loading.tsx`, shown as the Suspense fallback while this route loads. */
     readonly loading?: () => Promise<{ default: ComponentType }>;
-    /** Nearest `error.tsx` — rendered by an error boundary around this route. */
+    /** Nearest `error.tsx`, rendered by an error boundary around this route. */
     readonly errorComponent?: () => Promise<{ default: ComponentType<RouteErrorProps> }>;
+    /** Intercepting route (`(.)`/`(..)`/`(...)`), matched in its slot only on soft navigation. */
+    readonly intercept?: boolean;
 }
 
 /** Optional root layout loader (wraps every page). `null` when the project defines no layout. */