diff --git a/docs/configuration.md b/docs/configuration.md
index 3542fa9..1c3c2a0 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -254,6 +254,24 @@ playwright: {
 }
 ```
 
+### Browser Context Options
+
+Example:
+
+```javascript
+playwright: {
+  ignoreHTTPSErrors: true,
+  bypassCSP: true,
+  userAgent: 'Mozilla/5.0 (Explorbot)',
+  locale: 'en-GB',
+  colorScheme: 'dark',
+  basicAuth: { username: 'user', password: 'pass' },
+  emulate: { ...devices['iPhone 13'] },
+}
+```
+
+The browser session (cookies, localStorage) is restored automatically when you launch with `--session` — see [`commands.md`](./commands.md#--session).
+
 ## Directory Structure
 
 Default directory layout:
diff --git a/src/explorer.ts b/src/explorer.ts
index 4a82eb0..9583ec3 100644
--- a/src/explorer.ts
+++ b/src/explorer.ts
@@ -8,6 +8,7 @@ import { createTest } from 'codeceptjs/lib/mocha/test';
 import { ActionResult } from './action-result.ts';
 import Action from './action.js';
 import { AIProvider } from './ai/provider.js';
+import type { BrowserContextOptions } from 'playwright';
 import { visuallyAnnotateContainers } from './ai/researcher/coordinates.ts';
 import { RequestStore } from './api/request-store.ts';
 import { XhrCapture } from './api/xhr-capture.ts';
@@ -235,7 +236,17 @@ class Explorer {
     }
     await this.connectOrLaunchBrowser();
     const hasSession = this.options?.session && existsSync(this.options.session);
-    const contextOptions = hasSession ? { storageState: this.options!.session } : undefined;
+    const helperOptions = this.playwrightHelper.options || {};
+    // CodeceptJS skips _createContextPage when sessions/storageState are involved, so we
+    // build contextOptions ourselves. Most keys share a name with Playwright's
+    // BrowserContextOptions and are copied as-is; `emulate` must be flattened, `basicAuth`
+    // renamed to `httpCredentials`, and `storageState` comes from the --session flag.
+    const contextOptions: BrowserContextOptions = {
+      ...helperOptions,
+    };
+    if (helperOptions.emulate) Object.assign(contextOptions, helperOptions.emulate);
+    if (helperOptions.basicAuth) contextOptions.httpCredentials = helperOptions.basicAuth;
+    if (hasSession) contextOptions.storageState = this.options!.session;
     await this.playwrightHelper._createContextPage(contextOptions);
     this.setupXhrCapture();
     if (hasSession) {