@farmslot/adapter-rn 0.30.0 → 0.31.1

package/dist/performance-capture.js

@@ -0,0 +1,751 @@
+// app.performance_capture on adapter-rn runs. `phase: "start"` opens a named
+// window on the device's native frames, `phase: "end"` closes it and writes
+// its summary (frames, the lowest sustained FPS, the latency of every press
+// inside it, and the window's budget verdict), and `phase: "report"` writes
+// one report over every window of the run and fails the node when a window
+// broke its budget. Targets are reported, never failed on.
+import { execFile } from 'node:child_process';
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { RecipeExecutionError, } from '@farmslot/recipe-runner';
+import { lowestWindowedFps, percentile, round, summarizeFrames, } from '@farmslot/recipe-runner/runtime/cdp-trace';
+import { createAndroidGfxinfoPerformanceBackend, } from './android-gfxinfo-performance.js';
+import { resolveMobileToolPath } from './tool-paths.js';
+export const PERFORMANCE_CAPTURE_ACTION = 'app.performance_capture';
+const execFileAsync = promisify(execFile);
+// Actions whose node is one press: their latency runs from the frame that
+// handled the input to the frame that answered it.
+const PRESS_ACTIONS = new Set(['ui.press', 'ui.key_press']);
+const DEFAULT_MAX_DURATION_MS = 5 * 60 * 1000;
+const MAX_DURATION_MS = 60 * 60 * 1000;
+const DEFAULT_SUSTAINED_WINDOW_MS = 500;
+// How long after the touch a first frame can answer a press that mounts
+// nothing: the window the atrace tab-press measurements searched (600 ms).
+const DEFAULT_RESPONSE_WINDOW_MS = 600;
+// A mount frame stands out from the touch and animation frames around it
+// (about 1 ms of UI-thread work on a Pixel 6; tab mounts measured 9-80 ms):
+// at least MOUNT_MIN_MS, and either a whole frame budget of UI-thread work or
+// MOUNT_OVER_MEDIAN times the median of the other frames after the touch.
+const MOUNT_MIN_MS = 4;
+const MOUNT_OVER_MEDIAN = 3;
+// A mount up to this many response windows after the touch answers the press,
+// even after a pause (a JavaScript stall delays it): 900 ms by default. Past
+// the window only a whole frame budget of UI-thread work counts as the mount;
+// a live update on an already-mounted screen is lighter (main's release
+// captures had a 6.9 ms update 1076 ms after a tab press).
+const MOUNT_LOOKAHEAD = 1.5;
+// Frames closer than this are one stretch of rendering for sustained FPS, so a
+// slow cadence (4 vsyncs at 90 Hz is 22.5 fps) counts against the floor.
+const MAX_ACTIVE_GAP_MS = 100;
+const DEFAULT_FRAME_BUDGET_MS = 1000 / 60;
+// The app logs its shown line from the second animation frame after focus,
+// once JavaScript is free, which can be before the UI thread finishes the
+// frame that mounts the screen. A shown press ends at the end of the last
+// frame that started by this many frame budgets after the line.
+const SHOWN_MARKER_FRAMES = 2;
+// The metrics failures name, so a reader knows what was measured.
+const PRESS_METRIC = 'gfxinfo input->mount frame';
+const SHOWN_PRESS_METRIC = 'gfxinfo input->shown marker';
+const FPS_METRIC = 'gfxinfo, lowest 500 ms';
+export function createPerformanceCaptureSession({ env, logger = console, dryRun = false, createBackend = createDeviceBackend, now = Date.now, }) {
+    const spans = [];
+    const windows = new Map();
+    const summaries = [];
+    let backend;
+    const resolveBackend = () => (backend ??= createBackend(env));
+    function finish(window) {
+        window.result ??= resolveBackend().end(window.id);
+        return window.result;
+    }
+    async function execute(node, context) {
+        const phase = String(node.phase ?? '').toLowerCase();
+        if (dryRun) {
+            return {
+                output: { action: PERFORMANCE_CAPTURE_ACTION, phase, dryRun: true, nodeId: context.nodeId },
+            };
+        }
+        if (phase === 'report')
+            return report(node, context);
+        const id = String(node.id ?? '').trim();
+        if (!['start', 'end'].includes(phase) || !id) {
+            throw new RecipeExecutionError('harness', `${PERFORMANCE_CAPTURE_ACTION} requires phase=start|end with a non-empty id, or phase=report.`);
+        }
+        if (phase === 'start') {
+            if (windows.size > 0) {
+                throw new RecipeExecutionError('harness', `${PERFORMANCE_CAPTURE_ACTION} window ${[...windows.keys()][0]} is still open; end it before starting ${id}.`);
+            }
+            await resolveBackend().start(id);
+            windows.set(id, {
+                id,
+                maxDurationMs: boundedDuration(node.max_duration_ms),
+                startedAtEpochMs: now(),
+            });
+            return { output: { action: PERFORMANCE_CAPTURE_ACTION, id, phase, status: 'started' } };
+        }
+        const window = windows.get(id);
+        if (!window) {
+            throw new RecipeExecutionError('harness', `Performance capture is not active: ${id}`);
+        }
+        windows.delete(id);
+        const result = await finish(window);
+        const summary = summarizeWindow({
+            id,
+            startedAtEpochMs: window.startedAtEpochMs,
+            endedAtEpochMs: now(),
+            maxDurationMs: window.maxDurationMs,
+            result,
+            spans,
+            budget: parseBudget(node.budget),
+            shownMarkers: parseShownMarkerMap(node.shown_markers),
+            baseline: parseBaseline(node.baseline),
+            targets: parseTargets(node.targets),
+            sustainedWindowMs: positiveNumber(node.sustained_window_ms) ?? DEFAULT_SUSTAINED_WINDOW_MS,
+            responseWindowMs: positiveNumber(node.response_window_ms) ?? DEFAULT_RESPONSE_WINDOW_MS,
+        });
+        summaries.push(summary);
+        const artifactPath = `performance/${safeId(id)}-summary.json`;
+        // The frames (and shown lines) the summary was read from, so a reviewer can
+        // check which frame answered a press.
+        const framesPath = `performance/${safeId(id)}-frames.json`;
+        await writeArtifact(context, artifactPath, `${JSON.stringify(summary, null, 2)}\n`);
+        await writeArtifact(context, framesPath, `${JSON.stringify({
+            schemaVersion: 1,
+            id,
+            spans: windowSpans(spans, summary),
+            frames: result.nativeUi.samples,
+            ...(result.shownMarkers ? { shownMarkers: result.shownMarkers } : {}),
+        })}\n`);
+        return {
+            output: { action: PERFORMANCE_CAPTURE_ACTION, phase, artifactPath, framesPath, ...summary },
+            artifacts: [
+                { path: artifactPath, type: 'metric', nodeId: context.nodeId, label: `Performance ${id}` },
+                { path: framesPath, type: 'json', nodeId: context.nodeId, label: `Frames ${id}` },
+            ],
+        };
+    }
+    async function report(node, context) {
+        const title = typeof node.title === 'string' && node.title.trim() ? node.title.trim() : 'Performance';
+        if (summaries.length === 0) {
+            throw new RecipeExecutionError('harness', `${PERFORMANCE_CAPTURE_ACTION} phase=report found no ended capture window.`);
+        }
+        const failed = summaries.filter((summary) => summary.budget?.verdict === 'fail');
+        const inconclusive = summaries.filter((summary) => summary.budget?.verdict === 'inconclusive');
+        const environment = {
+            device: await describeDevice(),
+            checkout: await describeCheckout(context.projectRoot, logger),
+        };
+        const document = {
+            schemaVersion: 1,
+            verdict: failed.length > 0 ? 'fail' : inconclusive.length > 0 ? 'inconclusive' : 'pass',
+            environment,
+            windows: summaries,
+        };
+        const jsonPath = 'performance/report.json';
+        const markdownPath = 'performance/report.md';
+        await writeArtifact(context, jsonPath, `${JSON.stringify(document, null, 2)}\n`);
+        await writeArtifact(context, markdownPath, renderPerformanceReport(title, summaries, environment));
+        const artifacts = [
+            { path: jsonPath, type: 'metric', nodeId: context.nodeId, label: `${title} report` },
+            { path: markdownPath, type: 'report', nodeId: context.nodeId, label: `${title} report` },
+        ];
+        if (failed.length > 0 || inconclusive.length > 0) {
+            for (const artifact of artifacts)
+                context.registerArtifact(artifact);
+            const reasons = [
+                ...failed.map((summary) => `${summary.id} (${summary.budget?.failures.join('; ')})`),
+                ...inconclusive.map((summary) => `${summary.id} inconclusive (${summary.budget?.inconclusive.join('; ')})`),
+            ];
+            throw new RecipeExecutionError(failed.length > 0 ? 'subject' : 'environment', `Performance budget ${failed.length > 0 ? 'failed' : 'inconclusive'}: ${reasons.join(', ')}`, {
+                code: failed.length > 0 ? 'PERFORMANCE_BUDGET_FAILED' : 'PERFORMANCE_INCONCLUSIVE',
+                details: document,
+            });
+        }
+        return {
+            output: { action: PERFORMANCE_CAPTURE_ACTION, phase: 'report', ...document },
+            artifacts,
+        };
+    }
+    async function describeDevice() {
+        try {
+            return await backend?.describe?.();
+        }
+        catch (error) {
+            // The report still renders without the device line; the reason is logged.
+            logger.warn(`Performance report could not describe the device: ${errorMessage(error)}`);
+            return undefined;
+        }
+    }
+    return {
+        handler: {
+            action: PERFORMANCE_CAPTURE_ACTION,
+            // Package code, not a recipe's: trusted like the runner's built-in actions.
+            source: { kind: 'bundled', trust: 'trusted', name: '@farmslot/adapter-rn' },
+            execute,
+        },
+        recordNodeEvent(event) {
+            if (event.status === 'running') {
+                spans.push({
+                    nodeId: event.nodeId,
+                    action: event.action,
+                    ...(event.target ? { target: event.target } : {}),
+                    startedAtEpochMs: now(),
+                });
+                return;
+            }
+            for (let index = spans.length - 1; index >= 0; index -= 1) {
+                const span = spans[index];
+                if (span?.nodeId !== event.nodeId || span.endedAtEpochMs !== undefined)
+                    continue;
+                span.endedAtEpochMs = now();
+                return;
+            }
+        },
+        async close() {
+            const open = [...windows.values()];
+            windows.clear();
+            for (const window of open) {
+                // A window still open here belongs to a run that failed before its
+                // phase=end. Ending it stops the polling; its error must not replace
+                // the run's own, so it is logged.
+                await finish(window).catch((error) => {
+                    logger.warn(`Performance window ${window.id} did not end: ${errorMessage(error)}`);
+                });
+            }
+            await backend?.close();
+        },
+    };
+}
+function createDeviceBackend(env) {
+    const platform = env.PLATFORM ?? '';
+    if (!platform.startsWith('android')) {
+        throw new RecipeExecutionError('environment', `${PERFORMANCE_CAPTURE_ACTION} reads Android gfxinfo frames; it needs PLATFORM=android (got ${platform || 'none'}).`);
+    }
+    const serial = env.ADB_SERIAL ?? env.ANDROID_SERIAL ?? env.ANDROID_DEVICE ?? '';
+    const packageId = env.FARMSLOT_RECIPE_APP_ID ?? '';
+    if (!serial || !packageId) {
+        throw new RecipeExecutionError('environment', `${PERFORMANCE_CAPTURE_ACTION} needs ADB_SERIAL and FARMSLOT_RECIPE_APP_ID for the target app.`);
+    }
+    return createAndroidGfxinfoPerformanceBackend({
+        serial,
+        packageId,
+        adbPath: resolveMobileToolPath('adb', { required: true }) ?? 'adb',
+        shownMarkers: true,
+    });
+}
+export function summarizeWindow({ id, startedAtEpochMs, endedAtEpochMs, maxDurationMs, result, spans, budget, shownMarkers = {}, baseline, targets, sustainedWindowMs, responseWindowMs, }) {
+    const samples = result.nativeUi.samples;
+    const coverageGapReasons = [...result.nativeUi.coverageGapReasons];
+    const exceeded = endedAtEpochMs - startedAtEpochMs >= maxDurationMs;
+    if (exceeded)
+        coverageGapReasons.push('Performance capture exceeded max_duration_ms.');
+    const pressSpans = spans.filter((span) => PRESS_ACTIONS.has(span.action) &&
+        span.startedAtEpochMs >= startedAtEpochMs &&
+        (span.endedAtEpochMs ?? endedAtEpochMs) <= endedAtEpochMs);
+    const markers = (result.shownMarkers?.markers ?? []).filter((marker) => marker.atEpochMs >= startedAtEpochMs && marker.atEpochMs <= endedAtEpochMs);
+    // An app that logs no shown line (an older build) keeps the frame rule, flagged.
+    const markerTimed = Object.keys(shownMarkers).length > 0 && markers.length > 0;
+    const frames = summarizeFrames(samples);
+    const presses = pressSpans.map((span, index) => {
+        const screen = markerTimed && span.target ? shownMarkers[span.target] : undefined;
+        return result.inputEvents === 'missing'
+            ? {
+                nodeId: span.nodeId,
+                action: span.action,
+                ...(span.target ? { target: span.target } : {}),
+                unmeasuredReason: "this device's gfxinfo framestats has no InputEventId column (Android 12 or later is needed to time presses)",
+            }
+            : screen
+                ? measureShownPress(samples, span, screen, markers, pressSpans[index + 1]?.startedAtEpochMs ?? endedAtEpochMs, 
+                // A window with no refresh budget is inconclusive whatever this reads.
+                frames.frameBudgetMs ?? DEFAULT_FRAME_BUDGET_MS)
+                : measurePress(samples, span, responseWindowMs, endedAtEpochMs);
+    });
+    const press = pressStats(presses);
+    const pressByTarget = {};
+    for (const target of new Set(presses.map((entry) => entry.target ?? entry.nodeId))) {
+        pressByTarget[target] = pressStats(presses.filter((entry) => (entry.target ?? entry.nodeId) === target));
+    }
+    const sustainedFps = lowestWindowedFps(samples, {
+        windowMs: sustainedWindowMs,
+        maxGapMs: MAX_ACTIVE_GAP_MS,
+    });
+    const summary = {
+        schemaVersion: 1,
+        id,
+        status: exceeded ? 'partial' : result.nativeUi.status,
+        platform: 'android',
+        source: result.nativeUi.kind,
+        startedAtEpochMs,
+        endedAtEpochMs,
+        durationMs: endedAtEpochMs - startedAtEpochMs,
+        frames,
+        ...(sustainedFps === undefined ? {} : { sustainedFps }),
+        sustainedWindowMs,
+        presses,
+        press,
+        pressByTarget,
+        coverageGapReasons,
+        unavailableReasons: [...result.nativeUi.unavailableReasons],
+        notes: [],
+    };
+    if (Object.keys(shownMarkers).length > 0 && !markerTimed) {
+        summary.notes.push(`no [farmslot-perf] shown line in this window (${result.shownMarkers
+            ? (result.shownMarkers.unavailableReason ?? 'none logged during it')
+            : 'the capture did not read logcat'}); its presses were timed by the frame rule (${PRESS_METRIC})`);
+    }
+    if (baseline?.refresh_hz !== undefined &&
+        frames.refreshRateHz !== undefined &&
+        Math.abs(frames.refreshRateHz - baseline.refresh_hz) > baseline.refresh_hz * 0.05) {
+        summary.notes.push(`measured ${Math.round(frames.refreshRateHz)} Hz; the baseline was recorded at ${baseline.refresh_hz} Hz`);
+    }
+    if (baseline)
+        summary.baseline = baseline;
+    if (budget)
+        summary.budget = checkBudget(summary, budget, baseline);
+    if (targets)
+        summary.targets = checkTargets(summary, targets);
+    return summary;
+}
+/**
+ * The press's latency: from the first frame that handled input during the
+ * press node to the end of the frame that answered it. The answer is the
+ * first later frame that stands out (see MOUNT_MIN_MS) within
+ * `responseWindowMs`, or past it within `MOUNT_LOOKAHEAD` windows, after a
+ * pause too, a frame with a whole frame budget of UI-thread work: the frame
+ * that mounts and draws the new screen. Touch ripples run on the render
+ * thread. Only when nothing answers that way is the press timed to the first
+ * frame within `responseWindowMs` (`first-frame`). A press with no input
+ * frame, or no frame after it, is untimed.
+ */
+export function measurePress(samples, span, responseWindowMs, windowEndEpochMs) {
+    const base = {
+        nodeId: span.nodeId,
+        action: span.action,
+        ...(span.target ? { target: span.target } : {}),
+    };
+    const input = inputFrame(samples, span, windowEndEpochMs);
+    if (!input)
+        return { ...base, unmeasuredReason: 'no frame handled input during the press' };
+    const searchEnd = Math.min(windowEndEpochMs, input.startedAtEpochMs + responseWindowMs * MOUNT_LOOKAHEAD);
+    const windowEnd = input.startedAtEpochMs + responseWindowMs;
+    const candidates = samples
+        .filter((sample) => sample.input !== true &&
+        sample.startedAtEpochMs > input.startedAtEpochMs &&
+        sample.startedAtEpochMs <= searchEnd)
+        .sort((left, right) => left.startedAtEpochMs - right.startedAtEpochMs);
+    const work = (sample) => sample.uiThreadMs ?? sample.durationMs;
+    const standsOut = (sample) => {
+        const ms = work(sample);
+        const wholeFrame = ms >= (sample.frameBudgetMs ?? DEFAULT_FRAME_BUDGET_MS);
+        if (sample.startedAtEpochMs > windowEnd)
+            return wholeFrame;
+        if (ms < MOUNT_MIN_MS)
+            return false;
+        if (wholeFrame)
+            return true;
+        const others = candidates
+            .filter((other) => other !== sample)
+            .map(work)
+            .sort((left, right) => left - right);
+        return others.length === 0 || ms >= percentile(others, 0.5) * MOUNT_OVER_MEDIAN;
+    };
+    // Any stand-out frame in reach answers, so a press is never read as instant
+    // while a mount follows it.
+    const mount = candidates.find(standsOut);
+    const response = mount ?? candidates.find((sample) => sample.startedAtEpochMs <= windowEnd);
+    if (!response) {
+        return {
+            ...base,
+            unmeasuredReason: `no frame answered the input within ${responseWindowMs} ms`,
+        };
+    }
+    return {
+        ...base,
+        latencyMs: round(response.completedAtEpochMs - input.startedAtEpochMs),
+        answer: mount ? 'mount' : 'first-frame',
+    };
+}
+/**
+ * A press timed by the app's own word: from the first frame that handled input
+ * during the press node to the screen's next `[farmslot-perf] shown` line, or
+ * to the end of the last frame from the touch on that started by
+ * `SHOWN_MARKER_FRAMES` frame budgets after the line, if that is later. The
+ * app logs the line from the second animation frame after focus, once
+ * JavaScript is free, so the UI thread can still be finishing the mount frame
+ * then. A press can over-read by up to about two light frames, and could miss
+ * a mount frame that starts more than two budgets after the line; a live
+ * update that starts later doesn't count, and a stall that delays the mount
+ * delays the line too. No line before the next press leaves the press untimed.
+ */
+export function measureShownPress(samples, span, screen, markers, searchEndEpochMs, frameBudgetMs) {
+    const base = {
+        nodeId: span.nodeId,
+        action: span.action,
+        ...(span.target ? { target: span.target } : {}),
+        marker: screen,
+    };
+    const input = inputFrame(samples, span, searchEndEpochMs);
+    if (!input)
+        return { ...base, unmeasuredReason: 'no frame handled input during the press' };
+    const shown = markers.find((marker) => marker.screen === screen &&
+        marker.atEpochMs >= input.startedAtEpochMs &&
+        marker.atEpochMs <= searchEndEpochMs);
+    if (!shown) {
+        return {
+            ...base,
+            unmeasuredReason: `no [farmslot-perf] shown ${screen} line after the touch, before the next press`,
+        };
+    }
+    const reach = shown.atEpochMs + SHOWN_MARKER_FRAMES * frameBudgetMs;
+    const endedAtEpochMs = samples.reduce((end, sample) => sample.startedAtEpochMs >= input.startedAtEpochMs && sample.startedAtEpochMs <= reach
+        ? Math.max(end, sample.completedAtEpochMs)
+        : end, shown.atEpochMs);
+    return {
+        ...base,
+        latencyMs: round(endedAtEpochMs - input.startedAtEpochMs),
+        answer: 'shown',
+    };
+}
+function inputFrame(samples, span, windowEndEpochMs) {
+    const spanEnd = span.endedAtEpochMs ?? windowEndEpochMs;
+    return samples.find((sample) => sample.input === true &&
+        sample.startedAtEpochMs >= span.startedAtEpochMs &&
+        sample.startedAtEpochMs <= spanEnd);
+}
+// Every failure names the metric, the limit, the measured value, where it was
+// measured and, given a baseline, the baseline's value. Values print with
+// enough decimals that a value over its limit never reads as equal to it.
+function checkBudget(summary, limits, baseline) {
+    const failures = [];
+    const against = (name, value, unit) => baseline && value !== undefined
+        ? `; ${baseline.label} baseline ${name} ${formatValue(value)} ${unit}`
+        : '';
+    if (limits.min_sustained_fps !== undefined &&
+        summary.sustainedFps !== undefined &&
+        summary.sustainedFps < limits.min_sustained_fps) {
+        failures.push(`sustained fps (${FPS_METRIC}) ${formatAgainst(summary.sustainedFps, limits.min_sustained_fps)} fps < ${limits.min_sustained_fps} fps (${summary.id})${against('sustained', baseline?.sustained_fps, 'fps')}`);
+    }
+    if (limits.max_press_p95_ms !== undefined &&
+        summary.press.p95Ms !== undefined &&
+        summary.press.p95Ms > limits.max_press_p95_ms) {
+        const [slowest, stats] = Object.entries(summary.pressByTarget).reduce((worst, entry) => ((entry[1].maxMs ?? 0) > (worst[1]?.maxMs ?? -1) ? entry : worst), [undefined, undefined]);
+        failures.push(`press p95 (${summary.presses.every((press) => press.marker) ? SHOWN_PRESS_METRIC : PRESS_METRIC}) ${formatAgainst(summary.press.p95Ms, limits.max_press_p95_ms)} ms > ${limits.max_press_p95_ms} ms (${summary.id}${slowest && stats?.maxMs !== undefined
+            ? `; slowest ${slowest} ${formatValue(stats.maxMs)} ms`
+            : ''})${against('p95', baseline?.press_p95_ms, 'ms')}`);
+    }
+    if (limits.max_press_ms !== undefined) {
+        for (const press of summary.presses) {
+            const where = `${press.target ?? press.nodeId}, node ${press.nodeId}`;
+            const metric = press.marker ? SHOWN_PRESS_METRIC : PRESS_METRIC;
+            if (press.latencyMs === undefined) {
+                failures.push(`press (${metric}) untimed, counted over ${limits.max_press_ms} ms (${where}): ${press.unmeasuredReason}${against('max', baseline?.press_max_ms, 'ms')}`);
+            }
+            else if (press.latencyMs > limits.max_press_ms) {
+                failures.push(`press (${metric}) ${formatAgainst(press.latencyMs, limits.max_press_ms)} ms > ${limits.max_press_ms} ms (${where})${against('max', baseline?.press_max_ms, 'ms')}`);
+            }
+        }
+    }
+    if (limits.min_frames !== undefined && summary.frames.frameCount < limits.min_frames) {
+        failures.push(`gfxinfo frames ${summary.frames.frameCount} < ${limits.min_frames} (${summary.id})${against('frames', baseline?.frames, '').trimEnd()}`);
+    }
+    // A capture with a gap can't support any verdict: a dropped device leaves no
+    // frames and untimed presses, which would otherwise read as the app failing.
+    // Nor can frames with no refresh budget: sustained FPS and the frame budget
+    // a mount needs would be guesses.
+    const inconclusive = summary.coverageGapReasons.map((reason) => `coverage gap: ${reason}`);
+    if (summary.frames.frameCount > 0 && summary.frames.refreshRateHz === undefined) {
+        inconclusive.push('no refresh budget: gfxinfo gave no FrameInterval and the frame starts show no refresh rate');
+    }
+    return {
+        verdict: inconclusive.length > 0 ? 'inconclusive' : failures.length > 0 ? 'fail' : 'pass',
+        limits,
+        failures,
+        inconclusive,
+    };
+}
+/** The value with the fewest decimals (up to 3) that don't round it onto `limit`. */
+function formatAgainst(value, limit) {
+    for (let decimals = 0; decimals < 3; decimals += 1) {
+        const text = value.toFixed(decimals);
+        if (Number(text) !== limit)
+            return String(Number(text));
+    }
+    return String(Number(value.toFixed(3)));
+}
+function formatValue(value) {
+    return String(Math.round(value * 10) / 10);
+}
+async function describeCheckout(projectRoot, logger) {
+    try {
+        const head = (await execFileAsync('git', ['-C', projectRoot, 'rev-parse', 'HEAD'], { encoding: 'utf8' })).stdout.trim();
+        const status = (await execFileAsync('git', ['-C', projectRoot, 'status', '--porcelain', '--untracked-files=no'], { encoding: 'utf8' })).stdout.trim();
+        return { head, dirty: status.length > 0 };
+    }
+    catch (error) {
+        // Outside a git checkout the report names no source revision; any other
+        // git failure leaves it out too, and says why.
+        if (!/not a git repository/u.test(execStderr(error))) {
+            logger.warn(`Performance report could not read the checkout: ${errorMessage(error)}`);
+        }
+        return undefined;
+    }
+}
+function execStderr(error) {
+    if (error && typeof error === 'object' && 'stderr' in error)
+        return String(error.stderr);
+    return '';
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function windowSpans(spans, summary) {
+    return spans.filter((span) => span.startedAtEpochMs >= summary.startedAtEpochMs &&
+        span.startedAtEpochMs <= summary.endedAtEpochMs);
+}
+function pressStats(presses) {
+    const timed = presses
+        .map((press) => press.latencyMs)
+        .filter((value) => value !== undefined)
+        .sort((first, second) => first - second);
+    return {
+        count: presses.length,
+        timed: timed.length,
+        shown: presses.filter((press) => press.answer === 'shown').length,
+        firstFrame: presses.filter((press) => press.answer === 'first-frame').length,
+        ...(timed.length > 0
+            ? {
+                p50Ms: round(percentile(timed, 0.5)),
+                p95Ms: round(percentile(timed, 0.95)),
+                maxMs: round(timed.at(-1) ?? 0),
+            }
+            : {}),
+    };
+}
+function answeredBy(stats) {
+    const how = [
+        ...(stats.shown > 0 ? [`${stats.shown} by shown line`] : []),
+        ...(stats.firstFrame > 0 ? [`${stats.firstFrame} first-frame`] : []),
+    ];
+    return how.length > 0 ? ` (${how.join(', ')})` : '';
+}
+function checkTargets(summary, targets) {
+    return {
+        ...(targets.fps === undefined
+            ? {}
+            : {
+                fps: {
+                    target: targets.fps,
+                    ...(summary.sustainedFps === undefined ? {} : { sustainedFps: summary.sustainedFps }),
+                    ...(summary.frames.activeFps === undefined
+                        ? {}
+                        : { activeFps: summary.frames.activeFps }),
+                    met: summary.sustainedFps === undefined || summary.sustainedFps >= targets.fps,
+                },
+            }),
+        ...(targets.press_ms === undefined
+            ? {}
+            : {
+                press: {
+                    target: targets.press_ms,
+                    ...(summary.press.p95Ms === undefined ? {} : { p95Ms: summary.press.p95Ms }),
+                    ...(summary.press.maxMs === undefined ? {} : { maxMs: summary.press.maxMs }),
+                    met: summary.press.maxMs === undefined || summary.press.maxMs <= targets.press_ms,
+                },
+            }),
+    };
+}
+export function renderPerformanceReport(title, summaries, environment = {}) {
+    const value = (number, unit = '') => number === undefined ? 'n/a' : `${formatValue(number)}${unit}`;
+    const rows = summaries.map((summary) => {
+        const fpsTarget = summary.targets?.fps;
+        const toTarget = fpsTarget && summary.sustainedFps !== undefined
+            ? `${Math.round((Math.min(summary.sustainedFps, fpsTarget.target) / fpsTarget.target) * 100)}% of ${fpsTarget.target}`
+            : 'n/a';
+        return [
+            summary.id,
+            summary.budget?.verdict ?? 'n/a',
+            value(summary.sustainedFps),
+            value(summary.frames.activeFps),
+            toTarget,
+            `${value(summary.press.p50Ms)} / ${value(summary.press.p95Ms)} / ${value(summary.press.maxMs)}`,
+            value(summary.frames.longestFrameMs, ' ms'),
+            value(summary.frames.overBudgetFramePercent, '%'),
+            String(summary.frames.frameCount),
+            value(summary.frames.refreshRateHz),
+        ];
+    });
+    const header = [
+        'flow',
+        'budget',
+        'sustained fps',
+        'active fps',
+        'fps target',
+        'press p50 / p95 / max (ms)',
+        'worst frame',
+        'janky',
+        'frames',
+        'Hz',
+    ];
+    const { device, checkout } = environment;
+    const lines = [
+        `# ${title}`,
+        '',
+        `- Device: ${device
+            ? [
+                device.model ?? 'unknown model',
+                device.androidRelease ? `Android ${device.androidRelease}` : '',
+                device.serial,
+            ]
+                .filter(Boolean)
+                .join(', ')
+            : 'unknown'}`,
+        `- App: ${device
+            ? [
+                device.packageId,
+                device.versionName,
+                device.buildType ? `${device.buildType} build` : '',
+                device.lastUpdateTime ? `installed ${device.lastUpdateTime}` : '',
+            ]
+                .filter(Boolean)
+                .join(', ')
+            : 'unknown'}`,
+        `- Checkout: ${checkout?.head ? `${checkout.head}${checkout.dirty ? ' (uncommitted changes)' : ''}` : 'unknown'}`,
+        '',
+        `| ${header.join(' | ')} |`,
+        `| ${header.map(() => '---').join(' | ')} |`,
+        ...rows.map((row) => `| ${row.join(' | ')} |`),
+        '',
+    ];
+    const targets = summaries.flatMap((summary) => Object.entries(summary.pressByTarget).map(([target, stats]) => [
+        summary.id,
+        target,
+        `${stats.timed}/${stats.count}${answeredBy(stats)}`,
+        `${value(stats.p50Ms)} / ${value(stats.p95Ms)} / ${value(stats.maxMs)}`,
+        summary.targets?.press
+            ? stats.maxMs !== undefined && stats.maxMs <= summary.targets.press.target
+                ? 'yes'
+                : 'no'
+            : 'n/a',
+    ]));
+    if (targets.length > 0) {
+        lines.push('| flow | press target | timed | p50 / p95 / max (ms) | within press target |', '| --- | --- | --- | --- | --- |', ...targets.map((row) => `| ${row.join(' | ')} |`), '');
+    }
+    for (const summary of summaries) {
+        if (summary.press.shown === 0)
+            continue;
+        const hz = summary.frames.refreshRateHz;
+        lines.push(`- ${summary.id} shown presses: touch frame to the end of the last frame that started by two vsyncs${hz === undefined
+            ? ''
+            : ` (${formatValue((SHOWN_MARKER_FRAMES * 1000) / hz)} ms at ${Math.round(hz)} Hz)`} after the screen's \`[farmslot-perf] shown\` line, logged from the second animation frame after focus. A press can over-read by up to about two light frames, and could miss a mount frame that starts more than two vsyncs after the line.`);
+    }
+    for (const summary of summaries) {
+        const baseline = summary.baseline;
+        if (!baseline)
+            continue;
+        const parts = [
+            baseline.press_p95_ms === undefined ? '' : `press p95 ${value(baseline.press_p95_ms, ' ms')}`,
+            baseline.press_max_ms === undefined ? '' : `max ${value(baseline.press_max_ms, ' ms')}`,
+            baseline.sustained_fps === undefined ? '' : `sustained ${value(baseline.sustained_fps)} fps`,
+            baseline.frames === undefined ? '' : `${baseline.frames} frames`,
+            baseline.refresh_hz === undefined ? '' : `${baseline.refresh_hz} Hz`,
+        ].filter(Boolean);
+        lines.push(`- ${summary.id} baseline, ${baseline.label}: ${parts.join(', ') || 'recorded'}`);
+    }
+    for (const summary of summaries) {
+        for (const failure of summary.budget?.failures ?? [])
+            lines.push(`- FAIL ${failure}`);
+        for (const reason of summary.budget?.inconclusive ?? []) {
+            lines.push(`- INCONCLUSIVE ${summary.id}: ${reason}`);
+        }
+        for (const note of summary.notes)
+            lines.push(`- NOTE ${summary.id}: ${note}`);
+    }
+    // Budgeted windows list their gaps as INCONCLUSIVE above.
+    const gaps = summaries.filter((summary) => !summary.budget && summary.coverageGapReasons.length > 0);
+    for (const summary of gaps) {
+        lines.push(`- ${summary.id} coverage: ${summary.coverageGapReasons.join('; ')}`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+function parseBudget(value) {
+    if (value === undefined)
+        return undefined;
+    const record = requireRecord(value, 'budget');
+    return {
+        ...optionalLimit(record, 'min_sustained_fps'),
+        ...optionalLimit(record, 'max_press_p95_ms'),
+        ...optionalLimit(record, 'max_press_ms'),
+        ...optionalLimit(record, 'min_frames'),
+    };
+}
+function parseShownMarkerMap(value) {
+    if (value === undefined)
+        return undefined;
+    const map = {};
+    for (const [target, screen] of Object.entries(requireRecord(value, 'shown_markers'))) {
+        if (typeof screen !== 'string' || !screen.trim()) {
+            throw new RecipeExecutionError('harness', `${PERFORMANCE_CAPTURE_ACTION} shown_markers.${target} must name a screen.`);
+        }
+        map[target] = screen.trim();
+    }
+    return map;
+}
+function parseBaseline(value) {
+    if (value === undefined)
+        return undefined;
+    const record = requireRecord(value, 'baseline');
+    if (typeof record.label !== 'string' || !record.label.trim()) {
+        throw new RecipeExecutionError('harness', `${PERFORMANCE_CAPTURE_ACTION} baseline.label must be a non-empty string.`);
+    }
+    return {
+        ...record,
+        label: record.label.trim(),
+        ...optionalLimit(record, 'sustained_fps'),
+        ...optionalLimit(record, 'press_p95_ms'),
+        ...optionalLimit(record, 'press_max_ms'),
+        ...optionalLimit(record, 'frames'),
+        ...optionalLimit(record, 'refresh_hz'),
+    };
+}
+function parseTargets(value) {
+    if (value === undefined)
+        return undefined;
+    const record = requireRecord(value, 'targets');
+    return { ...optionalLimit(record, 'fps'), ...optionalLimit(record, 'press_ms') };
+}
+function requireRecord(value, label) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        return Object.fromEntries(Object.entries(value));
+    }
+    throw new RecipeExecutionError('harness', `${PERFORMANCE_CAPTURE_ACTION} ${label} must be an object.`);
+}
+function optionalLimit(record, key) {
+    const raw = record[key];
+    if (raw === undefined)
+        return {};
+    const number = typeof raw === 'string' ? Number(raw) : raw;
+    if (typeof number !== 'number' || !Number.isFinite(number) || number <= 0) {
+        throw new RecipeExecutionError('harness', `${PERFORMANCE_CAPTURE_ACTION} ${key} must be a positive number.`);
+    }
+    const limit = {};
+    limit[key] = number;
+    return limit;
+}
+async function writeArtifact(context, relativePath, content) {
+    const file = context.resolveArtifactPath(relativePath);
+    await mkdir(path.dirname(file), { recursive: true });
+    await writeFile(file, content);
+}
+function boundedDuration(value) {
+    const number = positiveNumber(value);
+    return number === undefined ? DEFAULT_MAX_DURATION_MS : Math.min(number, MAX_DURATION_MS);
+}
+function positiveNumber(value) {
+    const number = typeof value === 'string' ? Number(value) : value;
+    return typeof number === 'number' && Number.isFinite(number) && number > 0 ? number : undefined;
+}
+function safeId(id) {
+    return id.replace(/[^a-zA-Z0-9._-]/gu, '-');
+}
+//# sourceMappingURL=performance-capture.js.map