simulator-use 0.0.0-stage → 0.8.0

package/dist/engine/xcresult.js

@@ -0,0 +1,95 @@
+import { readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { run } from "./exec.js";
+/** Failures as Xcode records them: the test, and "File.swift:12: message" for each failed assertion. */
+export function failuresIn(nodes, bundle = "") {
+    const out = [];
+    for (const node of nodes) {
+        if (node.nodeType === "Test Case" && node.result === "Failed") {
+            const messages = [];
+            const collect = (n) => {
+                if (n.nodeType === "Failure Message" && n.name)
+                    messages.push(n.name);
+                n.children?.forEach(collect);
+            };
+            node.children?.forEach(collect);
+            // The identifier already holds the suite (SignInTests/testX()); the bundle makes it -only-testing ready.
+            const id = node.nodeIdentifier ?? node.name ?? "?";
+            const test = [bundle, id].filter(Boolean).join("/");
+            for (const message of messages.length ? messages : ["failed (no message recorded)"])
+                out.push({ test, id, message });
+        }
+        else if (node.children) {
+            out.push(...failuresIn(node.children, /test bundle$/i.test(node.nodeType ?? "") ? (node.name ?? bundle) : bundle));
+        }
+    }
+    return out;
+}
+export async function readTestReport(bundle) {
+    // Right after xcodebuild exits, one read of a finished bundle failed once; the same read a moment later worked.
+    const get = async (what, more = []) => {
+        const args = ["xcresulttool", "get", "test-results", what, ...more, "--path", bundle];
+        const out = await run("xcrun", args, { timeoutMs: 60_000 }).catch(async () => {
+            await new Promise((r) => setTimeout(r, 1_000));
+            return run("xcrun", args, { timeoutMs: 60_000 });
+        });
+        return JSON.parse(out.stdout);
+    };
+    const [summary, tests] = await Promise.all([get("summary"), get("tests")]);
+    const failures = failuresIn(tests.testNodes ?? []);
+    // Xcode 26 starts a failure message with "File.swift:12: "; Xcode 27 keeps the place in the test's details.
+    for (const f of failures.filter((x) => !/^[^\s/:]+\.\w+:\d+: /.test(x.message)).slice(0, 10)) {
+        const details = await get(`test-details`, ["--test-id", f.id]).catch(() => undefined);
+        const place = details && sourceLocation(details.testRuns ?? []);
+        if (place?.filePath)
+            Object.assign(f, { file: place.filePath, line: place.lineNumber });
+    }
+    return {
+        result: summary.result,
+        passed: summary.passedTests ?? 0,
+        failed: summary.failedTests ?? 0,
+        skipped: summary.skippedTests ?? 0,
+        total: summary.totalTestCount ?? 0,
+        failures,
+    };
+}
+/** The first source location in a test's details: where the failed assertion is. */
+export function sourceLocation(nodes) {
+    for (const node of nodes) {
+        if (node.sourceLocation?.filePath)
+            return node.sourceLocation;
+        const inner = sourceLocation(node.children ?? []);
+        if (inner)
+            return inner;
+    }
+    return undefined;
+}
+/** "SignInTests.swift:12: ..." names the file only; this finds it in the project to give its path. */
+export function locate(message, projectDir) {
+    const match = /^([^\s/:]+\.(?:swift|m|mm)):(\d+): /.exec(message);
+    if (!match)
+        return message;
+    const found = [];
+    const walk = (dir, depth) => {
+        if (depth > 6 || found.length > 1)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.startsWith(".") || /^(DerivedData|build|Pods|node_modules|Carthage)$/.test(entry) || entry.endsWith(".xcodeproj") || entry.endsWith(".xcworkspace"))
+                continue;
+            const full = join(dir, entry);
+            if (entry === match[1])
+                found.push(full);
+            else if (statSync(full).isDirectory())
+                walk(full, depth + 1);
+        }
+    };
+    walk(projectDir, 0);
+    return found.length === 1 ? `${relative(projectDir, found[0])}${message.slice(match[1].length)}` : message;
+}

package/dist/errors.js

@@ -0,0 +1,11 @@
+/** A failure the agent can act on: what went wrong, and the next step. */
+export class ToolError extends Error {
+    next;
+    constructor(message, next) {
+        super(message);
+        this.next = next;
+    }
+    toText() {
+        return this.next ? `${this.message}\nNext: ${this.next}` : this.message;
+    }
+}

package/dist/look/read.js

@@ -0,0 +1,50 @@
+import { setTimeout as sleep } from "node:timers/promises";
+import { AccessibilityStarting, describeUi } from "../engine/axe.js";
+import { render, snapshot } from "./snapshot.js";
+/** Right after a launch the app's accessibility tree is empty for a moment (seen on Xcode 27). */
+const NOT_READY_RETRIES = 4;
+const NOT_READY_WAIT_MS = 750;
+const SETTLE_START_MS = 120;
+const SETTLE_TIMEOUT_MS = 4_000;
+/** How long a call keeps trying while accessibility starts, leaving room in the 45 s a call may take. */
+const STARTING_BUDGET_MS = 35_000;
+/** Reads the tree, waiting out a starting accessibility service for up to 35 s before giving up. */
+async function describeWhenReady(udid) {
+    const deadline = Date.now() + STARTING_BUDGET_MS;
+    for (;;) {
+        try {
+            return await describeUi(udid);
+        }
+        catch (error) {
+            if (!(error instanceof AccessibilityStarting) || Date.now() > deadline)
+                throw error;
+            await sleep(1_000);
+        }
+    }
+}
+export async function readScreen(udid, waitUntilReady = true) {
+    let tree = await describeWhenReady(udid);
+    let snap = snapshot(tree);
+    for (let i = 0; waitUntilReady && i < NOT_READY_RETRIES && !snap.elements.length && !snap.tabs.length; i++) {
+        await sleep(NOT_READY_WAIT_MS);
+        tree = await describeUi(udid);
+        snap = snapshot(tree);
+    }
+    return { tree, snap };
+}
+/**
+ * Waits for the screen to stop changing after an action: two reads in a row that look the same.
+ * `settled: false` means it was still moving at the timeout (an animation, a ticker, a spinner).
+ */
+export async function settle(udid) {
+    const deadline = Date.now() + SETTLE_TIMEOUT_MS;
+    await sleep(SETTLE_START_MS);
+    let last = (await readScreen(udid, false)).snap;
+    while (Date.now() < deadline) {
+        const next = (await readScreen(udid, false)).snap;
+        if (render(next) === render(last))
+            return { snap: next, settled: true };
+        last = next;
+    }
+    return { snap: last, settled: false };
+}

package/dist/look/snapshot.js

@@ -0,0 +1,459 @@
+/**
+ * Turns the Simulator's accessibility tree (AXe describe-ui JSON) into the compact screen an agent reads:
+ * one line per element with its kind, label, #id, state and @x,y center in points. Groups, decorations,
+ * scroll bars and the on-screen keyboard's keys are folded away; the tab bar and scrolling become one line each.
+ *
+ * Only what can be tapped is listed: a sheet, a full-screen cover or an alert hides the screen behind it,
+ * and content under the navigation bar, the tab bar or the keyboard is counted as hidden instead.
+ */
+/** UIKit's keyboard, its suggestion bar and the view holding both: shown to the agent as one line. */
+const KEYBOARD_IDS = new Set(["inputView", "UIKeyboardLayoutStar Preview", "SystemInputAssistantView"]);
+const STATUS_BAR_BOTTOM = 50;
+const SCROLL_BAR = /^(Vertical|Horizontal) scroll bar, (\d+) pages?$/;
+const CONTROLS = new Set(["button", "back", "tab", "segment", "link", "cell", "switch", "checkbox", "radio", "slider", "stepper", "popup", "menu", "picker", "textfield", "securefield", "searchfield", "textview"]);
+const FIELDS = new Set(["textfield", "securefield", "searchfield", "textview"]);
+/** UIKit names a navigation bar after its view controller's class when it has no title. */
+const MANGLED = /^_Tt|^[A-Za-z0-9]+(Controller|Hosting)$/;
+const ROLE_KINDS = {
+    AXButton: "button",
+    AXLink: "link",
+    AXCell: "cell",
+    AXStaticText: "text",
+    AXHeading: "heading",
+    AXImage: "image",
+    AXTextField: "textfield",
+    AXSearchField: "searchfield",
+    AXTextView: "textview",
+    AXTextArea: "textview",
+    AXSlider: "slider",
+    AXIncrementor: "stepper",
+    AXPopUpButton: "popup",
+    AXMenuButton: "menu",
+    AXPicker: "picker",
+    AXPickerWheel: "picker",
+    AXProgressIndicator: "progress",
+    AXRadioButton: "radio",
+    AXCheckBox: "checkbox",
+    AXSheet: "alert",
+    AXGenericElement: "element",
+};
+/** Roles that only hold other elements. */
+const CONTAINERS = new Set(["", "AXGroup", "AXApplication", "AXScrollArea", "AXWindow", "AXTabGroup", "AXSegmentedControl"]);
+function kindOf(node, inTabGroup) {
+    const role = node.role ?? "";
+    if (role === "AXButton" && node.role_description === "back button")
+        return "back";
+    if (role === "AXTextField" && node.subrole === "AXSecureTextField")
+        return "securefield";
+    if (role === "AXCheckBox" && node.subrole === "AXSwitch")
+        return "switch";
+    // A tab button inside a tab group is a segment of a segmented control; any other is a tab: in the iPhone's
+    // tab bar, or in the iPad's, which sits at the top with no "Tab Bar" group around it.
+    if (role === "AXRadioButton" && node.subrole === "AXTabButton")
+        return inTabGroup ? "segment" : "tab";
+    if (ROLE_KINDS[role])
+        return ROLE_KINDS[role];
+    if (CONTAINERS.has(role))
+        return null;
+    // Anything else with a name still matters (maps, web links): name it after its role.
+    return (node.role_description || role.replace(/^AX/, "")).toLowerCase().replace(/\s+/g, "");
+}
+const text = (value) => (value === null || value === undefined ? "" : String(value).trim());
+const center = (f) => ({ x: Math.round(f.x + f.width / 2), y: Math.round(f.y + f.height / 2) });
+const inside = (point, f) => point.x >= f.x && point.x < f.x + f.width && point.y >= f.y && point.y < f.y + f.height;
+const area = (f) => Math.max(0, f.width) * Math.max(0, f.height);
+const isTabBar = (n) => n.AXLabel === "Tab Bar" || n.role_description === "tab bar";
+const isNavBar = (n) => n.role_description?.toLowerCase() === "nav bar";
+/** The part of a frame on screen, below the navigation bar and above the tab bar, or null when none of it is. */
+function visible(f, screen, floor, ceiling = screen.y) {
+    const x = Math.max(f.x, screen.x);
+    const y = Math.max(f.y, ceiling);
+    const right = Math.min(f.x + f.width, screen.x + screen.width);
+    const bottom = Math.min(f.y + f.height, floor);
+    if (right - x < 1 || bottom - y < 1)
+        return null;
+    return { x, y, width: right - x, height: bottom - y };
+}
+function* walkAll(nodes) {
+    for (const n of nodes) {
+        yield n;
+        yield* walkAll(n.children ?? []);
+    }
+}
+function isKeyboard(node) {
+    if (node.AXUniqueId && KEYBOARD_IDS.has(node.AXUniqueId))
+        return true;
+    // Other layouts: a group holding a row of single-character keys.
+    const keys = (node.children ?? []).filter((c) => c.role === "AXButton" && text(c.AXLabel).length === 1).length;
+    return keys >= 8;
+}
+/** Whether a subtree holds anything an agent could read: a labeled element that isn't a scroll bar or the keyboard. */
+function readable(node) {
+    if (isKeyboard(node))
+        return false;
+    const label = text(node.AXLabel);
+    if (!CONTAINERS.has(node.role ?? "") && (label || text(node.AXUniqueId)) && !SCROLL_BAR.test(label))
+        return true;
+    return (node.children ?? []).some(readable);
+}
+/** Whether a node itself (not its children) has something to read. */
+function readableOwn(n) {
+    const label = text(n.AXLabel);
+    return !CONTAINERS.has(n.role ?? "") && Boolean(label || text(n.AXUniqueId)) && !SCROLL_BAR.test(label) && !isKeyboard(n);
+}
+/**
+ * The box a presented layer occupies: down through the containers with one readable child, to the last one
+ * that still holds everything readable. A sheet's is its card (from y 62 on an iPhone), a cover's the screen.
+ */
+function box(node) {
+    let at = node;
+    let frame = node.frame;
+    for (;;) {
+        const inner = (at.children ?? []).filter(readable);
+        if (inner.length !== 1 || !CONTAINERS.has(inner[0].role ?? ""))
+            return frame;
+        at = inner[0];
+        if (at.frame && area(at.frame) > 0)
+            frame = at.frame;
+    }
+}
+/**
+ * What is in front. An alert (an AXSheet: the app's own, or iOS's permission prompts) always is. Otherwise a
+ * presented sheet or full-screen cover is a later sibling of the screen it covers, near the top of the tree:
+ * at the first place the tree splits into readable parts, a later part that covers most of the screen and has
+ * something to tap or a navigation bar is in front. A later part that is small (a tab bar, a toast) is not.
+ */
+function frontLayer(roots, screen) {
+    let alert;
+    for (const n of walkAll(roots))
+        if (n.role === "AXSheet" && readable(n))
+            alert = n;
+    if (alert)
+        return { nodes: [alert], modal: "alert" };
+    let level = roots;
+    for (let depth = 0; depth < 40; depth++) {
+        const parts = level.filter(readable);
+        if (parts.length >= 2) {
+            for (let i = parts.length - 1; i > 0; i--) {
+                const part = parts[i];
+                const frame = box(part);
+                const large = frame && area(frame) >= area(screen) * 0.5;
+                const actionable = [...walkAll([part])].some((n) => isNavBar(n) || CONTROLS.has(kindOf(n, false) ?? ""));
+                // Something must be behind it: on an iPad the tab bar is its own part before the screen, and a screen
+                // after a part that only holds tabs is just the screen. What it covers is a screen too: iOS 27's large
+                // title is its own small part before the list, and a list after a title strip is just the screen.
+                const behind = parts
+                    .slice(0, i)
+                    .some((p) => (area(box(p) ?? { x: 0, y: 0, width: 0, height: 0 }) >= area(screen) * 0.3) && [...walkAll([p])].some((n) => readableOwn(n) && n.subrole !== "AXTabButton" && !isTabBar(n)));
+                if (large && actionable && behind && ![...walkAll([part])].some(isTabBar))
+                    return { nodes: [part], modal: "screen" };
+            }
+            return { nodes: roots };
+        }
+        if (parts.length === 0)
+            return { nodes: roots };
+        level = parts[0].children ?? [];
+    }
+    return { nodes: roots };
+}
+/** The on-screen keyboard's frame, or undefined when there is none or it is off screen (a hardware keyboard). */
+function keyboardFrame(nodes, screen) {
+    let found;
+    for (const n of walkAll(nodes)) {
+        if (!isKeyboard(n) || !n.frame)
+            continue;
+        const part = visible(n.frame, screen, screen.y + screen.height);
+        if (part && (!found || part.y < found.y))
+            found = { ...part, height: screen.y + screen.height - part.y };
+    }
+    return found;
+}
+/** A switch row's unnamed twin is its knob: tapping the row's middle doesn't toggle it, tapping the knob does. */
+function knob(owner, point) {
+    if (owner.kind === "switch") {
+        owner.x = point.x;
+        owner.y = point.y;
+    }
+    return true;
+}
+function stateOf(kind, node) {
+    const value = text(node.AXValue);
+    const parts = [];
+    if (kind === "switch" || kind === "checkbox")
+        parts.push(value === "1" ? "on" : "off");
+    if ((kind === "tab" || kind === "segment" || kind === "radio") && value === "1")
+        parts.push("selected");
+    if (node.enabled === false)
+        parts.push("disabled");
+    return parts.length ? parts.join(" ") : undefined;
+}
+/** A slider's 0.30000001192092896 reads as 0.3. */
+function tidy(value) {
+    return /^-?\d+\.\d{4,}$/.test(value) ? String(Number(Number(value).toFixed(2))) : value;
+}
+/** The app's name; SpringBoard (the home screen, and iOS's own alerts over an app) has none. */
+function appName(app, roots, modal) {
+    const own = text(app.AXLabel);
+    if (own)
+        return own;
+    // SpringBoard's tree with an app's card in it: iOS is showing something over that app. A permission prompt
+    // is an alert; the contacts or photos pickers that follow are drawn by other processes and can't be read.
+    const card = [...walkAll(roots)].find((n) => text(n.AXUniqueId).startsWith("card:"));
+    const name = card ? text(card.AXLabel) : "";
+    if (modal === "alert")
+        return name ? `${name} · system alert` : "System alert";
+    return name ? `${name} · system screen` : "Home screen";
+}
+export function snapshot(tree) {
+    const roots = Array.isArray(tree) ? tree : [tree];
+    const app = roots.find((n) => n.role === "AXApplication") ?? roots[0] ?? {};
+    const screen = app.frame ?? { x: 0, y: 0, width: 0, height: 0 };
+    const front = frontLayer(roots, screen);
+    const result = {
+        app: appName(app, roots, front.modal),
+        elements: [],
+        tabs: [],
+        keyboard: false,
+        hidden: { above: 0, below: 0, left: 0, right: 0 },
+        unreadable: [],
+        screen,
+        ...(front.modal ? { modal: front.modal } : {}),
+    };
+    const nodes = front.nodes;
+    // Content scrolls under the navigation bar and the tab bar: a tap there hits the bar, not the content.
+    // With navigation inside navigation (UIKit in SwiftUI), the innermost bar is the lowest.
+    const all = [...walkAll(nodes)];
+    const tabBar = all.find(isTabBar)?.frame;
+    const navBars = all.filter((n) => isNavBar(n) && n.frame && n.frame.y < screen.y + screen.height / 3);
+    const navBar = navBars.reduce((low, n) => (!low || n.frame.y + n.frame.height > low.frame.y + low.frame.height ? n : low), undefined);
+    const barFrames = new Set([tabBar, ...navBars.map((n) => n.frame)].filter(Boolean));
+    // The title: the heading in the innermost navigation bar, or its name when that is a real title.
+    const navTitle = navBar && (navBar.children ?? []).find((c) => c.role === "AXHeading" && text(c.AXLabel));
+    const navName = text(navBar?.AXUniqueId);
+    if (navTitle)
+        result.title = text(navTitle.AXLabel);
+    else if (navName && !MANGLED.test(navName))
+        result.title = navName;
+    // An on-screen keyboard covers the bottom of the screen, tab bar included; its own bottom row (Emoji,
+    // Dictate) sits outside its groups on iOS 27, so everything whose middle is under it is left out.
+    const keyboard = keyboardFrame(roots, screen);
+    result.keyboard = Boolean(keyboard);
+    if (keyboard)
+        result.keyboardTop = Math.round(keyboard.y);
+    const bottom = keyboard ? keyboard.y : screen.y + screen.height;
+    const floor = tabBar ? Math.min(tabBar.y, bottom) : bottom;
+    const ceiling = navBar?.frame ? navBar.frame.y + navBar.frame.height : screen.y;
+    // The main scroller: the tallest vertical scroll bar. Carousels and an alert's own scrolling are not it.
+    let mainScroll;
+    for (const n of all) {
+        const m = SCROLL_BAR.exec(text(n.AXLabel));
+        if (!m || m[1] !== "Vertical" || !n.frame || n.frame.height < screen.height * 0.4)
+            continue;
+        if (!mainScroll || n.frame.height > mainScroll.height)
+            mainScroll = { pages: Number(m[2]), at: text(n.AXValue), height: n.frame.height };
+    }
+    // An alert's own scrolling text is not the screen's.
+    if (mainScroll && mainScroll.pages > 1 && front.modal !== "alert")
+        result.scroll = `${mainScroll.pages} pages, at ${mainScroll.at === "0%" ? "top" : mainScroll.at === "100%" ? "bottom" : mainScroll.at}`;
+    const hide = (f) => {
+        const c = center(f);
+        if (c.x < screen.x)
+            result.hidden.left++;
+        else if (c.x > screen.x + screen.width)
+            result.hidden.right++;
+        else if (c.y < (ceiling + floor) / 2)
+            result.hidden.above++;
+        else
+            result.hidden.below++;
+    };
+    const walk = (node, owner, inBar, inTabGroup, parentLabel) => {
+        if (isKeyboard(node))
+            return;
+        const nowInBar = inBar || barFrames.has(node.frame);
+        const kind = kindOf(node, inTabGroup);
+        const label = text(node.AXLabel);
+        const id = text(node.AXUniqueId);
+        if (SCROLL_BAR.test(label))
+            return;
+        // A large area with nothing readable inside: a web view, a map, a game, custom drawing.
+        if ((node.role === "AXScrollArea" || node.role === "AXWebArea") && node.frame && area(node.frame) >= area(screen) * 0.15 && !readable(node)) {
+            const shown = visible(node.frame, screen, floor, ceiling);
+            if (shown)
+                result.unreadable.push(shown);
+            return;
+        }
+        let element = null;
+        // A zero-size node is a container (a home screen page, a folder) whose children have their own frames.
+        const sized = node.frame && node.frame.width > 0 && node.frame.height > 0;
+        if (kind && node.frame && sized) {
+            // Bars' own buttons, and tabs (an iPad's float over the navigation bar), are never under a bar.
+            const onBar = nowInBar || kind === "tab";
+            const shown = onBar ? visible(node.frame, screen, bottom) : visible(node.frame, screen, floor, ceiling);
+            const point = shown ? center(shown) : null;
+            if (keyboard && (!shown || inside(center(node.frame), keyboard)))
+                return;
+            const covered = point && !onBar && tabBar && inside(point, tabBar);
+            if (!shown || covered) {
+                if (label || id)
+                    hide(node.frame);
+                return;
+            }
+            let value = tidy(text(node.AXValue));
+            if (kind === "switch" || kind === "checkbox" || kind === "tab" || kind === "segment" || kind === "radio")
+                value = "";
+            // A field with no label shows its placeholder or its text as the value; name it by that.
+            const name = label || (FIELDS.has(kind) ? value : "");
+            if (name === value)
+                value = "";
+            const skip = 
+            // The title is in the header line.
+            (kind === "heading" && name === result.title) ||
+                (kind === "image" && (!label || owner !== null)) ||
+                // Inside a control: its own text and icons repeat its label; an unnamed twin (a switch's knob) adds nothing.
+                (owner !== null && !CONTROLS.has(kind) && (!name || Boolean(owner.label?.includes(name)))) ||
+                (owner !== null && kind === owner.kind && !name && knob(owner, point)) ||
+                // A control nested in its twin (an iPad tab inside a tab of the same name) is the same control.
+                (owner !== null && kind === owner.kind && name === owner.label) ||
+                // An alert's title repeats as its first text.
+                (kind === "text" && name === parentLabel) ||
+                // UIKit's disclosure arrow in a table cell is a disabled button named "chevron".
+                (kind === "button" && node.enabled === false && /^chevron/.test(name)) ||
+                (!name && !id && !CONTROLS.has(kind)) ||
+                // The status bar (time, signal, battery) only appears in SpringBoard's tree; it is noise there.
+                (owner === null && (kind === "text" || kind === "element") && node.frame.y + node.frame.height <= STATUS_BAR_BOTTOM);
+            if (!skip) {
+                element = { kind, x: point.x, y: point.y, frame: node.frame };
+                if (name)
+                    element.label = name;
+                if (id)
+                    element.id = id;
+                if (value)
+                    element.value = value;
+                const state = stateOf(kind, node);
+                if (state)
+                    element.state = state;
+                if (kind === "tab")
+                    result.tabs.push(element);
+                else {
+                    const last = result.elements.at(-1);
+                    if (!last || line(last) !== line(element))
+                        result.elements.push(element);
+                }
+            }
+        }
+        const nextOwner = element && CONTROLS.has(element.kind) ? element : owner;
+        for (const child of node.children ?? [])
+            walk(child, nextOwner, nowInBar, node.role === "AXTabGroup", label || parentLabel);
+    };
+    nodes.forEach((root) => walk(root, null, false, false, ""));
+    result.elements = withoutLetterRuns(withoutRepeatedLabels(result.elements));
+    return result;
+}
+/**
+ * Text animated letter by letter is one element per character ("E", "v", "e", ...): a run of four or more
+ * one-character texts on one line becomes one line, or goes when another element already says the phrase.
+ */
+function withoutLetterRuns(elements) {
+    const out = [];
+    const letter = (e) => e?.kind === "text" && e.label !== undefined && [...e.label].length <= 2 && !e.id;
+    for (let i = 0; i < elements.length;) {
+        let j = i;
+        while (letter(elements[j]) && Math.abs(elements[j].y - elements[i].y) <= 4)
+            j++;
+        if (j - i < 4) {
+            out.push(elements[i]);
+            i++;
+            continue;
+        }
+        const run = elements.slice(i, j);
+        const word = run.map((e) => e.label).join("");
+        const squash = (s) => s.replace(/\s+/g, "").toLowerCase();
+        if (!elements.some((e) => e.label && !letter(e) && squash(e.label) === squash(word))) {
+            const left = Math.min(...run.map((e) => e.frame.x));
+            const right = Math.max(...run.map((e) => e.frame.x + e.frame.width));
+            const top = Math.min(...run.map((e) => e.frame.y));
+            const frame = { x: left, y: top, width: right - left, height: Math.max(...run.map((e) => e.frame.height)) };
+            out.push({ kind: "text", label: word, x: Math.round(left + frame.width / 2), y: run[0].y, frame });
+        }
+        i = j;
+    }
+    return out;
+}
+/**
+ * A text beside a control that says the same thing ("Count: 2" next to its stepper, "Flavor" next to the
+ * "Flavor, Vanilla" picker, "Date" next to its date picker) is the control's own label: one line is enough.
+ */
+function withoutRepeatedLabels(elements) {
+    const controls = elements.filter((e) => CONTROLS.has(e.kind) && e.label);
+    return elements.filter((e) => {
+        // Plain text, and the unnamed-role elements a picker leaves after its menu closes.
+        if ((e.kind !== "text" && e.kind !== "element") || !e.label)
+            return true;
+        const t = e.label;
+        return !controls.some((c) => Math.abs(c.y - e.y) <= 12 && (c.label === t || c.label.startsWith(`${t},`) || c.label.startsWith(`${t} `)));
+    });
+}
+/** App text printed without quotes (the header, tab names) stays on its line: a newline in it can't start a fake one. */
+export const oneLine = (s) => s.replace(/[\u0000-\u001f\u007f\u2028\u2029]+/g, " ").trim();
+export const quote = (s) => JSON.stringify(s.length > 80 ? `${s.slice(0, 79)}…` : s);
+/** `#signIn`, or `#"pay now"` when the id isn't a plain word. */
+export const ref = (id) => `#${/^[\w.:-]+$/.test(id) ? id : quote(id)}`;
+/** One element as the agent reads it: `button "Sign In" #signIn @201,350`. */
+export function line(e) {
+    let out = e.kind;
+    if (e.label !== undefined)
+        out += ` ${quote(e.label)}`;
+    if (e.id && e.id !== e.label)
+        out += ` ${ref(e.id)}`;
+    if (e.value)
+        out += ` =${quote(e.value)}`;
+    if (e.state)
+        out += ` ${e.state}`;
+    return `${out} @${e.x},${e.y}`;
+}
+export function render(snap, options = {}) {
+    // A screen titled like its app (Settings · Settings) is named once.
+    const header = [snap.app, snap.title === snap.app ? undefined : snap.title, options.device].filter(Boolean).map((part) => oneLine(part)).join(" · ");
+    let elements = snap.elements;
+    const lines = [header];
+    if (options.find) {
+        const needle = options.find.toLowerCase();
+        const matches = (e) => [e.label, e.id, e.value].some((v) => v?.toLowerCase().includes(needle));
+        elements = [...elements, ...snap.tabs].filter(matches);
+        if (!elements.length) {
+            lines.push(`No element matches ${quote(options.find)} (${snap.elements.length + snap.tabs.length} on screen).\nNext: ui_look without find lists them.`);
+            return lines.join("\n");
+        }
+    }
+    if (snap.modal === "alert")
+        lines.push("An alert is in front: answer it with one of its buttons.");
+    else if (snap.modal === "screen")
+        lines.push("Something is in front (a sheet, menu or full-screen view); the screen behind it is not listed.");
+    const max = options.maxLines ?? 150;
+    for (const e of elements.slice(0, max))
+        lines.push(line(e));
+    if (elements.length > max)
+        lines.push(`… ${elements.length - max} more; use find to narrow`);
+    if (options.find)
+        return lines.join("\n");
+    for (const f of snap.unreadable) {
+        const c = center(f);
+        lines.push(`unreadable @${c.x},${c.y} (${Math.round(f.width)}x${Math.round(f.height)}): a web view, custom drawing or an iOS system screen; ui_look with screenshot shows it, then tap @x,y`);
+    }
+    // React Native apps often set a test id as the accessibility label: the screen then shows other text.
+    const idLike = elements.filter((e) => e.kind === "text" && e.label && /^[a-z0-9]+(?:[-_][a-z0-9]+)+$/.test(e.label)).map((e) => e.label);
+    if (idLike.length)
+        lines.push(`note: ${idLike.slice(0, 3).map((l) => quote(l)).join(", ")} ${idLike.length === 1 ? "is a test id the app set as its label" : "are test ids the app set as labels"}; the text on screen differs, and ui_look with screenshot shows it`);
+    if (snap.tabs.length)
+        lines.push(`tabs: ${snap.tabs.map((t) => `${oneLine(t.label ?? t.id ?? "")}${t.state ? ` (${t.state})` : ""} @${t.x},${t.y}`).join(", ")}`);
+    const { above, below, left, right } = snap.hidden;
+    const more = [snap.scroll, above && `${above} above`, below && `${below} below`, left && `${left} to the left`, right && `${right} to the right`].filter(Boolean);
+    if (more.length)
+        lines.push(`scroll: ${more.join("; ")}`);
+    if (snap.keyboard)
+        lines.push(`keyboard: shown, covering y ${snap.keyboardTop ?? "?"} and below`);
+    if (!snap.elements.length && !snap.tabs.length && !snap.unreadable.length) {
+        lines.push("Nothing readable on screen yet. The app may still be launching, or it shows no accessibility elements; a screenshot shows what is there.");
+    }
+    return lines.join("\n");
+}