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

> Learn how to configure enableMask to control SimulatorMask visibility in alibaba/page-agent. Set enableMask to true or use showMask hideMask functions for dynamic control.

- Repository: [Alibaba/page-agent](https://github.com/alibaba/page-agent)
- Tags: how-to-guide
- Published: 2026-03-09

---

**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`](https://github.com/alibaba/page-agent/blob/main/packages/page-controller/src/PageController.ts). By default, this property is set to `false`, meaning the mask is disabled unless explicitly activated.

```ts
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`](https://github.com/alibaba/page-agent/blob/main/packages/page-agent/src/PageAgent.ts) (lines 17–20), the `PageAgent` class merges user configuration and defaults `enableMask` to `true`:

```ts
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`](https://github.com/alibaba/page-agent/blob/main/PageController.ts):

```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):

```ts
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`:

```ts
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:

```ts
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:

```ts
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`](https://github.com/alibaba/page-agent/blob/main/packages/page-controller/src/PageController.ts) defines `enableMask` with a default of `false`.
- **UI default**: `PageAgent` in [`packages/page-agent/src/PageAgent.ts`](https://github.com/alibaba/page-agent/blob/main/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`](https://github.com/alibaba/page-agent/blob/main/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`](https://github.com/alibaba/page-agent/blob/main/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.