Merge oct8-browse: viewport auto, screenshot --clip= (triage wave)

This commit is contained in:
garrytan committed 2026-10-08 06:24:13 +00:00
commit 610039029b
8 files changed
+141 -13

No files matched your search

+1 -1
View File
@@ -107,7 +107,7 @@ Refs are invalidated on navigation — run `snapshot` again after `goto`.
| `type [--selector <sel>] [--] <text>` | Send keystrokes to the focused element, or to <sel> with --selector (focuses it first). Text that starts with -- goes after a -- separator. |
| `upload <sel> <file> [file2...]` | Upload file(s) |
| `useragent <string>` | Set user agent |
| `viewport [<WxH>] [--scale <n>]` | Set viewport size and optional deviceScaleFactor (1-3, for retina screenshots). --scale requires a context rebuild. |
| `viewport [<WxH>|auto] [--scale <n>]` | 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 <sel|--networkidle|--load>` | Wait for element, network idle, or page load (timeout: 15s) |
### Inspection
+35
View File
@@ -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;
+1 -1
View File
@@ -1744,7 +1744,7 @@ Navigation: goto <url> | back | forward | reload | url
Content: text | html [sel] | links | forms | accessibility
Interaction: click <sel> | fill <sel> <val> | select <sel> <val>
hover <sel> | type [--selector <sel>] <text> | press <key>
scroll [sel] | wait <sel|--networkidle|--load> | viewport <WxH>
scroll [sel] | wait <sel|--networkidle|--load> | viewport <WxH|auto>
upload <sel> <file1> [file2...]
cookie-import <json-file>
cookie-import-browser [browser] [--domain <d> | --all] [--profile <p>] [--clear-storage] [--verify-auth]
+1 -1
View File
@@ -127,7 +127,7 @@ export const COMMAND_DESCRIPTIONS: Record<string, { category: string; descriptio
'scroll': { category: 'Interaction', description: 'With a selector, smooth-scrolls the element into view. Without a selector, jumps to page bottom. No --by/--to amount option; for pixel-precise scrolling use `js window.scrollTo(0, N)`.', usage: 'scroll [sel|@ref]' },
'wait': { category: 'Interaction', description: 'Wait for element, network idle, or page load (timeout: 15s)', usage: 'wait <sel|--networkidle|--load>' },
'upload': { category: 'Interaction', description: 'Upload file(s)', usage: 'upload <sel> <file> [file2...]' },
'viewport':{ category: 'Interaction', description: 'Set viewport size and optional deviceScaleFactor (1-3, for retina screenshots). --scale requires a context rebuild.', usage: 'viewport [<WxH>] [--scale <n>]' },
'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 [<WxH>|auto] [--scale <n>]' },
'cookie': { category: 'Interaction', description: 'Set cookie on current page domain', usage: 'cookie <name>=<value>' },
'cookie-import': { category: 'Interaction', description: 'Import cookies from JSON file', usage: 'cookie-import <json>' },
'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]' },
+9 -6
View File
@@ -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 <css> [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))
+10 -3
View File
@@ -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 <n>]`);
throw new Error(`Unexpected positional arg: ${args[i]}. Usage: viewport [WxH|auto] [--scale <n>]`);
}
}
if (sizeArg === undefined && scaleArg === undefined) {
throw new Error('Usage: browse viewport [<WxH>] [--scale <n>] (e.g. 375x812, or --scale 2 to keep current size)');
throw new Error('Usage: browse viewport [<WxH>|auto] [--scale <n>] (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 [<WxH>] [--scale <n>] (e.g., 375x812)');
if (!sizeArg.includes('x')) throw new Error('Usage: browse viewport [<WxH>|auto] [--scale <n>] (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);
+83
View File
@@ -790,6 +790,30 @@ describe('Visual', () => {
}
});
test('screenshot accepts --clip=x,y,w,h and --selector=<css>', 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 {
@@ -2617,6 +2641,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('<p id="kept">kept</p>');
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)', () => {
+1 -1
View File
@@ -111,7 +111,7 @@ Run with `browse <command> [args]`. Full reference: `browse/SKILL.md`.
- `type [--selector <sel>] [--] <text>`: Send keystrokes to the focused element, or to <sel> with --selector (focuses it first).
- `upload <sel> <file> [file2...]`: Upload file(s)
- `useragent <string>`: Set user agent
- `viewport [<WxH>] [--scale <n>]`: Set viewport size and optional deviceScaleFactor (1-3, for retina screenshots).
- `viewport [<WxH>|auto] [--scale <n>]`: Set viewport size and optional deviceScaleFactor (1-3, for retina screenshots).
- `wait <sel|--networkidle|--load>`: Wait for element, network idle, or page load (timeout: 15s)
### Meta