@solidjs/router 2.0.0-next.36 → 2.0.0-next.38

package/README.md

@@ -17,9 +17,9 @@ Explore the official [documentation](https://docs.solidjs.com/solid-router) for
 ## Core Features
 
 - **Typed Routing**: URLs built through a typed path proxy inferred from your route config — `paths.users(2).settings` typechecks against the tree
-- **Plain Anchors**: no link component — `<a>` elements get `aria-current`, `data-active`, and `data-pending` automatically via compiler-claimed anchors
+- **Plain Anchors**: no link component — `<a>` elements get `aria-current` and `data-active` automatically via compiler-claimed anchors, and `data-pending` with the opt-in `pendingLinks` plugin
 - **Universal Rendering**: one factory for browser, hash, memory, and server rendering; history adapters are imports, so unused ones never enter your bundle
-- **Preload Functions**: parallel data fetching following the render-as-you-fetch pattern, triggered eagerly on link hover/focus
+- **Preload Functions**: parallel data fetching following the render-as-you-fetch pattern, triggered eagerly by opt-in [link preloading](#preloading)
 - **Data APIs with Caching**: `query` and `action` with deduplication, revalidation, single-flight mutations, and progressive enhancement — plus experimental `liveQuery` for keyed queries over live streams
 - **Typed Search Params**: opt-in per-route [Standard Schema](https://github.com/standard-schema/standard-schema) validation — `search.page` is a `number`, not `"2"`
 
@@ -40,6 +40,7 @@ Explore the official [documentation](https://docs.solidjs.com/solid-router) for
   - [File-System Routes](#file-system-routes)
 - [Typed Paths](#typed-paths)
 - [Links](#links)
+- [Preloading](#preloading)
 - [Preload Functions](#preload-functions)
 - [Data APIs](#data-apis)
 - [Typed Search Params](#typed-search-params)
@@ -171,7 +172,7 @@ A route definition supports:
 | `path`         | `string \| string[]`                                         | Path partial for this route segment                                             |
 | `component`    | `Component`                                                  | Component rendered for the matched segment                                      |
 | `children`     | `RouteDefinition \| RouteDefinition[] \| () => Promise<...>` | Nested route definitions, or a thunk for a [lazy subtree](#lazy-route-subtrees) |
-| `preload`      | `RoutePreloadFunc`                                           | Called on preload intent (hover/focus) and navigation                           |
+| `preload`      | `RoutePreloadFunc`                                           | Called on [link preloading](#preloading) and navigation                         |
 | `matchFilters` | `MatchFilters`                                               | Additional constraints for matching parameters                                  |
 | `search`       | `StandardSchemaV1`                                           | Search-param validator; its types flow into `paths` and hooks                   |
 | `info`         | `Record<string, any>`                                        | Arbitrary metadata, readable via `useRouteMatches`                              |
@@ -360,11 +361,11 @@ const router = createRouter({
 });
 ```
 
-The import only fires when something needs the subtree — hovering a link into it, navigating into it, or the server matching a URL beneath it. Until then the tree carries a placeholder that knows every URL under `/admin` belongs to the subtree without knowing its contents (static sibling routes still win without triggering the load). Everything folds in as if the routes were inline:
+The import only fires when something needs the subtree — preloading a link into it, navigating into it, or the server matching a URL beneath it. Until then the tree carries a placeholder that knows every URL under `/admin` belongs to the subtree without knowing its contents (static sibling routes still win without triggering the load). Everything folds in as if the routes were inline:
 
 - **Types**: TypeScript never runs the thunk — inference flows through the import's promise type, so `paths.admin.users(2)` typechecks (match filters and search schemas included) before any of the subtree's code exists client-side. The module's `default` or `routes` export is used. Only tables genuinely built at runtime (typed as plain `RouteDefinition[]`) degrade to untyped.
 - **Navigation**: the table load folds into the navigation transition — the old screen holds until the subtree (and its matched components) are ready, exactly like a `lazy()` route component.
-- **Preloading**: hover intent kicks the table load, and when it lands the preload continues into the inner routes' components and `preload` functions — one cascading warm-up from the earliest possible moment.
+- **Preloading**: a link preload kicks the table load, and when it lands the preload continues into the inner routes' components and `preload` functions — one cascading warm-up from the earliest possible moment.
 - **Server**: SSR resolves matched boundaries during the render (use the streaming entry point `renderToStream` — awaiting it resolves with the settled HTML — as with any async work), and the single-flight collector resolves them before its data pass.
 
 Resolution is cached per thunk and append-only: the tree never changes shape after a subtree lands, it just gets more specific. Keep thunks deterministic — `() => import(...)` — rather than switching tables on runtime state.
@@ -399,10 +400,10 @@ The source is called with **derived** arguments, not a live location — the cal
 
 A route view is route-shaped on purpose — the address stays stable and `defineRoute` can check its params against the pattern — which means it is only callable as a route. When the same server component is also used elsewhere, keep it a plain (non-exported, non-endpoint) function and have the route view call it with `params.id`. The value `serverRouteComponent` returns is a component only so it fits the `component` field; mounting it any other way (through `lazy()`, or by hand) throws, since outside the match there are only merged params to call with.
 
-The router mounts the resolved component with the outlet as `children`, so a server component can be a layout, and it calls the same source under preload intent — link hover, `preloadRoute`, the [single-flight collector](#server-integration) — with the same derived args. What that call _means_ is the source's: the router does not choose the cache strategy or own the key.
+The router mounts the resolved component with the outlet as `children`, so a server component can be a layout, and it calls the same source under preload intent — link preloading, `usePreloadRoute`, the [single-flight collector](#server-integration) — with the same derived args. What that call _means_ is the source's: the router does not choose the cache strategy or own the key.
 
 - `query(fn, key)`: link intent warms the entry the render reads, `revalidate("story")` and action responses refetch it, and the collector reproduces it so a mutation's response carries the route's fresh markup. Argument changes deliver into the mounted boundary — it morphs in place rather than remounting.
-- [`liveQuery(fn, key)`](#livequery-experimental): the frame stream stays open and the channel owns it — hover connects it (held through the preload window, so a hovered link is an open stream), `revalidate(key)` reconnects, and the mutation sweep and the single-flight collector both leave it alone — nothing pulls it server-side, and the stream is its own freshness.
+- [`liveQuery(fn, key)`](#livequery-experimental): the frame stream stays open and the channel owns it — a link preload connects it (held through the preload window, so a preloaded link is an open stream), `revalidate(key)` reconnects, and the mutation sweep and the single-flight collector both leave it alone — nothing pulls it server-side, and the stream is its own freshness.
 
 Anything else callable with the args works too; wrapping is what gives dedupe, preload, and revalidation.
 
@@ -425,7 +426,7 @@ const routes = [{ component: serverRouteComponent(query(appShell, "shell")), chi
 render(() => <Router routes={routes} />, document.body);
 ```
 
-`children` is the only client position the router fills, and the helper's type says so: a server component that requires other props — event handlers, refs, named slots — is rejected. Those come from the client, so that route has a client half; write it as an ordinary route component around `dynamic()`. Interaction that lives on the server — form posts to server actions via `action={addTodo}` — needs no client component at all.
+`children` is the only client position the router fills, and the helper's type says so: a server component that requires other props — event handlers, refs, named slots — is rejected. Those come from the client, so that route has a client half; write it as an ordinary route component around `dynamicComponent()`. Interaction that lives on the server — form posts to server actions via `action={addTodo}` — needs no client component at all.
 
 ### File-System Routes
 
@@ -502,14 +503,14 @@ There is no link component. Use `<a>`; the router intercepts same-origin clicks
 
 Behavior modifiers are attributes, so they work identically in client, server-rendered, and third-party markup:
 
-| attribute  | description                                                                                                     |
-| ---------- | --------------------------------------------------------------------------------------------------------------- |
-| `replace`  | Replace the history entry instead of pushing                                                                    |
-| `noscroll` | Turn off scrolling to the top after navigation                                                                  |
-| `state`    | JSON string [pushed](https://developer.mozilla.org/en-US/docs/Web/API/History/pushState) onto the history stack |
-| `preload`  | Set to `"false"` to opt this link out of hover/focus preloading                                                 |
-| `link`     | Marks a router link when `explicitLinks` is enabled                                                             |
-| `target`   | Any value (e.g. `_self`) opts the anchor out of router handling                                                 |
+| attribute  | description                                                                                                         |
+| ---------- | ------------------------------------------------------------------------------------------------------------------- |
+| `replace`  | Replace the history entry instead of pushing                                                                        |
+| `noscroll` | Turn off scrolling to the top after navigation                                                                      |
+| `state`    | JSON string [pushed](https://developer.mozilla.org/en-US/docs/Web/API/History/pushState) onto the history stack     |
+| `preload`  | `"false"` opts this link out of all [preloading](#preloading); `"viewport"` or `"eager"` opts it into that strategy |
+| `link`     | Marks a router link when `explicitLinks` is enabled                                                                 |
+| `target`   | Any value (e.g. `_self`) opts the anchor out of router handling                                                     |
 
 ```tsx
 <a href={paths.login} replace>Log in</a>
@@ -517,7 +518,7 @@ Behavior modifiers are attributes, so they work identically in client, server-re
 <a href="https://example.com">External — untouched</a>
 ```
 
-Active and pending state is styled with CSS — one vocabulary for every kind of link:
+Active and pending state is styled with CSS — one vocabulary for every kind of link. `aria-current` and `data-active` are automatic; `data-pending` is opt-in:
 
 ```css
 nav a[aria-current="page"] {
@@ -528,9 +529,19 @@ nav a[data-active] {
 } /* exact or prefix match on the path */
 a[data-pending] {
   opacity: 0.6;
-} /* target of in-flight navigation */
+} /* target of in-flight navigation — needs `links: pendingLinks` */
 ```
 
+`data-pending` is opt-in, so an app that never shows pending link state doesn't ship the code that computes it. Pass the `pendingLinks` plugin to the router:
+
+```tsx
+import { createRouter, pendingLinks } from "@solidjs/router";
+
+const Router = createRouter({ routes, links: pendingLinks });
+```
+
+It marks the links whose path covers the in-flight destination of a link click or `navigate()` call — by the same path rule as `data-active` — until that navigation lands. Back/forward traversals don't mark links pending. `data-pending` agrees with `useLinkState().pending` at every moment; the hook works with or without the plugin.
+
 One rule decides both, for anchors and `useLinkState` alike:
 
 - **current** (`aria-current="page"`) — same path and same query, ignoring parameter order and the hash. On `/?filter=active`, `<a href="/?filter=active">` is current and `<a href="/">` is not.
@@ -553,9 +564,47 @@ function TabLink(props: { href: string; children: JSX.Element }) {
 }
 ```
 
+## Preloading
+
+The router can warm a link's route before it is clicked: preloading **code** loads the matched routes' `lazy()` components (and any [lazy subtree](#lazy-route-subtrees) on the way), and preloading **data** also runs their [preload functions](#preload-functions) with `intent: "preload"`. Nothing is preloaded unless you opt in. Earlier `next` prereleases preloaded on hover, focus, and touch by default; that built-in is gone. A boolean `preloadLinks` is a type error and, in development, a warning — it preloads nothing.
+
+```tsx
+import { createRouter, intentPreload } from "@solidjs/router";
+
+const Router = createRouter({ routes, preloadLinks: intentPreload() });
+```
+
+| strategy                                                           | preloads a link when                                                                                                                                                                                                                                | defaults      |
+| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
+| `intentPreload({ delay = 20, data = true })`                       | the pointer rests on it for `delay` ms, it is focused (`focusin`), or a touch starts on it (`touchstart`). Moving over a link that already preloaded does not preload it again until the pointer leaves                                             | code and data |
+| `tapPreload({ data = true })`                                      | a pointer goes down on it (`pointerdown`: mouse, touch, or pen), ahead of the click                                                                                                                                                                 | code and data |
+| `viewportPreload({ all = false, data = false, delay = 100, rootMargin })` | it has stayed in the viewport for `delay` ms and the browser is then idle (`requestIdleCallback`, or `setTimeout` if that is missing). Once per `href`; leaving before the idle flush cancels it, and a new `href` preloads again. One shared `IntersectionObserver`. `rootMargin` is passed through (the observer's own `"0px"` when omitted) | code          |
+| `eagerPreload({ all = false, data = false })`                      | the page has loaded and the browser is idle, including links mounted later. Once per `href`; a link removed before that flush is dropped                                                                                                                                 | code          |
+
+Pass an array to combine strategies — viewport for code, intent for data:
+
+```tsx
+const Router = createRouter({
+  routes,
+  preloadLinks: [viewportPreload({ all: true }), intentPreload()]
+});
+```
+
+Strategies are client-only, and an app ships only the ones it imports. `intentPreload` and `tapPreload` apply to every router link. `viewportPreload` and `eagerPreload` apply only to links that name them, `<a href="/pricing" preload="viewport">` or `preload="eager"`, unless created with `{ all: true }`. They also skip preloading when the browser reports Save-Data or a 2g connection (`effectiveType` of `"2g"` or `"slow-2g"`).
+
+The `href` and `preload` attribute are read when the preload runs, so a dynamic `href` is the one the link has then.
+
+Hover, focus, and touch preloads do not check modifier keys or `defaultPrevented`, and neither does `tapPreload`'s `pointerdown`. A click still does: the router ignores it when `preventDefault` was already called, when it is not the primary button, or when alt, ctrl, meta, or shift is held.
+
+Preloading is purely an optimization: without it every navigation still loads the same code and data, just after the click instead of before it. A link with `preload="false"` is never preloaded by any strategy.
+
+Whether a strategy also preloads data is its own `data` option, not a per-link choice. `intentPreload` and `tapPreload` default to data because the user is about to click; a data preload runs only for route levels the navigation would change, and `query` keeps the result for the few seconds until the click arrives. `viewportPreload` and `eagerPreload` warm links that are merely on screen or already on the page, so they default to code only — a data preload there is worth it only when the cache outlives the moment of clicking, as with TanStack Query or an HTTP-cached `GET` server function. Pass `{ data: true }` to opt in.
+
+`usePreloadRoute` triggers the same work by hand.
+
 ## Preload Functions
 
-Even with smart caches, waterfalls happen when data fetching waits on view logic or lazy-loaded code. Preload functions start fetching data in parallel with loading the route — called when a route renders, and eagerly when links are hovered or focused.
+Even with smart caches, waterfalls happen when data fetching waits on view logic or lazy-loaded code. Preload functions start fetching data in parallel with loading the route — called when a route renders, and eagerly when the router [preloads a link](#preloading) with data.
 
 ```tsx
 import { lazy } from "solid-js";
@@ -571,11 +620,11 @@ const routes = defineRoutes([{ path: "/users/:id", component: User, preload: pre
 
 The preload function receives:
 
-| key      | type                                               | description                                                                                                                                                       |
-| -------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| params   | object                                             | The route parameters (same value as `useParams()` inside the route component)                                                                                     |
-| location | `{ pathname, search, hash, query, state, key }`    | Path information (corresponds to [`useLocation()`](#uselocation))                                                                                                 |
-| intent   | `"initial" \| "navigate" \| "native" \| "preload"` | Why this is being called: `initial` — first render; `navigate` — router navigation; `native` — browser back/forward; `preload` — link hover/focus, not navigating |
+| key      | type                                               | description                                                                                                                                                      |
+| -------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| params   | object                                             | The route parameters (same value as `useParams()` inside the route component)                                                                                    |
+| location | `{ pathname, search, hash, query, state, key }`    | Path information (corresponds to [`useLocation()`](#uselocation))                                                                                                |
+| intent   | `"initial" \| "navigate" \| "native" \| "preload"` | Why this is being called: `initial` — first render; `navigate` — router navigation; `native` — browser back/forward; `preload` — link preloading, not navigating |
 
 The factory-level `preload` option is the app-wide counterpart: it runs once per mount/request with the merged params of every match, and its result reaches the root render-prop as `props.data`.
 
@@ -596,7 +645,7 @@ const getUser = query(async id => {
 A query:
 
 1. Dedupes on the server for the lifetime of the request.
-2. Fills a preload cache in the browser lasting 5 seconds, so hover preloads and route entry share one fetch.
+2. Fills a preload cache in the browser lasting 5 seconds, so link preloads and route entry share one fetch.
 3. Refetches reactively by key on action revalidation.
 4. Serves as a back/forward cache for browser navigation up to 5 minutes; user-initiated navigation bypasses it.
 
@@ -783,17 +832,18 @@ Without a schema, `useSearchParams()` behaves as before: raw string values, merg
 createRouter(config);
 ```
 
-| option          | type                      | description                                                                                           |
-| --------------- | ------------------------- | ----------------------------------------------------------------------------------------------------- |
-| `routes`        | `RouteDefinition[]`       | The route tree — inline arrays infer literally; wrap extracted trees in `defineRoutes`                |
-| `base`          | `string`                  | Base url to use for matching routes                                                                   |
-| `preload`       | `RoutePreloadFunc`        | App-wide preload: once per mount/request, result reaches the root render-prop as `props.data`         |
-| `history`       | `RouterHistory`           | History adapter; defaults to browser history on the client and the request URL on the server          |
-| `singleFlight`  | `boolean`                 | Single-flight mutations, default `true`                                                               |
-| `actionBase`    | `string`                  | Root url for server actions, default `/_server`                                                       |
-| `preloadLinks`  | `boolean`                 | Preload route code/data on link hover and focus, default `true`                                       |
-| `explicitLinks` | `boolean`                 | Require the `link` attribute for router handling instead of intercepting all anchors, default `false` |
-| `transformUrl`  | `(url: string) => string` | Rewrite URLs before matching                                                                          |
+| option          | type                           | description                                                                                           |
+| --------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------- |
+| `routes`        | `RouteDefinition[]`            | The route tree — inline arrays infer literally; wrap extracted trees in `defineRoutes`                |
+| `base`          | `string`                       | Base url to use for matching routes                                                                   |
+| `preload`       | `RoutePreloadFunc`             | App-wide preload: once per mount/request, result reaches the root render-prop as `props.data`         |
+| `history`       | `RouterHistory`                | History adapter; defaults to browser history on the client and the request URL on the server          |
+| `singleFlight`  | `boolean`                      | Single-flight mutations, default `true`                                                               |
+| `actionBase`    | `string`                       | Root url for server actions, default `/_server`                                                       |
+| `preloadLinks`  | `LinkPreload \| LinkPreload[]` | [Link preload strategies](#preloading), e.g. `intentPreload()`; none by default. A boolean is a type error |
+| `explicitLinks` | `boolean`                      | Require the `link` attribute for router handling instead of intercepting all anchors, default `false` |
+| `links`         | `LinksPlugin`                  | Link claims plugin — `pendingLinks` adds `data-pending` to the in-flight navigation's target          |
+| `transformUrl`  | `(url: string) => string`      | Rewrite URLs before matching                                                                          |
 
 The returned instance is the provider component and carries the static surface:
 
@@ -850,14 +900,24 @@ See [Typed Search Params](#typed-search-params). Reads are proxied — access pr
 
 ### useIsRouting
 
-A signal indicating whether the router is processing a navigation — useful for pending UI while the next route and its data settle:
+A signal indicating whether the router is processing a navigation — useful for pending UI while the next route and its data settle. It's the way to read routing state: `RouterContext` doesn't carry `isRouting` or `pendingTarget`.
 
 ```tsx
 const isRouting = useIsRouting();
 return <div classList={{ "grey-out": isRouting() }}>...</div>;
 ```
 
-In Solid's dev and observe builds the router also declares every navigation to the attribution engine (`solid-js/attribution`): holds and re-runs caused by a navigation are named after the route pattern (`navigation to /users/:id`), timed from the user event that started it, and redirect hops fold onto the navigation they belong to. `attribution.history("navigation")` and `feedback().navigations` list them; nothing of this exists in production builds.
+The router doesn't expose where a navigation is heading; read it off the location with Solid's `isPending` and `latest`. It covers back/forward traversals too:
+
+```tsx
+import { isPending, latest } from "solid-js";
+
+const location = useLocation();
+const target = () =>
+  isPending(() => location.pathname) ? latest(() => location.pathname) : undefined;
+```
+
+In Solid's dev and observe builds the router also declares every navigation to the attribution engine (`solid-js/attribution`): holds and re-runs caused by a navigation are named after the route pattern (`navigation to /users/:id`), timed from the user event that started it, and redirect hops fold onto the navigation they belong to. A link click or a native form submit the router handles runs in the interaction Solid records for that event, so the navigation or action belongs to the same record as any `onClick` work for that click. `attribution.history("navigation")` and `feedback().navigations` list them; nothing of this exists in production builds.
 
 ### useMatch
 
@@ -892,7 +952,7 @@ declare module "@solidjs/router" {
 
 ### usePreloadRoute
 
-Returns a function to preload a route manually — the same work link hover/focus triggers automatically. Accepts strings, URLs, and typed path nodes:
+Returns a function to preload a route manually — the same work [link preloading](#preloading) triggers automatically. Accepts strings, URLs, and typed path nodes:
 
 ```tsx
 const preload = usePreloadRoute();
@@ -905,7 +965,7 @@ Reactive `active`/`current`/`pending` state for [custom link components](#links)
 
 - `current()` — same path and same query as the location, ignoring parameter order and the hash (what `aria-current="page"` reflects)
 - `active()` — the location's path is the link's path or lives under it, query ignored (`data-active`); a root link (`/`, which resolves to the router's `base`) is exact-only
-- `pending()` — the link's path is the target of an in-flight navigation (`data-pending`)
+- `pending()` — the link's path is the target of an in-flight navigation, back/forward excluded (`data-pending`). Works without the [`pendingLinks`](#links) plugin, which only adds the attribute to plain anchors
 
 Pass `{ end: true }` to make `active` (and `pending`) exact-path for any link.
 
@@ -1032,8 +1092,10 @@ Route props map 1:1 onto definition keys (`path`, `component`, `preload`, `match
 - `<A href replace noScroll state>` → `<a href replace noscroll state>` (attributes, all lowercase)
 - `activeClass` / `inactiveClass` → CSS attribute selectors on `[data-active]` / `[aria-current="page"]`
 - `end` → style exact matches with `[aria-current="page"]` (which also compares the query) instead of `[data-active]`; the root path already only matches exactly
+- Pending link styling → `[data-pending]`, opt-in with `createRouter({ routes, links: pendingLinks })`
 - Route-relative hrefs → typed `paths`; `useResolvedPath` / `useHref` remain for manual resolution
 - Custom link components → `useLinkState`
+- Hover/focus preloading is opt-in → `createRouter({ routes, preloadLinks: intentPreload() })`; `preload="false"` on a link skips it entirely. The previous `next` prerelease preloaded on hover by default
 
 ### Removed and renamed
 
@@ -1042,6 +1104,7 @@ Route props map 1:1 onto definition keys (`path`, `component`, `preload`, `match
 - `redirect` / `reload` → import from `@solidjs/web`; they're protocol-level and work without the router
 - `json(data, init)` → `respond(data, init)` from `@solidjs/web`
 - `cache` (deprecated alias) → `query`
+- `RouterContext`'s `isRouting` / `pendingTarget` → `useIsRouting()`; for the in-flight destination, the [`isPending`/`latest` recipe](#useisrouting)
 
 ### Data APIs (Solid 2)
 

package/dist/claims.d.ts

@@ -1,4 +1,4 @@
-import type { RouterContext } from "./types.js";
+import type { LinksPlugin, RouterContext } from "./types.js";
 export declare function setFormClaimHandler(handler: ((form: HTMLFormElement) => void) | undefined): void;
 /**
  * The compiler claims every `a[href]` and `form[action]` at creation, and the
@@ -11,9 +11,11 @@ export declare function setFormClaimHandler(handler: ((form: HTMLFormElement) =>
  *   included (parameter order aside)
  * - `data-active` — pathname exact or prefix match (the router's root, its
  *   base path, exact only)
- * - `data-pending` — the link is the target of an in-flight navigation
+ * - `data-pending` — the link is the target of an in-flight navigation;
+ *   opt-in through `createRouter({ links: pendingLinks })`. Without the
+ *   plugin, claims never read pending state and the sweep does not track it.
  *
- * The matching rule is `matchLink`, shared with `useLinkState`. The router
+ * The matching rule is `linkMatcher`, shared with `useLinkState`. The router
  * only touches an `aria-current` it wrote itself: one the author set (a
  * stepper's `"step"`, a static `"page"`) is left in place, current or not.
  *
@@ -26,4 +28,4 @@ export declare function setFormClaimHandler(handler: ((form: HTMLFormElement) =>
  * are the same one-shot untracked refresh, reading the element's current
  * `href` from the DOM.
  */
-export declare function setupLinkClaims(router: RouterContext, explicitLinks?: boolean): void;
+export declare function setupLinkClaims(router: RouterContext, explicitLinks?: boolean, links?: LinksPlugin): void;

package/dist/claims.js

@@ -1,6 +1,6 @@
 import { registerElementClaim } from "@solidjs/web";
 import { createRenderEffect, getOwner, onCleanup, untrack } from "solid-js";
-import { isUnderBase, matchLink } from "./utils.js";
+import { isUnderBase, linkMatcher } from "./utils.js";
 /**
  * Claimed forms are handed to this slot instead of the claims importing the
  * action module: the action side installs it on first action creation (see
@@ -22,9 +22,11 @@ export function setFormClaimHandler(handler) {
  *   included (parameter order aside)
  * - `data-active` — pathname exact or prefix match (the router's root, its
  *   base path, exact only)
- * - `data-pending` — the link is the target of an in-flight navigation
+ * - `data-pending` — the link is the target of an in-flight navigation;
+ *   opt-in through `createRouter({ links: pendingLinks })`. Without the
+ *   plugin, claims never read pending state and the sweep does not track it.
  *
- * The matching rule is `matchLink`, shared with `useLinkState`. The router
+ * The matching rule is `linkMatcher`, shared with `useLinkState`. The router
  * only touches an `aria-current` it wrote itself: one the author set (a
  * stepper's `"step"`, a static `"page"`) is left in place, current or not.
  *
@@ -37,8 +39,9 @@ export function setFormClaimHandler(handler) {
  * are the same one-shot untracked refresh, reading the element's current
  * `href` from the DOM.
  */
-export function setupLinkClaims(router, explicitLinks) {
+export function setupLinkClaims(router, explicitLinks, links) {
     const basePath = router.base.path();
+    const plugin = links && links(router, basePath);
     // per-element record; `owned` is whether the `aria-current` on the element
     // is the router's, so it never writes over or removes an authored one
     const claimed = new WeakMap();
@@ -72,26 +75,31 @@ export function setupLinkClaims(router, explicitLinks) {
             return;
         return url;
     }
+    // every anchor matches against the same location, so its parse is shared
+    // until the location changes
+    let matched;
+    let match;
     function linkState(a) {
         // read reactive sources unconditionally so the owning effect stays
         // subscribed even while the anchor is not router-managed
         const location = router.location;
-        const routing = router.isRouting();
+        const routing = plugin && plugin.track();
         const url = managedUrl(a);
         const target = url && url.pathname + url.search;
+        const key = location.pathname + location.search;
         // no per-anchor `end` opt-out like useLinkState has
-        const { active, current } = matchLink(location, target, basePath);
-        // effects observe the committed location during a transition, so the
-        // in-flight target comes from pendingTarget — readable here because the
-        // isRouting write flushes after the target is assigned
-        const pending = routing &&
-            !!router.pendingTarget &&
-            matchLink({ pathname: router.pendingTarget.value, search: "" }, target, basePath).active;
+        if (key !== matched) {
+            matched = key;
+            match = linkMatcher(location, basePath);
+        }
+        const { active, current } = match(target);
+        const pending = !!routing && plugin.pending(target);
         return { active, pending, current };
     }
     function apply(a, rec, { active, pending, current }) {
         active ? a.setAttribute("data-active", "") : a.removeAttribute("data-active");
-        pending ? a.setAttribute("data-pending", "") : a.removeAttribute("data-pending");
+        if (plugin)
+            pending ? a.setAttribute("data-pending", "") : a.removeAttribute("data-pending");
         // Ownership is read against the element, not just the record. A
         // server-component morph resets attributes to the server HTML, which
         // never carries router link state, then re-claims: an owned value that
@@ -114,9 +122,10 @@ export function setupLinkClaims(router, explicitLinks) {
     }
     const refresh = (a, rec) => untrack(() => apply(a, rec, linkState(a)));
     // The one subscription for every anchor: compute tracks the sources
-    // linkState derives from (the in-flight pendingTarget is readable in the
-    // effect phase because the isRouting write flushes after the target is
-    // assigned), the effect phase sweeps the registry untracked.
+    // linkState derives from (with the plugin, its pending read — the
+    // in-flight target is readable in the effect phase because the isRouting
+    // write flushes after the target is assigned), the effect phase sweeps the
+    // registry untracked.
     //
     // `transparent` keeps the effect invisible to the hydration id scheme.
     // This setup is client-only, so an id-consuming node here has no server
@@ -124,7 +133,7 @@ export function setupLinkClaims(router, explicitLinks) {
     // slot — lazy-route lookups miss and hydration leaves server nodes
     // unclaimed. (The option is honored by the runtime but missing from the
     // published EffectOptions type, hence the cast.)
-    createRenderEffect(() => (router.location.pathname, router.location.search, router.isRouting()), () => registry.forEach(a => refresh(a, claimed.get(a))), { transparent: true });
+    createRenderEffect(() => (router.location.pathname, router.location.search, plugin && plugin.track()), () => registry.forEach(a => refresh(a, claimed.get(a))), { transparent: true });
     onCleanup(registerElementClaim(node => {
         const name = node.nodeName.toUpperCase();
         if (name === "FORM")

package/dist/data/events.d.ts

@@ -1,4 +1,4 @@
-import type { RouterContext } from "../types.js";
+import type { LinkPreload, RouterContext } from "../types.js";
 /**
  * The submit delegation consults this slot instead of importing the action
  * module: the action side installs its handler on first action creation
@@ -7,11 +7,18 @@ import type { RouterContext } from "../types.js";
  */
 export type RouterFormHandler = (evt: SubmitEvent, router: RouterContext, actionBase: string) => void;
 export declare function setRouterFormHandler(handler: RouterFormHandler | undefined): void;
+/**
+ * Link preload strategies reach route preloading through this slot instead
+ * of the event wiring importing it: a strategy installs it when it runs (see
+ * preload.ts), so an app with no strategy and no `usePreloadRoute` never
+ * ships route preloading.
+ */
+declare let linkPreloader: ((router: RouterContext, url: URL, data: boolean) => void) | undefined;
+export declare function setLinkPreloader(preloader: typeof linkPreloader): void;
 type NativeEventConfig = {
-    preload?: boolean;
+    preload?: LinkPreload | readonly LinkPreload[];
     explicitLinks?: boolean;
     actionBase?: string;
-    transformUrl?: (url: string) => string;
 };
-export declare function setupNativeEvents({ preload, explicitLinks, actionBase, transformUrl }?: NativeEventConfig): (router: RouterContext) => void;
+export declare function setupNativeEvents({ preload, explicitLinks, actionBase }?: NativeEventConfig): (router: RouterContext) => void;
 export {};

package/dist/data/events.js

@@ -1,16 +1,24 @@
-import { delegateEvents } from "@solidjs/web";
+import { delegateEvents, dispatchAsInteraction } from "@solidjs/web";
 import { onCleanup } from "solid-js";
 import { isUnderBase } from "../utils.js";
 let formHandler;
 export function setRouterFormHandler(handler) {
     formHandler = handler;
 }
-export function setupNativeEvents({ preload = true, explicitLinks = false, actionBase = "/_server", transformUrl } = {}) {
+/**
+ * Link preload strategies reach route preloading through this slot instead
+ * of the event wiring importing it: a strategy installs it when it runs (see
+ * preload.ts), so an app with no strategy and no `usePreloadRoute` never
+ * ships route preloading.
+ */
+let linkPreloader;
+export function setLinkPreloader(preloader) {
+    linkPreloader = preloader;
+}
+export function setupNativeEvents({ preload, explicitLinks = false, actionBase = "/_server" } = {}) {
     return (router) => {
         const basePath = router.base.path();
         const navigateFromRoute = router.navigatorFactory(router.base);
-        let preloadTimeout;
-        let lastElement;
         function isSvg(el) {
             return el.namespaceURI === "http://www.w3.org/2000/svg";
         }
@@ -22,10 +30,19 @@ export function setupNativeEvents({ preload = true, explicitLinks = false, actio
                 evt.ctrlKey ||
                 evt.shiftKey)
                 return;
+            return findAnchor(evt);
+        }
+        // no button or modifier gate: focus and touch events carry neither
+        function findAnchor(evt) {
             const a = evt
                 .composedPath()
                 .find(el => el instanceof Node && el.nodeName.toUpperCase() === "A");
-            if (!a || (explicitLinks && !a.hasAttribute("link")))
+            const url = a && anchorUrl(a);
+            return url && [a, url];
+        }
+        /** The anchor's URL when the router manages it, else `undefined`. */
+        function anchorUrl(a) {
+            if (explicitLinks && !a.hasAttribute("link"))
                 return;
             const svg = isSvg(a);
             const href = svg ? a.href.baseVal : a.href;
@@ -42,7 +59,7 @@ export function setupNativeEvents({ preload = true, explicitLinks = false, actio
                 return;
             if (url.origin !== window.location.origin || !isUnderBase(url.pathname, basePath))
                 return;
-            return [a, url];
+            return url;
         }
         function handleAnchorClick(evt) {
             const res = handleAnchor(evt);
@@ -52,34 +69,14 @@ export function setupNativeEvents({ preload = true, explicitLinks = false, actio
             const to = router.parsePath(url.pathname + url.search + url.hash);
             const state = a.getAttribute("state");
             evt.preventDefault();
-            navigateFromRoute(to, {
+            // Only a click the router acts on joins the event's interaction: this
+            // listener hears every click on the document.
+            dispatchAsInteraction(evt, () => navigateFromRoute(to, {
                 resolve: false,
                 replace: a.hasAttribute("replace"),
                 scroll: !a.hasAttribute("noscroll"),
                 state: state ? JSON.parse(state) : undefined
-            });
-        }
-        function handleAnchorPreload(evt) {
-            const res = handleAnchor(evt);
-            if (!res)
-                return;
-            const [a, url] = res;
-            transformUrl && (url.pathname = transformUrl(url.pathname));
-            router.preloadRoute(url, a.getAttribute("preload") !== "false");
-        }
-        function handleAnchorMove(evt) {
-            clearTimeout(preloadTimeout);
-            const res = handleAnchor(evt);
-            if (!res)
-                return (lastElement = null);
-            const [a, url] = res;
-            if (lastElement === a)
-                return;
-            transformUrl && (url.pathname = transformUrl(url.pathname));
-            preloadTimeout = setTimeout(() => {
-                router.preloadRoute(url, a.getAttribute("preload") !== "false");
-                lastElement = a;
-            }, 20);
+            }));
         }
         function handleFormSubmit(evt) {
             if (formHandler)
@@ -102,27 +99,30 @@ export function setupNativeEvents({ preload = true, explicitLinks = false, actio
             const path = router.parsePath(url.pathname + url.search);
             if (!path.startsWith(actionBase) || form.method.toUpperCase() !== "POST")
                 return;
-            evt.preventDefault();
-            const data = new FormData(form, evt.submitter);
-            import("./serverForms.js").then(m => m.submitServerForm(router, path, form, data));
+            // The import sits inside the check so bundlers drop the server-forms
+            // chunk. An early return above a still-present import() does not.
+            // Missing stays off: an undefined constant does not fold.
+            if (typeof __SOLID_SERVER_COMPONENTS__ !== "undefined" && __SOLID_SERVER_COMPONENTS__) {
+                evt.preventDefault();
+                const data = new FormData(form, evt.submitter);
+                import("./serverForms.js").then(m => m.submitServerForm(router, path, form, data));
+            }
         }
+        const handleSubmit = (evt) => dispatchAsInteraction(evt, () => handleFormSubmit(evt));
         // ensure delegated event run first
         delegateEvents(["click", "submit"]);
         document.addEventListener("click", handleAnchorClick);
-        if (preload) {
-            document.addEventListener("mousemove", handleAnchorMove, { passive: true });
-            document.addEventListener("focusin", handleAnchorPreload, { passive: true });
-            document.addEventListener("touchstart", handleAnchorPreload, { passive: true });
-        }
-        document.addEventListener("submit", handleFormSubmit);
+        document.addEventListener("submit", handleSubmit);
         onCleanup(() => {
             document.removeEventListener("click", handleAnchorClick);
-            if (preload) {
-                document.removeEventListener("mousemove", handleAnchorMove);
-                document.removeEventListener("focusin", handleAnchorPreload);
-                document.removeEventListener("touchstart", handleAnchorPreload);
-            }
-            document.removeEventListener("submit", handleFormSubmit);
+            document.removeEventListener("submit", handleSubmit);
         });
+        // the pre-strategy boolean option is ignored (a dev warning names it)
+        if (preload && preload !== true)
+            [].concat(preload).forEach(strategy => strategy({
+                anchor: findAnchor,
+                url: anchorUrl,
+                preload: (url, data) => linkPreloader(router, url, data)
+            }));
     };
 }

package/dist/index.d.ts

@@ -19,11 +19,14 @@ export interface RouteInfo {
 }
 export * from "./routers/index.js";
 export * from "./lifecycle.js";
-export { useHref, useIsRouting, useLinkState, useLocation, useMatch, useNavigate, usePreloadRoute, useParams, useResolvedPath, useRouteMatches, useSearchParams, RouterContextObj as RouterContext } from "./routing.js";
+export { useHref, useIsRouting, useLinkState, useLocation, useMatch, useNavigate, useParams, useResolvedPath, useRouteMatches, useSearchParams, RouterContextObj as RouterContext } from "./routing.js";
 export type { LinkState } from "./routing.js";
+export { pendingLinks } from "./pending.js";
+export { eagerPreload, intentPreload, tapPreload, viewportPreload } from "./preload.js";
+export { usePreloadRoute } from "./preloadRoute.js";
 export { mergeSearchString as _mergeSearchString } from "./utils.js";
 export { int } from "./paths.js";
 export { serverRouteComponent } from "./serverRouteComponent.js";
 export type { RoutePaths, PathParamsOf, PathEnd, TypedMatchFilter, DefaultSearchTypes } from "./paths.js";
 export * from "./data/index.js";
-export type { Location, LocationChange, LocationWrite, SearchParams, MatchFilter, MatchFilters, NavigateOptions, Navigator, OutputMatch, Params, PathMatch, RouteComponent, RouteParams, RouteProps, RouteSectionProps, RoutePreloadFunc, RoutePreloadFuncArgs, RouteDefinition, RouteDescription, RouteMatch, RouterIntegration, RouterUtils, SetParams, SetSearchParams, ServerRouteArgs, ServerRouteParams, ServerRouteFunction, ServerRouteView, Submission, BeforeLeaveEventArgs, TypedPath, TypedSearchPath, StandardSchemaV1 } from "./types.js";
+export type { LinkPreload, LinksPlugin, Location, LocationChange, LocationWrite, SearchParams, MatchFilter, MatchFilters, NavigateOptions, Navigator, OutputMatch, Params, PathMatch, RouteComponent, RouteParams, RouteProps, RouteSectionProps, RoutePreloadFunc, RoutePreloadFuncArgs, RouteDefinition, RouteDescription, RouteMatch, RouterIntegration, RouterUtils, SetParams, SetSearchParams, ServerRouteArgs, ServerRouteParams, ServerRouteFunction, ServerRouteView, Submission, BeforeLeaveEventArgs, TypedPath, TypedSearchPath, StandardSchemaV1 } from "./types.js";