Screen atlas

Someone who has built every screen themselves can still lose the shape of the whole app. The fix is not a diagram, because a diagram is drawn from memory and drifts. It is the real screens, in order, on one page.

What this produces: one self contained HTML file, grouped into flows, each step captioned with what that screen is for. It lives in the repo and is gitignored, because it is megabytes of screenshots that go stale the moment a screen changes.

The honesty rule, and it is the whole credibility of the thing. The images are real captures. The ORDER is written by hand from the navigation calls. Those are different claims and the page must say so on its face. Never describe a hand written sequence as a recorded journey.

1. Check the app has the seam, or stop here

This needs two things, and most apps have neither:

If the app has a smoke or end to end tier, it probably already has both, and the manifest is the one in that tier. Reuse it. Do not write a second list of screens: two lists disagree within a month, and the one nothing enforces is the one that rots.

If the app has neither, say so and offer to build the seam first. The see-it-work skill covers that, and it is a bigger job than the atlas.

2. Enumerate the screens

Read the manifest. Count what is reachable and what is deliberately skipped (anything needing a camera, a real purchase, or hardware a simulator lacks). Report both numbers. A catalogue that quietly omits the skipped ones is lying by a smaller amount than one that fakes them, but it is still lying.

3. Capture them

Drive the manifest, one screen per case: stop the app, launch it, wait until it is drawing, fire the seed, wait for the screen's anchor, screenshot.

Read references/capture-traps.md before writing any of this. Four traps are in there and every one of them produces a run of failures that look like broken screens and are not. The short version:

• A seed link fired before the router is listening is lost silently. Launch first, and wait long enough.
• A seed may be claimed once per process, so a run that does not restart between screens is refused with no error.
• An "optional" tap in a flow runner is not failure proof.
• The duration tells you which failure you have. Fast is the driver. The full timeout is the screen.

Two rules for the capture itself:

• Shoot only after the screen is confirmed. A screenshot taken before the anchor appears is a picture of a splash screen filed under a real screen's name, which is worse than a missing tile because nothing downstream can tell.
• A retry belongs here and not in the release gate. A gate that retries hides flake and stops being believed. A catalogue has the opposite priority: a missing tile for a healthy screen is the bad outcome.

4. Group them into flows

Trace the real navigation calls in the code. Do not invent the order from what seems sensible: in a real run of this, two inferred sequences were wrong, and tracing caught both.

For each flow write an id, a title, one line on what it is for, and the ordered steps. For each step, one line on what that screen is for.

Write it the way a person talks about the product. The step note is for someone thinking about the app, not reading the code. Say "the button in the bottom right corner", not the component name.

Record the screens that no flow reaches. Give them their own section with the reason, rather than dropping them. This is the most useful thing the atlas produces and the easiest to lose: a screen can render perfectly, pass its test, and be reachable by nothing. The first real run of this found three.

5. Build the page

One HTML file. Each flow is a block: title, summary, then a horizontally scrolling strip of phone frames in order, numbered, each captioned.

• Deduplicate the images. A screen can appear in several flows. Inlining it per frame pays for its bytes every time: one build spent 1.4MB on a single captured screen before this was fixed. One CSS rule per screen, referenced by class, pays once.
• Downscale. Around 640px wide at JPEG quality 72 is plenty for review and is roughly 75KB a screen.
• Numbering is earned here. A flow IS a sequence, so numbered steps encode something true. Do not number things that are not ordered.
• If it opens a larger view, give it three ways out: a visible close button, Escape, and a click outside the image. A full screen overlay with no exit is the single worst thing this page can do, and a plain display rule on a dialog element will paint one over the page from the moment it loads.

6. Gate it so it cannot rot

The atlas is a second list that can disagree with the app, so wire two checks into whatever the project runs before a commit:

• A flow naming a screen that no longer exists.
• A real screen that sits in no flow and is not recorded as having no entry point.

Then break it both ways and watch it go red. A check nobody has seen fail is not a check.

Neither of these can catch a step ORDER that has gone stale, which is the likelier rot. Say that in the file rather than implying the gate covers it.

Finishing

Tell the user where the file is and how to rebuild it. Give the counts: flows, screens, captured, skipped. Name anything the atlas found, especially screens nothing reaches.

Do not publish it anywhere the user did not ask for. It is a picture of every screen in an unreleased product, including developer tools and paywalls.