From c56a642f3b2dfaa37998906788358f9afd79573c Mon Sep 17 00:00:00 2001 From: garrytan Date: Thu, 8 Oct 2026 06:17:21 +0000 Subject: [PATCH 1/2] fix(browse): viewport auto unpins a pinned viewport without a restart `viewport WxH` pinned the page with no way back short of `browse restart`, which also drops a headed /connect-chrome session. `viewport auto` (aliases `reset`, `unpin`) now undoes the pin: - headed: the context already launches with `viewport: null`, but Playwright cannot drop a page's emulated size (and re-applies it on new frame sessions), so the active tab gets a fresh page in the same context at the same URL or load-html content. Cookies and storage persist, the tab id and ownership stay, refs reset as on navigation, and the page follows the real window again. - headless: back to the 1280x720 launch default, tracked viewport included. `auto` with --scale is rejected. Fixes #1059. Adopts #2782 and #1881. Co-authored-by: Jack Thomas <17882510+loulanyue@users.noreply.github.com> Co-authored-by: Jayesh Betala Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- browse/sections/command-list.md | 2 +- browse/src/browser-manager.ts | 35 +++++++++++++++++++ browse/src/cli.ts | 2 +- browse/src/commands.ts | 2 +- browse/src/write-commands.ts | 13 ++++++-- browse/test/commands.test.ts | 59 +++++++++++++++++++++++++++++++++ gstack/llms.txt | 2 +- 7 files changed, 108 insertions(+), 7 deletions(-) diff --git a/browse/sections/command-list.md b/browse/sections/command-list.md index 757c19dd1..be87f64d9 100644 --- a/browse/sections/command-list.md +++ b/browse/sections/command-list.md @@ -107,7 +107,7 @@ Refs are invalidated on navigation — run `snapshot` again after `goto`. | `type [--selector ] [--] ` | Send keystrokes to the focused element, or to with --selector (focuses it first). Text that starts with -- goes after a -- separator. | | `upload [file2...]` | Upload file(s) | | `useragent ` | Set user agent | -| `viewport [] [--scale ]` | Set viewport size and optional deviceScaleFactor (1-3, for retina screenshots). --scale requires a context rebuild. | +| `viewport [|auto] [--scale ]` | Set viewport size and optional deviceScaleFactor (1-3, for retina screenshots). --scale requires a context rebuild. `auto` (alias `reset`) unpins: headed follows the window again, headless returns to 1280x720. | | `wait ` | Wait for element, network idle, or page load (timeout: 15s) | ### Inspection diff --git a/browse/src/browser-manager.ts b/browse/src/browser-manager.ts index c976511ed..29f9d0636 100644 --- a/browse/src/browser-manager.ts +++ b/browse/src/browser-manager.ts @@ -1589,6 +1589,41 @@ export class BrowserManager { await this.getPage().setViewportSize({ width, height }); } + /** + * Undo a `viewport WxH` pin. Headless contexts restore the 1280x720 launch + * default. Headed contexts launch with `viewport: null`, but Playwright has no + * way to drop a page's emulated size, so the active tab gets a fresh page in + * the same context (cookies and storage persist, refs reset as on navigation). + */ + async resetViewport(): Promise<'window' | 'default'> { + this.currentViewport = { width: 1280, height: 720 }; + if (this.connectionMode !== 'headed') { + await this.getPage().setViewportSize(this.currentViewport); + return 'default'; + } + if (!this.context) throw new Error('Browser not launched'); + + const tabId = this.activeTabId; + const pinned = this.getPage(); + const loaded = this.getActiveSession().getLoadedHtml(); + const url = pinned.url(); + const page = await this.context.newPage(); + const session = new TabSession(page); + this.wirePageEvents(page); + try { + if (loaded) await session.setTabContent(loaded.html, { waitUntil: loaded.waitUntil }); + else if (url !== 'about:blank') await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 15000 }); + } catch (err) { + await page.close().catch(() => {}); + throw err; + } + this.pages.set(tabId, page); + this.tabSessions.set(tabId, session); + await pinned.close().catch(() => {}); + await page.bringToFront().catch(() => {}); + return 'window'; + } + // ─── Extra Headers ───────────────────────────────────────── async setExtraHeader(name: string, value: string) { this.extraHeaders[name] = value; diff --git a/browse/src/cli.ts b/browse/src/cli.ts index d4ddee1d8..63bcb1dec 100644 --- a/browse/src/cli.ts +++ b/browse/src/cli.ts @@ -1744,7 +1744,7 @@ Navigation: goto | back | forward | reload | url Content: text | html [sel] | links | forms | accessibility Interaction: click | fill | select hover | type [--selector ] | press - scroll [sel] | wait | viewport + scroll [sel] | wait | viewport upload [file2...] cookie-import cookie-import-browser [browser] [--domain | --all] [--profile

] [--clear-storage] [--verify-auth] diff --git a/browse/src/commands.ts b/browse/src/commands.ts index 9a0bfdf3d..433561efd 100644 --- a/browse/src/commands.ts +++ b/browse/src/commands.ts @@ -127,7 +127,7 @@ export const COMMAND_DESCRIPTIONS: Record' }, 'upload': { category: 'Interaction', description: 'Upload file(s)', usage: 'upload [file2...]' }, - 'viewport':{ category: 'Interaction', description: 'Set viewport size and optional deviceScaleFactor (1-3, for retina screenshots). --scale requires a context rebuild.', usage: 'viewport [] [--scale ]' }, + 'viewport':{ category: 'Interaction', description: 'Set viewport size and optional deviceScaleFactor (1-3, for retina screenshots). --scale requires a context rebuild. `auto` (alias `reset`) unpins: headed follows the window again, headless returns to 1280x720.', usage: 'viewport [|auto] [--scale ]' }, 'cookie': { category: 'Interaction', description: 'Set cookie on current page domain', usage: 'cookie =' }, 'cookie-import': { category: 'Interaction', description: 'Import cookies from JSON file', usage: 'cookie-import ' }, 'cookie-import-browser': { category: 'Interaction', description: 'Copy cookies from chrome, chromium, brave, edge, Windows-only opera, opera-gx, or macOS-only comet, arc, dia. Omitted browser retains legacy comet; select the intended browser explicitly. --domain requires a matching current page; no scope flag opens the picker. --profile is the source directory; ambiguous profiles require selection. --all explicitly selects every non-expired cookie and cannot accompany --domain or --clear-storage. Storage is preserved unless --clear-storage resets captured-origin localStorage (shared across context tabs) and target-tab sessionStorage. --verify-auth requires daemon GSTACK_COOKIE_AUTH_SELECTOR and GSTACK_COOKIE_AUTH_EXPECTED_IDENTITY before startup; missing config rejects before mutation. Verified means an exact visible identity match, not cookie counts or HTTP 200. Windows native extraction remains disabled pending qualification.', usage: 'cookie-import-browser [browser] [--domain d] [--profile p] [--all] [--clear-storage] [--verify-auth]' }, diff --git a/browse/src/write-commands.ts b/browse/src/write-commands.ts index b771deb88..b0e09b86f 100644 --- a/browse/src/write-commands.ts +++ b/browse/src/write-commands.ts @@ -545,18 +545,25 @@ export async function handleWriteCommand( } else if (sizeArg === undefined) { sizeArg = args[i]; } else { - throw new Error(`Unexpected positional arg: ${args[i]}. Usage: viewport [WxH] [--scale ]`); + throw new Error(`Unexpected positional arg: ${args[i]}. Usage: viewport [WxH|auto] [--scale ]`); } } if (sizeArg === undefined && scaleArg === undefined) { - throw new Error('Usage: browse viewport [] [--scale ] (e.g. 375x812, or --scale 2 to keep current size)'); + throw new Error('Usage: browse viewport [|auto] [--scale ] (e.g. 375x812, auto to unpin, or --scale 2 to keep current size)'); + } + + if (sizeArg !== undefined && ['auto', 'reset', 'unpin'].includes(sizeArg.toLowerCase())) { + if (scaleArg !== undefined) throw new Error('viewport auto cannot be combined with --scale or a size.'); + return (await bm.resetViewport()) === 'window' + ? 'Viewport unpinned: the page follows the browser window again (refs cleared)' + : 'Viewport reset to default 1280x720'; } // Resolve width/height: either from sizeArg or from current viewport if --scale-only. let w: number, h: number; if (sizeArg) { - if (!sizeArg.includes('x')) throw new Error('Usage: browse viewport [] [--scale ] (e.g., 375x812)'); + if (!sizeArg.includes('x')) throw new Error('Usage: browse viewport [|auto] [--scale ] (e.g., 375x812)'); const [rawW, rawH] = sizeArg.split('x').map(Number); w = Math.min(Math.max(Math.round(rawW) || 1280, 1), 16384); h = Math.min(Math.max(Math.round(rawH) || 720, 1), 16384); diff --git a/browse/test/commands.test.ts b/browse/test/commands.test.ts index b400ab60a..5ea8d8823 100644 --- a/browse/test/commands.test.ts +++ b/browse/test/commands.test.ts @@ -2617,6 +2617,65 @@ describe('viewport --scale', () => { }); }); +describe('viewport auto (unpin a pinned size)', () => { + test('headless: viewport 375x812 then auto returns to the 1280x720 default', async () => { + await handleWriteCommand('goto', [baseUrl + '/basic.html'], bm); + await handleWriteCommand('viewport', ['375x812'], bm); + expect(await handleWriteCommand('viewport', ['auto'], bm)).toBe('Viewport reset to default 1280x720'); + expect(bm.getPage().viewportSize()).toEqual({ width: 1280, height: 720 }); + expect(await bm.getPage().evaluate(() => window.innerWidth)).toBe(1280); + expect(bm.getCurrentViewport()).toEqual({ width: 1280, height: 720 }); + }); + + test('reset and unpin are aliases', async () => { + for (const alias of ['reset', 'unpin']) { + await handleWriteCommand('viewport', ['400x300'], bm); + await handleWriteCommand('viewport', [alias], bm); + expect(bm.getPage().viewportSize()).toEqual({ width: 1280, height: 720 }); + } + }); + + test('auto rejects --scale', async () => { + await expect(handleWriteCommand('viewport', ['auto', '--scale', '2'], bm)).rejects.toThrow(/cannot be combined/); + }); + + test('handler reports which reset the manager performed', async () => { + for (const [mode, expected] of [['window', /follows the browser window/], ['default', /default 1280x720/]] as const) { + const fakeBm = { resetViewport: async () => mode } as unknown as BrowserManager; + expect(await _handleWriteCommand('viewport', ['auto'], bm.getActiveSession(), fakeBm)).toMatch(expected); + } + }); + + test('headed: auto replaces the pinned page with a window-following one in the same tab', async () => { + const context = await (bm as any).browser.newContext({ viewport: null }); + const headed = new BrowserManager(); + Object.assign(headed as any, { connectionMode: 'headed', context }); + try { + const tabId = await headed.newTab(baseUrl + '/basic.html'); + await handleWriteCommand('viewport', ['600x400'], headed); + const pinned = headed.getPage(); + expect(pinned.viewportSize()).toEqual({ width: 600, height: 400 }); + + expect(await handleWriteCommand('viewport', ['auto'], headed)).toMatch(/follows the browser window/); + const fresh = headed.getPage(); + expect(fresh).not.toBe(pinned); + expect(pinned.isClosed()).toBe(true); + expect(fresh.viewportSize()).toBeNull(); + expect(fresh.url()).toBe(baseUrl + '/basic.html'); + expect(headed.getActiveTabId()).toBe(tabId); + expect(headed.getTabCount()).toBe(1); + + await headed.getActiveSession().setTabContent('

kept

'); + await handleWriteCommand('viewport', ['500x300'], headed); + await handleWriteCommand('viewport', ['auto'], headed); + expect(await headed.getPage().textContent('#kept')).toBe('kept'); + expect(headed.getPage().viewportSize()).toBeNull(); + } finally { + await context.close(); + } + }); +}); + // ─── setContent replay across context recreation ──────────────── describe('setContent replay (load-html survives viewport --scale)', () => { diff --git a/gstack/llms.txt b/gstack/llms.txt index 2f1e04e83..be4a20531 100644 --- a/gstack/llms.txt +++ b/gstack/llms.txt @@ -111,7 +111,7 @@ Run with `browse [args]`. Full reference: `browse/SKILL.md`. - `type [--selector ] [--] `: Send keystrokes to the focused element, or to with --selector (focuses it first). - `upload [file2...]`: Upload file(s) - `useragent `: Set user agent -- `viewport [] [--scale ]`: Set viewport size and optional deviceScaleFactor (1-3, for retina screenshots). +- `viewport [|auto] [--scale ]`: Set viewport size and optional deviceScaleFactor (1-3, for retina screenshots). - `wait `: Wait for element, network idle, or page load (timeout: 15s) ### Meta From 3e84751884b31ee5f0a041713747be65398ff5c2 Mon Sep 17 00:00:00 2001 From: garrytan Date: Thu, 8 Oct 2026 06:19:19 +0000 Subject: [PATCH 2/2] fix(browse): screenshot accepts --clip=x,y,w,h and --selector= Agent-generated commands often use the GNU `--flag=value` form, which threw "Unknown screenshot flag". Both value flags now accept it, through the same validation and conflict checks as the space-separated form. Adopts #1563. Co-authored-by: techcenter68 <75930234+techcenter68@users.noreply.github.com> Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- browse/src/meta-commands.ts | 15 +++++++++------ browse/test/commands.test.ts | 24 ++++++++++++++++++++++++ 2 files changed, 33 insertions(+), 6 deletions(-) diff --git a/browse/src/meta-commands.ts b/browse/src/meta-commands.ts index 38d4b0593..b59247504 100644 --- a/browse/src/meta-commands.ts +++ b/browse/src/meta-commands.ts @@ -447,15 +447,18 @@ export async function handleMetaCommand( const remaining: string[] = []; let flagSelector: string | undefined; for (let i = 0; i < args.length; i++) { - if (args[i] === '--viewport') { + const inline = /^(--clip|--selector)=(.*)$/s.exec(args[i]); + const flag = inline ? inline[1] : args[i]; + const flagValue = () => (inline ? inline[2] : args[++i]); + if (flag === '--viewport') { viewportOnly = true; - } else if (args[i] === '--base64') { + } else if (flag === '--base64') { base64Mode = true; - } else if (args[i] === '--selector') { - flagSelector = args[++i]; + } else if (flag === '--selector') { + flagSelector = flagValue(); if (!flagSelector) throw new Error('Usage: screenshot --selector [path]'); - } else if (args[i] === '--clip') { - const coords = args[++i]; + } else if (flag === '--clip') { + const coords = flagValue(); if (!coords) throw new Error('Usage: screenshot --clip x,y,w,h [path]'); const parts = coords.split(',').map(Number); if (parts.length !== 4 || parts.some(isNaN)) diff --git a/browse/test/commands.test.ts b/browse/test/commands.test.ts index 5ea8d8823..427350c8d 100644 --- a/browse/test/commands.test.ts +++ b/browse/test/commands.test.ts @@ -790,6 +790,30 @@ describe('Visual', () => { } }); + test('screenshot accepts --clip=x,y,w,h and --selector=', async () => { + await handleWriteCommand('goto', [baseUrl + '/basic.html'], bm); + const p = tmpp(`browse-test-clip-eq-${Date.now()}.png`); + try { + expect(await handleMetaCommand('screenshot', ['--clip=0,0,10,10', p], bm, async () => {})).toContain('Screenshot saved (clip 0,0,10,10)'); + const png = fs.readFileSync(p); + expect([png.readUInt32BE(16), png.readUInt32BE(20)]).toEqual([10, 10]); + expect(await handleMetaCommand('screenshot', ['--selector=#title', p], bm, async () => {})).toContain('Screenshot saved (element)'); + } finally { + fs.rmSync(p, { force: true }); + } + }); + + test('screenshot --clip= keeps the usage errors and the selector conflict', async () => { + await handleWriteCommand('goto', [baseUrl + '/basic.html'], bm); + const run = (args: string[]) => handleMetaCommand('screenshot', args, bm, async () => {}); + await expect(run(['--clip='])).rejects.toThrow('Usage: screenshot --clip x,y,w,h'); + await expect(run(['--clip=1,2,3'])).rejects.toThrow('all must be numbers'); + await expect(run(['--selector='])).rejects.toThrow('Usage: screenshot --selector'); + await expect(run(['--clip=0,0,10,10', '#title'])).rejects.toThrow('Cannot use --clip with a selector/ref'); + await expect(run(['--selector=#title', '--clip=0,0,10,10'])).rejects.toThrow('Cannot use --clip with a selector/ref'); + await expect(run(['--viewport=1'])).rejects.toThrow('Unknown screenshot flag'); + }); + test('screenshot unknown flag throws', async () => { await handleWriteCommand('goto', [baseUrl + '/basic.html'], bm); try {