@epsilon-asi/actors 0.0.1

package/src/browser/BrowserFactory.ts

@@ -0,0 +1,253 @@
+import puppeteer from 'puppeteer-core';
+import { BrowserSession } from './BrowserSession.js';
+import { ConfigError } from '../errors/ConfigError.js';
+import type { BrowserRuntimeConfig, ExistingChromeProfileConfig, RemoteDebuggingChromeConfig, RuntimeConfig } from './RuntimeConfig.js';
+import { isExistingChromeProfileConfig, isRemoteDebuggingChromeConfig, normalizeRuntimeConfig } from './RuntimeConfig.js';
+import type { BrowserContextLike, BrowserLike, PageLike, PuppeteerConnectOptions, PuppeteerLauncher, PuppeteerLaunchOptions } from './PuppeteerLike.js';
+import { validateExistingProfileConfig, validateRemoteDebuggingConfig } from './profileValidation.js';
+
+export class BrowserFactory {
+  constructor(private readonly launcher: PuppeteerLauncher = puppeteer as unknown as PuppeteerLauncher) {}
+
+  buildLaunchOptions(profile: ExistingChromeProfileConfig): PuppeteerLaunchOptions {
+    const args = [
+      ...(profile.profileDirectory !== undefined ? [`--profile-directory=${profile.profileDirectory}`] : []),
+      ...(profile.args ?? [])
+    ];
+
+    const options: PuppeteerLaunchOptions = {
+      browser: 'chrome',
+      channel: profile.channel ?? 'chrome',
+      headless: false,
+      userDataDir: profile.userDataDir,
+      args
+    };
+
+    if (profile.executablePath !== undefined) options.executablePath = profile.executablePath;
+    if (profile.defaultViewport !== undefined) options.defaultViewport = profile.defaultViewport;
+    if (profile.dumpio !== undefined) options.dumpio = profile.dumpio;
+
+    return options;
+  }
+
+  buildConnectOptions(config: RemoteDebuggingChromeConfig): PuppeteerConnectOptions {
+    if (config.browserURL !== undefined && config.browserWSEndpoint !== undefined) {
+      throw new ConfigError('Use either browser.browserURL or browser.browserWSEndpoint, not both.');
+    }
+
+    const options: Record<string, unknown> = {};
+
+    if (config.browserWSEndpoint !== undefined) {
+      options.browserWSEndpoint = config.browserWSEndpoint;
+    } else {
+      options.browserURL = config.browserURL ?? `http://${config.remoteDebuggingHost ?? '127.0.0.1'}:${config.remoteDebuggingPort ?? 9222}`;
+    }
+
+    if (config.defaultViewport !== undefined) options.defaultViewport = config.defaultViewport;
+    if (config.protocolTimeout !== undefined) options.protocolTimeout = config.protocolTimeout;
+    if (config.slowMo !== undefined) options.slowMo = config.slowMo;
+
+    return options as PuppeteerConnectOptions;
+  }
+
+  async launch(config: RuntimeConfig): Promise<BrowserSession> {
+    const normalized = normalizeRuntimeConfig(config);
+
+    if (isExistingChromeProfileConfig(normalized.browser)) {
+      return this.launchExistingProfile(normalized as RuntimeConfig & { browser: ExistingChromeProfileConfig });
+    }
+
+    if (isRemoteDebuggingChromeConfig(normalized.browser)) {
+      return this.connectToRemoteDebuggingBrowser(normalized as RuntimeConfig & { browser: RemoteDebuggingChromeConfig });
+    }
+
+    throw new ConfigError('Unsupported browser mode.');
+  }
+
+  private async launchExistingProfile(config: RuntimeConfig & { browser: ExistingChromeProfileConfig }): Promise<BrowserSession> {
+    validateExistingProfileConfig(config.browser);
+
+    let browser: BrowserLike;
+    try {
+      browser = await this.launcher.launch(this.buildLaunchOptions(config.browser));
+    } catch (error) {
+      if ((config.browser.runningInstance?.enabled ?? true) && isLikelyProfileInUseError(error)) {
+        return this.connectToAlreadyRunningProfile(config, error);
+      }
+
+      throw explainLaunchFailure(error, config.browser);
+    }
+
+    const { context, page } = await this.preparePage(browser, config);
+    return new BrowserSession(browser, context, page, config.browser, 'launched');
+  }
+
+  private async connectToAlreadyRunningProfile(
+    config: RuntimeConfig & { browser: ExistingChromeProfileConfig },
+    launchError: unknown
+  ): Promise<BrowserSession> {
+    const remoteBrowser = this.buildProfileLockedConnectConfig(config.browser);
+    validateRemoteDebuggingConfig(remoteBrowser);
+
+    const connect = this.launcher.connect;
+    if (connect === undefined) {
+      throw new ConfigError('Chrome profile is already running, but the configured Puppeteer launcher does not support connect().', {
+        cause: launchError,
+        details: profileLockConnectDetails(config.browser, remoteBrowser, launchError)
+      });
+    }
+
+    let browser: BrowserLike;
+    try {
+      browser = await connect.call(this.launcher, this.buildConnectOptions(remoteBrowser));
+    } catch (connectError) {
+      throw explainProfileLockedConnectFailure(connectError, config.browser, remoteBrowser, launchError);
+    }
+
+    const connectedRuntimeConfig: RuntimeConfig & { browser: RemoteDebuggingChromeConfig } = {
+      ...config,
+      browser: remoteBrowser
+    };
+    const { context, page } = await this.preparePage(browser, connectedRuntimeConfig);
+    return new BrowserSession(browser, context, page, remoteBrowser, 'connected');
+  }
+
+  private buildProfileLockedConnectConfig(profile: ExistingChromeProfileConfig): RemoteDebuggingChromeConfig {
+    const running = profile.runningInstance ?? {};
+    const remoteBrowser: RemoteDebuggingChromeConfig = {
+      mode: 'remote-debugging',
+      remoteDebuggingHost: running.remoteDebuggingHost ?? '127.0.0.1',
+      remoteDebuggingPort: running.remoteDebuggingPort ?? 9222,
+      reuseExistingPage: running.reuseExistingPage ?? false,
+      closeBrowserOnFinish: false,
+      disconnectOnFinish: running.disconnectOnFinish ?? true
+    };
+
+    if (running.browserURL !== undefined) remoteBrowser.browserURL = running.browserURL;
+    if (running.browserWSEndpoint !== undefined) remoteBrowser.browserWSEndpoint = running.browserWSEndpoint;
+    if (running.protocolTimeout !== undefined) remoteBrowser.protocolTimeout = running.protocolTimeout;
+    if (running.slowMo !== undefined) remoteBrowser.slowMo = running.slowMo;
+    if (profile.defaultViewport !== undefined) remoteBrowser.defaultViewport = profile.defaultViewport;
+    if (profile.startUrl !== undefined) remoteBrowser.startUrl = profile.startUrl;
+
+    return remoteBrowser;
+  }
+
+  private async connectToRemoteDebuggingBrowser(config: RuntimeConfig & { browser: RemoteDebuggingChromeConfig }): Promise<BrowserSession> {
+    validateRemoteDebuggingConfig(config.browser);
+
+    const connect = this.launcher.connect;
+    if (connect === undefined) {
+      throw new ConfigError('The configured Puppeteer launcher does not support connect().');
+    }
+
+    let browser: BrowserLike;
+    try {
+      browser = await connect.call(this.launcher, this.buildConnectOptions(config.browser));
+    } catch (error) {
+      throw explainConnectFailure(error, config.browser);
+    }
+
+    const { context, page } = await this.preparePage(browser, config);
+    return new BrowserSession(browser, context, page, config.browser, 'connected');
+  }
+
+  private async preparePage(browser: BrowserLike, config: RuntimeConfig & { browser: BrowserRuntimeConfig }): Promise<{ context: BrowserContextLike; page: PageLike }> {
+    const context = browser.defaultBrowserContext();
+    const pages = await browser.pages();
+    const page = config.browser.reuseExistingPage !== false && pages[0] !== undefined
+      ? pages[0]
+      : await browser.newPage();
+
+    page.setDefaultTimeout?.(config.defaultTimeoutMs ?? 15_000);
+    page.setDefaultNavigationTimeout?.(config.navigationTimeoutMs ?? 30_000);
+
+    if (config.browser.startUrl !== undefined) {
+      await page.goto(config.browser.startUrl, { waitUntil: 'domcontentloaded' });
+    }
+
+    return { context, page };
+  }
+}
+
+function isLikelyProfileInUseError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return /DevToolsActivePort|SingletonLock|already\s+(?:in\s+use|running)|browser is already running|userDataDir|user data directory|profile.*(?:lock|in use|running)/i.test(message);
+}
+
+function explainLaunchFailure(error: unknown, profile: ExistingChromeProfileConfig): ConfigError {
+  const message = error instanceof Error ? error.message : String(error);
+  const likelyProfileIssue = isLikelyProfileInUseError(error) || /profile/i.test(message);
+
+  if (likelyProfileIssue) {
+    return new ConfigError(
+      'Could not launch Chrome with the configured existing profile because it appears to already be running. Close other Chrome windows using this profile, or start Chrome once with a local remote debugging endpoint and let existing-profile mode connect to it.',
+      {
+        cause: error,
+        details: {
+          userDataDir: profile.userDataDir,
+          profileDirectory: profile.profileDirectory ?? '(default)',
+          launchError: message
+        }
+      }
+    );
+  }
+
+  return new ConfigError('Could not launch Chrome with the configured existing profile.', {
+    cause: error,
+    details: {
+      userDataDir: profile.userDataDir,
+      profileDirectory: profile.profileDirectory ?? '(default)',
+      launchError: message
+    }
+  });
+}
+
+function explainConnectFailure(error: unknown, config: RemoteDebuggingChromeConfig): ConfigError {
+  const message = error instanceof Error ? error.message : String(error);
+  return new ConfigError(
+    'Could not connect to the existing Chrome debugging endpoint. Make sure Chrome was started with --remote-debugging-port and that the browserURL/browserWSEndpoint is correct.',
+    {
+      cause: error,
+      details: {
+        browserURL: config.browserURL ?? `http://${config.remoteDebuggingHost ?? '127.0.0.1'}:${config.remoteDebuggingPort ?? 9222}`,
+        browserWSEndpoint: config.browserWSEndpoint ?? '(not configured)',
+        connectError: message
+      }
+    }
+  );
+}
+
+function explainProfileLockedConnectFailure(
+  connectError: unknown,
+  profile: ExistingChromeProfileConfig,
+  remoteBrowser: RemoteDebuggingChromeConfig,
+  launchError: unknown
+): ConfigError {
+  const connectMessage = connectError instanceof Error ? connectError.message : String(connectError);
+  return new ConfigError(
+    'Chrome profile is already running, but the configured local DevTools endpoint could not be reached. Ensure Chrome was started with --remote-debugging-port and that the endpoint is bound only to localhost.',
+    {
+      cause: connectError,
+      details: profileLockConnectDetails(profile, remoteBrowser, launchError, connectMessage)
+    }
+  );
+}
+
+function profileLockConnectDetails(
+  profile: ExistingChromeProfileConfig,
+  remoteBrowser: RemoteDebuggingChromeConfig,
+  launchError: unknown,
+  connectError?: string
+): Record<string, unknown> {
+  const launchMessage = launchError instanceof Error ? launchError.message : String(launchError);
+  return {
+    userDataDir: profile.userDataDir,
+    profileDirectory: profile.profileDirectory ?? '(default)',
+    endpoint: remoteBrowser.browserWSEndpoint ?? remoteBrowser.browserURL ?? `http://${remoteBrowser.remoteDebuggingHost ?? '127.0.0.1'}:${remoteBrowser.remoteDebuggingPort ?? 9222}`,
+    browserURL: remoteBrowser.browserURL ?? `http://${remoteBrowser.remoteDebuggingHost ?? '127.0.0.1'}:${remoteBrowser.remoteDebuggingPort ?? 9222}`,
+    browserWSEndpoint: remoteBrowser.browserWSEndpoint ?? '(not configured)',
+    launchError: launchMessage,
+    ...(connectError !== undefined ? { connectError } : {})
+  };
+}

package/src/browser/BrowserSession.ts

@@ -0,0 +1,50 @@
+import type { BrowserRuntimeConfig } from './RuntimeConfig.js';
+import type { BrowserContextLike, BrowserLike, PageLike } from './PuppeteerLike.js';
+
+export type BrowserSessionKind = 'launched' | 'connected';
+
+export class BrowserSession {
+  readonly connectionMode: BrowserSessionKind;
+
+  constructor(
+    readonly browser: BrowserLike,
+    readonly context: BrowserContextLike,
+    readonly page: PageLike,
+    readonly profile: BrowserRuntimeConfig,
+    readonly kind: BrowserSessionKind = profile.mode === 'remote-debugging' ? 'connected' : 'launched'
+  ) {
+    this.connectionMode = kind;
+  }
+
+  shouldCloseOnFinish(): boolean {
+    if (this.kind === 'connected' && this.profile.mode === 'remote-debugging') {
+      return this.profile.closeBrowserOnFinish === true || this.profile.disconnectOnFinish !== false;
+    }
+
+    // In launched mode, closeBrowserOnFinish=false means "detach but keep Chrome running".
+    return true;
+  }
+
+  async close(): Promise<void> {
+    if (this.kind === 'connected') {
+      if (this.profile.mode === 'remote-debugging' && this.profile.closeBrowserOnFinish === true && this.profile.disconnectOnFinish === false) {
+        await this.browser.close();
+        return;
+      }
+
+      if (this.profile.mode === 'remote-debugging' && this.profile.disconnectOnFinish === false) {
+        return;
+      }
+
+      await this.browser.disconnect?.();
+      return;
+    }
+
+    if (this.profile.closeBrowserOnFinish === false) {
+      await this.browser.disconnect?.();
+      return;
+    }
+
+    await this.browser.close();
+  }
+}

package/src/browser/PuppeteerLike.ts

@@ -0,0 +1,65 @@
+import type {
+  Browser,
+  BrowserContext,
+  ConnectOptions,
+  HTTPResponse,
+  LaunchOptions,
+  Page,
+  WaitForOptions,
+  WaitForSelectorOptions
+} from 'puppeteer-core';
+
+export type PuppeteerLaunchOptions = LaunchOptions;
+export type PuppeteerConnectOptions = ConnectOptions;
+
+export interface PuppeteerLauncher {
+  launch(options: PuppeteerLaunchOptions): Promise<BrowserLike>;
+  connect?(options: PuppeteerConnectOptions): Promise<BrowserLike>;
+}
+
+export interface BrowserLike {
+  defaultBrowserContext(): BrowserContextLike;
+  pages(): Promise<PageLike[]>;
+  newPage(): Promise<PageLike>;
+  close(): Promise<void>;
+  disconnect?(): Promise<void> | void;
+}
+
+export interface BrowserContextLike {
+  // Intentionally minimal; actors normally interact with PageLike.
+}
+
+export interface KeyboardLike {
+  type(text: string, options?: { delay?: number }): Promise<void>;
+  press(key: string, options?: { delay?: number }): Promise<void>;
+}
+
+export interface PageLike {
+  keyboard: KeyboardLike;
+  goto(url: string, options?: WaitForOptions): Promise<HTTPResponse | null>;
+  waitForSelector(selector: string, options?: WaitForSelectorOptions): Promise<unknown>;
+  waitForNavigation(options?: WaitForOptions): Promise<HTTPResponse | null>;
+  click(selector: string, options?: Record<string, unknown>): Promise<void>;
+  focus(selector: string): Promise<void>;
+  $eval<T>(selector: string, pageFunction: (element: Element, ...args: unknown[]) => T, ...args: unknown[]): Promise<T>;
+  $$eval<T>(selector: string, pageFunction: (elements: Element[], ...args: unknown[]) => T, ...args: unknown[]): Promise<T>;
+  evaluate<T>(pageFunction: (...args: unknown[]) => T, ...args: unknown[]): Promise<T>;
+  url(): string;
+  title(): Promise<string>;
+  content(): Promise<string>;
+  screenshot(options?: Record<string, unknown>): Promise<Uint8Array | string>;
+  setDefaultTimeout?(timeout: number): void;
+  setDefaultNavigationTimeout?(timeout: number): void;
+}
+
+export function asBrowserLike(browser: Browser): BrowserLike {
+  return browser as unknown as BrowserLike;
+}
+
+export function asBrowserContextLike(context: BrowserContext): BrowserContextLike {
+  return context as unknown as BrowserContextLike;
+}
+
+export function asPageLike(page: Page): PageLike {
+  return page as unknown as PageLike;
+}

package/src/browser/RuntimeConfig.ts

@@ -0,0 +1,152 @@
+import os from 'node:os';
+import path from 'node:path';
+import type { HumanTypingOptions } from '../interaction/HumanTyping.js';
+
+export type ChromeReleaseChannel = 'chrome' | 'chrome-beta' | 'chrome-dev' | 'chrome-canary';
+
+export interface BrowserSessionBehavior {
+  defaultViewport?: { width: number; height: number } | null;
+  startUrl?: string;
+  reuseExistingPage?: boolean;
+  /**
+   * Existing-profile mode defaults to true because the framework owns the browser it launched.
+   * Remote-debugging mode defaults to false because Chrome is usually a long-lived host process.
+   */
+  closeBrowserOnFinish?: boolean;
+}
+
+export interface RemoteDebuggingEndpointConfig {
+  /**
+   * HTTP endpoint for an already-running Chrome instance, e.g. http://127.0.0.1:9222.
+   * Use either browserURL or browserWSEndpoint, not both.
+   */
+  browserURL?: string;
+  /** WebSocket endpoint from /json/version, e.g. ws://127.0.0.1:9222/devtools/browser/<id>. */
+  browserWSEndpoint?: string;
+  /** Used only when browserURL and browserWSEndpoint are omitted. */
+  remoteDebuggingHost?: string;
+  /** Used only when browserURL and browserWSEndpoint are omitted. */
+  remoteDebuggingPort?: number;
+  protocolTimeout?: number;
+  slowMo?: number;
+}
+
+export interface RunningChromeInstanceConfig extends RemoteDebuggingEndpointConfig {
+  /**
+   * If false, disables automatic attach when an existing-profile launch fails
+   * because the profile is already running. Defaults to true.
+   */
+  enabled?: boolean;
+  /** Connected runs should usually open a fresh tab. Defaults to false. */
+  reuseExistingPage?: boolean;
+  /** A running Chrome host should not be closed by default. Defaults to false. */
+  closeBrowserOnFinish?: boolean;
+  /** Disconnect the Puppeteer client on finish. Defaults to true. */
+  disconnectOnFinish?: boolean;
+}
+
+export interface ExistingChromeProfileConfig extends BrowserSessionBehavior {
+  mode: 'existing-profile';
+  /** Parent user data directory, not the nested profile folder. */
+  userDataDir: string;
+  /** Profile folder within userDataDir, e.g. Default or Profile 1. */
+  profileDirectory?: string;
+  channel?: ChromeReleaseChannel;
+  executablePath?: string;
+  headless?: false;
+  args?: string[];
+  allowCreatingUserDataDir?: boolean;
+  allowCreatingProfileDirectory?: boolean;
+  dumpio?: boolean;
+
+  /**
+   * Endpoint to try when this profile is already locked/running. If omitted,
+   * the framework still tries http://127.0.0.1:9222 by default. Set
+   * { enabled: false } to disable automatic attach.
+   */
+  runningInstance?: RunningChromeInstanceConfig;
+}
+
+export interface RemoteDebuggingChromeConfig extends BrowserSessionBehavior, RemoteDebuggingEndpointConfig {
+  mode: 'remote-debugging';
+  /** Disconnect the Puppeteer client on finish. Defaults to true. */
+  disconnectOnFinish?: boolean;
+}
+
+export type BrowserRuntimeConfig = ExistingChromeProfileConfig | RemoteDebuggingChromeConfig;
+
+export interface RuntimeConfig {
+  browser: BrowserRuntimeConfig;
+  defaultTimeoutMs?: number;
+  navigationTimeoutMs?: number;
+  interaction?: {
+    typing?: HumanTypingOptions;
+  };
+}
+
+export function expandHome(input: string): string {
+  if (input === '~') return os.homedir();
+  if (input.startsWith(`~${path.sep}`)) return path.join(os.homedir(), input.slice(2));
+  return input;
+}
+
+export function isExistingChromeProfileConfig(config: BrowserRuntimeConfig): config is ExistingChromeProfileConfig {
+  return config.mode === 'existing-profile';
+}
+
+export function isRemoteDebuggingChromeConfig(config: BrowserRuntimeConfig): config is RemoteDebuggingChromeConfig {
+  return config.mode === 'remote-debugging';
+}
+
+function normalizeRunningChromeInstanceConfig(config: RunningChromeInstanceConfig | undefined): RunningChromeInstanceConfig | undefined {
+  if (config === undefined) return undefined;
+
+  return {
+    ...config,
+    enabled: config.enabled ?? true,
+    remoteDebuggingHost: config.remoteDebuggingHost ?? '127.0.0.1',
+    remoteDebuggingPort: config.remoteDebuggingPort ?? 9222,
+    reuseExistingPage: config.reuseExistingPage ?? false,
+    closeBrowserOnFinish: config.closeBrowserOnFinish ?? false,
+    disconnectOnFinish: config.disconnectOnFinish ?? true
+  };
+}
+
+function normalizeExistingProfileConfig(browser: ExistingChromeProfileConfig): ExistingChromeProfileConfig {
+  const runningInstance = normalizeRunningChromeInstanceConfig(browser.runningInstance);
+
+  return {
+    ...browser,
+    userDataDir: path.resolve(expandHome(browser.userDataDir)),
+    channel: browser.channel ?? 'chrome',
+    headless: false,
+    reuseExistingPage: browser.reuseExistingPage ?? true,
+    closeBrowserOnFinish: browser.closeBrowserOnFinish ?? true,
+    allowCreatingUserDataDir: browser.allowCreatingUserDataDir ?? false,
+    allowCreatingProfileDirectory: browser.allowCreatingProfileDirectory ?? false,
+    ...(runningInstance !== undefined ? { runningInstance } : {})
+  };
+}
+
+function normalizeRemoteDebuggingConfig(browser: RemoteDebuggingChromeConfig): RemoteDebuggingChromeConfig {
+  return {
+    ...browser,
+    remoteDebuggingHost: browser.remoteDebuggingHost ?? '127.0.0.1',
+    remoteDebuggingPort: browser.remoteDebuggingPort ?? 9222,
+    reuseExistingPage: browser.reuseExistingPage ?? false,
+    closeBrowserOnFinish: browser.closeBrowserOnFinish ?? false,
+    disconnectOnFinish: browser.disconnectOnFinish ?? true
+  };
+}
+
+export function normalizeRuntimeConfig(config: RuntimeConfig): RuntimeConfig {
+  return {
+    ...config,
+    browser: config.browser.mode === 'existing-profile'
+      ? normalizeExistingProfileConfig(config.browser)
+      : normalizeRemoteDebuggingConfig(config.browser),
+    defaultTimeoutMs: config.defaultTimeoutMs ?? 15_000,
+    navigationTimeoutMs: config.navigationTimeoutMs ?? 30_000,
+    ...(config.interaction !== undefined ? { interaction: config.interaction } : {})
+  };
+}

package/src/browser/index.ts

@@ -0,0 +1,5 @@
+export * from './BrowserFactory.js';
+export * from './BrowserSession.js';
+export * from './PuppeteerLike.js';
+export * from './RuntimeConfig.js';
+export * from './profileValidation.js';

package/src/browser/profileValidation.ts

@@ -0,0 +1,73 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { ConfigError } from '../errors/ConfigError.js';
+import type { ExistingChromeProfileConfig, RemoteDebuggingChromeConfig, RemoteDebuggingEndpointConfig, RunningChromeInstanceConfig } from './RuntimeConfig.js';
+
+export function getProfileDirectoryPath(config: ExistingChromeProfileConfig): string | undefined {
+  return config.profileDirectory === undefined
+    ? undefined
+    : path.join(config.userDataDir, config.profileDirectory);
+}
+
+export function validateExistingProfileConfig(config: ExistingChromeProfileConfig): void {
+  if (config.mode !== 'existing-profile') {
+    throw new ConfigError('validateExistingProfileConfig only accepts existing-profile mode.');
+  }
+
+  if (!config.userDataDir.trim()) {
+    throw new ConfigError('browser.userDataDir is required for existing-profile mode.');
+  }
+
+  if (!config.allowCreatingUserDataDir && !fs.existsSync(config.userDataDir)) {
+    throw new ConfigError('Configured Chrome userDataDir does not exist. Refusing to create a new profile directory.', {
+      details: { userDataDir: config.userDataDir }
+    });
+  }
+
+  if (config.profileDirectory !== undefined) {
+    if (path.isAbsolute(config.profileDirectory) || config.profileDirectory.includes('..')) {
+      throw new ConfigError('browser.profileDirectory must be a Chrome profile folder name such as Default or Profile 1, not a path.');
+    }
+
+    const profilePath = getProfileDirectoryPath(config);
+    if (profilePath !== undefined && !config.allowCreatingProfileDirectory && !fs.existsSync(profilePath)) {
+      throw new ConfigError('Configured Chrome profileDirectory does not exist inside userDataDir. Refusing to create a new Chrome profile.', {
+        details: { profileDirectory: config.profileDirectory, profilePath }
+      });
+    }
+  }
+
+  if (config.runningInstance !== undefined) {
+    validateRunningChromeInstanceConfig(config.runningInstance);
+  }
+}
+
+export function validateRemoteDebuggingConfig(config: RemoteDebuggingChromeConfig): void {
+  if (config.mode !== 'remote-debugging') {
+    throw new ConfigError('validateRemoteDebuggingConfig only accepts remote-debugging mode.');
+  }
+
+  validateRemoteDebuggingEndpointConfig(config);
+}
+
+export function validateRunningChromeInstanceConfig(config: RunningChromeInstanceConfig): void {
+  validateRemoteDebuggingEndpointConfig(config);
+}
+
+function validateRemoteDebuggingEndpointConfig(config: RemoteDebuggingEndpointConfig): void {
+  if (config.browserURL !== undefined && config.browserWSEndpoint !== undefined) {
+    throw new ConfigError('Use either browser.browserURL or browser.browserWSEndpoint, not both.');
+  }
+
+  if (config.browserURL !== undefined && config.browserURL.trim().length === 0) {
+    throw new ConfigError('browser.browserURL cannot be empty.');
+  }
+
+  if (config.browserWSEndpoint !== undefined && config.browserWSEndpoint.trim().length === 0) {
+    throw new ConfigError('browser.browserWSEndpoint cannot be empty.');
+  }
+
+  if (config.remoteDebuggingPort !== undefined && (!Number.isInteger(config.remoteDebuggingPort) || config.remoteDebuggingPort < 1 || config.remoteDebuggingPort > 65_535)) {
+    throw new ConfigError('browser.remoteDebuggingPort must be an integer between 1 and 65535.');
+  }
+}