dsh-browser-playwright-codex 0.5.1

package/lib/types.d.ts

@@ -0,0 +1,242 @@
+/**
+ * Domain types for the browser capability: snapshots, sessions, providers.
+ * @module dsh-browser-playwright-codex/types
+ */
+/** Page load condition a navigation waits for. */
+export type LoadState = 'load' | 'domcontentloaded' | 'networkidle';
+/** One snapshot element. Refs identify actionable elements for later calls. */
+export interface BrowserNode {
+    /** Accessible role, e.g. link, button, textbox, heading. */
+    readonly role: string;
+    /** Accessible-ish name; empty when the element has none. */
+    readonly name: string;
+    /** Stable per-snapshot reference; present only on actionable elements. */
+    readonly ref?: string;
+    /** Heading level (1-6); present only for headings. */
+    readonly level?: number;
+    /** Whether a checkbox/radio is checked. */
+    readonly checked?: boolean;
+    /** Whether an option is selected. */
+    readonly selected?: boolean;
+    /** Whether the element is disabled. */
+    readonly disabled?: boolean;
+    /** Href for links; present when the page is same-origin. */
+    readonly href?: string;
+    readonly children: readonly BrowserNode[];
+}
+/** Bounded accessibility snapshot of the current page. */
+export interface BrowserSnapshot {
+    readonly url: string;
+    readonly title: string;
+    readonly nodes: readonly BrowserNode[];
+    /** Total refs assigned before any truncation. */
+    readonly totalRefs: number;
+    /** True when node or text caps cut the tree short. */
+    readonly truncated: boolean;
+    /**
+     * Incremental diff against the previous snapshot of this document, present
+     * only when the provider's snapshot.diff is enabled and a baseline exists.
+     * Absence means "full snapshot follows": first capture, navigation reset,
+     * or a truncated tree (diff is then unreliable, so the provider degrades
+     * to the full tree). Diff entries are keyed by the stable data-dsh-ref.
+     */
+    readonly diff?: SnapshotDiff;
+    /**
+     * Note parked on the snapshot when a native dialog blocks the page: the
+     * snapshot then describes the blocker instead of the page (DIALOG-POLICY).
+     */
+    dialogNote?: string;
+    /**
+     * Where the last click actually landed, when the provider can prove it. Its
+     * absence means "not reported", never "landed on the target".
+     */
+    landingNote?: string;
+    /**
+     * Set when the configured page reader could not read this page and the
+     * provider degraded to the other engine. Without it the fallback was silent,
+     * and a user who picked smart mode kept believing it was running.
+     */
+    engineNote?: string;
+}
+/** One element that entered the tree since the previous snapshot. */
+export interface SnapshotDiffEntry {
+    readonly ref: string;
+    readonly role?: string;
+    readonly name?: string;
+    /** State flags for an added element (checked / selected / disabled / level=N). */
+    readonly flags?: string[];
+    /** State flags that changed on an existing element. */
+    readonly flagsDelta?: string[];
+    /** Nearest ancestor ref, so a diff line keeps its tree context. */
+    readonly parentRef?: string;
+}
+/**
+ * Incremental delta between two snapshots of the same document, keyed by the
+ * stable data-dsh-ref (e<docNonce><seq>). `navigationReset: true` means the
+ * ref space changed (navigation) or the tree was truncated, so the delta is
+ * void and the consumer must rely on the full snapshot that follows.
+ */
+export interface SnapshotDiff {
+    readonly added: readonly SnapshotDiffEntry[];
+    readonly removed: readonly string[];
+    readonly changed: readonly SnapshotDiffEntry[];
+    /** Number of elements whose ref and features are unchanged. */
+    readonly same: number;
+    /** True when the previous ref space is void (navigation or truncation). */
+    readonly navigationReset: boolean;
+}
+/** One open tab in the browser session. */
+export interface TabInfo {
+    readonly index: number;
+    readonly url: string;
+    readonly title: string;
+    /** True for the tab the session currently drives. */
+    readonly active: boolean;
+}
+/** PNG capture of a page or element. */
+export interface ScreenshotCapture {
+    readonly mime: 'image/png';
+    readonly bytes: Uint8Array;
+}
+/** One captured diagnostics entry: a console line or a network request. */
+export type DiagnosticsEntry = {
+    /** Monotonic sequence number within the session's ring buffer. */
+    n?: number | undefined;
+    /** Capture time (epoch milliseconds), set by the provider. */
+    at?: number | undefined;
+    /** Console level (log / warning / error / pageerror), diagnostics only. */
+    level?: string | undefined;
+    /** Console text, truncated by the provider. */
+    text?: string | undefined;
+    /** Source URL the console entry came from. */
+    source?: string | undefined;
+    /** HTTP method, network entries only. */
+    method?: string | undefined;
+    /** Request URL, network entries only. */
+    url?: string | undefined;
+    /** Response status, null while pending or after a failure. */
+    status?: number | null | undefined;
+    /** Resource type, network entries only. */
+    kind?: string | undefined;
+    /** Round-trip duration in milliseconds, when the request settled. */
+    ms?: number | null | undefined;
+    /** Transport failure text, when the request never completed. */
+    failure?: string | null | undefined;
+    /**
+     * Which page of this session produced the entry. The rings stay session-wide so
+     * chronology survives a tab switch, but the diagnostics tools report only the
+     * page the session is driving and say how many entries they left out.
+     */
+    page?: number | undefined;
+};
+/** Canonical value of browser_console_messages and browser_network_requests. */
+export type DiagnosticsValue = {
+    /** URL of the tab the entries were captured from, when known. */
+    url?: string | null;
+    /** Requested console level filter, diagnostics only. */
+    level?: string | undefined;
+    /** Entries matching the filter. */
+    readonly total: number;
+    /** Entries actually returned after the limit was applied. */
+    readonly returned: number;
+    /** Entries evicted from the ring buffer, so truncation stays visible. */
+    readonly dropped?: number;
+    /**
+     * Matching entries that were left out because they belong to another tab of
+     * the shared window. Non-zero means "this tab is quiet, the noise is elsewhere"
+     * — the reader must say so instead of letting a model diagnose a foreign page.
+     */
+    readonly otherPages?: number;
+    readonly entries: readonly DiagnosticsEntry[];
+};
+/**
+ * Live browser session owned by one caller (a harness session id).
+ * Providers manage the underlying browser contexts; callers only drive.
+ */
+export interface BrowserSession {
+    /** Opaque owner key supplied at acquisition. */
+    readonly owner: string;
+    /** Navigate the active page and return the post-navigation snapshot. */
+    navigate(url: string, waitUntil: LoadState, signal?: AbortSignal): Promise<BrowserSnapshot>;
+    /** Snapshot the active page without changing it. */
+    snapshot(opts?: {
+        readonly interactiveOnly?: boolean;
+    }): Promise<BrowserSnapshot>;
+    /** Click the element referenced by the latest snapshot. */
+    click(ref: string, signal?: AbortSignal): Promise<BrowserSnapshot>;
+    /** Replace the referenced input's value and return the new snapshot. */
+    fill(ref: string, text: string, signal?: AbortSignal): Promise<BrowserSnapshot>;
+    /** Press a keyboard key on the referenced element. */
+    press(ref: string, key: string, signal?: AbortSignal): Promise<BrowserSnapshot>;
+    /** Scroll the page, or the referenced scrollable, by the given amount. */
+    scroll(direction: 'up' | 'down', amount: number, ref: string | undefined, signal?: AbortSignal): Promise<BrowserSnapshot>;
+    /** History back. */
+    back(signal?: AbortSignal): Promise<BrowserSnapshot>;
+    /** History forward. */
+    forward(signal?: AbortSignal): Promise<BrowserSnapshot>;
+    /** Wait a bounded duration, letting lazy content arrive. */
+    wait(ms: number, signal?: AbortSignal): Promise<void>;
+    /** List open tabs. */
+    tabs(): Promise<readonly TabInfo[]>;
+    /** Activate the tab at the given index. */
+    switchTab(index: number, signal?: AbortSignal): Promise<BrowserSnapshot>;
+    /** Open a new tab and navigate it. */
+    openTab(url: string, waitUntil: LoadState, signal?: AbortSignal): Promise<BrowserSnapshot>;
+    /** Close the tab at the given index; the last tab resets to a blank page. */
+    closeTab(index: number, signal?: AbortSignal): Promise<void>;
+    /** Capture a PNG of the page or referenced element. */
+    screenshot(opts: {
+        readonly fullPage?: boolean;
+        readonly ref?: string;
+    } | undefined, signal?: AbortSignal): Promise<ScreenshotCapture>;
+    /** Extract the page's bounded data: text, links, forms, frames. */
+    pageData(): Promise<unknown>;
+    /** Evaluate one JavaScript expression and return its JSON result. */
+    evaluate(expression: string, signal?: AbortSignal): Promise<unknown>;
+    /** Click the element whose visible text matches, by semantic locator. */
+    clickText(text: string, signal?: AbortSignal): Promise<BrowserSnapshot>;
+    /** Click the element referenced by the latest snapshot at its geometry. */
+    clickAtRef(ref: string, signal?: AbortSignal): Promise<BrowserSnapshot>;
+    /** Click raw viewport coordinates, when no ref resolves the target. */
+    clickAt(x: number, y: number, signal?: AbortSignal): Promise<BrowserSnapshot>;
+    /** Hover the referenced element. */
+    hover(ref: string, signal?: AbortSignal): Promise<BrowserSnapshot>;
+    /** Hover the element whose visible text matches. */
+    hoverText(text: string, signal?: AbortSignal): Promise<BrowserSnapshot>;
+    /** Answer the parked native dialog and return the post-answer snapshot. */
+    resolveDialog(accept: boolean, promptText: string | undefined, signal?: AbortSignal): Promise<BrowserSnapshot>;
+    /**
+     * Send one raw CDP command on the current page. The provider performs no
+     * policy filtering: callers are the tool layer, which holds the allow-list.
+     */
+    cdp(method: string, params: Record<string, unknown>, signal?: AbortSignal): Promise<unknown>;
+    /** Recent console messages and uncaught page errors for this session. */
+    consoleMessages(args: {
+        readonly level?: string;
+        readonly limit?: number;
+    }): DiagnosticsValue;
+    /** Recent network requests for this session, newest last. */
+    networkRequests(args: {
+        readonly urlContains?: string;
+        readonly failedOnly?: boolean;
+        readonly limit?: number;
+    }): DiagnosticsValue;
+    /** Close the session; the provider forgets its browser context. */
+    close(): Promise<void>;
+}
+/**
+ * One browser-capability implementation. Providers own browser binaries,
+ * context fleets, and lifecycle; the runtime selects exactly one.
+ */
+export interface BrowserProvider {
+    /** Stable unique provider id. */
+    readonly id: string;
+    /** Whether this provider can currently serve sessions. */
+    available(): boolean;
+    /** Acquire or reuse the session owned by the owner key. */
+    acquire(owner: string, signal?: AbortSignal): Promise<BrowserSession>;
+    /** Release the session owned by the owner key and its browser resources. */
+    disposeOwner(owner: string): Promise<void>;
+    /** Release every session and the browser itself. */
+    dispose(): Promise<void>;
+}

package/lib/types.js

@@ -0,0 +1,5 @@
+/**
+ * Domain types for the browser capability: snapshots, sessions, providers.
+ * @module dsh-browser-playwright-codex/types
+ */
+export {};

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Browser Automation",
+    "description": "Playwright-powered browser capability for DeepSeek Harness: accessibility-snapshot interaction with stable element refs, session-scoped browser sessions, screenshots as attachments."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "浏览器自动化",
+    "description": "浏览器自动化（Playwright）：无障碍快照交互 + 稳定元素引用、会话级浏览器实例、截图作为附件。"
+  }
+}

package/package.json

@@ -0,0 +1,108 @@
+{
+  "name": "dsh-browser-playwright-codex",
+  "version": "0.5.1",
+  "description": "Browser automation for DeepSeek Harness: fill in forms, scrape lists and work across tabs in real pages, using the logins you already have. Runs in a visible window that stays quiet when minimised, and stops for sign-ins, CAPTCHAs and native dialogs instead of confirming for you.",
+  "license": "MIT",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./service": {
+      "types": "./lib/service.d.ts",
+      "default": "./lib/service.js"
+    },
+    "./playwright": {
+      "types": "./lib/playwright.d.ts",
+      "default": "./lib/playwright.js"
+    },
+    "./tool": {
+      "types": "./lib/tool.d.ts",
+      "default": "./lib/tool.js"
+    },
+    "./runtime-state": {
+      "default": "./lib/runtime-state.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json"
+  },
+  "files": [
+    "lib",
+    "scripts",
+    "cordis.patch.yml",
+    "README.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "locale"
+  ],
+  "scripts": {
+    "build": "node node_modules/typescript/bin/tsc -p tsconfig.json",
+    "test": "node node_modules/tsx/dist/cli.mjs --test \"tests/*.test.ts\"",
+    "test:scenarios": "node node_modules/tsx/dist/cli.mjs --test tests/scenarios.test.ts tests/tool-scenarios.test.ts",
+    "test:live": "node node_modules/tsx/dist/cli.mjs --test tests/live-smoke.test.ts",
+    "verify": "npm run build && node scripts/dsh-browser-verify.mjs",
+    "verify:live": "npm run build && node scripts/dsh-browser-verify.mjs --live",
+    "doctor": "node scripts/doctor.mjs",
+    "cost": "node node_modules/tsx/dist/cli.mjs scripts/measure-prompt-cost.mjs",
+    "format": "node node_modules/prettier/bin/prettier.cjs --write \"src/**/*.ts\" \"tests/**/*.ts\" \"scripts/**/*.mjs\"",
+    "format:check": "node node_modules/prettier/bin/prettier.cjs --check \"src/**/*.ts\" \"tests/**/*.ts\" \"scripts/**/*.mjs\"",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "*",
+    "playwright-core": "~1.62.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "*",
+    "@deepseek-ai/dsh-llm": "*",
+    "@deepseek-ai/dsh-tools": "*"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.4",
+    "@deepseek-ai/dsh-agent": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-attachment": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-llm": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-session": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-tools": "0.2.0-rc.1",
+    "@deepseek-ai/schemastery": "3.18.4",
+    "@types/node": "^24.13.3",
+    "prettier": "^3.9.9",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.0"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "dsh-plugin",
+    "browser",
+    "playwright",
+    "web-automation",
+    "agent",
+    "automation",
+    "browser-automation",
+    "web-scraping",
+    "form-filling",
+    "deepseek",
+    "ai-agent",
+    "rpa"
+  ],
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "packageManager": "pnpm@10.31.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/miqian-nomad/dsh-browser-playwright-codex.git"
+  },
+  "homepage": "https://github.com/miqian-nomad/dsh-browser-playwright-codex#readme"
+}

package/scripts/analysis/hl-compare.mjs

@@ -0,0 +1,149 @@
+/**
+ * Measures what actually differs between the plugin's headless and headful
+ * launch shapes, on the SAME persistent profile, using the plugin's real
+ * launch options (channel chrome, HUMANIZED_LAUNCH args, viewport rules).
+ *
+ *   MODE=headless|headful  PROFILE=<dir>  node hl-compare.mjs
+ */
+import { createRequire } from 'node:module'
+import path from 'node:path'
+import fs from 'node:fs'
+
+const require = createRequire(import.meta.url)
+const { chromium } = require(process.env.PW_CORE_PATH ?? 'playwright-core')
+
+const MODE = process.env.MODE ?? 'headless'
+const headless = MODE === 'headless'
+const profile = process.env.PROFILE
+const probeHtml = process.env.PROBE_HTML
+
+// Mirror of the plugin's baseOptions (lib/playwright.js:437-457).
+const HUMANIZED_LAUNCH = { args: ['--disable-blink-features=AutomationControlled'] }
+const options = {
+  headless,
+  channel: process.env.CHANNEL || undefined,
+  ...(headless ? { viewport: { width: 1280, height: 800 } } : { viewport: null }),
+  ignoreHTTPSErrors: false,
+  ...HUMANIZED_LAUNCH,
+  args: [
+    '--no-first-run',
+    '--no-default-browser-check',
+    ...(headless ? [] : ['--start-maximized']),
+    ...HUMANIZED_LAUNCH.args,
+    ...(process.env.EXTRA_ARG ? [process.env.EXTRA_ARG] : []),
+  ],
+}
+
+const context = await chromium.launchPersistentContext(profile, options)
+const page = context.pages()[0] ?? (await context.newPage())
+
+// Persistent state continuity across a headless <-> headful switch.
+if (process.env.PHASE === 'write') {
+  await page.goto('https://example.com', { waitUntil: 'domcontentloaded' }).catch(() => {})
+  await context.addCookies([
+    { name: 'switch-session', value: 'session-42', domain: 'example.com', path: '/' },
+    {
+      name: 'switch-durable',
+      value: 'durable-42',
+      domain: 'example.com',
+      path: '/',
+      expires: Math.floor(Date.now() / 1000) + 365 * 24 * 3600,
+    },
+  ])
+  await page.evaluate(() => localStorage.setItem('switch-probe', 'kept-42')).catch(() => {})
+  console.log(JSON.stringify({ mode: MODE, phase: 'write', cookieSet: true }))
+  await context.close()
+  process.exit(0)
+}
+
+if (process.env.PHASE === 'check') {
+  await page.goto('https://example.com', { waitUntil: 'domcontentloaded' }).catch(() => {})
+  const cookies = await context.cookies('https://example.com')
+  const ls = await page.evaluate(() => localStorage.getItem('switch-probe')).catch(() => null)
+  console.log(
+    JSON.stringify(
+      {
+        mode: MODE,
+        phase: 'check',
+        sessionCookie: cookies.find((c) => c.name === 'switch-session')?.value ?? null,
+        durableCookie: cookies.find((c) => c.name === 'switch-durable')?.value ?? null,
+        localStorage: ls,
+      },
+      null,
+      2,
+    ),
+  )
+  await context.close()
+  process.exit(0)
+}
+
+await page.goto('file:///' + probeHtml.replace(/\\/g, '/'), { waitUntil: 'load' })
+
+const measured = await page.evaluate(async () => {
+  const box = document.querySelector('#box').getBoundingClientRect()
+  const cjk = document.querySelector('#cjk').getBoundingClientRect()
+  const tail = document.querySelector('#tail').getBoundingClientRect()
+  const rafStart = performance.now()
+  let rafCount = 0
+  await new Promise((resolve) => {
+    const tick = () => {
+      rafCount += 1
+      if (performance.now() - rafStart > 1000) resolve()
+      else requestAnimationFrame(tick)
+    }
+    requestAnimationFrame(tick)
+  })
+  return {
+    ua: navigator.userAgent,
+    webdriver: navigator.webdriver,
+    inner: [window.innerWidth, window.innerHeight],
+    outer: [window.outerWidth, window.outerHeight],
+    screen: [screen.width, screen.height],
+    avail: [screen.availWidth, screen.availHeight],
+    dpr: window.devicePixelRatio,
+    visibility: document.visibilityState,
+    hasFocus: document.hasFocus(),
+    rafPerSecond: rafCount,
+    box: [Math.round(box.width), Math.round(box.height)],
+    cjkWidth: Math.round(cjk.width * 100) / 100,
+    tailY: Math.round(tail.top),
+    fonts: document.fonts.size,
+    // Media-feature fingerprint: Playwright's headless default args include
+    // --blink-settings=primaryPointerType=4,availableHoverTypes=2.
+    coarse: matchMedia('(pointer: coarse)').matches,
+    fine: matchMedia('(pointer: fine)').matches,
+    hoverHover: matchMedia('(hover: hover)').matches,
+    anyHover: matchMedia('(any-hover: hover)').matches,
+    maxTouchPoints: navigator.maxTouchPoints,
+    languages: navigator.languages.join(','),
+    breakpoints: {
+      'min-width:1000px': matchMedia('(min-width: 1000px)').matches,
+      'min-width:1152px': matchMedia('(min-width: 1152px)').matches,
+      'min-width:1200px': matchMedia('(min-width: 1200px)').matches,
+      'min-width:1280px': matchMedia('(min-width: 1280px)').matches,
+      'min-width:1440px': matchMedia('(min-width: 1440px)').matches,
+    },
+  }
+})
+
+const shot = await page.screenshot({ path: path.join(path.dirname(profile), `shot-${MODE}.png`) })
+const png = fs.readFileSync(path.join(path.dirname(profile), `shot-${MODE}.png`))
+// PNG IHDR: width/height are bytes 16-23.
+const shotW = png.readUInt32BE(16)
+const shotH = png.readUInt32BE(20)
+
+console.log(
+  JSON.stringify(
+    {
+      mode: MODE,
+      headless,
+      ...measured,
+      screenshotBytes: shot.length,
+      screenshotSize: [shotW, shotH],
+    },
+    null,
+    2,
+  ),
+)
+
+await context.close()

package/scripts/analysis/live-handoff-probe.mjs

@@ -0,0 +1,97 @@
+/**
+ * Does a minimize -> (agent works) -> restore cycle preserve the live page?
+ *
+ * If yes, a headful browser can sit minimized while the agent works, and a
+ * "show the window" action can hand the SAME page (same captcha, same form,
+ * same scroll position) to the human without a relaunch, a reload, or any
+ * loss of tabs / session cookies.
+ */
+import { createRequire } from 'node:module'
+import path from 'node:path'
+import fs from 'node:fs'
+import os from 'node:os'
+
+const require = createRequire(import.meta.url)
+const { chromium } = require(process.env.PW_CORE_PATH ?? 'playwright-core')
+
+const profile = fs.mkdtempSync(path.join(os.tmpdir(), 'pw-live-handoff-'))
+const context = await chromium.launchPersistentContext(profile, {
+  headless: false,
+  channel: process.env.CHANNEL || undefined,
+  viewport: null,
+  ignoreDefaultArgs: ['--enable-automation'],
+  args: [
+    '--no-first-run',
+    '--no-default-browser-check',
+    '--start-maximized',
+    '--disable-blink-features=AutomationControlled',
+  ],
+})
+const page = context.pages()[0] ?? (await context.newPage())
+const out = {}
+
+// A "challenge-like" page: a form + a live counter + scroll depth, all of which
+// would be destroyed by a reload.
+await page.setContent(`<html><body style="height:5000px">
+  <input id=t value="">
+  <div id=status>fresh</div>
+  <script>
+    window.__loads = (window.__loads || 0) + 1;
+    window.__counter = 0;
+    setInterval(() => { window.__counter++; document.querySelector('#status').textContent = 'ticks:' + window.__counter; }, 200);
+    window.scrollTo(0, 1500);
+  </script>
+</body></html>`)
+await page.fill('#t', 'captcha-answer-in-progress')
+await page.evaluate(() => window.scrollTo(0, 1500))
+await new Promise((r) => setTimeout(r, 700))
+
+const cdp = await context.newCDPSession(page)
+const windowId = async () => (await cdp.send('Browser.getWindowForTarget')).windowId
+const state = async () => (await cdp.send('Browser.getWindowBounds', { windowId: await windowId() })).bounds.windowState
+const setState = async (s) => {
+  const id = await windowId()
+  return cdp.send('Browser.setWindowBounds', { windowId: id, bounds: { windowState: s } })
+}
+
+out.beforeMinimize = { windowState: await state() }
+
+// Human walks away / the harness wants the desktop: minimize.
+await setState('minimized')
+await new Promise((r) => setTimeout(r, 900))
+out.minimized = { windowState: await state() }
+
+// Agent keeps working on the SAME minimized page.
+const snapshotWhileMinimized = await page.evaluate(() => ({
+  value: document.querySelector('#t').value,
+  status: document.querySelector('#status').textContent,
+  scrollY: Math.round(window.scrollY),
+  loads: window.__loads,
+  counter: window.__counter,
+}))
+await page.screenshot({ path: path.join(path.dirname(profile), 'while-minimized.png') })
+out.agentWorkWhileMinimized = snapshotWhileMinimized
+
+// Human needed: show the window. No relaunch, no reload.
+const foregroundBefore = await page.evaluate(() => document.hasFocus())
+await setState('normal')
+await page.bringToFront()
+await new Promise((r) => setTimeout(r, 900))
+out.afterShow = {
+  windowState: await state(),
+  documentFocused: await page.evaluate(() => document.hasFocus()),
+  documentFocusedBefore: foregroundBefore,
+  // The point of the whole exercise: is it still the same page instance?
+  statePreserved: await page.evaluate(() => ({
+    value: document.querySelector('#t').value,
+    status: document.querySelector('#status').textContent,
+    scrollY: Math.round(window.scrollY),
+    loads: window.__loads,
+    counter: window.__counter,
+  })),
+}
+
+console.log(JSON.stringify(out, null, 2))
+await setState('normal').catch(() => {})
+await context.close()
+fs.rmSync(profile, { recursive: true, force: true })