verikun 0.4.1

package/dist/run.js

@@ -0,0 +1,434 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Recorder = void 0;
+exports.isRecordable = isRecordable;
+exports.rolloverReason = rolloverReason;
+exports.stepName = stepName;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const format_1 = require("./ui/format");
+const errors_1 = require("./errors");
+const output_1 = require("./output");
+const report_1 = require("./report");
+// Commands that become a recorded step (a JUnit testcase). Inspection commands
+// (ui, find, devices, doctor, current) are deliberately excluded — they are how
+// an agent decides what to do, not assertions about the app. `log` is the one
+// exception: it inspects, but is recorded so its captured device logs land in
+// the archived report (the agent pulls them on-demand after a failure).
+const RECORDABLE = new Set([
+    'tap', 'click',
+    'text', 'type',
+    'key', 'back', 'home', 'enter',
+    'swipe', 'scroll',
+    'screenshot', 'shot',
+    'wait', 'assert',
+    'launch', 'open', 'stop', 'clear',
+    'log', 'logs',
+]);
+function isRecordable(command) {
+    return RECORDABLE.has(command);
+}
+const HIERARCHY_CAP = 24000; // chars of failure hierarchy kept inline in run.json
+const LOG_CAP = 50000; // chars of device logs kept inline in run.json (tail-kept)
+// --- paths & persistence --------------------------------------------------
+const activeDir = () => (0, node_path_1.join)((0, output_1.artifactDir)(), 'run');
+const archiveBase = () => (0, node_path_1.join)((0, output_1.artifactDir)(), 'runs');
+const statePath = (dir) => (0, node_path_1.join)(dir, 'run.json');
+function loadState(dir) {
+    if (!(0, node_fs_1.existsSync)(statePath(dir)))
+        return null;
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)(statePath(dir), 'utf8'));
+    }
+    catch (e) {
+        // The state file exists but won't parse — it's corrupt. Surface it (then treat as no
+        // active run, which the next run start overwrites) instead of swallowing it silently.
+        (0, output_1.err)(`[verikun] ignoring unreadable run state ${statePath(dir)} (${e.message})`);
+        return null;
+    }
+}
+function saveState(dir, state) {
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    (0, node_fs_1.writeFileSync)(statePath(dir), JSON.stringify(state, null, 2));
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+function runId() {
+    const d = new Date();
+    const p = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
+}
+function uniqueDir(base) {
+    if (!(0, node_fs_1.existsSync)(base))
+        return base;
+    for (let i = 2;; i++) {
+        const candidate = `${base}-${i}`;
+        if (!(0, node_fs_1.existsSync)(candidate))
+            return candidate;
+    }
+}
+// --- run-context rollover -------------------------------------------------
+//
+// An implicit run should not silently swallow unrelated activity. Before adding
+// a step to an existing run we check whether the context still matches; if not,
+// the old run is auto-closed (archived — never discarded) and a fresh one starts.
+/** A stable-per-session id, if the environment provides one. Opt-in by design:
+ *  in an agent harness each command may be a fresh shell, so we never derive it
+ *  from the process tree (that would roll over on every action). */
+function currentSession() {
+    return process.env.VERIKUN_SESSION || process.env.TERM_SESSION_ID || undefined;
+}
+/** Idle-timeout in minutes (0 disables). Default 30. */
+function idleMinutes() {
+    const v = process.env.VERIKUN_RUN_IDLE_MIN;
+    if (v === undefined)
+        return 30;
+    const n = Number(v);
+    return Number.isFinite(n) && n >= 0 ? n : 30;
+}
+function lastActiveMs(state) {
+    const ts = state.updatedAt ||
+        (state.steps.length ? state.steps[state.steps.length - 1].startedAt : '') ||
+        state.startedAt;
+    const ms = Date.parse(ts);
+    return Number.isNaN(ms) ? Date.now() : ms;
+}
+function ageMs(state) {
+    return Date.now() - lastActiveMs(state);
+}
+function fmtAge(ms) {
+    const m = Math.floor(ms / 60000);
+    if (m < 1)
+        return '<1m';
+    if (m < 60)
+        return `${m}m`;
+    return `${Math.floor(m / 60)}h${m % 60}m`;
+}
+/** Why the active run should be closed before recording the next step, or null to keep it. */
+function rolloverReason(state, serial, session) {
+    // A different device or session is a hard context change — applies to any run.
+    if (state.device && serial && state.device !== serial)
+        return `device changed (${state.device} → ${serial})`;
+    if (state.session && session && state.session !== session)
+        return 'different session';
+    // Idle timeout only retires runs that were auto-started; an explicitly named
+    // run (`vk run start`) is the user's deliberate container and persists.
+    const idle = idleMinutes();
+    if (idle > 0 && state.implicit && ageMs(state) > idle * 60000)
+        return `idle for ${fmtAge(ageMs(state))} (>${idle}m)`;
+    return null;
+}
+function stepName(command, positionals, flags) {
+    const p = positionals;
+    const at = typeof flags['at'] === 'string' ? flags['at'] : undefined;
+    const from = typeof flags['from'] === 'string' ? flags['from'] : undefined;
+    const to = typeof flags['to'] === 'string' ? flags['to'] : undefined;
+    const on = typeof flags['on'] === 'string' ? flags['on'] : undefined;
+    switch (command) {
+        case 'tap':
+        case 'click':
+            return at ? `tap (${at})` : `tap ${p[0] ?? ''}`.trim();
+        case 'text':
+            return `text ${p[0] ?? ''}`.trim(); // omit the typed value (may be secret)
+        case 'type':
+            return 'type';
+        case 'swipe':
+        case 'scroll':
+            if (from && to)
+                return `swipe ${from}->${to}`;
+            return `swipe ${p[0] ?? ''}${on ? ` on ${on}` : ''}`.trim();
+        case 'screenshot':
+        case 'shot':
+            return 'screenshot';
+        case 'back':
+        case 'home':
+        case 'enter':
+            return command;
+        default:
+            return `${command} ${p[0] ?? ''}`.trim();
+    }
+}
+// --- recorder -------------------------------------------------------------
+class Recorder {
+    state;
+    dir;
+    step;
+    startMs;
+    constructor(state, dir, step, startMs) {
+        this.state = state;
+        this.dir = dir;
+        this.step = step;
+        this.startMs = startMs;
+    }
+    /**
+     * Open a step for a recordable command, auto-starting an implicit run if none
+     * is active. Returns null when recording is disabled via VERIKUN_NO_RUN.
+     */
+    static beginStep(command, positionals, flags, platform, deviceReq, serial, driver) {
+        if (process.env.VERIKUN_NO_RUN)
+            return null;
+        const dir = activeDir();
+        let state = loadState(dir);
+        const session = currentSession();
+        let rolledOver = false;
+        // Close a stale / context-mismatched run before continuing.
+        if (state) {
+            const reason = rolloverReason(state, serial, session);
+            if (reason) {
+                try {
+                    const dest = Recorder.seal(state, dir);
+                    (0, output_1.err)(`[verikun] previous run '${state.name}' (${state.steps.length} step(s)) auto-closed → ${dest} (${reason}); starting a fresh run`);
+                    state = null;
+                    rolledOver = true;
+                }
+                catch (e) {
+                    (0, output_1.err)(`[verikun] could not close stale run (${e.message}); appending to it instead`);
+                }
+            }
+        }
+        if (!state) {
+            state = {
+                id: runId(),
+                name: 'run',
+                startedAt: nowIso(),
+                updatedAt: nowIso(),
+                platform,
+                device: serial || deviceReq,
+                session,
+                implicit: true,
+                steps: [],
+            };
+            if (!rolledOver) {
+                (0, output_1.err)('[verikun] recording test run (implicit) — archive: `vk run archive` · discard: `vk run clear`');
+            }
+        }
+        else {
+            // Backfill identity once it becomes known (e.g. a run started without a device).
+            if (!state.device && (serial || deviceReq))
+                state.device = serial || deviceReq;
+            if (!state.session && session)
+                state.session = session;
+        }
+        // Anchor the log window at the session's first step (covers both implicit
+        // creation and an explicit `vk run start`, which records no marker itself).
+        // Best-effort — a missing marker just means `vk log` falls back to last-N.
+        if (driver && !state.logStart) {
+            try {
+                const t = driver.deviceTime();
+                if (t)
+                    state.logStart = t;
+            }
+            catch {
+                /* device clock unavailable */
+            }
+        }
+        const step = {
+            index: state.steps.length,
+            command,
+            name: stepName(command, positionals, flags),
+            startedAt: nowIso(),
+            durationMs: 0,
+            status: 'passed',
+            exitCode: 0,
+        };
+        return new Recorder(state, dir, step, Date.now());
+    }
+    /** Attach selector / heal-tier / resolved-element / message detail to the current step. */
+    note(info) {
+        const s = this.step;
+        if (info.selector) {
+            s.selector = {
+                raw: info.selector.raw,
+                kind: info.selector.kind,
+                value: info.selector.value,
+                contains: info.selector.contains || undefined,
+                index: info.selector.index,
+            };
+        }
+        if (info.tier && info.tier !== 'exact')
+            s.tier = info.tier;
+        if (info.element) {
+            const el = info.element;
+            s.resolved = {
+                type: el.type,
+                id: el.id || undefined,
+                idShort: el.idShort || undefined,
+                text: el.text || undefined,
+                desc: el.desc || undefined,
+                center: el.center,
+            };
+        }
+        if (info.message)
+            s.message = info.message;
+    }
+    /** Store an image captured by a `screenshot` step in the run's artifacts. */
+    attachImage(buf) {
+        const rel = `artifacts/step-${this.step.index}-screenshot.png`;
+        this.writeArtifact(rel, buf);
+        this.step.image = rel;
+    }
+    /** Store device logs captured by a `log` step. Keeps the TAIL — the newest
+     *  lines, where a crash/stack trace is — unlike failHierarchy which keeps the head. */
+    attachLog(text) {
+        this.step.logs = text.length > LOG_CAP ? '…(truncated)\n' + text.slice(-LOG_CAP) : text;
+    }
+    /** The session-start log marker — but only once a prior step exists, so a `log`
+     *  that is itself the first action isn't scoped to an empty (just-now) window. */
+    logWindowStart() {
+        return this.state.steps.length > 0 ? this.state.logStart : undefined;
+    }
+    /** Finalize a step that returned a normal exit code (0 pass, 1 fail, ≥2 error). */
+    finish(exitCode, driver) {
+        this.step.exitCode = exitCode;
+        this.step.status = exitCode === 0 ? 'passed' : exitCode === 1 ? 'failed' : 'error';
+        if (exitCode !== 0)
+            this.capture(driver);
+        this.commit();
+    }
+    /** Finalize a step whose command threw. */
+    finishError(e, driver) {
+        const exitCode = e instanceof errors_1.CliError ? e.exitCode : 3;
+        this.step.exitCode = exitCode;
+        this.step.status = exitCode === 1 ? 'failed' : 'error';
+        if (!this.step.message)
+            this.step.message = e.message;
+        this.capture(driver);
+        this.commit();
+    }
+    // Best-effort: grab a screenshot and the UI hierarchy of the failing page.
+    // The device may be unreachable (that may be why we failed) — swallow errors.
+    capture(driver) {
+        if (!driver)
+            return;
+        try {
+            this.writeArtifact(`artifacts/step-${this.step.index}-fail.png`, driver.screenshot());
+            this.step.failImage = `artifacts/step-${this.step.index}-fail.png`;
+        }
+        catch (e) {
+            // Best-effort evidence: the device may be gone (often why the step failed). Surface
+            // it so a screenshot bug isn't hidden, but never let it derail failure recording.
+            (0, output_1.err)(`[verikun] could not capture failure screenshot (${e.message})`);
+        }
+        try {
+            const text = (0, format_1.formatCompact)(driver.getElements({ all: false }));
+            this.step.failHierarchy = text.length > HIERARCHY_CAP ? text.slice(0, HIERARCHY_CAP) + '\n…(truncated)' : text;
+        }
+        catch (e) {
+            (0, output_1.err)(`[verikun] could not capture failure hierarchy (${e.message})`);
+        }
+    }
+    writeArtifact(rel, buf) {
+        (0, node_fs_1.mkdirSync)((0, node_path_1.join)(this.dir, 'artifacts'), { recursive: true });
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(this.dir, rel), buf);
+    }
+    commit() {
+        this.step.durationMs = Date.now() - this.startMs;
+        this.state.steps.push(this.step);
+        this.state.updatedAt = nowIso();
+        saveState(this.dir, this.state);
+    }
+    /** Finalize a run: write reports next to it, then move it into ./.verikun/runs/<id>/. */
+    static seal(state, dir) {
+        state.finishedAt = nowIso();
+        state.updatedAt = nowIso();
+        saveState(dir, state);
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(dir, 'report.xml'), (0, report_1.toJUnitXml)(state));
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(dir, 'report.html'), (0, report_1.toHtml)(state));
+        (0, node_fs_1.mkdirSync)(archiveBase(), { recursive: true });
+        const dest = uniqueDir((0, node_path_1.join)(archiveBase(), state.id));
+        (0, node_fs_1.renameSync)(dir, dest);
+        return dest;
+    }
+    /** One-line context summary for `vk run status`. */
+    static contextLine(state) {
+        const bits = [];
+        if (state.device)
+            bits.push(`device ${state.device}`);
+        if (state.session)
+            bits.push(`session ${state.session}`);
+        bits.push(`last active ${fmtAge(ageMs(state))} ago`);
+        return bits.join(' · ');
+    }
+    // --- lifecycle (vk run <sub>) ------------------------------------------
+    static status() {
+        return loadState(activeDir());
+    }
+    /** Merge a patch into the active run (used by `vk ai` to attach its summary
+     *  before archiving). No-op if there is no active run. */
+    static annotateRun(patch) {
+        const dir = activeDir();
+        const state = loadState(dir);
+        if (!state)
+            return;
+        Object.assign(state, patch);
+        saveState(dir, state);
+    }
+    /** Downgrade the most-recently-recorded step from a failed attempt to a healed
+     *  pass — the `vk ai` engine calls this after a successful repair so a
+     *  self-healed leaf does not count as a failure (and the run that the engine
+     *  considers green has a clean report). No-op if there is no active run. */
+    static markLastStepHealed(message) {
+        const dir = activeDir();
+        const state = loadState(dir);
+        if (!state || state.steps.length === 0)
+            return;
+        const last = state.steps[state.steps.length - 1];
+        last.healed = true;
+        last.status = 'passed';
+        last.exitCode = 0;
+        // The attempt that just failed had failure evidence captured (screenshot +
+        // hierarchy); drop it so a now-green healed step doesn't render as a failure.
+        delete last.failImage;
+        delete last.failHierarchy;
+        if (message)
+            last.message = message;
+        saveState(dir, state);
+    }
+    static start(name, platform, device, force) {
+        const dir = activeDir();
+        const existing = loadState(dir);
+        if (existing && existing.steps.length > 0 && !force) {
+            throw new errors_1.CliError(`A test run ('${existing.name}', ${existing.steps.length} step(s)) is already active. ` +
+                'Archive it (`vk run archive`), discard it (`vk run clear`), or pass --force to replace.', 2);
+        }
+        if ((0, node_fs_1.existsSync)(dir))
+            (0, node_fs_1.rmSync)(dir, { recursive: true, force: true });
+        const state = {
+            id: runId(),
+            name: name || 'run',
+            startedAt: nowIso(),
+            updatedAt: nowIso(),
+            platform,
+            device,
+            session: currentSession(),
+            implicit: false,
+            steps: [],
+        };
+        saveState(dir, state);
+        return state;
+    }
+    /** Discard the active run without producing a report. Returns what was cleared. */
+    static clear() {
+        const dir = activeDir();
+        const existing = loadState(dir);
+        if ((0, node_fs_1.existsSync)(dir))
+            (0, node_fs_1.rmSync)(dir, { recursive: true, force: true });
+        return existing;
+    }
+    /** Write JUnit + HTML reports and move the run into ./.verikun/runs/<id>/. */
+    static archive(name) {
+        const dir = activeDir();
+        if (!(0, node_fs_1.existsSync)(statePath(dir))) {
+            throw new errors_1.CliError('No active test run to archive. Run an action first, or `vk run start`.', 1);
+        }
+        const state = loadState(dir);
+        if (!state)
+            throw new errors_1.CliError('Active run state is unreadable (.verikun/run/run.json is corrupt).', 3);
+        if (name)
+            state.name = name;
+        const dest = Recorder.seal(state, dir);
+        return { dir: dest, xmlPath: (0, node_path_1.join)(dest, 'report.xml'), htmlPath: (0, node_path_1.join)(dest, 'report.html'), state };
+    }
+}
+exports.Recorder = Recorder;

package/dist/types.js

@@ -0,0 +1,5 @@
+"use strict";
+// Shared types for verikun. The Element model is normalized across platforms so
+// the selector / formatting / command layers are fully platform-agnostic — each
+// Driver is responsible only for producing Element[] from its native source.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/ui/android-parse.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isInteresting = isInteresting;
+exports.parseHierarchy = parseHierarchy;
+// Parses uiautomator XML (from `adb shell uiautomator dump`) into normalized
+// Element[]. We hand-roll a tiny tag scanner rather than pulling in an XML
+// dependency: uiautomator output is regular and entity-escaped, so a
+// quote-aware scan + attribute regex is robust for this specific format.
+const NAMED_ENTITIES = {
+    lt: '<',
+    gt: '>',
+    amp: '&',
+    quot: '"',
+    apos: "'",
+};
+function decodeEntities(s) {
+    return s.replace(/&(#x?[0-9a-fA-F]+|lt|gt|amp|quot|apos);/g, (whole, body) => {
+        if (body[0] === '#') {
+            const code = body[1] === 'x' || body[1] === 'X'
+                ? parseInt(body.slice(2), 16)
+                : parseInt(body.slice(1), 10);
+            return Number.isFinite(code) ? String.fromCodePoint(code) : whole;
+        }
+        return NAMED_ENTITIES[body] ?? whole;
+    });
+}
+function parseAttrs(tagBody) {
+    const attrs = {};
+    // Values are double-quoted and any literal '"' is escaped to &quot;, so [^"]*
+    // safely captures the whole value.
+    const re = /([\w:.-]+)="([^"]*)"/g;
+    let m;
+    while ((m = re.exec(tagBody))) {
+        attrs[m[1]] = decodeEntities(m[2]);
+    }
+    return attrs;
+}
+function simpleType(cls) {
+    if (!cls)
+        return 'View';
+    const parts = cls.split('.');
+    return parts[parts.length - 1] || cls;
+}
+function parseBounds(s) {
+    const m = /\[(-?\d+),(-?\d+)\]\[(-?\d+),(-?\d+)\]/.exec(s ?? '');
+    if (!m)
+        return { x1: 0, y1: 0, x2: 0, y2: 0 };
+    return { x1: +m[1], y1: +m[2], x2: +m[3], y2: +m[4] };
+}
+const asBool = (v) => v === 'true';
+function buildElement(a, depth) {
+    const cls = a['class'] ?? '';
+    const id = a['resource-id'] ?? '';
+    const bounds = parseBounds(a['bounds']);
+    return {
+        index: -1,
+        class: cls,
+        type: simpleType(cls),
+        id,
+        idShort: id.includes('/') ? id.slice(id.lastIndexOf('/') + 1) : id,
+        text: a['text'] ?? '',
+        desc: a['content-desc'] ?? '',
+        bounds,
+        center: {
+            x: Math.floor((bounds.x1 + bounds.x2) / 2),
+            y: Math.floor((bounds.y1 + bounds.y2) / 2),
+        },
+        depth,
+        clickable: asBool(a['clickable']),
+        longClickable: asBool(a['long-clickable']),
+        checkable: asBool(a['checkable']),
+        checked: asBool(a['checked']),
+        focusable: asBool(a['focusable']),
+        focused: asBool(a['focused']),
+        scrollable: asBool(a['scrollable']),
+        enabled: a['enabled'] === undefined ? true : asBool(a['enabled']),
+        selected: asBool(a['selected']),
+        password: asBool(a['password']),
+    };
+}
+/**
+ * "Interesting" = something an agent can act on or read. Pure layout containers
+ * (no text/id/desc and not interactive) are dropped to keep snapshots compact.
+ */
+function isInteresting(el) {
+    const w = el.bounds.x2 - el.bounds.x1;
+    const h = el.bounds.y2 - el.bounds.y1;
+    if (w <= 0 || h <= 0)
+        return false; // not visible / not tappable
+    if (el.text.trim())
+        return true;
+    if (el.desc.trim())
+        return true;
+    if (el.id)
+        return true;
+    if (el.clickable || el.checkable || el.scrollable || el.longClickable)
+        return true;
+    if (/EditText|AutoComplete|TextField|Edit$/.test(el.class))
+        return true;
+    return false;
+}
+function parseHierarchy(xml, opts = {}) {
+    const all = [];
+    const n = xml.length;
+    let i = 0;
+    let depth = 0;
+    while (i < n) {
+        const lt = xml.indexOf('<', i);
+        if (lt < 0)
+            break;
+        // Find the matching '>' that is not inside a quoted attribute value.
+        let j = lt + 1;
+        let inQuote = false;
+        while (j < n) {
+            const c = xml[j];
+            if (c === '"')
+                inQuote = !inQuote;
+            else if (c === '>' && !inQuote)
+                break;
+            j++;
+        }
+        if (j >= n)
+            break;
+        const tag = xml.slice(lt + 1, j);
+        i = j + 1;
+        if (tag[0] === '?' || tag[0] === '!')
+            continue; // <?xml ...?> / comments
+        if (tag[0] === '/') {
+            const closeName = tag.slice(1).trim();
+            if (closeName === 'node')
+                depth = Math.max(0, depth - 1);
+            continue;
+        }
+        const selfClosing = tag.endsWith('/');
+        const body = selfClosing ? tag.slice(0, -1) : tag;
+        const sp = body.search(/\s/);
+        const name = sp < 0 ? body : body.slice(0, sp);
+        if (name === 'node') {
+            all.push(buildElement(parseAttrs(body), depth));
+            if (!selfClosing)
+                depth++;
+        }
+    }
+    const result = opts.all ? all : all.filter(isInteresting);
+    result.forEach((el, idx) => {
+        el.index = idx;
+    });
+    return result;
+}

package/dist/ui/format.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatInline = formatInline;
+exports.formatCompact = formatCompact;
+exports.formatTree = formatTree;
+exports.toJsonShape = toJsonShape;
+// Compact one-line rendering tuned for AI agents: dense, scannable, and using
+// the same `@idShort` token that the selector grammar accepts, so an element
+// printed here can be copy-pasted straight back into a `tap`/`find` command.
+function clip(s, max) {
+    return s.length > max ? s.slice(0, max - 1) + '…' : s;
+}
+function formatInline(el) {
+    const parts = [`[${el.index}]`, el.type];
+    if (el.text.trim())
+        parts.push(JSON.stringify(clip(el.text, 60)));
+    if (el.idShort)
+        parts.push('@' + el.idShort);
+    if (el.desc.trim() && el.desc !== el.text)
+        parts.push('desc=' + JSON.stringify(clip(el.desc, 40)));
+    parts.push(`(${el.center.x},${el.center.y})`);
+    const flags = [];
+    if (el.clickable)
+        flags.push('tap');
+    if (el.scrollable)
+        flags.push('scroll');
+    if (el.checkable)
+        flags.push(el.checked ? 'checked' : 'unchecked');
+    if (el.focused)
+        flags.push('focused');
+    if (el.password)
+        flags.push('pwd');
+    if (el.selected)
+        flags.push('selected');
+    if (!el.enabled)
+        flags.push('disabled');
+    if (flags.length)
+        parts.push(flags.join(','));
+    return parts.join(' ');
+}
+function formatCompact(elements) {
+    if (!elements.length)
+        return '(no elements)';
+    return elements.map(formatInline).join('\n');
+}
+function formatTree(elements) {
+    if (!elements.length)
+        return '(no elements)';
+    return elements.map((el) => '  '.repeat(el.depth) + formatInline(el)).join('\n');
+}
+/** Structured shape for --json. Omits empty/false fields to stay compact. */
+function toJsonShape(el) {
+    return {
+        index: el.index,
+        type: el.type,
+        class: el.class,
+        id: el.id || undefined,
+        text: el.text || undefined,
+        desc: el.desc || undefined,
+        center: el.center,
+        bounds: el.bounds,
+        clickable: el.clickable || undefined,
+        scrollable: el.scrollable || undefined,
+        checkable: el.checkable || undefined,
+        checked: el.checkable ? el.checked : undefined,
+        focused: el.focused || undefined,
+        password: el.password || undefined,
+        enabled: el.enabled,
+        selected: el.selected || undefined,
+    };
+}