trawl-devices-agent 0.1.0

package/dist/sessions.js

@@ -0,0 +1,85 @@
+import { randomBytes } from "node:crypto";
+import { chromium, firefox, webkit, } from "playwright";
+import { AgentError } from "./types.js";
+const ENGINES = { chromium, firefox, webkit };
+/** Playwright context options derived from a device. */
+export function contextOptionsFor(device, trawlProxyPort) {
+    const proxy = device.proxy.mode === "trawl"
+        ? { server: `http://127.0.0.1:${trawlProxyPort}` }
+        : device.proxy.mode === "custom"
+            ? { server: device.proxy.url }
+            : undefined;
+    return {
+        ...(proxy ? { proxy } : {}),
+        ignoreHTTPSErrors: device.ignoreHTTPSErrors,
+        viewport: device.viewport,
+        ...(device.userAgent ? { userAgent: device.userAgent } : {}),
+        ...(device.locale ? { locale: device.locale } : {}),
+        ...(device.timezone ? { timezoneId: device.timezone } : {}),
+        ...(device.storageStateFile ? { storageState: device.storageStateFile } : {}),
+    };
+}
+export class SessionStore {
+    sessions = new Map();
+    async start(device, options = {}) {
+        const engine = ENGINES[device.browser];
+        const headless = options.headless ?? device.headless;
+        let browser;
+        try {
+            browser = await engine.launch({ headless });
+        }
+        catch (err) {
+            throw new AgentError("device", `failed to launch ${device.browser}: ${err.message}. ` +
+                `Install it with: pnpm exec playwright install ${device.browser}`);
+        }
+        const contextOptions = contextOptionsFor(device, options.trawlProxyPort ?? 8080);
+        if (device.video && options.videoDir)
+            contextOptions.recordVideo = { dir: options.videoDir };
+        const context = await browser.newContext(contextOptions);
+        const page = await context.newPage();
+        const live = {
+            sessionId: `s_${randomBytes(6).toString("hex")}`,
+            deviceId: device.id,
+            state: "idle",
+            startedAt: Date.now(),
+            currentUrl: null,
+            browser,
+            context,
+            page,
+        };
+        page.on("framenavigated", (frame) => {
+            if (frame === page.mainFrame())
+                live.currentUrl = frame.url();
+        });
+        this.sessions.set(live.sessionId, live);
+        return this.describe(live);
+    }
+    get(sessionId) {
+        const live = this.sessions.get(sessionId);
+        if (!live)
+            throw new AgentError("device", `unknown session: ${sessionId}`);
+        return live;
+    }
+    setState(sessionId, state) {
+        this.get(sessionId).state = state;
+    }
+    list() {
+        return [...this.sessions.values()].map((s) => this.describe(s));
+    }
+    async stop(sessionId) {
+        const live = this.sessions.get(sessionId);
+        if (!live)
+            return;
+        this.sessions.delete(sessionId);
+        await live.context.close().catch(() => { });
+        await live.browser.close().catch(() => { });
+    }
+    async stopAll() {
+        await Promise.all([...this.sessions.keys()].map((id) => this.stop(id)));
+    }
+    describe(live) {
+        const { sessionId, deviceId, state, startedAt, currentUrl } = live;
+        return { sessionId, deviceId, state, startedAt, currentUrl };
+    }
+}
+//# sourceMappingURL=sessions.js.map

package/dist/sessions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.js","sourceRoot":"","sources":["../src/sessions.ts"],"names":[],"mappings":"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"}

package/dist/steps.js

@@ -0,0 +1,27 @@
+/** The DSL vocabulary — the single source of truth. Bump DSL_VERSION when it changes. */
+export const STEP_NAMES = [
+    // setup
+    "device", "use",
+    // navigation
+    "goto", "back", "forward", "reload",
+    // actions
+    "click", "dblclick", "fill", "type", "press", "check", "uncheck",
+    "select", "hover", "upload", "drag", "scrollTo",
+    // waits
+    "waitFor", "waitForUrl", "waitForResponse", "sleep",
+    // UI assertions
+    "expectVisible", "expectHidden", "expectText", "expectValue",
+    "expectUrl", "expectCount", "expectAttr",
+    // HTTP assertions
+    "expectRequest", "expectResponse", "expectNoRequest",
+    // reads
+    "getText", "getValue", "getAttr", "getUrl", "count",
+    // misc
+    "step", "screenshot", "note",
+];
+/** Globals a script may call that are not steps. `secret` and `env` come from the run scope. */
+export const ALLOWED_GLOBALS = [
+    "console", "JSON", "Math", "Number", "String", "Boolean", "Array", "Object",
+    "Date", "RegExp", "parseInt", "parseFloat", "isNaN", "secret",
+];
+//# sourceMappingURL=steps.js.map

package/dist/steps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"steps.js","sourceRoot":"","sources":["../src/steps.ts"],"names":[],"mappings":"AAAA,yFAAyF;AACzF,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,QAAQ;IACR,QAAQ,EAAE,KAAK;IACf,aAAa;IACb,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ;IACnC,UAAU;IACV,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS;IAChE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU;IAC/C,QAAQ;IACR,SAAS,EAAE,YAAY,EAAE,iBAAiB,EAAE,OAAO;IACnD,gBAAgB;IAChB,eAAe,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa;IAC5D,WAAW,EAAE,aAAa,EAAE,YAAY;IACxC,kBAAkB;IAClB,eAAe,EAAE,gBAAgB,EAAE,iBAAiB;IACpD,QAAQ;IACR,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO;IACnD,OAAO;IACP,MAAM,EAAE,YAAY,EAAE,MAAM;CACpB,CAAC;AAIX,gGAAgG;AAChG,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ;IAC3E,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ;CACrD,CAAC"}

package/dist/targets.js

@@ -0,0 +1,68 @@
+import { AgentError } from "./types.js";
+export const isRegexSpec = (v) => typeof v === "object" && v !== null && "__regex" in v;
+/**
+ * `instanceof RegExp` lies across realms, and scripts run inside `node:vm` —
+ * their regexes come from a different realm than ours.
+ */
+export const isRegExp = (v) => Object.prototype.toString.call(v) === "[object RegExp]";
+/**
+ * A script may pass a RegExp; JSON transport passes {__regex:{source,flags}}.
+ * Foreign-realm regexes are rebuilt here so Playwright's own `instanceof`
+ * checks recognise them.
+ */
+export function toMatcher(value) {
+    if (isRegexSpec(value))
+        return new RegExp(value.__regex.source, value.__regex.flags);
+    if (isRegExp(value)) {
+        // Rebuild only when it comes from another realm; TS cannot see that
+        // distinction, so the source/flags are read off a plain alias.
+        const foreign = value;
+        return value instanceof RegExp ? value : new RegExp(foreign.source, foreign.flags);
+    }
+    return value;
+}
+export function toLocator(scope, target) {
+    const base = target.within ? toLocator(scope, target.within) : scope;
+    let loc;
+    if (target.testId !== undefined)
+        loc = base.getByTestId(target.testId);
+    else if (target.role !== undefined) {
+        loc = base.getByRole(target.role, target.name === undefined ? undefined : { name: toMatcher(target.name) });
+    }
+    else if (target.label !== undefined)
+        loc = base.getByLabel(toMatcher(target.label));
+    else if (target.placeholder !== undefined)
+        loc = base.getByPlaceholder(toMatcher(target.placeholder));
+    else if (target.text !== undefined)
+        loc = base.getByText(toMatcher(target.text));
+    else if (target.css !== undefined)
+        loc = base.locator(target.css);
+    else
+        throw new AgentError("script", `empty target: ${JSON.stringify(target)}`);
+    return target.nth === undefined ? loc : loc.nth(target.nth);
+}
+const show = (v) => isRegexSpec(v) ? `/${v.__regex.source}/${v.__regex.flags}` : isRegExp(v) ? String(v) : JSON.stringify(v);
+/** Human-readable target, used in assertion and timeout messages. */
+export function describeTarget(target) {
+    const parts = [];
+    if (target.testId !== undefined)
+        parts.push(`testId=${target.testId}`);
+    if (target.role !== undefined)
+        parts.push(`role=${target.role}`);
+    if (target.name !== undefined)
+        parts.push(`name=${show(target.name)}`);
+    if (target.label !== undefined)
+        parts.push(`label=${show(target.label)}`);
+    if (target.placeholder !== undefined)
+        parts.push(`placeholder=${show(target.placeholder)}`);
+    if (target.text !== undefined)
+        parts.push(`text=${show(target.text)}`);
+    if (target.css !== undefined)
+        parts.push(`css=${target.css}`);
+    if (target.within !== undefined)
+        parts.push(`in(${describeTarget(target.within)})`);
+    if (target.nth !== undefined)
+        parts.push(`[${target.nth}]`);
+    return parts.join(" ");
+}
+//# sourceMappingURL=targets.js.map

package/dist/targets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"targets.js","sourceRoot":"","sources":["../src/targets.ts"],"names":[],"mappings":"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"}

package/dist/traffic.js

@@ -0,0 +1,116 @@
+import { AgentError } from "./types.js";
+const METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
+export function parseMatcher(input) {
+    if (typeof input !== "string") {
+        const { method, host, path, url } = input;
+        return {
+            ...(method ? { method: method.toUpperCase() } : {}),
+            ...(host ? { host } : {}),
+            ...(path ? { path } : {}),
+            ...(url ? { urlPart: url } : {}),
+        };
+    }
+    const [head, ...rest] = input.trim().split(/\s+/);
+    if (head && METHODS.includes(head.toUpperCase()) && rest.length) {
+        return { method: head.toUpperCase(), urlPart: rest.join(" ") };
+    }
+    return { urlPart: input.trim() };
+}
+export function matchesObserved(o, m) {
+    if (m.method && o.method.toUpperCase() !== m.method)
+        return false;
+    if (m.urlPart && !o.url.includes(m.urlPart))
+        return false;
+    if (m.host || m.path) {
+        let parsed;
+        try {
+            parsed = new URL(o.url);
+        }
+        catch {
+            return false;
+        }
+        if (m.host && parsed.host !== m.host)
+            return false;
+        if (m.path && parsed.pathname !== m.path)
+            return false;
+    }
+    return true;
+}
+export const describeMatcher = (m) => [m.method, m.urlPart, m.host, m.path].filter(Boolean).join(" ");
+export class TrafficBuffer {
+    seen = [];
+    waiters = [];
+    observe(o) {
+        const waiterIndex = this.waiters.findIndex((w) => matchesObserved(o, w.matcher));
+        if (waiterIndex >= 0) {
+            const [waiter] = this.waiters.splice(waiterIndex, 1);
+            o.consumed = true;
+            this.seen.push(o);
+            waiter.resolve(o);
+            return;
+        }
+        this.seen.push(o);
+    }
+    /** First unconsumed match, waiting up to `timeoutMs` for one to arrive. */
+    async consume(matcher, timeoutMs) {
+        const existing = this.seen.find((o) => !o.consumed && matchesObserved(o, matcher));
+        if (existing) {
+            existing.consumed = true;
+            return existing;
+        }
+        return new Promise((resolve, reject) => {
+            const waiter = { matcher, resolve };
+            this.waiters.push(waiter);
+            const timer = setTimeout(() => {
+                const at = this.waiters.indexOf(waiter);
+                if (at < 0)
+                    return;
+                this.waiters.splice(at, 1);
+                reject(new AgentError("assertion", `no request matched ${describeMatcher(matcher)} within ${timeoutMs}ms`, {
+                    expected: describeMatcher(matcher),
+                    actual: "no matching request",
+                }));
+            }, timeoutMs);
+            timer.unref?.();
+        });
+    }
+    seenSince(step, matcher) {
+        return this.seen.filter((o) => o.step >= step && matchesObserved(o, matcher));
+    }
+    all() {
+        return this.seen;
+    }
+    /** Marker headers + response observation. Returns a detach function. */
+    static async attach(context, runId, getStep, buffer) {
+        // The step is fixed when the request goes out, not when the response comes
+        // back — otherwise attribution would disagree with the marker header the
+        // plugin correlates on.
+        const stepOfRequest = new WeakMap();
+        await context.route("**", async (route) => {
+            const step = getStep();
+            stepOfRequest.set(route.request(), step);
+            await route
+                .continue({
+                headers: { ...route.request().headers(), "x-trawl-run": runId, "x-trawl-step": String(step) },
+            })
+                .catch(() => { });
+        });
+        const onResponse = (response) => {
+            buffer.observe({
+                method: response.request().method(),
+                url: response.url(),
+                status: response.status(),
+                step: stepOfRequest.get(response.request()) ?? getStep(),
+                ts: Date.now(),
+                consumed: false,
+                responseBody: () => response.text().catch(() => null),
+            });
+        };
+        context.on("response", onResponse);
+        return async () => {
+            context.off("response", onResponse);
+            await context.unroute("**").catch(() => { });
+        };
+    }
+}
+//# sourceMappingURL=traffic.js.map

package/dist/traffic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"traffic.js","sourceRoot":"","sources":["../src/traffic.ts"],"names":[],"mappings":"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"}

package/dist/transform.js

@@ -0,0 +1,110 @@
+import { parse } from "acorn";
+import { ancestor, simple } from "acorn-walk";
+import { AgentError } from "./types.js";
+export function parseScript(code) {
+    try {
+        return parse(code, {
+            ecmaVersion: "latest",
+            sourceType: "script",
+            allowAwaitOutsideFunction: true,
+            allowReturnOutsideFunction: true,
+        });
+    }
+    catch (err) {
+        throw new AgentError("script", `syntax error: ${err.message}`);
+    }
+}
+const FUNCTIONS = new Set(["FunctionDeclaration", "FunctionExpression", "ArrowFunctionExpression"]);
+/**
+ * Where `async` has to go for a function to become async. Method shorthand
+ * (`{ foo() {} }`, `class { foo() {} }`) needs it before the key, not before
+ * the value's parameter list.
+ */
+function asyncInsertPoint(fn, parent) {
+    const p = parent;
+    if (p && (p.type === "Property" || p.type === "MethodDefinition") && p.value === fn && p.key) {
+        return p.key.start;
+    }
+    return fn.start;
+}
+const calleeName = (node) => node.callee.type === "Identifier" ? node.callee.name : null;
+/**
+ * Insert `await` before every bare call to a known step name, and mark the
+ * enclosing function `async` when it isn't already — otherwise an awaited step
+ * inside a callback like `step('name', () => { … })` is a syntax error.
+ */
+export function addAwaits(code, stepNames) {
+    const ast = parseScript(code);
+    const names = new Set(stepNames);
+    const inserts = new Map();
+    ancestor(ast, {
+        CallExpression(node, _state, ancestors) {
+            const name = calleeName(node);
+            if (!name || !names.has(name))
+                return;
+            const parent = ancestors[ancestors.length - 2];
+            if (parent?.type === "AwaitExpression")
+                return;
+            inserts.set(node.start, "await ");
+            // The nearest enclosing function must be async for that await to be legal.
+            for (let i = ancestors.length - 2; i >= 0; i--) {
+                const fn = ancestors[i];
+                if (!FUNCTIONS.has(fn.type))
+                    continue;
+                if (!fn.async) {
+                    inserts.set(asyncInsertPoint(fn, ancestors[i - 1]), "async ");
+                }
+                break;
+            }
+        },
+    });
+    let out = code;
+    for (const at of [...inserts.keys()].sort((a, b) => b - a)) {
+        out = out.slice(0, at) + inserts.get(at) + out.slice(at);
+    }
+    return out;
+}
+/** True when the step list produced by collect mode can only be approximate. */
+export function hasBranching(code) {
+    const ast = parseScript(code);
+    let found = false;
+    const mark = () => {
+        found = true;
+    };
+    simple(ast, {
+        IfStatement: mark,
+        ForStatement: mark,
+        ForOfStatement: mark,
+        ForInStatement: mark,
+        WhileStatement: mark,
+        DoWhileStatement: mark,
+        SwitchStatement: mark,
+        ConditionalExpression: mark,
+        LogicalExpression: mark,
+    });
+    return found;
+}
+/** Bare calls that are not steps, not locally defined, and not allowed globals. */
+export function unknownCalls(code, stepNames, allowedGlobals) {
+    const ast = parseScript(code);
+    const known = new Set([...stepNames, ...allowedGlobals]);
+    const declared = new Set();
+    const called = new Set();
+    const declare = (node) => {
+        if (node.type === "FunctionDeclaration" && node.id)
+            declared.add(node.id.name);
+        if (node.type === "VariableDeclarator" && node.id.type === "Identifier")
+            declared.add(node.id.name);
+    };
+    simple(ast, {
+        FunctionDeclaration: declare,
+        VariableDeclarator: declare,
+        CallExpression(node) {
+            const name = calleeName(node);
+            if (name)
+                called.add(name);
+        },
+    });
+    return [...called].filter((name) => !known.has(name) && !declared.has(name));
+}
+//# sourceMappingURL=transform.js.map

package/dist/transform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform.js","sourceRoot":"","sources":["../src/transform.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,12 @@
+/** An error with a kind the plugin and the report can branch on. */
+export class AgentError extends Error {
+    kind;
+    detail;
+    constructor(kind, message, detail) {
+        super(message);
+        this.kind = kind;
+        this.detail = detail;
+        this.name = "AgentError";
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAEA,oEAAoE;AACpE,MAAM,OAAO,UAAW,SAAQ,KAAK;IAExB;IAEA;IAHX,YACW,IAAe,EACxB,OAAe,EACN,MAA+C;QAExD,KAAK,CAAC,OAAO,CAAC,CAAC;QAJN,SAAI,GAAJ,IAAI,CAAW;QAEf,WAAM,GAAN,MAAM,CAAyC;QAGxD,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF"}

package/dist/version.js

@@ -0,0 +1,5 @@
+/** Package version, reported by /health. */
+export const AGENT_VERSION = "0.1.0";
+/** Bumped whenever STEP_NAMES changes, so the plugin can demand an update. */
+export const DSL_VERSION = 1;
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,MAAM,CAAC,MAAM,aAAa,GAAG,OAAO,CAAC;AACrC,8EAA8E;AAC9E,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC"}

package/dist/workspace.js

@@ -0,0 +1,50 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { AgentError } from "./types.js";
+/** Resolve `rel` under `root`, refusing anything that escapes it. */
+export function resolveInWorkspace(root, rel) {
+    const normRoot = path.resolve(root);
+    const abs = path.resolve(normRoot, rel);
+    if (abs !== normRoot && !abs.startsWith(normRoot + path.sep)) {
+        throw new AgentError("script", `path escapes workspace: ${rel}`);
+    }
+    return abs;
+}
+export const scriptsDir = (root) => path.join(path.resolve(root), "scripts");
+export const runsDir = (root) => path.join(path.resolve(root), "runs");
+export const runDir = (root, runId) => path.join(runsDir(root), runId);
+export async function ensureWorkspace(root) {
+    await fs.mkdir(scriptsDir(root), { recursive: true });
+    await fs.mkdir(runsDir(root), { recursive: true });
+}
+export async function readScript(root, rel) {
+    return fs.readFile(resolveInWorkspace(root, rel), "utf8");
+}
+export async function writeScript(root, rel, code) {
+    const abs = resolveInWorkspace(root, rel);
+    await fs.mkdir(path.dirname(abs), { recursive: true });
+    await fs.writeFile(abs, code, "utf8");
+}
+/** Every `.js` under scripts/, as workspace-relative paths. */
+export async function listScripts(root) {
+    const out = [];
+    const walk = async (dir) => {
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const abs = path.join(dir, e.name);
+            if (e.isDirectory())
+                await walk(abs);
+            else if (e.name.endsWith(".js"))
+                out.push(path.relative(path.resolve(root), abs));
+        }
+    };
+    await walk(scriptsDir(root));
+    return out;
+}
+//# sourceMappingURL=workspace.js.map

package/dist/workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "trawl-devices-agent",
+  "version": "0.1.0",
+  "description": "Local sidecar for the Trawl devices plugin — records and replays browser scenarios with Playwright.",
+  "type": "module",
+  "bin": {
+    "trawl-devices-agent": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "author": "legostin",
+  "homepage": "https://github.com/legostin/trawl-devices-agent#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/legostin/trawl-devices-agent.git"
+  },
+  "bugs": {
+    "url": "https://github.com/legostin/trawl-devices-agent/issues"
+  },
+  "keywords": [
+    "trawl",
+    "playwright",
+    "testing",
+    "browser-automation",
+    "record-and-replay",
+    "mcp"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "start": "node dist/index.js",
+    "prepublishOnly": "pnpm build"
+  },
+  "dependencies": {
+    "acorn": "^8.17.0",
+    "acorn-walk": "^8.3.5",
+    "playwright": "^1.62.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "~5.8.3",
+    "vitest": "^3.2.4"
+  }
+}

package/skills/writing-device-scripts/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: writing-device-scripts
+description: Use when writing or editing Trawl device scripts — the declarative JS DSL recorded and replayed by trawl-devices-agent.
+---
+
+# Writing device scripts
+
+A device script is a plain `.js` file made of flat step calls. It is **not**
+Playwright code: do not write `page.` anything, do not write `await`, do not
+import anything.
+
+```js
+device('chrome-desktop')
+use({ baseUrl: '{{BASE_URL}}', timeout: 15000 })
+
+goto('/login')
+fill({ label: 'Email' }, '{{USER}}')
+fill({ label: 'Пароль' }, secret('PWD'))
+click({ role: 'button', name: 'Войти' })
+expectResponse('POST /api/login', { status: 200, jsonPath: { '$.token': /^ey/ } })
+expectUrl('**/dashboard')
+expectText({ testId: 'greeting' }, /Привет/)
+```
+
+## Targets
+
+Prefer, in order: `{ testId }`, `{ role, name }`, `{ label }`, `{ placeholder }`,
+`{ text }`, `{ css }`. Narrow with `within` and `nth`:
+
+```js
+click({ role: 'row', name: 'Заказ 42', within: { testId: 'orders' } })
+```
+
+## Steps
+
+- Navigation: `goto`, `back`, `forward`, `reload`
+- Actions: `click`, `dblclick`, `fill`, `type`, `press`, `check`, `uncheck`,
+  `select`, `hover`, `upload`, `drag`, `scrollTo`
+- Waits: `waitFor(target, 'visible'|'hidden'|'attached')`, `waitForUrl`,
+  `waitForResponse`, `sleep`
+- UI assertions: `expectVisible`, `expectHidden`, `expectText`, `expectValue`,
+  `expectUrl`, `expectCount`, `expectAttr`
+- HTTP assertions: `expectRequest`, `expectResponse`, `expectNoRequest`
+- Reads: `getText`, `getValue`, `getAttr`, `getUrl`, `count`
+- Misc: `step(name, fn)`, `screenshot(name)`, `note(text)`
+
+## Rules
+
+1. **No `await`.** The runner inserts it. Reads return real values:
+   `const title = getText({ css: 'h1' })`.
+2. **`{{VAR}}`** comes from the Trawl project env; an unknown name fails the run.
+   **`secret('NAME')`** reads the Keychain — never paste a literal password.
+3. **Prefer assertions over `sleep`.** Every step already auto-waits.
+4. **Group with `step('name', () => { … })`** — the report shows the group name.
+5. **HTTP matchers are a method plus a URL substring** (`'POST /api/login'`), or
+   an object (`{ method, host, path }`). Each `expectResponse` consumes the
+   first matching response not yet consumed, waiting up to the timeout.
+6. **A failing step ends the run.** Steps after it never execute, so they do not
+   appear in the report.