alibaba/page-agent · warning

[SimulatorMask] Motion overlay unavailable:

Error message

[SimulatorMask] Motion overlay unavailable:

What it means

SimulatorMask's constructor tries to create a motion overlay (an animated cursor/pointer visual) and attach it to the mask wrapper. If creating the overlay throws for any reason (e.g. the motion module fails to initialize in the current browser or environment), the constructor catches the error and logs this warning. The mask still works — only the optional motion animation is disabled.

Source

Thrown at packages/page-controller/src/mask/SimulatorMask.ts:40

	constructor() {
		super()

		this.wrapper.id = 'page-agent-runtime_simulator-mask'
		this.wrapper.className = styles.wrapper
		this.wrapper.setAttribute('data-browser-use-ignore', 'true')
		this.wrapper.setAttribute('data-page-agent-ignore', 'true')

		try {
			const motion = new Motion({
				mode: isPageDark() ? 'dark' : 'light',
				styles: { position: 'absolute', inset: '0' },
			})
			this.motion = motion
			this.wrapper.appendChild(motion.element)
			motion.autoResize(this.wrapper)
		} catch (e) {
			console.warn('[SimulatorMask] Motion overlay unavailable:', e)
		}

		// Capture all mouse, keyboard, and wheel events
		this.wrapper.addEventListener('click', (e) => {
			e.stopPropagation()
			e.preventDefault()
		})
		this.wrapper.addEventListener('mousedown', (e) => {
			e.stopPropagation()
			e.preventDefault()
		})
		this.wrapper.addEventListener('mouseup', (e) => {
			e.stopPropagation()
			e.preventDefault()
		})
		this.wrapper.addEventListener('mousemove', (e) => {
			e.stopPropagation()
			e.preventDefault()

View on GitHub (pinned to d02db1ee7c)

Solutions

1. If seen in tests/jsdom: mock or stub the motion overlay module, or construct the mask only in browser-like environments
2. Verify the wrapper element is attached to a real document before the mask is created
3. Update @page-agent/* packages together so the motion overlay API matches the mask's expectations
4. If motion animation is not needed, ignore the warning — the mask and event blocking remain functional

Example fix

// before (jsdom test fails to create overlay)
const mask = new SimulatorMask(document.body)

// after (guard in test env)
if (typeof document !== 'undefined' && document.createElementNS) {
  mask = new SimulatorMask(document.body)
}

// Before enabling the mask, check the environment supports the overlay
const canUseMask =
  typeof document !== 'undefined' &&
  typeof document.createElementNS === 'function' &&
  typeof requestAnimationFrame === 'function'

When it happens

Trigger: Constructing `new SimulatorMask(...)` (directly or via `new PageController({ enableMask: true })`) in an environment where `createMotionOverlay()`/`motion.autoResize()` throws — e.g. unsupported CSS features, a DOM-less or test environment, or a wrapper element the motion library cannot attach to.

Common situations: Running automated tests (jsdom/happy-dom) or SSR-like environments where the motion overlay's DOM/CSS APIs are unavailable; older browsers lacking APIs the overlay relies on; version mismatches between @page-agent/ui and @page-agent/page-controller after partial upgrades.

AI-assisted analysis of alibaba/page-agent@d02db1ee7c (2026-08-28). Data as JSON: /api/errors/7ced69f926c4817e. Report an issue: GitHub.