Module surface_capture 

Persistent CoreSimulator framebuffer capture via a resident smix-capture-host. See surface_capture::SurfaceCaptureHost. Persistent CoreSimulator framebuffer capture via a resident per-sim smix-capture-host process in request-response (“serve”) mode.

The per-shot xcrun simctl io <udid> screenshot path pays a ~74 ms process-spawn + dyld floor and a ~66 ms PNG encode every shot (see docs/perf/v2.8-c3-screenshot-decomposition.md). This module holds one resident host per booted UDID that resolves the display IOSurface once (~58 ms, amortized) and then answers each capture request by locking + copying the framebuffer directly — ~0.3 ms for a raw BGRA frame, ~66 ms for an in-host ImageIO PNG encode, with no per-shot process spawn.

Correctness: the host revalidates the surface on every grab (re-fetches the device’s current framebufferSurface and adopts it if the sim rebooted and vended a new one). If the surface can no longer be resolved (sim shut down, framework layout changed) the host answers with a surface-unavailable status and exits, and the caller falls back to the xcrun simctl io screenshot path. A stale/garbage frame is never returned.

Wire protocol (host serve mode):

• host emits <W>x<H>\n on stderr once, then loops.
• request: one opcode byte on stdin — [OP_RAW] (raw BGRA) or [OP_PNG] (ImageIO PNG). EOF ends the host.
• response: one status byte — [STATUS_OK] or [STATUS_UNAVAILABLE]. On OK, followed by a 12-byte header w:u32 h:u32 len:u32 (little endian) then len payload bytes. On UNAVAILABLE the host exits.

Structs

CaptureHostRegistry

Per-UDID resident-host registry. Held behind an async mutex inside SimctlClient.

FrameHeader

Parsed w:u32 h:u32 len:u32 little-endian frame header.

SurfaceCaptureHost

A resident smix-capture-host in serve mode for one booted UDID.

Enums

CapturedFrame

A captured frame — either raw BGRA pixels (the fast diff-loop path) or a PNG (the file-save path, or the simctl fallback which is always PNG).

HostError

Why a resident-host capture could not be produced. Every variant means “fall back to simctl”, but they are distinguished for diagnostics.

Constants

OP_PNG

Opcode: grab an in-host ImageIO-encoded PNG frame.

OP_RAW

Opcode: grab a raw BGRA frame (row padding stripped).

STATUS_OK

Response status: an w/h/len header + payload follow.

STATUS_UNAVAILABLE

Response status: the surface could not be resolved; the host is exiting and the caller must fall back to simctl.

Functions

capture_host_bin

Locate the smix-capture-host binary the same way the /live pipeline does: honor SMIX_CAPTURE_HOST_BIN, else the in-repo release build path.

parse_geometry_line

Parse a WxH\n geometry line.