@itmetsam/samurai-framework 0.1.0 → 0.2.0

package/docs/superpowers/recorder-roadmap.md

@@ -1,52 +0,0 @@
-# Recorder — roadmap
-
-Date: 2026-10-01
-Status: planning. No spec written yet.
-UI: the Electron app at `~/dev/itmetsam/projects/samurai` (designs: "SAMURAI" design canvas, boards "Test editor & recorder" and "Test editor · code view").
-
-Each item gets its own spec in `docs/superpowers/specs/` and its own plan. Order respects dependencies (`←`).
-
-## Decisions so far
-
-- **Audience: non-technical testers.** Recording, editing and replaying happen in the Electron UI; nobody has to touch code.
-- **Source of truth: the `.spec.ts` file.** The steps view is parsed from it and edits are written back with minimal diffs ("edit either one and the other updates"). The recorder emits a restricted set of known step calls so parsing is reliable; any statement outside that set becomes a "Custom code" step.
-- **Recording browser: external window for now.** The engine launches the browser over BiDi; the tester interacts in that window while the Electron app shows steps live. In-page overlay handles the Alt+click assertion picker. Embedding the page in the Electron editor panel (as the designs show) is **required later** — see item 7.
-
-## Todo
-
-### Phase 1 — framework prerequisites
-- [x] **1. Test API alignment** — `describe`, `test(name, async ({ page, browser, env, secrets }) => …)` fixtures, `page.goto` resolving relative URLs against the environment's `baseURL`; environment selection, per-environment variables and timeout precedence (run > environment > project); a secrets provider interface (env-var/`.env` provider now, keychain/vault plugged in by the Electron app later) with masking in logs and reports. — [spec](specs/2026-10-01-test-api-alignment-design.md)
-- [ ] **2. Semantic locators** — `getByRole`, `getByLabel`, `getByTestId`, `getByText`, plus an ordered fallback-locator list per step (input for self-healing).
-
-### Phase 2 — recorder core
-- [ ] **3. Step codec** ← 1, 2 — steps model, parser (TS AST → steps, unknown → "Custom code"), minimal-diff writer.
-- [ ] **4. Recorder engine** ← 2, 3 — preload capture over a `script.addPreloadScript` channel, locator ranking (verified to match exactly one element), step normalisation (merge typing into `fill`, drop focus clicks, navigation waits), record-from-line N, Alt+click assertions.
-
-### Phase 3 — UI
-- [ ] **5. Recorder UI (Electron)** ← 3, 4 — steps panel, step inspector, IPC to the engine, live step stream while recording.
-
-### Phase 4 — browsers
-- [ ] **6. Chrome support** — likely via the `chromium-bidi` mapper (BiDi over CDP). Separate from the recorder, but item 7 builds on it.
-- [ ] **7. Embedded recording browser (Electron + chromium-bidi)** ← 6 — **required**: the designs show the recorded page inside the editor panel.
-  - Idea: render the page under test in a `WebContentsView`, expose CDP (`remote-debugging-port` or `webContents.debugger`), run the `chromium-bidi` mapper in the main process, and add a framework transport that talks BiDi to it. Everything above the transport stays unchanged.
-  - Risks to settle in a spike first:
-    - The debugging port exposes every Electron window over CDP, including SAMURAI's own UI. It must be filtered to the recording view, and a local open port is a security concern (prefer a pipe or `webContents.debugger`).
-    - The mapper expects browser-level CDP (`Target.*`, `Browser.*`); a page-level `webContents.debugger` session may not be enough.
-    - User contexts (`createBrowserContext`), downloads and some emulation may behave differently in Electron.
-    - Firefox can't be embedded: in-app recording is Chromium-only. Replay still runs in Firefox and Chrome.
-  - Spike (throwaway): the mapper drives one `WebContentsView` in Electron 41 and runs `browsingContext.navigate` and `script.callFunction`.
-  - Considered and rejected: **Tauri**. It uses the OS webview (WKWebView on macOS, WebView2 on Windows, WebKitGTK on Linux); only WebView2 exposes CDP, so in-app recording would work on Windows only.
-
-### Later (not scheduled)
-- AI-suggested assertions, self-healing (selector fixes), AI agent recording. All build on item 4.
-- `api.<name>` fixture: per-environment HTTP client with auth from a secret (designs: "Environment settings" → APIs). Builds on item 1.
-- Masking secrets in screenshots, videos and traces (item 1 only masks logs and reports).
-
-## Dependency graph
-
-```
-1 ─┐
-   ├─ 3 ─┬─ 4 ── 5
-2 ─┴─────┘
-6 ── 7
-```

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

@@ -1,185 +0,0 @@
-# Auto-waiting actions — design
-
-Date: 2026-09-29
-Status: approved in brainstorming, pending spec review
-Depends on: the `expect` feature (`docs/superpowers/specs/2026-09-29-expect-design.md`), including its final fix wave (commits 6b5ed5b, e802a96, 0a377cf).
-
-## Goal
-
-Locator actions (`click`, `fill`, `focus`) wait until the element is ready for that action instead of firing once and throwing. Waiting uses one retry mechanism shared with `expect`, with a clear error naming the unmet check.
-
-```ts
-await page.locator("button[@type='submit']").click();          // waits: attached, visible, stable, enabled, not covered
-await page.locator("input[@id='name']").fill("Sam", { timeout: 10000 });
-await page.locator("div[@class='spinner']").waitFor({ state: "hidden" });
-await page.locator("button[@id='hidden-debug']").click({ force: true });
-```
-
-## Non-goals
-
-- Waiting in reads (`textContent`, `inputValue`, `isVisible`, …) — they stay instant; `expect()` does the waiting for reads.
-- New actions (`hover`, `press`, `check`, `selectOption`, …) — later work; they reuse this mechanism.
-- `toBeEnabled` / `toBeEditable` matchers — enabled by the new reads, added later.
-- Shadow DOM, iframes, CSS selectors.
-
-## Components
-
-### `src/wait/wait-until.ts` (new) — the one retry mechanism
-
-```ts
-export interface WaitOptions { timeout: number; interval?: number } // interval default 100
-
-export async function waitUntil<T>(
-  probe: () => Promise<T>,
-  isDone: (current: T, previous: T | undefined) => boolean,
-  options: WaitOptions,
-): Promise<T>;
-
-export async function resolveTimeout(perCall?: number): Promise<number>;
-// perCall → config `expect.timeout` → 5000
-
-export class WaitTimeoutError<T> extends Error {
-  readonly timeout: number;
-  readonly last: T | undefined;      // last completed probe result, undefined if none completed
-}
-```
-
-Behaviour (carries over the `expect` loop semantics after fix F3, plus the clamp from that fix's open concern):
-
-1. Always probes at least once.
-2. `timeout === 0`: the single probe is awaited un-raced; `isDone` false → `WaitTimeoutError` with that result.
-3. `timeout > 0`: each probe races the time remaining to the deadline. If the deadline wins, throw `WaitTimeoutError` with `last` = the last completed result (or `undefined`).
-4. After a completed probe: `isDone(current, previous)` true → resolve with `current`. Otherwise, if the deadline has passed → `WaitTimeoutError`; else sleep `min(interval, remaining)`. A probe is only started while time remains, so after the final clamped sleep the wait ends at the deadline instead of starting a probe that could only lose the race (resolves the open concern from expect fix F3).
-5. Errors thrown by `probe` are rethrown immediately.
-6. Race timers are cleared when the probe wins; no timer outlives the call.
-
-`LocatorAssertions.assertEventually` in `src/assert/expect.ts` is rewritten on top of `waitUntil` with identical observable behaviour: `WaitTimeoutError` with `last` → `AssertionError` with `actual = last`; without `last` → `Error("expect(locator).<name>: could not read <selector> within <timeout>ms")`. `resolveTimeout` moves from `expect.ts` to `wait-until.ts`. The existing `expect` tests must pass unchanged.
-
-### `src/locator/element-state.ts` (new) — browser-side probe
-
-```ts
-export interface ElementBox { x: number; y: number; width: number; height: number } // viewport coords
-export interface ElementState {
-  attached: boolean;
-  visible: boolean;
-  enabled: boolean;
-  editable: boolean;
-  box: ElementBox | null;            // after any scroll; null when not attached
-  hitTarget: "self" | string | null; // "self", a description of the covering element, or null when not checked / not attached
-}
-export interface ProbeOptions { scroll: boolean; hitTest: boolean }
-
-export function elementStateScript(elementExpression: string, options: ProbeOptions): string;
-export function parseElementState(value: RemoteValue): ElementState;
-```
-
-One `script.evaluate` per poll returns the whole state as a JSON string (parsed by `parseElementState`, which throws on a malformed result).
-
-Check definitions (browser side):
-
-| Check | Definition |
-|---|---|
-| attached | the xpath matches an element |
-| visible | box width and height > 0 and computed style not `display:none`, `visibility:hidden`, `opacity:"0"` (same rule as `isVisible()`) |
-| enabled | `!el.matches(":disabled")` and `el.getAttribute("aria-disabled") !== "true"` |
-| editable | enabled, and not `el.readOnly`, and (a text-type `<input>` — type in text, search, email, url, tel, password, number, or missing — or `<textarea>` or `el.isContentEditable`) |
-| stable | computed in Node: `box` equal (all four numbers) to the previous poll's `box`, both non-null |
-| hit target | with `hitTest`: `document.elementFromPoint(centerX, centerY)` is `el` or `el.contains(it)` → `"self"`; otherwise a description `tag#id.class1.class2` of the topmost element (`"nothing"` when `elementFromPoint` returns null) |
-
-Scrolling: with `scroll`, when attached and the box is not fully inside the viewport, call `el.scrollIntoView({ block: "center", inline: "center" })` before measuring `box` and hit target.
-
-### `src/locator/locator.ts` changes
-
-```ts
-export interface ActionOptions { timeout?: number; force?: boolean }
-export type WaitForState = "attached" | "detached" | "visible" | "hidden";
-
-click(options?: ActionOptions): Promise<void>;
-fill(value: string, options?: ActionOptions): Promise<void>;
-focus(options?: ActionOptions): Promise<void>;
-waitFor(options?: { state?: WaitForState; timeout?: number }): Promise<void>; // state default "visible"
-isEnabled(): Promise<boolean>;   // instant; false when missing
-isEditable(): Promise<boolean>;  // instant; false when missing
-```
-
-- `click()` and `focus()` now return `Promise<void>` (previously leaked the raw BiDi `RemoteValue`).
-- `clickRect(rect)` stays public and unchanged.
-- The actions click with real BiDi pointer input at the centre of the **latest** measured box.
-
-### `src/locator/action-timeout-error.ts` (new)
-
-```ts
-export class ActionTimeoutError extends Error {
-  readonly action: string;             // "click" | "fill" | "focus" | "waitFor"
-  readonly selector: string;
-  readonly timeout: number;
-  readonly checks: Record<string, "pass" | "fail" | "pending"> | undefined;
-  readonly coveredBy: string | undefined;
-}
-```
-
-The runner reports it through the existing `toTestError` path as `type: "error"` (not an assertion).
-
-## Per-action flow
-
-Every poll is one probe round trip. Checks are evaluated in the listed order; the first failing check is the reason in the error.
-
-| Action | Probe options | Done when | Then |
-|---|---|---|---|
-| `click()` | scroll, hitTest | attached, visible, stable, enabled, hit = self | pointer move/down/up at centre of latest box |
-| `fill()` | scroll, hitTest | attached, visible, enabled, editable, hit = self | pointer click at centre (focus), select existing value, type (existing `fill` behaviour; `""` → Backspace) |
-| `focus()` | none | attached | `el.focus()` |
-| `waitFor({ state })` | none | attached: attached · detached: not attached · visible: attached and visible · hidden: not attached or not visible | resolve |
-
-With `timeout: 0` the *stable* check is dropped from `click()`'s required checks (it needs two probes); there is still exactly one probe.
-
-`force: true` (click, fill, focus): skip every check except *attached*; still scroll into view (click, fill) and use the real pointer.
-
-## Errors
-
-Timeout message, built from the last completed probe:
-
-```
-click(): //button[@type="submit"] was not actionable within 5000ms
-  attached ✓  visible ✓  stable ✓  enabled ✗  hit target —
-```
-
-- Symbols: `✓` pass, `✗` fail, `—` not evaluated because an earlier check failed.
-- Covered element: the hit-target entry reads `hit target ✗ (covered by div#cookie-banner.overlay)`.
-- Never attached: `click(): //button[@type="submit"] was not attached within 5000ms`.
-- No probe completed before the deadline: `click(): could not read //button[@type="submit"] within 5000ms`.
-- `waitFor`: `waitFor(): //div[@class="spinner"] did not become hidden within 5000ms`.
-
-Probe errors (invalid xpath, navigation destroying the execution context) are rethrown immediately.
-
-## Timeouts
-
-- Resolution: per-call `{ timeout }` → config `expect.timeout` → `5000` (shared with `expect` via `resolveTimeout`).
-- `timeout: 0` checks once without waiting; the stability check is skipped because it needs two probes.
-- A test timeout closes the browser; the in-flight probe then fails or never settles, and `waitUntil`'s deadline race ends the action within its own timeout.
-
-## Behaviour changes (intended, user-visible)
-
-- `click()` is a real pointer click (trusted events; hover/mousedown/mouseup fire) instead of the synthetic `el.click()`.
-- Actions on a missing element wait up to the timeout instead of throwing immediately.
-- `click()` / `focus()` resolve to `void`.
-
-## Testing
-
-- Unit (`npm test`, no browser):
-  - `src/wait/wait-until.test.ts` — fake probes: at least one probe; probe until done; `previous` passed to `isDone`; timeout with last value; `timeout: 0` single un-raced probe; probe error rethrown without retry; never-settling probe stops at the deadline; final sleep clamped to remaining time; no leftover timers.
-  - `src/locator/element-state.test.ts` — script compiles for all option combinations; embeds the element expression; `parseElementState` round-trips and rejects malformed values.
-  - `src/locator/locator-actions.test.ts` — stub connector with scripted `ElementState` sequences:
-    - `click()` retries through not attached → hidden → moving → disabled → covered → actionable, then sends exactly one pointer click at the latest box centre;
-    - timeout error text for each failing check, covered-by, never-attached and no-probe cases;
-    - `force` skips checks but still requires attached;
-    - `fill()` waits for editable, then keeps the select-then-type sequence;
-    - `focus()` waits for attached only;
-    - `waitFor` for all four states and its error text;
-    - `isEnabled()` / `isEditable()`.
-  - Existing `expect` tests pass unchanged (regression net for the `waitUntil` refactor).
-- Browser (opt-in, `npm run test:browser` → `tsx --test "src/**/*.browser-test.ts"`, headless Firefox; not matched by `npm test`'s `src/**/*.test.ts` glob because the suffix is `-test.ts`, not `.test.ts`):
-  - Fixtures injected into a blank page via `script.evaluate` (no external site, no real form submissions): button enabled after 300 ms; overlay removed after 300 ms; element sliding for 300 ms; button below the fold; readonly input; an `opacity:0` button for `force` (not "visible" by our rule, yet still hit-testable — a truly hidden or covered element cannot receive a real pointer click, with or without `force`); an element removed after 300 ms for `waitFor({ state: "hidden" })`; disabled and covered buttons for the timeout errors.
-  - The fixtures load `about:blank`, which needs `Page.navigateTo` to keep URLs that already have a scheme (today it turns any non-`http` URL into the literal `https://url`); the plan fixes that as part of the browser-test task.
-  - Each asserts the action succeeds or fails with the specified message.
-- TDD: each test before its implementation.

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

@@ -1,130 +0,0 @@
-# BiDi foundation — design
-
-Date: 2026-09-29
-Status: implemented (see "Implementation notes")
-Roadmap item: 0 (prerequisite of every other BiDi spec)
-
-## Goal
-
-Fix the transport gaps that make every later feature unreliable, and add the shared primitives (typed commands, refcounted subscriptions, event waiting, context tree) the other specs build on.
-
-## Problems found in the current code
-
-1. `BiDiConnector.messageListener` handles only `type: "success"` and `"event"`. A `type: "error"` reply is dropped and its promise stays in `resolveMap` forever, so a failing command hangs until some outer timeout.
-2. `Browser.newPage()` sends `browsingContext.create` but returns `new Page(connector, "")`, an empty context id.
-3. The subscribed events are a hardcoded list in `Browser.launch` (`["browsingContext.load"]`); `onEvent` for anything else silently never fires.
-4. `Page.waitForNetworkIdle` leaks its listener and never resolves if `load` already fired (fixed properly in the network-tracking spec, but needs the primitives here).
-5. `BiDiCommands` lacks most commands the other specs use (see Typing).
-
-## Non-goals
-
-- Multi-browser support, reconnecting after socket loss, BiDi over pipes.
-- Public API for the primitives below; they are internal to `src/transport` and `src/browser`.
-
-## Components
-
-### Error replies — `src/transport/bidi-error.ts` (new)
-
-```ts
-export class BiDiError extends Error {
-  readonly code: string;        // BiDi error code: "no such node", "invalid argument", "unknown error", …
-  readonly command: string;     // e.g. "script.callFunction"
-  readonly remoteStack?: string;
-}
-```
-
-`messageListener` handles `{ type: "error", id, error, message, stacktrace }`: look up `id`, reject with `BiDiError`, delete the entry. `resolveMap` entries store the method name for the error. A reply with an unknown `id` is logged at debug level and ignored. `rejectAll` (socket close/error) keeps rejecting with plain errors, now including the pending method names in the message.
-
-### Send timeout
-
-`send(method, params, { timeout? })`: default `commandTimeout` from config (`bidi.commandTimeout`, default 30000). On expiry: delete the map entry and reject with `BiDiError` code `"timeout"`. A late reply for a deleted id is ignored. Commands known to block legitimately (`browsingContext.navigate` with `wait: "complete"`, `browsingContext.print`) pass their own timeout.
-
-### Refcounted subscriptions — `src/transport/subscriptions.ts` (new)
-
-```ts
-connector.subscribe(events: (keyof BiDiEvents)[], options?: { contexts?: string[] }): Promise<Subscription>;
-interface Subscription { readonly id: string; unsubscribe(): Promise<void> }
-```
-
-- Refcount per event name (global scope). First subscriber of an event sends `session.subscribe { events: [name] }` and stores the returned `subscription` id; last unsubscriber sends `session.unsubscribe { subscriptions: [id] }`.
-- Context-scoped subscriptions send `contexts` and are not shared; they always issue their own command.
-- `Browser.launch` stops subscribing to a hardcoded list; `browsingContext.load` is subscribed by the feature that needs it.
-- `unsubscribe()` is idempotent.
-- Module-level events (e.g. `network`) subscribe to all their events on `session.subscribe`; the connector's typed event map stays per-event.
-
-### Event waiting
-
-```ts
-connector.waitForEvent<E extends keyof BiDiEvents>(
-  event: E,
-  predicate: (params: BiDiEvents[E]["params"]) => boolean,
-  options: { timeout: number; signal?: AbortSignal },
-): Promise<BiDiEvents[E]["params"]>;
-```
-
-Registers the listener before returning (so callers can start the triggering command afterwards without racing), removes it on match, timeout or abort. Timeout rejects with `WaitTimeoutError` (from `src/wait/wait-until.ts`).
-
-### Context tree — `src/browser/context-tree.ts` (new)
-
-```ts
-class ContextTree {
-  static create(connector): Promise<ContextTree>;  // getTree + subscribe browsingContext.contextCreated/contextDestroyed
-  parentOf(context: string): string | null;
-  rootOf(context: string): string;                 // the top-level context
-  isWithin(context: string, root: string): boolean;
-  dispose(): Promise<void>;
-}
-```
-
-Events for iframes carry the child's context id; features that filter by page (`network`, `log`, prompts) call `tree.isWithin(event.context, page.contextId)`.
-
-### `Browser.newPage` / `Page`
-
-- `newPage` returns `new Page(connector, result.context)`. `background`/`userContext` keep passing through.
-- `Page` exposes a read-only `contextId` getter (tests currently reach into private fields).
-- `Page` owns a `ContextTree` instance created lazily and shared by features.
-
-### Typing
-
-Add to `src/types/bidi-modules/*.d.ts` and `BiDiCommands`/`BiDiEvents` (params/result per the spec), each with a one-line doc comment:
-
-| Module | Commands |
-|---|---|
-| script | `callFunction`, `disown`, `addPreloadScript`, `removePreloadScript` |
-| browsingContext | `locateNodes`, `handleUserPrompt`, `setViewport`, `reload`, `traverseHistory`, `close`, `print` |
-| input | `setFiles` |
-| network | `addIntercept`, `removeIntercept`, `continueRequest`, `continueResponse`, `continueWithAuth`, `provideResponse`, `failRequest`, `setCacheBehavior`, `addDataCollector`, `removeDataCollector`, `getData`, `disownData` |
-| browser | `createUserContext`, `removeUserContext`, `getUserContexts`, `setDownloadBehavior` |
-| session | `unsubscribe` |
-| emulation | all `emulation.set*` (types exist; only wire into `BiDiCommands`) |
-
-The `network` and `emulation` modules are currently missing from `BiDiCommands` entirely. A compile-time test (`src/types/bidi-commands.test-d.ts` checked by `tsc --noEmit`) asserts each method above resolves to a params/result pair.
-
-## Errors
-
-| Situation | Behaviour |
-|---|---|
-| `type:"error"` reply | reject with `BiDiError` |
-| No reply within timeout | reject with `BiDiError` code `"timeout"` |
-| Socket closed | reject all pending; message names the methods |
-| Command not supported by the browser | `BiDiError` code `"unknown command"` / `"unsupported operation"`, unchanged (features wrap where they need friendlier text) |
-
-## Testing
-
-- Unit (stub connector): error reply rejects the right promise only; unknown-id reply ignored; timeout rejects and a late reply does not throw; refcount sends one `session.subscribe` for two subscribers and one `unsubscribe` after both leave; double `unsubscribe()` is a no-op; `waitForEvent` registers before resolving, cleans up on all three exits; `ContextTree` parent/root/`isWithin` including destroyed contexts.
-- Browser: `newPage()` returns a page whose `navigateTo("about:blank")` works; a deliberately invalid command (`script.evaluate` with bad target) rejects with `code: "no such frame"` within a second.
-- TDD: tests first.
-
-## Implementation notes
-
-Deviations and details settled while implementing:
-
-- `session.unsubscribe` takes `{ subscriptions }` or `{ events }`; the connector only uses subscription ids.
-- A new subscriber that arrives while the last one is still unsubscribing keeps the existing subscription (no unsubscribe/subscribe churn); the per-event command queue makes this safe.
-- Multi-event `subscribe([...])` sends one `session.subscribe` per event so refcounts stay per event; a failure part-way rolls back the events already acquired.
-- `commandTimeout` is a `BiDiConnector` option, read once at launch from config `bidi.commandTimeout` (a missing config falls back to 30000), instead of a config read per `send`.
-- `Page.waitForNetworkIdle` now subscribes to `browsingContext.load` itself, waits with `waitForEvent` (30000 ms cap) and unsubscribes; its real replacement is the network-tracking spec.
-- `Page.tree()` is the lazily created, shared `ContextTree`; nothing creates it until a feature needs it.
-- Type fix: `Info.children` is `InfoList | null` (was `InfoList[]`), `parent` may be `null`, `originalOpener` may be `null`.
-- `src/testing/fake-websocket.ts` (`FakeWebSocket`, `autoReply`, `tick`) is the new unit-test seam for the real connector; `stubConnector` is unchanged.
-- Tests: `transport/{bidi-connection,subscriptions}.test.ts`, `browser/{context-tree,browser}.test.ts`, additions to `browser/page.test.ts`, `types/bidi-commands.test-d.ts` (compile-time, via `tsc --noEmit`), and `transport/foundation.browser-test.ts` (real Firefox).

package/docs/superpowers/specs/2026-09-29-contexts-and-storage-design.md

@@ -1,88 +0,0 @@
-# User contexts and storage — design
-
-Date: 2026-09-29
-Status: implemented (see "Implementation notes")
-Roadmap item: 12
-Depends on: bidi-foundation
-
-## Goal
-
-Cheap isolated browser sessions (separate cookies, storage, cache) inside one browser process, and a cookie API that is scoped to them. Base for parallel tests and multi-user scenarios.
-
-```ts
-const alice = await browser.newContext();
-const bob = await browser.newContext();
-const pageA = await alice.newPage();
-await alice.addCookies([{ name: "sid", value: "1", domain: "example.com" }]);
-await bob.close();
-```
-
-## Non-goals
-
-- Parallel test execution (only the primitive it needs; the runner currently launches one browser per test and keeps doing so).
-- Persistent profiles per context, proxy per context (`createUserContext.proxy` is left out until needed).
-- Cross-context storage copying.
-
-## Components
-
-### `BrowserContext` (rewrite of the test helper in `src/browser/browser-context.ts`)
-
-The existing file holds only the test-only `setContent`; it moves to `src/testing/set-content.ts` (imports updated) and the file becomes the real class.
-
-```ts
-class BrowserContext {
-  readonly id: string;                                   // BiDi userContext, "default" for the default one
-  newPage(): Promise<Page>;                              // browsingContext.create { type: "tab", userContext }
-  pages(): Page[];
-  addCookies(cookies: Cookie[]): Promise<void>;          // storage.setCookie, partition { type: "context", userContext }
-  cookies(filter?: { name?: string; domain?: string; path?: string }): Promise<Cookie[]>; // storage.getCookies
-  clearCookies(filter?): Promise<void>;                  // storage.deleteCookies
-  close(): Promise<void>;                                // browser.removeUserContext, closes its pages
-}
-```
-
-`Browser` additions:
-
-```ts
-newContext(options?: { acceptInsecureCerts?: boolean; unhandledPromptBehavior?: … }): Promise<BrowserContext>; // browser.createUserContext
-contexts(): BrowserContext[];                               // browser.getUserContexts
-defaultContext: BrowserContext
-```
-
-- `Browser.newPage()` delegates to `defaultContext.newPage()` and returns a working `Page` (bug fix owned by the foundation spec).
-- `Browser.getCookie` / `setCookie` (existing) are kept and delegate to `defaultContext` with the `partition` argument still accepted.
-- Cookie value conversion: BiDi cookies carry `value: { type: "string" | "base64", value }`; the public `Cookie` uses plain strings (base64 only when `valueEncoding: "base64"`). `sameSite`, `httpOnly`, `secure`, `expiry` map 1:1. `domain` is mandatory in BiDi; `addCookies` throws `TypeError` when missing and no `url` was given (`url` is parsed for domain/path/secure).
-- `BrowserContext.close()` removes the user context; the browser closes its tabs. `Page`s of that context reject further use with `Error("page closed")`.
-- Context ids for `Page`: a `Page` remembers its `BrowserContext` so `page.context()` works and cookie helpers on `Page` (`page.context().addCookies`) are scoped correctly.
-- Cleanup: `Browser.close()` closes all contexts first (best effort), then the browser.
-
-### Storage partitions
-
-`storage.*` commands take `partition`: `{ type: "context", context }` (by top-level context) or `{ type: "storageKey", userContext, sourceOrigin }`. `BrowserContext` cookies use `{ type: "storageKey", userContext }`; the returned `partitionKey` is ignored on read.
-
-## Errors
-
-| Situation | Error |
-|---|---|
-| Removing the default context | `Error("cannot close the default context")` |
-| Cookie without domain/url | `TypeError` |
-| `no such user context` | `BiDiError` (context already removed) |
-
-## Testing
-
-- Unit (stub connector): create/remove payloads; `newPage` passes `userContext`; cookie mapping both ways incl. base64 and `url` parsing; `close` order (pages, then remove); default-context guard; `Browser.getCookie/setCookie` still work.
-- Browser: two contexts; a cookie set in one is invisible to the other (via `document.cookie` on a local server origin); `clearCookies` with filter; closing a context closes its pages; the old `newPage()` bug (empty context id) has a regression test navigating the returned page.
-- TDD: tests first.
-
-## Implementation notes
-
-- **Where:** `browser/browser-context.ts` (`BrowserContext`, `Cookie`, `CookieInput`, `CookieFilter`), `Browser.newContext/contexts/defaultContext`, `Page.context()`. The old contents of that file (a test-only `setContent` copy nobody imported; tests use `testing/browser-fixture.ts`) were replaced, so nothing had to move.
-- **`browser.newPage(options)` keeps its BiDi-shaped signature** and sends exactly what it is given (existing tests depend on that); it attaches the page to the context named by `userContext` (the default one when absent or `"default"`). `context.newPage()` calls it with `userContext` for a user context and without for the default one. The page `Browser.launch` returns belongs to the default context. `Browser.getCookie/setCookie` stay as raw partition-based calls.
-- **`browser.contexts()` is sync and lists the default context plus the contexts this browser created** (not `browser.getUserContexts`): Firefox keeps user contexts in its profile, so that command also lists contexts left by earlier runs. A page opened with a `userContext` id this browser did not create adopts a context object for it.
-- **Contexts are removed with the browser.** `Browser.close()` closes the contexts still open before it closes the browser (failures ignored), because otherwise every context a test forgets stays in the test profile. A browser test relaunches the browser after closing and checks none of the ids it created remain.
-- **Cookies:** `addCookies` takes plain string values, a `domain` or a `url` (then domain, path and `secure` come from it unless given; `path` defaults to `/`), and checks every cookie before storing any. `cookies(filter?)` returns plain cookies (`value` a string, `expiry` only for persistent ones); `clearCookies(filter?)`. All use the partition `{ type: "storageKey", userContext }`, which for the default context is `"default"`. The local partition typing said `"storagekey"`; the browser only accepts `"storageKey"`.
-- **Base64 cookie values were left out:** Firefox returns a base64 value as a Latin-1 string (`héllo` comes back as `héllo`), so a round trip would garble text; `cookies()` still decodes a `base64` value if a browser sends one.
-- **`BrowserContext.close()`** removes the user context (the browser closes its tabs), then marks its pages closed (`Page.detach()`, which releases what they registered) and drops it from `browser.contexts()`. `no such user context` counts as closed; the default context cannot be closed (`cannot close the default context`); a second call does nothing; other errors leave it open. After closing, `newPage`, `addCookies`, `cookies` and `clearCookies` throw `context closed`.
-- **Firefox 153 facts:** `createUserContext` (also `acceptInsecureCerts`), `getUserContexts`, `removeUserContext` (closes the tabs; the default context answers `invalid argument`), cookies isolated per user context (`document.cookie` in the other context is empty), `setCookie` without a partition writes to the default context; a new context inherits the session's `unhandledPromptBehavior`, so dialogs there are handled by the same page policy.
-- **Not done:** per-context proxy, persistent profiles per context, cross-context storage copying (non-goals); `emulation` options on `newContext` come with the emulation spec.
-- Tests: `browser/browser-context.test.ts` (24), `browser/browser-context.browser-test.ts` (port 9245; isolation, cookies through `document.cookie`, closing, dialog and viewport in a new context, leftovers checked after the browser closed with a second launch on port 9246).

package/docs/superpowers/specs/2026-09-29-downloads-and-file-dialogs-design.md

@@ -1,94 +0,0 @@
-# Downloads and file dialogs — design
-
-Date: 2026-09-29
-Status: implemented (see "Implementation notes")
-Roadmap item: 14
-Depends on: bidi-foundation, set-files (file chooser reuses `setFiles`)
-
-## Goal
-
-Test downloads and native file pickers.
-
-```ts
-const download = await page.waitForDownload({ trigger: () => link.click() });
-console.log(download.suggestedFilename(), download.url());
-const file = await download.path();          // resolves once the download completed
-await download.cancel?.();                   // only if the browser supports it (see below)
-
-const chooser = await page.waitForFileChooser({ trigger: () => button.click() });
-await chooser.setFiles("./fixtures/a.png");
-```
-
-## Non-goals
-
-- Streaming download contents, resuming, progress events beyond start/end.
-- Downloads from other tabs.
-- Saving to arbitrary user-chosen folders per download (folder is per context/browser).
-
-## Downloads
-
-### Events and command
-
-- `browsingContext.downloadWillBegin { context, navigation, url, suggestedFilename, timestamp }` and `browsingContext.downloadEnd { …, status: "complete" | "canceled", filepath? }`.
-- `browser.setDownloadBehavior { downloadBehavior: { type: "allowed", destinationFolder } | { type: "denied" } | null, userContexts? }` sets where files land. The framework sets `allowed` with a per-test temp folder (`<config downloadsDir, default result/downloads>/<testId>/`) on page creation so downloads are deterministic and cleaned by the runner with the other artifacts. `null` restores the browser default.
-- Browser support gate: `setDownloadBehavior` is newer than the events. If Firefox lacks it (`unknown command`), `page.waitForDownload` still works using the events, `download.path()` returns the `filepath` from `downloadEnd`, and the folder option throws `UnsupportedOperationError`. Confirmed by a browser test before the destination-folder feature ships.
-
-### `src/browser/download.ts` (new)
-
-```ts
-class Download {
-  url(): string;
-  suggestedFilename(): string;
-  path(): Promise<string>;              // resolves on downloadEnd complete; rejects on canceled
-  failure(): Promise<string | null>;    // "canceled" or null
-}
-page.waitForDownload(options: { trigger?: () => Promise<unknown>; timeout?: number }): Promise<Download>;
-page.on("download", (d: Download) => …);
-```
-
-- Correlation: `downloadEnd` matched to `downloadWillBegin` by `navigation` id.
-- `waitForDownload` registers its `waitForEvent` **before** running `trigger`, then resolves on `downloadWillBegin` (not on end). `timeout` defaults to the navigation timeout (30000).
-- `path()` has its own timeout (same default). A canceled download rejects with `DownloadError { url, reason: "canceled" }`.
-- Subscription (refcounted) to both events from `Page` creation so `page.on("download")` and early downloads are not missed; events filtered by `ContextTree`.
-
-## File dialogs
-
-- `input.fileDialogOpened { context, element?, multiple }` fires when a click would open the native picker. Subscribed from page creation. Firefox may open the OS dialog unless it is suppressed; the browser test verifies that headless Firefox does not hang (the dialog is not shown headless).
-- `page.waitForFileChooser({ trigger?, timeout? }): Promise<FileChooser>`.
-
-```ts
-class FileChooser {
-  isMultiple(): boolean;
-  element(): Locator | null;               // Locator pinned to the element (locate-nodes `handle` selector) when `element` was provided
-  setFiles(files: string | string[]): Promise<void>;  // input.setFiles on that element; reuses set-files validation
-}
-```
-
-- If `element` is absent in the event (browser omitted it), `setFiles` throws `Error("file chooser has no element reference")`.
-- Unhandled dialogs are not answered; a picker that is opened while nobody waits is ignored (the headless browser closes it).
-
-## Errors
-
-| Situation | Error |
-|---|---|
-| No download within timeout | `WaitTimeoutError` → `waitForDownload(): no download started within <t>ms` |
-| Download canceled | `DownloadError` from `path()` |
-| `setDownloadBehavior` unsupported | `UnsupportedOperationError` (events still work) |
-| Chooser without element | `Error` as above |
-
-## Testing
-
-- Unit (stub connector): behaviour set on page creation with per-test folder; `waitForDownload` registers before `trigger`; begin/end correlation by navigation id; canceled → rejection; `path()` timeout; iframe event accepted, foreign ignored; `FileChooser` mapping to `setFiles` with the event's element and `multiple` guard; missing element error.
-- Browser (local server with `Content-Disposition: attachment`): download completes and file content matches; `suggestedFilename`; canceled/failed download (server aborts) rejects; `<input type=file>` click yields a chooser and `setFiles` populates `input.files`; behaviour of unsupported `setDownloadBehavior` recorded by an explicit skip-with-reason.
-- TDD: tests first.
-
-## Implementation notes
-
-- **Where:** `browser/download.ts` (`Download`, `DownloadTracker`, `DownloadError`, `DownloadTimeoutError`), `browser/file-chooser.ts` (`FileChooser`, `FileChooserTracker`), `browser/downloads-dir.ts` (`prepareDownloadsDir`, `removeIfEmpty`), `browser/file-paths.ts` (`resolveFiles`, `assertIsFile`, shared with `Locator.setInputFiles`), `browser/page-wait.ts` (`DownloadWaitTimeoutError`, `FileChooserTimeoutError`), and on `Page`: `startDownloadTracking`, `startFileChooserTracking`, `waitForDownload`, `waitForFileChooser`, `page.on/once/off("download" | "filechooser")`. `Browser.downloadsDir`, config `downloadsDir` (default `result/downloads`).
-- **Everything in the draft works on Firefox 153, including `browser.setDownloadBehavior`** (probed, then browser-tested), so no fallback was needed. The framework calls it when the browser starts (`allowed`, into a new folder `<downloadsDir>/dl-<time>-<pid>-<n>` of the browser's own), so a test knows where downloads land and runs do not mix. A browser without the command gets no folder (`browser.downloadsDir` is undefined, a `warn` is logged) and the events still work. `Browser.close()` removes the folder again when nothing was downloaded into it, so runs do not pile up empty folders; a folder with downloads is left for the test artifacts.
-- **`Download`:** `url()`, `suggestedFilename()`, `path({ timeout? })` (waits for the end, resolves with the file the browser wrote, rejects with `DownloadError` when cancelled and `DownloadTimeoutError` after `timeout`, default the navigation timeout), `failure()` (null when complete, otherwise "canceled" or "page closed"). Ends are matched to beginnings by navigation id; an end nobody began is ignored; disposing the page fails downloads still going on with "page closed".
-- **`waitForDownload({ trigger, timeout })`** resolves when the download *starts*; it listens before `trigger` runs, and a trigger that throws rejects the wait with that error. The generic `Page.waitForPageEvent` now serves the request, response, download and file-chooser waits.
-- **Firefox 153 facts:** `downloadEnd`'s field is `filepath` (the local typing said `filePath`; fixed); a download the server breaks off, or one refused with `downloadBehavior: denied`, ends as `canceled`; when a name is taken Firefox saves under `report(1).csv` and its `suggestedFilename` already carries the suffix (`report(2).csv`); iframe downloads reach the page; `fileDialogOpened` fires for a click on the input and on its label, carries the input as a full node (`sharedId` is all that is used) and `multiple`, and nothing is shown in headless mode.
-- **`FileChooser`:** `isMultiple()` and `setFiles(files)` (resolves paths, checks every file exists and is a file before sending, refuses several files for a single-file input, sends `input.setFiles` for the element in the frame that opened the dialog; an empty list clears; `file chooser has no element reference` when the browser omitted it). The draft's `element(): Locator` was left out: locators no longer have a pinned-handle form (see the locate-nodes notes) and `setFiles` is what a test needs. A picker nobody waits for is simply ignored and does not hang the page.
-- **Cleanup in tests:** the browser test removes its downloads folder afterwards.
-- Tests: `browser/download.test.ts` (12), `browser/file-chooser.test.ts` (11), `browser/downloads-dir.test.ts`, the "Page downloads and file choosers" block in `browser/page.test.ts`, `browser/transfers.browser-test.ts` (port 9250, 13 tests).