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 to make those questions auditable.
🔗 GitHub: https://github.com/tiezhu0415/grounded-ios-to-web-harness
What it is
Grounded iOS-to-Web Harness is an experimental, lightweight grounding + verification layer for migrating iOS apps into complete, interactive, mobile-sized WebApps.
Claude Code remains the primary implementer. The Harness does not prescribe the React component tree, choose a state-management library, or replace the coding agent. Instead, it establishes source facts and verifies the result against evidence from the original app.
iOS source + Assets + code graph + runtime states
↓
locked source facts
↓
per-screen implementation context
↓
agent builds the React WebApp
↓
coverage + truth + behavior + critical VRT
↓
bounded repair, then human review
Why prompt-only migration is not enough
A prompt such as “convert this iOS app to React” can produce a good demo. But on longer tasks, an agent may miss screens, implement only one state, invent data or assets, choose navigation that differs from iOS, forget earlier facts, or optimize a screenshot while breaking real interaction.
This project treats the iOS source and Assets as the truth for content and behavior, while runtime screenshots provide evidence for what the result should look like.
The pipeline
1. Discover and reconcile source facts
Static source inspection, codebase-memory, and necessary iOS runtime exploration are combined into machine-readable facts for screens, UI states, actions, navigation outcomes, cross-screen flows, real data and asset origins, and source confidence.
Facts are locked before implementation. Important actions record preconditions, data effects, navigation effects, and visible feedback.
2. Give the agent small, relevant context
Instead of injecting the entire repository and every tool description into every prompt, the Harness creates a compact context for each screen. This reduces context drift without restricting how the agent writes React, CSS, routing, or state management.
3. Verify truth and coverage
The WebApp is checked for missing states, blank routes, broken images, fabricated data, screenshot-background cheating, desktop layouts escaping the mobile shell, and implementation evidence that does not match the locked facts.
Coverage is measured as Screen + State, not merely as a list of routes.
4. Verify behavior with Playwright
Playwright executes real clicks, input, state changes, and cross-page journeys. Expected behavior must refer back to locked action facts, preventing code and tests from agreeing on the same invented behavior.
5. Run critical-state visual regression
The Harness compares iOS and Web screenshots for the same state on the same canvas using:
- Pixelmatch for changed-pixel ratio;
- SSIM for structural similarity;
- regional diff to expose severe local defects;
- saved comparison and diff images for human review.
Visual metrics are used for triage, not marketed as a “fidelity percentage.” Thresholds remain experimental.
Reference evaluation
The repository contains a sanitized reference migration of an e-commerce app. The source iOS project is intentionally not included.
The checked-in evaluation records:
- 19 screens
- 28 states
- 19 navigation contracts
- 34 actions
- 3 cross-page Playwright journeys
- 31 screen/state behavior checks
- 10 critical visual states
- 41/41 Web checks passing
- 40/40 Harness regression tests passing
The final result was accepted after human visual review. Six experimental visual states were still routed to “review recommended,” and the repository reports that honestly rather than turning SSIM into a false product-quality claim.
Research inspiration, not paper reproduction
The design was informed by three recent research directions:
- Coherence Debt: keeping dependent facts available and consistent during long agentic tasks;
- WidgetGen: giving models selective text, color, layout, and asset evidence before UI generation;
- WebDesignIter: preserving design knowledge and validating local edits across repository-scale iterations.
The repository does not claim to reproduce these research systems. It borrows their highest-ROI ideas and implements a thin orchestration layer around codebase-memory, Playwright, Pixelmatch, SSIM, Tesseract, and iOS runtime evidence.
What this project is not
- not an iOS-to-React compiler;
- not a promise of pixel-perfect equivalence;
- not a general-purpose multi-agent workflow platform;
- not a replacement for human acceptance;
- not a benchmark result across many production apps—yet.
The current release is experimental. The next meaningful step is testing it against additional iOS projects and calibrating which facts, journeys, and visual states deliver the highest verification value.
If you work on app modernization, UI migration, coding-agent evaluation, or visual regression, I would love feedback.
⭐ Repository: https://github.com/tiezhu0415/grounded-ios-to-web-harness
Issues, experiments, and pull requests are welcome.
