Interaction Guard

Import

import { startInteractionGuard } from "webotron/plugins/interaction-guard";

Entry Point

• startInteractionGuard(view, options?)

Usage

const guard = await startInteractionGuard(view, {
  message: "Interaction blocked: automation session is active",
  blockKeyboard: true,
  disableInHeadless: true,
});

await guard.enable();

const offBlocked = guard.onBlockedAttempt((event) => {
  console.log("Blocked interaction", event.eventType, event.x, event.y);
});

// Run automation actions while guard is enabled.
await view.click("#submit");

await guard.disable();
offBlocked();
await guard.stop();

Controller API

• enable()
• disable()
• isEnabled()
• onBlockedAttempt(handler)
• stop()

Options

Option	Type	Purpose
message	string	UI text shown when interaction is blocked.
zIndex	number	Overlay z-index used for the guard UI.
blockKeyboard	boolean	Whether keyboard events are blocked while enabled.
toastDurationMs	number	Duration of blocked-interaction feedback message.
disableInHeadless	boolean	When true (default), plugin returns a no-op controller in headless sessions to avoid unnecessary overhead.

Headless behavior

By default, the interaction guard does not activate in headless browsers because there is no direct human interaction to block. If you still want guard behavior in headless mode for a specific workflow, pass disableInHeadless: false.

Plugin Coordination

This plugin is decoupled from the mouse pointer visualizer implementation details. Coordination happens over the host-side plugin message bus (plugins/shared/plugin-message-bus.ts) using message topics:

• automation:bypass:before
• automation:bypass:after

This means removing the visualizer plugin does not require changing interaction-guard code.