# Development Tools

The `ForesightJS` development tools are framework agnostic and work the same in React as anywhere else; initialize them once next to your `ForesightManager.initialize` call.

[![npm version](https://img.shields.io/npm/v/js.foresight-devtools.svg)](https://www.npmjs.com/package/js.foresight-devtools) [![npm downloads](https://img.shields.io/npm/dt/js.foresight-devtools.svg)](https://www.npmjs.com/package/js.foresight-devtools)

`ForesightJS` offers dedicated [Development Tools](https://github.com/spaansba/ForesightJS/tree/main/packages/js.foresight-devtools), written in [Lit](https://lit.dev/), 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](https://foresightjs.com/#playground), 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[​](#installation "Direct link to 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[​](#enabling-development-tools "Direct link to 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[​](#development-tools-features "Direct link to 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[​](#control-panel "Direct link to Control Panel")

The control panel has three tabs: Settings, Elements, and Log.

#### Settings Tab[​](#settings-tab "Direct link to 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[​](#elements-tab "Direct link to 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`](/docs/getting-started/typescript.md#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[​](#log-tab "Direct link to 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`](/docs/debugging/static-properties.md#foresightmanagerinstancegetmanagerdata) 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.