decisium 0.0.0-stage → 0.1.2

package/dist/runner.js

@@ -0,0 +1,282 @@
+import { readStep } from "./step.js";
+import { capabilities, gate, GATE_TARGET_MARGIN, GATE_TARGET_TOP, grouped, NotYet, named, fmt, PAGE } from "./decision.js";
+import { verdict as checkVerdict } from "./check.js";
+import { changes } from "./change.js";
+import { MASK } from "./observation.js";
+/** `ask` on `obs`, re-observing after each change while it throws NotYet. */
+async function settled(rt, obs, ask) {
+    const deadline = Date.now() + ASSERT_TIMEOUT_MS;
+    for (;;) {
+        try {
+            return [obs, await ask(obs)];
+        }
+        catch (err) {
+            if (!(err instanceof NotYet))
+                throw err;
+            const left = deadline - Date.now();
+            if (left <= 0 || !(await rt.waitForChange(obs.text, left)))
+                throw err.final;
+            obs = await rt.observe();
+        }
+    }
+}
+const MAX_TURNS = 8;
+const TOGGLES = new Set(["checkbox", "switch", "menuitemcheckbox"]);
+/** Jev torn between "nothing to do" and a toggle already in the wanted state (task 0043): both mean done. */
+function alreadyToggled(pick, obs, goal) {
+    const done = (c) => c === "none" || obs.elements.some(e => e.ref === c && toggled(e, goal));
+    if (!Object.entries(pick.probabilities).some(([c, p]) => c !== "none" && p >= 0.1 && done(c)))
+        return false;
+    const merged = {};
+    for (const [c, p] of Object.entries(pick.probabilities))
+        merged[done(c) ? "none" : c] = (merged[done(c) ? "none" : c] ?? 0) + p;
+    return gate({ choice: "none", probabilities: merged }, GATE_TARGET_TOP, GATE_TARGET_MARGIN)
+        && Object.entries(merged).every(([c, p]) => c === "none" || p < merged.none);
+}
+/** An element like `el` (role, name or text) inside a named element like `to` on `obs`; unnamed targets cannot be told apart. */
+function landed(obs, el, to) {
+    if (!to.name)
+        return false;
+    const id = (e) => `${e.role}|${e.name || e.value}`;
+    return obs.elements.some(e => {
+        if (id(e) !== id(el))
+            return false;
+        for (let p = e.parent; p; p = p.parent)
+            if (p.role === to.role && p.name === to.name)
+                return true;
+        return false;
+    });
+}
+/** The element is a toggle in the Step's wanted state, or a checked radio (radios cannot be unchecked). */
+const toggled = (e, goal) => goal !== undefined
+    && (TOGGLES.has(e.role) || e.role === "radio" && goal) && /\[checked\]/.test(e.state) === goal;
+/** The browser Action for each target action (decision.ts ACTIONS); `press <key>` is PRESS. */
+const VERBS = { click: "CLICK", type: "TYPE", select: "SELECT", upload: "UPLOAD", paste: "PASTE",
+    hover: "HOVER", "double click": "DBLCLICK", "right click": "RIGHTCLICK", drag: "DRAG", "scroll down": "SCROLL", "scroll up": "SCROLL_UP",
+    wait: "WAIT", back: "BACK", forward: "FORWARD", reload: "RELOAD", "close tab": "CLOSE_TAB", "switch tab": "SWITCH_TAB", enter: "ENTER" };
+const ASSERT_TIMEOUT_MS = 5000; // total time an Assertion step may wait for the UI to reach the expected state
+const DONE_THRESHOLD = 0.8;
+/**
+ * After an action that changed the page, "nothing left to do" is evidence too: with it, done needs only this much
+ * (task 0007). In the corpus every such Turn with done >= 0.5 was a real success (SauceDemo cart 0.58-0.77).
+ */
+const DONE_AFTER_ACTION = 0.5;
+/**
+ * Jev classifies the check and picks the element it is about; code decides pass/fail.
+ * `judged` opts in to fuzzy checks, which Jev answers directly and are reported as JUDGED_*, never PASSED.
+ */
+/**
+ * `earlier`: quoted values from this scenario's earlier Steps (value -> Step), for checks that quote none.
+ * `arg`: a doc string is one more quoted value; a one-column table is a list of values that must all be shown, a wider
+ * one is matched row by row to the page table under its column headers.
+ */
+export async function runAssertion(step, rt, decider, log = console.log, judged = false, earlier = {}, arg = {}) {
+    const { label: said, values, list, exact } = readStep({ text: step, kind: "assertion", ...arg }); // said: what Jev reads, with the table or doc string
+    log(`\nAssert: ${said}`);
+    const end = finish(log);
+    const { table } = arg;
+    if (table && !list && table.length < 2)
+        return end("UNVERIFIABLE", "the table has only its header row (a check's first row names the columns), so there is no row to compare");
+    let recallNote = "";
+    let recall;
+    if (!values.length && !table && Object.keys(earlier).length) {
+        const r = await decider.recall(said, earlier);
+        log(`  Recall: ${fmt(r)}`);
+        if (gate(r) && r.choice !== "none") {
+            values.push(r.choice);
+            recall = r;
+        }
+        else
+            recallNote = `; Jev could not tell which earlier value it refers to (${named(r)})`;
+    }
+    // Like Playwright's expect: a check that does not pass is re-evaluated whenever the UI changes, until
+    // the UI stops changing within the wait cap. Jev is asked again only after a change.
+    const deadline = Date.now() + ASSERT_TIMEOUT_MS;
+    let obs = await rt.observe();
+    for (;;) {
+        let verdict;
+        [obs, verdict] = await settled(rt, obs, check);
+        const final = ["PASSED", "JUDGED_PASSED", "UNVERIFIABLE"].includes(verdict.outcome);
+        const left = deadline - Date.now();
+        if (verdict.outcome === "UNVERIFIABLE")
+            verdict.reason += recallNote;
+        if (final || left <= 0)
+            return end(verdict.outcome, verdict.reason, verdict.marginal);
+        log("  (not passed yet; waiting for the UI to change)");
+        if (!(await rt.waitForChange(obs.text, left)))
+            return end(verdict.outcome, verdict.reason);
+        obs = await rt.observe();
+    }
+    async function check(obs) {
+        const a = await decider.assess(said, obs, judged);
+        const result = checkVerdict(a, obs, { values, table, list, exact, recall });
+        for (const line of result.details)
+            log(line);
+        return result;
+    }
+}
+const finish = (log) => (outcome, reason, weak = []) => {
+    const marginal = weak.length ? weak.join("; ") : undefined;
+    log(`  => ${outcome}${reason ? `: ${reason}` : ""}${marginal ? ` (marginal: ${marginal})` : ""}`);
+    return { outcome, reason, ...(marginal ? { marginal } : {}) };
+};
+/**
+ * Action or Attempt step. An Attempt is done once its actions are performed, even if the app rejects them.
+ * `docString`: one more value to type, read by Jev with the Step.
+ */
+export async function runStep(step, rt, decider, log = console.log, attempt = false, docString) {
+    return rt.actionStep(() => act(step, rt, decider, log, attempt, docString), log);
+}
+/**
+ * How to answer the open dialog: Cancel unless Jev is sure the Step means OK (or one of its quoted values, for a
+ * prompt). An alert, or a prompt the Step quotes nothing for, has no other answer, so Jev is not asked.
+ */
+async function answerDialog(dialog, said, values, obs, decider, log) {
+    const answers = dialog.type === "alert" ? [] : dialog.type === "prompt" ? values : ["accept"];
+    if (!answers.length)
+        return { verb: "DISMISS" };
+    const p = await decider.dialog(said, obs, [...answers, "dismiss"]);
+    log(`  Dialog answer: ${fmt(p)}`);
+    if (!gate(p) || p.choice === "dismiss")
+        return { verb: "DISMISS" };
+    return dialog.type === "prompt" ? { verb: "ACCEPT", value: p.choice } : { verb: "ACCEPT" };
+}
+async function act(step, rt, decider, log, attempt, docString) {
+    const read = readStep({ text: step, kind: "action", docString });
+    const said = read.label;
+    log(`\n${attempt ? "Attempt" : "Step"}: ${said}`);
+    const end = finish(log);
+    // Only "press X" or "go back" / "go to /x": nothing to choose, so code does it and the following checks verify the
+    // effect (tasks 0039, 0041).
+    const only = read.pressOnly ? { verb: "PRESS", value: read.pressOnly } : read.navigation;
+    if (only) {
+        const described = `${only.verb}${only.value === undefined ? "" : ` ${only.value}`}`;
+        log(`  Execute: ${described}`);
+        try {
+            await rt.execute(only);
+        }
+        catch (err) {
+            return end("ACTION_FAILED", `${described} failed: ${err.message.split("\n")[0]}`);
+        }
+        return end("DONE");
+    }
+    const recent = []; // this Step's actions, sent to Jev so it knows what it already did
+    let unchanged = 0;
+    let obs = await rt.observe();
+    for (let turn = 1; turn <= MAX_TURNS; turn++) {
+        log(`\n  Observation #${turn}:`);
+        for (const e of obs.elements)
+            log(`    [${e.ref}] ${e.line}`);
+        // An open dialog blocks the page: this Turn answers it, nothing else.
+        if (obs.dialog?.state === "open") {
+            const action = await answerDialog(obs.dialog, said, read.values, obs, decider, log);
+            const described = `${action.verb} ${obs.dialog.type} "${obs.dialog.message}"${action.value === undefined ? "" : ` <- "${action.value}"`}`;
+            log(`  Execute: ${described}`);
+            try {
+                await rt.execute(action);
+            }
+            catch (err) {
+                return end("ACTION_FAILED", `${described} failed: ${err.message.split("\n")[0]}`);
+            }
+            recent.push(described);
+            obs = await rt.observe();
+            unchanged = 0;
+            continue;
+        }
+        let t;
+        [obs, t] = await settled(rt, obs, o => decider.turn(said, o, recent, attempt, read.keys));
+        t = { ...t, target: grouped(t.target, obs) }; // equivalent links count as one (task 0065)
+        log(`  Decision: done=${t.done.toFixed(2)}${t.action ? ` action: ${fmt(t.action)}` : ""} target: ${fmt(t.target)}`);
+        if (t.done >= DONE_THRESHOLD)
+            return end("DONE");
+        if (recent.length && unchanged === 0 && t.target.choice === "none" && t.done >= DONE_AFTER_ACTION)
+            return end("DONE");
+        if (alreadyToggled(t.target, obs, read.toggle)) {
+            log("  Toggle: already done");
+            return end("DONE");
+        }
+        if (!gate(t.target, GATE_TARGET_TOP, GATE_TARGET_MARGIN))
+            return end("AMBIGUOUS", `Jev is unsure what to do next: ${named(t.target, obs)}`);
+        if (t.target.choice === "none")
+            return end("BLOCKED", "nothing on this screen helps do the step");
+        const el = t.target.choice === PAGE ? undefined : obs.elements.find(e => e.ref === t.target.choice);
+        if (t.target.choice !== PAGE && !el)
+            return end("ELEMENT_NOT_FOUND", `Jev chose an element that is no longer on the page (${t.target.choice})`);
+        // The likeliest action the target can do; not gated (task 0065: restricted, the right one can be far below 0.5).
+        const can = capabilities(el ?? PAGE, obs, read.keys);
+        const how = !t.action ? can[0] : Object.entries(t.action.probabilities).filter(([a]) => can.includes(a)).sort((a, b) => b[1] - a[1])[0]?.[0];
+        // Only a recorded answer can miss (live answers rate every action): it was not offered this Turn.
+        if (!how)
+            return end("ELEMENT_NOT_FOUND", `Jev chose ${t.action?.choice} on ${el?.line ?? "the page"}, which is not offered now`);
+        const key = /^press (.+)$/.exec(how)?.[1];
+        let action;
+        let described;
+        let dropOn;
+        if (!el) {
+            action = key ? { verb: "PRESS", value: key } : { verb: VERBS[how] };
+            described = key ? `PRESS ${key}` : action.verb;
+        }
+        else {
+            if (el.verb === "CLICK" && toggled(el, read.toggle)) {
+                log(`  Toggle: already ${el.line}`);
+                return end("DONE");
+            }
+            action = { verb: VERBS[how], ref: el.ref };
+            let onto = "";
+            if (action.verb === "DRAG") {
+                const d = await decider.drop(said, obs, el);
+                log(`  Drop: ${fmt(d)}`);
+                if (!gate(d, GATE_TARGET_TOP, GATE_TARGET_MARGIN) || d.choice === "none")
+                    return end("AMBIGUOUS", `Jev is unsure where to drop ${el.line}: ${named(d, obs)}`);
+                action.to = d.choice;
+                const to = dropOn = [...obs.readable, ...obs.areas].find(e => e.ref === d.choice);
+                onto = ` onto ${to.role} "${to.name || to.value.slice(0, 60)}"`;
+            }
+            if (action.verb === "TYPE" || action.verb === "SELECT" || action.verb === "UPLOAD") {
+                // A file to upload is only ever one the Step quotes (task 0044).
+                const candidates = el.verb === "SELECT" ? el.options : action.verb === "UPLOAD" ? read.quoted : read.candidates;
+                if (!candidates.length)
+                    return end("AMBIGUOUS", `the step gives no value to enter into ${el.line}; quote it (e.g. enter "Winter Sale")`);
+                // A clear Step that quotes nothing allows only "": no question (task 0067: Jev's "" 79% missed the gate).
+                const v = candidates.length === 1 && candidates[0] === "" && action.verb === "TYPE" ? { choice: "", probabilities: { "": 1 } }
+                    : await decider.value(said, obs, el, candidates);
+                log(`  Value: ${el.secret ? "(secret)" : fmt(v)}`);
+                if (!gate(v) || v.choice === "none")
+                    return end("AMBIGUOUS", `Jev is unsure which value to enter into ${el.line}${el.secret ? "" : `: ${named(v)}`}`);
+                action.value = v.choice;
+            }
+            const shown = action.value === undefined ? "" : ` <- "${el.secret ? MASK : action.value}"`;
+            described = `${action.verb} ${el.role} "${el.name || el.value.slice(0, 60)}"${shown}${onto}`;
+        }
+        // The page moved on its own since the Turn's Observation: diff from now, so that change is not the action's.
+        const before = await rt.stale?.() ? await rt.observe() : obs;
+        log(`  Execute: ${described}`);
+        try {
+            await rt.execute(action);
+        }
+        catch (err) {
+            return end("ACTION_FAILED", `${described} failed: ${err.message.split("\n")[0]}`);
+        }
+        const next = await rt.observe();
+        // What the action changed, for Jev's next `done` (task 0066: under-confident after working actions).
+        const effect = changes(before, next, action.ref);
+        log(`  Effect: ${effect}`);
+        recent.push(`${described} -> ${effect}`);
+        // Drag effect check (task 0065): Jev's done stayed 0.57-0.73 with the item shown in its new list, any wording.
+        if (action.verb === "DRAG" && el && dropOn && !landed(obs, el, dropOn) && landed(next, el, dropOn)) {
+            log(`  Drag: ${el.line} is now in ${dropOn.role} "${dropOn.name}"`);
+            return end("DONE");
+        }
+        const box = action.verb === "CLICK" ? next.elements.find(e => e.ref === action.ref && toggled(e, read.toggle)) : undefined;
+        if (box) {
+            log(`  Toggle: ${box.line}`);
+            return end("DONE");
+        }
+        // By the effect, not the raw text: focus alone ([active]) is no change (task 0067, false DONE on the hover menu).
+        unchanged = effect === "no visible change" ? unchanged + 1 : 0;
+        if (unchanged >= 2)
+            return end("BLOCKED", `the page did not change after two actions (last: ${described})`);
+        obs = next;
+    }
+    return end("STEP_TIMEOUT", `not done after ${MAX_TURNS} actions (${recent.join(", ")})`);
+}

package/dist/step.d.ts

@@ -0,0 +1,55 @@
+import { PickleStepType } from "@cucumber/messages";
+export type StepKind = "action" | "attempt" | "assertion";
+/** A Step's Gherkin argument: a data table (rows of cells) or a doc string. */
+export interface StepArgument {
+    table?: string[][];
+    docString?: string;
+}
+export interface ParsedStep extends StepArgument {
+    text: string;
+    kind: StepKind;
+    line?: number;
+}
+export interface StepReading {
+    /** The Step as reports and cassette keys show it: the table compactly, e.g. `[First name=Ada, Last name=Lovelace]`. */
+    label: string;
+    /** What runs: an Action step's Data table as one Step per row (none for a header alone), else the text. */
+    rows: string[];
+    /** Double-quoted strings in the text. Single quotes are left alone so apostrophes ("campaign's") don't open a quote. */
+    quoted: string[];
+    /** Quoted values and the Doc string; for a check also its one-column table: what it compares, or a prompt can answer. */
+    values: string[];
+    /** Candidate values an Action step can type: quoted strings, numbers with an optional unit word, the Doc string; clear/empty adds "". */
+    candidates: string[];
+    /** Named keys after "press" or "hit", as Playwright names them, one per verb. Actions only. */
+    keys: string[];
+    /** What the Step means as a key (a `+` combination, or "the X key") but is not a key name; never pressed. */
+    unknownKeys: string[];
+    /** The key of a Step that is only "press X" (`I press Escape`, `hit the "Tab" key`). */
+    pressOnly?: string;
+    /** A Step that is only "go back", "go forward", "reload the page" or "go to <URL or path>" (task 0041). */
+    navigation?: Navigation;
+    /** A Step that only checks (true) or unchecks (false) one box; "and"/"then" mean more to do. */
+    toggle?: boolean;
+    /** A check of rows "exactly" or "in this order". */
+    exact: boolean;
+    /** The table's first row is a header: a check with 2+ columns, an action with 3+. */
+    header: boolean;
+    /** A check's one-column table: a list of values that must all be shown. */
+    list: boolean;
+    /** The `"$NAME"` Secret placeholders: quoted, as the Doc string, or as a table cell. */
+    placeholders: string[];
+    /** An action's table cell that cannot become a quoted value (rows): empty gives none, a `"` splits it in two. */
+    badCell?: string;
+}
+export declare function readStep(step: ParsedStep): StepReading;
+export declare const stepKind: (step: {
+    text: string;
+    type?: PickleStepType;
+}) => StepKind;
+/** A quoted `"$NAME"` is a secret placeholder (task 0030): the variable's name, else undefined. */
+export declare const placeholder: (value: string) => string | undefined;
+export interface Navigation {
+    verb: "GOTO" | "BACK" | "FORWARD" | "RELOAD" | "CLOSE_TAB" | "SWITCH_TAB";
+    value?: string;
+}

package/dist/step.js

@@ -0,0 +1,126 @@
+// The Step language (task 0052): what a Step's text, Data table and Doc string mean to the runtime, read in one place.
+// The runner, Jev's questions, lint, reports and cassette keys all read a Step through readStep().
+import { PickleStepType } from "@cucumber/messages";
+export function readStep(step) {
+    const { text, kind, table, docString } = step;
+    const isCheck = kind === "assertion";
+    const header = !!table && table[0].length > (isCheck ? 1 : 2);
+    const list = isCheck && !!table && !header;
+    const quotedText = quoted(text);
+    const withDoc = docString === undefined ? quotedText : [...quotedText, docString];
+    const numbers = [...text.matchAll(/\b\d+(?:[.,]\d+)?(?:\s+[a-z]+)?/gi)].map(m => m[0]);
+    const { keys, unknown } = isCheck ? { keys: [], unknown: [] } : stepKeys(text);
+    const clear = !isCheck && /\b(clear|empty)\b/i.test(text.replace(/["“][^"”]*["”]/g, ""));
+    return {
+        label: label(text, table, docString, header),
+        rows: table && !isCheck ? tableSteps(text, table, header) : [text],
+        quoted: quotedText,
+        values: list ? [...withDoc, ...table.map(r => r[0])] : withDoc,
+        candidates: [...new Set([...quotedText, ...numbers, ...clear ? [""] : []]), ...docString === undefined ? [] : [docString]],
+        keys,
+        unknownKeys: unknown,
+        pressOnly: isCheck ? undefined : pressOnly(text),
+        navigation: isCheck ? undefined : navigation(text),
+        toggle: isCheck ? undefined : toggleGoal(text),
+        exact: /\b(exactly|in this order)\b/i.test(text),
+        header,
+        list,
+        placeholders: [...withDoc, ...table?.flat() ?? []].filter(v => placeholder(v)),
+        badCell: isCheck ? undefined : table?.flat().find(c => !c.trim() || /["“”]/.test(c)),
+    };
+}
+/** "try"/"attempt" right after the keyword marks an Attempt step: done once performed, even if the app rejects it. */
+const ATTEMPT = /^(I\s+)?(try|tries|attempt|attempts)\b/i;
+export const stepKind = (step) => step.type === PickleStepType.OUTCOME ? "assertion" : ATTEMPT.test(step.text) ? "attempt" : "action";
+/** A quoted `"$NAME"` is a secret placeholder (task 0030): the variable's name, else undefined. */
+export const placeholder = (value) => /^\$([A-Za-z_]\w*)$/.exec(value)?.[1];
+const quoted = (text) => [...text.matchAll(/["“]([^"”]+)["”]/g)].map(m => m[1]);
+function label(text, table, docString, header) {
+    if (docString !== undefined)
+        return `${text} ${JSON.stringify(docString)}`;
+    if (!table)
+        return text;
+    const cells = header ? table.slice(1).map(row => row.map((v, i) => `${table[0][i]}=${v}`).join(", ")).join("; ")
+        : table.map(row => row.length === 1 ? row[0] : `${row[0]}=${row[1]}`).join(", ");
+    return `${text} [${cells}]`;
+}
+/** An Action step's table as one Step per row, each resolved alone; 2 columns are label/value pairs (Cucumber `rowsHash`). */
+function tableSteps(text, table, header) {
+    const base = text.replace(/\s*:$/, "");
+    if (header)
+        return table.slice(1).map(row => `${base} ${row.map((v, i) => `${table[0][i]} "${v}"`).join(", ")}`);
+    return table.map(row => row.length === 1 ? `${base} "${row[0]}"` : `I enter "${row[1]}" as ${row[0]}`);
+}
+/**
+ * Jev's `done` barely tells checked from unchecked (task 0033: 0.45-0.80 on checked boxes, so it kept clicking), so
+ * code reads the box after the click instead, like the TYPE/SELECT effect check.
+ */
+function toggleGoal(text) {
+    if (/\b(and|then)\b|,/i.test(text))
+        return undefined;
+    if (/^(I\s+)?(uncheck|untick|deselect|clear|turn off|switch off|disable)\b/i.test(text))
+        return false;
+    // Task 0043: other wordings mean on unless negated; only applied when the clicked element is a toggle or radio.
+    return !/\b(disable|turn off|switch off|decline|reject|opt out|unsubscribe)/i.test(text);
+}
+/** Key names a Step can press (task 0039): Playwright's, lower-cased, plus aliases. */
+const KEYS = new Map([
+    ..."Escape Tab Enter Backspace Delete Insert Home End PageUp PageDown ArrowUp ArrowDown ArrowLeft ArrowRight Space Control Shift Alt Meta"
+        .split(" "), ...Array.from({ length: 12 }, (_, i) => `F${i + 1}`)
+].map(k => [k.toLowerCase(), k]));
+for (const [alias, key] of Object.entries({ esc: "Escape", return: "Enter", del: "Delete", ctrl: "Control", cmd: "Meta", command: "Meta",
+    option: "Alt", "page up": "PageUp", "page down": "PageDown", "up arrow": "ArrowUp", "down arrow": "ArrowDown",
+    "left arrow": "ArrowLeft", "right arrow": "ArrowRight", "arrow up": "ArrowUp", "arrow down": "ArrowDown",
+    "arrow left": "ArrowLeft", "arrow right": "ArrowRight" }))
+    KEYS.set(alias, key);
+/** `Ctrl+K`, `down arrow` -> Playwright's `Control+K`, `ArrowDown`; undefined if a part is no key. A letter or digit alone only quoted. */
+function keyName(expr, quoted) {
+    const parts = expr.trim().split(/\s*\+\s*/);
+    const named = parts.map(p => KEYS.get(p.toLowerCase()) ?? (/^[a-z0-9]$/i.test(p) && (quoted || parts.length > 1) ? p : undefined));
+    return named.every(k => k !== undefined) ? named.join("+") : undefined;
+}
+const ELEMENT_NOUN = /^(button|link|tab|icon|item|option|menu|card|row|toggle|checkbox|control)s?$/i;
+const PRESS = /\b(?:press(?:es|ed|ing)?|hit(?:s|ting)?)\s+(?:the\s+)?(?:["“]([^"”]+)["”]|([\w+]+(?:\s*\+\s*\w+)*)(?=((?:\s+\w+){0,2})))/gi; // the words after: lookahead, so a next "press" is still found
+function stepKeys(text) {
+    const keys = [], unknown = [];
+    // Quoted text (a value to type, a doc string) names no key, unless it is the quoted key itself: press "Tab".
+    const said = text.replace(/(\b(?:press(?:es|ed|ing)?|hit(?:s|ting)?)\s+(?:the\s+)?["“][^"”]+["”])|["“][^"”]*["”]/gi, (m, key) => key ?? '""');
+    for (const [, quotedKey, first, rest] of said.matchAll(PRESS)) {
+        const [next = ""] = rest?.trim().split(/\s+/) ?? [];
+        // "press the Delete button" clicks a button named like a key.
+        const key = quotedKey !== undefined ? keyName(quotedKey, true)
+            : keyName(`${first} ${next}`, false) ?? (ELEMENT_NOUN.test(next) ? undefined : keyName(first, false));
+        if (key)
+            keys.push(key);
+        else if (first && (first.includes("+") || next.toLowerCase() === "key"))
+            unknown.push(first);
+    }
+    return { keys, unknown };
+}
+/**
+ * Code navigates without Jev only for these whole-Step forms; "go back to the list" and the like are left to Jev, which
+ * is offered back/forward/reload every Turn. GOTO needs something URL-like (a path, query, hash, or full URL), never a
+ * page name: "I go to the Settings page" is Jev's.
+ */
+function navigation(text) {
+    const t = text.trim().replace(/[.!]$/, "");
+    const go = /^(?:I\s+)?(?:go|goes|navigate|navigates|browse|browses)\s+/i.source;
+    if (new RegExp(`${go}back$`, "i").test(t))
+        return { verb: "BACK" };
+    if (new RegExp(`${go}forward$`, "i").test(t))
+        return { verb: "FORWARD" };
+    if (/^(?:I\s+)?(?:reload|reloads|refresh|refreshes)(?:\s+the)?(?:\s+page)?$/i.test(t))
+        return { verb: "RELOAD" };
+    // Jev picks "close tab" right (0.97) but then barely takes the Step as done (0.24-0.37): a closed tab leaves no trace.
+    if (/^(?:I\s+)?(?:close|closes)\s+(?:the|this)\s+(?:new\s+)?tab$/i.test(t))
+        return { verb: "CLOSE_TAB" };
+    if (/^(?:I\s+)?(?:switch|switches|go|goes)\s+back\s+to\s+the\s+(?:previous|first|other|original)\s+tab$/i.test(t))
+        return { verb: "SWITCH_TAB" };
+    const m = new RegExp(`(?:${go}to|^(?:I\\s+)?(?:open|opens|visit|visits))\\s+(?:["“]([^"”]+)["”]|(\\S+))$`, "i").exec(t);
+    const url = m?.[1] ?? m?.[2];
+    return url && /^(\/|\?|#|\.\.?\/|[a-z][a-z\d+.-]*:\/\/)/i.test(url) ? { verb: "GOTO", value: url } : undefined;
+}
+function pressOnly(text) {
+    const m = /^(?:I\s+)?(?:press|hit)(?:es|s)?\s+(?:the\s+)?(?:["“]([^"”]+)["”]|(.+?))(?:\s+key)?[.!]?$/i.exec(text.trim());
+    return m ? keyName(m[1] ?? m[2], m[1] !== undefined) : undefined;
+}

package/dist/steps.d.ts

@@ -0,0 +1 @@
+export {};