@agentrhq/webcmd 0.3.4 → 0.4.1

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/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) {

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

@@ -1,8 +1,8 @@
 import { describe, expect, it, vi } from 'vitest';
 import { LocalCloakRuntimeProvider } from './provider.js';
-function fakePage(url) {
+function fakePage(url, initialViewport = { width: 1280, height: 720 }) {
     let closed = false;
-    let viewportSize = { width: 1280, height: 720 };
+    let viewportSize = initialViewport;
     return {
         isClosed: vi.fn(() => closed),
         goto: vi.fn(async (nextUrl) => {
@@ -24,8 +24,9 @@ function fakePage(url) {
         }),
     };
 }
-function makeProviderWithFakePage() {
-    const pages = [fakePage('https://example.com/')];
+function makeProviderWithFakePage(initialViewport = { width: 1280, height: 720 }) {
+    const pages = [fakePage('https://example.com/', initialViewport)];
+    const cdpSession = { send: vi.fn().mockResolvedValue(undefined), detach: vi.fn().mockResolvedValue(undefined) };
     const context = {
         on: vi.fn(),
         pages: vi.fn(() => pages.filter((page) => !page.isClosed())),
@@ -34,6 +35,7 @@ function makeProviderWithFakePage() {
             pages.push(page);
             return page;
         }),
+        newCDPSession: vi.fn().mockResolvedValue(cdpSession),
         cookies: vi.fn().mockResolvedValue([{ name: 'sid', value: '1', domain: 'example.com', path: '/' }]),
         close: vi.fn().mockResolvedValue(undefined),
     };
@@ -41,7 +43,7 @@ function makeProviderWithFakePage() {
         baseDir: '/tmp/webcmd-test',
         launchPersistentContext: vi.fn().mockResolvedValue(context),
     });
-    return { provider, page: pages[0], pages, context };
+    return { provider, page: pages[0], pages, context, cdpSession };
 }
 describe('LocalCloakRuntimeProvider', () => {
     it('reports a runtime-named connected status before any profile launches', async () => {
@@ -66,6 +68,20 @@ describe('LocalCloakRuntimeProvider', () => {
         expect(result).toMatchObject({ id: 'cmd-1', ok: true, page: expect.any(String) });
         expect(page.goto).toHaveBeenCalledWith('https://example.com/', expect.objectContaining({ waitUntil: 'load' }));
     });
+    it("maps waitUntil 'none' to a commit-only navigation wait", async () => {
+        const { provider, page } = makeProviderWithFakePage();
+        const result = await provider.dispatch({
+            id: 'cmd-1',
+            action: 'navigate',
+            session: 'work',
+            surface: 'browser',
+            url: 'https://example.com/',
+            waitUntil: 'none',
+            profileId: 'default',
+        });
+        expect(result).toMatchObject({ id: 'cmd-1', ok: true, page: expect.any(String) });
+        expect(page.goto).toHaveBeenCalledWith('https://example.com/', expect.objectContaining({ waitUntil: 'commit' }));
+    });
     it('evaluates JavaScript in the resolved page', async () => {
         const { provider } = makeProviderWithFakePage();
         const nav = await provider.dispatch({ id: 'nav', action: 'navigate', session: 'work', surface: 'browser', url: 'https://example.com/', profileId: 'default' });
@@ -146,6 +162,18 @@ describe('LocalCloakRuntimeProvider', () => {
         expect(page.setViewportSize).toHaveBeenNthCalledWith(2, { width: 1280, height: 720 });
         expect(page.screenshot).toHaveBeenCalledTimes(1);
     });
+    it('reversibly overrides via CDP and never pins the viewport when the context has no fixed viewport', async () => {
+        const { provider, page, cdpSession } = makeProviderWithFakePage(null);
+        const nav = await provider.dispatch({ id: 'nav', action: 'navigate', session: 'work', surface: 'browser', url: 'https://example.com/', profileId: 'default' });
+        await provider.dispatch({ id: 'shot', action: 'screenshot', session: 'work', surface: 'browser', page: nav.page, format: 'png', width: 375, height: 812, profileId: 'default' });
+        // The override must not permanently pin the real window via setViewportSize (#120).
+        expect(page.setViewportSize).not.toHaveBeenCalled();
+        expect(cdpSession.send).toHaveBeenCalledWith('Emulation.setDeviceMetricsOverride', expect.objectContaining({ width: 375, height: 812 }));
+        // ...and it must be cleared afterward so the override is per-shot only.
+        expect(cdpSession.send).toHaveBeenCalledWith('Emulation.clearDeviceMetricsOverride');
+        expect(cdpSession.detach).toHaveBeenCalledTimes(1);
+        expect(page.screenshot).toHaveBeenCalledTimes(1);
+    });
     it('ignores screenshot height overrides for full-page captures while applying width', async () => {
         const { provider, page } = makeProviderWithFakePage();
         const nav = await provider.dispatch({ id: 'nav', action: 'navigate', session: 'work', surface: 'browser', url: 'https://example.com/', profileId: 'default' });

package/dist/src/build-manifest.js

@@ -348,8 +348,8 @@ async function main() {
     fs.mkdirSync(path.dirname(OUTPUT), { recursive: true });
     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}`);
+    console.error(`✅ Manifest compiled: ${entries.length} entries → ${OUTPUT}`);
+    console.error(`✅ 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".
@@ -366,7 +366,7 @@ async function main() {
                 const abs = path.resolve(projectRoot, binPath);
                 if (fs.existsSync(abs)) {
                     fs.chmodSync(abs, 0o755);
-                    console.log(`✅ Restored executable permission: ${binPath}`);
+                    console.error(`✅ Restored executable permission: ${binPath}`);
                 }
             }
         }