@solidjs/router 1.0.0-next.9 → 2.0.0-next.12

package/dist/index.js

@@ -1,6 +1,7 @@
-import { getOwner, runWithOwner, createMemo, createRenderEffect, onCleanup, untrack, createContext, createSignal, useContext, NotReadyError, flush, createComponent, createRoot, sharedConfig, getObserver, $TRACK, action as action$1 } from 'solid-js';
-import { registerElementClaim, delegateEvents, isServer, getRequestEvent, createComponent as createComponent$1, memo, isResponseEnvelope } from '@solidjs/web';
-import { isServerFunction, getServerFunctionMetadata, GET, decodeResponse, subscribeFlightData, createServerReference } from '@solidjs/web/server-functions';
+import { getOwner, runWithOwner, createMemo, createRenderEffect, onCleanup, untrack, createContext, createSignal, useContext, NotReadyError, isPending, flush, createComponent, createRoot, createEffect, sharedConfig, getObserver, $TRACK, action as action$1 } from 'solid-js';
+import { registerElementClaim, delegateEvents, isServer, getRequestEvent, createComponent as createComponent$1, memo, isResponseEnvelope, REVALIDATE_HEADER } from '@solidjs/web';
+import { hasFlashCookie, clearFlashCookie, isServerFunction, getServerFunctionMetadata, GET, decodeResponse, subscribeFlightData, decodeResponsePayload, createServerReference } from '@solidjs/web/server-functions';
+import { decodeFlashCookie } from '@solidjs/web/server-functions/server';
 
 const hasSchemeRegex = /^(?:[a-z0-9]+:)?\/\//i;
 const trimPathRegex = /^\/+|(\/)\/+$/g;
@@ -504,31 +505,6 @@ function createPathsProxy(renderPath = p => p, base = "") {
   return node(normalizePath(base));
 }
 
-// The flash cookie's name and one-shot clearing — split from the codec in
-// flash.ts so the router core can consume the cookie eagerly (the clear must
-// be appended before streaming flushes the response headers, and an unread
-// outcome must not haunt a later request) without carrying the encode/decode
-// machinery into client bundles that never load the action layer.
-
-const FLASH_COOKIE = "flash";
-const FLASH_MATCHER = new RegExp(`(?:^|;\\s*)${FLASH_COOKIE}=([^;]+)`);
-
-/** Whether a Cookie header carries a flash cookie (readable or not). */
-function hasFlashCookie(cookieHeader) {
-  return !!cookieHeader && FLASH_MATCHER.test(cookieHeader);
-}
-
-/** The raw encoded flash payload out of a Cookie header, if present. */
-function matchFlashCookie(cookieHeader) {
-  const match = cookieHeader && cookieHeader.match(FLASH_MATCHER);
-  return match ? match[1] : undefined;
-}
-
-/** The Set-Cookie value clearing the flash cookie after it has been read. */
-function clearFlashCookie() {
-  return `${FLASH_COOKIE}=; Max-Age=0; Path=/`;
-}
-
 const MAX_REDIRECTS = 100;
 
 /** Consider this API opaque and internal. It is likely to change in the future. */
@@ -608,17 +584,27 @@ const useIsRouting = () => useRouter().isRouting;
 /**
  * `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.
- * 
+ *
+ * Accepts a pattern string — the match's `params` are typed from it — or a
+ * typed path node (a concrete URL, so no params to speak of):
+ *
  * @example
  * ```js
  * const match = useMatch(() => props.href);
- * 
+ *
  * return <div classList={{ active: Boolean(match()) }} />;
+ *
+ * const section = useMatch(() => "/docs/:page");
+ * section()?.params.page; // string
+ *
+ * const here = useMatch(() => paths.users(2));
  * ```
  */
 const useMatch = (path, matchFilters) => {
   const location = useLocation();
-  const matchers = createMemo(() => expandOptionals(path()).map(path => createMatcher(path, undefined, matchFilters)));
+  const matchers = createMemo(() =>
+  // `String()` folds typed path nodes to their URL
+  expandOptionals(String(path())).map(path => createMatcher(path, undefined, matchFilters)));
   return createMemo(() => {
     for (const matcher of matchers()) {
       const match = matcher(location.pathname);
@@ -1058,7 +1044,7 @@ function provideFlightConsumer(factory) {
 /**
  * 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)
+ * per request (detection + one-shot clear via the runtime's isomorphic 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
@@ -1100,7 +1086,7 @@ function createRouterContext(integration, branches, getContext, options = {}) {
       scroll: false
     });
   }
-  const [isRouting, setIsRouting] = createSignal(false, {
+  const [isNavigating, setIsRouting] = createSignal(false, {
     ownedWrite: true
   });
 
@@ -1120,7 +1106,7 @@ function createRouterContext(integration, branches, getContext, options = {}) {
   // 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
+  // and clearing happen here (the runtime's isomorphic 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;
@@ -1150,6 +1136,14 @@ function createRouterContext(integration, branches, getContext, options = {}) {
     if (pending.length) throw new NotReadyError(Promise.all(pending.map(resolveLazySubtree)));
     return m;
   });
+
+  // Every write is a transition in Solid 2, so a native history pop forks the
+  // source signal exactly like programmatic navigation does. isRouting is
+  // therefore derived: the manual flag covers navigateFromRoute's explicit
+  // window, and isPending over the location/matches read reports any
+  // in-flight fork — including popstate traversals and the lazy-subtree
+  // resolution matches() parks on.
+  const isRouting = createMemo(() => isNavigating() || isPending(() => (matches(), location.search, location.hash)));
   const buildParams = () => mergeParams(matches());
   const wrapParams = utils.paramsWrapper ? getParams => utils.paramsWrapper(getParams, branches) : getParams => createMemoObject(getParams);
   const params = wrapParams(buildParams);
@@ -1321,8 +1315,8 @@ 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), consumed eagerly above and
+  // function runtime redirected back with the outcome in a one-shot flash
+  // cookie (its default no-JS convention), 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.
@@ -1730,6 +1724,127 @@ function memoryHistory(initial = "/") {
   };
 }
 
+const STORAGE_KEY = "solid-router:scroll";
+
+/**
+ * Explicit scroll restoration for back/forward navigation. The browser's
+ * native same-document heuristic is unreliable for suspense-driven rendering:
+ * if the destination route forces a layout while the document is still short,
+ * the saved offset for the previous entry is clamped and lost (#577).
+ *
+ * Positions are captured continuously from the scroll event, keyed by the
+ * `_depth` the router already stamps on every history entry — capturing at
+ * scroll time (rather than at exit) stays correct through `useBeforeLeave`
+ * blocked/reverted traversals. The map persists to sessionStorage on pagehide
+ * so restoration survives reloads, which `scrollRestoration = "manual"`
+ * otherwise disables.
+ *
+ * Restoration is a single scroll once routing settles — the same strategy
+ * SvelteKit, TanStack Router and React Router use. Settling after the
+ * transition commits is what makes the offset reachable; chasing a still-
+ * growing document afterwards (a ResizeObserver re-asserting the offset as
+ * content arrives) was tried and removed: no peer router does it, an
+ * unbounded observer re-clamps the viewport to the bottom when the target is
+ * never reachable (a list that is genuinely shorter now), and scroll-induced
+ * layout changes can feed it back into itself. Content that commits after the
+ * transition settles — an image without reserved space, a boundary below the
+ * fold — keeps whatever offset the document can hold.
+ */
+function createScrollRestoration() {
+  window.history.scrollRestoration = "manual";
+  // the current entry needs its depth stamp for captures to have a key, even
+  // if something replaced history.state after the adapter stamped it
+  saveCurrentDepth();
+  let positions = {};
+  try {
+    positions = JSON.parse(sessionStorage.getItem(STORAGE_KEY)) || {};
+  } catch {}
+  const depth = () => window.history.state && window.history.state._depth;
+  let programmatic = false;
+  let pending;
+  const unbind = [bindEvent(window, "scroll", () => {
+    const d = depth();
+    if (d != null) positions[d] = window.scrollY;
+    // the user took over — a pending restore would yank them
+    if (!programmatic) pending = undefined;
+  }), bindEvent(window, "pagehide", () => {
+    try {
+      sessionStorage.setItem(STORAGE_KEY, JSON.stringify(positions));
+    } catch {}
+  })];
+  const restore = () => {
+    if (pending == null) return;
+    const y = positions[pending];
+    pending = undefined;
+    if (y == null) return;
+    // flagged so the resulting scroll event is not mistaken for the user
+    // taking over (which cancels a pending restore)
+    programmatic = true;
+    window.scrollTo(0, y);
+    programmatic = false;
+  };
+  return {
+    /** When the adapter notifies a traversal: mark the target for restoration. */
+    onPop() {
+      pending = depth();
+    },
+    /** After a push: forward entries died, and this depth may be reused. */
+    onPush() {
+      const d = depth();
+      if (d != null) for (const k in positions) +k >= d && delete positions[k];
+    },
+    create(router) {
+      // Restore once the traversal has settled: key on the location (a fully
+      // synchronous pop commits without isRouting ever flipping) and on
+      // isRouting, which reports in-flight transitions — native pops
+      // included — and holds the restore until they commit. restore() no-ops
+      // unless a traversal marked a target, so push navigations are inert.
+      // `transparent` keeps the effect invisible to the hydration id scheme —
+      // same reasoning as the link-claims effect (claims.ts): this setup is
+      // client-only, so an id-consuming node here has no server counterpart
+      // and every hydration id allocated after it shifts by one child slot.
+      // The visible failure is any <Loading> content that settled before the
+      // shell flush (a cache hit, a preloaded query): its serialized value and
+      // inlined markup are keyed under the server's ids, the shifted client
+      // misses both, recomputes, and re-renders the route fresh — duplicating
+      // the server DOM and leaving it inert.
+      createEffect(() => ({
+        url: router.location.pathname + router.location.search + router.location.hash,
+        routing: router.isRouting()
+      }), current => {
+        if (!current.routing) restore();
+      }, {
+        transparent: true
+      });
+      onCleanup(() => unbind.forEach(u => u()));
+      // reload/back_forward document loads land on an existing entry (a fresh
+      // navigation starts a new one and belongs at the top); the effect's
+      // initial run performs the restore after first render
+      const [nav] = performance.getEntriesByType && performance.getEntriesByType("navigation");
+      if (nav && nav.type !== "navigate") pending = depth();
+    }
+  };
+}
+/**
+ * Threads restoration through a history adapter: pushes prune dead forward
+ * entries, and adapter notifications (unblocked pops) mark the traversal
+ * target. Notification runs after the adapter's depth bookkeeping, so the
+ * marked depth is the entry being restored to.
+ */
+function withScrollRestoration(history, restoration) {
+  return {
+    ...history,
+    set(next) {
+      history.set(next);
+      next.replace || restoration.onPush();
+    },
+    init: history.init && (notify => history.init(value => {
+      restoration.onPop();
+      notify(value);
+    }))
+  };
+}
+
 /**
  * Identity helper that preserves literal types when the route tree is
  * declared as a separate variable. `createRouter` infers literally from
@@ -1740,6 +1855,41 @@ function memoryHistory(initial = "/") {
 function defineRoutes(routes) {
   return routes;
 }
+
+// The single contextual signature for `component` in `defineRoute`. The
+// public `RouteSectionComponent` union can't be used here: TypeScript only
+// contextually types a lambda's parameter from a single call signature, and
+// the whole point of `defineRoute` is that `props` infers. `children` is
+// `any` so `VoidComponent` pages (whose props declare `children?: never`,
+// #347) still assign under contravariance.
+
+/**
+ * The type `defineRoute` hands back: `path`, `matchFilters`, `children`, and
+ * `search` stay literal — and only present when provided precisely, which is
+ * what the `paths` machinery keys on — while `component`/`preload` widen back
+ * to the plain `RouteDefinition` contract so the route drops into any route
+ * tree. Generics that stayed at their fallback (not provided, or deferred by
+ * a context-sensitive value inside) are omitted rather than widening the
+ * whole route.
+ */
+
+/**
+ * Identity helper that types a single route from its own `path` pattern:
+ * inside `component` and `preload`, `props.params`/`args.params` carry the
+ * params the pattern guarantees (`:id` is `string`, `:tab?` is
+ * `string | undefined`) instead of the open `Params` record. Params
+ * inherited from parent routes remain accessible as `string | undefined`.
+ *
+ * Purely a definition-site convenience — plain object routes behave
+ * identically at runtime, and nested `children` only get typed params if
+ * they use `defineRoute` themselves.
+ */
+
+// pathless (layout) route — params stay the open `Params` record
+
+function defineRoute(route) {
+  return route;
+}
 /** Wraps a history adapter in the integration signal the router core consumes. Must run under a reactive owner. */
 function createIntegration(history) {
   let ignore = false;
@@ -1768,27 +1918,26 @@ function createIntegration(history) {
 
 /**
  * Server default: a static view of the request URL — no signal machinery, a
- * server render never navigates. Without a request event (SSG scripts,
- * server-side tests) the configured history adapter provides the location,
- * so e.g. `memoryHistory("/page")` works isomorphically.
+ * server render never navigates. The request event (when the harness scopes
+ * one) wins; the provider's `url` prop is the fallback for renders outside a
+ * request scope (SSG scripts, server-side tests, runtimes without
+ * `node:async_hooks`). History adapters are a client navigation concern and
+ * play no part in locating a server render.
  */
-function staticIntegration(history) {
+function staticIntegration(url, utils) {
   const e = getRequestEvent();
+  const source = e ? e.request.url : url;
   let value = "";
-  if (e) {
-    const url = new URL(e.request.url);
-    value = url.pathname + url.search;
-  } else if (history) {
-    value = history.get();
+  if (source) {
+    const u = new URL(source, mockBase);
+    value = u.pathname + u.search;
   }
-  const obj = typeof value === "string" ? {
+  const obj = {
     value
-  } : {
-    ...value
   };
   return {
     signal: [() => obj, next => Object.assign(obj, next)],
-    utils: history && history.utils
+    utils
   };
 }
 function createRouter(config) {
@@ -1818,7 +1967,13 @@ function createRouter(config) {
       console.warn("Mounting a router inside another router is not supported. " + "Compose route trees in one createRouter config instead.");
     }
     const root = untrack(() => props.children);
-    const integration = isServer ? staticIntegration(config.history) : createIntegration(config.history || browserHistory());
+    let restoration;
+    let history = config.history;
+    if (!isServer && (config.scrollRestoration ?? !history)) {
+      restoration = createScrollRestoration();
+      history = withScrollRestoration(history || browserHistory(), restoration);
+    }
+    const integration = isServer ? staticIntegration(props.url, config.history && config.history.utils) : createIntegration(history || browserHistory());
     let context;
     const routerState = createRouterContext(integration, branches, () => context, {
       base: basePath,
@@ -1834,6 +1989,7 @@ function createRouter(config) {
       })(routerState);
       setupLinkClaims(routerState, config.explicitLinks);
       if (routerState.singleFlight) onCleanup(registerFlightRouter(routerState));
+      restoration && restoration.create(routerState);
     }
     return createComponent$1(RouterContextObj, {
       value: routerState,
@@ -1963,52 +2119,6 @@ const useBeforeLeave = listener => {
   onCleanup(s);
 };
 
-// The no-JS form convention's cookie codec. When a form posts to a server
-// function without the client runtime (no instance header), the server
-// handler redirects back carrying the outcome in a one-shot "flash" cookie;
-// the next SSR pass reads it and seeds the router's submission state so
-// useSubmission() renders the result exactly as a scripted submission would.
-// Both codec halves live in this module so the write (src/server.ts, the
-// handler's handleNoJS) and the read (provided to the router core by
-// data/action.ts) can never drift apart. The cookie's name/clearing live in
-// flashCookie.ts — the only piece the router core itself consumes — so this
-// codec stays out of bundles that never load the action layer.
-
-function decodeInputValue(value) {
-  if (value && typeof value === "object") {
-    if (Array.isArray(value.$f)) {
-      const form = new FormData();
-      for (const [k, v] of value.$f) form.append(k, v);
-      return form;
-    }
-    if (Array.isArray(value.$u)) return new URLSearchParams(value.$u);
-  }
-  return value;
-}
-
-/**
- * Decodes the flash cookie out of a request's Cookie header. Returns
- * undefined when absent or unreadable (a malformed cookie must never take
- * down SSR — it is cleared either way).
- */
-function decodeFlashCookie(cookieHeader) {
-  const match = matchFlashCookie(cookieHeader);
-  if (!match) return;
-  try {
-    const payload = JSON.parse(decodeURIComponent(match));
-    if (!payload || !payload.result) return;
-    const result = payload.error ? new Error(payload.result) : payload.result;
-    return {
-      input: Array.isArray(payload.input) ? payload.input.map(decodeInputValue) : [],
-      url: payload.url,
-      result: payload.thrown ? undefined : result,
-      error: payload.thrown ? result : undefined
-    };
-  } catch (error) {
-    console.error(error);
-  }
-}
-
 const LocationHeader = "Location";
 const PRELOAD_TIMEOUT = 5000;
 const CACHE_TIMEOUT = 180000;
@@ -2326,8 +2436,11 @@ let integrationsInstalled = false;
 function installRouterIntegrations() {
   if (integrationsInstalled) return;
   integrationsInstalled = true;
-  provideFlashDecoder(decodeFlashCookie);
-  if (!isServer) {
+  if (isServer) {
+    // Server-only: initSubmissions only decodes during SSR, so client builds
+    // tree-shake the codec (which now lives behind the runtime's server entry).
+    provideFlashDecoder(decodeFlashCookie);
+  } else {
     setRouterFormHandler(handleFormAction);
     provideFlightConsumer(setupFlightDataConsumer);
   }
@@ -2399,13 +2512,12 @@ function actionImpl(fn, options = {}) {
     } finally {
       form && setFormBusy(form, -1);
     }
-    if (!response) return undefined;
     let submission;
     submission = {
       input: variables,
       url,
-      result: response.data,
-      error: response.error,
+      result: response && response.data,
+      error: response && response.error,
       clear() {
         router.submissions[1](entries => entries.filter(entry => entry !== submission));
       },
@@ -2417,10 +2529,18 @@ function actionImpl(fn, options = {}) {
         }, variables, current);
       }
     };
-    router.submissions[1](entries => [...entries, submission]);
+    // Book-keeping is intentional: only outcomes worth showing or retrying
+    // (a result or an error) enter the submissions list, so the typical void
+    // mutation leaves nothing behind. Settled hooks still see every
+    // completion — void, metadata-only, and redirects included — one
+    // `onSettled` per invocation (#580).
+    response && router.submissions[1](entries => [...entries, submission]);
     for (const hook of settledHooks.values()) hook(submission);
-    if (response.error && !form) throw response.error;
-    return response.data;
+    if (response) {
+      if (response.error && !form) throw response.error;
+      return response.data;
+    }
+    return undefined;
   }
   const o = typeof options === "string" ? {
     name: options
@@ -2523,10 +2643,10 @@ function setupFlightDataConsumer(router) {
  * the flight-data consumer and the action response path (which still sees
  * metadata-bearing responses when no flight data was collected).
  */
-async function applyResponseMetadata(metadata, navigate, flightData) {
+function applyResponseMetadata(metadata, navigate, flightData) {
   let keys;
   if (metadata) {
-    if (metadata.headers.has("X-Revalidate")) keys = metadata.headers.get("X-Revalidate").split(",");
+    if (metadata.headers.has(REVALIDATE_HEADER)) keys = metadata.headers.get(REVALIDATE_HEADER).split(",");
     if (metadata.headers.has("Location")) {
       const locationUrl = metadata.headers.get("Location") || "/";
       if (locationUrl.startsWith("http")) {
@@ -2541,7 +2661,7 @@ async function applyResponseMetadata(metadata, navigate, flightData) {
   // set cache
   flightData && Object.keys(flightData).forEach(k => query.set(k, flightData[k]));
   // trigger revalidation
-  await revalidate(keys, false);
+  revalidate(keys, false);
 }
 async function handleResponse(response, error, navigate, metadataHandled) {
   let data;
@@ -2557,14 +2677,11 @@ async function handleResponse(response, error, navigate, metadataHandled) {
     // carry a codec-encoded body the router decodes itself. With the
     // flight-data consumer registered single-flight payloads never reach
     // this path, but a manually opted-in call (no consumer) still can —
-    // unwrap the standardized { value, data } shape for it too.
+    // the runtime splits its own envelope shape.
     if (response.body) {
-      data = await decodeResponse(response);
-      if (response.headers.has("X-Single-Flight")) {
-        const payload = data;
-        data = payload.value;
-        flightData = payload.data;
-      }
+      const payload = await decodeResponsePayload(response);
+      data = payload.value;
+      flightData = payload.flightData;
     }
   } else if (error) return {
     error: response
@@ -2572,7 +2689,7 @@ async function handleResponse(response, error, navigate, metadataHandled) {
   // The transport consumer applies metadata before returning a server
   // function's unwrapped value. Do not treat that value as a second plain
   // action response and invalidate the freshly seeded query cache again.
-  if (!metadataHandled || metadata || flightData) await applyResponseMetadata(metadata, navigate, flightData);
+  if (!metadataHandled || metadata || flightData) applyResponseMetadata(metadata, navigate, flightData);
   return data != null ? {
     data
   } : undefined;
@@ -2588,4 +2705,4 @@ var serverForms = /*#__PURE__*/Object.freeze({
   submitServerForm: submitServerForm
 });
 
-export { RouterContextObj as RouterContext, mergeSearchString as _mergeSearchString, action, browserHistory, createBeforeLeave, createRouter, defineRoutes, hashHistory, int, memoryHistory, query, revalidate, useAction, useBeforeLeave, useHref, useIsRouting, useLinkState, useLocation, useMatch, useNavigate, useParams, usePreloadRoute, useResolvedPath, useRouteMatches, useSearchParams, useSubmissions };
+export { RouterContextObj as RouterContext, mergeSearchString as _mergeSearchString, action, browserHistory, createBeforeLeave, createRouter, defineRoute, defineRoutes, hashHistory, int, memoryHistory, query, revalidate, useAction, useBeforeLeave, useHref, useIsRouting, useLinkState, useLocation, useMatch, useNavigate, useParams, usePreloadRoute, useResolvedPath, useRouteMatches, useSearchParams, useSubmissions };

package/dist/routers/factory.d.ts

@@ -1,6 +1,6 @@
 import type { JSX } from "@solidjs/web";
 import type { RoutePaths } from "../paths.js";
-import type { OutputMatch, RouteDefinition, RoutePreloadFunc, RouteSectionProps } from "../types.js";
+import type { DefinedRouteFilters, LazyRouteChildren, OutputMatch, Params, RouteDefinition, RouteInfo, RouteParams, RoutePreloadFunc, RoutePreloadFuncArgs, RouteSectionComponent, RouteSectionProps, StandardSchemaV1, ValidFilters } from "../types.js";
 import type { RouterHistory } from "./history.js";
 /**
  * Identity helper that preserves literal types when the route tree is
@@ -10,6 +10,60 @@ import type { RouterHistory } from "./history.js";
  * declared `as const` — `defineRoutes` makes that impossible to forget.
  */
 export declare function defineRoutes<const R extends readonly RouteDefinition[]>(routes: R): R;
+type RouteChildren = RouteDefinition | readonly RouteDefinition[] | LazyRouteChildren;
+type DefinedRouteComponent<T, P extends Params> = (props: RouteSectionProps<T, P> & {
+    children?: any;
+}) => JSX.Element;
+/**
+ * The type `defineRoute` hands back: `path`, `matchFilters`, `children`, and
+ * `search` stay literal — and only present when provided precisely, which is
+ * what the `paths` machinery keys on — while `component`/`preload` widen back
+ * to the plain `RouteDefinition` contract so the route drops into any route
+ * tree. Generics that stayed at their fallback (not provided, or deferred by
+ * a context-sensitive value inside) are omitted rather than widening the
+ * whole route.
+ */
+export type DefinedRoute<S = undefined, T = unknown, F = undefined, C = undefined, Sch = undefined> = ([S] extends [undefined] ? {} : {
+    path: S;
+}) & ([F] extends [undefined] ? {} : DefinedRouteFilters<S> extends F ? {} : {
+    matchFilters: F;
+}) & ([C] extends [undefined] ? {} : [RouteChildren | undefined] extends [C] ? {} : {
+    children: C;
+}) & ([Sch] extends [undefined] ? {} : {
+    search: Sch;
+}) & {
+    component?: RouteSectionComponent<T>;
+    preload?: RoutePreloadFunc<T>;
+    info?: RouteInfo;
+};
+/**
+ * Identity helper that types a single route from its own `path` pattern:
+ * inside `component` and `preload`, `props.params`/`args.params` carry the
+ * params the pattern guarantees (`:id` is `string`, `:tab?` is
+ * `string | undefined`) instead of the open `Params` record. Params
+ * inherited from parent routes remain accessible as `string | undefined`.
+ *
+ * Purely a definition-site convenience — plain object routes behave
+ * identically at runtime, and nested `children` only get typed params if
+ * they use `defineRoute` themselves.
+ */
+export declare function defineRoute<const S extends string | readonly string[], T = unknown, const F = DefinedRouteFilters<S>, const C extends RouteChildren | undefined = RouteChildren | undefined, Sch extends StandardSchemaV1<any, any> | undefined = undefined>(route: {
+    path: S;
+    matchFilters?: F & ValidFilters<F, S>;
+    preload?: (args: RoutePreloadFuncArgs<RouteParams<S>>) => T;
+    component?: DefinedRouteComponent<T, RouteParams<S>>;
+    children?: C;
+    /** Standard Schema validator for this route's search params; its input type flows into the typed path proxy. */
+    search?: Sch;
+    info?: RouteInfo;
+}): DefinedRoute<S, T, F, C, Sch>;
+export declare function defineRoute<T = unknown, const C extends RouteChildren | undefined = RouteChildren | undefined, Sch extends StandardSchemaV1<any, any> | undefined = undefined>(route: {
+    preload?: (args: RoutePreloadFuncArgs) => T;
+    component?: DefinedRouteComponent<T, Params>;
+    children?: C;
+    search?: Sch;
+    info?: RouteInfo;
+}): DefinedRoute<undefined, T, undefined, C, Sch>;
 export interface RouterConfig<R extends readonly RouteDefinition[] = RouteDefinition[]> {
     /** The route tree. Immutable per instance — it is the source of truth for matching *and* types. */
     routes: R;
@@ -20,20 +74,41 @@ export interface RouterConfig<R extends readonly RouteDefinition[] = RouteDefini
      * `props.data`.
      */
     preload?: RoutePreloadFunc;
-    /** History adapter; defaults to browser history on the client and the request URL on the server. */
+    /**
+     * History adapter for client navigation; defaults to browser history. On
+     * the server only its `utils` apply — the location comes from the request
+     * event or the provider's `url` prop.
+     */
     history?: RouterHistory;
     singleFlight?: boolean;
     actionBase?: string;
     explicitLinks?: boolean;
     /** Preload route code/data on link hover and focus. Defaults to `true`. */
     preloadLinks?: boolean;
+    /**
+     * Explicit scroll restoration for back/forward navigation: positions are
+     * saved per history entry and restored once the navigation settles,
+     * replacing the browser heuristic that loses offsets when the destination
+     * route forces a layout while rendering. Defaults to `true` with the
+     * default browser history; a custom `history` adapter owns its session and
+     * must opt in explicitly.
+     */
+    scrollRestoration?: boolean;
     transformUrl?: (url: string) => string;
 }
+export interface RouterProps {
+    /**
+     * Server-only: the location for this render when no request event is in
+     * scope (SSG scripts, tests, runtimes without `node:async_hooks`). A
+     * request event established by the server harness takes precedence.
+     * Ignored on the client, where the history adapter owns the location.
+     */
+    url?: string;
+    children?: (props: RouteSectionProps) => JSX.Element;
+}
 export interface RouterInstance<R extends readonly RouteDefinition[] = RouteDefinition[]> {
     /** The instance is the provider component; the render-prop child receives the matched content as `props.children`. */
-    (props: {
-        children?: (props: RouteSectionProps) => JSX.Element;
-    }): JSX.Element;
+    (props: RouterProps): JSX.Element;
     /** Typed path proxy — builds URLs through property access and calls. */
     readonly paths: RoutePaths<R>;
     readonly routes: R;
@@ -43,3 +118,4 @@ export interface RouterInstance<R extends readonly RouteDefinition[] = RouteDefi
     match(url: string): OutputMatch[];
 }
 export declare function createRouter<const R extends readonly RouteDefinition[]>(config: RouterConfig<R>): RouterInstance<R>;
+export {};