craftdriver 1.0.3 → 1.1.0

package/docs/session-management.md

@@ -1,11 +1,14 @@
 # Session Management
 
-Craftdriver supports Playwright-style session persistence, allowing you to save and restore browser state including cookies and localStorage. This is perfect for:
+CraftDriver supports Playwright-style session persistence, allowing you to save and restore browser state including cookies and localStorage. This is perfect for:
 
 - **Skipping login in tests** - Log in once, reuse session across test runs
 - **Sharing auth state** - Generate auth state in setup, use in parallel tests
 - **Debugging** - Capture session state at any point
 
+Session management is the user-facing feature. Under the hood, CraftDriver uses
+the best available WebDriver transport for the browser you launched.
+
 ## Saving Session State
 
 ```typescript
@@ -51,6 +54,15 @@ The saved file contains:
 await browser.loadState('./session.json');
 ```
 
+## Working With State Objects
+
+Use the state object directly when you do not want to write a file:
+
+```typescript
+const state = await browser.storage.getState();
+await browser.storage.setState(state);
+```
+
 ## Launching with Pre-loaded State
 
 The most common pattern - launch a browser with existing session:
@@ -89,6 +101,11 @@ const cookies = await browser.storage.getCookies();
 // Get cookies for specific domain
 const domainCookies = await browser.storage.getCookies({ domain: 'example.com' });
 
+// Set multiple cookies
+await browser.storage.setCookies([
+  { name: 'theme', value: 'dark', domain: 'example.com', path: '/' },
+]);
+
 // Clear all cookies
 await browser.storage.clearCookies();
 

package/docs/standards.md

@@ -0,0 +1,40 @@
+# WebDriver Standards
+
+CraftDriver is built on W3C WebDriver protocols:
+
+- **WebDriver Classic** for broadly supported browser automation commands
+- **WebDriver BiDi** for modern bidirectional browser capabilities
+
+That protocol choice is the center of the project. CraftDriver tries to provide a modern developer experience without making browser-private protocols the foundation of user code.
+
+## Classic And BiDi Together
+
+| Protocol          | Used for                                                                                                                                              |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| WebDriver Classic | Stable navigation, element actions, browser sessions, window operations, and widely supported commands.                                               |
+| WebDriver BiDi    | Network interception, console and page errors, screenshots, storage, contexts, init scripts, downloads, tracing, and other event-driven capabilities. |
+
+CraftDriver picks the practical protocol path behind a single public API. You call `browser.click()`, `browser.navigateTo()`, `browser.network.mock()`, or `browser.startTrace()`; the library handles the transport details.
+
+## Why It Matters
+
+Standards-based automation gives projects a few useful properties:
+
+- browser behavior can converge across engines instead of depending on a single vendor protocol
+- Firefox support is a first-class target, not an afterthought
+- protocol errors can be mapped into stable CraftDriver error codes
+- browser control can be exposed safely to CLIs and MCP tools
+
+## Honest Limits
+
+WebDriver BiDi is still evolving. Some capabilities are browser-specific today, especially around emulation and mobile behavior. CraftDriver documents those limits instead of silently pretending every browser supports every feature.
+
+Use these pages when you need exact capability details:
+
+- [Network Mocking And Request Waiting](./network.md)
+- [Console Logs And JavaScript Errors](./browser-logs.md)
+- [Session Management](./session-management.md)
+- [Browser Contexts](./browser-context.md)
+- [Emulation](./emulation.md)
+- [Mobile Emulation](./mobile-emulation.md)
+- [Error Codes](./error-codes.md)

package/docs/why-craftdriver.md

@@ -0,0 +1,28 @@
+# Why CraftDriver?
+
+CraftDriver is for writing boringly reliable automation against real browsers, with code that reads nicely.
+
+## What It Cares About
+
+- 🍺 **Focused Node.js API** - browser automation without a giant framework around it.
+- 🧭 **Real browsers** - drives installed Chrome, Chromium, and Firefox instead of patched browser engine builds.
+- 🌐 **Standards that age well** - W3C WebDriver standards stay stable while browser-private protocols change.
+- 🚦 **Readable, auto-waited flows** - role, label, text, test id, CSS, XPath, click, fill, and expect.
+- 📡 **Network control** - mock, block, intercept, and wait for browser requests and responses.
+- 🔐 **Reusable sessions** - save cookies and localStorage, then launch already signed in.
+- ⏱️ **Virtual clock** - freeze or fast-forward `Date`, timers, and time-sensitive UI.
+- ♿ **Accessibility audits** - run axe-core checks on pages, elements, and locators.
+- 🧾 **Trace evidence** - capture actions, console output, errors, network events, and screenshots.
+- 🤖 **Agent-friendly** - CLI, MCP, and assistant rules when coding agents need the browser.
+
+## Good Fits
+
+- End-to-end tests in Node.js.
+- Browser scripts and diagnostics.
+- Projects that want installed Chrome, Chromium, and Firefox through WebDriver.
+- Tests that need network mocks, saved auth state, virtual time, or accessibility gates.
+- Coding agents that should use the same browser automation primitives as humans.
+
+## Not The Goal
+
+CraftDriver is not trying to be a giant testing universe. It is the browser control layer: launch, navigate, click, fill, assert, inspect, debug, and get on with your day.

package/docs/zero-config-drivers.md

@@ -0,0 +1,64 @@
+# Zero-Config Drivers
+
+CraftDriver is designed so a normal install is enough:
+
+```bash
+npm install craftdriver --save-dev
+```
+
+Then launch an installed browser:
+
+```ts
+import { Browser } from 'craftdriver';
+
+const browser = await Browser.launch({ browserName: 'chrome' });
+```
+
+You do not need to add `chromedriver`, `geckodriver`, or browser downloads to most projects. CraftDriver resolves the matching WebDriver binary, starts it on a free port, and caches resolution details so later launches are faster.
+
+## What Happens At Launch?
+
+CraftDriver checks for the driver in this order:
+
+| Step | Source                                                                  |
+| ---- | ----------------------------------------------------------------------- |
+| 1    | Explicit `ChromeService` / `FirefoxService` configuration               |
+| 2    | Environment variables such as `CHROMEDRIVER_PATH` or `GECKODRIVER_PATH` |
+| 3    | Known CI-provided driver directories (e.g. GitHub Actions' `CHROMEWEBDRIVER` / `GECKOWEBDRIVER`) |
+| 4    | Project-local binaries in `node_modules/.bin`                           |
+| 5    | Binaries already available on `PATH`                                    |
+| 6    | Auto-resolved and cached driver matching the installed browser          |
+
+If a browser update leaves a cached driver stale, CraftDriver retries once with a refreshed driver instead of making you clear the cache manually.
+
+## CI Friendly
+
+The default setup works well on CI runners that already include Chrome or
+Firefox. On **GitHub Actions** specifically, craftdriver auto-detects the
+runner's own pre-installed, version-matched driver out of the box (via
+`CHROMEWEBDRIVER` / `GECKOWEBDRIVER`) — no configuration needed, and it's
+faster than the fallback probes since it skips version detection entirely (see
+[Driver Configuration → CI platform detection](./driver-configuration.md#ci-platform-detection)).
+
+For platforms without built-in detection, or to pin a driver other than the
+runner's default, set the path manually:
+
+```bash
+CRAFTDRIVER_CHROMEDRIVER_PATH=/usr/bin/chromedriver npm test
+CRAFTDRIVER_OFFLINE=1 npm test
+CRAFTDRIVER_CACHE_DIR=/tmp/craftdriver-cache npm test
+```
+
+## When To Configure Manually
+
+Manual configuration is useful when:
+
+- your CI image pins a specific browser and driver pair
+- network access is blocked
+- you need custom driver logging
+- you want to avoid any version detection during launch
+- you're launching a non-default Chrome/Chromium/Firefox build via
+  `browserPath` / `CRAFTDRIVER_CHROME_PATH` — see
+  [Driver Configuration → Browser Binary Configuration](./driver-configuration.md#browser-binary-configuration)
+
+See [Driver Configuration](./driver-configuration.md) for the full reference.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "craftdriver",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "Modern WebDriver automation library for NodeJS",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -24,6 +24,10 @@
     "examples:start": "npm run serve",
     "docs:api": "node scripts/gen-api-reference.mjs",
     "docs:api:check": "node scripts/gen-api-reference.mjs --check",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs",
+    "docs:check": "npm run docs:api:check && npm run docs:build",
     "prepublishOnly": "npm run build && npm run lint"
   },
   "keywords": [
@@ -34,11 +38,16 @@
     "chromium",
     "automation",
     "browser-automation",
+    "e2e",
+    "e2e-testing",
     "testing",
     "selenium",
+    "mcp",
     "cli",
     "agent",
-    "ai"
+    "ai",
+    "ai-agents",
+    "web-testing"
   ],
   "author": "Dimitar Topuzov",
   "license": "MIT",
@@ -49,14 +58,15 @@
   "bugs": {
     "url": "https://github.com/dtopuzov/craftdriver/issues"
   },
-  "homepage": "https://github.com/dtopuzov/craftdriver#readme",
+  "homepage": "https://dtopuzov.github.io/craftdriver/",
   "engines": {
     "node": ">=18"
   },
   "files": [
     "dist",
     "bin",
-    "docs",
+    "docs/**/*.md",
+    "docs/public",
     "skills",
     "README.md",
     "CHANGELOG.md",
@@ -80,6 +90,7 @@
     "rimraf": "^6.1.3",
     "semantic-release": "^25.0.5",
     "typescript": "^5.0.0",
+    "vitepress": "^1.6.4",
     "vitest": "^4.0.18"
   },
   "dependencies": {
@@ -90,6 +101,9 @@
     "brace-expansion": "5.0.6",
     "ip-address": "10.1.1",
     "npm": "^11.18.0",
-    "undici": "7.28.0"
+    "undici": "7.28.0",
+    "vitepress": {
+      "vite": "6.4.3"
+    }
   }
 }