Investigate on-device preview support (real iPhone/iPad)

[obj-p]

Explore whether PreviewsMCP can render previews on physical iOS devices, not just the simulator.

Core blocker

iOS prohibits dlopen of arbitrary unsigned code at runtime. The simulator doesn't have this restriction, which is why Xcode Previews only supports simulator too. Our entire preview pipeline depends on dlopen of compiled dylibs.

Approaches to investigate

1. Signed framework loading (most promising)
Can dlopen load a framework signed with the same team identity as the host app on a developer-mode device? If yes, the rest of the architecture (host app, touch injection, file communication) transfers directly. Compile preview as a .framework, sign with the dev cert, push to app's Frameworks/ directory.

2. JIT entitlement
Xcode's XCPreviewAgent uses a JIT executor to link .o files in-memory. The com.apple.security.cs.allow-jit entitlement enables this. Investigate whether a third-party app can use this entitlement on device (likely restricted to Apple-signed binaries).

3. Recompile + reinstall (slow but known-good)
Build the full app (host + preview) as a single binary each time. Sign and install via devicectl/ios-deploy. ~15-30s per iteration. No dlopen needed. Works on stock developer-mode devices.

4. Network rendering
Run compilation on Mac, render on Mac (simulator or in-process), stream frames to a companion app on device. Device is just a display. Different architecture but sidesteps all code signing issues.

What already works on device

• Touch injection (Hammer approach is in-process, same on device)
• Screenshots (devicectl or idb)
• File communication (push to app sandbox via USB/network)
• The host app pattern itself

Spike plan

1. Create a minimal iOS app with developer signing
2. At runtime, attempt to dlopen a .framework from the app's bundle that was NOT present at install time (pushed via devicectl after install)
3. Test on a developer-mode device
4. If it works: the path to on-device previews is clear
5. If not: evaluate approach 3 (recompile+reinstall) for viability

[obj-p]

Research Findings

Investigated all four approaches and compared with how Expo achieves real-device hot reload.

Why Expo can do this but we can't (today)

Expo separates the native shell (compiled once, installed once) from UI logic (JavaScript, sent as data over WiFi/USB, interpreted by JSC/Hermes). JavaScript isn't subject to code signing because it's interpreted data, not native executable code.

Swift doesn't have this luxury — SwiftUI views are compiled native code, and every dylib must be signed and present in the app bundle at install time.

Approach 1 (Signed dlopen) — Dead end

iOS requires all code to be present in the app bundle at install time and signed with the same team ID. Dyld verifies code signatures at dlopen time at the kernel level — not just an App Store review check. A framework pushed to the device after installation via devicectl device copy would fail code signature validation. Multiple sources confirm this:

• Apple Forums: Code signing of dylib for use under iOS
• Apple Forums: dlopen fails after app is signed
• iOS runtime loading dynamic framework — works only because frameworks are bundled and signed at build time

The spike plan (push framework post-install, attempt dlopen) is still worth running to definitively confirm, but all evidence points to failure.

Approach 2 (JIT entitlement) — Dead end

com.apple.security.cs.allow-jit is restricted to Apple-signed binaries. Third-party apps cannot use it on device.

Approach 3 (Recompile + reinstall) — Viable but slow

xcrun devicectl device install app works on iOS 17+ real devices. Cycle would be: recompile full app with preview baked in (no dlopen needed) → sign → install via devicectl. Realistic cycle time: 10-20s with aggressive caching, vs <1s for our current simulator dlopen path.

devicectl device copy supports pushing files to appDataContainer, so our file-based IPC (touch-signal.json, elements-request.json, etc.) could transfer as-is. Touch injection (Hammer approach) is in-process and works the same on device.

Main issue: the iteration speed makes this impractical for the rapid feedback loop that previews are meant to provide.

Approach 4 (Network rendering) — Best UX, but not truly on-device

Compile and render on Mac (simulator or in-process), stream frames to a thin viewer app on the real device. Device provides real touch input, Mac does all compilation and rendering. Sub-second updates, no reinstall per change. Complements #19 (screen streaming).

Downside: not actually running on real hardware, so you don't get real device performance characteristics or device-specific behavior.

Conclusion

Not feasible today for true on-device rendering with a fast feedback loop. The fundamental blocker is that iOS enforces code signing for all executable code, and Swift/SwiftUI compiles to native code (unlike JS which is interpreted data).

The only other avenue worth exploring would be a server-driven UI approach — exposing UI primitives that get sent as data (like a layout DSL) to a pre-installed renderer app on device. But that's a fundamentally different architecture and a much larger scope.

For now, simulator remains the right target for iOS previews.