Grounded iOS-to-Web Harness: Evidence-Driven App Migration with Behavioral and Visual Verification
Turning an iOS app into a React web app is no longer the hard part. Modern coding agents can generate a convincing first version quickly. The hard part is answering three less glamorous questions: Did we discover every important screen and state? Did the generated app preserve the source behavior and data? Is the result actually close to the native UI, or does it merely look plausible? I built…
Grounded iOS-to-Web Harness is an experimental tool aimed at bridging the gap between iOS and React web applications. While modern coding agents can swiftly generate a basic version of a web app from an iOS source, ensuring completeness and fidelity remains a challenge. Grounded iOS-to-Web Harness addresses this by providing a grounding and verification layer to validate the migration process.
The tool treats the iOS source code, assets, and runtime states as the definitive truth, while the generated React web app is checked against this source using several methods. First, it identifies and reconciles source facts, including screens, UI states, actions, navigation outcomes, cross-screen flows, real data, asset origins, and the confidence in these facts. These facts are locked before any implementation begins to ensure consistency throughout the migration.
Next, the harness provides the coding agent with targeted context for each screen, reducing the risk of context drift without restricting the agent's ability to write the necessary React components, CSS, routing, and state management. The generated web app is then verified for completeness and accuracy. This verification process checks for missing states, blank routes, broken images, fabricated data, misleading background images, desktop layouts that escape the mobile shell, and any implementation details that do not align with the locked source facts. Coverage is measured as a combination of screens and states, rather than simply a list of routes.
Behavioral verification is performed using Playwright, which simulates real user interactions such as clicks, input, state changes, and cross-page journeys. These behaviors must refer back to the locked action facts to prevent the agent from agreeing on invented behaviors. Finally, the harness conducts critical-state visual regression by comparing iOS and web screenshots for the same state on the same canvas.
Pixelmatch, SSIM, regional diff, and saved comparison and diff images are used to identify and highlight discrepancies, with visual metrics guiding the triage process rather than being presented as a percentage of fidelity.
The repository contains a sanitized reference migration of an e-commerce app, with complete records of 19 screens, 28 states, 19 navigation contracts, 34 actions, and three cross-page Playwright journeys. It also includes 31 screen/state behavior checks and 10 critical visual states, achieving 41/41 passing Web checks and 40/40 Harness regression tests.
The final result only required human visual review, with six experimental visual states still recommended for review. The project remains experimental, with future work focusing on testing against additional iOS projects and calibrating the verification process to maximize its value. Feedback from those working on app modernization, UI migration, coding-agent evaluation, and visual regression is welcome.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
