matthewwong525/WongStack / .agents/plugins/browser
browser
VerifiedThe person's own browser, for errands.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 4.4 KB |
| SKILL.md | skill md | 3.6 KB |
| VERSION | other | 6 B |
| addon/background.js | script | 1.1 KB |
| addon/check.svg | other | 591 B |
| addon/manifest.json | config | 462 B |
| references/browser-proxy.md | markdown | 5.2 KB |
| references/browser-window.md | markdown | 6.4 KB |
| references/browsing.md | markdown | 18.6 KB |
| references/login-codes.md | markdown | 5.6 KB |
| references/password-manager.md | markdown | 8.3 KB |
| references/setup.md | markdown | 6.4 KB |
| scripts/addons.mjs | script | 26.3 KB |
| scripts/browse.mjs | script | 53.5 KB |
| scripts/browser-server.mjs | script | 50.8 KB |
| scripts/connect-browser.mjs | script | 17.3 KB |
| scripts/forwarder.mjs | script | 14.5 KB |
| scripts/launch-config.py | script | 7.4 KB |
| scripts/lib/cli.mjs | script | 1.2 KB |
| scripts/lib/env.mjs | script | 614 B |
| scripts/lib/primary-root.mjsexecutable | script | 1.9 KB |
| scripts/lib/profile.mjs | script | 1.4 KB |
| scripts/login-move.mjs | script | 4.0 KB |
| scripts/mask-keys.mjs | script | 2.9 KB |
| scripts/proxy-lines.mjs | script | 4.7 KB |
| scripts/refs.mjs | script | 5.4 KB |
scripts/browser-server.mjs
View on GitHub#!/usr/bin/env node
// The shared browser: one Camoufox profile, driven by the Playwright inside the Python camoufox library, behind the
// REST routes camofox-browser had (github.com/jo-inc/camofox-browser, MIT), so browse.mjs keeps its calls.
import { spawn } from 'node:child_process';
import { randomBytes, timingSafeEqual } from 'node:crypto';
import { readFileSync, statSync, writeFileSync } from 'node:fs';
import { createServer } from 'node:http';
import { createRequire } from 'node:module';
import { dirname, join, relative } from 'node:path';
import { fileURLToPath } from 'node:url';
import { startArgs as addonArgs, handBackArgs } from './addons.mjs';
import { FILES, LAUNCH_MS, OLD_PROFILES, launchConfig, proxySetting, windowSetting } from './browse.mjs';
import { NETWORK_FILE, startForwarder } from './forwarder.mjs';
import { moveLogins } from './login-move.mjs';
import { resolveFirst, resolveUpstream } from './proxy-lines.mjs';
import { ADDON_PAGE, ADDON_REFUSAL, MAX_FRAMES, buildSnapshot, frameHasBoxes, frameLabel, frameSkipped, windowSnapshot } from './refs.mjs';
import { isMain } from './lib/cli.mjs';
import { primaryRoot } from './lib/primary-root.mjs';
/** Xvfb as camofox ran it: one 1280x720 screen, no TCP, and the extensions a real desktop lacks turned off. */
const XVFB_ARGS = ['-screen', '0', '1280x720x24', '-ac', '-nolisten', 'tcp', '-extension', 'RENDER', '+extension', 'GLX', '-extension', 'COMPOSITE',
'-extension', 'XVideo', '-extension', 'XVideo-MotionCompensation', '-extension', 'XINERAMA', '-fp', 'built-ins', '-nocursor', '-br'];
const KEY_ALIASES = { ctrl: 'Control', control: 'Control', cmd: 'Meta', command: 'Meta', meta: 'Meta', option: 'Alt', esc: 'Escape', return: 'Enter',
enter: 'Enter', del: 'Delete', backspace: 'Backspace', tab: 'Tab', space: 'Space', home: 'Home', end: 'End', pageup: 'PageUp', pagedown: 'PageDown',
arrowup: 'ArrowUp', arrowdown: 'ArrowDown', arrowleft: 'ArrowLeft', arrowright: 'ArrowRight' };
const IDLE_MS = 5 * 60_000;
// The longest one step may hold its tab: a page that never answers would block every later step on it.
const STEP_MS = 50_000;
const BODY_LIMIT = 5 * 1024 * 1024;
// A task's tab opens from the home tab through the browser's own new-tab path: the driver's new page is always a
// new window. It opens behind the tab shown, so it never takes the person's tab away.
const OPEN_TAB = "void window.open('about:blank', '_blank')";
const TAB_PREFS = { 'browser.tabs.loadDivertedInBackground': true };
const TAB_MS = 15_000;
// The person's turn keeps its tab in front while the helper renews it; a helper that died lets go after this.
const TURN_MS = 60_000;
const BUSY = 'the person is using the browser';
// How long the check that a turn's page still shows may take; a live view's poll catches a miss.
const SHOWN_MS = 1000;
// The server's own code: once one of these changes, an idle server stops, so the next command starts the new code.
const OWN_CODE = ['browser-server.mjs', 'browse.mjs', 'refs.mjs', 'addons.mjs', 'forwarder.mjs', 'login-move.mjs', 'proxy-lines.mjs'];
// The mark before the title of each tab that waits on the person; the browser lets a script change nothing else there.
export const BELL = '🔔 ';
const BELL_MS = 1000;
/** Puts the bell before the page's title, and keeps it there while the site changes its title. It runs in the page,
* with the bell, and keeps its watcher on the document, which the page's own scripts never see. */
const RING = bell => {
const mark = () => { if (!document.title.startsWith(bell)) document.title = bell + document.title; };
mark();
if (document.wongBell) return;
document.wongBell = new MutationObserver(mark);
document.wongBell.observe(document.head ?? document.documentElement, { subtree: true, childList: true, characterData: true });
};
/** Takes the bell off the page's title, and stops keeping it. It runs in the page, with the bell. */
const UNRING = bell => {
document.wongBell?.disconnect();
delete document.wongBell;
if (document.title.startsWith(bell)) document.title = document.title.slice(bell.length);
};
// The screen a Linux desktop's window needs; the library hands the browser no variable of its own.
const SCREEN_VARS = ['DISPLAY', 'WAYLAND_DISPLAY', 'XAUTHORITY', 'XDG_RUNTIME_DIR'];
/** A refusal with its HTTP status. */
const refusal = (status, message) => Object.assign(new Error(message), { status });
const sleep = wait => new Promise(done => setTimeout(done, wait));
/** The Python library's persistent-context options in the Node driver's names: camelCase keys, a media setting of
* `no-override` as null, no viewport as `viewport: null`, and every env value a string. */
export function contextOptions(options) {
const out = {};
for (const [key, value] of Object.entries(options)) {
if (key === 'no_viewport') { if (value) out.viewport = null; continue; }
out[key.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase())] = value === 'no-override' ? null : value;
}
out.env = Object.fromEntries(Object.entries(out.env ?? {}).map(([name, value]) => [name, String(value)]));
// This process closes the browser itself, after the routes stop.
return { ...out, handleSIGTERM: false, handleSIGINT: false, handleSIGHUP: false };
}
/** The persistent context's options for launch-config.py's answer `config`: the library's, with the screen's
* variables `screen` and the pref that opens a task's tab behind the one shown. */
export function persistentOptions(config, screen = {}) {
const options = contextOptions(config.options);
return { ...options, env: { ...options.env, ...screen }, firefoxUserPrefs: { ...options.firefoxUserPrefs, ...TAB_PREFS }, timeout: LAUNCH_MS };
}
/** A key as Playwright's `keyboard.press` spells it: `ctrl+a` is `Control+a`. */
export const pressKey = key => String(key).split('+').map(part => KEY_ALIASES[part.trim().toLowerCase()] ?? part.trim()).join('+');
/** The refusal while the tab shows the password manager's page, marked so a live view's helper can tell it apart. It
* gives the page's own size, `[width, height]`, so a view over that page sets it back at its end. */
const onAddonPage = tab => Object.assign(refusal(403, ADDON_REFUSAL), { addonPage: true, size: tab.addon?.own ? [tab.addon.own.width, tab.addon.own.height] : null });
/** Whether any of `found` is the password manager's frame, or inside it. It runs in the page, so it uses nothing
* outside. */
const ADDON_TARGET = found => found.some(element => (/^(IFRAME|FRAME|OBJECT|EMBED)$/.test(element.tagName) && /^moz-extension:/i.test(element.src || element.data || ''))
|| /^moz-extension:/i.test(element.ownerDocument?.URL ?? ''));
/** Whether the page's keyboard is in `frame`: on the frame, or on the element whose shadow root holds it, closed ones
* too, as 1Password's are. It runs in the page with the frame's element. */
const HOLDS_FOCUS = frame => {
let field = document.activeElement;
while (field?.shadowRoot?.activeElement) field = field.shadowRoot.activeElement;
for (let at = frame; at; at = at.getRootNode().host) if (at === field) return true;
return false;
};
/** Whether `frame` is the password manager's, or sits inside one. */
const inAddonFrame = frame => {
for (let at = frame; at; at = at.parentFrame?.()) if (ADDON_PAGE.test(at.url())) return true;
return false;
};
const KEY_IN_BOX = "a password manager's box shows on this page, and a key could press its buttons";
const LIST_OPEN = "the password manager's fill list is open on this page, and a key could pick a login from it: pick through `browse.mjs addon logins` and `addon pick`, or close the list with `press Escape` first";
/** Refuses a step aimed at the password manager's frame by selector or keyboard (a ref never names one), and, while its
* fill list shows, any key but Escape: arrow keys and Enter in the page's own box pick from that list. */
async function guardAddon(page, name, { ref, selector, key, pressEnter, submit }) {
if (!ref && await aimedAtAddon(page, selector)) throw await addonRefusal(page);
const keys = name === 'press' ? !/^escape$/i.test(String(key ?? '').trim()) : name === 'type' && Boolean(pressEnter || submit);
if (keys && await addonFrameShown(page)) throw await keyRefusal(page);
}
/** The refusal of a key while a password manager's frame shows: its fill list's, else one naming `addon close` while
* a box of its own covers the page, which Escape does not close. */
async function keyRefusal(page) {
const list = fillList(page);
const element = list ? await list.frameElement().catch(() => null) : null;
if (list && (!element || await element.isVisible().catch(() => true))) return refusal(403, LIST_OPEN);
return refusal(403, (await hintBoxes(page)).length ? `${KEY_IN_BOX}${BOX_HINT}` : KEY_IN_BOX);
}
/** Whether a password manager's frame shows on the page; one whose element can not be read counts as shown. */
async function addonFrameShown(page) {
for (const frame of page.frames().filter(inAddonFrame)) {
const element = await frame.frameElement().catch(() => null);
if (!element || await element.isVisible().catch(() => true)) return true;
}
return false;
}
/** The refusal of a step aimed at the password manager, pointing to `addon close` while a box of its own shows. */
async function addonRefusal(page) {
return refusal(403, (await hintBoxes(page)).length ? `${ADDON_REFUSAL}${BOX_HINT}` : ADDON_REFUSAL);
}
/** Whether `selector`, or the keyboard with none, reaches the password manager's frame; an error counts as no. */
async function aimedAtAddon(page, selector) {
try {
return selector ? (await page.locator(selector).evaluateAll(ADDON_TARGET)) === true : await focusInAddon(page);
} catch {
return false;
}
}
/** Whether the keyboard is in one of the password manager's frames. */
async function focusInAddon(page) {
for (const frame of page.frames().filter(inAddonFrame)) {
const element = await frame.frameElement().catch(() => null);
if (element && (await element.evaluate(HOLDS_FOCUS).catch(() => false)) === true) return true;
}
return false;
}
/** 1Password's in-page fill list: its frame, whose address says whether it is locked, and its login rows. */
const FILL_LIST = /^moz-extension:\/\/[^/]+\/inline\/menu\/menu\.html/i;
const LOGIN_ROW = '[role="menuitem"].entry';
const LIST_MS = 3000;
const LIST_POLL_MS = 250;
const LIST_PRESS_MS = 1000;
const FILL_MS = 3000;
/** How long a read of the login names lets one pick follow. */
export const PICK_MS = 2 * 60_000;
// The username box, else the text box before the first password box, else that password box, as a 2-step sign-in.
const LOGIN_BOXES = ['input[autocomplete~="username" i]:visible, input[autocomplete~="email" i]:visible',
'xpath=(//input[@type="password"])[1]/preceding::input[not(@type) or @type="text" or @type="email"][1]', 'input[type="password"]:visible'];
/** The login box and each shown password box with its value, kept in the page as a handle: Node never reads a value.
* A hidden password box, as on Google's email step, is no box: it runs in the page, so it repeats the filter. */
const BOX_VALUES = login => new Map([login, ...[...document.querySelectorAll('input[type="password"]')]
.filter(box => box.checkVisibility?.() ?? box.getClientRects().length > 0)].map(box => [box, box.value]));
/** Whether a box changed since `before` and the page now holds a password, or the login of a 2-step sign-in. */
const FILLED_SINCE = (login, before) => {
const passwords = [...document.querySelectorAll('input[type="password"]')].filter(box => box.checkVisibility?.() ?? box.getClientRects().length > 0);
const changed = [login, ...passwords].some(box => !before.has(box) || before.get(box) !== box.value);
return changed && (passwords.length ? passwords.some(box => box.value !== '') : login.value !== '');
};
const NO_OFFER = 'run `browse.mjs addon logins` on this page and ask the person first: a pick needs its login names read here within 2 minutes, once';
const fillList = page => page.frames().find(frame => FILL_LIST.test(frame.url()));
// 1Password draws its icon in a closed shadow root no locator reaches (tried 2026-11-13), so the page finds it where
// it shows in the login box. It runs in the page with that box, so it uses nothing outside.
const ICON_TAGS = ['com-1password-button'];
const ICON_AT = (box, tags) => {
const { left, top, right, bottom } = box.getBoundingClientRect();
const hits = [];
for (let x = left; x < right; x += 4) {
for (let y = top; y < bottom; y += 4) if (tags.includes(box.ownerDocument.elementFromPoint(x, y)?.localName)) hits.push([x, y]);
}
const mid = axis => hits.reduce((sum, hit) => sum + hit[axis], 0) / hits.length;
return hits.length ? { x: mid(0), y: mid(1) } : null;
};
const ICON_MS = 1500;
/** Clicks the password manager's icon in the login box, once, where the page shows it; false with none there. */
async function clickIcon(page, box) {
const at = await box.evaluate(ICON_AT, ICON_TAGS, { timeout: 3000 }).catch(() => null);
if (!at) return false;
await page.mouse.click(at.x, at.y);
return true;
}
/** 1Password's page for a box over the page, such as *Save login?* or its passkey box. */
const BOX_PAGE = /^moz-extension:\/\/[^/]+\/inline\/notification\/notification\.html/i;
const PASSKEY_TITLE = { name: 'Sign in with a passkey', exact: true };
const PASSKEY_ROW = 'li button';
const PASSKEY_SIGN_IN = { name: 'Sign in', exact: true };
const PASSKEY_MS = 10_000;
/** The passkey box's offer, `{names, locked}`: each `row`'s text, or the one passkey's beside its *Sign in* button.
* It runs in the box's frame, so it uses nothing outside. */
const PASSKEY_OFFER = (body, row) => {
const line = element => element.innerText.split('\n').map(part => part.trim()).filter(part => part && part !== 'Sign in').join(' · ').slice(0, 200);
const rows = [...body.querySelectorAll(row)];
const button = rows.length ? null : [...body.querySelectorAll('button')].find(found => found.innerText.trim() === 'Sign in');
let single = button?.parentElement;
while (single && !line(single)) single = single.parentElement;
const names = rows.length ? rows.map(line) : single ? [line(single)] : [];
return { names, locked: !names.length && /unlock/i.test(body.innerText) };
};
const isPasskeyBox = async frame => BOX_PAGE.test(frame.url()) && await frame.getByRole('heading', PASSKEY_TITLE).count().catch(() => 0) > 0;
/** The shown passkey box, or null. */
async function passkeyBox(page) {
for (const frame of await shownBoxes(page)) if (await isPasskeyBox(frame)) return frame;
return null;
}
/** The boxes a refusal points to `addon close` for: all but the passkey box, whose close would drop a sign-in. */
async function hintBoxes(page) {
const boxes = [];
for (const frame of await shownBoxes(page)) if (!(await isPasskeyBox(frame))) boxes.push(frame);
return boxes;
}
/** The passkey box's offer as `offeredLogins` gives it: `{state: 'passkey', names, box}`, `locked`, or `none`. */
async function offeredPasskeys(box) {
const { names = [], locked = false } = await box.locator('body').evaluate(PASSKEY_OFFER, PASSKEY_ROW, { timeout: 3000 }).catch(() => ({}));
return names.length ? { state: 'passkey', names, box } : { state: locked ? 'locked' : 'none', names: [] };
}
/** Presses passkey `n`'s sign-in once its name is still the one read, then waits for the box to go, as it does once
* signed in. */
async function pickPasskey(page, n, name) {
const box = await passkeyBox(page);
const { names } = box ? await offeredPasskeys(box) : { names: [] };
if (names[n - 1] !== name) throw refusal(409, 'the password manager no longer offers that passkey here; read the logins again and ask the person again');
const rows = box.locator(PASSKEY_ROW);
await clickOn(await rows.count() ? rows.nth(n - 1) : box.getByRole('button', PASSKEY_SIGN_IN));
if (!(await gone(page, [box], PASSKEY_MS))) throw refusal(502, 'the password manager did not sign in with the passkey');
}
// Its own close button's names, or the X's; never *Save*, *Update*, or *Never*, which save or change a setting.
const CLOSE_NAMES = /^(close|dismiss|dismiss banner|not now|no thanks)$/i;
const CLOSE_MS = 3000;
const BOX_HINT = '; a box of its own covers the page: close it with browse.mjs addon close';
const NO_CLOSE = "the password manager's box has no close button; the person closes it in the live view";
/** Each shown frame of the password manager's but its fill list, which Escape closes: its boxes over the page. */
async function shownBoxes(page) {
const shown = [];
for (const frame of page.frames().filter(frame => inAddonFrame(frame) && !FILL_LIST.test(frame.url()) && !inAddonFrame(frame.parentFrame?.() ?? null))) {
const element = await frame.frameElement().catch(() => null);
if (element && await element.isVisible().catch(() => false)) shown.push(frame);
}
return shown;
}
/** Whether every one of `frames` on `page` went, hidden or detached, within `wait`. */
async function gone(page, frames, wait) {
for (const end = Date.now() + wait; Date.now() < end; await sleep(LIST_POLL_MS)) {
if (!(await shownBoxes(page)).some(frame => frames.includes(frame))) return true;
}
return false;
}
/** Closes each box by its own close button: none pressed unless every box has one. Resolves to how many closed. */
async function closeBoxes(page) {
const boxes = await shownBoxes(page);
const buttons = await Promise.all(boxes.map(async frame => {
const button = frame.getByRole('button', { name: CLOSE_NAMES }).first();
return await button.count().catch(() => 0) ? button : null;
}));
if (buttons.includes(null)) throw refusal(403, NO_CLOSE);
for (const button of buttons) await clickOn(button);
if (boxes.length && !(await gone(page, boxes, CLOSE_MS))) throw refusal(502, "the password manager's box did not close; the person closes it in the live view");
return boxes.length;
}
async function loginBox(page) {
for (const selector of LOGIN_BOXES) {
const box = page.locator(selector).first();
if (await box.count().catch(() => 0)) return box;
}
return null;
}
/** Each login row's visible text, one line each; nothing else in the list is read. */
const rowNames = list => list.locator(LOGIN_ROW).evaluateAll(rows => rows.map(row => row.innerText.split('\n').map(line => line.trim()).filter(Boolean).join(' · ').slice(0, 200)));
/** A shown passkey box's passkeys, else the login box's list: `{state: 'list', names, box}`, `locked`, or `none`. A
* key opens the list when focus alone does not, and then the add-on's icon in the box. */
async function offeredLogins(page) {
const passkeys = await passkeyBox(page);
if (passkeys) return offeredPasskeys(passkeys);
const box = await loginBox(page);
if (!box) return { state: 'none', names: [] };
await box.focus({ timeout: 3000 });
const start = Date.now();
for (let end = start + LIST_MS, pressed = 0, clicked = false; Date.now() < end; await sleep(LIST_POLL_MS)) {
const list = fillList(page);
if (list && new URL(list.url()).searchParams.get('locked') !== 'false') return { state: 'locked', names: [] };
const names = list ? await rowNames(list).catch(() => []) : [];
if (names.length) return { state: 'list', names, box };
if (list) continue;
if (!clicked && Date.now() - start >= ICON_MS) {
clicked = true;
if (await clickIcon(page, box)) pressed = Date.now();
}
if (Date.now() - pressed >= LIST_PRESS_MS) {
await box.press('ArrowDown', { timeout: 3000 });
pressed = Date.now();
}
}
return { state: 'none', names: [] };
}
/** Clicks login `n` once its name is still the one read, then waits for a box to change and the page's password box,
* or the login box of a 2-step sign-in, to hold a value: a pre-filled email alone is no fill. */
async function pickLogin(page, n, name) {
const { state, names, box } = await offeredLogins(page);
if (state !== 'list' || names[n - 1] !== name) throw refusal(409, 'the password manager no longer offers that login here; read the logins again and ask the person again');
const before = await box.evaluateHandle(BOX_VALUES);
try {
await clickOn(fillList(page).locator(LOGIN_ROW).nth(n - 1));
for (const end = Date.now() + FILL_MS; Date.now() < end; await sleep(LIST_POLL_MS)) {
if (await box.evaluate(FILLED_SINCE, before).catch(() => false) === true) return;
}
} finally {
await before.dispose().catch(() => {});
}
throw refusal(502, 'the password manager did not fill the page');
}
/** Sizes the page with its tab shown: a tab behind sizes the window the shown one is in, and never ends (tried
* 2026-11-06). */
async function showAndSize(page, size) {
await page.bringToFront();
await page.setViewportSize(size);
}
/** The size a `viewport` step asks for, rounded; a refusal outside 100..4000 px. */
function viewportSize({ width, height }) {
const fits = size => Number.isFinite(size) && size >= 100 && size <= 4000;
if (!fits(width) || !fits(height)) throw refusal(400, 'width and height required (100..4000 px)');
return { width: Math.round(width), height: Math.round(height) };
}
/** Goes to an http(s) address and waits for the page's document, unless the address is a picture. */
async function go(page, url) {
if (!/^https?:\/\//i.test(url ?? '')) throw refusal(400, 'url must be an http(s) address');
const response = await page.goto(url, { waitUntil: 'commit', timeout: 30_000 });
if (!(response?.headers()['content-type'] ?? '').startsWith('image/')) await page.waitForLoadState('domcontentloaded', { timeout: 15_000 }).catch(() => {});
}
const ADDON_OPEN_MS = 3000;
const ADDON_PROBE_MS = 1000;
const [SCREEN_WIDTH, SCREEN_HEIGHT] = XVFB_ARGS[2].split('x').map(Number);
/** Opens the password manager's page in the tab, sized to the screen less the browser's bar, as a live view fits it;
* the driver can not use the tab until the person goes back to a site (tried 2026-11-05), which gets `own` back. */
async function openAddonPage(tab, url) {
const [width, height, outer] = await tab.page.evaluate('[innerWidth, innerHeight, outerHeight]').catch(() => []);
const size = outer > height ? { width: SCREEN_WIDTH, height: SCREEN_HEIGHT - (outer - height) } : null;
const own = tab.addon?.own ?? (width > 0 && height > 0 ? { width, height } : null);
if (size) await showAndSize(tab.page, size).then(() => tab.page.waitForTimeout(150), () => {});
tab.addon = { size, own };
await tab.page.goto(url, { waitUntil: 'commit', timeout: ADDON_OPEN_MS }).catch(() => {});
return { ok: true, url };
}
/** The page text with refs: the main page, then each frame that holds a box, as camofox read them. */
export async function readPage(page) {
await page.waitForLoadState('domcontentloaded', { timeout: 3000 }).catch(() => {});
const main = await page.locator('body').ariaSnapshot({ timeout: 5000 }).catch(() => '');
const frames = [];
for (const frame of page.frames()) {
if (frame === page.mainFrame() || frameSkipped(frame.url(), frame.name()) || inAddonFrame(frame)) continue;
if (frames.length >= MAX_FRAMES) break;
const yaml = await frame.locator('body').ariaSnapshot({ timeout: 3000 }).catch(() => '');
if (frameHasBoxes(yaml)) frames.push({ label: frameLabel(frame.name(), frame.url()), yaml, frame });
}
return buildSnapshot(main, frames);
}
/** The element a ref names. Refs read before a click or a move are read again, as is a ref whose frame went. */
async function refLocator(tab, ref) {
let info = tab.refs?.get(ref);
if (!info || info.frame?.isDetached()) {
tab.refs = (await readPage(tab.page)).refs;
info = tab.refs.get(ref);
}
if (!info) throw refusal(409, `${ref} is not on the page now; read the page again and use a current ref`);
if (info.frame && inAddonFrame(info.frame)) throw await addonRefusal(tab.page);
const scope = info.frame ?? tab.page;
return (info.name ? scope.getByRole(info.role, { name: info.name, exact: true }) : scope.getByRole(info.role)).nth(info.nth);
}
/** A selector that matches one visible element among hidden copies takes that one; a list stays as given. */
async function clickTarget(page, selector) {
const trimmed = selector.trim();
if (trimmed.includes(',') || trimmed.includes(':visible')) return page.locator(selector);
const visible = page.locator(`${trimmed}:visible`);
return (await visible.count()) === 1 ? visible : page.locator(selector);
}
/** A click as camofox made it: a normal one, then a forced one past an overlay or a wait, then the page's own.
* Resolves to how it landed: `mouse`, `forced`, or `script`, an event the page can tell from a person's. */
async function clickOn(locator) {
try {
await locator.click({ timeout: 3000 });
return 'mouse';
} catch (error) {
if (!/intercepts pointer events|not visible|timeout/i.test(error.message)) throw error;
}
try {
await locator.click({ timeout: 3000, force: true });
return 'forced';
} catch {
await locator.evaluate(element => element.click(), undefined, { timeout: 3000 });
return 'script';
}
}
/** Each action on one tab, by its route name. */
const ACTIONS = {
async navigate(tab, { url }) {
if (ADDON_PAGE.test(url ?? '')) return openAddonPage(tab, url);
await go(tab.page, url);
return { ok: true, url: tab.page.url() };
},
async click(tab, { ref, selector }) {
if (!ref && !selector) throw refusal(400, 'ref or selector required');
const via = await clickOn(ref ? await refLocator(tab, ref) : await clickTarget(tab.page, selector));
await tab.page.waitForTimeout(500);
return { ok: true, url: tab.page.url(), via };
},
async type(tab, { ref, selector, text, mode = 'fill', delay = 30, pressEnter = false, submit = false }) {
if (mode !== 'fill' && mode !== 'keyboard') throw refusal(400, "mode must be 'fill' or 'keyboard'");
if (typeof text !== 'string') throw refusal(400, 'text is required');
if (mode === 'fill' && !ref && !selector) throw refusal(400, 'ref or selector required for mode=fill');
const locator = ref ? await refLocator(tab, ref) : null;
if (mode === 'fill') await (locator ?? tab.page.locator(selector)).fill(text, { timeout: 10_000 });
else {
if (locator) await locator.focus({ timeout: 10_000 });
else if (selector) await tab.page.focus(selector, { timeout: 10_000 });
await tab.page.keyboard.type(text, { delay });
}
if (pressEnter || submit) await tab.page.keyboard.press('Enter');
return { ok: true };
},
async select(tab, { ref, selector, option }) {
if ((!ref && !selector) || typeof option !== 'string' || !option) throw refusal(400, 'ref or selector and a nonempty option are required');
const locator = ref ? await refLocator(tab, ref) : tab.page.locator(selector);
await locator.selectOption({ label: option }, { timeout: 5000 }).catch(() => locator.selectOption({ value: option }, { timeout: 5000 }));
return { ok: true };
},
async press(tab, { key }) {
await tab.page.keyboard.press(pressKey(key));
return { ok: true };
},
async evaluate(tab, { expression }) {
if (!expression) throw refusal(400, 'expression is required');
return { ok: true, result: await tab.page.evaluate(expression) };
},
async viewport(tab, body) {
const size = viewportSize(body);
await showAndSize(tab.page, size);
await tab.page.waitForTimeout(150);
return { ok: true, ...size };
},
async front(tab) {
await tab.page.bringToFront();
return { ok: true };
},
/** The one opening in the add-on guard: the login or passkey names here, kept with the address for one pick. */
async logins(tab) {
const { state, names } = await offeredLogins(tab.page);
tab.offer = state === 'list' || state === 'passkey' ? { url: tab.page.url(), names, at: Date.now(), passkey: state === 'passkey' } : null;
return { ok: true, state, names };
},
async pick(tab, { n }) {
const { offer } = tab;
tab.offer = null;
if (!offer || offer.url !== tab.page.url() || Date.now() - offer.at > PICK_MS) throw refusal(409, NO_OFFER);
if (!Number.isInteger(n) || n < 1 || n > offer.names.length) throw refusal(400, `pick takes a login number from 1 to ${offer.names.length}`);
if (!offer.passkey) await pickLogin(tab.page, n, offer.names[n - 1]);
else await pickPasskey(tab.page, n, offer.names[n - 1]);
return { ok: true, ...(offer.passkey ? { passkey: true } : { filled: true }) };
},
/** The other opening: each box of the password manager's over the page, closed by its own close button. */
async closeBoxes(tab) {
return { ok: true, closed: await closeBoxes(tab.page) };
},
};
// Only these actions keep the refs: the rest can change the page.
const KEEPS_REFS = new Set(['type', 'select', 'evaluate', 'viewport', 'front', 'logins']);
// The agent's own steps, which never reach the password manager; only these run while its page shows.
const GUARDED = new Set(['click', 'type', 'select', 'press']);
const OPEN_ON_ADDON = new Set(['navigate', 'front']);
// Steps that can bring their tab to the front: a resize, and a click in the add-on's list, icon, or box.
const RAISES_TAB = new Set(['viewport', 'logins', 'pick', 'closeBoxes']);
/** The request's JSON body, or {} with none. */
async function readBody(request) {
const chunks = [];
let size = 0;
for await (const chunk of request) {
size += chunk.length;
if (size > BODY_LIMIT) throw refusal(413, 'the request is too large');
chunks.push(chunk);
}
if (!size) return {};
try { return JSON.parse(Buffer.concat(chunks).toString('utf8')); } catch { throw refusal(400, 'the body is not JSON'); }
}
/** True when the request holds the API key. */
function authorized(request, key) {
const given = Buffer.from(request.headers.authorization ?? '');
const wanted = Buffer.from(`Bearer ${key}`);
return given.length === wanted.length && timingSafeEqual(given, wanted);
}
/** Whether the page shows, within `SHOWN_MS`; a page that does not answer counts as shown. */
const pageShown = page => Promise.race([page.evaluate('document.visibilityState').then(state => state === 'visible', () => true),
new Promise(done => setTimeout(done, SHOWN_MS, true).unref?.())]);
/** A check of the server's own code `files`: true once one changed, went, or came after this call. */
export function codeChanged(files) {
const stamp = file => { try { return statSync(file).mtimeMs; } catch { return null; } };
const start = files.map(stamp);
return () => files.some((file, at) => stamp(file) !== start[at]);
}
/** The server's own scripts in `dir`, and the same scripts in the primary checkout, where a merge lands: a linked
* worktree, which often starts the server, never gets one. `find` gives the checkout's `{root, primary}`. */
export function ownCode(dir, find = primaryRoot) {
const here = OWN_CODE.map(name => join(dir, name));
try {
const { root, primary } = find(dir);
return primary === root ? here : [...here, ...OWN_CODE.map(name => join(primary, relative(root, dir), name))];
} catch {
return here;
}
}
/** The HTTP handler over one browser `context`: browse.mjs's routes behind `key`, a tab per userId + sessionKey, closed
* after `idleMs` unused. `handBackKey` opens only the turn count and Hand back. Idle and `outdated()`: `onOutdated`. */
export function routes(context, key, { idleMs = IDLE_MS, stepMs = STEP_MS, turnMs = TURN_MS, handBackKey = null, outdated = () => false, onOutdated = () => {} } = {}) {
const tabs = new Map();
let made = 0;
let home = null;
let opening = Promise.resolve();
// Tabs still opening: one has no entry in `tabs` yet, so the idle stop waits for it.
let pendingOpens = 0;
// Each page made for a task's tab: any other page but the home tab is one the person or a site opened.
const taskPages = new WeakSet();
// Each open turn by its tab's id, `{until, before, shared}`: a turn's page that shows goes back to the front after
// another tab's step. `before` holds the pages open when it began; shared turns stand side by side.
const turns = new Map();
// The tabs whose shared turn the person handed back, each until its renewal hears it, or a lease's time.
const handedBack = new Map();
const tabOf = (id, userId) => {
const tab = tabs.get(id);
if (!tab || tab.page.isClosed() || (userId && tab.userId !== userId)) throw refusal(404, 'Tab not found');
tab.lastUse = Date.now();
return tab;
};
// One step at a time on a tab, so a click never lands while the page text is read.
// A step past `stepMs` fails, and the next one runs, so one stuck page call can't hold the tab for good.
const inQueue = (tab, step) => {
const run = tab.queue.then(() => {
let timer;
const limit = new Promise((_, reject) => { timer = setTimeout(() => reject(refusal(504, `the page step timed out after ${stepMs / 1000} s`)), stepMs); });
return Promise.race([step(), limit]).finally(() => clearTimeout(timer));
});
tab.queue = run.catch(() => {});
return run;
};
const closeTab = async id => {
const tab = tabs.get(id);
tabs.delete(id);
await tab?.page.close().catch(() => {});
};
const reaper = setInterval(() => {
for (const [id, tab] of tabs) if (Date.now() - tab.lastUse > idleMs) void closeTab(id);
if (!tabs.size && !pendingOpens && !openTurns().size && outdated()) onOutdated();
}, Math.min(60_000, idleMs));
reaper.unref();
/** The kept blank tab no task gets: the browser's first page, else a new window when the person closed it. */
const homeTab = async () => {
if (home && !home.isClosed()) return home;
const first = home ? null : context.pages().find(page => !page.isClosed() && page.url() === 'about:blank');
home = first ?? await context.newPage();
return home;
};
/** A new tab in the home tab's window, with no way back to it. One opens at a time, so each gets its own. */
const newTab = () => {
const made = opening.then(async () => {
const from = await homeTab();
const [page] = await Promise.all([
context.waitForEvent('page', { predicate: async page => (await page.opener()) === from, timeout: TAB_MS }),
from.evaluate(OPEN_TAB),
]);
taskPages.add(page);
await page.evaluate('window.opener = null').catch(() => {});
return page;
});
opening = made.catch(() => {});
return made;
};
/** Runs `script` with the bell on the tab's page, for at most a second: a page that never answers holds no turn. */
const onTitle = (id, script) => {
const page = tabs.get(id)?.page;
return page && Promise.race([page.evaluate(script, BELL).catch(() => {}), sleep(BELL_MS)]);
};
/** Ends the tab's turn and takes its bell off. */
const endTurn = id => {
if (turns.get(id)?.shared) void onTitle(id, UNRING);
turns.delete(id);
};
/** The open turns, once each lapsed lease or closed tab has ended its own. */
const openTurns = () => {
for (const [id, held] of turns) if (Date.now() >= held.until || tabs.get(id)?.page.isClosed() !== false) endTurn(id);
for (const [id, until] of handedBack) if (Date.now() >= until) handedBack.delete(id);
return turns;
};
/** Whether another tab holds a turn of the person's. */
const otherTurn = tab => [...openTurns().keys()].some(id => id !== tab.id);
/** Ends every shared turn, as the person's *Hand back* in the browser's toolbar does: each renewal then hears it. */
const handBack = () => {
for (const [id, held] of openTurns()) {
if (!held.shared) continue;
handedBack.set(id, Date.now() + turnMs);
endTurn(id);
}
return { ok: true };
};
const openTab = async ({ userId, sessionKey, url }) => {
if (!userId || !sessionKey) throw refusal(400, 'userId and sessionKey required');
const known = [...tabs].find(([, tab]) => tab.userId === userId && tab.sessionKey === sessionKey && !tab.page.isClosed());
if (known) {
const [tabId, tab] = known;
return inQueue(tab, async () => {
if (url) await go(tab.page, url);
Object.assign(tab, { refs: null, text: null, lastUse: Date.now() });
return { tabId, url: tab.page.url() };
});
}
pendingOpens++;
let page;
try {
page = await newTab();
try { if (url) await go(page, url); } catch (error) { await page.close().catch(() => {}); throw error; }
} finally { pendingOpens--; }
const tabId = `tab-${Date.now().toString(36)}-${++made}`;
tabs.set(tabId, { id: tabId, page, userId, sessionKey, refs: null, text: null, lastUse: Date.now(), queue: Promise.resolve() });
page.on('close', () => {
if (tabs.get(tabId)?.page === page) tabs.delete(tabId);
});
// A new page has the site's own title: the bell goes back on.
page.on('domcontentloaded', () => { if (turns.get(tabId)?.shared) void onTitle(tabId, RING); });
return { tabId, url: page.url() };
};
const listTabs = async userId => ({
running: true,
tabs: await Promise.all([...tabs].filter(([, tab]) => tab.userId === userId && !tab.page.isClosed())
.map(async ([tabId, tab]) => ({ tabId, url: tab.page.url(), title: await tab.page.title().catch(() => ''), listItemId: tab.sessionKey }))),
});
/** Whether the tab shows the password manager's page. The driver does not see that page, so a tab sent there counts
* as on it until a quick read gives a site again; the site then gets the page's own size back. */
const onAddon = async tab => {
if (ADDON_PAGE.test(tab.page.url())) return true;
if (!tab.addon) return false;
const href = await Promise.race([tab.page.evaluate('document.URL').catch(() => null), new Promise(done => setTimeout(done, ADDON_PROBE_MS, null))]);
if (typeof href !== 'string' || ADDON_PAGE.test(href)) return true;
const { own } = tab.addon;
// A resize shows the tab, so during another tab's turn the size comes back at a later read.
if (own && otherTurn(tab)) return false;
tab.addon = null;
if (own) await showAndSize(tab.page, own).catch(() => {});
return false;
};
/** A resize while the password manager's page shows: the page takes the width, keeps its height under the bar, and
* the size asked for is the one the site gets back, so a live view's end sets it. */
const keepForSite = async (tab, body) => {
const asked = tab.addon.own = viewportSize(body);
const size = { width: asked.width, height: tab.addon.size?.height ?? asked.height };
const shown = tab.addon.shown ?? tab.addon.size;
if (size.width !== shown?.width || size.height !== shown?.height) {
// The driver's resize reaches this page, but its answer never comes while the page shows (tried 2026-11-12);
// so it is sent once per size, unawaited, and a closed tab's late rejection is dropped.
tab.page.setViewportSize(size).catch(() => {});
tab.addon.shown = size;
await tab.page.waitForTimeout(150);
}
return { ok: true, ...size, addonPage: true };
};
const snapshot = (tab, offset) => inQueue(tab, async () => {
if (await onAddon(tab)) throw onAddonPage(tab);
// A later window reads the text the first one built, so the pieces join.
if (!offset || tab.text == null) Object.assign(tab, (({ refs, snapshot: text }) => ({ refs, text }))(await readPage(tab.page)));
return { url: tab.page.url(), ...windowSnapshot(tab.text, offset), refsCount: tab.refs.size };
});
/** One step on a tab. */
const step = async (tab, name, body) => {
if (name === 'viewport' && tab.addon && await onAddon(tab)) return keepForSite(tab, body);
if (!OPEN_ON_ADDON.has(name) && await onAddon(tab)) throw onAddonPage(tab);
if (GUARDED.has(name)) await guardAddon(tab.page, name, body);
const result = await ACTIONS[name](tab, body);
if (!KEEPS_REFS.has(name)) Object.assign(tab, { refs: null, text: null });
return result;
};
/** One step, then the turn's page that showed before it back in front if the step hid it: always after a step that
* raises its tab. A tab with a turn of its own is the person's to show, so its steps put nothing back. */
const act = (tab, name, body) => inQueue(tab, async () => {
if (!otherTurn(tab) || turns.has(tab.id)) return step(tab, name, body);
const raises = RAISES_TAB.has(name) || (name === 'navigate' && ADDON_PAGE.test(body.url ?? ''));
const shown = await shownTurnPage();
try {
return await step(tab, name, body);
} finally {
if (shown && !shown.isClosed() && (raises || !(await pageShown(shown)))) await shown.bringToFront().catch(() => {});
}
});
/** Whether a page the person or a site opened during the turn is still open, such as a *Forgot password* tab or a
* sign-in window. A page can not tell which tab shows, so the person may be on it. */
const ownPages = () => {
const before = new Set([...turns.values()].flatMap(held => [...held.before]));
return context.pages().filter(page => !page.isClosed() && page !== home && !taskPages.has(page) && !before.has(page));
};
const ownPageOpen = () => ownPages().length > 0;
/** The turns' page that shows, or null: each turn's tab, then each page the person or a site opened in a turn. */
const shownTurnPage = async () => {
for (const page of [...[...openTurns().keys()].map(id => tabs.get(id)?.page), ...ownPages()]) {
if (page && !page.isClosed() && await pageShown(page)) return page;
}
return null;
};
/** Whether another tab's turn keeps this one from holding: any turn, or for a shared turn only a turn not shared. */
const blocked = (tab, shared) => [...openTurns()].some(([id, held]) => id !== tab.id && !(shared && held.shared));
/** Brings the tab to the front, or answers `behind` during another turn. `turn` holds or ends a turn, `raise: false`
* renews it, `reselect` keeps the person's page; a `shared` turn rings its bell, raises alone, hears `handedBack`. */
const front = async (tab, { turn: hold, raise = true, reselect = false, shared = false }) => {
if (hold === false) {
handedBack.delete(tab.id);
endTurn(tab.id);
return { ok: true };
}
openTurns();
// Only a renewal hears a Hand back: a new turn's first hold on the same tab clears it.
if (hold === true && shared && handedBack.delete(tab.id) && !raise) return { ok: true, handedBack: true };
if (hold !== true && otherTurn(tab)) return { ok: true, behind: true };
if (blocked(tab, hold === true && shared)) throw refusal(409, BUSY);
const alone = !otherTurn(tab);
if (hold === true) {
turns.set(tab.id, { until: Date.now() + turnMs, before: turns.get(tab.id)?.before ?? new Set(context.pages()), shared });
if (shared) await onTitle(tab.id, RING);
}
if (reselect && turns.has(tab.id) && ownPageOpen()) return { ok: true };
if (!raise || !alone) return { ok: true };
return act(tab, 'front', {});
};
/** The toolbar button's two routes: how many tabs wait on the person, and their Hand back. */
const BUTTON_ROUTES = { 'GET /turns': () => ({ ok: true, count: [...openTurns().values()].filter(held => held.shared).length }), 'POST /hand-back': handBack };
/** The answer to one authorized request: a JSON body, or PNG bytes. */
const answer = async (method, parts, query, body) => {
const userId = body.userId ?? query.get('userId');
const [top, id, action] = parts;
if (top === 'tabs' && !id) {
if (method === 'POST') return openTab(body);
if (method === 'GET') return listTabs(userId);
}
if (top === 'tabs' && id && !action && method === 'DELETE') {
if (!userId) throw refusal(400, 'userId required (query or body)');
if (tabs.get(id)?.userId === userId) await closeTab(id);
return { ok: true };
}
if (top === 'tabs' && method === 'GET' && action === 'snapshot') return snapshot(tabOf(id, userId), Number(query.get('offset') ?? 0));
if (top === 'tabs' && method === 'GET' && action === 'screenshot') {
const tab = tabOf(id, userId);
return inQueue(tab, async () => {
if (await onAddon(tab)) throw onAddonPage(tab);
return tab.page.screenshot({ type: 'png', fullPage: query.get('fullPage') === 'true' });
});
}
if (top === 'tabs' && method === 'POST' && action === 'front') return front(tabOf(id, userId), body);
// A click never waits now; the route stays for a browse.mjs that still asks after one.
if (top === 'tabs' && method === 'GET' && action === 'click') return tabOf(id, userId) && { ok: true, none: true };
if (top === 'tabs' && method === 'POST' && Object.hasOwn(ACTIONS, action)) return act(tabOf(id, userId), action, body);
if (top === 'sessions' && id && !action && method === 'DELETE') {
await Promise.all([...tabs].filter(([, tab]) => tab.userId === id).map(([tabId]) => closeTab(tabId)));
return { ok: true };
}
if (top === 'sessions' && id && action === 'cookies' && method === 'POST') {
if (!Array.isArray(body.cookies)) throw refusal(400, 'cookies must be a list');
// The profile folder keeps cookies itself; an empty list asks for nothing more.
if (body.cookies.length) await context.addCookies(body.cookies);
return { ok: true, count: body.cookies.length };
}
throw refusal(404, 'no such route');
};
const handle = async (request, response) => {
const send = (status, body) => {
if (Buffer.isBuffer(body)) response.writeHead(status, { 'content-type': 'image/png' }).end(body);
else response.writeHead(status, { 'content-type': 'application/json' }).end(JSON.stringify(body));
};
const url = new URL(request.url, 'http://127.0.0.1');
if (request.method === 'GET' && url.pathname === '/health') return send(200, { ok: true, engine: 'camoufox', tabs: tabs.size });
const button = BUTTON_ROUTES[`${request.method} ${url.pathname}`];
if (button && (authorized(request, key) || (handBackKey && authorized(request, handBackKey)))) return send(200, button());
if (!authorized(request, key)) return send(401, { error: 'unauthorized' });
try {
const body = request.method === 'POST' ? await readBody(request) : {};
send(200, await answer(request.method, url.pathname.split('/').filter(Boolean).map(decodeURIComponent), url.searchParams, body));
} catch (error) {
send(error.status ?? 500, { error: error.message, ...(error.addonPage && { addonPage: true, size: error.size }) });
}
};
handle.close = () => clearInterval(reaper);
return handle;
}
/** Starts Xvfb on the first free display; resolves to its `{display, child}`. */
function startXvfb() {
return new Promise((resolve, reject) => {
const child = spawn('Xvfb', ['-displayfd', '3', ...XVFB_ARGS], { stdio: ['ignore', 'ignore', 'ignore', 'pipe'] });
let text = '';
child.stdio[3].on('data', chunk => {
text += chunk;
if (text.includes('\n')) resolve({ display: `:${text.trim()}`, child });
});
child.once('error', () => reject(new Error('Xvfb, the screen the browser draws on, is not installed')));
child.once('exit', () => reject(new Error('Xvfb stopped before it gave a display')));
});
}
const starting = response => {
response.writeHead(503, { 'content-type': 'application/json' });
response.end(JSON.stringify({ ok: false, starting: true }));
};
/** The browser shows in a window unless the person turned it off, on Linux only where a screen exists; else Linux
* draws on Xvfb. Its launch flags, the screen's variables, its server record, and whether Xvfb starts. */
export function windowLaunch({ platform, setting, env = {} }) {
const linux = platform === 'linux';
const shown = setting && (!linux || Boolean(env.DISPLAY || env.WAYLAND_DISPLAY));
const screen = shown && linux ? Object.fromEntries(SCREEN_VARS.filter(name => env[name]).map(name => [name, env[name]])) : {};
return { args: shown ? ['--window'] : [], env: screen, record: shown ? { window: true } : {}, xvfb: linux && !shown };
}
const savedLines = () => ({ first: resolveFirst(), upstream: resolveUpstream() });
/** The local forwarder through the saved routes when the proxy setting is on: its launch flags and its close; none
* when off, and the saved lines are not read. A forwarder that fails to start fails the browser's start. */
export async function startProxy(on, start = startForwarder, lines = savedLines) {
if (!on) return { on: false, args: [], close: () => {} };
const proxy = await start({ ...lines(), networkFile: NETWORK_FILE });
return { on: true, args: ['--proxy', `http://127.0.0.1:${proxy.port}`], close: () => proxy.close() };
}
const record = info => writeFileSync(FILES.server, `${JSON.stringify({ pid: process.pid, ...info })}\n`, { mode: 0o600 });
/** Takes the port, then starts the proxy when it is on, the screen, the browser and the routes; /health says ok
* only once the browser is up. A failed start leaves its reason in server.json. */
async function main() {
const port = Number(process.env.BROWSE_SERVER_PORT);
const stops = [];
let stopping = false;
const stop = async code => {
if (stopping) return;
stopping = true;
for (const step of stops.reverse()) await Promise.resolve().then(step).catch(() => {});
process.exit(code);
};
process.on('SIGTERM', () => void stop(0));
process.on('SIGINT', () => void stop(0));
let handle = null;
// The port is taken first, so a taken port fails before a browser starts; /health says 503 until the routes are up.
const server = createServer((request, response) => handle ? handle(request, response) : starting(response));
try {
await new Promise((resolve, reject) => server.once('error', reject).listen(port, '127.0.0.1', resolve));
stops.push(() => new Promise(done => { handle?.close(); server.close(done); server.closeAllConnections(); }));
const proxy = await startProxy(proxySetting());
stops.push(() => proxy.close());
const setting = windowSetting();
const windowed = windowLaunch({ platform: process.platform, setting, env: process.env });
const screen = windowed.xvfb ? await startXvfb() : null;
if (screen) stops.push(() => screen.child.kill());
// A broken add-on never stops a start: the browser starts without it.
const addon = await addonArgs().catch(() => []);
const handBackKey = randomBytes(24).toString('hex');
const handBack = (() => { try { return handBackArgs({ port, key: handBackKey }); } catch { return []; } })();
const config = await launchConfig([...proxy.args, ...(screen ? ['--display', screen.display] : []), ...windowed.args, '--fingerprint', FILES.fingerprint, ...addon, ...handBack]);
if (config.error) throw new Error(config.error);
const { firefox } = createRequire(import.meta.url)(join(config.driver, 'index.js'));
const context = await firefox.launchPersistentContext(FILES.profile, persistentOptions(config, windowed.env));
stops.push(() => context.close());
await moveLogins(context, { profilesDir: OLD_PROFILES, marker: FILES.marker }).catch(() => {});
const outdated = codeChanged(ownCode(dirname(fileURLToPath(import.meta.url))));
handle = routes(context, readFileSync(FILES.key, 'utf8').trim(), { handBackKey, outdated, onOutdated: () => void stop(0) });
record({ port, display: screen?.display ?? null, ...windowed.record, proxy: proxy.on, windowSetting: setting, library: config.library, build: config.build, locale: config.locale });
// A browser that quits on its own takes the server with it, so the next command starts a fresh one.
context.on('close', () => void stop(1));
} catch (error) {
// A taken port leaves no reason, so browse.mjs tries another port; any other failure is the browser's own.
if (error.code !== 'EADDRINUSE') record({ port, error: error.message });
await stop(1);
}
}
if (isMain(import.meta.url)) await main();
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |