@houwert/conductor 0.27.2 → 0.29.0

package/dist/commands/input-latency.js

@@ -0,0 +1,348 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.measureKeyLatency = measureKeyLatency;
+exports.printLatencyReport = printLatencyReport;
+/**
+ * Input-to-response latency for `press-key --measure`.
+ *
+ * Three things had to be got right here, all of them learned by measuring on
+ * real Android TV hardware over networked adb rather than assumed:
+ *
+ *  - **A repeat is not a repeated measurement.** Pressing Right twenty times
+ *    walks focus across twenty *different* transitions, some cheap, some
+ *    crossing into a lazily-mounted row. Samples are therefore grouped by the
+ *    transition they actually performed, and the aggregate is reported
+ *    alongside — never instead of — the per-transition breakdown.
+ *
+ *  - **Focus refusing to move is not a hang.** At the end of a rail the app is
+ *    correctly declining to move focus. Reporting that as a timeout would be
+ *    evidence of the sluggishness we are hunting, invented out of correct
+ *    behaviour. `outcome` distinguishes `moved` / `unchanged` / `query-failed`.
+ *
+ *  - **Over networked adb, host-side polling cannot measure this at all.** One
+ *    hierarchy dump costs a full round trip (~400ms on a LAN); focus on a
+ *    healthy TV app moves in 50-150ms. The polling result is then a measurement
+ *    of the network with a deceptively tight variance, so when `pollCost`
+ *    dominates we say so in a structured note. The measurement that does work
+ *    is `pressToFrame`, which is computed entirely from device-side clocks.
+ */
+const runner_js_1 = require("../runner.js");
+const bootstrap_js_1 = require("../drivers/bootstrap.js");
+const focused_js_1 = require("./focused.js");
+const press_key_js_1 = require("./press-key.js");
+const stats_js_1 = require("../stats.js");
+const device_js_1 = require("../android/device.js");
+const profile_frames_js_1 = require("./profile-frames.js");
+async function resolveDeviceId(sessionName) {
+    if (sessionName !== 'default')
+        return sessionName;
+    const detected = await (0, runner_js_1.detectFirstDevice)().catch(() => undefined);
+    if (!detected)
+        throw new Error('no device found; pass --device');
+    return detected;
+}
+/**
+ * Reset, inject, timestamp, settle and dump — all inside one device-side shell.
+ *
+ * The timestamp is taken *after* the injection command returns rather than
+ * before it. `adb shell input keyevent` costs ~713ms on the device because it
+ * spawns an `app_process` JVM per invocation, and that cost lands entirely
+ * before the event is dispatched (`input` injects with WAIT_FOR_FINISH and then
+ * exits). Reading the clock afterwards therefore puts the press timestamp
+ * within a few ms of the actual injection instead of 713ms early, which is the
+ * difference between reporting the app's latency and reporting JVM startup.
+ *
+ * What this does *not* fix is contention: spawning and tearing down a JVM
+ * beside the frames being measured is load, and on a 1.7GB device it competes
+ * for exactly the resources whose scarcity we are looking for. That residual is
+ * reported as a `driver-perturbation` note rather than hidden.
+ */
+async function measurePressResponse(deviceId, appId, keycode, settleMs) {
+    const bracket = await (0, device_js_1.shellBracketed)(deviceId, `dumpsys gfxinfo ${appId} reset; cat /proc/uptime; input keyevent ${keycode}; ` +
+        `cat /proc/uptime; sleep ${(settleMs / 1000).toFixed(2)}; ` +
+        `dumpsys gfxinfo ${appId} framestats`);
+    if (!bracket)
+        return undefined;
+    const stamps = [...bracket.stdout.matchAll(/^\s*(\d+\.\d+)\s+\d+\.\d+\s*$/gm)].map((m) => Number(m[1]) * 1000);
+    if (stamps.length < 2)
+        return undefined;
+    const [beforeInject, afterInject] = stamps;
+    const frames = (0, profile_frames_js_1.parseFramestats)(bracket.stdout)
+        .map((r) => (0, profile_frames_js_1.toFrameSample)(r))
+        .filter((f) => f !== null)
+        .sort((a, b) => a.vsyncNs - b.vsyncNs);
+    // A frame that *started* after the injection is a response to it. Frames
+    // drawn during JVM startup are in the buffer too and must not be counted.
+    const responding = frames.filter((f) => f.vsyncNs / 1e6 >= afterInject);
+    if (responding.length === 0)
+        return undefined;
+    const first = responding[0];
+    const last = responding[responding.length - 1];
+    return {
+        injectionCostMs: (0, stats_js_1.round)(afterInject - beforeInject),
+        response: {
+            pressToFrameMs: (0, stats_js_1.round)(first.completedNs / 1e6 - afterInject),
+            pressToFrameUpperMs: (0, stats_js_1.round)(first.completedNs / 1e6 - beforeInject),
+            dispatchWindowMs: (0, stats_js_1.round)(afterInject - beforeInject),
+            renderBurstMs: (0, stats_js_1.round)((last.completedNs - first.vsyncNs) / 1e6),
+            framesInBurst: responding.length,
+            jankyInBurst: responding.filter((f) => f.totalMs > 16.67).length,
+        },
+    };
+}
+/** One sample: press, then poll focus until its identity changes or we give up. */
+async function sampleOnce(driver, key, index, opts, pollCosts, androidTarget) {
+    let before;
+    try {
+        before = await (0, focused_js_1.queryFocused)(driver);
+    }
+    catch {
+        return {
+            index,
+            key,
+            outcome: 'query-failed',
+            elapsedMs: null,
+            dispatchMs: 0,
+            polls: 0,
+            from: '(unknown)',
+            to: '(unknown)',
+        };
+    }
+    const beforeKey = (0, focused_js_1.focusKey)(before);
+    let response;
+    let injectionCostMs;
+    let dispatchMs = 0;
+    const t0 = performance.now();
+    const keycode = androidTarget ? press_key_js_1.ANDROID_KEYCODE[key] : undefined;
+    if (androidTarget && keycode !== undefined) {
+        // Injection happens inside the device-side bracket, so the press is timed
+        // in the device's own clock domain with no host or adb time in the window.
+        const measured = await measurePressResponse(androidTarget.deviceId, androidTarget.appId, keycode, opts.settleMs);
+        dispatchMs = (0, stats_js_1.round)(performance.now() - t0);
+        response = measured?.response;
+        injectionCostMs = measured?.injectionCostMs;
+        // The bracket already waited out the settle, so focus has landed.
+    }
+    else {
+        const t = performance.now();
+        await (0, press_key_js_1.dispatchKey)(driver, key, opts.holdSeconds);
+        dispatchMs = (0, stats_js_1.round)(performance.now() - t);
+    }
+    const deadline = performance.now() + opts.timeoutMs;
+    let polls = 0;
+    let queryFailed = false;
+    let lastKey = beforeKey;
+    while (performance.now() < deadline) {
+        const pollStart = performance.now();
+        let current;
+        try {
+            current = await (0, focused_js_1.queryFocused)(driver);
+        }
+        catch {
+            queryFailed = true;
+            break;
+        }
+        const pollEnd = performance.now();
+        pollCosts.push((0, stats_js_1.round)(pollEnd - pollStart));
+        polls++;
+        lastKey = (0, focused_js_1.focusKey)(current);
+        if (lastKey !== beforeKey) {
+            return {
+                index,
+                key,
+                outcome: 'moved',
+                // pollEnd is an upper bound: the change could have landed any time
+                // during this dump. pollCost is the error bar.
+                elapsedMs: (0, stats_js_1.round)(pollEnd - t0),
+                dispatchMs,
+                polls,
+                from: beforeKey,
+                to: lastKey,
+                response,
+                injectionCostMs,
+            };
+        }
+        if (opts.pollIntervalMs > 0) {
+            await new Promise((r) => setTimeout(r, opts.pollIntervalMs));
+        }
+    }
+    return {
+        index,
+        key,
+        // Focus queries kept succeeding and the identity never changed: the app is
+        // responding, it simply did not move focus. That is a boundary, not a hang.
+        outcome: queryFailed ? 'query-failed' : 'unchanged',
+        elapsedMs: null,
+        dispatchMs,
+        polls,
+        from: beforeKey,
+        to: lastKey,
+        response,
+        injectionCostMs,
+    };
+}
+function groupByTransition(samples) {
+    const groups = new Map();
+    for (const s of samples) {
+        if (s.outcome !== 'moved')
+            continue;
+        const id = `${s.key}${s.from}${s.to}`;
+        groups.set(id, [...(groups.get(id) ?? []), s]);
+    }
+    return [...groups.entries()]
+        .map(([id, group]) => {
+        const [key, from, to] = id.split('');
+        return {
+            key,
+            from,
+            to,
+            count: group.length,
+            focusChange: (0, stats_js_1.describe)(group.map((s) => s.elapsedMs).filter((v) => v !== null)),
+            pressToFrame: (0, stats_js_1.describe)(group.map((s) => s.response?.pressToFrameMs).filter((v) => v !== undefined)),
+        };
+    })
+        .sort((a, b) => (b.pressToFrame.p50Ms ?? b.focusChange.p50Ms ?? 0) -
+        (a.pressToFrame.p50Ms ?? a.focusChange.p50Ms ?? 0));
+}
+async function measureKeyLatency(sessionName, keys, opts) {
+    const deviceId = await resolveDeviceId(sessionName);
+    const platform = await (0, bootstrap_js_1.detectPlatform)(deviceId).catch(() => 'unknown');
+    const driver = await (0, runner_js_1.getDriver)(sessionName);
+    const notes = [];
+    let androidTarget;
+    let appId;
+    if (platform === 'android') {
+        appId = opts.appId ?? (await (0, device_js_1.resolveAndroidForegroundApp)(deviceId));
+        if (appId) {
+            const probe = await (0, device_js_1.adbShell)(deviceId, ['dumpsys', 'gfxinfo', appId]);
+            if (probe.success)
+                androidTarget = { deviceId, appId };
+        }
+    }
+    const pollCosts = [];
+    const samples = [];
+    for (let i = 0; i < opts.repeat; i++) {
+        samples.push(await sampleOnce(driver, keys[i % keys.length], i, opts, pollCosts, androidTarget));
+    }
+    const outcomes = { moved: 0, unchanged: 0, 'query-failed': 0 };
+    for (const s of samples)
+        outcomes[s.outcome]++;
+    const moved = samples.filter((s) => s.elapsedMs !== null).map((s) => s.elapsedMs);
+    const responses = samples
+        .map((s) => s.response?.pressToFrameMs)
+        .filter((v) => v !== undefined);
+    const focusChange = moved.length > 0 ? (0, stats_js_1.describe)(moved) : undefined;
+    const pollCost = pollCosts.length > 0 ? (0, stats_js_1.describe)(pollCosts) : undefined;
+    const pressToFrame = responses.length > 0 ? (0, stats_js_1.describe)(responses) : undefined;
+    // A poll that costs more than the thing it is timing is measuring itself.
+    if ((0, stats_js_1.hasSamples)(focusChange) && (0, stats_js_1.hasSamples)(pollCost)) {
+        const ratio = (0, stats_js_1.round)(pollCost.p50Ms / focusChange.p50Ms);
+        if (ratio > 0.5) {
+            notes.push({
+                code: 'round-trip-bound',
+                message: `One focus query costs ${pollCost.p50Ms}ms against a focusChange of ` +
+                    `${focusChange.p50Ms}ms, so this result is bounded by transport, not by the app. ` +
+                    `Its small variance reflects a stable connection rather than a precise measurement. ` +
+                    (pressToFrame
+                        ? 'Use pressToFrame, which is computed from device-side clocks.'
+                        : 'Connect over USB rather than networked adb, or profile with `profile frames`.'),
+                pollCostP50Ms: pollCost.p50Ms,
+                focusChangeP50Ms: focusChange.p50Ms,
+                ratio,
+            });
+        }
+    }
+    // The harness spawns a JVM per keypress. On a memory-constrained TV that is
+    // load landing on exactly the resources whose scarcity we are measuring, so
+    // it is declared rather than left for the reader to infer.
+    const injectionCosts = samples
+        .map((s) => s.injectionCostMs)
+        .filter((v) => v !== undefined);
+    if (injectionCosts.length > 0) {
+        const cost = (0, stats_js_1.describe)(injectionCosts);
+        if ((0, stats_js_1.hasSamples)(cost) && cost.p50Ms > 100) {
+            notes.push({
+                code: 'driver-perturbation',
+                message: `Each press is injected with \`adb shell input keyevent\`, which spawns an ` +
+                    `app_process JVM on the device and cost ${cost.p50Ms}ms here. That process starts and ` +
+                    `tears down alongside the frames being measured, so on a memory-constrained device ` +
+                    `some of the jank in this window is the harness. pressToFrame excludes the startup ` +
+                    `time but cannot exclude the contention.`,
+                injectionCostMs: cost.p50Ms,
+            });
+        }
+    }
+    if (androidTarget && !pressToFrame) {
+        notes.push({
+            code: 'no-press-to-frame',
+            message: 'No frames were attributable to any press, so the device-side measurement is absent. ' +
+                'The app may not be redrawing in response, or --settle is too short.',
+        });
+    }
+    if (outcomes.unchanged > 0) {
+        notes.push({
+            code: 'boundary-refusals',
+            message: `${outcomes.unchanged}/${samples.length} press(es) left focus where it was while focus ` +
+                `queries kept succeeding. That is the app declining to move — a rail edge, or a key this ` +
+                `screen ignores — not a hang, and it is excluded from the latency figures.`,
+        });
+    }
+    if (outcomes['query-failed'] > 0) {
+        notes.push({
+            code: 'query-failures',
+            message: `${outcomes['query-failed']}/${samples.length} sample(s) could not read the focused ` +
+                `element at all. Unlike a boundary refusal this does suggest the app or driver is wedged.`,
+        });
+    }
+    return {
+        keys: [...new Set(keys)],
+        deviceId,
+        platform,
+        appId,
+        samples,
+        outcomes,
+        focusChange,
+        pressToFrame,
+        pollCost,
+        byTransition: groupByTransition(samples),
+        notes,
+    };
+}
+function line(label, d) {
+    if (!(0, stats_js_1.hasSamples)(d))
+        return `  ${label.padEnd(14)} n/a`;
+    return (`  ${label.padEnd(14)} p50 ${(0, stats_js_1.fmt)(d.p50Ms)}  p90 ${(0, stats_js_1.fmt)(d.p90Ms)}  p99 ${(0, stats_js_1.fmt)(d.p99Ms)}  ` +
+        `max ${(0, stats_js_1.fmt)(d.maxMs)}  (n=${d.count}, σ ${(0, stats_js_1.fmt)(d.stddevMs)})`);
+}
+function shortId(key) {
+    const [id, , bounds] = key.split('|');
+    return id || bounds || key;
+}
+function printLatencyReport(r) {
+    console.log(`press-key ${r.keys.join(',')} --measure — ${r.samples.length} sample(s) on ${r.deviceId}`);
+    console.log(`  outcomes:      moved=${r.outcomes.moved} unchanged=${r.outcomes.unchanged} ` +
+        `queryFailed=${r.outcomes['query-failed']}`);
+    if (r.pressToFrame)
+        console.log(line('press→frame', r.pressToFrame));
+    console.log(line('focus→move', r.focusChange));
+    console.log(line('poll cost', r.pollCost));
+    if (r.byTransition.length > 0) {
+        console.log('\n  by transition (aggregates above mix these together)');
+        for (const t of r.byTransition) {
+            const primary = (0, stats_js_1.hasSamples)(t.pressToFrame) ? t.pressToFrame : t.focusChange;
+            const which = (0, stats_js_1.hasSamples)(t.pressToFrame) ? 'press→frame' : 'focus→move';
+            console.log(`    ${t.key}  ${shortId(t.from)} → ${shortId(t.to)}  ` +
+                `${which} p50 ${(0, stats_js_1.fmt)(primary.p50Ms)} max ${(0, stats_js_1.fmt)(primary.maxMs)} (n=${t.count})`);
+        }
+    }
+    const withBurst = r.samples.filter((s) => s.response);
+    if (withBurst.length > 0) {
+        const burst = (0, stats_js_1.describe)(withBurst.map((s) => s.response.renderBurstMs));
+        console.log(line('render burst', burst));
+        const window = (0, stats_js_1.describe)(withBurst.map((s) => s.response.dispatchWindowMs));
+        console.log(`  dispatch window p50 ${(0, stats_js_1.fmt)(window.p50Ms)} — press→frame is a lower bound; ` +
+            `its upper bound is that much higher.`);
+    }
+    for (const note of r.notes)
+        console.log(`\n  note [${note.code}]: ${note.message}`);
+}

package/dist/commands/list-apps.js

@@ -23,6 +23,8 @@ async function listApps(opts = {}, sessionName = 'default') {
     }
     const platform = await (0, bootstrap_js_1.detectPlatform)(deviceId);
     let appIds;
+    // Display names, where the platform gives them up cheaply (iOS/tvOS only).
+    const appNames = {};
     if (platform === 'web') {
         (0, output_js_1.printError)('list-apps is not supported on web. Use foreground-app to get the current URL.', opts);
         return 1;
@@ -43,6 +45,11 @@ async function listApps(opts = {}, sessionName = 'default') {
         try {
             const parsed = JSON.parse(result.stdout);
             appIds = Object.keys(parsed).sort();
+            for (const id of appIds) {
+                const name = parsed[id]?.CFBundleDisplayName ?? parsed[id]?.CFBundleName;
+                if (typeof name === 'string' && name)
+                    appNames[id] = name;
+            }
         }
         catch {
             (0, output_js_1.printError)('Failed to parse app list from simctl', opts);
@@ -62,7 +69,7 @@ async function listApps(opts = {}, sessionName = 'default') {
             .sort();
     }
     if (opts.json) {
-        (0, output_js_1.printData)({ status: 'ok', apps: appIds }, opts);
+        (0, output_js_1.printData)({ status: 'ok', apps: appIds, ...(Object.keys(appNames).length ? { appNames } : {}) }, opts);
     }
     else {
         for (const id of appIds)

package/dist/commands/list-devices.js

@@ -21,8 +21,25 @@ const cdp_discovery_js_1 = require("../drivers/cdp-discovery.js");
 // Module-scoped because the discover function returns Device[]; bolting an
 // extra return field onto the public type would ripple beyond this fix.
 let listAvdsError;
+/**
+ * Android TV identifies itself through `ro.build.characteristics` (or the
+ * leanback feature). One cheap getprop per device beats guessing from a model
+ * name like `sdk_google_atv_x86` or `AFTKA`.
+ */
+async function annotateAndroidFormFactors(devices, ids) {
+    await Promise.all(ids.map(async (id) => {
+        const device = devices.find((d) => d.id === id);
+        if (!device)
+            return;
+        const res = await (0, runner_js_1.spawnCommand)((0, sdk_js_1.resolveAndroidTool)('adb'), ['-s', id, 'shell', 'getprop', 'ro.build.characteristics'], { env: (0, sdk_js_1.androidSpawnEnv)() });
+        if (!res.success)
+            return;
+        device.formFactor = /\btv\b/i.test(res.stdout) ? 'tv' : 'handset';
+    }));
+}
 async function discoverBootedDevices() {
     const devices = [];
+    const androidIds = [];
     // Try adb devices (Android)
     const adb = await (0, runner_js_1.spawnCommand)((0, sdk_js_1.resolveAndroidTool)('adb'), ['devices', '-l'], {
         env: (0, sdk_js_1.androidSpawnEnv)(),
@@ -40,9 +57,11 @@ async function discoverBootedDevices() {
                 const modelMatch = trimmed.match(/model:(\S+)/);
                 const name = modelMatch ? modelMatch[1].replace(/_/g, ' ') : id;
                 devices.push({ id, name, platform: 'android', status });
+                androidIds.push(id);
             }
         }
     }
+    await annotateAndroidFormFactors(devices, androidIds);
     // Try xcrun simctl list (iOS simulators)
     const xcrun = await (0, runner_js_1.spawnCommand)('xcrun', ['simctl', 'list', 'devices', 'booted', '--json']);
     if (xcrun.success) {
@@ -143,7 +162,17 @@ async function discoverAvailableDevices() {
         for (const line of emu.stdout.split('\n')) {
             const name = line.trim();
             if (name) {
-                devices.push({ id: name, name, platform: 'android', status: 'available' });
+                // A shut-down AVD can't be probed, so fall back to its name: the AVD
+                // wizard calls TV images "Television"/"Android TV" or `_atv_`.
+                devices.push({
+                    id: name,
+                    name,
+                    platform: 'android',
+                    status: 'available',
+                    formFactor: /(^|[_\s-])(tv|television|atv|leanback)([_\s-]|$)/i.test(name)
+                        ? 'tv'
+                        : 'handset',
+                });
             }
         }
     }

package/dist/commands/metro.js

@@ -29,6 +29,8 @@ async function pidsOnPort(port) {
     });
 }
 async function metroStop(opts, metroOpts) {
+    // Deliberately not auto-discovered: this kills whatever listens on the port,
+    // and guessing one risks killing a Metro the user did not mean to stop.
     const port = metroOpts.port ?? 8081;
     const pids = await pidsOnPort(port);
     if (pids.length === 0) {
@@ -65,13 +67,13 @@ async function metroStop(opts, metroOpts) {
     return 0;
 }
 async function metroReload(opts, sessionName, metroOpts) {
-    const port = metroOpts.port ?? 8081;
     let deviceId;
     let platform;
     if (sessionName && sessionName !== 'default') {
         deviceId = sessionName;
         platform = await (0, bootstrap_js_1.detectPlatform)(deviceId).catch(() => undefined);
     }
+    const port = await (0, metro_cdp_js_1.resolveMetroPort)({ port: metroOpts.port, deviceId, platform });
     // Try CDP Page.reload first (works on Hermes/Fusebox).
     try {
         await (0, metro_cdp_js_1.cdpCall)('Page.reload', undefined, {

package/dist/commands/native-rn.js

@@ -55,11 +55,11 @@ async function nativeRnSet(args, opts, sessionName, rnOpts) {
     }
     const path = args.path.split('.').filter((s) => s.length > 0);
     const { json } = parseValue(args.value);
-    const port = rnOpts.port ?? 8081;
     const { deviceId, platformPromise } = resolveSession(sessionName);
     const client = new metro_cdp_js_1.MetroCdpClient();
     try {
         const platform = await platformPromise;
+        const port = await (0, metro_cdp_js_1.resolveMetroPort)({ port: rnOpts.port, deviceId, platform });
         await client.connect({ port, deviceId, platform, targetIndex: rnOpts.targetIndex });
         const raw = await client.evaluate((0, metro_scripts_js_1.makeOverridePropsScript)(tag, path, json), true);
         const res = JSON.parse(raw);
@@ -86,11 +86,11 @@ async function nativeRnProps(args, opts, sessionName, rnOpts) {
         (0, output_js_1.printError)('native-rn-props needs --react-tag <n> (from native-inspect rn.reactTag)', opts);
         return 1;
     }
-    const port = rnOpts.port ?? 8081;
     const { deviceId, platformPromise } = resolveSession(sessionName);
     const client = new metro_cdp_js_1.MetroCdpClient();
     try {
         const platform = await platformPromise;
+        const port = await (0, metro_cdp_js_1.resolveMetroPort)({ port: rnOpts.port, deviceId, platform });
         await client.connect({ port, deviceId, platform, targetIndex: rnOpts.targetIndex });
         const raw = await client.evaluate((0, metro_scripts_js_1.makeRnPropsScript)(tag), true);
         const res = JSON.parse(raw);

package/dist/commands/network.js

@@ -140,10 +140,10 @@ async function networkLogs(opts, sessionName, netOpts) {
             return 1;
         }
     }
-    const port = netOpts.port ?? 8081;
     const { deviceId, platformPromise } = resolveSession(sessionName);
     try {
         const platform = await platformPromise;
+        const port = await (0, metro_cdp_js_1.resolveMetroPort)({ port: netOpts.port, deviceId, platform });
         const client = new metro_cdp_js_1.MetroCdpClient();
         await client.connect({ port, deviceId, platform, targetIndex: netOpts.targetIndex });
         await client.evaluate(INSTALL_SHIM_SCRIPT);
@@ -227,10 +227,10 @@ async function networkRequest(url, opts, sessionName, reqOpts) {
   }
 })()
 `;
-    const port = reqOpts.port ?? 8081;
     const { deviceId, platformPromise } = resolveSession(sessionName);
     try {
         const platform = await platformPromise;
+        const port = await (0, metro_cdp_js_1.resolveMetroPort)({ port: reqOpts.port, deviceId, platform });
         const client = new metro_cdp_js_1.MetroCdpClient();
         await client.connect({ port, deviceId, platform, targetIndex: reqOpts.targetIndex });
         const result = await client.evaluate(script);