@povio/lightning-panda 0.0.0-stage → 0.0.17

package/LLM.md

@@ -0,0 +1,260 @@
+# Writing E2E tests with @povio/lightning-panda: instructions for coding agents
+
+Read this before writing or porting a test. It is the whole contract; the
+source is `src/steps.ts` (builders) and `src/index.ts` (pages and runs).
+
+## The model
+
+- A test is **seeding, then one `page.run([...steps])`**. The browser runs every
+  step itself and replies once. Do not split a scenario into several `run`
+  calls unless plain code (an API call, a computation) must happen between
+  them.
+- **Nothing is polled from the test.** Every step waits in the browser until it
+  holds (default 5 s per step). Never write `sleep`, retry loops,
+  `expect.poll`, `waitForTimeout` or `waitForResponse`.
+- **Actions settle.** After `click`, `fill`, `press`, `check`, `uncheck` and
+  `route`, the next step starts only when the page is quiet: the requests the
+  action started have finished, no task is queued, no timeout is due within
+  50 ms, no animation frame is pending and no navigation is half done. Intervals,
+  later timeouts and animation loops do not count. Assert the outcome with the
+  next `check`; do not wait for the request.
+- **Requests are recorded, not awaited.** `check.request(method, path)` looks
+  at the requests made during *this* run (it waits for one to appear and
+  finish). Put it in the same `run` as the action that sends the request.
+
+## Skeleton
+
+Install the browser and client with `bun add --dev @povio/lightning-panda`
+(or `@povio/lightning-panda@next` for an RC). `Lightningpanda.launch()` finds
+the bundled macOS browser automatically. Fork mode requires a separately built
+patched JavaScriptCore browser selected via `LIGHTNINGPANDA_BIN` or `bin`.
+On other operating systems, connect to a remote browser with
+`Lightningpanda.connect()`.
+
+```ts
+import { afterAll, beforeAll, expect, test } from 'bun:test';
+import { Lightningpanda, button, check, dialog, text, label } from '@povio/lightning-panda';
+
+let lp: Lightningpanda;
+beforeAll(async () => {
+  lp = await Lightningpanda.connect(process.env.LIGHTNINGPANDA_WS!, { connections: 4 });
+  await lp.profile('employee', {
+    url: `${APP}/platform`,                 // any page of the app: it boots signed in and waits
+    localStorage: authEntries,              // what the app reads at boot (tokens, user store)
+    viewport: { width: 1440, height: 900 },
+    pool: 2,
+  });
+});
+afterAll(() => lp.close());
+
+test.concurrent('closes a position', async () => {
+  const position = await api.createPosition();                    // seed through the API, not the UI
+  await using page = await lp.page({ as: 'employee', route: `/positions/${position.id}` });
+  const r = await page.run([
+    check(text(position.number)).visible(),
+    button('Settings', { exact: true }).click(),
+    dialog().hasText('will be closed').button('Close Position', { exact: true }).click(),
+    check.request('POST', `/positions/${position.id}/close`).status(200),
+    check(button('Reopen Position')).count(1),
+    text(/^Closed by: /).read('closedBy'),
+  ]);
+  expect(r.values.closedBy).toContain('E2E');                     // bun:test expect on values read
+});
+```
+
+- `lp.page({ as, route })`: a pre-booted, signed-in page; `route` changes the
+  URL in place (pushState + popstate), so the app does not boot again. Use
+  `url` instead only when a full page load is the point of the test.
+- `await using page` closes the page when the test ends (do not leave pages
+  open: an open page stops its connection from refilling).
+- One profile per kind of user (`as`). Several profiles are fine.
+
+## Locators
+
+Build them with the exported helpers; they are data, so build them once and
+reuse them.
+
+| Want | Write |
+|---|---|
+| Button / link / heading / dialog … by accessible name | `button('Save')`, `link('Docs')`, `heading('Positions')`, `dialog()`, `role('tab', 'Air')` |
+| Form control by its label | `label('Email')` |
+| By placeholder | `placeholder('Search')` |
+| By visible text | `text('Saved')`, `text(/^Updated by .*/)` |
+| By test id | `testId('row-42')` (`testId(id, 'data-test')` for another attribute) |
+| CSS as a last resort | `css('#out')` |
+| Inside another locator | `dialog().button('OK')`, `row('EXP-1001').button('Edit')`, `css('.card').text('Total')` |
+| Inside an iframe | `css('#editor').frame().button('Bold')`, `inFrame(css('#editor')).text('Hi')` |
+| Narrow the matches | `.visible()`, `.hasText('beta')`, `.hasNotText('alpha')`, `.has(button('Edit'))`, `.hasNot(…)` |
+| Pick one of several | `.first()`, `.last()`, `.nth(i)` (after the filters) |
+
+- Strings match **case-insensitive substrings** after whitespace
+  normalization; pass `{ exact: true }` for a whole, case-sensitive match. A
+  `RegExp` (flags `i`, `m`, `s` only) tests the normalized text.
+- **Strict mode:** an action on a locator that matches several elements fails
+  at once and lists them. Fix the locator (scope it, filter it, `exact`), and
+  use `.first()` only when any match will do.
+- `text()` follows Playwright's `getByText`: the scope element itself can match
+  (`css('td').text('Domestic', { exact: true })` finds the cell), and an exact
+  string also matches an element one of whose own text runs equals it
+  (`<span><span>|</span>TS-1</span>` for `text('TS-1', { exact: true })`).
+- Prefer role + name, then label / placeholder / text, then test id, then CSS.
+- Hidden elements (`display: none`, `aria-hidden`) have no role: `button('X')`
+  does not match a hidden button. Add `.visible()` to `text()` / `css()`
+  locators when hidden copies exist.
+
+## Steps
+
+| Step | Notes |
+|---|---|
+| `loc.click()` | visible, enabled, not covered, scrolled into view, then a real mouse click; `{ button: 'right', position: { x, y }, force: true }` |
+| `loc.dblclick()` / `loc.hover()` | same pointer options as `click` |
+| `loc.type('text')` | focuses, then one key press per character (`pressSequentially`) |
+| `loc.blur()` | moves focus away (`blur` / `focusout`) |
+| `loc.upload([{ name, text \| base64, mimeType? }])` | sets the files of an `<input type=file>`; a string is a path on the browser's machine |
+| `loc.dropFiles([{ name, text \| base64, mimeType? }])` | external file drag into a visible target; real dragenter/dragover/drop and File data, preserving inline names |
+| `loc.drag(target)` | native drag and drop onto `target`, else a pointer drag |
+| `loc.wheel(deltaX, deltaY)` / `mouse('click', { x, y })` | mouse wheel over the element / raw mouse at viewport coordinates (`click`, `dblclick`, `move`, `down`, `up`, `wheel`) |
+| `loc.fill('text')` | replaces the value of an input, textarea or contenteditable |
+| `loc.press('Enter')` | focuses, then a key or chord: `Escape`, `Tab`, `ArrowDown`, `Shift+Tab`, `ControlOrMeta+A`, `a` |
+| `loc.check()` / `loc.uncheck()` | checkbox or radio; no-op when already in that state |
+| `loc.focus()` | |
+| `loc.read('name', 'text' \| 'value' \| 'count' \| 'visible' \| 'box' \| 'name' \| 'focused' \| 'enabled')` | value lands in `r.values.name`; `loc.read('c', 'css', 'color')` for a computed style |
+| `check(loc).visible()` / `.hidden()` | |
+| `check(loc).text('…')` / `.containsText('…')` / `.value('…')` / `.count(n)` / `.checked()` | `check(loc).not.visible()` negates |
+| `check(loc).css('color', 'rgb(0, 0, 0)')` / `.focused()` / `.name('…')` / `.enabled()` / `.disabled()` | computed style, focus, accessible name, disabled state |
+| `check.request('POST', '/exact/path').status(200)` | path is exact (no query); a `RegExp` tests the full URL; `.status([200, 304])` for any of several; `.count(n)` for exactly n; `.body(…)`, `.bodyKeys([…])`, `.headers({ … })`; `.state('started')` also counts requests in flight |
+| `goto(url)` / `route(path)` | full navigation / same-document route change; `route(path, { settle: false })` does not wait for its requests |
+| `reload()` / `waitForUrl('/positions/')` | reload and wait for `load` / wait until the URL contains (or matches) it |
+| `loaded()` | wait for the page's document to load (added for you on a page still booting) |
+| `idle({ timeout })` | wait until the page is quiet, as after an action; never fails |
+| `mock('/api/items', { json: [] })` / `unmock(url?)` | answer matching requests (`status`, `body`, `headers`, `delay`, `abort`, `times`); `{ passthrough: true }` lets them through, `{ patch: { … } }` rewrites the real response, `{ hold: 'name' }` holds them until `release('name')` |
+| `download({ as, saveTo })` / `popup('name')` | wait for the next download / popup of the run |
+| `viewport(w, h)` / `media({ colorScheme: 'dark' })` | resize the viewport / emulate media features mid-test |
+| `matchScreenshot('name', { … })` / `loc.matchScreenshot('name')` | renders the page (or `clip`, `fullPage`, the element) in the browser and compares it with `__screenshots__/name.png` beside the test; see Screenshots below |
+| `evaluate('expression', 'name')` | escape hatch: JSON value of a page expression into `r.values.name`; a returned promise is awaited (within the step timeout) and a rejection fails the step |
+
+Pointer options (wire shape; the builders take the same names): `click` and
+`dblclick` accept `button: 'right' | 'middle'` (a right click fires
+`contextmenu` after the press and `auxclick` after the release, never
+`click`, as Chromium does); `click`, `dblclick`, `hover`
+and `wheel` accept `position: { x, y }` (an offset from the element's
+top-left instead of its center) and `force: true` (skip the covered and
+enabled checks). `hover` never needs an enabled element: hovering a disabled
+input or an `aria-disabled` menu item works. An element wider than its
+scroll container is clicked at the center of its visible part, as Playwright
+does.
+
+| Step (wire) | Notes |
+|---|---|
+| `{ act: { locator, action: 'wheel', deltaX, deltaY } }` | hovers the element, fires `wheel` there and scrolls the nearest scrollable container unless canceled |
+| `{ mouse: { action: 'click' \| 'dblclick' \| 'move', x, y, button?, steps? } }` | `page.mouse.*` at viewport coordinates; `move` with `steps` sends intermediate moves |
+| `{ mouse: { action: 'down' \| 'up', button?, x?, y? } }` | at the current pointer position unless `x`/`y` are given; buttons stay held across `move` steps until `up` |
+| `{ mouse: { action: 'wheel', deltaX, deltaY, x?, y? } }` | wheel at the current pointer position (or `x`/`y`) |
+| `{ viewport: { width, height } }` | same as `viewport(w, h)`: resizes mid-run, fires `resize` and `matchMedia` `change`, settles like an action |
+| `{ media: { colorScheme?, reducedMotion?, media? } }` | same as `media({ … })`: replaces the whole emulation (an omitted field resets: `light`, `no-preference`, `screen`); `media: 'print'` makes `print` queries match; `matchMedia(…)` `change` listeners fire |
+| `{ page: { target: 'tab' \| targetId \| 'main' } }` | the following steps drive another page of the context: the `as` name of an earlier `popup('tab')`, a target id, or `main` (the page the run started on); add `waitForUrl` / `loaded()` after switching to a fresh popup. Builder: `switchTo('tab')`, `switchTo('main')` |
+
+Every action and check takes `{ timeout }` (ms); `page.run(steps, { timeout })`
+sets the default for the run. Pass `{ settle: false }` to an action whose
+requests never finish (polling, streaming) or that you do not want to wait for.
+
+### Requests and mocks in detail
+
+- A `RegExp` anywhere (locators, `mock`, `waitForUrl`, `check.request`) runs
+  with JavaScript semantics: look-ahead `(?=…)`, negative look-ahead `(?!…)`,
+  look-behind, backreferences and named groups work; flags `i`, `m`, `s`.
+- `check.request(…)` and the reply's `requests` carry `requestHeaders`,
+  `postData` (text; base64 with `postDataBase64: true` when not UTF-8; cut at
+  1 MiB with `postDataTruncated: true`) and `responseHeaders`.
+  `.bodyKeys(['a', 'b'])` wants exactly these top-level JSON keys;
+  `.headers({ 'X-Key': /^k\d$/ })` matches names case-insensitively.
+- `.state('started')` counts a request as soon as it is sent, so
+  `.count(1).state('started')` holds while a mock still delays or holds it.
+- `mock(url, { patch: { status, headers, json, body } })` sends the request to
+  the real backend and rewrites its response; `json` is a JSON merge patch
+  (`null` deletes a key) onto a JSON object body, else the new body.
+- `mock(url, { hold: 'save', json: … })` keeps the request unsent until
+  `release('save')`, then answers it (or sends it on, without a response
+  option); with `passthrough: true` (or `patch`) the request reaches the
+  backend and its response is held instead. `release` waits until something
+  is held, so it can come before the action's request starts; holds outlive
+  the run. The native `advanceTime` step explicitly advances page Date and timers;
+  mock `delay` remains a network delay.
+
+## Porting from Playwright
+
+| Playwright | @povio/lightning-panda |
+|---|---|
+| `page.getByRole('button', { name: 'X' })` | `button('X')` |
+| `locator.filter({ visible: true }).first()` | `loc.visible().first()` |
+| `page.getByRole('dialog').filter({ hasText }).last().getByRole('button', …)` | `dialog().hasText(…).last().button(…)` |
+| `await expect(loc).toBeVisible()` / `toHaveText` / `toHaveCount` | `check(loc).visible()` / `.text()` / `.count()` |
+| `await expect.poll(() => loc.count()).toBe(1)` | `check(loc).count(1)` |
+| `Promise.all([page.waitForResponse(…), loc.click()])` | `loc.click()` then `check.request(method, path).status(200)` |
+| `browser.newContext({ storageState }) + newPage + goto` | `lp.profile(...)` once, then `lp.page({ as, route })` |
+| `page.evaluate(fn)` | `evaluate('expression', 'name')` (an expression string, no closures; promises are awaited) |
+| `page.addInitScript(src)` | `lp.page({ as, initScripts: [src] })`, or `await page.addInitScript(src)` before a `goto` / `reload` |
+| `page.waitForURL(url)` | `waitForUrl(url)` |
+| `page.route(url, r => r.fulfill(…))` | `mock(url, { … })` as a step |
+| `frameLocator('#editor').getByRole(…)` | `css('#editor').frame().role(…)` |
+| helpers that retry clicks or re-open dropdowns | delete them: actions wait for actionability and settle |
+
+## When a run fails
+
+`page.run` throws `RunError` with the step index and why that step was still
+waiting when it timed out, for example:
+
+- `matched no element`: wrong locator, or the UI never got there; check the
+  step before it.
+- `strict mode violation: … matched 3 elements: <button> "Edit", …`: scope or
+  filter the locator.
+- `<div> intercepts pointer events`: an overlay covers the element; close it
+  first or click what the user would click.
+- `element is disabled` / `not editable` / `not visible`.
+- `no matching request yet` / `last match was {…status: 500…}`: the request
+  check; the reply's `requests` lists everything the page requested.
+
+Do not raise timeouts to fix a failure: a step waits only for its own
+condition, so a timeout means the condition never held.
+
+## Do not
+
+- Do not add waits, sleeps or retry loops; do not wrap steps in try/catch.
+- Do not drive login or seeding through the UI; use the profile and the API.
+- Do not send one `run` per step "to be safe": it costs a round trip per step
+  and request checks only see their own run.
+- Do not share a page between tests; take a new one per test.
+
+## Screenshots
+
+Visual checks run in the browser, in the same `run` as the steps that lead
+to the state (needs a browser built with the `render` feature):
+
+```ts
+await page.run([
+  label('Email').fill('ada@example.com'),
+  matchScreenshot('login-filled'),                     // viewport
+  css('.card').matchScreenshot('login-card'),          // one element's box
+  matchScreenshot('login-full', { fullPage: true }),
+]);
+await page.matchScreenshot('dashboard', { maxDiffPixels: 20 });  // one-step form
+```
+
+- Baselines are `__screenshots__/<name>.png` (+ `<name>.json` with the
+  display-list hash) beside the test file; `dir` overrides. Commit them.
+- First run (no baseline): the image is written and the test fails. Run once
+  with `LP_UPDATE_SNAPSHOTS=1` (or `bun test -u`) to write or refresh all.
+- A mismatch throws `ScreenshotMismatchError` (`.result.diffPixels`,
+  `.result.files`) and writes `<name>.actual.png` and `<name>.diff.png`
+  (differing pixels in red). Look at the diff before updating a baseline.
+- Rendering is deterministic on the CPU: compare exactly by default. Use
+  `threshold` (0-1, per channel) or `maxDiffPixels` only for known noise.
+- What is captured: the live DOM after script, every stylesheet (including
+  ones added or edited by script), input/textarea/select state, the window
+  scroll position, viewport and device scale factor, images and fonts loaded
+  through the page's network (mocks apply). Not captured: canvas and video
+  pixels, iframe contents, element scroll offsets, `:hover`/`:focus` styles,
+  the caret, running animations. Pixels come from lightningpanda's renderer
+  (Blitz), never compare them with Chromium screenshots.
+
+`downloadCount(as)` reads the current page's native initiated-download count without consuming positive download waits. Compare snapshots before and after a settled preview action to assert no new downloads; the count persists across batches on the same page.

package/NOTICE

@@ -0,0 +1,27 @@
+lightningpanda
+Copyright (C) 2026 Povio and contributors
+
+This project is a Rust rewrite of Lightpanda Browser
+(https://github.com/lightpanda-io/browser), Copyright (C) 2023-2026
+Lightpanda (Selecy SAS), Francis Bouvier, Pierre Tachoire; licensed under the GNU Affero General Public License v3.0 only.
+The design, module structure, behaviour and tests are derived from the
+upstream source at commit 2ad38773fd674d3c9cea26a263b814ee46f6ba84.
+
+lightningpanda is distributed under the same license, AGPL-3.0-only; see
+LICENSE. Network users of a modified version must be offered its source
+(AGPL section 13).
+
+It dynamically links JavaScriptCore (WebKit, LGPL-2.0+/BSD). Standard macOS
+archives use the operating-system framework. The optional macOS ARM64 fork
+archive includes a separately built, patched JavaScriptCore shared library.
+That variant includes upstream license files and identifies the matching
+JavaScriptCore source archive supplied with the same release. The source
+archive retains upstream notices and includes the exact WebKit revision,
+Lightningpanda patches and build instructions.
+
+crates/lp-dom/src/stylo/ua.css is the HTML user-agent stylesheet of
+blitz-dom (https://github.com/DioxusLabs/blitz), derived from Mozilla
+Firefox's html.css, under the Mozilla Public License 2.0 (header kept),
+with Chrome's defaults for links and form controls.
+crates/lp-dom/src/stylo/hints.rs adapts blitz-dom's presentational hints
+(MIT OR Apache-2.0). Style computation uses Stylo (MPL-2.0).

package/README.md

@@ -1,3 +1,116 @@
-# Temporary Holding Version
+# @povio/lightning-panda
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Lightningpanda browser CLI and typed testing API in one package.
+
+E2E tests for `bun test` on Lightningpanda. A test sends its whole scenario as
+one `LP.run` command: the browser runs every step itself (locating, acting,
+waiting for the app to settle, checking) and replies once.
+
+```ts
+import { Lightningpanda, button, check, dialog, text } from '@povio/lightning-panda';
+
+const lp = await Lightningpanda.connect('ws://127.0.0.1:9222/'); // or Lightningpanda.launch()
+await lp.profile('employee', { url: 'http://localhost:3000/platform', localStorage: { token } });
+
+test.concurrent('closes a position', async () => {
+  const position = await api.createPosition();
+  await using page = await lp.page({ as: 'employee', route: `/positions/${position.id}` });
+  const r = await page.run([
+    check(text(position.number)).visible(),
+    button('Settings').press('Enter'),
+    dialog().hasText('will be closed').button('Close Position', { exact: true }).click(),
+    check.request('POST', `/positions/${position.id}/close`).status(200),
+    check(button('Reopen Position')).count(1),
+  ]);
+});
+```
+
+- **Pages.** `lp.profile(name, …)` keeps signed-in pages booted ahead
+  (`Lightningpanda.registerPreparedPage`); `lp.page({ as, route })` takes one
+  and attaches in one call. `route` is a same-document navigation
+  (`pushState` + `popstate`) run as the first step of the first `run`, so the
+  app does not boot again. `url` navigates instead. With no page waiting, one
+  is booted for the test.
+- **Connections.** `connect(ws, { connections: 4 })` opens one browser thread
+  per connection, each with its own pools. A test takes a page from the
+  connection with the fewest open pages, and a connection boots replacements
+  as soon as it has no open page, in parallel with tests on the others.
+- **Fork mode.** Against `lightningpanda serve --fork` each `lp.page()` opens
+  its own connection, which the server forks from a process that booted the
+  profile once: the page starts booted in about 20 ms, shares nothing with
+  other tests, and its process exits when the page closes. `connections` and
+  `pool` then make no difference. `setup` steps in a profile run once on the
+  booted page (sign-in flows, opening a view, filling filters) and every page
+  starts from their result. `base: 'otherProfile'` builds a snapshot on top of
+  another one: only its own `setup` runs, on a fork of that snapshot (boot on
+  the login page once, sign in once, then one snapshot per test file).
+- **Locators** are data: `css`, `testId`, `text`, `label`, `placeholder`,
+  `role` (and `button`, `dialog`, `link`, …), chained inside one another
+  (`dialog().button('OK')`), filtered (`.visible()`, `.hasText()`,
+  `.hasNotText()`, `.has()`, `.hasNot()`) and picked (`.first()`, `.last()`,
+  `.nth(i)`). Strings match case-insensitive substrings unless `{ exact: true }`;
+  a `RegExp` (flags `i`, `m`, `s`) tests the whitespace-normalized text.
+- **Steps**: `.click()`, `.fill(v)`, `.press('Enter' | 'Shift+Tab' | …)`,
+  `.check()`, `.uncheck()`, `.focus()`, `.read(as)`; `check(loc).visible()`,
+  `.hidden()`, `.text()`, `.containsText()`, `.value()`, `.count()`,
+  `.checked()`, `.not.…`; `check.request(method, path).status(n)` /
+  `.count(n)`; `goto(url)`, `route(url)`, `evaluate(expr, as)`.
+- **Waiting** happens in the browser. A step that does not hold yet is tried
+  again when the DOM changes; an action settles before the next step (the
+  page goes quiet: no queued task, no request the action started, no timeout
+  due within 50 ms, no pending animation frame or navigation); a request
+  check waits for the request log. Each step has its own timeout (5 s default,
+  `page.run(steps, { timeout })` or per step).
+- **The reply** has `values` (reads), `results` (per step), `requests` (every
+  request the page made during the run), `screenshots` and `ms`. A failure
+  throws `RunError` naming the step and why it was still waiting.
+- **Screenshots** (a browser built with the `render` feature):
+  `matchScreenshot('home')`, `css('#card').matchScreenshot('card')` or
+  `await page.matchScreenshot('home', { fullPage: true })` render the page in
+  the browser (Blitz, CPU) and compare it there with
+  `__screenshots__/home.png` beside the test file. A baseline is sent once
+  per connection; a render whose display list matches the one recorded in
+  `home.json` passes without rasterizing. A missing baseline is written and
+  fails the test; `LP_UPDATE_SNAPSHOTS=1` (or `bun test -u`) rewrites
+  baselines; a mismatch throws `ScreenshotMismatchError` and writes
+  `home.actual.png` and `home.diff.png`. Options: `threshold` (0-1 per
+  channel), `maxDiffPixels`, `maxDiffPixelRatio`, `clip`, `fullPage`, `dir`.
+  `expect.extend(screenshotMatchers)` adds `await expect(page).toMatchScreenshot(name)`.
+  Baselines come from lightningpanda's renderer: Chromium screenshots do not
+  match them pixel for pixel.
+
+## Install
+
+```sh
+npm install --save-dev @povio/lightning-panda
+# Or: bun add --dev @povio/lightning-panda
+npx lightningpanda serve --port 9222
+```
+
+For release candidates, install `@povio/lightning-panda@next`.
+
+The package bundles browsers for **macOS 14+ on Apple Silicon and Intel**, with
+layout, screenshots and PDF rendering enabled. No Rust toolchain, install
+scripts or binary downloads are needed. The API supports Node.js 22+ and Bun;
+Bun loads TypeScript sources, while Node loads compiled JavaScript and types.
+On other operating systems, use `Lightningpanda.connect()` with a remote
+browser. Installing/importing the client does not launch a local browser.
+
+`Lightningpanda.launch()` selects `bin`, then `$LIGHTNINGPANDA_BIN`, then the
+bundled browser for the current architecture, then a sibling browser in a
+legacy release archive. The CLI also respects `$LIGHTNINGPANDA_BIN`.
+
+The bundled browsers use macOS's system JavaScriptCore. **Fork mode requires
+a separately built patched JavaScriptCore browser**; select that browser with
+`bin` or `$LIGHTNINGPANDA_BIN` when using `args: ['--fork']`.
+
+The package is licensed under AGPL-3.0-only; see the included `LICENSE` and
+`NOTICE`. Maintainers: see
+[publishing instructions](https://github.com/povio/lightningpanda/blob/main/docs/NPM_PUBLISHING.md).
+
+Coding agents: read [LLM.md](LLM.md) before writing tests.
+
+`examples/positions-close.test.ts` is TOS's `positions-close.e2e.ts` ported.
+`bench/scripts/cdp-perf.mjs --filter '^(pw\.)?tos\.'` runs the same flow
+against a TOS-shaped app in the bench site, as Playwright, step by step, as one
+run, and as one run on a pre-booted page.

package/dist/binary.d.ts

@@ -0,0 +1,7 @@
+/** Shared by the CLI and launch(); never fall back to our own CLI on PATH. */
+export declare function resolveBinary({ platform, arch, root, env, }?: {
+    platform?: string;
+    arch?: string;
+    root?: string;
+    env?: NodeJS.ProcessEnv;
+}): string;

package/dist/cdp.d.ts

@@ -0,0 +1,23 @@
+export declare class CdpError extends Error {
+    readonly method: string;
+    readonly code: number;
+    /** The error's `data` (a failed `matchScreenshot` carries its images). */
+    readonly data?: unknown | undefined;
+    constructor(method: string, code: number, message: string, 
+    /** The error's `data` (a failed `matchScreenshot` carries its images). */
+    data?: unknown | undefined);
+}
+export declare class Cdp {
+    private ws;
+    private nextId;
+    private pending;
+    private closed;
+    private constructor();
+    static open(url: string): Promise<Cdp>;
+    send<T = any>(method: string, params?: object, sessionId?: string): Promise<T>;
+    /** Sends without waiting; a failure is ignored (cleanup). */
+    post(method: string, params?: object, sessionId?: string): void;
+    close(): void;
+    private onMessage;
+    private fail;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { spawn } from "node:child_process";
+
+// src/binary.ts
+import { statSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+function resolveBinary({
+  platform = process.platform,
+  arch = process.arch,
+  root = fileURLToPath(new URL("../", import.meta.url)),
+  env = process.env
+} = {}) {
+  if (env.LIGHTNINGPANDA_BIN)
+    return env.LIGHTNINGPANDA_BIN;
+  const bundled = join(root, "native", `${platform}-${arch}`, "lightningpanda");
+  if (statSync(bundled, { throwIfNoEntry: false })?.isFile())
+    return bundled;
+  const sibling = join(root, "..", "lightningpanda");
+  if (statSync(sibling, { throwIfNoEntry: false })?.isFile())
+    return sibling;
+  if (platform !== "darwin" || !["arm64", "x64"].includes(arch)) {
+    throw new Error(`Lightningpanda has no bundled browser for ${platform}-${arch}. The browser supports macOS 14+ on arm64 and x64. Use Lightningpanda.connect() for a remote browser, or set LIGHTNINGPANDA_BIN.`);
+  }
+  throw new Error(`Missing bundled browser: ${bundled}. Reinstall @povio/lightning-panda or set LIGHTNINGPANDA_BIN to a built browser.`);
+}
+
+// src/cli.ts
+try {
+  const child = spawn(resolveBinary(), process.argv.slice(2), { stdio: "inherit" });
+  const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
+  const forward = (signal) => {
+    child.kill(signal);
+  };
+  for (const signal of signals)
+    process.on(signal, forward);
+  const cleanup = () => {
+    for (const signal of signals)
+      process.off(signal, forward);
+  };
+  child.once("error", (error) => {
+    cleanup();
+    console.error(`lightningpanda: ${error.message}`);
+    process.exitCode = 1;
+  });
+  child.once("exit", (code, signal) => {
+    cleanup();
+    if (signal)
+      process.kill(process.pid, signal);
+    else
+      process.exitCode = code ?? 1;
+  });
+} catch (error) {
+  console.error(`lightningpanda: ${error instanceof Error ? error.message : error}`);
+  process.exitCode = 1;
+}