@houwert/conductor 0.28.0 → 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/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);

package/dist/commands/press-key.js

@@ -1,12 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VALID_KEYS = exports.HELP = void 0;
+exports.ANDROID_KEYCODE = exports.VALID_KEYS = exports.HELP = void 0;
+exports.dispatchKey = dispatchKey;
 exports.pressKey = pressKey;
 exports.HELP = `  press-key <key>                     Press a key (Enter, Backspace, Home, ...)
     --long-press                      Hold the button ~1.5s (tvOS remote buttons)
-    --duration <seconds>              Hold for a custom duration (tvOS remote buttons)`;
+    --duration <seconds>              Hold for a custom duration (tvOS remote buttons)
+    --measure                         Time the app's response to the press
+    --repeat <n>                      With --measure, take n samples and report a distribution
+    --sequence <k1,k2,...>            With --repeat, cycle these keys so focus oscillates
+    --timeout <ms>                    With --measure, give up on a sample after n ms (default 3000)
+    --poll-interval <ms>              With --measure, delay between focus polls (default 0)
+    --settle <ms>                     With --measure on Android, render time to allow (default 700)`;
 const runner_js_1 = require("../runner.js");
 const output_js_1 = require("../output.js");
+const input_latency_js_1 = require("./input-latency.js");
 const ios_js_1 = require("../drivers/ios.js");
 const android_js_1 = require("../drivers/android.js");
 const web_js_1 = require("../drivers/web.js");
@@ -87,7 +95,7 @@ const VEGA_REMOTE_BUTTONS = {
     VolumeDown: 'volumeDown',
 };
 // Android keyevent codes
-const ANDROID_KEYCODE = {
+exports.ANDROID_KEYCODE = {
     Home: 3,
     Back: 4,
     Enter: 66,
@@ -124,6 +132,72 @@ const ANDROID_KEYCODE = {
     'TV Input HDMI 2': 244,
     'TV Input HDMI 3': 245,
 };
+/**
+ * Send `key` on an already-connected driver. Split out of `pressKey` so
+ * `--measure` can reuse one driver across repeats instead of paying driver
+ * setup on every sample.
+ */
+async function dispatchKey(driver, matched, holdSeconds) {
+    if (driver instanceof ios_js_1.IOSDriver) {
+        if (driver.platform === 'tvos') {
+            const tvosButton = TVOS_REMOTE_BUTTONS[matched];
+            const iosButton = IOS_BUTTON_MAP[matched];
+            if (tvosButton) {
+                await driver.pressButton(tvosButton, holdSeconds);
+            }
+            else if (iosButton) {
+                await driver.pressButton(iosButton, holdSeconds);
+            }
+            // Keys not mapped on tvOS are silently ignored
+        }
+        else {
+            const iosKey = IOS_KEY_MAP[matched];
+            const iosButton = IOS_BUTTON_MAP[matched];
+            if (iosKey) {
+                await driver.pressKey(iosKey);
+            }
+            else if (iosButton) {
+                await driver.pressButton(iosButton);
+            }
+            // Keys not mapped on iOS (e.g. Back, VolumeUp) are silently ignored
+        }
+    }
+    else if (driver instanceof web_js_1.WebDriver) {
+        const WEB_KEY_MAP = {
+            Enter: 'Enter',
+            Tab: 'Tab',
+            Backspace: 'Backspace',
+            Delete: 'Delete',
+            Escape: 'Escape',
+            Home: 'Home',
+            End: 'End',
+            // Canvas webtv apps (Lightning/WPE) navigate focus via the D-pad, which they listen
+            // for as arrow keys (and Enter for select). Maps the TV remote onto web keyboard.
+            'Remote Dpad Up': 'ArrowUp',
+            'Remote Dpad Down': 'ArrowDown',
+            'Remote Dpad Left': 'ArrowLeft',
+            'Remote Dpad Right': 'ArrowRight',
+            'Remote Dpad Center': 'Enter',
+        };
+        const webKey = WEB_KEY_MAP[matched];
+        if (webKey) {
+            await driver.pressKey(webKey);
+        }
+    }
+    else if (driver instanceof vega_js_1.VegaDriver) {
+        const vegaButton = VEGA_REMOTE_BUTTONS[matched];
+        if (vegaButton) {
+            await driver.pressButton(vegaButton);
+        }
+        // Keys not mapped on vega are silently ignored
+    }
+    else if (driver instanceof android_js_1.AndroidDriver) {
+        const code = exports.ANDROID_KEYCODE[matched];
+        if (code !== undefined) {
+            await driver.pressKeyEvent(code);
+        }
+    }
+}
 async function pressKey(key, opts = {}, sessionName = 'default', flags = {}) {
     // A held press is requested via --long-press (default 1.5s) or an explicit --duration.
     const holdSeconds = flags.duration ?? (flags.longPress ? 1.5 : undefined);
@@ -136,67 +210,39 @@ async function pressKey(key, opts = {}, sessionName = 'default', flags = {}) {
         (0, output_js_1.printError)(`Unknown key "${key}". Valid keys: ${exports.VALID_KEYS.join(', ')}`, opts);
         return 1;
     }
-    const result = await (0, runner_js_1.runDirect)(async (driver) => {
-        if (driver instanceof ios_js_1.IOSDriver) {
-            if (driver.platform === 'tvos') {
-                const tvosButton = TVOS_REMOTE_BUTTONS[matched];
-                const iosButton = IOS_BUTTON_MAP[matched];
-                if (tvosButton) {
-                    await driver.pressButton(tvosButton, holdSeconds);
-                }
-                else if (iosButton) {
-                    await driver.pressButton(iosButton, holdSeconds);
-                }
-                // Keys not mapped on tvOS are silently ignored
-            }
-            else {
-                const iosKey = IOS_KEY_MAP[matched];
-                const iosButton = IOS_BUTTON_MAP[matched];
-                if (iosKey) {
-                    await driver.pressKey(iosKey);
-                }
-                else if (iosButton) {
-                    await driver.pressButton(iosButton);
-                }
-                // Keys not mapped on iOS (e.g. Back, VolumeUp) are silently ignored
+    if (flags.measure) {
+        const sequence = [matched];
+        for (const raw of flags.sequence ?? []) {
+            const k = exports.VALID_KEYS.find((v) => v.toLowerCase() === raw.trim().toLowerCase());
+            if (!k) {
+                (0, output_js_1.printError)(`Unknown key "${raw}" in --sequence. Valid keys: ${exports.VALID_KEYS.join(', ')}`, opts);
+                return 1;
             }
+            sequence.push(k);
         }
-        else if (driver instanceof web_js_1.WebDriver) {
-            const WEB_KEY_MAP = {
-                Enter: 'Enter',
-                Tab: 'Tab',
-                Backspace: 'Backspace',
-                Delete: 'Delete',
-                Escape: 'Escape',
-                Home: 'Home',
-                End: 'End',
-                // Canvas webtv apps (Lightning/WPE) navigate focus via the D-pad, which they listen
-                // for as arrow keys (and Enter for select). Maps the TV remote onto web keyboard.
-                'Remote Dpad Up': 'ArrowUp',
-                'Remote Dpad Down': 'ArrowDown',
-                'Remote Dpad Left': 'ArrowLeft',
-                'Remote Dpad Right': 'ArrowRight',
-                'Remote Dpad Center': 'Enter',
-            };
-            const webKey = WEB_KEY_MAP[matched];
-            if (webKey) {
-                await driver.pressKey(webKey);
-            }
+        const measureOpts = {
+            repeat: flags.repeat ?? 1,
+            timeoutMs: flags.timeoutMs ?? 3000,
+            pollIntervalMs: flags.pollIntervalMs ?? 0,
+            settleMs: flags.settleMs ?? 700,
+            appId: flags.appId,
+            holdSeconds,
+        };
+        try {
+            const report = await (0, input_latency_js_1.measureKeyLatency)(sessionName, sequence, measureOpts);
+            if (opts.json)
+                (0, output_js_1.printData)({ status: 'ok', ...report }, opts);
+            else
+                (0, input_latency_js_1.printLatencyReport)(report);
+            // Nothing measurable at all is a failure; boundary refusals are not.
+            return report.outcomes.moved === 0 && !report.pressToFrame ? 1 : 0;
         }
-        else if (driver instanceof vega_js_1.VegaDriver) {
-            const vegaButton = VEGA_REMOTE_BUTTONS[matched];
-            if (vegaButton) {
-                await driver.pressButton(vegaButton);
-            }
-            // Keys not mapped on vega are silently ignored
+        catch (err) {
+            (0, output_js_1.printError)(`press-key ${matched} --measure — ${err instanceof Error ? err.message : String(err)}`, opts);
+            return 1;
         }
-        else if (driver instanceof android_js_1.AndroidDriver) {
-            const code = ANDROID_KEYCODE[matched];
-            if (code !== undefined) {
-                await driver.pressKeyEvent(code);
-            }
-        }
-    }, sessionName);
+    }
+    const result = await (0, runner_js_1.runDirect)((driver) => dispatchKey(driver, matched, holdSeconds), sessionName);
     if (result.success) {
         (0, output_js_1.printSuccess)(`press-key ${matched} — done`, opts);
         return 0;