@melaya/runner 1.1.73 → 1.1.75

package/dist/computerPause.d.ts

@@ -0,0 +1,179 @@
+export type PauseRec = Record<string, unknown>;
+export interface PauseRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Where a run stopped / continues: batch step, then stroke / point / frac inside a path (contract ComputerResumePoint). */
+export interface PausePosition {
+    step?: number;
+    stroke?: number;
+    point?: number;
+    frac?: number;
+}
+/** How far a cancelled path / drag got, as the helper reports it (contract ComputerPathProgress). */
+export interface PauseProgress {
+    stroke?: number;
+    point?: number;
+    frac?: number;
+    pressed?: boolean;
+}
+/** What the pauses of one command did (contract ComputerPauseReport). */
+export interface PauseReport {
+    count: number;
+    pausedMs: number;
+    refocused?: number;
+    moved?: boolean;
+    resumedStrokes?: number;
+}
+/** The part of a ComputerResult the engine reads. */
+export interface PauseResult {
+    ok: boolean;
+    kind?: string;
+    text?: string;
+    error?: {
+        code?: string;
+        message?: string;
+    };
+    [k: string]: unknown;
+}
+export interface PauseWindow {
+    windowId: string;
+    appId?: string;
+    title?: string;
+    bounds: PauseRect;
+    focused?: boolean;
+    minimized?: boolean;
+}
+export declare const PAUSE_DEFAULTS: {
+    /** The user must be idle this long before the run goes on. */
+    readonly quietMs: 1500;
+    /** One pause lasts at most this long; then the run stops with user_interrupted and a resume point. */
+    readonly maxPauseMs: 60000;
+    /** Pause time the server grants per command on top of its deadline. */
+    readonly budgetMs: 180000;
+    /** A step interrupted more often than this stops (the user keeps taking over). */
+    readonly maxResumesPerStep: 20;
+    /** Time kept back before the deadline: a pause ends in time to report where it stopped. */
+    readonly reserveMs: 1500;
+};
+/** Reads that send no input: they run while the user is busy. Everything else waits until the user is idle. */
+export declare const PAUSE_PASSIVE_KINDS: ReadonlySet<string>;
+/** Pointer streams cancelled the moment the user takes over (never fight for the cursor); short atomic writes finish. */
+export declare const PAUSE_CANCEL_KINDS: ReadonlySet<string>;
+export declare function pauseNeedsIdle(kind: string): boolean;
+export declare function pauseRectMoved(a: PauseRect, b: PauseRect, tol?: number): boolean;
+export declare function pauseRectResized(a: PauseRect, b: PauseRect, tol?: number): boolean;
+type PausePt = number[];
+/**
+ * The rest of one stroke from (point, frac): it starts on the last sample the pointer reached (pressed again there,
+ * one sample of overlap, no gap, nothing drawn twice beyond it), then every later point; times are shifted to start at
+ * 0. null when nothing is left (the stroke had reached its last point).
+ */
+export declare function pauseTrimStroke(stroke: PausePt[], point: number, frac: number): PausePt[] | null;
+/** A path from a position (strokes before `stroke` are done, that stroke goes on from point / frac); null when nothing is left. */
+export declare function pauseTrimPath(action: PauseRec, pos: PausePosition): PauseRec | null;
+/**
+ * The helper's progress on a path that was itself cut at `base`, as a position in the ORIGINAL path. The cut path's
+ * point 0 is the re-pressed sample on base segment (point -> point + 1); its point k >= 1 is base point + k.
+ */
+export declare function pauseAbsolute(base: PausePosition, rel: PauseProgress): PausePosition;
+/** A resumeFrom as a position (step, stroke, point: whole numbers >= 0; frac in 0..1); null when absent. */
+export declare function pausePositionOf(v: unknown): PausePosition | null;
+/**
+ * A window / region path moved with its window (same size only: a canvas does not scale with its window, so a resized
+ * window stops the run). null when it cannot follow (screen pixels, or resized).
+ */
+export declare function pauseShiftPath(action: PauseRec, from: PauseRect, to: PauseRect): PauseRec | null;
+/**
+ * One step after its window moved from `from` to `to`: window / region paths move with it; points in screen pixels
+ * and refs bound to a screen taken before the move cannot follow (null: stop there); a label is found again (its
+ * snapshot binding is dropped). Steps on other windows, or without coordinates, are unchanged.
+ */
+export declare function pauseShiftStep(step: PauseRec, from: PauseRect, to: PauseRect): PauseRec | null;
+export type PauseStopReason = "stopped" | "max_pause" | "deadline" | "window_closed" | "dialog" | "moved" | "refocus" | "repress" | "dropped" | "unknown_progress" | "stale" | "too_many";
+export interface PauseStop {
+    reason: PauseStopReason;
+    message: string;
+    /** Inside a path: where it stopped (stroke / point / frac in the step's original strokes). */
+    at?: PausePosition;
+}
+/** What the executor needs from its host. Every command goes through `exec` (the host's own checks apply). */
+export interface PauseHost {
+    now(): number;
+    sleep(ms: number): Promise<void>;
+    /** Runs one helper command (never batch / handoff / keep_awake) and resolves with its result, cancelled or not. */
+    exec(action: PauseRec, id: string): Promise<PauseResult>;
+    /** Cancels one running command for a pause; its (stopped) result, with `progress`, still resolves `exec`. */
+    cancel(id: string): void;
+    /** Releases every key and mouse button the helper holds. */
+    release(): void;
+    /** The command was answered elsewhere (Stop, the deadline, the app closing): stop waiting, act on nothing. */
+    ended(): boolean;
+    /** Time left before the command's deadline (ms). */
+    timeLeft(): number;
+    /** Pushes the deadline back by up to `ms` from the pause budget (negative: gives time back); returns what moved. */
+    extend(ms: number): number;
+    /** Time of the last real user input the host saw (0: none). */
+    lastInputAt(): number;
+    /** The helper refused because someone is using the computer: start a new quiet period from now. */
+    markInput(): void;
+    /** Shows / hides "Paused while you use the computer". */
+    overlay(paused: boolean): void;
+    quietMs: number;
+    maxPauseMs: number;
+}
+/** State of one command that may pause (a single action, or every step of a batch). */
+export declare class PauseRun {
+    count: number;
+    pausedMs: number;
+    refocused: number;
+    moved: boolean;
+    resumedStrokes: number;
+    /** Keys (hold_key) and buttons (mouse down) the run holds; released at a pause, pressed again before going on. */
+    readonly keys: Map<string, string>;
+    readonly buttons: Set<string>;
+    pointer: {
+        x: number;
+        y: number;
+    } | null;
+    /** The run's window (the last result's `current`). */
+    windowId: string | null;
+    /** Windows that moved during a pause: where they were first, where they are now. */
+    readonly shifts: Map<string, {
+        from: PauseRect;
+        to: PauseRect;
+    }>;
+    current: {
+        id: string;
+        kind: string;
+    } | null;
+    readonly cancelled: Set<string>;
+    /** The user took over since the last pause: the next step that sends input pauses first. */
+    interrupted: boolean;
+    holds(): boolean;
+    /** Real user input: cancel a pointer stream now, let go of what the run holds; the next step pauses. */
+    onUserInput(host: Pick<PauseHost, "cancel" | "release">): void;
+    /** What a finished step left held, where the pointer is, which window the run is in. */
+    track(action: PauseRec, r: PauseResult): void;
+    report(): PauseReport | undefined;
+    /** A step as it must run now: moved with its window if that window moved during an earlier pause (null: it cannot). */
+    adapt(step: PauseRec): PauseRec | null;
+}
+/** One line for a result that paused: how often, how long, what was done to go on. */
+export declare function pauseReportText(r: PauseReport | undefined): string;
+/** The message of a run that stopped: why, where, and how to continue (resume_from). */
+export declare function pauseStopText(stop: PauseStop, where: string, resume: PausePosition): string;
+/**
+ * One step that pauses for the user instead of failing. Before a step that sends input, it waits while the user is
+ * busy; a pointer stream the user interrupted goes on from where it was (a path from its last sample, a drag from
+ * its start if nothing was picked up, a move / hover / mouse step again). `start`: a path's resume position.
+ * Returns the step's result, or `stop` when the run cannot go on safely (the caller answers user_interrupted).
+ */
+export declare function pauseRunStep(host: PauseHost, run: PauseRun, step: PauseRec, id: string, start?: PausePosition | null): Promise<{
+    result: PauseResult;
+} | {
+    stop: PauseStop;
+}>;
+export {};

package/dist/computerPause.js

@@ -0,0 +1,488 @@
+// Pause and resume for computer control (2026-10-23), runner copy: the CLI host (computerHostCli.ts, `npx
+// @melaya/runner --computer`) pauses for the user exactly as the desktop app does. This package cannot import
+// @melaya/desktop-contract, so the engine below is a byte-identical copy of
+// packages/desktop-contract/src/computerPause.ts (server/test/computerPause.test.ts diffs the three copies).
+// Edit the contract file first, then copy the block between the markers here and into the server.
+export const PAUSE_DEFAULTS = {
+    /** The user must be idle this long before the run goes on. */
+    quietMs: 1500,
+    /** One pause lasts at most this long; then the run stops with user_interrupted and a resume point. */
+    maxPauseMs: 60_000,
+    /** Pause time the server grants per command on top of its deadline. */
+    budgetMs: 180_000,
+    /** A step interrupted more often than this stops (the user keeps taking over). */
+    maxResumesPerStep: 20,
+    /** Time kept back before the deadline: a pause ends in time to report where it stopped. */
+    reserveMs: 1500,
+};
+/** Reads that send no input: they run while the user is busy. Everything else waits until the user is idle. */
+export const PAUSE_PASSIVE_KINDS = new Set([
+    "screen", "screenshot", "find", "get_text", "current_app", "list_windows", "list_apps", "list_displays", "clipboard_read",
+    "ocr", "wait", "zoom", "cursor_position", "read_table", "expect", "handoff", "keep_awake",
+]);
+/** Pointer streams cancelled the moment the user takes over (never fight for the cursor); short atomic writes finish. */
+export const PAUSE_CANCEL_KINDS = new Set(["path", "drag", "move", "hover", "mouse"]);
+export function pauseNeedsIdle(kind) {
+    return !PAUSE_PASSIVE_KINDS.has(kind);
+}
+function pauseNum(v) {
+    const n = Number(v);
+    return Number.isFinite(n) ? n : 0;
+}
+function pauseIsRect(v) {
+    const r = v;
+    return !!r && typeof r === "object" && [r.x, r.y, r.width, r.height].every((n) => Number.isFinite(Number(n)));
+}
+export function pauseRectMoved(a, b, tol = 2) {
+    return Math.abs(a.x - b.x) > tol || Math.abs(a.y - b.y) > tol || Math.abs(a.width - b.width) > tol || Math.abs(a.height - b.height) > tol;
+}
+export function pauseRectResized(a, b, tol = 2) {
+    return Math.abs(a.width - b.width) > tol || Math.abs(a.height - b.height) > tol;
+}
+/** A position inside a stroke: frac 1 is the start of the next segment. */
+function pauseNormalize(point, frac) {
+    let p = Math.max(0, Math.floor(pauseNum(point)));
+    let f = Math.min(1, Math.max(0, pauseNum(frac)));
+    if (f >= 1) {
+        p += 1;
+        f = 0;
+    }
+    return { point: p, frac: f };
+}
+/**
+ * The rest of one stroke from (point, frac): it starts on the last sample the pointer reached (pressed again there,
+ * one sample of overlap, no gap, nothing drawn twice beyond it), then every later point; times are shifted to start at
+ * 0. null when nothing is left (the stroke had reached its last point).
+ */
+export function pauseTrimStroke(stroke, point, frac) {
+    const n = stroke.length;
+    const at = pauseNormalize(point, frac);
+    if (at.point === 0 && at.frac === 0)
+        return stroke.map((q) => q.slice());
+    if (at.point >= n - 1)
+        return null;
+    const a = stroke[at.point], b = stroke[at.point + 1];
+    const timed = a.length >= 3 && b.length >= 3;
+    const head = [a[0] + (b[0] - a[0]) * at.frac, a[1] + (b[1] - a[1]) * at.frac];
+    if (timed)
+        head.push(a[2] + (b[2] - a[2]) * at.frac);
+    const out = [head, ...stroke.slice(at.point + 1).map((q) => q.slice())];
+    if (timed) {
+        const t0 = head[2];
+        for (const q of out)
+            q[2] = Math.max(0, q[2] - t0);
+    }
+    return out;
+}
+/** A path from a position (strokes before `stroke` are done, that stroke goes on from point / frac); null when nothing is left. */
+export function pauseTrimPath(action, pos) {
+    const strokes = Array.isArray(action.strokes) ? action.strokes : [];
+    const s = Math.max(0, Math.floor(pauseNum(pos.stroke)));
+    if (s >= strokes.length)
+        return null;
+    const first = pauseTrimStroke(strokes[s], pauseNum(pos.point), pauseNum(pos.frac));
+    const next = [...(first ? [first] : []), ...strokes.slice(s + 1).map((st) => st.map((q) => q.slice()))];
+    if (!next.length)
+        return null;
+    const out = { ...action, strokes: next };
+    delete out.resumeFrom;
+    return out;
+}
+/**
+ * The helper's progress on a path that was itself cut at `base`, as a position in the ORIGINAL path. The cut path's
+ * point 0 is the re-pressed sample on base segment (point -> point + 1); its point k >= 1 is base point + k.
+ */
+export function pauseAbsolute(base, rel) {
+    const bs = Math.max(0, Math.floor(pauseNum(base.stroke)));
+    const b = pauseNormalize(base.point, base.frac);
+    const rs = Math.max(0, Math.floor(pauseNum(rel.stroke)));
+    if (!rel.pressed)
+        return rs === 0 ? { stroke: bs, point: b.point, frac: b.frac } : { stroke: bs + rs, point: 0, frac: 0 };
+    const r = pauseNormalize(rel.point, rel.frac);
+    if (rs > 0)
+        return { stroke: bs + rs, point: r.point, frac: r.frac };
+    if (r.point === 0)
+        return { stroke: bs, point: b.point, frac: b.frac + r.frac * (1 - b.frac) };
+    return { stroke: bs, point: b.point + r.point, frac: r.frac };
+}
+/** A resumeFrom as a position (step, stroke, point: whole numbers >= 0; frac in 0..1); null when absent. */
+export function pausePositionOf(v) {
+    if (!v || typeof v !== "object")
+        return null;
+    const o = v;
+    const out = {};
+    for (const k of ["step", "stroke", "point"])
+        if (o[k] !== undefined)
+            out[k] = Math.max(0, Math.floor(pauseNum(o[k])));
+    if (o.frac !== undefined)
+        out.frac = Math.min(1, Math.max(0, pauseNum(o.frac)));
+    return out;
+}
+/**
+ * A window / region path moved with its window (same size only: a canvas does not scale with its window, so a resized
+ * window stops the run). null when it cannot follow (screen pixels, or resized).
+ */
+export function pauseShiftPath(action, from, to) {
+    if (!pauseRectMoved(from, to))
+        return action;
+    if (pauseRectResized(from, to))
+        return null;
+    const anchor = action.anchor === "window" || action.anchor === "region" ? action.anchor : pauseIsRect(action.windowRect) ? "window" : "screen";
+    if (anchor === "screen")
+        return null;
+    const dx = to.x - from.x, dy = to.y - from.y;
+    const strokes = (Array.isArray(action.strokes) ? action.strokes : []).map((st) => st.map((q) => {
+        const c = q.slice();
+        c[0] = c[0] + dx;
+        c[1] = c[1] + dy;
+        return c;
+    }));
+    const out = { ...action, strokes };
+    if (pauseIsRect(action.windowRect)) {
+        const w = action.windowRect;
+        out.windowRect = { x: w.x + dx, y: w.y + dy, width: w.width, height: w.height };
+    }
+    return out;
+}
+/**
+ * One step after its window moved from `from` to `to`: window / region paths move with it; points in screen pixels
+ * and refs bound to a screen taken before the move cannot follow (null: stop there); a label is found again (its
+ * snapshot binding is dropped). Steps on other windows, or without coordinates, are unchanged.
+ */
+export function pauseShiftStep(step, from, to) {
+    if (!pauseRectMoved(from, to))
+        return step;
+    const kind = String(step.kind);
+    if (kind === "path")
+        return pauseShiftPath(step, pauseIsRect(step.windowRect) ? step.windowRect : from, to);
+    if (kind === "move")
+        return null;
+    for (const k of ["target", "from", "to"]) {
+        const t = step[k];
+        if (t && typeof t === "object" && t.x !== undefined && t.y !== undefined)
+            return null;
+    }
+    if (step.snapshotId === undefined)
+        return step;
+    for (const k of ["target", "from", "to"]) {
+        const t = step[k];
+        if (t && typeof t === "object" && typeof t.ref === "string")
+            return null;
+    }
+    const { snapshotId: _snap, ...rest } = step;
+    return rest;
+}
+/** State of one command that may pause (a single action, or every step of a batch). */
+export class PauseRun {
+    count = 0;
+    pausedMs = 0;
+    refocused = 0;
+    moved = false;
+    resumedStrokes = 0;
+    /** Keys (hold_key) and buttons (mouse down) the run holds; released at a pause, pressed again before going on. */
+    keys = new Map();
+    buttons = new Set();
+    pointer = null;
+    /** The run's window (the last result's `current`). */
+    windowId = null;
+    /** Windows that moved during a pause: where they were first, where they are now. */
+    shifts = new Map();
+    current = null;
+    cancelled = new Set();
+    /** The user took over since the last pause: the next step that sends input pauses first. */
+    interrupted = false;
+    holds() {
+        return this.keys.size > 0 || this.buttons.size > 0;
+    }
+    /** Real user input: cancel a pointer stream now, let go of what the run holds; the next step pauses. */
+    onUserInput(host) {
+        this.interrupted = true;
+        const cur = this.current;
+        if (cur && PAUSE_CANCEL_KINDS.has(cur.kind) && !this.cancelled.has(cur.id)) {
+            this.cancelled.add(cur.id);
+            host.cancel(cur.id);
+        }
+        if (this.holds())
+            host.release();
+    }
+    /** What a finished step left held, where the pointer is, which window the run is in. */
+    track(action, r) {
+        const kind = String(action.kind);
+        if (kind === "hold_key") {
+            const k = String(action.key || "").trim();
+            if (action.state === "down")
+                this.keys.set(k.toLowerCase(), k);
+            else
+                this.keys.delete(k.toLowerCase());
+        }
+        else if (kind === "mouse") {
+            const b = typeof action.button === "string" ? action.button : "left";
+            if (action.state === "down")
+                this.buttons.add(b);
+            else
+                this.buttons.delete(b);
+        }
+        const p = r.pointer;
+        const t = (action.target ?? action.to);
+        if (p && Number.isFinite(Number(p.x)) && Number.isFinite(Number(p.y)))
+            this.pointer = { x: Number(p.x), y: Number(p.y) };
+        else if (kind === "move" && Number.isFinite(Number(action.x)) && Number.isFinite(Number(action.y)))
+            this.pointer = { x: Number(action.x), y: Number(action.y) };
+        else if (t && typeof t === "object" && Number.isFinite(Number(t.x)) && Number.isFinite(Number(t.y)))
+            this.pointer = { x: Number(t.x), y: Number(t.y) };
+        const cur = r.current;
+        if (cur && typeof cur.windowId === "string" && cur.windowId)
+            this.windowId = cur.windowId;
+        else if (typeof action.windowId === "string" && action.windowId)
+            this.windowId = action.windowId;
+    }
+    report() {
+        if (!this.count)
+            return undefined;
+        return {
+            count: this.count, pausedMs: Math.round(this.pausedMs),
+            ...(this.refocused ? { refocused: this.refocused } : {}),
+            ...(this.moved ? { moved: true } : {}),
+            ...(this.resumedStrokes ? { resumedStrokes: this.resumedStrokes } : {}),
+        };
+    }
+    /** A step as it must run now: moved with its window if that window moved during an earlier pause (null: it cannot). */
+    adapt(step) {
+        if (!this.shifts.size)
+            return step;
+        const wid = typeof step.windowId === "string" ? step.windowId : this.windowId;
+        const m = wid ? this.shifts.get(wid) : undefined;
+        return m ? pauseShiftStep(step, m.from, m.to) : step;
+    }
+}
+function pauseSecs(ms) {
+    return ms >= 10_000 ? `${Math.round(ms / 1000)} s` : `${(ms / 1000).toFixed(1)} s`;
+}
+/** One line for a result that paused: how often, how long, what was done to go on. */
+export function pauseReportText(r) {
+    if (!r || !r.count)
+        return "";
+    const extra = [
+        r.refocused ? "brought the window back to the front" : "",
+        r.moved ? "followed the window to where it was moved" : "",
+        r.resumedStrokes ? `continued ${r.resumedStrokes} stroke${r.resumedStrokes === 1 ? "" : "s"} midway` : "",
+    ].filter(Boolean).join(", ");
+    return `Paused ${r.count === 1 ? "once" : `${r.count} times`} (${pauseSecs(r.pausedMs)}) while the user used the computer, then resumed${extra ? ` (${extra})` : ""}.`;
+}
+/** The message of a run that stopped: why, where, and how to continue (resume_from). */
+export function pauseStopText(stop, where, resume) {
+    return `${stop.message} Melaya stopped ${where}; nothing after that point was done. Read the screen first, then call again with the same ` +
+        `steps / strokes and resume_from ${JSON.stringify(resume)} to continue exactly there without redoing anything, or ask the user.`;
+}
+function pauseStop(reason, message, at) {
+    return { stop: { reason, message, ...(at ? { at } : {}) } };
+}
+function pauseWindows(r) {
+    if (!r.ok || !Array.isArray(r.windows))
+        return null;
+    return r.windows.filter((w) => w && typeof w.windowId === "string" && pauseIsRect(w.bounds));
+}
+/**
+ * The pause itself: let go of what the run holds, wait until the user has been idle `quietMs` (at most `maxPauseMs`,
+ * within the deadline), then check the world before going on: the window still exists, no new window of its app
+ * (a dialog) took the front, it is in front again (re-focused only now, when the user is idle), where it moved;
+ * finally press again what the run held. Returns the window move, if any.
+ */
+async function pauseHold(host, run, step, id) {
+    const t0 = host.now();
+    run.count++;
+    const n = run.count;
+    if (run.holds())
+        host.release();
+    host.overlay(true);
+    const granted = host.extend(host.maxPauseMs);
+    try {
+        const before = pauseWindows(await host.exec({ kind: "list_windows" }, `${id}~p${n}a`));
+        const wid = typeof step.windowId === "string" ? step.windowId : run.windowId;
+        const target = wid && (!before || before.some((w) => w.windowId === wid)) ? wid
+            : (before?.find((w) => w.focused && !w.minimized)?.windowId ?? wid ?? null);
+        for (;;) {
+            if (host.ended())
+                return pauseStop("stopped", "Stopped while paused.");
+            const now = host.now();
+            const quiet = now - host.lastInputAt();
+            if (quiet >= host.quietMs)
+                break;
+            if (now - t0 >= host.maxPauseMs)
+                return pauseStop("max_pause", `The user kept using the computer for more than ${Math.round(host.maxPauseMs / 1000)} s, so Melaya stopped instead of waiting longer.`);
+            if (host.timeLeft() <= PAUSE_DEFAULTS.reserveMs)
+                return pauseStop("deadline", "The time for this call ran out while Melaya waited for the user to finish.");
+            await host.sleep(Math.max(10, Math.min(100, host.quietMs - quiet + 5)));
+        }
+        run.interrupted = false;
+        if (host.ended())
+            return pauseStop("stopped", "Stopped while paused.");
+        let shift;
+        if (target) {
+            let after = pauseWindows(await host.exec({ kind: "list_windows" }, `${id}~p${n}b`));
+            let a = after?.find((w) => w.windowId === target);
+            if (after && !a)
+                return pauseStop("window_closed", "The window Melaya was working in was closed while it waited for the user.");
+            if (after && a) {
+                const f = after.find((w) => w.focused && !w.minimized);
+                if (f && f.windowId !== target && before && !before.some((w) => w.windowId === f.windowId) && (!f.appId || f.appId === a.appId)) {
+                    return pauseStop("dialog", `A new window of the app ("${String(f.title || "").slice(0, 60)}", a dialog?) opened while Melaya waited, so Melaya did not act on it.`);
+                }
+                if (a.minimized || !a.focused) {
+                    const fr = await host.exec({ kind: "focus_window", windowId: target }, `${id}~p${n}f`);
+                    if (!fr.ok || host.ended())
+                        return pauseStop("refocus", `The window could not be brought back to the front after the user switched away (${String(fr.error?.message || "focus refused").slice(0, 160)}).`);
+                    run.refocused++;
+                    if (a.minimized) {
+                        after = pauseWindows(await host.exec({ kind: "list_windows" }, `${id}~p${n}c`));
+                        a = after?.find((w) => w.windowId === target) ?? a;
+                    }
+                }
+                const b = before?.find((w) => w.windowId === target);
+                if (b && !b.minimized && !a.minimized && pauseRectMoved(b.bounds, a.bounds)) {
+                    shift = { windowId: target, from: b.bounds, to: a.bounds };
+                    const prev = run.shifts.get(target);
+                    run.shifts.set(target, { from: prev ? prev.from : b.bounds, to: a.bounds });
+                    run.moved = true;
+                }
+            }
+        }
+        // What the run held before the pause is pressed again; the pointer goes back by our own move, never assumed.
+        for (const key of run.keys.values()) {
+            const r = await host.exec({ kind: "hold_key", key, state: "down", observe: "none" }, `${id}~p${n}k`);
+            if (!r.ok || host.ended())
+                return pauseStop("repress", `Melaya could not press ${key} again after the pause.`);
+        }
+        for (const button of run.buttons) {
+            const at = run.pointer;
+            if (!at)
+                return pauseStop("repress", `Melaya let go of the ${button} mouse button for the user and does not know where to press it again.`);
+            let x = at.x, y = at.y;
+            if (shift) {
+                x += shift.to.x - shift.from.x;
+                y += shift.to.y - shift.from.y;
+            }
+            const r = await host.exec({ kind: "mouse", target: { x, y }, button, state: "down", observe: "none" }, `${id}~p${n}m`);
+            if (!r.ok || host.ended())
+                return pauseStop("repress", `Melaya could not press the ${button} mouse button again after the pause (${String(r.error?.message || "").slice(0, 160)}).`);
+        }
+        return shift ? { shift } : {};
+    }
+    finally {
+        const used = host.now() - t0;
+        run.pausedMs += used;
+        if (granted > used)
+            host.extend(-(granted - used));
+        if (!host.ended())
+            host.overlay(false);
+    }
+}
+/**
+ * One step that pauses for the user instead of failing. Before a step that sends input, it waits while the user is
+ * busy; a pointer stream the user interrupted goes on from where it was (a path from its last sample, a drag from
+ * its start if nothing was picked up, a move / hover / mouse step again). `start`: a path's resume position.
+ * Returns the step's result, or `stop` when the run cannot go on safely (the caller answers user_interrupted).
+ */
+export async function pauseRunStep(host, run, step, id, start) {
+    const kind = String(step.kind);
+    const isPath = kind === "path";
+    const adapted = run.adapt(step);
+    if (!adapted)
+        return pauseStop("moved", "The window moved while Melaya waited for the user, and this step uses screen coordinates (or a ref) of where it was.");
+    let orig = adapted;
+    let pos = isPath && start ? { stroke: start.stroke ?? 0, point: start.point ?? 0, frac: start.frac ?? 0 } : { stroke: 0, point: 0, frac: 0 };
+    const done = () => ({ ok: true, kind, text: "Nothing was left to draw: the path had reached its end.", elapsedMs: 0 });
+    const first = isPath ? pauseTrimPath(orig, pos) : orig;
+    if (!first)
+        return { result: done() };
+    let attempt = first;
+    let tries = 0;
+    let afterPause = false;
+    for (;;) {
+        if (host.ended())
+            return { result: { ok: false, kind, error: { code: "stopped", message: "Stopped." }, elapsedMs: 0 } };
+        if (pauseNeedsIdle(kind) && (run.interrupted || host.now() - host.lastInputAt() < host.quietMs)) {
+            const h = await pauseHold(host, run, orig, id);
+            if ("stop" in h)
+                return { stop: { ...h.stop, ...(isPath ? { at: pos } : {}) } };
+            afterPause = true;
+            if (h.shift) {
+                const moved = pauseShiftStep(orig, isPath && pauseIsRect(orig.windowRect) ? orig.windowRect : h.shift.from, h.shift.to);
+                if (!moved) {
+                    return pauseStop("moved", pauseRectResized(h.shift.from, h.shift.to)
+                        ? "The window was resized while Melaya waited for the user, so the coordinates planned for its old size would land elsewhere."
+                        : "The window moved while Melaya waited for the user, and this step uses screen coordinates (or a ref) of where it was.", isPath ? pos : undefined);
+                }
+                orig = moved;
+            }
+            const again = isPath ? pauseTrimPath(orig, pos) : orig;
+            if (!again)
+                return { result: done() };
+            attempt = again;
+            // The user may have come back while the window was checked: look again before sending anything.
+            continue;
+        }
+        const hid = tries === 0 ? id : `${id}~r${tries}`;
+        run.current = { id: hid, kind: String(attempt.kind) };
+        const r = await host.exec(attempt, hid);
+        run.current = null;
+        const cancelled = run.cancelled.delete(hid);
+        if (host.ended())
+            return { result: r };
+        const code = r.ok ? "" : String(r.error?.code ?? "");
+        // The helper's own check (Linux: real input within 1.5 s) refused before sending anything.
+        const refused = code === "user_interrupted";
+        if (r.ok || (!cancelled && !refused)) {
+            if (!r.ok && afterPause && (code === "frame_stale" || code === "stale_ref")) {
+                const t = (attempt.target ?? attempt.from);
+                if (attempt.snapshotId !== undefined && t && typeof t === "object" && typeof t.label === "string" && tries < PAUSE_DEFAULTS.maxResumesPerStep) {
+                    const relabel = { ...attempt };
+                    delete relabel.snapshotId;
+                    attempt = relabel;
+                    if (!isPath)
+                        orig = relabel;
+                    tries++;
+                    continue;
+                }
+                return pauseStop("stale", "The window changed while Melaya waited for the user, and this step targets an element of the screen read before the pause.", isPath ? pos : undefined);
+            }
+            if (r.ok)
+                run.track(attempt, r);
+            return { result: r };
+        }
+        if (refused)
+            host.markInput();
+        run.interrupted = true;
+        tries++;
+        if (tries > PAUSE_DEFAULTS.maxResumesPerStep)
+            return pauseStop("too_many", "The user took over this step too many times in a row.", isPath ? pos : undefined);
+        if (refused)
+            continue; // nothing was sent: the same attempt runs after the pause
+        if (isPath) {
+            const prog = r.progress;
+            if (!prog || typeof prog !== "object")
+                return pauseStop("unknown_progress", "A stroke was interrupted and this computer's helper cannot tell how far it got (it may be partly drawn).", pos);
+            if (orig.gesture === "drag") {
+                if (prog.pressed || pauseNum(prog.stroke) > 0)
+                    return pauseStop("dropped", "The drag was interrupted after it had picked the item up; letting go for the user dropped it where the pointer was.", { stroke: 0, point: 0, frac: 0 });
+                continue; // nothing picked up yet: the whole gesture again
+            }
+            pos = pauseAbsolute(pos, prog);
+            const rest = pauseTrimPath(orig, pos);
+            if (!rest)
+                return { result: done() };
+            attempt = rest;
+            if (prog.pressed)
+                run.resumedStrokes++;
+            continue;
+        }
+        if (kind === "drag") {
+            const prog = r.progress;
+            if (!prog || prog.pressed)
+                return pauseStop("dropped", "The drag was interrupted after it had picked the item up; letting go for the user dropped it where the pointer was.");
+            continue;
+        }
+        // move, hover, mouse: sending them again is the same input (the button the run held is pressed again first).
+    }
+}
+// END COMPUTER PAUSE ENGINE