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 <jayesh.betala7@gmail.com>
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
This commit is contained in:
committed 2026-10-08 06:17:21 +00:00
1 parent f67c478f05
commit c56a642f3b
7 files changed
+108 -7

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]' },
+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);
+59
View File
@@ -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('<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