js.foresight-devtools

ForesightJS offers dedicated Development Tools, written in Lit, to help you better understand and fine-tune how ForesightJS works within your application. You can see the development tools in action on the playground page, which includes visual trajectory indicators, element boundaries, and a control panel in the bottom-right corner.

These tools are built entirely using ForesightJS's built-in events, demonstrating how you can create your own monitoring and debugging tools using the same event system.

Installation

To install the ForesightJS Development Tools package, use your preferred package manager:

pnpm add -D js.foresight-devtools
# or
npm install -D js.foresight-devtools
# or
yarn add -D js.foresight-devtools

Enabling Development Tools

import { ForesightManager } from "js.foresight"
import { ForesightDevtools } from "js.foresight-devtools"

// Initialize ForesightJS
ForesightManager.initialize({})

// Initialize the development tools (all options are optional)
ForesightDevtools.initialize({
  showDebugger: true,
  isControlPanelDefaultMinimized: false, // optional setting which allows you to minimize the control panel on default
  showNameTags: true, // optional setting which shows the name of the element
  sortElementList: "visibility", // optional setting for how the elements in the control panel are sorted
  logging: {
    logLocation: "controlPanel", // Where to log the Foresight Events
    callbackCompleted: true,
    elementReactivated: true,
    callbackInvoked: true,
    elementDataUpdated: false,
    elementRegistered: false,
    elementUnregistered: false,
    managerSettingsChanged: true,
    mouseTrajectoryUpdate: false, // dont log this to the devtools
    scrollTrajectoryUpdate: false, // dont log this to the devtools
    deviceStrategyChanged: true,
  },
})

Development Tools Features

Once enabled, the ForesightJS Development Tools add several visual layers to your application, including mouse and scroll trajectories and element hitboxes. A control panel also appears in the bottom-right corner of the screen.

Control Panel

The control panel provides three main tabs for debugging and configuration. Each tab serves a specific purpose in understanding and tuning ForesightJS behavior.

Settings Tab

The Settings tab provides real-time controls for all Global Configurations. Changes made through these controls immediately affect the ForesightManager configuration, allowing you to see how different settings impact your app without fiddling in your code.

Elements Tab

The Elements tab displays a overview of all currently registered elements within the ForesightManager. Each element entry shows its current status through color-coded indicators:

• 🟢 Green - Active visible elements in desktop mode
• ⚫ Grey - Active invisible elements in desktop mode
• 🟣 Purple - Active elements while in touch device mode (all elements, we dont track visibility in this mode)
• 🟡 Yellow - Elements which callbacks are currently executing
• 🔘 Light Gray - Inactive elements

Each element can also be expanded to reveal its ForesightElementData information including settings, callback status, and metadata. A countdown timer appears for elements in their reactivation cooldown period (reactivateAfter), clicking this timer will instantly reactivate the element.

Log Tab

The Log tab displays real-time events emitted by ForesightJS. You can see callback execution times, the full element's lifecycle and other system events. Events can be filtered through the devtools initialization configuration or in the control panel itself.

You can also print out the complete ForesightManager.instance.getManagerData state without having to call it from your code.

:::caution Avoid logging frequently emitted events to the browser console, as it can noticeably slow down your development environment. Use the control panel for this instead. :::

:::note Element overlay visualization and visibility sorting in the control panel only work with desktop/mouse prediction strategies. When debugging touchDeviceStrategy configurations, these features are not available as touch strategies don't track the same positioning data. :::