@itmetsam/samurai-framework 0.1.0 → 0.2.0

package/docs/superpowers/specs/2026-09-29-network-interception-design.md

@@ -1,91 +0,0 @@
-# Network interception — design
-
-Date: 2026-09-29
-Status: implemented (see "Implementation notes")
-Roadmap item: 9
-Depends on: bidi-foundation, network-tracking
-
-## Goal
-
-Mock, block and modify requests from tests.
-
-```ts
-await page.route("**/api/users", (route) =>
-  route.fulfill({ status: 200, json: [{ id: 1 }] }));
-await page.route(/\.(png|jpg)$/, (route) => route.abort());
-await page.route("**/api/**", (route) =>
-  route.continue({ headers: { ...route.request().headers, "x-test": "1" } }));
-await page.unroute("**/api/users");
-```
-
-## Non-goals
-
-- Modifying responses of real requests (`network.continueResponse`, phase `responseStarted`); a later addition.
-- `route.fetch()` (BiDi has no way to perform a request and hand back the response); use `continue` or `fulfill`.
-- HTTP auth (`authRequired` + `continueWithAuth`); planned follow-up `page.setHttpCredentials`.
-- Service worker requests.
-
-## API
-
-```ts
-page.route(url: string | RegExp, handler: (route: Route) => void | Promise<void>): Promise<void>;
-page.unroute(url: string | RegExp, handler?): Promise<void>;
-page.unrouteAll(): Promise<void>;
-
-class Route {
-  request(): Request;
-  fulfill(o: { status?: number; headers?: Record<string,string>; contentType?: string; body?: string | Buffer; json?: unknown }): Promise<void>;
-  continue(o?: { url?: string; method?: string; headers?: Record<string,string>; postData?: string | Buffer }): Promise<void>;
-  abort(): Promise<void>;                    // BiDi failRequest has no error code
-  fallback(): Promise<void>;                 // pass to the next matching route
-}
-```
-
-URL matching: a string without `*` is an exact match; with `*`/`**` a glob (`*` = no `/`, `**` = anything); a `RegExp` tests the full URL.
-
-## Components — `src/network/router.ts` (new)
-
-- **One intercept per page**, not per route: on the first `page.route`, send `network.addIntercept { phases: ["beforeRequestSent"], contexts: [pageContext] }` (no `urlPatterns`); matching happens in Node. This avoids translating globs/RegExps to BiDi URL patterns and keeps ordering logic in one place. Unmatched blocked requests are released immediately with `continueRequest { request }`.
-  - Optimisation: when every registered route is a plain exact string, pass `urlPatterns: [{ type: "string", pattern }]` so unrelated traffic is never blocked. Recomputed (remove + add intercept) when routes change.
-- On `network.beforeRequestSent` with `isBlocked: true` for this page (`ContextTree`): find matching routes, newest first; create a `Route`; call the handler. `fallback()` moves to the next match; when none remain (or none matched) the request continues unchanged.
-- Resolution mapping:
-  - `fulfill` → `network.provideResponse { request, statusCode, reasonPhrase, headers, body }`. `json` sets body `JSON.stringify` and content type `application/json`; `Buffer` body is `{ type: "base64" }`, string is `{ type: "string" }`. `Content-Length` computed unless supplied. Default status 200.
-  - `continue` → `network.continueRequest { request, url, method, headers, body }` (headers as `{ name, value: { type: "string", value } }`).
-  - `abort` → `network.failRequest { request }`.
-- **Every blocked request must be resolved exactly once.** Guarantees:
-  - a second resolution call throws `Error("route already handled")`;
-  - a handler that throws → the request is failed (`failRequest`) and the error is stored and rethrown to the test after the next `await` boundary via `page.routeErrors` surfaced in the runner (same channel as page errors);
-  - a handler that returns without resolving → after the handler's promise settles the route auto-`continue`s and logs a warn (safer than a hang);
-  - `unroute*` and `dispose` resolve pending routes by continuing them, then `removeIntercept`.
-  - a route pending longer than `network.routeTimeout` (default 30000) logs an error and is continued.
-- Blocked requests count as in flight for `waitForNetworkIdle` (tracking spec).
-- Requests from other contexts are untouched: the intercept is scoped with `contexts`.
-
-## Errors
-
-| Situation | Behaviour |
-|---|---|
-| Resolve twice | `Error("route already handled")` |
-| Handler throws | request failed, error reported to the test |
-| Browser rejects (`no such request`, request already finished) | `BiDiError` rethrown from the Route method |
-| Redirect to a URL matching another route | the new hop is a new blocked request, routed independently |
-
-## Testing
-
-- Unit (stub connector): single intercept for multiple routes; exact-only optimisation and re-registration; glob and RegExp matching; newest-first ordering and `fallback`; each resolution's payload (fulfill json/Buffer/headers/default status, continue overrides, abort); unmatched blocked request continued; double resolve; throwing handler → `failRequest`; non-resolving handler → auto-continue + warning; `unroute` continues pending then removes the intercept; foreign-context request ignored.
-- Browser (local server): fulfil an XHR with JSON and assert the page sees it; abort an image and see `onerror`; continue with an added header and echo it from the server; a redirect chain; a route that never resolves does not hang the page.
-- TDD: tests first.
-
-## Implementation notes
-
-- **Where:** `network/url-match.ts` (`matchUrl`, `isExactString`, `samePattern`), `network/router.ts` (`Router`, `Route`), `Page.route/unroute/unrouteAll/routeErrors`, config `network.routeTimeout` (default 30000), and `RouteErrorsError` in `runner/page-logs-report.ts`. `network-tracker.ts` now exports `toRequest`.
-- **One intercept per page, matching here**, as designed. The router listens to `network.beforeRequestSent` itself (not through the tracker, so it works when `network.track` is false) and only acts on requests held by one of its own intercept ids, in this page or its frames. Adding a route that widens what must be blocked adds the new intercept first and removes the old one after, so nothing slips through.
-- **Exact-URL optimisation is conservative.** `urlPatterns` are sent only when every route is an exact string already in `new URL(x).href` form (so the browser reads it as we do); anything else blocks everything and matches in Node. If a browser rejects `urlPatterns` (`invalid argument`) the router falls back to blocking everything and remembers that per connection.
-- **Every held request is answered exactly once:** a second answer throws `route already handled`; a handler that throws fails the request (`failRequest`) and the error is kept in `page.routeErrors()` (message `route handler for <url> threw: <message>`, cause attached); a handler that returns without answering lets the request continue with a `warn` (so a handler must `await` its answer; answering later from a callback is too late); a request pending longer than `routeTimeout` continues with an `error` log; `unroute*` and `dispose` continue the requests the removed routes still hold before the intercept goes; `fallback()` hands the request to the next older matching route, and past the last one it continues unchanged.
-- **Runner:** route handler errors fail a passing test (`RouteErrorsError`, `<n> route handler error(s): …`), regardless of `logs.failOnPageError`; they take precedence over page errors, and a test that already failed keeps its own error.
-- **`fulfill`:** status defaults to 200 with the standard reason phrase; `json` implies `application/json`; `content-type` and `content-length` (bytes) are added only when the headers you pass have none, compared case-insensitively; `json` together with `body` is a `TypeError`.
-- **`continue`:** only what you pass is sent. A new `postData` always comes with a matching `content-length` (dropping the request's old one): otherwise Firefox keeps the old header and cuts the new body off (or waits for missing bytes). `headers` replaces all request headers, so spread `route.request().headers` to add one.
-- **Firefox 153 facts** (browser tests): `fulfill`, `abort`, `fallback`, header changes, method changes and body replacement work for `fetch`, images and documents, iframes included; mocking a page's document by routing its URL works. **Changing the URL only works for navigations:** for `fetch`, XHR and images Firefox fails the request (`AbortError` / error event) although the rewritten request reaches the server, hence the note on `ContinueOptions.url`. A `fetch` from a page that is itself a JSON document (Firefox's JSON viewer) fails whatever the routes: use an HTML page in tests.
-- Blocked requests stay in flight for `waitForNetworkIdle` (browser test: idle waits for a request a handler holds for 400 ms).
-- **Not done:** `route.fetch()`, modifying real responses, HTTP auth; unchanged from the non-goals.
-- Tests: `network/url-match.test.ts`, `network/router.test.ts` (38), "Page routing" block in `browser/page.test.ts`, route errors in `runner/page-logs-report.test.ts`, `network/router.browser-test.ts` (port 9241, local server, 20 tests).

package/docs/superpowers/specs/2026-09-29-network-tracking-design.md

@@ -1,86 +0,0 @@
-# Network tracking and real network idle — design
-
-Date: 2026-09-29
-Status: implemented (see "Implementation notes")
-Roadmap item: 5
-Depends on: bidi-foundation
-
-## Goal
-
-Replace `Page.waitForNetworkIdle` (today it only waits for the next `browsingContext.load` event, leaks its listener, and never resolves if `load` already fired) with a tracker built on `network.beforeRequestSent`, `network.responseCompleted` and `network.fetchError`. The same tracker later feeds interception and response data.
-
-```ts
-await page.navigateTo("example.com");
-await page.waitForNetworkIdle();                       // no requests in flight for 500ms
-await page.waitForNetworkIdle({ idleTime: 200, timeout: 10000 });
-page.on("request", (r) => …); page.on("response", (r) => …); page.on("requestfailed", (r) => …);
-```
-
-## Non-goals
-
-- Blocking or altering requests (interception spec), response bodies (network-data spec).
-- Tracking requests of other tabs.
-- WebSocket / SSE frames (BiDi has no events for them).
-
-## Components
-
-### `src/network/network-tracker.ts` (new)
-
-```ts
-class NetworkTracker {
-  static async start(connector, tree: ContextTree, contextId: string, options?: TrackerOptions): Promise<NetworkTracker>;
-  readonly inflight: number;
-  waitForIdle(options: { idleTime: number; timeout: number }): Promise<void>;
-  on(event: "request" | "response" | "requestfailed", listener): void;
-  off(…): void;
-  dispose(): Promise<void>;
-}
-interface TrackerOptions { ignore?: (request: NetworkRequest) => boolean }   // default: ignore none
-```
-
-- Subscribes (refcounted) to the three network events. Events are kept when `tree.isWithin(event.context, contextId)`.
-- In-flight key: `${request.request}:${request.redirectCount}`. `beforeRequestSent` adds; `responseCompleted` and `fetchError` with the same key remove. A redirect is a new key, so a redirect chain counts as one live request at a time. Events with unknown keys (tracker started mid-request) are ignored on removal.
-- Blocked requests (`isBlocked: true`, interception spec) stay in flight until resolved, so idle never fires while a route handler is pending.
-- Never-completing requests (long-poll, SSE) would block idle forever: `ignore` lets callers exclude them, and `waitForIdle` also stops at its timeout.
-- `waitForIdle`: resolves once `inflight === 0` has held for `idleTime` (a timer restarts on every new request). Checks the current state first, so it resolves immediately on an already-idle page (after `idleTime`). Rejects with `WaitTimeoutError` including the URLs still in flight (max 5) at the deadline.
-- Started at `Page` creation, always on. Cost: three event listeners and a `Map`. Config `network.track: false` disables it; `waitForNetworkIdle` then throws `Error("network tracking is disabled")`.
-- Must exist before the first navigation, otherwise requests started earlier are missed and idle can fire early; `Page` creation awaits `NetworkTracker.start`.
-
-### `Page` changes
-
-```ts
-waitForNetworkIdle(options?: { idleTime?: number; timeout?: number }): Promise<void>; // 500ms / navigation timeout
-on/off("request" | "response" | "requestfailed", …)
-```
-
-- `idleTime` default 500 (config `network.idleTime`), `timeout` default from navigation spec (30000).
-- The old zero-argument call keeps working. The old behaviour (resolve on `load`) is gone; `navigateTo` with `wait: "complete"` covers it (navigation-waits spec).
-- `Request` wrapper: `url`, `method`, `headers` (plain object, lower-cased names), `resourceType` (from `initiatorType`/`destination`), `navigation`, `redirectedFrom`. `Response`: `url`, `status`, `statusText`, `headers`, `fromCache`, `request`. Bodies are not included here.
-
-## Errors
-
-| Situation | Error |
-|---|---|
-| Idle not reached | `WaitTimeoutError` → message `waitForNetworkIdle(): still <n> request(s) in flight after <t>ms: <urls>` |
-| Tracker disabled | `Error("network tracking is disabled")` |
-| Page closed while waiting | rejects with `Error("page closed")` |
-
-## Testing
-
-- Unit (stub connector emitting scripted events): add/remove keys; redirect chain (same id, incrementing `redirectCount`) counts as one at a time; `fetchError` removes; event from an iframe context counted, from an unrelated context ignored; idle timer restarts on a new request; immediate idle on quiet page; timeout message lists URLs; `ignore` predicate; `dispose` unsubscribes and removes listeners; disabled config.
-- Browser: local `node:http` server with `/slow` (300ms) and a redirect route; page fires three fetches on a timer; `waitForNetworkIdle` resolves after the last one plus `idleTime`, not before; a hanging route is reported on timeout.
-- TDD: tests first.
-
-## Implementation notes
-
-- **Where it lives:** `src/network/network-tracker.ts` (`NetworkTracker`, `NetworkIdleTimeoutError`, `toHeaders`), `Page.waitForNetworkIdle/on/once/off/startNetworkTracking`, config `network: { track, idleTime }` (in `types/config.d.ts`), `PageSettings` (3rd `Page` constructor argument) to override config in tests.
-- **Start:** the tracker is created lazily by `Page` (its constructor stays synchronous), and eagerly by `Browser.launch` and `Browser.newPage` through `page.startNetworkTracking()`, so requests made before the first navigation are seen. A `Page` built by hand starts tracking on first use and misses earlier requests.
-- **`NetworkIdleTimeoutError extends WaitTimeoutError<string[]>`**: `last` holds up to five in-flight URLs and the message is the one from the spec.
-- **`page.on/once/off`** are typed for `request` / `response` / `requestfailed` and start tracking on first use. Listener exceptions are logged, never break tracking.
-- **Redirects:** a hop is linked to the previous one (`redirectedFrom`) using the `request id:redirect count` key. A redirect response keeps its request for the next hop; other responses and failures drop it.
-- **`requestfailed`** payload is the request plus `errorText`.
-- **Disabled tracking:** `waitForNetworkIdle()` rejects with `network tracking is disabled`; nothing is subscribed.
-- **`dispose()`** rejects pending waits with `page closed`, removes listeners and unsubscribes; `Page.dispose()` disposes the tracker before the context tree it reads.
-- **The old `waitForNetworkIdle`** (wait for the next `load`) is gone; `navigateTo(…, "complete")` covers that.
-- **Test runner:** `npm run test:browser` now passes `--test-concurrency=1`. All browser tests launch Firefox with the same profile directory, and launching six at once made some fail to start.
-- Tests: `network/network-tracker.test.ts`, the "Page network tracking" block in `browser/page.test.ts`, `network/network-tracker.browser-test.ts` (port 9237, local `node:http` server with slow, redirect, failing, hanging and iframe routes).

package/docs/superpowers/specs/2026-09-29-page-api-design.md

@@ -1,90 +0,0 @@
-# Page API completeness — design
-
-Date: 2026-09-29
-Status: implemented (see "Implementation notes")
-Roadmap item: 11
-Depends on: bidi-foundation, script-call-function
-
-## Goal
-
-Finish the everyday page surface with BiDi commands that have no framework wrapper yet, and fix `captureScreenshot`, which currently throws its result away (`// TODO: Store screenshot`).
-
-```ts
-await page.setViewport({ width: 1280, height: 720, devicePixelRatio: 2 });
-await page.reload({ wait: "complete", ignoreCache: true });
-await page.goBack(); await page.goForward();
-const png = await page.screenshot({ path: "out/home.png", fullPage: true });
-await page.locator("//header").screenshot();
-await page.pdf({ path: "out/page.pdf", format: "A4" });
-page.url(); await page.title();
-await page.close({ runBeforeUnload: true });
-```
-
-## Non-goals
-
-- Window management (`browser.setClientWindowState`).
-- PDF header/footer templates (not in BiDi).
-- Multi-page tab APIs (contexts spec).
-
-## API and mapping
-
-| Method | BiDi | Notes |
-|---|---|---|
-| `setViewport({ width, height, devicePixelRatio? })` | `browsingContext.setViewport { context, viewport, devicePixelRatio }` | `null` resets. Validates positive integers. |
-| `reload({ wait?, ignoreCache? })` | `browsingContext.reload` | same wait/timeout/`NavigationError` semantics as `navigateTo` (navigation-waits spec) |
-| `goBack()` / `goForward()` | `browsingContext.traverseHistory { delta: ∓1 }` | resolves `true`; on `no such history entry` resolves `false` (not an error, matches Playwright's null) |
-| `screenshot(options?)` | `browsingContext.captureScreenshot` | returns `Buffer`; see below |
-| `Locator.screenshot(options?)` | `captureScreenshot` with `clip: { type: "element", element: SharedReference }` | scrolls into view first (`attached`+`visible` wait) |
-| `pdf(options?)` | `browsingContext.print` | returns `Buffer`; `path`, `landscape`, `scale`, `pageRanges`, `margin`, `background`, `format` (`A4`/`Letter` → page size in cm) |
-| `url()` | `callFunction(() => location.href)` | |
-| `title()` | `callFunction(() => document.title)` | |
-| `close({ runBeforeUnload? })` | `browsingContext.close { promptUnload }` | further use of the page throws `Error("page closed")`; disposes trackers/subscriptions |
-
-### Screenshot
-
-```ts
-interface ScreenshotOptions {
-  path?: string;                       // written (dirs created) in addition to being returned
-  fullPage?: boolean;                  // origin: "document"; default "viewport"
-  clip?: { x: number; y: number; width: number; height: number };
-  type?: "png" | "jpeg";               // format.type
-  quality?: number;                    // 0–100 → format.quality 0–1, jpeg only
-}
-```
-
-- Base64 result decoded to a `Buffer`.
-- Default output dir for auto-named screenshots (test failure screenshots, next step of the runner) from config `screenshotDir` (default `result/screenshots`); this spec only provides the mechanism.
-- `clip` and `fullPage` combine as BiDi `clip: { type: "box", x, y, width, height }` with `origin: "document"`.
-
-### Default viewport
-
-`use: { viewport: { width: 1280, height: 720 } }` in config applied when a `Page` is created, so headless screenshots are reproducible. `viewport: null` keeps the browser default.
-
-## Errors
-
-| Situation | Error |
-|---|---|
-| Invalid viewport numbers | `RangeError` before sending |
-| `jpeg` quality out of range or with png | `RangeError` |
-| Locator not attached/visible within timeout | `ActionTimeoutError` (`action: "screenshot"`) |
-| Use after `close()` | `Error("page closed")` |
-| Screenshot/print rejected (`unable to capture screen`) | `BiDiError` |
-
-## Testing
-
-- Unit (stub connector): payload for each method; base64 → Buffer and `path` write (temp dir); clip/fullPage/jpeg mapping; `goBack` false on `no such history entry`; viewport validation; `close` sets closed state and disposes trackers; default viewport applied at creation; `Locator.screenshot` uses element clip with the resolved reference.
-- Browser: viewport 400×300 reflected by `innerWidth`; PNG magic bytes; full-page taller than viewport; element screenshot dimensions ≈ bounding box; history back/forward across two `about:blank`-style data pages; PDF starts with `%PDF`.
-- TDD: tests first.
-
-## Implementation notes
-
-- **Where:** `browser/screenshot.ts` (`takeScreenshot`, `writeOutput`), `browser/pdf.ts` (`printPdf`, paper sizes), and on `Page`: `setViewport`, `applyDefaultViewport`, `reload`, `goBack`, `goForward`, `url`, `title`, `screenshot`, `pdf`, `close`, `closed`; `Locator.screenshot`. Config `use.viewport` (default 1280x720; `null` keeps the browser's own size).
-- **Image types go out as MIME types** (`image/png`, `image/jpeg`): Firefox silently answers a PNG for anything else (`"jpeg"` included). `quality` (0–100, jpeg only) is sent as a 0–1 fraction; the local `ImageFormat` typing was narrowed to five literal qualities and is now a `number`. `captureScreenshot`'s result type is `{ data: string }` (was `{}`).
-- **`screenshot`:** nothing but the context is sent by default; `fullPage` adds `origin: "document"`, `clip` a box (viewport coordinates, or document coordinates together with `fullPage`), `path` writes the file after creating folders. A quality without `type: "jpeg"`, or outside 0–100, is a `RangeError` before anything is sent. `Locator.screenshot` waits for attached + visible (with a scroll into view) and clips to the element (`ActionTimeoutError` with `action: "screenshot"`).
-- **The old `Page.captureScreenshot(clip, format, origin)` is left as it was;** `screenshot()` is the API to use. The auto-named failure screenshot and a `screenshotDir` config were not added ("this spec only provides the mechanism").
-- **`reload`** shares `navigateTo`'s handling (default wait `complete` or config, `NavigationError` named `reload(): <url> failed: …`, the navigation timeout, progress tracking for `wait: "none"`; the code moved into a private `Page.navigation()`). **Firefox 153 does not support `ignoreCache`** (`unsupported operation`), so asking for it throws `UnsupportedOperationError`.
-- **`goBack` / `goForward`** answer false on `no such history entry`. A new tab's initial `about:blank` is not a history entry. Walking a tab back past its first entry lands on Firefox's own start page, and a later `reload` there hung until the navigation timeout in one run; keep tests inside the entries they created.
-- **`setViewport`** validates positive integers (`RangeError`); `null` resets size and ratio. An omitted `devicePixelRatio` keeps the current one (BiDi's behaviour), so reset with `null` when a test set one. Firefox headless opens at 1227x682, hence the 1280x720 default, applied by `Browser.launch` / `newPage`.
-- **`pdf`:** `landscape`, `scale` (0.1–2, `RangeError`), `pageRanges`, `margin` (centimetres), `printBackground`, `format` (A0–A6, Letter, Legal, Tabloid, Ledger; unknown is a `RangeError`) and `path`. Browser test: A4 is about 595x842 pt, landscape swaps them, Letter is about 612x792 (found by inflating the PDF's compressed streams).
-- **`close({ runBeforeUnload })`** sends `browsingContext.close` (`promptUnload`), treats `no such frame` as already closed, then disposes what the page registered (errors from that are only logged). After it `page.closed` is true and `navigateTo`, `reload`, `goBack`, `goForward`, `screenshot`, `pdf`, `url`, `title`, `setViewport`, `waitForLoadState`, `addInitScript`, `route`, `locator` and the `getBy*` methods throw `page closed`; a second `close()` does nothing. Closing the browser's last tab may end the browser.
-- Tests: the "Page API" block in `browser/page.test.ts`, `browser/page-api.browser-test.ts` (port 9244; PNG dimensions read from the header, JPEG quality vs size, PDF page boxes, history, reload, close).

package/docs/superpowers/specs/2026-09-29-preload-scripts-design.md

@@ -1,82 +0,0 @@
-# `script.addPreloadScript` — design
-
-Date: 2026-09-29
-Status: implemented (see "Implementation notes")
-Roadmap item: 2
-Depends on: bidi-foundation, script-call-function
-
-## Goal
-
-Run code before any page script in every new document, so (a) the framework installs its own helper library once per document instead of re-sending probe source every poll, and (b) users get `page.addInitScript`.
-
-```ts
-await page.addInitScript(() => { window.__testMode = true });   // page's own world
-await page.addInitScript((flag) => { … }, { flag: 1 });
-```
-
-## Non-goals
-
-- Exposing binding functions (`exposeFunction`); `script.message` channels are used internally only (logs spec).
-- Removing scripts by handle from user code beyond the returned `dispose()`.
-
-## Components
-
-### `src/script/preload.ts` (new)
-
-```ts
-export interface PreloadHandle { readonly id: string; dispose(): Promise<void> }
-export async function addPreload(
-  connector: BiDiConnector,
-  options: { source: string; contexts?: string[]; sandbox?: string; args?: ChannelValue[] },
-): Promise<PreloadHandle>;
-```
-
-- Sends `script.addPreloadScript { functionDeclaration, contexts, sandbox, arguments }`; result `{ script }` is the id.
-- Preload scripts only affect documents created **after** registration. `addPreload` therefore also runs the same function once in every already-loaded context in scope (`browsingContext.getTree`, via `callFunction` in the same sandbox), so registration order never matters.
-- `dispose()` sends `script.removePreloadScript`; idempotent. Already-loaded documents keep the effect until they navigate; documented.
-
-### Framework helper realm
-
-- Name: sandbox `"samurai"`. A sandbox realm shares the DOM with the page but has its own JS globals, so page code cannot tamper with the helpers and helpers do not leak into `window`.
-- `src/script/helpers.ts` exports a function declaration that installs `globalThis.__samurai = { probeElement, resolveXpath, … }` in the sandbox realm.
-- `Page` registers it once at creation (`contexts: [rootContext]` includes its iframes automatically since preload scripts apply to child navigables of the listed top-level context).
-- Locator `callFunction` calls pass `sandbox: "samurai"` and call `(…a) => globalThis.__samurai.probeElement(…a)`. If the helper is missing (registration lost), the wrapper reinstalls it once and retries; a second miss throws `ScriptError`.
-
-### `page.addInitScript`
-
-```ts
-addInitScript(script: string | ((arg?: any) => void), arg?: unknown): Promise<PreloadHandle>;
-```
-
-- Runs in the page's main realm (no sandbox): it is meant to change what page scripts see.
-- Function form is serialized like `callFunction` (same `__name(` guard). `arg` goes through `toLocalValue` as the function's first argument.
-- All init scripts registered on a page dispose with it.
-
-## Errors
-
-| Situation | Error |
-|---|---|
-| Init script throws | Browser reports through `log.entryAdded` (javascript error); the logs spec surfaces it. Not a test failure by itself. |
-| Registration fails (`invalid argument`) | `BiDiError` rethrown from `addInitScript` |
-| Helper missing during a locator call | one reinstall + retry, then `ScriptError` |
-
-## Testing
-
-- Unit: payload shape (sandbox, contexts, arguments); the "also run in existing contexts" step calls `getTree` and one `callFunction` per context; `dispose` is idempotent; helper-missing retry path with a stub returning the missing-helper error once.
-- Browser: an init script sets `window.__x = 1`, then after `navigateTo` a locator-independent `evaluate` reads it; a script registered *after* load still applies to the current document (via the immediate run) and to the next navigation; the helper realm is invisible: `typeof window.__samurai === "undefined"` from the main realm; `dispose()` stops the effect on the next navigation.
-- TDD: tests first.
-
-## Implementation notes
-
-Deviations and details settled while implementing:
-
-- **Lazy install.** `Page` is constructed synchronously (tests and `Browser` build pages without I/O), so the helpers are not registered at creation. `Locator` awaits `HelperRealm.ensureInstalled()` before every probe; the first call registers, later calls reuse the cached promise (a failed install is retried). The immediate run covers any document loaded before the first probe.
-- **Missing helpers are detected with a marker, not error text.** The call wrapper is `(...args) => globalThis.__samurai ? probeElement(...args) : "samurai:helpers-missing"`. On the marker the locator calls `reinstall()` (runs the helpers again in the loaded documents, no new registration) and retries once; a second marker throws `ScriptError`.
-- **Only `probeElement` is installed.** `resolveXpath` from the draft is not added: nothing calls it yet, and the other element reads keep resolving the xpath inline.
-- **A `Locator` built by hand (no helper realm) still works:** it sends the probe source to the page realm on every poll, as before. `Page.locator()` always passes its realm.
-- **Channels are not supported yet.** `addPreload` has no `args`; BiDi preload arguments can only be channels, and the logs spec will add them when it needs `script.message`.
-- **`addInitScript` argument.** Preload scripts cannot take arguments, so the function is wrapped as `() => (<function>)(<JSON of arg>)`; `arg` must be JSON-serializable (`TypeError` otherwise, and for a `bigint` or a cycle). A string script is wrapped as `() => { <script> }` and takes no argument.
-- **Errors while running in an already-loaded document.** For `addInitScript` a throwing script is logged (`warn`) and the registration stays; for the framework helpers it fails the install. If the immediate run throws, the fresh registration is removed again.
-- **`page.dispose()`** (new) removes init scripts, the helper registration and the context tree; the page-api spec's `close()` should call it.
-- **Verified in Firefox:** preload scripts with a `sandbox` create the sandbox realm before page scripts; init scripts also apply to iframes created later; the page cannot reach or overwrite `__samurai` (it lives only in the sandbox realm). Firefox prints `TypeError: WeakMap key null …` from its own `browsingContext.sys.mjs` on stderr when an iframe loads under a preload script; it is harmless and unrelated to our code.
-- Tests: `script/{preload,helpers}.test.ts`, additions to `browser/page.test.ts` and `locator/locator-actions.test.ts`, `script/preload.browser-test.ts` (port 9234). The reply pumps in the fake-WebSocket tests are `unref`'d so a failing test can no longer hang the run.

package/docs/superpowers/specs/2026-09-29-script-call-function-design.md

@@ -1,107 +0,0 @@
-# `script.callFunction` — design
-
-Date: 2026-09-29
-Status: implemented (see "Implementation notes")
-Roadmap item: 1 (with `script.disown`)
-Depends on: bidi-foundation
-
-## Goal
-
-Replace string-built `script.evaluate` expressions with typed function calls. Arguments are serialized by the protocol (no JSON-in-JS-string escaping), elements travel as `SharedReference`s, and return values are deserialized to plain JS.
-
-```ts
-// before (locator.ts): xpath embedded via JSON.stringify inside a source string
-await this.evaluate(`document.evaluate(${JSON.stringify(xpath)}, …).singleNodeValue.focus()`);
-
-// after
-await script.call(target, (xpath) => { … }, [xpath]);
-```
-
-## Non-goals
-
-- Public `page.evaluate` (a later, tiny follow-up on top of this module).
-- Changing what the actionability probe checks.
-- Sandboxed realms (preload-scripts spec).
-
-## Components
-
-### `src/script/serialize.ts` (new)
-
-```ts
-export type Arg = unknown | ElementHandle;
-export function toLocalValue(value: Arg): LocalValue;
-export function fromRemoteValue(value: RemoteValue): unknown;
-```
-
-`toLocalValue` mapping: `undefined`/`null`/boolean/string → primitive types; number incl. `NaN`, `Infinity`, `-Infinity`, `-0` via the special-number form; `bigint`; `Date` → `date`; `RegExp` → `regexp`; `Array` → `array`; `Map` → `map`; `Set` → `set`; plain object → `object` (entries); `ElementHandle` → `{ sharedId, handle? }` reference; functions and symbols throw `TypeError("cannot serialize <type>")`. Cycles throw `TypeError` (depth cap 100 as a second guard).
-
-`fromRemoteValue` is the inverse for `RemoteValue` (`node` → `ElementHandle`, `window`/`function`/`error`/`promise` etc. → an opaque `RemoteObject` with `type` and `handle`; `error` → `Error` with the remote message).
-
-### `src/script/element-handle.ts` (new)
-
-```ts
-export class ElementHandle { readonly sharedId: string; readonly handle?: string; }
-```
-
-Node values returned by `callFunction` become `ElementHandle`s. A `sharedId` stays valid across scripts within the same document, also after the node was removed from the DOM (Firefox keeps a detached node resolvable while it is alive); after a navigation to another document the browser answers `no such node`. `ElementHandle` is internal; user code keeps using `Locator`.
-
-### `src/script/call-function.ts` (new)
-
-```ts
-export interface CallOptions {
-  awaitPromise?: boolean;            // default true
-  ownership?: "none" | "root";       // default "none"; "root" keeps a handle alive until disown
-  sandbox?: string;                  // realm sandbox name (preload-scripts spec)
-  thisArg?: Arg;
-}
-export async function callFunction<T = unknown>(
-  connector: BiDiConnector,
-  context: string,
-  fn: string | ((...args: any[]) => unknown),
-  args?: Arg[],
-  options?: CallOptions,
-): Promise<T>;
-export async function disown(connector, context, handles: string[]): Promise<void>;
-```
-
-- `fn` string is used as-is as `functionDeclaration`. `fn` function is `fn.toString()`.
-- Function-form caveat: `tsx`/esbuild may wrap named functions with a `__name(...)` helper that does not exist in the page. `callFunction` throws `ScriptSerializationError` if the source contains `__name(`, telling the caller to use an arrow function without a name or the string form. A unit test runs under `tsx` to lock this behaviour.
-- `exception` results throw `ScriptError` (`message`, `text`, `stackTrace`, `functionSource` trimmed to 200 chars).
-- `type: "success"` returns `fromRemoteValue(result)`.
-- `awaitPromise: true` is safe for sync functions and required for async ones; the auto-wait probes pass `false`.
-- With `ownership: "root"` the caller receives `RemoteObject.handle` and is responsible for `disown`; `disown` swallows `no such handle`.
-
-### Locator migration (`src/locator/*`)
-
-- `elementStateScript(expression, options)` becomes `probeElement(xpath: string, options: ProbeOptions)`, a function declaration executed via `callFunction`. The xpath is an argument, so `JSON.stringify` embedding disappears. `parseElementState` becomes a type guard over the returned object (no JSON string round trip).
-- `Locator.evaluate(expression)` is replaced by `Locator.call(fn, args)`, which resolves the element inside the function (`document.evaluate(xpath…)`) until locate-nodes lands.
-- Every existing action keeps its observable behaviour and error messages. `ScriptError` from the probe becomes the existing `Failed to locate element <xpath>. Details: …` message.
-
-## Errors
-
-| Situation | Error |
-|---|---|
-| Un-serializable argument | `TypeError` before anything is sent |
-| Function throws in page | `ScriptError` |
-| `no such node` from a `sharedId` of a previous document | `BiDiError` (callers such as `Locator` catch and re-resolve) |
-| `__name(` in function source | `ScriptSerializationError` |
-
-## Testing
-
-- Unit: `toLocalValue`/`fromRemoteValue` round trip for every mapped type, special numbers, nested structures, cycles, unsupported types. `callFunction` with the stub connector: payload shape (`functionDeclaration`, `arguments`, `target`, `awaitPromise`, `resultOwnership`, `this`), exception mapping, `__name(` guard.
-- The full existing locator/expect unit suite passes unchanged (regression net for the migration).
-- Browser: xpath containing `"`, `'`, `\` and a newline is located without escaping issues (previously a risk class); a `Map`/`Date` argument round trips; `ownership: "root"` handle then `disown` succeeds, second `disown` is silent; a removed node stays usable, and a `sharedId` from before a navigation yields `no such node`.
-- TDD: tests first.
-
-## Implementation notes
-
-Deviations and details settled while implementing:
-
-- `fromRemoteValue` maps `error` to an opaque `RemoteObject` (the protocol's `ErrorRemoteValue` carries no message); `internalId` back references are resolved, so cyclic remote objects come back as cyclic JS objects. Values cut off by the serialization depth also become `RemoteObject`s.
-- With `ownership: "root"` results that carry a handle come back as `RemoteObject { type, handle, value }` (`value` = the deserialized copy), so the caller can `disown(handle)`. With `"none"` the plain value is returned.
-- `toLocalValue` accepts only plain objects (prototype `Object.prototype` or `null`), arrays, `Map`, `Set`, `Date`, `RegExp`, primitives and `ElementHandle`; class instances, `Buffer`, functions and symbols throw `TypeError`.
-- The actionability probe is one constant `PROBE_ELEMENT` (a function declaration string) called as `(xpath, options)`; both xpath and `{ scroll, hitTest }` are arguments. It returns a plain object, so `parseElementState` is a check over `unknown` (JSON round trip gone).
-- `Locator` has `call` / `callOnElement`; other reads pass what they need (`getAttribute` passes the attribute name, `count` passes `count(<xpath>)`) as arguments too. A `ScriptError` becomes the existing `Failed to locate element <xpath>. Details: <text>` message.
-- `getBoundingClientRect` now returns the object directly (was a JSON string).
-- The stub connector answers `script.callFunction` like `script.evaluate`, records `calls` (declaration + decoded arguments) and exposes `remote()` to build object results. Tests that looked at expression text for `scrollIntoView` / `elementFromPoint` / `getAttribute("href")` now assert on the arguments instead; all other locator and expect tests are unchanged.
-- Tests: `script/{serialize,call-function}.test.ts`, `script/call-function.browser-test.ts` (real Firefox, port 9233).

package/docs/superpowers/specs/2026-09-29-set-files-design.md

@@ -1,62 +0,0 @@
-# `input.setFiles` — design
-
-Date: 2026-09-29
-Status: implemented (see "Implementation notes")
-Roadmap item: 4
-Depends on: script-call-function, locate-nodes
-
-## Goal
-
-Real file upload for `<input type="file">`, which pointer/keyboard input cannot do.
-
-```ts
-await page.locator("input[@type='file']").setInputFiles("./fixtures/avatar.png");
-await page.locator("input[@type='file']").setInputFiles(["a.csv", "b.csv"]);
-await page.locator("input[@type='file']").setInputFiles([]);   // clear
-```
-
-## Non-goals
-
-- In-memory files (`{ name, mimeType, buffer }`); BiDi takes paths on the browser's machine only.
-- Drag-and-drop uploads.
-- The file chooser popup flow (downloads-and-file-dialogs spec).
-
-## API
-
-```ts
-setInputFiles(files: string | string[], options?: { timeout?: number }): Promise<void>;
-```
-
-## Behaviour
-
-1. Normalise `files` to an array; resolve each with `path.resolve` (relative to `process.cwd()`).
-2. Before touching the browser, `fs.stat` every path: missing or a directory throws `Error("setInputFiles(): file not found: <path>")` (a local-runner assumption: browser and tests share a filesystem, true for the spawned Firefox; documented).
-3. Wait (auto-wait mechanism, `waitUntil`) for checks: **attached** and **enabled**. Not *visible*: file inputs are commonly hidden behind a styled label, so visibility and hit-testing are skipped.
-4. One `callFunction` reads `{ tag, type, multiple }`. Not `input[type=file]` → `ActionTimeoutError`-free immediate `Error("setInputFiles(): <selector> is not an <input type=file> (found <tag type=…>)")`. More than one file and `!multiple` → `Error("… does not accept multiple files")`.
-5. `input.setFiles { context, element: SharedReference, files }`. The browser fires `input` and `change` events itself; no synthetic dispatch.
-6. `[]` clears the selection and fires the events (browser behaviour; asserted in the browser test).
-
-## Errors
-
-| Situation | Error |
-|---|---|
-| Path missing | plain `Error`, before any BiDi call |
-| Wrong element / multiple | plain `Error` |
-| Never attached/enabled within timeout | `ActionTimeoutError` (`action: "setInputFiles"`, standard checks line) |
-| Browser rejects (`no such element`, `invalid argument`) | `BiDiError` |
-
-`ActionTimeoutError.action` union gains `"setInputFiles"`; `expect.timeout` config docs mention it.
-
-## Testing
-
-- Unit (stub connector): step order (stat → wait → type check → `setFiles`), `element` is the resolved `SharedReference`, absolute paths sent, multiple-files guard, wrong-element message, timeout error text, `[]` sends an empty list.
-- Browser: fixture page with a file input and a listener writing `input.files[0].name` and event counts into the DOM; single upload, multiple upload, clear, hidden input behind a label, `multiple`-less input with two files errors.
-- TDD: tests first.
-
-## Implementation notes
-
-- A directory gets its own message, `setInputFiles(): not a file: <path>` (the draft used "file not found" for both); a missing path is `setInputFiles(): file not found: <path>`. Both are checked for every path, in order, before any BiDi command is sent.
-- Sequence: stat → wait (`attached`, `enabled`; no scroll, no hit test) → resolve the element again → one script reads `{ tag, type, multiple }` → `input.setFiles`. If the element vanished between the wait and the second search, the error is `Failed to locate element … no element matches`.
-- `ActionTimeoutError.action` is a plain string, so `"setInputFiles"` needed no type change. The `expect.timeout` doc comment in `types/config.d.ts` was left alone.
-- Verified in Firefox: the browser fires `input` and `change` exactly once per call, `[]` clears the selection, hidden inputs work, the content is readable by the page.
-- Tests: `locator/set-files.test.ts`, `locator/set-files.browser-test.ts` (port 9236). The stub connector gained `input.setFiles` and `failCommand(method, error)`.

package/docs/superpowers/specs/2026-09-29-user-prompts-design.md

@@ -1,75 +0,0 @@
-# User prompts (`browsingContext.handleUserPrompt`) — design
-
-Date: 2026-09-29
-Status: implemented (see "Implementation notes")
-Roadmap item: 7
-Depends on: bidi-foundation
-
-## Goal
-
-`alert`, `confirm`, `prompt` and `beforeunload` dialogs must never hang a test. While a prompt is open the page's script commands can stall, which today would freeze an action until its timeout.
-
-```ts
-page.on("dialog", async (dialog) => {
-  console.log(dialog.type(), dialog.message());
-  await dialog.accept("Sam");          // prompt text; or dialog.dismiss()
-});
-```
-
-## Non-goals
-
-- Custom dialogs (HTML `<dialog>`), which are just DOM.
-- Permission prompts and HTTP auth dialogs (interception spec handles `authRequired`).
-
-## Components
-
-### Session capability
-
-`Browser.launch` sends `session.new { capabilities: { alwaysMatch: { unhandledPromptBehavior: { default: "ignore" } } } }`. With `ignore` the browser leaves the prompt open, fires `browsingContext.userPromptOpened`, and waits for `handleUserPrompt`. That is the only setting that lets the framework decide per prompt. (Verified against Firefox in the browser test; if Firefox ignores the capability the test fails, and the spec falls back to per-user-context `createUserContext { unhandledPromptBehavior }`.)
-
-### `src/browser/dialog.ts` (new)
-
-```ts
-class Dialog {
-  type(): "alert" | "confirm" | "prompt" | "beforeunload";
-  message(): string;
-  defaultValue(): string;                       // "" unless a prompt
-  accept(promptText?: string): Promise<void>;   // handleUserPrompt { accept: true, userText }
-  dismiss(): Promise<void>;                     // handleUserPrompt { accept: false }
-  readonly closed: Promise<{ accepted: boolean; userText?: string }>; // resolves on userPromptClosed
-}
-```
-
-`accept`/`dismiss` may be called once; a second call throws `Error("dialog already handled")`. `no such alert` from the browser (closed by navigation or another handler) is swallowed with a debug log because the outcome the caller wanted (dialog gone) is true.
-
-### `Page` integration
-
-- `page.on("dialog", handler)` / `page.off` / `page.once`. Subscribes (refcounted) to `userPromptOpened` and `userPromptClosed`, filtered by `ContextTree.isWithin`.
-- Always subscribed from page creation (as a `Page` internal listener) so the default policy below works even with no user handler.
-- Dispatch: on `userPromptOpened`, call every registered handler (awaited concurrently). After they settle, if the prompt is still open (`Dialog` not handled), apply the default policy.
-- **Default policy (no listener, or listeners left it open):** `beforeunload` → accept (so navigation proceeds), everything else → dismiss. Log a `warn`: `Dialog "<message>" was dismissed automatically; add page.on("dialog") to handle it`. Handler exceptions are logged and also trigger the default policy so the test does not hang.
-- While a prompt is open, `waitUntil` probes still race their deadline (auto-wait spec), so a stalled `callFunction` fails at its own timeout instead of hanging; the default policy normally closes the prompt within a tick, unblocking it.
-
-## Errors
-
-| Situation | Behaviour |
-|---|---|
-| Handler throws | logged; default policy applied; the test does not fail by itself |
-| `accept()` after handled | `Error("dialog already handled")` |
-| Prompt disappeared | swallowed (`no such alert`) |
-
-## Testing
-
-- Unit (stub connector): capability sent in `session.new`; `alert` with no listener dismissed + warning; `beforeunload` accepted; listener `accept("x")` sends `userText`; double-handle throws; handler throws → default policy; prompt from an iframe context handled, from an unrelated context ignored; `closed` resolves from `userPromptClosed`.
-- Browser: page with buttons for `alert`, `confirm`, `prompt` and a `beforeunload` handler; `confirm` accepted returns `true` to the page, dismissed returns `false`; `prompt` text reaches the page; unhandled `alert` on click does not hang the click; navigating away from a `beforeunload` page completes.
-- TDD: tests first.
-
-## Implementation notes
-
-- **Where:** `browser/dialog.ts` (`Dialog`), `Page.on/once/off("dialog")` (the event methods now cover `PageEventName`: network events and `dialog`), `Page.startDialogHandling()`, `SESSION_CAPABILITIES` exported from `browser/browser.ts` and sent with `session.new`. `Browser.launch` and `Browser.newPage` start dialog handling next to network tracking; `page.on("dialog")` starts it for a page built by hand.
-- **Verified in Firefox 153:** `unhandledPromptBehavior: { default: "ignore" }` leaves the dialog open and the browser reports `userPromptOpened` (with `handler: "ignore"`) for `alert`, `confirm`, `prompt` and, after a user gesture, `beforeunload`, so the per-user-context fallback from the draft was not needed. The page stays blocked in `alert()` until the dialog is answered.
-- **Answering:** always through the page's top-level context (`handleUserPrompt` needs it), also for a prompt an iframe opened. Prompts of other pages are ignored (`ContextTree`).
-- **`Dialog`:** `type()`, `message()`, `defaultValue()` (empty unless a prompt), `accept(text?)`, `dismiss()`, `handled`, `closed`. One answer only, a second call throws `dialog already handled`; `no such alert` is swallowed, other errors reach the caller. When the browser has already answered (`handler` is not `ignore`) the dialog starts as handled and listeners are still told.
-- **Default policy:** after all `dialog` listeners settled, a dialog still open is answered: `beforeunload` accepted, everything else dismissed, with a `warn` log `Dialog "<message>" was dismissed automatically; add page.on("dialog") to handle it`. A listener that throws is logged and the default applies. Listeners run concurrently and are awaited, so an async listener may answer late.
-- **`once` listeners** are called through `EventEmitter.rawListeners()`: `listeners()` returns the unwrapped function and a `once` listener would never remove itself.
-- Tests: `browser/dialog.test.ts`, `browser/dialog.browser-test.ts` (port 9239: alert holds the page, confirm true/false, prompt text and default, dismissed prompt is null, `closed`, an unhandled alert on a click does not hang, iframe alert, `beforeunload` accepted).