How to Configure `enableMask` to Control SimulatorMask Visibility in Page Agent

Set enableMask to true in your PageControllerConfig to activate the visual overlay, or call showMask() and hideMask() at runtime to toggle visibility programmatically.

The SimulatorMask is a lightweight visual overlay in the alibaba/page-agent repository that blocks user interaction while automated actions execute. Controlling this mask requires understanding the enableMask configuration flag defined in the Page Controller and the runtime API exposed for dynamic visibility management.

Understanding the enableMask Configuration Option

The enableMask flag is defined in the PageControllerConfig interface within packages/page-controller/src/PageController.ts. By default, this property is set to false, meaning the mask is disabled unless explicitly activated.

export interface PageControllerConfig extends dom.DomConfig {
  viewportExpansion?: number
  /** Enable visual mask overlay during operations (default: false) */
  enableMask?: boolean                     // ← definition
}

However, when using the UI-enabled entry point, the default behavior changes. In packages/page-agent/src/PageAgent.ts (lines 17–20), the PageAgent class merges user configuration and defaults enableMask to true:

const pageController = new PageController({
  ...config,
  enableMask: config.enableMask ?? true,   // ← defaults to true
})

This means headless implementations start with the mask disabled, while UI-based agents enable it automatically unless you explicitly opt out.

Initializing the SimulatorMask

When enableMask is truthy during construction, the controller lazily initializes the mask via the private initMask() method. This occurs at line 97 of PageController.ts:

if (config.enableMask) this.initMask()

The mask is not created if enableMask remains false, conserving resources and preventing unnecessary DOM manipulation.

Runtime Control of the Simulator Mask

After instantiation, you can programmatically reveal or hide the overlay regardless of the initial configuration. The PageController exposes two async methods for this purpose (lines 100–112):

await pageController.showMask(); // displays the overlay
await pageController.hideMask(); // removes the overlay

These methods allow fine-grained control over when users can interact with the underlying page during multi-step automation workflows.

Configuration Examples

Disable the Mask for Debugging

To completely disable the mask (useful for faster debugging or headless environments), explicitly set enableMask to false:

import { PageAgent } from '@page-agent/page-agent';

const agent = new PageAgent({
  // other AgentConfig fields …
  enableMask: false,           // mask will never be created
});

// The UI panel still works, but no overlay blocks the page.

Toggle Visibility During Execution

Keep the mask enabled (the default in UI mode) and control visibility around specific operations:

import { PageAgent } from '@page-agent/page-agent';

const agent = new PageAgent({
  // …your config
  // enableMask omitted → defaults to true
});

// Show the mask while a long-running action occurs
await agent.pageController.showMask();
await agent.pageController.clickElement(42); // some automated click
await agent.pageController.hideMask();      // hide when done

Dynamically Enable After Construction

If you initialize the controller with enableMask: false but later require the overlay, manually initialize and display the mask:

import { PageAgent } from '@page-agent/page-agent';

const agent = new PageAgent({
  // mask disabled initially
  enableMask: false,
});

// Later we decide we need the overlay
await agent.pageController.initMask();   // manual init (optional)
await agent.pageController.showMask();

Summary

• Configuration location: PageControllerConfig in packages/page-controller/src/PageController.ts defines enableMask with a default of false.
• UI default: PageAgent in packages/page-agent/src/PageAgent.ts overrides this to true for UI-enabled instances.
• Lazy loading: The mask initializes only when enableMask is truthy during construction.
• Runtime API: Use showMask() and hideMask() to toggle visibility after initialization.
• Implementation: The visual overlay logic resides in packages/page-controller/src/mask/SimulatorMask.ts.

Frequently Asked Questions

What is the default value of enableMask?

In the core PageController, the default is false. However, when using the PageAgent UI entry point, the default becomes true because the code explicitly sets enableMask: config.enableMask ?? true during instantiation.

Can I toggle the mask after initialization?

Yes. Even if enableMask was set to false initially, you can call await pageController.initMask() followed by showMask() to activate the overlay at any time. Similarly, hideMask() removes it without destroying the instance.

Where is the mask implementation located?

The SimulatorMask implementation is located at packages/page-controller/src/mask/SimulatorMask.ts. This file contains the visual overlay logic that blocks user interaction when active.

Does disabling enableMask affect the UI panel functionality?

No. Disabling enableMask only prevents the creation of the visual overlay that blocks page interaction. The UI panel and other PageAgent features continue to function normally, allowing you to observe automation without the SimulatorMask blocking the viewport.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}