@farmslot/adapter-rn 0.30.0 → 0.31.1

package/dist/performance-capture.d.ts

@@ -0,0 +1,192 @@
+import { type ActionHandler } from '@farmslot/recipe-runner';
+import { type FrameMetricSummary, type PerformanceSourceStatus } from '@farmslot/recipe-runner/runtime/cdp-trace';
+import { type AndroidDeviceDescription, type AndroidFrameSample, type AndroidGfxinfoCaptureResult, type AndroidGfxinfoPerformanceBackend, type AndroidShownMarker } from './android-gfxinfo-performance.js';
+export declare const PERFORMANCE_CAPTURE_ACTION = "app.performance_capture";
+export interface RecipeNodeSpan {
+    nodeId: string;
+    action: string;
+    /** What the node acted on (its test id, selector, text or key), named in failures. */
+    target?: string;
+    startedAtEpochMs: number;
+    endedAtEpochMs?: number;
+}
+export interface PerformanceBudget {
+    /** Fail when the lowest sustained FPS of the window is below this. */
+    min_sustained_fps?: number;
+    /** Fail when the 95th percentile press latency is above this. */
+    max_press_p95_ms?: number;
+    /** Fail when any press latency is above this, or a press could not be timed. */
+    max_press_ms?: number;
+    /** Fail when the window recorded fewer native frames, e.g. a scroll that never rendered. */
+    min_frames?: number;
+}
+/**
+ * The reference a failure is compared against, e.g. the default branch on a
+ * named build and refresh rate. `label` and the numbers appear in failure
+ * messages; the whole object is echoed in the summary.
+ */
+export interface PerformanceBaseline {
+    label: string;
+    sustained_fps?: number;
+    press_p95_ms?: number;
+    press_max_ms?: number;
+    /** Native frames the window recorded on the baseline. */
+    frames?: number;
+    /** Display refresh rate of the baseline; a different measured rate is noted. */
+    refresh_hz?: number;
+    [key: string]: unknown;
+}
+export interface PerformanceTargets {
+    fps?: number;
+    press_ms?: number;
+}
+export interface PressLatency {
+    nodeId: string;
+    action: string;
+    target?: string;
+    /** Input frame start to the end of the frame that answered it; absent when not timed. */
+    latencyMs?: number;
+    /**
+     * `shown`: the screen's `[farmslot-perf] shown` line, logged after React
+     * committed it, and the frames that started by two frame budgets after it.
+     * `mount`: the first frame after the touch that stood out is the answer.
+     * `first-frame`: none stood out, so the press is timed to the first frame
+     * after the touch; the new screen did no measurable UI-thread work.
+     */
+    answer?: 'shown' | 'mount' | 'first-frame';
+    /** The screen whose shown line times the press (`shown_markers`). */
+    marker?: string;
+    /** Why the press has no latency. */
+    unmeasuredReason?: string;
+}
+export interface PerformanceWindowSummary {
+    schemaVersion: 1;
+    id: string;
+    status: PerformanceSourceStatus;
+    platform: 'android';
+    source: string;
+    startedAtEpochMs: number;
+    endedAtEpochMs: number;
+    durationMs: number;
+    frames: FrameMetricSummary;
+    /** The lowest active FPS over any `sustainedWindowMs` of the window; absent with too few frames. */
+    sustainedFps?: number;
+    sustainedWindowMs: number;
+    presses: PressLatency[];
+    press: PressStats;
+    /** The same statistics per press target, e.g. per tab. */
+    pressByTarget: Record<string, PressStats>;
+    /**
+     * `inconclusive` when the capture has a coverage gap (failed polls, frames
+     * gfxinfo overwrote), whatever else failed: it never passes, and `failures`
+     * still lists what the partial capture showed. An idle window, no frames and
+     * no gaps, passes.
+     */
+    budget?: {
+        verdict: 'pass' | 'fail' | 'inconclusive';
+        limits: PerformanceBudget;
+        failures: string[];
+        inconclusive: string[];
+    };
+    baseline?: PerformanceBaseline;
+    targets?: {
+        fps?: {
+            target: number;
+            sustainedFps?: number;
+            activeFps?: number;
+            met: boolean;
+        };
+        press?: {
+            target: number;
+            p95Ms?: number;
+            maxMs?: number;
+            met: boolean;
+        };
+    };
+    /** Frames the capture may have missed: poll failures, overwritten frames, an overrun window. */
+    coverageGapReasons: string[];
+    /** Why the source has no frames, e.g. an idle screen. Not a gap. */
+    unavailableReasons: string[];
+    /** Observations that don't change the verdict, e.g. a refresh rate unlike the baseline's. */
+    notes: string[];
+}
+export interface PressStats {
+    count: number;
+    timed: number;
+    /** Timed presses answered by their screen's shown line. */
+    shown: number;
+    /** Timed presses with no standout mount frame, answered by the first frame. */
+    firstFrame: number;
+    p50Ms?: number;
+    p95Ms?: number;
+    maxMs?: number;
+}
+export interface PerformanceCaptureSession {
+    handler: ActionHandler;
+    /** The runner's node boundaries, used to find the presses inside a window. */
+    recordNodeEvent(event: {
+        nodeId: string;
+        action: string;
+        target?: string;
+        status: 'running' | 'passed' | 'failed';
+    }): void;
+    close(): Promise<void>;
+}
+export interface PerformanceCaptureSessionOptions {
+    env: Record<string, string | undefined>;
+    logger?: Pick<Console, 'warn'>;
+    /** Validate the nodes without a device: no window opens and nothing is measured. */
+    dryRun?: boolean;
+    createBackend?: (env: Record<string, string | undefined>) => AndroidGfxinfoPerformanceBackend;
+    now?: () => number;
+}
+export declare function createPerformanceCaptureSession({ env, logger, dryRun, createBackend, now, }: PerformanceCaptureSessionOptions): PerformanceCaptureSession;
+export declare function summarizeWindow({ id, startedAtEpochMs, endedAtEpochMs, maxDurationMs, result, spans, budget, shownMarkers, baseline, targets, sustainedWindowMs, responseWindowMs, }: {
+    id: string;
+    startedAtEpochMs: number;
+    endedAtEpochMs: number;
+    maxDurationMs: number;
+    result: AndroidGfxinfoCaptureResult;
+    spans: readonly RecipeNodeSpan[];
+    budget?: PerformanceBudget;
+    /** Press target -> the screen whose `[farmslot-perf] shown` line answers it. */
+    shownMarkers?: Record<string, string>;
+    baseline?: PerformanceBaseline;
+    targets?: PerformanceTargets;
+    sustainedWindowMs: number;
+    responseWindowMs: number;
+}): PerformanceWindowSummary;
+/**
+ * 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 declare function measurePress(samples: readonly AndroidFrameSample[], span: RecipeNodeSpan, responseWindowMs: number, windowEndEpochMs: number): PressLatency;
+/**
+ * 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 declare function measureShownPress(samples: readonly AndroidFrameSample[], span: RecipeNodeSpan, screen: string, markers: readonly AndroidShownMarker[], searchEndEpochMs: number, frameBudgetMs: number): PressLatency;
+export interface PerformanceReportEnvironment {
+    device?: AndroidDeviceDescription;
+    checkout?: {
+        head?: string;
+        dirty?: boolean;
+    };
+}
+export declare function renderPerformanceReport(title: string, summaries: readonly PerformanceWindowSummary[], environment?: PerformanceReportEnvironment): string;
+//# sourceMappingURL=performance-capture.d.ts.map

package/dist/performance-capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"performance-capture.d.ts","sourceRoot":"","sources":["../src/performance-capture.ts"],"names":[],"mappings":"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"}