@agentrhq/webcmd 0.3.3 → 0.4.0

package/clis/linkedin-learning/auth.js

@@ -53,10 +53,4 @@ registerSiteAuthCommands({
   columns: ['public_id', 'plain_id', 'name'],
   quickCheck: hasLinkedinSessionCookie,
   verify: verifyLinkedinLearningIdentity,
-  poll: async (page) => {
-    if (!await hasLinkedinSessionCookie(page)) {
-      throw new AuthRequiredError('linkedin.com', 'Waiting for LinkedIn li_at cookie');
-    }
-    return verifyLinkedinLearningIdentity(page);
-  },
 });

package/clis/manus/auth.js

@@ -45,10 +45,4 @@ registerSiteAuthCommands({
   loginUrl: 'https://manus.im/login',
   columns: ['user_id', 'name'],
   verify: verifyManusIdentity,
-  poll: async (page) => {
-    if (!await hasManusSessionCookie(page)) {
-      throw new AuthRequiredError('manus.im', 'Waiting for Manus session cookies');
-    }
-    return verifyManusIdentity(page);
-  },
 });

package/clis/notebooklm/auth.js

@@ -46,10 +46,4 @@ registerSiteAuthCommands({
   columns: ['name', 'authuser'],
   quickCheck: hasNotebookLmSsoCookies,
   verify: verifyNotebookLmIdentity,
-  poll: async (page) => {
-    if (!await hasNotebookLmSsoCookies(page)) {
-      throw new AuthRequiredError('notebooklm.google.com', 'Waiting for Google SSO cookies (SID + SAPISID)');
-    }
-    return verifyNotebookLmIdentity(page);
-  },
 });

package/clis/pixiv/auth.js

@@ -4,7 +4,7 @@ import { registerSiteAuthCommands } from '../_shared/site-auth.js';
 async function hasPixivSessionCookie(page) {
   const cookies = await page.getCookies({ url: 'https://www.pixiv.net' });
   // Anonymous PHPSESSID is a bare hash; logged-in form is `<userId>_<hash>`.
-  // Require the numeric uid prefix so the login poll doesn't navigate away
+  // Require the numeric uid prefix so identity verification does not navigate away
   // from accounts.pixiv.net while the user is still signing in.
   return cookies.some(c => c.name === 'PHPSESSID' && /^\d+_/.test(c.value || ''));
 }
@@ -55,10 +55,4 @@ registerSiteAuthCommands({
   columns: ['user_id', 'name'],
   quickCheck: hasPixivSessionCookie,
   verify: verifyPixivIdentity,
-  poll: async (page) => {
-    if (!await hasPixivSessionCookie(page)) {
-      throw new AuthRequiredError('pixiv.net', 'Waiting for Pixiv PHPSESSID cookie');
-    }
-    return verifyPixivIdentity(page);
-  },
 });

package/clis/practo/login.js

@@ -1,48 +1,22 @@
-import { AuthRequiredError, TimeoutError } from '@agentrhq/webcmd/errors';
-import { cli, Strategy } from '@agentrhq/webcmd/registry';
+import { registerSiteAuthCommands } from '../_shared/site-auth.js';
 import { PRACTO, probeIdentity } from './utils.js';
 
-const DEFAULT_TIMEOUT_SECONDS = 300;
-
-function isAuthRequired(error) {
-  return error instanceof AuthRequiredError;
-}
-
-cli({
+registerSiteAuthCommands({
   site: 'practo',
-  name: 'login',
-  access: 'write',
-  description: 'Open Practo login and wait until the browser session is authenticated',
   domain: 'www.practo.com',
-  strategy: Strategy.COOKIE,
-  browser: true,
-  navigateBefore: false,
-  defaultWindowMode: 'foreground',
-  siteSession: 'persistent',
-  args: [
-    { name: 'timeout', type: 'int', default: DEFAULT_TIMEOUT_SECONDS, help: 'Maximum seconds to wait for the user to finish login' },
-  ],
-  columns: ['status', 'logged_in', 'site', 'name'],
-  func: async (page, kwargs) => {
+  loginUrl: `${PRACTO}/login`,
+  columns: ['name'],
+  whoamiAliases: ['auth-status'],
+  quickCheck: async (page) => {
     try {
       const rows = await probeIdentity(page);
-      return [{ status: 'already_logged_in', ...rows[0] }];
-    } catch (error) {
-      if (!isAuthRequired(error)) throw error;
+      return { logged_in: true, name: rows[0].name };
+    } catch {
+      return { logged_in: false };
     }
-
+  },
+  verify: async (page) => (await probeIdentity(page))[0],
+  openLogin: async (page) => {
     await page.goto(`${PRACTO}/login`, { waitUntil: 'none', settleMs: 1500 });
-    const timeout = Number(kwargs.timeout ?? DEFAULT_TIMEOUT_SECONDS);
-    const deadline = Date.now() + timeout * 1000;
-    while (Date.now() < deadline) {
-      await page.wait(2);
-      try {
-        const rows = await probeIdentity(page);
-        return [{ status: 'login_complete', ...rows[0] }];
-      } catch (error) {
-        if (!isAuthRequired(error)) throw error;
-      }
-    }
-    throw new TimeoutError('practo login', timeout, 'Complete Practo login in the browser, then retry.');
   },
 });

package/clis/practo/practo.test.js

@@ -12,7 +12,6 @@ import './login.js';
 import './profile.js';
 import './search.js';
 import './slots.js';
-import './whoami.js';
 import { __test__ } from './utils.js';
 
 const {
@@ -124,22 +123,27 @@ describe('practo command registry', () => {
     expect(cancel.args.find((arg) => arg.name === 'confirm')?.type).toBe('boolean');
   });
 
-  it('waits for manual login to complete', async () => {
+  it('opens login without waiting for manual authentication', async () => {
     const login = getRegistry().get('practo/login');
+    const whoami = getRegistry().get('practo/whoami');
     const page = {
       goto: vi.fn().mockResolvedValue(undefined),
       wait: vi.fn().mockResolvedValue(undefined),
       evaluate: vi.fn()
-        .mockResolvedValueOnce({ __error: 'HTTP 401', status: 401 })
-        .mockResolvedValueOnce({ name: 'Ada' }),
+        .mockResolvedValueOnce({ __error: 'HTTP 401', status: 401 }),
     };
 
-    await expect(login.func(page, { timeout: 1 })).resolves.toEqual([{
-      status: 'login_complete',
-      logged_in: true,
+    expect(login.args).toEqual([]);
+    expect(login.columns).toEqual(expect.arrayContaining(['action', 'verify_command']));
+    expect(whoami).toBeDefined();
+    expect(getRegistry().get('practo/auth-status')).toBe(whoami);
+    await expect(login.func(page, {})).resolves.toEqual([expect.objectContaining({
+      status: 'action_required',
+      logged_in: false,
       site: 'practo',
-      name: 'Ada',
-    }]);
+      verify_command: 'webcmd practo whoami',
+    })]);
+    expect(page.wait).not.toHaveBeenCalledWith(2);
   });
 
   it('refuses real booking without --confirm true', async () => {

package/clis/reddit/auth.js

@@ -43,10 +43,4 @@ registerSiteAuthCommands({
   columns: ['username', 'id'],
   quickCheck: hasRedditSessionCookie,
   verify: verifyRedditIdentity,
-  poll: async (page) => {
-    if (!await hasRedditSessionCookie(page)) {
-      throw new AuthRequiredError('reddit.com', 'Waiting for Reddit reddit_session cookie');
-    }
-    return verifyRedditIdentity(page);
-  },
 });

package/clis/reuters/auth.js

@@ -50,18 +50,4 @@ registerSiteAuthCommands({
   loginUrl: 'https://www.reuters.com/account/sign-in/',
   columns: ['user_id', 'subscribed'],
   verify: verifyReutersIdentity,
-  // No-navigation poll: check localStorage on the current page so login-flow
-  // polling doesn't bounce the user off the sign-in page every interval.
-  poll: async (page) => {
-    const loggedIn = await page.evaluate(`(() => {
-      try {
-        const raw = localStorage.getItem('rcom-subscription-state');
-        return raw ? JSON.parse(raw).isLoggedIn === true : false;
-      } catch { return false; }
-    })()`);
-    if (!loggedIn) {
-      throw new AuthRequiredError('reuters.com', 'Waiting for Reuters login');
-    }
-    return verifyReutersIdentity(page);
-  },
 });

package/clis/suno/auth.js

@@ -54,10 +54,4 @@ registerSiteAuthCommands({
   columns: ['user_id', 'name'],
   quickCheck: hasSunoClerkCookie,
   verify: verifySunoIdentity,
-  poll: async (page) => {
-    if (!await hasSunoClerkCookie(page)) {
-      throw new AuthRequiredError('suno.com', 'Waiting for Suno Clerk __session/__client cookie');
-    }
-    return verifySunoIdentity(page);
-  },
 });

package/clis/tiktok/auth.js

@@ -56,10 +56,4 @@ registerSiteAuthCommands({
   columns: ['sec_uid', 'username', 'nickname'],
   quickCheck: hasTiktokSessionCookie,
   verify: verifyTiktokIdentity,
-  poll: async (page) => {
-    if (!await hasTiktokSessionCookie(page)) {
-      throw new AuthRequiredError('www.tiktok.com', 'Waiting for TikTok session cookies');
-    }
-    return verifyTiktokIdentity(page);
-  },
 });

package/clis/twitter/auth.js

@@ -32,10 +32,4 @@ registerSiteAuthCommands({
   columns: ['username', 'url'],
   quickCheck: hasTwitterSessionCookies,
   verify: verifyTwitterIdentity,
-  poll: async (page) => {
-    if (!await hasTwitterSessionCookies(page)) {
-      throw new AuthRequiredError('x.com', 'Waiting for Twitter/X auth cookies');
-    }
-    return verifyTwitterIdentity(page);
-  },
 });

package/clis/upwork/auth.js

@@ -44,10 +44,4 @@ registerSiteAuthCommands({
   columns: ['user_id', 'ciphertext'],
   quickCheck: hasUpworkSessionCookie,
   verify: verifyUpworkIdentity,
-  poll: async (page) => {
-    if (!await hasUpworkSessionCookie(page)) {
-      throw new AuthRequiredError('upwork.com', 'Waiting for Upwork session cookies');
-    }
-    return verifyUpworkIdentity(page);
-  },
 });

package/clis/youtube/auth.js

@@ -45,10 +45,4 @@ registerSiteAuthCommands({
   columns: ['name'],
   quickCheck: hasGoogleSessionCookie,
   verify: verifyYoutubeIdentity,
-  poll: async (page) => {
-    if (!await hasGoogleSessionCookie(page)) {
-      throw new AuthRequiredError('www.youtube.com', 'Waiting for Google session cookies');
-    }
-    return verifyYoutubeIdentity(page);
-  },
 });

package/clis/zepto/auth.js

@@ -1,5 +1,5 @@
-import { AuthRequiredError, TimeoutError } from '@agentrhq/webcmd/errors';
-import { cli, Strategy } from '@agentrhq/webcmd/registry';
+import { AuthRequiredError } from '@agentrhq/webcmd/errors';
+import { registerSiteAuthCommands } from '../_shared/site-auth.js';
 import { DOMAIN, HOME_URL, SITE, ZEPTO_NAV_OPTIONS, safeGoto } from './utils.js';
 
 function authEvaluate() {
@@ -23,36 +23,23 @@ function openLoginEvaluate() {
   `;
 }
 
-cli({
+async function verifyZeptoIdentity(page) {
+  await safeGoto(page, HOME_URL, 'zepto login', ZEPTO_NAV_OPTIONS);
+  const result = await page.evaluate(authEvaluate());
+  if (!result.loggedIn) throw new AuthRequiredError(DOMAIN, 'Zepto login is required');
+  return {};
+}
+
+registerSiteAuthCommands({
   site: SITE,
-  name: 'login',
-  access: 'write',
-  description: 'Open Zepto login and wait until the browser session is authenticated',
   domain: DOMAIN,
-  strategy: Strategy.COOKIE,
-  browser: true,
-  navigateBefore: false,
-  defaultWindowMode: 'foreground',
-  siteSession: 'persistent',
-  args: [
-    { name: 'timeout', type: 'int', default: 300, help: 'Maximum seconds to wait for the user to finish login' },
-  ],
-  columns: ['status', 'logged_in', 'site'],
-  func: async (page, kwargs) => {
+  loginUrl: HOME_URL,
+  columns: [],
+  verify: verifyZeptoIdentity,
+  openLogin: async (page) => {
     await safeGoto(page, HOME_URL, 'zepto login', ZEPTO_NAV_OPTIONS);
-    if ((await page.evaluate(authEvaluate()).catch(() => ({ loggedIn: false }))).loggedIn) {
-      return [{ status: 'already_logged_in', logged_in: true, site: SITE }];
-    }
-    await page.evaluate(openLoginEvaluate()).catch(() => false);
-    const timeout = Number(kwargs.timeout ?? 300);
-    const deadline = Date.now() + timeout * 1000;
-    while (Date.now() < deadline) {
-      await page.wait(2);
-      if ((await page.evaluate(authEvaluate()).catch(() => ({ loggedIn: false }))).loggedIn) {
-        return [{ status: 'login_complete', logged_in: true, site: SITE }];
-      }
-    }
-    throw new TimeoutError('zepto login', timeout, 'Run webcmd zepto login and complete the login dialog in the browser.');
+    const opened = await page.evaluate(openLoginEvaluate());
+    if (!opened) throw new Error('Zepto login dialog did not open');
   },
 });
 

package/clis/zepto/zepto.test.js

@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import { JSDOM } from 'jsdom';
 import { ArgumentError, AuthRequiredError } from '@agentrhq/webcmd/errors';
 import { getRegistry } from '@agentrhq/webcmd/registry';
@@ -193,11 +193,54 @@ describe('zepto helpers', () => {
 
 describe('zepto registry shape', () => {
   it('registers the buying-path commands', () => {
-    for (const name of ['login', 'location', 'search', 'product', 'add-to-cart', 'cart', 'checkout', 'place-order']) {
+    for (const name of ['login', 'whoami', 'location', 'search', 'product', 'add-to-cart', 'cart', 'checkout', 'place-order']) {
       expect(getRegistry().get(`zepto/${name}`)).toBeDefined();
     }
   });
 
+  it('opens login without waiting for manual authentication', async () => {
+    const login = getRegistry().get('zepto/login');
+    const whoami = getRegistry().get('zepto/whoami');
+    const page = {
+      goto: vi.fn().mockResolvedValue(undefined),
+      wait: vi.fn().mockResolvedValue(undefined),
+      evaluate: vi.fn().mockResolvedValue({ loggedIn: false }),
+    };
+
+    expect(login.args).toEqual([]);
+    expect(login.columns).toEqual(expect.arrayContaining(['action', 'verify_command']));
+    expect(whoami).toBeDefined();
+    await expect(login.func(page, {})).resolves.toEqual([expect.objectContaining({
+      status: 'action_required',
+      logged_in: false,
+      site: 'zepto',
+      verify_command: 'webcmd zepto whoami',
+    })]);
+    expect(page.wait).not.toHaveBeenCalledWith(2);
+  });
+
+  it('propagates Zepto identity probe failures', async () => {
+    const error = new Error('evaluate crashed');
+    const page = {
+      goto: vi.fn().mockResolvedValue(undefined),
+      evaluate: vi.fn().mockRejectedValue(error),
+    };
+
+    await expect(getRegistry().get('zepto/whoami').func(page, {})).rejects.toBe(error);
+  });
+
+  it('rejects when the Zepto login dialog cannot be opened', async () => {
+    const login = getRegistry().get('zepto/login');
+    const page = {
+      goto: vi.fn().mockResolvedValue(undefined),
+      evaluate: vi.fn()
+        .mockResolvedValueOnce({ loggedIn: false })
+        .mockResolvedValueOnce(false),
+    };
+
+    await expect(login.func(page, {})).rejects.toThrow('Zepto login dialog did not open');
+  });
+
   it('marks only cart-changing commands as write', () => {
     expect(getRegistry().get('zepto/location').access).toBe('read');
     expect(getRegistry().get('zepto/search').access).toBe('read');

package/dist/src/browser/ax-snapshot.js

@@ -71,7 +71,7 @@ function renderAxTree(axTree, lines, refs, nextRef, opts) {
     const rawNodes = Array.isArray(axTree?.nodes)
         ? axTree.nodes
         : [];
-    const nodes = rawNodes.filter((node) => node && !node.ignored);
+    const nodes = rawNodes.filter((node) => node);
     const byId = new Map();
     const parentIds = new Set();
     for (const node of nodes) {
@@ -88,11 +88,21 @@ function renderAxTree(axTree, lines, refs, nextRef, opts) {
     });
     const root = roots[0] ?? nodes[0];
     const maxDepth = Math.max(1, Math.min(Number(opts.maxDepth) || 50, 200));
+    const maxTraversalHops = 200;
     const roleNameCounts = countRoleNames(nodes);
     const roleNameSeen = new Map();
-    function render(node, depth) {
-        if (!node || depth > maxDepth)
+    function render(node, depth, hops, path) {
+        if (!node || depth > maxDepth || hops > maxTraversalHops || path.has(node))
             return false;
+        const nextPath = new Set(path).add(node);
+        if (node.ignored) {
+            let hasVisibleChild = false;
+            for (const childId of node.childIds ?? []) {
+                if (render(byId.get(childId), depth, hops + 1, nextPath))
+                    hasVisibleChild = true;
+            }
+            return hasVisibleChild;
+        }
         const role = axString(node.role) || 'generic';
         const name = cleanText(axString(node.name));
         const value = cleanText(axString(node.value) || propertyValue(node, 'value'));
@@ -109,7 +119,7 @@ function renderAxTree(axTree, lines, refs, nextRef, opts) {
         const childStart = lines.length;
         let hasVisibleChild = false;
         for (const childId of node.childIds ?? []) {
-            if (render(byId.get(childId), depth + 1))
+            if (render(byId.get(childId), depth + 1, hops + 1, nextPath))
                 hasVisibleChild = true;
         }
         if (!shouldShowSelf && !hasVisibleChild) {
@@ -151,7 +161,7 @@ function renderAxTree(axTree, lines, refs, nextRef, opts) {
         }
         return true;
     }
-    render(root, opts.baseDepth);
+    render(root, opts.baseDepth, 0, new Set());
     return nextRef;
 }
 export function findAxRefReplacement(axTree, ref) {

package/dist/src/browser/ax-snapshot.test.js

@@ -1,6 +1,12 @@
+import { readFileSync } from 'node:fs';
 import { describe, expect, it } from 'vitest';
 import { buildAxSnapshot, buildAxSnapshotFromTrees, findAxRefReplacement } from './ax-snapshot.js';
 describe('AX snapshot prototype', () => {
+    it('publishes the AX snapshot builder as a package subpath', () => {
+        const packageJson = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+        expect(packageJson.exports?.['./browser/ax-snapshot'])
+            .toBe('./dist/src/browser/ax-snapshot.js');
+    });
     it('builds compact refs from Accessibility.getFullAXTree output', () => {
         const result = buildAxSnapshot({
             nodes: [
@@ -25,6 +31,49 @@ describe('AX snapshot prototype', () => {
             name: 'Category',
         });
     });
+    it('keeps actionable descendants of ignored AX nodes', () => {
+        const result = buildAxSnapshot({
+            nodes: [
+                { nodeId: '1', role: { value: 'RootWebArea' }, childIds: ['2'] },
+                { nodeId: '2', ignored: true, childIds: ['3', '4'] },
+                { nodeId: '3', role: { value: 'button' }, name: { value: 'First' }, backendDOMNodeId: 30 },
+                { nodeId: '4', role: { value: 'button' }, name: { value: 'Second' }, backendDOMNodeId: 40 },
+            ],
+        });
+        expect(result.text).toContain('  [1]button "First"\n  [2]button "Second"');
+        expect(result.text).not.toContain('ignored');
+        expect([...result.refs.values()]).toEqual([
+            { ref: '1', backendNodeId: 30, role: 'button', name: 'First' },
+            { ref: '2', backendNodeId: 40, role: 'button', name: 'Second' },
+        ]);
+    });
+    it('stops ignored-node cycles without changing promoted indentation', () => {
+        const result = buildAxSnapshot({
+            nodes: [
+                { nodeId: '1', role: { value: 'RootWebArea' }, childIds: ['2'] },
+                { nodeId: '2', ignored: true, childIds: ['2', '3'] },
+                { nodeId: '3', role: { value: 'button' }, name: { value: 'Save' }, backendDOMNodeId: 30 },
+            ],
+        });
+        expect(result.text).toContain('\n  [1]button "Save"\n');
+        expect(result.refs).toHaveLength(1);
+    });
+    it('bounds traversal through long ignored-node chains', () => {
+        const ignored = Array.from({ length: 201 }, (_, index) => ({
+            nodeId: String(index + 2),
+            ignored: true,
+            childIds: [String(index + 3)],
+        }));
+        const result = buildAxSnapshot({
+            nodes: [
+                { nodeId: '1', role: { value: 'RootWebArea' }, childIds: ['2'] },
+                ...ignored,
+                { nodeId: '203', role: { value: 'button' }, name: { value: 'Too deep' }, backendDOMNodeId: 203 },
+            ],
+        });
+        expect(result.text).not.toContain('Too deep');
+        expect(result.refs).toHaveLength(0);
+    });
     it('tracks nth only for duplicate role/name pairs', () => {
         const result = buildAxSnapshot({
             nodes: [

package/dist/src/browser/cdp.js

@@ -172,7 +172,9 @@ class CDPPage extends BasePage {
             await this.bridge.send('Page.enable');
             this._pageEnabled = true;
         }
-        const loadPromise = this.bridge.waitForEvent('Page.loadEventFired', 30_000).catch(() => { });
+        const loadPromise = options?.waitUntil === 'none'
+            ? undefined
+            : this.bridge.waitForEvent('Page.loadEventFired', 30_000).catch(() => { });
         await this.bridge.send('Page.navigate', { url });
         await loadPromise;
         this._lastUrl = url;

package/dist/src/browser/cdp.test.js

@@ -76,4 +76,16 @@ describe('CDPBridge cookies', () => {
             ['Page.getLayoutMetrics', {}],
         ]);
     });
+    it("only waits for the load event when waitUntil is not 'none'", async () => {
+        vi.stubEnv('WEBCMD_CDP_ENDPOINT', 'ws://127.0.0.1:9222/devtools/page/1');
+        const bridge = new CDPBridge();
+        vi.spyOn(bridge, 'send').mockResolvedValue({});
+        const waitForEvent = vi.spyOn(bridge, 'waitForEvent').mockResolvedValue({});
+        const page = await bridge.connect();
+        await page.goto('https://example.com/fast', { waitUntil: 'none' });
+        expect(waitForEvent).not.toHaveBeenCalled();
+        await page.goto('https://example.com/full', { settleMs: 0 });
+        expect(waitForEvent).toHaveBeenCalledOnce();
+        expect(waitForEvent).toHaveBeenCalledWith('Page.loadEventFired', 30_000);
+    });
 });

package/dist/src/browser/page.js

@@ -94,9 +94,13 @@ export class Page extends BasePage {
     }
     async goto(url, options) {
         let result;
+        const navigateParams = {
+            url,
+            ...(options?.waitUntil && { waitUntil: options.waitUntil }),
+        };
         try {
             result = await sendCommandFull('navigate', {
-                url,
+                ...navigateParams,
                 ...this._cmdOpts(),
             });
         }
@@ -110,7 +114,7 @@ export class Page extends BasePage {
                 throw err;
             this._page = undefined;
             result = await sendCommandFull('navigate', {
-                url,
+                ...navigateParams,
                 ...this._cmdOpts(),
             });
         }

package/dist/src/browser/page.test.js

@@ -50,6 +50,7 @@ describe('Page.getCurrentUrl', () => {
             session: 'site:chatgpt',
             surface: 'adapter',
             siteSession: 'persistent',
+            waitUntil: 'none',
         }));
         expect(sendCommandMock).toHaveBeenCalledWith('exec', expect.objectContaining({
             session: 'site:chatgpt',

package/dist/src/browser/protocol.d.ts

@@ -14,6 +14,8 @@ export interface BrowserRuntimeCommand {
     /** Close any existing leased page and start on a new one (sent on the first action of a command run). */
     freshPage?: boolean;
     url?: string;
+    /** Navigation wait condition: 'none' returns once navigation commits instead of waiting for the load event. */
+    waitUntil?: 'load' | 'none';
     op?: string;
     index?: number;
     domain?: string;

package/dist/src/browser/runtime/local-cloak/actions.js

@@ -55,17 +55,46 @@ function execTarget(page, frameIndex, pageId) {
         throw new CloakActionError('frame_not_found', `Frame not found: ${frameIndex}`, pageId);
     return frame;
 }
-async function applyScreenshotViewport(page, command) {
+async function captureScreenshot(page, context, command) {
     const width = Number.isFinite(command.width) && command.width > 0 ? Math.ceil(command.width) : undefined;
     const height = !command.fullPage && Number.isFinite(command.height) && command.height > 0 ? Math.ceil(command.height) : undefined;
+    const options = {
+        type: command.format ?? 'png',
+        quality: command.format === 'jpeg' ? command.quality : undefined,
+        fullPage: command.fullPage,
+    };
     if (width === undefined && height === undefined)
-        return null;
+        return page.screenshot(options);
     const current = page.viewportSize();
-    await page.setViewportSize({
-        width: width ?? current?.width ?? 1280,
-        height: height ?? current?.height ?? 720,
-    });
-    return current;
+    if (current) {
+        // Emulated viewport: override for the shot, then restore the prior fixed size.
+        await page.setViewportSize({ width: width ?? current.width, height: height ?? current.height });
+        try {
+            return await page.screenshot(options);
+        }
+        finally {
+            await page.setViewportSize(current);
+        }
+    }
+    // Real-window context (viewport: null): setViewportSize can't return to a windowed
+    // state, so override reversibly via CDP and clear it so the override is per-shot only.
+    const windowSize = width === undefined || height === undefined
+        ? await page.evaluate(() => ({ width: window.innerWidth, height: window.innerHeight }))
+        : { width: 0, height: 0 };
+    const cdp = await context.newCDPSession(page);
+    try {
+        await cdp.send('Emulation.setDeviceMetricsOverride', {
+            width: width ?? windowSize.width,
+            height: height ?? windowSize.height,
+            deviceScaleFactor: 0,
+            mobile: false,
+        });
+        return await page.screenshot(options);
+    }
+    finally {
+        await cdp.send('Emulation.clearDeviceMetricsOverride').catch(() => { });
+        await cdp.detach().catch(() => { });
+    }
 }
 export async function dispatchCloakAction(manager, command) {
     try {
@@ -74,7 +103,10 @@ export async function dispatchCloakAction(manager, command) {
                 if (!command.url)
                     return invalidRequest(command, 'Missing url');
                 const lease = await resolveLease(manager, command);
-                await lease.page.goto(command.url, { waitUntil: 'load' });
+                // 'none' maps to Playwright's 'commit': sites that stream analytics forever
+                // never fire the load event, so adapters gating readiness on their own
+                // selector waits must be able to skip it.
+                await lease.page.goto(command.url, { waitUntil: command.waitUntil === 'none' ? 'commit' : 'load' });
                 return { id: command.id, ok: true, data: { title: await lease.page.title(), url: lease.page.url(), timedOut: false }, page: lease.pageId };
             }
             case 'exec': {
@@ -93,19 +125,8 @@ export async function dispatchCloakAction(manager, command) {
             }
             case 'screenshot': {
                 const lease = await resolveLease(manager, command);
-                const previousViewport = await applyScreenshotViewport(lease.page, command);
-                try {
-                    const buffer = await lease.page.screenshot({
-                        type: command.format ?? 'png',
-                        quality: command.format === 'jpeg' ? command.quality : undefined,
-                        fullPage: command.fullPage,
-                    });
-                    return { id: command.id, ok: true, data: buffer.toString('base64'), page: lease.pageId };
-                }
-                finally {
-                    if (previousViewport)
-                        await lease.page.setViewportSize(previousViewport);
-                }
+                const buffer = await captureScreenshot(lease.page, lease.context, command);
+                return { id: command.id, ok: true, data: buffer.toString('base64'), page: lease.pageId };
             }
             case 'close-window': {
                 if (command.page) {