@itmetsam/samurai-framework 0.1.0 → 0.2.0

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

@@ -1,88 +0,0 @@
-# Emulation — design
-
-Date: 2026-09-29
-Status: implemented (see "Implementation notes")
-Roadmap item: 13
-Depends on: contexts-and-storage (overrides can target user contexts), bidi-foundation
-
-## Goal
-
-Expose the `emulation.*` commands (already typed in `src/types/bidi-modules/emulation.d.ts`, not wired into `BiDiCommands`) as page/context options.
-
-```ts
-const ctx = await browser.newContext({
-  locale: "nl-NL", timezone: "Europe/Amsterdam",
-  geolocation: { latitude: 52.37, longitude: 4.9, accuracy: 10 },
-  userAgent: "Samurai/1.0", colorScheme: "dark", offline: false,
-});
-await page.emulate({ geolocation: null });                 // reset one override
-```
-
-## Non-goals
-
-- Device descriptors (iPhone 15, …); a list of presets can be layered on later.
-- Permissions API grants (`permissions.setPermission` is a separate BiDi module, not in scope).
-- CPU throttling.
-
-## Options and mapping
-
-| Option | Command | Reset |
-|---|---|---|
-| `locale` | `emulation.setLocaleOverride { locale }` | `null` |
-| `timezone` | `emulation.setTimezoneOverride { timezone }` | `null` |
-| `geolocation` `{ latitude, longitude, accuracy? }` | `emulation.setGeolocationOverride { coordinates }` | `null` |
-| `userAgent` | `emulation.setUserAgentOverride { userAgent }` | `null` |
-| `colorScheme` `"light" \| "dark"` | `emulation.setForcedColorsModeThemeOverride`-adjacent; see Caveat | `null` |
-| `offline` | `emulation.setNetworkConditions { networkConditions: { type: "offline" } }` | `null` |
-| `orientation` | `emulation.setScreenOrientationOverride` | `null` |
-| `touch` (max touch points) | `emulation.setTouchOverride { maxTouchPoints }` | `null` |
-| `javaScriptEnabled` | `emulation.setScriptingEnabled { enabled }` (`null` resets) | `null` |
-
-Each command accepts `contexts` or `userContexts` (mutually exclusive). Context-level options (`browser.newContext({…})`) use `userContexts: [id]` so every page of the context inherits them, including pages created later; `page.emulate({…})` uses `contexts: [pageContext]`. A page override wins over its context's override (browser behaviour; asserted in a browser test).
-
-### Caveat: colour scheme
-
-BiDi only has `setForcedColorsModeThemeOverride` (forced-colors theme), which is not the same as `prefers-color-scheme`. `colorScheme` is included only if the browser test proves it drives `matchMedia("(prefers-color-scheme: dark)")` in Firefox; otherwise it is dropped from v1 and documented as unsupported (`UnsupportedOperationError`). The same proof-first rule applies to every row: each option ships only if its browser test passes on Firefox; the rest throw `UnsupportedOperationError` naming the option.
-
-## Components
-
-- `src/browser/emulation.ts`: `applyEmulation(connector, target: { contexts?: string[]; userContexts?: string[] }, options)` runs the mapped commands sequentially, skipping `undefined` options, sending `null` to reset. Validation before sending: latitude −90..90, longitude −180..180, accuracy ≥ 0, IANA timezone via `Intl.DateTimeFormat(undefined, { timeZone })` (throws `RangeError` on unknown), locale via `Intl.getCanonicalLocales`.
-- `Page.emulate(options)`; `Browser.newContext(options)` accepts the same options object (contexts spec) and applies it right after `createUserContext`, before the first page exists.
-- `BrowserContext.emulate(options)` for changing a live context.
-- Partial failure: if command N of M fails, previously applied commands are **not** rolled back; the thrown `EmulationError` lists `applied` and `failed` option names so the caller knows the state.
-
-## Errors
-
-`EmulationError extends Error { applied: string[]; failed: string; cause: BiDiError }`; `UnsupportedOperationError` per option as above; `RangeError` for invalid values.
-
-## Testing
-
-- Unit: option → command/payload table for each row, `null` reset, contexts vs userContexts targeting, validation errors, partial failure report, context options applied before first page.
-- Browser (each row is its own test and gates whether the option ships): `navigator.language`, `Intl.DateTimeFormat().resolvedOptions().timeZone`, `navigator.geolocation.getCurrentPosition` result, `navigator.userAgent`, `navigator.onLine` plus a failing fetch when offline, `matchMedia` for colour scheme, `screen.orientation.type`, `navigator.maxTouchPoints`, scripting disabled leaves inline script unexecuted; page override beats context override.
-- TDD: tests first.
-
-## Implementation notes
-
-- **Where:** `browser/emulation.ts` (`EmulationOptions`, `applyEmulation`, `validateEmulation`, `EmulationError`, `EmulationUnsupportedError`), `Page.emulate`, `BrowserContext.emulate`, `Browser.newContext(options)` (its options now extend `EmulationOptions`), `permissions.setPermission` typed (`types/bidi-modules/permissions.d.ts`, wired into `BiDiCommands`).
-- **Proof-first result on Firefox 153** (probed, then browser-tested; each row is its own test):
-
-  | Option | Firefox 153 |
-  |---|---|
-  | `locale` | works: `navigator.language`, `Intl` formatting; `null` resets |
-  | `timezone` | works: `Intl` zone and `getTimezoneOffset`; `null` resets |
-  | `userAgent` | works: `navigator.userAgent` and the request header the server receives |
-  | `offline` | works: `navigator.onLine` false and fetches fail |
-  | `orientation` | works: `screen.orientation.type` |
-  | `screen` (new: `{ width, height }` → `setScreenSettingsOverride`) | works: `screen.width`/`height` |
-  | `geolocation` | works, **once the permission is granted for that user context** (without it `getCurrentPosition` never answers) |
-  | `touch`, `javaScriptEnabled` | `unknown command` → `UnsupportedOperationError` |
-  | `colorScheme` | **dropped**: BiDi has no `prefers-color-scheme` override, only forced colours, which Firefox 153 lacks (`unknown command`) |
-
-  `setTouchOverride`, `setScriptingEnabled` and the forced-colours / scrollbar commands are unknown to Firefox 153; the framework maps `touch` and `javaScriptEnabled` anyway and turns `unknown command` / `unsupported operation` into `UnsupportedOperationError` (so they work where a browser has them). The forced-colours and scrollbar commands are not exposed.
-- **Permissions (an addition to the draft, which listed them as a non-goal):** geolocation is unusable without a grant, so `BrowserContext.setPermission(name, state, origin)` and `Page.grantPermission(name, { origin? })` (default: the origin the page is on; `about:blank` and `data:` pages need an explicit one) send `permissions.setPermission`, naming the user context for non-default contexts.
-- **Targets:** `page.emulate` uses `contexts: [pageId]`, `context.emulate` and `newContext` options use `userContexts: [id]` (the default context is `"default"`). Firefox rejects both or neither. Verified: a context's setting reaches open pages and pages opened later, not other contexts; a page's own setting wins; `null` on the page falls back to the context's value.
-- **Options:** `undefined` leaves an option alone, `null` resets it; `offline: false` and `javaScriptEnabled: true` mean "back to normal" (a `null` command); `orientation` takes `"portrait"` / `"landscape"` (primary) or one of the four BiDi types. Commands go out in a fixed order (locale, timezone, userAgent, geolocation, offline, orientation, screen, touch, javaScriptEnabled).
-- **Validation before anything is sent** (`RangeError`): latitude −90..90, longitude −180..180, accuracy ≥ 0, timezone via `Intl.DateTimeFormat`, locale via `Intl.getCanonicalLocales`, non-empty user agent, positive integers for screen and touch, known orientation. `newContext` validates before it creates the context.
-- **Failures:** nothing is rolled back. `EmulationError` (`applied`, `failed`, `cause`) for an ordinary failure; `EmulationUnsupportedError extends UnsupportedOperationError` (`option`, `applied`) for an unsupported option. `newContext` removes the context it just created when its emulation fails, so nothing stays in the profile.
-- **Typing fixes:** `SetLocaleOverrideParameters` no longer requires both `contexts` and `userContexts`; `SetTouchOverrideParameters.maxTouchPoints` may be `null`.
-- Tests: `browser/emulation.test.ts` (34), the "emulation" block in `browser/browser-context.test.ts`, `browser/emulation.browser-test.ts` (port 9248, 12 tests).

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

@@ -1,130 +0,0 @@
-# `expect` assertions — design
-
-Date: 2026-09-29
-Status: approved in brainstorming, pending spec review
-
-## Goal
-
-Give tests a single `expect()` API for:
-
-- **Locators** — web-first assertions that auto-retry until the DOM matches or a timeout expires.
-- **Plain values** — synchronous, Jest-style matchers.
-
-A failing assertion throws, stops the test, and is reported as `type: "assertion"` with `expected` / `actual`.
-
-```ts
-import { expect } from "../assert/expect.js";
-
-await expect(page.locator("div[@class='alert']")).toBeVisible();
-await expect(page.locator("h1")).not.toHaveText(/error/i, { timeout: 2000 });
-
-expect(count).toBeGreaterThan(2);
-expect(result).toEqual({ ok: true });
-```
-
-## Non-goals (v1)
-
-- Soft assertions (`expect.soft`).
-- Custom matchers / `expect.extend()`.
-- Page-level matchers (`toHaveURL`, `toHaveTitle`).
-
-## Components
-
-### `src/assert/expect.ts`
-
-- `expect` overloads:
-  - `expect(locator: Locator): LocatorAssertions`
-  - `expect<T>(value: T): ValueAssertions<T>`
-  - Dispatch by `value instanceof Locator`.
-- `LocatorAssertions` — every matcher returns `Promise<void>` and takes an optional last argument `{ timeout?: number }`:
-  - `toBeVisible()`
-  - `toHaveText(expected: string | RegExp)` — string compares against trimmed `textContent` exactly.
-  - `toContainText(expected: string | RegExp)` — string is a substring check.
-  - `toHaveValue(expected: string | RegExp)`
-  - `toHaveAttribute(name: string, expected: string | RegExp)`
-  - `toHaveCount(expected: number)`
-- `ValueAssertions<T>` — every matcher returns `void`:
-  - `toBe(expected)` — `Object.is`.
-  - `toEqual(expected)` — `util.isDeepStrictEqual`.
-  - `toBeTruthy()`, `toBeFalsy()`
-  - `toContain(item)` — arrays (`includes`) and strings (substring).
-  - `toMatch(pattern: string | RegExp)` — strings only.
-  - `toBeGreaterThan`, `toBeGreaterThanOrEqual`, `toBeLessThan`, `toBeLessThanOrEqual` — numbers/bigints.
-- Both classes expose a `.not` getter returning a negated instance.
-- Type misuse (e.g. `toMatch` on a non-string, number comparison on a non-number) throws a `TypeError`, not an `AssertionError`.
-
-### `src/assert/assertion-error.ts`
-
-`AssertionError extends Error` with:
-
-- `matcher: string` — e.g. `"toHaveText"` or `"not.toHaveText"`.
-- `expected: unknown`, `actual: unknown`
-- `locator?: string` — the XPath, for locator assertions.
-
-Message format:
-
-```
-expect(locator).toHaveText
-  locator: //h1
-  expected: "Contact"
-  received: "Home"
-```
-
-Values are formatted by a shared `format()`: strings quoted, RegExp as `/src/flags`, other values via `util.inspect` with `depth: 2`.
-
-### `src/locator/locator.ts` — new public reads
-
-None of these throw when the element is missing; an evaluate exception (e.g. invalid XPath) still throws.
-
-| Method | Returns | Missing element |
-|---|---|---|
-| `isVisible()` | `boolean` — exists, bounding box width and height > 0, computed style not `display:none`, `visibility:hidden`, `opacity:0` | `false` |
-| `textContent()` | trimmed `string` | `null` |
-| `inputValue()` | `string` (`.value`) | `null` |
-| `getAttribute(name)` | `string` | `null` (also when the attribute is absent) |
-| `count()` | `number` via XPath `count(...)` with `XPathResult.NUMBER_TYPE` | `0` |
-
-## Retry behaviour (locator matchers only)
-
-- Internal `poll(read, check, timeout)`:
-  1. `actual = await read()`; with `timeout > 0` the read is raced against the time left until the deadline (start + timeout), and the race timer is cleared when the read wins.
-  2. If `check(actual) !== negated` → resolve.
-  3. If elapsed ≥ timeout → throw `AssertionError` with the last `actual`.
-  4. Otherwise wait 100 ms and repeat.
-- The timeout is a hard bound: if the deadline expires while a read is still pending, the matcher throws `AssertionError` with the last completed `actual`, or, when no read ever completed, a plain `Error`: `expect(locator).<matcher>: could not read <selector> within <timeout>ms`.
-- A matcher always reads at least once, even with `timeout: 0`; with `timeout: 0` that single read is awaited without a race.
-- Errors thrown by `read()` (invalid XPath, BiDi socket closed after the browser was killed) are rethrown immediately, not retried.
-- Timeout resolution: per-call `{ timeout }` → config `expect.timeout` → default `5000` ms.
-- `SamuraiTestConfig` gains `expect?: { timeout?: number }`.
-
-## Failure reporting
-
-- `TestError.type` becomes `"timeout" | "error" | "assertion"`, with optional `expected?: unknown` and `actual?: unknown`. The reporter stores them as-is (JSON-serialisable values); a RegExp, bigint, symbol or function, or any value `JSON.stringify` rejects (e.g. a circular object), is stored as its `format()` string.
-- `test-runner.ts`: in the test's `catch`, `err instanceof AssertionError` → `type: "assertion"` with `expected` / `actual`; everything else stays `"error"`.
-
-### Missing-`await` guard
-
-- Every locator assertion is added to a module-level `pendingAssertions` registry in `expect.ts`. It is removed as soon as anyone subscribes to it (`await`, `.then`, `.catch`, `.finally`, `Promise.all`, `assert.rejects`) or when it passes. An un-awaited assertion that fails stays in the registry: a failure nobody observed is the same silent-pass trap as one still running.
-- To detect `await`, matchers return a `Promise` subclass (still typed `Promise<void>`) whose overridden `then` removes it from the registry; `await` calls that `then` because the constructor is not the native `Promise`. Promises derived from it are plain promises.
-- `expect.ts` exports `takePendingAssertions(): string[]`, which returns the matcher names of un-awaited assertions that are still running or already failed, and clears the registry.
-- After the test function resolves, the runner calls it; if the result is non-empty, the test fails with `type: "assertion"` and message `expect(locator).<matcher>() was not awaited`.
-- Each assertion gets an internal rejection handler (which does not count as awaiting), so an un-awaited failure is never an unhandled rejection.
-
-## Testing
-
-- Runner: Node's built-in `node:test` via tsx. `package.json`: `"test": "tsx --test \"src/**/*.test.ts\""`.
-- `src/assert/expect.test.ts`:
-  - Each value matcher: pass, fail, `.not`, `AssertionError` fields, `TypeError` on misuse.
-  - Locator matchers against a stub `BiDiConnector` whose `send("script.evaluate")` returns a scripted sequence of results:
-    - passes after N polls,
-    - times out with the last `actual`,
-    - rethrows on an evaluate exception without retrying,
-    - `.not` variants,
-    - per-call `timeout` overrides the default.
-  - Missing-`await` guard: an un-awaited locator assertion shows up in `takePendingAssertions()`, also when it already failed; an awaited one never does, pass or fail.
-- End-to-end: `src/tests/index.spec.ts` asserts `toHaveValue` on the filled fields and `toBeVisible` on the name field; verified with `bun run dev` against Firefox.
-- TDD: write each test before its implementation.
-
-## Out of scope, noted
-
-- `Page.navigateTo` builds `` `${protocol}://url` `` (literal `url`) for scheme-less URLs — separate fix.

package/docs/superpowers/specs/2026-09-29-locate-nodes-design.md

@@ -1,90 +0,0 @@
-# `browsingContext.locateNodes` — design
-
-Date: 2026-09-29
-Status: implemented (see "Implementation notes")
-Roadmap item: 3
-Depends on: script-call-function (preload-scripts optional)
-
-## Goal
-
-Add CSS, text and accessibility locators, and move element resolution from ad-hoc `document.evaluate` calls to the protocol's own locator command. Existing `page.locator(xpath)` behaviour is unchanged.
-
-```ts
-page.locator("//button[@type='submit']")        // unchanged
-page.getByCss("form.login input[name=user]")
-page.getByText("Sign in", { match: "full" })
-page.getByRole("button", { name: "Submit" })
-page.locator("//form").getByRole("textbox")     // chained, scoped to the form
-```
-
-## Non-goals
-
-- Shadow-DOM piercing beyond what the browser's `locateNodes` does natively.
-- A custom selector-string mini-language (`role=button[name=…]`); constructors only.
-- `getByLabel`, `getByPlaceholder`, `getByTestId`; each is a one-line CSS/xpath wrapper, added later.
-
-## Components
-
-### Selector model — `src/locator/selector.ts` (new)
-
-```ts
-export type Selector =
-  | { kind: "xpath"; value: string }
-  | { kind: "css"; value: string }
-  | { kind: "text"; value: string; match: "full" | "partial"; ignoreCase: boolean }
-  | { kind: "role"; role: string; name?: string };
-
-export function toBiDiLocator(selector: Selector): BrowsingContext.Locator;
-export function describeSelector(selector: Selector): string; // used in every error message
-```
-
-`describeSelector` output: xpath → the normalised xpath (unchanged from today, so existing error texts and tests keep passing); css → `css=form input`; text → `text="Sign in"`; role → `role=button[name="Submit"]`. A chain is described `parent >> child`.
-
-Mapping: xpath → `{type:"xpath"}`, css → `{type:"css"}`, text → `{type:"innerText", value, matchType, ignoreCase}`, role → `{type:"accessibility", role, name}`.
-
-### `Locator` changes
-
-- Constructor takes `Selector[]` (a chain) instead of an xpath string; `new Locator(xpath, …)` callers keep working via `Page.locator(xpath)` which builds `[{kind:"xpath", …}]`.
-- New: `getByCss`, `getByText`, `getByRole`, `locator(xpath)` on `Locator` (chaining). Each returns a new `Locator` whose chain is the parent chain plus one selector.
-- `resolveOne(): Promise<ElementHandle | null>`: for each selector in the chain call `browsingContext.locateNodes { context, locator, maxNodeCount: 1, startNodes }` where `startNodes` is the previous result as a `SharedReference`; return null when any step is empty.
-- `resolveAll(): Promise<ElementHandle[]>`: intermediate steps use every match as `startNodes`; the last step has no `maxNodeCount`. Results de-duplicated by `sharedId`, document order kept as returned.
-- `count()`, `all()` use `resolveAll`. `all()` returns locators pinned to an element via a `{kind: "handle"}` internal selector (never exposed) instead of the `(xpath)[n]` trick, so non-xpath selectors also support `all()`.
-- The actionability probe takes the element as a `callFunction` argument (`probeElement(el, options)`) instead of resolving the xpath in page code. A `no such node` reply (element replaced between resolve and probe) is treated as "not attached" for that poll.
-- One poll = `locateNodes` + one `callFunction`: two round trips instead of one. To keep the cost down, `resolveOne` caches the last `ElementHandle` per action; the next poll reuses it and only re-resolves after `no such node`.
-
-### Accessibility locator caveats
-
-- `accessibility` requires a role and/or name; both empty throws `TypeError` at construction.
-- Support and exact name computation differ per browser. If Firefox rejects the locator type with `unsupported operation`, `getByRole` throws `UnsupportedOperationError("getByRole is not supported by <browser>")` instead of retrying until the timeout.
-
-## Errors
-
-| Situation | Behaviour |
-|---|---|
-| Invalid CSS / xpath | `BiDiError` `invalid selector` → thrown immediately (not retried), message includes `describeSelector` |
-| No match | as today: retried until the action/assert timeout, then the existing `ActionTimeoutError` (“was not attached”) |
-| Unsupported locator type | `UnsupportedOperationError` |
-
-## Testing
-
-- Unit: `toBiDiLocator` / `describeSelector` for every kind and for chains; chain resolution sends `startNodes` from the previous step; multi-match parents are unioned and de-duplicated; cached handle reused then re-resolved after a `no such node` stub reply; invalid selector not retried.
-- Existing `locator-actions`, `expect-locator`, `element-state` tests pass unchanged (xpath behaviour, messages).
-- Browser: css, text (full vs partial, case), role+name against a fixture page; chained locator scoped to one of two forms; `all()` on a css locator; element replaced mid-wait is re-resolved and clicked.
-- TDD: tests first.
-
-## Implementation notes
-
-Deviations and details settled while implementing:
-
-- **No handle cache across polls (replaces the "cache the last `ElementHandle`" idea).** Firefox keeps a removed node resolvable while it is alive, so a cached handle would keep probing a detached element, and it would also miss that a different element became the first match. Every poll searches again: one `locateNodes` (limited to 1 node) plus one `callFunction`. The probe checks `el.isConnected`, so a resolvable-but-removed node reads as not attached. `no such node` between the search and the call also reads as missing/not attached.
-- **Locating asks for references only:** `serializationOptions: { maxDomDepth: 0 }`.
-- **`nth` steps replace pinned handles for `all()`.** `all()` on a locator that is a single xpath keeps returning positional xpaths (`(//li)[n]`, unchanged); every other locator gets a `nth=<index>` step that re-resolves the whole chain and picks the n-th match (0-based), so items survive re-renders. The step before `nth` is never limited by `maxNodeCount`. No internal `handle` selector exists.
-- **Chained xpaths are scoped:** in a chain, `input` and `//input` become `.//input`; absolute (`/…`), grouped (`(…)`) and `./…` paths are kept.
-- **Defaults:** `getByText` matches fully and case-sensitively (BiDi's defaults); `match: "partial"` and `ignoreCase: true` are opt-in. `describeSelector` adds `(partial, ignoring case)` only for non-default options.
-- **`Locator` takes `string | Selector[]`**, so `new Locator(xpath, …)` keeps working; `selector` prints the chain (`//form >> role=button[name="Save"]`).
-- **New API:** `Locator.locator/getByCss/getByText/getByRole` (chaining) and `Page.getByCss/getByText/getByRole`; `InvalidSelectorError` (browser answered `invalid selector`, thrown at once, never retried) and `UnsupportedOperationError` are exported from `locator.ts`.
-- **What Firefox (153) supports:** `css`, `xpath` and `accessibility` natively; **`innerText` is `unsupported operation`.** So `getByRole` (role and/or name) works as designed, and text search has a fallback: `TEXT_LOCATE` (`src/locator/text-locator.ts`), an in-page function that searches the descendants of the start nodes (or the whole document), compares `innerText` with whitespace collapsed (`full` = equal, `partial` = substring, optional lower-casing), returns only the innermost matches, unique and in document order. It is tried only after the browser said `unsupported operation`; the answer is remembered per connection, so later text locators go straight to the page. Other locator types that come back unsupported still raise `UnsupportedOperationError`.
-- Cost of the text fallback: it reads `innerText` of every element under the roots, so it is linear in page size times depth; fine for test pages, not for very large DOMs.
-- The actionability probe is now `PROBE_ELEMENT = (el, options) => …` (element as argument, `DETACHED_STATE` for a missing element) and the framework helpers install it unchanged.
-- Test infrastructure: the stub connector answers `browsingContext.locateNodes` (`nodeCounts`, `failLocate`, `unsupportedLocators`, `{ error }` responses). Tests that read the xpath from script text now read it from the locate command.
-- Tests: `locator/{selector,text-locator,locator-chain}.test.ts`, updated `locator*.test.ts`/`element-state.test.ts`/`expect-locator.test.ts`, `locator/locate-nodes.browser-test.ts` (real Firefox, port 9235).

package/docs/superpowers/specs/2026-09-29-logs-and-errors-design.md

@@ -1,87 +0,0 @@
-# Logs and page errors (`log.entryAdded`) — design
-
-Date: 2026-09-29
-Status: implemented (see "Implementation notes")
-Roadmap item: 8
-Depends on: bidi-foundation, script-call-function
-
-## Goal
-
-Capture browser console output and uncaught page exceptions, attach them to failing tests, and optionally fail tests on page errors.
-
-```ts
-page.on("console", (msg) => console.log(msg.type(), msg.text()));
-page.on("pageerror", (err) => console.log(err.message));
-```
-
-```ts
-// samurai.config.ts
-logs: { capture: "failures", failOnPageError: true }
-```
-
-## Non-goals
-
-- `script.message` channels and `page.exposeFunction`.
-- Console line-level source mapping.
-- Browser-level (non-page) log entries.
-
-## Components
-
-### `src/browser/page-logs.ts` (new)
-
-```ts
-class PageLogs {
-  static async start(connector, tree: ContextTree, contextId: string, options?: { maxEntries?: number }): Promise<PageLogs>;
-  readonly entries: readonly LogEntry[];      // ring buffer, default 1000
-  readonly errors: readonly PageError[];      // uncaught exceptions only
-  on/off("console" | "pageerror", …);
-  clear(): void;
-  dispose(): Promise<void>;
-}
-```
-
-- Subscribes (refcounted) to `log.entryAdded`; keeps entries where `source.context` is set and within the page (`ContextTree`). Entries without a context (worker realms) are ignored in v1.
-- Started at page creation so early logs are not lost.
-- BiDi entry → wrapper:
-  - `type: "console"`: `ConsoleMessage { type() /* method: log|info|warn|error|debug|… */, text(), args: unknown[] /* fromRemoteValue */, timestamp, location, stack }`.
-  - `type: "javascript"`: `PageError extends Error { message: text, stack from stackTrace, timestamp }`; also emitted as `pageerror`.
-- `level` is kept on the raw entry (`debug | info | warn | error`); `console.error` is `level: "error"` but is **not** a page error.
-- Ring buffer drops oldest entries and counts `dropped` for the report.
-
-### Runner integration (`src/runner/*`)
-
-- Config:
-  ```ts
-  logs?: {
-    capture?: "off" | "failures" | "all";   // default "failures"
-    failOnPageError?: boolean;               // default false
-    ignoreErrors?: (string | RegExp)[];     // messages never counted as failures
-  }
-  ```
-- After each test, `capture: "failures"` attaches `entries` to the `TestResult` only when the test failed; `"all"` always; `"off"` never. The reporter prints them under the failure and writes them into `result/report.json` (`logs: [{ level, type, text, timestamp }]`).
-- `failOnPageError`: after the test body succeeds, if `errors` contains any not matching `ignoreErrors`, the test fails with `PageErrorsError` listing the messages. A test that already failed keeps its own error; page errors are attached as logs.
-- Per-test escape hatch: `page.allowPageErrors()` (this test only).
-- A fresh `Browser` per test (current runner) means no manual clearing is needed; `clear()` stays for tests that reuse a page.
-
-## Errors
-
-`PageErrorsError extends Error { errors: PageError[] }`, message `<n> uncaught page error(s): <first message>` plus the rest one per line.
-
-## Testing
-
-- Unit: entry mapping for each console method and for a javascript entry; args deserialized via `fromRemoteValue`; ring buffer overflow and `dropped`; iframe entry kept, foreign context dropped; `pageerror` emitted only for `javascript` type; `console.error` not a page error; `ignoreErrors` string and RegExp; runner attaches logs per `capture` mode and `failOnPageError` behaviour incl. `allowPageErrors`; report JSON shape.
-- Browser: page calls `console.log({a:1})`, `console.error("x")`, and throws in a `setTimeout`; assert entries, args `{a:1}`, one page error with a stack.
-- TDD: tests first.
-
-## Implementation notes
-
-- **Where:** `browser/page-logs.ts` (`PageLogs`, `ConsoleMessage`, `PageError`, `LogRecord`), `Page.startLogging/getLogs/pageErrors/clearLogs/syncLogs/allowPageErrors/pageErrorsAllowed/logsDropped` and `page.on/once/off("console" | "pageerror")`; `runner/page-logs-report.ts` (`judgePageLogs`, `PageErrorsError`); config `logs: { capture, failOnPageError, ignoreErrors }`; `logs` / `logsDropped` on test results in the report.
-- **Typing fix:** the BiDi log entry text field is `text` (the local typing called it `string`).
-- **Start:** `Browser.launch` / `newPage` start logging with the page, so output of the first document is kept (a browser test loads a `data:` page that logs at once). A hand-built `Page` starts on first `page.on("console" | "pageerror")` or `startLogging()`.
-- **`ConsoleMessage`:** `type()` (the console method), `text()` (the browser's rendering, e.g. `hello 42 Object(2)` in Firefox), `args` (plain values through `fromRemoteValue`), `level`, `timestamp`, `location()` (top stack frame), `stackTrace`. **`PageError`** is an `Error` whose `stack` is the text plus one `at fn (url:line:col)` line per frame.
-- **Buffer:** `entries` and `errors` are copies (a snapshot); the buffer keeps the newest `maxEntries` (1000) and counts `dropped`. Entries without a context (workers) and of other pages are ignored; iframes count. Entries of other types (e.g. deprecation) are recorded without an event.
-- **Firefox facts:** `console.error` is `level: "error"` and not a page error; an **unhandled promise rejection is reported as a `javascript` entry**, so it is a page error and counts for `failOnPageError`.
-- **`syncLogs()`** sends `session.status`: events and replies share one ordered connection, so everything logged before the call has arrived when it resolves. The runner calls it before it reads the logs.
-- **Runner integration:** `judgePageLogs` is a pure function (config, entries, errors, dropped, testFailed, allowPageErrors) that returns the error to fail a passing test with, and the entries for the report; `test-runner.ts` calls it through a small `judgeLogs(page, testFailed)` helper on the three ways a test ends (passed, failed, unawaited assertions). A timed-out test ends before that and carries no logs. `capture` defaults to `"failures"`; a test that fails because of page errors counts as failed for that. `ignoreErrors` strings match as substrings.
-- **Not done:** the draft said the reporter "prints" the logs under a failure; the reporter only writes `result/report.json` today, and that is where the logs go.
-- Tests: `browser/page-logs.test.ts`, "Page logs" block in `browser/page.test.ts`, `runner/page-logs-report.test.ts`, `browser/page-logs.browser-test.ts` (port 9240).

package/docs/superpowers/specs/2026-09-29-navigation-waits-design.md

@@ -1,83 +0,0 @@
-# Navigation waits — design
-
-Date: 2026-09-29
-Status: implemented (see "Implementation notes")
-Roadmap item: 6
-Depends on: bidi-foundation, network-tracking
-
-## Goal
-
-Make navigation deterministic: pick when `navigateTo` resolves, fail with a real error when navigation fails, and expose load-state waiting for actions that trigger navigation (a click on a link).
-
-```ts
-await page.navigateTo("example.com");                              // wait: "complete" (default)
-await page.navigateTo("example.com", { wait: "interactive" });
-await page.navigateTo("example.com", { wait: "none" });
-await page.locator("//a[@id='next']").click();
-await page.waitForLoadState("domcontentloaded");                   // "load" | "domcontentloaded" | "networkidle"
-await page.reload();
-```
-
-## Non-goals
-
-- `waitForURL` and `waitForNavigation` (small follow-ups on the events added here).
-- History traversal and `reload` details (page-api spec owns those commands; this spec only defines the shared wait semantics).
-
-## API
-
-```ts
-navigateTo(url: string, options?: NavigateOptions): Promise<{ navigation: string | null; url: string }>;
-interface NavigateOptions {
-  wait?: "none" | "interactive" | "complete";   // default config navigation.waitUntil, else "complete"
-  timeout?: number;                             // default config navigation.timeout, else 30000
-  protocol?: "http" | "https";                  // existing third param, kept
-}
-waitForLoadState(state?: "load" | "domcontentloaded" | "networkidle", options?: { timeout?: number }): Promise<void>; // default "load"
-```
-
-The current positional signature `navigateTo(url, wait?, protocol?)` stays accepted for one release: a string second argument is treated as `wait`.
-
-Config additions (`SamuraiTestConfig`):
-
-```ts
-navigation?: { timeout?: number /* 30000 */; waitUntil?: "none" | "interactive" | "complete" /* "complete" */ };
-```
-
-The navigation timeout is deliberately separate from `expect.timeout` (5000, for actions/assertions): page loads legitimately take longer.
-
-## Behaviour
-
-- `browsingContext.navigate { context, url, wait }` runs with the navigation timeout as its command timeout (foundation spec). The result `{ navigation, url }` is returned (`navigation` is null for same-document navigations).
-- The `wait` value is passed to the browser, replacing the existing `if (!result)` check (which could never fire).
-- Failure detection: on a `BiDiError` from `navigate` (DNS failure, connection refused, TLS error surface as `unknown error` with the net error in the message), throw `NavigationError { url, reason, code }`. `navigationFailed` / `navigationAborted` events matching the `navigation` id also reject a still-pending wait (covers `wait: "none"` followed by `waitForLoadState`).
-- Timeout: throw `NavigationError` with `reason: "timeout after <t>ms"`. A best-effort `browsingContext.navigate` to the current URL is *not* attempted; the caller decides.
-- Existing scheme handling (`about:blank`, `data:`, `localhost:3000`) is kept.
-- `waitForLoadState(state)`:
-  1. Read `document.readyState` via `callFunction` (already reached → resolve). Mapping: `load` ⇔ `complete`; `domcontentloaded` ⇔ `interactive` or `complete`.
-  2. Otherwise `waitForEvent("browsingContext.load" | "browsingContext.domContentLoaded", context === page)`, listener registered *before* step 1 completes to avoid the read/event race.
-  3. `networkidle` = `load` then `NetworkTracker.waitForIdle`.
-- Navigation triggered by a click: `click()` does not wait for navigation itself; callers use `waitForLoadState`. (Auto-waiting for navigations after actions is out of scope.)
-
-## Errors
-
-`NavigationError extends Error { url: string; reason: string; code?: string }` with message `navigateTo(): <url> failed: <reason>`. The runner maps it to a normal test error.
-
-## Testing
-
-- Unit (stub connector): `wait` param forwarded, default resolved from config; `BiDiError` → `NavigationError`; `navigationFailed` rejects a pending wait for the matching navigation id only; timeout path; positional-argument compatibility; `waitForLoadState` already-reached (no event wait), not-yet-reached (event), event-before-read race (event registered first), `networkidle` composition.
-- Browser (local `node:http` server): `complete` resolves after a delayed subresource, `interactive` before it, `none` immediately; connection-refused port yields `NavigationError`; slow server hits the navigation timeout; click on a link then `waitForLoadState("load")`.
-- TDD: tests first.
-
-## Implementation notes
-
-- **Where:** `Page.navigateTo` / `Page.waitForLoadState`, `browser/navigation-error.ts` (`NavigationError`, `LoadStateTimeoutError`), config `navigation: { timeout, waitUntil }` in `types/config.d.ts`, `PageSettings` (`Pick<SamuraiTestConfig, "network" | "navigation">`). `navigateTo(url, wait?, protocol?)` still works; the second argument may be a string (the wait) or an options object.
-- **Default wait is now `"complete"`** (was the browser default, `"none"`), from config `navigation.waitUntil` when set.
-- **`NavigationError`** for every BiDi error from `browsingContext.navigate` (`code` = the BiDi code, or `"timeout"` with reason `timeout after <t>ms`). The BiDi command itself carries the navigation timeout.
-- **`LoadStateTimeoutError extends WaitTimeoutError`**: `waitForLoadState("load") did not finish within <t>ms`. `waitForNetworkIdle`'s default timeout is now the navigation timeout too.
-- **Progress per navigation (not in the draft).** A document that is still the old one reports `readyState === "complete"`, so `navigateTo(url, { wait: "none" })` followed by `waitForLoadState()` would have returned at once. For navigations that do not wait for the load, `Page` records which navigation ids reached DOMContentLoaded and load (`browsingContext.domContentLoaded`/`load`, subscribed from the first such navigation until `dispose()`, latest 20 ids kept). `waitForLoadState` trusts that record when it says the last `navigateTo` navigation is short of the state, and reads `document.readyState` otherwise. Failure events count when they belong to that navigation, or, when no navigation is known, `navigationFailed` in this page's context.
-- **`waitForLoadState` after a click** cannot know a navigation is coming: if the click's navigation has not started yet, the old document counts as loaded. Wait for a sign of the navigation first (an element of the new page, the URL) and then for the load state; the browser test does this.
-- **Firefox 153 facts** (browser tests): the `browsingContext.navigationAborted` event is unknown to it (`session.subscribe` answers `invalid argument`), so a wait subscribes to it only when the browser knows it and remembers per connection when it does not; `navigate` fails with `NS_ERROR_CONNECTION_REFUSED` even with `wait: "none"`; `wait: "none"` returns once the navigation has committed (response headers received), so a server that never answers blocks it until the navigation timeout.
-- **`networkidle`** = load, then `NetworkTracker.waitForIdle` (idle time from config `network.idleTime`); the timeout applies to each of the two stages.
-- `reload` is left to the page-api spec.
-- **Test infra:** `autoReply` handlers may now answer `session.subscribe` (an Error with a `code` property answers with that BiDi code). A few timing assertions in `wait-until.test.ts` and `expect-locator.test.ts` got 5 ms of slack (`setTimeout` can fire a millisecond early).
-- Tests: the "Page navigation" block in `browser/page.test.ts`, `browser/navigation.browser-test.ts` (port 9238; local server with a slow image, refused port, hanging route).

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

@@ -1,78 +0,0 @@
-# Network data (cache control and response bodies) — design
-
-Date: 2026-09-29
-Status: implemented (see "Implementation notes")
-Roadmap item: 10
-Depends on: network-tracking
-
-## Goal
-
-Read response bodies and control the HTTP cache.
-
-```ts
-const response = await page.waitForResponse("**/api/users");
-expect(response.status).toBe(200);
-const users = await response.json();
-
-await page.setCacheDisabled(true);       // network.setCacheBehavior { cacheBehavior: "bypass" }
-```
-
-## Non-goals
-
-- Streaming bodies, request body capture beyond what `dataType: "request"` returns (added if Firefox supports it; otherwise out of scope).
-- HAR export.
-- Modifying responses (interception spec).
-
-## API
-
-```ts
-page.waitForResponse(match: string | RegExp | ((r: Response) => boolean), options?: { timeout?: number }): Promise<Response>;
-page.waitForRequest(match: …, options?): Promise<Request>;
-page.setCacheDisabled(disabled: boolean): Promise<void>;
-
-interface Response {
-  url; status; statusText; headers; fromCache; request;      // from network-tracking spec
-  body(): Promise<Buffer>;
-  text(): Promise<string>;
-  json<T = unknown>(): Promise<T>;
-}
-```
-
-`match` strings/RegExps use the URL matching from the interception spec (shared `matchUrl` util in `src/network/url-match.ts`). `waitForResponse` uses `waitForEvent`-style registration: call it before triggering the request, or pass the trigger: `page.waitForResponse(match, { trigger: () => button.click() })` (registers first, runs the trigger, then awaits).
-
-## Components
-
-### Data collector — `src/network/data-collector.ts` (new)
-
-- BiDi only retains bodies for requests that a **collector** was registered for *before* the request. `network.addDataCollector { dataTypes: ["response"], maxEncodedDataSize, contexts: [pageContext] }` returns a `collector` id.
-- The collector is created lazily on the first use of `waitForResponse`, `response.body()`, `page.on("response")` body access, or explicitly by `page.collectResponseBodies()`. Bodies of requests that completed before that are unavailable: `response.body()` throws `ResponseBodyUnavailableError`.
-- Trade-off (documented): always-on collection would retain every body in browser memory, so it is opt-in by first use, plus config `network.collectBodies: true` to start with the page.
-- `maxEncodedDataSize` from config `network.maxBodySize` (default 10 MiB). Larger responses: `body()` throws `ResponseBodyUnavailableError("exceeds maxBodySize")`.
-- `Response.body()`: waits for `responseCompleted` of that request if not yet seen, then `network.getData { dataType: "response", collector, request }` → `bytes` (`{ type: "string" | "base64", value }`) → `Buffer`. The Buffer is cached on the `Response` so repeated calls work. After a successful read: `network.disownData { dataType, collector, request }` to free browser memory (guarded; failures logged, not thrown).
-- `dispose()`: `network.removeDataCollector`.
-- Redirect responses have no body: `body()` throws `ResponseBodyUnavailableError("redirect response")`.
-
-### Cache
-
-`setCacheDisabled(true)` → `network.setCacheBehavior { cacheBehavior: "bypass", contexts: [pageContext] }`; `false` → `"default"`. Scoped to the page. If unsupported: `UnsupportedOperationError`.
-
-## Errors
-
-`ResponseBodyUnavailableError extends Error { url: string; reason: string }` with reasons: `collector not registered before the request`, `exceeds maxBodySize`, `redirect response`, `no data available`.
-
-## Testing
-
-- Unit (stub connector): lazy collector creation and payload; `getData` mapping for string/base64 bytes; caching of the buffer; `disownData` after read and failure tolerance; `redirect` and size errors; `waitForResponse` with `trigger` registers before running it; timeout error text; `setCacheDisabled` payload both ways; `dispose` removes the collector.
-- Browser (local server): JSON endpoint body via `json()`; binary body round trip via `base64`; second `fetch` with `setCacheDisabled(true)` hits the server twice while default hits it once (server counts requests, cacheable headers set); a response completed before the collector exists rejects with the documented error.
-- TDD: tests first.
-
-## Implementation notes
-
-- **Where:** `network/data-collector.ts` (`DataCollector`, `ResponseBodyUnavailableError`), `network/response.ts` (`Response`), `network/network-wait.ts` (`RequestTimeoutError`, `ResponseTimeoutError`, `toPredicate`), and on `Page`: `startBodyCollection`, `waitForResponse`, `waitForRequest`, `setCacheDisabled`. Config `network.collectBodies` (default false) and `network.maxBodySize` (default 10485760).
-- **`page.on("response")` now hands out `Response` objects** (a superset of the tracker's plain response: `url`, `status`, `statusText`, `headers`, `fromCache`, `request`, plus `id`, `body()`, `text()`, `json()`). There is exactly one `Response` per network response however many listeners or `waitForResponse` calls see it, so a body is read from the browser once, kept, and released with `network.disownData`.
-- **Collection starts on first use** (`page.on("response")`, `waitForResponse`, `startBodyCollection()`), or with the page when `collectBodies` is true. A response that completed before collection began cannot be read. `page.on("response")` starts collection asynchronously, so a response that arrives within the first few milliseconds after registering may still miss it; register listeners before triggering traffic.
-- **Error reasons:** the browser answers `no such network data` for both "collector started after the request" and "larger than maxBodySize", and they cannot be told apart, so `ResponseBodyUnavailableError` says: `no body was collected: the collector started after the request, or the response is larger than maxBodySize`. A 3xx response with a `Location` header is a `redirect response` (checked locally, the browser is not asked; a 304 is asked for). `unavailable network data` maps to `the body is not available yet`. Other errors pass through.
-- **`waitForResponse(match, { timeout, trigger })` / `waitForRequest`:** `match` is a URL pattern (same rules as `page.route`) or a function of the response/request. The wait listens first, then runs `trigger`; a trigger that throws rejects the wait with that error and leaves nothing listening. `timeout` defaults to the navigation timeout. The timeout error names what was awaited: `waitForResponse(): no response matching "**/api/users" within 5000ms` (`/regex/` and `the given function` likewise).
-- **`setCacheDisabled(disabled)`** is `network.setCacheBehavior` with `bypass` / `default` for this page; an unsupported browser gives `UnsupportedOperationError`.
-- **Firefox 153 facts** (probed, then browser-tested): `addDataCollector`, `getData` (text as `string`, binary as `base64`, readable repeatedly until disowned), `disownData`, `removeDataCollector` and `setCacheBehavior` all work; `getData` for `dataType: "request"` answers `no such network data` for a plain GET, so request bodies were left out; with the cache on, two fetches of a `max-age` resource hit the server once, with `bypass` twice.
-- Tests: `network/data-collector.test.ts`, `network/response.test.ts`, the "Page network data" block in `browser/page.test.ts`, `network/network-data.browser-test.ts` (port 9243: JSON, text, binary, empty, document and redirect bodies, click trigger, size limit through a second `Page` view with a small `maxBodySize`, cache on/off against a request-counting server).