@houwert/conductor 0.29.0 → 0.29.2

package/dist/commands/profile-frames.js

@@ -73,18 +73,25 @@ function num(out, re) {
 function parseGfxinfoSummary(out) {
     const header = out.match(/\*\* Graphics info for pid (\d+) \[([^\]]+)\]/);
     const janky = out.match(/Janky frames:\s*(\d+)\s*\(([\d.]+)%\)/);
+    const totalFrames = num(out, /Total frames rendered:\s*(\d+)/);
+    // With nothing drawn the platform still prints percentiles, filled from the
+    // top histogram bucket — "p99 4950ms" for a window in which no frame existed.
+    // A percentile over zero frames is not a slow frame, it is no frame, and it
+    // must not be representable as a value.
+    const drew = totalFrames !== undefined && totalFrames > 0;
+    const pctile = (re) => (drew ? num(out, re) : undefined);
     // The GPU block repeats these labels as "50th gpu percentile", so matching the
     // exact phrase keeps us on the UI-thread figures.
     return {
         pid: header ? Number(header[1]) : undefined,
         packageName: header ? header[2] : undefined,
-        totalFrames: num(out, /Total frames rendered:\s*(\d+)/),
+        totalFrames,
         jankyFrames: janky ? Number(janky[1]) : undefined,
-        jankyPercent: janky ? Number(janky[2]) : undefined,
-        platformP50Ms: num(out, /50th percentile:\s*(\d+)ms/),
-        platformP90Ms: num(out, /90th percentile:\s*(\d+)ms/),
-        platformP95Ms: num(out, /95th percentile:\s*(\d+)ms/),
-        platformP99Ms: num(out, /99th percentile:\s*(\d+)ms/),
+        jankyPercent: drew && janky ? Number(janky[2]) : undefined,
+        platformP50Ms: pctile(/50th percentile:\s*(\d+)ms/),
+        platformP90Ms: pctile(/90th percentile:\s*(\d+)ms/),
+        platformP95Ms: pctile(/95th percentile:\s*(\d+)ms/),
+        platformP99Ms: pctile(/99th percentile:\s*(\d+)ms/),
         missedVsync: num(out, /Number Missed Vsync:\s*(\d+)/),
         highInputLatency: num(out, /Number High input latency:\s*(\d+)/),
         slowUiThread: num(out, /Number Slow UI thread:\s*(\d+)/),
@@ -589,6 +596,14 @@ async function profileFramesReport(opts, sessionName, frameOpts) {
                 `(hardware acceleration must be on; WebView-only or SurfaceView-only apps report nothing)`, opts);
             return 1;
         }
+        if (summary.totalFrames === 0) {
+            notes.push({
+                code: 'no-frames',
+                message: `${appId} drew no frames in this window, so there is nothing to measure — not ` +
+                    `smooth, not janky. The app may be idle, backgrounded, or rendering through a ` +
+                    `SurfaceView/WebView that HWUI does not count. Drive it, or check it is foreground.`,
+            });
+        }
         if (!clockAnchor) {
             notes.push({
                 code: 'no-clock-anchor',

package/dist/commands/profile-js.js

@@ -27,6 +27,15 @@ const output_js_1 = require("../output.js");
 const bootstrap_js_1 = require("../drivers/bootstrap.js");
 const metro_cdp_js_1 = require("../drivers/metro-cdp.js");
 const stats_js_1 = require("../stats.js");
+/** Hermes marks its own frames with brackets; anything else is app code. */
+function classifyFrame(name) {
+    if (/^\[GC\b/i.test(name) || /garbage collector/i.test(name))
+        return 'gc';
+    if (name === '[root]' || name === '(root)' || name === '(program)' || name === '(idle)') {
+        return 'idle';
+    }
+    return name.startsWith('[') || name.startsWith('(') ? 'idle' : 'named';
+}
 function shortFile(url) {
     const u = url ?? '';
     return u.includes('/') ? u.slice(u.lastIndexOf('/') + 1) : u;
@@ -82,6 +91,33 @@ function analyzeCpuProfile(profile, top) {
         }
     }
     const totalUs = [...self.values()].reduce((a, b) => a + b, 0);
+    // Split before ranking: a top-30 list assembled from 5% of the samples is
+    // noise dressed as a finding, and the reader cannot tell without this.
+    const buckets = { gc: 0, idle: 0, named: 0 };
+    for (const [key, us] of self.entries()) {
+        buckets[classifyFrame(label.get(key).functionName || '(anonymous)')] += us;
+    }
+    const share = (v) => (totalUs > 0 ? (0, stats_js_1.round)((v / totalUs) * 100, 1) : 0);
+    const attribution = {
+        namedJsPercent: share(buckets.named),
+        gcPercent: share(buckets.gc),
+        idlePercent: share(buckets.idle),
+    };
+    const notes = [];
+    if (totalUs > 0 && attribution.namedJsPercent < 25) {
+        notes.push({
+            code: 'low-attribution',
+            message: `Only ${attribution.namedJsPercent}% of sampled time landed in a named JS function ` +
+                `(${attribution.idlePercent}% with an empty JS stack, ${attribution.gcPercent}% in GC). ` +
+                `The ranking below is built on what little is left and should not be trusted. ` +
+                `A large empty-stack share means the JS thread was idle when sampled — which is itself ` +
+                `a result: the bottleneck is not JS. A large GC share is a memory finding; follow it ` +
+                `with \`profile memory --track\` rather than a function ranking.`,
+            namedJsPercent: attribution.namedJsPercent,
+            gcPercent: attribution.gcPercent,
+            idlePercent: attribution.idlePercent,
+        });
+    }
     const ranked = [...self.entries()]
         .map(([key, selfUs]) => {
         const frame = label.get(key);
@@ -101,8 +137,10 @@ function analyzeCpuProfile(profile, top) {
         durationMs: (0, stats_js_1.round)((profile.endTime - profile.startTime) / 1000),
         sampleCount: samples.length,
         medianSampleIntervalMs: sortedDeltas.length > 0 ? (0, stats_js_1.round)(sortedDeltas[Math.floor(sortedDeltas.length / 2)] / 1000) : 0,
+        attribution,
         top: ranked.slice(0, top),
         omitted: Math.max(0, ranked.length - top),
+        notes,
     };
 }
 async function connect(sessionName, cdpOpts) {
@@ -114,7 +152,10 @@ async function connect(sessionName, cdpOpts) {
     return client;
 }
 async function startSampling(client) {
-    await client.send('Profiler.enable');
+    // React Native's Fusebox CDP backend answers `Profiler.enable` with
+    // -32601 Unsupported method, but implements `Profiler.start` perfectly well.
+    // Enabling is a courtesy to backends that require it, never a precondition.
+    await client.send('Profiler.enable').catch(() => undefined);
     await client.send('Profiler.start');
 }
 async function stopSampling(client) {
@@ -134,13 +175,18 @@ async function writeProfile(out, profile) {
 function printSummary(summary, out) {
     console.log(`profile js — ${summary.durationMs}ms, ${summary.sampleCount} samples ` +
         `(~${summary.medianSampleIntervalMs}ms apart)`);
-    console.log(`  ${'self'.padStart(9)} ${'total'.padStart(9)}  ${'%'.padStart(5)}  function`);
+    const a = summary.attribution;
+    console.log(`  sampled time:  ${a.namedJsPercent}% named JS  ${a.gcPercent}% GC  ` +
+        `${a.idlePercent}% empty JS stack`);
+    console.log(`\n  ${'self'.padStart(9)} ${'total'.padStart(9)}  ${'%'.padStart(5)}  function`);
     for (const f of summary.top) {
         console.log(`  ${`${f.selfMs}ms`.padStart(9)} ${`${f.totalMs}ms`.padStart(9)}  ` +
             `${f.selfPercent.toFixed(1).padStart(5)}  ${f.name}  ${f.location}`);
     }
     if (summary.omitted > 0)
         console.log(`  ... ${summary.omitted} more (raise --top)`);
+    for (const note of summary.notes)
+        console.log(`\n  note [${note.code}]: ${note.message}`);
     console.log(`\n  raw profile → ${out}`);
     console.log('  open it in Chrome DevTools (Performance → Load profile), or convert with ' +
         '`npx hermes-profile-transformer`.');

package/dist/commands/profile.js

@@ -7,6 +7,7 @@ exports.REACT_PROFILER_STOP = exports.REACT_PROFILER_READ = exports.REACT_PROFIL
 exports.parseSimpleperfReport = parseSimpleperfReport;
 exports.profileCpu = profileCpu;
 exports.heapGrowth = heapGrowth;
+exports.inferCollections = inferCollections;
 exports.profileMemory = profileMemory;
 exports.profileReactStart = profileReactStart;
 exports.profileReactStop = profileReactStop;
@@ -228,6 +229,37 @@ function heapGrowth(samples) {
 function mb(bytes) {
     return `${(bytes / 1024 / 1024).toFixed(1)}MB`;
 }
+/**
+ * Infer collections from the heap series rather than from logcat.
+ *
+ * A heap that shrinks between two samples was collected between them — there is
+ * no other mechanism. This matters because ART's GC logging is not reliably on:
+ * measured on a Fire TV Stick (Fire OS, API 30), a window in which the Java heap
+ * fell 11.8MB produced no `art:I` lines at all. Absence of logged collections is
+ * therefore not absence of collection, and the deltas are the sounder signal.
+ */
+function inferCollections(samples, series = 'javaHeapBytes') {
+    const values = [];
+    for (const s of samples) {
+        const app = s.data?.app;
+        const v = app?.[series];
+        if (typeof v === 'number')
+            values.push(v);
+    }
+    if (values.length < 2)
+        return undefined;
+    let collections = 0;
+    let reclaimedBytes = 0;
+    for (let i = 1; i < values.length; i++) {
+        const drop = values[i - 1] - values[i];
+        // Ignore sampling jitter; only count drops worth a collection.
+        if (drop > 256 * 1024) {
+            collections++;
+            reclaimedBytes += drop;
+        }
+    }
+    return { collections, reclaimedBytes, series };
+}
 async function profileMemory(opts, sessionName, profileOpts) {
     const samples = [];
     const platform = await (0, bootstrap_js_1.detectPlatform)(sessionName).catch(() => undefined);
@@ -257,6 +289,7 @@ async function profileMemory(opts, sessionName, profileOpts) {
         }
     });
     const growth = heapGrowth(parsed);
+    const inferredGc = isAndroid ? inferCollections(parsed) : undefined;
     let gc;
     if (isAndroid) {
         const events = await (0, profile_gc_js_1.collectGcSince)(sessionName, gcSince);
@@ -264,7 +297,7 @@ async function profileMemory(opts, sessionName, profileOpts) {
             gc = (0, profile_gc_js_1.summariseGc)(events);
     }
     if (opts.json) {
-        (0, output_js_1.printData)({ samples: parsed, durationMs: Date.now() - start, growth, gc }, opts);
+        (0, output_js_1.printData)({ samples: parsed, durationMs: Date.now() - start, growth, gc, inferredGc }, opts);
     }
     else {
         console.log(`profile memory — ${samples.length} samples over ${profileOpts.trackSec}s`);
@@ -293,8 +326,20 @@ async function profileMemory(opts, sessionName, profileOpts) {
             }
         }
         else if (isAndroid) {
-            console.log('\n  GC: no ART collections logged in the window. ART only logs collections it ' +
-                'considers noteworthy, so a quiet window here is a real signal.');
+            console.log('\n  GC: no ART collections logged in the window.');
+            if (inferredGc && inferredGc.collections > 0) {
+                console.log(`    But ${inferredGc.series} fell ${inferredGc.collections} time(s), reclaiming ` +
+                    `${mb(inferredGc.reclaimedBytes)} — so collections did run and were not logged. ` +
+                    `ART's logging is off or filtered on this build; trust the heap deltas, not logcat.`);
+            }
+            else {
+                console.log('    Absence of logged collections is not absence of collection — ART logging is ' +
+                    'off or filtered on some builds. The heap deltas above are the sounder signal.');
+            }
+        }
+        if (inferredGc && inferredGc.collections > 0 && gc) {
+            console.log(`    (heap deltas independently imply ${inferredGc.collections} collection(s), ` +
+                `${mb(inferredGc.reclaimedBytes)} reclaimed)`);
         }
     }
     return 0;

package/dist/drivers/log-sources/metro.js

@@ -131,7 +131,9 @@ async function discoverTarget(port, host, targetIndex) {
     const data = await fetchTargets(port, host);
     const withWs = data.filter((t) => t.webSocketDebuggerUrl);
     if (withWs.length === 0) {
-        throw new Error('Metro returned no debugger targets. Is the app running on a device/simulator?');
+        throw new Error('Metro is reachable but has no debugger targets. Most often the app is a release ' +
+            'build — release Hermes ships without the inspector and never connects to Metro. ' +
+            'Otherwise, check the app is running and pointed at this Metro instance.');
     }
     if (targetIndex !== undefined) {
         if (targetIndex < 0 || targetIndex >= withWs.length) {

package/dist/drivers/metro-cdp.js

@@ -33,7 +33,17 @@ function selectDebuggerUrl(targets, opts, displayName) {
     const host = opts.host ?? 'localhost';
     const withWs = targets.filter((t) => t.webSocketDebuggerUrl);
     if (withWs.length === 0) {
-        throw new Error(`Metro on ${host}:${port} returned no debugger targets. Is an app running on a device/simulator?`);
+        // Metro is reachable but nothing registered. The usual cause is not a
+        // missing app — it is a release build: release Hermes ships without the
+        // inspector and never connects to Metro at all, so asking "is the app
+        // running?" sends people to check something that is already true.
+        throw new Error(`Metro on ${host}:${port} is reachable but has no debugger targets.\n` +
+            `Most often the app is a release build — release Hermes ships without the ` +
+            `inspector and never connects to Metro, so no amount of relaunching will help. ` +
+            `Use a debug or profiling build for anything that attaches over Metro ` +
+            `(\`profile js\`, \`profile react\`, \`debug\`, \`network\`).\n` +
+            `Otherwise: check the app is running and foreground, and that it is pointed at ` +
+            `this Metro instance rather than another one.`);
     }
     if (opts.targetIndex !== undefined) {
         if (opts.targetIndex < 0 || opts.targetIndex >= withWs.length) {

package/package.json

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