@agentrhq/webcmd 0.2.5 → 0.3.1

package/dist/src/browser/runtime/local-cloak/darwin-background-launch.js

@@ -0,0 +1,106 @@
+import { execFile } from 'node:child_process';
+import { readFile, rm } from 'node:fs/promises';
+import { posix as path } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { promisify } from 'node:util';
+import { buildLaunchOptions, humanizeBrowser } from 'cloakbrowser';
+import { chromium } from 'playwright-core';
+const execFileAsync = promisify(execFile);
+async function openApplication(appPath, args) {
+    await execFileAsync('/usr/bin/open', ['-g', '-n', appPath, '--args', ...args]);
+}
+export async function waitForDevToolsPort(portFile, timeoutMs = 10_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            const port = Number.parseInt((await readFile(portFile, 'utf8')).split('\n')[0], 10);
+            if (Number.isInteger(port) && port > 0)
+                return port;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        await delay(50);
+    }
+    throw new Error('Timed out waiting for background Chromium CDP endpoint');
+}
+async function terminateProfile(userDataDir) {
+    const { stdout } = await execFileAsync('/bin/ps', ['-axo', 'pid=,command=']);
+    const needle = `--user-data-dir=${userDataDir}`;
+    for (const line of stdout.split('\n')) {
+        if (!line.includes(needle))
+            continue;
+        const pid = Number.parseInt(line.trim().split(/\s+/, 1)[0], 10);
+        if (Number.isInteger(pid) && pid !== process.pid)
+            process.kill(pid, 'SIGTERM');
+    }
+}
+const defaultDependencies = {
+    buildLaunchOptions,
+    humanizeBrowser,
+    openApplication,
+    activateApplication: async (appPath) => {
+        await execFileAsync('/usr/bin/open', [appPath]);
+    },
+    readPort: waitForDevToolsPort,
+    connectOverCDP: endpoint => chromium.connectOverCDP(endpoint),
+    terminateProfile,
+    removePortFile: portFile => rm(portFile, { force: true }),
+};
+const contextActivators = new WeakMap();
+export async function activateDarwinBackgroundContext(context) {
+    await contextActivators.get(context)?.();
+}
+function appPathFor(executablePath) {
+    const marker = `${path.sep}Contents${path.sep}MacOS${path.sep}`;
+    const index = executablePath.lastIndexOf(marker);
+    if (index < 0)
+        throw new Error(`Cloak Chromium executable is not inside a macOS app bundle: ${executablePath}`);
+    return executablePath.slice(0, index);
+}
+export async function launchDarwinBackgroundPersistentContext(options, deps = defaultDependencies) {
+    const portFile = path.join(options.userDataDir, 'DevToolsActivePort');
+    await deps.removePortFile(portFile);
+    const launchOptions = await deps.buildLaunchOptions(options);
+    if (!launchOptions.executablePath)
+        throw new Error('Cloak Chromium executable path is missing');
+    const appPath = appPathFor(launchOptions.executablePath);
+    let browser;
+    let launched = false;
+    try {
+        await deps.openApplication(appPath, [
+            ...(launchOptions.args ?? []),
+            '--password-store=basic',
+            '--use-mock-keychain',
+            `--user-data-dir=${options.userDataDir}`,
+            '--remote-debugging-address=127.0.0.1',
+            '--remote-debugging-port=0',
+            'about:blank',
+        ]);
+        launched = true;
+        const port = await deps.readPort(portFile);
+        browser = await deps.connectOverCDP(`http://127.0.0.1:${port}`);
+        await deps.humanizeBrowser(browser, options);
+        const context = browser.contexts()[0];
+        if (!context)
+            throw new Error('Background Chromium did not expose a persistent context');
+        contextActivators.set(context, () => deps.activateApplication(appPath));
+        context.close = async () => {
+            try {
+                await browser.close();
+            }
+            finally {
+                contextActivators.delete(context);
+                await deps.terminateProfile(options.userDataDir);
+            }
+        };
+        return context;
+    }
+    catch (error) {
+        await browser?.close().catch(() => { });
+        if (launched)
+            await deps.terminateProfile(options.userDataDir).catch(() => { });
+        throw error;
+    }
+}

package/dist/src/browser/runtime/local-cloak/darwin-background-launch.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/browser/runtime/local-cloak/darwin-background-launch.test.js

@@ -0,0 +1,65 @@
+import { describe, expect, it, vi } from 'vitest';
+import { activateDarwinBackgroundContext, launchDarwinBackgroundPersistentContext, waitForDevToolsPort } from './darwin-background-launch.js';
+const options = {
+    userDataDir: '/tmp/cloak profile',
+    headless: false,
+    humanize: true,
+};
+function fakeRuntime() {
+    const context = { close: vi.fn() };
+    const browser = {
+        contexts: vi.fn(() => [context]),
+        close: vi.fn().mockResolvedValue(undefined),
+    };
+    return { browser, context };
+}
+function fakeDependencies(browser) {
+    return {
+        buildLaunchOptions: vi.fn().mockResolvedValue({
+            executablePath: '/Applications/Cloak Chromium.app/Contents/MacOS/Chromium',
+            args: ['--fingerprint=123'],
+        }),
+        humanizeBrowser: vi.fn().mockResolvedValue(undefined),
+        openApplication: vi.fn().mockResolvedValue(undefined),
+        activateApplication: vi.fn().mockResolvedValue(undefined),
+        readPort: vi.fn().mockResolvedValue(43123),
+        connectOverCDP: vi.fn().mockResolvedValue(browser),
+        terminateProfile: vi.fn().mockResolvedValue(undefined),
+        removePortFile: vi.fn().mockResolvedValue(undefined),
+    };
+}
+describe('launchDarwinBackgroundPersistentContext', () => {
+    it('launches the Chromium app without activation and connects through loopback CDP', async () => {
+        const { browser, context } = fakeRuntime();
+        const deps = fakeDependencies(browser);
+        const result = await launchDarwinBackgroundPersistentContext(options, deps);
+        expect(deps.removePortFile).toHaveBeenCalledWith('/tmp/cloak profile/DevToolsActivePort');
+        expect(deps.openApplication).toHaveBeenCalledWith('/Applications/Cloak Chromium.app', [
+            '--fingerprint=123',
+            '--password-store=basic',
+            '--use-mock-keychain',
+            '--user-data-dir=/tmp/cloak profile',
+            '--remote-debugging-address=127.0.0.1',
+            '--remote-debugging-port=0',
+            'about:blank',
+        ]);
+        expect(deps.connectOverCDP).toHaveBeenCalledWith('http://127.0.0.1:43123');
+        expect(deps.humanizeBrowser).toHaveBeenCalledWith(browser, expect.objectContaining({ humanize: true }));
+        expect(result).toBe(context);
+        await activateDarwinBackgroundContext(result);
+        expect(deps.activateApplication).toHaveBeenCalledWith('/Applications/Cloak Chromium.app');
+        await result.close();
+        expect(browser.close).toHaveBeenCalledOnce();
+        expect(deps.terminateProfile).toHaveBeenCalledWith(options.userDataDir);
+    });
+    it('fails immediately when the CDP port file misses its deadline', async () => {
+        await expect(waitForDevToolsPort('/missing/DevToolsActivePort', 0)).rejects.toThrow('Timed out waiting for background Chromium CDP endpoint');
+    });
+    it('terminates the launched profile when CDP connection fails', async () => {
+        const { browser } = fakeRuntime();
+        const deps = fakeDependencies(browser);
+        deps.connectOverCDP.mockRejectedValueOnce(new Error('connect failed'));
+        await expect(launchDarwinBackgroundPersistentContext(options, deps)).rejects.toThrow('connect failed');
+        expect(deps.terminateProfile).toHaveBeenCalledWith(options.userDataDir);
+    });
+});

package/dist/src/browser/runtime/local-cloak/provider.test.js

@@ -231,6 +231,42 @@ describe('LocalCloakRuntimeProvider', () => {
             .resolves.toMatchObject({ id: 'close', ok: true, data: { closed: created.page } });
         expect(pages[1].close).toHaveBeenCalled();
     });
+    it('does not bring selected tabs to front in background window mode', async () => {
+        const { provider, pages } = makeProviderWithFakePage();
+        const created = await provider.dispatch({ id: 'new', action: 'tabs', op: 'new', session: 'work', surface: 'browser', url: 'https://second.example/', profileId: 'default' });
+        await expect(provider.dispatch({
+            id: 'select',
+            action: 'tabs',
+            op: 'select',
+            session: 'work',
+            surface: 'browser',
+            page: created.page,
+            profileId: 'default',
+            windowMode: 'background',
+        })).resolves.toMatchObject({ id: 'select', ok: true });
+        expect(pages[1].bringToFront).not.toHaveBeenCalled();
+    });
+    it('does not bring bound tabs to front in background window mode', async () => {
+        const { provider, pages } = makeProviderWithFakePage();
+        const created = await provider.dispatch({ id: 'new', action: 'tabs', op: 'new', session: 'source', surface: 'browser', url: 'https://second.example/', profileId: 'default' });
+        await expect(provider.dispatch({
+            id: 'bind',
+            action: 'bind',
+            session: 'target',
+            surface: 'browser',
+            page: created.page,
+            profileId: 'default',
+            windowMode: 'background',
+        })).resolves.toMatchObject({ id: 'bind', ok: true });
+        expect(pages[1].bringToFront).not.toHaveBeenCalled();
+    });
+    it('brings bound tabs to front by default', async () => {
+        const { provider, pages } = makeProviderWithFakePage();
+        const created = await provider.dispatch({ id: 'new', action: 'tabs', op: 'new', session: 'source', surface: 'browser', url: 'https://second.example/', profileId: 'default' });
+        await expect(provider.dispatch({ id: 'bind', action: 'bind', session: 'target', surface: 'browser', page: created.page, profileId: 'default' }))
+            .resolves.toMatchObject({ id: 'bind', ok: true });
+        expect(pages[1].bringToFront).toHaveBeenCalledOnce();
+    });
     it('closes a window by page identity when command.page is provided', async () => {
         const { provider, pages } = makeProviderWithFakePage();
         const first = await provider.dispatch({ id: 'first', action: 'navigate', session: 'first', surface: 'browser', url: 'https://first.example/', profileId: 'default' });

package/dist/src/browser/runtime/local-cloak/session-manager.d.ts

@@ -1,6 +1,7 @@
 import type { BrowserContext, Page as PlaywrightPage } from 'playwright-core';
 import { launchPersistentContext as cloakLaunchPersistentContext } from 'cloakbrowser';
-import type { BrowserSurface, SiteSessionMode } from '../../protocol.js';
+import type { BrowserSurface, BrowserWindowMode, SiteSessionMode } from '../../protocol.js';
+import { activateDarwinBackgroundContext } from './darwin-background-launch.js';
 import { CloakNetworkCapture } from './network.js';
 export type LaunchPersistentContext = typeof cloakLaunchPersistentContext;
 export type RecoverLockedProfile = (userDataDir: string) => Promise<boolean>;
@@ -10,6 +11,7 @@ export interface SessionKeyInput {
     surface?: BrowserSurface;
     siteSession?: SiteSessionMode;
     idleTimeout?: number;
+    windowMode?: BrowserWindowMode;
     /** Discard the existing leased page (if any) and create a new one under the same lease. */
     freshPage?: boolean;
 }
@@ -34,13 +36,19 @@ export interface CloakTabInfo {
 export interface CloakSessionManagerOptions {
     baseDir?: string;
     launchPersistentContext?: LaunchPersistentContext;
+    launchBackgroundPersistentContext?: LaunchPersistentContext;
+    activateBackgroundContext?: typeof activateDarwinBackgroundContext;
     recoverLockedProfile?: RecoverLockedProfile;
+    platform?: NodeJS.Platform;
 }
 export declare function resolveLeaseKey(input: SessionKeyInput): string;
 export declare class CloakSessionManager {
     private readonly opts;
     readonly networkCapture: CloakNetworkCapture;
     private readonly launchPersistentContext;
+    private readonly launchBackgroundPersistentContext;
+    private readonly activateBackgroundContext;
+    private readonly platform;
     private readonly recoverLockedProfile;
     private readonly profiles;
     private readonly profileLaunches;
@@ -61,7 +69,7 @@ export declare class CloakSessionManager {
     newPage(input: SessionKeyInput & {
         url?: string;
     }): Promise<CloakPageLease>;
-    selectPage(input: Pick<SessionKeyInput, 'profileId'> & {
+    selectPage(input: Pick<SessionKeyInput, 'profileId' | 'windowMode'> & {
         pageId?: string;
         index?: number;
     }): Promise<CloakPageLease | null>;

package/dist/src/browser/runtime/local-cloak/session-manager.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import { execFile } from 'node:child_process';
 import { launchPersistentContext as cloakLaunchPersistentContext } from 'cloakbrowser';
+import { activateDarwinBackgroundContext, launchDarwinBackgroundPersistentContext } from './darwin-background-launch.js';
 import { normalizeProfileId, resolveCloakProfileDir } from './profiles.js';
 import { CloakNetworkCapture } from './network.js';
 let pageCounter = 0;
@@ -18,12 +19,18 @@ export class CloakSessionManager {
     opts;
     networkCapture = new CloakNetworkCapture();
     launchPersistentContext;
+    launchBackgroundPersistentContext;
+    activateBackgroundContext;
+    platform;
     recoverLockedProfile;
     profiles = new Map();
     profileLaunches = new Map();
     constructor(opts = {}) {
         this.opts = opts;
         this.launchPersistentContext = opts.launchPersistentContext ?? cloakLaunchPersistentContext;
+        this.launchBackgroundPersistentContext = opts.launchBackgroundPersistentContext ?? launchDarwinBackgroundPersistentContext;
+        this.activateBackgroundContext = opts.activateBackgroundContext ?? activateDarwinBackgroundContext;
+        this.platform = opts.platform ?? process.platform;
         this.recoverLockedProfile = opts.recoverLockedProfile ?? recoverLockedCloakProfile;
     }
     profileStatuses() {
@@ -43,7 +50,7 @@ export class CloakSessionManager {
         const session = requireSession(input.session);
         const surface = normalizeSurface(input.surface);
         const leaseKey = resolveLeaseKey(input);
-        const runtime = await this.getProfileRuntime(profileId);
+        const runtime = await this.getProfileRuntime(profileId, input.windowMode);
         const freshPage = input.freshPage === true;
         const existing = runtime.pages.get(leaseKey);
         if (existing && !pageIsClosed(existing.page) && !freshPage) {
@@ -130,7 +137,7 @@ export class CloakSessionManager {
         const profileId = normalizeProfileId(input.profileId);
         const session = requireSession(input.session);
         const surface = normalizeSurface(input.surface);
-        const runtime = await this.getProfileRuntime(profileId);
+        const runtime = await this.getProfileRuntime(profileId, input.windowMode);
         const page = await runtime.context.newPage();
         if (input.url) {
             await page.goto(input.url, { waitUntil: 'load' });
@@ -152,7 +159,10 @@ export class CloakSessionManager {
         if (!match)
             return null;
         const [leaseKey, entry] = match;
-        await entry.page.bringToFront?.().catch(() => { });
+        if (input.windowMode !== 'background') {
+            await entry.page.bringToFront?.().catch(() => { });
+            await this.activateBackgroundContext(runtime.context);
+        }
         runtime.selectedPageId = entry.pageId;
         runtime.lastSeenAt = Date.now();
         return { profileId, leaseKey, context: runtime.context, page: entry.page, pageId: entry.pageId };
@@ -183,7 +193,10 @@ export class CloakSessionManager {
         entry.siteSession = input.siteSession;
         entry.idleTimeout = input.idleTimeout;
         runtime.pages.set(canonicalKey, entry);
-        await entry.page.bringToFront?.().catch(() => { });
+        if (input.windowMode !== 'background') {
+            await entry.page.bringToFront?.().catch(() => { });
+            await this.activateBackgroundContext(runtime.context);
+        }
         this.refreshIdleTimer(runtime, canonicalKey, entry);
         runtime.selectedPageId = entry.pageId;
         runtime.lastSeenAt = Date.now();
@@ -235,14 +248,14 @@ export class CloakSessionManager {
         }
         this.profiles.clear();
     }
-    async getProfileRuntime(profileId) {
+    async getProfileRuntime(profileId, windowMode) {
         const existing = this.profiles.get(profileId);
         if (existing)
             return existing;
         const pending = this.profileLaunches.get(profileId);
         if (pending)
             return pending;
-        const launch = this.launchProfileRuntime(profileId);
+        const launch = this.launchProfileRuntime(profileId, windowMode);
         this.profileLaunches.set(profileId, launch);
         try {
             return await launch;
@@ -251,7 +264,7 @@ export class CloakSessionManager {
             this.profileLaunches.delete(profileId);
         }
     }
-    async launchProfileRuntime(profileId) {
+    async launchProfileRuntime(profileId, windowMode) {
         const userDataDir = resolveCloakProfileDir(profileId, { baseDir: this.opts.baseDir });
         fs.mkdirSync(userDataDir, { recursive: true });
         const launchOptions = {
@@ -259,14 +272,17 @@ export class CloakSessionManager {
             headless: false,
             humanize: true,
         };
+        const launchPersistentContext = this.platform === 'darwin' && windowMode === 'background'
+            ? this.launchBackgroundPersistentContext
+            : this.launchPersistentContext;
         let context;
         try {
-            context = await this.launchPersistentContext(launchOptions);
+            context = await launchPersistentContext(launchOptions);
         }
         catch (err) {
             if (!isProfileAlreadyInUseError(err) || !(await this.recoverLockedProfile(userDataDir)))
                 throw err;
-            context = await this.launchPersistentContext(launchOptions);
+            context = await launchPersistentContext(launchOptions);
         }
         const runtime = { context, pages: new Map(), lastSeenAt: Date.now() };
         this.profiles.set(profileId, runtime);

package/dist/src/browser/runtime/local-cloak/session-manager.test.js

@@ -42,6 +42,42 @@ describe('CloakSessionManager', () => {
         expect(launchPersistentContext).toHaveBeenCalledTimes(1);
         expect(launchPersistentContext.mock.calls[0][0]).toMatchObject({ headless: false });
     });
+    it.each([
+        { platform: 'darwin', windowMode: 'background', backgroundCalls: 1, normalCalls: 0 },
+        { platform: 'darwin', windowMode: 'foreground', backgroundCalls: 0, normalCalls: 1 },
+        { platform: 'linux', windowMode: 'background', backgroundCalls: 0, normalCalls: 1 },
+    ])('routes a cold $platform $windowMode launch', async ({ platform, windowMode, backgroundCalls, normalCalls }) => {
+        const launched = fakeContext();
+        const launchPersistentContext = vi.fn().mockResolvedValue(launched.context);
+        const launchBackgroundPersistentContext = vi.fn().mockResolvedValue(launched.context);
+        const manager = new CloakSessionManager({
+            baseDir: '/tmp/webcmd-test',
+            platform,
+            launchPersistentContext,
+            launchBackgroundPersistentContext,
+        });
+        await manager.getPage({ profileId: 'default', session: 'work', surface: 'browser', windowMode });
+        expect(launchBackgroundPersistentContext).toHaveBeenCalledTimes(backgroundCalls);
+        expect(launchPersistentContext).toHaveBeenCalledTimes(normalCalls);
+    });
+    it('reactivates a background-launched context for foreground tab selection', async () => {
+        const launched = fakeContext();
+        const activateBackgroundContext = vi.fn().mockResolvedValue(undefined);
+        const manager = new CloakSessionManager({
+            baseDir: '/tmp/webcmd-test',
+            platform: 'darwin',
+            launchBackgroundPersistentContext: vi.fn().mockResolvedValue(launched.context),
+            activateBackgroundContext,
+        });
+        const lease = await manager.getPage({
+            profileId: 'default',
+            session: 'work',
+            surface: 'browser',
+            windowMode: 'background',
+        });
+        await manager.selectPage({ profileId: 'default', pageId: lease.pageId, windowMode: 'foreground' });
+        expect(activateBackgroundContext).toHaveBeenCalledWith(launched.context);
+    });
     it('coalesces concurrent persistent context launches for the same profile', async () => {
         const launched = fakeContext();
         let resolveLaunch;

package/dist/src/browser/target-resolver.d.ts

@@ -77,6 +77,7 @@ export declare function resolveTargetJs(ref: string, opts?: ResolveOptions): str
  */
 export declare function boundingRectResolvedJs(opts?: {
     skipScroll?: boolean;
+    forClick?: boolean;
 }): string;
 /**
  * Generate JS for click that uses the unified resolver.

package/dist/src/browser/target-resolver.js

@@ -282,18 +282,113 @@ export function resolveTargetJs(ref, opts = {}) {
  */
 export function boundingRectResolvedJs(opts = {}) {
     const shouldScroll = opts.skipScroll ? 'false' : 'true';
+    const forClick = opts.forClick ? 'true' : 'false';
     return `
     (() => {
       const el = window.__resolved;
       if (!el) throw new Error('No resolved element');
       if (${shouldScroll}) el.scrollIntoView({ behavior: 'instant', block: 'center' });
-      const rect = el.getBoundingClientRect();
+
+      const FOR_CLICK = ${forClick};
+      // hover()/dblClick() want the plain element centre — the retarget + hit-test
+      // below are click-only so those actions keep their original behaviour.
+      if (!FOR_CLICK) {
+        const r0 = el.getBoundingClientRect();
+        return {
+          x: Math.round(r0.left + r0.width / 2),
+          y: Math.round(r0.top + r0.height / 2),
+          w: Math.round(r0.width),
+          h: Math.round(r0.height),
+          visible: Math.round(r0.width) > 0 && Math.round(r0.height) > 0,
+        };
+      }
+
+      // Does this node OWN a click handler? Deliberately excludes cursor:pointer,
+      // which is an *inherited* CSS property — an <svg> icon inside a clickable
+      // <div> inherits the pointer cursor but owns no handler, so cursor can't
+      // decide whether a node is the real click target. See issue #2071.
+      const ownsClickHandler = (node) => {
+        if (!node || node.nodeType !== 1) return false;
+        const tag = node.tagName.toLowerCase();
+        if (['a','button','input','select','textarea','label','summary'].includes(tag)) return true;
+        const role = node.getAttribute && node.getAttribute('role');
+        if (role && ['button','link','menuitem','menuitemcheckbox','menuitemradio','tab','option','checkbox','radio','switch'].includes(role)) return true;
+        if (typeof node.onclick === 'function') return true;
+        if (node.hasAttribute && (node.hasAttribute('onclick') || node.hasAttribute('jsaction'))) return true;
+        try {
+          for (const k in node) {
+            if (k.charCodeAt(0) === 95 && (k.indexOf('__reactProps$') === 0 || k.indexOf('__reactEventHandlers$') === 0)) {
+              const p = node[k];
+              if (p && (p.onClick || p.onMouseDown || p.onMouseUp)) return true;
+            }
+          }
+        } catch (e) {}
+        return false;
+      };
+      // A retarget destination just needs to look clickable; here cursor:pointer
+      // IS a useful signal (the ancestor is where it was set).
+      const isClickableAncestor = (node) => {
+        if (ownsClickHandler(node)) return true;
+        try { return window.getComputedStyle(node).cursor === 'pointer'; } catch (e) { return false; }
+      };
+
+      // #2071: if the resolved node owns no click handler but a nearby ancestor
+      // is clickable, aim at that ancestor so the handler fires.
+      let target = el;
+      let retargeted = false;
+      if (!ownsClickHandler(el)) {
+        let a = el.parentElement, hops = 0;
+        while (a && hops < 4) {
+          if (isClickableAncestor(a)) { target = a; retargeted = true; break; }
+          a = a.parentElement; hops++;
+        }
+      }
+
+      const rect = target.getBoundingClientRect();
       const w = Math.round(rect.width);
       const h = Math.round(rect.height);
-      const x = Math.round(rect.left + rect.width / 2);
-      const y = Math.round(rect.top + rect.height / 2);
+      let x = Math.round(rect.left + rect.width / 2);
+      let y = Math.round(rect.top + rect.height / 2);
       const visible = w > 0 && h > 0;
-      return { x, y, w, h, visible };
+
+      // #2076: verify the click point actually lands on the target. A trusted
+      // CDP click hit-tests at (x,y) and delivers the event to whatever is
+      // topmost there — an overlay/sibling can silently swallow it. Classify:
+      //   'target'   — the point is the target or a light-DOM descendant.
+      //   'ancestor' — the point is an ANCESTOR of the target. This is the
+      //                open-shadow-DOM case (elementFromPoint returns the shadow
+      //                *host*, not the shadow content) and the "point sits over
+      //                the target's own wrapper background" case. In both a CDP
+      //                click at (x,y) still reaches the target — CDP hit-testing
+      //                pierces shadow roots, and light-DOM clicks bubble up — so
+      //                it is trustworthy, unlike an unrelated overlay.
+      //   'other'    — an unrelated element covers the point (the real overlay
+      //                bug); the caller then dispatches a direct DOM click.
+      const hitClass = (px, py) => {
+        let at = null;
+        try { at = document.elementFromPoint(px, py); } catch (e) { return 'none'; }
+        if (!at) return 'none';
+        if (at === target || target.contains(at)) return 'target';
+        if (at.contains && at.contains(target)) return 'ancestor';
+        return 'other';
+      };
+      let hit = visible ? hitClass(x, y) : 'none';
+      if (visible && hit !== 'target' && hit !== 'ancestor') {
+        const cands = [
+          [rect.left + rect.width * 0.5, rect.top + rect.height * 0.25],
+          [rect.left + rect.width * 0.25, rect.top + rect.height * 0.5],
+          [rect.left + rect.width * 0.75, rect.top + rect.height * 0.5],
+          [rect.left + rect.width * 0.5, rect.top + rect.height * 0.75],
+          [rect.left + 3, rect.top + 3],
+          [rect.right - 3, rect.bottom - 3],
+        ];
+        for (const c of cands) {
+          const px = Math.round(c[0]), py = Math.round(c[1]);
+          const hc = hitClass(px, py);
+          if (hc === 'target' || hc === 'ancestor') { x = px; y = py; hit = hc; break; }
+        }
+      }
+      return { x, y, w, h, visible, hit, retargeted };
     })()
   `;
 }