decisium 0.0.0-stage → 0.1.2

package/dist/jev.js

@@ -0,0 +1,198 @@
+import { choice, noul, TypeSafeClient } from "@typesafe-ai/sdk";
+import { AREA_MISSING, AREA_PAGE, ASSERTION_KINDS, capabilities, describeAction, PAGE, STATES } from "./decision.js";
+export const MODEL = "jev-1.14.0";
+/** What answering each kind of browser dialog means, for Jev (task 0040). */
+const DIALOG_ANSWERS = {
+    accept: {
+        confirm: "Click OK: `step` clearly asks for what `dialog` asks to confirm.",
+        beforeunload: "Leave the page: `step` clearly intends to leave this page, even if changes are lost.",
+    },
+    dismiss: {
+        confirm: "Click Cancel: `step` does not clearly ask for what `dialog` asks to confirm, or says to cancel.",
+        beforeunload: "Stay on the page: `step` does not clearly intend to leave this page.",
+        prompt: "Click Cancel: none of the other answers is what `step` asks to enter, or `step` says to cancel.",
+    },
+};
+const refs = (els) => Object.fromEntries(els.map(e => [e.ref, e.line]));
+/** Jev API limit: options per choice question. */
+const MAX_CHOICES = 255;
+const FINALISTS = 3; // kept from each batch
+/**
+ * Pages can offer more candidates than one question accepts (GitHub: 336 links and buttons). Ask in batches, keep each
+ * batch's most likely candidates, repeat until they fit; the caller asks the real question over what is left, so the
+ * confidence gate still reads one comparable distribution. `fixed` answers (none, scroll, ...) are in every batch.
+ */
+export async function narrow(candidates, fixed, ask, max = MAX_CHOICES) {
+    let left = Object.entries(candidates);
+    const size = max - Object.keys(fixed).length;
+    while (left.length > size) {
+        const kept = [];
+        for (let i = 0; i < left.length; i += size) {
+            const batch = left.slice(i, i + size);
+            const { probabilities } = await ask({ ...Object.fromEntries(batch), ...fixed });
+            const best = batch.map(([k]) => k).sort((a, b) => (probabilities[b] ?? 0) - (probabilities[a] ?? 0)).slice(0, FINALISTS);
+            kept.push(...batch.filter(([k]) => best.includes(k)));
+        }
+        left = kept;
+    }
+    return { ...Object.fromEntries(left), ...fixed };
+}
+/**
+ * Jev rejects requests over its token limit (`max_tokens_exceeded`): measured between 115k and 117k characters of
+ * Wikipedia snapshot in one request. `ui` stays under this budget so 255 choices still fit next to it (task 0021).
+ */
+export const UI_BUDGET = 80_000;
+const SECTION = 8_000; // a page over budget is read in sections of about this size
+/**
+ * A `ui` over budget, reduced to the sections that matter for `step`. Sections are cut at lines and carry their
+ * ancestor lines (so a list item keeps its list); narrow() keeps the likeliest ones per batch until they fit, so every
+ * question of the Turn reads one reduced `ui` and their probabilities stay comparable.
+ */
+export async function reduceUi(ui, ask, budget = UI_BUDGET, section = SECTION) {
+    if (ui.length <= budget)
+        return ui;
+    const lines = ui.split("\n");
+    const indent = (l) => /^\s*/.exec(l)[0].length;
+    const parts = [];
+    const open = []; // ancestors of the current line, by indentation
+    let part = [], size = 0;
+    lines.forEach((l, i) => {
+        while (open.length && indent(lines[open.at(-1)]) >= indent(l))
+            open.pop();
+        if (size + l.length > section && part.length) {
+            parts.push(part);
+            part = [...open];
+            size = open.reduce((n, a) => n + lines[a].length + 1, 0);
+        }
+        part.push(i);
+        size += l.length + 1;
+        open.push(i);
+    });
+    parts.push(part);
+    const text = (p) => p.map(i => lines[i]).join("\n");
+    const kept = await narrow(Object.fromEntries(parts.map((p, i) => [`s${i}`, text(p)])), {}, ask, Math.floor(budget / (section * 1.5)));
+    const keep = new Set(Object.keys(kept).flatMap(k => parts[Number(k.slice(1))]));
+    return lines.filter((_, i) => keep.has(i)).join("\n");
+}
+/** Live Jev requests of this process and their tokens; cassette replays cost nothing and are not counted. */
+export const jevUsage = { calls: 0, inputTokens: 0, outputTokens: 0 };
+/** Every question sends the Step text as-is, so a value quoted in a Step (a password included) reaches the API. */
+export class JevDecider {
+    #client; // created on the first live call: replay-only runs need no TYPESAFE_API_KEY
+    #reduced = new WeakMap(); // per Observation and Step: asked once per Turn
+    /** `ui` for `step` on this Observation, reduced to the sections that matter when the page is over budget. */
+    #ui(obs, about, step) {
+        const byStep = this.#reduced.get(obs) ?? new Map();
+        this.#reduced.set(obs, byStep);
+        if (!byStep.has(step))
+            byStep.set(step, reduceUi(obs.text, async (sections) => {
+                const res = await this.#ask({
+                    state: { [about]: step, ...sections },
+                    questions: { pick: choice(`Which of these sections of the page holds what \`${about}\` needs?`, Object.fromEntries(Object.keys(sections).map(k => [k, `section \`${k}\``]))) },
+                });
+                return res.answers.pick;
+            }));
+        return byStep.get(step);
+    }
+    async #ask(request) {
+        const res = await (this.#client ??= new TypeSafeClient({ defaultModel: MODEL })).systemOne(request); // reads TYPESAFE_API_KEY
+        jevUsage.calls++;
+        jevUsage.inputTokens += res.usage?.input_tokens ?? 0;
+        jevUsage.outputTokens += res.usage?.output_tokens ?? 0;
+        return { model: res.model, answers: res.answers };
+    }
+    /** One choice question over `criteria`, for narrow(). */
+    #choose(state, question) {
+        return async (criteria) => (await this.#ask({ state, questions: { pick: choice(question, criteria) } })).answers.pick;
+    }
+    async turn(step, obs, recent, attempt = false, keys = []) {
+        const state = { step, ui: await this.#ui(obs, "step", step), actions_taken_for_step: recent.length ? recent : "none yet" };
+        const question = "Which element in `ui` should be interacted with next to accomplish `step`?";
+        const page = `page "${obs.readable.find(e => e.ref === "title")?.value ?? ""}": the page itself (scroll it, wait, history, tabs, keys)`;
+        const targets = await narrow(refs(obs.elements), { none: "No element on screen helps accomplish `step`.", [PAGE]: page }, this.#choose(state, question));
+        // Every action some target offers; code keeps the chosen target's own (task 0065, ADR 0005).
+        const actions = [...new Set([PAGE, ...obs.elements].flatMap(t => capabilities(t, obs, keys)))];
+        const res = await this.#ask({
+            state,
+            questions: {
+                done: attempt
+                    ? noul("Given `actions_taken_for_step`, has the user performed every action `step` asks for, regardless of whether the app accepted it?")
+                    : noul("Given `actions_taken_for_step`, does `ui` show that `step` has been fully accomplished?"),
+                target: choice(question, targets),
+                // Same request as target: one call per Turn (task 0065: as accurate as asking after the target, half the time).
+                action: choice("How should the element chosen to interact with next be used to accomplish `step`?", Object.fromEntries(actions.map(a => [a, describeAction(a)]))),
+            },
+        });
+        return { done: res.answers.done.noul, target: res.answers.target, action: res.answers.action };
+    }
+    async drop(step, obs, source) {
+        const state = { step, ui: await this.#ui(obs, "step", step), dragged: source.line };
+        const question = "`dragged` is being dragged with the mouse to accomplish `step`. Onto which element in `ui` should it be dropped?";
+        const among = [...new Set([...obs.readable, ...obs.areas])].filter(e => e !== source);
+        const targets = await narrow(refs(among), { none: "No element in `ui` is where `step` says to drop it." }, this.#choose(state, question));
+        return (await this.#ask({ state, questions: { target: choice(question, targets) } })).answers.target;
+    }
+    async recall(step, earlier) {
+        const values = Object.keys(earlier);
+        const criteria = Object.fromEntries(values.map((v, i) => [`v${i}`, `"${v}", from the earlier step: ${earlier[v]}`]));
+        criteria.none = "`check` does not refer to any of these values.";
+        const res = await this.#ask({
+            state: { check: step },
+            questions: { value: choice("`check` quotes no value. Which value from an earlier step of the same test does it refer to (e.g. \"the campaign\" meaning the campaign named earlier)?", criteria) },
+        });
+        const a = res.answers.value;
+        const name = (k) => k === "none" ? k : values[Number(k.slice(1))] ?? k;
+        return { choice: name(a.choice), probabilities: Object.fromEntries(Object.entries(a.probabilities).map(([k, p]) => [name(k), p])) };
+    }
+    async dialog(step, obs, answers) {
+        const { type, message } = obs.dialog;
+        const criteria = Object.fromEntries(answers.map((a, i) => a === "accept" || a === "dismiss"
+            ? [a, DIALOG_ANSWERS[a][type]] : [`v${i}`, `Enter "${a}" and click OK.`]));
+        const res = await this.#ask({
+            state: { step, dialog: message },
+            questions: { answer: choice(`A browser ${type === "beforeunload" ? "\"Leave site?\"" : type} dialog is open, saying \`dialog\`. How should it be answered to accomplish \`step\`?`, criteria) },
+        });
+        const a = res.answers.answer;
+        const name = (k) => /^v\d+$/.test(k) ? answers[Number(k.slice(1))] : k;
+        return { choice: name(a.choice), probabilities: Object.fromEntries(Object.entries(a.probabilities).map(([k, p]) => [name(k), p])) };
+    }
+    async value(step, obs, el, candidates) {
+        const state = { step, ui: await this.#ui(obs, "step", step), element: el.line };
+        // A clicked element gets a value only to upload a file (task 0044): "entered into a button" read as nothing.
+        const question = el.verb === "CLICK" ? "Which file should be uploaded with `element` to accomplish `step`?"
+            : "Which value should be entered into `element` to accomplish `step`?";
+        const criteria = await narrow(Object.fromEntries(candidates.map((c, i) => [`v${i}`, c])), { none: "None of these values is what `step` asks for." }, this.#choose(state, question));
+        const res = await this.#ask({ state, questions: { value: choice(question, criteria) } });
+        const a = res.answers.value;
+        // Map label keys back to the values so traces and execution use real text.
+        const name = (k) => criteria[k] !== undefined && k !== "none" ? criteria[k] : k;
+        return {
+            choice: name(a.choice),
+            probabilities: Object.fromEntries(Object.entries(a.probabilities).map(([k, p]) => [name(k), p])),
+        };
+    }
+    async assess(step, obs, judged) {
+        const state = { check: step, ui: await this.#ui(obs, "check", step) };
+        const subjectQ = "Which element in `ui` is the one `check` is about, regardless of whether the check passes?";
+        const areaQ = "Where does `check` say to look? Pick the element in `ui` that is that area (a list, table, section, dialog...), regardless of whether the check passes.";
+        const [subjects, areas] = await Promise.all([
+            narrow(refs(obs.readable), { none: "No element in `ui` is the one `check` is about." }, this.#choose(state, subjectQ)),
+            narrow(refs(obs.areas), {
+                [AREA_PAGE]: "`check` names no specific area; anywhere on the page counts.",
+                [AREA_MISSING]: "`check` names a specific area, but no element in `ui` is that area.",
+            }, this.#choose(state, areaQ)),
+        ]);
+        const res = await this.#ask({
+            state,
+            questions: {
+                kind: choice("What kind of check is `check`?", ASSERTION_KINDS),
+                subject: choice(subjectQ, subjects),
+                state: choice("Which control state does `check` require?", STATES),
+                area: choice(areaQ, areas),
+                ...(judged ? { judged: noul("Does `ui` satisfy `check`?") } : {}),
+            },
+        });
+        const a = res.answers;
+        return { kind: a.kind, subject: a.subject, area: a.area, state: a.state, judged: a.judged?.noul };
+    }
+}

package/dist/lint.d.ts

@@ -0,0 +1,5 @@
+import { type ParsedStep } from "./step.ts";
+/** Cookbook warnings for one Step. `before`: the scenario's earlier Steps. */
+export declare function warnings(step: ParsedStep, before: ParsedStep[], env?: Record<string, string | undefined>): string[];
+/** The explanation of one feature file, for people. */
+export declare function lint(path: string, env?: Record<string, string | undefined>): string;

package/dist/lint.js

@@ -0,0 +1,109 @@
+// `decisium lint <file.feature>`: what each Step will be taken as, read without a browser or Jev (task 0031).
+// Per Step: its kind, the quoted values Jev can pick from, the keys it presses, secret placeholders, and warnings for wordings that
+// docs/cookbook.md shows failing.
+import { readFileSync } from "node:fs";
+import { parseFeature } from "./feature.js";
+import { KIND } from "./report.js";
+import { placeholder, readStep } from "./step.js";
+const SEE = "see docs/cookbook.md";
+/** Cookbook warnings for one Step. `before`: the scenario's earlier Steps. */
+export function warnings(step, before, env = process.env) {
+    const t = step.text;
+    const read = readStep(step);
+    const earlier = before.flatMap(s => readStep(s).quoted).filter(v => !placeholder(v));
+    const { values } = read; // a check with a table returns before reading these
+    const out = [];
+    for (const name of new Set(read.placeholders.map(v => placeholder(v)))) {
+        if (!env[name])
+            out.push(`$${name} is not set in this environment: the run stops before it starts (exit 2)`);
+    }
+    const secret = /\b(?:password|passcode|token|secret|api key)\b[^"“]*["“]([^"”]+)["”]/i.exec(t)?.[1];
+    if (secret && !placeholder(secret) && step.kind !== "assertion") {
+        out.push(`a literal value next to "password/token/secret" is sent to Jev and written to the cassette and logs; write "$NAME" and set it in the environment (${SEE}, Secrets)`);
+    }
+    if (step.kind !== "assertion") {
+        if (/\bsearch(es)? (for|the)\b/i.test(t) && !/\b(open|opens|submit|submits)\b/i.test(t)) {
+            out.push(`"search for" runs a search but does not open a result, and Jev may count typing alone as done; say "I open the "X" ... through the search", or add "and submit the search" (${SEE}, Navigate)`);
+        }
+        if (/^(I\s+)?(un)?(check|tick)\b/i.test(t) && /\b(and|then)\b|,/i.test(t))
+            out.push(`checking a box is decided by code only when the Step does nothing else; split "and ..." into its own Step (${SEE}, Submit and act)`);
+        for (const name of read.unknownKeys)
+            out.push(`"${name}" is not a key name, so it is never pressed; use Escape, Tab, ArrowDown, PageDown, Home, F2, Esc, down arrow, Space, Ctrl+K... (${SEE}, Keys)`);
+        if (!/\b(press(es|ed|ing)?|hit(s|ting)?)\b/i.test(t) && /\b(Esc|Escape)\b|\b(Tab|Enter|Return|Space|Backspace|Delete|Home|End|arrow|F\d+) key\b|\b(Ctrl|Control|Shift|Alt|Cmd|Meta)\s*\+\s*\w/i.test(t))
+            out.push(`names a key without "press" or "hit", so no key is offered: say "press Escape" (${SEE}, Keys)`);
+        if (/^(I\s+)?(accept|dismiss|cancel|answer|confirm)\s+(the\s+)?(alert|confirm|confirmation|prompt|browser dialog)\b/i.test(t))
+            out.push(`a browser dialog is answered by the Step that opens it and dismissed when that Step ends, so this Step finds none open; say the intent in the Step that opens it ("I delete the note", "I start deleting the note but cancel") (${SEE}, Browser dialogs)`);
+        if (step.table && read.header && step.table.length < 2)
+            out.push(`an action's table with 3+ columns starts with its header row, so this one has no row to act on: AMBIGUOUS; add one row per entry under the header (${SEE}, Data tables)`);
+        return out;
+    }
+    // Checks. A table is matched by code, row by row under its header; a header alone compares nothing.
+    if (step.table) {
+        if (read.header && step.table.length < 2)
+            out.push(`a check's table with 2+ columns starts with its header row, so this one has no row to compare: UNVERIFIABLE; add a header row naming the page table's columns (${SEE}, Data tables)`);
+        if (read.header && /\b(not|no longer|never)\b/i.test(t))
+            out.push(`code can check that table rows are shown, not that they are absent: UNVERIFIABLE; check each row's absence in its own Step (${SEE}, Data tables)`);
+        return out;
+    }
+    // Checks. A state check ("should be disabled") needs no quoted value.
+    const state = /\bshould (?:not )?be (disabled|enabled|checked|unchecked|expanded|collapsed|selected|unselected|pressed|unpressed)\b/i.test(t);
+    const subjective = !values.length && /\b(well|nicely|good|nice|tidy|clean|readable|beautiful|professional|properly|correctly|looks?)\b/i.test(t);
+    if (!values.length && !state && !subjective) {
+        out.push(earlier.length
+            ? `quotes nothing: Jev must work out which earlier value it means (${[...new Set(earlier)].map(v => `"${v}"`).join(", ")}); if it is unsure the check is UNVERIFIABLE, so quote the value when there are several (${SEE}, Memory)`
+            : `quotes nothing for code to compare: UNVERIFIABLE; quote the expected text or value (${SEE}, Presence)`);
+    }
+    if (values.length > 1 && /\bshould (be|say|show|read|equal)\b(?! (shown|visible|displayed|listed))/i.test(t)) {
+        out.push(`a value check compares exactly one quoted value; with ${values.length} it is UNVERIFIABLE (split it into one check per value) (${SEE}, Value checks)`);
+    }
+    if (/\btitle\b/i.test(t) && !/\b(page|tab|browser|window) title\b/i.test(t)) {
+        out.push(`"title" also names the browser tab's title, so Jev may be unsure which one you mean (AMBIGUOUS); say "heading" (${SEE}, Value checks)`);
+    }
+    if (subjective) {
+        out.push(`reads as subjective: code cannot compare it (UNVERIFIABLE) unless the run has --judged; quote something concrete (${SEE}, Value checks)`);
+    }
+    const AREA = "(?:[\\w-]+ ){0,3}(?:list|calendar|table|results|menu|section|dialog|sidebar|panel|grid|cart|tab|form|header|footer|toolbar|campaigns)";
+    // "... in the campaign list", or the area as subject: "the campaign list should contain ...".
+    const area = new RegExp(`\\b(?:in|on|inside|within|among|under) (?:the |a )?(${AREA})\\b`, "i").exec(t)
+        ?? new RegExp(`^(?:the )?(${AREA}) should (?:not )?(?:contain|include|list|show)\\b`, "i").exec(t);
+    // The cookbook's failing pattern: the last action opened something else (a campaign), and the check names an area
+    // (the campaign list) that is therefore not on the screen.
+    const lastAction = before.findLast(s => s.kind !== "assertion")?.text ?? "";
+    const noun = area?.[1].split(" ").at(-1);
+    if (area && /\bopen/i.test(lastAction) && !new RegExp(`\\b${noun}`, "i").test(lastAction))
+        out.push(`looks only in "${area[1]}", but the Step before opened something else: if that area is not on the screen, the check is AMBIGUOUS; open it first (${SEE}, Scoped presence)`);
+    return out;
+}
+/** The explanation of one feature file, for people. */
+export function lint(path, env = process.env) {
+    const out = [path];
+    let flagged = 0;
+    for (const s of parseFeature(readFileSync(path, "utf8"), path)) {
+        out.push("", `  Scenario: ${s.name}${s.url ? `  (${s.url})` : ""}`);
+        const before = [];
+        for (const step of s.steps) {
+            const read = readStep(step);
+            const values = step.kind === "assertion" ? read.quoted : step.docString === undefined ? read.candidates : read.candidates.slice(0, -1);
+            const secrets = [...new Set(read.placeholders)];
+            out.push(`  ${String(step.line ?? "").padStart(4)}  ${KIND[step.kind].padEnd(7)} ${read.label}`);
+            if (step.table && step.kind !== "assertion")
+                for (const row of read.rows)
+                    out.push(`${" ".repeat(15)}row: ${row}`);
+            const shown = values.filter(v => !placeholder(v));
+            if (shown.length)
+                out.push(`${" ".repeat(15)}${step.kind === "assertion" ? "compares" : "values"}: ${shown.map(v => `"${v}"`).join(", ")}`);
+            const { keys } = read;
+            if (keys.length)
+                out.push(`${" ".repeat(15)}keys: ${keys.join(", ")}`);
+            if (secrets.length)
+                out.push(`${" ".repeat(15)}secrets (from the environment, never sent to Jev): ${secrets.join(", ")}`);
+            for (const w of warnings(step, before, env)) {
+                out.push(`${" ".repeat(15)}⚠ ${w}`);
+                flagged++;
+            }
+            before.push(step);
+        }
+    }
+    out.push("", flagged ? `${flagged} warning${flagged > 1 ? "s" : ""}.` : "No warnings.");
+    return out.join("\n");
+}

package/dist/network.d.ts

@@ -0,0 +1,9 @@
+import type { BrowserContext } from "playwright";
+export interface NetworkReplay {
+    glob: string;
+    har: string;
+    mode: "record" | "replay";
+}
+export declare function recordNetwork(context: BrowserContext, { glob, har }: NetworkReplay): Promise<void>;
+/** `missed` gets "METHOD url" for each matching request the HAR does not have. */
+export declare function replayNetwork(context: BrowserContext, { glob, har }: NetworkReplay, missed: (request: string) => void): Promise<void>;

package/dist/network.js

@@ -0,0 +1,35 @@
+// Network record/replay for `@replay-network:<glob>` (task 0048). Recording: Playwright's routeFromHAR writes only the
+// matching requests to a HAR (bodies in files beside it). Replay: our own route handler, not routeFromHAR, because that
+// matches request bodies exactly and misses every POST with a timestamp or id in it. A request is matched by method +
+// URL + occurrence (the n-th call to that URL), body ignored; one not in the recording is aborted and reported, never
+// sent live.
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+export async function recordNetwork(context, { glob, har }) {
+    mkdirSync(dirname(har), { recursive: true });
+    await context.routeFromHAR(har, { url: glob, update: true, updateContent: "attach", updateMode: "minimal" });
+}
+/** `missed` gets "METHOD url" for each matching request the HAR does not have. */
+export async function replayNetwork(context, { glob, har }, missed) {
+    if (!existsSync(har))
+        throw new Error(`No network recording ${har} for @replay-network:${glob}; record it with --record all.`);
+    const entries = JSON.parse(readFileSync(har, "utf8")).log.entries;
+    const served = new Map(); // "METHOD url" -> times served
+    await context.route(glob, route => {
+        const req = route.request();
+        const key = `${req.method()} ${req.url()}`;
+        const n = served.get(key) ?? 0;
+        served.set(key, n + 1);
+        const entry = entries.filter(e => `${e.request.method} ${e.request.url}` === key)[n];
+        if (!entry) {
+            missed(n ? `${key} (call ${n + 1})` : key);
+            return route.abort();
+        }
+        const { status, headers, content } = entry.response;
+        const body = content._file ? readFileSync(join(dirname(har), content._file))
+            : Buffer.from(content.text ?? "", content.encoding === "base64" ? "base64" : "utf8");
+        // content-length/encoding describe the recorded transfer, not the decoded body served here.
+        const kept = headers.filter(h => !/^(content-length|content-encoding|transfer-encoding)$/i.test(h.name));
+        return route.fulfill({ status, headers: Object.fromEntries(kept.map(h => [h.name, h.value])), body });
+    });
+}

package/dist/observation.d.ts

@@ -0,0 +1,87 @@
+/** A node of `ariaSnapshotJSON`: free-form, states as extra keys (`checked`, `level`, ...); text nodes are strings. */
+export type AriaNode = string | {
+    role: string;
+    name?: string;
+    ref?: string;
+    cursor?: string;
+    url?: string;
+    text?: string;
+    children?: AriaNode[];
+    [state: string]: unknown;
+};
+/**
+ * The snapshot's text form, one line per node, without YAML quoting: the YAML text quoted lines whose name held a colon
+ * (`- 'heading "Releases: x/y" [ref=e1]'`) and the line parser dropped them (task 0064). Names escape `\` and `"`.
+ */
+export declare function renderSnapshot(nodes: AriaNode[], indent?: string): string;
+export type Verb = "CLICK" | "TYPE" | "SELECT";
+export interface Element {
+    ref: string;
+    role: string;
+    name: string;
+    value: string;
+    description?: string;
+    state: string;
+    secret: boolean;
+    line: string;
+    verb: Verb;
+    options: string[];
+    text: string;
+    parent?: Element;
+    cells?: Element[];
+    url?: string;
+}
+export interface Observation {
+    text: string;
+    elements: Element[];
+    readable: Element[];
+    areas: Element[];
+    pageText: string;
+    dialog?: Dialog;
+}
+/** A browser dialog: open, or the last one shown, readable until the next action Step (task 0040). */
+export interface Dialog {
+    type: "alert" | "confirm" | "prompt" | "beforeunload";
+    message: string;
+    state: "open" | "accepted" | "dismissed";
+}
+export declare const MASK = "\u2022\u2022\u2022\u2022";
+/**
+ * `secretRefs`: refs of password fields (the snapshot itself shows them as plain textboxes with their value).
+ * `editableRefs`: comboboxes you type into (search boxes with suggestions); other comboboxes are clicked open.
+ * `targetRefs`: non-controls with their own pointer cursor or tabindex: Turn targets (task 0064).
+ */
+export declare function parseSnapshot(snapshot: string, secretRefs?: ReadonlySet<string>, editableRefs?: ReadonlySet<string>, targetRefs?: ReadonlySet<string>): Observation;
+/**
+ * Text an Assertion step compares against, or undefined when the element's text is only its label.
+ * Value-bearing controls compare their value (empty counts); other controls (buttons, checkboxes) only
+ * have a name, so "the 'Schedule' button should be disabled" must not pass just because the name matches.
+ * Links are the exception: their text is content (a breadcrumb or title showing a name), like a heading's.
+ */
+export declare function assertableText(el: Element): string | undefined;
+/**
+ * Adds the page URL and title as two readable pseudo-elements (refs `url`, `title`) on top of `ui`, so a value check
+ * can pick them as the subject (task 0025). Not actionable, and not in `pageText`: text only in the URL is not shown.
+ * `tabs` (task 0041): e.g. "2 open, this is tab 2", only while more than one is open, so one-tab pages read as before.
+ */
+export declare function withPage(obs: Observation, url: string, title: string, tabs?: string): Observation;
+/**
+ * Adds a browser dialog as a readable pseudo-element (ref `dialog`) on top of `ui`, named "browser dialog" so it is not
+ * taken for an ARIA alert, with its state (open, accepted, dismissed: Jev read a check about the page after a closed
+ * "Delete the Ideas note?" as an absence check). Its message is information for Jev and what a value check compares,
+ * never something to click. Like the URL it is not an area or page text: a check about the page must not read it.
+ */
+export declare function withDialog(obs: Observation, dialog?: Dialog): Observation;
+/** The last download of the scenario (task 0044), saved to its run folder. `text`: its contents, unless binary. */
+export interface Download {
+    name: string;
+    size: number;
+    text?: string;
+}
+/**
+ * Adds the last download as a readable pseudo-element (ref `download`): its value is the file name and, for a text file,
+ * its contents, so the value check compares either. An empty file is `[empty]`, and a value check on it fails.
+ */
+export declare function withDownload(obs: Observation, download?: Download): Observation;
+/** Adds the clipboard text (task 0062) as a readable pseudo-element (ref `clipboard`), so a value check reads copied text. */
+export declare function withClipboard(obs: Observation, text?: string): Observation;