js.foresight 3.2.1 → 3.3.0

package/README.md

@@ -11,12 +11,13 @@
 [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Demo](https://img.shields.io/badge/demo-live-blue)](https://foresightjs.com#playground)
-ForesightJS is a lightweight JavaScript library with full TypeScript support that predicts user intent based on mouse movements, scroll and keyboard navigation. By analyzing cursor/scroll trajectory and tab sequences, it anticipates which elements a user is likely to interact with, allowing developers to trigger actions before the actual hover or click occurs (for example prefetching).
+
+ForesightJS is a lightweight JavaScript library that predicts user intent to prefetch content before it's needed. **It works completely out of the box without configuration**, supporting both desktop and mobile devices with different prediction strategies.
 
 ### [Playground](https://foresightjs.com/)
 
 ![](https://github.com/user-attachments/assets/f5650c63-4489-4878-bd72-d8954c6a739b)
-_In the GIF above, the [ForesightJS DevTools](https://foresightjs.com/docs/getting_started/development_tools) are enabled. Normally, users won't see anything that ForesightJS does except the increased perceived speed from early prefetching._
+_In the GIF above, the [ForesightJS DevTools](https://foresightjs.com/docs/debugging/devtools) are enabled. Normally, users won't see anything that ForesightJS does except the increased perceived speed from early prefetching._
 
 ## Download
 
@@ -28,27 +29,9 @@ npm install js.foresight
 yarn add js.foresight
 ```
 
-## Which problems does ForesightJS solve?
-
-### Problem 1: On-Hover Prefetching Still Has Latency
-
-Traditional hover-based prefetching only triggers after the user's cursor reaches an element. This approach wastes the critical 100-200ms window between when a user begins moving toward a target and when the hover event actually fires.
-
-### Problem 2: Viewport-Based Prefetching is Wasteful
-
-Many modern frameworks (like Next.js) automatically prefetch resources for all links that enter the viewport. While well-intentioned, this creates significant overhead since users typically interact with only a small fraction of visible elements. Simply scrolling up and down the Next.js homepage can trigger **_1.59MB_** of unnecessary prefetch requests.
-
-### Problem 3: Hover-Based Prefetching Excludes Keyboard Users
-
-Many routers rely on hover-based prefetching, but this approach completely excludes keyboard users since keyboard navigation never triggers hover events. This means keyboard users miss out on the performance benefits that mouse users get from hover-based prefetching.
-
-### The ForesightJS Solution
-
-ForesightJS bridges the gap between wasteful viewport prefetching and basic hover prefetching. The `ForesightManager` predicts user interactions by analyzing mouse trajectory patterns, scroll direction and keyboard navigation sequences. This allows you to prefetch resources at the optimal time to improve performance, but targeted enough to avoid waste.
-
 ## Basic Usage Example
 
-This basic example is in vanilla JS, ofcourse most people will use ForesightJS with a framework. You can read about framework integrations in the [docs](https://foresightjs.com/docs/integrations).
+This basic example is in vanilla JS, ofcourse most people will use ForesightJS with a framework. You can read about framework integrations in the [docs](https://foresightjs.com/docs/integrations/react/useForesight).
 
 ```javascript
 import { ForesightManager } from "foresightjs"
@@ -73,38 +56,29 @@ const { isTouchDevice } = ForesightManager.instance.register({
 
 ## Integrations
 
-Since ForesightJS is framework agnostic, it can be integrated with any JavaScript framework. While I haven't yet built [integrations](https://foresightjs.com/docs/integrations) for every framework, ready-to-use implementations for [Next.js](https://foresightjs.com/docs/integrations/react/nextjs) and [React Router](https://foresightjs.com/docs/integrations/react/react-router) are already available. Sharing integrations for other frameworks/packages is highly appreciated!
+Since ForesightJS is framework agnostic, it can be integrated with any JavaScript framework. While I haven't yet built integrations for every framework, ready-to-use implementations for [Next.js](https://foresightjs.com/docs/integrations/react/nextjs) and [React Router](https://foresightjs.com/docs/integrations/react/react-router) are already available. Sharing integrations for other frameworks/packages is highly appreciated!
 
 ## Configuration
 
-ForesightJS can be used bare-bones but also can be configured. For all configuration possibilities you can reference the [docs](https://foresightjs.com/docs/getting_started/config).
+ForesightJS works out of the box with no setup required, but it can be configured both [globally](https://foresightjs.com/docs/configuration/global-settings) and per [element](https://foresightjs.com/docs/configuration/element-settings) if needed.
 
 ## Development Tools
 
-ForesightJS has dedicated [Development Tools](https://github.com/spaansba/ForesightJS-DevTools) created with [Foresight Events](https://foresightjs.com/docs/getting_started/events) that help you understand and tune how foresight is working in your application. This standalone development package provides real-time visualization of mouse trajectory predictions, element bounds, and callback execution. It's particularly helpful when setting up ForesightJS for the first time or when fine-tuning for specific UI components.
+ForesightJS has dedicated [Development Tools](https://github.com/spaansba/ForesightJS/tree/main/packages/js.foresight-devtools) created with [Foresight Events](https://foresightjs.com/docs/events) that help you understand and tune how foresight is working in your application. This standalone development package provides real-time visualization of mouse trajectory predictions, element bounds, and callback execution.
 
 ```bash
-npm install js.foresight-devtools
+pnpm add js.foresight-devtools
 ```
 
-See the [development tools documentation](https://foresightjs.com/docs/getting_started/debug) for more details.
-
-## What About Touch Devices and Slow Connections?
+See the [development tools documentation](https://foresightjs.com/docs/debugging/devtools) for more details.
 
-Since ForesightJS relies on the keyboard/mouse it will not register elements for touch devices. For limited connections (2G or data-saver mode), we respect the user's preference to minimize data usage and skip registration aswell.
+## Prediction Strategies
 
-The `ForesightManager.instance.register()` method returns these properties:
+ForesightJS uses different prediction strategies depending on the device type:
 
-- `isTouchDevice` - true if user is on a touch device
-- `isLimitedConnection` - true when user is on a 2G connection or has data-saver enabled
-- `isRegistered` - true if element was actually registered
+**Desktop/Keyboard Users**: Mouse trajectory prediction, keyboard navigation tracking, and scroll-based prefetching. [Read more](https://foresightjs.com/docs/getting-started/what-is-foresightjs#keyboardmouse-users)
 
-With these properties you could create your own fallback prefetching methods if required. For example if the user is on a touch device you could prefetch based on viewport.
-An example of this can be found in the [Next.js](https://foresightjs.com/docs/integrations/react/nextjs) or [React Router](https://foresightjs.com/docs/integrations/react/react-router) ForesightLink components.
-
-## How Does ForesightJS Work?
-
-For a detailed technical explanation of its prediction algorithms and internal architecture, see the **[Behind the Scenes documentation](https://foresightjs.com/docs/Behind_the_Scenes)**.
+**Mobile Devices**: Viewport enter detection and touch start events (configurable via [`touchDeviceStrategy`]). [Read more](https://foresightjs.com/docs/getting-started/what-is-foresightjs#touch-devices-v330)
 
 ## Providing Context to AI Tools
 
@@ -114,6 +88,8 @@ ForesightJS is a newer library, so most AI assistants and LLMs may not have much
 - Use [llms-full.txt](https://foresightjs.com/llms-full.txt) for a full markdown version of the docs, ideal for AI tools that support context injection or uploads.
 - All documentation pages are also available in markdown. You can view them by adding .md to the end of any URL, for example: https://foresightjs.com/docs/getting_started.md.
 
+[Read more](https://foresightjs.com/docs/ai-context)
+
 # Contributing
 
 Please see the [contributing guidelines](/CONTRIBUTING.md)

package/dist/index.d.ts

@@ -64,19 +64,10 @@ type ElementBounds = {
     /** The hit slop values applied to this element. */
     hitSlop: Exclude<HitSlop, number>;
 };
-/**
- * Represents trajectory hit related data for a foresight element.
- */
-type TrajectoryHitData = {
-    /** True if the predicted mouse trajectory has intersected the element's expanded bounds. */
-    isTrajectoryHit: boolean;
-    /** The timestamp when the last trajectory hit occurred. */
-    trajectoryHitTime: number;
-    /** Timeout ID for expiring the trajectory hit state. */
-    trajectoryHitExpirationTimeoutId?: ReturnType<typeof setTimeout>;
-};
 type ForesightRegisterResult = {
-    /** Whether the current device is a touch device. This is important as ForesightJS only works based on cursor movement. If the user is using a touch device you should handle prefetching differently  */
+    /** Whether the current device is a touch device. This is important as ForesightJS only works based on cursor movement. If the user is using a touch device you should handle prefetching differently
+     * @deprecated As of version 3.3, ForesightJS handles touch devices internally with dedicated touch strategies
+     */
     isTouchDevice: boolean;
     /** Whether the user has connection limitations (slow network (2g) or data saver enabled) that should prevent prefetching */
     isLimitedConnection: boolean;
@@ -95,10 +86,6 @@ type ForesightElementData = Required<Pick<ForesightRegisterOptions, "callback" |
     id: string;
     /** The boundary information for the element. */
     elementBounds: ElementBounds;
-    /**
-     * Represents trajectory hit related data for a foresight element. Only used for the manager
-     */
-    trajectoryHitData: TrajectoryHitData;
     /**
      * Is the element intersecting with the viewport, usefull to track which element we should observe or not
      * Can be @undefined in the split second the element is registering
@@ -175,6 +162,8 @@ type CallbackHits = {
     mouse: MouseCallbackCounts;
     tab: TabCallbackCounts;
     scroll: ScrollCallbackCounts;
+    touch: number;
+    viewport: number;
 };
 type CallbackHitType = {
     kind: "mouse";
@@ -185,6 +174,12 @@ type CallbackHitType = {
 } | {
     kind: "scroll";
     subType: keyof ScrollCallbackCounts;
+} | {
+    kind: "touch";
+    subType?: string;
+} | {
+    kind: "viewport";
+    subType?: string;
 };
 /**
  * Snapshot of the current ForesightManager state
@@ -194,7 +189,10 @@ type ForesightManagerData = {
     globalSettings: Readonly<ForesightManagerSettings>;
     globalCallbackHits: Readonly<CallbackHits>;
     eventListeners: ReadonlyMap<keyof ForesightEventMap, ForesightEventListener[]>;
+    currentDeviceStrategy: CurrentDeviceStrategy;
+    activeElementCount: number;
 };
+type TouchDeviceStrategy = "none" | "viewport" | "onTouchStart";
 type BaseForesightManagerSettings = {
     /**
      * Number of mouse positions to keep in history for trajectory calculation.
@@ -261,7 +259,16 @@ type BaseForesightManagerSettings = {
      * @default 2
      */
     tabOffset: number;
+    /**
+     * The prefetch strategy used for touch devices.
+     * - `none`: No prefetching is done on touch devices.
+     * - `viewport`: Prefetching is done based on the viewport, meaning elements in the viewport are preloaded.
+     * - `onTouchStart`: Prefetching is done when the user touches the element
+     * @default onTouchStart
+     */
+    touchDeviceStrategy: TouchDeviceStrategy;
 };
+type CurrentDeviceStrategy = "mouse" | "touch" | "pen";
 /**
  * Configuration options for the ForesightManager
  * @link https://foresightjs.com/docs/getting_started/config#available-global-settings
@@ -322,8 +329,14 @@ interface ForesightEventMap {
     mouseTrajectoryUpdate: MouseTrajectoryUpdateEvent;
     scrollTrajectoryUpdate: ScrollTrajectoryUpdateEvent;
     managerSettingsChanged: ManagerSettingsChangedEvent;
+    deviceStrategyChanged: DeviceStrategyChangedEvent;
+}
+type ForesightEvent = "elementRegistered" | "elementReactivated" | "elementUnregistered" | "elementDataUpdated" | "callbackInvoked" | "callbackCompleted" | "mouseTrajectoryUpdate" | "scrollTrajectoryUpdate" | "managerSettingsChanged" | "deviceStrategyChanged";
+interface DeviceStrategyChangedEvent extends ForesightBaseEvent {
+    type: "deviceStrategyChanged";
+    newStrategy: CurrentDeviceStrategy;
+    oldStrategy: CurrentDeviceStrategy;
 }
-type ForesightEvent = "elementRegistered" | "elementReactivated" | "elementUnregistered" | "elementDataUpdated" | "callbackInvoked" | "callbackCompleted" | "mouseTrajectoryUpdate" | "scrollTrajectoryUpdate" | "managerSettingsChanged";
 interface ElementRegisteredEvent extends ForesightBaseEvent {
     type: "elementRegistered";
     elementData: ForesightElementData;
@@ -336,7 +349,7 @@ interface ElementUnregisteredEvent extends ForesightBaseEvent {
     type: "elementUnregistered";
     elementData: ForesightElementData;
     unregisterReason: ElementUnregisteredReason;
-    wasLastElement: boolean;
+    wasLastRegisteredElement: boolean;
 }
 /**
  * The reason an element was unregistered from ForesightManager's tracking.
@@ -346,7 +359,7 @@ interface ElementUnregisteredEvent extends ForesightBaseEvent {
  * - `devtools`: When clicking the trash icon in the devtools element tab
  * - any other string
  */
-type ElementUnregisteredReason = "callbackHit" | "disconnected" | "apiCall" | "devtools" | (string & {});
+type ElementUnregisteredReason = "disconnected" | "apiCall" | "devtools" | (string & {});
 interface ElementDataUpdatedEvent extends Omit<ForesightBaseEvent, "timestamp"> {
     type: "elementDataUpdated";
     elementData: ForesightElementData;
@@ -363,6 +376,7 @@ interface CallbackCompletedEventBase extends ForesightBaseEvent {
     elementData: ForesightElementData;
     hitType: CallbackHitType;
     elapsed: number;
+    wasLastActiveElement: boolean;
 }
 type CallbackCompletedEvent = CallbackCompletedEventBase & {
     status: callbackStatus;
@@ -417,17 +431,19 @@ interface ForesightBaseEvent {
 declare class ForesightManager {
     private static manager;
     private elements;
-    private trajectoryPositions;
-    private isSetup;
     private idCounter;
+    private activeElementCount;
+    private desktopHandler;
+    private touchDeviceHandler;
+    private handler;
+    private isSetup;
     private _globalCallbackHits;
     private _globalSettings;
+    private pendingPointerEvent;
+    private rafId;
     private domObserver;
-    private positionObserver;
     private eventListeners;
-    private mousePredictor;
-    private tabPredictor;
-    private scrollPredictor;
+    private currentDeviceStrategy;
     private constructor();
     private generateId;
     static initialize(props?: Partial<UpdateForsightManagerSettings>): ForesightManager;
@@ -442,9 +458,15 @@ declare class ForesightManager {
     get registeredElements(): ReadonlyMap<ForesightElement, ForesightElementData>;
     register({ element, callback, hitSlop, name, meta, reactivateAfter, }: ForesightRegisterOptions): ForesightRegisterResult;
     unregister(element: ForesightElement, unregisterReason?: ElementUnregisteredReason): void;
-    private updateNumericSettings;
-    private updateBooleanSetting;
-    alterGlobalSettings(props?: Partial<UpdateForsightManagerSettings>): void;
+    private updateHitCounters;
+    reactivate(element: ForesightElement): void;
+    private clearReactivateTimeout;
+    private makeElementUnactive;
+    private callCallback;
+    private setDeviceStrategy;
+    private handlePointerMove;
+    private initializeGlobalListeners;
+    private removeGlobalListeners;
     /**
      * Detects when registered elements are removed from the DOM and automatically unregisters them to prevent stale references.
      *
@@ -452,20 +474,16 @@ declare class ForesightManager {
      *
      */
     private handleDomMutations;
-    private updateHitCounters;
-    reactivate(element: ForesightElement): void;
-    private makeElementUnactive;
-    private callCallback;
-    private handlePositionChange;
-    private handlePositionChangeDataUpdates;
-    private initializeGlobalListeners;
-    private removeGlobalListeners;
     private forceUpdateAllElementBounds;
     /**
      * ONLY use this function when you want to change the rect bounds via code, if the rects are changing because of updates in the DOM do not use this function.
      * We need an observer for that
      */
     private forceUpdateElementBounds;
+    private initializeManagerSettings;
+    private updateNumericSettings;
+    private updateBooleanSetting;
+    alterGlobalSettings(props?: Partial<UpdateForsightManagerSettings>): void;
 }
 
-export { type CallbackCompletedEvent, type CallbackHitType, type CallbackHits, type CallbackInvokedEvent, type ElementCallbackInfo, type ElementDataUpdatedEvent, type ElementReactivatedEvent, type ElementRegisteredEvent, type ElementUnregisteredEvent, type ForesightElement, type ForesightElementData, type ForesightEvent, ForesightManager, type ForesightManagerSettings, type Rect as ForesightRect, type ForesightRegisterOptions, type ForesightRegisterOptionsWithoutElement, type ForesightRegisterResult, type HitSlop, type ManagerSettingsChangedEvent, type MouseTrajectoryUpdateEvent, type ScrollTrajectoryUpdateEvent, type UpdateForsightManagerSettings, type UpdatedManagerSetting };
+export { type CallbackCompletedEvent, type CallbackHitType, type CallbackHits, type CallbackInvokedEvent, type DeviceStrategyChangedEvent, type ElementCallbackInfo, type ElementDataUpdatedEvent, type ElementReactivatedEvent, type ElementRegisteredEvent, type ElementUnregisteredEvent, type ForesightElement, type ForesightElementData, type ForesightEvent, ForesightManager, type ForesightManagerSettings, type Rect as ForesightRect, type ForesightRegisterOptions, type ForesightRegisterOptionsWithoutElement, type ForesightRegisterResult, type HitSlop, type ManagerSettingsChangedEvent, type MouseTrajectoryUpdateEvent, type ScrollTrajectoryUpdateEvent, type TouchDeviceStrategy, type UpdateForsightManagerSettings, type UpdatedManagerSetting };

package/dist/index.js

@@ -1 +1 @@
-import{PositionObserver as st}from"position-observer";var v=class{constructor(t){this.head=0;this.count=0;if(t<=0)throw new Error("CircularBuffer capacity must be greater than 0");this.capacity=t,this.buffer=new Array(t)}add(t){this.buffer[this.head]=t,this.head=(this.head+1)%this.capacity,this.count<this.capacity&&this.count++}getFirst(){if(this.count!==0)return this.count<this.capacity?this.buffer[0]:this.buffer[this.head]}getLast(){if(this.count!==0){if(this.count<this.capacity)return this.buffer[this.count-1];{let t=(this.head-1+this.capacity)%this.capacity;return this.buffer[t]}}}getFirstLast(){if(this.count===0)return[void 0,void 0];if(this.count===1){let i=this.count<this.capacity?this.buffer[0]:this.buffer[this.head];return[i,i]}let t=this.getFirst(),e=this.getLast();return[t,e]}resize(t){if(t<=0)throw new Error("CircularBuffer capacity must be greater than 0");if(t===this.capacity)return;let e=this.getAllItems();if(this.capacity=t,this.buffer=new Array(t),this.head=0,this.count=0,e.length>t){let i=e.slice(-t);for(let o of i)this.add(o)}else for(let i of e)this.add(i)}getAllItems(){if(this.count===0)return[];let t=new Array(this.count);if(this.count<this.capacity)for(let e=0;e<this.count;e++)t[e]=this.buffer[e];else{let e=this.head;for(let i=0;i<this.capacity;i++){let o=(e+i)%this.capacity;t[i]=this.buffer[o]}}return t}clear(){this.head=0,this.count=0}get length(){return this.count}get size(){return this.capacity}get isFull(){return this.count===this.capacity}get isEmpty(){return this.count===0}};function u(n,t,e,i){return n<t?console.warn(`ForesightJS: "${i}" value ${n} is below minimum bound ${t}, clamping to ${t}`):n>e&&console.warn(`ForesightJS: "${i}" value ${n} is above maximum bound ${e}, clamping to ${e}`),Math.min(Math.max(n,t),e)}function D(n){let t=window.innerWidth||document.documentElement.clientWidth,e=window.innerHeight||document.documentElement.clientHeight;return n.top<e&&n.bottom>0&&n.left<t&&n.right>0}function k(n){if(typeof n=="number"){let t=u(n,0,2e3,"hitslop");return{top:t,left:t,right:t,bottom:t}}return{top:u(n.top,0,2e3,"hitslop - top"),left:u(n.left,0,2e3,"hitslop - left"),right:u(n.right,0,2e3,"hitslop - right"),bottom:u(n.bottom,0,2e3,"hitslop - bottom")}}function S(n,t){return{left:n.left-t.left,right:n.right+t.right,top:n.top-t.top,bottom:n.bottom+t.bottom}}function x(n,t){return!n||!t?n===t:n.left===t.left&&n.right===t.right&&n.top===t.top&&n.bottom===t.bottom}function T(n,t){return n.x>=t.left&&n.x<=t.right&&n.y>=t.top&&n.y<=t.bottom}function j(){let n=z(),t=K();return{isTouchDevice:n,isLimitedConnection:t,shouldRegister:!n&&!t}}function z(){return window.matchMedia("(pointer: coarse)").matches&&navigator.maxTouchPoints>0}function K(){let n=navigator.connection;return n?/2g/.test(n.effectiveType)||n.saveData:!1}function O(n,t){return n!==void 0&&t!==n}function I(n,t,e){let i=0,o=1,r=t.x-n.x,c=t.y-n.y,s=(a,l)=>{if(a===0){if(l<0)return!1}else{let d=l/a;if(a<0){if(d>o)return!1;d>i&&(i=d)}else{if(d<i)return!1;d<o&&(o=d)}}return!0};return!s(-r,n.x-e.left)||!s(r,e.right-n.x)||!s(-c,n.y-e.top)||!s(c,e.bottom-n.y)?!1:i<=o}function w(n,t,e){let i=performance.now(),o={point:n,time:i},{x:r,y:c}=n;if(t.add(o),t.length<2)return{x:r,y:c};let[s,a]=t.getFirstLast();if(!s||!a)return{x:r,y:c};let l=(a.time-s.time)*.001;if(l===0)return{x:r,y:c};let d=a.point.x-s.point.x,p=a.point.y-s.point.y,g=d/l,b=p/l,R=e*.001,_=r+g*R,A=c+b*R;return{x:_,y:A}}var h=class{constructor(t){this.elements=t.dependencies.elements,this.callCallback=t.dependencies.callCallback,this.emit=t.dependencies.emit,this.abortController=new AbortController}abort(){this.abortController.abort()}handleError(t,e){console.error(`${this.constructor.name} error in ${e}:`,t)}};var C=class extends h{constructor(e){super(e);this.pendingMouseEvent=null;this.rafId=null;this.handleMouseMove=e=>{this.pendingMouseEvent=e,!this.rafId&&(this.rafId=requestAnimationFrame(()=>{this.pendingMouseEvent&&this.processMouseMovement(this.pendingMouseEvent),this.rafId=null}))};this.enableMousePrediction=e.settings.enableMousePrediction,this.trajectoryPredictionTime=e.settings.trajectoryPredictionTime,this.positionHistorySize=e.settings.positionHistorySize,this.trajectoryPositions=e.trajectoryPositions,this.initializeListeners()}initializeListeners(){let{signal:e}=this.abortController;document.addEventListener("mousemove",this.handleMouseMove,{signal:e})}updatePointerState(e){let i={x:e.clientX,y:e.clientY};this.trajectoryPositions.currentPoint=i,this.enableMousePrediction?this.trajectoryPositions.predictedPoint=w(i,this.trajectoryPositions.positions,this.trajectoryPredictionTime):this.trajectoryPositions.predictedPoint=i}cleanup(){this.abort(),this.rafId&&(cancelAnimationFrame(this.rafId),this.rafId=null),this.pendingMouseEvent=null}processMouseMovement(e){try{this.updatePointerState(e);for(let i of this.elements.values()){if(!i.isIntersectingWithViewport||!i.callbackInfo.isCallbackActive||i.callbackInfo.isRunningCallback)continue;let o=i.elementBounds.expandedRect;if(this.enableMousePrediction)I(this.trajectoryPositions.currentPoint,this.trajectoryPositions.predictedPoint,o)&&this.callCallback(i,{kind:"mouse",subType:"trajectory"});else if(T(this.trajectoryPositions.currentPoint,o)){this.callCallback(i,{kind:"mouse",subType:"hover"});return}}this.emit({type:"mouseTrajectoryUpdate",predictionEnabled:this.enableMousePrediction,trajectoryPositions:this.trajectoryPositions})}catch(i){this.handleError(i,"processMouseMovement")}}};function H(n,t){let i=t.top-n.top,o=t.left-n.left;return i<-1?"down":i>1?"up":o<-1?"right":o>1?"left":"none"}function N(n,t,e){let{x:i,y:o}=n,r={x:i,y:o};switch(t){case"down":r.y+=e;break;case"up":r.y-=e;break;case"left":r.x-=e;break;case"right":r.x+=e;break;case"none":break;default:}return r}var y=class extends h{constructor(e){super(e);this.predictedScrollPoint=null;this.scrollDirection=null;this.scrollMargin=e.settings.scrollMargin,this.trajectoryPositions=e.trajectoryPositions}initializeListeners(){}cleanup(){this.abort(),this.resetScrollProps()}resetScrollProps(){this.scrollDirection=null,this.predictedScrollPoint=null}handleScrollPrefetch(e,i){if(!(!e.isIntersectingWithViewport||e.callbackInfo.isRunningCallback||!e.callbackInfo.isCallbackActive))try{if(this.scrollDirection=this.scrollDirection??H(e.elementBounds.originalRect,i),this.scrollDirection==="none")return;this.predictedScrollPoint=this.predictedScrollPoint??N(this.trajectoryPositions.currentPoint,this.scrollDirection,this.scrollMargin),I(this.trajectoryPositions.currentPoint,this.predictedScrollPoint,e.elementBounds.expandedRect)&&this.callCallback(e,{kind:"scroll",subType:this.scrollDirection}),this.emit({type:"scrollTrajectoryUpdate",currentPoint:this.trajectoryPositions.currentPoint,predictedPoint:this.predictedScrollPoint,scrollDirection:this.scrollDirection})}catch(o){this.handleError(o,"handleScrollPrefetch")}}handleError(e,i){super.handleError(e,i),this.emit({type:"scrollTrajectoryUpdate",currentPoint:this.trajectoryPositions.currentPoint,predictedPoint:this.trajectoryPositions.currentPoint,scrollDirection:"none"})}};import{tabbable as V}from"tabbable";function U(n,t,e,i){if(t!==null&&t>-1){let o=n?t-1:t+1;if(o>=0&&o<e.length&&e[o]===i)return o}return e.findIndex(o=>o===i)}var E=class extends h{constructor(e){super(e);this.lastKeyDown=null;this.tabbableElementsCache=[];this.lastFocusedIndex=null;this.handleKeyDown=e=>{e.key==="Tab"&&(this.lastKeyDown=e)};this.handleFocusIn=e=>{try{if(!this.lastKeyDown)return;let i=e.target;if(!(i instanceof HTMLElement))return;(!this.tabbableElementsCache.length||this.lastFocusedIndex===-1)&&(this.tabbableElementsCache=V(document.documentElement));let o=this.lastKeyDown.shiftKey,r=U(o,this.lastFocusedIndex,this.tabbableElementsCache,i);this.lastFocusedIndex=r,this.lastKeyDown=null;let c=[];for(let s=0;s<=this.tabOffset;s++){let a=o?r-s:r+s,l=this.tabbableElementsCache[a];l&&l instanceof Element&&this.elements.has(l)&&c.push(l)}for(let s of c){let a=this.elements.get(s);a&&!a.callbackInfo.isRunningCallback&&a.callbackInfo.isCallbackActive&&this.callCallback(a,{kind:"tab",subType:o?"reverse":"forwards"})}}catch(i){this.handleError(i,"handleFocusIn")}};this.tabOffset=e.settings.tabOffset,this.initializeListeners()}initializeListeners(){let{signal:e}=this.abortController;document.addEventListener("keydown",this.handleKeyDown,{signal:e}),document.addEventListener("focusin",this.handleFocusIn,{signal:e})}invalidateCache(){this.tabbableElementsCache=[],this.lastFocusedIndex=null}cleanup(){this.abort(),this.tabbableElementsCache=[],this.lastFocusedIndex=null,this.lastKeyDown=null}};var L=class n{constructor(){this.elements=new Map;this.trajectoryPositions={positions:new v(8),currentPoint:{x:0,y:0},predictedPoint:{x:0,y:0}};this.isSetup=!1;this.idCounter=0;this._globalCallbackHits={mouse:{hover:0,trajectory:0},tab:{forwards:0,reverse:0},scroll:{down:0,left:0,right:0,up:0},total:0};this._globalSettings={debug:!1,enableMousePrediction:!0,enableScrollPrediction:!0,positionHistorySize:8,trajectoryPredictionTime:120,scrollMargin:150,defaultHitSlop:{top:0,left:0,right:0,bottom:0},enableTabPrediction:!0,tabOffset:2};this.domObserver=null;this.positionObserver=null;this.eventListeners=new Map;this.mousePredictor=null;this.tabPredictor=null;this.scrollPredictor=null;this.handleDomMutations=t=>{t.length&&this.tabPredictor?.invalidateCache();for(let e of t)if(e.type==="childList"&&e.removedNodes.length>0)for(let i of this.elements.keys())i.isConnected||this.unregister(i,"disconnected")};this.handlePositionChange=t=>{let e=this._globalSettings.enableScrollPrediction;for(let i of t){let o=this.elements.get(i.target);o&&(e?this.scrollPredictor?.handleScrollPrefetch(o,i.boundingClientRect):T(this.trajectoryPositions.currentPoint,o.elementBounds.expandedRect)&&this.callCallback(o,{kind:"mouse",subType:"hover"}),this.handlePositionChangeDataUpdates(o,i))}this._globalSettings.enableScrollPrediction&&this.scrollPredictor?.resetScrollProps()};this.handlePositionChangeDataUpdates=(t,e)=>{let i=[],o=e.isIntersecting;t.isIntersectingWithViewport!==o&&(i.push("visibility"),t.isIntersectingWithViewport=o),o&&(i.push("bounds"),t.elementBounds={hitSlop:t.elementBounds.hitSlop,originalRect:e.boundingClientRect,expandedRect:S(e.boundingClientRect,t.elementBounds.hitSlop)}),i.length&&this.emit({type:"elementDataUpdated",elementData:t,updatedProps:i})}}generateId(){return`foresight-${++this.idCounter}`}static initialize(t){return this.isInitiated||(n.manager=new n),t!==void 0&&n.manager.alterGlobalSettings(t),n.manager}addEventListener(t,e,i){if(i?.signal?.aborted)return()=>{};let o=this.eventListeners.get(t)??[];o.push(e),this.eventListeners.set(t,o),i?.signal?.addEventListener("abort",()=>this.removeEventListener(t,e))}removeEventListener(t,e){let i=this.eventListeners.get(t);if(!i)return;let o=i.indexOf(e);o>-1&&i.splice(o,1)}emit(t){let e=this.eventListeners.get(t.type)?.slice();if(e)for(let i=0;i<e.length;i++)try{e[i](t)}catch(o){console.error(`Error in ForesightManager event listener ${i} for ${t.type}:`,o)}}get getManagerData(){return{registeredElements:this.elements,globalSettings:this._globalSettings,globalCallbackHits:this._globalCallbackHits,eventListeners:this.eventListeners}}static get isInitiated(){return!!n.manager}static get instance(){return this.initialize()}get registeredElements(){return this.elements}register({element:t,callback:e,hitSlop:i,name:o,meta:r,reactivateAfter:c}){let{shouldRegister:s,isTouchDevice:a,isLimitedConnection:l}=j();if(!s)return{isLimitedConnection:l,isTouchDevice:a,isRegistered:!1,unregister:()=>{}};let d=this.elements.get(t);if(d)return d.registerCount++,{isLimitedConnection:l,isTouchDevice:a,isRegistered:!1,unregister:()=>{}};this.isSetup||this.initializeGlobalListeners();let p=t.getBoundingClientRect(),g=i?k(i):this._globalSettings.defaultHitSlop,b={id:this.generateId(),element:t,callback:e,elementBounds:{originalRect:p,expandedRect:S(p,g),hitSlop:g},trajectoryHitData:{isTrajectoryHit:!1,trajectoryHitTime:0,trajectoryHitExpirationTimeoutId:void 0},name:o||t.id||"unnamed",isIntersectingWithViewport:D(p),registerCount:1,meta:r??{},callbackInfo:{callbackFiredCount:0,lastCallbackInvokedAt:void 0,lastCallbackCompletedAt:void 0,lastCallbackRuntime:void 0,lastCallbackStatus:void 0,lastCallbackErrorMessage:void 0,reactivateAfter:c??1/0,isCallbackActive:!0,isRunningCallback:!1,reactivateTimeoutId:void 0}};return this.elements.set(t,b),this.positionObserver?.observe(t),this.emit({type:"elementRegistered",timestamp:Date.now(),elementData:b}),{isTouchDevice:a,isLimitedConnection:l,isRegistered:!0,unregister:()=>{}}}unregister(t,e){let i=this.elements.get(t);if(!i)return;i?.trajectoryHitData.trajectoryHitExpirationTimeoutId&&clearTimeout(i.trajectoryHitData.trajectoryHitExpirationTimeoutId),i?.callbackInfo.reactivateTimeoutId&&clearTimeout(i.callbackInfo.reactivateTimeoutId),this.positionObserver?.unobserve(t),this.elements.delete(t);let o=this.elements.size===0&&this.isSetup;o&&this.removeGlobalListeners(),i&&this.emit({type:"elementUnregistered",elementData:i,timestamp:Date.now(),unregisterReason:e??"by user",wasLastElement:o})}updateNumericSettings(t,e,i,o){return O(t,this._globalSettings[e])?(this._globalSettings[e]=u(t,i,o,e),!0):!1}updateBooleanSetting(t,e){return O(t,this._globalSettings[e])?(this._globalSettings[e]=t,!0):!1}alterGlobalSettings(t){let e=[],i=this._globalSettings.trajectoryPredictionTime;this.updateNumericSettings(t?.trajectoryPredictionTime,"trajectoryPredictionTime",10,200)&&e.push({setting:"trajectoryPredictionTime",oldValue:i,newValue:this._globalSettings.trajectoryPredictionTime});let r=this._globalSettings.positionHistorySize;this.updateNumericSettings(t?.positionHistorySize,"positionHistorySize",2,30)&&(e.push({setting:"positionHistorySize",oldValue:r,newValue:this._globalSettings.positionHistorySize}),this.trajectoryPositions.positions.resize(this._globalSettings.positionHistorySize));let s=this._globalSettings.scrollMargin;if(this.updateNumericSettings(t?.scrollMargin,"scrollMargin",30,300)){let f=this._globalSettings.scrollMargin;this.scrollPredictor&&(this.scrollPredictor.scrollMargin=f),e.push({setting:"scrollMargin",oldValue:s,newValue:f})}let l=this._globalSettings.tabOffset;this.updateNumericSettings(t?.tabOffset,"tabOffset",0,20)&&(this.tabPredictor&&(this.tabPredictor.tabOffset=this._globalSettings.tabOffset),e.push({setting:"tabOffset",oldValue:l,newValue:this._globalSettings.tabOffset}));let p=this._globalSettings.enableMousePrediction;this.updateBooleanSetting(t?.enableMousePrediction,"enableMousePrediction")&&e.push({setting:"enableMousePrediction",oldValue:p,newValue:this._globalSettings.enableMousePrediction});let b=this._globalSettings.enableScrollPrediction;this.updateBooleanSetting(t?.enableScrollPrediction,"enableScrollPrediction")&&(this._globalSettings.enableScrollPrediction?this.scrollPredictor=new y({dependencies:{callCallback:this.callCallback.bind(this),emit:this.emit.bind(this),elements:this.elements},settings:{scrollMargin:this._globalSettings.scrollMargin},trajectoryPositions:this.trajectoryPositions}):(this.scrollPredictor?.cleanup(),this.scrollPredictor=null),e.push({setting:"enableScrollPrediction",oldValue:b,newValue:this._globalSettings.enableScrollPrediction}));let _=this._globalSettings.enableTabPrediction;if(this.updateBooleanSetting(t?.enableTabPrediction,"enableTabPrediction")&&(e.push({setting:"enableTabPrediction",oldValue:_,newValue:this._globalSettings.enableTabPrediction}),this._globalSettings.enableTabPrediction?this.tabPredictor=new E({dependencies:{callCallback:this.callCallback.bind(this),emit:this.emit.bind(this),elements:this.elements},settings:{tabOffset:this._globalSettings.tabOffset}}):(this.tabPredictor?.cleanup(),this.tabPredictor=null)),t?.defaultHitSlop!==void 0){let f=this._globalSettings.defaultHitSlop,F=k(t.defaultHitSlop);x(f,F)||(this._globalSettings.defaultHitSlop=F,e.push({setting:"defaultHitSlop",oldValue:f,newValue:F}),this.forceUpdateAllElementBounds())}e.length>0&&this.emit({type:"managerSettingsChanged",timestamp:Date.now(),managerData:this.getManagerData,updatedSettings:e})}updateHitCounters(t){switch(t.kind){case"mouse":this._globalCallbackHits.mouse[t.subType]++;break;case"tab":this._globalCallbackHits.tab[t.subType]++;break;case"scroll":this._globalCallbackHits.scroll[t.subType]++;break;default:}this._globalCallbackHits.total++}reactivate(t){let e=this.elements.get(t);e&&(e.callbackInfo.reactivateTimeoutId&&(clearTimeout(e.callbackInfo.reactivateTimeoutId),e.callbackInfo.reactivateTimeoutId=void 0),e.callbackInfo.isRunningCallback||(e.callbackInfo.isCallbackActive=!0,this.positionObserver?.observe(e.element),this.emit({type:"elementReactivated",elementData:e,timestamp:Date.now()})))}makeElementUnactive(t){t.callbackInfo.callbackFiredCount++,t.callbackInfo.lastCallbackInvokedAt=Date.now(),t.callbackInfo.isRunningCallback=!0,t.callbackInfo.reactivateTimeoutId&&(clearTimeout(t.callbackInfo.reactivateTimeoutId),t.callbackInfo.reactivateTimeoutId=void 0),t?.trajectoryHitData.trajectoryHitExpirationTimeoutId&&clearTimeout(t.trajectoryHitData.trajectoryHitExpirationTimeoutId)}callCallback(t,e){if(t.callbackInfo.isRunningCallback||!t.callbackInfo.isCallbackActive)return;this.makeElementUnactive(t),(async()=>{this.updateHitCounters(e),this.emit({type:"callbackInvoked",timestamp:Date.now(),elementData:t,hitType:e});let o=performance.now(),r,c=null;try{await t.callback(),r="success"}catch(s){c=s instanceof Error?s.message:String(s),r="error",console.error(`Error in callback for element ${t.name} (${t.element.tagName}):`,s)}t.callbackInfo.lastCallbackCompletedAt=Date.now(),this.emit({type:"callbackCompleted",timestamp:Date.now(),elementData:t,hitType:e,elapsed:t.callbackInfo.lastCallbackRuntime=performance.now()-o,status:t.callbackInfo.lastCallbackStatus=r,errorMessage:t.callbackInfo.lastCallbackErrorMessage=c}),t.callbackInfo.isRunningCallback=!1,t.callbackInfo.isCallbackActive=!1,this.positionObserver?.unobserve(t.element),t.callbackInfo.reactivateAfter!==1/0&&t.callbackInfo.reactivateAfter>0&&(t.callbackInfo.reactivateTimeoutId=setTimeout(()=>{this.reactivate(t.element)},t.callbackInfo.reactivateAfter))})()}initializeGlobalListeners(){if(this.isSetup||typeof window>"u"||typeof document>"u")return;let t=this._globalSettings,e={callCallback:this.callCallback.bind(this),emit:this.emit.bind(this),elements:this.elements};t.enableTabPrediction&&(this.tabPredictor=new E({dependencies:e,settings:{tabOffset:t.tabOffset}})),t.enableScrollPrediction&&(this.scrollPredictor=new y({dependencies:e,settings:{scrollMargin:t.scrollMargin},trajectoryPositions:this.trajectoryPositions})),this.mousePredictor=new C({dependencies:e,settings:{enableMousePrediction:t.enableMousePrediction,trajectoryPredictionTime:t.trajectoryPredictionTime,positionHistorySize:t.positionHistorySize},trajectoryPositions:this.trajectoryPositions}),this.domObserver=new MutationObserver(this.handleDomMutations),this.domObserver.observe(document.documentElement,{childList:!0,subtree:!0,attributes:!1}),this.positionObserver=new st(this.handlePositionChange),this.isSetup=!0}removeGlobalListeners(){this.isSetup=!1,this.domObserver?.disconnect(),this.domObserver=null,this.positionObserver?.disconnect(),this.positionObserver=null,this.mousePredictor?.cleanup(),this.tabPredictor?.cleanup(),this.scrollPredictor?.cleanup()}forceUpdateAllElementBounds(){for(let[,t]of this.elements)t.isIntersectingWithViewport&&this.forceUpdateElementBounds(t)}forceUpdateElementBounds(t){let e=t.element.getBoundingClientRect(),i=S(e,t.elementBounds.hitSlop);if(!x(i,t.elementBounds.expandedRect)){let o={...t,elementBounds:{...t.elementBounds,originalRect:e,expandedRect:i}};this.elements.set(t.element,o),this.emit({type:"elementDataUpdated",elementData:o,updatedProps:["bounds"]})}}};export{L as ForesightManager};
+function p(n,e,t,i){return n<e?console.warn(`ForesightJS: "${i}" value ${n} is below minimum bound ${e}, clamping to ${e}`):n>t&&console.warn(`ForesightJS: "${i}" value ${n} is above maximum bound ${t}, clamping to ${t}`),Math.min(Math.max(n,e),t)}function z(n){if(typeof window>"u"||typeof document>"u")return!1;let e=window.innerWidth||document.documentElement.clientWidth,t=window.innerHeight||document.documentElement.clientHeight;return n.top<t&&n.bottom>0&&n.left<e&&n.right>0}function T(n){if(typeof n=="number"){let e=p(n,0,2e3,"hitslop");return{top:e,left:e,right:e,bottom:e}}return{top:p(n.top,0,2e3,"hitslop - top"),left:p(n.left,0,2e3,"hitslop - left"),right:p(n.right,0,2e3,"hitslop - right"),bottom:p(n.bottom,0,2e3,"hitslop - bottom")}}function P(n,e){return{left:n.left-e.left,right:n.right+e.right,top:n.top-e.top,bottom:n.bottom+e.bottom}}function w(n,e){return!n||!e?n===e:n.left===e.left&&n.right===e.right&&n.top===e.top&&n.bottom===e.bottom}function C(n,e){return n.x>=e.left&&n.x<=e.right&&n.y>=e.top&&n.y<=e.bottom}function K(){let n=A(),e=te();return{isTouchDevice:n,isLimitedConnection:e,shouldRegister:!e}}function A(){return typeof window>"u"||typeof navigator>"u"?!1:window.matchMedia("(pointer: coarse)").matches&&navigator.maxTouchPoints>0}function te(){let n=navigator.connection;return n?/2g/.test(n.effectiveType)||n.saveData:!1}function N(n,e){return n!==void 0&&e!==n}var u=class{constructor(e){this._isConnected=!1;this.elements=e.elements,this.callCallback=e.callCallback,this.emit=e.emit,this.settings=e.settings}get isConnected(){return this._isConnected}disconnect(){this.isConnected&&(this.devLog(`Disconnecting ${this.moduleName}...`),this.abortController?.abort(`${this.moduleName} module disconnected`),this.onDisconnect(),this._isConnected=!1)}connect(){this.devLog(`Connecting ${this.moduleName}...`),this.onConnect(),this._isConnected=!0}devLog(e){process.env.NODE_ENV==="development"&&console.log(`\u{1F6E0}\uFE0F ${this.moduleName}: ${e}`)}createAbortController(){this.abortController&&!this.abortController.signal.aborted||(this.abortController=new AbortController,this.devLog(`Created new AbortController for ${this.moduleName}`))}};function I(n,e,t){let i=0,o=1,r=e.x-n.x,l=e.y-n.y,a=(s,d)=>{if(s===0){if(d<0)return!1}else{let c=d/s;if(s<0){if(c>o)return!1;c>i&&(i=c)}else{if(c<i)return!1;c<o&&(o=c)}}return!0};return!a(-r,n.x-t.left)||!a(r,t.right-n.x)||!a(-l,n.y-t.top)||!a(l,t.bottom-n.y)?!1:i<=o}function Y(n,e,t){let i=performance.now(),o={point:n,time:i},{x:r,y:l}=n;if(e.add(o),e.length<2)return{x:r,y:l};let[a,s]=e.getFirstLast();if(!a||!s)return{x:r,y:l};let d=(s.time-a.time)*.001;if(d===0)return{x:r,y:l};let c=s.point.x-a.point.x,h=s.point.y-a.point.y,y=c/d,g=h/d,x=t*.001,L=r+y*x,V=l+g*x;return{x:L,y:V}}var F=class extends u{constructor(t){super(t.dependencies);this.moduleName="MousePredictor";this.trajectoryPositions=t.trajectoryPositions}updatePointerState(t){let i={x:t.clientX,y:t.clientY};this.trajectoryPositions.currentPoint=i,this.settings.enableMousePrediction?this.trajectoryPositions.predictedPoint=Y(i,this.trajectoryPositions.positions,this.settings.trajectoryPredictionTime):this.trajectoryPositions.predictedPoint=i}processMouseMovement(t){this.updatePointerState(t);let i=this.settings.enableMousePrediction,o=this.trajectoryPositions.currentPoint;for(let r of this.elements.values()){if(!r.isIntersectingWithViewport||!r.callbackInfo.isCallbackActive||r.callbackInfo.isRunningCallback)continue;let l=r.elementBounds.expandedRect;if(i)I(o,this.trajectoryPositions.predictedPoint,l)&&this.callCallback(r,{kind:"mouse",subType:"trajectory"});else if(C(o,l)){this.callCallback(r,{kind:"mouse",subType:"hover"});return}}this.emit({type:"mouseTrajectoryUpdate",predictionEnabled:i,trajectoryPositions:this.trajectoryPositions})}onDisconnect(){}onConnect(){}};function $(n,e){let i=e.top-n.top,o=e.left-n.left;return i<-1?"down":i>1?"up":o<-1?"right":o>1?"left":"none"}function G(n,e,t){let{x:i,y:o}=n,r={x:i,y:o};switch(e){case"down":r.y+=t;break;case"up":r.y-=t;break;case"left":r.x-=t;break;case"right":r.x+=t;break;case"none":break;default:}return r}var M=class extends u{constructor(t){super(t.dependencies);this.moduleName="ScrollPredictor";this.predictedScrollPoint=null;this.scrollDirection=null;this.onDisconnect=()=>this.resetScrollProps();this.trajectoryPositions=t.trajectoryPositions}resetScrollProps(){this.scrollDirection=null,this.predictedScrollPoint=null}handleScrollPrefetch(t,i){!t.isIntersectingWithViewport||t.callbackInfo.isRunningCallback||!t.callbackInfo.isCallbackActive||(this.scrollDirection=this.scrollDirection??$(t.elementBounds.originalRect,i),this.scrollDirection!=="none"&&(this.predictedScrollPoint=this.predictedScrollPoint??G(this.trajectoryPositions.currentPoint,this.scrollDirection,this.settings.scrollMargin),I(this.trajectoryPositions.currentPoint,this.predictedScrollPoint,t.elementBounds.expandedRect)&&this.callCallback(t,{kind:"scroll",subType:this.scrollDirection}),this.emit({type:"scrollTrajectoryUpdate",currentPoint:this.trajectoryPositions.currentPoint,predictedPoint:this.predictedScrollPoint,scrollDirection:this.scrollDirection})))}onConnect(){}};import{tabbable as ie}from"tabbable";function X(n,e,t,i){if(e!==null&&e>-1){let o=n?e-1:e+1;if(o>=0&&o<t.length&&t[o]===i)return o}return t.findIndex(o=>o===i)}var D=class extends u{constructor(t){super(t);this.moduleName="TabPredictor";this.lastKeyDown=null;this.tabbableElementsCache=[];this.lastFocusedIndex=null;this.handleKeyDown=t=>{t.key==="Tab"&&(this.lastKeyDown=t)};this.handleFocusIn=t=>{if(!this.lastKeyDown)return;let i=t.target;if(!(i instanceof HTMLElement))return;(!this.tabbableElementsCache.length||this.lastFocusedIndex===-1)&&(this.tabbableElementsCache=ie(document.documentElement));let o=this.lastKeyDown.shiftKey,r=X(o,this.lastFocusedIndex,this.tabbableElementsCache,i);this.lastFocusedIndex=r,this.lastKeyDown=null;let l=[],a=this.settings.tabOffset,s=this.elements;for(let d=0;d<=a;d++){let c=o?r-d:r+d,h=this.tabbableElementsCache[c];h&&h instanceof Element&&s.has(h)&&l.push(h)}for(let d of l){let c=s.get(d);c&&!c.callbackInfo.isRunningCallback&&c.callbackInfo.isCallbackActive&&this.callCallback(c,{kind:"tab",subType:o?"reverse":"forwards"})}}}invalidateCache(){this.tabbableElementsCache=[],this.lastFocusedIndex=null}onConnect(){typeof document>"u"||(this.createAbortController(),document.addEventListener("keydown",this.handleKeyDown,{signal:this.abortController?.signal,passive:!0}),document.addEventListener("focusin",this.handleFocusIn,{signal:this.abortController?.signal,passive:!0}))}onDisconnect(){this.tabbableElementsCache=[],this.lastFocusedIndex=null,this.lastKeyDown=null}};import{PositionObserver as ne}from"position-observer";var R=class{constructor(e){this.head=0;this.count=0;if(e<=0)throw new Error("CircularBuffer capacity must be greater than 0");this.capacity=e,this.buffer=new Array(e)}add(e){this.buffer[this.head]=e,this.head=(this.head+1)%this.capacity,this.count<this.capacity&&this.count++}getFirst(){if(this.count!==0)return this.count<this.capacity?this.buffer[0]:this.buffer[this.head]}getLast(){if(this.count!==0){if(this.count<this.capacity)return this.buffer[this.count-1];{let e=(this.head-1+this.capacity)%this.capacity;return this.buffer[e]}}}getFirstLast(){if(this.count===0)return[void 0,void 0];if(this.count===1){let i=this.count<this.capacity?this.buffer[0]:this.buffer[this.head];return[i,i]}let e=this.getFirst(),t=this.getLast();return[e,t]}resize(e){if(e<=0)throw new Error("CircularBuffer capacity must be greater than 0");if(e===this.capacity)return;let t=this.getAllItems();if(this.capacity=e,this.buffer=new Array(e),this.head=0,this.count=0,t.length>e){let i=t.slice(-e);for(let o of i)this.add(o)}else for(let i of t)this.add(i)}getAllItems(){if(this.count===0)return[];let e=new Array(this.count);if(this.count<this.capacity)for(let t=0;t<this.count;t++)e[t]=this.buffer[t];else{let t=this.head;for(let i=0;i<this.capacity;i++){let o=(t+i)%this.capacity;e[i]=this.buffer[o]}}return e}clear(){this.head=0,this.count=0}get length(){return this.count}get size(){return this.capacity}get isFull(){return this.count===this.capacity}get isEmpty(){return this.count===0}};var f=class extends u{constructor(t){super(t);this.moduleName="DesktopHandler";this.positionObserver=null;this.trajectoryPositions={positions:new R(8),currentPoint:{x:0,y:0},predictedPoint:{x:0,y:0}};this.handlePositionChange=t=>{let i=this.settings.enableScrollPrediction;for(let o of t){let r=this.elements.get(o.target);r&&(i?this.scrollPredictor?.handleScrollPrefetch(r,o.boundingClientRect):this.checkForMouseHover(r),this.handlePositionChangeDataUpdates(r,o))}i&&this.scrollPredictor?.resetScrollProps()};this.checkForMouseHover=t=>{C(this.trajectoryPositions.currentPoint,t.elementBounds.expandedRect)&&this.callCallback(t,{kind:"mouse",subType:"hover"})};this.handlePositionChangeDataUpdates=(t,i)=>{let o=[],r=i.isIntersecting;t.isIntersectingWithViewport!==r&&(o.push("visibility"),t.isIntersectingWithViewport=r),r&&(o.push("bounds"),t.elementBounds={hitSlop:t.elementBounds.hitSlop,originalRect:i.boundingClientRect,expandedRect:P(i.boundingClientRect,t.elementBounds.hitSlop)}),o.length&&this.emit({type:"elementDataUpdated",elementData:t,updatedProps:o})};this.processMouseMovement=t=>this.mousePredictor.processMouseMovement(t);this.invalidateTabCache=()=>this.tabPredictor?.invalidateCache();this.observeElement=t=>this.positionObserver?.observe(t);this.unobserveElement=t=>this.positionObserver?.unobserve(t);this.connectTabPredictor=()=>this.tabPredictor.connect();this.connectScrollPredictor=()=>this.scrollPredictor.connect();this.connectMousePredictor=()=>this.mousePredictor.connect();this.disconnectTabPredictor=()=>this.tabPredictor.disconnect();this.disconnectScrollPredictor=()=>this.scrollPredictor.disconnect();this.disconnectMousePredictor=()=>this.mousePredictor.disconnect();this.tabPredictor=new D(t),this.scrollPredictor=new M({dependencies:t,trajectoryPositions:this.trajectoryPositions}),this.mousePredictor=new F({dependencies:t,trajectoryPositions:this.trajectoryPositions})}onConnect(){this.settings.enableTabPrediction&&this.connectTabPredictor(),this.settings.enableScrollPrediction&&this.connectScrollPredictor(),this.connectMousePredictor(),this.positionObserver=new ne(this.handlePositionChange);for(let t of this.elements.keys())this.positionObserver.observe(t)}onDisconnect(){this.disconnectMousePredictor(),this.disconnectTabPredictor(),this.disconnectScrollPredictor(),this.positionObserver?.disconnect(),this.positionObserver=null}};var _=class extends u{constructor(t){super(t);this.moduleName="ViewportPredictor";this.intersectionObserver=null;this.onConnect=()=>this.intersectionObserver=new IntersectionObserver(this.handleViewportEnter);this.observeElement=t=>this.intersectionObserver?.observe(t);this.unobserveElement=t=>this.intersectionObserver?.unobserve(t);this.handleViewportEnter=t=>{for(let i of t){if(!i.isIntersecting)continue;let o=this.elements.get(i.target);o&&(this.callCallback(o,{kind:"viewport"}),this.unobserveElement(i.target))}}}onDisconnect(){this.intersectionObserver?.disconnect(),this.intersectionObserver=null}};var k=class extends u{constructor(t){super(t);this.moduleName="TouchStartPredictor";this.onConnect=()=>this.createAbortController();this.onDisconnect=()=>{};this.handleTouchStart=t=>{let i=t.target,o=this.elements.get(i);o&&(this.callCallback(o,{kind:"touch"}),this.unobserveElement(i))}}observeElement(t){t instanceof HTMLElement&&t.addEventListener("touchstart",this.handleTouchStart,{signal:this.abortController?.signal})}unobserveElement(t){t instanceof HTMLElement&&t.removeEventListener("touchstart",this.handleTouchStart)}};var v=class extends u{constructor(t){super(t);this.moduleName="TouchDeviceHandler";this.predictor=null;this.onDisconnect=()=>this.predictor?.disconnect();this.onConnect=()=>this.setTouchPredictor();this.observeElement=t=>this.predictor?.observeElement(t);this.unobserveElement=t=>this.predictor?.unobserveElement(t);this.viewportPredictor=new _(t),this.touchStartPredictor=new k(t),this.predictor=this.viewportPredictor}setTouchPredictor(){switch(this.predictor?.disconnect(),this.settings.touchDeviceStrategy){case"viewport":this.predictor=this.viewportPredictor;break;case"onTouchStart":this.predictor=this.touchStartPredictor;break;case"none":this.predictor=null;return;default:this.settings.touchDeviceStrategy}this.predictor?.connect();for(let t of this.elements.keys())this.predictor?.observeElement(t)}};var B=class n{constructor(e){this.elements=new Map;this.idCounter=0;this.activeElementCount=0;this.isSetup=!1;this._globalCallbackHits={mouse:{hover:0,trajectory:0},tab:{forwards:0,reverse:0},scroll:{down:0,left:0,right:0,up:0},touch:0,viewport:0,total:0};this._globalSettings={debug:!1,enableMousePrediction:!0,enableScrollPrediction:!0,positionHistorySize:8,trajectoryPredictionTime:120,scrollMargin:150,defaultHitSlop:{top:0,left:0,right:0,bottom:0},enableTabPrediction:!0,tabOffset:2,touchDeviceStrategy:"onTouchStart"};this.pendingPointerEvent=null;this.rafId=null;this.domObserver=null;this.eventListeners=new Map;this.currentDeviceStrategy=A()?"touch":"mouse";this.handlePointerMove=e=>{this.pendingPointerEvent=e,e.pointerType!=this.currentDeviceStrategy&&(this.emit({type:"deviceStrategyChanged",timestamp:Date.now(),newStrategy:e.pointerType,oldStrategy:this.currentDeviceStrategy}),this.setDeviceStrategy(this.currentDeviceStrategy=e.pointerType)),!this.rafId&&(this.rafId=requestAnimationFrame(()=>{if(this.handler instanceof v){this.rafId=null;return}this.pendingPointerEvent&&this.handler.processMouseMovement(this.pendingPointerEvent),this.rafId=null}))};this.handleDomMutations=e=>{if(!e.length)return;this.desktopHandler?.invalidateTabCache();let t=!1;for(let i=0;i<e.length;i++){let o=e[i];if(o.type==="childList"&&o.removedNodes.length>0){t=!0;break}}if(t)for(let i of this.elements.keys())i.isConnected||this.unregister(i,"disconnected")};e!==void 0&&this.initializeManagerSettings(e);let t={elements:this.elements,callCallback:this.callCallback.bind(this),emit:this.emit.bind(this),settings:this._globalSettings};this.desktopHandler=new f(t),this.touchDeviceHandler=new v(t),this.handler=this.currentDeviceStrategy==="mouse"?this.desktopHandler:this.touchDeviceHandler,this.initializeGlobalListeners()}generateId(){return`foresight-${++this.idCounter}`}static initialize(e){return this.isInitiated||(n.manager=new n(e)),n.manager}addEventListener(e,t,i){if(i?.signal?.aborted)return()=>{};let o=this.eventListeners.get(e)??[];o.push(t),this.eventListeners.set(e,o),i?.signal?.addEventListener("abort",()=>this.removeEventListener(e,t))}removeEventListener(e,t){let i=this.eventListeners.get(e);if(!i)return;let o=i.indexOf(t);o>-1&&i.splice(o,1)}emit(e){let t=this.eventListeners.get(e.type)?.slice();if(t)for(let i=0;i<t.length;i++)try{t[i](e)}catch(o){console.error(`Error in ForesightManager event listener ${i} for ${e.type}:`,o)}}get getManagerData(){return{registeredElements:this.elements,globalSettings:this._globalSettings,globalCallbackHits:this._globalCallbackHits,eventListeners:this.eventListeners,currentDeviceStrategy:this.currentDeviceStrategy,activeElementCount:this.activeElementCount}}static get isInitiated(){return!!n.manager}static get instance(){return this.initialize()}get registeredElements(){return this.elements}register({element:e,callback:t,hitSlop:i,name:o,meta:r,reactivateAfter:l}){let{isTouchDevice:a,isLimitedConnection:s,shouldRegister:d}=K();if(!d)return{isLimitedConnection:s,isTouchDevice:a,isRegistered:!1,unregister:()=>{}};let c=this.elements.get(e);if(c)return c.registerCount++,{isLimitedConnection:s,isTouchDevice:a,isRegistered:!1,unregister:()=>{}};this.isSetup||this.initializeGlobalListeners();let h=e.getBoundingClientRect(),y=i?T(i):this._globalSettings.defaultHitSlop,g={id:this.generateId(),element:e,callback:t,elementBounds:{originalRect:h,expandedRect:P(h,y),hitSlop:y},name:o||e.id||"unnamed",isIntersectingWithViewport:z(h),registerCount:1,meta:r??{},callbackInfo:{callbackFiredCount:0,lastCallbackInvokedAt:void 0,lastCallbackCompletedAt:void 0,lastCallbackRuntime:void 0,lastCallbackStatus:void 0,lastCallbackErrorMessage:void 0,reactivateAfter:l??1/0,isCallbackActive:!0,isRunningCallback:!1,reactivateTimeoutId:void 0}};return this.elements.set(e,g),this.activeElementCount++,this.handler.observeElement(e),this.emit({type:"elementRegistered",timestamp:Date.now(),elementData:g}),{isTouchDevice:a,isLimitedConnection:s,isRegistered:!0,unregister:()=>{this.unregister(e)}}}unregister(e,t){let i=this.elements.get(e);if(!i)return;this.clearReactivateTimeout(i),this.handler.unobserveElement(e),this.elements.delete(e),i.callbackInfo.isCallbackActive&&this.activeElementCount--;let o=this.elements.size===0&&this.isSetup;o&&this.removeGlobalListeners(),i&&this.emit({type:"elementUnregistered",elementData:i,timestamp:Date.now(),unregisterReason:t??"by user",wasLastRegisteredElement:o})}updateHitCounters(e){switch(e.kind){case"mouse":this._globalCallbackHits.mouse[e.subType]++;break;case"tab":this._globalCallbackHits.tab[e.subType]++;break;case"scroll":this._globalCallbackHits.scroll[e.subType]++;break;case"touch":this._globalCallbackHits.touch++;break;case"viewport":this._globalCallbackHits.viewport++;break;default:}this._globalCallbackHits.total++}reactivate(e){let t=this.elements.get(e);t&&(this.isSetup||this.initializeGlobalListeners(),this.clearReactivateTimeout(t),t.callbackInfo.isRunningCallback||(t.callbackInfo.isCallbackActive=!0,this.activeElementCount++,this.handler.observeElement(e),this.emit({type:"elementReactivated",elementData:t,timestamp:Date.now()})))}clearReactivateTimeout(e){clearTimeout(e.callbackInfo.reactivateTimeoutId),e.callbackInfo.reactivateTimeoutId=void 0}makeElementUnactive(e){e.callbackInfo.callbackFiredCount++,e.callbackInfo.lastCallbackInvokedAt=Date.now(),e.callbackInfo.isRunningCallback=!0,this.clearReactivateTimeout(e)}callCallback(e,t){if(e.callbackInfo.isRunningCallback||!e.callbackInfo.isCallbackActive)return;this.makeElementUnactive(e),(async()=>{this.updateHitCounters(t),this.emit({type:"callbackInvoked",timestamp:Date.now(),elementData:e,hitType:t});let o=performance.now(),r,l=null;try{await e.callback(),r="success"}catch(s){l=s instanceof Error?s.message:String(s),r="error",console.error(`Error in callback for element ${e.name}:`,s)}e.callbackInfo.lastCallbackCompletedAt=Date.now(),e.callbackInfo.isRunningCallback=!1,e.callbackInfo.isCallbackActive=!1,this.activeElementCount--,this.handler.unobserveElement(e.element),e.callbackInfo.reactivateAfter!==1/0&&(e.callbackInfo.reactivateTimeoutId=setTimeout(()=>{this.reactivate(e.element)},e.callbackInfo.reactivateAfter));let a=this.activeElementCount===0;a&&this.removeGlobalListeners(),this.emit({type:"callbackCompleted",timestamp:Date.now(),elementData:e,hitType:t,elapsed:e.callbackInfo.lastCallbackRuntime=performance.now()-o,status:e.callbackInfo.lastCallbackStatus=r,errorMessage:e.callbackInfo.lastCallbackErrorMessage=l,wasLastActiveElement:a})})()}setDeviceStrategy(e){this.handler.disconnect(),this.handler=e==="mouse"?this.desktopHandler:this.touchDeviceHandler,this.handler.connect()}initializeGlobalListeners(){this.isSetup||typeof document>"u"||(this.setDeviceStrategy(this.currentDeviceStrategy),document.addEventListener("pointermove",this.handlePointerMove),this.domObserver=new MutationObserver(this.handleDomMutations),this.domObserver.observe(document.documentElement,{childList:!0,subtree:!0,attributes:!1}),this.isSetup=!0)}removeGlobalListeners(){typeof document>"u"||(this.isSetup=!1,this.domObserver?.disconnect(),this.domObserver=null,document.removeEventListener("pointermove",this.handlePointerMove),this.handler.disconnect(),this.rafId&&(cancelAnimationFrame(this.rafId),this.rafId=null),this.pendingPointerEvent=null)}forceUpdateAllElementBounds(){for(let[,e]of this.elements)e.isIntersectingWithViewport&&this.forceUpdateElementBounds(e)}forceUpdateElementBounds(e){let t=e.element.getBoundingClientRect(),i=P(t,e.elementBounds.hitSlop);if(!w(i,e.elementBounds.expandedRect)){let o={...e,elementBounds:{...e.elementBounds,originalRect:t,expandedRect:i}};this.elements.set(e.element,o),this.emit({type:"elementDataUpdated",elementData:o,updatedProps:["bounds"]})}}initializeManagerSettings(e){this.updateNumericSettings(e.trajectoryPredictionTime,"trajectoryPredictionTime",10,200),this.updateNumericSettings(e.positionHistorySize,"positionHistorySize",2,30),this.updateNumericSettings(e.scrollMargin,"scrollMargin",30,300),this.updateNumericSettings(e.tabOffset,"tabOffset",0,20),this.updateBooleanSetting(e.enableMousePrediction,"enableMousePrediction"),this.updateBooleanSetting(e.enableScrollPrediction,"enableScrollPrediction"),this.updateBooleanSetting(e.enableTabPrediction,"enableTabPrediction"),e.defaultHitSlop!==void 0&&(this._globalSettings.defaultHitSlop=T(e.defaultHitSlop)),e.touchDeviceStrategy!==void 0&&(this._globalSettings.touchDeviceStrategy=e.touchDeviceStrategy),e.debug!==void 0&&(this._globalSettings.debug=e.debug)}updateNumericSettings(e,t,i,o){return N(e,this._globalSettings[t])?(this._globalSettings[t]=p(e,i,o,t),!0):!1}updateBooleanSetting(e,t){return N(e,this._globalSettings[t])?(this._globalSettings[t]=e,!0):!1}alterGlobalSettings(e){let t=[],i=this._globalSettings.trajectoryPredictionTime;this.updateNumericSettings(e?.trajectoryPredictionTime,"trajectoryPredictionTime",10,200)&&t.push({setting:"trajectoryPredictionTime",oldValue:i,newValue:this._globalSettings.trajectoryPredictionTime});let r=this._globalSettings.positionHistorySize;this.updateNumericSettings(e?.positionHistorySize,"positionHistorySize",2,30)&&(t.push({setting:"positionHistorySize",oldValue:r,newValue:this._globalSettings.positionHistorySize}),this.desktopHandler.trajectoryPositions.positions.resize(this._globalSettings.positionHistorySize));let a=this._globalSettings.scrollMargin;if(this.updateNumericSettings(e?.scrollMargin,"scrollMargin",30,300)){let m=this._globalSettings.scrollMargin;t.push({setting:"scrollMargin",oldValue:a,newValue:m})}let d=this._globalSettings.tabOffset;this.updateNumericSettings(e?.tabOffset,"tabOffset",0,20)&&(this._globalSettings.tabOffset=p(e.tabOffset,0,20,"tabOffset"),t.push({setting:"tabOffset",oldValue:d,newValue:this._globalSettings.tabOffset}));let h=this._globalSettings.enableMousePrediction;this.updateBooleanSetting(e?.enableMousePrediction,"enableMousePrediction")&&t.push({setting:"enableMousePrediction",oldValue:h,newValue:this._globalSettings.enableMousePrediction});let g=this._globalSettings.enableScrollPrediction;this.updateBooleanSetting(e?.enableScrollPrediction,"enableScrollPrediction")&&(this.handler instanceof f&&(this._globalSettings.enableScrollPrediction?this.handler.connectScrollPredictor():this.handler.disconnectScrollPredictor()),t.push({setting:"enableScrollPrediction",oldValue:g,newValue:this._globalSettings.enableScrollPrediction}));let L=this._globalSettings.enableTabPrediction;if(this.updateBooleanSetting(e?.enableTabPrediction,"enableTabPrediction")&&(this.handler instanceof f&&(this._globalSettings.enableTabPrediction?this.handler.connectTabPredictor():this.handler.disconnectTabPredictor()),t.push({setting:"enableTabPrediction",oldValue:L,newValue:this._globalSettings.enableTabPrediction})),e?.defaultHitSlop!==void 0){let m=this._globalSettings.defaultHitSlop,b=T(e.defaultHitSlop);w(m,b)||(this._globalSettings.defaultHitSlop=b,t.push({setting:"defaultHitSlop",oldValue:m,newValue:b}),this.forceUpdateAllElementBounds())}if(e?.touchDeviceStrategy!==void 0){let m=this._globalSettings.touchDeviceStrategy,b=e.touchDeviceStrategy;this._globalSettings.touchDeviceStrategy=b,t.push({setting:"touchDeviceStrategy",oldValue:m,newValue:b}),this.handler instanceof v&&this.handler.setTouchPredictor()}t.length>0&&this.emit({type:"managerSettingsChanged",timestamp:Date.now(),managerData:this.getManagerData,updatedSettings:t})}};export{B as ForesightManager};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "js.foresight",
-  "version": "3.2.1",
-  "description": "Predicts mouse trajectory to trigger actions as users approach elements, enabling anticipatory UI updates or pre-loading. Made with vanilla javascript and usable in every framework.",
+  "version": "3.3.0",
+  "description": "Predicts where users will click based on mouse movement, keyboard navigation, and scroll behavior. Includes touch device support. Triggers callbacks before interactions happen to enable prefetching and faster UI responses. Works with any framework.",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -26,6 +26,8 @@
     "javascript-prefetch",
     "smart-prefetch",
     "fast-prefetch",
+    "interaction-prediction",
+    "mobile-prefetch",
     "mouse-trajectory",
     "element-hitslop",
     "foresight",
@@ -39,21 +41,23 @@
   ],
   "author": "Bart Spaans",
   "license": "MIT",
+  "llms": "https://foresightjs.com/llms.txt",
+  "llmsFull": "https://foresightjs.com/llms-full.txt",
   "devDependencies": {
-    "@testing-library/dom": "^10.4.0",
-    "@testing-library/jest-dom": "^6.6.3",
-    "@types/node": "^22.15.30",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^6.6.4",
+    "@types/node": "^24.1.0",
     "@vitest/coverage-v8": "3.2.4",
     "@vitest/ui": "^3.2.4",
     "happy-dom": "^18.0.1",
     "jsdom": "^26.1.0",
     "tslib": "^2.8.1",
     "tsup": "^8.5.0",
-    "typescript": "^5.8.3",
+    "typescript": "^5.9.2",
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "position-observer": "^1.0.0",
+    "position-observer": "^1.0.1",
     "tabbable": "^6.2.0"
   },
   "scripts": {