npm - craftdriver - Versions diffs - 0.0.3 → 0.2.0 - Mend

craftdriver 0.0.3 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (192) hide show

package/CHANGELOG.md +104 -0
package/README.md +186 -10
package/bin/craftdriver.mjs +26 -0
package/dist/cli/client.d.ts +17 -0
package/dist/cli/client.d.ts.map +1 -0
package/dist/cli/client.js +88 -0
package/dist/cli/client.js.map +1 -0
package/dist/cli/daemon.d.ts +15 -0
package/dist/cli/daemon.d.ts.map +1 -0
package/dist/cli/daemon.js +145 -0
package/dist/cli/daemon.js.map +1 -0
package/dist/cli/defaults.d.ts +10 -0
package/dist/cli/defaults.d.ts.map +1 -0
package/dist/cli/defaults.js +42 -0
package/dist/cli/defaults.js.map +1 -0
package/dist/cli/dispatcher.d.ts +28 -0
package/dist/cli/dispatcher.d.ts.map +1 -0
package/dist/cli/dispatcher.js +319 -0
package/dist/cli/dispatcher.js.map +1 -0
package/dist/cli/index.d.ts +2 -0
package/dist/cli/index.d.ts.map +1 -0
package/dist/cli/index.js +404 -0
package/dist/cli/index.js.map +1 -0
package/dist/cli/init.d.ts +24 -0
package/dist/cli/init.d.ts.map +1 -0
package/dist/cli/init.js +192 -0
package/dist/cli/init.js.map +1 -0
package/dist/cli/mcp/artifacts.d.ts +43 -0
package/dist/cli/mcp/artifacts.d.ts.map +1 -0
package/dist/cli/mcp/artifacts.js +104 -0
package/dist/cli/mcp/artifacts.js.map +1 -0
package/dist/cli/mcp/server.d.ts +34 -0
package/dist/cli/mcp/server.d.ts.map +1 -0
package/dist/cli/mcp/server.js +214 -0
package/dist/cli/mcp/server.js.map +1 -0
package/dist/cli/mcp/tools.d.ts +34 -0
package/dist/cli/mcp/tools.d.ts.map +1 -0
package/dist/cli/mcp/tools.js +236 -0
package/dist/cli/mcp/tools.js.map +1 -0
package/dist/cli/parseArgs.d.ts +37 -0
package/dist/cli/parseArgs.d.ts.map +1 -0
package/dist/cli/parseArgs.js +215 -0
package/dist/cli/parseArgs.js.map +1 -0
package/dist/cli/protocol.d.ts +34 -0
package/dist/cli/protocol.d.ts.map +1 -0
package/dist/cli/protocol.js +2 -0
package/dist/cli/protocol.js.map +1 -0
package/dist/cli/selector.d.ts +29 -0
package/dist/cli/selector.d.ts.map +1 -0
package/dist/cli/selector.js +100 -0
package/dist/cli/selector.js.map +1 -0
package/dist/cli/snapshot.d.ts +48 -0
package/dist/cli/snapshot.d.ts.map +1 -0
package/dist/cli/snapshot.js +179 -0
package/dist/cli/snapshot.js.map +1 -0
package/dist/index.d.ts +14 -1
package/dist/index.d.ts.map +1 -1
package/dist/index.js +17 -1
package/dist/index.js.map +1 -1
package/dist/lib/a11y.d.ts +81 -0
package/dist/lib/a11y.d.ts.map +1 -0
package/dist/lib/a11y.js +171 -0
package/dist/lib/a11y.js.map +1 -0
package/dist/lib/bidi/connection.d.ts +62 -0
package/dist/lib/bidi/connection.d.ts.map +1 -0
package/dist/lib/bidi/connection.js +227 -0
package/dist/lib/bidi/connection.js.map +1 -0
package/dist/lib/bidi/index.d.ts +101 -0
package/dist/lib/bidi/index.d.ts.map +1 -0
package/dist/lib/bidi/index.js +163 -0
package/dist/lib/bidi/index.js.map +1 -0
package/dist/lib/bidi/logs.d.ts +104 -0
package/dist/lib/bidi/logs.d.ts.map +1 -0
package/dist/lib/bidi/logs.js +273 -0
package/dist/lib/bidi/logs.js.map +1 -0
package/dist/lib/bidi/network.d.ts +165 -0
package/dist/lib/bidi/network.d.ts.map +1 -0
package/dist/lib/bidi/network.js +477 -0
package/dist/lib/bidi/network.js.map +1 -0
package/dist/lib/bidi/storage.d.ts +83 -0
package/dist/lib/bidi/storage.d.ts.map +1 -0
package/dist/lib/bidi/storage.js +299 -0
package/dist/lib/bidi/storage.js.map +1 -0
package/dist/lib/bidi/types.d.ts +323 -0
package/dist/lib/bidi/types.d.ts.map +1 -0
package/dist/lib/bidi/types.js +6 -0
package/dist/lib/bidi/types.js.map +1 -0
package/dist/lib/browser.d.ts +776 -13
package/dist/lib/browser.d.ts.map +1 -1
package/dist/lib/browser.js +1547 -70
package/dist/lib/browser.js.map +1 -1
package/dist/lib/browserContext.d.ts +486 -0
package/dist/lib/browserContext.d.ts.map +1 -0
package/dist/lib/browserContext.js +937 -0
package/dist/lib/browserContext.js.map +1 -0
package/dist/lib/builder.d.ts +3 -0
package/dist/lib/builder.d.ts.map +1 -1
package/dist/lib/builder.js +31 -4
package/dist/lib/builder.js.map +1 -1
package/dist/lib/by.d.ts +18 -2
package/dist/lib/by.d.ts.map +1 -1
package/dist/lib/by.js +20 -2
package/dist/lib/by.js.map +1 -1
package/dist/lib/chrome.d.ts +13 -1
package/dist/lib/chrome.d.ts.map +1 -1
package/dist/lib/chrome.js +13 -17
package/dist/lib/chrome.js.map +1 -1
package/dist/lib/clock.d.ts +115 -0
package/dist/lib/clock.d.ts.map +1 -0
package/dist/lib/clock.js +407 -0
package/dist/lib/clock.js.map +1 -0
package/dist/lib/driver.d.ts +45 -0
package/dist/lib/driver.d.ts.map +1 -1
package/dist/lib/driver.js +129 -1
package/dist/lib/driver.js.map +1 -1
package/dist/lib/driverManager.d.ts +25 -0
package/dist/lib/driverManager.d.ts.map +1 -0
package/dist/lib/driverManager.js +399 -0
package/dist/lib/driverManager.js.map +1 -0
package/dist/lib/elementHandle.d.ts +69 -2
package/dist/lib/elementHandle.d.ts.map +1 -1
package/dist/lib/elementHandle.js +215 -40
package/dist/lib/elementHandle.js.map +1 -1
package/dist/lib/errors.d.ts +71 -0
package/dist/lib/errors.d.ts.map +1 -0
package/dist/lib/errors.js +73 -0
package/dist/lib/errors.js.map +1 -0
package/dist/lib/expect.d.ts +6 -1
package/dist/lib/expect.d.ts.map +1 -1
package/dist/lib/expect.js +55 -37
package/dist/lib/expect.js.map +1 -1
package/dist/lib/firefox.d.ts +18 -0
package/dist/lib/firefox.d.ts.map +1 -0
package/dist/lib/firefox.js +33 -0
package/dist/lib/firefox.js.map +1 -0
package/dist/lib/frame.d.ts +57 -0
package/dist/lib/frame.d.ts.map +1 -0
package/dist/lib/frame.js +277 -0
package/dist/lib/frame.js.map +1 -0
package/dist/lib/keyboard.d.ts +1 -1
package/dist/lib/keyboard.d.ts.map +1 -1
package/dist/lib/keyboard.js +1 -1
package/dist/lib/keyboard.js.map +1 -1
package/dist/lib/locator.d.ts +71 -2
package/dist/lib/locator.d.ts.map +1 -1
package/dist/lib/locator.js +289 -31
package/dist/lib/locator.js.map +1 -1
package/dist/lib/mouse.d.ts +1 -1
package/dist/lib/mouse.d.ts.map +1 -1
package/dist/lib/mouse.js +1 -1
package/dist/lib/mouse.js.map +1 -1
package/dist/lib/page.d.ts +107 -0
package/dist/lib/page.d.ts.map +1 -0
package/dist/lib/page.js +388 -0
package/dist/lib/page.js.map +1 -0
package/dist/lib/tracing.d.ts +128 -0
package/dist/lib/tracing.d.ts.map +1 -0
package/dist/lib/tracing.js +272 -0
package/dist/lib/tracing.js.map +1 -0
package/dist/lib/wait.d.ts.map +1 -1
package/dist/lib/wait.js +14 -1
package/dist/lib/wait.js.map +1 -1
package/dist/lib/webelement.d.ts +2 -0
package/dist/lib/webelement.d.ts.map +1 -1
package/dist/lib/webelement.js +18 -0
package/dist/lib/webelement.js.map +1 -1
package/docs/accessibility.md +177 -0
package/docs/api-reference.md +71 -0
package/docs/assertions.md +182 -0
package/docs/bidi-features.md +462 -0
package/docs/browser-api.md +673 -0
package/docs/browser-context.md +522 -0
package/docs/cli.md +233 -0
package/docs/clock.md +245 -0
package/docs/dialogs.md +143 -0
package/docs/driver-configuration.md +64 -0
package/docs/element-api.md +219 -0
package/docs/emulation.md +155 -0
package/docs/error-codes.md +67 -0
package/docs/getting-started.md +168 -0
package/docs/keyboard-mouse.md +250 -0
package/docs/mcp.md +250 -0
package/docs/mobile-emulation.md +194 -0
package/docs/screenshots.md +146 -0
package/docs/selectors.md +382 -0
package/docs/session-management.md +229 -0
package/docs/tracing.md +282 -0
package/package.json +25 -5
package/skills/craftdriver/SKILL.md +84 -0
package/skills/craftdriver/cheatsheet.md +194 -0
package/skills/craftdriver/cli.md +104 -0
package/skills/craftdriver/patterns.md +139 -0

package/docs/browser-api.md ADDED Viewed

@@ -0,0 +1,673 @@
+# Browser API
+The `Browser` class is the main entry point for browser automation.
+> **Heads-up.** `browser.click()`, `browser.find()`, `browser.evaluate()`
+> and the other DOM-touching shortcuts target the focused page in
+> `browser.defaultContext` — i.e. `(await browser.activePage()).X(...)`.
+> They never reach into pages inside a context created by
+> `browser.newContext()`. See
+> [Getting Started — `browser.X()` vs `page.X()`](./getting-started.md#browserx-vs-pagex--when-to-use-which).
+## Launching
+```typescript
+import { Browser } from 'craftdriver';
+const browser = await Browser.launch({ browserName: 'chrome' });
+// With pre-loaded session state
+const browser = await Browser.launch({
+  browserName: 'chrome',
+  storageState: './auth.json',
+});
+```
+### Launch options
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `browserName` | `'chrome' \| 'chromium' \| 'firefox'` | `'chrome'` | Browser to launch |
+| `enableBiDi` | `boolean` | `true` | Use WebDriver BiDi. Set `false` only when running against a browser that does not support it. |
+| `storageState` | `string` | — | Path to a session-state JSON file to load on startup |
+| `mobileEmulation` | `MobileEmulation \| DeviceName` | — | Mobile device emulation settings (Chrome/Chromium only) |
+| `downloadsDir` | `string` | temp dir | Directory where downloaded files are saved |
+## Navigation
+```typescript
+// Navigate to URL — waits for the page load event (default)
+await browser.navigateTo('https://example.com');
+// Wait only until DOMContentLoaded (faster — skips images/fonts)
+await browser.navigateTo('https://example.com', { waitUntil: 'domcontentloaded' });
+// Wait until no requests are in-flight for 500 ms after load
+await browser.navigateTo('https://example.com', { waitUntil: 'networkidle' });
+// Fire-and-forget — does not wait for any load event
+await browser.navigateTo('https://example.com', { waitUntil: 'none' });
+// Get current URL
+const url = await browser.url();
+// Get page title
+const title = await browser.title();
+```
+### `waitForLoadState(state?, opts?)`
+Wait for the page to reach a given load state after an action that triggers navigation
+(e.g. clicking a link or submitting a form).
+```typescript
+// After an action that causes navigation:
+await browser.click('#submit');
+await browser.waitForLoadState();              // default: 'load'
+await browser.waitForLoadState('domcontentloaded');
+await browser.waitForLoadState('networkidle', { timeout: 10_000 });
+```
+| State | Description |
+|-------|-------------|
+| `'load'` | Page `load` event fired (default) |
+| `'domcontentloaded'` | `DOMContentLoaded` fired — no waiting for images/fonts |
+| `'networkidle'` | `load` + no in-flight requests for 500 ms |
+Uses BiDi `browsingContext.load` / `browsingContext.domContentLoaded` events.
+### History
+```typescript
+await browser.goBack();      // history back
+await browser.goForward();   // history forward
+await browser.reload();      // reload the active page
+```
+All three proxy to the active page (`browser.activePage()`); use
+`page.goBack()` / `page.goForward()` / `page.reload()` directly when
+working with a specific tab.
+### Page content
+```typescript
+// Full document HTML (document.documentElement.outerHTML)
+const html = await browser.content();
+// Replace the document with synthetic HTML and wait for the load event
+await browser.setContent('<!doctype html><h1>Hello</h1>');
+// Faster — wait only for DOMContentLoaded
+await browser.setContent(html, { waitUntil: 'domcontentloaded' });
+```
+Implementation: `setContent` navigates to a `data:text/html` URL so the
+new document goes through a real navigation and load events fire.
+### Viewport
+```typescript
+await browser.setViewportSize({ width: 1280, height: 720 });
+```
+Uses BiDi `browsingContext.setViewport` to resize the **layout** viewport
+without changing the OS window. In Classic mode it falls back to
+`POST /session/{id}/window/rect`, which resizes the OS window — the
+inner viewport may end up a few pixels smaller because of browser
+chrome.
+For full mobile emulation (DPR, user-agent, touch), pass
+`mobileEmulation` to `Browser.launch` — see
+[Mobile emulation](./mobile-emulation.md). `setViewportSize` only
+changes the viewport box.
+### Emulation
+`browser.emulate({...})` overrides `prefers-color-scheme`,
+`prefers-reduced-motion`, `forced-colors`, `navigator.language`,
+`Intl.*` timezone, and `navigator.onLine` for the current session.
+```typescript
+await browser.emulate({
+  colorScheme: 'dark',
+  locale: 'de-DE',
+  timezoneId: 'Europe/Berlin',
+});
+```
+`locale` and `timezoneId` work on Chrome, Chromium and Firefox.
+The CSS-media-feature fields and `offline` are Chromium-only — see
+[Emulation](./emulation.md) for the full option table and use cases.
+## Element Interaction
+String selectors are CSS selectors. For semantic selectors, pass a `By.*`
+locator or use `browser.getByRole()`, `browser.getByText()`,
+`browser.getByLabel()`, and related helpers.
+```typescript
+// Click an element
+await browser.click('#submit-btn');
+await browser.click(By.text('Submit'));
+// Fill text input
+await browser.fill('#username', 'testuser');
+// Clear input
+await browser.clear('#search');
+```
+### `getValue(selector, opts?)`
+Return the live `value` property of an `<input>`, `<textarea>`, or
+`<select>`. Use this rather than `getAttribute('value')` — the
+attribute reflects the *initial* value, the property reflects what the
+user has typed.
+```typescript
+const typed = await browser.getValue('#input');
+const withTimeout = await browser.getValue('#input', { timeout: 1000 });
+```
+Returns `string` (empty string if the property is null/undefined).
+### `getAttribute(selector, name, opts?)`
+Return the value of an HTML attribute, or `null` if the attribute is
+not set. Pass a `By` locator or CSS string.
+```typescript
+const href = await browser.getAttribute('a.link', 'href');
+const role = await browser.getAttribute(By.testId('menu'), 'role');
+```
+## Finding Elements
+```typescript
+// Returns an ElementHandle for chained operations
+const element = browser.find('#my-element');
+// With By locators
+const button = browser.find(By.text('Click me'));
+const input = browser.find(By.placeholder('Enter email'));
+```
+## Playwright-style Locators
+```typescript
+// By role
+browser.getByRole('button', { name: 'Submit' });
+// By visible text
+browser.getByText('Hello World');
+browser.getByText('partial', { exact: false });
+// By label
+browser.getByLabel('Username');
+// By placeholder
+browser.getByPlaceholder('Enter email');
+// By test ID
+browser.getByTestId('submit-btn');
+```
+## Waiting
+> **`attached` vs `visible`.** *Attached* means the element exists in
+> the DOM — it may still be `display: none` or have zero size.
+> *Visible* is stricter: attached **and** laid out with non-zero size
+> and not `visibility: hidden`. *Hidden* and *detached* are the
+> respective negatives. The default for `waitFor` is `'visible'`,
+> which matches what users mean 95 % of the time.
+```typescript
+// Canonical: pick the state explicitly.
+await browser.waitFor('#modal',   { state: 'visible' });
+await browser.waitFor('#loading', { state: 'hidden', timeout: 5000 });
+await browser.waitFor('#dynamic', { state: 'attached' });
+await browser.waitFor('#removed', { state: 'detached' });
+// Shortcuts (one-liner wrappers):
+await browser.waitForVisible('#modal');
+await browser.waitForHidden('#loading');
+await browser.waitForAttached('#dynamic-content');
+await browser.waitForDetached('#removed-element');
+// Pause for fixed time
+await browser.pause(1000); // 1 second
+// Wait for custom condition
+await browser.waitFor(async () => {
+  const count = await browser.find('#items').text();
+  return parseInt(count) > 5;
+});
+```
+## Assertions
+```typescript
+// Assert text content
+await browser.expect('#message').toHaveText('Success');
+await browser.expect('#message').toContainText('Success');
+// Assert visibility
+await browser.expect('#modal').toBeVisible();
+await browser.expect('#modal').not.toBeVisible();
+// Assert attribute
+await browser.expect('a').toHaveAttribute('href', '/home');
+// Assert value
+await browser.expect('#input').toHaveValue('test');
+```
+## Frames and Contexts
+### Iframes
+```typescript
+import { Browser } from 'craftdriver';
+const browser = await Browser.launch();
+await browser.navigateTo('https://example.com/page-with-iframe');
+// Obtain a Frame scoped to the first matching iframe
+const frame = await browser.frame('#stripe-card-frame');
+// All element methods are scoped to the iframe
+await frame.fill('#card-number', '4242 4242 4242 4242');
+await frame.click('#pay-btn');
+await frame.expect('#result').toContainText('success');
+// Evaluate JavaScript inside the iframe
+const iframeTitle = await frame.evaluate(() => document.title);
+// Get all iframes on the page
+const frames = await browser.frames();
+console.log(`Page has ${frames.length} iframe(s)`);
+```
+### Pages (tabs and popups)
+A `Page` is a top-level browsing context — a tab or a popup window. Maps
+1-to-1 onto the WebDriver BiDi `browsingContext` concept (the BiDi spec
+calls them "top-level browsing contexts"; we call them pages because that
+is what users mean).
+```typescript
+import { Browser } from 'craftdriver';
+const browser = await Browser.launch();
+await browser.navigateTo('https://example.com/dashboard');
+// List all open pages (tabs / windows)
+const pages = await browser.pages();
+console.log(`Open tabs: ${pages.length}`);
+// Open a new tab proactively (BiDi-only)
+const newTab = await browser.openPage({
+  url: 'https://example.com/help',
+  type: 'tab',
+});
+await newTab.waitForLoadState('load');
+// Capture a popup opened by a user action
+const popup = await browser.waitForPage(async () => {
+  await browser.click('#open-in-new-tab');
+});
+await popup.waitForLoadState('load');
+// Interact with the popup just like the main browser
+const heading = await popup.find('h1').text();
+console.log(heading);
+await popup.evaluate(() => {
+  window.close();
+});
+```
+> **Note.** `browser.openPage()` requires BiDi (the default). In Classic
+> mode it throws — WebDriver Classic has no spec-level command for
+> creating a top-level browsing context.
+>
+> For **isolated profiles** (cookies, localStorage, IndexedDB scoped to
+> a single test user), see [Browser Contexts](./browser-context.md) —
+> `browser.newContext()` returns a real `BrowserContext` backed by BiDi
+> user contexts.
+## Screenshots
+```typescript
+// Capture viewport (default)
+const buffer = await browser.screenshot();
+// Capture the full scrollable document (BiDi)
+const fullBuffer = await browser.screenshot({ fullPage: true });
+// Capture specific element
+const elementBuffer = await browser.screenshot({ selector: '#header' });
+// Save to file
+await browser.screenshot({ path: 'page.png' });
+await browser.screenshot({ selector: '#header', path: 'element.png' });
+```
+## Session Management
+See [Session Management](./session-management.md) for full details.
+```typescript
+// Access storage manager
+const storage = browser.storage;
+// Save current session to file
+await browser.saveState('./session.json');
+// Load session from file
+await browser.loadState('./session.json');
+```
+## Evaluate
+Run JavaScript in the page and get the result back. Useful for reading app state,
+asserting on globals, or triggering things the UI doesn't expose.
+```typescript
+// Function form — arguments are passed through
+const title = await browser.evaluate(() => document.title);
+const sum   = await browser.evaluate((a, b) => a + b, 2, 3); // 5
+// String form — write it like a function body
+const href = await browser.evaluate('return location.href');
+// On a specific element — receives the DOM node as the first argument
+const tag  = await browser.find('#btn').evaluate(el => el.tagName.toLowerCase());
+const has  = await browser.find('#btn').evaluate((el, cls) => el.classList.contains(cls), 'active');
+```
+Only JSON-serializable return values are supported. Returning a DOM node or function
+throws a clear error.
+## Init scripts
+Register a script that runs before any page script on every navigation:
+```typescript
+// Function form
+const handle = await browser.addInitScript(() => {
+  window.__featureFlags = { darkMode: true };
+});
+// Or a script string
+await browser.addInitScript(`window.__featureFlags = { darkMode: true };`);
+// The script survives navigations automatically
+await browser.navigateTo(url);
+const flag = await browser.evaluate(() => window.__featureFlags.darkMode); // true
+// Unregister when no longer needed
+await handle.remove();
+await browser.navigateTo(url);
+// window.__featureFlags is now undefined
+```
+> Init scripts are scoped to the current browser session and survive navigations automatically.
+## Files (upload & download)
+### Upload
+Set the value of an `<input type="file">` element:
+```typescript
+const handle = browser.find('#file-input');
+await handle.setInputFiles('/absolute/path/to/file.pdf');
+// Multiple files (input must have the `multiple` attribute)
+await handle.setInputFiles(['/path/to/a.pdf', '/path/to/b.pdf']);
+```
+Throws a clear error if the element is not an `<input type="file">`.
+### Download
+Pass a callback that triggers the download; `waitForDownload` resolves once
+a file appears in the downloads directory:
+```typescript
+const dl = await browser.waitForDownload(() => browser.click('#export-btn'));
+console.log(dl.suggestedFilename); // 'report.csv'
+console.log(dl.path);              // absolute path on disk
+// Copy to a known location
+await dl.saveAs('/tmp/report.csv');
+```
+Configure the directory at launch (defaults to an isolated temp directory):
+```typescript
+const browser = await Browser.launch({
+  downloadsDir: '/tmp/my-test-downloads',
+});
+```
+## Time Control
+Control the clock the page sees — `Date.now()`, `new Date()`,
+`performance.now()`, `setTimeout`, and `setInterval`.
+See [Virtual Clock](./clock.md) for the full guide and method reference.
+```typescript
+// Freeze date for date-dependent rendering (no fake timers)
+await browser.clock.setFixedTime('2026-06-15T23:59:00Z');
+await browser.navigateTo('/billing');
+await browser.expect('#trial-banner').toContainText('expires today');
+// Full fake-timer installation — control every setTimeout/setInterval
+await browser.clock.install({ time: '2026-01-01T09:00:00Z' });
+await browser.navigateTo('/dashboard');
+await browser.clock.fastForward('15:01'); // advance 15 min 1 s
+await browser.expect('#login-modal').toBeVisible();
+// Debounced input: advance exactly to the threshold
+await browser.clock.install();
+await browser.fill('#q', 'lap');
+await browser.clock.tick(299); // debounce hasn't fired yet
+await browser.clock.tick(2);   // total 301 ms — fires exactly once
+```
+## Dialogs (alert / confirm / prompt)
+> **Heads-up.** craftdriver makes unhandled dialogs **loud failures**
+> rather than silently auto-dismissing them like Playwright does. The
+> action that triggered the dialog will time out until something
+> handles it. See [Dialogs](./dialogs.md) for the dedicated guide,
+> including `waitForDialog()`, `onDialog()`, and the imperative
+> `acceptDialog()` / `dismissDialog()` API.
+Quick example:
+```typescript
+const [, dialog] = await Promise.all([
+  browser.click('#confirm-btn'),
+  browser.waitForDialog(),
+]);
+await dialog.accept();
+```
+## Cleanup
+```typescript
+// Always quit the browser when done
+await browser.quit();
+```
+`quit()` closes the browser session and stops the WebDriver process. Use
+it in a `finally` block (or your test runner's teardown hook) so it
+runs even when the test throws:
+```typescript
+const browser = await Browser.launch({ browserName: 'chrome' });
+try {
+  // … your test …
+} finally {
+  await browser.quit().catch(() => {
+    // The session may already be gone (browser crash, killed driver,
+    // network blip). Swallow — there is nothing useful left to clean
+    // up from the client side.
+  });
+}
+```
+### When `quit()` is not enough
+`quit()` makes a best-effort `DELETE /session` call to the driver and
+then kills the local driver process craftdriver spawned. It does **not**
+cover:
+- **The host process is killed** (`kill -9`, OS reboot, CI runner
+  cancellation). The driver and browser may linger as orphan processes.
+  Clean them up at the OS level (CI runners typically do this
+  automatically; on a dev machine `pkill chromedriver` /
+  `pkill geckodriver` is the easy fix).
+- **Custom `ChromeService` / `FirefoxService` you own.** If you passed
+  one via `chromeService` / `firefoxService` and want to keep it for a
+  second `Browser.launch()` call, manage its lifetime yourself —
+  craftdriver only stops services it spawned.
+- **Multiple browsers in one test.** Each instance must be quit
+  independently; there is no global registry.
+## Advanced
+### `isBiDiEnabled()`
+Returns `true` if BiDi negotiation succeeded at launch. Use this to
+guard code paths that depend on BiDi-only features (network mocking,
+log capture, init scripts) when the same code may run against a
+browser launched with `enableBiDi: false`.
+```typescript
+if (browser.isBiDiEnabled()) {
+  await browser.network.block('**/analytics/**');
+}
+```
+### `actions()`
+Returns a low-level W3C Actions builder for input sequences the
+high-level `browser.keyboard` / `browser.mouse` APIs do not cover —
+e.g. drag-and-drop with a held modifier, multi-pointer gestures, or
+custom timing.
+The builder is fluent and **all steps in a single chain are dispatched
+in one HTTP `POST /session/{id}/actions` call**, so they execute as one
+sequence on the browser side.
+#### Example: shift-drag a marquee selection
+The example page at `examples/mouse.html` includes an SVG canvas at
+fixed coordinates. The snippet below holds **Shift**, drags from
+`(100, 100)` to `(300, 300)`, then releases — modelling a "Shift-drag
+to add to selection" interaction:
+```typescript
+import { Browser, Key } from 'craftdriver';
+const browser = await Browser.launch();
+await browser.navigateTo('http://127.0.0.1:8080/mouse.html');
+await browser
+  .actions()
+  .keyDown(Key.SHIFT)               // hold Shift
+  .pointerMove(100, 100)            // jump cursor to start
+  .pointerDown()                    // press primary button
+  .pointerMove(300, 300, { duration: 250 })  // drag over 250 ms
+  .pointerUp()                      // release
+  .keyUp(Key.SHIFT)                 // release Shift
+  .perform();
+await browser.quit();
+```
+Available steps: `keyDown(value)`, `keyUp(value)`, `pointerMove(x, y, opts?)`,
+`pointerDown(button?)`, `pointerUp(button?)`, `pause(ms?)`,
+`wheel(deltaX, deltaY, opts?)`, then `await .perform()`.
+For routine clicks and typing prefer `browser.keyboard`,
+`browser.mouse`, and `browser.click()` — they auto-wait for the target
+and report failures clearly. Reach for `actions()` only when you need
+byte-for-byte control of the input sequence.
+## Configuring timeouts
+All element actions, waits, and assertions use a browser-level default timeout
+of **5000 ms**. You can change this globally or override it per call.
+### Default timeouts
+| Setting | Default | Applies to |
+|---|---|---|
+| `setDefaultTimeout(ms)` | **5 000 ms** | Element actions (`click`, `fill`, `clear`, `getValue`, `getAttribute`, …), `waitFor*`, assertions, dialog waits, locator/handle methods. |
+| `setDefaultNavigationTimeout(ms)` | **30 000 ms** | `navigateTo()` and `waitForLoadState()`. |
+Every method that accepts a `{ timeout }` option overrides the
+appropriate default for that single call. The change made by
+`setDefaultTimeout()` is live — it applies to `ElementHandle` and
+`Locator` objects that already exist.
+### Global defaults
+```typescript
+// Change the default for all actions/waits/assertions on this browser instance
+browser.setDefaultTimeout(10000); // 10 s
+// Change the default for navigation (used by navigateTo in future BiDi mode)
+browser.setDefaultNavigationTimeout(30000); // 30 s (this is already the default)
+```
+### Per-call override
+Every method that interacts with the DOM accepts an optional `{ timeout }` option
+that overrides the browser default for that single call:
+```typescript
+// One-shot override — only this click uses 2 s
+await browser.click('#slow-button', { timeout: 2000 });
+// Works on fill, clear, getValue, getAttribute, waitFor* too
+await browser.fill('#input', 'text', { timeout: 3000 });
+await browser.waitForVisible('#modal', { timeout: 8000 });
+// Works on ElementHandle methods
+await browser.find('#result').text({ timeout: 1000 });
+await browser.find('#submit').click({ timeout: 2000 });
+// Works on assertions
+await browser.expect('#message').toBeVisible({ timeout: 3000 });
+await browser.expect('#data').toHaveText('Loaded', { timeout: 10000 });
+```
+### Live updates
+`setDefaultTimeout()` takes effect immediately, including for `ElementHandle`
+and locator objects that were already created:
+```typescript
+const button = browser.find('#submit');
+browser.setDefaultTimeout(2000); // change after creating handle
+await button.click(); // uses 2000 ms, not 5000 ms
+```
+## Properties
+| Property   | Type                  | Description                    |
+| ---------- | --------------------- | ------------------------------ |
+| `keyboard` | `Keyboard`            | Low-level keyboard control     |
+| `mouse`    | `Mouse`               | Low-level mouse control        |
+| `storage`  | `SessionStateManager` | Cookie and storage management  |
+| `network`  | `NetworkInterceptor`  | Network mocking (BiDi only)    |
+| `logs`     | `LogMonitor`          | Console/error logs (BiDi only) |