Skip to main content
Version: 4.x

Development Tools

In Astro the easiest way to enable the devtools is the integration's devtools option, which loads them automatically during astro dev and keeps them out of production builds:

// astro.config.mjs
foresight({
  devtools: true,
})

You still need to install the js.foresight-devtools package yourself (see below). If you want to customize the devtools options, skip the integration option and initialize them from a <script> tag instead.

npm version npm downloads

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.

They are built entirely on ForesightJS's built-in events, so they double as a working example of what you can build on 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 { ForesightDevtools } from "js.foresight-devtools"

// Initialize ForesightJS
ForesightManager.initialize({})

// Initialize the development tools (all options are optional)
ForesightDevtools.initialize({
  show: {
    controlPanel: true, // the floating control panel
    nameTags: true, // the element name above each registered element
    elementOverlays: true, // the hit-slop boundary around each registered element
    mouseTrajectory: true, // the predicted mouse trajectory line
    scrollTrajectory: true, // the predicted scroll trajectory line
  },
  isControlPanelDefaultMinimized: false, // start with the control panel minimized
  sortElementList: "visibility", // "visibility" | "documentOrder" | "insertionOrder"
  logging: {
    logLocation: "controlPanel", // "controlPanel" | "console" | "both" | "none"
    callbackCompleted: true,
    callbackInvoked: true,
    elementRegistered: false,
    elementUnregistered: false,
    managerSettingsChanged: true,
    mouseTrajectoryUpdate: false, // too noisy to log
    scrollTrajectoryUpdate: false, // too noisy to log
    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 has three tabs: Settings, Elements, and Log.

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 shows every element currently registered with the ForesightManager, grouped into Active and Inactive sections. Each element entry shows its current status through a color-coded indicator:

  • 🟢 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

Inactive elements also carry one or more reason badges explaining why they are inactive (an element can have several at once, e.g. disabled while detached):

  • disabled - turned off via the enabled option
  • parked - removed from the DOM (isParked: true); the element stays registered but inactive and resumes when it reconnects
  • limited - on a limited connection (data saver / slow network)
  • fired - already ran its callback and is waiting on reactivateAfter (with the default Infinity it stays fired)

Each element can also be expanded to reveal its ForesightElementState information including settings, callback status, and metadata. For fired elements with a finite reactivateAfter, a countdown timer appears for their reactivation cooldown period; 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.