@quitecode/chromium-automaton 0.1.0-beta.1 → 0.1.0-beta.5

package/README.md

@@ -1,118 +1,53 @@
 # Chromium Automaton
 
-[![ci](https://github.com/quitecode9-lab/chromium-automation/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/quitecode9-lab/chromium-automation/actions/workflows/ci.yml)
+Chromium-only automation built on the Chrome DevTools Protocol (CDP). A lightweight, Playwright-style API with `Browser`, `Context`, `Page`, `Frame`, and `Locator` primitives—no test runner included.
 
-Chromium Automaton is a lightweight, Chromium-only browser automation library built directly on the Chrome DevTools Protocol (CDP). It offers a Playwright-style API without bundling any runner, fixtures, or reporting.
-
-## What it is
-- A small CDP client with a focused API for Chromium automation
-- A CLI for downloading and caching Chromium snapshots
-- Runner-agnostic assertions you can plug into any test setup
-
-## What it is not
-- Not a framework, runner, or test harness
-- Not multi-browser (Chromium only)
-- Not a report generator (no built-in reporting)
-
-## Install
+## Quick start
 
 ```bash
 npm install @quitecode/chromium-automaton
+npx chromium-automaton download    # downloads a pinned Chromium build
 ```
 
-## Download Chromium
-
-```bash
-npx chromium-automaton download
-npx chromium-automaton download --latest
-```
-
-## Usage
-
 ```ts
+// quick.js
 import { chromium, expect } from "@quitecode/chromium-automaton";
 
 const browser = await chromium.launch({ headless: true });
 const page = await browser.newPage();
 
-await page.goto("https://example.com", { waitUntil: "load" });
-await page.click("h1");
-const screenshotBase64 = await page.screenshotBase64();
-
+await page.goto("https://example.com");
 await expect(page).element("h1").toHaveText(/Example Domain/);
 
 await browser.close();
 ```
 
-## Documentation Site
-
-Docs are built with VitePress and published to GitHub Pages:
-https://quitecode9-lab.github.io/chromium-automation/
-
-## Architecture
-
-```mermaid
-graph LR
-  CLI[CLI: chromium-automaton download] --> Downloader[Downloader]
-  Downloader --> Cache[Chromium Cache]
-  User[User Code] --> API[chromium.launch]
-  API --> Manager[ChromiumManager]
-  Manager --> Chromium[Chromium Process]
-  Manager --> Conn[CDP Connection]
-  Conn --> Browser[Browser]
-  Browser --> Page[Page]
-  Page --> Frame[Frame]
-  Page --> Locator[Locator]
-  Page --> Expect[expect]
-```
-
-## Locators
-
-```ts
-const locator = page.locator("#login", { pierceShadowDom: true });
-await locator.click();
-await locator.type("admin");
-```
-
-## Frames
-
-```ts
-const frame = page.frame({ urlIncludes: "embedded" });
-if (frame) {
-  await frame.click("button.submit");
-}
-```
-
-## Shadow DOM
-
-```ts
-await page.click("button.action", { pierceShadowDom: true });
-const text = await page.evaluate(() => document.title);
+Run it:
+```bash
+node quick.js
 ```
 
-## Assertions
-
-```ts
-await expect(page).element(".ready").toExist();
-await expect(page).element(".hidden").not.toBeVisible();
-await expect(page).element("h1").toHaveText("Example Domain");
-```
+## Core ideas
+- CDP-only: no WebDriver, no playwright-core dependency.
+- Small surface: pages/frames/locators, plus built-in expect matchers.
+- Selector routing: CSS by default; XPath if the selector starts with `/`, `./`, `.//`, `..`, or `(/`. Shadow DOM via `>>>` (e.g., `host >>> button`).
+- Contexts: `browser.newContext()` gives incognito-style isolation without launching a new browser.
+- Downloads: `npx chromium-automaton download` (or `--latest`) fetches Chromium into a local cache.
 
-## Environment configuration
-- `CHROMIUM_AUTOMATON_CACHE_DIR`: override cache root
-- `CHROMIUM_AUTOMATON_REVISION`: override pinned revision
-- `CHROMIUM_AUTOMATON_EXECUTABLE_PATH`: bypass download and use this executable
-- `CHROMIUM_AUTOMATON_LOG_LEVEL`: error, warn, info, debug, trace
+## Key APIs
+- `chromium.launch(options)` → `Browser`
+- `browser.newContext()` → isolated `BrowserContext`
+- `browser.newPage()` / `context.newPage()` → `Page`
+- `page.goto(url, { waitUntil: "load" | "domcontentloaded" })`
+- Actions: `click`, `dblclick`, `type`, `typeSecure`, `fillInput`, `selectOption`, `setFileInput`
+- Queries: `query`, `queryAll`, `queryXPath`, `queryAllXPath`, `locator`
+- Assertions: `expect(page).element("selector").toBeVisible()` (see `docs/guide/assertions.md`)
 
-Default cache root:
-- Linux and macOS: `~/.cache/chromium-automaton`
-- Windows: `%LOCALAPPDATA%\chromium-automaton`
+## Docs
+Full guide and API reference: https://quitecode9-lab.github.io/chromium-automation/ (built from `docs/` via VitePress). Start at `docs/guide/intro.md` or `docs/guide/api/`.
 
-## Limitations
-- Chromium only (no Chrome, Firefox, WebKit)
-- XPath selectors do not pierce shadow DOM
-- `evaluate(string)` is unsafe if the string includes untrusted input
-- Only http/https are allowed in `goto` unless `allowFileUrl` is true
+## Demo app
+`index.html` is a local, data-driven visa-style wizard used to stress-test automation flows (no server required). Open it directly via `file://` to exercise navigation, conditionals, overlays, Shadow DOM, uploads, and receipts.
 
-## ESM
-This package is ESM-only. Use `import` syntax in Node 18+.
+## License
+MIT

package/dist/assert/expect.d.ts

@@ -1 +1 @@
-export { E as ExpectSelectorOptions, e as expect } from '../expect-CBZIoH1D.js';
+export { E as ElementExpectation, c as ExpectFrame, d as ExpectSelectorOptions, e as expect } from '../expect-DTg-IWd-.js';

package/dist/assert/expect.js

@@ -1,6 +1,6 @@
 import {
   expect
-} from "../chunk-ADOXZ36A.js";
+} from "../chunk-E3D6NMS7.js";
 export {
   expect
 };