@pablovitasso/szkrabok 1.0.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,114 @@
+# Szkrabok
+
+MCP server supplementing [microsoft/playwright-mcp](https://github.com/microsoft/playwright-mcp) with persistent sessions, stealth mode, and scripted automation.
+
+**Core Enhancements:**
+
+* **Named Sessions:** Persistent cookies, localStorage, and Chromium profiles.
+* **Stealth:** Integrated `playwright-extra` + stealth plugin and anti-bot CDP patches.
+* **Deterministic Ports:** Fixed CDP ports per session for `connectOverCDP()`.
+
+---
+
+## Tools & Capabilities
+
+| Tool | Description |
+| --- | --- |
+| `session_manage` | Manage sessions: `open` (launch/resume), `close`, `list`, `delete`, `endpoint` (CDP/WS URLs). |
+| `workflow.scrape` | Auto-scrape current page into LLM-ready text (headings, content, links, tables). Optional CSS selectors to target specific areas. |
+| `browser_run` | Execute Playwright JS on session page: pass `code` (inline snippet) or `path` (named export from `.mjs` file). |
+| `browser.run_test` | Run `.spec.js` tests via CDP (requires `scaffold.init`). |
+| `scaffold.init` | Bootstrap project with `playwright.config.js` and templates. |
+
+---
+
+## Setup
+
+**1. Install**
+
+| Use Case | Command |
+| --- | --- |
+| **Scaffolding a new project** | `npx @pablovitasso/szkrabok init` |
+| **Claude Code** | `claude mcp add szkrabok -- npx -y @pablovitasso/szkrabok` |
+| **Claude Desktop** | See config snippet below |
+| **Development (from source)** | `npm ci && claude mcp add szkrabok node /path/to/szkrabok/src/index.js` |
+
+Claude Desktop — add to `claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "szkrabok": {
+      "command": "npx",
+      "args": ["-y", "@pablovitasso/szkrabok"]
+    }
+  }
+}
+```
+
+> **Browser not installed?** Run `npx @pablovitasso/szkrabok --setup` once in your terminal, then restart Claude.
+> Set `CI=true` or `SZKRABOK_SKIP_BROWSER_INSTALL=1` to suppress the auto-install in CI / Docker.
+
+**2. Configure**
+
+Optionally create `szkrabok.config.local.toml` to set a custom browser binary or user agent:
+
+```toml
+[default]
+executablePath = "/path/to/your/chrome"
+overrideUserAgent = true
+userAgent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/145.0.0.0 Safari/537.36"
+log_level = "debug"
+```
+
+---
+
+## Usage
+
+### Claude Code (LLM)
+
+```
+session_manage { "action": "open", "sessionName": "my-session", "url": "https://example.com" }
+workflow.scrape { "sessionName": "my-session" }
+session_manage { "action": "close", "sessionName": "my-session" }
+```
+
+Bootstrap a new project, then run tests:
+
+```
+scaffold.init { "dir": "/path/to/project", "preset": "full" }
+session_manage { "action": "open", "sessionName": "my-session" }
+browser.run_test { "sessionName": "my-session", "files": ["automation/example.spec.js"] }
+```
+
+### Bebok (CLI)
+
+`bebok` is the human/shell interface — calls the same handlers as MCP tools:
+
+```bash
+bebok open <profile>              # Launch browser, print CDP endpoint, stay alive
+bebok session list                # Show all sessions (active + stored)
+bebok session inspect <id>        # Dump cookie/localStorage counts
+bebok session delete <id>         # Delete a session
+bebok session cleanup --days 30   # Delete sessions unused for N days
+bebok endpoint <sessionName>      # Print CDP + WS endpoints
+```
+
+---
+
+## Project Structure
+
+* **`@pablovitasso/szkrabok/runtime`** (`packages/runtime/`): Browser bootstrap, stealth, session pool, MCP client (`mcpConnect`, `spawnClient`, codegen).
+* **Config**: `szkrabok.config.toml` (defaults) deep-merged with `szkrabok.config.local.toml` (machine-specific, gitignored).
+* **Release**: `npm run release:patch` bumps version, then `npm publish --access public`.
+
+---
+
+## Documentation
+
+| Doc | Contents |
+|-----|----------|
+| [docs/architecture.md](./docs/architecture.md) | Layer map, file layout, session lifecycle, invariants |
+| [docs/development.md](./docs/development.md) | Adding tools, CLI design, release workflow |
+| [docs/testing.md](./docs/testing.md) | Test categories, how to run, writing specs |
+| [docs/mcp-client-library.md](./docs/mcp-client-library.md) | MCP client library and codegen |
+| [docs/scaffold-init.md](./docs/scaffold-init.md) | scaffold.init presets and template structure |

package/package.json

@@ -0,0 +1,124 @@
+{
+  "name": "@pablovitasso/szkrabok",
+  "version": "1.0.10",
+  "description": "Production-grade MCP browser automation layer with persistent sessions and stealth capabilities",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./runtime": "./packages/runtime/index.js"
+  },
+  "imports": {
+    "#runtime": "./packages/runtime/index.js"
+  },
+  "files": [
+    "src",
+    "packages/runtime",
+    "scripts",
+    "README.md"
+  ],
+  "bin": {
+    "szkrabok": "./src/index.js",
+    "bebok": "./src/cli.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "workspaces": [
+    "packages/runtime"
+  ],
+  "scripts": {
+    "start": "node src/index.js",
+    "dev": "node --watch src/index.js",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "prettier": "prettier --write \"{src,tests}/**/*.{js,json,md}\" \"*.{js,json,md}\"",
+    "format": "npm run prettier",
+    "format:check": "prettier --check \"{src,tests}/**/*.{js,json,md}\" \"*.{js,json,md}\"",
+    "codegen:mcp": "node packages/runtime/mcp-client/codegen/generate-mcp-tools.mjs",
+    "prepack": "git describe --exact-match --tags HEAD 2>/dev/null || (echo 'ERROR: HEAD is not tagged. Run npm run release:patch or release:minor first.' && exit 1)",
+    "pack:runtime": "npm pack --workspace=packages/runtime --pack-destination=dist/",
+    "pack": "mkdir -p dist && npm run pack:runtime",
+    "release:patch": "npm version patch --workspaces --include-workspace-root --ignore-scripts && npm run pack && node scripts/release-reminder.js",
+    "release:minor": "npm version minor --workspaces --include-workspace-root --ignore-scripts && npm run pack && node scripts/release-reminder.js",
+    "release:publish": "node scripts/release-publish.js",
+    "test": "npm run test:self && npm run test:auto",
+    "test:node": "node --test tests/node/*.test.js",
+    "test:runtime:unit": "node --test tests/node/runtime/unit.test.js",
+    "test:runtime:integration": "node --test tests/node/runtime/integration.test.js",
+    "test:contracts": "node --test tests/node/contracts.test.js",
+    "test:playwright": "playwright test --project=integration",
+    "prepare": "node scripts/setup.js",
+    "postinstall": "node scripts/patch-playwright.js && node scripts/postinstall.js",
+    "test:self": "playwright test --project=integration && node --test tests/node/*.test.js",
+    "test:auto": "PLAYWRIGHT_PROJECT=e2e playwright test --project=e2e"
+  },
+  "keywords": [
+    "mcp",
+    "playwright",
+    "browser-automation",
+    "stealth",
+    "session-management",
+    "llm-tools",
+    "web-scraping",
+    "model-context-protocol"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PabloVitasso/szkrabok.git"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "dotenv": "^17.3.1",
+    "playwright": "^1.49.1",
+    "playwright-core": "^1.58.2",
+    "playwright-extra": "^4.3.6",
+    "puppeteer": "^24.34.0",
+    "puppeteer-extra-plugin-stealth": "^2.11.2",
+    "smol-toml": "^1.6.0",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.17.0",
+    "@types/puppeteer": "^5.4.7",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "eslint": "^9.17.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-node": "^11.1.0",
+    "globals": "^15.13.0",
+    "prettier": "^3.4.2",
+    "puppeteer-extra": "^3.3.6"
+  },
+  "eslintConfig": {
+    "env": {
+      "node": true,
+      "es2022": true
+    },
+    "extends": [
+      "eslint:recommended",
+      "prettier"
+    ],
+    "parserOptions": {
+      "ecmaVersion": "latest",
+      "sourceType": "module"
+    },
+    "rules": {
+      "no-unused-vars": [
+        "warn",
+        {
+          "argsIgnorePattern": "^_",
+          "varsIgnorePattern": "^_"
+        }
+      ],
+      "no-console": "off",
+      "prefer-const": "error",
+      "no-var": "error",
+      "object-shorthand": "error",
+      "prefer-template": "error",
+      "prefer-arrow-callback": "error"
+    }
+  }
+}

package/packages/runtime/config.js

@@ -0,0 +1,173 @@
+import { homedir } from 'os';
+import { join, resolve, dirname } from 'path';
+import { readdirSync, existsSync, readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { parse } from 'smol-toml';
+
+// TOML config resolution:
+// 1. SZKRABOK_CONFIG env var (absolute path)
+// 2. CWD/szkrabok.config.toml + CWD/szkrabok.config.local.toml
+// 3. package dir / szkrabok.config.toml (fallback for monorepo root)
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = resolve(__dirname, '..', '..');
+
+const isPlainObject = v => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+const deepMerge = (base, override) => {
+  const result = { ...base };
+  for (const key of Object.keys(override)) {
+    result[key] =
+      isPlainObject(base[key]) && isPlainObject(override[key])
+        ? deepMerge(base[key], override[key])
+        : override[key];
+  }
+  return result;
+};
+
+const loadToml = () => {
+  const configEnv = process.env.SZKRABOK_CONFIG;
+  if (configEnv && existsSync(configEnv)) {
+    return parse(readFileSync(configEnv, 'utf8'));
+  }
+
+  const cwdBase = join(process.cwd(), 'szkrabok.config.toml');
+  const cwdLocal = join(process.cwd(), 'szkrabok.config.local.toml');
+  const pkgBase = join(PACKAGE_ROOT, 'szkrabok.config.toml');
+  const pkgLocal = join(PACKAGE_ROOT, 'szkrabok.config.local.toml');
+
+  const basePath = existsSync(cwdBase) ? cwdBase : existsSync(pkgBase) ? pkgBase : null;
+  const localPath = existsSync(cwdLocal) ? cwdLocal : existsSync(pkgLocal) ? pkgLocal : null;
+
+  const base = basePath ? parse(readFileSync(basePath, 'utf8')) : {};
+  const local = localPath ? parse(readFileSync(localPath, 'utf8')) : {};
+  return deepMerge(base, local);
+};
+
+const toml = loadToml();
+const tomlDefault = toml.default ?? {};
+const tomlPresets = toml.preset ?? {};
+
+// Resolve a preset by name: merge [default] → [preset.<name>]
+export const resolvePreset = name => {
+  const base = {
+    label: tomlDefault.label ?? 'Default',
+    userAgent: tomlDefault.userAgent ?? null,
+    overrideUserAgent: tomlDefault.overrideUserAgent ?? null,
+    viewport: tomlDefault.viewport ?? null,
+    locale: tomlDefault.locale ?? null,
+    timezone: tomlDefault.timezone ?? null,
+    headless: tomlDefault.headless ?? null,
+  };
+
+  if (!name || name === 'default') {
+    return { preset: 'chromium-honest', ...base };
+  }
+
+  const override = tomlPresets[name];
+  if (!override) {
+    return { preset: 'chromium-honest', ...base };
+  }
+
+  return {
+    preset: name,
+    label: override.label ?? base.label,
+    userAgent: override.userAgent ?? base.userAgent,
+    overrideUserAgent: override.overrideUserAgent ?? base.overrideUserAgent,
+    viewport: override.viewport ?? base.viewport,
+    locale: override.locale ?? base.locale,
+    timezone: override.timezone ?? base.timezone,
+    headless: override.headless ?? base.headless,
+  };
+};
+
+export const PRESETS = Object.keys(tomlPresets);
+
+// ── stealth config ──────────────────────────────────────────────────────────
+
+const tomlStealth = toml['puppeteer-extra-plugin-stealth'] ?? {};
+const tomlStealthEvasions = tomlStealth.evasions ?? {};
+
+export const STEALTH_ENABLED = tomlStealth.enabled ?? true;
+
+export const STEALTH_CONFIG = {
+  evasions: tomlStealthEvasions,
+  'user-agent-override': tomlStealth['user-agent-override'] ?? { enabled: true, mask_linux: true },
+  'navigator.vendor': tomlStealth['navigator.vendor'] ?? { enabled: true, vendor: 'Google Inc.' },
+  'navigator.hardwareConcurrency': tomlStealth['navigator.hardwareConcurrency'] ?? {
+    enabled: true,
+    hardware_concurrency: 4,
+  },
+  'navigator.languages': tomlStealth['navigator.languages'] ?? { enabled: true },
+  'webgl.vendor': tomlStealth['webgl.vendor'] ?? {
+    enabled: true,
+    vendor: 'Intel Inc.',
+    renderer: 'Intel Iris OpenGL Engine',
+  },
+};
+
+// ── resolved defaults ───────────────────────────────────────────────────────
+
+const defaults = resolvePreset('default');
+
+export const DEFAULT_TIMEOUT = 30000;
+export const TIMEOUT = tomlDefault.timeout ?? DEFAULT_TIMEOUT;
+
+export const HEADLESS =
+  process.env.HEADLESS !== undefined
+    ? process.env.HEADLESS === 'true'
+    : process.env.DISPLAY
+      ? (defaults.headless ?? false)
+      : true;
+
+export const DISABLE_WEBGL = tomlDefault.disable_webgl ?? false;
+export const LOG_LEVEL = tomlDefault.log_level ?? 'info';
+
+export const VIEWPORT = defaults.viewport ?? { width: 1280, height: 800 };
+
+export const USER_AGENT =
+  defaults.userAgent ||
+  'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36';
+
+export const LOCALE = defaults.locale || 'en-US';
+export const TIMEZONE = defaults.timezone || 'America/New_York';
+
+// ── Chromium path resolution ────────────────────────────────────────────────
+
+export const findChromiumPath = () => {
+  if (tomlDefault.executablePath) {
+    return tomlDefault.executablePath;
+  }
+
+  const playwrightCache = join(homedir(), '.cache', 'ms-playwright');
+
+  if (existsSync(playwrightCache)) {
+    const dirs = readdirSync(playwrightCache)
+      .filter(d => d.startsWith('chromium-'))
+      .sort()
+      .reverse();
+
+    for (const dir of dirs) {
+      const paths = [
+        join(playwrightCache, dir, 'chrome-linux', 'chrome'),
+        join(playwrightCache, dir, 'chrome-linux64', 'chrome'),
+      ];
+
+      for (const path of paths) {
+        if (existsSync(path)) return path;
+      }
+    }
+  }
+
+  const systemChromiums = [
+    '/usr/bin/chromium',
+    '/usr/bin/chromium-browser',
+    '/usr/bin/google-chrome',
+  ];
+
+  for (const path of systemChromiums) {
+    if (existsSync(path)) return path;
+  }
+
+  return null;
+};

package/packages/runtime/index.js

@@ -0,0 +1,10 @@
+// @szkrabok/runtime — public API
+// Do NOT expose: pool internals, storage internals, stealth utilities
+
+export { launch, connect } from './launch.js';
+export { closeSession, getSession, listSessions as listRuntimeSessions, listStoredSessions, updateSessionMeta, deleteStoredSession, updateSessionPage, closeAllSessions } from './sessions.js';
+export { resolvePreset, PRESETS } from './config.js';
+
+// MCP client
+export { mcpConnect } from './mcp-client/mcp-tools.js';
+export { spawnClient } from './mcp-client/runtime/transport.js';

package/packages/runtime/launch.js

@@ -0,0 +1,240 @@
+// launch.js — the one true browser bootstrap entry point.
+// Only this file calls launchPersistentContext.
+
+import { chromium } from 'playwright';
+import {
+  resolvePreset,
+  findChromiumPath,
+  HEADLESS,
+  VIEWPORT,
+  USER_AGENT,
+  LOCALE,
+  TIMEZONE,
+  STEALTH_ENABLED,
+} from './config.js';
+import { enhanceWithStealth, applyStealthToExistingPage } from './stealth.js';
+import * as storage from './storage.js';
+import * as pool from './pool.js';
+import { log } from './logger.js';
+
+// Derive a deterministic CDP port from session id.
+// Range 20000–29999 — avoids common service ports, gives 10 000 slots.
+const cdpPortForId = id => {
+  let h = 0;
+  for (let i = 0; i < id.length; i++) h = (Math.imul(31, h) + id.charCodeAt(i)) | 0;
+  return 20000 + (Math.abs(h) % 10000);
+};
+
+// _launchPersistentContext — internal, not exported.
+// Only called by launch() below.
+const _launchPersistentContext = async (userDataDir, options = {}) => {
+  const presetConfig = options.presetConfig ?? {};
+  const pw = options.stealth ? enhanceWithStealth(chromium, presetConfig) : chromium;
+  const executablePath = findChromiumPath();
+
+  if (executablePath) {
+    log('Using existing Chromium for persistent context', { path: executablePath });
+  }
+
+  const launchOptions = {
+    ...options,
+    headless: options.headless ?? HEADLESS,
+    executablePath,
+    viewport: options.viewport,
+    locale: options.locale,
+    timezoneId: options.timezoneId,
+    userAgent: options.userAgent,
+  };
+
+  delete launchOptions.stealth;
+  delete launchOptions.presetConfig;
+
+  launchOptions.args = [
+    '--hide-crash-restore-bubble',
+    '--disable-features=PortalActivationDelegate',
+    ...(launchOptions.args || []),
+  ];
+
+  if (launchOptions.cdpPort) {
+    launchOptions.args = [
+      ...launchOptions.args,
+      `--remote-debugging-port=${launchOptions.cdpPort}`,
+    ];
+    delete launchOptions.cdpPort;
+  }
+
+  const context = await pw.launchPersistentContext(userDataDir, launchOptions);
+
+  if (options.stealth) {
+    const pages = context.pages();
+    if (pages.length > 0) {
+      await applyStealthToExistingPage(pages[0], presetConfig);
+    }
+  }
+
+  return context;
+};
+
+/**
+ * Launch a browser session.
+ *
+ * @param {object} [options]
+ * @param {string} [options.profile]    Session name / profile dir key
+ * @param {string} [options.preset]     TOML preset name (default: "default")
+ * @param {boolean} [options.headless]  Overrides TOML + env
+ * @param {boolean} [options.stealth]   Overrides TOML stealth setting
+ * @param {string} [options.userAgent]  Overrides TOML + preset userAgent
+ * @param {object} [options.viewport]   Overrides TOML + preset viewport { width, height }
+ * @param {string} [options.locale]     Overrides TOML + preset locale
+ * @param {string} [options.timezone]   Overrides TOML + preset timezone
+ * @param {boolean} [options.reuse]     Return existing if profile already open (default: true)
+ * @returns {Promise<{ browser: import('playwright').Browser, context: import('playwright').BrowserContext, cdpEndpoint: string, close(): Promise<void> }>}
+ */
+export const launch = async (options = {}) => {
+  const { profile = 'default', preset: presetName, headless, stealth, userAgent, viewport, locale, timezone, reuse = true } = options;
+
+  // Idempotency: return existing handle when reuse=true and profile is open
+  if (reuse && pool.has(profile)) {
+    log(`Reusing existing session: ${profile}`);
+    const existing = pool.get(profile);
+    const cdpEndpoint = `http://localhost:${existing.cdpPort}`;
+    return {
+      browser: existing.context.browser(),
+      context: existing.context,
+      cdpEndpoint,
+      close: async () => {
+        const state = await existing.context.storageState();
+        await storage.saveState(profile, state);
+        await storage.updateMeta(profile, { lastUsed: Date.now() });
+        await existing.context.close();
+        pool.remove(profile);
+      },
+    };
+  }
+
+  await storage.ensureSessionsDir();
+
+  const savedMeta = await storage.loadMeta(profile);
+  const savedConfig = savedMeta?.config ?? {};
+
+  // If an explicit preset is given, it resets the baseline — savedConfig is bypassed
+  // for preset-derived fields. Individual field overrides (userAgent etc.) always win.
+  const resolved = resolvePreset(presetName ?? savedMeta?.preset);
+  const base = presetName ? {} : savedConfig;
+
+  const effectiveViewport = viewport || base.viewport || resolved.viewport || VIEWPORT;
+  const effectiveUserAgent = userAgent || base.userAgent || resolved.userAgent || USER_AGENT;
+  const effectiveLocale = locale || base.locale || resolved.locale || LOCALE;
+  const effectiveTimezone = timezone || base.timezone || resolved.timezone || TIMEZONE;
+  const effectiveStealth = stealth ?? savedConfig.stealth ?? STEALTH_ENABLED;
+  const effectiveHeadless = headless ?? savedConfig.headless ?? HEADLESS;
+
+  const presetConfig = {
+    userAgent: effectiveUserAgent,
+    locale: effectiveLocale,
+    overrideUserAgent: resolved.overrideUserAgent,
+  };
+
+  const userDataDir = storage.getUserDataDir(profile);
+  const cdpPort = cdpPortForId(profile);
+
+  const context = await _launchPersistentContext(userDataDir, {
+    stealth: effectiveStealth,
+    presetConfig,
+    viewport: effectiveViewport,
+    userAgent: effectiveUserAgent,
+    locale: effectiveLocale,
+    timezoneId: effectiveTimezone,
+    headless: effectiveHeadless,
+    cdpPort,
+  });
+
+  // Restore saved state (cookies + localStorage)
+  const savedState = await storage.loadState(profile);
+  if (savedState) {
+    if (savedState.cookies?.length) {
+      try {
+        await context.addCookies(savedState.cookies);
+        log(`Restored ${savedState.cookies.length} cookies for ${profile}`);
+      } catch (err) {
+        log(`Cookie restore failed for ${profile}: ${err.message}`);
+      }
+    }
+    if (savedState.origins?.length) {
+      const origins = savedState.origins;
+      await context.addInitScript(savedOrigins => {
+        const origin = location.origin;
+        const entry = savedOrigins.find(o => o.origin === origin);
+        if (!entry?.localStorage?.length) return;
+        for (const { name, value } of entry.localStorage) {
+          try { localStorage.setItem(name, value); } catch {}
+        }
+      }, origins);
+      log(`Restored localStorage for ${savedState.origins.length} origin(s) in ${profile}`);
+    }
+  }
+
+  // Mask iframe fingerprints
+  await context.addInitScript(() => {
+    const originalCreateElement = document.createElement;
+    document.createElement = function (tag) {
+      return originalCreateElement.call(document, tag);
+    };
+  });
+
+  context.on('close', () => {
+    log(`Context ${profile} was closed`);
+    if (pool.has(profile)) pool.remove(profile);
+  });
+
+  const pages = context.pages();
+  const page = pages.length > 0 ? pages[0] : await context.newPage();
+
+  pool.add(profile, context, page, cdpPort, resolved.preset, resolved.label);
+
+  const meta = {
+    sessionName: profile,
+    created: savedMeta?.created ?? Date.now(),
+    lastUsed: Date.now(),
+    preset: resolved.preset,
+    label: resolved.label,
+    config: {
+      userAgent: effectiveUserAgent,
+      viewport: effectiveViewport,
+      locale: effectiveLocale,
+      timezone: effectiveTimezone,
+      stealth: effectiveStealth,
+      headless: effectiveHeadless,
+    },
+    userDataDir,
+  };
+  await storage.saveMeta(profile, meta);
+
+  const cdpEndpoint = `http://localhost:${cdpPort}`;
+
+  return {
+    browser: context.browser(),
+    context,
+    cdpEndpoint,
+    close: async () => {
+      const state = await context.storageState();
+      await storage.saveState(profile, state);
+      await storage.updateMeta(profile, { lastUsed: Date.now() });
+      await context.close();
+      pool.remove(profile);
+    },
+  };
+};
+
+/**
+ * Connect to an already-running browser via CDP endpoint.
+ *
+ * @param {string} cdpEndpoint
+ * @returns {Promise<{ browser: import('playwright').Browser, context: import('playwright').BrowserContext }>}
+ */
+export const connect = async cdpEndpoint => {
+  const browser = await chromium.connectOverCDP(cdpEndpoint);
+  const contexts = browser.contexts();
+  const context = contexts[0] ?? (await browser.newContext());
+  return { browser, context };
+};