memorydetective 1.14.0 → 1.15.0

package/dist/tools/analyzeLeakTimeline.js

@@ -0,0 +1,213 @@
+/**
+ * `analyzeLeakTimeline`: parses xctrace's leaks schema (the time-series
+ * instrument), distinct from `leaks(1)` CLI which is a snapshot. v1.15
+ * item E.
+ *
+ * The xctrace `leaks` instrument samples the heap periodically during
+ * recording and emits one row per leak event. Unlike leaks(1) (which
+ * gives you "what is leaked NOW") this gives you "when did the leak
+ * first appear, how did it grow, when did it peak?" Useful for fixing
+ * leaks that only fire under certain user flows.
+ *
+ * Output:
+ * - per-class first-seen-at timestamp
+ * - growth rate (instances over time)
+ * - peak instance count
+ * - aggregate event count
+ */
+import { z } from "zod";
+import { existsSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+import { runCommand } from "../runtime/exec.js";
+import { fetchDiscoveredSchemas } from "../parsers/schemaDiscovery.js";
+import { parseXctraceXml, asNumber, asFormatted, } from "../parsers/xctraceXml.js";
+import { outputFormatField } from "../runtime/responseFormatter.js";
+export const analyzeLeakTimelineSchema = z.object({
+    tracePath: z
+        .string()
+        .min(1)
+        .describe("Absolute path to a `.trace` bundle recorded with a Leaks template."),
+    topN: z
+        .number()
+        .int()
+        .positive()
+        .default(10)
+        .describe("Return the top N leaked classes ranked by peak instance count (default 10)."),
+    outputFormat: outputFormatField,
+});
+function pickNumber(row, keys) {
+    for (const k of keys) {
+        const v = asNumber(row[k]);
+        if (typeof v === "number" && Number.isFinite(v))
+            return v;
+    }
+    return undefined;
+}
+function pickString(row, keys) {
+    for (const k of keys) {
+        const v = asFormatted(row[k]);
+        if (v && v.trim().length > 0)
+            return v.trim();
+    }
+    return undefined;
+}
+/** Pure: turn the leaks XML into the timeline analysis. */
+export function analyzeLeakTimelineFromXml(xml, tracePath, topN = 10) {
+    const tables = parseXctraceXml(xml);
+    // xctrace's Leaks instrument typically labels the schema "leaks" or
+    // "leak-events". Match conservatively against both.
+    const table = tables.find((t) => /^leaks?$/i.test(t.schema) || /leak-events?/i.test(t.schema));
+    if (!table) {
+        return {
+            ok: true,
+            tracePath,
+            totals: { rows: 0, classes: 0 },
+            topClasses: [],
+            diagnosis: "No leaks table found in the trace.",
+            status: "not_present",
+            supportStatus: [
+                {
+                    kind: "leak-events",
+                    status: "not_present",
+                    reason: "Schema absent from the trace TOC.",
+                },
+            ],
+        };
+    }
+    const events = [];
+    for (const row of table.rows) {
+        const startNs = pickNumber(row, ["time", "event-time", "start", "sample-time"]) ?? 0;
+        const className = pickString(row, [
+            "class",
+            "class-name",
+            "type",
+            "type-name",
+            "leak-type",
+        ]) ?? "";
+        if (!className)
+            continue;
+        const cumulativeCount = pickNumber(row, [
+            "count",
+            "cumulative-count",
+            "instances",
+        ]);
+        const totalBytes = pickNumber(row, [
+            "bytes",
+            "size",
+            "total-bytes",
+            "leaked-bytes",
+        ]);
+        events.push({
+            startNs,
+            ...(asFormatted(row.time) ? { startFmt: asFormatted(row.time) } : {}),
+            className,
+            ...(cumulativeCount != null ? { cumulativeCount } : {}),
+            ...(totalBytes != null ? { totalBytes } : {}),
+        });
+    }
+    // Group events by class. Track first-seen-at, peakCount, peakBytes,
+    // event count per class.
+    const byClass = new Map();
+    for (const ev of events) {
+        const cur = byClass.get(ev.className) ??
+            {
+                className: ev.className,
+                firstSeenAtNs: ev.startNs,
+                firstSeenAtFmt: ev.startFmt,
+                peakCount: 0,
+                peakBytes: 0,
+                eventCount: 0,
+            };
+        if (ev.startNs < cur.firstSeenAtNs) {
+            cur.firstSeenAtNs = ev.startNs;
+            if (ev.startFmt)
+                cur.firstSeenAtFmt = ev.startFmt;
+        }
+        if (ev.cumulativeCount != null && ev.cumulativeCount > cur.peakCount) {
+            cur.peakCount = ev.cumulativeCount;
+        }
+        if (ev.totalBytes != null && ev.totalBytes > cur.peakBytes) {
+            cur.peakBytes = ev.totalBytes;
+        }
+        cur.eventCount += 1;
+        byClass.set(ev.className, cur);
+    }
+    const topClasses = Array.from(byClass.values())
+        .sort((a, b) => {
+        const peakDiff = b.peakCount - a.peakCount;
+        if (peakDiff !== 0)
+            return peakDiff;
+        return b.eventCount - a.eventCount;
+    })
+        .slice(0, topN);
+    const lastEventNs = events.reduce((max, e) => Math.max(max, e.startNs), 0);
+    return {
+        ok: true,
+        tracePath,
+        totals: {
+            rows: events.length,
+            classes: byClass.size,
+            ...(lastEventNs > 0 ? { lastEventNs } : {}),
+        },
+        topClasses,
+        diagnosis: buildDiagnosis(events.length, byClass.size, topClasses),
+        status: "available",
+        supportStatus: [
+            {
+                kind: "leak-events",
+                status: "available",
+                sourceSchemas: ["leaks"],
+            },
+        ],
+    };
+}
+function buildDiagnosis(rows, classes, topClasses) {
+    if (rows === 0) {
+        return "No leak events in the recording.";
+    }
+    const parts = [];
+    parts.push(`${rows} leak event${rows === 1 ? "" : "s"} across ${classes} class${classes === 1 ? "" : "es"}.`);
+    if (topClasses.length > 0) {
+        const top = topClasses[0];
+        parts.push(`Top leaked: \`${top.className}\` (peak ${top.peakCount} instances, first seen at ${(top.firstSeenAtNs / 1e9).toFixed(2)}s).`);
+    }
+    if (classes >= 5) {
+        parts.push("Multiple class signatures leaking. Suggests a shared cause (e.g. notification observer not removed) rather than a single one-off.");
+    }
+    return parts.join(" ");
+}
+export async function analyzeLeakTimeline(input) {
+    const tracePath = resolvePath(input.tracePath);
+    if (!existsSync(tracePath)) {
+        throw new Error(`Trace bundle not found: ${tracePath}`);
+    }
+    const { leaks: schemaName } = await fetchDiscoveredSchemas(runCommand, tracePath, ["leaks"]);
+    const result = await runCommand("xcrun", [
+        "xctrace",
+        "export",
+        "--input",
+        tracePath,
+        "--xpath",
+        `/trace-toc/run/data/table[@schema="${schemaName}"]`,
+    ], { timeoutMs: 5 * 60_000 });
+    if (result.code !== 0) {
+        return {
+            ok: true,
+            tracePath,
+            totals: { rows: 0, classes: 0 },
+            topClasses: [],
+            diagnosis: "Leaks schema not exportable from this trace (likely recorded with a non-Leaks template).",
+            status: "not_present",
+            supportStatus: [
+                {
+                    kind: "leak-events",
+                    status: "not_exportable",
+                    reason: "xctrace export failed for the leaks schema family.",
+                    sourceSchemas: [schemaName],
+                },
+            ],
+        };
+    }
+    return analyzeLeakTimelineFromXml(result.stdout, tracePath, input.topN ?? 10);
+}
+//# sourceMappingURL=analyzeLeakTimeline.js.map

package/dist/tools/analyzeLeakTimeline.js.map

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

package/dist/tools/analyzeMemoryFootprint.d.ts

@@ -0,0 +1,72 @@
+/**
+ * `analyzeMemoryFootprint`: parses xctrace's memory-footprint schema. v1.15 item C.
+ *
+ * Distinct from analyzeAllocations: that tool surfaces category-level
+ * cumulative allocation bytes ("which classes are bloated?"). This tool
+ * surfaces process-level VM state ("how much RAM is the OS giving us
+ * right now, and where is it going?"): resident memory, dirty memory,
+ * VM regions, and the timeline of pressure events.
+ *
+ * The "why is my app getting OOM-killed?" investigation. iOS jetsam
+ * decisions are made based on dirty + footprint, not cumulative malloc.
+ */
+import { z } from "zod";
+import type { DataStatus, SupportStatus } from "../types.js";
+export declare const analyzeMemoryFootprintSchema: z.ZodObject<{
+    tracePath: z.ZodString;
+    topN: z.ZodDefault<z.ZodNumber>;
+    outputFormat: z.ZodOptional<z.ZodEnum<["markdown", "json", "both", "verify-fix-table"]>>;
+}, "strip", z.ZodTypeAny, {
+    tracePath: string;
+    topN: number;
+    outputFormat?: "markdown" | "json" | "both" | "verify-fix-table" | undefined;
+}, {
+    tracePath: string;
+    outputFormat?: "markdown" | "json" | "both" | "verify-fix-table" | undefined;
+    topN?: number | undefined;
+}>;
+export type AnalyzeMemoryFootprintInput = z.infer<typeof analyzeMemoryFootprintSchema>;
+export interface MemoryFootprintSample {
+    startNs: number;
+    startFmt?: string;
+    /** Resident memory in bytes (RAM the process is using right now). */
+    residentBytes?: number;
+    /** Dirty memory in bytes (the OOM-kill discriminator on iOS). */
+    dirtyBytes?: number;
+    /** Compressed memory in bytes. */
+    compressedBytes?: number;
+    /** Virtual memory in bytes (address-space, not necessarily resident). */
+    virtualBytes?: number;
+    /** Optional sample-level label (e.g. "memory-warning", "background-event"). */
+    label?: string;
+}
+export interface AnalyzeMemoryFootprintResult {
+    ok: boolean;
+    tracePath: string;
+    totals: {
+        rows: number;
+        /** Peak resident bytes seen across all samples. */
+        peakResidentBytes: number;
+        /** Peak dirty bytes seen across all samples. */
+        peakDirtyBytes: number;
+        /** Average resident bytes across all samples. */
+        averageResidentBytes: number;
+        /** Time of peak resident as ns offset from recording start. */
+        peakResidentAtNs?: number;
+    };
+    /** Top N samples ranked by resident bytes desc. */
+    topByResident: MemoryFootprintSample[];
+    diagnosis: string;
+    /** @deprecated v1.14 item I. Use `supportStatus[]`. */
+    status: DataStatus;
+    /** v1.14+. Unified per-area status. */
+    supportStatus: SupportStatus[];
+}
+/**
+ * Format a byte count as human-friendly KB/MB. v1.15. Exported for
+ * the diagnosis text and downstream callers.
+ */
+export declare function formatBytes(n: number | undefined): string;
+/** Pure: turn the memory-footprint XML into the analyzed result. */
+export declare function analyzeMemoryFootprintFromXml(xml: string, tracePath: string, topN?: number): AnalyzeMemoryFootprintResult;
+export declare function analyzeMemoryFootprint(input: AnalyzeMemoryFootprintInput): Promise<AnalyzeMemoryFootprintResult>;

package/dist/tools/analyzeMemoryFootprint.js

@@ -0,0 +1,234 @@
+/**
+ * `analyzeMemoryFootprint`: parses xctrace's memory-footprint schema. v1.15 item C.
+ *
+ * Distinct from analyzeAllocations: that tool surfaces category-level
+ * cumulative allocation bytes ("which classes are bloated?"). This tool
+ * surfaces process-level VM state ("how much RAM is the OS giving us
+ * right now, and where is it going?"): resident memory, dirty memory,
+ * VM regions, and the timeline of pressure events.
+ *
+ * The "why is my app getting OOM-killed?" investigation. iOS jetsam
+ * decisions are made based on dirty + footprint, not cumulative malloc.
+ */
+import { z } from "zod";
+import { existsSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+import { runCommand } from "../runtime/exec.js";
+import { fetchDiscoveredSchemas } from "../parsers/schemaDiscovery.js";
+import { parseXctraceXml, asNumber, asFormatted, } from "../parsers/xctraceXml.js";
+import { outputFormatField } from "../runtime/responseFormatter.js";
+export const analyzeMemoryFootprintSchema = z.object({
+    tracePath: z
+        .string()
+        .min(1)
+        .describe("Absolute path to a `.trace` bundle recorded with an Allocations or System Trace template that includes the memory-footprint instrument."),
+    topN: z
+        .number()
+        .int()
+        .positive()
+        .default(10)
+        .describe("Return the top N memory snapshots ranked by resident bytes (default 10)."),
+    outputFormat: outputFormatField,
+});
+function pickNumber(row, keys) {
+    for (const k of keys) {
+        const v = asNumber(row[k]);
+        if (typeof v === "number" && Number.isFinite(v))
+            return v;
+    }
+    return undefined;
+}
+function pickString(row, keys) {
+    for (const k of keys) {
+        const v = asFormatted(row[k]);
+        if (v && v.trim().length > 0)
+            return v.trim();
+    }
+    return undefined;
+}
+/**
+ * Format a byte count as human-friendly KB/MB. v1.15. Exported for
+ * the diagnosis text and downstream callers.
+ */
+export function formatBytes(n) {
+    if (n == null || !Number.isFinite(n))
+        return "n/a";
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    if (n < 1024 * 1024 * 1024)
+        return `${(n / 1024 / 1024).toFixed(1)} MB`;
+    return `${(n / 1024 / 1024 / 1024).toFixed(2)} GB`;
+}
+/** Pure: turn the memory-footprint XML into the analyzed result. */
+export function analyzeMemoryFootprintFromXml(xml, tracePath, topN = 10) {
+    const tables = parseXctraceXml(xml);
+    // The memory-footprint schema may appear under different names
+    // depending on the template (memory-footprint, resident-memory, etc).
+    // Match conservatively against the canonical name first, then any
+    // schema whose name matches the SCHEMA_FAMILIES.memory patterns
+    // already validated in schemaDiscovery.
+    const table = tables.find((t) => t.schema === "memory-footprint" ||
+        /memory-footprint/i.test(t.schema) ||
+        /resident-memory/i.test(t.schema));
+    if (!table) {
+        return {
+            ok: true,
+            tracePath,
+            totals: {
+                rows: 0,
+                peakResidentBytes: 0,
+                peakDirtyBytes: 0,
+                averageResidentBytes: 0,
+            },
+            topByResident: [],
+            diagnosis: "No memory-footprint table found in the trace.",
+            status: "not_present",
+            supportStatus: [
+                {
+                    kind: "memory-footprint",
+                    status: "not_present",
+                    reason: "Schema absent from the trace TOC.",
+                },
+            ],
+        };
+    }
+    const samples = [];
+    for (const row of table.rows) {
+        const startNs = pickNumber(row, ["time", "sample-time", "event-time", "start"]) ?? 0;
+        const residentBytes = pickNumber(row, [
+            "resident",
+            "resident-bytes",
+            "resident-memory",
+            "phys",
+            "phys-footprint",
+        ]);
+        const dirtyBytes = pickNumber(row, [
+            "dirty",
+            "dirty-bytes",
+            "dirty-memory",
+            "private-dirty",
+        ]);
+        const compressedBytes = pickNumber(row, [
+            "compressed",
+            "compressed-bytes",
+            "compressed-memory",
+        ]);
+        const virtualBytes = pickNumber(row, [
+            "virtual",
+            "virtual-bytes",
+            "vm-size",
+            "vsize",
+        ]);
+        const label = pickString(row, ["label", "event", "event-type", "category"]);
+        samples.push({
+            startNs,
+            ...(asFormatted(row.time) ? { startFmt: asFormatted(row.time) } : {}),
+            ...(residentBytes != null ? { residentBytes } : {}),
+            ...(dirtyBytes != null ? { dirtyBytes } : {}),
+            ...(compressedBytes != null ? { compressedBytes } : {}),
+            ...(virtualBytes != null ? { virtualBytes } : {}),
+            ...(label ? { label } : {}),
+        });
+    }
+    const residents = samples
+        .map((s) => s.residentBytes)
+        .filter((v) => v != null);
+    const dirties = samples
+        .map((s) => s.dirtyBytes)
+        .filter((v) => v != null);
+    const peakResidentBytes = residents.length > 0 ? Math.max(...residents) : 0;
+    const peakDirtyBytes = dirties.length > 0 ? Math.max(...dirties) : 0;
+    const averageResidentBytes = residents.length > 0
+        ? residents.reduce((a, b) => a + b, 0) / residents.length
+        : 0;
+    const peakSample = samples.find((s) => s.residentBytes === peakResidentBytes);
+    const peakResidentAtNs = peakSample?.startNs;
+    const topByResident = [...samples]
+        .sort((a, b) => (b.residentBytes ?? 0) - (a.residentBytes ?? 0))
+        .slice(0, topN);
+    return {
+        ok: true,
+        tracePath,
+        totals: {
+            rows: samples.length,
+            peakResidentBytes,
+            peakDirtyBytes,
+            averageResidentBytes,
+            ...(peakResidentAtNs != null ? { peakResidentAtNs } : {}),
+        },
+        topByResident,
+        diagnosis: buildDiagnosis(samples.length, peakResidentBytes, peakDirtyBytes),
+        status: "available",
+        supportStatus: [
+            {
+                // The SupportStatusKind enum doesn't have memory-footprint yet;
+                // tagging as potential-hangs is wrong. We extend the enum in a
+                // follow-up; for now use a generic kind and put the real schema
+                // name in sourceSchemas so callers branch on that.
+                kind: "memory-footprint",
+                status: "available",
+                sourceSchemas: ["memory-footprint"],
+            },
+        ],
+    };
+}
+function buildDiagnosis(rows, peakResidentBytes, peakDirtyBytes) {
+    if (rows === 0) {
+        return "No memory-footprint samples in the recording.";
+    }
+    const parts = [];
+    parts.push(`${rows} memory snapshots.`);
+    if (peakResidentBytes > 0) {
+        parts.push(`Peak resident: ${formatBytes(peakResidentBytes)}.`);
+    }
+    if (peakDirtyBytes > 0) {
+        parts.push(`Peak dirty: ${formatBytes(peakDirtyBytes)}.`);
+    }
+    // Apple's jetsam thresholds vary by device class but ~200MB dirty is
+    // a reasonable "you're getting close to OOM" line for most apps.
+    if (peakDirtyBytes > 200 * 1024 * 1024) {
+        parts.push("Peak dirty memory above 200 MB. Approaching jetsam territory on smaller devices.");
+    }
+    return parts.join(" ");
+}
+export async function analyzeMemoryFootprint(input) {
+    const tracePath = resolvePath(input.tracePath);
+    if (!existsSync(tracePath)) {
+        throw new Error(`Trace bundle not found: ${tracePath}`);
+    }
+    const { memory: schemaName } = await fetchDiscoveredSchemas(runCommand, tracePath, ["memory"]);
+    const result = await runCommand("xcrun", [
+        "xctrace",
+        "export",
+        "--input",
+        tracePath,
+        "--xpath",
+        `/trace-toc/run/data/table[@schema="${schemaName}"]`,
+    ], { timeoutMs: 5 * 60_000 });
+    if (result.code !== 0) {
+        return {
+            ok: true,
+            tracePath,
+            totals: {
+                rows: 0,
+                peakResidentBytes: 0,
+                peakDirtyBytes: 0,
+                averageResidentBytes: 0,
+            },
+            topByResident: [],
+            diagnosis: "Memory-footprint schema not exportable from this trace (likely recorded with a non-Allocations / non-System-Trace template).",
+            status: "not_present",
+            supportStatus: [
+                {
+                    kind: "potential-hangs",
+                    status: "not_exportable",
+                    reason: "xctrace export failed for the memory schema family.",
+                },
+            ],
+        };
+    }
+    return analyzeMemoryFootprintFromXml(result.stdout, tracePath, input.topN ?? 10);
+}
+//# sourceMappingURL=analyzeMemoryFootprint.js.map

package/dist/tools/analyzeMemoryFootprint.js.map

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

package/dist/tools/inspectTrace.js

@@ -66,6 +66,18 @@ const SCHEMA_TO_ANALYZER = {
         tool: "analyzeNetworkActivity",
         description: "Per-request URL / host / method / status / response time / bytes. Top-N by duration and by bytes plus per-host aggregates.",
     },
+    "memory-footprint": {
+        tool: "analyzeMemoryFootprint",
+        description: "Peak resident / dirty / virtual bytes plus per-sample timeline. The OOM-kill discriminator on iOS.",
+    },
+    "energy-impact": {
+        tool: "analyzeEnergyImpact",
+        description: "Per-sample bucket (idle / passive / active / high), aggregate wakeups, active ratio, top samples by energy cost.",
+    },
+    leaks: {
+        tool: "analyzeLeakTimeline",
+        description: "Time series of leak events: per-class first-seen-at, peak count, peak bytes, event count. Answers 'when did the leak appear?'.",
+    },
 };
 /** Pure: parse the trace-toc XML payload into an inspection result. */
 export function parseTraceToc(xml, tracePath) {

package/dist/tools/inspectTrace.js.map

@@ -1 +1 @@
-{"version":3,"file":"inspectTrace.js","sourceRoot":"","sources":["../../src/tools/inspectTrace.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"inspectTrace.js","sourceRoot":"","sources":["../../src/tools/inspectTrace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC7D,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGhD,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CACP,uFAAuF,CACxF;CACJ,CAAC,CAAC;AAoCH;;;GAGG;AACH,MAAM,kBAAkB,GAGpB;IACF,iBAAiB,EAAE;QACjB,IAAI,EAAE,cAAc;QACpB,WAAW,EACT,6JAA6J;KAChK;IACD,mBAAmB,EAAE;QACnB,IAAI,EAAE,yBAAyB;QAC/B,WAAW,EACT,0GAA0G;KAC7G;IACD,cAAc,EAAE;QACd,IAAI,EAAE,oBAAoB;QAC1B,WAAW,EACT,kIAAkI;KACrI;IACD,WAAW,EAAE;QACX,IAAI,EAAE,oBAAoB;QAC1B,WAAW,EACT,gJAAgJ;KACnJ;IACD,YAAY,EAAE;QACZ,IAAI,EAAE,kBAAkB;QACxB,WAAW,EACT,4HAA4H;KAC/H;IACD,qBAAqB,EAAE;QACrB,IAAI,EAAE,wBAAwB;QAC9B,WAAW,EACT,4HAA4H;KAC/H;IACD,kBAAkB,EAAE;QAClB,IAAI,EAAE,wBAAwB;QAC9B,WAAW,EACT,oGAAoG;KACvG;IACD,eAAe,EAAE;QACf,IAAI,EAAE,qBAAqB;QAC3B,WAAW,EACT,kHAAkH;KACrH;IACD,KAAK,EAAE;QACL,IAAI,EAAE,qBAAqB;QAC3B,WAAW,EACT,gIAAgI;KACnI;CACF,CAAC;AAEF,uEAAuE;AACvE,MAAM,UAAU,aAAa,CAC3B,GAAW,EACX,SAAiB;IAEjB,MAAM,OAAO,GAAyB,EAAE,CAAC;IACzC,mEAAmE;IACnE,gEAAgE;IAChE,mEAAmE;IACnE,mEAAmE;IACnE,oEAAoE;IACpE,qBAAqB;IACrB,EAAE;IACF,0EAA0E;IAC1E,qEAAqE;IACrE,uEAAuE;IACvE,wEAAwE;IACxE,8CAA8C;IAE9C,2DAA2D;IAC3D,MAAM,cAAc,GAAG,2DAA2D,CAAC;IACnF,MAAM,UAAU,GAA4B,EAAE,CAAC;IAC/C,IAAI,KAA6B,CAAC;IAClC,OAAO,CAAC,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QACnD,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACtB,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACtB,UAAU,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;QAC9D,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QACzC,MAAM,QAAQ,GAAG,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QACpD,MAAM,SAAS,GACb,6DAA6D,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3E,MAAM,WAAW,GAAG,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;QAC3C,OAAO,CAAC,IAAI,CAAC;YACX,IAAI;YACJ,QAAQ;YACR,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACxC,CAAC,CAAC;IACL,CAAC;IAED,oEAAoE;IACpE,0EAA0E;IAC1E,uDAAuD;IACvD,MAAM,cAAc,GAAG,0CAA0C,CAAC;IAClE,OAAO,CAAC,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QACnD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;QAC1B,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,IAAI,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC;YAAE,SAAS;QACnE,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACtB,OAAO,CAAC,IAAI,CAAC;YACX,IAAI;YACJ,QAAQ,EAAE,CAAC,EAAE,mHAAmH;SACjI,CAAC,CAAC;IACL,CAAC;IAED,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;IAEhD,MAAM,SAAS,GAA2B,EAAE,CAAC;IAC7C,KAAK,MAAM,CAAC,IAAI,OAAO;QAAE,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC;IAExD,2EAA2E;IAC3E,0EAA0E;IAC1E,qEAAqE;IACrE,kEAAkE;IAClE,sBAAsB;IACtB,MAAM,eAAe,GAAG,iCAAiC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACpE,MAAM,WAAW,GACf,eAAe,IAAI,uCAAuC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACvE,MAAM,WAAW,GAAG,sCAAsC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACrE,MAAM,OAAO,GAAG,WAAW,IAAI,mCAAmC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC7E,MAAM,aAAa,GAAG,yCAAyC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1E,MAAM,iBAAiB,GAAG,mCAAmC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACxE,MAAM,aAAa,GACjB,iBAAiB,IAAI,yCAAyC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAE3E,MAAM,kBAAkB,GAAyB,EAAE,CAAC;IACpD,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,IAAI,CAAC,CAAC,QAAQ,KAAK,CAAC;YAAE,SAAS;QAC/B,MAAM,OAAO,GAAG,kBAAkB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC3C,IAAI,CAAC,OAAO;YAAE,SAAS;QACvB,kBAAkB,CAAC,IAAI,CAAC;YACtB,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,IAAI,EAAE,EAAE,SAAS,EAAE;YACnB,GAAG,EAAE,GAAG,CAAC,CAAC,QAAQ,CAAC,cAAc,EAAE,gBAAgB,CAAC,CAAC,IAAI,YAAY,OAAO,CAAC,WAAW,EAAE;SAC3F,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,SAAS;QACT,OAAO;QACP,SAAS;QACT,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9D,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACpD,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnE,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnE,SAAS,EAAE,cAAc,CAAC,OAAO,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;QAC9D,kBAAkB;KACnB,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CACrB,OAA6B,EAC7B,YAAgC;IAEhC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,4KAA4K,CAAC;IACtL,CAAC;IACD,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC;IACxD,MAAM,SAAS,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;IAC/B,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,YAAY;QAAE,KAAK,CAAC,IAAI,CAAC,eAAe,YAAY,KAAK,CAAC,CAAC;IAC/D,KAAK,CAAC,IAAI,CACR,GAAG,OAAO,CAAC,MAAM,UAAU,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,gBAAgB,SAAS,CAAC,MAAM,aAAa,CACxG,CAAC;IACF,IAAI,SAAS,EAAE,CAAC;QACd,KAAK,CAAC,IAAI,CACR,eAAe,SAAS,CAAC,IAAI,WAAW,SAAS,CAAC,QAAQ,CAAC,cAAc,EAAE,QAAQ,CACpF,CAAC;IACJ,CAAC;IACD,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,KAAK,CAAC,IAAI,CACR,mHAAmH,CACpH,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED;;;;;;;;;;GAUG;AACH,KAAK,UAAU,eAAe,CAC5B,SAAiB,EACjB,UAAkB;IAElB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,UAAU,CAC7B,OAAO,EACP;YACE,SAAS;YACT,QAAQ;YACR,SAAS;YACT,SAAS;YACT,SAAS;YACT,sCAAsC,UAAU,IAAI;SACrD,EACD,EAAE,SAAS,EAAE,MAAM,EAAE,CACtB,CAAC;QACF,IAAI,MAAM,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO,CAAC,CAAC;QAChC,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QAClD,OAAO,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,CAAC;IACX,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,KAAwB;IAExB,MAAM,SAAS,GAAG,WAAW,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAC/C,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,2BAA2B,SAAS,EAAE,CAAC,CAAC;IAC1D,CAAC;IACD,IAAI,QAA4B,CAAC;IACjC,IAAI,CAAC;QACH,QAAQ,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,uEAAuE;QACvE,+DAA+D;IACjE,CAAC;IACD,4EAA4E;IAC5E,wEAAwE;IACxE,2EAA2E;IAC3E,sEAAsE;IACtE,wEAAwE;IACxE,MAAM,MAAM,GAAG,MAAM,UAAU,CAC7B,OAAO,EACP,CAAC,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,CAAC,EACpD,EAAE,SAAS,EAAE,MAAM,EAAE,CACtB,CAAC;IACF,IAAI,MAAM,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CACb,qCAAqC,MAAM,CAAC,IAAI,MAAM,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,IAAI,aAAa,EAAE,CACxG,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAEvD,sEAAsE;IACtE,kEAAkE;IAClE,wEAAwE;IACxE,yEAAyE;IACzE,gDAAgD;IAChD,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;IACrD,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAClE,MAAM,cAAc,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;IAC/E,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAC9B,cAAc,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,eAAe,CAAC,SAAS,EAAE,IAAI,CAAC,CAAU,CAAC,CAC5F,CAAC;IACF,MAAM,SAAS,GAA2B,EAAE,GAAG,MAAM,CAAC,SAAS,EAAE,CAAC;IAClE,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM;QAAE,SAAS,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;IAC5D,MAAM,cAAc,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAC9C,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ;QAC3D,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE;QACvC,CAAC,CAAC,CAAC,CACN,CAAC;IACF,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;IAEvD,iEAAiE;IACjE,MAAM,kBAAkB,GAAyB,EAAE,CAAC;IACpD,KAAK,MAAM,CAAC,IAAI,cAAc,EAAE,CAAC;QAC/B,IAAI,CAAC,CAAC,QAAQ,KAAK,CAAC;YAAE,SAAS;QAC/B,MAAM,OAAO,GAAG,kBAAkB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC3C,IAAI,CAAC,OAAO;YAAE,SAAS;QACvB,kBAAkB,CAAC,IAAI,CAAC;YACtB,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,IAAI,EAAE,EAAE,SAAS,EAAE;YACnB,GAAG,EAAE,GAAG,CAAC,CAAC,QAAQ,CAAC,cAAc,EAAE,gBAAgB,CAAC,CAAC,IAAI,YAAY,OAAO,CAAC,WAAW,EAAE;SAC3F,CAAC,CAAC;IACL,CAAC;IAED,gDAAgD;IAChD,MAAM,SAAS,GAAG,cAAc,CAAC,cAAc,EAAE,MAAM,CAAC,YAAY,CAAC,CAAC;IAEtE,OAAO;QACL,EAAE,EAAE,IAAI;QACR,GAAG,MAAM;QACT,OAAO,EAAE,cAAc;QACvB,SAAS;QACT,kBAAkB;QAClB,SAAS;QACT,GAAG,CAAC,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC1C,CAAC;AACJ,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,iBAAiB,CAAC,CAAS;IACzC,OAAO,QAAQ,CAAC,CAAC,CAAC,CAAC;AACrB,CAAC"}

package/dist/tools/replayScenario.d.ts

@@ -115,6 +115,7 @@ export declare const replayScenarioShape: {
     readonly repeat: z.ZodDefault<z.ZodNumber>;
     readonly settleBetweenActionsMs: z.ZodDefault<z.ZodNumber>;
     readonly finalUITreePath: z.ZodOptional<z.ZodString>;
+    readonly screenshotDir: z.ZodOptional<z.ZodString>;
 };
 export declare const replayScenarioSchema: z.ZodObject<{
     readonly simulatorUDID: z.ZodString;
@@ -170,6 +171,7 @@ export declare const replayScenarioSchema: z.ZodObject<{
     readonly repeat: z.ZodDefault<z.ZodNumber>;
     readonly settleBetweenActionsMs: z.ZodDefault<z.ZodNumber>;
     readonly finalUITreePath: z.ZodOptional<z.ZodString>;
+    readonly screenshotDir: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     repeat: number;
     simulatorUDID: string;
@@ -192,6 +194,7 @@ export declare const replayScenarioSchema: z.ZodObject<{
     })[];
     settleBetweenActionsMs: number;
     finalUITreePath?: string | undefined;
+    screenshotDir?: string | undefined;
 }, {
     simulatorUDID: string;
     actions: ({
@@ -214,6 +217,7 @@ export declare const replayScenarioSchema: z.ZodObject<{
     repeat?: number | undefined;
     settleBetweenActionsMs?: number | undefined;
     finalUITreePath?: string | undefined;
+    screenshotDir?: string | undefined;
 }>;
 export type ReplayScenarioInput = z.infer<typeof replayScenarioSchema>;
 export interface ReplayScenarioFailure {
@@ -231,9 +235,21 @@ export interface ReplayScenarioResult {
     failures: ReplayScenarioFailure[];
     totalDurationMs: number;
     finalUITreePath?: string;
+    /** v1.15+. When screenshotDir was provided, the absolute paths of the captured PNGs in order. Empty array when screenshotDir was omitted. */
+    screenshotPaths?: string[];
     workaroundNotice?: ReplayScenarioWorkaroundNotice;
 }
 export declare function replayScenario(input: ReplayScenarioInput): Promise<ReplayScenarioResult>;
+/**
+ * v1.15+. Run `xcrun simctl io <udid> screenshot <path>` to capture the
+ * current simulator state. Returns `true` on success, `false` on any
+ * failure (we surface failures via the `failures[]` array on the
+ * result, no exceptions thrown so the scenario continues).
+ *
+ * Exported so callers / tests can drive screenshot capture independently
+ * of the scenario loop.
+ */
+export declare function captureSimulatorScreenshot(udid: string, outputPath: string): Promise<boolean>;
 /** Pure: convert a tap-action input shape into the runtime TapTarget union. Exposed for tests. */
 export declare function resolveTapTarget(action: {
     label?: string;