Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
ee0e86fe56 | ||
|
|
8bb985a9d2 | ||
|
|
766f268ea6 | ||
|
|
01f32fdb33 | ||
|
|
43aed26c80 | ||
|
|
e84a4a19d0 | ||
|
|
a40ef9e9a5 | ||
|
|
0beef676a9 | ||
|
|
f90ab1f480 | ||
|
|
6a8dbfb5a3 | ||
|
|
e3afc2a00c | ||
|
|
a60ae5c6d8 | ||
|
|
d26e65db47 | ||
|
|
47f37988a5 | ||
|
|
1a5a95af63 | ||
|
|
fc5b465513 | ||
|
|
09b9f34e33 |
No files matched your search
@@ -159,6 +159,23 @@ invisible on a device.
|
||||
|
||||
A pixel mismatch that rounds to 0.00% is noise and counts as "same". Diff regions inside the status-bar band are excluded from the verdict and reported as `ignoredStatusBarRegions`; the Viewer marks that band in Compare.
|
||||
|
||||
Each changed region also records whether its content only moved. CI searches for the shift (up to 20 screenshot
|
||||
pixels vertically and 4 horizontally, whole pixels and then sixths of one) that best lines Before up with After inside
|
||||
the region; near-ties go to the smallest move, and a second fit nearly as good two or more pixels away (repeating
|
||||
content) or a best fit at the edge of the search leaves the region unmeasured. When the shift explains most of the
|
||||
region's difference (a quarter for a move of half a pixel or less, where text re-rasterizes rather than moves; 60%
|
||||
above that) and, aligned by it, no more than two pixels still differ by over 140 in any channel, the region gets
|
||||
`shift: { x, y }` in screenshot pixels (right and down positive). New text, another colour or a caret is not a move.
|
||||
Every region the comparison found is measured, not only the eight it publishes, and `allRegionsMoved: true` says all
|
||||
of them moved. Moves are measured while the comparison's time budget lasts.
|
||||
|
||||
The Viewer draws moved areas dashed, at each side's own position, labelled with how far they moved to a tenth
|
||||
("↑4.1pt"); areas whose moves are within a third of each other merge into one outline, never around a changed area.
|
||||
When every region moved, What changed says how far per direction in place of the generic visual finding, and adds
|
||||
"Nothing on this screen changed content" when no other finding remains. A switch there turns the labels off. iOS
|
||||
screenshots are one pixel per point, so labels read in points; Android's are labelled in screenshot pixels, since the
|
||||
report does not know the screen's density.
|
||||
|
||||
## 7. Local CI test
|
||||
|
||||
`test/ci/run.mjs` runs the production pipeline against an app folder in this repository (`test/ci/apps/wallet`) and a scenario (`test/ci/scenarios/<app>/<name>/`: `scenario.json`, `overlay/`, `expected.json`, optional `setup.yaml`). The [local CI test harness README](test/ci/README.md) covers prerequisites, scenarios, expectations, the matrix runner and how to revisit a result. In outline:
|
||||
|
||||
@@ -4,11 +4,52 @@ Explore maps your app: a screenshot of every screen, connected by the taps betwe
|
||||
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/readme-hero-dark.png">
|
||||
<img alt="Explore's Map of the euxy app with the new About screen selected: every screen as a card laid out by distance from the launch screen, and the Inspector on the right showing the About capture as an added screen with its transitions" src="docs/screenshots/readme-hero-light.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">
|
||||
</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.
|
||||
|
||||
<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">
|
||||
<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">
|
||||
<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">
|
||||
</picture>
|
||||
<strong>A comment on every PR</strong>: with <a href="#set-up-ci">CI</a>, the report links and the added, removed and modified screens.
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<details>
|
||||
<summary><strong>Ask an agent about a report</strong></summary>
|
||||
|
||||
Paste this into Claude Code, Codex, Cursor, or any tool that can fetch a URL. In the Viewer, **Hand off to AI** fills it in for you:
|
||||
|
||||
```text
|
||||
Review the visual changes in this PR. Expo Explore report: <report link>
|
||||
|
||||
Fetch the link first. It explains the report's JSON API. Go through the changed screens,
|
||||
compare the before and after screenshots, and tell me which changes look intended and
|
||||
which look like regressions. For each regression, name the source file to fix.
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Requirements</strong></summary>
|
||||
|
||||
@@ -20,9 +61,75 @@ Explore maps your app: a screenshot of every screen, connected by the taps betwe
|
||||
|
||||
</details>
|
||||
|
||||
## Try it on your app
|
||||
## Quick start
|
||||
|
||||
Paste this into Claude Code or Codex from your app's directory. It explores a build you point to, or an Expo project straight from its source:
|
||||
Review a change to your own app, on your machine. You need an Expo SDK 57+ app with Expo Router or React Navigation, Node.js 24.12+, and EAS Simulator access ([join the waitlist](https://expo.dev/services/simulators)). No API keys, no CI.
|
||||
|
||||
From your app's directory:
|
||||
|
||||
1. **Make the app buildable on EAS, if it is not yet.**
|
||||
|
||||
```sh
|
||||
npx eas-cli@latest login
|
||||
npx eas-cli@latest init
|
||||
```
|
||||
|
||||
Then set `ios.bundleIdentifier` in your app config, add a simulator profile to `eas.json`, and commit. The review builds your last commit as the "before".
|
||||
|
||||
```json
|
||||
{ "build": { "explore": { "ios": { "simulator": true } } } }
|
||||
```
|
||||
|
||||
2. **Change a screen, then review the change.** Edit some text near the top of a screen (Explore captures the first screenful) and run:
|
||||
|
||||
```sh
|
||||
npx @expo/explore capture
|
||||
```
|
||||
|
||||
Explore builds your last commit and your uncommitted changes on EAS, captures the screens the changes can affect, before and after, on EAS Simulator, and opens the report in your browser. The first run waits for an EAS build; later runs reuse it while your native code is unchanged.
|
||||
|
||||
Or paste this into Claude Code or Codex from your app's directory:
|
||||
|
||||
```text
|
||||
Show me an Expo Explore review of a change to this app. Follow the "Review a change on
|
||||
this machine" section of https://unpkg.com/@expo/explore/skills/explore-setup/SKILL.md.
|
||||
If the app cannot build for the iOS Simulator on EAS yet, set that up (an EAS project,
|
||||
ios.bundleIdentifier, an "explore" profile with ios.simulator: true) and ask me before
|
||||
you commit it. If I have no uncommitted changes, change some text near the top of a
|
||||
screen. Then run npx @expo/explore capture and open the report.
|
||||
```
|
||||
|
||||
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>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/readme-reports-dark.png">
|
||||
<img alt="npx @expo/explore reports in a terminal: the Expo Explore wordmark, then one line per saved run (a local review of HEAD vs main selected, an exploration of an app, and PR #1), and below them the selected run's head and base commits with their messages and its 13 modified, 2 added, 2 removed and 17 need-review screens" src="docs/screenshots/readme-reports-light.png">
|
||||
</picture>
|
||||
|
||||
<details>
|
||||
<summary><strong>Other commits, and what a review does</strong></summary>
|
||||
|
||||
```sh
|
||||
npx @expo/explore capture # HEAD and your uncommitted changes, against where HEAD left the default branch
|
||||
npx @expo/explore capture --committed # HEAD alone
|
||||
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 on EAS Simulator (`--platform` picks one), and opens the report in a local Viewer. `--upload` hosts it 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.
|
||||
- Like a CI review, it builds on EAS (reusing a matching build) and runs simulator sessions: expect several minutes and EAS usage.
|
||||
- Saved runs take up to 2 GB in all, the oldest going first. `reports add <report.zip>` keeps a report you downloaded, such as a PR's `explore-review` artifact.
|
||||
|
||||
</details>
|
||||
|
||||
Explore uses its defaults until you run `npx @expo/explore setup`, which writes `.expo-explore/config.yaml` for you to change. Next: [review every pull request](#set-up-ci).
|
||||
|
||||
## Map every screen of any app
|
||||
|
||||
To map every screen of an app instead, with no config, paste this into Claude Code or Codex from your app's directory. It explores a build you point to, or an Expo project straight from its source:
|
||||
|
||||
```text
|
||||
Show me Expo Explore working on this app. Follow
|
||||
@@ -66,7 +173,7 @@ Explore starts an EAS Simulator, installs the build, taps through the app with y
|
||||
<details>
|
||||
<summary><strong>Explore a simulator session you already started</strong></summary>
|
||||
|
||||
If the app is already running on an `agent-device` EAS Simulator session, Explore can start from there. It leaves your session running.
|
||||
If the app is already running on an EAS Simulator session (`--type agent-device` or `--type argent`), Explore can start from there, with the session's controller. It leaves your session running.
|
||||
|
||||
```sh
|
||||
eas simulator:start --type agent-device --out-config-type dotenv # then agent-device install / open
|
||||
@@ -87,42 +194,6 @@ One card per screen the run reached, laid out by how many taps it took, with the
|
||||
|
||||
</details>
|
||||
|
||||
### Review a change before you push it
|
||||
|
||||
Once Explore is [set up](#set-up-ci) (`.expo-explore/config.yaml` committed), the review a PR gets also runs on your machine, between any two commits. No tokens or keys to set: it uses your `eas login` and your Claude Code or Codex login.
|
||||
|
||||
```text
|
||||
Review my current changes with Expo Explore. Follow the "Review a change on this machine"
|
||||
section of https://unpkg.com/@expo/explore/skills/explore-setup/SKILL.md, compare my
|
||||
branch (with my uncommitted changes) against main, and open the report.
|
||||
```
|
||||
|
||||
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>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/readme-reports-dark.png">
|
||||
<img alt="npx @expo/explore reports in a terminal: the Expo Explore wordmark, then one line per saved run (a local review of HEAD vs main selected, an exploration of an app, and PR #1), and below them the selected run's head and base commits with their messages and its 13 modified, 2 added, 2 removed and 17 need-review screens" src="docs/screenshots/readme-reports-light.png">
|
||||
</picture>
|
||||
|
||||
<details>
|
||||
<summary><strong>Run it yourself</strong></summary>
|
||||
|
||||
```sh
|
||||
npx @expo/explore capture:review # HEAD against where it left the default branch
|
||||
npx @expo/explore capture:review --uncommitted # your uncommitted changes too
|
||||
npx @expo/explore capture:review --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 on EAS Simulator (`--platform` picks one), and opens the report in a local Viewer. `--upload` hosts it and prints the link; `report:upload <report.zip>` hosts one you already have.
|
||||
- Your checkout, index and branches are never touched. `--uncommitted` takes tracked changes only; `--include-untracked` adds untracked files, which are uploaded with the EAS build.
|
||||
- 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.
|
||||
- Like a CI review, it builds on EAS (reusing a matching build) and runs simulator sessions: expect several minutes and EAS usage.
|
||||
- Saved runs take up to 2 GB in all, the oldest going first. `reports add <report.zip>` keeps a report you downloaded, such as a PR's `explore-review` artifact.
|
||||
|
||||
</details>
|
||||
|
||||
## Set up CI
|
||||
|
||||
Explore runs in your repository's GitHub Actions in two ways, both from the same setup: a review on every pull request, and a comparison of any two commits, such as a release against the last one.
|
||||
@@ -154,8 +225,8 @@ report:
|
||||
```
|
||||
|
||||
- Run `expo-explore setup --workflows` after enabling it to add the `deploy` job.
|
||||
- A [comparison of two commits](#compare-any-two-commits) links its hosted report from the run's summary instead of a PR comment. `capture:review --upload` on your machine deploys to the same project with your `eas login`.
|
||||
- `expo-explore report:upload <report.zip>...` hosts reports already on your machine the same way: a review's reports (one per platform, from `capture:review --output` or a downloaded `explore-review` artifact) or an `explore:binary` report.
|
||||
- A [comparison of two commits](#compare-any-two-commits) links its hosted report from the run's summary instead of a PR comment. `capture --upload` on your machine deploys to the same project with your `eas login`.
|
||||
- `expo-explore report:upload <report.zip>...` hosts reports already on your machine the same way: a review's reports (one per platform, from `capture --output` or a downloaded `explore-review` artifact) or an `explore:binary` report.
|
||||
- `EXPO_TOKEN` must be able to create the EAS project, so use a [robot user's](https://docs.expo.dev/accounts/programmatic-access/) token.
|
||||
- The report is encrypted, and only a request carrying the link's token can open it. Treat the link like a shared file link; see [report access](docs/private-review.md#hosted-previews).
|
||||
|
||||
@@ -172,7 +243,7 @@ The prompt above walks through these steps with you. To do them yourself:
|
||||
- `EXPO_TOKEN`: create it in [Expo access tokens](https://expo.dev/settings/access-tokens). For [hosted previews](#hosted-previews), use a [robot user](https://docs.expo.dev/accounts/programmatic-access/) that can create projects.
|
||||
- A secret for each `{{secret:NAME}}` in your setup steps. Run `npx @expo/explore setup --workflows` after you add one.
|
||||
4. Commit, merge to the default branch, and run **Expo Explore baseline** from GitHub Actions.
|
||||
5. Open a PR. **Expo Explore review** runs and posts a comment with the report. To see a whole review of your branch first, run `npx @expo/explore capture:review` on your machine.
|
||||
5. Open a PR. **Expo Explore review** runs and posts a comment with the report. To see a whole review of your branch first, run `npx @expo/explore capture` on your machine.
|
||||
|
||||
A failed run shows an error code and a next action in the PR comment; see [CI troubleshooting](docs/quickstart-ci.md#diagnose-a-failed-run).
|
||||
|
||||
@@ -227,6 +298,29 @@ platforms:
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary id="controller"><strong>Device controller: agent-device or Argent</strong></summary>
|
||||
|
||||
Explore drives EAS Simulator with [agent-device](https://github.com/callstackincubator/agent-device) by default. To use [Argent](https://github.com/software-mansion/argent) instead, set it in the config or pass it for one run:
|
||||
|
||||
```yaml
|
||||
capture:
|
||||
controller: argent # agent-device (default) | argent
|
||||
```
|
||||
|
||||
```sh
|
||||
npx @expo/explore capture --controller argent
|
||||
npx @expo/explore explore:binary ./app.apk --controller argent
|
||||
```
|
||||
|
||||
Explore pins each controller's version and starts the EAS session with it. Reports and baselines record the controller, and a review compares captures made with the same one.
|
||||
|
||||
Neither controller is installed with Explore. The first run that needs one downloads its pinned npm release (agent-device 1.4 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 records one appearance: the one the app forces, else light. Explore warns when it skips one.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Keep your setup current</strong></summary>
|
||||
|
||||
@@ -252,7 +346,7 @@ There are a few ways to snapshot a release:
|
||||
|
||||
- **On demand:** in your repository's Actions tab, open **Expo Explore compare**, choose **Run workflow**, and set `base` to the last release's tag (`v1.3.0`), `head` to the new tag or release candidate (`v1.4.0-rc.1`), `scope` to `all` and `expires-in` to `never`. The run's summary links the report.
|
||||
- **Automatically, on every tag:** add the `release-review.yml` in [The comparison workflow](#compare) below. It compares each tag, release candidates included, with the last stable tag, so a release candidate is reviewed against what people have now.
|
||||
- **On your machine, without CI:** `npx @expo/explore capture:review --base v1.3.0 --head v1.4.0 --scope all --upload`, with your `eas login`. `npx @expo/explore reports` lists the runs you have kept.
|
||||
- **On your machine, without CI:** `npx @expo/explore capture --base v1.3.0 --head v1.4.0 --scope all --upload`, with your `eas login`. `npx @expo/explore reports` lists the runs you have kept.
|
||||
|
||||
`scope: all` captures every screen, not only those whose source changed, so the report shows the whole release with what changed since the last one marked; `expires-in: never` keeps its link.
|
||||
|
||||
@@ -329,46 +423,7 @@ If the sign-in can't be typed (one-time codes, email links, Sign in with Apple o
|
||||
|
||||
When a run stops early, `gap:list --dir <output>` says what blocked it.
|
||||
|
||||
## What you get
|
||||
|
||||
### A comment on every PR
|
||||
|
||||
The report links, a row per platform, and the added, removed and modified screens.
|
||||
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/readme-pr-comment-dark.png">
|
||||
<img 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">
|
||||
</picture>
|
||||
|
||||
### Compare
|
||||
|
||||
Each changed screen before and after, with the changed regions outlined.
|
||||
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/readme-compare-dark.png">
|
||||
<img 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>
|
||||
|
||||
### Screens
|
||||
|
||||
Every capture, in a section per route folder, with a route tree whose folders fold away and a **Changed** / **All** filter.
|
||||
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/readme-screens-dark.png">
|
||||
<img alt="The Screens view of a euxy review: a foldable route tree on the left with Changed and All above it, and the screens in sections named after their app/ folder (Launch, Sequencer, Settings, Patterns) with each folder path beneath, the new About screen marked Added, Activity Log and Settings marked Modified, and the Sequencer marked No visible change" src="docs/screenshots/readme-screens-light.png">
|
||||
</picture>
|
||||
|
||||
### Ask an agent about it
|
||||
|
||||
Paste this into Claude Code, Codex, Cursor, or any tool that can fetch a URL. In the Viewer, **Hand off to AI** fills it in for you:
|
||||
|
||||
```text
|
||||
Review the visual changes in this PR. Expo Explore report: <report link>
|
||||
|
||||
Fetch the link first. It explains the report's JSON API. Go through the changed screens,
|
||||
compare the before and after screenshots, and tell me which changes look intended and
|
||||
which look like regressions. For each regression, name the source file to fix.
|
||||
```
|
||||
## Additional information
|
||||
|
||||
<details>
|
||||
<summary><strong>Terms in the report</strong></summary>
|
||||
@@ -397,8 +452,6 @@ curl -s "$LINK/api/v1/screens?status=modified" | jq '.items[] | {route, status,
|
||||
|
||||
</details>
|
||||
|
||||
## Additional information
|
||||
|
||||
<details>
|
||||
<summary><strong>How it works</strong></summary>
|
||||
|
||||
@@ -408,7 +461,7 @@ curl -s "$LINK/api/v1/screens?status=modified" | jq '.items[] | {route, status,
|
||||
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.
|
||||
|
||||
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:review`, [above](#review-a-change-before-you-push-it)). The workflows' logic lives in `expo-explore ci:*` commands, so a fix reaches CI with the `@expo/explore` version the workflows pin.
|
||||
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.
|
||||
|
||||
Reports and baselines are kept for 30 days and diagnostics for 7. Hosted deployments are never deleted automatically; see [report access](docs/private-review.md).
|
||||
|
||||
@@ -423,6 +476,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`, each capture records one appearance (see [device controller](#controller)).
|
||||
|
||||
</details>
|
||||
|
||||
|
||||
@@ -179,6 +179,10 @@ imported source changed), `app-wide` (only app-wide inputs such as dependencies,
|
||||
| Not compared | No comparison was performed, including for a screen whose source changed. Not counted as a change: Explore reports what the captures show, not what the code might do. Earlier versions listed these as Source-affected |
|
||||
|
||||
A difference that rounds to 0.00% of pixels is rendering noise and counts as no difference.
|
||||
A changed region whose content only moved (a layout that grew by a device pixel, a sheet that is taller) carries
|
||||
`shift`, how far it moved in screenshot pixels, and `allRegionsMoved: true` says every region CI found moved (it
|
||||
publishes the largest eight); the Viewer labels each outline with its move. A shift does not change the verdict: a
|
||||
moved screen is still Modified.
|
||||
Accessibility only is how readers present a `modified` verdict whose visual verdict is `unchanged`; the contract has no
|
||||
separate status for it, so reports from earlier versions show it too. The accessibility tree can include content outside
|
||||
the screenshot (rows below the fold, elements under a sheet), so such a change may still be visible on a device.
|
||||
|
||||
@@ -101,9 +101,11 @@ navigation:
|
||||
# entry: src/navigation/RootNavigator.tsx
|
||||
device:
|
||||
name: iPhone 17 # Android: an AVD profile id such as pixel_7
|
||||
# pose: open # a foldable (iPhone Duo): closed (the outer display, how a session starts) | half-open | open (the inner display)
|
||||
exploration:
|
||||
scope: changes # changes | all
|
||||
capture:
|
||||
# controller: agent-device # agent-device (default) | argent (one appearance per capture until Argent can switch it; --controller overrides it for one run)
|
||||
maxMinutes: 30
|
||||
maxActions: 500
|
||||
repack: eas # eas (hosted EAS workflow job, default) | local (repack-app + eas upload on the runner)
|
||||
|
||||
|
Before Width: | Height: | Size: 452 KiB After Width: | Height: | Size: 451 KiB |
|
Before Width: | Height: | Size: 452 KiB After Width: | Height: | Size: 452 KiB |
|
Before Width: | Height: | Size: 870 KiB After Width: | Height: | Size: 847 KiB |
|
Before Width: | Height: | Size: 832 KiB After Width: | Height: | Size: 830 KiB |
|
Before Width: | Height: | Size: 151 KiB After Width: | Height: | Size: 151 KiB |
|
Before Width: | Height: | Size: 147 KiB After Width: | Height: | Size: 147 KiB |
|
Before Width: | Height: | Size: 610 KiB After Width: | Height: | Size: 642 KiB |
|
Before Width: | Height: | Size: 606 KiB After Width: | Height: | Size: 643 KiB |
@@ -1,18 +1,17 @@
|
||||
{
|
||||
"name": "@expo/explore",
|
||||
"version": "0.19.2",
|
||||
"version": "0.19.5",
|
||||
"lockfileVersion": 3,
|
||||
"requires": true,
|
||||
"packages": {
|
||||
"": {
|
||||
"name": "@expo/explore",
|
||||
"version": "0.19.2",
|
||||
"version": "0.19.5",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"@expo/repack-app": "0.10.1",
|
||||
"@types/node": "^22.19.19",
|
||||
"@zip.js/zip.js": "2.16.0",
|
||||
"agent-device": "0.21.15",
|
||||
"ajv": "^8.17.1",
|
||||
"pngjs": "7.0.0",
|
||||
"typescript": "^5.9.3",
|
||||
@@ -30,6 +29,7 @@
|
||||
"@types/react-dom": "^19.2.4",
|
||||
"@vitejs/plugin-react": "^4.7.0",
|
||||
"@xyflow/react": "^12.11.3",
|
||||
"agent-device": "0.21.15",
|
||||
"babel-plugin-react-compiler": "^1.0.0",
|
||||
"eslint": "^10.12.0",
|
||||
"eslint-plugin-react-hooks": "^7.1.1",
|
||||
@@ -48,7 +48,7 @@
|
||||
"optionalDependencies": {
|
||||
"@anthropic-ai/claude-agent-sdk": "0.3.285",
|
||||
"@openai/codex": "0.159.2",
|
||||
"eas-cli": "24.4.2"
|
||||
"eas-cli": "25.0.0"
|
||||
}
|
||||
},
|
||||
"node_modules/@0no-co/graphql.web": {
|
||||
@@ -1600,15 +1600,15 @@
|
||||
}
|
||||
},
|
||||
"node_modules/@expo/eas-build-job": {
|
||||
"version": "24.3.0",
|
||||
"resolved": "https://registry.npmjs.org/@expo/eas-build-job/-/eas-build-job-24.3.0.tgz",
|
||||
"integrity": "sha512-CyDUm8B8pSH38XZg8QzdPaxukThspSWfJ4ccUBCzBLs/qL6SknaLVswD3OTxNQmirrZUyo72DfzupSxHDZOeyw==",
|
||||
"version": "25.0.0",
|
||||
"resolved": "https://registry.npmjs.org/@expo/eas-build-job/-/eas-build-job-25.0.0.tgz",
|
||||
"integrity": "sha512-Vuai42tVopKuK2KFyTWUsW9cL1YMY1dWhFAKz+evUV5AKaMCk4dYxOYZ6tBWNhIJ15bGK3p4N0YUomlAqubFWg==",
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"dependencies": {
|
||||
"@expo/logger": "24.0.0",
|
||||
"@expo/logger": "25.0.0",
|
||||
"@expo/results": "1.0.0",
|
||||
"@expo/turtle-spawn": "24.0.0",
|
||||
"@expo/turtle-spawn": "25.0.0",
|
||||
"joi": "^17.13.1",
|
||||
"semver": "^7.6.2",
|
||||
"zod": "^4.3.5"
|
||||
@@ -1642,14 +1642,14 @@
|
||||
}
|
||||
},
|
||||
"node_modules/@expo/eas-json": {
|
||||
"version": "24.3.0",
|
||||
"resolved": "https://registry.npmjs.org/@expo/eas-json/-/eas-json-24.3.0.tgz",
|
||||
"integrity": "sha512-FIdvHmGeRFB0BoA4+aicn/tnpUUTSre4cCrN/hk6xkHOlpbjDVyl2tFaEe0RpiI1itrQ2ze/KTUYqdyecfHv0Q==",
|
||||
"version": "25.0.0",
|
||||
"resolved": "https://registry.npmjs.org/@expo/eas-json/-/eas-json-25.0.0.tgz",
|
||||
"integrity": "sha512-ilPw4O0Lnce/6lbu1GPwega8KF2GqTio9vuNFjNaGL78pfxz7GdktBsJ9JRaGtiM0LYdPa09W2FYb7DcMY8xWA==",
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"dependencies": {
|
||||
"@babel/code-frame": "7.23.5",
|
||||
"@expo/eas-build-job": "24.3.0",
|
||||
"@expo/eas-build-job": "25.0.0",
|
||||
"chalk": "4.1.2",
|
||||
"env-string": "1.0.1",
|
||||
"fs-extra": "11.2.0",
|
||||
@@ -1900,9 +1900,9 @@
|
||||
}
|
||||
},
|
||||
"node_modules/@expo/logger": {
|
||||
"version": "24.0.0",
|
||||
"resolved": "https://registry.npmjs.org/@expo/logger/-/logger-24.0.0.tgz",
|
||||
"integrity": "sha512-LezHQbZbqa7papq2ciCmwEjz4gUxe3b4oIdl3IU/wp3WGy+zQ4s+xKdDuUCbDLVkbqABBgVNqFav4ucXo1Gh/w==",
|
||||
"version": "25.0.0",
|
||||
"resolved": "https://registry.npmjs.org/@expo/logger/-/logger-25.0.0.tgz",
|
||||
"integrity": "sha512-KcNOYmeJH8GESYEjbiewg+LU98XH/yBs368XlPqmEHVZekkbOONpIzPd5AFcFRWO1BW0c2nl/58BUI876UFT8A==",
|
||||
"license": "BUSL-1.1",
|
||||
"optional": true,
|
||||
"dependencies": {
|
||||
@@ -2592,14 +2592,14 @@
|
||||
}
|
||||
},
|
||||
"node_modules/@expo/steps": {
|
||||
"version": "24.3.0",
|
||||
"resolved": "https://registry.npmjs.org/@expo/steps/-/steps-24.3.0.tgz",
|
||||
"integrity": "sha512-y0zuyUaivXiq1l7D0x9xosUbhtknDwQ4v669smGslshEYXZAuxYQJo0L6H0MRuRsaZn6N8zvfICBM+4n/n4Xeg==",
|
||||
"version": "25.0.0",
|
||||
"resolved": "https://registry.npmjs.org/@expo/steps/-/steps-25.0.0.tgz",
|
||||
"integrity": "sha512-+o04mm5akQJRX0j9TwwkdZiuNM9swLxw9DsDPtFhbWceg95gky/vc/0qF200kjZL4DEMfd/WhzngBW9aqJ0JQg==",
|
||||
"license": "BUSL-1.1",
|
||||
"optional": true,
|
||||
"dependencies": {
|
||||
"@expo/eas-build-job": "24.3.0",
|
||||
"@expo/logger": "24.0.0",
|
||||
"@expo/eas-build-job": "25.0.0",
|
||||
"@expo/logger": "25.0.0",
|
||||
"@expo/spawn-async": "^1.7.2",
|
||||
"arg": "^5.0.2",
|
||||
"fast-glob": "^3.3.2",
|
||||
@@ -2637,13 +2637,13 @@
|
||||
"optional": true
|
||||
},
|
||||
"node_modules/@expo/turtle-spawn": {
|
||||
"version": "24.0.0",
|
||||
"resolved": "https://registry.npmjs.org/@expo/turtle-spawn/-/turtle-spawn-24.0.0.tgz",
|
||||
"integrity": "sha512-HtumnPY7iVCc6vDmSmjsUEvhIPnmwVzpQ2aNPxAX+G0M2Zst88DAlItOd7mZUPSNNO8qp3izDPtqmI0fdLYPng==",
|
||||
"version": "25.0.0",
|
||||
"resolved": "https://registry.npmjs.org/@expo/turtle-spawn/-/turtle-spawn-25.0.0.tgz",
|
||||
"integrity": "sha512-XBQZ2azxh0IWozO5hCxIJt150LjIGbk6VZakeyA6UXPHp1ESenm97o0JIHOvzQNOgBV481muV88KmIWHGt0yIA==",
|
||||
"license": "BUSL-1.1",
|
||||
"optional": true,
|
||||
"dependencies": {
|
||||
"@expo/logger": "24.0.0",
|
||||
"@expo/logger": "25.0.0",
|
||||
"@expo/spawn-async": "^1.7.2"
|
||||
}
|
||||
},
|
||||
@@ -4556,6 +4556,16 @@
|
||||
"node": ">=0.4.0"
|
||||
}
|
||||
},
|
||||
"node_modules/agent-base": {
|
||||
"version": "7.1.4",
|
||||
"resolved": "https://registry.npmjs.org/agent-base/-/agent-base-7.1.4.tgz",
|
||||
"integrity": "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==",
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"engines": {
|
||||
"node": ">= 14"
|
||||
}
|
||||
},
|
||||
"node_modules/agent-cli-detector": {
|
||||
"version": "0.1.7",
|
||||
"resolved": "https://registry.npmjs.org/agent-cli-detector/-/agent-cli-detector-0.1.7.tgz",
|
||||
@@ -4573,6 +4583,7 @@
|
||||
"version": "0.21.15",
|
||||
"resolved": "https://registry.npmjs.org/agent-device/-/agent-device-0.21.15.tgz",
|
||||
"integrity": "sha512-Om1j6oNJkeKlkk8lBM+0V9bKwpxUXLMf/PDDSvAt3RFquBRqAiM58J81E0rvPQNxs6GCjhABYpwVvIAXptxjjA==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"bin": {
|
||||
"agent-device": "bin/agent-device.mjs"
|
||||
@@ -5711,9 +5722,9 @@
|
||||
}
|
||||
},
|
||||
"node_modules/eas-cli": {
|
||||
"version": "24.4.2",
|
||||
"resolved": "https://registry.npmjs.org/eas-cli/-/eas-cli-24.4.2.tgz",
|
||||
"integrity": "sha512-7tXqvzZ+4hRBS9p8Voo0PB2Ruapvqc9LLn99ZSw5m2VOQITAxdNhj8PcF+RAV3by7lMGT0oFotP7+/v3FDjpyg==",
|
||||
"version": "25.0.0",
|
||||
"resolved": "https://registry.npmjs.org/eas-cli/-/eas-cli-25.0.0.tgz",
|
||||
"integrity": "sha512-FBY3pIo/3L0s+8KK5ZpMKzlLrA5jOmr5kOpoOwkAXsxMrI4vo+LNoEsciRcOxjce9efc08GqEEPc/CxLRAWIvA==",
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"dependencies": {
|
||||
@@ -5721,11 +5732,11 @@
|
||||
"@expo/code-signing-certificates": "0.0.5",
|
||||
"@expo/config": "55.0.10",
|
||||
"@expo/config-plugins": "55.0.7",
|
||||
"@expo/eas-build-job": "24.3.0",
|
||||
"@expo/eas-json": "24.3.0",
|
||||
"@expo/eas-build-job": "25.0.0",
|
||||
"@expo/eas-json": "25.0.0",
|
||||
"@expo/env": "^1.0.0",
|
||||
"@expo/json-file": "8.3.3",
|
||||
"@expo/logger": "24.0.0",
|
||||
"@expo/logger": "25.0.0",
|
||||
"@expo/multipart-body-parser": "2.0.0",
|
||||
"@expo/osascript": "2.1.4",
|
||||
"@expo/package-manager": "1.9.10",
|
||||
@@ -5737,7 +5748,7 @@
|
||||
"@expo/results": "1.0.0",
|
||||
"@expo/rudder-sdk-node": "1.1.1",
|
||||
"@expo/spawn-async": "1.7.2",
|
||||
"@expo/steps": "24.3.0",
|
||||
"@expo/steps": "25.0.0",
|
||||
"@expo/timeago.js": "1.0.0",
|
||||
"@oclif/core": "^4.8.3",
|
||||
"@oclif/plugin-autocomplete": "^3.2.40",
|
||||
@@ -5768,7 +5779,7 @@
|
||||
"gradle-to-js": "2.0.1",
|
||||
"graphql": "16.8.1",
|
||||
"graphql-tag": "2.12.6",
|
||||
"https-proxy-agent": "5.0.1",
|
||||
"https-proxy-agent": "7.0.6",
|
||||
"ignore": "5.3.0",
|
||||
"indent-string": "4.0.0",
|
||||
"invariant": "^2.2.2",
|
||||
@@ -5817,19 +5828,6 @@
|
||||
"node": "^20.18.3 || >=22.0.0"
|
||||
}
|
||||
},
|
||||
"node_modules/eas-cli/node_modules/agent-base": {
|
||||
"version": "6.0.2",
|
||||
"resolved": "https://registry.npmjs.org/agent-base/-/agent-base-6.0.2.tgz",
|
||||
"integrity": "sha512-RZNwNclF7+MS/8bDg70amg32dyeZGZxiDuQmZxKLAlQjr3jGyLx+4Kkk58UO7D2QdgFIQCovuSuZESne6RG6XQ==",
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"dependencies": {
|
||||
"debug": "4"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">= 6.0.0"
|
||||
}
|
||||
},
|
||||
"node_modules/eas-cli/node_modules/ajv": {
|
||||
"version": "8.11.0",
|
||||
"resolved": "https://registry.npmjs.org/ajv/-/ajv-8.11.0.tgz",
|
||||
@@ -5847,20 +5845,6 @@
|
||||
"url": "https://github.com/sponsors/epoberezkin"
|
||||
}
|
||||
},
|
||||
"node_modules/eas-cli/node_modules/https-proxy-agent": {
|
||||
"version": "5.0.1",
|
||||
"resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-5.0.1.tgz",
|
||||
"integrity": "sha512-dFcAjpTQFgoLMzC2VwU+C/CbS7uRL0lWmxDITmqm7C+7F0Odmj6s9l6alZc6AELXhrnggM2CeWSXHGOdX2YtwA==",
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"dependencies": {
|
||||
"agent-base": "6",
|
||||
"debug": "4"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">= 6"
|
||||
}
|
||||
},
|
||||
"node_modules/eas-cli/node_modules/ignore": {
|
||||
"version": "5.3.0",
|
||||
"resolved": "https://registry.npmjs.org/ignore/-/ignore-5.3.0.tgz",
|
||||
@@ -7399,6 +7383,20 @@
|
||||
"url": "https://opencollective.com/express"
|
||||
}
|
||||
},
|
||||
"node_modules/https-proxy-agent": {
|
||||
"version": "7.0.6",
|
||||
"resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-7.0.6.tgz",
|
||||
"integrity": "sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw==",
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"dependencies": {
|
||||
"agent-base": "^7.1.2",
|
||||
"debug": "4"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">= 14"
|
||||
}
|
||||
},
|
||||
"node_modules/hyperlinker": {
|
||||
"version": "1.0.0",
|
||||
"resolved": "https://registry.npmjs.org/hyperlinker/-/hyperlinker-1.0.0.tgz",
|
||||
@@ -7808,13 +7806,13 @@
|
||||
}
|
||||
},
|
||||
"node_modules/jsep": {
|
||||
"version": "1.4.0",
|
||||
"resolved": "https://registry.npmjs.org/jsep/-/jsep-1.4.0.tgz",
|
||||
"integrity": "sha512-B7qPcEVE3NVkmSJbaYxvv4cHkVW7DQsZz13pUMrfS8z8Q/BuShN+gcTXrUlPiGqM2/t/EEaI030bpxMqY8gMlw==",
|
||||
"version": "1.6.0",
|
||||
"resolved": "https://registry.npmjs.org/jsep/-/jsep-1.6.0.tgz",
|
||||
"integrity": "sha512-Y8Tr54CX7B5YGAwo7/n8eumidEX3Opx98RyyQVnlHqUaZcPA8uUzL2v1rshr9ypW9Q6hNjfJtg3sL+8kaNE7TA==",
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"engines": {
|
||||
"node": ">= 10.16.0"
|
||||
"node": ">= 20.16.0"
|
||||
}
|
||||
},
|
||||
"node_modules/jsesc": {
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@expo/explore",
|
||||
"version": "0.19.2",
|
||||
"version": "0.19.5",
|
||||
"description": "Source-driven mobile app maps, deterministic CI capture, and visual reviews",
|
||||
"license": "MIT",
|
||||
"type": "module",
|
||||
@@ -63,7 +63,6 @@
|
||||
"@expo/repack-app": "0.10.1",
|
||||
"@types/node": "^22.19.19",
|
||||
"@zip.js/zip.js": "2.16.0",
|
||||
"agent-device": "0.21.15",
|
||||
"ajv": "^8.17.1",
|
||||
"pngjs": "7.0.0",
|
||||
"typescript": "^5.9.3",
|
||||
@@ -73,7 +72,7 @@
|
||||
"optionalDependencies": {
|
||||
"@anthropic-ai/claude-agent-sdk": "0.3.285",
|
||||
"@openai/codex": "0.159.2",
|
||||
"eas-cli": "24.4.2"
|
||||
"eas-cli": "25.0.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@anthropic-ai/claude-code": "2.1.285",
|
||||
@@ -83,6 +82,7 @@
|
||||
"@types/react-dom": "^19.2.4",
|
||||
"@vitejs/plugin-react": "^4.7.0",
|
||||
"@xyflow/react": "^12.11.3",
|
||||
"agent-device": "0.21.15",
|
||||
"babel-plugin-react-compiler": "^1.0.0",
|
||||
"eslint": "^10.12.0",
|
||||
"eslint-plugin-react-hooks": "^7.1.1",
|
||||
|
||||
@@ -6,7 +6,8 @@
|
||||
// [--pr https://github.com/brentvatne/euxy/pull/148]
|
||||
//
|
||||
// --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
|
||||
// --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
|
||||
// --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
|
||||
@@ -22,6 +23,7 @@ const { values: args } = parseArgs({
|
||||
select: { type: "string", default: "/settings" },
|
||||
compare: { type: "string", default: "patterns" },
|
||||
pr: { type: "string" },
|
||||
zoom: { type: "string", default: "73" },
|
||||
},
|
||||
});
|
||||
if (!args.report) {
|
||||
@@ -31,7 +33,7 @@ if (!args.report) {
|
||||
|
||||
const out = fileURLToPath(new URL("../docs/screenshots/", import.meta.url));
|
||||
const SHOTS = [
|
||||
{ file: "readme-hero", hash: "#/map", viewport: { width: 2200, height: 1240 }, click: "Fit canvas", select: args.select },
|
||||
{ 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-screens", hash: "#/screens", viewport: { width: 1760, height: 1000 } },
|
||||
];
|
||||
@@ -58,11 +60,28 @@ try {
|
||||
await page.mouse.move(400, shot.viewport.height - 30);
|
||||
await page.waitForTimeout(1500);
|
||||
}
|
||||
if (shot.zoom) {
|
||||
// Zoom around the selected screen with the wheel, which keeps it under the pointer, then pan it left and up, clear
|
||||
// of the minimap and the bottom bar. The camera stops at the first wheel step past the zoom asked for.
|
||||
const box = await page.locator(`.screen-screenshot-target[title="${shot.select}"]`).boundingBox();
|
||||
await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2);
|
||||
for (let step = 0; step < 60; step++) {
|
||||
if (Number((await page.locator(".zoom-button span").first().textContent()).replace("%", "")) >= shot.zoom) break;
|
||||
await page.keyboard.down("Control");
|
||||
await page.mouse.wheel(0, -12);
|
||||
await page.keyboard.up("Control");
|
||||
await page.waitForTimeout(150);
|
||||
}
|
||||
await page.mouse.wheel(160, 90);
|
||||
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`;
|
||||
await page.screenshot({ path });
|
||||
if (shot.framed) await writeFile(path, await stagedWindow(browser, await page.screenshot(), shot.viewport, theme));
|
||||
else await page.screenshot({ path });
|
||||
console.log(path);
|
||||
await context.close();
|
||||
}
|
||||
@@ -95,6 +114,26 @@ 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.
|
||||
|
||||
@@ -24,8 +24,8 @@ Platform, bundle id, app name and version are read from the archive; do not pass
|
||||
## What happens
|
||||
|
||||
1. Archive inspection and compatibility checks (size, simulator build, emulator ABI, sha256).
|
||||
2. `eas simulator:start` of an empty agent-device session, verified by exact session id before use.
|
||||
3. `agent-device install` of the archive straight into the session, then `open <bundle id>`.
|
||||
2. `eas simulator:start` of an empty agent-device session (an `argent` one with `--controller argent`), verified by exact session id before use.
|
||||
3. `agent-device install` of the archive straight into the session (Argent: `reinstall-app`), then `open <bundle id>`.
|
||||
4. The model explores through a small tool set (observe, act, capture, finish); app text is treated as untrusted and destructive controls (delete, reset, sign out, purchase, send, share) are blocked outside the model.
|
||||
5. The map and screenshots are written under `--output` (default `./explore-<archive>-<timestamp>`), plus `report/` for the Viewer.
|
||||
6. The report is sealed and deployed to EAS Hosting (`--no-upload` skips this; `--expires-in 7d|30d|never`).
|
||||
@@ -65,14 +65,14 @@ The model only ever sees the reference; Explore types the value into the field.
|
||||
|
||||
## Already have a session? `explore:session`
|
||||
|
||||
When the app is already installed on an agent-device EAS Simulator session you started (for example after `eas simulator:start --type agent-device --out-config-type dotenv`, `agent-device install ...`, `agent-device open ...`), skip intake and install:
|
||||
When the app is already installed on an EAS Simulator session you started (for example after `eas simulator:start --type agent-device --out-config-type dotenv`, `agent-device install ...`, `agent-device open ...`; an `--type argent` session works the same way, with Argent's tools), skip intake and install:
|
||||
|
||||
```sh
|
||||
npx @expo/explore explore:session # session from ./.env.eas-simulator or EAS_SIMULATOR_SESSION_ID; explores the app in the foreground
|
||||
npx @expo/explore explore:session <session-id> --env-file path/.env.eas-simulator --bundle-id dev.brent.euxy --json
|
||||
```
|
||||
|
||||
The app is whatever is in the foreground, else the only user-installed app; pass `--bundle-id` when neither is clear (`BUNDLE_ID_REQUIRED` lists what is installed); `--app-name`/`--app-version` label the report. The session is checked with `eas simulator:get` (must be agent-device, in progress, and the same daemon as the connection you passed), your existing `agent-device` session on the device is reused, and the same model, budgets, hints and destructive-action flags apply. The map and `report/` are written under `--output` and opened in the local Viewer (`--port N`); `--no-open` skips that and `--upload` hosts the report instead. The session is never stopped: the output ends with the `eas simulator:stop --id ...` command for when you are done.
|
||||
The app is whatever is in the foreground, else the only user-installed app; pass `--bundle-id` when neither is clear (`BUNDLE_ID_REQUIRED` lists what is installed); `--app-name`/`--app-version` label the report. The session is checked with `eas simulator:get` (must be the controller type its connection names, agent-device or argent, in progress, and the same endpoint as the connection you passed; `--controller` must agree with it), your existing `agent-device` session on the device is reused, and the same model, budgets, hints and destructive-action flags apply. The map and `report/` are written under `--output` and opened in the local Viewer (`--port N`); `--no-open` skips that and `--upload` hosts the report instead. The session is never stopped: the output ends with the `eas simulator:stop --id ...` command for when you are done.
|
||||
|
||||
## An Expo project and no build: run it from source
|
||||
|
||||
|
||||
@@ -152,18 +152,18 @@ Repeat `expo-explore doctor --json` and fix each `fail` until none remain, colle
|
||||
|
||||
## Review a change on this machine
|
||||
|
||||
Once `.expo-explore/config.yaml` is committed, the same review CI runs works locally, between any two commits:
|
||||
The same review CI runs works locally, between any two commits. It reads `.expo-explore/config.yaml` from the head commit, else from the checkout when setup wrote it but it is not committed, else uses the defaults `setup --non-interactive` would write (with several simulator profiles, the one named `explore`), so it works before setup:
|
||||
|
||||
```sh
|
||||
npx @expo/explore capture:review # HEAD against where it left the default branch
|
||||
npx @expo/explore capture:review --uncommitted # your uncommitted changes to tracked files against HEAD's base
|
||||
npx @expo/explore capture:review --base v1.3.0 --head v1.4.0 --scope all
|
||||
npx @expo/explore capture # HEAD and the uncommitted changes, against where HEAD left the default branch
|
||||
npx @expo/explore capture --committed # HEAD alone
|
||||
npx @expo/explore capture --base v1.3.0 --head v1.4.0 --scope all
|
||||
```
|
||||
|
||||
- It prints which commits it compares. Each is checked out as a detached worktree in a temporary directory, its dependencies installed (frozen lockfile, no scripts, no Explore credentials in the environment), and removed afterwards; the user's checkout, index and branches are never touched.
|
||||
- It runs both commits' code as the user (dependency installs, the app config, bundling). Before reviewing a branch the user did not write, say so and ask; credential-free installs are not a sandbox.
|
||||
- Logins: `EXPO_TOKEN` and the provider's API key when they are set; otherwise the user's `eas login` and their local `claude` or `codex` login for the configured provider. If `eas whoami` fails, tell them to run `eas login`.
|
||||
- `--uncommitted` includes tracked files only. `--include-untracked` adds untracked, non-ignored files, which are uploaded with the EAS build, so check the listed files first and never include secrets.
|
||||
- Without `--head`, the head is HEAD plus the working tree's changes, untracked non-ignored files included, which is what `eas build` uploads. It lists them; check that list for secrets the user would not want built. `--committed` reviews HEAD alone, and an `eas.json` with `cli.requireCommit: true` leaves the changes out unless `--uncommitted` is passed.
|
||||
- Every configured platform is reviewed unless `--platform` picks one. It opens the report in a local Viewer; `--upload` hosts it instead and prints the link, `--no-open` or `--json` only prints the report paths.
|
||||
- Every run is kept on this machine for 30 days: `npx @expo/explore reports list` (or `--json`) shows them, `reports open <id|latest>` reopens one in the local Viewer, and `reports upload <id>` hosts it without capturing again. Run bare in a terminal, `reports` is an arrow-key picker for the user.
|
||||
- To host a report after the fact, run `npx @expo/explore report:upload <report.zip>...` with the paths it printed (or the `--output` directory's `<platform>/report.zip`), one per platform. It uses the same project as `--upload` and does not capture again.
|
||||
@@ -176,7 +176,7 @@ npx @expo/explore capture:review --base v1.3.0 --head v1.4.0 --scope all
|
||||
|
||||
- **Releases.** Unless the user asks otherwise, compare each release with the last stable release, with `scope: all` (every screen, so the report shows the whole release with what changed marked) and, when hosted previews are on, `expires-in: never` (the link outlives the 30-day artifact). For every tag as it is pushed, add the `release-review.yml` from the README's "Compare any two commits" section: it finds the newest earlier tag without a `-` (so a release candidate is compared with the last stable release) and calls `explore-compare.yml` with `secrets: inherit` and `permissions: { contents: read, actions: read }`. A nightly compares with yesterday's tag; a release branch with `main`.
|
||||
- **Once, on demand.** The workflow must be on the default branch to be dispatched: `gh workflow run explore-compare.yml -f base=<ref> -f head=<ref> -f scope=all -f expires-in=never`, or **Run workflow** under Actions → Expo Explore compare.
|
||||
- **Without CI.** `npx @expo/explore capture:review --base <ref> --head <ref> --scope all --upload` runs the same comparison on this machine (see the previous section).
|
||||
- **Without CI.** `npx @expo/explore capture --base <ref> --head <ref> --scope all --upload` runs the same comparison on this machine (see the previous section).
|
||||
- Call the workflow once per workflow run (a second call in the same run reuses the first one's artifact names). A `base` the baseline workflow captured in the last 30 days is reused, so only `head` is captured.
|
||||
- To verify, run it once on the latest tag and open the run's summary: it lists each platform's result and links the report.
|
||||
|
||||
|
||||
@@ -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, and gives a prompt to copy for trying it on your app 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 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 numbered quick-start steps for reviewing a change to your own app, a prompt to copy for exploring any build, 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
|
||||
@@ -53,18 +53,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/Modified badges, 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 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.
|
||||
|
||||
## 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`).
|
||||
2. **Try it on your app**: one sentence and a prompt to paste into Claude Code or Codex that gets a simulator build of any app (Expo or not, or just a build) and runs `explore:binary` on it. After its collapsibles, **Review a change before you push it**: one sentence, a prompt that runs `capture:review` locally (the explore-setup skill's "Review a change on this machine" section) on a set-up app, and the `reports` picker image (`readme-reports-*.png`) with one sentence on saved runs, at the top level, not inside a collapsible. Each section keeps its own "Run it yourself"; never put one section between another's prompt and its collapsibles.
|
||||
3. **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).
|
||||
4. **What you get**: the PR comment, Compare, and Screens, each a heading, one line, and its picture, then a prompt for asking an agent about a report.
|
||||
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**: the smallest set of steps to see a review of the reader's own Expo app on their machine, numbered and with nothing optional in them: make the app buildable on EAS (login, init, bundle identifier, a simulator profile named `explore`) and commit (the before build is the last commit), then edit a screen near its top and run `capture`, which reviews uncommitted changes as `eas build` would upload them and uses setup's defaults when there is no config. After the steps, a prompt that has Claude Code or Codex do the same through the explore-setup skill's "Review a change on this machine" section. 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 and a prompt to paste into Claude Code or Codex that gets a simulator build of any app (Expo or not, or just a build) and runs `explore:binary` on it. Each section keeps its own "Run it yourself"; never put one section between another's prompt and its collapsibles.
|
||||
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`), 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. 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;
|
||||
|
||||
@@ -233,7 +233,7 @@ async function hashDirectory(root: string, maxBytes: number): Promise<{ sha256:
|
||||
type TarVisitor = (entry: { name: string; type: string; size: number; mode: number }, contents: () => Promise<Buffer>, skip: () => Promise<void>) => Promise<boolean | void>;
|
||||
|
||||
/** Walk a gzip tarball once; `visit` returns true to stop. Long GNU names are honoured; nothing is written. */
|
||||
async function walkTar(path: string, visit: TarVisitor): Promise<void> {
|
||||
export async function walkTar(path: string, visit: TarVisitor): Promise<void> {
|
||||
const stream = createReadStream(path).pipe(createGunzip());
|
||||
const iterator = stream[Symbol.asyncIterator]();
|
||||
let buffer = Buffer.alloc(0);
|
||||
@@ -296,7 +296,7 @@ async function tarEntry(path: string, match: (name: string) => boolean): Promise
|
||||
return found;
|
||||
}
|
||||
|
||||
function safeRelativePath(name: string): string | undefined {
|
||||
export function safeRelativePath(name: string): string | undefined {
|
||||
const parts = name.replace(/^\.\//, "").split("/").filter(part => part.length);
|
||||
if (!parts.length || parts.some(part => part === "." || part === ".." || part.includes("\\") || part.includes("\0"))) return undefined;
|
||||
return parts.join("/");
|
||||
|
||||
@@ -7,7 +7,7 @@ import type { CaptureSetupAction } from "../config/explore-config.js";
|
||||
import { createExplorationInputs, explorationSecretNames } from "../config/exploration-inputs.js";
|
||||
import type { ExploreStore, PreparedArtifact } from "../map/store.js";
|
||||
import { CiError } from "../shared/ci-errors.js";
|
||||
import type { ActionKind, ActionRisk, Artifact, ElementRole, ExploreMap, ObservedElement, Observation, Screen } from "../types.js";
|
||||
import type { ActionKind, ActionRisk, Artifact, Controller, ElementRole, ExploreMap, ObservedElement, Observation, Screen } from "../types.js";
|
||||
|
||||
/** One look at the device: accessibility always, a PNG when the host could take a safe one. */
|
||||
export type BlackBoxFrame = {
|
||||
@@ -278,7 +278,7 @@ function markPressableGroups(nodes: readonly Record<string, unknown>[]): void {
|
||||
}
|
||||
}
|
||||
|
||||
export function elementsOf(nodes: readonly Record<string, unknown>[], allow: readonly string[]): Array<Omit<ObservedElement, "elementId">> {
|
||||
export function elementsOf(nodes: readonly Record<string, unknown>[], allow: readonly string[], controller: Controller = "agent-device"): Array<Omit<ObservedElement, "elementId">> {
|
||||
markPressableGroups(nodes);
|
||||
const occurrences = new Map<string, number>();
|
||||
const out: Array<Omit<ObservedElement, "elementId">> = [];
|
||||
@@ -306,7 +306,7 @@ export function elementsOf(nodes: readonly Record<string, unknown>[], allow: rea
|
||||
const occurrence = (occurrences.get(key) ?? 0) + 1;
|
||||
occurrences.set(key, occurrence);
|
||||
const rect = node.rect && typeof node.rect === "object" ? node.rect as Record<string, unknown> : undefined;
|
||||
out.push({ role, label, ...(identifier ? { identifier } : {}), occurrence, controller: "agent-device",
|
||||
out.push({ role, label, ...(identifier ? { identifier } : {}), occurrence, controller,
|
||||
actions: role === "field" ? ["fill"] : role === "toggle" ? ["press"] : ["press"],
|
||||
risk: riskOf(label, allow), actionable: true, enabled: node.enabled !== false, visible: true,
|
||||
...(rect && typeof rect.x === "number" && typeof rect.y === "number" && typeof rect.width === "number" && typeof rect.height === "number"
|
||||
@@ -497,7 +497,7 @@ export async function runBlackBoxExploration(options: BlackBoxExplorerOptions):
|
||||
for (const part of loose) seen.parts.add(part);
|
||||
seen.loadingOnly &&= loading;
|
||||
evidence.set(screen.id, seen);
|
||||
for (const element of elementsOf(frame.nodes, allow)) {
|
||||
for (const element of elementsOf(frame.nodes, allow, map.run.controller)) {
|
||||
const id = elementId(screen.id, element);
|
||||
if (!screen.elementIds.includes(id)) {
|
||||
screen.elementIds.push(id);
|
||||
@@ -538,7 +538,7 @@ export async function runBlackBoxExploration(options: BlackBoxExplorerOptions):
|
||||
}
|
||||
screenshotArtifactId = artifact.id;
|
||||
}
|
||||
const elements = elementsOf(frame.nodes, allow).map(element => ({ elementId: elementId(screen.id, element), ...element }));
|
||||
const elements = elementsOf(frame.nodes, allow, map.run.controller).map(element => ({ elementId: elementId(screen.id, element), ...element }));
|
||||
const observation: Observation = { id: observationId, screenId: screen.id, variantId: variant.id, capturedAt: frame.capturedAt, surfaceScope: "app",
|
||||
fingerprints: { combined: screenEvidenceKey(frame.nodes), accessibility: accessibilitySha, ...(screenshotArtifactId ? { visual: map.artifacts.find(item => item.id === screenshotArtifactId)!.sha256 } : {}) },
|
||||
elementIds: elements.map(element => element.elementId), elements, accessibilityArtifactId: accessibilityArtifact.id, ...(screenshotArtifactId ? { screenshotArtifactId } : {}) };
|
||||
|
||||
@@ -6,12 +6,14 @@ import { join } from "node:path";
|
||||
import { createCiAgentSession, type CiAgentSession, type CiAgentSessionConfig } from "../capture/agent/session.js";
|
||||
import { createLocalCiAgentSession } from "../capture/agent/session-local.js";
|
||||
import type { CiAgentProviderName } from "../capture/agent/provider.js";
|
||||
import { AGENT_DEVICE_VERSION, CONTROLLER_SESSION, baseEnvironment, isRecord } from "../capture/common.js";
|
||||
import { CONTROLLER_SESSION, baseEnvironment, isRecord } from "../capture/common.js";
|
||||
import { controllerData, defaultRunner, openedSimulatorDevice } from "../capture/controller.js";
|
||||
import type { CommandRequest, CommandResult } from "../capture/run.js";
|
||||
import { executeCaptureSetup } from "../capture/setup-actions.js";
|
||||
import { SIMULATOR_DOTENV_FILE_NAME, SIMULATOR_DOTENV_HEADER, assertSimulatorSessionIdentity, assertSimulatorStopped, readSimulatorDotenvHandoff,
|
||||
assertAttachedSimulatorSession, resolveAttachedSimulatorSession, simulatorOsVersion, simulatorStartFailure, type ActiveSimulatorRuntime, type SimulatorConnection } from "../capture/simulator.js";
|
||||
assertAttachedSimulatorSession, connectionController, controllerVersion, resolveAttachedSimulatorSession, simulatorOsVersion, simulatorStartFailure, type ActiveSimulatorRuntime, type SimulatorConnection } from "../capture/simulator.js";
|
||||
import { argentControllerInvocation } from "../capture/controller-invocation.js";
|
||||
import { agentDeviceLauncher, ensureController } from "../shared/controller-cache.js";
|
||||
import { DEFAULT_ANDROID_DEVICE } from "../config/explore-config.js";
|
||||
import { createExplorationInputs } from "../config/exploration-inputs.js";
|
||||
import { ExploreStore, getCoverage } from "../map/store.js";
|
||||
@@ -46,6 +48,8 @@ export type BinaryExploreOptions = {
|
||||
owner?: string;
|
||||
/** EAS project slug the sessions run under; created on first use. */
|
||||
project?: string;
|
||||
/** The session's device controller; agent-device unless Argent is chosen. explore:session takes it from the session. */
|
||||
controller?: "agent-device" | "argent";
|
||||
environment?: NodeJS.ProcessEnv;
|
||||
runner?: typeof defaultRunner;
|
||||
createSession?: (config: CiAgentSessionConfig, options: { env: NodeJS.ProcessEnv; auth: ModelAuth }) => CiAgentSession;
|
||||
@@ -64,10 +68,19 @@ export type BinaryExploreResult = {
|
||||
durationMs: number;
|
||||
};
|
||||
|
||||
/** The command and environment that reach a session's controller: agent-device's CLI with its daemon, or the Argent bridge. */
|
||||
type ControllerInvocation = { command: string; environment: NodeJS.ProcessEnv };
|
||||
|
||||
async function argentInvocation(connection: SimulatorConnection, work: string, platform: Platform, environment: NodeJS.ProcessEnv, bundleId?: string): Promise<ControllerInvocation> {
|
||||
return argentControllerInvocation({ directory: work, connection, platform, environment: baseEnvironment(environment), sourceEnvironment: environment, ...(bundleId ? { bundleId } : {}) });
|
||||
}
|
||||
|
||||
/** The daemon refuses a second session on a busy device; the caller's own `agent-device` session (from install/open) is reused instead. */
|
||||
function daemonSessions(runner: typeof defaultRunner, connection: SimulatorConnection, work: string, platform: Platform, environment: NodeJS.ProcessEnv): { name: string; device: string }[] {
|
||||
// Argent has no named sessions to share; its tool-server serves every caller.
|
||||
if (connectionController(connection) === "argent") return [];
|
||||
try {
|
||||
const result = runner({ command: packageBin("agent-device", "agent-device"), args: ["session", "list", "--json"], cwd: work, timeoutMs: 60_000,
|
||||
const result = runner({ command: agentDeviceLauncher(environment), args: ["session", "list", "--json"], cwd: work, timeoutMs: 60_000,
|
||||
environment: { ...baseEnvironment(environment), AGENT_DEVICE_DAEMON_BASE_URL: connection.daemonBaseUrl, AGENT_DEVICE_DAEMON_AUTH_TOKEN: connection.daemonAuthToken } });
|
||||
const data = controllerData(result.stdout, "session list");
|
||||
const sessions = Array.isArray(data.sessions) ? data.sessions : [];
|
||||
@@ -119,11 +132,11 @@ const named = (apps: { bundleId: string | undefined; name: string | undefined }[
|
||||
};
|
||||
|
||||
/** Finds the app to explore when the caller named none: the one the session has in the foreground, else the only user-installed app. */
|
||||
export function resolveSessionApp(runner: typeof defaultRunner, connection: SimulatorConnection, work: string, platform: Platform, device: string, controllerSession: string | undefined, environment: NodeJS.ProcessEnv): { bundleId: string; name?: string } {
|
||||
export function resolveSessionApp(runner: typeof defaultRunner, connection: SimulatorConnection, work: string, platform: Platform, device: string, controllerSession: string | undefined, environment: NodeJS.ProcessEnv, invocation?: ControllerInvocation): { bundleId: string; name?: string } {
|
||||
const run = (args: string[]): Record<string, unknown> | undefined => {
|
||||
try {
|
||||
const result = runner({ command: packageBin("agent-device", "agent-device"), args: [...args, ...(platform === "ios" ? ["--device", device] : []), "--platform", platform, "--json"], cwd: work, timeoutMs: 60_000,
|
||||
environment: { ...baseEnvironment(environment), AGENT_DEVICE_DAEMON_BASE_URL: connection.daemonBaseUrl, AGENT_DEVICE_DAEMON_AUTH_TOKEN: connection.daemonAuthToken } });
|
||||
const result = runner({ command: invocation?.command ?? agentDeviceLauncher(environment), args: [...args, ...(platform === "ios" ? ["--device", device] : []), "--platform", platform, "--json"], cwd: work, timeoutMs: 60_000,
|
||||
environment: invocation?.environment ?? { ...baseEnvironment(environment), AGENT_DEVICE_DAEMON_BASE_URL: connection.daemonBaseUrl, AGENT_DEVICE_DAEMON_AUTH_TOKEN: connection.daemonAuthToken } });
|
||||
return controllerData(result.stdout, args[0]!);
|
||||
} catch { return undefined; }
|
||||
};
|
||||
@@ -260,11 +273,20 @@ export type ConnectedSessionExploration = {
|
||||
export async function exploreConnectedSession(ctx: ConnectedSessionExploration): Promise<{ runtime: ActiveSimulatorRuntime; exploration: BlackBoxExplorerResult }> {
|
||||
const { connection, platform, device, bundleId, app, install, work, runner, environment, secrets, inputs, say, now, limits, store, map, model, sessionJson, launchUrl, hints, allowDestructive } = ctx;
|
||||
const controllerSession = ctx.controllerSession ?? CONTROLLER_SESSION;
|
||||
const controllerConfig = join(work, "agent-device.json");
|
||||
await writeFile(controllerConfig, "{}\n", { flag: "wx", mode: 0o400 });
|
||||
const controllerEnvironment = { ...baseEnvironment(environment), AGENT_DEVICE_CONFIG: controllerConfig, AGENT_DEVICE_DAEMON_BASE_URL: connection.daemonBaseUrl,
|
||||
AGENT_DEVICE_DAEMON_AUTH_TOKEN: connection.daemonAuthToken, AGENT_DEVICE_SESSION: controllerSession, AGENT_DEVICE_SESSION_LOCK: "reject", AGENT_DEVICE_PLATFORM: platform };
|
||||
const agentDevice = packageBin("agent-device", "agent-device");
|
||||
const controllerKind = connectionController(connection);
|
||||
const controllerName = controllerKind === "argent" ? "Argent" : "agent-device";
|
||||
if (controllerKind === "argent") await ensureController("argent", { environment, progress: say });
|
||||
let agentDevice: string;
|
||||
let controllerEnvironment: NodeJS.ProcessEnv;
|
||||
if (controllerKind === "argent") {
|
||||
({ command: agentDevice, environment: controllerEnvironment } = await argentInvocation(connection, work, platform, environment, bundleId));
|
||||
} else {
|
||||
const controllerConfig = join(work, "agent-device.json");
|
||||
await writeFile(controllerConfig, "{}\n", { flag: "wx", mode: 0o400 });
|
||||
controllerEnvironment = { ...baseEnvironment(environment), AGENT_DEVICE_CONFIG: controllerConfig, AGENT_DEVICE_DAEMON_BASE_URL: connection.daemonBaseUrl,
|
||||
AGENT_DEVICE_DAEMON_AUTH_TOKEN: connection.daemonAuthToken, AGENT_DEVICE_SESSION: controllerSession, AGENT_DEVICE_SESSION_LOCK: "reject", AGENT_DEVICE_PLATFORM: platform };
|
||||
agentDevice = agentDeviceLauncher(environment);
|
||||
}
|
||||
const deviceArgs = platform === "ios" ? ["--device", device] : [];
|
||||
const controller = (args: string[], timeoutMs = 90_000): CommandResult => {
|
||||
// Session flags go before a `--` separator so model-chosen text (`type -h`, a URL, a label) is never read as a flag.
|
||||
@@ -275,22 +297,23 @@ export async function exploreConnectedSession(ctx: ConnectedSessionExploration):
|
||||
};
|
||||
const failureText = (error: unknown): string => lastLine(redactSecrets(error instanceof Error ? error.message : String(error), secrets)).slice(0, 400);
|
||||
const version = runner({ command: agentDevice, args: ["--version"], cwd: work, environment: controllerEnvironment, timeoutMs: 30_000 }).stdout.trim();
|
||||
if (version !== AGENT_DEVICE_VERSION) throw binaryError("EXPLORE_TOOLS_MISSING", `agent-device ${AGENT_DEVICE_VERSION} is required (found ${version || "none"}).`, "Reinstall @expo/explore.");
|
||||
if (version !== controllerVersion(controllerKind)) throw binaryError("EXPLORE_TOOLS_MISSING", `${controllerName} ${controllerVersion(controllerKind)} is required (found ${version || "none"}).`, "Reinstall @expo/explore.");
|
||||
|
||||
if (install) {
|
||||
say(`installing ${install.kind === "android-apk" ? "the APK" : "the app"} on session ${connection.sessionId}`);
|
||||
try { controller(["install", install.path, "--json"], 15 * 60_000); }
|
||||
catch (error) { throw binaryError("APP_INSTALL_FAILED", `agent-device 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 }); }
|
||||
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 }); }
|
||||
}
|
||||
const opened = controller(["open", bundleId, "--level", "full", "--json"], 2 * 60_000);
|
||||
const openedDevice = openedSimulatorDevice(opened.stdout, bundleId, "initial app open", platform, controllerSession);
|
||||
const data = controllerData(opened.stdout, "initial app open");
|
||||
const deviceData = data.device && typeof data.device === "object" ? data.device as Record<string, unknown> : {};
|
||||
const observed = (key: string): string => { const value = deviceData[key] ?? data[key]; return typeof value === "string" && value.trim() ? value : "unknown"; };
|
||||
const runtime = { provider: "eas-simulator", controller: "agent-device", controllerPackageVersion: AGENT_DEVICE_VERSION, easCliVersion: "unknown", platform, controllerDeviceId: openedDevice.deviceId,
|
||||
const runtime = { provider: "eas-simulator", controller: controllerKind, controllerPackageVersion: controllerVersion(controllerKind), easCliVersion: "unknown", platform, controllerDeviceId: openedDevice.deviceId,
|
||||
deviceModel: openedDevice.deviceModel, osVersion: observed("osVersion"), locale: observed("locale"), orientation: observed("orientation") === "landscape" ? "landscape" : "portrait",
|
||||
colorScheme: observed("colorScheme") === "dark" ? "dark" : "light" } as ActiveSimulatorRuntime;
|
||||
try { runtime.osVersion = await simulatorOsVersion(sessionJson(), runtime.controllerDeviceId, fetch, platform); } catch { /* descriptive only */ }
|
||||
// Argent's `open` reports the OS version itself (list-devices); agent-device's comes from the session's preview.
|
||||
if (runtime.osVersion === "unknown" || controllerKind !== "argent") try { runtime.osVersion = await simulatorOsVersion(sessionJson(), runtime.controllerDeviceId, fetch, platform); } catch { /* descriptive only */ }
|
||||
map.run.deviceId = runtime.controllerDeviceId;
|
||||
map.run.environment = { deviceModel: runtime.deviceModel, osVersion: runtime.osVersion, locale: runtime.locale, orientation: runtime.orientation, colorScheme: runtime.colorScheme };
|
||||
map.run.status = "exploring";
|
||||
@@ -474,7 +497,13 @@ export async function runSessionExploration(options: SessionExploreOptions): Pro
|
||||
try { connection = await resolveAttachedSimulatorSession(environment, options.envFile, options.session); }
|
||||
catch (error) {
|
||||
throw binaryError("SESSION_NOT_PROVIDED", `No EAS Simulator session connection was found: ${error instanceof Error ? error.message : String(error)}`,
|
||||
"Start one with `eas simulator:start --type agent-device --out-config-type dotenv` and run explore:session in that directory (or pass --env-file / set EAS_SIMULATOR_SESSION_ID, AGENT_DEVICE_DAEMON_BASE_URL and AGENT_DEVICE_DAEMON_AUTH_TOKEN).");
|
||||
"Start one with `eas simulator:start --type agent-device --out-config-type dotenv` (or `--type argent`) and run explore:session in that directory (or pass --env-file / set EAS_SIMULATOR_SESSION_ID with AGENT_DEVICE_DAEMON_BASE_URL and AGENT_DEVICE_DAEMON_AUTH_TOKEN, or ARGENT_TOOLS_URL).");
|
||||
}
|
||||
const sessionController = connectionController(connection);
|
||||
if (!options.runner) await ensureController(sessionController, { environment, progress: say });
|
||||
if (options.controller && options.controller !== sessionController) {
|
||||
throw binaryError("CONTROLLER_MISMATCH", `--controller ${options.controller} was passed, but the session is driven by ${sessionController}.`,
|
||||
`Drop --controller, or start a session with \`eas simulator:start --type ${options.controller}\`.`, { sessionId: connection.sessionId });
|
||||
}
|
||||
if (!environment.EXPO_TOKEN?.trim() && !environment.EXPO_SESSION_SECRET?.trim() && !(await easLoggedIn(runner, environment))) {
|
||||
throw binaryError("EXPO_LOGIN_REQUIRED", "No EAS login was found.", "Run `eas login` or set EXPO_TOKEN, then rerun explore:session.");
|
||||
@@ -495,7 +524,7 @@ export async function runSessionExploration(options: SessionExploreOptions): Pro
|
||||
let device = options.device ?? "";
|
||||
const app = { name: options.appName ?? options.bundleId ?? "app", bundleId: options.bundleId ?? "app", ...(options.version ? { version: options.version } : {}) };
|
||||
const secrets = [environment.EXPO_TOKEN ?? "", connection.daemonAuthToken, ...inputs.values].filter(Boolean);
|
||||
const map: ExploreMap = { contract: CONTRACT, revision: 0, run: { id: randomUUID(), name: app.name, platform, controller: "agent-device", exploration: "black-box", bundleId: app.bundleId, status: "draft",
|
||||
const map: ExploreMap = { contract: CONTRACT, revision: 0, run: { id: randomUUID(), name: app.name, platform, controller: sessionController, exploration: "black-box", bundleId: app.bundleId, status: "draft",
|
||||
createdAt: new Date(now()).toISOString(), updatedAt: new Date(now()).toISOString(), build: { ...(app.version ? { version: app.version } : {}), source: "unknown" }, environment: {}, limits },
|
||||
artifacts: [], screens: [], variants: [], observations: [], elements: [], actionAttempts: [], transitions: [], journeys: [], frontier: [], gaps: [] };
|
||||
try {
|
||||
@@ -504,7 +533,7 @@ export async function runSessionExploration(options: SessionExploreOptions): Pro
|
||||
try { info = assertAttachedSimulatorSession(sessionJson(), connection, options.platform); }
|
||||
catch (error) {
|
||||
throw binaryError("SESSION_UNAVAILABLE", `EAS Simulator session ${connection.sessionId} cannot be explored: ${lastLine(redactSecrets(error instanceof Error ? error.message : String(error), secrets))}`,
|
||||
"Check `eas simulator:list`; the session must be in progress, of type agent-device, and match the connection you passed.", { sessionId: connection.sessionId });
|
||||
`Check \`eas simulator:list\`; the session must be in progress, of type ${sessionController}, and match the connection you passed.`, { sessionId: connection.sessionId });
|
||||
}
|
||||
platform = info.platform;
|
||||
const candidates = daemonSessions(runner, connection, work, platform, environment).filter(item => !device || item.device === device);
|
||||
@@ -514,7 +543,8 @@ export async function runSessionExploration(options: SessionExploreOptions): Pro
|
||||
if (existing) say(`reusing agent-device session "${existing.name}" on ${existing.device}`);
|
||||
device = device || existing?.device || (platform === "ios" ? DEFAULT_IOS_DEVICE : DEFAULT_ANDROID_DEVICE);
|
||||
if (!options.bundleId) {
|
||||
const resolved = resolveSessionApp(runner, connection, work, platform, device, existing?.name, environment);
|
||||
const resolved = resolveSessionApp(runner, connection, work, platform, device, existing?.name, environment,
|
||||
sessionController === "argent" ? await argentInvocation(connection, work, platform, environment) : undefined);
|
||||
app.bundleId = resolved.bundleId;
|
||||
if (!options.appName) app.name = resolved.name ?? app.bundleId;
|
||||
map.run.bundleId = app.bundleId;
|
||||
@@ -582,7 +612,10 @@ export async function runBinaryExploration(options: BinaryExploreOptions): Promi
|
||||
let exploration: BlackBoxExplorerResult | undefined;
|
||||
let owner = options.owner ?? "";
|
||||
const project = options.project ?? DEFAULT_BINARY_PROJECT;
|
||||
const map: ExploreMap = { contract: CONTRACT, revision: 0, run: { id: randomUUID(), name: archive.appName, platform, controller: "agent-device", exploration: "black-box", bundleId, status: "draft",
|
||||
const controller = options.controller ?? "agent-device";
|
||||
// Fetched before the paid session starts, so a blocked download costs nothing.
|
||||
if (!options.runner) await ensureController(controller, { environment, progress: say });
|
||||
const map: ExploreMap = { contract: CONTRACT, revision: 0, run: { id: randomUUID(), name: archive.appName, platform, controller, exploration: "black-box", bundleId, status: "draft",
|
||||
createdAt: new Date(now()).toISOString(), updatedAt: new Date(now()).toISOString(),
|
||||
build: { ...(archive.version ? { version: archive.version } : {}), ...(archive.buildNumber ? { number: archive.buildNumber } : {}), hash: archive.sha256, source: "local" },
|
||||
environment: { deviceModel: device }, limits }, artifacts: [], screens: [], variants: [], observations: [], elements: [], actionAttempts: [], transitions: [], journeys: [], frontier: [], gaps: [] };
|
||||
@@ -610,7 +643,7 @@ export async function runBinaryExploration(options: BinaryExploreOptions): Promi
|
||||
await writeFile(dotenvPath, SIMULATOR_DOTENV_HEADER, { flag: "wx", mode: 0o600 });
|
||||
let startError: unknown;
|
||||
try {
|
||||
const started = eas(["simulator:start", "--name", sessionName, "--platform", platform, "--device", device, "--type", "agent-device", "--package-version", AGENT_DEVICE_VERSION,
|
||||
const started = eas(["simulator:start", "--name", sessionName, "--platform", platform, "--device", device, "--type", controller, "--package-version", controllerVersion(controller), "--public-link",
|
||||
"--max-duration-minutes", String(limits.maxDurationMinutes + 5), "--out-config-type", "dotenv", "--non-interactive"], 20 * 60_000);
|
||||
if (started.status !== 0) throw new Error(started.stderr || started.stdout || "eas simulator:start failed");
|
||||
} catch (error) { startError = error; }
|
||||
|
||||
@@ -18,6 +18,19 @@ export function resolveColorSchemes(appearance: AppearanceSetting, appConfig: Re
|
||||
return ["light"];
|
||||
}
|
||||
|
||||
/**
|
||||
* What an Argent capture renders: one pass, since Argent cannot switch the device's appearance yet
|
||||
* (software-mansion/argent#1509). An app that forces a style renders it on any device; any other app renders as the
|
||||
* fresh simulator starts, light. Requested schemes that pass cannot show are reported as skipped.
|
||||
*/
|
||||
export function argentColorSchemes(requested: readonly ColorScheme[], appConfig: Record<string, unknown> | undefined, platform: string): { schemes: ColorScheme[]; skipped: ColorScheme[] } {
|
||||
const platformConfig = appConfig?.[platform];
|
||||
const declared = (platformConfig && typeof platformConfig === "object" ? (platformConfig as Record<string, unknown>).userInterfaceStyle : undefined)
|
||||
?? appConfig?.userInterfaceStyle;
|
||||
const scheme: ColorScheme = declared === "dark" ? "dark" : "light";
|
||||
return { schemes: [scheme], skipped: requested.filter(item => item !== scheme) };
|
||||
}
|
||||
|
||||
export function parseAppearance(value: unknown, path: string): AppearanceSetting {
|
||||
if (value === undefined || value === "auto") return "auto";
|
||||
const list = Array.isArray(value) ? value : [value];
|
||||
|
||||
@@ -0,0 +1,143 @@
|
||||
/**
|
||||
* The Argent controller's command line: Explore runs it where it would run agent-device, with the same
|
||||
* arguments. Each command becomes `argent run <tool> --args <json>` calls, as EAS Simulator recommends
|
||||
* driving an `argent` session, with the session's ARGENT_TOOLS_URL and ARGENT_AUTH_TOKEN in the environment.
|
||||
*/
|
||||
import { spawnSync } from "node:child_process";
|
||||
import { appendFile, copyFile, mkdir, readFile, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
|
||||
import { dirname, join } from "node:path";
|
||||
import { createRequire } from "node:module";
|
||||
import type { DecodedFrame } from "../shared/png-evidence.js";
|
||||
import { ArgentCallError, runBridgeCommand, type ArgentBridgeState, type ArgentPlatform, type ArgentTree } from "./argent-driver.js";
|
||||
import { ARGENT_VERSION } from "../shared/argent-version.js";
|
||||
import { ensureController } from "../shared/controller-cache.js";
|
||||
|
||||
const ARGENT_CALL_TIMEOUT_MS = 180_000;
|
||||
|
||||
async function readState(path: string): Promise<ArgentBridgeState> {
|
||||
try { return JSON.parse(await readFile(path, "utf8")) as ArgentBridgeState; }
|
||||
catch { return { generation: 0 }; }
|
||||
}
|
||||
|
||||
/** Written whole and renamed into place, so a command stopped mid-write never leaves a torn state. */
|
||||
async function writeState(path: string, state: ArgentBridgeState): Promise<void> {
|
||||
const temporary = `${path}.${process.pid}.tmp`;
|
||||
await writeFile(temporary, JSON.stringify(state), { mode: 0o600 });
|
||||
await rename(temporary, path);
|
||||
}
|
||||
|
||||
/** A call's arguments for the debug log: text that could be typed into a field is logged by length only. */
|
||||
function loggedArgs(args: Record<string, unknown>): Record<string, unknown> {
|
||||
return Object.fromEntries(Object.entries(args).map(([key, value]) => key === "text" && typeof value === "string" ? [key, `<${value.length} characters>`]
|
||||
: key === "steps" && Array.isArray(value) ? [key, `<${value.length} steps>`] : [key, value]));
|
||||
}
|
||||
|
||||
/** What a call answered, for the debug log: a tree's shape, not its contents. */
|
||||
function summarize(tool: string, value: unknown): unknown {
|
||||
if (!value || typeof value !== "object") return value;
|
||||
if (tool !== "ui-tree") return Object.keys(value);
|
||||
const tree = value as ArgentTree;
|
||||
let nodes = 0;
|
||||
const walk = (node: { children?: unknown[] }) => { nodes++; (node.children ?? []).forEach(child => walk(child as { children?: unknown[] })); };
|
||||
(tree.roots ?? []).forEach(walk);
|
||||
return { foregroundApp: tree.foregroundApp, alertVisible: tree.alertVisible, keyboardVisible: tree.keyboardVisible, truncated: tree.truncated,
|
||||
screen: tree.screen, nodes, roots: (tree.roots ?? []).map(root => [root.type ?? null, root.bundleId ?? null, (root.children ?? []).length]) };
|
||||
}
|
||||
|
||||
async function main(): Promise<number> {
|
||||
const environment = process.env;
|
||||
const statePath = environment.EXPLORE_ARGENT_STATE;
|
||||
const platform = environment.EXPLORE_ARGENT_PLATFORM as ArgentPlatform | undefined;
|
||||
const toolsUrl = environment.ARGENT_TOOLS_URL;
|
||||
if (!statePath || (platform !== "ios" && platform !== "android")) {
|
||||
process.stdout.write(JSON.stringify({ success: false, error: { code: "INVALID_ARGS", message: "The Argent controller needs EXPLORE_ARGENT_STATE and EXPLORE_ARGENT_PLATFORM." } }));
|
||||
return 1;
|
||||
}
|
||||
const argv = process.argv.slice(2);
|
||||
if (argv[0] !== "--version" && !toolsUrl) {
|
||||
// Without a URL the Argent client would start a local tool-server; Explore only drives the session's own.
|
||||
process.stdout.write(JSON.stringify({ success: false, error: { code: "INVALID_ARGS", message: "ARGENT_TOOLS_URL is not set for the Argent controller." } }));
|
||||
return 1;
|
||||
}
|
||||
// EXPLORE_ARGENT_LOG_DIR (opt-in): every Argent call this bridge makes, how long it took, and the shape of what it read.
|
||||
const logPath = environment.EXPLORE_ARGENT_LOG_DIR
|
||||
? join(environment.EXPLORE_ARGENT_LOG_DIR, `argent-${platform}-${environment.EXPLORE_ARGENT_LOG_NAME ?? "bridge"}.jsonl`) : undefined;
|
||||
const log = async (entry: Record<string, unknown>) => {
|
||||
if (!logPath) return;
|
||||
await appendFile(logPath, `${JSON.stringify({ at: new Date().toISOString(), command: argv[0], ...entry })}\n`, { mode: 0o600 }).catch(() => undefined);
|
||||
};
|
||||
const state = await readState(statePath);
|
||||
let cli: string;
|
||||
try { cli = argv[0] === "--version" ? "" : await ensureController("argent", { environment, progress: message => process.stderr.write(`[explore] ${message}\n`) }); }
|
||||
catch (error) {
|
||||
const failure = error as { code?: string; message?: string };
|
||||
process.stdout.write(JSON.stringify({ success: false, error: { code: failure.code ?? "CONTROLLER_DOWNLOAD_FAILED", message: failure.message ?? String(error) } }));
|
||||
return 1;
|
||||
}
|
||||
|
||||
const callArgent = async (tool: string, args: Record<string, unknown>, options?: { out?: string }): Promise<unknown> => {
|
||||
const run = spawnSync(process.execPath, [cli, "run", tool, "--args", JSON.stringify(args), ...(options?.out ? ["--out", options.out] : [])],
|
||||
{ env: environment, encoding: "utf8", maxBuffer: 64 * 1024 * 1024, timeout: ARGENT_CALL_TIMEOUT_MS });
|
||||
if (run.error) throw new ArgentCallError(`argent run ${tool}: ${run.error.message}`, true);
|
||||
if (run.status !== 0) {
|
||||
const detail = `${run.stderr ?? ""}\n${run.stdout ?? ""}`.trim().split("\n").filter(Boolean).slice(-4).join(" | ").slice(0, 800);
|
||||
throw new ArgentCallError(`argent run ${tool} failed: ${detail}`, true);
|
||||
}
|
||||
// With --out the client saves the tool's file and prints where ("Wrote: <path>"), not the tool's JSON.
|
||||
if (options?.out) {
|
||||
const written = await stat(options.out).catch(() => undefined);
|
||||
if (!written?.isFile() || written.size === 0) throw new ArgentCallError(`argent run ${tool} did not write ${options.out}`, true);
|
||||
return { path: options.out };
|
||||
}
|
||||
try { return JSON.parse(run.stdout); }
|
||||
catch { throw new ArgentCallError(`argent run ${tool} did not answer with JSON`, true); }
|
||||
};
|
||||
|
||||
const result = await runBridgeCommand(argv, {
|
||||
state, platform, version: ARGENT_VERSION,
|
||||
...(environment.EXPLORE_ARGENT_BUNDLE_ID ? { bundleId: environment.EXPLORE_ARGENT_BUNDLE_ID } : {}),
|
||||
call: async (tool, args, options) => {
|
||||
const started = Date.now();
|
||||
try {
|
||||
const value = await callArgent(tool, args, options);
|
||||
await log({ tool, args: loggedArgs(args), ms: Date.now() - started, summary: summarize(tool, value) });
|
||||
return value;
|
||||
} catch (error) {
|
||||
await log({ tool, args: loggedArgs(args), ms: Date.now() - started, error: (error instanceof Error ? error.message : String(error)).slice(0, 400) });
|
||||
throw error;
|
||||
}
|
||||
},
|
||||
reachable: async () => {
|
||||
let ok = false;
|
||||
try {
|
||||
const token = environment.ARGENT_AUTH_TOKEN;
|
||||
// The same URL Argent's own client checks: ARGENT_TOOLS_URL may carry a path, which /tools is appended to.
|
||||
const response = await fetch(`${(toolsUrl ?? "").replace(/\/+$/, "")}/tools`, { headers: token ? { authorization: `Bearer ${token}` } : {}, signal: AbortSignal.timeout(5_000) });
|
||||
await response.body?.cancel();
|
||||
ok = response.status < 500;
|
||||
} catch { ok = false; }
|
||||
if (!ok) await log({ tool: "reachable", ok });
|
||||
return ok;
|
||||
},
|
||||
sleep: milliseconds => new Promise(resolve => setTimeout(resolve, milliseconds)),
|
||||
scratchImage: { path: join(dirname(statePath), "argent-scratch.png"), read: async path => {
|
||||
const { PNG } = createRequire(import.meta.url)("pngjs") as { PNG: { sync: { read(bytes: Buffer, options: { checkCRC: boolean }): DecodedFrame } } };
|
||||
return PNG.sync.read(await readFile(path), { checkCRC: false });
|
||||
} },
|
||||
moveFile: async (from, to) => {
|
||||
// Argent's client downloads a recording under its HOME or the working directory; nothing else is moved.
|
||||
const source = await realpath(from);
|
||||
const roots = await Promise.all([environment.HOME, process.cwd()].filter((root): root is string => !!root).map(root => realpath(root).catch(() => root)));
|
||||
if (!roots.some(root => source.startsWith(`${root}/`))) throw new Error(`Argent returned a recording outside its own directories: ${from}`);
|
||||
await mkdir(dirname(to), { recursive: true });
|
||||
try { await rename(from, to); }
|
||||
catch { await copyFile(from, to); await rm(from, { force: true }); }
|
||||
},
|
||||
});
|
||||
await writeState(statePath, state);
|
||||
await log({ result: result.exitCode === 0 ? "ok" : result.stdout.slice(0, 300) });
|
||||
process.stdout.write(result.stdout);
|
||||
return result.exitCode;
|
||||
}
|
||||
|
||||
process.exitCode = await main();
|
||||
@@ -0,0 +1,721 @@
|
||||
/**
|
||||
* Translates the agent-device commands Explore sends into Argent tool calls, and Argent's answers into
|
||||
* agent-device's JSON envelopes, so capture, setup, the agent tool host and black-box exploration drive
|
||||
* either controller without knowing which one runs. Pure: the Argent call, the clock and file moves are
|
||||
* injected, so the translation is tested against recorded Argent output.
|
||||
*/
|
||||
import { CONTROLLER_SESSION } from "./common.js";
|
||||
import type { DecodedFrame } from "../shared/png-evidence.js";
|
||||
|
||||
export type ArgentPlatform = "ios" | "android";
|
||||
|
||||
/** One `argent run <tool>` call. `sent: false` means the request provably never reached the tool-server. */
|
||||
export class ArgentCallError extends Error {
|
||||
constructor(message: string, readonly sent: boolean) { super(message); }
|
||||
}
|
||||
|
||||
export type ArgentCall = (tool: string, args: Record<string, unknown>, options?: { out?: string }) => Promise<unknown>;
|
||||
|
||||
type Rect = { x: number; y: number; width: number; height: number };
|
||||
|
||||
/** What the bridge keeps between commands, in the per-run state file. */
|
||||
export type ArgentBridgeState = {
|
||||
udid?: string;
|
||||
model?: string;
|
||||
osVersion?: string;
|
||||
/** The coordinate space of the last tree: points on iOS, pixels on Android, as agent-device reports them. */
|
||||
screen?: { width: number; height: number };
|
||||
generation: number;
|
||||
refs?: Record<string, { rect: Rect; type?: string; value?: string; secure?: boolean }>;
|
||||
/** iOS asks "Open in “<app>”?" for the first custom-scheme link of a session; later links open directly. */
|
||||
deepLinkPromptAccepted?: boolean;
|
||||
recording?: string;
|
||||
};
|
||||
|
||||
export type ArgentBridgeContext = {
|
||||
call: ArgentCall;
|
||||
state: ArgentBridgeState;
|
||||
platform: ArgentPlatform;
|
||||
/** The app under test when the caller names it outside the command (explore:binary's `install`). */
|
||||
bundleId?: string;
|
||||
version: string;
|
||||
sleep: (milliseconds: number) => Promise<void>;
|
||||
/** Moves a file the Argent client downloaded (a screen recording) to where Explore asked for it. */
|
||||
moveFile: (from: string, to: string) => Promise<void>;
|
||||
/** Whether the tool-server answers, checked before a UI action is sent (see `remoteUnavailable`). */
|
||||
reachable: () => Promise<boolean>;
|
||||
/** A file the bridge may overwrite with a screenshot, and a reader for it (the link-prompt fallback). */
|
||||
scratchImage?: { path: string; read: (path: string) => Promise<DecodedFrame> };
|
||||
};
|
||||
|
||||
export type BridgeResult = { exitCode: number; stdout: string };
|
||||
|
||||
const success = (data: Record<string, unknown>): BridgeResult => ({ exitCode: 0, stdout: JSON.stringify({ success: true, data }) });
|
||||
const failure = (code: string, message: string, details?: Record<string, unknown>): BridgeResult =>
|
||||
({ exitCode: 1, stdout: JSON.stringify({ success: false, error: { code, message, ...(details ? { details } : {}) } }) });
|
||||
|
||||
/**
|
||||
* agent-device's answer when its pre-flight health check fails, which Explore resends because the command was
|
||||
* provably never sent (controller.ts remoteDaemonUnavailable). The bridge gives it only on the same proof.
|
||||
*/
|
||||
const remoteUnavailable = () => failure("COMMAND_FAILED", "Remote daemon is unavailable");
|
||||
|
||||
/** Flags agent-device takes after a command; the bridge needs the platform only from its own context. */
|
||||
const VALUE_FLAGS = new Set(["--session", "--device", "--platform", "--level", "--udid", "--scope", "--bundle-id", "--serial", "--timeout"]);
|
||||
const BOOLEAN_FLAGS = new Set(["--json", "--relaunch", "--normalize-status-bar", "--force-full", "--in-app", "--system"]);
|
||||
|
||||
export function parseCommand(argv: readonly string[]): { positional: string[]; flags: Record<string, string | true> } {
|
||||
const positional: string[] = [];
|
||||
const flags: Record<string, string | true> = {};
|
||||
for (let index = 0; index < argv.length; index++) {
|
||||
const value = argv[index]!;
|
||||
if (value === "--") { positional.push(...argv.slice(index + 1)); break; }
|
||||
if (VALUE_FLAGS.has(value)) { flags[value.slice(2)] = argv[index + 1] ?? ""; index++; continue; }
|
||||
if (BOOLEAN_FLAGS.has(value)) { flags[value.slice(2)] = true; continue; }
|
||||
positional.push(value);
|
||||
}
|
||||
return { positional, flags };
|
||||
}
|
||||
|
||||
type ArgentNode = { role?: string; type?: string; label?: string; identifier?: string; value?: string; contentDescription?: string; disabled?: boolean;
|
||||
frame?: Rect; traits?: string[]; hidden?: boolean; selected?: boolean; password?: boolean; bundleId?: string; children?: ArgentNode[] };
|
||||
export type ArgentTree = { schemaVersion?: number; source?: string; screen?: { width: number; height: number }; roots?: ArgentNode[];
|
||||
truncated?: boolean; alertVisible?: boolean; keyboardVisible?: boolean; foregroundApp?: string };
|
||||
|
||||
const record = (value: unknown): Record<string, unknown> => (value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {});
|
||||
const finite = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value);
|
||||
|
||||
/** Android widget classes as agent-device names their element types. */
|
||||
function agentDeviceType(node: ArgentNode, platform: ArgentPlatform): string {
|
||||
const type = node.type ?? node.role ?? "Other";
|
||||
if (node.password) return "SecureTextField";
|
||||
if (platform === "ios") return type;
|
||||
const simple = type.split(".").pop() ?? type;
|
||||
if (/EditText|TextInput/.test(simple)) return "TextField";
|
||||
if (/Button$|ImageButton|CheckBox|Switch|RadioButton/.test(simple)) return simple.endsWith("Button") ? "Button" : simple;
|
||||
if (/TextView/.test(simple)) return "StaticText";
|
||||
if (/ImageView/.test(simple)) return "Image";
|
||||
if (/ScrollView|RecyclerView|ListView/.test(simple)) return "ScrollView";
|
||||
return simple || "Other";
|
||||
}
|
||||
|
||||
/**
|
||||
* The tree as agent-device's snapshot: the app's root (an `Application` node sized to the screen) and every
|
||||
* element on or near the screen, in the units agent-device uses (points on iOS, pixels on Android), with
|
||||
* refs pinned to this snapshot's generation. Elements Argent lists twice (iOS AX does) appear once.
|
||||
*/
|
||||
export function snapshotFromTree(tree: ArgentTree, platform: ArgentPlatform, generation: number, bundleId?: string) {
|
||||
const screen = tree.screen;
|
||||
if (!screen || !finite(screen.width) || !finite(screen.height) || screen.width <= 0 || screen.height <= 0) {
|
||||
throw new Error("ui-tree did not report the screen size");
|
||||
}
|
||||
const app = bundleId ?? tree.foregroundApp;
|
||||
// Android's status bar and navigation (com.android.systemui) are not part of the app; a dialog another package draws
|
||||
// over it (a runtime permission prompt) is, because it covers the app and setup has to answer it.
|
||||
const roots = (tree.roots ?? []).filter(root => platform === "ios" || root.bundleId !== ANDROID_SYSTEM_UI);
|
||||
const nodes: Record<string, unknown>[] = [];
|
||||
const refs: NonNullable<ArgentBridgeState["refs"]> = {};
|
||||
const seen = new Set<string>();
|
||||
const toPoints = (frame: Rect): Rect => ({ x: frame.x * screen.width, y: frame.y * screen.height, width: frame.width * screen.width, height: frame.height * screen.height });
|
||||
/**
|
||||
* iOS visibility, as Argent computes it (a node is hidden when its frame misses every ancestor's frame), except that a
|
||||
* root clips to the whole screen. On iPhone Duo's inner display Argent 0.29 reports the app root as the top-left third
|
||||
* of the screen ([0, 0, 0.333, 0.333], its 3x scale applied twice), which hid everything outside that third: a sheet's
|
||||
* title and its Cancel button among them. Android's `hidden` is the system's own visible-to-user flag and is kept.
|
||||
*/
|
||||
const clipOf = (node: ArgentNode, clip: Rect | undefined, root: boolean): Rect | undefined => {
|
||||
if (root || !node.frame || ![node.frame.x, node.frame.y, node.frame.width, node.frame.height].every(finite)) return clip;
|
||||
return clip && intersect(node.frame, clip);
|
||||
};
|
||||
const visit = (node: ArgentNode, depth: number, parentIndex: number | undefined, appRoot: boolean, clip: Rect | undefined, root: boolean) => {
|
||||
const frame = node.frame;
|
||||
const inner = clipOf(node, clip, root);
|
||||
const rect = frame && [frame.x, frame.y, frame.width, frame.height].every(finite) ? toPoints(frame) : undefined;
|
||||
const onScreen = !!rect && rect.x < screen.width && rect.y < screen.height && rect.x + rect.width > 0 && rect.y + rect.height > 0;
|
||||
const type = appRoot ? "Application" : agentDeviceType(node, platform);
|
||||
const label = node.label ?? node.contentDescription;
|
||||
const key = JSON.stringify([type, label, node.identifier, node.value, rect && [Math.round(rect.x), Math.round(rect.y), Math.round(rect.width), Math.round(rect.height)]]);
|
||||
let index = parentIndex;
|
||||
// Off-screen content stays out, as agent-device leaves it out; its parents still come through for depth.
|
||||
if (rect && (onScreen || appRoot) && !seen.has(key)) {
|
||||
seen.add(key);
|
||||
index = nodes.length;
|
||||
const ref = `e${index + 1}`;
|
||||
const traits = node.traits ?? [];
|
||||
// iOS marks a disabled element with the notEnabled trait, Android with disabled.
|
||||
const enabled = !traits.includes("notEnabled") && node.disabled !== true;
|
||||
const visible = platform === "ios" ? !!inner : node.hidden !== true;
|
||||
nodes.push({ depth, index, ...(parentIndex === undefined ? {} : { parentIndex }), type, ref,
|
||||
rect: appRoot ? { x: 0, y: 0, width: screen.width, height: screen.height } : rect,
|
||||
...(label ? { label } : {}), ...(node.identifier ? { identifier: node.identifier } : {}),
|
||||
...(node.value !== undefined ? { value: node.value } : {}), enabled, hittable: enabled && visible && !appRoot,
|
||||
...(visible ? {} : { visible: false }), ...(node.selected || traits.includes("selected") ? { selected: true } : {}) });
|
||||
refs[ref] = { rect: appRoot ? { x: 0, y: 0, width: screen.width, height: screen.height } : rect, type,
|
||||
...(node.value !== undefined ? { value: node.value } : {}), ...(type === "SecureTextField" ? { secure: true } : {}) };
|
||||
}
|
||||
for (const child of node.children ?? []) visit(child, depth + 1, index, false, inner, false);
|
||||
};
|
||||
for (const root of roots) {
|
||||
const isAppRoot = platform === "ios" ? root.type === "Application" || nodes.length === 0 : root.bundleId === app;
|
||||
visit(root, 0, undefined, isAppRoot, { x: 0, y: 0, width: 1, height: 1 }, true);
|
||||
}
|
||||
return { nodes, refs, screen: { width: screen.width, height: screen.height } };
|
||||
}
|
||||
|
||||
function intersect(a: Rect, b: Rect): Rect | undefined {
|
||||
const x = Math.max(a.x, b.x), y = Math.max(a.y, b.y);
|
||||
const right = Math.min(a.x + a.width, b.x + b.width), bottom = Math.min(a.y + a.height, b.y + b.height);
|
||||
return right > x && bottom > y ? { x, y, width: right - x, height: bottom - y } : undefined;
|
||||
}
|
||||
|
||||
const centre = (rect: Rect, screen: { width: number; height: number }) =>
|
||||
({ x: (rect.x + rect.width / 2) / screen.width, y: (rect.y + rect.height / 2) / screen.height });
|
||||
|
||||
/**
|
||||
* Argent read nothing: exactly one bare root and no foreground app, which is what iOS 27.1 gives while the link prompt
|
||||
* is up. A read that returned no roots at all is a failed read, not this state.
|
||||
*/
|
||||
function blindTree(tree: ArgentTree): boolean {
|
||||
const roots = tree.roots ?? [];
|
||||
return !tree.foregroundApp && roots.length === 1 && (roots[0]!.children ?? []).length === 0 && !roots[0]!.label && !roots[0]!.type;
|
||||
}
|
||||
|
||||
/** A tree with the app's root and something in it: what a relaunch must reach before the app is usable. */
|
||||
function appReady(tree: ArgentTree, bundleId: string): boolean {
|
||||
if (tree.foregroundApp !== bundleId) return false;
|
||||
const count = (node: ArgentNode): number => 1 + (node.children ?? []).reduce((sum, child) => sum + count(child), 0);
|
||||
return (tree.roots ?? []).some(root => count(root) > 1);
|
||||
}
|
||||
|
||||
function flatten(tree: ArgentTree): ArgentNode[] {
|
||||
const nodes: ArgentNode[] = [];
|
||||
const walk = (node: ArgentNode) => { nodes.push(node); (node.children ?? []).forEach(walk); };
|
||||
(tree.roots ?? []).forEach(walk);
|
||||
return nodes;
|
||||
}
|
||||
|
||||
/** iOS: `com.apple.CoreSimulator.SimRuntime.iOS-26-5` → `26.5`. */
|
||||
export function iosRuntimeVersion(runtime: unknown): string | undefined {
|
||||
const match = typeof runtime === "string" ? /iOS-(\d+)-(\d+)(?:-(\d+))?$/.exec(runtime) : null;
|
||||
return match ? [match[1], match[2], match[3]].filter(Boolean).join(".") : undefined;
|
||||
}
|
||||
|
||||
const DEEP_LINK_PROMPT_CONFIRM = { dxPoints: 74, dyPoints: 37 };
|
||||
const KEYBOARD_DISMISS_LABELS = ["Hide keyboard", "Dismiss keyboard", "Done"];
|
||||
// A keyboard covers the lower part of the screen; its keys start below this share of the height.
|
||||
const KEYBOARD_TOP = 0.4;
|
||||
const ALERT_PREFERRED_BUTTONS = ["Open", "OK", "Allow", "Allow While Using App", "Continue"];
|
||||
const READ_TOOLS = new Set(["ui-tree", "list-devices", "screenshot", "foreground-app", "await-screen-idle", "describe"]);
|
||||
const SPRINGBOARD = "com.apple.springboard";
|
||||
const ANDROID_SYSTEM_UI = "com.android.systemui";
|
||||
const OPEN_IN_APP_PROMPT = /^Open in “.+”\?$/;
|
||||
|
||||
/**
|
||||
* iOS's "Open in “<app>”?" link prompt, recognized by its own text. Argent 0.29 does not always flag it as an alert
|
||||
* (on iOS 27.1, iPhone Duo, `alertVisible` stays false while SpringBoard shows it), and another alert must never be
|
||||
* taken for it: the bridge presses this prompt's Open on its own.
|
||||
*/
|
||||
export function openInAppPromptShowing(tree: ArgentTree): boolean {
|
||||
return flatten(tree).some(node => OPEN_IN_APP_PROMPT.test(node.label ?? ""));
|
||||
}
|
||||
|
||||
/** Any system alert in front of the app: one Argent flags, or the link prompt it does not. */
|
||||
function alertShowing(tree: ArgentTree): boolean {
|
||||
return tree.alertVisible === true || (tree.foregroundApp === SPRINGBOARD && openInAppPromptShowing(tree));
|
||||
}
|
||||
|
||||
/**
|
||||
* The link prompt's Open button found in a screenshot: the largest wide, filled system-blue shape in the middle of the
|
||||
* screen, as iOS 26 and 27 draw it. Used only when Argent cannot read the screen at all while the prompt is up.
|
||||
*/
|
||||
export function findOpenButton(frame: DecodedFrame): { x: number; y: number } | undefined {
|
||||
const step = Math.max(1, Math.round(frame.width / 200));
|
||||
const columns = Math.floor(frame.width / step), rows = Math.floor(frame.height / step);
|
||||
const top = Math.floor(rows * 0.2), bottom = Math.ceil(rows * 0.8);
|
||||
const blue = new Uint8Array(columns * rows);
|
||||
for (let row = top; row < bottom; row++) for (let column = 0; column < columns; column++) {
|
||||
const offset = (row * step * frame.width + column * step) * 4;
|
||||
const [red, green, blueValue] = [frame.data[offset]!, frame.data[offset + 1]!, frame.data[offset + 2]!];
|
||||
if (red < 70 && green > 90 && green < 170 && blueValue > 200) blue[row * columns + column] = 1;
|
||||
}
|
||||
let best: { cells: number; left: number; right: number; top: number; bottom: number } | undefined;
|
||||
const seen = new Uint8Array(columns * rows);
|
||||
for (let start = 0; start < blue.length; start++) {
|
||||
if (!blue[start] || seen[start]) continue;
|
||||
const shape = { cells: 0, left: columns, right: 0, top: rows, bottom: 0 };
|
||||
const queue = [start];
|
||||
seen[start] = 1;
|
||||
while (queue.length) {
|
||||
const cell = queue.pop()!;
|
||||
const row = Math.floor(cell / columns), column = cell % columns;
|
||||
shape.cells++;
|
||||
shape.left = Math.min(shape.left, column); shape.right = Math.max(shape.right, column);
|
||||
shape.top = Math.min(shape.top, row); shape.bottom = Math.max(shape.bottom, row);
|
||||
for (const next of [cell - 1, cell + 1, cell - columns, cell + columns]) {
|
||||
if (next < 0 || next >= blue.length || seen[next] || !blue[next]) continue;
|
||||
if (Math.abs((next % columns) - column) > 1) continue;
|
||||
seen[next] = 1;
|
||||
queue.push(next);
|
||||
}
|
||||
}
|
||||
const width = shape.right - shape.left + 1, height = shape.bottom - shape.top + 1;
|
||||
// A dialog button: wide, a few percent of the screen tall, and well under its full width.
|
||||
if (width < columns * 0.15 || width > columns * 0.6 || width < height * 1.5 || height < rows * 0.03 || height > rows * 0.12) continue;
|
||||
if (!best || shape.cells > best.cells) best = shape;
|
||||
}
|
||||
if (!best) return undefined;
|
||||
return { x: ((best.left + best.right + 1) / 2) / columns, y: ((best.top + best.bottom + 1) / 2) / rows };
|
||||
}
|
||||
|
||||
/**
|
||||
* The prompt's Open button from `describe`. On iOS 27.1 (iPhone Duo) `ui-tree` reports SpringBoard's frames with
|
||||
* x and y swapped, while `describe` reads them correctly, so the button is located there.
|
||||
*/
|
||||
export function describedButton(description: unknown, label: string): Rect | undefined {
|
||||
if (typeof description !== "string") return undefined;
|
||||
const escaped = label.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
|
||||
// Only a whole line Argent printed counts, so an app label that spells out a button line cannot be picked.
|
||||
const match = new RegExp(`^\\s*AXButton "${escaped}"\\s+\\(([\\d.]+), ([\\d.]+), ([\\d.]+), ([\\d.]+)\\)\\s*$`, "m").exec(description);
|
||||
if (!match) return undefined;
|
||||
const [x, y, width, height] = match.slice(1).map(Number) as [number, number, number, number];
|
||||
return [x, y, width, height].every(finite) && width > 0 && height > 0 ? { x, y, width, height } : undefined;
|
||||
}
|
||||
|
||||
/** Runs one agent-device command against Argent and answers as agent-device would. */
|
||||
export async function runBridgeCommand(argv: readonly string[], context: ArgentBridgeContext): Promise<BridgeResult> {
|
||||
const { state, platform } = context;
|
||||
if (argv[0] === "--version") return { exitCode: 0, stdout: `${context.version}\n` };
|
||||
const [command, ...rest] = argv;
|
||||
const { positional, flags } = parseCommand(rest);
|
||||
const bundleFlag = typeof flags["bundle-id"] === "string" ? flags["bundle-id"] : context.bundleId;
|
||||
|
||||
/** 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 };
|
||||
for (let attempt = 0; ; attempt++) {
|
||||
try { return record(await context.call(tool, withDevice, options)); }
|
||||
catch (error) {
|
||||
if (READ_TOOLS.has(tool) && attempt < 2) { await context.sleep(1_000 * (attempt + 1)); continue; }
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
};
|
||||
const tree = async (): Promise<ArgentTree> => (await call("ui-tree")) as ArgentTree;
|
||||
const ensureDevice = async () => {
|
||||
if (state.udid) return;
|
||||
let devices: Record<string, unknown>[] = [];
|
||||
// A tool-server that has just started can list no devices at all for its first call; that is not an answer.
|
||||
for (let attempt = 0; attempt < 3; attempt++) {
|
||||
const listed = await call("list-devices");
|
||||
const all = Array.isArray(listed.devices) ? listed.devices : [];
|
||||
devices = all.map(record).filter(device => device.platform === platform
|
||||
&& (platform === "ios" ? device.state === "Booted" && device.runtimeKind !== "tv" : device.state === "device" && device.runtimeKind !== "tv"));
|
||||
if (all.length) break;
|
||||
await context.sleep(2_000);
|
||||
}
|
||||
if (devices.length !== 1) throw new BridgeFailure("DEVICE_UNAVAILABLE", `Argent lists ${devices.length} booted ${platform} devices on this session; Explore drives exactly one.`);
|
||||
const device = devices[0]!;
|
||||
const udid = platform === "ios" ? device.udid : device.serial;
|
||||
if (typeof udid !== "string" || !udid) throw new BridgeFailure("DEVICE_UNAVAILABLE", "Argent did not name the booted device.");
|
||||
state.udid = udid;
|
||||
state.model = String(platform === "ios" ? device.name : device.model ?? device.avdName ?? udid);
|
||||
const version = platform === "ios" ? iosRuntimeVersion(device.runtime) : undefined;
|
||||
if (version) state.osVersion = version;
|
||||
};
|
||||
/** Relaunches until the app's tree is readable: an EAS simulator Argent did not boot needs a relaunch first. */
|
||||
const relaunch = async (bundleId: string) => {
|
||||
for (let restart = 0; restart < 2; restart++) {
|
||||
await call("restart-app", { bundleId });
|
||||
for (let poll = 0; poll < 12; poll++) {
|
||||
await context.sleep(1_000);
|
||||
if (appReady(await tree(), bundleId)) return;
|
||||
}
|
||||
}
|
||||
throw new BridgeFailure("APP_NOT_READY", `${bundleId} did not come up with a readable accessibility tree after relaunching.`);
|
||||
};
|
||||
const deviceEnvelope = (bundleId: string) => ({ session: CONTROLLER_SESSION, appBundleId: bundleId, platform, target: "mobile",
|
||||
device: { platform, target: "mobile", name: state.model, id: state.udid, ...(state.osVersion ? { osVersion: state.osVersion } : {}) },
|
||||
identifiers: { session: CONTROLLER_SESSION, appBundleId: bundleId, deviceName: state.model, deviceId: state.udid } });
|
||||
const screen = async () => {
|
||||
if (!state.screen) { const current = await tree(); if (current.screen) state.screen = { ...current.screen }; }
|
||||
if (!state.screen) throw new BridgeFailure("COMMAND_FAILED", "The screen size is not known yet.");
|
||||
return state.screen;
|
||||
};
|
||||
const tap = async (x: number, y: number) => { await call("gesture-tap", { x, y }); };
|
||||
const resolveRef = (value: string) => {
|
||||
const match = /^@?(e\d+)(?:~s(\d+))?$/.exec(value);
|
||||
if (!match) throw new BridgeFailure("INVALID_ARGS", `Not an element reference: ${value}`);
|
||||
if (match[2] && Number(match[2]) !== state.generation) throw new BridgeFailure("COMMAND_FAILED", `Element reference ${value} is stale; take a new snapshot.`);
|
||||
const target = state.refs?.[match[1]!];
|
||||
if (!target) throw new BridgeFailure("COMMAND_FAILED", `Element reference ${value} is not in the last snapshot.`);
|
||||
return target;
|
||||
};
|
||||
/**
|
||||
* A UI action is only sent when the tool-server answers first, so a failure after this point is never resent. A
|
||||
* session's tool-server can still be starting when EAS reports the session ready, so it is given about 25 s to answer.
|
||||
*/
|
||||
const beforeAction = async () => {
|
||||
for (const delay of [1_000, 2_000, 3_000, 4_000, 5_000, 5_000, 5_000]) {
|
||||
if (await context.reachable()) return;
|
||||
await context.sleep(delay);
|
||||
}
|
||||
if (!await context.reachable()) throw new UnsentFailure();
|
||||
};
|
||||
|
||||
try {
|
||||
switch (command) {
|
||||
case "open": {
|
||||
await ensureDevice();
|
||||
const target = positional.length === 2 ? { bundleId: positional[0]!, url: positional[1]! }
|
||||
: positional.length === 1 && /^[A-Za-z][A-Za-z0-9+.-]*:/.test(positional[0]!) ? { url: positional[0]! } : { bundleId: positional[0] };
|
||||
if (target.url) {
|
||||
await beforeAction();
|
||||
await call("open-url", { url: target.url });
|
||||
if (platform === "ios" && !state.deepLinkPromptAccepted) await acceptDeepLinkPrompt(target.bundleId ?? bundleFlag);
|
||||
return success({ ...(target.bundleId ? deviceEnvelope(target.bundleId) : { session: CONTROLLER_SESSION }), url: target.url });
|
||||
}
|
||||
const bundleId = target.bundleId ?? bundleFlag;
|
||||
if (!bundleId) throw new BridgeFailure("INVALID_ARGS", "open needs a bundle identifier or a URL.");
|
||||
// agent-device's plain open brings a running app forward and keeps its state; only --relaunch restarts it.
|
||||
if (flags.relaunch !== true && appReady(await tree(), bundleId)) return success({ ...deviceEnvelope(bundleId), appName: bundleId });
|
||||
await beforeAction();
|
||||
await relaunch(bundleId);
|
||||
return success({ ...deviceEnvelope(bundleId), appName: bundleId });
|
||||
}
|
||||
case "snapshot": {
|
||||
await ensureDevice();
|
||||
const current = await tree();
|
||||
state.generation += 1;
|
||||
const converted = snapshotFromTree(current, platform, state.generation, bundleFlag);
|
||||
state.refs = converted.refs;
|
||||
state.screen = converted.screen;
|
||||
const dialog = platform === "android" ? readAlert(current) : undefined;
|
||||
if (dialog && !converted.nodes.some(node => node.type === "Alert")) {
|
||||
// An Android dialog from another package covers the app: report it as agent-device does, as an Alert.
|
||||
converted.nodes.push({ depth: 1, index: converted.nodes.length, parentIndex: 0, type: "Alert", ref: `e${converted.nodes.length + 1}`,
|
||||
rect: { x: 0, y: 0, width: converted.screen.width, height: converted.screen.height }, label: dialog.message || "System dialog", enabled: true, hittable: false });
|
||||
} else if (platform === "ios" && alertShowing(current) && !converted.nodes.some(node => node.type === "Alert")
|
||||
&& !(bundleFlag && appReady(current, bundleFlag))) {
|
||||
// A system alert (SpringBoard's) hides the app's tree; report it the way agent-device does, as an Alert node.
|
||||
converted.nodes.push({ depth: 1, index: converted.nodes.length, parentIndex: 0, type: "Alert", ref: `e${converted.nodes.length + 1}`,
|
||||
rect: { x: 0, y: 0, width: converted.screen.width, height: converted.screen.height }, label: "System alert", enabled: true, hittable: false });
|
||||
}
|
||||
return success({ nodes: converted.nodes, truncated: current.truncated === true, refsGeneration: state.generation,
|
||||
...(current.foregroundApp ? { appBundleId: current.foregroundApp, appName: current.foregroundApp } : {}),
|
||||
snapshotQuality: { state: "healthy", backend: "argent" } });
|
||||
}
|
||||
case "appstate": {
|
||||
await ensureDevice();
|
||||
const current = await tree();
|
||||
const foreground = current.foregroundApp;
|
||||
return success({ ...(foreground ? { appBundleId: foreground, ...(platform === "android" ? { package: foreground } : {}) } : {}),
|
||||
session: CONTROLLER_SESSION, state: foreground ? "runningForeground" : "unknown", surface: foreground ? "app" : "home",
|
||||
device: { id: state.udid, name: state.model } });
|
||||
}
|
||||
case "alert": {
|
||||
await ensureDevice();
|
||||
const current = await tree();
|
||||
const alert = readAlert(current);
|
||||
if (positional[0] === "get") {
|
||||
if (!alert) return platform === "android" ? success({ platform: "android", alert: null }) : failure("COMMAND_FAILED", "alert not found");
|
||||
return platform === "android" ? success({ platform: "android", alert: { title: alert.message, buttons: alert.items } })
|
||||
: success({ message: alert.message, items: alert.items });
|
||||
}
|
||||
if (positional[0] === "accept" || positional[0] === "dismiss") {
|
||||
if (!alert) return failure("COMMAND_FAILED", "alert not found");
|
||||
const preferred = positional[0] === "dismiss"
|
||||
? alert.buttons.find(button => /^(Cancel|Not Now|Don.t Allow|Dismiss)$/.test(button.label)) ?? alert.buttons[0]
|
||||
: ALERT_PREFERRED_BUTTONS.map(label => alert.buttons.find(button => button.label === label)).find(Boolean) ?? alert.buttons.at(-1);
|
||||
if (!preferred) return failure("COMMAND_FAILED", "The alert has no button to press.");
|
||||
await beforeAction();
|
||||
const size = current.screen ?? await screen();
|
||||
// describe places SpringBoard's buttons correctly where ui-tree may not (iOS 27.1); the tree is the fallback.
|
||||
const described = describedButton(await call("describe").then(value => value.description, () => undefined), preferred.label);
|
||||
await tap(...Object.values(described ? centre(described, { width: 1, height: 1 }) : centre(preferred.rect, size)) as [number, number]);
|
||||
await context.sleep(800);
|
||||
if (readAlert(await tree())) return failure("COMMAND_FAILED", "The alert is still showing after its button was pressed.");
|
||||
return success({ action: positional[0], button: preferred.label });
|
||||
}
|
||||
return failure("INVALID_ARGS", `Unsupported alert command: ${positional[0] ?? ""}`);
|
||||
}
|
||||
case "press": {
|
||||
await ensureDevice();
|
||||
const size = await screen();
|
||||
let point: { x: number; y: number };
|
||||
if (positional[0]?.startsWith("@") || /^e\d+/.test(positional[0] ?? "")) point = centre(resolveRef(positional[0]!).rect, size);
|
||||
else {
|
||||
const x = Number(positional[0]), y = Number(positional[1]);
|
||||
if (!finite(x) || !finite(y)) throw new BridgeFailure("INVALID_ARGS", "press needs an element reference or x and y.");
|
||||
point = { x: x / size.width, y: y / size.height };
|
||||
}
|
||||
await beforeAction();
|
||||
await tap(point.x, point.y);
|
||||
return success({ action: "press", x: point.x, y: point.y });
|
||||
}
|
||||
case "fill": {
|
||||
await ensureDevice();
|
||||
const target = resolveRef(positional[0] ?? "");
|
||||
const text = positional.slice(1).join(" ");
|
||||
rejectSecretPlaceholder(text);
|
||||
const size = await screen();
|
||||
await beforeAction();
|
||||
await tap(...Object.values(centre(target.rect, size)) as [number, number]);
|
||||
await context.sleep(400);
|
||||
if (platform === "android") {
|
||||
const filled = await call("fill", { text });
|
||||
if (filled.verified !== true) return failure("COMMAND_FAILED", "Argent could not verify the field's new text.");
|
||||
return success({ action: "fill" });
|
||||
}
|
||||
// Argent's iOS `fill` cannot see React Native's focused field, so the old text is erased and the new one typed.
|
||||
const erase = target.secure ? 64 : (target.value ?? "").length;
|
||||
if (erase > 0) {
|
||||
const erased = await call("run-sequence", { steps: Array.from({ length: erase }, () => ({ tool: "keyboard", args: { udid: state.udid, key: "backspace" } })) });
|
||||
// run-sequence answers normally when it stops partway; typing over half-erased text would leave a wrong value.
|
||||
if (erased.completed !== erased.total) return failure("COMMAND_FAILED", `Erasing the field stopped after ${String(erased.completed)} of ${String(erased.total)} keys; nothing was typed.`);
|
||||
}
|
||||
if (text) await call("keyboard", { text });
|
||||
if (!target.secure) {
|
||||
const after = flatten(await tree()).find(node => node.frame && Math.abs(node.frame.x * size.width - target.rect.x) < 2
|
||||
&& Math.abs(node.frame.y * size.height - target.rect.y) < 2 && /TextField|EditText/.test(node.type ?? ""));
|
||||
if (after && (after.value ?? "") !== text) return failure("COMMAND_FAILED", "The field does not hold the requested text after typing it.");
|
||||
}
|
||||
return success({ action: "fill" });
|
||||
}
|
||||
case "type": {
|
||||
await ensureDevice();
|
||||
const text = positional.join(" ");
|
||||
rejectSecretPlaceholder(text);
|
||||
await beforeAction();
|
||||
await call("keyboard", { text });
|
||||
return success({ action: "type" });
|
||||
}
|
||||
case "keyboard": {
|
||||
if (positional[0] !== "dismiss") return failure("INVALID_ARGS", `Unsupported keyboard command: ${positional[0] ?? ""}`);
|
||||
await ensureDevice();
|
||||
const current = await tree();
|
||||
if (!current.keyboardVisible) return success({ platform, action: "dismiss", wasVisible: false, dismissed: false, visible: false });
|
||||
await beforeAction();
|
||||
if (platform === "android") await call("button", { button: "back" });
|
||||
else {
|
||||
// agent-device taps the keyboard's own dismiss control, and fails with this message when there is none, which
|
||||
// callers answer with the return key. Only a key in the keyboard's area counts: an app's "Done" above it is not one.
|
||||
const key = flatten(current).find(node => KEYBOARD_DISMISS_LABELS.includes(node.label ?? "") && node.frame && node.frame.y >= KEYBOARD_TOP);
|
||||
if (!key) return failure("COMMAND_FAILED", "Unable to dismiss the iOS keyboard: the keyboard exposes no dismiss control.");
|
||||
const size = current.screen ?? await screen();
|
||||
await tap(...Object.values(centre({ x: key.frame!.x * size.width, y: key.frame!.y * size.height,
|
||||
width: key.frame!.width * size.width, height: key.frame!.height * size.height }, size)) as [number, number]);
|
||||
}
|
||||
await context.sleep(500);
|
||||
const visible = (await tree()).keyboardVisible === true;
|
||||
if (visible && platform === "ios") return failure("COMMAND_FAILED", "Unable to dismiss the iOS keyboard: it is still showing after its dismiss key was pressed.");
|
||||
return success({ platform, action: "dismiss", wasVisible: true, dismissed: !visible, visible });
|
||||
}
|
||||
case "scroll": {
|
||||
await ensureDevice();
|
||||
const direction = positional[0] ?? "down";
|
||||
const vertical = direction === "down" || direction === "up";
|
||||
const [from, to] = direction === "down" || direction === "right" ? [0.7, 0.3] : [0.3, 0.7];
|
||||
await beforeAction();
|
||||
await call("gesture-swipe", vertical ? { fromX: 0.5, fromY: from, toX: 0.5, toY: to, momentum: false } : { fromX: from, fromY: 0.5, toX: to, toY: 0.5, momentum: false });
|
||||
return success({ action: "scroll", direction });
|
||||
}
|
||||
case "swipe": {
|
||||
await ensureDevice();
|
||||
const [x1, y1, x2, y2] = positional.slice(0, 4).map(Number);
|
||||
if (![x1, y1, x2, y2].every(finite)) throw new BridgeFailure("INVALID_ARGS", "swipe needs x1 y1 x2 y2.");
|
||||
const size = await screen();
|
||||
await beforeAction();
|
||||
await call("gesture-swipe", { fromX: x1! / size.width, fromY: y1! / size.height, toX: x2! / size.width, toY: y2! / size.height, momentum: false });
|
||||
return success({ action: "swipe" });
|
||||
}
|
||||
case "back": {
|
||||
await ensureDevice();
|
||||
await beforeAction();
|
||||
if (flags.system === true) {
|
||||
// agent-device's system back: the hardware button on Android, the edge swipe on iOS.
|
||||
if (platform === "android") await call("button", { button: "back" });
|
||||
else await call("gesture-swipe", { fromX: 0.05, fromY: 0.5, toX: 0.8, toY: 0.5, momentum: false });
|
||||
return success({ action: "back", mode: "system" });
|
||||
}
|
||||
const current = await tree();
|
||||
const nodes = flatten(current);
|
||||
const button = platform === "android"
|
||||
? nodes.find(node => /^(Navigate up|Back)$/i.test(node.contentDescription ?? node.label ?? "") && node.frame)
|
||||
: (() => {
|
||||
const bar = nodes.find(node => node.type === "NavigationBar" && node.frame);
|
||||
return bar && (bar.children ?? []).flatMap(function all(node: ArgentNode): ArgentNode[] { return [node, ...(node.children ?? []).flatMap(all)]; })
|
||||
.find(node => node.type === "Button" && node.frame && node.frame.x < 1 / 3);
|
||||
})();
|
||||
if (button?.frame) {
|
||||
await tap(button.frame.x + button.frame.width / 2, button.frame.y + button.frame.height / 2);
|
||||
return success({ action: "back", mode: "in-app" });
|
||||
}
|
||||
if (flags["in-app"] === true || platform === "ios") return failure("COMMAND_FAILED", "in-app back control is not available");
|
||||
await call("button", { button: "back" });
|
||||
return success({ action: "back", mode: "system" });
|
||||
}
|
||||
case "wait": {
|
||||
if (positional[0] === "stable") {
|
||||
await ensureDevice();
|
||||
const minStableMs = Number(positional[1] ?? 500), timeoutMs = Number(positional[2] ?? 8000);
|
||||
const idle = await call("await-screen-idle", { minStableMs: finite(minStableMs) ? minStableMs : 500, timeoutMs: finite(timeoutMs) ? timeoutMs : 8000 });
|
||||
return success({ stable: idle.settled === true });
|
||||
}
|
||||
const milliseconds = Number(positional[0]);
|
||||
if (!finite(milliseconds) || milliseconds < 0) throw new BridgeFailure("INVALID_ARGS", "wait needs a number of milliseconds or `stable`.");
|
||||
await context.sleep(milliseconds);
|
||||
return success({ waitedMs: milliseconds });
|
||||
}
|
||||
case "screenshot": {
|
||||
await ensureDevice();
|
||||
const path = positional[0];
|
||||
if (!path) throw new BridgeFailure("INVALID_ARGS", "screenshot needs a path.");
|
||||
await call("screenshot", { scale: 1 }, { out: path });
|
||||
return success({ path });
|
||||
}
|
||||
case "record": {
|
||||
await ensureDevice();
|
||||
if (positional[0] === "start") {
|
||||
if (!positional[1]) throw new BridgeFailure("INVALID_ARGS", "record start needs a path.");
|
||||
await call("screen-recording-start", { timeLimitSeconds: 300, trimStatic: false, showTouches: false });
|
||||
state.recording = positional[1];
|
||||
return success({ recording: true, outPath: positional[1] });
|
||||
}
|
||||
if (positional[0] === "stop") {
|
||||
const stopped = await call("screen-recording-stop");
|
||||
const target = state.recording;
|
||||
delete state.recording;
|
||||
if (typeof stopped.video !== "string") return failure("COMMAND_FAILED", "Argent did not return the recording.");
|
||||
if (target) await context.moveFile(stopped.video, target);
|
||||
return success({ outPath: target ?? stopped.video, ...(finite(stopped.durationMs) ? { durationMs: stopped.durationMs } : {}) });
|
||||
}
|
||||
return failure("INVALID_ARGS", `Unsupported record command: ${positional[0] ?? ""}`);
|
||||
}
|
||||
case "install": {
|
||||
await ensureDevice();
|
||||
const path = positional[0];
|
||||
if (!path || !bundleFlag) throw new BridgeFailure("INVALID_ARGS", "install needs an archive path and the app's bundle identifier.");
|
||||
await beforeAction();
|
||||
await call("reinstall-app", { bundleId: bundleFlag, appPath: path });
|
||||
return success({ installed: true, appBundleId: bundleFlag });
|
||||
}
|
||||
case "fold": {
|
||||
await ensureDevice();
|
||||
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();
|
||||
const folded = await call("fold", { posture });
|
||||
// The other panel lights at another size: every stored coordinate and element reference is stale.
|
||||
delete state.screen;
|
||||
delete state.refs;
|
||||
state.generation += 1;
|
||||
// Argent's accessibility reader can keep reading the panel that went dark (seen on iPhone Duo when it had read
|
||||
// the outer panel before the fold): its tree keeps the old panel's shape and comes back bare. Nothing is read
|
||||
// before the fold, and the tree must take the shape of the panel the fold lit before the bridge answers.
|
||||
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);
|
||||
}
|
||||
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 "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.
|
||||
case "settings": return failure("CONTROLLER_UNSUPPORTED", "Argent cannot change the device's appearance yet.");
|
||||
case "logs": return failure("CONTROLLER_UNSUPPORTED", "Argent does not provide device logs to Explore.");
|
||||
default: return failure("INVALID_ARGS", `Unsupported command for the Argent controller: ${command ?? ""}`);
|
||||
}
|
||||
} catch (error) {
|
||||
if (error instanceof UnsentFailure) return remoteUnavailable();
|
||||
if (error instanceof BridgeFailure) return failure(error.code, error.message);
|
||||
if (error instanceof ArgentCallError) {
|
||||
// Never "Remote daemon is unavailable" here: the request may have run, so Explore must not resend it.
|
||||
return failure(error.sent ? "ARGENT_TOOL_FAILED" : "COMMAND_FAILED", error.sent ? error.message : "Remote daemon is unavailable");
|
||||
}
|
||||
return failure("ARGENT_BRIDGE_FAILED", error instanceof Error ? error.message : String(error));
|
||||
}
|
||||
|
||||
/** Accepts iOS's "Open in “<app>”?" once per session; later links in the same session open without it. */
|
||||
async function acceptDeepLinkPrompt(bundleId: string | undefined) {
|
||||
for (let poll = 0; poll < 6; poll++) {
|
||||
await context.sleep(700);
|
||||
const current = await tree();
|
||||
// Argent can read nothing while iOS 27.1 shows the prompt; find Open in a screenshot instead.
|
||||
if (blindTree(current) && poll >= 1 && context.scratchImage) {
|
||||
if (await pressOpenFromScreenshot(context.scratchImage)) { state.deepLinkPromptAccepted = true; return; }
|
||||
continue;
|
||||
}
|
||||
if (!openInAppPromptShowing(current)) {
|
||||
if (bundleId && appReady(current, bundleId)) { state.deepLinkPromptAccepted = true; return; }
|
||||
// Another alert is the app's or the system's own business; capture answers it, the bridge does not.
|
||||
if (current.alertVisible) return;
|
||||
continue;
|
||||
}
|
||||
const size = current.screen;
|
||||
if (!size) break;
|
||||
const open = describedButton(await call("describe").then(described => described.description, () => undefined), "Open");
|
||||
// Without a described button, the prompt's Open button sits at a fixed offset from the centre on iPhone 17.
|
||||
await tap(...(open ? Object.values(centre(open, { width: 1, height: 1 })) as [number, number]
|
||||
: [0.5 + DEEP_LINK_PROMPT_CONFIRM.dxPoints / size.width, 0.5 + DEEP_LINK_PROMPT_CONFIRM.dyPoints / size.height] as [number, number]));
|
||||
if (await promptCleared()) { state.deepLinkPromptAccepted = true; return; }
|
||||
throw new BridgeFailure("CONTROLLER_DEEP_LINK_PROMPT", "iOS kept asking to open the link in the app after Open was pressed.");
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* After Open is pressed, the prompt can stay in the tree for a second or two while the app comes forward (observed on
|
||||
* iPhone Duo's inner display), so the bridge reads again for a few seconds before it calls the press a failure.
|
||||
*/
|
||||
async function promptCleared(): Promise<boolean> {
|
||||
for (let poll = 0; poll < 6; poll++) {
|
||||
await context.sleep(1_000);
|
||||
if (!openInAppPromptShowing(await tree())) return true;
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
/** Taps the Open button found in a screenshot, then confirms it is gone. */
|
||||
async function pressOpenFromScreenshot(scratch: NonNullable<ArgentBridgeContext["scratchImage"]>): Promise<boolean> {
|
||||
await call("screenshot", { scale: 1 }, { out: scratch.path });
|
||||
const open = findOpenButton(await scratch.read(scratch.path));
|
||||
if (!open) return false;
|
||||
await tap(open.x, open.y);
|
||||
await context.sleep(1_000);
|
||||
const after = await tree();
|
||||
if (!blindTree(after)) return !openInAppPromptShowing(after);
|
||||
await call("screenshot", { scale: 1 }, { out: scratch.path });
|
||||
return !findOpenButton(await scratch.read(scratch.path));
|
||||
}
|
||||
|
||||
function readAlert(current: ArgentTree) {
|
||||
const androidDialog = platform === "android"
|
||||
? (current.roots ?? []).find(root => root.bundleId && root.bundleId !== ANDROID_SYSTEM_UI && root.bundleId !== (bundleFlag ?? current.foregroundApp))
|
||||
: undefined;
|
||||
if (!androidDialog && !alertShowing(current)) return undefined;
|
||||
const size = current.screen ?? state.screen ?? { width: 1, height: 1 };
|
||||
const nodes = flatten(current);
|
||||
const container = nodes.find(node => node.type === "Alert")
|
||||
?? nodes.find(node => (node.children ?? []).length > 0 && OPEN_IN_APP_PROMPT.test(node.label ?? "")) ?? androidDialog;
|
||||
if (!container) return undefined;
|
||||
const inside = flatten({ roots: [container] });
|
||||
const buttons = inside.filter(node => /Button/.test(node.type ?? node.role ?? "") && node.label && node.frame)
|
||||
.map(node => ({ label: node.label!, rect: { x: node.frame!.x * size.width, y: node.frame!.y * size.height, width: node.frame!.width * size.width, height: node.frame!.height * size.height } }));
|
||||
const text = inside.filter(node => /StaticText|TextView/.test(node.type ?? node.role ?? "") && node.label).map(node => node.label!);
|
||||
return buttons.length ? { message: text.join(" ") || container.label || "", items: buttons.map(button => button.label), buttons } : undefined;
|
||||
}
|
||||
}
|
||||
|
||||
class BridgeFailure extends Error { constructor(readonly code: string, message: string) { super(message); } }
|
||||
class UnsentFailure extends Error {}
|
||||
|
||||
/** Argent's `fill` and `keyboard` would expand `{{secret:NAME}}` from Argent's own secret store; Explore resolves its own. */
|
||||
function rejectSecretPlaceholder(text: string) {
|
||||
if (/\{\{\s*secret\s*:/i.test(text)) throw new BridgeFailure("INVALID_ARGS", "Text for the device must not contain a {{secret:…}} placeholder.");
|
||||
}
|
||||
@@ -1,6 +1,6 @@
|
||||
import { CiError } from "../shared/ci-errors.js";
|
||||
|
||||
export const EAS_CLI_VERSION = "24.4.2";
|
||||
export const EAS_CLI_VERSION = "25.0.0";
|
||||
export { AGENT_DEVICE_VERSION } from "../shared/agent-device-version.js";
|
||||
|
||||
export const CONTROLLER_SESSION = "expo-explore-runtime";
|
||||
|
||||
@@ -0,0 +1,43 @@
|
||||
import { mkdir, writeFile } from "node:fs/promises";
|
||||
import { join } from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
import type { SimulatorConnection } from "./simulator.js";
|
||||
import { controllerCacheRoot } from "../shared/controller-cache.js";
|
||||
|
||||
/** The Argent bridge's entry, run where agent-device's CLI would be. */
|
||||
export const ARGENT_CONTROLLER_WORKER = fileURLToPath(new URL("./argent-controller-worker.js", import.meta.url));
|
||||
|
||||
const shellQuote = (value: string) => `'${value.replace(/'/g, `'\\''`)}'`;
|
||||
|
||||
/**
|
||||
* The command and environment that drive an Argent session the way agent-device's are run: a small executable in
|
||||
* the run's private directory runs the bridge with this Node, so every caller keeps passing one command and its
|
||||
* arguments. The bridge gets only the session's tool-server variables, telemetry off, and a HOME of its own, so
|
||||
* Argent's state (links, downloaded recordings) is never shared between runs or sides of a review.
|
||||
*/
|
||||
export async function argentControllerInvocation(options: {
|
||||
directory: string; connection: SimulatorConnection; platform: "ios" | "android"; environment: NodeJS.ProcessEnv; bundleId?: string;
|
||||
/** The caller's full environment, which names the controller cache and npm registry the narrowed one drops. */
|
||||
sourceEnvironment?: NodeJS.ProcessEnv;
|
||||
}): Promise<{ command: string; environment: NodeJS.ProcessEnv }> {
|
||||
const source = options.sourceEnvironment ?? options.environment;
|
||||
const home = join(options.directory, "argent-home");
|
||||
await mkdir(home, { recursive: true, mode: 0o700 });
|
||||
const command = join(options.directory, "argent-controller");
|
||||
await writeFile(command, `#!/bin/sh\nexec ${shellQuote(process.execPath)} ${shellQuote(ARGENT_CONTROLLER_WORKER)} "$@"\n`, { mode: 0o700 });
|
||||
// agent-device's variables never reach Argent's bridge, and Argent's never reach agent-device.
|
||||
const environment = Object.fromEntries(Object.entries(options.environment).filter(([name]) => !/^(AGENT_DEVICE_|ARGENT_)/.test(name)));
|
||||
return {
|
||||
command,
|
||||
environment: { ...environment, HOME: home, DO_NOT_TRACK: "1",
|
||||
ARGENT_TOOLS_URL: options.connection.daemonBaseUrl,
|
||||
...(options.connection.daemonAuthToken ? { ARGENT_AUTH_TOKEN: options.connection.daemonAuthToken } : {}),
|
||||
EXPLORE_ARGENT_STATE: join(options.directory, "argent-state.json"), EXPLORE_ARGENT_PLATFORM: options.platform,
|
||||
// The bridge runs with a HOME of its own, so it is told where the fetched Argent release is cached.
|
||||
EXPLORE_CONTROLLER_CACHE: controllerCacheRoot(source),
|
||||
...(source.EXPLORE_NPM_REGISTRY ? { EXPLORE_NPM_REGISTRY: source.EXPLORE_NPM_REGISTRY } : {}),
|
||||
// Opt-in: each Argent call to a JSON-lines log, one file per session, for debugging a controller run.
|
||||
...(source.EXPLORE_ARGENT_LOG_DIR ? { EXPLORE_ARGENT_LOG_DIR: source.EXPLORE_ARGENT_LOG_DIR, EXPLORE_ARGENT_LOG_NAME: options.connection.sessionId } : {}),
|
||||
...(options.bundleId ? { EXPLORE_ARGENT_BUNDLE_ID: options.bundleId } : {}) },
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,32 @@
|
||||
/**
|
||||
* Runs a device controller Explore fetches on first use: `controller-launcher.js <controller> <args...>` makes sure
|
||||
* the pinned release is in the cache, then runs it with the arguments, passing its output and exit code through.
|
||||
* A failed fetch answers in agent-device's JSON envelope, so callers report it like any controller failure.
|
||||
*/
|
||||
import { spawn } from "node:child_process";
|
||||
import { ensureController, type ControllerName } from "../shared/controller-cache.js";
|
||||
|
||||
async function main(): Promise<number> {
|
||||
const [controller, ...args] = process.argv.slice(2);
|
||||
if (controller !== "agent-device") {
|
||||
process.stdout.write(JSON.stringify({ success: false, error: { code: "INVALID_ARGS", message: `Unknown controller: ${controller ?? ""}` } }));
|
||||
return 1;
|
||||
}
|
||||
let bin: string;
|
||||
try { bin = await ensureController(controller as ControllerName, { progress: message => process.stderr.write(`[explore] ${message}\n`) }); }
|
||||
catch (error) {
|
||||
const failure = error as { code?: string; message?: string; nextAction?: string };
|
||||
process.stdout.write(JSON.stringify({ success: false, error: { code: failure.code ?? "CONTROLLER_DOWNLOAD_FAILED",
|
||||
message: failure.message ?? String(error), ...(failure.nextAction ? { hint: failure.nextAction } : {}) } }));
|
||||
return 1;
|
||||
}
|
||||
return new Promise(resolve => {
|
||||
const child = spawn(process.execPath, [bin, ...args], { stdio: "inherit" });
|
||||
// A capture that stops the launcher stops the controller with it.
|
||||
for (const signal of ["SIGINT", "SIGTERM"] as const) process.on(signal, () => child.kill(signal));
|
||||
child.on("exit", (code, signal) => resolve(code ?? (signal ? 1 : 0)));
|
||||
child.on("error", () => resolve(1));
|
||||
});
|
||||
}
|
||||
|
||||
process.exitCode = await main();
|
||||
@@ -1,4 +1,4 @@
|
||||
import { appearanceArgs, bundleColorSchemes, mergeSchemeOutcomes, resolveColorSchemes, routeIdOfScreen, type AppearanceSetting, type ColorScheme } from "./appearance.js";
|
||||
import { appearanceArgs, argentColorSchemes, bundleColorSchemes, mergeSchemeOutcomes, resolveColorSchemes, routeIdOfScreen, type AppearanceSetting, type ColorScheme } from "./appearance.js";
|
||||
import { assertNoCaptureHealthIssues, captureHealthIssues, partitionCaptureHealthIssues } from "./health.js";
|
||||
import { type RouteResetSetting } from "./route-reset.js";
|
||||
import { defaultReadinessSeconds } from "./readiness.js";
|
||||
@@ -14,15 +14,16 @@ import type { SourceCapturePlan } from "../source/capture-plan.js";
|
||||
import { CONTRACT, type ExploreMap, type Platform, type RunStatus } from "../types.js";
|
||||
import { ExploreStore, validateMap } from "../map/store.js";
|
||||
import { CiError, serializeCiError, toCiError } from "../shared/ci-errors.js";
|
||||
import type { CaptureSetupAction } from "../config/explore-config.js";
|
||||
import type { CaptureSetupAction, DevicePose } from "../config/explore-config.js";
|
||||
import { type CiAgentRuntimeOptions } from "./agent/runtime.js";
|
||||
import { EAS_CLI_VERSION, AGENT_DEVICE_VERSION, CONTROLLER_SESSION, isRecord, parseJson, baseEnvironment, nonEmpty } from "./common.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 { defaultRunner } 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, simulatorOsVersion, type ActiveSimulatorRuntime } from "./simulator.js";
|
||||
import { SIMULATOR_DOTENV_FILE_NAME, SIMULATOR_DOTENV_HEADER, simulatorSessionName, simulatorStartFailure, readSimulatorDotenvHandoff, assertSimulatorSessionIdentity, assertSimulatorStopped, collectRuntime, controllerVersion, simulatorOsVersion, type ActiveSimulatorRuntime } from "./simulator.js";
|
||||
import { argentControllerInvocation } from "./controller-invocation.js";
|
||||
import { type UnattributedSetting } from "./unattributed.js";
|
||||
import { appScheme, hasConcreteRoutePath, unavailableRoute, capturePlannedRoutes, deviceArgs } from "./route-capture.js";
|
||||
|
||||
@@ -51,6 +52,10 @@ export type CiMapOptions = {
|
||||
/** Host-side pause used while a controller read is resent; tests pair it with `now` so recovery waits are not real time. */
|
||||
sleep?: (milliseconds: number) => void;
|
||||
easCommand: string; repackCommand: string; agentDeviceCommand: string;
|
||||
/** The device controller EAS starts on the session; agent-device unless the config chose Argent. */
|
||||
controller?: "agent-device" | "argent";
|
||||
/** A foldable's pose (device.pose), set with the controller's `fold` before anything is captured. */
|
||||
devicePose?: DevicePose;
|
||||
/** Where the route observer is bundled into the app: a hosted EAS repack job (default) or repack-app on this machine. */
|
||||
repack?: RepackMode;
|
||||
/** Which appearances to capture; `auto` (default) follows the app's `userInterfaceStyle`. */
|
||||
@@ -69,7 +74,7 @@ export type CiMapOptions = {
|
||||
signal?: AbortSignal;
|
||||
};
|
||||
export type SimulatorRuntimeMetadata = {
|
||||
provider: "eas-simulator"; controller: "agent-device"; controllerPackageVersion: string;
|
||||
provider: "eas-simulator"; controller: "agent-device" | "argent"; controllerPackageVersion: string;
|
||||
easCliVersion: string; platform: Platform; deviceModel: string; osVersion: string; locale: string;
|
||||
orientation: "portrait" | "landscape"; colorScheme: "light" | "dark" | "system"; colorSchemes?: ColorScheme[];
|
||||
sessionLifecycle: "stopped";
|
||||
@@ -94,7 +99,7 @@ function newCaptureMap(options: CiMapOptions, runtime?: ActiveSimulatorRuntime,
|
||||
const timestamp = new Date((options.now ?? Date.now)()).toISOString();
|
||||
return {
|
||||
contract: CONTRACT, revision: 0,
|
||||
run: { id: options.buildId, name: options.name, platform: options.platform, controller: "agent-device", status: "draft",
|
||||
run: { id: options.buildId, name: options.name, platform: options.platform, controller: options.controller ?? "agent-device", status: "draft",
|
||||
bundleId: options.bundleId, ...(runtime ? { deviceId: runtime.controllerDeviceId } : {}),
|
||||
createdAt: timestamp, updatedAt: timestamp,
|
||||
build: { id: options.buildId, version: options.buildVersion, gitCommit: options.gitCommit, source: "eas", ...(fingerprint ? { hash: fingerprint } : {}) },
|
||||
@@ -163,6 +168,7 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
|
||||
const setup = revisionSetup(options.setup ?? [], plan, side);
|
||||
const runner = options.runner ?? defaultRunner;
|
||||
const sourceEnvironment = options.environment ?? process.env;
|
||||
const controller = options.controller ?? "agent-device";
|
||||
const restrictedEnvironment = baseEnvironment(sourceEnvironment);
|
||||
const easEnvironment = { ...restrictedEnvironment, ...(options.expoToken ? { EXPO_TOKEN: options.expoToken } : {}) };
|
||||
const assertCheckout = () => {
|
||||
@@ -279,7 +285,7 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
|
||||
app = { name: cachedBundle.appName ?? options.name };
|
||||
appIcon = await loadCachedAppIcon(cacheRoot, cachedBundle.appIcon);
|
||||
const cachedProfile = cachedBundle.runtimeProfile!;
|
||||
runtime = { provider: "eas-simulator", controller: "agent-device", controllerPackageVersion: AGENT_DEVICE_VERSION,
|
||||
runtime = { provider: "eas-simulator", controller, controllerPackageVersion: controllerVersion(controller),
|
||||
easCliVersion: EAS_CLI_VERSION, platform: options.platform, controllerDeviceId: cachedDeviceId ?? "cached",
|
||||
deviceModel: cachedProfile.deviceModel, osVersion: cachedProfile.osVersion, locale: cachedProfile.locale,
|
||||
orientation: cachedProfile.orientation === "landscape" ? "landscape" : "portrait",
|
||||
@@ -349,7 +355,7 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
|
||||
await rm(launchWorkDirectory, { recursive: true, force: true });
|
||||
const storedIcon = appIcon ? await storeAppIcon(outputDirectory, appIcon) : undefined;
|
||||
const bundle: CaptureBundle = { contract: "explore.bundle", side, gitCommit: options.gitCommit, easBuildId, completedAt: map.run.completedAt,
|
||||
easProjectId: projectId, platform: options.platform, profile: options.easProfile, appName: app.name, ...(storedIcon ? { appIcon: storedIcon } : {}),
|
||||
easProjectId: projectId, platform: options.platform, profile: options.easProfile, appName: app.name, ...(controller === "argent" ? { controller } : {}), ...(storedIcon ? { appIcon: storedIcon } : {}),
|
||||
selectedSurfaceIds: selectedIds,
|
||||
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) },
|
||||
@@ -381,6 +387,11 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
|
||||
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);
|
||||
if (controller === "argent") {
|
||||
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;
|
||||
}
|
||||
app = { name: profile.projectIdentity.name, ...(profile.projectIdentity.version ? { version: profile.projectIdentity.version } : {}),
|
||||
...(profile.projectIdentity.buildNumber ? { buildNumber: profile.projectIdentity.buildNumber } : {}) };
|
||||
projectId = profile.projectIdentity.projectId;
|
||||
@@ -446,7 +457,7 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
|
||||
await writeFile(dotenvPath, SIMULATOR_DOTENV_HEADER, { flag: "wx", mode: 0o600 });
|
||||
let startError: unknown;
|
||||
try { eas(["simulator:start", "--name", sessionName, "--platform", options.platform, "--device", options.device,
|
||||
"--type", "agent-device", "--package-version", AGENT_DEVICE_VERSION, "--build-id", easBuildId,
|
||||
"--type", controller, "--package-version", controllerVersion(controller), "--build-id", easBuildId, "--public-link",
|
||||
"--max-duration-minutes", String(options.maxDurationMinutes), "--out-config-type", "dotenv", "--non-interactive"], 20 * 60_000, simulatorProject); }
|
||||
catch (error) { startError = error; }
|
||||
const handoff = await readSimulatorDotenvHandoff(dotenvPath);
|
||||
@@ -480,15 +491,29 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
|
||||
await rm(dotenvPath, { force: true });
|
||||
const controllerConfig = join(simulatorProject, "agent-device.json");
|
||||
await writeFile(controllerConfig, "{}\n", { flag: "wx", mode: 0o400 });
|
||||
const controllerEnvironment = { ...restrictedEnvironment, AGENT_DEVICE_CONFIG: controllerConfig,
|
||||
const argent = controller === "argent"
|
||||
? await argentControllerInvocation({ directory: simulatorProject, connection: handoff.connection, platform: options.platform, environment: restrictedEnvironment, sourceEnvironment, bundleId: options.bundleId })
|
||||
: undefined;
|
||||
const controllerEnvironment = argent?.environment ?? { ...restrictedEnvironment, AGENT_DEVICE_CONFIG: controllerConfig,
|
||||
AGENT_DEVICE_DAEMON_BASE_URL: handoff.connection.daemonBaseUrl, AGENT_DEVICE_DAEMON_AUTH_TOKEN: handoff.connection.daemonAuthToken,
|
||||
AGENT_DEVICE_SESSION: CONTROLLER_SESSION, AGENT_DEVICE_SESSION_LOCK: "reject", AGENT_DEVICE_PLATFORM: options.platform };
|
||||
// Every controller call below goes to the session's controller; for Argent that is the bridge.
|
||||
const controllerCommand = argent?.command ?? options.agentDeviceCommand;
|
||||
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}`);
|
||||
runner({ command: controllerCommand, args: ["fold", options.devicePose, "--session", CONTROLLER_SESSION,
|
||||
...deviceArgs({ platform: options.platform, deviceModel: options.device }), "--platform", options.platform, "--json"],
|
||||
cwd: simulatorProject, environment: controllerEnvironment, timeoutMs: 2 * 60_000 });
|
||||
}
|
||||
runtimeStage = "runtime";
|
||||
setStage(runtimeStage);
|
||||
runtime = collectRuntime(options, controllerEnvironment);
|
||||
runtime = collectRuntime({ ...options, agentDeviceCommand: controllerCommand }, controllerEnvironment);
|
||||
runtime.colorScheme = colorSchemes[0]!;
|
||||
// The version is descriptive; a capture proceeds without it and records "unknown".
|
||||
try {
|
||||
// The version is descriptive; a capture proceeds without it and records "unknown". Argent names it with the device;
|
||||
// agent-device's is always taken from the session, as before.
|
||||
if (runtime.osVersion === "unknown" || controller !== "argent") try {
|
||||
runtime.osVersion = await simulatorOsVersion(eas(["simulator:get", "--id", sessionId, "--json", "--non-interactive"], 2 * 60_000).stdout,
|
||||
runtime.controllerDeviceId, options.fetch ?? fetch, options.platform);
|
||||
} catch (error) {
|
||||
@@ -504,7 +529,8 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
|
||||
const passes: CaptureBundle["outcomes"][] = [];
|
||||
const recordingTools = launchSetting === "off" ? undefined : options.recordingTools === undefined ? ffmpegRecordingTools() : options.recordingTools ?? undefined;
|
||||
for (const [index, colorScheme] of colorSchemes.entries()) {
|
||||
runner({ command: options.agentDeviceCommand, args: [...appearanceArgs(colorScheme), "--session", CONTROLLER_SESSION, ...deviceArgs(runtime), "--platform", options.platform],
|
||||
// Argent cannot switch the appearance yet (software-mansion/argent#1509); 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 });
|
||||
// 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.
|
||||
@@ -516,7 +542,7 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
|
||||
const record = await captureLaunch({ bundleId: options.bundleId, keepVideo: launchSetting === "video", platform: options.platform,
|
||||
directory: join(launchWorkDirectory, launchDirectory(colorScheme)), relativeDirectory: launchDirectory(colorScheme), ...(options.now ? { now: options.now } : {}),
|
||||
...(recordingTools ? { recordingTools } : {}),
|
||||
controller: (args, controllerOptions) => runner({ command: options.agentDeviceCommand, args: [...args, "--session", CONTROLLER_SESSION, ...deviceArgs(runtime!), "--platform", options.platform],
|
||||
controller: (args, controllerOptions) => runner({ command: controllerCommand, args: [...args, "--session", CONTROLLER_SESSION, ...deviceArgs(runtime!), "--platform", options.platform],
|
||||
cwd: simulatorProject, environment: controllerEnvironment, timeoutMs: controllerOptions?.timeoutMs ?? 60_000, ...(controllerOptions?.allowFailure ? { allowFailure: true } : {}) }) });
|
||||
launch[colorScheme] = { root: launchWorkDirectory, record };
|
||||
} catch (error) {
|
||||
@@ -524,11 +550,11 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
|
||||
say(`the app launch could not be observed (${(error as Error).message}); the report has no launch evidence for ${colorScheme}`);
|
||||
await rm(join(launchWorkDirectory, launchDirectory(colorScheme)), { recursive: true, force: true });
|
||||
}
|
||||
} else if (index > 0) runner({ command: options.agentDeviceCommand, args: ["open", options.bundleId, "--relaunch", "--session", CONTROLLER_SESSION,
|
||||
} else if (index > 0) 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 });
|
||||
runtime.colorScheme = colorScheme;
|
||||
if (colorSchemes.length > 1) say(`appearance ${colorScheme} (${index + 1}/${colorSchemes.length})`);
|
||||
passes.push(await capturePlannedRoutes({ capture: { ...options, setup, progress: say }, routes: missingRoutes, inventory, scheme, appName: app.name, runtime,
|
||||
passes.push(await capturePlannedRoutes({ capture: { ...options, agentDeviceCommand: controllerCommand, setup, progress: say }, routes: missingRoutes, inventory, scheme, appName: app.name, runtime,
|
||||
connection: handoff.connection, environment: controllerEnvironment, store, map, acceptedFrames, outcomes: index === 0 ? outcomes : {},
|
||||
...(colorSchemes.length > 1 ? { appearance: { scheme: colorScheme, primary: index === 0 } } : {}) }));
|
||||
}
|
||||
|
||||
@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
|
||||
import { readFile } from "node:fs/promises";
|
||||
import { toCiError, serializeCiError, CiError } from "../shared/ci-errors.js";
|
||||
import { isRecord, parseJson, baseEnvironment, AGENT_DEVICE_VERSION, CONTROLLER_SESSION, EAS_CLI_VERSION } from "./common.js";
|
||||
import { ARGENT_VERSION } from "../shared/argent-version.js";
|
||||
import { SIMULATOR_PREVIEW_HOST, framedSimulatorPreviewServer } from "../shared/simulator-preview.js";
|
||||
import { lstatIfExists } from "./fs-safety.js";
|
||||
import { defaultRunner, openedSimulatorDevice, controllerData } from "./controller.js";
|
||||
@@ -9,7 +10,21 @@ import type { RepackProfile } from "./eas-build.js";
|
||||
import type { SimulatorRuntimeMetadata, CiMapOptions } from "./run.js";
|
||||
import type { Platform } from "../types.js";
|
||||
|
||||
export type SimulatorConnection = { sessionId: string; daemonBaseUrl: string; daemonAuthToken: string };
|
||||
/**
|
||||
* How Explore reaches a session's device controller. For agent-device (no `controller`) these are the daemon's URL and
|
||||
* token; for Argent they are the tool-server's `ARGENT_TOOLS_URL` and `ARGENT_AUTH_TOKEN`, whose token may be empty.
|
||||
*/
|
||||
export type SimulatorConnection = { sessionId: string; daemonBaseUrl: string; daemonAuthToken: string; controller?: "argent" };
|
||||
|
||||
/** The controller a connection reaches: the session `--type` EAS started. */
|
||||
export function connectionController(connection: Pick<SimulatorConnection, "controller">): "agent-device" | "argent" {
|
||||
return connection.controller ?? "agent-device";
|
||||
}
|
||||
|
||||
/** The controller's pinned version: what EAS installs on the session (`--package-version`) and what runs here. */
|
||||
export function controllerVersion(controller: "agent-device" | "argent"): string {
|
||||
return controller === "argent" ? ARGENT_VERSION : AGENT_DEVICE_VERSION;
|
||||
}
|
||||
export type ActiveSimulatorRuntime = Omit<SimulatorRuntimeMetadata, "sessionLifecycle"> & { controllerDeviceId: string };
|
||||
const SIMULATOR_SESSION_NAME_MAX_CHARACTERS = 50;
|
||||
const SIMULATOR_SESSION_DIGEST_CHARACTERS = 20;
|
||||
@@ -64,24 +79,28 @@ function simulatorConnection(
|
||||
sessionId: string,
|
||||
daemonBaseUrl: unknown,
|
||||
daemonAuthToken: unknown,
|
||||
controller: "agent-device" | "argent" = "agent-device",
|
||||
): SimulatorConnection {
|
||||
// An Argent tool-server may run without a token (ARGENT_AUTH_TOKEN is only set when it needs one).
|
||||
if (controller === "argent" && daemonAuthToken === undefined) daemonAuthToken = "";
|
||||
if (
|
||||
typeof daemonBaseUrl !== "string"
|
||||
|| typeof daemonAuthToken !== "string"
|
||||
|| !daemonBaseUrl
|
||||
|| !daemonAuthToken
|
||||
|| (!daemonAuthToken && controller !== "argent")
|
||||
|| daemonBaseUrl.length > 2_048
|
||||
|| daemonAuthToken.length > 8_192
|
||||
|| /[\u0000-\u001f\u007f]/.test(daemonBaseUrl)
|
||||
|| /[\u0000-\u001f\u007f]/.test(daemonAuthToken)
|
||||
) {
|
||||
throw new Error("eas simulator:start returned an unsafe agent-device connection");
|
||||
throw new Error(`eas simulator:start returned an unsafe ${controller} connection`);
|
||||
}
|
||||
remoteDaemonDomain(daemonBaseUrl);
|
||||
remoteDaemonDomain(daemonBaseUrl, controller);
|
||||
return {
|
||||
sessionId,
|
||||
daemonBaseUrl,
|
||||
daemonAuthToken,
|
||||
...(controller === "argent" ? { controller } : {}),
|
||||
};
|
||||
}
|
||||
|
||||
@@ -100,7 +119,7 @@ export function simulatorStartFailure(error: unknown, secrets: readonly string[]
|
||||
message: source.message.replace(/\\+(["'/])/g, "$1"),
|
||||
nextAction: "Inspect the EAS simulator start failure." }), { secrets });
|
||||
const message = failure.message
|
||||
.replace(/\b(?:AGENT_DEVICE_[A-Z_]+|EAS_SIMULATOR_[A-Z_]+|EXPO_TOKEN|agentDeviceRemoteSession(?:Token|Url)|webPreviewUrl)["']?\s*[:=][^\r\n]*/g, "[REDACTED_HANDOFF]")
|
||||
.replace(/\b(?:AGENT_DEVICE_[A-Z_]+|ARGENT_[A-Z_]+|EAS_SIMULATOR_[A-Z_]+|EXPO_TOKEN|agentDeviceRemoteSession(?:Token|Url)|toolsUrl|toolsAuthToken|webPreviewUrl|previewApiUrl)["']?\s*[:=][^\r\n]*/g, "[REDACTED_HANDOFF]")
|
||||
.replace(/\b[A-Za-z][A-Za-z0-9+.-]*:\/\/[^\s<>"']+/g, "[REDACTED_URL]")
|
||||
.slice(0, 1600);
|
||||
return { code: failure.code, stage: "session", message,
|
||||
@@ -149,6 +168,8 @@ export async function readSimulatorDotenvHandoff(path: string): Promise<Simulato
|
||||
"EAS_SIMULATOR_SESSION_ID",
|
||||
"AGENT_DEVICE_DAEMON_BASE_URL",
|
||||
"AGENT_DEVICE_DAEMON_AUTH_TOKEN",
|
||||
"ARGENT_TOOLS_URL",
|
||||
"ARGENT_AUTH_TOKEN",
|
||||
].includes(name)) {
|
||||
validationError ??= new Error("EAS Simulator dotenv handoff contains an unexpected assignment");
|
||||
continue;
|
||||
@@ -177,11 +198,14 @@ export async function readSimulatorDotenvHandoff(path: string): Promise<Simulato
|
||||
let connection: SimulatorConnection | undefined;
|
||||
if (sessionId) {
|
||||
try {
|
||||
connection = simulatorConnection(
|
||||
sessionId,
|
||||
assignments.AGENT_DEVICE_DAEMON_BASE_URL,
|
||||
assignments.AGENT_DEVICE_DAEMON_AUTH_TOKEN,
|
||||
);
|
||||
// An `argent` session writes the Argent tool-server's variables instead of agent-device's.
|
||||
connection = assignments.ARGENT_TOOLS_URL !== undefined
|
||||
? simulatorConnection(sessionId, assignments.ARGENT_TOOLS_URL, assignments.ARGENT_AUTH_TOKEN, "argent")
|
||||
: simulatorConnection(
|
||||
sessionId,
|
||||
assignments.AGENT_DEVICE_DAEMON_BASE_URL,
|
||||
assignments.AGENT_DEVICE_DAEMON_AUTH_TOKEN,
|
||||
);
|
||||
} catch (error) {
|
||||
validationError ??= error instanceof Error ? error : new Error(String(error));
|
||||
}
|
||||
@@ -207,7 +231,7 @@ export function assertSimulatorSessionIdentity(
|
||||
sessionId !== expectedSessionId
|
||||
|| !isRecord(value)
|
||||
|| value.name !== expectedSessionName
|
||||
|| value.type !== "agent-device"
|
||||
|| value.type !== (expectedConnection ? connectionController(expectedConnection) : "agent-device")
|
||||
|| value.platform !== expectedPlatform.toUpperCase()
|
||||
|| value.status !== "IN_PROGRESS"
|
||||
) {
|
||||
@@ -226,17 +250,19 @@ export function assertSimulatorSessionIdentity(
|
||||
if (!projectProven) {
|
||||
throw new Error("eas simulator:get did not prove the exact expected simulator session");
|
||||
}
|
||||
if (expectedConnection) {
|
||||
if (
|
||||
!isRecord(value.remoteConfig)
|
||||
|| value.remoteConfig.agentDeviceRemoteSessionUrl !== expectedConnection.daemonBaseUrl
|
||||
|| value.remoteConfig.agentDeviceRemoteSessionToken !== expectedConnection.daemonAuthToken
|
||||
) {
|
||||
throw new Error("eas simulator:get returned a different agent-device connection");
|
||||
}
|
||||
if (expectedConnection && !remoteConfigMatches(value.remoteConfig, expectedConnection)) {
|
||||
throw new Error(`eas simulator:get returned a different ${connectionController(expectedConnection)} connection`);
|
||||
}
|
||||
}
|
||||
|
||||
/** 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;
|
||||
return connectionController(connection) === "argent"
|
||||
? remoteConfig.toolsUrl === connection.daemonBaseUrl && (remoteConfig.toolsAuthToken ?? "") === connection.daemonAuthToken
|
||||
: remoteConfig.agentDeviceRemoteSessionUrl === connection.daemonBaseUrl && remoteConfig.agentDeviceRemoteSessionToken === connection.daemonAuthToken;
|
||||
}
|
||||
|
||||
/**
|
||||
* A session Explore did not start: the connection comes from `eas simulator:start --out-config-type dotenv`
|
||||
* (`.env.eas-simulator`) or from the `EAS_SIMULATOR_SESSION_ID` / `AGENT_DEVICE_DAEMON_*` variables that
|
||||
@@ -263,7 +289,9 @@ export async function resolveAttachedSimulatorSession(
|
||||
if (requestedSessionId && environment.EAS_SIMULATOR_SESSION_ID && environment.EAS_SIMULATOR_SESSION_ID !== requestedSessionId) {
|
||||
throw new Error(`EAS_SIMULATOR_SESSION_ID is ${environment.EAS_SIMULATOR_SESSION_ID}, not ${requestedSessionId}`);
|
||||
}
|
||||
return simulatorConnection(sessionId, environment.AGENT_DEVICE_DAEMON_BASE_URL, environment.AGENT_DEVICE_DAEMON_AUTH_TOKEN);
|
||||
return environment.ARGENT_TOOLS_URL !== undefined && environment.AGENT_DEVICE_DAEMON_BASE_URL === undefined
|
||||
? simulatorConnection(sessionId, environment.ARGENT_TOOLS_URL, environment.ARGENT_AUTH_TOKEN, "argent")
|
||||
: simulatorConnection(sessionId, environment.AGENT_DEVICE_DAEMON_BASE_URL, environment.AGENT_DEVICE_DAEMON_AUTH_TOKEN);
|
||||
}
|
||||
|
||||
/** Proves an attached session is live, agent-device typed, and served by the connection we hold; returns its platform. */
|
||||
@@ -274,8 +302,8 @@ export function assertAttachedSimulatorSession(
|
||||
): { platform: Platform; name: string; deviceRunSessionUrl?: string } {
|
||||
const value = parseJson(stdout, "eas simulator:get");
|
||||
const sessionId = simulatorSessionId(value, "eas simulator:get");
|
||||
if (sessionId !== connection.sessionId || !isRecord(value) || value.type !== "agent-device") {
|
||||
throw new Error("eas simulator:get did not describe the attached agent-device session");
|
||||
if (sessionId !== connection.sessionId || !isRecord(value) || value.type !== connectionController(connection)) {
|
||||
throw new Error(`eas simulator:get did not describe the attached ${connectionController(connection)} session`);
|
||||
}
|
||||
if (value.status !== "IN_PROGRESS") {
|
||||
throw new Error(`EAS Simulator session ${sessionId} is ${String(value.status).toLowerCase()}, not in progress`);
|
||||
@@ -284,12 +312,8 @@ export function assertAttachedSimulatorSession(
|
||||
if (!platform || (expectedPlatform && platform !== expectedPlatform)) {
|
||||
throw new Error(`EAS Simulator session ${sessionId} is ${String(value.platform).toLowerCase()}${expectedPlatform ? `, not ${expectedPlatform}` : ""}`);
|
||||
}
|
||||
if (
|
||||
!isRecord(value.remoteConfig)
|
||||
|| value.remoteConfig.agentDeviceRemoteSessionUrl !== connection.daemonBaseUrl
|
||||
|| value.remoteConfig.agentDeviceRemoteSessionToken !== connection.daemonAuthToken
|
||||
) {
|
||||
throw new Error("eas simulator:get returned a different agent-device connection than the one provided");
|
||||
if (!remoteConfigMatches(value.remoteConfig, connection)) {
|
||||
throw new Error(`eas simulator:get returned a different ${connectionController(connection)} connection than the one provided`);
|
||||
}
|
||||
return {
|
||||
platform,
|
||||
@@ -309,12 +333,12 @@ export function assertSimulatorStopped(stdout: string, expectedSessionId: string
|
||||
}
|
||||
}
|
||||
|
||||
function remoteDaemonDomain(value: string): string {
|
||||
function remoteDaemonDomain(value: string, controller: "agent-device" | "argent" = "agent-device"): string {
|
||||
let url: URL;
|
||||
try {
|
||||
url = new URL(value);
|
||||
} catch {
|
||||
throw new Error("eas simulator returned an invalid agent-device URL");
|
||||
throw new Error(`eas simulator returned an invalid ${controller} URL`);
|
||||
}
|
||||
if (
|
||||
url.protocol !== "https:"
|
||||
@@ -322,19 +346,22 @@ function remoteDaemonDomain(value: string): string {
|
||||
|| url.password
|
||||
|| !url.hostname
|
||||
) {
|
||||
throw new Error("eas simulator returned an unsafe agent-device URL");
|
||||
throw new Error(`eas simulator returned an unsafe ${controller} URL`);
|
||||
}
|
||||
return url.hostname;
|
||||
}
|
||||
|
||||
export function collectRuntime(options: CiMapOptions & { platform: NonNullable<CiMapOptions["platform"]> }, environment: NodeJS.ProcessEnv): ActiveSimulatorRuntime {
|
||||
const runner = options.runner ?? defaultRunner;
|
||||
const controller = options.controller ?? "agent-device";
|
||||
const version = runner({ command: options.agentDeviceCommand, args: ["--version"], cwd: options.project,
|
||||
environment: baseEnvironment(options.environment ?? process.env), timeoutMs: 30_000 }).stdout.trim();
|
||||
if (version !== AGENT_DEVICE_VERSION) throw new Error(`agent-device version must be ${AGENT_DEVICE_VERSION}`);
|
||||
environment: controller === "argent" ? environment : baseEnvironment(options.environment ?? process.env), timeoutMs: 30_000 }).stdout.trim();
|
||||
if (version !== controllerVersion(controller)) throw new Error(`${controller} version must be ${controllerVersion(controller)}`);
|
||||
const opened = runner({ command: options.agentDeviceCommand,
|
||||
args: ["open", options.bundleId, "--session", CONTROLLER_SESSION, ...(options.platform === "ios" ? ["--device", options.device] : []),
|
||||
"--platform", options.platform, "--level", "full", "--json"], cwd: options.project, environment, timeoutMs: 60_000 });
|
||||
"--platform", options.platform, "--level", "full", "--json"], cwd: options.project, environment,
|
||||
// Argent's first call can wait for a tool-server that is still starting, then relaunch the app until it is readable.
|
||||
timeoutMs: controller === "argent" ? 180_000 : 60_000 });
|
||||
const device = openedSimulatorDevice(opened.stdout, options.bundleId, "initial app open", options.platform);
|
||||
if (options.platform === "ios" && device.deviceModel !== options.device) throw new CiError({ code: "DEVICE_MISMATCH", stage: "runtime",
|
||||
message: `EAS opened ${device.deviceModel} instead of the configured ${options.device}.`,
|
||||
@@ -345,7 +372,7 @@ export function collectRuntime(options: CiMapOptions & { platform: NonNullable<C
|
||||
const value = deviceData[key] ?? data[key];
|
||||
return typeof value === "string" && value.trim() ? value : "unknown";
|
||||
};
|
||||
return { provider: "eas-simulator", controller: "agent-device", controllerPackageVersion: AGENT_DEVICE_VERSION,
|
||||
return { provider: "eas-simulator", controller, controllerPackageVersion: controllerVersion(controller),
|
||||
easCliVersion: EAS_CLI_VERSION, platform: options.platform, controllerDeviceId: device.deviceId, deviceModel: device.deviceModel,
|
||||
osVersion: observed("osVersion"), locale: observed("locale"),
|
||||
orientation: observed("orientation") === "landscape" ? "landscape" : "portrait",
|
||||
@@ -361,11 +388,15 @@ export function collectRuntime(options: CiMapOptions & { platform: NonNullable<C
|
||||
export async function simulatorOsVersion(session: string, deviceId: string, transport: typeof fetch, platform: "ios" | "android" = "ios"): Promise<string> {
|
||||
const value = parseJson(session, "eas simulator:get");
|
||||
const remote = isRecord(value) && isRecord(value.remoteConfig) ? value.remoteConfig : {};
|
||||
if (typeof remote.webPreviewUrl !== "string") throw new Error("EAS did not publish the simulator preview URL");
|
||||
const preview = new URL(remote.webPreviewUrl);
|
||||
// eas-cli 25 publishes the preview server itself as previewApiUrl, with the token in its query, but only for a
|
||||
// session started with --public-link; its webPreviewUrl is then an expo.dev page with the token in the fragment.
|
||||
// Earlier versions folded the token into webPreviewUrl's query. A private session's output has no token at all.
|
||||
const published = typeof remote.previewApiUrl === "string" ? remote.previewApiUrl : remote.webPreviewUrl;
|
||||
if (typeof published !== "string") throw new Error("EAS did not publish the simulator preview URL");
|
||||
const preview = new URL(published);
|
||||
if (preview.protocol !== "https:" || preview.username || preview.password) throw new Error("The simulator preview URL is not HTTPS");
|
||||
// eas-cli --json folds the preview token into the URL; the catalog takes it as a bearer credential.
|
||||
const token = preview.searchParams.get("token");
|
||||
// The catalog takes the preview token as a bearer credential.
|
||||
const token = preview.searchParams.get("token") ?? new URLSearchParams(preview.hash.slice(1)).get("token");
|
||||
const catalog = new URL(framedSimulatorPreviewServer(preview) ?? preview.origin);
|
||||
if (!SIMULATOR_PREVIEW_HOST.test(catalog.hostname)) throw new Error(`The simulator preview URL names no preview server: ${preview.origin}${preview.pathname}`);
|
||||
// The iOS preview server lists simulators at /grid/api; the Android one has no grid and lists
|
||||
|
||||
@@ -11,6 +11,7 @@ import { canonicalJson } from "../shared/canonical-json.js";
|
||||
import type { ExploreConfig } from "../config/explore-config.js";
|
||||
import { hasVerifiedCapture } from "../capture/health.js";
|
||||
import { CAPTURE_OBSERVER_HASH } from "../capture/observer.js";
|
||||
import { ARGENT_VERSION } from "../shared/argent-version.js";
|
||||
|
||||
const METADATA = "cache-metadata.json";
|
||||
const CONTRACT = "explore.capture-cache";
|
||||
@@ -34,6 +35,8 @@ 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 ?? [], capture: config.capture,
|
||||
// agent-device recipes stay as they were; an Argent capture is keyed to the Argent release that drove it.
|
||||
...(config.capture.controller === "argent" ? { controllerVersion: ARGENT_VERSION } : {}),
|
||||
});
|
||||
}
|
||||
|
||||
|
||||
@@ -8,8 +8,10 @@ import type { CaptureBundle } from "../contracts/capture.js";
|
||||
import type { SourceCapturePlan } from "../source/capture-plan.js";
|
||||
import type { CommandRunner } from "../capture/run.js";
|
||||
import { runBaselineCi } from "./pipeline.js";
|
||||
import { DEFAULT_EXPLORE_CONFIG_PATH, configPlatforms, readExploreConfig, readExploreInstructions, resolvePlatformConfig, type ExploreConfig, type ExplorePlatform } from "../config/explore-config.js";
|
||||
import { DEFAULT_EXPLORE_CONFIG_PATH, configPlatforms, readExploreConfig, readExploreInstructions, resolvePlatformConfig, withRunOverrides, type ExploreConfig, type ExplorePlatform } from "../config/explore-config.js";
|
||||
import { explorationSecretNames } from "../config/exploration-inputs.js";
|
||||
import { controllerCached } from "../shared/controller-cache.js";
|
||||
import { ARGENT_VERSION } from "../shared/argent-version.js";
|
||||
import { AGENT_PROVIDERS as PROVIDERS, DRAFT_INSTRUCTIONS_MARKER, EXPO_TOKENS_URL as TOKENS, appConfig, simulatorProfiles } from "../config/setup.js";
|
||||
import { captureCompatibility } from "../capture/observer.js";
|
||||
import { assertCaptureEasProfile, assertSimulatorAvailable, repackProfileFrom, unreproducibleEasVariables } from "../capture/eas-build.js";
|
||||
@@ -46,6 +48,8 @@ export type DoctorOptions = {
|
||||
github?: boolean;
|
||||
/** One small model request with the local provider key. */
|
||||
checkModel?: boolean;
|
||||
/** `--controller`: the device controller to check, over the config's `capture.controller`. */
|
||||
controller?: string | undefined;
|
||||
run?: DoctorRun;
|
||||
environment?: NodeJS.ProcessEnv;
|
||||
nodeVersion?: string;
|
||||
@@ -383,7 +387,7 @@ export async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
|
||||
return { ok: false, mode: null, checks, ...(routes ? { routes } : {}) };
|
||||
}
|
||||
let config: ExploreConfig;
|
||||
try { config = await readExploreConfig(project); }
|
||||
try { config = withRunOverrides(await readExploreConfig(project), { controller: options.controller }); }
|
||||
catch (error) {
|
||||
checks.push(fromError(4, "config", error, { code: "CONFIG_INVALID", nextAction: `Correct ${DEFAULT_EXPLORE_CONFIG_PATH} and rerun doctor.` }));
|
||||
return { ok: false, mode: null, checks };
|
||||
@@ -392,6 +396,7 @@ 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 (config.capture.controller === "argent") checks.push(argentCheck(environment));
|
||||
if (config.capture.launch !== "off") {
|
||||
const ffmpeg = run("ffmpeg", ["-version"], project);
|
||||
checks.push(ffmpeg.status === 0
|
||||
@@ -547,7 +552,16 @@ 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.
|
||||
*/
|
||||
export async function runCaptureCheck(options: { project: string; output: string; platform?: ExplorePlatform; environment?: NodeJS.ProcessEnv; runner?: CommandRunner; progress?: Progress }): Promise<CaptureCheckResult> {
|
||||
/** 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 {
|
||||
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." };
|
||||
}
|
||||
|
||||
export async function runCaptureCheck(options: { project: string; output: string; platform?: ExplorePlatform; controller?: string | undefined; environment?: NodeJS.ProcessEnv; runner?: CommandRunner; progress?: Progress }): Promise<CaptureCheckResult> {
|
||||
const project = await realpath(options.project);
|
||||
const git = (...args: string[]) => spawnSync("git", ["-C", project, ...args], { encoding: "utf8", timeout: 10_000 });
|
||||
const head = git("rev-parse", "HEAD");
|
||||
@@ -559,7 +573,7 @@ export async function runCaptureCheck(options: { project: string; output: string
|
||||
nextAction: "Commit your changes, including .expo-explore (a local commit is enough; nothing is pushed), then rerun. "
|
||||
+ "To keep unrelated files, run it from a clean checkout instead: git worktree add --detach ../app-capture HEAD, install the app's dependencies there, and run doctor --capture in it." });
|
||||
const commit = head.stdout.trim();
|
||||
const config = resolvePlatformConfig(await readExploreConfig(project), options.platform);
|
||||
const config = withRunOverrides(resolvePlatformConfig(await readExploreConfig(project), options.platform), { controller: options.controller });
|
||||
// Capture keeps its working directories in the system temporary directory, outside the app.
|
||||
await mkdir(options.output, { recursive: true });
|
||||
const output = await realpath(options.output);
|
||||
|
||||
@@ -8,7 +8,7 @@ import { runCiReview } from "./pipeline.js";
|
||||
import { resolveCommit } from "./workflow-steps.js";
|
||||
import { ciLayout, installCommand, type PackageManager } from "./workflow-install.js";
|
||||
import { configPlatforms, readExploreConfig, resolvePlatformConfig, withRunOverrides, DEFAULT_EXPLORE_CONFIG_PATH, type ExploreConfig, type ExplorePlatform } from "../config/explore-config.js";
|
||||
import { AGENT_PROVIDERS } from "../config/setup.js";
|
||||
import { AGENT_PROVIDERS, defaultExploreConfig } from "../config/setup.js";
|
||||
import type { PrepareCiExplorationOptions } from "../capture/agent/exploration.js";
|
||||
import { createCiAgentSession } from "../capture/agent/session.js";
|
||||
import { createLocalCiAgentSession } from "../capture/agent/session-local.js";
|
||||
@@ -32,13 +32,15 @@ export type LocalReviewOptions = {
|
||||
project: string;
|
||||
base?: string | undefined;
|
||||
head?: string | undefined;
|
||||
/** Review uncommitted changes to tracked files as the head (the working tree, not a commit). */
|
||||
/** Review HEAD alone, leaving out the working tree's changes. */
|
||||
committed?: boolean | undefined;
|
||||
/** Review the working tree even when eas.json sets cli.requireCommit. Without --head this is the default. */
|
||||
uncommitted?: boolean | undefined;
|
||||
/** With `uncommitted`: also include untracked files that are not ignored. */
|
||||
untracked?: boolean | undefined;
|
||||
platform?: ExplorePlatform | undefined;
|
||||
scope?: string | undefined;
|
||||
expiresIn?: string | undefined;
|
||||
/** `--controller`: the device controller for both sides, over the config's `capture.controller`. */
|
||||
controller?: string | undefined;
|
||||
/** Reuse and keep captures in the local capture cache (default true). */
|
||||
cache?: boolean | undefined;
|
||||
configPath?: string | undefined;
|
||||
@@ -89,7 +91,7 @@ export async function snapshotWorkingTree(root: string, options: { untracked?: b
|
||||
for (const file of untracked) bytes += (await stat(join(root, file)).catch(() => ({ size: 0 }))).size;
|
||||
if (bytes > UNTRACKED_LIMIT_BYTES) throw new CiError({ code: "LOCAL_REVIEW_UNTRACKED_TOO_LARGE", stage: "preflight",
|
||||
message: `The untracked files add up to ${Math.round(bytes / 1024 / 1024)} MB; they would be uploaded with the EAS build.`,
|
||||
nextAction: "Ignore or commit the large files, or leave out --include-untracked." });
|
||||
nextAction: "Ignore or commit the large files, or pass --committed to review HEAD alone." });
|
||||
must(git(root, ["add", options.untracked ? "-A" : "-u", "--", "."], environment), "Cannot stage the working tree", "Check the repository's state.");
|
||||
const tree = must(git(root, ["write-tree"], environment), "Cannot write the working tree", "Check the repository's state.");
|
||||
await rm(index, { force: true });
|
||||
@@ -271,6 +273,49 @@ export async function stopRecordedSessions(outputs: string[], environment: NodeJ
|
||||
return stopped;
|
||||
}
|
||||
|
||||
/**
|
||||
* What the head of a review without --head is: the working tree, as `eas build` uploads it (tracked and untracked
|
||||
* files, not ignored ones), unless the app's eas.json sets cli.requireCommit, which makes eas build refuse uncommitted
|
||||
* changes, or --committed asks for HEAD alone. --head names a commit, so the working tree is never part of it.
|
||||
*/
|
||||
export async function reviewHeadSource(options: Pick<LocalReviewOptions, "head" | "committed" | "uncommitted">, project: string):
|
||||
Promise<"working-tree" | "commit" | "require-commit"> {
|
||||
const namedHead = options.head !== undefined && options.head !== "HEAD";
|
||||
if (options.uncommitted && (namedHead || options.committed)) throw new CiError({ code: "LOCAL_REVIEW_UNCOMMITTED_HEAD", stage: "preflight",
|
||||
message: "--uncommitted reviews the working tree, which is on top of HEAD.", nextAction: `Leave out ${namedHead ? "--head" : "--committed"}, or leave out --uncommitted.` });
|
||||
if (namedHead || options.committed) return "commit";
|
||||
if (options.uncommitted) return "working-tree";
|
||||
let eas: unknown;
|
||||
try { eas = JSON.parse(await readFile(join(project, "eas.json"), "utf8")); } catch { return "working-tree"; }
|
||||
const cli = eas !== null && typeof eas === "object" ? (eas as { cli?: unknown }).cli : undefined;
|
||||
return cli !== null && typeof cli === "object" && (cli as { requireCommit?: unknown }).requireCommit === true ? "require-commit" : "working-tree";
|
||||
}
|
||||
|
||||
/**
|
||||
* The config a local review runs with: the head commit's; else the one in your checkout, when setup has written it but
|
||||
* it is not committed yet; else the defaults setup would write, so an app can be reviewed before it is set up. A
|
||||
* config path passed with --config must be in the head commit.
|
||||
*/
|
||||
export async function localReviewConfig(options: { project: string; head: string; configPath: string; explicit: boolean;
|
||||
platform?: ExplorePlatform | undefined; progress?: Progress }): Promise<ExploreConfig> {
|
||||
const progress = options.progress ?? silentProgress;
|
||||
if (options.explicit || await exists(join(options.head, options.configPath))) return readExploreConfig(options.head, options.configPath);
|
||||
if (await exists(join(options.project, options.configPath))) {
|
||||
progress(`config: ${options.configPath} from your checkout (it is not in the head commit)`);
|
||||
return readExploreConfig(options.project, options.configPath);
|
||||
}
|
||||
let config: ExploreConfig;
|
||||
try { config = await defaultExploreConfig(options.project, options.platform); }
|
||||
catch (error) {
|
||||
throw new CiError({ code: "LOCAL_REVIEW_CONFIG_DEFAULTS", stage: "preflight",
|
||||
message: `There is no ${options.configPath}, so this review uses setup's defaults, which need this: ${(error as Error).message}`,
|
||||
nextAction: "Fix that and rerun (with several simulator profiles, the one named explore is used), or run expo-explore setup to write a config." });
|
||||
}
|
||||
progress(`config: none yet, so setup's defaults (${config.app.bundleId}, EAS profile ${config.app.easProfile}, ${config.device.name}); `
|
||||
+ "expo-explore setup writes one you can change");
|
||||
return config;
|
||||
}
|
||||
|
||||
export async function runLocalReview(options: LocalReviewOptions): Promise<LocalReviewResult> {
|
||||
const environment = { ...(options.environment ?? process.env) };
|
||||
const progress = options.progress ?? silentProgress;
|
||||
@@ -306,14 +351,14 @@ export async function runLocalReview(options: LocalReviewOptions): Promise<Local
|
||||
// The commits.
|
||||
const headRef = options.head ?? "HEAD";
|
||||
let head: LocalReviewResult["head"];
|
||||
if (options.uncommitted) {
|
||||
if (options.head && options.head !== "HEAD") throw new CiError({ code: "LOCAL_REVIEW_UNCOMMITTED_HEAD", stage: "preflight",
|
||||
message: "--uncommitted reviews the working tree, which is on top of HEAD.", nextAction: "Leave out --head, or leave out --uncommitted." });
|
||||
const snapshot = await snapshotWorkingTree(root, { untracked: options.untracked, work });
|
||||
const source = await reviewHeadSource(options, project);
|
||||
if (source === "require-commit") progress("head: HEAD; eas.json sets cli.requireCommit, so uncommitted changes are left out as eas build leaves them out (--uncommitted includes them)");
|
||||
if (source === "working-tree") {
|
||||
const snapshot = await snapshotWorkingTree(root, { untracked: true, work });
|
||||
head = snapshot ? { ref: "uncommitted changes", sha: snapshot.sha, uncommitted: snapshot.changed } : { ref: "HEAD", sha: resolveCommit(root, "HEAD", "head") };
|
||||
if (snapshot) progress(`head: your uncommitted changes to ${snapshot.changed.length} file${snapshot.changed.length === 1 ? "" : "s"}`
|
||||
+ (snapshot.untracked.length ? ` (untracked, uploaded with the build and kept in .git/objects until git gc: ${snapshot.untracked.join(", ")})` : ""));
|
||||
else progress("head: no uncommitted changes, reviewing HEAD");
|
||||
if (snapshot) progress(`head: HEAD with your uncommitted changes to ${snapshot.changed.length} file${snapshot.changed.length === 1 ? "" : "s"}, as eas build would upload them`
|
||||
+ (snapshot.untracked.length ? ` (untracked, kept in .git/objects until git gc: ${snapshot.untracked.join(", ")})` : "") + "; --committed leaves them out");
|
||||
else progress("head: HEAD (no uncommitted changes)");
|
||||
} else {
|
||||
const sha = resolveCommit(root, headRef, "head");
|
||||
head = { ref: reportRef(root, headRef, sha), sha };
|
||||
@@ -321,7 +366,7 @@ export async function runLocalReview(options: LocalReviewOptions): Promise<Local
|
||||
const baseSha = options.base ? resolveCommit(root, options.base, "base") : undefined;
|
||||
const base = options.base && baseSha ? { ref: reportRef(root, options.base, baseSha), sha: baseSha } : defaultBase(root, head.sha);
|
||||
if (base.sha === head.sha) throw new CiError({ code: "COMPARE_SAME_COMMIT", stage: "preflight", message: `${base.ref} and ${head.ref} are the same commit (${head.sha.slice(0, 8)}).`,
|
||||
nextAction: "Pass --base with an earlier commit, or --uncommitted to review your uncommitted changes." });
|
||||
nextAction: "Change something to review it, or pass --base with an earlier commit." });
|
||||
progress(`comparing ${head.ref} (${head.sha.slice(0, 8)}) with ${base.ref} (${base.sha.slice(0, 8)})`);
|
||||
|
||||
// The checkouts, and the config at head.
|
||||
@@ -333,7 +378,8 @@ export async function runLocalReview(options: LocalReviewOptions): Promise<Local
|
||||
}
|
||||
const projects = { base: join(checkouts.base, appDirectory), head: join(checkouts.head, appDirectory) };
|
||||
const configPath = options.configPath ?? DEFAULT_EXPLORE_CONFIG_PATH;
|
||||
const rawConfig = await readExploreConfig(projects.head, configPath);
|
||||
const rawConfig = await localReviewConfig({ project, head: projects.head, configPath, explicit: options.configPath !== undefined,
|
||||
platform: options.platform, progress });
|
||||
const platforms = options.platform ? [options.platform] : configPlatforms(rawConfig);
|
||||
const repository = repositoryName(root, rawConfig);
|
||||
|
||||
@@ -354,7 +400,7 @@ export async function runLocalReview(options: LocalReviewOptions): Promise<Local
|
||||
});
|
||||
const reports: LocalReviewReport[] = [];
|
||||
for (const platform of platforms) {
|
||||
const config = withRunOverrides(resolvePlatformConfig(rawConfig, platform), { scope: options.scope, expiresIn: options.expiresIn });
|
||||
const config = withRunOverrides(resolvePlatformConfig(rawConfig, platform), { scope: options.scope, expiresIn: options.expiresIn, controller: options.controller });
|
||||
const output = join(work, platform); await mkdir(output);
|
||||
outputs.push(output);
|
||||
const platformEnvironment = { ...environment };
|
||||
|
||||
@@ -26,6 +26,7 @@ import type { SourceCapturePlan } from "../source/capture-plan.js";
|
||||
import { createSourceChangeSummaries } from "../source/change-summary.js";
|
||||
import { assertNoCaptureHealthIssues, partitionCaptureHealthIssues, renderCaptureIssueAnnotation, renderComparisonDiagnosticAnnotation, renderNotesUnavailableAnnotation, renderReviewGapAnnotation, sortedCaptureHealthIssues } from "../capture/health.js";
|
||||
import { EXPLORE_PACKAGE, packageBin } from "../shared/package-paths.js";
|
||||
import { agentDeviceLauncher, ensureController } from "../shared/controller-cache.js";
|
||||
import { silentProgress, type Progress } from "../shared/progress.js";
|
||||
|
||||
|
||||
@@ -63,16 +64,22 @@ type CaptureClock = { now?: (() => number) | undefined; sleep?: ((milliseconds:
|
||||
|
||||
function captureOptions(config: ExploreConfig, environment: NodeJS.ProcessEnv, runner?: CommandRunner, clock: CaptureClock = {}) {
|
||||
return { ...(runner && clock.now ? { now: clock.now } : {}), ...(runner && clock.sleep ? { sleep: clock.sleep } : {}), platform: config.app.platform, bundleId: config.app.bundleId,
|
||||
...(config.app.scheme ? { scheme: config.app.scheme } : {}), device: config.device.name,
|
||||
...(config.app.scheme ? { scheme: config.app.scheme } : {}), device: config.device.name, ...(config.device.pose ? { devicePose: config.device.pose } : {}),
|
||||
easProfile: config.app.easProfile, expoToken: environment.EXPO_TOKEN ?? "",
|
||||
maxScreens: 5000, maxActions: config.capture.maxActions, maxDurationMinutes: config.capture.maxMinutes,
|
||||
setup: config.setup ?? [], forceFreshBuild: false, confirmExternalRun: true, confirmTrustedSource: true, repack: config.capture.repack, appearance: config.capture.appearance, launch: config.capture.launch, reset: config.capture.reset, unattributed: config.capture.unattributed, ...(config.capture.readinessSeconds !== undefined ? { readinessSeconds: config.capture.readinessSeconds } : {}),
|
||||
environment, ...(runner ? { runner } : {}), easCommand: packageBin("eas-cli", "eas"), agentDeviceCommand: packageBin("agent-device", "agent-device"), repackCommand: packageBin("@expo/repack-app", "repack-app") };
|
||||
setup: config.setup ?? [], forceFreshBuild: false, confirmExternalRun: true, confirmTrustedSource: true, repack: config.capture.repack, 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 } : {}),
|
||||
environment, ...(runner ? { runner } : {}), easCommand: packageBin("eas-cli", "eas"), agentDeviceCommand: agentDeviceLauncher(environment), repackCommand: packageBin("@expo/repack-app", "repack-app") };
|
||||
}
|
||||
/**
|
||||
* Head and base run in parallel worker threads when nothing ties them together: an agent session is
|
||||
* shared, an injected runner belongs to this thread, and a plausible baseline needs head's runtime profile.
|
||||
*/
|
||||
/** The controllers a capture of this config runs: agent-device always (it also compares screenshots), Argent when chosen. */
|
||||
async function prefetchControllers(config: ExploreConfig, environment: NodeJS.ProcessEnv, progress: Progress): Promise<void> {
|
||||
await ensureController("agent-device", { environment, progress });
|
||||
if (config.capture.controller === "argent") await ensureController("argent", { environment, progress });
|
||||
}
|
||||
|
||||
export function captureSidesConcurrently(input: { plan: SourceCapturePlan; agent: boolean; injectedRunner: boolean; baselineMayExist: boolean }): boolean {
|
||||
return !input.agent && !input.injectedRunner && !input.baselineMayExist
|
||||
&& input.plan.headCaptureSurfaceIds.length > 0 && input.plan.baseCaptureSurfaceIds.length > 0;
|
||||
@@ -246,6 +253,9 @@ export async function runCiReview(options: {
|
||||
}) {
|
||||
const { projects, output, config, environment, state, assertCurrentHead, postComment } = options;
|
||||
const progress = options.progress ?? silentProgress;
|
||||
// The controllers are fetched before any EAS work, so a blocked download fails before a session is paid for. agent-device
|
||||
// also compares the screenshots. An injected runner (tests) runs no real controller.
|
||||
if (!options.runner) await prefetchControllers(config, environment, progress);
|
||||
const pr = options.presentation;
|
||||
const now = options.now ?? Date.now;
|
||||
const secretValues = Object.entries(environment).filter(([key]) => /(?:TOKEN|SECRET|PASSWORD|API_KEY)/i.test(key)).flatMap(([, value]) => value ? [value] : []);
|
||||
@@ -344,7 +354,7 @@ export async function runCiReview(options: {
|
||||
stage = "compare";
|
||||
progress("comparing base and head captures");
|
||||
const sides = { base: await evidenceSide(join(output, "base-export")), head: await evidenceSide(join(output, "head-export")) };
|
||||
const evidence = await assessPublicEvidence({ platform: config.app.platform, plan, ...sides, ...(options.measure ? { measure: options.measure } : {}), profile: `${config.app.easProfile}:${config.app.bundleId}`, agentDeviceCommand: packageBin("agent-device", "agent-device") });
|
||||
const evidence = await assessPublicEvidence({ platform: config.app.platform, plan, ...sides, ...(options.measure ? { measure: options.measure } : {}), profile: `${config.app.easProfile}:${config.app.bundleId}`, agentDeviceCommand: agentDeviceLauncher(options.environment) });
|
||||
const result = await prepareCaptureReview({ plan, pullRequest: pr, baseDirectory: sides.base.directory, headDirectory: sides.head.directory,
|
||||
runId: options.runId, runAttempt: options.runAttempt, assertCurrentHead, assessments: evidence.surfaces,
|
||||
...(options.platforms ? { platforms: options.platforms } : {}),
|
||||
@@ -444,6 +454,7 @@ export async function runBaselineCi(options: { platform?: ExplorePlatform; proje
|
||||
subscription?: boolean }) {
|
||||
const environment = options.environment ?? process.env;
|
||||
assertCheckout(options.project, options.sha);
|
||||
if (!options.runner) await prefetchControllers(options.config, environment, options.progress ?? silentProgress);
|
||||
const output = resolve(options.output);
|
||||
const relativeOutput = relative(await realpath(options.project), output);
|
||||
if (!relativeOutput.startsWith("..") || isAbsolute(relativeOutput)) throw new Error("Baseline output must be outside the source checkout");
|
||||
|
||||
@@ -26,9 +26,12 @@ const aliases: Record<string, string> = {
|
||||
"config platforms": "config:platforms",
|
||||
};
|
||||
|
||||
/** One-word names for commands people type: `capture` is the local review, `capture:review` without its CI flags. */
|
||||
const shortNames: Record<string, string> = { capture: "capture:review" };
|
||||
|
||||
const first = argv[0] ?? "help";
|
||||
const pair = `${first} ${argv[1] ?? ""}`.trim();
|
||||
export const command = aliases[pair] ?? first;
|
||||
export const command = aliases[pair] ?? shortNames[first] ?? first;
|
||||
export const resultContract = ["source:verify", "capture:review", "capture:baseline", "ci:report", "ci:publish", "ci:failure", "ci:deploy", "ci:pr", "ci:find-baseline", "ci:compare-refs", "ci:after-capture", "config:platforms", "explore:binary", "explore:session", "report:upload", "reports"].includes(command)
|
||||
? "explore.result" : QUERY_CONTRACT;
|
||||
const commandArgCount = aliases[pair] ? 2 : 1;
|
||||
@@ -47,8 +50,8 @@ const flagKinds: Record<string, Record<string, "value" | "boolean">> = {
|
||||
setup: { project: "value", platform: "value", device: "value", scope: "value", profile: "value", "bundle-id": "value", scheme: "value", navigation: "value",
|
||||
mode: "value", provider: "value", model: "value", param: "value", "app-state": "value", workflows: "boolean", "no-workflows": "boolean",
|
||||
"non-interactive": "boolean", check: "boolean", force: "boolean", help: "boolean" },
|
||||
doctor: { project: "value", offline: "boolean", "no-github": "boolean", "check-model": "boolean", capture: "boolean", output: "value", platform: "value", yes: "boolean", help: "boolean" },
|
||||
"capture:baseline": { project:"value", sha:"value", output:"value", config:"value", platform:"value" },
|
||||
doctor: { project: "value", offline: "boolean", "no-github": "boolean", "check-model": "boolean", capture: "boolean", output: "value", platform: "value", controller: "value", yes: "boolean", help: "boolean" },
|
||||
"capture:baseline": { project:"value", sha:"value", output:"value", config:"value", platform:"value", controller:"value" },
|
||||
"source:verify": { "base-project":"value", "head-project":"value", "base-sha":"value", "head-sha":"value", output:"value", config:"value", scope:"value", platform:"value" },
|
||||
"config:platforms": { project:"value", config:"value" },
|
||||
"screen:list": { limit: "value", cursor: "value", unexplored: "boolean" },
|
||||
@@ -80,15 +83,15 @@ 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", platform:"value", scope:"value", "expires-in":"value",
|
||||
base:"value", head:"value", project:"value", uncommitted:"boolean", "include-untracked":"boolean", upload:"boolean", "no-open":"boolean", "no-cache":"boolean", port:"value" },
|
||||
"capture:review": { "base-project":"value", "head-project":"value", "pull-request":"value", compare:"value", output:"value", config:"value", platform:"value", controller:"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" },
|
||||
|
||||
|
||||
|
||||
"explore:binary": { archive:"value", output:"value", platform:"value", device:"value", "bundle-id":"value", "launch-url":"value", hints:"value", "allow-destructive":"value",
|
||||
"explore:binary": { archive:"value", output:"value", platform:"value", controller:"value", device:"value", "bundle-id":"value", "launch-url":"value", hints:"value", "allow-destructive":"value",
|
||||
"max-duration-minutes":"value", "max-screens":"value", "max-actions":"value", provider:"value", model:"value", owner:"value", project:"value",
|
||||
upload:"boolean", "no-upload":"boolean", "expires-in":"value", alias:"value" },
|
||||
"explore:session": { session:"value", "env-file":"value", "bundle-id":"value", "app-name":"value", "app-version":"value", output:"value", platform:"value", device:"value", "launch-url":"value", hints:"value",
|
||||
"explore:session": { session:"value", "env-file":"value", "bundle-id":"value", "app-name":"value", "app-version":"value", output:"value", platform:"value", controller:"value", device:"value", "launch-url":"value", hints:"value",
|
||||
"allow-destructive":"value", "max-duration-minutes":"value", "max-screens":"value", "max-actions":"value", provider:"value", model:"value", owner:"value", project:"value",
|
||||
upload:"boolean", "expires-in":"value", alias:"value", "no-open":"boolean", port:"value" },
|
||||
"ci:report": { input:"value", output:"value", platform:"value" },
|
||||
|
||||
@@ -38,13 +38,14 @@ export async function exploreBinary(): Promise<void> {
|
||||
const expiresAfterDays = expiresInDays(flag("expires-in") ?? "7d");
|
||||
const platform = flag("platform") === undefined ? undefined : oneOf("platform", ["ios", "android"] as const);
|
||||
const provider = flag("provider") === undefined ? undefined : oneOf("provider", ["anthropic", "openai"] as const);
|
||||
const controller = flag("controller") === undefined ? undefined : oneOf("controller", ["agent-device", "argent"] as const);
|
||||
const started = Date.now();
|
||||
const say = (message: string) => { process.stderr.write(`[explore ${Math.round((Date.now() - started) / 1000)}s] ${message}\n`); };
|
||||
const allowDestructive = flags("allow-destructive").flatMap(value => value.split(",")).map(value => value.trim()).filter(Boolean);
|
||||
if (!has("no-upload")) await assertHostingExport();
|
||||
const result = await runBinaryExploration({
|
||||
archive: resolve(process.cwd(), archive), output: outputDirectory, progress: say,
|
||||
...(platform ? { platform } : {}), ...(provider ? { provider } : {}),
|
||||
...(platform ? { platform } : {}), ...(provider ? { provider } : {}), ...(controller ? { controller } : {}),
|
||||
...(flag("device") ? { device: flag("device")! } : {}), ...(flag("bundle-id") ? { bundleId: flag("bundle-id")! } : {}),
|
||||
...(flag("launch-url") ? { launchUrl: flag("launch-url")! } : {}), ...(flag("hints") ? { hints: flag("hints")! } : {}),
|
||||
...(allowDestructive.length ? { allowDestructive } : {}), ...(flag("model") ? { model: flag("model")! } : {}),
|
||||
@@ -93,6 +94,7 @@ export async function exploreSession(): Promise<void> {
|
||||
const expiresAfterDays = expiresInDays(flag("expires-in") ?? "7d");
|
||||
const platform = flag("platform") === undefined ? undefined : oneOf("platform", ["ios", "android"] as const);
|
||||
const provider = flag("provider") === undefined ? undefined : oneOf("provider", ["anthropic", "openai"] as const);
|
||||
const controller = flag("controller") === undefined ? undefined : oneOf("controller", ["agent-device", "argent"] as const);
|
||||
const port = flag("port") === undefined ? undefined : nonNegativeInteger("port");
|
||||
const started = Date.now();
|
||||
const say = (message: string) => { process.stderr.write(`[explore ${Math.round((Date.now() - started) / 1000)}s] ${message}\n`); };
|
||||
@@ -103,7 +105,7 @@ export async function exploreSession(): Promise<void> {
|
||||
output: outputDirectory, progress: say,
|
||||
...(bundleId ? { bundleId } : {}), ...(session ? { session } : {}), ...(envFile ? { envFile } : {}),
|
||||
...(flag("app-name") ? { appName: flag("app-name")! } : {}), ...(flag("app-version") ? { version: flag("app-version")! } : {}),
|
||||
...(platform ? { platform } : {}), ...(provider ? { provider } : {}),
|
||||
...(platform ? { platform } : {}), ...(provider ? { provider } : {}), ...(controller ? { controller } : {}),
|
||||
...(flag("device") ? { device: flag("device")! } : {}),
|
||||
...(flag("launch-url") ? { launchUrl: flag("launch-url")! } : {}), ...(flag("hints") ? { hints: flag("hints")! } : {}),
|
||||
...(allowDestructive.length ? { allowDestructive } : {}), ...(flag("model") ? { model: flag("model")! } : {}),
|
||||
|
||||
@@ -26,7 +26,7 @@ export async function doctor(): Promise<void> {
|
||||
if (has("help")) return help();
|
||||
const project = flag("project") ?? process.cwd();
|
||||
const report = await runDoctor({ project, online: !has("offline"), github: !has("no-github") && !has("offline"),
|
||||
checkModel: has("check-model") });
|
||||
checkModel: has("check-model"), controller: flag("controller") });
|
||||
if (!has("capture")) {
|
||||
if (has("json")) output({ ...report });
|
||||
else console.log(formatDoctorReport(report));
|
||||
@@ -53,7 +53,7 @@ Fix the problems in steps 1–5 before a capture check.`);
|
||||
let result: Awaited<ReturnType<typeof runCaptureCheck>>;
|
||||
try {
|
||||
const platform = platformFlag();
|
||||
result = await runCaptureCheck({ project, ...(platform ? { platform } : {}), output: resolve(flag("output") ?? await mkdtemp(join(tmpdir(), "expo-explore-capture-"))), progress: stderrProgress() });
|
||||
result = await runCaptureCheck({ project, ...(platform ? { platform } : {}), controller: flag("controller"), output: resolve(flag("output") ?? await mkdtemp(join(tmpdir(), "expo-explore-capture-"))), progress: stderrProgress() });
|
||||
} catch (error) {
|
||||
// A refusal before any EAS work: show it with its next action next to the static report.
|
||||
if (!(error instanceof CiError)) throw error;
|
||||
@@ -203,7 +203,7 @@ export async function captureReview(): Promise<void> {
|
||||
const configPath = flag("config") ?? DEFAULT_EXPLORE_CONFIG_PATH;
|
||||
const platform = platformFlag();
|
||||
const rawConfig = await readExploreConfig(headProject, configPath);
|
||||
const config = withRunOverrides(resolvePlatformConfig(rawConfig, platform), { scope: flag("scope"), expiresIn: flag("expires-in") });
|
||||
const config = withRunOverrides(resolvePlatformConfig(rawConfig, platform), { scope: flag("scope"), expiresIn: flag("expires-in"), controller: flag("controller") });
|
||||
if (has("pull-request") === has("compare")) argumentError("Pass --pull-request FILE for a pull request, or --compare FILE for any two commits.", has("compare") ? "compare" : "pull-request");
|
||||
const common = { ...(platform ? { platform } : {}), platforms: listPlatforms(rawConfig), baseProject: required("base-project"), headProject,
|
||||
output: required("output"), config, configPath, progress: stderrProgress() };
|
||||
@@ -217,16 +217,17 @@ export async function captureReview(): Promise<void> {
|
||||
export async function captureBaseline(): Promise<void> {
|
||||
const project = required("project");
|
||||
const platform = platformFlag();
|
||||
const config = resolvePlatformConfig(await readExploreConfig(project, flag("config") ?? DEFAULT_EXPLORE_CONFIG_PATH), platform);
|
||||
const config = withRunOverrides(resolvePlatformConfig(await readExploreConfig(project, flag("config") ?? DEFAULT_EXPLORE_CONFIG_PATH), platform), { controller: flag("controller") });
|
||||
output({ ok: true, ...await runBaselineCi({ ...(platform ? { platform } : {}), project, sha: required("sha"), output: required("output"), config, progress: stderrProgress() }) });
|
||||
}
|
||||
|
||||
/** `capture:review [--base REF] [--head REF | --uncommitted]`: a local review, opened in the Viewer or hosted with --upload. */
|
||||
/** `capture` (or `capture:review`) `[--base REF] [--head REF | --committed]`: a local review, opened in the Viewer or hosted with --upload. */
|
||||
async function localReview(): Promise<void> {
|
||||
const platform = platformFlag();
|
||||
const result = await runLocalReview({ project: flag("project") ?? process.cwd(), base: flag("base"), head: flag("head"),
|
||||
uncommitted: has("uncommitted"), untracked: has("include-untracked"), ...(platform ? { platform } : {}),
|
||||
scope: flag("scope"), expiresIn: flag("expires-in"), cache: !has("no-cache"), configPath: flag("config"), progress: stderrProgress() });
|
||||
// --include-untracked is accepted from before untracked files were included by default.
|
||||
committed: has("committed"), uncommitted: has("uncommitted"), ...(platform ? { platform } : {}),
|
||||
scope: flag("scope"), expiresIn: flag("expires-in"), controller: flag("controller"), cache: !has("no-cache"), configPath: flag("config"), progress: stderrProgress() });
|
||||
if (has("output")) {
|
||||
for (const report of result.reports) {
|
||||
const target = resolve(required("output"), report.platform);
|
||||
|
||||
@@ -15,13 +15,18 @@ const GET_STARTED = `Get started (run these in the Expo app's directory):
|
||||
doctor [--project DIRECTORY] [--offline] [--no-github] [--check-model] [--json]
|
||||
(checks every setup step and prints the next action for each problem; exits 1 until ready)
|
||||
(--offline skips EAS and GitHub; --check-model sends one small request with the local provider key)
|
||||
doctor --capture [--project DIRECTORY] [--output DIRECTORY] [--platform ios|android] [--yes]
|
||||
doctor --capture [--project DIRECTORY] [--output DIRECTORY] [--platform ios|android] [--controller agent-device|argent] [--yes]
|
||||
(captures the committed HEAD like the baseline workflow, with your eas login, and reports each route)
|
||||
capture:review [--base REF] [--head REF | --uncommitted [--include-untracked]] [--platform ios|android] [--scope all|changes]
|
||||
[--upload [--expires-in 7d|30d|never]] [--no-open] [--no-cache] [--output DIRECTORY] [--project DIRECTORY]
|
||||
capture [--base REF] [--head REF | --committed] [--platform ios|android] [--scope all|changes]
|
||||
[--controller agent-device|argent] [--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 and your
|
||||
local claude or codex login, and opens the report; the base defaults to where HEAD left the default branch;
|
||||
it runs both commits' code as you, so review only commits you would run)
|
||||
local claude or codex login, and opens the report; the head is HEAD with your uncommitted changes, as eas build
|
||||
uploads them (--committed, or cli.requireCommit in eas.json, leaves them out); the base defaults to where HEAD
|
||||
left the default branch;
|
||||
without .expo-explore/config.yaml it uses the defaults setup would write;
|
||||
it runs both commits' code as you, so review only commits you would run; capture:review is the same command;
|
||||
--controller argent drives the simulator with Argent instead of agent-device, the default (or set
|
||||
capture.controller in config.yaml); Argent cannot switch appearance yet, so it captures one appearance)
|
||||
view [--catalog FILE] [--port N] [--no-open]
|
||||
(opens a report in the Viewer)
|
||||
reports [list | open ID | add REPORT... | upload ID | rm ID | prune] [--all] [--json]
|
||||
@@ -37,6 +42,7 @@ const BINARY = `Prebuilt apps (no source needed; runs on EAS Simulator with your
|
||||
(installs the archive in a fresh EAS Simulator session, lets the model explore it, writes a map
|
||||
and report under --output, hosts the report on EAS Hosting, and prints the link)
|
||||
Flags, all optional: --device NAME --bundle-id ID --launch-url URL --hints "what to focus on"
|
||||
--controller agent-device|argent (the session's device controller; agent-device by default)
|
||||
(a sign-in in --hints is written as {{secret:NAME}}: Explore types the value of the environment variable NAME,
|
||||
and the model and the report only see the reference)
|
||||
--max-duration-minutes N --max-screens N --max-actions N --provider anthropic|openai --model ID
|
||||
@@ -46,11 +52,12 @@ const BINARY = `Prebuilt apps (no source needed; runs on EAS Simulator with your
|
||||
(iOS needs a simulator build; a device .ipa and Android .aab are rejected before any session starts)
|
||||
explore:session [SESSION_ID] [--bundle-id ID] [--output DIRECTORY] [--upload] [--json]
|
||||
(explores an app that is already installed on an EAS Simulator session you started — run it where
|
||||
"eas simulator:start --type agent-device --out-config-type dotenv" wrote .env.eas-simulator, or pass
|
||||
--env-file FILE, or export EAS_SIMULATOR_SESSION_ID, AGENT_DEVICE_DAEMON_BASE_URL and
|
||||
AGENT_DEVICE_DAEMON_AUTH_TOKEN; writes the map and report, then opens them in the local Viewer;
|
||||
"eas simulator:start --type agent-device --out-config-type dotenv" (or --type argent) wrote .env.eas-simulator,
|
||||
or pass --env-file FILE, or export EAS_SIMULATOR_SESSION_ID with AGENT_DEVICE_DAEMON_BASE_URL and
|
||||
AGENT_DEVICE_DAEMON_AUTH_TOKEN, or with ARGENT_TOOLS_URL and ARGENT_AUTH_TOKEN; writes the map and report, then opens them in the local Viewer;
|
||||
--upload hosts the report instead, --no-open skips the Viewer; the session is left running;
|
||||
the app is the one in the foreground, else the only installed one; --bundle-id picks it otherwise)
|
||||
the app is the one in the foreground, else the only installed one; --bundle-id picks it otherwise;
|
||||
the controller follows the session's type, and --controller must match it)
|
||||
Extra flags: --app-name NAME --app-version X.Y --port N, plus the explore:binary budget/model flags
|
||||
Afterwards: view --dir DIRECTORY, screen:list --dir DIRECTORY, gap:list --dir DIRECTORY`;
|
||||
|
||||
@@ -58,9 +65,9 @@ const CI = `CI (the installed workflows run these; they manage remote EAS Simula
|
||||
config:platforms [--project DIRECTORY] [--config FILE]
|
||||
(lists the platforms config.yaml captures; the review workflow's matrix)
|
||||
capture:review --base-project DIRECTORY --head-project DIRECTORY (--pull-request FILE | --compare FILE)
|
||||
--output TEMP_DIRECTORY [--config .expo-explore/config.yaml] [--platform ios|android]
|
||||
--output TEMP_DIRECTORY [--config .expo-explore/config.yaml] [--platform ios|android] [--controller agent-device|argent]
|
||||
(--compare reviews any two commits without a PR: {"origin":"compare","repositoryId","repository","base":{ref,sha},"head":{ref,sha}})
|
||||
capture:baseline --project DIRECTORY --sha COMMIT --output TEMP_DIRECTORY [--config FILE] [--platform ios|android]
|
||||
capture:baseline --project DIRECTORY --sha COMMIT --output TEMP_DIRECTORY [--config FILE] [--platform ios|android] [--controller agent-device|argent]
|
||||
source:verify --base-project DIRECTORY --head-project DIRECTORY
|
||||
--base-sha COMMIT --head-sha COMMIT --output DIRECTORY [--config FILE] [--scope all|changes] [--platform ios|android]
|
||||
compare --baseline DIRECTORY --current DIRECTORY --output FILE
|
||||
|
||||
@@ -176,7 +176,7 @@ async function uploadSavedRun(run: SavedRun): Promise<void> {
|
||||
}
|
||||
|
||||
function listLines(runs: SavedRun[], now = Date.now()): string[] {
|
||||
if (!runs.length) return ["No saved runs yet. expo-explore capture:review reviews your branch on this machine, and its report is kept here."];
|
||||
if (!runs.length) return ["No saved runs yet. expo-explore capture reviews your branch on this machine, and its report is kept here."];
|
||||
const idWidth = Math.max(...runs.map(run => run.id.length));
|
||||
return [...runs.map(run => `${run.id.padEnd(idWidth)} ${kindLabel(run).padEnd(9)}${runTitle(run)} (${run.platforms.join(", ")}, ${friendlyTime(run.createdAt, now)})`),
|
||||
"", "Open one with: expo-explore reports open <id>"];
|
||||
|
||||
@@ -129,7 +129,7 @@ export function renderPicker(state: PickerState, options: { width: number; heigh
|
||||
if (!runs.length) {
|
||||
const empty = state.runs.length
|
||||
? [` ${paint.dim(state.filter ? `Nothing matches "${state.filter}".` : `No saved runs of ${state.repository}. Press tab for every repository.`)}`]
|
||||
: [` ${paint.text("No saved runs yet.")}`, ` ${paint.dim("expo-explore capture:review reviews your branch on this machine, and its report is kept here.")}`];
|
||||
: [` ${paint.text("No saved runs yet.")}`, ` ${paint.dim("expo-explore capture reviews your branch on this machine, and its report is kept here.")}`];
|
||||
return [...header, ...empty, "", ...footer].map(line => fit(line, width));
|
||||
}
|
||||
const selected = runs[Math.min(state.selected, runs.length - 1)]!;
|
||||
|
||||
@@ -2,7 +2,7 @@ import { CiError } from "../shared/ci-errors.js";
|
||||
import type { CaptureSetupAction } from "./explore-config.js";
|
||||
|
||||
const TOKEN = /\{\{secret:([A-Z][A-Z0-9_]{0,127})\}\}/g;
|
||||
const RESERVED = /^(?:GITHUB_|RUNNER_|ACTIONS_|AGENT_DEVICE_|OPENAI_|ANTHROPIC_|EXPO_TOKEN$)/;
|
||||
const RESERVED = /^(?:GITHUB_|RUNNER_|ACTIONS_|AGENT_DEVICE_|ARGENT_|OPENAI_|ANTHROPIC_|EXPO_TOKEN$)/;
|
||||
|
||||
/** References are data, never shell expressions or arbitrary environment access. */
|
||||
export function explorationSecretNames(text: string): string[] {
|
||||
|
||||
@@ -43,6 +43,10 @@ export const DEFAULT_ANDROID_DEVICE = "pixel_7";
|
||||
* One platform's capture target. `platforms.ios` fields default to the flat `app`/`device` fields;
|
||||
* `platforms.android` needs its own package and EAS profile (an `android.buildType: apk` profile).
|
||||
*/
|
||||
/** The poses a foldable device can be captured in (`fold` in agent-device and Argent). */
|
||||
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 };
|
||||
|
||||
/** Source discovery never consumes a user-authored screen inventory. */
|
||||
@@ -50,7 +54,11 @@ export type ExploreConfig = {
|
||||
mode: "deterministic" | "agent";
|
||||
app: { name?: string; platform: ExplorePlatform; bundleId: string; easProfile: string; scheme?: string };
|
||||
navigation: { provider: "auto" | "expo-router" | "react-navigation"; entry?: string };
|
||||
device: { name: string };
|
||||
/**
|
||||
* `pose` folds a foldable (iPhone Duo) before capture: closed lights the outer display, open the inner one.
|
||||
* Absent leaves the device as it starts (closed). It applies to the primary platform's device.
|
||||
*/
|
||||
device: { name: string; pose?: DevicePose };
|
||||
/**
|
||||
* Each platform Explore captures, in CI as one matrix job each. Absent: the single platform the
|
||||
* flat fields describe. Capture code never reads this map; resolvePlatformConfig flattens it.
|
||||
@@ -58,7 +66,9 @@ export type ExploreConfig = {
|
||||
platforms?: Partial<Record<ExplorePlatform, PlatformConfig>>;
|
||||
/** `exclude` names routes, as `requiresRoute` does, that stay in the map but are never captured. */
|
||||
exploration: { scope: "changes" | "all"; exclude?: string[] };
|
||||
capture: { maxMinutes: number; maxActions: number; repack: "eas" | "local"; appearance: AppearanceSetting; launch: LaunchSetting; reset: RouteResetSetting; unattributed: UnattributedSetting; readinessSeconds?: number };
|
||||
capture: { maxMinutes: number; maxActions: number; repack: "eas" | "local"; appearance: AppearanceSetting; launch: LaunchSetting; reset: RouteResetSetting; unattributed: UnattributedSetting; readinessSeconds?: number;
|
||||
/** The device controller; absent means agent-device, so configs that never chose one keep their cache recipes. */
|
||||
controller?: "argent" };
|
||||
parameters?: Record<string, Record<string, string>>;
|
||||
setup?: ExploreSetupAction[];
|
||||
agent?: { provider: "openai" | "anthropic"; model: string; instructions?: string };
|
||||
@@ -237,13 +247,15 @@ export function validateExploreConfig(value: unknown): ExploreConfig {
|
||||
const app = record(root.app, "app");
|
||||
exactKeys(app, ["name", "platform", "bundleId", "easProfile", "scheme"], "app");
|
||||
const device = record(root.device, "device");
|
||||
exactKeys(device, ["name"], "device");
|
||||
exactKeys(device, ["name", "pose"], "device");
|
||||
const pose = device.pose === undefined ? undefined : literal(device.pose, DEVICE_POSES, "device.pose", "closed");
|
||||
const navigation = optionalRecord(root.navigation, "navigation");
|
||||
exactKeys(navigation, ["provider", "entry"], "navigation");
|
||||
const exploration = optionalRecord(root.exploration, "exploration");
|
||||
exactKeys(exploration, ["scope", "exclude"], "exploration");
|
||||
const capture = optionalRecord(root.capture, "capture");
|
||||
exactKeys(capture, ["maxMinutes", "maxActions", "repack", "appearance", "launch", "reset", "unattributed", "readinessSeconds"], "capture");
|
||||
exactKeys(capture, ["maxMinutes", "maxActions", "repack", "appearance", "launch", "reset", "unattributed", "readinessSeconds", "controller"], "capture");
|
||||
const controller = literal(capture.controller, ["agent-device", "argent"] as const, "capture.controller", "agent-device");
|
||||
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");
|
||||
@@ -276,7 +288,7 @@ export function validateExploreConfig(value: unknown): ExploreConfig {
|
||||
provider: literal(navigation.provider, ["auto", "expo-router", "react-navigation"] as const, "navigation.provider", "auto"),
|
||||
...(navigation.entry === undefined ? {} : { entry: repoPath(navigation.entry, "navigation.entry") }),
|
||||
},
|
||||
device: { name: text(device.name, "device.name", 128) },
|
||||
device: { name: text(device.name, "device.name", 128), ...(pose === undefined ? {} : { pose }) },
|
||||
...(platforms === undefined ? {} : { platforms }),
|
||||
exploration: {
|
||||
scope: literal(exploration.scope, ["changes", "all"] as const, "exploration.scope", "changes"),
|
||||
@@ -291,6 +303,7 @@ export function validateExploreConfig(value: unknown): ExploreConfig {
|
||||
reset: parseRouteResetSetting(capture.reset, "capture.reset"),
|
||||
unattributed: parseUnattributedSetting(capture.unattributed, "capture.unattributed"),
|
||||
...(capture.readinessSeconds !== undefined ? { readinessSeconds: positiveInteger(capture.readinessSeconds, "capture.readinessSeconds") } : {}),
|
||||
...(controller === "argent" ? { controller } : {}),
|
||||
},
|
||||
...(root.parameters === undefined ? {} : { parameters: parameters(root.parameters) }),
|
||||
...(root.setup === undefined ? {} : { setup: setupActions(root.setup, scheme) }),
|
||||
@@ -362,7 +375,9 @@ export function resolvePlatformConfig(config: ExploreConfig, platform: ExplorePl
|
||||
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) } };
|
||||
device: { name: entry.device ?? (primary ? config.device.name : platform === "android" ? DEFAULT_ANDROID_DEVICE : config.device.name),
|
||||
// A pose belongs to the primary platform's device; the other platform's device starts as it is.
|
||||
...(primary && config.device.pose ? { pose: config.device.pose } : {}) } };
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -370,8 +385,13 @@ 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 }): ExploreConfig {
|
||||
export function withRunOverrides(config: ExploreConfig, overrides: { scope?: string | undefined; expiresIn?: string | undefined; controller?: string | undefined }): ExploreConfig {
|
||||
let result = config;
|
||||
if (overrides.controller !== undefined) {
|
||||
if (overrides.controller !== "agent-device" && overrides.controller !== "argent") fail("--controller must be agent-device or argent", "--controller");
|
||||
const { controller: _previous, ...capture } = result.capture;
|
||||
result = { ...result, capture: { ...capture, ...(overrides.controller === "argent" ? { controller: "argent" as const } : {}) } };
|
||||
}
|
||||
if (overrides.scope !== undefined) {
|
||||
if (overrides.scope !== "changes" && overrides.scope !== "all") fail("--scope must be changes or all", "--scope");
|
||||
result = { ...result, exploration: { ...result.exploration, scope: overrides.scope } };
|
||||
|
||||
@@ -4,7 +4,7 @@ import { dirname, join, resolve } from "node:path";
|
||||
import { createInterface } from "node:readline/promises";
|
||||
import { fileURLToPath } from "node:url";
|
||||
import { stringify } from "yaml";
|
||||
import { DEFAULT_EXPLORE_CONFIG_PATH, readExploreConfig, validateExploreConfig, type ExploreConfig } from "./explore-config.js";
|
||||
import { DEFAULT_EXPLORE_CONFIG_PATH, readExploreConfig, validateExploreConfig, type ExploreConfig, type ExplorePlatform } from "./explore-config.js";
|
||||
import { explorationSecretNames } from "./exploration-inputs.js";
|
||||
import type { RouteEntryReport } from "../ci/route-entry.js";
|
||||
import type { CiInstallResult } from "../ci/workflow-install.js";
|
||||
@@ -60,6 +60,8 @@ type SetupOptions = {
|
||||
appState?: string | undefined;
|
||||
workflows?: boolean | undefined;
|
||||
nonInteractive?: boolean;
|
||||
/** Return the config without writing anything. */
|
||||
dryRun?: boolean;
|
||||
check?: boolean;
|
||||
};
|
||||
type Interaction = {
|
||||
@@ -234,6 +236,14 @@ export type SetupResult = {
|
||||
nextSteps?: string[];
|
||||
};
|
||||
|
||||
/**
|
||||
* The config `setup --non-interactive` would write, without writing it: what a local review runs with in an app that
|
||||
* has no config yet. Throws setup's errors when the app cannot be built for capture.
|
||||
*/
|
||||
export async function defaultExploreConfig(project: string, platform?: ExplorePlatform): Promise<ExploreConfig> {
|
||||
return (await runExploreSetup({ project, platform, nonInteractive: true, dryRun: true })).config;
|
||||
}
|
||||
|
||||
/**
|
||||
* The guided setup. It writes what it can derive (app identity, mode, route parameters it was given,
|
||||
* an agent-instructions draft, CI files) and hands the app-specific flows to the user's coding agent.
|
||||
@@ -290,7 +300,9 @@ export async function runExploreSetup(options: SetupOptions = {}, interaction?:
|
||||
}
|
||||
const schemes = Array.isArray(app.scheme) ? app.scheme.filter((value): value is string => typeof value === "string") : undefined;
|
||||
const scheme = await choose("URL scheme (optional)", options.scheme, schemes?.[0] ?? string(app.scheme), schemes);
|
||||
const profile = await choose(platform === "android" ? "EAS emulator (APK) build profile" : "EAS simulator build profile", options.profile, profiles.length === 1 ? profiles[0]! : "", profiles);
|
||||
const profile = await choose(platform === "android" ? "EAS emulator (APK) build profile" : "EAS simulator build profile", options.profile,
|
||||
// With several, the one named explore, the name the README and the explore-setup skill give it.
|
||||
profiles.length === 1 ? profiles[0]! : profiles.includes("explore") ? "explore" : "", profiles);
|
||||
if (!profiles.includes(profile)) throw new Error(`Choose ${platform === "android" ? "an Android APK" : "a simulator"} profile from eas.json with --profile: ${profiles.join(", ")}.`);
|
||||
const inferredProvider = dependencies["expo-router"] ? "expo-router" : dependencies["@react-navigation/native"] ? "react-navigation" : "auto";
|
||||
const provider = await choose("Navigation provider", options.navigation, inferredProvider, ["auto", "expo-router", "react-navigation"]);
|
||||
@@ -390,6 +402,7 @@ export async function runExploreSetup(options: SetupOptions = {}, interaction?:
|
||||
const answer = await ui!.ask("Write this config? (yes/no)", "yes");
|
||||
if (!/^(y|yes)$/i.test(answer.trim())) throw new Error("Setup canceled; no config was written.");
|
||||
}
|
||||
if (options.dryRun) return { path, config, created: false };
|
||||
await mkdir(parent, { recursive: true });
|
||||
await writeFile(path, yaml, { flag: "wx" });
|
||||
if (instructions) await writeFile(instructionsPath, instructions, { flag: "wx" });
|
||||
|
||||
@@ -73,6 +73,8 @@ export type CaptureBundle = {
|
||||
/** Execution completion time, recorded even when no routes require screenshots. */
|
||||
completedAt?: string;
|
||||
appName?: string;
|
||||
/** The device controller that drove the capture; absent for agent-device, the default. */
|
||||
controller?: "argent";
|
||||
/** The icon the app config declares, shrunk to at most 128 pixels; absent when unavailable. */
|
||||
appIcon?: Omit<AppIconImage, "url"> & { path: string };
|
||||
profile: string; selectedSurfaceIds: string[];
|
||||
@@ -172,8 +174,18 @@ export type PublicVisualVerdict = {
|
||||
rect: { x: number; y: number; width: number; height: number };
|
||||
normalizedRect: { x: number; y: number; width: number; height: number };
|
||||
differentPixels: number; shareOfDiffPercentage: number; dominantChange: string; location: string;
|
||||
/**
|
||||
* Set when the region's content is the same in both screenshots, only moved: how far, in screenshot pixels
|
||||
* (right and down are positive). Absent when the content itself changed.
|
||||
*/
|
||||
shift?: { x: number; y: number };
|
||||
}>;
|
||||
tool: string;
|
||||
/**
|
||||
* Every region the comparison found (not only the published ones) only moved: nothing on the screen changed
|
||||
* content. Absent when any region changed, or moves were not measured.
|
||||
*/
|
||||
allRegionsMoved?: true;
|
||||
/** Diff regions inside the iOS status-bar band that were excluded from the verdict. */
|
||||
ignoredStatusBarRegions?: number;
|
||||
/** Diff regions that lay entirely inside the home-indicator band and were left out of the verdict. */
|
||||
@@ -228,6 +240,8 @@ export type PublicReview = {
|
||||
appIcon?: AppIconImage;
|
||||
/** Absent in reports published before Android support: iOS. */
|
||||
platform?: "ios" | "android";
|
||||
/** The device controller that drove the head capture; absent for agent-device, the default. */
|
||||
controller?: "argent";
|
||||
device?: { model: string; osVersion: string };
|
||||
/** The share of each screenshot's height the verdict ignored as the status bar. */
|
||||
statusBarBandPercent?: number;
|
||||
|
||||
@@ -75,13 +75,23 @@ function assertReviewFields(surface: Surface, enforceComparisonEvidence: boolean
|
||||
}
|
||||
}
|
||||
|
||||
/** A region's move between the screenshots: finite, and small enough to be layout drift rather than another screen. */
|
||||
function validShift(shift: unknown): boolean {
|
||||
if (!shift || typeof shift !== "object") return false;
|
||||
const { x, y } = shift as { x?: unknown; y?: unknown };
|
||||
return typeof x === "number" && typeof y === "number" && Number.isFinite(x) && Number.isFinite(y) && Math.abs(x) <= 64 && Math.abs(y) <= 64;
|
||||
}
|
||||
|
||||
function assertVisualVerdict(visual: PublicVisualVerdict, enforceComparisonEvidence: boolean, paired: boolean): void {
|
||||
if (!visual || typeof visual !== "object" || !VISUAL_VERDICTS.has(visual.verdict)
|
||||
|| typeof visual.reason !== "string" || (enforceComparisonEvidence && visual.reason === "diff-failed") || typeof visual.tool !== "string"
|
||||
|| typeof visual.threshold !== "number" || !Number.isFinite(visual.threshold)
|
||||
|| (visual.mismatchPercentage !== undefined
|
||||
&& (typeof visual.mismatchPercentage !== "number" || !Number.isFinite(visual.mismatchPercentage) || visual.mismatchPercentage < 0))
|
||||
|| (visual.regions !== undefined && (!Array.isArray(visual.regions) || visual.regions.length > 64))
|
||||
|| (visual.regions !== undefined && (!Array.isArray(visual.regions) || visual.regions.length > 64
|
||||
|| visual.regions.some(region => region?.shift !== undefined && !validShift(region.shift))))
|
||||
|| (visual.allRegionsMoved !== undefined && (visual.allRegionsMoved !== true || !visual.regions?.length
|
||||
|| visual.regions.some(region => region.shift === undefined)))
|
||||
|| !paired) {
|
||||
throw new Error("Public visual verdict is inconsistent");
|
||||
}
|
||||
|
||||
@@ -284,6 +284,10 @@ async function constructCaptureReview(options: CaptureReviewOptions, store: Scre
|
||||
? sourceImpactKinds(surface.sourceChange.files.map((file) => file.relation))
|
||||
: []
|
||||
);
|
||||
// Each controller reads and drives the device its own way; a review compares captures made the same way.
|
||||
if ((head.bundle.controller ?? "agent-device") !== (base.bundle.controller ?? "agent-device")) {
|
||||
throw new Error(`The base was captured with ${base.bundle.controller ?? "agent-device"} and the head with ${head.bundle.controller ?? "agent-device"}; capture both sides with the same controller.`);
|
||||
}
|
||||
const colorSchemes = bundleColorSchemes(head.bundle);
|
||||
const baseColorSchemes = bundleColorSchemes(base.bundle);
|
||||
const review: PublicReview = {
|
||||
@@ -291,7 +295,7 @@ async function constructCaptureReview(options: CaptureReviewOptions, store: Scre
|
||||
runId: options.runId, runAttempt: options.runAttempt,
|
||||
...(plan.navigation ? { navigation: plan.navigation } : {}),
|
||||
runtime: { projectId: head.bundle.easProjectId ?? "", buildId: head.bundle.easBuildId ?? "", gitCommit: plan.headSha,
|
||||
platform: head.bundle.platform ?? "ios", statusBarBandPercent: statusBarBandPercent(head.bundle.platform),
|
||||
platform: head.bundle.platform ?? "ios", ...(head.bundle.controller === "argent" ? { controller: "argent" as const } : {}), statusBarBandPercent: statusBarBandPercent(head.bundle.platform),
|
||||
...(homeIndicatorBandPercent(head.bundle.platform) > 0 ? { homeIndicatorBandPercent: homeIndicatorBandPercent(head.bundle.platform) } : {}),
|
||||
...(options.platforms && options.platforms.length > 1 ? { platforms: [...options.platforms] } : {}),
|
||||
...(colorSchemes.length > 1 ? { colorSchemes: [...colorSchemes] } : {}),
|
||||
|
||||
@@ -27,6 +27,7 @@ import {
|
||||
} from "./visual-evidence.js";
|
||||
import { AGENT_DEVICE_VERSION } from "../shared/agent-device-version.js";
|
||||
import { STATUS_BAR_BAND_PERCENT } from "../shared/png-evidence.js";
|
||||
import { measureRegionShifts } from "./region-shift.js";
|
||||
|
||||
export const DEFAULT_VISUAL_THRESHOLD = 0.1;
|
||||
export const DEFAULT_EVIDENCE_TIME_BUDGET_MS = 10 * 60_000;
|
||||
@@ -141,6 +142,29 @@ function visualVerdict(assessment: VisualEvidenceAssessment, threshold: number):
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* The published regions with how far their content moved, where a move explains it: a layout that shifted by a
|
||||
* device pixel reads as moved, not as changed. Every region the comparison found is measured, not only the ones
|
||||
* published, so `allRegionsMoved` can say nothing else on the screen changed. A measurement that fails leaves the
|
||||
* regions as they were.
|
||||
*/
|
||||
async function withRegionShifts(basePath: string, headPath: string, all: readonly VisualDiffRegion[], published: NonNullable<PublicVisualVerdict["regions"]>):
|
||||
Promise<Pick<PublicVisualVerdict, "regions" | "allRegionsMoved">> {
|
||||
try {
|
||||
const shifts = await measureRegionShifts(basePath, headPath, all.map(region => region.rect));
|
||||
const shiftOf = new Map(all.map((region, index) => [region.rect, shifts[index]] as const));
|
||||
return {
|
||||
regions: published.map(region => {
|
||||
const shift = shiftOf.get(region.rect);
|
||||
return shift ? { ...region, shift } : region;
|
||||
}),
|
||||
...(all.length > 0 && shifts.every(Boolean) ? { allRegionsMoved: true as const } : {}),
|
||||
};
|
||||
} catch {
|
||||
return { regions: published };
|
||||
}
|
||||
}
|
||||
|
||||
/** Remove status-bar-only diff regions from a measurement and recompute its verdict inputs. */
|
||||
export function ignoreStatusBar(measurement: ScreenshotDiffMeasurement, bandPercent: number = STATUS_BAR_BAND_PERCENT): { measurement: ScreenshotDiffMeasurement; ignored: number } {
|
||||
const bands = ignoreSystemBands(measurement, { top: bandPercent, bottom: 0 });
|
||||
@@ -463,6 +487,10 @@ export async function assessPublicEvidence(options: {
|
||||
representative: measurement,
|
||||
});
|
||||
visual = visualVerdict(assessment, threshold);
|
||||
// Measuring moves is extra: once the comparison budget is spent, regions go out unmeasured.
|
||||
if (visual.verdict === "modified" && visual.regions?.length && now() <= deadline) {
|
||||
Object.assign(visual, await withRegionShifts(basePath, headPath, measurement.regions, visual.regions));
|
||||
}
|
||||
if (ignoredTop > 0) visual.ignoredStatusBarRegions = ignoredTop;
|
||||
if (ignoredBottom > 0) visual.ignoredHomeIndicatorRegions = ignoredBottom;
|
||||
visualCounts.compared += 1;
|
||||
|
||||
@@ -0,0 +1,150 @@
|
||||
import { createRequire } from "node:module";
|
||||
import { readFile } from "node:fs/promises";
|
||||
import type { DecodedFrame } from "../shared/png-evidence.js";
|
||||
|
||||
/** How far a region's content moved from Before to After, in screenshot pixels (right and down are positive). */
|
||||
export type RegionShift = { x: number; y: number };
|
||||
type Rect = { x: number; y: number; width: number; height: number };
|
||||
|
||||
/**
|
||||
* The farthest a region is searched for, in screenshot pixels: layout drift, not a different screen. Drift adds up
|
||||
* down a long screen (a device pixel per text element above), so the vertical reach is the larger.
|
||||
*/
|
||||
const MAX_SHIFT_X = 4;
|
||||
const MAX_SHIFT_Y = 20;
|
||||
/** How close to the edge of the search a best fit may land and still count: the real one may lie beyond it. */
|
||||
const EDGE = 1.5;
|
||||
/**
|
||||
* The share of a region's difference one shift must explain for the region to have moved rather than changed.
|
||||
* A move of half a pixel or less re-rasterizes text rather than shifting it, so a pure shift explains only a
|
||||
* quarter to a half of it; content that changed (new text, a caret) explains under a quarter at that size, and
|
||||
* anything larger has to be explained mostly by the shift. Measured on euxy's SDK 58 upgrade (brentvatne/euxy#161).
|
||||
*/
|
||||
const MIN_EXPLAINED = 0.6;
|
||||
const MIN_EXPLAINED_SUBPIXEL = 0.25;
|
||||
const SUBPIXEL = 0.5;
|
||||
/** A smaller shift is rendering noise, not a move. */
|
||||
const MIN_SHIFT = 0.25;
|
||||
/** Sixths of a pixel in the refining search: a third of a 1x pixel is one device pixel on a 3x screen. */
|
||||
const STEPS_PER_PIXEL = 6;
|
||||
/** Fits this close to the best are ties, which go to the smallest move (content that is the same all along one axis). */
|
||||
const TIE = 1.005;
|
||||
/** Another fit this close at a vertical offset two or more pixels away makes the move ambiguous (repeating content). */
|
||||
const AMBIGUOUS = 1.05;
|
||||
/**
|
||||
* After aligning by the move, content is the same only where every channel is within this: re-rasterized text
|
||||
* differs by at most about 125 (brentvatne/euxy#161), new content by about 200. A few pixels over it are noise; more are a change.
|
||||
*/
|
||||
const CHANGED_CHANNEL = 140;
|
||||
const CHANGED_PIXELS = 3;
|
||||
|
||||
type Image = { width: number; height: number; frame: DecodedFrame; luminance: Float32Array };
|
||||
type Fit = { sx: number; sy: number; error: number };
|
||||
|
||||
function image(frame: DecodedFrame): Image {
|
||||
const luminance = new Float32Array(frame.width * frame.height);
|
||||
for (let index = 0; index < luminance.length; index += 1) {
|
||||
const offset = index * 4;
|
||||
luminance[index] = 0.299 * frame.data[offset]! + 0.587 * frame.data[offset + 1]! + 0.114 * frame.data[offset + 2]!;
|
||||
}
|
||||
return { width: frame.width, height: frame.height, frame, luminance };
|
||||
}
|
||||
|
||||
/** Bilinear sample of one plane: `channel` 0–2 of the frame, or luminance when undefined. */
|
||||
function at(source: Image, x: number, y: number, channel?: number): number {
|
||||
const cx = Math.min(source.width - 1, Math.max(0, x));
|
||||
const cy = Math.min(source.height - 1, Math.max(0, y));
|
||||
const x0 = Math.floor(cx), y0 = Math.floor(cy);
|
||||
const x1 = Math.min(source.width - 1, x0 + 1), y1 = Math.min(source.height - 1, y0 + 1);
|
||||
const fx = cx - x0, fy = cy - y0;
|
||||
const value = channel === undefined
|
||||
? (px: number, py: number) => source.luminance[py * source.width + px]!
|
||||
: (px: number, py: number) => source.frame.data[(py * source.width + px) * 4 + channel]!;
|
||||
return value(x0, y0) * (1 - fx) * (1 - fy) + value(x1, y0) * fx * (1 - fy) + value(x0, y1) * (1 - fx) * fy + value(x1, y1) * fx * fy;
|
||||
}
|
||||
|
||||
/** How badly After's region matches Before shifted by (sx, sy). */
|
||||
function mismatch(base: Image, head: Image, rect: Rect, sx: number, sy: number): number {
|
||||
let error = 0;
|
||||
for (let y = rect.y; y < rect.y + rect.height; y += 1) {
|
||||
for (let x = rect.x; x < rect.x + rect.width; x += 1) {
|
||||
error += Math.abs(at(base, x - sx, y - sy) - head.luminance[y * head.width + x]!);
|
||||
}
|
||||
}
|
||||
return error;
|
||||
}
|
||||
|
||||
/** The best of some fits, with near-ties going to the smallest move. */
|
||||
function bestOf(fits: readonly Fit[]): Fit {
|
||||
const least = Math.min(...fits.map(fit => fit.error));
|
||||
return fits.filter(fit => fit.error <= least * TIE + 1e-6)
|
||||
.sort((a, b) => Math.hypot(a.sx, a.sy) - Math.hypot(b.sx, b.sy))[0]!;
|
||||
}
|
||||
|
||||
/** Whether, aligned by the move, some of the region still differs strongly in any channel: content that changed. */
|
||||
function changedAfterMove(base: Image, head: Image, rect: Rect, sx: number, sy: number): boolean {
|
||||
let strong = 0;
|
||||
for (let y = rect.y; y < rect.y + rect.height; y += 1) {
|
||||
for (let x = rect.x; x < rect.x + rect.width; x += 1) {
|
||||
for (let channel = 0; channel < 3; channel += 1) {
|
||||
if (Math.abs(at(base, x - sx, y - sy, channel) - head.frame.data[(y * head.width + x) * 4 + channel]!) > CHANGED_CHANNEL) {
|
||||
strong += 1;
|
||||
if (strong >= CHANGED_PIXELS) return true;
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* The shift that explains one region's difference, if one does: the region's content is the same in both
|
||||
* screenshots, only moved. A region whose content changed (new text, another colour) has no shift, and neither has
|
||||
* one whose content repeats so that several shifts fit.
|
||||
*/
|
||||
function regionShift(base: Image, head: Image, region: Rect): RegionShift | undefined {
|
||||
const x = Math.max(0, Math.floor(region.x)), y = Math.max(0, Math.floor(region.y));
|
||||
const rect = { x, y, width: Math.min(head.width - x, Math.ceil(region.width)), height: Math.min(head.height - y, Math.ceil(region.height)) };
|
||||
if (rect.width <= 0 || rect.height <= 0) return undefined;
|
||||
const unshifted = mismatch(base, head, rect, 0, 0);
|
||||
if (unshifted === 0) return undefined;
|
||||
// Whole pixels first, every pixel counting: sampling every other row aliases on thin shapes (text, hairlines).
|
||||
const whole: Fit[] = [];
|
||||
for (let sy = -MAX_SHIFT_Y; sy <= MAX_SHIFT_Y; sy += 1) {
|
||||
for (let sx = -MAX_SHIFT_X; sx <= MAX_SHIFT_X; sx += 1) whole.push({ sx, sy, error: mismatch(base, head, rect, sx, sy) });
|
||||
}
|
||||
const coarse = bestOf(whole);
|
||||
if (whole.some(fit => Math.abs(fit.sy - coarse.sy) >= 2 && fit.error <= coarse.error * AMBIGUOUS + 1e-6)) return undefined;
|
||||
// Then sixths of a pixel around it, from whole-number steps so a move up and a move down round alike.
|
||||
const fine: Fit[] = [];
|
||||
for (let iy = -STEPS_PER_PIXEL; iy <= STEPS_PER_PIXEL; iy += 1) {
|
||||
for (let ix = -STEPS_PER_PIXEL; ix <= STEPS_PER_PIXEL; ix += 1) {
|
||||
const sx = coarse.sx + ix / STEPS_PER_PIXEL, sy = coarse.sy + iy / STEPS_PER_PIXEL;
|
||||
fine.push({ sx, sy, error: ix === 0 && iy === 0 ? coarse.error : mismatch(base, head, rect, sx, sy) });
|
||||
}
|
||||
}
|
||||
const best = bestOf(fine);
|
||||
if (Math.abs(best.sx) > MAX_SHIFT_X - EDGE || Math.abs(best.sy) > MAX_SHIFT_Y - EDGE) return undefined;
|
||||
const distance = Math.hypot(best.sx, best.sy);
|
||||
const needed = distance <= SUBPIXEL + 1e-6 ? MIN_EXPLAINED_SUBPIXEL : MIN_EXPLAINED;
|
||||
if (distance < MIN_SHIFT - 1e-6 || 1 - best.error / unshifted < needed) return undefined;
|
||||
if (changedAfterMove(base, head, rect, best.sx, best.sy)) return undefined;
|
||||
const round = (value: number) => Math.round(value * 100) / 100 || 0;
|
||||
return { x: round(best.sx), y: round(best.sy) };
|
||||
}
|
||||
|
||||
/** Each region's shift between two screenshots of the same size; undefined where a region's content changed. */
|
||||
export function regionShifts(baseFrame: DecodedFrame, headFrame: DecodedFrame, regions: readonly Rect[]): Array<RegionShift | undefined> {
|
||||
if (baseFrame.width !== headFrame.width || baseFrame.height !== headFrame.height) return regions.map(() => undefined);
|
||||
const base = image(baseFrame), head = image(headFrame);
|
||||
return regions.map(region => regionShift(base, head, region));
|
||||
}
|
||||
|
||||
/** Reads both PNG screenshots and measures each region's shift. */
|
||||
export async function measureRegionShifts(basePath: string, headPath: string, regions: readonly Rect[]): Promise<Array<RegionShift | undefined>> {
|
||||
const { PNG } = createRequire(import.meta.url.replace(/\?.*$/, ""))("pngjs") as
|
||||
{ PNG: { sync: { read(bytes: Buffer, options: { checkCRC: boolean }): DecodedFrame } } };
|
||||
const [base, head] = await Promise.all([readFile(basePath), readFile(headPath)]);
|
||||
return regionShifts(PNG.sync.read(base, { checkCRC: false }), PNG.sync.read(head, { checkCRC: false }), regions);
|
||||
}
|
||||
@@ -11,12 +11,14 @@ import type {
|
||||
} from "./runtime-evidence.js";
|
||||
import type { ExploreMap, Observation, Screen } from "../types.js";
|
||||
import { CAPTURE_OBSERVER_IDENTIFIER } from "../capture/observer.js";
|
||||
import { ARGENT_VERSION } from "../shared/argent-version.js";
|
||||
|
||||
/** Strict, non-secret subset written after a successful EAS Simulator cleanup. */
|
||||
export type RuntimeExecutionContext = {
|
||||
provider: "eas-simulator";
|
||||
controller: "agent-device";
|
||||
controllerPackageVersion: typeof AGENT_DEVICE_VERSION;
|
||||
controller: "agent-device" | "argent";
|
||||
/** The pinned package of the controller that drove the session. */
|
||||
controllerPackageVersion: typeof AGENT_DEVICE_VERSION | typeof ARGENT_VERSION;
|
||||
easCliVersion: typeof EAS_CLI_VERSION;
|
||||
platform: "ios" | "android";
|
||||
deviceModel: string;
|
||||
@@ -107,12 +109,13 @@ export function parseRuntimeExecutionContext(value: unknown): RuntimeExecutionCo
|
||||
}
|
||||
return context.colorSchemes.map((entry) => literal(entry, ["light", "dark"], "Runtime color schemes"));
|
||||
})();
|
||||
const controller = literal(context.controller, ["agent-device", "argent"], "Runtime controller");
|
||||
return {
|
||||
provider: literal(context.provider, ["eas-simulator"], "Runtime provider"),
|
||||
controller: literal(context.controller, ["agent-device"], "Runtime controller"),
|
||||
controller,
|
||||
controllerPackageVersion: literal(
|
||||
context.controllerPackageVersion,
|
||||
[AGENT_DEVICE_VERSION],
|
||||
[controller === "argent" ? ARGENT_VERSION : AGENT_DEVICE_VERSION],
|
||||
"Controller package version",
|
||||
),
|
||||
easCliVersion: literal(context.easCliVersion, [EAS_CLI_VERSION], "EAS CLI version"),
|
||||
|
||||
@@ -93,7 +93,7 @@ export type RawCaptureSample = {
|
||||
|
||||
export type RawSimulatorEnvironment = {
|
||||
provider: "eas-simulator";
|
||||
controller: "agent-device";
|
||||
controller: "agent-device" | "argent";
|
||||
platform: Platform;
|
||||
deviceModel: string;
|
||||
osVersion: string;
|
||||
@@ -247,7 +247,7 @@ export type RuntimeEnvironmentEvidence = {
|
||||
profile: EvidenceField<"capture-context", string>;
|
||||
fixturePersona?: EvidenceField<"capture-context", string>;
|
||||
provider: EvidenceField<"eas-agent-device", "eas-simulator">;
|
||||
controller: EvidenceField<"eas-agent-device", "agent-device">;
|
||||
controller: EvidenceField<"eas-agent-device", "agent-device" | "argent">;
|
||||
controllerPackageVersion?: EvidenceField<"capture-context", string>;
|
||||
easCliVersion?: EvidenceField<"capture-context", string>;
|
||||
platform: EvidenceField<"eas-agent-device", Platform>;
|
||||
@@ -785,7 +785,7 @@ function parseEnvironment(value: unknown): RawSimulatorEnvironment {
|
||||
);
|
||||
return {
|
||||
provider: literal(environment.provider, ["eas-simulator"], "Runtime provider"),
|
||||
controller: literal(environment.controller, ["agent-device"], "Runtime controller"),
|
||||
controller: literal(environment.controller, ["agent-device", "argent"], "Runtime controller"),
|
||||
platform: literal(environment.platform, PLATFORMS, "Runtime platform"),
|
||||
deviceModel: safeString(environment.deviceModel, "Device model", 256),
|
||||
osVersion: safeString(environment.osVersion, "OS version", 256),
|
||||
|
||||
@@ -0,0 +1,5 @@
|
||||
/**
|
||||
* The one Argent version Explore runs. The local CLI (`package.json`) and the EAS Simulator controller
|
||||
* (`--package-version` for an `argent` session) must both be this version.
|
||||
*/
|
||||
export const ARGENT_VERSION = "0.29.0";
|
||||
@@ -0,0 +1,170 @@
|
||||
/**
|
||||
* The device controllers Explore drives, fetched on first use instead of installed with Explore. Each is pinned to
|
||||
* an exact npm release and its sha512 integrity; the tarball is checked before anything in it is written, nothing in
|
||||
* it runs at install time, and neither controller needs other packages at run time.
|
||||
*/
|
||||
import { createHash, randomUUID } from "node:crypto";
|
||||
import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
|
||||
import { chmod, mkdir, open, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
|
||||
import { homedir } from "node:os";
|
||||
import { dirname, join, resolve, sep } from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
import { safeRelativePath, walkTar } from "../binary/archive.js";
|
||||
import { CiError } from "./ci-errors.js";
|
||||
import { AGENT_DEVICE_VERSION } from "./agent-device-version.js";
|
||||
import { ARGENT_VERSION } from "./argent-version.js";
|
||||
|
||||
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-Om1j6oNJkeKlkk8lBM+0V9bKwpxUXLMf/PDDSvAt3RFquBRqAiM58J81E0rvPQNxs6GCjhABYpwVvIAXptxjjA==" },
|
||||
argent: { name: "@swmansion/argent", version: ARGENT_VERSION, bin: "dist/cli.js",
|
||||
integrity: "sha512-XXWlWZJlHKqnAvNx3RDhuiVFQOPqh5EDB76+mFAyqC2mutC6irzw03+M/6S/WQ+Dzz2IYOkEfOzQnOOdhrGgJg==" },
|
||||
};
|
||||
|
||||
const COMPLETE = ".explore-controller.json";
|
||||
const MAX_CONTROLLER_BYTES = 256 * 1024 * 1024;
|
||||
const LAUNCHER = fileURLToPath(new URL("../capture/controller-launcher.js", import.meta.url));
|
||||
|
||||
/** Where fetched controllers live: EXPLORE_CONTROLLER_CACHE, else the user's cache directory. */
|
||||
export function controllerCacheRoot(environment: NodeJS.ProcessEnv = process.env): string {
|
||||
if (environment.EXPLORE_CONTROLLER_CACHE) return resolve(environment.EXPLORE_CONTROLLER_CACHE);
|
||||
const base = environment.XDG_CACHE_HOME || join(environment.HOME || homedir(), ".cache");
|
||||
return join(base, "expo-explore", "controllers");
|
||||
}
|
||||
|
||||
export function controllerDirectory(controller: ControllerName, environment: NodeJS.ProcessEnv = process.env): string {
|
||||
const { name, version } = CONTROLLER_PACKAGES[controller];
|
||||
return join(controllerCacheRoot(environment), `${name.replace("/", "+")}@${version}`);
|
||||
}
|
||||
|
||||
/** The controller's entry file in the cache; it exists once `ensureController` has run. */
|
||||
export function controllerBin(controller: ControllerName, environment: NodeJS.ProcessEnv = process.env): string {
|
||||
return join(controllerDirectory(controller, environment), CONTROLLER_PACKAGES[controller].bin);
|
||||
}
|
||||
|
||||
export function controllerCached(controller: ControllerName, environment: NodeJS.ProcessEnv = process.env): boolean {
|
||||
return existsSync(join(controllerDirectory(controller, environment), COMPLETE));
|
||||
}
|
||||
|
||||
/** The registry tarball for a release, from EXPLORE_NPM_REGISTRY (a mirror) or the public npm registry. */
|
||||
export function controllerTarballUrl(controller: ControllerName, environment: NodeJS.ProcessEnv = process.env): string {
|
||||
const { name, version } = CONTROLLER_PACKAGES[controller];
|
||||
const registry = (environment.EXPLORE_NPM_REGISTRY || "https://registry.npmjs.org").replace(/\/+$/, "");
|
||||
return `${registry}/${name}/-/${name.split("/").pop()}-${version}.tgz`;
|
||||
}
|
||||
|
||||
/**
|
||||
* The command that runs agent-device: a small script in the cache that fetches the pinned release on first use and
|
||||
* then runs it with the same arguments. It names the cache, so a caller that narrows the environment (no HOME) still
|
||||
* finds it. Written synchronously, so capture options can name it before any controller call.
|
||||
*/
|
||||
export function agentDeviceLauncher(environment: NodeJS.ProcessEnv = process.env): string {
|
||||
const root = controllerCacheRoot(environment);
|
||||
const quote = (value: string) => `'${value.replace(/'/g, `'\\''`)}'`;
|
||||
// The registry is part of the command too: controller calls run with a narrowed environment that drops it.
|
||||
const registry = environment.EXPLORE_NPM_REGISTRY ? ` EXPLORE_NPM_REGISTRY=${quote(environment.EXPLORE_NPM_REGISTRY)}` : "";
|
||||
const script = `#!/bin/sh\nEXPLORE_CONTROLLER_CACHE=${quote(root)}${registry} exec ${quote(process.execPath)} ${quote(LAUNCHER)} agent-device "$@"\n`;
|
||||
// One command per pinned release and installation, so two Explore installs on a machine never swap each other's
|
||||
// controller in the middle of a capture.
|
||||
const digest = createHash("sha256").update(script).digest("hex").slice(0, 12);
|
||||
const command = join(root, "bin", `agent-device-${CONTROLLER_PACKAGES["agent-device"].version}-${digest}`);
|
||||
if (existsSync(command) && readFileSync(command, "utf8") === script) return command;
|
||||
mkdirSync(dirname(command), { recursive: true, mode: 0o700 });
|
||||
const temporary = `${command}.${process.pid}.${randomUUID()}`;
|
||||
writeFileSync(temporary, script, { mode: 0o755 });
|
||||
renameSync(temporary, command);
|
||||
return command;
|
||||
}
|
||||
|
||||
/** A fetch killed mid-download (a timed-out controller call) leaves its staging files; clear any over an hour old. */
|
||||
async function removeAbandonedStaging(root: string): Promise<void> {
|
||||
const cutoff = Date.now() - 60 * 60_000;
|
||||
for (const name of await readdir(root).catch(() => [] as string[])) {
|
||||
if (!name.startsWith(".staging-")) continue;
|
||||
const path = join(root, name);
|
||||
const info = await stat(path).catch(() => undefined);
|
||||
if (info && info.mtimeMs < cutoff) await rm(path, { recursive: true, force: true });
|
||||
}
|
||||
}
|
||||
|
||||
function downloadFailed(controller: ControllerName, message: string): CiError {
|
||||
const { name, version } = CONTROLLER_PACKAGES[controller];
|
||||
return new CiError({ code: "CONTROLLER_DOWNLOAD_FAILED", stage: "preflight", message: `${name}@${version} could not be fetched: ${message}`,
|
||||
nextAction: "Check that this machine can reach the npm registry (or set EXPLORE_NPM_REGISTRY to a mirror that serves it), then rerun." });
|
||||
}
|
||||
|
||||
/**
|
||||
* Fetches the pinned controller into the cache once and returns its entry file. The download is hashed while it
|
||||
* streams and must match the pinned integrity before it is unpacked; only regular files and directories inside the
|
||||
* package are written, and the finished directory is renamed into place, so concurrent runs never see half of it.
|
||||
*/
|
||||
export async function ensureController(controller: ControllerName, options: {
|
||||
environment?: NodeJS.ProcessEnv; fetch?: typeof fetch; progress?: (message: string) => void;
|
||||
/** Tests: releases built on the spot instead of the pinned npm ones. */
|
||||
packages?: typeof CONTROLLER_PACKAGES;
|
||||
} = {}): Promise<string> {
|
||||
const environment = options.environment ?? process.env;
|
||||
const pinned = (options.packages ?? CONTROLLER_PACKAGES)[controller];
|
||||
const directory = controllerDirectory(controller, environment);
|
||||
const bin = join(directory, pinned.bin);
|
||||
if (controllerCached(controller, environment)) return bin;
|
||||
const root = controllerCacheRoot(environment);
|
||||
await mkdir(root, { recursive: true, mode: 0o700 });
|
||||
await removeAbandonedStaging(root);
|
||||
const staging = join(root, `.staging-${process.pid}-${randomUUID()}`);
|
||||
const tarball = `${staging}.tgz`;
|
||||
try {
|
||||
options.progress?.(`fetching ${pinned.name}@${pinned.version}`);
|
||||
let response: Response;
|
||||
try { response = await (options.fetch ?? fetch)(controllerTarballUrl(controller, environment)); }
|
||||
catch (error) { throw downloadFailed(controller, error instanceof Error ? error.message : String(error)); }
|
||||
if (!response.ok || !response.body) throw downloadFailed(controller, `the registry answered ${response.status}`);
|
||||
const hash = createHash("sha512");
|
||||
const file = await open(tarball, "wx", 0o600);
|
||||
let bytes = 0;
|
||||
try {
|
||||
for await (const chunk of response.body as unknown as AsyncIterable<Uint8Array>) {
|
||||
bytes += chunk.length;
|
||||
if (bytes > MAX_CONTROLLER_BYTES) throw downloadFailed(controller, "the tarball is larger than expected");
|
||||
hash.update(chunk);
|
||||
await file.write(chunk);
|
||||
}
|
||||
} finally { await file.close(); }
|
||||
const integrity = `sha512-${hash.digest("base64")}`;
|
||||
if (integrity !== pinned.integrity) {
|
||||
throw new CiError({ code: "CONTROLLER_INTEGRITY_MISMATCH", stage: "preflight",
|
||||
message: `${pinned.name}@${pinned.version} from the registry does not match the release Explore pins (${integrity}).`,
|
||||
nextAction: "Do not use this registry for Explore's controllers; unset EXPLORE_NPM_REGISTRY or point it at a faithful mirror." });
|
||||
}
|
||||
await mkdir(staging, { mode: 0o700 });
|
||||
let written = 0;
|
||||
await walkTar(tarball, async (entry, contents) => {
|
||||
const relative = safeRelativePath(entry.name);
|
||||
if (relative === "package" && entry.type === "5") return;
|
||||
if (!relative || !relative.startsWith("package/")) throw downloadFailed(controller, `the tarball has an entry outside the package (${entry.name})`);
|
||||
const target = join(staging, relative.slice("package/".length));
|
||||
if (!target.startsWith(`${staging}${sep}`)) throw downloadFailed(controller, `the tarball has an unsafe entry (${entry.name})`);
|
||||
if (entry.type === "5") { await mkdir(target, { recursive: true }); return; }
|
||||
if (entry.type !== "0") throw downloadFailed(controller, `the tarball has a link or special file (${entry.name})`);
|
||||
written += entry.size;
|
||||
if (written > MAX_CONTROLLER_BYTES) throw downloadFailed(controller, "the package is larger than expected");
|
||||
await mkdir(dirname(target), { recursive: true });
|
||||
await writeFile(target, await contents(), { mode: entry.mode & 0o111 ? 0o755 : 0o644 });
|
||||
});
|
||||
if (!existsSync(join(staging, pinned.bin))) throw downloadFailed(controller, `the package has no ${pinned.bin}`);
|
||||
await chmod(join(staging, pinned.bin), 0o755);
|
||||
await writeFile(join(staging, COMPLETE), `${JSON.stringify({ name: pinned.name, version: pinned.version, integrity })}\n`);
|
||||
try { await rename(staging, directory); }
|
||||
catch (error) {
|
||||
// Another run finished first; its copy is the same verified release.
|
||||
if (!controllerCached(controller, environment)) throw error;
|
||||
}
|
||||
return bin;
|
||||
} finally {
|
||||
await rm(tarball, { force: true });
|
||||
await rm(staging, { recursive: true, force: true });
|
||||
}
|
||||
}
|
||||
@@ -406,10 +406,13 @@ test("the Screens tree folds by row, by keyboard, and all at once, and remembers
|
||||
await tree.getByRole("button", { name: "Expand all" }).click();
|
||||
await expect.poll(() => rows.count()).toBe(expandedRows);
|
||||
|
||||
// Section headings name the folder, with the path beneath.
|
||||
const onboarding = page.getByRole("region", { name: "Onboarding" });
|
||||
await expect(onboarding.getByRole("heading", { level: 2 })).toHaveText("Onboarding");
|
||||
await expect(onboarding.locator(".screens-section-head .path")).toHaveText("app/onboarding");
|
||||
// The tree names the folders, so the page beside it is one grid without section headings, in the tree's order.
|
||||
await expect(page.locator(".screens-page .screens-section-head")).toHaveCount(0);
|
||||
await expect(page.locator(".screens-page .screens-grid")).toHaveCount(1);
|
||||
const treeOrder = await tree.locator(".screens-tree-row[data-screen-id]").evaluateAll(rows => rows.map(row => row.dataset.screenId));
|
||||
const gridOrder = await page.locator(".screens-page .screens-cell").evaluateAll(cells => cells.map(cell => cell.dataset.screenId));
|
||||
assert.ok(gridOrder.length > 1);
|
||||
assert.deepEqual(gridOrder, treeOrder);
|
||||
assert.deepEqual(errors, []);
|
||||
});
|
||||
|
||||
|
||||
@@ -1309,7 +1309,100 @@ for (const canvas of ["map", "screens"] as const) {
|
||||
});
|
||||
}
|
||||
|
||||
test("reuses the Map screenshot card visual in Screens, with the route at the card's left edge", async ({ page }) => {
|
||||
test("← and → step through the Screens cards in page order, with focus, and leave the tree's arrows alone", async ({ page }) => {
|
||||
await serveWorkspace(page);
|
||||
await page.goto("/screens");
|
||||
const grid = page.getByRole("main", { name: "Screens" });
|
||||
await grid.getByRole("button", { name: /^All/ }).click();
|
||||
const cells = grid.locator(".screens-grid .screens-cell");
|
||||
const ids = await cells.evaluateAll(elements => elements.map(element => element.getAttribute("data-screen-id")!));
|
||||
expect(ids.length).toBeGreaterThan(2);
|
||||
const card = (id: string) => grid.locator(`.screens-cell[data-screen-id="${id}"] .screen-screenshot-card`);
|
||||
const target = (id: string) => grid.locator(`.screens-cell[data-screen-id="${id}"] .screen-screenshot-target`);
|
||||
|
||||
// With nothing selected, → starts at the first card.
|
||||
await expect(grid.locator(".screen-screenshot-card.selected")).toHaveCount(0);
|
||||
await page.keyboard.press("ArrowRight");
|
||||
await expect(card(ids[0]!)).toHaveClass(/selected/);
|
||||
await expect(target(ids[0]!)).toBeFocused();
|
||||
await page.keyboard.press("ArrowRight");
|
||||
await expect(card(ids[1]!)).toHaveClass(/selected/);
|
||||
await expect(target(ids[1]!)).toBeFocused();
|
||||
await page.keyboard.press("ArrowRight");
|
||||
await expect(card(ids[2]!)).toHaveClass(/selected/);
|
||||
await page.keyboard.press("ArrowLeft");
|
||||
await expect(card(ids[1]!)).toHaveClass(/selected/);
|
||||
await expect(card(ids[2]!)).not.toHaveClass(/selected/);
|
||||
|
||||
// ↓ and ↑ move a row, to the card in the same column.
|
||||
const tops = await cells.evaluateAll(elements => elements.map(element => Math.round(element.getBoundingClientRect().top)));
|
||||
const columns = tops.filter(top => top === tops[0]).length;
|
||||
if (ids.length > 1 + columns) {
|
||||
await page.keyboard.press("ArrowDown");
|
||||
await expect(card(ids[1 + columns]!)).toHaveClass(/selected/);
|
||||
await expect(target(ids[1 + columns]!)).toBeFocused();
|
||||
await page.keyboard.press("ArrowUp");
|
||||
await expect(card(ids[1]!)).toHaveClass(/selected/);
|
||||
}
|
||||
|
||||
// Held, → keeps stepping, as in Compare, and stops on release.
|
||||
const selectedAt = async () => ids.indexOf((await grid.locator(".screens-cell:has(.screen-screenshot-card.selected)").getAttribute("data-screen-id"))!);
|
||||
const from = await selectedAt();
|
||||
await page.keyboard.down("ArrowRight");
|
||||
await expect.poll(selectedAt, { timeout: 4000 }).toBeGreaterThanOrEqual(Math.min(ids.length - 1, from + 3));
|
||||
await page.keyboard.up("ArrowRight");
|
||||
const released = await selectedAt();
|
||||
await page.waitForTimeout(500);
|
||||
expect(await selectedAt()).toBe(released);
|
||||
|
||||
// Return opens the pick in the Inspector, from the card or from anywhere on the page.
|
||||
const inspector = page.getByRole("complementary", { name: "Inspector panel" });
|
||||
await expect(inspector).toBeHidden();
|
||||
await page.keyboard.press("Enter");
|
||||
await expect(inspector).toBeVisible();
|
||||
await page.keyboard.press("Escape");
|
||||
await expect(inspector).toBeHidden();
|
||||
await page.evaluate(() => (document.activeElement as HTMLElement | null)?.blur());
|
||||
await page.keyboard.press("Enter");
|
||||
await expect(inspector).toBeVisible();
|
||||
await page.keyboard.press("Escape");
|
||||
await expect(inspector).toBeHidden();
|
||||
|
||||
// In the tree, ← and → fold and unfold rows; they do not step the cards.
|
||||
const picked = await selectedAt();
|
||||
const row = grid.locator(".screens-tree-row").first();
|
||||
await row.focus();
|
||||
await page.keyboard.press("ArrowLeft");
|
||||
await expect(card(ids[picked]!)).toHaveClass(/selected/);
|
||||
});
|
||||
|
||||
test("→ steps the Screens cards right after Screens is opened from the toolbar, and from a pick that Changed hides", async ({ page }) => {
|
||||
await serveWorkspace(page);
|
||||
await page.goto("/map");
|
||||
await page.getByRole("group", { name: "Canvas view" }).getByRole("button", { name: "Screens", exact: true }).click();
|
||||
const grid = page.getByRole("main", { name: "Screens" });
|
||||
const cells = grid.locator(".screens-grid .screens-cell");
|
||||
await expect(cells.first()).toBeVisible();
|
||||
// Focus is still on the toolbar's Screens button.
|
||||
await page.keyboard.press("ArrowRight");
|
||||
await expect(cells.first().locator(".screen-screenshot-card")).toHaveClass(/selected/);
|
||||
|
||||
// Pick a screen that Changed hides, then show Changed: → goes to the next changed card after it in the tree.
|
||||
await grid.getByRole("button", { name: /^All/ }).click();
|
||||
const all = await cells.evaluateAll(elements => elements.map(element => element.getAttribute("data-screen-id")!));
|
||||
await grid.getByRole("button", { name: /^Changed/ }).click();
|
||||
const changed = await cells.evaluateAll(elements => elements.map(element => element.getAttribute("data-screen-id")!));
|
||||
const hidden = all.find((id, position) => !changed.includes(id) && all.slice(position + 1).some(next => changed.includes(next)));
|
||||
test.skip(!hidden, "the fixture has no unchanged screen before a changed one");
|
||||
await grid.getByRole("button", { name: /^All/ }).click();
|
||||
await grid.locator(`.screens-cell[data-screen-id="${hidden}"] .screen-screenshot-target`).click();
|
||||
await grid.getByRole("button", { name: /^Changed/ }).click();
|
||||
const expected = all.slice(all.indexOf(hidden!) + 1).find(id => changed.includes(id))!;
|
||||
await page.keyboard.press("ArrowRight");
|
||||
await expect(grid.locator(`.screens-cell[data-screen-id="${expected}"] .screen-screenshot-card`)).toHaveClass(/selected/);
|
||||
});
|
||||
|
||||
test("reuses the Map screenshot card in Screens, with the route under the screenshot at the card's left edge", async ({ page }) => {
|
||||
await serveWorkspace(page);
|
||||
await page.goto("/screens");
|
||||
|
||||
@@ -1337,8 +1430,9 @@ test("reuses the Map screenshot card visual in Screens, with the route at the ca
|
||||
};
|
||||
});
|
||||
expect(layout.flexDirection).toBe("column");
|
||||
// The card is the Map's, so the heading still comes first in the markup; Screens shows it as the card's footer.
|
||||
expect(layout.headingBeforeImage).toBe(true);
|
||||
expect(layout.headingTop).toBeLessThan(layout.imageTop);
|
||||
expect(layout.headingTop).toBeGreaterThan(layout.imageTop);
|
||||
expect(layout.titleLeftDelta).toBeLessThan(1);
|
||||
|
||||
}
|
||||
|
||||
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"description": "Source: ax-service\nMode: flat\nCoordinates are normalized [0,1] fractions of the screen (x, y, width, height), not pixels.\nPass them straight to gesture-tap / gesture-swipe / gesture-pinch, which expect this same space.\nTo tap an element, use its centre: tap_x = frame.x + frame.width / 2, tap_y = frame.y + frame.height / 2.\n\nROOT AXGroup (0.000, 0.000, 1.000, 1.000)\n\n AXGroup \"Open in “euxy”?\" (0.067, 0.382, 0.687, 0.186)\n AXAdjustable \"Vertical scroll bar, 2 pages\" value=\"0%\" (0.682, 0.382, 0.064, 0.068)\n AXAdjustable \"Horizontal scroll bar, 1 page\" value=\"0%\" (0.067, 0.412, 0.687, 0.034)\n AXStaticText \"Open in “euxy”?\" (0.131, 0.414, 0.558, 0.030)\n AXAdjustable \"Vertical scroll bar, 1 page\" value=\"0%\" (0.682, 0.450, 0.064, 0.118)\n AXButton \"Cancel\" (0.101, 0.473, 0.300, 0.071)\n AXButton \"Open\" (0.418, 0.473, 0.300, 0.071)\n AXAdjustable \"Horizontal scroll bar, 1 page\" value=\"0%\" (0.067, 0.519, 0.687, 0.044)",
|
||||
"source": "ax-service",
|
||||
"hint": "This simulator was not booted through argent, so system dialogs and native modals may not appear in this tree; everything else reads normally. If something you expect is missing, boot-device with force=true reboots the simulator with the full accessibility settings"
|
||||
}
|
||||
@@ -0,0 +1,117 @@
|
||||
{
|
||||
"devices": [
|
||||
{
|
||||
"platform": "ios",
|
||||
"udid": "404F2659-7202-4450-8465-912BD2AB744B",
|
||||
"name": "iPhone 17",
|
||||
"state": "Booted",
|
||||
"runtime": "com.apple.CoreSimulator.SimRuntime.iOS-26-5",
|
||||
"runtimeKind": "mobile"
|
||||
},
|
||||
{
|
||||
"platform": "ios",
|
||||
"udid": "13145DF8-2591-4879-8B4E-0EE52E38B9DC",
|
||||
"name": "Apple TV 4K (3rd generation)",
|
||||
"state": "Shutdown",
|
||||
"runtime": "com.apple.CoreSimulator.SimRuntime.tvOS-26-5",
|
||||
"runtimeKind": "tv"
|
||||
},
|
||||
{
|
||||
"platform": "ios",
|
||||
"udid": "9F874416-F37E-49D4-BE9F-D03A61447F37",
|
||||
"name": "Apple TV 4K (3rd generation) (at 1080p)",
|
||||
"state": "Shutdown",
|
||||
"runtime": "com.apple.CoreSimulator.SimRuntime.tvOS-26-5",
|
||||
"runtimeKind": "tv"
|
||||
},
|
||||
{
|
||||
"platform": "ios",
|
||||
"udid": "AA581E94-E134-4DEC-8D68-A80C02932E86",
|
||||
"name": "Apple TV",
|
||||
"state": "Shutdown",
|
||||
"runtime": "com.apple.CoreSimulator.SimRuntime.tvOS-26-5",
|
||||
"runtimeKind": "tv"
|
||||
},
|
||||
{
|
||||
"platform": "ios",
|
||||
"udid": "7166D6B3-15EA-485E-B233-D4CF5AA1A9E6",
|
||||
"name": "iPhone 17 Pro",
|
||||
"state": "Shutdown",
|
||||
"runtime": "com.apple.CoreSimulator.SimRuntime.iOS-26-5",
|
||||
"runtimeKind": "mobile"
|
||||
},
|
||||
{
|
||||
"platform": "ios",
|
||||
"udid": "65AF775B-D9DC-4293-88B6-7862868B66BC",
|
||||
"name": "iPhone 17 Pro Max",
|
||||
"state": "Shutdown",
|
||||
"runtime": "com.apple.CoreSimulator.SimRuntime.iOS-26-5",
|
||||
"runtimeKind": "mobile"
|
||||
},
|
||||
{
|
||||
"platform": "ios",
|
||||
"udid": "65D86638-6B23-47AB-A60B-B152A3E5FBEC",
|
||||
"name": "iPhone 17e",
|
||||
"state": "Shutdown",
|
||||
"runtime": "com.apple.CoreSimulator.SimRuntime.iOS-26-5",
|
||||
"runtimeKind": "mobile"
|
||||
},
|
||||
{
|
||||
"platform": "ios",
|
||||
"udid": "A690C59A-DE62-467C-9A93-6B9C81BE7859",
|
||||
"name": "iPhone Air",
|
||||
"state": "Shutdown",
|
||||
"runtime": "com.apple.CoreSimulator.SimRuntime.iOS-26-5",
|
||||
"runtimeKind": "mobile"
|
||||
},
|
||||
{
|
||||
"platform": "ios",
|
||||
"udid": "9D7FC73C-7A12-4BCF-83C2-9B52ACF9859D",
|
||||
"name": "iPad Pro 13-inch (M5)",
|
||||
"state": "Shutdown",
|
||||
"runtime": "com.apple.CoreSimulator.SimRuntime.iOS-26-5",
|
||||
"runtimeKind": "mobile"
|
||||
},
|
||||
{
|
||||
"platform": "ios",
|
||||
"udid": "E71C61D3-8D9F-4591-8511-8FE65229C790",
|
||||
"name": "iPad Pro 11-inch (M5)",
|
||||
"state": "Shutdown",
|
||||
"runtime": "com.apple.CoreSimulator.SimRuntime.iOS-26-5",
|
||||
"runtimeKind": "mobile"
|
||||
},
|
||||
{
|
||||
"platform": "ios",
|
||||
"udid": "ED9D983B-1AA4-4648-8EED-CDCD5327B8D6",
|
||||
"name": "iPad mini (A17 Pro)",
|
||||
"state": "Shutdown",
|
||||
"runtime": "com.apple.CoreSimulator.SimRuntime.iOS-26-5",
|
||||
"runtimeKind": "mobile"
|
||||
},
|
||||
{
|
||||
"platform": "ios",
|
||||
"udid": "9C0DF431-D699-4862-8CF3-264CA044F515",
|
||||
"name": "iPad Air 13-inch (M4)",
|
||||
"state": "Shutdown",
|
||||
"runtime": "com.apple.CoreSimulator.SimRuntime.iOS-26-5",
|
||||
"runtimeKind": "mobile"
|
||||
},
|
||||
{
|
||||
"platform": "ios",
|
||||
"udid": "B92DDF42-5EB6-47F1-A1E7-2B3F2CE2CA84",
|
||||
"name": "iPad Air 11-inch (M4)",
|
||||
"state": "Shutdown",
|
||||
"runtime": "com.apple.CoreSimulator.SimRuntime.iOS-26-5",
|
||||
"runtimeKind": "mobile"
|
||||
},
|
||||
{
|
||||
"platform": "ios",
|
||||
"udid": "44804797-154C-40DB-8559-342C3F95477A",
|
||||
"name": "iPad (A16)",
|
||||
"state": "Shutdown",
|
||||
"runtime": "com.apple.CoreSimulator.SimRuntime.iOS-26-5",
|
||||
"runtimeKind": "mobile"
|
||||
}
|
||||
],
|
||||
"avds": []
|
||||
}
|
||||
|
After Width: | Height: | Size: 215 KiB |
|
After Width: | Height: | Size: 167 KiB |
|
After Width: | Height: | Size: 131 KiB |
|
After Width: | Height: | Size: 619 KiB |
@@ -67,6 +67,7 @@ export async function fixture(t, provider, { docsOnly = false, unresolvedParamet
|
||||
await put('eas.json', JSON.stringify({ build: { capture: { ios: { simulator: true }, android: { buildType: 'apk', distribution: 'internal' } } } }));
|
||||
const registration = names => `import {createNativeStackNavigator} from '@react-navigation/native-stack';
|
||||
import {createStaticNavigation} from '@react-navigation/native';
|
||||
|
||||
${names.map(name => `import ${name} from './${name}';`).join('\n')}
|
||||
const Root=createNativeStackNavigator({screens:{${names.map(name => `${name}:{screen:${name},linking:'${name.toLowerCase()}'}`).join(',')}}});
|
||||
const Navigation=createStaticNavigation(Root); export default function App(){return <Navigation/>;}`;
|
||||
@@ -114,7 +115,7 @@ const Navigation=createStaticNavigation(Root); export default function App(){ret
|
||||
const sleep = milliseconds => { clockMs += milliseconds; };
|
||||
const runner = request => {
|
||||
requests.push(request);
|
||||
if (basename(request.command) === 'agent-device') clockMs += 600;
|
||||
if (/^agent-device(-|$)/.test(basename(request.command))) clockMs += 600;
|
||||
if (request.command === 'git') { const result = spawnSync('git', request.args, { cwd: request.cwd, encoding: 'utf8', env: request.environment }); assert.equal(result.status, 0); return { stdout: result.stdout, stderr: result.stderr }; }
|
||||
const command = request.args[0];
|
||||
if (basename(request.command) === 'eas') {
|
||||
@@ -154,7 +155,7 @@ const Navigation=createStaticNavigation(Root); export default function App(){ret
|
||||
mkdirSync(value(request, '--output'));
|
||||
return { stdout: '', stderr: '' };
|
||||
}
|
||||
if (basename(request.command) === 'agent-device') {
|
||||
if (/^agent-device(-|$)/.test(basename(request.command))) {
|
||||
// Base and head capture in parallel, each on its own simulator: a request names its session in the daemon URL,
|
||||
// so the route, appearance and build it sees are that session's, not whichever session started last.
|
||||
const device = sessions.get(/\/([^/]+)$/.exec(request.environment?.AGENT_DEVICE_DAEMON_BASE_URL ?? '')?.[1]) ?? sessions.get(currentSession) ?? idleDevice;
|
||||
|
||||
@@ -0,0 +1,543 @@
|
||||
import assert from "node:assert/strict";
|
||||
import { readFileSync } from "node:fs";
|
||||
import test from "node:test";
|
||||
import { tsImport } from "tsx/esm/api";
|
||||
|
||||
const { PNG } = await import("pngjs");
|
||||
const { ArgentCallError, describedButton, findOpenButton, iosRuntimeVersion, openInAppPromptShowing, parseCommand, runBridgeCommand, snapshotFromTree } = await tsImport("../../src/capture/argent-driver.ts", import.meta.url);
|
||||
|
||||
const fixture = name => JSON.parse(readFileSync(new URL(`../fixtures/argent-0.29/${name}`, import.meta.url), "utf8"));
|
||||
const IOS_HOME = fixture("fixture-ios-ui-tree-home.json");
|
||||
const IOS_RENAME = fixture("fixture-ios-ui-tree-rename.json");
|
||||
const ANDROID_HOME = fixture("fixture-android-ui-tree-home.json");
|
||||
const ANDROID_RENAME = fixture("fixture-android-ui-tree-rename.json");
|
||||
const IOS_DEVICES = fixture("list-devices.out");
|
||||
// iOS 27.1 on iPhone Duo: the link prompt is up, SpringBoard is in front, and alertVisible is false.
|
||||
const DUO_PROMPT = fixture("fixture-ios27-duo-open-prompt-ui-tree.json");
|
||||
const DUO_PROMPT_DESCRIBE = fixture("fixture-ios27-duo-open-prompt-describe.json");
|
||||
const DUO_HOME = fixture("fixture-ios27-duo-home-ui-tree.json");
|
||||
// iPhone Duo opened (the inner display), Edit Lane sheet up: Argent reports the app root as the screen's top-left third.
|
||||
const DUO_OPEN_EDIT_LANE = fixture("fixture-ios27-duo-open-edit-lane-ui-tree.json");
|
||||
const DUO_DEVICES = { devices: [{ platform: "ios", udid: "74195B53-4DBC-4EAA-9991-F98E5BB86BA8", name: "iPhone Duo", state: "Booted", runtime: "com.apple.CoreSimulator.SimRuntime.iOS-27-1", runtimeKind: "mobile" }] };
|
||||
const ANDROID_DEVICES = { devices: [{ platform: "android", serial: "emulator-5554", state: "device", isEmulator: true, model: "sdk_gphone64_x86_64", avdName: "pixel_7", sdkLevel: 36, runtimeKind: "mobile" }], avds: [] };
|
||||
const BUNDLE = "dev.brent.euxy";
|
||||
const UDID = "404F2659-7202-4450-8465-912BD2AB744B";
|
||||
|
||||
/** A scripted tool-server: each tool answers from `answers` (a value, a function of the args, or a queue of either). */
|
||||
function harness(platform, answers, options = {}) {
|
||||
const calls = [];
|
||||
const moves = [];
|
||||
const queues = Object.fromEntries(Object.entries(answers).map(([tool, answer]) => [tool, Array.isArray(answer) ? [...answer] : answer]));
|
||||
const context = {
|
||||
platform, version: "0.29.0", state: options.state ?? { generation: 0 }, ...(options.bundleId ? { bundleId: options.bundleId } : {}),
|
||||
sleep: async () => {},
|
||||
reachable: async () => options.reachable ?? true,
|
||||
moveFile: async (from, to) => { moves.push([from, to]); },
|
||||
call: async (tool, args, callOptions) => {
|
||||
calls.push({ tool, args, ...(callOptions ? { options: callOptions } : {}) });
|
||||
let answer = queues[tool];
|
||||
if (Array.isArray(answer)) answer = answer.length > 1 ? answer.shift() : answer[0];
|
||||
if (answer === undefined) throw new Error(`unexpected tool ${tool}`);
|
||||
const value = typeof answer === "function" ? answer(args) : answer;
|
||||
if (value instanceof Error) throw value;
|
||||
return structuredClone(value);
|
||||
},
|
||||
};
|
||||
return { calls, moves, context, run: argv => runBridgeCommand(argv, context).then(result => ({ ...result, json: result.stdout.trim().startsWith("{") ? JSON.parse(result.stdout) : result.stdout })) };
|
||||
}
|
||||
|
||||
const flags = (platform, extra = []) => [...extra, "--session", "expo-explore-runtime", ...(platform === "ios" ? ["--device", "iPhone 17"] : []), "--platform", platform, "--json"];
|
||||
const flatten = tree => { const out = []; const walk = node => { out.push(node); (node.children ?? []).forEach(walk); }; (tree.roots ?? []).forEach(walk); return out; };
|
||||
|
||||
test("parseCommand separates agent-device's trailing flags from positionals and keeps text after --", () => {
|
||||
assert.deepEqual(parseCommand(["e3", "--session", "s", "--device", "iPhone 17", "--platform", "ios", "--json", "--", "-h", "--json"]),
|
||||
{ positional: ["e3", "-h", "--json"], flags: { session: "s", device: "iPhone 17", platform: "ios", json: true } });
|
||||
});
|
||||
|
||||
test("iosRuntimeVersion reads the OS version from a CoreSimulator runtime id", () => {
|
||||
assert.equal(iosRuntimeVersion("com.apple.CoreSimulator.SimRuntime.iOS-26-5"), "26.5");
|
||||
assert.equal(iosRuntimeVersion("com.apple.CoreSimulator.SimRuntime.iOS-18-0-1"), "18.0.1");
|
||||
assert.equal(iosRuntimeVersion("com.apple.CoreSimulator.SimRuntime.tvOS-26-5"), undefined);
|
||||
});
|
||||
|
||||
test("--version answers with the pinned Argent version without calling Argent", async () => {
|
||||
const { run, calls } = harness("ios", {});
|
||||
assert.equal((await run(["--version"])).stdout, "0.29.0\n");
|
||||
assert.equal(calls.length, 0);
|
||||
});
|
||||
|
||||
test("an iOS snapshot is agent-device's shape: points, the app root, the observer, and no duplicate nodes", () => {
|
||||
const { nodes, refs, screen } = snapshotFromTree(IOS_HOME, "ios", 1, BUNDLE);
|
||||
assert.deepEqual(screen, { width: 402, height: 874 });
|
||||
assert.equal(nodes[0].type, "Application");
|
||||
assert.deepEqual(nodes[0].rect, { x: 0, y: 0, width: 402, height: 874 });
|
||||
assert.equal(nodes[0].hittable, false);
|
||||
for (const [index, node] of nodes.entries()) {
|
||||
assert.equal(node.index, index);
|
||||
assert.equal(node.ref, `e${index + 1}`);
|
||||
assert.ok(refs[node.ref]);
|
||||
if (index > 0) assert.ok(node.parentIndex < index, "a parent comes before its children");
|
||||
assert.ok(node.rect.x < 402 && node.rect.y < 874 && node.rect.x + node.rect.width > 0 && node.rect.y + node.rect.height > 0, "only on-screen nodes");
|
||||
}
|
||||
const observer = nodes.find(node => node.identifier === "expo-explore-observer");
|
||||
assert.ok(observer, "the capture observer is in the tree");
|
||||
assert.equal(JSON.parse(observer.label).pathname, "/");
|
||||
const keys = nodes.map(node => JSON.stringify([node.type, node.label, node.identifier, node.value, Object.values(node.rect).map(Math.round)]));
|
||||
assert.equal(new Set(keys).size, keys.length, "iOS AX duplicates appear once");
|
||||
assert.ok(nodes.length < flatten(IOS_HOME).length);
|
||||
assert.ok(nodes.some(node => node.type === "Button" && node.identifier === "lane-row-title-0"));
|
||||
});
|
||||
|
||||
test("an Android snapshot keeps pixels, drops the system UI root, and names widgets as agent-device does", () => {
|
||||
const { nodes, screen } = snapshotFromTree(ANDROID_HOME, "android", 1, BUNDLE);
|
||||
assert.deepEqual(screen, { width: 720, height: 1600 });
|
||||
assert.equal(nodes[0].type, "Application");
|
||||
assert.deepEqual(nodes[0].rect, { x: 0, y: 0, width: 720, height: 1600 });
|
||||
assert.ok(!nodes.some(node => /^android\.widget\./.test(node.type)), "widget classes are simplified");
|
||||
assert.ok(nodes.some(node => node.identifier === "expo-explore-observer"));
|
||||
const systemUi = flatten({ roots: ANDROID_HOME.roots.filter(root => root.bundleId === "com.android.systemui") })
|
||||
.map(node => node.label ?? node.contentDescription).filter(Boolean);
|
||||
for (const label of systemUi) assert.ok(!nodes.some(node => node.label === label && node.depth === 0), `system UI root is left out (${label})`);
|
||||
assert.ok(nodes.filter(node => node.depth === 0).length === 1);
|
||||
});
|
||||
|
||||
test("snapshot pins refs to its generation and reports the foreground app; press resolves a ref to the element's centre", async () => {
|
||||
const { run, calls, context } = harness("ios", { "list-devices": IOS_DEVICES, "ui-tree": IOS_HOME, "gesture-tap": {} });
|
||||
const snapshot = await run(["snapshot", ...flags("ios", ["--force-full", "--level", "full"])]);
|
||||
assert.equal(snapshot.exitCode, 0);
|
||||
assert.equal(snapshot.json.data.refsGeneration, 1);
|
||||
assert.equal(snapshot.json.data.appBundleId, BUNDLE);
|
||||
assert.equal(snapshot.json.data.truncated, false);
|
||||
assert.equal(context.state.udid, UDID);
|
||||
assert.equal(context.state.model, "iPhone 17");
|
||||
assert.equal(context.state.osVersion, "26.5");
|
||||
const target = snapshot.json.data.nodes.find(node => node.identifier === "lane-row-title-0");
|
||||
const pressed = await run(["press", `@${target.ref}`, ...flags("ios")]);
|
||||
assert.equal(pressed.exitCode, 0);
|
||||
const tap = calls.at(-1);
|
||||
assert.equal(tap.tool, "gesture-tap");
|
||||
assert.equal(tap.args.udid, UDID);
|
||||
assert.ok(Math.abs(tap.args.x - (target.rect.x + target.rect.width / 2) / 402) < 1e-9);
|
||||
assert.ok(Math.abs(tap.args.y - (target.rect.y + target.rect.height / 2) / 874) < 1e-9);
|
||||
|
||||
const stale = await run(["press", `${target.ref}~s0`, ...flags("ios")]);
|
||||
assert.equal(stale.exitCode, 1);
|
||||
assert.match(stale.json.error.message, /stale/);
|
||||
});
|
||||
|
||||
test("press with coordinates normalizes Android pixels", async () => {
|
||||
const { run, calls } = harness("android", { "list-devices": ANDROID_DEVICES, "ui-tree": ANDROID_HOME, "gesture-tap": {} });
|
||||
assert.equal((await run(["press", "360", "400", ...flags("android")])).exitCode, 0);
|
||||
assert.deepEqual(calls.at(-1), { tool: "gesture-tap", args: { udid: "emulator-5554", x: 0.5, y: 0.25 } });
|
||||
});
|
||||
|
||||
test("open relaunches the app until its tree is readable and answers with agent-device's open envelope", async () => {
|
||||
const empty = { ...IOS_HOME, roots: [{ type: "Other", frame: { x: 0, y: 0, width: 1, height: 1 } }] };
|
||||
const { run, calls } = harness("ios", { "list-devices": IOS_DEVICES, "restart-app": {}, "ui-tree": [empty, empty, IOS_HOME] });
|
||||
const opened = await run(["open", BUNDLE, ...flags("ios", ["--level", "full"])]);
|
||||
assert.equal(opened.exitCode, 0);
|
||||
assert.deepEqual(opened.json.data.device, { platform: "ios", target: "mobile", name: "iPhone 17", id: UDID, osVersion: "26.5" });
|
||||
assert.equal(opened.json.data.appBundleId, BUNDLE);
|
||||
assert.equal(opened.json.data.session, "expo-explore-runtime");
|
||||
assert.deepEqual(opened.json.data.identifiers, { session: "expo-explore-runtime", appBundleId: BUNDLE, deviceName: "iPhone 17", deviceId: UDID });
|
||||
assert.deepEqual(calls.filter(call => call.tool === "restart-app").map(call => call.args), [{ udid: UDID, bundleId: BUNDLE }]);
|
||||
});
|
||||
|
||||
test("open fails clearly when the app never shows a tree", async () => {
|
||||
const empty = { ...IOS_HOME, roots: [] };
|
||||
const { run, calls } = harness("ios", { "list-devices": IOS_DEVICES, "restart-app": {}, "ui-tree": empty });
|
||||
const opened = await run(["open", BUNDLE, ...flags("ios")]);
|
||||
assert.equal(opened.exitCode, 1);
|
||||
assert.equal(opened.json.error.code, "APP_NOT_READY");
|
||||
assert.equal(calls.filter(call => call.tool === "restart-app").length, 2);
|
||||
});
|
||||
|
||||
test("a session with no single booted device is refused", async () => {
|
||||
const none = { devices: IOS_DEVICES.devices.map(device => ({ ...device, state: "Shutdown" })) };
|
||||
const { run } = harness("ios", { "list-devices": none });
|
||||
const result = await run(["snapshot", ...flags("ios")]);
|
||||
assert.equal(result.json.error.code, "DEVICE_UNAVAILABLE");
|
||||
});
|
||||
|
||||
test("the first iOS deep link accepts the Open prompt once; later links open directly", async () => {
|
||||
// iOS 26.5 flags the prompt as an alert; its text is what identifies it as the link prompt.
|
||||
const prompt = { ...IOS_HOME, alertVisible: true, foregroundApp: "com.apple.springboard",
|
||||
roots: [...IOS_HOME.roots, { type: "Alert", label: "Open in “euxy”?", frame: { x: 0.1, y: 0.4, width: 0.8, height: 0.2 }, children: [] }] };
|
||||
const { run, calls, context } = harness("ios", { "list-devices": IOS_DEVICES, "open-url": {}, "gesture-tap": {}, "ui-tree": [prompt, IOS_HOME] });
|
||||
const first = await run(["open", BUNDLE, "euxy://settings", ...flags("ios")]);
|
||||
assert.equal(first.exitCode, 0);
|
||||
const tap = calls.find(call => call.tool === "gesture-tap");
|
||||
assert.ok(Math.abs(tap.args.x - (0.5 + 74 / 402)) < 1e-9 && Math.abs(tap.args.y - (0.5 + 37 / 874)) < 1e-9);
|
||||
assert.equal(context.state.deepLinkPromptAccepted, true);
|
||||
const before = calls.length;
|
||||
assert.equal((await run(["open", "euxy://patterns", ...flags("ios")])).exitCode, 0);
|
||||
assert.deepEqual(calls.slice(before).map(call => call.tool), ["open-url"]);
|
||||
});
|
||||
|
||||
test("iOS fill taps the field, erases its text with backspaces, types, and checks the result", async () => {
|
||||
const field = flatten(IOS_RENAME).find(node => node.type === "TextField" && node.frame);
|
||||
assert.ok(field, "the rename fixture has a text field");
|
||||
const typed = structuredClone(IOS_RENAME);
|
||||
flatten(typed).find(node => node.type === "TextField" && node.frame).value = "Groove";
|
||||
const { run, calls } = harness("ios", { "list-devices": IOS_DEVICES, "ui-tree": [IOS_RENAME, typed], "gesture-tap": {}, "run-sequence": {}, keyboard: {} });
|
||||
const snapshot = await run(["snapshot", ...flags("ios")]);
|
||||
const node = snapshot.json.data.nodes.find(item => item.type === "TextField");
|
||||
const filled = await run(["fill", node.ref, ...flags("ios"), "--", "Groove"]);
|
||||
assert.equal(filled.exitCode, 0, filled.stdout);
|
||||
const tools = calls.slice(2).map(call => call.tool);
|
||||
assert.equal(tools[0], "gesture-tap");
|
||||
const erase = (field.value ?? "").length;
|
||||
if (erase) {
|
||||
const sequence = calls.find(call => call.tool === "run-sequence");
|
||||
assert.equal(sequence.args.steps.length, erase);
|
||||
assert.deepEqual(sequence.args.steps[0], { tool: "keyboard", args: { udid: UDID, key: "backspace" } });
|
||||
}
|
||||
assert.deepEqual(calls.find(call => call.tool === "keyboard").args, { udid: UDID, text: "Groove" });
|
||||
assert.ok(!calls.some(call => call.tool === "fill"), "Argent's iOS fill is not used");
|
||||
});
|
||||
|
||||
test("Android fill uses Argent's fill and requires it to verify the text", async () => {
|
||||
const { run, calls } = harness("android", { "list-devices": ANDROID_DEVICES, "ui-tree": ANDROID_RENAME, "gesture-tap": {}, fill: [{ verified: true }, { verified: false }] });
|
||||
const snapshot = await run(["snapshot", ...flags("android")]);
|
||||
const node = snapshot.json.data.nodes.find(item => item.type === "TextField");
|
||||
assert.ok(node, "the rename fixture has an EditText");
|
||||
assert.equal((await run(["fill", node.ref, ...flags("android"), "--", "Groove"])).exitCode, 0);
|
||||
assert.deepEqual(calls.find(call => call.tool === "fill").args, { udid: "emulator-5554", text: "Groove" });
|
||||
const unverified = await run(["fill", node.ref, ...flags("android"), "--", "Groove"]);
|
||||
assert.equal(unverified.exitCode, 1);
|
||||
});
|
||||
|
||||
test("text with a {{secret:…}} placeholder never reaches Argent", async () => {
|
||||
const { run, calls } = harness("ios", { "list-devices": IOS_DEVICES, keyboard: {} });
|
||||
const typed = await run(["type", ...flags("ios"), "--", "{{secret:PASSWORD}}"]);
|
||||
assert.equal(typed.json.error.code, "INVALID_ARGS");
|
||||
assert.ok(!calls.some(call => call.tool === "keyboard"));
|
||||
});
|
||||
|
||||
test("keyboard dismiss matches agent-device: Android presses back; iOS taps a dismiss key or reports it could not", async () => {
|
||||
const android = harness("android", { "list-devices": ANDROID_DEVICES, "ui-tree": [{ ...ANDROID_RENAME, keyboardVisible: true }, { ...ANDROID_RENAME, keyboardVisible: false }], button: {} });
|
||||
const dismissed = await android.run(["keyboard", "dismiss", ...flags("android")]);
|
||||
assert.deepEqual(dismissed.json.data, { platform: "android", action: "dismiss", wasVisible: true, dismissed: true, visible: false });
|
||||
assert.deepEqual(android.calls.find(call => call.tool === "button").args, { udid: "emulator-5554", button: "back" });
|
||||
|
||||
// agent-device fails with this message when the keyboard has no dismiss key, and callers fall back to the return key.
|
||||
const noKey = harness("ios", { "list-devices": IOS_DEVICES, "ui-tree": { ...IOS_HOME, keyboardVisible: true } });
|
||||
const failed = await noKey.run(["keyboard", "dismiss", ...flags("ios")]);
|
||||
assert.equal(failed.exitCode, 1);
|
||||
assert.match(failed.json.error.message, /^Unable to dismiss the iOS keyboard/);
|
||||
|
||||
const hidden = harness("ios", { "list-devices": IOS_DEVICES, "ui-tree": IOS_HOME });
|
||||
assert.equal((await hidden.run(["keyboard", "dismiss", ...flags("ios")])).json.data.wasVisible, false);
|
||||
});
|
||||
|
||||
test("iOS back with no navigation bar back control fails with agent-device's message", async () => {
|
||||
const { run } = harness("ios", { "list-devices": IOS_DEVICES, "ui-tree": IOS_HOME });
|
||||
const back = await run(["back", ...flags("ios")]);
|
||||
assert.equal(back.exitCode, 1);
|
||||
assert.equal(back.json.error.message, "in-app back control is not available");
|
||||
});
|
||||
|
||||
test("alerts read and answer in each platform's agent-device shape", async () => {
|
||||
const noAlert = harness("ios", { "list-devices": IOS_DEVICES, "ui-tree": IOS_HOME });
|
||||
assert.equal((await noAlert.run(["alert", "get", ...flags("ios")])).json.error.message, "alert not found");
|
||||
const androidNone = harness("android", { "list-devices": ANDROID_DEVICES, "ui-tree": ANDROID_HOME });
|
||||
assert.deepEqual((await androidNone.run(["alert", "get", ...flags("android")])).json.data, { platform: "android", alert: null });
|
||||
|
||||
const alertTree = { ...IOS_HOME, alertVisible: true, roots: [{ type: "Alert", label: "Allow?", frame: { x: 0.1, y: 0.4, width: 0.8, height: 0.2 }, children: [
|
||||
{ type: "StaticText", label: "Allow notifications?", frame: { x: 0.1, y: 0.4, width: 0.8, height: 0.05 } },
|
||||
{ type: "Button", label: "Don’t Allow", frame: { x: 0.1, y: 0.55, width: 0.4, height: 0.05 } },
|
||||
{ type: "Button", label: "Allow", frame: { x: 0.5, y: 0.55, width: 0.4, height: 0.05 } }] }] };
|
||||
const ios = harness("ios", { "list-devices": IOS_DEVICES, "ui-tree": [alertTree, alertTree, IOS_HOME], "gesture-tap": {} });
|
||||
assert.deepEqual((await ios.run(["alert", "get", ...flags("ios")])).json.data, { message: "Allow notifications?", items: ["Don’t Allow", "Allow"] });
|
||||
const accepted = await ios.run(["alert", "accept", ...flags("ios")]);
|
||||
assert.deepEqual(accepted.json.data, { action: "accept", button: "Allow" });
|
||||
const tap = ios.calls.find(call => call.tool === "gesture-tap");
|
||||
assert.ok(Math.abs(tap.args.x - 0.7) < 1e-9 && Math.abs(tap.args.y - 0.575) < 1e-9);
|
||||
});
|
||||
|
||||
test("screenshots download at full resolution to the requested path", async () => {
|
||||
const { run, calls } = harness("ios", { "list-devices": IOS_DEVICES, screenshot: {} });
|
||||
assert.deepEqual((await run(["screenshot", "/tmp/out.png", ...flags("ios")])).json.data, { path: "/tmp/out.png" });
|
||||
assert.deepEqual(calls.at(-1), { tool: "screenshot", args: { udid: UDID, scale: 1 }, options: { out: "/tmp/out.png" } });
|
||||
});
|
||||
|
||||
test("a recording is moved from where the Argent client downloaded it to the path Explore asked for", async () => {
|
||||
const { run, moves, context } = harness("android", { "list-devices": ANDROID_DEVICES, "screen-recording-start": {}, "screen-recording-stop": { video: "/home/.argent/recordings/r.mp4", durationMs: 4200 } });
|
||||
assert.equal((await run(["record", "start", "/work/launch.mp4", ...flags("android")])).exitCode, 0);
|
||||
assert.equal(context.state.recording, "/work/launch.mp4");
|
||||
const stopped = await run(["record", "stop", ...flags("android")]);
|
||||
assert.deepEqual(stopped.json.data, { outPath: "/work/launch.mp4", durationMs: 4200 });
|
||||
assert.deepEqual(moves, [["/home/.argent/recordings/r.mp4", "/work/launch.mp4"]]);
|
||||
assert.equal(context.state.recording, undefined);
|
||||
});
|
||||
|
||||
test("install reinstalls the archive under the bundle id the caller names", async () => {
|
||||
const { run, calls } = harness("ios", { "list-devices": IOS_DEVICES, "reinstall-app": {} }, { bundleId: BUNDLE });
|
||||
assert.deepEqual((await run(["install", "/work/bundle/euxy.app", ...flags("ios")])).json.data, { installed: true, appBundleId: BUNDLE });
|
||||
assert.deepEqual(calls.at(-1).args, { udid: UDID, bundleId: BUNDLE, appPath: "/work/bundle/euxy.app" });
|
||||
const missing = harness("ios", { "list-devices": IOS_DEVICES, "reinstall-app": {} });
|
||||
assert.equal((await missing.run(["install", "/work/a.app", ...flags("ios")])).json.error.code, "INVALID_ARGS");
|
||||
});
|
||||
|
||||
test("appearance and logs are reported as unsupported, not silently ignored", async () => {
|
||||
const { run } = harness("ios", {});
|
||||
assert.equal((await run(["settings", "appearance", "dark", ...flags("ios")])).json.error.code, "CONTROLLER_UNSUPPORTED");
|
||||
assert.equal((await run(["logs", "path", ...flags("ios")])).json.error.code, "CONTROLLER_UNSUPPORTED");
|
||||
});
|
||||
|
||||
test("a tool-server that is still starting is waited for before the action is sent", async () => {
|
||||
const { run, calls, context } = harness("ios", { "list-devices": IOS_DEVICES, "ui-tree": IOS_HOME, "gesture-tap": {} });
|
||||
const answers = [false, false, false, true];
|
||||
context.reachable = async () => answers.shift() ?? true;
|
||||
assert.equal((await run(["press", "10", "10", ...flags("ios")])).exitCode, 0);
|
||||
assert.equal(calls.filter(call => call.tool === "gesture-tap").length, 1);
|
||||
});
|
||||
|
||||
test("an unreachable tool-server before a UI action is the retryable 'Remote daemon is unavailable'", async () => {
|
||||
const { run, calls } = harness("ios", { "list-devices": IOS_DEVICES, "ui-tree": IOS_HOME, "gesture-tap": {} }, { reachable: false });
|
||||
const pressed = await run(["press", "10", "10", ...flags("ios")]);
|
||||
assert.deepEqual(pressed.json.error, { code: "COMMAND_FAILED", message: "Remote daemon is unavailable" });
|
||||
assert.ok(!calls.some(call => call.tool === "gesture-tap"));
|
||||
});
|
||||
|
||||
test("a UI action whose answer is lost is reported once and never retried", async () => {
|
||||
const { run, calls } = harness("ios", { "list-devices": IOS_DEVICES, "ui-tree": IOS_HOME, "gesture-tap": new ArgentCallError("argent run gesture-tap failed: socket hang up", true) });
|
||||
const pressed = await run(["press", "10", "10", ...flags("ios")]);
|
||||
assert.equal(pressed.json.error.code, "ARGENT_TOOL_FAILED");
|
||||
assert.notEqual(pressed.json.error.message, "Remote daemon is unavailable");
|
||||
assert.equal(calls.filter(call => call.tool === "gesture-tap").length, 1);
|
||||
});
|
||||
|
||||
test("reads are retried after a transport failure", async () => {
|
||||
const { run, calls } = harness("ios", { "list-devices": IOS_DEVICES, "ui-tree": [new ArgentCallError("timeout", true), IOS_HOME] });
|
||||
assert.equal((await run(["snapshot", ...flags("ios")])).exitCode, 0);
|
||||
assert.equal(calls.filter(call => call.tool === "ui-tree").length, 2);
|
||||
});
|
||||
|
||||
test("wait stable maps to await-screen-idle", async () => {
|
||||
const { run, calls } = harness("android", { "list-devices": ANDROID_DEVICES, "await-screen-idle": { settled: true } });
|
||||
assert.deepEqual((await run(["wait", "stable", "700", "5000", ...flags("android")])).json.data, { stable: true });
|
||||
assert.deepEqual(calls.at(-1).args, { udid: "emulator-5554", minStableMs: 700, timeoutMs: 5000 });
|
||||
});
|
||||
|
||||
test("iOS 27.1's link prompt is recognized by its text when Argent does not flag it as an alert", () => {
|
||||
assert.equal(DUO_PROMPT.alertVisible, false);
|
||||
assert.equal(openInAppPromptShowing(DUO_PROMPT), true);
|
||||
assert.equal(openInAppPromptShowing(DUO_HOME), false);
|
||||
assert.equal(openInAppPromptShowing(IOS_HOME), false);
|
||||
});
|
||||
|
||||
test("describe locates the prompt's Open button where it is on screen", () => {
|
||||
assert.deepEqual(describedButton(DUO_PROMPT_DESCRIBE.description, "Open"), { x: 0.418, y: 0.473, width: 0.3, height: 0.071 });
|
||||
assert.equal(describedButton(DUO_PROMPT_DESCRIBE.description, "Allow"), undefined);
|
||||
assert.equal(describedButton(undefined, "Open"), undefined);
|
||||
});
|
||||
|
||||
test("on iPhone Duo the first link taps Open where describe puts it, not at iPhone 17's offset", async () => {
|
||||
const { run, calls, context } = harness("ios", { "list-devices": DUO_DEVICES, "open-url": {}, "gesture-tap": {}, describe: DUO_PROMPT_DESCRIBE, "ui-tree": [DUO_PROMPT, DUO_HOME] });
|
||||
const opened = await run(["open", "dev.brent.euxy", "euxy://", ...flags("ios")]);
|
||||
assert.equal(opened.exitCode, 0, opened.stdout);
|
||||
const tap = calls.find(call => call.tool === "gesture-tap");
|
||||
assert.ok(Math.abs(tap.args.x - (0.418 + 0.15)) < 1e-9 && Math.abs(tap.args.y - (0.473 + 0.0355)) < 1e-9, JSON.stringify(tap.args));
|
||||
assert.equal(context.state.deepLinkPromptAccepted, true);
|
||||
});
|
||||
|
||||
test("a snapshot taken while iOS 27.1's link prompt is up reports it as an alert", async () => {
|
||||
const { run } = harness("ios", { "list-devices": DUO_DEVICES, "ui-tree": DUO_PROMPT });
|
||||
const snapshot = await run(["snapshot", ...flags("ios")]);
|
||||
assert.ok(snapshot.json.data.nodes.some(node => node.type === "Alert"));
|
||||
});
|
||||
|
||||
test("a tool-server that lists no devices on its first call is asked again", async () => {
|
||||
const { run, calls, context } = harness("ios", { "list-devices": [{ devices: [], avds: [] }, DUO_DEVICES], "ui-tree": DUO_HOME });
|
||||
assert.equal((await run(["snapshot", ...flags("ios")])).exitCode, 0);
|
||||
assert.equal(calls.filter(call => call.tool === "list-devices").length, 2);
|
||||
assert.equal(context.state.model, "iPhone Duo");
|
||||
assert.equal(context.state.osVersion, "27.1");
|
||||
});
|
||||
|
||||
test("alert get and accept read iOS 27.1's link prompt and press Open where describe puts it", async () => {
|
||||
const { run, calls } = harness("ios", { "list-devices": DUO_DEVICES, "gesture-tap": {}, describe: DUO_PROMPT_DESCRIBE, "ui-tree": [DUO_PROMPT, DUO_PROMPT, DUO_HOME] });
|
||||
const read = await run(["alert", "get", ...flags("ios")]);
|
||||
assert.deepEqual(read.json.data, { message: "Open in “euxy”?", items: ["Cancel", "Open"] });
|
||||
const accepted = await run(["alert", "accept", ...flags("ios")]);
|
||||
assert.deepEqual(accepted.json.data, { action: "accept", button: "Open" });
|
||||
const tap = calls.find(call => call.tool === "gesture-tap");
|
||||
assert.ok(Math.abs(tap.args.x - 0.568) < 1e-9 && Math.abs(tap.args.y - 0.5085) < 1e-9, JSON.stringify(tap.args));
|
||||
});
|
||||
|
||||
const image = name => PNG.sync.read(readFileSync(new URL(`../fixtures/argent-0.29/${name}`, import.meta.url)));
|
||||
const near = (actual, expected, tolerance = 0.02) => Math.abs(actual - expected) <= tolerance;
|
||||
|
||||
test("the link prompt's Open button is found in iOS 26 and iOS 27.1 screenshots", () => {
|
||||
// iPhone Duo: describe puts Open at (0.418, 0.473, 0.3 × 0.071).
|
||||
const duo = findOpenButton(image("screenshot-ios27-duo-open-prompt.png"));
|
||||
assert.ok(duo && near(duo.x, 0.568) && near(duo.y, 0.5085), JSON.stringify(duo));
|
||||
const iphone17 = findOpenButton(image("screenshot-ios26-iphone17-open-prompt.png"));
|
||||
assert.ok(iphone17 && iphone17.x > 0.5 && iphone17.x < 0.85 && iphone17.y > 0.48 && iphone17.y < 0.6, JSON.stringify(iphone17));
|
||||
});
|
||||
|
||||
test("no Open button is found without the prompt, even with a blue key on screen", () => {
|
||||
assert.equal(findOpenButton(image("screenshot-ios27-duo-no-prompt-small.png")), undefined);
|
||||
assert.equal(findOpenButton(image("screenshot-ios26-keyboard.png")), undefined);
|
||||
});
|
||||
|
||||
test("when Argent reads nothing while the prompt is up, Open is tapped from a screenshot", async () => {
|
||||
const blind = { schemaVersion: 1, source: "ax-service", screen: { width: 466, height: 678 }, roots: [{ role: "AXGroup", children: [] }], truncated: false, alertVisible: false };
|
||||
const frames = [image("screenshot-ios27-duo-open-prompt.png"), image("screenshot-ios27-duo-no-prompt-small.png")];
|
||||
const { run, calls, context } = harness("ios", { "list-devices": DUO_DEVICES, "open-url": {}, "gesture-tap": {}, screenshot: {}, "ui-tree": blind });
|
||||
context.scratchImage = { path: "/work/argent-scratch.png", read: async () => frames.shift() };
|
||||
const opened = await run(["open", "dev.brent.euxy", "euxy://", ...flags("ios")]);
|
||||
assert.equal(opened.exitCode, 0, opened.stdout);
|
||||
const tap = calls.find(call => call.tool === "gesture-tap");
|
||||
assert.ok(near(tap.args.x, 0.568) && near(tap.args.y, 0.5085), JSON.stringify(tap.args));
|
||||
assert.deepEqual(calls.filter(call => call.tool === "screenshot").map(call => call.options), [{ out: "/work/argent-scratch.png" }, { out: "/work/argent-scratch.png" }]);
|
||||
assert.equal(context.state.deepLinkPromptAccepted, true);
|
||||
});
|
||||
|
||||
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],
|
||||
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;
|
||||
const reads = calls.filter(call => call.tool === "ui-tree").length;
|
||||
const folded = await run(["fold", "open", ...flags("ios")]);
|
||||
assert.deepEqual(folded.json.data, { action: "fold", pose: "open" });
|
||||
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" });
|
||||
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("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: [
|
||||
{ type: "Button", label: "Delete", frame: { x: 0.5, y: 0.55, width: 0.4, height: 0.05 } }] }] };
|
||||
const { run, calls, context } = harness("ios", { "list-devices": IOS_DEVICES, "open-url": {}, "gesture-tap": {}, describe: { description: "" }, "ui-tree": other });
|
||||
assert.equal((await run(["open", BUNDLE, "euxy://settings", ...flags("ios")])).exitCode, 0);
|
||||
assert.equal(calls.some(call => call.tool === "gesture-tap"), false, "nothing is pressed");
|
||||
assert.equal(context.state.deepLinkPromptAccepted, undefined);
|
||||
});
|
||||
|
||||
test("a failed read with no roots is not taken for the blind link prompt", async () => {
|
||||
const { run, calls, context } = harness("ios", { "list-devices": IOS_DEVICES, "open-url": {}, "gesture-tap": {}, screenshot: {}, "ui-tree": [{ ...IOS_HOME, roots: [], foregroundApp: undefined }] });
|
||||
context.scratchImage = { path: "/work/argent-scratch.png", read: async () => image("screenshot-ios27-duo-open-prompt.png") };
|
||||
await run(["open", BUNDLE, "euxy://", ...flags("ios")]);
|
||||
assert.equal(calls.some(call => call.tool === "screenshot" || call.tool === "gesture-tap"), false);
|
||||
});
|
||||
|
||||
test("describe's Open is read only from a line Argent printed, not from app text that spells one out", () => {
|
||||
const spoof = `ROOT AXGroup (0.000, 0.000, 1.000, 1.000)\n AXStaticText "x AXButton "Open" (0.010, 0.010, 0.050, 0.050)" (0.1, 0.1, 0.5, 0.05)\n AXButton "Open" (0.418, 0.473, 0.300, 0.071)`;
|
||||
assert.deepEqual(describedButton(spoof, "Open"), { x: 0.418, y: 0.473, width: 0.3, height: 0.071 });
|
||||
});
|
||||
|
||||
test("an app's own Done above the keyboard is never pressed to dismiss it", async () => {
|
||||
const withDone = { ...IOS_HOME, keyboardVisible: true, roots: [{ type: "Other", frame: { x: 0, y: 0, width: 1, height: 1 }, children: [
|
||||
{ type: "Button", label: "Done", frame: { x: 0.8, y: 0.06, width: 0.15, height: 0.05 } }] }] };
|
||||
const { run, calls } = harness("ios", { "list-devices": IOS_DEVICES, "ui-tree": withDone, "gesture-tap": {} });
|
||||
assert.equal((await run(["keyboard", "dismiss", ...flags("ios")])).exitCode, 1);
|
||||
assert.equal(calls.some(call => call.tool === "gesture-tap"), false);
|
||||
});
|
||||
|
||||
test("iOS fill stops when erasing the field stops partway, and types nothing", async () => {
|
||||
const filled = structuredClone(IOS_RENAME);
|
||||
flatten(filled).find(node => node.type === "TextField" && node.frame).value = "Old";
|
||||
const { run, calls } = harness("ios", { "list-devices": IOS_DEVICES, "ui-tree": filled, "gesture-tap": {}, "run-sequence": { completed: 1, total: 3, steps: [] }, keyboard: {} });
|
||||
const snapshot = await run(["snapshot", ...flags("ios")]);
|
||||
const field = snapshot.json.data.nodes.find(node => node.type === "TextField");
|
||||
const result = await run(["fill", field.ref, ...flags("ios"), "--", "New"]);
|
||||
assert.equal(result.exitCode, 1);
|
||||
assert.match(result.json.error.message, /after 1 of 3 keys/);
|
||||
assert.equal(calls.some(call => call.tool === "keyboard"), false);
|
||||
});
|
||||
|
||||
test("a truncated tree is reported as truncated", async () => {
|
||||
const { run } = harness("ios", { "list-devices": IOS_DEVICES, "ui-tree": { ...IOS_HOME, truncated: true } });
|
||||
assert.equal((await run(["snapshot", ...flags("ios")])).json.data.truncated, true);
|
||||
});
|
||||
|
||||
test("Android disabled controls are reported disabled (the recorded rename screen has four)", () => {
|
||||
const { nodes } = snapshotFromTree(ANDROID_RENAME, "android", 1, BUNDLE);
|
||||
const rename = nodes.find(node => node.label === "Rename" && node.type === "Button");
|
||||
assert.ok(rename, "the rename fixture has its Rename button");
|
||||
assert.equal(rename.enabled, false);
|
||||
assert.equal(rename.hittable, false);
|
||||
});
|
||||
|
||||
test("an Android permission dialog from another package stays in the snapshot as an alert", async () => {
|
||||
const dialog = { ...ANDROID_HOME, roots: [...ANDROID_HOME.roots, { type: "android.widget.FrameLayout", bundleId: "com.google.android.permissioncontroller",
|
||||
frame: { x: 0.1, y: 0.35, width: 0.8, height: 0.3 }, children: [
|
||||
{ type: "android.widget.TextView", label: "Allow euxy to send you notifications?", frame: { x: 0.15, y: 0.4, width: 0.7, height: 0.05 } },
|
||||
{ type: "android.widget.Button", label: "Allow", frame: { x: 0.15, y: 0.55, width: 0.7, height: 0.05 } }] }] };
|
||||
const { run } = harness("android", { "list-devices": ANDROID_DEVICES, "ui-tree": dialog });
|
||||
const snapshot = (await run(["snapshot", ...flags("android")])).json.data;
|
||||
assert.ok(snapshot.nodes.some(node => node.type === "Button" && node.label === "Allow"), "the dialog's buttons can be found");
|
||||
assert.ok(snapshot.nodes.some(node => node.type === "Alert"), "capture sees an alert covering the app");
|
||||
assert.ok(!snapshot.nodes.some(node => /systemui/.test(JSON.stringify(node))), "the system UI is still left out");
|
||||
assert.deepEqual((await run(["alert", "get", ...flags("android")])).json.data.alert.buttons, ["Allow"]);
|
||||
});
|
||||
|
||||
test("system back swipes from the iOS edge; Android prefers an in-app back control", async () => {
|
||||
const ios = harness("ios", { "list-devices": IOS_DEVICES, "ui-tree": IOS_HOME, "gesture-swipe": {} });
|
||||
assert.equal((await ios.run(["back", "--system", ...flags("ios")])).exitCode, 0);
|
||||
assert.deepEqual(ios.calls.at(-1).args, { udid: UDID, fromX: 0.05, fromY: 0.5, toX: 0.8, toY: 0.5, momentum: false });
|
||||
|
||||
const up = { ...ANDROID_HOME, roots: [...ANDROID_HOME.roots.filter(root => root.bundleId !== BUNDLE), { type: "android.widget.FrameLayout", bundleId: BUNDLE,
|
||||
frame: { x: 0, y: 0, width: 1, height: 1 }, children: [{ type: "android.widget.ImageButton", contentDescription: "Navigate up", frame: { x: 0, y: 0.05, width: 0.1, height: 0.05 } }] }] };
|
||||
const android = harness("android", { "list-devices": ANDROID_DEVICES, "ui-tree": up, "gesture-tap": {}, button: {} });
|
||||
assert.deepEqual((await android.run(["back", "--in-app", ...flags("android")])).json.data, { action: "back", mode: "in-app" });
|
||||
assert.equal(android.calls.some(call => call.tool === "button"), false);
|
||||
const none = harness("android", { "list-devices": ANDROID_DEVICES, "ui-tree": ANDROID_HOME, button: {} });
|
||||
assert.equal((await none.run(["back", "--in-app", ...flags("android")])).json.error.message, "in-app back control is not available");
|
||||
assert.deepEqual((await none.run(["back", ...flags("android")])).json.data, { action: "back", mode: "system" });
|
||||
});
|
||||
|
||||
test("open without --relaunch keeps a running app as it is", async () => {
|
||||
const { run, calls } = harness("ios", { "list-devices": IOS_DEVICES, "ui-tree": IOS_HOME, "restart-app": {} });
|
||||
assert.equal((await run(["open", BUNDLE, ...flags("ios")])).exitCode, 0);
|
||||
assert.equal(calls.some(call => call.tool === "restart-app"), false);
|
||||
});
|
||||
|
||||
test("a link prompt that lingers a moment after Open is pressed is not a failure", async () => {
|
||||
const prompt = { ...IOS_HOME, alertVisible: true, foregroundApp: "com.apple.springboard",
|
||||
roots: [...IOS_HOME.roots, { type: "Alert", label: "Open in “euxy”?", frame: { x: 0.1, y: 0.4, width: 0.8, height: 0.2 }, children: [] }] };
|
||||
// Read once before the press, twice more while the app comes forward, then the app.
|
||||
const { run, context } = harness("ios", { "list-devices": IOS_DEVICES, "open-url": {}, "gesture-tap": {}, describe: { description: "" }, "ui-tree": [prompt, prompt, prompt, IOS_HOME] });
|
||||
assert.equal((await run(["open", BUNDLE, "euxy://", ...flags("ios")])).exitCode, 0);
|
||||
assert.equal(context.state.deepLinkPromptAccepted, true);
|
||||
});
|
||||
|
||||
test("on iPhone Duo's inner display, a sheet's title outside Argent's shrunken root frame is visible", () => {
|
||||
assert.deepEqual(DUO_OPEN_EDIT_LANE.roots[0].frame, { x: 0, y: 0, width: 0.3333333333333333, height: 0.3333333333333333 }, "the recorded Argent quirk");
|
||||
const { nodes } = snapshotFromTree(DUO_OPEN_EDIT_LANE, "ios", 1, BUNDLE);
|
||||
for (const label of ["Edit Lane", "Cancel", "Done"]) {
|
||||
const node = nodes.find(item => item.label === label);
|
||||
assert.ok(node, label);
|
||||
assert.notEqual(node.visible, false, `${label} is visible`);
|
||||
}
|
||||
});
|
||||
|
||||
test("a node its ancestor clips away is still reported hidden on iOS", () => {
|
||||
const clipped = { screen: { width: 400, height: 800 }, foregroundApp: BUNDLE, roots: [{ type: "Application", frame: { x: 0, y: 0, width: 1, height: 1 }, children: [
|
||||
{ type: "ScrollView", frame: { x: 0, y: 0, width: 1, height: 0.5 }, children: [
|
||||
{ type: "Button", label: "In view", frame: { x: 0.1, y: 0.1, width: 0.3, height: 0.05 } },
|
||||
{ type: "Button", label: "Scrolled away", frame: { x: 0.1, y: 0.7, width: 0.3, height: 0.05 } }] }] }] };
|
||||
const { nodes } = snapshotFromTree(clipped, "ios", 1, BUNDLE);
|
||||
assert.notEqual(nodes.find(node => node.label === "In view").visible, false);
|
||||
assert.equal(nodes.find(node => node.label === "Scrolled away").visible, false);
|
||||
});
|
||||
|
||||
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] });
|
||||
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 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");
|
||||
});
|
||||
@@ -101,3 +101,27 @@ test("attached sessions are proven live, agent-device typed, and served by the g
|
||||
await assert.rejects(resolveAttachedSimulatorSession({}, undefined), /EAS_SIMULATOR_SESSION_ID did not return a session id/);
|
||||
await assert.rejects(resolveAttachedSimulatorSession({ ...env, AGENT_DEVICE_DAEMON_AUTH_TOKEN: "" }, undefined), /unsafe agent-device connection/);
|
||||
});
|
||||
|
||||
test("an attached argent session is found from ARGENT_* and proven against the session's tool-server", async () => {
|
||||
const { assertAttachedSimulatorSession, readSimulatorDotenvHandoff, resolveAttachedSimulatorSession } = await import(join(root, "dist", "capture", "simulator.js"));
|
||||
const connection = { sessionId: "01a1-mine", daemonBaseUrl: "https://tools.example.eas.dev", daemonAuthToken: "secret", controller: "argent" };
|
||||
const env = { EAS_SIMULATOR_SESSION_ID: "01a1-mine", ARGENT_TOOLS_URL: connection.daemonBaseUrl, ARGENT_AUTH_TOKEN: "secret" };
|
||||
assert.deepEqual(await resolveAttachedSimulatorSession(env, undefined), connection);
|
||||
// A tool-server that needs no token is still an argent session.
|
||||
assert.deepEqual(await resolveAttachedSimulatorSession({ ...env, ARGENT_AUTH_TOKEN: undefined }, undefined), { ...connection, daemonAuthToken: "" });
|
||||
await assert.rejects(resolveAttachedSimulatorSession({ ...env, ARGENT_TOOLS_URL: "http://tools.example.eas.dev" }, undefined), /unsafe argent/);
|
||||
const session = (overrides = {}) => JSON.stringify({ id: "01a1-mine", name: "mine", type: "argent", status: "IN_PROGRESS", platform: "ANDROID",
|
||||
remoteConfig: { toolsUrl: connection.daemonBaseUrl, toolsAuthToken: "secret" }, ...overrides });
|
||||
assert.equal(assertAttachedSimulatorSession(session(), connection).platform, "android");
|
||||
assert.throws(() => assertAttachedSimulatorSession(session({ type: "agent-device" }), connection), /attached argent session/);
|
||||
assert.throws(() => assertAttachedSimulatorSession(session({ remoteConfig: { toolsUrl: connection.daemonBaseUrl, toolsAuthToken: "other" } }), connection), /different argent connection/);
|
||||
const dir = await mkdtemp(join(tmpdir(), "explore-argent-dotenv-"));
|
||||
try {
|
||||
const path = join(dir, ".env.eas-simulator");
|
||||
await writeFile(path, "# Do not commit this file.\n# Do not modify these values manually. They are managed by eas-cli.\n# It holds configuration only for the current simulator session.\n\nEAS_SIMULATOR_SESSION_ID='01a1-mine'\nARGENT_TOOLS_URL='https://tools.example.eas.dev'\nARGENT_AUTH_TOKEN='secret'\n");
|
||||
const handoff = await readSimulatorDotenvHandoff(path);
|
||||
assert.equal(handoff.validationError, undefined);
|
||||
assert.deepEqual(handoff.connection, connection);
|
||||
assert.deepEqual(await resolveAttachedSimulatorSession({}, path), connection);
|
||||
} finally { await rm(dir, { recursive: true, force: true }); }
|
||||
});
|
||||
@@ -135,6 +135,11 @@ test("capture recipes exclude display settings but bind agent instructions and c
|
||||
assert.equal(JSON.parse(key).observer, CAPTURE_OBSERVER_HASH);
|
||||
assert.match(JSON.parse(key).observer, /^[a-f0-9]{64}$/);
|
||||
assert.equal(key,captureRecipeConfig({...config,app:{...config.app,name:"Renamed display"}}));
|
||||
// agent-device recipes are unchanged by Argent support; an Argent capture is keyed to Argent and its version.
|
||||
assert.equal(JSON.parse(key).controllerVersion, undefined);
|
||||
const argent = JSON.parse(captureRecipeConfig({...config,capture:{...config.capture,controller:"argent"}}));
|
||||
assert.equal(argent.capture.controller, "argent");
|
||||
assert.match(argent.controllerVersion, /^\d+\.\d+\.\d+$/);
|
||||
const agent = {...config,mode:"agent",agent:{provider:"openai",model:"another-model",instructions:".expo-explore/instructions.md"}};
|
||||
assert.notEqual(key,captureRecipeConfig(agent,"a".repeat(64)));
|
||||
assert.equal(JSON.parse(captureRecipeConfig(agent,"a".repeat(64))).agent.acceptancePolicy, AGENT_ACCEPTANCE_POLICY);
|
||||
|
||||
@@ -142,15 +142,19 @@ 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'\nAGENT_DEVICE_DAEMON_BASE_URL='https://controller.example/session'\nAGENT_DEVICE_DAEMON_AUTH_TOKEN='" + DAEMON_TOKEN + "'\n");
|
||||
writeFileSync(join(request.cwd, '.env.eas-simulator'), HEADER + "EAS_SIMULATOR_SESSION_ID='session-1'\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');
|
||||
return { stdout: 'ready', stderr: '' };
|
||||
}
|
||||
if (command === 'simulator:get') return json({ id: 'session-1', name: sessionName, type: 'agent-device', platform: settings.android ? 'ANDROID' : 'IOS', status: 'IN_PROGRESS',
|
||||
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',
|
||||
app: { id: settings.wrongProject ? 'foreign-project' : PROJECT_ID, slug: 'example', ownerAccount: { name: 'acme' } },
|
||||
remoteConfig: { agentDeviceRemoteSessionUrl: 'https://controller.example/session', agentDeviceRemoteSessionToken: DAEMON_TOKEN,
|
||||
remoteConfig: { ...(settings.argent ? { toolsUrl: 'https://controller.example/session', toolsAuthToken: DAEMON_TOKEN }
|
||||
: { agentDeviceRemoteSessionUrl: 'https://controller.example/session', agentDeviceRemoteSessionToken: DAEMON_TOKEN }),
|
||||
// eas-cli --json folds the preview token into an expo.dev page that frames the preview server.
|
||||
webPreviewUrl: settings.webPreviewUrl ?? `https://expo.dev/simulator-preview/${PREVIEW_ID}?token=${PREVIEW_TOKEN}` } });
|
||||
webPreviewUrl: settings.webPreviewUrl ?? `https://expo.dev/simulator-preview/${PREVIEW_ID}?token=${PREVIEW_TOKEN}`,
|
||||
...(settings.previewApiUrl ? { previewApiUrl: settings.previewApiUrl } : {}) } });
|
||||
if (command === 'simulator:stop') {
|
||||
if (settings.stopFailure) throw new Error('stop unavailable');
|
||||
return json({ id: 'session-1', status: 'STOPPED' });
|
||||
@@ -164,8 +168,9 @@ async function fixture(t, settings = {}) {
|
||||
if (settings.android) writeFileSync(value(request, '--output'), 'apk'); else mkdirSync(value(request, '--output'));
|
||||
return { stdout: '', stderr: '' };
|
||||
}
|
||||
if (request.command === 'fake-controller') {
|
||||
if (command === '--version') return { stdout: AGENT_DEVICE_VERSION, stderr: '' };
|
||||
// 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 === 'open') {
|
||||
if (request.args.includes('--relaunch')) splashLeft = settings.splashFrames ?? 0;
|
||||
if (request.args[2]?.startsWith('sample://')) {
|
||||
@@ -184,6 +189,7 @@ async function fixture(t, settings = {}) {
|
||||
return ok(settings.wrongForeground ? { appBundleId: 'com.foreign.app' } : identity());
|
||||
}
|
||||
if (command === 'wait') return ok({});
|
||||
if (command === 'fold') return 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 }); }
|
||||
writeFileSync(recordingPath, 'mp4-bytes'); return ok({ path: recordingPath });
|
||||
@@ -282,7 +288,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.launch ? { launch: settings.launch, recordingTools: settings.recordingTools ?? null } : {}), ...(settings.repack ? { repack: settings.repack } : {}),
|
||||
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 } : {}),
|
||||
environment: { PATH: process.env.PATH, HOME: 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 };
|
||||
@@ -349,6 +355,74 @@ test('an app pinned to one appearance is captured once, in that appearance', asy
|
||||
assert.deepEqual(map.screens.map(screen => [screen.id, screen.colorScheme]), [[f.ids.home, undefined], [f.ids.settings, undefined]]);
|
||||
});
|
||||
|
||||
test('an Argent capture starts an argent session, drives it through the bridge, and records Argent as the controller', async t => {
|
||||
const f = await fixture(t, { argent: true, userInterfaceStyle: 'automatic', environment: { AGENT_DEVICE_DAEMON_BASE_URL: 'https://wrong.example', ARGENT_TOOLS_URL: 'https://wrong.example' } });
|
||||
const lines = [];
|
||||
const result = await runCiMap({ ...f.options, progress: line => lines.push(line) });
|
||||
assert.equal(result.runStatus, 'complete');
|
||||
const start = f.requests.find(request => request.args[0] === 'simulator:start');
|
||||
assert.equal(value(start, '--type'), 'argent');
|
||||
assert.equal(value(start, '--package-version'), '0.29.0');
|
||||
assert.ok(start.args.includes('--public-link'));
|
||||
const controller = f.requests.filter(request => request.command.endsWith('/argent-controller'));
|
||||
assert.ok(controller.length > 0);
|
||||
assert.ok(!f.requests.some(request => request.command === 'fake-controller'), 'every controller call goes through the bridge');
|
||||
for (const request of controller) {
|
||||
assert.equal(request.environment.ARGENT_TOOLS_URL, 'https://controller.example/session');
|
||||
assert.equal(request.environment.ARGENT_AUTH_TOKEN, DAEMON_TOKEN);
|
||||
assert.equal(request.environment.DO_NOT_TRACK, '1');
|
||||
assert.equal(request.environment.EXPLORE_ARGENT_PLATFORM, 'ios');
|
||||
assert.equal(request.environment.EXPLORE_ARGENT_BUNDLE_ID, 'com.example.app');
|
||||
assert.ok(request.environment.HOME.endsWith('/argent-home') && request.environment.HOME !== f.options.environment.HOME, 'Argent gets a HOME of its own');
|
||||
assert.deepEqual(Object.keys(request.environment).filter(name => name.startsWith('AGENT_DEVICE_')), []);
|
||||
}
|
||||
// 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'));
|
||||
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);
|
||||
assert.deepEqual(map.screens.map(screen => screen.id), [f.ids.home, f.ids.settings]);
|
||||
const bundle = JSON.parse(await readFile(join(f.options.outputDirectory, 'bundle.json'), 'utf8'));
|
||||
assert.equal(bundle.controller, 'argent');
|
||||
const execution = parseRuntimeExecutionContext(JSON.parse(await readFile(join(f.options.outputDirectory, 'execution.json'), 'utf8')));
|
||||
assert.equal(execution.controller, 'argent');
|
||||
assert.equal(execution.controllerPackageVersion, '0.29.0');
|
||||
});
|
||||
|
||||
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 = [];
|
||||
await runCiMap({ ...f.options, progress: line => lines.push(line) });
|
||||
assert.equal(lines.some(line => /Argent cannot switch appearance/.test(line)), false);
|
||||
const execution = parseRuntimeExecutionContext(JSON.parse(await readFile(join(f.options.outputDirectory, 'execution.json'), 'utf8')));
|
||||
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 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'), []);
|
||||
}
|
||||
});
|
||||
|
||||
test('an agent-device capture writes no controller into its bundle', async t => {
|
||||
const f = await fixture(t);
|
||||
await runCiMap(f.options);
|
||||
const bundle = JSON.parse(await readFile(join(f.options.outputDirectory, 'bundle.json'), 'utf8'));
|
||||
assert.equal('controller' in bundle, false);
|
||||
const start = f.requests.find(request => request.args[0] === 'simulator:start');
|
||||
assert.equal(value(start, '--type'), 'agent-device');
|
||||
assert.equal(value(start, '--package-version'), AGENT_DEVICE_VERSION);
|
||||
});
|
||||
|
||||
test('a preview URL that names the preview server directly reads its catalog', async t => {
|
||||
const f = await fixture(t, { webPreviewUrl: `https://web-preview-${PREVIEW_ID}.eas-simulator.ngrok.dev/?token=${PREVIEW_TOKEN}` });
|
||||
const result = await runCiMap(f.options);
|
||||
@@ -356,6 +430,31 @@ test('a preview URL that names the preview server directly reads its catalog', a
|
||||
assert.deepEqual(f.catalogRequests.map(request => request.url), [`https://web-preview-${PREVIEW_ID}.eas-simulator.ngrok.dev/grid/api?limit=1000`]);
|
||||
});
|
||||
|
||||
test('sessions start with a public preview link, and eas-cli 25 publishes its token on previewApiUrl', async t => {
|
||||
// eas-cli 25 omits the preview token from a private session's --json output; a --public-link session carries it on
|
||||
// previewApiUrl (the preview server itself) and in the fragment of the expo.dev page.
|
||||
const f = await fixture(t, { webPreviewUrl: `https://expo.dev/simulator-preview/${PREVIEW_ID}#token=${PREVIEW_TOKEN}`,
|
||||
previewApiUrl: `https://web-preview-${PREVIEW_ID}.eas-simulator.ngrok.dev/?token=${PREVIEW_TOKEN}` });
|
||||
const result = await runCiMap(f.options);
|
||||
assert.ok(f.requests.find(request => request.args[0] === 'simulator:start').args.includes('--public-link'));
|
||||
assert.equal(result.simulatorRuntime.osVersion, '26.5');
|
||||
assert.deepEqual(f.catalogRequests.map(request => request.url), [`https://web-preview-${PREVIEW_ID}.eas-simulator.ngrok.dev/grid/api?limit=1000`]);
|
||||
});
|
||||
|
||||
test('a preview token in the expo.dev page fragment reaches the framed preview server', async t => {
|
||||
const f = await fixture(t, { webPreviewUrl: `https://expo.dev/simulator-preview/${PREVIEW_ID}#token=${PREVIEW_TOKEN}` });
|
||||
const result = await runCiMap(f.options);
|
||||
assert.equal(result.simulatorRuntime.osVersion, '26.5');
|
||||
assert.equal(f.catalogRequests.length, 1);
|
||||
});
|
||||
|
||||
test('a private session publishes no preview token, so the OS version is unknown and capture goes on', async t => {
|
||||
const f = await fixture(t, { webPreviewUrl: `https://expo.dev/simulator-preview/${PREVIEW_ID}` });
|
||||
const result = await runCiMap(f.options);
|
||||
assert.equal(result.outcomes[f.ids.home].status, 'captured');
|
||||
assert.ok(f.catalogRequests.every(request => request.authorization === null), 'no credential is invented');
|
||||
});
|
||||
|
||||
test('an unrecognized preview URL is not sent the preview token', async t => {
|
||||
const f = await fixture(t, { webPreviewUrl: `https://preview.example/session?token=${PREVIEW_TOKEN}` });
|
||||
const result = await runCiMap(f.options);
|
||||
@@ -2524,13 +2623,6 @@ test('a timed-out native alert query is unknown: the snapshot decides, and it is
|
||||
assert.equal(blocked.operations().includes('screenshot'), false);
|
||||
});
|
||||
|
||||
test('the installed agent-device dependency is the version every controller check uses', async () => {
|
||||
const manifest = JSON.parse(await readFile(new URL('../../package.json', import.meta.url), 'utf8'));
|
||||
const lock = JSON.parse(await readFile(new URL('../../package-lock.json', import.meta.url), 'utf8'));
|
||||
assert.equal(manifest.dependencies['agent-device'], AGENT_DEVICE_VERSION);
|
||||
assert.equal(lock.packages['node_modules/agent-device'].version, AGENT_DEVICE_VERSION);
|
||||
});
|
||||
|
||||
test('agent observation waits out a deferred system-surface snapshot instead of failing', async t => {
|
||||
const f = await fixture(t, { routes: [route('home')] });
|
||||
let refusals = 1, snapshots = 0;
|
||||
|
||||
@@ -122,6 +122,19 @@ test("version prints the package version", () => {
|
||||
}
|
||||
});
|
||||
|
||||
test("capture is the local review, capture:review by a shorter name", async (t) => {
|
||||
const outside = await mkdtemp(join(tmpdir(), "explore-capture-"));
|
||||
t.after(() => rm(outside, { recursive: true, force: true }));
|
||||
const failures = ["capture", "capture:review"].map(command => [
|
||||
runFailure(outside, [command, "--bogus", "--json"]),
|
||||
runFailure(outside, [command, "--committed", "--json"]),
|
||||
]);
|
||||
assert.deepEqual(failures[0], failures[1], "the same flags, errors and result contract");
|
||||
assert.equal(failures[0][0].command, "capture:review");
|
||||
assert.equal(failures[0][0].diagnostic.code, "CLI_ARGUMENT_INVALID");
|
||||
assert.equal(failures[0][1].diagnostic.code, "LOCAL_REVIEW_GIT_FAILED", "--committed is a known flag; outside a repository the review stops");
|
||||
});
|
||||
|
||||
test("removed map-writing commands fail as unknown commands", () => {
|
||||
for (const command of ["init", "screen:add", "attempt:commit", "frontier:claim", "gap:add", "finish"]) {
|
||||
const result = spawnSync(process.execPath, [cli, command], { cwd: root, encoding: "utf8" });
|
||||
|
||||
@@ -0,0 +1,124 @@
|
||||
import assert from "node:assert/strict";
|
||||
import { spawnSync } from "node:child_process";
|
||||
import { createHash } from "node:crypto";
|
||||
import { existsSync, statSync } from "node:fs";
|
||||
import { mkdir, mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
import test from "node:test";
|
||||
import { gzipSync } from "node:zlib";
|
||||
import { AGENT_DEVICE_VERSION } from "../../dist/shared/agent-device-version.js";
|
||||
import { ARGENT_VERSION } from "../../dist/shared/argent-version.js";
|
||||
import { CONTROLLER_PACKAGES, agentDeviceLauncher, controllerBin, controllerCacheRoot, controllerCached, controllerDirectory, controllerTarballUrl, ensureController } from "../../dist/shared/controller-cache.js";
|
||||
|
||||
/** A gzip tarball of `entries` ({ name, contents?, type?, mode?, link? }), laid out as npm publishes one. */
|
||||
function tarball(entries) {
|
||||
const blocks = [];
|
||||
for (const entry of entries) {
|
||||
const contents = Buffer.from(entry.contents ?? "");
|
||||
const header = Buffer.alloc(512);
|
||||
header.write(entry.name, 0, 100);
|
||||
header.write(`${(entry.mode ?? 0o644).toString(8).padStart(7, "0")}\0`, 100);
|
||||
header.write("0000000\0", 108); header.write("0000000\0", 116);
|
||||
header.write(`${(entry.type === "0" || !entry.type ? contents.length : 0).toString(8).padStart(11, "0")}\0`, 124);
|
||||
header.write("00000000000\0", 136);
|
||||
header.write(" ", 148);
|
||||
header.write(entry.type ?? "0", 156);
|
||||
if (entry.link) header.write(entry.link, 157, 100);
|
||||
header.write("ustar\0", 257); header.write("00", 263);
|
||||
const sum = header.reduce((total, byte) => total + byte, 0);
|
||||
header.write(`${sum.toString(8).padStart(6, "0")}\0 `, 148);
|
||||
blocks.push(header);
|
||||
if (!entry.type || entry.type === "0") blocks.push(contents, Buffer.alloc((512 - (contents.length % 512)) % 512));
|
||||
}
|
||||
blocks.push(Buffer.alloc(1024));
|
||||
return gzipSync(Buffer.concat(blocks));
|
||||
}
|
||||
|
||||
const integrity = bytes => `sha512-${createHash("sha512").update(bytes).digest("base64")}`;
|
||||
|
||||
async function harness(t, entries, options = {}) {
|
||||
const root = await mkdtemp(join(tmpdir(), "explore-controller-cache-"));
|
||||
t.after(() => rm(root, { recursive: true, force: true }));
|
||||
const bytes = tarball(entries);
|
||||
const environment = { EXPLORE_CONTROLLER_CACHE: join(root, "cache") };
|
||||
const packages = { ...CONTROLLER_PACKAGES, "agent-device": { ...CONTROLLER_PACKAGES["agent-device"], integrity: options.integrity ?? integrity(bytes) } };
|
||||
const requests = [];
|
||||
const fetch = async url => { requests.push(String(url)); return new Response(bytes); };
|
||||
return { root, environment, requests, ensure: () => ensureController("agent-device", { environment, fetch, packages }) };
|
||||
}
|
||||
|
||||
const CLI = { name: "package/bin/agent-device.mjs", contents: "#!/usr/bin/env node\nconsole.log(JSON.stringify(process.argv.slice(2)));\n" };
|
||||
|
||||
test("the pinned controllers are the versions Explore drives, and agent-device matches the lockfile Explore tests with", async () => {
|
||||
assert.equal(CONTROLLER_PACKAGES["agent-device"].version, AGENT_DEVICE_VERSION);
|
||||
assert.equal(CONTROLLER_PACKAGES.argent.version, ARGENT_VERSION);
|
||||
const manifest = JSON.parse(await readFile(new URL("../../package.json", import.meta.url), "utf8"));
|
||||
const lock = JSON.parse(await readFile(new URL("../../package-lock.json", import.meta.url), "utf8"));
|
||||
assert.equal(manifest.dependencies["agent-device"], undefined, "agent-device is fetched on use, not installed with Explore");
|
||||
assert.equal(manifest.dependencies["@swmansion/argent"], undefined, "Argent is fetched on use, not installed with Explore");
|
||||
assert.equal(manifest.devDependencies["agent-device"], AGENT_DEVICE_VERSION);
|
||||
assert.equal(lock.packages["node_modules/agent-device"].integrity, CONTROLLER_PACKAGES["agent-device"].integrity);
|
||||
});
|
||||
|
||||
test("tarballs come from the npm registry, or a mirror, at the pinned version", () => {
|
||||
assert.equal(controllerTarballUrl("argent", {}), `https://registry.npmjs.org/@swmansion/argent/-/argent-${ARGENT_VERSION}.tgz`);
|
||||
assert.equal(controllerTarballUrl("agent-device", { EXPLORE_NPM_REGISTRY: "https://npm.example.com/" }),
|
||||
`https://npm.example.com/agent-device/-/agent-device-${AGENT_DEVICE_VERSION}.tgz`);
|
||||
assert.equal(controllerCacheRoot({ HOME: "/home/me" }), "/home/me/.cache/expo-explore/controllers");
|
||||
assert.equal(controllerCacheRoot({ HOME: "/home/me", XDG_CACHE_HOME: "/cache" }), "/cache/expo-explore/controllers");
|
||||
assert.match(controllerDirectory("argent", { EXPLORE_CONTROLLER_CACHE: "/c" }), new RegExp(`^/c/@swmansion\\+argent@${ARGENT_VERSION}$`));
|
||||
});
|
||||
|
||||
test("a controller is fetched once, verified, unpacked, and its entry made executable", async t => {
|
||||
const f = await harness(t, [{ name: "package/", type: "5", mode: 0o755 }, CLI, { name: "package/package.json", contents: "{}" }]);
|
||||
const bin = await f.ensure();
|
||||
assert.equal(bin, controllerBin("agent-device", f.environment));
|
||||
assert.equal(statSync(bin).mode & 0o111, 0o111);
|
||||
assert.ok(controllerCached("agent-device", f.environment));
|
||||
assert.equal(await f.ensure(), bin);
|
||||
assert.equal(f.requests.length, 1, "a cached controller is not fetched again");
|
||||
assert.deepEqual((await readdir(join(f.root, "cache"))).filter(name => name.startsWith(".staging")), [], "no staging files are left");
|
||||
});
|
||||
|
||||
test("a tarball that does not match the pinned integrity is never unpacked", async t => {
|
||||
const f = await harness(t, [CLI], { integrity: "sha512-not-the-release" });
|
||||
await assert.rejects(f.ensure(), error => error.code === "CONTROLLER_INTEGRITY_MISMATCH");
|
||||
assert.equal(controllerCached("agent-device", f.environment), false);
|
||||
assert.equal(existsSync(controllerDirectory("agent-device", f.environment)), false);
|
||||
});
|
||||
|
||||
test("links and paths outside the package are refused", async t => {
|
||||
for (const entry of [{ name: "package/evil", type: "2", link: "/etc/passwd" }, { name: "package/../escape.js", contents: "x" }, { name: "other/file.js", contents: "x" }]) {
|
||||
const f = await harness(t, [CLI, entry]);
|
||||
await assert.rejects(f.ensure(), error => error.code === "CONTROLLER_DOWNLOAD_FAILED", entry.name);
|
||||
assert.equal(controllerCached("agent-device", f.environment), false);
|
||||
}
|
||||
});
|
||||
|
||||
test("a registry failure names the release and the mirror setting", async t => {
|
||||
const root = await mkdtemp(join(tmpdir(), "explore-controller-cache-"));
|
||||
t.after(() => rm(root, { recursive: true, force: true }));
|
||||
await assert.rejects(ensureController("agent-device", { environment: { EXPLORE_CONTROLLER_CACHE: root }, fetch: async () => new Response("no", { status: 404 }) }),
|
||||
error => error.code === "CONTROLLER_DOWNLOAD_FAILED" && /agent-device@/.test(error.message) && /EXPLORE_NPM_REGISTRY/.test(error.nextAction));
|
||||
});
|
||||
|
||||
test("the agent-device command runs the cached release with the caller's arguments, without a network", async t => {
|
||||
const root = await mkdtemp(join(tmpdir(), "explore-controller-cache-"));
|
||||
t.after(() => rm(root, { recursive: true, force: true }));
|
||||
const environment = { EXPLORE_CONTROLLER_CACHE: join(root, "cache") };
|
||||
const directory = controllerDirectory("agent-device", environment);
|
||||
await mkdir(join(directory, "bin"), { recursive: true });
|
||||
await writeFile(join(directory, "bin/agent-device.mjs"), CLI.contents, { mode: 0o755 });
|
||||
await writeFile(join(directory, ".explore-controller.json"), "{}\n");
|
||||
const command = agentDeviceLauncher(environment);
|
||||
assert.equal(agentDeviceLauncher(environment), command, "the command is stable");
|
||||
assert.match(command, new RegExp(`/bin/agent-device-${AGENT_DEVICE_VERSION}-[0-9a-f]{12}$`), "the command names its release");
|
||||
const mirrored = agentDeviceLauncher({ ...environment, EXPLORE_NPM_REGISTRY: "https://npm.example.com" });
|
||||
assert.notEqual(mirrored, command, "another setup gets a command of its own instead of rewriting this one");
|
||||
assert.match(await readFile(mirrored, "utf8"), /EXPLORE_NPM_REGISTRY='https:\/\/npm\.example\.com'/, "the mirror reaches the narrowed controller environment");
|
||||
// The command names its cache, so a caller that narrows the environment still reaches it.
|
||||
const run = spawnSync(command, ["snapshot", "--json", "--", "-h"], { encoding: "utf8", env: { PATH: process.env.PATH } });
|
||||
assert.equal(run.status, 0, run.stderr);
|
||||
assert.deepEqual(JSON.parse(run.stdout), ["snapshot", "--json", "--", "-h"]);
|
||||
});
|
||||
@@ -130,7 +130,7 @@ function runtimeFor(side, map, expectedSamples = 3, capturedSamples = expectedSa
|
||||
observationId: observation.id,
|
||||
expectedSampleCount: expectedSamples,
|
||||
controllerPackageVersion: "0.20.2",
|
||||
easCliVersion: "24.4.2",
|
||||
easCliVersion: "25.0.0",
|
||||
},
|
||||
runtime: {
|
||||
kind: "eas-agent-device-raw",
|
||||
|
||||
@@ -5,7 +5,7 @@ import { join } from "node:path";
|
||||
import test from "node:test";
|
||||
import { tsImport } from "tsx/esm/api";
|
||||
|
||||
const { DEFAULT_EXPLORE_CONFIG_PATH, assertExecutionMode, parseExploreConfig, readExploreConfig, validateExploreConfig, configPlatforms, resolvePlatformConfig } =
|
||||
const { DEFAULT_EXPLORE_CONFIG_PATH, assertExecutionMode, parseExploreConfig, readExploreConfig, validateExploreConfig, configPlatforms, resolvePlatformConfig, withRunOverrides } =
|
||||
await tsImport("../../src/config/explore-config.ts", import.meta.url);
|
||||
|
||||
const SOURCE = `app:
|
||||
@@ -241,3 +241,31 @@ test("capture.reset accepts root-link or none, defaults to root-link, and reject
|
||||
assert.equal(validateExploreConfig({ ...base(), capture: { reset: "none" } }).capture.reset, "none");
|
||||
assert.throws(() => validateExploreConfig({ ...base(), capture: { reset: "relaunch" } }), /capture\.reset must be "root-link" or "none"/);
|
||||
});
|
||||
|
||||
test("capture.controller chooses Argent; agent-device, the default, leaves the config as it was", () => {
|
||||
const plain = validateExploreConfig(base());
|
||||
assert.equal("controller" in plain.capture, false);
|
||||
assert.deepEqual(validateExploreConfig({ ...base(), capture: { controller: "agent-device" } }), plain);
|
||||
assert.equal(validateExploreConfig({ ...base(), capture: { controller: "argent" } }).capture.controller, "argent");
|
||||
assert.throws(() => validateExploreConfig({ ...base(), capture: { controller: "maestro" } }), error => error.code === "CONFIG_INVALID");
|
||||
});
|
||||
|
||||
test("--controller overrides the config's controller for one run and is validated", () => {
|
||||
const plain = validateExploreConfig(base());
|
||||
const argent = withRunOverrides(plain, { controller: "argent" });
|
||||
assert.equal(argent.capture.controller, "argent");
|
||||
assert.deepEqual(withRunOverrides(argent, { controller: "agent-device" }), plain);
|
||||
assert.deepEqual(withRunOverrides(plain, {}), plain);
|
||||
assert.throws(() => withRunOverrides(plain, { controller: "appium" }), /--controller must be agent-device or argent/);
|
||||
});
|
||||
|
||||
test("device.pose folds the primary platform's device and is validated", () => {
|
||||
const open = validateExploreConfig({ ...base(), device: { name: "iPhone Duo", pose: "open" } });
|
||||
assert.deepEqual(open.device, { name: "iPhone Duo", pose: "open" });
|
||||
assert.equal("pose" in validateExploreConfig(base()).device, false);
|
||||
assert.throws(() => validateExploreConfig({ ...base(), device: { name: "iPhone Duo", pose: "flat" } }), error => error.code === "CONFIG_INVALID");
|
||||
const both = validateExploreConfig({ ...base(), app: { ...base().app, platform: "ios" }, device: { name: "iPhone Duo", pose: "open" },
|
||||
platforms: { ios: {}, android: { device: "pixel_7", bundleId: "com.example.app", easProfile: "explore" } } });
|
||||
assert.deepEqual(resolvePlatformConfig(both, "ios").device, { name: "iPhone Duo", pose: "open" });
|
||||
assert.deepEqual(resolvePlatformConfig(both, "android").device, { name: "pixel_7" });
|
||||
});
|
||||
@@ -5,7 +5,7 @@ import { spawnSync } from 'node:child_process';
|
||||
import { lstat, mkdtemp, readFile, realpath, rm, writeFile } from 'node:fs/promises';
|
||||
import { tmpdir } from 'node:os';
|
||||
import { join } from 'node:path';
|
||||
import { appEnvironment, captureCacheDirectory, defaultBase, installDependencies, keepCapture, localInstallCommand, reportRef, runLocalReview, snapshotWorkingTree } from '../../dist/ci/local-review.js';
|
||||
import { appEnvironment, captureCacheDirectory, defaultBase, installDependencies, keepCapture, localInstallCommand, localReviewConfig, reportRef, reviewHeadSource, runLocalReview, snapshotWorkingTree } from '../../dist/ci/local-review.js';
|
||||
import { mkdir, readdir } from 'node:fs/promises';
|
||||
import { startLocalReportServer } from '../../dist/report/local-report-server.js';
|
||||
import { fixture, git } from '../helpers/public-ci-fixture.mjs';
|
||||
@@ -56,6 +56,56 @@ test('the working tree becomes a commit on HEAD without touching the index, file
|
||||
assert.deepEqual({ status: git(root, 'status', '--porcelain'), index: git(root, 'diff', '--cached', '--name-only'), refs: git(root, 'for-each-ref'), head: git(root, 'rev-parse', 'HEAD') }, before);
|
||||
});
|
||||
|
||||
test('the head is the working tree, as eas build uploads it, unless --committed, --head, or eas.json requireCommit says otherwise', async t => {
|
||||
const project = await scratch(t, 'explore-local-head-');
|
||||
assert.equal(await reviewHeadSource({}, project), 'working-tree', 'no eas.json');
|
||||
await writeFile(join(project, 'eas.json'), JSON.stringify({ cli: { version: '>= 16' }, build: {} }));
|
||||
assert.equal(await reviewHeadSource({}, project), 'working-tree');
|
||||
assert.equal(await reviewHeadSource({ committed: true }, project), 'commit');
|
||||
assert.equal(await reviewHeadSource({ head: 'HEAD' }, project), 'working-tree', '--head HEAD is the default head');
|
||||
assert.equal(await reviewHeadSource({ head: 'v1.0.0' }, project), 'commit');
|
||||
await writeFile(join(project, 'eas.json'), JSON.stringify({ cli: { requireCommit: true } }));
|
||||
assert.equal(await reviewHeadSource({}, project), 'require-commit', 'eas build refuses uncommitted changes here, so the review leaves them out');
|
||||
assert.equal(await reviewHeadSource({ uncommitted: true }, project), 'working-tree', '--uncommitted includes them anyway');
|
||||
await writeFile(join(project, 'eas.json'), '{ not json');
|
||||
assert.equal(await reviewHeadSource({}, project), 'working-tree');
|
||||
for (const conflict of [{ uncommitted: true, head: 'v1.0.0' }, { uncommitted: true, committed: true }]) {
|
||||
await assert.rejects(reviewHeadSource(conflict, project), { code: 'LOCAL_REVIEW_UNCOMMITTED_HEAD' });
|
||||
}
|
||||
});
|
||||
|
||||
test('a review uses the head commit\'s config, else an uncommitted one, else the defaults setup would write', async t => {
|
||||
const project = await scratch(t, 'explore-local-app-');
|
||||
const head = await scratch(t, 'explore-local-head-');
|
||||
const json = (path, value) => writeFile(join(project, path), JSON.stringify(value));
|
||||
await json('package.json', { dependencies: { expo: '*', 'expo-router': '*' } });
|
||||
await json('app.json', { expo: { name: 'Test app', scheme: 'test-app', ios: { bundleIdentifier: 'com.example.test' } } });
|
||||
await json('eas.json', { build: { explore: { ios: { simulator: true } } } });
|
||||
const configPath = '.expo-explore/config.yaml';
|
||||
const resolve = (options = {}) => localReviewConfig({ project, head, configPath, explicit: false, ...options });
|
||||
|
||||
const messages = [];
|
||||
const defaults = await resolve({ progress: message => messages.push(message) });
|
||||
assert.equal(defaults.mode, 'deterministic');
|
||||
assert.deepEqual([defaults.app.platform, defaults.app.bundleId, defaults.app.easProfile, defaults.app.scheme], ['ios', 'com.example.test', 'explore', 'test-app']);
|
||||
assert.equal(defaults.navigation.provider, 'expo-router');
|
||||
assert.equal(defaults.exploration.scope, 'changes');
|
||||
assert.match(messages.join('\n'), /setup's defaults \(com\.example\.test, EAS profile explore, iPhone 17\)/);
|
||||
await assert.rejects(lstat(join(project, '.expo-explore')), { code: 'ENOENT' }, 'the defaults are not written');
|
||||
|
||||
const config = name => `mode: deterministic\napp:\n name: ${name}\n platform: ios\n bundleId: com.example.test\n easProfile: explore\n`
|
||||
+ 'navigation:\n provider: expo-router\ndevice:\n name: iPhone 17\nexploration:\n scope: changes\n';
|
||||
await mkdir(join(project, '.expo-explore')); await writeFile(join(project, configPath), config('Checkout'));
|
||||
assert.equal((await resolve()).app.name, 'Checkout', 'setup ran but its config is not committed yet');
|
||||
await mkdir(join(head, '.expo-explore')); await writeFile(join(head, configPath), config('Head'));
|
||||
assert.equal((await resolve()).app.name, 'Head', 'the commit under review wins');
|
||||
|
||||
await assert.rejects(resolve({ configPath: 'other.yaml', explicit: true }), { code: 'CONFIG_READ_FAILED' }, 'a --config path must be in the commit');
|
||||
await rm(join(project, '.expo-explore'), { recursive: true }); await rm(join(head, '.expo-explore'), { recursive: true });
|
||||
await rm(join(project, 'eas.json'));
|
||||
await assert.rejects(resolve(), error => error.code === 'LOCAL_REVIEW_CONFIG_DEFAULTS' && /no \.expo-explore\/config\.yaml.*No eas\.json found/s.test(error.message));
|
||||
});
|
||||
|
||||
test('with no base, a branch is compared with where it left the default branch', async t => {
|
||||
const root = await repository(t);
|
||||
const fork = git(root, 'rev-parse', 'HEAD');
|
||||
@@ -221,7 +271,7 @@ test('Ctrl+C during a deterministic capture stops it before the next route and s
|
||||
const name = request.command.split('/').at(-1);
|
||||
calls.push({ name, command: request.args[0], afterCtrlC: ctrlC.signal.aborted });
|
||||
// The first route link is opened: the person presses Ctrl+C while it loads.
|
||||
if (name === 'agent-device' && request.args[0] === 'open' && /sample:\/\//.test(request.args[2] ?? '') && !ctrlC.signal.aborted) ctrlC.abort();
|
||||
if (/^agent-device(-|$)/.test(name) && request.args[0] === 'open' && /sample:\/\//.test(request.args[2] ?? '') && !ctrlC.signal.aborted) ctrlC.abort();
|
||||
return f.runner(request);
|
||||
};
|
||||
let kept;
|
||||
@@ -234,7 +284,7 @@ test('Ctrl+C during a deterministic capture stops it before the next route and s
|
||||
const after = calls.filter(call => call.afterCtrlC);
|
||||
assert.ok(after.some(call => call.command === 'simulator:stop'), 'its session is stopped');
|
||||
assert.equal(after.filter(call => call.command === 'simulator:start').length, 0, 'no other session starts');
|
||||
assert.ok(after.filter(call => call.name === 'agent-device' && call.command === 'open').length <= 1, 'no further route is opened');
|
||||
assert.ok(after.filter(call => /^agent-device(-|$)/.test(call.name) && call.command === 'open').length <= 1, 'no further route is opened');
|
||||
});
|
||||
|
||||
test('Ctrl+C stops the review, and the checkouts are removed while its files are kept', async t => {
|
||||
|
||||
@@ -0,0 +1,35 @@
|
||||
import assert from "node:assert/strict";
|
||||
import test from "node:test";
|
||||
import { tsImport } from "tsx/esm/api";
|
||||
|
||||
const { mapFrame, MAP_SCREEN_WIDTH, MAP_SCREEN_HEIGHT } = await tsImport("../../viewer/src/utils/map-frame.ts", import.meta.url);
|
||||
const { typicalScreenshotSize } = await tsImport("../../viewer/src/utils/screen-images.ts", import.meta.url);
|
||||
|
||||
const size = (imageWidth, imageHeight) => ({ imageWidth, imageHeight });
|
||||
|
||||
test("phone screenshots keep the map's default card", () => {
|
||||
for (const phone of [size(402, 874), size(1206, 2622), size(720, 1600), undefined]) {
|
||||
const frame = mapFrame(phone);
|
||||
assert.equal(frame.width, MAP_SCREEN_WIDTH);
|
||||
assert.equal(frame.height, MAP_SCREEN_HEIGHT);
|
||||
}
|
||||
assert.deepEqual(mapFrame(size(720, 1600)).screen, { width: 390, height: 845 }, "a missing screenshot keeps the default phone frame");
|
||||
assert.deepEqual(mapFrame(size(1398, 2034)).screen, { width: 1398, height: 2034 }, "a missing screenshot on a wider screen is framed like the run's");
|
||||
});
|
||||
|
||||
test("a wider screen gets a card in its own shape with about the same screen area", () => {
|
||||
// iPhone Duo screenshots are 1398 × 2034 pixels.
|
||||
const duo = mapFrame(size(1398, 2034));
|
||||
const slotHeight = duo.height - 34;
|
||||
assert.ok(Math.abs(duo.width / slotHeight - 1398 / 2034) < 0.01, JSON.stringify(duo));
|
||||
const phoneArea = mapFrame(size(402, 874));
|
||||
const area = duo.width * slotHeight, defaultArea = (phoneArea.height - 34) ** 2 * (9 / 19.5);
|
||||
assert.ok(Math.abs(area / defaultArea - 1) < 0.02, `${area} vs ${defaultArea}`);
|
||||
assert.ok(duo.width > MAP_SCREEN_WIDTH && duo.height < MAP_SCREEN_HEIGHT);
|
||||
});
|
||||
|
||||
test("a run's screenshot shape is its median one, and unknown sizes do not count", () => {
|
||||
const duo = size(1398, 2034);
|
||||
assert.deepEqual(typicalScreenshotSize([duo, undefined, duo, size(1398, 3000), duo]), duo);
|
||||
assert.equal(typicalScreenshotSize([undefined, undefined]), undefined);
|
||||
});
|
||||
@@ -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: '24.4.2', 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.0.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: {
|
||||
|
||||
@@ -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: "24.4.2",
|
||||
provider: "eas-simulator", controller: "agent-device", controllerPackageVersion: AGENT_DEVICE_VERSION, easCliVersion: "25.0.0",
|
||||
platform: "ios", deviceModel: "iPhone 17", osVersion: "26.0", locale: "en-US", orientation: "portrait",
|
||||
colorScheme: "light", sessionLifecycle: "stopped",
|
||||
};
|
||||
|
||||
@@ -253,3 +253,36 @@ test("quarantine: a report-level contract failure still throws", () => {
|
||||
assert.throws(() => quarantineReviewContract(provenance), /disagree with their build provenance/);
|
||||
});
|
||||
|
||||
|
||||
test('a visual region may carry the shift its content moved by, and a malformed one is rejected', async () => {
|
||||
const { assertPublicReview } = await import('../../dist/contracts/review-validation.js');
|
||||
const valid = JSON.parse(JSON.stringify(reviewWithRegion({ x: 0, y: -4.17 })));
|
||||
assert.doesNotThrow(() => assertPublicReview(valid));
|
||||
for (const shift of [{ x: 0 }, { x: 0, y: Number.NaN }, { x: 0, y: 500 }, 'up']) {
|
||||
assert.throws(() => assertPublicReview(reviewWithRegion(shift)), /visual verdict is inconsistent/, JSON.stringify(shift));
|
||||
}
|
||||
});
|
||||
|
||||
function reviewWithRegion(shift) {
|
||||
const input = review();
|
||||
input.surfaces[0].review = { status: "modified", description: "Updated visual styling in the main content area." };
|
||||
input.surfaces[0].visual = { verdict: "modified", reason: "repeated-cross-build-delta", mismatchPercentage: 1, threshold: 0.1, tool: "agent-device",
|
||||
regions: [{ rect: { x: 0, y: 0, width: 1, height: 1 }, normalizedRect: { x: 0, y: 0, width: 100, height: 100 },
|
||||
differentPixels: 1, shareOfDiffPercentage: 100, dominantChange: "mixed", location: "center", shift }] };
|
||||
return input;
|
||||
}
|
||||
|
||||
test('allRegionsMoved is only true, and only where every published region carries its shift', async () => {
|
||||
const { assertPublicReview } = await import('../../dist/contracts/review-validation.js');
|
||||
const moved = reviewWithRegion({ x: 0, y: 1 });
|
||||
moved.surfaces[0].visual.allRegionsMoved = true;
|
||||
assert.doesNotThrow(() => assertPublicReview(moved));
|
||||
for (const [label, mutate] of [['false', visual => { visual.allRegionsMoved = false; }],
|
||||
['a region without a shift', visual => { delete visual.regions[0].shift; }],
|
||||
['no regions', visual => { delete visual.regions; }]]) {
|
||||
const input = reviewWithRegion({ x: 0, y: 1 });
|
||||
input.surfaces[0].visual.allRegionsMoved = true;
|
||||
mutate(input.surfaces[0].visual);
|
||||
assert.throws(() => assertPublicReview(input), /visual verdict is inconsistent/, label);
|
||||
}
|
||||
});
|
||||
@@ -0,0 +1,103 @@
|
||||
import assert from "node:assert/strict";
|
||||
import test from "node:test";
|
||||
import { Buffer } from "node:buffer";
|
||||
import { regionShifts } from "../../dist/review/region-shift.js";
|
||||
|
||||
/** A 120×160 frame of a light background with dark text-like bars, drawn `offsetY` pixels lower (fractions blend rows). */
|
||||
function frame(offsetY, { barColor = 40, extraBar = false } = {}) {
|
||||
const width = 120, height = 160;
|
||||
const data = Buffer.alloc(width * height * 4, 240);
|
||||
const bars = [[10, 20, 80, 6], [10, 34, 60, 4], [10, 60, 90, 8], ...(extraBar ? [[10, 90, 70, 6]] : [])];
|
||||
for (let y = 0; y < height; y += 1) {
|
||||
for (let x = 0; x < width; x += 1) {
|
||||
// Coverage of the pixel row [y, y+1) by each bar after the vertical offset, for sub-pixel moves.
|
||||
let coverage = 0;
|
||||
for (const [bx, by, bw, bh] of bars) {
|
||||
if (x < bx || x >= bx + bw) continue;
|
||||
const top = by + offsetY, bottom = top + bh;
|
||||
coverage += Math.max(0, Math.min(y + 1, bottom) - Math.max(y, top));
|
||||
}
|
||||
const value = Math.round(240 - Math.min(1, coverage) * (240 - barColor));
|
||||
data.fill(value, (y * width + x) * 4, (y * width + x) * 4 + 3);
|
||||
data[(y * width + x) * 4 + 3] = 255;
|
||||
}
|
||||
}
|
||||
return { width, height, data };
|
||||
}
|
||||
|
||||
const region = { x: 0, y: 10, width: 110, height: 70 };
|
||||
|
||||
test("a region whose content only moved reports how far, to a sixth of a pixel", () => {
|
||||
assert.deepEqual(regionShifts(frame(0), frame(2), [region]), [{ x: 0, y: 2 }]);
|
||||
assert.deepEqual(regionShifts(frame(0), frame(-4), [region]), [{ x: 0, y: -4 }]);
|
||||
const [third] = regionShifts(frame(0), frame(1 / 3), [region]);
|
||||
assert.ok(third && Math.abs(third.y - 1 / 3) < 0.1 && third.x === 0, JSON.stringify(third));
|
||||
});
|
||||
|
||||
test("a region whose content changed, or that did not change, has no shift", () => {
|
||||
assert.deepEqual(regionShifts(frame(0), frame(0, { barColor: 200 }), [region]), [undefined], "another colour is a change, not a move");
|
||||
assert.deepEqual(regionShifts(frame(0), frame(0, { extraBar: true }), [{ x: 0, y: 80, width: 110, height: 30 }]), [undefined], "new content is a change");
|
||||
assert.deepEqual(regionShifts(frame(0), frame(0), [region]), [undefined], "identical pixels have nothing to explain");
|
||||
});
|
||||
|
||||
test("screenshots of different sizes are not measured", () => {
|
||||
const small = { ...frame(0), width: 60, data: Buffer.alloc(60 * 160 * 4, 240) };
|
||||
assert.deepEqual(regionShifts(small, frame(2), [region]), [undefined]);
|
||||
});
|
||||
|
||||
test("a third of a pixel counts as a move even when re-rasterized text explains only part of it, but changed content does not", () => {
|
||||
// A third of a pixel down, then every bar a shade darker: the shift explains roughly a third of the difference,
|
||||
// as re-rasterized text does on a 3x screen.
|
||||
const shifted = frame(1 / 3), base = frame(0);
|
||||
const noisy = { ...shifted, data: Buffer.from(shifted.data.map((value, index) => (index % 4 === 3 || value === 240 ? value : Math.max(0, value - 14)))) };
|
||||
const [move] = regionShifts(base, noisy, [region]);
|
||||
assert.ok(move && Math.abs(move.y - 1 / 3) < 0.1, JSON.stringify(move));
|
||||
});
|
||||
|
||||
test("a best fit at the edge of the search is not a move: repeating content lines up with itself a pitch away", () => {
|
||||
// Bars repeating every 12 pixels; After is the same pattern 12 pixels lower, which also matches unshifted rows.
|
||||
const stripes = offset => {
|
||||
const width = 60, height = 120, data = Buffer.alloc(width * height * 4, 240);
|
||||
for (let y = 0; y < height; y += 1) if (((y - offset) % 12 + 12) % 12 < 4) for (let x = 0; x < width; x += 1) data.fill(30, (y * width + x) * 4, (y * width + x) * 4 + 3);
|
||||
for (let i = 3; i < data.length; i += 4) data[i] = 255;
|
||||
return { width, height, data };
|
||||
};
|
||||
// Moved down 5 also fits as up 7: two fits that good are ambiguous, so the region is not a move rather than a wrong one.
|
||||
assert.deepEqual(regionShifts(stripes(0), stripes(5), [{ x: 0, y: 20, width: 60, height: 60 }]), [undefined]);
|
||||
});
|
||||
|
||||
/** A frame painted by `paint(x, y)` (dark where true) on a light background, optionally in colour. */
|
||||
function painted(width, height, paint, colour = [30, 30, 30]) {
|
||||
const data = Buffer.alloc(width * height * 4, 240);
|
||||
for (let y = 0; y < height; y += 1) for (let x = 0; x < width; x += 1) {
|
||||
const offset = (y * width + x) * 4;
|
||||
if (paint(x, y)) { data[offset] = colour[0]; data[offset + 1] = colour[1]; data[offset + 2] = colour[2]; }
|
||||
data[offset + 3] = 255;
|
||||
}
|
||||
return { width, height, data };
|
||||
}
|
||||
|
||||
test("content that is the same all along one axis is measured along the other: full-width bars and hairlines", () => {
|
||||
const bar = offset => painted(80, 100, (x, y) => y >= 40 + offset && y < 46 + offset);
|
||||
assert.deepEqual(regionShifts(bar(0), bar(2), [{ x: 0, y: 30, width: 80, height: 30 }]), [{ x: 0, y: 2 }]);
|
||||
const hairline = offset => painted(80, 100, (x, y) => y === 50 + offset);
|
||||
assert.deepEqual(regionShifts(hairline(0), hairline(1), [{ x: 0, y: 44, width: 80, height: 12 }]), [{ x: 0, y: 1 }]);
|
||||
assert.deepEqual(regionShifts(hairline(0), hairline(-3), [{ x: 0, y: 40, width: 80, height: 16 }]), [{ x: 0, y: -3 }]);
|
||||
});
|
||||
|
||||
test("a region that moved and also changed is not a move: the leftover after aligning it gives the change away", () => {
|
||||
// Three bars moved down 2px, plus a new short bar inside the region, as a digit that changed in a row that moved.
|
||||
const bars = (offset, extra) => painted(120, 160, (x, y) => (x >= 10 && x < 90 && ((y >= 20 + offset && y < 26 + offset)
|
||||
|| (y >= 34 + offset && y < 38 + offset) || (y >= 60 + offset && y < 68 + offset))) || (extra && x >= 95 && x < 105 && y >= 45 && y < 48));
|
||||
assert.deepEqual(regionShifts(bars(0, false), bars(2, false), [region]), [{ x: 0, y: 2 }]);
|
||||
assert.deepEqual(regionShifts(bars(0, false), bars(2, true), [region]), [undefined]);
|
||||
// Another colour of the same brightness, moved: luminance alone would call it moved.
|
||||
const red = painted(120, 160, (x, y) => x >= 10 && x < 90 && y >= 20 && y < 40, [200, 40, 40]);
|
||||
const green = painted(120, 160, (x, y) => x >= 10 && x < 90 && y >= 22 && y < 42, [40, 112, 40]);
|
||||
assert.deepEqual(regionShifts(red, green, [region]), [undefined]);
|
||||
});
|
||||
|
||||
test("a half-pixel move up and down is judged alike", () => {
|
||||
const up = regionShifts(frame(0), frame(-0.5), [region])[0], down = regionShifts(frame(0), frame(0.5), [region])[0];
|
||||
assert.deepEqual([up?.y, down?.y], [-0.5, 0.5]);
|
||||
});
|
||||
@@ -7,6 +7,7 @@ import {
|
||||
} from "../../dist/review/runtime-adapter.js";
|
||||
import { projectRuntimeEvidence } from "../../dist/review/runtime-evidence.js";
|
||||
import { AGENT_DEVICE_VERSION } from "../../dist/capture/run.js";
|
||||
import { ARGENT_VERSION } from "../../dist/shared/argent-version.js";
|
||||
|
||||
const sha = "a".repeat(40);
|
||||
|
||||
@@ -15,7 +16,7 @@ function execution(overrides = {}) {
|
||||
provider: "eas-simulator",
|
||||
controller: "agent-device",
|
||||
controllerPackageVersion: AGENT_DEVICE_VERSION,
|
||||
easCliVersion: "24.4.2",
|
||||
easCliVersion: "25.0.0",
|
||||
platform: "ios",
|
||||
deviceModel: "iPhone 17",
|
||||
osVersion: "26.0",
|
||||
@@ -188,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, "24.4.2");
|
||||
assert.equal(result.groups.environment.easCliVersion?.value, "25.0.0");
|
||||
});
|
||||
|
||||
test("normalizes multi-line labels and treats only open parser gaps as truncation", () => {
|
||||
@@ -288,3 +289,11 @@ test("fails closed on provenance, environment, surface, and capture mismatches",
|
||||
/visual fingerprint is missing/,
|
||||
);
|
||||
});
|
||||
|
||||
test("an Argent capture's execution context names Argent and its pinned version, never another pairing", () => {
|
||||
const argent = execution({ controller: "argent", controllerPackageVersion: ARGENT_VERSION });
|
||||
assert.deepEqual(parseRuntimeExecutionContext(argent), argent);
|
||||
assert.throws(() => parseRuntimeExecutionContext(execution({ controller: "argent" })), /Controller package version.*invalid/i);
|
||||
assert.throws(() => parseRuntimeExecutionContext(execution({ controllerPackageVersion: ARGENT_VERSION })), /Controller package version.*invalid/i);
|
||||
assert.throws(() => parseRuntimeExecutionContext(execution({ controller: "appium" })), /Runtime controller.*invalid/i);
|
||||
});
|
||||
@@ -3,7 +3,7 @@ import test from "node:test";
|
||||
|
||||
const { tsImport } = await import("tsx/esm/api");
|
||||
const { indexMap } = await tsImport("../../viewer/src/utils/model.ts", import.meta.url);
|
||||
const { screenTree } = await tsImport("../../viewer/src/utils/screen-tree.ts", import.meta.url);
|
||||
const { screenTree, treeScreenOrder } = await tsImport("../../viewer/src/utils/screen-tree.ts", import.meta.url);
|
||||
|
||||
const at = (second) => `2026-10-13T00:00:${String(second).padStart(2, "0")}.000Z`;
|
||||
function screen(id, title, depth, extra = {}) {
|
||||
@@ -49,6 +49,20 @@ test("with route files, sections follow the app directory and the tabs lead", ()
|
||||
assert.deepEqual(folders, ["(tabs)/"]);
|
||||
});
|
||||
|
||||
test("the screens' order is the tree's, depth first: a nested folder's screens come right after their parent's", () => {
|
||||
// The folders are found as settings, feed, settings/security: sections keep that order, while the tree nests
|
||||
// security under settings. The Screens grid and its arrow keys follow the tree, as the sidebar reads.
|
||||
const screens = [screen("profile", "A profile", 1), screen("feed", "B feed", 1), screen("security", "C security", 1), screen("loose", "D loose", 1)];
|
||||
const routeFiles = new Map([
|
||||
["profile", "app/settings/profile.tsx"],
|
||||
["feed", "app/feed/index.tsx"],
|
||||
["security", "app/settings/security/index.tsx"],
|
||||
]);
|
||||
const tree = screenTree(screens, indexMap(map({ screens })), routeFiles);
|
||||
assert.deepEqual(tree.sections.flatMap(section => section.screenIds), ["profile", "feed", "security", "loose"]);
|
||||
assert.deepEqual(treeScreenOrder(tree), ["profile", "security", "feed", "loose"]);
|
||||
});
|
||||
|
||||
test("a black-box exploration groups by the tab each screen was opened from", () => {
|
||||
const screens = [
|
||||
screen("seq", "Sequencer", 0),
|
||||
|
||||
@@ -78,11 +78,16 @@ test("EAS profile inheritance is respected and device builds cannot be selected"
|
||||
explore: { extends: "base", ios: { buildConfiguration: "Release" } },
|
||||
production: { extends: "base", ios: { simulator: false } },
|
||||
} });
|
||||
await assert.rejects(runExploreSetup({ project, ...options }), /--profile/);
|
||||
await assert.rejects(runExploreSetup({ project, ...options, profile: "production" }), /--profile/);
|
||||
await assert.rejects(stat(path), { code: "ENOENT" });
|
||||
await runExploreSetup({ project, ...options, profile: "explore" });
|
||||
// Of several simulator profiles, the one named explore is the default; without one, setup asks for --profile.
|
||||
await runExploreSetup({ project, ...options });
|
||||
assert.equal((await readExploreConfig(project)).app.easProfile, "explore");
|
||||
await rm(path);
|
||||
await json("eas.json", { build: { base: { ios: { simulator: true } }, sim: { extends: "base" } } });
|
||||
await assert.rejects(runExploreSetup({ project, ...options }), /--profile: base, sim/);
|
||||
await runExploreSetup({ project, ...options, profile: "sim" });
|
||||
assert.equal((await readExploreConfig(project)).app.easProfile, "sim");
|
||||
});
|
||||
|
||||
test("dynamic config uses the app's Expo resolver instead of stale app.json", async (t) => {
|
||||
|
||||
@@ -15,6 +15,21 @@ test("hints print modifiers in Apple's ⌥⇧⌘ order and as Ctrl+Alt+Shift els
|
||||
assert.equal(formatShortcut(SHORTCUTS.camera.fit, true), "⇧1");
|
||||
assert.equal(formatShortcut({ code: "KeyT", key: "T", mod: true, alt: true }, false), "Ctrl+Alt+T");
|
||||
assert.equal(formatShortcut(SHORTCUTS.edit.redo, false), "Ctrl+Shift+Z");
|
||||
// The Control key itself prints as ⌃ on a Mac, where ⌘ would be a different key.
|
||||
assert.equal(formatShortcut(SHORTCUTS.canvasByNumber.screens, true), "⌃2");
|
||||
assert.equal(formatShortcut(SHORTCUTS.canvasByNumber.screens, false), "Ctrl+2");
|
||||
});
|
||||
|
||||
test("Ctrl+1, Ctrl+2 and Ctrl+3 reach Map, Screens and Compare with Control alone, never ⌘ (the browser's tab keys)", () => {
|
||||
assert.equal(matchesShortcut(key("Digit1", { ctrlKey: true }), SHORTCUTS.canvasByNumber.map), true);
|
||||
assert.equal(matchesShortcut(key("Digit2", { ctrlKey: true }), SHORTCUTS.canvasByNumber.screens), true);
|
||||
assert.equal(matchesShortcut(key("Digit3", { ctrlKey: true }), SHORTCUTS.canvasByNumber.compare), true);
|
||||
assert.equal(matchesShortcut(key("Digit1", { metaKey: true }), SHORTCUTS.canvasByNumber.map), false);
|
||||
assert.equal(matchesShortcut(key("Digit1", { ctrlKey: true, metaKey: true }), SHORTCUTS.canvasByNumber.map), false);
|
||||
assert.equal(matchesShortcut(key("Digit1", { ctrlKey: true, shiftKey: true }), SHORTCUTS.canvasByNumber.map), false);
|
||||
// Compare's 1, 2, 3 (Split, Swipe, Flip) stay plain digits.
|
||||
assert.equal(matchesShortcut(key("Digit1", { ctrlKey: true }), SHORTCUTS.compare.split), false);
|
||||
assert.equal(matchesShortcut(key("Digit1"), SHORTCUTS.canvasByNumber.map), false);
|
||||
});
|
||||
|
||||
test("a chord matches only its own modifiers, on either ⌘ or Ctrl", () => {
|
||||
@@ -35,7 +50,8 @@ test("no two shortcuts share a chord", () => {
|
||||
const seen = new Map();
|
||||
for (const [group, entries] of Object.entries(SHORTCUTS)) {
|
||||
for (const [name, shortcut] of Object.entries(entries)) {
|
||||
const chord = `${shortcut.code}:${Boolean(shortcut.mod)}:${Boolean(shortcut.alt)}:${Boolean(shortcut.shift)}`;
|
||||
// Off Apple keyboards ⌘ is Ctrl, so a Control chord clashes with the same ⌘ chord.
|
||||
const chord = `${shortcut.code}:${Boolean(shortcut.mod || shortcut.ctrl)}:${Boolean(shortcut.alt)}:${Boolean(shortcut.shift)}`;
|
||||
const clash = seen.get(chord);
|
||||
assert.ok(!clash, `${group}.${name} repeats ${clash}`);
|
||||
seen.set(chord, `${group}.${name}`);
|
||||
|
||||
@@ -0,0 +1,47 @@
|
||||
import assert from "node:assert/strict";
|
||||
import test from "node:test";
|
||||
|
||||
const { tsImport } = await import("tsx/esm/api");
|
||||
const { groupVisualRegions, formatMove, layoutShiftSummary } = await tsImport("../../viewer/src/utils/visual-diff.ts", import.meta.url);
|
||||
|
||||
const move = (y, x = 0, unit = "pt") => ({ x: x / 4, y: y / 8, amount: { x, y }, unit });
|
||||
const region = (y, height, shift, x = 10, width = 60) => ({ x, y, width, height, share: 10, ...(shift === undefined ? {} : { move: shift }) });
|
||||
|
||||
test("areas that moved by the same amount read as one, across a gap that keeps changed areas apart", () => {
|
||||
// A sheet's title, button and footer moved up about 4pt (measured 3.8–4.3 across its parts), 5% of the height apart.
|
||||
const sheet = groupVisualRegions([region(60, 5, move(-4)), region(70, 5, move(-4.33)), region(80, 3, move(-3.83)), region(86, 3, move(-4.17))]);
|
||||
assert.equal(sheet.length, 1);
|
||||
assert.equal(formatMove(sheet[0]), "↑4.1pt", "one number: the parts' average, to a tenth");
|
||||
// The same areas with changed content stay apart, as before.
|
||||
assert.equal(groupVisualRegions([region(60, 5), region(70, 5), region(80, 3)]).length, 3);
|
||||
// A moved area and a changed one that touch are not merged, and up and down did not move together.
|
||||
assert.equal(groupVisualRegions([region(60, 5, move(-4)), region(65, 5)]).length, 2);
|
||||
assert.equal(groupVisualRegions([region(30, 5, move(1)), region(36, 5, move(-1))]).length, 2);
|
||||
});
|
||||
|
||||
test("rows that drifted by different amounts keep their own outlines and numbers", () => {
|
||||
// List rows a device pixel and more apart: 1, 1.5 and 2pt, as the rows behind euxy's sheet.
|
||||
const rows = groupVisualRegions([region(40, 5, move(1)), region(46, 5, move(1.5)), region(52, 5, move(2))]);
|
||||
assert.deepEqual(rows.map(row => formatMove(row)), ["↓1pt", "↓1.5pt", "↓2pt"]);
|
||||
// Two-thirds of a point apart is a different move too, as on euxy's channel-surf sheet (1.3 and 2pt).
|
||||
assert.equal(groupVisualRegions([region(40, 5, move(1.33)), region(46, 5, move(2))]).length, 2);
|
||||
});
|
||||
|
||||
test("a moved outline never grows around a changed area", () => {
|
||||
const changes = groupVisualRegions([region(10, 4, move(1)), region(15, 4), region(20, 4, move(1))]);
|
||||
assert.deepEqual(changes.map(change => `${change.move ? "moved" : "changed"} ${change.y}`), ["moved 10", "changed 15", "moved 20"]);
|
||||
});
|
||||
|
||||
test("labels are one number, never empty or zero", () => {
|
||||
assert.equal(formatMove({ move: move(1, 2, "px") }), "→2 ↓1px", "a sideways move is named too, in Android's screenshot pixels");
|
||||
assert.equal(formatMove({ move: move(1.33) }), "↓1.3pt");
|
||||
// Two nudges a third of a pixel apart, one sideways and one down, average under a quarter on both axes.
|
||||
assert.equal(formatMove({ move: move(0.17, 0.16) }), "↓0.2pt");
|
||||
});
|
||||
|
||||
test("What changed summarizes a screen whose every area moved, per direction, and nothing when any content changed", () => {
|
||||
const moved = groupVisualRegions([region(20, 5, move(1)), region(40, 5, move(2)), region(70, 5, move(-4.17))]);
|
||||
assert.deepEqual(layoutShiftSummary(moved), ["2 areas moved down 1–2pt.", "1 area moved up 4.2pt."]);
|
||||
assert.equal(layoutShiftSummary([...moved, ...groupVisualRegions([region(90, 3)])]), undefined);
|
||||
assert.equal(layoutShiftSummary([]), undefined);
|
||||
});
|
||||
@@ -46,6 +46,7 @@ import {
|
||||
type ThemePreference,
|
||||
} from "./utils/navigation";
|
||||
import {
|
||||
CANVAS_NUMBER_KEYS,
|
||||
matchesShortcut,
|
||||
modalOpen,
|
||||
SHORTCUTS,
|
||||
@@ -142,7 +143,10 @@ const LEGACY_COLLAPSED_STORAGE_KEY = "expo-explore:panel-collapsed";
|
||||
const RIGHT_COLLAPSED_STORAGE_KEY = "expo-explore:right-panel-collapsed";
|
||||
// The shell's keyboard map, paired with what each key selects. Read as lists so a key and the
|
||||
// thing it reaches stay one entry.
|
||||
const CANVAS_KEYS = Object.entries(SHORTCUTS.canvas) as [CanvasView, Shortcut][];
|
||||
const CANVAS_KEYS = [
|
||||
...Object.entries(SHORTCUTS.canvas),
|
||||
...(CANVAS_NUMBER_KEYS ? Object.entries(SHORTCUTS.canvasByNumber) : []),
|
||||
] as [CanvasView, Shortcut][];
|
||||
|
||||
/** Before data loads there is no comparison to assume. A workspace reparses the URL on arrival. */
|
||||
const EMPTY_ROUTE_CONTEXT: RouteContext = {
|
||||
|
||||
@@ -25,6 +25,8 @@ export type ScreenScreenshotCardProps = {
|
||||
ariaPressed?: boolean;
|
||||
imageWidth?: number;
|
||||
imageHeight?: number;
|
||||
/** The frame of a screen without a screenshot: its run's screenshots, so it lines up beside them. */
|
||||
placeholderSize?: { width: number; height: number };
|
||||
loading?: "eager" | "lazy";
|
||||
leading?: ReactNode;
|
||||
trailing?: ReactNode;
|
||||
@@ -42,7 +44,7 @@ export function ScreenScreenshotCard(props: ScreenScreenshotCardProps) {
|
||||
// frame it waited in, and a screen without one is framed like a phone screenshot beside it.
|
||||
const frame = props.screenshot && props.imageWidth && props.imageHeight
|
||||
? { width: props.imageWidth, height: props.imageHeight }
|
||||
: DEFAULT_SCREENSHOT_SIZE;
|
||||
: props.placeholderSize ?? DEFAULT_SCREENSHOT_SIZE;
|
||||
const missing = (
|
||||
<span
|
||||
className="image-placeholder"
|
||||
|
||||
@@ -5,6 +5,10 @@ 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 { setMeasurementsShown, useMeasurementsShown } from "../../utils/measurements-setting";
|
||||
|
||||
/** A screen whose every changed area only moved: how far, per direction, and whether no other finding remains. */
|
||||
export type LayoutShift = { lines: string[]; nothingElse: boolean };
|
||||
import type { ComparePicker } from "./compare-section";
|
||||
|
||||
/**
|
||||
@@ -92,11 +96,29 @@ export function CompareSteps(props: {
|
||||
* findings as bullets, then what changed for assistive technology under its own heading, then the
|
||||
* notes about the comparison under a hairline.
|
||||
*/
|
||||
export function WhatChangedContent(props: { facts: string[]; assistive?: string[]; accessibilityOnly?: boolean | undefined; notes: string[] }) {
|
||||
export function WhatChangedContent(props: {
|
||||
facts: string[];
|
||||
assistive?: string[];
|
||||
accessibilityOnly?: boolean | undefined;
|
||||
/** Set when every changed area only moved: a line per direction (layoutShiftSummary), and whether nothing else changed. */
|
||||
layoutShift?: LayoutShift | undefined;
|
||||
/** Some outlined area moved, so its outline can be labelled with how far. */
|
||||
measurable?: boolean | undefined;
|
||||
notes: string[];
|
||||
}) {
|
||||
const assistive = props.assistive ?? [];
|
||||
const assistiveTitle = useId();
|
||||
const measurements = useMeasurementsShown();
|
||||
return (
|
||||
<div className="what-changed-content" role="region" aria-label="What changed on this screen">
|
||||
{props.layoutShift ? (
|
||||
<div className="what-changed-shift">
|
||||
<p>{props.layoutShift.nothingElse ? "Layout shifted. Nothing on this screen changed content." : "Layout shifted."}</p>
|
||||
<ul className="what-changed-content-list">
|
||||
{props.layoutShift.lines.map((line) => <li key={line}>{line}</li>)}
|
||||
</ul>
|
||||
</div>
|
||||
) : null}
|
||||
{props.facts.length > 0 ? (
|
||||
<ul className="what-changed-content-list">
|
||||
{props.facts.map((fact) => <li key={fact}>{fact}</li>)}
|
||||
@@ -123,6 +145,16 @@ export function WhatChangedContent(props: { facts: string[]; assistive?: string[
|
||||
{props.notes.map((note) => <p key={note}>{note}</p>)}
|
||||
</div>
|
||||
) : null}
|
||||
{props.measurable ? (
|
||||
<label className="what-changed-measurements">
|
||||
<span className="what-changed-measurements-text">
|
||||
<span>Show measurements</span>
|
||||
<small>How far each outlined area moved</small>
|
||||
</span>
|
||||
<input type="checkbox" role="switch" className="what-changed-switch" checked={measurements}
|
||||
onChange={(event) => setMeasurementsShown(event.target.checked)} />
|
||||
</label>
|
||||
) : null}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -136,13 +168,15 @@ export function WhatChangedPopover(props: {
|
||||
facts: string[];
|
||||
assistive?: string[];
|
||||
accessibilityOnly?: boolean | undefined;
|
||||
layoutShift?: LayoutShift | undefined;
|
||||
measurable?: boolean | undefined;
|
||||
notes: string[];
|
||||
open: boolean;
|
||||
onOpenChange: (open: boolean) => void;
|
||||
}) {
|
||||
const ref = useRef<HTMLDivElement>(null);
|
||||
const { open, onOpenChange } = props;
|
||||
const empty = props.facts.length === 0 && !props.assistive?.length && props.notes.length === 0;
|
||||
const empty = props.facts.length === 0 && !props.assistive?.length && !props.layoutShift && props.notes.length === 0;
|
||||
useEffect(() => {
|
||||
if (!open) return;
|
||||
const onPointerDown = (event: PointerEvent) => {
|
||||
@@ -173,10 +207,10 @@ export function WhatChangedPopover(props: {
|
||||
{open ? (
|
||||
<div className="compare-what-changed-popover" role="dialog" aria-modal="false" aria-label="What changed">
|
||||
{/* A screen that changed only for assistive technology has nothing else to title. */}
|
||||
{props.facts.length > 0 || props.notes.length > 0
|
||||
{props.facts.length > 0 || props.notes.length > 0 || props.layoutShift
|
||||
? <strong className="compare-what-changed-popover-title">What changed</strong> : null}
|
||||
<WhatChangedContent facts={props.facts} {...(props.assistive ? { assistive: props.assistive } : {})}
|
||||
accessibilityOnly={props.accessibilityOnly} notes={props.notes} />
|
||||
accessibilityOnly={props.accessibilityOnly} layoutShift={props.layoutShift} measurable={props.measurable} notes={props.notes} />
|
||||
</div>
|
||||
) : null}
|
||||
</div>
|
||||
|
||||
@@ -203,6 +203,51 @@
|
||||
.what-changed-assistive-title > .status-glyph-dot { width: 8px; height: 8px; border-radius: 2px; background: var(--diff); }
|
||||
.what-changed-assistive-context { margin: 0; color: var(--secondary); font-size: 12px; line-height: 17px; }
|
||||
.what-changed-assistive + .what-changed-content-notes { padding-top: 12px; border-top: 1px solid var(--panel-line); }
|
||||
/* A screen whose changed areas only moved: the verdict, then how far, per direction. */
|
||||
.what-changed-shift { display: flex; flex-direction: column; gap: 8px; }
|
||||
.what-changed-shift > p { margin: 0; color: var(--text); font-size: 13px; line-height: 18px; }
|
||||
/* Show measurements: a row with a switch, under a hairline, like the hand-off's scope switch. */
|
||||
.what-changed-measurements {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: space-between;
|
||||
gap: 12px;
|
||||
padding-top: 12px;
|
||||
border-top: 1px solid var(--panel-line);
|
||||
cursor: pointer;
|
||||
}
|
||||
.what-changed-measurements-text { display: flex; min-width: 0; flex-direction: column; gap: 2px; font-size: 13px; font-weight: 500; line-height: 18px; }
|
||||
.what-changed-measurements-text > small { color: var(--secondary); font-size: 12px; font-weight: 400; line-height: 16px; }
|
||||
.what-changed-switch {
|
||||
position: relative;
|
||||
width: 36px;
|
||||
height: 22px;
|
||||
flex: none;
|
||||
margin: 0;
|
||||
border-radius: 11px;
|
||||
background: var(--border);
|
||||
cursor: pointer;
|
||||
appearance: none;
|
||||
transition: background 160ms ease;
|
||||
}
|
||||
.what-changed-switch::after {
|
||||
position: absolute;
|
||||
top: 2px;
|
||||
left: 2px;
|
||||
width: 18px;
|
||||
height: 18px;
|
||||
border-radius: 9px;
|
||||
background: #fff;
|
||||
box-shadow: 0 1px 2px rgb(0 0 0 / 0.25);
|
||||
content: "";
|
||||
transition: transform 160ms ease;
|
||||
}
|
||||
.what-changed-switch:checked { background: var(--text); }
|
||||
.what-changed-switch:checked::after { transform: translateX(14px); }
|
||||
.what-changed-switch:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
|
||||
@media (prefers-reduced-motion: reduce) {
|
||||
.what-changed-switch, .what-changed-switch::after { transition: none; }
|
||||
}
|
||||
.what-changed-content-list + .what-changed-content-notes { padding-top: 12px; border-top: 1px solid var(--panel-line); }
|
||||
.what-changed-content-notes > p { margin: 0; color: var(--secondary); font-size: 12px; line-height: 17px; }
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ import type { ChangesMenuData } from "../panels/changes-menu";
|
||||
import { diffLabel, ACCESSIBILITY_ONLY_HIGHLIGHT, type BuildDiff, type ScreenDiff } from "../../utils/build-diff";
|
||||
import type { MapIndex } from "../../utils/model";
|
||||
import type { ChangedScreen } from "../../utils/changed-screens";
|
||||
import { groupVisualRegions, type VisualChange } from "../../utils/visual-diff";
|
||||
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 { optionalStorage } from "../../utils/embedded-report";
|
||||
@@ -51,11 +51,14 @@ export function compareModeOptions() {
|
||||
// Highlight changes (the outlines) is one remembered choice, on unless turned off, shared by
|
||||
// every view that draws them: Compare, the Inspector's review and its header button, and the O key.
|
||||
const outlinesListeners = new Set<() => void>();
|
||||
/** The choice made this visit, so the button works where storage is denied (a private window). */
|
||||
let outlinesChosen: boolean | undefined;
|
||||
function storedOutlines(): boolean {
|
||||
return optionalStorage.getItem(OUTLINES_STORAGE_KEY) !== "false";
|
||||
return outlinesChosen ?? optionalStorage.getItem(OUTLINES_STORAGE_KEY) !== "false";
|
||||
}
|
||||
/** Sets the outlines choice everywhere at once and remembers it. */
|
||||
/** Sets the outlines choice everywhere at once and remembers it where it can. */
|
||||
export function setOutlinesShown(shown: boolean) {
|
||||
outlinesChosen = shown;
|
||||
optionalStorage.setItem(OUTLINES_STORAGE_KEY, String(shown));
|
||||
for (const listener of outlinesListeners) listener();
|
||||
}
|
||||
@@ -101,9 +104,22 @@ export function useCompareController(options: CompareControllerOptions) {
|
||||
);
|
||||
// Only what CI found on this screen. The generic summary ("Shared app source changed.") is
|
||||
// not a finding about this screen, so it leaves the list empty and the button disabled.
|
||||
// Every changed area only moved, CI's own count included (it publishes the largest regions only): say how far,
|
||||
// in place of its generic pixel finding ("Updated visual styling in the main content area").
|
||||
const shiftLines = useMemo(
|
||||
() => (screenDiff?.visual?.allRegionsMoved ? layoutShiftSummary(areas) : undefined),
|
||||
[areas, screenDiff?.visual?.allRegionsMoved],
|
||||
);
|
||||
const measurable = areas.some((area) => area.move);
|
||||
const facts = useMemo(
|
||||
() => presentedChanges(screenDiff).filter((change) => change.id !== "legacy-summary"),
|
||||
[screenDiff],
|
||||
() => presentedChanges(screenDiff).filter((change) => change.id !== "legacy-summary"
|
||||
&& !(shiftLines && change.fact?.templateId === "visual.main-content-changed")),
|
||||
[screenDiff, shiftLines],
|
||||
);
|
||||
// "Nothing on this screen changed content" only when no other finding says otherwise.
|
||||
const layoutShift = useMemo(
|
||||
() => (shiftLines ? { lines: shiftLines, nothingElse: facts.length === 0 } : undefined),
|
||||
[shiftLines, facts.length],
|
||||
);
|
||||
// What changed for assistive technology is listed under its own heading.
|
||||
const split = useMemo(() => splitForAssistiveTechnology(facts, screenDiff), [facts, screenDiff]);
|
||||
@@ -241,7 +257,7 @@ export function useCompareController(options: CompareControllerOptions) {
|
||||
const chosenMode: CompareMode = phone ? phoneMode : desktopMode;
|
||||
const modesDisabled = !comparable;
|
||||
return {
|
||||
screen, screenDiff, route, position, previous, next, comparable, areas, facts, split,
|
||||
screen, screenDiff, route, position, previous, next, comparable, areas, facts, split, layoutShift, measurable,
|
||||
mode, chosenMode, modesDisabled, chooseMode, modeOptions, outlines, shownOutlines, statusBarIgnored, homeIndicatorIgnored, toggleOutlines,
|
||||
activeArea, setActiveArea, stepArea, flipSide, flip, swipePosition, setSwipePosition,
|
||||
aspect, setAspect, factsOpen, setFactsOpen,
|
||||
@@ -355,7 +371,7 @@ export function CompareSection(props: CompareSectionProps) {
|
||||
</button>
|
||||
</Tooltip>
|
||||
<WhatChangedPopover facts={factCopies} assistive={assistive} accessibilityOnly={screenDiff.accessibilityOnly}
|
||||
notes={notes} open={factsOpen} onOpenChange={setFactsOpen} />
|
||||
layoutShift={compare.layoutShift} measurable={compare.measurable} notes={notes} open={factsOpen} onOpenChange={setFactsOpen} />
|
||||
</div>
|
||||
</header>
|
||||
|
||||
@@ -490,7 +506,7 @@ export function CompareStage(props: StageProps) {
|
||||
))}
|
||||
</figcaption>
|
||||
<div className="compare-frame-wrap">
|
||||
<button type="button" className="compare-frame compare-flip-frame"
|
||||
<button type="button" className="compare-frame compare-flip-frame" data-side={showing}
|
||||
aria-label={`Show ${showing === "after" ? "Before" : "After"}`} onClick={props.onFlip}>
|
||||
<CompareImage src={showing === "after" ? after : before} alt={`${props.title}, ${showing}`}
|
||||
placeholder="No screenshot" onAspect={props.onAspect} />
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
import { useEffect } from "react";
|
||||
import { createPortal } from "react-dom";
|
||||
import { X } from "lucide-react";
|
||||
import { formatShortcut, SHORTCUTS, type Shortcut } from "../../utils/shortcuts";
|
||||
import { CANVAS_NUMBER_KEYS, formatShortcut, SHORTCUTS, type Shortcut } from "../../utils/shortcuts";
|
||||
import type { CanvasView } from "../../utils/navigation";
|
||||
import { useModalDialog } from "../../hooks/use-modal-dialog";
|
||||
|
||||
@@ -63,6 +63,9 @@ export function shortcutGroups(context: ShortcutContext): Group[][] {
|
||||
label: context.hasChanges ? "Map, Screens, Compare" : "Map, Screens",
|
||||
keys: sections.map((section) => SHORTCUTS.canvas[section]),
|
||||
},
|
||||
...(CANVAS_NUMBER_KEYS
|
||||
? [{ label: "The same, by their place in the toolbar", keys: sections.map((section) => SHORTCUTS.canvasByNumber[section]) }]
|
||||
: []),
|
||||
{ label: "Search screens", keys: [SHORTCUTS.app.search] },
|
||||
...(context.handoff ? [{ label: "Hand off to AI", keys: [SHORTCUTS.app.handoff] }] : []),
|
||||
...(context.hasChanges ? [{ label: "Changed screens menu", keys: [SHORTCUTS.app.changes] }] : []),
|
||||
@@ -83,9 +86,17 @@ export function shortcutGroups(context: ShortcutContext): Group[][] {
|
||||
{ label: "Close the inspector, then deselect", keys: ["Esc"] },
|
||||
],
|
||||
};
|
||||
const screensGroup: Group = {
|
||||
title: "Screens",
|
||||
rows: [
|
||||
{ label: "Move through the screens", keys: ["←", "→", "↑", "↓"] },
|
||||
{ label: "Close the inspector, then deselect", keys: ["Esc"] },
|
||||
],
|
||||
};
|
||||
const here: Group[] = context.canvas === "compare"
|
||||
? [reviewGroup(context)]
|
||||
: [...(context.review ? [reviewGroup(context)] : []), ...(context.canvas === "map" ? [mapGroup] : []), CAMERA];
|
||||
: [...(context.review ? [reviewGroup(context)] : []), ...(context.canvas === "map" ? [mapGroup] : []),
|
||||
...(context.canvas === "screens" ? [screensGroup] : []), CAMERA];
|
||||
return [here, [goTo, view]];
|
||||
}
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@ import { type CSSProperties, type ReactNode } from "react";
|
||||
import { ChevronDown } from "lucide-react";
|
||||
import { ToggleGroup } from "../shared/toggle-group";
|
||||
import { ChangeOutlines, HomeIndicatorBand, StatusBarBand } from "../panels/visual-diff";
|
||||
import { WhatChangedContent } from "./compare-header";
|
||||
import { WhatChangedContent, type LayoutShift } from "./compare-header";
|
||||
import {
|
||||
CompareStage,
|
||||
compareModeOptions,
|
||||
@@ -46,11 +46,13 @@ function WhatChangedAccordion(props: {
|
||||
facts: string[];
|
||||
assistive?: string[];
|
||||
accessibilityOnly?: boolean | undefined;
|
||||
layoutShift?: LayoutShift | undefined;
|
||||
measurable?: boolean | undefined;
|
||||
notes: string[];
|
||||
open: boolean;
|
||||
onOpenChange?: (open: boolean) => void;
|
||||
}) {
|
||||
const count = props.facts.length + (props.assistive?.length ?? 0);
|
||||
const count = props.facts.length + (props.assistive?.length ?? 0) + (props.layoutShift?.lines.length ?? 0);
|
||||
const empty = !props.onOpenChange || (count === 0 && props.notes.length === 0);
|
||||
const open = props.open && !empty;
|
||||
return (
|
||||
@@ -72,7 +74,7 @@ function WhatChangedAccordion(props: {
|
||||
{open ? (
|
||||
<div className="what-changed-accordion-content" id="what-changed-accordion-content">
|
||||
<WhatChangedContent facts={props.facts} {...(props.assistive ? { assistive: props.assistive } : {})}
|
||||
accessibilityOnly={props.accessibilityOnly} notes={props.notes} />
|
||||
accessibilityOnly={props.accessibilityOnly} layoutShift={props.layoutShift} measurable={props.measurable} notes={props.notes} />
|
||||
</div>
|
||||
) : null}
|
||||
</section>
|
||||
@@ -145,7 +147,8 @@ export function SidebarReview(props: CompareControllerOptions) {
|
||||
/>
|
||||
</div>
|
||||
|
||||
<WhatChangedAccordion facts={facts} assistive={assistive} accessibilityOnly={screenDiff.accessibilityOnly} notes={notes}
|
||||
<WhatChangedAccordion facts={facts} assistive={assistive} accessibilityOnly={screenDiff.accessibilityOnly}
|
||||
layoutShift={compare.layoutShift} measurable={compare.measurable} notes={notes}
|
||||
open={compare.factsOpen} onOpenChange={compare.setFactsOpen} />
|
||||
</section>
|
||||
);
|
||||
|
||||
@@ -349,7 +349,7 @@ function ScreenDiffSection(props: {
|
||||
: { ...current, [screenshot]: aspectRatio }
|
||||
));
|
||||
};
|
||||
// CI compares the two images pixel for pixel, so the same areas are outlined on both sides.
|
||||
// The same areas are outlined on both sides; an area that only moved sits where its content is on each.
|
||||
const outlines = visualChanges.length > 0 ? <ChangeOutlines changes={visualChanges} /> : null;
|
||||
|
||||
return (
|
||||
|
||||
@@ -19,6 +19,35 @@
|
||||
box-shadow: 0 0 0 3px color-mix(in srgb, var(--modified) 35%, transparent);
|
||||
}
|
||||
.visual-change-outlines.has-active .visual-change-outline:not(.active) { opacity: 0.35; }
|
||||
/* An area that only moved: dashed and quiet, in the slate of a measurement rather than the orange of a change. */
|
||||
.visual-change-outline.moved {
|
||||
border: 1.5px dashed var(--moved);
|
||||
background: transparent;
|
||||
}
|
||||
.visual-change-outline.moved.active {
|
||||
background: color-mix(in srgb, var(--moved) 14%, transparent);
|
||||
box-shadow: 0 0 0 3px color-mix(in srgb, var(--moved) 30%, transparent);
|
||||
}
|
||||
/* How far it moved, riding the outline's top right corner. */
|
||||
.visual-change-measure {
|
||||
position: absolute;
|
||||
top: 0;
|
||||
right: 0;
|
||||
padding: 0 5px;
|
||||
border-radius: 5px;
|
||||
color: #fff;
|
||||
background: var(--moved);
|
||||
font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, monospace;
|
||||
font-size: 10px;
|
||||
font-weight: 600;
|
||||
line-height: 15px;
|
||||
white-space: nowrap;
|
||||
transform: translate(4px, -60%);
|
||||
}
|
||||
:root[data-theme="dark"] .visual-change-measure { color: #0b0c0e; }
|
||||
/* The Before side draws moved areas where their content was (see ChangeOutlines): Compare's sides and the
|
||||
Inspector's side-by-side pair. */
|
||||
.compare-side[data-side="before"], .compare-flip-frame[data-side="before"], [data-diff-side="before"] { --outline-before: 1; }
|
||||
|
||||
/* The status-bar band CI does not compare: blurred out, explained by its tooltip on hover. */
|
||||
.visual-status-bar-band {
|
||||
|
||||
@@ -1,36 +1,42 @@
|
||||
import { useRef, useState, type CSSProperties, type KeyboardEvent, type PointerEvent } from "react";
|
||||
import { ChevronsLeftRight } from "lucide-react";
|
||||
import { outlineRect, type VisualChange } from "../../utils/visual-diff";
|
||||
import { formatMove, outlineRect, type VisualChange } from "../../utils/visual-diff";
|
||||
import { useMeasurementsShown } from "../../utils/measurements-setting";
|
||||
import { HOME_INDICATOR_BAND_PERCENT_BY_PLATFORM, STATUS_BAR_BAND_PERCENT } from "../../../../src/contracts/capture";
|
||||
import { ScreenshotImage } from "../shared/screenshot-image";
|
||||
import "./visual-diff.css";
|
||||
|
||||
/**
|
||||
* Outlines over a screenshot, one per changed area. The same rectangles go on Before and After:
|
||||
* CI compares the two images pixel for pixel, so an area has one position, not one per side.
|
||||
* The parent must be positioned.
|
||||
* Outlines over a screenshot, one per changed area. An area whose content changed has one position, the same
|
||||
* on Before and After. An area that only moved is dashed and drawn where its content is on each side, labelled
|
||||
* with how far it moved while measurements are shown. The parent must be positioned.
|
||||
*/
|
||||
export function ChangeOutlines(props: {
|
||||
changes: readonly VisualChange[];
|
||||
activeIndex?: number | undefined;
|
||||
}) {
|
||||
const measurements = useMeasurementsShown();
|
||||
return (
|
||||
<span
|
||||
className={`visual-change-outlines${props.activeIndex !== undefined ? " has-active" : ""}`}
|
||||
aria-hidden="true">
|
||||
{props.changes.map((change, index) => {
|
||||
const rect = outlineRect(change);
|
||||
// A moved area sits where its content is on each side: the Before side (--outline-before: 1) draws it
|
||||
// back by the move, so the outline jumps by the amount on its label when the sides flip.
|
||||
const back = (offset: number, move: number | undefined) => (move ? `calc(${offset}% - var(--outline-before, 0) * ${move}%)` : `${offset}%`);
|
||||
return (
|
||||
<span
|
||||
key={index}
|
||||
className={`visual-change-outline${props.activeIndex === index ? " active" : ""}`}
|
||||
className={`visual-change-outline${change.move ? " moved" : ""}${props.activeIndex === index ? " active" : ""}`}
|
||||
style={{
|
||||
left: `${rect.x}%`,
|
||||
top: `${rect.y}%`,
|
||||
left: back(rect.x, change.move?.x),
|
||||
top: back(rect.y, change.move?.y),
|
||||
width: `${rect.width}%`,
|
||||
height: `${rect.height}%`,
|
||||
}}
|
||||
/>
|
||||
}}>
|
||||
{change.move && measurements ? <span className="visual-change-measure">{formatMove(change)}</span> : null}
|
||||
</span>
|
||||
);
|
||||
})}
|
||||
</span>
|
||||
|
||||
@@ -75,7 +75,7 @@ export function PhoneCompare(props: CompareControllerOptions & {
|
||||
<ScanSearch aria-hidden="true" />
|
||||
</button>
|
||||
<button type="button" className="phone-icon-button" aria-label="What changed" aria-haspopup="dialog"
|
||||
disabled={compare.facts.length === 0 && notes.length === 0} onClick={() => compare.setFactsOpen(true)}>
|
||||
disabled={compare.facts.length === 0 && !compare.layoutShift && notes.length === 0} onClick={() => compare.setFactsOpen(true)}>
|
||||
<List aria-hidden="true" />
|
||||
</button>
|
||||
{props.headerAction}
|
||||
@@ -122,7 +122,8 @@ export function PhoneCompare(props: CompareControllerOptions & {
|
||||
</div>
|
||||
|
||||
<PhoneSheet title="What changed" open={compare.factsOpen} onClose={() => compare.setFactsOpen(false)}>
|
||||
<WhatChangedContent facts={facts} assistive={assistive} accessibilityOnly={screenDiff.accessibilityOnly} notes={notes} />
|
||||
<WhatChangedContent facts={facts} assistive={assistive} accessibilityOnly={screenDiff.accessibilityOnly}
|
||||
layoutShift={compare.layoutShift} measurable={compare.measurable} notes={notes} />
|
||||
</PhoneSheet>
|
||||
</section>
|
||||
);
|
||||
|
||||
@@ -184,6 +184,91 @@ button.screens-tree-row:hover { color: var(--text); background: var(--panel-hove
|
||||
.screens-cell-via { overflow: hidden; color: var(--tertiary); font-size: 11px; text-overflow: ellipsis; white-space: nowrap; }
|
||||
.screens-cell-elsewhere { color: var(--modified); font-size: 11px; font-weight: 600; }
|
||||
|
||||
/* ── Desktop grid ── */
|
||||
/* One evenly spaced grid. Each screen is a card: the screenshot in a grey well and the route under it, with the
|
||||
status as the tree's dot before it, the way file browsers show documents. Nothing is framed in the status colour,
|
||||
so the page reads as a list of screens rather than a canvas of them. */
|
||||
.screens-page:not(.phone) .screens-sections { display: block; padding-top: 0; }
|
||||
.screens-page:not(.phone) .screens-grid { gap: 12px; }
|
||||
/* Wide enough for a 28-character route after the dot, in the footer's 10.5px mono with room to spare: Linux's
|
||||
fonts set it at about 183px. Five cards fit beside the tree at 1440px. */
|
||||
.screens-page:not(.phone) .screens-cell { width: 216px; }
|
||||
.screens-page:not(.phone) .screens-cell .screen-screenshot-card {
|
||||
overflow: hidden;
|
||||
gap: 0;
|
||||
border: 1px solid var(--border-subtle);
|
||||
border-radius: 12px;
|
||||
background: var(--surface);
|
||||
transition: border-color 120ms ease, box-shadow 120ms ease;
|
||||
}
|
||||
.screens-page:not(.phone) .screens-cell .screen-screenshot-card:has(.screen-screenshot-target:hover) { border-color: color-mix(in srgb, var(--accent) 55%, var(--border-subtle)); }
|
||||
.screens-page:not(.phone) .screens-cell .screen-screenshot-card.selected { border-color: var(--accent); box-shadow: 0 0 0 1px var(--accent); }
|
||||
/* The status is laid out against the card, not the screenshot, so it can sit in the footer. */
|
||||
.screens-page:not(.phone) .screens-cell :is(.screen-screenshot-slot, .diff-frame) { position: static; }
|
||||
.screens-page:not(.phone) .screens-cell .screen-screenshot-slot { order: 1; height: 236px; flex: none; padding: 12px 0; background: var(--element); }
|
||||
.screens-page:not(.phone) .screens-cell .screen-screenshot-card.selected .screen-screenshot-slot { background: var(--accent-soft); }
|
||||
.screens-page:not(.phone) .screens-cell .screen-node-image img,
|
||||
.screens-page:not(.phone) .screens-cell .screen-node-image > .image-placeholder,
|
||||
.screens-page:not(.phone) .screens-cell .screen-screenshot-card .diff-frame .screen-node-image img,
|
||||
.screens-page:not(.phone) .screens-cell .screen-screenshot-card .diff-frame .screen-node-image > .image-placeholder {
|
||||
border-color: transparent;
|
||||
border-radius: 8px;
|
||||
box-shadow: 0 1px 3px rgb(0 0 0 / 0.14);
|
||||
}
|
||||
/* The image box hugs the screenshot, so its corners and shadow are the screenshot's and no box shows around it. */
|
||||
/* The screenshot fits the well both ways at its own proportions (styles.css's max-width and max-height), so a
|
||||
landscape capture is framed as itself, not letterboxed inside a portrait-sized box. */
|
||||
.screens-page:not(.phone) .screens-cell .screen-node-image img { width: auto; height: auto; background: transparent; }
|
||||
/* No screenshot: the well has a size here, so the placeholder fits it the way styles.css fits it to a Map slot,
|
||||
at the screenshot's proportions, rather than by the cell's width as a phone's cell does (phone.css). */
|
||||
.screens-page:not(.phone) .screens-cell .screen-node-image:has(> .image-placeholder) { container-type: size; }
|
||||
.screens-page:not(.phone) .screens-cell .screen-node-image > .image-placeholder {
|
||||
width: min(
|
||||
100cqw - 2 * var(--frame-border),
|
||||
(100cqh - 2 * var(--frame-border)) * var(--screenshot-width) / var(--screenshot-height),
|
||||
var(--screenshot-width) * 1px
|
||||
);
|
||||
height: min(
|
||||
100cqh - 2 * var(--frame-border),
|
||||
(100cqw - 2 * var(--frame-border)) * var(--screenshot-height) / var(--screenshot-width),
|
||||
var(--screenshot-height) * 1px
|
||||
);
|
||||
aspect-ratio: auto;
|
||||
}
|
||||
/* A selected card's button is pressed, and a focused pressed button brightens (styles.css). Here that would wash out
|
||||
the screenshot and, as a filter, become the box the status is placed in, lifting it into the well. Keyboard focus
|
||||
rings the card instead. */
|
||||
.screens-page:not(.phone) .screens-cell .screen-screenshot-target:focus-visible { filter: none; outline: 0; }
|
||||
.screens-page:not(.phone) .screens-cell .screen-screenshot-card:has(.screen-screenshot-target:focus-visible) {
|
||||
box-shadow: 0 0 0 3px color-mix(in srgb, var(--accent) 42%, transparent);
|
||||
}
|
||||
.screens-page:not(.phone) .screens-cell .screen-screenshot-card.selected:has(.screen-screenshot-target:focus-visible) {
|
||||
box-shadow: 0 0 0 1px var(--accent), 0 0 0 4px color-mix(in srgb, var(--accent) 32%, transparent);
|
||||
}
|
||||
.screens-page:not(.phone) .screens-cell .screen-node-heading { order: 2; min-height: 0; padding: 10px 6px 10px 8px; }
|
||||
.screens-page:not(.phone) .screens-cell .screen-screenshot-card:has(.diff-label) .screen-node-heading { padding-left: 20px; }
|
||||
.screens-page:not(.phone) .screens-cell .screen-node-title { font-size: 10.5px; line-height: 14px; }
|
||||
.screens-page:not(.phone) .screens-cell .screen-screenshot-card.selected .screen-node-title { color: var(--accent-strong); font-weight: 600; }
|
||||
/* The status is the tree's dot before the route, in the status colour (a square for accessibility only); the word
|
||||
stays in the label's accessible name. */
|
||||
.screens-page:not(.phone) .screens-cell .screen-screenshot-card .diff-label {
|
||||
top: auto;
|
||||
bottom: 13.5px;
|
||||
left: 8px;
|
||||
width: 7px;
|
||||
height: 7px;
|
||||
overflow: hidden;
|
||||
padding: 0;
|
||||
border-radius: 50%;
|
||||
color: transparent;
|
||||
background: var(--diff);
|
||||
box-shadow: none;
|
||||
font-size: 0;
|
||||
transform: none;
|
||||
}
|
||||
.screens-page:not(.phone) .screens-cell .diff-accessibility-only .diff-label { border-radius: 2px; }
|
||||
.screens-page:not(.phone) .screens-cell :is(.screens-cell-via, .screens-cell-elsewhere) { padding-inline: 2px; }
|
||||
|
||||
/* ── Phone ── */
|
||||
/* The space under the top bar is a block, not padding: both engines inset a sticky child's rest
|
||||
position by the scroll container's padding, which pushed the section bar a bar's height too low. */
|
||||
|
||||
@@ -1,13 +1,16 @@
|
||||
import { useEffect, useMemo, useRef, useState, type CSSProperties, type KeyboardEvent, type ReactNode } from "react";
|
||||
import { ChevronRight, ChevronsDownUp, ChevronsUpDown, ListTree } from "lucide-react";
|
||||
import { artifactUrl, isLaunchScreen, type ExploreMap, type MapIndex, type Screen } from "../../utils/model";
|
||||
import { primaryScreenshotForScreen, screenshotSize } from "../../utils/screen-images";
|
||||
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";
|
||||
import { displayPathForScreen, screenLabel } from "../../utils/screen-path";
|
||||
import { screenTree, treeIndex, treeNodeKey, type ScreenTree, type ScreenTreeNode } from "../../utils/screen-tree";
|
||||
import { screenTree, treeIndex, treeNodeKey, treeScreenOrder, type ScreenTree, type ScreenTreeNode } from "../../utils/screen-tree";
|
||||
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 { placeholderScreen } from "../../utils/map-frame";
|
||||
import { ScreenScreenshotCard } from "../canvas/screen-screenshot-card";
|
||||
import { useCanvasVisibleFrame } from "../canvas/visible-frame-provider";
|
||||
import { PhoneSheet } from "../phone/phone-chrome";
|
||||
@@ -75,6 +78,26 @@ function cardId(id: string): string {
|
||||
return `screens-card-${id.replace(/[^A-Za-z0-9_-]/g, "_")}`;
|
||||
}
|
||||
|
||||
/**
|
||||
* The card in the row above or below a screen's, nearest it across: read from where the cards sit, so it follows the
|
||||
* grid however many columns the page has room for. A short last row still takes ↓ from the row above it.
|
||||
*/
|
||||
function cardInNextRow(from: string, ids: readonly string[], down: boolean): string | undefined {
|
||||
const box = (id: string) => document.getElementById(cardId(id))?.getBoundingClientRect();
|
||||
const here = box(from);
|
||||
if (!here) return undefined;
|
||||
const centre = (rect: DOMRect) => rect.left + rect.width / 2;
|
||||
const rows = ids.flatMap(id => {
|
||||
const rect = box(id);
|
||||
return rect && (down ? rect.top >= here.bottom - 1 : rect.bottom <= here.top + 1) ? [{ id, rect }] : [];
|
||||
});
|
||||
if (!rows.length) return undefined;
|
||||
const nearestTop = down ? Math.min(...rows.map(row => row.rect.top)) : Math.max(...rows.map(row => row.rect.top));
|
||||
const row = rows.filter(candidate => Math.abs(candidate.rect.top - nearestTop) < 1);
|
||||
return row.reduce((best, candidate) =>
|
||||
Math.abs(centre(candidate.rect) - centre(here)) < Math.abs(centre(best.rect) - centre(here)) ? candidate : best).id;
|
||||
}
|
||||
|
||||
function sectionAnchor(id: string): string {
|
||||
return `screens-section-${id.replace(/[^A-Za-z0-9_-]/g, "_")}`;
|
||||
}
|
||||
@@ -92,6 +115,8 @@ function ScreenCell(props: {
|
||||
via?: string | undefined;
|
||||
selected: boolean;
|
||||
dimmed: boolean;
|
||||
/** The run's screenshot shape, which a screen without a screenshot is framed in. */
|
||||
typicalSize?: ScreenshotSize | undefined;
|
||||
onSelect: () => void;
|
||||
}) {
|
||||
const artifact = primaryScreenshotForScreen(props.screen, props.index);
|
||||
@@ -108,6 +133,7 @@ function ScreenCell(props: {
|
||||
{...(props.index.plainTitles ? { plainTitle: true } : {})}
|
||||
{...(url ? { screenshot: url } : {})}
|
||||
{...(size ? size : {})}
|
||||
placeholderSize={placeholderScreen(props.typicalSize)}
|
||||
{...(status ? { diff: status } : {})}
|
||||
{...(props.diff?.screens.get(props.screen.id)?.accessibilityOnly ? { accessibilityOnly: true } : {})}
|
||||
selected={props.selected}
|
||||
@@ -168,6 +194,7 @@ function TreeRows(props: {
|
||||
<button type="button" style={style}
|
||||
className={`screens-tree-row${node.tab ? " tab" : ""}${props.visible.has(screen.id) ? "" : " filtered"}`}
|
||||
aria-current={props.selectedScreenId === screen.id ? "true" : undefined}
|
||||
data-screen-id={screen.id}
|
||||
aria-expanded={key ? open : undefined}
|
||||
data-tree-key={key}
|
||||
onClick={() => props.onSelect(screen.id)}>
|
||||
@@ -202,14 +229,18 @@ function Legend(props: { others: Appearance[] }) {
|
||||
}
|
||||
|
||||
/**
|
||||
* Screens as a page that scrolls: a section per route folder (or per tab, when there are no route
|
||||
* files), with the tree of them beside it on desktop and behind a Tree button on a phone.
|
||||
* Screens as a page that scrolls. On desktop, one grid of every screen in the order of the tree beside it; on a
|
||||
* phone, a section per route folder (or per tab, when there are no route files), with the tree behind a Tree button.
|
||||
*/
|
||||
export function ScreensView(props: ScreensViewProps) {
|
||||
const tree: ScreenTree = useMemo(
|
||||
() => screenTree(props.map.screens, props.index, props.routeFiles),
|
||||
[props.index, props.map.screens, props.routeFiles],
|
||||
);
|
||||
const typicalSize = useMemo(
|
||||
() => typicalScreenshotSize(props.map.screens.map(screen => screenshotSize(primaryScreenshotForScreen(screen, props.index)))),
|
||||
[props.index, props.map.screens],
|
||||
);
|
||||
const changedIds = useMemo(
|
||||
() => new Set(props.map.screens
|
||||
.filter(screen => isChanged(props.diff, screen.id) || (props.changedElsewhere?.get(screen.id)?.length ?? 0) > 0)
|
||||
@@ -222,6 +253,9 @@ export function ScreensView(props: ScreensViewProps) {
|
||||
const sections = tree.sections
|
||||
.map(section => ({ ...section, screenIds: section.screenIds.filter(id => shown.has(id)) }))
|
||||
.filter(section => section.screenIds.length > 0);
|
||||
// The desktop grid reads in the tree's order, not the sections' (screen-tree.ts).
|
||||
const treeOrder = useMemo(() => treeScreenOrder(tree), [tree]);
|
||||
const order = props.phone ? sections.flatMap(section => section.screenIds) : treeOrder.filter(id => shown.has(id));
|
||||
const others = [...new Set([...(props.changedElsewhere?.values() ?? [])].flat())];
|
||||
|
||||
// Folding. All keeps the reader's folds and remembers them per report. Changed folds separately, starting
|
||||
@@ -321,12 +355,119 @@ export function ScreensView(props: ScreensViewProps) {
|
||||
requestAnimationFrame(() => document.getElementById(cardId(id))?.scrollIntoView({ block: "center", behavior: "smooth" }));
|
||||
};
|
||||
|
||||
// On desktop the arrow keys move through the cards: ← and → in their order on the page (`order`), as the arrows step
|
||||
// through screens in Compare, and ↑ and ↓ to the card above or below, by where the cards sit, so they follow the grid
|
||||
// at any width. A step picks the screen as the tree does, leaving the Inspector as it is, and focus follows it; with
|
||||
// nothing picked, → and ↓ start at the first card, and a pick that Changed hides steps from where it sits in the tree.
|
||||
// The tree's rows keep their arrow keys, and so do the Inspector's controls. Phones are left as they were.
|
||||
// Held, an arrow keeps stepping as Compare's do (key-hold.ts). Return opens the picked screen in the Inspector, as a
|
||||
// click on its card does; on the card itself the button already does.
|
||||
const orderRef = useRef(order);
|
||||
orderRef.current = order;
|
||||
const treeOrderRef = useRef(treeOrder);
|
||||
treeOrderRef.current = treeOrder;
|
||||
const selectedRef = useRef(selected);
|
||||
selectedRef.current = selected;
|
||||
const pickRef = useRef(props.onPickScreen ?? props.onSelectScreen);
|
||||
pickRef.current = props.onPickScreen ?? props.onSelectScreen;
|
||||
const openRef = useRef(props.onSelectScreen);
|
||||
openRef.current = props.onSelectScreen;
|
||||
useEffect(() => {
|
||||
if (props.phone) return;
|
||||
/** The card an arrow moves to from `from` (the pick, or the last card a hold stepped to). */
|
||||
const next = (code: string, from: string | undefined): string | undefined => {
|
||||
const ids = orderRef.current;
|
||||
const vertical = code === "ArrowUp" || code === "ArrowDown";
|
||||
const forward = code === "ArrowRight" || code === "ArrowDown";
|
||||
if (from && ids.includes(from)) return vertical ? cardInNextRow(from, ids, forward) : ids[ids.indexOf(from) + (forward ? 1 : -1)];
|
||||
if (from && treeOrderRef.current.includes(from)) {
|
||||
// Picked, but hidden by Changed: the nearest shown card past it in the tree's order.
|
||||
const shownIds = new Set(ids);
|
||||
const all = treeOrderRef.current;
|
||||
const at = all.indexOf(from);
|
||||
return (forward ? all.slice(at + 1) : all.slice(0, at).reverse()).find(candidate => shownIds.has(candidate));
|
||||
}
|
||||
return forward ? ids[0] : ids[ids.length - 1];
|
||||
};
|
||||
const go = (id: string) => {
|
||||
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;
|
||||
};
|
||||
const beginHold = (code: string, at: string) => {
|
||||
endHold();
|
||||
let step = 1;
|
||||
const tick = () => {
|
||||
const id = hold && next(code, hold.at);
|
||||
if (!hold || !id) { endHold(); return; }
|
||||
go(id);
|
||||
hold = { code, at: id, timer: setTimeout(tick, holdIntervalMs(step)) };
|
||||
step += 1;
|
||||
};
|
||||
hold = { code, at, timer: setTimeout(tick, HOLD_INITIAL_DELAY_MS) };
|
||||
};
|
||||
const onKeyDown = (event: globalThis.KeyboardEvent) => {
|
||||
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.metaKey || event.ctrlKey || event.altKey || event.shiftKey || event.defaultPrevented || !shortcutsLive(event)) return;
|
||||
const target = event.target instanceof Element ? event.target : null;
|
||||
if (!arrow) {
|
||||
// Return on a button or a link presses it; elsewhere on the page it opens the pick.
|
||||
const selectedId = selectedRef.current;
|
||||
if (target?.closest("button, a, [role=\"button\"]") || !target?.closest("body") || !selectedId || !orderRef.current.includes(selectedId)) return;
|
||||
if (target !== document.body && !target.closest(".screens-page")) return;
|
||||
event.preventDefault();
|
||||
openRef.current(selectedId);
|
||||
return;
|
||||
}
|
||||
// The page, or the bottom toolbar that Screens was just opened from; its buttons have no arrow keys of their own.
|
||||
const onPage = !target || target === document.body || target.closest(".screens-page, .canvas-toolbar") !== null;
|
||||
if (!onPage || target?.closest(".screens-tree-list")) return;
|
||||
const id = next(event.code, selectedRef.current);
|
||||
if (!id) return;
|
||||
event.preventDefault();
|
||||
go(id);
|
||||
beginHold(event.code, id);
|
||||
};
|
||||
const onKeyUp = (event: globalThis.KeyboardEvent) => {
|
||||
if (hold && event.code === hold.code) endHold();
|
||||
};
|
||||
window.addEventListener("keydown", onKeyDown);
|
||||
window.addEventListener("keyup", onKeyUp);
|
||||
window.addEventListener("blur", endHold);
|
||||
return () => {
|
||||
endHold();
|
||||
window.removeEventListener("keydown", onKeyDown);
|
||||
window.removeEventListener("keyup", onKeyUp);
|
||||
window.removeEventListener("blur", endHold);
|
||||
};
|
||||
}, [props.phone]);
|
||||
|
||||
// The Inspector floats over the right edge; the page keeps its content clear of it.
|
||||
const { visibleFrame } = useCanvasVisibleFrame();
|
||||
const style = !props.phone && visibleFrame
|
||||
? ({ "--screens-right-inset": `calc(100% - ${visibleFrame.x + visibleFrame.width}px)` } as CSSProperties)
|
||||
: undefined;
|
||||
|
||||
const cell = (id: string) => {
|
||||
const screen = props.index.screens.get(id);
|
||||
return screen ? (
|
||||
<ScreenCell key={id} screen={screen} index={props.index} diff={props.diff}
|
||||
elsewhere={isChanged(props.diff, id) ? undefined : props.changedElsewhere?.get(id)}
|
||||
via={tree.via.get(id)}
|
||||
typicalSize={typicalSize}
|
||||
selected={props.selectedScreenId === id}
|
||||
dimmed={Boolean(props.focus?.length) && !props.focus!.some((state) => state === focusStatusOf(props.diff?.screens.get(id)))}
|
||||
onSelect={() => props.onSelectScreen(id)} />
|
||||
) : null;
|
||||
};
|
||||
|
||||
const treeRows = (
|
||||
<ul className="screens-tree-list" onKeyDown={onTreeKey}>
|
||||
<TreeRows nodes={tree.tree} depth={0} index={props.index} diff={props.diff} elsewhere={props.changedElsewhere}
|
||||
@@ -378,28 +519,20 @@ export function ScreensView(props: ScreensViewProps) {
|
||||
</aside>
|
||||
)}
|
||||
<div className="screens-sections">
|
||||
{sections.map(section => (
|
||||
{props.phone ? sections.map(section => (
|
||||
<section key={section.id} id={sectionAnchor(section.id)} className="screens-section" aria-label={section.name ?? section.title}>
|
||||
<header className="screens-section-head">
|
||||
<h2>{section.name ?? section.title}</h2>
|
||||
{section.path ? <span className="path">{breakAfterSlashes(section.title)}</span>
|
||||
: section.subtitle ? <span>{section.subtitle}</span> : null}
|
||||
</header>
|
||||
<div className="screens-grid">
|
||||
{section.screenIds.map(id => {
|
||||
const screen = props.index.screens.get(id);
|
||||
return screen ? (
|
||||
<ScreenCell key={id} screen={screen} index={props.index} diff={props.diff}
|
||||
elsewhere={isChanged(props.diff, id) ? undefined : props.changedElsewhere?.get(id)}
|
||||
via={tree.via.get(id)}
|
||||
selected={props.selectedScreenId === id}
|
||||
dimmed={Boolean(props.focus?.length) && !props.focus!.some((state) => state === focusStatusOf(props.diff?.screens.get(id)))}
|
||||
onSelect={() => props.onSelectScreen(id)} />
|
||||
) : null;
|
||||
})}
|
||||
</div>
|
||||
<div className="screens-grid">{section.screenIds.map(cell)}</div>
|
||||
</section>
|
||||
))}
|
||||
)) : (
|
||||
// On desktop the tree beside the page already shows the folders, so every screen sits in one evenly
|
||||
// spaced grid in the tree's order, without headings between them.
|
||||
<div className="screens-grid">{order.map(cell)}</div>
|
||||
)}
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
@@ -18,7 +18,8 @@ import {
|
||||
type ProjectionNode,
|
||||
} from "../../utils/graph-model";
|
||||
import { artifactUrl, isLaunchScreen, type ExploreMap, type MapIndex, type Screen } from "../../utils/model";
|
||||
import { primaryScreenshotForScreen, screenshotSize, type ScreenshotSize } from "../../utils/screen-images";
|
||||
import { primaryScreenshotForScreen, screenshotSize, typicalScreenshotSize, type ScreenshotSize } from "../../utils/screen-images";
|
||||
import { mapFrame, type MapFrame } from "../../utils/map-frame";
|
||||
import type { BuildDiff, DiffStatus } from "../../utils/build-diff";
|
||||
import { CANVAS_MAX_ZOOM } from "../../utils/canvas-zoom";
|
||||
import { usePhoneLayout } from "../../utils/phone-layout";
|
||||
@@ -28,10 +29,6 @@ import { displayPathForScreen } from "../../utils/screen-path";
|
||||
import { shortcutsLive } from "../../utils/shortcuts";
|
||||
import { mapKeyDirection, mapKeyTarget } from "../../utils/map-keyboard";
|
||||
|
||||
// The map is an inspection surface, not a thumbnail cloud. These dimensions preserve the
|
||||
// original phone aspect and leave enough vertical room for a wrapped title.
|
||||
const MAP_SCREEN_WIDTH = 184;
|
||||
const MAP_SCREEN_HEIGHT = 420;
|
||||
const HOVER_CLEAR_DELAY = 180;
|
||||
const MAP_LAYOUT_REVISION = "flat-v1";
|
||||
const MAP_FIT_VIEW_OPTIONS = {
|
||||
@@ -58,6 +55,7 @@ type ScreenNodeData = {
|
||||
missingReason?: string;
|
||||
highlighted: boolean;
|
||||
direction: MapDirection;
|
||||
frame: MapFrame;
|
||||
diff?: DiffStatus;
|
||||
accessibilityOnly?: boolean;
|
||||
projectionDelayMs?: number;
|
||||
@@ -74,6 +72,8 @@ type ProjectedStructure = {
|
||||
groups: ConnectionGroup[];
|
||||
positions: Map<string, Point>;
|
||||
screenshots: Map<string, MapScreenshot | undefined>;
|
||||
/** Every card's size, from the shape of the run's screenshots. */
|
||||
frame: MapFrame;
|
||||
screenNotes: Map<string, string>;
|
||||
hoverPaths: Map<string, { nodeIds: Set<string>; edgeIds: Set<string> }>;
|
||||
primaryEdgeKeys: Set<string>;
|
||||
@@ -98,6 +98,8 @@ function ScreenNodeCard({ data, selected }: NodeProps<ScreenGraphNode>) {
|
||||
selected={selected}
|
||||
highlighted={data.highlighted}
|
||||
style={{
|
||||
"--map-screen-width": `${data.frame.width}px`,
|
||||
"--map-screen-height": `${data.frame.height}px`,
|
||||
"--projection-delay": `${data.projectionDelayMs ?? 0}ms`,
|
||||
"--projection-scale": data.projectionScreenScale ?? 1,
|
||||
...(data.projectionScreenScale !== undefined
|
||||
@@ -107,8 +109,10 @@ function ScreenNodeCard({ data, selected }: NodeProps<ScreenGraphNode>) {
|
||||
ariaLabel={`Open ${data.screen.title}`}
|
||||
ariaPressed={selected}
|
||||
// The slot's own proportions stand in only when the screenshot's size is not recorded.
|
||||
imageWidth={data.screenshotSize?.imageWidth ?? MAP_SCREEN_WIDTH - 2}
|
||||
imageHeight={data.screenshotSize?.imageHeight ?? MAP_SCREEN_HEIGHT - 48}
|
||||
// A screenshot of unrecorded size, or none, is framed like the run's other screenshots.
|
||||
imageWidth={data.screenshotSize?.imageWidth ?? data.frame.screen.width}
|
||||
imageHeight={data.screenshotSize?.imageHeight ?? data.frame.screen.height}
|
||||
placeholderSize={data.frame.screen}
|
||||
loading="lazy"
|
||||
leading={<Handle type="target" position={horizontal ? Position.Left : Position.Top} className="graph-handle" />}
|
||||
trailing={<Handle type="source" position={horizontal ? Position.Right : Position.Bottom} className="graph-handle" />}
|
||||
@@ -128,8 +132,8 @@ function conciseActionLabel(label: string): string | undefined {
|
||||
return /^(continue|next|open)$/i.test(concise) ? undefined : concise;
|
||||
}
|
||||
|
||||
function nodeDimensions(_node: ProjectionNode) {
|
||||
return { width: MAP_SCREEN_WIDTH, height: MAP_SCREEN_HEIGHT };
|
||||
function nodeDimensions(frame: MapFrame) {
|
||||
return { width: frame.width, height: frame.height };
|
||||
}
|
||||
|
||||
function adjacency(groups: readonly ConnectionGroup[]) {
|
||||
@@ -195,7 +199,7 @@ function hoverNeighborhood(nodes: readonly ProjectionNode[], groups: readonly Co
|
||||
* One card per screen, layered by how many transitions it took to reach it from the start screen;
|
||||
* a screen never reached by a recorded transition joins the last layer. Edges are the transitions.
|
||||
*/
|
||||
function flatPositions(projection: GraphProjection): { positions: Map<string, Point>; horizontal: boolean } {
|
||||
function flatPositions(projection: GraphProjection, frame: MapFrame): { positions: Map<string, Point>; horizontal: boolean } {
|
||||
const screenNodes = projection.nodes.filter((node): node is Extract<ProjectionNode, { kind: "screen" }> => node.kind === "screen");
|
||||
const ids = new Set(screenNodes.map((node) => node.id));
|
||||
const outgoing = new Map<string, string[]>();
|
||||
@@ -225,8 +229,8 @@ function flatPositions(projection: GraphProjection): { positions: Map<string, Po
|
||||
}
|
||||
// Lay the deeper axis along the wider screen axis: a long chain of taps reads left to right.
|
||||
const horizontal = layers.size > Math.max(...[...layers.values()].map((members) => members.length));
|
||||
const alongPitch = (horizontal ? MAP_SCREEN_WIDTH : MAP_SCREEN_HEIGHT) + 160;
|
||||
const acrossPitch = (horizontal ? MAP_SCREEN_HEIGHT : MAP_SCREEN_WIDTH) + 56;
|
||||
const alongPitch = (horizontal ? frame.width : frame.height) + 160;
|
||||
const acrossPitch = (horizontal ? frame.height : frame.width) + 56;
|
||||
const positions = new Map<string, Point>();
|
||||
// Order each layer by where its parents sit in the previous one so edges cross as little as possible.
|
||||
const incoming = new Map<string, string[]>();
|
||||
@@ -252,18 +256,21 @@ function flatPositions(projection: GraphProjection): { positions: Map<string, Po
|
||||
}
|
||||
|
||||
function projectedStructure(projection: GraphProjection, index: MapIndex, plainTitles: boolean): ProjectedStructure {
|
||||
const { positions, horizontal } = flatPositions(projection);
|
||||
const screenshots = new Map(projection.nodes.map((node) => {
|
||||
const artifact = primaryScreenshotForScreen(node.screen, index);
|
||||
const url = artifactUrl(artifact);
|
||||
const size = screenshotSize(artifact);
|
||||
return [node.id, url ? { url, ...(size ? { size } : {}) } : undefined] as const;
|
||||
}));
|
||||
const frame = mapFrame(typicalScreenshotSize([...screenshots.values()].map((screenshot) => screenshot?.size)));
|
||||
const { positions, horizontal } = flatPositions(projection, frame);
|
||||
return {
|
||||
screenNotes: index.screenNotes,
|
||||
projectionNodes: projection.nodes,
|
||||
groups: projection.groups,
|
||||
positions,
|
||||
screenshots: new Map(projection.nodes.map((node) => {
|
||||
const artifact = primaryScreenshotForScreen(node.screen, index);
|
||||
const url = artifactUrl(artifact);
|
||||
const size = screenshotSize(artifact);
|
||||
return [node.id, url ? { url, ...(size ? { size } : {}) } : undefined] as const;
|
||||
})),
|
||||
frame,
|
||||
screenshots,
|
||||
hoverPaths: hoverNeighborhood(projection.nodes, projection.groups),
|
||||
primaryEdgeKeys: spanningEdges(projection.nodes, projection.groups),
|
||||
horizontal,
|
||||
@@ -282,7 +289,7 @@ function projectionElements(
|
||||
): { nodes: CanvasGraphNode[]; edges: TransitionGraphEdge[] } {
|
||||
const nodes: CanvasGraphNode[] = structure.projectionNodes.map((projectionNode) => {
|
||||
const point = structure.positions.get(projectionNode.id) ?? { x: 0, y: 0 };
|
||||
const size = nodeDimensions(projectionNode);
|
||||
const size = nodeDimensions(structure.frame);
|
||||
const position = { x: point.x - size.width / 2, y: point.y - size.height / 2 };
|
||||
const screen = projectionNode.screen;
|
||||
const screenshot = structure.screenshots.get(screen.id);
|
||||
@@ -319,6 +326,7 @@ function projectionElements(
|
||||
...(!screenshot && structure.screenNotes.get(screen.id) ? { missingReason: structure.screenNotes.get(screen.id)! } : {}),
|
||||
highlighted,
|
||||
direction: structure.horizontal ? "LR" : "TB",
|
||||
frame: structure.frame,
|
||||
...(status ? { diff: status } : {}),
|
||||
...(diff?.screens.get(screen.id)?.accessibilityOnly ? { accessibilityOnly: true } : {}),
|
||||
projectionMotion,
|
||||
|
||||