The one and only agent harness for complex codebases. Project memory, planning, execution, and verified completion inside Codex.
Browser setup (Web capture)
Capture with omowright from the js-eval kernel. The library is staged inside the browser skill;
load it once per session:
const { loadOmowright } = await import("<browser-skill-root>/scripts/omowright.mjs")
const { omowright } = await loadOmowright()
Owned engine (default for QA) - the capture matrix
A browser your code launches, with a task-owned profile, pinned viewport and no user state.
connectPipe opens no listening port and reaps the process on close(). One loop produces the
whole matrix the skill requires: phone (true mobile emulation) and desktop, light and dark, top
and scrolled-to-end, plus the reduced-motion variant for motion frames. page.screenshot() is a
PNG of the page itself, so no browser chrome can appear in it.
// js-eval cell; urls and outDir belong to this QA run.
const { mkdtempSync, rmSync } = await import("node:fs")
const profile = mkdtempSync(`${(await import("node:os")).tmpdir()}/visual-qa-`)
const browser = await omowright.connectPipe({
browserPath: chromeBinary, // installed Chrome, Chromium, CloakBrowser or chrome-headless-shell
browserArgs: ["--headless", "--no-first-run", `--user-data-dir=${profile}`],
storageRoot: profile,
})
const media = (page, sid, scheme, motion) => page.cdp.send("Emulation.setEmulatedMedia", {
features: [{ name: "prefers-color-scheme", value: scheme }, { name: "prefers-reduced-motion", value: motion }],
}, sid)
let page
try {
page = await browser.newTab("about:blank")
const sid = await page.resolveSessionId()
for (const [route, url] of Object.entries(urls)) {
for (const device of ["iphone-14", "desktop-1440"]) { // 390 @ DPR 3, mobile + touch (overlay scrollbars); 1440 @ DPR 1. Add { width: 1920, height: 1080, deviceScaleFactor: 1, mobile: false, hasTouch: false } for page layouts.
await omowright.emulate(page, device)
for (const scheme of ["light", "dark"]) {
await media(page, sid, scheme, "no-preference")
await page.goto(url, { waitUntil: "load" }) // then wait for the page's own ready state (a locator, waitForURL, network snoop), never a sleep
await Bun.write(`${outDir}/${route}-${device}-${scheme}-top.png`, await page.screenshot())
await page.evaluate(() => window.scrollTo(0, document.documentElement.scrollHeight))
await Bun.write(`${outDir}/${route}-${device}-${scheme}-end.png`, await page.screenshot())
}
}
}
// Motion frames: drive the state (hover/press/open), then capture rest, ~100 ms and settled; repeat under
// media(page, sid, scheme, "reduce") for the reduced-motion pass.
} finally {
if (page) await omowright.emulate(page, null)
await browser.close()
rmSync(profile, { recursive: true, force: true })
}
Chrome must already be installed; report an absent executable rather than downloading a managed
browser. For bot-scored or WAF targets use connectCloakProfile({ profileDir }) (CloakBrowser
with a pinned fingerprint seed) — the browser skill's references/owned-engine/README.md
covers it.
Attached engine (authenticated pages)
When the capture needs the user's login, drive the browser they are signed into instead of cloning its profile:
const session = await omowright.connectBrowserSkill({ name: "visual-qa capture", focused: false })
try {
await session.navigate(url, { waitUntil: "load" })
await session.resize(1440, 900) // desktop column of the matrix
await Bun.write(`${outDir}/${route}-1440-top.png`, (await session.screenshot()).buffer) // { buffer, width, height }
await session.emulate({ overrides: { width: 390, mobile: true } }) // phone column; `off: true` restores
await Bun.write(`${outDir}/${route}-390-top.png`, (await session.screenshot()).buffer)
} finally {
await session.emulate({ off: true })
await session.stop()
}
The attached engine follows the signed-in browser's own colour scheme; switch the OS or browser theme between the light and dark passes, and record which theme each file carries.
NEVER launch anything against, or clear cookies/cache/site data from, the user's live profile;
the attached engine is the only sanctioned way to a signed-in page. If no extension is connected,
run the browser skill's scripts/browser-install.mjs for the browser the user actually uses
(from memory, or its detection; on needsChoice ask them and pass --browser=<id>), relay its
one human step, and wait — do
not fall back to the owned engine for an authenticated criterion.
Capture at a fixed viewport
Match CSS viewport AND PNG dimensions: pin deviceScaleFactor through emulate (owned engine).
Attached resize(width, height) sets the window size only and leaves the device pixel ratio at the
user's display, so on the attached engine record the capture's DPR (PNG width / CSS viewport width)
and compare against a reference taken at that DPR. Never resize the PNG to force a pass; a 390-wide capture at desktop
DPR with classic scrollbars is not a phone capture. Wait for the specific page state (a locator,
a waitForURL, a createNetworkSnoop(page).waitFor(...)), not a sleep, then compare:
node "$SKILL_DIR/scripts/visual-qa.mjs" image-diff reference.png actual.png
Inspect dimensionsMatch and diffRatio, then inspect the image. Close every browser and session
and the fixture server, even on a failed capture; remove the owned profile in the same finally.