feat: add iOS frame perf sampling

[thymikee]

Summary

Add iOS frame-health perf sampling via xctrace Animation Hitches for connected iOS devices.

Keep Apple CPU/memory metrics available when FPS is unsupported or fails, serialize Apple xctrace sampling to avoid recorder contention, and retry transient kperf lock failures seen on physical devices.

Touched-file count: 10. Scope stayed within Apple perf, session perf aggregation, tests, CLI help, and docs.

Validation

• pnpm format
• pnpm exec vitest run src/platforms/ios/tests/perf.test.ts src/daemon/handlers/tests/session-perf.test.ts src/tests/cli-perf.test.ts src/utils/tests/args.test.ts
• pnpm exec vitest run src/platforms/ios/tests/perf.test.ts src/daemon/handlers/tests/session.test.ts -t "perf samples Apple cpu and memory metrics on iOS simulator app sessions|perf samples Apple cpu and memory metrics on physical iOS devices|sampleApplePerfMetrics uses simctl spawn ps"
• pnpm exec vitest run src/platforms/ios/tests/perf.test.ts src/daemon/handlers/tests/session-perf.test.ts
• pnpm check:quick
• pnpm build
• pnpm test:smoke
• pnpm exec vitest run src/tests/client-metro-packaged.test.ts
• pnpm check:fallow --base origin/main
• Manual iOS simulator test app validation: Expo Go opened Agent Device Tester, snapshot confirmed UI, perf returned startup/cpu/memory and FPS unavailable as expected
• Manual physical iOS validation on thymikee-iphone / iPhone 17 Pro with RNCLI83: perf returned fps.available=true via xctrace-animation-hitches, refreshRateHz=120, totalFrameCount=159, droppedFramePercent=0, plus CPU/memory samples

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://callstackincubator.github.io/agent-device/pr-preview/pr-477/
Built to branch gh-pages at 2026-04-29 23:26 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 383cf217fa

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Select the app PID before recording Animation Hitches

The frame sampler unconditionally attaches xctrace to processes[0], but iOS bundles can have multiple running processes (main app plus extensions/helpers) and this list is not ordered by foreground relevance. When a helper PID appears first, the trace targets the wrong process and droppedFramePercent can silently under-report real UI hitches for the app session. Choose the main app executable PID (or another deterministic foreground PID) before building the --attach argument.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Treat display-info export as optional in frame sampling

The parser already models displayInfoXml as optional and can compute dropped-frame metrics without refresh-rate data, but capture currently fails the entire FPS metric if device-display-info export fails. This makes frame health unavailable on environments where that table is missing or intermittently fails to export, even when hitches and hitches-frame-lifetimes exported successfully. Make the display-info export/read path best-effort so core FPS data still returns.

Useful? React with 👍 / 👎.