{"record":{"id":"7ced69f926c4817e","repo":"alibaba/page-agent","slug":"simulatormask-motion-overlay-unavailable","errorCode":null,"errorMessage":"[SimulatorMask] Motion overlay unavailable:","messagePattern":"\\[SimulatorMask\\] Motion overlay unavailable:","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"packages/page-controller/src/mask/SimulatorMask.ts","lineNumber":40,"sourceCode":"\n\tconstructor() {\n\t\tsuper()\n\n\t\tthis.wrapper.id = 'page-agent-runtime_simulator-mask'\n\t\tthis.wrapper.className = styles.wrapper\n\t\tthis.wrapper.setAttribute('data-browser-use-ignore', 'true')\n\t\tthis.wrapper.setAttribute('data-page-agent-ignore', 'true')\n\n\t\ttry {\n\t\t\tconst motion = new Motion({\n\t\t\t\tmode: isPageDark() ? 'dark' : 'light',\n\t\t\t\tstyles: { position: 'absolute', inset: '0' },\n\t\t\t})\n\t\t\tthis.motion = motion\n\t\t\tthis.wrapper.appendChild(motion.element)\n\t\t\tmotion.autoResize(this.wrapper)\n\t\t} catch (e) {\n\t\t\tconsole.warn('[SimulatorMask] Motion overlay unavailable:', e)\n\t\t}\n\n\t\t// Capture all mouse, keyboard, and wheel events\n\t\tthis.wrapper.addEventListener('click', (e) => {\n\t\t\te.stopPropagation()\n\t\t\te.preventDefault()\n\t\t})\n\t\tthis.wrapper.addEventListener('mousedown', (e) => {\n\t\t\te.stopPropagation()\n\t\t\te.preventDefault()\n\t\t})\n\t\tthis.wrapper.addEventListener('mouseup', (e) => {\n\t\t\te.stopPropagation()\n\t\t\te.preventDefault()\n\t\t})\n\t\tthis.wrapper.addEventListener('mousemove', (e) => {\n\t\t\te.stopPropagation()\n\t\t\te.preventDefault()","sourceCodeStart":22,"sourceCodeEnd":58,"githubUrl":"https://github.com/alibaba/page-agent/blob/d02db1ee7c41f5315beda88bab2fe935c580f662/packages/page-controller/src/mask/SimulatorMask.ts#L22-L58","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["If seen in tests/jsdom: mock or stub the motion overlay module, or construct the mask only in browser-like environments","Verify the wrapper element is attached to a real document before the mask is created","Update @page-agent/* packages together so the motion overlay API matches the mask's expectations","If motion animation is not needed, ignore the warning — the mask and event blocking remain functional"],"exampleFix":"// before (jsdom test fails to create overlay)\nconst mask = new SimulatorMask(document.body)\n\n// after (guard in test env)\nif (typeof document !== 'undefined' && document.createElementNS) {\n  mask = new SimulatorMask(document.body)\n}","handlingStrategy":"fallback","validationCode":"// Before enabling the mask, check the environment supports the overlay\nconst canUseMask =\n  typeof document !== 'undefined' &&\n  typeof document.createElementNS === 'function' &&\n  typeof requestAnimationFrame === 'function'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only construct SimulatorMask in real browser environments (guard in tests/SSR)","Keep @page-agent/* workspace versions in sync when upgrading","Treat the warning as informational; assert mask event-blocking still works in your E2E tests"],"tags":["simulator-mask","motion-overlay","browser-compat","optional-feature"],"backgroundTag":"optional-feature-degraded","analyzedSha":"d02db1ee7c41f5315beda88bab2fe935c580f662","analyzedAt":"2026-08-28T19:39:48.634Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}