@agentrhq/webcmd 0.3.0 → 0.3.1

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/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, 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>;
@@ -35,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;

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,8 +159,10 @@ export class CloakSessionManager {
         if (!match)
             return null;
         const [leaseKey, entry] = match;
-        if (input.windowMode !== 'background')
+        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 };
@@ -184,8 +193,10 @@ export class CloakSessionManager {
         entry.siteSession = input.siteSession;
         entry.idleTimeout = input.idleTimeout;
         runtime.pages.set(canonicalKey, entry);
-        if (input.windowMode !== 'background')
+        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();
@@ -237,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;
@@ -253,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 = {
@@ -261,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 };
     })()
   `;
 }

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

@@ -1,5 +1,145 @@
 import { describe, expect, it } from 'vitest';
-import { resolveTargetJs } from './target-resolver.js';
+import { boundingRectResolvedJs, resolveTargetJs } from './target-resolver.js';
+/**
+ * Build a fake element usable by the generated boundingRectResolvedJs. Rects are
+ * {left,top,width,height}; getBoundingClientRect derives right/bottom.
+ */
+function makeEl(opts) {
+    const attrs = opts.attrs ?? {};
+    const el = {
+        nodeType: 1,
+        tagName: opts.tag.toUpperCase(),
+        _cursor: opts.cursor ?? 'auto',
+        onclick: opts.onclick ? () => { } : null,
+        parentElement: null,
+        children: [],
+        scrollIntoView() { },
+        getBoundingClientRect() {
+            const r = opts.rect;
+            return { left: r.left, top: r.top, width: r.width, height: r.height, right: r.left + r.width, bottom: r.top + r.height };
+        },
+        getAttribute(k) { return k === 'role' ? (opts.role ?? null) : (attrs[k] ?? null); },
+        hasAttribute(k) { return k === 'role' ? opts.role != null : k in attrs; },
+        contains(other) {
+            if (other === el)
+                return true;
+            for (const c of el.children) {
+                if (c === other || (c.contains && c.contains(other)))
+                    return true;
+            }
+            return false;
+        },
+    };
+    return el;
+}
+/** Resolve computed cursor with CSS inheritance, so the fake DOM matches the
+ * browser: a child with no own cursor inherits its ancestors' pointer cursor. */
+function inheritedCursor(node) {
+    let n = node;
+    while (n) {
+        if (n._cursor && n._cursor !== 'auto')
+            return n._cursor;
+        n = n.parentElement;
+    }
+    return 'auto';
+}
+/** Run the generated boundingRectResolvedJs against a fake DOM. */
+function runRect(resolved, elementAt) {
+    const fakeWindow = { __resolved: resolved, getComputedStyle: (n) => ({ cursor: inheritedCursor(n) }) };
+    const fakeDoc = { elementFromPoint: (x, y) => elementAt(x, y) };
+    const js = boundingRectResolvedJs({ skipScroll: true, forClick: true });
+    // js is an IIFE expression `(() => {...})()`; arrow captures window/document
+    // params. Wrap in parens so ASI doesn't turn `return\n(` into `return;`.
+    return new Function('window', 'document', 'return (' + js + ')')(fakeWindow, fakeDoc);
+}
+describe('boundingRectResolvedJs runtime behavior', () => {
+    it('reports hit=target and no retarget when the centre lands on the element', () => {
+        const btn = makeEl({ tag: 'button', rect: { left: 0, top: 0, width: 100, height: 40 } });
+        const out = runRect(btn, () => btn);
+        expect(out.visible).toBe(true);
+        expect(out.hit).toBe('target');
+        expect(out.retargeted).toBe(false);
+        expect(out.x).toBe(50);
+        expect(out.y).toBe(20);
+    });
+    it('retargets an <svg> icon to its clickable <div> ancestor (#2071)', () => {
+        const div = makeEl({ tag: 'div', rect: { left: 0, top: 0, width: 80, height: 80 }, cursor: 'pointer' });
+        const svg = makeEl({ tag: 'svg', rect: { left: 20, top: 20, width: 40, height: 40 } });
+        svg.parentElement = div;
+        div.children = [svg];
+        // elementFromPoint at the div centre returns the svg (topmost paint), which
+        // is contained by div → hit=target on the retargeted element.
+        const out = runRect(svg, () => svg);
+        expect(out.retargeted).toBe(true);
+        expect(out.hit).toBe('target');
+        // measured rect is the div's (80x80 → centre 40,40), not the svg's
+        expect(out.w).toBe(80);
+        expect(out.x).toBe(40);
+        expect(out.y).toBe(40);
+    });
+    it('retargets to an ancestor that owns an onclick handler even without cursor:pointer (#2071)', () => {
+        const div = makeEl({ tag: 'div', rect: { left: 0, top: 0, width: 60, height: 60 }, onclick: true });
+        const svg = makeEl({ tag: 'svg', rect: { left: 10, top: 10, width: 40, height: 40 } });
+        svg.parentElement = div;
+        div.children = [svg];
+        const out = runRect(svg, () => svg);
+        expect(out.retargeted).toBe(true);
+        expect(out.w).toBe(60);
+    });
+    it('does not retarget when no ancestor is clickable', () => {
+        const wrap = makeEl({ tag: 'div', rect: { left: 0, top: 0, width: 60, height: 60 } });
+        const span = makeEl({ tag: 'span', rect: { left: 10, top: 10, width: 40, height: 40 } });
+        span.parentElement = wrap;
+        wrap.children = [span];
+        const out = runRect(span, () => span);
+        expect(out.retargeted).toBe(false);
+        expect(out.w).toBe(40);
+    });
+    it('treats an ancestor hit as trustworthy (open shadow-DOM host / own wrapper) and keeps the centre', () => {
+        // elementFromPoint returns a light-DOM ancestor (e.g. the shadow host) that
+        // contains the target — CDP pierces to the target, so this must NOT fall back.
+        const host = makeEl({ tag: 'div', rect: { left: 0, top: 0, width: 120, height: 60 } });
+        const btn = makeEl({ tag: 'button', rect: { left: 10, top: 10, width: 100, height: 40 } });
+        btn.parentElement = host;
+        host.children = [btn];
+        const out = runRect(btn, () => host); // topmost at every point is the host (ancestor)
+        expect(out.hit).toBe('ancestor');
+        expect(out.retargeted).toBe(false);
+        // centre kept — no wasted probing when the hit is already trustworthy
+        expect(out.x).toBe(60);
+        expect(out.y).toBe(30);
+    });
+    it('hover/dblClick mode (forClick omitted) returns the plain element centre with no hit-test', () => {
+        const div = makeEl({ tag: 'div', rect: { left: 0, top: 0, width: 80, height: 80 }, cursor: 'pointer' });
+        const svg = makeEl({ tag: 'svg', rect: { left: 20, top: 20, width: 40, height: 40 } });
+        svg.parentElement = div;
+        div.children = [svg];
+        const js = boundingRectResolvedJs({ skipScroll: true }); // no forClick
+        const out = new Function('window', 'document', 'return (' + js + ')')({ __resolved: svg, getComputedStyle: () => ({ cursor: 'pointer' }) }, { elementFromPoint: () => div });
+        // no retarget, no hit field — svg's own centre (40,40), unchanged behavior
+        expect(out.hit).toBeUndefined();
+        expect(out.retargeted).toBeUndefined();
+        expect(out.x).toBe(40);
+        expect(out.y).toBe(40);
+        expect(out.w).toBe(40);
+    });
+    it('reports hit=other when an overlay covers the element and no probe point lands (#2076)', () => {
+        const btn = makeEl({ tag: 'button', rect: { left: 0, top: 0, width: 100, height: 40 } });
+        const overlay = makeEl({ tag: 'div', rect: { left: 0, top: 0, width: 1000, height: 1000 } });
+        const out = runRect(btn, () => overlay); // every point hits the overlay
+        expect(out.hit).toBe('other');
+        expect(out.retargeted).toBe(false);
+    });
+    it('recovers a hitting point by probing when the centre is occluded but a corner is clear (#2076)', () => {
+        const btn = makeEl({ tag: 'button', rect: { left: 0, top: 0, width: 100, height: 40 } });
+        const overlay = makeEl({ tag: 'div', rect: { left: 40, top: 15, width: 20, height: 10 } });
+        // Centre (50,20) is covered by the overlay; the top-left inset (3,3) is clear.
+        const out = runRect(btn, (x, y) => (x === 50 && y === 20 ? overlay : btn));
+        expect(out.hit).toBe('target');
+        // the returned point moved off the occluded centre (50,20)
+        expect(out.x === 50 && out.y === 20).toBe(false);
+    });
+});
 /**
  * Tests for the target resolver JS generator.
  *

package/dist/src/build-manifest.d.ts

@@ -22,6 +22,7 @@
  *     amount) to confirm an intentional removal.
  */
 import type { ManifestEntry } from './manifest-types.js';
+import { type HostedBrowserCommandContract } from './hosted/contract.js';
 export type { ManifestEntry } from './manifest-types.js';
 /**
  * Thrown by `loadManifestEntries` when an adapter file looks like a CLI
@@ -66,6 +67,11 @@ export declare function loadManifestEntries(filePath: string, site: string, impo
 export declare function scanClisDir(clisDir: string, importer?: (moduleHref: string) => Promise<unknown>): Promise<BuildManifestResult>;
 export declare function buildManifest(): Promise<BuildManifestResult>;
 export declare function serializeManifest(manifest: ManifestEntry[]): string;
+export interface BuildManifestArtifacts {
+    manifestJson: string;
+    hostedContractJson: string;
+}
+export declare function buildManifestArtifacts(entries: ManifestEntry[], packageVersion: string, browserCatalog: readonly HostedBrowserCommandContract[]): BuildManifestArtifacts;
 /**
  * Metadata audit: every positional arg must carry a non-empty `help` string.
  *

package/dist/src/build-manifest.js

@@ -28,10 +28,12 @@ import { getErrorMessage } from './errors.js';
 import { fullName, getRegistry } from './registry.js';
 import { findPackageRoot, getCliManifestPath } from './package-paths.js';
 import { isRecord } from './utils.js';
+import { buildHostedContract, serializeHostedContract, } from './hosted/contract.js';
 const PACKAGE_ROOT = findPackageRoot(fileURLToPath(import.meta.url));
 const CLIS_DIR = path.join(PACKAGE_ROOT, 'clis');
 // Write manifest next to clis/ so both dev and installed runtime can find it.
 const OUTPUT = getCliManifestPath(CLIS_DIR);
+const HOSTED_CONTRACT_OUTPUT = path.join(PACKAGE_ROOT, 'hosted-contract.json');
 // Module is treated as a CLI command source if it either:
 //   1. Calls `cli(...)` directly (the common case), or
 //   2. Calls a factory `make<Pascal>Command(...)` from clis/_shared/ that
@@ -64,6 +66,7 @@ function toManifestArgs(args) {
         positional: arg.positional || undefined,
         help: arg.help ?? '',
         choices: arg.choices,
+        file: arg.file,
     }));
 }
 function toModulePath(filePath, site) {
@@ -211,6 +214,12 @@ export async function buildManifest() {
 export function serializeManifest(manifest) {
     return `${JSON.stringify(manifest, null, 2)}\n`;
 }
+export function buildManifestArtifacts(entries, packageVersion, browserCatalog) {
+    return {
+        manifestJson: serializeManifest(entries),
+        hostedContractJson: serializeHostedContract(buildHostedContract(entries, browserCatalog, packageVersion)),
+    };
+}
 export function findManifestMetadataIssues(entries) {
     const issues = [];
     for (const entry of entries) {
@@ -330,9 +339,17 @@ async function main() {
             process.exit(1);
         }
     }
+    const packagePath = path.resolve(PACKAGE_ROOT, 'package.json');
+    const packageMetadata = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+    if (typeof packageMetadata.name !== 'string' || typeof packageMetadata.version !== 'string') {
+        throw new Error(`Package name and version are required in ${packagePath}`);
+    }
+    const artifacts = buildManifestArtifacts(entries, packageMetadata.version, []);
     fs.mkdirSync(path.dirname(OUTPUT), { recursive: true });
-    fs.writeFileSync(OUTPUT, serializeManifest(entries));
+    fs.writeFileSync(OUTPUT, artifacts.manifestJson);
+    fs.writeFileSync(HOSTED_CONTRACT_OUTPUT, artifacts.hostedContractJson);
     console.log(`✅ Manifest compiled: ${entries.length} entries → ${OUTPUT}`);
+    console.log(`✅ Hosted contract compiled: ${packageMetadata.name}@${packageMetadata.version} → ${HOSTED_CONTRACT_OUTPUT}`);
     // Restore executable permissions on bin entries.
     // tsc does not preserve the +x bit, so after a clean rebuild the CLI
     // entry-point loses its executable permission, causing "Permission denied".