@houwert/conductor 0.29.0 → 0.29.1

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/package.json

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