autopilot-web 3.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jason M. Schwefel / Cold Bore Ballistics LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# autopilot-web
+
+The **web backend** for [AutoPilot](https://github.com/jschwefel-CBB/autopilot-core) —
+runs the same declarative JSON test plans against a **browser**, via
+[Playwright](https://playwright.dev). It is a first-class **test backend** (headless,
+for CI parity, like the macOS/iOS/Android backends) *and* a **demo/screencast driver**
+(headed, with on-page highlight/caption overlays and paced typing).
+
+AutoPilot plans are plain JSON, designed to be authored by hand or by an AI agent. The
+same plan the native runners execute drives the browser here — the JSON plan schema is
+the single cross-platform contract. This runner reimplements the plan-execution loop
+over Playwright, exactly as the Android runner reimplements it over UiAutomator and the
+iOS runner over XCUITest.
+
+> AutoPilot **is** a web testing tool. (Earlier AutoPilot docs said it was not — that is
+> no longer true; web is a supported platform.)
+
+## What runs on web, and what is skipped
+
+Everything with a browser equivalent is exercised and asserted:
+
+- **Actions:** `launch` (open the URL), `click`, `doubleClick`, `rightClick`, `press`,
+  `type` (with `clear`/`commit`/paced typing), `setValue`, `keyPress`, `scroll`, `drag`,
+  `waitFor`, `screenshot`, `wait`, `assert`, and the demo actions `highlight` /
+  `caption` / `pace`.
+- **Assert properties:** `value`, `title`, `enabled`, `focused`, `marked` (checkbox/
+  radio), `position`, `size`, `count` — with ops `equals` / `notEquals` / `contains` /
+  `matches` / `exists` / `notExists` / `greaterThan` / `lessThan`.
+
+Steps with **no web equivalent are skipped** (reported as `skipped`, never failed —
+the same "skip-don't-branch" contract the mobile backends use):
+
+- `menu` (native menu bar), `assertPixel` / `assertRegion` / `snapshot` (native pixel
+  capture), `exec` (host command), and the assert properties `clipboard` / `stdout` /
+  `stderr` / `exitCode`.
+
+## Prerequisites — install Node.js (18+)
+
+You need **Node.js 18 or newer**. Install it for your OS:
+
+- **Debian:** `sudo apt-get update && sudo apt-get install -y nodejs npm`
+  (for a current version, use [NodeSource](https://github.com/nodesource/distributions):
+  `curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt-get install -y nodejs`)
+- **Ubuntu:** same as Debian (NodeSource recommended for a current version).
+- **RHEL / Fedora:** `sudo dnf install -y nodejs npm`
+  (or NodeSource: `curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash - && sudo dnf install -y nodejs`)
+- **Windows:** download the LTS installer from <https://nodejs.org/> and run it, or
+  `winget install OpenJS.NodeJS.LTS`.
+- **macOS:** `brew install node`, or download the installer from <https://nodejs.org/>.
+
+Verify: `node --version` (should print `v18…` or higher) and `npm --version`.
+
+## Install
+
+From the repo directory:
+
+```bash
+npm install                      # install dependencies (Playwright + TypeScript)
+npx playwright install chromium  # download the Chromium browser Playwright drives
+npm run build                    # compile the TypeScript to dist/
+```
+
+## Run a plan
+
+```bash
+# Headless (the normal test path) against the bundled TestHost page:
+node dist/src/index.js run plans/test-web-capabilities.json --url testhost/index.html
+
+# Against a live site:
+node dist/src/index.js run plans/my-plan.json --url https://example.com
+
+# Print the report as JSON (for tooling / CI):
+node dist/src/index.js run plans/my-plan.json --url https://example.com --json
+```
+
+`--url` accepts an `http(s)://` URL or a local file path (a bare path is opened as a
+`file://` URL). A plan may also set `target.url`; the `--url` flag overrides it.
+
+The process exits non-zero if the plan does not pass, so CI can gate on it.
+
+### Demo / screencast mode
+
+```bash
+# Headed browser, with on-page highlight + caption overlays and paced typing,
+# recording a video of the run:
+node dist/src/index.js run plans/my-plan.json --url https://example.com \
+  --headed --demo --record ./recordings
+```
+
+- `--headed` shows the browser window (omit for headless).
+- `--demo` renders `highlight`/`caption` overlays and applies `pace` cadence
+  (per-char typing + post-step delays). **Without `--demo`, the demo actions are
+  passing no-ops** — a plan runs as a fast, clean test.
+- `--record <dir>` writes a `.webm` video of the run into `<dir>`.
+
+## Test (the CI parity gate)
+
+```bash
+npm test
+```
+
+This builds, then runs the `web-capabilities` plan against the bundled
+`testhost/index.html` and asserts the expected pass/skip counts — the gate that makes
+web a real test backend. It uses Node's built-in test runner (`node:test`); no extra
+test framework is required.
+
+## Layout
+
+- `src/planModel.ts` — the Plan/Step/Selector/Assert types, mirroring the core schema.
+- `src/runner.ts` — the plan-execution loop over Playwright (selector mapping, actions,
+  assertions, demo overlays, skip-don't-branch).
+- `src/index.ts` — the CLI.
+- `testhost/index.html` — the web TestHost (mirrors the native TestHostApp surface).
+- `plans/test-web-capabilities.json` — the plan run by the parity gate.
+- `test/runner.test.ts` — the parity-gate tests.
+
+## Selector mapping
+
+AutoPilot selectors map onto Playwright locators:
+
+| AutoPilot selector | Playwright locator |
+| --- | --- |
+| `identifier: "foo"` | `page.locator('#foo')` |
+| `role: "button", title: "Save"` | `page.getByRole('button', { name: 'Save' })` |
+| `role: "list"` | `page.getByRole('list')` |
+| `title: "Save"` (no role) | `page.getByText('Save')` |
+| `index: 2` | `.nth(2)` |
+| `within: {...}` | resolve the parent, then locate the child inside it |
+
+Native AX roles (e.g. `AXButton`, `AXTextField`) are mapped to their ARIA equivalents
+(`button`, `textbox`); plain ARIA roles pass through unchanged.

package/dist/src/index.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// AutoPilot web runner CLI.
+//   autopilot-web run <plan.json> --url <target> [--headed] [--demo] [--record <dir>]
+//
+// Runs the same declarative JSON plan AutoPilot uses on macOS/iOS/Android, against a
+// browser via Playwright. A test backend (headless, for CI parity) AND a
+// demo/screencast driver (--headed --demo).
+import { readFileSync } from "node:fs";
+import { resolve, isAbsolute } from "node:path";
+import { pathToFileURL } from "node:url";
+import { parsePlan } from "./planModel.js";
+import { runPlan } from "./runner.js";
+function usage() {
+    process.stderr.write("usage: autopilot-web run <plan.json> --url <target> [--headed] [--demo] [--record <dir>] [--json]\n");
+    process.exit(2);
+}
+function parseArgs(argv) {
+    if (argv[0] !== "run" || !argv[1])
+        usage();
+    const out = { planPath: argv[1], headed: false, demo: false, json: false };
+    for (let i = 2; i < argv.length; i++) {
+        const a = argv[i];
+        switch (a) {
+            case "--url":
+                out.url = argv[++i];
+                break;
+            case "--headed":
+                out.headed = true;
+                break;
+            case "--demo":
+                out.demo = true;
+                break;
+            case "--record":
+                out.recordDir = argv[++i];
+                break;
+            case "--json":
+                out.json = true;
+                break;
+            default:
+                process.stderr.write(`unknown argument: ${a}\n`);
+                usage();
+        }
+    }
+    return out;
+}
+/** Resolve a --url that may be a local file path or an http(s) URL to something
+ *  page.goto accepts. A bare path becomes a file:// URL. */
+function resolveUrl(url) {
+    if (/^https?:\/\//i.test(url) || /^file:\/\//i.test(url))
+        return url;
+    return pathToFileURL(isAbsolute(url) ? url : resolve(process.cwd(), url)).href;
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    let planRaw;
+    try {
+        planRaw = JSON.parse(readFileSync(args.planPath, "utf8"));
+    }
+    catch (e) {
+        process.stderr.write(`Cannot read plan: ${args.planPath} (${String(e)})\n`);
+        process.exit(2);
+    }
+    const plan = parsePlan(planRaw);
+    // The URL: --url wins, else the plan's target.url, else error.
+    const rawUrl = args.url ?? plan.target.url;
+    if (!rawUrl) {
+        process.stderr.write("no target URL — pass --url <target> or set target.url in the plan\n");
+        process.exit(2);
+    }
+    const url = resolveUrl(rawUrl);
+    const report = await runPlan(plan, {
+        url, headed: args.headed, demo: args.demo, recordDir: args.recordDir,
+    });
+    if (args.json) {
+        process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+    }
+    else {
+        printReport(report);
+    }
+    // Exit non-zero if the plan did not pass, so CI gates on it.
+    process.exit(report.result === "pass" ? 0 : 1);
+}
+function printReport(r) {
+    const c = r.counts;
+    process.stdout.write(`RESULT ${r.result} — ${c.pass} pass, ${c.fail} fail, ${c.error} error, ${c.skipped} skipped\n`);
+    process.stdout.write(`Plan: ${r.plan}\n`);
+    for (const s of r.steps) {
+        const detail = s.message ? `  (${s.message})` : (s.expected != null ? `  expected=${s.expected} actual=${s.actual}` : "");
+        process.stdout.write(`  [${s.result}] ${s.id} — ${s.action} (${s.durationMs}ms)${detail}\n`);
+    }
+}
+main().catch((e) => {
+    process.stderr.write(`autopilot-web error: ${String(e)}\n`);
+    process.exit(1);
+});

package/dist/src/planModel.js

@@ -0,0 +1,76 @@
+// Plan model for the web runner. Mirrors autopilot-core's schema v1.2 (the JSON
+// plan is the single cross-platform contract). Like Android's PlanModel.kt and
+// iOS's PlanModel.swift, this hand-mirrors the schema rather than importing the
+// Swift package.
+const ACCEPTED_SCHEMA_VERSIONS = new Set(["1.1", "1.2"]);
+const VALID_LEVELS = new Set(["happyPath", "integrationSuite", "tryToBreakIt"]);
+/** Parse + validate a plan, mirroring the core parser's headline rules. Throws on
+ *  anything the Swift parser would reject (unsupported version, missing level,
+ *  duplicate ids, missing required per-action args). */
+export function parsePlan(raw) {
+    if (typeof raw !== "object" || raw === null)
+        throw new Error("plan is not an object");
+    const plan = raw;
+    if (!ACCEPTED_SCHEMA_VERSIONS.has(plan.schemaVersion)) {
+        throw new Error(`unsupported schemaVersion '${plan.schemaVersion}' (accepted: 1.1, 1.2)`);
+    }
+    if (!Array.isArray(plan.steps))
+        throw new Error("plan.steps must be an array");
+    const seen = new Set();
+    for (const step of plan.steps) {
+        if (!step.id)
+            throw new Error("a step is missing its id");
+        if (seen.has(step.id))
+            throw new Error(`duplicate step id: ${step.id}`);
+        seen.add(step.id);
+        if (!step.level || !VALID_LEVELS.has(step.level)) {
+            throw new Error(`step ${step.id}: missing/invalid level (use happyPath, integrationSuite, tryToBreakIt)`);
+        }
+        validateStep(step);
+    }
+    return plan;
+}
+const TARGET_REQUIRING = new Set([
+    "click", "doubleClick", "rightClick", "press", "type", "keyPress", "setValue",
+    "scroll", "waitFor", "assert", "highlight",
+]);
+function validateStep(step) {
+    if (TARGET_REQUIRING.has(step.action) && !step.target) {
+        const clipboardAssert = step.action === "assert" && step.assert?.property === "clipboard";
+        if (!clipboardAssert)
+            throw new Error(`step ${step.id}: action '${step.action}' requires a target`);
+    }
+    switch (step.action) {
+        case "type":
+        case "setValue":
+            if (step.args?.text == null)
+                throw new Error(`step ${step.id}: '${step.action}' requires args.text`);
+            break;
+        case "keyPress":
+            if (step.args?.keys == null)
+                throw new Error(`step ${step.id}: keyPress requires args.keys`);
+            break;
+        case "scroll":
+            if (step.args?.deltaX == null && step.args?.deltaY == null)
+                throw new Error(`step ${step.id}: scroll requires args.deltaX or args.deltaY`);
+            break;
+        case "assert":
+            if (!step.assert)
+                throw new Error(`step ${step.id}: assert requires an assert block`);
+            break;
+        case "wait":
+            if (step.args?.seconds == null)
+                throw new Error(`step ${step.id}: wait requires args.seconds`);
+            break;
+        case "caption":
+            if (step.args?.text == null)
+                throw new Error(`step ${step.id}: caption requires args.text`);
+            break;
+        case "pace":
+            if (step.args?.typeMsPerChar == null && step.args?.stepDelayMs == null)
+                throw new Error(`step ${step.id}: pace requires args.typeMsPerChar or args.stepDelayMs`);
+            break;
+        default:
+            break;
+    }
+}

package/dist/src/runner.js

@@ -0,0 +1,394 @@
+// The AutoPilot web runner: reimplements the deterministic plan-execution loop over
+// a Playwright browser, exactly as Android reimplemented it over UiAutomator and iOS
+// over XCUITest. The JSON plan schema is the only shared contract.
+//
+// Skip-don't-branch: actions with no web equivalent (native menubar `menu`, native
+// pixel capture assertPixel/assertRegion/snapshot, host `exec`) are SKIPPED and
+// reported as such — never a hard failure — matching the mobile runners.
+import { chromium, } from "playwright";
+// Actions with no web equivalent — reported as skipped (skip-don't-branch).
+const SKIP_ON_WEB = new Set([
+    "menu", "assertPixel", "assertRegion", "snapshot", "exec",
+]);
+/** Run a plan against a browser and return a report. */
+export async function runPlan(plan, options) {
+    const timeout = plan.defaults?.timeoutMs ?? options.defaultTimeoutMs ?? 5000;
+    const browser = await chromium.launch({ headless: !options.headed });
+    const context = await browser.newContext(options.recordDir ? { recordVideo: { dir: options.recordDir } } : {});
+    const page = await context.newPage();
+    page.setDefaultTimeout(timeout);
+    const cadence = { typeMsPerChar: 0, stepDelayMs: 0 };
+    const results = [];
+    const url = plan.target.url ?? options.url;
+    try {
+        for (const step of plan.steps) {
+            const start = Date.now();
+            let r;
+            try {
+                r = await runStep(step, { page, url, timeout, demo: !!options.demo, cadence });
+            }
+            catch (e) {
+                r = {
+                    id: step.id, action: step.action, result: "error",
+                    durationMs: Date.now() - start, message: String(e),
+                };
+            }
+            r.durationMs = Date.now() - start;
+            results.push(r);
+            // Demo pacing: pause after each step (except pace itself) so a screencast is
+            // watchable. Never runs in a normal test (cadence stays 0 unless demo pace set it).
+            if (options.demo && step.action !== "pace" && cadence.stepDelayMs > 0) {
+                await sleep(cadence.stepDelayMs);
+            }
+            if (r.result === "fail" || r.result === "error") {
+                // Stop on first failure (matches the runners' default; no keepGoing here).
+                break;
+            }
+        }
+    }
+    finally {
+        await context.close();
+        await browser.close();
+    }
+    const counts = { pass: 0, fail: 0, error: 0, skipped: 0 };
+    for (const r of results)
+        counts[r.result] += 1;
+    const overall = counts.fail || counts.error ? "fail" : "pass";
+    return { plan: plan.name, result: overall, steps: results, counts };
+}
+async function runStep(step, ctx) {
+    const { page } = ctx;
+    const base = (result, extra = {}) => ({ id: step.id, action: step.action, result, durationMs: 0, ...extra });
+    if (SKIP_ON_WEB.has(step.action)) {
+        return base("skipped", { message: `${step.action} has no web equivalent` });
+    }
+    switch (step.action) {
+        case "launch": {
+            await page.goto(ctx.url, { waitUntil: "load" });
+            return base("pass");
+        }
+        case "terminate":
+            // Browser/context teardown happens in runPlan's finally; nothing per-step.
+            return base("pass");
+        case "wait":
+            await sleep((step.args?.seconds ?? 0) * 1000);
+            return base("pass");
+        case "waitFor": {
+            const present = step.args?.present ?? true;
+            const loc = locate(page, step.target);
+            try {
+                await loc.first().waitFor({ state: present ? "visible" : "hidden", timeout: ctx.timeout });
+                return base("pass");
+            }
+            catch {
+                return base("fail", { message: `element ${present ? "did not appear" : "did not disappear"}` });
+            }
+        }
+        case "click":
+            await locate(page, step.target).first().click();
+            return base("pass");
+        case "doubleClick":
+            await locate(page, step.target).first().dblclick();
+            return base("pass");
+        case "rightClick":
+            await locate(page, step.target).first().click({ button: "right" });
+            return base("pass");
+        case "press":
+            // No native AX "press" on web; a click is the closest robust equivalent.
+            await locate(page, step.target).first().click();
+            return base("pass");
+        case "type": {
+            const loc = locate(page, step.target).first();
+            const text = step.args?.text ?? "";
+            if (step.args?.clear)
+                await loc.fill("");
+            if (step.args?.focus !== false)
+                await loc.focus();
+            // Demo pacing: type char-by-char with a delay so it's watchable. In a normal
+            // run the delay is 0, so this types at full speed.
+            const delay = ctx.demo ? (step.args?.typeMsPerChar ?? ctx.cadence.typeMsPerChar) : 0;
+            await loc.pressSequentially(text, { delay });
+            if (step.args?.commit)
+                await loc.press("Enter");
+            return base("pass");
+        }
+        case "setValue": {
+            // fill() replaces the whole value in one shot (the setValue semantics).
+            await locate(page, step.target).first().fill(step.args?.text ?? "");
+            return base("pass");
+        }
+        case "keyPress": {
+            const key = chordToPlaywright(step.args?.keys ?? "");
+            await page.keyboard.press(key);
+            return base("pass");
+        }
+        case "scroll": {
+            const loc = locate(page, step.target).first();
+            const dx = step.args?.deltaX ?? 0;
+            const dy = step.args?.deltaY ?? 0;
+            await loc.evaluate((el, [x, y]) => { el.scrollBy(x, y); }, [dx, dy]);
+            return base("pass");
+        }
+        case "drag": {
+            const from = locate(page, step.target).first();
+            const to = step.args?.to ? locate(page, step.args.to).first() : null;
+            if (!to)
+                return base("error", { message: "drag on web requires args.to (file drag unsupported)" });
+            await from.dragTo(to);
+            return base("pass");
+        }
+        case "screenshot": {
+            const path = step.args?.path;
+            if (step.target)
+                await locate(page, step.target).first().screenshot(path ? { path } : {});
+            else
+                await page.screenshot(path ? { path, fullPage: false } : {});
+            return base("pass");
+        }
+        case "assert":
+            return await runAssert(step, ctx);
+        // ── Demo actions (v1.2). Render only in demo mode; otherwise passing no-ops.
+        case "pace": {
+            if (step.args?.typeMsPerChar != null)
+                ctx.cadence.typeMsPerChar = Math.max(0, step.args.typeMsPerChar);
+            if (step.args?.stepDelayMs != null)
+                ctx.cadence.stepDelayMs = Math.max(0, step.args.stepDelayMs);
+            return base("pass");
+        }
+        case "caption": {
+            if (ctx.demo)
+                await showCaption(page, step.args?.text ?? "", step.args?.position ?? "bottom", step.args?.holdMs ?? 0);
+            return base("pass");
+        }
+        case "highlight": {
+            if (ctx.demo) {
+                try {
+                    await showHighlight(locate(page, step.target).first(), step.args?.holdMs ?? 0);
+                }
+                catch { /* decorative */ }
+            }
+            return base("pass");
+        }
+        default:
+            return base("skipped", { message: `unhandled action ${step.action}` });
+    }
+}
+// ── Selector mapping (verified against the Playwright locator API + the TestHost) ──
+// identifier -> [id="..."]; role+title -> getByRole(role,{name:title}); role alone ->
+// getByRole; title alone -> by accessible name; index -> .nth(); within -> chained.
+function locate(page, sel) {
+    let loc = locateIn(page, sel);
+    if (sel.within) {
+        // Scope: resolve the parent first, then find the child inside it.
+        const parent = locate(page, sel.within);
+        loc = locateIn(parent, sel);
+    }
+    if (sel.index != null)
+        loc = loc.nth(sel.index);
+    return loc;
+}
+// Build a locator from a selector's own fields, rooted at `root` (a Page or Locator).
+function locateIn(root, sel) {
+    if (sel.identifier)
+        return root.locator(`#${cssEscape(sel.identifier)}`);
+    if (sel.role) {
+        // AutoPilot roles may be native-AX style (AXButton) or plain ARIA (button).
+        const role = normalizeRole(sel.role);
+        return sel.title
+            ? root.getByRole(role, { name: sel.title })
+            : root.getByRole(role);
+    }
+    if (sel.title)
+        return root.getByText(sel.title);
+    if (sel.value)
+        return root.locator(`[value="${cssEscape(sel.value)}"]`);
+    // Nothing usable — an empty locator that will simply not match.
+    return root.locator(":scope >> nth=-1");
+}
+// Map a few common AX roles to ARIA roles; pass through anything already ARIA.
+function normalizeRole(role) {
+    const ax = {
+        AXButton: "button",
+        AXTextField: "textbox",
+        AXTextArea: "textbox",
+        AXCheckBox: "checkbox",
+        AXStaticText: "text",
+        AXList: "list",
+        AXRow: "listitem",
+        AXLink: "link",
+        AXRadioButton: "radio",
+    };
+    return ax[role] ?? role;
+}
+async function runAssert(step, ctx) {
+    const a = step.assert;
+    const base = (result, extra = {}) => ({ id: step.id, action: "assert", result, durationMs: 0, ...extra });
+    // presence
+    if (a.op === "exists" || a.op === "notExists") {
+        const present = a.op === "exists";
+        const loc = locate(ctx.page, step.target);
+        try {
+            await loc.first().waitFor({ state: present ? "visible" : "hidden", timeout: ctx.timeout });
+            return base("pass", { expected: a.op, actual: a.op });
+        }
+        catch {
+            return base("fail", { expected: a.op, actual: present ? "notExists" : "exists" });
+        }
+    }
+    // count
+    if (a.property === "count") {
+        const n = await locate(ctx.page, step.target).count();
+        return compare(base, a, String(n));
+    }
+    // clipboard / stdout / stderr / exitCode have no web equivalent.
+    if (["clipboard", "stdout", "stderr", "exitCode"].includes(a.property)) {
+        return base("skipped", { message: `assert property '${a.property}' has no web equivalent` });
+    }
+    const loc = locate(ctx.page, step.target).first();
+    const actual = await readProperty(loc, a.property);
+    return compare(base, a, actual);
+}
+async function readProperty(loc, property) {
+    switch (property) {
+        case "value": {
+            // A form control's value, or the element's text for non-inputs (statusLabel).
+            const tag = await loc.evaluate((el) => el.tagName.toLowerCase()).catch(() => "");
+            if (tag === "input" || tag === "textarea" || tag === "select")
+                return (await loc.inputValue().catch(() => "")) ?? "";
+            return ((await loc.textContent()) ?? "").trim();
+        }
+        case "title":
+            return ((await loc.textContent()) ?? "").trim();
+        case "enabled":
+            return String(await loc.isEnabled().catch(() => false));
+        case "focused":
+            return String(await loc.evaluate((el) => el === document.activeElement).catch(() => false));
+        case "marked": // checkbox/radio checked state
+            return String(await loc.isChecked().catch(() => false));
+        case "position": {
+            const box = await loc.boundingBox();
+            return box ? `${Math.round(box.x)},${Math.round(box.y)}` : "";
+        }
+        case "size": {
+            const box = await loc.boundingBox();
+            return box ? `${Math.round(box.width)},${Math.round(box.height)}` : "";
+        }
+        default:
+            return "";
+    }
+}
+function compare(base, a, actual) {
+    const expected = a.expected ?? "";
+    let ok = false;
+    switch (a.op) {
+        case "equals":
+            ok = actual === expected;
+            break;
+        case "notEquals":
+            ok = actual !== expected;
+            break;
+        case "contains":
+            ok = actual.includes(expected);
+            break;
+        case "matches":
+            ok = safeRegex(expected)?.test(actual) ?? false;
+            break;
+        case "greaterThan":
+            ok = num(actual) > num(expected);
+            break;
+        case "lessThan":
+            ok = num(actual) < num(expected);
+            break;
+        default: ok = false;
+    }
+    return base(ok ? "pass" : "fail", { expected, actual });
+}
+// ── Demo overlays (injected into the page in demo mode) ──
+async function showHighlight(loc, holdMs) {
+    const box = await loc.boundingBox();
+    if (!box)
+        return;
+    await loc.page().evaluate(({ b, hold }) => {
+        const d = document.createElement("div");
+        d.style.cssText =
+            `position:fixed;left:${b.x - 4}px;top:${b.y - 4}px;width:${b.width + 8}px;height:${b.height + 8}px;` +
+                "border:3px solid gold;border-radius:8px;box-shadow:0 0 12px 3px rgba(255,215,0,.8);" +
+                "pointer-events:none;z-index:2147483647;transition:opacity .3s;";
+        d.setAttribute("data-autopilot-overlay", "highlight");
+        document.body.appendChild(d);
+        setTimeout(() => { d.style.opacity = "0"; setTimeout(() => d.remove(), 300); }, Math.max(hold, 400));
+    }, { b: box, hold: holdMs });
+}
+async function showCaption(page, text, position, holdMs) {
+    await page.evaluate(({ t, pos, hold }) => {
+        const d = document.createElement("div");
+        const vertical = pos === "top" ? "top:24px;" : pos === "center" ? "top:50%;transform:translate(-50%,-50%);" : "bottom:24px;";
+        d.style.cssText =
+            `position:fixed;left:50%;${pos === "center" ? "" : "transform:translateX(-50%);"}${vertical}` +
+                "background:rgba(0,0,0,.8);color:#fff;font:600 20px system-ui,sans-serif;padding:12px 20px;" +
+                "border-radius:12px;pointer-events:none;z-index:2147483647;max-width:70vw;text-align:center;transition:opacity .3s;";
+        d.setAttribute("data-autopilot-overlay", "caption");
+        d.textContent = t;
+        document.body.appendChild(d);
+        setTimeout(() => { d.style.opacity = "0"; setTimeout(() => d.remove(), 300); }, Math.max(hold, 400));
+    }, { t: text, pos: position, hold: holdMs });
+}
+// ── helpers ──
+function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
+function num(s) { const n = Number(s); return Number.isNaN(n) ? NaN : n; }
+function safeRegex(p) { try {
+    return new RegExp(p);
+}
+catch {
+    return null;
+} }
+function cssEscape(s) { return s.replace(/["\\]/g, "\\$&"); }
+// Translate an AutoPilot chord ("cmd+s", "cmd+plus") to a Playwright key string
+// ("Meta+s", "Meta+Shift+="). Playwright uses Meta for Cmd, Control for Ctrl.
+function chordToPlaywright(chord) {
+    const parts = chord.split("+").map((p) => p.trim().toLowerCase()).filter(Boolean);
+    const mods = [];
+    let key = "";
+    for (const p of parts) {
+        switch (p) {
+            case "cmd":
+            case "command":
+                mods.push("Meta");
+                break;
+            case "ctrl":
+            case "control":
+                mods.push("Control");
+                break;
+            case "shift":
+                mods.push("Shift");
+                break;
+            case "opt":
+            case "option":
+            case "alt":
+                mods.push("Alt");
+                break;
+            case "plus":
+                mods.push("Shift");
+                key = "=";
+                break; // '+' is Shift+'='
+            case "enter":
+            case "return":
+                key = "Enter";
+                break;
+            case "tab":
+                key = "Tab";
+                break;
+            case "space":
+                key = " ";
+                break;
+            case "escape":
+                key = "Escape";
+                break;
+            case "delete":
+                key = "Backspace";
+                break;
+            default: key = p.length === 1 ? p : p.charAt(0).toUpperCase() + p.slice(1);
+        }
+    }
+    return [...mods, key].filter(Boolean).join("+");
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "autopilot-web",
+  "version": "3.5.0",
+  "description": "Web backend for AutoPilot — runs the same declarative JSON plans against a browser via Playwright. A test runner AND a demo/screencast driver.",
+  "type": "module",
+  "bin": {
+    "autopilot-web": "dist/src/index.js"
+  },
+  "files": [
+    "dist/src",
+    "testhost",
+    "plans",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "run-plan": "npm run build && node dist/src/index.js",
+    "test": "npm run build && node --test dist/test/*.test.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "playwright": "^1.48.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jschwefel-CBB/autopilot-web.git"
+  },
+  "homepage": "https://github.com/jschwefel-CBB/autopilot-web#readme",
+  "bugs": {
+    "url": "https://github.com/jschwefel-CBB/autopilot-web/issues"
+  },
+  "author": "Jason M. Schwefel",
+  "license": "MIT"
+}

package/plans/test-web-capabilities.json

@@ -0,0 +1,65 @@
+{
+  "schemaVersion": "1.2",
+  "name": "web-capabilities",
+  "target": {},
+  "defaults": { "timeoutMs": 5000, "retryIntervalMs": 100 },
+  "steps": [
+    { "id": "launch", "level": "happyPath", "action": "launch" },
+
+    { "id": "wait-name", "level": "happyPath", "action": "waitFor",
+      "target": { "identifier": "nameField" }, "args": { "present": true } },
+
+    { "id": "type-name", "level": "happyPath", "action": "type",
+      "target": { "identifier": "nameField" },
+      "args": { "text": "Ada", "clear": true } },
+
+    { "id": "assert-status-by-id", "level": "happyPath", "action": "assert",
+      "target": { "identifier": "statusLabel" },
+      "assert": { "property": "value", "op": "contains", "expected": "Ada" } },
+
+    { "id": "assert-status-by-role", "level": "integrationSuite", "action": "assert",
+      "target": { "role": "status" },
+      "assert": { "property": "value", "op": "contains", "expected": "Ada" } },
+
+    { "id": "click-greet-by-role", "level": "happyPath", "action": "click",
+      "target": { "role": "button", "title": "Greet" } },
+
+    { "id": "assert-greeted", "level": "happyPath", "action": "assert",
+      "target": { "identifier": "statusLabel" },
+      "assert": { "property": "value", "op": "equals", "expected": "status: greeted" } },
+
+    { "id": "type-search", "level": "integrationSuite", "action": "type",
+      "target": { "identifier": "searchField" },
+      "args": { "text": "Item 1" } },
+
+    { "id": "assert-filtered-count", "level": "integrationSuite", "action": "assert",
+      "target": { "role": "listitem" },
+      "assert": { "property": "count", "op": "greaterThan", "expected": "0" } },
+
+    { "id": "check-agree", "level": "happyPath", "action": "click",
+      "target": { "identifier": "agree" } },
+
+    { "id": "assert-agree-marked", "level": "integrationSuite", "action": "assert",
+      "target": { "identifier": "agree" },
+      "assert": { "property": "marked", "op": "equals", "expected": "true" } },
+
+    { "id": "assert-greet-enabled", "level": "integrationSuite", "action": "assert",
+      "target": { "identifier": "greetButton" },
+      "assert": { "property": "enabled", "op": "equals", "expected": "true" } },
+
+    { "id": "menu-skips", "level": "tryToBreakIt", "action": "menu",
+      "args": { "menuPath": ["File", "Nope"] } },
+
+    { "id": "exec-skips", "level": "tryToBreakIt", "action": "exec",
+      "args": { "command": "true" } },
+
+    { "id": "pace", "level": "happyPath", "action": "pace",
+      "args": { "typeMsPerChar": 30, "stepDelayMs": 150 } },
+
+    { "id": "caption-demo", "level": "happyPath", "action": "caption",
+      "args": { "text": "Demo overlay", "position": "bottom", "holdMs": 500 } },
+
+    { "id": "highlight-demo", "level": "happyPath", "action": "highlight",
+      "target": { "identifier": "nameField" }, "args": { "holdMs": 500 } }
+  ]
+}

package/testhost/index.html

@@ -0,0 +1,108 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>AutoPilot Web TestHost</title>
+  <style>
+    :root { font-family: system-ui, -apple-system, sans-serif; }
+    body { margin: 0; padding: 24px; max-width: 720px; }
+    h1 { font-size: 20px; }
+    .row { margin: 14px 0; }
+    label { display: block; font-size: 13px; color: #555; margin-bottom: 4px; }
+    input[type="text"], input[type="search"] { width: 320px; padding: 8px; font-size: 15px; }
+    #status { font-weight: 600; min-height: 1.2em; }
+    #results { border: 1px solid #ccc; height: 140px; overflow-y: auto; width: 320px; padding: 4px; }
+    .result { padding: 6px 4px; border-bottom: 1px solid #eee; }
+    button { padding: 8px 14px; font-size: 15px; }
+    #clicks { color: #06c; }
+  </style>
+</head>
+<body>
+  <!--
+    Web TestHost for AutoPilot. Mirrors the native TestHostApp surface so the same
+    kinds of plans run against a browser. Elements carry BOTH a stable id (for the
+    selector.identifier -> [id] mapping) AND a proper role/accessible name (for the
+    selector role+title -> getByRole mapping) so both paths are exercised.
+  -->
+  <h1>AutoPilot Web TestHost</h1>
+
+  <div class="row">
+    <label for="nameField">Name</label>
+    <!-- Typing here echoes into #status, like the native nameField -> statusLabel. -->
+    <input type="text" id="nameField" aria-label="Name" />
+  </div>
+
+  <div class="row">
+    <label>Status</label>
+    <!-- role="status" + id. Its text reflects the last name typed. -->
+    <div id="statusLabel" role="status">status: (none)</div>
+  </div>
+
+  <div class="row">
+    <!-- A button with an accessible name "Greet" (getByRole('button',{name:'Greet'})). -->
+    <button id="greetButton" type="button">Greet</button>
+    <span id="clicks" role="note" aria-label="Clicks">clicks: 0</span>
+  </div>
+
+  <div class="row">
+    <label for="searchField">Search</label>
+    <input type="search" id="searchField" aria-label="Search" placeholder="type to filter" />
+  </div>
+
+  <div class="row">
+    <label>Results</label>
+    <!-- A scrollable list; used to exercise scroll + count asserts. -->
+    <div id="results" role="list" aria-label="Results"></div>
+  </div>
+
+  <div class="row">
+    <label><input type="checkbox" id="agree" aria-label="Agree" /> Agree to terms</label>
+    <div id="agreeState" role="status">agree: false</div>
+  </div>
+
+  <script>
+    const nameField = document.getElementById('nameField');
+    const statusLabel = document.getElementById('statusLabel');
+    nameField.addEventListener('input', () => {
+      const v = nameField.value;
+      statusLabel.textContent = v ? ('status: ' + v) : 'status: (none)';
+    });
+
+    let clicks = 0;
+    const clicksEl = document.getElementById('clicks');
+    document.getElementById('greetButton').addEventListener('click', () => {
+      clicks += 1;
+      clicksEl.textContent = 'clicks: ' + clicks;
+      statusLabel.textContent = 'status: greeted';
+    });
+
+    // Seed the results list, filtered by the search box.
+    const ALL = Array.from({ length: 12 }, (_, i) => 'Item ' + (i + 1));
+    const results = document.getElementById('results');
+    function renderResults(filter) {
+      const f = (filter || '').toLowerCase();
+      results.innerHTML = '';
+      for (const item of ALL) {
+        if (!f || item.toLowerCase().includes(f)) {
+          const el = document.createElement('div');
+          el.className = 'result';
+          el.setAttribute('role', 'listitem');
+          el.textContent = item;
+          results.appendChild(el);
+        }
+      }
+    }
+    renderResults('');
+    document.getElementById('searchField').addEventListener('input', (e) => {
+      renderResults(e.target.value);
+    });
+
+    const agree = document.getElementById('agree');
+    const agreeState = document.getElementById('agreeState');
+    agree.addEventListener('change', () => {
+      agreeState.textContent = 'agree: ' + agree.checked;
+    });
+  </script>
+</body>
+</html>