@houwert/conductor 0.28.0 → 0.29.0

package/dist/commands/run-flow.js

@@ -4,15 +4,58 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HELP = void 0;
+exports.aggregateRuns = aggregateRuns;
 exports.runFlow = runFlow;
 exports.HELP = `  run-flow <file> [--device <id>]     Run a Maestro YAML flow file
     --env KEY=VALUE                   Inject env var (repeatable; overrides flow env block)
-    --benchmark                       Print elapsed time for each command and total flow time`;
+    --benchmark                       Print elapsed time for each command and total flow time
+    --repeat <n>                      With --benchmark, run the flow n times and report p50/p90/σ
+    --json                            With --benchmark --repeat, emit the aggregate as JSON`;
 const path_1 = __importDefault(require("path"));
 const runner_js_1 = require("../runner.js");
 const flow_runner_js_1 = require("../drivers/flow-runner.js");
 const output_js_1 = require("../output.js");
-async function runFlow(file, opts = {}, sessionName = 'default', env = {}, benchmark = false) {
+const stats_js_1 = require("../stats.js");
+/**
+ * Aggregate per-run timings by command label. Keyed on label rather than
+ * position so a flow whose branches differ between runs still lines up.
+ */
+function aggregateRuns(runs) {
+    const byLabel = new Map();
+    for (const run of runs) {
+        for (const entry of run.entries) {
+            const slot = byLabel.get(entry.label) ?? { times: [], failures: 0 };
+            slot.times.push(entry.ms);
+            if (!entry.ok)
+                slot.failures++;
+            byLabel.set(entry.label, slot);
+        }
+    }
+    return {
+        runs: runs.length,
+        total: (0, stats_js_1.describe)(runs.map((r) => r.totalMs)),
+        commands: [...byLabel.entries()]
+            .map(([label, v]) => ({
+            label,
+            runs: v.times.length,
+            failures: v.failures,
+            ...(0, stats_js_1.describe)(v.times),
+        }))
+            .sort((a, b) => (b.p50Ms ?? 0) - (a.p50Ms ?? 0)),
+    };
+}
+function printAggregate(agg) {
+    console.log(`\nBenchmark over ${agg.runs} run(s)`);
+    console.log(`  total  p50 ${(0, stats_js_1.fmt)(agg.total.p50Ms)}  p90 ${(0, stats_js_1.fmt)(agg.total.p90Ms)}  ` +
+        `σ ${(0, stats_js_1.fmt)(agg.total.stddevMs)}  min ${(0, stats_js_1.fmt)(agg.total.minMs)}  max ${(0, stats_js_1.fmt)(agg.total.maxMs)}`);
+    console.log(`\n  ${'p50'.padStart(9)} ${'p90'.padStart(9)} ${'σ'.padStart(8)}  n  command`);
+    for (const c of agg.commands) {
+        console.log(`  ${(0, stats_js_1.fmt)(c.p50Ms).padStart(9)} ${(0, stats_js_1.fmt)(c.p90Ms).padStart(9)} ` +
+            `${(0, stats_js_1.fmt)(c.stddevMs).padStart(8)}  ${c.runs}  ${c.label}` +
+            (c.failures > 0 ? `  (${c.failures} failed)` : ''));
+    }
+}
+async function runFlow(file, opts = {}, sessionName = 'default', env = {}, benchmark = false, repeat = 1) {
     if (!file) {
         (0, output_js_1.printError)('run-flow requires <file>', opts);
         return 1;
@@ -21,8 +64,31 @@ async function runFlow(file, opts = {}, sessionName = 'default', env = {}, bench
     try {
         const driver = await (0, runner_js_1.getDriver)(sessionName);
         const flow = await (0, flow_runner_js_1.parseFlowFile)(resolvedFile, env);
-        await (0, flow_runner_js_1.executeFlow)(flow, driver, { cwd: path_1.default.dirname(resolvedFile), env, benchmark });
-        (0, output_js_1.printSuccess)(`run-flow "${file}" — done`, opts);
+        if (repeat <= 1) {
+            await (0, flow_runner_js_1.executeFlow)(flow, driver, { cwd: path_1.default.dirname(resolvedFile), env, benchmark });
+            (0, output_js_1.printSuccess)(`run-flow "${file}" — done`, opts);
+            return 0;
+        }
+        const runs = [];
+        for (let i = 0; i < repeat; i++) {
+            const entries = [];
+            console.log(`\n── run ${i + 1}/${repeat} ─────────────────────────────`);
+            const started = performance.now();
+            await (0, flow_runner_js_1.executeFlow)(flow, driver, {
+                cwd: path_1.default.dirname(resolvedFile),
+                env,
+                benchmark,
+                benchmarkSink: (e) => entries.push(e),
+            });
+            runs.push({ totalMs: (0, stats_js_1.round)(performance.now() - started), entries });
+        }
+        const agg = aggregateRuns(runs);
+        if (opts.json)
+            (0, output_js_1.printData)({ status: 'ok', benchmark: agg }, opts);
+        else {
+            printAggregate(agg);
+            (0, output_js_1.printSuccess)(`run-flow "${file}" — ${repeat} runs done`, opts);
+        }
         return 0;
     }
     catch (err) {

package/dist/drivers/flow-runner.js

@@ -392,6 +392,7 @@ async function executeFlow(flow, driver, opts = {}) {
         output: opts.output ?? {},
         depth: opts.depth ?? 0,
         benchmark: opts.benchmark,
+        benchmarkSink: opts.benchmarkSink,
     };
     const flowStart = opts.benchmark ? perf_hooks_1.performance.now() : 0;
     if (flow.onFlowStart?.length) {
@@ -515,9 +516,11 @@ async function executeCommand(cmd, driver, opts) {
     else {
         process.stdout.write(`${indent}→ ${label} ... `);
     }
-    const t0 = opts.benchmark ? perf_hooks_1.performance.now() : 0;
+    const timing = opts.benchmark || opts.benchmarkSink;
+    const t0 = timing ? perf_hooks_1.performance.now() : 0;
     try {
         await executeCommandBody(key, resolvedVal, driver, opts);
+        opts.benchmarkSink?.({ label, depth: opts.depth, ms: perf_hooks_1.performance.now() - t0, ok: true });
         const elapsed = opts.benchmark ? `  (${fmtMs(perf_hooks_1.performance.now() - t0)})` : '';
         if (!isCompound) {
             console.log(`ok${elapsed}`);
@@ -528,6 +531,7 @@ async function executeCommand(cmd, driver, opts) {
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
+        opts.benchmarkSink?.({ label, depth: opts.depth, ms: perf_hooks_1.performance.now() - t0, ok: false });
         const elapsed = opts.benchmark ? `  (${fmtMs(perf_hooks_1.performance.now() - t0)})` : '';
         if (optional) {
             // For compound commands the sub-command already printed its warning/failure
@@ -1273,6 +1277,7 @@ async function executeCommandBody(key, val, driver, opts) {
                     output: opts.output,
                     depth: childDepth,
                     benchmark: opts.benchmark,
+                    benchmarkSink: opts.benchmarkSink,
                 });
             }
             else {
@@ -1293,6 +1298,7 @@ async function executeCommandBody(key, val, driver, opts) {
                         output: opts.output,
                         depth: childDepth,
                         benchmark: opts.benchmark,
+                        benchmarkSink: opts.benchmarkSink,
                     });
                 }
             }

package/dist/drivers/metro-cdp.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MetroCdpClient = void 0;
 exports.selectDebuggerUrl = selectDebuggerUrl;
 exports.resolveDebuggerUrl = resolveDebuggerUrl;
+exports.resolveMetroPort = resolveMetroPort;
 exports.cdpCall = cdpCall;
 /**
  * One-shot CDP client to Metro's debugger endpoint.
@@ -62,14 +63,38 @@ function selectDebuggerUrl(targets, opts, displayName) {
  * Throws with a clear message if Metro is unreachable or no target matches.
  */
 async function resolveDebuggerUrl(opts) {
-    const port = opts.port ?? 8081;
+    const port = await resolveMetroPort(opts);
     const host = opts.host ?? 'localhost';
-    const targets = await (0, metro_js_1.fetchTargets)(port, host);
+    let targets;
+    try {
+        targets = await (0, metro_js_1.fetchTargets)(port, host);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new Error(`Cannot reach Metro on ${host}:${port} — ${detail}.\n` +
+            `Pass --port <n> if Metro listens elsewhere (a project may set RCT_METRO_PORT); ` +
+            `\`conductor workspace info\` reports the port it can see.`);
+    }
     let displayName;
     if (opts.deviceId && opts.platform) {
         displayName = (await (0, metro_discovery_js_1.getDeviceDisplayName)(opts.platform, opts.deviceId)) ?? undefined;
     }
-    return selectDebuggerUrl(targets, opts, displayName);
+    return selectDebuggerUrl(targets, { ...opts, port }, displayName);
+}
+/**
+ * Metro's port for this device: the explicit --port, else whatever the device is
+ * actually connected to, else 8081. Auto-discovery matters because a project
+ * that sets RCT_METRO_PORT otherwise fails with an opaque connection error.
+ */
+async function resolveMetroPort(opts) {
+    if (opts.port !== undefined)
+        return opts.port;
+    if (opts.deviceId && opts.platform) {
+        const discovered = await (0, metro_discovery_js_1.discoverMetroPortForDevice)(opts.platform, opts.deviceId).catch(() => null);
+        if (discovered)
+            return discovered;
+    }
+    return 8081;
 }
 /**
  * Open a short-lived CDP socket, send a single method, return the result.

package/dist/index.js

@@ -42,6 +42,8 @@ const debug_js_1 = require("./commands/debug.js");
 const network_js_1 = require("./commands/network.js");
 const flow_record_js_1 = require("./commands/flow-record.js");
 const profile_js_1 = require("./commands/profile.js");
+const profile_frames_js_1 = require("./commands/profile-frames.js");
+const profile_js_js_1 = require("./commands/profile-js.js");
 const crashes_js_1 = require("./commands/crashes.js");
 const flow_recorder_js_1 = require("./drivers/flow-recorder.js");
 const foreground_app_js_1 = require("./commands/foreground-app.js");
@@ -61,7 +63,6 @@ const start_device_js_1 = require("./commands/start-device.js");
 const stop_device_js_1 = require("./commands/stop-device.js");
 const delete_device_js_1 = require("./commands/delete-device.js");
 const logs_js_1 = require("./commands/logs.js");
-const cases_js_1 = require("./commands/cases.js");
 const memory_js_1 = require("./commands/memory.js");
 const metro_js_1 = require("./commands/metro.js");
 const clipboard_js_1 = require("./commands/clipboard.js");
@@ -89,7 +90,6 @@ const COMMAND_HELP = {
     'list-devices': list_devices_js_1.HELP,
     'foreground-app': foreground_app_js_1.HELP,
     'list-apps': list_apps_js_1.HELP,
-    cases: cases_js_1.HELP,
     'copy-app': copy_app_js_1.HELP,
     'download-app': download_app_js_1.HELP,
     'install-app': install_app_js_1.HELP,
@@ -225,6 +225,10 @@ async function main() {
             'force',
             'yes',
             'update',
+            'measure',
+            'report',
+            'timeline',
+            'baselines',
         ],
         string: [
             'device',
@@ -256,6 +260,9 @@ async function main() {
             'source',
             'level',
             'save',
+            'save-baseline',
+            'sequence',
+            'settle',
             'diff',
             'vs',
             'top',
@@ -294,13 +301,6 @@ async function main() {
             'speed',
             'threshold',
             'reference',
-            'project',
-            'junit',
-            'verdict',
-            'note',
-            'column',
-            'build',
-            'environment',
         ],
         alias: { h: 'help', v: 'verbose', V: 'version', o: 'output', y: 'yes' },
     });
@@ -664,6 +664,15 @@ async function main() {
             exitCode = await (0, press_key_js_1.pressKey)(key, opts, sessionName, {
                 longPress: argv['long-press'],
                 duration: durationArg !== undefined ? Number(durationArg) : undefined,
+                measure: argv['measure'],
+                repeat: argv['repeat'] !== undefined ? Number(argv['repeat']) : undefined,
+                timeoutMs: argv['timeout'] !== undefined ? Number(argv['timeout']) : undefined,
+                pollIntervalMs: argv['poll-interval'] !== undefined ? Number(argv['poll-interval']) : undefined,
+                settleMs: argv['settle'] !== undefined ? Number(argv['settle']) : undefined,
+                sequence: typeof argv['sequence'] === 'string'
+                    ? argv['sequence'].split(',')
+                    : undefined,
+                appId: argv['app'],
             });
             break;
         }
@@ -878,35 +887,6 @@ async function main() {
                 interval: argv['interval'] !== undefined ? Number(argv['interval']) : undefined,
             });
             break;
-        case 'cases': {
-            // Repo-scoped, not device-scoped: cases and their results are files.
-            const root = argv['project'] ?? process.cwd();
-            const sub = rest[0] ?? 'list';
-            if (sub === 'list') {
-                exitCode = await (0, cases_js_1.casesList)(root, opts);
-            }
-            else if (sub === 'report') {
-                exitCode = await (0, cases_js_1.casesReport)(root, argv['junit'] ?? '', {
-                    ...opts,
-                    build: argv['build'],
-                    environment: argv['environment'],
-                });
-            }
-            else if (sub === 'result') {
-                exitCode = await (0, cases_js_1.casesResult)(root, rest[1] ?? '', argv['verdict'] ?? 'passed', {
-                    ...opts,
-                    note: argv['note'],
-                    column: argv['column'],
-                    build: argv['build'],
-                    environment: argv['environment'],
-                });
-            }
-            else {
-                console.error(`Unknown cases subcommand "${sub}". Use list, report or result.`);
-                exitCode = 1;
-            }
-            break;
-        }
         case 'logs':
             exitCode = await (0, logs_js_1.logs)(opts, sessionName, {
                 source: argv['source'],
@@ -939,7 +919,7 @@ async function main() {
             const rawEnv = argv['env'];
             const envPairs = Array.isArray(rawEnv) ? rawEnv : rawEnv ? [rawEnv] : [];
             const flowEnv = Object.fromEntries(envPairs.map((e) => e.split('=', 2)));
-            exitCode = await (0, run_flow_js_1.runFlow)(file, opts, sessionName, flowEnv, argv['benchmark']);
+            exitCode = await (0, run_flow_js_1.runFlow)(file, opts, sessionName, flowEnv, argv['benchmark'], argv['repeat'] !== undefined ? Number(argv['repeat']) : 1);
             break;
         }
         case 'run-flow-inline': {
@@ -1018,12 +998,15 @@ async function main() {
             const sub = (rest[0] ?? '').toLowerCase();
             const port = argv['port'] !== undefined ? Number(argv['port']) : undefined;
             const targetIndex = argv['target'] !== undefined ? Number(argv['target']) : undefined;
+            const top = argv['top'] !== undefined ? Number(argv['top']) : undefined;
             if (sub === 'cpu') {
                 const durationSec = argv['duration'] !== undefined ? Number(argv['duration']) : 10;
                 exitCode = await (0, profile_js_1.profileCpu)(opts, sessionName, {
                     durationSec,
                     out: argv['out'],
                     appId: rest[1],
+                    report: argv['report'],
+                    top,
                 });
             }
             else if (sub === 'memory') {
@@ -1035,14 +1018,67 @@ async function main() {
                     appId: rest[1],
                 });
             }
+            else if (sub === 'frames') {
+                const sub2 = (rest[1] ?? '').toLowerCase();
+                if (sub2 === 'reset') {
+                    exitCode = await (0, profile_frames_js_1.profileFramesReset)(opts, sessionName, rest[2]);
+                }
+                else if (sub2 === 'report') {
+                    exitCode = await (0, profile_frames_js_1.profileFramesReport)(opts, sessionName, {
+                        appId: rest[2],
+                        trackSec: argv['track'] !== undefined ? Number(argv['track']) : undefined,
+                        intervalMs: argv['interval'] !== undefined ? Number(argv['interval']) : undefined,
+                        top,
+                        saveBaseline: argv['save-baseline'],
+                        diff: argv['diff'],
+                        listBaselines: argv['baselines'],
+                    });
+                }
+                else {
+                    console.error('Usage: conductor profile frames <reset|report> [<appId>]');
+                    exitCode = 1;
+                }
+            }
+            else if (sub === 'js') {
+                const sub2 = (rest[1] ?? '').toLowerCase();
+                const jsOpts = {
+                    port,
+                    targetIndex,
+                    out: argv['out'],
+                    top,
+                    durationSec: argv['duration'] !== undefined ? Number(argv['duration']) : undefined,
+                };
+                if (sub2 === 'record') {
+                    exitCode = await (0, profile_js_js_1.profileJsRecord)(opts, sessionName, jsOpts);
+                }
+                else if (sub2 === 'start') {
+                    exitCode = await (0, profile_js_js_1.profileJsStart)(opts, sessionName, jsOpts);
+                }
+                else if (sub2 === 'stop') {
+                    exitCode = await (0, profile_js_js_1.profileJsStop)(opts, sessionName, jsOpts);
+                }
+                else if (sub2 === '_hold') {
+                    exitCode = await (0, profile_js_js_1.profileJsHold)(sessionName, jsOpts);
+                }
+                else {
+                    console.error('Usage: conductor profile js <record|start|stop>');
+                    exitCode = 1;
+                }
+            }
             else if (sub === 'react') {
                 const sub2 = (rest[1] ?? '').toLowerCase();
-                const top = argv['top'] !== undefined ? Number(argv['top']) : 20;
+                const reactOpts = {
+                    port,
+                    targetIndex,
+                    maxCommits: argv['max-commits'] !== undefined ? Number(argv['max-commits']) : undefined,
+                    maxComponents: argv['max-components'] !== undefined ? Number(argv['max-components']) : undefined,
+                    timeline: argv['timeline'],
+                };
                 if (sub2 === 'start') {
-                    exitCode = await (0, profile_js_1.profileReactStart)(opts, sessionName, { port, targetIndex });
+                    exitCode = await (0, profile_js_1.profileReactStart)(opts, sessionName, reactOpts);
                 }
                 else if (sub2 === 'stop') {
-                    exitCode = await (0, profile_js_1.profileReactStop)(opts, sessionName, { port, targetIndex }, top);
+                    exitCode = await (0, profile_js_1.profileReactStop)(opts, sessionName, reactOpts, top ?? 20);
                 }
                 else {
                     console.error('Usage: conductor profile react <start|stop>');
@@ -1050,7 +1086,7 @@ async function main() {
                 }
             }
             else {
-                console.error('Usage: conductor profile <cpu|memory|react> [args]');
+                console.error('Usage: conductor profile <cpu|memory|frames|js|react> [args]');
                 exitCode = 1;
             }
             break;

package/dist/stats.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * Percentile / dispersion helpers shared by the profiling commands.
+ *
+ * Percentiles use nearest-rank on a sorted copy so a p99 over a handful of
+ * samples still names a real observation rather than an interpolated one that
+ * never happened.
+ *
+ * With no samples every figure is `null`, never 0. A missing measurement that
+ * reads as `0ms` is a missing measurement that reads as a *perfect* one, and a
+ * consumer has to remember to check `count` to avoid believing it. `null`
+ * propagates through arithmetic and comparison loudly enough to notice.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EMPTY_DISTRIBUTION = void 0;
+exports.hasSamples = hasSamples;
+exports.percentile = percentile;
+exports.round = round;
+exports.roundOrNull = roundOrNull;
+exports.describe = describe;
+exports.fmt = fmt;
+exports.EMPTY_DISTRIBUTION = {
+    count: 0,
+    minMs: null,
+    maxMs: null,
+    meanMs: null,
+    stddevMs: null,
+    p50Ms: null,
+    p90Ms: null,
+    p95Ms: null,
+    p99Ms: null,
+};
+function hasSamples(d) {
+    return d !== undefined && d.count > 0;
+}
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return null;
+    const rank = Math.ceil((p / 100) * sorted.length);
+    return sorted[Math.min(sorted.length - 1, Math.max(0, rank - 1))];
+}
+function round(n, digits = 2) {
+    const f = 10 ** digits;
+    return Math.round(n * f) / f;
+}
+/** `round` that passes `null` through, for optional measurements. */
+function roundOrNull(n, digits = 2) {
+    return n === null ? null : round(n, digits);
+}
+function describe(values) {
+    if (values.length === 0)
+        return { ...exports.EMPTY_DISTRIBUTION };
+    const sorted = [...values].sort((a, b) => a - b);
+    const mean = sorted.reduce((a, b) => a + b, 0) / sorted.length;
+    const variance = sorted.reduce((acc, v) => acc + (v - mean) ** 2, 0) / sorted.length;
+    return {
+        count: sorted.length,
+        minMs: round(sorted[0]),
+        maxMs: round(sorted[sorted.length - 1]),
+        meanMs: round(mean),
+        stddevMs: round(Math.sqrt(variance)),
+        p50Ms: roundOrNull(percentile(sorted, 50)),
+        p90Ms: roundOrNull(percentile(sorted, 90)),
+        p95Ms: roundOrNull(percentile(sorted, 95)),
+        p99Ms: roundOrNull(percentile(sorted, 99)),
+    };
+}
+/** Format a possibly-absent measurement for text output. */
+function fmt(v, unit = 'ms') {
+    return v === null || v === undefined ? 'n/a' : `${v}${unit}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@houwert/conductor",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "description": "CLI tool for mobile app interactions — optimized for AI agents",
   "license": "MIT",
   "repository": {

package/skills/conductor-create-flow/SKILL.md

@@ -14,7 +14,7 @@ existing Maestro flows run unchanged. Use flows for repeatable journeys; use
 
 | Command | Purpose |
 |---|---|
-| `conductor run-flow <file> [--env K=V] [--benchmark]` | Run a Maestro YAML flow file |
+| `conductor run-flow <file> [--env K=V] [--benchmark] [--repeat <n>]` | Run a Maestro YAML flow file. `--benchmark --repeat <n>` reports per-command p50/p90/stddev across runs |
 | `conductor run-flow-inline '<yaml>' [--benchmark]` | Run inline YAML from the command line |
 | `conductor run-sequence [--file path.json]` | Run a JSON sequence of conductor commands serially; reads stdin if no `--file` |
 | `conductor run-parallel --flows-dir <path>` | Shard a directory of flows across all booted devices |

package/skills/conductor-device-interact/SKILL.md

@@ -41,7 +41,7 @@ conductor assert-visible "Dashboard"
 | `conductor copy-text-from <element>` | Print an element's text (and copy to the iOS clipboard) |
 | `conductor input-text <text>` | Type into the focused field |
 | `conductor erase-text [n]` | Erase n characters (default 50) |
-| `conductor press-key <key>` | Press a key (Enter, Backspace, Home, …) or a remote button (`Remote Dpad Up/Down/Left/Right/Center`, `Remote Menu`) for tvOS / Android TV / vega. `--long-press` / `--duration <seconds>` holds it |
+| `conductor press-key <key>` | Press a key (Enter, Backspace, Home, …) or a remote button (`Remote Dpad Up/Down/Left/Right/Center`, `Remote Menu`) for tvOS / Android TV / vega. `--long-press` / `--duration <seconds>` holds it; `--measure` times the response (see `conductor-profiler`) |
 | `conductor hide-keyboard` | Dismiss the on-screen keyboard |
 | `conductor back` | Press back |
 | `conductor scroll [--direction down\|up\|left\|right]` | Scroll |

package/skills/conductor-profiler/SKILL.md

@@ -1,21 +1,116 @@
 ---
 name: conductor-profiler
-description: Profile a running app's CPU, memory, and React render performance with the conductor CLI, and read crash reports. Use when investigating slowness, jank, memory growth or leaks, excessive React re-renders, or when an app has crashed and you need the crash report.
+description: Profile a running app's frame timing, input latency, JS CPU, native CPU, memory and React renders with the conductor CLI, and read crash reports. Use when investigating jank or sluggishness, slow navigation, input lag on TV remotes, memory growth or leaks, GC pauses, excessive React re-renders, or when an app has crashed and you need the crash report.
 ---
 
 # Conductor — profiling & crashes
 
 Measure a running app's performance and inspect crashes.
 
-## Profiling
+## Pick the right instrument
+
+| Symptom the user reports | Measure with |
+|---|---|
+| "Scrolling/navigation is janky" | `profile frames` (Android) — objective jank rate and per-phase attribution |
+| "I press a key and it takes a moment" | `press-key <key> --measure --repeat 20` |
+| "It's slow, where does the time go?" (JS) | `profile js record --duration 10` |
+| "It's slow, where does the time go?" (native) | `profile cpu --duration 10 --report` |
+| "Which component re-renders on every input?" | `profile react start` → interact → `profile react stop` |
+| "Memory grows / it stutters periodically" | `profile memory --track 30` |
+
+`profile frames`, `profile cpu` and `profile memory` work on **release builds**
+and on real hardware. `profile js` and `profile react` attach over Metro, so
+they need a dev/profiling build.
+
+## Frame timing & jank (Android, incl. Fire TV / Android TV)
+
+| Command | Purpose |
+|---|---|
+| `conductor profile frames reset [<appId>]` | Zero the gfxinfo counters |
+| `conductor profile frames report [<appId>]` | Jank rate, p50–p99 frame times, per-phase breakdown |
+| `conductor profile frames report --track <s> [--interval <ms>]` | Reset, sample for N seconds, then report |
+| `conductor profile frames report --save-baseline <name>` / `--diff <name>` / `--baselines` | Save and compare runs |
+
+Reads `dumpsys gfxinfo <pkg> framestats`, so it needs no instrumentation.
+
+**On TV, be deliberate about who is driving.** `press-key` injects with
+`adb shell input keyevent`, which spawns a JVM on the device (~713ms) beside
+the frames you are measuring. Mobile's answer — fling and measure the momentum
+scroll — does not exist on TV, where focus moves one step per press and stops.
+So a navigation capture is always partly a measurement of the harness. Idle
+screens, load settles, cold start and self-running animations are clean; for
+navigation, prefer asking a human to drive the physical remote during the
+window (the command announces the window on stderr for exactly this), and treat
+a divergence between human-driven and automated numbers as the harness.
+
+Not available on `vega` — but a **physical Fire TV Stick runs Fire OS
+(Android)** over adb and works fine.
+
+Attribute jank by comparing each phase's p95 against its p50: `vsyncDelay` means
+the UI thread was blocked elsewhere, `traversal` means measure/layout,
+`draw` means display-list recording, `issueDraw` means render-thread/GPU.
+
+## Input latency
+
+| Command | Purpose |
+|---|---|
+| `conductor press-key <key> --measure` | Time the app's response to the press |
+| `conductor press-key <key> --measure --repeat <n>` | Take n samples and report a distribution |
+| `--sequence <k1,k2>` | Cycle keys so repeats oscillate instead of drifting across the UI |
+| `--timeout <ms>` / `--poll-interval <ms>` / `--settle <ms>` | Give-up time; poll delay; render time to allow |
+
+Read `outcome` per sample before the aggregates. `moved` is a measurement;
+`unchanged` means focus queries kept working and the app simply declined to move
+(a rail edge, or a key this screen ignores) and is **not** a hang;
+`query-failed` is the one that suggests something is wedged.
+
+`--repeat` is not repeated measurement of one event — pressing Right twenty
+times walks twenty different transitions. Read `byTransition` before the
+aggregate, or use `--sequence` to oscillate between two positions.
+
+On Android `pressToFrame` is derived from device-side clocks and is the figure
+to trust. `focusChange` is bounded by how long one hierarchy dump takes, and a
+`round-trip-bound` note fires when that floor dominates. gfxinfo's own
+`inputLatency` appears only when the device populates `NewestInputEvent` — it
+does on a Fire TV Stick, it never does on an NVIDIA SHIELD — so treat it as a
+bonus, never as something whose absence means no input occurred.
+
+## JS CPU (Hermes sampling profiler)
+
+| Command | Purpose |
+|---|---|
+| `conductor profile js record --duration <s> [--top n] [--out <path>]` | Sample, then rank functions by self time with `file:line` |
+| `conductor profile js start` / `conductor profile js stop [--top n]` | Same, bracketing a flow you drive in between |
+
+Writes a raw `.cpuprofile` you can load in Chrome DevTools (Performance → Load
+profile) or convert with `npx hermes-profile-transformer`.
+
+## Native CPU
 
 | Command | Purpose |
 |---|---|
-| `conductor profile cpu --duration <s> [--out <path>]` | Record a CPU trace (iOS: xctrace, Android: simpleperf) |
-| `conductor profile memory --track <s> [--interval ms] [<appId>]` | Sample memory for N seconds, report deltas |
-| `conductor profile react start` / `profile react stop [--top N]` | Install a React commit-profiler hook, then summarize captured commits |
+| `conductor profile cpu --duration <s> [--out <path>]` | Record a trace (iOS: xctrace, Android: simpleperf) |
+| `conductor profile cpu --duration <s> --report [--top n]` | Android: also return a ranked symbol table |
 
-## Memory
+Without `--report` on Android you get a binary `perf.data` you cannot read —
+pass `--report` when you need the answer rather than the artefact.
+
+## React renders
+
+| Command | Purpose |
+|---|---|
+| `conductor profile react start [--max-commits n] [--max-components n]` | Install the commit-profiler hook |
+| `conductor profile react stop [--top n] [--timeline] [--json]` | Stop and rank components by self time |
+
+Sort key is `selfMs`, which is additive across components; `totalMs` is
+subtree-inclusive and double-counts parents. `--json` includes the per-commit
+timeline (timestamps + durations) so you can line a jank spike up with an input;
+`--timeline` adds per-commit component detail. If either buffer overflows the
+output says `truncated: true` with the dropped counts — raise the limits rather
+than trusting the tail. On a release build it fails with a clear message instead
+of reporting zeroes.
+
+## Memory & GC
 
 | Command | Purpose |
 |---|---|
@@ -24,10 +119,17 @@ Measure a running app's performance and inspect crashes.
 | `conductor memory --leaks` | Run leak detection (iOS only; slow, can pause the app) |
 | `conductor memory --save <name>` / `--diff <name>` / `--diff <name> --vs <other>` | Snapshot and diff memory reports |
 | `conductor memory --filter <regex>` / `--growth-only` / `--top <n>` | Narrow object/class tables (great for leak-hunting) |
+| `conductor profile memory --track <s> [--interval <ms>]` | Sample over a window; on Android also reports heap growth and ART GC pause counts/durations |
 
 Typical leak hunt: `memory --save before`, exercise the screen, then
 `memory --diff before --growth-only`.
 
+## Repeatable benchmarking
+
+`conductor run-flow <file> --benchmark --repeat <n> --json` runs the flow n
+times and reports per-command p50/p90/stddev. Use it on TV, where single-run
+variance is large enough to swamp the effect you're looking for.
+
 ## Crashes
 
 | Command | Purpose |
@@ -39,4 +141,10 @@ Typical leak hunt: `memory --save before`, exercise the screen, then
 ## Tips
 
 - Add `--json` to parse reports programmatically.
-- These commands can be slow or pause the app — scope them with `--duration` / `--track` and avoid leaving `crashes tail` running.
+- `--port` is auto-detected from the device for Metro-backed commands; pass it
+  explicitly only if that fails.
+- These commands can be slow or pause the app — scope them with `--duration` /
+  `--track` and avoid leaving `crashes tail` running.
+- An Android TV emulator is far faster than a Fire TV Stick. Trust frame timing
+  only from real hardware; emulators are fine for counts (React commits, GC
+  collections, JS self-time ranking).