browser-commander 0.25.0 → 0.26.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.26.0
+
+### Minor Changes
+
+- 8f9ef1c: Add native Safari and Technology Preview W3C WebDriver control through real/common launchers and CLI, with isolated cookie seeding, setup diagnostics and typed unsupported feature errors.
+
+  Update the transitive shell-quote lock entry to fix GHSA-pqg4-j6r4-53mv and unblock npm audit.
+
 ## 0.25.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-commander",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Universal browser automation library that supports Playwright, Puppeteer, and Selenium with a unified API",
   "main": "src/index.js",
   "bin": {

package/src/browser/browser-sources.json

@@ -766,7 +766,9 @@
       },
       "default": {
         "darwin": ["com.apple.safari"]
-      }
+      },
+      "executables": { "darwin": ["/usr/bin/safaridriver"] },
+      "controlProtocol": "webdriver"
     },
     {
       "id": "safari-technology-preview",
@@ -781,7 +783,13 @@
       },
       "default": {
         "darwin": ["com.apple.safaritechnologypreview"]
-      }
+      },
+      "executables": {
+        "darwin": [
+          "/Applications/Safari Technology Preview.app/Contents/MacOS/safaridriver"
+        ]
+      },
+      "controlProtocol": "webdriver"
     },
     {
       "id": "whale",

package/src/browser/launcher.js

@@ -17,6 +17,8 @@ import { resolveSystemBrowserExecutable } from './system-browser.js';
 import { applyFingerprint } from '../fingerprint/apply.js';
 import { attachDownloads } from '../downloads/attach.js';
 import { launchWebDriver } from './webdriver.js';
+import { launchSafari } from './safari-launch.js';
+import { isSafariChannel } from './safari-support.js';
 import {
   loadStorageState,
   restorePlaywrightStorageState,
@@ -300,6 +302,18 @@ export async function launchBrowserWithDependencies(
   options = {},
   dependencies = {}
 ) {
+  if (isSafariChannel(options.channel ?? options.browser)) {
+    validateLaunchMode({
+      engine: options.engine ?? 'playwright',
+      launch: options.launch ?? 'real',
+      attach: options.attach,
+    });
+    return await launchSafari(options, dependencies);
+  }
+  return await launchNonSafariBrowser(options, dependencies);
+}
+
+async function launchNonSafariBrowser(options, dependencies) {
   const {
     engine = 'playwright',
     launch = 'real',

package/src/browser/real-browser.js

@@ -1,6 +1,8 @@
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { findBrowserSource } from './browser-sources.js';
+import { launchSafari } from './safari-launch.js';
+import { isSafariChannel } from './safari-support.js';
 
 import { startProcess } from '../utilities/subprocess.js';
 import {
@@ -563,6 +565,9 @@ export async function launchAndConnectRealBrowserWithDependencies(
   options = {},
   dependencies = {}
 ) {
+  if (isSafariChannel(options.channel ?? options.browser)) {
+    return launchSafari(options, dependencies);
+  }
   const {
     engine = 'playwright',
     channel = 'chrome',

package/src/browser/safari-launch.js

@@ -0,0 +1,42 @@
+import { launchWebDriver } from './webdriver.js';
+import { findBrowserSource } from './browser-sources.js';
+import { validateSafariOptions } from './safari-support.js';
+import { restoreWebDriverStorageState } from './storage-state.js';
+
+/** Launch installed Safari through its native W3C WebDriver server. */
+export async function launchSafari(options = {}, dependencies = {}) {
+  validateSafariOptions(options);
+  const channel = findBrowserSource(
+    options.channel ?? options.browser ?? 'safari'
+  ).id;
+  const launched = await (dependencies.launchWebDriver ?? launchWebDriver)(
+    {
+      ...options,
+      browser: channel,
+      driverPath: options.driverPath ?? options.executablePath,
+      executablePath: undefined,
+    },
+    dependencies
+  );
+  try {
+    const state = options.storageState;
+    await restoreWebDriverStorageState({
+      page: launched.page,
+      storageState: state,
+      seedCookies: options.seedCookies,
+    });
+  } catch (error) {
+    await launched.close();
+    throw error;
+  }
+  return {
+    ...launched,
+    browser: launched.driver,
+    engine: 'selenium',
+    controlProtocol: 'webdriver',
+    executablePath: launched.driverPath,
+    browserProcess: launched.driverProcess,
+    downloads: null,
+    launch: options.launch ?? 'real',
+  };
+}

package/src/browser/safari-support.js

@@ -0,0 +1,98 @@
+import { findBrowserSource } from './browser-sources.js';
+import { runCommand } from '../utilities/subprocess.js';
+
+/** Whether a channel (including aliases) selects an installed Safari. */
+export function isSafariChannel(channel) {
+  return findBrowserSource(channel)?.family === 'safari';
+}
+
+/** A requested operation unavailable in Safari's classic WebDriver. */
+export class SafariUnsupportedError extends Error {
+  constructor(feature) {
+    super(`${feature} is unsupported on safari`);
+    this.name = 'SafariUnsupportedError';
+    this.code = 'SAFARI_UNSUPPORTED';
+    this.feature = feature;
+  }
+}
+
+/** One-time setup failure with actionable instructions and a settings opener. */
+export class SafariSetupError extends Error {
+  constructor(cause, channel = 'safari') {
+    const driver = findBrowserSource(channel).executables.darwin[0];
+    super(
+      `Safari automation setup required: ${cause.message}. In Safari → Settings → Advanced enable "Show features for web developers", then Develop → "Allow Remote Automation". Run "${driver}" --enable once (an admin password may be required). Call error.openSettings() to open Safari's Advanced settings.`,
+      { cause }
+    );
+    this.name = 'SafariSetupError';
+    this.code = 'SAFARI_SETUP_REQUIRED';
+    this.channel = channel;
+  }
+  openSettings() {
+    return openSafariSettings({ channel: this.channel });
+  }
+}
+
+/** Translate only recognizable authorization failures; preserve other errors. */
+export function safariLaunchError(error, channel) {
+  return /allow\s+remote\s+automation|remote automation.*(?:disabled|enable)|(?:safaridriver|webdriver).*(?:--enable|authoriz|not enabled)|not authorized.*(?:safari|automation)/i.test(
+    error.message
+  )
+    ? new SafariSetupError(error, channel)
+    : error;
+}
+
+/** Open Advanced settings on explicit request; never change authorization. */
+export async function openSafariSettings({
+  channel = 'safari',
+  platform = process.platform,
+  run = runCommand,
+} = {}) {
+  if (platform !== 'darwin') {
+    throw new SafariUnsupportedError('Safari settings outside macOS');
+  }
+  const app =
+    findBrowserSource(channel)?.id === 'safari-technology-preview'
+      ? 'Safari Technology Preview'
+      : 'Safari';
+  return await run('osascript', [
+    '-e',
+    `tell application "${app}" to activate`,
+    '-e',
+    `tell application "${app}" to open location "x-safari-preferences:com.apple.Safari.preferences.Advanced"`,
+  ]);
+}
+
+/** Reject settings Safari cannot apply before touching disk or starting it. */
+export function validateSafariOptions(options) {
+  for (const name of [
+    'headless',
+    'userDataDir',
+    'attach',
+    'migrateFrom',
+    'remoteDebuggingPort',
+    'cdpEndpoint',
+    'wsEndpoint',
+    'fingerprint',
+    'colorScheme',
+    'downloads',
+    'bidi',
+    'preferences',
+    'localState',
+    'defaultBrowserCheck',
+    'firstRun',
+  ]) {
+    if (
+      options[name] !== undefined &&
+      options[name] !== null &&
+      options[name] !== false
+    ) {
+      throw new SafariUnsupportedError(name);
+    }
+  }
+  for (const name of ['args', 'extraArgs', 'restrictions']) {
+    if (options[name]?.length) {
+      throw new SafariUnsupportedError(name);
+    }
+  }
+}

package/src/browser/storage-state.js

@@ -31,27 +31,47 @@ function restoreOriginLocalStorage(origins) {
 }
 
 /** Restore classic WebDriver cookies; origin preload scripts require BiDi. */
-export async function restoreWebDriverStorageState({ page, storageState }) {
-  if (!storageState) {
+export async function restoreWebDriverStorageState({
+  page,
+  storageState,
+  seedCookies = [],
+}) {
+  storageState = await loadStorageState(storageState);
+  if (!storageState && !seedCookies.length) {
     return;
   }
-  const origins = storageState.origins ?? [];
+  const origins = storageState?.origins ?? [];
   if (origins.length) {
-    await page.evaluateOnNewDocument(restoreOriginLocalStorage, origins);
-    await page.evaluate(restoreOriginLocalStorage, origins);
+    if (!page.browserName?.toLowerCase().startsWith('safari')) {
+      await page.evaluateOnNewDocument(restoreOriginLocalStorage, origins);
+      await page.evaluate(restoreOriginLocalStorage, origins);
+    }
   }
   const originalUrl = page.url();
-  const cookies = storageState.cookies ?? [];
+  const cookies = [...(storageState?.cookies ?? []), ...seedCookies];
   try {
     for (const cookie of cookies) {
       const origin = cookie.url
         ? new URL(cookie.url).origin
-        : `${cookie.secure ? 'https' : 'http'}://${cookie.domain.replace(/^\./u, '')}`;
+        : (origins.find(
+            ({ origin }) =>
+              new URL(origin).hostname === cookie.domain?.replace(/^\./u, '')
+          )?.origin ??
+          `${cookie.secure ? 'https' : 'http'}://${cookie.domain.replace(/^\./u, '')}`);
       await page.goto(origin);
       await page.setCookie(cookie);
     }
+    if (page.browserName?.toLowerCase().startsWith('safari')) {
+      for (const { origin } of origins) {
+        await page.goto(origin);
+        await page.evaluate(restoreOriginLocalStorage, origins);
+      }
+    }
   } finally {
-    if (cookies.length) {
+    if (
+      cookies.length ||
+      (origins.length && page.browserName?.toLowerCase().startsWith('safari'))
+    ) {
       await page.goto(originalUrl);
     }
   }

package/src/browser/webdriver.js

@@ -40,6 +40,13 @@ import {
 } from './profile-directory.js';
 import { buildRealBrowserArgs } from './real-browser.js';
 import { resolveRestrictions } from './restrictions.js';
+import { findBrowserSource } from './browser-sources.js';
+import {
+  isSafariChannel,
+  SafariUnsupportedError,
+  safariLaunchError,
+  validateSafariOptions,
+} from './safari-support.js';
 
 const require = createRequire(import.meta.url);
 const accessAsync = promisify(access);
@@ -76,6 +83,8 @@ export const CHROMEDRIVER_DEFAULT_SWITCHES = Object.freeze([
 const DRIVERS = Object.freeze({
   chrome: { name: 'chromedriver', builder: 'chrome' },
   firefox: { name: 'geckodriver', builder: 'firefox' },
+  safari: { name: 'safaridriver', builder: 'safari' },
+  'safari-technology-preview': { name: 'safaridriver', builder: 'safari' },
 });
 
 /**
@@ -102,7 +111,7 @@ export function loadSelenium(subpath) {
 function assertBrowser(browser) {
   if (!DRIVERS[browser]) {
     throw new Error(
-      `Unsupported WebDriver browser: ${browser}. Expected 'chrome' or 'firefox'`
+      `Unsupported WebDriver browser: ${browser}. Expected 'chrome', 'firefox' or 'safari'`
     );
   }
   return DRIVERS[browser];
@@ -182,6 +191,20 @@ export async function resolveWebDriverExecutable({
   managerPath,
 } = {}) {
   const { name } = assertBrowser(browser);
+  if (isSafariChannel(browser)) {
+    if (platform !== 'darwin') {
+      throw new SafariUnsupportedError('Safari launch outside macOS');
+    }
+    const file = driverPath ?? findBrowserSource(browser).executables.darwin[0];
+    if (!(await isExecutable(file, checkAccess))) {
+      throw new Error(`Safari WebDriver executable is not accessible: ${file}`);
+    }
+    return {
+      driverPath: file,
+      browserPath: null,
+      source: 'bundled-safaridriver',
+    };
+  }
   if (driverPath) {
     if (!(await isExecutable(driverPath, checkAccess))) {
       throw new Error(`WebDriver executable is not accessible: ${driverPath}`);
@@ -237,6 +260,9 @@ export async function resolveWebDriverExecutable({
  * @returns {string[]}
  */
 export function buildDriverServerArgs(browser, port) {
+  if (isSafariChannel(browser)) {
+    return ['--port', String(port)];
+  }
   if (assertBrowser(browser).name === 'geckodriver') {
     return ['--port', String(port), '--host', LOOPBACK_HOST];
   }
@@ -306,6 +332,16 @@ export function buildBrowserOptions({
 }) {
   let options;
   let browserArgs;
+  if (isSafariChannel(browser)) {
+    options = new selenium.webdriver.Capabilities();
+    options.set(
+      'browserName',
+      browser === 'safari-technology-preview'
+        ? 'Safari Technology Preview'
+        : 'safari'
+    );
+    return { options, args: [] };
+  }
   if (browser === 'chrome') {
     options = new selenium.chrome.Options();
     if (debuggerAddress) {
@@ -387,7 +423,9 @@ function buildSession({ selenium, serverUrl, browser, options }) {
   const builder = new selenium.webdriver.Builder()
     .usingServer(serverUrl)
     .forBrowser(DRIVERS[browser].builder);
-  if (browser === 'chrome') {
+  if (isSafariChannel(browser)) {
+    builder.withCapabilities(options);
+  } else if (browser === 'chrome') {
     builder.setChromeOptions(options);
   } else {
     builder.setFirefoxOptions(options);
@@ -462,6 +500,10 @@ export async function launchWebDriver(options = {}, dependencies = {}) {
     debuggerAddress,
   } = options;
   assertBrowser(browser);
+  const safari = isSafariChannel(browser);
+  if (safari) {
+    validateSafariOptions(options);
+  }
   if (debuggerAddress && browser !== 'chrome') {
     throw new Error('debuggerAddress is only supported by Chrome WebDriver');
   }
@@ -476,23 +518,17 @@ export async function launchWebDriver(options = {}, dependencies = {}) {
   const startProcess = dependencies.startProcess ?? defaultStartProcess;
 
   const resolved = await resolveWebDriverExecutable({
+    ...dependencies,
     browser,
     driverPath: requestedDriverPath,
     executablePath,
-    runCommand: dependencies.runCommand ?? defaultRunCommand,
-    ...(dependencies.checkAccess
-      ? { checkAccess: dependencies.checkAccess }
-      : {}),
-    ...(dependencies.environment
-      ? { environment: dependencies.environment }
-      : {}),
-    ...(dependencies.platform ? { platform: dependencies.platform } : {}),
   });
 
-  const temporaryProfile = !debuggerAddress && !requestedUserDataDir;
-  const userDataDir = debuggerAddress
-    ? undefined
-    : await resolveProfile(browser, requestedUserDataDir);
+  const temporaryProfile = !safari && !debuggerAddress && !requestedUserDataDir;
+  const userDataDir =
+    safari || debuggerAddress
+      ? undefined
+      : await resolveProfile(browser, requestedUserDataDir);
   const childEnv = driverEnvironment(restrictions, env);
 
   let driverProcess;
@@ -506,9 +542,11 @@ export async function launchWebDriver(options = {}, dependencies = {}) {
       { env: childEnv, forwardOutput: verbose }
     );
     let output = '';
-    driverProcess.stderr?.on('data', (chunk) => {
-      output = `${output}${chunk}`.slice(-4000);
-    });
+    for (const stream of [driverProcess.stdout, driverProcess.stderr]) {
+      stream?.on('data', (chunk) => {
+        output = `${output}${chunk}`.slice(-4000);
+      });
+    }
     await waitForDriverReady(serverUrl, {
       fetchImplementation: dependencies.fetch ?? fetch,
       timeout: startupTimeout,
@@ -536,7 +574,14 @@ export async function launchWebDriver(options = {}, dependencies = {}) {
       browser,
       options: built.options,
     });
-    const page = await createWebDriverPage(driver, dependencies.pageOptions);
+    // Fresh Safari sessions can report an empty URL until first navigation.
+    if (safari) {
+      await driver.get('about:blank');
+    }
+    const page = await createWebDriverPage(driver, {
+      ...dependencies.pageOptions,
+      ...(safari ? { browserName: 'safari' } : {}),
+    });
 
     const close = memoize(() =>
       teardown({ page, driver, driverProcess, temporaryProfile, userDataDir })
@@ -558,7 +603,7 @@ export async function launchWebDriver(options = {}, dependencies = {}) {
     };
   } catch (error) {
     await teardown({ driver, driverProcess, temporaryProfile, userDataDir });
-    throw error;
+    throw safari ? safariLaunchError(error, browser) : error;
   }
 }
 

package/src/cli/sessions.js

@@ -12,6 +12,9 @@ export const BROWSER_CHANNELS = Object.freeze({
   msedge: 'msedge',
   brave: 'brave',
   chromium: 'chromium',
+  safari: 'safari',
+  'safari-technology-preview': 'safari-technology-preview',
+  'safari-tp': 'safari-technology-preview',
 });
 
 const ENGINES = Object.freeze(['playwright', 'puppeteer', 'selenium']);
@@ -40,6 +43,7 @@ const LAUNCH_PASSTHROUGH = Object.freeze([
   'firstRun',
   'driverPath',
   'bidi',
+  'seedCookies',
 ]);
 
 /** Validate an engine name, defaulting to Playwright. */
@@ -118,6 +122,7 @@ export function buildLaunchOptions(params = {}) {
  * persistent context whose `browser()` is null. Puppeteer returns a Browser.
  */
 export function sessionFromLaunch(engine, launched) {
+  engine = launched.engine ?? engine;
   const playwright = engine === 'playwright';
   const handle = launched.browser;
   return {

package/src/core/webdriver-page.js

@@ -32,6 +32,7 @@ import {
   toWebDriverKey,
 } from './webdriver-conversions.js';
 import { createWebDriverEventBridge } from './webdriver-events.js';
+import { SafariUnsupportedError } from '../browser/safari-support.js';
 
 const require = createRequire(import.meta.url);
 
@@ -99,6 +100,7 @@ export class WebDriverPage extends EventEmitter {
     }
     this.driver = driver;
     this.engine = 'selenium';
+    this.browserName = options.browserName;
     this.isWebDriverPage = true;
     this._url = 'about:blank';
     this._closed = false;
@@ -358,6 +360,57 @@ export class WebDriverPage extends EventEmitter {
     return result;
   }
 
+  /** Execute an asynchronous function using W3C execute/async. */
+  async evaluateAsync(pageFunction, ...args) {
+    const script = buildEvaluateScript(pageFunction);
+    const result = await this.driver.executeAsyncScript(
+      `const done = arguments[arguments.length - 1]; const args = Array.from(arguments).slice(0, -1); Promise.resolve((function(){${script}}).apply(null, args)).then(value => done({value}), error => done({error: String(error)}));`,
+      ...args
+    );
+    if (result.error) {
+      throw new Error(result.error);
+    }
+    const [value, href] = result.value;
+    this._url = href;
+    return value;
+  }
+
+  /** Fail before subscribing or creating files for unsupported Safari features. */
+  requireFeature(feature) {
+    if (this.browserName?.toLowerCase().startsWith('safari')) {
+      throw new SafariUnsupportedError(feature);
+    }
+  }
+
+  setRequestInterception() {
+    return Promise.resolve().then(() => {
+      this.requireFeature('network interception');
+      throw new Error('Network interception requires a supporting engine');
+    });
+  }
+
+  route() {
+    return this.setRequestInterception();
+  }
+
+  /** W3C window handles include both tabs and windows. */
+  async windows() {
+    return await this.driver.getAllWindowHandles();
+  }
+
+  async newWindow(type = 'tab') {
+    await this.driver.switchTo().newWindow(type);
+    this._contextId = await this.driver.getWindowHandle();
+    await this.syncUrl();
+    return this._contextId;
+  }
+
+  async switchToWindow(handle) {
+    await this.driver.switchTo().window(handle);
+    this._contextId = handle;
+    await this.syncUrl();
+  }
+
   /**
    * Puppeteer's evaluateOnNewDocument, as a BiDi preload script.
    *
@@ -626,6 +679,7 @@ export class WebDriverPage extends EventEmitter {
    * @returns {Promise<Buffer>}
    */
   async pdf(options = {}) {
+    this.requireFeature('PDF');
     const buffer = Buffer.from(
       await this.driver.printPage(toPrintOptions(options)),
       'base64'
@@ -709,6 +763,14 @@ export class WebDriverPage extends EventEmitter {
  * @returns {Promise<WebDriverPage>}
  */
 export async function createWebDriverPage(driver, options = {}) {
+  if (!options.browserName) {
+    const capabilities = await driver.getCapabilities();
+    options = {
+      ...options,
+      browserName:
+        capabilities?.get?.('browserName') ?? capabilities?.browserName,
+    };
+  }
   const page = new WebDriverPage(driver, options);
   await page.contextId();
   await page.syncUrl();

package/src/exports.js

@@ -322,3 +322,9 @@ export {
   redactUrl,
   redactValue,
 } from './traces/redaction.js';
+
+export {
+  SafariSetupError,
+  SafariUnsupportedError,
+  openSafariSettings,
+} from './browser/safari-support.js';

package/src/traces/recorder.js

@@ -93,6 +93,7 @@ function validateLinksOptions(links) {
  * @returns {Promise<Object>} The running trace
  */
 export async function startTrace(options = {}) {
+  requireTraceSupport(options);
   const {
     commander,
     page = commander?.page,
@@ -468,3 +469,7 @@ export async function startTrace(options = {}) {
     },
   };
 }
+
+function requireTraceSupport(options) {
+  (options.page ?? options.commander?.page)?.requireFeature?.('tracing');
+}

package/tests/e2e/safari.e2e.test.js

@@ -0,0 +1,104 @@
+// feature-parity: safari.control@native-typed
+import { it } from 'node:test';
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import {
+  launchRealBrowser,
+  SafariUnsupportedError,
+  makeBrowserCommander,
+} from '../../src/index.js';
+import { createDispatcher } from '../../src/cli/dispatcher.js';
+
+it(
+  'Safari drives a local page in an isolated automation session',
+  {
+    skip:
+      process.platform !== 'darwin' || process.env.RUN_SAFARI_E2E !== 'true',
+    timeout: 60_000,
+  },
+  async () => {
+    const server = createServer((_request, response) => {
+      response.writeHead(200, { 'content-type': 'text/html' });
+      response.end(
+        '<title>Safari smoke</title><input id="name"><button id="go" onclick="document.querySelector(\'#out\').textContent=document.querySelector(\'#name\').value">Go</button><p id="out"></p>'
+      );
+    });
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const url = `http://127.0.0.1:${server.address().port}/`;
+    let session;
+    let commander;
+    const cli = createDispatcher();
+    const phase = (message) =>
+      console.info(`[Safari smoke] ${new Date().toISOString()} ${message}`);
+    try {
+      phase('launch seeded session');
+      session = await launchRealBrowser({
+        channel: 'safari',
+        startupTimeout: 20_000,
+        seedCookies: [{ name: 'seed', value: 'yes', url, httpOnly: true }],
+      });
+      const { page, driver } = session;
+      phase('exercise page commands');
+      commander = makeBrowserCommander({ page });
+      await page.goto(url);
+      assert.equal(commander.engine, 'selenium');
+      await commander.fill({ selector: '#name', text: 'Safari' });
+      await commander.click({ selector: '#go' });
+      assert.equal(
+        await page.evaluate(() => document.querySelector('#out').textContent),
+        'Safari'
+      );
+      assert.equal(await page.evaluateAsync(async (value) => value + 1, 4), 5);
+      assert.ok((await page.screenshot()).length > 100);
+      assert.equal((await driver.manage().getCookie('seed')).value, 'yes');
+      phase('exercise windows and tabs');
+      const initial = await driver.getWindowHandle();
+      for (const type of ['tab', 'window']) {
+        const handle = await page.newWindow(type);
+        assert.ok((await page.windows()).includes(handle));
+        await page.goto(url);
+        await driver.close();
+        await page.switchToWindow(initial);
+      }
+      await assert.rejects(() => page.pdf(), SafariUnsupportedError);
+      await assert.rejects(
+        () => page.setRequestInterception(true),
+        SafariUnsupportedError
+      );
+      phase('close seeded session');
+      await session.close();
+      phase('launch fresh session');
+      session = await launchRealBrowser({ channel: 'safari' });
+      await session.page.goto(url);
+      assert.equal(
+        (await session.driver.manage().getCookies()).some(
+          (cookie) => cookie.name === 'seed'
+        ),
+        false
+      );
+      phase('close fresh session');
+      await session.close();
+      phase('launch CLI session');
+      await cli.dispatch('session.launch', {
+        browser: 'safari',
+        engine: 'selenium',
+      });
+      phase('exercise CLI commands');
+      await cli.dispatch('page.goto', { url });
+      assert.equal(
+        (await cli.dispatch('page.eval', { expression: 'document.title' }))
+          .value,
+        'Safari smoke'
+      );
+    } finally {
+      phase('close CLI session');
+      await cli.close();
+      phase('destroy commander');
+      await commander?.destroy();
+      phase('close remaining session and server');
+      await session?.close();
+      await new Promise((resolve) => server.close(resolve));
+      phase('cleanup complete');
+    }
+  }
+);

package/tests/unit/browser/real-browser.test.js

@@ -204,7 +204,7 @@ describe('launchAndConnectRealBrowser', () => {
   });
 
   it('rejects non-CDP catalogue browsers before resolving or spawning them', async () => {
-    for (const channel of ['firefox', 'librewolf', 'safari', 'duckduckgo']) {
+    for (const channel of ['firefox', 'librewolf', 'duckduckgo']) {
       await assert.rejects(
         launchAndConnectRealBrowserWithDependencies(
           { channel },

package/tests/unit/browser/safari.test.js

@@ -0,0 +1,192 @@
+// feature-parity: safari.control@native-typed safari.setup@native-typed safari.seed@native-typed safari.unsupported@native-typed
+import { it } from 'node:test';
+import assert from 'node:assert/strict';
+import vm from 'node:vm';
+import { findBrowserSource } from '../../../src/browser/browser-sources.js';
+import {
+  buildDriverServerArgs,
+  resolveWebDriverExecutable,
+} from '../../../src/browser/webdriver.js';
+import {
+  WebDriverPage,
+  createWebDriverPage,
+} from '../../../src/core/webdriver-page.js';
+import { createMockDriver } from '../../helpers/webdriver-mocks.js';
+import { launchBrowserWithDependencies } from '../../../src/browser/launcher.js';
+import { launchAndConnectRealBrowserWithDependencies } from '../../../src/browser/real-browser.js';
+import {
+  SafariSetupError,
+  SafariUnsupportedError,
+  safariLaunchError,
+  openSafariSettings,
+} from '../../../src/browser/safari-support.js';
+import { startTrace } from '../../../src/traces/recorder.js';
+import {
+  buildLaunchOptions,
+  sessionFromLaunch,
+} from '../../../src/cli/sessions.js';
+
+it('catalogue exposes both Safari WebDriver executables', () => {
+  for (const channel of ['safari', 'safari-tp']) {
+    const source = findBrowserSource(channel);
+    assert.equal(source.controlProtocol, 'webdriver');
+    assert.ok(source.executables.darwin[0].endsWith('/safaridriver'));
+  }
+});
+
+it('Safari channels route real/common launch and CLI to Selenium and seed cookies', async () => {
+  for (const launch of [
+    launchBrowserWithDependencies,
+    launchAndConnectRealBrowserWithDependencies,
+  ]) {
+    const driver = createMockDriver({
+      capabilities: { browserName: 'safari' },
+    });
+    const page = await createWebDriverPage(driver);
+    let calls = 0;
+    const launched = await launch(
+      {
+        channel: 'safari-tp',
+        seedCookies: [
+          {
+            name: 'auth',
+            value: 'yes',
+            domain: '.example.test',
+            secure: true,
+            httpOnly: true,
+            expires: -1,
+          },
+        ],
+      },
+      {
+        launchWebDriver: async (options) => {
+          calls++;
+          assert.equal(options.browser, 'safari-technology-preview');
+          return {
+            driver,
+            page,
+            close: () => driver.quit(),
+            driverPath: '/Safari TP/safaridriver',
+          };
+        },
+        resolveExecutable: () => assert.fail('Safari must bypass CDP'),
+        resolveSystem: () =>
+          assert.fail('Safari must bypass Chromium resolution'),
+      }
+    );
+    assert.equal(calls, 1);
+    assert.equal(launched.engine, 'selenium');
+    assert.equal(launched.browser, driver);
+    assert.equal(driver.state.url, 'about:blank');
+    assert.ok(
+      driver.calls.some(
+        ([method, url]) => method === 'get' && url === 'https://example.test'
+      )
+    );
+    assert.ok(
+      driver.calls.some(
+        ([method, cookie]) => method === 'addCookie' && cookie.httpOnly
+      )
+    );
+    assert.equal(sessionFromLaunch('playwright', launched).engine, 'selenium');
+    await launched.close();
+  }
+  assert.equal(buildLaunchOptions({ browser: 'safari' }).channel, 'safari');
+});
+
+it('Safari fails unsupported launch options before starting and page features before writes', async () => {
+  for (const options of [
+    { headless: true },
+    { userDataDir: '/tmp/profile' },
+    { args: ['--flag'] },
+    { fingerprint: {} },
+    { downloads: true },
+  ]) {
+    await assert.rejects(
+      () =>
+        launchBrowserWithDependencies(
+          { channel: 'safari', ...options },
+          { launchWebDriver: () => assert.fail('must reject before starting') }
+        ),
+      SafariUnsupportedError
+    );
+  }
+  const page = new WebDriverPage(createMockDriver(), { browserName: 'safari' });
+  await assert.rejects(
+    () => page.pdf(),
+    (error) =>
+      error instanceof SafariUnsupportedError && error.feature === 'PDF'
+  );
+  await assert.rejects(
+    () => page.setRequestInterception(true),
+    SafariUnsupportedError
+  );
+  await assert.rejects(
+    () => startTrace({ page, output: '/must-not-create' }),
+    SafariUnsupportedError
+  );
+});
+
+it('Safari async evaluation uses execute/async and returns rejected promises as errors', async () => {
+  const driver = createMockDriver();
+  let mode = 'success';
+  driver.executeAsyncScript = (source, ...args) =>
+    new Promise((resolve) => {
+      vm.runInNewContext(`(function(){${source}}).apply(null, args)`, {
+        args: [...args, resolve],
+        location: { href: 'https://example.test' },
+        setTimeout,
+        mode,
+      });
+    });
+  const page = new WebDriverPage(driver, { browserName: 'safari' });
+  assert.equal(await page.evaluateAsync(async (value) => value + 1, 4), 5);
+  mode = 'error';
+  await assert.rejects(
+    () =>
+      page.evaluateAsync(async () => {
+        throw new Error('rejected');
+      }),
+    /rejected/
+  );
+});
+
+it('setup errors identify both authorization steps and offer an explicit settings opener', async () => {
+  for (const message of [
+    "You must enable the 'Allow Remote Automation' option",
+    'safaridriver requires --enable authorization',
+  ]) {
+    const error = safariLaunchError(
+      new Error(message),
+      'safari-technology-preview'
+    );
+    assert.ok(error instanceof SafariSetupError);
+    assert.match(error.message, /Show features for web developers/);
+    assert.match(error.message, /admin password/);
+    assert.match(error.message, /Safari Technology Preview.app/);
+    assert.equal(typeof error.openSettings, 'function');
+  }
+  const other = new Error('port already in use');
+  assert.equal(safariLaunchError(other, 'safari'), other);
+  let argv;
+  await openSafariSettings({
+    channel: 'safari-tp',
+    platform: 'darwin',
+    run: async (file, args) => {
+      assert.equal(file, 'osascript');
+      argv = args;
+    },
+  });
+  assert.ok(argv.some((arg) => arg.includes('Safari Technology Preview')));
+});
+
+it('Safari uses its bundled driver and the native --port argument', async () => {
+  assert.deepEqual(buildDriverServerArgs('safari', 12345), ['--port', '12345']);
+  const result = await resolveWebDriverExecutable({
+    browser: 'safari',
+    platform: 'darwin',
+    checkAccess: async () => {},
+    runCommand: () => assert.fail('Safari needs no Selenium Manager'),
+  });
+  assert.equal(result.driverPath, '/usr/bin/safaridriver');
+});

package/tests/unit/browser/webdriver.test.js

@@ -92,7 +92,7 @@ function createMockSelenium(driver = createMockDriver()) {
     record,
     driver,
     selenium: {
-      webdriver: { Builder },
+      webdriver: { Builder, Capabilities: Options },
       chrome: {
         Options: class extends Options {
           constructor() {
@@ -265,8 +265,8 @@ describe('resolveWebDriverExecutable', () => {
 
   it('rejects browsers it has no driver for', async () => {
     await assert.rejects(
-      () => resolveWebDriverExecutable({ browser: 'safari' }),
-      /Unsupported WebDriver browser: safari/
+      () => resolveWebDriverExecutable({ browser: 'unknown-browser' }),
+      /Unsupported WebDriver browser: unknown-browser/
     );
   });
 });
@@ -446,6 +446,51 @@ describe('launchWebDriver', () => {
   });
 });
 
+function safariDependencies() {
+  return launchDependencies({
+    platform: 'darwin',
+    checkAccess: async () => {},
+  });
+}
+
+describe('Safari driver lifecycle', () => {
+  it('uses no disk profile or Chromium/BiDi capabilities and closes idempotently', async () => {
+    const { dependencies, started, mock } = safariDependencies();
+    mock.driver.state.url = '';
+    const result = await launchWebDriver(
+      { browser: 'safari-technology-preview' },
+      dependencies
+    );
+    assert.equal(result.page.url(), 'about:blank');
+    assert.equal(result.userDataDir, undefined);
+    assert.equal(result.temporaryProfile, false);
+    assert.equal(
+      mock.record.builders[0].capabilities.capabilities.browserName,
+      'Safari Technology Preview'
+    );
+    assert.deepEqual(started[0].args, ['--port', '41001']);
+    assert.match(started[0].file, /Safari Technology Preview.app/);
+    await Promise.all([result.close(), result.close()]);
+    assert.equal(
+      mock.driver.calls.filter(([name]) => name === 'quit').length,
+      1
+    );
+    assert.ok(started[0].child.killed);
+  });
+
+  it('cleans up the driver if Safari authorization fails', async () => {
+    const { dependencies, started, mock } = safariDependencies();
+    mock.selenium.webdriver.Builder.prototype.build = () => {
+      throw new Error("You must enable the 'Allow Remote Automation' option");
+    };
+    await assert.rejects(
+      () => launchWebDriver({ browser: 'safari' }, dependencies),
+      (error) => error.code === 'SAFARI_SETUP_REQUIRED'
+    );
+    assert.ok(started[0].child.killed);
+  });
+});
+
 describe('connectWebDriver', () => {
   it('opens a session on a running server with the given capabilities', async () => {
     const mock = createMockSelenium();

package/tests/unit/cli/dispatcher.test.js

@@ -280,7 +280,7 @@ describe('dispatcher: high-level methods', () => {
       { code: -32602 }
     );
     await assert.rejects(
-      dispatcher.dispatch('session.launch', { browser: 'safari' }),
+      dispatcher.dispatch('session.launch', { browser: 'unknown-browser' }),
       { code: -32602 }
     );
     await assert.rejects(dispatcher.dispatch('page.goto', { url: 'x' }), {