craftdriver 1.0.3 → 1.1.0

package/docs/agents.md

@@ -0,0 +1,92 @@
+# AI Agent Guide
+
+CraftDriver ships agent-facing tooling in the npm package. You can use the library directly, drive the browser from the shell, expose tools through MCP, or drop assistant rules into a project.
+
+## Which Surface Should I Use?
+
+| Agent environment          | Best surface       | Why                                                                              |
+| -------------------------- | ------------------ | -------------------------------------------------------------------------------- |
+| Shell-capable coding agent | CLI                | Simple commands, persistent daemon, JSON output when piped.                      |
+| MCP-aware host             | MCP server         | Typed tools, compact accessibility snapshots, artifact spilling for screenshots. |
+| Code-writing assistant     | `craftdriver init` | Project rules teach selector preference, auto-waiting, and error-code handling.  |
+| Custom orchestrator        | Skill pack         | Small always-on `SKILL.md` with deeper references loaded on demand.              |
+
+## CLI
+
+The CLI is good for agents that can run shell commands.
+
+```bash
+npx craftdriver daemon start
+npx craftdriver go http://127.0.0.1:8080/login.html
+npx craftdriver snapshot
+npx craftdriver fill 'label=Username' alice
+npx craftdriver fill 'label=Password' hunter2
+npx craftdriver click 'role=button[name=Sign in]'
+npx craftdriver text '#result'
+npx craftdriver daemon stop
+```
+
+State survives between calls while the daemon is running, so an agent can explore, act, inspect, and refine.
+
+Read the full [CLI reference](./cli.md).
+
+## MCP Server
+
+MCP-aware hosts can use `craftdriver mcp`.
+
+```bash
+claude mcp add craftdriver -- npx -y craftdriver mcp
+```
+
+```jsonc
+{
+  "mcpServers": {
+    "craftdriver": {
+      "command": "npx",
+      "args": ["-y", "craftdriver", "mcp"],
+    },
+  },
+}
+```
+
+Mutating tools return compact accessibility snapshot diffs, so the agent can see what changed without a separate read. Large artifacts such as screenshots are written to disk instead of inlined into model context.
+
+Read the full [MCP reference](./mcp.md).
+
+## Assistant Bootstrap Files
+
+Use `craftdriver init` inside a project that uses CraftDriver:
+
+```bash
+npx craftdriver init agents
+npx craftdriver init copilot
+npx craftdriver init claude
+npx craftdriver init cursor
+npx craftdriver init gemini
+npx craftdriver init all
+```
+
+The generated files tell assistants to:
+
+- prefer semantic selectors before brittle CSS
+- rely on auto-waiting instead of sleeps
+- inspect stable `CraftdriverError.code` values
+- use the CLI or MCP server for live browser work
+- keep test code aligned with the public TypeScript API
+
+## Skill Pack
+
+The npm tarball includes a tiered skill pack under `skills/craftdriver/`:
+
+| File            | Purpose                                                                                |
+| --------------- | -------------------------------------------------------------------------------------- |
+| `SKILL.md`      | Always-on rules and routing, kept small for model context.                             |
+| `cheatsheet.md` | Fast command and API reference for tests.                                              |
+| `patterns.md`   | Worked recipes such as login, uploads, network waits, a11y, tracing, and virtual time. |
+| `cli.md`        | Agent-facing CLI reference.                                                            |
+
+Point compatible agents at:
+
+```text
+node_modules/craftdriver/skills/craftdriver/SKILL.md
+```

package/docs/api-reference.md

@@ -1,71 +1,133 @@
 # API reference
 
-Every symbol re-exported from [`src/index.ts`](../src/index.ts). One row per export.
+Every symbol re-exported from [`src/index.ts`](../src/index.ts), grouped by the feature area most users look for first.
 Generated by `scripts/gen-api-reference.mjs` — do not edit by hand.
 
 Run `npm run docs:api` to regenerate. CI fails when this file is out of date.
 
+Start with [`Browser`](./browser-api.md), [`By`](./selectors.md) / [`Locator`](./selectors.md), and the feature guide that matches the job you are automating.
+
+## Browser And Pages
+
+Launch browsers, move between pages and frames, handle dialogs, and wait for navigation.
+
 | Symbol | Kind | Summary | Docs |
 |---|---|---|---|
-| `A11y` | class | Ergonomic wrapper around axe-core. Obtain instances via the `.a11y` accessor on `Browser`, `ElementHandle`, or `Locator` — never construct directly. | [accessibility](accessibility.md) |
-| `A11yError` | class | Thrown by `A11y.check()` when violations are found. | [accessibility](accessibility.md) |
-| `A11yImpact` | type | Severity buckets reported by axe-core. | [accessibility](accessibility.md) |
-| `A11yOptions` | type | — | [accessibility](accessibility.md) |
-| `A11yResult` | type | — | [accessibility](accessibility.md) |
-| `A11yViolation` | type | — | [accessibility](accessibility.md) |
-| `A11yViolationNode` | type | — | [accessibility](accessibility.md) |
 | `Browser` | class | — | [browser-api](browser-api.md) |
+| `LaunchOptions` | type | — | [browser-api](browser-api.md) |
+| `LoadState` | type | When to consider a navigation complete. - `'load'` — page `load` event has fired (default) - `'domcontentloaded'` — `DOMContentLoaded` has fired (faster, no waiting for images/fonts) - `'networkidle'` — `load` + no in-flight requests for 500 ms - `'none'` — do not wait; return as soon as the navigation is initiated | [browser-api](browser-api.md) |
+| `Page` | class | — | [browser-api](browser-api.md) |
+| `Frame` | class | — | [browser-api](browser-api.md) |
+| `Dialog` | type | Represents an open browser dialog (alert / confirm / prompt). Passed to handlers registered with `browser.onDialog()`. | [browser-api](browser-api.md) |
+| `DialogType` | type | The type of a browser dialog. | [browser-api](browser-api.md) |
+| `Download` | type | A file downloaded during a `waitForDownload()` call. | [browser-api](browser-api.md) |
+
+## Locators And Elements
+
+Find page content with semantic locators and selector helpers.
+
+| Symbol | Kind | Summary | Docs |
+|---|---|---|---|
+| `By` | class | — | [selectors](selectors.md) |
+| `Locator` | class | — | [selectors](selectors.md) |
+
+## Input
+
+Drive keyboard, mouse, and low-level key values.
+
+| Symbol | Kind | Summary | Docs |
+|---|---|---|---|
+| `Key` | const | — | [keyboard-mouse](keyboard-mouse.md) |
+| `Keyboard` | class | — | [keyboard-mouse](keyboard-mouse.md) |
+| `Mouse` | class | — | [keyboard-mouse](keyboard-mouse.md) |
+
+## Contexts And Sessions
+
+Isolate users, manage cookies, and save or restore browser state.
+
+| Symbol | Kind | Summary | Docs |
+|---|---|---|---|
 | `BrowserContext` | class | — | [browser-context](browser-context.md) |
 | `BrowserContextConfig` | type | Per-context options stored at creation time. | [browser-context](browser-context.md) |
 | `BrowserContextHooks` | type | Internal hooks the owning {@link Browser } passes to a new context. | [browser-context](browser-context.md) |
-| `By` | class | — | [selectors](selectors.md) |
-| `ChromeService` | class | — | [getting-started](getting-started.md) |
-| `ChromeServiceOptions` | type | — | [getting-started](getting-started.md) |
 | `ClearCookiesFilter` | type | Filter applied to {@link BrowserContext.clearCookies}. | [browser-context](browser-context.md) |
+| `ContextStorageStateOptions` | type | Options for {@link BrowserContext.storageState}. | [browser-context](browser-context.md) |
+| `InitScriptHandle` | type | A handle returned by {@link BrowserContext.addInitScript}. | [browser-context](browser-context.md) |
+| `RoutePattern` | type | Pattern accepted by {@link BrowserContext.route}. Same shape as the browser-level interceptor. | [browser-context](browser-context.md) |
+| `Cookie` | type | — | [session-management](session-management.md) |
+| `CookieInput` | type | — | [session-management](session-management.md) |
+| `SessionState` | type | — | [session-management](session-management.md) |
+| `SessionStateManager` | class | — | [session-management](session-management.md) |
+| `StorageStateOptions` | type | — | [session-management](session-management.md) |
+
+## Network
+
+Mock, intercept, observe, and assert browser network traffic.
+
+| Symbol | Kind | Summary | Docs |
+|---|---|---|---|
+| `NetworkInterceptor` | class | — | [network](network.md) |
+| `MockResponse` | type | — | [network](network.md) |
+| `InterceptedRequest` | type | — | [network](network.md) |
+| `InterceptedResponse` | type | — | [network](network.md) |
+
+## Logs And Tracing
+
+Capture console output, JavaScript errors, and trace artifacts.
+
+| Symbol | Kind | Summary | Docs |
+|---|---|---|---|
+| `LogMonitor` | class | — | [browser-logs](browser-logs.md) |
+| `ConsoleMessage` | type | — | [browser-logs](browser-logs.md) |
+| `JavaScriptError` | type | — | [browser-logs](browser-logs.md) |
+| `LogMessage` | type | — | [browser-logs](browser-logs.md) |
+| `TraceStartOptions` | type | — | [tracing](tracing.md) |
+| `TraceScreenshotMode` | type | Screenshot mode for tracing. | [tracing](tracing.md) |
+| `TraceEvent` | type | — | [tracing](tracing.md) |
+
+## Emulation And Time
+
+Configure devices, emulation overrides, and deterministic browser time.
+
+| Symbol | Kind | Summary | Docs |
+|---|---|---|---|
+| `devices` | const | Common mobile device presets | [browser-api](browser-api.md) |
+| `DeviceMetrics` | type | Device metrics for custom mobile emulation | [browser-api](browser-api.md) |
+| `DeviceName` | type | — | [browser-api](browser-api.md) |
+| `MobileEmulation` | type | Mobile emulation configuration | [browser-api](browser-api.md) |
+| `EmulateOptions` | type | Options for {@link Browser.emulate}. Every field is independent; only the keys you pass are applied, others stay at their previous value. Passing `null` for a field clears the override for that field. | [browser-api](browser-api.md) |
 | `Clock` | class | Controls the virtual clock inside the browser page. | [clock](clock.md) |
 | `ClockInstallOptions` | type | Options for {@link Clock.install}. | [clock](clock.md) |
 | `ClockTime` | type | Accepted forms for a point in time. | [clock](clock.md) |
-| `ConsoleMessage` | type | — | [bidi-features](bidi-features.md) |
-| `ContextStorageStateOptions` | type | Options for {@link BrowserContext.storageState}. | [browser-context](browser-context.md) |
-| `Cookie` | type | — | [bidi-features](bidi-features.md) |
-| `CookieInput` | type | — | [bidi-features](bidi-features.md) |
+
+## Accessibility
+
+Run axe-core accessibility checks and inspect violation details.
+
+| Symbol | Kind | Summary | Docs |
+|---|---|---|---|
+| `A11y` | class | Ergonomic wrapper around axe-core. Obtain instances via the `.a11y` accessor on `Browser`, `ElementHandle`, or `Locator` — never construct directly. | [accessibility](accessibility.md) |
+| `A11yError` | class | Thrown by `A11y.check()` when violations are found. | [accessibility](accessibility.md) |
+| `A11yImpact` | type | Severity buckets reported by axe-core. | [accessibility](accessibility.md) |
+| `A11yOptions` | type | — | [accessibility](accessibility.md) |
+| `A11yResult` | type | — | [accessibility](accessibility.md) |
+| `A11yViolation` | type | — | [accessibility](accessibility.md) |
+| `A11yViolationNode` | type | — | [accessibility](accessibility.md) |
+
+## Errors And Driver Services
+
+Handle stable CraftDriver errors or customize browser driver services.
+
+| Symbol | Kind | Summary | Docs |
+|---|---|---|---|
 | `CraftdriverError` | class | Base class for every error thrown from the public API. | [error-codes](error-codes.md) |
 | `CraftdriverErrorOptions` | type | — | [error-codes](error-codes.md) |
-| `DeviceMetrics` | type | Device metrics for custom mobile emulation | [browser-api](browser-api.md) |
-| `DeviceName` | type | — | [browser-api](browser-api.md) |
-| `devices` | const | Common mobile device presets | [browser-api](browser-api.md) |
-| `Dialog` | type | Represents an open browser dialog (alert / confirm / prompt). Passed to handlers registered with `browser.onDialog()`. | [browser-api](browser-api.md) |
-| `DialogType` | type | The type of a browser dialog. | [browser-api](browser-api.md) |
-| `Download` | type | A file downloaded during a `waitForDownload()` call. | [browser-api](browser-api.md) |
-| `EmulateOptions` | type | Options for {@link Browser.emulate}. Every field is independent; only the keys you pass are applied, others stay at their previous value. Passing `null` for a field clears the override for that field. | [browser-api](browser-api.md) |
 | `ErrorCode` | const | Stable, machine-readable error codes for the public craftdriver API. | [error-codes](error-codes.md) |
 | `ErrorCodeName` | type | — | [error-codes](error-codes.md) |
 | `ErrorCodeValue` | type | — | [error-codes](error-codes.md) |
+| `ChromeService` | class | — | [getting-started](getting-started.md) |
+| `ChromeServiceOptions` | type | — | [getting-started](getting-started.md) |
 | `FirefoxService` | class | — | [getting-started](getting-started.md) |
 | `FirefoxServiceOptions` | type | — | [getting-started](getting-started.md) |
-| `Frame` | class | — | [browser-api](browser-api.md) |
-| `InitScriptHandle` | type | A handle returned by {@link BrowserContext.addInitScript}. | [browser-context](browser-context.md) |
-| `InterceptedRequest` | type | — | [bidi-features](bidi-features.md) |
-| `InterceptedResponse` | type | — | [bidi-features](bidi-features.md) |
-| `JavaScriptError` | type | — | [bidi-features](bidi-features.md) |
-| `Key` | const | — | [keyboard-mouse](keyboard-mouse.md) |
-| `Keyboard` | class | — | [keyboard-mouse](keyboard-mouse.md) |
-| `LaunchOptions` | type | — | [browser-api](browser-api.md) |
-| `LoadState` | type | When to consider a navigation complete. - `'load'` — page `load` event has fired (default) - `'domcontentloaded'` — `DOMContentLoaded` has fired (faster, no waiting for images/fonts) - `'networkidle'` — `load` + no in-flight requests for 500 ms - `'none'` — do not wait; return as soon as the navigation is initiated | [browser-api](browser-api.md) |
-| `Locator` | class | — | [selectors](selectors.md) |
-| `LogMessage` | type | — | [bidi-features](bidi-features.md) |
-| `LogMonitor` | class | — | [bidi-features](bidi-features.md) |
-| `MobileEmulation` | type | Mobile emulation configuration | [browser-api](browser-api.md) |
-| `MockResponse` | type | — | [bidi-features](bidi-features.md) |
-| `Mouse` | class | — | [keyboard-mouse](keyboard-mouse.md) |
-| `NetworkInterceptor` | class | — | [bidi-features](bidi-features.md) |
-| `Page` | class | — | [browser-api](browser-api.md) |
-| `RoutePattern` | type | Pattern accepted by {@link BrowserContext.route}. Same shape as the browser-level interceptor. | [browser-context](browser-context.md) |
-| `SessionState` | type | — | [bidi-features](bidi-features.md) |
-| `SessionStateManager` | class | — | [bidi-features](bidi-features.md) |
-| `StorageStateOptions` | type | — | [bidi-features](bidi-features.md) |
-| `TraceEvent` | type | — | [tracing](tracing.md) |
-| `TraceScreenshotMode` | type | Screenshot mode for tracing. | [tracing](tracing.md) |
-| `TraceStartOptions` | type | — | [tracing](tracing.md) |
 
 Total exports: **60**.

package/docs/browser-api.md

@@ -29,10 +29,11 @@ const browser = await Browser.launch({
 |--------|------|---------|-------------|
 | `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 — every BiDi-only feature then throws a `requires BiDi` error if called. |
-| `captureLogs` | `boolean` | `false` | Start console/error log capture immediately at launch instead of lazily on first `browser.logs`/`onConsole`/`onError`/`waitForConsole` touch. See [BiDi Features — Console & Error Logs](./bidi-features.md#console--error-logs). |
+| `captureLogs` | `boolean` | `false` | Start console/error log capture immediately at launch instead of lazily on first `browser.logs`/`onConsole`/`onError`/`waitForConsole` touch. See [Console Logs And JavaScript Errors](./browser-logs.md). |
 | `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 |
+| `browserPath` | `string` | — | Custom browser binary to launch (Chrome/Chromium/Firefox) — see [Driver Configuration → Browser Binary Configuration](./driver-configuration.md#browser-binary-configuration) |
 
 ## Navigation
 

package/docs/browser-context.md

@@ -262,19 +262,16 @@ this context.
 the listener reference than the unsubscribe function.
 
 ```typescript
-// Real-world: capture every console error across every tab a test opens,
-// including popups. No more "why did my test pass with a 500 in a popup".
-const errors: string[] = [];
+const opened: string[] = [];
 ctx.on('page', (page) => {
-  page.on('console', (msg) => {
-    if (msg.type() === 'error') errors.push(`${page.url()}: ${msg.text()}`);
-  });
+  void page.url().then((url) => opened.push(url));
 });
 
 const main = await ctx.newPage({ url: '/checkout' });
 const receipt = await ctx.waitForPage(() => main.find('#print').click());
 await receipt.waitForLoadState('load');
-expect(errors).toEqual([]);
+
+expect(opened.some((url) => url.endsWith('/checkout'))).toBe(true);
 ```
 
 ### `BrowserContext.addInitScript(script): Promise<InitScriptHandle>`

package/docs/browser-logs.md

@@ -0,0 +1,158 @@
+# Console Logs And JavaScript Errors
+
+Use `browser.logs` to capture what the page writes to the console and what
+JavaScript errors the browser reports. This is useful for failing tests on
+unexpected client-side errors, debugging flaky flows, or asserting that an app
+emitted a known log message.
+
+> **Requires the default browser event connection.** Console and JavaScript
+> error capture requires `enableBiDi: true` (the default) and a browser that
+> supports WebDriver BiDi. If you launch with `enableBiDi: false`, these
+> methods throw a clear `requires BiDi` error.
+
+## Capture Timing
+
+Capture is lazy by default. CraftDriver subscribes to log events the first time
+you touch `browser.logs.onLog()`, `.onConsole()`, `.onError()`, `.on()`,
+`.waitForConsole()`, or `.waitForError()`.
+
+Messages emitted before that first touch are not captured, so this can return an
+empty array:
+
+```typescript
+await browser.navigateTo('https://example.com');
+const messages = browser.logs.getMessages();
+```
+
+Start capture before the action that logs:
+
+```typescript
+const warning = browser.logs.waitForConsole((msg) => msg.level === 'warn');
+
+await browser.getByRole('button', { name: 'Show warning' }).click();
+expect((await warning).text).toContain('Heads up');
+```
+
+Or start capture immediately at launch:
+
+```typescript
+const browser = await Browser.launch({
+  browserName: 'chrome',
+  captureLogs: true,
+});
+```
+
+## Read Collected Messages
+
+```typescript
+const messages = browser.logs.getMessages();
+
+for (const msg of messages) {
+  console.log(`[${msg.level}] ${msg.text}`);
+}
+```
+
+Each console message has:
+
+| Property | Description |
+| -------- | ----------- |
+| `type` | Always `'console'` |
+| `level` | `'debug'`, `'info'`, `'warn'`, or `'error'` |
+| `text` | Message text |
+| `method` | Console method, such as `'log'`, `'warn'`, or `'error'` |
+| `args` | Arguments passed to `console.*` |
+| `timestamp` | When the message was logged |
+| `stackTrace` | Optional stack frames |
+
+Filter by level:
+
+```typescript
+const warnings = browser.logs.getLogsByLevel('warn');
+const errors = browser.logs.getLogsByLevel('error');
+```
+
+## Read JavaScript Errors
+
+```typescript
+const errors = browser.logs.getErrors();
+
+for (const error of errors) {
+  console.log(`Error: ${error.text}`);
+}
+```
+
+Each JavaScript error has:
+
+| Property | Description |
+| -------- | ----------- |
+| `type` | Always `'javascript'` |
+| `level` | Always `'error'` |
+| `text` | Error message |
+| `timestamp` | When the error occurred |
+| `stackTrace` | Optional stack frames with function, URL, line, and column |
+
+## Wait For A Log Or Error
+
+```typescript
+const consoleMessage = browser.logs.waitForConsole((msg) => {
+  return msg.level === 'info' && msg.text.includes('Saved');
+});
+
+await browser.getByRole('button', { name: 'Save' }).click();
+expect((await consoleMessage).text).toContain('Saved');
+```
+
+```typescript
+const pageError = browser.logs.waitForError((error) => {
+  return error.text.includes('Cannot read properties');
+});
+
+await browser.getByRole('button', { name: 'Trigger error' }).click();
+expect((await pageError).text).toContain('Cannot read properties');
+```
+
+## Subscribe In Real Time
+
+```typescript
+const unsubscribeConsole = browser.logs.onConsole((msg) => {
+  if (msg.level === 'error') {
+    console.log('Console error:', msg.text);
+  }
+});
+
+const unsubscribeErrors = browser.logs.onError((error) => {
+  console.log('JavaScript error:', error.text);
+});
+
+// Later:
+unsubscribeConsole();
+unsubscribeErrors();
+```
+
+## Fail On Unexpected Errors
+
+```typescript
+await browser.navigateTo('https://example.com');
+await browser.getByRole('button', { name: 'Run flow' }).click();
+
+browser.logs.assertNoErrors();
+```
+
+You can also inspect errors yourself:
+
+```typescript
+const errors = browser.logs.getErrors();
+expect(errors).toHaveLength(0);
+```
+
+## Other Helpers
+
+| Method | Description |
+| ------ | ----------- |
+| `onLog(handler)` | Subscribe to all log messages |
+| `on(level, handler)` | Subscribe to one level: `debug`, `info`, `warn`, or `error` |
+| `getLogs()` | Return all captured console and JavaScript error messages |
+| `clearLogs()` | Clear all collected console messages and errors |
+| `waitForConsole(predicate, timeout?)` | Wait for a matching console message |
+| `waitForError(predicate?, timeout?)` | Wait for a JavaScript error |
+| `assertNoErrors()` | Throw if any JavaScript errors were captured |

package/docs/cli.md

@@ -83,21 +83,21 @@ Run `craftdriver --help` for the full list.
 
 CSS is the default. Switch kind with a `prefix=value` form:
 
-| Prefix          | Maps to                                  | Example                              |
-| --------------- | ---------------------------------------- | ------------------------------------ |
-| _none_, `css=`  | `By.css`                                 | `'.product-list li'`                 |
-| `xpath=`        | `By.xpath`                               | `'xpath=//button[1]'`                |
-| `role=`         | `By.role` (+ `[name=...]` for the name)  | `'role=button[name=Submit]'`         |
-| `text=`         | `By.text` (exact)                        | `'text=Sign In'`                     |
-| `text*=`        | `By.partialText`                         | `'text*=Sign'`                       |
-| `label=`        | `By.labelText`                           | `'label=Email'`                      |
-| `placeholder=`  | `By.placeholder`                         | `'placeholder=name@example.com'`     |
-| `alt=`          | `By.altText`                             | `'alt=Logo'`                         |
-| `title=`        | `By.title`                               | `'title=Help'`                       |
-| `testid=`       | `By.testId`                              | `'testid=login-btn'`                 |
-| `id=`           | `By.id`                                  | `'id=submit'`                        |
-| `name=`         | `By.name`                                | `'name=email'`                       |
-| `ref=`          | snapshot ref (`craftdriver snapshot`)    | `'ref=e5'`                           |
+| Prefix         | Maps to                                 | Example                          |
+| -------------- | --------------------------------------- | -------------------------------- |
+| _none_, `css=` | `By.css`                                | `'.product-list li'`             |
+| `xpath=`       | `By.xpath`                              | `'xpath=//button[1]'`            |
+| `role=`        | `By.role` (+ `[name=...]` for the name) | `'role=button[name=Submit]'`     |
+| `text=`        | `By.text` (exact)                       | `'text=Sign In'`                 |
+| `text*=`       | `By.partialText`                        | `'text*=Sign'`                   |
+| `label=`       | `By.labelText`                          | `'label=Email'`                  |
+| `placeholder=` | `By.placeholder`                        | `'placeholder=name@example.com'` |
+| `alt=`         | `By.altText`                            | `'alt=Logo'`                     |
+| `title=`       | `By.title`                              | `'title=Help'`                   |
+| `testid=`      | `By.testId`                             | `'testid=login-btn'`             |
+| `id=`          | `By.id`                                 | `'id=submit'`                    |
+| `name=`        | `By.name`                               | `'name=email'`                   |
+| `ref=`         | snapshot ref (`craftdriver snapshot`)   | `'ref=e5'`                       |
 
 Anything else is treated as a CSS selector, so attribute selectors with
 `=` inside (e.g. `'button[type=submit]'`) work as expected.
@@ -148,11 +148,11 @@ code:  NO_MATCH
 
 ## Exit codes
 
-| Code | Meaning                                                                 |
-| ---- | ----------------------------------------------------------------------- |
-| `0`  | success (or `exists` matched at least one element)                      |
-| `1`  | assertion / timeout / `NO_MATCH` / `exists` matched zero elements       |
-| `2`  | usage error (missing argument, unknown command)                         |
+| Code | Meaning                                                           |
+| ---- | ----------------------------------------------------------------- |
+| `0`  | success (or `exists` matched at least one element)                |
+| `1`  | assertion / timeout / `NO_MATCH` / `exists` matched zero elements |
+| `2`  | usage error (missing argument, unknown command)                   |
 
 ## Fail-fast defaults
 
@@ -221,12 +221,12 @@ For agents that load skills explicitly (Claude Code's Skills system,
 Copilot agent customization, custom orchestrators), the npm tarball
 ships a tiered skill pack under `skills/craftdriver/`:
 
-| File                                                          | Purpose                                                                  |
-| ------------------------------------------------------------- | ------------------------------------------------------------------------ |
-| [`SKILL.md`](../skills/craftdriver/SKILL.md)                  | Always-on, ≤ 500 tokens. Selector order, error-code-first, auto-wait.   |
-| [`cheatsheet.md`](../skills/craftdriver/cheatsheet.md)        | Command-by-command reference for writing tests.                          |
-| [`patterns.md`](../skills/craftdriver/patterns.md)            | Worked recipes (login, upload, network-wait, a11y, tracing, clock).      |
-| [`cli.md`](../skills/craftdriver/cli.md)                      | Agent-facing CLI reference.                                              |
+| File                                                                                                  | Purpose                                                               |
+| ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| [`SKILL.md`](https://github.com/dtopuzov/craftdriver/blob/main/skills/craftdriver/SKILL.md)           | Always-on, ≤ 500 tokens. Selector order, error-code-first, auto-wait. |
+| [`cheatsheet.md`](https://github.com/dtopuzov/craftdriver/blob/main/skills/craftdriver/cheatsheet.md) | Command-by-command reference for writing tests.                       |
+| [`patterns.md`](https://github.com/dtopuzov/craftdriver/blob/main/skills/craftdriver/patterns.md)     | Worked recipes (login, upload, network-wait, a11y, tracing, clock).   |
+| [`cli.md`](https://github.com/dtopuzov/craftdriver/blob/main/skills/craftdriver/cli.md)               | Agent-facing CLI reference.                                           |
 
 Point your agent at `node_modules/craftdriver/skills/craftdriver/SKILL.md`
 or copy it into your project. The other files are referenced from