@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/commands/phone.js

@@ -0,0 +1,398 @@
+import { execFile } from 'node:child_process';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join, relative, resolve } from 'node:path';
+import { EXIT, servedRoot } from "./verify.js";
+import { serveDir } from "../verify/serve.js";
+import { parseAt } from "../inspect/describe.js";
+import { distinctControls, flattenAx, parseAx, parseDevices, phoneSupport, pickDevice, popupClose, runner, START_WORDS, sweepPoints, landscapeOf, landscapeTap, toLandscape, } from "../phone/baguette.js";
+import { frameStats, phoneRoutes, tapSeen } from "../phone/listen.js";
+import { ui } from "../ui.js";
+const realDeps = {
+    support: phoneSupport,
+    sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+    bootstatus: (udid) => new Promise((ok) => execFile('xcrun', ['simctl', 'bootstatus', udid, '-b'], { timeout: 180_000 }, () => ok())),
+    now: () => new Date(),
+    upright: (file) => new Promise((ok) => execFile('sips', ['-r', '90', file], { timeout: 30_000 }, () => ok())),
+};
+async function sweep(run, udid, points) {
+    const out = [];
+    let i = 0;
+    const worker = async () => {
+        while (i < points.length) {
+            const p = points[i++];
+            const n = parseAx(await run(['describe-ui', '--udid', udid, '--x', String(p.x), '--y', String(p.y)], 15_000).catch(() => ''));
+            if (n)
+                out.push(...flattenAx(n));
+        }
+    };
+    await Promise.all([worker(), worker(), worker(), worker()]);
+    return out;
+}
+async function closeTip(run, udid, d, answer, waitMs) {
+    const read = async () => parseAx(await run(['describe-ui', '--udid', udid], 60_000).catch(() => ''));
+    let root = await read();
+    for (let waited = 0; !popupClose(root) && waited < waitMs; waited += 500) {
+        await d.sleep(500);
+        root = await read() ?? root;
+    }
+    const close = popupClose(root);
+    if (!close)
+        return { root, closed: false };
+    const g = landscapeOf(root);
+    const c = center(g ? toLandscape(close, g) : close);
+    const f = root?.frame ?? { width: 402, height: 874 };
+    const t = g ? landscapeTap(c.x, c.y, g) : { ...c, width: f.width, height: f.height };
+    await run(['tap', '--udid', udid, '--x', String(t.x), '--y', String(t.y), '--width', String(t.width), '--height', String(t.height)]);
+    answer.popup_closed = true;
+    answer.tips_closed = (answer.tips_closed ?? 0) + 1;
+    for (let waited = 0; waited < 3000; waited += 500) {
+        await d.sleep(500);
+        const next = await read();
+        if (next)
+            root = next;
+        if (!popupClose(next))
+            break;
+    }
+    await d.sleep(800);
+    return { root, closed: true };
+}
+export const MAX_TIPS = 3;
+export const NEXT_TIP_MS = 2500;
+async function closeTips(run, udid, d, answer, waitMs) {
+    let r = await closeTip(run, udid, d, answer, waitMs);
+    for (let i = 1; i < MAX_TIPS && r.closed; i++) {
+        const next = await closeTip(run, udid, d, answer, NEXT_TIP_MS);
+        r = { root: next.root ?? r.root, closed: next.closed };
+    }
+    return r.root;
+}
+export const SAFARI_BAR_PT = 100;
+const SWIPE_DIRS = { left: [-1, 0], right: [1, 0], up: [0, -1], down: [0, 1] };
+export function changedFields(a, b) {
+    if (!a || !b || typeof a !== 'object' || typeof b !== 'object')
+        return [];
+    const x = a, y = b;
+    return [...new Set([...Object.keys(x), ...Object.keys(y)])].filter((k) => k !== 't' && JSON.stringify(x[k]) !== JSON.stringify(y[k]));
+}
+const center = (c) => ({ x: Math.round(c.x + c.width / 2), y: Math.round(c.y + c.height / 2) });
+export const inControl = (s) => {
+    if (!s || typeof s !== 'object')
+        return null;
+    const o = s;
+    return o.control === true || (o.control === undefined && o.screen === 'playing') ? true : o.control === undefined && o.screen === undefined ? null : false;
+};
+export const FRONT_DOOR_PRESSES = 3;
+const screenOf = (s) => (s && typeof s === 'object' && 'screen' in s ? String(s.screen) : null);
+export async function phone(opts, io = console, deps = {}) {
+    const d = { ...realDeps, ...deps };
+    const u = ui(io, 'phone');
+    const answer = {
+        observed: false, reporter: false, popup_closed: false, controls: [], small_controls: [], start: null,
+        state_before: null, state_after_start: null, state_end: null, frames: {}, errors: [], shots: [], notes: [],
+    };
+    const support = d.support();
+    if (!support.ok) {
+        answer.reason = support.why;
+        answer.install = support.install;
+        return finish(answer, opts, io);
+    }
+    const run = d.run ?? runner(support.bin);
+    let served = null;
+    const reports = [];
+    const control = { leave: false, left: false };
+    let url = opts.target && /^https?:\/\//.test(opts.target) ? opts.target : '';
+    const dir = url ? null : resolve(opts.target ?? '.');
+    if (dir) {
+        const root = servedRoot(dir);
+        if (!root) {
+            u.error(`no dist/index.html in ${dir}`, 'build the game first (npm run build)');
+            return EXIT.error;
+        }
+        served = await serveDir(root, phoneRoutes(() => readFile(join(root, 'index.html'), 'utf8'), reports, control));
+        url = served.url;
+        answer.reporter = true;
+    }
+    answer.url = url;
+    let device = null;
+    let bootedByUs = false;
+    const outDir = resolve(opts.out ?? join(dir ?? '.', '.funtools', 'phone', d.now().toISOString().replace(/[:.]/g, '-')));
+    const phases = [];
+    const mark = (name) => { const t = Date.now(); const prev = phases[phases.length - 1]; if (prev)
+        prev.to = t; phases.push({ name, from: t, to: Infinity }); };
+    const shot = async (name) => {
+        const file = join(outDir, `${String(answer.shots.length + 1).padStart(2, '0')}-${name}.png`);
+        await run(['screenshot', '--udid', device.udid, '--scale', '3', '--output', file], 30_000)
+            .then(async () => { if (answer.orientation === 'landscape')
+            await d.upright(file); answer.shots.push(file); }).catch((e) => answer.notes.push(`screenshot ${name}: ${e.message}`));
+    };
+    const lastState = () => [...reports].reverse().find((r) => r.kind === 'frames' || r.kind === 'hello')?.state ?? null;
+    try {
+        device = pickDevice(parseDevices(await run(['list', '--json'], 30_000)), opts.sim);
+        if (!device) {
+            answer.reason = opts.sim ? `no simulator named ${opts.sim} (baguette list shows them)` : 'no iPhone simulator is installed (Xcode → Settings → Components → iOS)';
+            return finish(answer, opts, io);
+        }
+        answer.device = device;
+        await mkdir(outDir, { recursive: true });
+        answer.dir = outDir;
+        if (device.state !== 'Booted') {
+            bootedByUs = true;
+            await run(['boot', '--udid', device.udid], 240_000);
+            await d.bootstatus(device.udid);
+        }
+        answer.booted_by_us = bootedByUs;
+        const orientation = opts.orientation ?? 'portrait';
+        answer.orientation = orientation;
+        if (orientation === 'landscape')
+            await run(['orientation', '--udid', device.udid, 'landscape-left'], 30_000);
+        else
+            await run(['orientation', '--udid', device.udid, 'portrait'], 30_000).catch(() => '');
+        mark('loading');
+        const udid = device.udid;
+        await run(['openurl', '--udid', udid, url], 60_000).catch(async (e) => {
+            answer.notes.push(`the first open failed (${String(e?.message ?? e).split('\n').pop()?.slice(0, 120)}); opened again`);
+            await d.sleep(4000);
+            await run(['openurl', '--udid', udid, url], 60_000);
+        });
+        for (let waited = 0; waited < 20_000; waited += 500) {
+            if (!answer.reporter ? waited >= 6000 : reports.some((r) => r.kind === 'hello'))
+                break;
+            await d.sleep(500);
+        }
+        const hello = reports.find((r) => r.kind === 'hello');
+        if (answer.reporter && !hello)
+            answer.notes.push('the page never reported its load in 20 s (a script error before load, or Safari could not reach the Mac)');
+        answer.page = hello ? { w: Number(hello.w), h: Number(hello.h), dpr: Number(hello.dpr), insets: hello.insets ?? null, ua: String(hello.ua ?? '') } : null;
+        const root = await closeTips(run, device.udid, d, answer, 5000);
+        const land = orientation === 'landscape' ? landscapeOf(root) : null;
+        if (orientation === 'landscape' && !land)
+            answer.notes.push('landscape: the accessibility tree did not come back letterboxed as baguette 0.2.0 gives it, so nothing is pressed — look at the screenshots');
+        const size = land ? land.size : root?.frame ? { width: Math.round(root.frame.width), height: Math.round(root.frame.height) } : { width: 402, height: 874 };
+        answer.size = size;
+        mark('title');
+        await shot('loaded');
+        answer.state_before = lastState();
+        const pageTop = answer.page && answer.page.h > 0 ? size.height - answer.page.h : 0;
+        if (land) {
+            answer.controls = distinctControls(flattenAx(parseAx(await run(['describe-ui', '--udid', device.udid], 60_000).catch(() => '')) ?? root))
+                .map((c) => toLandscape(c, land)).filter((c) => c.y + c.height / 2 > Math.max(pageTop, 40));
+        }
+        else if (orientation !== 'landscape')
+            answer.controls = distinctControls(await sweep(run, device.udid, sweepPoints(size)))
+                .filter((c) => { const y = c.y + c.height / 2; return y > 50 && y < size.height - SAFARI_BAR_PT; });
+        answer.small_controls = answer.controls.filter((c) => c.width < 44 || c.height < 44);
+        answer.start = answer.controls.find((c) => START_WORDS.test(c.label)) ?? null;
+        const marked = () => { const r = [...reports].reverse().find((x) => x.kind === 'frames' || x.kind === 'hello'); return (r?.start ?? null); };
+        let offset = null;
+        const calibrate = (sx, sy, since) => {
+            const down = reports.find((r) => r.kind === 'input' && r.type === 'pointerdown' && r.at >= since && typeof r.y === 'number');
+            if (down && !offset)
+                offset = { x: sx - Number(down.x), y: sy - Number(down.y) };
+        };
+        const markedControl = () => {
+            const m = marked();
+            if (!m || (orientation === 'landscape' && !land))
+                return null;
+            const pw = answer.page?.w ?? size.width, ph = answer.page?.h ?? size.height;
+            if (m.y + m.h / 2 > ph || m.y + m.h / 2 < 0 || m.x + m.w / 2 > pw || m.x + m.w / 2 < 0) {
+                const named = m.text && m.text !== m.label ? `"${m.text}"${m.label ? ` (aria-label "${m.label}")` : ''}` : `"${m.label || m.text || 'data-fpx-start'}"`;
+                const line = `the start control ${named} is off screen at this size: ${m.w}x${m.h} at left ${m.x}, top ${m.y} in a ${pw}x${ph} px page (${orientation}) — no player can press it`;
+                if (!answer.notes.includes(line)) {
+                    answer.notes.push(line);
+                    (answer.findings ??= []).push(line);
+                }
+                return null;
+            }
+            const o = offset ?? { x: land && answer.page ? Math.max(0, Math.round((size.width - answer.page.w) / 2)) : 0, y: pageTop };
+            return { role: 'marked data-fpx-start', label: m.label || 'data-fpx-start', x: m.x + o.x, y: m.y + o.y, width: m.w, height: m.h };
+        };
+        const namedAgain = async () => {
+            const cs = land
+                ? distinctControls(flattenAx(parseAx(await run(['describe-ui', '--udid', device.udid], 60_000).catch(() => '')) ?? root)).map((c) => toLandscape(c, land)).filter((c) => c.y + c.height / 2 > Math.max(pageTop, 40))
+                : orientation !== 'landscape' ? distinctControls(await sweep(run, device.udid, sweepPoints(size))).filter((c) => { const y = c.y + c.height / 2; return y > 50 && y < size.height - SAFARI_BAR_PT; }) : [];
+            return { found: cs.find((c) => START_WORDS.test(c.label)) ?? null, cs };
+        };
+        if (!answer.start)
+            answer.start = markedControl();
+        const tap = (x, y) => {
+            const t = land ? landscapeTap(x, y, land) : { x, y, width: size.width, height: size.height };
+            return run(['tap', '--udid', device.udid, '--x', String(t.x), '--y', String(t.y), '--width', String(t.width), '--height', String(t.height)]);
+        };
+        if (answer.start) {
+            const c = center(answer.start);
+            const pressStart = async () => {
+                const at = answer.start?.role === 'marked data-fpx-start' ? center(markedControl() ?? answer.start) : c;
+                const since = Date.now();
+                await tap(at.x, at.y);
+                await d.sleep(1500);
+                calibrate(at.x, at.y, since);
+                return { seen: tapSeen(reports, since), state: lastState() };
+            };
+            let pressed = await pressStart();
+            mark('after-start');
+            const before = screenOf(answer.state_before);
+            const stuck = () => before !== null && before === screenOf(pressed.state);
+            if (stuck() && answer.reporter) {
+                const { down, click } = pressed.seen;
+                answer.notes.push(down && !click
+                    ? `the first tap on "${answer.start.label}" reached the page (pointerdown/up) but WebKit sent no click: Safari kept the tap for its own UI`
+                    : !down ? `the first tap on "${answer.start.label}" never reached the page` : `the first tap on "${answer.start.label}" clicked and __FPX_STATE__().screen stayed "${before}"`);
+                await closeTips(run, device.udid, d, answer, 0);
+                pressed = await pressStart();
+                answer.start_taps = 2;
+            }
+            await shot('after-start');
+            answer.state_after_start = pressed.state;
+            if (stuck())
+                answer.notes.push(`the start control "${answer.start.label}" was tapped${answer.start_taps === 2 ? ' twice' : ''} and __FPX_STATE__().screen stayed "${before}" in WebKit${pressed.seen.down && !pressed.seen.click ? ' (touch reached the page, no click)' : ''} — press it in Chromium (verify --front-door, or --engine webkit for Safari's engine) to compare`);
+            else {
+                let waits = 0;
+                for (let i = 0; i < FRONT_DOOR_PRESSES && inControl(lastState()) === false; i++) {
+                    let next = markedControl();
+                    if (!next) {
+                        const again = await namedAgain();
+                        next = again.found;
+                        if (!next) {
+                            const was = screenOf(lastState());
+                            await d.sleep(2500);
+                            if (inControl(lastState()) === true)
+                                break;
+                            if (screenOf(lastState()) !== was && waits++ < FRONT_DOOR_PRESSES) {
+                                i--;
+                                continue;
+                            }
+                            if (!answer.findings?.length)
+                                answer.notes.push(`after a press on "${was ?? '?'}", no start control by name or mark: the accessibility tree had ${again.cs.length ? again.cs.map((c) => `"${c.label || c.role}"`).join(', ') : 'no controls'}`);
+                            break;
+                        }
+                    }
+                    (answer.front_door ??= []).push(screenOf(lastState()) ?? '?');
+                    const p = center(next);
+                    const since = Date.now();
+                    await tap(p.x, p.y);
+                    await d.sleep(1500);
+                    calibrate(p.x, p.y, since);
+                }
+                if (answer.front_door) {
+                    answer.state_after_start = lastState();
+                    await shot('after-front-door');
+                }
+            }
+        }
+        else if (orientation !== 'landscape' || land)
+            answer.notes.push('no start control by name (play, start, go, begin, new game…) in the accessibility tree, and none marked data-fpx-start: --taps presses a point');
+        mark('play');
+        const shots = Math.max(1, Math.min(4, Math.round(opts.seconds / 2)));
+        const gap = (opts.seconds * 1000) / shots;
+        let t = 0;
+        for (const raw of orientation === 'landscape' && !land ? [] : opts.taps) {
+            const p = parseAt(raw, size);
+            if (!p) {
+                answer.notes.push(`--taps ${raw} is not a point on the ${size.width}x${size.height} screen`);
+                continue;
+            }
+            await tap(p.x, p.y);
+            answer.taps_made = (answer.taps_made ?? 0) + 1;
+            await d.sleep(600);
+            t += 600;
+        }
+        for (const dir of opts.swipes ?? []) {
+            const v = SWIPE_DIRS[dir];
+            if (!v || land || orientation === 'landscape') {
+                answer.notes.push(v ? '--swipes: portrait only' : `--swipes ${dir}: left, right, up or down`);
+                continue;
+            }
+            const cx = Math.round(size.width / 2), cy = Math.round(pageTop + (answer.page?.h ?? size.height - pageTop) / 2), reach = Math.round(size.width / 4);
+            const before = lastState();
+            await run(['swipe', '--udid', device.udid, '--start-x', String(cx), '--start-y', String(cy), '--end-x', String(cx + v[0] * reach), '--end-y', String(cy + v[1] * reach), '--width', String(size.width), '--height', String(size.height), '--duration', '0.2']);
+            await d.sleep(1200);
+            (answer.swipes_made ??= []).push({ dir, changed: changedFields(before, lastState()) });
+            t += 1200;
+        }
+        for (let i = 0; i < shots; i++) {
+            await d.sleep(Math.max(0, gap - (i === 0 ? t : 0)));
+            await shot(`play-${i + 1}`);
+        }
+        mark('end');
+        await d.sleep(1100);
+        answer.state_end = lastState();
+        answer.observed = true;
+    }
+    catch (e) {
+        answer.notes.push(e instanceof Error ? e.message : String(e));
+        if (!answer.observed)
+            answer.reason = answer.reason ?? (e instanceof Error ? e.message : String(e));
+    }
+    finally {
+        if (device && bootedByUs && !opts.keep)
+            await run(['shutdown', '--udid', device.udid], 120_000).catch((e) => answer.notes.push(`shutdown: ${e.message} — shut it down with: baguette shutdown --udid ${device.udid}`));
+        else if (device && served && !opts.keep) {
+            control.leave = true;
+            for (let waited = 0; waited < 3000 && !control.left; waited += 250)
+                await d.sleep(250);
+            if (!control.left)
+                answer.notes.push('the page did not leave: close its Safari tab if it still plays sound');
+        }
+        await served?.close();
+    }
+    const playPhase = phases.find((p) => p.name === 'play');
+    if (playPhase && inControl(answer.state_end) === false) {
+        playPhase.name = `on "${screenOf(answer.state_end) ?? 'the page'}", never in control`;
+        answer.notes.push(`the game never reported control (__FPX_STATE__().control) in ${opts.seconds} s after the start${answer.front_door ? ` and ${answer.front_door.length} more press(es) of its marked start` : ''}: those frames are not play`);
+    }
+    for (const p of phases.slice(0, -1)) {
+        const ms = reports.filter((r) => r.kind === 'frames' && r.at > p.from && r.at <= p.to + 1000).flatMap((r) => r.ms ?? []);
+        answer.frames[p.name] = frameStats(ms);
+    }
+    for (const r of reports) {
+        if (r.kind !== 'error' && r.kind !== 'rejection' && r.kind !== 'console')
+            continue;
+        const where = r.file ? `${String(r.file).replace(/^https?:\/\/[^/]+\//, '')}:${r.line}:${r.col}` : String(r.stack ?? '').split('\n').find((l) => /:\d+:\d+/.test(l))?.trim() ?? '';
+        answer.errors.push({ kind: r.kind, message: String(r.message).slice(0, 300), where });
+    }
+    if (answer.dir)
+        await writeFile(join(answer.dir, 'phone.json'), JSON.stringify(answer, null, 2) + '\n').catch(() => { });
+    return finish(answer, opts, io);
+}
+function finish(a, opts, io) {
+    const u = ui(io, 'phone');
+    if (opts.json) {
+        io.log(JSON.stringify(a, null, 2));
+        return !a.observed ? EXIT.not_observed : a.findings?.length ? EXIT.fail : EXIT.pass;
+    }
+    if (!a.device || !a.observed) {
+        u.summary('not_observed', `${a.reason ?? 'nothing observed'}${a.install ? ` — optional: ${a.install}` : ''}${a.install ? '; verify --viewport phone stays the check that runs everywhere' : ''}`);
+        for (const n of a.notes)
+            u.line(n);
+        return EXIT.not_observed;
+    }
+    u.heading(`phone · ${a.device.name} (${a.device.runtime}) · Mobile Safari · ${a.orientation ?? 'portrait'}${a.size ? ` · ${a.size.width}x${a.size.height} pt` : ''}${a.booted_by_us ? ' · booted and shut down' : ' · already running, left running'}`);
+    if (a.page)
+        u.item('note', 'page', `${a.page.w}x${a.page.h} CSS px @ DPR ${a.page.dpr}${a.page.insets ? ` · safe area top ${a.page.insets[0]} right ${a.page.insets[1]} bottom ${a.page.insets[2]} left ${a.page.insets[3]}` : ''}`);
+    if (a.popup_closed)
+        u.item('note', 'Safari', (a.tips_closed ?? 1) > 1 ? `closed ${a.tips_closed} of its first-run tips over the page, one after another` : 'closed its first-run tip over the page');
+    u.item(a.controls.length ? 'pass' : 'not_observed', 'controls', a.controls.length ? a.controls.map((c) => `${c.label || c.role} ${Math.round(c.width)}x${Math.round(c.height)}`).join(' · ') : 'none found by the accessibility sweep');
+    if (a.small_controls.length)
+        u.item('warn', 'under 44 pt', a.small_controls.map((c) => `${c.label || c.role} ${Math.round(c.width)}x${Math.round(c.height)}`).join(' · '));
+    u.item(a.start ? 'pass' : 'not_observed', 'start', a.start ? `tapped "${a.start.label}"${a.start.role === 'marked data-fpx-start' ? ' (found by its data-fpx-start mark)' : ''}${a.front_door ? `, then again on ${a.front_door.map((s) => `"${s}"`).join(', ')}` : ''}` : 'no start control by name or data-fpx-start mark');
+    const states = [a.state_before, a.state_after_start, a.state_end].map(screenOf);
+    if (states.some((s) => s !== null))
+        u.item('note', 'screen', states.map((s) => s ?? '–').join(' → '));
+    for (const [phase, f] of Object.entries(a.frames)) {
+        u.item(!f || / never in control$/.test(phase) ? 'not_observed' : f.long > f.frames * 0.05 ? 'warn' : 'pass', `frames · ${phase}`, f ? `p50 ${f.p50} ms · p95 ${f.p95} ms (~${f.fps_p95} fps at the p95) · max ${f.max} · ${f.long} over 33 ms of ${f.frames} — WebKit's pacing on the Mac, not the phone's speed` : a.reporter ? 'no frames reported' : 'a URL has no reporter (point phone at the game folder)');
+    }
+    u.item(a.errors.length ? 'warn' : a.reporter ? 'pass' : 'not_observed', 'errors', a.errors.length ? `${a.errors.length}` : a.reporter ? 'none reported by the page' : 'not read (a URL has no reporter)');
+    for (const e of a.errors.slice(0, 8))
+        u.line(`  ${e.kind}: ${e.message}${e.where ? ` at ${e.where}` : ''}`);
+    for (const f of a.findings ?? [])
+        u.item('fail', 'start', f);
+    for (const n of a.notes.filter((x) => !(a.findings ?? []).includes(x)))
+        u.item('warn', 'note', n);
+    u.item('note', 'screenshots', a.shots.map((s) => relative(process.cwd(), s)).join(' · '));
+    if (a.findings?.length) {
+        u.summary('fail', `${a.findings.length === 1 ? 'a fault' : `${a.findings.length} faults`} a player meets on this phone (above); the rest is evidence, not a verdict`);
+        return EXIT.fail;
+    }
+    u.summary('pass', 'observed in real WebKit — look at the screenshots; evidence, not a verdict');
+    return EXIT.pass;
+}

package/dist/commands/pick.js

@@ -0,0 +1,146 @@
+import { copyFileSync, existsSync, mkdirSync } from 'node:fs';
+import { basename, extname, join, relative, resolve, sep } from 'node:path';
+import { EXIT } from "./verify.js";
+import { ensurePipeline } from "./next.js";
+import { evaluate } from "../pipeline/pipeline.js";
+import { appendEntry, nextQuestion, readProgress } from "../progress/progress.js";
+import { answerQuestion } from "../progress/answers.js";
+import { addDecision, readDecisions } from "../memory/decisions.js";
+import { logMaking, readLanes } from "../lanes/lanes.js";
+import { laneOf } from "../lanes/where.js";
+import { ui } from "../ui.js";
+export const PICK_SUBCOMMANDS = ['list', 'choose'];
+const T = 'npx @funpixel/tools';
+const slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 40) || 'pick';
+export const isPick = (q) => !!q.frames;
+export function settlePicks(root, now = new Date()) {
+    const s = readProgress(root);
+    const have = new Set(readDecisions(root).map((d) => d.from).filter(Boolean));
+    const out = [];
+    for (const q of s.questions.filter(isPick)) {
+        if (!q.answer || q.answer.by !== 'owner' || have.has(q.id))
+            continue;
+        const pick = q.answer.pick;
+        const d = addDecision(root, {
+            choice: `${q.topic ?? 'pick'}: ${pick} (${q.frames?.[pick] ?? pick})`,
+            over: q.options.filter((o) => o !== pick).join(', '),
+            because: `the owner picked it by eye (${q.id}, ${q.answer.at.slice(0, 10)})`,
+            owner: q.answer.words ?? `picked ${pick}`, from: q.id, ...(q.frames?.[pick] ? { shot: q.frames[pick] } : {}),
+            touches: q.lane ? [q.lane] : [], status: 'open',
+        }, now);
+        if (q.lane)
+            logMaking(root, { lane: q.lane, kind: 'pick', line: `the owner picked ${pick} for ${q.topic} (${q.id}) → ${d.id}`, at: now.toISOString() });
+        out.push(d);
+    }
+    return out;
+}
+export async function pick(opts, io = console) {
+    const u = ui(io, 'pick');
+    const here = resolve(opts.dir ?? '.');
+    const root = laneOf(here)?.home ?? here;
+    if (!existsSync(join(root, 'funpixel.json'))) {
+        u.error(`${root} is not a game folder (no funpixel.json)`, '--dir <game>');
+        return EXIT.error;
+    }
+    const now = opts.now ?? new Date();
+    try {
+        if (opts.sub === 'propose')
+            return propose(root, opts, u, io, now);
+        if (opts.sub === 'choose') {
+            const [which, option, ...words] = opts.args;
+            if (opts.by !== 'owner') {
+                u.error('a pick is the owner\'s', `show the candidates in the chat; when the owner chooses there, record it with their words: \`${T} pick choose ${which ?? '<topic>'} ${option ?? '<option>'} --by owner\``);
+                return EXIT.fail;
+            }
+            const q = readProgress(root).questions.filter(isPick).reverse().find((x) => x.id === which || x.topic === which);
+            if (!q) {
+                u.error(`no pick ${which ?? ''}`, `${T} pick lists them`);
+                return EXIT.error;
+            }
+            answerQuestion(root, q.id, option ?? '', { words: words.join(' '), now });
+            const made = settlePicks(root, now);
+            if (opts.json)
+                io.log(JSON.stringify({ q: q.id, pick: option, decisions: made }, null, 2));
+            else
+                u.summary('pass', `the owner picked ${option} for ${q.topic} (${q.id})${made.length ? `: ${made.map((d) => d.id).join(', ')} in design/decisions.md` : ''}${q.lane ? `; lane ${q.lane} may merge once its gate and verifier pass` : ''}`);
+            return EXIT.pass;
+        }
+        const made = settlePicks(root, now);
+        const picks = readProgress(root).questions.filter(isPick);
+        const ds = readDecisions(root);
+        if (opts.json) {
+            io.log(JSON.stringify({ picks: picks.map((q) => ({ id: q.id, topic: q.topic, lane: q.lane, options: q.options, frames: q.frames, answer: q.answer, decision: ds.find((d) => d.from === q.id)?.id ?? null })), new_decisions: made.map((d) => d.id) }, null, 2));
+            return picks.length ? EXIT.pass : EXIT.not_observed;
+        }
+        if (!picks.length) {
+            u.summary('not_observed', `no picks yet: \`${T} pick <topic> a.png b.png c.png --lane <id>\``);
+            return EXIT.not_observed;
+        }
+        for (const q of [...picks].sort((a, b) => Number(!!a.answer) - Number(!!b.answer))) {
+            const d = ds.find((x) => x.from === q.id);
+            u.item(q.answer?.by === 'owner' ? 'pass' : 'warn', `${q.id} ${q.topic}${q.lane ? ` (lane ${q.lane})` : ''}: ${q.answer?.by === 'owner' ? `the owner picked ${q.answer.pick}${d ? ` → ${d.id}` : ''}` : `waiting for the owner: ${q.options.join(' / ')}`}`);
+        }
+        return EXIT.pass;
+    }
+    catch (e) {
+        u.error(e.message);
+        return EXIT.error;
+    }
+}
+function propose(root, opts, u, io, now) {
+    const [topicRaw, ...files] = opts.args;
+    if (!topicRaw || files.length < 2 || files.length > 4) {
+        u.error('a pick is a topic and two to four candidate frames', `${T} pick hero-hold a.png b.png c.png --lane look`);
+        return EXIT.error;
+    }
+    const topic = slug(topicRaw);
+    const lanes = readLanes(root);
+    const lane = opts.lane ? lanes?.lanes.find((l) => l.id === opts.lane) : undefined;
+    if (opts.lane && !lane) {
+        u.error(`no lane ${opts.lane}`, `${T} lanes status lists them`);
+        return EXIT.error;
+    }
+    if (readProgress(root).questions.some((q) => isPick(q) && q.topic === topic && !q.answer)) {
+        u.error(`a pick on ${topic} is already waiting for the owner`, `${T} pick lists it`);
+        return EXIT.error;
+    }
+    const frames = {};
+    const dir = join(root, 'design', 'picks', topic);
+    mkdirSync(dir, { recursive: true });
+    for (const [i, f] of files.entries()) {
+        const src = resolve(f);
+        if (!existsSync(src)) {
+            u.error(`${f} does not exist`);
+            return EXIT.error;
+        }
+        let label = slug(basename(f, extname(f)));
+        if (label in frames)
+            label = `${label}-${i + 1}`;
+        const rel = relative(root, src).split(sep).join('/');
+        const inDesign = rel.startsWith('design/') && !rel.startsWith('..');
+        const dest = inDesign ? rel : `design/picks/${topic}/${label}${extname(f).toLowerCase()}`;
+        if (!inDesign)
+            copyFileSync(src, join(root, dest));
+        frames[label] = dest;
+    }
+    let stage = lane?.stage ?? '';
+    if (!stage) {
+        try {
+            const [p] = ensurePipeline(root, now);
+            stage = evaluate(root, p, null).current?.stage.id ?? 'slice';
+        }
+        catch {
+            stage = 'slice';
+        }
+    }
+    const s = readProgress(root);
+    const q = { type: 'ask', id: nextQuestion(s), at: now.toISOString(), kind: 'taste', stage, text: opts.question?.trim() || `Pick the ${topicRaw.replace(/-/g, ' ')}: ${Object.keys(frames).join(', ')}? ${lane ? `Lane ${lane.id} waits on your choice before it merges.` : ''}`.trim(), options: Object.keys(frames), frames, topic, ...(lane ? { lane: lane.id } : {}) };
+    appendEntry(root, q);
+    if (lane)
+        logMaking(root, { lane: lane.id, kind: 'pick', line: `put ${Object.keys(frames).length} candidates for ${topic} to the owner (${q.id}): ${Object.keys(frames).join(', ')}`, at: now.toISOString() });
+    if (opts.json)
+        io.log(JSON.stringify({ ask: q }, null, 2));
+    else
+        u.summary('pass', `${q.id}: ${Object.keys(frames).length} candidates for ${topic}: show them in the chat and record the owner's choice (\`${T} pick choose ${topic} <option> --by owner "<their words>"\`)${lane ? `; lane ${lane.id} cannot merge until the owner picks` : ''}`);
+    return EXIT.pass;
+}