Mobile Preview

Mobile Preview opens a floating phone-sized window beside the chat that hosts your Expo project running on its own dev server. While the MiraBridge agent edits files, the preview hot-reloads. Runtime errors surface in the conversation with a one-click "Fix this" handoff that sends the error back to the agent.

Requirements#

Mobile Preview runs entirely on your machine. To enable it you need:

• A paid MiraBridge plan (PRO, PRO_PLUS, ULTRA, TEAM, or ENTERPRISE). The feature is gated client-side; the chat-side "Fix this" path remains gated server-side by the normal billing rules.
• Node.js installed and resolvable on your PATH.
• An existing Expo project in the workspace folder you opened in MiraBridge Desktop. Mobile Preview does not scaffold new projects in PR1.
• The Expo CLI installed inside the project: node_modules/.bin/expo must exist. The easiest way to get there is npm install (or pnpm install / yarn install) in the project root.

PR1 explicitly does not spawn npm install, npm i -g expo, or npx create-expo-app for you. You stay in control of which packages land on disk.

What MiraBridge detects#

When you open a workspace folder, MiraBridge runs a read-only setup probe and shows one of three states:

| Detected | What you see | | -------- | ------------ | | Expo project + workspace-local Expo CLI | "Mobile preview is ready" prompt above the chat composer. Click Open preview to spawn npx expo start --web and open the floating window. | | Expo project but the workspace-local CLI is missing | "Mobile preview needs setup" prompt. Copy the suggested cd … && npm install command into your terminal, run it, and the prompt switches to the ready state. | | No Expo project (or no package.json, or a Flutter / native iOS / native Android repo) | Nothing — the prompt stays hidden. Mobile Preview only surfaces for Expo. |

Supported project shapes (PR1)#

• ✅ Expo SDK 50 – 53, managed and bare workflows
• ✅ Expo monorepo (one detected candidate is auto-selected)
• ✅ React Native + Expo + Expo Router
• ⚠️ Bare React Native without Expo — detected but expo start will fail unless the project has its own Expo CLI
• 🚧 Flutter, native Swift, native Kotlin — not in PR1, planned for a future release
• 🚧 Snack / bundled-Node fallback for users without Node — planned for a future release

Inside the floating window#

Once preview is running, the floating window shows your app inside a minimalist phone outline. The toolbar offers:

• Device picker — iPhone 15 Pro, iPhone SE, Pixel 8, Galaxy S24, iPad mini, or custom. Only the viewport size changes; the underlying bundle stays the same.
• Reload — best-effort Metro hot reload via r. Falls back to Metro's own file watcher if the stdin pipe is unavailable.
• Restart — kills the Metro process tree and respawns on the same port.
• Clear cache — same as restart but with --clear so Metro drops its bundler cache.
• Console — shows stdout / stderr from the dev server.
• Always-on-top toggle — pins the preview window over MiraBridge.
• Close — closes the window. The Expo dev server is also stopped if MiraBridge owns it.

The painkiller loop#

Two integrations make Mobile Preview different from a passive iframe:

1. Agent write → preview reloads. When the agent finishes a Write / Edit / MultiEdit tool call inside the selected Expo project root, MiraBridge nudges Metro to reload immediately instead of waiting on the file watcher's debounce.
2. Preview error → conversation card. Runtime errors in the preview (TypeError, ReferenceError, etc.) are parsed from Metro's stderr stream and forwarded to the main MiraBridge window. A red card appears above the chat composer with the stacktrace and a Fix this → button that prefills the chat with the error context. You hit send manually, and the agent fixes it through its normal plan / cascade flow.

Limits and known gaps#

• Mobile Preview talks only to your local machine. There is no cloud render, no shared preview link, and no mobile-companion handoff yet.
• The plan-tier gate is a marketing gate, not a safety gate. Real billing enforcement happens at the chat-send step where the agent reaches a provider — Mobile Preview itself consumes no Gateway resources.
• The first time you spawn Metro on macOS or Windows, the OS may prompt for firewall access. Allow it for node / Node Helper.
• Apple Silicon machines need an arm64 Node install. Rosetta-only Node will fail to spawn with EBADARCH.

Troubleshooting#

| Symptom | Likely cause | What to do | | ------- | ------------ | ---------- | | Prompt never appears for a real Expo project | node_modules/.bin/expo missing | Run npm install in the project root | | Prompt never appears for a non-Expo mobile project | Flutter / native iOS / native Android | Not supported in PR1; track v2 backlog | | Floating window opens but iframe is blank | Metro still starting (30 – 60 s on first run) or firewall block | Wait for the "Web is waiting" stdout line, or check the OS firewall prompt | | Preview shows stale code | Hot reload missed an edit | Click Reload, or Restart if the JS state is wedged | | Reload button does nothing | Metro stdin pipe was closed | Fall back to Restart | | Error card never appears for a real crash | The stderr block did not match a known error header (TypeError, ReferenceError, SyntaxError, RangeError, URIError, EvalError, Error) | Surface the issue via the in-app feedback so the parser can be widened |

Where this fits in the MiraBridge surface map#

Mobile Preview is Desktop only. It does not exist in the VSCode extension or the Mobile companion app today. It runs entirely against the Tauri Rust runtime — no Gateway calls are made for the preview itself. The chat-side "Fix this" path uses the normal ai_chat_stream route, which means all the standard provider / billing / quota gates still apply.