Compare commits

..
Author SHA1 Message Date
Brent Vatne b9e0275a3a Release 0.19.7 2026-10-17 21:44:17 -07:00
Brent Vatne 3392f799f6 Test that report.comment.map reaches the comment the publish job renders
The integration review sets it and reads it back from report-input.json, which also shows the baseline cache still
hits with it set; the unreachable-screens review checks it is absent by default.
2026-10-17 21:44:17 -07:00
Brent Vatne 25df16d914 README: Compare at full width, Screens and the PR comment side by side
At a third of the column the Compare wipe's phone was too small to read.
2026-10-17 21:37:08 -07:00
Brent Vatne 068445c82b PR comment map: opt in with report.comment.map
The map of changed screens is off by default: on a large review it is more than most comments need. report.comment.map:
true turns it on; the capture recipe ignores report, so switching it keeps cached baselines.
2026-10-17 21:37:08 -07:00
Brent Vatne c24049c443 README: animated hero and Compare, a map of changed screens in the PR comment (#12) 2026-10-17 21:31:58 -07:00
Brent Vatne cefeb8059a Release 0.19.6 2026-10-17 20:44:52 -07:00
Brent Vatne 078902710b Capture iPhone Duo on EAS Simulator with eas simulator:control, for both controllers (#9)
Capture iPhone Duo on EAS Simulator with eas simulator:control, for both controllers

- eas-cli 25.2.0: app.approveUrlScheme after install, appearance.set for Argent on
  iOS EAS sessions, and springboard.restart as the last fold recovery step. The
  controller's own tools come first; these only fill what neither controller has.
- iPhone Duo on EAS: both controllers' folds are verified (Argent by its tree,
  agent-device by its screenshot) and recovered by restarting SpringBoard and
  folding again, once; never by stopping the session's tool-server.
- agent-device opens the app before folding on EAS, as it does locally.
- agent-device pinned to 0.21.29-nightly.20261018.74 for callstack/agent-device#3776,
  which stops @expo/ui sliders on a regular-width display from wedging its runner.
- A session EAS fails to start is replaced, up to five times within 30 minutes,
  with a growing wait, only when the failure is provably EAS's.
- doctor warns about Argent's single appearance only for Android EAS sessions.
2026-10-17 20:44:41 -07:00
Brent Vatne 46ff99aad1 Viewer: held keys repeat and glide, arrows enter the map, held modifiers show their keys, T and ⇧T (#10) 2026-10-17 18:52:55 -07:00
113 changed files with 2206 additions and 5151 deletions

No files matched your search

+43 -26
View File
@@ -3,29 +3,29 @@
Explore maps your app: a screenshot of every screen, connected by the taps between them. On each pull request it captures the screens the PR changes, before and after, on EAS Simulator, and posts a visual review. On your Mac it can also run on a local simulator.
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/readme-hero-dark.png">
<img alt="Explore's Map of a euxy pull request, zoomed in on the new About screen, marked Added among the modified Patterns screens, with its transitions highlighted and the Inspector open on it, shown as a window on a soft stage" src="docs/screenshots/readme-hero-light.png">
<source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/readme-hero-dark.svg">
<img alt="Explore's Map of a euxy pull request, animated: the screen cards appear row by row, the new About screen marked Added among the modified Patterns screens, the transitions between them wipe in, then a click selects About, its transitions light up and the Inspector slides in on it, shown as a window on a soft stage" src="docs/screenshots/readme-hero-light.svg">
</picture>
**See a real report:** [euxy](https://explore-example--euxy.expo.app/p/rfcoic27ccgnrmzgijubxkmuzmptcrva?platform=ios), a MIDI sequencer, reviewed by Explore. It is redeployed with the current Viewer on every merge to main.
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/readme-compare-dark.svg">
<img alt="The euxy Patterns screen wiping from its capture before the pull request to its capture after it: each pattern row's tempo moves out of the subtitle into its own column on the right, then the changed subtitles are outlined" src="docs/screenshots/readme-compare-light.svg">
</picture>
**Compare**: each changed screen before and after, with the changed regions outlined.
<table>
<tr>
<td width="33%" valign="top">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/readme-compare-dark.png">
<img width="100%" alt="The Compare view with the euxy Patterns screen's before and after captures side by side: each pattern row's tempo moved out of the subtitle into its own column on the right, the changed subtitles outlined in both" src="docs/screenshots/readme-compare-light.png">
</picture>
<strong>Compare</strong>: each changed screen before and after, with the changed regions outlined.
</td>
<td width="33%" valign="top">
<td width="50%" valign="top">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/readme-screens-dark.png">
<img width="100%" alt="The Screens view of a euxy review: the app/ route tree on the left under Changed 9 and All 19, and a grid of screen cards beside it in the same order, each with its route below the screenshot and a dot before it: green for the new /about, orange for modified screens such as /activity-log, /settings and /patterns, red for the removed /channel-surf" src="docs/screenshots/readme-screens-light.png">
</picture>
<strong>Screens</strong>: every capture in one grid, beside the route tree, with a dot for what changed.
</td>
<td width="33%" valign="top">
<td width="50%" valign="top">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/readme-pr-comment-dark.png">
<img width="100%" alt="Explore's GitHub PR comment on a euxy PR: the heading links to the iOS and Android reports, a table with one row per platform giving device, result and an Open link, the Added, Removed, Modified, Needs review and Source-affected screens as collapsed lists, fading out below them" src="docs/screenshots/readme-pr-comment-light.png">
@@ -80,7 +80,10 @@ describes, never for a password in chat. Open the report, and if I need to log i
something first, tell me the command.
```
You need Node.js 24.12+. Reviewing a change needs an Expo account and an Expo SDK 57+ app with Expo Router or React Navigation: it is built on EAS and captured on EAS Simulator ([join the waitlist](https://expo.dev/services/simulators)) or, with Xcode, on a simulator on your Mac. Exploring a build needs a Claude Code or Codex login, and EAS Simulator or a simulator on your Mac; on your Mac, no Expo account. No API keys, no CI.
You need Node.js 24.12+. Reviewing a change needs an Expo account and an Expo SDK 57+ app with Expo Router or React Navigation: it is built on EAS and captured on EAS Simulator or, with Xcode, on a simulator on your Mac. Exploring a build needs a Claude Code or Codex login, and EAS Simulator or a simulator on your Mac; on your Mac, no Expo account. No API keys, no CI.
> [!NOTE]
> EAS Simulator is in preview. [Join the waitlist](https://expo.dev/services/simulators), or pass `--simulator local` to capture on a simulator on your Mac.
<details>
<summary><strong>Run it yourself</strong></summary>
@@ -123,6 +126,9 @@ Explore starts an EAS Simulator, installs the build, taps through the app with y
</details>
> [!WARNING]
> A review runs both commits' code on your machine, as you: it installs their dependencies, evaluates the app config and bundles the JavaScript. Review only commits you would run yourself, and someone else's branch only if you trust it.
Every run is kept on your machine for 30 days. `npx @expo/explore reports` lists your local reviews, explorations and uploaded reports with their commits, and reopens or hosts one without capturing again:
<picture>
@@ -141,7 +147,6 @@ npx @expo/explore capture --base v1.3.0 --head v1.4.0 --scope all --upload
- It checks out both commits as temporary worktrees, installs their dependencies, captures every configured platform or [target](#targets) on EAS Simulator or a [local simulator](#simulator), and opens the report in a local Viewer. `--target` or `--platform` picks some; they run at once, at most `--parallel N` at a time. `--upload` hosts it for 30 days (`--expires-in` changes that) and prints the link; `report:upload <report.zip>` hosts one you already have.
- Your checkout, index and branches are never touched. Your uncommitted changes, untracked files included, are reviewed as `eas build` would upload them; `--committed`, or `cli.requireCommit: true` in `eas.json`, leaves them out.
- It runs both commits' code on your machine, as you: installing their dependencies, evaluating the app config, and bundling the JavaScript. That is what checking them out and running them would do, so review only commits you would run, and someone else's branch only if you trust it.
- Installs run without credential environment variables, which keeps tokens out of reach of a registry a commit's `.npmrc` names; that is not a sandbox. A registry that needs `${NPM_TOKEN}` in the project's `.npmrc` must be authenticated in your own `~/.npmrc`.
- Captures are cached in `~/.cache/expo-explore`, so the same base is not captured twice (`--no-cache` skips it); a capture unused for 30 days goes, and the cache stays under 2 GB. Ctrl+C stops the run's simulator sessions and local devices; when a run is stopped harder than that, the next local run stops what it left running.
- Like a CI review, it builds on EAS (reusing a matching build) and, unless it captures on a local simulator, runs EAS Simulator sessions: expect several minutes and EAS usage.
@@ -341,7 +346,7 @@ Explore pins each controller's version and starts the EAS session with it. Repor
Neither controller is installed with Explore. The first run that needs one downloads its pinned npm release (agent-device 1.6 MB, Argent 27 MB), checks it against the integrity hash Explore pins, and keeps it in `~/.cache/expo-explore/controllers` (`EXPLORE_CONTROLLER_CACHE` moves it). Behind a private registry, set `EXPLORE_NPM_REGISTRY` to a mirror of it.
Argent cannot switch the simulator's appearance yet ([software-mansion/argent#1509](https://github.com/software-mansion/argent/pull/1509)), so an Argent capture on EAS Simulator records one appearance: the one the app forces, else light. Explore warns when it skips one. On a [local simulator](#simulator) the host switches it, so every appearance the config asks for is captured.
Argent cannot switch the simulator's appearance yet ([software-mansion/argent#1509](https://github.com/software-mansion/argent/pull/1509)), so the host switches it: on an iOS EAS Simulator session (`eas simulator:control appearance.set`) and on a [local simulator](#simulator), every appearance the config asks for is captured. An Argent capture on an Android EAS Simulator session records one appearance: the one the app forces, else light. Explore warns when it skips one.
</details>
@@ -372,7 +377,7 @@ For a review, builds still run on EAS. The app is repacked with the route observ
With `--controller argent`, Explore installs Argent's tool-server on first use with `npm ci` from a lockfile Explore ships, so every dependency is pinned (about 160 MB, in the controller cache), and starts one per device. The host switches the appearance, so a local Argent capture records every appearance the config asks for. Reports record where they were captured, and a baseline is reused only by a review captured the same way.
A foldable folds before the app first opens (`pose` on a [target](#targets)); with agent-device on a local simulator it folds just after, since agent-device folds only inside a session. With Argent, an opened iPhone Duo is captured upright, in landscape. After a fold, Argent's reader can stay on the panel that went dark; Explore then restarts its tool-server, and if that is not enough SpringBoard as well, and opens the app again.
A foldable folds before the app first opens (`pose` on a [target](#targets)); with agent-device on a local simulator it folds just after, since agent-device folds only inside a session. With Argent, an opened iPhone Duo is captured upright, in landscape. After a fold, Argent's reader can stay on the panel that went dark, so Explore checks that the lit panel is read. If it isn't, Explore restarts the tool-server on a local simulator. On EAS Simulator, where the tool-server is the session's, it resets Argent's device helpers, then restarts SpringBoard and folds again. On EAS Simulator, an opened iPhone Duo usually needs that SpringBoard restart, which adds about a minute.
Each capture records what it starts on your Mac (simulators, emulators, controller daemons, tool-servers) and removes it when it ends. If a review or a local `explore:binary` run is stopped hard, the next local one stops what it left running; nothing Explore did not record is touched.
@@ -451,10 +456,6 @@ jobs:
</details>
## Flows: capture what a user does, not only where a link lands
When one frame per route is not enough (a payment, a sign-up, a wizard), give Explore the app's own [`e2e`](https://e2e.tester.army) tests and set `mode: flows` (or add `flows:` beside deterministic capture). Explore runs them on its simulator session on both revisions; every `app.screenshot("label")` in a test is a frame the review compares, each flow is a journey in the Viewer, and a flow that fails keeps the frames it took and names the step that failed. There is no Explore flow language to learn, and `explore capture --flows e2e/checkout.e2e.ts` runs just the flows you name; every step in the review links to its line in the test file. See [Flows](docs/quickstart-ci.md#flows-the-apps-e2e-tests-as-capture). Set `flows.frames: steps` to also take a frame after every step of a flow, not only where it calls `app.screenshot`.
## Sign-in and other app state
Each run starts on a fresh install. Tell Explore how to get past what the app needs: with `--hints` when running without source, or with [setup steps or agent instructions](docs/quickstart-ci.md#when-the-config-needs-setup-steps) in CI.
@@ -516,11 +517,28 @@ curl -s "$LINK/api/v1/screens?status=modified" | jq '.items[] | {route, status,
<details>
<summary><strong>How it works</strong></summary>
1. The review workflow runs on open, non-draft PRs from the repository whose author has write access. Bots such as Devin go under `ci.trustedAuthors` in `.expo-explore/config.yaml`.
2. Explore reads the diff and your router source to pick the affected screens.
3. It builds both revisions on EAS (reusing a build with the same native fingerprint) and captures each screen on EAS Simulator (or, on your machine, a local simulator), reusing a baseline of the base commit when one exists.
4. It compares the captures. A screen with a source change is **Modified** if its captures differ.
5. It uploads the report to GitHub Actions and posts a PR comment.
```mermaid
sequenceDiagram
autonumber
participant PR as Pull request
participant GA as GitHub Actions
participant B as EAS Build
participant S as EAS Simulator
PR->>GA: opened or updated
GA->>GA: read the diff and router source, pick the affected screens
GA->>B: build base and head
Note over B: reuses a build with the same native fingerprint
B-->>GA: simulator builds
GA->>S: capture each affected screen, in each appearance
Note over S: the base reuses its baseline when one exists
S-->>GA: screenshots
GA->>GA: compare the captures, outline the changed regions
GA->>PR: upload the report, comment with its links
```
- The review workflow runs on open, non-draft PRs from the repository whose author has write access. Bots such as Devin go under `ci.trustedAuthors` in `.expo-explore/config.yaml`.
- A screen with a source change is **Modified** if its captures differ.
- If EAS fails to start a session, Explore starts a new one, up to five times within 30 minutes. On your machine, a local simulator can stand in for EAS Simulator.
The same review runs for any two commits without a PR ([`explore-compare.yml`](#compare-any-two-commits), linking the report from the run summary) and on your machine (`capture`, [above](#quick-start)). The workflows' logic lives in `expo-explore ci:*` commands, so a fix reaches CI with the `@expo/explore` version the workflows pin.
@@ -537,8 +555,7 @@ Reports and baselines are kept for 30 days and diagnostics for 7. Hosted deploym
- The launch is captured once per appearance and compared like any screen. The comment says how long the splash stayed as it first appeared, when it first changed (a native launch screen handing over to an app-drawn one, an animation starting on it), and when the first screen settled. `capture.launch: video` adds a recording; a launch too fast to observe is reported as "no splash observed".
- On Android the splash usually shows only in the recording, which needs `ffmpeg`. The generated workflows install it.
- Hosted acceptance of agent mode with an API key is incomplete.
- With `capture.controller: argent` on EAS Simulator, each capture records one appearance (see [device controller](#controller)).
- On EAS Simulator, an opened iPhone Duo can fail to capture when Argent's reader stays on the cover panel after the fold. A [local simulator](#simulator) recovers from it.
- With `capture.controller: argent` on an Android EAS Simulator session, each capture records one appearance (see [device controller](#controller)).
- A local simulator runs only on your machine; the CI workflows capture on EAS Simulator.
- `explore:session` explores EAS Simulator sessions only.
+13 -60
View File
@@ -90,7 +90,7 @@ The capture profile can be a release build; a development client is not supporte
The generated `.expo-explore/config.yaml` lives in the application directory. Commit it with the app:
```yaml
mode: deterministic # deterministic (route links) | flows (setup, then the app's e2e tests) | agent
mode: deterministic
app:
platform: ios # ios | android
bundleId: com.example.myapp # Android: the application id (android.package)
@@ -105,7 +105,7 @@ device:
exploration:
scope: changes # changes | all
capture:
# controller: agent-device # agent-device (default) | argent (one appearance per capture on EAS Simulator until Argent can switch it; --controller overrides it for one run)
# controller: agent-device # agent-device (default) | argent (one appearance per capture on Android EAS Simulator until Argent can switch it; --controller overrides it for one run)
# simulator: eas # eas (EAS Simulator, default) | local (a simulator or emulator Explore starts on this machine with Xcode or the Android SDK; --simulator overrides it for one run)
maxMinutes: 30
maxActions: 500
@@ -265,63 +265,6 @@ Do not assume a failed full run is cheap to repeat: inspect its diagnostic and
correct the specific failure first. Respect a user's request to stop paid runs;
offline tests do not establish live cost or complete capture acceptance.
### Flows: the app's e2e tests as capture
Deterministic capture shows one frame per route. A flow shows the screens a user actually passes through: sign-up,
sending money, checking out. Explore does not define a flow language for this; a flow is a test file of the
[`e2e`](https://e2e.tester.army) package, written and run the way the app's own e2e suite is, and Explore runs it on
the simulator session it already holds, on both revisions, after `setup`.
```yaml
mode: flows # or keep mode: deterministic and add flows: to capture the routes and the flows
flows:
tests:
- e2e/**/*.e2e.ts # paths or globs from the app directory
# frames: steps # also take a frame after every step; the default keeps only the frames the flows take with app.screenshot
```
```ts
// e2e/send-money.e2e.ts
import { expect, test } from "e2e";
test("send money to a contact", async ({ app, device, screen }) => {
await device.openLink("myapp://send/contacts");
await app.screenshot("contacts"); // a frame the review compares across revisions
await screen.getByText("Alex Rivera").tap();
await screen.getByTestId("send-amount-input").fill("25");
await app.screenshot("amount");
await screen.getByTestId("send-amount-continue").tap();
await expect(screen.getByTestId("send-confirm")).toBeVisible();
await app.screenshot("review");
});
```
Every `app.screenshot(label)` is a frame the review compares across revisions; the label names it. For a long flow, set
`flows.frames: steps` and Explore also takes a frame after every step (a tap, a fill, an assertion), named by its step
number, so the Flows view shows the whole journey rather than only the checkpoints. Per-step frames cost one screenshot
per step, so a 30-step flow takes about a minute longer per revision and appearance.
- A flow starts by opening the app: `await app.open()` for a plain launch, or `device.openLink("myapp://…")` for a deep
link. The flows run in their own agent-device session on Explore's simulator, which begins with no app in the
foreground (e2e's mobile engine is built that way: "a test launches the pinned app with `app.open()`").
- Every `app.screenshot(label)` is a frame of the review, `flow:<file>/<test>/<label>`, compared pixel by pixel
between base and head like a route. The Viewer lists each flow as a journey through its frames; the PR comment has
one line per flow.
- A flow that fails keeps the frames it took and the report names the step that failed (`failed on head at step 5
(locator.tap getByText("Alex Rivera"))`); the capture goes on with the next flow. A flow is review evidence, not a
gate: the workflow does not fail because a flow did.
- `agent.act("…")` steps run when the config has an `agent` block with its provider key in the environment; e2e's
replay cache (`.e2e/cache`, committed) then replays them without a model on later runs. Locator-only flows need no
model.
- The flows run as the reviewed commit's own code, in a child process with the capture's narrowed environment, under
the same trust rule as the capture itself (same-repository PRs by authors with write access, or `ci.trustedAuthors`).
- `e2e` writes its report inside the app directory while the flows run (`.expo-explore-flows/`); Explore removes it
before the checkout is verified clean.
- A target or platform can run its own flows: `targets.fold.flows: { tests: [e2e/fold/*.e2e.ts] }` (or `platforms.android.flows`) replaces the top-level `flows` for that target; the others keep it. Within one file, e2e's own `test.describe(..., { platforms: ["ios"] })` already keeps a test to a platform, so a shared list usually suffices.
- To run a few flows without touching the config, name them on the command line: `explore capture --flows e2e/sequencer.e2e.ts,e2e/patterns.e2e.ts` (files or globs, comma-separated) runs those e2e files as the whole capture — flows mode, no route frames — whatever `mode:` says.
- The flows run once per appearance in `capture.appearance` (so twice for `[light, dark]`, after the light pass): a frame the dark pass takes shows up in Compare as the dark pair of its light frame; the Flows view lists the light frames and the steps once.
- Every step the review shows links to its line in the e2e file at the head commit (the Flows view and, for a frame, the inspector's Flow section), when the review names a GitHub repository.
### Agent mode
Keep the app, navigation, device, scope, and capture settings above, then explicitly select agent mode:
@@ -343,7 +286,7 @@ The provider selects the runtime that owns the navigation loop:
| `anthropic` | Claude Code through `@anthropic-ai/claude-agent-sdk` 0.3.285 and its platform-native package | `ANTHROPIC_API_KEY` |
| `openai` | Codex app-server from `@openai/codex` 0.159.2 and its platform-native package | `OPENAI_API_KEY` |
Both runtimes use Explore's device tools to operate the existing EAS Simulator through official `agent-device` 0.21.28. The runtime and native binaries come from the pinned tools installation. CI does not use the development-only `node_modules/.bin/claude` executable or an interactive subscription login.
Both runtimes use Explore's device tools to operate the existing EAS Simulator through official `agent-device` 0.21.29-nightly.20261018.74. The runtime and native binaries come from the pinned tools installation. CI does not use the development-only `node_modules/.bin/claude` executable or an interactive subscription login.
Create and commit the nonempty English prose file named by `agent.instructions`. The shared setup skill authors it from source and asks for missing test data or environment inputs. Describe how to reach the app's screens, necessary prerequisites, the representative state to use on both revisions, readiness signals, and actions to avoid. This file guides the runtime agent; it is not a list of mandatory YAML steps or a second screen inventory.
@@ -419,6 +362,16 @@ Capture uses the automatic GitHub token with `pull-requests: write`, so it can k
The sticky comment is one comment for the whole run: a header with the base and head commits, one row per captured platform (device, result, **Open** / **zip** / **run** links), every changed screen listed once with a link per platform, and a collapsed validation table with one column per platform. Each platform's job updates only its own hidden record in the comment, so iOS and Android jobs never overwrite each other. When a new run starts (a push, a rerun), the earlier run moves to a collapsed **Previous runs** list that keeps its head commit, result, report and run links; the last five runs are kept. A run that finishes after the PR moved on is still published, under previous runs, instead of failing. The failure job posts through the same renderer (`ci:failure`), so a crash before the pipeline's own comment still lands in that platform's row.
The comment can also draw a map of the change: the added, removed and visually changed screens, the screens one step before them, and the transitions among them, as a collapsed Mermaid flowchart that GitHub draws in place. It is off by default; turn it on with:
```yaml
report:
comment:
map: true # default false
```
The map leaves out screens whose source changed but whose captures match, and it is skipped when more than 30 routes changed or when the comment would be over GitHub's size limit.
PR review links always use [explore-preview.expo.app](https://explore-preview.expo.app/); no viewer-origin variable is needed or accepted by the CI publisher. Reports stay in GitHub Actions: the comment's **zip** link fetches the `explore-review-<run>-<attempt>.zip` artifact (GitHub asks for sign-in and repository read access), and the page that **Open** opens takes that ZIP by drag-and-drop or **Choose file**. Nothing is enabled per repository on Expo's side. See [report access](private-review.md).
Credentialed capture accepts open, non-draft, same-repository PRs whose authors have current write access, or are listed under `ci.trustedAuthors` in the default branch's `.expo-explore/config.yaml` (for bots such as `devin-ai-integration[bot]`). Fork PRs cannot receive capture credentials. Tools are loaded from the pinned reviewed commit, not the PR checkout. Build execution still runs the authorized application's code.
Binary file not shown.

Before

Width:  |  Height:  |  Size: 451 KiB

+1
View File
@@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1000 600" width="1000" height="600" role="img" aria-label="The /patterns screen of euxy wiping from its capture before the pull request to its capture after it, with the changed regions outlined"><style>.after{animation:wipe 7s cubic-bezier(.65,0,.35,1) infinite}@keyframes wipe{0.00%{clip-path:inset(0 100% 0 0)}14.29%{clip-path:inset(0 100% 0 0)}37.14%{clip-path:inset(0 0 0 0)}82.86%{clip-path:inset(0 0 0 0)}97.14%{clip-path:inset(0 100% 0 0)}100.00%{clip-path:inset(0 100% 0 0)}}.divider{opacity:0;animation:divider 7s cubic-bezier(.65,0,.35,1) infinite}@keyframes divider{0.00%{transform:translateX(0);opacity:0}11.43%{transform:translateX(0);opacity:1}14.29%{transform:translateX(0);opacity:1}37.14%{transform:translateX(248px);opacity:1}41.43%{transform:translateX(248px);opacity:0}82.86%{transform:translateX(248px);opacity:0}85.71%{transform:translateX(248px);opacity:1}97.14%{transform:translateX(0);opacity:1}100.00%{transform:translateX(0);opacity:0}}.regions{animation:regions 7s ease-in-out infinite}@keyframes regions{0.00%{opacity:0}38.57%{opacity:0}44.29%{opacity:1}51.43%{opacity:.3}58.57%{opacity:1}81.43%{opacity:1}85.71%{opacity:0}100.00%{opacity:0}}.before-label{opacity:.3;animation:before-label 7s linear infinite}.after-label{animation:after-label 7s linear infinite}@keyframes before-label{0.00%{opacity:1}25.71%{opacity:1}28.57%{opacity:.3}88.57%{opacity:.3}91.43%{opacity:1}100.00%{opacity:1}}@keyframes after-label{0.00%{opacity:.3}25.71%{opacity:.3}28.57%{opacity:1}88.57%{opacity:1}91.43%{opacity:.3}100.00%{opacity:.3}}@media (prefers-reduced-motion: reduce){*{animation:none!important}}</style><defs><clipPath id="stage"><rect width="1000" height="600" rx="16"/></clipPath><clipPath id="phone"><rect x="376" y="30" width="248" height="540" rx="40"/></clipPath><filter id="shadow" x="-20%" y="-20%" width="140%" height="140%"><feDropShadow dx="0" dy="8" stdDeviation="14" flood-color="rgba(1,4,9,0.6)"/></filter></defs><g clip-path="url(#stage)"><rect width="1000" height="600" fill="#151B23"/><rect x="376" y="30" width="248" height="540" rx="40" fill="#151B23" filter="url(#shadow)"/><g clip-path="url(#phone)"><image href="data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/4gHYSUNDX1BST0ZJTEUAAQEAAAHIAAAAAAQwAABtbnRyUkdCIFhZWiAH4AABAAEAAAAAAABhY3NwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQAA9tYAAQAAAADTLQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAlkZXNjAAAA8AAAACRyWFlaAAABFAAAABRnWFlaAAABKAAAABRiWFlaAAABPAAAABR3dHB0AAABUAAAABRyVFJDAAABZAAAAChnVFJDAAABZAAAAChiVFJDAAABZAAAAChjcHJ0AAABjAAAADxtbHVjAAAAAAAAAAEAAAAMZW5VUwAAAAgAAAAcAHMAUgBHAEJYWVogAAAAAAAAb6IAADj1AAADkFhZWiAAAAAAAABimQAAt4UAABjaWFlaIAAAAAAAACSgAAAPhAAAts9YWVogAAAAAAAA9tYAAQAAAADTLXBhcmEAAAAAAAQAAAACZmYAAPKnAAANWQAAE9AAAApbAAAAAAAAAABtbHVjAAAAAAAAAAEAAAAMZW5VUwAAACAAAAAcAEcAbwBvAGcAbABlACAASQBuAGMALgAgADIAMAAxADb/2wBDAAYEBAUEBAYFBQUGBgYHCQ4JCQgICRINDQoOFRIWFhUSFBQXGiEcFxgfGRQUHScdHyIjJSUlFhwpLCgkKyEkJST/2wBDAQYGBgkICREJCREkGBQYJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCT/wAARCANqAZIDASIAAhEBAxEB/8QAHAABAAICAwEAAAAAAAAAAAAAAAMFBAYBAgcI/8QAWBAAAQMDAQQECwQHBAUKBQQDAQACAwQFERIGEyExFEFR0QcVIjJSU2GBkZKTNFRxsQgjM2OhouEWQmLBJHJ1gtIYNkNVVrKz1OLwFzdzlJUmNThEg8Px/8QAGAEBAQEBAQAAAAAAAAAAAAAAAAEDAgT/xAAdEQEBAAMBAAMBAAAAAAAAAAAAEQECAwQSMUFR/9oADAMBAAIRAxEAPwD5UREQEREBERAREQEREBERAREQEREBERAREQEREBERAREQEREBERAREQEREBERAREQEREBERAREQEREBERAREQEREBERAREQEREBFs2wdn2aut0kftXeZrbbaZgkdHTRa6ircXACKIHgHHOdTuAAXptz8CuzVB4X9sLRPUXCHZPZS3suVSWva6olbuI37priManOecHHIY9qDwxF6dtdsfspd/B5Dt9sZT19sp4Lj4suNurZxPuXFupkrHhoJaRwII5nhy449DsjsFs/tZc6faXa2K8Wm3UQqIDZ8g3KcgEQNeQQzBJy49nUeQecovVdtdiNjpdktlNsrGa/Z2gvVdJQ1NLXvNTuGscA6eNzWhz2AZyMZzwCu6fYTwZbVWvaaLZ2j2lo4rHbpa2n2jrZR0atdHgBroyxujWT5IB1ezIwg8PREQEREBERAREQEREBERAREQEREBERAREQEREBERAREQEReh+C3YDZbaenr7xthtdDZLXb3sjdSwDXW1TneaImYPPB4gO4jl1oPPEX0xUeDTwVMt5kqvB34VrbQacm7vpc7tvrHMy4hvXnR7l414T9iLNsXdaQbP7U0O0druEHSaeaA4ljZnGmVv913A+3gcgckGmIvQPA/4M5PCZtDFao5IY3SF+XzaiyJjG5c4hpBceLQACOJ4ngve/wDkWUn/AGlt3/4qf/ziD5ERfXf/ACLKT/tJbv8A8VP/AOcXgHhU8GtT4P8AaOstGGSvpHfrHQajG5hYx7ZAHZLQQ8Agk4IPEhBoaIiAiIgIiICIiAiIgIiIJaRwZVQucQAHtJJ6uK+jL54QNlLp4afCLQTXyljsW1tqit8F2YdcMM7aeIMc4j+4HBwJ6j2DJXzciD17aipsuwXgiOwlNtBar/d7rdm3GsltMxmp6eBjNLGCTABeSM+zjnqzjbJbPeC7a3wkSOddp9ntkKWGObc3ioa2eqeAAYg9uQ0F2SSMkDlgnh5UiD2HwsNprxe7Vc7xtlsxWWKKojoIbTs1O6R1so+JJjY6NoOA3ieZcR1YxttnqLBsfZ7xS3vwmWLarYQ0M8dssYeZqt0jsmI7osG4e0k+UCME9XV84ogIiICIiAiIgIiICIiAiIgIiICIiAiIgIiICIiAiIgszQ2/pMEfTsxvYS93onsURpaPo1TJ0r9ZHIWxtx57e1YKIMuvp6aDddGqN9qbl3+ErI2a2iuGyV+ob7aZWRV1DKJYXPYHgEdoPAjGQqxEH0HV+HF9u2Lt+1Nr8I21VXttUTaaq01W7dQMx553OjS1mCNJack9mDjwKsq5q+rnq6l+ueeR0sjsAanOOScDgOJ6lCiD1DwD+Eel8HG1ENzqoRPGzeMki3jY3Pje0AlrnEN1AtacOIBGeIX0t/yuNiP+rLz9eg/80vhlEH3N/wArjYj/AKsvP16D/wA0vmbwzeEwbb7WXC7UDRTMrf1Zia9shZCGRsDXOHAuOgk6SQMgZPFeZIgIiICIiAiIgIiICIiAiIgIiICIiAiIgIiICIiAiIgIiICIiAiIgIiICIiAiIgIiICIiAiIgIilhpZ6jO6ie/HMgcB+JQRIsw2qrAzu2fUb3rHlp5YDiSNzOzI5oI0REBERARSw0s9RndRPfjmQOA/Eqc2qLine truncated

After

Width:  |  Height:  |  Size: 107 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 452 KiB

@@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1000 600" width="1000" height="600" role="img" aria-label="The /patterns screen of euxy wiping from its capture before the pull request to its capture after it, with the changed regions outlined"><style>.after{animation:wipe 7s cubic-bezier(.65,0,.35,1) infinite}@keyframes wipe{0.00%{clip-path:inset(0 100% 0 0)}14.29%{clip-path:inset(0 100% 0 0)}37.14%{clip-path:inset(0 0 0 0)}82.86%{clip-path:inset(0 0 0 0)}97.14%{clip-path:inset(0 100% 0 0)}100.00%{clip-path:inset(0 100% 0 0)}}.divider{opacity:0;animation:divider 7s cubic-bezier(.65,0,.35,1) infinite}@keyframes divider{0.00%{transform:translateX(0);opacity:0}11.43%{transform:translateX(0);opacity:1}14.29%{transform:translateX(0);opacity:1}37.14%{transform:translateX(248px);opacity:1}41.43%{transform:translateX(248px);opacity:0}82.86%{transform:translateX(248px);opacity:0}85.71%{transform:translateX(248px);opacity:1}97.14%{transform:translateX(0);opacity:1}100.00%{transform:translateX(0);opacity:0}}.regions{animation:regions 7s ease-in-out infinite}@keyframes regions{0.00%{opacity:0}38.57%{opacity:0}44.29%{opacity:1}51.43%{opacity:.3}58.57%{opacity:1}81.43%{opacity:1}85.71%{opacity:0}100.00%{opacity:0}}.before-label{opacity:.3;animation:before-label 7s linear infinite}.after-label{animation:after-label 7s linear infinite}@keyframes before-label{0.00%{opacity:1}25.71%{opacity:1}28.57%{opacity:.3}88.57%{opacity:.3}91.43%{opacity:1}100.00%{opacity:1}}@keyframes after-label{0.00%{opacity:.3}25.71%{opacity:.3}28.57%{opacity:1}88.57%{opacity:1}91.43%{opacity:.3}100.00%{opacity:.3}}@media (prefers-reduced-motion: reduce){*{animation:none!important}}</style><defs><clipPath id="stage"><rect width="1000" height="600" rx="16"/></clipPath><clipPath id="phone"><rect x="376" y="30" width="248" height="540" rx="40"/></clipPath><filter id="shadow" x="-20%" y="-20%" width="140%" height="140%"><feDropShadow dx="0" dy="8" stdDeviation="14" flood-color="rgba(17,17,17,0.14)"/></filter></defs><g clip-path="url(#stage)"><rect width="1000" height="600" fill="#F6F8FA"/><rect x="376" y="30" width="248" height="540" rx="40" fill="#F6F8FA" filter="url(#shadow)"/><g clip-path="url(#phone)"><image href="data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/4gHYSUNDX1BST0ZJTEUAAQEAAAHIAAAAAAQwAABtbnRyUkdCIFhZWiAH4AABAAEAAAAAAABhY3NwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQAA9tYAAQAAAADTLQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAlkZXNjAAAA8AAAACRyWFlaAAABFAAAABRnWFlaAAABKAAAABRiWFlaAAABPAAAABR3dHB0AAABUAAAABRyVFJDAAABZAAAAChnVFJDAAABZAAAAChiVFJDAAABZAAAAChjcHJ0AAABjAAAADxtbHVjAAAAAAAAAAEAAAAMZW5VUwAAAAgAAAAcAHMAUgBHAEJYWVogAAAAAAAAb6IAADj1AAADkFhZWiAAAAAAAABimQAAt4UAABjaWFlaIAAAAAAAACSgAAAPhAAAts9YWVogAAAAAAAA9tYAAQAAAADTLXBhcmEAAAAAAAQAAAACZmYAAPKnAAANWQAAE9AAAApbAAAAAAAAAABtbHVjAAAAAAAAAAEAAAAMZW5VUwAAACAAAAAcAEcAbwBvAGcAbABlACAASQBuAGMALgAgADIAMAAxADb/2wBDAAYEBAUEBAYFBQUGBgYHCQ4JCQgICRINDQoOFRIWFhUSFBQXGiEcFxgfGRQUHScdHyIjJSUlFhwpLCgkKyEkJST/2wBDAQYGBgkICREJCREkGBQYJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCT/wAARCANqAZIDASIAAhEBAxEB/8QAHQABAAEFAQEBAAAAAAAAAAAAAAECAwQFBgcICf/EAFkQAAEDAwICBwQHBAYFCgQDCQEAAgMEBREGEiExBxMUQVFSkSIyYaEVM1NxgZLhCCNisRgkNELR0xZWlJXBJTdDcnN1gqKz8Bdjk9QmNTY4RlV0g4Sy0vH/xAAYAQEBAQEBAAAAAAAAAAAAAAAAAQIDBP/EABoRAQEBAQEBAQAAAAAAAAAAAAARAQIDIQT/2gAMAwEAAhEDEQA/APpxERFEREBERAREQEREBERAREQEREBERARYl0u9uslI6sulfSUFMz3pqmVsbB+LiAuCuH7RnRXbZDHNq6mkcOH9XgmmHqxhHzQekIvKv6UPRP8A6zSf7vqf8tP6UPRP/rNJ/u+p/wAtB6qi8q/pQ9E/+s0n+76n/LT+lD0T/wCs0n+76n/LQeqovKv6UPRP/rNJ/u+p/wAtP6UPRP8A6zSf7vqf8tB6qi8q/pQ9E/8ArNJ/u+p/y0/pQ9E/+s0n+76n/LQeqovKv6UPRP8A6zSf7vqf8tP6UPRP/rNJ/u+p/wAtB6qi8vpv2mOiipeGN1W1hP2lFUMHqY8Lt9O6z03q2IyWG+W65hoy4U07XuZ/1mg5H4hBuUREBERAREQEREBERAREQEREBERAREQEREBERAREQEREBFq9TXK4Wix1NZabTJeK9m1sFFHIIzK9zg0ZceDWjOSe4Aryaz9NOobTofXl91ZTW2W4aauLqCKChDmxPkO1rW5JJI3uHHngIPbUXkdFq/X+jdTaYpNcVFor6DUzzTf1KndC+3VRbubHkuO9p93J48M93HprprLVD7Vqf6F0ZXPudrnbTW9lW5rIrhuIHWtOR7DcknjxAxnOQA7ZF5PZ9Va6030lWLSOqrjZ73HfaSeoD6GmMD6F0TdxyMndGfdBOCT4YwadM9I2trl0s02nb9Z6KzWyutUlxpqPcZKpjWybGmVwO0OOCdoHAEDOcoPWkREBERAXE9LvSdQ9FWkZbzUMbUVkrupoqUnHXSkZ4+DQOJP4cyF2y+MP2wtRT3LpIpbNvPZrVRM2s7usk9pzvxb1Y/BB5NrLXWodfXZ901DcpqyZxOxhOI4R5WN5NH3fjkrQIiIIiICIiAiIgIiICIiAsm3XKttFbFXW+rno6qF26OaCQsew+II4hYyIPtX9nDp2m6RaaTTuopGfT9HH1kc4AaK2IcCcDgHt4ZxzBz3Fe5L83ujTUU+k9f2C8wPLDTVsW/H96Nztr2/i0uH4r9IUUREQEREBEXn/AEn681RpmooLRpHSc15udwY97aqc7KKla3mZH5HLI4Et4Hn3IPQEXzbT9JHSk+vEdL0g9Flyrt3C0sqcb3fZtfhoLu7G/wDFew9GetbxrK11Zv8Apiu09c6Cfs1RDOMxSOxndE7+83iPhxGCeaDsUXBdLnSTH0bWCW6SRyyNjDcMh2h8r3uw1oLgQ0cHEkg8BwHFeEf0y6r/AFcuH+9IP/tEH1oi+TP6ZdV/q5cP96Qf/aL3rou6R6bXunaS7ZfEyrb+7bPtEjXhz2ujJbgOILCQQBkEcAUHcoiICIiAiIgIiICIiAiIgLwGp6ML/qTSPSxZ+xS0lVdL/JXW0zjY2oDHMe0tJ4YdtLc8uK9+RB4pPUak6WdV6LbU6RvNgpNP1QudznuUIiY6oY3DI4eJ6wF2fa8F2t0uut9MWrVF1qKCl1AWTA2S321jhMYzhoEue8E5OM8A74AdsiDxHogq7jBqB9x1Lo3V79U3r2a281tGxlLSsALhDH7ZLIhgAcMuOCe7HS3CxXOT9oK13xlDO62Radlpn1Yb+7bKZiQwnxxxwvSUQEREBERAXxV+19Yprd0ox3NzD1FzoYnsf3FzMsc37wA0/wDiC+1VLine truncated

After

Width:  |  Height:  |  Size: 109 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 847 KiB

+1
View File
@@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1600 900" width="1600" height="900" role="img" aria-label="Explore's Map of a euxy pull request: the screen cards appear row by row, the transitions between them wipe in, then a click selects /about and the Inspector opens on it"><style>.c0{transform-origin:0 0;animation:c0 12s cubic-bezier(.2,.8,.2,1) infinite}@keyframes c0{0.00%{opacity:0;transform:scale(.92)}4.33%{opacity:0;transform:scale(.92)}8.08%{opacity:1;transform:scale(1)}100.00%{opacity:1;transform:scale(1)}}.c1{transform-origin:0 0;animation:c1 12s cubic-bezier(.2,.8,.2,1) infinite}@keyframes c1{0.00%{opacity:0;transform:scale(.92)}4.00%{opacity:0;transform:scale(.92)}7.75%{opacity:1;transform:scale(1)}100.00%{opacity:1;transform:scale(1)}}.c2{transform-origin:0 0;animation:c2 12s cubic-bezier(.2,.8,.2,1) infinite}@keyframes c2{0.00%{opacity:0;transform:scale(.92)}4.67%{opacity:0;transform:scale(.92)}8.42%{opacity:1;transform:scale(1)}100.00%{opacity:1;transform:scale(1)}}.c3{transform-origin:0 0;animation:c3 12s cubic-bezier(.2,.8,.2,1) infinite}@keyframes c3{0.00%{opacity:0;transform:scale(.92)}6.08%{opacity:0;transform:scale(.92)}9.83%{opacity:1;transform:scale(1)}100.00%{opacity:1;transform:scale(1)}}.c4{transform-origin:0 0;animation:c4 12s cubic-bezier(.2,.8,.2,1) infinite}@keyframes c4{0.00%{opacity:0;transform:scale(.92)}6.41%{opacity:0;transform:scale(.92)}10.16%{opacity:1;transform:scale(1)}100.00%{opacity:1;transform:scale(1)}}.c5{transform-origin:0 0;animation:c5 12s cubic-bezier(.2,.8,.2,1) infinite}@keyframes c5{0.00%{opacity:0;transform:scale(.92)}6.75%{opacity:0;transform:scale(.92)}10.50%{opacity:1;transform:scale(1)}100.00%{opacity:1;transform:scale(1)}}.c6{transform-origin:0 0;animation:c6 12s cubic-bezier(.2,.8,.2,1) infinite}@keyframes c6{0.00%{opacity:0;transform:scale(.92)}7.08%{opacity:0;transform:scale(.92)}10.83%{opacity:1;transform:scale(1)}100.00%{opacity:1;transform:scale(1)}}.c7{transform-origin:0 0;animation:c7 12s cubic-bezier(.2,.8,.2,1) infinite}@keyframes c7{0.00%{opacity:0;transform:scale(.92)}3.66%{opacity:0;transform:scale(.92)}7.41%{opacity:1;transform:scale(1)}100.00%{opacity:1;transform:scale(1)}}.c8{transform-origin:0 0;animation:c8 12s cubic-bezier(.2,.8,.2,1) infinite}@keyframes c8{0.00%{opacity:0;transform:scale(.92)}7.41%{opacity:0;transform:scale(.92)}11.16%{opacity:1;transform:scale(1)}100.00%{opacity:1;transform:scale(1)}}.c9{transform-origin:0 0;animation:c9 12s cubic-bezier(.2,.8,.2,1) infinite}@keyframes c9{0.00%{opacity:0;transform:scale(.92)}7.75%{opacity:0;transform:scale(.92)}11.50%{opacity:1;transform:scale(1)}100.00%{opacity:1;transform:scale(1)}}.c10{transform-origin:0 0;animation:c10 12s cubic-bezier(.2,.8,.2,1) infinite}@keyframes c10{0.00%{opacity:0;transform:scale(.92)}8.08%{opacity:0;transform:scale(.92)}11.83%{opacity:1;transform:scale(1)}100.00%{opacity:1;transform:scale(1)}}.c11{transform-origin:0 0;animation:c11 12s cubic-bezier(.2,.8,.2,1) infinite}@keyframes c11{0.00%{opacity:0;transform:scale(.92)}8.42%{opacity:0;transform:scale(.92)}12.17%{opacity:1;transform:scale(1)}100.00%{opacity:1;transform:scale(1)}}.full{animation:full 12s cubic-bezier(.45,0,.25,1) infinite}@keyframes full{0.00%{clip-path:inset(0 0 100% 0)}10.83%{clip-path:inset(0 0 100% 0)}21.67%{clip-path:inset(0 0 0 0)}100.00%{clip-path:inset(0 0 0 0)}}.ptr{opacity:0;animation:ptr 12s cubic-bezier(.4,0,.2,1) infinite}@keyframes ptr{0.00%{opacity:0;transform:translate(978.5px,714.0px)}25.83%{opacity:0;transform:translate(978.5px,714.0px)}27.50%{opacity:1;transform:translate(978.5px,714.0px)}35.83%{opacity:1;transform:translate(718.5px,505.2px)}36.67%{opacity:1;transform:translate(718.5px,505.2px) scale(.82)}37.92%{opacity:1;transform:translate(718.5px,505.2px)}45.83%{opacity:0;transform:translate(718.5px,505.2px)}100.00%{opacity:0;transform:translate(718.5px,505.2px)}}.sel{animation:sel 12s ease-out infinite}@keyframes sel{0.00%{opacity:0}36.67%{opacity:0}39.17%{opacity:1}100.00%{opacity:1}}.insp{animation:insp 12s cubic-bezier(.2,.8,.2,1) infinite}@keyframes insp{0.00%{opacity:0;transform:translateX(48px)}37.08%{opacity:0;transform:translateX(48px)}42.08%{opacity:1;transform:translateX(0)}100.00%{opacity:1;transform:translateX(0)}}.cover{opacity:0;animation:cover 12s linear infinite}@keyframes cover{0.00%{opacity:1}1.67%{opacity:0}94.17%{opacity:0}100.00%{opacity:1}}@media (prefers-reduced-motion: reduce){*{animation:none!important}}</style><defs><image id="empty" width="1376" height="774" href="data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/4gHYSUNDX1BST0ZJTEUAAQEAAAHIAAAAAAQwAABtbnRyUkdCIFhZWiAH4AABAAEAAAAAAABhY3NwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQAA9tYAAQAAAADTLQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAlkZXNjAAAA8AAAACRyWFlaAAABFAAAABRnWFlaAAABKAAAABRiWFlaAAABPAAAABR3dHB0AAABUAAAABRyVFJDAAABZAAAAChnVFJDAAABZAAAAChiVFJDAAABZAAAAChjcHJ0AAABjAAAADxtbHVjAAAAAAAAAAEAAAAMZW5VUwAAAAgAAAAcAHMAUgBHAEJYWVogAAAAAAAAb6IAADj1AAADkFhZWiAALine truncated

After

Width:  |  Height:  |  Size: 1.4 MiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 830 KiB

+1
View File
@@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1600 900" width="1600" height="900" role="img" aria-label="Explore's Map of a euxy pull request: the screen cards appear row by row, the transitions between them wipe in, then a click selects /about and the Inspector opens on it"><style>.c0{transform-origin:0 0;animation:c0 12s cubic-bezier(.2,.8,.2,1) infinite}@keyframes c0{0.00%{opacity:0;transform:scale(.92)}4.33%{opacity:0;transform:scale(.92)}8.08%{opacity:1;transform:scale(1)}100.00%{opacity:1;transform:scale(1)}}.c1{transform-origin:0 0;animation:c1 12s cubic-bezier(.2,.8,.2,1) infinite}@keyframes c1{0.00%{opacity:0;transform:scale(.92)}4.00%{opacity:0;transform:scale(.92)}7.75%{opacity:1;transform:scale(1)}100.00%{opacity:1;transform:scale(1)}}.c2{transform-origin:0 0;animation:c2 12s cubic-bezier(.2,.8,.2,1) infinite}@keyframes c2{0.00%{opacity:0;transform:scale(.92)}4.67%{opacity:0;transform:scale(.92)}8.42%{opacity:1;transform:scale(1)}100.00%{opacity:1;transform:scale(1)}}.c3{transform-origin:0 0;animation:c3 12s cubic-bezier(.2,.8,.2,1) infinite}@keyframes c3{0.00%{opacity:0;transform:scale(.92)}6.08%{opacity:0;transform:scale(.92)}9.83%{opacity:1;transform:scale(1)}100.00%{opacity:1;transform:scale(1)}}.c4{transform-origin:0 0;animation:c4 12s cubic-bezier(.2,.8,.2,1) infinite}@keyframes c4{0.00%{opacity:0;transform:scale(.92)}6.41%{opacity:0;transform:scale(.92)}10.16%{opacity:1;transform:scale(1)}100.00%{opacity:1;transform:scale(1)}}.c5{transform-origin:0 0;animation:c5 12s cubic-bezier(.2,.8,.2,1) infinite}@keyframes c5{0.00%{opacity:0;transform:scale(.92)}6.75%{opacity:0;transform:scale(.92)}10.50%{opacity:1;transform:scale(1)}100.00%{opacity:1;transform:scale(1)}}.c6{transform-origin:0 0;animation:c6 12s cubic-bezier(.2,.8,.2,1) infinite}@keyframes c6{0.00%{opacity:0;transform:scale(.92)}7.08%{opacity:0;transform:scale(.92)}10.83%{opacity:1;transform:scale(1)}100.00%{opacity:1;transform:scale(1)}}.c7{transform-origin:0 0;animation:c7 12s cubic-bezier(.2,.8,.2,1) infinite}@keyframes c7{0.00%{opacity:0;transform:scale(.92)}3.66%{opacity:0;transform:scale(.92)}7.41%{opacity:1;transform:scale(1)}100.00%{opacity:1;transform:scale(1)}}.c8{transform-origin:0 0;animation:c8 12s cubic-bezier(.2,.8,.2,1) infinite}@keyframes c8{0.00%{opacity:0;transform:scale(.92)}7.41%{opacity:0;transform:scale(.92)}11.16%{opacity:1;transform:scale(1)}100.00%{opacity:1;transform:scale(1)}}.c9{transform-origin:0 0;animation:c9 12s cubic-bezier(.2,.8,.2,1) infinite}@keyframes c9{0.00%{opacity:0;transform:scale(.92)}7.75%{opacity:0;transform:scale(.92)}11.50%{opacity:1;transform:scale(1)}100.00%{opacity:1;transform:scale(1)}}.c10{transform-origin:0 0;animation:c10 12s cubic-bezier(.2,.8,.2,1) infinite}@keyframes c10{0.00%{opacity:0;transform:scale(.92)}8.08%{opacity:0;transform:scale(.92)}11.83%{opacity:1;transform:scale(1)}100.00%{opacity:1;transform:scale(1)}}.c11{transform-origin:0 0;animation:c11 12s cubic-bezier(.2,.8,.2,1) infinite}@keyframes c11{0.00%{opacity:0;transform:scale(.92)}8.42%{opacity:0;transform:scale(.92)}12.17%{opacity:1;transform:scale(1)}100.00%{opacity:1;transform:scale(1)}}.full{animation:full 12s cubic-bezier(.45,0,.25,1) infinite}@keyframes full{0.00%{clip-path:inset(0 0 100% 0)}10.83%{clip-path:inset(0 0 100% 0)}21.67%{clip-path:inset(0 0 0 0)}100.00%{clip-path:inset(0 0 0 0)}}.ptr{opacity:0;animation:ptr 12s cubic-bezier(.4,0,.2,1) infinite}@keyframes ptr{0.00%{opacity:0;transform:translate(978.5px,714.0px)}25.83%{opacity:0;transform:translate(978.5px,714.0px)}27.50%{opacity:1;transform:translate(978.5px,714.0px)}35.83%{opacity:1;transform:translate(718.5px,505.2px)}36.67%{opacity:1;transform:translate(718.5px,505.2px) scale(.82)}37.92%{opacity:1;transform:translate(718.5px,505.2px)}45.83%{opacity:0;transform:translate(718.5px,505.2px)}100.00%{opacity:0;transform:translate(718.5px,505.2px)}}.sel{animation:sel 12s ease-out infinite}@keyframes sel{0.00%{opacity:0}36.67%{opacity:0}39.17%{opacity:1}100.00%{opacity:1}}.insp{animation:insp 12s cubic-bezier(.2,.8,.2,1) infinite}@keyframes insp{0.00%{opacity:0;transform:translateX(48px)}37.08%{opacity:0;transform:translateX(48px)}42.08%{opacity:1;transform:translateX(0)}100.00%{opacity:1;transform:translateX(0)}}.cover{opacity:0;animation:cover 12s linear infinite}@keyframes cover{0.00%{opacity:1}1.67%{opacity:0}94.17%{opacity:0}100.00%{opacity:1}}@media (prefers-reduced-motion: reduce){*{animation:none!important}}</style><defs><image id="empty" width="1376" height="774" href="data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/4gHYSUNDX1BST0ZJTEUAAQEAAAHIAAAAAAQwAABtbnRyUkdCIFhZWiAH4AABAAEAAAAAAABhY3NwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQAA9tYAAQAAAADTLQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAlkZXNjAAAA8AAAACRyWFlaAAABFAAAABRnWFlaAAABKAAAABRiWFlaAAABPAAAABR3dHB0AAABUAAAABRyVFJDAAABZAAAAChnVFJDAAABZAAAAChiVFJDAAABZAAAAChjcHJ0AAABjAAAADxtbHVjAAAAAAAAAAEAAAAMZW5VUwAAAAgAAAAcAHMAUgBHAEJYWVogAAAAAAAAb6IAADj1AAADkFhZWiAALine truncated

After

Width:  |  Height:  |  Size: 1.4 MiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 642 KiB

After

Width:  |  Height:  |  Size: 640 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 643 KiB

After

Width:  |  Height:  |  Size: 642 KiB

+183 -1116
View File
File diff suppressed because it is too large. Load diff
+4 -6
View File
@@ -1,6 +1,6 @@
{
"name": "@expo/explore",
"version": "0.19.5",
"version": "0.19.7",
"description": "Source-driven mobile app maps, deterministic CI capture, and visual reviews",
"license": "MIT",
"type": "module",
@@ -50,7 +50,7 @@
"test:node": "node --test test/node/*.test.mjs",
"test:hosting": "npm --prefix viewer-host run typecheck && npm --prefix viewer-host test",
"test:viewer:artifacts": "node --test test/browser/artifact-report.browser.mjs test/browser/artifact-cache.browser.mjs",
"test:viewer:browser": "node --test test/browser/flows-view.browser.mjs test/browser/screenshot-image.browser.mjs test/browser/inspector-notes.browser.mjs test/browser/inspector-variants.browser.mjs test/browser/inspector-source-navigation.browser.mjs test/browser/map-edge-presentation.browser.mjs test/browser/local-ci-view.browser.mjs test/browser/report-viewer.browser.mjs",
"test:viewer:browser": "node --test test/browser/screenshot-image.browser.mjs test/browser/inspector-notes.browser.mjs test/browser/inspector-variants.browser.mjs test/browser/inspector-source-navigation.browser.mjs test/browser/map-edge-presentation.browser.mjs test/browser/local-ci-view.browser.mjs test/browser/report-viewer.browser.mjs",
"test:viewer:e2e": "npm run test:viewer:browser && playwright test",
"typecheck": "tsc -p tsconfig.json --noEmit && tsc -p viewer/tsconfig.json --noEmit",
"lint": "eslint .",
@@ -61,12 +61,10 @@
"readme:screenshots": "node scripts/readme-screenshots.mjs"
},
"dependencies": {
"@e2e-dev/mobile": "0.12.3",
"@expo/repack-app": "0.10.1",
"@types/node": "^22.19.19",
"@zip.js/zip.js": "2.16.0",
"ajv": "^8.17.1",
"e2e": "0.21.2",
"pngjs": "7.0.0",
"typescript": "^5.9.3",
"yaml": "^2.9.0",
@@ -75,7 +73,7 @@
"optionalDependencies": {
"@anthropic-ai/claude-agent-sdk": "0.3.285",
"@openai/codex": "0.159.2",
"eas-cli": "25.0.0"
"eas-cli": "25.2.0"
},
"devDependencies": {
"@anthropic-ai/claude-code": "2.1.285",
@@ -85,7 +83,7 @@
"@types/react-dom": "^19.2.4",
"@vitejs/plugin-react": "^4.7.0",
"@xyflow/react": "^12.11.3",
"agent-device": "0.21.28",
"agent-device": "0.21.29-nightly.20261018.74",
"babel-plugin-react-compiler": "^1.0.0",
"eslint": "^10.12.0",
"eslint-plugin-react-hooks": "^7.1.1",
+243
View File
@@ -0,0 +1,243 @@
// The README's two animated SVGs, written by readme-screenshots.mjs. Each is a plain image: CSS keyframes on one loop,
// every picture inlined as a JPEG data URI (an SVG shown with <img> loads nothing), and with prefers-reduced-motion
// it shows its last frame, which is also what a viewer that does not animate SVG shows.
//
// readme-hero the Viewer's Map, built from real Viewer frames: the screens appear row by row, the transitions
// wipe in from the top, then a click selects a screen and the Inspector slides in
// readme-compare one modified screen wiping from its base capture to its head capture, the changed regions pulsing
import { ZipReader, Uint8ArrayReader, Uint8ArrayWriter } from "@zip.js/zip.js";
/** The soft stage the PR comment picture sits on too (stagedComment in readme-screenshots.mjs), and its accents. */
const STAGE = {
light: { stage: "#F6F8FA", border: "#D1D9E0", shadow: "rgba(17,17,17,0.14)", text: "#1F2328", muted: "#59636E", accent: "#0969DA", region: "#D4520F" },
dark: { stage: "#151B23", border: "#3D444D", shadow: "rgba(1,4,9,0.6)", text: "#F0F6FC", muted: "#9198A1", accent: "#4493F8", region: "#F0883E" },
};
const FONT = "-apple-system, BlinkMacSystemFont, &apos;Segoe UI&apos;, &apos;Noto Sans&apos;, Helvetica, Arial, sans-serif";
const MONO = "ui-monospace, SFMono-Regular, &apos;SF Mono&apos;, Menlo, Consolas, monospace";
const JPEG_QUALITY = 82;
const dataUri = jpeg => `data:image/jpeg;base64,${jpeg.toString("base64")}`;
const escapeXml = text => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
const box = ({ x, y, width, height }) => `x="${x}" y="${y}" width="${width}" height="${height}"`;
/** Keyframes given in seconds on a shared loop, so every element stays in step. */
function keyframes(name, loop, frames) {
return `@keyframes ${name}{${frames.map(([at, css]) => `${((at / loop) * 100).toFixed(2)}%{${css}}`).join("")}}`;
}
/**
* Photographs the hero's states from a Viewer page whose Map has its camera set and nothing selected: the Map without
* its screens, without its edges, and whole; then it clicks `select`, which opens the Inspector without moving the
* camera, and photographs that. Returns the frames and where each screen card, the Inspector and the selected card are.
*/
export async function captureHeroFrames(page, { select, viewport }) {
const shoot = () => page.screenshot({ type: "jpeg", quality: JPEG_QUALITY });
const neutral = () => page.mouse.move(viewport.width - 4, viewport.height - 4);
const rect = locator => locator.boundingBox().then(b => b && { x: Math.round(b.x), y: Math.round(b.y), width: Math.round(b.width), height: Math.round(b.height) });
const camera = () => page.locator(".react-flow__viewport").evaluate(el => el.style.transform);
const target = page.locator(`.screen-screenshot-target[title="${select}"]`);
// A card under the pointer dims the others and highlights its edges; let that fade before the first frame.
await neutral();
await page.waitForTimeout(1000);
const at = await camera();
const selected = await rect(target);
if (!selected) throw new Error(`The hero needs ${select} on the Map.`);
const cards = [];
for (const node of await page.locator(".react-flow__node").all()) {
const b = await rect(node);
if (b && b.x < viewport.width && b.y < viewport.height && b.x + b.width > 0 && b.y + b.height > 0) cards.push(b);
}
const full = await shoot();
const hide = async css => {
const style = await page.addStyleTag({ content: `${css} { visibility: hidden !important; }` });
await page.waitForTimeout(300);
return style;
};
const edges = await hide(".react-flow__edges, .react-flow__edge, .react-flow__edgelabel-renderer");
const screensOnly = await shoot();
const nodes = await hide(".react-flow__node");
const empty = await shoot();
for (const style of [edges, nodes]) await style.evaluate(el => el.remove());
await target.click();
await neutral();
await page.waitForTimeout(1500);
const inspector = await rect(page.locator("aside.right-panel"));
if (!inspector) throw new Error(`Selecting ${select} did not open the Inspector.`);
if ((await camera()) !== at) throw new Error(`The Map's camera moved when ${select} was selected: ${at} → ${await camera()}.`);
const inspecting = await shoot();
return { viewport, empty, screensOnly, full, inspecting, cards, selected, inspector };
}
/**
* The hero: the frames from captureHeroFrames as a window on a rounded 1600×900 stage. Each screen
* card is a clip of the screens-only frame, so what appears is exactly what the Viewer draws.
*/
export function heroSvg(frames, theme, alt) {
const t = STAGE[theme];
const LOOP = 12;
const W = 1600, H = 900;
const { viewport: v } = frames;
const wx = (W - v.width) / 2, wy = (H - v.height) / 2;
const css = [];
const defs = [];
const layers = [];
const image = (id, jpeg) => defs.push(`<image id="${id}" width="${v.width}" height="${v.height}" href="${dataUri(jpeg)}"/>`);
image("empty", frames.empty);
image("screens", frames.screensOnly);
image("full", frames.full);
image("inspecting", frames.inspecting);
// Cards appear a row at a time, top to bottom, as the Map lays out taps from launch; a row's cards left to right.
const PAD = 18;
const rows = [...new Set(frames.cards.map(c => c.y))].sort((a, b) => a - b);
frames.cards.forEach((card, i) => {
const appear = 0.4 + rows.indexOf(card.y) * 0.35 + (card.x / v.width) * 0.3;
const clip = { x: card.x - PAD, y: card.y - PAD, width: card.width + PAD * 2, height: card.height + PAD * 2 };
defs.push(`<clipPath id="c${i}"><rect ${box(clip)}/></clipPath>`);
css.push(`.c${i}{transform-origin:0 0;animation:c${i} ${LOOP}s cubic-bezier(.2,.8,.2,1) infinite}`);
css.push(keyframes(`c${i}`, LOOP, [[0, "opacity:0;transform:scale(.92)"], [appear, "opacity:0;transform:scale(.92)"], [appear + 0.45, "opacity:1;transform:scale(1)"], [LOOP, "opacity:1;transform:scale(1)"]]));
// Scaled about the card's centre: the class sits on a group whose origin is there.
const cx = card.x + card.width / 2, cy = card.y + card.height / 2;
layers.push(`<g transform="translate(${cx} ${cy})"><g class="c${i}"><g transform="translate(${-cx} ${-cy})" clip-path="url(#c${i})"><use href="#screens"/></g></g></g>`);
});
const settled = 0.4 + (rows.length - 1) * 0.35 + 0.75;
// The transitions wipe in from the top: the full frame over the cards, which it draws in the same places.
const EDGES = settled - 0.2, EDGES_END = EDGES + 1.3;
css.push(`.full{animation:full ${LOOP}s cubic-bezier(.45,0,.25,1) infinite}`);
css.push(keyframes("full", LOOP, [[0, "clip-path:inset(0 0 100% 0)"], [EDGES, "clip-path:inset(0 0 100% 0)"], [EDGES_END, "clip-path:inset(0 0 0 0)"], [LOOP, "clip-path:inset(0 0 0 0)"]]));
layers.push(`<use class="full" href="#full"/>`);
// A pointer glides to the selected card and clicks; the selection lands and the Inspector slides in.
const { selected: s, inspector: p } = frames;
const target = { x: s.x + s.width * 0.55, y: s.y + s.height * 0.45 };
const start = { x: Math.min(v.width - 120, target.x + 260), y: Math.min(v.height - 60, target.y + 220) };
const MOVE = EDGES_END + 0.5, CLICK = MOVE + 1.2;
const pointer = (x, y, extra = "") => `transform:translate(${x.toFixed(1)}px,${y.toFixed(1)}px)${extra}`;
css.push(`.ptr{opacity:0;animation:ptr ${LOOP}s cubic-bezier(.4,0,.2,1) infinite}`);
css.push(keyframes("ptr", LOOP, [
[0, `opacity:0;${pointer(start.x, start.y)}`], [MOVE, `opacity:0;${pointer(start.x, start.y)}`], [MOVE + 0.2, `opacity:1;${pointer(start.x, start.y)}`],
[CLICK, `opacity:1;${pointer(target.x, target.y)}`], [CLICK + 0.1, `opacity:1;${pointer(target.x, target.y, " scale(.82)")}`],
[CLICK + 0.25, `opacity:1;${pointer(target.x, target.y)}`], [CLICK + 1.2, `opacity:0;${pointer(target.x, target.y)}`], [LOOP, `opacity:0;${pointer(target.x, target.y)}`],
]));
defs.push(`<clipPath id="canvas"><rect x="0" y="0" width="${p.x}" height="${v.height}"/></clipPath>`);
defs.push(`<clipPath id="panel"><rect ${box(p)}/></clipPath>`);
css.push(`.sel{animation:sel ${LOOP}s ease-out infinite}`);
css.push(keyframes("sel", LOOP, [[0, "opacity:0"], [CLICK + 0.1, "opacity:0"], [CLICK + 0.4, "opacity:1"], [LOOP, "opacity:1"]]));
css.push(`.insp{animation:insp ${LOOP}s cubic-bezier(.2,.8,.2,1) infinite}`);
css.push(keyframes("insp", LOOP, [[0, "opacity:0;transform:translateX(48px)"], [CLICK + 0.15, "opacity:0;transform:translateX(48px)"], [CLICK + 0.75, "opacity:1;transform:translateX(0)"], [LOOP, "opacity:1;transform:translateX(0)"]]));
layers.push(`<use class="sel" href="#inspecting" clip-path="url(#canvas)"/>`);
layers.push(`<g class="insp"><use href="#inspecting" clip-path="url(#panel)"/></g>`);
layers.push(`<g class="ptr"><path d="M0 0L0 22L6 16.5L10.5 26L14 24.5L9.8 15.2L18 15.2Z" fill="#111" stroke="#fff" stroke-width="1.6" stroke-linejoin="round"/></g>`);
// The empty Map covers the reset: it fades in over the last frame, and the loop starts again beneath it.
css.push(`.cover{opacity:0;animation:cover ${LOOP}s linear infinite}`);
css.push(keyframes("cover", LOOP, [[0, "opacity:1"], [0.2, "opacity:0"], [LOOP - 0.7, "opacity:0"], [LOOP, "opacity:1"]]));
layers.push(`<use class="cover" href="#empty"/>`);
css.push("@media (prefers-reduced-motion: reduce){*{animation:none!important}}");
defs.push(`<clipPath id="window"><rect width="${v.width}" height="${v.height}" rx="14"/></clipPath>`);
defs.push(`<filter id="shadow" x="-10%" y="-10%" width="120%" height="125%"><feDropShadow dx="0" dy="2" stdDeviation="2" flood-color="${t.shadow}" flood-opacity=".3"/><feDropShadow dx="0" dy="30" stdDeviation="35" flood-color="${t.shadow}"/></filter>`);
defs.push(`<clipPath id="stage"><rect width="${W}" height="${H}" rx="22"/></clipPath>`);
return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${W} ${H}" width="${W}" height="${H}" role="img" aria-label="${escapeXml(alt)}">`
+ `<style>${css.join("")}</style><defs>${defs.join("")}</defs>`
+ `<g clip-path="url(#stage)"><rect width="${W}" height="${H}" fill="${t.stage}"/>`
+ `<rect x="${wx}" y="${wy}" width="${v.width}" height="${v.height}" rx="14" fill="${t.stage}" filter="url(#shadow)"/>`
+ `<g transform="translate(${wx} ${wy})"><g clip-path="url(#window)"><use href="#empty"/>${layers.join("")}</g>`
+ `<rect x=".5" y=".5" width="${v.width - 1}" height="${v.height - 1}" rx="14" fill="none" stroke="${t.border}"/></g></g></svg>`;
}
/** review.json and an asset reader from a sealed review report's bytes. */
export async function openReport(bytes) {
const reader = new ZipReader(new Uint8ArrayReader(new Uint8Array(bytes)));
const entries = new Map((await reader.getEntries()).map(entry => [entry.filename, entry]));
const read = async name => {
const entry = entries.get(name);
if (!entry) throw new Error(`The report has no ${name}.`);
return Buffer.from(await entry.getData(new Uint8ArrayWriter()));
};
const review = JSON.parse((await read("review.json")).toString("utf8")).review;
return { review, asset: sha => read(`assets/${sha}.png`) };
}
/** A PNG as a JPEG at most `maxHeight` tall, drawn by the browser so the script needs no image library. */
async function toJpeg(browser, png, maxHeight) {
const page = await browser.newPage();
try {
const base64 = await page.evaluate(async ({ png, maxHeight, quality }) => {
const bitmap = await createImageBitmap(await (await fetch(`data:image/png;base64,${png}`)).blob());
const scale = Math.min(1, maxHeight / bitmap.height);
const canvas = document.createElement("canvas");
canvas.width = Math.round(bitmap.width * scale);
canvas.height = Math.round(bitmap.height * scale);
const context = canvas.getContext("2d");
context.imageSmoothingQuality = "high";
context.drawImage(bitmap, 0, 0, canvas.width, canvas.height);
return canvas.toDataURL("image/jpeg", quality).split(",")[1];
}, { png: png.toString("base64"), maxHeight, quality: JPEG_QUALITY / 100 });
return Buffer.from(base64, "base64");
} finally {
await page.close();
}
}
/**
* The surface of the Compare key `key` (the slug of the Viewer's #/compare/<key>, which is the route without its
* slash) in `theme`, among the report's visually modified screens.
*/
export function compareSurface(review, key, theme) {
const route = `/${key}`;
const surface = review.surfaces.find(s => (s.head ?? s.base)?.route === route && s.colorScheme === theme && s.visual?.verdict === "modified");
if (!surface) throw new Error(`No visually modified ${route} in ${theme} in this report; pass --compare <key> from a #/compare/<key> URL.`);
return surface;
}
/** The Compare picture: `surface`'s base capture wiping to its head capture, its changed regions outlined. */
export async function compareSvg(browser, report, surface, theme, alt) {
const t = STAGE[theme];
const LOOP = 7;
const W = 1000, H = 600;
const { baseImage, headImage } = surface;
const PH = 540, PW = Math.round(PH * headImage.width / headImage.height);
const x = (W - PW) / 2, y = (H - PH) / 2;
const k = PW / headImage.width;
const before = dataUri(await toJpeg(browser, await report.asset(baseImage.sha256), PH * 2));
const after = dataUri(await toJpeg(browser, await report.asset(headImage.sha256), PH * 2));
const { pullRequest } = report.review;
const css = [];
// The After capture is revealed left to right, and the divider rides the edge of the reveal.
css.push(`.after{animation:wipe ${LOOP}s cubic-bezier(.65,0,.35,1) infinite}`);
css.push(keyframes("wipe", LOOP, [[0, "clip-path:inset(0 100% 0 0)"], [1.0, "clip-path:inset(0 100% 0 0)"], [2.6, "clip-path:inset(0 0 0 0)"], [5.8, "clip-path:inset(0 0 0 0)"], [6.8, "clip-path:inset(0 100% 0 0)"], [LOOP, "clip-path:inset(0 100% 0 0)"]]));
css.push(`.divider{opacity:0;animation:divider ${LOOP}s cubic-bezier(.65,0,.35,1) infinite}`);
css.push(keyframes("divider", LOOP, [[0, "transform:translateX(0);opacity:0"], [0.8, "transform:translateX(0);opacity:1"], [1.0, "transform:translateX(0);opacity:1"], [2.6, `transform:translateX(${PW}px);opacity:1`], [2.9, `transform:translateX(${PW}px);opacity:0`], [5.8, `transform:translateX(${PW}px);opacity:0`], [6.0, `transform:translateX(${PW}px);opacity:1`], [6.8, "transform:translateX(0);opacity:1"], [LOOP, "transform:translateX(0);opacity:0"]]));
css.push(`.regions{animation:regions ${LOOP}s ease-in-out infinite}`);
css.push(keyframes("regions", LOOP, [[0, "opacity:0"], [2.7, "opacity:0"], [3.1, "opacity:1"], [3.6, "opacity:.3"], [4.1, "opacity:1"], [5.7, "opacity:1"], [6.0, "opacity:0"], [LOOP, "opacity:0"]]));
css.push(`.before-label{opacity:.3;animation:before-label ${LOOP}s linear infinite}.after-label{animation:after-label ${LOOP}s linear infinite}`);
css.push(keyframes("before-label", LOOP, [[0, "opacity:1"], [1.8, "opacity:1"], [2.0, "opacity:.3"], [6.2, "opacity:.3"], [6.4, "opacity:1"], [LOOP, "opacity:1"]]));
css.push(keyframes("after-label", LOOP, [[0, "opacity:.3"], [1.8, "opacity:.3"], [2.0, "opacity:1"], [6.2, "opacity:1"], [6.4, "opacity:.3"], [LOOP, "opacity:.3"]]));
css.push("@media (prefers-reduced-motion: reduce){*{animation:none!important}}");
const regions = surface.visual.regions.map(({ rect: r }) =>
`<rect x="${(x + r.x * k - 3).toFixed(1)}" y="${(y + r.y * k - 3).toFixed(1)}" width="${(r.width * k + 6).toFixed(1)}" height="${(r.height * k + 6).toFixed(1)}" rx="3" fill="none" stroke="${t.region}" stroke-width="2"/>`).join("");
const label = (cls, anchor, lx, title, sub, note) => `<g class="${cls}" font-family="${FONT}" text-anchor="${anchor}">`
+ `<text x="${lx}" y="${y + PH / 2 - 14}" font-size="26" font-weight="700" fill="${t.text}">${title}</text>`
+ `<text x="${lx}" y="${y + PH / 2 + 12}" font-family="${MONO}" font-size="13" fill="${t.muted}">${escapeXml(sub)}</text>`
+ (note ? `<text x="${lx}" y="${y + PH / 2 + 36}" font-size="13" font-weight="600" fill="${t.region}">${note}</text>` : "") + "</g>";
const count = surface.visual.regions.length;
return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${W} ${H}" width="${W}" height="${H}" role="img" aria-label="${escapeXml(alt)}">`
+ `<style>${css.join("")}</style>`
+ `<defs><clipPath id="stage"><rect width="${W}" height="${H}" rx="16"/></clipPath><clipPath id="phone"><rect x="${x}" y="${y}" width="${PW}" height="${PH}" rx="40"/></clipPath>`
+ `<filter id="shadow" x="-20%" y="-20%" width="140%" height="140%"><feDropShadow dx="0" dy="8" stdDeviation="14" flood-color="${t.shadow}"/></filter></defs>`
+ `<g clip-path="url(#stage)"><rect width="${W}" height="${H}" fill="${t.stage}"/>`
+ `<rect x="${x}" y="${y}" width="${PW}" height="${PH}" rx="40" fill="${t.stage}" filter="url(#shadow)"/>`
+ `<g clip-path="url(#phone)"><image href="${before}" x="${x}" y="${y}" width="${PW}" height="${PH}"/>`
+ `<image class="after" href="${after}" x="${x}" y="${y}" width="${PW}" height="${PH}"/></g>`
+ `<rect x="${x}" y="${y}" width="${PW}" height="${PH}" rx="40" fill="none" stroke="${t.border}"/>`
+ `<g class="divider"><rect x="${x - 1.5}" y="${y}" width="3" height="${PH}" fill="${t.accent}"/><circle cx="${x}" cy="${y + PH / 2}" r="13" fill="${t.accent}"/>`
+ `<path d="M${x - 5} ${y + PH / 2 - 4}l-3 4l3 4M${x + 5} ${y + PH / 2 - 4}l3 4l-3 4" stroke="#fff" stroke-width="1.8" fill="none" stroke-linecap="round" stroke-linejoin="round"/></g>`
+ `<g class="regions">${regions}</g>`
+ label("before-label", "end", x - 44, "Before", `${pullRequest.base.ref} ·${pullRequest.base.sha.slice(0, 7)}`)
+ label("after-label", "start", x + PW + 44, "After", `PR #${pullRequest.number} · ${pullRequest.head.sha.slice(0, 7)}`, `${count} changed region${count === 1 ? "" : "s"}`)
+ "</g></svg>";
}
+23 -33
View File
@@ -1,4 +1,4 @@
// Regenerates the Viewer screenshots in docs/screenshots from a review report, in light and dark
// Regenerates the README's pictures in docs/screenshots from a review report, in light and dark
// (the README shows them with <picture>; GitHub Mobile ignores the dark source and shows light). The reference app is euxy
// (github.com/brentvatne/euxy): skills/readme-refresh/SKILL.md says which report to pass and how.
//
@@ -7,8 +7,10 @@
//
// --report a sealed review report (the hosted link's report.zip?platform=ios, or the PR's zip artifact)
// --select the route selected on the hero Map (opens the Inspector); default /settings. The hero zooms in around it
// (--zoom, default 73%) and is framed as a window on a soft stage, like the PR comment
// --compare the Compare key of a modified screen: the slug in the Viewer's #/compare/<key> URL; default patterns
// (--zoom, default 73%) and is an animated SVG of a window on a soft stage (readme-animations.mjs): the
// Map's cards appear, its transitions wipe in, and a click on this screen opens the Inspector
// --compare the Compare key of a modified screen: the slug in the Viewer's #/compare/<key> URL; default patterns.
// It becomes readme-compare-*.svg, its before capture wiping to its after capture
// --pr a GitHub PR URL whose Explore comment becomes readme-pr-comment-light.png (public repository): the comment
// at its own size on a soft stage, cut off with a fade after the list of changed screens
import { chromium } from "@playwright/test";
@@ -16,6 +18,7 @@ import { readFile, writeFile } from "node:fs/promises";
import { parseArgs } from "node:util";
import { fileURLToPath } from "node:url";
import { startReportViewer } from "../test/ci/lib/report-viewer.mjs";
import { captureHeroFrames, compareSurface, compareSvg, heroSvg, openReport } from "./readme-animations.mjs";
const { values: args } = parseArgs({
options: {
@@ -33,15 +36,22 @@ if (!args.report) {
const out = fileURLToPath(new URL("../docs/screenshots/", import.meta.url));
const SHOTS = [
{ file: "readme-hero", hash: "#/map", viewport: { width: 1376, height: 774 }, click: "Fit canvas", select: args.select, zoom: Number(args.zoom), framed: true },
{ file: "readme-compare", hash: `#/compare/${args.compare}`, viewport: { width: 1760, height: 1000 } },
{ file: "readme-hero", hash: "#/map", viewport: { width: 1376, height: 774 }, click: "Fit canvas", select: args.select, zoom: Number(args.zoom), animated: true },
{ file: "readme-screens", hash: "#/screens", viewport: { width: 1760, height: 1000 } },
];
const bytes = await readFile(args.report);
const report = await openReport(bytes);
const { server, url } = await startReportViewer({ bytes, watch: false });
const browser = await chromium.launch();
try {
for (const theme of ["light", "dark"]) {
const surface = compareSurface(report.review, args.compare, theme);
const path = `${out}readme-compare-${theme}.svg`;
await writeFile(path, await compareSvg(browser, report, surface, theme,
`The ${surface.head.route} screen of euxy wiping from its capture before the pull request to its capture after it, with the changed regions outlined`));
console.log(path);
}
for (const theme of ["light", "dark"]) for (const shot of SHOTS) {
const context = await browser.newContext({ viewport: shot.viewport, deviceScaleFactor: 2, colorScheme: theme });
await context.addInitScript(value => localStorage.setItem("expo-explore:theme", value), theme);
@@ -54,8 +64,8 @@ try {
await page.mouse.move(400, shot.viewport.height - 30);
await page.waitForTimeout(1500);
}
if (shot.select) {
// Selecting a screen opens the Inspector without moving the fitted camera.
if (shot.select && !shot.animated) {
// Selecting a screen opens the Inspector without moving the fitted camera. The animated hero selects it last.
await page.locator(`.screen-screenshot-target[title="${shot.select}"]`).click();
await page.mouse.move(400, shot.viewport.height - 30);
await page.waitForTimeout(1500);
@@ -76,12 +86,12 @@ try {
await page.mouse.move(shot.viewport.width - 60, shot.viewport.height / 2);
await page.waitForTimeout(1200);
}
if (shot.hash.startsWith("#/compare/") && !page.url().includes(shot.hash)) {
throw new Error(`Compare key ${args.compare} is not a screen of this report (the Viewer went to ${page.url()}); pass --compare <key> from a #/compare/<key> URL.`);
}
const path = `${out}${shot.file}-${theme}.png`;
if (shot.framed) await writeFile(path, await stagedWindow(browser, await page.screenshot(), shot.viewport, theme));
else await page.screenshot({ path });
const path = `${out}${shot.file}-${theme}.${shot.animated ? "svg" : "png"}`;
if (shot.animated) {
const frames = await captureHeroFrames(page, { select: shot.select, viewport: shot.viewport });
await writeFile(path, heroSvg(frames, theme,
`Explore's Map of a euxy pull request: the screen cards appear row by row, the transitions between them wipe in, then a click selects ${shot.select} and the Inspector opens on it`));
} else await page.screenshot({ path });
console.log(path);
await context.close();
}
@@ -114,26 +124,6 @@ try {
await server.close?.();
}
/**
* A Viewer screenshot as a window on a rounded 1600×900 stage (drawn at 2x), with a hairline border and a soft shadow,
* as the post about Explore frames it. The corners outside the stage stay transparent, so it sits on either GitHub theme.
*/
async function stagedWindow(browser, shot, viewport, theme) {
const dark = theme === "dark";
const stage = dark ? "#151B23" : "#F6F8FA";
const border = dark ? "#3D444D" : "#D1D9E0";
const shadow = dark ? "0 2px 4px rgba(1,4,9,0.4), 0 30px 70px rgba(1,4,9,0.6)" : "0 2px 4px rgba(17,17,17,0.04), 0 30px 70px rgba(17,17,17,0.14)";
const context = await browser.newContext({ viewport: { width: 1600, height: 900 }, deviceScaleFactor: 2 });
const page = await context.newPage();
await page.setContent(`<!doctype html><html><body style="margin:0;background:transparent">
<div id="stage" style="position:relative;width:1600px;height:900px;background:${stage};border-radius:22px;overflow:hidden">
<img src="data:image/png;base64,${shot.toString("base64")}" style="position:absolute;left:${(1600 - viewport.width) / 2}px;top:${(900 - viewport.height) / 2}px;width:${viewport.width}px;height:${viewport.height}px;box-sizing:border-box;border:1px solid ${border};border-radius:14px;box-shadow:${shadow}">
</div></body></html>`);
const png = await page.locator("#stage").screenshot({ omitBackground: true });
await context.close();
return png;
}
/**
* The comment on a rounded stage as wide as the README column (880 px, drawn at 2x), with a soft shadow and a fade at
* the cut. The corners outside the stage stay transparent, so the image sits on either GitHub theme.
+18 -10
View File
@@ -1,6 +1,6 @@
---
name: readme-refresh
description: Refresh Expo Explore's README.md with euxy (github.com/brentvatne/euxy) as the reference app. Regenerate every screenshot in docs/screenshots from a current euxy review report and PR comment, then re-read the README as a first-time user: the top level only says what Explore does, links the live euxy example, gives one quick-start prompt to copy that reviews a change to your own app or explores a build you point it to, and one for setting up CI; everything else lives in collapsibles. Use after a Viewer or PR-comment change that the README shows, a new command or setting, or a release that made a README claim stale. Not for the docs/ guides or the shipped skills.
description: Refresh Expo Explore's README.md with euxy (github.com/brentvatne/euxy) as the reference app. Regenerate every screenshot and animated SVG in docs/screenshots from a current euxy review report and PR comment, then re-read the README as a first-time user: the top level only says what Explore does, links the live euxy example, gives one quick-start prompt to copy that reviews a change to your own app or explores a build you point it to, and one for setting up CI; everything else lives in collapsibles. Use after a Viewer or PR-comment change that the README shows, a new command or setting, or a release that made a README claim stale. Not for the docs/ guides or the shipped skills.
---
# Refresh the README
@@ -24,17 +24,25 @@ scripts/refresh-viewer-preview-fixtures.sh '<hosted link>' brentvatne/euxy#<n>
Do not pick a same-tree demo PR, where every change is noise. The refreshed fixtures reach the live example on the next push to main, or when you run **Example report** from GitHub Actions. `curl -s "<hosted link>/api/v1/screens?status=added,removed,modified&platform=ios"` lists what changed, which tells you which screen to select and compare.
## 2. Regenerate every screenshot
## 2. Regenerate every screenshot and animation
```sh
npm ci
node scripts/readme-screenshots.mjs --report ~/euxy-report/ios.zip --select /settings --compare patterns --pr https://github.com/brentvatne/euxy/pull/<n>
node scripts/readme-screenshots.mjs --report ~/euxy-report/ios.zip --select /about --compare patterns --pr https://github.com/brentvatne/euxy/pull/<n>
```
- `--select` is the route selected on the hero Map (the Inspector opens on it): choose an added or clearly modified screen.
- `--compare` is the key in the Viewer's `#/compare/<key>` URL for a **modified** screen with outlined regions (open the report, click the screen in Compare, copy the key). The script fails if the key is not in the report.
- `--select` is the route the hero's pointer clicks on the Map (the Inspector opens on it): choose an added or clearly modified screen. The script zooms in around it, so it must be a screen the Map shows.
- `--compare` is the key in the Viewer's `#/compare/<key>` URL for a **modified** screen with outlined regions (open the report, click the screen in Compare, copy the key): the route without its slash. The script fails if the report has no visually modified screen at that route.
- `--pr` screenshots the Explore comment on that PR: the fixtures' `source`. Headless Chromium needs a colour emoji font for the result glyphs (`sudo apt-get install fonts-noto-color-emoji` on Debian/Ubuntu); a comment with hollow boxes where 🟩 should be is not acceptable.
- The script serves the report through the Viewer's Vite dev server, so no build is needed. It writes a `-light` and a `-dark` PNG for every shot (the PR comment too: signed-out github.com follows `prefers-color-scheme`). The README shows each pair with `<picture>`: a `<source media="(prefers-color-scheme: dark)">` for the dark file and an `<img>` with the alt text and the light file, which is what GitHub Mobile shows (it ignores the dark source), so the light file is the one that must always be right.
- The script serves the report through the Viewer's Vite dev server, so no build is needed. It writes a `-light` and a `-dark` file for every picture (the PR comment too: signed-out github.com follows `prefers-color-scheme`). The README shows each pair with `<picture>`: a `<source media="(prefers-color-scheme: dark)">` for the dark file and an `<img>` with the alt text and the light file, which is what GitHub Mobile shows (it ignores the dark source), so the light file is the one that must always be right.
Two of the pictures are animated SVGs, built by `scripts/readme-animations.mjs` in the same run; there is nothing else to run when the screenshots change:
- `readme-hero-*.svg` is made of real Viewer frames at the zoomed Map camera: the Map without screens, the screens without edges, the whole Map, and the Map after the pointer clicks `--select`. The cards appear row by row, the edges wipe in from the top, then the pointer clicks and the Inspector slides in. Each is about 1.4 MB: four 2x JPEG frames inlined, since an SVG shown with `<img>` can load nothing. Anything the Viewer draws on the Map or in the Inspector shows up here on the next run, so regenerate it after a Viewer change the hero shows.
- `readme-compare-*.svg` is the `--compare` screen's base capture wiping to its head capture, with the report's changed regions pulsing. It is drawn from `review.json` and the report's assets, not from a Viewer screenshot, so a Viewer change does not stale it, but a new report does.
- Both loop on CSS keyframes, and with `prefers-reduced-motion` they hold the last frame: Inspector open, regions outlined. That frame is also what a viewer that does not animate SVG shows, so it must read on its own.
Open each SVG in a browser before committing, light and dark, and watch a full loop: every card should appear once and land where the whole Map has it, with no hover highlight in the frames before the click; the pointer should click the `--select` card; the Inspector should open on that screen; Compare's outlines should sit on the changed text, not beside it. To look at one moment, pause the animations in the console: `document.getAnimations().forEach(a => { a.pause(); a.currentTime = 5000; })`. Keep the README's `<img>` and `<source>` pointing at the `.svg` files.
`docs/screenshots/readme-exploration-light.png` is the black-box map and comes from a euxy `explore:binary` run (`npx @expo/explore explore:binary <euxy simulator build> --no-upload`, then `expo-explore view --dir <output>` at 1760×1000, Map, Fit canvas). It has no dark variant and is a plain Markdown image. Regenerate it when the Map's rendering of edges or labels changed; otherwise keep it, and say so in the PR.
@@ -53,18 +61,18 @@ cd - && npm run build:cli && node scripts/readme-reports-rows.mjs > /tmp/reports
- The script renders the picker as the CLI draws it (96 columns, the newest run selected) and writes the terminal body as HTML: each coloured piece is exactly its characters wide, so columns line up, and the wordmark is drawn as cell rectangles, since a design tool's font does not draw `█▀▄` cell for cell.
- In Paper, replace the frame named "Terminal" inside each artboard's window with that HTML, check both artboards in a screenshot (crisp wordmark, aligned columns, the selected row highlighted to the end, coloured counts), and export both at 2x as `readme-reports-light.png` and `readme-reports-dark.png`. The window's title bar reads `npx @expo/explore reports`, as people run it.
Look at every PNG you produced before committing, light and dark: the selected screen should be the one you asked for, the Compare view must show Before and After with outlines, the Screens grid must show the added, removed and modified status dots, the PR comment must show the heading links and result glyphs. Describe each in its Markdown alt text as what the picture shows, not what the feature is.
Look at every PNG you produced before committing, light and dark: the Screens grid must show the added, removed and modified status dots, the PR comment must show the heading links and result glyphs. Describe each in its Markdown alt text as what the picture shows, not what the feature is.
## 3. Pass over the content as a first-time user
Read the README top to bottom once without opening a collapsible. At that level it may only answer, in this order:
1. What Explore is (one short paragraph), the hero image, and the link to the live euxy example (`explore-example--euxy.expo.app`, redeployed on every merge to main by `.github/workflows/example-report.yml`). Under it, one table row of three pictures with a one-line caption each: Compare, Screens, and the PR comment (which says it needs CI), then the agent prompt collapsed as **Ask an agent about a report**. The hero is a zoomed Map framed as a window on a stage (`stagedWindow` in the script); the three below are plain.
2. **Quick start**: one path. A single prompt to paste into Claude Code or Codex that reviews a change to the reader's own Expo app through the explore-setup skill's "Review a change on this machine" section, or, when they point it to a build (or the app is not an Expo project), explores a simulator build through the explore-binary skill. Then one sentence on what each case needs (a review needs an Expo account, is built on EAS, and is captured on EAS Simulator or a local simulator; exploring a build needs a Claude Code or Codex login and EAS Simulator or a local simulator, and no Expo account locally). Then one **Run it yourself** collapsible with both by hand: the numbered steps for a review, with nothing optional in them (make the app buildable on EAS: login, init, bundle identifier, a simulator profile named `explore`, and commit, since the before build is the last commit; then edit a screen near its top and run `capture`, or `capture --simulator local`), and the `explore:binary` commands, including `--simulator local`. Then the `reports` picker image (`readme-reports-*.png`) with one sentence on saved runs, at the top level, and one collapsible for other commits (`--committed`, `--base`/`--head`) and what a review does on the machine. Run the steps on a fresh `create-expo-app` before changing them.
1. What Explore is (one short paragraph), the hero image, and the link to the live euxy example (`explore-example--euxy.expo.app`, redeployed on every merge to main by `.github/workflows/example-report.yml`). Under it, Compare at full width with a one-line caption, then one table row of two pictures with a one-line caption each: Screens and the PR comment (which says it needs CI), then the agent prompt collapsed as **Ask an agent about a report**. The hero is the animated zoomed Map, framed as a window on a stage, and Compare is the animated wipe (both from `readme-animations.mjs`); the Screens and PR comment pictures are PNGs. Compare gets its own row because a phone wiping from before to after is unreadable at a third of the column.
2. **Quick start**: one path. A single prompt to paste into Claude Code or Codex that reviews a change to the reader's own Expo app through the explore-setup skill's "Review a change on this machine" section, or, when they point it to a build (or the app is not an Expo project), explores a simulator build through the explore-binary skill. Then one sentence on what each case needs (a review needs an Expo account, is built on EAS, and is captured on EAS Simulator or a local simulator; exploring a build needs a Claude Code or Codex login and EAS Simulator or a local simulator, and no Expo account locally), and under it one `> [!NOTE]` alert: EAS Simulator is in preview, with the waitlist link and `--simulator local` as the alternative. Then one **Run it yourself** collapsible with both by hand: the numbered steps for a review, with nothing optional in them (make the app buildable on EAS: login, init, bundle identifier, a simulator profile named `explore`, and commit, since the before build is the last commit; then edit a screen near its top and run `capture`, or `capture --simulator local`), and the `explore:binary` commands, including `--simulator local`. Right after **Run it yourself**, one `> [!WARNING]` alert: a review runs both commits' code on the reader's machine, so review only commits they would run. These are the README's only two alerts; do not add more, or they stop standing out. Then the `reports` picker image (`readme-reports-*.png`) with one sentence on saved runs, at the top level, and one collapsible for other commits (`--committed`, `--base`/`--head`) and what a review does on the machine. Run the steps on a fresh `create-expo-app` before changing them.
3. **Map every screen of any app**: one sentence on what exploring a build shows (pointing back to the quick start, which runs it), then its collapsibles: its options, exploring a session already started, and what a run without source shows.
4. **Set up CI**: one sentence, then two subsections, each a sentence on what it gives and a prompt to paste: **Review on every PR** (the setup prompt, then a few grouped collapsibles: Hosted previews first, then Manual setup (the setup prompt's steps done by hand, in order: setup, doctor, secrets, baseline, first PR), Capture modes: deterministic or agent, iOS, Android, or both, Keep your setup current) and **Compare any two commits** (a prompt that follows the explore-setup skill's "Compare any two commits" section, the ways to snapshot a release as bullets, then the comparison workflow collapsed).
Lead with prompts, not explanations: a reader should be able to copy something and see Explore work. Everything else, the manual commands, requirements, options, the manual setup, capture modes, hosted previews, iOS and Android, agent mode, repository settings, how agents read a report, how it works, limitations, contributing, goes into a `<details>` block under the section it belongs to, with a `<summary>` that says what the reader will find. Keep bullets to one or two sentences. Group related collapsibles rather than adding one per topic, so a section shows a handful, not nine. Requirements sit collapsed right under the example report link. Keep the collapsibles' `id` attributes that other docs link to (`#hosted-previews`, `#platforms`, `#compare`, `#agents`); the Terms and How agents read a report collapsibles live under Additional information, and keep the Inspiration section (screenmap and Revyl's Atlas).
Lead with prompts, not explanations: a reader should be able to copy something and see Explore work. Everything else, the manual commands, requirements, options, the manual setup, capture modes, hosted previews, iOS and Android, agent mode, repository settings, how agents read a report, how it works, limitations, contributing, goes into a `<details>` block under the section it belongs to, with a `<summary>` that says what the reader will find. Keep bullets to one or two sentences. Group related collapsibles rather than adding one per topic, so a section shows a handful, not nine. Requirements sit collapsed right under the example report link. The **How it works** collapsible opens with a Mermaid `sequenceDiagram` of a PR review (pull request, GitHub Actions, EAS Build, EAS Simulator), followed by the facts it cannot show as bullets: who triggers a review, what Modified means, session retries. Check its steps against `CI-FLOW.md` and the `ci:*` commands, and edit the diagram's text, not a picture: GitHub draws it. Keep the collapsibles' `id` attributes that other docs link to (`#hosted-previews`, `#platforms`, `#compare`, `#agents`); the Terms and How agents read a report collapsibles live under Additional information, and keep the Inspiration section (screenmap and Revyl's Atlas).
Check that each prompt still works as written:
- the skill links it names (`https://unpkg.com/@expo/explore/skills/...`) are files the package ships (`files` in `package.json`), and they open from the published release;
+20 -16
View File
@@ -1,5 +1,4 @@
import { createHash, randomUUID } from "node:crypto";
import { createRequire } from "node:module";
import { lstat, mkdir, mkdtemp, readFile, realpath, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
@@ -17,13 +16,14 @@ import { agentDeviceLauncher, ensureArgentToolServer, ensureController } from ".
import { agentDeviceClaims, approveLinkScheme, createLocalSimulator, deleteLocalEmulator, deleteLocalSimulator, hostEmulatorAbi, installOnLocalEmulator, installOnLocalSimulator, startLocalArgentServer,
startLocalEmulator, stopLocalAgentDevice, stopLocalArgentServer, waitForLocalEmulator, waitForLocalSimulator, type LocalArgentServer } from "../capture/local-simulator.js";
import { openLocalCaptureRecord, sweepLocalCaptures } from "../capture/local-registry.js";
import { approveSessionUrlSchemes, simulatorControlActions, type EasCommand } from "../capture/simulator-control.js";
import { DEFAULT_ANDROID_DEVICE } from "../config/explore-config.js";
import { createExplorationInputs } from "../config/exploration-inputs.js";
import { ExploreStore, getCoverage } from "../map/store.js";
import { whoamiAccounts } from "../report/preview-deploy.js";
import { CiError, serializeCiError, toCiError } from "../shared/ci-errors.js";
import { packageBin } from "../shared/package-paths.js";
import { assertDecodedPng, type DecodedFrame } from "../shared/png-evidence.js";
import { assertDecodedPng, solidColour } from "../shared/png-evidence.js";
import { CONTRACT, type ExploreMap, type Platform } from "../types.js";
import { assertEmulatorCompatible, extractIosBundle, inspectArchive, type ArchiveKind, type InspectedArchive, readArchiveIcon } from "./archive.js";
import { runBlackBoxExploration, type BlackBoxExplorerResult, type BlackBoxFrame, SYSTEM_DIALOG_PACKAGES } from "./explorer.js";
@@ -277,6 +277,8 @@ export type ConnectedSessionExploration = {
* serial (agent-device with a daemon of its own in `stateDirectory`, or a local Argent tool-server pinned to it).
*/
local?: { deviceId: string; osVersion: string; stateDirectory: string };
/** Runs once the app is installed and before anything opens it, as an EAS session's link approval must. */
afterInstall?: () => void;
};
/** Drives an agent-device daemon we already hold a connection to: optional install, open, then the model-led exploration. */
@@ -317,6 +319,7 @@ export async function exploreConnectedSession(ctx: ConnectedSessionExploration):
try { controller(["install", install.path, "--json"], 15 * 60_000); }
catch (error) { throw binaryError("APP_INSTALL_FAILED", `${controllerName} could not install the app: ${failureText(error)}`, "Check that the archive is a simulator build for this platform and under the size limit, then rerun.", { sessionId: connection.sessionId }); }
}
ctx.afterInstall?.();
// On a local device, the first open also builds agent-device's iOS runner.
const opened = controller(["open", bundleId, "--level", "full", "--json"], local ? 15 * 60_000 : 2 * 60_000);
const openedDevice = openedSimulatorDevice(opened.stdout, bundleId, "initial app open", platform, controllerSession);
@@ -714,7 +717,8 @@ export async function runBinaryExploration(options: BinaryExploreOptions): Promi
let installPath = archive.path;
if (archive.kind === "ios-tgz" || archive.kind === "ios-ipa") { say("unpacking the iOS bundle"); installPath = await extractIosBundle(archive, join(work, "bundle")); }
const appIcon = await readArchiveIcon(archive);
const exploreOn = (connection: SimulatorConnection, sessionJson: () => string, localDevice?: LocalDevice) => exploreConnectedSession({ connection, platform, device, bundleId,
const exploreOn = (connection: SimulatorConnection, sessionJson: () => string, localDevice?: LocalDevice, afterInstall?: () => void) => exploreConnectedSession({ connection, platform, device, bundleId,
...(afterInstall ? { afterInstall } : {}),
...(appIcon ? { appIcon } : {}), app: { name: archive.appName, ...(archive.version ? { version: archive.version } : {}) },
// A local device has the app installed by simctl or adb before the controller starts.
...(localDevice ? { local: localDevice } : { install: { path: installPath, kind: archive.kind } }),
@@ -770,7 +774,18 @@ export async function runBinaryExploration(options: BinaryExploreOptions): Promi
if (handoff.validationError) throw handoff.validationError;
if (!handoff.connection) throw new Error("Simulator handoff is missing its controller connection");
await rm(dotenvPath, { force: true });
({ runtime, exploration } = await exploreOn(handoff.connection, () => eas(["simulator:get", "--id", handoff.connection!.sessionId, "--json", "--non-interactive"], 2 * 60_000).stdout));
// The app's own links open without iOS asking first, when the session's host can approve them (serve-sim 0.10.0).
const verifiedSession = sessionId;
const sessionEas: EasCommand = (args, commandOptions) => {
const result = eas(args, commandOptions?.timeoutMs);
if (result.status !== 0 && !commandOptions?.allowFailure) throw new Error(lastLine(result.stderr || result.stdout) || `eas ${args[0]} failed`);
return result;
};
const afterInstall = platform === "ios" && archive.urlSchemes.length ? () => {
const approved = approveSessionUrlSchemes(sessionEas, verifiedSession, simulatorControlActions(sessionEas, verifiedSession), bundleId, archive.urlSchemes);
if (approved.length) say(`approved ${approved.map(item => `${item}://`).join(", ")} links on the session`);
} : undefined;
({ runtime, exploration } = await exploreOn(handoff.connection, () => eas(["simulator:get", "--id", handoff.connection!.sessionId, "--json", "--non-interactive"], 2 * 60_000).stdout, undefined, afterInstall));
}
} catch (error) {
primaryError = toCiError(error, { code: "EXPLORE_BINARY_FAILED", stage: "exploration", nextAction: "Inspect the diagnostic, correct the failing prerequisite, and rerun explore:binary." });
@@ -839,18 +854,7 @@ export function assertAppUrl(url: string, appSchemes: readonly string[] = []): v
export const BLANK_SCREENSHOT_MESSAGE = "The app blocks screen capture on this screen (Android FLAG_SECURE), so its screenshot came back blank.";
/** A capture-protected screen comes back as a single flat colour (black on Android); every 97th pixel is enough to tell. */
export function solidColour(png: Buffer): boolean {
let frame: DecodedFrame;
try { frame = createRequire(import.meta.url.replace(/\?.*$/, ""))("pngjs").PNG.sync.read(png, { checkCRC: false }) as DecodedFrame; }
catch { return false; }
const { data } = frame;
if (data.length < 4) return false;
for (let offset = 0; offset + 3 < data.length; offset += 4 * 97) {
if (data[offset] !== data[0] || data[offset + 1] !== data[1] || data[offset + 2] !== data[2]) return false;
}
return true;
}
export { solidColour };
/** Setup commands whose last positional is free text (`fill <ref> <text>`, `type <text>`): move the flags ahead of a `--` separator. */
export function guardPositionals(args: readonly string[]): string[] {
+1 -1
View File
@@ -16,7 +16,7 @@ export async function prepareCiExploration(config: ExploreConfig, project: strin
if (!active) return { instructionsSha256: instructions?.sha256, agent: undefined };
const inputs = createExplorationInputs({ ...(instructions ? { instructions: instructions.text } : {}),
...(config.setup ? { setup: config.setup } : {}), environment });
if (config.mode !== "agent") return { instructionsSha256: undefined, agent: undefined };
if (config.mode === "deterministic") return { instructionsSha256: undefined, agent: undefined };
if (!options.subscription) assertExecutionMode(config, environment);
const tracked = spawnSync("git", ["-C", project, "ls-files", "--error-unmatch", "--", config.agent!.instructions!], { encoding: "utf8" });
if (tracked.status !== 0) throw new CiError({ code: "AGENT_INSTRUCTIONS_UNCOMMITTED", stage: "preflight",
+29 -7
View File
@@ -301,7 +301,8 @@ export async function runBridgeCommand(argv: readonly string[], context: ArgentB
/** Reads are resent after a transport failure (they change nothing); a UI action is sent once, after a health check. */
const call = async (tool: string, args: Record<string, unknown> = {}, options?: { out?: string }): Promise<Record<string, unknown>> => {
const withDevice = tool === "list-devices" ? args : { udid: state.udid, ...args };
// Tools that name devices their own way (or none) take no udid.
const withDevice = tool === "list-devices" || tool === "stop-all-simulator-servers" ? args : { udid: state.udid, ...args };
for (let attempt = 0; ; attempt++) {
try { return record(await context.call(tool, withDevice, options)); }
catch (error) {
@@ -619,6 +620,10 @@ export async function runBridgeCommand(argv: readonly string[], context: ArgentB
const posture = positional[0];
if (posture !== "closed" && posture !== "half-open" && posture !== "open") throw new BridgeFailure("INVALID_ARGS", "fold needs closed, half-open or open.");
await beforeAction();
// Helpers the tool-server started before a fold can leave the panel it lights black and unread: on a fresh EAS
// session, whose tool-server started them at boot, the first fold opened to a black inner panel every time
// without this, and read the panel at once with it. A local tool-server is Explore's own and starts clean.
await call("stop-all-simulator-servers", { devices: [state.udid] });
const folded = await call("fold", { posture });
// The other panel lights at another size: every stored coordinate and element reference is stale.
delete state.screen;
@@ -630,16 +635,33 @@ export async function runBridgeCommand(argv: readonly string[], context: ArgentB
const lit = record(folded.screen);
if (finite(lit.width) && finite(lit.height) && lit.height > 0) {
const litRatio = lit.width / lit.height;
let followed = false;
for (let poll = 0; poll < 10 && !followed; poll++) {
const shape = (await tree()).screen;
followed = !!shape && shape.height > 0 && Math.abs(shape.width / shape.height - litRatio) < 0.004;
if (!followed) await context.sleep(1_000);
const follows = async () => {
for (let poll = 0; poll < 10; poll++) {
const shape = (await tree()).screen;
if (shape && shape.height > 0 && Math.abs(shape.width / shape.height - litRatio) < 0.004) return true;
await context.sleep(1_000);
}
return false;
};
// A reader still stuck on the dark panel is reset once more (the device's helpers, as reset-reader does): it is
// cheap and leaves the app alone. If that is not enough, capture restarts SpringBoard and folds again.
if (!await follows() && !await call("stop-all-simulator-servers", { devices: [state.udid] }).then(follows, () => false)) {
throw new BridgeFailure("CONTROLLER_FOLD_UNVERIFIED", `Argent kept reading the other panel after folding the device ${posture}, and after its device helpers were reset.`);
}
if (!followed) throw new BridgeFailure("CONTROLLER_FOLD_UNVERIFIED", `Argent kept reading the other panel after folding the device ${posture}.`);
}
return success({ action: "fold", pose: posture, ...(folded.panel !== undefined ? { panel: folded.panel } : {}) });
}
case "reset-reader": {
// Stops the device's Argent helpers, among them the accessibility service describe reads through; the
// tool-server starts fresh ones on the next call. It is how a reader stuck on the panel a fold turned off is
// reset where the tool-server itself cannot be restarted, as on EAS (it started it; never stop it there).
await ensureDevice();
const stopped = await call("stop-all-simulator-servers", { devices: [state.udid] });
delete state.screen;
delete state.refs;
state.generation += 1;
return success({ action: "reset-reader", stopped: Array.isArray(stopped.stopped) ? stopped.stopped.filter(item => typeof item === "string") : [] });
}
case "apps": return success({ apps: [] });
case "session": return success({ sessions: [] });
// TODO(argent#1509): map `settings appearance <scheme>` to Argent's `set-appearance` once a release with it is pinned.
+1 -1
View File
@@ -1,6 +1,6 @@
import { CiError } from "../shared/ci-errors.js";
export const EAS_CLI_VERSION = "25.0.0";
export const EAS_CLI_VERSION = "25.2.0";
export { AGENT_DEVICE_VERSION } from "../shared/agent-device-version.js";
export const CONTROLLER_SESSION = "expo-explore-runtime";
-101
View File
@@ -1,101 +0,0 @@
/**
* Reads what an e2e run (the `e2e` package's `report.json`) says about each flow: its status, its steps, and the
* frames `app.screenshot(label)` took. Nothing here touches a device; the worker produces the report and the host
* turns these summaries into bundle evidence.
*/
import type { FlowStatus, FlowStepStatus } from "../../contracts/capture.js";
export type FlowFrameSummary = { key: string; label: string; path: string; stepIndex: number; capturedAt: string };
export type FlowStepSummary = { api: string; label: string; status: FlowStepStatus; durationMs: number; frame?: string; error?: { code: string; message: string };
/** The line of the test file the step was called from, when e2e recorded one. */
line?: number };
export type FlowTestSummary = {
id: string; file: string; title: string; status: FlowStatus; durationMs: number;
error?: { code: string; message: string };
/** The line of the test file the test is declared on, when e2e recorded one. */
line?: number;
steps: FlowStepSummary[];
frames: FlowFrameSummary[];
};
const FLOW_STATUSES: readonly FlowStatus[] = ["passed", "failed", "skipped", "flaky", "timed-out", "interrupted", "blocked"];
const STEP_STATUSES: readonly FlowStepStatus[] = ["passed", "failed", "blocked", "timed-out", "cancelled"];
const isRecord = (value: unknown): value is Record<string, unknown> => Boolean(value) && typeof value === "object" && !Array.isArray(value);
const text = (value: unknown, fallback = ""): string => typeof value === "string" ? value : fallback;
const count = (value: unknown): number => typeof value === "number" && Number.isFinite(value) && value >= 0 ? Math.round(value) : 0;
/** A path segment from free text: lower case, `-` between words, at most 64 characters, never empty. */
export function flowSlug(value: string): string {
const slug = value.toLowerCase().replace(/\.e2e\.[cm]?[jt]sx?$/, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64).replace(/-+$/, "");
return slug || "flow";
}
/** The flow's identity across revisions: its file (without `tests/` and the extension) and its title, both slugged. */
export function flowId(file: string, titlePath: readonly string[]): string {
const stem = file.replace(/\\/g, "/").replace(/^(\.\/)?(tests?|e2e|flows)\//, "");
return `${flowSlug(stem)}/${flowSlug(titlePath.join(" "))}`;
}
function serializedError(value: unknown): { code: string; message: string } | undefined {
if (!isRecord(value)) return undefined;
return { code: text(value.code, "ERROR").slice(0, 64), message: text(value.message).slice(0, 2_000) };
}
/** Every selected test of the report, with the attempt the run counted (the last one). */
/** A frame the worker took after a step ended, when the capture asks for a frame per step. */
export type StepFrameFile = { stepIndex: number; path: string; capturedAt: string };
export function summarizeFlowReport(report: unknown, stepFrames?: ReadonlyMap<string, readonly StepFrameFile[]>): FlowTestSummary[] {
if (!isRecord(report) || !isRecord(report.run) || !Array.isArray(report.run.results)) throw new Error("The e2e report has no run results");
const artifacts = new Map<string, Record<string, unknown>>();
const summaries: FlowTestSummary[] = [];
for (const result of report.run.results) {
if (!isRecord(result) || result.selected === false) continue;
const file = text(result.file);
const titlePath = Array.isArray(result.titlePath) ? result.titlePath.filter((part): part is string => typeof part === "string") : [];
const attempts = Array.isArray(result.attempts) ? result.attempts.filter(isRecord) : [];
const attempt = attempts.at(-1);
for (const artifact of Array.isArray(attempt?.artifacts) ? attempt.artifacts : []) if (isRecord(artifact) && typeof artifact.id === "string") artifacts.set(artifact.id, artifact);
const status = FLOW_STATUSES.includes(result.status as FlowStatus) ? result.status as FlowStatus : "failed";
const steps: FlowStepSummary[] = [];
const frames: FlowFrameSummary[] = [];
const keys = new Map<string, number>();
for (const step of Array.isArray(attempt?.steps) ? attempt.steps.filter(isRecord) : []) {
const summary: FlowStepSummary = { api: text(step.api, "step").slice(0, 64), label: text(step.label).slice(0, 256),
status: STEP_STATUSES.includes(step.status as FlowStepStatus) ? step.status as FlowStepStatus : "failed", durationMs: count(step.durationMs) };
const error = serializedError(step.error);
if (error) summary.error = error;
if (isRecord(step.source) && step.source.file === file && Number.isSafeInteger(step.source.line) && (step.source.line as number) > 0) summary.line = step.source.line as number;
if (summary.api === "app.screenshot" && summary.status === "passed" && Array.isArray(step.artifacts) && step.artifacts.length === 1) {
const artifact = artifacts.get(String(step.artifacts[0]));
if (artifact?.kind === "screenshot" && typeof artifact.path === "string") {
const base = flowSlug(summary.label || "screenshot");
const seen = (keys.get(base) ?? 0) + 1;
keys.set(base, seen);
const key = seen === 1 ? base : `${base}-${seen}`;
summary.frame = key;
frames.push({ key, label: summary.label, path: artifact.path, stepIndex: steps.length, capturedAt: text(step.startedAt) });
}
}
steps.push(summary);
}
// Per-step frames fill in the steps that took no frame of their own, in the step's place.
for (const file of stepFrames?.get(text(result.testId) || text(result.id)) ?? []) {
const step = steps[file.stepIndex];
if (!step || step.frame !== undefined) continue;
const base = `step-${file.stepIndex + 1}`;
const seen = (keys.get(base) ?? 0) + 1;
keys.set(base, seen);
const key = seen === 1 ? base : `${base}-${seen}`;
step.frame = key;
frames.push({ key, label: `${file.stepIndex + 1}. ${step.label || step.api}`.slice(0, 80), path: file.path, stepIndex: file.stepIndex, capturedAt: file.capturedAt });
}
frames.sort((a, b) => a.stepIndex - b.stepIndex);
const summaryError = serializedError(attempt?.error);
const line = isRecord(result.source) && result.source.file === file && Number.isSafeInteger(result.source.line) && (result.source.line as number) > 0 ? result.source.line as number : undefined;
summaries.push({ id: flowId(file, titlePath), file, title: titlePath.join(" › "), status, durationMs: count(attempt?.durationMs),
...(summaryError ? { error: summaryError } : {}), ...(line ? { line } : {}), steps, frames });
}
return summaries;
}
-140
View File
@@ -1,140 +0,0 @@
/**
* Runs the app's e2e flows on the capture's device and turns the frames they took into bundle evidence. The flows
* are the `e2e` package's test files; Explore adds nothing to their language. A flow that fails keeps the frames it
* took before failing, and the capture goes on: flows are review evidence, not a gate.
*/
import { createHash } from "node:crypto";
import { copyFile, lstat, mkdir, readFile, readdir, realpath, rm, writeFile, mkdtemp, rmdir } from "node:fs/promises";
import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
import { fileURLToPath } from "node:url";
import { homeIndicatorBandPercent, statusBarBandPercent, type BundleFlow, type FlowFrame } from "../../contracts/capture.js";
import { assertDecodedPng, contentSha256 } from "../../shared/png-evidence.js";
import { CONTROLLER_SESSION } from "../common.js";
import type { CommandRunner } from "../run.js";
import type { SimulatorConnection } from "../simulator.js";
import type { FlowsRequest, FlowsResult } from "./worker.js";
export const FLOWS_WORKER = fileURLToPath(new URL("./worker-main.js", import.meta.url));
/** The agent-device session the flows drive the device under, beside Explore's own locked session. */
/**
* The agent-device session the flows use: Explore's own. A daemon lets one session hold a device; a second session name
* connects but cannot open the app ("Device is already in use by session expo-explore-runtime", seen on EAS Simulator).
*/
export const FLOWS_SESSION = CONTROLLER_SESSION;
/** Where e2e writes while the flows run, inside the app directory as e2e requires; removed once the frames are copied out. */
export const FLOWS_OUTPUT_DIRECTORY = ".expo-explore-flows";
const MAX_FRAME_BYTES = 30 * 1024 * 1024;
export type RunFlowsOptions = {
project: string;
tests: readonly string[];
platform: "ios" | "android";
bundleId: string;
connection?: SimulatorConnection | undefined;
/** The local agent-device daemon's state directory when the capture has no session daemon. */
stateDir?: string | undefined;
deviceId?: string | undefined;
/** The capture's private directory: the request, e2e's output and report go under it. */
workDirectory: string;
/** The bundle directory the frames are exported into, under `flows/`. */
outputDirectory: string;
runner: CommandRunner;
environment: NodeJS.ProcessEnv;
timeoutMs: number;
agent?: { provider: "openai" | "anthropic"; model: string } | undefined;
/** `steps`: a frame after every step of every flow, not only where a flow calls app.screenshot. */
frames?: "checkpoints" | "steps" | undefined;
progress?: ((message: string) => void) | undefined;
/** Tests only: an engine module in place of agent-device. */
engineModule?: string | undefined;
};
export type FlowsOutcome = { flows: Record<string, BundleFlow>; failure?: { code: string; message: string } };
/** The relative bundle path of a flow frame. */
export const flowFramePath = (flowId: string, key: string): string => `flows/${flowId}/${key}.png`;
export async function runFlows(options: RunFlowsOptions): Promise<FlowsOutcome> {
const say = options.progress ?? (() => {});
const work = join(options.workDirectory, "flows");
await mkdir(work, { recursive: true, mode: 0o700 });
// e2e keeps its report and screenshots inside the project it tests, so they live in the app directory while the
// flows run and leave with the frames copied out: the capture's checkout must be clean again when it ends.
// The sides of one commit share a checkout across platforms, so each run gets its own directory under it.
const root = join(options.project, FLOWS_OUTPUT_DIRECTORY);
const existing = await lstat(root).catch(() => undefined);
if (existing && !existing.isDirectory()) return { flows: {}, failure: { code: "FLOWS_OUTPUT_EXISTS", message: `${FLOWS_OUTPUT_DIRECTORY} exists in the app directory and is not a directory; remove it and rerun.` } };
await mkdir(root, { recursive: true, mode: 0o700 });
const output = await mkdtemp(join(root, `${options.platform}-`));
try { return await executeFlows(options, work, output, say); }
finally {
await rm(output, { recursive: true, force: true });
// The last run out removes the directory; a concurrent run's files keep it (ENOTEMPTY).
await rmdir(root).catch(async () => {
const left = await readdir(root).catch(() => []);
if (left.length) say(`${FLOWS_OUTPUT_DIRECTORY} still holds ${left.slice(0, 3).join(", ")}${left.length > 3 ? ", …" : ""} (another run, or a late writer)`);
});
}
}
async function executeFlows(options: RunFlowsOptions, work: string, output: string, say: (message: string) => void): Promise<FlowsOutcome> {
const request: FlowsRequest = {
projectRoot: options.project, tests: [...options.tests], platform: options.platform, bundleId: options.bundleId, session: FLOWS_SESSION,
output, timeoutMs: options.timeoutMs, frames: options.frames ?? "checkpoints",
...(options.connection ? { daemon: { baseUrl: options.connection.daemonBaseUrl } } : options.stateDir ? { stateDir: options.stateDir } : {}),
...(options.deviceId ? { deviceId: options.deviceId } : {}),
...(options.agent ? { agent: options.agent } : {}),
...(options.engineModule ? { engineModule: options.engineModule } : {}),
};
const requestPath = join(work, "request.json");
await writeFile(requestPath, JSON.stringify(request), { mode: 0o600 });
say(`running ${options.tests.length} flow ${options.tests.length === 1 ? "file" : "files"} with e2e`);
// The worker's exit code is e2e's: 1 for failed tests, which is a result here, not a fault.
const result = options.runner({ command: process.execPath, args: [FLOWS_WORKER, requestPath], cwd: options.project,
environment: { ...options.environment, E2E_TELEMETRY_DISABLED: "1", ...(options.connection?.daemonAuthToken ? { EXPLORE_FLOWS_DAEMON_TOKEN: options.connection.daemonAuthToken } : {}) },
timeoutMs: options.timeoutMs + 120_000, allowFailure: true });
let summary: FlowsResult;
try { summary = JSON.parse(await readFile(join(output, "explore-flows.json"), "utf8")) as FlowsResult; }
catch {
// The worker prints the error and its stack; the message is the error lines, not the frames.
const message = (result.stderr || result.stdout).trim().split("\n").filter(line => line.trim() && !/^\s+at /.test(line)).slice(0, 4).join("\n").slice(0, 2_000);
say(`the flows did not run: ${message || "the e2e worker wrote no result"}`);
return { flows: {}, failure: { code: "FLOWS_NOT_RUN", message: message || "The e2e worker wrote no result." } };
}
const artifactsRoot = await realpath(summary.artifactsRoot).catch(() => resolve(summary.artifactsRoot));
const flows: Record<string, BundleFlow> = {};
for (const test of summary.tests) {
const frames: Record<string, FlowFrame> = {};
for (const frame of test.frames) {
try {
const source = await realpath(resolve(artifactsRoot, frame.path));
if (isAbsolute(frame.path) || relative(artifactsRoot, source).startsWith("..") || source.split(sep).includes("..")) throw new Error("outside the e2e artifacts");
const info = await lstat(source);
if (!info.isFile() || info.size > MAX_FRAME_BYTES) throw new Error("not a bounded regular file");
const png = await readFile(source);
assertDecodedPng(png, `Flow frame ${test.id}/${frame.key}`);
const path = flowFramePath(test.id, frame.key);
await mkdir(join(options.outputDirectory, dirname(path)), { recursive: true });
await copyFile(source, join(options.outputDirectory, path));
frames[frame.key] = { path, sha256: createHash("sha256").update(png).digest("hex"), width: png.readUInt32BE(16), height: png.readUInt32BE(20),
contentSha256: contentSha256(png, { top: statusBarBandPercent(options.platform), bottom: homeIndicatorBandPercent(options.platform) }),
capturedAt: Number.isFinite(Date.parse(frame.capturedAt)) ? frame.capturedAt : new Date().toISOString() };
} catch (error) {
say(`flow ${test.id}: frame ${frame.key} was not kept (${(error as Error).message})`);
const step = test.steps[frame.stepIndex];
if (step) delete step.frame;
}
}
flows[test.id] = { file: test.file, title: test.title, status: test.status, durationMs: test.durationMs, ...(test.error ? { error: test.error } : {}),
steps: test.steps.map(step => ({ ...step, ...(step.frame && !frames[step.frame] ? { frame: undefined } : {}) })).map(({ frame, ...rest }) => frame ? { ...rest, frame } : rest),
frames };
const taken = Object.keys(frames).length;
say(`flow ${test.title}: ${test.status}${taken ? `, ${taken} ${taken === 1 ? "frame" : "frames"}` : ""}${test.error ? ` (${test.error.code}: ${test.error.message.split("\n")[0]})` : ""}`);
}
if (summary.stepFrames) {
const { taken, failed, firstError } = summary.stepFrames;
say(`${taken} step ${taken === 1 ? "frame" : "frames"} taken${failed ? `, ${failed} not taken (${firstError})` : ""}`);
}
const failure = summary.errors[0];
return { flows, ...(failure && !summary.tests.length ? { failure: { code: failure.code, message: failure.message } } : {}) };
}
-7
View File
@@ -1,7 +0,0 @@
/** The flows worker's entry: `node worker-main.js <request.json>`. */
import { runFlowsWorker } from "./worker.js";
const requestPath = process.argv[2];
if (!requestPath) { console.error("usage: flows worker <request.json>"); process.exit(2); }
try { await runFlowsWorker(requestPath); }
catch (error) { console.error((error as Error).stack ?? String(error)); process.exitCode = 1; }
-167
View File
@@ -1,167 +0,0 @@
import { createHash } from "node:crypto";
/**
* Runs the app's e2e flows (the `e2e` package) on the device Explore already drives. A child process of the capture:
* the flows are the reviewed commit's own test code, so they run with the narrowed environment the capture gives
* them and never inside Explore's process. Reads one request file, writes one result file next to it.
*/
import { mkdir, readFile, writeFile } from "node:fs/promises";
import { join, relative } from "node:path";
import { run, type RunEventSink } from "e2e/runner";
import { createAgentDeviceClient } from "agent-device";
import type { E2EConfig } from "e2e";
import type { EngineHandle } from "e2e/engine";
import { mobile, type DeviceProvider } from "@e2e-dev/mobile";
import { summarizeFlowReport, type StepFrameFile } from "./report.js";
export type FlowsRequest = {
projectRoot: string;
tests: string[];
platform: "ios" | "android";
bundleId: string;
/** The agent-device session name the flows drive the device under; Explore's own session stays locked to its commands. */
session: string;
/** Where e2e writes its report and screenshots; inside the capture's private directory. */
output: string;
timeoutMs: number;
/** `steps` takes a frame after every step of a flow; `checkpoints` keeps only the frames the flows take with app.screenshot. */
frames: "checkpoints" | "steps";
/** Explore's EAS session daemon; the token comes through `EXPLORE_FLOWS_DAEMON_TOKEN`. */
daemon?: { baseUrl: string };
/** A local agent-device daemon's state directory, when the capture runs a simulator on this machine. */
stateDir?: string;
/** The device inside that daemon: a simulator UDID or an adb serial. */
deviceId?: string;
agent?: { provider: "openai" | "anthropic"; model: string };
/** Tests only: a module whose `engine()` export replaces the agent-device engine. */
engineModule?: string;
};
export type FlowsResult = {
status: string; exitCode: number;
errors: Array<{ code: string; message: string }>;
artifactsRoot: string;
tests: ReturnType<typeof summarizeFlowReport>;
/** Per-step frames (`frames: steps`): how many were taken, how many failed and the first failure. */
stepFrames?: { taken: number; failed: number; firstError?: string };
};
/** Hands e2e the device Explore holds instead of leasing one: same daemon, same simulator, another session name. */
export function exploreDevice(request: FlowsRequest, token: string | undefined): DeviceProvider {
return {
name: "expo-explore",
async acquire() {
if (request.daemon) return { id: "explore-session", daemon: { baseUrl: request.daemon.baseUrl, ...(token ? { authToken: token } : {}) }, ...(request.deviceId ? { deviceId: request.deviceId } : {}) };
if (request.stateDir) return { id: "explore-local", client: { stateDir: request.stateDir }, ...(request.deviceId ? { deviceId: request.deviceId } : {}) };
throw new Error("The flows request names neither a session daemon nor a local daemon state directory");
},
async release() { /* Explore stops its own session once the capture is done. */ },
};
}
async function agentModel(agent: NonNullable<FlowsRequest["agent"]>, environment: NodeJS.ProcessEnv): Promise<unknown> {
const name = agent.provider === "anthropic" ? "@ai-sdk/anthropic" : "@ai-sdk/openai";
const key = agent.provider === "anthropic" ? environment.ANTHROPIC_API_KEY : environment.OPENAI_API_KEY;
if (!key) throw new Error(`agent.act in a flow needs ${agent.provider === "anthropic" ? "ANTHROPIC_API_KEY" : "OPENAI_API_KEY"} in the capture environment`);
let module: Record<string, unknown>;
try { module = await import(name) as Record<string, unknown>; }
catch { throw new Error(`agent.act in a flow needs ${name} installed next to @expo/explore (e2e builds the model with the AI SDK)`); }
const create = module[agent.provider === "anthropic" ? "createAnthropic" : "createOpenAI"] as (options: { apiKey: string }) => (model: string) => unknown;
return create({ apiKey: key })(agent.model);
}
export async function runFlowsWorker(requestPath: string, environment: NodeJS.ProcessEnv = process.env): Promise<void> {
const request = JSON.parse(await readFile(requestPath, "utf8")) as FlowsRequest;
const token = environment.EXPLORE_FLOWS_DAEMON_TOKEN;
const engine: EngineHandle = request.engineModule
? ((await import(request.engineModule)) as { engine: () => EngineHandle }).engine()
: mobile({ platform: request.platform, device: exploreDevice(request, token), session: request.session, videoTouches: false });
const config: E2EConfig = {
targets: [{ name: request.platform, engine, app: { bundleId: request.bundleId } }],
// The configured suite is exactly the files the config names; nothing else in the app is collected.
tests: request.tests,
output: request.output,
timeout: request.timeoutMs,
retries: 0,
workers: 1,
cache: "read-only",
...(request.agent ? { agents: { default: { model: await agentModel(request.agent, environment) as never } } } : {}),
};
const controller = new AbortController();
const expiry = setTimeout(() => controller.abort(), request.timeoutMs + 60_000);
const stepFrames = request.frames === "steps" && !request.engineModule ? stepFrameRecorder(request, token) : undefined;
try {
const result = await run({ cwd: request.projectRoot, config, interruptSignal: controller.signal, ...(stepFrames ? { onEvent: stepFrames.onEvent } : {}) });
// e2e closes its device session as the run ends; a frame still settling keeps the shot it has instead of asking for another.
stepFrames?.stop();
const stepResult = stepFrames ? await stepFrames.finish() : undefined;
const frames = stepResult?.frames;
const report = result.report as unknown as { run: { errors?: unknown[] } };
const output: FlowsResult = { status: result.status, exitCode: result.exitCode,
errors: (report.run.errors ?? []).flatMap(error => error && typeof error === "object" ? [{ code: String((error as { code?: unknown }).code ?? "ERROR"), message: String((error as { message?: unknown }).message ?? "") }] : []),
artifactsRoot: join(request.output, "results"), tests: summarizeFlowReport(result.report, frames),
...(stepResult ? { stepFrames: { taken: [...stepResult.frames.values()].reduce((n, files) => n + files.length, 0), failed: stepResult.failures.length,
...(stepResult.failures[0] ? { firstError: stepResult.failures[0] } : {}) } } : {}) };
await writeFile(join(request.output, "explore-flows.json"), JSON.stringify(output), { mode: 0o600 });
} finally { clearTimeout(expiry); }
}
/**
* Takes a frame of the flows' session after every step ends, through the same daemon e2e drives it on. e2e does not wait
* for a reporter, so the frame shows the device as the next step begins; a frame that fails is skipped, not fatal.
*/
/**
* The step ends while the app may still be settling (a list easing into place, a control fading in), and a frame shot
* at that instant is a near-duplicate of its neighbours that never folds. Shoot again after a short pause until two
* shots agree, within a bounded number of tries; the last shot is kept either way.
*/
export async function settledScreenshot(client: { capture: { screenshot(options: { path: string }): Promise<unknown> } }, file: string,
options: { pauseMs?: number; tries?: number; sleep?: (ms: number) => Promise<void>; /** False once the device is about to go away: keep the shot in hand. */ more?: () => boolean } = {}): Promise<{ tries: number; settled: boolean }> {
const pauseMs = options.pauseMs ?? 150; const maxTries = options.tries ?? 4;
const sleep = options.sleep ?? ((ms: number) => new Promise<void>(resolve => setTimeout(resolve, ms)));
const digest = async () => createHash("sha256").update(await readFile(file)).digest("hex");
await client.capture.screenshot({ path: file });
let previous = await digest();
for (let tries = 1; tries < maxTries; tries++) {
await sleep(pauseMs);
if (options.more && !options.more()) return { tries, settled: false };
await client.capture.screenshot({ path: file });
const current = await digest();
if (current === previous) return { tries: tries + 1, settled: true };
previous = current;
}
return { tries: maxTries, settled: false };
}
export function stepFrameRecorder(request: FlowsRequest, token: string | undefined): { onEvent: RunEventSink; stop: () => void; finish: () => Promise<{ frames: Map<string, StepFrameFile[]>; failures: string[] }> } {
const root = join(request.output, "results");
const directory = join(root, "explore-step-frames");
// @e2e-dev/mobile drives the device as `<session>-<slot>` and Explore runs one worker, so the flows' session is `<session>-0`.
const client = createAgentDeviceClient({
session: `${request.session}-0`,
...(request.daemon ? { daemonBaseUrl: request.daemon.baseUrl, daemonAuthToken: token } : { stateDir: request.stateDir, daemonBaseUrl: "", daemonAuthToken: "", daemonTransport: "auto" }),
} as Parameters<typeof createAgentDeviceClient>[0]);
const frames = new Map<string, StepFrameFile[]>();
const pending: Promise<void>[] = [];
const failures: string[] = [];
let ready: Promise<void> | undefined;
let stopped = false;
return {
stop() { stopped = true; },
onEvent(event) {
if (event.type !== "step" || event.progress.phase !== "end" || event.progress.status !== "passed") return;
const { testId } = event;
const stepIndex = event.progress.identity?.stepIndex;
if (stepIndex === undefined) return;
const file = join(directory, `${testId.replace(/[^A-Za-z0-9._-]+/g, "_")}-${stepIndex}.png`);
ready ??= mkdir(directory, { recursive: true }).then(() => undefined);
pending.push(ready
.then(() => settledScreenshot(client, file, { more: () => !stopped }))
.then(() => { (frames.get(testId) ?? frames.set(testId, []).get(testId)!).push({ stepIndex, path: relative(root, file), capturedAt: new Date().toISOString() }); })
.catch(error => {
const message = `step frame ${stepIndex + 1} of ${testId} was not taken: ${(error as Error).message}`;
failures.push(message); process.stderr.write(`explore: ${message}\n`);
}));
},
async finish() { await Promise.all(pending); return { frames, failures }; },
};
}
+212 -145
View File
@@ -3,7 +3,6 @@ import { assertNoCaptureHealthIssues, captureHealthIssues, partitionCaptureHealt
import { type RouteResetSetting } from "./route-reset.js";
import { defaultReadinessSeconds } from "./readiness.js";
import { captureLaunch, ffmpegRecordingTools, launchDirectory, type LaunchSetting, type RecordingTools } from "./launch-capture.js";
import { FLOWS_OUTPUT_DIRECTORY, flowFramePath, runFlows } from "./flows/run-flows.js";
import { createHash } from "node:crypto";
import { copyFile, lstat, mkdir, mkdtemp, readFile, realpath, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
@@ -20,10 +19,10 @@ import { type CiAgentRuntimeOptions } from "./agent/runtime.js";
import { EAS_CLI_VERSION, CONTROLLER_SESSION, isRecord, parseJson, baseEnvironment, nonEmpty } from "./common.js";
import { lstatIfExists, isWithin, temporaryCaptureDirectory, absoluteContractFile, readContractJson, assertNoSymlinkAncestors } from "./fs-safety.js";
import { loadAppIcon, loadCachedAppIcon, storeAppIcon } from "./app-icon.js";
import { controllerCommandFailure, defaultRunner, runAgentControllerCommand } from "./controller.js";
import { defaultRunner, runAgentControllerCommand } from "./controller.js";
import { silentProgress, type Progress } from "../shared/progress.js";
import { assertCaptureEasProfile, assertSimulatorAvailable, fingerprintFrom, hasEasEnvironmentFetchFailure, nativeBuildFrom, existingBuild, repackProfileFrom, prepareExactSourceBuild, type RepackMode } from "./eas-build.js";
import { SIMULATOR_DOTENV_FILE_NAME, SIMULATOR_DOTENV_HEADER, simulatorSessionName, simulatorStartFailure, readSimulatorDotenvHandoff, assertSimulatorSessionIdentity, assertSimulatorStopped, collectRuntime, controllerVersion, simulatorOsVersion, type ActiveSimulatorRuntime, type SimulatorConnection } from "./simulator.js";
import { SIMULATOR_DOTENV_FILE_NAME, SIMULATOR_DOTENV_HEADER, endedOwnSimulatorSession, liveSimulatorSessionsNamed, simulatorSessionName, simulatorStartFailure, readSimulatorDotenvHandoff, assertSimulatorSessionIdentity, assertSimulatorStopped, collectRuntime, controllerVersion, simulatorOsVersion, type ActiveSimulatorRuntime, type SimulatorConnection } from "./simulator.js";
import { argentControllerInvocation } from "./controller-invocation.js";
import { sharedBuild } from "./shared-build.js";
import { LOCAL_EMULATOR_STATE_PREFIX, LOCAL_SIMULATOR_STATE_PREFIX, agentDeviceClaims, assertLocalEmulatorCompatible, createLocalSimulator, startLocalEmulator, waitForLocalEmulator, waitForLocalSimulator, deleteLocalEmulator,
@@ -31,6 +30,8 @@ import { LOCAL_EMULATOR_STATE_PREFIX, LOCAL_SIMULATOR_STATE_PREFIX, agentDeviceC
pngSize, setLocalEmulatorAppearance, setLocalSimulatorAppearance, startLocalArgentServer, stopLocalAgentDevice, stopLocalArgentServer, type LocalArgentServer } from "./local-simulator.js";
import { ensureArgentToolServer } from "../shared/controller-cache.js";
import { openLocalCaptureRecord } from "./local-registry.js";
import { approveSessionUrlSchemes, simulatorControl, simulatorControlActions, type EasCommand } from "./simulator-control.js";
import { solidColour } from "../shared/png-evidence.js";
import { type UnattributedSetting } from "./unattributed.js";
import { appScheme, hasConcreteRoutePath, unavailableRoute, capturePlannedRoutes, deviceArgs } from "./route-capture.js";
@@ -83,8 +84,6 @@ export type CiMapOptions = {
progress?: Progress;
/** Stops the capture between steps (before the build, the session and each route); a session it started is still stopped. */
signal?: AbortSignal;
/** The app's e2e flows to run after the routes (`only`: instead of them), as paths or globs from the app directory. */
flows?: { tests: readonly string[]; only?: boolean; frames?: "checkpoints" | "steps"; agent?: { provider: "openai" | "anthropic"; model: string } };
};
export type SimulatorRuntimeMetadata = {
provider: "eas-simulator" | "local-simulator"; controller: "agent-device" | "argent"; controllerPackageVersion: string;
@@ -101,6 +100,20 @@ export type CiMapResult = {
};
/** New EAS sessions a capture starts in place of one EAS failed to start (ERRORED while booting, or never named). */
const SESSION_START_RETRIES = 5;
/**
* The most time, from the first failed start, that replacement sessions may take, waits included. It keeps a review
* inside its CI job (90 minutes for a baseline) with a native build, a repack and both captures still to run.
*/
const SESSION_RETRY_BUDGET_MS = 30 * 60_000;
/** How long one `eas simulator:start` may take: eas-cli waits up to 15 minutes for a session, not counting the queue. */
const SESSION_START_TIMEOUT_MS = 20 * 60_000;
/** The wait before each of them: 10 s, doubling, at most 2 minutes. */
export function sessionRetryDelayMs(retry: number): number {
return Math.min(10_000 * 2 ** (retry - 1), 120_000);
}
/**
* Minutes an EAS session is asked for beyond the capture's own budget. The session starts beside the repack, and the
* capture deadline only starts once the app is installed, so the session also has to outlast a slow or queued hosted
@@ -116,6 +129,17 @@ function sessionDurationLimit(error: unknown): number | undefined {
return match ? Math.floor(Number(match[1])) : undefined;
}
/**
* A start failure EAS may not repeat on the next try: a failed request, a dropped connection, a timeout, or no capacity
* right now. An account's quota, plan or permissions are not, and fail at once rather than after every retry.
*/
function transientSessionStartFailure(error: unknown): boolean {
if (error instanceof CiError && error.code === "CONTROLLER_REQUEST_TIMEOUT") return true;
const message = error instanceof Error ? error.message : String(error);
if (/not authori[sz]ed|unauthori[sz]ed|forbidden|permission|quota|billing|max duration/i.test(message)) return false;
return /GraphQL request failed|ECONNRESET|ETIMEDOUT|EAI_AGAIN|socket hang up|timed out|\b50[234]\b|capacity/i.test(message);
}
function positiveInteger(value: number, name: string): number {
if (!Number.isInteger(value) || value <= 0) {
throw new Error(`${name} must be a positive integer`);
@@ -192,7 +216,7 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
const route = row[`${side}Surface`];
return route ? [route] : [];
});
const routes = options.flows?.only ? [] : inventory.filter(route => selected.has(route.id));
const routes = inventory.filter(route => selected.has(route.id));
const setup = revisionSetup(options.setup ?? [], plan, side);
const runner = options.runner ?? defaultRunner;
const sourceEnvironment = options.environment ?? process.env;
@@ -202,13 +226,8 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
const easEnvironment = { ...restrictedEnvironment, ...(options.expoToken ? { EXPO_TOKEN: options.expoToken } : {}) };
const assertCheckout = () => {
const call = (args: string[]) => runner({ command: "git", args, cwd: project, environment: restrictedEnvironment, timeoutMs: 30_000 }).stdout.trim();
const head = call(["rev-parse", "HEAD"]);
// Explore's own flows scratch directory is not a change to the application; it is removed when the flows end.
const changes = call(["status", "--porcelain", "--untracked-files=normal", "--", ".", `:(exclude)${FLOWS_OUTPUT_DIRECTORY}`]);
if (head !== options.gitCommit || changes) {
const detail = head !== options.gitCommit ? `HEAD is ${head.slice(0, 12) || "unreadable"}, the plan recorded ${options.gitCommit.slice(0, 12)}`
: `changed: ${changes.split("\n").slice(0, 3).join(", ")}${changes.split("\n").length > 3 ? ", …" : ""}`;
throw new CiError({ code: "SOURCE_CHECKOUT_CHANGED", stage: "source", message: `The application checkout differs from its recorded commit (${detail}).`,
if (call(["rev-parse", "HEAD"]) !== options.gitCommit || call(["status", "--porcelain", "--untracked-files=normal"])) {
throw new CiError({ code: "SOURCE_CHECKOUT_CHANGED", stage: "source", message: "The application checkout differs from its recorded commit.",
nextAction: "Use a clean checkout at the exact plan commit. Capture output must stay outside the application." });
}
};
@@ -231,8 +250,6 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
// Launch evidence waits in a work directory until the export directory exists.
const launch: Record<string, { root: string; record: BundleLaunchCapture }> = {};
const launchWorkDirectory = await mkdtemp(join(tmpdir(), "expo-explore-launch-"));
// Flow frames land here first: the export directory must not exist until the map is exported into it.
const flowsWorkDirectory = await mkdtemp(join(tmpdir(), "expo-explore-flows-"));
const acceptedFrames: Record<string, AgentAcceptedFrame> = {};
if (options.reuseDirectory) {
const cacheRoot = await realpath(options.reuseDirectory);
@@ -334,9 +351,6 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
+ (routes.length - missingRoutes.length ? `, ${routes.length - missingRoutes.length} reused from the baseline` : "")
+ (missingRoutes.length ? `, ${missingRoutes.length} to capture` : ""));
let captureFailure: unknown;
let flowRecords: CaptureBundle["flows"] | undefined;
let flowsFailure: CaptureBundle["flowsFailure"] | undefined;
const captureStartedAt = (options.now ?? Date.now)();
const finish = async (): Promise<CiMapResult> => {
if (!(await store.exists())) await store.initialize(map, false);
const incomplete = captureFailure !== undefined || selectedIds.some(id => outcomes[id]?.status !== "captured" || outcomes[id]?.landing !== "verified")
@@ -395,16 +409,6 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
launchRecords[scheme] = record;
}
await rm(launchWorkDirectory, { recursive: true, force: true });
for (const flow of Object.values(flowRecords ?? {})) {
for (const frame of Object.values(flow.frames)) {
const source = join(flowsWorkDirectory, frame.path);
await assertNoSymlinkAncestors(flowsWorkDirectory, source, "flow frame");
await mkdir(join(outputDirectory, dirname(frame.path)), { recursive: true });
await copyFile(source, join(outputDirectory, frame.path));
if (createHash("sha256").update(await readFile(join(outputDirectory, frame.path))).digest("hex") !== frame.sha256) throw new Error(`Exported flow frame ${frame.path} does not match the captured file`);
}
}
await rm(flowsWorkDirectory, { recursive: true, force: true });
const storedIcon = appIcon ? await storeAppIcon(outputDirectory, appIcon) : undefined;
const bundle: CaptureBundle = { contract: "explore.bundle", side, gitCommit: options.gitCommit, easBuildId: frameBuildId, completedAt: map.run.completedAt,
easProjectId: projectId, platform: options.platform, profile: options.easProfile, appName: app.name, ...(controller === "argent" ? { controller } : {}), ...(storedIcon ? { appIcon: storedIcon } : {}),
@@ -412,8 +416,6 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
runtimeProfile: metadata ? { deviceModel: metadata.deviceModel, osVersion: metadata.osVersion, locale: metadata.locale,
orientation: metadata.orientation, colorScheme: metadata.colorScheme, ...(metadata.colorSchemes ? { colorSchemes: metadata.colorSchemes.join(",") } : {}) } : null, images, outcomes, procedure: { reset: options.reset ?? "root-link", readinessSeconds: options.readinessSeconds ?? defaultReadinessSeconds(options.platform) },
...(Object.keys(launchRecords).length ? { launch: launchRecords } : {}),
...(flowRecords && Object.keys(flowRecords).length ? { flows: flowRecords } : {}),
...(flowsFailure ? { flowsFailure } : {}),
...(options.agent ? { captureContexts: Object.fromEntries(selectedIds.filter(id => outcomes[id]?.status === "captured" && options.agent!.contexts[id])
.map(id => [id, options.agent!.contexts[id]!])), agentAcceptance: { policy: AGENT_ACCEPTANCE_POLICY,
frames: Object.fromEntries(Object.keys(images).map(id => [id, acceptedFrames[id]!])) } } : {}) };
@@ -428,7 +430,7 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
simulatorSessionId: sessionId ?? null, simulatorRuntime: metadata, mapDirectory, outputDirectory,
runStatus: routes.length === 0 ? "complete" : map.run.status, app, outcomes };
};
if (!options.flows && (!missingRoutes.length || !options.agent && !missingRoutes.some(hasConcreteRoutePath))) {
if (!missingRoutes.length || !options.agent && !missingRoutes.some(hasConcreteRoutePath)) {
for (const route of missingRoutes) outcomes[route.id] = { ...unavailableRoute(route), attempts: 0, landing: "unverified" };
return finish();
}
@@ -436,22 +438,31 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
say(`reading EAS build profile ${options.easProfile}`);
const eas = (args: string[], timeoutMs = 5 * 60_000, cwd = project) => runner({ command: options.easCommand, args,
cwd, environment: easEnvironment, timeoutMs });
// `eas simulator:control` names the session by id, from the session's own project directory.
const sessionEas: EasCommand = (args, commandOptions) => runner({ command: options.easCommand, args, cwd: simulatorProject, environment: easEnvironment,
timeoutMs: commandOptions?.timeoutMs ?? 5 * 60_000, ...(commandOptions?.allowFailure ? { allowFailure: true } : {}) });
// What the EAS session's host can do through simulator:control (iOS sessions on serve-sim 0.10.0 or later).
let controlActions = new Set<string>();
const configResult = eas(["config", "--platform", options.platform, "--profile", options.easProfile, "--json", "--non-interactive"]);
const profile = repackProfileFrom(configResult.stdout);
const configValue = parseJson(configResult.stdout, "eas config") as { appConfig: Record<string, unknown>; buildProfile: Record<string, unknown> };
scheme ??= appScheme(configValue.appConfig.scheme);
colorSchemes = resolveColorSchemes(options.appearance ?? "auto", configValue.appConfig, options.platform);
// Argent cannot switch the appearance itself; on a local device the host switches it (simctl, adb), so it is kept.
if (controller === "argent" && !local) {
const single = argentColorSchemes(colorSchemes, configValue.appConfig, options.platform);
if (single.skipped.length) say(`Argent cannot switch appearance yet (software-mansion/argent#1509); capturing ${single.schemes[0]} only, skipped ${single.skipped.join(", ")}`);
colorSchemes = single.schemes;
}
// Argent cannot switch the appearance itself. On a local device the host switches it (simctl, adb); on an EAS iOS
// session serve-sim does (appearance.set), which is known once the session starts; otherwise one appearance is captured.
let argentSchemes = controller === "argent" && !local ? argentColorSchemes(colorSchemes, configValue.appConfig, options.platform) : undefined;
const narrowToArgentScheme = () => {
if (!argentSchemes) return;
if (argentSchemes.skipped.length) say(`Argent cannot switch appearance on this session; capturing ${argentSchemes.schemes[0]} only, skipped ${argentSchemes.skipped.join(", ")}`);
colorSchemes = argentSchemes.schemes;
argentSchemes = undefined;
};
if (options.platform !== "ios") narrowToArgentScheme();
app = { name: profile.projectIdentity.name, ...(profile.projectIdentity.version ? { version: profile.projectIdentity.version } : {}),
...(profile.projectIdentity.buildNumber ? { buildNumber: profile.projectIdentity.buildNumber } : {}) };
projectId = profile.projectIdentity.projectId;
appIcon = await loadAppIcon(project, configValue.appConfig, options.platform) ?? appIcon;
if (!scheme && !options.agent && !options.flows) {
if (!scheme && !options.agent) {
for (const route of missingRoutes) outcomes[route.id] = { ...unavailableRoute(route), attempts: 0, landing: "unverified" };
return finish();
}
@@ -516,19 +527,23 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
}
} catch (error) { await stopEarlyDevice().catch(() => undefined); throw error; }
// The session is named before its app exists: an EAS session starts while the app is repacked (startSession).
const sessionName = simulatorSessionName({ mapName: options.name, mapId: options.buildId, gitCommit: options.gitCommit, easBuildId: local ? "local" : "installed",
runIdentity: JSON.stringify({ mapDirectory, outputDirectory, run: sourceEnvironment.GITHUB_RUN_ID, attempt: sourceEnvironment.GITHUB_RUN_ATTEMPT }) });
// A session EAS failed to start is replaced once (see the session block), under a name of its own.
const sessionNameFor = (retry: number) => simulatorSessionName({ mapName: options.name, mapId: options.buildId, gitCommit: options.gitCommit, easBuildId: local ? "local" : "installed",
runIdentity: JSON.stringify({ mapDirectory, outputDirectory, run: sourceEnvironment.GITHUB_RUN_ID, attempt: sourceEnvironment.GITHUB_RUN_ATTEMPT, ...(retry ? { sessionRetry: retry } : {}) }) });
let sessionRetries = 0;
let sessionName = sessionNameFor(0);
/**
* Starts the EAS Simulator session in the background, empty, once the build to repack is known (not while a native
* build runs, which can take most of an hour of session time). The app is installed through the controller when both
* are ready. Resolves with the start command's failure, if any; the session block verifies what EAS handed over.
*/
const startSession = () => {
const startSession = (retry?: { timeoutMs: number }) => {
if (local || sessionStart) return;
say(`starting an EAS Simulator session (${options.device}) while the app is repacked`);
if (!retry) say(`starting an EAS Simulator session (${options.device}) while the app is repacked`);
const request = (minutes: number) => ({ command: options.easCommand, args: ["simulator:start", "--name", sessionName, "--platform", options.platform, "--device", options.device,
"--type", controller, "--package-version", controllerVersion(controller), "--public-link",
"--max-duration-minutes", String(minutes), "--out-config-type", "dotenv", "--non-interactive"], cwd: simulatorProject, environment: easEnvironment, timeoutMs: 20 * 60_000 });
"--max-duration-minutes", String(minutes), "--out-config-type", "dotenv", "--non-interactive"], cwd: simulatorProject, environment: easEnvironment,
timeoutMs: retry?.timeoutMs ?? SESSION_START_TIMEOUT_MS });
// An injected runner (tests) answers synchronously; a real start runs beside the repack.
const start = async (minutes: number) => options.runner ? options.runner(request(minutes)) : runAgentControllerCommand(request(minutes), options.signal ?? new AbortController().signal);
sessionStart = writeFile(dotenvPath, SIMULATOR_DOTENV_HEADER, { flag: "wx", mode: 0o600 })
@@ -622,8 +637,72 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
throw new Error("The local device did not start before capture");
} else {
if (!localApp || !sessionStart) throw new Error("An EAS Simulator session needs the instrumented app on this machine");
const startError = await sessionStart;
const handoff = await readSimulatorDotenvHandoff(dotenvPath);
let startError = await sessionStart;
let handoff = await readSimulatorDotenvHandoff(dotenvPath);
// EAS sometimes fails to start a session: it errors while booting, or the start request fails before a session is
// named. After every failed start, whatever it may have left running is accounted for; then, when the failure is
// provably EAS's, a new session replaces it, up to SESSION_START_RETRIES times within SESSION_RETRY_BUDGET_MS, with
// a growing wait. A session Explore cannot prove is its own is never replaced or stopped: that stays a handoff
// failure below, as does a lookup that fails.
const clock = options.now ?? Date.now;
const endedSessions: string[] = [];
let ended: { sessionId: string; status: string } | undefined;
let retryDeadline: number | undefined;
for (;;) {
const easRead = (args: string[]) => {
try { return runner({ command: options.easCommand, args, cwd: project, environment: easEnvironment, timeoutMs: 2 * 60_000, allowFailure: true }).stdout; }
catch { return ""; }
};
let reason: string | undefined;
ended = undefined;
if (handoff.sessionId) {
const status = endedOwnSimulatorSession(easRead(["simulator:get", "--id", handoff.sessionId, "--json", "--non-interactive"]),
{ sessionId: handoff.sessionId, sessionName, project: profile.projectIdentity, type: controller, platform: options.platform });
if (status) {
ended = { sessionId: handoff.sessionId, status };
endedSessions.push(handoff.sessionId);
reason = `EAS ended simulator session ${handoff.sessionId} (${status}) before it was ready`;
}
} else if (startError && transientSessionStartFailure(startError)) {
// The failed request may still have created a session: any by this exact name is stopped, so none is left running.
const live = liveSimulatorSessionsNamed(easRead(["simulator:list", "--name", sessionName, "--status", "new", "--status", "queued", "--status", "starting",
"--status", "in-progress", "--limit", "100", "--json", "--non-interactive"]), sessionName, profile.projectIdentity);
if (live) {
for (const id of live) assertSimulatorStopped(eas(["simulator:stop", "--id", id, "--json", "--non-interactive"], 2 * 60_000).stdout, id);
reason = `EAS could not start the simulator session (${simulatorStartFailure(startError, [options.expoToken]).message})`;
}
}
if (!reason || sessionRetries >= SESSION_START_RETRIES) break;
retryDeadline ??= clock() + SESSION_RETRY_BUDGET_MS;
const delayMs = sessionRetryDelayMs(sessionRetries + 1);
// A new start needs at least a minute of the budget after its wait; one started later could not finish in it.
const startTimeoutMs = Math.min(SESSION_START_TIMEOUT_MS, retryDeadline - clock() - delayMs);
if (startTimeoutMs < 60_000) break;
sessionRetries += 1;
say(`${reason}; starting a new EAS Simulator session in ${Math.round(delayMs / 1000)} s (${sessionRetries}/${SESSION_START_RETRIES})`);
options.signal?.throwIfAborted();
// Asynchronous and cancellable, so targets capturing beside this one keep running and Ctrl+C stops the wait.
if (options.sleep) options.sleep(delayMs);
else await new Promise<void>((resolve, reject) => {
const timer = setTimeout(() => { options.signal?.removeEventListener("abort", abort); resolve(); }, delayMs);
const abort = () => { clearTimeout(timer); reject(options.signal!.reason); };
options.signal?.addEventListener("abort", abort, { once: true });
});
options.signal?.throwIfAborted();
await rm(dotenvPath, { force: true });
sessionName = sessionNameFor(sessionRetries);
sessionStart = undefined;
startSession({ timeoutMs: startTimeoutMs });
startError = await sessionStart;
handoff = await readSimulatorDotenvHandoff(dotenvPath);
}
// Every session EAS ended is its own failure to start, never a question of ownership.
if (ended) throw new CiError({ code: "SIMULATOR_START_FAILED", stage: "session",
message: `EAS could not start a simulator session: ${endedSessions.length === 1 ? `session ${ended.sessionId} ended (${ended.status}) before it was ready`
: `${endedSessions.length} sessions ended before they were ready (the last, ${ended.sessionId}, ${ended.status})`}.`,
nextAction: "Rerun Explore. If sessions keep failing to start, check the EAS Simulator status and the sessions' logs on expo.dev.",
retryable: true, details: { attempts: sessionRetries + 1, endedSessions, ...(startError ? { startFailure: simulatorStartFailure(startError, [options.expoToken]) } : {}) },
...(startError ? { cause: startError } : {}) });
const startSecrets = [options.expoToken, ...(handoff.connection ? [handoff.connection.daemonAuthToken] : [])];
const startFailure = startError ? simulatorStartFailure(startError, startSecrets) : undefined;
if (handoff.sessionId) {
@@ -653,6 +732,8 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
if (!handoff.connection) throw new Error("Simulator handoff is missing its controller connection");
connection = handoff.connection;
await rm(dotenvPath, { force: true });
if (options.platform === "ios") controlActions = simulatorControlActions(sessionEas, sessionId);
if (!controlActions.has("appearance.set")) narrowToArgentScheme();
}
const controllerConfig = join(simulatorProject, "agent-device.json");
await writeFile(controllerConfig, "{}\n", { flag: "wx", mode: 0o400 });
@@ -680,14 +761,22 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
say(`installing the app on session ${sessionId}`);
runner({ command: controllerCommand, args: ["install", localApp, "--session", CONTROLLER_SESSION, ...deviceArgs({ platform: options.platform, deviceModel: options.device }),
"--platform", options.platform, "--json"], cwd: simulatorProject, environment: controllerEnvironment, timeoutMs: 15 * 60_000 });
// Before any link opens, as a local capture does with simctl: the app's own links then open without the prompt.
if (sessionId && scheme) {
const approved = approveSessionUrlSchemes(sessionEas, sessionId, controlActions, options.bundleId, [scheme]);
if (approved.length) say(`approved ${approved.map(item => `${item}://`).join(", ")} links on session ${sessionId}`);
}
}
if (options.devicePose) {
// A fold relights the other panel and resizes the window. It comes before the app is first opened or read, so the
// controller's accessibility reader starts on the lit panel: Argent's, started on the outer panel, can stay there.
say(`folding ${options.device} ${options.devicePose}`);
const target = deviceArgs({ platform: options.platform, deviceModel: options.device, ...(localDevice() ? { provider: "local-simulator" as const, controllerDeviceId: localDevice()! } : {}) });
// agent-device reads the hinge back after folding and fails to (locally and on EAS); its display is checked instead.
const easAgentDevice = !!sessionId && controller === "agent-device";
const fold = () => runner({ command: controllerCommand, args: ["fold", options.devicePose!, "--session", CONTROLLER_SESSION, ...target, "--platform", options.platform, "--json"],
cwd: simulatorProject, environment: controllerEnvironment, timeoutMs: 2 * 60_000, ...(localSimulator ? { allowFailure: true } : {}) });
cwd: simulatorProject, environment: controllerEnvironment, timeoutMs: 2 * 60_000, ...(localSimulator || easAgentDevice ? { allowFailure: true } : {}) });
const pause = options.sleep ?? (milliseconds => { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds); });
if (localSimulator && controller === "argent") {
// Argent folds without a session and checks the fold against its own reader; this machine also checks the display.
fold();
@@ -705,40 +794,60 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
...(options.sleep ? { sleep: options.sleep } : {}) })) throw new CiError({ code: "CONTROLLER_FOLD_UNVERIFIED", stage: "session",
message: `${options.device} did not show the ${options.devicePose} display after folding: ${(folded.stderr || folded.stdout).trim().split("\n").at(-1) ?? ""}`.trim(),
nextAction: "Rerun; if it persists, check that this Xcode's simulator supports folding the device." });
} else {
// agent-device folds only inside a session, and `install` opens none (SESSION_NOT_FOUND on EAS Simulator when the
// fold came first): the app opens once to start the session. Argent's bridge folds without one.
// A foldable's first open on EAS Simulator has timed out inside the controller once (`xcrun timed out`); one retry.
for (let attempt = 0; controller !== "argent"; attempt += 1) {
try {
runner({ command: controllerCommand, args: ["open", options.bundleId, "--session", CONTROLLER_SESSION, ...target, "--platform", options.platform, "--json"],
cwd: simulatorProject, environment: controllerEnvironment, timeoutMs: 5 * 60_000 });
break;
} catch (error) {
if (attempt > 0) throw error;
say(`the app did not open before the fold (${(error as Error).message.split("\n")[0]}); opening it again`);
} else if (easAgentDevice && sessionId) {
// On EAS, agent-device also folds only inside a session, so the app opens first. The first fold of a fresh session
// can leave the panel it lights black, as it does for Argent: the controller then reads the old panel and a
// relaunch draws nothing. The display is the check, through the controller's own screenshot: in the pose's shape
// and drawn. If it is not, SpringBoard is restarted, the app reopened and the device folded again, once.
const open = (relaunch: boolean) => runner({ command: controllerCommand, args: ["open", options.bundleId, ...(relaunch ? ["--relaunch"] : []), "--session", CONTROLLER_SESSION,
...target, "--platform", options.platform, "--json"], cwd: simulatorProject, environment: controllerEnvironment, timeoutMs: 15 * 60_000 });
const shown = async () => {
if (options.devicePose !== "open" && options.devicePose !== "closed") return true;
const file = join(simulatorProject, "pose.png");
// The display relights and resizes over a moment after the hinge moves.
for (let attempt = 0; attempt < 10; attempt += 1) {
if (attempt) pause(1_000);
runner({ command: controllerCommand, args: ["screenshot", file, "--session", CONTROLLER_SESSION, ...target, "--platform", options.platform, "--json"],
cwd: simulatorProject, environment: controllerEnvironment, timeoutMs: 2 * 60_000, allowFailure: true });
const png = await readFile(file).catch(() => Buffer.alloc(0));
await rm(file, { force: true });
const size = pngSize(png);
if (size && (options.devicePose === "open" ? size.width > size.height : size.height > size.width) && !solidColour(png)) return true;
}
return false;
};
open(false);
fold();
if (!await shown()) {
if (!controlActions.has("springboard.restart")) throw new CiError({ code: "CONTROLLER_FOLD_UNVERIFIED", stage: "session",
message: `${options.device} did not show the ${options.devicePose} display after folding.`, nextAction: "Rerun the capture on a new session." });
say(`${options.device} did not draw the ${options.devicePose} display after the fold; restarting SpringBoard and folding ${options.devicePose} again`);
simulatorControl(sessionEas, sessionId, "springboard.restart");
pause(8_000);
open(true);
fold();
if (!await shown()) throw new CiError({ code: "CONTROLLER_READER_STUCK", stage: "session",
message: `${options.device} did not draw the ${options.devicePose} display after folding, nor after SpringBoard was restarted and it was folded again.`,
nextAction: "Rerun the capture; if it keeps happening, report it to Explore with the session's link." });
}
} else if (controller === "argent" && sessionId && controlActions.has("springboard.restart")) {
// The bridge has already reset Argent's device helpers once when its reader stayed on the dark panel. On EAS the
// tool-server cannot be restarted, so the next step is SpringBoard, then the same fold and check again.
try { fold(); }
catch (error) {
if (toCiError(error).code !== "CONTROLLER_FOLD_UNVERIFIED") throw error;
say(`Argent kept reading the other panel after the fold; restarting SpringBoard and folding ${options.devicePose} again`);
simulatorControl(sessionEas, sessionId, "springboard.restart");
pause(8_000);
try { fold(); }
catch (retry) {
if (toCiError(retry).code !== "CONTROLLER_FOLD_UNVERIFIED") throw retry;
throw new CiError({ code: "CONTROLLER_READER_STUCK", stage: "session",
message: `Argent's accessibility reader kept reading the panel the fold turned off, after its device helpers were reset and SpringBoard was restarted.`,
nextAction: "Rerun the capture; if it keeps happening, report it to Explore: this session's Argent tool-server needs a restart that EAS cannot do yet.", cause: retry });
}
}
const folded = runner({ command: controllerCommand, args: ["fold", options.devicePose, "--session", CONTROLLER_SESSION, ...target, "--platform", options.platform, "--json"],
cwd: simulatorProject, environment: controllerEnvironment, timeoutMs: 2 * 60_000, allowFailure: true });
const failure = foldFailure(folded.stdout);
if (failure) {
// On EAS Simulator agent-device dispatches the pose but cannot read the hinge back, so the lit display's shape
// confirms the pose instead: the inner one is landscape when open, the outer one portrait when closed.
if (!/hinge/i.test(failure)) throw controllerCommandFailure(folded.stdout, "fold");
const file = join(simulatorProject, "pose.png");
runner({ command: controllerCommand, args: ["screenshot", file, "--session", CONTROLLER_SESSION, ...target, "--platform", options.platform, "--json"],
cwd: simulatorProject, environment: controllerEnvironment, timeoutMs: 60_000 });
const size = pngSize(await readFile(file).catch(() => Buffer.alloc(0)));
await rm(file, { force: true });
const shown = options.devicePose === "open" ? size !== undefined && size.width > size.height
: options.devicePose === "closed" ? size !== undefined && size.height > size.width : true;
if (!shown) throw new CiError({ code: "CONTROLLER_FOLD_UNVERIFIED", stage: "session",
message: `${options.device} did not show the ${options.devicePose} display after folding: ${failure}`,
nextAction: "Rerun; if it persists, check that this EAS Simulator image supports folding the device." });
say(`${options.device} shows the ${options.devicePose} display (the controller could not read the hinge back)`);
}
}
} else fold();
}
runtimeStage = "runtime";
setStage(runtimeStage);
@@ -748,9 +857,28 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
// (APP_NOT_READY). On this machine the capture runs that reader, so it recovers in two steps, each followed by one more
// open: a fresh tool-server, whose reader starts on the lit panel; then, as XcodeBuildMCP#537 found for this panel,
// SpringBoard restarted as well. The bridge's cached view of the device goes with the old server.
// On EAS the tool-server is the session's and must never be stopped, so the recovery there resets Argent's device
// helpers (reset-reader), then restarts SpringBoard as well, and then gives up with a reason rather than retrying.
const easArgentRecovery = !local && controller === "argent" && !!sessionId && options.platform === "ios";
for (let recovery = 0; ; recovery += 1) try { runtime = collect(); break; }
catch (error) {
if (!localArgent || recovery === 2 || toCiError(error).code !== "APP_NOT_READY") throw error;
if (toCiError(error).code !== "APP_NOT_READY") throw error;
if (easArgentRecovery && sessionId) {
if (recovery === 2 || recovery === 1 && !controlActions.has("springboard.restart")) throw new CiError({ code: "CONTROLLER_READER_STUCK", stage: "session",
message: "Argent's accessibility reader kept reading the panel the fold turned off, after its device helpers were reset"
+ `${recovery === 2 ? " and SpringBoard was restarted" : ""}.`,
nextAction: "Rerun the capture; if it keeps happening, report it to Explore: this session's Argent tool-server needs a restart that EAS cannot do yet.", cause: error });
if (recovery === 1) {
say("Argent still did not read the app; restarting SpringBoard, then resetting Argent's device helpers and opening the app again");
simulatorControl(sessionEas, sessionId, "springboard.restart");
// SpringBoard takes a moment to come back, and sends the app to the background; the next open brings it back.
(options.sleep ?? (milliseconds => { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds); }))(8_000);
} else say("Argent did not read the app after starting it; resetting Argent's device helpers and opening the app again");
runner({ command: controllerCommand, args: ["reset-reader", "--session", CONTROLLER_SESSION, "--platform", options.platform, "--json"],
cwd: simulatorProject, environment: controllerEnvironment, timeoutMs: 2 * 60_000 });
continue;
}
if (!localArgent || recovery === 2) throw error;
say(recovery === 0 ? "Argent did not read the app after starting it; restarting Argent's tool-server and opening the app again"
: "Argent still did not read the app; restarting SpringBoard and Argent's tool-server and opening the app again");
stopLocalArgentServer(localArgent);
@@ -786,16 +914,14 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
// Every pass sets the appearance explicitly, so a capture does not inherit whatever the simulator last used.
const passes: CaptureBundle["outcomes"][] = [];
const recordingTools = launchSetting === "off" ? undefined : options.recordingTools === undefined ? ffmpegRecordingTools() : options.recordingTools ?? undefined;
// Argent cannot switch the appearance yet (software-mansion/argent#1509): on EAS its single pass runs as the device
// starts, and on this machine the host switches it.
const applyAppearance = (colorScheme: ColorScheme): void => {
if (controller !== "argent") runner({ command: controllerCommand, args: [...appearanceArgs(colorScheme), "--session", CONTROLLER_SESSION, ...deviceArgs(runtime!), "--platform", options.platform],
for (const [index, colorScheme] of colorSchemes.entries()) {
// Argent cannot switch the appearance yet (software-mansion/argent#1509): the host does, simctl or adb on this
// machine and serve-sim on an EAS iOS session; elsewhere its single pass runs as the device starts.
if (controller !== "argent") runner({ command: controllerCommand, args: [...appearanceArgs(colorScheme), "--session", CONTROLLER_SESSION, ...deviceArgs(runtime), "--platform", options.platform],
cwd: simulatorProject, environment: controllerEnvironment, timeoutMs: 60_000 });
else if (sessionId && controlActions.has("appearance.set")) simulatorControl(sessionEas, sessionId, "appearance.set", [colorScheme]);
else if (localSimulator) setLocalSimulatorAppearance({ runner, udid: localSimulator, scheme: colorScheme, cwd: simulatorProject, environment: restrictedEnvironment });
else if (localEmulator) setLocalEmulatorAppearance({ runner, serial: localEmulator, scheme: colorScheme, cwd: simulatorProject, environment: restrictedEnvironment });
};
for (const [index, colorScheme] of colorSchemes.entries()) {
applyAppearance(colorScheme);
// A scheme change recreates the Android activity in place, and the sheets it re-presents lose their inset; a
// relaunch starts the app in the new scheme, the same way the first pass did.
if (launchSetting !== "off") {
@@ -824,57 +950,6 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
}
runtime.colorScheme = colorSchemes[0]!;
Object.assign(outcomes, mergeSchemeOutcomes(passes, colorSchemes));
if (options.flows) {
runtimeStage = "flows";
// The flows run in the primary appearance, which the last route pass may have left.
if (colorSchemes.length > 1) applyAppearance(colorSchemes[0]!);
// The flows share the deadline the routes had; a flow that fails or runs out of time keeps the frames it took.
const remainingMs = Math.max(60_000, options.maxDurationMinutes * 60_000 - ((options.now ?? Date.now)() - captureStartedAt));
// A daemon lets one agent-device session hold the device, and e2e names its own (`<session>-<slot>`): Explore
// hands the device over by closing its session. The app and the state setup put in it stay on the device.
if (controller !== "argent") runner({ command: options.agentDeviceCommand, args: ["close", "--session", CONTROLLER_SESSION, "--json"], cwd: simulatorProject,
environment: controllerEnvironment, timeoutMs: 60_000, allowFailure: true });
const flowRunOptions = { project, tests: options.flows.tests, platform: options.platform, bundleId: options.bundleId, connection,
...(connection ? {} : { stateDir: join(simulatorProject, "agent-device-state") }), deviceId: runtime.controllerDeviceId,
workDirectory: simulatorProject, runner, environment: controllerEnvironment,
agent: options.flows.agent, frames: options.flows.frames ?? "checkpoints", progress: say, ...(options.environment?.EXPLORE_FLOWS_ENGINE_MODULE ? { engineModule: options.environment.EXPLORE_FLOWS_ENGINE_MODULE } : {}) };
const result = await runFlows({ ...flowRunOptions, outputDirectory: flowsWorkDirectory, timeoutMs: remainingMs });
flowRecords = result.flows;
flowsFailure = result.failure;
if (result.failure) say(`the flows did not run: ${result.failure.message}`);
// The other appearances run the flows again; a frame the primary pass took joins its record as `<key>@<scheme>`
// (the launch convention), so Compare pairs it by appearance. A pass that fails only leaves its frames missing.
for (const colorScheme of colorSchemes.slice(1)) {
if (flowsFailure || controller === "argent" || !Object.keys(flowRecords).length) break;
const schemeRemainingMs = options.maxDurationMinutes * 60_000 - ((options.now ?? Date.now)() - captureStartedAt);
if (schemeRemainingMs < 60_000) { say(`no time left for the ${colorScheme} flows`); break; }
say(`flows in ${colorScheme}`);
// Explore's session comes back to switch the appearance and relaunch the app in it, then hands the device over again.
runner({ command: controllerCommand, args: ["open", options.bundleId, "--session", CONTROLLER_SESSION, ...deviceArgs(runtime), "--platform", options.platform, "--json"],
cwd: simulatorProject, environment: controllerEnvironment, timeoutMs: 5 * 60_000 });
applyAppearance(colorScheme);
runner({ command: controllerCommand, args: ["open", options.bundleId, "--relaunch", "--session", CONTROLLER_SESSION, ...deviceArgs(runtime), "--platform", options.platform, "--level", "full", "--json"],
cwd: simulatorProject, environment: controllerEnvironment, timeoutMs: 60_000 });
runner({ command: options.agentDeviceCommand, args: ["close", "--session", CONTROLLER_SESSION, "--json"], cwd: simulatorProject,
environment: controllerEnvironment, timeoutMs: 60_000, allowFailure: true });
const schemeDirectory = await mkdtemp(join(tmpdir(), `expo-explore-flows-${colorScheme}-`));
try {
const pass = await runFlows({ ...flowRunOptions, outputDirectory: schemeDirectory, timeoutMs: schemeRemainingMs });
if (pass.failure) say(`the ${colorScheme} flows did not run: ${pass.failure.message}`);
for (const [flowId, flow] of Object.entries(pass.flows)) {
const record = flowRecords[flowId];
if (!record) continue;
for (const [key, frame] of Object.entries(flow.frames)) {
if (!record.frames[key]) continue;
const path = flowFramePath(flowId, `${key}@${colorScheme}`);
await mkdir(join(flowsWorkDirectory, dirname(path)), { recursive: true });
await copyFile(join(schemeDirectory, frame.path), join(flowsWorkDirectory, path));
record.frames[`${key}@${colorScheme}`] = { ...frame, path };
}
}
} finally { await rm(schemeDirectory, { recursive: true, force: true }); }
}
}
} catch (error) { primaryError = toCiError(error, { code: `CAPTURE_${runtimeStage.toUpperCase()}_FAILED`, stage: runtimeStage,
nextAction: "Inspect the capture diagnostic, correct the failing prerequisite, and rerun Explore." }); }
finally {
@@ -946,11 +1021,3 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
say(`${captured} of ${selectedIds.length} ${selectedIds.length === 1 ? "route" : "routes"} captured`);
return finish();
}
/** The message of a `fold --json` the controller reported as failed, or undefined when it succeeded. */
function foldFailure(stdout: string): string | undefined {
try {
const parsed = JSON.parse(stdout) as { success?: boolean; error?: { message?: string } };
return parsed.success === false ? String(parsed.error?.message ?? "fold failed") : undefined;
} catch { return undefined; }
}
+42
View File
@@ -0,0 +1,42 @@
import { isRecord } from "./common.js";
/** Runs the pinned EAS CLI with these arguments; throws when it exits non-zero unless `allowFailure` is set. */
export type EasCommand = (args: string[], options?: { timeoutMs?: number; allowFailure?: boolean }) => { stdout: string; stderr?: string };
/**
* The host actions an EAS Simulator iOS session offers through `eas simulator:control` (serve-sim's actions, 0.10.0 and
* later for the ones Explore uses): an empty set when the session or the EAS CLI offers none, so a caller falls back to
* what it did before them. The session is always named by id, never taken from a `.env.eas-simulator` beside it.
*
* These are a fallback: what the session's controller can do itself (agent-device or Argent: fold, appearance, a
* reader reset) goes through the controller. Explore uses an action here only for what neither controller offers —
* approving a link scheme, restarting SpringBoard, and Argent's appearance (software-mansion/argent#1509).
*/
export function simulatorControlActions(eas: EasCommand, sessionId: string): Set<string> {
try {
const listed = eas(["simulator:control", "--list", "--id", sessionId, "--json", "--non-interactive"], { timeoutMs: 2 * 60_000, allowFailure: true });
const actions = JSON.parse(listed.stdout) as unknown;
return new Set(isRecord(actions) ? Object.keys(actions) : []);
} catch { return new Set(); }
}
/** Runs one `eas simulator:control` action on the session; eas-cli fills in the device. Throws with EAS's reason. */
export function simulatorControl(eas: EasCommand, sessionId: string, action: string, values: readonly string[] = []): void {
// Values follow `--` so one that starts with a dash is never read as a flag.
eas(["simulator:control", action, "--id", sessionId, "--json", "--non-interactive", "--", ...values], { timeoutMs: 2 * 60_000 });
}
/**
* Lets the app open its own links without iOS asking "Open in “App”?" first, like local captures do with simctl. A
* session without the action keeps the controllers' prompt handling; http and https never prompt and are skipped.
*/
export function approveSessionUrlSchemes(eas: EasCommand, sessionId: string, actions: ReadonlySet<string>, bundleId: string, schemes: readonly string[]): string[] {
if (!actions.has("app.approveUrlScheme")) return [];
const approved: string[] = [];
for (const scheme of new Set(schemes.map(value => value.toLowerCase()))) {
if (scheme === "http" || scheme === "https" || !/^[a-z][a-z0-9+.-]*$/.test(scheme)) continue;
simulatorControl(eas, sessionId, "app.approveUrlScheme", [bundleId, scheme]);
approved.push(scheme);
}
return approved;
}
+41 -11
View File
@@ -237,17 +237,7 @@ export function assertSimulatorSessionIdentity(
) {
throw new Error("eas simulator:get did not prove the exact expected simulator session");
}
// eas-cli 22.4.0 omits the `app` record; its `deviceRunSessionUrl` still binds the session
// to one exact owner and slug, so accept either proof but never neither.
const expectedSessionUrl = `https://expo.dev/accounts/${expectedProject.owner}`
+ `/projects/${expectedProject.slug}/simulator-sessions/${expectedSessionId}`;
const projectProven = isRecord(value.app)
? value.app.id === expectedProject.projectId
&& value.app.slug === expectedProject.slug
&& isRecord(value.app.ownerAccount)
&& value.app.ownerAccount.name === expectedProject.owner
: value.deviceRunSessionUrl === expectedSessionUrl;
if (!projectProven) {
if (!sessionProjectProven(value, expectedSessionId, expectedProject)) {
throw new Error("eas simulator:get did not prove the exact expected simulator session");
}
if (expectedConnection && !remoteConfigMatches(value.remoteConfig, expectedConnection)) {
@@ -255,6 +245,46 @@ export function assertSimulatorSessionIdentity(
}
}
/**
* eas-cli 22.4.0 omits the `app` record; its `deviceRunSessionUrl` still binds the session to one exact owner and
* slug, so either proof is accepted but never neither.
*/
function sessionProjectProven(value: Record<string, unknown>, sessionId: string, project: RepackProfile["projectIdentity"]): boolean {
const expectedSessionUrl = `https://expo.dev/accounts/${project.owner}/projects/${project.slug}/simulator-sessions/${sessionId}`;
return isRecord(value.app)
? value.app.id === project.projectId && value.app.slug === project.slug && isRecord(value.app.ownerAccount) && value.app.ownerAccount.name === project.owner
: value.deviceRunSessionUrl === expectedSessionUrl;
}
/**
* The status (ERRORED or STOPPED) of a session `eas simulator:get` shows EAS ended before Explore could use it, when it
* is provably this capture's own: the exact id, name, type, platform and project. Only such a session is replaced by a
* new one; anything less certain (undefined here) stays a handoff failure.
*/
export function endedOwnSimulatorSession(stdout: string, expected: { sessionId: string; sessionName: string; project: RepackProfile["projectIdentity"];
type: "agent-device" | "argent"; platform: Platform }): "ERRORED" | "STOPPED" | undefined {
let value: unknown;
try { value = JSON.parse(stdout); } catch { return undefined; }
return isRecord(value) && value.id === expected.sessionId && value.name === expected.sessionName && value.type === expected.type
&& value.platform === expected.platform.toUpperCase() && (value.status === "ERRORED" || value.status === "STOPPED")
&& sessionProjectProven(value, expected.sessionId, expected.project) ? value.status : undefined;
}
/**
* This project's sessions with exactly this name that EAS may still be starting or running, from
* `eas simulator:list --json`: their ids when every one is provably this project's, or undefined when the listing
* cannot be read or a session by that name cannot be proven Explore's, so a caller never assumes none exist.
*/
export function liveSimulatorSessionsNamed(stdout: string, sessionName: string, project: RepackProfile["projectIdentity"]): string[] | undefined {
let value: unknown;
try { value = JSON.parse(stdout); } catch { return undefined; }
if (!isRecord(value) || !Array.isArray(value.sessions)) return undefined;
const live = new Set(["NEW", "QUEUED", "STARTING", "IN_PROGRESS"]);
const named = value.sessions.filter((session): session is Record<string, unknown> => isRecord(session) && session.name === sessionName && live.has(String(session.status)));
if (named.some(session => typeof session.id !== "string" || !/^[A-Za-z0-9._-]{1,256}$/.test(session.id) || !sessionProjectProven(session, session.id, project))) return undefined;
return named.map(session => session.id as string);
}
/** The session's published controller endpoint is the one Explore holds: agent-device's daemon, or Argent's tool-server. */
function remoteConfigMatches(remoteConfig: unknown, connection: SimulatorConnection): boolean {
if (!isRecord(remoteConfig)) return false;
-1
View File
@@ -35,7 +35,6 @@ export function captureRecipeConfig(config: ExploreConfig, instructionsSha256?:
app: { platform: config.app.platform, bundleId: config.app.bundleId, easProfile: config.app.easProfile,
...(config.app.scheme === undefined ? {} : { scheme: config.app.scheme }) },
device: config.device, parameters: config.parameters, setup: config.setup ?? [],
...(config.flows ? { flows: config.flows } : {}),
// The repack as it resolves, so a config that leaves it to the default keeps the recipe it had when the default was written out.
capture: { ...config.capture, repack: captureRepack(config) },
// agent-device recipes stay as they were; an Argent capture is keyed to the Argent release that drove it.
+16 -40
View File
@@ -2,7 +2,7 @@ import { spawnSync } from "node:child_process";
import { readFileSync } from "node:fs";
import { lstat, mkdir, readdir, readFile, realpath } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join, relative, sep } from "node:path";
import { join, sep } from "node:path";
import { CiError, toCiError } from "../shared/ci-errors.js";
import type { CaptureBundle } from "../contracts/capture.js";
import type { SourceCapturePlan } from "../source/capture-plan.js";
@@ -10,7 +10,6 @@ import type { CommandRunner } from "../capture/run.js";
import { runBaselineCi } from "./pipeline.js";
import { DEFAULT_EXPLORE_CONFIG_PATH, captureRepack, configTargets, readExploreConfig, readExploreInstructions, resolveTargetConfig, withRunOverrides, type ExploreConfig, type ExplorePlatform } from "../config/explore-config.js";
import { explorationSecretNames } from "../config/exploration-inputs.js";
import { FLOWS_OUTPUT_DIRECTORY } from "../capture/flows/run-flows.js";
import { controllerCached } from "../shared/controller-cache.js";
import { androidTools, hostEmulatorAbi, localSimulatorTarget, localSystemImage } from "../capture/local-simulator.js";
import { ARGENT_VERSION } from "../shared/argent-version.js";
@@ -92,36 +91,6 @@ export function referencedSecretNames(config: ExploreConfig, instructions?: stri
...(config.setup ?? []).map(action => action.action === "fill" || action.action === "type" ? action.text : "")].join("\n"));
}
/** `**` crosses directories, `*` and `?` stay inside a segment; the rest is literal. */
function globToRegExp(glob: string): RegExp {
const source = glob.split("**").map(part => part.split("*").map(piece => piece.split("?").map(ch => ch.replace(/[.+^${}()|[\]\\]/g, "\\$&")).join("[^/]")).join("[^/]*")).join("(?:.*)");
return new RegExp(`^${source.replace(/^\(\?:\.\*\)\//, "(?:.*/)?")}$`);
}
/** The flows the capture would run: each entry of flows.tests names a committed file, and the app can import `e2e`. */
async function flowChecks(project: string, config: ExploreConfig): Promise<DoctorCheck[]> {
if (!config.flows) return [];
const checks: DoctorCheck[] = [];
const files = (await readdir(project, { recursive: true, withFileTypes: true }).catch(() => []))
.filter(entry => entry.isFile() && !relative(project, entry.parentPath).split(sep).includes("node_modules"))
.map(entry => relative(project, join(entry.parentPath, entry.name)).split(sep).join("/"));
const unmatched = config.flows.tests.filter(pattern => /[*?]/.test(pattern) ? !files.some(file => globToRegExp(pattern).test(file)) : !files.includes(pattern));
const matched = new Set(config.flows.tests.flatMap(pattern => /[*?]/.test(pattern) ? files.filter(file => globToRegExp(pattern).test(file)) : files.includes(pattern) ? [pattern] : []));
checks.push(unmatched.length
? { step: 4, id: "flows-tests", status: "fail", code: "FLOWS_TESTS_MISSING", message: `flows.tests names no file for ${unmatched.map(pattern => `"${pattern}"`).join(", ")}.`,
nextAction: "Point flows.tests at the app's committed e2e test files (for example e2e/**/*.e2e.ts), or add the files." }
: { step: 4, id: "flows-tests", status: "pass", message: `flows.tests matches ${matched.size} e2e test file${matched.size === 1 ? "" : "s"}.` });
const e2ePackage = await readFile(join(project, "node_modules", "e2e", "package.json"), "utf8").then(text => JSON.parse(text) as { version?: string }).catch(() => undefined);
checks.push(e2ePackage
? { step: 4, id: "flows-e2e", status: "pass", message: `The app resolves e2e ${e2ePackage.version ?? ""}`.trim() + "." }
: { step: 4, id: "flows-e2e", status: "warn", code: "FLOWS_E2E_UNRESOLVED", message: "The app's node_modules has no e2e package; its test files import it.",
nextAction: "Add e2e to the app's devDependencies and install (the capture installs the committed lockfile)." });
if (await lstat(join(project, FLOWS_OUTPUT_DIRECTORY)).catch(() => undefined)) checks.push({ step: 4, id: "flows-output", status: "warn", code: "FLOWS_OUTPUT_EXISTS",
message: `${FLOWS_OUTPUT_DIRECTORY} is in the app directory; a capture writes e2e's output there and removes it when it ends.`,
nextAction: `Remove ${FLOWS_OUTPUT_DIRECTORY} (a previous run was interrupted) and keep it out of the commit.` });
return checks;
}
function routeChecks(config: ExploreConfig, report: RouteEntryReport): DoctorCheck[] {
const checks: DoctorCheck[] = [];
const deterministic = config.mode === "deterministic";
@@ -505,7 +474,8 @@ export async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
checks.push(config.mode === "agent"
? { step: 3, id: "mode", status: "pass", message: `Agent mode with ${config.agent!.provider} ${config.agent!.model}. Capture navigation uses the model and is billed to your ${config.agent!.provider} account.` }
: { step: 3, id: "mode", status: "pass", message: "Deterministic mode: capture replays config.yaml without a model, so it needs no API key and has no AI charges." });
if (runTargets(config, { controller: options.controller }).some(target => target.capture.controller === "argent")) checks.push(argentCheck(environment));
const argentTargets = runTargets(config, { controller: options.controller }).filter(target => target.capture.controller === "argent");
if (argentTargets.length) checks.push(argentCheck(environment, argentTargets.some(target => target.app.platform === "android" && target.capture.simulator !== "local")));
if (config.capture.launch !== "off") {
const ffmpeg = run("ffmpeg", ["-version"], project);
checks.push(ffmpeg.status === 0
@@ -539,7 +509,6 @@ export async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
try {
routes = readRouteEntry(project, config);
checks.push(...routeChecks(config, routes));
checks.push(...await flowChecks(project, config));
} catch (error) {
checks.push(fromError(5, "routes", error, { code: "SOURCE_ANALYSIS_FAILED", nextAction: "Commit the app source and check navigation.provider and navigation.entry." }));
}
@@ -662,13 +631,20 @@ export function summarizeCaptureCheck(plan: SourceCapturePlan, bundle: CaptureBu
* Capture the committed HEAD the way the baseline workflow does, with the local EAS login. This is
* the only doctor step that starts an EAS build and a simulator session.
*/
/** An Argent capture records one appearance, and fetches the pinned Argent release on first use. agent-device, the default, is not reported. */
function argentCheck(environment: NodeJS.ProcessEnv): DoctorCheck {
/**
* Argent fetches its pinned release on first use, and cannot switch the appearance itself (software-mansion/argent#1509):
* the host does, through `simulator:control` on an iOS EAS session or simctl and adb on this Mac. Only an Android EAS
* session has no host to ask, so its captures record one appearance. agent-device, the default, is not reported.
*/
function argentCheck(environment: NodeJS.ProcessEnv, androidOnEas: boolean): DoctorCheck {
const cached = controllerCached("argent", environment);
return { step: 3, id: "controller", status: "warn", code: "CONTROLLER_APPEARANCE_FIXED",
message: `Device controller: Argent ${ARGENT_VERSION} (${cached ? "cached on this machine" : "fetched from npm on the first capture, about 27 MB"}). `
+ "Argent cannot switch the simulator's appearance yet (software-mansion/argent#1509), so each capture records one appearance: the app's forced one, else light.",
nextAction: "Nothing to do unless you need dark-mode screenshots; use agent-device (the default) for those." };
const release = `Device controller: Argent ${ARGENT_VERSION} (${cached ? "cached on this machine" : "fetched from npm on the first capture, about 27 MB"}). `;
return androidOnEas
? { step: 3, id: "controller", status: "warn", code: "CONTROLLER_APPEARANCE_FIXED",
message: `${release}Argent cannot switch the appearance on an Android EAS Simulator session yet (software-mansion/argent#1509), so those captures record one appearance: the app's forced one, else light.`,
nextAction: "Nothing to do unless you need dark-mode screenshots on Android; use agent-device (the default) for those." }
: { step: 3, id: "controller", status: "pass",
message: `${release}The simulator's host switches the appearance, so every appearance the config asks for is captured.` };
}
export async function runCaptureCheck(options: { project: string; output: string; platform?: ExplorePlatform; controller?: string | undefined; simulator?: string | undefined; repack?: string | undefined; target?: string | undefined; environment?: NodeJS.ProcessEnv; runner?: CommandRunner; progress?: Progress }): Promise<CaptureCheckResult> {
+1 -3
View File
@@ -48,8 +48,6 @@ export type LocalReviewOptions = {
parallel?: number | undefined;
scope?: string | undefined;
expiresIn?: string | undefined;
/** e2e files or globs to run as the capture instead of the config's mode (`--flows`). */
flows?: readonly string[] | undefined;
/** `--controller`: the device controller for both sides, over the config's `capture.controller`. */
controller?: string | undefined;
/** `--simulator`: `local` runs both sides on simulators this Mac creates, over the config's `capture.simulator`. */
@@ -460,7 +458,7 @@ export async function runLocalReview(options: LocalReviewOptions): Promise<Local
});
// The targets run at once, as CI runs them in parallel jobs: each on its own simulators, with its own output.
const captureTarget = async (target: RunTarget): Promise<LocalReviewReport> => {
const config = withRunOverrides(resolveTargetConfig(rawConfig, { target: target.id }), { scope: options.scope, expiresIn: options.expiresIn, flows: options.flows, controller: options.controller, simulator: options.simulator, repack: options.repack });
const config = withRunOverrides(resolveTargetConfig(rawConfig, { target: target.id }), { scope: options.scope, expiresIn: options.expiresIn, controller: options.controller, simulator: options.simulator, repack: options.repack });
const platform = target.platform;
const output = join(work, target.id); await mkdir(output);
outputs.push(output);
+7 -16
View File
@@ -1,5 +1,4 @@
import type { RunTarget } from "../types.js";
import { FLOWS_OUTPUT_DIRECTORY } from "../capture/flows/run-flows.js";
import { spawnSync } from "node:child_process";
import { mkdir, open, readFile, realpath, writeFile } from "node:fs/promises";
import { join, relative, resolve, isAbsolute } from "node:path";
@@ -41,17 +40,10 @@ function requireSecret(environment: NodeJS.ProcessEnv, name: string): string {
return value;
}
function assertCheckout(project: string, sha: string): void {
// Explore's own flows scratch directory (another target's flows may be running in the same checkout) is not a change.
const checks = [
[["rev-parse", "HEAD"], sha],
[["status", "--porcelain", "--untracked-files=normal", "--", ".", `:(exclude)${FLOWS_OUTPUT_DIRECTORY}`], ""],
] as const;
for (const [args, expected] of checks) {
for (const [args, expected] of [[ ["rev-parse", "HEAD"], sha ], [["status", "--porcelain", "--untracked-files=normal"], ""]] as const) {
const result = spawnSync("git", ["-C", project, ...args], { encoding: "utf8" });
const observed = result.stdout.trim();
if (result.status !== 0 || observed !== expected) throw new CiError({
code: "SOURCE_CHECKOUT_MISMATCH", stage: "preflight",
message: `Source checkout does not match ${sha} (${args[0] === "rev-parse" ? `HEAD is ${observed.slice(0, 12) || "unreadable"}` : `changed: ${observed.split("\n").slice(0, 3).join(", ")}`}).`,
if (result.status !== 0 || result.stdout.trim() !== expected) throw new CiError({
code: "SOURCE_CHECKOUT_MISMATCH", stage: "preflight", message: `Source checkout does not match ${sha}.`,
nextAction: "Check out the exact recorded commit and remove generated changes from the source checkout." });
}
}
@@ -78,7 +70,6 @@ function captureOptions(config: ExploreConfig, environment: NodeJS.ProcessEnv, r
maxScreens: 5000, maxActions: config.capture.maxActions, maxDurationMinutes: config.capture.maxMinutes,
setup: config.setup ?? [], forceFreshBuild: false, confirmExternalRun: true, confirmTrustedSource: true, repack: captureRepack(config), appearance: config.capture.appearance, launch: config.capture.launch, reset: config.capture.reset, unattributed: config.capture.unattributed, ...(config.capture.readinessSeconds !== undefined ? { readinessSeconds: config.capture.readinessSeconds } : {}), ...(config.capture.controller ? { controller: config.capture.controller } : {}),
...(config.capture.simulator ? { simulator: config.capture.simulator } : {}),
...(config.flows ? { flows: { tests: config.flows.tests, only: config.mode === "flows", ...(config.flows.frames ? { frames: config.flows.frames } : {}), ...(config.agent ? { agent: { provider: config.agent.provider, model: config.agent.model } } : {}) } } : {}),
environment, ...(runner ? { runner } : {}), easCommand: packageBin("eas-cli", "eas"), agentDeviceCommand: agentDeviceLauncher(environment), repackCommand: packageBin("@expo/repack-app", "repack-app") };
}
/**
@@ -159,7 +150,8 @@ async function prepareCiRun(options: Pick<PublicCiOptions, "baseProject" | "head
links: viewerLinks({ repository: presentation.repository, headSha: presentation.head.sha, runId: environment.GITHUB_RUN_ID!,
runAttempt: environment.GITHUB_RUN_ATTEMPT!, configPath: repositoryConfigPath }),
startedAt: now(), updatedAt: now(), build: { platform: config.app.platform, easProfile: config.app.easProfile }, artifactOnly: true,
...(config.target ? { target: config.target } : {}), ...(options.targets && options.targets.length > 1 ? { targets: options.targets } : {}) };
...(config.target ? { target: config.target } : {}), ...(options.targets && options.targets.length > 1 ? { targets: options.targets } : {}),
...(config.report?.comment?.map ? { map: true } : {}) };
return { projects, output, state };
}
@@ -301,8 +293,7 @@ export async function runCiReview(options: {
done: { base: 0, head: 0 }, baseFromCache: false };
await assertCurrentHead(); await postComment();
stage = "preflight";
// A side with routes to capture, or flows to run, needs the token, the installed dependencies and a session.
const active = plan.headCaptureSurfaceIds.length + plan.baseCaptureSurfaceIds.length > 0 || config.flows !== undefined;
const active = plan.headCaptureSurfaceIds.length + plan.baseCaptureSurfaceIds.length > 0;
if (active && !options.useLocalEasSession) requireSecret(environment, "EXPO_TOKEN");
const exploration = await prepareCiExploration(config, projects.head, environment, active,
{ ...(options.agentSessionFactory ? { createSession: options.agentSessionFactory } : {}),
@@ -487,7 +478,7 @@ export async function runBaselineCi(options: { platform?: ExplorePlatform; proje
const plan = await buildVerifiedPlan({ baseProject: options.project, headProject: options.project,
baseSha: options.sha, headSha: options.sha, config: options.config, output, scope: "all" });
progress(planSummary(plan, true));
const active = plan.headCaptureSurfaceIds.length > 0 || options.config.flows !== undefined;
const active = plan.headCaptureSurfaceIds.length > 0;
if (active && !options.useLocalEasSession) requireSecret(environment, "EXPO_TOKEN");
let usagePhase: AgentUsagePhase = "preflight";
const exploration = await prepareCiExploration(options.config, options.project, environment, active,
-2
View File
@@ -91,8 +91,6 @@ export async function buildVerifiedPlan(options: {
changedFiles: internal,
externalChanges: external,
mode: options.scope ?? config.exploration.scope,
// Flows mode keeps the route inventory for the map and the navigation context, and captures none of it.
...(config.mode === "flows" ? { captureRoutes: false } : {}),
...(config.exploration.exclude ? { exclude: config.exploration.exclude } : {}),
provider: config.navigation.provider,
...(config.navigation.entry ? { entry: config.navigation.entry } : {}),
+1 -1
View File
@@ -85,7 +85,7 @@ const flagKinds: Record<string, Record<string, "value" | "boolean">> = {
validate: {},
export: { output: "value" },
"export:web": {catalog:"value",output:"value"},
"capture:review": { "base-project":"value", "head-project":"value", "pull-request":"value", compare:"value", output:"value", config:"value", parallel:"value", target:"value", platform:"value", controller:"value", simulator:"value", repack:"value", flows:"value", scope:"value", "expires-in":"value",
"capture:review": { "base-project":"value", "head-project":"value", "pull-request":"value", compare:"value", output:"value", config:"value", parallel:"value", target:"value", platform:"value", controller:"value", simulator:"value", repack:"value", scope:"value", "expires-in":"value",
base:"value", head:"value", project:"value", committed:"boolean", uncommitted:"boolean", "include-untracked":"boolean", upload:"boolean", "no-open":"boolean", "no-cache":"boolean", port:"value" },
-1
View File
@@ -250,7 +250,6 @@ async function localReview(): Promise<void> {
...(parallel ? { parallel } : {}),
// --include-untracked is accepted from before untracked files were included by default.
committed: has("committed"), uncommitted: has("uncommitted"), ...(platform ? { platform } : {}),
...(has("flows") ? { flows: required("flows").split(",") } : {}),
scope: flag("scope"), expiresIn: flag("expires-in"), controller: flag("controller"), simulator: flag("simulator"), repack: flag("repack"), cache: !has("no-cache"), configPath: flag("config"), progress: stderrProgress() });
if (has("output")) {
for (const report of result.reports) {
+1 -1
View File
@@ -17,7 +17,7 @@ const GET_STARTED = `Get started (run these in the Expo app's directory):
(--offline skips EAS and GitHub; --check-model sends one small request with the local provider key)
doctor --capture [--project DIRECTORY] [--output DIRECTORY] [--target ID | --platform ios|android] [--controller agent-device|argent] [--simulator eas|local] [--repack eas|local] [--yes]
(captures the committed HEAD like the baseline workflow, with your eas login, and reports each route)
capture [--base REF] [--head REF | --committed] [--target ID | --platform ios|android] [--parallel N] [--scope all|changes] [--flows FILE[,FILE]]
capture [--base REF] [--head REF | --committed] [--target ID | --platform ios|android] [--parallel N] [--scope all|changes]
[--controller agent-device|argent] [--simulator eas|local] [--repack eas|local] [--upload [--expires-in 7d|30d|never]] [--no-open] [--no-cache] [--output DIRECTORY] [--project DIRECTORY]
(on this machine: checks out both commits in temporary worktrees, captures them with your eas login (in agent
mode, also your local claude or codex login), and opens the report; the head is HEAD with your uncommitted changes, as eas build
+34 -62
View File
@@ -48,9 +48,7 @@ export const DEFAULT_ANDROID_DEVICE = "pixel_7";
export const DEVICE_POSES = ["closed", "half-open", "open"] as const;
export type DevicePose = typeof DEVICE_POSES[number];
export type PlatformConfig = { device?: string; bundleId?: string; easProfile?: string;
/** This platform's flows, over the top-level `flows` (e2e's own `platforms` option filters tests within a file). */
flows?: { tests: string[]; frames?: "checkpoints" | "steps" } };
export type PlatformConfig = { device?: string; bundleId?: string; easProfile?: string };
/**
* One named capture target (`targets.<id>`): a platform's device, optionally in a pose, captured as its own report.
@@ -58,9 +56,7 @@ export type PlatformConfig = { device?: string; bundleId?: string; easProfile?:
*/
export type TargetConfig = { platform: ExplorePlatform; device?: string; pose?: DevicePose; bundleId?: string; easProfile?: string; label?: string;
/** This target's device controller and simulator, over `capture.controller` and `capture.simulator`. */
controller?: "agent-device" | "argent"; simulator?: "eas" | "local";
/** This target's flows, over the top-level `flows`: a foldable may run its own journeys, a phone the common ones. */
flows?: { tests: string[]; frames?: "checkpoints" | "steps" } };
controller?: "agent-device" | "argent"; simulator?: "eas" | "local" };
/**
* A target id names directories, report files, CI artifacts and URL parameters, so it is short and plain. `base` and
@@ -75,8 +71,7 @@ export function isTargetId(value: unknown): value is string {
/** Source discovery never consumes a user-authored screen inventory. */
export type ExploreConfig = {
/** `flows` runs setup and the configured flows only; `deterministic` with `flows` runs the route links and then the flows. */
mode: "deterministic" | "agent" | "flows";
mode: "deterministic" | "agent";
app: { name?: string; platform: ExplorePlatform; bundleId: string; easProfile: string; scheme?: string };
navigation: { provider: "auto" | "expo-router" | "react-navigation"; entry?: string };
/**
@@ -107,11 +102,11 @@ export type ExploreConfig = {
simulator?: "local" };
parameters?: Record<string, Record<string, string>>;
setup?: ExploreSetupAction[];
/** The app's e2e flows (test files of the `e2e` package) the capture runs on each revision, as paths or globs from the app directory. */
flows?: { tests: string[]; frames?: "checkpoints" | "steps" };
agent?: { provider: "openai" | "anthropic"; model: string; instructions?: string };
/** Hosted previews: one token-gated EAS Hosting deployment per review, see docs/private-review.md. */
report?: { preview?: { hosting: "eas"; /** null: the link never expires; the deployment lives until someone deletes it. */ expiresAfterDays: number | null; owner?: string; project?: string } };
report?: { preview?: { hosting: "eas"; /** null: the link never expires; the deployment lives until someone deletes it. */ expiresAfterDays: number | null; owner?: string; project?: string };
/** `map`: the PR comment draws a Mermaid map of the changed screens and the screens that lead to them. Off by default. */
comment?: { map: boolean } };
/**
* `trustedAuthors`: GitHub logins (e.g. `devin-ai-integration[bot]`) whose same-repository pull
* requests the review workflow captures although they lack write access. The workflow reads this
@@ -278,34 +273,10 @@ function parameters(value: unknown): Record<string, Record<string, string>> {
}));
}
/** The flows the capture runs: the app's e2e test files. `flows` mode needs them; agent mode has no room for them yet. */
function flowsConfig(value: unknown, mode: ExploreConfig["mode"]): ExploreConfig["flows"] {
if (value === undefined) {
if (mode === "flows") fail("flows.tests is required in flows mode", "flows", "List the e2e test files (or globs) the capture runs, for example `flows: { tests: [e2e/**/*.e2e.ts] }`.");
return undefined;
}
if (mode === "agent") fail("flows cannot be combined with agent mode", "flows", "Use mode: flows, or mode: deterministic with flows, so the agent and the flows do not drive the device at once.");
return flowTests(value, "flows");
}
/** `{ tests: [...] }` at `label`: e2e files or globs inside the app directory. Targets and platforms carry their own. */
function flowTests(value: unknown, label: string): NonNullable<ExploreConfig["flows"]> {
const input = record(value, label);
exactKeys(input, ["tests", "frames"], label);
const tests = Array.isArray(input.tests) ? input.tests : input.tests === undefined ? [] : [input.tests];
if (!tests.length || tests.length > 100) fail(`${label}.tests must list between 1 and 100 test files or globs`, `${label}.tests`);
if (input.frames !== undefined && input.frames !== "checkpoints" && input.frames !== "steps") fail(`${label}.frames must be "checkpoints" (frames where the flows call app.screenshot) or "steps" (a frame after every step)`, `${label}.frames`);
return { ...(input.frames === "steps" ? { frames: "steps" as const } : {}), tests: tests.map((entry, index) => {
const path = text(entry, `${label}.tests[${index}]`, 512);
if (isAbsolute(path) || path.split(/[\\/]/).includes("..") || /[\u0000-\u001f]/.test(path)) fail(`${label}.tests[${index}] must be a path or glob inside the app directory`, `${label}.tests[${index}]`);
return path.replace(/\\/g, "/");
}) };
}
/** Validate and normalize plain data; credential validation is a separate execution gate. */
export function validateExploreConfig(value: unknown): ExploreConfig {
const root = record(value, "config");
exactKeys(root, ["mode", "app", "navigation", "device", "platforms", "targets", "exploration", "capture", "parameters", "setup", "flows", "agent", "report", "ci"], "config");
exactKeys(root, ["mode", "app", "navigation", "device", "platforms", "targets", "exploration", "capture", "parameters", "setup", "agent", "report", "ci"], "config");
const app = record(root.app, "app");
exactKeys(app, ["name", "platform", "bundleId", "easProfile", "scheme"], "app");
const device = record(root.device, "device");
@@ -319,7 +290,7 @@ export function validateExploreConfig(value: unknown): ExploreConfig {
exactKeys(capture, ["maxMinutes", "maxActions", "repack", "appearance", "launch", "reset", "unattributed", "readinessSeconds", "controller", "simulator"], "capture");
const controller = literal(capture.controller, ["agent-device", "argent"] as const, "capture.controller", "agent-device");
const simulator = literal(capture.simulator, ["eas", "local"] as const, "capture.simulator", "eas");
const mode = literal(root.mode, ["deterministic", "agent", "flows"] as const, "mode", "deterministic");
const mode = literal(root.mode, ["deterministic", "agent"] as const, "mode", "deterministic");
const name = optionalText(app.name, "app.name", 128);
const scheme = app.scheme === undefined ? undefined : customScheme(app.scheme, "app.scheme");
const platform = literal(app.platform, EXPLORE_PLATFORMS, "app.platform", "ios");
@@ -328,7 +299,6 @@ export function validateExploreConfig(value: unknown): ExploreConfig {
const platforms = platformsConfig(root.platforms, platform);
const targets = targetsConfig(root.targets, platform);
if (platforms && targets) fail("Use targets or platforms, not both", "targets", "Move each platforms entry into targets, with its platform.");
if (mode === "agent" && [...Object.values(platforms ?? {}), ...Object.values(targets ?? {})].some(entry => entry.flows)) fail("flows cannot be combined with agent mode", "flows", "Use mode: flows, or mode: deterministic with flows, so the agent and the flows do not drive the device at once.");
let agent: ExploreConfig["agent"];
if (root.agent !== undefined || mode === "agent") {
const input = record(root.agent, "agent");
@@ -341,7 +311,6 @@ export function validateExploreConfig(value: unknown): ExploreConfig {
if (mode === "agent" && !agent.instructions) fail("agent.instructions is required in agent mode", "agent.instructions",
"Use the explore-setup skill to write app-specific instructions and set agent.instructions to their repository-relative path.");
}
const flows = flowsConfig(root.flows, mode);
const report = reportConfig(root.report);
const ci = ciConfig(root.ci);
return {
@@ -376,7 +345,6 @@ export function validateExploreConfig(value: unknown): ExploreConfig {
},
...(root.parameters === undefined ? {} : { parameters: parameters(root.parameters) }),
...(root.setup === undefined ? {} : { setup: setupActions(root.setup, scheme) }),
...(flows === undefined ? {} : { flows }),
...(agent === undefined ? {} : { agent }),
...(report === undefined ? {} : { report }),
...(ci === undefined ? {} : { ci }),
@@ -405,16 +373,15 @@ function platformsConfig(value: unknown, primary: ExplorePlatform): ExploreConfi
for (const platform of entries) {
const label = `platforms.${platform}`;
const entry = mapping[platform] === null ? {} : record(mapping[platform], label);
exactKeys(entry, ["device", "bundleId", "easProfile", "flows"], label);
exactKeys(entry, ["device", "bundleId", "easProfile"], label);
const device = optionalText(entry.device, `${label}.device`, 128);
const flows = entry.flows === undefined ? undefined : flowTests(entry.flows, `${label}.flows`);
const bundleId = entry.bundleId === undefined ? undefined : applicationId(entry.bundleId, `${label}.bundleId`);
const easProfile = entry.easProfile === undefined ? undefined : profileName(entry.easProfile, `${label}.easProfile`);
if (platform !== primary && (bundleId === undefined || easProfile === undefined)) {
fail(`${label} needs bundleId and easProfile`, label,
`Set ${label}.bundleId to the app's ${platform === "android" ? "android.package" : "ios.bundleIdentifier"} and ${label}.easProfile to an eas.json profile that builds a ${platform === "android" ? "signed APK (android.buildType: apk)" : "simulator app (ios.simulator: true)"}.`);
}
result[platform] = { ...(device === undefined ? {} : { device }), ...(bundleId === undefined ? {} : { bundleId }), ...(easProfile === undefined ? {} : { easProfile }), ...(flows === undefined ? {} : { flows }) };
result[platform] = { ...(device === undefined ? {} : { device }), ...(bundleId === undefined ? {} : { bundleId }), ...(easProfile === undefined ? {} : { easProfile }) };
}
return result;
}
@@ -430,8 +397,7 @@ function targetsConfig(value: unknown, primary: ExplorePlatform): ExploreConfig[
const label = `targets.${id}`;
if (!isTargetId(id)) fail(`${label}: a target id is lowercase letters, digits and dashes, starts with a letter, and is not base, head or report`, label);
const entry = record(mapping[id], label);
exactKeys(entry, ["platform", "device", "pose", "bundleId", "easProfile", "label", "controller", "simulator", "flows"], label);
const flows = entry.flows === undefined ? undefined : flowTests(entry.flows, `${label}.flows`);
exactKeys(entry, ["platform", "device", "pose", "bundleId", "easProfile", "label", "controller", "simulator"], label);
const platform = literal(entry.platform, EXPLORE_PLATFORMS, `${label}.platform`);
const device = optionalText(entry.device, `${label}.device`, 128);
const pose = entry.pose === undefined ? undefined : literal(entry.pose, DEVICE_POSES, `${label}.pose`);
@@ -446,7 +412,7 @@ function targetsConfig(value: unknown, primary: ExplorePlatform): ExploreConfig[
}
result[id] = { platform, ...(device === undefined ? {} : { device }), ...(pose === undefined ? {} : { pose }), ...(bundleId === undefined ? {} : { bundleId }),
...(easProfile === undefined ? {} : { easProfile }), ...(name === undefined ? {} : { label: name }),
...(controller === undefined ? {} : { controller }), ...(simulator === undefined ? {} : { simulator }), ...(flows === undefined ? {} : { flows }) };
...(controller === undefined ? {} : { controller }), ...(simulator === undefined ? {} : { simulator }) };
}
return result;
}
@@ -498,7 +464,7 @@ export function resolveTargetConfig(config: ExploreConfig, selection: { target?:
void _controller; void _simulator;
const controller = entry.controller ?? config.capture.controller ?? "agent-device";
const simulator = entry.simulator ?? config.capture.simulator ?? "eas";
return { ...rest, target: chosen, ...(entry.flows ? { flows: entry.flows } : {}),
return { ...rest, target: chosen,
capture: { ...capture, ...(controller === "argent" ? { controller } : {}), ...(simulator === "local" ? { simulator } : {}) },
app: { ...config.app, platform: entry.platform, bundleId: entry.bundleId ?? config.app.bundleId, easProfile: entry.easProfile ?? config.app.easProfile },
device: { name: entry.device ?? (primary ? config.device.name : DEFAULT_ANDROID_DEVICE),
@@ -531,7 +497,7 @@ export function resolvePlatformConfig(config: ExploreConfig, platform: ExplorePl
const primary = platform === config.app.platform;
const { platforms: _platforms, ...rest } = config;
void _platforms;
return { ...rest, ...(entry.flows ? { flows: entry.flows } : {}),
return { ...rest,
app: { ...config.app, platform, bundleId: entry.bundleId ?? (primary ? config.app.bundleId : fail(`platforms.${platform}.bundleId is required`)),
easProfile: entry.easProfile ?? (primary ? config.app.easProfile : fail(`platforms.${platform}.easProfile is required`)) },
device: { name: entry.device ?? (primary ? config.device.name : platform === "android" ? DEFAULT_ANDROID_DEVICE : config.device.name),
@@ -544,16 +510,8 @@ export function resolvePlatformConfig(config: ExploreConfig, platform: ExplorePl
* every screen (`scope: all`) and keep its hosted link (`expiresIn: never`). `expiresIn` changes nothing when the
* config hosts no report.
*/
export function withRunOverrides(config: ExploreConfig, overrides: { scope?: string | undefined; expiresIn?: string | undefined; controller?: string | undefined; simulator?: string | undefined; repack?: string | undefined ; flows?: readonly string[] | undefined }): ExploreConfig{
export function withRunOverrides(config: ExploreConfig, overrides: { scope?: string | undefined; expiresIn?: string | undefined; controller?: string | undefined; simulator?: string | undefined; repack?: string | undefined }): ExploreConfig {
let result = config;
if (overrides.flows !== undefined) {
// --flows FILE[,FILE]: run these e2e files as the capture, and nothing else (flows mode), whatever config.yaml says.
const tests = overrides.flows.map(entry => entry.trim()).filter(Boolean);
if (!tests.length) fail("--flows needs at least one e2e test file or glob", "--flows");
for (const path of tests) if (isAbsolute(path) || path.split(/[\\/]/).includes("..") || /[\u0000-\u001f]/.test(path)) fail(`--flows ${path} must be a path or glob inside the app directory`, "--flows");
if (result.mode === "agent") fail("--flows cannot be combined with agent mode", "--flows");
result = { ...result, mode: "flows", flows: { tests: tests.map(path => path.replace(/\\/g, "/")) } };
}
if (overrides.repack !== undefined) {
if (overrides.repack !== "eas" && overrides.repack !== "local") fail("--repack must be eas or local", "--repack");
result = { ...result, capture: { ...result.capture, repack: overrides.repack } };
@@ -632,9 +590,23 @@ function trustedAuthorList(value: unknown): string[] {
function reportConfig(value: unknown): ExploreConfig["report"] {
if (value === undefined) return undefined;
const report = record(value, "report");
exactKeys(report, ["preview"], "report");
if (report.preview === undefined) return {};
const preview = record(report.preview, "report.preview");
exactKeys(report, ["preview", "comment"], "report");
const comment = commentConfig(report.comment);
const preview = previewConfig(report.preview);
return { ...(preview ? { preview } : {}), ...(comment ? { comment } : {}) };
}
function commentConfig(value: unknown): NonNullable<ExploreConfig["report"]>["comment"] {
if (value === undefined) return undefined;
const comment = record(value, "report.comment");
exactKeys(comment, ["map"], "report.comment");
if (typeof comment.map !== "boolean") fail("report.comment.map must be true or false", "report.comment.map");
return { map: comment.map };
}
function previewConfig(value: unknown): NonNullable<ExploreConfig["report"]>["preview"] {
if (value === undefined) return undefined;
const preview = record(value, "report.preview");
exactKeys(preview, ["hosting", "expiresAfter", "owner", "project"], "report.preview");
const owner = optionalText(preview.owner, "report.preview.owner", 64);
if (owner !== undefined && !/^[a-z0-9][a-z0-9_-]*$/.test(owner)) {
@@ -644,12 +616,12 @@ function reportConfig(value: unknown): ExploreConfig["report"] {
if (project !== undefined && !/^[a-z0-9][a-z0-9-]*[a-z0-9]$/.test(project)) {
fail("report.preview.project must be a lowercase EAS project slug", "report.preview.project");
}
return { preview: {
return {
hosting: literal(preview.hosting, ["eas"] as const, "report.preview.hosting"),
expiresAfterDays: previewDays(preview.expiresAfter, "report.preview.expiresAfter"),
...(owner === undefined ? {} : { owner }),
...(project === undefined ? {} : { project }),
} };
};
}
/**
+2 -55
View File
@@ -62,37 +62,6 @@ export type BundleLaunchCapture = {
video?: LaunchVideo;
};
/** A frame a flow took with `app.screenshot(label)`; stored and verified like a launch frame. */
/** `contentSha256` hashes the pixels between the system bands, so frames that differ only by the clock fold together in the Viewer. */
export type FlowFrame = LaunchFrame & { contentSha256?: string };
/** A flows run that produced no flow records: the e2e worker failed before any test ran. */
export type FlowsFailure = { code: string; message: string };
export type FlowStatus = "passed" | "failed" | "skipped" | "flaky" | "timed-out" | "interrupted" | "blocked";
export type FlowStepStatus = "passed" | "failed" | "blocked" | "timed-out" | "cancelled";
export type BundleFlowStep = {
/** The e2e step API (`locator.tap`, `expect.toBeVisible`, `app.screenshot`, `agent.act`). */
api: string; label: string; status: FlowStepStatus; durationMs: number;
/** The key under `frames` of the screenshot this step took. */
frame?: string;
error?: { code: string; message: string };
/** The line of the test file the step was called from, when e2e recorded one. */
line?: number;
};
/**
* One flow (an e2e test) the capture ran on this revision: its outcome, its steps, and the frames it took. The frames
* are review surfaces of their own (`flow:<id>/<key>`), never attributed to a source route.
*/
export type BundleFlow = {
file: string; title: string; status: FlowStatus; durationMs: number;
error?: { code: string; message: string };
/** The line of the test file the test is declared on, when e2e recorded one. */
line?: number;
steps: BundleFlowStep[];
frames: Record<string, FlowFrame>;
};
/** The review surface id of a flow frame. */
export const flowSurfaceId = (flowId: string, key: string): string => `flow:${flowId}/${key}`;
export type LaunchFilmstrip = LaunchFrame & {
/** When each tile was on screen, in milliseconds from the launch transition (negative before it). */
frameTimesMs: number[];
@@ -115,10 +84,6 @@ export type CaptureBundle = {
outcomes: Record<string, CaptureOutcome>;
/** Launch evidence per appearance (`light`/`dark`), when the capture observed the app launch. */
launch?: Record<string, BundleLaunchCapture>;
/** The app's e2e flows run on this revision, by flow id, when the config names flows. */
flows?: Record<string, BundleFlow>;
/** Why the flows produced no records at all (the e2e worker did not run, or collected no test), when the config names flows. */
flowsFailure?: FlowsFailure;
/** How route frames were produced; absent in bundles from before `capture.reset` existed (root-link was not applied). */
procedure?: { reset: "root-link" | "none"; readinessSeconds?: number };
/** Committed destination goals used for this capture, including cached evidence. */
@@ -267,20 +232,6 @@ export type PublicLaunchEvidence = {
base?: PublicLaunchSide; head?: PublicLaunchSide;
visual?: PublicVisualVerdict;
};
/** A flow frame as published: the capture's record with its stored URL. */
export type PublicFlowFrame = Omit<FlowFrame, "path"> & { url: string };
export type PublicFlowSide = Omit<BundleFlow, "frames" | "file" | "title"> & { frames: Record<string, PublicFlowFrame> };
/**
* One flow across the two revisions: its outcome on each side and its frames in step order. A frame is compared when
* both sides took it; a side that failed before a frame simply lacks it.
*/
export type PublicFlowEvidence = {
/** The flow id (`<file>/<title>`, slugged); its frames are the surfaces `flow:<id>/<key>`. */
id: string; title: string; file: string;
base?: PublicFlowSide; head?: PublicFlowSide;
/** A secondary-appearance frame is `<key>@<scheme>` with its `colorScheme`, taken by a second run of the flow in that appearance. */
frames: Array<{ key: string; id: string; label: string; visual?: PublicVisualVerdict; colorScheme?: "light" | "dark" }>;
};
export type PublicReview = {
contract: "explore.review";
pullRequest: ReviewPresentation; mode: "all" | "changes"; createdAt: string;
@@ -310,10 +261,6 @@ export type PublicReview = {
navigation?: { base: NavigationGraph; head: NavigationGraph };
/** The app launch per appearance, kept apart from source routes: it has no route or navigation. */
launch?: PublicLaunchEvidence[];
/** The app's e2e flows the capture ran, kept apart from source routes like the launch. */
flows?: PublicFlowEvidence[];
/** A side whose flows did not run at all, with e2e's reason; the review still carries the other side's flows. */
flowsFailure?: { base?: FlowsFailure; head?: FlowsFailure };
surfaces: Array<{
id: string; status: "added" | "modified" | "removed" | "unchanged";
base: SourceRoute | null; head: SourceRoute | null;
@@ -336,7 +283,7 @@ export function validateCapturePlan(value: unknown): SourceCapturePlan {
const p = value as SourceCapturePlan;
if (!p || p.contract !== "explore.plan"
|| !/^[a-f0-9]{40}$/.test(p.baseSha) || !/^[a-f0-9]{40}$/.test(p.headSha)
|| !["all", "changes"].includes(p.mode) || (p.captureRoutes !== undefined && p.captureRoutes !== false)
|| !["all", "changes"].includes(p.mode)
|| !Array.isArray(p.surfaces) || p.surfaces.length > 5000) throw new Error("Invalid source capture plan");
const ids = new Set<string>();
for (const s of p.surfaces) {
@@ -367,7 +314,7 @@ export function validateCapturePlan(value: unknown): SourceCapturePlan {
const context = graph ? new Set(navigationCaptureContext(graph, seeds, routes)) : undefined;
for (const surface of p.surfaces) {
const entry = surface[`${side}Surface`];
const selected = Boolean(p.captureRoutes !== false && entry && entry.kind !== "redirect" && !excluded.has(surface.id)
const selected = Boolean(entry && entry.kind !== "redirect" && !excluded.has(surface.id)
&& (p.mode === "all" || (context ? context.has(surface.id) : surface.status !== "unchanged")));
if (surface[`${side}Capture`] !== selected) throw new Error("Capture selection disagrees with source and navigation context");
}
+1 -55
View File
@@ -1,5 +1,5 @@
import { projectReviewPresentation } from "./review.js";
import { LAUNCH_SURFACE_ID, flowSurfaceId, launchSurfaceId, type PublicFlowSide, type PublicLaunchSide, type PublicReview, type PublicVisualVerdict } from "./capture.js";
import { LAUNCH_SURFACE_ID, launchSurfaceId, type PublicLaunchSide, type PublicReview, type PublicVisualVerdict } from "./capture.js";
import { SOURCE_IMPACT_KINDS, validateSourceChangeSummary } from "./source-change.js";
import { validateNavigationGraph } from "./navigation-graph.js";
import { validateSourceRoute } from "./source-route.js";
@@ -127,59 +127,6 @@ function validLaunchSide(side: unknown): boolean {
&& /^[a-f0-9]{64}$/.test(video.sha256) && Number.isSafeInteger(video.bytes) && video.bytes > 0 && video.mimeType === "video/mp4"
&& (video.durationMs === undefined || (Number.isSafeInteger(video.durationMs) && video.durationMs >= 0))));
}
const FLOW_STATUSES = new Set(["passed", "failed", "skipped", "flaky", "timed-out", "interrupted", "blocked"]);
const STEP_STATUSES = new Set(["passed", "failed", "blocked", "timed-out", "cancelled"]);
const validFlowFrame = (value: unknown): boolean => Boolean(value) && typeof value === "object"
&& Object.keys(value as object).every(key => ["url", "sha256", "width", "height", "capturedAt", "contentSha256"].includes(key))
&& typeof (value as { url: unknown }).url === "string" && /^[a-f0-9]{64}$/.test(String((value as { sha256: unknown }).sha256))
&& ((value as { contentSha256?: unknown }).contentSha256 === undefined || /^[a-f0-9]{64}$/.test(String((value as { contentSha256: unknown }).contentSha256)))
&& Number.isSafeInteger((value as { width: unknown }).width) && Number.isSafeInteger((value as { height: unknown }).height)
&& Number.isFinite(Date.parse(String((value as { capturedAt: unknown }).capturedAt)));
function validFlowSide(value: unknown): value is PublicFlowSide {
if (!value || typeof value !== "object" || Object.keys(value).some(key => !["status", "durationMs", "error", "line", "steps", "frames"].includes(key))) return false;
const side = value as PublicFlowSide;
return FLOW_STATUSES.has(side.status) && Number.isSafeInteger(side.durationMs) && side.durationMs >= 0
&& (side.line === undefined || (Number.isSafeInteger(side.line) && side.line > 0))
&& (side.error === undefined || (typeof side.error?.code === "string" && typeof side.error.message === "string"))
&& Array.isArray(side.steps) && side.steps.length <= 10_000 && side.steps.every(step => step && typeof step === "object"
&& Object.keys(step).every(key => ["api", "label", "status", "durationMs", "frame", "error", "line"].includes(key))
&& (step.line === undefined || (Number.isSafeInteger(step.line) && step.line > 0))
&& typeof step.api === "string" && typeof step.label === "string" && STEP_STATUSES.has(step.status) && Number.isSafeInteger(step.durationMs)
&& (step.frame === undefined || (typeof step.frame === "string" && Object.hasOwn(side.frames, step.frame))))
&& side.frames !== null && typeof side.frames === "object" && Object.entries(side.frames).every(([key, frame]) => /^[a-z0-9-]+(?:@(?:light|dark))?$/.test(key) && validFlowFrame(frame));
}
/** Flow evidence is one entry per flow either side ran, with a verdict only for frames both sides took. */
const validFlowsFailure = (value: unknown): boolean => Boolean(value) && typeof value === "object" && Object.keys(value as object).every(key => key === "code" || key === "message")
&& typeof (value as { code: unknown }).code === "string" && typeof (value as { message: unknown }).message === "string" && (value as { message: string }).message.length <= 4_000;
function assertFlowEvidence(review: PublicReview, enforceComparisonEvidence: boolean): void {
if (review.flowsFailure !== undefined) {
const failure = review.flowsFailure;
if (!failure || typeof failure !== "object" || !Object.keys(failure).length || Object.keys(failure).some(key => key !== "base" && key !== "head")
|| Object.values(failure).some(value => !validFlowsFailure(value))) throw new Error("Public flows failure is invalid");
}
const flows = review.flows;
// Reports from before flow evidence carry a structural `flows` object (source-derived groups); it is not evidence.
if (flows === undefined || (flows !== null && typeof flows === "object" && !Array.isArray(flows))) return;
if (!Array.isArray(flows) || flows.length === 0 || flows.length > 1_000) throw new Error("Public flow evidence is invalid");
const ids = new Set<string>();
for (const entry of flows) {
if (!entry || typeof entry !== "object" || Object.keys(entry).some(key => !["id", "title", "file", "base", "head", "frames"].includes(key))
|| typeof entry.id !== "string" || !/^[a-z0-9-]+\/[a-z0-9-]+$/.test(entry.id) || ids.has(entry.id)
|| typeof entry.title !== "string" || typeof entry.file !== "string"
|| (!entry.base && !entry.head) || (entry.base !== undefined && !validFlowSide(entry.base)) || (entry.head !== undefined && !validFlowSide(entry.head))
|| !Array.isArray(entry.frames)) throw new Error("Public flow evidence is invalid");
ids.add(entry.id);
const keys = new Set<string>();
for (const frame of entry.frames) {
if (!frame || typeof frame !== "object" || Object.keys(frame).some(key => !["key", "id", "label", "visual", "colorScheme"].includes(key))
|| (frame.colorScheme !== undefined && (frame.colorScheme !== "light" && frame.colorScheme !== "dark" || !frame.key.endsWith(`@${frame.colorScheme}`)))
|| typeof frame.key !== "string" || keys.has(frame.key) || frame.id !== flowSurfaceId(entry.id, frame.key) || typeof frame.label !== "string"
|| (!entry.base?.frames[frame.key] && !entry.head?.frames[frame.key])) throw new Error("Public flow evidence is invalid");
keys.add(frame.key);
if (frame.visual !== undefined) assertVisualVerdict(frame.visual, enforceComparisonEvidence, Boolean(entry.base?.frames[frame.key] && entry.head?.frames[frame.key]));
}
}
}
/** Launch evidence is one entry per captured appearance, with a verdict only when both sides observed a splash. */
function assertLaunchEvidence(review: PublicReview, enforceComparisonEvidence: boolean): void {
const launch = review.launch;
@@ -386,7 +333,6 @@ function validatePublicReview(review: PublicReview, enforceComparisonEvidence: b
}
if (review.runtime.appIcon !== undefined) assertAppIcon(review.runtime.appIcon);
assertLaunchEvidence(review, enforceComparisonEvidence);
assertFlowEvidence(review, enforceComparisonEvidence);
const ids = new Set<string>();
const sideBuildIds = { base: new Set<string>(), head: new Set<string>() };
for (const surface of review.surfaces) {
+113 -26
View File
@@ -2,8 +2,8 @@ import type { PublicReview } from "../contracts/capture.js";
import type { RunTarget } from "../types.js";
import type { SimulatorRuntimeMetadata } from "../capture/run.js";
import { CI_COMMENT_MARKER } from "./pr-comment.js";
import { CHANGE_GROUPS, MAX_COMMENT_TARGETS, changeCountText, compareTargets, defaultTargetLabel, foldRecord, strongerGroup, historyLine, orderedRecords, readCommentRecords, recordLabel, recordLine, recordSummary, recordTarget,
type ChangeGroup, type CommentTarget, type CommentRecords, type HistoryEntry, type PlatformRecord } from "./pr-comment-record.js";
import { CHANGE_GROUPS, MAX_COMMENT_TARGETS, MAX_NAVIGATION_EDGES, MAX_NAVIGATION_NODES, changeCountText, compareTargets, defaultTargetLabel, foldRecord, strongerGroup, historyLine, orderedRecords, readCommentRecords, recordLabel, recordLine, recordSummary, recordTarget,
type ChangeGroup, type CommentNavigation, type CommentTarget, type CommentRecords, type HistoryEntry, type NavigationGroup, type NavigationKind, type PlatformRecord } from "./pr-comment-record.js";
import { isAccessibilityOnlyChange } from "../contracts/review-validation.js";
import type { PublicCaptureHealth, PublicEvidenceSummary } from "../review/evidence-assessment.js";
import type { ReviewPresentation } from "../contracts/review.js";
@@ -20,7 +20,7 @@ export type PublicCommentState = {
phase: PublicCommentPhase;
pullRequest: ReviewPresentation;
mode: "all" | "changes";
executionMode: "deterministic" | "agent" | "flows";
executionMode: "deterministic" | "agent";
/** Repository-relative path of the reviewed configuration file. */
configPath: string;
links: ViewerLinks;
@@ -57,6 +57,8 @@ export type PublicCommentState = {
artifactOnly?: boolean;
/** The PR moved while this run worked; the comment keeps its report under previous runs. */
superseded?: boolean;
/** report.comment.map: draw the map of the changed screens. */
map?: true;
};
type ReviewGroup = ChangeGroup;
@@ -194,23 +196,6 @@ function previewExpiry(expiresAt: number): string {
* (source-unchanged screens captured in another runtime state) and app-wide source changes that
* left some screens without a visible difference.
*/
/** "Flow Send money: passed, 4 frames, 1 changed" — one line per e2e flow the capture ran. */
function flowLines(review: PublicReview): string[] {
const notRun = ((["head", "base"] as const).filter(side => review.flowsFailure?.[side]))
.map(side => `Flows did not run on ${side}: ${plainText(review.flowsFailure![side]!.message, 200)}.`);
return [...notRun, ...(Array.isArray(review.flows) ? review.flows : []).map(entry => {
const side = (name: "base" | "head") => {
const flow = entry[name];
if (!flow) return `not run on ${name}`;
const failed = flow.steps.find(step => step.status !== "passed");
return `${flow.status} on ${name}${failed && flow.status !== "passed" ? ` at step ${flow.steps.indexOf(failed) + 1} (${plainText(failed.api, 40)} ${plainText(failed.label, 80)})` : ""}`;
};
const compared = entry.frames.filter(frame => frame.visual);
const changed = compared.filter(frame => frame.visual?.verdict === "modified").length;
const frames = entry.frames.length ? `${plural(entry.frames.length, "frame")}${compared.length ? `, ${changed ? `${changed} changed` : "none changed"}` : ""}` : "no frames";
return `Flow ${plainText(entry.title, 80)}: ${side("head")}; ${frames}${entry.base && entry.head && entry.base.status === "passed" && entry.head.status !== "passed" ? ` (was ${side("base")})` : ""}.`;
})];
}
/** "Launch: splash unchanged for 3.1 s" — the app launch per appearance, kept apart from the screen rows. */
function launchLine(review: PublicReview): string | undefined {
const launch = review.launch ?? [];
@@ -242,7 +227,6 @@ function contextLines(review: PublicReview): string[] {
const lines: string[] = [];
const launch = launchLine(review);
if (launch) lines.push(launch);
lines.push(...flowLines(review));
if (variants > 0) lines.push(`${plural(variants, "screen")} ${variants === 1 ? "differs" : "differ"} only in runtime state (screen variants); no source change reaches ${variants === 1 ? "it" : "them"}.`);
if (appWide.length > 0) {
const named = files.length ? ` (${files.slice(0, 5).map(path => `\`${plainText(path, 120).replace(/`/g, "")}\``).join(", ")}${files.length > 5 ? ", …" : ""})` : "";
@@ -328,6 +312,8 @@ export function platformRecordOf(state: PublicCommentState, target?: CommentTarg
const scheme = schemeOf(surface.id);
record.changes.push({ id: surface.id, route: routeOf(surface), group, description: descriptionOf(surface, group), ...(scheme ? { scheme } : {}) });
}
const navigation = state.map ? navigationOf(state.review, new Map(record.changes.map(change => [change.id, change.group]))) : undefined;
if (navigation) record.navigation = navigation;
const notCompared = state.review.surfaces.filter(notComparedChange).length;
if (notCompared) record.notCompared = notCompared;
record.context = contextLines(state.review).filter(line => line.length);
@@ -354,6 +340,104 @@ export function platformRecordOf(state: PublicCommentState, target?: CommentTarg
return record;
}
const NAVIGATION_GROUPS: NavigationGroup[] = ["added", "removed", "modified"];
const NAVIGATION_KINDS: NavigationKind[] = ["push", "replace", "navigate", "dismissTo", "redirect"];
/** "/p/[d]" for the route file app/(tabs)/(patterns)/p/[d].tsx: the route without its groups, which a dynamic route's variants share. */
function routePattern(route: NonNullable<Surface["head"]>): string {
const path = `/${route.logicalPath.replace(/^\/+/, "")}`.split("/").filter(segment => !/^\(.*\)$/.test(segment)).join("/");
return plainText(path.replace(/\/index$/, ""), MAX_ROUTE_LENGTH) || "/";
}
/**
* The map the comment draws: every route added, removed or changed visually (a screen whose source changed but looks
* the same is not one), the routes one step before them, and the transitions among those. A route's appearances and
* variants are one node. Switching tabs reaches every tab from every other, so tab transitions are not edges: the
* routes a tab switch shows are grouped instead. Removed routes and the transitions into them come from the base.
*/
function navigationOf(review: PublicReview, groups: Map<string, ChangeGroup>): CommentNavigation | undefined {
if (!review.navigation) return undefined;
const keyOf = new Map<string, string>();
const groupOf = new Map<string, NavigationGroup>();
for (const surface of review.surfaces) {
const route = surface.head ?? surface.base;
if (!route || route.kind === "redirect") continue;
const key = routePattern(route);
keyOf.set(surface.id.replace(/@(light|dark)$/, ""), key);
const group = groups.get(surface.id);
if (group !== "added" && group !== "removed" && group !== "modified") continue;
const current = groupOf.get(key);
if (!current || NAVIGATION_GROUPS.indexOf(group) < NAVIGATION_GROUPS.indexOf(current)) groupOf.set(key, group);
}
if (!groupOf.size || groupOf.size > MAX_NAVIGATION_NODES) return undefined;
const tabs = new Set<string>();
const links = new Map<string, { from: string; to: string; kinds: Set<NavigationKind>; base: boolean }>();
const add = (edge: NonNullable<PublicReview["navigation"]>["head"]["edges"][number], base: boolean) => {
const from = keyOf.get(edge.from), to = keyOf.get(edge.to);
if (!from || !to || from === to) return;
if (edge.kind === "tab") { tabs.add(to); return; }
const link = links.get(`${from}\n${to}`) ?? { from, to, kinds: new Set(), base };
link.kinds.add(edge.kind);
links.set(`${from}\n${to}`, link);
};
for (const edge of review.navigation.head.edges) add(edge, false);
for (const edge of review.navigation.base.edges) if (groupOf.get(keyOf.get(edge.to) ?? "") === "removed") add(edge, true);
// The routes that lead to the most changed ones first, while the map has room.
const leads = new Map<string, number>();
for (const link of links.values()) if (groupOf.has(link.to) && !groupOf.has(link.from)) leads.set(link.from, (leads.get(link.from) ?? 0) + 1);
const before = [...leads].sort(([a, m], [b, n]) => n - m || (a < b ? -1 : 1)).slice(0, MAX_NAVIGATION_NODES - groupOf.size).map(([key]) => key);
const keys = [...groupOf.keys(), ...before].sort();
const index = new Map(keys.map((key, position) => [key, position]));
const edges = [...links.values()].filter(link => index.has(link.from) && index.has(link.to))
.sort((a, b) => Number(groupOf.has(b.to)) - Number(groupOf.has(a.to)) || index.get(a.from)! - index.get(b.from)! || index.get(a.to)! - index.get(b.to)!)
.slice(0, MAX_NAVIGATION_EDGES)
.sort((a, b) => index.get(a.from)! - index.get(b.from)! || index.get(a.to)! - index.get(b.to)!)
.map(link => ({ from: index.get(link.from)!, to: index.get(link.to)!, kinds: NAVIGATION_KINDS.filter(kind => link.kinds.has(kind)), ...(link.base ? { base: true as const } : {}) }));
if (!edges.length) return undefined;
return { nodes: keys.map(key => ({ route: key, ...(groupOf.has(key) ? { group: groupOf.get(key)! } : {}), ...(tabs.has(key) ? { tab: true as const } : {}) })), edges };
}
/** A route as a quoted Mermaid label, with Mermaid's entity codes for what would end the label, the line or the fence. */
function mermaidLabel(route: string): string {
return `"${plainText(route, MAX_ROUTE_LENGTH).replace(/#/g, "#35;").replace(/"/g, "#quot;").replace(/</g, "#lt;").replace(/>/g, "#gt;").replace(/`/g, "#96;")}"`;
}
/** Outlines, not fills: GitHub draws Mermaid in the reader's theme, and a fixed fill is wrong in one of them. */
const MAP_CLASSES: Record<NavigationGroup, string> = {
added: "stroke:#1a7f37,stroke-width:3px",
modified: "stroke:#bc4c00,stroke-width:3px",
removed: "stroke:#cf222e,stroke-width:2px,stroke-dasharray:5 4",
};
function mermaidMap(navigation: CommentNavigation): string[] {
const node = (index: number) => `n${index}[${mermaidLabel(navigation.nodes[index]!.route)}]`;
const tabs = navigation.nodes.flatMap((entry, index) => entry.tab ? [index] : []);
const lines = ["```mermaid", "flowchart LR"];
if (tabs.length) lines.push(` subgraph tabs["Tabs"]`, ...tabs.map(index => ` ${node(index)}`), " end");
lines.push(...navigation.nodes.flatMap((entry, index) => entry.tab ? [] : [` ${node(index)}`]));
lines.push(...navigation.edges.map(edge => ` n${edge.from} ${edge.base ? "-.->" : "-->"}|${edge.kinds.join(", ")}| n${edge.to}`));
for (const group of ["added", "modified", "removed"] as const) {
const members = navigation.nodes.flatMap((entry, index) => entry.group === group ? [`n${index}`] : []);
if (members.length) lines.push(` classDef ${group} ${MAP_CLASSES[group]}`, ` class ${members.join(",")} ${group}`);
}
return [...lines, "```"];
}
/** One collapsed map per distinct navigation: targets with the same routes share one, named when the targets' maps differ. */
function mapSection(ready: PlatformRecord[]): string[] {
const maps = new Map<string, { navigation: CommentNavigation; records: PlatformRecord[] }>();
for (const record of ready) {
if (!record.navigation) continue;
const key = JSON.stringify(record.navigation);
maps.set(key, { navigation: record.navigation, records: [...(maps.get(key)?.records ?? []), record] });
}
return [...maps.values()].flatMap(({ navigation, records }) => {
const named = maps.size > 1 || records.length < ready.length ? `${records.map(labelOf).join(" · ")} · ` : "";
return details(`${named}Map (${plural(navigation.nodes.length, "screen")})`, ["", ...mermaidMap(navigation), "",
"Outlined: green added, orange changed, red dashed removed; the others lead to them. Tabs groups the screens a tab switch shows.", ""]);
});
}
const commitLink = (repository: string, sha: string) => link(inlineText(sha.slice(0, 8), 8), `https://github.com/${repository.split("/").map(encodeURIComponent).join("/")}/commit/${encodeURIComponent(sha)}`);
function surfaceLink(report: string, id: string): string | undefined {
@@ -449,7 +533,7 @@ function renderChangeRow(row: ChangeRow, records: PlatformRecord[]): string {
return `- ${route} — ${inlineText(row.description, MAX_DESCRIPTION_LENGTH)}${where.length ? ` · ${where.join(" · ")}` : ""}`;
}
function changesSection(records: PlatformRecord[], rowCap: number): string[] {
function changesSection(records: PlatformRecord[], rowCap: number, withMap: boolean): string[] {
const ready = records.filter(record => record.phase === "ready");
if (!ready.length) return [];
const groups = changeRows(ready);
@@ -472,6 +556,7 @@ function changesSection(records: PlatformRecord[], rowCap: number): string[] {
content.push("");
lines.push(...details(`${GROUP_LABEL[group]} (${rows.length})`, content));
}
if (withMap) lines.push(...mapSection(ready));
const seen = new Set<string>();
for (const record of ready) for (const line of record.context ?? []) {
if (seen.has(line)) continue;
@@ -612,13 +697,13 @@ export function renderCommentRecords(records: CommentRecords, existing?: string,
...historySection("", records.history)].join("\n");
const first = current[0]!;
const repository = repositoryOf(first.links.run);
const render = (rowCap: number): string => {
const render = (rowCap: number, withMap: boolean): string => {
const lines: string[] = [...hidden, heading(current), "",
`<sub>base ${commitLink(repository, first.baseSha)} → ${commitLink(repository, first.headSha)}</sub>`, ""];
if (first.superseded) lines.push(SUPERSEDED_NOTE, "");
lines.push(`| | Device | Result | Report |`, `|---|---|---|---|`,
...current.map(record => `| ${labelOf(record)} | ${deviceCell(record)} | ${resultCell(record)} | ${reportCell(record)} |`), "");
lines.push(...changesSection(current, rowCap));
lines.push(...changesSection(current, rowCap, withMap));
lines.push(...validationSection(current));
lines.push(...historySection(repository, records.history));
const expiries = current.filter(record => record.phase === "ready" && record.links.expiresAt !== undefined).map(record => record.links.expiresAt);
@@ -631,9 +716,11 @@ export function renderCommentRecords(records: CommentRecords, existing?: string,
lines.push(footer.join(" · "));
return lines.join("\n");
};
// The map goes first when the body is over budget, then the change lists shrink.
let rowCap = MAX_ROWS_PER_GROUP;
let body = render(rowCap);
while (body.length > budget && rowCap > 1) { rowCap = Math.max(1, Math.floor(rowCap / 2)); body = render(rowCap); }
let body = render(rowCap, true);
if (body.length > budget) body = render(rowCap, false);
while (body.length > budget && rowCap > 1) { rowCap = Math.max(1, Math.floor(rowCap / 2)); body = render(rowCap, false); }
return body;
}
+39
View File
@@ -56,6 +56,23 @@ export function changeCountText(groups: readonly ChangeGroup[]): string {
return [visual ? `${visual} visual change${visual === 1 ? "" : "s"}` : undefined, `${accessibility} accessibility only`].filter(Boolean).join(" · ");
}
export type NavigationGroup = "added" | "modified" | "removed";
export type NavigationKind = "push" | "replace" | "navigate" | "redirect" | "tab" | "dismissTo";
const NAVIGATION_GROUPS: NavigationGroup[] = ["added", "modified", "removed"];
const NAVIGATION_KINDS: NavigationKind[] = ["push", "replace", "navigate", "redirect", "tab", "dismissTo"];
export const MAX_NAVIGATION_NODES = 30;
export const MAX_NAVIGATION_EDGES = 80;
/**
* The comment's map: one node per route that was added, removed or changed visually, and per route one step before
* one of them; edges index `nodes`. `tab` marks a route a tab switch shows, `base` an edge into a removed route, which
* only the base revision's navigation has.
*/
export type CommentNavigation = {
nodes: { route: string; group?: NavigationGroup; tab?: true }[];
edges: { from: number; to: number; kinds: NavigationKind[]; base?: true }[];
};
export type SideHealth = { planned: number; captured: number; verified: number; unverified: number; unavailable: number };
export type PlatformRecord = {
@@ -92,6 +109,7 @@ export type PlatformRecord = {
notCompared?: number;
/** Differences stated once rather than per screen (variants, app-wide source changes). */
context?: string[];
navigation?: CommentNavigation;
diagnostics?: { side?: "base" | "head"; route: string; code: string; message: string; nextAction: string }[];
diagnosticCount?: number;
failure?: { step: string; message: string };
@@ -236,6 +254,8 @@ export function parsePlatformRecord(value: unknown): PlatformRecord | undefined
? [{ id: entry.id, route: entry.route, group: entry.group as ChangeGroup, description: entry.description, ...(isString(entry.scheme, 20) ? { scheme: entry.scheme } : {}) }] : []);
if (changes.length <= 2000) record.changes = changes;
}
const navigation = parseNavigation(value.navigation);
if (navigation) record.navigation = navigation;
if (Array.isArray(value.context)) record.context = value.context.filter((entry): entry is string => isString(entry, 2000)).slice(0, 10);
if (Array.isArray(value.diagnostics)) {
record.diagnostics = value.diagnostics.flatMap((entry): NonNullable<PlatformRecord["diagnostics"]> => isRecord(entry) && isString(entry.route, 2000) && isString(entry.code, 200)
@@ -249,6 +269,25 @@ export function parsePlatformRecord(value: unknown): PlatformRecord | undefined
return record;
}
function parseNavigation(value: unknown): CommentNavigation | undefined {
if (!isRecord(value) || !Array.isArray(value.nodes) || !Array.isArray(value.edges) || value.nodes.length > MAX_NAVIGATION_NODES
|| value.edges.length > MAX_NAVIGATION_EDGES) return undefined;
const nodes: CommentNavigation["nodes"] = [];
for (const node of value.nodes) {
if (!isRecord(node) || !isString(node.route, 200) || !optional(node.group, (group): group is NavigationGroup => NAVIGATION_GROUPS.includes(group as NavigationGroup))
|| !(node.tab === undefined || node.tab === true)) return undefined;
nodes.push({ route: node.route, ...(node.group ? { group: node.group } : {}), ...(node.tab ? { tab: true } : {}) });
}
const edges: CommentNavigation["edges"] = [];
const isNode = (index: unknown): index is number => isCount(index) && index < nodes.length;
for (const edge of value.edges) {
if (!isRecord(edge) || !isNode(edge.from) || !isNode(edge.to) || !Array.isArray(edge.kinds) || !edge.kinds.length
|| !edge.kinds.every(kind => NAVIGATION_KINDS.includes(kind as NavigationKind)) || !(edge.base === undefined || edge.base === true)) return undefined;
edges.push({ from: edge.from, to: edge.to, kinds: [...new Set(edge.kinds as NavigationKind[])], ...(edge.base ? { base: true } : {}) });
}
return nodes.length && edges.length ? { nodes, edges } : undefined;
}
export function parseHistory(value: unknown): HistoryEntry[] {
if (!Array.isArray(value)) return [];
const entries: HistoryEntry[] = [];
+2 -47
View File
@@ -4,7 +4,7 @@ import { createHash } from "node:crypto";
import { lstat, readFile, realpath } from "node:fs/promises";
import { isAbsolute, relative, resolve, sep } from "node:path";
import { assertDecodedPng } from "../shared/png-evidence.js";
import { assertAgentAcceptance, validateCapturePlan, type AppIconImage, type BundleLaunchCapture, type CaptureBundle, type CaptureOutcome, type CapturedImage, type LaunchFilmstrip, type LaunchFrame, type PublicFlowEvidence, type PublicFlowSide, type PublicLaunchSide, type PublicReview, flowSurfaceId, homeIndicatorBandPercent, launchSurfaceId, statusBarBandPercent } from "../contracts/capture.js";
import { assertAgentAcceptance, validateCapturePlan, type AppIconImage, type BundleLaunchCapture, type CaptureBundle, type CaptureOutcome, type CapturedImage, type LaunchFilmstrip, type LaunchFrame, type PublicLaunchSide, type PublicReview, homeIndicatorBandPercent, launchSurfaceId, statusBarBandPercent } from "../contracts/capture.js";
import { COLOR_SCHEMES } from "../capture/appearance.js";
import { launchDirectory } from "../capture/launch-capture.js";
import { APP_ICON_FILE, APP_ICON_MAX_SIZE } from "../capture/app-icon.js";
@@ -235,21 +235,6 @@ async function uploadSide(store: ScreenshotStore, directory: string, expectedCom
launch[scheme] = { ...rest, ...(splash ? { splash: await frame(splash, "splash") } : {}), settled: await frame(settled, "settled"),
...(publicFilmstrip ? { filmstrip: publicFilmstrip } : {}), ...(publicVideo ? { video: publicVideo } : {}) };
}
const flows: Record<string, PublicFlowSide> = {};
for (const [flowId, flow] of Object.entries(bundle.flows ?? {})) {
if (!/^[a-z0-9-]+\/[a-z0-9-]+$/.test(flowId)) throw new Error("Capture bundle flow id is invalid");
const frames: PublicFlowSide["frames"] = {};
for (const [key, value] of Object.entries(flow.frames)) {
if (!/^[a-z0-9-]+(?:@(?:light|dark))?$/.test(key)) throw new Error("Capture bundle flow frame key is invalid");
const bytes = await evidenceFile(value.path); assertDecodedPng(bytes, "Flow frame");
if (value.sha256 !== createHash("sha256").update(bytes).digest("hex") || value.width !== bytes.readUInt32BE(16) || value.height !== bytes.readUInt32BE(20)
|| !Number.isFinite(Date.parse(value.capturedAt)) || (value.contentSha256 !== undefined && !SHA256.test(value.contentSha256))) throw new Error("Flow frame provenance mismatch");
const { path: _, ...metadata } = value;
frames[key] = { ...metadata, url: await store.put(`${prefix}/flow-${flowId.replace("/", "-")}-${key}.png`, bytes, "image/png") };
}
const { frames: _frames, file: _file, title: _title, ...rest } = flow;
flows[flowId] = { ...rest, frames };
}
let appIcon: AppIconImage | undefined;
if (bundle.appIcon) {
const iconPath = resolve(directory, bundle.appIcon.path);
@@ -262,32 +247,7 @@ async function uploadSide(store: ScreenshotStore, directory: string, expectedCom
const { path: _, ...metadata } = bundle.appIcon;
appIcon = { ...metadata, url: await store.put(`${prefix}/${APP_ICON_FILE}`, bytes, "image/png") };
}
return { bundle, images, appIcon, launch, flows, ...(bundle.flowsFailure ? { flowsFailure: bundle.flowsFailure } : {}) };
}
/** Every flow either side ran, head's order first; a frame row for each key a side took, in head's step order. */
function publicFlows(base: { bundle: CaptureBundle; flows: Record<string, PublicFlowSide> }, head: { bundle: CaptureBundle; flows: Record<string, PublicFlowSide> },
assessments: CaptureReviewOptions["assessments"]): PublicFlowEvidence[] {
const ids = [...new Set([...Object.keys(head.flows), ...Object.keys(base.flows)])];
const schemes = bundleColorSchemes(head.bundle);
return ids.map(id => {
const record = head.bundle.flows?.[id] ?? base.bundle.flows?.[id];
const keys = [...new Set([...(head.bundle.flows?.[id]?.steps ?? []).flatMap(step => step.frame ? [step.frame] : []),
...(base.bundle.flows?.[id]?.steps ?? []).flatMap(step => step.frame ? [step.frame] : [])])];
// A checkpoint frame is named by its `app.screenshot(label)`; a per-step frame by its step number and what the step did.
const labelOf = (key: string) => {
const steps = (head.bundle.flows?.[id] ?? base.bundle.flows?.[id])?.steps ?? [];
const index = steps.findIndex(step => step.frame === key);
const step = steps[index];
if (!step) return key;
return step.api === "app.screenshot" ? step.label || key : `${index + 1}. ${step.label || step.api}`.slice(0, 80);
};
return { id, title: record?.title ?? id, file: record?.file ?? "",
...(base.flows[id] ? { base: base.flows[id] } : {}), ...(head.flows[id] ? { head: head.flows[id] } : {}),
frames: keys.flatMap(key => [key, ...schemes.slice(1).map(scheme => `${key}@${scheme}`)]
.filter(frameKey => frameKey === key || head.flows[id]?.frames[frameKey] || base.flows[id]?.frames[frameKey])
.map(frameKey => { const surface = flowSurfaceId(id, frameKey); const visual = assessments?.[surface]?.visual; const scheme = frameKey.slice(key.length + 1);
return { key: frameKey, id: surface, label: labelOf(key), ...(visual ? { visual } : {}), ...(scheme ? { colorScheme: scheme as "light" | "dark" } : {}) }; })) };
});
return { bundle, images, appIcon, launch };
}
export type CaptureReviewOptions = {
plan: unknown; pullRequest: unknown; baseDirectory: string; headDirectory: string;
@@ -359,8 +319,6 @@ async function constructCaptureReview(options: CaptureReviewOptions, store: Scre
...(base.launch[scheme] ? { base: base.launch[scheme]! } : {}), ...(head.launch[scheme] ? { head: head.launch[scheme]! } : {}),
...(assessment?.visual ? { visual: assessment.visual } : {}) };
}) } : {}),
...(Object.keys(head.flows).length || Object.keys(base.flows).length ? { flows: publicFlows(base, head, options.assessments) } : {}),
...(base.flowsFailure || head.flowsFailure ? { flowsFailure: { ...(base.flowsFailure ? { base: base.flowsFailure } : {}), ...(head.flowsFailure ? { head: head.flowsFailure } : {}) } } : {}),
surfaces: plan.surfaces.flatMap(s => appearancePairs(s.id, colorSchemes, baseColorSchemes).map(({ id, scheme, baseId }) => {
const assessment = options.assessments?.[id];
// The bundle records one outcome per route; a secondary appearance's surface carries that outcome only when the
@@ -412,9 +370,6 @@ export async function prepareCaptureReview(options: CaptureReviewOptions): Promi
for (const record of Object.values(bundle.launch ?? {})) {
for (const file of [record.splash, record.settled, record.video]) if (file) assets.set(file.sha256, { sha256: file.sha256, path: resolve(directory, file.path) });
}
for (const flow of Object.values(bundle.flows ?? {})) {
for (const frame of Object.values(flow.frames)) assets.set(frame.sha256, { sha256: frame.sha256, path: resolve(directory, frame.path) });
}
}
// Only the head icon names the app in the review header.
const icon = review.runtime.appIcon && (await readCaptureBundle(options.headDirectory)).appIcon;
+1 -25
View File
@@ -1,6 +1,6 @@
import { unattributedIssue } from "../capture/health.js";
import { appearancePairs, bundleColorSchemes } from "../capture/appearance.js";
import { flowSurfaceId, homeIndicatorBandPercent, launchSurfaceId, statusBarBandPercent } from "../contracts/capture.js";
import { homeIndicatorBandPercent, launchSurfaceId, statusBarBandPercent } from "../contracts/capture.js";
import { readFileSync, statSync } from "node:fs";
import { stat } from "node:fs/promises";
import { isAbsolute, resolve } from "node:path";
@@ -556,30 +556,6 @@ export async function assessPublicEvidence(options: {
}
}
// Flow frames compare like screens when both revisions took the same frame of the same flow.
for (const [flowId, headFlow] of Object.entries(options.head.bundle.flows ?? {})) {
const baseFlow = options.base.bundle.flows?.[flowId];
if (!baseFlow || !visualAvailable) continue;
for (const [key, headFrame] of Object.entries(headFlow.frames)) {
const baseFrame = baseFlow.frames[key];
if (!baseFrame || now() > deadline) continue;
const id = flowSurfaceId(flowId, key);
const basePath = localEvidencePath(options.base, baseFrame.path); const headPath = localEvidencePath(options.head, headFrame.path);
if (!basePath || !headPath) continue;
try {
const { measurement, ignoredTop, ignoredBottom } = ignoreSystemBands(await measure(basePath, headPath), { top: statusBarBandPercent(options.platform), bottom: homeIndicatorBandPercent(options.platform) });
const visual = visualVerdict(assessVisualMeasurements({ baselineSamples: 1, currentSamples: 1, requiredSamples: 1,
baselineWithin: [], currentWithin: [], crossBuild: [measurement], representative: measurement }), threshold);
if (ignoredTop > 0) visual.ignoredStatusBarRegions = ignoredTop;
if (ignoredBottom > 0) visual.ignoredHomeIndicatorRegions = ignoredBottom;
surfaces[id] = { visual };
} catch (error) {
comparisonError(id, error, { code: "VISUAL_COMPARISON_FAILED", stage: "compare",
message: "Flow frame comparison failed.", nextAction: "Check the flow frames and the agent-device comparison diagnostics, then rerun comparison.", retryable: true });
}
}
}
return {
surfaces,
summary: {
+1 -1
View File
@@ -3,4 +3,4 @@
* controller (`--package-version`), the daemon health check, and the screenshot diff tool must
* all be this version; each caller checks it by exact equality.
*/
export const AGENT_DEVICE_VERSION = "0.21.28";
export const AGENT_DEVICE_VERSION = "0.21.29-nightly.20261018.74";
+1 -1
View File
@@ -21,7 +21,7 @@ export type ControllerName = "agent-device" | "argent";
/** Each controller's npm release, the file Explore runs from it, and the integrity npm publishes for it. */
export const CONTROLLER_PACKAGES: Record<ControllerName, { name: string; version: string; bin: string; integrity: string }> = {
"agent-device": { name: "agent-device", version: AGENT_DEVICE_VERSION, bin: "bin/agent-device.mjs",
integrity: "sha512-uGEENVhPzSpIACrVlt16O1mloODWJyAemTCT0boDb4L006JXN2rG747u1TRoQJudOpdP/Pm2urxNRHeECLMLfg==" },
integrity: "sha512-7+ajWLr0J+8iLZ9q11ERbj6U14mC20umBK5BQQdw5aERA79yeXc3Ze6KmtvnILnWjEtoVkYQsXQasL8RL6Uatw==" },
argent: { name: "@swmansion/argent", version: ARGENT_VERSION, bin: "dist/cli.js",
integrity: "sha512-XXWlWZJlHKqnAvNx3RDhuiVFQOPqh5EDB76+mFAyqC2mutC6irzw03+M/6S/WQ+Dzz2IYOkEfOzQnOOdhrGgJg==" },
};
+17 -15
View File
@@ -1,6 +1,5 @@
import { createRequire } from "node:module";
import { createHash } from "node:crypto";
import { Buffer } from "node:buffer";
import { createRequire } from "node:module";
import { inflateSync } from "node:zlib";
import { STATUS_BAR_BAND_PERCENT } from "../contracts/capture.js";
@@ -9,6 +8,22 @@ export { STATUS_BAR_BAND_PERCENT };
/** Decoded RGBA pixels of one frame, as pngjs returns them (four bytes per pixel, row by row). */
export type DecodedFrame = { width: number; height: number; data: Buffer };
/**
* Whether a screenshot is a single flat colour: a capture-protected screen (black on Android), or a display that is lit
* but not drawn (an iPhone Duo's inner panel after its first fold on EAS). Every 97th pixel is enough to tell.
*/
export function solidColour(png: Buffer): boolean {
let frame: DecodedFrame;
try { frame = createRequire(import.meta.url.replace(/\?.*$/, ""))("pngjs").PNG.sync.read(png, { checkCRC: false }) as DecodedFrame; }
catch { return false; }
const { data } = frame;
if (data.length < 4) return false;
for (let offset = 0; offset + 3 < data.length; offset += 4 * 97) {
if (data[offset] !== data[0] || data[offset + 1] !== data[1] || data[offset + 2] !== data[2]) return false;
}
return true;
}
/**
* Whether a coordinate tap at normalized height `y` would act on a changed frame. Differences inside
* the status-bar band are ignored only when the tap lands below the band: a tap inside it acts on
@@ -95,16 +110,3 @@ export function assertDecodedPng(contents: Buffer, label: string): void {
if (decoded[row * (rowBytes + 1)]! > 4) throw new Error(`${label} has an invalid PNG row filter`);
}
}
/**
* SHA-256 of a frame's pixels between the system bands (status bar above, home indicator below), so two frames that
* differ only by the clock or the indicator's inversion hash alike. Decodes with pngjs; `bands` are percentages of the height.
*/
export function contentSha256(png: Buffer, bands: { top: number; bottom: number }): string {
const { PNG } = createRequire(import.meta.url)("pngjs") as { PNG: { sync: { read(buffer: Buffer): DecodedFrame } } };
const frame = PNG.sync.read(png);
const rowBytes = frame.width * 4;
const first = Math.min(frame.height, Math.floor(frame.height * bands.top / 100));
const last = Math.max(first, frame.height - Math.ceil(frame.height * bands.bottom / 100));
return createHash("sha256").update(`${frame.width}x${last - first}:`).update(frame.data.subarray(first * rowBytes, last * rowBytes)).digest("hex");
}
+3 -8
View File
@@ -21,8 +21,6 @@ export type CapturePlanOptions = DiscoverRouteOptions & {
changedFiles: SourceChange[];
externalChanges?: SourceChange[];
mode?: CaptureMode;
/** False when the capture runs flows only: every route stays in the inventory and the navigation context, none is captured. */
captureRoutes?: boolean;
/** Routes named in exploration.exclude: kept in the map and its navigation context, never captured. */
exclude?: string[];
navigation?: Pick<DiscoverRouteOptions, "provider" | "entry">;
@@ -33,8 +31,6 @@ export type SourceCapturePlan = {
baseSha: string;
headSha: string;
mode: CaptureMode;
/** Present, as false, when the plan captures no route (flows mode): the inventory and navigation are kept, no surface is captured. */
captureRoutes?: false;
conservative: boolean;
unresolved: string[];
diagnostics: { base: string[]; head: string[] };
@@ -163,12 +159,11 @@ export function createSourceCapturePlan(options: CapturePlanOptions): SourceCapt
const seeds = definitions.filter(route => route.status !== "unchanged").map(route => route.id);
const selected = { base: new Set(navigationCaptureContext(navigation.base, seeds, baseRoutes)), head: new Set(navigationCaptureContext(navigation.head, seeds, headRoutes)) };
const excluded = excludedSurfaceIds(definitions, options.exclude ?? []);
const captureRoutes = options.captureRoutes ?? true;
const surfaces = definitions.map(route => ({ ...route,
baseCapture: Boolean(captureRoutes && route.baseSurface && route.baseSurface.kind !== "redirect" && !excluded.includes(route.id) && (mode === "all" || selected.base.has(route.id))),
headCapture: Boolean(captureRoutes && route.headSurface && route.headSurface.kind !== "redirect" && !excluded.includes(route.id) && (mode === "all" || selected.head.has(route.id))),
baseCapture: Boolean(route.baseSurface && route.baseSurface.kind !== "redirect" && !excluded.includes(route.id) && (mode === "all" || selected.base.has(route.id))),
headCapture: Boolean(route.headSurface && route.headSurface.kind !== "redirect" && !excluded.includes(route.id) && (mode === "all" || selected.head.has(route.id))),
}));
return { contract: "explore.plan", baseSha: options.baseSha, headSha: options.headSha, mode, ...(captureRoutes ? {} : { captureRoutes: false as const }), conservative, unresolved, surfaces, navigation,
return { contract: "explore.plan", baseSha: options.baseSha, headSha: options.headSha, mode, conservative, unresolved, surfaces, navigation,
diagnostics: { base: baseInventory.diagnostics, head: headInventory.diagnostics },
inventorySurfaceIds: surfaces.map(route => route.id), baseCaptureSurfaceIds: surfaces.filter(route => route.baseCapture).map(route => route.id), headCaptureSurfaceIds: surfaces.filter(route => route.headCapture).map(route => route.id),
...(excluded.length ? { excludedSurfaceIds: excluded } : {}),
-137
View File
@@ -1,137 +0,0 @@
import assert from "node:assert/strict";
import { mkdtemp, readFile, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import test from "node:test";
import { chromium, expect } from "@playwright/test";
import { BlobReader, BlobWriter, Uint8ArrayReader, Uint8ArrayWriter, ZipReader, ZipWriter } from "@zip.js/zip.js";
import { startReportViewer } from "../ci/lib/report-viewer.mjs";
// The recorded Meow review with one e2e flow added: "send money to a contact" passed on base with three frames and
// failed on head at step 8 with two, so the Flows view shows a compared pair, a base-only frame and a stopped side.
const REPORT = new URL("../fixtures/example-review-artifact.zip", import.meta.url);
const FLOW = JSON.parse(await readFile(new URL("../fixtures/flows/public-review-flow.json", import.meta.url), "utf8"));
async function reportWithFlow(flowsFailure, flow = FLOW) {
const reader = new ZipReader(new BlobReader(new Blob([await readFile(REPORT)])));
const writer = new ZipWriter(new BlobWriter("application/zip"), { useWebWorkers: false });
for (const entry of await reader.getEntries()) {
const bytes = await entry.getData(new Uint8ArrayWriter());
if (entry.filename !== "review.json") { await writer.add(entry.filename, new Uint8ArrayReader(bytes), { level: 0 }); continue; }
const report = JSON.parse(new TextDecoder().decode(bytes));
report.review = { ...report.review, flows: [flow], ...(flowsFailure ? { flowsFailure } : {}) };
await writer.add("review.json", new Uint8ArrayReader(new TextEncoder().encode(JSON.stringify(report))), { level: 6 });
}
await reader.close();
return Buffer.from(await (await writer.close()).arrayBuffer());
}
async function openReport(t, bytes, viewport = { width: 1440, height: 900 }) {
const cacheDir = await mkdtemp(join(tmpdir(), "explore-flows-viewer-"));
const { server, url } = await startReportViewer({ bytes, port: "free", watch: false, cacheDir });
const browser = await chromium.launch({ headless: true });
t.after(async () => { await browser.close(); await server.close(); await rm(cacheDir, { recursive: true, force: true }); });
const page = await browser.newPage({ viewport });
const errors = [];
page.on("pageerror", error => errors.push(error.message));
return { page, url, errors };
}
test("the Flows view shows each flow's outcome per side, its frames and steps, and opens a frame in the inspector", async t => {
const { page, url, errors } = await openReport(t, await reportWithFlow());
await page.goto(`${url}#/flows`);
const card = page.getByRole("region", { name: "send money to a contact" });
await expect(card).toBeVisible();
await expect(card).toContainText("flows/send-money.e2e.ts");
await expect(card.locator(".flow-outcome", { hasText: "After" })).toContainText("failed at step 8");
await expect(card.locator(".flow-outcome", { hasText: "Before" })).toContainText("passed");
await expect(card.locator(".flow-failure")).toContainText('expect.toBeVisible getByTestId("send-confirm")');
// Both sides took contacts and amount; only base reached review.
await expect(card.locator(".flow-frame-caption", { hasText: "contacts" })).toBeVisible();
const contacts = card.locator(".flow-frame", { has: page.locator(".flow-frame-caption", { hasText: "contacts" }) });
// One After | Before toggle per flow flips every frame of the strip; no badge sits on the frames themselves.
await expect(contacts).toHaveAttribute("data-side", "head");
await expect(contacts.locator(".flow-frame-flip")).toHaveCount(0);
const review = card.locator(".flow-frame", { has: page.locator(".flow-frame-caption", { hasText: "review" }) });
await expect(review.locator(".flow-frame-missing")).toContainText("Not reached");
await expect(card).toContainText("Not reached after");
await expect(card.locator("img")).toHaveCount(2, "After: contacts and amount; review was not reached");
const toggle = card.locator(".flow-side-toggle");
await toggle.getByRole("radio", { name: "Before" }).click();
await expect(contacts).toHaveAttribute("data-side", "base");
await expect(contacts.locator(".flow-frame-image")).toHaveAttribute("alt", /Before$/);
await expect(review.locator(".flow-frame-image")).toBeVisible();
await expect(card.locator("img")).toHaveCount(3, "Before: all three frames");
await toggle.getByRole("radio", { name: "After" }).click();
await expect(contacts).toHaveAttribute("data-side", "head");
await expect(card.locator("img")).toHaveCount(2, "After again: contacts and amount");
for (const image of await card.locator("img").all()) {
expect(await image.evaluate(element => element.naturalWidth), "every frame decodes from the report's assets").toBeGreaterThan(0);
}
const steps = card.locator("ol.flow-steps").first().locator("li");
await expect(steps).toHaveCount(8);
await expect(steps.nth(7)).toHaveClass(/failed/);
// A frame opens in the inspector, beside the flow.
await card.locator(".flow-frame-button").first().click();
await expect(page).toHaveURL(/#\/flows\/flow:send-money/);
await expect(page.getByRole("complementary", { name: "Inspector panel" })).toContainText("send money to a contact › contacts");
// The inspector explains the frame by its flow, not by a route transition: the step, the steps around it, the e2e source.
const inspector = page.getByRole("complementary", { name: "Inspector panel" });
await expect(inspector.locator(".flow-section")).toContainText("Frame from step 3 of 8");
await expect(inspector.locator(".transition-section")).toHaveCount(0);
await expect(inspector.locator(".flow-section-step-row").nth(2)).toHaveClass(/current/);
await expect(inspector.locator(".flow-section-step-row").nth(2).locator("a")).toHaveAttribute("href", /github\.com\/expo\/explore-playground\/blob\/[0-9a-f]{40}\/flows\/send-money\.e2e\.ts#L6$/);
await expect(card.locator(".flow-file a")).toHaveAttribute("href", /send-money\.e2e\.ts#L3$/);
assert.deepEqual(errors, []);
});
test("flow frames leave the Screens tree while the Changes count keeps the compared frames", async t => {
const { page, url } = await openReport(t, await reportWithFlow());
await page.goto(`${url}#/screens`);
await expect(page.getByRole("toolbar", { name: "Canvas tools" }).getByRole("button", { name: "Screens", exact: true })).toBeVisible();
await expect(page.locator(".screens-view, main").first()).not.toContainText("send money to a contact");
await expect(page.getByRole("toolbar", { name: "Canvas tools" }).getByRole("button", { name: "Flows", exact: true })).toBeVisible();
});
test("a side whose flows did not run is announced on the Flows view, and the tab stays reachable", async t => {
const failure = { head: { code: "FLOWS_NOT_RUN", message: "Error: Cannot find module 'e2e/runner'" } };
const { page, url } = await openReport(t, await reportWithFlow(failure));
await page.goto(`${url}#/flows`);
const alert = page.getByRole("alert");
await expect(alert).toContainText("The flows did not run");
await expect(alert).toContainText("FLOWS_NOT_RUN");
await expect(alert).toContainText("Cannot find module 'e2e/runner'");
await expect(page.getByRole("region", { name: "send money to a contact" })).toBeVisible();
});
test("on a phone the Flows tab lists the flow with its frames as a filmstrip", async t => {
const { page, url } = await openReport(t, await reportWithFlow(), { width: 390, height: 844 });
await page.goto(`${url}#/flows`);
const card = page.getByRole("region", { name: "send money to a contact" });
await expect(card).toBeVisible();
const strip = card.locator(".flow-filmstrip");
const widths = await strip.evaluate(element => ({ scroll: element.scrollWidth, client: element.clientWidth }));
assert.ok(widths.scroll > widths.client, `the filmstrip scrolls sideways (${widths.scroll} > ${widths.client})`);
for (const button of await card.getByRole("button").all()) {
const box = await button.boundingBox();
assert.ok(box && box.width >= 44 && box.height >= 44, `touch target ${JSON.stringify(box)}`);
}
});
test("a step frame identical to the previous frame on every side folds into it; checkpoints never fold", async t => {
const flow = structuredClone(FLOW);
const contacts = flow.frames.findIndex(frame => frame.key === "contacts");
const twin = key => ({ key, id: `${FLOW.frames[contacts].id.replace(/contacts$/, key)}`, label: `${key === "step-6" ? "6" : "7"}. expect.toBeVisible getByText("Alex Rivera")` });
flow.frames.splice(contacts + 1, 0, twin("step-6"), twin("step-7"));
for (const side of ["head", "base"]) for (const key of ["step-6", "step-7"]) flow[side].frames[key] = { ...flow[side].frames.contacts };
flow.base.frames["step-7"] = { ...flow.base.frames.amount };
const { page, url, errors } = await openReport(t, await reportWithFlow(undefined, flow));
await page.goto(`${url}#/flows`);
const card = page.getByRole("region", { name: "send money to a contact" });
const captions = card.locator(".flow-frame-caption strong");
await expect(captions).toHaveText([/^contacts$/, /^7\. expect/, /^amount$/, /^review$/], "step-6 (same picture on both sides) folds into contacts; step-7 differs on base, so it shows");
const folded = card.locator(".flow-frame", { has: page.locator(".flow-frame-caption", { hasText: "contacts" }) }).locator(".flow-frame-same");
await expect(folded).toHaveText("+1");
await expect(folded).toHaveAttribute("title", /6\. expect\.toBeVisible/);
assert.deepEqual(errors, []);
});
+1 -1
View File
@@ -74,7 +74,7 @@ npm run ci:local -- \
--scope all
```
`--mode` (default `deterministic`) selects `deterministic.yaml`, `agent.yaml` or `flows.yaml`; `--scope`
`--mode` (default `deterministic`) selects `deterministic.yaml` or `agent.yaml`; `--scope`
overrides the config's `exploration.scope`. `--run-id NAME` selects a readable ID and refuses
overwrite. `--plan-only` runs the production planner, checks the expectations at plan level, and
validates each setup step's `requiresRoute` against both revisions, without installation,
-18
View File
@@ -1,18 +0,0 @@
// The wallet app's e2e flow. Explore runs it on both revisions after setup signed the review account in;
// each app.screenshot is a frame the review compares, and a failing step keeps the frames before it.
import { expect, test } from "e2e";
test("send money to a contact", async ({ app, device, screen }) => {
await device.openLink("explore-example-wallet://send/contacts");
await expect(screen.getByTestId("contacts-list")).toBeVisible();
await app.screenshot("contacts");
await screen.getByText("Alex Rivera").tap();
await expect(screen.getByTestId("send-amount-input")).toBeVisible();
await screen.getByTestId("send-amount-input").fill("25");
await app.screenshot("amount");
await screen.getByTestId("send-amount-continue").tap();
await expect(screen.getByTestId("send-confirm")).toBeVisible();
await app.screenshot("review");
});
+24 -1141
View File
File diff suppressed because it is too large. Load diff
-1
View File
@@ -40,7 +40,6 @@
"@babel/core": "^7.20.0",
"@types/react": "~19.2.4",
"babel-preset-expo": "~57.0.8",
"e2e": "0.21.2",
"typescript": "~6.0.3"
}
}
+2 -2
View File
@@ -4,7 +4,7 @@ import { basename, join } from 'node:path';
import { parseArgs } from 'node:util';
export const MATRIX_USAGE = 'Usage: npm run ci:local:matrix -- --app APP (--cells SCENARIO:MODE:SCOPE,... | --scenarios A,B [--modes deterministic,agent] [--scopes all,changes]) [--parallel N] [--prefix NAME] [--plan-only]';
const MODES = ['deterministic', 'agent', 'flows'];
const MODES = ['deterministic', 'agent'];
const SCOPES = ['all', 'changes'];
const list = value => (value ?? '').split(',').map(item => item.trim()).filter(Boolean);
@@ -33,7 +33,7 @@ export function parseMatrixArguments(args, now = new Date()) {
const cells = requested.map(({ scenario, mode, scope }) => {
if (!MODES.includes(mode)) throw new Error(`Unknown mode in matrix: ${mode}`);
if (!SCOPES.includes(scope)) throw new Error(`Unknown scope in matrix: ${scope}`);
const name = `${basename(scenario)}-${mode === 'deterministic' ? 'det' : mode}-${scope}`;
const name = `${basename(scenario)}-${mode === 'deterministic' ? 'det' : 'agent'}-${scope}`;
if (seen.has(name)) throw new Error(`Duplicate matrix cell: ${name}`);
seen.add(name);
return { name, scenario: scenarioPath(values.app, scenario), mode, scope, runId: `${prefix}-${name}` };
+1 -1
View File
@@ -6,7 +6,7 @@ import { lstat, readFile, realpath } from 'node:fs/promises';
import { dirname, isAbsolute, join, normalize, resolve, sep } from 'node:path';
import { parse, stringify } from 'yaml';
const MODES = ['deterministic', 'agent', 'flows'];
const MODES = ['deterministic', 'agent'];
const SCOPES = ['all', 'changes'];
const STATUSES = ['added', 'removed', 'modified', 'needs-review', 'unchanged', 'variant'];
+2 -2
View File
@@ -346,13 +346,13 @@ export async function runLocalCi(input) {
return { run, metadata };
}
export const USAGE = 'Usage: npm run ci:local -- --app APP --scenario SCENARIO [--mode deterministic|agent|flows] [--scope all|changes] [--run-id ID] [--plan-only]';
export const USAGE = 'Usage: npm run ci:local -- --app APP --scenario SCENARIO [--mode deterministic|agent] [--scope all|changes] [--run-id ID] [--plan-only]';
export function parseRunArguments(args) {
const { values } = parseArgs({ args, options: { app: { type: 'string' }, scenario: { type: 'string' }, mode: { type: 'string' }, scope: { type: 'string' },
'run-id': { type: 'string' }, 'plan-only': { type: 'boolean' } } });
if (!values.app || !values.scenario) throw new Error(USAGE);
if (values.mode && !['deterministic', 'agent', 'flows'].includes(values.mode)) throw new Error('--mode must be deterministic, agent or flows');
if (values.mode && !['deterministic', 'agent'].includes(values.mode)) throw new Error('--mode must be deterministic or agent');
if (values.scope && !['all', 'changes'].includes(values.scope)) throw new Error('--scope must be all or changes');
return { app: values.app, scenario: values.scenario, mode: values.mode ?? 'deterministic', ...(values.scope ? { scope: values.scope } : {}),
runId: values['run-id'], planOnly: values['plan-only'] };
-41
View File
@@ -1,41 +0,0 @@
# Flows Explore config for the wallet app: setup signs in, then the e2e flows under flows/ run on the same session.
# The flows are plain e2e tests (https://e2e.tester.army); every `app.screenshot(label)` is a compared frame.
mode: flows
app:
name: Wallet
platform: ios
bundleId: com.expo-explore.example.wallet
easProfile: explore
scheme: explore-example-wallet
navigation:
provider: expo-router
device:
name: iPhone 17
capture:
maxMinutes: 30
maxActions: 300
flows:
tests:
- e2e/*.e2e.ts
setup:
- action: open
url: explore-example-wallet://onboarding/currency
ready: { identifier: currency-continue, enabled: true }
- action: tap
identifier: currency-continue
ready: { identifier: auth-name }
- action: open
url: explore-example-wallet://auth/sign-up
ready: { label: Create your account }
- action: fill
identifier: auth-name
text: Review User
- action: fill
identifier: auth-email
text: [email protected]
- action: fill
identifier: auth-password
text: WalletReview123!
- action: tap
identifier: auth-submit
ready: { identifier: home-balance }
+130 -9
View File
@@ -1491,8 +1491,19 @@ test("Esc closes the Inspector first, then deselects; arrows and hjkl walk the m
await expect(selected).toHaveCount(0);
await expect(page).toHaveURL(/\/map$/);
// Nothing selected: the arrows are not map moves.
await page.keyboard.press("ArrowDown");
// Nothing selected: ↓ enters the map at its top, as → enters Screens at its first card; held, it
// keeps walking down from there and stops where it is on release.
await page.keyboard.down("ArrowDown");
await expect(selected).toHaveCount(1);
const entered = await selected.getAttribute("data-id");
await expect.poll(() => selected.getAttribute("data-id"), { timeout: 4000 }).not.toBe(entered);
await page.keyboard.up("ArrowDown");
const walkedTo = await selected.getAttribute("data-id");
await page.waitForTimeout(500);
await expect(selected).toHaveAttribute("data-id", walkedTo!);
await page.keyboard.press("Escape");
await expect(page.locator(".right-panel")).toHaveCount(0);
await page.keyboard.press("Escape");
await expect(selected).toHaveCount(0);
await page.locator(".map-canvas .react-flow__node-screen .screen-screenshot-target").first().click();
@@ -1508,6 +1519,67 @@ test("Esc closes the Inspector first, then deselects; arrows and hjkl walk the m
await expect(selected).toHaveAttribute("data-id", child!);
});
test("a held key stops when Esc, another key or a dialog takes the keyboard; a menu keeps its own arrows", async ({ page }) => {
await page.goto("/map");
const selected = page.locator(".map-canvas .react-flow__node-screen.selected");
const inspector = page.locator(".right-panel");
const search = page.getByRole("dialog", { name: "Search Explore" });
const viewport = page.locator(".map-canvas .react-flow__viewport");
const mod = process.platform === "darwin" ? "Meta" : "Control";
// Nothing selected and a menu open: ← and → on its item are the menu's, not the map's.
await expect(selected).toHaveCount(0);
await page.locator(".zoom-button").click();
await expect(page.getByRole("menu")).toBeVisible();
await page.keyboard.press("ArrowDown");
await page.keyboard.press("ArrowLeft");
await page.keyboard.press("ArrowRight");
await expect(selected).toHaveCount(0);
await page.keyboard.press("Escape");
await expect(page.getByRole("menu")).toHaveCount(0);
// Esc mid-walk closes the Inspector, and the walk does not reopen it on its next step.
await page.locator(".map-canvas .react-flow__node-screen .screen-screenshot-target").first().click();
await expect(inspector).toBeVisible();
await page.keyboard.down("ArrowDown");
await page.keyboard.press("Escape");
await expect(inspector).toHaveCount(0);
await page.waitForTimeout(800);
await expect(inspector).toHaveCount(0);
await page.keyboard.up("ArrowDown");
// ⌘K mid-walk opens Search, and the selection behind it stays where it was.
await page.keyboard.down("ArrowDown");
await page.keyboard.press(`${mod}+k`);
await expect(search).toBeVisible();
const behind = await selected.getAttribute("data-id");
await page.waitForTimeout(800);
await expect(selected).toHaveAttribute("data-id", behind!);
await page.keyboard.up("ArrowDown");
await page.keyboard.press("Escape");
await expect(search).toHaveCount(0);
// A held + glides past the tap's one step and stops where it is on release.
const zoomNow = async () => (await readCanvasCamera(viewport)).zoom;
const before = await zoomNow();
await page.keyboard.down("Equal");
await expect.poll(zoomNow, { timeout: 4000 }).toBeGreaterThan(before * 1.2 * 1.2);
await page.keyboard.up("Equal");
const released = await zoomNow();
await page.waitForTimeout(300);
expect(await zoomNow()).toBeCloseTo(released, 3);
// Held −, then a click opens Search: the glide stops rather than zoom behind the dialog.
await page.keyboard.down("Minus");
await page.getByRole("button", { name: "Search", exact: true }).click();
await expect(search).toBeVisible();
await page.waitForTimeout(400);
const atOpen = await zoomNow();
await page.waitForTimeout(800);
expect(await zoomNow()).toBeCloseTo(atOpen, 3);
await page.keyboard.up("Minus");
});
test("a drag that starts on a transition edge pans the map", async ({ page }) => {
await page.goto("/map");
const viewport = page.locator(".map-canvas .react-flow__viewport");
@@ -2040,16 +2112,12 @@ test("canonicalizes the legacy Workspace route to Changes and reports the exact
if (entry.status === "unchanged") return total;
return total + (entry.currentScreenIds.length || entry.baselineScreenIds.length);
}, 0);
// The bottom bar's Compare button carries the count.
const badge = page.locator(".canvas-toolbar .toolbar-badge");
await expect(badge).toHaveText(String(expectedChanges));
const menu = await openChangesMenu(page);
await expect(menu.locator(".changes-panel-title .changes-panel-count")).toHaveText(String(expectedChanges));
// Without a baseline there is nothing to count. Compare still opens, and the view says why it is empty.
await page.goto("/map?baseline=none");
await expect(page).toHaveURL(/baseline=none/);
await expect(badge).toHaveCount(0);
const compare = page.getByRole("toolbar", { name: "Canvas tools" }).getByRole("button", { name: "Compare", exact: true });
await expect(compare).not.toHaveAttribute("aria-disabled", "true");
await compare.click();
@@ -2700,6 +2768,31 @@ test("drives the shell from the keyboard, and says so on hover", async ({ page }
}
await expect(page.getByRole("button", { name: "Comments", exact: true })).toHaveCount(0);
// A held modifier shows, on each button it makes a chord with, the key that completes it: ⇧ puts
// 1 on Fit canvas, ⌘ (Ctrl elsewhere) puts K on Search. Released, the hints go.
const hints = page.locator(".key-hint");
await expect(hints).toHaveCount(0);
await page.keyboard.down("Shift");
await expect(page.getByRole("button", { name: "Fit canvas" }).locator(".key-hint")).toHaveText("1");
await expect(page.getByRole("button", { name: "Center canvas" }).locator(".key-hint")).toHaveText("2");
await expect(page.getByRole("button", { name: "Search", exact: true }).locator(".key-hint")).toHaveCount(0);
await page.keyboard.up("Shift");
await expect(hints).toHaveCount(0);
await page.keyboard.down(mod);
await expect(page.getByRole("button", { name: "Search", exact: true }).locator(".key-hint")).toHaveText("K");
await expect(page.getByRole("button", { name: "Fit canvas" }).locator(".key-hint")).toHaveCount(0);
await page.keyboard.up(mod);
await expect(hints).toHaveCount(0);
// Focus that moves into a field by mouse, with ⇧ still down, takes the hints with it.
await page.keyboard.down("Shift");
await expect(page.getByRole("button", { name: "Fit canvas" }).locator(".key-hint")).toHaveText("1");
await page.getByRole("button", { name: "Search", exact: true }).click();
await expect(page.getByRole("dialog", { name: "Search Explore" })).toBeVisible();
await expect(hints).toHaveCount(0);
await page.keyboard.up("Shift");
await page.keyboard.press("Escape");
await expect(page.getByRole("dialog", { name: "Search Explore" })).toHaveCount(0);
// ⌘B opens and closes the Changes menu.
await page.keyboard.press(`${mod}+b`);
await expect(page.locator(".changes-menu")).toBeVisible();
@@ -2732,14 +2825,23 @@ test("drives the shell from the keyboard, and says so on hover", async ({ page }
await expect(page.locator(".tooltip-key")).toHaveText("C");
await page.getByRole("button", { name: "Expand inspector" }).hover();
await expect(page.locator(".tooltip-key")).toHaveText("I");
// The theme button has no key: it names the mode in force and nothing else.
// The theme button names the mode in force, and T is its key.
const themeButton = page.getByRole("button", { name: "Toggle theme" });
await themeButton.hover();
await expect(page.locator(".tooltip-content")).toContainText("Theme:");
await expect(page.locator(".tooltip-key")).toHaveCount(0);
await expect(page.locator(".tooltip-content")).toContainText("Theme: Auto");
await expect(page.locator(".tooltip-key")).toHaveText("T");
await page.mouse.move(0, 0);
const initialTheme = await page.locator("html").getAttribute("data-theme");
expect(initialTheme === "light" || initialTheme === "dark").toBe(true);
const otherTheme = initialTheme === "dark" ? "light" : "dark";
// T flips between dark and light from whatever Auto showed, and never steps back to Auto.
await page.keyboard.press("t");
await expect(page.locator("html")).toHaveAttribute("data-theme", otherTheme);
await page.keyboard.press("t");
await expect(page.locator("html")).toHaveAttribute("data-theme", initialTheme!);
await themeButton.hover();
await expect(page.locator(".tooltip-content")).toContainText(initialTheme === "dark" ? "Theme: Dark" : "Theme: Light");
await page.mouse.move(0, 0);
// The retired theme and inspector chords no longer answer.
await page.keyboard.press(`${mod}+Alt+t`);
await expect(page.locator("html")).toHaveAttribute("data-theme", initialTheme!);
@@ -4202,6 +4304,25 @@ test("desktop Compare: one command bar with the modes in it, even gaps to both b
for (let step = 1; step < before; step += 1) await page.keyboard.press("ArrowRight");
await expect(position).toHaveText(new RegExp(`^${before} of `));
// In Swipe, [ and ] nudge the divider; held, ] keeps going until it is released or at the edge.
await page.keyboard.press("2");
const divider = compare.getByRole("slider");
await expect(divider).toHaveAttribute("aria-valuenow", "50");
await page.keyboard.press("BracketLeft");
await expect(divider).toHaveAttribute("aria-valuenow", "45");
const dividerAt = async () => Number(await divider.getAttribute("aria-valuenow"));
await page.keyboard.down("BracketRight");
await expect(divider).toHaveAttribute("aria-valuenow", "50");
await expect.poll(dividerAt, { timeout: 4000 }).toBeGreaterThanOrEqual(65);
await page.keyboard.up("BracketRight");
const dividerHeld = await dividerAt();
await page.waitForTimeout(600);
expect(await dividerAt()).toBe(dividerHeld);
await page.keyboard.down("BracketRight");
await expect.poll(dividerAt, { timeout: 8000 }).toBe(100);
await page.keyboard.up("BracketRight");
await page.keyboard.press("1");
// The bar keeps one size whatever the route, so Next stays under the pointer: it can be clicked
// again and again through screens whose routes differ in length.
const nextButton = bar.getByRole("button", { name: "Next changed screen" });
-262
View File
@@ -1,262 +0,0 @@
{
"schemaVersion": "report-1",
"run": {
"id": "01a14c4a-51de-7ee0-bfc7-69e8c5353071",
"specVersion": "0.1",
"runner": {
"name": "e2e",
"version": "0.21.2"
},
"status": "passed",
"exitCode": 0,
"startedAt": "2026-10-17T23:55:01.510Z",
"finishedAt": "2026-10-17T23:55:01.530Z",
"project": {
"id": "e2e-probe",
"configDigest": "b61c15749f8acd2d3a2e2fe22cd35ef0b1c1496b94871dc26075448c0c47043a"
},
"environment": {
"ci": false,
"trustNoticeShown": false,
"os": "linux 6.8.0-1061-aws",
"arch": "x64",
"runtime": "node v24.12.0"
},
"targets": [
{
"id": "fake",
"index": 0,
"platform": "fake",
"environment": "test",
"engine": {
"name": "fake",
"version": "0.0.1",
"spiVersion": 1
},
"capabilities": [
"actions",
"artifacts",
"location",
"observation"
],
"artifactCapabilities": [
"screenshot"
],
"stateCapability": false
}
],
"serialGroups": [],
"results": [
{
"id": "eb3881d095c951b6922752e35a8485fa329ff482a49cc0bef3088675c1b34b35",
"testId": "tests/goal.e2e.ts::goal%20without%20model",
"kind": "test",
"declarationIndex": 0,
"titlePath": [
"goal without model"
],
"file": "tests/goal.e2e.ts",
"source": {
"file": "tests/goal.e2e.ts",
"line": 2,
"column": 1
},
"targetId": "fake",
"platform": "fake",
"agent": "default",
"repeat": 0,
"tags": [],
"selected": false,
"status": "skipped",
"skip": {
"cause": "filtered",
"reason": "file not selected by a positional argument"
},
"attempts": []
},
{
"id": "09af3c698e01af961caa47df553e9242887a9c799a28a1f39aa236cc85831150",
"testId": "tests/send.e2e.ts::send%20money%20reaches%20contacts",
"kind": "test",
"declarationIndex": 0,
"titlePath": [
"send money reaches contacts"
],
"file": "tests/send.e2e.ts",
"source": {
"file": "tests/send.e2e.ts",
"line": 2,
"column": 1
},
"targetId": "fake",
"platform": "fake",
"agent": "default",
"repeat": 0,
"tags": [],
"selected": true,
"status": "passed",
"attempts": [
{
"id": "01a14c4a-520d-76c6-9013-1d2dbc51ebc5",
"index": 0,
"status": "passed",
"startedAt": "2026-10-17T23:55:01.517Z",
"durationMs": 12,
"artifacts": [
{
"id": "01a14c4a-520d-76c6-9013-1d2dbc51ebc5:artifact:0",
"kind": "screenshot",
"mediaType": "image/png",
"redaction": "complete",
"producer": {
"kind": "step",
"stepId": "01a14c4a-520d-76c6-9013-1d2dbc51ebc5:0"
},
"path": "send-money-reaches-contacts-09af3c698e01af96/attempt-1/screenshots/001.png",
"size": 70,
"sha256": "497790947d4666760ce38f3c00e852c71fdb66cae849bae8e9ede352719e1581"
},
{
"id": "01a14c4a-520d-76c6-9013-1d2dbc51ebc5:artifact:1",
"kind": "screenshot",
"mediaType": "image/png",
"redaction": "complete",
"producer": {
"kind": "step",
"stepId": "01a14c4a-520d-76c6-9013-1d2dbc51ebc5:3"
},
"path": "send-money-reaches-contacts-09af3c698e01af96/attempt-1/screenshots/002.png",
"size": 70,
"sha256": "497790947d4666760ce38f3c00e852c71fdb66cae849bae8e9ede352719e1581"
}
],
"secondaryErrors": [],
"cleanup": "complete",
"steps": [
{
"id": "01a14c4a-520d-76c6-9013-1d2dbc51ebc5:0",
"index": 0,
"kind": "app",
"api": "app.screenshot",
"label": "home",
"status": "passed",
"startedAt": "2026-10-17T23:55:01.520Z",
"durationMs": 1,
"events": [],
"artifacts": [
"01a14c4a-520d-76c6-9013-1d2dbc51ebc5:artifact:0"
],
"source": {
"file": "tests/send.e2e.ts",
"line": 3,
"column": 13
}
},
{
"id": "01a14c4a-520d-76c6-9013-1d2dbc51ebc5:1",
"index": 1,
"kind": "locator",
"api": "locator.tap",
"label": "getByTestId(\"home-send\")",
"status": "passed",
"startedAt": "2026-10-17T23:55:01.521Z",
"durationMs": 1,
"events": [
{
"kind": "engine",
"name": "tap",
"startedAt": "2026-10-17T23:55:01.522Z",
"durationMs": 0,
"status": "passed",
"detail": "tap button \"Send\""
}
],
"artifacts": [],
"source": {
"file": "tests/send.e2e.ts",
"line": 4,
"column": 41
}
},
{
"id": "01a14c4a-520d-76c6-9013-1d2dbc51ebc5:2",
"index": 2,
"kind": "assertion",
"api": "expect.toBeVisible",
"label": "getByRole(\"heading\", name: \"Your contacts\")",
"status": "passed",
"startedAt": "2026-10-17T23:55:01.523Z",
"durationMs": 0,
"events": [
{
"kind": "poll",
"name": "expect",
"startedAt": "2026-10-17T23:55:01.523Z",
"durationMs": 0,
"status": "passed",
"count": 1
}
],
"artifacts": [],
"source": {
"file": "tests/send.e2e.ts",
"line": 5,
"column": 62
}
},
{
"id": "01a14c4a-520d-76c6-9013-1d2dbc51ebc5:3",
"index": 3,
"kind": "app",
"api": "app.screenshot",
"label": "contacts",
"status": "passed",
"startedAt": "2026-10-17T23:55:01.523Z",
"durationMs": 0,
"events": [],
"artifacts": [
"01a14c4a-520d-76c6-9013-1d2dbc51ebc5:artifact:1"
],
"source": {
"file": "tests/send.e2e.ts",
"line": 6,
"column": 13
}
}
]
}
]
}
],
"errors": [],
"summary": {
"discovered": 2,
"selected": 1,
"executed": 1,
"passed": 1,
"failed": 0,
"interrupted": 0,
"flaky": 0,
"skipped": 0
},
"limits": {
"maxAgentContextBytes": 16384,
"maxLedgerBytes": 8192,
"maxObservationBytes": 262144,
"maxEventsPerStep": 1000,
"maxModelTokensPerCall": 64000
},
"usage": {
"discoveredResults": 2,
"maxAgentContextBytes": 0,
"maxLedgerBytes": 0,
"maxObservationBytes": 0,
"artifactBytes": 140,
"downloads": 0,
"events": 2,
"modelTokens": 0,
"maxModelCallsInStep": 0,
"maxActionStepsInStep": 0
}
}
}
-36
View File
@@ -1,36 +0,0 @@
// A two-screen app for the flows worker: Home (a Send button) and Contacts (a heading and one contact).
import { defineEngine, resolveExpression } from "e2e/engine";
import { mkdirSync, writeFileSync } from "node:fs";
import { join } from "node:path";
const PNG = Buffer.from("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==", "base64");
const screens = {
home: [{ ref: { id: "send", revision: "1" }, role: "button", name: "Send", testId: "home-send", rect: { x: 0, y: 0, width: 100, height: 40 } }],
contacts: [
{ ref: { id: "title", revision: "2" }, role: "heading", name: "Your contacts", rect: { x: 0, y: 0, width: 100, height: 40 } },
{ ref: { id: "alex", revision: "2" }, role: "button", name: "Alex Rivera", rect: { x: 0, y: 50, width: 100, height: 40 } },
],
};
export function engine() {
let screen = "home";
let attemptDir = "";
let shots = 0;
const root = () => ({ ref: { id: "root", revision: screen }, role: "window", children: screens[screen] });
return defineEngine({
name: "fake-device", version: "0.0.1", spiVersion: 1, platform: "fake",
async startAttempt(info) { attemptDir = info.artifactsDir; screen = "home"; shots = 0; },
async observe() { return { root: root(), viewport: { width: 100, height: 100 } }; },
async locate(expression) { return resolveExpression(expression, [root()]); },
actions: ["tap"],
async perform(ref) { if (ref.id === "send") screen = "contacts"; },
session: { async restart() { screen = "home"; } },
artifacts: { async screenshot() {
shots += 1;
const path = `screenshots/${String(shots).padStart(3, "0")}.png`;
mkdirSync(join(attemptDir, "screenshots"), { recursive: true });
writeFileSync(join(attemptDir, path), PNG);
return path;
} },
});
}
-223
View File
@@ -1,223 +0,0 @@
{
"id": "send-money/send-money-to-a-contact",
"title": "send money to a contact",
"file": "flows/send-money.e2e.ts",
"base": {
"status": "passed",
"durationMs": 3202,
"steps": [
{
"api": "device.openLink",
"label": "explore-example-wallet://send/contacts",
"status": "passed",
"durationMs": 812,
"line": 4
},
{
"api": "expect.toBeVisible",
"label": "getByTestId(\"contacts-list\")",
"status": "passed",
"durationMs": 140,
"line": 5
},
{
"api": "app.screenshot",
"label": "contacts",
"status": "passed",
"durationMs": 310,
"frame": "contacts",
"line": 6
},
{
"api": "locator.tap",
"label": "getByText(\"Alex Rivera\")",
"status": "passed",
"durationMs": 420,
"line": 7
},
{
"api": "locator.fill",
"label": "getByTestId(\"send-amount-input\")",
"status": "passed",
"durationMs": 380,
"line": 8
},
{
"api": "app.screenshot",
"label": "amount",
"status": "passed",
"durationMs": 290,
"frame": "amount",
"line": 9
},
{
"api": "locator.tap",
"label": "getByTestId(\"send-amount-continue\")",
"status": "passed",
"durationMs": 400,
"line": 10
},
{
"api": "expect.toBeVisible",
"label": "getByTestId(\"send-confirm\")",
"status": "passed",
"durationMs": 150,
"line": 11
},
{
"api": "app.screenshot",
"label": "review",
"status": "passed",
"durationMs": 300,
"frame": "review",
"line": 12
}
],
"frames": {
"contacts": {
"url": "https://embedded.expo-explore.invalid/f3f6e607859abb7e1ff343cdeed2e8939d243966e7aca90e023fb561266cdfcb.png",
"sha256": "f3f6e607859abb7e1ff343cdeed2e8939d243966e7aca90e023fb561266cdfcb",
"width": 402,
"height": 874,
"capturedAt": "2026-09-22T11:39:40.895Z"
},
"amount": {
"url": "https://embedded.expo-explore.invalid/c127fb80b3c6423998da6bc161aba372c6fcf76b664253822718672f33c7d238.png",
"sha256": "c127fb80b3c6423998da6bc161aba372c6fcf76b664253822718672f33c7d238",
"width": 402,
"height": 874,
"capturedAt": "2026-09-22T11:39:47.748Z"
},
"review": {
"url": "https://embedded.expo-explore.invalid/157d6714f158f3b430cd0522eb72c20861f4159339d85ff0fc0ad4515a70ba72.png",
"sha256": "157d6714f158f3b430cd0522eb72c20861f4159339d85ff0fc0ad4515a70ba72",
"width": 402,
"height": 874,
"capturedAt": "2026-09-22T11:39:54.038Z"
}
},
"line": 3
},
"head": {
"status": "failed",
"durationMs": 7754,
"error": {
"code": "ASSERTION_FAILED",
"message": "getByTestId(\"send-confirm\") was not visible within 5000 ms"
},
"steps": [
{
"api": "device.openLink",
"label": "explore-example-wallet://send/contacts",
"status": "passed",
"durationMs": 812,
"line": 4
},
{
"api": "expect.toBeVisible",
"label": "getByTestId(\"contacts-list\")",
"status": "passed",
"durationMs": 140,
"line": 5
},
{
"api": "app.screenshot",
"label": "contacts",
"status": "passed",
"durationMs": 310,
"frame": "contacts",
"line": 6
},
{
"api": "locator.tap",
"label": "getByText(\"Alex Rivera\")",
"status": "passed",
"durationMs": 420,
"line": 7
},
{
"api": "locator.fill",
"label": "getByTestId(\"send-amount-input\")",
"status": "passed",
"durationMs": 380,
"line": 8
},
{
"api": "app.screenshot",
"label": "amount",
"status": "passed",
"durationMs": 290,
"frame": "amount",
"line": 9
},
{
"api": "locator.tap",
"label": "getByTestId(\"send-amount-continue\")",
"status": "passed",
"durationMs": 400,
"line": 10
},
{
"api": "expect.toBeVisible",
"label": "getByTestId(\"send-confirm\")",
"status": "failed",
"durationMs": 5002,
"error": {
"code": "ASSERTION_FAILED",
"message": "getByTestId(\"send-confirm\") was not visible within 5000 ms"
},
"line": 11
}
],
"frames": {
"contacts": {
"url": "https://embedded.expo-explore.invalid/962bb0cd594c48b6c47ef6fd8a6ca6f2411128d812a93ab17854b74fc59e6892.png",
"sha256": "962bb0cd594c48b6c47ef6fd8a6ca6f2411128d812a93ab17854b74fc59e6892",
"width": 402,
"height": 874,
"capturedAt": "2026-09-22T11:31:18.054Z"
},
"amount": {
"url": "https://embedded.expo-explore.invalid/4b2cd242fcf5a38712a4f290561fb24e496dfeeeb7c78c4258f6c75f26608b9f.png",
"sha256": "4b2cd242fcf5a38712a4f290561fb24e496dfeeeb7c78c4258f6c75f26608b9f",
"width": 402,
"height": 874,
"capturedAt": "2026-09-22T11:31:33.692Z"
}
},
"line": 3
},
"frames": [
{
"key": "contacts",
"id": "flow:send-money/send-money-to-a-contact/contacts",
"label": "contacts",
"visual": {
"verdict": "unchanged",
"reason": "matched",
"mismatchPercentage": 0,
"threshold": 0.1,
"tool": "[email protected]",
"ignoredStatusBarRegions": 1
}
},
{
"key": "amount",
"id": "flow:send-money/send-money-to-a-contact/amount",
"label": "amount",
"visual": {
"verdict": "unchanged",
"reason": "matched",
"mismatchPercentage": 0,
"threshold": 0.1,
"tool": "[email protected]",
"ignoredStatusBarRegions": 1
}
},
{
"key": "review",
"id": "flow:send-money/send-money-to-a-contact/review",
"label": "review"
}
]
}
+8 -1
View File
@@ -179,7 +179,14 @@ const Navigation=createStaticNavigation(Root); export default function App(){ret
}
return ok(identity(device));
}
if (command === 'fold') return ok({ action: 'fold', pose: request.args[1] });
if (command === 'fold') { device.pose = request.args[1]; return ok({ action: 'fold', pose: request.args[1] }); }
// The display a fold lit, as a pose check reads it: landscape when opened, and drawn.
if (command === 'screenshot' && request.args[1].endsWith('/pose.png')) {
const display = new PNG(device.pose === 'open' ? { width: 24, height: 16 } : { width: 16, height: 24 });
display.data[0] = 255;
writeFileSync(request.args[1], PNG.sync.write(display));
return ok({ path: request.args[1] });
}
if (command === 'install') {
const app = request.args[1];
device.build = platform === 'android' ? readFileSync(app, 'utf8') : readFileSync(join(app, 'build-id'), 'utf8');
+29 -3
View File
@@ -395,9 +395,18 @@ test("when Argent reads nothing while the prompt is up, Open is tapped from a sc
assert.equal(context.state.deepLinkPromptAccepted, true);
});
test("reset-reader stops the device's Argent helpers by its UDID and forgets what the old reader saw", async () => {
const state = { generation: 3, udid: UDID, screen: { width: 402, height: 874 }, refs: { e1: {} } };
const { calls, run } = harness("ios", { "stop-all-simulator-servers": { stopped: [`NativeDevtools:${UDID}`, `AXService:${UDID}`] } }, { state });
const reset = await run(["reset-reader", ...flags("ios")]);
assert.deepEqual(reset.json.data, { action: "reset-reader", stopped: [`NativeDevtools:${UDID}`, `AXService:${UDID}`] });
assert.deepEqual(calls, [{ tool: "stop-all-simulator-servers", args: { devices: [UDID] } }]);
assert.equal(state.screen, undefined); assert.equal(state.refs, undefined); assert.equal(state.generation, 4);
});
test("fold moves a foldable to a pose and forgets the old panel's geometry", async () => {
// Argent's fold answers with the panel it lit, in pixels; the inner panel is 2007 × 2853 (669 × 951 points).
const { run, calls, context } = harness("ios", { "list-devices": DUO_DEVICES, "ui-tree": [DUO_HOME, DUO_OPEN_EDIT_LANE],
const { run, calls, context } = harness("ios", { "list-devices": DUO_DEVICES, "ui-tree": [DUO_HOME, DUO_OPEN_EDIT_LANE], "stop-all-simulator-servers": { stopped: [] },
fold: { activeScreen: 3, screen: { id: 3, panel: "inner panel", width: 2007, height: 2853 }, posture: "open", hingeAngle: 180 } });
await run(["snapshot", ...flags("ios")]);
const generation = context.state.generation;
@@ -407,12 +416,29 @@ test("fold moves a foldable to a pose and forgets the old panel's geometry", asy
const fold = calls.findIndex(call => call.tool === "fold");
assert.equal(calls.slice(0, fold).filter(call => call.tool === "ui-tree").length, reads, "nothing is read between the command and the fold");
assert.deepEqual(calls[fold].args, { udid: "74195B53-4DBC-4EAA-9991-F98E5BB86BA8", posture: "open" });
// The device's helpers are reset just before the fold, so the panel it lights is read by fresh ones.
assert.deepEqual(calls[fold - 1], { tool: "stop-all-simulator-servers", args: { devices: ["74195B53-4DBC-4EAA-9991-F98E5BB86BA8"] } });
assert.equal(context.state.screen, undefined);
assert.equal(context.state.refs, undefined);
assert.equal(context.state.generation, generation + 1);
assert.equal((await run(["fold", "sideways", ...flags("ios")])).json.error.code, "INVALID_ARGS");
});
test("a reader stuck on the dark panel after a fold is reset once more before the fold is called unverified", async () => {
const fold = { activeScreen: 3, screen: { id: 3, panel: "inner panel", width: 2007, height: 2853 }, posture: "open", hingeAngle: 180 };
const stopped = { stopped: ["AXService:74195B53-4DBC-4EAA-9991-F98E5BB86BA8"] };
// Ten reads still in the cover panel's shape (as on EAS, 2026-10-17), then the inner panel once the helpers restart.
const recovers = harness("ios", { "list-devices": DUO_DEVICES, fold, "stop-all-simulator-servers": stopped, "ui-tree": [...Array(10).fill(DUO_HOME), DUO_OPEN_EDIT_LANE] });
assert.deepEqual((await recovers.run(["fold", "open", ...flags("ios")])).json.data, { action: "fold", pose: "open" });
assert.deepEqual(recovers.calls.filter(call => call.tool === "stop-all-simulator-servers").map(call => call.args), Array(2).fill({ devices: ["74195B53-4DBC-4EAA-9991-F98E5BB86BA8"] }));
const stuck = harness("ios", { "list-devices": DUO_DEVICES, fold, "stop-all-simulator-servers": stopped, "ui-tree": DUO_HOME });
const failed = await stuck.run(["fold", "open", ...flags("ios")]);
assert.equal(failed.json.error.code, "CONTROLLER_FOLD_UNVERIFIED");
assert.match(failed.json.error.message, /after its device helpers were reset/);
assert.equal(stuck.calls.filter(call => call.tool === "stop-all-simulator-servers").length, 2, "before the fold and once after, not in a loop");
});
test("an alert that is not the link prompt is left for capture to answer", async () => {
const other = { ...IOS_HOME, alertVisible: true, foregroundApp: "com.apple.springboard",
roots: [{ type: "Alert", label: "Delete all data?", frame: { x: 0.1, y: 0.4, width: 0.8, height: 0.2 }, children: [
@@ -534,9 +560,9 @@ test("a node its ancestor clips away is still reported hidden on iOS", () => {
test("a fold whose panel Argent never reads fails clearly instead of capturing the dark panel", async () => {
const lit = { activeScreen: 3, screen: { id: 3, panel: "inner panel", width: 2007, height: 2853 }, posture: "open", hingeAngle: 180 };
const blindClosed = { ...DUO_HOME, foregroundApp: undefined, roots: [{ role: "AXGroup", children: [] }] };
const late = harness("ios", { "list-devices": DUO_DEVICES, fold: lit, "ui-tree": [blindClosed, blindClosed, DUO_OPEN_EDIT_LANE] });
const late = harness("ios", { "list-devices": DUO_DEVICES, fold: lit, "stop-all-simulator-servers": { stopped: [] }, "ui-tree": [blindClosed, blindClosed, DUO_OPEN_EDIT_LANE] });
assert.equal((await late.run(["fold", "open", ...flags("ios")])).exitCode, 0, "a reader that catches up within the wait is fine");
const stuck = harness("ios", { "list-devices": DUO_DEVICES, fold: lit, "ui-tree": blindClosed });
const stuck = harness("ios", { "list-devices": DUO_DEVICES, fold: lit, "stop-all-simulator-servers": { stopped: [] }, "ui-tree": blindClosed });
const failed = await stuck.run(["fold", "open", ...flags("ios")]);
assert.equal(failed.json.error.code, "CONTROLLER_FOLD_UNVERIFIED");
assert.equal(stuck.calls.filter(call => call.tool === "fold").length, 1, "the session is not folded back and forth");
+1 -1
View File
@@ -8,7 +8,7 @@ const transition = await tsImport(
);
test("canvas view direction follows the toolbar order", () => {
assert.deepEqual(transition.CANVAS_VIEW_ORDER, ["flows", "map", "screens", "compare"]);
assert.deepEqual(transition.CANVAS_VIEW_ORDER, ["map", "screens", "compare"]);
assert.equal(transition.canvasViewTransitionDirection("screens", "compare"), "forward");
assert.equal(transition.canvasViewTransitionDirection("map", "screens"), "forward");
assert.equal(transition.canvasViewTransitionDirection("compare", "screens"), "backward");
+223 -82
View File
@@ -1,7 +1,7 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import { spawn, spawnSync } from 'node:child_process';
import { existsSync, mkdirSync, readdirSync, readFileSync, symlinkSync, writeFileSync } from 'node:fs';
import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
import { createHash } from 'node:crypto';
import { mkdtemp, mkdir, readdir, readFile, realpath, rm, writeFile } from 'node:fs/promises';
import { join, relative, sep } from 'node:path';
@@ -103,21 +103,19 @@ async function fixture(t, settings = {}) {
await writeCaptureObserverPackages(project);
await writeFile(join(project, 'package.json'), '{"name":"example","main":"index.js"}\n');
await writeFile(join(project, 'app.json'), JSON.stringify({ expo: { name: 'Example', slug: 'example' } }));
if (settings.flowFiles) {
// The app resolves `e2e` from its own node_modules, as a real app does.
await mkdir(join(project, 'e2e')); await mkdir(join(project, 'node_modules'), { recursive: true });
symlinkSync(new URL('../../node_modules/e2e', import.meta.url).pathname, join(project, 'node_modules', 'e2e'), 'dir');
for (const [name, source] of Object.entries(settings.flowFiles)) await writeFile(join(project, 'e2e', name), source);
}
const routes = settings.routes ?? [route('home'), route('settings')];
const files = new Map(routes.map(item => [item.routeFile, 'export default function Screen(){return null;}']));
const plan = createSourceCapturePlan({ baseSha: SHA, headSha: HEAD, baseFiles: files, headFiles: files,
changedFiles: [], mode: 'all', provider: 'expo-router', ...(settings.flows?.only ? { captureRoutes: false } : {}) });
changedFiles: [], mode: 'all', provider: 'expo-router' });
const ids = Object.fromEntries(routes.map(item => [item.id, plan.surfaces.find(row => row.baseSurface.routeFile === item.routeFile).id]));
const planPath = join(root, 'plan.json'); await writeFile(planPath, JSON.stringify(plan));
const requests = [];
let current = '/'; let snapshots = 0; let sessionName; let screenshotAttempts = 0; let splashLeft = 0; let recordingPath = ''; let alert = null; let appearance = 'light'; let alertReads = 0;
let enteredName = false; let scrolledToContinue = false; let finishHidden = false; let wedgeCleared = false; let deviceLost = false; let relaunchedAfterForeign = false; let serverStarts = 0; let unreadableLeft = settings.unreadableAfterFold ?? 0;
// startsErrored / startsUnnamed: how many session starts EAS fails, after naming the session (it ERRORS) or before.
let starts = 0; let currentSession = 'session-1'; const erroredSessions = new Set(); let foldUnverifiedLeft = settings.foldUnverified ?? 0;
// blackAfterFold: the first so many folds of an EAS agent-device session light the panel but draw nothing.
let folds = 0;
const deviceName = settings.android ? 'Pixel 7' : 'iPhone 17 Pro';
const platform = settings.android ? 'android' : 'ios';
// A local simulator is the one the capture created, named for Explore.
@@ -131,12 +129,6 @@ async function fixture(t, settings = {}) {
const runner = request => {
requests.push(request);
const command = request.args[0];
// The flows worker is a real child process: e2e runs the app's test files against the fake engine.
if (request.command === process.execPath) {
const child = spawnSync(request.command, request.args, { cwd: request.cwd, env: request.environment, encoding: 'utf8', timeout: request.timeoutMs });
if (child.status !== 0 && !request.allowFailure) throw new Error(`worker exited ${child.status}: ${child.stderr}`);
return { stdout: child.stdout ?? '', stderr: child.stderr ?? '' };
}
if (request.command === 'git') {
if (command === 'ls-files') return { stdout: readdirSync(project, { recursive: true, withFileTypes: true })
.filter(entry => entry.isFile() && !relative(project, entry.parentPath).split(sep).includes('node_modules'))
@@ -194,6 +186,14 @@ async function fixture(t, settings = {}) {
appConfig: { name: 'Example', slug: 'example', owner: 'acme', ...(settings.userInterfaceStyle ? { userInterfaceStyle: settings.userInterfaceStyle } : {}), scheme: settings.noScheme ? undefined : 'sample',
...(settings.android ? { android: { package: 'com.example.app' } } : { ios: { bundleIdentifier: 'com.example.app' } }), extra: { eas: { projectId: PROJECT_ID } } } });
if (command === 'simulator:availability') return json({ available: settings.available !== false });
// controlActions: what the session's serve-sim offers through simulator:control (none unless a test names them).
if (command === 'simulator:control') {
assert.equal(value(request, '--id'), currentSession, 'simulator:control names the session');
if (request.args.includes('--list')) return json(Object.fromEntries((settings.controlActions ?? []).map(action => [action, { type: 'object' }])));
assert.ok((settings.controlActions ?? []).includes(request.args[1]), `${request.args[1]} is offered by the session`);
if (request.args[1] === 'appearance.set') appearance = request.args.at(-1);
return json({ id: currentSession, action: request.args[1], output: '' });
}
if (command === 'fingerprint:generate') return json({ hash: 'source-fingerprint' });
const buildMetadata = settings.buildMetadata ? { appVersion: '2.1.0', appBuildVersion: '42' } : {};
if (command === 'build:list') return json(settings.reuse ? [{ id: 'native-build', ...buildMetadata }] : []);
@@ -223,13 +223,23 @@ async function fixture(t, settings = {}) {
}
if (command === 'simulator:start') {
sessionName = value(request, '--name');
writeFileSync(join(request.cwd, '.env.eas-simulator'), HEADER + "EAS_SIMULATOR_SESSION_ID='session-1'\n" + (settings.argent
starts += 1; currentSession = `session-${starts}`;
if (starts <= (settings.startsUnnamed ?? 0)) { writeFileSync(join(request.cwd, '.env.eas-simulator'), HEADER); throw new Error('GraphQL request failed.'); }
if (starts <= (settings.startsErrored ?? 0)) erroredSessions.add(currentSession);
writeFileSync(join(request.cwd, '.env.eas-simulator'), HEADER + `EAS_SIMULATOR_SESSION_ID='${currentSession}'\n` + (settings.argent
? "ARGENT_TOOLS_URL='https://controller.example/session'\nARGENT_AUTH_TOKEN='" + DAEMON_TOKEN + "'\n"
: "AGENT_DEVICE_DAEMON_BASE_URL='https://controller.example/session'\nAGENT_DEVICE_DAEMON_AUTH_TOKEN='" + DAEMON_TOKEN + "'\n"));
if (settings.startFailure) throw new Error('start reported failure after allocation');
if (erroredSessions.has(currentSession)) throw new Error('Simulator session errored while starting');
return { stdout: 'ready', stderr: '' };
}
if (command === 'simulator:get') return json({ id: 'session-1', name: sessionName, type: settings.argent ? 'argent' : 'agent-device', platform: settings.android ? 'ANDROID' : 'IOS', status: 'IN_PROGRESS',
// orphanFromFailedStart: a start that failed before naming the session had still created one.
if (command === 'simulator:list') return json({ sessions: settings.orphanFromFailedStart && value(request, '--name') === sessionName ? [{ id: 'orphan-1', name: sessionName,
type: settings.argent ? 'argent' : 'agent-device', status: 'STARTING', platform: 'IOS',
// orphanUnproven: the session by that name does not show it belongs to this project.
deviceRunSessionUrl: `https://expo.dev/accounts/${settings.orphanUnproven ? 'someone-else' : 'acme'}/projects/example/simulator-sessions/orphan-1` }] : [], pageInfo: {} });
if (command === 'simulator:get') return json({ id: value(request, '--id'), name: sessionName, type: settings.argent ? 'argent' : 'agent-device', platform: settings.android ? 'ANDROID' : 'IOS',
status: erroredSessions.has(value(request, '--id')) ? 'ERRORED' : 'IN_PROGRESS',
app: { id: settings.wrongProject ? 'foreign-project' : PROJECT_ID, slug: 'example', ownerAccount: { name: 'acme' } },
remoteConfig: { ...(settings.argent ? { toolsUrl: 'https://controller.example/session', toolsAuthToken: DAEMON_TOKEN }
: { agentDeviceRemoteSessionUrl: 'https://controller.example/session', agentDeviceRemoteSessionToken: DAEMON_TOKEN }),
@@ -238,7 +248,7 @@ async function fixture(t, settings = {}) {
...(settings.previewApiUrl ? { previewApiUrl: settings.previewApiUrl } : {}) } });
if (command === 'simulator:stop') {
if (settings.stopFailure) throw new Error('stop unavailable');
return json({ id: 'session-1', status: 'STOPPED' });
return json({ id: value(request, '--id'), status: 'STOPPED' });
}
}
if (request.command === 'fake-repack') {
@@ -253,6 +263,7 @@ async function fixture(t, settings = {}) {
// An Argent capture runs its per-run bridge in place of agent-device; the bridge answers in agent-device's envelopes.
if (request.command === 'fake-controller' || (settings.argent && request.command.endsWith('/argent-controller'))) {
if (command === '--version') return { stdout: settings.argent ? '0.29.0' : AGENT_DEVICE_VERSION, stderr: '' };
if (command === 'reset-reader') return json({ success: true, data: { action: 'reset-reader', stopped: ['AXService:device'] } });
if (command === 'open') {
// unreadableAfterFold: Argent's reader stayed on the outer panel, so the first app opens find no readable app.
if (unreadableLeft > 0 && !request.args[2]?.startsWith('sample://')) { unreadableLeft -= 1;
@@ -286,9 +297,12 @@ async function fixture(t, settings = {}) {
// An EAS session starts empty while the app is repacked; the controller installs the app from this machine.
if (command === 'install') { assert.ok(existsSync(request.args[1]), 'the repacked app is on this machine'); return ok({ installed: true, appBundleId: 'com.example.app' }); }
// agent-device 0.21.15 cannot read Xcode 27.1's hinge angle back, so a local fold reports a failure after folding.
// foldUnverified: the bridge's reader stayed on the dark panel through its own reset, for that many folds.
// The bridge exits non-zero, and the runner throws its structured error, as defaultRunner does.
if (command === 'fold') folds += 1;
if (command === 'fold' && foldUnverifiedLeft > 0) { foldUnverifiedLeft -= 1;
throw controllerCommandFailure(json({ success: false, error: { code: 'CONTROLLER_FOLD_UNVERIFIED', message: 'Argent kept reading the other panel after folding the device open, and after its device helpers were reset.' } }).stdout, 'fold'); }
if (command === 'fold') return settings.local ? json({ success: false, error: { code: 'COMMAND_FAILED', message: "CoreDevice reported no hinge angle sample: Unknown option '--device'" } })
// EAS Simulator: the pose is dispatched, but agent-device cannot read the hinge back to confirm it.
: settings.foldUnverified ? json({ success: false, error: { code: 'COMMAND_FAILED', message: `fold: iPhone Duo received the ${request.args[1]} pose request, but the first hinge-angle read returned no sample to verify it` } })
: ok({ action: 'fold', pose: request.args[1] });
if (command === 'record' && settings.recording) {
if (request.args[1] === 'start') { recordingPath = request.args[2]; return ok({ path: recordingPath }); }
@@ -361,6 +375,13 @@ async function fixture(t, settings = {}) {
if (request.args[1] === 'appearance') appearance = request.args[2];
return ok({ setting: request.args[1], value: request.args[2] });
}
// The display after a fold, as agent-device's screenshot shows it on EAS: in the pose's shape, drawn or black.
if (command === 'screenshot' && request.args[1]?.endsWith('/pose.png')) {
const display = new PNG(settings.devicePose === 'open' ? { width: 30, height: 20 } : { width: 20, height: 30 });
if (folds > (settings.blackAfterFold ?? 0)) display.data[0] = 255;
writeFileSync(request.args[1], PNG.sync.write(display));
return ok({ path: request.args[1] });
}
if (command === 'screenshot') {
screenshotAttempts += 1;
if (settings.firstScreenshotFails && screenshotAttempts === 1) throw new Error('temporary screenshot transport error');
@@ -392,7 +413,7 @@ async function fixture(t, settings = {}) {
buildId: 'source-capture', buildVersion: '1', gitCommit: SHA, bundleId: 'com.example.app',
...(settings.noScheme ? {} : { scheme: 'sample' }), device: deviceName, easProfile: 'capture', expoToken: 'expo-private', ...(settings.android ? { platform: 'android' } : {}),
planPath, maxScreens: 120, maxActions: 500, maxDurationMinutes: 30, forceFreshBuild: false,
confirmExternalRun: true, confirmTrustedSource: true, easCommand: 'fake-eas', repackCommand: 'fake-repack', agentDeviceCommand: 'fake-controller', ...(settings.argent ? { controller: 'argent' } : {}), ...(settings.devicePose ? { devicePose: settings.devicePose } : {}), ...(settings.launch ? { launch: settings.launch, recordingTools: settings.recordingTools ?? null } : {}), ...(settings.repack ? { repack: settings.repack } : {}), ...(settings.local ? { simulator: 'local' } : {}), ...(settings.flows ? { flows: settings.flows } : {}),
confirmExternalRun: true, confirmTrustedSource: true, easCommand: 'fake-eas', repackCommand: 'fake-repack', agentDeviceCommand: 'fake-controller', ...(settings.argent ? { controller: 'argent' } : {}), ...(settings.devicePose ? { devicePose: settings.devicePose } : {}), ...(settings.launch ? { launch: settings.launch, recordingTools: settings.recordingTools ?? null } : {}), ...(settings.repack ? { repack: settings.repack } : {}), ...(settings.local ? { simulator: 'local' } : {}),
environment: { PATH: process.env.PATH, HOME: root, ...(settings.local && settings.android ? { ANDROID_HOME: sdk, TMPDIR: root } : {}), GITHUB_TOKEN: 'github-private', ANTHROPIC_API_KEY: 'must-not-be-used', AGENT_DEVICE_DAEMON_AUTH_TOKEN: 'wrong-token', ...settings.environment },
// Every controller round trip advances the fixture clock by one poll interval, as a device snapshot would.
runner: request => { clockMs += 600; return runner(request); }, now: () => clockMs, sleep: milliseconds => { clockMs += milliseconds; }, fetch: catalog };
@@ -482,7 +503,7 @@ test('an Argent capture starts an argent session, drives it through the bridge,
}
// Argent cannot switch appearance yet: one pass, no `settings appearance`, and a warning naming what was skipped.
assert.equal(f.requests.some(request => request.args[0] === 'settings'), false);
assert.ok(lines.some(line => /Argent cannot switch appearance yet .*capturing light only, skipped dark/.test(line)), lines.join('\n'));
assert.ok(lines.some(line => /Argent cannot switch appearance on this session; capturing light only, skipped dark/.test(line)), lines.join('\n'));
const map = JSON.parse(await readFile(join(f.options.outputDirectory, 'screen-map.json'), 'utf8'));
assert.equal(map.run.controller, 'argent');
assert.equal(map.run.environment.colorSchemes, undefined);
@@ -494,6 +515,150 @@ test('an Argent capture starts an argent session, drives it through the bridge,
assert.equal(execution.controllerPackageVersion, '0.29.0');
});
test('on an EAS iOS session with serve-sim\'s appearance.set, an Argent capture records every appearance', async t => {
const f = await fixture(t, { argent: true, userInterfaceStyle: 'automatic', controlActions: ['appearance.set'] });
const lines = [];
assert.equal((await runCiMap({ ...f.options, progress: line => lines.push(line) })).runStatus, 'complete');
assert.equal(lines.some(line => /Argent cannot switch appearance/.test(line)), false, lines.join('\n'));
assert.deepEqual(f.requests.filter(request => request.args[0] === 'simulator:control' && request.args[1] === 'appearance.set').map(request => request.args.at(-1)), ['light', 'dark']);
const map = JSON.parse(await readFile(join(f.options.outputDirectory, 'screen-map.json'), 'utf8'));
assert.deepEqual(map.run.environment.colorSchemes, ['light', 'dark']);
});
test('an EAS iOS session approves the app\'s link scheme after installing it and before any link opens', async t => {
for (const argent of [false, true]) {
const f = await fixture(t, { argent, controlActions: ['app.approveUrlScheme'] });
assert.equal((await runCiMap(f.options)).runStatus, 'complete');
const approve = f.requests.findIndex(request => request.args[0] === 'simulator:control' && request.args[1] === 'app.approveUrlScheme');
assert.ok(approve >= 0, argent ? 'Argent' : 'agent-device');
assert.deepEqual(f.requests[approve].args.slice(f.requests[approve].args.indexOf('--') + 1), ['com.example.app', 'sample']);
const controller = f.requests.map((request, index) => ({ request, index })).filter(({ request }) => request.command === 'fake-controller' || request.command.endsWith('/argent-controller'));
const install = controller.find(({ request }) => request.args[0] === 'install');
const firstLink = controller.find(({ request }) => request.args[0] === 'open' && request.args[2]?.startsWith('sample://'));
assert.ok(install.index < approve && approve < firstLink.index, 'installed, then approved, then the first link');
}
// A session whose serve-sim predates the action keeps the controllers' prompt handling, and is not asked.
const older = await fixture(t, { argent: true });
assert.equal((await runCiMap(older.options)).runStatus, 'complete');
assert.equal(older.requests.some(request => request.args[0] === 'simulator:control' && !request.args.includes('--list')), false);
});
test('when Argent cannot read the app after a fold on EAS, the capture resets its device helpers, then restarts SpringBoard, and never stops the tool-server', async t => {
const actions = ['springboard.restart'];
for (const [unreadable, completes, resets, restarts] of [[1, true, 1, 0], [2, true, 2, 1], [3, false, 2, 1]]) {
const f = await fixture(t, { argent: true, devicePose: 'open', unreadableAfterFold: unreadable, controlActions: actions });
const lines = [];
const run = runCiMap({ ...f.options, progress: line => lines.push(line), sleep: () => {} });
if (completes) assert.equal((await run).runStatus, 'complete', `${unreadable} unreadable opens`);
else await assert.rejects(run, error => JSON.stringify(error).includes('CONTROLLER_READER_STUCK'));
assert.equal(f.requests.filter(request => request.command.endsWith('/argent-controller') && request.args[0] === 'reset-reader').length, resets);
assert.equal(f.requests.filter(request => request.args[0] === 'simulator:control' && request.args[1] === 'springboard.restart').length, restarts);
assert.equal(f.requests.some(request => request.args.join(' ').includes('server stop')), false, 'the session\'s tool-server is never stopped');
assert.ok(lines.some(line => /resetting Argent's device helpers/.test(line)), lines.join('\n'));
}
// Without springboard.restart (an older serve-sim), a second unreadable open is reported after the reset alone.
const older = await fixture(t, { argent: true, devicePose: 'open', unreadableAfterFold: 2 });
await assert.rejects(runCiMap({ ...older.options, sleep: () => {} }), error => JSON.stringify(error).includes('CONTROLLER_READER_STUCK'));
});
test('when a fold on EAS leaves Argent reading the dark panel, the capture restarts SpringBoard and folds again, once', async t => {
for (const [unverified, completes] of [[1, true], [2, false]]) {
const f = await fixture(t, { argent: true, devicePose: 'open', foldUnverified: unverified, controlActions: ['springboard.restart'] });
const run = runCiMap({ ...f.options, sleep: () => {} });
if (completes) assert.equal((await run).runStatus, 'complete');
else await assert.rejects(run, error => JSON.stringify(error).includes('CONTROLLER_READER_STUCK'));
assert.equal(f.requests.filter(request => request.command.endsWith('/argent-controller') && request.args[0] === 'fold').length, 2);
assert.equal(f.requests.filter(request => request.args[0] === 'simulator:control' && request.args[1] === 'springboard.restart').length, 1);
}
});
test('a session EAS ends while starting is replaced by a new one, under a name of its own, up to five times with a growing wait', async t => {
const f = await fixture(t, { startsErrored: 1 });
const lines = []; const waits = [];
const result = await runCiMap({ ...f.options, progress: line => lines.push(line), sleep: ms => { waits.push(ms); } });
assert.equal(result.runStatus, 'complete');
const started = f.requests.filter(request => request.args[0] === 'simulator:start').map(request => value(request, '--name'));
assert.equal(started.length, 2);
assert.notEqual(started[0], started[1], 'the new session has a name of its own');
assert.ok(lines.some(line => /EAS ended simulator session session-1 \(ERRORED\) before it was ready; starting a new EAS Simulator session in 10 s \(1\/5\)/.test(line)), lines.join('\n'));
assert.equal(lines.filter(line => /while the app is repacked/.test(line)).length, 1, 'only the first start runs beside the repack');
assert.equal(result.simulatorSessionId, 'session-2');
assert.ok(waits.includes(10_000));
// Five new sessions at most, waiting 10 s, 20 s, 40 s, 80 s and 120 s before them; then the failure to start is reported as one.
const always = await fixture(t, { startsErrored: 6 });
const backoff = [];
await assert.rejects(runCiMap({ ...always.options, sleep: ms => { if (ms >= 10_000) backoff.push(ms); } }),
error => error.code === 'SIMULATOR_START_FAILED' && /6 sessions ended before they were ready \(the last, session-6, ERRORED\)/.test(error.message)
&& error.details.endedSessions.length === 6 && error.details.attempts === 6);
assert.equal(always.requests.filter(request => request.args[0] === 'simulator:start').length, 6);
assert.deepEqual(backoff, [10_000, 20_000, 40_000, 80_000, 120_000]);
assert.equal(new Set(always.requests.filter(request => request.args[0] === 'simulator:start').map(request => value(request, '--name'))).size, 6, 'every session has its own name');
// One session that ended is a failure to start too, not a question of ownership.
const once = await fixture(t, { startsErrored: 6 });
await assert.rejects(runCiMap({ ...once.options, sleep: () => {}, runner: request => {
if (request.args[0] === 'simulator:start' && once.requests.filter(r => r.args[0] === 'simulator:start').length >= 1) throw new Error('Controller simulator:start exited with status 1: quota exhausted');
return once.options.runner(request);
} }), error => error.code === 'SIMULATOR_START_FAILED');
});
test('new sessions stay within 30 minutes of the first failed start, each start capped by what is left', async t => {
const f = await fixture(t, { startsErrored: 6 });
let clock = Date.parse('2026-10-18T00:00:00Z');
const timeouts = [];
await assert.rejects(runCiMap({ ...f.options, now: () => clock, sleep: ms => { clock += ms; }, runner: request => {
// Each start takes 10 minutes before EAS ends the session.
if (request.args[0] === 'simulator:start') { timeouts.push(request.timeoutMs); clock += 10 * 60_000; }
return f.options.runner(request);
} }), error => error.code === 'SIMULATOR_START_FAILED');
// The budget runs from the first failure, at 10:00, to 40:00. The start at 10:10 fits whole; those at 20:30 and 31:10
// get only what is left (19:30, then 8:50); after 41:10 none starts.
assert.deepEqual(timeouts, [20 * 60_000, 20 * 60_000, 19.5 * 60_000, (8 * 60 + 50) * 1000]);
});
test('Ctrl+C while waiting for a new session stops the review instead of starting one', async t => {
const f = await fixture(t, { startsErrored: 6 });
const controller = new AbortController();
await assert.rejects(runCiMap({ ...f.options, signal: controller.signal, sleep: () => controller.abort(new Error('interrupted')) }));
assert.equal(f.requests.filter(request => request.args[0] === 'simulator:start').length, 1);
});
test('a start that fails before naming a session stops any session of that name first, then starts a new one', async t => {
const f = await fixture(t, { startsUnnamed: 1, orphanFromFailedStart: true });
assert.equal((await runCiMap({ ...f.options, sleep: () => {} })).runStatus, 'complete');
const order = f.requests.map(request => request.args[0] === 'simulator:stop' && value(request, '--id') === 'orphan-1' ? 'stop-orphan' : request.args[0] === 'simulator:start' ? 'start' : undefined).filter(Boolean);
assert.deepEqual(order, ['start', 'stop-orphan', 'start']);
// The last failed start is accounted for as well, though no new session follows it.
const always = await fixture(t, { startsUnnamed: 6, orphanFromFailedStart: true });
await assert.rejects(runCiMap({ ...always.options, sleep: () => {} }), error => error.code === 'SIMULATOR_START_FAILED');
assert.equal(always.requests.filter(request => request.args[0] === 'simulator:stop' && value(request, '--id') === 'orphan-1').length, 6);
});
test('a session of that name Explore cannot prove is its own is never stopped or replaced', async t => {
const f = await fixture(t, { startsUnnamed: 1, orphanFromFailedStart: true, orphanUnproven: true });
await assert.rejects(runCiMap({ ...f.options, sleep: () => {} }), error => error.code === 'SIMULATOR_START_FAILED');
assert.equal(f.requests.filter(request => request.args[0] === 'simulator:start').length, 1);
assert.equal(f.requests.some(request => request.args[0] === 'simulator:stop'), false);
});
test('a session Explore cannot prove is its own is never replaced, even one that ERRORED', async t => {
const f = await fixture(t, { wrongProject: true, startsErrored: 1 });
await assert.rejects(runCiMap(f.options), error => /SESSION_HANDOFF_UNVERIFIED/.test(JSON.stringify(error)));
assert.equal(f.requests.filter(request => request.args[0] === 'simulator:start').length, 1);
});
test('account failures to start are not retried; temporary ones and timeouts are', async t => {
for (const [message, retried] of [['GraphQL request failed: not authorized', false], ['quota exhausted', false], ['GraphQL request failed.', true], ['No simulator capacity for iPhone Duo', true]]) {
const f = await fixture(t);
let starts = 0;
const run = runCiMap({ ...f.options, sleep: () => {}, runner: request => {
if (request.args[0] === 'simulator:start' && ++starts === 1) { writeFileSync(join(request.cwd, '.env.eas-simulator'), HEADER); throw new Error(`Controller simulator:start exited with status 1: ${message}`); }
return f.options.runner(request);
} });
if (retried) assert.equal((await run).runStatus, 'complete', message); else await assert.rejects(run, error => error.code === 'SIMULATOR_START_FAILED', message);
assert.equal(starts, retried ? 2 : 1, message);
}
});
test('an Argent capture of an app pinned to dark is labelled dark and is not warned about', async t => {
const f = await fixture(t, { argent: true, userInterfaceStyle: 'dark' });
const lines = [];
@@ -503,29 +668,45 @@ test('an Argent capture of an app pinned to dark is labelled dark and is not war
assert.equal(execution.colorScheme, 'dark');
});
test('device.pose folds the device first, before the app is opened, read or captured', async t => {
for (const argent of [false, true]) {
const f = await fixture(t, { devicePose: 'open', argent });
assert.equal((await runCiMap(f.options)).runStatus, 'complete');
const controller = f.requests.filter(request => request.command === 'fake-controller' || request.command.endsWith('/argent-controller'));
const folds = controller.filter(request => request.args[0] === 'fold');
assert.equal(folds.length, 1);
assert.deepEqual(folds[0].args.slice(0, 2), ['fold', 'open']);
const foldAt = controller.indexOf(folds[0]);
// The fold comes first: the app is installed but not read or captured before it, so the controller starts on the lit panel.
// agent-device folds only inside a session, so one open (and nothing else) starts it; Argent folds without one.
assert.deepEqual(controller.slice(0, foldAt).map(request => request.args[0]).filter(command => command !== '--version' && command !== 'install'), argent ? [] : ['open']);
// Argent's bridge is told the pose, so it captures the opened panel's landscape UI upright.
if (argent) for (const request of controller) assert.equal(request.environment.EXPLORE_ARGENT_POSE, 'open');
}
test('device.pose with Argent folds the device first, before the app is opened, read or captured', async t => {
const f = await fixture(t, { devicePose: 'open', argent: true });
assert.equal((await runCiMap(f.options)).runStatus, 'complete');
const controller = f.requests.filter(request => request.command.endsWith('/argent-controller'));
const folds = controller.filter(request => request.args[0] === 'fold');
assert.equal(folds.length, 1);
assert.deepEqual(folds[0].args.slice(0, 2), ['fold', 'open']);
const foldAt = controller.indexOf(folds[0]);
// The fold comes first: the app is installed but not opened, read or captured before it, so the controller starts on the lit panel.
assert.deepEqual(controller.slice(0, foldAt).map(request => request.args[0]).filter(command => command !== '--version' && command !== 'install'), []);
// Argent's bridge is told the pose, so it captures the opened panel's landscape UI upright.
for (const request of controller) assert.equal(request.environment.EXPLORE_ARGENT_POSE, 'open');
});
test('on EAS Simulator a fold the controller cannot read back is confirmed by the lit display: portrait is closed, landscape is open', async t => {
const closed = await fixture(t, { devicePose: 'closed', foldUnverified: true });
assert.equal((await runCiMap(closed.options)).runStatus, 'complete');
assert.ok(closed.requests.some(request => request.args[0] === 'screenshot' && request.args[1].endsWith('pose.png')), 'the display is read after the unconfirmed fold');
const open = await fixture(t, { devicePose: 'open', foldUnverified: true });
await assert.rejects(runCiMap(open.options), error => error.code === 'CONTROLLER_FOLD_UNVERIFIED');
test('device.pose with agent-device on EAS opens the app, folds, and checks the display it lit', async t => {
const f = await fixture(t, { devicePose: 'open' });
assert.equal((await runCiMap({ ...f.options, sleep: () => {} })).runStatus, 'complete');
const controller = f.requests.filter(request => request.command === 'fake-controller').map(request => request.args[0] === 'screenshot' && request.args[1].endsWith('/pose.png') ? 'pose' : request.args[0]);
// agent-device folds only inside a session, so the app opens first; the fold's hinge readback is not trusted, the display is.
assert.deepEqual(controller.filter(command => command !== '--version' && command !== 'install').slice(0, 3), ['open', 'fold', 'pose']);
assert.equal(f.requests.some(request => request.args[0] === 'simulator:control' && request.args[1] === 'springboard.restart'), false);
});
test('when an agent-device fold on EAS lights a black panel, the capture restarts SpringBoard, reopens the app and folds again, once', async t => {
for (const [black, completes] of [[1, true], [2, false]]) {
const f = await fixture(t, { devicePose: 'open', blackAfterFold: black, controlActions: ['springboard.restart'] });
const lines = [];
const run = runCiMap({ ...f.options, sleep: () => {}, progress: line => lines.push(line) });
if (completes) assert.equal((await run).runStatus, 'complete');
else await assert.rejects(run, error => JSON.stringify(error).includes('CONTROLLER_READER_STUCK'));
const controller = f.requests.filter(request => request.command === 'fake-controller');
assert.equal(controller.filter(request => request.args[0] === 'fold').length, 2);
assert.ok(controller.some(request => request.args[0] === 'open' && request.args.includes('--relaunch')), 'the app is reopened after SpringBoard');
assert.equal(f.requests.filter(request => request.args[0] === 'simulator:control' && request.args[1] === 'springboard.restart').length, 1);
assert.ok(lines.some(line => /did not draw the open display after the fold; restarting SpringBoard/.test(line)), lines.join('\n'));
}
// Without springboard.restart (an older serve-sim), a black panel is reported at once.
const older = await fixture(t, { devicePose: 'open', blackAfterFold: 1 });
await assert.rejects(runCiMap({ ...older.options, sleep: () => {} }), error => JSON.stringify(error).includes('CONTROLLER_FOLD_UNVERIFIED'));
});
test('a local simulator capture creates its own iOS simulator, installs the repacked app there, and deletes the simulator', async t => {
@@ -3375,43 +3556,3 @@ test('a verified label is located on the image\'s axes when the screenshot is th
// A 669 x 951 portrait panel captured upright as a 951 x 669 image: the button near its bottom-left is near the image's top-left.
assert.deepEqual(verifiedCaptureLabels(nodes, ['Done'], { height: 951 })[0].rect, { x: 11, y: 10, width: 40, height: 100 });
});
const FAKE_ENGINE = new URL('../fixtures/flows/fake-engine.mjs', import.meta.url).pathname;
const FLOW_FILE = `import { test, expect } from "e2e";
test("home shows the balance", async ({ app, screen }) => {
await app.screenshot("home");
await screen.getByTestId("home-send").tap();
await expect(screen.getByRole("heading", "Your contacts")).toBeVisible();
await app.screenshot("contacts");
});
`;
test('flows mode runs the app\'s e2e files after the routes, hands the device over, and exports their frames with the map', async t => {
const f = await fixture(t, { flows: { tests: ['e2e/*.e2e.ts'], only: true }, flowFiles: { 'home.e2e.ts': FLOW_FILE }, environment: { EXPLORE_FLOWS_ENGINE_MODULE: FAKE_ENGINE } });
const result = await runCiMap(f.options);
const bundle = JSON.parse(await readFile(join(f.options.outputDirectory, 'bundle.json'), 'utf8'));
assert.equal(bundle.flowsFailure, undefined);
const flow = bundle.flows['home/home-shows-the-balance'];
assert.equal(flow.status, 'passed');
assert.deepEqual(Object.keys(flow.frames), ['home', 'contacts']);
for (const frame of Object.values(flow.frames)) {
const png = await readFile(join(f.options.outputDirectory, frame.path));
assert.equal(createHash('sha256').update(png).digest('hex'), frame.sha256, 'the exported frame is the one the flow took');
}
assert.deepEqual(Object.keys(bundle.images), [], 'flows mode captures no routes');
assert.deepEqual((await readdir(f.options.project)).filter(name => name.startsWith('.expo-explore')), [], "e2e's output leaves the app directory");
assert.ok(f.operations().lastIndexOf('close') < f.requests.findIndex(request => request.command === process.execPath), 'Explore closes its session before e2e opens the app');
assert.equal(result.runStatus, 'complete', 'no route was planned, so none is missing');
});
test('a flows worker that cannot start leaves a flows failure in the bundle instead of failing the capture', async t => {
const f = await fixture(t, { flows: { tests: ['e2e/*.e2e.ts'], only: true }, flowFiles: { 'home.e2e.ts': FLOW_FILE }, environment: { EXPLORE_FLOWS_ENGINE_MODULE: join(tmpdir(), 'missing-engine.mjs') } });
const lines = [];
await runCiMap({ ...f.options, progress: line => lines.push(line) });
const bundle = JSON.parse(await readFile(join(f.options.outputDirectory, 'bundle.json'), 'utf8'));
assert.equal(bundle.flows, undefined);
assert.equal(bundle.flowsFailure.code, 'FLOWS_NOT_RUN');
assert.match(bundle.flowsFailure.message, /missing-engine/);
assert.ok(lines.some(line => /the flows did not run: .*missing-engine/.test(line)), 'the capture log names the reason the flows did not run');
assert.deepEqual((await readdir(f.options.project)).filter(name => name.startsWith('.expo-explore')), []);
});
+1 -6
View File
@@ -1,6 +1,6 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
import { readFile, writeFile } from 'node:fs/promises';
import { join } from 'node:path';
import { runCompareCi } from '../../dist/ci/pipeline.js';
import { writeCaptureOutputs } from '../../dist/ci/workflow-steps.js';
@@ -16,10 +16,6 @@ test('any two commits: a capture and report like a pull request\'s, with no pull
await writeFile(comparePath, JSON.stringify({ origin: 'compare', repositoryId: '123', repository: 'acme/example',
base: { ref: 'v1.0.0', sha: f.baseSha }, head: { ref: 'v1.1.0', sha: f.headSha } }));
const output = join(f.root, 'compare');
// Another target's flows may be running in the same checkout: Explore's scratch directory is not a source change.
const scratch = join(f.baseProject, '.expo-explore-flows');
await mkdir(join(scratch, 'android-abc'), { recursive: true });
await writeFile(join(scratch, 'android-abc', 'frame.png'), 'png');
const result = await runCompareCi({ baseProject: f.baseProject, headProject: f.headProject, comparePath, output, config: f.config,
environment: { ...f.environment, GITHUB_TOKEN: '' }, runner: f.runner, now: f.now, sleep: f.sleep });
@@ -70,7 +66,6 @@ test('any two commits: a capture and report like a pull request\'s, with no pull
assert.match(summary, new RegExp(`\\(https://github\\.com/acme/example/compare/${f.baseSha}\\.\\.${f.headSha}\\)`));
assert.match(summary, /^- iOS.*: \d+ changes?$/m);
await rm(scratch, { recursive: true, force: true });
assert.equal(git(f.baseProject, 'status', '--porcelain'), '');
assert.equal(git(f.headProject, 'status', '--porcelain'), '');
assert.equal(f.requests.filter(request => request.args[0] === 'simulator:start').length,
+6 -22
View File
@@ -639,31 +639,15 @@ test("doctor checks each target where it runs: local tools for local targets, EA
targets: { phone: { platform: "ios" }, cloud: { platform: "ios", device: "iPhone 17 Pro", simulator: "eas", controller: "argent" } } });
assert.deepEqual(devices(mixed), ["iPhone 17"]);
assert.equal(check(mixed, "eas-simulator")[0].status, "pass");
// The target's Argent is reported as a top-level one would be.
assert.equal(check(mixed, "controller")[0].code, "CONTROLLER_APPEARANCE_FIXED");
// The target's Argent is reported as a top-level one would be: on an iOS EAS session the host switches its appearance.
assert.equal(check(mixed, "controller")[0].status, "pass");
// Only Argent on an Android EAS session records a single appearance.
const android = await doctor({ ...baseConfig, targets: { phone: { platform: "ios" },
droid: { platform: "android", device: "pixel_7", bundleId: "com.example.app", easProfile: "explore-android", controller: "argent" } } });
assert.equal(check(android, "controller")[0].code, "CONTROLLER_APPEARANCE_FIXED");
// --simulator and --controller decide for every target, as they do in a capture.
const forced = await doctor({ ...baseConfig, targets: { phone: { platform: "ios", simulator: "local", controller: "argent" } } }, { simulator: "eas", controller: "agent-device" });
assert.deepEqual(devices(forced), []);
assert.equal(check(forced, "eas-simulator")[0].status, "pass");
assert.deepEqual(check(forced, "controller"), []);
});
test("doctor checks that flows.tests names committed e2e files and that the app can import e2e", async (t) => {
const flows = { ...baseConfig, mode: "flows", flows: { tests: ["e2e/*.e2e.ts", "e2e/extra/checkout.e2e.ts"] } };
const root = await app(t, flows, { "e2e/home.e2e.ts": "import { test } from 'e2e';\ntest('home', async () => {});\n" });
const report = await runDoctor(offline(root));
const tests = check(report, "flows-tests")[0];
assert.equal(tests.status, "fail");
assert.equal(tests.code, "FLOWS_TESTS_MISSING");
assert.match(tests.message, /"e2e\/extra\/checkout\.e2e\.ts"/);
assert.doesNotMatch(tests.message, /e2e\/\*\.e2e\.ts/);
assert.equal(check(report, "flows-e2e")[0].code, "FLOWS_E2E_UNRESOLVED");
assert.equal(check(report, "flows-output").length, 0);
await write(root, { "e2e/extra/checkout.e2e.ts": "export {};\n", "node_modules/e2e/package.json": JSON.stringify({ name: "e2e", version: "0.21.2" }), ".expo-explore-flows/keep": "" });
const ready = await runDoctor(offline(root));
assert.equal(check(ready, "flows-tests")[0].status, "pass");
assert.match(check(ready, "flows-tests")[0].message, /2 e2e test files/);
assert.match(check(ready, "flows-e2e")[0].message, /e2e 0\.21\.2/);
assert.equal(check(ready, "flows-output")[0].code, "FLOWS_OUTPUT_EXISTS");
});
+1 -1
View File
@@ -130,7 +130,7 @@ function runtimeFor(side, map, expectedSamples = 3, capturedSamples = expectedSa
observationId: observation.id,
expectedSampleCount: expectedSamples,
controllerPackageVersion: "0.20.2",
easCliVersion: "25.0.0",
easCliVersion: "25.2.0",
},
runtime: {
kind: "eas-agent-device-raw",
+9 -41
View File
@@ -191,6 +191,15 @@ test("report.preview opts into hosted previews with a bounded expiry and an opti
assert.throws(() => validateExploreConfig({ ...base(), report: { hosting: "eas" } }), /report/);
});
test("report.comment.map opts the PR comment into its map of changed screens, beside or without a hosted preview", () => {
assert.deepEqual(validateExploreConfig({ ...base(), report: { comment: { map: true } } }).report, { comment: { map: true } });
assert.deepEqual(validateExploreConfig({ ...base(), report: { comment: { map: false }, preview: { hosting: "eas" } } }).report,
{ comment: { map: false }, preview: { hosting: "eas", expiresAfterDays: 30 } });
for (const comment of [{}, { map: "yes" }, { map: true, graph: true }, true]) {
assert.throws(() => validateExploreConfig({ ...base(), report: { comment } }), /Invalid .expo-explore\/config.yaml: report.comment/);
}
});
test("platforms: a flat config is iOS-only and resolves to itself", () => {
const config = validateExploreConfig(base());
assert.deepEqual(configPlatforms(config), ["ios"]);
@@ -354,44 +363,3 @@ test("a target can choose its own controller and simulator over capture's", () =
assert.deepEqual(["duo", "android", "cloud"].map(id => captureRepack(resolveTargetConfig(config, { target: id }))), ["local", "local", "eas"]);
assert.throws(() => validateExploreConfig({ ...base(), targets: { duo: { platform: "ios", controller: "maestro" } } }), error => error.code === "CONFIG_INVALID");
});
test("flows: the app's e2e tests run in flows mode or beside deterministic routes, never with the agent", () => {
const flows = validateExploreConfig({ ...base(), mode: "flows", flows: { tests: ["flows/*.e2e.ts", "e2e/checkout.e2e.ts"] } });
assert.equal(flows.mode, "flows");
assert.deepEqual(flows.flows, { tests: ["flows/*.e2e.ts", "e2e/checkout.e2e.ts"] });
assert.deepEqual(validateExploreConfig({ ...base(), flows: { tests: "e2e/**/*.e2e.ts" } }).flows, { tests: ["e2e/**/*.e2e.ts"] });
assert.deepEqual(validateExploreConfig({ ...base(), flows: { tests: "e2e/a.e2e.ts", frames: "steps" } }).flows, { frames: "steps", tests: ["e2e/a.e2e.ts"] });
assert.deepEqual(validateExploreConfig({ ...base(), flows: { tests: "e2e/a.e2e.ts", frames: "checkpoints" } }).flows, { tests: ["e2e/a.e2e.ts"] }, "checkpoints is the default and is not kept");
assert.throws(() => validateExploreConfig({ ...base(), flows: { tests: "e2e/a.e2e.ts", frames: "all" } }), /flows\.frames must be "checkpoints"/);
assert.throws(() => validateExploreConfig({ ...base(), mode: "flows" }), /flows.tests is required in flows mode/);
assert.throws(() => validateExploreConfig({ ...base(), mode: "agent", agent: { provider: "openai", model: "m", instructions: "x.md" }, flows: { tests: ["a.e2e.ts"] } }), /cannot be combined with agent mode/);
assert.throws(() => validateExploreConfig({ ...base(), flows: { tests: ["../outside.e2e.ts"] } }), /inside the app directory/);
assert.throws(() => validateExploreConfig({ ...base(), flows: { tests: [], extra: 1 } }), /flows/);
});
test("--flows runs the named e2e files as the whole capture, in flows mode, and is validated", () => {
const plain = validateExploreConfig(base());
const flows = withRunOverrides(plain, { flows: ["e2e/checkout.e2e.ts", " e2e/sign-up/*.e2e.ts "] });
assert.equal(flows.mode, "flows");
assert.deepEqual(flows.flows, { tests: ["e2e/checkout.e2e.ts", "e2e/sign-up/*.e2e.ts"] });
assert.deepEqual(withRunOverrides(plain, {}), plain);
assert.throws(() => withRunOverrides(plain, { flows: [" "] }), error => error.code === "CONFIG_INVALID");
assert.throws(() => withRunOverrides(plain, { flows: ["../other/app.e2e.ts"] }), error => error.code === "CONFIG_INVALID");
assert.throws(() => withRunOverrides(validateExploreConfig({ ...base(), mode: "agent" }), { flows: ["e2e/a.e2e.ts"] }), error => error.code === "CONFIG_INVALID");
});
test("a target or platform runs its own flows over the top-level list; agent mode takes none", () => {
const shared = { tests: ["e2e/*.e2e.ts"] };
const targets = validateExploreConfig({ ...base(), flows: shared, targets: {
phone: { platform: "ios" },
fold: { platform: "ios", device: "iPhone Duo", flows: { tests: ["e2e/fold/*.e2e.ts"] } } } });
assert.deepEqual(resolveTargetConfig(targets, { target: "phone" }).flows, shared);
assert.deepEqual(resolveTargetConfig(targets, { target: "fold" }).flows, { tests: ["e2e/fold/*.e2e.ts"] });
const platforms = validateExploreConfig({ ...base(), mode: "flows", flows: shared, platforms: {
ios: {}, android: { bundleId: "com.example.app", easProfile: "explore", flows: { tests: ["e2e/android/*.e2e.ts"] } } } });
assert.deepEqual(resolvePlatformConfig(platforms, "ios").flows, shared);
assert.deepEqual(resolvePlatformConfig(platforms, "android").flows, { tests: ["e2e/android/*.e2e.ts"] });
assert.throws(() => validateExploreConfig({ ...base(), targets: { fold: { platform: "ios", flows: { tests: ["../e2e/x.e2e.ts"] } } } }), error => error.code === "CONFIG_INVALID");
assert.throws(() => validateExploreConfig({ ...base(), mode: "agent", agent: { provider: "openai", model: "gpt-5" }, targets: { fold: { platform: "ios", flows: shared } } }),
error => error.code === "CONFIG_INVALID" && /agent mode/.test(error.message));
});
-28
View File
@@ -1,28 +0,0 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import { createRequire } from 'node:module';
import { contentSha256 } from '../../dist/shared/png-evidence.js';
const { PNG } = createRequire(import.meta.url)('pngjs');
function frame(width, height, paint) {
const png = new PNG({ width, height });
for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) {
const [r, g, b] = paint(x, y); const i = (y * width + x) * 4;
png.data[i] = r; png.data[i + 1] = g; png.data[i + 2] = b; png.data[i + 3] = 255;
}
return PNG.sync.write(png);
}
test('contentSha256 ignores the status-bar and home-indicator bands and sees everything between them', () => {
const bands = { top: 6.5, bottom: 3 };
const body = (x, y) => [x % 256, y % 256, 40];
const base = frame(60, 200, body);
const clockTicked = frame(60, 200, (x, y) => (y < 10 ? [255, 255, 255] : body(x, y)));
const indicatorInverted = frame(60, 200, (x, y) => (y >= 196 ? [0, 0, 0] : body(x, y)));
const contentChanged = frame(60, 200, (x, y) => (y === 100 && x === 30 ? [9, 9, 9] : body(x, y)));
assert.equal(contentSha256(clockTicked, bands), contentSha256(base, bands), 'a change inside the top band does not count');
assert.equal(contentSha256(indicatorInverted, bands), contentSha256(base, bands), 'a change inside the bottom band does not count');
assert.notEqual(contentSha256(contentChanged, bands), contentSha256(base, bands), 'one pixel between the bands does');
assert.notEqual(contentSha256(base, bands), contentSha256(base, { top: 0, bottom: 0 }), 'the hashed region is part of the hash');
assert.match(contentSha256(base, bands), /^[a-f0-9]{64}$/);
});
-38
View File
@@ -1,38 +0,0 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import { mkdtemp, readFile, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { settledScreenshot } from '../../dist/capture/flows/worker.js';
function fakeDevice(frames) {
const shots = [];
return { shots, client: { capture: { async screenshot({ path }) { const frame = frames[Math.min(shots.length, frames.length - 1)]; shots.push(frame); await writeFile(path, frame); } } } };
}
test('a step frame is shot again until two shots agree, and the last shot is kept', async () => {
const dir = await mkdtemp(join(tmpdir(), 'explore-settled-'));
const pauses = [];
const sleep = async ms => { pauses.push(ms); };
const settling = fakeDevice(['easing-1', 'easing-2', 'settled', 'settled']);
const file = join(dir, 'a.png');
assert.deepEqual(await settledScreenshot(settling.client, file, { sleep, pauseMs: 150 }), { tries: 4, settled: true });
assert.equal(settling.shots.length, 4, 'three re-shots after the first');
assert.deepEqual(pauses, [150, 150, 150]);
assert.equal(await readFile(file, 'utf8'), 'settled');
const still = fakeDevice(['same']);
assert.deepEqual(await settledScreenshot(still.client, join(dir, 'b.png'), { sleep }), { tries: 2, settled: true }, 'a still screen costs one re-shot');
const restless = fakeDevice(['1', '2', '3', '4', '5', '6']);
const result = await settledScreenshot(restless.client, join(dir, 'c.png'), { sleep, tries: 3 });
assert.deepEqual(result, { tries: 3, settled: false }, 'bounded: an animating screen is kept after the last try');
assert.equal(await readFile(join(dir, 'c.png'), 'utf8'), '3');
const closing = fakeDevice(['x', 'y', 'z']);
let open = true;
const stopAfterFirstPause = async ms => { pauses.push(ms); open = false; };
assert.deepEqual(await settledScreenshot(closing.client, join(dir, 'd.png'), { sleep: stopAfterFirstPause, more: () => open }), { tries: 1, settled: false },
'once the device is going away the shot in hand is kept instead of asking for another');
assert.equal(closing.shots.length, 1);
});
-87
View File
@@ -1,87 +0,0 @@
import assert from "node:assert/strict";
import { readFileSync } from "node:fs";
import test from "node:test";
import { tsImport } from "tsx/esm/api";
const { summarizeFlowReport, flowId, flowSlug } = await tsImport("../../src/capture/flows/report.ts", import.meta.url);
const report = JSON.parse(readFileSync(new URL("../fixtures/flows/e2e-report.json", import.meta.url), "utf8"));
test("summarizes the selected tests of an e2e report with their steps and screenshot frames", () => {
const tests = summarizeFlowReport(report);
assert.equal(tests.length, 1, "unselected files stay out");
const [flow] = tests;
assert.equal(flow.id, "send/send-money-reaches-contacts");
assert.equal(flow.status, "passed");
assert.equal(flow.file, "tests/send.e2e.ts");
assert.deepEqual(flow.steps.map(step => [step.api, step.label, step.status, step.frame]), [
["app.screenshot", "home", "passed", "home"],
["locator.tap", 'getByTestId("home-send")', "passed", undefined],
["expect.toBeVisible", 'getByRole("heading", name: "Your contacts")', "passed", undefined],
["app.screenshot", "contacts", "passed", "contacts"],
]);
assert.deepEqual(flow.frames.map(frame => [frame.key, frame.path, frame.stepIndex]), [
["home", "send-money-reaches-contacts-09af3c698e01af96/attempt-1/screenshots/001.png", 0],
["contacts", "send-money-reaches-contacts-09af3c698e01af96/attempt-1/screenshots/002.png", 3],
]);
assert.ok(Number.isFinite(Date.parse(flow.frames[0].capturedAt)));
});
test("flow ids and frame keys are stable path segments", () => {
assert.equal(flowId("tests/checkout/Pay now.e2e.ts", ["Checkout", "pays with the test card"]), "checkout-pay-now/checkout-pays-with-the-test-card");
assert.equal(flowId("e2e/onboarding.e2e.ts", ["signs up"]), "onboarding/signs-up");
assert.equal(flowSlug(" Review — step 2! "), "review-step-2");
assert.equal(flowSlug("***"), "flow");
});
test("a failed flow keeps the frames it took and names the failing step", () => {
const failed = structuredClone(report);
const result = failed.run.results.find(entry => entry.selected);
result.status = "failed";
const attempt = result.attempts[0];
attempt.status = "failed";
attempt.error = { code: "LOCATOR_NOT_FOUND", message: "no element matches getByText(\"Alex Rivera\")" };
attempt.steps = [...attempt.steps.slice(0, 2), { ...attempt.steps[1], index: 2, api: "locator.tap", label: 'getByText("Alex Rivera")', status: "failed", artifacts: [],
error: { code: "LOCATOR_NOT_FOUND", message: "no element matches" } }];
const [flow] = summarizeFlowReport(failed);
assert.equal(flow.status, "failed");
assert.equal(flow.error.code, "LOCATOR_NOT_FOUND");
assert.deepEqual(flow.frames.map(frame => frame.key), ["home"]);
assert.equal(flow.steps[2].status, "failed");
assert.equal(flow.steps[2].error.code, "LOCATOR_NOT_FOUND");
});
test("repeated screenshot labels get distinct frame keys", () => {
const twice = structuredClone(report);
const attempt = twice.run.results.find(entry => entry.selected).attempts[0];
attempt.steps[3] = { ...attempt.steps[3], label: "home" };
const [flow] = summarizeFlowReport(twice);
assert.deepEqual(flow.frames.map(frame => frame.key), ["home", "home-2"]);
});
test("steps and tests carry the e2e source line of the test file", async () => {
const summaries = summarizeFlowReport(JSON.parse(readFileSync(new URL("../fixtures/flows/e2e-report.json", import.meta.url), "utf8")));
const send = summaries.find(summary => summary.file === "tests/send.e2e.ts");
assert.equal(send.steps[0].line, 3);
assert.equal(send.steps[1].line, 4);
assert.ok(send.line === undefined || send.line > 0);
});
test("per-step frames fill the steps that took no frame of their own, keyed by step number", () => {
const selected = report.run.results.find(result => result.selected !== false);
const stepFrames = new Map([[selected.testId, [
{ stepIndex: 1, path: "explore-step-frames/a-1.png", capturedAt: "2026-01-01T00:00:01.000Z" },
{ stepIndex: 0, path: "explore-step-frames/a-0.png", capturedAt: "2026-01-01T00:00:00.000Z" },
{ stepIndex: 2, path: "explore-step-frames/a-2.png", capturedAt: "2026-01-01T00:00:02.000Z" },
{ stepIndex: 9, path: "explore-step-frames/a-9.png", capturedAt: "2026-01-01T00:00:09.000Z" },
]]]);
const [flow] = summarizeFlowReport(report, stepFrames);
assert.deepEqual(flow.steps.map(step => step.frame), ["home", "step-2", "step-3", "contacts"], "a screenshot step keeps its own frame; a step past the end is ignored");
assert.deepEqual(flow.frames.map(frame => [frame.key, frame.stepIndex, frame.path]), [
["home", 0, flow.frames[0].path],
["step-2", 1, "explore-step-frames/a-1.png"],
["step-3", 2, "explore-step-frames/a-2.png"],
["contacts", 3, flow.frames[3].path],
], "frames come out in step order");
assert.equal(flow.frames[1].label, '2. getByTestId("home-send")');
assert.deepEqual(summarizeFlowReport(report, new Map([["other-test", [{ stepIndex: 1, path: "x.png", capturedAt: "" }]]]))[0].frames.length, 2, "frames of another test are not attached");
});
-81
View File
@@ -1,81 +0,0 @@
import assert from "node:assert/strict";
import { mkdtemp, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { fileURLToPath } from "node:url";
import test from "node:test";
import { runFlows, flowFramePath } from "../../dist/capture/flows/run-flows.js";
import { defaultRunner } from "../../dist/capture/controller.js";
const engineModule = fileURLToPath(new URL("../fixtures/flows/fake-engine.mjs", import.meta.url));
const repo = fileURLToPath(new URL("../../", import.meta.url));
async function project(files) {
const root = await mkdtemp(join(tmpdir(), "explore-flows-"));
const app = join(root, "app");
await mkdir(join(app, "e2e"), { recursive: true });
// The app resolves `e2e` the way a real app does: from its own node_modules.
await mkdir(join(app, "node_modules"), { recursive: true });
const { symlink } = await import("node:fs/promises");
await symlink(join(repo, "node_modules", "e2e"), join(app, "node_modules", "e2e"), "dir");
for (const [name, source] of Object.entries(files)) await writeFile(join(app, "e2e", name), source);
return { root, app, work: join(root, "work"), output: join(root, "bundle") };
}
const run = async (files, options = {}) => {
const paths = await project(files);
await mkdir(paths.work, { recursive: true });
await mkdir(paths.output, { recursive: true });
const progress = [];
const result = await runFlows({ project: paths.app, tests: Object.keys(files).map(name => `e2e/${name}`), platform: "ios", bundleId: "com.example.app",
stateDir: join(paths.work, "state"), workDirectory: paths.work, outputDirectory: paths.output, runner: defaultRunner, environment: { ...process.env },
timeoutMs: 60_000, progress: message => progress.push(message), engineModule, ...options });
return { ...paths, result, progress };
};
test("runs e2e flows through the worker and keeps every app.screenshot as a bundle frame", async () => {
const { result, output, root } = await run({ "send.e2e.ts": `import { test, expect } from "e2e";
test("send money reaches contacts", async ({ app, screen }) => {
await app.screenshot("home");
await screen.getByTestId("home-send").tap();
await expect(screen.getByRole("heading", "Your contacts")).toBeVisible();
await app.screenshot("contacts");
});
` });
try {
assert.equal(result.failure, undefined);
assert.deepEqual((await readdir(join(root, "app"))).filter(name => name.startsWith(".expo-explore")), [], "e2e's output leaves the app directory");
const flow = result.flows["send/send-money-reaches-contacts"];
assert.ok(flow, Object.keys(result.flows).join(","));
assert.equal(flow.status, "passed");
assert.deepEqual(flow.steps.map(step => [step.api, step.status, step.frame]),
[["app.screenshot", "passed", "home"], ["locator.tap", "passed", undefined], ["expect.toBeVisible", "passed", undefined], ["app.screenshot", "passed", "contacts"]]);
assert.deepEqual(Object.keys(flow.frames), ["home", "contacts"]);
for (const [key, frame] of Object.entries(flow.frames)) {
assert.equal(frame.path, flowFramePath("send/send-money-reaches-contacts", key));
assert.deepEqual([frame.width, frame.height], [1, 1]);
const bytes = await readFile(join(output, frame.path));
assert.equal(bytes.length > 0, true);
assert.match(frame.sha256, /^[a-f0-9]{64}$/);
}
} finally { await rm(root, { recursive: true, force: true }); }
});
test("a failing flow keeps the frames before the failure and reports the failing step; the capture goes on", async () => {
const { result, root } = await run({ "broken.e2e.ts": `import { test, expect } from "e2e";
test("taps a contact that is not there", async ({ app, screen }) => {
await app.screenshot("home");
await screen.getByTestId("home-send").tap();
await screen.getByText("Nobody Here").tap();
await app.screenshot("never");
});
` });
try {
assert.equal(result.failure, undefined);
const flow = result.flows["broken/taps-a-contact-that-is-not-there"];
assert.equal(flow.status, "failed");
assert.deepEqual(Object.keys(flow.frames), ["home"]);
assert.equal(flow.steps[2].status, "failed");
assert.ok(flow.error?.code, JSON.stringify(flow));
} finally { await rm(root, { recursive: true, force: true }); }
});
+28
View File
@@ -0,0 +1,28 @@
import assert from "node:assert/strict";
import test from "node:test";
const { tsImport } = await import("tsx/esm/api");
const { heldKeyHint, shortcutModifiers } = await tsImport("../../viewer/src/utils/held-modifiers.ts", import.meta.url);
const { SHORTCUTS } = await tsImport("../../viewer/src/utils/shortcuts.ts", import.meta.url);
const held = (keys) => ({ shift: false, ctrl: false, meta: false, alt: false, ...keys });
test("holding a chord's modifiers shows the key that completes it; anything else shows nothing", () => {
assert.equal(heldKeyHint(SHORTCUTS.canvasByNumber.map, held({ ctrl: true }), true), "1");
assert.equal(heldKeyHint(SHORTCUTS.canvasByNumber.compare, held({ ctrl: true }), true), "3");
assert.equal(heldKeyHint(SHORTCUTS.camera.fit, held({ shift: true }), true), "1");
assert.equal(heldKeyHint(SHORTCUTS.appearance.app, held({ shift: true }), true), "T");
assert.equal(heldKeyHint(SHORTCUTS.canvasByNumber.map, held({ shift: true }), true), undefined, "the wrong modifier");
assert.equal(heldKeyHint(SHORTCUTS.canvasByNumber.map, held({ ctrl: true, shift: true }), true), undefined, "an extra modifier");
assert.equal(heldKeyHint(SHORTCUTS.canvas.map, held({ ctrl: true }), true), undefined, "a plain key has no chord");
assert.equal(heldKeyHint(SHORTCUTS.canvasByNumber.map, held({}), true), undefined, "nothing held");
});
test("mod is ⌘ on Apple keyboards and Ctrl elsewhere", () => {
assert.equal(heldKeyHint(SHORTCUTS.app.search, held({ meta: true }), true), "K");
assert.equal(heldKeyHint(SHORTCUTS.app.search, held({ ctrl: true }), true), undefined);
assert.equal(heldKeyHint(SHORTCUTS.app.search, held({ ctrl: true }), false), "K");
assert.equal(heldKeyHint(SHORTCUTS.app.search, held({ meta: true }), false), undefined);
assert.deepEqual(shortcutModifiers(SHORTCUTS.app.search, true), held({ meta: true }));
assert.deepEqual(shortcutModifiers(SHORTCUTS.app.search, false), held({ ctrl: true }));
});
+68 -1
View File
@@ -2,7 +2,7 @@ import assert from "node:assert/strict";
import test from "node:test";
const { tsImport } = await import("tsx/esm/api");
const { HOLD_INITIAL_DELAY_MS, HOLD_FIRST_INTERVAL_MS, HOLD_FLOOR_INTERVAL_MS, holdIntervalMs, holdSchedule } =
const { HOLD_INITIAL_DELAY_MS, HOLD_FIRST_INTERVAL_MS, HOLD_FLOOR_INTERVAL_MS, createKeyHold, glideRate, holdIntervalMs, holdSchedule } =
await tsImport("../../viewer/src/utils/key-hold.ts", import.meta.url);
test("a held paging key waits, then steps sooner and sooner down to a floor", () => {
@@ -16,3 +16,70 @@ test("a held paging key waits, then steps sooner and sooner down to a floor", ()
assert.ok(schedule.at(-1) < 2000, "six held steps fit in two seconds");
assert.ok(HOLD_INITIAL_DELAY_MS > HOLD_FIRST_INTERVAL_MS, "the hold begins slower than it repeats");
});
test("a held key steps on the schedule from its first step, and ends when a step finds nothing", (t) => {
t.mock.timers.enable({ apis: ["setTimeout"] });
const hold = createKeyHold();
let steps = 0;
hold.begin("ArrowRight", () => (steps += 1) < 3);
assert.ok(hold.holding("ArrowRight"));
assert.ok(!hold.holding("ArrowLeft"));
t.mock.timers.tick(HOLD_INITIAL_DELAY_MS - 1);
assert.equal(steps, 0, "nothing before the initial delay");
t.mock.timers.tick(1);
assert.equal(steps, 1, "the second step lands after the initial delay");
t.mock.timers.tick(holdIntervalMs(1));
assert.equal(steps, 2);
t.mock.timers.tick(holdIntervalMs(2));
assert.equal(steps, 3, "the third attempt finds nothing");
assert.ok(!hold.holding("ArrowRight"), "and the hold ends by itself");
t.mock.timers.tick(10_000);
assert.equal(steps, 3, "no further steps");
});
test("ending a hold, or beginning another key, stops the first", (t) => {
t.mock.timers.enable({ apis: ["setTimeout"] });
const hold = createKeyHold();
let right = 0;
let left = 0;
hold.begin("ArrowRight", () => { right += 1; return true; });
t.mock.timers.tick(HOLD_INITIAL_DELAY_MS);
assert.equal(right, 1);
hold.begin("ArrowLeft", () => { left += 1; return true; });
assert.ok(!hold.holding("ArrowRight"));
assert.ok(hold.holding("ArrowLeft"));
// Mock timers run one scheduled round per tick; a hold schedules the next step from each step.
t.mock.timers.tick(HOLD_INITIAL_DELAY_MS);
t.mock.timers.tick(holdIntervalMs(1));
assert.equal(right, 1, "the first key stopped stepping");
assert.equal(left, 2);
hold.end();
assert.ok(!hold.holding("ArrowLeft"));
t.mock.timers.tick(holdIntervalMs(2));
t.mock.timers.tick(1000);
assert.equal(left, 2);
});
test("another key ends a hold, as the OS's own repeat stops; its own repeats and a modifier do not", () => {
const key = (code, key = code, repeat = false) => ({ code, key, repeat });
const hold = createKeyHold();
hold.begin("ArrowDown", () => true);
hold.interrupt(key("ArrowDown", "ArrowDown", true));
hold.interrupt(key("ShiftLeft", "Shift"));
hold.interrupt(key("MetaLeft", "Meta"));
assert.ok(hold.holding("ArrowDown"), "its own repeat and a modifier leave it held");
hold.interrupt(key("Escape"));
assert.ok(!hold.holding("ArrowDown"), "Esc ends it");
hold.begin("ArrowDown", () => true);
hold.interrupt(key("KeyK", "k"));
assert.ok(!hold.holding("ArrowDown"), "so does the K of ⌘K");
hold.end();
});
test("a glide picks up from rest, then eases from the stepped hold's first speed up to its top speed", () => {
assert.equal(glideRate(0), 0, "it starts at rest, where the tap's step ended");
assert.ok(Math.abs(glideRate(80) - 1000 / HOLD_FIRST_INTERVAL_MS) < 0.2, "within a few frames it moves a step per first interval");
for (let at = 10; at <= 1200; at += 10) assert.ok(glideRate(at) >= glideRate(at - 10), `never slows, at ${at}ms`);
assert.equal(glideRate(1000), 1000 / HOLD_FLOOR_INTERVAL_MS, "after a second, a step per floor interval");
assert.equal(glideRate(5000), glideRate(1000), "and no faster");
});
+9 -1
View File
@@ -2,7 +2,7 @@ import assert from "node:assert/strict";
import test from "node:test";
const { tsImport } = await import("tsx/esm/api");
const { mapKeyDirection, mapKeyTarget } = await tsImport("../../viewer/src/utils/map-keyboard.ts", import.meta.url);
const { mapKeyDirection, mapKeyEntry, mapKeyTarget } = await tsImport("../../viewer/src/utils/map-keyboard.ts", import.meta.url);
// A top-to-bottom map: root fans out to a, b, c on one rank; b leads on to d; e is a stray rank with no edges.
// root
@@ -100,3 +100,11 @@ test("a left-to-right map needs no special case: the keys read positions", () =>
assert.equal(mapKeyTarget(rotated, "a", "down"), "b");
assert.equal(mapKeyTarget(rotated, "c", "up"), "b");
});
test("with nothing selected, an arrow enters the map at the edge it moves away from, as Screens' arrows do", () => {
assert.equal(mapKeyEntry(structure, "down"), "root", "down starts at the top");
assert.equal(mapKeyEntry(structure, "up"), "d", "up starts at the bottom; the leftmost of that rank");
assert.equal(mapKeyEntry(structure, "right"), "a", "right starts at the left edge");
assert.equal(mapKeyEntry(structure, "left"), "e", "left starts at the right edge");
assert.equal(mapKeyEntry({ positions: new Map() }, "down"), undefined, "an empty map has no entry");
});
+2 -3
View File
@@ -196,10 +196,9 @@ test("a screen without a route, or one the map does not know yet, travels as an
test("legacy hashes still parse", () => {
assert.deepEqual(parse("/#workspace"), base);
assert.deepEqual(parse("/#workspace/screens"), { ...base, canvas: "screens" });
// The hash-era Flows canvas was retired; its links land on the map. The path form is the
// current Flows view (the app sends it to the map when the review ran no flows).
// Flows was retired; its links land on the map.
assert.deepEqual(parse("/#workspace/flows"), base);
assert.deepEqual(parse("/flows?flow=derived-apps"), { ...base, canvas: "flows" });
assert.deepEqual(parse("/flows?flow=derived-apps"), base);
assert.deepEqual(parse("/#workspace/graph"), base);
assert.deepEqual(parse("/map?panel=workspace"), base);
assert.equal(nav.formatRoute(parse("/map?panel=workspace"), ctx), "/map");
-41
View File
@@ -357,44 +357,3 @@ test('a head that gained a dark appearance reviews <id>@dark with its own digest
assert.equal(secondary.headOutcome.status, 'captured');
assert.equal(secondary.headImage.url, `https://embedded.expo-explore.invalid/${darkSha}.png`);
});
test('a flows failure is published per side and validated as a code and a bounded message', async t => {
const f = await captureFixture(t);
const result = await prepareCaptureReview({ ...f.options });
const failure = { code: 'FLOWS_NOT_RUN', message: 'The e2e worker wrote no result.' };
assertPublicReview({ ...result.review, flowsFailure: { head: failure } });
assertPublicReview({ ...result.review, flowsFailure: { base: failure, head: failure } });
for (const invalid of [{}, { head: {} }, { head: { code: 1, message: 'x' } }, { head: { ...failure, extra: true } }, { other: failure }, { head: { ...failure, message: 'x'.repeat(4_001) } }]) {
assert.throws(() => assertPublicReview({ ...result.review, flowsFailure: invalid }), /Public flows failure is invalid/);
}
});
test('flow frames are report assets: the review names them by hash and the local report carries their bytes', async t => {
const f = await captureFixture(t);
// A second PNG, distinct from the route frame.
const frameImage = new PNG({ width: 1, height: 1 }); frameImage.data = Buffer.from([12, 34, 56, 255]);
const framePng = PNG.sync.write(frameImage);
const frameSha = createHash('sha256').update(framePng).digest('hex');
const headDirectory = f.options.headDirectory;
await mkdir(join(headDirectory, 'flows', 'home', 'home-opens'), { recursive: true });
await writeFile(join(headDirectory, 'flows', 'home', 'home-opens', 'home.png'), framePng);
const darkImage = new PNG({ width: 1, height: 1 }); darkImage.data = Buffer.from([1, 2, 3, 255]);
const darkPng = PNG.sync.write(darkImage); const darkSha = createHash('sha256').update(darkPng).digest('hex');
await writeFile(join(headDirectory, 'flows', 'home', 'home-opens', '[email protected]'), darkPng);
const head = { ...f.bundles.head, runtimeProfile: { ...f.bundles.head.runtimeProfile, colorSchemes: 'light,dark' }, flows: { 'home/home-opens': { file: 'e2e/home.e2e.ts', title: 'home opens', status: 'passed', durationMs: 12,
steps: [{ api: 'app.screenshot', label: 'home', status: 'passed', durationMs: 3, frame: 'home' }],
frames: { home: { path: 'flows/home/home-opens/home.png', sha256: frameSha, width: 1, height: 1, capturedAt: '2026-09-08T00:00:01Z' },
'home@dark': { path: 'flows/home/home-opens/[email protected]', sha256: darkSha, width: 1, height: 1, capturedAt: '2026-09-08T00:00:02Z' } } } } };
await writeFile(join(headDirectory, 'bundle.json'), JSON.stringify(head));
const result = await prepareCaptureReview({ ...f.options });
assertPublicReview(result.review);
const flow = result.review.flows[0];
assert.equal(flow.id, 'home/home-opens');
assert.match(flow.head.frames.home.url, new RegExp(`${frameSha}\\.png$`));
assert.deepEqual(result.assets.filter(asset => asset.sha256 === frameSha).map(asset => asset.path), [join(headDirectory, 'flows', 'home', 'home-opens', 'home.png')]);
// A second appearance's frame is its own surface, `<key>@<scheme>`, carrying the scheme; the primary frame carries none.
assert.deepEqual(flow.frames.map(frame => [frame.key, frame.id, frame.colorScheme]),
[['home', 'flow:home/home-opens/home', undefined], ['home@dark', 'flow:home/home-opens/home@dark', 'dark']]);
assert.match(flow.head.frames['home@dark'].url, new RegExp(`${darkSha}\\.png$`));
assert.equal(result.assets.filter(asset => asset.sha256 === darkSha).length, 1);
});
+4 -1
View File
@@ -31,8 +31,10 @@ for (const provider of ['expo-router', 'react-navigation']) {
const before = f.requests.length;
const output = join(f.root, 'review');
const result = await runPublicCi({ baseProject: f.baseProject, headProject: f.headProject, pullRequestPath: f.pullRequestPath, output,
config: f.config, environment: { ...f.environment, EXPLORE_CAPTURE_CACHE: baseline.directory }, transport: f.transport, runner: f.runner, now: f.now, sleep: f.sleep });
config: { ...f.config, report: { comment: { map: true } } }, environment: { ...f.environment, EXPLORE_CAPTURE_CACHE: baseline.directory },
transport: f.transport, runner: f.runner, now: f.now, sleep: f.sleep });
const plan = JSON.parse(await readFile(join(output, 'execution-plan.json'), 'utf8'));
assert.equal(JSON.parse(await readFile(result.inputPath, 'utf8')).commentState.map, true, 'report.comment.map reaches the comment the publish job renders');
assert.equal(result.review.contract, 'explore.review');
assert.equal(result.review.runtime.appVersion, '3.0.0', 'the Viewer header shows the captured app version');
assert.equal(result.review.runtime.appBuildNumber, '7', 'the Viewer header shows the captured build number');
@@ -122,6 +124,7 @@ test('unreachable screens do not fail CI: both revisions, the report and an Inco
.map(line => line.replace('(home)', `(${result.review.surfaces.find(surface => surface.head?.route === '/home')?.id})`)).sort());
assert.ok(progress.includes('2 screens are unavailable in this report'));
const reportInput = JSON.parse(await readFile(join(output, 'report-input.json'), 'utf8'));
assert.equal(reportInput.commentState.map, undefined, 'the comment draws no map unless the config asks for one');
assert.equal(reportInput.publicReview.surfaces.filter(surface => surface.headOutcome && surface.headOutcome.status !== 'captured').length, 0);
assert.equal(reportInput.publicReview.surfaces.filter(surface => surface.headOutcome?.landing === 'unverified' && surface.headImage).length, 1);
assert.equal(reportInput.publicReview.surfaces.filter(surface => surface.baseOutcome && surface.baseOutcome.status !== 'captured').length, 1);
+53 -8
View File
@@ -60,7 +60,7 @@ function state(overrides = {}) {
phase: 'ready', pullRequest, mode: 'changes', executionMode: 'deterministic', configPath: '.expo-explore/config.yaml', links,
startedAt: Date.parse('2026-09-11T03:00:48Z'), updatedAt: Date.parse('2026-09-11T03:07:00Z'),
build: { appName: 'Example', appVersion: '1.4.0', appBuildNumber: '27', platform: 'ios', easProfile: 'explore', easBuildId: 'eas-build', reusedEasBuild: true },
runtime: { provider: 'eas-simulator', controller: 'agent-device', controllerPackageVersion: '0.20.2', easCliVersion: '25.0.0', platform: 'ios', deviceModel: 'iPhone 17', osVersion: '26.5', locale: 'en-US', orientation: 'portrait', colorScheme: 'light', sessionLifecycle: 'stopped' },
runtime: { provider: 'eas-simulator', controller: 'agent-device', controllerPackageVersion: '0.20.2', easCliVersion: '25.2.0', platform: 'ios', deviceModel: 'iPhone 17', osVersion: '26.5', locale: 'en-US', orientation: 'portrait', colorScheme: 'light', sessionLifecycle: 'stopped' },
capture: { planned: { base: 3, head: 3 }, done: { base: 3, head: 3 }, baseFromCache: true },
review: evidenceReview(),
evidence: {
@@ -589,11 +589,56 @@ test('a comment written by a per-platform version keeps parsing, and malformed t
assert.equal(parse(...many).length, 8, 'a comment holds at most one record per configurable target');
});
test('a side whose flows did not run is named with e2e\'s reason, ahead of the flow lines', () => {
const flowsFailure = { head: { code: 'FLOWS_NOT_RUN', message: 'Cannot find module "e2e/runner"' } };
const body = renderPublicComment(reviewOnlyState({ ...review([surface('home', 'unchanged')]), flowsFailure }));
assert.match(visible(body), /Flows did not run on head: Cannot find module "e2e\/runner"\./);
const both = renderPublicComment(reviewOnlyState({ ...review([surface('home', 'unchanged')]), flowsFailure: { ...flowsFailure, base: { code: 'FLOWS_NOT_RUN', message: 'timed out' } } }));
assert.match(visible(both), /Flows did not run on head: Cannot find module/);
assert.match(visible(both), /Flows did not run on base: timed out\./);
test('with report.comment.map, the map draws the added, removed and visually changed screens, the screens one step before them, and tabs as a group', async () => {
const { readCommentRecords } = await import('../../dist/report/pr-comment-body.js');
const edge = (from, to, kind) => ({ from, to, kind, sourceFile: 'src/app/_layout.tsx', provenance: 'source' });
const graph = edges => ({ contract: 'explore.navigation', edges, modalSurfaceIds: [], unresolved: [] });
const base = evidenceReview();
const dark = surface('settings@dark', 'modified', { route: '/settings', extra: base.surfaces[2].review && { review: base.surfaces[2].review, visual: base.surfaces[2].visual } });
const withNavigation = { ...base, surfaces: [...base.surfaces, dark], navigation: {
// home is a redirect, not a screen; cats and settings are tabs; cats changed only in source, so it is drawn as the way to care-guide.
head: graph([edge('cats', 'care-guide', 'push'), edge('cats', 'settings', 'tab'), edge('settings', 'cats', 'tab'), edge('home', 'cats', 'replace')]),
base: graph([edge('cats', 'sweet-bee', 'push'), edge('cats', 'settings', 'tab')]),
} };
// Off by default: most reviews do not need it, so a config opts in with report.comment.map.
assert.ok(!/<summary>Map/.test(renderPublicComment(state({ artifactOnly: true, review: withNavigation }))));
assert.equal(platformRecordOf(state({ review: withNavigation })).navigation, undefined);
const body = renderPublicComment(state({ artifactOnly: true, map: true, review: withNavigation }));
assert.deepEqual(summaries(body), ['🟩 Added (1)', '🟥 Removed (1)', '🟧 Modified (2)', 'Map (4 screens)', 'Validation · iOS 🟩 8/8 captured']);
const map = body.slice(body.indexOf('```mermaid'), body.indexOf('```\n', body.indexOf('```mermaid')) + 3);
assert.equal(map, ['```mermaid', 'flowchart LR', ' subgraph tabs["Tabs"]', ' n0["/cats"]', ' n3["/settings"]', ' end',
' n1["/cats/care-guide"]', ' n2["/cats/sweet-bee"]', ' n0 -->|push| n1', ' n0 -.->|push| n2',
' classDef added stroke:#1a7f37,stroke-width:3px', ' class n1 added', ' classDef modified stroke:#bc4c00,stroke-width:3px', ' class n3 modified',
' classDef removed stroke:#cf222e,stroke-width:2px,stroke-dasharray:5 4', ' class n2 removed', '```'].join('\n'));
assert.ok(body.indexOf('<summary>🟧 Modified') < body.indexOf('<summary>Map') && body.indexOf('<summary>Map') < body.indexOf('<summary>Validation'));
assert.match(body, /<summary>Map \(4 screens\)<\/summary>\n\n```mermaid\n/, 'a blank line opens the fence inside the collapsible');
assert.deepEqual(readCommentRecords(body).current.ios.navigation, platformRecordOf(state({ map: true, review: withNavigation })).navigation, 'the map is carried in the record');
// A label cannot end itself, its line or the fence.
const odd = { ...withNavigation, surfaces: withNavigation.surfaces.map(entry => entry.id === 'care-guide'
? { ...entry, head: { ...entry.head, logicalPath: 'cats/"a"#<b>`c`' } } : entry) };
assert.match(renderPublicComment(state({ map: true, review: odd })), /\n {2}n1\["\/cats\/#quot;a#quot;#35;#lt;b#gt;#96;c#96;"\]\n/);
// No navigation, or nothing changed visually: no map.
assert.ok(!summaries(renderPublicComment(state({ map: true }))).includes('Map (4 screens)'));
const unchanged = { ...withNavigation, surfaces: withNavigation.surfaces.filter(entry => entry.status !== 'added' && entry.status !== 'removed' && !entry.id.startsWith('settings')) };
assert.ok(!/<summary>Map/.test(renderPublicComment(state({ map: true, review: unchanged }))));
});
test('the map is dropped before the change lists shrink, and a malformed map is dropped from the record', async () => {
const { encodeRecordPayload } = await import('../../dist/report/pr-comment-record.js');
const { readCommentRecords, renderCommentRecords } = await import('../../dist/report/pr-comment-body.js');
const record = { ...platformRecordOf(state()), navigation: { nodes: [{ route: '/a', group: 'modified' }, { route: '/b' }], edges: [{ from: 1, to: 0, kinds: ['push'] }] } };
const records = { current: { ios: record }, history: [] };
assert.match(renderCommentRecords(records), /<summary>Map \(2 screens\)<\/summary>/);
const tight = renderCommentRecords(records, undefined, renderCommentRecords(records).length - 1);
assert.ok(!tight.includes('```mermaid'));
assert.match(tight, /<summary>🟧 Modified \(1\)<\/summary>/);
const parse = navigation => readCommentRecords(`<!-- expo-explore-record:ios:${encodeRecordPayload({ ...record, navigation })} -->`).current.ios;
assert.deepEqual(parse(record.navigation).navigation, record.navigation);
for (const navigation of [{ ...record.navigation, edges: [{ from: 0, to: 2, kinds: ['push'] }] }, { ...record.navigation, edges: [{ from: 0, to: 1, kinds: ['teleport'] }] },
{ ...record.navigation, nodes: [{ route: '/a', group: 'needs-review' }, { route: '/b' }] }, { nodes: [], edges: [] }]) {
const parsed = parse(navigation);
assert.ok(parsed, 'the rest of the record still parses');
assert.equal(parsed.navigation, undefined);
}
});
+1 -1
View File
@@ -13,7 +13,7 @@ const BASE_SHA = "a".repeat(40);
const HEAD_SHA = "b".repeat(40);
const PNG = Buffer.from("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=", "base64");
const EXECUTION = {
provider: "eas-simulator", controller: "agent-device", controllerPackageVersion: AGENT_DEVICE_VERSION, easCliVersion: "25.0.0",
provider: "eas-simulator", controller: "agent-device", controllerPackageVersion: AGENT_DEVICE_VERSION, easCliVersion: "25.2.0",
platform: "ios", deviceModel: "iPhone 17", osVersion: "26.0", locale: "en-US", orientation: "portrait",
colorScheme: "light", sessionLifecycle: "stopped",
};
+2 -2
View File
@@ -16,7 +16,7 @@ function execution(overrides = {}) {
provider: "eas-simulator",
controller: "agent-device",
controllerPackageVersion: AGENT_DEVICE_VERSION,
easCliVersion: "25.0.0",
easCliVersion: "25.2.0",
platform: "ios",
deviceModel: "iPhone 17",
osVersion: "26.0",
@@ -189,7 +189,7 @@ test("projects one map surface into the five runtime evidence groups", () => {
assert.equal(result.groups.interaction.transitionCount.value, 1);
assert.equal(result.groups.ui.landmarks.value.length, 0);
assert.equal(result.groups.environment.controllerPackageVersion?.value, AGENT_DEVICE_VERSION);
assert.equal(result.groups.environment.easCliVersion?.value, "25.0.0");
assert.equal(result.groups.environment.easCliVersion?.value, "25.2.0");
});
test("normalizes multi-line labels and treats only open parser gaps as truncation", () => {
-15
View File
@@ -209,18 +209,3 @@ test("in a black-box tree, a screen with screens opened from it folds under its
assert.deepEqual(shape.screensUnder.get("screen:seq"), ["new"]);
assert.deepEqual(shape.ancestors.get("new"), ["screen:seq"]);
});
test("flow frames stay out of the Screens tree in both modes: the Flows view shows them, the Map draws their chain", () => {
const screens = [
screen("home", "Home", 0, { route: "/" }),
screen("flow:send-money/contacts", "Send money › contacts", 1, { route: "send-money", state: "contacts" }),
screen("removed:aaaaaaaa:screen:flow:send-money/review", "Send money › review", 2, { route: "send-money", state: "review" }),
];
const routeFiles = new Map([["home", "src/app/index.tsx"]]);
for (const tree of [screenTree(screens, indexMap(map({ screens })), routeFiles), screenTree(screens, indexMap(map({ screens })))]) {
const listed = tree.sections.flatMap((section) => section.screenIds);
assert.deepEqual(listed.filter((id) => id.includes("flow:")), []);
assert.deepEqual(treeScreenOrder(tree).filter((id) => id.includes("flow:")), []);
assert.ok(listed.includes("home"));
}
});
+40
View File
@@ -0,0 +1,40 @@
import assert from "node:assert/strict";
import test from "node:test";
import { tsImport } from "tsx/esm/api";
const { approveSessionUrlSchemes, simulatorControl, simulatorControlActions } = await tsImport("../../src/capture/simulator-control.ts", import.meta.url);
function easFake(listed) {
const calls = [];
const eas = (args, options) => {
calls.push({ args, options });
if (args.includes("--list")) { if (listed instanceof Error) throw listed; return { stdout: listed }; }
return { stdout: "{}" };
};
return { calls, eas };
}
test("a session's control actions come from --list, by session id; an older session or CLI has none", () => {
const { calls, eas } = easFake(JSON.stringify({ "appearance.set": {}, "springboard.restart": {} }));
assert.deepEqual([...simulatorControlActions(eas, "session-1")], ["appearance.set", "springboard.restart"]);
assert.deepEqual(calls[0].args, ["simulator:control", "--list", "--id", "session-1", "--json", "--non-interactive"]);
assert.equal(calls[0].options.allowFailure, true);
assert.equal(simulatorControlActions(easFake("Unknown command simulator:control").eas, "session-1").size, 0);
assert.equal(simulatorControlActions(easFake(new Error("eas exited 1")).eas, "session-1").size, 0);
});
test("an action's values follow --, so one that starts with a dash is never read as a flag", () => {
const { calls, eas } = easFake("{}");
simulatorControl(eas, "session-1", "clipboard.write", ["--not-a-flag"]);
assert.deepEqual(calls[0].args, ["simulator:control", "clipboard.write", "--id", "session-1", "--json", "--non-interactive", "--", "--not-a-flag"]);
});
test("link schemes are approved once each, lowercased, never http or https, and only when the session offers it", () => {
const { calls, eas } = easFake("{}");
const approved = approveSessionUrlSchemes(eas, "session-1", new Set(["app.approveUrlScheme"]), "dev.example.app", ["Example", "example", "https", "exp+example", "not a scheme"]);
assert.deepEqual(approved, ["example", "exp+example"]);
assert.deepEqual(calls.map(call => call.args.slice(-2)), [["dev.example.app", "example"], ["dev.example.app", "exp+example"]]);
const none = easFake("{}");
assert.deepEqual(approveSessionUrlSchemes(none.eas, "session-1", new Set(), "dev.example.app", ["example"]), []);
assert.equal(none.calls.length, 0);
});
+18 -23
View File
@@ -17,7 +17,6 @@ import { MapView } from "./components/views/semantic-map";
import { RightPanel } from "./components/panels/right";
import { SearchCommand } from "./components/search-command";
import { ScreensView } from "./components/views/screens";
import { FlowsView } from "./components/views/flows";
import { publicReviewProjection, publicReviewToWorkspace } from "./public/public-workspace";
import type { PublicReview } from "../../src/contracts/capture";
import {
@@ -28,7 +27,7 @@ import {
type ViewerBuild,
type ViewerWorkspace,
} from "./utils/build-diff";
import { type ViewerPayload, artifactUrl, isFlowScreen } from "./utils/model";
import { type ViewerPayload, artifactUrl } from "./utils/model";
import {
canonicalRoute,
formatRoute,
@@ -307,6 +306,8 @@ function ViewerApp() {
const [mapProjectionFitKey, setMapProjectionFitKey] = useState(0);
// A report captured in several appearances shows one at a time; the primary (first captured) is the default.
const [appearanceChoice, setAppearanceChoice] = useState<Appearance | undefined>();
// For the ⇧T shortcut, which steps to the next captured appearance; set once they are known.
const appearanceRef = useRef<{ options: readonly Appearance[]; current: Appearance | undefined }>({ options: [], current: undefined });
const [handoffOpen, setHandoffOpen] = useState(false);
/** Whether this page can hand the report off (a hosted preview); the A key reads it. */
const handoffAvailableRef = useRef(false);
@@ -372,6 +373,10 @@ function ViewerApp() {
const toggleTheme = useCallback(() => {
setThemePreference(current => current === "system" ? "dark" : current === "dark" ? "light" : "system");
}, []);
// The T key flips what is on screen, dark to light and back; only the button returns to Auto.
const flipTheme = useCallback(() => {
setThemePreference(current => (current === "system" ? preferredSystemTheme : current) === "dark" ? "light" : "dark");
}, [preferredSystemTheme]);
const load = useCallback(async (silent = false) => {
void silent;
@@ -995,6 +1000,14 @@ function ViewerApp() {
if (matchesShortcut(event, SHORTCUTS.app.handoff)) {
if (!handoffAvailableRef.current) return;
setHandoffOpen(true);
} else if (matchesShortcut(event, SHORTCUTS.appearance.theme)) {
flipTheme();
} else if (matchesShortcut(event, SHORTCUTS.appearance.app)) {
// Only a report captured in both schemes has another appearance to show.
const { options, current } = appearanceRef.current;
if (options.length < 2) return;
const index = current ? options.indexOf(current) : -1;
setAppearanceChoice(options[(index + 1) % options.length]);
} else if (matchesShortcut(event, SHORTCUTS.app.changes)) {
setChangesOpen((open) => !open);
} else if (matchesShortcut(event, SHORTCUTS.panel.right)) {
@@ -1010,7 +1023,7 @@ function ViewerApp() {
return () => {
window.removeEventListener("keydown", onKeyDown);
};
}, [clearSelectedScreen, navigate, searchOpen, selectCanvas, toggleRightPanel]);
}, [clearSelectedScreen, flipTheme, navigate, searchOpen, selectCanvas, toggleRightPanel]);
// A side-panel row or a deep link is a "go to": the camera fits that screen and the step is
// kept. Screens inventory clicks only select in place; Map clicks also focus the chosen screen. Repeating a selected target refits it without adding history.
@@ -1103,6 +1116,7 @@ function ViewerApp() {
const baseline = builds.find((build) => build.id === route.baseline);
const appearances = useMemo(() => appearanceOptions(payload?.map), [payload]);
const appearance = appearanceChoice && appearances.includes(appearanceChoice) ? appearanceChoice : appearances[0];
appearanceRef.current = { options: appearances, current: appearance };
const appearanceMap = useMemo(() => payload ? filterMapAppearance(payload.map, appearance) : undefined, [appearance, payload]);
const currentMap = useMemo(() => (
appearanceMap && workspace && currentBuild
@@ -1184,16 +1198,6 @@ function ViewerApp() {
? { ...presentedMap, run: { ...presentedMap.run, name: workspace.catalog.name } }
: presentedMap
), [presentedMap, workspace]);
const hasFlows = (Array.isArray(loadedPublicReview?.flows) && loadedPublicReview!.flows!.length > 0) || loadedPublicReview?.flowsFailure !== undefined;
// A flows-only review has no routes: the Map and Screens would be empty, so the Flows view is the home.
// A flows review: every screen is a flow frame, or the capture took no route frame on either side (flows mode lists the routes without capturing them).
const flowsOnly = hasFlows && ((map !== undefined && map.screens.length > 0 && map.screens.every((screen) => isFlowScreen(screen)))
|| (loadedPublicReview?.surfaces ?? []).every((surface) => isFlowScreen(surface) || (!surface.baseImage && !surface.headImage)));
useEffect(() => {
if (flowsOnly && (route.canvas === "map" || route.canvas === "screens")) navigate({ canvas: "flows" }, { replace: true });
// A Flows link into a review that ran none (or an old link to the retired canvas) lands on the map.
if (loadedPublicReview && !hasFlows && route.canvas === "flows") navigate({ canvas: "map" }, { replace: true });
}, [flowsOnly, hasFlows, loadedPublicReview, route.canvas, navigate]);
// Focus singles out diff states, so it means nothing without a baseline to diff against.
const focusFilter = diff ? route.focus : [];
const focusCounts = useMemo(() => countFocusStatuses(diff), [diff]);
@@ -1539,9 +1543,6 @@ function ViewerApp() {
<CanvasVisibleFrameProvider
layoutKey={`${rightCollapsed}:${route.canvas}:${route.inspect}`}>
<div className="canvas-view-content" data-canvas-view={route.canvas}>
{route.canvas === "flows" && loadedPublicReview ? (
<FlowsView review={loadedPublicReview} phone={phone} onOpenFrame={(id) => openChangedScreen(id)} />
) : null}
{route.canvas === "screens" ? (
<ScreensView
map={map}
@@ -1614,16 +1615,11 @@ function ViewerApp() {
<PhoneTabBar
canvas={route.canvas}
compareCount={compareOrder.length}
hasFlows={hasFlows}
flowsOnly={flowsOnly}
onSelectCanvas={selectCanvas}
/>
) : <CanvasToolbar
canvas={route.canvas}
searchOpen={searchOpen}
compareCount={compareOrder.length}
hasFlows={hasFlows}
flowsOnly={flowsOnly}
{...(handoffAction ? { actions: handoffAction } : {})}
onOpenShortcuts={() => setShortcutsOpen(true)}
onSelectCanvas={selectCanvas}
@@ -1632,7 +1628,7 @@ function ViewerApp() {
</CanvasVisibleFrameProvider>
{shortcutsOpen ? (
<ShortcutsDialog
context={{ canvas: route.canvas, review: reviewingInSidebar, hasChanges: compareOrder.length > 0, handoff: Boolean(handoffInput) }}
context={{ canvas: route.canvas, review: reviewingInSidebar, hasChanges: compareOrder.length > 0, handoff: Boolean(handoffInput), appearances: appearances.length > 1 }}
onClose={() => setShortcutsOpen(false)}
/>
) : null}
@@ -1660,7 +1656,6 @@ function ViewerApp() {
onSelectScreen={goToScreenKeepingView}
onOpenCompare={compareOrder.length > 0 ? () => selectCanvas("compare") : undefined}
review={compareOrder.length > 0 ? { order: compareOrder, onSelectScreen: openChangedScreen } : undefined}
flowReview={loadedPublicReview ?? undefined}
/>}
{error && payload && (
<button className="sync-warning" onClick={() => void load()}>
@@ -3,6 +3,7 @@ import { Fullscreen, LocateFixed } from "lucide-react";
import { runCanvasZoomCommand } from "../../utils/canvas-zoom";
import { useCanvasZoom } from "../../hooks/use-canvas-zoom";
import { formatShortcut, SHORTCUTS } from "../../utils/shortcuts";
import { KeyHint } from "../shared/key-hint";
import { Menu, type MenuItem } from "../shared/menu";
import { Tooltip } from "../shared/tooltip";
import { FullscreenToggleButton, ThemeToggleButton, type ShellActionsProps, type ShellTheme } from "../panels/shell-actions";
@@ -86,6 +87,7 @@ function FitControl() {
disabled={!camera}
onClick={() => runCanvasZoomCommand(camera?.hasSelection() ? "selection" : "fit")}>
<Fullscreen aria-hidden="true" />
<KeyHint shortcut={SHORTCUTS.camera.fit} />
</button>
</Tooltip>
);
@@ -105,6 +107,7 @@ function RecenterControl() {
disabled={!camera}
onClick={() => runCanvasZoomCommand("recenter")}>
<LocateFixed aria-hidden="true" />
<KeyHint shortcut={SHORTCUTS.camera.center} />
</button>
</Tooltip>
);
+6 -15
View File
@@ -1,8 +1,9 @@
import { GitCompareArrows, Keyboard, LayoutGrid, Map, Search, ListOrdered } from "lucide-react";
import { GitCompareArrows, Keyboard, LayoutGrid, Map, Search } from "lucide-react";
import { type CSSProperties } from "react";
import { Tooltip } from "../shared/tooltip";
import { useCanvasVisibleFrame } from "./visible-frame-provider";
import { formatShortcut, SHORTCUTS } from "../../utils/shortcuts";
import { CANVAS_NUMBER_KEYS, formatShortcut, SHORTCUTS } from "../../utils/shortcuts";
import { KeyHint } from "../shared/key-hint";
import {
CANVAS_DESCRIPTIONS,
CANVAS_LABELS,
@@ -14,21 +15,13 @@ const VIEW_ICONS: Record<CanvasView, React.ReactNode> = {
map: <Map />,
screens: <LayoutGrid />,
compare: <GitCompareArrows />,
flows: <ListOrdered />,
};
const TOOLBAR_MINIMUM_FRAME_WIDTH = 220;
type CanvasToolbarProps = {
/** True when the review ran flows: the Flows view is offered. */
hasFlows?: boolean;
/** True when the review captured flows and no routes: Map and Screens have nothing to show. */
flowsOnly?: boolean;
canvas: CanvasView;
searchOpen: boolean;
/** How many changed screens Compare holds, shown as a badge on its button. Compare's own header
steps through them. */
compareCount?: number;
/** Page-wide actions beside Search (Hand off to AI). */
actions?: React.ReactNode;
onSelectCanvas: (canvas: CanvasView) => void;
@@ -46,8 +39,7 @@ export function CanvasToolbar(props: CanvasToolbarProps) {
const style = visibleFrame ? ({
"--canvas-visible-bottom-inset": `calc(100% - ${visibleFrame.y + visibleFrame.height}px)`,
} as CSSProperties) : undefined;
// The Flows view exists only for a review that ran flows.
const views = CANVAS_VIEW_ORDER.filter((id) => (id !== "flows" || props.hasFlows) && !(props.flowsOnly && (id === "map" || id === "screens")));
const views = CANVAS_VIEW_ORDER;
return (
<div className="canvas-toolbar" role="toolbar" aria-label="Canvas tools" style={style}>
@@ -66,6 +58,7 @@ export function CanvasToolbar(props: CanvasToolbarProps) {
aria-expanded={props.searchOpen}
onClick={props.onOpenSearch}>
<Search />
<KeyHint shortcut={SHORTCUTS.app.search} />
</button>
</Tooltip>
{props.actions}
@@ -94,9 +87,7 @@ export function CanvasToolbar(props: CanvasToolbarProps) {
onClick={() => props.onSelectCanvas(id)}>
{VIEW_ICONS[id]}
<span className="toolbar-view-label" aria-hidden="true"><span>{CANVAS_LABELS[id]}</span></span>
{id === "compare" && props.compareCount ? (
<span className="toolbar-badge" aria-hidden="true">{props.compareCount}</span>
) : null}
{CANVAS_NUMBER_KEYS ? <KeyHint shortcut={SHORTCUTS.canvasByNumber[id]} /> : null}
</button>
</Tooltip>
);
+60 -3
View File
@@ -3,6 +3,7 @@ import { useReactFlow, useStore } from "@xyflow/react";
import { publishZoom, registerZoomApi, runCanvasZoomCommand } from "../../utils/canvas-zoom";
import { isTyping, matchesShortcut, SHORTCUTS } from "../../utils/shortcuts";
import { useCanvasVisibleFrame } from "./visible-frame-provider";
import { createKeyHold, glideWhileHeld, type KeyHold } from "../../utils/key-hold";
import {
canvasBoundsViewport,
canvasPriorityProjectionBounds,
@@ -15,6 +16,8 @@ import {
} from "./camera";
const DURATION = 160;
/** React Flow's zoomIn/zoomOut step, which a tap of + or − takes. */
const KEY_ZOOM_STEP = 1.2;
const PIXEL_WHEEL_ZOOM_RATE = 0.002;
const LINE_WHEEL_ZOOM_RATE = 0.05;
const PAGE_WHEEL_ZOOM_RATE = 1;
@@ -36,6 +39,12 @@ function canvasOwnsKeyboardEvent(event: KeyboardEvent, canvas: HTMLElement): boo
return focusOwned || canvas.matches(":hover");
}
function plainZoomDirection(event: KeyboardEvent): 1 | -1 | undefined {
if (event.key === "+" || event.key === "=") return 1;
if (event.key === "-" || event.key === "_") return -1;
return undefined;
}
function modifiedZoomCommand(event: KeyboardEvent): "in" | "out" | "100" | undefined {
if (event.code === "Equal" || event.code === "NumpadAdd") return "in";
if (event.code === "Minus" || event.code === "NumpadSubtract") return "out";
@@ -60,6 +69,12 @@ export function ZoomBridge(props: {
fitMaxZoom?: number;
}) {
const { visibleFrame } = useCanvasVisibleFrame();
// Outlives the effect below, which re-runs as the camera moves: a held key must not end just
// because its own zoom step re-registered the listeners.
const holdRef = useRef<KeyHold>(undefined);
holdRef.current ??= createKeyHold();
const hold = holdRef.current;
useEffect(() => () => hold.end(), [hold]);
const {
zoomIn,
zoomOut,
@@ -201,8 +216,37 @@ export function ZoomBridge(props: {
};
registerZoomApi(api);
// A tap of + or − takes one eased step. Held, the OS key repeat is ignored (each repeat
// restarting the easing made holding slower than tapping); once the tap's step has landed the
// camera glides instead, frame by frame about the pane's centre, as zoomIn does, until the key
// is released, the hold is interrupted, or the zoom reaches its limit.
const zoomStep = (direction: 1 | -1): boolean => {
const viewport = getViewport();
const next = Math.min(maxZoom, Math.max(minZoom, viewport.zoom * KEY_ZOOM_STEP ** direction));
if (next === viewport.zoom) return false;
if (direction === 1) void zoomIn({ duration: DURATION });
else void zoomOut({ duration: DURATION });
return true;
};
const zoomGlide = (direction: 1 | -1) => (steps: number): boolean => {
const viewport = getViewport();
const zoom = Math.min(maxZoom, Math.max(minZoom, viewport.zoom * KEY_ZOOM_STEP ** (direction * steps)));
if (zoom === viewport.zoom) return false;
const scale = zoom / viewport.zoom;
const centerX = canvasWidth / 2;
const centerY = canvasHeight / 2;
void setViewport({ zoom, x: centerX - (centerX - viewport.x) * scale, y: centerY - (centerY - viewport.y) * scale });
return true;
};
const onKeyDown = (event: KeyboardEvent) => {
hold.interrupt(event);
// Typing comes first: a held key's repeats belong to a field that took focus mid-hold.
if (isTyping(event.target)) return;
if (event.repeat && hold.holding(event.code)) {
event.preventDefault();
return;
}
// Browser zoom and canvas zoom use the same familiar chord. The pointer/focus boundary
// decides who owns it: canvas-owned events reset its camera; a focused panel or field keeps
@@ -225,10 +269,18 @@ export function ZoomBridge(props: {
event.preventDefault();
return;
}
if (event.key === "+" || event.key === "=") runCanvasZoomCommand("in");
else if (event.key === "-" || event.key === "_") runCanvasZoomCommand("out");
else return;
const direction = plainZoomDirection(event);
if (!direction) return;
event.preventDefault();
onCameraGestureStart.current?.();
if (!zoomStep(direction)) return;
// The hold only tracks the key (released, interrupted, a field or dialog taking over); the
// glide reads it every frame and stops with it.
hold.begin(event.code, () => true);
glideWhileHeld(hold, event.code, DURATION, zoomGlide(direction));
};
const onKeyUp = (event: KeyboardEvent) => {
if (hold.holding(event.code)) hold.end();
};
const onModifierWheel = (event: WheelEvent) => {
@@ -292,9 +344,13 @@ export function ZoomBridge(props: {
};
window.addEventListener("keydown", onKeyDown);
window.addEventListener("keyup", onKeyUp);
window.addEventListener("blur", hold.end);
canvas?.addEventListener("wheel", onModifierWheel, { capture: true, passive: false });
return () => {
window.removeEventListener("keydown", onKeyDown);
window.removeEventListener("keyup", onKeyUp);
window.removeEventListener("blur", hold.end);
canvas?.removeEventListener("wheel", onModifierWheel, { capture: true });
if (wheelFrame.current !== undefined) cancelAnimationFrame(wheelFrame.current);
wheelFrame.current = undefined;
@@ -308,6 +364,7 @@ export function ZoomBridge(props: {
getNodes,
getNodesBounds,
getViewport,
hold,
maxZoom,
minZoom,
props.fitPadding,
@@ -5,6 +5,7 @@ import { StatusGlyph } from "../shared/status-icon";
import { Tooltip } from "../shared/tooltip";
import { DIFF_LABELS, type DiffStatus } from "../../utils/build-diff";
import { formatShortcut, SHORTCUTS } from "../../utils/shortcuts";
import { KeyHint } from "../shared/key-hint";
import { setMeasurementsShown, useMeasurementsShown } from "../../utils/measurements-setting";
/** A screen whose every changed area only moved: how far, per direction, and whether no other finding remains. */
@@ -48,6 +49,7 @@ export function CompareNav(props: {
<StatusGlyph status={props.status} accessibilityOnly={props.accessibilityOnly} label={props.statusLabel ?? DIFF_LABELS[props.status]} />
{/* A route that does not fit loses its start, not the end that names the screen. */}
<code className="compare-nav-route" title={props.title}><bdi>{props.route}</bdi></code>
<KeyHint shortcut={SHORTCUTS.app.changes} />
</button>
</Tooltip>
{props.stepsApart ? null : <CompareSteps {...props} />}
@@ -6,7 +6,7 @@ import type { MapIndex } from "../../utils/model";
import type { ChangedScreen } from "../../utils/changed-screens";
import { groupVisualRegions, layoutShiftSummary, type VisualChange } from "../../utils/visual-diff";
import { formatShortcut, matchesShortcut, SHORTCUTS, shortcutsLive } from "../../utils/shortcuts";
import { HOLD_INITIAL_DELAY_MS, holdIntervalMs } from "../../utils/key-hold";
import { createKeyHold, glideWhileHeld, HOLD_INITIAL_DELAY_MS, type KeyHold } from "../../utils/key-hold";
import { optionalStorage } from "../../utils/embedded-report";
import { usePhoneLayout } from "../../utils/phone-layout";
import { ToggleGroup } from "../shared/toggle-group";
@@ -160,11 +160,12 @@ export function useCompareController(options: CompareControllerOptions) {
};
const flip = () => setFlipSide((side) => (side === "after" ? "before" : "after"));
const keyState = useRef({ previous, next, mode, activeArea, options });
keyState.current = { previous, next, mode, activeArea, options };
const keyState = useRef({ previous, next, mode, activeArea, options, swipePosition });
keyState.current = { previous, next, mode, activeArea, options, swipePosition };
// Stepping to the previous or next changed screen; a held key keeps stepping, accelerating, until
// it is released, the window loses focus, or the list ends. Reads the latest neighbours on each step.
// it is released, the window loses focus, or the end is reached. The Swipe divider is continuous,
// so a tap of [ or ] nudges it one step and a held one glides. Both read the latest state.
const stepScreen = (direction: 1 | -1): boolean => {
const state = keyState.current;
const target = direction === 1 ? state.next : state.previous;
@@ -172,34 +173,38 @@ export function useCompareController(options: CompareControllerOptions) {
state.options.onSelectScreen(target.id);
return true;
};
const hold = useRef<{ code: string; timer: ReturnType<typeof setTimeout> } | undefined>(undefined);
const endHold = () => {
if (!hold.current) return;
clearTimeout(hold.current.timer);
hold.current = undefined;
const moveDivider = (direction: 1 | -1, steps = 1): boolean => {
const state = keyState.current;
if (state.mode !== "swipe") return false;
const position = Math.max(0, Math.min(100, state.swipePosition + direction * SWIPE_STEP * steps));
if (position === state.swipePosition) return false;
state.swipePosition = position;
setSwipePosition(position);
return true;
};
const beginHold = (code: string, direction: 1 | -1) => {
endHold();
let step = 1;
const tick = () => {
if (!stepScreen(direction)) { endHold(); return; }
hold.current = { code, timer: setTimeout(tick, holdIntervalMs(step)) };
step += 1;
};
hold.current = { code, timer: setTimeout(tick, HOLD_INITIAL_DELAY_MS) };
const holdRef = useRef<KeyHold>(undefined);
holdRef.current ??= createKeyHold();
const hold = holdRef.current;
useEffect(() => hold.end, [hold]);
// The hold only tracks the key; the glide reads it every frame and stops with it.
const glideDivider = (code: string, direction: 1 | -1) => {
hold.begin(code, () => true);
glideWhileHeld(hold, code, HOLD_INITIAL_DELAY_MS, (steps) => moveDivider(direction, steps));
};
useEffect(() => endHold, []);
useEffect(() => {
const onKeyDown = (event: KeyboardEvent) => {
hold.interrupt(event);
// The browser's own repeat of the held key is not a step; it must not scroll either.
if (event.repeat && hold.holding(event.code)) { event.preventDefault(); return; }
if (event.defaultPrevented || !shortcutsLive(event)) return;
const state = keyState.current;
const keys = SHORTCUTS.compare;
const stepScreens = state.options.stepScreens !== false;
if (stepScreens && matchesShortcut(event, keys.previousScreen)) {
if (stepScreen(-1)) beginHold(event.code, -1);
if (stepScreen(-1)) hold.begin(event.code, () => stepScreen(-1));
} else if (stepScreens && matchesShortcut(event, keys.nextScreen)) {
if (stepScreen(1)) beginHold(event.code, 1);
if (stepScreen(1)) hold.begin(event.code, () => stepScreen(1));
} else if (matchesShortcut(event, keys.nextArea)) {
stepArea(1);
} else if (matchesShortcut(event, keys.previousArea)) {
@@ -220,10 +225,10 @@ export function useCompareController(options: CompareControllerOptions) {
flip();
} else if (matchesShortcut(event, keys.dividerLeft)) {
if (state.mode !== "swipe") return;
setSwipePosition((value) => Math.max(0, value - SWIPE_STEP));
if (moveDivider(-1)) glideDivider(event.code, -1);
} else if (matchesShortcut(event, keys.dividerRight)) {
if (state.mode !== "swipe") return;
setSwipePosition((value) => Math.min(100, value + SWIPE_STEP));
if (moveDivider(1)) glideDivider(event.code, 1);
} else if (matchesShortcut(event, keys.outlines)) {
toggleOutlines();
} else if (matchesShortcut(event, keys.whatChanged)) {
@@ -234,15 +239,15 @@ export function useCompareController(options: CompareControllerOptions) {
event.preventDefault();
};
const onKeyUp = (event: KeyboardEvent) => {
if (hold.current && event.code === hold.current.code) endHold();
if (hold.holding(event.code)) hold.end();
};
window.addEventListener("keydown", onKeyDown);
window.addEventListener("keyup", onKeyUp);
window.addEventListener("blur", endHold);
window.addEventListener("blur", hold.end);
return () => {
window.removeEventListener("keydown", onKeyDown);
window.removeEventListener("keyup", onKeyUp);
window.removeEventListener("blur", endHold);
window.removeEventListener("blur", hold.end);
};
});
@@ -412,9 +417,8 @@ export function compareNotes(screenDiff: ScreenDiff, factCount: number, statusBa
return [
...(factCount === 0 && screenDiff.status === "needs-review"
? ["The code for this screen changed. No visible difference was found."] : []),
// A capture note says why a side has no frame (a flow that stopped before it); without one the screen itself came or went.
...(screenDiff.status === "added" ? [screenDiff.captureNotes?.before ?? "This screen is new in this PR. There is no Before to compare."]
: screenDiff.status === "removed" ? [screenDiff.captureNotes?.after ?? "This screen was removed in this PR. There is no After to compare."] : []),
...(screenDiff.status === "added" ? ["This screen is new in this PR. There is no Before to compare."]
: screenDiff.status === "removed" ? ["This screen was removed in this PR. There is no After to compare."] : []),
...(statusBarIgnored
? ["The status bar (clock, signal, battery) differs between the captures. It is not counted as a change."] : []),
...(homeIndicatorIgnored
@@ -17,6 +17,8 @@ export type ShortcutContext = {
hasChanges: boolean;
/** The report can be handed off to an agent (a hosted preview). */
handoff?: boolean;
/** The report was captured in both light and dark, so the app's appearance can be switched. */
appearances?: boolean;
};
const COMPARE = SHORTCUTS.compare;
@@ -75,13 +77,15 @@ export function shortcutGroups(context: ShortcutContext): Group[][] {
title: "View",
rows: [
...(context.canvas === "compare" ? [] : [{ label: "Show or hide the inspector", keys: [SHORTCUTS.panel.right] }]),
{ label: "Viewer theme: dark or light", keys: [SHORTCUTS.appearance.theme] },
...(context.appearances ? [{ label: "The app's appearance: light or dark", keys: [SHORTCUTS.appearance.app] }] : []),
{ label: "Show this list", keys: ["?"] },
],
};
const mapGroup: Group = {
title: "Map",
rows: [
{ label: "Walk the map from the selected screen", keys: ["↑", "↓", "←", "→", "H J K L"] },
{ label: "Walk the map, or enter it at an edge", keys: ["↑", "↓", "←", "→", "H J K L"] },
{ label: "Undo or redo moving a card", keys: [SHORTCUTS.edit.undo, SHORTCUTS.edit.redo] },
{ label: "Close the inspector, then deselect", keys: ["Esc"] },
],
+4 -1
View File
@@ -7,6 +7,8 @@ import { isPreviewPath, isReportTargetId, previewReportsUrl, targetQuery } from
import { ScreenshotImage } from "../shared/screenshot-image";
import { artifactUrl } from "../../utils/model";
import { Tooltip } from "../shared/tooltip";
import { KeyHint } from "../shared/key-hint";
import { formatShortcut, SHORTCUTS } from "../../utils/shortcuts";
import { ChangesMenu } from "./changes-menu";
import type { FocusStatus } from "../../utils/navigation";
import type { ExploreMap, MapIndex } from "../../utils/model";
@@ -192,12 +194,13 @@ export function AppPill(props: AppPillProps) {
) : null}
{props.appearance ? (
<>
<Tooltip label="Appearance · the same screens captured in the other scheme" placement="bottom">
<Tooltip label="Appearance · the same screens captured in the other scheme" shortcut={formatShortcut(SHORTCUTS.appearance.app)} placement="bottom">
<button ref={appearanceRef} type="button" className="collapsed-platform" aria-haspopup="menu" aria-expanded={appearanceOpen}
aria-label={`Appearance: ${appearanceLabel(props.appearance.current)}. Show the other appearance`}
onClick={() => setAppearanceOpen(open => !open)}>
{appearanceLabel(props.appearance.current)}
<svg aria-hidden="true" width="8" height="8" viewBox="0 0 8 8"><path d="M1 2.5 4 5.5 7 2.5" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" /></svg>
<KeyHint shortcut={SHORTCUTS.appearance.app} />
</button>
</Tooltip>
<Menu items={appearanceItems} open={appearanceOpen} anchorRef={appearanceRef} ariaLabel="Appearance" onDismiss={() => setAppearanceOpen(false)} />
@@ -1,5 +1,3 @@
import type { PublicFlowEvidence, PublicReview } from "../../../../src/contracts/capture";
import { flowOfScreen, flowSourceHref } from "../../utils/flow-source";
import { useEffect, useMemo, useRef, useState, type CSSProperties } from "react";
import { LAUNCH_SURFACE_ID } from "../../../../src/contracts/capture";
import { isEmbeddedArtifactUrl, resolveEmbeddedArtifactUrl } from "../../utils/embedded-report";
@@ -417,8 +415,6 @@ type InspectorPanelProps = {
onOpenCompare?: (() => void) | undefined;
/** The changed screens in review order, and how to step to one, for the sidebar review. */
review?: { order: readonly ChangedScreen[]; onSelectScreen: (id: string) => void } | undefined;
/** The public review, for a flow frame's flow (its steps and e2e source). */
flowReview?: PublicReview | undefined;
};
/** The URL to show for an artifact, resolving an embedded (self-contained report) reference lazily. */
@@ -465,50 +461,6 @@ function LaunchSection({ screen, index, note }: { screen: Screen; index: MapInde
);
}
/** A flow frame's place in its flow: the step that took it, the steps around it, the outcome per side, and the e2e source. */
function FlowSection(props: { context: { flow: PublicFlowEvidence; key: string }; review: PublicReview | undefined; onSelectScreen: (id: string) => void }) {
const { flow, key } = props.context;
const side = flow.head ?? flow.base;
const steps = side?.steps ?? [];
// A secondary-appearance frame (`<key>@<scheme>`) belongs to the step that took the primary one.
const frameKey = key.replace(/@(?:light|dark)$/, "");
const stepIndex = steps.findIndex(step => step.frame === frameKey);
const fileHref = flowSourceHref(props.review, flow.file, side?.line);
const outcome = (name: "base" | "head") => {
const run = flow[name];
if (!run) return "not run";
const failed = run.steps.findIndex(step => step.status !== "passed");
return run.status === "passed" || failed < 0 ? run.status : `${run.status} at step ${failed + 1}`;
};
return (
<section className="inspector-section flow-section">
<div className="section-title"><h3>Flow</h3></div>
<p className="flow-section-title">{flow.title}</p>
<p className="flow-section-file">{fileHref ? <a href={fileHref} target="_blank" rel="noreferrer">{flow.file}</a> : flow.file}</p>
<dl className="flow-section-outcomes">
<div><dt>After</dt><dd>{outcome("head")}</dd></div>
<div><dt>Before</dt><dd>{outcome("base")}</dd></div>
</dl>
{stepIndex >= 0 ? <p className="flow-section-step">Frame from step {stepIndex + 1} of {steps.length}</p> : null}
<ol className="flow-section-steps">
{steps.map((step, index) => {
const href = flowSourceHref(props.review, flow.file, step.line);
const frame = step.frame ? flow.frames.find(entry => entry.key === step.frame) : undefined;
const text = <><span className="flow-section-step-api">{step.api}</span> <span className="flow-section-step-label">{step.label}</span></>;
return (
<li key={index} className={`flow-section-step-row${index === stepIndex ? " current" : ""}${step.status !== "passed" ? " failed" : ""}`}>
<span className="flow-section-step-number">{index + 1}</span>
{href ? <a href={href} target="_blank" rel="noreferrer" title={`${flow.file}:${step.line}`}>{text}</a> : text}
{frame && frame.key !== key ? <button type="button" className="flow-section-step-frame" onClick={() => props.onSelectScreen(frame.id)}>frame · {frame.label}</button> : null}
{step.status !== "passed" && step.error ? <span className="flow-section-step-error">{step.error.message}</span> : null}
</li>
);
})}
</ol>
</section>
);
}
export function InspectorPanel(props: InspectorPanelProps) {
const { direction, screen } = props;
const screenDiff = screen ? props.diff?.screens.get(screen.id) : undefined;
@@ -516,7 +468,6 @@ export function InspectorPanel(props: InspectorPanelProps) {
const { outgoing, incoming } = useMemo(
() => inspectorTransitions(screen?.id, props.index), [screen?.id, props.index],
);
const flowContext = useMemo(() => screen ? flowOfScreen(props.flowReview, screen.id) : undefined, [props.flowReview, screen]);
// Only a screen whose comparison actually differs earns the Before → After layout. A screen
// the review confirmed as unchanged reads like any other: one screenshot and its transitions.
const showDiff = Boolean(
@@ -590,7 +541,6 @@ export function InspectorPanel(props: InspectorPanelProps) {
{screen.id.startsWith(LAUNCH_SURFACE_ID) ? <LaunchSection screen={screen} index={props.index} note={screenDiff?.note} /> : null}
{flowContext ? <FlowSection context={flowContext} review={props.flowReview} onSelectScreen={props.onSelectScreen} /> : (
<section
className={`inspector-section transition-section${transitions.length === 0 ? " is-empty" : ""}`}>
<div className="section-title">
@@ -624,7 +574,6 @@ export function InspectorPanel(props: InspectorPanelProps) {
</div>
)}
</section>
)}
</div>
);
}
-4
View File
@@ -1,4 +1,3 @@
import type { PublicReview } from "../../../../src/contracts/capture";
import { useEffect, useRef } from "react";
import { GitCompareArrows, PanelRight, ScanSearch, X } from "lucide-react";
import { Tooltip } from "../shared/tooltip";
@@ -30,8 +29,6 @@ type RightPanelProps = {
onOpenCompare?: (() => void) | undefined;
/** The changed screens in review order, and how to step to one, for the sidebar review. */
review?: { order: readonly ChangedScreen[]; onSelectScreen: (id: string) => void } | undefined;
/** The public review, for a flow frame's flow (its steps and e2e source). */
flowReview?: PublicReview | undefined;
};
export function RightPanel(props: RightPanelProps) {
@@ -152,7 +149,6 @@ export function RightPanel(props: RightPanelProps) {
onSelectScreen={props.onSelectScreen}
onOpenCompare={props.onOpenCompare}
review={props.review}
flowReview={props.flowReview}
/>
</AutoHideScrollArea>
</aside>
@@ -1,6 +1,7 @@
import { useEffect, useState } from "react";
import { Maximize, Minimize, Moon, Sun, SunMoon } from "lucide-react";
import { Tooltip } from "../shared/tooltip";
import { formatShortcut, SHORTCUTS } from "../../utils/shortcuts";
import type { ThemePreference } from "../../utils/navigation";
export type ShellTheme = "light" | "dark";
@@ -51,7 +52,7 @@ const THEME_LABELS: Record<ThemePreference, string> = {
export function ThemeToggleButton(props: ShellActionsProps) {
const Icon = props.themePreference === "system" ? SunMoon : props.themePreference === "dark" ? Moon : Sun;
return (
<Tooltip label={THEME_LABELS[props.themePreference]} placement="bottom">
<Tooltip label={THEME_LABELS[props.themePreference]} shortcut={formatShortcut(SHORTCUTS.appearance.theme)} placement="bottom">
<button
type="button"
className={props.className ?? "icon-button"}
+2 -5
View File
@@ -1,6 +1,6 @@
import { useEffect, useRef, type PointerEvent as ReactPointerEvent, type ReactNode } from "react";
import { createPortal } from "react-dom";
import { GitCompareArrows, LayoutGrid, Map as MapIcon, X, ListOrdered } from "lucide-react";
import { GitCompareArrows, LayoutGrid, Map as MapIcon, X } from "lucide-react";
import { CANVAS_LABELS, type CanvasView } from "../../utils/navigation";
import { CANVAS_VIEW_ORDER } from "../../utils/canvas-view-transition";
import "./phone.css";
@@ -9,7 +9,6 @@ const VIEW_ICONS: Record<CanvasView, ReactNode> = {
map: <MapIcon />,
screens: <LayoutGrid />,
compare: <GitCompareArrows />,
flows: <ListOrdered />,
};
/**
@@ -19,13 +18,11 @@ const VIEW_ICONS: Record<CanvasView, ReactNode> = {
export function PhoneTabBar(props: {
canvas: CanvasView;
compareCount: number;
hasFlows?: boolean;
flowsOnly?: boolean;
onSelectCanvas: (canvas: CanvasView) => void;
}) {
return (
<nav className="phone-tab-bar" aria-label="Views">
{CANVAS_VIEW_ORDER.filter((id) => (id !== "flows" || props.hasFlows) && !(props.flowsOnly && (id === "map" || id === "screens"))).map((id) => {
{CANVAS_VIEW_ORDER.map((id) => {
return (
<button key={id} type="button" className="phone-tab"
aria-current={props.canvas === id ? "page" : undefined}
-4
View File
@@ -380,10 +380,6 @@
.phone-layout .collapsed-pr,
.screens-page.phone .screens-cell .screen-path-text,
.phone-layout .inspector-screen-path { padding-top: 14px; padding-bottom: 14px; margin-top: -14px; margin-bottom: -14px; }
/* A long review title ("devin/flows-capture vs main") ends in an ellipsis instead of running under the search buttons. */
.phone-layout .collapsed-app-identity > .tooltip-anchor { flex: none; }
.phone-layout .collapsed-app-identity > .tooltip-anchor:has(> .collapsed-pr) { flex: 1 1 0; min-width: 0; }
.phone-layout .collapsed-pr { flex: 0 1 auto; min-width: 0; overflow: hidden; text-overflow: ellipsis; }
/* Before/After keep a 32px line; the hit area grows into the gap on each side. */
.phone-layout .compare-flip-side { min-height: 32px; padding: 6px 12px; margin: -6px 0; }
.phone-layout .right-panel .icon-button { width: 44px; height: 44px; }
+14
View File
@@ -0,0 +1,14 @@
import { heldKeyHint, useHeldModifiers } from "../../utils/held-modifiers";
import type { Shortcut } from "../../utils/shortcuts";
/**
* The key that completes a chord, shown on a button's corner while the chord's modifiers are
* held. Hold ⌃ and the toolbar's sections show 1, 2 and 3; release it and they are gone.
* Nothing renders for a plain key or while nothing is held.
*/
export function KeyHint({ shortcut }: { shortcut: Shortcut }) {
const held = useHeldModifiers();
const key = heldKeyHint(shortcut, held);
if (!key) return null;
return <kbd className="key-hint" aria-hidden="true">{key}</kbd>;
}
-58
View File
@@ -1,58 +0,0 @@
.flows-page { padding: 72px 32px 120px; display: flex; flex-direction: column; gap: 24px; overflow: auto; height: 100%; box-sizing: border-box; }
.flows-page.phone { padding: 64px 12px 120px; gap: 16px; }
.flows-empty { color: var(--text-muted, #6b6b6b); }
.flow-card { border: 1px solid var(--border, #e5e5e5); border-radius: 14px; background: var(--surface, #fff); padding: 18px 20px; display: flex; flex-direction: column; gap: 14px; }
.flow-header { display: flex; justify-content: space-between; gap: 16px; align-items: flex-start; flex-wrap: wrap; }
.flow-header h2 { margin: 0; font-size: 17px; font-weight: 600; }
.flow-file { margin: 4px 0 0; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 12px; color: var(--text-muted, #6b6b6b); }
.flow-outcomes { display: flex; gap: 16px; }
.flow-outcome { display: flex; flex-direction: column; gap: 4px; align-items: flex-start; }
.flow-outcome-side { font-size: 11px; text-transform: uppercase; letter-spacing: 0.04em; color: var(--text-muted, #6b6b6b); }
.flow-status, .flow-verdict { display: inline-flex; align-items: center; padding: 2px 8px; border-radius: 999px; font-size: 12px; font-weight: 600; background: #f0f0f0; color: #444; }
.tone-passed.flow-status, .tone-unchanged.flow-verdict { background: #e6f4ea; color: #1e7a3b; }
.tone-failed.flow-status, .tone-removed.flow-verdict { background: #fdecec; color: #b42318; }
.tone-modified.flow-verdict, .tone-needs-review.flow-verdict { background: #fff1e0; color: #b45309; }
.tone-added.flow-verdict { background: #e6f4ea; color: #1e7a3b; }
.flow-failure { margin: 0; padding: 10px 12px; border-radius: 10px; background: #fdecec; color: #7a1c14; font-size: 13px; }
.flow-failure code { font-size: 12px; }
.flow-body { display: grid; grid-template-columns: minmax(0, 1fr) minmax(260px, 360px); gap: 20px; align-items: start; }
.flows-page.phone .flow-body { grid-template-columns: 1fr; }
.flow-filmstrip { list-style: none; margin: 0; padding: 4px 0 8px; display: flex; flex-wrap: wrap; gap: 16px; }
/* Phone: one horizontal strip, swiped frame by frame. Desktop wraps so a long flow is visible at a glance. */
.flows-page.phone .flow-filmstrip { flex-wrap: nowrap; overflow-x: auto; scroll-snap-type: x proximity; }
.flow-frame { flex: 0 0 auto; width: 140px; display: flex; flex-direction: column; gap: 8px; scroll-snap-align: start; }
.flows-page.phone .flow-frame { width: 150px; }
.flow-frame-face {
position: relative;
margin: 0;
display: flex;
flex-direction: column;
}
/* A folded run of unchanged step frames: the count sits after the label; the folded steps are the tooltip. */
.flow-frame-tags { display: flex; align-items: center; gap: 6px; }
.flow-frame-same { padding: 1px 6px; border-radius: 999px; background: var(--panel-hover, #f0f0f0); color: var(--text-muted, #6b6b6b); font-size: 10px; font-weight: 600; vertical-align: 1px; }
.flow-header-side { display: flex; flex-direction: column; align-items: flex-end; gap: 10px; }
.flow-side-toggle { font-size: 12px; }
.flow-frame-button { padding: 0; border: 0; background: none; cursor: pointer; border-radius: 10px; min-width: 44px; min-height: 44px; }
.flow-frame-button:focus-visible { outline: 2px solid #2f6fed; outline-offset: 2px; }
.flow-frame-image { display: block; width: 140px; height: auto; border-radius: 10px; border: 1px solid var(--border, #e5e5e5); background: #fafafa; }
.flows-page.phone .flow-frame-image { width: 150px; }
.flow-frame-missing { width: 140px; aspect-ratio: 402 / 874; border-radius: 10px; border: 1px dashed #d0d0d0; display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 6px; text-align: center; padding: 12px; box-sizing: border-box; font-size: 12px; color: var(--text-muted, #6b6b6b); }
.flow-frame-missing small { font-size: 11px; }
.flow-frame-caption { display: flex; flex-direction: column; align-items: flex-start; gap: 4px; }
/* The label is the step that produced the frame; long locators clamp to two lines (full text on hover). */
.flow-frame-caption strong { font-size: 12px; font-weight: 600; line-height: 1.3; display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden; overflow-wrap: anywhere; }
.flow-steps { margin: 0; padding: 0; list-style: none; display: flex; flex-direction: column; gap: 6px; font-size: 13px; }
.flow-step { display: grid; grid-template-columns: 22px auto 1fr auto; column-gap: 8px; row-gap: 2px; align-items: baseline; padding: 6px 8px; border-radius: 8px; min-height: 44px; box-sizing: border-box; }
.flow-step.frame { background: #f6f8fb; }
.flow-step.failed { background: #fdecec; }
.flow-step.skipped { opacity: 0.45; }
.flow-step-number { color: var(--text-muted, #6b6b6b); font-variant-numeric: tabular-nums; }
.flow-step-api { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 12px; color: #444; }
.flow-step-label { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 12px; overflow-wrap: anywhere; }
.flow-step-duration { grid-column: 4; font-size: 11px; color: var(--text-muted, #6b6b6b); font-variant-numeric: tabular-nums; white-space: nowrap; }
.flow-meta { margin: 2px 0 0; font-size: 12px; color: var(--text-muted, #6b6b6b); font-variant-numeric: tabular-nums; }
.flow-step-frame { grid-column: 2 / -1; font-size: 11px; color: #2f6fed; }
.flow-step-error { grid-column: 2 / -1; font-size: 12px; color: #7a1c14; }
-221
View File
@@ -1,221 +0,0 @@
import { useState } from "react";
import type { PublicFlowEvidence, PublicFlowSide, PublicReview } from "../../../../src/contracts/capture";
import { artifactUrl, type Artifact } from "../../utils/model";
import { flowSourceHref } from "../../utils/flow-source";
import { ScreenshotImage } from "../shared/screenshot-image";
import { ToggleGroup } from "../shared/toggle-group";
import "./flows.css";
type Side = "base" | "head";
const SIDE_LABEL: Record<Side, string> = { base: "Before", head: "After" };
/** The step a side stopped at, when it did not pass. */
function stoppedAt(flow: PublicFlowSide): { index: number; step: PublicFlowSide["steps"][number] } | undefined {
if (flow.status === "passed") return undefined;
const index = flow.steps.findIndex(step => step.status !== "passed");
return index < 0 ? undefined : { index, step: flow.steps[index]! };
}
function formatDuration(ms: number): string {
if (!Number.isFinite(ms) || ms < 0) return "";
if (ms < 1000) return `${Math.round(ms)} ms`;
if (ms < 60_000) return `${(ms / 1000).toFixed(ms < 10_000 ? 1 : 0)} s`;
return `${Math.floor(ms / 60_000)}m ${String(Math.round((ms % 60_000) / 1000)).padStart(2, "0")}s`;
}
function sideSummary(entry: PublicFlowEvidence, side: Side): string {
const flow = entry[side];
if (!flow) return "not run";
const stop = stoppedAt(flow);
return stop ? `${flow.status} at step ${stop.index + 1}` : flow.status;
}
function verdictLabel(entry: PublicFlowEvidence["frames"][number], base: PublicFlowSide | undefined, head: PublicFlowSide | undefined): { text: string; tone: string } {
const inBase = Boolean(base?.frames[entry.key]); const inHead = Boolean(head?.frames[entry.key]);
if (inBase && inHead) {
if (!entry.visual) return { text: "Not compared", tone: "muted" };
return entry.visual.verdict === "unchanged" ? { text: "Unchanged", tone: "unchanged" }
: entry.visual.verdict === "modified" ? { text: entry.visual.mismatchPercentage !== undefined ? `Changed · ${entry.visual.mismatchPercentage.toFixed(1)}%` : "Changed", tone: "modified" }
: { text: "Needs review", tone: "needs-review" };
}
if (inHead) return { text: base ? "Not reached before" : "New", tone: "added" };
if (inBase) return { text: head ? "Not reached after" : "Removed", tone: "removed" };
return { text: "Not taken", tone: "muted" };
}
/** The same resolution the Screens grid uses: embedded bytes in a report, the published URL otherwise. */
function frameSrc(entry: PublicFlowEvidence, side: Side, key: string, taken: NonNullable<PublicFlowSide["frames"][string]>): string | undefined {
const artifact: Artifact = { id: `flow:${side}:${entry.id}/${key}`, kind: "screenshot", path: `${side}/flows/${entry.id}/${key}.png`,
publicUrl: taken.url, sha256: taken.sha256, mimeType: "image/png", width: taken.width, height: taken.height, createdAt: taken.capturedAt };
return artifactUrl(artifact);
}
function Frame(props: {
entry: PublicFlowEvidence;
frame: PublicFlowEvidence["frames"][number];
side: Side;
/** Labels of the step frames after this one that left the screen unchanged, folded into this frame. */
same: string[];
onOpen?: (surfaceId: string) => void;
}) {
const { entry, frame, side } = props;
const verdict = verdictLabel(frame, entry.base, entry.head);
const taken = entry[side]?.frames[frame.key];
const flow = entry[side];
const stop = flow && !taken ? stoppedAt(flow) : undefined;
const src = taken ? frameSrc(entry, side, frame.key, taken) : undefined;
return (
<li className={`flow-frame tone-${verdict.tone}`} data-side={side}>
<figure className="flow-frame-face">
{taken && src ? (
<button
type="button"
className="flow-frame-button"
onClick={props.onOpen ? () => props.onOpen!(frame.id) : undefined}
aria-label={`Open ${frame.label} (${SIDE_LABEL[side]}) in Compare`}
>
<ScreenshotImage
className="flow-frame-image"
src={src}
alt={`${entry.title} › ${frame.label}, ${SIDE_LABEL[side]}`}
width={taken.width}
height={taken.height}
/>
</button>
) : (
<div className="flow-frame-missing" role="note">
{!flow
? "Flow not run"
: stop
? (
<>
Not reached
<small>
the flow {flow.status} at step {stop.index + 1}
</small>
</>
)
: "Not taken"}
</div>
)}
</figure>
<div className="flow-frame-caption">
<strong title={frame.label}>{frame.label}</strong>
<span className="flow-frame-tags">
<span className={`flow-verdict tone-${verdict.tone}`}>
{verdict.text}
</span>
{props.same.length ? (
<small className="flow-frame-same" title={`Unchanged after:\n${props.same.join("\n")}`}>+{props.same.length}</small>
) : null}
</span>
</div>
</li>
);
}
/** A step frame whose picture (outside the system bands, when the capture hashed that) equals the previous shown frame's on every side that took both adds nothing: it folds into that frame. Checkpoints always show. */
function visibleFrames(entry: PublicFlowEvidence): { frame: PublicFlowEvidence["frames"][number]; same: string[] }[] {
const sameOnEverySide = (a: string, b: string) => (["head", "base"] as const).every(side => {
const frames = entry[side]?.frames;
if (!frames) return true;
const x = frames[a]; const y = frames[b];
return Boolean(x && y && (x.contentSha256 ?? x.sha256) === (y.contentSha256 ?? y.sha256));
});
const shown: { frame: PublicFlowEvidence["frames"][number]; same: string[] }[] = [];
for (const frame of entry.frames.filter(frame => !frame.colorScheme)) {
const previous = shown.at(-1);
if (previous && /^step-\d+$/.test(frame.key) && sameOnEverySide(previous.frame.key, frame.key)) { previous.same.push(frame.label); continue; }
shown.push({ frame, same: [] });
}
return shown;
}
function FlowCard(props: { entry: PublicFlowEvidence; review: PublicReview; onOpenFrame?: (surfaceId: string) => void }) {
const { entry, review } = props;
const head = entry.head; const base = entry.base;
const [side, setSide] = useState<Side>(head ? "head" : "base");
const shownSide: Side = head && base ? side : head ? "head" : "base";
const headStop = head ? stoppedAt(head) : undefined;
const tone = !head ? "muted" : head.status === "passed" ? "passed" : "failed";
const sourceHref = flowSourceHref(review, entry.file, entry.head?.line ?? entry.base?.line);
return (
<section className={`flow-card tone-${tone}`} aria-labelledby={`flow-${entry.id}`}>
<header className="flow-header">
<div>
<h2 id={`flow-${entry.id}`}>{entry.title}</h2>
<p className="flow-file">{sourceHref ? <a href={sourceHref} target="_blank" rel="noreferrer noopener">{entry.file}</a> : entry.file}</p>
{(head ?? base) ? <p className="flow-meta">{(head ?? base)!.steps.length} steps · {formatDuration((head ?? base)!.steps.reduce((sum, step) => sum + step.durationMs, 0))}</p> : null}
</div>
<div className="flow-header-side">
<div className="flow-outcomes">
<span className="flow-outcome"><span className="flow-outcome-side">After</span><span className={`flow-status tone-${tone}`}>{sideSummary(entry, "head")}</span></span>
<span className="flow-outcome"><span className="flow-outcome-side">Before</span><span className={`flow-status tone-${!base ? "muted" : base.status === "passed" ? "passed" : "failed"}`}>{sideSummary(entry, "base")}</span></span>
</div>
{head && base ? (
<div className="flow-side-toggle">
<ToggleGroup<Side> value={shownSide} onChange={setSide} ariaLabel="Frames shown" variant="flat"
options={[{ id: "head", label: "After" }, { id: "base", label: "Before" }]} />
</div>
) : null}
</div>
</header>
{headStop?.step.error ? (
<p className="flow-failure" role="note">
Stopped at step {headStop.index + 1} — <code>{headStop.step.api} {headStop.step.label}</code>: {headStop.step.error.message}
</p>
) : null}
<div className="flow-body">
<ol className="flow-filmstrip" aria-label={`Frames (${SIDE_LABEL[shownSide]})`}>
{visibleFrames(entry).map(({ frame, same }) => <Frame key={frame.key} entry={entry} frame={frame} side={shownSide} same={same} {...(props.onOpenFrame ? { onOpen: props.onOpenFrame } : {})} />)}
</ol>
<Steps entry={entry} review={review} />
</div>
</section>
);
}
function Steps(props: { entry: PublicFlowEvidence; review: PublicReview }) {
// The steps as head ran them; base's are shown when head did not run at all.
const side: Side = props.entry.head ? "head" : "base";
const flow = props.entry[side];
if (!flow) return null;
const stop = stoppedAt(flow);
return (
<ol className="flow-steps" aria-label={`Steps (${SIDE_LABEL[side]})`}>
{flow.steps.map((step, index) => {
const failed = stop?.index === index;
const after = stop !== undefined && index > stop.index;
return (
<li key={index} className={`flow-step${failed ? " failed" : ""}${after ? " skipped" : ""}${step.frame ? " frame" : ""}`}>
<span className="flow-step-number">{index + 1}</span>
{flowSourceHref(props.review, props.entry.file, step.line) ? (
<a className="flow-step-source" href={flowSourceHref(props.review, props.entry.file, step.line)} target="_blank" rel="noreferrer" title={`${props.entry.file}:${step.line}`}>
<span className="flow-step-api">{step.api}</span> <span className="flow-step-label">{step.label}</span>
</a>
) : <><span className="flow-step-api">{step.api}</span> <span className="flow-step-label">{step.label}</span></>}
<span className="flow-step-duration">{formatDuration(step.durationMs)}</span>
{step.frame ? <span className="flow-step-frame">frame · {step.frame}</span> : null}
{failed && step.error ? <span className="flow-step-error">{step.error.message}</span> : null}
</li>
);
})}
</ol>
);
}
export function FlowsView(props: { review: PublicReview; phone?: boolean; onOpenFrame?: (surfaceId: string) => void }) {
const flows = Array.isArray(props.review.flows) ? props.review.flows : [];
return (
<main className={`flows-page${props.phone ? " phone" : ""}`} aria-label="Flows">
{(["head", "base"] as const).filter(side => props.review.flowsFailure?.[side]).map(side => (
<section key={side} className="flow-card tone-failed flows-not-run" role="alert">
<header className="flow-header"><div><h2>The flows did not run</h2></div><div className="flow-outcomes"><span className="flow-outcome"><span className="flow-outcome-side">{SIDE_LABEL[side]}</span><span className="flow-status tone-failed">{props.review.flowsFailure![side]!.code}</span></span></div></header>
<p className="flow-failure">{props.review.flowsFailure![side]!.message}</p>
</section>
))}
{flows.length === 0 && !props.review.flowsFailure ? <p className="flows-empty">This review ran no flows.</p> : null}
{flows.map(entry => <FlowCard key={entry.id} entry={entry} review={props.review} {...(props.onOpenFrame ? { onOpenFrame: props.onOpenFrame } : {})} />)}
</main>
);
}
+16 -20
View File
@@ -1,6 +1,6 @@
import { useEffect, useMemo, useRef, useState, type CSSProperties, type KeyboardEvent, type ReactNode } from "react";
import { ChevronRight, ChevronsDownUp, ChevronsUpDown, ListTree } from "lucide-react";
import { artifactUrl, isFlowScreen, isLaunchScreen, type ExploreMap, type MapIndex, type Screen } from "../../utils/model";
import { artifactUrl, isLaunchScreen, type ExploreMap, type MapIndex, type Screen } from "../../utils/model";
import { primaryScreenshotForScreen, screenshotSize, typicalScreenshotSize, type ScreenshotSize } from "../../utils/screen-images";
import { diffClass, type BuildDiff, type DiffStatus } from "../../utils/build-diff";
import { focusStatusOf, isCapturedChange } from "../../utils/changed-screens";
@@ -9,7 +9,7 @@ import { screenTree, treeIndex, treeNodeKey, treeScreenOrder, type ScreenTree, t
import type { Appearance } from "../../utils/appearance";
import type { FocusRequest, FocusStatus } from "../../utils/navigation";
import { shortcutsLive } from "../../utils/shortcuts";
import { HOLD_INITIAL_DELAY_MS, holdIntervalMs } from "../../utils/key-hold";
import { createKeyHold } from "../../utils/key-hold";
import { placeholderScreen } from "../../utils/map-frame";
import { ScreenScreenshotCard } from "../canvas/screen-screenshot-card";
import { useCanvasVisibleFrame } from "../canvas/visible-frame-provider";
@@ -129,7 +129,7 @@ function ScreenCell(props: {
className="screens-card"
ariaLabel={props.screen.title}
title={props.screen.title}
path={isFlowScreen(props.screen) ? props.screen.state ?? displayPathForScreen(props.screen) : displayPathForScreen(props.screen)}
path={displayPathForScreen(props.screen)}
{...(props.index.plainTitles ? { plainTitle: true } : {})}
{...(url ? { screenshot: url } : {})}
{...(size ? size : {})}
@@ -188,7 +188,7 @@ function TreeRows(props: {
if (!screen) return null;
const dot = dotClass(props.diff, props.elsewhere, screen.id);
const launch = isLaunchScreen(screen);
const label = launch ? "Cold start" : isFlowScreen(screen) ? screen.state ?? screenLabel(screen, props.index) : screenLabel(screen, props.index);
const label = launch ? "Cold start" : screenLabel(screen, props.index);
return (
<li key={node.screenId} className={key ? "screens-tree-parent" : undefined}>
<button type="button" style={style}
@@ -393,28 +393,23 @@ export function ScreensView(props: ScreensViewProps) {
pickRef.current(id);
requestAnimationFrame(() => document.getElementById(cardId(id))?.querySelector<HTMLElement>(".screen-screenshot-target")?.focus({ preventScroll: true }));
};
let hold: { code: string; at: string; timer: ReturnType<typeof setTimeout> } | undefined;
const endHold = () => {
if (hold) clearTimeout(hold.timer);
hold = undefined;
};
// A held arrow keeps stepping from the card the last step landed on, not the lagging pick.
const hold = createKeyHold();
const beginHold = (code: string, at: string) => {
endHold();
let step = 1;
const tick = () => {
const id = hold && next(code, hold.at);
if (!hold || !id) { endHold(); return; }
hold.begin(code, () => {
const id = next(code, at);
if (!id) return false;
at = id;
go(id);
hold = { code, at: id, timer: setTimeout(tick, holdIntervalMs(step)) };
step += 1;
};
hold = { code, at, timer: setTimeout(tick, HOLD_INITIAL_DELAY_MS) };
return true;
});
};
const onKeyDown = (event: globalThis.KeyboardEvent) => {
hold.interrupt(event);
const arrow = ["ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown"].includes(event.code);
if (!arrow && event.key !== "Enter") return;
// The browser's own repeat of a held arrow would scroll the page under the hold.
if (event.repeat && hold?.code === event.code) { event.preventDefault(); return; }
if (event.repeat && hold.holding(event.code)) { event.preventDefault(); return; }
if (event.metaKey || event.ctrlKey || event.altKey || event.shiftKey || event.defaultPrevented || !shortcutsLive(event)) return;
const target = event.target instanceof Element ? event.target : null;
if (!arrow) {
@@ -436,8 +431,9 @@ export function ScreensView(props: ScreensViewProps) {
beginHold(event.code, id);
};
const onKeyUp = (event: globalThis.KeyboardEvent) => {
if (hold && event.code === hold.code) endHold();
if (hold.holding(event.code)) hold.end();
};
const endHold = hold.end;
window.addEventListener("keydown", onKeyDown);
window.addEventListener("keyup", onKeyUp);
window.addEventListener("blur", endHold);
Loaded 100 of 113 files, more files were not shown because too many files have changed in this diff. Show more