ForesightJS Documentation

ForesightJS is a lightweight JavaScript library designed to predict user intent, allowing you to prefetch content before a user explicitly requests it.

It solves the problem of when to fetch data by analyzing user behavior such as mouse trajectory and tab navigation. This allows for proactive loading that works out of the box for both desktop and mobile devices.

To use ForesightJS, you follow a simple mental model:

1. ForesightJS handles the 'When': It predicts the optimal moment to start fetching based on intent.
2. You handle the 'What' and 'How': You provide a callback function when registering an element that defines which resource to load and which loading/caching strategy to use.

ForesightJS is a lightweight JavaScript library with full TypeScript support designed to predict user intent. It achieves this by analyzing user interactions such as mouse movements and keyboard navigation to enable proactive optimizations like:

• Mouse prediction: Anticipating where a user is moving their cursor.
• Tab prediction: Predicting which tab or navigation element a user might select.
• Mobile/Desktop prefetching: Triggering resource prefetching based on predicted intent to improve perceived performance.

ForesightJS is a lightweight library designed to predict user intent based on mouse movements and keyboard navigation (such as tab prediction).

When using ForesightJS within a Vue application, you interact with it via the official @foresightjs/vue package using two primary mechanisms:

1. The v-foresight directive: Used to register specific DOM elements for tracking and prediction.
2. Composables: Used to access and react to the prediction state within your component logic.

The Angular package provides several ways to integrate ForesightJS:

• ForesightDirective: A standalone [fsForesight] directive for element registration via callback or options object.
• ForesightService: An injectable service for manual registration and subscribing to manager events.
• ForesightComponent: A standalone wrapper component that registers its host element.
• injectForesightEvent: A helper function to subscribe to a ForesightManager event for the lifetime of the current injection context.

The v-foresight directive is designed for the simplest prefetching implementation: you attach it to an element, provide a callback, and the directive handles registration and unregistration automatically.

If you need access to the element's actual prediction state (e.g., to change UI based on how likely a user is to interact with an element), you should use the useForesight composable instead.

Mouse prediction anticipates click targets by analyzing cursor velocity and trajectory.

Mechanism:

1. Tracking: mousemove events record clientX and clientY coordinates. The amount of history kept is controlled by the positionHistorySize setting.
2. Algorithm: The predictNextMousePosition function uses linear extrapolation. It calculates average velocity from the position history and projects the current position along the trajectory based on the trajectoryPredictionTimeInMs setting.
3. Intersection: The library uses the Liang-Barsky line clipping algorithm (lineSegmentIntersectsRect) to check if the predicted path intersects an element's rectangle. This check includes the element's hitSlop to increase accuracy.

ForesightJS automatically switches prediction logic based on the detected device type to ensure optimal performance and accuracy:

Desktop/Keyboard Users

Uses behavior-based tracking including:

• Mouse trajectory prediction: Anticipating where the user is moving the cursor.
• Keyboard navigation tracking: Monitoring focus and navigation patterns.
• Scroll-based prefetching: Predicting content needs based on scroll velocity and direction.

Mobile Devices

Uses touch-based signals including:

• Viewport enter detection: Predicting intent when elements enter the viewport.
• Touch start events: Using initial touch contact to anticipate navigation (this behavior is configurable via the touchDeviceStrategy option).

ForesightJS is designed for efficient code splitting. While the full library is ~32 KB minified, the library lazy-loads handlers and predictors based on the device type and enabled features. This ensures users only download the code they actually use.

Example Scenarios:

• Touch Device: Loads Core + TouchDeviceHandler + one Touch predictor.
• Desktop User: Loads Core + DesktopHandler + enabled predictors (Mouse, Tab, or Scroll).