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

@@ -69,6 +69,7 @@ import {
 import {TextSnapshot} from './TextSnapshot.js';
 import type {Locator} from './third_party/index.js';
 import {
+  CdpPage,
   PredefinedNetworkConditions,
   type Dialog,
   type ElementHandle,
@@ -93,7 +94,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 +554,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 +1011,36 @@ export class McpPage implements ContextPage {
     await this.emulate(currentSetting);
   }
 
+  async #emulateMediaFeatures(settings: EmulationSettings): Promise<void> {
+    const page = this.pptrPage;
+    if (!(page instanceof CdpPage)) {
+      throw new Error('Media feature emulation requires a CDP page.');
+    }
+    // `Emulation.setEmulatedMedia` 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 page._client().send('Emulation.setEmulatedMedia', {
+      features: [
+        {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 +1110,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>;
 }