@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/unity/probe/player.js

@@ -0,0 +1,255 @@
+import { execFile, spawn } from 'node:child_process';
+import { closeSync, existsSync, openSync, readdirSync, statSync } from 'node:fs';
+import { mkdir, readFile, readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { unityRun } from "../run.js";
+import { lease, readLease, release } from "../../simulator/lease.js";
+export const buildDir = (project, target, variant = 'development') => join(project, 'Builds', 'FunpixelProbe', (target === 'mac' ? 'mac' : 'ios-sim') + (variant === 'capture' ? '-capture' : ''));
+export const BUILD_METHOD = { mac: 'Funpixel.Probe.Editor.ProbeBuild.Mac', sim: 'Funpixel.Probe.Editor.ProbeBuild.IosSimulator' };
+export async function readBuild(dir) {
+    try {
+        return JSON.parse(await readFile(join(dir, 'funpixel-probe-build.json'), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function appIn(dir, target, rec) {
+    if (target === 'mac')
+        return rec?.path && existsSync(rec.path) ? rec.path : firstApp(dir);
+    return firstApp(join(dir, 'DerivedData', 'Build', 'Products', 'Debug-iphonesimulator'));
+}
+function firstApp(dir) {
+    try {
+        const a = readdirSync(dir).find((n) => n.endsWith('.app'));
+        return a ? join(dir, a) : null;
+    }
+    catch {
+        return null;
+    }
+}
+const SKIP = new Set(['Library', 'Temp', 'Logs', 'Builds', 'obj', 'UserSettings', '.git']);
+export async function newestInput(project) {
+    let best = { at: 0, file: '' };
+    const see = (file, at) => { if (at > best.at)
+        best = { at, file }; };
+    async function walk(dir, depth) {
+        let names;
+        try {
+            names = await readdir(dir);
+        }
+        catch {
+            return;
+        }
+        for (const n of names) {
+            if (n.startsWith('.') || SKIP.has(n) || n.endsWith('~'))
+                continue;
+            const p = join(dir, n);
+            let s;
+            try {
+                s = await stat(p);
+            }
+            catch {
+                continue;
+            }
+            if (s.isDirectory()) {
+                if (depth < 24)
+                    await walk(p, depth + 1);
+            }
+            else
+                see(p, s.mtimeMs);
+        }
+    }
+    await walk(join(project, 'Assets'), 0);
+    await walk(join(project, 'ProjectSettings'), 0);
+    for (const f of ['manifest.json', 'packages-lock.json']) {
+        try {
+            see(join(project, 'Packages', f), statSync(join(project, 'Packages', f)).mtimeMs);
+        }
+        catch { }
+    }
+    return best;
+}
+export async function freshness(project, target, variant = 'development') {
+    const dir = buildDir(project, target, variant);
+    const record = await readBuild(dir);
+    const app = appIn(dir, target, record);
+    if (!record || record.result !== 'Succeeded')
+        return { app, record, fresh: false, why: 'no probe build yet' };
+    if (!app)
+        return { app, record, fresh: false, why: target === 'sim' ? 'the Xcode project was exported but not built for the Simulator' : 'the built app is gone' };
+    const built = Date.parse(record.built_at) || 0;
+    const n = await newestInput(project);
+    if (n.at > built)
+        return { app, record, fresh: false, why: `${n.file.slice(project.length + 1)} changed after the last build (${record.built_at})` };
+    return { app, record, fresh: true, why: `built ${record.built_at}, nothing changed since` };
+}
+export function buildRecorded(rec, target, app) {
+    return rec?.result === 'Succeeded' && (target !== 'mac' || app !== null);
+}
+export async function buildPlayer(project, target, o) {
+    const variant = o.variant ?? 'development';
+    const dir = buildDir(project, target, variant);
+    await mkdir(dir, { recursive: true });
+    o.log(`building a ${variant} player (${target}) of ${project} through the Unity queue → ${dir}`);
+    const r = await unityRun({
+        unityArgs: ['-executeMethod', BUILD_METHOD[target], '-fpOut', dir, ...(variant === 'capture' ? ['-fpCapture'] : []), ...(o.keepTarget ? ['-fpKeepTarget'] : [])],
+        project, cwd: project, queue: o.queue,
+    }, o.run);
+    const rec = await readBuild(dir);
+    const recorded = buildRecorded(rec, target, target === 'mac' ? appIn(dir, target, rec) : null);
+    if (r.code !== 0 && !recorded)
+        return { ok: false, unity: r, message: r.message ?? `the Unity build exited ${r.code}${r.errors?.length ? `: ${r.errors.slice(0, 4).join(' | ')}` : ''}${r.log ? ` (log ${r.log})` : ''}` };
+    if (r.code !== 0)
+        o.log(`note: Unity exited ${r.code} after the build, but its build record says Succeeded and the player is there: the build is kept (a crash on quit, not a failed build${r.log ? `; log ${r.log}` : ''})`);
+    if (!rec || rec.result !== 'Succeeded')
+        return { ok: false, unity: r, message: `the build wrote no success record${rec?.error ? `: ${rec.error}` : ''} — is com.funpixel.probe installed (funtools unity probe install)?` };
+    if (target === 'mac') {
+        const app = appIn(dir, 'mac', rec);
+        return app ? { ok: true, app, unity: r, message: `built ${app}` } : { ok: false, unity: r, message: 'the build succeeded but no .app is there' };
+    }
+    const xb = await (o.xcodebuild ?? xcodebuildSim)(dir, o.log);
+    if (!xb.ok)
+        return { ok: false, unity: r, message: xb.message };
+    const app = appIn(dir, 'sim', rec);
+    return app ? { ok: true, app, unity: r, message: `built ${app}` } : { ok: false, unity: r, message: 'xcodebuild succeeded but no Simulator .app is there' };
+}
+export const xcodebuildSim = (dir, log) => new Promise((ok) => {
+    const project = join(dir, 'xcode', 'Unity-iPhone.xcodeproj');
+    if (!existsSync(project))
+        return ok({ ok: false, message: `no ${project}` });
+    const logFile = join(dir, 'xcodebuild.log');
+    log(`xcodebuild for the Simulator (log ${logFile})`);
+    const args = ['-project', project, '-scheme', 'Unity-iPhone', '-configuration', 'Debug', '-sdk', 'iphonesimulator', '-destination', 'generic/platform=iOS Simulator',
+        '-derivedDataPath', join(dir, 'DerivedData'), 'CODE_SIGNING_ALLOWED=NO', 'build'];
+    const out = openSync(logFile, 'w');
+    const c = spawn('xcodebuild', args, { stdio: ['ignore', out, out] });
+    c.on('error', (e) => { closeSync(out); ok({ ok: false, message: `xcodebuild: ${e.message}` }); });
+    c.on('exit', async (code) => {
+        try {
+            closeSync(out);
+        }
+        catch { }
+        if (code === 0)
+            return ok({ ok: true, message: 'built' });
+        let tail = '';
+        try {
+            tail = (await readFile(logFile, 'utf8')).split('\n').filter((l) => /error:|BUILD FAILED/.test(l)).slice(0, 6).join(' | ');
+        }
+        catch { }
+        ok({ ok: false, message: `xcodebuild exited ${code}${tail ? `: ${tail}` : ''} (log ${logFile})` });
+    });
+});
+export const execText = (bin, args, env, timeoutMs = 120_000) => new Promise((ok, fail) => {
+    execFile(bin, args, { env: env ?? process.env, timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
+        if (err)
+            fail(new Error(`${bin.split('/').pop()} ${args[0] ?? ''}: ${String(stderr || err.message).trim().split('\n').slice(-2).join(' ')}`));
+        else
+            ok(String(stdout));
+    });
+});
+export function launchArgs(o) {
+    const a = ['-fp-remote', String(o.port)];
+    if (o.probe)
+        a.push('-fp-probe', '-fp-warmup-frames', String(o.warmup ?? 60));
+    if (o.hitchMs)
+        a.push('-fp-hitch-ms', String(o.hitchMs));
+    if (o.mute)
+        a.push('-fp-mute');
+    if (o.size)
+        a.push('-screen-fullscreen', '0', '-screen-width', String(o.size.w), '-screen-height', String(o.size.h));
+    if (o.log)
+        a.push('-logFile', o.log);
+    return a;
+}
+async function executableOf(app, plist) {
+    const info = await plist(join(app, 'Contents', 'Info.plist'));
+    const name = typeof info?.CFBundleExecutable === 'string' ? info.CFBundleExecutable : app.split('/').pop().replace(/\.app$/, '');
+    return join(app, 'Contents', 'MacOS', name);
+}
+const runsExe = (p, exe) => p.args === exe || p.args.startsWith(exe + ' ');
+export async function launchMac(app, args, o, d) {
+    const exe = await executableOf(app, d.plist);
+    const before = (await d.procs()).filter((p) => runsExe(p, exe));
+    if (before.length)
+        throw new Error(`this player already runs (pid ${before.map((p) => p.pid).join(', ')}): \`funtools unity play end\` stops a play session's; one player per build folder`);
+    await d.exec('open', ['-n', ...(o.visible ? [] : ['-g', '-j']), app, '--args', ...args]);
+    for (let i = 0; i < 60; i++) {
+        const p = (await d.procs()).find((x) => runsExe(x, exe));
+        if (p)
+            return { target: 'mac', app, exe, pid: p.pid, port: o.port, started: new Date(d.now()).toISOString(), log: args[args.indexOf('-logFile') + 1] };
+        await d.sleep(500);
+    }
+    throw new Error(`${app} did not start in 30 s`);
+}
+export async function stopMac(r, quit, d) {
+    if (!r.pid || !r.exe)
+        return 'nothing to stop';
+    const mine = async () => (await d.procs()).some((p) => p.pid === r.pid && runsExe(p, r.exe));
+    if (quit) {
+        try {
+            await quit();
+        }
+        catch { }
+    }
+    for (let i = 0; i < 20; i++) {
+        if (!(await mine()))
+            return 'quit';
+        await d.sleep(500);
+    }
+    if (await mine()) {
+        d.kill(r.pid, 'SIGTERM');
+        for (let i = 0; i < 10; i++) {
+            if (!(await mine()))
+                return 'terminated';
+            await d.sleep(500);
+        }
+    }
+    if (await mine()) {
+        d.kill(r.pid, 'SIGKILL');
+        return 'killed';
+    }
+    return 'quit';
+}
+export async function launchSim(app, args, o, d, l) {
+    let udid = o.udid;
+    let leased = false;
+    if (udid) {
+        const rec = await readLease(l.root, udid);
+        if (!rec)
+            throw new Error(`${udid} is not a funtools lease — funtools only installs on Simulators it leased (funtools sim lease)`);
+    }
+    else {
+        const got = await lease({ device: o.device, runtime: o.runtime, boot: true }, l);
+        if (!got.ok)
+            throw new Error(got.message);
+        udid = got.lease.udid;
+        leased = true;
+        d.log(`leased ${got.lease.name} (${got.lease.device}, ${got.lease.runtime}) ${udid}`);
+    }
+    const info = await d.plist(join(app, 'Info.plist'));
+    const bundle = typeof info?.CFBundleIdentifier === 'string' ? info.CFBundleIdentifier : null;
+    if (!bundle)
+        throw new Error(`${app}/Info.plist has no CFBundleIdentifier`);
+    await d.exec('xcrun', ['simctl', 'install', udid, app], undefined, 300_000);
+    const env = { ...process.env, SIMCTL_CHILD_FUNPIXEL_PROBE_ARGS: args.filter((a, i) => !['-logFile', '-screen-fullscreen', '-screen-width', '-screen-height'].includes(a) && !['-logFile', '-screen-fullscreen', '-screen-width', '-screen-height'].includes(args[i - 1])).join(' ') };
+    const out = await d.exec('xcrun', ['simctl', 'launch', '--terminate-running-process', udid, bundle, ...(o.gameArgs ?? [])], env, 120_000);
+    const pid = Number(/:\s*(\d+)/.exec(out)?.[1] ?? 0) || undefined;
+    return { target: 'sim', app, udid, bundle, pid, leased: leased && !o.keep, port: o.port, started: new Date(d.now()).toISOString() };
+}
+export async function stopSim(r, quit, d, l) {
+    if (!r.udid || !r.bundle)
+        return 'nothing to stop';
+    if (quit) {
+        try {
+            await quit();
+        }
+        catch { }
+        await d.sleep(1500);
+    }
+    await d.exec('xcrun', ['simctl', 'terminate', r.udid, r.bundle], undefined, 60_000).catch(() => '');
+    if (!r.leased)
+        return `stopped on ${r.udid} (the lease is kept)`;
+    const rel = await release(r.udid, { force: false }, l);
+    return rel.ok ? `stopped; released ${r.udid}` : `stopped; the lease was not released: ${rel.message}`;
+}

package/dist/unity/probe/report.js

@@ -0,0 +1,102 @@
+export const SCHEMA = 'funpixel.probe/1';
+const isDist = (v) => !!v && typeof v === 'object' && ['n', 'mean', 'p50', 'p95', 'p99', 'max'].every((k) => typeof v[k] === 'number');
+export function parseReport(input) {
+    let v = input;
+    if (typeof input === 'string') {
+        try {
+            v = JSON.parse(input);
+        }
+        catch (e) {
+            return { ok: false, error: `not JSON: ${e.message}` };
+        }
+    }
+    if (!v || typeof v !== 'object')
+        return { ok: false, error: 'not an object' };
+    const r = v;
+    if (r.schema !== SCHEMA)
+        return { ok: false, error: `schema ${JSON.stringify(r.schema)}, expected ${SCHEMA} (a newer or older com.funpixel.probe?)` };
+    const f = r.frames;
+    if (!f || typeof f.sampled !== 'number' || typeof f.included !== 'number')
+        return { ok: false, error: 'no frames block' };
+    for (const k of ['frame_ms', 'main_ms', 'render_ms', 'work_ms', 'game_work_ms', 'gpu_ms', 'gc_bytes', 'draws', 'setpass', 'batches', 'triangles']) {
+        if (r[k] !== null && r[k] !== undefined && !isDist(r[k]))
+            return { ok: false, error: `${k} is not a distribution` };
+        if (r[k] === undefined)
+            r[k] = null;
+    }
+    if (!Array.isArray(r.hitches))
+        r.hitches = [];
+    if (!Array.isArray(r.worst))
+        r.worst = [];
+    if (!Array.isArray(r.segments))
+        r.segments = [];
+    r.memory_mb ??= { total_used_peak: null, total_used_last: null, system_used_peak: null, gc_used_peak: null };
+    r.counters ??= {};
+    r.meta ??= {};
+    return { ok: true, report: r };
+}
+export function percentile(sorted, q) {
+    if (!sorted.length)
+        return NaN;
+    const i = Math.min(sorted.length - 1, Math.max(0, Math.ceil(q * sorted.length) - 1));
+    return sorted[i];
+}
+export function dist(values) {
+    const a = values.filter((v) => v >= 0 && Number.isFinite(v)).sort((x, y) => x - y);
+    if (!a.length)
+        return null;
+    const r3 = (x) => Math.round(x * 1000) / 1000;
+    return { n: a.length, mean: r3(a.reduce((t, x) => t + x, 0) / a.length), p50: a.length ? percentile(a, 0.5) : 0, p95: percentile(a, 0.95), p99: percentile(a, 0.99), max: a[a.length - 1] };
+}
+export function measuredFrames(r) {
+    if (!r.rows || !r.columns)
+        return null;
+    const at = (name) => r.columns.indexOf(name);
+    const c = { frame: at('frame'), segment: at('segment'), skip: at('skip'), ms: at('ms'), main: at('main'), render: at('render'), work: at('work'), game_work: at('game_work'), gpu: at('gpu'), gc: at('gc') };
+    if (c.frame < 0 || c.ms < 0 || c.skip < 0)
+        return null;
+    const labels = r.segments.map((s) => s.label);
+    const val = (row, i) => (i < 0 || row[i] === undefined || row[i] === null || row[i] < 0 ? null : row[i]);
+    return r.rows.filter((row) => row[c.skip] === 0).map((row) => ({
+        frame: row[c.frame], ms: row[c.ms], main: val(row, c.main), render: val(row, c.render), work: val(row, c.work), game_work: val(row, c.game_work),
+        gpu: val(row, c.gpu), gc: val(row, c.gc), segment: labels[row[c.segment]] ?? null,
+    }));
+}
+export const HOST_SHARE = 0.25;
+export const HOST_MIN_MS = 2;
+export function hostFlags(r) {
+    const rows = measuredFrames(r);
+    const frames = rows ?? r.hitches;
+    const hitches = frames.filter((f) => f.ms > r.hitch_ms);
+    const out = {
+        flagged: [], game: [], unknown: [], max_game_ms: null, from: rows ? 'rows' : 'hitches',
+        rule: `a frame over ${r.hitch_ms} ms whose own work (FunpixelProbe.Work, else the player loop minus its waits) is at most max(${HOST_MIN_MS} ms, ${HOST_SHARE * 100}% of the frame), with the render thread and GPU each under half of it`,
+    };
+    for (const f of hitches) {
+        const own = f.game_work ?? f.work;
+        if (own === null) {
+            out.unknown.push(f);
+            continue;
+        }
+        const small = own <= Math.max(HOST_MIN_MS, HOST_SHARE * f.ms);
+        const busyGpu = (f.render ?? 0) > f.ms / 2 || (f.gpu ?? 0) > f.ms / 2;
+        if (small && !busyGpu)
+            out.flagged.push({ ...f, own_ms: own, own_from: f.game_work !== null ? 'game_work' : 'work' });
+        else
+            out.game.push(f);
+    }
+    const flaggedFrames = new Set(out.flagged.map((f) => f.frame));
+    if (rows) {
+        const kept = rows.filter((f) => !flaggedFrames.has(f.frame)).map((f) => f.ms);
+        out.max_game_ms = kept.length ? Math.max(...kept) : null;
+    }
+    else if (r.frame_ms) {
+        const longest = [...out.game, ...out.unknown].map((f) => f.ms);
+        out.max_game_ms = longest.length ? Math.max(...longest) : flaggedFrames.size ? r.frame_ms.p99 : r.frame_ms.max;
+    }
+    return out;
+}
+export function withoutRows(r) {
+    const { rows: _rows, columns: _columns, skips: _skips, ...rest } = r;
+    return rest;
+}

package/dist/unity/probe/script.js

@@ -0,0 +1,225 @@
+const VERBS = ['wait', 'tap', 'hold', 'drag', 'key', 'pad', 'stick', 'scene', 'view', 'segment', 'shot', 'state', 'expect', 'cmd', 'repeat', 'frames', 'speed', 'release'];
+const isPair = (v) => Array.isArray(v) && v.length === 2 && v.every((n) => typeof n === 'number' && Number.isFinite(n));
+export function verbOf(s) {
+    const found = VERBS.filter((v) => v in s);
+    return found.length === 1 ? found[0] : null;
+}
+export function parseScript(input) {
+    let v = input;
+    if (typeof input === 'string') {
+        try {
+            v = JSON.parse(input);
+        }
+        catch (e) {
+            return { ok: false, error: `not JSON: ${e.message}` };
+        }
+    }
+    const o = Array.isArray(v) ? { steps: v } : v;
+    if (!o || typeof o !== 'object' || !Array.isArray(o.steps))
+        return { ok: false, error: 'a script is {"steps": [...]} or a list of steps' };
+    const s = o;
+    if (s.seconds !== undefined && !(typeof s.seconds === 'number' && s.seconds > 0 && s.seconds <= 3600))
+        return { ok: false, error: '"seconds" is 1 to 3600' };
+    if (s.space !== undefined && s.space !== 'px' && s.space !== 'pt')
+        return { ok: false, error: '"space" is "px" or "pt"' };
+    const bad = checkSteps(s.steps, 'steps');
+    return bad ? { ok: false, error: bad } : { ok: true, script: s };
+}
+function checkSteps(steps, at) {
+    for (const [i, raw] of steps.entries()) {
+        const where = `${at}[${i}]`;
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            return `${where}: a step is an object like {"tap": [x, y]}`;
+        const s = raw;
+        const verb = verbOf(s);
+        if (!verb)
+            return `${where}: one verb per step (${VERBS.join(', ')}), found ${Object.keys(s).filter((k) => VERBS.includes(k)).join(', ') || 'none'}`;
+        const v = s[verb];
+        switch (verb) {
+            case 'wait':
+            case 'frames':
+                if (!(typeof v === 'number' && v >= 0))
+                    return `${where}: ${verb} takes a number`;
+                break;
+            case 'tap':
+            case 'hold':
+                if (!isPair(v) && !(typeof v === 'string' && v))
+                    return `${where}: ${verb} takes [x, y] or a target name`;
+                break;
+            case 'drag':
+                if (!(Array.isArray(v) && v.length === 2 && isPair(v[0]) && isPair(v[1])))
+                    return `${where}: drag takes [[x1, y1], [x2, y2]]`;
+                break;
+            case 'stick':
+                if (!isPair(v))
+                    return `${where}: stick takes [x, y] in -1..1`;
+                break;
+            case 'key':
+            case 'pad':
+            case 'scene':
+            case 'view':
+            case 'segment':
+            case 'shot':
+            case 'cmd':
+                if (typeof v !== 'string' || !v)
+                    return `${where}: ${verb} takes a name`;
+                break;
+            case 'speed':
+                if (!(typeof v === 'number' && v >= 0 && v <= 8))
+                    return `${where}: speed is 0 to 8`;
+                break;
+            case 'expect':
+                if (!v || typeof v !== 'object' || Array.isArray(v))
+                    return `${where}: expect takes {"field": value}`;
+                break;
+            case 'repeat': {
+                if (!(Number.isInteger(v) && v >= 1 && v <= 1000))
+                    return `${where}: repeat is 1 to 1000`;
+                if (!Array.isArray(s.steps))
+                    return `${where}: repeat needs "steps"`;
+                const inner = checkSteps(s.steps, `${where}.steps`);
+                if (inner)
+                    return inner;
+                break;
+            }
+        }
+    }
+    return null;
+}
+export function parseWords(text) {
+    const w = text.trim().split(/\s+/);
+    const verb = (w[0] ?? '').toLowerCase();
+    const nums = w.slice(1).map(Number);
+    const allNums = w.length > 1 && nums.every((n) => Number.isFinite(n));
+    const rest = w.slice(1).join(' ');
+    switch (verb) {
+        case 'tap':
+        case 'hold':
+            if (w.length >= 3 && Number.isFinite(nums[0]) && Number.isFinite(nums[1]))
+                return { [verb]: [nums[0], nums[1]], ...(Number.isFinite(nums[2]) ? { ms: nums[2] } : {}) };
+            return rest ? { [verb]: rest } : { error: `${verb} x y, or ${verb} <target name>` };
+        case 'drag':
+            if (allNums && nums.length >= 4)
+                return { drag: [[nums[0], nums[1]], [nums[2], nums[3]]], ...(nums.length > 4 ? { ms: nums[4] } : {}) };
+            return { error: 'drag x1 y1 x2 y2 [ms]' };
+        case 'stick':
+            if (allNums && nums.length >= 2)
+                return { stick: [nums[0], nums[1]], ...(nums.length > 2 ? { ms: nums[2] } : {}) };
+            return { error: 'stick dx dy [ms] (-1..1)' };
+        case 'key':
+        case 'pad':
+            if (!w[1])
+                return { error: `${verb} <name> [ms]` };
+            return { [verb]: w[1], ...(Number.isFinite(Number(w[2])) ? { ms: Number(w[2]) } : {}) };
+        case 'wait':
+        case 'frames':
+        case 'speed':
+            return allNums && nums.length === 1 ? { [verb]: nums[0] } : { error: `${verb} <number>` };
+        case 'shot':
+            return { shot: rest || 'shot' };
+        case 'scene':
+        case 'view':
+        case 'segment':
+        case 'cmd':
+            return rest ? { [verb]: rest } : { error: `${verb} <name>` };
+        case 'state':
+        case 'release':
+            return { [verb]: true };
+        default:
+            return { error: `unknown step "${verb}" (tap, hold, drag, stick, key, pad, wait, frames, scene, view, segment, shot, state, release, cmd, speed)` };
+    }
+}
+export function toCommand(s, base = {}) {
+    const verb = verbOf(s);
+    const space = s.space ?? base.space ?? 'px';
+    const device = s.device ?? base.device;
+    const extra = { ...(device ? { device } : {}) };
+    const ms = typeof s.ms === 'number' ? { ms: s.ms } : {};
+    switch (verb) {
+        case 'wait': return { cmd: 'wait', ms: s.wait };
+        case 'frames': return { cmd: 'frames', n: s.frames };
+        case 'tap':
+        case 'hold': {
+            const v = s[verb];
+            return isPair(v) ? { cmd: verb, x: v[0], y: v[1], space, ...ms, ...extra } : { cmd: verb, target: v, ...ms, ...extra };
+        }
+        case 'drag': {
+            const [a, b] = s.drag;
+            return { cmd: 'drag', from: a, to: b, space, ...ms, ...(typeof s.hold_ms === 'number' ? { hold_ms: s.hold_ms } : {}), ...extra };
+        }
+        case 'key': return { cmd: 'key', name: s.key, ...ms };
+        case 'pad': return { cmd: 'pad', button: s.pad, ...ms };
+        case 'stick': return { cmd: 'pad', stick: s.stick, ms: typeof s.ms === 'number' ? s.ms : 500 };
+        case 'scene': return { cmd: 'scene', name: s.scene };
+        case 'view': return { cmd: 'view', name: s.view };
+        case 'segment': return { cmd: 'probe.segment', label: s.segment };
+        case 'shot': return { cmd: 'shot', inline: true, ...(typeof s.scale === 'number' ? { scale: s.scale } : {}) };
+        case 'state': return { cmd: 'state' };
+        case 'speed': return { cmd: 'speed', x: s.speed };
+        case 'release': return { cmd: 'release' };
+        case 'cmd': {
+            const { cmd: name, ...fields } = s;
+            return { ...fields, cmd: name };
+        }
+        default: return null;
+    }
+}
+export function field(state, path) {
+    let cur = state;
+    for (const part of path.split('.')) {
+        if (!cur || typeof cur !== 'object')
+            return undefined;
+        cur = cur[part];
+    }
+    return cur;
+}
+export async function runSteps(steps, bridge, base, hooks) {
+    const now = hooks.now ?? Date.now;
+    const out = [];
+    const stop = hooks.stopOnFail ?? true;
+    for (const s of steps) {
+        const t0 = now();
+        const verb = verbOf(s);
+        if (verb === 'repeat') {
+            for (let i = 0; i < s.repeat; i++) {
+                const inner = await runSteps(s.steps, bridge, base, hooks);
+                out.push(...inner);
+                if (stop && inner.some((r) => !r.ok))
+                    return out;
+            }
+            continue;
+        }
+        if (verb === 'expect') {
+            const st = await bridge.send({ cmd: 'state' });
+            const want = s.expect;
+            const misses = Object.entries(want).filter(([k, v]) => JSON.stringify(field(st, k)) !== JSON.stringify(v)).map(([k, v]) => `${k} is ${JSON.stringify(field(st, k))}, expected ${JSON.stringify(v)}`);
+            const r = { step: s, reply: st, ok: st.ok && !misses.length, ms: now() - t0, ...(misses.length ? { error: misses.join('; ') } : st.ok ? {} : { error: st.error }) };
+            out.push(r);
+            hooks.log?.(`${r.ok ? 'ok ' : 'FAIL'} expect ${JSON.stringify(want)}${r.error ? ` — ${r.error}` : ''}`);
+            if (!r.ok && stop)
+                return out;
+            continue;
+        }
+        const cmd = toCommand(s, base);
+        if (!cmd)
+            continue;
+        const budget = 30_000 + (typeof s.wait === 'number' ? s.wait : 0) + (typeof s.ms === 'number' ? s.ms : 0) + (verb === 'scene' || verb === 'view' ? 90_000 : 0);
+        let reply;
+        try {
+            reply = await bridge.send(cmd, budget);
+        }
+        catch (e) {
+            reply = { ok: false, error: e.message };
+        }
+        const r = { step: s, reply, ok: reply.ok, ms: now() - t0, ...(reply.ok ? {} : { error: reply.error ?? 'refused' }) };
+        if (verb === 'shot' && reply.ok && typeof reply.png === 'string') {
+            r.shot = await hooks.shot(String(s.shot), Buffer.from(reply.png, 'base64'), reply);
+            delete reply.png;
+        }
+        out.push(r);
+        hooks.log?.(`${r.ok ? 'ok ' : 'FAIL'} ${verb} ${JSON.stringify(s[verb])}${r.error ? ` — ${r.error}` : ''}${r.shot ? ` → ${r.shot}` : ''}`);
+        if (!r.ok && stop)
+            return out;
+    }
+    return out;
+}