@solidjs/router 0.17.0-next.6 → 1.0.0-next.7

package/dist/routing.js

@@ -1,14 +1,13 @@
 import { flush, runWithOwner } from "solid-js";
-import { children, createComponent, createContext, createMemo, createSignal, onCleanup, untrack, useContext } from "solid-js";
+import { createComponent, createContext, createMemo, createSignal, NotReadyError, untrack, useContext } from "solid-js";
 import { isServer, getRequestEvent } from "@solidjs/web";
-import { createBeforeLeave } from "./lifecycle.js";
-import { mockBase, createMemoObject, extractSearchParams, invariant, resolvePath, createMatcher, joinPaths, scoreRoute, mergeSearchString, expandOptionals } from "./utils.js";
-import { clearFlashCookie, decodeFlashCookie, hasFlashCookie } from "./data/flash.js";
+import { mockBase, comparablePath, createMemoObject, extractSearchParams, invariant, resolvePath, createMatcher, joinPaths, scoreRoute, mergeSearchString, expandOptionals } from "./utils.js";
+import { clearFlashCookie, hasFlashCookie } from "./data/flashCookie.js";
 const MAX_REDIRECTS = 100;
 /** Consider this API opaque and internal. It is likely to change in the future. */
 export const RouterContextObj = createContext();
 export const RouteContextObj = createContext();
-function useOptionalContext(context) {
+export function useOptionalContext(context) {
     try {
         return useContext(context);
     }
@@ -77,21 +76,6 @@ export const useLocation = () => useRouter().location;
  * ```
  */
 export const useIsRouting = () => useRouter().isRouting;
-/**
- * usePreloadRoute returns a function that can be used to preload a route manual.
- * This is what happens automatically with link hovering and similar focus based behavior, but it is available here as an API.
- *
- * @example
- * ```js
- * const preload = usePreloadRoute();
- *
- * preload(`/users/settings`, { preloadData: true });
- * ```
- */
-export const usePreloadRoute = () => {
-    const pre = useRouter().preloadRoute;
-    return (url, options = {}) => pre(url instanceof URL ? url : new URL(url, mockBase), options.preloadData);
-};
 /**
  * `useMatch` takes an accessor that returns the path and creates a `Memo` that returns match information if the current path matches the provided path.
  * Useful for determining if a given path matches the current route.
@@ -115,61 +99,44 @@ export const useMatch = (path, matchFilters) => {
     });
 };
 /**
- * `useCurrentMatches` returns all the matches for the current matched route.
- * Useful for getting all the route information.
+ * `useRouteMatches` returns an accessor of the router's resolved matches for
+ * the current location — the chain of route definitions producing the current
+ * render, outermost first. Useful for reading `info` metadata off the matched
+ * chain. Unlike `useMatch`, which tests a path pattern you supply against the
+ * location, this reflects the route tree itself.
  *
  * @example
  * ```js
- * const matches = useCurrentMatches();
+ * const matches = useRouteMatches();
  *
- * const breadcrumbs = createMemo(() => matches().map(m => m.route.info.breadcrumb))
+ * const breadcrumbs = createMemo(() => matches().map(m => m.route.info.breadcrumb));
  * ```
  */
-export const useCurrentMatches = () => {
+export const useRouteMatches = () => {
     const router = useRouter();
     // return a copy so user mutations (eg. `.reverse()`) can't corrupt router state
     return () => router.matches().slice();
 };
 /**
- * Retrieves a reactive, store-like object containing the current route path parameters as defined in the Route.
+ * `usePreloadRoute` returns a function for warming a route by hand — the same
+ * work link hover/focus intent triggers automatically: the matched routes'
+ * lazy components load, and with `preloadData` their `preload` functions run.
  *
  * @example
  * ```js
- * const params = useParams();
+ * const preload = usePreloadRoute();
  *
- * // fetch user based on the id path parameter
- * const getUser = query(() => fetchUser(params.id), "user");
+ * preload(paths.users(2).settings, { preloadData: true });
  * ```
  */
-export const useParams = () => useRoute().params;
-/**
- * Retrieves a tuple containing a reactive object to read the current location's query parameters and a method to update them.
- * The object is a proxy so you must access properties to subscribe to reactive updates.
- * **Note** that values will be strings and property names will retain their casing.
- *
- * The setter method accepts an object whose entries will be merged into the current query string.
- * Values `''`, `undefined` and `null` will remove the key from the resulting query string.
- * Updates will behave just like a navigation and the setter accepts the same optional second parameter as `navigate` and auto-scrolling is disabled by default.
- *
- * @examples
- * ```js
- * const [searchParams, setSearchParams] = useSearchParams();
- *
- * return (
- *   <div>
- *     <span>Page: {searchParams.page}</span>
- *     <button
- *       onClick={() =>
- *         setSearchParams({ page: (parseInt(searchParams.page) || 0) + 1 })
- *       }
- *     >
- *       Next Page
- *     </button>
- *   </div>
- * );
- * ```
- */
-export const useSearchParams = () => {
+export const usePreloadRoute = () => {
+    const pre = useRouter().preloadRoute;
+    return (url, options = {}) => pre(url instanceof URL ? url : new URL(String(url), mockBase), options.preloadData);
+};
+export function useParams(_path) {
+    return useRoute().params;
+}
+export function useSearchParams(path) {
     const router = useRouter();
     const location = router.location;
     const navigate = useNavigate();
@@ -189,48 +156,165 @@ export const useSearchParams = () => {
             ...options
         });
     };
-    return [location.query, setSearchParams];
-};
+    // Passing a paths node opts into schema parsing. The node itself is a
+    // type-level reference; the schemas that run come from the currently
+    // matched routes (root→leaf), whose outputs merge over the raw query.
+    // A schema that reports issues is skipped, leaving raw values — search
+    // strings are user input, so defaults belong in the schema itself.
+    const query = path
+        ? createMemoObject(createMemo(() => {
+            const raw = { ...location.query };
+            let result;
+            for (const match of router.matches()) {
+                const schema = match.route.key.search;
+                if (!schema)
+                    continue;
+                const outcome = schema["~standard"].validate(raw);
+                if (outcome instanceof Promise)
+                    throw new Error("Async Standard Schema validation is not supported for search params");
+                if (!outcome.issues)
+                    result = Object.assign(result || { ...raw }, outcome.value);
+            }
+            return result || raw;
+        }))
+        : location.query;
+    return [query, setSearchParams];
+}
 /**
- * useBeforeLeave takes a function that will be called prior to leaving a route.
- * The function will be called with:
- *
- * - from (*Location*): current location (before change).
- * - to (*string | number*): path passed to `navigate`.
- * - options (*NavigateOptions*): options passed to navigate.
- * - preventDefault (*function*): call to block the route change.
- * - defaultPrevented (*readonly boolean*): `true` if any previously called leave handlers called `preventDefault`.
- * - retry (*function*, force?: boolean ): call to retry the same navigation, perhaps after confirming with the user. Pass `true` to skip running the leave handlers again (i.e. force navigate without confirming).
+ * Reactive link state for custom link components — the programmatic
+ * counterpart of the attribute vocabulary plain anchors receive
+ * (`aria-current`, `data-active`, `data-pending`).
  *
  * @example
- * ```js
- * useBeforeLeave((e: BeforeLeaveEventArgs) => {
- *   if (form.isDirty && !e.defaultPrevented) {
- *     // preventDefault to block immediately and prompt user async
- *     e.preventDefault();
- *     setTimeout(() => {
- *       if (window.confirm("Discard unsaved changes - are you sure?")) {
- *         // user wants to proceed anyway so retry with force=true
- *         e.retry(true);
- *       }
- *     }, 100);
- *   }
- * });
+ * ```tsx
+ * function TabLink(props: { href: string; children: JSX.Element }) {
+ *   const link = useLinkState(() => props.href);
+ *   return (
+ *     <a href={props.href} class="tab" data-selected={link.active() || undefined}>
+ *       {props.children}
+ *     </a>
+ *   );
+ * }
  * ```
  */
-export const useBeforeLeave = (listener) => {
-    const s = useRouter().beforeLeave.subscribe({
-        listener,
-        location: useLocation(),
-        navigate: useNavigate()
+export const useLinkState = (href, options = {}) => {
+    const router = useRouter();
+    const location = router.location;
+    const to = useResolvedPath(() => String(href()));
+    // trailing slashes are ignored so `/route` and `/route/` share state
+    const path = createMemo(() => {
+        const to_ = to();
+        return to_ === undefined ? undefined : comparablePath(to_);
     });
-    onCleanup(s);
+    const matches = (loc) => {
+        const path_ = path();
+        if (path_ === undefined)
+            return [false, false];
+        const exact = loc === path_;
+        return [exact || (!options.end && loc.startsWith(path_ + "/")), exact];
+    };
+    const state = createMemo(() => matches(decodeURI(comparablePath(location.pathname))));
+    return {
+        active: () => state()[0],
+        current: () => state()[1],
+        // match the in-flight target explicitly (rather than active-while-routing)
+        // so the answer is the same from pure reads and from effects, which
+        // observe the committed location during a transition
+        pending: createMemo(() => {
+            state(); // location dependency: mid-flight target swaps recompute
+            return (router.isRouting() &&
+                !!router.pendingTarget &&
+                matches(decodeURI(comparablePath(router.pendingTarget.value)))[0]);
+        })
+    };
 };
 // Encodes a static path segment like `encodeURIComponent`, but leaves RFC 3986
 // pchar characters (sub-delims / ":" / "@") literal, matching how browsers
 // report them in `location.pathname`. Non-ASCII characters (eg. CJK paths) are
 // still percent-encoded exactly as before, since browsers encode those too.
 const encodeSegment = (s) => encodeURIComponent(s).replace(/%(2B|40|3A|24|26|2C|3B|3D)/g, m => decodeURIComponent(m));
+// ---------------------------------------------------------------------------
+// Lazy route subtrees
+// ---------------------------------------------------------------------------
+//
+// A `children` thunk (`() => import("./feature/routes")`) is a *boundary*:
+// until it resolves, the compiled tree carries a param-less catch-all
+// placeholder branch under the boundary's pattern (splat-scored, so static
+// siblings still win). Resolution is append-only and cached per thunk, then a
+// module-level version signal bumps and every `branches()` consumer
+// recompiles — matches, params, and route states all react. The placeholder's
+// component reads a memo of the resolution promise, which keeps the enclosing
+// navigation transition pending exactly like a `lazy()` route component; its
+// `preload` *is* the resolver, so hover-intent preloading kicks the table
+// load through the existing component-preload path.
+const lazyBoundaries = new WeakMap();
+// Module scope: boundary resolution is global, deterministic state (same
+// thunk -> same routes), shared by every factory instance and the server's
+// flight collector.
+const [lazyTreeVersion, setLazyTreeVersion] = createSignal(0);
+/** Reactive read of the lazy-subtree version — recompile compiled branches when it changes. */
+export function trackLazySubtrees() {
+    return lazyTreeVersion();
+}
+/** Non-reactive read, for cache-busting outside the reactive graph (server collectors). */
+export function peekLazySubtrees() {
+    return untrack(lazyTreeVersion);
+}
+function getLazyBoundary(thunk) {
+    let record = lazyBoundaries.get(thunk);
+    if (!record)
+        lazyBoundaries.set(thunk, (record = { thunk }));
+    return record;
+}
+/**
+ * Kicks (or joins) a boundary's resolution. Returns the resolved routes
+ * synchronously once available, the in-flight promise otherwise. Commit is
+ * always async — even for thunks returning arrays — so the version bump
+ * never writes a signal from inside a render computation.
+ */
+export function resolveLazySubtree(record) {
+    if (record.resolved)
+        return record.resolved;
+    return (record.promise ||= Promise.resolve(record.thunk()).then(m => {
+        const routes = Array.isArray(m)
+            ? m
+            : m
+                .default ||
+                m.routes ||
+                [];
+        record.resolved = routes;
+        setLazyTreeVersion(v => v + 1);
+        return record.resolved;
+    }));
+}
+/**
+ * The unresolved boundaries in a match chain. Rendering gates on these (the
+ * route-states memo suspends until they land — see routers/components.tsx)
+ * and the server's flight collector awaits them before its preload pass.
+ */
+export function unresolvedLazyMatches(matches) {
+    const pending = [];
+    for (const match of matches)
+        if (match.route.lazy && !match.route.lazy.resolved)
+            pending.push(match.route.lazy);
+    return pending;
+}
+function createLazyPlaceholder(pattern, record) {
+    // The placeholder never renders and needs no component — `matches` parks
+    // on unresolved boundaries before route contexts are created (kicking the
+    // resolver as it does), preloadRoute kicks it directly, and the version
+    // bump swaps in the real routes. `path + "/*"` with no splat name matches
+    // the boundary itself and everything beneath it without recording a param
+    // (createMatcher skips empty splat names).
+    const placeholderPattern = pattern + "/*";
+    return {
+        key: record,
+        originalPath: "*",
+        pattern: placeholderPattern,
+        matcher: createMatcher(placeholderPattern),
+        lazy: record
+    };
+}
 export function createRoutes(routeDef, base = "") {
     const { component, preload, children, info } = routeDef;
     const isLeaf = !children || (Array.isArray(children) && !children.length);
@@ -284,16 +368,6 @@ export function createBranch(routes, index = 0) {
 function asArray(value) {
     return Array.isArray(value) ? value : [value];
 }
-/**
- * Resolves the route tree an app hands the router — JSX `<Route>` children
- * (`Route` is a data-holder component, evaluating to its merged props),
- * config objects, arrays, or thunks producing either — into route
- * definitions. Shared by the `<Router>` component (which keeps the
- * resolution live) and the server integration's preload runner (one-shot).
- */
-export function resolveRouteDefinitions(routes) {
-    return children(() => routes);
-}
 export function createBranches(routeDef, base = "", stack = [], branches = []) {
     const routeDefs = asArray(routeDef);
     for (let i = 0, len = routeDefs.length; i < len; i++) {
@@ -304,9 +378,24 @@ export function createBranches(routeDef, base = "", stack = [], branches = []) {
             const routes = createRoutes(def, base);
             for (const route of routes) {
                 stack.push(route);
-                const isEmptyArray = Array.isArray(def.children) && def.children.length === 0;
-                if (def.children && !isEmptyArray) {
-                    createBranches(def.children, route.pattern, stack, branches);
+                let children = def.children;
+                if (typeof children === "function") {
+                    const record = getLazyBoundary(children);
+                    if (record.resolved) {
+                        children = record.resolved;
+                    }
+                    else {
+                        // unresolved boundary: a catch-all placeholder holds its ground
+                        stack.push(createLazyPlaceholder(route.pattern, record));
+                        branches.push(createBranch([...stack], branches.length));
+                        stack.pop();
+                        stack.pop();
+                        continue;
+                    }
+                }
+                const isEmptyArray = Array.isArray(children) && children.length === 0;
+                if (children && !isEmptyArray) {
+                    createBranches(children, route.pattern, stack, branches);
                 }
                 else {
                     const branch = createBranch([...stack], branches.length);
@@ -375,6 +464,49 @@ function createLocation(path, state, queryWrapper) {
         query: queryWrapper ? queryWrapper(queryFn) : createMemoObject(queryFn)
     };
 }
+/**
+ * Rendezvous between the router and the data layer's single-flight consumer.
+ * The Router registers itself at mount (unless `singleFlight={false}`); the
+ * action side provides the consumer factory when the first action is created
+ * (see data/action.ts). Whichever side arrives first waits for the other, so
+ * an action module loaded lazily (a code-split route) still attaches to the
+ * already-mounted router — and a router-only app, where no action ever
+ * loads, never subscribes to the transport, so the server is never asked to
+ * collect.
+ */
+let flightConsumerFactory;
+const flightRouters = new Map();
+export function registerFlightRouter(router) {
+    flightRouters.set(router, flightConsumerFactory && flightConsumerFactory(router));
+    return () => {
+        const unsubscribe = flightRouters.get(router);
+        flightRouters.delete(router);
+        unsubscribe && unsubscribe();
+    };
+}
+export function provideFlightConsumer(factory) {
+    if (flightConsumerFactory)
+        return;
+    flightConsumerFactory = factory;
+    for (const [router, unsubscribe] of flightRouters) {
+        if (!unsubscribe)
+            flightRouters.set(router, factory(router));
+    }
+}
+/**
+ * The flash-cookie codec, provided by the action side (data/action.ts) so
+ * the router core never carries it: the core consumes the cookie eagerly
+ * per request (detection + one-shot clear via the tiny flashCookie.ts half)
+ * but defers decoding to this slot, read when the submissions signal
+ * initializes. Actions are created at module scope, so on the server the
+ * decoder is always installed before useSubmission can read — and a
+ * router-only app, where it never installs, has no actions that could have
+ * produced a flash cookie in the first place.
+ */
+let flashDecoder;
+export function provideFlashDecoder(decoder) {
+    flashDecoder || (flashDecoder = decoder);
+}
 let intent;
 export function getIntent() {
     return intent;
@@ -390,7 +522,8 @@ export function createRouterContext(integration, branches, getContext, options =
     const { signal: [source, setSource], utils = {} } = integration;
     const parsePath = utils.parsePath || (p => p);
     const renderPath = utils.renderPath || (p => p);
-    const beforeLeave = utils.beforeLeave || createBeforeLeave();
+    // An empty slot until `useBeforeLeave` installs the guard on first use.
+    const beforeLeave = utils.beforeLeave || {};
     const basePath = resolvePath("", options.base || "");
     const initialSource = untrack(source);
     if (basePath === undefined) {
@@ -411,14 +544,42 @@ export function createRouterContext(integration, branches, getContext, options =
     const effective = createMemo(() => navigateTarget() ?? source());
     const location = createLocation(() => effective().value, () => effective().state, utils.queryWrapper);
     const referrers = [];
-    const submissions = createSignal(isServer ? initFromFlash() : [], {
-        ownedWrite: true
-    });
-    const matches = createMemo(() => {
-        if (typeof options.transformUrl === "function") {
-            return getRouteMatches(branches(), options.transformUrl(location.pathname));
+    // The flash cookie is consumed eagerly: its one-shot clear (Set-Cookie)
+    // must be appended before streaming flushes the response headers, and an
+    // unread outcome must not haunt a later request's render. Only detection
+    // and clearing happen here (the tiny flashCookie.ts half); the raw header
+    // is stashed and decoding waits for the action-provided codec, read when
+    // the lazily allocated submissions signal below first initializes.
+    let flashCookieHeader;
+    if (isServer) {
+        const e = getRequestEvent();
+        if (e && !(e.router && e.router.submission)) {
+            const cookieHeader = e.request.headers.get("cookie");
+            if (hasFlashCookie(cookieHeader)) {
+                flashCookieHeader = cookieHeader;
+                // one-shot: clear it even when unreadable so it can't haunt later renders
+                if (e.response && e.response.headers)
+                    e.response.headers.append("Set-Cookie", clearFlashCookie());
+            }
         }
-        return getRouteMatches(branches(), location.pathname);
+    }
+    let submissions;
+    const matches = createMemo(() => {
+        const pathname = typeof options.transformUrl === "function"
+            ? options.transformUrl(location.pathname)
+            : location.pathname;
+        const m = getRouteMatches(branches(), pathname);
+        // An unresolved lazy subtree parks readers on not-ready semantics — the
+        // navigation transition (or the SSR stream) holds until the table lands.
+        // NotReadyError (not a returned promise) because a match chain is full
+        // of component functions the hydration serializer must never see. The
+        // recompute comes from the version-signal dependency on the client and
+        // from the carried promise's retry on the server; a boundary nested
+        // inside a boundary just parks the recomputed chain again.
+        const pending = unresolvedLazyMatches(m);
+        if (pending.length)
+            throw new NotReadyError(Promise.all(pending.map(resolveLazySubtree)));
+        return m;
     });
     const buildParams = () => mergeParams(matches());
     const wrapParams = utils.paramsWrapper
@@ -450,7 +611,9 @@ export function createRouterContext(integration, branches, getContext, options =
         beforeLeave,
         preloadRoute,
         singleFlight: options.singleFlight === undefined ? true : options.singleFlight,
-        submissions
+        get submissions() {
+            return (submissions ||= createSignal(isServer ? initSubmissions() : [], { ownedWrite: true }));
+        }
     };
     function navigateFromRoute(route, to, options) {
         // Untrack in case someone navigates in an effect - don't want to track `reference` or route paths
@@ -467,6 +630,9 @@ export function createRouterContext(integration, branches, getContext, options =
                 }
                 return;
             }
+            // typed path proxy nodes coerce to their href
+            if (typeof to !== "string")
+                to = to.toString();
             const queryOnly = !to || to[0] === "?";
             const { replace, resolve, scroll, state: nextState } = {
                 replace: false,
@@ -490,18 +656,21 @@ export function createRouterContext(integration, branches, getContext, options =
                     e && (e.response = { status: 302, headers: new Headers({ Location: resolvedTo }) });
                     setSource({ value: resolvedTo, replace, scroll, state: nextState });
                 }
-                else if (beforeLeave.confirm(resolvedTo, options)) {
+                else if (!beforeLeave.current || beforeLeave.current.confirm(resolvedTo, options)) {
                     referrers.push({ value: current.value, replace, scroll, state: current.state });
                     const newTarget = {
                         value: resolvedTo,
                         state: nextState
                     };
-                    if (lastTransitionTarget === undefined) {
+                    const firstNavigation = lastTransitionTarget === undefined;
+                    intent = "navigate";
+                    // assign the target before flushing so effects that run for the
+                    // isRouting flip (e.g. pending link state) can read it
+                    lastTransitionTarget = newTarget;
+                    if (firstNavigation) {
                         setIsRouting(true);
                         flush();
                     }
-                    intent = "navigate";
-                    lastTransitionTarget = newTarget;
                     if (lastTransitionTarget === newTarget) {
                         setNavigateTarget({ ...lastTransitionTarget });
                         queueMicrotask(() => {
@@ -536,6 +705,12 @@ export function createRouterContext(integration, branches, getContext, options =
     }
     function preloadRoute(url, preloadData) {
         const matches = getRouteMatches(branches(), url.pathname);
+        // An unresolved lazy subtree in the chain: the placeholder's
+        // component.preload (below) kicks the table load; once it lands,
+        // preload again so the real inner routes warm too.
+        const boundary = matches.find(m => m.route.lazy && !m.route.lazy.resolved);
+        boundary &&
+            resolveLazySubtree(boundary.route.lazy).then(() => preloadRoute(url, preloadData));
         const prevIntent = intent;
         intent = "preload";
         for (let match in matches) {
@@ -565,22 +740,16 @@ export function createRouterContext(integration, branches, getContext, options =
     }
     // Seeds the initial submission from a no-JS form post: the server
     // function handler redirected back with the outcome in a one-shot flash
-    // cookie (see src/server.ts's handleNoJS), which is read here — and
-    // cleared — so the post-redirect SSR renders useSubmission() state
+    // cookie (see src/server.ts's handleNoJS), consumed eagerly above and
+    // decoded here — so the post-redirect SSR renders useSubmission() state
     // exactly as a scripted submission would. An explicitly pre-seeded
     // `event.router.submission` (framework integrations) takes precedence.
-    function initFromFlash() {
+    function initSubmissions() {
         const e = getRequestEvent();
-        if (!e)
-            return [];
-        let submission = e.router && e.router.submission;
-        if (!submission) {
-            const cookieHeader = e.request.headers.get("cookie");
-            submission = decodeFlashCookie(cookieHeader);
-            // one-shot: clear it even when unreadable so it can't haunt later renders
-            if (hasFlashCookie(cookieHeader) && e.response && e.response.headers)
-                e.response.headers.append("Set-Cookie", clearFlashCookie());
-        }
+        const submission = (e && e.router && e.router.submission) ||
+            (flashDecoder && flashCookieHeader !== undefined
+                ? flashDecoder(flashCookieHeader)
+                : undefined);
         if (!submission)
             return [];
         return [

package/dist/server.d.ts

@@ -5,30 +5,40 @@ export type { FlashSubmission } from "./data/flash.js";
 export type { CollectFlightDataHook, ServerFunctionOutcome };
 export interface FlightDataCollectorOptions {
     /**
-     * The app's route tree — the same thing the `<Router>` receives as
-     * children: JSX `<Route>` trees, config objects, arrays, or a thunk
-     * producing either (for lazily/per-request built trees). Normalized to
-     * route definitions the same way the `<Router>` normalizes its children
-     * (on the server `Route` evaluates to its props, so no render pass is
-     * needed). Flight data is produced by the pure preload runner: the target
-     * URL is matched against the tree and the matched routes' `preload`
-     * functions run in data-only mode.
+     * The app's route tree — the same config objects the `createRouter`
+     * factory receives, an array of them, or a thunk producing either (for
+     * lazily/per-request built trees). Flight data is produced by the pure
+     * preload runner: the target URL is matched against the tree and the
+     * matched routes' `preload` functions run in data-only mode.
      */
-    routes: JSX.Element | RouteDefinition | RouteDefinition[] | (() => JSX.Element | RouteDefinition | RouteDefinition[]);
+    routes: RouteDefinition | readonly RouteDefinition[] | (() => RouteDefinition | readonly RouteDefinition[]);
     /**
-     * The root layout's preload — the same function the app passes to
-     * `<Router rootPreload>`. Runs before the matched routes' preloads with
-     * the semantics the root gets during a real server render: the merged
-     * params of every match and `intent: "initial"`.
+     * The root layout's preload — the same function the app passes to the
+     * `createRouter` factory's `preload` option. Runs before the matched
+     * routes' preloads with the semantics the root gets during a real server
+     * render: the merged params of every match and `intent: "initial"`.
      */
     rootPreload?: RoutePreloadFunc;
     /** The app's base path, for resolving redirect `Location`s and matching. */
     base?: string;
 }
+/** A `createRouter` instance carries everything the collector needs. */
+interface RouterInstanceLike {
+    (props: any): JSX.Element;
+    readonly routes: readonly RouteDefinition[];
+    readonly config: {
+        base?: string;
+        preload?: RoutePreloadFunc;
+    };
+}
 /**
  * Produces the `collectFlightData` implementation for
  * `configureServerFunctionsServer` (or `handleServerFunctionRequest`
- * options). Strategy: rerun the route data for the URL the client will show
+ * options). Accepts a `createRouter` instance directly — its routes, base,
+ * and `preload` are the single source of truth — or an options object for
+ * trees not created through the factory.
+ *
+ * Strategy: rerun the route data for the URL the client will show
  * after the mutation — the redirect `Location` when the outcome carries
  * one, the referring page otherwise — collecting each `query` result under
  * its cache key, scoped to the outcome's `X-Revalidate` keys when present
@@ -36,7 +46,7 @@ export interface FlightDataCollectorOptions {
  * payload seeds the client router's cache through its registered
  * flight-data consumer.
  */
-export declare function createFlightDataCollector(options: FlightDataCollectorOptions): CollectFlightDataHook;
+export declare function createFlightDataCollector(options: FlightDataCollectorOptions | RouterInstanceLike): CollectFlightDataHook;
 /**
  * The request headers for the flight-data collection pass: the source
  * request's headers with the mutation's `Set-Cookie` mutations folded into