@reticlehq/server 3.5.0 → 3.7.0

package/dist/portal/pool/browser-pool.js

@@ -10,7 +10,9 @@
  * the thin Playwright adapter that satisfies these interfaces lives separately.
  */
 import { unreachableUrlIn } from '@reticlehq/core';
-import { seedStorageInto } from './storage-seed.js';
+import { seedStorageInto, targetOriginOf } from './storage-seed.js';
+import { installLeaseMarker, leaseMarkerOf } from './lease-marker-stamp.js';
+import { grantLeasePermissions, NOTIFICATION_PERMISSION_READ, NOTIFICATION_READ_TIMEOUT_MS, } from './context-permissions.js';
 /** Default lease time-to-live: a lease untouched for this long is presumed orphaned and reclaimed. */
 export const DEFAULT_LEASE_TTL_MS = 5 * 60_000;
 /** Default cap on how long a lease's initial navigation may take before it fails (frees the slot). */
@@ -20,20 +22,29 @@ const DEFAULT_NAV_TIMEOUT_MS = 30_000;
  * this is slack for a burst sweep, not a history.
  */
 const MAX_REMEMBERED_REAPED_LEASES = 64;
+/** What a headed lease is refused with where no window can be opened. */
+export const NO_HEADED_BROWSER = 'no headed browser can be opened here';
 /**
- * Owns a single browser and leases isolated contexts out of it, capped at `maxContexts`.
+ * What an acquire that asked for an init script is refused with when the page cannot run one.
+ *
+ * A refusal rather than a lease: the caller asked for a stub of the bindings a desktop shell
+ * injects, and a tab opened without it would throw in the app's view and read as a broken app.
+ */
+const INIT_SCRIPT_UNSUPPORTED = 'Init script failed: this page does not support init scripts, so the requested stub would not be there';
+/**
+ * Owns a headless browser (and, when asked, a headed one) and leases isolated contexts out of them,
+ * capped at `maxContexts` across both.
  * Not exported as a singleton — the daemon owns one instance.
  */
 export class BrowserPool {
-    #launch;
     #max;
     #genId;
     #now;
     #ttl;
     #zeroInstall;
     #navTimeout;
-    #browser;
-    #launching;
+    #headless;
+    #headed;
     #closed = false;
     /** Leases reclaimed for going stale — see reapedLeaseCount(). */
     #reapedLeases = 0;
@@ -65,7 +76,8 @@ export class BrowserPool {
     constructor(launch, opts) {
         if (opts.maxContexts < 1)
             throw new Error('maxContexts must be >= 1');
-        this.#launch = launch;
+        this.#headless = { launch, headed: false };
+        this.#headed = { launch: opts.launchHeaded, headed: true };
         this.#max = opts.maxContexts;
         this.#genId = opts.genSessionId;
         this.#now = opts.now ?? (() => Date.now());
@@ -93,16 +105,22 @@ export class BrowserPool {
         return [...this.#active.keys()];
     }
     /**
-     * The public session id of an active lease on this origin, if we already hold one.
+     * The public session id of an active lease on this origin that `owner` took, if there is one.
      *
      * The lease TOOL reuses that id instead of minting a second context: a second acquire on the same
-     * origin used to leave both tabs connected and poison default session resolution (#600). The pool's
-     * own `acquire` still mints — the parallel suite needs isolation on purpose.
+     * origin used to leave both tabs connected and poison default session resolution (#600). Only the
+     * caller that took the lease gets it back: handing it to whoever asked put two agents in one tab,
+     * each one's verdicts resting on the other's actions (#1226). A caller with no owner cannot be told
+     * apart from another, so it always gets its own. The pool's own `acquire` still mints.
      *
      * Prefers the alias the agent was given, when the app registered under its own name.
      */
-    leaseIdOnOrigin(origin) {
+    leaseIdOnOrigin(origin, owner) {
+        if (owner === undefined)
+            return undefined;
         for (const [leaseId, lease] of this.#active) {
+            if (lease.owner !== owner)
+                continue;
             let leaseOrigin;
             try {
                 leaseOrigin = new URL(lease.url).origin;
@@ -172,6 +190,15 @@ export class BrowserPool {
     #leaseIdOf(sessionId) {
         return this.#active.has(sessionId) ? sessionId : (this.#aliases.get(sessionId) ?? sessionId);
     }
+    /**
+     * Whether `sessionId` is a live lease that `owner` may let go of: one it took, or one taken by a
+     * caller with no id, which cannot be told apart from it. Another agent's lease is never this
+     * caller's to close (#1226).
+     */
+    heldBy(sessionId, owner) {
+        const lease = this.#active.get(this.#leaseIdOf(sessionId));
+        return lease !== undefined && (lease.owner === undefined || lease.owner === owner);
+    }
     /** Mark a lease as still in use (called on agent activity) so the reaper doesn't reclaim it. */
     touch(sessionId) {
         const lease = this.#active.get(this.#leaseIdOf(sessionId));
@@ -206,6 +233,28 @@ export class BrowserPool {
             return undefined;
         }
     }
+    /** The URL a lease was opened on — the one that carries its Reticle identity. */
+    leaseUrl(sessionId) {
+        return this.#active.get(this.#leaseIdOf(sessionId))?.url;
+    }
+    /**
+     * Navigate a leased page through the browser. For a lease whose page has no SDK to take the
+     * command — a navigate to an image left the lease unreachable, and the next navigate answered "no
+     * connected session". False when this is not a lease or the page would not go.
+     */
+    async gotoLease(sessionId, url, timeoutMs) {
+        const lease = this.#active.get(this.#leaseIdOf(sessionId));
+        if (lease === undefined)
+            return false;
+        this.touch(sessionId);
+        try {
+            await lease.page.goto(url, timeoutMs === undefined ? {} : { timeoutMs });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     /**
      * Move the real pointer on a leased page, or false when this session is not a lease or cannot
      * hover. Same optional-capability contract as screenshotLease: absence must read as "could not
@@ -266,6 +315,52 @@ export class BrowserPool {
             return false;
         }
     }
+    /** What a lease was granted when it opened, or undefined for a session that is not a lease. */
+    permissionsOf(sessionId) {
+        return this.#active.get(this.#leaseIdOf(sessionId))?.permissions;
+    }
+    /**
+     * Whether this lease's page runs a caller-supplied init script — a stub of the bindings a desktop
+     * shell injects. Alias-resolved like every agent-facing lookup, and false for any session that is
+     * not a lease with a stub, so a verdict can say when it was measured against a fake shell.
+     */
+    stubInstalled(sessionId) {
+        return this.#active.get(this.#leaseIdOf(sessionId))?.hostStub !== undefined;
+    }
+    /**
+     * The init script this lease installed, or undefined when it runs none. Alias-resolved like
+     * `stubInstalled`. The lease tool compares it to the script a caller asks for: the same text means
+     * the held tab already is what was asked for, so it is reused rather than released and remade.
+     */
+    hostStubScript(sessionId) {
+        return this.#active.get(this.#leaseIdOf(sessionId))?.hostStubScript;
+    }
+    /**
+     * What the leased page's `Notification.permission` says, or undefined when it cannot be asked.
+     *
+     * Read back rather than inferred from the grant, because the headless shell answers `denied`
+     * after a notifications grant — see context-permissions.ts. Bounded, so a page that never answers
+     * reads as "could not ask" instead of holding the caller.
+     */
+    async notificationPermission(sessionId) {
+        const lease = this.#active.get(this.#leaseIdOf(sessionId));
+        if (lease === undefined || lease.page.evaluate === undefined)
+            return undefined;
+        let timer;
+        const gaveUp = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(undefined), NOTIFICATION_READ_TIMEOUT_MS);
+        });
+        try {
+            const value = await Promise.race([lease.page.evaluate(NOTIFICATION_PERMISSION_READ), gaveUp]);
+            return 'string' === typeof value ? value : undefined;
+        }
+        catch {
+            return undefined;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
     async sweepExpired() {
         const now = this.#now();
         const expired = [...this.#active.entries()]
@@ -314,6 +409,10 @@ export class BrowserPool {
     async acquire(url, opts = {}) {
         if (this.#closed)
             throw new Error('browser pool is shut down');
+        const slot = true === opts.headed ? this.#headed : this.#headless;
+        // Refused before a slot is claimed, so a refusal never holds one.
+        if (slot.launch === undefined)
+            throw new Error(NO_HEADED_BROWSER);
         // #waitForSlot claims the slot synchronously (bumps #occupied) before returning, so the cap holds
         // even when many acquires race through the gate in the same tick.
         await this.#waitForSlot(opts.signal);
@@ -322,9 +421,22 @@ export class BrowserPool {
         let pending;
         let pendingDialogMessage;
         try {
-            const browser = await this.#ensureBrowser();
-            context = await browser.newContext();
+            const browser = await this.#ensureBrowser(slot);
+            context = await browser.newContext(true === opts.ignoreHTTPSErrors ? { ignoreHTTPSErrors: true } : undefined);
+            if (opts.permissions !== undefined)
+                await grantLeasePermissions(context, opts.permissions, url);
             const page = await context.newPage();
+            // A caller-supplied init script is a stub of the bindings a desktop shell injects, and it has
+            // to exist before the app's first module runs. Installed here — before goto — so the very
+            // first document gets it, and kept for the lease (see hostStub) so a reload keeps it too.
+            let hostStub;
+            if (opts.initScript !== undefined) {
+                const added = await page.addInitScript?.(opts.initScript);
+                if (added === undefined || 'function' !== typeof added.dispose) {
+                    throw new Error(INIT_SCRIPT_UNSUPPORTED);
+                }
+                hostStub = added;
+            }
             // Per-page crash isolation: if THIS renderer dies, reclaim only this lease — the shared browser
             // and every other agent's context keep running. (A full browser death is handled by #onCrash.)
             page.onCrash(() => {
@@ -354,6 +466,10 @@ export class BrowserPool {
                     pendingDialogMessage = dialog.message;
                 void dialog.dismiss();
             });
+            const marker = leaseMarkerOf(url);
+            if (marker?.session === sessionId) {
+                await installLeaseMarker(page, sessionId, targetOriginOf(url), marker.project);
+            }
             let seedHandle;
             let checkSeedError;
             if (opts.seedStorage !== undefined) {
@@ -375,8 +491,11 @@ export class BrowserPool {
             // #occupied. Registering the lease now would resurrect a dead entry against a crashed browser with
             // the slot count out of sync (drifting below #active.size, eventually exceeding the cap). If we're
             // no longer the live browser, bail — the catch below closes the context and returns the slot.
-            if (this.#browser !== browser)
+            if (slot.browser !== browser)
                 throw new Error('browser crashed during navigation');
+            // Foreground it: a page opened beside other tabs can start hidden (#1351). Best-effort — a tab
+            // that stays hidden is reported by name at the lease, which failing here would lose.
+            await page.bringToFront?.().catch(() => undefined);
             let navStatus;
             if (null !== navRes && 'object' === typeof navRes && 'status' in navRes) {
                 const s = navRes.status;
@@ -395,12 +514,19 @@ export class BrowserPool {
                 }
             }
             this.#active.set(sessionId, {
+                headed: slot.headed,
                 context,
                 page,
                 url,
+                ...(opts.owner === undefined ? {} : { owner: opts.owner }),
                 touchedAt: this.#now(),
+                permissions: opts.permissions ?? [],
+                ignoresHTTPSErrors: true === opts.ignoreHTTPSErrors,
                 ...(pending === undefined ? {} : { dialFailureUrl: pending }),
                 ...(pendingDialogMessage === undefined ? {} : { lastDialogMessage: pendingDialogMessage }),
+                ...(hostStub === undefined || opts.initScript === undefined
+                    ? {}
+                    : { hostStub, hostStubScript: opts.initScript }),
             });
             return {
                 sessionId,
@@ -450,17 +576,19 @@ export class BrowserPool {
         await Promise.all(contexts.map((c) => c.close().catch(() => undefined)));
         // If a launch is in flight, await it so we can close the resulting browser — otherwise it
         // resolves after shutdown returns and the Chromium process is orphaned (hundreds of MB leaked).
-        const inflight = this.#launching;
-        if (inflight !== undefined) {
-            const launched = await inflight.catch(() => undefined);
-            if (launched !== undefined && launched !== this.#browser) {
-                await launched.close().catch(() => undefined);
+        for (const slot of [this.#headless, this.#headed]) {
+            const inflight = slot.launching;
+            if (inflight !== undefined) {
+                const launched = await inflight.catch(() => undefined);
+                if (launched !== undefined && launched !== slot.browser) {
+                    await launched.close().catch(() => undefined);
+                }
             }
+            const browser = slot.browser;
+            slot.browser = undefined;
+            if (browser !== undefined)
+                await browser.close().catch(() => undefined);
         }
-        const browser = this.#browser;
-        this.#browser = undefined;
-        if (browser !== undefined)
-            await browser.close().catch(() => undefined);
         for (const waiter of this.#waiters.splice(0))
             waiter();
     }
@@ -475,6 +603,9 @@ export class BrowserPool {
             if (leaseId === sessionId)
                 this.#aliases.delete(registered);
         }
+        // Disposed with the lease, which is what "for that lease only" means. Best-effort: a context
+        // that is already gone (a crash) makes the disposal moot, not a reason to fail the release.
+        await lease.hostStub?.dispose().catch(() => undefined);
         await lease.context.close().catch(() => undefined);
         this.#releaseSlot();
     }
@@ -532,38 +663,60 @@ export class BrowserPool {
         if (next !== undefined)
             next();
     }
-    async #ensureBrowser() {
+    async #ensureBrowser(slot) {
         if (this.#closed)
             throw new Error('browser pool is shut down');
-        if (this.#browser !== undefined && this.#browser.isConnected())
-            return this.#browser;
+        if (slot.browser !== undefined && slot.browser.isConnected())
+            return slot.browser;
+        const launch = slot.launch;
+        if (launch === undefined)
+            throw new Error(NO_HEADED_BROWSER);
         // De-dupe concurrent launches: the first acquire to find no browser starts one; the rest await it.
-        if (this.#launching === undefined) {
+        if (slot.launching === undefined) {
             // The in-flight promise MUST be cleared on failure as well as success. It used to be cleared only
             // in the success callback, so the first failed launch — Chromium not downloaded, a transient
             // EAGAIN — left a permanently rejected promise here, and every subsequent acquire for the daemon's
             // lifetime re-returned that same stale rejection. Running `npx playwright install` did not help;
             // only restarting the daemon did. A retry must be allowed to actually retry.
-            this.#launching = this.#launch()
+            slot.launching = launch()
                 .then((b) => {
-                b.onDisconnected(() => this.#onCrash(b));
-                this.#browser = b;
+                b.onDisconnected(() => this.#onCrash(slot, b));
+                slot.browser = b;
                 return b;
             })
                 .finally(() => {
-                this.#launching = undefined;
+                slot.launching = undefined;
             });
         }
-        return this.#launching;
+        return slot.launching;
     }
-    /** The browser process died: drop every lease (they're invalid) and clear so the next acquire relaunches. */
-    #onCrash(crashed) {
-        if (this.#browser !== crashed)
+    /**
+     * A browser process died: drop the leases it held (they're invalid) and clear its slot so the next
+     * acquire of that kind relaunches it. The other browser's leases live on.
+     */
+    #onCrash(slot, crashed) {
+        if (slot.browser !== crashed)
             return; // a stale handler from a prior browser
-        this.#browser = undefined;
-        this.#active.clear();
-        this.#occupied = 0; // every slot is gone with the browser
+        slot.browser = undefined;
+        let freed = 0;
+        for (const [id, lease] of this.#active) {
+            if (lease.headed !== slot.headed)
+                continue;
+            this.#active.delete(id);
+            freed += 1;
+        }
+        // A lease mid-acquire on the dead browser holds a slot too; it frees it in its own catch. When
+        // every lease belonged to this browser, nothing else can be holding one.
+        this.#occupied = 0 === this.#active.size ? 0 : Math.max(0, this.#occupied - freed);
         for (const waiter of this.#waiters.splice(0))
             waiter(); // let them re-claim + relaunch
     }
+    /** Whether this lease's context skips certificate checks. A context cannot change it later. */
+    ignoresHTTPSErrors(sessionId) {
+        return true === this.#active.get(this.#leaseIdOf(sessionId))?.ignoresHTTPSErrors;
+    }
+    /** Whether this lease lives in the headed browser. */
+    isHeaded(sessionId) {
+        return true === this.#active.get(this.#leaseIdOf(sessionId))?.headed;
+    }
 }

package/dist/portal/pool/context-permissions.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Browser permissions on a leased context: granted before the first navigation, and read back where
+ * the browser can contradict the grant.
+ *
+ * Never changed on a lease that is already open. Acquire hands an origin's live lease to whoever asks
+ * for that origin, so the lease may be another agent's tab mid-flow, and nothing here knows whose it
+ * is. A different set means a fresh lease.
+ *
+ * Each grant is scoped to the origin the lease was opened on, so a third-party frame the app embeds
+ * is not handed the same grant as the app.
+ *
+ * Notifications are why the read-back exists. Playwright's headless shell — what the pool launches
+ * when Playwright's own Chromium is installed — has no notification support: after a grant,
+ * `navigator.permissions.query` reports `granted` while `Notification.permission` still reads
+ * `denied`. A page that gates its UI on the second never sees the grant, so a lease that reported
+ * "granted" there would be reporting something the page cannot see.
+ */
+import type { PooledContext } from './pool-contract.js';
+/** The permission whose grant the headless shell does not pass on to `Notification.permission`. */
+export declare const NOTIFICATIONS_PERMISSION = "notifications";
+/** Evaluated in the leased page. A string, because the pool's page surface evaluates scripts. */
+export declare const NOTIFICATION_PERMISSION_READ = "typeof Notification === 'undefined' ? 'unsupported' : Notification.permission";
+/**
+ * How long a read-back may take. Bounded because acquire waits on it, and a wedged renderer never
+ * answers an evaluation: an unbounded one would turn "this tab is stuck" into "acquire hangs".
+ */
+export declare const NOTIFICATION_READ_TIMEOUT_MS = 1500;
+/** A permission could not be granted or cleared. Its message is written for the agent. */
+export declare class LeasePermissionError extends Error {
+    readonly name = "LeasePermissionError";
+}
+/** Grant `permissions` on the origin of `url`. Nothing to grant is a no-op, not a refusal. */
+export declare function grantLeasePermissions(context: PooledContext, permissions: readonly string[], url: string): Promise<void>;

package/dist/portal/pool/context-permissions.js

@@ -0,0 +1,33 @@
+/** The permission whose grant the headless shell does not pass on to `Notification.permission`. */
+export const NOTIFICATIONS_PERMISSION = 'notifications';
+/** Evaluated in the leased page. A string, because the pool's page surface evaluates scripts. */
+export const NOTIFICATION_PERMISSION_READ = "typeof Notification === 'undefined' ? 'unsupported' : Notification.permission";
+/**
+ * How long a read-back may take. Bounded because acquire waits on it, and a wedged renderer never
+ * answers an evaluation: an unbounded one would turn "this tab is stuck" into "acquire hangs".
+ */
+export const NOTIFICATION_READ_TIMEOUT_MS = 1_500;
+/** Playwright prefixes its errors with the call that failed; the agent needs only the reason. */
+const PLAYWRIGHT_CALL_PREFIX = /^browserContext\.\w+:\s*/;
+/** A permission could not be granted or cleared. Its message is written for the agent. */
+export class LeasePermissionError extends Error {
+    name = 'LeasePermissionError';
+}
+function reasonOf(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return (message.split('\n')[0] ?? message).replace(PLAYWRIGHT_CALL_PREFIX, '');
+}
+/** Grant `permissions` on the origin of `url`. Nothing to grant is a no-op, not a refusal. */
+export async function grantLeasePermissions(context, permissions, url) {
+    if (0 === permissions.length)
+        return;
+    if (context.grantPermissions === undefined) {
+        throw new LeasePermissionError('this browser context cannot grant permissions');
+    }
+    try {
+        await context.grantPermissions([...permissions], { origin: new URL(url).origin });
+    }
+    catch (err) {
+        throw new LeasePermissionError(`could not grant ${permissions.join(', ')}: ${reasonOf(err)}`);
+    }
+}

package/dist/portal/pool/lease-marker-stamp.d.ts

@@ -0,0 +1,23 @@
+import type { PooledPage } from './pool-contract.js';
+interface LeaseMarkerArg {
+    session: string;
+    project?: string | undefined;
+    targetOrigin: string;
+    sessionParam: string;
+    projectParam: string;
+}
+/**
+ * Init script restoring the marker a server redirect dropped, so the SDK registers under the lease id.
+ * It runs only in pages of the lease's own browser context, so a person's tab at the same URL never
+ * carries the marker and is never adopted. It writes only in the top frame, only on the lease's own
+ * target origin (never an identity provider's or any third party's URL), and the pool installs it
+ * only when the navigated URL's marker matches this lease's id. Must stay self-contained: Playwright
+ * serialises the function source into the page.
+ */
+export declare function stampLeaseMarker(arg: LeaseMarkerArg): void;
+export declare function installLeaseMarker(page: PooledPage, leaseId: string, targetOrigin: string | undefined, project: string | undefined): Promise<void>;
+export declare function leaseMarkerOf(url: string): {
+    session: string;
+    project: string | undefined;
+} | undefined;
+export {};

package/dist/portal/pool/lease-marker-stamp.js

@@ -0,0 +1,49 @@
+import { RETICLE_URL_PARAM } from '@reticlehq/core';
+/**
+ * Init script restoring the marker a server redirect dropped, so the SDK registers under the lease id.
+ * It runs only in pages of the lease's own browser context, so a person's tab at the same URL never
+ * carries the marker and is never adopted. It writes only in the top frame, only on the lease's own
+ * target origin (never an identity provider's or any third party's URL), and the pool installs it
+ * only when the navigated URL's marker matches this lease's id. Must stay self-contained: Playwright
+ * serialises the function source into the page.
+ */
+export function stampLeaseMarker(arg) {
+    const win = globalThis.window;
+    if (win === undefined || win.top !== win || win.location.origin !== arg.targetOrigin)
+        return;
+    try {
+        const url = new URL(win.location.href);
+        if (url.searchParams.has(arg.sessionParam))
+            return;
+        url.searchParams.set(arg.sessionParam, arg.session);
+        if (arg.project !== undefined && !url.searchParams.has(arg.projectParam)) {
+            url.searchParams.set(arg.projectParam, arg.project);
+        }
+        win.history.replaceState(null, '', url.toString());
+    }
+    catch {
+        return;
+    }
+}
+export async function installLeaseMarker(page, leaseId, targetOrigin, project) {
+    if (page.addInitScript === undefined || targetOrigin === undefined)
+        return;
+    await page.addInitScript(stampLeaseMarker, {
+        session: leaseId,
+        project,
+        targetOrigin,
+        sessionParam: RETICLE_URL_PARAM.SESSION,
+        projectParam: RETICLE_URL_PARAM.PROJECT,
+    });
+}
+export function leaseMarkerOf(url) {
+    try {
+        const params = new URL(url).searchParams;
+        const session = params.get(RETICLE_URL_PARAM.SESSION) ?? '';
+        const project = params.get(RETICLE_URL_PARAM.PROJECT) ?? '';
+        return '' === session ? undefined : { session, project: '' === project ? undefined : project };
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/portal/pool/playwright-launcher.d.ts

@@ -6,6 +6,41 @@
  * Headless by default — the pool exists for fault-tolerant headless multi-agent testing.
  */
 import type { Launcher } from './browser-pool.js';
+import type { ScreenshotOptions } from './pool-contract.js';
+/**
+ * Reticle paints its own UI (presenter HUD, glow, annotator marks, tour) into the page. It is
+ * time-varying, since the activity log and border state change with every command, so capturing it
+ * makes a fresh screenshot of an unchanged page differ from its baseline. Playwright applies `style`
+ * for the shot only and then reverts it, so the page under test is never changed. Disabling animations
+ * settles any remaining transitions. Shared by every capture path, driven and leased, so both hide
+ * the same set: core's `RETICLE_OVERLAY_SELECTOR`.
+ */
+export declare const SCREENSHOT_DETERMINISM: {
+    readonly style: "[data-reticle-overlay],[data-reticle-cursor],[data-reticle-hud],[data-reticle-glow],[data-reticle-mark],[data-reticle-blocker],[data-reticle-tour]{display:none !important}";
+    readonly animations: "disabled";
+};
+/**
+ * How Playwright captures a leased tab: a PNG by default, a JPEG for a live picture. Every capture
+ * hides Reticle's own UI with `SCREENSHOT_DETERMINISM`, the same as the driven path, so a lease
+ * baseline shows the app and not the HUD.
+ */
+export declare function screenshotOptions(opts: ScreenshotOptions): {
+    fullPage: boolean;
+    style?: string;
+    animations?: 'disabled';
+    type?: 'jpeg';
+    quality?: number;
+    scale?: 'css';
+};
+/**
+ * A step screenshot with Reticle's own UI out of it. The step path injects nothing into the page
+ * (no stylesheet, no fast-forwarded animation), so the HUD covered a third of every picture. Only
+ * our own hosts change, by their own inline `visibility`, for this one capture, and are put back
+ * whatever the capture did: the app's DOM, styles and events are not touched.
+ */
+export declare function captureWithChromeHidden(page: {
+    evaluate: (script: string) => Promise<unknown>;
+}, capture: () => Promise<Uint8Array>): Promise<Uint8Array>;
 /**
  * How a leased tab navigates. Pure, and exported, because the decision in it is worth a test while
  * the rest of this file needs a real Chromium.

package/dist/portal/pool/playwright-launcher.js

@@ -6,11 +6,61 @@
  * Headless by default — the pool exists for fault-tolerant headless multi-agent testing.
  */
 import { BrowserLaunchKind } from '@reticlehq/core/telemetry';
+import { HIDE_RETICLE_CHROME_CSS, RETICLE_OVERLAY_SELECTOR } from '@reticlehq/core';
 import { launchChromium } from '../../launch-chromium.js';
 import { getSessionMetrics } from '../../telemetry/session-metrics.js';
 import { classifyConnectFailure } from '../../telemetry/connect-failure.js';
 import { chromiumInstallCommand, chromiumInstallDepsCommand, bundledPlaywrightVersion, } from '../../command/cli/doctor/browser/chromium-hint.js';
 import { installNetworkMocks } from '../input/network-mock.js';
+/**
+ * Reticle paints its own UI (presenter HUD, glow, annotator marks, tour) into the page. It is
+ * time-varying, since the activity log and border state change with every command, so capturing it
+ * makes a fresh screenshot of an unchanged page differ from its baseline. Playwright applies `style`
+ * for the shot only and then reverts it, so the page under test is never changed. Disabling animations
+ * settles any remaining transitions. Shared by every capture path, driven and leased, so both hide
+ * the same set: core's `RETICLE_OVERLAY_SELECTOR`.
+ */
+export const SCREENSHOT_DETERMINISM = {
+    style: HIDE_RETICLE_CHROME_CSS,
+    animations: 'disabled',
+};
+/**
+ * How Playwright captures a leased tab: a PNG by default, a JPEG for a live picture. Every capture
+ * hides Reticle's own UI with `SCREENSHOT_DETERMINISM`, the same as the driven path, so a lease
+ * baseline shows the app and not the HUD.
+ */
+export function screenshotOptions(opts) {
+    // A step screenshot is evidence about the page, so it must not change it: `animations: disabled`
+    // fast-forwards running animations to their end and fires their events in the app under test.
+    if (true === opts.cssScale && opts.jpegQuality !== undefined) {
+        return { fullPage: false, type: 'jpeg', quality: opts.jpegQuality, scale: 'css' };
+    }
+    const base = { ...SCREENSHOT_DETERMINISM, fullPage: true === opts.fullPage };
+    return opts.jpegQuality === undefined
+        ? base
+        : { ...base, type: 'jpeg', quality: opts.jpegQuality };
+}
+/** Where the hidden hosts' own visibility waits to be put back, on the page's window. */
+const SHOT_HIDDEN_KEY = '__reticleShotHidden';
+/** A string literal safe to splice into a script: JSON plus the characters that end one early. */
+const scriptLiteral = (value) => JSON.stringify(value).replace(/[<>/\u2028\u2029]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+const HIDE_CHROME_SCRIPT = `(() => { const held = []; for (const el of document.querySelectorAll(${scriptLiteral(RETICLE_OVERLAY_SELECTOR)})) { held.push([el, el.style.visibility]); el.style.visibility = 'hidden'; } window.${SHOT_HIDDEN_KEY} = held; })()`;
+const RESTORE_CHROME_SCRIPT = `(() => { for (const [el, was] of window.${SHOT_HIDDEN_KEY} ?? []) el.style.visibility = was; delete window.${SHOT_HIDDEN_KEY}; })()`;
+/**
+ * A step screenshot with Reticle's own UI out of it. The step path injects nothing into the page
+ * (no stylesheet, no fast-forwarded animation), so the HUD covered a third of every picture. Only
+ * our own hosts change, by their own inline `visibility`, for this one capture, and are put back
+ * whatever the capture did: the app's DOM, styles and events are not touched.
+ */
+export async function captureWithChromeHidden(page, capture) {
+    await page.evaluate(HIDE_CHROME_SCRIPT);
+    try {
+        return await capture();
+    }
+    finally {
+        await page.evaluate(RESTORE_CHROME_SCRIPT).catch(() => undefined);
+    }
+}
 /**
  * How a leased tab navigates. Pure, and exported, because the decision in it is worth a test while
  * the rest of this file needs a real Chromium.
@@ -33,8 +83,8 @@ export function gotoOptions(timeoutMs) {
 function wrapBrowser(browser) {
     return {
         isConnected: () => browser.isConnected(),
-        newContext: async () => {
-            const context = await browser.newContext();
+        newContext: async (opts) => {
+            const context = await browser.newContext(true === opts?.ignoreHTTPSErrors ? { ignoreHTTPSErrors: true } : undefined);
             return {
                 newPage: async () => {
                     const page = await context.newPage();
@@ -43,7 +93,15 @@ function wrapBrowser(browser) {
                         close: () => page.close(),
                         evaluate: (script) => page.evaluate(script),
                         // Playwright returns a Buffer; Uint8Array is what the visual store and differ take.
-                        screenshot: async (opts) => new Uint8Array(await page.screenshot({ fullPage: true === opts?.fullPage })),
+                        // Same determinism as the driven path's capturePage: without it a lease baseline caught
+                        // the HUD, its activity log and the toolbar, and a HUD change read as a regression (#1355).
+                        screenshot: async (opts) => {
+                            const shoot = async () => new Uint8Array(await page.screenshot(screenshotOptions(opts ?? {})));
+                            // A step capture injects no stylesheet, so our own hosts are hidden another way.
+                            return true === opts?.cssScale
+                                ? captureWithChromeHidden({ evaluate: (script) => page.evaluate(script) }, shoot)
+                                : shoot();
+                        },
                         // Three moves, same as performGesture: a single move to the center can be a no-op if
                         // the pointer was already there, and CSS :hover needs a native hit-test to apply.
                         hover: async (x, y) => {
@@ -53,6 +111,7 @@ function wrapBrowser(browser) {
                         },
                         installMocks: (rules) => installNetworkMocks(page, [...rules]),
                         setViewport: (size) => page.setViewportSize(size),
+                        bringToFront: () => page.bringToFront(),
                         onCrash: (handler) => page.on('crash', handler),
                         onConsole: (handler) => page.on('console', (msg) => handler(msg.text())),
                         onDialog: (handler) => page.on('dialog', (dialog) => handler({ message: dialog.message(), dismiss: () => dialog.dismiss() })),
@@ -67,6 +126,8 @@ function wrapBrowser(browser) {
                     };
                 },
                 addCookies: (cookies) => context.addCookies(cookies),
+                grantPermissions: (permissions, opts) => context.grantPermissions(permissions, opts),
+                clearPermissions: () => context.clearPermissions(),
                 close: () => context.close(),
             };
         },