@real-router/preload-plugin 0.0.1

package/README.md

@@ -0,0 +1,221 @@
+# @real-router/preload-plugin
+
+[![npm](https://img.shields.io/npm/v/@real-router/preload-plugin.svg?style=flat-square)](https://www.npmjs.com/package/@real-router/preload-plugin)
+[![npm downloads](https://img.shields.io/npm/dm/@real-router/preload-plugin.svg?style=flat-square)](https://www.npmjs.com/package/@real-router/preload-plugin)
+[![bundle size](https://deno.bundlejs.com/?q=@real-router/preload-plugin&treeshake=[*]&badge=detailed)](https://bundlejs.com/?q=@real-router/preload-plugin&treeshake=[*])
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](../../LICENSE)
+
+> Preload on navigation intent for [Real-Router](https://github.com/greydragon888/real-router). Trigger data preloading when users hover over or touch links — before they click.
+
+```typescript
+// Without plugin — data loads AFTER navigation:
+// click → navigate → render → fetch → re-render (waterfall)
+
+// With plugin — data loads BEFORE navigation:
+// hover → preload → click → navigate → render (data ready)
+```
+
+## Installation
+
+```bash
+npm install @real-router/preload-plugin
+```
+
+**Peer dependency:** `@real-router/core`
+
+**Runtime dependency:** `@real-router/browser-plugin` must be registered (provides `matchUrl` for URL → route resolution).
+
+## Quick Start
+
+```typescript
+import { createRouter } from "@real-router/core";
+import { browserPluginFactory } from "@real-router/browser-plugin";
+import { preloadPluginFactory } from "@real-router/preload-plugin";
+
+const routes = [
+  {
+    name: "users.profile",
+    path: "/users/:id",
+    preload: async (params) => {
+      await queryClient.prefetchQuery({
+        queryKey: ["user", params.id],
+        queryFn: () => fetchUser(params.id),
+      });
+    },
+  },
+  {
+    name: "products.detail",
+    path: "/products/:slug",
+    preload: async (params) => {
+      await productStore.prefetch(params.slug);
+    },
+  },
+];
+
+const router = createRouter(routes);
+router.usePlugin(browserPluginFactory(), preloadPluginFactory());
+
+await router.start();
+```
+
+When a user hovers over a `<Link routeName="users.profile" routeParams={{ id: '123' }}>` for 65ms, the plugin calls `preload({ id: '123' })` — warming up your data layer before navigation.
+
+## Options
+
+```typescript
+router.usePlugin(
+  preloadPluginFactory({
+    delay: 100, // Hover debounce in ms (default: 65)
+    networkAware: true, // Disable on Save-Data / 2G (default: true)
+  }),
+);
+```
+
+| Option         | Type      | Default | Description                                          |
+| -------------- | --------- | ------- | ---------------------------------------------------- |
+| `delay`        | `number`  | `65`    | Milliseconds to wait before triggering hover preload |
+| `networkAware` | `boolean` | `true`  | Skip preloading on Save-Data or 2G connections       |
+
+## How It Works
+
+### Zero adapter changes
+
+The plugin uses **DOM-level event delegation** — listeners on `document`, not on individual `<Link>` components. No modifications to React, Vue, Preact, Solid, or Svelte adapters.
+
+### Intent detection
+
+| Trigger   | Event        | Timing                    | Rationale                      |
+| --------- | ------------ | ------------------------- | ------------------------------ |
+| **Hover** | `mouseover`  | Debounced (configurable)  | Filter accidental mouse passes |
+| **Touch** | `touchstart` | ~100ms (scroll detection) | Touch = strong intent signal   |
+
+### Route resolution
+
+```
+anchor.href → router.matchUrl(href) → State → getRouteConfig(state.name)?.preload → call
+```
+
+External links, routes without `preload`, and non-matching URLs are silently skipped.
+
+### Mobile support
+
+- **Touch preloading**: `touchstart` triggers preload with minimal delay
+- **Scroll detection**: `touchmove` with >10px vertical movement cancels pending preload
+- **Ghost event suppression**: Synthetic `mouseover` events fired by mobile browsers after `touchstart` are suppressed (prevents double-preload)
+
+All listeners use `{ passive: true }` — never blocks scrolling.
+
+### Network awareness
+
+Preloading is automatically disabled when:
+
+- `navigator.connection.saveData` is enabled
+- `navigator.connection.effectiveType` is `2g` or `slow-2g`
+
+Disable with `networkAware: false` if your preload functions handle this themselves.
+
+## Per-Link Opt-Out
+
+```html
+<!-- Disable preloading for a specific link -->
+<a href="/heavy-page" data-no-preload>Heavy Page</a>
+```
+
+Works in all frameworks via prop pass-through:
+
+```tsx
+<Link routeName="heavy" data-no-preload>
+  Heavy Page
+</Link>
+```
+
+## Router Extension
+
+The plugin adds one method to the router:
+
+```typescript
+router.getPreloadSettings();
+// → { delay: 65, networkAware: true }
+```
+
+## Data Layer Integration
+
+The plugin is **data-agnostic** — it calls your `preload` function and doesn't care about the result. You control what happens inside:
+
+### TanStack Query
+
+```typescript
+{
+  name: "users.profile",
+  path: "/users/:id",
+  preload: async (params) => {
+    await queryClient.prefetchQuery({
+      queryKey: ["user", params.id],
+      queryFn: () => fetchUser(params.id),
+    });
+  },
+}
+```
+
+### Zustand / Pinia / Custom Store
+
+```typescript
+{
+  name: "products.detail",
+  path: "/products/:slug",
+  preload: async (params) => {
+    await productStore.prefetch(params.slug);
+  },
+}
+```
+
+### Multiple Concerns
+
+```typescript
+{
+  name: "dashboard",
+  path: "/dashboard",
+  preload: async () => {
+    await Promise.all([
+      queryClient.prefetchQuery({ queryKey: ["stats"], queryFn: fetchStats }),
+      queryClient.prefetchQuery({ queryKey: ["recent"], queryFn: fetchRecent }),
+    ]);
+  },
+}
+```
+
+Errors in `preload` are silently caught — error handling is your data layer's responsibility.
+
+## SSR Support
+
+The plugin is SSR-safe — returns an empty plugin object when `document` is not available:
+
+```typescript
+// Server-side — no errors, no listeners
+router.usePlugin(preloadPluginFactory());
+```
+
+## Graceful Degradation
+
+Without `browser-plugin`, `router.matchUrl` is `undefined`. The plugin silently skips preloading via optional chaining — no errors, no warnings.
+
+## Documentation
+
+- [ARCHITECTURE.md](ARCHITECTURE.md) — Design decisions and data flow
+- [Plugin Architecture](https://github.com/greydragon888/real-router/wiki/plugin-architecture) — How plugins integrate with the router
+
+## Related Packages
+
+| Package                                                                                      | Description                            |
+| -------------------------------------------------------------------------------------------- | -------------------------------------- |
+| [@real-router/core](https://www.npmjs.com/package/@real-router/core)                         | Core router (required peer dependency) |
+| [@real-router/browser-plugin](https://www.npmjs.com/package/@real-router/browser-plugin)     | Browser plugin (provides `matchUrl`)   |
+| [@real-router/lifecycle-plugin](https://www.npmjs.com/package/@real-router/lifecycle-plugin) | Route-level lifecycle hooks            |
+
+## Contributing
+
+See [contributing guidelines](../../CONTRIBUTING.md) for development setup and PR process.
+
+## License
+
+[MIT](../../LICENSE) © [Oleg Ivanov](https://github.com/greydragon888)

package/dist/cjs/index.d.ts

@@ -0,0 +1,25 @@
+import { Params, PluginFactory } from "@real-router/core";
+
+//#region src/types.d.ts
+interface PreloadPluginOptions {
+  /** Hover debounce delay in ms. @default 65 */
+  delay?: number;
+  /** Check saveData/2g and disable preloading on slow connections. @default true */
+  networkAware?: boolean;
+}
+//#endregion
+//#region src/factory.d.ts
+declare function preloadPluginFactory(opts?: Partial<PreloadPluginOptions>): PluginFactory;
+//#endregion
+//#region src/index.d.ts
+declare module "@real-router/core" {
+  interface Route {
+    preload?: (params: Params) => Promise<unknown>;
+  }
+  interface Router {
+    getPreloadSettings(): PreloadPluginOptions;
+  }
+}
+//#endregion
+export { type PreloadPluginOptions, preloadPluginFactory };
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/index.js

@@ -0,0 +1,2 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require(`@real-router/core/api`);const t={delay:65,networkAware:!0};function n(){let e=navigator.connection;return e?!!(e.saveData||e.effectiveType?.includes(`2g`)):!1}var r=class{#e;#t;#n;#r;#i=null;#a=null;#o=null;#s=0;#c=null;constructor(e,t,n){this.#e=e,this.#t=t,this.#n=n,this.#r=t.extendRouter({getPreloadSettings:()=>({...n})})}getPlugin(){return{onStart:()=>{document.addEventListener(`mouseover`,this.#l,{capture:!0,passive:!0}),document.addEventListener(`touchstart`,this.#u,{capture:!0,passive:!0}),document.addEventListener(`touchmove`,this.#d,{capture:!0,passive:!0})},onStop:()=>{this.#_()},teardown:()=>{this.#_(),this.#r()}}}#l=e=>{if(this.#m(e))return;let t=e.target;if(!t||!(`closest`in t)){this.#h();return}let n=t.closest(`a[href]`);if(n===this.#i)return;this.#h(),this.#i=n;let r=this.#f(n);r&&(this.#a=setTimeout(()=>{this.#a=null,r.fn(r.params).catch(()=>{})},this.#n.delay))};#u=e=>{this.#c={target:e.target,timeStamp:e.timeStamp},this.#g();let t=e.target,n=t&&`closest`in t?t.closest(`a[href]`):null,r=this.#f(n);r&&(this.#s=e.touches[0].clientY,this.#o=setTimeout(()=>{this.#o=null,r.fn(r.params).catch(()=>{})},100))};#d=e=>{this.#o!==null&&Math.abs(e.touches[0].clientY-this.#s)>10&&this.#g()};#f(e){if(e&&!(`noPreload`in e.dataset)&&!(this.#n.networkAware&&n()))return this.#p(e)}#p(e){let t=this.#e.matchUrl?.(e.href);if(!t)return;let n=this.#t.getRouteConfig(t.name);if(typeof n?.preload==`function`)return{fn:n.preload,params:t.params}}#m(e){return this.#c!==null&&e.target===this.#c.target&&e.timeStamp-this.#c.timeStamp<2500}#h(){this.#a!==null&&(clearTimeout(this.#a),this.#a=null),this.#i=null}#g(){this.#o!==null&&(clearTimeout(this.#o),this.#o=null)}#_(){document.removeEventListener(`mouseover`,this.#l,{capture:!0}),document.removeEventListener(`touchstart`,this.#u,{capture:!0}),document.removeEventListener(`touchmove`,this.#d,{capture:!0}),this.#h(),this.#g(),this.#c=null}};function i(n){let i={...t,...n};return function(t){return typeof document>`u`?{}:new r(t,(0,e.getPluginApi)(t),i).getPlugin()}}exports.preloadPluginFactory=i;
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["#router","#api","#options","#removeExtensions","#handleMouseOver","#handleTouchStart","#handleTouchMove","#cleanup","#isGhostMouseEvent","#cancelHover","#currentAnchor","#resolveAnchorPreload","#hoverTimer","#lastTouchStartEvent","#cancelTouch","#touchStartY","#touchTimer","#resolvePreload"],"sources":["../../src/constants.ts","../../src/network.ts","../../src/plugin.ts","../../src/factory.ts"],"sourcesContent":["import type { PreloadPluginOptions } from \"./types\";\n\nexport const defaultOptions: Required<PreloadPluginOptions> = {\n  delay: 65,\n  networkAware: true,\n};\n\nexport const GHOST_EVENT_THRESHOLD = 2500;\n\nexport const TOUCH_SCROLL_THRESHOLD = 10;\n\nexport const TOUCH_PRELOAD_DELAY = 100;\n","type NetworkConnection =\n  | { saveData?: boolean; effectiveType?: string }\n  | undefined;\n\ninterface NavigatorWithConnection extends Navigator {\n  connection?: NetworkConnection;\n}\n\nexport function isSlowConnection(): boolean {\n  const connection = (navigator as NavigatorWithConnection).connection;\n\n  if (!connection) {\n    return false;\n  }\n  if (connection.saveData) {\n    return true;\n  }\n  if (connection.effectiveType?.includes(\"2g\")) {\n    return true;\n  }\n\n  return false;\n}\n","import {\n  GHOST_EVENT_THRESHOLD,\n  TOUCH_PRELOAD_DELAY,\n  TOUCH_SCROLL_THRESHOLD,\n} from \"./constants\";\nimport { isSlowConnection } from \"./network\";\n\nimport type { PreloadPluginOptions } from \"./types\";\nimport type { Params, Plugin, Router, State } from \"@real-router/core\";\nimport type { PluginApi } from \"@real-router/core/api\";\n\ndeclare module \"@real-router/core\" {\n  interface Router {\n    matchUrl?: (url: string) => State | undefined;\n  }\n}\n\nexport class PreloadPlugin {\n  readonly #router: Router;\n  readonly #api: PluginApi;\n  readonly #options: Required<PreloadPluginOptions>;\n  readonly #removeExtensions: () => void;\n\n  #currentAnchor: HTMLAnchorElement | null = null;\n  #hoverTimer: ReturnType<typeof setTimeout> | null = null;\n  #touchTimer: ReturnType<typeof setTimeout> | null = null;\n  #touchStartY = 0;\n  #lastTouchStartEvent: {\n    target: EventTarget | null;\n    timeStamp: number;\n  } | null = null;\n\n  constructor(\n    router: Router,\n    api: PluginApi,\n    options: Required<PreloadPluginOptions>,\n  ) {\n    this.#router = router;\n    this.#api = api;\n    this.#options = options;\n\n    this.#removeExtensions = api.extendRouter({\n      getPreloadSettings: () => ({ ...options }),\n    });\n  }\n\n  getPlugin(): Plugin {\n    return {\n      onStart: () => {\n        document.addEventListener(\"mouseover\", this.#handleMouseOver, {\n          capture: true,\n          passive: true,\n        });\n        document.addEventListener(\"touchstart\", this.#handleTouchStart, {\n          capture: true,\n          passive: true,\n        });\n        document.addEventListener(\"touchmove\", this.#handleTouchMove, {\n          capture: true,\n          passive: true,\n        });\n      },\n\n      onStop: () => {\n        this.#cleanup();\n      },\n\n      teardown: () => {\n        this.#cleanup();\n        this.#removeExtensions();\n      },\n    };\n  }\n\n  readonly #handleMouseOver = (event: MouseEvent): void => {\n    if (this.#isGhostMouseEvent(event)) {\n      return;\n    }\n\n    const target = event.target as Element | null;\n\n    if (!target || !(\"closest\" in target)) {\n      this.#cancelHover();\n\n      return;\n    }\n\n    const anchor = target.closest<HTMLAnchorElement>(\"a[href]\");\n\n    if (anchor === this.#currentAnchor) {\n      return;\n    }\n\n    this.#cancelHover();\n    this.#currentAnchor = anchor;\n\n    const preload = this.#resolveAnchorPreload(anchor);\n\n    if (!preload) {\n      return;\n    }\n\n    this.#hoverTimer = setTimeout(() => {\n      this.#hoverTimer = null;\n      preload.fn(preload.params).catch(() => {});\n    }, this.#options.delay);\n  };\n\n  readonly #handleTouchStart = (event: TouchEvent): void => {\n    this.#lastTouchStartEvent = {\n      target: event.target,\n      timeStamp: event.timeStamp,\n    };\n\n    this.#cancelTouch();\n\n    const target = event.target as Element | null;\n    const anchor =\n      target && \"closest\" in target\n        ? target.closest<HTMLAnchorElement>(\"a[href]\")\n        : null;\n    const preload = this.#resolveAnchorPreload(anchor);\n\n    if (!preload) {\n      return;\n    }\n\n    this.#touchStartY = event.touches[0].clientY;\n\n    this.#touchTimer = setTimeout(() => {\n      this.#touchTimer = null;\n      preload.fn(preload.params).catch(() => {});\n    }, TOUCH_PRELOAD_DELAY);\n  };\n\n  readonly #handleTouchMove = (event: TouchEvent): void => {\n    if (this.#touchTimer === null) {\n      return;\n    }\n\n    const deltaY = Math.abs(event.touches[0].clientY - this.#touchStartY);\n\n    if (deltaY > TOUCH_SCROLL_THRESHOLD) {\n      this.#cancelTouch();\n    }\n  };\n\n  #resolveAnchorPreload(\n    anchor: HTMLAnchorElement | null | undefined,\n  ): { fn: (params: Params) => Promise<unknown>; params: Params } | undefined {\n    if (!anchor) {\n      return undefined;\n    }\n\n    if (\"noPreload\" in anchor.dataset) {\n      return undefined;\n    }\n\n    if (this.#options.networkAware && isSlowConnection()) {\n      return undefined;\n    }\n\n    return this.#resolvePreload(anchor);\n  }\n\n  #resolvePreload(\n    anchor: HTMLAnchorElement,\n  ): { fn: (params: Params) => Promise<unknown>; params: Params } | undefined {\n    const state = this.#router.matchUrl?.(anchor.href);\n\n    if (!state) {\n      return undefined;\n    }\n\n    const config = this.#api.getRouteConfig(state.name);\n\n    if (typeof config?.preload !== \"function\") {\n      return undefined;\n    }\n\n    return {\n      fn: config.preload as (params: Params) => Promise<unknown>,\n      params: state.params,\n    };\n  }\n\n  #isGhostMouseEvent(event: MouseEvent): boolean {\n    return (\n      this.#lastTouchStartEvent !== null &&\n      event.target === this.#lastTouchStartEvent.target &&\n      event.timeStamp - this.#lastTouchStartEvent.timeStamp <\n        GHOST_EVENT_THRESHOLD\n    );\n  }\n\n  #cancelHover(): void {\n    if (this.#hoverTimer !== null) {\n      clearTimeout(this.#hoverTimer);\n      this.#hoverTimer = null;\n    }\n\n    this.#currentAnchor = null;\n  }\n\n  #cancelTouch(): void {\n    if (this.#touchTimer !== null) {\n      clearTimeout(this.#touchTimer);\n      this.#touchTimer = null;\n    }\n  }\n\n  #cleanup(): void {\n    document.removeEventListener(\"mouseover\", this.#handleMouseOver, {\n      capture: true,\n    });\n    document.removeEventListener(\"touchstart\", this.#handleTouchStart, {\n      capture: true,\n    });\n    document.removeEventListener(\"touchmove\", this.#handleTouchMove, {\n      capture: true,\n    });\n\n    this.#cancelHover();\n    this.#cancelTouch();\n    this.#lastTouchStartEvent = null;\n  }\n}\n","import { getPluginApi } from \"@real-router/core/api\";\n\nimport { defaultOptions } from \"./constants\";\nimport { PreloadPlugin } from \"./plugin\";\n\nimport type { PreloadPluginOptions } from \"./types\";\nimport type { PluginFactory, Router } from \"@real-router/core\";\n\nexport function preloadPluginFactory(\n  opts?: Partial<PreloadPluginOptions>,\n): PluginFactory {\n  const options: Required<PreloadPluginOptions> = {\n    ...defaultOptions,\n    ...opts,\n  };\n\n  return function preloadPlugin(routerBase) {\n    if (typeof document === \"undefined\") {\n      return {};\n    }\n\n    const plugin = new PreloadPlugin(\n      routerBase as Router,\n      getPluginApi(routerBase),\n      options,\n    );\n\n    return plugin.getPlugin();\n  };\n}\n"],"mappings":"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"}

package/dist/esm/index.d.mts

@@ -0,0 +1,25 @@
+import { Params, PluginFactory } from "@real-router/core";
+
+//#region src/types.d.ts
+interface PreloadPluginOptions {
+  /** Hover debounce delay in ms. @default 65 */
+  delay?: number;
+  /** Check saveData/2g and disable preloading on slow connections. @default true */
+  networkAware?: boolean;
+}
+//#endregion
+//#region src/factory.d.ts
+declare function preloadPluginFactory(opts?: Partial<PreloadPluginOptions>): PluginFactory;
+//#endregion
+//#region src/index.d.ts
+declare module "@real-router/core" {
+  interface Route {
+    preload?: (params: Params) => Promise<unknown>;
+  }
+  interface Router {
+    getPreloadSettings(): PreloadPluginOptions;
+  }
+}
+//#endregion
+export { type PreloadPluginOptions, preloadPluginFactory };
+//# sourceMappingURL=index.d.mts.map

package/dist/esm/index.mjs

@@ -0,0 +1,2 @@
+import{getPluginApi as e}from"@real-router/core/api";const t={delay:65,networkAware:!0};function n(){let e=navigator.connection;return e?!!(e.saveData||e.effectiveType?.includes(`2g`)):!1}var r=class{#e;#t;#n;#r;#i=null;#a=null;#o=null;#s=0;#c=null;constructor(e,t,n){this.#e=e,this.#t=t,this.#n=n,this.#r=t.extendRouter({getPreloadSettings:()=>({...n})})}getPlugin(){return{onStart:()=>{document.addEventListener(`mouseover`,this.#l,{capture:!0,passive:!0}),document.addEventListener(`touchstart`,this.#u,{capture:!0,passive:!0}),document.addEventListener(`touchmove`,this.#d,{capture:!0,passive:!0})},onStop:()=>{this.#_()},teardown:()=>{this.#_(),this.#r()}}}#l=e=>{if(this.#m(e))return;let t=e.target;if(!t||!(`closest`in t)){this.#h();return}let n=t.closest(`a[href]`);if(n===this.#i)return;this.#h(),this.#i=n;let r=this.#f(n);r&&(this.#a=setTimeout(()=>{this.#a=null,r.fn(r.params).catch(()=>{})},this.#n.delay))};#u=e=>{this.#c={target:e.target,timeStamp:e.timeStamp},this.#g();let t=e.target,n=t&&`closest`in t?t.closest(`a[href]`):null,r=this.#f(n);r&&(this.#s=e.touches[0].clientY,this.#o=setTimeout(()=>{this.#o=null,r.fn(r.params).catch(()=>{})},100))};#d=e=>{this.#o!==null&&Math.abs(e.touches[0].clientY-this.#s)>10&&this.#g()};#f(e){if(e&&!(`noPreload`in e.dataset)&&!(this.#n.networkAware&&n()))return this.#p(e)}#p(e){let t=this.#e.matchUrl?.(e.href);if(!t)return;let n=this.#t.getRouteConfig(t.name);if(typeof n?.preload==`function`)return{fn:n.preload,params:t.params}}#m(e){return this.#c!==null&&e.target===this.#c.target&&e.timeStamp-this.#c.timeStamp<2500}#h(){this.#a!==null&&(clearTimeout(this.#a),this.#a=null),this.#i=null}#g(){this.#o!==null&&(clearTimeout(this.#o),this.#o=null)}#_(){document.removeEventListener(`mouseover`,this.#l,{capture:!0}),document.removeEventListener(`touchstart`,this.#u,{capture:!0}),document.removeEventListener(`touchmove`,this.#d,{capture:!0}),this.#h(),this.#g(),this.#c=null}};function i(n){let i={...t,...n};return function(t){return typeof document>`u`?{}:new r(t,e(t),i).getPlugin()}}export{i as preloadPluginFactory};
+//# sourceMappingURL=index.mjs.map

package/dist/esm/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":["#router","#api","#options","#removeExtensions","#handleMouseOver","#handleTouchStart","#handleTouchMove","#cleanup","#isGhostMouseEvent","#cancelHover","#currentAnchor","#resolveAnchorPreload","#hoverTimer","#lastTouchStartEvent","#cancelTouch","#touchStartY","#touchTimer","#resolvePreload"],"sources":["../../src/constants.ts","../../src/network.ts","../../src/plugin.ts","../../src/factory.ts"],"sourcesContent":["import type { PreloadPluginOptions } from \"./types\";\n\nexport const defaultOptions: Required<PreloadPluginOptions> = {\n  delay: 65,\n  networkAware: true,\n};\n\nexport const GHOST_EVENT_THRESHOLD = 2500;\n\nexport const TOUCH_SCROLL_THRESHOLD = 10;\n\nexport const TOUCH_PRELOAD_DELAY = 100;\n","type NetworkConnection =\n  | { saveData?: boolean; effectiveType?: string }\n  | undefined;\n\ninterface NavigatorWithConnection extends Navigator {\n  connection?: NetworkConnection;\n}\n\nexport function isSlowConnection(): boolean {\n  const connection = (navigator as NavigatorWithConnection).connection;\n\n  if (!connection) {\n    return false;\n  }\n  if (connection.saveData) {\n    return true;\n  }\n  if (connection.effectiveType?.includes(\"2g\")) {\n    return true;\n  }\n\n  return false;\n}\n","import {\n  GHOST_EVENT_THRESHOLD,\n  TOUCH_PRELOAD_DELAY,\n  TOUCH_SCROLL_THRESHOLD,\n} from \"./constants\";\nimport { isSlowConnection } from \"./network\";\n\nimport type { PreloadPluginOptions } from \"./types\";\nimport type { Params, Plugin, Router, State } from \"@real-router/core\";\nimport type { PluginApi } from \"@real-router/core/api\";\n\ndeclare module \"@real-router/core\" {\n  interface Router {\n    matchUrl?: (url: string) => State | undefined;\n  }\n}\n\nexport class PreloadPlugin {\n  readonly #router: Router;\n  readonly #api: PluginApi;\n  readonly #options: Required<PreloadPluginOptions>;\n  readonly #removeExtensions: () => void;\n\n  #currentAnchor: HTMLAnchorElement | null = null;\n  #hoverTimer: ReturnType<typeof setTimeout> | null = null;\n  #touchTimer: ReturnType<typeof setTimeout> | null = null;\n  #touchStartY = 0;\n  #lastTouchStartEvent: {\n    target: EventTarget | null;\n    timeStamp: number;\n  } | null = null;\n\n  constructor(\n    router: Router,\n    api: PluginApi,\n    options: Required<PreloadPluginOptions>,\n  ) {\n    this.#router = router;\n    this.#api = api;\n    this.#options = options;\n\n    this.#removeExtensions = api.extendRouter({\n      getPreloadSettings: () => ({ ...options }),\n    });\n  }\n\n  getPlugin(): Plugin {\n    return {\n      onStart: () => {\n        document.addEventListener(\"mouseover\", this.#handleMouseOver, {\n          capture: true,\n          passive: true,\n        });\n        document.addEventListener(\"touchstart\", this.#handleTouchStart, {\n          capture: true,\n          passive: true,\n        });\n        document.addEventListener(\"touchmove\", this.#handleTouchMove, {\n          capture: true,\n          passive: true,\n        });\n      },\n\n      onStop: () => {\n        this.#cleanup();\n      },\n\n      teardown: () => {\n        this.#cleanup();\n        this.#removeExtensions();\n      },\n    };\n  }\n\n  readonly #handleMouseOver = (event: MouseEvent): void => {\n    if (this.#isGhostMouseEvent(event)) {\n      return;\n    }\n\n    const target = event.target as Element | null;\n\n    if (!target || !(\"closest\" in target)) {\n      this.#cancelHover();\n\n      return;\n    }\n\n    const anchor = target.closest<HTMLAnchorElement>(\"a[href]\");\n\n    if (anchor === this.#currentAnchor) {\n      return;\n    }\n\n    this.#cancelHover();\n    this.#currentAnchor = anchor;\n\n    const preload = this.#resolveAnchorPreload(anchor);\n\n    if (!preload) {\n      return;\n    }\n\n    this.#hoverTimer = setTimeout(() => {\n      this.#hoverTimer = null;\n      preload.fn(preload.params).catch(() => {});\n    }, this.#options.delay);\n  };\n\n  readonly #handleTouchStart = (event: TouchEvent): void => {\n    this.#lastTouchStartEvent = {\n      target: event.target,\n      timeStamp: event.timeStamp,\n    };\n\n    this.#cancelTouch();\n\n    const target = event.target as Element | null;\n    const anchor =\n      target && \"closest\" in target\n        ? target.closest<HTMLAnchorElement>(\"a[href]\")\n        : null;\n    const preload = this.#resolveAnchorPreload(anchor);\n\n    if (!preload) {\n      return;\n    }\n\n    this.#touchStartY = event.touches[0].clientY;\n\n    this.#touchTimer = setTimeout(() => {\n      this.#touchTimer = null;\n      preload.fn(preload.params).catch(() => {});\n    }, TOUCH_PRELOAD_DELAY);\n  };\n\n  readonly #handleTouchMove = (event: TouchEvent): void => {\n    if (this.#touchTimer === null) {\n      return;\n    }\n\n    const deltaY = Math.abs(event.touches[0].clientY - this.#touchStartY);\n\n    if (deltaY > TOUCH_SCROLL_THRESHOLD) {\n      this.#cancelTouch();\n    }\n  };\n\n  #resolveAnchorPreload(\n    anchor: HTMLAnchorElement | null | undefined,\n  ): { fn: (params: Params) => Promise<unknown>; params: Params } | undefined {\n    if (!anchor) {\n      return undefined;\n    }\n\n    if (\"noPreload\" in anchor.dataset) {\n      return undefined;\n    }\n\n    if (this.#options.networkAware && isSlowConnection()) {\n      return undefined;\n    }\n\n    return this.#resolvePreload(anchor);\n  }\n\n  #resolvePreload(\n    anchor: HTMLAnchorElement,\n  ): { fn: (params: Params) => Promise<unknown>; params: Params } | undefined {\n    const state = this.#router.matchUrl?.(anchor.href);\n\n    if (!state) {\n      return undefined;\n    }\n\n    const config = this.#api.getRouteConfig(state.name);\n\n    if (typeof config?.preload !== \"function\") {\n      return undefined;\n    }\n\n    return {\n      fn: config.preload as (params: Params) => Promise<unknown>,\n      params: state.params,\n    };\n  }\n\n  #isGhostMouseEvent(event: MouseEvent): boolean {\n    return (\n      this.#lastTouchStartEvent !== null &&\n      event.target === this.#lastTouchStartEvent.target &&\n      event.timeStamp - this.#lastTouchStartEvent.timeStamp <\n        GHOST_EVENT_THRESHOLD\n    );\n  }\n\n  #cancelHover(): void {\n    if (this.#hoverTimer !== null) {\n      clearTimeout(this.#hoverTimer);\n      this.#hoverTimer = null;\n    }\n\n    this.#currentAnchor = null;\n  }\n\n  #cancelTouch(): void {\n    if (this.#touchTimer !== null) {\n      clearTimeout(this.#touchTimer);\n      this.#touchTimer = null;\n    }\n  }\n\n  #cleanup(): void {\n    document.removeEventListener(\"mouseover\", this.#handleMouseOver, {\n      capture: true,\n    });\n    document.removeEventListener(\"touchstart\", this.#handleTouchStart, {\n      capture: true,\n    });\n    document.removeEventListener(\"touchmove\", this.#handleTouchMove, {\n      capture: true,\n    });\n\n    this.#cancelHover();\n    this.#cancelTouch();\n    this.#lastTouchStartEvent = null;\n  }\n}\n","import { getPluginApi } from \"@real-router/core/api\";\n\nimport { defaultOptions } from \"./constants\";\nimport { PreloadPlugin } from \"./plugin\";\n\nimport type { PreloadPluginOptions } from \"./types\";\nimport type { PluginFactory, Router } from \"@real-router/core\";\n\nexport function preloadPluginFactory(\n  opts?: Partial<PreloadPluginOptions>,\n): PluginFactory {\n  const options: Required<PreloadPluginOptions> = {\n    ...defaultOptions,\n    ...opts,\n  };\n\n  return function preloadPlugin(routerBase) {\n    if (typeof document === \"undefined\") {\n      return {};\n    }\n\n    const plugin = new PreloadPlugin(\n      routerBase as Router,\n      getPluginApi(routerBase),\n      options,\n    );\n\n    return plugin.getPlugin();\n  };\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@real-router/preload-plugin",
+  "version": "0.0.1",
+  "type": "commonjs",
+  "description": "Preload plugin — trigger data preloading on navigation intent (hover, touch)",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.mjs",
+  "types": "./dist/esm/index.d.mts",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": {
+        "import": "./dist/esm/index.d.mts",
+        "require": "./dist/cjs/index.d.ts"
+      },
+      "import": "./dist/esm/index.mjs",
+      "require": "./dist/cjs/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/greydragon888/real-router.git"
+  },
+  "keywords": [
+    "real-router",
+    "preload",
+    "prefetch",
+    "hover",
+    "touch",
+    "navigation-intent"
+  ],
+  "author": {
+    "name": "Oleg Ivanov",
+    "email": "greydragon888@gmail.com",
+    "url": "https://github.com/greydragon888"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/greydragon888/real-router",
+  "bugs": {
+    "url": "https://github.com/greydragon888/real-router/issues"
+  },
+  "scripts": {
+    "test": "vitest",
+    "build": "tsdown --config-loader unrun",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint --cache --ext .ts src/ tests/ --fix --max-warnings 0",
+    "lint:package": "publint",
+    "lint:types": "attw --pack .",
+    "build:dist-only": "tsdown --config-loader unrun"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@real-router/core": "workspace:^"
+  },
+  "devDependencies": {
+    "jsdom": "28.1.0"
+  }
+}

package/src/constants.ts

@@ -0,0 +1,12 @@
+import type { PreloadPluginOptions } from "./types";
+
+export const defaultOptions: Required<PreloadPluginOptions> = {
+  delay: 65,
+  networkAware: true,
+};
+
+export const GHOST_EVENT_THRESHOLD = 2500;
+
+export const TOUCH_SCROLL_THRESHOLD = 10;
+
+export const TOUCH_PRELOAD_DELAY = 100;

package/src/factory.ts

@@ -0,0 +1,30 @@
+import { getPluginApi } from "@real-router/core/api";
+
+import { defaultOptions } from "./constants";
+import { PreloadPlugin } from "./plugin";
+
+import type { PreloadPluginOptions } from "./types";
+import type { PluginFactory, Router } from "@real-router/core";
+
+export function preloadPluginFactory(
+  opts?: Partial<PreloadPluginOptions>,
+): PluginFactory {
+  const options: Required<PreloadPluginOptions> = {
+    ...defaultOptions,
+    ...opts,
+  };
+
+  return function preloadPlugin(routerBase) {
+    if (typeof document === "undefined") {
+      return {};
+    }
+
+    const plugin = new PreloadPlugin(
+      routerBase as Router,
+      getPluginApi(routerBase),
+      options,
+    );
+
+    return plugin.getPlugin();
+  };
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+/* eslint-disable @typescript-eslint/method-signature-style -- method syntax required for declaration merging overload (property syntax causes TS2717) */
+import type { PreloadPluginOptions } from "./types";
+import type { Params } from "@real-router/core";
+
+export { preloadPluginFactory } from "./factory";
+
+export type { PreloadPluginOptions } from "./types";
+
+declare module "@real-router/core" {
+  interface Route {
+    preload?: (params: Params) => Promise<unknown>;
+  }
+
+  interface Router {
+    getPreloadSettings(): PreloadPluginOptions;
+  }
+}

package/src/network.ts

@@ -0,0 +1,23 @@
+type NetworkConnection =
+  | { saveData?: boolean; effectiveType?: string }
+  | undefined;
+
+interface NavigatorWithConnection extends Navigator {
+  connection?: NetworkConnection;
+}
+
+export function isSlowConnection(): boolean {
+  const connection = (navigator as NavigatorWithConnection).connection;
+
+  if (!connection) {
+    return false;
+  }
+  if (connection.saveData) {
+    return true;
+  }
+  if (connection.effectiveType?.includes("2g")) {
+    return true;
+  }
+
+  return false;
+}

package/src/plugin.ts

@@ -0,0 +1,227 @@
+import {
+  GHOST_EVENT_THRESHOLD,
+  TOUCH_PRELOAD_DELAY,
+  TOUCH_SCROLL_THRESHOLD,
+} from "./constants";
+import { isSlowConnection } from "./network";
+
+import type { PreloadPluginOptions } from "./types";
+import type { Params, Plugin, Router, State } from "@real-router/core";
+import type { PluginApi } from "@real-router/core/api";
+
+declare module "@real-router/core" {
+  interface Router {
+    matchUrl?: (url: string) => State | undefined;
+  }
+}
+
+export class PreloadPlugin {
+  readonly #router: Router;
+  readonly #api: PluginApi;
+  readonly #options: Required<PreloadPluginOptions>;
+  readonly #removeExtensions: () => void;
+
+  #currentAnchor: HTMLAnchorElement | null = null;
+  #hoverTimer: ReturnType<typeof setTimeout> | null = null;
+  #touchTimer: ReturnType<typeof setTimeout> | null = null;
+  #touchStartY = 0;
+  #lastTouchStartEvent: {
+    target: EventTarget | null;
+    timeStamp: number;
+  } | null = null;
+
+  constructor(
+    router: Router,
+    api: PluginApi,
+    options: Required<PreloadPluginOptions>,
+  ) {
+    this.#router = router;
+    this.#api = api;
+    this.#options = options;
+
+    this.#removeExtensions = api.extendRouter({
+      getPreloadSettings: () => ({ ...options }),
+    });
+  }
+
+  getPlugin(): Plugin {
+    return {
+      onStart: () => {
+        document.addEventListener("mouseover", this.#handleMouseOver, {
+          capture: true,
+          passive: true,
+        });
+        document.addEventListener("touchstart", this.#handleTouchStart, {
+          capture: true,
+          passive: true,
+        });
+        document.addEventListener("touchmove", this.#handleTouchMove, {
+          capture: true,
+          passive: true,
+        });
+      },
+
+      onStop: () => {
+        this.#cleanup();
+      },
+
+      teardown: () => {
+        this.#cleanup();
+        this.#removeExtensions();
+      },
+    };
+  }
+
+  readonly #handleMouseOver = (event: MouseEvent): void => {
+    if (this.#isGhostMouseEvent(event)) {
+      return;
+    }
+
+    const target = event.target as Element | null;
+
+    if (!target || !("closest" in target)) {
+      this.#cancelHover();
+
+      return;
+    }
+
+    const anchor = target.closest<HTMLAnchorElement>("a[href]");
+
+    if (anchor === this.#currentAnchor) {
+      return;
+    }
+
+    this.#cancelHover();
+    this.#currentAnchor = anchor;
+
+    const preload = this.#resolveAnchorPreload(anchor);
+
+    if (!preload) {
+      return;
+    }
+
+    this.#hoverTimer = setTimeout(() => {
+      this.#hoverTimer = null;
+      preload.fn(preload.params).catch(() => {});
+    }, this.#options.delay);
+  };
+
+  readonly #handleTouchStart = (event: TouchEvent): void => {
+    this.#lastTouchStartEvent = {
+      target: event.target,
+      timeStamp: event.timeStamp,
+    };
+
+    this.#cancelTouch();
+
+    const target = event.target as Element | null;
+    const anchor =
+      target && "closest" in target
+        ? target.closest<HTMLAnchorElement>("a[href]")
+        : null;
+    const preload = this.#resolveAnchorPreload(anchor);
+
+    if (!preload) {
+      return;
+    }
+
+    this.#touchStartY = event.touches[0].clientY;
+
+    this.#touchTimer = setTimeout(() => {
+      this.#touchTimer = null;
+      preload.fn(preload.params).catch(() => {});
+    }, TOUCH_PRELOAD_DELAY);
+  };
+
+  readonly #handleTouchMove = (event: TouchEvent): void => {
+    if (this.#touchTimer === null) {
+      return;
+    }
+
+    const deltaY = Math.abs(event.touches[0].clientY - this.#touchStartY);
+
+    if (deltaY > TOUCH_SCROLL_THRESHOLD) {
+      this.#cancelTouch();
+    }
+  };
+
+  #resolveAnchorPreload(
+    anchor: HTMLAnchorElement | null | undefined,
+  ): { fn: (params: Params) => Promise<unknown>; params: Params } | undefined {
+    if (!anchor) {
+      return undefined;
+    }
+
+    if ("noPreload" in anchor.dataset) {
+      return undefined;
+    }
+
+    if (this.#options.networkAware && isSlowConnection()) {
+      return undefined;
+    }
+
+    return this.#resolvePreload(anchor);
+  }
+
+  #resolvePreload(
+    anchor: HTMLAnchorElement,
+  ): { fn: (params: Params) => Promise<unknown>; params: Params } | undefined {
+    const state = this.#router.matchUrl?.(anchor.href);
+
+    if (!state) {
+      return undefined;
+    }
+
+    const config = this.#api.getRouteConfig(state.name);
+
+    if (typeof config?.preload !== "function") {
+      return undefined;
+    }
+
+    return {
+      fn: config.preload as (params: Params) => Promise<unknown>,
+      params: state.params,
+    };
+  }
+
+  #isGhostMouseEvent(event: MouseEvent): boolean {
+    return (
+      this.#lastTouchStartEvent !== null &&
+      event.target === this.#lastTouchStartEvent.target &&
+      event.timeStamp - this.#lastTouchStartEvent.timeStamp <
+        GHOST_EVENT_THRESHOLD
+    );
+  }
+
+  #cancelHover(): void {
+    if (this.#hoverTimer !== null) {
+      clearTimeout(this.#hoverTimer);
+      this.#hoverTimer = null;
+    }
+
+    this.#currentAnchor = null;
+  }
+
+  #cancelTouch(): void {
+    if (this.#touchTimer !== null) {
+      clearTimeout(this.#touchTimer);
+      this.#touchTimer = null;
+    }
+  }
+
+  #cleanup(): void {
+    document.removeEventListener("mouseover", this.#handleMouseOver, {
+      capture: true,
+    });
+    document.removeEventListener("touchstart", this.#handleTouchStart, {
+      capture: true,
+    });
+    document.removeEventListener("touchmove", this.#handleTouchMove, {
+      capture: true,
+    });
+
+    this.#cancelHover();
+    this.#cancelTouch();
+    this.#lastTouchStartEvent = null;
+  }
+}

package/src/types.ts

@@ -0,0 +1,6 @@
+export interface PreloadPluginOptions {
+  /** Hover debounce delay in ms. @default 65 */
+  delay?: number;
+  /** Check saveData/2g and disable preloading on slow connections. @default true */
+  networkAware?: boolean;
+}