@felipe-software/react-native-gpui 0.0.0-stage → 1.0.1

package/cli/commands/shot.ts

@@ -0,0 +1,312 @@
+// `rngpui shot` / `reshot` / `diff` — the fast one-shot iteration loop.
+//
+// shot: launch a bundle/fixture offscreen, wait for a stable frame, write png + tree,
+//       then print the png path + key measurements (bounds + sampled color of every
+//       --select'd node) in ONE command. No flag archaeology — the output tells you
+//       what to look at next.
+// reshot: re-capture an already-running kept session (`rngpui dev` keeps one alive)
+//       in sub-second time — no relaunch, no re-bundle.
+// diff: compare two pngs, print the changed-pixel ratio + the bounding box of the
+//       change, and (optionally) write a magenta-on-gray highlight png.
+
+import { copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, resolve as resolvePath } from "node:path";
+import type { DumpNode, Host, LaunchedHost } from "../host";
+import { attachSession, launchHost, scopeToWindow } from "../host";
+import { isVisible, resolve as resolveSelector, walk } from "../selectors";
+import { averageColor, dominantColor } from "../../scripts/pixel.mjs";
+import { decodePng, encodePng, readPng } from "../../scripts/png.mjs";
+
+export type ShotFlags = {
+    json: boolean;
+    size?: string;
+    appearance?: string;
+    out?: string;
+    select: string[];
+    crop?: string;
+    fixture: boolean;
+    session?: string;
+    bundle?: string;
+    launch?: string;
+    keep: boolean;
+    window?: string;
+};
+
+// the team-machine app paints an empty "connecting…" shell without data; the fixture
+// env loads deterministic demo sessions so an offscreen shot shows the real layout.
+// honored by both the team-machine bundle and rngpui examples (which simply ignore it).
+function shotEnv(flags: ShotFlags): Record<string, string> {
+    const env: Record<string, string> = {};
+    if (flags.fixture) env.TM_FIXTURE_ONLY = "1";
+    if (flags.appearance === "light" || flags.appearance === "dark") {
+        // native bridge theme (flips tamagui via the appearance event) AND the JS-side
+        // capture entries — covers the team-machine bundle and the parity/capture fixtures.
+        env.RNGPUI_FORCE_APPEARANCE = flags.appearance;
+        env.TM_CAPTURE_APPEARANCE = flags.appearance;
+    }
+    return env;
+}
+
+function nodeLabel(node: DumpNode): string {
+    const a = node.accessibility ?? {};
+    return a.testID ?? a.identifier ?? a.nativeID ?? a.label ?? (node.text ? `"${node.text.slice(0, 24)}"` : `#${node.globalId}`);
+}
+
+function boundsStr(b: DumpNode["bounds"]): string {
+    return b ? `${b.x.toFixed(0)},${b.y.toFixed(0)} ${b.width.toFixed(0)}x${b.height.toFixed(0)}` : "—";
+}
+
+function matchNodes(dump: DumpNode, selector: string): DumpNode[] {
+    const { best, candidates } = resolveSelector(dump, selector);
+    if (!best) return [];
+    return candidates.filter((c) => c.matchedValue === best.matchedValue).map((c) => c.node);
+}
+
+type Measurement = {
+    selector: string;
+    matched: number;
+    globalId: number | null;
+    type: string | null;
+    label: string | null;
+    bounds: DumpNode["bounds"] | null;
+    visible: boolean;
+    dominant: string | null;
+    average: string | null;
+    coverage: number | null;
+};
+
+// sample a node's color out of the just-captured png (scaled from logical → pixel).
+function sampleNodeFromPng(img: { width: number; height: number }, host: Host, node: DumpNode) {
+    const b = node.bounds;
+    if (!b || b.width < 1 || b.height < 1) return null;
+    const scaleX = img.width / host.window.width;
+    const scaleY = img.height / host.window.height;
+    const rect = {
+        x: Math.round(b.x * scaleX),
+        y: Math.round(b.y * scaleY),
+        width: Math.max(1, Math.round(b.width * scaleX)),
+        height: Math.max(1, Math.round(b.height * scaleY)),
+    };
+    const dom = dominantColor(img as never, rect);
+    const avg = averageColor(img as never, rect);
+    return { dominant: dom.hex, average: avg.hex, coverage: dom.coverage };
+}
+
+function measureSelectors(host: Host, dump: DumpNode, png: string, selectors: string[]): Measurement[] {
+    if (selectors.length === 0) return [];
+    const img = existsSync(png) && statSync(png).size > 0 ? readPng(png) : null;
+    return selectors.map((selector) => {
+        const nodes = matchNodes(dump, selector);
+        const node = nodes[0];
+        if (!node) {
+            return { selector, matched: 0, globalId: null, type: null, label: null, bounds: null, visible: false, dominant: null, average: null, coverage: null };
+        }
+        const color = img && isVisible(node) ? sampleNodeFromPng(img, host, node) : null;
+        return {
+            selector,
+            matched: nodes.length,
+            globalId: node.globalId,
+            type: node.type,
+            label: nodeLabel(node),
+            bounds: node.bounds ?? null,
+            visible: isVisible(node),
+            dominant: color?.dominant ?? null,
+            average: color?.average ?? null,
+            coverage: color?.coverage ?? null,
+        };
+    });
+}
+
+// the whole point of shot: one block of output that tells a designer/agent exactly
+// what they have and what to look at next — no second command, no flag hunting.
+function printShot(result: ShotResult, json: boolean) {
+    if (json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(`  png: ${result.png}  (${result.pngSize})${result.appearance ? `  appearance=${result.appearance}` : ""}`);
+    console.log(`  tree: ${result.tree}`);
+    console.log(`  nodes=${result.nodes} visible=${result.visible} webviews=${result.webviews} window=${result.window}`);
+    if (result.session) console.log(`  session: ${result.session}  (reshot with: rngpui reshot --session ${result.session})`);
+    if (result.measurements.length) {
+        console.log("  measurements:");
+        for (const m of result.measurements) {
+            if (m.matched === 0) {
+                console.log(`    ${JSON.stringify(m.selector)} — no match`);
+                continue;
+            }
+            const color = m.dominant ? `  dominant=${m.dominant} (${((m.coverage ?? 0) * 100).toFixed(0)}%) avg=${m.average}` : m.visible ? "" : "  [not painted]";
+            const more = m.matched > 1 ? ` (+${m.matched - 1} more)` : "";
+            console.log(`    ${JSON.stringify(m.selector)} → ${m.type} ${m.label} #${m.globalId} [${boundsStr(m.bounds)}]${color}${more}`);
+        }
+    }
+}
+
+type ShotResult = {
+    png: string;
+    pngSize: string;
+    tree: string;
+    nodes: number;
+    visible: number;
+    webviews: number;
+    window: string;
+    appearance: string | null;
+    session: string | null;
+    measurements: Measurement[];
+};
+
+// produce the png + tree + measurements for an already-attached/launched host.
+function captureShot(host: Host, flags: ShotFlags, dump: DumpNode, session: string | null): ShotResult {
+    const outPng = resolvePath(flags.out ?? "/tmp/rngpui-shot.png");
+    const outTree = outPng.replace(/\.png$/i, ".tree.json");
+    mkdirSync(dirname(outPng), { recursive: true });
+    host.capture(outPng);
+    writeFileSync(outTree, JSON.stringify(dump));
+    const img = existsSync(outPng) ? readPng(outPng) : { width: 0, height: 0 };
+    let nodes = 0;
+    let visible = 0;
+    let webviews = 0;
+    for (const node of walk(dump)) {
+        nodes += 1;
+        if (isVisible(node)) visible += 1;
+        if (node.type === "webview") webviews += 1;
+    }
+    return {
+        png: outPng,
+        pngSize: `${img.width}x${img.height}`,
+        tree: outTree,
+        nodes,
+        visible,
+        webviews,
+        window: `${host.window.width}x${host.window.height}`,
+        appearance: flags.appearance === "light" || flags.appearance === "dark" ? flags.appearance : null,
+        session,
+        measurements: measureSelectors(host, dump, outPng, flags.select),
+    };
+}
+
+export async function runShot(flags: ShotFlags): Promise<number> {
+    // reshot path: a kept session is already alive — re-capture in sub-second time.
+    if (flags.session) {
+        const session = await attachSession(flags.session);
+        const host = flags.window ? await scopeToWindow(session, flags.window) : session;
+        try {
+            const dump = await host.dump();
+            printShot(captureShot(host, flags, dump, flags.session), flags.json);
+            return 0;
+        } finally {
+            host.close(); // keepOnClose: true for attached sessions, so this is a no-op for the process
+        }
+    }
+
+    const target = flags.bundle ?? flags.launch;
+    if (!target) {
+        console.error("  shot needs --bundle <app.js>, --launch <entry.tsx>, or --session <dir>");
+        return 1;
+    }
+    const env = shotEnv(flags);
+    const prevEnv: Record<string, string | undefined> = {};
+    for (const [key, value] of Object.entries(env)) {
+        prevEnv[key] = process.env[key];
+        process.env[key] = value;
+    }
+    let host: LaunchedHost | null = null;
+    try {
+        host = await launchHost(flags.launch ?? "", {
+            bundle: flags.bundle,
+            size: flags.size,
+            keep: flags.keep,
+        });
+        const dump = await host.dump();
+        const session = flags.keep ? host.sessionDir : null;
+        printShot(captureShot(host, flags, dump, session), flags.json);
+        return 0;
+    } finally {
+        host?.close();
+        for (const [key, value] of Object.entries(prevEnv)) {
+            if (value === undefined) delete process.env[key];
+            else process.env[key] = value;
+        }
+    }
+}
+
+// ---- diff ----
+
+type DiffResult = {
+    before: string;
+    after: string;
+    width: number;
+    height: number;
+    changed: number;
+    total: number;
+    ratio: number;
+    maxDelta: number;
+    box: { x: number; y: number; width: number; height: number } | null;
+    out: string | null;
+};
+
+export async function runDiff(positional: string[], flags: { json: boolean; out?: string; threshold?: number }): Promise<number> {
+    const [beforePath, afterPath] = positional;
+    if (!beforePath || !afterPath) {
+        console.error("  usage: rngpui diff <before.png> <after.png> [--out highlight.png] [--threshold n]");
+        return 1;
+    }
+    const before = decodePng(readFileSync(beforePath));
+    const after = decodePng(readFileSync(afterPath));
+    const width = Math.min(before.width, after.width);
+    const height = Math.min(before.height, after.height);
+    const threshold = flags.threshold ?? 24;
+    const diff = Buffer.alloc(width * height * 4);
+    let changed = 0;
+    let maxDelta = 0;
+    let minX = width;
+    let minY = height;
+    let maxX = -1;
+    let maxY = -1;
+    for (let y = 0; y < height; y += 1) {
+        for (let x = 0; x < width; x += 1) {
+            const bi = (y * before.width + x) * 4;
+            const ai = (y * after.width + x) * 4;
+            const oi = (y * width + x) * 4;
+            const dr = Math.abs(before.rgba[bi] - after.rgba[ai]);
+            const dg = Math.abs(before.rgba[bi + 1] - after.rgba[ai + 1]);
+            const db = Math.abs(before.rgba[bi + 2] - after.rgba[ai + 2]);
+            const da = Math.abs(before.rgba[bi + 3] - after.rgba[ai + 3]);
+            const md = Math.max(dr, dg, db, da);
+            if (md > maxDelta) maxDelta = md;
+            if (md > threshold) {
+                changed += 1;
+                diff[oi] = 255;
+                diff[oi + 1] = 0;
+                diff[oi + 2] = 180;
+                diff[oi + 3] = 255;
+                if (x < minX) minX = x;
+                if (y < minY) minY = y;
+                if (x > maxX) maxX = x;
+                if (y > maxY) maxY = y;
+            } else {
+                const gray = (after.rgba[ai] * 0.299 + after.rgba[ai + 1] * 0.587 + after.rgba[ai + 2] * 0.114) | 0;
+                diff[oi] = gray;
+                diff[oi + 1] = gray;
+                diff[oi + 2] = gray;
+                diff[oi + 3] = 255;
+            }
+        }
+    }
+    const total = width * height;
+    const out = flags.out ? resolvePath(flags.out) : null;
+    if (out) {
+        mkdirSync(dirname(out), { recursive: true });
+        writeFileSync(out, encodePng(width, height, diff));
+    }
+    const box = maxX >= 0 ? { x: minX, y: minY, width: maxX - minX + 1, height: maxY - minY + 1 } : null;
+    const result: DiffResult = { before: beforePath, after: afterPath, width, height, changed, total, ratio: changed / total, maxDelta, box, out };
+    if (flags.json) {
+        console.log(JSON.stringify(result, null, 2));
+    } else {
+        console.log(`  ${changed}/${total} px changed (${(result.ratio * 100).toFixed(3)}%)  maxDelta=${maxDelta}  threshold=${threshold}`);
+        console.log(`  changed region: ${box ? `${box.x},${box.y} ${box.width}x${box.height}` : "(no change above threshold)"}`);
+        if (out) console.log(`  highlight: ${out}  (magenta = changed, gray = unchanged)`);
+    }
+    return 0;
+}

package/cli/commands/trace.ts

@@ -0,0 +1,293 @@
+// `rngpui trace` — record an animation's actual per-frame values, no screenshots.
+//
+//   rngpui trace dialog --action "tap open-button" --ms 1200 --session <dir>
+//   rngpui trace --all --keys opacity,transform --ms 800 --attach
+//
+// Arms an in-service trace session (traceStart), optionally fires input actions, waits,
+// then collects (traceStop) every off-thread reanimated style write and NativeLayout
+// tween tick that landed in the window — each tagged with a wall-clock timestamp and the
+// painted-frame counter. The analysis proves the three things a screenshot can't:
+// cadence (per-sample gaps + dropped frames), curve shape (sparkline; spring overshoot
+// is visible), and endpoints (first → last value).
+
+import { isDriveableHost, type AttachedHost, type DumpNode, type LaunchedHost } from "../host";
+import { sleep } from "../../scripts/conformance-utils.mjs";
+import { centerOf, parsePoint, resolve } from "../selectors";
+
+type Host = LaunchedHost | AttachedHost;
+
+export interface TraceOptions {
+    json: boolean;
+    /// style keys to record (default: all)
+    keys?: string[];
+    /// observation window after actions fire
+    ms: number;
+    /// input actions to fire right after arming: "tap <selector>", "key <key>", "type <text>"
+    actions: string[];
+    /// trace all nodes instead of resolving selectors
+    all: boolean;
+}
+
+type Sample = { t: number; f: number; id?: number; nativeKey?: string; k: string; v: unknown };
+type StopResponse = {
+    ok: boolean;
+    error?: string;
+    durationMs: number;
+    framesPainted: number;
+    paintGapsMs: number[];
+    truncated: boolean;
+    samples: Sample[];
+};
+
+export async function runTrace(host: Host, selectors: string[], opts: TraceOptions): Promise<number> {
+    if (!isDriveableHost(host)) {
+        console.error("  trace needs a driveable target: --launch, --bundle, --session, or a control-socket attach");
+        return 1;
+    }
+    const driveable = host;
+
+    // resolve selectors → the matched nodes' whole subtrees. Animated style usually
+    // lands on an inner wrapper (Dialog.Content, a presence wrapper), not the node
+    // carrying the testID, so the subtree is the useful unit.
+    let ids: number[] | undefined;
+    let nativeKeys: string[] | undefined;
+    const labels: string[] = [];
+    if (!opts.all && selectors.length > 0) {
+        const dump = await driveable.dump();
+        const idSet = new Set<number>();
+        const nativeSet = new Set<string>();
+        for (const selector of selectors) {
+            const { best } = resolve(dump, selector);
+            if (!best) {
+                console.error(`  no node matched "${selector}"`);
+                return 1;
+            }
+            labels.push(`${selector} → #${best.node.globalId}`);
+            collectSubtree(best.node, idSet, nativeSet);
+        }
+        ids = [...idSet];
+        nativeKeys = nativeSet.size > 0 ? [...nativeSet] : undefined;
+    }
+
+    const start = await driveable.request<{ ok: boolean; error?: string }>({
+        $cmd: "traceStart",
+        ...(ids ? { ids } : {}),
+        ...(opts.keys ? { keys: opts.keys } : {}),
+        ...(nativeKeys ? { nativeKeys } : {}),
+        maxMs: opts.ms + 5_000,
+    });
+    if (!start.ok) {
+        console.error(`  traceStart failed: ${start.error || "unknown"}`);
+        return 1;
+    }
+
+    for (const action of opts.actions) {
+        const error = await fireAction(driveable, action);
+        if (error) {
+            await driveable.request({ $cmd: "traceStop" });
+            console.error(`  action "${action}" failed: ${error}`);
+            return 1;
+        }
+    }
+
+    await sleep(opts.ms);
+
+    const stop = await driveable.request<StopResponse>({ $cmd: "traceStop" });
+    if (!stop.ok) {
+        console.error(`  traceStop failed: ${stop.error || "unknown"}`);
+        return 1;
+    }
+
+    const series = buildSeries(stop.samples);
+    const analysis = series.map(analyzeSeries);
+
+    if (opts.json) {
+        console.log(
+            JSON.stringify(
+                {
+                    tracedNodes: labels,
+                    durationMs: stop.durationMs,
+                    framesPainted: stop.framesPainted,
+                    truncated: stop.truncated,
+                    series: analysis,
+                    samples: stop.samples,
+                },
+                null,
+                2,
+            ),
+        );
+        return 0;
+    }
+
+    const paintLine = paintCadence(stop.paintGapsMs);
+    console.log(`  traced ${Math.round(stop.durationMs)}ms — ${stop.framesPainted} frames painted${paintLine}`);
+    for (const label of labels) console.log(`  ${label}`);
+    if (stop.truncated) console.log("  WARNING: sample buffer overflowed — series are incomplete");
+    if (analysis.length === 0) {
+        console.log("  no animated values recorded — nothing wrote styles/native-layout frames in the window");
+        return 0;
+    }
+    for (const s of analysis) {
+        if (s.kind === "numeric") {
+            const dropped = s.droppedGaps > 0 ? `, ${s.droppedGaps} dropped-frame gaps` : "";
+            const overshoot = s.overshoots > 0 ? `, overshoots final ×${s.overshoots} (springy)` : "";
+            console.log(`  ${s.key}  ${s.first} → ${s.last}  [${s.min}..${s.max}]`);
+            console.log(
+                `    ${s.spark}  ${s.count} samples over ${Math.round(s.spanMs)}ms (~${s.sampleHz}Hz${dropped}${overshoot})`,
+            );
+        } else {
+            console.log(`  ${s.key}  ${s.count} writes: ${s.first} → ${s.last}`);
+        }
+    }
+    return 0;
+}
+
+function collectSubtree(node: DumpNode, ids: Set<number>, nativeKeys: Set<string>) {
+    ids.add(node.globalId);
+    const key = (node as { nativeLayoutKey?: string }).nativeLayoutKey;
+    if (key) nativeKeys.add(key);
+    for (const child of node.children ?? []) collectSubtree(child, ids, nativeKeys);
+}
+
+async function fireAction(
+    driveable: { dump(): Promise<DumpNode>; request<T>(cmd: object): Promise<T> },
+    action: string,
+): Promise<string | null> {
+    const [verb, ...rest] = action.trim().split(/\s+/);
+    const arg = rest.join(" ");
+    if (verb === "tap") {
+        let x: number, y: number;
+        const pt = parsePoint(arg);
+        if (pt) {
+            ({ x, y } = pt);
+        } else {
+            const dump = await driveable.dump();
+            const { best } = resolve(dump, arg);
+            if (!best) return `no node matched "${arg}"`;
+            const center = centerOf(best.node);
+            if (!center) return `node #${best.node.globalId} has no bounds`;
+            ({ x, y } = center);
+        }
+        const r = await driveable.request<{ ok: boolean; error?: string }>({ $cmd: "tap", x, y });
+        return r.ok ? null : r.error || "tap failed";
+    }
+    if (verb === "key") {
+        const r = await driveable.request<{ ok: boolean; error?: string }>({ $cmd: "key", key: arg });
+        return r.ok ? null : r.error || "key failed";
+    }
+    if (verb === "type") {
+        const r = await driveable.request<{ ok: boolean; error?: string }>({ $cmd: "type", text: arg });
+        return r.ok ? null : r.error || "type failed";
+    }
+    return `unknown action verb "${verb}" (tap/key/type)`;
+}
+
+type Point = { t: number; f: number; val: number };
+type Series =
+    | { kind: "numeric"; key: string; points: Point[] }
+    | { kind: "discrete"; key: string; values: { t: number; v: string }[] };
+
+/// Flatten raw samples into per-(node,key) series. Numbers chart; transform arrays
+/// explode into per-component numeric series; everything else is a discrete log.
+function buildSeries(samples: Sample[]): Series[] {
+    const numeric = new Map<string, Point[]>();
+    const discrete = new Map<string, { t: number; v: string }[]>();
+    const push = (key: string, t: number, f: number, v: unknown) => {
+        if (typeof v === "number") {
+            let arr = numeric.get(key);
+            if (!arr) numeric.set(key, (arr = []));
+            arr.push({ t, f, val: v });
+            return;
+        }
+        let arr = discrete.get(key);
+        if (!arr) discrete.set(key, (arr = []));
+        arr.push({ t, v: JSON.stringify(v) });
+    };
+    for (const s of samples) {
+        const base = s.nativeKey ? `${s.nativeKey}(native)` : `#${s.id}`;
+        if (s.k === "transform" && Array.isArray(s.v)) {
+            for (const part of s.v) {
+                if (part && typeof part === "object") {
+                    for (const [tk, tv] of Object.entries(part)) push(`${base}.transform.${tk}`, s.t, s.f, tv);
+                }
+            }
+            continue;
+        }
+        if (s.nativeKey && s.v && typeof s.v === "object") {
+            for (const [fk, fv] of Object.entries(s.v)) push(`${base}.${fk}`, s.t, s.f, fv);
+            continue;
+        }
+        push(`${base}.${s.k}`, s.t, s.f, s.v);
+    }
+    const out: Series[] = [];
+    for (const [key, points] of numeric) out.push({ kind: "numeric", key, points });
+    for (const [key, values] of discrete) out.push({ kind: "discrete", key, values });
+    out.sort((a, b) => a.key.localeCompare(b.key));
+    return out;
+}
+
+const SPARK = "▁▂▃▄▅▆▇█";
+
+function sparkline(values: number[], width = 44): string {
+    if (values.length === 0) return "";
+    // resample to `width` buckets so long traces still read as one curve
+    const sampled: number[] = [];
+    for (let i = 0; i < Math.min(width, values.length); i++) {
+        sampled.push(values[Math.floor((i * values.length) / Math.min(width, values.length))]);
+    }
+    const min = Math.min(...sampled);
+    const max = Math.max(...sampled);
+    const span = max - min || 1;
+    return sampled.map((v) => SPARK[Math.min(7, Math.floor(((v - min) / span) * 8))]).join("");
+}
+
+function analyzeSeries(series: Series) {
+    if (series.kind === "discrete") {
+        const { key, values } = series;
+        return {
+            kind: "discrete" as const,
+            key,
+            count: values.length,
+            first: values[0]?.v,
+            last: values[values.length - 1]?.v,
+        };
+    }
+    const { key, points } = series;
+    const vals = points.map((p) => p.val);
+    const spanMs = points.length > 1 ? points[points.length - 1].t - points[0].t : 0;
+    const gaps: number[] = [];
+    for (let i = 1; i < points.length; i++) gaps.push(points[i].t - points[i - 1].t);
+    const sortedGaps = [...gaps].sort((a, b) => a - b);
+    const medianGap = sortedGaps[Math.floor(sortedGaps.length / 2)] ?? 0;
+    const droppedGaps = medianGap > 0 ? gaps.filter((g) => g > medianGap * 2).length : 0;
+    // spring fingerprint: how many times the curve crosses its settling value before the end
+    const last = vals[vals.length - 1];
+    let overshoots = 0;
+    for (let i = 1; i < vals.length - 1; i++) {
+        if ((vals[i - 1] - last) * (vals[i] - last) < 0) overshoots++;
+    }
+    const round = (v: number) => Math.round(v * 1000) / 1000;
+    return {
+        kind: "numeric" as const,
+        key,
+        count: points.length,
+        spanMs,
+        sampleHz: spanMs > 0 ? Math.round(((points.length - 1) / spanMs) * 1000) : 0,
+        first: round(vals[0]),
+        last: round(last),
+        min: round(Math.min(...vals)),
+        max: round(Math.max(...vals)),
+        medianGapMs: round(medianGap),
+        droppedGaps,
+        overshoots,
+        spark: sparkline(vals),
+    };
+}
+
+function paintCadence(gaps: number[]): string {
+    if (!gaps || gaps.length < 2) return "";
+    const sorted = [...gaps].sort((a, b) => a - b);
+    const median = sorted[Math.floor(sorted.length / 2)];
+    const p95 = sorted[Math.floor(sorted.length * 0.95)];
+    return ` (paint gap median ${median.toFixed(1)}ms, p95 ${p95.toFixed(1)}ms)`;
+}