feat: support emulating additional CSS media features

This patch adds support for:

- `forced-colors`
- `prefers-contrast`
- `prefers-reduced-motion`

Author: mathiasbynens

docs/tool-reference.md

@@ -285,8 +285,11 @@
 - **colorScheme** (enum: "dark", "light", "auto") _(optional)_: [`Emulate`](#emulate) the dark or the light mode. Set to "auto" to reset to the default.
 - **cpuThrottlingRate** (number) _(optional)_: Represents the CPU slowdown factor. Omit or set the rate to 1 to disable throttling
 - **extraHttpHeaders** (string) _(optional)_: Extra HTTP headers as a JSON string object, e.g. {"X-Custom": "value", "Authorization": "Bearer token"}. Headers are included into every HTTP request originating from the page and persist across navigations until cleared. Pass an empty string to clear all extra headers.
+- **forcedColors** (enum: "active", "none", "auto") _(optional)_: [`Emulate`](#emulate) the `forced-colors` CSS media feature. Set to "auto" to reset to the default.
 - **geolocation** (string) _(optional)_: Geolocation (`<latitude>,<longitude>`) to [`emulate`](#emulate). Latitude between -90 and 90. Longitude between -180 and 180. Omit to clear the geolocation override.
 - **networkConditions** (enum: "Offline", "Slow 3G", "Fast 3G", "Slow 4G", "Fast 4G") _(optional)_: Throttle network. Omit to disable throttling.
+- **prefersContrast** (enum: "more", "less", "custom", "no-preference", "auto") _(optional)_: [`Emulate`](#emulate) the `prefers-contrast` CSS media feature. Set to "auto" to reset to the default.
+- **prefersReducedMotion** (enum: "reduce", "no-preference", "auto") _(optional)_: [`Emulate`](#emulate) the `prefers-reduced-motion` CSS media feature. Set to "auto" to reset to the default.
 - **userAgent** (string) _(optional)_: User agent to [`emulate`](#emulate). Set to empty string to clear the user agent override.
 - **viewport** (string) _(optional)_: [`Emulate`](#emulate) device viewports '<width>x<height>x<devicePixelRatio>[,mobile][,touch][,landscape]'. 'touch' and 'mobile' to [`emulate`](#emulate) mobile devices. 'landscape' to [`emulate`](#emulate) landscape mode.
 

src/McpPage.ts

@@ -93,7 +93,10 @@ import type {
 } from './tools/ToolDefinition.js';
 import type {
   EmulationSettings,
+  ForcedColors,
   GeolocationOptions,
+  PrefersContrast,
+  PrefersReducedMotion,
   TextSnapshotNode,
 } from './types.js';
 import {logger} from './utils/logger.js';
@@ -550,6 +553,18 @@ export class McpPage implements ContextPage {
     return this.emulationSettings.colorScheme ?? null;
   }
 
+  get forcedColors(): ForcedColors | null {
+    return this.emulationSettings.forcedColors ?? null;
+  }
+
+  get prefersContrast(): PrefersContrast | null {
+    return this.emulationSettings.prefersContrast ?? null;
+  }
+
+  get prefersReducedMotion(): PrefersReducedMotion | null {
+    return this.emulationSettings.prefersReducedMotion ?? null;
+  }
+
   // Public for testability: tests spy on this method to verify throttle multipliers.
   createWaitForHelper(
     cpuMultiplier: number,
@@ -995,12 +1010,30 @@ export class McpPage implements ContextPage {
     await this.emulate(currentSetting);
   }
 
+  async #emulateMediaFeatures(settings: EmulationSettings): Promise<void> {
+    // `page.emulateMediaFeatures` replaces all previously emulated media
+    // features, so every supported feature is sent on each call. An empty
+    // value disables the override for that feature.
+    await this.pptrPage.emulateMediaFeatures([
+      {name: 'prefers-color-scheme', value: settings.colorScheme ?? ''},
+      {name: 'forced-colors', value: settings.forcedColors ?? ''},
+      {name: 'prefers-contrast', value: settings.prefersContrast ?? ''},
+      {
+        name: 'prefers-reduced-motion',
+        value: settings.prefersReducedMotion ?? '',
+      },
+    ]);
+  }
+
   async emulate(options: {
     networkConditions?: string;
     cpuThrottlingRate?: number;
     geolocation?: GeolocationOptions;
     userAgent?: string;
     colorScheme?: 'dark' | 'light' | 'auto';
+    forcedColors?: ForcedColors | 'auto';
+    prefersContrast?: PrefersContrast | 'auto';
+    prefersReducedMotion?: PrefersReducedMotion | 'auto';
     viewport?: Viewport;
     extraHttpHeaders?: Record<string, string> | undefined;
   }): Promise<void> {
@@ -1070,17 +1103,34 @@ export class McpPage implements ContextPage {
     }
 
     if (!options.colorScheme || options.colorScheme === 'auto') {
-      await page.emulateMediaFeatures([
-        {name: 'prefers-color-scheme', value: ''},
-      ]);
       delete newSettings.colorScheme;
     } else {
-      await page.emulateMediaFeatures([
-        {name: 'prefers-color-scheme', value: options.colorScheme},
-      ]);
       newSettings.colorScheme = options.colorScheme;
     }
 
+    if (!options.forcedColors || options.forcedColors === 'auto') {
+      delete newSettings.forcedColors;
+    } else {
+      newSettings.forcedColors = options.forcedColors;
+    }
+
+    if (!options.prefersContrast || options.prefersContrast === 'auto') {
+      delete newSettings.prefersContrast;
+    } else {
+      newSettings.prefersContrast = options.prefersContrast;
+    }
+
+    if (
+      !options.prefersReducedMotion ||
+      options.prefersReducedMotion === 'auto'
+    ) {
+      delete newSettings.prefersReducedMotion;
+    } else {
+      newSettings.prefersReducedMotion = options.prefersReducedMotion;
+    }
+
+    await this.#emulateMediaFeatures(newSettings);
+
     if (!options.viewport) {
       delete newSettings.viewport;
     } else {

src/McpResponse.ts

@@ -886,6 +886,9 @@ export class McpResponse implements Response {
       userAgent?: string;
       cpuThrottlingRate?: number;
       colorScheme?: string;
+      forcedColors?: string;
+      prefersContrast?: string;
+      prefersReducedMotion?: string;
       dialog?: {
         type: string;
         message: string;
@@ -1011,6 +1014,26 @@ export class McpResponse implements Response {
       structuredContent.colorScheme = colorScheme;
     }
 
+    const forcedColors = this.#page?.forcedColors;
+    if (forcedColors) {
+      response.push(`Emulating forced-colors: ${forcedColors}`);
+      structuredContent.forcedColors = forcedColors;
+    }
+
+    const prefersContrast = this.#page?.prefersContrast;
+    if (prefersContrast) {
+      response.push(`Emulating prefers-contrast: ${prefersContrast}`);
+      structuredContent.prefersContrast = prefersContrast;
+    }
+
+    const prefersReducedMotion = this.#page?.prefersReducedMotion;
+    if (prefersReducedMotion) {
+      response.push(
+        `Emulating prefers-reduced-motion: ${prefersReducedMotion}`,
+      );
+      structuredContent.prefersReducedMotion = prefersReducedMotion;
+    }
+
     const dialog = this.#page?.getDialog();
     if (dialog) {
       const defaultValueIfNeeded =

src/config/cli-options.ts

@@ -276,6 +276,30 @@ export const commands: Commands = {
         required: false,
         enum: ['dark', 'light', 'auto'],
       },
+      forcedColors: {
+        name: 'forcedColors',
+        type: 'string',
+        description:
+          'Emulate the `forced-colors` CSS media feature. Set to "auto" to reset to the default.',
+        required: false,
+        enum: ['active', 'none', 'auto'],
+      },
+      prefersContrast: {
+        name: 'prefersContrast',
+        type: 'string',
+        description:
+          'Emulate the `prefers-contrast` CSS media feature. Set to "auto" to reset to the default.',
+        required: false,
+        enum: ['more', 'less', 'custom', 'no-preference', 'auto'],
+      },
+      prefersReducedMotion: {
+        name: 'prefersReducedMotion',
+        type: 'string',
+        description:
+          'Emulate the `prefers-reduced-motion` CSS media feature. Set to "auto" to reset to the default.',
+        required: false,
+        enum: ['reduce', 'no-preference', 'auto'],
+      },
       viewport: {
         name: 'viewport',
         type: 'string',

src/telemetry/tool_call_metrics.json

@@ -105,6 +105,18 @@
       {
         "name": "page_id",
         "argType": "number"
+      },
+      {
+        "name": "forced_colors",
+        "argType": "string"
+      },
+      {
+        "name": "prefers_contrast",
+        "argType": "string"
+      },
+      {
+        "name": "prefers_reduced_motion",
+        "argType": "string"
       }
     ]
   },

src/tools/ToolDefinition.ts

@@ -41,6 +41,9 @@ import type {
   TextSnapshotNode,
   GeolocationOptions,
   CD4ACommentThread,
+  ForcedColors,
+  PrefersContrast,
+  PrefersReducedMotion,
 } from '../types.js';
 import type {McpWorker} from '../McpWorker.js';
 import type {PaginationOptions} from '../types.js';
@@ -424,6 +427,9 @@ export type ContextPage = Readonly<{
     geolocation?: GeolocationOptions;
     userAgent?: string;
     colorScheme?: 'dark' | 'light' | 'auto';
+    forcedColors?: ForcedColors | 'auto';
+    prefersContrast?: PrefersContrast | 'auto';
+    prefersReducedMotion?: PrefersReducedMotion | 'auto';
     viewport?: Viewport;
   }): Promise<void>;
   waitForTextOnPage(text: string[], timeout?: number): Promise<Element>;

src/tools/emulation.ts

@@ -6,6 +6,11 @@
  */
 
 import {zod, PredefinedNetworkConditions} from '../third_party/index.js';
+import {
+  FORCED_COLORS_VALUES,
+  PREFERS_CONTRAST_VALUES,
+  PREFERS_REDUCED_MOTION_VALUES,
+} from '../types.js';
 
 import {ToolCategory} from './categories.js';
 import {
@@ -84,6 +89,24 @@ export const emulate = definePageTool(() => ({
       .describe(
         'Emulate the dark or the light mode. Set to "auto" to reset to the default.',
       ),
+    forcedColors: zod
+      .enum([...FORCED_COLORS_VALUES, 'auto'])
+      .optional()
+      .describe(
+        'Emulate the `forced-colors` CSS media feature. Set to "auto" to reset to the default.',
+      ),
+    prefersContrast: zod
+      .enum([...PREFERS_CONTRAST_VALUES, 'auto'])
+      .optional()
+      .describe(
+        'Emulate the `prefers-contrast` CSS media feature. Set to "auto" to reset to the default.',
+      ),
+    prefersReducedMotion: zod
+      .enum([...PREFERS_REDUCED_MOTION_VALUES, 'auto'])
+      .optional()
+      .describe(
+        'Emulate the `prefers-reduced-motion` CSS media feature. Set to "auto" to reset to the default.',
+      ),
     viewport: zod
       .string()
       .transform(viewportTransform)

src/types.ts

@@ -22,12 +22,33 @@ export interface GeolocationOptions {
   longitude: number;
 }
 
+export const FORCED_COLORS_VALUES = ['active', 'none'] as const;
+export type ForcedColors = (typeof FORCED_COLORS_VALUES)[number];
+
+export const PREFERS_CONTRAST_VALUES = [
+  'more',
+  'less',
+  'custom',
+  'no-preference',
+] as const;
+export type PrefersContrast = (typeof PREFERS_CONTRAST_VALUES)[number];
+
+export const PREFERS_REDUCED_MOTION_VALUES = [
+  'reduce',
+  'no-preference',
+] as const;
+export type PrefersReducedMotion =
+  (typeof PREFERS_REDUCED_MOTION_VALUES)[number];
+
 export interface EmulationSettings {
   networkConditions?: string;
   cpuThrottlingRate?: number;
   geolocation?: GeolocationOptions;
   userAgent?: string;
   colorScheme?: 'dark' | 'light';
+  forcedColors?: ForcedColors;
+  prefersContrast?: PrefersContrast;
+  prefersReducedMotion?: PrefersReducedMotion;
   viewport?: Viewport;
   extraHttpHeaders?: Record<string, string>;
 }

tests/McpPage.test.ts

@@ -539,24 +539,74 @@ describe('McpPage', () => {
       });
     });
 
-    it('calls emulateMediaFeatures with dark color scheme', async () => {
-      const {mcpPage, pptrPage} = await createMcpPage();
-      await mcpPage.emulate({colorScheme: 'dark'});
-      assert.strictEqual(mcpPage.colorScheme, 'dark');
-      sinon.assert.calledOnceWithExactly(pptrPage.emulateMediaFeatures, [
-        {name: 'prefers-color-scheme', value: 'dark'},
-      ]);
-    });
+    describe('media features', () => {
+      it('emulates all media features in a single call', async () => {
+        const {mcpPage, pptrPage} = await createMcpPage();
+        await mcpPage.emulate({
+          colorScheme: 'dark',
+          forcedColors: 'active',
+          prefersContrast: 'more',
+          prefersReducedMotion: 'reduce',
+        });
+        assert.strictEqual(mcpPage.colorScheme, 'dark');
+        assert.strictEqual(mcpPage.forcedColors, 'active');
+        assert.strictEqual(mcpPage.prefersContrast, 'more');
+        assert.strictEqual(mcpPage.prefersReducedMotion, 'reduce');
+        sinon.assert.calledOnceWithExactly(pptrPage.emulateMediaFeatures, [
+          {name: 'prefers-color-scheme', value: 'dark'},
+          {name: 'forced-colors', value: 'active'},
+          {name: 'prefers-contrast', value: 'more'},
+          {name: 'prefers-reduced-motion', value: 'reduce'},
+        ]);
+      });
 
-    it('calls emulateMediaFeatures with empty string to reset color scheme', async () => {
-      const {mcpPage, pptrPage} = await createMcpPage();
-      await mcpPage.emulate({colorScheme: 'dark'});
-      await mcpPage.emulate({colorScheme: 'auto'});
-      assert.strictEqual(mcpPage.colorScheme, null);
-      sinon.assert.calledTwice(pptrPage.emulateMediaFeatures);
-      sinon.assert.calledWithExactly(pptrPage.emulateMediaFeatures.secondCall, [
-        {name: 'prefers-color-scheme', value: ''},
-      ]);
+      it('resets media features set to auto', async () => {
+        const {mcpPage, pptrPage} = await createMcpPage();
+        await mcpPage.emulate({
+          colorScheme: 'dark',
+          forcedColors: 'active',
+          prefersContrast: 'more',
+          prefersReducedMotion: 'reduce',
+        });
+        await mcpPage.emulate({
+          colorScheme: 'auto',
+          forcedColors: 'auto',
+          prefersContrast: 'auto',
+          prefersReducedMotion: 'auto',
+        });
+        assert.strictEqual(mcpPage.colorScheme, null);
+        assert.strictEqual(mcpPage.forcedColors, null);
+        assert.strictEqual(mcpPage.prefersContrast, null);
+        assert.strictEqual(mcpPage.prefersReducedMotion, null);
+        sinon.assert.calledTwice(pptrPage.emulateMediaFeatures);
+        sinon.assert.calledWithExactly(
+          pptrPage.emulateMediaFeatures.secondCall,
+          [
+            {name: 'prefers-color-scheme', value: ''},
+            {name: 'forced-colors', value: ''},
+            {name: 'prefers-contrast', value: ''},
+            {name: 'prefers-reduced-motion', value: ''},
+          ],
+        );
+      });
+
+      it('resets omitted media features', async () => {
+        const {mcpPage, pptrPage} = await createMcpPage();
+        await mcpPage.emulate({forcedColors: 'active'});
+        await mcpPage.emulate({prefersContrast: 'less'});
+        assert.strictEqual(mcpPage.forcedColors, null);
+        assert.strictEqual(mcpPage.prefersContrast, 'less');
+        sinon.assert.calledTwice(pptrPage.emulateMediaFeatures);
+        sinon.assert.calledWithExactly(
+          pptrPage.emulateMediaFeatures.secondCall,
+          [
+            {name: 'prefers-color-scheme', value: ''},
+            {name: 'forced-colors', value: ''},
+            {name: 'prefers-contrast', value: 'less'},
+            {name: 'prefers-reduced-motion', value: ''},
+          ],
+        );
+      });
     });
 
     it('calls setViewport with the given dimensions merged with defaults', async () => {

tests/ToolHandler.test.ts

@@ -1284,6 +1284,9 @@ describe('ToolHandler', () => {
     sinon.stub(mockPage, 'viewport').get(() => undefined);
     sinon.stub(mockPage, 'userAgent').get(() => undefined);
     sinon.stub(mockPage, 'colorScheme').get(() => undefined);
+    sinon.stub(mockPage, 'forcedColors').get(() => undefined);
+    sinon.stub(mockPage, 'prefersContrast').get(() => undefined);
+    sinon.stub(mockPage, 'prefersReducedMotion').get(() => undefined);
     sinon.stub(mockPage, 'cpuThrottlingRate').get(() => 1);
     mockContext.getSelectedMcpPage.returns(mockPage);
     const canonicalFilePath = path.resolve('/canonical/output.png');