Screenmap

screenmap

Produce a visual map of an Expo / React Native or NativeScript app's navigation: every route as a card with a screenshot, runtime state variants (bottom sheets at each snap point, modals), and navigation edges between screens.

Arguments: optional path to the app project (default: current working directory). --static = skip the device phases and render a screenshot-less map. --platform ios|android|both (default ios) = which device(s) to capture on. pr <number> or diff <base>..<head> = PR diff mode (see bottom).

Working directory contract: all outputs go to <project>/.screenmap/out/ — graph.json, screens/*.png, flows/*.yaml + flows/*.meta.json, map.html. Suggest adding .screenmap/out/ to the project's .gitignore at the end.

Platform contract: with one platform, screenshots go to screens/<slug>.png as they always have. With --platform both, they go to screens/ios/<slug>.png and screens/android/<slug>.png, capture-status.json is keyed by platform first ({"android": {"<routeId>": …}}), and the bundle carries both so the viewer gets an iOS / Android switcher. Run the device phases once per platform, all the way through, before starting the next — never interleave them.

Device command table

Everything below that touches a device has a form per platform. <dev> is the iOS UDID or the Android serial (adb devices); with one device attached you can use booted on iOS and omit -s <dev> on Android.

Quote the Android deep link in single quotes: adb shell runs the string on the device, so an unquoted & in a query string backgrounds the command instead of passing it.

Flow recording (do this throughout Phases 4–5)

Every interaction sequence you perform is recorded as a replayable flow, written at the moment you perform it — not reconstructed afterwards. Flows use the argent flow format (argent.swmansion.com — Software Mansion's agentic mobile toolkit): a <name>.yaml argent flow plus a <name>.meta.json cartography sidecar, both in <project>/.screenmap/out/flows/. Anyone replays a flow headlessly, no LLM in the loop: npx @swmansion/argent flow run .screenmap/out/flows/<name>.yaml. Full pair schema: docs/scrmap-format.md in the skill repo.

# Open item details and expand the sheet to 50%
steps:
  - tool: open-url
    args:
      url: "myapp://details/42"
  - wait: 1500
  # Open sheet button
  - tap: { x: 0.4975, y: 0.4691 }
  - tool: gesture-swipe
    args: { fromX: 0.4975, fromY: 0.8009, toX: 0.4975, toY: 0.4828 }

{ "formatVersion": 2, "name": "details-sheet-50", "route": "details/[id]",
  "title": "Open item details and expand the sheet to 50%", "device": "iPhone 17 Pro",
  "steps": { "2": { "target": "Open sheet button" },
             "3": { "capture": "details_id--sheet-50.png", "note": "sheet at 50% snap" } } }

Rules:

• If the argent MCP is connected, record through it (flow-start-recording / flow-add-step): every step executes live, only successful steps are recorded, and taps get durable selectors instead of coordinates. Write the sidecar yourself alongside. Without argent, write the YAML directly using normalized 0–1 coordinates (device points ÷ device point-size).
• Sidecar steps is keyed by 0-based YAML step index. Every coordinate tap/swipe needs a target label (visible text or accessibility description). When a tap/swipe NAVIGATES to a different screen, set "screen": "<route id it landed on>" — this is how multi-screen flows stay traceable and observed edges get pinned. Screenshots are sidecar capture entries on the step they follow — never YAML steps.
• Add top-level "landmarks": ["Explore", "Trending"] — 2–5 words that are visible on the arrival screen and identify it (a title, a section header, a fixed button label; not live content). Headless replays in CI OCR the end screen and check these words to detect flow drift — without landmarks a drifted flow can only be caught heuristically.
• Simple deep-link visits from the sweep are flows too (generate them mechanically). Record dead ends you resolved with a note.
• Never record credentials; argent supports {{secret:NAME}} placeholders if input is unavoidable.

Phase 1 — static parse

node <this skill's dir>/scripts/parse-routes.mjs <project>

The parser picks a route provider for the project — expo-router, react-navigation, nativescript (Angular Router, Core XML pages, or the components an Octane / React / Vue / Svelte app mounts, pushes and presents), or a custom command — and prints which one it chose and why. See docs/route-providers.md for the full contract.

For a NativeScript project (mode is nativescript), read references/nativescript.md in this skill's directory now: deep links come from routes.links, there is no Metro, and it has its own state hints and PR-diff steps.

Read the produced <project>/.screenmap/out/graph.json and report the summary to the user: the provider (mode), route count, layouts (with navigator types), edges (flag unresolved ones), routes with state hints, routes needing params, and routes with no deep link (navigationOnlyRoutes).

If the parser exits saying no provider recognised the project, or that two fit equally well, do not guess. Show the user the detection table it printed and ask which to use, then re-run with --provider <id>:

node <this skill's dir>/scripts/parse-routes.mjs <project> --detect          # scores only
node <this skill's dir>/scripts/parse-routes.mjs <project> --provider react-navigation

A project whose screens are registered somewhere none of the providers read — a generated route table, a home-grown router — is not a dead end: write a small script that emits the graph fragment documented in docs/route-providers.md and point .screenmap/config.json at it with {"routes":{"provider":"custom","command":"…"}}.

If --static was requested, jump to Phase 6.

Phase 2 — plan params and auth

• For each route with params, pick a sample value: prefer concrete values found in resolved edges' raw hrefs (e.g. /details/42 → id=42), then seed/fixture data in the repo, else 1. Record the substitution you'll use in deep links.
• Skim the graph for routes that are likely auth-gated (segments like (auth), login, sign-in, or a root layout with a redirect). Expect those to redirect during the sweep; that's fine — capture what actually renders and mark it in your report.

Phase 3 — boot the app

Run this phase once per platform.

iOS

1. xcrun simctl list devices booted — check for a booted simulator.
2. Call the iOS simulator MCP attach action FIRST so the user can watch (harmless error if nothing is booted yet — boot/build, then retry attach).
3. Get the app running, preferring what already exists:
   • If Metro is already running and the app is open in the simulator, use it as-is.
   • Else start Metro in the background (npx expo start via background Bash from the project dir).
   • If a dev build of the app is installed on the simulator, launch it. If only Expo Go is available, open the project in it. If neither, npx expo run:ios (warn the user this builds and takes minutes), or fall back to web (see bottom).
4. Verify deep linking before sweeping. Open the root route with the scheme from graph.json:
   • dev build: xcrun simctl openurl booted "<scheme>://"
   • Expo Go: xcrun simctl openurl booted "exp://127.0.0.1:8081/--/" Take an MCP screenshot to confirm the app rendered (not a crash/error screen). Use whichever URL form worked for the rest of the run.

Android

There is no Android equivalent of the iOS simulator MCP, so the user watches the emulator window itself — say so rather than promising a live panel. The android-debugging skill, if available, covers adb troubleshooting in more depth.

1. adb devices -l — check for an attached device or a running emulator. If none, list AVDs with emulator -list-avds and start one in the background: emulator -avd <name> -no-snapshot -no-boot-anim &. If adb/emulator are not on PATH, they are under $ANDROID_HOME/platform-tools and $ANDROID_HOME/emulator.
2. Wait for the boot to finish — adb wait-for-device only waits for adb to see it, so poll until adb shell getprop sys.boot_completed returns 1, then dismiss the lock screen with adb shell input keyevent 82. Installing before that fails in ways that read as a broken APK.
3. adb reverse tcp:8081 tcp:8081. The emulator's localhost is the emulator; without the tunnel the app cannot reach Metro on the host and nothing will load. Redo it after any emulator restart.
4. Get the app running: start Metro in the background as above, then launch the installed dev build (adb shell monkey -p <pkg> -c android.intent.category.LAUNCHER 1). If no dev build is installed, npx expo run:android (warn the user this builds and takes minutes).
5. Verify deep linking before sweeping, same as iOS: adb shell am start -a android.intent.action.VIEW -d '<scheme>://', then screenshot to disk and look at it.

Phase 4 — route sweep

Routes with "reach": "navigation-only" have no deep link at all — normal for react-navigation screens that are absent from the linking config. Do not deep-link them and do not visit the app root in their place: that captures the home screen under the wrong route's name, which is exactly the kind of silent bad capture Phase 4b exists to catch. Skip them in this phase, record {"needsNavigation": true} for them in capture-status.json, and reach them by tapping in Phase 5b — their nav flow is their capture.

For each route with a URL (substituting params from Phase 2; for +not-found, deep-link a garbage path like /definitely-not-a-route):

1. Open the route's deep link (see the device command table).
2. Wait ~1–1.5s for the transition (MCP wait, or just sleep). Content screens that fetch over the network need 3–4s — a capture showing a spinner or loading skeleton means the wait was too short, not that the route is broken; the Phase 4b review catches these, and you re-capture with a longer wait.
3. Capture to disk at <project>/.screenmap/out/screens/<slug>.png (or screens/<platform>/<slug>.png when capturing both) — use the exact slug from graph.json; the renderer depends on this naming. (The iOS MCP screenshot is for your own eyes only; it doesn't save a file.)
4. Every few routes, sanity-check that you're capturing real screens — read a capture back with the Read tool, or on iOS take an MCP screenshot. If a route shows a red error screen, an error boundary, or redirected somewhere else, still keep the capture but note it for the final report.

Phase 4b — review and recover (do not skip)

Error boundaries stick: once a bad deep link crashes a screen, subsequent deep links may render into the same error boundary, silently poisoning every capture after it. So before delivering:

1. Render a draft map (Phase 6 commands) and look at it — it doubles as a contact sheet of all captures.

2. Classify every capture that isn't clearly the real screen, and write the verdicts to <project>/.screenmap/out/capture-status.json (the renderer badges them on the map):

   { "<routeId>": { "status": "not-found", "needsNavigation": true, "note": "why + what a future agent should do instead" } }

   Statuses: ok · empty-state · not-found · error-boundary · loading · auth-wall. Decide per capture:

   • Loading spinner/skeleton — wait was too short OR the param is synthetic. Re-capture with 3–4s; if still loading, the data doesn't exist → treat as not-found.
   • Not-found / empty "Oops" screen — your sample param doesn't resolve to real data. First try to find real params (public APIs, seed data, values seen in other captures — e.g. a real starter-pack rkey from the account's public profile). Only if no real value is obtainable, keep the capture, set needsNavigation: true, and say in the note how the screen is actually reached (opened from a shared link, requires user-owned data, etc.).
   • Genuine empty state — the screen rendered correctly but the account has no content (e.g. "Nothing saved yet"). That IS the screen; status empty-state, no needsNavigation. Don't confuse this with not-found.
   • Error boundary — the route can't render from a bare deep link at all (missing runtime params). Keep as finding, needsNavigation: true. Beware the poisoned tail: error boundaries stick, so captures taken after a crash may show the same stuck error — relaunch the app (xcrun simctl terminate booted <bundleId>, relaunch, wait for the bundle) and re-capture those.

3. Re-render after recovery.

Phase 5 — runtime states (the part static analysis can't see)

For each route whose stateHints is non-empty, deep-link to it again and:

bottom-sheet — Read the route's source file (file in graph.json) to find what opens the sheet (a button whose onPress calls ref.expand() / present(); some sheets are open by default — check the index prop). Take an MCP screenshot, locate the trigger, tap it. Then for each snap point in the hint (e.g. 25%, 50%, 90%):

• drag the sheet to that height: swipe from the sheet handle's current position to y ≈ screen_height × (1 − snap). Start the swipe well inside the screen — a start point within 4pt of an edge triggers an OS edge gesture instead.
• capture screens/<slug>--sheet-<value>.png (e.g. details_id--sheet-50.png — strip the %).

rn-modal — find and tap the trigger, capture screens/<slug>--modal.png, then dismiss (close button, tap outside, or just deep-link away).

router-modal — already captured as its own route in Phase 4; nothing extra needed.

Rules for this phase:

• Re-deep-link between routes to reset state; don't let one screen's leftover state bleed into the next capture.
• Never tap destructive or irreversible controls: delete, remove, sign out, purchase, send, submit. If a sheet can only be opened via such a control, skip it and note why.
• If you type into inputs to reach a state, use obviously fake data.
• A hint is advisory — if you can't find the trigger in 2–3 attempts, skip it and note it. Also: sheets defined in shared components aren't in the hints; if you see an obvious sheet/modal trigger while on a screen, capture it as a bonus state.
• The hint list is a work queue, not a suggestion box. Phase 5 is not done until every hinted route is either captured or explicitly skipped with a reason. End the phase with a coverage line — state hints: N routes · captured M · skipped K (list + why) — and carry it into the Phase 6 delivery report. A state pass that quietly processes 3 of 17 hints looks complete on the map and isn't; that silence has bitten before.