Module foreground 

Foreground emulation for background tabs (ADR-004).

Chromium treats a tab in a minimized window, or any tab while the display is locked, as hidden: requestAnimationFrame never fires, timers are throttled, document.visibilityState is hidden and document.hasFocus() is false. Emulation.setFocusEmulationEnabled flips all of that, but only for as long as the CDP session that enabled it stays attached.

So both the CLI (browser-control tab foreground <browser>/<tab> on) and the MCP tool (browser_tab_foreground) use the same thing: a small detached holder process (browser-control tab foreground-hold, a hidden subcommand) that attaches one session, enables the emulation, and blocks until it is stopped, the tab goes away, or the browser exits. Its PID is recorded in the registry so off can stop it and tab listings can show the flag from either surface. The holder is push-only: it waits on CDP events and a termination signal; nothing polls or wakes on a timer. This is the documented exception to the daemonless rule in ADR-002.

Constants

DEFAULT_TIMEOUT

Default lifetime of a holder. Agents forget to turn things off; an hour covers a long debugging session without keeping a game at 60 fps in the background forever.

Functions

active_targets

Target ids under foreground emulation for a browser.

apply

Make Chromium treat the tab as focused and visible (or stop doing so). setFocusEmulationEnabled is what flips document.visibilityState, document.hasFocus(), requestAnimationFrame, and timer throttling for a minimized window or a locked display; setIdleOverride additionally answers the Idle Detection API with “active, unlocked”.

hold

Body of the hidden tab foreground-hold subcommand: attach, emulate, record, and block until told to stop or the tab/browser goes away.

spawn_holder

Start a detached holder for the tab that expires after timeout, or return the existing one. Returns (pid, created).

status

Whether a live holder exists for the tab.

stop_all

Stop every holder on a browser. Returns how many were running.

stop_holder

Stop the holder for the tab, if any. Returns whether one was running.